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)

[eskenazit]

This will not work after merge of mpc mock.

After the rebase of #236 you will have

"required": [],
"anyOf": [
{ "required": ["name", "description", "call"], ... }, // simple
{ "required": ["name", "description", "steps"], ... }, // orchestrated
{ "required": ["ref"] } // ref (aggregate)
]
which will allow an empty tool since ref is required only from an anyOf branching perspective.

I think should become :

{
"required": ["name", "description", "outputParameters"],
"type": "object",
"description": "Mock mode: serves static responses from const values. No call, steps, or ref needed.",
"properties": {
"outputParameters": {
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/$defs/MockOutputParameter"
}
}
},
"not": {
"anyOf": [
{ "required": ["call"] },
{ "required": ["steps"] },
{ "required": ["ref"] }
]
}
}

But we should close #236 first and rebase since the two re working on the same schema, we will have non trivial conflicts

[jlouvel]

Let's wait for #236 and #239 to merge then :)