Feat/aggregates

[jlouvel]

Related Issue

Closes #191

---

What does this PR do?

Introduces aggregates[] on the Capability object, enabling DDD-inspired domain functions that can be defined once and referenced from multiple adapters (MCP tools, REST operations) via ref.

Schema:

• New definitions: Aggregate, AggregateFunction, Semantics
• ref property on McpTool and ExposedOperation (third anyOf branch alongside simple/orchestrated)
• name and description are optional when using ref (inherited from the function)

Engine:

• AggregateRefResolver merges inherited fields from the referenced function (name, description, call, with, steps, inputParameters, outputParameters) — explicit fields override inherited ones
• Automatic derivation of MCP hints from function semantics (safe → readOnly/destructive, idempotent → idempotent), with explicit hints overriding derived values

Spectral:

• naftiko-aggregate-function-description rule: warns when a function lacks a description
• naftiko-aggregate-semantics-consistency rule (custom JS function): detects contradictions between function semantics and MCP tool hints (e.g. safe=true + destructive=true) or REST methods (e.g. safe=true + DELETE)

Documentation:

• Specification-Schema: §3.4.5 (Aggregate Object), §3.5.5 (McpTool ref mode), §3.9 (ExposedOperation ref mode)
• FAQ: new "Aggregates & Reuse (DDD-inspired)" section
• design-guidelines, AGENTS.md, SKILL.md, wrap-api-as-mcp: aggregate design rules and constraints

Built on top of #239 (MCP tool hints).

---

Tests

• 25 unit tests (AggregateRefResolverTest): function map indexing, ref lookup, MCP tool merge (name, description, call, inputParams), REST operation merge, deriveHints (6 scenarios), mergeHints (3 scenarios), resolve pipeline
• 11 integration tests (AggregateIntegrationTest): end-to-end YAML → engine → output for ref resolution, parameter inheritance, hints derivation, overrides, backward compatibility, unknown ref fail-fast
• 3 Spectral tests (NaftikoSpectralRulesetTest): semantics-hints contradiction detection, REST method contradiction, consistent-document no-warn
• 3 test fixtures: aggregate-basic.yaml, aggregate-hints-override.yaml, aggregate-invalid-ref.yaml, plus 2 Spectral fixtures

---

Checklist

• CI is green (build, tests, schema validation, security scans)
• Rebased on latest main
• Small and focused — one concern per PR
• Commit messages follow Conventional Commits

---

Agent Context (optional)

agent_name: GitHub Copilot
llm: Claude Opus 4.6
tool: VS Code Chat
confidence: high
source_event: "Issue #191 — Factorize capability core with aggregates[]"
discovery_method: code_review
review_focus: >
  AggregateRefResolver.java (merge logic + hints derivation),
  naftiko-schema.json (McpTool/ExposedOperation anyOf branches),
  aggregate-semantics-consistency.js (Spectral custom function)

[jlouvel]

@eskenazit I've rebased from #287 , that might work well

[jlouvel]

@eskenazit I've enhanced this PR to support mocks at the aggregates level. Downgraded JUnit to version 5 due to VS Code detection issue and minor JaCoCo upgrade.

[jlouvel]

@eskenazit As discussed, I have reworked the implementation to have an engine implementation of aggregates

[eskenazit]

Seems way more solid with delegated instances than with copies ! =)