@gobing-ai/spur 0.4.0 → 0.4.1

package/plugins/sp/skills/spur-dev/references/structured-trace-emission.md

@@ -0,0 +1,178 @@
+---
+name: structured-trace-emission
+description: "Structured trace emission (task 1128 split, ADR-117 / task 0868): the action vocabulary, the per-step emit shape, the close contract and the parse rules the host driver follows. Read it when the first trace event is emitted."
+see_also:
+  - inline-pipeline-driver
+---
+
+## Structured trace emission (ADR-117, task 0868)
+
+`.spur/memory/runs/<run-id>.md` is the human half of the two-file run record — evidence, **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>] [--estimated] \
+    --project-root "$OWNING_TREE"
+  ```
+
+  `<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. 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. The writer
+  back-dates the row's `started_at` from its own `completed_at` minus the measured duration
+  (0887 R8), so `completed_at − started_at == duration_ms` exactly; a back-date failure is
+  recorded (`action.backdate`) and never affects the run.
+
+  **`--project-root` names the tree that owns the run row (task 1136 R1/R2).** Per-tree DBs are
+deliberate, so when the driver runs inside a `--worktree` (or any other execution tree) the run row
+lives in the **invoking** tree's `.spur/spur.db` while the action commands run in the execution
+tree. `--project-root` is the invoking tree recorded by the WT-3 marker; without it the row is read
+from the cwd tree. A run-row miss is a **correctness failure**, not a best-effort emission failure:
+`--action`, `--actions-file` and `--node-enter` exit `1` with
+`{"ok":false,"code":"RUN_NOT_FOUND"}`, exactly like `--close`. **Never redirect these calls'
+stdout/stderr to `/dev/null`** — the suppressed-RUN_NOT_FOUND run of task 1132 lost 93 action rows
+to exactly that redirect. Capture the output or let it stream; a failure must be visible.
+
+  **Durations: measured beats reported (task 1136 R4).** Stamp the enter time before the action runs:
+
+  ```bash
+  bun "$SETUP_SCRIPT" --node-enter --run-id "$RUN_ID" --node <state-id> --project-root "$OWNING_TREE"
+  ```
+
+  Then call `--action` **without** `--duration-ms` — the delegate computes
+  `duration = now − enter` and stamps `provenance: measured` into `action_runs.result_json`. A
+  caller-supplied `--duration-ms` stays valid but is recorded `provenance: host-reported` (with
+  `--estimated` marking a value reconstructed after the fact); every other inline row is
+  `host-reported` too, and the projection exposes `provenance` per attempt so the Board can label a
+  reported duration instead of presenting it as measured. A row whose computed start would precede
+  `runs.started_at` is **rejected** (exit `1`) — a timestamp before the run began is a broken clock,
+  not evidence. Calling `--action` without `--duration-ms` and without a matching `--node-enter`
+  exits `1` with `code:"ACTION_DURATION_UNAVAILABLE"`; it never silently drops the row.
+
+- **A state with several actions (1007 R5)** — emit the whole state's boundaries in one call
+  instead of one `--action` invocation per action. Write a JSON array
+  (`[{node,kind,status,ok,durationMs,estimated?}, …]` — the `--action` fields, `estimated`
+  optional and `false` when absent) to a temp file and pass it with `--actions-file`:
+
+  ```bash
+  bun "$SETUP_SCRIPT" --actions-file <actions.json> --run-id "$RUN_ID" --project-root "$OWNING_TREE"
+  ```
+
+  Every row is recorded through the same writer as `--action` (one `action_runs` row per entry);
+  the batch is validated in full before the first write, so an invalid row or unreadable file
+  exits `1` with `{"ok":false}` and leaves **no** partial rows — fix the batch and re-emit. On
+  success it prints `{"ok":true,"runId":…,"recorded":<n>}` and exits `0`. Row emission stays
+  best-effort exactly like `--action`: if a row's write fails mid-batch, the failure is recorded
+  to the run record and the call reports `{"ok":false,…,"error":…}` but still exits `0` — the run
+  continues; never retry the batch or backfill by hand. `--actions-file` is exclusive with the
+  other mode flags (`--action`, `--decide`, `--close`, …): mixing them is a usage error (exit 2),
+  and a mixed call must be corrected, not silently split.
+
+- **A `decide` action (0941)** — the driver never executes the DecisionMaker itself; it delegates
+  to the same app runner the engine registers, which writes the resultFile row (schemaVersion 1)
+  and returns the decision, then the delegate records the `action_runs` row (`kind=decide`)
+  through the same writer as every other action:
+
+  ```bash
+  bun "$SETUP_SCRIPT" --decide --run-id "$RUN_ID" --node <state-id> --options-json <options-file>
+  ```
+
+  The options JSON mirrors the YAML `decide` options (`id`, `method: choice|noul`, `question`,
+  `choices`/`default`, optional `evidence`, optional `minConfidence`, `resultFile`); paths resolve
+  against the project workdir. The decision never pauses and never fails the run for model
+  problems: a degraded outcome (feature switch off, no backend, error, timeout, low confidence)
+  prints `ok:true` with `degraded:true`, the declared `reason`, and `value = default`, and exits
+  `0` — route on the resultFile's `.value` with the declared file guards. Every row carries
+  `source: model|default` (0976 R2), and the delegate appends
+  `decide node=<id> value=<v> source=<s> reason=<r>` to the run log, so a declared-default
+  fallback is never read as a model decision. Only an invalid options
+  schema exits `1` (fail closed), and usage errors exit `2`. The `action_runs` trace row is
+  best-effort exactly like `--action`.
+
+- **An operator pause is its own row (task 1136 R5)** — while the driver waits on a `hitl.confirm`
+  or `hitl.input`, emit the wait as its own boundary instead of charging it to the neighbouring
+  node:
+
+  ```bash
+  bun "$SETUP_SCRIPT" --action --run-id "$RUN_ID" --node <state-id> --kind operator-wait \
+    --status done --ok true --duration-ms <waited-ms> --project-root "$OWNING_TREE"
+  ```
+
+  `operator-wait` is a row kind, not a new state — the decision itself still belongs to the
+  declared node, and the wait's wall clock stays visible instead of inflating the node's duration.
+
+- **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> --project-root "$OWNING_TREE"
+  ```
+
+  The close also produces the execution summary (1146 R1): its stdout carries
+  **`summaryFile`** (`.spur/run/<runId>-summary.md`) unless `--no-summary` was passed. Print that
+  file's contents verbatim under an `### Execution summary` heading — the driver generates nothing
+  itself, and the window is the run row's `started_at` → close time, so no `SINCE` is recorded. A
+  summary failure never changes the close verdict: the file then holds exactly
+  `Execution summary: n/a (<reason>)`.
+
+  `--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`. On success
+  the close reports the recorded evidence: `{"ok":true,"runId":…,"actionRows":<n>}` plus
+  **`missingNodes`** — the declared states the driver recorded as entered that never emitted an
+  `action_runs` row (`{"missingNodes":["precheck","verify"]}`, empty array when the trace is
+  whole). `missingNodes` is a **trace defect reported, never a close failure**: the close still
+  exits `0`, and it exists so a gap is visible — the repair is to emit the missing rows in the next
+  run, never to backfill them (ADR-117).
+  After the close, the invoking command prints the measured
+  [execution summary](dev-operations.md#execution-summary) for `$RUN_ID` unless `--no-summary`.
+
+  **Zero-row done closes are a named failure (task 0975 R2).** A run closed `done` with **zero**
+  `action_runs` rows (`actionRows:0`) finalizes the row but exits `1` with
+  `{"ok":false,"code":"NO_ACTION_ROWS","actionRows":0}` — a run that claims success without a
+  single recorded action is exactly the untraced-runs gap ADR-117 closes, so the driver must
+  surface the code in its final report instead of reporting a clean close. The failure must NOT
+  be repaired by backfilling rows: the run row is already terminal, and hand-written rows are
+  forbidden (ADR-117) — record the finding and let the task's evidence show the gap. A `failed`
+  close with zero rows stays a clean `0` (a halt before the first boundary legitimately records
+  nothing), and any `done` close with `actionRows ≥ 1` exits `0`.
+
+**Best-effort at the action boundary only (ADR-117, task 1136 R1/R2).** An `--action` persistence
+failure is recorded — the delegate appends a `trace-emission-failed` line to
+`.spur/memory/runs/<run-id>.md` 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
+exception is the **run row itself**: a missing run row, a duration that cannot be measured, or a
+start time before `runs.started_at` are correctness failures and exit `1`
+(`RUN_NOT_FOUND`, `ACTION_DURATION_UNAVAILABLE`). The run-row closure (`--close`) is bookkeeping, not
+trace emission, and is **not** best-effort either: 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`, or a malformed `--duration-ms`) and must be corrected, not ignored.
+
+**Never suppress this output.** The driver reference forbids redirecting `inline-run-setup`,
+`quality-gate` and `persist-out*` stdout/stderr to `/dev/null`; a static pin fails any reference
+snippet that does. Suppressing a `RUN_NOT_FOUND` is how task 1132's 93 action rows disappeared.
+
+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/plugins/sp/skills/wayfinder/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wayfinder
-description: "Chart a multi-session investigation map when the destination is too foggy to spec in one session. Creates a spur feature as the map, decomposes specifiable questions into spur tasks, and resolves them one at a time until the route becomes visible. Triggers: wayfind, chart a course, multi-session investigation, --wayfind."
+description: "Chart a multi-session investigation map when the destination is too foggy to spec in one session. Creates a spur feature as the map, decomposes specifiable questions into spur tasks, and resolves them one at a time until the route becomes visible. Triggers: wayfind, chart a course, multi-session investigation, /sp:dev-find-way."
 license: Apache-2.0
 version: 1.0.0
 created_at: 2026-07-06
@@ -57,7 +57,7 @@ Activate sp:wayfinder when:
 | "multi-session investigation" | User expects multiple sessions to reach clarity |
 | "find the way to X" | Destination is named but the route is unknown |
 | "explore the solution space" | Open-ended exploration before committing |
-| `--wayfind` flag on `/sp:dev-brainstorm` | Power-user skip straight to charting |
+| `/sp:dev-find-way` | The command entry — charting or one-ticket resolution in an isolated worktree |
 
 **NOT for:**
 - A clear spec that just needs decomposition (use `sp:spec-decomposition` instead)
@@ -110,7 +110,7 @@ Two modes. Either way, **never resolve more than one ticket per session.**
 
 Invoked when the operator has a loose idea and the destination itself is foggy. Charting IS one session's work — do not also resolve tickets.
 
-0. **Branch first.** `git checkout -b wayfind/<destination-slug>` before touching the map. A session is what spans the fog edit and the tickets it graduates into — routinely separate commits — so the branch point is the only boundary that contains both. The `corpus.ungraduated-fog` gate measures `merge-base(origin/main, HEAD)..(working tree)`, which means it **cannot fire at all** on work done directly on the default branch. That is exactly how the 2026-08-07 incident shipped.
+0. **Worktree first.** Run in an isolated git worktree on its own branch — `/sp:dev-find-way` does this (`sp/wayfind-<slug>-<short-id>`, FF-merged on success). Never `git checkout -b` in a shared tree: it switches the checkout under every other agent using it. The `corpus.ungraduated-fog` gate measures `merge-base(origin/main, HEAD)..(working tree)`, so it **cannot fire at all** on the default branch — how the 2026-08-07 incident shipped.
 1. **Name the destination.** Run a discovery interview (one question at a time, always with a recommendation) to pin down what this map is finding its way to — the spec, decision, or change. The destination fixes the scope, so it's settled first.
 2. **Map the frontier breadth-first.** Fan out across the whole space rather than deep on any one thread, surfacing open decisions and the first steps takeable now. Use the decision-brief format for each HITL choice (see `../spur-dev/references/decision-brief.md`).
 3. **Create the map as a spur feature.** `spur feature create "<destination>"`. The feature description carries:
@@ -130,7 +130,7 @@ Invoked when the operator has a loose idea and the destination itself is foggy.
 
 Invoked when a map already exists (operator provides the feature ID). A ticket is **optional** — without one, pick the next frontier ticket, not the operator's preference. Pipeline runs: `references/pipeline-resolution.md`.
 
-0. **Branch first.** `git checkout -b wayfind/<wbs>-<slug>`, for the same reason as charting: steps 6 and 7 below remove fog from the map, and the gate that checks the removal was paid for measures the branch, not the commit. On the default branch the check silently passes no matter what you delete.
+0. **Worktree first.** Same rule as charting (`sp/wayfind-<wbs>-<short-id>`): steps 6 and 7 remove fog from the map, and the gate that checks the removal measures the branch, not the commit. The `wip` claim lands only in the worktree until the merge, so `/sp:dev-find-way` excludes tickets held by other active `dev-find-way` worktree markers when picking the frontier.
 1. **Load the map** — the feature description (the low-res view), not every task body. Read the destination and Decisions-so-far to orient.
 2. **Pick the first frontier ticket.** Query: `spur task list --feature <id> --status todo` — the first open, unblocked, unclaimed task. If the operator named one, use it instead.
 3. **Claim it.** `spur task update <wbs> wip` — before any work.
@@ -195,13 +195,9 @@ Ruling something out of scope is a scoping act, not a step on the route. When a
 
 ## Invocation
 
-### From `/sp:dev-brainstorm` (semi-automatic escalation)
+### From `/sp:dev-find-way` (primary)
 
-At the end of the discovery interview (Phase 1), the brainstorm command runs a **scope check**: "Can this be spec'd in one session, or is the destination itself still foggy?" If foggy, it offers wayfinding as the escalation path:
-
-> *"This is a multi-session investigation. Want me to chart a wayfinder map so we can work through it one decision at a time?"*
-
-The operator confirms before wayfinding begins — never silently escalate. The `--wayfind` flag on `/sp:dev-brainstorm` skips the prompt and enters wayfinding directly.
+`/sp:dev-find-way "<idea>"` charts; `/sp:dev-find-way <feature-id> [<wbs>]` resolves one ticket. The command owns the worktree lifecycle and dispatches here. `/sp:dev-brainstorm` never charts: when its scope check finds a foggy destination it stops and recommends `/sp:dev-find-way` — the operator decides.
 
 ### Direct invocation
 
@@ -225,9 +221,9 @@ The operator invokes this skill directly: `Skill(skill="sp:wayfinder", args="<lo
 ## Red Flags
 
 - Resolving more than one ticket in a single session.
-- Charting or resolving directly on the default branch — the `corpus.ungraduated-fog` gate is branch-scoped, so on `main` fog can be deleted with no ticket and nothing complains.
+- Charting or resolving outside an isolated worktree — on the default branch the branch-scoped `corpus.ungraduated-fog` gate never fires; a `git checkout -b` in a shared tree moves every other agent's checkout.
 - Creating a map without a destination statement — the destination fixes scope; without it, every ticket is unbounded.
-- Auto-escalating to wayfinding without operator confirmation (except under `--wayfind`).
+- Starting wayfinding without operator confirmation.
 - An empty or missing **### Not yet specified** section when the destination was described as foggy — fog that isn't written down is fog the next session can't see.
 - Skipping the claim step (`spur task update <wbs> wip`) before work — concurrent sessions may collide.
 - Pre-slicing fog into ticket stubs before the questions are sharp.
@@ -243,7 +239,7 @@ The operator invokes this skill directly: `Skill(skill="sp:wayfinder", args="<lo
 
 ### Charting verification
 
-- [ ] The session ran on its own branch, not the default branch (`git branch --show-current`).
+- [ ] The session ran in its own worktree + branch (`git rev-parse --git-dir` ≠ `--git-common-dir`; branch is not the default).
 - [ ] Destination is a single, concrete sentence (not a paragraph, not a vague noun phrase).
 - [ ] Map feature exists (`spur feature show <id>` returns clean).
 - [ ] Feature description has all six sections: Destination, Notes, Open questions, Decisions so far (empty), Not yet specified, Out of scope.
@@ -256,7 +252,7 @@ The operator invokes this skill directly: `Skill(skill="sp:wayfinder", args="<lo
 
 ### Resolution verification
 
-- [ ] The session ran on its own branch, not the default branch (`git branch --show-current`).
+- [ ] The session ran in its own worktree + branch (`git rev-parse --git-dir` ≠ `--git-common-dir`; branch is not the default).
 - [ ] Exactly one ticket was resolved this session.
 - [ ] The ticket was claimed (`wip`) before work began.
 - [ ] The resolution is recorded in the task body (not just a status transition — the answer is written down).

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

@@ -105,6 +105,29 @@
                         "type": "boolean",
                         "description": "When true, the engine pauses the run at this state for HITL (E3); resume with `spur workflow continue`."
                     },
+                    "display": {
+                        "type": "object",
+                        "additionalProperties": false,
+                        "description": "Presentation-only metadata for plan/UI generators; the engine never reads it at run time.",
+                        "required": ["phase"],
+                        "properties": {
+                            "phase": {
+                                "type": "string",
+                                "minLength": 1
+                            },
+                            "phaseTitle": {
+                                "type": "string",
+                                "minLength": 1
+                            },
+                            "title": {
+                                "type": "string",
+                                "minLength": 1
+                            },
+                            "show": {
+                                "enum": ["plan", "on-entry"]
+                            }
+                        }
+                    },
                     "onEnter": {
                         "type": "array",
                         "items": {