@gobing-ai/spur 0.3.97 → 0.3.99

package/plugins/sp/scripts/task-diffstat.mjs

@@ -3,7 +3,7 @@
 
 // plugins/sp/scripts/task-diffstat.ts
 import { spawnSync } from "child_process";
-import { mkdirSync, readFileSync, writeFileSync } from "fs";
+import { fstatSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "fs";
 import { join } from "path";
 
 // plugins/sp/lib/env.ts
@@ -85,10 +85,14 @@ function runDiffstat(env, options = {}, git = defaultGitRunner(options.cwd)) {
     process.stderr.write(`task-diffstat: ${reason} \u2014 failing safe (sensitive)
 `);
     const row2 = { files: 0, insertions: 0, deletions: 0, paths: [], sensitive: true };
-    writeFileSync(abs(relResult), `${JSON.stringify(row2)}
-`);
+    writeArtifact(abs(relResult), row2);
     return { ...row2, resultFile: relResult, exitCode: 0 };
   };
+  let stdoutIsArtifact = false;
+  try {
+    const [out, art] = [fstatSync(1), statSync(abs(relResult))];
+    stdoutIsArtifact = out.dev === art.dev && out.ino === art.ino;
+  } catch {}
   let base = "";
   try {
     base = readFileSync(abs(join(relRun, `${wbs}-base.sha`)), "utf8").trim();
@@ -125,9 +129,17 @@ function runDiffstat(env, options = {}, git = defaultGitRunner(options.cwd)) {
   const all = [...paths].filter((p) => p.length > 0).sort();
   const sensitive = all.some((p) => sensitiveReasonForPath(p) !== null);
   const row = { files: all.length, insertions, deletions, paths: all, sensitive };
-  writeFileSync(abs(relResult), `${JSON.stringify(row)}
+  writeArtifact(abs(relResult), row);
+  if (stdoutIsArtifact)
+    process.stderr.write(`task-diffstat: stdout redirected onto the artifact \u2014 kept; redirect stdout elsewhere
+`);
+  return { ...row, resultFile: relResult, exitCode: stdoutIsArtifact ? 1 : 0 };
+}
+function writeArtifact(absPath, row) {
+  const tmp = `${absPath}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(row)}
 `);
-  return { ...row, resultFile: relResult, exitCode: 0 };
+  renameSync(tmp, absPath);
 }
 var TASK_DIFFSTAT_USAGE = "usage: task-diffstat  (env: wbs)";
 function main(argv, env = getEnvVars(), options = {}) {

package/plugins/sp/scripts/task-diffstat.ts

@@ -19,13 +19,17 @@
  * other probe problem writes `sensitive: true` (and exits 0) so the lane degrades to
  * safety, never to fast.
  *
+ * The artifact is written atomically (tmp + rename), so redirecting stdout onto the artifact path
+ * cannot corrupt it — the rename swaps in the real JSON after the shell's redirect truncates the
+ * old inode (1067 R3); that redirect is still refused with a nonzero exit. Normal output is silent.
+ *
  * Node-builtin imports only; the git lookup is a spawnable `GitRunner` so tests can fake
  * it; `main(argv, env, options)` is the same injection point the workflow wrapper and its
  * node twin exercise. Only an empty `wbs` (mis-invocation) exits nonzero.
  */
 
 import { spawnSync } from 'node:child_process';
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { fstatSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { getEnvVars } from '../lib/env';
 
@@ -166,10 +170,18 @@ export function runDiffstat(
     const failSafe = (reason: string): DiffstatResult => {
         process.stderr.write(`task-diffstat: ${reason} — failing safe (sensitive)\n`);
         const row: Diffstat = { files: 0, insertions: 0, deletions: 0, paths: [], sensitive: true };
-        writeFileSync(abs(relResult), `${JSON.stringify(row)}\n`);
+        writeArtifact(abs(relResult), row);
         return { ...row, resultFile: relResult, exitCode: 0 };
     };
 
+    let stdoutIsArtifact = false; // 1067 R3: stdout redirected onto the artifact itself clobbered it once
+    try {
+        const [out, art] = [fstatSync(1), statSync(abs(relResult))];
+        stdoutIsArtifact = out.dev === art.dev && out.ino === art.ino;
+    } catch {
+        /* artifact absent or stdout not a regular file — nothing to compare */
+    }
+
     let base = '';
     try {
         base = readFileSync(abs(join(relRun, `${wbs}-base.sha`)), 'utf8').trim();
@@ -203,8 +215,17 @@ export function runDiffstat(
     const all = [...paths].filter((p) => p.length > 0).sort();
     const sensitive = all.some((p) => sensitiveReasonForPath(p) !== null);
     const row: Diffstat = { files: all.length, insertions, deletions, paths: all, sensitive };
-    writeFileSync(abs(relResult), `${JSON.stringify(row)}\n`);
-    return { ...row, resultFile: relResult, exitCode: 0 };
+    writeArtifact(abs(relResult), row);
+    if (stdoutIsArtifact)
+        process.stderr.write('task-diffstat: stdout redirected onto the artifact — kept; redirect stdout elsewhere\n');
+    return { ...row, resultFile: relResult, exitCode: stdoutIsArtifact ? 1 : 0 };
+}
+
+/** Atomic artifact write (tmp + rename): a stdout redirect onto the path cannot interleave (1067 R3). */
+function writeArtifact(absPath: string, row: Diffstat): void {
+    const tmp = `${absPath}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(row)}\n`);
+    renameSync(tmp, absPath);
 }
 
 export const TASK_DIFFSTAT_USAGE = 'usage: task-diffstat  (env: wbs)';

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/code-verification/SKILL.md

@@ -336,6 +336,7 @@ Verdict: PASS    (or PARTIAL / FAIL)
 
 ```markdown
 Verdict: PASS
+Confidence: HIGH
 
 ### Per-Requirement Traceability
 | Req | Status | Evidence |
@@ -354,6 +355,8 @@ Verdict: PASS
 ```
 
 The per-requirement traceability table MUST use `| Req | Status | Evidence |` (exactly this header, no `R#`/`R`/`Requirement` variant — `Status` in column 2 — and no extra columns between Req and Status). The Acceptance Criteria table MUST use `| AC | Status | Evidence Type | Evidence |`.
+The answer MUST carry exactly one `Confidence: HIGH|MEDIUM|LOW` line (task 1068): the verifier's stated confidence in the verdict — HIGH = fresh executable evidence + re-read anchors this run; MEDIUM = partial reliance on prior evidence, external/delegated outcomes, or an unstable tree; LOW = key evidence not re-executed. A missing or out-of-vocabulary line fails lint (`confidence-missing` / `confidence-value`) and blocks derivation; the value lands in the verdict artifact's `confidence` field and the recorded `## Testing` section.
+The answer MUST cite a source for external API/library claims in Requirement/AC evidence cells: a cell asserting a scoped-package (`@scope/name`), `node_modules/`, semver-version (`x.y.z`), or backticked function-call (`` `name(args)` ``) claim is rejected with `evidence-citation` unless the SAME cell carries a citation — a repo `path:line(-end)` (backticked or bare), the external named-origin form (@origin `path` line N), or a URL. Cross-cell references ("receipt above") do not count; marker-free receipts ("bun test 398 pass / 0 fail") need no citation.
 **MUST NOT:** place a `Severity` column between `Req` and `Status` in the authoring contract.
 The parser is tolerant of these variants (defense-in-depth), but the authoring contract is
 canonical.

package/plugins/sp/skills/code-verification/references/verdict-schema.md

@@ -115,7 +115,9 @@ AC ids that do not resolve to one accepted identity — a task AC checklist labe
 (exact/bare title, `Scenario:` prefix, bracket tags, `AC-N`); paraphrases and ambiguous aliases
 fail — invalid status (`MET | PARTIAL | UNMET` for requirements;
 `N/A` additionally allowed for AC), invalid evidence type (`test | command | static-ref |
-manual-review | llm-judge | n/a`, or a `+` compound), and empty evidence. Interrupted runs keep the
+manual-review | llm-judge | n/a`, or a `+` compound), and empty evidence. Evidence cells that assert an
+external API/library claim without a same-cell citation are rejected with `evidence-citation` (see
+"Source citations for external claims" below). Interrupted runs keep the
 rows that pass the lint and complete only the missing IDs on retry.
 
 **Feature-credited AC ids are narrower than the lint's accepted set (task 0966 finding).** A row keyed
@@ -136,6 +138,20 @@ the run actually verified. Since 0804 R9 the checker ignores complete parsed cit
 scanning for subjects, so a citation's filename (including snake_case paths) can never become a
 false subject — a real absent symbol, nonexistent file, or invalid range still reports.
 
+## Source citations for external claims (task 1070)
+
+A Requirement/AC evidence cell that asserts an external API/library claim must carry a verifiable
+citation in the SAME cell, or lint rejects the row with `evidence-citation` (blocking derivation).
+
+- Claim markers (closed set): a scoped-package mention (`@scope/name`), a `node_modules/` reference,
+  a semver version claim (`x.y.z`), or a backticked function-call-shaped token (`` `name(args)` ``).
+- Accepted citation forms (any one clears the cell): a repo `path:line(-end)` (backticked or bare),
+  the external named-origin form (@origin `path` line N — line number outside the backticks), or an
+  http(s) URL.
+- The rule is cell-local: a citation in another row or a "receipt above" cross-reference does not
+  satisfy it. Marker-free receipts (test counts, reviewed-log notes) need no citation. The check is
+  presence-only — which citation proves which claim is not deterministically decidable.
+
 ## Checks evidence
 
 Wave C verification can emit the following additive `checks[]` rows:

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/ac-style-guide.md

@@ -30,10 +30,28 @@ Rules:
 ## Task-side numbering (`AC<n>`)
 
 `R<n>` is the **feature** scenario key and the **task Requirements** key. Task `### Acceptance
-Criteria` items therefore use their own namespace: `- [ ] AC1 — <title>` or `Scenario: AC1 — <title>`,
-numbered task-locally. Carry a feature scenario by copying its title after the prefix (`normalizeTitle`
-strips both `AC<n>` and `R<n>`, so DD-09 matching is unaffected); bind a task requirement with
-`(req: R<n>)`. Legacy tasks that wrote `- [ ] R<n> —` / `Scenario: R<n> —` keep working unchanged.
+Criteria` items therefore use their own namespace: `AC1, AC2, …`. Two frontmatter fields split the
+gate work, and neither implies the other:
+
+- **`ac_altitude`** owns the **feature subset** (DD-09). `graduating` (or absent) keeps
+  normalized-title matching against the linked feature (`normalizeTitle` strips both `AC<n>` and
+  `R<n>` prefixes, so copied titles match); `task-local` skips that check — and nothing else.
+- **`ac_numbering: task-local`** owns **task requirement bindings**. It opts the AC section into the
+  `L3.ac-requirement-coverage` loop, which reads **`Scenario:` titles only**: bind requirements with
+  `(req: R1; R2)` in the title, or ship a legacy `Scenario: R1 — …` title, which still binds by its
+  own prefix.
+
+**Preferred task-local form** (regression/fix tasks): `Scenario: AC1 — <concrete outcome> (req: R1)`
+with Given/When/Then, declaring **both** `ac_altitude: task-local` and `ac_numbering: task-local`.
+
+Parsed checkbox rows (`- [ ] AC1 — <title>`) are a supported form: they join checklist parsing, the
+feature-subset match, and the terminal-status unchecked-box count — but they do **not** enter the
+Scenario-only requirement-binding loop, so a checkbox row never substitutes for a `(req: …)` binding.
+
+Raw freeform bullets (`- AC1 — …`: no checkbox, no `Scenario:`) parse as nothing — no subset match,
+no requirement binding, no box counting. They survive in the corpus as **legacy unparsed records**:
+read them, don't author them, and don't reach for them to dodge traceability. Completed tasks keep
+their records; new work uses one of the two parsed forms above.
 
 ## Two AC tiers (authoring convention)
 
@@ -145,9 +163,11 @@ The `spur task verdict` answer lint declares the bold span of a single-line crit
 (`- **AC2 — The roster runtime is gone (R3).** Given …, when …, then …`) and its head before the
 first ` — ` or `:` — so answer rows may key `AC2` or `AC2 — The roster runtime is gone (R3).`. Keep
 at least one answer row keyed to the verbatim feature scenario title the task graduates, and keep
-requirement ids in the corpus form they are checked against (`- **R1** — …`): `L3.requirements-format`
-matches `R\d+` followed by a space, so a colon after the bold span silently drops the whole section
-to a warning.
+requirement ids in the template-taught corpus form, `- [ ] R1. <text>`: that (or an unbolded `R1.`
+variant) is what the task-local binding loop parses — bold wrapping (`**R1**`) passes the
+`L3.requirements-format` ratio but binds nothing — and a colon after the bold span still silently
+drops the whole section to a warning. Bold AC heads are likewise a verdict-table id form, not the AC
+authoring form: author new AC rows in the plain `- [ ] AC1 —` / `Scenario: AC1 —` shapes.
 
 ### The id is exactly the scenario title — no Gherkin body appended
 
@@ -276,3 +296,16 @@ Use `task-local` for a fix/refactor task whose regression criteria are not the f
 contract. Keep a `graduating` task's scenario titles identical to the feature's so DD-09 stays
 satisfied. Absent-altitude is `graduating` — set `task-local` explicitly only where the subset rule
 truly does not apply (do not silently default new tasks to it).
+
+### Choosing an AC form (decision table)
+
+| Task situation | Author AC as | Frontmatter | Gate effect |
+| --- | --- | --- | --- |
+| Criteria that graduate the feature's ship contract | `Scenario: AC1 — <feature scenario title>` | `ac_altitude: graduating` (or absent) | DD-09 subset enforced — drifted titles report `L4.uncovered-task-scenario`; `(req: …)` binding only when `ac_numbering: task-local` is also declared |
+| Task-local regression/fix criteria | `Scenario: AC1 — <concrete outcome> (req: R1)` + Given/When/Then | `ac_altitude: task-local` + `ac_numbering: task-local` | subset skipped; every `- [ ] R<n>.` requirement must be bound by some scenario's `(req: …)` |
+| Simple verifiable checklist rows | `- [ ] AC1 — <title>` | either altitude, per the rows above | joins checklist parsing and the subset match; **no** requirement binding (`Scenario:`-only) |
+| Legacy raw bullets | `- AC1 …` (no checkbox, no `Scenario:`) | n/a | unparsed: invisible to subset, binding, and box checks — preserve in place, never author new |
+
+`task-local` altitude skips only the feature-subset check. It does not waive the unchecked-box check,
+required sections, the proof-bound verdict, line anchors, or any other done check — AC syntax alone,
+at any altitude, never makes a task done.

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:**