@gobing-ai/spur 0.3.97 → 0.3.98

package/plugins/sp/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "sp",
-    "version": "0.3.97",
+    "version": "0.3.98",
     "description": "Spur — a local-first harness engineering toolkit that wraps mainstream coding agents with constraint checking, workflow orchestration, and history analytics.",
     "extensions": {
         "pi": ["./hooks/pi/guard-extension.ts"]

package/plugins/sp/references/roles.md

@@ -91,9 +91,9 @@ must not sit below the highest `min_tier` among its folded stages.
   architecture survey, feature-frontier prioritization, and feature-tree restructure. Folds `plan`,
   `refine`, `brainstorm`.
 
-**Placement notes (directory closure, task 0535).** The decided four-row table listed 31 commands;
-the live `plugins/sp/commands/` directory has 38 (39 at the time of the mapping; `dev-history-load`
-was removed in HA-S1 0661). The six additional commands were placed by the
+**Placement notes (directory closure, task 0535).** The decided four-row table listed 31 commands.
+The current command inventory comes from `plugins/sp/commands/`; `dev-history-load`
+was removed in HA-S1 0661. The six additions to the original mapping were placed by the
 same stage logic: `dev-refineall` folds `refine` → planner; `dev-find-next` is planning-side
 frontier work → planner; `dev-feature-change` is planning-half corpus surgery on the feature tree →
 planner; `dev-gtd` is the execution/delivery flow → coder; `dev-find-conflict` and `dev-find-issue`

package/plugins/sp/scripts/inline-run-setup.mjs

@@ -15,7 +15,7 @@ function getEnvVar(name, fallback) {
 
 // plugins/sp/scripts/inline-run-setup.ts
 function usage() {
-  console.error([
+  const text = [
     "Usage: bun plugins/sp/scripts/inline-run-setup.ts --run-id <id> --file <definition> [--spur-bin <path>]",
     "       bun plugins/sp/scripts/inline-run-setup.ts --fingerprint --task-file <path> [--feature-file <path>] [--spur-bin <path>]",
     "       bun plugins/sp/scripts/inline-run-setup.ts --action --run-id <id> --node <state> --kind <kind> --status <done|failed> --ok <true|false> --duration-ms <n> [--spur-bin <path>]",
@@ -23,9 +23,11 @@ function usage() {
     "       bun plugins/sp/scripts/inline-run-setup.ts --close --run-id <id> --status <done|failed|paused> [--reason <terminal-reason>] [--spur-bin <path>]",
     "       bun plugins/sp/scripts/inline-run-setup.ts --persist-out --from <worktree-path> [--task-file <path>]... [--spur-bin <path>]",
     "       terminal-reason is a closed enum (0937 R2): done, paused-operator, failed-check, failed-agent, failed-timeout, failed-guard, cancelled, interrupted, retry-exhausted",
+    "       close defaults (1051 AC1): --status done \u2192 reason done, --status paused \u2192 reason paused-operator; --status failed requires an explicit --reason",
     "       bun plugins/sp/scripts/inline-run-setup.ts --decide --run-id <id> --node <state> --options-json <file> [--spur-bin <path>]"
   ].join(`
-`));
+`);
+  console.error(text);
   process.exit(2);
 }
 var SAFE_RUN_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;

package/plugins/sp/scripts/inline-run-setup.ts

@@ -15,18 +15,18 @@ import { getEnvVar } from '../lib/env';
 type InlineApp = typeof spurApp & { EMBEDDED_SPUR_SCHEMAS?: ReadonlyMap<string, string> };
 
 function usage(): never {
-    console.error(
-        [
-            'Usage: bun plugins/sp/scripts/inline-run-setup.ts --run-id <id> --file <definition> [--spur-bin <path>]',
-            '       bun plugins/sp/scripts/inline-run-setup.ts --fingerprint --task-file <path> [--feature-file <path>] [--spur-bin <path>]',
-            '       bun plugins/sp/scripts/inline-run-setup.ts --action --run-id <id> --node <state> --kind <kind> --status <done|failed> --ok <true|false> --duration-ms <n> [--spur-bin <path>]',
-            '       bun plugins/sp/scripts/inline-run-setup.ts --actions-file <json-file> --run-id <id> [--spur-bin <path>]  (1007 R5 batch trace emission)',
-            '       bun plugins/sp/scripts/inline-run-setup.ts --close --run-id <id> --status <done|failed|paused> [--reason <terminal-reason>] [--spur-bin <path>]',
-            '       bun plugins/sp/scripts/inline-run-setup.ts --persist-out --from <worktree-path> [--task-file <path>]... [--spur-bin <path>]',
-            '       terminal-reason is a closed enum (0937 R2): done, paused-operator, failed-check, failed-agent, failed-timeout, failed-guard, cancelled, interrupted, retry-exhausted',
-            '       bun plugins/sp/scripts/inline-run-setup.ts --decide --run-id <id> --node <state> --options-json <file> [--spur-bin <path>]',
-        ].join('\n'),
-    );
+    const text = [
+        'Usage: bun plugins/sp/scripts/inline-run-setup.ts --run-id <id> --file <definition> [--spur-bin <path>]',
+        '       bun plugins/sp/scripts/inline-run-setup.ts --fingerprint --task-file <path> [--feature-file <path>] [--spur-bin <path>]',
+        '       bun plugins/sp/scripts/inline-run-setup.ts --action --run-id <id> --node <state> --kind <kind> --status <done|failed> --ok <true|false> --duration-ms <n> [--spur-bin <path>]',
+        '       bun plugins/sp/scripts/inline-run-setup.ts --actions-file <json-file> --run-id <id> [--spur-bin <path>]  (1007 R5 batch trace emission)',
+        '       bun plugins/sp/scripts/inline-run-setup.ts --close --run-id <id> --status <done|failed|paused> [--reason <terminal-reason>] [--spur-bin <path>]',
+        '       bun plugins/sp/scripts/inline-run-setup.ts --persist-out --from <worktree-path> [--task-file <path>]... [--spur-bin <path>]',
+        '       terminal-reason is a closed enum (0937 R2): done, paused-operator, failed-check, failed-agent, failed-timeout, failed-guard, cancelled, interrupted, retry-exhausted',
+        '       close defaults (1051 AC1): --status done → reason done, --status paused → reason paused-operator; --status failed requires an explicit --reason',
+        '       bun plugins/sp/scripts/inline-run-setup.ts --decide --run-id <id> --node <state> --options-json <file> [--spur-bin <path>]',
+    ].join('\n');
+    console.error(text);
     process.exit(2);
 }
 

package/plugins/sp/skills/code-implementation/SKILL.md

@@ -184,7 +184,7 @@ reproduce → isolate → minimal fix → regression guard.
 
 - Writing code without having read the immediate callers of what you're changing.
 - A `## Solution` section that lists files but not what changed or why.
-- A `## Solution` section with file references that are not in backtick `` `path:line` `` form (L3 requirement: `` `packages/app/src/foo.ts:123` `` or `` `packages/app/src/bar.ts:10-20` ``; paths from repo root).
+- A `## Solution` section with file references that are not in backtick `` `path:line` `` form (L3 requirement: `` `packages/app/src/foo.ts:123` `` or `` `packages/app/src/bar.ts:10-20` ``; paths from repo root). Non-repo paths (external packages, `@scope/...`) can never resolve repo-relative — cite them in the frozen external-evidence form instead: `Evidence: @gobing-ai/ts-x \`src/persistence.ts\` line 108` (origin and line number OUTSIDE the backticks). Wrong: `` `@gobing-ai/ts-x/src/persistence.ts:108` `` — the L4 gate fails it as an unresolvable anchor (task 1055).
 - A new abstraction with exactly one caller and no second use in sight.
 - The diff touches files unrelated to the task's scope.
 - The diff touches another WBS's surfaces, or the pass reads sibling `todo` / `wip` task files.

package/plugins/sp/skills/conflict-finding/SKILL.md

@@ -249,7 +249,7 @@ Thin wrapper: `Skill(skill="sp:conflict-finding", args="$ARGUMENTS")`.
 - Silently omitting a selected pillar or a tool failure (no coverage accounting).
 - Claiming "comprehensive" when `coverage.complete` is false.
 - Any mutation in audit mode, or automatic mutation merely because `--resolve` is present.
-- Editing a derived projection before its authority.
+- Editing a derived projection before correcting a defective authority, or changing a correct authority merely to repair its stale projection.
 - Adding a production analyzer, index/cache/database, dependency, or dedicated subagent in v1.
 
 ## Reference files

package/plugins/sp/skills/conflict-finding/references/authority-resolution.md

@@ -206,13 +206,15 @@ authority it governs:
 | Owner | Repair route | Governs (claim types) |
 |-------|--------------|----------------------|
 | Task/feature corpus | `sp:spur-cli` / `spur task` / `spur feature`; never direct file writes | Task obligation/status, feature goal and AC |
-| Numbered docs and AGENTS projections | `sp:doc-evolve`; authority first, derived projections second | Process rules, structural decision, product scope, architecture, command surface |
+| Numbered docs and AGENTS projections | `sp:doc-evolve`; inspect authority first, correct it only if defective, then repair affected projections | Process rules, structural decision, product scope, architecture, command surface |
 | Source/tests | create/use a Spur task and route through `sp:spur-dev` / build competencies | Implementation behavior, architecture mechanism |
 | Command/skill capability source | Superskill command/skill lifecycle in the owning plugin source | Command/API/schema surface |
 | Ambiguous authority | **stop** for an operator decision; do not mutate either side | (all, when unresolved) |
 
-Never edit a derived projection before its authority. The authority column of §2 is always the
-owner surface's source of truth; a projection is brought into line with it, not the reverse.
+Inspect the governing authority before repairing a derived projection. Correct the authority first
+only when it is defective and the correction is authorized; otherwise leave it unchanged and repair
+the projection. The authority column of §2 remains the owner surface's source of truth; a projection
+is brought into line with it, not the reverse.
 
 ## 7. Worked examples
 

package/plugins/sp/skills/conflict-finding/references/remediation-routing.md

@@ -113,13 +113,13 @@ between "the audit said X" and "the file now says Y."
 Each approved repair is dispatched through the artifact's **owner surface** — the harness path that
 owns writes to that artifact — not a direct file write. Authority for a repair is the same
 authority model as the audit ([./authority-resolution.md](./authority-resolution.md)): for a given
-subject + claim type, one artifact is normative; derived projections are updated only after their
-authority.
+subject + claim type, one artifact is normative. Inspect it first; correct it only if defective and
+authorized, then update affected projections. A correct authority needs no edit for a stale projection.
 
 | Owner | Repair route | Never |
 |-------|--------------|-------|
 | Task/feature corpus | `sp:spur-cli` — `spur task` / `spur feature` (with `--section`, `--from-file`, `--json` as needed) | Direct file writes to task/feature files. |
-| Numbered docs and AGENTS projections | `sp:doc-evolve` — **authority first, derived projections second** (see below) | Editing `docs/05_FEATURES.md` or an `AGENTS.md` projection before its authoritative source is fixed. |
+| Numbered docs and AGENTS projections | `sp:doc-evolve` — inspect authority first; correct it only if defective, then repair affected projections (see below) | Changing correct authority to repair a stale projection, or projecting a defective authority before its authorized correction. |
 | Source / tests | Create or use a **Spur task** and route through `sp:spur-dev` / build competencies (`sp:code-implementation`, `sp:code-testing`), **unless** the active session already has explicit implementation authority for the change. | Bare in-place edits to source/tests without a task or explicit authority. |
 | Command/skill capability source | Superskill command/skill **lifecycle** (`superskill command …` / `superskill skill …` scaffold/validate/evaluate/refine) in the owning plugin source. | Hand-editing capability source outside the Superskill lifecycle. |
 | Ambiguous authority | **Stop for an operator decision.** Do not mutate either side. | Choosing a winner, editing both sides, or forcing a global ranking. |
@@ -148,12 +148,13 @@ item; never route around it with a direct write.
 
 ### 3.2 Numbered docs and AGENTS projections
 
-Documentation repairs follow **authority first, derived projections second**. If a derived
+Documentation repairs **inspect authority first**. If a derived
 projection (`docs/04_DESIGN.md`, `docs/05_FEATURES.md`, `AGENTS.md`, templates) has drifted from its
 authority (`docs/00_ADR.md`, `docs/01_PRD.md`, `docs/03_ARCHITECTURE.md`,
-`docs/99_PROJECT_CONSTITUTION.md`), the repair fixes the **authority** first, then re-derives the
-projection via `sp:doc-evolve`. Editing a projection without its authority is a prohibited
-anti-pattern (see §6).
+`docs/99_PROJECT_CONSTITUTION.md`), leave a correct authority unchanged and repair the stale
+projection via `sp:doc-evolve`. If the authority itself is defective, correct it first within the
+approved scope, then update affected projections. Incomparable authority still requires an operator
+decision; projection drift alone never authorizes changing the governing contract (see §6).
 
 `sp:doc-evolve` owns the numbered-doc/projection lifecycle: sync checks, contract verification,
 frontmatter checks, and derived-doc refresh. A doc repair is dispatched to it; it is not hand-applied.
@@ -244,7 +245,7 @@ These are the explicit boundaries for remediation. Each is a hard violation, not
 | Anti-pattern | Why it is prohibited |
 |--------------|----------------------|
 | **Automatic mutation merely because `--resolve` is present** | `--resolve` only opens the workflow; it never authorizes automatic repair. Confirmation + freshness + owner surface are all required. |
-| **Editing a derived projection before its authority** | A projection (`docs/04`/`docs/05`, `AGENTS.md`, templates) is not the source of truth; fixing it without its authority (`ADR`/`PRD`/constitution) leaves the real conflict in place. Authority first. |
+| **Changing correct authority for projection drift** | A stale projection is repaired against its governing contract. Correct authority only when defective and authorized; then update affected projections. |
 | **Broad cleanup outside confirmed findings** | Only the artifacts named by confirmed, freshness-checked findings are touched. No opportunistic refactors or doc "improvements" while repairing. |
 | **Ambiguity silently resolved** | Ambiguous/missing authority stops for an operator decision; it is never forced through a global ranking or a guessed owner. |
 | **Partial failure silently continued** | A failed repair is reported, not papered over; siblings are not marked successful and the run does not roll forward silently. |

package/plugins/sp/skills/doc-evolve/SKILL.md

@@ -100,9 +100,10 @@ rg --files apps packages                       # real modules
 git log -1 --format='%ci' -- docs/04_DESIGN.md     # last touch vs. recent surface changes
 ```
 
-**Repair protocol (§7):** fix the authoritative statement first, then affected detail/index/entry
-files. Preserve ADR numbers, original titles/dates and decision history; editorial condensation
-follows §6.1, while actual reversals need a superseding decision. Record findings in a task/report.
+**Repair protocol (§7):** inspect the governing statement first. Correct it only if defective and
+authorized, then update affected detail/index/entry files; otherwise leave the authority unchanged
+and repair its stale projections. Preserve ADR numbers, original titles/dates and decision history;
+editorial condensation follows §6.1, while actual reversals need a superseding decision. Record findings in a task/report.
 Routine lessons go to existing learning/context storage (§8); no automatic constitution edits.
 
 Output a **drift report**: per finding, `{ doc, what code says, what the doc says, authority, repair

package/plugins/sp/skills/spur-cli/references/tasks/section-editing.md

@@ -42,13 +42,16 @@ for `Plan`, `Acceptance Criteria`, hand-authored `Solution`, and any narrative s
    spur task update 0040 --section Review --from-file /tmp/review.md
    ```
 
-3. The whole `### Review` body is now that file's contents. To amend rather than overwrite, read
-   the current body (`spur task show 0040`), edit the temp file to the full desired state, and
-   replace again — there is no append mode for ordinary sections.
+3. The whole `### Review` body is now that file's contents. To amend rather than overwrite, either
+   read the current body (`spur task show 0040`), edit the temp file to the full desired state, and
+   replace again — or pass `--append` (task 1057) to write the file's body after the existing
+   section content (existing content + one blank line + new body; surrounding whitespace trimmed; an empty/missing section is
+   created). `--append` requires `--section` and never replaces on its own.
 
 **`Q&A` is the exception.** `--section "Q&A"` APPENDS a timestamped `#### Q&A entry — <ISO>`
 block rather than replacing the section. Start the body with `<!-- qa:replace -->` to replace it
-wholesale.
+wholesale. Explicit `--append` on `Q&A` uses the generic append (no timestamped wrapper); the
+`<!-- qa:replace -->` marker still wins and forces wholesale replace.
 
 `--section` **requires** `--from-file` (exit `2` otherwise). Section names match the DD-08 headings
 exactly: `Background`, `Requirements`, `Acceptance Criteria`, `Q&A`, `Design`, `Plan`, `Solution`, `Root Cause`, `Testing`, `Review`, `References`, `History`, `Notes` (universal sections are `History`, `References`, `Notes`; `Root Cause` is carried by the `issue` template variant).

package/plugins/sp/skills/spur-cli/references/tasks/verbs.md

@@ -70,9 +70,12 @@ frontmatter scalar.
   `testing→done` `check` gates above still run; the CLI evaluates them inline when the FSM guard
   does not. `--force-done` waives the verify **verdict** only, never the section matrix.
 - **Section** (`--section` **requires** `--from-file`): writes the named section body from the file.
-  Most sections replace wholesale. Exception: `--section "Q&A"` APPENDS a timestamped
-  `#### Q&A entry — <ISO>` block; start the body with `<!-- qa:replace -->` to replace the section
-  wholesale. No inline-body flag. Section names: `Background`, `Requirements`, `Acceptance Criteria`, `Q&A`, `Design`, `Plan`, `Solution`, `Testing`, `Review`, `References`, `History`, `Notes`.
+  Most sections replace wholesale. `--append` extends instead: existing body + one blank line + the
+  file's body (task 1057; empty/missing section is created; still requires `--section`). Exception:
+  `--section "Q&A"` APPENDS a timestamped `#### Q&A entry — <ISO>` block; start the body with
+  `<!-- qa:replace -->` to replace the section wholesale (explicit `--append` on `Q&A` uses the
+  generic append, marker still wins). No inline-body flag. Section names (case-sensitive):
+  `Background`, `Requirements`, `Acceptance Criteria`, `Q&A`, `Design`, `Plan`, `Solution`, `Testing`, `Review`, `References`, `History`, `Notes`.
 - **Frontmatter** (`--feature <id>`, `--priority <p>`): sets the scalar frontmatter field on an
   existing task — the only post-create path, allow-listed to `feature_id` / `parent_wbs` / `priority`.
 - **Estimate** (`--estimate-hours <n>`): sets the `estimate_hours` frontmatter field (positive number) —
@@ -113,7 +116,7 @@ Flags: `--folder <path>`, `--json`. Exit codes: `0` success, `1` error, `2` usag
 
 ## `sections <wbs> <op> [name]`
 
-CLI-safe, matrix-enforced task section mutation. Section names are validated against canonical sections (`Background`, `Requirements`, `Acceptance Criteria`, `Q&A`, `Design`, `Plan`, `Solution`, `Root Cause`, `Testing`, `Review`, `References`, `History`, `Notes`). Universal sections (`History`, `References`, `Notes`) are always allowed; `Root Cause` is carried by the `issue` template variant. `Q&A` on `update --section` appends rather than replacing (see the Section bullet above); `<!-- qa:replace -->` forces a wholesale replace.
+CLI-safe, matrix-enforced task section mutation. Section names are validated against canonical sections (`Background`, `Requirements`, `Acceptance Criteria`, `Q&A`, `Design`, `Plan`, `Solution`, `Root Cause`, `Testing`, `Review`, `References`, `History`, `Notes`). Universal sections (`History`, `References`, `Notes`) are always allowed; `Root Cause` is carried by the `issue` template variant. `Q&A` on `update --section` appends rather than replacing (see the Section bullet above); `<!-- qa:replace -->` forces a wholesale replace. `--append` is the generic extend-after-existing path (task 1057).
 
 | Op | Usage | Description |
 | --- | --- | --- |

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

@@ -534,7 +534,8 @@ is the procedure. The backing is a combination of git CLI, `spur` CLI, and agent
      - **Coverage** — bullet count equals the commit count in `<since>..<until>`, and every short hash appears exactly once.
      - **Mapping** — per-category bullet counts match the conventional-type counts (`feat`→`Added`, `fix`→`Fixed`, other recognized types→`Changed`, unrecognized→`Other`).
      - **Header** — `[<version>] - <date>` matches the resolved `--version` (or detected tag) and the header date.
-     - **HIGH** — all three checks pass. **MEDIUM** — coverage intact but mapping or header deviates. **LOW** — coverage broken (missing/duplicate hashes) or the range cannot be reconciled against git.
+     - **Citations** — a bullet that asserts API/library behavior or a version/dependency claim beyond its commit summary carries a source citation: an official docs URL, or a local `path:line` verified against the installed manifest/lockfile (`package.json`, lockfile, or the cited file). A commit hash is provenance for what shipped, not a citation for what the API/library does; an uncited claim is flagged inline on the bullet (`(uncited: <claim>)`) rather than silently dropped.
+     - **HIGH** — all checks pass with every API/library claim cited. **MEDIUM** — coverage intact but mapping or header deviates, or at least one API/library claim lacks a source citation. **LOW** — coverage broken (missing/duplicate hashes), the range cannot be reconciled against git, or a citation fails verification (dead URL, or a `path:line` that does not support the claim).
 - **Invariants:** Never mutates `CHANGELOG.md` directly — the command surface is stdout-only; writing it to a file (e.g. appending to `CHANGELOG.md`) is the operator's redirect choice, never the command's.
 
 ### 9. gitmsg
@@ -624,25 +625,27 @@ is the procedure. The backing is a combination of git CLI, `spur` CLI, and agent
 - **Inputs:** `--scope <path>` (default: entire working tree) — limits fixes to a file or directory. `--gate-log <path>` (R3, task 0482) — before fixing, read this captured validation-run log and start at the `file:line` anchors its findings name, rather than re-deriving the failure from a fresh gate run. `--findings <anchors>` (R3, task 0482) — space-separated `file:line` anchors already extracted from that log by the `test` hop; when present these ARE the failing set, so fix them in order and do not run the gate to discover what broke.
 - **Backing:** `inline` — lint + test fix loop.
 - **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. **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.
+  1. Inspect the project's formatter command, then settle formatter-only diffs. Without `--scope`, use the project formatter (here `bun run format`). With `--scope`, use a formatter invocation whose only path operands are inside the selected scope — for Biome, `bunx biome check --write "$SCOPE"`. Never append a path to a script already containing `.`: `biome check . --write <path>` still writes across the repository. Preserve quoted paths and apply the same scope to every later formatting pass. If no scoped formatter is available, report that limitation and leave out-of-scope files untouched. Here `bun run lint` checks formatting without rewriting it and also runs typecheck; formatting errors fail that check.
+  2. Run the project's read-only lint/type check (here `bun run lint`). Collect all errors. A repository-wide check may report outside-scope errors; report them without widening the authorized fix scope.
+  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 in-scope pinned test/docs file in that sweep; report outside-scope matches without editing them. 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 — standalone invocation only (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. **Skip this step entirely when `--gate-log` is set** (see step 10) — under the pipeline nothing consumes its verdict.
+  5. **Lint fix loop:** for each in-scope error, diagnose the root cause and apply the smallest fix. **Use targeted probes to verify each fix** (`bunx tsc --noEmit` on the affected package, `bunx biome check <file>`) — do NOT re-run the full gate after every batch. Loop until lint is green, or report outside-scope blockers without editing them.
+  6. For standalone execution, run `bun run test` and collect all failures. With `--gate-log`, use its failing set and targeted tests instead of running the full suite here.
+  7. If tests are green, proceed to the applicable standalone confirmation or pipeline handoff below.
+  8. **Test fix loop:** for each in-scope failure, diagnose (test bug vs implementation bug), apply the fix, re-run the **failing test only** (`bun test <file> --test-name-pattern "<test>"`). Report outside-scope blockers without editing them. Do NOT re-run the full suite per fix — it is the dominant loop cost (task 0436 R2).
+  9. **Confirming run — standalone invocation only (at most once).** After all fixes, repeat the scope-safe formatting invocation from step 1, then run the selected validation command **at most once** to confirm (here the default project gate is `bun run spur-check`). If it passes, the hop is done. **Skip this step entirely when `--gate-log` is set** (see step 10) — under the pipeline nothing consumes its verdict.
   10. **Pipeline-awareness (R4, task 0483; confirming run dropped 2026-08-31).** `--gate-log` is set only by the pipeline's `test-fix` hop, so treat it as the pipeline signal. There, `test-recheck` runs the full `${vars.qualityGateCmd}` gate immediately after this hop returns — that is the **deciding** run, the only one that writes PASS to `.spur/run/<wbs>-test-gate.status`. A confirming run inside this hop decides nothing and costs a second full gate (~105 s here) to answer a question `test-recheck` is about to answer anyway. So under `--gate-log`: **run no full gate at all.** Your self-check is what step 8 already gives you — the failing tests you re-ran individually — plus **one `bun run lint`** (~7 s: Biome + typecheck) to catch type or lint breakage your fixes introduced. Then return and let `test-recheck` judge. `test-recheck` opens with the same cheap `${vars.gateProbeCmd}` probe, so a still-red tree is caught in seconds rather than by a full suite. Historical anti-pattern this replaces: 0482 ran the gate 3× plus a standalone `bun run test`, and `test-recheck` then ran it a 5th time.
   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:
+- **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. Here lint checks formatting and types; it does not prove that the full test gate passed. Keep every write inside `--scope`. **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 — standalone only.** At step 9, execute the following once; do not add another confirming run:
   1. Run validation command: `eval "$VALIDATION_CMD"`
   2. Capture exit code: `EXIT_CODE=$?`
   3. Output: `echo "EXIT_CODE=$EXIT_CODE"`
   4. **EXIT_CODE must equal 0**
 
-  If EXIT_CODE != 0: NOT completed. MUST continue fixing.
+  If EXIT_CODE != 0: NOT completed. Continue the bounded fix loop for in-scope failures; report outside-scope blockers.
+
+  **Pipeline exit condition (`--gate-log` set):** return the fixes and the targeted-test/lint evidence from step 10 to `test-recheck`. Do not run the standalone validation command or claim a full-gate PASS; `test-recheck` owns that verdict.
 
   **Hallucination Red Flags — STOP if you think:**
   - "The errors look fixed" — check exit code, not appearance
@@ -671,7 +674,7 @@ is the procedure. The backing is a combination of git CLI, `spur` CLI, and agent
   └─────────────────────────────────────────────────┘
   ```
 
-  The 7 phases map onto the format→lint→test behavior loop above: Phases 1–2 capture the gate, Phase 3 settles auto-fixable formatting, Phases 4–6 are the per-group root-cause fix loops, Phase 7 is the final verification re-run.
+  The 7 phases describe standalone execution: Phases 1–2 capture the gate, Phase 3 settles auto-fixable formatting within scope, Phases 4–6 are the per-group root-cause fix loops, Phase 7 is the final verification run. With `--gate-log`, use the supplied evidence instead of capturing the gate again, and hand off to `test-recheck` instead of running Phase 7's full validation.
 
 - **Fix Priority:**
 

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

@@ -530,7 +530,7 @@ pass before the invoking tree is written → WT-5. Without `--task-file` nothing
 The shapes are pinned (task 0975 R1; `record-missing` and citation behavior per 0984): idempotent on re-persist;
 success exits 0 printing
 `{"ok":true,"persisted":<n>,"skipped":[{"id":<run-id>,"reason":"id-exists"|"external-key-conflict"|"record-conflict:<file>"|"record-missing:<file>"|"cited-directory:<name>"|"cited-symlink:<name>"|"cited-non-file:<name>"}]}`
-— an `external-key-conflict` skip leaves the target run unchanged; an `id-exists` replay repairs missing owned artifacts and task links without duplicating them. A
+— an `external-key-conflict` skip leaves the target run unchanged **and fails the pass (1049)**: the delegate exits 1 printing `{"ok":false,"error":…}` naming the skipped source run ids, because that (workflow, external key) identity already belongs to a different receiving run — the batch was not persisted, so reconcile the source worktree by hand (it stays the provenance owner of record) before any teardown: auditable reconciliation names the original archived DB snapshot and the skipped source run identities, verifies the archive by file hash and by merged-commit ancestry of the source branch, and treats any residual deletion as explicit operator-authorized cleanup under the strict canonical evidence rules above. An `id-exists` replay repairs missing owned artifacts and task links without duplicating them. A
 `record-conflict:<file>` never overwrites a divergent invoking-tree record and causes the delegate to exit 1, retaining the worktree. A
 `record-missing:<file>` skip is a known `task-lifecycle`/`feature-lifecycle` row with no record file
 at all (its inserted DB row still counts in `persisted` — 0984 R5). Any failure

package/plugins/sp/skills/spur-dev/references/flag-glossary.md

@@ -17,17 +17,16 @@ patterns, skill-backed, inline) remains in `dev-operations.md`.
 
 Every flag shared by two or more commands has exactly one entry here. This is the single place a
 shared flag's meaning is stated; command argument-hints and table rows cite it and must not
-re-define it. The shared-flag set is derived mechanically from the 28 command argument-hints (a flag
+re-define it. The shared-flag set is derived mechanically from all live `dev-*` command argument-hints (a flag
 counts as shared when it appears in two or more); flags appearing on a single command stay documented
 in that command's body and are not listed here.
 
-**Reference form (mechanically detectable).** A command file points at a glossary entry with a
-markdown link whose link target is the entry's anchor — `[`--next`](#flag-next)`. The anchor is
-always `#flag-<name>` where `<name>` is the flag minus its leading `--` (so `--keep-going` →
-`#flag-keep-going`). The test gate (`command-flag-parity.test.ts`, task 0403) finds these references
-with the regex ``\[`--<flag>`\]\(#flag-`` over each command file — **a shared flag declared without
-this reference fails the build.** Prose-only citations (the flag name mentioned in a sentence but not
-in the link form) do not count; the reference must be the link.
+**Reference form (mechanically detectable).** Each `dev-*` command carries exactly one canonical
+footer link to `../skills/spur-dev/references/flag-glossary.md`, enforced by
+`scripts/commands/validate-commands.ts` (task 0412). Per-flag deep links are not required.
+`command-flag-parity.test.ts` derives shared flags from all live hints and requires exactly one
+canonical glossary entry per shared flag. Each entry retains its `#flag-<name>` anchor, where
+`<name>` is the flag minus its leading `--` (so `--keep-going` → `#flag-keep-going`), for navigation.
 
 **Availability rule.** Two flags are only declared where the underlying capability already exists:
 `--json` where the command already produces a structured result a script could consume; `--auto`

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

@@ -75,6 +75,9 @@ the human/native presentation layer — labels are display addresses only, never
 2. Allocate a collision-resistant inline run id (`uuidgen`, with a timestamp/pid fallback), create
    `.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`.
+   The run id lives in those two files and the persisted run row — never stage it in an ad-hoc
+   `*.env` file: the `no-env-files` gate rule flags any `.env` name, so run-scoped staging files
+   use `<run-id>-*` names with `.md`/`.json`/`.txt`/`.status` extensions only.
 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):