@gobing-ai/spur 0.3.99 → 0.4.0

package/.claude-plugin/marketplace.json

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

package/config/config.global.yaml

@@ -149,3 +149,20 @@ agent:
 # extra workflow folders by concatenating them here (loader merge):
 workflows:
     paths: []
+
+# Decision catalogs (feature P / ADR-134): the project layer is always
+# `<cwd>/.spur/decisions` and the shared layer is the installed package's own
+# `config/decisions`, so no config entry is needed to discover the shipped
+# catalogs. `paths` registers extra catalog folders (absolute or
+# project-relative); the first layer wins per file basename (ADR-113 style).
+# `maker` selects the default DecisionMaker for every decision point, and
+# `makers` overrides it per decision id. Built-in makers: typesafe, fm-local,
+# laya-local (laya-local needs Apple Silicon). An unregistered name is a config
+# error, never a silent fallback. Inspect the effective choice with
+# `spur decision status`. `init` never overwrites this file — until you add the
+# keys, the shipped catalog's maker applies (see `status`).
+decisions:
+    paths: []
+    maker: typesafe
+    # makers:
+    #     task-triage: laya-local

package/config/decisions/task-pipeline.yaml

@@ -0,0 +1,55 @@
+$schema: "@gobing-ai/spur/schemas/decision-catalog.schema.json"
+# Decision catalogs for the task pipeline (feature P / task 1092, ADR-134).
+#
+# These entries mirror the inline decide actions that ship in
+# config/workflows/task-pipeline.yaml today — same questions, choices and
+# fallbacks — so their reliability can be measured with `spur decision run`
+# before feature P1 migrates the workflow actions onto them (design §3.5).
+# No workflow references this catalog yet.
+#
+# Resolution: this file ships in the shared layer (the installed package's
+# config/decisions/). A project can override it per basename through
+# .spur/decisions/ or decisions.paths (first layer wins, ADR-113 style).
+version: 1
+
+defaults:
+    # ADR-125 value, kept over the upstream 0.7 default.
+    minConfidence: 0.8
+
+decisions:
+    task-triage:
+        type: choice
+        description: Which verification lane does a green-gate diff deserve?
+        parameters:
+            wbs:
+                type: string
+                description: Task WBS the diff belongs to.
+        criteria:
+            low: Small, contained diff — the fast lane is enough.
+            standard: Ordinary diff — the standard verification lane applies.
+            high: Broad or risky diff — verify with high caution.
+        fallback: standard
+
+    failure-class:
+        type: choice
+        description: Is a failed quality gate fixable by the repair agent, or should the run stop?
+        parameters:
+            wbs:
+                type: string
+                description: Task WBS whose gate failed.
+        criteria:
+            fix: The failure looks fixable — send it to the repair agent.
+            stop: The failure is not mechanically fixable — stop the run for the operator.
+        fallback: fix
+
+    review-failure-class:
+        type: choice
+        description: Is a non-PASS review fixable by the repair agent, or should the run stop?
+        parameters:
+            wbs:
+                type: string
+                description: Task WBS whose review did not certify PASS.
+        criteria:
+            fix: The findings look fixable — send them to the repair agent.
+            stop: The findings are not mechanically fixable — stop the run for the operator.
+        fallback: fix

package/config/plugin-scripts.json

@@ -76,11 +76,21 @@
             "contract": "standard",
             "twin": "residual-scan.mjs"
         },
+        {
+            "rel": "run-summary.ts",
+            "contract": "standard",
+            "twin": "run-summary.mjs"
+        },
         {
             "rel": "script-root.ts",
             "contract": "standard",
             "twin": "script-root.mjs"
         },
+        {
+            "rel": "session-timeline.ts",
+            "contract": "standard",
+            "twin": "session-timeline.mjs"
+        },
         {
             "rel": "task-diffstat.ts",
             "contract": "standard",

package/config/rules/boundary/sp-runtime-path.yaml

@@ -24,6 +24,8 @@ exclude:
     # legitimately contains `config/...` documentation / self-references — not
     # runtime paths.
     - "apps/cli/config/**"
+    # Desktop stage copies the same generated build-time asset payload beside each binary.
+    - "apps/desktop/resources/**"
 rules:
     - id: sp-runtime-path
       description: >

package/config/rules/quality/coverage-gate.yaml

@@ -2,9 +2,11 @@ $schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
 # Coverage gate — per-file line coverage meets threshold from Bun's lcov output.
 # Absorbed from ts-libs/.spur/rules/quality/coverage-gate.yaml, re-scoped to
 # Spur's monorepo layout:
-#   - lcovPath kept at .coverage/lcov.info (Spur's `bun run test:coverage` —
-#     what `bun run check` and the `*:full` chains run — writes coverage there
-#     via --coverage-dir=.coverage; plain `bun run test` skips coverage)
+#   - lcovPath kept at .coverage/lcov.info (Spur's `bun run test:coverage`
+#     writes it via --coverage-dir=.coverage, and `bunfig.toml
+#     [test] coverage = true` means a plain `bun run test` writes the same
+#     artifact — so a TARGETED `bun test <file>` overwrites it with a partial
+#     tracefile, and this rule then judges that partial data)
 #   - include expanded to apps/** + packages/** (Spur tests cover both;
 #     ts-libs only covers packages/**)
 #   - threshold kept at 90 matching bunfig.toml coverageThreshold

package/config/rules/strict/runtime-boundaries.yaml

@@ -32,6 +32,10 @@ rules:
             - "**/tests/**"
             - "**/*.test.ts"
 
+            # Electron Node adapter: ts-runtime's streaming handle uses Bun.spawn.
+            # Owns the detached process-group handle needed for startup cancellation and quit.
+            - "apps/desktop/src/server-process.ts"
+
             # Low-level system primitives:
             - "packages/app/src/services/quality-gate.ts" # gate runs `sh -c` with stdout+stderr merged onto ONE fd; ProcessExecutor captures streams separately and cannot reproduce the stream-order contract (task 1006 R1; mirrors the history-anatomy bundling exemptions)
 
@@ -60,16 +64,23 @@ rules:
             - "packages/app/src/services/token-ledger-service.ts" # FD byte-window log tailing
             - "packages/app/src/services/token-ledger-watcher.ts" # node:fs watch() live watcher
             - "packages/app/src/services/project-registry.ts" # atomic projects.json persistence
+            - "packages/app/src/services/project-server-owner.ts" # atomic mkdir lifetime claim + unique-marker stale recovery; FileSystem has no exclusive mkdir primitive (1082)
             - "packages/app/src/services/slash-commands-service.ts" # synchronous ~/.config/spur/slash_commands.json persistence (mirrors project-registry.ts)
             - "packages/app/src/services/agent-usage-producer.ts" # atomic agent-usage snapshot write (tmp + rename, mirrors project-registry.ts; task 0892 R1)
             - "packages/app/src/services/history-service.ts" # versioned analyze artifact + bounded-errors sidecar + latest.json symlink pointer (task 0474); ts-runtime FileSystem seam has no symlink, so the pointer uses node:fs directly (mirrors project-registry.ts persistence exemption)
             - "packages/app/src/services/history-anatomy.ts" # deterministic history-anatomy cache core (task 1005 R2): fsync'd tmp+rename atomic publish, readdir digest scans and sync report reads must stay byte-stable; bundled standalone for the bare-node plugin twin (mirrors agent-usage-producer.ts / history-service.ts exemptions)
             - "packages/app/src/observability/workflow-run-log-sink.ts" # sync FD append for mid-run tail-able all-in-one run log (task 0426 / feature D2); append() is sync from the observability bus
+            - "packages/app/src/observability/agent-run-log.ts" # same primitive as the sink above for the per-run agent stream (task 1076 R1, ADR-132); append() is sync from the agent service's own onOutput hook, and the byte cap needs the FD position it tracks
             - "apps/cli/src/commands/workflow.ts" # FD byte-window tail of the mid-run run log for `workflow trace --follow` streaming (task 0428 / feature D2); readSync at offset over the observability sink's FDs
             - "apps/web/src/modules/discover.ts" # Vite/Astro module scanner fallback under bun test
             - "packages/app/src/services/quality-gate.ts" # gate artifacts (log/findings/receipt) written directly; merged-fd gate log and fsync-free atomic writes must stay byte-stable; bundled standalone for the bare-node plugin twin (task 1006 R1; mirrors history-anatomy.ts)
             - "packages/app/src/services/run-storage.ts" # durable-evidence migration core (task 1025 R4): atomic tmp+rename byte copies with digest reread and atomic manifest publish must stay byte-stable (mirrors agent-usage-producer.ts / project-registry.ts exemptions)
 
+            # Electron Node adapters cannot load Bun runtime implementations; keep the
+            # synchronous existence/directory probes injected for unit testing (desktop contract).
+            - "apps/desktop/src/layout.ts"
+            - "apps/desktop/src/server-process.ts"
+
             # Synchronous bootstrap & path resolution:
             - "packages/config/src/bundled-config.ts" # sync bundledConfigRoot() directory walk
             - "packages/config/src/loader.ts" # sync resolveConfigFile() / schema specifier lookup

package/config/rules/structure/protected-files.yaml

@@ -37,6 +37,9 @@ rules:
             # this rule's include scope — scanning generated copies only adds noise
             # (e.g. `id: task-implement-transition` trips the sk- token shape).
             - "apps/cli/config/"
+            # Desktop ships the same generated config payload beside each compiled binary.
+            # Its source remains outside this source-code rule, just like the CLI bundle.
+            - "apps/desktop/resources/"
             # `apps/cli/plugins/` is the same kind of gitignored build:bundle output — a staged
             # npm copy of `plugins/`, itself outside the include scope. Minified generated libs
             # there trip the api-key shape (0976: HEAD's inline-run.generated.mjs fires too).

package/config/workflows/task-pipeline.yaml

@@ -19,6 +19,21 @@
 # done guard closed, and re-records Testing before the failed edge); done settles
 # deferrals; failed renders the recovery report. No new state, edge, or model query.
 #
+# Confidence gate (session finding after 1088, task 1068 follow-up): the verify answer has
+# carried a `Confidence: HIGH|MEDIUM|LOW` line since 1068, and nothing read it — a PASS at
+# LOW confidence certified exactly like HIGH. The verify stamp now records a `confidence`
+# check row, and BOTH completion guards (verify → record, record → done) refuse a LOW (or
+# absent) level unless the run was launched with `--vars '{"ackLowConfidence":"true"}'`.
+# The acknowledgement is an operator decision, not a model one: it is the only way to
+# certify a verdict the verifier itself would not stand behind.
+#
+# Review-failure routing (session finding after 1088): `review` had no outgoing edge for a
+# FAIL verdict, so a failing review could only be remediated by driving the graph by hand
+# (re-entering `test` and hand-emitting rows). The review stage now derives
+# `.spur/run/<wbs>-review.status` from its own answer file (fail-closed to FAIL), and a FAIL
+# routes through `review-fail-triage` — the review-side twin of `test-fail-triage` (0943) —
+# into the SAME bounded fix budget, so remediation stays on-graph and bounded.
+#
 # Vars (passed as a JSON object via `--vars`):
 #   wbs                       — task WBS (required)
 #   profile                   — "auto" skips HITL approve (R4)
@@ -36,7 +51,19 @@ kind: state-machine
 name: task-pipeline
 # 0772 R2: explicit identity tag. Set only after the proof failure-path tests
 # passed; the engine treats unversioned external definitions as supported.
-version: "3"
+# v4 (session finding after 1088): the completion gate reads the verifier's confidence level and
+# the graph routes a non-PASS review into bounded remediation — both are contract changes, so the
+# identity moves with them.
+# v5 (task 1077's inline run, 2026-10-06): the verify verdict action is explicitly `onError:
+# continue`. `task verdict` exits non-zero on any non-PASS verdict BY DESIGN (1003 R2) — that is
+# data for the verify guards, not a state failure. Under the engine's default 'fail' policy
+# (`resolveOnErrorPolicy: action ?? workflowDefault ?? runOption ?? 'fail'`) the state sequence
+# halted on that exit code and `lifecycle.fail('verify')` finalized the run before any transition
+# guard was evaluated, which made the declared `verify → test-fix` "repairable non-PASS" lane
+# UNREACHABLE: a non-PASS verify could only end the run failed. `test-fix` also gained the
+# review-lane evidence projection (see its onEnter) so the repair hop is not fed an empty findings
+# list when the failing hop was `review-fail-triage` rather than the quality gate.
+version: "5"
 description: "Standard task pipeline: precheck → implement → quality-gate (test/fix/recheck) → review → approve → verify → record → done"
 # Task entity lifecycle (owned by task-lifecycle.yaml):
 #   normal: backlog → todo → wip → testing → done
@@ -149,6 +176,14 @@ vars:
     # Escalation counter: .spur/run/<wbs>-escalation-count. Default 2 = two answered
     # questions; a third pause routes to failed with a report note.
     maxEscalations: "2"
+    # Operator acknowledgement of a LOW-confidence certification (session finding after 1088).
+    # The verify answer's `Confidence:` line is captured into the verdict artifact; a LOW (or
+    # absent) level fails the completion guards unless this is "true", because a PASS the
+    # verifier would not stand behind is an operator risk decision, not a mechanical one.
+    # Set per run: `--vars '{"ackLowConfidence":"true"}'` (and export it on the inline path).
+    # Deliberately NOT settable from the task file or the verifier's own answer: the point is
+    # that a second party, not the producer, accepts the residual uncertainty.
+    ackLowConfidence: ""
     # Runtime-written, 0933: the escalate hop's file.read.into-var fills this from
     # .spur/run/<wbs>-question.md; the hitl.input prompt below references it. Declared
     # here (empty) so the static var-reference validator sees the template source.
@@ -438,6 +473,17 @@ states:
             options:
                 command: >-
                     printf '%s\n' "$(( $(cat ".spur/run/$wbs-test-fix-attempt" 2>/dev/null || echo 0) + 1 ))" > ".spur/run/$wbs-test-fix-attempt"; [ -f ".spur/run/$wbs-verdict.json" ] && echo '--- verify verdict (remediation input, task 0703 R4) ---' >> ".spur/run/$wbs-test-gate.log" && cat ".spur/run/$wbs-verdict.json" >> ".spur/run/$wbs-test-gate.log"; [ -f ".spur/run/$wbs-residuals.json" ] && echo '--- residual artifact (F96 fix targets; deferrals go to residual-deferrals.json, P3/markers only) ---' >> ".spur/run/$wbs-test-gate.log" && cat ".spur/run/$wbs-residuals.json" >> ".spur/run/$wbs-test-gate.log"; exit 0
+          # Review-lane input (v5, task 1077 run): `review-fail-triage` routes a non-PASS review
+          # into this same bounded repair hop, but it stages no review evidence — the fixer then
+          # received a GREEN gate log and an empty findings list, so the review finding it exists
+          # to repair was invisible to it. Project the reviewer's answer into the same log the
+          # other lanes use, and only on the review lane (the decision file exists only after
+          # `review-fail-triage`). Own action, not an append to the one above: ADR-115's 800-char
+          # shell cap is already 602 chars there.
+          - kind: shell
+            options:
+                command: >-
+                    [ -f ".spur/run/$wbs-review-failure-class.decision" ] && [ -f ".spur/run/$__runId-review-answer.txt" ] && echo '--- review verdict (remediation input, review lane) ---' >> ".spur/run/$wbs-test-gate.log" && cat ".spur/run/$__runId-review-answer.txt" >> ".spur/run/$wbs-test-gate.log"; exit 0
           # R3 (0482): project the extracted gate anchors into a var so the dispatch input
           # can NAME the failing file:line, not merely point at a log. A vars template cannot
           # run a shell, so the read is an action, not an inline `$(cat ...)` substitution.
@@ -611,10 +657,43 @@ states:
           # verify stamp marks review `completed` only when this marker equals the current digest;
           # otherwise `skipped` (an honest downgrade, never a fake completed), and the bound
           # `record` registration refuses a skipped review.
+          # Session finding after 1088: the review VERDICT is read straight out of the reviewer's
+          # own answer file by the review → * guards below, so this stage needs no extra artifact
+          # and no extra action (ADR-115 legibility cap).
           - kind: shell
             options:
                 command: 'mkdir -p .spur/run; printf "%s" "$proofDigest" > ".spur/run/$__runId-review-proof.digest"; exit 0'
 
+    # ── review-fail-triage (session finding after 1088) ────────────────────────
+    # A review that reports FAIL used to have no outgoing edge: the graph could not see the
+    # verdict and nothing consumed it, so remediating a failing review meant driving the
+    # states by hand. This state is the review-side twin of `test-fail-triage` (0943 R3):
+    # the deterministic classifier routes the failure into the SAME bounded fix budget
+    # (`.spur/run/<wbs>-test-fix-attempt` against `qualityGateMaxFixAttempts`), and the fix
+    # re-enters quality → review → verify on a freshly captured digest. The `decide` action
+    # itself always runs (the engine has no onEnter conditionals); with
+    # `workflow.decideDecisionMaker` off it degrades to its declared default.
+    - id: review-fail-triage
+      description: >-
+          Deterministic router for a review that did NOT certify PASS (session finding after 1088).
+          `decide review-failure-class` reads the reviewer's answer and the task spec and routes:
+          fix → the shared test-fix hop, stop → failed with terminalReason failed-check. A
+          missing/corrupt decision fails closed to failed-check.
+      onEnter:
+          - kind: decide
+            options:
+                id: review-failure-class
+                method: choice
+                question: >-
+                    The review did not certify PASS (FAIL or PARTIAL). Is the finding fixable by the
+                    repair agent, or should the run stop here for the operator?
+                choices: [fix, stop]
+                default: fix
+                evidence:
+                    - .spur/run/${vars.__runId}-review-answer.txt
+                    - ${vars.taskSpecPath}
+                resultFile: .spur/run/${vars.wbs}-review-failure-class.decision
+
     - id: approve
       description: >
           Human-in-the-loop approval gate. Under `profile=auto` this state is never entered
@@ -675,8 +754,26 @@ states:
           # (d) `spur task verdict` owns the answer lint (task 1003 R2) — the shell below
           # fails closed when the verifier's answer is malformed, before any verdict artifact.
           - kind: shell
+            # `task verdict` exits 1 on a non-PASS verdict by design (1003 R2). The `continue`
+            # policy keeps that exit code as recorded evidence (the action row is still `failed`)
+            # while letting the state finish its remaining actions and reach the guards below;
+            # without it the default 'fail' policy halts the run here and `verify → test-fix`
+            # (the declared bounded remediation lane) can never fire (v5, task 1077 run).
+            onError: continue
             options:
                 command: "$spurBin task verdict $wbs --from-answer .spur/run/$wbs-verify-answer.txt"
+          # Session finding after 1088: the verifier's confidence level becomes a `confidence` check
+          # row (warn unless HIGH) and a gate-log line, so the level the completion guards enforce is
+          # visible in the artifact and the log — not only in the answer file. This is its own action
+          # because the proof-binding stamp below must stay the state's LAST action AND under the
+          # ADR-115 800-char shell cap.
+          - kind: shell
+            options:
+                command: >-
+                    V=".spur/run/$wbs-verdict.json"; [ -f "$V" ] || exit 0;
+                    jq --arg ack "$ackLowConfidence" '. + {checks: ((.checks // []) | map(select(.name != "confidence"))) + [{name: "confidence", status: (if (.confidence // "LOW") == "HIGH" then "pass" else "warn" end), evidence: ((.confidence // "LOW (absent from artifact)") + (if $ack == "true" then " (operator-acknowledged)" else "" end))}]}' "$V" > "$V.tmp" && mv "$V.tmp" "$V";
+                    printf 'confidence: %s (ack=%s)\n' "$(jq -r '.confidence // "LOW (absent)"' "$V")" "$ackLowConfidence" >> ".spur/run/$wbs-test-gate.log";
+                    exit 0
           # (e) one jq mutation binds the verdict to the proof digest (0703 R3; runId 0730 §B.2 /
           # 0757 R4; definitionDigest 0759 R5; honest review stamp 0785 R4; soft action + hard guard).
           - kind: shell
@@ -1018,21 +1115,73 @@ transitions:
       description: Failure-class decision missing/corrupt — stop at failed.
       guard:
           kind: always
-    # ── review → approve, OR skip the HITL gate entirely when profile=auto (R4) ──
-    # Declaration order matters: the auto-skip guard is tried FIRST, so under
-    # profile=auto the run routes straight to verify and never ENTERS approve
-    # (whose onEnter hitl.confirm would otherwise block). Otherwise fall through
-    # to approve for the human gate.
+    # ── review-failure routing (session finding after 1088): the review-side twin of the
+    # failure-class router above — stop first, then the shared attempt cap, then the fix lane,
+    # then the fail-closed defense. The counter is the SAME one the quality-gate loop uses, so a
+    # review FAIL cannot buy extra attempts and the iteration bound stays finite.
+    - from: review-fail-triage
+      to: failed
+      terminalReason: failed-check
+      description: Review failure class stop — the run terminates at failed, never bypassed.
+      guard:
+          kind: shell
+          options:
+              command: >-
+                  jq -e '.value == "stop"' ".spur/run/$wbs-review-failure-class.decision" >/dev/null 2>&1
+    - from: review-fail-triage
+      to: failed
+      terminalReason: retry-exhausted
+      description: Attempt cap reached — qualityGateMaxFixAttempts bounds the review repair lane.
+      guard:
+          kind: shell
+          options:
+              command: >-
+                  fix_attempts="$(cat .spur/run/$wbs-test-fix-attempt 2>/dev/null || echo 0)";
+                  test "$fix_attempts" -ge "$qualityGateMaxFixAttempts"
+    - from: review-fail-triage
+      to: test-fix
+      description: Review failure class fix and under the cap — the shared bounded repair hop.
+      guard:
+          kind: shell
+          options:
+              command: >-
+                  jq -e '.value == "fix"' ".spur/run/$wbs-review-failure-class.decision" >/dev/null 2>&1
+    # Defense: missing/corrupt review-failure decision — fail closed instead of silently repairing.
+    - from: review-fail-triage
+      to: failed
+      terminalReason: failed-check
+      description: Review-failure decision missing/corrupt — stop at failed.
+      guard:
+          kind: always
+    # ── review routing: FAIL → bounded remediation; PASS → approve or the auto-skip (R4) ──
+    # Declaration order matters and is FAIL-CLOSED: the two PASS edges each demand the reviewer's
+    # own `Verdict: PASS` line, and the catch-all sends EVERYTHING ELSE (FAIL, a missing answer, an
+    # unparseable one) into `review-fail-triage`. Before this, a FAIL review had no outgoing edge at
+    # all — the graph could not see the verdict, so remediation meant driving states by hand
+    # (session finding after 1088). The reviewer writes `Verdict: PASS|FAIL` in its answer; both
+    # plain and bold forms are accepted. Under `profile=auto` the approve gate is skipped, so the
+    # PASS+auto edge is tried first and the interactive PASS edge second.
     - from: review
       to: verify
-      description: profile=auto — skip the human approval gate, go straight to verify.
+      description: profile=auto and the review certified PASS — skip the human approval gate.
       guard:
           kind: shell
           options:
-              command: 'test "$profile" = auto'
+              command: >-
+                  test "$profile" = auto &&
+                  grep -qiE '^[[:space:]]*\**Verdict:\** *PASS' ".spur/run/$__runId-review-answer.txt"
     - from: review
       to: approve
-      description: Review done — gate on human approval.
+      description: Review certified PASS — gate on human approval before verification.
+      guard:
+          kind: shell
+          options:
+              command: grep -qiE '^[[:space:]]*\**Verdict:\** *PASS' ".spur/run/$__runId-review-answer.txt"
+    - from: review
+      to: review-fail-triage
+      description: >-
+          No PASS in the reviewer's answer (FAIL, PARTIAL, missing, or unparseable — fail closed) —
+          classify the failure and route it into the bounded repair hop instead of dead-ending the run.
       guard:
           kind: always
 
@@ -1069,19 +1218,23 @@ transitions:
     # The verify step emits .spur/run/<wbs>-verdict.json with a required proof block (task 0703 R3/R5).
     # Only `verdict: PASS` PLUS a proof block whose digest — top level and every named stage — equals
     # the captured `proofDigest` clears the gate to `record`; any non-PASS, a missing file, malformed
-    # JSON, or missing/mismatched proof evidence does not. Declaration order: PASS+proof guard FIRST,
+    # JSON, or missing/mismatched proof evidence does not. The verifier's confidence level is part of
+    # that certification (session finding after 1088): a PASS the verifier itself marked LOW — or left
+    # unstated — clears the gate only when the operator accepted it with
+    # `--vars '{"ackLowConfidence":"true"}'`. Declaration order: PASS+proof guard FIRST,
     # then the bounded remediation route (R4), then the always catch-all so a PASS verdict with a
     # missing/malformed proof block still terminates at `failed` instead of hanging the state.
     - from: verify
       to: record
-      description: Verification verdict is PASS and its proof block names the captured digest on every stage — record results and proceed to done.
+      description: Verification verdict is PASS, its proof block names the captured digest on every stage, and any LOW confidence was operator-acknowledged — record results and proceed to done.
       guard:
           # (one jq -e predicate) PASS verdict; proof, quality-gate, review and verification digests
-          # equal to proofDigest; review completed; matching run id and definition digest (0703 R5, 0785 R4).
+          # equal to proofDigest; review completed; matching run id and definition digest (0703 R5, 0785 R4);
+          # confidence HIGH/MEDIUM, or LOW/absent with the operator's ack (session finding after 1088).
           kind: shell
           options:
               command: >-
-                  jq -e --arg d "$proofDigest" --arg r "$__runId" --arg dd "$__definitionDigest" '
+                  jq -e --arg d "$proofDigest" --arg r "$__runId" --arg dd "$__definitionDigest" --arg ack "$ackLowConfidence" '
                   .verdict == "PASS"
                   and (.proof.digest // "") == $d
                   and (.proof.stages.qualityGate.digest // "") == $d
@@ -1090,6 +1243,7 @@ transitions:
                   and (.proof.stages.verification.digest // "") == $d
                   and (.proof.runId // "") == $r
                   and (.proof.definitionDigest // "") == $dd
+                  and ((.confidence // "LOW") != "LOW" or $ack == "true")
                   ' ".spur/run/$wbs-verdict.json" >/dev/null 2>&1
     - from: verify
       to: test-fix
@@ -1117,11 +1271,12 @@ transitions:
     # ── done gate: record → done/failed gated on `spur task check` (ADR-026 amendment 2026-06-23)
     # PLUS the proof-block re-assertion (task 0703 R5): the verdict artifact must still be PASS and
     # still name the captured digest — a forged or mutated completion artifact fails closed here.
+    # PLUS the confidence re-assertion (session finding after 1088): the same ack rule as verify →
+    # record, re-read from the artifact so a mutation between the two boundaries cannot slip through.
     # Declaration order: pass guard first.
     - 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).
+      description: Task check passed, the verdict proof block still names the captured digest, and any LOW confidence was acknowledged — certify done.
       guard:
           kind: shell
           options:
@@ -1130,11 +1285,16 @@ transitions:
               # the CLI's own target-aware `--no-lifecycle` backstop (F92 R3). No `#`
               # comments inside the folded scalar: `>-` joins same-indent lines into
               # one shell line.
+              # Two logical commands, deliberately (ADR-115): the `task check` projection plus
+              # ONE jq predicate re-asserting the whole completion contract — PASS verdict, the
+              # captured proof digest, and the confidence rule (session finding after 1088).
               command: >-
                   $spurBin task check $wbs --as done &&
-                  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"
+                  jq -e --arg p "$proofDigest" --arg ack "$ackLowConfidence" '
+                  .verdict == "PASS"
+                  and ((.proof.digest // "") == $p)
+                  and ((.confidence // "LOW") != "LOW" or $ack == "true")
+                  ' ".spur/run/$wbs-verdict.json" >/dev/null 2>&1
     - from: record
       to: failed
       terminalReason: failed-check

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.3.99",
+    "version": "0.4.0",
     "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",
@@ -57,14 +57,14 @@
     },
     "devDependencies": {
         "@commander-js/extra-typings": "^14.0.0",
-        "@gobing-ai/ts-db": "^0.5.12",
-        "@gobing-ai/ts-ai-runner": "^0.5.12",
-        "@gobing-ai/ts-dual-workflow-engine": "^0.5.12",
-        "@gobing-ai/ts-infra": "^0.5.12",
-        "@gobing-ai/ts-llm-jsonl-importer": "^0.5.12",
-        "@gobing-ai/ts-rule-engine": "^0.5.12",
-        "@gobing-ai/ts-runtime": "^0.5.12",
-        "@gobing-ai/ts-utils": "^0.5.12",
+        "@gobing-ai/ts-db": "^0.5.16",
+        "@gobing-ai/ts-ai-runner": "^0.5.16",
+        "@gobing-ai/ts-dual-workflow-engine": "^0.5.16",
+        "@gobing-ai/ts-infra": "^0.5.16",
+        "@gobing-ai/ts-llm-jsonl-importer": "^0.5.16",
+        "@gobing-ai/ts-rule-engine": "^0.5.16",
+        "@gobing-ai/ts-runtime": "^0.5.16",
+        "@gobing-ai/ts-utils": "^0.5.16",
         "@types/bun": "1.3.14",
         "@types/figlet": "^1.7.0",
         "@types/node-notifier": "8.0.5",

package/plugins/sp/README.md

@@ -273,6 +273,7 @@ plugins/sp/
 ├── commands/                        # Slash-command wrappers — the SSOT (hand-editable thin wrappers; see Commands below)
 ├── agents/                          # 4 specialist subagents (expert-spur, super-coder, super-planner, super-reviewer)
 ├── hooks/                           # hooks.json + task-write-guard.{ts,test.ts} + context-{session-start,post-tool,session-stop}.ts
+│                                    # + agent-lifecycle.{ts,test.ts} + fleet-guest-stop.{ts,test.ts} (fleet member/guest hooks)
 │                                    # + careful-guard.{ts,test.ts} + context-hooks.test.ts + token-estimate.test.ts
 │                                    # + shared policy modules: agent-hint.ts, destructive-policy.{ts,test.ts}, task-file-policy.{ts,test.ts}
 │                                    # + pi/guard-extension.{ts,test.ts} (plugin.json `extensions.pi` entry point)
@@ -342,6 +343,7 @@ surface or run one workflow. All skills target the same five core platforms: `cl
 | `reverse-engineering`       | 1.1   | Codebase analysis / HLD generation / audit — depth-driven reverse engineering with orthogonal mode, focus, and format controls; backs `/sp:dev-reverse`                                                                                    |
 | `issue-finding`             | 2.0   | Session-log forensics — multi-source discovery, bottleneck ranking, optional topic focus, CLI-gated fix task generation; **legacy path** — superseded by `history-anatomy` for indexed reporting; backs no current command; directly invocable as sp:issue-finding |
 | `conflict-finding`          | 1.0   | Authority-aware semantic audit — four-pillar (source/task/feature/authority) conflict discovery, claim-specific authority resolution, reproducible evidence, confirmed owner-routed remediation; backs `/sp:dev-find-conflict`             |
+| `fleet-join`                | 1.0   | Guest fleet occupancy — join as a live guest occupant, loop `spur agent wait --inbox` to pull work, reply through `spur message reply`, then leave; G73 (task 1081)                                                                          |
 | `next-feature`              | 1.0   | Prompt-first feature frontier prioritizer — sync-first precondition, B3 actionability gate (cited, never restated), tiered rubric over measured signals, D1–D4 defect proposals conforming to the restructure map schema; backs `/sp:dev-find-next` |
 | `pr-reviewing`              | 1.0   | GitHub Codex PR review — PR prepare/reuse, `@codex review` request with per-HEAD dedupe, bounded polling, findings normalization, validated fix + re-review; spine SSOT `pr-review.yaml` + `scripts/pr-reviewing.ts`; backs `/sp:dev-pr-review`     |
 | `indexed-context`           | 1.0   | Cross-agent project context — anatomy/learnings/pitfalls/buglog/memory in `.spur/context/`; hook-tracked token-ledger; graceful degradation on agents without hooks                                                                        |
@@ -473,13 +475,16 @@ the agent provides an isolated context window.
 #### 4. Hooks (`hooks/`)
 
 Event-driven enforcement that runs automatically without user invocation. `hooks.json` registers
-four handlers:
+six handlers across seven events:
 
 | Event          | Matcher                               | Handler                                        | Timeout |
 | -------------- | ------------------------------------- | ---------------------------------------------- | ------- |
 | `PreToolUse`   | `Write\|Edit`                         | `superskill hook run sp task-write-guard`      | 10s     |
 | `PostToolUse`  | `Bash\|Grep\|Glob\|Read\|Write\|Edit` | `superskill hook run sp context-post-tool`     | 10s     |
 | `SessionStart` | —                                     | `superskill hook run sp context-session-start` | 15s     |
+| `SessionStart`, `UserPromptSubmit`, `Stop` | —         | `superskill hook run sp agent-lifecycle`       | 5s      |
+| `Notification` | `permission_prompt`                   | `superskill hook run sp agent-lifecycle`       | 5s      |
+| `Stop`         | —                                     | `superskill hook run sp fleet-guest-stop`      | 10s     |
 | `SessionEnd`   | —                                     | `superskill hook run sp context-session-stop`  | 15s     |
 
 **Write guard.** The `PreToolUse` hook fires on every `Write`/`Edit` tool call and checks whether
@@ -493,6 +498,11 @@ estimates the token cost of each matched tool call and appends it to `.spur/cont
 (with redaction of sensitive argument fields), `context-session-start` seeds the indexed-context
 hint on first launch, and `context-session-stop` closes out the session record.
 
+**Fleet hooks (1080/1081).** `agent-lifecycle` reports member state in the background via
+`spur agent report --state working|idle|blocked` (a permission prompt is `blocked`) — only when
+`SPUR_SPEC_ID` is set, so outside a fleet it makes no call. `fleet-guest-stop` delivers pending
+inbox work to a session joined as a fleet guest at turn end; any other session passes through.
+
 **Available but unwired:** `careful-guard.ts` ships in `hooks/` (with tests) as an opt-in
 `PreToolUse` guard that asks before destructive shell commands (`rm -rf`, `DROP TABLE`,
 `git push --force`, …) — it is **not** registered in `hooks.json`. Fail-open by contract; escape
@@ -511,6 +521,7 @@ hold `SKILL.md` and prompt-side companions only.
 | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `hooks/task-write-guard.ts`                          | Compatibility shim for older installs that still execute the script path directly. Forwards stdin to the stable PATH command `superskill hook run sp task-write-guard`, mirrors parseable PreToolUse decisions, and fails open if the runtime is unavailable. Performs no source-tree CLI lookup. |
 | `hooks/context-*.ts`                                 | Runtime for the three registered context hooks (session-start, post-tool, session-stop) — token-cost estimation + ledger append for `sp:indexed-context`                                                                                                                                          |
+| `hooks/{agent-lifecycle,fleet-guest-stop}.ts`       | Fleet hooks (1080/1081): member lifecycle reports via `spur agent report`; turn-end inbox delivery to joined guests |
 | `hooks/careful-guard.ts`                             | Opt-in destructive-command guard (unwired — see Hooks above)                                                                                                                                                                                                                                      |
 | `scripts/batch-preflight.ts`                         | Pure TABLE A STOP evaluation for `super-planner` — skip doomed pipeline launches without spawning a Skill subprocess; recovery hints map stuck statuses to a single `/sp:dev-*` hop                                                                                                               |
 | `scripts/workflow-step-profile.ts`                   | Thin glue over the generated lib bundle (`lib/step-profile.generated.mjs` from `packages/app/src/workflow/step-profile.ts`) — read-only step profile from `spur workflow trace`: per node and action-kind durations, idle gaps, session mode and `cacheHit` coverage, plus the ADR-115 cache-window flags `sp:spur-doctor` turns into workflow-optimization proposals |
@@ -518,6 +529,8 @@ hold `SKILL.md` and prompt-side companions only.
 | `scripts/dogfood-testing/validate-report.ts`         | Pure `validateReport(md)` — footer-mandatory + 7-check finalize-or-abort contract with stable error codes                                                                                                                                                                                         |
 | `scripts/daily-summary/{daily-summary,logger}.ts`    | ccusage + git-history orchestration helpers for `sp:daily-summary`                                                                                                                                                                                                                                |
 | `scripts/task-diffstat.ts`                           | 0943 triage-lane diffstat producer — numstat + untracked scan vs the run base; writes `<wbs>-diffstat.json` with the sensitive-path flag; fails safe (sensitive)                                                       |
+| `scripts/run-summary.ts`                             | Measured execution summary `/sp:dev-run` / `/sp:dev-runall` print by default (`--no-summary` skips) — windows the host transcript by `spur workflow progress` attempt timestamps; per stage/run time, wait, tool calls, total / non-cached tokens; `n/a` for subprocess windows |
+| `scripts/session-timeline.ts`                        | Measured Time/Wait/Token evidence for `sp:session-review` — reads the active Claude Code transcript read-only, one segment per operator prompt, usage deduplicated by message id, tokens split total / non-cached; `{available:false}` exit 0 when no transcript |
 | `scripts/commands/validate-flag-contracts.ts`        | Mechanical consistency gate — compares flag claims across command files, flag-glossary, cross-cutting, dev-operations, and ADR; reports disagreements                                                                                    |
 | `*.test.ts`                                          | Unit suites — in `hooks/` for guards, in `tests/<skill>/` per ADR-031 pairing                                                                                                                                                                                                                     |