aw-spec-cli 0.1.15 → 0.1.16

package/assets/.appweaver/orchestrator/modules/spec-state-gate.orch.yaml

@@ -0,0 +1,87 @@
+# =============================================================================
+# spec-state-gate (orchestrator) — the ledger tripwire, gated on STATE
+#
+# Included by every phase that READS spec.md as an oracle and does not stamp it.
+# It answers one question before that phase starts doing work:
+#
+#     is spec.md's version an honest name for spec.md's contents?
+#
+# WHY THE `ok` BOOLEAN IS NOT ENOUGH. spec-check's decisive branch asks only "is
+# there a version ROW above the version the kit last recorded", and never opens the
+# body. Two of its states are therefore ok:true with a body nobody has re-baselined:
+#
+#   ledgered_edit   a row exists above the recorded version — the edit was RECORDED,
+#                   but the kit has not re-hashed, so every LATER edit lands inside
+#                   the same window and passes the same test. Verified: a requirement
+#                   DELETED with no row naming it passes.
+#   header_behind   the same, with the document's header not yet caught up.
+#
+# Both are legitimate transient states and both have the same remedy — spec-stamp,
+# which re-baselines the hash and closes the window. That remedy is already named in
+# these phases' own refusal messages and in SPEC-EDIT-PROTOCOL.md.
+#
+# WHY NOT FLIP `ok` INSTEAD. Because specify is the stamper. It MUST keep accepting
+# both states — it is the command that resolves them — so making spec-check refuse
+# them would wedge the one workflow that can fix them. The distinction belongs at the
+# consumer, which is what this module is.
+#
+# WHAT IT DOES NOT DO. It never stamps, never edits and never repairs. Every state
+# spec-check already refuses (unrowed_edit, unledgered_edit, rollback, no_ledger,
+# delta_open) still stops on `ok`, with spec-check's own message.
+#
+# Inputs (via include `with`):
+#   command  — the phase being gated, quoted back in the failure message
+#
+# Produces: spec_ok / spec_state (the raw answers) and spec_current (true when the
+# state is one this phase may read from), for a caller that wants to say more.
+# =============================================================================
+
+name: spec-state-gate
+dialect: aw-spec.orchestrator/v1
+
+scripts:
+  actions:
+    sh:  .appweaver/scripts/bash/aw-spec-actions.sh
+    ps1: .appweaver/scripts/powershell/aw-spec-actions.ps1
+
+workflow:
+
+  - 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" }
+
+  # The states spec-check itself refuses. Kept first and kept separate: its own error
+  # text says which one and why, and this module has nothing to add to it.
+  - id: spec_guard
+    action: verify_context
+    require_true: spec_ok
+    on_false: stop
+    on_false_message: "{{command}} cannot run: spec.md has moved outside the ledger (state: {{spec_state}}), so its version no longer names its contents and nothing read from it can be trusted. Record what changed in a Change History row naming the ids, then re-run spec-stamp to re-baseline — or, when the edit touched no requirement at all, spec-stamp alone (see .appweaver/SPEC-EDIT-PROTOCOL.md)."
+
+  # The two states that pass `ok` and still leave the body un-baselined. Ordered sets
+  # rather than a compound condition — the evaluator takes single comparisons only, so
+  # the refusal is the default and each acceptable state lifts it.
+  - id: spec_state_default
+    action: set
+    vars: { spec_current: "false" }
+  - id: spec_state_clean
+    condition: "{{spec_state}} == clean"
+    action: set
+    vars: { spec_current: "true" }
+  # A pre-ledger spec the kit has never stamped. Legitimate: nothing has been recorded
+  # against it, so there is no window between a row and a baseline to fall into.
+  - id: spec_state_unstamped
+    condition: "{{spec_state}} == unstamped"
+    action: set
+    vars: { spec_current: "true" }
+
+  - id: spec_state_gate
+    action: verify_context
+    require_true: spec_current
+    on_false: stop
+    on_false_message: "{{command}} cannot run: spec.md is in state '{{spec_state}}' — the edit is recorded in a Change History row, but the kit has not re-baselined the document, so its recorded hash still describes the text before the edit. Until it does, every FURTHER edit passes the same tripwire unnoticed, including a requirement deleted with no row naming it. Run /appweaver specify (which stamps), or re-run spec-stamp to re-baseline directly, then re-run {{command}}."

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

@@ -51,7 +51,7 @@
 #   • 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  (never repaired here)
+#   • 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
 #
@@ -87,6 +87,10 @@ vars:
   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
@@ -108,6 +112,9 @@ vars:
   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: ""
@@ -198,19 +205,10 @@ workflow:
   #     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_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}}), so its version no longer names its contents and no plan can be certified against it. 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 analyze-design."
+    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
@@ -404,8 +402,8 @@ workflow:
       - 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>", 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: "", backend_repair: false, frontend_repair: false, gaps: [] }
+        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}},
@@ -487,6 +485,15 @@ workflow:
           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" }
@@ -494,6 +501,7 @@ workflow:
           - { 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
@@ -521,7 +529,13 @@ workflow:
           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.
-        options: ["Repair", "Report and Skip"]
+        # 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
@@ -598,7 +612,16 @@ workflow:
         action: execute_script
         script: { ref: actions }
         subcommand: plan-stamp
-        args: ["--doc", "{{be_plan}}", "--feature-dir", "{{feature_dir}}", "--ids", "{{gap_refs}}", "--note", "Conformance repair (analyze-design)"]
+        # --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" }
@@ -640,7 +663,9 @@ workflow:
         action: execute_script
         script: { ref: actions }
         subcommand: plan-stamp
-        args: ["--doc", "{{fe_plan}}", "--feature-dir", "{{feature_dir}}", "--ids", "{{gap_refs}}", "--note", "Conformance repair (analyze-design)"]
+        # 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" }
@@ -680,6 +705,12 @@ workflow:
       - "# 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
@@ -694,6 +725,31 @@ workflow:
       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;
@@ -703,7 +759,15 @@ workflow:
     script: { ref: actions }
     subcommand: gate-result
     # The lenient loader needs a flow sequence on ONE line.
-    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", "frontend_plan={{fe_plan}}", "--field", "frontend_in_scope={{fe_in_scope}}", "--field", "frontend_state={{fe_state}}", "--field", "frontend_derived={{fe_derived}}"]
+    # 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" }
 

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

@@ -234,6 +234,17 @@ workflow:
     on_false: stop
     on_false_message: "No spec.md for the current feature. Run /appweaver specify first — the spec is this gate's oracle, and code cannot be conformed to a contract that does not exist."
 
+  # THE ORACLE HAS TO BE HONEST ABOUT ITS OWN VERSION. This is the only gate whose
+  # declared oracle IS spec.md — every judgement below resolves an id's meaning from it
+  # — and it stamps {{current_version}} into the machine-readable verdict a pipeline
+  # branches on. A spec whose version no longer names its contents makes that stamp a
+  # false claim about what was certified, so the fence every other consumer carries
+  # belongs here most of all.
+  - id: spec_state_guard
+    action: include
+    module: .appweaver/orchestrator/modules/spec-state-gate.orch.yaml
+    with: { command: "/appweaver analyze-slice" }
+
   # 1. WHICH STORY, if any. An id in the input scopes the gate to that story; anything
   #    else widens it to the feature. Deliberately NO ask: this gate has to be runnable
   #    unattended, and a gate that stops to ask cannot run in CI. Naming a story narrows
@@ -302,7 +313,7 @@ workflow:
     condition: "{{story_resolved}} == false"
     action: set
     vars:
-      scope_brief: "SCOPE — the WHOLE FEATURE, because no story was named. In scope: every FR- and BR- you can see in spec.md EXCEPT these, which have OPEN stories and are work in flight rather than drift: {{inflight_csv}}. EXTENT — the whole of each in-scope id. Also in scope are the CN-/DC-/IC-/UX- the spec binds this feature by."
+      scope_brief: "SCOPE — the WHOLE FEATURE, because no story was named. In scope: every FR- and BR- you can see in spec.md EXCEPT these, which have OPEN stories and are work in flight rather than drift: {{inflight_csv}}. EXTENT — the whole of each in-scope id. Also in scope are the CN-/DC-/IC-/UX- the spec binds this feature by, and the SC- Success Criteria — this phase is the one the spec names as their verifier, and a feature-scoped run is the only scope at which a feature-level outcome can be judged. SC- is scored differently from every other class; see the SUCCESS CRITERIA rules below."
   - id: bridge_story
     condition: "{{story_be_exists}} == true"
     action: set
@@ -386,6 +397,14 @@ workflow:
     args: ["--feature-dir", "{{feature_dir}}", "--ids", "{{exercises_csv}}"]
     outputs:
       - { name: all_paths,       from: "$.all_paths" }
+      # THE SAME FILES AS A CSV, for the steps that name them in a prompt instead of
+      # inlining them. `context_from: all_paths` APPENDS every one of those paths to the
+      # envelope, and the engine reads the envelope IN FULL into the user block — so this
+      # gate inlined the feature's whole codebase four times over, and again on every fix
+      # iteration. Every consumer of that list can open a file itself; what it needed was
+      # to be told which files, not to be handed their contents.
+      - { name: all_csv,         from: "$.all_csv" }
+      - { name: all_count,       from: "$.all_count" }
       - { name: paths_missing,   from: "$.all_missing_csv" }
       - { name: coverage_digest, from: "$.digest" }
       - { name: be_count,        from: "$.backend_count" }
@@ -443,18 +462,23 @@ workflow:
         vars:
           test_log: "{{test_log}}"
           no_test_edit_rule: "{{no_test_edit_rule}}"
+          all_csv: "{{all_csv}}"
+          all_count: "{{all_count}}"
         context:
           - { path: "{{spec_file}}" }
-        context_from: all_paths
       - id: fix
         action: agent_generate
         tools: "Read,Write,Edit,Bash"
         permission_mode: acceptEdits
         task: |
           Tests failed. Make them pass by fixing the code (or a genuinely wrong
-          test) in the files in context, keeping behaviour aligned with the spec's
-          acceptance criteria (spec in context). {{no_test_edit_rule}} Test log:
+          test), keeping behaviour aligned with the spec's acceptance criteria (spec
+          in context). {{no_test_edit_rule}} Test log:
           {{test_log}}
+
+          This slice's code, both lanes ({{all_count}} file(s)) — READ the ones the
+          failures point at; they are named, not inlined:
+            {{all_csv}}
         outputs:
           - { name: fixed_files, from: "$.files" }
 
@@ -549,8 +573,10 @@ workflow:
       to a FUNCTIONAL story citing the requirement it moves. Two ways out, and they are not
       interchangeable: restore the tests and make the refactor behaviour-preserving, or
       accept that this work changes behaviour — close this story as cancelled, raise a
-      functional story for the change through /appweaver sync-spec (if the contract moves)
-      or /appweaver add-story, and build it there where an FR- can be traced to it.
+      functional story for the change through /appweaver sync-spec (⌛ not yet built — until it is, fold the change back by hand under .appweaver/SPEC-EDIT-PROTOCOL.md) (if the contract moves)
+      or by raising a story by hand from .appweaver/templates/story-template.md
+      (/appweaver add-story, which mints the id and stamps the frontmatter, is ⌛ not yet
+      built), and build it there where an FR- can be traced to it.
 
   # ═══════ PASS 3 — DOMAIN CONFORMANCE: code vs the gate overlay checklist ═══════
   # With tests green, scan the feature's CODE against the domain gate overlays (the
@@ -578,18 +604,26 @@ workflow:
         action: build_context
         vars:
           no_test_edit_rule: "{{no_test_edit_rule}}"
+          all_csv: "{{all_csv}}"
+          all_count: "{{all_count}}"
         context:
           - { path: "{{spec_file}}" }
-        context_from: all_paths
       - id: check_overlays
         action: agent_query
+        # A query step is PAYLOAD-ONLY unless it declares tools. It read the code because
+        # context_from inlined every file; naming them instead without granting Read would
+        # leave it reasoning about a codebase it cannot open.
+        tools: Read
         include_standards: true            # the gate overlays (checklist) are in the standards
         schema: { ok: true, violations: [ { rule: "<overlay rule / id>", where: "<file:symbol>", issue: "<what is violated>" } ] }
         mock: { ok: true, violations: [] }
         task: |
           The domain gate checklist is loaded in the standards (the overlay
-          forbidden-patterns, refusal conditions, and CI gates). Check the feature's
-          generated code + tests (in context) against EACH checklist rule and list
+          forbidden-patterns, refusal conditions, and CI gates). This slice's code and
+          tests, both lanes ({{all_count}} file(s)) — READ them; they are named, not
+          inlined:
+            {{all_csv}}
+          Check them against EACH checklist rule and list
           EVERY violation, e.g.: a hard delete of a retention-protected aggregate /
           version history / audit record; a second write path bypassing the aggregate
           or interop adapter; an invented/free-text coded value where a validated code
@@ -666,12 +700,16 @@ workflow:
       referrer_names: "{{referrer_names}}"
       referrer_count: "{{referrer_count}}"
       integrity_log: "{{integrity_log}}"
+      all_csv: "{{all_csv}}"
+      all_count: "{{all_count}}"
     context:
       - { path: "{{spec_file}}" }
-    context_from: all_paths
   - id: write_broken_referrers
     action: agent_author
     condition: "{{integrity_ok}} != true"
+    # An author step is PAYLOAD-ONLY unless it declares tools. The triage report has to
+    # name what this slice CHANGED that the referrers depend on, which means reading it.
+    tools: Read
     include_standards: false                       # a triage report, not generated code
     output_target: { type: file, path: "{{feature_dir}}/broken-referrers.md" }
     task: |
@@ -681,6 +719,9 @@ workflow:
       referrer (that is the referrer's own slice's job). Referrer blast radius
       ({{referrer_count}}): {{referrer_names}}. Failing test log:
       {{integrity_log}}
+      This slice's code, both lanes ({{all_count}} file(s)) — READ what it changed on the
+      published surface to say WHY the referrers broke; the files are named, not inlined:
+        {{all_csv}}
       Write markdown, in this order:
       - `# Broken Referrers — <feature>` and a one-line statement of what this file is:
         aggregates that USE this feature and whose tests went red when this feature's
@@ -730,6 +771,8 @@ workflow:
       bridge_note: "{{bridge_note}}"
       coverage_digest: "{{coverage_digest}}"
       stale_note: "{{stale_note}}"
+      all_csv: "{{all_csv}}"
+      all_count: "{{all_count}}"
     context:
       - { path: "{{spec_file}}" }                       # THE ORACLE — the contract's own wording
       - { path: "{{story_path}}", optional: true }      # the extent: what this slice claims of each id
@@ -739,12 +782,11 @@ workflow:
       - { path: "{{fe_plan}}", optional: true }
       - { path: "{{feature_dir}}/interfaces.md", optional: true }   # the published surface, cited by IF- id
       - { path: "{{feature_dir}}/adr.md", optional: true }          # ratified decisions
-    context_from: all_paths                             # the CODE — both lanes, from the OKF concept
   - id: trace
     action: agent_query
     tools: Read                          # follow a call out of the listed files when a trace needs it
     include_standards: false             # the contract is the spec, not a rule corpus
-    schema: { ok: true, bridge_ok: true, gap_count: 0, gap_refs: "<comma-separated spec ids the gaps touch>", coverage: "<one line per in-scope id — id | what the spec requires | the design element that maps it | the code that realises it | DELIVERED or GAP>", gaps: [ { severity: "high", spec_ref: "<FR/BR/CN/DC/IC/UX id>", kind: "code-missing|code-wrong|bridge-missing|spec-wrong", where: "<file:symbol, or the document>", gap: "<what the spec requires and what is actually there>", route: "<the command that fixes it>" } ], bridge_gaps: "<one line per in-scope id no design maps, or empty>" }
+    schema: { ok: true, bridge_ok: true, gap_count: 0, gap_refs: "<comma-separated spec ids the gaps touch>", coverage: "<one line per in-scope id — id | what the spec requires | the design element that maps it | the code that realises it | DELIVERED or GAP>", gaps: [ { severity: "high", spec_ref: "<FR/BR/CN/DC/IC/UX/SC id>", kind: "code-missing|code-wrong|bridge-missing|spec-wrong", where: "<file:symbol, or the document>", gap: "<what the spec requires and what is actually there>", route: "<the command that fixes it>" } ], bridge_gaps: "<one line per in-scope id no design maps, or empty>" }
     mock: { ok: true, bridge_ok: true, gap_count: 0, gap_refs: "", coverage: "", gaps: [], bridge_gaps: "" }
     task: |
       spec.md is the ORACLE. Judge the CODE against it and report every id it fails to
@@ -757,9 +799,11 @@ workflow:
 
       {{bridge_note}}
 
-      The code in context is this slice's whole OKF file list, both lanes. Use Read to
-      follow anything it calls that a trace needs. Do NOT modify a single file — this
-      step is read-only by contract.
+      THIS SLICE'S CODE, both lanes, from the OKF concept ({{all_count}} file(s)) — READ
+      the ones each id's trace needs, and follow anything they call. They are named here
+      rather than inlined, because a real codebase does not fit a payload:
+        {{all_csv}}
+      Do NOT modify a single file — this step is read-only by contract.
 
       {{coverage_digest}}
 
@@ -777,6 +821,29 @@ workflow:
           a home in each. A UX- lives only in the UI lane; a BR- only in the service
           lane. Do not report a UI gap for a slice that has no UI lane in scope.
 
+      SUCCESS CRITERIA (SC-) ARE SCORED AS OUTCOMES, NOT AS REALISATIONS. An SC- is a
+      measurable result the whole feature is supposed to produce — "a customer can place
+      an order in under two minutes", "90% of first-time users complete an order without
+      assistance" — so no design element "maps" one and no file "realises" one. Four
+      rules, and they override steps (2) and (3) and the ok/bridge_ok sentences below for
+      this class alone:
+        • Score each in-scope SC- as MET, NOT MET, or NOT ASSESSABLE FROM A STATIC READ.
+          Most are the third: a latency budget, an adoption rate or a support-ticket
+          reduction cannot be decided by reading code, and inventing a verdict is worse
+          than recording that it needs measuring.
+        • NOT ASSESSABLE is not a gap. It does not set ok=false and it is not counted in
+          gap_count — say in its `coverage` line what would have to be measured, and by
+          what, to settle it.
+        • NOT MET does fail ok: reserve it for the case where the code plainly cannot
+          satisfy the criterion (the feature has no such surface at all, or the design
+          rules the outcome out).
+        • An SC- NEVER sets bridge_ok=false and is NEVER a "bridge-missing" gap. There is
+          no design element to be missing, so routing one to story-plan sends someone to
+          design a document entry that should not exist.
+      Every in-scope SC- still gets its `coverage` line. The record is the point: this is
+      the phase the spec names as their verifier, and "measured how, and when" is the
+      answer it is meant to leave behind.
+
       CLASSIFY every gap by `kind`, because the four routes are different commands:
         code-missing   the design maps the id and no code realises it   → /appweaver implement
         code-wrong     code exists and does something else              → /appweaver implement
@@ -798,9 +865,11 @@ workflow:
       Fill `coverage` with ONE LINE PER IN-SCOPE ID, delivered or not — that table is the
       traceability record this gate exists to leave behind, and it is written on a green
       run too. Set gap_count and gap_refs from `gaps`. Set ok=true ONLY when every
-      in-scope id is delivered as the spec words it. Set bridge_ok=false when any
-      in-scope id has no design mapping it, INDEPENDENTLY of ok — working code with a
-      documentation gap is a true state and must be reportable as one.
+      in-scope FR-/BR-/CN-/DC-/IC-/UX- is delivered as the spec words it and no in-scope
+      SC- is NOT MET — an SC- scored not-assessable leaves ok exactly as it was. Set
+      bridge_ok=false when any in-scope id OTHER THAN AN SC- has no design mapping it,
+      INDEPENDENTLY of ok — working code with a documentation gap is a true state and must
+      be reportable as one.
       {{stale_note}}
     outputs:
       - { name: trace_ok,        from: "$.ok" }
@@ -993,4 +1062,4 @@ outputs:
   okf_orphans: "{{okf_orphans}}"
   stale_ids: "{{stale_csv}}"
   active_change: "{{active_change}}"
-  next: "CHANGE OPEN ({{active_change}}): /appweaver close-delta — the slice delivers the contract, is domain-conformant and broke no referrer, and its delta is already merged into the master docs, so the change may now be archived and the version bumped. NO OPEN CHANGE: /appweaver close-story {{story}} to ratify its ADRs, flip its interface entries live and archive its design passes — then /appweaver run."
+  next: "CHANGE OPEN ({{active_change}}): /appweaver close-delta — the slice delivers the contract, is domain-conformant and broke no referrer, and its delta is already merged into the master docs, so the change may now be archived and the version bumped. NO OPEN CHANGE: /appweaver close-story {{story}} would ratify its ADRs, flip its interface entries live and archive its design passes — but it is ⌛ NOT BUILT YET, so nothing closes a story and this one stays OPEN. Until it lands, do not read a green run here as the story being delivered: its ids stay in flight, a feature-scoped analyze-slice keeps subtracting them, and its ADRs and interface entries stay `proposed`. Then /appweaver run."