aw-spec-cli 0.1.14 → 0.1.16

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

@@ -1,27 +1,67 @@
 # =============================================================================
-# aw-spec-analyze-design (orchestrator) — the spec↔design conformance GATE
+# aw-spec-analyze-design (orchestrator) — the spec ↔ FEATURE PLAN conformance GATE
 #
-# The single, discrete conformance gate on the forward path:
-#   specify → design → analyze-design → implement.
-# spec.md is the ANCHOR. Confirm design.md STRICTLY follows the spec (+ the domain
-# gate overlays as a backstop); on drift, REPORT the gaps and ASK whether to repair,
-# then UPDATE design.md to conform (spec wins). Design AUTHORS; this stage VALIDATES.
+# The discrete conformance gate on the forward path:
+#   specify / sync-spec → plan (+ plan-ui) → ANALYZE-DESIGN → sync-stories → story-plan
+# spec.md is the ANCHOR. This stage proves that the feature's PLAN DOCUMENTS —
+# specs/<Aggregate>/backend-plan.md and, where a frontend lane is declared,
+# specs/<Aggregate>/frontend-plan.md — strictly follow it, in BOTH directions: every
+# spec id has a design home, and every design element has a spec reason.
 #
-# BOOTSTRAP-ONLY, and it NEVER opens, merges or closes a change. It gates a feature
-# whose spec.md + design.md ARE the masters. With a change OPEN the delta docs are the
-# authoritative in-flight edit and the master pair must not be rewritten under them, so
-# the run STOPS and routes to /appweaver analyze-delta-design (the delta's own gate).
-# The change is closed by close-delta, the SINGLE cr-archive caller, and only after
-# finalize-delta has merged the delta into the masters. Also runnable on demand to
-# re-anchor a hand-edited spec — again, only when no change is open.
+# LOAD-BEARING, not advisory. story-plan reads backend-plan.md as BINDING feature
+# architecture and implement generates from the story pass beneath it, so a plan that
+# drifted from the spec propagates into code through documents that never re-ask the
+# question. This is the only stage that asks it — and it writes a machine-readable
+# verdict (plan-analyze-report.json) beside the human report, so a pipeline can branch
+# on the answer instead of parsing prose (§7 of Workflow-To-Build.md).
+#
+# ONE COMMAND, BOTH LANES — deliberately, unlike plan / plan-ui. Those split because
+# each lane's AUTHORING rules are a different set (tech-rule-bindings gives each its
+# own, and one command would hand the phase both lanes' whole rule surface). This stage
+# loads no lane rule set at all: its checklist is the DOMAIN gate overlay, which is
+# lane-neutral. And the question it exists to answer is a UNION question that neither
+# lane can answer alone — a UX- has its only home in frontend-plan.md, a BR- only in
+# backend-plan.md, and an FR- with a user-facing surface needs BOTH. Gating one lane at
+# a time would either miss every UX- or report every UI-bearing FR- as uncovered in the
+# service lane. There is no /appweaver analyze-design-ui, and there will not be one.
+#
+# IT DOES NOT AUTHOR, AND IT DOES NOT SCAFFOLD. Each feature plan has exactly ONE
+# author (/appweaver plan, /appweaver plan-ui). This stage never creates the document
+# it gates: an empty template conjured here would be measured against the spec, found
+# wholly non-conformant, and then written by the gate — authoring under another name,
+# with none of the author's lane rules, code reading or interface publication. A
+# declared lane with no plan STOPS and routes to that lane's author.
+#
+# FRESHNESS FIRST. A plan is conformant to the spec version it DERIVES FROM; certifying
+# one the spec has moved past is a false green, because it conforms to a contract that
+# no longer holds. plan-check runs per lane and the run STOPS on `behind` /
+# `edited_behind`, routing to plan / plan-ui — whose update mode conforms exactly the
+# ids the ledger moved and appends the plan's own history row. `untracked` (a migrated
+# legacy master with no baseline) is ADMITTED: the whole document is analysed against
+# the whole spec, and the stamp establishes the baseline that was missing.
+#
+# REPAIR IS BOUNDED AND RECORDED. On approval the gate closes the gaps it found and
+# nothing else — no new design, no version, no id. plan-stamp then appends the plan's
+# own Change History row naming the ids and re-baselines the body hash, so the rewrite
+# is IN the ledger and story-plan does not later read it as an unexplained hand edit.
+# The verdict records the gaps AS FOUND alongside the final status, so a green earned
+# by repair stays visible as one.
+#
+# ROUTES OUT, by what the gap actually is:
+#   • the plan lags what the ledger moved      → /appweaver plan  ·  /appweaver plan-ui
+#   • the plan is wrong and the spec is right  → repair here, or hand-edit the plan and
+#                                                re-run plan with accept_manual: true
+#   • the SPEC is wrong                        → /appweaver sync-spec (⌛ not yet built — until it is, fold the change back by hand under .appweaver/SPEC-EDIT-PROTOCOL.md)  (never repaired here)
+#   • a gate-overlay constraint was never lifted into the spec (LIFT-FAILURE:)
+#                                              → /appweaver specify
 #
 # Launch:  /appweaver analyze-design [strategy]
-# Prereq:  /appweaver design   (a spec.md + design.md for the active feature).
+# Prereq:  /appweaver plan  (and /appweaver plan-ui where a frontend lane is declared).
 # =============================================================================
 
 name: aw-spec-analyze-design
-description: The spec↔design conformance gate — confirm design.md conforms to spec.md (spec is the anchor; domain overlays are a backstop) and, with approval, repair it. Bootstrap-only — with a change open it stops and routes to analyze-delta-design; it never closes a change.
-version: 2.1.0
+description: The spec ↔ feature-plan conformance gate, both lanes in one pass — proves backend-plan.md and frontend-plan.md strictly follow spec.md in both directions (every spec id has a design home; every design element has a spec reason), with the domain gate overlays as a lift backstop. Checks each lane's derivation freshness first and refuses to certify a plan the spec has moved past, routing to plan / plan-ui. Never scaffolds the document it gates. On approval it repairs only the gaps it found and plan-stamp records the repair in the plan's own ledger. Writes a two-directional markdown report and a machine-readable verdict beside it for CI.
+version: 3.0.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -34,15 +74,91 @@ standards:
   - { path: .appweaver/ai-rules.md }   # kit-resident: the universal operating rules, every flow
 
 vars:
+  # --- lane scope ---------------------------------------------------------
+  be_declared: "false"
+  fe_declared: "false"
+  be_in_scope: "false"          # a backend lane is declared ⇒ backend-plan.md is gated
+  fe_in_scope: "false"          # a frontend lane is declared ⇒ frontend-plan.md is gated
+  have_lane: "false"            # at least one lane in scope — false ⇒ nothing to gate
+  # --- per-lane derivation tracking (plan-check) --------------------------
+  be_state: ""                  # fresh | untracked | clean | behind | edited | edited_behind
+  be_derived: ""
+  be_changed: ""
+  fe_state: ""
+  fe_derived: ""
+  fe_changed: ""
+  # The plan shapes this run certifies, re-read after any repair (step 8b). Empty means the
+  # lane was not in scope, which every reader treats as "not certified", never as a mismatch.
+  be_final_sha: ""
+  fe_final_sha: ""
+  current_version: ""
+  # Freshness gates default FALSE so a probe that could not run fails CLOSED. The
+  # message vars carry a generic default for the same reason — an empty stop message
+  # would leave the user with a refusal and no route.
+  be_gate_ok: "false"
+  fe_gate_ok: "false"
+  be_gate_msg: "The backend plan's derivation check did not complete, so this gate cannot tell whether backend-plan.md is current with the spec. Re-run /appweaver analyze-design; if it keeps failing, run /appweaver plan to re-derive and re-baseline the plan."
+  fe_gate_msg: "The frontend plan's derivation check did not complete, so this gate cannot tell whether frontend-plan.md is current with the spec. Re-run /appweaver analyze-design; if it keeps failing, run /appweaver plan-ui to re-derive and re-baseline the plan."
+  # --- the analysis -------------------------------------------------------
   analyze_ok: "false"
+  analyze_gaps: ""
+  gap_count: "0"                # gaps still open at the end of the loop
+  gap_refs: ""
+  be_needs_repair: "false"
+  fe_needs_repair: "false"
+  fe_repair_go: "false"         # fe_needs_repair AND the frontend lane is in scope
+  found_recorded: "false"       # the first pass's findings are the report's subject
+  found_gaps: ""
+  found_count: "0"
+  found_refs: ""
+  repaired: "false"
+  # The ids a repair pass actually rewrote — the model's own declaration, and NOT the same
+  # set as gap_refs (which holds every finding, including the ones left deliberately open).
+  repaired_refs: ""
+  be_stamp_ok: "true"           # vacuously true until a repair actually stamps
+  fe_stamp_ok: "true"
+  be_stamp_error: ""
+  fe_stamp_error: ""
+  report_path: ""
+  result_file: ""
+  # --- legacy delta guard -------------------------------------------------
   active_change: ""
   has_change: "false"
+  no_open_change: "true"        # NOT has_change ⇒ the masters are authoritative ⇒ this gate applies
   version: ""
-  no_open_change: "true"   # NOT has_change ⇒ the masters are authoritative ⇒ this gate applies
 
 workflow:
 
-  # 1. Resolve the current feature + its spec; require the spec (the anchor).
+  # 1. Which lanes exist. The DECLARATION is the question — not the lane-gate module,
+  #    whose on-disk check would refuse a greenfield project that declared a root it
+  #    has not scaffolded. A plan is gated as a document, before any code exists.
+  - id: lane_resolve
+    action: execute_script
+    on_error: continue      # never crash raw on an undeclared lane — the gates below explain it
+    script: { ref: actions }
+    subcommand: lane-resolve
+    outputs:
+      - { name: lanes_declared, from: "$.declared" }
+      - { name: be_declared,    from: "$.backend_declared" }
+      - { name: fe_declared,    from: "$.frontend_declared" }
+
+  - id: be_scope
+    condition: "{{be_declared}} == true"
+    action: set
+    vars: { be_in_scope: "true", have_lane: "true" }
+  - id: fe_scope
+    condition: "{{fe_declared}} == true"
+    action: set
+    vars: { fe_in_scope: "true", have_lane: "true" }
+  - id: require_lane
+    action: verify_context
+    require_true: have_lane
+    on_false: stop
+    on_false_message: "No lane is declared in .appweaver/stacks.json, so there is no plan document to gate. Run /appweaver select-stack to declare the stack(s) and their source paths, then /appweaver plan (and /appweaver plan-ui where there is a UI) before re-running analyze-design."
+
+  # 2. Resolve the current feature and require its spec — the anchor everything is
+  #    measured against. feature-paths reports both plan paths whether or not they
+  #    exist; the freshness gates below decide what that absence means.
   - id: feature_paths
     action: execute_script
     on_error: continue      # never crash raw on 'no feature set' — the gate below explains it
@@ -52,6 +168,8 @@ workflow:
       - { name: feature_dir, from: "$.feature_dir" }
       - { name: spec_file,   from: "$.spec_file" }
       - { name: spec_exists, from: "$.spec_exists" }
+      - { name: be_plan,     from: "$.backend_plan_file" }
+      - { name: fe_plan,     from: "$.frontend_plan_file" }
 
   - id: require_feature
     action: verify_context
@@ -63,10 +181,42 @@ workflow:
     action: verify_context
     require_true: spec_exists
     on_false: stop
-    on_false_message: "No spec.md for the current feature. Run /appweaver specify (and design) first."
+    on_false_message: "No spec.md for the current feature. Run /appweaver specify first — the spec is this gate's anchor, and there is nothing to measure a plan against without it."
+
+  - id: report_paths
+    action: set
+    vars: { report_path: "{{feature_dir}}/plan-analyze-report.md" }
+
+  # 2a. INVALIDATE any previous verdict, before anything downstream can stop. A gate
+  #     that writes its result only on completion leaves the LAST run's verdict on disk
+  #     for every run that aborts — a freshness stop, a refused stamp — and a pipeline
+  #     reading that file would act on a certification this run never made. Every exit
+  #     from here on therefore leaves at least a red; the real verdict overwrites it.
+  - id: gate_result_open
+    action: execute_script
+    # The lenient loader needs a flow sequence on ONE line.
+    args: ["--gate", "analyze-design", "--feature-dir", "{{feature_dir}}", "--ok", "false", "--report", "{{report_path}}", "--note", "analyze-design started and has not reached a verdict; a run that stops before certifying leaves this red on purpose"]
+    script: { ref: actions }
+    subcommand: gate-result
+    outputs:
+      - { name: result_file, from: "$.result_file" }
+
+  # 2b. The spec's own ledger tripwire, the same fence plan and plan-ui carry. This
+  #     gate compares each plan's derived version against the spec's ledger, so a spec
+  #     that moved OUTSIDE the ledger makes every one of those comparisons a lie: the
+  #     plans would be certified current against a version the spec no longer is.
+  - id: spec_guard
+    action: include
+    module: .appweaver/orchestrator/modules/spec-state-gate.orch.yaml
+    with: { command: "/appweaver analyze-design" }
 
-  # 1b. Read the open change (opened by specify, or by design on a design-only change).
-  #     has_change drives the BOOTSTRAP-ONLY guard below — it closes nothing.
+  # 2c. LEGACY GUARD. Nothing in the current model opens a change — specify writes the
+  #     spec directly and the delta family is retired (deletion scheduled). has_change
+  #     true therefore means a repo left mid-flight by that retired chain: delta-spec /
+  #     delta-design are still the authoritative in-flight edit, and repairing the
+  #     master plans under them would drift the masters out from beneath the delta
+  #     before finalize-delta merges it. Stop BEFORE any analysis so the wrong-stage run
+  #     has zero side effects.
   - id: read_change
     action: execute_script
     script: { ref: actions }
@@ -77,11 +227,6 @@ workflow:
       - { name: has_change,    from: "$.has_change" }
       - { name: version,       from: "$.version" }
 
-  # 1c. BOOTSTRAP-ONLY GUARD. A change open ⇒ delta-spec/delta-design are the
-  #     authoritative in-flight edit and this stage is the WRONG gate: its repair loop
-  #     rewrites the MASTER design.md, which would drift the masters out from under the
-  #     delta before finalize-delta merges it. Stop BEFORE any scaffold/authoring so the
-  #     wrong-stage run has zero side effects, and route to the delta's own gate.
   - id: flag_change_open
     condition: "{{has_change}} == true"
     action: set
@@ -91,22 +236,116 @@ workflow:
     action: verify_context
     require_true: no_open_change
     on_false: stop
-    on_false_message: "Change {{active_change}} is OPEN on this feature — analyze-design is the BOOTSTRAP gate and must not rewrite the master design.md while a delta is in flight. Gate the delta instead: /appweaver analyze-delta-design → implement-delta → build → finalize-delta (merges the delta into spec.md + design.md) → analyze-slice → close-delta (archives the change + bumps the version). Re-run analyze-design once the change is closed, to re-anchor the masters."
+    on_false_message: "Change {{active_change}} is still OPEN on this feature — a leftover from the retired delta chain. This gate must not repair the master plans while a delta is in flight beneath them. Finish that change (/appweaver analyze-delta-design → implement-delta → build → finalize-delta → analyze-slice → close-delta) or abandon it, then re-run analyze-design to re-anchor the masters against the current spec."
 
-  # 2. Ensure design.md exists (idempotent scaffold — returns the existing path, or
-  #    a fresh template the repair loop will author to conform to the spec).
-  - id: design_scaffold
+  # 3. Per-lane derivation freshness. plan-check reports `fresh` when the document does
+  #    not exist at all, which is how a declared-but-unplanned lane is caught here
+  #    rather than by a scaffold this stage deliberately does not perform.
+  - id: be_track
     action: execute_script
+    condition: "{{be_in_scope}} == true"
+    on_error: continue      # a probe that fails binds nothing; be_gate_ok stays false ⇒ fails CLOSED
     script: { ref: actions }
-    subcommand: design-scaffold
-    args: ["--feature-dir", "{{feature_dir}}"]
+    subcommand: plan-check
+    args: ["--doc", "{{be_plan}}", "--feature-dir", "{{feature_dir}}"]
     outputs:
-      - { name: design_doc, from: "$.design_doc" }
+      - { name: be_state,        from: "$.state" }
+      - { name: be_derived,      from: "$.derived_version" }
+      - { name: be_changed,      from: "$.changed_csv" }
+      - { name: current_version, from: "$.current_version" }
 
-  # 2b. Load the domain GATE overlays (the domain-rule-bindings `/aw-spec-gate` checklist) as
-  #     the conformance checklist — VALIDATION input only, NEVER authoring. The analyze
-  #     step sees them (include_standards: true); reconcile does NOT (design conforms to
-  #     the SPEC, not to the overlays). Empty/no-op for a non-domain project.
+  - id: fe_track
+    action: execute_script
+    condition: "{{fe_in_scope}} == true"
+    on_error: continue      # same fail-closed contract as the backend probe
+    script: { ref: actions }
+    subcommand: plan-check
+    args: ["--doc", "{{fe_plan}}", "--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: fe_state,        from: "$.state" }
+      - { name: fe_derived,      from: "$.derived_version" }
+      - { name: fe_changed,      from: "$.changed_csv" }
+      - { name: current_version, from: "$.current_version" }
+
+  # 3a. BACKEND freshness. clean / edited / untracked proceed; the rest stop. `edited`
+  #     proceeds because a hand-edited plan is exactly what this gate exists to judge —
+  #     it measures the document as it stands. `untracked` proceeds because a migrated
+  #     legacy master has no baseline to be behind, and the whole-document analysis plus
+  #     the stamp is what establishes one.
+  - id: be_gate_na
+    condition: "{{be_in_scope}} == false"
+    action: set
+    vars: { be_gate_ok: "true" }
+  - id: be_gate_clean
+    condition: "{{be_state}} == clean"
+    action: set
+    vars: { be_gate_ok: "true" }
+  - id: be_gate_edited
+    condition: "{{be_state}} == edited"
+    action: set
+    vars: { be_gate_ok: "true" }
+  - id: be_gate_untracked
+    condition: "{{be_state}} == untracked"
+    action: set
+    vars: { be_gate_ok: "true" }
+  - id: be_msg_fresh
+    condition: "{{be_state}} == fresh"
+    action: set
+    vars: { be_gate_msg: "A backend lane is declared but there is no backend-plan.md for this feature, so there is nothing to gate on the service lane — and this stage does not create the document it gates. Run /appweaver plan to author it from the spec, then re-run analyze-design." }
+  - id: be_msg_behind
+    condition: "{{be_state}} == behind"
+    action: set
+    vars: { be_gate_msg: "backend-plan.md derives from spec {{be_derived}} and the spec is now at {{current_version}} — certifying it would green-light a plan that conforms to a contract no longer in force. Requirements the ledger moved since: {{be_changed}}. Run /appweaver plan (update mode conforms exactly those ids and appends the plan's own history row), then re-run analyze-design." }
+  - id: be_msg_edited_behind
+    condition: "{{be_state}} == edited_behind"
+    action: set
+    vars: { be_gate_msg: "backend-plan.md was hand-edited AND the spec has moved past it (derived from {{be_derived}}, spec now {{current_version}}; ids moved: {{be_changed}}). Run /appweaver plan with accept_manual: true — it folds the manual edits in, conforms the moved ids and re-baselines — then re-run analyze-design." }
+  - id: require_be_current
+    action: verify_context
+    require_true: be_gate_ok
+    on_false: stop
+    on_false_message: "{{be_gate_msg}}"
+
+  # 3b. FRONTEND freshness — the same contract, routed to the frontend lane's author.
+  - id: fe_gate_na
+    condition: "{{fe_in_scope}} == false"
+    action: set
+    vars: { fe_gate_ok: "true" }
+  - id: fe_gate_clean
+    condition: "{{fe_state}} == clean"
+    action: set
+    vars: { fe_gate_ok: "true" }
+  - id: fe_gate_edited
+    condition: "{{fe_state}} == edited"
+    action: set
+    vars: { fe_gate_ok: "true" }
+  - id: fe_gate_untracked
+    condition: "{{fe_state}} == untracked"
+    action: set
+    vars: { fe_gate_ok: "true" }
+  - id: fe_msg_fresh
+    condition: "{{fe_state}} == fresh"
+    action: set
+    vars: { fe_gate_msg: "A frontend lane is declared but there is no frontend-plan.md for this feature. The spec's Experience Standards (UX-) have their ONLY design home there, so a green from this gate would claim a coverage this feature does not have. Run /appweaver plan-ui to author it, then re-run analyze-design." }
+  - id: fe_msg_behind
+    condition: "{{fe_state}} == behind"
+    action: set
+    vars: { fe_gate_msg: "frontend-plan.md derives from spec {{fe_derived}} and the spec is now at {{current_version}} — ids the ledger moved since: {{fe_changed}}. Run /appweaver plan-ui, then re-run analyze-design." }
+  - id: fe_msg_edited_behind
+    condition: "{{fe_state}} == edited_behind"
+    action: set
+    vars: { fe_gate_msg: "frontend-plan.md was hand-edited AND the spec has moved past it (derived from {{fe_derived}}, spec now {{current_version}}; ids moved: {{fe_changed}}). Run /appweaver plan-ui with accept_manual: true, then re-run analyze-design." }
+  - id: require_fe_current
+    action: verify_context
+    require_true: fe_gate_ok
+    on_false: stop
+    on_false_message: "{{fe_gate_msg}}"
+
+  # 4. Load the domain GATE overlays (domain-rule-bindings `/aw-spec-gate`) as the
+  #    conformance CHECKLIST — validation input only, never authoring. The analyze step
+  #    sees them (include_standards: true); the repair steps do NOT, because a plan
+  #    conforms to the SPEC and an overlay constraint absent from the spec is a lift
+  #    failure to report, not a rule to design against. Empty for a non-domain project.
   - id: resolve_gate_overlays
     action: execute_script
     script: { ref: actions }
@@ -119,7 +358,8 @@ workflow:
     files_from_variable: gate_overlays
     optional: true
 
-  # 3. Pre-execution hooks.
+  # 5. Pre-execution hooks. The phase keys stay `before_analyze` / `after_analyze` —
+  #    they are configuration contract and outlive the rename.
   - id: resolve_pre_hooks
     action: execute_script
     script: { ref: actions }
@@ -131,120 +371,416 @@ workflow:
     action: dispatch_hooks
     hooks_from_variable: before_hooks
 
-  # 4. Conformance + REPAIR loop (spec is the anchor): check → REPORT gaps + ASK →
-  #    Repair on approval → re-check; "Report and Skip" writes design-analyze-report.md
-  #    and stops. Bounded (3×).
+  # 6. The context both lanes are judged in. One envelope, because the coverage
+  #    question spans them: a UX- lives only in the frontend plan, a BR- only in the
+  #    backend plan, and an FR- with a user-facing surface needs a home in each.
+  #    Both plans are `optional:` ONLY because a lane may be undeclared — for a
+  #    declared lane the freshness gate above already proved the file exists, so an
+  #    in-scope plan is never silently skipped here.
+  - id: ctx_analyze
+    action: build_context
+    context:
+      - { path: "{{spec_file}}" }
+      - { path: "{{be_plan}}", optional: true }
+      - { path: "{{fe_plan}}", optional: true }
+      - { path: "{{feature_dir}}/interfaces.md", optional: true }   # the published surface both plans cite by IF- id
+
+  # 7. Conformance loop: analyze → REPORT gaps + ASK → repair the found gaps → re-check.
+  #    Bounded (3x). "Report and Skip" leaves both plans untouched and stops at the
+  #    report, which is the right answer whenever the fix belongs to another stage.
   - id: analyze_loop
     action: loop
     while: "{{analyze_ok}} != true"
     max_iterations: 3
     steps:
+      # A stale `true` from a previous iteration must never arm a write, so the
+      # frontend repair permission is rebuilt from scratch on every pass.
+      - id: fe_repair_reset
+        action: set
+        vars: { fe_repair_go: "false" }
+
       - id: analyze
         action: agent_query
-        context: ["{{spec_file}}", "{{design_doc}}"]
-        include_standards: true            # the gate overlays (checklist) are in the standards
-        schema: { ok: true, gaps: [ { severity: "high", spec_ref: "<FR/BR/CN/DC/IC/US/SC or overlay or —>", where: "<design section>", gap: "<how it drifts>" } ] }
-        mock: { ok: true, gaps: [] }
+        include_standards: true            # the domain gate overlays (the checklist) ride in the standards
+        schema: { ok: true, gap_count: 0, gap_refs: "<comma-separated spec ids the gaps touch>", repaired_refs: "<comma-separated spec ids THIS repair actually rewrote — empty on the first pass>", backend_repair: false, frontend_repair: false, gaps: [ { severity: "high", lane: "backend|frontend|cross", spec_ref: "<FR/BR/CN/DC/IC/UX/SC id, or the overlay name, or —>", where: "<document + section>", gap: "<how it drifts>", route: "<the command that fixes it>" } ] }
+        mock: { ok: true, gap_count: 0, gap_refs: "", repaired_refs: "", backend_repair: false, frontend_repair: false, gaps: [] }
         task: |
-          spec.md is the ANCHOR. Check that design.md (in context) STRICTLY follows
-          the spec (in context) and list EVERY drift as a gap:
-          (1) every spec item — FR / Business Rule / Constraint (CN-) / Data
-          Classification (DC-) / Integration Contract (IC-) / user story / success
-          criterion — has a design home (the Traceability section is complete). A lifted
-          CN-/DC-/IC- with no design row is a HIGH gap;
-          (2) the DOMAIN model matches the spec EXACTLY — entities/value objects are
-          the spec's Key Entities (same names), invariants are the spec's Business
-          Rules, and the boundary is the spec's Aggregate Boundary;
-          (3) NO design element exceeds or contradicts the spec — anything without a
-          spec basis is a drift unless already logged as a DA-n assumption;
-          (4) the layers are coherent (Application→Domain, API→Application, Infra
-          implements the declared ports) and it stays high-level + technology-agnostic.
-          (5) OVERLAY BACKSTOP — the domain gate checklist is loaded in the standards.
-          For each constraint it states (retention, immutability, append-only audit,
-          data-exposure, interop obligation, etc.), confirm design.md realises it via a
-          spec CN-/DC-/IC-. If a checklist constraint is present in NEITHER the spec nor
-          the design, it is a HIGH gap — set spec_ref to the overlay name and PREFIX the
-          gap text with "LIFT-FAILURE:" (it was never lifted into the spec; the fix is
-          /appweaver specify, not design — do not fabricate it in the design).
-          (If design.md is still the empty template, treat the WHOLE spec as gaps.)
-          Set ok=true ONLY when design.md fully conforms to the spec AND no checklist
-          constraint is unaccounted for.
+          spec.md is the ANCHOR. Judge the feature's PLAN DOCUMENTS against it and list
+          EVERY drift as a gap. In scope this run: backend-plan.md = {{be_in_scope}},
+          frontend-plan.md = {{fe_in_scope}}. Judge ONLY the plans in scope; never
+          report a gap against a lane that is not declared.
+
+          SECTION NUMBERS ARE NOT STABLE, so identify every section by its ROLE and by
+          the heading actually present in the document in front of you. A brownfield
+          project's plans come from the code-derived template /appweaver onboard
+          installs, whose layout differs from the greenfield one (its traceability,
+          assumptions and deviations sections carry different numbers, and its
+          component sections are named after the project's own structural axes). Any
+          "§n" below is the GREENFIELD number, given only to say WHICH section is
+          meant. Put the heading you actually found in `where`, and never report a
+          missing section on the strength of a number.
+
+          (1) FORWARD — COVERAGE. Every spec item has a design home, in the RIGHT lane:
+              • FR- (requirement) — a home in backend-plan.md; and ALSO a screen/
+                component/state in frontend-plan.md when it has a user-facing surface.
+              • BR- (business rule) — backend-plan.md only, as a domain invariant.
+              • CN- (constraint) — wherever it binds. A CN- that binds both lanes needs
+                a home in BOTH; one that binds a single lane needs only that one.
+              • DC- (data classification) — backend enforcement, plus what the frontend
+                withholds from the client wherever a client sees the data.
+              • IC- (integration contract) — the backend adapter/port that realises it;
+                the frontend binds to it through interfaces.md, never directly.
+              • UX- (experience standard) — frontend-plan.md ONLY. backend-plan.md does
+                not carry them, so a UX- with no frontend row is a DROPPED requirement
+                and is always a HIGH gap.
+              • SC- (success criterion) — wherever it is met and how it is verified.
+              A lifted CN-/DC-/IC- with no row in the relevant Traceability section is a
+              HIGH gap: those sections are the two-way guarantee and must be complete.
+              Edge Cases carry no ids by design — do not invent one for them.
+
+          (2) THE DOMAIN MODEL MATCHES THE SPEC EXACTLY (backend). Entities and value
+              objects are the spec's Key Entities under the same names, invariants are
+              the spec's Business Rules, and the boundary is the spec's Aggregate
+              Boundary. A renamed or invented entity is a HIGH gap.
+
+          (3) BACKWARD — JUSTIFICATION. No design element exceeds or contradicts the
+              spec. Anything without a spec basis is a drift UNLESS it is already logged
+              as a DA-n assumption or a WA-n workaround in that plan's own ledgers — a
+              logged item with a stated basis (including "per Const. §<n>" for standing
+              technical machinery the constitution mandates) is accounted for, not a gap.
+
+          (4) CROSS-LANE — the checks neither lane can make alone. Report these with
+              lane "cross":
+              • an FR- with a user-facing surface designed in one lane only;
+              • a CN-/DC-/IC- that binds both lanes and is honoured in only one;
+              • the frontend's contract-binding section (greenfield §5) citing an IF-
+                id that interfaces.md does not publish, or an operation it needs that
+                has no IF- entry and is not already raised as a contract gap;
+              • either plan RESTATING the wording of a published interface instead of
+                citing its IF- id — the spec owns requirement wording and interfaces.md
+                owns contract wording; a second copy is drift by construction;
+              • the two plans contradicting each other on the same behaviour.
+
+          (5) COHERENCE. The backend layers hold (Application→Domain, API→Application,
+              Infrastructure implements the declared ports); the frontend's state,
+              components and flows are consistent with its own navigation. Both stay
+              high-level and technology-agnostic.
+
+          (6) OVERLAY BACKSTOP. The domain gate checklist is loaded in the standards.
+              For each constraint it states (retention, immutability, append-only audit,
+              data exposure, interop obligation …), confirm a plan realises it VIA a
+              spec CN-/DC-/IC-. If a checklist constraint is in NEITHER the spec nor a
+              plan, it is a HIGH gap: set spec_ref to the overlay name and PREFIX the
+              gap text with "LIFT-FAILURE:". It was never lifted into the spec, so the
+              fix is /appweaver specify — never fabricate it into a plan.
+
+          For each gap set `route` to the command that actually fixes it: repair here
+          when the plan is wrong and the spec is right; /appweaver sync-spec when the
+          SPEC is what is wrong; /appweaver specify for a LIFT-FAILURE; /appweaver plan
+          or /appweaver plan-ui when the plan simply lags the spec.
+
+          Set backend_repair true only if at least one gap can be closed by rewriting
+          backend-plan.md, and frontend_repair likewise for frontend-plan.md — false for
+          a lane that is not in scope, and false when every gap on that lane routes to
+          another command. Set gap_count to the number of gaps and gap_refs to their
+          spec ids, comma-separated. Set ok=true ONLY when every plan in scope fully
+          conforms to the spec AND no checklist constraint is unaccounted for.
+
+          `repaired_refs` IS A DIFFERENT SET FROM `gap_refs`, and it goes into the plans'
+          own Change History. Set it to the spec ids THIS PASS ACTUALLY REWROTE a plan for
+          — empty on a pass that repaired nothing, which includes the first pass of every
+          run. Never copy gap_refs into it: that set holds every finding, including the
+          gaps you were told to leave OPEN (route sync-spec or specify), a LIFT-FAILURE
+          whose spec_ref is an overlay name rather than an id, and any "—". Recording one
+          of those claims the plan was conformed for a requirement nobody touched, in the
+          ledger story-plan and the next /appweaver plan read.
         outputs:
-          - { name: analyze_ok,   from: "$.ok" }
-          - { name: analyze_gaps, from: "$.gaps" }
+          - { name: analyze_ok,       from: "$.ok" }
+          - { name: analyze_gaps,     from: "$.gaps" }
+          - { name: gap_count,        from: "$.gap_count" }
+          - { name: gap_refs,         from: "$.gap_refs" }
+          - { name: be_needs_repair,  from: "$.backend_repair" }
+          - { name: fe_needs_repair,  from: "$.frontend_repair" }
+          - { name: repaired_refs,    from: "$.repaired_refs" }
+
+      # The report's subject is the state the gate FOUND, not what survived repair —
+      # a verdict that only ever describes the repaired document cannot show that a
+      # repair happened, and a green earned by repair must stay visible as one.
+      - id: record_found
+        condition: "{{found_recorded}} == false"
+        action: set
+        vars:
+          found_gaps: "{{analyze_gaps}}"
+          found_count: "{{gap_count}}"
+          found_refs: "{{gap_refs}}"
+          found_recorded: "true"
+
       - id: conform_break
         action: break
         condition: "{{analyze_ok}} == true"
+
       - id: ask_repair
         action: ask
         prompt: |
-          Analyze found spec↔design gaps (spec.md is the anchor):
+          Spec ↔ plan gaps found (spec.md is the anchor; {{gap_count}} gap(s) on {{gap_refs}}):
           {{analyze_gaps}}
-          Repair design.md to conform to the spec now, or report the gaps and stop?
-        options: ["Repair", "Report and Skip"]
+          Repair the plan document(s) to conform now, or write the report and stop?
+          Repair closes only these gaps and records the rewrite in the plan's own
+          Change History. Choose Report and Skip whenever the fix belongs elsewhere —
+          a wrong SPEC goes through /appweaver sync-spec, a LIFT-FAILURE through
+          /appweaver specify.
+        # REPORT FIRST, BECAUSE THE FIRST OPTION IS THE UNATTENDED ANSWER. An `ask` with
+        # nobody at the terminal resolves to option one, so an unattended run of this gate
+        # takes whichever branch is written here. Repairing means REWRITING both feature
+        # plans and re-stamping them, and a CI job that rewrites the documents it was asked
+        # to check reports on a state it created. Reporting is the safe default: it writes
+        # the report, leaves the plans untouched, and the person who reads it chooses.
+        options: ["Report and Skip", "Repair"]
         answer_var: repair_choice
-      - id: write_report
+
+      - id: skip_break
+        action: break
         condition: "{{repair_choice}} == Report and Skip"
+
+      - id: mark_repaired
+        action: set
+        vars: { repaired: "true" }
+
+      # The frontend lane's write permission is the AND of "the model found something
+      # to fix there" and "that lane is in scope" — the evaluator takes single
+      # comparisons only, so the second half arrives as the assigned value.
+      - id: fe_repair_arm
+        condition: "{{fe_needs_repair}} == true"
+        action: set
+        vars: { fe_repair_go: "{{fe_in_scope}}" }
+
+      - id: reconcile_be
+        condition: "{{be_needs_repair}} == true"
         action: agent_author
-        context: ["{{design_doc}}"]
-        include_standards: false
-        output_target: { type: file, path: "{{feature_dir}}/design-analyze-report.md" }
+        include_standards: false           # rewrite-in-place: the SPEC anchors, not the overlays
+        output_target: { type: file, path: "{{be_plan}}" }
         task: |
-          Write a Design Analyze Report to the output from these spec↔design
-          conformance gaps (spec.md is the ANCHOR; the user chose to skip repair):
+          spec.md is the ANCHOR — update backend-plan.md (in context) to CONFORM to it,
+          closing the gaps below whose lane is "backend" or "cross" AND whose route is
+          this repair. The spec WINS every time.
           {{analyze_gaps}}
-          Markdown format:
-          - "# Design Analyze Report — <aggregate>" plus today's date.
-          - A verdict line: "verdict: GAPS ✗ · <n> gap(s)".
-          - "## Gaps" as a table: | # | severity | spec ref | design location | gap |.
-          - "## How to resolve": the spec is the anchor — update design.md to follow
-            the spec for each gap (out of band), then re-run /appweaver analyze-design
-            to clear the report.
-          Return the complete report markdown only.
-      - id: skip_break
-        action: break
-        condition: "{{repair_choice}} == Report and Skip"
-      - id: reconcile
+          - SECTION NUMBERS ARE NOT STABLE: this document may be the greenfield
+            four-layer template or the code-derived one /appweaver onboard installs,
+            whose layout differs. Work from the headings actually in the document; the
+            "§n" below name the GREENFIELD section so you know which one is meant.
+            NEVER renumber or reorder what is there.
+          - Give each uncovered spec FR-/BR-/CN-/DC-/IC-/SC- a design home: a lifted
+            CN-/DC-/IC- lands in a domain invariant (§1), the persistence component
+            (§4.1), an external-integrations adapter row (§4.2), or a cross-cutting
+            row (§5).
+          - Realign the domain model to the spec: entity and value-object names = the
+            spec's Key Entities, invariants = the spec's Business Rules, boundary = the
+            spec's Aggregate Boundary.
+          - REMOVE, or move to a DA-n assumption, any design element with no spec basis.
+            EXCEPTION: do NOT remove a cross-cutting element the technical constitution
+            mandates — standing technical or infrastructure machinery rather than
+            invented domain logic. MOVE it to a DA-n citing the mandating principle
+            ("per Const. §<n>"); removing it could violate the constitution. Reserve
+            REMOVE for genuine over-reach — invented domain entities, rules or behaviour
+            the spec omits.
+          - The published-surface section (§3) is an INDEX into interfaces.md: cite IF-
+            ids, never restate a published contract's wording. If a gap says an operation
+            has no IF- entry, note it there as a contract gap to publish — do not invent
+            an IF- id, and never edit interfaces.md from here; /appweaver plan is its
+            only publisher.
+          - A "LIFT-FAILURE:" gap CANNOT be closed here: the constraint is not in the
+            spec and you must not invent a domain rule the spec omits. Leave it open and
+            add a DA-n reading "lift-failure: <constraint> — re-run /appweaver specify to
+            lift it into CN-/DC-/IC-".
+          - Leave every gap routed to /appweaver sync-spec or /appweaver specify OPEN.
+            Fixing the plan to match a wrong spec buries the defect in the document that
+            is supposed to reveal it.
+          - Keep the Traceability section (§6) in sync with what you changed. Preserve
+            every already-conformant section VERBATIM, and preserve the Assumptions (§7),
+            Workarounds/Deviations (§8) and Change History (§9) sections as LEDGERS —
+            append to them, never rewrite, renumber or drop them. Dropping the Change
+            History section is refused downstream and stops the run. Write NO version and
+            NO history row: plan-stamp does both.
+          - Do NOT change spec.md, frontend-plan.md, interfaces.md or adr.md.
+          Return the COMPLETE updated backend-plan.md content only.
+
+      # plan-stamp is the plan's only version authority. Repairing without stamping
+      # would leave the document reading as an unexplained hand edit to story-plan and
+      # to the next /appweaver plan, and the rewrite would be absent from its ledger.
+      - id: stamp_be
+        condition: "{{be_needs_repair}} == true"
+        action: execute_script
+        script: { ref: actions }
+        subcommand: plan-stamp
+        # --ids is WHAT THIS REPAIR WROTE, not every gap the pass found. gap_refs is the
+        # whole finding set — including gaps the repair prompt is told to leave OPEN (route
+        # sync-spec / specify), a LIFT-FAILURE whose spec_ref is an overlay name rather than
+        # an id, and the literal "—" the schema permits. Stamping those recorded, in the
+        # plan's own Change History, that the repair conformed ids it never touched — and
+        # that ledger is what story-plan and the next /appweaver plan read.
+        # --note carries the plan's tracking STATE, because a repair over an `edited`
+        # document re-baselines a hand edit that /appweaver plan would have refused without
+        # accept_manual: true. Admitting the edit is right; adopting it silently is not.
+        args: ["--doc", "{{be_plan}}", "--feature-dir", "{{feature_dir}}", "--ids", "{{repaired_refs}}", "--note", "Conformance repair (analyze-design) over a plan in state '{{be_state}}'"]
+        outputs:
+          - { name: be_stamp_ok,    from: "$.ok" }
+          - { name: be_stamp_error, from: "$.error" }
+
+      - id: reconcile_fe
+        condition: "{{fe_repair_go}} == true"
         action: agent_author
-        context: ["{{spec_file}}", "{{design_doc}}"]
-        include_standards: false           # rewrite-in-place: spec anchors — NOT the overlays
-        output_target: { type: file, path: "{{design_doc}}" }
+        include_standards: false
+        output_target: { type: file, path: "{{fe_plan}}" }
         task: |
-          spec.md is the ANCHOR — update design.md (in context) to CONFORM to it,
-          closing these gaps (the spec WINS every time):
+          spec.md is the ANCHOR — update frontend-plan.md (in context) to CONFORM to it,
+          closing the gaps below whose lane is "frontend" or "cross" AND whose route is
+          this repair. The spec WINS every time.
           {{analyze_gaps}}
-          - Add a design home for each uncovered spec FR/BR/CN/DC/IC/US/SC (a lifted
-            CN-/DC-/IC- lands in a §1 domain invariant · the persistence component or an
-            External Integrations table adapter row · a Cross-Cutting Concerns row).
-          - Realign the DOMAIN model to the spec: entity/value-object names = the
-            spec's Key Entities, invariants = the spec's Business Rules, boundary =
-            the spec's Aggregate Boundary.
-          - REMOVE, or move to a DA-n assumption, any design element with no spec
-            basis — never keep design that exceeds or contradicts the spec. EXCEPTION:
-            do NOT remove a cross-cutting element that is (or may be) mandated by the
-            technical constitution — it cites a principle as its basis ("per Const.
-            §<n>"), or it is standing technical/infrastructure machinery rather than
-            invented domain logic. MOVE such an element to a DA-n citing the mandating
-            principle; removing it could violate the constitution. Reserve REMOVE for
-            genuine over-reach — invented domain entities/rules/behaviour the spec omits.
-          - A "LIFT-FAILURE:" gap you CANNOT close — the constraint is not in the spec,
-            and you must NOT invent a domain rule the spec omits. Leave it open and add a
-            DA-n note "lift-failure: <constraint> — re-run /appweaver specify to lift
-            it into CN-/DC-/IC-". (The gate will stop and direct the user to specify.)
-          - Keep the Traceability section in sync. Preserve every already-conformant section
-            VERBATIM. Do NOT change the spec.
-          Return the COMPLETE updated design.md content only.
+          - Give every uncovered UX- a home — this document is their ONLY home — and
+            every FR- with a user-facing surface a screen, component or state.
+          - Honour each CN-/DC- that binds this lane: a DC- says what the client is not
+            shown, a CN- a bound the experience must meet.
+          - SECTION NUMBERS ARE NOT STABLE — work from the headings actually in the
+            document; the "§n" here name the greenfield sections so you know which is
+            meant, and nothing is renumbered or reordered.
+          - The Contract Binding section (§5) cites interfaces.md by IF- id and never
+            restates a contract's wording. An operation with no published entry keeps the
+            "(unpublished)" marker and is listed under contract gaps to raise — this
+            lane never writes interfaces.md; /appweaver plan publishes it.
+          - REMOVE, or move to a DA-n, any element with no spec basis, except what
+            constitution.ui.md mandates — that moves to a DA-n citing the basis.
+          - Leave every gap routed to /appweaver sync-spec or /appweaver specify OPEN.
+          - Keep the Traceability section (§7) in sync. Preserve every already-conformant
+            section VERBATIM, and preserve the Assumptions (§8), Workarounds (§9) and
+            Change History sections as LEDGERS — append, never rewrite, renumber or drop.
+            Dropping the Change History section is refused downstream and stops the run.
+            Write NO version and NO history row: plan-stamp does both.
+          - Do NOT change spec.md, backend-plan.md, interfaces.md or adr.md.
+          Return the COMPLETE updated frontend-plan.md content only.
+
+      - id: stamp_fe
+        condition: "{{fe_repair_go}} == true"
+        action: execute_script
+        script: { ref: actions }
+        subcommand: plan-stamp
+        # Same two rules as the service lane: the ids this repair actually wrote, and the
+        # tracking state the repair ran over. See stamp_be.
+        args: ["--doc", "{{fe_plan}}", "--feature-dir", "{{feature_dir}}", "--ids", "{{repaired_refs}}", "--note", "Conformance repair (analyze-design) over a plan in state '{{fe_state}}'"]
+        outputs:
+          - { name: fe_stamp_ok,    from: "$.ok" }
+          - { name: fe_stamp_error, from: "$.error" }
+
+  # 7b. The ledger-survival fence. plan-stamp refuses to baseline a document whose
+  #     Change History section went missing, so ok=false here means a repair landed on
+  #     disk having dropped the plan's ledger. That is the one loss this model never
+  #     absorbs silently — stop on it, before any verdict is written.
+  - id: be_stamp_fence
+    action: verify_context
+    require_true: be_stamp_ok
+    on_false: stop
+    on_false_message: "The repair to backend-plan.md was written but NOT baselined: {{be_stamp_error}}. The rewrite dropped a section plan-stamp refuses to stamp over (its Change History ledger). Restore that section in backend-plan.md — git diff shows what the repair removed — then re-run analyze-design."
+  - id: fe_stamp_fence
+    action: verify_context
+    require_true: fe_stamp_ok
+    on_false: stop
+    on_false_message: "The repair to frontend-plan.md was written but NOT baselined: {{fe_stamp_error}}. The rewrite dropped a section plan-stamp refuses to stamp over (its Change History ledger). Restore that section in frontend-plan.md — git diff shows what the repair removed — then re-run analyze-design."
+
+  # 8. The human report — written on EVERY run, green or red. It is the two-directional
+  #    coverage record, and a gate that leaves nothing behind when it passes gives a
+  #    reviewer no evidence that it ran at all.
+  - id: write_report
+    action: agent_author
+    include_standards: false
+    output_target: { type: file, path: "{{report_path}}" }
+    task: |
+      Write the Plan Analyze Report for this feature to the output.
+      Verdict: conformant={{analyze_ok}}. Gaps as FOUND: {{found_count}} on
+      {{found_refs}}. Gaps still open: {{gap_count}}. Repair was run: {{repaired}}.
+      Lanes gated: backend={{be_in_scope}} (tracking {{be_state}}, derived from spec
+      {{be_derived}}), frontend={{fe_in_scope}} (tracking {{fe_state}}, derived from
+      spec {{fe_derived}}). Spec version: {{current_version}}.
+      The gaps as found:
+      {{found_gaps}}
+      Markdown format:
+      - "# Plan Analyze Report — <aggregate>", then a line naming the spec version and
+        each gated plan with its tracking state.
+      - A verdict line: "verdict: CONFORMS ✓" or "verdict: GAPS ✗ · <n> open".
+        WHERE A REPAIR RAN OVER A HAND-EDITED PLAN, say so on that line — backend-plan.md
+        tracking state was "{{be_state}}" and frontend-plan.md "{{fe_state}}", and an
+        `edited` or `edited_behind` there means the repair re-baselined a hand edit that
+        /appweaver plan would have refused without accept_manual: true. Name the document,
+        the state, and that the edit is now adopted into the plan's baseline — whoever made
+        it should confirm the repair kept its intent.
+        When repair ran, say so and give both numbers — found and still open.
+      - "## Coverage (spec → plan)": a table | spec id | type | lane(s) it needs |
+        design home | status |, one row per spec id you can see in the spec, marking
+        each covered or UNCOVERED. This is the forward half of the two-way guarantee
+        and it is the reason this report exists — write it even on a green run.
+      - "## Gaps": a table | # | severity | lane | spec ref | where | gap | route |.
+        Omit the section when there were none.
+      - "## How to resolve": group by route and give the exact command for each — the
+        spec is the anchor, so a wrong plan is repaired here or via /appweaver plan
+        with accept_manual, a wrong SPEC goes through /appweaver sync-spec, and a
+        "LIFT-FAILURE:" goes through /appweaver specify. Omit on a green run.
+      Do not invent ids, versions or dates beyond the values given above.
+      Return the complete report markdown only.
+
+  # 8b. THE SHAPE BEING CERTIFIED, read at the last possible moment. Taken here rather than
+  #     from the freshness probes at the top, because the repair loop may have rewritten and
+  #     re-stamped both plans in between — recording the pre-repair hash would certify a
+  #     document that no longer exists and fail every downstream comparison on a green run.
+  #     Per lane and conditional: a lane out of scope has no hash and gets an empty field,
+  #     which the readers treat as "this lane was not certified" rather than as a mismatch.
+  - id: be_final_hash
+    condition: "{{be_in_scope}} == true"
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: plan-check
+    args: ["--doc", "{{be_plan}}", "--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: be_final_sha, from: "$.body_sha256" }
+  - id: fe_final_hash
+    condition: "{{fe_in_scope}} == true"
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: plan-check
+    args: ["--doc", "{{fe_plan}}", "--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: fe_final_sha, from: "$.body_sha256" }
+
+  # 9. The machine-readable verdict, written beside the report by the SCRIPT — CI
+  #    cannot branch on prose, and a verdict is exactly the kind of dated, derived
+  #    record the model never writes. `ok` from this step means the file was written;
+  #    the pass/fail verdict is `status` inside it.
+  - id: gate_result
+    action: execute_script
+    script: { ref: actions }
+    subcommand: gate-result
+    # The lenient loader needs a flow sequence on ONE line.
+    # backend_sha256 / frontend_sha256 are WHAT THIS RUN CERTIFIED — the shape each plan was
+    # in when it was judged. Nothing else in the verdict can say it: backend_state and
+    # backend_derived do not move when a plan is hand-edited, so a plan approved here and
+    # edited afterwards was indistinguishable from one still in the approved shape. story-plan
+    # and both implements compare against these, which is what makes law 40 (approved,
+    # changed, never re-approved must not reach code) enforceable rather than stated.
+    # RE-READ AFTER ANY REPAIR: the loop above may have rewritten and re-stamped the plans, so
+    # the hash recorded has to be the one on disk NOW, not the one the freshness probe saw.
+    args: ["--gate", "analyze-design", "--feature-dir", "{{feature_dir}}", "--ok", "{{analyze_ok}}", "--spec-version", "{{current_version}}", "--report", "{{report_path}}", "--gap-count", "{{found_count}}", "--gap-refs", "{{found_refs}}", "--field", "gaps_open={{gap_count}}", "--field", "repaired={{repaired}}", "--field", "backend_plan={{be_plan}}", "--field", "backend_in_scope={{be_in_scope}}", "--field", "backend_state={{be_state}}", "--field", "backend_derived={{be_derived}}", "--field", "backend_sha256={{be_final_sha}}", "--field", "frontend_plan={{fe_plan}}", "--field", "frontend_in_scope={{fe_in_scope}}", "--field", "frontend_state={{fe_state}}", "--field", "frontend_derived={{fe_derived}}", "--field", "frontend_sha256={{fe_final_sha}}"]
+    outputs:
+      - { name: result_file, from: "$.result_file" }
 
   - id: analyze_gate
     action: verify_context
     require_true: analyze_ok
     on_false: stop
-    on_false_message: "design.md does not conform to the spec (gaps: {{analyze_gaps}}) — repair was skipped (see design-analyze-report.md), or it could not be reconciled in 3 passes. A 'LIFT-FAILURE:' gap means a domain constraint from the gate checklist was never lifted into the spec — re-run /appweaver specify to add it (CN-/DC-/IC-). Otherwise fix out of band, or re-run and choose Repair; resolve an ambiguous spec via /appweaver specify."
+    on_false_message: "The feature plans do not conform to spec {{current_version}} — {{gap_count}} gap(s) open on {{gap_refs}}. The full two-directional report is at {{report_path}} and the machine-readable verdict at {{result_file}}. Repair was skipped, or the gaps could not be closed in 3 passes. Route by gap: a wrong PLAN is repaired here or by hand-editing it and re-running /appweaver plan (or plan-ui) with accept_manual: true; a wrong SPEC goes through /appweaver sync-spec; a 'LIFT-FAILURE:' gap means a domain constraint from the gate checklist was never lifted into the spec, so re-run /appweaver specify to add it as a CN-/DC-/IC-."
 
-  # (No change-close here by design — this stage only ever runs with NO change open,
-  #  and cr-archive belongs to close-delta, which runs after finalize-delta's merge.)
+  # (No version is written here by design. This gate proves conformance; close-story is
+  #  the version authority downstream, and plan-stamp the plans' own.)
 
-  # 5. Post-execution hooks.
+  # 10. Post-execution hooks.
   - id: resolve_post_hooks
     action: execute_script
     script: { ref: actions }
@@ -258,8 +794,20 @@ workflow:
 
 outputs:
   feature_dir: "{{feature_dir}}"
-  design_doc: "{{design_doc}}"
+  spec_version: "{{current_version}}"
+  backend_plan: "{{be_plan}}"
+  backend_in_scope: "{{be_in_scope}}"
+  backend_state: "{{be_state}}"
+  backend_derived: "{{be_derived}}"
+  frontend_plan: "{{fe_plan}}"
+  frontend_in_scope: "{{fe_in_scope}}"
+  frontend_state: "{{fe_state}}"
+  frontend_derived: "{{fe_derived}}"
   conformant: "{{analyze_ok}}"
+  gaps_found: "{{found_count}}"
+  gaps_open: "{{gap_count}}"
+  repaired: "{{repaired}}"
+  report: "{{report_path}}"
+  result_json: "{{result_file}}"
   gaps: "{{analyze_gaps}}"
-  version: "{{version}}"
-  next: "/appweaver implement   (design conforms to the spec; version unchanged — this gate closes nothing)"
+  next: "Both lanes' plans conform to spec {{current_version}} — the verdict is at {{result_file}} for CI and the coverage report at {{report_path}}. Next: /appweaver sync-stories to plan the backlog against this spec version, then /appweaver story-plan <story-id> for the slice, which reads backend-plan.md as binding feature architecture. Re-run this gate after EVERY /appweaver plan and /appweaver plan-ui — it is what keeps that binding honest. NOTE repaired=true means this gate rewrote a plan to close its own findings and plan-stamp recorded the rewrite in that plan's Change History; gaps_found is what it found before repairing, so review the diff rather than reading the green alone."