aw-spec-cli 0.1.16 → 0.1.18

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

@@ -1,813 +0,0 @@
-# =============================================================================
-# aw-spec-analyze-design (orchestrator) — the spec ↔ FEATURE PLAN conformance GATE
-#
-# 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.
-#
-# 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 plan  (and /appweaver plan-ui where a frontend lane is declared).
-# =============================================================================
-
-name: aw-spec-analyze-design
-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
-
-scripts:
-  actions:
-    sh:  .appweaver/scripts/bash/aw-spec-actions.sh
-    ps1: .appweaver/scripts/powershell/aw-spec-actions.ps1
-
-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: ""
-
-workflow:
-
-  # 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
-    script: { ref: actions }
-    subcommand: feature-paths
-    outputs:
-      - { 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
-    require_non_empty: feature_dir
-    on_empty: stop
-    on_empty_message: "No active feature. Run /appweaver select-feature first (pick or create the aggregate, e.g. Order), then re-run analyze-design."
-
-  - id: verify_spec
-    action: verify_context
-    require_true: spec_exists
-    on_false: stop
-    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" }
-
-  # 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 }
-    subcommand: version-read
-    args: ["--feature-dir", "{{feature_dir}}"]
-    outputs:
-      - { name: active_change, from: "$.active_change" }
-      - { name: has_change,    from: "$.has_change" }
-      - { name: version,       from: "$.version" }
-
-  - id: flag_change_open
-    condition: "{{has_change}} == true"
-    action: set
-    vars: { no_open_change: "false" }
-
-  - id: require_no_change
-    action: verify_context
-    require_true: no_open_change
-    on_false: stop
-    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."
-
-  # 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: plan-check
-    args: ["--doc", "{{be_plan}}", "--feature-dir", "{{feature_dir}}"]
-    outputs:
-      - { name: be_state,        from: "$.state" }
-      - { name: be_derived,      from: "$.derived_version" }
-      - { name: be_changed,      from: "$.changed_csv" }
-      - { name: current_version, from: "$.current_version" }
-
-  - 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 }
-    subcommand: resolve-domain
-    args: ["--command", "aw-spec-gate"]
-    outputs:
-      - { name: gate_overlays, from: "$.candidates" }
-  - id: load_gate_overlays
-    action: load_standards
-    files_from_variable: gate_overlays
-    optional: true
-
-  # 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 }
-    subcommand: resolve-hooks
-    args: ["--phase", "before_analyze"]
-    outputs:
-      - { name: before_hooks, from: "$.hooks" }
-  - id: dispatch_pre_hooks
-    action: dispatch_hooks
-    hooks_from_variable: before_hooks
-
-  # 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
-        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. 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: 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: |
-          Spec ↔ plan gaps found (spec.md is the anchor; {{gap_count}} gap(s) on {{gap_refs}}):
-          {{analyze_gaps}}
-          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: 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
-        include_standards: false           # rewrite-in-place: the SPEC anchors, not the overlays
-        output_target: { type: file, path: "{{be_plan}}" }
-        task: |
-          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}}
-          - 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
-        include_standards: false
-        output_target: { type: file, path: "{{fe_plan}}" }
-        task: |
-          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}}
-          - 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: "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 version is written here by design. This gate proves conformance; close-story is
-  #  the version authority downstream, and plan-stamp the plans' own.)
-
-  # 10. Post-execution hooks.
-  - id: resolve_post_hooks
-    action: execute_script
-    script: { ref: actions }
-    subcommand: resolve-hooks
-    args: ["--phase", "after_analyze"]
-    outputs:
-      - { name: after_hooks, from: "$.hooks" }
-  - id: dispatch_post_hooks
-    action: dispatch_hooks
-    hooks_from_variable: after_hooks
-
-outputs:
-  feature_dir: "{{feature_dir}}"
-  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}}"
-  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."