aw-spec-cli 0.1.15 → 0.1.16

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

@@ -12,7 +12,8 @@
 # extract). See .appweaver/DESIGN-FORMAT.md + .appweaver/templates/design-template.md.
 # (`plan` re-uses the name of a long-retired phase whose plan.md had zero consumers.)
 #
-# WHERE IT SITS. specify/sync-spec move the spec; the developer then runs plan, which
+# WHERE IT SITS. specify/sync-spec (⌛ sync-spec is not built yet; the hand route is
+# .appweaver/SPEC-EDIT-PROTOCOL.md) move the spec; the developer then runs plan, which
 # conforms this feature's design to what moved. Story designs (/appweaver story-plan)
 # READ this document for the ids they carry and NEVER write back — nothing merges into
 # it, so it keeps exactly one writer and cannot be silently rewritten. It is the
@@ -198,19 +199,10 @@ workflow:
   #    conformance theatre: an edit that skipped the Change History has no version, so
   #    the derivation stamp this run writes would claim a baseline the ledger cannot
   #    name. spec-check's only ok:false is exactly that case.
-  - id: spec_guard_read
-    action: execute_script
-    script: { ref: actions }
-    subcommand: spec-check
-    args: ["--feature-dir", "{{feature_dir}}"]
-    outputs:
-      - { name: spec_ok,    from: "$.ok" }
-      - { name: spec_state, from: "$.state" }
   - id: spec_guard
-    action: verify_context
-    require_true: spec_ok
-    on_false: stop
-    on_false_message: "spec.md has moved outside the ledger (state: {{spec_state}}). Record what changed in a Change History row (or fold it back through /appweaver sync-spec), re-run spec-stamp to re-baseline, then re-run plan — a plan derived from an unledgered spec stamps a baseline the ledger cannot name."
+    action: include
+    module: .appweaver/orchestrator/modules/spec-state-gate.orch.yaml
+    with: { command: "/appweaver plan" }
 
   # 4. Scaffold backend-plan.md (idempotent). --lane backend resolves the pair
   #    design-template → backend-plan.md, and MIGRATES a legacy design.md by renaming
@@ -284,7 +276,7 @@ workflow:
     action: verify_context
     require_true: plan_stale
     on_false: stop
-    on_false_message: "backend-plan.md is in step with spec {{current_version}} — nothing to update."
+    on_false_message: "backend-plan.md is in step with spec {{current_version}} — nothing to update. If the PLAN is wrong and the spec is right, hand-edit backend-plan.md and re-run /appweaver plan with accept_manual: true — that is what tells this command to keep the edit's intent and reconcile it rather than treat it as drift; without the flag the manual fence stops the run after the edit is already on disk."
 
   # 5b. THE CODE. The plan is an architectural confirmation, so it must know what the
   #     feature already looks like on disk: concept-paths resolves the feature's OKF
@@ -549,6 +541,13 @@ workflow:
       - AN ID THE SPEC NO LONGER DEFINES LOSES ITS REALISATION: remove the elements
         that existed only to serve it (and their §6 rows). An id whose wording moved
         is re-realised from the spec's CURRENT text — the spec is the wording.
+      - AN ID THE SPEC HAS NEWLY DEFINED GAINS ONE. An id in the work list that NO
+        existing section realises is an ADDITION, not an error and not out of scope:
+        give it a home — the §1/§2/§3 elements that realise it, its §4.2 or §5 rows
+        where it needs them — and a §6 traceability row like any other. The scope rule
+        above says which sections may be touched; it does not say a new requirement may
+        not be designed, and reading it that way would let every added requirement
+        select nothing to rework and quietly land unrealised.
       - THE SPEC IS THE ONLY DOMAIN INPUT, same as at bootstrap: realise ids, invent
         nothing; an unavoidable new concept is a §7 DA-n.
       - THE CODE IS THE WHAT-EXISTS AUTHORITY, and it is a DIFFERENT authority from the
@@ -663,6 +662,40 @@ workflow:
       - { name: if_unknown_csv, from: "$.unknown_ids_csv" }
       - { name: if_badsup_csv,  from: "$.bad_supersedes_csv" }
 
+  # 7c. THE TWO INTEGRITY SIGNALS log-append ALREADY RETURNS. Both were bound and neither
+  #     was said out loud — the idiom every other integrity check in these workflows uses
+  #     is a verify_context that continues, and these had none.
+  #       unknown_ids_csv     an entry's `serves:` names an id the spec does not define,
+  #                           so the BE→FE contract anchor points at nothing.
+  #       bad_supersedes_csv  an entry supersedes one the log does not carry, so what it
+  #                           claims to replace is not there — and readers take the LATEST
+  #                           entry per interface, which is now ambiguous.
+  #     Announce-only: the entries are appended by the time this is visible, ids are
+  #     permanent, and an append-only log is corrected by a later entry, never by a rewrite.
+  - id: if_unknown_notice
+    condition: "{{if_unknown_csv}} != ''"
+    action: verify_context
+    require_value: if_unknown_csv
+    equals: ""
+    on_mismatch: continue
+    on_mismatch_message: >
+      interfaces.md now carries entries whose `serves:` names ids the spec does not define:
+      {{if_unknown_csv}}. That is a broken trace anchor in the BE→FE contract — the frontend
+      binds to these entries by id, and the requirement they claim to serve is not in
+      {{spec_file}}. Either the id is a typo, or the requirement was never specified: fix it
+      with a superseding entry (never by editing the log), or take it through /appweaver specify.
+  - id: if_badsup_notice
+    condition: "{{if_badsup_csv}} != ''"
+    action: verify_context
+    require_value: if_badsup_csv
+    equals: ""
+    on_mismatch: continue
+    on_mismatch_message: >
+      An entry appended to interfaces.md supersedes an id the log does not carry:
+      {{if_badsup_csv}}. Nothing was replaced, so the interface it meant to retire is still
+      the latest entry for its surface and both now read as current. Append a corrected
+      superseding entry naming the real id.
+
   # 8. Post-execution hooks.
   - id: resolve_post_hooks
     action: execute_script
@@ -685,4 +718,4 @@ outputs:
   interfaces_published: "{{if_ids_csv}}"
   interfaces_error: "{{if_error}}"
   source_files_read: "{{source_count}}"
-  next: "Gate this write: /appweaver analyze-design (spec ↔ plan conformance) — after EVERY bootstrap and EVERY update. Then the backlog and the stories: /appweaver sync-stories, then /appweaver story-plan <id>, which READS this plan and refuses to design against one the spec has moved past. {{fe_next}} READ THE FIELDS ABOVE FIRST: interfaces_published are the IF- ids this run appended to interfaces.md as status:proposed — cite them in the plan's API section on the next update, and never edit the log by hand; interfaces_error non-empty means the extraction was refused and .aw-if-new.tmp.md is still beside the plan for a hand-run of log-append, so THIS RUN PUBLISHED NOTHING; source_files_read 0 means no code was found for this feature, so the plan was written greenfield. NOTE while the pipeline is mid-rename: migrated_legacy_design=true means design.md is now backend-plan.md, and stages not yet rebuilt for the rename (implement, the delta chain) still look for design.md — rebuild or point them at backend-plan.md before relying on them."
+  next: "Gate this write: /appweaver analyze-design (spec ↔ plan conformance) — after EVERY bootstrap and EVERY update. Then the backlog and the stories: /appweaver sync-stories, then /appweaver story-plan <id>, which READS this plan and refuses to design against one the spec has moved past. {{fe_next}} READ THE FIELDS ABOVE FIRST: interfaces_published are the IF- ids this run appended to interfaces.md as status:proposed — cite them in the plan's API section on the next update, and never edit the log by hand; interfaces_error non-empty means the extraction was refused and .aw-if-new.tmp.md is still beside the plan for a hand-run of log-append, so THIS RUN PUBLISHED NOTHING; source_files_read 0 means no code was found for this feature, so the plan was written greenfield."

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

@@ -10,7 +10,8 @@
 # it wrote. It does not touch stories/. The spec is the CONTRACT; a story is an
 # execution SLICE over it, and the two directions between them each have their own
 # workflow — /appweaver sync-stories refreshes the backlog after the spec moves,
-# /appweaver update-spec folds a hand-edited story back into the contract. Keeping
+# /appweaver sync-spec (⌛ not yet built — .appweaver/SPEC-EDIT-PROTOCOL.md is the hand
+# route meanwhile) folds a hand-edited story back into the contract. Keeping
 # specify story-blind is what stops the spec->story rule having two implementations.
 #
 # Auto-detects first-vs-subsequent from spec.md:
@@ -392,6 +393,12 @@ workflow:
   #     nothing. Fed to the author as a preference, then checked against the diff below —
   #     the preference is a nudge, the check after the fact is the detector.
   #     Empty until the backlog exists, which degrades to "no preference, no ask".
+  #     CARRIED, NOT COVERED. `covered_csv` is the DELIVERY relation — the FR-/BR- ids open
+  #     stories are delivering — and a story also CARRIES the bounds it is built to satisfy.
+  #     Amending or removing a CN-/DC-/IC-/UX- moves ground somebody is standing on exactly
+  #     as amending an FR- does, and reading the narrower set here meant it raised no ask at
+  #     all and printed "nobody has open work" while stories were being built against it.
+  #     `carried_csv` is exercises: ∪ the `constraints:` frontmatter story-stamp lifts.
   - id: ext_story_context
     condition: "{{needs_bootstrap}} == false"
     action: execute_script
@@ -401,18 +408,21 @@ workflow:
     args: ["--feature-dir", "{{feature_dir}}"]
     outputs:
       - { name: covered_csv, from: "$.covered_csv" }
+      - { name: carried_csv, from: "$.carried_csv" }
+      - { name: backlog_scanned, from: "$.ok" }
 
   # 6b-bis. WORD THE PREFERENCE FOR THE CASE AT HAND. The rule below is an argument for
   #     preferring an ADDITION over an amendment, and it only makes sense while somebody is
-  #     actually building. Interpolating covered_csv straight into it left a spec with no
+  #     actually building. Interpolating the carried set straight into it left a spec with no
   #     backlog reading an eight-line case for adding requirements under a blank list — the
   #     logic was vacuous ("one of those" names nothing) but the rhetoric was not, and the
   #     first extend of a spec nobody has stories against is exactly where amending in place
-  #     is the honest thing to do. Two ordered sets rather than a compound condition, the
-  #     same idiom as readdit_verdict_na/_real: the no-backlog wording is the default, and
-  #     the preference replaces it only when there is open work to protect.
-  #     Safe on the bootstrap path too — ext_story_context is skipped there, so covered_csv
-  #     is empty and the second step cannot fire.
+  #     is the honest thing to do. THREE ORDERED SETS rather than a compound condition, the
+  #     same idiom as readdit_verdict_na/_real: the no-backlog wording is the default, the
+  #     preference replaces it where there is open work to protect, and the scan-failed
+  #     wording is last so it wins over both.
+  #     Safe on the bootstrap path too — ext_story_context is skipped there, so nothing is
+  #     bound and only the default can fire.
   - id: ext_covered_none
     action: set
     vars:
@@ -424,11 +434,13 @@ workflow:
         without inventing a companion requirement to avoid touching anything.
 
   - id: ext_covered_some
-    condition: "{{covered_csv}} != ''"
+    condition: "{{carried_csv}} != ''"
     action: set
     vars:
       covered_note: >
-        THESE REQUIREMENTS ARE BEING BUILT RIGHT NOW: {{covered_csv}}. Where the change can
+        THESE REQUIREMENTS AND BOUNDS ARE BEING BUILT AGAINST RIGHT NOW: {{carried_csv}}.
+        (FR-/BR- are what open stories DELIVER; CN-/DC-/IC-/UX- are what they are built to
+        MEET — moving either moves ground someone is standing on.) Where the change can
         be expressed EITHER as an amendment to one of those or as a new requirement
         alongside it, prefer the new requirement — an amendment moves ground someone is
         standing on, and a requirement that gains a companion leaves their work correct as
@@ -438,6 +450,21 @@ workflow:
         Requirements NOT in that list have no open work against them: amend those in place
         wherever the change genuinely belongs to them.
 
+  # THE SCAN ITSELF CAN FAIL, and ext_story_context carries `on_error: continue` because a
+  # spec must stay editable when its backlog cannot be read. What it must not do is answer
+  # as though the scan had run and found nothing: nothing binds, ext_covered_some cannot
+  # fire, and the unconditional default above then tells the author NOBODY HAS OPEN WORK —
+  # the strongest claim available, on no evidence at all.
+  - id: ext_covered_unknown
+    condition: "{{backlog_scanned}} != true"
+    action: set
+    vars:
+      covered_note: >
+        THE BACKLOG COULD NOT BE READ THIS RUN, so this run does not know who is building
+        what. Treat every requirement as possibly under way: prefer adding a requirement to
+        amending one, and where you must amend, say in the Change History row exactly what
+        moved so the next sync can find every story that carries it.
+
   - id: ext_ctx
     condition: "{{needs_bootstrap}} == false"
     action: build_context
@@ -755,6 +782,26 @@ workflow:
       - { name: disturbing_csv,  from: "$.disturbing_csv" }
       - { name: reissued_csv,    from: "$.reissued_csv" }
       - { name: change_count,    from: "$.change_count" }
+      - { name: diff_warnings,   from: "$.warnings_note" }
+
+  # 10a-bis. IDS THE LEDGER CANNOT KEY TO A DEFINITION. The diff keys an id to the line that
+  #      DEFINES it and hashes the block under it; three authoring forms fall outside that,
+  #      and each one is silent — the requirement moves, change_count stays 0, no row is
+  #      appended, and the stamp below re-baselines the new body as clean. A standing
+  #      property of the document rather than a verdict on this run, so it is reported every
+  #      time until the requirement is rewritten in the shape the template uses.
+  - id: diff_warning_notice
+    condition: "{{diff_warnings}} != ''"
+    action: verify_context
+    require_value: diff_warnings
+    equals: ""
+    on_mismatch: continue
+    on_mismatch_message: >
+      THE LEDGER CANNOT SEE PART OF THIS SPEC. {{spec_file}} states requirements in a form
+      the version diff cannot key to a definition, so an edit to one of them raises no
+      Change History row and no story citing it is ever told: {{diff_warnings}}. Rewrite them
+      in the template's shape — `- **FR-001**: …`, defined ABOVE the Change History table,
+      with any continuation on the lines directly under the id and no blank line between.
 
   # 10b. DID THIS MOVE GROUND SOMEONE IS STANDING ON? The diff is fact, so this is the
   #      detector the pre-authoring preference lacked: of the requirements this run
@@ -1065,6 +1112,23 @@ workflow:
     args: ["--feature-dir", "{{feature_dir}}", "--ids", "{{disturbing_csv}}"]
     outputs:
       - { name: disturbed_stories, from: "$.story_csv" }
+      - { name: final_refs_ok,     from: "$.ok" }
+
+  # 10h-bis. THE SAME HONESTY THE PRE-AUTHORING SCAN NOW HAS. This step carries
+  #      `on_error: continue` so a failed re-scan cannot strand a written document, and on
+  #      failure disturbed_stories binds to nothing — which the post-restore report (law 45)
+  #      then reads as "nobody was disturbed", the one claim it must not make on no evidence.
+  - id: final_refs_unknown_notice
+    condition: "{{final_refs_ok}} != true"
+    action: verify_context
+    require_value: final_refs_ok
+    equals: "true"
+    on_mismatch: continue
+    on_mismatch_message: >
+      The final backlog re-scan did not complete, so the disturbed-stories list below is
+      NOT a list of nobody — it is unknown. The requirements this run moved are
+      {{disturbing_csv}}; run /appweaver sync-stories to find and reconcile the stories
+      carrying them.
 
   # 10i. AN ID THE LEDGER HAS ALREADY SPENT. Ids are permanent: re-issuing a retired one
   #      silently re-points stories, designs and code that have already shipped, which is
@@ -1097,6 +1161,29 @@ workflow:
     outputs:
       - { name: ledger_version, from: "$.version" }
 
+  # 11a-bis. A PROSE-ONLY EDIT RE-BASELINES WITH NO ROW, AND SAYS SO. ledger-append is
+  #      conditional on change_count, because law 5 requires a version row to NAME at least
+  #      one id and an edit that touched no requirement has none to give. The stamp below is
+  #      not conditional, so this run rewrites the baseline and the document's own history
+  #      records nothing — which is right, and was silent. Aggregate Boundary, Experience
+  #      Scope and the rest of the load-bearing prose are read by every later phase and have
+  #      no staleness signal of their own; the least this can do is say that the baseline
+  #      moved and nothing recorded why.
+  - id: prose_only_notice
+    condition: "{{change_count}} == 0"
+    action: verify_context
+    require_value: needs_bootstrap
+    equals: "true"
+    on_mismatch: continue
+    on_mismatch_message: >
+      This run changed {{spec_file}} but moved no requirement: the diff found no id added,
+      modified or removed, so no Change History row was appended — a row must name at least
+      one id, and there is none to name. The document is still RE-BASELINED below, so the
+      next run reads it as clean. Nothing else is: if the edit touched load-bearing prose
+      (Aggregate Boundary, Experience Scope, Scope & Assumptions), no story is stale, no
+      sync will notice, and the only record is this message and your commit. Say what moved
+      in the commit message.
+
   # ═══════════════ STORY COVERAGE — both paths, before the baseline ══════════
   # 11b. Rewrite the spec's AW:COVERAGE block: every FR-/BR- in the document and the
   #      stories delivering it, read out of the stories/ frontmatter. The relation is
@@ -1105,7 +1192,7 @@ workflow:
   #
   #      Deliberately OUTSIDE the ledger. The hash guards the CONTRACT, and coverage is a
   #      projection of the backlog — spec-check, spec-diff and ledger-append all cut this
-  #      block out before they look. That is what lets user-story and sync-stories write
+  #      block out before they look. That is what lets add-story and sync-stories write
   #      it too without a story creation reading as an unledgered spec edit, or a story
   #      raised against FR-003 reading as FR-003 having changed.
   #

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

@@ -120,10 +120,31 @@ vars:
   fe_plan: ""
   spec_ok: "false"
   spec_state: ""
+  # the analyze-design verdict — law 40's evidence. certified defaults FALSE so a probe
+  # that could not run fails CLOSED, and the message default carries a route for the same
+  # reason: a refusal with no route is a wedged feature.
+  gate_status: ""
+  gate_certified: "false"
+  gate_aborted: "false"
+  gate_gap_refs: ""
+  gate_report: ""
+  gate_be_sha: ""
+  gate_fe_sha: ""
+  gate_spec_version: ""
+  gate_msg: "The analyze-design verdict could not be read, so this run cannot tell whether the feature plans were ever certified. Run /appweaver analyze-design, then re-run story-plan."
+  # what has to land first (read here, gated nowhere — see deps_notice)
+  story_wave: ""
+  depends_on_csv: ""
+  open_deps_csv: ""
+  unresolved_deps_csv: ""
+  deps_clear: "true"
+  deps_note: ""
   # per-lane feature-plan freshness (the one-way coupling: a story pass READS a plan)
   be_plan_state: ""
   be_plan_derived: ""
   be_plan_changed: ""
+  be_plan_sha: ""
+  fe_plan_sha: ""
   be_plan_note: ""
   be_drop_msg: ""
   be_dropped: "false"
@@ -246,19 +267,10 @@ workflow:
   # 3. The spec's ledger tripwire: no design pass from an unledgered spec — every
   #    pass records the spec version it designed against, and an unledgered edit has
   #    no version to record.
-  - id: spec_guard_read
-    action: execute_script
-    script: { ref: actions }
-    subcommand: spec-check
-    args: ["--feature-dir", "{{feature_dir}}"]
-    outputs:
-      - { name: spec_ok,    from: "$.ok" }
-      - { name: spec_state, from: "$.state" }
   - id: spec_guard
-    action: verify_context
-    require_true: spec_ok
-    on_false: stop
-    on_false_message: "spec.md has moved outside the ledger (state: {{spec_state}}). Record what changed in a Change History row (fold it back through the spec workflow), re-run spec-stamp to re-baseline, then re-run story-plan — a design pass derived from an unledgered spec records a baseline the ledger cannot name."
+    action: include
+    module: .appweaver/orchestrator/modules/spec-state-gate.orch.yaml
+    with: { command: "/appweaver story-plan" }
 
   # 4. THE FEATURE-PLAN GATES, one per declared lane. A story design is a SLICE of
   #    the feature's architecture, so it READS that lane's plan and NEVER writes
@@ -286,6 +298,10 @@ workflow:
       - { name: be_plan_state,   from: "$.state" }
       - { name: be_plan_derived, from: "$.derived_version" }
       - { name: be_plan_changed, from: "$.changed_csv" }
+      # THE PLAN'S SHAPE, not just whether it moved. The certification check below compares
+      # this against the hash analyze-design recorded in its verdict — which is the only way
+      # to tell "approved" from "approved, then edited".
+      - { name: be_plan_sha,     from: "$.body_sha256" }
   - id: fe_plan_read
     condition: "{{fe_in_scope}} == true"
     action: execute_script
@@ -297,6 +313,7 @@ workflow:
       - { name: fe_plan_state,   from: "$.state" }
       - { name: fe_plan_derived, from: "$.derived_version" }
       - { name: fe_plan_changed, from: "$.changed_csv" }
+      - { name: fe_plan_sha,     from: "$.body_sha256" }
 
   # 4a. SERVICE lane verdict. Only `clean` and `edited` keep the lane; every other
   #     state (including the empty string a crashed probe leaves) drops it.
@@ -494,6 +511,14 @@ workflow:
       - { name: fe_next_pass,       from: "$.fe_next_pass" }
       - { name: fe_pass_tmp,        from: "$.fe_pass_tmp" }
       - { name: if_tmp,             from: "$.if_tmp" }
+      - { name: story_wave,          from: "$.story_wave" }
+      - { name: depends_on_csv,      from: "$.depends_on_csv" }
+      - { name: open_deps_csv,       from: "$.open_deps_csv" }
+      - { name: unresolved_deps_csv, from: "$.unresolved_deps_csv" }
+      - { name: deps_clear,          from: "$.deps_clear" }
+      - { name: deps_note,           from: "$.deps_note" }
+      - { name: be_pass_plan_hash,   from: "$.be_pass_plan_hash" }
+      - { name: fe_pass_plan_hash,   from: "$.fe_pass_plan_hash" }
   - id: require_story
     action: verify_context
     require_true: resolved
@@ -511,6 +536,25 @@ workflow:
   # 5a. A dropped lane is announced HERE — after the story is known, so the notice
   #     names the story it applies to, and before any write, so the author can stop
   #     and fix the plan rather than discovering the gap after a pass has landed.
+  # 5.0 WHAT HAS TO LAND FIRST. sync-stories computes depends_on: and wave: and stamps both
+  #     into every story, and until now nothing downstream read either — the ordering was
+  #     recorded and never enforced, in the one place with a story in hand to enforce it on.
+  #     A NOTICE, NOT A REFUSAL: a dependency is about CODE ordering, and designing against
+  #     work that has not landed is legitimate — it is BUILDING against it that starts to
+  #     cost something. Two misses are kept apart: a dependency still OPEN in this feature
+  #     is work in progress, and one with no story file here is UNRESOLVED, which is the
+  #     ordinary shape of a cross-feature edge and not at all the same as satisfied.
+  #     Deliberately NOT "an open story in a lower wave": a story becomes startable when its
+  #     OWN dependencies land, not when the whole previous wave finishes, so warning on the
+  #     wave would serialise a level that exists precisely to be unordered. The wave is
+  #     surfaced and gated by nothing.
+  - id: deps_notice
+    condition: "{{deps_clear}} != true"
+    action: verify_context
+    require_true: deps_clear
+    on_false: continue
+    on_false_message: "{{deps_note}}"
+
   - id: be_drop_notice
     condition: "{{be_dropped}} == true"
     action: verify_context
@@ -526,6 +570,120 @@ workflow:
     on_mismatch: continue
     on_mismatch_message: "{{fe_drop_msg}}"
 
+  # ═══════ 5a-bis. LAW 40 — approved, changed, never re-approved must not reach code ═══════
+  # analyze-design certifies the feature plans and writes a machine-readable verdict beside
+  # its report. Nothing in the kit read one back, so "was this plan approved, and was it
+  # approved in the shape it is in NOW" was a question only a person opening the JSON could
+  # answer — and this is the phase that turns a feature plan into a slice design that
+  # implement builds from without ever re-asking it.
+  #
+  # HERE, AND NOT AT be_plan_read. Those probes feed the drop-on-behind decision above;
+  # gating there would change WHICH lanes get dropped. This runs after the keep/drop set is
+  # settled and before anything is authored, so it can supersede be_keep_edited — that step
+  # keeps an edited plan and tells the author it "is authoritative here", which is exactly
+  # the state law 40 forbids when nobody certified the edit.
+  - id: gate_verdict
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: gate-read
+    args: ["--feature-dir", "{{feature_dir}}", "--gate", "analyze-design"]
+    outputs:
+      - { name: gate_status,       from: "$.status" }
+      - { name: gate_certified,    from: "$.certified" }
+      - { name: gate_aborted,      from: "$.aborted" }
+      - { name: gate_gap_refs,     from: "$.gap_refs_csv" }
+      - { name: gate_report,       from: "$.report" }
+      - { name: gate_be_sha,       from: "$.backend_sha256" }
+      - { name: gate_fe_sha,       from: "$.frontend_sha256" }
+      - { name: gate_spec_version, from: "$.spec_version" }
+
+  # THREE REASONS, THREE ROUTES, and telling them apart is the whole value. Ordered sets,
+  # last match wins: never ran → gated red → started and aborted. Aborted is last because it
+  # also carries status "fail" (gate_result_open writes a red BEFORE any analysis, so an
+  # abandoned run never leaves a stale green) and sending someone to read gaps that were
+  # never found is the one wrong answer here.
+  - id: gate_msg_never
+    action: set
+    vars:
+      gate_msg: "The feature plans for this feature have never been certified: there is no analyze-design verdict beside them. A story design turns the feature plan into the slice implement builds, so designing against an ungated plan puts an unapproved architecture into code through two documents that never re-ask the question. Run /appweaver analyze-design, then re-run story-plan {{story}}."
+  - id: gate_msg_red
+    condition: "{{gate_status}} == fail"
+    action: set
+    vars:
+      gate_msg: "The feature plans do NOT conform to the spec: analyze-design's last verdict is FAIL on {{gate_gap_refs}}. The full report is at {{gate_report}}. Close those gaps first — a wrong PLAN is repaired by re-running /appweaver analyze-design and accepting the repair, or by hand-editing it and re-running /appweaver plan (or plan-ui) with accept_manual: true; a wrong SPEC goes through the spec route. Then re-run story-plan {{story}}."
+  - id: gate_msg_aborted
+    condition: "{{gate_aborted}} == true"
+    action: set
+    vars:
+      gate_msg: "The last analyze-design run STARTED and never reached a verdict — the red on disk is the one it writes before any analysis, so nothing was found and there are no gaps to go and read. The plans are UNCERTIFIED, not rejected. Run /appweaver analyze-design to completion, then re-run story-plan {{story}}."
+
+  - id: gate_certified_guard
+    condition: "{{have_lane}} == true"
+    action: verify_context
+    require_true: gate_certified
+    on_false: stop
+    on_false_message: "{{gate_msg}}"
+
+  # PER KEPT LANE, and only per kept lane. A lane that is undeclared or was dropped above
+  # has no certified hash and must not fail the run for lacking one.
+  # An EMPTY recorded hash fails the comparison, and that is correct: a verdict that does
+  # not say which shape it certified cannot prove this is that shape.
+  - id: be_certified_shape
+    condition: "{{be_in_scope}} == true"
+    action: verify_context
+    require_value: be_plan_sha
+    equals: "{{gate_be_sha}}"
+    on_mismatch: stop
+    on_mismatch_message: "backend-plan.md is not the document analyze-design certified — it has been edited since (or the verdict predates hash recording and cannot say what it approved). Designing this slice against it would carry an unapproved architecture into code, which is exactly what law 40 forbids. Re-run /appweaver analyze-design to certify the plan as it now stands, then re-run story-plan {{story}}."
+  - id: fe_certified_shape
+    condition: "{{fe_in_scope}} == true"
+    action: verify_context
+    require_value: fe_plan_sha
+    equals: "{{gate_fe_sha}}"
+    on_mismatch: stop
+    on_mismatch_message: "frontend-plan.md is not the document analyze-design certified — it has been edited since (or the verdict predates hash recording and cannot say what it approved). Re-run /appweaver analyze-design to certify the plan as it now stands, then re-run story-plan {{story}}."
+
+  # ═══════ 5a-ter. WHICH LANES THIS STORY WAS DESIGNED FOR, AND WHICH WERE DROPPED ═══════
+  # Two fields, because one of them cannot say the difference. analyze-design STOPS on a
+  # lane whose plan is behind; this workflow DROPS it and designs the other — so one command
+  # later "this slice has no user-facing surface" and "the UI lane was out of scope when it
+  # was designed" are the same state on disk, and a UX--bearing requirement can ship
+  # backend-only with a green story-scoped gate.
+  # story-stamp is the frontmatter writer, and every one of its fields is guarded by its own
+  # flag, so these calls touch nothing else in the story. One per lane per outcome, because
+  # the keys UNION: a lane that has ever been designed keeps saying so.
+  # NOT story-plan-doc — that writes the PASS, and a dropped lane has no pass, which is the
+  # entire point. NOT sync-stories — stories are not designed there.
+  - id: stamp_lane_be_designed
+    condition: "{{be_in_scope}} == true"
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: story-stamp
+    args: ["--feature-dir", "{{feature_dir}}", "--story", "{{story}}", "--designed-lanes", "backend"]
+  - id: stamp_lane_be_dropped
+    condition: "{{be_dropped}} == true"
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: story-stamp
+    args: ["--feature-dir", "{{feature_dir}}", "--story", "{{story}}", "--dropped-lanes", "backend"]
+  - id: stamp_lane_fe_designed
+    condition: "{{fe_in_scope}} == true"
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: story-stamp
+    args: ["--feature-dir", "{{feature_dir}}", "--story", "{{story}}", "--designed-lanes", "frontend"]
+  - id: stamp_lane_fe_dropped
+    condition: "{{fe_dropped}} == true"
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: story-stamp
+    args: ["--feature-dir", "{{feature_dir}}", "--story", "{{story}}", "--dropped-lanes", "frontend"]
+
   # 5b. A pre-split story-plan.md beside the story is REPORTED, never read and never
   #     written. Silently leaving it there would leave a design document nobody
   #     consumes sitting beside two that are read — and the next person to open the
@@ -706,7 +864,12 @@ workflow:
     action: execute_script
     script: { ref: actions }
     subcommand: story-plan-doc
-    args: ["--feature-dir", "{{feature_dir}}", "--story", "{{story}}", "--lane", "backend", "--pass-file", "{{be_pass_tmp}}", "--spec-version", "{{current_version}}"]
+    # --plan-hash stamps the CERTIFIED feature-plan hash into the pass header — the one
+    # analyze-design recorded, which the guard above has just proved is the plan on disk.
+    # A pass is written once and read forever, so without it implement could only ask
+    # "is the plan certified NOW", and a pass designed against plan H1 would still
+    # generate after the plan was edited to H2 and re-gated — the exact case law 40 names.
+    args: ["--feature-dir", "{{feature_dir}}", "--story", "{{story}}", "--lane", "backend", "--pass-file", "{{be_pass_tmp}}", "--spec-version", "{{current_version}}", "--plan-hash", "{{gate_be_sha}}"]
     outputs:
       - { name: be_pass_n,  from: "$.pass" }
       - { name: be_created, from: "$.created" }
@@ -778,6 +941,40 @@ workflow:
       - { name: if_unknown_csv, from: "$.unknown_ids_csv" }
       - { name: if_badsup_csv,  from: "$.bad_supersedes_csv" }
 
+  # 7c. THE TWO INTEGRITY SIGNALS log-append ALREADY RETURNS. Both were bound and neither
+  #     was said out loud — the idiom every other integrity check in these workflows uses
+  #     is a verify_context that continues, and these had none.
+  #       unknown_ids_csv     an entry's `serves:` names an id the spec does not define,
+  #                           so the BE→FE contract anchor points at nothing.
+  #       bad_supersedes_csv  an entry supersedes one the log does not carry, so what it
+  #                           claims to replace is not there — and readers take the LATEST
+  #                           entry per interface, which is now ambiguous.
+  #     Announce-only: the entries are appended by the time this is visible, ids are
+  #     permanent, and an append-only log is corrected by a later entry, never by a rewrite.
+  - id: if_unknown_notice
+    condition: "{{if_unknown_csv}} != ''"
+    action: verify_context
+    require_value: if_unknown_csv
+    equals: ""
+    on_mismatch: continue
+    on_mismatch_message: >
+      interfaces.md now carries entries whose `serves:` names ids the spec does not define:
+      {{if_unknown_csv}}. That is a broken trace anchor in the BE→FE contract — the frontend
+      binds to these entries by id, and the requirement they claim to serve is not in
+      {{spec_file}}. Either the id is a typo, or the requirement was never specified: fix it
+      with a superseding entry (never by editing the log), or take it through /appweaver specify.
+  - id: if_badsup_notice
+    condition: "{{if_badsup_csv}} != ''"
+    action: verify_context
+    require_value: if_badsup_csv
+    equals: ""
+    on_mismatch: continue
+    on_mismatch_message: >
+      An entry appended to interfaces.md supersedes an id the log does not carry:
+      {{if_badsup_csv}}. Nothing was replaced, so the interface it meant to retire is still
+      the latest entry for its surface and both now read as current. Append a corrected
+      superseding entry naming the real id.
+
   # ══════════════════════ THE UI DESIGN (payload-only + Read) ══════════════════
   # The UI lane's rules load here, AFTER the service pass has been written, so a
   # service author is never handed component and styling rules. The pass reads the
@@ -913,7 +1110,12 @@ workflow:
     action: execute_script
     script: { ref: actions }
     subcommand: story-plan-doc
-    args: ["--feature-dir", "{{feature_dir}}", "--story", "{{story}}", "--lane", "frontend", "--pass-file", "{{fe_pass_tmp}}", "--spec-version", "{{current_version}}"]
+    # --plan-hash stamps the CERTIFIED feature-plan hash into the pass header — the one
+    # analyze-design recorded, which the guard above has just proved is the plan on disk.
+    # A pass is written once and read forever, so without it implement could only ask
+    # "is the plan certified NOW", and a pass designed against plan H1 would still
+    # generate after the plan was edited to H2 and re-gated — the exact case law 40 names.
+    args: ["--feature-dir", "{{feature_dir}}", "--story", "{{story}}", "--lane", "frontend", "--pass-file", "{{fe_pass_tmp}}", "--spec-version", "{{current_version}}", "--plan-hash", "{{gate_fe_sha}}"]
     outputs:
       - { name: fe_pass_n,  from: "$.pass" }
       - { name: fe_created, from: "$.created" }