@gobing-ai/spur 0.3.90 → 0.3.92

package/.claude-plugin/marketplace.json

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

package/config/pipeline-budgets.json

@@ -36,10 +36,10 @@
             "decision": null
         },
         "history-anatomy": {
-            "modelQueries": 4,
+            "modelQueries": 3,
             "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.",
+            "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. 0920 recount 2026-09-23: 4 -> 3 — the resolve-scope model hop was removed; scope/window validation is deterministic in the history-anatomy-cache paths command.",
             "decision": null
         },
         "wayfinder-resolution": {
@@ -48,6 +48,13 @@
             "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
+        },
+        "decision-routing-example": {
+            "modelQueries": 0,
+            "wallClockMs": null,
+            "tokenCostUsd": null,
+            "source": "Coverage entry (0911): authoring example (config/workflows/decision-routing-example.yaml) enumerating `decision:` modes. Measured 0 model queries — the producer is a shell action, so the example runs with no provider (live count via loadQueryCounts, 2026-09-20). Not a pipeline humans run; wall-clock and cost unenforced, never 0.",
+            "decision": null
         }
     }
 }

package/config/plugin-scripts.json

@@ -48,7 +48,13 @@
         },
         {
             "rel": "inline-run-setup.ts",
-            "contract": "repo-only"
+            "contract": "standard",
+            "twin": "inline-run-setup.mjs"
+        },
+        {
+            "rel": "feature-verification-steps.ts",
+            "contract": "standard",
+            "twin": "feature-verification-steps.mjs"
         },
         {
             "rel": "idea-coverage-check.ts",
@@ -63,11 +69,21 @@
             "contract": "standard",
             "twin": "pr-reviewing.mjs"
         },
+        {
+            "rel": "record-feature-sync.ts",
+            "contract": "standard",
+            "twin": "record-feature-sync.mjs"
+        },
         {
             "rel": "quality-gate.ts",
             "contract": "standard",
             "twin": "quality-gate.mjs"
         },
+        {
+            "rel": "residual-scan.ts",
+            "contract": "standard",
+            "twin": "residual-scan.mjs"
+        },
         {
             "rel": "script-contract-check.ts",
             "contract": "repo-only"

package/config/workflows/decision-routing-example.yaml

@@ -0,0 +1,134 @@
+# DecisionMaker routing example (task 0911, D7). Demonstrates the three `decision:` modes
+# on hitl.* actions; copy the pattern into your own workflow instead of running this file.
+#
+#   never    — the action always asks the human (DecisionMaker is bypassed even when
+#              `workflow.hitlDecisionMaker: true`). Used for gates that must stay human-only.
+#   evidence — the DecisionMaker answers from recorded action evidence of the listed producer
+#              states: it picks one of the offered choices when confidence >= 0.9, or defers
+#              (answer var is cleared, status var records `deferred`) when evidence is missing,
+#              stale, or inconclusive. Requires a non-paused state, a statusVar distinct from
+#              the answer var, and producer states that exist in this workflow.
+#   (omitted) — legacy 0910 semantics: DecisionMaker may confirm/select without evidence and
+#              without provenance. Kept for compatibility; prefer an explicit mode.
+#
+# The run is safe and local: one shell producer emits a fixed failure summary, the choose step
+# reads it as evidence, and the operator gate has no side effects. No provider is required —
+# without `workflow.hitlDecisionMaker: true` (or without a key) the evidence step defers and
+# `never` behaves exactly like an unconfigured gate. See `spur self status` -> `decisionMaker`
+# for offline readiness. Optional registered-summary evidence (`summaryArtifact`) is documented
+# in docs/help/how_to_enable_jev_in_spur.md; this example deliberately creates no artifact.
+"$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
+kind: state-machine
+name: decision-routing-example
+version: "1"
+initialState: assess
+description: >
+  Worked example of DecisionMaker decision routing (0911 D7): a shell producer records a fixed
+  recovery summary as action evidence, a non-pausing hitl.select lets the DecisionMaker choose
+  retry or stop from that evidence (deferring with provenance when it is inconclusive), an
+  accepted retry runs exactly one attempt and then escalates, and the never-mode pause=true
+  hitl.confirm gate always waits for the operator with explicit yes/no/cancel branches.
+  Illustrative only — copy the patterns rather than running this file.
+vars:
+    recoveryChoice: ""
+    decisionStatus: ""
+    # Default answer var the never-mode gate's yes/no/cancel branches read (matches the stock gates).
+    __hitlAnswer: ""
+states:
+  - id: assess
+    description: >
+      Producer state: one shell action whose redacted output becomes the evidence the decide
+      state's DecisionMaker reads. One producer state carries one evidence-bearing action.
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            printf 'Failure summary: verification failed twice on the flaky fixture; no data loss;
+            retry is safe, or stop and hand the decision to the operator.'
+  - id: decide
+    description: >
+      Evidence-mode select (non-paused): DecisionMaker picks a recovery step from the assess
+      state's recorded evidence. Low confidence, missing or stale evidence defers and writes the
+      status variable instead of answering, so no implicit approval is ever produced.
+    onEnter:
+      - kind: hitl.select
+        options:
+          prompt: "Choose the next safe recovery step using the recorded failure summary."
+          options: [retry, stop]
+          var: recoveryChoice
+          decision:
+            mode: evidence
+            statusVar: decisionStatus
+            evidenceNodes: [assess]
+  - id: retry
+    description: >
+      The single bounded retry an accepted `retry` choice buys: this state runs once and routes
+      to the operator gate, so an accepted answer can never loop back into the decision.
+    onEnter:
+      - kind: shell
+        options:
+          command: "printf 'retry attempt: re-running the failed verification step once'"
+  - id: humanGate
+    description: >
+      Never-mode confirm (paused): always waits for the operator, whichever branch reached it.
+      `spur workflow continue --answer yes|no|cancel` records the explicit operator answer.
+    pause: true
+    onEnter:
+      - kind: hitl.confirm
+        options:
+          prompt: "Publish the recovered result, stop, or cancel the run?"
+          decision:
+            mode: never
+  - id: published
+    description: Operator approved the recovered result; terminal marker state.
+  - id: stop
+    description: Recovery stopped deliberately — requested by the decision or rejected by the operator.
+  - id: cancelled
+    description: Operator cancelled the run at the gate; terminal marker state.
+transitions:
+  # Accepted decision branches first: the state machine takes the first passing edge.
+  - from: assess
+    to: decide
+    guard: { kind: always }
+  - from: decide
+    to: retry
+    guard:
+      kind: shell
+      options:
+        command: 'test "$recoveryChoice" = "retry"'
+  - from: decide
+    to: stop
+    guard:
+      kind: shell
+      options:
+        command: 'test "$recoveryChoice" = "stop"'
+  # Declared defer edge: evidence mode wrote `deferred` and cleared the answer var.
+  - from: decide
+    to: humanGate
+    guard:
+      kind: shell
+      options:
+        command: 'test "$decisionStatus" = "deferred"'
+  - from: retry
+    to: humanGate
+    guard: { kind: always }
+  # Explicit yes / no / cancel branches on the default answer var, matching the stock gates.
+  - from: humanGate
+    to: published
+    guard:
+      kind: shell
+      options:
+        command: 'test "$__hitlAnswer" = "yes"'
+  - from: humanGate
+    to: stop
+    guard:
+      kind: shell
+      options:
+        command: 'test "$__hitlAnswer" = "no"'
+  - from: humanGate
+    to: cancelled
+    guard:
+      kind: shell
+      options:
+        command: 'test "$__hitlAnswer" = "cancel"'
+terminalStates: [published, stop, cancelled]

package/config/workflows/feature-lifecycle.yaml

@@ -40,9 +40,17 @@ states:
     onEnter:
       # Caller wiring (task 0880, ADR-119): entering verification RUNS the
       # feature-scoped pass instead of only passively reading its status file.
+      # 0948 R1: pass BOTH vars the inner workflow needs. `--vars` was documented as
+      # replace-not-merge and a partial override silently blanked `spurBin`; the engine
+      # merges declared defaults today (0948 R2), but the caller stays explicit so the
+      # nested run is self-sufficient under either semantic.
       - kind: shell
         options:
-          command: '$spurBin workflow run feature-verification.yaml --vars "{\"featureId\":\"$featureId\"}"'
+          # Pass featureId and spurBin together. A partial --vars map used to be
+          # applied as a replacement, so the inner run lost spurBin and loadModule
+          # fell into source mode (0948 R1). The nested JSON is shell-expanded:
+          # $spurBin inside the double quotes keeps a multi-word invocation intact.
+          command: '$spurBin workflow run feature-verification.yaml --vars "{\"featureId\":\"$featureId\",\"spurBin\":\"$spurBin\"}"'
   - id: blocked
     description: Impediment; work suspended.
   - id: done
@@ -68,13 +76,14 @@ transitions:
   - from: verifying
     to: done
     description: >
-      Feature verified — complete. Requires the feature-scoped verification pass
-      (ADR-119) to have recorded PASS, then strict check (AC validated,
-      traceability clean).
+      Feature verified — complete. The strict check at the done boundary also
+      validates the bound verification receipt (D63 task 0915): current, PASS,
+      matching feature identity and verifier contract, digest-chained to the
+      checked inputs. Stale/missing/failed evidence denies the hop.
     guard:
       kind: shell
       options:
-        command: 'test "$(cat .spur/run/$featureId-feature-verification.status 2>/dev/null)" = PASS && $spurBin feature check $featureId --strict --as done'
+        command: '$spurBin feature check $featureId --strict --as done'
 
   # Rework: verifying → active (mandatory History entry)
   - from: verifying

package/config/workflows/feature-verification.yaml

@@ -1,29 +1,34 @@
-# Feature-scoped verification pass (ADR-119, feature D62, task 0872).
+# Feature-scoped verification pass (ADR-119, feature D62, task 0872; D63 task
+# 0915 remediation folds the evidence contract into a workflow-owned script).
 #
 # 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, deliberately
-# the slow pass; `feature-lifecycle`'s verifying entry invokes this workflow (task
-# 0880 caller wiring), and its verifying→done guard refuses to complete the
-# feature until this pass records PASS (ADR-119 consequence: a feature is not
-# done until it passes).
+# invariant spans the repository rather than a single task's diff. They run
+# once per feature, deliberately the slow pass; `feature-lifecycle`'s verifying
+# entry invokes this workflow (task 0880 caller wiring), and its 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"}'
+# Run: spur workflow run feature-verification.yaml --vars '{"featureId":"D63"}'
 #
-# 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.
+# Shape: verify -> done | failed. The onEnter step runs the standard script
+# `feature-verification-steps.ts` (no public CLI verb, D63 task 0915): it
+# resolves this very definition for the verifier identity (name, source path,
+# layer, definition digest), records the RUNNING receipt (run-scoped +
+# feature-latest copies), registers the run-scoped receipt as a run artifact,
+# runs the configured verification command via the safe launch splitter, and
+# completes the receipt PASS/FAIL with the after-pass proof-input digest. A
+# changed tree during the pass records FAIL.
 #
 # 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).
+# verification command comes from `vars.verificationCmd` below and is never
+# interpolated through a shell. The always-exit-0 onEnter means missing,
+# corrupt or FAIL evidence routes to `failed` via the guard (fail-closed),
+# never a silent PASS; infrastructure errors exit nonzero and surface.
 "$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 and records PASS/FAIL. Invoked by feature-lifecycle's verifying entry."
+description: "Feature-scoped verification pass (ADR-119): runs the repo-wide check set once per feature and records a bound PASS/FAIL evidence receipt. Invoked by feature-lifecycle's verifying entry."
 iterationBound: 2
 initialState: verify
 terminalStates:
@@ -35,37 +40,40 @@ vars:
   featureId: "X"
   spurBin: "spur"
   verificationCmd: "bun run spur-check-feature"
+  __runId: ""
 
 states:
   - id: verify
     description: >
-      Run the repo-wide check set, record the verdict, always exit 0.
+      Run the repo-wide check set via the standard verification script, which
+      records the bound evidence receipt (verifier identity, checked-input
+      digest, run identity) and the coarse status file, always exit 0 so the
+      transition guard routes missing/corrupt/FAIL to `failed`.
     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
+            bun plugins/sp/scripts/feature-verification-steps.ts verify
+            --feature-id "$featureId"
+            --run-id "$__runId"
+            --spur-bin "$spurBin"
 
   - id: done
-    description: Terminal — repo-wide checks passed.
+    description: Terminal — repo-wide checks passed and the receipt is bound.
 
   - id: failed
-    description: Terminal — repo-wide checks failed or the verdict is missing/corrupt.
+    description: Terminal — repo-wide checks failed or the evidence is missing/corrupt.
 
 transitions:
   - from: verify
     to: done
-    description: Repo-wide checks passed — the feature-scoped verification pass records PASS.
+    description: Repo-wide checks passed — the script completed the receipt with PASS.
     guard:
       kind: shell
       options:
-        command: 'test "$(cat .spur/run/$featureId-feature-verification.status 2>/dev/null)" = PASS'
+        command: 'test "$(cat .spur/run/$__runId-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.
+    description: Repo-wide checks failed (or the evidence is missing/corrupt) — stop at failed.
     guard:
       kind: always

package/config/workflows/history-anatomy.yaml

@@ -11,7 +11,7 @@
 # would exceed the shell composition threshold and be flagged as an owned-capability candidate.
 #
 # Shape:
-#   start -> resolve-scope -> resolve-paths -> analyze -> cache-probe
+#   start -> resolve-paths -> analyze -> cache-probe
 #            (hit  -> refresh-provenance -> publish -> published)
 #            (miss -> render -> enrich -> structure-gate -> validate -> stamp -> publish)
 #            (structure-gate FAIL -> correct (max 2 total) -> structure-gate; exhausted -> failed)
@@ -28,7 +28,7 @@
 #
 # Vars (all must be declared here — the vars: block is the only safe shape; `spur workflow
 # validate` and the skill-structure test enforce it):
-#   mode      — "daily" (default) | "ad-hoc" (validated in resolve-scope)
+#   mode      — "daily" (default) | "ad-hoc" (validated deterministically by the helper `paths` command)
 #   date      — YYYY-MM-DD for --date (daily); empty for ad-hoc
 #   since     — inclusive ISO lower bound (ad-hoc; also normalizes daily via the DST-aware rule)
 #   until     — inclusive ISO upper bound (ad-hoc)
@@ -39,7 +39,7 @@
 #   focus     — ad-hoc focus string (required in ad-hoc mode, rejected in daily)
 #   recompute — "true" forces the full analyze/render/enrich/validate path (cache disposition
 #               forced-recompute)
-#   output    — explicit report output path; default run directory
+#   output    — explicit report output path; default docs/report/<date>-history-anatomy.md
 #   agent     — executor for the agent.run stages (enrich/validate)
 #   spurBin   — PATH-independent spur invocation (overridden by CLI at run start)
 #   __runId   — run-scoped id for explicit artifact paths (allocated in start)
@@ -85,28 +85,22 @@ states:
     description: >
       Allocate the run-scoped id and root. Every analyze/render path in this workflow writes to
       an explicit unique path under this run id — no stage reads the mutable latest.json pointer.
+      The retained identity is `.spur/run/<runId>-history-anatomy-run.id` (0948 R8). The fixed
+      `history-anatomy-run.id` name is only a latest pointer and is overwritten by the next run.
     onEnter:
       - kind: shell
         options:
           command: >-
             mkdir -p .spur/run;
             if [ -z "$__runId" ]; then __runId=$(uuidgen | tr 'A-Z' 'a-z' | cut -c1-8); fi;
-            echo "$__runId" > .spur/run/history-anatomy-run.id
+            echo "$__runId" > ".spur/run/$__runId-history-anatomy-run.id";
+            cp ".spur/run/$__runId-history-anatomy-run.id" .spur/run/history-anatomy-run.id
+          # 0948 R8 retention disposition: `history-anatomy-run.id` is a SINGLE fixed-name
+          # pointer that is overwritten every run — it does not accumulate, so it needs no
+          # reclamation path (unlike the run-record pair and legacy `.log` files, which
+          # `spur workflow clean --logs` owns). It is deliberately NOT a run record and is
+          # exempt from the catalog record-name sweep (see run-record-catalog.test.ts).
 
-  - id: resolve-scope
-    description: >
-      Dispatch the skill's mode validation (0658 references/modes.md): daily is the default and
-      rejects focus/since/until/output; ad-hoc requires a non-empty focus plus two ordered
-      inclusive bounds and rejects --date/--recompute. Writes the normalized selector artifact.
-    onEnter:
-      - kind: agent.run
-        options:
-          agent: ${vars.agent}
-          input: "Validate the mode arguments per sp:history-anatomy references/modes.md and write the normalized selector to .spur/run/${vars.__runId}-selector.json. mode=${vars.mode} date=${vars.date} since=${vars.since} until=${vars.until} focus=${vars.focus}. Reject conflicting arguments, naming the offending one; a rejection marks the run failed."
-          # Declared Layer-1 role (0538 R2): mode validation is a reviewer-standard judgment.
-          role: reviewer
-          expectFile: .spur/run/${vars.__runId}-selector.json
-          timeoutMs: ${vars.stepTimeoutMs}
 
   - id: resolve-paths
     description: >
@@ -122,6 +116,7 @@ states:
             h=$(superskill script path sp history-anatomy-cache.mjs);
             node "$h" paths --helper "$h" --report-dir "$reportDir" --date "$date"
             --output "$output" --mode "$mode" --since "$since" --until "$until"
+            --focus "$focus" --recompute "$recompute" --run-id "$__runId"
             --out .spur/run/$__runId-paths.txt
 
   - id: analyze
@@ -338,14 +333,8 @@ states:
 
 transitions:
   - from: start
-    to: resolve-scope
-    description: Scope resolved.
-    guard:
-      kind: always
-
-  - from: resolve-scope
     to: resolve-paths
-    description: Mode valid — resolve helper/skill/target paths once.
+    description: Mode/window grammar validated and paths resolved once (deterministic).
     guard:
       kind: always
 

package/config/workflows/idea-pipeline.yaml

@@ -145,6 +145,8 @@ states:
       - kind: hitl.confirm
         options:
           prompt: "Review the idea evaluation report (.spur/run/${vars.__runId}-idea-eval-report.md). Approve to create a feature, or reject to cancel? (Reject creates no feature.)"
+          decision:
+            mode: never
 
   - id: feature-create
     description: >
@@ -282,6 +284,8 @@ states:
       - kind: hitl.confirm
         options:
           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.)"
+          decision:
+            mode: never
 
   - id: system-design
     description: >
@@ -358,6 +362,8 @@ states:
       - kind: hitl.confirm
         options:
           prompt: "Review the system design for feature ${vars.featureId}. Approve to proceed to decomposition? To reject, first record your feedback in .spur/run/${vars.__runId}-idea-design-review.md under the `## Operator feedback` heading, then answer no."
+          decision:
+            mode: never
 
   - id: decompose
     description: >
@@ -416,6 +422,8 @@ states:
       - kind: hitl.confirm
         options:
           prompt: "Batch-create for feature ${vars.featureId}. Review the task batch and confirm to proceed? (Failures route back to decompose for revision, capped at 3 retries.)"
+          decision:
+            mode: never
 
   - id: batch-create-run
     description: >
@@ -453,10 +461,12 @@ states:
       plan, ac, decisions, dependencies, premises) so the deterministic task
       check passes, then writes the run-scoped ready evidence sidecar
       (.spur/run/${vars.__runId}-idea-ready.json) with one row per task: wbs,
-      status (ready|failed|skipped), planningDigest, and seven check rows.
-      Handoff-finalize verifies presence, digest and checklist evidence before
-      recommending auto runall; missing or failing evidence never fails the
-      run — it degrades the recommendation to ready-depth refineall.
+      status (ready|failed|skipped), planningDigest, and seven check rows,
+      with the premises row carrying tree-verified path:line citations
+      (0947). Handoff-finalize verifies presence, digest, feature binding and
+      checklist evidence before recommending auto runall; missing or failing
+      evidence never fails the run — it degrades the recommendation to
+      ready-depth refineall.
     onEnter:
       - kind: agent.run
         options:
@@ -475,7 +485,9 @@ states:
             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.
+            .spur/run/${vars.__runId}-idea-ready.json. The premises check row passes only
+            when each material premise was verified against the current tree and its evidence
+            cites at least one verified path:line (handoff-finalize lints it; task 0947).
           answerFile: .spur/run/${vars.__runId}-ready-prepare-answer.txt
           expectFile: .spur/run/${vars.__runId}-ready-prepare-answer.txt
       # Fail-closed shape validation (mirrors the order-sidecar guard). Absence is