aw-spec-cli 0.1.5 → 0.1.6

package/assets/.aw-spec/orchestrator/workflows/aw-spec-adopt.orch.yaml

@@ -1,775 +0,0 @@
-# =============================================================================
-# aw-spec-adopt (orchestrator) — the JUST-IN-TIME per-feature step of Brownfield DEV
-#
-# Develop an EXISTING feature by first reverse-engineering ONE aggregate / vertical
-# slice from its code into a living spec.md + aligned design.md (+ a source-map.md
-# sidecar), THEN reconciling this feature's evidence into the project governance that
-# /aw-spec-orch onboard established. Adopt is the inverse of implement: implement reads
-# spec+design and generates code; adopt reads code and generates spec+design — equally
-# a reasoning step, stamped `origin: reverse-engineered` with per-item confidence.
-#
-#   onboard → ADOPT <Feature> (JIT, one feature at a time) → [ forward / CR delta loop ]   ← you are here
-#
-# Adopt is JUST-IN-TIME and per-feature: reverse ONLY the feature you are about to
-# develop, never the whole codebase (that scale is what onboard's shallow feature map
-# avoids). A NEW feature (no existing code) is NOT adopted — it is authored straight
-# through the forward pipeline (/aw-spec-orch specify → design → implement), which
-# onboard already made brownfield-ready (the code-derived design template is the
-# project default). So adopt = reverse an EXISTING feature; the forward pipeline = a
-# new one. Both then evolve through the CR delta loop.
-#
-# The reverse output is a NORMAL feature: spec.md + design.md are the very documents
-# the CR delta loop + forward pipeline consume unchanged. All brownfield provenance
-# lives in `origin:` frontmatter + the source-map sidecar. Adopt inits
-# active_version.json (v1.0) so the CR loop works immediately after.
-#
-# GOVERNANCE RECONCILE (the JIT contract, gap-fix #1): onboard established the PROJECT
-# constitution + docs/domainspecs/<domain>/ rule pack from the whole-repo SCAN, with
-# per-feature specifics marked PROVISIONAL. Adopt RECONCILES this feature's real
-# evidence (BR-/CN-/DC-/IC- ids, code coordinates) INTO that scaffold — upgrading
-# provisional → evidenced. It RECONCILES, never re-authors: it never rewrites the
-# project's principle SET or another feature's evidence (that would re-introduce
-# single-feature scoping bias), so the constitution stays PROJECT-scoped.
-#
-# Rule partition (same as the forward loop): the reversed SPEC is authored with DOMAIN
-# authority (DDD); the reversed DESIGN is authored from the spec + TECHNICAL standards
-# only, NO domain files — domain reaches design as spec ids.
-#
-# Adopt does NOT generate code and does NOT modify source — writes land under
-# specs/<Feature>/, .aw-spec/memory/constitution*.md, and docs/domainspecs/<domain>/.
-# Fidelity checks spec/design ↔ CODE; the Adopt review is REPORTED for out-of-band
-# closure — it blocks only on structural failures (unmapped code / fabricated spec/design).
-# There is NO migration content here (characterize is an optional on-touch fence, not a
-# phase; parity/cutover belong to the separate later modernization phase).
-#
-# Launch:  /aw-spec-orch adopt [strategy]         # adopt the ACTIVE feature (set by select-feature)
-#          /aw-spec-orch adopt [strategy] <Feature>   # or name it directly (also selects it)
-#   e.g.   /aw-spec-orch adopt MedicinalProduct
-# Prereq:  /aw-spec-orch onboard  (the feature map names this feature + the governance
-#          scaffold adopt reconciles into), then /aw-spec-orch select-feature to pick
-#          the aggregate — adopt consumes it, so the no-arg form is the normal path.
-# =============================================================================
-
-name: aw-spec-adopt
-description: The JIT per-feature step of brownfield development — reverse-engineer ONE existing feature into a living spec.md + design.md + source-map.md (origin reverse-engineered, per-item confidence, code-derived design template), COMPLETE its shallow OKF concept (deepen it to the reversed reality + link the deep artifacts), then RECONCILE its real evidence into the project governance onboard established (fill the provisional rule files + constitution — reconcile, never re-author). Fidelity gate is spec/design vs code; the review is reported for out-of-band closure. A NEW feature is authored via the forward pipeline instead. Output is a normal feature for the CR + forward loop.
-# 1.5.0 — user_input is now OPTIONAL: adopt CONSUMES the ACTIVE feature (select-feature's
-#         .aw-spec/feature.json) when no arg is passed, so onboard→select-feature→adopt needs
-#         no re-typing; an explicit <Feature> still selects directly (and wins). One coalesced
-#         feature_name (set-feature-canonicalised) replaces USER_INPUT throughout.
-# 1.4.0 — COMPLETE the shallow OKF aggregate concept from the trustworthy reversed docs
-#         (deepen detail + link spec/design/source-map + mark adopted) before xref_record.
-# 1.3.0 — reverse design scaffolds from the DEFAULT `design-template` (onboard's code-derived
-#         override) instead of the never-shipped `brownfield-design-template`, unifying the
-#         whole brownfield pipeline on one code-derived template.
-version: 1.5.0
-agent_agnostic: true
-dialect: aw-spec.orchestrator/v1
-
-inputs:
-  user_input:
-    description: OPTIONAL existing feature to adopt (a candidate from the onboard feature map, e.g. MedicinalProduct). Omit it to adopt the ACTIVE feature already selected by /aw-spec-orch select-feature (.aw-spec/feature.json) — the normal onboard→select-feature→adopt flow. A NEW feature (no existing code) is developed via the forward pipeline instead, not adopt.
-    required: false
-    bind: USER_INPUT
-
-scripts:
-  inventory:
-    sh:  .aw-spec/scripts/bash/aw-inventory.sh
-    ps1: .aw-spec/scripts/powershell/aw-inventory.ps1
-  actions:
-    sh:  .aw-spec/scripts/bash/aw-spec-actions.sh
-    ps1: .aw-spec/scripts/powershell/aw-spec-actions.ps1
-  xref:
-    sh:  .aw-spec/scripts/bash/aw-xref.sh
-    ps1: .aw-spec/scripts/powershell/aw-xref.ps1
-
-# Sticky standards seed = the UNIVERSAL always-on rule only (ai-rules). The TECHNICAL/
-# architecture set for the reversed DESIGN step (mirrors aw-spec-design) is no longer
-# hardcoded here — it is now CONFIGURATION, loaded per-command from
-# docs/domainspecs/<domain>/commandtechrulemap.md under "## /aw-spec-adopt" by the
-# tech-select module (see the tech_select step below). The reversed SPEC step runs
-# include_standards:false and gets DOMAIN authority (DDD + domain constitution) via
-# build_context — so design never sees a domain rule file (rule partition preserved); the
-# tech map lists only technical files. constitution.technical.md is referred to directly
-# (context in reverse_design), never mapped. Missing files skipped at assembly time.
-standards:
-  - { path: docs/glossary/ai-rules.md, optional: true }
-
-vars:
-  bundle_dir: "knowledge"      # where /aw-spec-orch onboard writes the OKF feature map (repo-root default)
-  feature_name: ""             # the aggregate to adopt: USER_INPUT if passed, else the active feature (set-feature canonicalises)
-  concept_exists: "false"
-  spec_exists: "false"
-  fidelity_ok: "false"
-  rulemap_exists: "false"      # governance-present signal (onboard ran) — bound from resolve-domain
-  reconcile_governance: "false"  # HELD 2026-07-29 — the governance (constitution + rule-pack) reconcile block is PAUSED on adopt; flip to "true" to re-enable it
-  technical_ok: "false"        # technical-half reconcile lint guard
-  domain_ok: "false"           # domain-half reconcile lint guard
-  guard_sentinel: ""           # deliberately empty — the conditioned "already-adopted" gate stops on it
-  pack_reconciled: ""          # default while reconcile is HELD (no rule-pack files reconciled)
-  composed_file: ""            # default while reconcile is HELD (constitution view not recomposed)
-
-workflow:
-
-  # 0. TECHNICAL rule files → sticky standards (configuration, not hardcoded). tech-select
-  #    reads docs/domainspecs/<domain>/commandtechrulemap.md under "## /aw-spec-adopt" and
-  #    loads that reference set into the sticky standards. Loaded FIRST so it is present for
-  #    reverse_design (include_standards:true) — the reversed SPEC step still turns it off
-  #    (include_standards:false), keeping design domain-free (rule partition). No domain rule
-  #    file here — the tech map lists only technical files. No blocking gate: an unconfigured
-  #    project soft-continues (constitution.technical.md still carries the tech base).
-  - id: tech_select
-    action: include
-    module: .aw-spec/orchestrator/modules/tech-select.orch.yaml
-    with: { command: aw-spec-adopt }
-
-  # 1. Resolve the aggregate to adopt. TWO ways in (arg wins over active):
-  #    a) `/aw-spec-orch adopt <Feature>` — the explicit arg selects directly.
-  #    b) `/aw-spec-orch adopt` (no arg) — CONSUME the feature select-feature already
-  #       made active (.aw-spec/feature.json), so the onboard→select-feature→adopt
-  #       flow needs no re-typing. feature-paths returns the active aggregate name;
-  #       on_error:continue leaves it empty when nothing is selected yet.
-  - id: active_feature
-    action: execute_script
-    on_error: continue
-    script: { ref: actions }
-    subcommand: feature-paths
-    outputs:
-      - { name: active_name, from: "$.feature" }
-
-  # Coalesce: default to the active feature, then let an explicit arg override it.
-  # (The engine has no compound conditions, so this is two ordered sets.)
-  - id: name_from_active
-    action: set
-    vars: { feature_name: "{{active_name}}" }
-  - id: name_from_arg
-    action: set
-    condition: "{{USER_INPUT}}"
-    vars: { feature_name: "{{USER_INPUT}}" }
-
-  - id: require_target
-    action: verify_context
-    require_non_empty: feature_name
-    on_empty: stop
-    on_empty_message: "No feature to adopt. Either run /aw-spec-orch select-feature first (pick the aggregate from the onboard feature map), then /aw-spec-orch adopt; or name it directly: /aw-spec-orch adopt <Feature>."
-
-  # Create-or-select the feature dir + persist it active (idempotent in the no-arg
-  # path where it is already active; creates it in the explicit-arg path). set-feature
-  # canonicalises to the PascalCase aggregate id → the single feature_name used below.
-  - id: set_feature
-    action: execute_script
-    script: { ref: actions }
-    subcommand: set-feature
-    args: ["--feature", "{{feature_name}}"]
-    outputs:
-      - { name: feature_name, from: "$.feature" }
-      - { name: feature_dir,  from: "$.feature_dir" }
-      - { name: spec_file,    from: "$.spec_file" }
-      - { name: spec_exists,  from: "$.spec_exists" }
-
-  # 1a. One-time baseline: refuse to clobber an already-adopted / authored spec.
-  #     After adoption, changes go through the CR delta loop, not adopt.
-  #     set-feature returns spec_exists as a JSON boolean; the condition path
-  #     normalises bools to "true"/"false" (json), so gate through it — a
-  #     require_value/equals would compare str(False)="False" and mis-fire. The
-  #     gate only runs when a spec already exists, and stops on the empty sentinel.
-  - id: guard_not_adopted
-    condition: "{{spec_exists}} == true"
-    action: verify_context
-    require_non_empty: guard_sentinel
-    on_empty: stop
-    on_empty_message: "specs/ already has a spec.md for {{feature_name}} — adopt is a one-time baseline. For a change to an adopted slice use the CR delta loop (/aw-spec-orch specify → design → analyze-delta-design → implement-delta → build → finalize-delta → analyze-slice → close-delta); to re-adopt from scratch, remove the feature dir first."
-
-  # 1b. Resolve this aggregate's OKF bundle concept → its source_files (the code
-  #     that IS the slice) + module dir. The INDEX adopt reverse-engineers FROM;
-  #     the code itself is the source of truth (read during authoring).
-  - id: concept
-    action: execute_script
-    script: { ref: inventory }
-    subcommand: concept
-    args: ["--bundle", "{{bundle_dir}}", "--aggregate", "{{feature_name}}"]
-    outputs:
-      - { name: concept_exists, from: "$.exists" }
-      - { name: concept_path,   from: "$.concept_path" }
-      - { name: source_files,   from: "$.source_files" }
-      - { name: source_count,   from: "$.count" }
-      - { name: module_dir,     from: "$.module_dir" }
-
-  # No feature-map concept for this name means one of two things, both handled by a
-  # redirect (adopt reverses EXISTING code only): either onboard has not run, or this
-  # is a NEW feature (no existing code) — which is developed via the forward pipeline,
-  # not adopt.
-  - id: require_concept
-    action: verify_context
-    require_true: concept_exists
-    on_false: stop
-    on_false_message: "No feature '{{feature_name}}' in the onboard feature map under {{bundle_dir}}. If you have not onboarded, run /aw-spec-orch onboard first, then use the exact feature name from {{bundle_dir}}/aggregates/index.md. If '{{feature_name}}' is a NEW feature (no existing code), do NOT adopt it — author it through the forward pipeline (/aw-spec-orch specify → design → implement), which onboard already made brownfield-ready."
-
-  # Governance prerequisite (JIT contract): adopt RECONCILES this feature's evidence into
-  # the governance onboard established (constitution + docs/domainspecs/<domain>/ pack).
-  # Resolve the active domain now and require its rule map to exist — if it does not,
-  # onboard has not established governance, and there is nothing for adopt to reconcile
-  # into. (Reconciling into a project scaffold, never authoring from one feature, is what
-  # keeps the constitution PROJECT-scoped — gap-fix #1.)
-  - id: resolve_active_domain
-    action: execute_script
-    script: { ref: actions }
-    subcommand: resolve-domain
-    outputs:
-      - { name: gov_domain,     from: "$.domain" }
-      - { name: rulemap_exists, from: "$.rulemap_exists" }
-
-  - id: require_governance
-    action: verify_context
-    require_true: rulemap_exists
-    on_false: stop
-    on_false_message: "No active governance to reconcile into — run /aw-spec-orch onboard first. onboard establishes the PROJECT constitution + docs/domainspecs/<domain>/ rule pack (provisional-from-scan); adopt reconciles this feature's real evidence into it. Reversing '{{feature_name}}' without that scaffold would have no governance home."
-
-  # 2. Scaffold the living docs. The SPEC reuses the forward spec-template (it is
-  #    tech-agnostic WHAT/WHY — no architectural bias). The DESIGN scaffolds from the
-  #    DEFAULT `design-template` — which /aw-spec-orch onboard REPLACED with the repo's
-  #    code-derived override (resolve_template Priority-1, reverse-engineered from the
-  #    code), so the reversed design's structural sections follow the code's own
-  #    architecture rather than a fixed greenfield layering, describing the system
-  #    as-built. (Falls back to the greenfield base if onboard has not run.) Both are
-  #    still normal forward docs (same identity + spine) that the CR delta loop consumes
-  #    unchanged. Then init active_version.json (v1.0).
-  - id: scaffold_spec
-    action: execute_script
-    script: { ref: actions }
-    subcommand: scaffold
-    args: ["--feature-dir", "{{feature_dir}}", "--allow-existing"]
-
-  - id: scaffold_design
-    action: execute_script
-    script: { ref: actions }
-    subcommand: design-scaffold
-    args: ["--feature-dir", "{{feature_dir}}"]   # default `design-template` = onboard's code-derived override (greenfield base if onboard has not run)
-    outputs:
-      - { name: design_doc, from: "$.design_doc" }
-
-  - id: version_init
-    action: execute_script
-    script: { ref: actions }
-    subcommand: version-init
-    args: ["--feature-dir", "{{feature_dir}}"]
-
-  # 3. Pre-execution hooks.
-  - id: resolve_pre_hooks
-    action: execute_script
-    script: { ref: actions }
-    subcommand: resolve-hooks
-    args: ["--phase", "before_adopt"]
-    outputs:
-      - { name: before_hooks, from: "$.hooks" }
-  - id: dispatch_pre_hooks
-    action: dispatch_hooks
-    hooks_from_variable: before_hooks
-
-  # ══════════════ REVERSE SPEC — from CODE, with DOMAIN authority ═════════════
-  # The bundle concept is the INDEX (source_files, seam, open_questions); the
-  # CODE is the source of truth. DDD is fed via context (NOT the sticky set) so
-  # the spec is domain-classified but the technical/arch set stays off the spec.
-  - id: ctx_reverse_spec
-    action: build_context
-    context:
-      - { path: "{{spec_file}}" }                 # the scaffolded template = section structure
-      - { path: "{{concept_path}}" }              # the OKF concept: source_files, seam, open_questions
-      - { path: docs/domain/domain-driven-design.md, optional: true }        # DDD authority (classification)
-      - { path: .aw-spec/memory/constitution.domain.md, optional: true }     # the domain frame
-  - id: reverse_spec
-    action: agent_author
-    include_standards: false                       # domain via context; technical/arch sticky set is for design
-    output_target: { type: file, path: "{{spec_file}}" }
-    task: |
-      Reverse-engineer the MASTER specification (the target spec.md in context)
-      for the aggregate '{{feature_name}}' FROM ITS CODE. The bundle concept (in
-      context) is the INDEX — its `source_files` list the code that IS this slice;
-      READ those files (under {{module_dir}}, listed below) as the SOURCE OF TRUTH.
-      The concept is a summary; the CODE is authoritative — if they disagree, the
-      code wins (and note the drift). Fill the template; preserve its section order.
-
-      Capture what the code ACTUALLY DOES, as-built (bugs/quirks included), in the
-      template's vocabulary:
-      - The feature IS the aggregate; set the Aggregate field, keep US-1.
-      - Each command / endpoint / use-case the code exposes is a USER STORY (US-n),
-        never a separate feature. Derive its Given/When/Then from the code's paths.
-      - System Requirements in EARS (THE SYSTEM SHALL / WHEN / IF…THEN / WHILE /
-        WHERE), each atomic + testable, derived from observed behaviour.
-      - Always-true invariants the code enforces → Business Rules (BR-n).
-      - DDD (in context) IS the modelling standard: express the domain as a
-        ubiquitous language, the aggregate + root, entities vs value objects, and
-        aggregate-owned invariants — as domain MODEL, not code / not C# types.
-      - DOMAIN LIFT — where the CODE enforces them, lift into the three sections
-        (cite the source file): Constraints & NFRs (CN-, e.g. retention /
-        immutability / append-only audit the code implements), Data Classification
-        (DC-, sensitive fields + where they may/mustn't appear), Integration
-        Contracts (IC-, external services/feeds the code calls). "None (as of v1.0)"
-        if the code shows none — never delete a section.
-      - Always include "## Success Criteria" with 2-4 measurable SC-nnn.
-
-      PROVENANCE + honesty (this is a REVERSED spec):
-      - Add `origin: reverse-engineered` to the spec's identity block (near Version).
-      - Mark CONFIDENCE: where you had to INFER intent the code does not state
-        outright, tag the item "(inferred)" and add a `[NEEDS CLARIFICATION: …]`
-        marker (at most 3, highest-impact) or an Assumption — NEVER fabricate a
-        rule the code does not exhibit. Behaviour that is clearly present is
-        "(certain)".
-      - Reference the source-map: note that legacy-artefact ↔ requirement links
-        live in `specs/{{feature_name}}/source-map.md` (authored next).
-      - This is v1.0: fill the Change History row; keep US-1's "Added: v1.0".
-      - Business-facing + testable; NO implementation mechanics (an external interop
-        OBLIGATION is an IC- requirement, never the adapter design).
-
-      Source files to read (the slice's code): {{source_files}}
-
-  # ═══════════ REVERSE DESIGN — from the reversed SPEC + CODE, AS-BUILT ═══════
-  # Anchored to the reversed spec's ids (§4 Traceability → forward-compatible),
-  # grounded in the code's ACTUAL structure, tech-agnostic. NO domain files (rule
-  # partition). The scaffolded design.md IS onboard's code-derived `design-template`
-  # override — its §2 component sections follow the code's own folders/modules, not a
-  # fixed layering.
-  - id: ctx_reverse_design
-    action: build_context
-    context:
-      - { path: "{{design_doc}}" }                # the scaffolded code-derived template = structure + embedded guidance
-      - { path: "{{spec_file}}" }                 # the reversed spec = the ONLY domain input
-      - { path: "{{concept_path}}" }              # source_files + seam (structure hints)
-      - { path: .aw-spec/DESIGN-FORMAT.md }        # the HLD contract (see its Brownfield variant note)
-      - { path: knowledge/architecture/overview.md, optional: true } # the as-built architecture (inventory) — cite, don't re-derive
-      - { path: .aw-spec/memory/constitution.technical.md, optional: true } # technology base ONLY — no domain
-  - id: reverse_design
-    action: agent_author
-    include_standards: true                        # the technical/architecture sticky set (reference only — the CODE wins)
-    output_target: { type: file, path: "{{design_doc}}" }
-    task: |
-      Reverse-engineer the MASTER high-level design (the target design.md in
-      context — it is the BROWNFIELD design template) — the tech-agnostic HLD that
-      MEDIATES the reversed spec ↔ the existing code. Ground every element in the
-      CODE (read the source files listed below) but ANCHOR each to a spec id from
-      the reversed spec (in context) so §4 Traceability is complete and the doc is
-      forward-compatible. Guidance: {{feature_name}}
-
-      THE CODE IS THE SOURCE OF TRUTH — describe the system AS-BUILT. Do NOT reshape
-      it toward any reference architecture; the technical standards in context are a
-      vocabulary to NAME what you find, never a target to bend the code toward.
-      Rules:
-      - THE SPEC IS THE ONLY DOMAIN INPUT. You have the reversed spec + the code's
-        actual STRUCTURE — and NO domain rule files. Realise the spec ids; introduce
-        no domain rule the spec omits. A concept the code exhibits but the spec lacks
-        → surface it (it belongs in the spec) and record a §5 DA-n; do not smuggle it in.
-      - STRUCTURE FOLLOWS THE CODE. Fill §1.1 As-Built Architecture from the code's
-        real shape (its folders / projects / modules — name the style, don't prescribe
-        one). Then create ONE §2 subsection per structural axis the slice's code
-        ACTUALLY has (its use-cases, endpoints/UI, persistence, external adapters,
-        jobs, host/composition) — titled after the CODE's own units, NOT a fixed
-        Domain/Application/API/Infrastructure layering. A component the code has that
-        fits no textbook layer (a UI tier, a worker, a shared library) gets its own
-        section; a layer the code lacks does NOT appear.
-      - KEEP THE NEUTRAL ANCHORS (the template pins these): §1.2 is the domain/data
-        MODEL and MUST match the spec's Key Entities / Business Rules (same names,
-        cite BR-/CN-) with cross-slice References-by-id kept here; one §2 subsection
-        is the EXTERNAL INTEGRATIONS table (heading contains "Integration") realising
-        the spec's IC-. Realise CN- (structural → §1.2 invariants/events; retention/
-        audit → §2 persistence / §3 cross-cutting), DC- (§3 + projection surface).
-      - AS-BUILT DEBT, not architecture drift. §6 records ONLY debt the CODE ITSELF
-        evidences — stubs/no-ops, dead or duplicate code, torn seams (shared table/
-        transaction), TODOs, hard-coded values. The code being organised differently
-        from any textbook layering is NOT debt — it is the as-built architecture (§1.1).
-        The concrete stack lives in the source-map, NOT here.
-      - TECHNOLOGY-AGNOSTIC: signatures + pre/post/invariant/raises pseudocode and
-        field-shape contracts — NEVER language code. Conceptual types only.
-      - Fill §4 Traceability completely (a row for EVERY FR/BR/CN/DC/IC/US/SC), and
-        the §5 Assumptions (DA-n) / §6 As-Built Deviations (WA-n) ledgers.
-      - Add `origin: reverse-engineered` near the Version field. This is v1.0.
-      - Omit a section only if the slice genuinely has nothing there (say why); no
-        complete code anywhere.
-
-      Source files to read (the slice's code): {{source_files}}
-
-  # ═══════════════ SOURCE MAP — the source anchor sidecar ════════════════════
-  - id: ctx_source_map
-    action: build_context
-    context:
-      - { path: .aw-spec/templates/source-map-template.md }   # the sidecar structure
-      - { path: "{{spec_file}}" }
-      - { path: "{{design_doc}}" }
-      - { path: "{{concept_path}}" }              # the full source_files list to map
-  - id: source_map
-    action: agent_author
-    include_standards: false
-    output_target: { type: file, path: "{{feature_dir}}/source-map.md" }
-    task: |
-      Author the source-map sidecar (the target in context) from the template,
-      for aggregate '{{feature_name}}'. It is the SOURCE ANCHOR of the traceability
-      spine — it keeps spec.md / design.md clean while recording provenance here.
-      - One row per legacy artefact in the bundle concept's `source_files` (read
-        them under {{module_dir}}): map each to the spec ids (FR/BR/US/CN/DC/IC)
-        and the design element (§/name) that now describe it, with CONFIDENCE
-        (certain | inferred). EVERY source file MUST appear — the Fidelity gate
-        checks full coverage both ways.
-      - Also map DB tables, endpoints, and background jobs the slice owns.
-      - Fill the Seam section: the boundary this slice owns (endpoint / table
-        owner / queue / interface), and note whether it is self-contained or SHARES
-        a transaction/table with another slice — a coupling fact for CR blast-radius
-        analysis (not a migration item).
-      - Record as-built quirks captured verbatim (candidate deviations), and any
-        unmapped code / unanchored spec ids.
-      - Baseline commit = the inventory HEAD.
-      Source files to map: {{source_files}}
-
-  # ═══════════════ FIDELITY — does spec+design describe the CODE? ═════════════
-  # spec/design ↔ CODE (NOT spec ↔ design). The agent can READ the source files.
-  # BLOCKING gaps = unmapped code / fabricated spec-or-design (structural). The
-  # rest (inferred items, quirks, missing-invariant candidates) are REVIEW items
-  # → written to an Adopt Review report and closed OUT OF BAND (Brownfield B1·R).
-  - id: fidelity
-    action: agent_query
-    context:
-      - "{{spec_file}}"
-      - "{{design_doc}}"
-      - "{{feature_dir}}/source-map.md"
-      - "{{concept_path}}"
-    include_standards: false
-    schema: { ok: true, report_needed: false, blocking_gaps: [ { severity: "high", artefact: "<source file / spec id / design element>", kind: "unmapped-code | fabricated-spec | fabricated-design", detail: "<why>" } ], review_items: [ { kind: "inferred | as-built-quirk | missing-invariant | confidence", where: "<spec/design/source-map location>", note: "<what to confirm out of band>" } ] }
-    mock: { ok: true, report_needed: false, blocking_gaps: [], review_items: [] }
-    task: |
-      FIDELITY CHECK — does the reversed spec.md + design.md actually describe the
-      CODE (spec/design ↔ CODE, NOT spec ↔ design)? Use the source-map (in context)
-      and READ the slice's source files (the concept's `source_files`, under
-      {{module_dir}}). Classify findings:
-      - BLOCKING (structural — set ok=false if any):
-        (1) unmapped-code: a source file with NO spec/design home in the source-map;
-        (2) fabricated-spec / fabricated-design: a spec id or design element with NO
-            basis in the code (reverse-engineering must not invent behaviour).
-      - REVIEW (does NOT block ok — these are the Adopt review worklist, closed out
-        of band): items marked "(inferred)"; as-built quirks the code shows but the
-        spec under-states; invariants the code enforces that may be missing/weak;
-        confidence miscalibration (marked inferred but clearly certain, or vice versa).
-      Set ok=true when there are NO blocking gaps (review_items may still be listed).
-      Set report_needed=true if there is ANY blocking gap OR any review item.
-    outputs:
-      - { name: fidelity_ok,      from: "$.ok" }
-      - { name: report_needed,    from: "$.report_needed" }
-      - { name: blocking_gaps,    from: "$.blocking_gaps" }
-      - { name: review_items,     from: "$.review_items" }
-
-  # Write the Adopt Review report when there's anything to close out of band
-  # (blocking gaps to fix, or review items to confirm). The B1·R worklist.
-  - id: write_review_report
-    condition: "{{report_needed}} == true"
-    action: agent_author
-    include_standards: false
-    context: ["{{spec_file}}", "{{design_doc}}", "{{feature_dir}}/source-map.md"]
-    output_target: { type: file, path: "{{feature_dir}}/adopt-review-report.md" }
-    task: |
-      Write an Adopt Review report (the target) for aggregate '{{feature_name}}' —
-      the out-of-band worklist for this reverse-engineered baseline. Markdown:
-      - "# Adopt Review — {{feature_name}}" + today's date + "origin: reverse-engineered".
-      - "verdict:" line — "BLOCKING ✗ · <n>" if blocking gaps exist, else "REVIEW ○ · <m> item(s)".
-      - "## Blocking gaps" (if any): table | # | kind | artefact | detail | — MUST be
-        resolved before the slice is trustworthy (fix by re-reading the code / refining
-        spec+design, then re-run adopt-review or re-adopt).
-        Blocking gaps: {{blocking_gaps}}
-      - "## Review items" (close out of band): table | # | kind | where | confirm |.
-        These are inferred-vs-certain calls, as-built quirks, and missing-invariant
-        candidates — confirm each against the code/SME, then fold the answer into
-        spec.md (a resolved [NEEDS CLARIFICATION] / Assumption) or log a deviation.
-        Review items: {{review_items}}
-      - "## How to proceed": resolve blocking gaps first; then the slice is a normal
-        feature — run /aw-spec-orch analyze-design (spec↔design gate) if desired, then
-        drive every change through the CR delta loop. If a change edits untested legacy
-        behaviour with blast radius, characterize just that surface first (optional
-        on-touch fence) — it is not a required phase.
-      Return the report markdown only.
-
-  - id: fidelity_gate
-    action: verify_context
-    require_true: fidelity_ok
-    on_false: stop
-    on_false_message: "Fidelity FAILED for {{feature_name}} — the reversed spec/design do not match the code (blocking gaps: {{blocking_gaps}}). See specs/{{feature_name}}/adopt-review-report.md. Fix the unmapped code / remove fabricated items (re-read the source, refine spec.md + design.md + source-map.md), then re-run /aw-spec-orch adopt (after removing the dir) or resolve out of band."
-
-  # ═══════════ OKF CONCEPT — COMPLETE the shallow scan concept (deep reverse) ═══
-  # onboard wrote this aggregate's OKF concept SHALLOW (a discovery stub — enough to pick the
-  # feature). Now that the deep reverse produced a TRUSTWORTHY spec.md + design.md +
-  # source-map.md, COMPLETE the concept: deepen its detail to the reversed reality, LINK the
-  # authored artifacts, refresh source_files, and mark it ADOPTED. RECONCILE, not rewrite —
-  # keep OKF format + the bundle links; do NOT touch the Depends-On / Cross-References
-  # sections (xref_record owns those, next). Runs only after fidelity passes (deepened from
-  # trustworthy docs). The complement of the governance reconcile below — the DISCOVERY tier
-  # (OKF) is completed here, the GOVERNANCE tier (constitution + rule pack) just after.
-  - id: ctx_complete_concept
-    action: build_context
-    context:
-      - { path: "{{concept_path}}" }                          # the shallow onboard concept to complete
-      - { path: "{{spec_file}}" }                             # the deep reversed spec (entities, US, BR/CN/DC/IC)
-      - { path: "{{design_doc}}" }                            # the deep reversed design (components, ports, integrations)
-      - { path: "{{feature_dir}}/source-map.md" }             # the source anchor (files, seam, quirks)
-      - { path: .aw-spec/templates/okf-concept-template.md }  # OKF v0.1 format authority
-  - id: complete_concept
-    action: agent_generate
-    tools: "Read,Write,Edit"
-    permission_mode: acceptEdits
-    task: |
-      COMPLETE the OKF aggregate concept for '{{feature_name}}' at {{concept_path}} — onboard
-      wrote it SHALLOW (a discovery stub from the whole-repo scan). The deep reverse has now
-      produced a TRUSTWORTHY spec.md + design.md + source-map.md (in context); deepen the
-      concept to match and LINK those artifacts. Follow the OKF concept template in context.
-      RECONCILE, do NOT rewrite:
-      - DEEPEN the responsibilities + the owned entities / value objects / domain events /
-        commands (user stories) / API endpoints / persistence to match the reversed spec +
-        design — correct any drift the shallow scan got wrong (the deep docs win).
-      - LINK the deep artifacts: add bundle links to specs/{{feature_name}}/spec.md, design.md,
-        and source-map.md so the concept points at the deep truth.
-      - Refresh `source_files` from the source-map (grouped by the code's OWN folders, per
-        OKF), and set `timestamp` to the baseline (inventory HEAD) commit time.
-      - Update frontmatter: keep `origin: reverse-engineered`; mark the concept ADOPTED /
-        deep-reversed (no longer a shallow scan stub) and stamp `generated_by: aw-spec-adopt`.
-      - Resolve any `open_questions` the deep reverse answered; keep the rest.
-      - Do NOT touch the concept's Depends-On / Cross-References sections (xref_record
-        maintains those next), and do NOT edit any OTHER aggregate concept.
-      Append a one-line `log.md` entry (bundle root) under today's date noting '{{feature_name}}'
-      was deep-adopted. Write ONLY {{concept_path}} (+ its dir index.md / bundle log.md if a
-      link or description changed). Report what you deepened.
-    outputs:
-      - { name: concept_completed, from: "$.files" }
-
-  # 3b. OKF cross-references (brownfield seed). The reversed design.md now names this
-  #     slice's cross-aggregate references (§1 References-by-id) + integration contracts
-  #     (its External integrations table, IC-); record them into the shared OKF bundle — a
-  #     Cross-References row in every
-  #     SIBLING aggregate this slice uses (their inventory concepts already exist, so this
-  #     resolves them rather than stubbing), plus this slice's own Depends-On. Same
-  #     reconcile-on-write helper as forward implement, stamped origin reverse-engineered,
-  #     additive to the inventory bundle. Runs only after fidelity passes.
-  - id: xref_record
-    action: execute_script
-    script: { ref: xref }
-    subcommand: record
-    args: ["--using", "{{feature_name}}", "--design", "{{design_doc}}", "--bundle", "{{bundle_dir}}", "--origin", "reverse-engineered"]
-    outputs:
-      - { name: xref_wrote,      from: "$.wrote" }
-      - { name: xref_edge_count, from: "$.edge_count" }
-
-  # ═══════════ GOVERNANCE RECONCILE — upgrade onboard's PROVISIONAL scaffold ═══
-  # ⏸ HELD 2026-07-29: every step in this block is gated on `reconcile_governance`
-  #   (default "false"), so adopt currently does NOT touch the constitution halves
-  #   or the docs/domainspecs/<domain>/ rule pack — onboard's provisional scaffold
-  #   is left as-is. Flip the var to "true" (workflow vars) to restore the behaviour.
-  # Now that this feature is reversed to a TRUSTWORTHY spec (real BR-/CN-/DC-/IC- ids)
-  # + design (real code coordinates), reconcile that evidence INTO the governance
-  # onboard established. RECONCILE, NOT re-author: fill provisional entries with this
-  # feature's real ids; NEVER rewrite the project's principle set or another feature's
-  # evidence. Runs only after fidelity passes (governance derived from trustworthy docs).
-  # setup-constitution is idempotent (returns the paths without clobbering onboard's
-  # content). compose-constitution re-renders the human view.
-  - id: setup_constitution
-    condition: "{{reconcile_governance}} == true"   # HELD — governance reconcile paused (see vars)
-    action: execute_script
-    script: { ref: actions }
-    subcommand: setup-constitution
-    outputs:
-      - { name: constitution_technical_file, from: "$.constitution_technical_file" }
-      - { name: constitution_domain_file,    from: "$.constitution_domain_file" }
-
-  # RECONCILE the domain rule-file pack with THIS feature's real ids.
-  - id: ctx_reconcile_pack
-    condition: "{{reconcile_governance}} == true"   # HELD — governance reconcile paused (see vars)
-    action: build_context
-    context:
-      - { path: "{{spec_file}}" }                                          # the feature's real BR-/CN-/DC-/IC-
-      - { path: "{{design_doc}}" }
-      - { path: "{{feature_dir}}/source-map.md" }
-      - { path: "docs/domainspecs/{{gov_domain}}/comandrulemap.md", optional: true }
-      - { path: .aw-spec/RULE-PARTITION.md }                                       # the rule-partition authority (which command reads what)
-  - id: reconcile_pack
-    condition: "{{reconcile_governance}} == true"   # HELD — governance reconcile paused (see vars)
-    action: agent_generate
-    tools: "Read,Write,Edit"
-    permission_mode: acceptEdits
-    task: |
-      RECONCILE the domain rule-file pack docs/domainspecs/{{gov_domain}}/ with the
-      newly-adopted feature '{{feature_name}}'. onboard authored these rule files from the
-      whole-repo scan with per-feature specifics marked `PROVISIONAL — reconciled at
-      adopt`. READ this feature's reversed spec.md + design.md + source-map.md (in
-      context — the real evidence) and the EXISTING pack files under
-      docs/domainspecs/{{gov_domain}}/.
-
-      RECONCILE, do NOT re-author:
-      - UPGRADE the provisional entries this feature now evidences: replace a
-        `PROVISIONAL` placeholder with the concrete rule, CITING the feature's real spec
-        ids (BR-/CN-/DC-/IC-/FR-). Leave provisional entries this feature does NOT touch
-        as they are — a later adopt reconciles them.
-      - ADD a `<concern>.domain.md` rule file ONLY if this feature evidences a concern the
-        pack has none for, and wire it into comandrulemap.md under the correct partition
-        heading. If a rule file already covers the concern, MERGE this feature's evidence
-        into it — do NOT duplicate.
-      - Do NOT rewrite the pack, re-scope it to this one aggregate, or remove another
-        feature's evidence. The pack stays PROJECT-level; this feature is new evidence in it.
-      - Preserve the RULE PARTITION in comandrulemap.md (constitution / specify / gate get
-        the domain files; design / implement get None). Keep each file's frontmatter and
-        note in `generated_by` that adopt reconciled '{{feature_name}}'.
-      Write ONLY inside docs/domainspecs/{{gov_domain}}/. Report the files changed/added.
-    outputs:
-      - { name: pack_reconciled, from: "$.files" }
-
-  # RECONCILE the TECHNICAL constitution: ground provisional principles in this feature's
-  # real CODE COORDINATES (from the source-map). Domain-free.
-  - id: ctx_reconcile_technical
-    condition: "{{reconcile_governance}} == true"   # HELD — governance reconcile paused (see vars)
-    action: build_context
-    context:
-      - { path: "{{constitution_technical_file}}" }
-      - { path: "{{design_doc}}" }
-      - { path: "{{feature_dir}}/source-map.md" }
-  - id: reconcile_technical
-    condition: "{{reconcile_governance}} == true"   # HELD — governance reconcile paused (see vars)
-    action: agent_author
-    include_standards: false
-    output_target: { type: file, path: "{{constitution_technical_file}}" }
-    task: |
-      RECONCILE the TECHNICAL constitution (target in context) with the adopted feature
-      '{{feature_name}}'. onboard discovered the technology principle SET from the scan and
-      marked per-feature code coordinates `PROVISIONAL`. READ this feature's design.md +
-      source-map.md (in context — the code-coordinate bridge: real file paths / type names).
-
-      RECONCILE, do NOT re-author:
-      - Where a principle is PROVISIONAL and THIS feature's code now evidences it, replace
-        the placeholder with the real CODE COORDINATE (file path / type name from the
-        source-map) — keep the principle's wording; just ground it.
-      - Do NOT change the principle SET, re-number, or re-scope the constitution to this
-        aggregate. Add a NEW technology principle ONLY if this feature reveals a project-
-        level technology trait onboard genuinely missed (cite the code coordinate) — rare.
-      - Ignore the source-map's domain spec-ids / entity semantics (those belong to the
-        domain half). Stay domain-agnostic.
-      - Bump CONSTITUTION_VERSION by semver; prepend a one-line note to the Sync Impact
-        Report ("reconciled from adopt {{feature_name}}: <principles grounded>"). Preserve
-        heading hierarchy + every other principle. ISO YYYY-MM-DD dates.
-      Return the complete updated technical constitution content only.
-  - id: reconcile_technical_lint
-    condition: "{{reconcile_governance}} == true"   # HELD — governance reconcile paused (see vars)
-    action: loop
-    while: "{{technical_ok}} != true"
-    max_iterations: 3
-    steps:
-      - id: rt_lint
-        action: execute_script
-        script: { ref: actions }
-        subcommand: constitution-verify
-        args: ["--file", "{{constitution_technical_file}}"]
-        outputs:
-          - { name: technical_ok,     from: "$.ok" }
-          - { name: technical_issues, from: "$.issues" }
-      - id: rt_break
-        action: break
-        condition: "{{technical_ok}} == true"
-      - id: rt_patch
-        action: agent_author
-        context: ["{{constitution_technical_file}}"]
-        include_standards: false
-        output_target: { type: file, path: "{{constitution_technical_file}}" }
-        task: |
-          Fix these mechanical defects in the technical constitution (target in context),
-          changing NOTHING else — preserve every principle, the heading hierarchy, and the
-          Sync Impact Report. Fill any listed [ALL_CAPS] placeholder (or a justified
-          TODO(<FIELD>): reason); make the body version AGREE with the Sync Impact Report;
-          ISO YYYY-MM-DD dates. Defects: {{technical_issues}}
-          Return the complete updated technical constitution content only.
-
-  # RECONCILE the DOMAIN constitution: ground provisional domain principles in this
-  # feature's real spec ids; CONTINUE (do not renumber) the technical numbering.
-  - id: ctx_reconcile_domain
-    condition: "{{reconcile_governance}} == true"   # HELD — governance reconcile paused (see vars)
-    action: build_context
-    context:
-      - { path: "{{constitution_domain_file}}" }
-      - { path: "{{constitution_technical_file}}" }
-      - { path: "{{spec_file}}" }
-      - { path: "docs/domainspecs/{{gov_domain}}/comandrulemap.md", optional: true }
-  - id: reconcile_domain
-    condition: "{{reconcile_governance}} == true"   # HELD — governance reconcile paused (see vars)
-    action: agent_author
-    include_standards: false
-    output_target: { type: file, path: "{{constitution_domain_file}}" }
-    task: |
-      RECONCILE the DOMAIN addenda constitution (target in context) with the adopted
-      feature '{{feature_name}}'. onboard authored the domain principles from the scan and
-      marked per-feature specifics `PROVISIONAL`. READ this feature's spec.md (in context
-      — real BR-/CN-/DC-/IC- + ubiquitous language) + the reconciled pack (comandrulemap).
-
-      RECONCILE, do NOT re-author:
-      - Where a domain principle is PROVISIONAL and this feature evidences it, ground it in
-        the feature's real spec ids — keep the principle TITLED by DOMAIN CONCERN (not the
-        aggregate name), so it still holds when a later feature enters the same context.
-      - Do NOT re-number or re-scope to this aggregate. Continue the technical half's
-        numbering (read constitution.technical.md for its last numeral). Add a NEW domain
-        principle ONLY if this feature reveals a project-level domain concern onboard missed.
-      - Bump CONSTITUTION_VERSION by semver; prepend a one-line Sync Impact Report note
-        ("reconciled from adopt {{feature_name}}"). Preserve heading hierarchy + other
-        principles. NO residual [BRACKET] token may remain. ISO YYYY-MM-DD dates.
-      Return the complete updated domain addenda content only.
-  - id: reconcile_domain_lint
-    condition: "{{reconcile_governance}} == true"   # HELD — governance reconcile paused (see vars)
-    action: loop
-    while: "{{domain_ok}} != true"
-    max_iterations: 3
-    steps:
-      - id: rd_lint
-        action: execute_script
-        script: { ref: actions }
-        subcommand: constitution-verify
-        args: ["--file", "{{constitution_domain_file}}"]
-        outputs:
-          - { name: domain_ok,     from: "$.ok" }
-          - { name: domain_issues, from: "$.issues" }
-      - id: rd_break
-        action: break
-        condition: "{{domain_ok}} == true"
-      - id: rd_patch
-        action: agent_author
-        context: ["{{constitution_domain_file}}"]
-        include_standards: false
-        output_target: { type: file, path: "{{constitution_domain_file}}" }
-        task: |
-          Fix these mechanical defects in the domain addenda constitution (target in
-          context), changing NOTHING else — preserve every principle, the heading
-          hierarchy, and the Sync Impact Report. Fill any listed [ALL_CAPS] placeholder
-          (or a justified TODO(<FIELD>): reason); make the body version AGREE with the
-          Sync Impact Report; ISO YYYY-MM-DD dates. Defects: {{domain_issues}}
-          Return the complete updated domain addenda content only.
-
-  - id: recompose_constitution
-    condition: "{{reconcile_governance}} == true"   # HELD — governance reconcile paused (see vars)
-    action: execute_script
-    script: { ref: actions }
-    subcommand: compose-constitution
-    outputs:
-      - { name: composed_file, from: "$.composed_file" }
-
-  # 4. Post-execution hooks.
-  - id: resolve_post_hooks
-    action: execute_script
-    script: { ref: actions }
-    subcommand: resolve-hooks
-    args: ["--phase", "after_adopt"]
-    outputs:
-      - { name: after_hooks, from: "$.hooks" }
-  - id: dispatch_post_hooks
-    action: dispatch_hooks
-    hooks_from_variable: after_hooks
-
-outputs:
-  feature_dir: "{{feature_dir}}"
-  spec_file: "{{spec_file}}"
-  design_doc: "{{design_doc}}"
-  source_map: "{{feature_dir}}/source-map.md"
-  aggregate: "{{feature_name}}"
-  source_count: "{{source_count}}"
-  review_items: "{{review_items}}"
-  concept_completed: "{{concept_completed}}"
-  xref_edge_count: "{{xref_edge_count}}"
-  gov_domain: "{{gov_domain}}"
-  pack_reconciled: "{{pack_reconciled}}"
-  composed_file: "{{composed_file}}"
-  technical_reconcile_ok: "{{technical_ok}}"
-  domain_reconcile_ok: "{{domain_ok}}"
-  next: "Adopted {{feature_name}} (spec.md + design.md + source-map.md, v1.0) and COMPLETED its OKF concept (deepened + linked the deep artifacts; {{xref_edge_count}} cross-slice edge(s) recorded). NOTE — governance reconcile is currently HELD (reconcile_governance=false): this run did NOT modify the constitution halves or the docs/domainspecs/{{gov_domain}}/ rule pack, so they keep onboard's provisional scaffold. Close any items in specs/{{feature_name}}/adopt-review-report.md out of band. The slice is now a NORMAL feature: refine via /aw-spec-orch analyze-design, then drive every change through the CR delta loop (/aw-spec-orch specify → design → analyze-delta-design → implement-delta → build → finalize-delta → analyze-slice → close-delta). If a change edits untested legacy behaviour with blast radius, characterize just that surface first (optional on-touch fence). To restore governance reconcile, set reconcile_governance to \"true\" in the workflow vars."