@gobing-ai/spur 0.3.72 → 0.3.74

package/config/workflows/docs-pipeline.yaml

@@ -11,12 +11,15 @@
 #   - requireDiff fails silent no-op drafts
 #   - HITL answer routing is exhaustive (yes/no/cancel)
 #   - verify measures the deliverable read-only (answer file + `spur task verdict` + proof
-#     digest bracket) — record → done is fail-closed on measured PASS, never on a stub
+#     digest bracket); recording happens only AFTER measured PASS (0769 ordering:
+#     precheck → draft → docs-review → verify → record → done) and `record → done` is
+#     fail-closed on the captured record result + re-asserted verdict — never on a stub
 
 "$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
+version: "1"
 kind: state-machine
 name: docs-pipeline
-description: "Docs-only execution pipeline (precheck -> draft -> docs-review -> record -> verify -> done)"
+description: "Docs-only execution pipeline (precheck -> draft -> docs-review -> verify -> record -> done)"
 iterationBound: 12
 initialState: precheck
 terminalStates:
@@ -34,13 +37,15 @@ vars:
   stepTimeoutMs: "1800000"
   # Proof-state bracket (task 0704, mirroring task-pipeline 0612/0703). `proofDigest` is the
   # canonical capture at verify entry; `proofDigestNow` is the live re-capture compared against
-  # it by the `verify → done` guard so verifier-time mutation fails closed (R4/R5).
+  # it by the `verify → record` guard so verifier-time mutation fails closed (R4/R5).
   proofDigest: ""
   proofDigestNow: ""
   # `taskSpecPath` carries the task file path because `docs/tasks*` is excluded from the digest's
   # git-tree half (task 0704 R4); resolved per-run by the verify state's taskpath shell step.
   taskSpecPath: ""
   __hitlAnswer: ""
+  # R8 (0366): injected by WorkflowAppService.run(); run-scopes every temporary capture.
+  __runId: ""
 
 states:
   - id: precheck
@@ -49,14 +54,16 @@ states:
       (D5-J, ADR-069). Both gates run `softFail: true`, so a red probe records FAIL and lets
       the transitions route to `failed` instead of aborting the run — the shipped action
       schema exposes no `onError`, so soft mode is what preserves that routing.
-      The canonical `.spur/run/$wbs-docs-precheck.status` is the AND of the two gate files.
+      The canonical `.spur/run/$__runId-docs-precheck.status` is the AND of the two gate files.
+      (0769: temporary captures are run-scoped — `.spur/run/<runId>-docs-*` — so concurrent
+      runs on one task never share or clobber a capture.)
     onEnter:
       - kind: command.gate
         options:
           id: docs-precheck-task
           executable: "${vars.spurBin}"
           args: ["task", "check", "${vars.wbs}"]
-          resultFile: .spur/run/${vars.wbs}-docs-precheck-task.status
+          resultFile: .spur/run/${vars.__runId}-docs-precheck-task.status
           softFail: true
           timeoutMs: 120000
       - kind: command.gate
@@ -64,16 +71,16 @@ states:
           id: docs-precheck-agent
           executable: "${vars.spurBin}"
           args: ["agent", "doctor", "${vars.agent}"]
-          resultFile: .spur/run/${vars.wbs}-docs-precheck-agent.status
+          resultFile: .spur/run/${vars.__runId}-docs-precheck-agent.status
           softFail: true
           timeoutMs: 120000
       - kind: shell
         options:
           command: >-
-            if test "$(cat .spur/run/$wbs-docs-precheck-task.status 2>/dev/null)" = PASS &&
-               test "$(cat .spur/run/$wbs-docs-precheck-agent.status 2>/dev/null)" = PASS;
-            then printf 'PASS\n' > ".spur/run/$wbs-docs-precheck.status";
-            else printf 'FAIL\n' > ".spur/run/$wbs-docs-precheck.status"; fi
+            if test "$(cat .spur/run/$__runId-docs-precheck-task.status 2>/dev/null)" = PASS &&
+               test "$(cat .spur/run/$__runId-docs-precheck-agent.status 2>/dev/null)" = PASS;
+            then printf 'PASS\n' > ".spur/run/$__runId-docs-precheck.status";
+            else printf 'FAIL\n' > ".spur/run/$__runId-docs-precheck.status"; fi
       - kind: note
         options:
           message: "Docs pipeline start for task ${vars.wbs}."
@@ -108,44 +115,39 @@ states:
         options:
           prompt: "Approve docs-only deliverable for task ${vars.wbs}?"
 
-  - id: record
-    description: >
-      Record the docs-only outcome into the task file. The task record verb backfills
-      Solution from the diff and moves the task to testing; the done gate still runs
-      the normal task matrix check before completion.
-    onEnter:
-      - kind: shell
-        options:
-          command: "$spurBin task record $wbs --solution-from-diff --transition testing"
-
-  - id: done
-    description: Terminal — docs deliverable measured, reviewed, and recorded.
-    onEnter:
-      # R1 (0704): no synthetic verdict writer. The verdict artifact is produced by measured
-      # verification in `verify` and registered there; done only performs the guarded
-      # transition. Override path remains: --force-done --reason.
-      - kind: shell
-        options:
-          command: "$spurBin task update $wbs done --no-lifecycle"
-      - kind: note
-        options:
-          message: "Docs pipeline complete for task ${vars.wbs}."
   - id: verify
     description: >
       Read-only measured verification (task 0704, R2/R4/R7): dispatch /sp:dev-verify --fix none
       with an answer file, derive the ONE standard verdict via `spur task verdict`, register the
       standard verify-verdict artifact, and bracket the verifier with proof-input digest capture/compare so any
       task-spec or document mutation during certification fails closed (R4). No docs assurance
-      subclass — PASS semantics are identical to task-pipeline (R7).
+      subclass — PASS semantics are identical to task-pipeline (R7). 0769: verification now
+      PRECEDES recording; the `verify → record` guard compares the proof bracket, and the
+      verdict artifact keeps its `.spur/run/<wbs>-verdict.json` compatibility path with
+      runId + definitionDigest stamped through the existing proof/run-artifact contract.
     onEnter:
+      # 0769: clear any stale current-run answer before the fresh-session verifier writes it.
+      - kind: shell
+        options:
+          command: "mkdir -p .spur/run && rm -f .spur/run/$__runId-docs-verify-answer.txt"
       # R4 (0703 R6 precedent): resolve the task-spec path BEFORE capture. `docs/tasks*` is
       # excluded from the digest's git-tree half, so the spec is folded in via `taskFile`.
       - kind: shell
         options:
-          command: '$spurBin task path $wbs --json 2>/dev/null | jq -r ".path // .filePath // empty" > ".spur/run/$wbs-docs-taskpath.txt" || true; exit 0'
+          # 0760 R1 (sibling of 0751 R2): task-path lookup fails closed. Drop
+          # `2>/dev/null`, `|| true`, and the forced `exit 0` so an unresolved
+          # wbs exits non-zero with a named message. The resolved path folds
+          # into the proof digest via `taskFile:` below; a silent miss would
+          # degrade the docs-pipeline proof to tree-only (same hazard 0751 R2
+          # removed from task-pipeline). (0769: run-scoped capture path.)
+          command: >-
+            set -e;
+            task_path="$($spurBin task path $wbs --json | jq -r '.path // .filePath // empty')";
+            if [ -z "$task_path" ]; then echo "docs-pipeline: task path did not resolve for wbs $wbs" >&2; exit 1; fi;
+            printf '%s' "$task_path" > ".spur/run/$__runId-docs-taskpath.txt"
       - kind: file.read.into-var
         options:
-          path: .spur/run/${vars.wbs}-docs-taskpath.txt
+          path: .spur/run/${vars.__runId}-docs-taskpath.txt
           var: taskSpecPath
       # R4: canonical capture BEFORE the verifier runs. Same fingerprint input as the
       # re-capture below so the bracket compares like for like.
@@ -164,19 +166,19 @@ states:
           input: /sp:dev-verify ${vars.wbs} --auto --fix none --focus all
           role: reviewer
           timeoutMs: ${vars.stepTimeoutMs}
-          answerFile: .spur/run/${vars.wbs}-verify-answer.txt
+          answerFile: .spur/run/${vars.__runId}-docs-verify-answer.txt
       - kind: shell
         options:
-          command: "$spurBin task verdict $wbs --from-answer .spur/run/$wbs-verify-answer.txt"
-      # R7: stamp the proof block into the standard verdict artifact, then register it.
-      # Soft action + hard guard: a missing/malformed stamp fails the `verify -> done`
+          command: "$spurBin task verdict $wbs --from-answer .spur/run/$__runId-docs-verify-answer.txt"
+      # R7: stamp the proof block + run identity into the standard verdict artifact, then register
+      # it. Soft action + hard guard: a missing/malformed stamp fails the `verify -> record`
       # guard below, not this step.
       - kind: shell
         options:
           command: >-
             V=".spur/run/$wbs-verdict.json";
             if [ -f "$V" ] && [ -n "$proofDigest" ]; then
-              jq --arg d "$proofDigest" '. + {proof: {digest: $d, capturePoint: "docs-verify-entry"}}' "$V" > "$V.tmp" && mv "$V.tmp" "$V";
+              jq --arg d "$proofDigest" --arg r "$__runId" '. + {proof: {digest: $d, capturePoint: "docs-verify-entry", runId: $r}}' "$V" > "$V.tmp" && mv "$V.tmp" "$V";
             fi;
             exit 0
       - kind: run.artifact
@@ -192,6 +194,37 @@ states:
           input: /sp:dev-verify ${vars.wbs} --auto --fix none --focus all
           timeoutMs: ${vars.stepTimeoutMs}
 
+  - id: record
+    description: >
+      Record the docs-only outcome AFTER measured verification (task 0769 ordering:
+      draft/approval → verify → record → done — the pre-verification record could write
+      UNKNOWN/old Testing evidence). The verdict is already derived and proof-bracketed in
+      `verify`; `verify → record` only opens on measured PASS with an intact bracket. The
+      task record verb backfills Solution from the diff and moves the task to testing; its
+      result is captured to a run-scoped status file so a record denial reaches `failed`
+      (record → failed) and is never converted to success by an exit 0.
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            if $spurBin task record $wbs --solution-from-diff --transition testing; then
+              printf 'PASS\n' > ".spur/run/$__runId-docs-record.status";
+            else
+              printf 'FAIL\n' > ".spur/run/$__runId-docs-record.status";
+            fi
+
+  - id: done
+    description: Terminal — docs deliverable measured, reviewed, and recorded.
+    onEnter:
+      # R1 (0704): no synthetic verdict writer. The verdict artifact is produced by measured
+      # verification in `verify` and registered there; done only performs the guarded
+      # transition. Override path remains: --force-done --reason.
+      - kind: shell
+        options:
+          command: "$spurBin task update $wbs done --no-lifecycle"
+      - kind: note
+        options:
+          message: "Docs pipeline complete for task ${vars.wbs}."
   - id: failed
     description: Terminal — docs pipeline failed or was rejected.
 
@@ -213,8 +246,8 @@ transitions:
       kind: always
 
   - from: draft
-    to: record
-    description: profile=auto — skip the docs-review HITL gate.
+    to: verify
+    description: "profile=auto — skip the docs-review HITL gate; verify measures BEFORE record (0769: a pre-verification record could write UNKNOWN/old Testing evidence)."
     guard:
       kind: shell
       options:
@@ -226,8 +259,8 @@ transitions:
       kind: always
 
   - from: docs-review
-    to: record
-    description: Docs approved — record results.
+    to: verify
+    description: "Docs approved — measure the deliverable (0769: verification precedes recording)."
     guard:
       kind: shell
       options:
@@ -247,16 +280,11 @@ transitions:
       options:
         command: 'test "$__hitlAnswer" = cancel'
 
-  - from: record
-    to: verify
-    description: Recorded — measure the deliverable (R2). Structural task-check gates remain
-      at precheck, record (wip→testing), and done (verdict-artifact guard, R3).
-    guard:
-      kind: always
-
   - from: verify
-    to: done
-    description: Measured PASS with the proof bracket intact (R4/R5).
+    to: record
+    description: Measured PASS with the proof bracket intact (R4/R5) — record only verified
+      outcomes (0769). Structural task-check gates remain at precheck, record (wip→testing),
+      and done (verdict-artifact guard, R3).
     guard:
       kind: shell
       options:
@@ -274,6 +302,25 @@ transitions:
   - from: verify
     to: failed
     description: Non-PASS verdict, missing/malformed answer, or digest mismatch (R5) — the run
-      reaches failed and no PASS artifact is certified.
+      reaches failed and nothing is recorded.
+    guard:
+      kind: always
+
+  - from: record
+    to: done
+    description: Recorded from a verified outcome; the persisted verdict/bracket is re-asserted
+      so a failed `task record` (captured FAIL) never converts to done (0769).
+    guard:
+      kind: shell
+      options:
+        command: >-
+          test "$(cat .spur/run/$__runId-docs-record.status 2>/dev/null)" = PASS &&
+          test -f ".spur/run/$wbs-verdict.json" &&
+          test "$(jq -r '.verdict // empty' .spur/run/$wbs-verdict.json 2>/dev/null)" = PASS &&
+          test -n "$proofDigest" &&
+          test "$(jq -r '.proof.digest // empty' .spur/run/$wbs-verdict.json 2>/dev/null)" = "$proofDigest"
+  - from: record
+    to: failed
+    description: "Task record denied or errored (captured status not PASS) — the record denial reaches failed; the done guard above never converts it to success."
     guard:
       kind: always

package/config/workflows/feature-dev.yaml

@@ -9,6 +9,7 @@
 "$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
 kind: state-machine
 name: feature-dev
+version: "1"
 description: >
   End-to-end FEATURE development loop: precheck → brainstorm → plan (decompose) →
   execute-tasks → feature-verify → done. Drives a whole feature (one description → a
@@ -143,32 +144,56 @@ states:
 
   - id: integration-review
     description: >
-      Advisory integration review (D5-P, feature R11). Runs `config/workflows/pr-review.yaml`
-      ONCE for this feature/branch HEAD, after the local gates and before wrap merge/cleanup.
-      Current-HEAD dedup stays inside pr-review (`mode: full`), so a re-entry on the same HEAD
-      is a no-op there rather than a second quota spend here.
+      Advisory integration review (D5-P, feature R11), upgraded by 0770 to a
+      truthful collect: ONE Codex review request per HEAD, then exactly ONE
+      `pr-reviewing.ts collect --head <captured-head>` against that same HEAD —
+      no wait loop, no polling. The request verdict (`REQUESTED` /
+      `ALREADY_REQUESTED` / `ALREADY_REVIEWED`) describes request state only;
+      it is NEVER clean evidence. The ONLY clean evidence is the collected
+      status (CLEAN / FINDINGS / PENDING) persisted run-scoped at
+      .spur/run/<runId>-integration-review-collect.status. A missing head SHA,
+      an invalid collect result, or head drift records collect FAIL.
 
-      The gate is `softFail: true`, so `pending`, a wait timeout, a missing pr-review
-      definition, or an unavailable review quota records FAIL and still reaches `done`.
-      Only `requireCleanReview=true` turns that FAIL into a blocking edge. Findings are
-      collected by pr-review itself and re-enter the affected local gates on the next run.
+      D8 decision D1 (0753 R3): invoking `pr-reviewing.ts request` directly —
+      the same per-HEAD dedupe-or-request logic `config/workflows/pr-review.yaml`
+      uses internally. Request FAIL records FAIL in
+      .spur/run/<runId>-integration-review.status, loudly (no softFail).
+      `requireCleanReview=true` turns a non-clean COLLECTED verdict (including
+      collect FAIL) into the blocking edge declared first below.
     onEnter:
-      - kind: command.gate
+      - kind: shell
         options:
-          id: feature-integration-review
-          executable: "${vars.spurBin}"
-          args:
-            - workflow
-            - run
-            - .spur/workflows/pr-review.yaml
-            - --vars
-            - '{"mode":"full","baseBranch":"${vars.baseBranch}"}'
-          resultFile: .spur/run/${vars.__runId}-integration-review.status
-          softFail: true
-          timeoutMs: 1800000
+          command: >-
+            mkdir -p .spur/run &&
+            STATUS_FILE=".spur/run/$__runId-integration-review.status" &&
+            REQUEST_JSON=".spur/run/$__runId-integration-review.json" &&
+            COLLECT_JSON=".spur/run/$__runId-integration-review-collect.json" &&
+            COLLECT_STATUS=".spur/run/$__runId-integration-review-collect.status" &&
+            PR_REQUEST_STATUS=".spur/run/$__runId-integration-review-pr-request.status" &&
+            set +e &&
+            bun "$(superskill script path sp pr-reviewing.ts)" request --base "$baseBranch" --json
+            --status-file "$PR_REQUEST_STATUS" > "$REQUEST_JSON" 2>&1;
+            request_rc=$?; set -e &&
+            if [ "$request_rc" -eq 0 ]; then
+              printf 'PASS\n' > "$STATUS_FILE";
+            else
+              printf 'FAIL\n' > "$STATUS_FILE";
+            fi &&
+            HEAD_SHA=$(jq -r '.head // empty' "$REQUEST_JSON" 2>/dev/null || true) &&
+            if [ -z "$HEAD_SHA" ]; then
+              echo "integration-review: request result carried no head SHA — collect not run, recorded FAIL" >&2;
+              printf 'FAIL\n' > "$COLLECT_STATUS";
+            else
+              set +e &&
+              bun "$(superskill script path sp pr-reviewing.ts)" collect --head "$HEAD_SHA" --json
+              --status-file "$COLLECT_STATUS" > "$COLLECT_JSON" 2>&1;
+              collect_rc=$?; set -e &&
+              echo "integration-review: collect rc=$collect_rc status=$(cat "$COLLECT_STATUS" 2>/dev/null || echo missing) — verdict captured to $COLLECT_JSON" >&2;
+            fi;
+            exit 0
       - kind: note
         options:
-          message: "Integration review for feature ${vars.featureId} recorded at .spur/run/${vars.__runId}-integration-review.status (advisory unless requireCleanReview=true)."
+          message: "Integration review for feature ${vars.featureId}: request verdict at .spur/run/${vars.__runId}-integration-review.status (request state only — REQUESTED/ALREADY_* are NEVER clean evidence); collected verdict at .spur/run/${vars.__runId}-integration-review-collect.status (CLEAN/FINDINGS/PENDING — the only clean evidence). Advisory unless requireCleanReview=true."
 
   - id: done
     description: Terminal — feature planned, all tasks executed, and the feature verified.
@@ -239,18 +264,23 @@ transitions:
   - from: integration-review
     to: failed
     description: >
-      Review came back FAIL and this branch opted into a hard gate
-      (requireCleanReview=true). Ordered before the advisory edge so the strict
-      policy wins when both would match.
+      Collected verdict is not CLEAN (FINDINGS / PENDING / collect FAIL or
+      missing) and this branch opted into a hard gate (requireCleanReview=true).
+      Exactly one collect ran against the captured request HEAD — no wait loop —
+      so pending or findings stop the feature here with the actual reason.
+      Ordered before the advisory edge so the strict policy wins when both
+      would match.
     guard:
       kind: shell
       options:
-        command: 'test "$requireCleanReview" = true && test "$(cat .spur/run/$__runId-integration-review.status 2>/dev/null)" = FAIL'
+        command: 'test "$requireCleanReview" = true && test "$(cat .spur/run/$__runId-integration-review-collect.status 2>/dev/null)" != CLEAN'
   - from: integration-review
     to: done
     description: >
-      Review clean, pending, unavailable, or advisory — the feature is complete. A
-      non-clean advisory review never blocks a locally-verified feature (feature R11).
+      Collected CLEAN, or advisory mode (requireCleanReview != true) — the
+      feature is complete. A non-clean advisory collect never blocks a
+      locally-verified feature (feature R11); the note above preserves the
+      collected non-clean state in the run record instead of hiding it.
     guard:
       kind: always
   - from: feature-verify

package/config/workflows/feature-lifecycle.yaml

@@ -9,6 +9,7 @@
 "$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
 kind: state-machine
 name: feature-lifecycle
+version: "1"
 description: >
   Feature lifecycle FSM (design §2.3, §5.1, DD-13). States are the canonical
   FeatureStatus vocabulary; transitions encode the §2.3 graph including the

package/config/workflows/history-anatomy.yaml

@@ -48,6 +48,7 @@
 "$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
 kind: state-machine
 name: history-anatomy
+version: "1"
 description: "Daily/ad-hoc history-anatomy report: cache branch, deterministic analyze/render, skill enrichment, deterministic structure gate, independent evidence validation, bounded correction, atomic publication"
 iterationBound: 20
 initialState: start
@@ -153,7 +154,7 @@ states:
             --baseline .spur/run/$__runId-history-anatomy-baseline.json --target "$HA_TARGET"
             --mode "$mode" --date "$HA_DATE" --recompute "$recompute" --executor "$agent"
             --skill-dir "$HA_SKILL" --contract "$HA_SKILL/references/report-contract.md"
-            --workflow "$workflowFile" --contract-version "$contractVersion" --run-id "$__runId"
+            --workflow "$workflowFile" --helper "$HA_HELPER" --contract-version "$contractVersion" --run-id "$__runId"
             --out .spur/run/$__runId-provenance.json
             > .spur/run/$__runId-cache-disposition.txt
 
@@ -208,6 +209,9 @@ states:
     description: >
       Independent evidence validation via the skill operation sp:history-anatomy validate.
       Publication is reachable only from a PASS here. Same undeclared-write assertion as enrich (0676 R3).
+      The publish guard reads the ANCHORED FINAL LINE (0771): only a validation artifact whose last
+      line is exactly `Verdict: PASS` publishes — a leading PASS under a later FAIL or a
+      `not Verdict: PASS` line can never satisfy it.
     onEnter:
       - kind: shell
         options:
@@ -390,18 +394,18 @@ transitions:
 
   - from: validate
     to: stamp
-    description: Independent validation PASS — stamp provenance, then publish atomically.
+    description: Independent validation PASS (anchored final line, 0771) — stamp provenance, then publish atomically.
     guard:
       kind: shell
       options:
-        command: 'grep -q "Verdict: PASS" .spur/run/$__runId-validation.txt 2>/dev/null'
+        command: 'tail -n 1 .spur/run/$__runId-validation.txt 2>/dev/null | grep -qx "Verdict: PASS"'
   - from: validate
     to: correct
     description: Validation FAIL under the shared two-pass correction cap.
     guard:
       kind: shell
       options:
-        command: '! grep -q "Verdict: PASS" .spur/run/$__runId-validation.txt 2>/dev/null && test "$(cat .spur/run/$__runId-correction-count 2>/dev/null || echo 0)" -lt 2'
+        command: '! tail -n 1 .spur/run/$__runId-validation.txt 2>/dev/null | grep -qx "Verdict: PASS" && test "$(cat .spur/run/$__runId-correction-count 2>/dev/null || echo 0)" -lt 2'
   - from: validate
     to: failed
     description: Validation FAIL with the correction cap exhausted — terminate without publishing.