@gobing-ai/spur 0.3.95 → 0.3.97

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

@@ -2,7 +2,7 @@
 name: inline-pipeline-driver
 description: "Interactive host-session interpreter for Spur state-machine pipelines: execute the existing FSM without a workflow agent subprocess while preserving actions, guards, artifacts, and provenance."
 owner: spur-dev-maintainers
-retirement-criterion: "The per-task interpreter retires once the engine covers per-task execution for /sp:dev-runall with real terminal runs and the parity check (plugins/sp/scripts/inline-pipeline-parity-check.ts) is green (D8 decision D7). Batch orchestration wrapper may remain."
+retirement-criterion: "The per-task interpreter retires once the engine covers per-task execution for /sp:dev-runall with real terminal runs and the parity check (scripts/commands/inline-pipeline-parity-check.ts) is green (D8 decision D7). Batch orchestration wrapper may remain."
 see_also:
   - spur-dev
   - execution-workflow
@@ -11,6 +11,10 @@ see_also:
 
 # Inline Pipeline Driver
 
+**Installed-copy drift (1046):** Superskill converts `/sp:dev-*` command spellings to
+`/sp-dev-*` for Codex. After `superskill install sp`, this adapter-only difference remains;
+the interpreter and trace instructions must match. Never hand-edit the installed reference.
+
 **Owner:** `spur-dev-maintainers` (per task 0755 R1). Reach the named owner via the frontmatter; no need to read the originating task.
 
 **Retirement criterion (0755 R5, D8 decision D7):** the per-task interpreter retires once the engine covers per-task execution for `/sp:dev-runall` with real terminal runs **and** the parity check (this doc's documented action/guard set ≡ the resolved action/guard set of every `.spur/workflows/*.yaml`) is green. Recording the criterion is part of this task; acting on it is not — that is a separate A3-gate decision.
@@ -18,7 +22,7 @@ see_also:
 ## Supported action and guard set (0755 R2 parity contract)
 
 The action and guard kinds this driver implements. The parity check
-(`plugins/sp/scripts/inline-pipeline-parity-check.ts`) compares this set against
+(`scripts/commands/inline-pipeline-parity-check.ts`) compares this set against
 the resolved actions and guards of every `.spur/workflows/*.yaml`; any element present
 in one and absent in the other fails the check. Add a new kind here when the driver
 implements it; remove the entry when the corresponding kind is dropped from the YAML.
@@ -69,8 +73,8 @@ the human/native presentation layer — labels are display addresses only, never
 1. Resolve the command inputs, `--auto`, and any explicit `--vars` — **without reading the selected
    YAML yet**. An explicit non-inline executor selection chooses the subprocess workflow path.
 2. Allocate a collision-resistant inline run id (`uuidgen`, with a timestamp/pid fallback), create
-   `.spur/run/`, and use the two-file run record (task 0927) — append lines to
-   `.spur/run/<run-id>.md` and read machine state from `.spur/run/<run-id>.state.json`.
+   `.spur/run/` for attempt staging and `.spur/memory/runs/` for retained records, and use the two-file run record (task 0927) — append lines to
+   `.spur/memory/runs/<run-id>.md` and read machine state from `.spur/memory/runs/<run-id>.state.json`.
 3. **Authoritative run identity (task 0804 R1, fail-closed).** Persist the run row through the
    internal delegate before any stage executes — this is what makes bound `run.artifact` record
    accept the inline run (0785 R3):
@@ -91,7 +95,7 @@ the human/native presentation layer — labels are display addresses only, never
    obtains the selected definition from the existing CLI `workflow show --format todo --json`
    projection and revalidates its schema/name/digest before preserving its source layer.
    Both paths create-or-attach the row,
-   and writes the run-record state `.spur/run/<run-id>.state.json` plus the `.md` run-start
+   and writes the run-record state `.spur/memory/runs/<run-id>.state.json` plus the `.md` run-start
    header (task 0927; a legacy pre-0927 run keeps its `<run-id>-inline-setup.json` sidecar).
    Seed `__runId` and `__definitionDigest`
    from that state so proof capture and bound registration verify against the persisted identity.
@@ -201,7 +205,7 @@ Expected artifacts per stage (all run-scoped under `.spur/run/<run-id>-*`):
 | start | `-idea-input.md` (verbatim idea), `-idea-precheck-doctor.status` |
 | discovery | `-idea-eval-report.md` (with `## Requirement inventory`), `-idea-needs-design.json` |
 | feature-create | `-idea-feature-id.txt`, `-idea-goal.md`, `-idea-scope.md` |
-| ac-generate | `-idea-ac-content.md`, `-idea-ac-check.status`, `-idea-coverage.status` |
+| ac-generate | `-idea-ac-content.md`, `-idea-ac-check.status` |
 | system-design | `-idea-design-review.md`, `-idea-design-check.status` |
 | decompose | `-idea-task-batch.json`, `-idea-task-order.json` |
 | batch-create-run | `-idea-batch-create-result.json`, `-idea-batch-create.done`/`.failed` |
@@ -236,6 +240,19 @@ Start at `initialState`. For each current state, execute its `onEnter` actions i
 then evaluate outgoing transitions in declaration order and take the first passing guard. Stop only
 at a declared terminal state or a surfaced HITL pause. The `iterationBound` remains mandatory.
 
+After each executed action settles, record its boundary before the next action, transition guard,
+or terminal close. Measure its actual duration and preserve its declared failure policy:
+
+```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>
+```
+
+For a multi-action state, `--actions-file` may emit the measured boundaries together before leaving
+that state. Follow [Structured trace emission](#structured-trace-emission-adr-117-task-0868) for the
+payload, delegated `decide` emission and best-effort failure handling. Never retry a failed batch
+or backfill at close; a zero-row done close fails with `NO_ACTION_ROWS`.
+
 Action semantics come from the YAML and the workflow action contract:
 
 - `shell` — run the expanded command in the project working tree with resolved vars exported as
@@ -247,6 +264,13 @@ Action semantics come from the YAML and the workflow action contract:
   actions/guards.
 - `hitl.confirm` — under `profile=auto`, follow the YAML's auto-skip transition. Otherwise pause,
   surface the prompt, and resume from the same state with the operator's answer.
+  **Host-session rendering:** ask the gate as ONE `AskUserQuestion`
+  [decision brief](decision-brief.md), never a typed yes/no. Read the state's evidence (the
+  artifacts its prompt names and the recorded `.status` files) and derive the recommendation;
+  map options to the `yes` / `no` / `cancel` answers the guards route on, recommended option
+  first, each with a one-line reason from that evidence. When a `no` needs operator feedback
+  (design-approval's `## Operator feedback`), take it from the operator's notes/"Other" text
+  and write it into the named artifact yourself before resuming. Never ask them to edit the file.
 - `hitl.input` — pause, surface the declared prompt (the agent's operator question, 0933), and
   resume from the same state with the operator's answer written into the declared var (default
   `__hitlInput`); the subsequent guards route on answer presence exactly as the engine does.
@@ -273,12 +297,12 @@ Action semantics come from the YAML and the workflow action contract:
   and pass the same `--feature-file` the run folded in — omitting it, or running from elsewhere,
   yields a different digest and the mismatch surfaces later as a refused `run.artifact`
   registration — and the run-scoped review-completion marker exists — then appends one provenance
-  line to `.spur/run/<run-id>.md` naming the equivalence (artifact kind, path, verdict, digest) and
+  line to `.spur/memory/runs/<run-id>.md` naming the equivalence (artifact kind, path, verdict, digest) and
   proceeds to `spur task record`. A failed validation stops at the state and follows the failure
   contract; the step is never silently skipped. Artifact-provenance consumers read that run-log
   line on the inline path — there is no ledger row. The validation also includes **run/definition
   identity agreement from authoritative evidence** (task 0809 R4): the verdict's `proof.runId` and
-  `proof.definitionDigest` must agree with the run-record state `.spur/run/<run-id>.state.json`
+  `proof.definitionDigest` must agree with the run-record state `.spur/memory/runs/<run-id>.state.json`
   (legacy pre-0927 runs: `<run-id>-inline-setup.json`) and the persisted run row; if that identity
   is absent or conflicts, STOP — recreating a row is
   not a diagnostic operation. The app-service bound-artifact fixture (which writes a real engine
@@ -307,6 +331,18 @@ Action semantics come from the YAML and the workflow action contract:
    with no `estimate_hours` passes this condition unchanged. The driver reads the frontmatter value
    directly — never estimates size itself.
 
+   **Diffstat arm (verify only, 1033 R1).** When the current state id is `verify`, condition 5
+   fails when the triage diffstat file `.spur/run/<wbs>-diffstat.json` exists and shows a
+   small, non-sensitive diff: `([.files, .insertions, .deletions] | all(type == "number")) and
+   .files <= 3 and (.insertions + .deletions) <= 60 and
+   .sensitive == false` (literal thresholds; the driver reads the file with `jq` — it never
+   estimates size itself). A missing, unparsable or `sensitive: true` diffstat leaves condition 5
+   as above, so the failure mode is more isolation, never less. A missing or null count also leaves
+   condition 5 as above. Below the floor on this arm, the
+   run log carries `stage verify executed inline in session <session-id> (below dispatch floor:
+   diffstat files <f> lines <n>)`. Only `verify` eligibility changes: `implement` and `review`
+   keep the estimate floor, and the pipeline state graph is unchanged.
+
 All five pass → dispatch. Any pre-dispatch failure → execute the stage **once** in the host session.
 An `agent.run` whose `input` is free-form prose rather than a pure slash command fails condition 2
 and is never dispatch-eligible: the driver executes it in the host session and logs it with the
@@ -458,7 +494,7 @@ or an operator decision returns a blocker; the host pauses at the current state
 subagent cannot approve, infer consent, or recursively invoke the full pipeline.
 
 After every successful inline `agent.run` action append exactly one provenance line (inline or
-subagent form above) to `.spur/run/<run-id>.md`, where `<id>` is the current YAML state id. Also
+subagent form above) to `.spur/memory/runs/<run-id>.md`, where `<id>` is the current YAML state id. Also
 log start/failure and the ignored timeout value so an inline run remains auditable without
 fabricating an `AgentRunTracedResult`.
 
@@ -470,7 +506,7 @@ in one file and makes the run unauditable (task 0726 mixed both forms).
 
 ## Structured trace emission (ADR-117, task 0868)
 
-`.spur/run/<run-id>.md` is the human half of the two-file run record — evidence, **not the record
+`.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
@@ -500,6 +536,25 @@ The driver reaches it through the existing run delegate (`$SETUP_SCRIPT`,
   (0887 R8), so `completed_at − started_at == duration_ms` exactly; a back-date failure is
   recorded (`action.backdate`) and never affects the run.
 
+- **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}, …]` — same fields the `--action` flags carry) to a temp
+  file and pass it with `--actions-file`:
+
+  ```bash
+  bun "$SETUP_SCRIPT" --actions-file <actions.json> --run-id "$RUN_ID"
+  ```
+
+  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`)
@@ -544,7 +599,7 @@ The driver reaches it through the existing run delegate (`$SETUP_SCRIPT`,
   nothing), and any `done` close with `actionRows ≥ 1` exits `0`.
 
 **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>.md` and
+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 run-row closure (`--close`) is
@@ -568,10 +623,12 @@ Order matters for the `testing → done` hop. The A3 batch hit the same clobberi
 tasks (0617, 0619) because the sections were hand-written **before** the verdict artifact existed:
 
 1. **Write the verdict artifact first.** `spur task record --solution-from-diff --transition testing`
-   reads `.spur/run/<wbs>-verdict.json` (default). With no artifact it emits a **UNKNOWN** verdict and
-   **overwrites** a hand-authored `## Testing` with an auto-generated "No requirements recorded" table,
-   plus replaces `## Solution` with a bare auto change-map. Creating the artifact first (PASS, with
-   requirement rows keyed by scenario title) makes `task record` the compliant path.
+   reads `.spur/run/<wbs>-verdict.json` (default attempt output) on every invocation and atomically retains the recorded verdict under `.spur/memory/evidence/`. A missing or malformed artifact
+   yields **UNKNOWN**: bare Testing receives a "No requirements recorded" stub, while already-authored
+   Testing is preserved. `--solution-from-diff` backfills only a bare Solution. The A3 clobbering above
+   describes the historical behavior, corrected by the authored-Testing safeguard. Creating the
+   artifact first (PASS, with requirement rows keyed by scenario title) remains the standard order;
+   re-running record after a real verdict arrives refreshes Testing from that verdict.
 
    ```bash
    # verdict artifact first (shape: {wbs, verdict, requirements:[{id,status,evidence}], checks:[], source})

package/plugins/sp/skills/spur-doctor/SKILL.md

@@ -105,7 +105,7 @@ rows stay per file. Flagged rows wait for the operator's answer.
 
 ## Workflow step profile and cache-window flags
 
-The step profile (`plugins/sp/scripts/workflow-step-profile`, ADR-065 plugin entrypoint) reads
+The step profile (`plugins/sp/scripts/workflow-step-profile`, ADR-065 plugin entrypoint whose aggregation core lives in `packages/app/src/workflow/step-profile.ts`) reads
 `spur workflow trace` for a workflow's last N completed, non-dry runs. Per node and action kind it
 reports run count, executions, p50 and max `durationMs`, p50 idle gap before the step, session mode
 (`fresh`, `resumed` or `mixed`) and `cacheHit` p50 with its coverage — satellite §10 step evidence.

package/plugins/sp/skills/sys-architecture/SKILL.md

@@ -73,8 +73,9 @@ codebase (or a named module tree) for **shallow modules and deepening opportunit
 them as candidates for the planning half. This is a *generator*, not a fixer — it never refactors;
 it produces a ranked candidate report an operator can turn into a task.
 
-**Not `/sp:dev-review`.** `/sp:dev-review` is a per-task DIFF review (a WBS, forward, findings written
-to the task's `## Review`, backed by `sp:code-verification`). The survey has no WBS and no diff — it
+**Not `/sp:dev-review`.** `/sp:dev-review` is a DIFF review of a task set (`--tasks`/`--feature`) or an advisory `--scope` path review
+(task targets: forward, findings written to each task's `## Review`; paths: advisory report, no task
+mutation; backed by `sp:code-verification`). The survey has no task set and no diff — it
 audits the standing codebase and feeds the planning half. Folding it into `dev-review` would overload
 that verb and pollute `code-verification` with a codebase scanner; it earns its own operation here.