Behaviour-driven architecture for CALM (tracking)

## Behaviour-driven architecture for CALM

This tracking issue holds the narrative, dependency order, and progress for a set of related changes that together let behaviour specifications drive architectural design — from BA-authored scenarios with zero architecture, through a derived draft architecture, to promoted, conformance-tested design.

### The user journey

1. **Capture** — a business analyst authors a standalone behaviour document: structured Given/When/Then scenarios with plain-language actors. No nodes, no flows, no identifiers. Publishable and reviewable as-is.
2. **Derive** — scenarios imply a cast and a choreography. `calm derive` extracts them and generates a business-level draft architecture: actor/system nodes, `interacts` relationships, one flow per scenario, and the glue decorator anchoring scenario steps to flow transitions — every construct stamped `status: draft`. The first draft of the logical architecture is computed from the behaviour specs.
3. **Design** — an architect refines on the canvas or in JSON: decomposes draft systems via `composed-of`, firms up types, draws real relationships. Draft markers come off element by element; the remainder is the promotion burn-down list. Scenarios never break — they anchor to flows and actor nodes whose ids persist through decomposition.
4. **Promote** — burn-down empty → the promotion guard passes → CALM Hub accepts promotion out of draft. Controls can gate the same moment on behaviour coverage.
5. **Verify** — specs anchored at interface/node level run in CI as conformance tests; evidence pointers come back; drift between architecture and implementation is detected continuously.

### The anchoring ladder

| Rung | Anchor | What it buys |
|---|---|---|
| 0 | none (standalone behaviour document) | captured intent, reviewable requirements |
| 1 | flow / transitions | traceability to a business process |
| 2 | interface / node | conformance testing, controls evidence |

Every rung is optional; flows are the primary anchor. Scope boundary across all of this: **CALM tooling never executes tests** — it stores intent and evidence pointers; CI executes.

### Work items and sequence

```
Phase 1 finos/calm-schema#19 (flow-first: transition unique-id, business-flow pattern) ∥ [#2620] lifecycle status + promotion guard
Phase 2 [#2621] behaviour document type + behaviour decorator + finos/architecture-as-code#2611 (calm-ai skill, validate --behaviour, evidence contract)
Phase 3 [#2622] calm derive ← integration test for every Phase 1–2 schema decision, while still draft
Phase 4 [#2623] Hub (behaviours resource + gate) ∥ [#2624] Studio ∥ [#2625] calm-widgets
Phase 5 [#2626] Morphir bridge (experimental)
```

All schema work targets draft `2026-03`; downstream items develop against the drafts and do not wait for a release.

- [ ] finos/calm-schema#19 — Support flow-first modelling before logical architecture (transition `unique-id` + nodes-as-actors idiom + pattern)
- [ ] finos/calm-schema#23 — Schema: lifecycle `status` (draft) with promotion guard
- [ ] finos/calm-schema#24 — Schema: behaviour document type and behaviour decorator
- [ ] finos/architecture-as-code#2611 — Attach BDD specs to CALM elements (capability: calm-ai skill, CLI validation, evidence contract)
- [ ] finos/architecture-as-code#2622 — CLI: `calm derive`
- [ ] finos/architecture-as-code#2623 — Hub: behaviours resource and draft promotion gate
- [ ] finos/architecture-as-code#2624 — Studio: flow builder, behaviour panel, draft rendering
- [ ] finos/architecture-as-code#2625 — calm-widgets: sequence rendering, behaviour + draft visuals
- [ ] finos/architecture-as-code#2626 — Experimental: Morphir bridge

### Why this shape

- **Actors are nodes** (#1875): `node-type: actor` and the actor-shaped `interacts` relationship already exist; flow-first needs an idiom and one additive schema change, not a parallel vocabulary.
- **Lifecycle status is core schema** (#2620): design status is load-bearing for validation, rendering, and governance — it is owned by the architecture, not supplementary to it.
- **Behaviour documents are first-class** (#2621): black-box requirements artefacts need somewhere to live before any architecture exists, with linkage kept in decorators so specs survive allocation changes.
- **Derive keeps AI at the edge** (#2622): structured step participants are filled in at authoring time; the CLI transformation is deterministic, testable, and repeatable.
- **Loose coupling for executable behaviour** (#2626): provider-agnostic decorator extensions; Morphir is the first provider, referenced by URL and FQName with no code dependency.