@gobing-ai/spur 0.3.85 → 0.3.86

package/plugins/sp/scripts/wrapup-steps.mjs

@@ -5,6 +5,13 @@
 import { spawnSync } from "child_process";
 import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { join } from "path";
+
+// ../ts-libs/packages/utils/dist/env.js
+function getEnvVars() {
+  return process.env;
+}
+
+// plugins/sp/scripts/wrapup-steps.ts
 function jqPick(...values) {
   for (const value of values) {
     if (value !== null && value !== undefined && value !== false)
@@ -319,7 +326,7 @@ function runFeatureTransition(env, options = {}) {
   return { status: syncStatus, statusFile: relStatusFile, exitCode: 0 };
 }
 var WRAPUP_STEPS_USAGE = "usage: wrapup-steps.ts <resolve|metrics|feature-transition>  (env: __runId, tasks, feature, featureGateCmd, spurBin)";
-function main(argv, env = process.env, options = {}) {
+function main(argv, env = getEnvVars(), options = {}) {
   const sub = argv[0];
   if (sub === "resolve")
     return resolveTasks(env, options).exitCode;

package/plugins/sp/scripts/wrapup-steps.ts

@@ -31,6 +31,7 @@
 import { spawnSync } from 'node:child_process';
 import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { getEnvVars } from '@gobing-ai/ts-utils';
 
 export interface WrapupStepsEnv {
     __runId?: string;
@@ -449,7 +450,7 @@ export function runFeatureTransition(env: WrapupStepsEnv, options: WrapupStepsOp
 export const WRAPUP_STEPS_USAGE =
     'usage: wrapup-steps.ts <resolve|metrics|feature-transition>  (env: __runId, tasks, feature, featureGateCmd, spurBin)';
 
-export function main(argv: string[], env: WrapupStepsEnv = process.env, options: WrapupStepsOptions = {}): number {
+export function main(argv: string[], env: WrapupStepsEnv = getEnvVars(), options: WrapupStepsOptions = {}): number {
     const sub = argv[0];
     if (sub === 'resolve') return resolveTasks(env, options).exitCode;
     if (sub === 'metrics') {

package/plugins/sp/skills/spur-cli/references/workflows.md

@@ -62,7 +62,7 @@ ordered guards, and may loop back on itself (e.g. implement → check → fix
 | Node typing | none (states are untyped) | `type: action\|gate\|parallel\|decision` |
 | Required keys | `name, initialState, states, transitions` | `kind, name, initialNode, nodes, edges` |
 | `kind` field | optional (defaults to state-machine) | **required** — `kind: transition-flow` |
-| Canonical example | implement→check→fix loop (`basic.yaml` — soft status-file probe + bounded fixall) | read→validate→transform→write pipeline |
+| Canonical example | implement→check→fix loop (`task-pipeline.yaml` — quality-gate hop with bounded fixall) | read→validate→transform→write pipeline |
 
 **Heuristic:** loops / retries / one-active-state → **state-machine**; pipeline / fan-out / action-per-node → **transition-flow**.
 
@@ -95,7 +95,7 @@ Use this skill to:
 
 The skill's logic divides by **whether the LLM adds value**:
 
-- **Direct CLI** (`validate`, `run`, `list`, `trace`, `continue`, `cancel`, `clean`) — deterministic,
+- **Direct CLI** (`validate`, `run`, `list`, `trace`, `progress`, `continue`, `cancel`, `clean`) — deterministic,
   single-verb commands. Run them straight. A slash-command wrapper would only forward flags and add
   drift; **there is no command for these — use the CLI**. The skill still drives them in natural
   language (interpreting a failed validate, reading a run trace).
@@ -113,6 +113,7 @@ The skill's logic divides by **whether the LLM adds value**:
 | `clean` | `spur workflow clean` (CLI) | `[--older-than <min>] [--force] [--logs] [--dry-run]` | Bulk-finalize stale `running`/`pending` runs as failed **and** reclaim retained run logs older than `workflow.logRetentionDays` (30d default) |
 | `list` | `spur workflow list` (CLI) | — | Available workflow **YAML definition files** (not run records) |
 | `trace` | `spur workflow trace` (CLI) | `[run-id] [--workflow <n>] [--status <s>] [--since <iso>] [--last <n>] [--follow] [--poll <ms>] [--output]` | Run history list or per-run timeline |
+| `progress` | `spur workflow progress` (CLI) | `<run-id>` | The `projectWorkflowProgress` projection for that run — current state, per-action attempts, candidate next transitions, diagnostics. Read-only; the verb renders, `packages/app` derives. Unknown run id exits 1 with `Run <id> not found.` |
 | `add` | agent procedure | `"<nl-description>" [--kind <state-machine\|transition-flow>] [--file <path>]` | **Mode chosen (confirmed)** → first reconciled against existing workflows (extend an existing flow rather than duplicate) → YAML authored in real schema shape → **validated AND dry-run** (reaches the expected terminal state) → [add](workflows/operations.md#add) |
 | `refine` | agent procedure | `<workflow-file> [--intent "<goal>"] [--dry-run]` | Smallest change meeting the intent, re-validated and re-dry-run; `--dry-run` emits a diff only → [refine](workflows/operations.md#refine) |
 
@@ -262,6 +263,7 @@ spur workflow cancel   <run-id> [--json]
 spur workflow clean    [--older-than <minutes>] [--force] [--logs] [--dry-run] [--json]
 spur workflow list     [--json]
 spur workflow trace    [run-id] [--workflow <name>] [--status <s>] [--since <iso>] [--last <n>] [--follow] [--poll <ms>] [--output] [--json]
+spur workflow progress <run-id> [--json]
 ```
 
 ### `show` - project a definition
@@ -359,7 +361,7 @@ the workflow's actions (`shell`, custom runners) do that; this skill builds and
    (transition-flow) wins. Order the specific case before the fallback. Simple shell checks can use
    `action-ok` before an unconditional retry edge; multi-condition gates prefer a **soft status-file
    probe** (always exit 0) with ordered shell guards for PASS / FAIL / exhausted (see
-   `basic.yaml` and `task-pipeline.yaml` quality-gate hop).
+   `task-pipeline.yaml`'s quality-gate hop).
 4. **`env.allow` is an allowlist.** `${env.X}` resolves only if `X` is listed under `env.allow`;
    otherwise it resolves empty. A workflow that "loses" an environment value usually forgot to allow it.
 5. **Extensions are fail-closed.** The CLI loads YAML-declared extension modules itself
@@ -400,10 +402,9 @@ the workflow's actions (`shell`, custom runners) do that; this skill builds and
   custom action/guard runners, the trust-gated extension loader, and CLI-vs-library capability gaps.
 - `@gobing-ai/ts-dual-workflow-engine` README — authoritative library reference (both drivers,
   RunLifecycle, persistence, the full event map, every built-in capability).
-- `basic.yaml` — the canonical state-machine implement→soft-check→fixall loop
-  (status-file branching + `qualityGateMaxFixAttempts`); copy real shapes from here.
-- `task-pipeline.yaml` — full production pipeline (precheck, quality gate, HITL,
-  verify, record) when you need the complete reliability pattern set.
+- `task-pipeline.yaml` — the canonical state-machine implement→soft-check→fixall loop and
+  full production pipeline (status-file branching, `qualityGateMaxFixAttempts`, quality gate,
+  HITL, verify, record); copy real shapes from here.
 
 ## Platform Notes
 

package/plugins/sp/skills/spur-dev/references/cross-cutting.md

@@ -573,8 +573,6 @@ invariants that keep the pipeline set coherent as new ones are added.
 | `idea-pipeline.yaml` | Ideation + planning (vague idea or known slug → feature + AC + task batch) | `/sp:dev-idea`, `/sp:dev-plan` | `handoff`, `cancelled` |
 | `task-pipeline.yaml` | Execution (one task → done) | `/sp:dev-run` | `done`, `failed` |
 | `wrapup-pipeline.yaml` | Wrap-up (completed tasks → learning + metrics + doc-sync) | `/sp:dev-wrap`, `/sp:dev-wrapall` | `done`, `skipped` |
-| `feature-dev.yaml` | Umbrella (brainstorm → plan → execute → feature-verify) | `/sp:dev-runall --feature <id>` (or `--tasks feature:<id>`) | `done`, `failed` |
-| `basic.yaml` | Simple (generic implement/check/fix loop) | direct `spur workflow run` | `done`, `failed` |
 | `feature-lifecycle.yaml` | Feature status FSM (entity lifecycle, not a phase pipeline) | `spur feature update` | `done`, `cancelled` |
 | `task-lifecycle.yaml` | Task status FSM (entity lifecycle, not a phase pipeline) | `spur task update` | `done`, `cancelled` |
 
@@ -587,8 +585,9 @@ not replace them.
 A pipeline may invoke another workflow through a command wrapper or `spur workflow run` **only at a
 phase boundary** — it must NOT inline another pipeline's state graph. Concretely:
 
-- `feature-dev.yaml`'s `execute-tasks` state may invoke `task-pipeline.yaml` per task via
-  `spur workflow run` (phase boundary: design → execution).
+- The feature-level batch entry (`/sp:dev-runall --feature <id>`) dispatches `task-pipeline.yaml`
+  per task through the CLI command wrapper, not by inlining the task graph (feature roster →
+  execution boundary).
 - `idea-pipeline.yaml`'s `handoff` state may output a command for the operator to run
   `task-pipeline.yaml` (phase boundary: ideation → execution).
 - `task-pipeline.yaml`'s `implement` state must NOT contain a nested state machine for
@@ -692,7 +691,7 @@ Field semantics (enforced by `parseCheckpointMetadata` / `checkpointStaleness`):
 **Writer cadence (0784 R4).** There is exactly one canonical writer: the `task-pipeline` done
 state's terminal checkpoint (`status: done`, real HEAD, run id from `$__runId`, and `$wbs`-expanded
 artifact paths). It is a plain `shell` step — checkpoints are working memory, not CLI-gated corpus.
-The `feature-dev`, `wrapup-pipeline`, and `idea-pipeline` pipelines used to echo pseudo-checkpoints
+The `wrapup-pipeline`, and `idea-pipeline` pipelines (plus the since-retired `feature-dev`) used to echo pseudo-checkpoints
 ("checkpoint: <workflow> done ...") that violated the canonical schema; those writers were removed
 in 0784 — the persisted run row is the authoritative terminal record, and a non-canonical echo
 cannot be resumed, routed, or reclaimed safely.

package/plugins/sp/skills/spur-dev/references/done-housekeeping.md

@@ -105,7 +105,7 @@ gate will reject the task without it). Use the normal `--section --from-file` co
 **4. Force-done with an honest reason.**
 
 ```bash
-SPUR_PROVENANCE_OVERRIDE=1 spur task update <wbs> done --force-done \
+spur task update <wbs> done --force-done --provenance-bypass \
   --reason "<step> agent.run timed out at <N>s; recovered manually: lint clean, <suite> pass, sections authored by hand"
 ```
 

package/plugins/sp/skills/spur-dev/references/gate-checklists.md

@@ -149,11 +149,11 @@ passed, so provenance denied first and Review L3 denied on the retry.
 
 | # | Gate layer | Triggers denial when | Remediation |
 |---|------------|----------------------|-------------|
-| 1 | **Strict-core + verdict artifact** (`spur task check <wbs> --strict-core` + `done-transition-guard.ts`) | The strict-core check fails, or `.spur/run/<wbs>-verdict.json` is **missing** or has a non-PASS aggregate. **Missing artifact is a deny** (not a silent allow — closes the 0349 "done without verdict" class). The aggregate is recomputed from requirement/AC rows; the harsher of stored and computed wins. | Re-run `/sp:dev-verify <wbs>` until PASS (writes the artifact), or explicitly override with `spur task update <wbs> done --force-done --reason "<why>"`. Docs-only pipelines (`docs-pipeline.yaml`) meet the same layer: read-only measured verification
+| 1 | **Strict-core + verdict artifact** (`spur task check <wbs> --strict-core` + `done-transition-guard.ts`) | The strict-core check fails, or `.spur/run/<wbs>-verdict.json` is **missing** or has a non-PASS aggregate. **Missing artifact is a deny** (not a silent allow — closes the 0349 "done without verdict" class). The aggregate is recomputed from requirement/AC rows; the harsher of stored and computed wins. | Re-run `/sp:dev-verify <wbs>` until PASS (writes the artifact), or explicitly override with `spur task update <wbs> done --force-done --reason "<why>"`. Docs-only procedures meet the same layer: read-only measured verification
 (answer file + `spur task verdict`) writes the standard `.spur/run/<wbs>-verdict.json` artifact
 under proof-input digest bracketing; missing or non-PASS evidence is a refusal, never a synthetic
 PASS stub. |
-| 2 | **Provenance guard** (`lifecycle-adapter.ts`) | No pipeline-kind run link exists for `<wbs>`. | Run `/sp:dev-run <wbs>` through the full pipeline, use `/sp:dev-run <wbs> --mode implement --auto --next` for the explicit step chain, or record the audited bypass with `SPUR_PROVENANCE_OVERRIDE=1`. |
+| 2 | **Provenance guard** (`lifecycle-adapter.ts`) | No pipeline-kind run link exists for `<wbs>`. | Run `/sp:dev-run <wbs>` through the full pipeline, use `/sp:dev-run <wbs> --mode implement --auto --next` for the explicit step chain, or record the audited bypass with `--provenance-bypass` on `spur task update`. |
 | 3 | **Review L3** (`task-check.ts`) | `### Review` is empty, placeholder-only, or lacks a populated P1–P4 findings table. | Run `/sp:dev-review <wbs>`; verify cannot write Review because of the Step 10 prohibition above. |
 
 When the verdict is **PARTIAL/FAIL**, or any gate layer fails: stop as review-pending — surface

package/plugins/sp/skills/spur-dev/references/inline-pipeline-driver.md

@@ -25,7 +25,11 @@ implements it; remove the entry when the corresponding kind is dropped from the
 
 **Actions:** `shell` · `note` · `doctor.probe` · `file.read.into-var` · `hitl.confirm` · `agent.run` · `proof.fingerprint` · `run.artifact` · `command.gate`
 
-**Guards (transitions):** `always` · `shell`
+**Guards (transitions):** `always` · `shell` · `action-ok` · `contract-violation`
+
+- `action-ok` — pass iff the prior action on this state/node succeeded (engine builtin).
+- `contract-violation` — pass iff the prior `agent.run` result is a named contract violation
+  (`data.outcome === 'contract-violation'`, ADR-118); the report carries `contract` and `observed`.
 
 ## What this driver is
 
@@ -398,6 +402,60 @@ keep their exact content after the stamp prefix. This normalization is contractu
 **bare local-clock stamps are prohibited** — a hand-appended `[stage 12:31]` form mixes timezones
 in one file and makes the run unauditable (task 0726 mixed both forms).
 
+## Structured trace emission (ADR-117, task 0868)
+
+`.spur/run/<run-id>.log` is a human convenience, **not the record of truth**. A run's
+observability is a property of the run, so the inline driver owes the same structured trace the
+engine subprocess writes — and it owes it through the **same writer**, never a parallel
+implementation. The shared writer is `WorkflowActionTraceWriter`
+(`packages/app/src/workflow/action-trace.ts`): the same decorator the engine composition installs
+around `DbWorkflowPersistenceAdapter`, so the two surfaces call one emission path and one run-row
+closure path and cannot drift.
+
+The driver reaches it through the existing run delegate (`$SETUP_SCRIPT`,
+`plugins/sp/scripts/inline-run-setup.ts`) — no new entry point, no second resolution chain:
+
+- **Every executed action** — after the action settles, whether it ran host-inline or via a native
+  subagent — append its provenance line as before, then record the boundary:
+
+  ```bash
+  bun "$SETUP_SCRIPT" --action --run-id "$RUN_ID" --node <state-id> --kind <action-kind> \
+    --status <done|failed> --ok <true|false> --duration-ms <measured-ms>
+  ```
+
+  `<state-id>` is the current YAML state id (the `node`), `<action-kind>` the YAML action kind
+  (`agent.run`, `shell`, `note`, `doctor.probe`, …). `--status` is `done` when the action settled
+  under its declared error policy and `failed` otherwise; `--duration-ms` is the wall clock the
+  driver measured around the action. This writes the `action_runs` row (node, kind, status, `ok`,
+  `duration_ms`, `run_id`) the engine would have written, so the run's rows are queryable by run id
+  (`spur workflow progress <run-id>`, `ActionRunDao`) without reading the text log.
+
+- **At the run's declared terminal state** — before the driver reports the run complete, close the
+  row so a successful inline run is never left non-terminal for `spur workflow clean` to reap as
+  stale:
+
+  ```bash
+  bun "$SETUP_SCRIPT" --close --run-id "$RUN_ID" --status <done|failed|paused>
+  ```
+
+  `--status` is the declared terminal state's verdict, not a guess: a run that reached a terminal
+  state is `done`; a run halted by a failing action under its error policy is `failed`.
+
+**Best-effort at the action boundary only (ADR-117).** An `--action` persistence failure is
+recorded — the delegate appends a `trace-emission-failed` line to `.spur/run/<run-id>.log` and
+prints `{"ok":false}` on stdout — and the run continues to its declared terminal state; the
+delegate exits `0` for that outcome and the driver must never treat an emission failure as a run
+failure, retry it in a loop, or substitute a hand-written row. The run-row closure (`--close`) is
+bookkeeping, not trace emission, and is **not** best-effort: a missing run row or a persistence
+failure exits `1` with `{"ok":false}` and a named error (a missing row also carries
+`code:"RUN_NOT_FOUND"`), because a silently `running` row is exactly the stale state
+`spur workflow clean` reaps as `failed`. Exit `2` means the invocation itself was malformed
+(missing `--node`/`--kind`/`--status`/`--ok`, a miscased `--ok`, a missing or malformed
+`--duration-ms`, or an unsafe run id) and must be corrected, not ignored.
+
+Emission is not optional and not deferred: an inline run that skips it reintroduces the
+1,011-untraced-runs gap ADR-117 exists to close.
+
 Transition guards are not advisory. Execute the declared guard exactly, in order, with the same
 resolved variables and artifacts. `--no-lifecycle` remains bookkeeping only; the YAML's task checks,
 verdict gate, record step, and done guard all remain authoritative.

package/schemas/state-machine-workflow.schema.json

@@ -161,6 +161,11 @@
                 "options": {
                     "type": "object",
                     "additionalProperties": true
+                },
+                "onError": {
+                    "type": "string",
+                    "enum": ["fail", "continue"],
+                    "description": "Per-action error handling policy: 'fail' halts the run; 'continue' logs the failure and proceeds so transition guards can route the outcome."
                 }
             }
         },

package/schemas/transition-flow-workflow.schema.json

@@ -140,6 +140,11 @@
                 "options": {
                     "type": "object",
                     "additionalProperties": true
+                },
+                "onError": {
+                    "type": "string",
+                    "enum": ["fail", "continue"],
+                    "description": "Per-action error handling policy: 'fail' halts the run; 'continue' logs the failure and proceeds so edge conditions can route the outcome."
                 }
             }
         },