aw-spec-cli 0.1.7 → 0.1.9

package/assets/.appweaver/templates/design-template.md

@@ -0,0 +1,383 @@
+# Design: [AGGREGATE]
+
+**Aggregate (feature)**: `[Aggregate]`  <!-- the feature = the aggregate, e.g. Order -->
+
+**Design home**: `specs/[Aggregate]/design.md`
+
+**Source spec**: `specs/[Aggregate]/spec.md`
+
+**Version**: v1.0   <!-- moves in lockstep with the spec; every applied change request bumps this — see Change History -->
+
+**Status**: Draft
+
+<!--
+  WHAT THIS DOCUMENT IS
+  =====================
+  The single, living High-Level Design (HLD) for ONE aggregate. It is the
+  MEDIATOR between spec.md (WHAT/WHY, tech-agnostic) and the generated code
+  (HOW, tech-specific). It is NOT code: it carries structure, contracts,
+  behaviour, and decisions — enough for ANY capable LLM to generate correct,
+  spec-satisfying code on ANY target stack, but no complete method bodies.
+
+    spec.md  ──▶  design.md  ──▶  code (+ tests)
+    behaviour     structure &       generated by `implement`
+    (FR/BR/US/SC) decisions (HLD)    (stack-bound at generation time)
+
+  ANCHORING RULES
+  - Every design element traces UP to a spec id (FR-/BR-/CN-/DC-/IC-/US-/SC-) and
+    the whole spec is covered DOWN here (see §6 Traceability). No design element
+    without a spec reason; no spec requirement without a design home.
+  - THE SPEC IS THE ONLY DOMAIN INPUT. Design reads the spec + the technical/
+    architecture standards — NOT the domain rule files. The domain reached this doc
+    only as spec ids: business invariants (BR-), domain-derived constraints (CN- —
+    retention/immutability/audit/limits), data classification (DC-), and interop
+    obligations (IC-). Realise each of those; invent no domain rule the spec omits
+    (if one seems missing, record it as an Assumption in §7, never smuggle it in).
+  - Feature = aggregate. Commands (CreateOrder, UpdateOrder…) are USER STORIES,
+    not features. One aggregate = one design.md = one owning design for its code
+    files. A later requirement is a delta on THIS doc, never a new one.
+
+  WHAT LIVES ELSEWHERE (do NOT repeat it here — it is identical for every feature)
+  - The clean-architecture layering + dependency rule (API → Application → Domain
+    ← Infrastructure) is a STANDING project rule in the constitution / architecture
+    standards. This doc just uses the layers as sections; it does not restate the rule.
+  - HOW to turn this design into code (folder mapping, file-per-element, test
+    pairing, stack binding) is a SOLUTION-WIDE, technology-specific rule applied in
+    the `implement` phase — NOT per feature. This doc stays technology-agnostic.
+  - Physical persistence (PKs/FKs, columns, indexes, JSON shapes, migration SQL)
+    belongs to a technical-data-model. This doc states WHAT is stored and WHICH
+    port persists it, not the schema.
+
+  TECHNOLOGY-AGNOSTIC (mandatory)
+  - Express behaviour as SIGNATURES + pre/post/invariant/raises pseudocode and
+    contracts as field shapes — NEVER language code. Use conceptual types
+    (string, int, decimal, enum, list<T>, set<T>, id<T>, money, date). The target
+    language/framework is bound only at `implement` time from the constitution's
+    technology base + the active stack profile. The SAME design must be
+    generatable on a different stack without edits.
+
+  HOW TO AUTHOR
+  - Fill every [PLACEHOLDER]. Keep the section order. Omit a LAYER subsection only
+    when the aggregate genuinely has nothing there (state why); never write "N/A".
+  - Two deferral ledgers are first-class and MANDATORY sections: §7 Assumptions
+    (things to confirm later) and §8 Workarounds (structural debt to clear later).
+    An empty ledger reads "None (as of vX.Y)", never a deletion.
+  - Delete these authoring comments as you fill each section.
+-->
+
+## 0. Design Overview
+
+<!--
+  One paragraph: the architectural shape of this aggregate and the 3–5 decisions
+  that matter most (why this boundary, the lifecycle model, the hardest trade-off).
+  This is the orientation a reviewer or an LLM reads first. The standing layering /
+  dependency rule is NOT restated here — it is the project architecture standard.
+-->
+
+[The architectural essence of this aggregate in 3–6 sentences: its purpose, its
+lifecycle spine, the key structural choices specific to it, and the single biggest
+trade-off. Layering follows the project architecture standard (constitution).]
+
+### Ubiquitous Language (design delta)
+
+<!--
+  The terms this design introduces or sharpens beyond the spec's language. Keep it
+  short — do not restate the whole spec glossary; add only design-level terms
+  (a port name, a state, a domain-service concept). Terms here are used IDENTICALLY
+  in the generated code (type names, method names).
+-->
+
+| Term | Meaning in this design |
+|---|---|
+| [Port / concept name] | [precise definition — this becomes a code identifier] |
+
+## 1. Domain Layer
+
+<!--
+  FOLLOW spec.md EXACTLY. This is not a fresh model — it is the DDD elaboration of
+  what the spec already fixes:
+    • Entities & value objects  = the spec's "Key Entities" (SAME names).
+    • Invariants                = the spec's "Business Rules" (BR-nnn) — cite each.
+    • Aggregate boundary        = the spec's "Scope & Assumptions → Aggregate Boundary"
+                                  (owns vs references-by-id vs out-of-scope).
+    • Lifecycle / states        = the states the spec describes.
+    • Domain-derived constraints = the spec's "Constraints & NFRs" (CN-nnn) that are
+                                  structural here — e.g. immutability, append-only audit,
+                                  no-hard-delete → realised as VO immutability, a domain
+                                  event, or an aggregate invariant; cite the CN-. (Retention/
+                                  performance-as-a-limit land in §4 Infra / §5 Cross-Cutting.)
+  You MAY add design-level structure — domain events, state machines, behaviour
+  signatures — but ONLY to REALISE spec behaviour. Do NOT invent an entity, value
+  object, or rule the spec does not state, and do NOT contradict it. If a genuinely
+  new concept is unavoidable, record it as an Assumption (§7, DA-n) and flag it —
+  never smuggle it in. Pure business model: no framework, no persistence, no I/O.
+  Model this section on a rich DDD reference (entities, VOs, events, state machines,
+  invariants, behaviours). Repeat the blocks as the aggregate needs.
+-->
+
+### 1.1 Aggregate structure *(from the spec's Aggregate Boundary — verbatim)*
+
+- **Aggregate root**: `[Root]` — [what it guards; the transaction boundary]
+- **Entities (owned)**: `[Entity]` — [role]; …
+- **Value objects (owned)**: `[VO]` — [role]; …
+- **References (by id, not owned)**: `[OtherAggregate]Id` → [why referenced] *(ID-only; no navigable link)*
+
+### 1.2 Domain events
+
+<!-- Meaningful state transitions — the audit/notification/coordination mechanism. -->
+
+| Event | Raised by | Trigger | Key payload | Serves |
+|---|---|---|---|---|
+| `[EntityStateChanged]` | `[Root/Entity]` | [what causes it] | `[id, key fields]` | FR-00X · US-Y |
+
+### 1.3 Entities
+
+<!--
+  Per entity: attributes (conceptual types), lifecycle state machine if it has one,
+  behaviours as SIGNATURE + pre/post/invariant/raises pseudocode (the most LLM-guidable,
+  stack-neutral form), and the invariants it enforces (each = a spec BR-nnn).
+-->
+
+#### `[Entity]` [(Aggregate Root)]
+
+**Attributes**
+
+| Attribute | Type (conceptual) | Notes |
+|---|---|---|
+| `[Id]` | `id<[Entity]>` | identity |
+| `[field]` | `[string \| int \| enum{A\|B} \| VO \| list<[Child]>]` | [meaning, constraints] |
+
+**State machine** *(only if the entity has a lifecycle described in the spec — else omit)*
+
+```
+[State] ──[Behaviour()]──▶ [State] ──[Behaviour()]──▶ [State]
+```
+<!-- A mermaid stateDiagram-v2 is welcome for non-trivial lifecycles. -->
+
+**Behaviours** *(technology-agnostic — signatures + contract, not code)*
+
+```
+[Entity].[Behaviour]([params])
+  Pre-condition:  [required state / inputs]
+  Invariant:      [what must hold — maps to a spec BR-nnn]
+  Post-condition: [resulting state / outputs]
+  Raises:         [DomainEvent]
+  Serves:         FR-00X · US-Y · BR-00Z
+```
+
+**Invariants** *(always-true; each maps to a spec BR-nnn — do not add rules absent from the spec)*
+
+- [Invariant statement] — **BR-00X**
+
+### 1.4 Value objects
+
+| Value object | Attributes | Equality | Validation / behaviour | Serves |
+|---|---|---|---|---|
+| `[VO]` | `[fields]` | [by value / by which fields] | [rules; `[method]() → …`] | BR-00X |
+
+### 1.5 Domain services *(cross-entity/aggregate logic that fits no single entity — omit if none)*
+
+```
+[Service].[Operation]([params]) → [result]
+  Purpose:  [why this can't live on one entity]
+  Steps:    1. … 2. … 3. …
+  Touches:  [aggregates/ports coordinated]
+  Serves:   FR-00X · US-Y
+```
+
+## 2. Application Layer
+
+<!--
+  Use-cases: one command/query per user-story action, its handler's orchestration,
+  the ports it depends on, application-level rules (authorization, input validation,
+  transaction + event publication), and the request/response DTO shapes. Consumes
+  Domain types and the PORTS the Domain/Application defines; NEVER touches
+  persistence directly. Stack-neutral (no framework/mediator specifics).
+-->
+
+### 2.1 Ports (interfaces the Application/Domain require)
+
+<!-- The seams Infrastructure implements. Name them; give the contract; keep abstract. -->
+
+| Port | Contract (operations) | Implemented in |
+|---|---|---|
+| `I[Aggregate]Repository` | `get(id) → [Root]?` · `add([Root])` · `[query]` | §4 Infra |
+| `I[External]` | `[operation]([in]) → [out]` | §4 Infra |
+
+### 2.2 Use-cases (commands / queries)
+
+<!-- One block per use-case = one user-story action. This is the LLM's unit of work. -->
+
+#### `[Command/Query]` — Serves US-Y · FR-00X
+
+- **Type**: command (writes) | query (reads)
+- **Request (DTO)**: `{ [field]: [type], … }`
+- **Response (DTO)**: `{ [field]: [type], … }`
+- **Authorization**: [role/policy required — maps to a spec FR]
+- **Validation (application-level)**: [input-shape / cross-field checks before the domain]
+- **Handler orchestration**:
+  ```
+  [Command]Handler.handle(request)
+    1. [authorize / validate input]
+    2. [load aggregate via I[Aggregate]Repository]
+    3. [invoke domain behaviour — the real rules live in §1]
+    4. [persist via port]  (single transaction boundary)
+    5. [publish domain events]
+    6. return [Response]
+    On failure: [which error → which API status in §3]
+  ```
+- **Emits**: `[DomainEvent]` (from §1.2)
+
+## 3. API Layer
+
+<!--
+  The contract other systems couple to. Describe it at PROTOCOL level (REST assumed
+  per the constitution — adapt for gRPC/GraphQL/CLI if the stack differs), NOT as
+  controller code. Pin route, verb, auth, request/response shape, status codes, and
+  the error contract. Delegates to an Application use-case; no business logic here.
+-->
+
+### `[VERB] [/route]` — [purpose] · Serves US-Y · FR-00X
+
+- **Auth**: [required role/scope]
+- **Request**: `[path/query params]` + body `{ [field]: [type], … }`
+- **Success**: `2xx` → `{ [response shape] }`
+- **Errors** *(the error contract)*:
+
+  | Status | When | Body shape |
+  |---|---|---|
+  | 400 | [validation failure] | `{ errors: [{ field, message }] }` |
+  | 403 | [unauthorized] | `{ error }` |
+  | 409 | [conflict / duplicate — maps to a BR] | `{ error }` |
+
+- **Maps to**: `[Command/Query]` (§2.2)
+
+## 4. Infrastructure Layer
+
+<!--
+  The outer edge: which ports (from §2.1) are implemented here, WHAT each persists
+  or integrates (conceptually), and where a schema change is needed. Do NOT specify
+  physical schema (columns/keys/indexes) — that is the technical-data-model's job;
+  reference it. Infrastructure is generated/compiled LAST (it depends on inward ports).
+-->
+
+### 4.1 Persistence
+
+| Port implemented | Adapter (intent) | Persists (conceptually) | Schema change? |
+|---|---|---|---|
+| `I[Aggregate]Repository` | `[Aggregate]Repository` | `[Root]` + owned `[Entity]`/`[VO]` | new / altered / none |
+
+- **Physical schema**: see `technical-data-model` (out of scope here).
+- **Concurrency / transaction**: [optimistic? boundary = aggregate?]
+
+### 4.2 External integrations *(realises the spec's Integration Contracts — omit only if the spec has none)*
+
+<!--
+  One row per spec Integration Contract (IC-nnn) plus any identity/messaging edge.
+  This is where an IC- obligation becomes an adapter/port — the spec named WHICH
+  standard/resources must be met; here you name the port that meets it. Cite the IC-.
+-->
+
+| Port implemented | External system | Operation | Failure mode | Serves |
+|---|---|---|---|---|
+| `I[External]` | [terminology / identity / messaging] | [what it calls] | [reject / degrade / retry] | IC-00X |
+
+### 4.3 Wiring & migrations
+
+- **Composition**: bind `[Port] → [Adapter]` for this aggregate.
+- **Migrations needed**: [yes → what changes conceptually / no]. The Run phase applies them.
+
+## 5. Cross-Cutting Concerns
+
+<!--
+  Where the spec's constraints land structurally: security (authz/PII), data
+  protection & exposure, observability (events/logging/audit), performance/scale,
+  retention, idempotency, eventing/outbox. Design-level only; omit rows that don't
+  apply. For a SPEC-derived concern the "Serves" column MUST cite a SPEC id — the
+  domain-derived constraints arrive as CN-/DC- (design does not read the domain rule
+  files or restate the constitution here); every CN-/DC- in the spec needs a home in
+  this table or §1/§4. A CONSTITUTION-MANDATED cross-cutting concern with NO per-feature
+  spec id is legitimate but is NOT spec-derived: log it as a §7 DA-n citing the
+  mandating principle and set this row's "Serves" to that DA-n (e.g. `DA-<n> · Const.
+  §<n>`). Never fabricate a fake CN- for it, and never leave it uncited — the analyze
+  gate reads an uncited non-spec element as over-reach.
+-->
+
+| Concern | Design decision | Serves |
+|---|---|---|
+| Security / authorization | [where enforced — §2 handler / §3 auth] | FR-00X · CN-00X |
+| Data protection & exposure | [classification handling; what MUST NOT surface in API/logs/traces] | DC-00X |
+| Audit & immutability | [audit emission point; append-only/versioning approach] | CN-00X |
+| Observability | [events emitted, what is logged/audited] | SC-00X |
+| Performance / scale | [target + structural choice] | SC-00X · CN-00X |
+| Retention | [retention window + where enforced; no-hard-delete/logical-delete] | CN-00X |
+| Idempotency / concurrency | [approach; if mandated by the constitution rather than a spec rule, cite its §7 DA-n, not a spec id] | BR-00X / DA-n |
+
+## 6. Traceability (the spine)
+
+<!--
+  The two-way guarantee: every FR/BR/CN/DC/IC/US/SC has a design home, and every
+  design element has a spec reason. This is what makes impact analysis exact and lets
+  the analyze gate verify coverage. Keep it complete — EVERY CN-/DC-/IC- in the spec
+  MUST appear as a row here (that is how the analyze gate proves no lifted constraint
+  was dropped). The Domain rows MUST match the spec's Key Entities and Business Rules
+  exactly.
+-->
+
+| Spec id | Type | Design element(s) | Layer |
+|---|---|---|---|
+| FR-001 | requirement | `[Root].[Behaviour]`, `[Command]`, `[VERB /route]` | Domain·App·API |
+| BR-001 | invariant | `[Root]` invariant / `[VO]` validation | Domain |
+| CN-001 | constraint | [where realised — §1 invariant / §4 persistence / §5 cross-cutting] | [layer] |
+| DC-001 | classification | [exposure enforcement — §2 projection / §5 data-protection] | App·Infra |
+| IC-001 | contract | [adapter/port realising it — §4.2] | Infra |
+| US-1 | story | [end-to-end elements realising it] | all |
+| SC-001 | success | [where it is met + how verified] | [layer] |
+
+## 7. Assumptions (to clarify later)
+
+<!--
+  MANDATORY LEDGER. Every reasonable default or open interpretation the design
+  commits to so it can proceed WITHOUT blocking — INCLUDING (a) any domain concept
+  not explicitly in the spec, and (b) any CROSS-CUTTING element the technical
+  constitution MANDATES that has no per-feature spec id. For (b) state the mandating
+  principle as the basis ("per Const. §<n>") — this is what lets the analyze gate accept
+  a constitution-required element that is absent from the spec (rule 3 admits a logged
+  §7 DA-n; it cannot see the constitution). Each tracked with an id, the risk if wrong,
+  and who resolves it. Design-level (distinct from the spec's behavioural Assumptions).
+  Empty → "None (as of vX.Y)".
+-->
+
+| id | Assumption | Why deferred | Impact if wrong | Owner / resolve-by |
+|---|---|---|---|---|
+| DA-1 | [what we assumed] | [why we didn't clarify now] | [blast radius] | [role / phase] |
+| DA-2 | [a cross-cutting element the constitution mandates but the spec omits] | Mandated by governance, not a per-feature FR — basis: per Const. §<n> | [blast radius] | — / standing |
+
+## 8. Architectural Workarounds & Deferred Decisions (to clear later)
+
+<!--
+  MANDATORY LEDGER. Structural debt KNOWINGLY taken — a shortcut, a temporary
+  coupling, a deferred split — with the proper end-state and the trigger that should
+  force the cleanup. Keeps the HLD honest about where it bends.
+  Empty → "None (as of vX.Y)".
+-->
+
+| id | Workaround taken | Proper end-state | Trigger to revisit | Serves / caused by |
+|---|---|---|---|---|
+| WA-1 | [the shortcut/coupling] | [the clean design] | [scale/CR/date that forces it] | [FR / constraint] |
+
+## 9. Change History
+
+<!--
+  The living-truth ledger, in lockstep with spec.md. Every applied change request
+  appends a row here, carrying the version it ships as. finalize-delta writes the row
+  when it merges the delta; close-delta then archives the CR, bumps the minor version
+  in active_version.json and stamps that same number into this document's **Version**
+  header — one mechanism, one stage, so header, row and active_version.json never
+  disagree. A change to this aggregate is a DELTA on THIS document (delta-design:
+  ADDED / MODIFIED / REMOVED sections), never a new design doc. Newest last.
+-->
+
+| Version | Date | Change | User stories | CR |
+|---------|------|--------|--------------|-----|
+| v1.0 | [DATE] | Initial design | US-1 | — |

package/assets/.appweaver/templates/okf-concept-template.md

@@ -0,0 +1,114 @@
+---
+type: aggregate
+title: [Aggregate]
+description: [one line — what this aggregate is and the invariant/boundary it guards]
+origin: greenfield
+source_files:
+ui_source_files:
+---
+
+<!--
+  OKF CONCEPT  —  one aggregate's node in the shared knowledge bundle.
+  Canonical home: knowledge/<slug>/<slug>.md  (dir also holds an index.md; the bundle
+  root holds index.md with okf_version + an optional log.md change journal).
+
+  This single bundle is the OKF knowledge tier for BOTH pipelines:
+    • greenfield — `implement` authors this concept (frontmatter + Overview + Depends-On)
+      as it generates the aggregate's code;
+    • brownfield — `inventory` seeds it and `adopt` enriches it.
+
+  WHO WRITES WHAT (do not cross these lanes):
+    • Frontmatter, Overview, Depends-On   → THIS aggregate's implement/adopt.
+    • Cross-References                     → the OTHER aggregates that USE this one; each
+                                             writes its own row (never hand-edit them here).
+  One addition inside the first lane: `analyze-slice` MERGES (never replaces) the files its
+  fix loops touched into `source_files`, because it is the last stage that changes the
+  slice's files — a constraint test it had to add did not exist when implement wrote this
+  concept. It touches nothing else; edges and Overview stay with implement/adopt.
+
+  Keep the file frontmatter-valid: `type` (non-empty) + `title` are what validate_okf
+  (E2) and the concept resolver (aw-inventory.py concept) key on. `source_files` MUST
+  list only paths this aggregate OWNS (they drive the shared-code overlap signal and
+  the source-map fidelity check).
+
+  `source_files` is a FLAT list — every consumer keys on that shape — but it is written
+  GROUPED with YAML comment headers (which all parsers skip) BY THE CODE'S OWN FOLDERS,
+  so the listing mirrors the real architecture instead of a fixed taxonomy. Each header
+  is the path segment that VARIES across the files after their shared parent directory —
+  the layer folder of a vertical slice, OR the tier project of an n-tier / layered app:
+
+      source_files:                       # vertical-slice layout
+        # Domain
+        - src/<Project>/<Slice>/Domain/<Root>.cs
+        # Features
+        - src/<Project>/<Slice>/Features/<UseCase>/<UseCase>Command.cs
+        # Persistence
+        - src/<Project>/<Slice>/Persistence/<Root>Configuration.cs
+        # tests
+        - tests/<Project>/<Slice>/<Root>Tests.cs
+
+      source_files:                       # n-tier / layered layout
+        # Acme.DataAccess
+        - src/Acme.DataAccess/Repositories/<Root>Repository.cs
+        # Acme.BusinessLogic
+        - src/Acme.BusinessLogic/Services/<Root>Service.cs
+        # tests
+        - test/Acme.Tests/<Root>Tests.cs
+
+  The grouping is DERIVED from the paths by _group_source_files (aw-xref.py) and
+  re-derived on every write (tests → a `tests` bucket; repo-root files → `(root)`), so
+  never hand-maintain the comment headers.
+
+  `ui_source_files` is the SAME shape for the slice's FRONTEND surface — the components,
+  routes, stores and stylesheets that serve this aggregate — and it is a separate key
+  rather than more entries in `source_files` for two reasons. A separable frontend
+  shares no directory prefix with the service tree, so folding it in would collapse the
+  concept resolver's `module_dir` to the repo root; and the two lanes are reversed by
+  different steps reading different code, which is the same separation scope_to_lanes
+  keeps in the scan substrate. Leave it EMPTY on a backend-only slice — never delete the
+  key. UI files that serve no single aggregate (the app shell, layout, design system)
+  belong in the bundle's `architecture/frontend.md`, not forced into a slice.
+-->
+
+# [Aggregate]
+
+## Overview
+
+<!--
+  2–4 sentences: the aggregate root, what it guards, its transaction boundary.
+  Greenfield: distilled from design.md §1 (Domain Model). Brownfield: from the
+  reverse-engineered spec/design. Prose only — the edges live in the two tables below.
+-->
+
+[overview of the [Aggregate] aggregate]
+
+## Depends-On
+
+<!--
+  FORWARD edges — the sibling aggregates THIS one references. Derived DETERMINISTICALLY
+  from design.md §1 — the model section, "References (by id, not owned)" — plus its
+  External integrations table (Integration Contracts), kept
+  to targets that are real project aggregates (a specs/<Target>/ or an existing concept).
+  This is the PRUNE INDEX: reconcile-on-write reads it to find where this slice wrote, so
+  a dropped dependency self-heals out of the used aggregate's Cross-References.
+  Regenerated every implement/adopt — DO NOT hand-edit.
+-->
+
+| Target | Via | Kind |
+| --- | --- | --- |
+<!-- e.g.  | Organization | ManufacturerId | entity-ref | -->
+
+## Cross-References
+
+<!--
+  REVERSE edges — the sibling aggregates that USE this one; i.e. THIS aggregate's
+  blast radius. Each row is written by the USING slice's implement/adopt
+  (reconcile-on-write, keyed by the "Using slice" column, so a using slice always
+  owns exactly its current rows). REVIEW THIS AT CR TIME: when this aggregate changes,
+  every Using slice listed here is downstream — finalize-delta runs their characterization
+  tests before the change can close. Rows are machine-maintained — DO NOT hand-add them.
+-->
+
+| Using slice | Uses (via) | Kind | Origin | Recorded |
+| --- | --- | --- | --- | --- |
+<!-- e.g.  | Prescription | MedicinalProductId | entity-ref | greenfield | 2026-07-21 | -->

package/assets/.appweaver/templates/parity-manifest-template.json

@@ -0,0 +1,49 @@
+{
+  "_comment": "Parity manifest — the cutover-gate corpus for a brownfield slice. `cases` are authored by /appweaver parity from the spec + source-map; the two `sides` invocation targets are YOURS to supply (where the legacy + new systems run). Parity runs every case against BOTH sides and diffs observable output; the seam cuts over only when parity holds. See Brownfield-Pipeline.md.",
+  "aggregate": "AGGREGATE",
+  "baseline_commit": "REPLACE_WITH_INVENTORY_HEAD",
+  "sides": {
+    "legacy": {
+      "_comment": "The running LEGACY system (the oracle). kind: http → set base_url. kind: shell → set command (it receives a case's request JSON on stdin and must emit the observed output JSON on stdout).",
+      "kind": "http",
+      "base_url": "REPLACE_WITH_LEGACY_BASE_URL"
+    },
+    "candidate": {
+      "_comment": "The new (AppWeaver) implementation behind the seam.",
+      "kind": "http",
+      "base_url": "REPLACE_WITH_CANDIDATE_BASE_URL"
+    }
+  },
+  "compare": {
+    "_comment": "ignore_paths are dropped from BOTH sides before diffing — use for non-deterministic fields (generated ids, timestamps). Supports $.a.b, wildcard $.a[*].b and $.*.b. ignore_status compares bodies only.",
+    "ignore_paths": ["$.id", "$.createdAt", "$.updatedAt", "$.*.timestamp"],
+    "ignore_status": false,
+    "timeout_seconds": 30
+  },
+  "expected_deviations": [
+    {
+      "_comment": "Approved INTENDED differences. A diff matching {case, path} here is ACCEPTED, not a failure. Each one MUST be recorded as a MODIFIED spec item via the CR delta loop — parity does not let behaviour drift silently. Delete this example.",
+      "case": "PC-000-EXAMPLE",
+      "path": "$.someField",
+      "reason": "MODIFIED US-n: <why the new behaviour intentionally differs from legacy>"
+    }
+  ],
+  "cases": [
+    {
+      "_comment": "EXAMPLE case — /appweaver parity replaces these with real ones derived from the spec's US/FR and the source-map's as-built quirks (each quirk MUST have a case that confirms the new code reproduces it). `request` is compared on {status, body}; optional `state_probe` is a follow-up request whose response captures RESULTING STATE (compared on body). Omit state_probe if not needed. Give real cases ids like PC-001 (ids ending EXAMPLE are ignored).",
+      "id": "PC-001-EXAMPLE",
+      "description": "Register a product with a valid NDC",
+      "spec_ids": ["US-1", "FR-001"],
+      "request": {
+        "method": "POST",
+        "path": "/product",
+        "headers": { "Content-Type": "application/json" },
+        "body": {}
+      },
+      "state_probe": {
+        "method": "GET",
+        "path": "/product/by-ndc/12345-678-90"
+      }
+    }
+  ]
+}

package/assets/.appweaver/templates/source-map-template.md

@@ -0,0 +1,85 @@
+# Source Map: [AGGREGATE]
+
+**Aggregate (feature)**: `[Aggregate]`  <!-- the feature = the aggregate, e.g. MedicinalProduct -->
+
+**Source home**: `specs/[Aggregate]/source-map.md`
+
+**Origin**: `reverse-engineered`   <!-- greenfield | reverse-engineered | migrated -->
+
+**Version**: v1.0   <!-- moves in lockstep with spec.md / design.md -->
+
+**Baseline commit**: `[short-sha]`   <!-- the inventory HEAD this slice was adopted from -->
+
+<!--
+  WHAT THIS DOCUMENT IS
+  =====================
+  The SOURCE ANCHOR of the traceability spine for a slice that aw-spec ADOPTED
+  from existing code (Brownfield-Pipeline B1). It links each LEGACY ARTEFACT
+  (source file, DB table, endpoint, background job) to the spec/design section
+  that now describes it, so:
+    • strangler cutover is precise — you know exactly which code a slice owns;
+    • impact analysis is exact — a legacy change traces forward to spec ids;
+    • parity is scoped — you diff only this slice's surface.
+
+    LegacyArtefact ↔ FR/BR/US ↔ Spec-section ↔ Design-element ↔ Code ↔ Commit
+
+  This is a SIDECAR: spec.md and design.md stay clean, forward-loop documents
+  (the CR delta loop + forward pipeline consume them unchanged). The brownfield
+  provenance lives HERE and in the `origin:` frontmatter — never as extra
+  structure inside spec.md / design.md.
+
+  CONFIDENCE travels with each row: `certain` (the code states it outright) vs
+  `inferred` (reverse-engineering had to reason). Inferred rows are the Adopt
+  review (B1·R) + Fidelity worklist; unresolved ones become spec Assumptions or
+  `[NEEDS CLARIFICATION]` — never silently promoted to fact.
+-->
+
+## Seam
+
+<!--
+  ACTION REQUIRED: the boundary this slice owns — what you can route traffic
+  across for a strangler cutover (interface, endpoint, queue, table owner) —
+  and whether it is CLEAN or TORN. A TORN seam (shares a transaction/table with
+  another slice) is a REMEDIATION item: introduce the seam before cutover.
+-->
+
+- **Boundary**: [e.g. `/product` endpoints + `PRODUCTS` table owner]
+- **Seam quality**: [clean | torn]
+- **Torn-seam remediation** (if torn): [what must be split first, or "n/a"]
+
+## Artefact → spec/design map
+
+<!--
+  ACTION REQUIRED: one row per legacy artefact this slice owns. Every source file
+  in the OKF bundle concept's `source_files` MUST appear here (Fidelity checks
+  full coverage both ways: no unmapped code, no spec id without a code anchor).
+-->
+
+| # | Legacy artefact | Kind | Spec ids | Design element | Confidence | Notes / quirk |
+|---|---|---|---|---|---|---|
+| SM-001 | `src/.../MedicinalProduct.cs` | file (aggregate root) | US-1, BR-001 | §1 Domain · MedicinalProduct | certain | |
+| SM-002 | `PRODUCTS` | table | FR-003, DC-001 | §4 Infra · MedicinalProductRepository | inferred | NDC stored unformatted — see WA/CN |
+| SM-003 | `POST /product` | endpoint | US-1, FR-001 | §3 API · RegisterMedicinalProduct | certain | |
+
+## As-built quirks captured
+
+<!--
+  ACTION REQUIRED: behaviours the code exhibits AS-IS (bugs, non-obvious
+  formatting, undocumented defaults) that were captured faithfully. Each links to
+  the spec item that records it (a MODIFIED-later candidate) or to a deviation.
+  These become characterization-test targets (B2) and deviation-register entries.
+  "None observed" if the slice is clean.
+-->
+
+- [e.g. NDC codes are stored without the canonical 5-4-2 hyphenation — captured as-is; candidate deviation.]
+
+## Unmapped / open
+
+<!--
+  Source files the reverse pass could not confidently place, and spec ids with no
+  code home found. Both are Fidelity gaps to resolve (out of band or by refining
+  the reverse spec/design). Empty when the map is complete.
+-->
+
+- **Unmapped code**: [files not yet placed, or "none"]
+- **Unanchored spec ids**: [spec items with no code, or "none"]