Design Discussion: Introduce a Knowledge Decorator for Architecture Documentation

## Feature Proposal

**Design Discussion: Introduce a Knowledge Decorator for Architecture Documentation**

### Target Project:
- `calm` (schema/standards) — core: define the `knowledge` decorator standard, including a `target-type` constraint on `applies-to`
- `calm-cli` — core: validation of the decorator, referenced documents, and round-trip back-links.
- `calm-ai` — optional: retrieval of linked knowledge for grounded reasoning.
- `calm-studio` — optional: authoring/visualising knowledge anchors.

### Description of Feature:
Introduce **architecture knowledge** as a first-class, decorator-anchored concern in CALM: standalone knowledge concepts (business intent, domain rules, operational context) authored as their own documents and linked to CALM elements via a thin `knowledge` decorator. This aligns the Open Knowledge Format (OKF) overlay pattern with CALM, following the first-class-document + linkage-decorator precedent established for behaviour (#2621).

**Background: What is OKF?**

The Open Knowledge Format (OKF) is a vendor-neutral convention for authoring architecture and domain knowledge — business intent, domain rules, operational context, decision rationale — as standalone Markdown documents with YAML frontmatter. OKF documents are designed to be both human-readable and AI-readable, are versioned independently of any architecture model, and are meant to be linkable to specific architecture elements. This proposal is the mechanism for establishing that link to CALM.

**Description of Feature**

Architecture models capture *what* the system is (nodes, relationships, flows) but not the durable *why* — business intent, domain rules, regulatory rationale, operational context. Teams keep this in wikis, ADRs and tribal memory that drift from the model. This proposal lets that knowledge live in versioned, standalone knowledge documents and be **anchored** to specific CALM elements through a lightweight decorator, so the architecture and its rationale stay navigable in both directions without embedding narrative inside the model.

**Why This Issue / The Gap**

CALM has no standard way to associate a first-class knowledge artefact with an architecture element. Practitioners currently either overload `description` fields, invent ad-hoc decorators, or maintain the knowledge entirely outside CALM with no traceable linkage back to nodes/relationships. There is also no reverse lookup from an element to the knowledge that explains it (#2793).

### Current Limitations:
- No standard association between a standalone knowledge artefact and a CALM element.
- Knowledge embedded in `description`/free text is unversioned, unstructured and not queryable.
- No reverse navigation from element → explanatory knowledge (#2793).
- No round-trip: knowledge documents cannot reliably point back at the exact element they describe.

### Proposed Implementation:

**1. First-class OKF knowledge document (primary design).** Knowledge concepts are authored as their own OKF/markdown documents with their own lifecycle and version history. These documents are versioned via their own external repository (e.g. git), **not** via CALM Hub — CALM Hub only ever stores/serves the `knowledge` decorator pointer, which is itself unversioned, consistent with current CALM Hub behaviour (per finos/architecture-as-code#2791). This design requires no CALM Hub storage or versioning capability beyond what exists today. Should CALM Hub later adopt a document-type mechanism per finos/architecture-as-code#2791's resolution, `knowledge` documents could migrate to it; that migration is explicitly out of scope for this issue.

**2. Thin `knowledge` anchor decorator (v1.2-conformant base shape).** The decorator only links; it never contains the narrative. Conforms exactly to the v1.2 base decorator (`unique-id`/`type`/`target[]`/`applies-to[]`/`data`). `applies-to` entries are additionally constrained via an `allOf` extension to `target-type: ["node", "relationship"]`, following the precedent set in finos/architecture-as-code#2345, so validators reject anchors pointed at unsupported element kinds:

```json
{
"unique-id": "knowledge-order-settlement-intent",
"type": "knowledge",
"target": ["./trade-platform.arch.json"],
"applies-to": ["node/settlement-engine", "relationship/settlement-to-ledger"],
"data": {
"document": "./knowledge/settlement-intent.md",
"category": "business-intent",
"summary": "Why settlement is decoupled from ledger posting and the domain rules that govern retries."
}
}
```

**3. Round-trip back-link.** No existing CALM decorator or extension currently defines a `calm:`-scheme URI or any comparable back-link addressing convention. Rather than introduce a bespoke URI scheme — with its own resolution/parsing specification and IANA-collision risk — the OKF document's frontmatter instead carries a plain path-based back-link: a relative or absolute file path to the CALM architecture file plus the element identifier, reusing the same string-matching convention already used by `target`/`applies-to` elsewhere in CALM. This gives reverse lookup (motivated by finos/architecture-as-code#2793) and bidirectional navigation without any new addressing scheme:

```yaml
# settlement-intent.md (frontmatter)
calm-links:
- architecture: ./trade-platform.arch.json
element: node/settlement-engine
```

The frontmatter's sole job is this back-link; category classification is not repeated here (see point 4 below and Validation Strategy).

**4. Open knowledge-category vocabulary.** A recommended-but-open set (e.g. `business-intent`, `domain-rule`, `operational-context`, `compliance-rationale`, `decision-record`), extensible without schema change. `data.category` on the decorator is the single authoritative source for category classification — it is not duplicated in the OKF document frontmatter.

**Backward Compatibility**

Fully additive. New decorator standard; no change to existing core schemas, no migration required. Models without knowledge decorators are unaffected.

**Non-Goal: Association Scalability**

This proposal reuses the existing `target` string-matching mechanism and inherits its known scalability limitations (#2793). As a minimal forward-compatible improvement, `target` could optionally reference a specific architecture version string where available, but this is not required for v1 of this proposal.

**Validation Strategy (via `calm validate`)**

- `applies-to[]` resolve to existing element `unique-id`s and satisfy the `target-type` constraint (`node`/`relationship`); `target[]` resolve to reachable CALM documents.
- Decorator `unique-id` uniqueness within scope.
- Referenced `document` exists and parses.
- Round-trip consistency: the OKF back-link (architecture path + element id) resolves to the anchoring element (see Open Questions for hard-error-vs-warning treatment).
- `category` is decorator-authoritative (`data.category`); it is not duplicated in, or cross-checked against, the OKF document frontmatter, which carries only the `calm-links` back-link.

**Implementation Impact**

- **calm (schema/standards)** — new knowledge decorator standard, including the `target-type` constraint on `applies-to` (per finos/architecture-as-code#2345 precedent).
- **calm-cli** — validation rules above.
- **calm-ai** — resolve and retrieve linked knowledge for grounded responses.
- **calm-studio** — author/visualise anchors.
- **calm-hub** — deferred; expected to require no schema impact (registry/rendering work only), pending the Hub decorator-registry design.

### Alternatives Considered:
- **Embed knowledge in the core schema** — rejected: couples narrative to structure, forces migration, no separate lifecycle.
- **Inline knowledge inside the decorator `data`** — rejected per finos/architecture-as-code#2791: loses versioning, dilutes the decorator concept, misrepresents a deliverable as metadata.
- **Extend ADRs** — rejected: ADRs capture point-in-time decisions, not living domain/operational knowledge, and lack element-level anchoring.
- **External URL-only reference with no decorator** — rejected: no standard anchoring, no reverse lookup, no validation.

### Testing Strategy:
- **Schema** — valid/invalid decorator fixtures against the v1.2 base, including `target-type` constraint cases.
- **Validation** — anchor resolution, `target-type` constraint violations, missing/broken `document`, duplicate ids, round-trip mismatch.
- **Hub** — registration/rendering (deferred; see Implementation Impact and Additional Context for dependency tracking).
- **AI** — retrieval of linked knowledge and correct element attribution.

### Documentation Requirements:
- Decorator standard reference and JSON example, including the `target-type` constraint on `applies-to`.
- OKF authoring guide (frontmatter path-based back-link convention).
- Category vocabulary guidance and extension rules.
- Round-trip navigation walkthrough (documents path resolution, not URI parsing).

### Implementation Checklist:
- [ ] Define knowledge decorator standard conforming to the v1.2 base decorator
- [ ] Define target-type constraint for `applies-to`, consistent with finos/architecture-as-code#2345 precedent
- [ ] Specify `data` fields (`document`, `category`, `summary`) and open category vocabulary
- [ ] Define path-based back-link frontmatter convention (architecture path + element id, no new URI scheme)
- [ ] Add `calm-cli` validation (anchor/target resolution, `target-type` constraint, uniqueness, document existence, round-trip)
- [ ] Author schema + validation test fixtures
- [ ] Coordinate Hub decorator registration/rendering with finos/architecture-as-code#2792 (currently blocked — no decorator-type registry exists)
- [ ] Add `calm-ai` retrieval of linked knowledge
- [ ] Write decorator reference + OKF authoring documentation

### Additional Context:

**Relationship to Existing Work**

- **#2791 (Documents vs Decorators)** — finos/architecture-as-code#2791 raises a broader, still-open design question about how standalone artefacts should relate to decorators across CALM generally; it isn't something this issue attempts to settle. We agree with the core concern it raises: standalone artefacts must not be crammed into decorators (loss of versioning, dilution of the decorator concept, misrepresenting deliverables as metadata). This proposal is best read as one narrow element of that question, scoped to a single artefact category — architecture knowledge — and for that category it deliberately **takes the "document" side**: knowledge lives in its own versioned OKF documents, versioned externally (e.g. git) rather than by CALM Hub; the decorator is *only* an anchor. This issue is intended as a concrete input/example to help inform finos/architecture-as-code#2791's resolution, not a parallel or competing decision. The broader question, for other artefact types, remains open in finos/architecture-as-code#2791.
- **#2621 (first-class behaviour document + behaviour decorator)** — The pattern we mirror: a first-class document plus a thin linkage decorator, so anchors can move without touching the artefact. Knowledge is proposed as a sibling of behaviour, not a parallel mechanism.
- **#2626 (Morphir bridge)** — proposes a `morphir` behaviour-provider decorator that references an external artefact using plain HTTPS URL and FQName fields (`distribution-url`, `fqname`, `test-suite-url`); reverse linkage back to CALM is achieved via Morphir's own native "decoration" mechanism, not any CALM-side URI scheme.
- **#2627 (behaviour-driven tracking)** — Related umbrella; knowledge complements behaviour (rationale vs. executable behaviour).
- **#2792 (Hub Decorator Registry & Views)** — Rendering a knowledge link depends on Hub being able to register/discover new decorator types.
- **#2793 (Decorator Association Scalability)** — Directly motivates the identifier and round-trip design

**Open Questions**

- Closed vs. open **category** vocabulary?
- Back-link addressing convention — relative vs. absolute paths, repo-qualified references, Hub ids (path-based, no new URI scheme)?
- Round-trip back-link mismatch — **hard error or warning**?
- Should `applies-to` entries pair explicitly with a specific `target` entry (as `calm-links` pairs `architecture`+`element`), to remove ambiguity when `target` holds multiple documents?

**Related Issues**

- finos/architecture-as-code#2791 — Design Discussion: Documents vs Decorators
- finos/calm-schema#24 — Schema: first-class behaviour document type and behaviour decorator
- finos/architecture-as-code#2627 — Behaviour-driven architecture for CALM (tracking)
- finos/architecture-as-code#2626 — Experimental: Morphir bridge — executable behaviour via a behaviour-provider decorator
- finos/architecture-as-code#2792 — Design Discussion: CALM-Hub Decorator Registry and Views
- finos/architecture-as-code#2793 — Design Discussion: Decorator Association Scalability Concerns
- finos/architecture-as-code#2345 — Decorator Proposal: Code Location (format exemplar)

Start by reading the related issues #2621, #2791, #2792, and #2793, then inspect the calm schema and calm-cli validation entry points; run the existing calm validate checks and schema/validation fixtures. Done requires an agreed knowledge-decorator design, schema and validation coverage, document and round-trip checks, plus the listed documentation and deferred integration decisions.

Written by the indexing model from the issue text.