@gobing-ai/spur 0.3.85 → 0.3.87

package/config/workflows/idea-pipeline.yaml

@@ -97,7 +97,10 @@ states:
       - kind: shell
         options:
           command: >-
-            test -n "$idea" || printf 'FAIL\n' > ".spur/run/$__runId-idea-precheck-doctor.status"
+            mkdir -p .spur/run &&
+            printf '%s\n' "$idea" > ".spur/run/$__runId-idea-input.md" &&
+            awk 'NF' ".spur/run/$__runId-idea-input.md" | grep -q . ||
+            printf 'FAIL\n' > ".spur/run/$__runId-idea-precheck-doctor.status"
 
   - id: discovery
     description: >
@@ -109,12 +112,14 @@ states:
       brainstorm also emits the idea-evaluation report to .spur/run/${vars.__runId}-idea-eval-report.md
       (template: the `sp:spur-dev` skill's `idea-evaluation` reference — named by skill, not by
       repo path, because `spur init` never scaffolds `plugins/sp/` into a seeded project).
+      The operator's verbatim idea argument is persisted at .spur/run/${vars.__runId}-idea-input.md
+      (written by start; the authoritative ask every model-bearing stage reads).
       expectFile fails a silent no-op discovery (no eval report).
     onEnter:
       - kind: agent.run
         options:
           agent: ${vars.planningAgent}
-          input: "Run sp:brainstorm for the idea: ${vars.idea}. The skill owns the approach-generation, design summary, and `needs_design` signal criteria; emit .spur/run/${vars.__runId}-idea-needs-design.json ({\"needs_design\": true|false}) and the design summary per the skill's `Design Approval Gate` and `The needs_design signal` sections. Also emit the idea-evaluation report to .spur/run/${vars.__runId}-idea-eval-report.md per the `sp:spur-dev` skill's `idea-evaluation` reference (urgency/necessity 0–5, premises, pros/cons, alternatives, enhanced idea, recommendation). At the END of the report, append a provenance footer block of the exact form: `---\\nrun_id: ${vars.__runId}\\ngenerated_at: <RFC3339 timestamp>\\n---` (omit the footer only if run_id is empty)."
+          input: "The operator's ask of record is .spur/run/${vars.__runId}-idea-input.md — idea persisted verbatim at start; authoritative, read it first (${vars.idea} is a convenience echo). Run sp:brainstorm. The skill owns the approach-generation, design summary, and `needs_design` signal criteria; emit .spur/run/${vars.__runId}-idea-needs-design.json ({\"needs_design\": true|false}) plus the design summary per its `Design Approval Gate` / `The needs_design signal` sections. Also emit the idea-evaluation report to .spur/run/${vars.__runId}-idea-eval-report.md per the `sp:spur-dev` skill's `idea-evaluation` reference (urgency/necessity 0–5, premises, pros/cons, alternatives, enhanced idea, recommendation, plus mandatory `## Requirement inventory`: numbered I<n> items quoting/paraphrasing idea-input lines; `[unclear: ...]` marks ambiguity, `[deferred: <reason>]` marks out-of-scope). End with this exact footer: `---\\nrun_id: ${vars.__runId}\\ngenerated_at: <RFC3339>\\n---` (omit if run_id is empty)."
           # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
           role: planner
           expectFile: .spur/run/${vars.__runId}-idea-eval-report.md
@@ -143,12 +148,14 @@ states:
       checklists never enter Goal. Shell actions then persist both sections through
       `spur feature update --section Goal|Scope --from-file ...`; a missing/empty artifact
       stops the state. Prefer the enhanced idea from .spur/run/${vars.__runId}-idea-eval-report.md as
-      context; do not overwrite vars.idea.
+      context; do not overwrite vars.idea. The operator's verbatim ask of record is
+      .spur/run/${vars.__runId}-idea-input.md (persisted at start; authoritative over any
+      paraphrase).
     onEnter:
       - kind: agent.run
         options:
           agent: ${vars.planningAgent}
-          input: 'Create a feature for the idea: ${vars.idea}. Read .spur/run/${vars.__runId}-idea-eval-report.md if present for the enhanced idea and scores. Use ''spur feature create "<name>" --json'' to create it. Write the feature id to .spur/run/${vars.__runId}-idea-feature-id.txt. If an existing feature is appropriate, use its id instead. Also write two body-only intent artifacts: .spur/run/${vars.__runId}-idea-goal.md with concise Goal intent only (a short statement of what the feature achieves; never task breakdowns, checklists, or how-to steps), and .spur/run/${vars.__runId}-idea-scope.md with explicit in-scope and out-of-scope boundary bullets.'
+          input: 'Create a feature for the idea. The operator''s ask of record is .spur/run/${vars.__runId}-idea-input.md — the idea argument persisted verbatim at start; treat it as the authoritative ask. Read .spur/run/${vars.__runId}-idea-eval-report.md if present for the enhanced idea and scores. Use ''spur feature create "<name>" --json'' to create it; with --json the feature id is returned under the .ref.id envelope (n), not a top-level .id — read it from there. Write the feature id to .spur/run/${vars.__runId}-idea-feature-id.txt. If an existing feature is appropriate, use its id instead. Also write two body-only intent artifacts: .spur/run/${vars.__runId}-idea-goal.md with concise Goal intent only (a short statement of what the feature achieves; never task breakdowns, checklists, or how-to steps), and .spur/run/${vars.__runId}-idea-scope.md with explicit in-scope and out-of-scope boundary bullets.'
           # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
           role: planner
           expectFile: .spur/run/${vars.__runId}-idea-feature-id.txt
@@ -182,6 +189,9 @@ states:
       check records FAIL and routes through the capped retry loop via guards that consume the
       recorded result — it never fails the run (the engine's default onError policy is `fail`,
       so an in-action check failure would kill the run before the retry edges are evaluated).
+      Requirement coverage is MEASURED alongside it by the soft idea-coverage-check shell
+      (0887 R4): the recorded coverage status conjuncts into the profile=auto ac-generate
+      guards below so uncovered inventory items route through the same capped retry loop.
     onEnter:
       - kind: shell
         options:
@@ -189,7 +199,7 @@ states:
       - kind: agent.run
         options:
           agent: ${vars.planningAgent}
-          input: "Generate acceptance criteria for feature ${vars.featureId}. Read the feature file and author R-numbered BDD Gherkin scenarios per ac-style-guide.md. Output only the complete Acceptance Criteria section body, including the gherkin code fence, with no surrounding commentary and no section heading."
+          input: "Generate acceptance criteria for feature ${vars.featureId}. The operator's ask of record is .spur/run/${vars.__runId}-idea-input.md — idea persisted verbatim at start; authoritative. Read the feature file and author R-numbered BDD Gherkin scenarios per ac-style-guide.md. Tie every scenario to the `## Requirement inventory` of .spur/run/${vars.__runId}-idea-eval-report.md: under each `Scenario:` heading add a comment `# covers: I1, I3` listing covered ids — every non-`[deferred: ...]` item needs at least one covering scenario. Two `spur task check` rules bind AC text: (1) AC bullets copy scenario titles verbatim — the title is the byte-identical identity key of its bullet; (2) gate-language words (HITL, approval/approved, merged/merge event, content-gate, GATED, capstone standalone) are forbidden in titles, bodies, and enum values (L4.gate-language) — rephrase around them. Output only the Acceptance Criteria section body (gherkin fence included), no commentary, no heading."
           # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
           role: planner
           answerFile: .spur/run/${vars.__runId}-idea-ac-content.md
@@ -221,6 +231,24 @@ states:
           resultFile: .spur/run/${vars.__runId}-idea-ac-check.status
           softFail: true
           timeoutMs: 120000
+      # 0887 R4: requirement-inventory ↔ AC coverage, measured once at the same author/revise
+      # boundary. Soft shell (exit 0 always): the checker writes the PASS/FAIL status itself and
+      # the guards below consume the recorded result — never re-run the checker (0769 pattern).
+      # Repo-checkout path first, then the superskill-staged twin (handoff-finalize resolution
+      # shape); neither present fails closed to FAIL so readiness degrades visibly instead of
+      # silently skipping coverage.
+      - kind: shell
+        options:
+          command: >-
+            mkdir -p .spur/run &&
+            S=plugins/sp/scripts/idea-coverage-check.ts &&
+            if [ ! -f "$S" ]; then S="$(superskill script path sp idea-coverage-check.ts 2>/dev/null)"; fi &&
+            if [ -n "$S" ] && [ -f "$S" ]; then
+              bun "$S" --run-id "$__runId" --report ".spur/run/$__runId-idea-eval-report.md" --ac ".spur/run/$__runId-idea-ac-content.md" || printf 'FAIL run=%s checker exited nonzero (bun missing or checker crash)\n' "$__runId" > ".spur/run/$__runId-idea-coverage.reason";
+            else
+              printf 'FAIL run=%s checker not found — run superskill install sp\n' "$__runId" | tee ".spur/run/$__runId-idea-coverage.reason" >&2;
+              printf 'FAIL\n' > ".spur/run/$__runId-idea-coverage.status";
+            fi
 
   - id: feature-check
     description: >
@@ -235,11 +263,14 @@ states:
       the transition guards route directly from ac-generate to the appropriate next
       state, so this state is only entered in interactive mode. On failure, the retry
       cap routes back to ac-generate (≤3 retries) or escalates to failed.
+      Requirement coverage (.spur/run/${vars.__runId}-idea-coverage.status, 0887 R4) is part of
+      the recorded results this gate surfaces: a FAIL there means some inventory items have no
+      covering scenario — answer no to route back to ac-generate for revision if needed.
     pause: true
     onEnter:
       - kind: hitl.confirm
         options:
-          prompt: "Feature check for ${vars.featureId}. Review the AC and confirm to proceed? (Failures route back to ac-generate for revision, capped at 3 retries.)"
+          prompt: "Feature check for ${vars.featureId}. Review the AC and confirm to proceed? Requirement coverage status: $(cat .spur/run/${vars.__runId}-idea-coverage.status 2>/dev/null || echo unknown) — reason: $(cat .spur/run/${vars.__runId}-idea-coverage.reason 2>/dev/null || echo n/a) (.spur/run/${vars.__runId}-idea-coverage.status[.reason]). (Failures route back to ac-generate for revision, capped at 3 retries.)"
 
   - id: system-design
     description: >
@@ -264,7 +295,7 @@ states:
       - kind: agent.run
         options:
           agent: ${vars.planningAgent}
-          input: 'Run sp:sys-architecture for feature ${vars.featureId}. Read the brainstorm artifact, feature AC, and .spur/run/${vars.__runId}-idea-design-review.md. Produce ADR entries, architecture updates, and design satellites (docs/design/<slug>.md) following the constitution edit rules. Do not write task or feature corpus files directly. Design-review contract (.spur/run/${vars.__runId}-idea-design-review.md, fixed headings `## Proposed design`, `## Operator feedback`, `## Reconciliation`): on the first pass write the proposed design summary under `## Proposed design` and leave `## Operator feedback` empty; on retry with operator feedback present, revise the design/ADR artifacts, document the changes under `## Reconciliation`, and when the feedback invalidates an Acceptance Criteria scenario write the revised AC section body to a file and persist it via `$spurBin feature update "$featureId" --section "Acceptance Criteria" --from-file <file>` — never edit feature corpus files directly.'
+          input: 'The operator''s ask of record is .spur/run/${vars.__runId}-idea-input.md (idea persisted verbatim at start; authoritative). Run sp:sys-architecture for feature ${vars.featureId}. Read the brainstorm artifact, feature AC, and .spur/run/${vars.__runId}-idea-design-review.md. Produce ADR entries, architecture updates, and design satellites (docs/design/<slug>.md) per the constitution edit rules; never write task or feature corpus files directly. Design-review contract (fixed headings `## Proposed design`, `## Operator feedback`, `## Reconciliation`): first pass — write the proposed summary under `## Proposed design`, leave `## Operator feedback` empty; retry after operator feedback — revise the design/ADR artifacts, document changes under `## Reconciliation`, and when feedback invalidates an Acceptance Criteria scenario write the revised AC section body to a file, persist via `$spurBin feature update "$featureId" --section "Acceptance Criteria" --from-file <file>`.'
           # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
           role: planner
           expectFile: .spur/run/${vars.__runId}-idea-design-review.md
@@ -331,7 +362,7 @@ states:
       - kind: agent.run
         options:
           agent: ${vars.planningAgent}
-          input: "Run sp:spec-decomposition for feature ${vars.featureId} per skill references/decomposition.md § Idea-pipeline emission: sizing first, then the batch JSON at .spur/run/${vars.__runId}-idea-task-batch.json and the private task-order sidecar at .spur/run/${vars.__runId}-idea-task-order.json."
+          input: "The operator's ask of record is .spur/run/${vars.__runId}-idea-input.md (the idea argument persisted verbatim at start; authoritative). Run sp:spec-decomposition for feature ${vars.featureId} per skill references/decomposition.md § Idea-pipeline emission: sizing first, then the batch JSON at .spur/run/${vars.__runId}-idea-task-batch.json and the private task-order sidecar at .spur/run/${vars.__runId}-idea-task-order.json."
           # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
           role: planner
           expectFile: .spur/run/${vars.__runId}-idea-task-batch.json
@@ -422,7 +453,9 @@ states:
           # project's own computePlanningDigest), so the bounded prompt pins the skill
           # reference instead of a command; artifacts are gated by answerFile/expectFile.
           input: >-
-            Run the ready-prepare stage for feature ${vars.featureId} per sp:spur-dev
+            The operator's ask of record is .spur/run/${vars.__runId}-idea-input.md (the idea
+            argument persisted verbatim at start; authoritative). Run the ready-prepare stage
+            for feature ${vars.featureId} per sp:spur-dev
             references/planning-workflow.md § Step 5.6 (Ready preparation): read
             .spur/run/${vars.__runId}-idea-batch-create-result.json and write
             .spur/run/${vars.__runId}-idea-ready.json.
@@ -559,51 +592,60 @@ transitions:
 
   # ── ac-generate: auto-skip (profile=auto) OR enter feature-check HITL gate (interactive) ──
   # Declaration order: auto-skip guards tried FIRST (same pattern as task-pipeline review→verify
-  # and design-gen→handoff). Under profile=auto, the recorded `idea-ac-check` result routes
-  # directly to the appropriate next state — guards never re-run the CLI (task 0769). Under
-  # interactive, the always fallback enters the feature-check state whose onEnter hitl.confirm
-  # pauses for operator confirmation.
+  # and design-gen→handoff). Under profile=auto, the recorded `idea-ac-check` result and the
+  # recorded requirement-coverage status (0887 R4) route directly to the appropriate next
+  # state — guards never re-run the CLI or the checker (task 0769). Under interactive, the
+  # always fallback enters the feature-check state whose onEnter hitl.confirm pauses for
+  # operator confirmation (coverage is surfaced in that prompt; the operator's answer governs).
   #
-  # Auto-skip 1: pass + design route → system-design (design=auto + needs_design != false)
+  # Auto-skip 1: pass + coverage + design route → system-design (design=auto + needs_design != false)
   - from: ac-generate
     to: system-design
-    description: "profile=auto, check passed, design route — run system design."
-    # (warn) 4 test segments: profile gate + captured status + route signal jointly own the
-    # route; guards never re-run the CLI (0769), so there is nothing smaller to extract.
+    description: "profile=auto, check passed, requirements covered, design route — run system design."
+    # (warn) 4 commands: one persistent multi-assignment line captures both statuses; `test -a` folds the
+    # profile/ac and design/needs pairs (same operand semantics); guards never re-run the CLI (0769).
     guard:
       kind: shell
       options:
-        command: 'test "$profile" = auto && test "$(cat .spur/run/$__runId-idea-ac-check.status 2>/dev/null)" = PASS && test "$design" = auto && test "$(jq -r .needs_design .spur/run/$__runId-idea-needs-design.json 2>/dev/null)" != false'
-  # Auto-skip 2: pass + skip-design route → decompose
+        command: >-
+          ac_status="$(cat .spur/run/$__runId-idea-ac-check.status 2>/dev/null)" cov_status="$(cat .spur/run/$__runId-idea-coverage.status 2>/dev/null)";
+          test "$profile" = auto -a "$ac_status" = PASS && test "$cov_status" = PASS && test "$design" = auto -a "$(jq -r .needs_design .spur/run/$__runId-idea-needs-design.json 2>/dev/null)" != false
+  # Auto-skip 2: pass + coverage + skip-design route → decompose
   - from: ac-generate
     to: decompose
-    description: "profile=auto, check passed, skip-design route — go directly to decompose."
-    # (warn) 5 test segments: same as auto-skip 1 plus the OR'd design=auto/needs_design=false
-    # pair that keeps one captured signal file authoritative for both routes (0769).
+    description: "profile=auto, check passed, requirements covered, skip-design route — go directly to decompose."
+    # (warn) 4 test segments: profile + inlined ac/coverage reads + the OR'd design=skip/(design=auto AND
+    # needs_design=false) pair folded into one `test` (`-a` binds tighter than `-o`), keeping one captured
+    # signal file authoritative for both routes (0769).
     guard:
       kind: shell
       options:
-        command: 'test "$profile" = auto && test "$(cat .spur/run/$__runId-idea-ac-check.status 2>/dev/null)" = PASS && (test "$design" = skip || (test "$design" = auto && test "$(jq -r .needs_design .spur/run/$__runId-idea-needs-design.json 2>/dev/null)" = false))'
-  # Auto-skip 3: check failed, retry < 3 → loop back to ac-generate (self-loop)
+        command: 'test "$profile" = auto && test "$(cat .spur/run/$__runId-idea-ac-check.status 2>/dev/null)" = PASS && test "$(cat .spur/run/$__runId-idea-coverage.status 2>/dev/null)" = PASS && test "$design" = skip -o "$design" = auto -a "$(jq -r .needs_design .spur/run/$__runId-idea-needs-design.json 2>/dev/null)" = false'
+  # Auto-skip 3: check or coverage failed, retry < 3 → loop back to ac-generate (self-loop)
   - from: ac-generate
     to: ac-generate
-    description: "profile=auto, check failed, retry cap not reached — re-run ac-generate."
-    # (warn) 4 test segments: profile gate + captured status + captured retry count; the
-    # retry loop is the smallest honest formulation of cap<3 routing (0769).
+    description: "profile=auto, check or coverage failed, retry cap not reached — re-run ac-generate."
+    # (warn) 5 commands: one persistent multi-assignment line captures both statuses and the retry count
+    # (with its 0 fallback); the failed-check pair stays verbatim and the profile gate folds into the retry
+    # test via `test -a`; the retry loop is the smallest honest formulation of cap<3 routing (0769).
     guard:
       kind: shell
       options:
-        command: 'test "$profile" = auto && test "$(cat .spur/run/$__runId-idea-ac-check.status 2>/dev/null)" != PASS && test "$(cat .spur/run/$__runId-idea-ac-retry-count 2>/dev/null || echo 0)" -lt 3'
-  # Auto-skip 4: check failed, retry cap reached → escalate to failed
+        command: >-
+          ac_status="$(cat .spur/run/$__runId-idea-ac-check.status 2>/dev/null)" cov_status="$(cat .spur/run/$__runId-idea-coverage.status 2>/dev/null)" retry="$(cat .spur/run/$__runId-idea-ac-retry-count 2>/dev/null || echo 0)";
+          { test "$ac_status" != PASS || test "$cov_status" != PASS; } && test "$profile" = auto -a "$retry" -lt 3
+  # Auto-skip 4: check or coverage failed, retry cap reached → escalate to failed
   - from: ac-generate
     to: failed
-    description: "profile=auto, check failed after 3 retries — escalate to failed."
-    # (warn) 4 test segments: mirror of the retry guard with cap>=3; keeping escalation and
-    # retry as one test-chain pair makes the cap boundary auditable in the diff (0769).
+    description: "profile=auto, check or coverage failed after 3 retries — escalate to failed."
+    # (warn) 5 commands: mirror of the retry guard with cap>=3; keeping escalation and retry as one
+    # test-chain pair makes the cap boundary auditable in the diff (0769).
     guard:
       kind: shell
       options:
-        command: 'test "$profile" = auto && test "$(cat .spur/run/$__runId-idea-ac-check.status 2>/dev/null)" != PASS && test "$(cat .spur/run/$__runId-idea-ac-retry-count 2>/dev/null || echo 0)" -ge 3'
+        command: >-
+          ac_status="$(cat .spur/run/$__runId-idea-ac-check.status 2>/dev/null)" cov_status="$(cat .spur/run/$__runId-idea-coverage.status 2>/dev/null)" retry="$(cat .spur/run/$__runId-idea-ac-retry-count 2>/dev/null || echo 0)";
+          { test "$ac_status" != PASS || test "$cov_status" != PASS; } && test "$profile" = auto -a "$retry" -ge 3
   # Interactive fallback: enter feature-check HITL gate
   - from: ac-generate
     to: feature-check
@@ -616,12 +658,14 @@ transitions:
   - from: feature-check
     to: system-design
     description: Feature check passed, design route — run system design.
-    # (warn) 4 test segments: HITL answer + captured status + design route; same shape as the
+    # (warn) 5 commands (named status capture + 4 conditions): HITL answer + captured status + design route; same shape as the
     # ac-generate auto-skips, reading the same captured signal files (0769).
     guard:
       kind: shell
       options:
-        command: 'test "$__hitlAnswer" = yes && test "$(cat .spur/run/$__runId-idea-ac-check.status 2>/dev/null)" = PASS && test "$design" = auto && test "$(jq -r .needs_design .spur/run/$__runId-idea-needs-design.json 2>/dev/null)" != false'
+        command: >-
+          ac_status="$(cat .spur/run/$__runId-idea-ac-check.status 2>/dev/null)";
+          test "$__hitlAnswer" = yes && test "$ac_status" = PASS && test "$design" = auto && test "$(jq -r .needs_design .spur/run/$__runId-idea-needs-design.json 2>/dev/null)" != false
   - from: feature-check
     to: decompose
     description: Feature check passed, skip-design route — go directly to decompose.
@@ -634,20 +678,24 @@ transitions:
   - from: feature-check
     to: ac-generate
     description: "Feature check failed — revise AC (retry cap: 3)."
-    # (warn) 4 test segments: HITL reject/failed-status OR-pair + captured retry count; the
+    # (warn) 5 commands (named status capture + 4 conditions): HITL reject/failed-status OR-pair + captured retry count; the
     # interactive retry mirror of the ac-generate cap<3 guard (0769).
     guard:
       kind: shell
       options:
-        command: '(test "$__hitlAnswer" = no || test "$(cat .spur/run/$__runId-idea-ac-check.status 2>/dev/null)" != PASS) && test "$(cat .spur/run/$__runId-idea-ac-retry-count 2>/dev/null || echo 0)" -lt 3'
+        command: >-
+          ac_status="$(cat .spur/run/$__runId-idea-ac-check.status 2>/dev/null)";
+          (test "$__hitlAnswer" = no || test "$ac_status" != PASS) && test "$(cat .spur/run/$__runId-idea-ac-retry-count 2>/dev/null || echo 0)" -lt 3
   - from: feature-check
     to: failed
     description: Feature check failed after 3 retries — escalate to failed.
-    # (warn) 4 test segments: mirror of the revise guard with cap>=3 (0769).
+    # (warn) 5 commands (named status capture + 4 conditions): mirror of the revise guard with cap>=3 (0769).
     guard:
       kind: shell
       options:
-        command: '(test "$__hitlAnswer" = no || test "$(cat .spur/run/$__runId-idea-ac-check.status 2>/dev/null)" != PASS) && test "$(cat .spur/run/$__runId-idea-ac-retry-count 2>/dev/null || echo 0)" -ge 3'
+        command: >-
+          ac_status="$(cat .spur/run/$__runId-idea-ac-check.status 2>/dev/null)";
+          (test "$__hitlAnswer" = no || test "$ac_status" != PASS) && test "$(cat .spur/run/$__runId-idea-ac-retry-count 2>/dev/null || echo 0)" -ge 3
   - from: feature-check
     to: cancelled
     description: Operator cancelled the feature-check gate.

package/config/workflows/task-pipeline.yaml

@@ -603,10 +603,14 @@ transitions:
     - from: precheck
       to: implement
       description: Deterministic size, evidence, and task checks are green — begin implementation.
+      # (warn) 5 commands: named size/evidence status reads + task check (legibility, 0874).
       guard:
           kind: shell
           options:
-              command: 'test "$(cat .spur/run/$wbs-precheck-size.status 2>/dev/null)" = PASS && test "$(cat .spur/run/$wbs-precheck-evidence.status 2>/dev/null)" = PASS && $spurBin task check $wbs'
+              command: >-
+                  size_status="$(cat .spur/run/$wbs-precheck-size.status 2>/dev/null)";
+                  evidence_status="$(cat .spur/run/$wbs-precheck-evidence.status 2>/dev/null)";
+                  test "$size_status" = PASS && test "$evidence_status" = PASS && $spurBin task check $wbs
     - from: precheck
       to: failed
       description: Size and/or task check failed — stop before implement.
@@ -626,14 +630,18 @@ transitions:
       guard:
           kind: shell
           options:
-              command: 'test "$(cat .spur/run/$wbs-test-gate.status 2>/dev/null)" = PASS && test "$mode" = fast'
+              command: >-
+                  gate_status="$(cat .spur/run/$wbs-test-gate.status 2>/dev/null)";
+                  test "$gate_status" = PASS && test "$mode" = fast
     - from: test
       to: review
       description: Quality gate already green and safety mode — proceed to review.
       guard:
           kind: shell
           options:
-              command: 'test "$(cat .spur/run/$wbs-test-gate.status 2>/dev/null)" = PASS && test "$mode" != fast'
+              command: >-
+                  gate_status="$(cat .spur/run/$wbs-test-gate.status 2>/dev/null)";
+                  test "$gate_status" = PASS && test "$mode" != fast
     - from: test
       to: test-fix
       description: Quality gate red — start bounded fixall loop.
@@ -659,28 +667,40 @@ transitions:
       guard:
           kind: shell
           options:
-              command: 'test "$(cat .spur/run/$wbs-test-gate.status 2>/dev/null)" = PASS && test "$mode" = fast'
+              command: >-
+                  gate_status="$(cat .spur/run/$wbs-test-gate.status 2>/dev/null)";
+                  test "$gate_status" = PASS && test "$mode" = fast
     - from: test-recheck
       to: review
       description: Quality gate green after fixall and safety mode — proceed to review.
       guard:
           kind: shell
           options:
-              command: 'test "$(cat .spur/run/$wbs-test-gate.status 2>/dev/null)" = PASS && test "$mode" != fast'
+              command: >-
+                  gate_status="$(cat .spur/run/$wbs-test-gate.status 2>/dev/null)";
+                  test "$gate_status" = PASS && test "$mode" != fast
     - from: test-recheck
       to: test-fix
       description: Still red and under qualityGateMaxFixAttempts — another fixall hop.
+      # (warn) 5 commands: named gate status + fix attempts (legibility, 0874).
       guard:
           kind: shell
           options:
-              command: 'test "$(cat .spur/run/$wbs-test-gate.status 2>/dev/null)" = FAIL && test "$(cat .spur/run/$wbs-test-fix-attempt 2>/dev/null || echo 0)" -lt "$qualityGateMaxFixAttempts"'
+              command: >-
+                  gate_status="$(cat .spur/run/$wbs-test-gate.status 2>/dev/null)";
+                  fix_attempts="$(cat .spur/run/$wbs-test-fix-attempt 2>/dev/null || echo 0)";
+                  test "$gate_status" = FAIL && test "$fix_attempts" -lt "$qualityGateMaxFixAttempts"
     - from: test-recheck
       to: failed
       description: Still red after max fixall attempts — stop at failed (not silent abort).
+      # (warn) 5 commands: named gate status + fix attempts (legibility, 0874).
       guard:
           kind: shell
           options:
-              command: 'test "$(cat .spur/run/$wbs-test-gate.status 2>/dev/null)" = FAIL && test "$(cat .spur/run/$wbs-test-fix-attempt 2>/dev/null || echo 0)" -ge "$qualityGateMaxFixAttempts"'
+              command: >-
+                  gate_status="$(cat .spur/run/$wbs-test-gate.status 2>/dev/null)";
+                  fix_attempts="$(cat .spur/run/$wbs-test-fix-attempt 2>/dev/null || echo 0)";
+                  test "$gate_status" = FAIL && test "$fix_attempts" -ge "$qualityGateMaxFixAttempts"
     # Defense: corrupt recheck status — failed, not review.
     - from: test-recheck
       to: failed
@@ -748,7 +768,16 @@ transitions:
           kind: shell
           options:
               command: >-
-                  jq -e --arg d "$proofDigest" --arg r "$__runId" --arg dd "$__definitionDigest" '.verdict == "PASS" and (.proof.digest // "") == $d and (.proof.stages.qualityGate.digest // "") == $d and (.proof.stages.review.digest // "") == $d and (.proof.stages.review.status // "") == "completed" and (.proof.stages.verification.digest // "") == $d and (.proof.runId // "") == $r and (.proof.definitionDigest // "") == $dd' ".spur/run/$wbs-verdict.json" >/dev/null 2>&1
+                  jq -e --arg d "$proofDigest" --arg r "$__runId" --arg dd "$__definitionDigest" '
+                  .verdict == "PASS"
+                  and (.proof.digest // "") == $d
+                  and (.proof.stages.qualityGate.digest // "") == $d
+                  and (.proof.stages.review.digest // "") == $d
+                  and (.proof.stages.review.status // "") == "completed"
+                  and (.proof.stages.verification.digest // "") == $d
+                  and (.proof.runId // "") == $r
+                  and (.proof.definitionDigest // "") == $dd
+                  ' ".spur/run/$wbs-verdict.json" >/dev/null 2>&1
     - from: verify
       to: test-fix
       description: >-
@@ -760,8 +789,8 @@ transitions:
           kind: shell
           options:
               command: >-
-                  V="$(jq -r .verdict .spur/run/$wbs-verdict.json 2>/dev/null)";
-                  test -n "$V" && test "$V" != PASS &&
+                  verdict="$(jq -r .verdict .spur/run/$wbs-verdict.json 2>/dev/null)";
+                  test -n "$verdict" && test "$verdict" != PASS &&
                   test "$(cat .spur/run/$wbs-test-fix-attempt 2>/dev/null || echo 0)" -lt "$qualityGateMaxFixAttempts"
     - from: verify
       to: failed
@@ -778,6 +807,7 @@ transitions:
     - from: record
       to: done
       description: Task check passed and the verdict proof block still names the captured digest — certify done.
+      # (warn) 5 commands: named verdict + proof digest reads after the task check (legibility, 0874).
       guard:
           kind: shell
           options:
@@ -788,8 +818,9 @@ transitions:
               # one shell line.
               command: >-
                   $spurBin task check $wbs --as done &&
-                  test "$(jq -r .verdict .spur/run/$wbs-verdict.json 2>/dev/null)" = PASS &&
-                  test "$(jq -r '.proof.digest // ""' .spur/run/$wbs-verdict.json 2>/dev/null)" = "$proofDigest"
+                  verdict="$(jq -r .verdict .spur/run/$wbs-verdict.json 2>/dev/null)" &&
+                  proof_digest="$(jq -r '.proof.digest // ""' .spur/run/$wbs-verdict.json 2>/dev/null)" &&
+                  test "$verdict" = PASS && test "$proof_digest" = "$proofDigest"
     - from: record
       to: failed
       description: Task check failed or proof evidence missing/malformed/mismatched — block before done.

package/config/workflows/wrapup-pipeline.yaml

@@ -13,10 +13,12 @@
 # pauses,
 # even under --auto (Iron Law #6: irreversible action -> surface to human).
 #
-# Shape: start -> task-resolve -> doc-sync -> metrics-record
+# Shape: start -> task-resolve -> doc-sync -> learnings-append -> metrics-record
 #          -> feature-transition (conditional: if vars.feature set)
 #          -> branch-cleanup (conditional: if vars.merge=true)
 #          -> done
+#        doc-sync routes a contract violation to `repair` (cheap, no
+#        re-dispatch — ADR-118 pilot) and an executor failure to `failed`;
 #        task-resolve with a VALIDATED empty list short-circuits to `skipped`;
 #        invalid wrap input, an unresolved/non-completed task, a failed metrics
 #        capture, a failed required sync, or a failed feature gate routes to
@@ -72,7 +74,7 @@
 "$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
 kind: state-machine
 name: wrapup-pipeline
-version: "3"
+version: "4"
 description: "Post-execution wrap-up: doc-sync (doc drift + learning capture), metrics, feature-transition, branch-cleanup"
 iterationBound: 10
 initialState: start
@@ -168,13 +170,16 @@ states:
       learnings (task 0607 R2: two adjacent agent.run hops merged, count 2 -> 1;
       no operator-decision pause or verdict boundary sits between them). No dedicated
       slash command yet — free-form skill pointer until a /sp:doc-evolve command
-      exists (ADR-043 residual). Capture+shell decoupling preserved: expectFile gates
-      a non-empty capture before the append; append is best-effort soft (empty capture
-      skips without aborting wrap-up).
+      exists (ADR-043 residual). This is the expensive stage; a contract violation
+      (a clean exit that missed its declared answerFile/expectFile post-condition)
+      routes to the cheap `repair` edge instead of a full re-dispatch (ADR-118
+      pilot, 0871) — `onError: continue` lets the transition guards read the
+      agent's result instead of halting the run.
     onEnter:
       # (warn) free-form prompt: no /sp:doc-evolve command surface yet (ADR-043
       # residual, 0607 R2 one-query merge); capture is bounded by expectFile.
       - kind: agent.run
+        onError: continue
         options:
           agent: ${vars.agent}
           input: >-
@@ -192,6 +197,13 @@ states:
           answerFile: .spur/run/${vars.__runId}-wrapup-learnings.md
           expectFile: .spur/run/${vars.__runId}-wrapup-learnings.md
           timeoutMs: ${vars.stepTimeoutMs}
+
+  - id: learnings-append
+    description: >
+      Best-effort soft append of the captured learnings to .spur/memory/learnings.md
+      (0607 R2): an empty capture skips without aborting wrap-up. Runs only after
+      doc-sync's contract held; a contract violation never reaches this state.
+    onEnter:
       # (warn) learnings append is intentionally soft (empty capture skips
       # without aborting wrap-up, 0607 R2).
       - kind: shell
@@ -207,6 +219,21 @@ states:
             fi &&
             exit 0
 
+  - id: repair
+    description: >
+      Contract-violation repair (ADR-118 pilot, 0871): doc-sync's agent.run missed
+      its declared post-condition after a clean exit, so wrap-up does NOT re-dispatch
+      the expensive agent on this attempt. The miss is recorded to a run-scoped
+      repair status and wrap-up proceeds to metrics-record — the run log and action
+      trace already name the violated contract and the observed value.
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            mkdir -p .spur/run &&
+            printf 'contract-violation: doc-sync learnings capture missed its declared contract — repair skipped re-dispatch (ADR-118 pilot)\n' > ".spur/run/$__runId-wrapup-repair.status" &&
+            exit 0
+
   - id: metrics-record
     description: >
       Append one JSONL row per task to .spur/memory/wrapup-metrics.jsonl deterministically.
@@ -354,10 +381,46 @@ transitions:
     guard:
       kind: always
 
-  # ── linear body: doc-sync -> metrics-record ──
+  # ── doc-sync: contract-first routing (ADR-118 pilot, 0871) ──
+  # Declaration order matters: the contract-violation edge is tried first, then
+  # success (action-ok), then the executor-failure defense (always) — a failed
+  # agent.run reaches these guards because doc-sync's agent.run declares
+  # onError: continue.
   - from: doc-sync
+    to: repair
+    description: >
+      Contract violation (ADR-118): the agent exited 0 but missed its declared
+      post-condition. Route to the cheap repair edge — never re-dispatch the
+      full agent.run on this attempt.
+    trigger: contract-violation
+    guard:
+      kind: contract-violation
+  - from: doc-sync
+    to: learnings-append
+    description: Doc drift repair + learning capture succeeded — append learnings.
+    guard:
+      kind: action-ok
+  - from: doc-sync
+    to: failed
+    description: >
+      Executor failure (non-zero exit, signal, or dispatch error) — keep the
+      existing fail semantics; a contract violation never falls through here
+      because the contract-violation edge is declared first.
+    trigger: executor-failure
+    guard:
+      kind: always
+
+  # ── linear body: learnings-append -> metrics-record ──
+  - from: learnings-append
+    to: metrics-record
+    description: Learning capture appended (or soft-skipped) — record metrics.
+    guard:
+      kind: always
+
+  # ── repair: cheap path, no re-dispatch -> metrics-record ──
+  - from: repair
     to: metrics-record
-    description: Doc drift repair + learning capture complete — record metrics.
+    description: Contract-violation repair recorded — proceed to metrics without re-dispatch.
     guard:
       kind: always
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.3.85",
+    "version": "0.3.87",
     "description": "Spur CLI — local-first harness for mainstream coding agents: constraint checking, workflow orchestration, agent health, and history analytics. Bun-native; exposes the `spur` command.",
     "keywords": [
         "spur",
@@ -53,14 +53,14 @@
     },
     "devDependencies": {
         "@commander-js/extra-typings": "^14.0.0",
-        "@gobing-ai/ts-db": "^0.4.66",
-        "@gobing-ai/ts-ai-runner": "^0.4.66",
-        "@gobing-ai/ts-dual-workflow-engine": "^0.4.66",
-        "@gobing-ai/ts-infra": "^0.4.66",
-        "@gobing-ai/ts-llm-jsonl-importer": "^0.4.66",
-        "@gobing-ai/ts-rule-engine": "^0.4.66",
-        "@gobing-ai/ts-runtime": "^0.4.66",
-        "@gobing-ai/ts-utils": "^0.4.66",
+        "@gobing-ai/ts-db": "^0.4.67",
+        "@gobing-ai/ts-ai-runner": "^0.4.67",
+        "@gobing-ai/ts-dual-workflow-engine": "^0.4.67",
+        "@gobing-ai/ts-infra": "^0.4.67",
+        "@gobing-ai/ts-llm-jsonl-importer": "^0.4.67",
+        "@gobing-ai/ts-rule-engine": "^0.4.67",
+        "@gobing-ai/ts-runtime": "^0.4.67",
+        "@gobing-ai/ts-utils": "^0.4.67",
         "@types/bun": "1.3.14",
         "@types/figlet": "^1.7.0",
         "@types/node-notifier": "8.0.5",