@gobing-ai/spur 0.3.55 → 0.3.58

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

@@ -199,10 +199,45 @@ spur workflow run ./workflows/approval.yaml --steer                # interactive
 - **`--steer`** is synchronous and in-process: it cannot combine with `--json` or `--async` (exit `2`).
   It accepts steering commands on stdin at declared action boundaries for interactive control.
 
+## Composition measures and the advisory (0615)
+
+`workflow validate` (valid path only) also reports a **warn-only composition advisory** covering the
+two detectable measures from ADR-069. It answers "does this workflow lean on ad-hoc shell or raw
+agent prompts where a first-class surface would own it better?" — nothing more.
+
+**The two triggers:**
+
+- **Shell measure** — a `shell` action (state hooks `onEnter`/`onExit`; guards are exempt) flags when
+  its `command` has **≥6** non-comment units (split on newline and `;`, blank/`#` units skipped).
+- **agent.run measure** — an `agent.run` action flags when its `input` is a **non-slash** prompt;
+  raw prompt length only sets the reported severity (<200 low / ≤1000 medium / >1000 high).
+
+**How to run it:** it is not a separate command — `spur workflow validate <file> --json` returns
+`composition: {findings[], suppressed}` on the valid path; human mode prints the advisory to stderr
+with exit 0. Actions with a recorded disposition in
+`config/workflow-composition-baseline.json` (resolved by walking up from the workflow file) are
+counted in `suppressed`, not `findings`.
+
+**How to read it, and the fix path per defect class:**
+
+- **Shell finding** → pick one of the five recorded owner options from
+  `docs/design/workflow-shell-ownership.md`: (a) public `spur` verb (consent-gated),
+  (b) application service, (c) least-privilege built-in action kind, (d) workflow-relative external
+  extension, (e) deliberately-stays-shell exception (record the reason in the baseline).
+- **agent.run finding** → move the operation behind a centralized agent skill or slash command and
+  make the action's `input` reference it (ADR-043 preference).
+
+**Advisory-only posture (binding):** findings never justify blocking a run, failing a gate, or
+editing a pipeline that is currently executing. The advisory never changes `validate`'s exit status,
+never blocks `workflow run`, and is not part of `spur-check` / `spur-check-new`. Treat a finding as
+a to-be-enhanced note for the workflow's owner — surface it in your report, apply the fix only when
+the operator accepts it, and never hot-edit a running workflow's shell in place.
+
 ## Command surface
 
 ```
 spur workflow validate <file> [--no-schema] [--json]
+spur workflow show      <file>
 spur workflow run      <file> [--run-id <id>] [--vars <json>] [--dry-run] [--async] [--no-plan] [--quiet/--silent/--verbose] [--detail <level>] [--trace-file] [--no-log] [--steer] [--json]
 spur workflow continue [run-id] [--yes] [--answer <yes|no|cancel>] [--json]
 spur workflow cancel   <run-id> [--json]
@@ -359,3 +394,8 @@ directly on the command line.
 
 **Template type**: technique
 **Purpose**: Operate `spur workflow` across its full lifecycle — choose the execution mode, author, validate, run, and refine dual-mode workflows
+
+> **Shared option declarations (0618):** options shared across command modules resolve from
+> `apps/cli/src/commands/shared-options.ts` (`SHARED_OPTIONS`). Never re-declare a shared flag
+> inline in a command module — see SKILL.md "Shared option registry" and
+> `docs/04_DESIGN.md` §1.0.1.

package/plugins/sp/skills/spur-dev/references/ac-style-guide.md

@@ -193,7 +193,7 @@ During decomposition, each core scenario maps to ≥1 task:
 | R3 — Login with email and password | 0043, 0044 | Auth service + UI |
 
 The mapping is recorded in the task's `## Background` or in the feature's `## Notes`.
-`spur feature check` warns on unmapped core scenarios after `spur feature refresh`
+`spur feature check` warns on unmapped core scenarios after `spur feature refresh --feature <id>`
 regenerates the `## Tasks` block.
 
 ## Decision-trace → AC-scenario mapping

package/plugins/sp/skills/spur-dev/references/dev-operations.md

@@ -412,14 +412,15 @@ is the procedure. The backing is a combination of git CLI, `spur` CLI, and agent
 - **Behavior:** 0. **Start at the anchors, never at a discovery run.** If `--findings <anchors>` is given, that space-separated `file:line` list IS the failing set — open those locations first, in order, and fix them; do not run the gate to find out what broke. If only `--gate-log <path>` is given, read that log first and identify the failing findings (lint/test errors with their `file:line` anchors) before running the loop — the captured log is the authoritative source. Either way the first action of this hop is a read, not a gate run (R3, task 0482).
   1. Run `bun run format` (add `-- <path>` if `--scope` is given) to settle formatter-only diffs first — `bun run lint` asserts `--error-on-warnings` + typecheck but does **not** rewrite formatting, so a formatter-only change (e.g. a multi-line import reflow) can pass `lint` locally yet still be unformatted. Formatting before linting removes that class of false-green.
   2. Run `bun run lint` (add `-- <path>` if `--scope` is given). Collect all errors.
-  3. If lint is clean, skip to step 5.
-  4. **Lint fix loop:** for each error, diagnose the root cause and apply the smallest fix. **Use targeted probes to verify each fix** (`bunx tsc --noEmit` on the affected package, `bun run lint -- <file>`) — do NOT re-run the full gate after every batch. Loop until lint is green.
-  5. Run `bun run test`. Collect all failures.
-  6. If tests are green, done.
-  7. **Test fix loop:** for each failure, diagnose (test bug vs implementation bug), apply the fix, re-run the **failing test only** (`bun test <file> --test-name-pattern "<test>"`). Do NOT re-run the full suite per fix — it is the dominant loop cost (task 0436 R2).
-  8. **Confirming run (at most once).** After all fixes, run `bun run format && bun run lint && bun run test` **at most once** to confirm. If it passes, the hop is done.
-  9. **Pipeline-awareness (R4, task 0483).** When `/sp:dev-fixall` is invoked from the pipeline's `test-fix` hop, `test-recheck` runs the full `${vars.qualityGateCmd}` gate immediately after this hop returns — that is the **deciding** run that writes PASS to `.spur/run/<wbs>-test-gate.status`. Do NOT re-run the full gate beyond the single confirming run in step 8; the deciding run belongs to `test-recheck`. If your confirming run already passed, return immediately — a second or third gate run inside this hop is pure redundancy (0482 ran the gate 3× plus a standalone `bun run test`; all four were followed by `test-recheck` running it a 5th time). If your confirming run failed and you fixed more, re-run the full gate once more within `--max-retry` budget, then return — let `test-recheck` judge.
-  10. Report: list what was fixed (file + one-line summary per fix). If any error could not be resolved, report it explicitly — do not suppress.
+  3. **Surface-change sweep (before any fix).** If the failing set is a **surface/parity** change — CLI noun/verb/flag surface, reference-file structure, or a renamed/moved symbol — do one upfront `rg` sweep across ALL test dirs + docs for stale references to the changed symbols (e.g. `rg -l "<old-noun>|<old-file>.md|Tier C" apps/*/tests plugins/sp/tests plugins/sp/skills docs`), and fix every pinned test/docs file in that sweep. A surface change is pinned in **multiple independent test files** (each with its own hardcoded noun→reference map); discovering them one-by-one via full-suite probes is the dominant waste — each wave costs a suite run and a fresh edit loop (task 0436 R2 lesson). One sweep produces the complete edit set upfront.
+  4. If lint is clean, skip to step 6.
+  5. **Lint fix loop:** for each error, diagnose the root cause and apply the smallest fix. **Use targeted probes to verify each fix** (`bunx tsc --noEmit` on the affected package, `bun run lint -- <file>`) — do NOT re-run the full gate after every batch. Loop until lint is green.
+  6. Run `bun run test`. Collect all failures.
+  7. If tests are green, done.
+  8. **Test fix loop:** for each failure, diagnose (test bug vs implementation bug), apply the fix, re-run the **failing test only** (`bun test <file> --test-name-pattern "<test>"`). Do NOT re-run the full suite per fix — it is the dominant loop cost (task 0436 R2).
+  9. **Confirming run (at most once).** After all fixes, run `bun run format && bun run lint && bun run test` **at most once** to confirm. If it passes, the hop is done.
+  10. **Pipeline-awareness (R4, task 0483).** When `/sp:dev-fixall` is invoked from the pipeline's `test-fix` hop, `test-recheck` runs the full `${vars.qualityGateCmd}` gate immediately after this hop returns — that is the **deciding** run that writes PASS to `.spur/run/<wbs>-test-gate.status`. Do NOT re-run the full gate beyond the single confirming run in step 9; the deciding run belongs to `test-recheck`. If your confirming run already passed, return immediately — a second or third gate run inside this hop is pure redundancy (0482 ran the gate 3× plus a standalone `bun run test`; all four were followed by `test-recheck` running it a 5th time). If your confirming run failed and you fixed more, re-run the full gate once more within `--max-retry` budget, then return — let `test-recheck` judge.
+  11. Report: list what was fixed (file + one-line summary per fix). If any error could not be resolved, report it explicitly — do not suppress.
 - **Invariants:** Never bypass with `--no-verify`, `--force`, or new `biome-ignore`/`eslint-disable` suppressions. Never skip or `.skip` a test to make the suite green. Fix the root cause, not the symptom. Never claim green on `bun run lint` alone — a formatter-only diff passes `lint` but fails the formatter; run `bun run format` (or assert it produces no diff) before declaring the gate clean. **Never re-run the full gate more than once per confirming pass** (R4) — use targeted probes during the fix loops and let the pipeline's `test-recheck` state be the deciding run.
 - **MANDATORY Exit Condition.** The ONLY way to complete successfully:
   1. Run validation command: `eval "$VALIDATION_CMD"`

package/plugins/sp/skills/spur-dev/references/execution-batch.md

@@ -734,6 +734,25 @@ command doc so it does not read as a bug.
   `sp:super-planner` surfaces blockers/HITL only at the **batch boundary** (between task runs), not
   from inside a pipeline step.
 
+## Gate preflight (dogfood 2026-08-21, feature A3)
+
+The A3 batch burned multiple full `spur-check-new` runs (~2 min each) that failed only at the tail
+gates. The cheap rule gates fail fast when run first — the full-gate run is dominated by the ~65 s
+test suite, so a gate run that dies at `test-post-check` or `corpus-check` wasted most of its wall
+time. Before launching a full `spur-check-new`:
+
+1. **Run the two rule gates first** — `bun run test-pre-check` (43 rules: `no-console-output`,
+   `no-direct-process-spawn`, `cli-*`, `require-corresponding-test`) and `bun run test-post-check`
+   (`every-export-has-tsdoc`, `coverage-gate`). They catch boundary/TSDoc violations in seconds.
+2. **Promoted code must satisfy the boundary rules `scripts/` never enforced.** A command module
+   moving from `scripts/` into `apps/cli/src` must route output through the `CommandOutput` seam (no
+   `console.*`), spawn processes via `NodeProcessExecutor` (no `Bun.spawnSync`), get a
+   `runtime-boundaries` fs-io exemption for sync reads (mirrors `task.ts`), and a non-command helper
+   must not live in `apps/cli/src/commands/` (the noun scan treats every file there as a noun).
+3. **Doc/TSDoc edits shift `file:line` anchors** cited by other tasks — `corpus-check` surfaces them
+   as `L4.anchor-subject-mismatch`. Repoint the shifted citations (via `spur task update --section`)
+   in the same commit, and reconcile new/stale baseline entries before the gate run.
+
 ## AC traceability
 
 | AC | Where satisfied |

package/plugins/sp/skills/spur-dev/references/execution-workflow.md

@@ -351,7 +351,7 @@ After a completed task, decide next action:
 - **More tasks in the feature?** Pick the next one, run again.
 - **Feature complete?** Run `spur feature update <id> verifying` to mark it for
   acceptance verification.
-- **All done?** Run `spur task refresh` + `spur feature refresh` to regenerate the kanban
+- **All done?** Run `spur task refresh` + `spur feature refresh --all` to regenerate the kanban
   and index.
 
 ## Skipping HITL

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

@@ -124,12 +124,34 @@ Transition guards are not advisory. Execute the declared guard exactly, in order
 resolved variables and artifacts. `--no-lifecycle` remains bookkeeping only; the YAML's task checks,
 verdict gate, record step, and done guard all remain authoritative.
 
-## Batch use
+## Record & done sequencing (dogfood 2026-08-21, feature A3)
 
-Sequential `/sp:dev-runall` with omit/`inline` runs this driver once per ready WBS, with a fresh run
-id and the same frozen/topologically ordered batch plan. Batch inspection, halt/keep-going policy,
-and reporting remain in `execution-batch.md`. Parallel mode cannot share one host session safely and
-therefore keeps the existing isolated subprocess/worktree path (trigger 4).
+Order matters for the `testing → done` hop. The A3 batch hit the same clobbering spiral on two
+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.
+   ```bash
+   # verdict artifact first (shape: {wbs, verdict, requirements:[{id,status,evidence}], checks:[], source})
+   # then the record hop; then re-write Testing/Solution if record's backfill is thinner than intended.
+   spur task update <wbs> wip --no-lifecycle
+   spur task record <wbs> --solution-from-diff --transition testing
+   ```
+   The engine now preserves an already-authored Testing when the verdict is UNKNOWN (task-service
+   `record` fallback-only, mirroring the Review 0593 precedent) — but the order above is still the
+   contract for the standard pipeline.
+2. **Done-probe before done.** Run the check projected to `done` (`spur task check <wbs> --as done`
+   via the `TaskCheckService` probe pattern) — it surfaces `L3.unchecked-checklist` (flip `- [ ]` → `- [x]`)
+   and `L3.required-section-placeholder` before the transition, not after.
+3. **Solution change-map anchor rule (L4.anchor-subject-mismatch).** A Solution change-map table must
+   list **one `file:line` per row**. A ·-joined paragraph makes every anchor's "subject" the other
+   anchors and trips the L4 subject check. Paths containing `_` (e.g. `docs/help/cmd_*.md`,
+   `spur-cli-matrix.md`) can **never** match their cited line — the snake_case filename token is
+   extracted as the subject and cannot appear in the line content — so drop those rows from the table
+   (prose still covers them).
 
 ## Failure contract
 

package/plugins/sp/skills/spur-dev/references/planning-workflow.md

@@ -146,7 +146,7 @@ that is the pre-check's job above). Common shape failures:
 - WBS collisions (already-allocated range).
 
 Loop until the command exits 0 — then the batch is created and each task appears in the
-feature's `## Tasks` block on next `spur feature refresh`.
+feature's `## Tasks` block on next `spur feature refresh --feature <id>`.
 
 **If you decomposed a parent task into sub-task files** (the children carry `parent_wbs`), the
 sub-task roster is **auto-generated** — `spur task batch-create` invokes `spur task refresh-roster`