@gobing-ai/spur 0.3.47 → 0.3.49

package/plugins/sp/scripts/task-size-precheck.ts

@@ -26,6 +26,8 @@
 import { execFileSync } from 'node:child_process';
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { STAGE_FLOOR_TIER, TIER_ORDER } from './stage-registry-adapter';
 
 // ─── Regex (sync with packages/app/src/services/task-size-precheck.ts) ───────
 
@@ -44,8 +46,17 @@ const CHECKLIST_ITEM_RE = /^\s*-\s*\[[ xX]\]/m;
 const LARGE_TASK_REQS = 5;
 const LARGE_TASK_PLAN_ITEMS = 8;
 
-/** Capability tiers strong enough for a large task. Anything else blocks. */
-const CAPABLE_TIERS = new Set(['capable-1', 'capable-2', 'capable-3']);
+/**
+ * Capability tiers strong enough for a large task (R3, task 0487). The floor is
+ * the `review` stage's Layer-1 tier — `reviewer` per `references/roles.md`,
+ * read via the stage-registry adapter (0538 R4: no tier literal here; roles.md
+ * is the pointer). Tiers at or above the floor pass. An unreachable roles.md
+ * degrades to the pre-reconcile band — fail-closed for a safety gate.
+ */
+const CAPABLE_TIERS: ReadonlySet<string> = (() => {
+    const floor = STAGE_FLOOR_TIER.get('review') ?? 'capable-1';
+    return new Set(TIER_ORDER.slice(Math.max(0, TIER_ORDER.indexOf(floor))));
+})();
 
 // ─── CLI ─────────────────────────────────────────────────────────────────────
 
@@ -56,6 +67,21 @@ function usage(): never {
     process.exit(1);
 }
 
+/**
+ * Resolve the spur CLI command in a monorepo-safe way:
+ * --spur-bin > SPUR_BIN > monorepo-local CLI entry > PATH `spur`.
+ * The plugin's own CI always passes an explicit --spur-bin; this fallback chain
+ * keeps ad-hoc invocations from silently hitting a stale PATH install.
+ */
+function defaultSpurBin(): string {
+    if (process.env.SPUR_BIN) return process.env.SPUR_BIN;
+    // scripts/ -> plugins/sp/ -> <repo>/apps/cli/src/index.ts (fileURLToPath — raw pathname breaks
+    // on %-encoded paths, e.g. spaces in the checkout directory)
+    const local = fileURLToPath(new URL('../../../apps/cli/src/index.ts', import.meta.url));
+    if (existsSync(local)) return `bun ${local}`;
+    return 'spur';
+}
+
 function parseArgs(argv: string[]): {
     wbs: string;
     spurBin: string;
@@ -63,7 +89,7 @@ function parseArgs(argv: string[]): {
     maxPlanItems: number;
     executor: string;
 } {
-    let spurBin = process.env.SPUR_BIN ?? 'spur';
+    let spurBin = defaultSpurBin();
     let wbs = '';
     let maxReqs = Number(process.env.MAX_IMPLEMENT_REQS) || 5;
     let maxPlanItems = Number(process.env.MAX_IMPLEMENT_PLAN_ITEMS) || 8;
@@ -73,7 +99,7 @@ function parseArgs(argv: string[]): {
     while (i < argv.length) {
         const arg = argv[i];
         if (arg === '--spur-bin') {
-            spurBin = argv[i + 1] ?? 'spur';
+            spurBin = argv[i + 1] ?? defaultSpurBin();
             i += 2;
         } else if (arg === '--max-reqs') {
             maxReqs = Number(argv[i + 1]) || 5;

package/plugins/sp/scripts/transition-shim-check.ts

@@ -0,0 +1,238 @@
+#!/usr/bin/env bun
+/**
+ * transition-shim-check — two-sided gate over `config/transition-shims.json`
+ * (task 0541, feature B2).
+ *
+ * A transition shim is a compatibility path that must survive the agent-role
+ * transition. Every shim carries a source marker comment `@transition-shim(<id>)`
+ * so it is a grep target and a review signal, and a manifest entry in
+ * `config/transition-shims.json` records who owns it and when it can be removed.
+ *
+ * The gate is deliberately two-sided, matching `config/corpus-baseline.json`
+ * semantics (corpus-check.ts): a marker with no manifest entry FAILS, and a
+ * manifest entry whose marker no longer appears in source FAILS. Without the
+ * second half the manifest would rot into a permanent suppression list — the
+ * exact invisible-debt pattern this gate exists to end.
+ *
+ * Marker convention (docs/04_DESIGN.md §2.5):
+ *   // @transition-shim(<id>) — <one line on what this keeps working>
+ *   <id> matches ^[a-z0-9][a-z0-9-]*$ (lowercase kebab).
+ * Markers live in production source roots (apps, packages, plugins, config,
+ * scripts, tooling). Docs and test fixtures are not scanned — prose examples
+ * and gate-fixture marker text must not trip the gate.
+ *
+ * The manifest is the removal worklist: emptying it is the definition of the
+ * transition being complete (R4).
+ *
+ * Ships with the plugin to arbitrary projects, so it stays node-builtin-only —
+ * no workspace imports.
+ *
+ * Usage:
+ *   bun plugins/sp/scripts/transition-shim-check.ts
+ *     [--manifest <path>]           default: config/transition-shims.json
+ *     [--roots <a,b,c>]             default: apps,packages,plugins,config,scripts,tooling
+ *
+ * Exit code: 0 when every manifest entry is present in source and every source
+ * marker is registered; 1 on any violation (unregistered marker, stale entry,
+ * or incomplete entry). Violations are printed to stderr; a summary to stdout.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+
+const MARKER_RE = /@transition-shim\(\s*([a-z0-9][a-z0-9-]*)\s*\)/g;
+const ID_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+/** Directories never scanned for markers (build output, vendored, VCS internals).
+ * `tests`/`test` are excluded too: a test fixture that mentions a marker id is
+ * data exercising the gate, not a compatibility path — shims live in production
+ * source, and only there do they need tracking. */
+const SKIP_DIRS = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'coverage',
+    '.spur',
+    'build',
+    '.next',
+    '.venv',
+    '__pycache__',
+    'vendors',
+    '_legacy_reference',
+    'artifacts',
+    'tests',
+    'test',
+]);
+
+const DEFAULT_ROOTS = ['apps', 'packages', 'plugins', 'config', 'scripts', 'tooling'];
+
+/** One manifest record — every field is required (R1). */
+interface ManifestEntry {
+    id: string;
+    wbs: string;
+    file: string;
+    keepsWorking: string;
+    removalCondition: string;
+}
+
+interface Violation {
+    kind: 'unregistered' | 'stale' | 'incomplete';
+    id: string;
+    message: string;
+}
+
+function parseArgs(argv: string[]): { manifest: string; roots: string[]; cwd: string } {
+    let manifest = 'config/transition-shims.json';
+    let roots = DEFAULT_ROOTS;
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--manifest') manifest = argv[++i] ?? manifest;
+        else if (argv[i] === '--roots') roots = (argv[++i] ?? '').split(',').filter(Boolean);
+    }
+    return { manifest, roots, cwd: process.cwd() };
+}
+
+/** Walk a root and return marker id -> repo-relative files. */
+function scanMarkers(cwd: string, roots: string[]): Map<string, Set<string>> {
+    const found = new Map<string, Set<string>>();
+    const walk = (dir: string): void => {
+        let entries: string[];
+        try {
+            entries = readdirSync(dir);
+        } catch {
+            return; // unreadable or missing root — skip
+        }
+        for (const name of entries) {
+            if (SKIP_DIRS.has(name)) continue;
+            const abs = join(dir, name);
+            let st: ReturnType<typeof statSync>;
+            try {
+                st = statSync(abs);
+            } catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                walk(abs);
+                continue;
+            }
+            if (!st.isFile()) continue;
+            let text: string;
+            try {
+                text = readFileSync(abs, 'utf8');
+            } catch {
+                continue; // binary or unreadable — markers are text only
+            }
+            for (const m of text.matchAll(MARKER_RE)) {
+                const id = m[1] as string;
+                const file = relative(cwd, abs);
+                const set = found.get(id) ?? new Set<string>();
+                set.add(file);
+                found.set(id, set);
+            }
+        }
+    };
+    for (const root of roots) walk(resolve(cwd, root));
+    return found;
+}
+
+/** Load the manifest; a missing file degrades to no entries (corpus-check parity). */
+function loadManifest(path: string): { entries: ManifestEntry[]; raw: string | null } {
+    if (!existsSync(path)) return { entries: [], raw: null };
+    const raw = readFileSync(path, 'utf8');
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(raw);
+    } catch (error) {
+        return { entries: [], raw: `malformed JSON at ${path}: ${String(error)}` };
+    }
+    const entries = (parsed as { entries?: unknown[] }).entries;
+    if (!Array.isArray(entries)) return { entries: [], raw: `${path}: missing "entries" array` };
+    return { entries: entries as ManifestEntry[], raw: null };
+}
+
+function validateEntry(e: ManifestEntry, violations: Violation[]): void {
+    const field = (key: keyof ManifestEntry, value: unknown, why: string): void => {
+        if (typeof value !== 'string' || value.trim() === '') {
+            violations.push({
+                kind: 'incomplete',
+                id: typeof e.id === 'string' ? e.id : '<missing>',
+                message: `manifest entry ${JSON.stringify(e.id ?? null)} is missing required field "${key}"${why}`,
+            });
+        }
+    };
+    field('id', e.id, '');
+    field('wbs', e.wbs, ` in entry ${JSON.stringify(e.id ?? null)}`);
+    field('file', e.file, ` in entry ${JSON.stringify(e.id ?? null)}`);
+    field('keepsWorking', e.keepsWorking, ` in entry ${JSON.stringify(e.id ?? null)}`);
+    field('removalCondition', e.removalCondition, ` in entry ${JSON.stringify(e.id ?? null)}`);
+    if (typeof e.id === 'string' && e.id !== '' && !ID_RE.test(e.id)) {
+        violations.push({
+            kind: 'incomplete',
+            id: e.id,
+            message: `manifest entry id ${JSON.stringify(e.id)} is not lowercase-kebab (^[a-z0-9][a-z0-9-]*$)`,
+        });
+    }
+}
+
+function run(): number {
+    const { manifest, roots, cwd } = parseArgs(process.argv.slice(2));
+    const manifestPath = resolve(cwd, manifest);
+    const { entries, raw } = loadManifest(manifestPath);
+    const violations: Violation[] = [];
+    const incomplete = new Set<string>();
+
+    if (raw !== null) {
+        violations.push({ kind: 'incomplete', id: '<manifest>', message: raw });
+        // A manifest that cannot be parsed has no valid entries to compare against.
+        for (const v of violations) console.error(`transition-shim-check: FAIL - ${v.message}`);
+        console.error('transition-shim-check: FAIL - manifest unreadable; refusing to pass');
+        return 1;
+    }
+
+    for (const e of entries) {
+        const before = violations.length;
+        validateEntry(e, violations);
+        if (violations.length > before) incomplete.add(String(e.id));
+    }
+
+    const markers = scanMarkers(cwd, roots);
+    const observedIds = new Set(markers.keys());
+    const manifestIds = new Set(entries.filter((e) => !incomplete.has(String(e.id))).map((e) => e.id));
+
+    for (const [id, files] of markers) {
+        if (manifestIds.has(id)) continue;
+        const file = [...files].sort().join(', ');
+        violations.push({
+            kind: 'unregistered',
+            id,
+            message: `new unregistered shim @transition-shim(${id}) in ${file} — add an entry to ${manifest} or remove the marker`,
+        });
+    }
+    for (const e of entries) {
+        if (incomplete.has(e.id)) continue;
+        if (observedIds.has(e.id)) continue;
+        violations.push({
+            kind: 'stale',
+            id: e.id,
+            message: `stale manifest entry ${e.id} (wbs ${e.wbs}) — @transition-shim(${e.id}) no longer appears in source; remove the entry, its removal condition was: ${e.removalCondition}`,
+        });
+    }
+
+    const unregistered = violations.filter((v) => v.kind === 'unregistered');
+    const stale = violations.filter((v) => v.kind === 'stale');
+    const incompleteCount = violations.filter((v) => v.kind === 'incomplete').length;
+    const ok = violations.length === 0;
+
+    const noun = entries.length === 1 ? 'entry' : 'entries';
+    console.log(
+        `transition-shim-check: ${markers.size} marker(s) observed, ${entries.length} manifest ${noun} baselined, ` +
+            `${unregistered.length} new, ${stale.length} stale, ${incompleteCount} incomplete — ${ok ? 'PASS' : 'FAIL'}`,
+    );
+    if (ok) return 0;
+
+    for (const v of violations) {
+        console.error(`transition-shim-check: ${v.kind === 'incomplete' ? 'FAIL' : `FAIL (${v.kind})`} - ${v.message}`);
+    }
+    return 1;
+}
+
+process.exit(run());

package/plugins/sp/scripts/validate-commands.ts

@@ -8,7 +8,8 @@
  *
  * Gates:
  *  (a) heading whitelist — H1 title + the per-contract ordered section headings
- *  (b) frontmatter schema — description, argument-hint, allowed-tools; dev-only extras
+ *  (b) frontmatter schema — description, argument-hint, allowed-tools; dev-only extras;
+ *      real-YAML re-parse so malformed blocks cannot ship an empty description
  *  (c) target resolution — sp:<skill> refs, workflow files, procedure anchors
  *  (d) allowed-tools coherence — Skill present iff body contains Skill() call
  *  (e) dev-command argument contract — syntax-only hint, Argument Flags table columns,
@@ -19,6 +20,7 @@
 
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
+import { parse as parseYaml } from 'yaml';
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -53,6 +55,8 @@ interface ParsedCommand {
     readonly description: string | undefined;
     readonly argumentHint: string | undefined;
     readonly allowedTools: string[] | undefined;
+    /** Set when the frontmatter fails a real YAML parse or yields an empty description. */
+    readonly frontmatterYamlProblem: string | undefined;
     readonly body: string;
 }
 
@@ -68,6 +72,30 @@ function parseCommand(filePath: string, name: string): ParsedCommand {
     const argumentHint = extractYamlField(fm, 'argument-hint');
     const allowedTools = extractYamlList(fm, 'allowed-tools');
 
+    // The regex extractions above feed the per-field gates, but they cannot see
+    // malformed YAML: `description: >-` followed by unindented keys reads as a
+    // present description to the regex while a real YAML parser folds the next
+    // keys into the block scalar — the bug that shipped an empty description to
+    // superskill install for dev-feature-change. Gate (b) re-checks with a real
+    // parse so that class cannot regress.
+    let frontmatterYamlProblem: string | undefined;
+    if (fm.trim() !== '') {
+        try {
+            const parsed: unknown = parseYaml(fm);
+            if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                frontmatterYamlProblem = 'frontmatter is not a YAML mapping';
+            } else {
+                const parsedDescription = (parsed as Record<string, unknown>).description;
+                if (typeof parsedDescription !== 'string' || parsedDescription.trim() === '') {
+                    frontmatterYamlProblem = 'frontmatter description is empty after YAML parsing';
+                }
+            }
+        } catch (error) {
+            const detail = error instanceof Error ? error.message.split('\n')[0] : String(error);
+            frontmatterYamlProblem = `frontmatter is not valid YAML: ${detail}`;
+        }
+    }
+
     const lines = body.split('\n');
     const title = lines[0]?.startsWith('# ') ? lines[0].slice(2).trim() : '';
 
@@ -90,7 +118,7 @@ function parseCommand(filePath: string, name: string): ParsedCommand {
         }
     }
 
-    return { name, title, headings, description, argumentHint, allowedTools, body };
+    return { name, title, headings, description, argumentHint, allowedTools, frontmatterYamlProblem, body };
 }
 
 /** Extract a plain YAML string field (handles quoted and unquoted). */
@@ -212,6 +240,9 @@ function checkHeadingWhitelist(cmd: ParsedCommand): readonly Violation[] {
 
 function checkFrontmatterSchema(cmd: ParsedCommand): readonly Violation[] {
     const violations: Violation[] = [];
+    if (cmd.frontmatterYamlProblem) {
+        violations.push({ command: cmd.name, gate: 'b', message: cmd.frontmatterYamlProblem });
+    }
     if (!cmd.description) {
         violations.push({ command: cmd.name, gate: 'b', message: 'missing frontmatter description' });
     }

package/plugins/sp/scripts/validate-flag-contracts.ts

@@ -406,10 +406,13 @@ export function extractTriggerTable(crossCuttingRaw: string): string[] | null {
 function adrAgentClaims(adrRaw: string): Map<string, SurfaceBehavior> | null {
     if (adrRaw.includes('## ADR-047')) {
         const out = new Map<string, SurfaceBehavior>();
+        // G5 amendment (feature G5 / task 0565): explicit inline is host-session-only — headless
+        // surfaces reject it with the stable special error; 0508 native-subagent eligibility
+        // applies to omitted --agent only, never explicit inline.
         out.set('inline', {
-            surfaces: new Set(['inline', 'subprocess']),
+            surfaces: new Set(['inline']),
             conditional: false,
-            defaultWhenOmitted: true,
+            defaultWhenOmitted: false,
         });
         out.set('auto', { surfaces: new Set(['subprocess']), conditional: false });
         out.set('<name>', { surfaces: new Set(['inline', 'subprocess']), conditional: true });

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

@@ -89,6 +89,14 @@ only burns wall clock and context budget.
   `bun test <file> --test-name-pattern "<test>"`, or `bunx tsc --noEmit` on a single package.
 - **NEVER run** `bun run test`, `bun run spur-check`, `bun run check`, or any other full-suite /
   project-gate command from inside implement. These belong to the pipeline's `test` hop.
+- **Full-suite budget: at most 2 per task** (task 0436 R2) — counted across the whole task run
+  (implement probes + the pipeline `test` hop + verify/recheck), not per step. When a check fails,
+  run the narrow target (`bun test <file> --test-name-pattern <test>`) to green before any full
+  suite; reach for the second full run only when the narrow target cannot reproduce the failure.
+- **Consolidate dogfood runs**: one combined real-data execution that exercises all scenarios,
+  not N near-identical `--dry-run`/real invocations of the same script. If you find yourself
+  rerunning the same dogfood command with one flag changed, stop and fold the variants into a
+  single run — repeated identical commands are loop-detector findings and pure cost.
 - If a targeted probe reveals a failure you cannot fix within implement scope, note it in
   `## Solution` and let the `test` hop's fixall handle it — do not pre-empt the gate.
 
@@ -146,7 +154,7 @@ reproduce → isolate → minimal fix → regression guard.
 ## Common Rationalizations
 
 | Rationalization | Reality |
-|---|---|
+| --- | --- |
 | "The spec is clear — I don't need to read the callers." | Code that looks orthogonal is how regressions ship (R5). Read the exports you touch and their immediate callers before writing. |
 | "I'll add the tests in a follow-up." | Untested production code is unverified code. The task's test step is not optional; behavior ships with its test. |
 | "This abstraction will be useful later." | Speculative abstraction is complexity without a caller (R2). Build for the requirement in front of you; add the seam when the second use arrives. |

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

@@ -239,6 +239,11 @@ printf '...' > /tmp/<wbs>-testing.md
 spur task update <wbs> --section Testing --from-file /tmp/<wbs>-testing.md
 ```
 
+> **Corrections: the answer file is the source of truth.** `spur task record` re-transcribes
+> `## Testing` from the verdict artifact, overwriting `--section Testing` writes — direct section
+> fixes are futile. Fix `.spur/run/<wbs>-verify-answer.txt` → `spur task verdict <wbs>
+> --from-answer <file>` → re-record. `--section` is initial authorship only.
+
 > **Do not write `## Review` directly in verify mode.** The `## Review` section is owned by the
 > `review` step (`/sp:dev-review`), which dispatches `functional-review` + `code-verification`
 > review mode + `code-improvement`. The `record` step backfills `## Review` from the verdict
@@ -283,9 +288,7 @@ Verdict: PASS
 | P4 | — | — | No P1–P3 findings; verify verdict PASS |
 ```
 
-The per-requirement traceability table MUST use `| Req | Status | Evidence |` (exactly this header, no `R#`/`R`/`Requirement` variant, and no extra columns between Req and Status). The Acceptance Criteria table MUST use `| AC | Status | Evidence Type | Evidence |`.
-
-**MUST NOT:** use `| R# | ... |` as the sole id header without `Status` in column 2.
+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 |`.
 **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.
@@ -348,8 +351,7 @@ mutation is discoverable from the tracked task file alone, without diffing untra
 ### Step 13 — Shippable readiness gate (feature-level)
 
 Per-task PASS is **not** the same as “this feature is ready to ship.” After Steps 11–12, when the
-gate is **active**, evaluate feature AC satisfaction via the existing CLI (do not invent a second
-framework).
+gate is **active**, evaluate feature AC satisfaction via the existing CLI.
 
 **When active**
 
@@ -371,16 +373,17 @@ framework).
    `docs/.spur/run` or other nested `.spur` trees). Ephemeral scratch may use `/tmp` or
    `/private/tmp`. Requirement / AC row `id`s in the verdict MUST match feature scenario titles
    (or `AC-N` aliases) so satisfaction can mark MET.
-2. Run:
+2. Run (0568 R6 monorepo-safe: SPUR_BIN env > local CLI > PATH):
 
    ```bash
-   spur feature check <featureId> --json
-   spur task list --feature <featureId> --json
+   SPUR_BIN="${SPUR_BIN:-$([ -f apps/cli/src/index.ts ] && echo 'bun apps/cli/src/index.ts' || echo spur)}"
+   $SPUR_BIN feature check <featureId> --json
+   $SPUR_BIN task list --feature <featureId> --json
    ```
 
 3. Classify **Shippable: PASS** only if **all** of:
    - No finding whose code/message indicates **linked but unverified** scenarios
-     (`L4_SCENARIO_UNVERIFIED` / “linked but unverified”).
+     (`L4_SCENARIO_UNVERIFIED`).
    - No **orphan / uncovered** feature scenarios (`L4_ORPHAN_SCENARIOS`,
      `L4_UNCOVERED_FEATURE_SCENARIO` / no covering task).
    - No **incomplete** linked tasks: every task with this `feature_id` is `done` or `cancelled`
@@ -424,16 +427,14 @@ Full flag matrix and ops notes: [spur-dev/references/dev-operations.md](../spur-
 
 ### Step 14 — Report
 
-Show the per-task verdict, the per-requirement table, the gate outcome (cleared / blocked), and the
-**Shippable:** line from Step 13 when applicable. Under the pipeline the task verdict is consumed by
-the done-gate; for a direct `/sp:dev-verify` invocation the full report is the operator's summary.
+Show the per-task verdict, per-requirement table, gate outcome (cleared/blocked), and the
+**Shippable:** line from Step 13 when applicable. Under the pipeline the done-gate consumes the
+verdict; for a direct `/sp:dev-verify` invocation the full report is the operator's summary.
 
-**`--next` on an already-terminal task (no-op surfacing).** When `--next` is invoked on a task
-already at `done` or `cancelled`, the transition cannot fire. The verify report line MUST state the
-no-op itself (e.g. `--next: no-op - task already terminal (<status>)`) rather than relying solely
-on the CLI print (documented in `dev-verify.md`'s `--next` chain section). The CLI print is the
-machine signal; the report line is the operator-visible summary - both must agree so a terminal-task
-re-audit cannot be misread as a successful `testing -> done` transition.
+**`--next` on a terminal task (no-op surfacing).** The transition cannot fire; the verify report
+line MUST state the no-op itself (e.g. `--next: no-op - task already terminal (<status>)`). The CLI
+print is the machine signal, the report line the operator summary — both must agree so a terminal
+re-audit is never misread as a successful `testing -> done` (dev-verify.md `--next` chain).
 
 ---
 
@@ -507,18 +508,18 @@ Do **not** use this skill for:
   and the per-requirement aggregation rule.
 - [references/secu-review.md](references/secu-review.md) — the SECUA dimensions and finding-severity
   rubric.
+- `plugins/sp/references/roles.md` — the Layer-1 role→tier table; this skill's verify/review modes
+  run under the `reviewer` role (0538 R4: this file points at roles.md, it does not restate tiers).
 - `.spur/workflows/task-pipeline.yaml` — the `verify → record` gate that consumes the verdict.
 - **`sp:spur-dev`** — the execution-half umbrella that drives the pipeline this skill gates.
 - [references/code-improvement.md](references/code-improvement.md) — architecture-improvement lens
   for module depth, seam placement, locality, coupling, and testability.
-- **`sp:functional-review`** — a peer review skill for requirements traceability (R{n} → file:line
-  evidence, per-requirement MET/PARTIAL/UNMET, `FunctionalVerdict`). When the `review` dimension
-  needs functional traceability (not just SECUA), dispatch this skill; see
-  [../functional-review/SKILL.md](../functional-review/SKILL.md).
-- **`sp:code-improvement`** — a peer review skill for architectural deepening (5 signals: shallow
-  module, tight coupling, wrong seam, weak locality, poor test surface; severity
-  blocker/major/minor/advisory). When review findings expose structural friction rather than a
-  localized defect, dispatch this skill; see [../code-improvement/SKILL.md](../code-improvement/SKILL.md).
+- **`sp:functional-review`** — requirements-traceability peer review (R{n} → file:line,
+  per-requirement MET/PARTIAL/UNMET). Dispatch when the `review` dimension needs functional
+  traceability, not just SECUA: [../functional-review/SKILL.md](../functional-review/SKILL.md).
+- **`sp:code-improvement`** — architectural-deepening peer review (5 signals, severity
+  blocker/major/minor/advisory). Dispatch for structural friction rather than localized
+  defects: [../code-improvement/SKILL.md](../code-improvement/SKILL.md).
 
 ---
 
@@ -531,5 +532,5 @@ directly: `Skill(skill="sp:code-verification", args="verify <wbs> --fix all")`.
 
 ### Codex / OpenClaw / OpenCode / Antigravity
 
-Run `spur` CLI via Bash; parse `--json`. Invoke this skill directly for the verification logic — the
-skill is the SSOT; the commands are thin wrappers.
+Run `spur` CLI via Bash; parse `--json`. Invoke the skill directly — the skill is the SSOT; the
+commands are thin wrappers.