aw-spec-cli 0.1.7 → 0.1.9

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

@@ -0,0 +1,934 @@
+# =============================================================================
+# 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
+# /appweaver 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 (/appweaver 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) — ⏸ HELD, OFF BY DEFAULT.
+# onboard established the PROJECT constitution + guardrails/projects/<project>/ rule set
+# from the whole-repo SCAN, with per-feature specifics marked PROVISIONAL. The reconcile
+# block below carries 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.
+# Every step of it is gated on `reconcile_governance` (vars, default "false"), so an
+# ordinary adopt run leaves the constitution halves and the rule set exactly as onboard
+# wrote them. What adopt ALWAYS does is the per-feature reverse (spec + design +
+# source-map) and the OKF concept completion; flip the var to "true" to add the
+# governance reconcile back.
+#
+# 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>/, .appweaver/memory/constitution*.md, and guardrails/projects/<project>/.
+# 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:  /appweaver adopt [strategy]         # adopt the ACTIVE feature (set by select-feature)
+#          /appweaver adopt [strategy] <Feature>   # or name it directly (also selects it)
+#   e.g.   /appweaver adopt MedicinalProduct
+# Prereq:  /appweaver onboard  (the feature map names this feature + the governance
+#          scaffold adopt reconciles into), then /appweaver 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 (+ design.ui.md where a frontend lane is declared and this slice owns part of its surface) + source-map.md (origin reverse-engineered, per-item confidence, code-derived design template), then COMPLETE its shallow OKF concept (deepen it to the reversed reality + link the deep artifacts) and record its cross-slice edges. Fidelity gate is spec/design vs code; the review is reported for out-of-band closure. The governance reconcile — carrying this feature's real evidence into the provisional rule files + constitution onboard wrote — is HELD (reconcile_governance=false), so an ordinary run does not touch the governance tier. 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
+#         .appweaver/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 /appweaver select-feature (.appweaver/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:  .appweaver/scripts/bash/aw-inventory.sh
+    ps1: .appweaver/scripts/powershell/aw-inventory.ps1
+  actions:
+    sh:  .appweaver/scripts/bash/aw-spec-actions.sh
+    ps1: .appweaver/scripts/powershell/aw-spec-actions.ps1
+  xref:
+    sh:  .appweaver/scripts/bash/aw-xref.sh
+    ps1: .appweaver/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
+# guardrails/projects/<project>/tech-rule-bindings.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 takes its domain frame from constitution.domain.md 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: .appweaver/ai-rules.md }   # kit-resident: the universal operating rules, every flow
+
+vars:
+  bundle_dir: "knowledge"      # where /appweaver 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"
+  fe_declared: "false"         # lane_readback runs on_error:continue, so both its bindings need a declared default
+  fe_root: ""
+  ui_lane: "false"             # THIS slice reverses a UI half: a frontend lane is declared AND the slice owns UI files
+  ui_count: "0"                # how many UI files the concept attributes to this aggregate (aw-inventory ui_source_files)
+  ui_source_files: ""
+  ui_design_doc: ""
+  ui_tpl_source: ""
+  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-set) 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-set 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 guardrails/projects/<project>/tech-rule-bindings.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: .appweaver/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) `/appweaver adopt <Feature>` — the explicit arg selects directly.
+  #    b) `/appweaver adopt` (no arg) — CONSUME the feature select-feature already
+  #       made active (.appweaver/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 /appweaver select-feature first (pick the aggregate from the onboard feature map), then /appweaver adopt; or name it directly: /appweaver 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 (/appweaver 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" }
+      # The slice's FRONTEND surface, listed apart from source_files so each lane's
+      # reverse step reads its own code. Empty on a backend-only slice.
+      - { name: ui_source_files, from: "$.ui_source_files" }
+      - { name: ui_count,        from: "$.ui_count" }
+
+  # 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 /appweaver 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 (/appweaver specify → design → implement), which onboard already made brownfield-ready."
+
+  # Governance prerequisite: the reverse steps below are authored AGAINST the project
+  # onboard established (the constitution halves + guardrails/projects/<project>/ rule set).
+  # Resolve the active domain now and require its rule map to exist — without it there is
+  # no code-derived rule set for tech_select to load, no domain frame for the reversed
+  # spec, and nothing for the reconcile block to upgrade when it is enabled. 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 for adopt to work against — run /appweaver onboard first. onboard establishes the PROJECT constitution + guardrails/projects/<project>/ rule set (provisional-from-scan) and activates it. Reversing '{{feature_name}}' without that scaffold would author the spec and design against no code-derived rules at all, and leave them with 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 /appweaver 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}}"]
+
+  # 2b. DOES THIS SLICE HAVE A UI HALF? Two conditions, and both are necessary.
+  #     A frontend lane must be DECLARED (stacks.json — select-stack is its sole
+  #     writer, and onboard authored the lane's governance off the same declaration),
+  #     and THIS aggregate must actually own UI files (the concept's ui_source_files,
+  #     attributed by the scan). A declared lane whose surface this slice does not
+  #     touch reverses a service half only — a shared-kernel or job-only slice in a
+  #     repo that has a UI is the ordinary case, not an omission.
+  #     The engine has no compound conditions, so this is three ordered sets: off,
+  #     on where the lane is declared, off again where this slice has no surface.
+  - id: lane_readback
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: lane-resolve
+    outputs:
+      - { name: fe_declared, from: "$.frontend_declared" }
+      - { name: fe_root,     from: "$.frontend_root" }
+  - id: ui_lane_off
+    action: set
+    vars: { ui_lane: "false" }
+  - id: ui_lane_on
+    action: set
+    condition: "{{fe_declared}}"
+    vars: { ui_lane: "true" }
+  - id: ui_lane_no_surface
+    action: set
+    condition: "{{ui_count}} == 0"
+    vars: { ui_lane: "false" }
+
+  # Scaffold the LANE's design doc from ITS template pair (--lane ui resolves
+  # ui-design-template -> design.ui.md), the twin of scaffold_design above. onboard
+  # GENERATED that override from this repo's own UI source, so the reversed UI design
+  # follows the code's real composition axes rather than a fixed screen taxonomy.
+  - id: scaffold_ui_design
+    condition: "{{ui_lane}} == true"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: design-scaffold
+    args: ["--feature-dir", "{{feature_dir}}", "--lane", "ui"]
+    outputs:
+      - { name: ui_design_doc, from: "$.design_doc" }
+      - { name: ui_tpl_source, from: "$.template_source" }
+      - { name: ui_tpl_override, from: "$.override_active" }
+
+  # A reverse needs the CODE-DERIVED template, not any template. The kit ships a
+  # greenfield ui-design-template for the forward `design-ui` phase, so the template
+  # always resolves and its presence proves nothing — override_active is the signal
+  # that asks the real question: did onboard generate this repo's own UI structure?
+  # Without it the lane was declared after onboard ran, so the UI governance this
+  # reverse authors against does not exist yet, and the greenfield section list would
+  # impose a screen taxonomy on code that has its own. Stop instead, the same call
+  # onboard's own verify_ui_design_template makes.
+  - id: require_ui_template
+    condition: "{{ui_lane}} == true"
+    action: verify_context
+    require_true: ui_tpl_override
+    on_false: stop
+    on_false_message: "A frontend lane is declared ({{fe_root}}) and '{{feature_name}}' owns {{ui_count}} UI file(s), but no CODE-DERIVED UI design template is installed at .appweaver/templates/overrides/ui-design-template.md — only the kit's greenfield template, which would impose a section structure this app's UI did not choose. onboard GENERATES the override from the UI source — declare the lane with /appweaver select-stack and re-run /appweaver onboard, then adopt this feature again."
+
+  # 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, in the template's vocabulary ══════
+  # The bundle concept is the INDEX (source_files, seam, open_questions); the
+  # CODE is the source of truth. The scaffolded template carries the modelling
+  # vocabulary itself — Aggregate Boundary, Key Entities, Business Rules — already
+  # technology-agnostic, so nothing further is needed to classify what the code
+  # shows. NO modelling rule file is loaded: a prescriptive one states what code
+  # OUGHT to be, and this step's oracle is what it IS. A legacy slice that is
+  # anemic, or models nothing at all, must reverse as exactly that. The two
+  # constitution halves it DOES load pass that same test: onboard reversed both
+  # out of THIS code, so they describe the repo rather than prescribe to it.
+  - id: ctx_reverse_spec
+    action: build_context
+    context:
+      - { path: "{{spec_file}}" }                 # the scaffolded template = section structure + the modelling vocabulary
+      - { path: "{{concept_path}}" }              # the OKF concept: source_files, seam, open_questions
+      - { path: .appweaver/memory/constitution.domain.md, optional: true }     # the domain frame
+      - { path: .appweaver/memory/constitution.ui.md, optional: true }         # the frontend lane's UX-* base — absent on a backend-only repo, which onboard leaves unwritten by design
+  - id: reverse_spec
+    action: agent_author
+    include_standards: false                       # the technical/arch sticky set is for design, never the spec
+    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).
+      - MODEL IN THE TEMPLATE'S OWN VOCABULARY: a ubiquitous language, the
+        aggregate + its root, entities vs value objects, aggregate-owned
+        invariants — as domain MODEL, never as the language's own types.
+        Classify from what the code EXHIBITS. A distinction the code does not
+        draw is not a gap to fill in: record the model as-built, however thin.
+      - 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.
+      - EXPERIENCE LIFT — only where this slice HAS a UI. Fill Experience Scope from
+        the surface the code exposes (UI actors, channels, and the device / browser /
+        assistive-technology floors the UI source actually targets), and lift the
+        project-wide standards that UI already holds into Experience Standards (UX-n),
+        citing constitution.ui.md's UX-* principle (in context where a lane exists) and
+        the source file. A UX-n is checkable on ANY surface — accessibility, interaction
+        states, content, journey integrity, responsiveness-as-a-limit — never a screen,
+        page, layout or component; a per-story behaviour stays FR-, a bound the SERVICE
+        meets stays CN-. Lift only what the UI code EXHIBITS: an unevidenced UX- is a
+        fabricated spec id and the fidelity gate scores it as one. No UI in this slice
+        (or no constitution.ui.md): "None (as of v1.0)" in BOTH sections — never delete
+        either.
+      - 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: .appweaver/DESIGN-FORMAT.md }        # the HLD contract (see its Brownfield variant note)
+      - { path: "{{bundle_dir}}/architecture/overview.md", optional: true } # the as-built architecture (inventory) — cite, don't re-derive
+      - { path: .appweaver/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}}
+
+  # ═══════ REVERSE UI DESIGN — the LANE's half, from the UI code, AS-BUILT ═══
+  # Runs only where this slice HAS a surface (ui_lane). The service design above is
+  # NOT its parent: design.md realises the spec's FR/BR/CN-, design.ui.md realises the
+  # spec's UX- and the user stories' interaction, and it CONSUMES design.md's contracts
+  # rather than restating them. Both are in context for exactly that reason.
+  - id: ctx_reverse_ui_design
+    condition: "{{ui_lane}} == true"
+    action: build_context
+    context:
+      - { path: "{{ui_design_doc}}" }             # the scaffolded code-derived lane template = structure + embedded guidance
+      - { path: "{{spec_file}}" }                 # the reversed spec — UX- + the user stories this surface serves
+      - { path: "{{design_doc}}" }                # the service design — the contracts the UI consumes, never re-specified here
+      - { path: .appweaver/memory/constitution.ui.md, optional: true }              # the lane's UX-* base, reversed by onboard from this same UI
+      - { path: "{{bundle_dir}}/architecture/frontend.md", optional: true }       # the as-built UI architecture + the SHARED surface no slice owns
+  - id: reverse_ui_design
+    condition: "{{ui_lane}} == true"
+    action: agent_author
+    include_standards: true                        # the lane's sticky technical set (reference only — the CODE wins)
+    output_target: { type: file, path: "{{ui_design_doc}}" }
+    task: |
+      Reverse-engineer the FRONTEND LANE's high-level design (the target design.ui.md
+      in context — it is this project's code-derived UI design template) for the
+      aggregate '{{feature_name}}', FROM ITS UI CODE. Fill the template; preserve its
+      section order.
+
+      THE UI CODE IS THE SOURCE OF TRUTH — describe the surface AS-BUILT, quirks
+      included. The standards in context are a vocabulary to NAME what you find, never
+      a target to bend it toward. An inconsistent app is recorded as inconsistent; a
+      surface with no loading states is recorded as having none, NEVER as needing them.
+      Rules:
+      - STAY IN THE LANE. Realise the spec's Experience Standards (UX-) and the
+        interaction its User Stories imply. The service design (in context) supplies
+        the CONTRACTS this surface consumes — cite them; do NOT restate, re-derive or
+        contradict them, and introduce no server-side behaviour here.
+      - STRUCTURE FOLLOWS THE UI CODE. Fill each section from the lane's real shape —
+        its actual routes and screens, its own composition axes (however it groups
+        components), where client state and server data-fetching really live, its
+        styling and any design-system in use. A section the slice genuinely has
+        nothing for says so and says why; do not invent a screen the code lacks.
+      - §7 TRACEABILITY IS THE SPINE: a row for every UX- this surface realises and
+        every US- it serves. A UX- in the spec with NO home here is a gap — record it
+        as a deviation (WA-n), never a fabricated screen. An element with no spec
+        basis is drift: surface it and log a DA-n.
+      - The SHARED surface (app shell, layout, design system, global styles) belongs to
+        no slice — it is recorded in the bundle's architecture/frontend.md (in context
+        where it exists). CITE it; do not copy it in and do not claim it here.
+      - Add `origin: reverse-engineered` near the Version field. This is v1.0.
+      - Conceptual only — component/state/route CONTRACTS and their shapes, NEVER
+        language code, and no complete component anywhere.
+
+      UI source files to read (this slice's surface): {{ui_source_files}}
+
+  # ═══════════════ SOURCE MAP — the source anchor sidecar ════════════════════
+  - id: ctx_source_map
+    action: build_context
+    context:
+      - { path: .appweaver/templates/source-map-template.md }   # the sidecar structure
+      - { path: "{{spec_file}}" }
+      - { path: "{{design_doc}}" }
+      - { path: "{{ui_design_doc}}", optional: true }   # the lane's design, where this slice has one
+      - { path: "{{concept_path}}" }              # both file lists 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.
+      - Where this slice has a UI half, its files map the same way, to the UX-/US-
+        they realise and the design.ui.md section (§/name) that describes them —
+        one spine, both lanes. UI files to map: {{ui_source_files}}
+      - 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}}"
+      - { path: "{{ui_design_doc}}", optional: true }   # the lane's design, where this slice has one
+      - "{{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 — do the reversed documents 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}}). Where design.ui.md is in context, it is judged the same way
+      against the slice's UI files ({{ui_source_files}}) — a screen, state store or
+      route it describes that the UI code does not have is a fabricated-design, and a
+      UI file with no home in the source-map is unmapped-code. 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 /appweaver 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 /appweaver 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 set) 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: .appweaver/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 guardrails/projects/<project>/ rule set — 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 set 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: "guardrails/projects/{{gov_domain}}/domain-rule-bindings.md", optional: true }
+      - { path: .appweaver/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 set in guardrails/projects/{{gov_domain}}/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 rule files under
+      guardrails/projects/{{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
+        the set has none for, and wire it into domain-rule-bindings.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 set, re-scope it to this one aggregate, or remove another
+        feature's evidence. The set stays PROJECT-level; this feature is new evidence in it.
+      - Preserve the RULE PARTITION in domain-rule-bindings.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 guardrails/projects/{{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: "guardrails/projects/{{gov_domain}}/domain-rule-bindings.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 set (domain-rule-bindings).
+
+      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}}"
+  ui_design_doc: "{{ui_design_doc}}"   # empty where this slice has no UI half
+  ui_lane: "{{ui_lane}}"
+  ui_count: "{{ui_count}}"
+  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). UI HALF: ui_lane={{ui_lane}} — where it is true this slice also has design.ui.md, reversed from the {{ui_count}} UI file(s) the feature map attributes to it; where it is false the repo declared no frontend lane, or this aggregate owns no part of its surface, and a service-only adoption is the correct outcome rather than a gap. The SHARED UI surface (app shell, layout, design system) belongs to no slice and stays in {{bundle_dir}}/architecture/frontend.md. NOTE — governance reconcile is currently HELD (reconcile_governance=false): this run did NOT modify the constitution halves or the guardrails/projects/{{gov_domain}}/ rule set, 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 /appweaver analyze-design, then drive every change through the CR delta loop (/appweaver 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."