@gobing-ai/spur 0.3.85 → 0.3.86

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
     "plugins": [
         {
             "name": "sp",
-            "version": "0.3.85",
+            "version": "0.3.86",
             "source": "./plugins/sp"
         }
     ]

package/config/pipeline-budgets.json

@@ -28,17 +28,6 @@
             "source": "Post-merge count (0607 R2: doc-sync + learning-capture consolidated, 2 -> 1). Real-run reading (R5): median 253s, max-sane 2319s (n=44). Budget = 60 min ceiling.",
             "decision": null
         },
-        "docs-pipeline": {
-            "modelQueries": 2,
-            "wallClockMs": null,
-            "tokenCostUsd": null,
-            "source": "No fixture (0607 option a) and only dry/short runs recorded in history (max 1s, n=4) — wall-clock budget unenforced until a real docs-pipeline run exists. Query budget 2 matches the live workflow definition's query list ['draft','verify'] (added by task 0704; 0607 R3 recorded 1, which is stale against the definition). 0754 R6: FIX, not raise — the value was wrong against the definition, the workflow's declared query count did not change.",
-            "decision": {
-                "date": "2026-09-03",
-                "wbs": "0754",
-                "note": "align docs-pipeline.modelQueries to the live workflow definition's query list ['draft','verify']; not a measured-cost raise — the workflow's declared query count was already 2 (added by 0704); the budget was the stale side, not the workflow. Per D8 Decision 11."
-            }
-        },
         "pr-review": {
             "modelQueries": 0,
             "wallClockMs": null,
@@ -53,26 +42,12 @@
             "source": "Coverage entry (0826 R2): the live definition's model-query count (extractResolvedWorkflowFacts, 2026-09-11). No real-run measurement yet: wall-clock and cost are unenforced until measured, never 0.",
             "decision": null
         },
-        "feature-dev": {
-            "modelQueries": 2,
-            "wallClockMs": null,
-            "tokenCostUsd": null,
-            "source": "Coverage entry (0826 R2): the live definition's model-query count (extractResolvedWorkflowFacts, 2026-09-11). No real-run measurement yet: wall-clock and cost are unenforced until measured, never 0.",
-            "decision": null
-        },
         "wayfinder-resolution": {
             "modelQueries": 2,
             "wallClockMs": null,
             "tokenCostUsd": null,
             "source": "Coverage entry (0826 R2): the live definition's model-query count (extractResolvedWorkflowFacts, 2026-09-11). No real-run measurement yet: wall-clock and cost are unenforced until measured, never 0.",
             "decision": null
-        },
-        "basic": {
-            "modelQueries": 1,
-            "wallClockMs": null,
-            "tokenCostUsd": null,
-            "source": "Coverage entry (0826 R2): the live definition's model-query count (extractResolvedWorkflowFacts, 2026-09-11). No real-run measurement yet: wall-clock and cost are unenforced until measured, never 0.",
-            "decision": null
         }
     }
 }

package/config/plugin-scripts.json

@@ -26,11 +26,6 @@
             "contract": "standard",
             "twin": "dogfood-testing/validate-report.mjs"
         },
-        {
-            "rel": "feature-dev-precheck.ts",
-            "contract": "standard",
-            "twin": "feature-dev-precheck.mjs"
-        },
         {
             "rel": "feature-sync-bounded.ts",
             "contract": "standard",

package/config/rules/boundary/env-var-hygiene.yaml

@@ -0,0 +1,41 @@
+$schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
+# Environment-variable hygiene — env access funnels through the config gateway (task 0902).
+#
+# Contract:
+# - `@gobing-ai/ts-utils` (`packages/utils/src/env.ts` in ts-libs) is the single
+#   implementation source; `packages/config/src/index.ts` re-exports `getEnvVar` /
+#   `getEnvVars` / `setEnvVar` / `removeEnvVar` / `getAppOptions` as the app-side funnel,
+#   and NO file in this repo touches `process.env` directly — packages/config included.
+#   Env flows into the app as typed config or injected `env` records (ADR-027). Runtime
+#   options belong in `.spur/config.yaml` `bootstrap.options` via `getAppOptions`;
+#   dev-only knobs belong in consts.
+# - Plugin scripts/hooks import the same functions from `@gobing-ai/ts-utils`; the
+#   `superskill script convert` `.mjs` twins bundle them in (self-contained on any
+#   install target).
+# - `apps/web` uses `import.meta.env` (Vite browser plane) — not process env, never matches.
+# - Which variables exist and who consumes them is documented in `.env.example`.
+#   (The former per-var lease table moved there; the rule now enforces the funnel,
+#   not a file-by-var inventory.)
+#
+# Scope: apps/**, packages/**, scripts/**, plugins/sp/** — src AND tests. No exclusions:
+# even the gateway package itself is free of direct access.
+include:
+  - "apps/**/src/**/*.{ts,tsx}"
+  - "apps/**/tests/**/*.{ts,tsx}"
+  - "packages/**/src/**/*.{ts,tsx}"
+  - "packages/**/tests/**/*.{ts,tsx}"
+  - "scripts/**/*.ts"
+  - "plugins/sp/**/*.ts"
+rules:
+  - id: env-var-hygiene
+    description: >
+      No direct `process.env` or `Bun.env` access outside the packages/config gateway.
+      Read via `getEnvVar` (single var, undefined-only fallback), seed/compose via
+      `getEnvVars()` (live record — also the sanctioned form for setting/deleting
+      parent→child contract markers), or take an injected `env` record parameter.
+      Aliasing (`const env = process.env`) is caught too — it must touch `process.env`.
+    severity: error
+    evaluator:
+      type: rg
+      config:
+        pattern: "process\\.env|\\bBun\\.env\\b"

package/config/transition-shims.json

@@ -1,5 +1,5 @@
 {
-    "note": "Transition-shim manifest (task 0541, feature B2). Each entry records one compatibility path marked @transition-shim(<id>) in source. Every field is required. The gate (bun run transition-shim-check, inside `spur-check`) is two-sided: an unregistered marker fails, and a listed entry whose marker is gone fails. Emptying this file is the definition of the transition being complete (docs/04_DESIGN.md §2.5). Removal conditions must be objectively checkable against the repository, not 'when convenient'. Shims are registered by the tasks that create them (0536/0537/0538/0542).",
+    "note": "Transition-shim manifest (task 0541, feature B2). Each entry records one compatibility path marked @transition-shim(<id>) in source. Every field is required. The gate (bun run transition-shim-check, in the feature-scoped `spur-check-feature` pass since task 0872) is two-sided: an unregistered marker fails, and a listed entry whose marker is gone fails. Emptying this file is the definition of the transition being complete (docs/04_DESIGN.md §2.5). Removal conditions must be objectively checkable against the repository, not 'when convenient'. Shims are registered by the tasks that create them (0536/0537/0538/0542).",
     "entries": [
         {
             "id": "agent-bare-binary-name",

package/config/workflow-candidates.json

@@ -0,0 +1,41 @@
+{
+    "schemaVersion": 1,
+    "note": "Workflow graph-change promotion candidates (task 0873, feature D62; ADR-076 amendment). A candidate is shadow-run against recorded real-run inputs and is promoted into the canonical definition or deleted by its named deadline — never left as a standing parallel <name>2.yaml. `verdict` is null while pending and is filled by `bun scripts/spur-dev.ts promotion evaluate <id>`; `promotion check` (spur-check-feature) fails any candidate still present past its deadline and any unreferenced parallel definition in config/workflows/.",
+    "candidates": [
+        {
+            "id": "wrapup-contract-violation-pilot-routing",
+            "canonical": "wrapup-pipeline",
+            "deadline": "2026-10-17",
+            "createdAt": "2026-09-17",
+            "rationale": "ADR-118 pilot graph change shipped by task 0871 (doc-sync contract-violation routing to the shell-only repair state). Registered by task 0876 to take the promotion decision on its first real-run measurement (R4/R5): wrapup-pipeline run fadca099-25a7-4884-a4ae-923cd0239775 (done, state-machine, definition sha256:cad7ad8b..., v4, created 2026-09-17T15:14:46Z, 14h28m after 0871 landed at 00:46:46Z - the only post-landing terminal non-dry wrapup run) routed doc-sync->learnings-append on the default edge: the doc-sync agent.run exited clean (exitCode 0) and produced its declared expectFile capture (.spur/run/fadca099-...-wrapup-learnings.md), so data.outcome was success, ContractViolationGuardRunner passed:false (packages/app/src/workflow/guards/contract-violation.ts:26), zero workflow.agent.contract-violation system_events, zero failed actions (executor-failure path not taken), no repair status file. Measured absence on real traffic - never fabricated. The change projects delta.agentRunCount=1 (unchanged): the repair edge adds no model hop (repair is a shell that records the miss; ADR-118 forbids re-dispatch), so the ADR-076 cost bar cannot reward it; its justification is ADR-118 routing correctness, evidenced here by the measured absence on the first real run. Disposition (resolve delete, or hold as the pattern-spread precedent for 0873's gate) belongs to the D62 owner before the deadline.",
+            "measurement": {
+                "workflow": "wrapup-pipeline",
+                "runIds": ["fadca099-25a7-4884-a4ae-923cd0239775"]
+            },
+            "delta": {
+                "agentRunCount": 1
+            },
+            "verdict": {
+                "decision": "delete",
+                "evaluatedAt": "2026-09-17T15:33:27.274Z",
+                "agentRunCount": {
+                    "runs": 1,
+                    "mean": 1,
+                    "median": 1,
+                    "min": 1,
+                    "max": 1
+                },
+                "agentRunDurationMs": {
+                    "runs": 1,
+                    "mean": 505937,
+                    "median": 505937,
+                    "min": 505937,
+                    "max": 505937
+                },
+                "candidateAgentRunCount": 1,
+                "canonicalAgentRunCount": 1,
+                "reason": "candidate projects 1 agent.run action(s), not fewer than the canonical wrapup-pipeline count of 1 (1 real run(s), median 1 agent.run action(s)/run, median 505937 ms/run) — ADR-076 rejected a graph adding a model hop"
+            }
+        }
+    ]
+}

package/config/workflows/feature-lifecycle.yaml

@@ -62,11 +62,13 @@ transitions:
   - from: verifying
     to: done
     description: >
-      Feature verified — complete. Runs strict check (AC validated, traceability clean).
+      Feature verified — complete. Requires the feature-scoped verification pass
+      (ADR-119) to have recorded PASS, then strict check (AC validated,
+      traceability clean).
     guard:
       kind: shell
       options:
-        command: '$spurBin feature check $featureId --strict --as done'
+        command: 'test "$(cat .spur/run/$featureId-feature-verification.status 2>/dev/null)" = PASS && $spurBin feature check $featureId --strict --as done'
 
   # Rework: verifying → active (mandatory History entry)
   - from: verifying

package/config/workflows/feature-verification.yaml

@@ -0,0 +1,70 @@
+# Feature-scoped verification pass (ADR-119, feature D62, task 0872).
+#
+# Owns a lifecycle boundary no per-task graph owns: the repo-wide checks whose
+# invariant spans the repository rather than a single task's diff — corpus
+# consistency, contract baselines, dependency/schema drift, the frozen History
+# surface, and the repo-wide test set. They run once per feature against a
+# settled tree, deliberately the slow pass, and `feature-lifecycle`'s
+# verifying→done guard refuses to complete the feature until this pass records
+# PASS (ADR-119 consequence: a feature is not done until it passes).
+#
+# Run: spur workflow run feature-verification.yaml --vars '{"featureId":"D62"}'
+#
+# Shape: verify -> done | failed. The shell action writes the verdict to
+# `.spur/run/<featureId>-feature-verification.status` and always exits 0; the
+# transition guard reads the status so a missing, corrupt or FAIL verdict routes
+# to `failed` (fail-closed), never a silent PASS.
+#
+# Reliability (aligned with task-pipeline / ADR-043): no agent.run nodes; the
+# verification command is a trusted config var executed via `sh -c` (same
+# surface as task-pipeline's qualityGateCmd — never interpolate untrusted input).
+"$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
+kind: state-machine
+name: feature-verification
+version: "1"
+description: "Feature-scoped verification pass (ADR-119): runs the repo-wide check set once per feature against a settled tree and records PASS/FAIL."
+iterationBound: 2
+initialState: verify
+terminalStates:
+  - done
+  - failed
+failureStates:
+  - failed
+vars:
+  featureId: "X"
+  spurBin: "spur"
+  verificationCmd: "bun run spur-check-feature"
+
+states:
+  - id: verify
+    description: >
+      Run the repo-wide check set, record the verdict, always exit 0.
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            mkdir -p .spur/run;
+            sh -c "$verificationCmd" > ".spur/run/$featureId-feature-verification.log" 2>&1
+            && printf 'PASS\n' > ".spur/run/$featureId-feature-verification.status"
+            || printf 'FAIL\n' > ".spur/run/$featureId-feature-verification.status";
+            exit 0
+
+  - id: done
+    description: Terminal — repo-wide checks passed.
+
+  - id: failed
+    description: Terminal — repo-wide checks failed or the verdict is missing/corrupt.
+
+transitions:
+  - from: verify
+    to: done
+    description: Repo-wide checks passed — the feature-scoped verification pass records PASS.
+    guard:
+      kind: shell
+      options:
+        command: 'test "$(cat .spur/run/$featureId-feature-verification.status 2>/dev/null)" = PASS'
+  - from: verify
+    to: failed
+    description: Repo-wide checks failed (or the verdict is missing/corrupt) — stop at failed.
+    guard:
+      kind: always

package/config/workflows/idea-pipeline.yaml

@@ -568,12 +568,14 @@ transitions:
   - 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
+    # (warn) 5 commands (named status capture + 4 conditions): profile gate + captured status + route signal jointly own the
     # route; guards never re-run the CLI (0769), so there is nothing smaller to extract.
     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'
+        command: >-
+          ac_status="$(cat .spur/run/$__runId-idea-ac-check.status 2>/dev/null)";
+          test "$profile" = auto && test "$ac_status" = 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
   - from: ac-generate
     to: decompose
@@ -588,22 +590,26 @@ transitions:
   - 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
+    # (warn) 5 commands (named status capture + 4 conditions): profile gate + captured status + captured retry count; 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'
+        command: >-
+          ac_status="$(cat .spur/run/$__runId-idea-ac-check.status 2>/dev/null)";
+          test "$profile" = auto && test "$ac_status" != 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
   - 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
+    # (warn) 5 commands (named status capture + 4 conditions): 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)";
+          test "$profile" = auto && test "$ac_status" != PASS && test "$(cat .spur/run/$__runId-idea-ac-retry-count 2>/dev/null || echo 0)" -ge 3
   # Interactive fallback: enter feature-check HITL gate
   - from: ac-generate
     to: feature-check
@@ -616,12 +622,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 +642,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.86",
     "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",