@gobing-ai/spur 0.3.77 → 0.3.80

package/plugins/sp/scripts/batch-preflight.ts

@@ -25,6 +25,182 @@ export type PreflightResult =
     | { action: 'run'; code?: string; reason?: string }
     | { action: 'skip'; code: string; reason: string; unmetDeps?: string[] };
 
+// ── Command-aware quick readiness (task 0814 R2) ──────────────────────────────
+// Read-only admission decision for the requested dev operation. Distinguishes
+// runnable / needs-refinement / blocked / skipped / invalid outcomes without
+// LLM dispatch, full tests/lint, live-data probes, feature mutation, or
+// corpus-wide relational checking. Refinement gaps are work to do, not errors.
+
+export type ReadinessOperation = 'run' | 'refine' | 'verify';
+
+export interface QuickReadinessInput {
+    wbs: string;
+    status: TaskStatus;
+    operation: ReadinessOperation;
+    /** Frontmatter dependencies[] WBS list (run only). */
+    dependencies?: string[];
+    /** Status of each dependency WBS; missing → treated as unmet (run only). */
+    depStatuses?: Record<string, string>;
+    /** Size of the status-filtered candidate set after the selector resolved; 0 = empty set. */
+    filteredCount?: number;
+    /** Required planning sections for this variant+status; empty = not applicable. */
+    requiredSections?: string[];
+    /** Sections that are actually present (non-placeholder) in the task. */
+    presentSections?: string[];
+    /** L1/L2/L3 content-policy findings keyed by section; empty = clean. */
+    sectionFindings?: Record<string, string>;
+    /** Verify only: re-verification semantics (--force) — never a dirty-tree bypass. */
+    force?: boolean;
+}
+
+export type QuickReadinessResult =
+    | { action: 'runnable'; code: string; reason: string }
+    | { action: 'needs-refinement'; code: string; reason: string; gaps: string[] }
+    | { action: 'blocked'; code: string; reason: string; unmetDeps?: string[] }
+    | { action: 'skipped'; code: string; reason: string }
+    | { action: 'invalid'; code: string; reason: string };
+
+/**
+ * Evaluate quick readiness for a requested dev operation (0814 R2). Read-only:
+ * no model, no full tests/lint, no live-data probe, no feature mutation, no
+ * corpus-wide relational check. An empty status-filtered set is `skipped`
+ * (mirrors the zero-task rule), never an error. Refinement gaps under `refine`
+ * are work to do, so they do not block; under `run` they are `needs-refinement`.
+ */
+export function quickReadiness(input: QuickReadinessInput): QuickReadinessResult {
+    const status = (input.status ?? '').toLowerCase();
+    const operation = input.operation;
+
+    if (operation !== 'run' && operation !== 'refine' && operation !== 'verify') {
+        return {
+            action: 'invalid',
+            code: 'IV',
+            reason: `quick-readiness: unknown operation '${operation}' (${input.wbs})`,
+        };
+    }
+
+    if (input.filteredCount !== undefined) {
+        if (input.filteredCount < 0) {
+            return {
+                action: 'invalid',
+                code: 'IV',
+                reason: `quick-readiness: invalid negative filtered count '${input.filteredCount}' (${input.wbs})`,
+            };
+        }
+        if (input.filteredCount === 0) {
+            return {
+                action: 'skipped',
+                code: 'EMPTY',
+                reason: `quick-readiness: empty status-filtered set — nothing to ${operation} (${input.wbs})`,
+            };
+        }
+    }
+
+    if (status === 'cancelled' || status === 'done') {
+        // verify --force re-verification (R2 AC): an already-verified terminal task
+        // is re-checked, not skipped — but force never bypasses a dirty tree or the
+        // owning gates; it only re-admits a terminal task for re-verification.
+        if (operation === 'verify' && input.force === true) {
+            return {
+                action: 'runnable',
+                code: 'FORCE',
+                reason: `quick-readiness: verify --force re-verification of ${status} task ${input.wbs}`,
+            };
+        }
+        return {
+            action: 'skipped',
+            code: status === 'done' ? 'DONE' : 'CANCELLED',
+            reason: `quick-readiness: already ${status} — no ${operation} hop (${input.wbs})`,
+        };
+    }
+
+    if (status === 'blocked') {
+        return {
+            action: 'blocked',
+            code: 'BLK',
+            reason: `quick-readiness: blocked — human/handover first (${input.wbs})`,
+        };
+    }
+
+    // Unmet out-of-set dependency is a block for the operation that needs it.
+    if (operation === 'run' && input.dependencies && input.dependencies.length > 0) {
+        const unmet = input.dependencies.filter((d) => (input.depStatuses?.[d] ?? 'missing').toLowerCase() !== 'done');
+        if (unmet.length > 0) {
+            return {
+                action: 'blocked',
+                code: 'DEP',
+                reason: `quick-readiness: unmet deps — ${unmet.join(', ')} (${input.wbs})`,
+                unmetDeps: unmet,
+            };
+        }
+    }
+
+    const required = input.requiredSections ?? [];
+    const present = input.presentSections ?? [];
+    // A required section is a gap when it is absent from the present-set OR carries a
+    // content-policy finding (the caller-supplied `sectionFindings` from the matrix /
+    // `TaskCheckService.checkContentPolicy`). This lets the function detect a gap itself
+    // rather than depending on the caller to pre-enumerate every missing section.
+    const gaps = required.filter((s) => {
+        const finding = input.sectionFindings?.[s];
+        return !present.includes(s) || (finding !== undefined && finding !== '');
+    });
+
+    // refine: missing/incomplete planning sections are the work, not a failure.
+    if (operation === 'refine') {
+        if (status !== 'backlog' && status !== 'todo') {
+            return {
+                action: 'skipped',
+                code: 'NONPLAN',
+                reason: `quick-readiness: refine targets backlog/todo only, not '${status}' (${input.wbs})`,
+            };
+        }
+        return {
+            action: 'runnable',
+            code: 'OK',
+            reason: `quick-readiness: refine ready for ${input.wbs} (${gaps.length} planning gap(s) to fill)`,
+        };
+    }
+
+    if (operation === 'verify') {
+        if (status !== 'testing' && status !== 'wip') {
+            return {
+                action: 'invalid',
+                code: 'NOVERIFY',
+                reason: `quick-readiness: verify needs testing/wip, not '${status}' (${input.wbs})`,
+            };
+        }
+        return {
+            action: 'runnable',
+            code: 'OK',
+            reason: `quick-readiness: verify ready for ${input.wbs}`,
+        };
+    }
+
+    // run: implementation admission. Eligible statuses are todo/wip/testing;
+    // a backlog task needs the chain's auto-promotion first (step 0).
+    if (status !== 'todo' && status !== 'wip' && status !== 'testing') {
+        return {
+            action: 'invalid',
+            code: 'NORUN',
+            reason: `quick-readiness: run needs todo/wip/testing, not '${status}' (${input.wbs})`,
+        };
+    }
+    if (gaps.length > 0) {
+        return {
+            action: 'needs-refinement',
+            code: 'REFINE',
+            reason: `quick-readiness: implementation sections incomplete (${input.wbs})`,
+            gaps,
+        };
+    }
+    return {
+        action: 'runnable',
+        code: 'OK',
+        reason: `quick-readiness: run ready for ${input.wbs}`,
+    };
+}
+
 /**
  * Evaluate whether the batch should launch task-pipeline.yaml for this WBS.
  * STOP codes align with routing-table TABLE A row ids (A2, A7, A8, A9).
@@ -113,6 +289,16 @@ export interface PreflightCliArgs {
     recovery: boolean;
     help: boolean;
     json: boolean;
+    /** Quick-readiness operation (run|refine|verify); when set, run quickReadiness. */
+    operation: ReadinessOperation | null;
+    /** Verify-only re-verification (R2 AC). */
+    force: boolean;
+    /** Status-filtered candidate set size; 0 = empty set. */
+    filteredCount: number | null;
+    /** Required planning sections (matrix-selected). */
+    requiredSections: string[];
+    /** Sections actually present in the task. */
+    presentSections: string[];
 }
 
 export function parsePreflightCliArgs(argv: string[]): PreflightCliArgs {
@@ -123,13 +309,43 @@ export function parsePreflightCliArgs(argv: string[]): PreflightCliArgs {
     let recovery = false;
     let help = false;
     let json = false;
+    let operation: ReadinessOperation | null = null;
+    let force = false;
+    let filteredCount: number | null = null;
+    let requiredSections: string[] = [];
+    let presentSections: string[] = [];
 
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a === '--help' || a === '-h') help = true;
         else if (a === '--json') json = true;
         else if (a === '--recovery') recovery = true;
-        else if (a === '--wbs') wbs = argv[++i] ?? wbs;
+        else if (a === '--force') force = true;
+        else if (a === '--operation') {
+            const v = argv[++i] ?? '';
+            operation = v === 'run' || v === 'refine' || v === 'verify' ? v : null;
+        } else if (a === '--filtered-count') {
+            const v = Number(argv[++i]);
+            filteredCount = Number.isFinite(v) ? v : null;
+        } else if (a === '--required-sections') {
+            const raw = argv[++i] ?? '';
+            requiredSections =
+                raw.length === 0
+                    ? []
+                    : raw
+                          .split(',')
+                          .map((s) => s.trim())
+                          .filter(Boolean);
+        } else if (a === '--present-sections') {
+            const raw = argv[++i] ?? '';
+            presentSections =
+                raw.length === 0
+                    ? []
+                    : raw
+                          .split(',')
+                          .map((s) => s.trim())
+                          .filter(Boolean);
+        } else if (a === '--wbs') wbs = argv[++i] ?? wbs;
         else if (a === '--status') status = argv[++i] ?? null;
         else if (a === '--deps') {
             const raw = argv[++i] ?? '';
@@ -149,12 +365,27 @@ export function parsePreflightCliArgs(argv: string[]): PreflightCliArgs {
             }
         }
     }
-    return { status, deps, depStatuses, wbs, recovery, help, json };
+    return {
+        status,
+        deps,
+        depStatuses,
+        wbs,
+        recovery,
+        help,
+        json,
+        operation,
+        force,
+        filteredCount,
+        requiredSections,
+        presentSections,
+    };
 }
 
 export const PREFLIGHT_CLI_USAGE = `Usage:
   bun plugins/sp/scripts/batch-preflight.ts --wbs <wbs> --status <status> \\
     [--deps 0275,0276] [--dep-status 0275:done,0276:todo] [--recovery] [--json]
+  bun plugins/sp/scripts/batch-preflight.ts --operation <run|refine|verify> --wbs <wbs> --status <status> \
+    [--filtered-count <n>] [--required-sections A,B] [--present-sections A,B] [--force] [--json]
 
 Exit: 0 = run (or recovery hint printed); 2 = skip; 1 = usage.`;
 
@@ -173,6 +404,30 @@ export function runPreflightCli(argv: string[]): { exitCode: number; stdout: str
         return { exitCode: 0, stdout: body, stderr: '' };
     }
 
+    // Quick command-aware readiness (0814 R2) — read-only admission decision.
+    if (args.operation !== null) {
+        const result = quickReadiness({
+            wbs: args.wbs,
+            status: args.status,
+            operation: args.operation,
+            dependencies: args.deps,
+            depStatuses: args.depStatuses,
+            ...(args.filteredCount !== null ? { filteredCount: args.filteredCount } : {}),
+            ...(args.requiredSections.length > 0 ? { requiredSections: args.requiredSections } : {}),
+            ...(args.presentSections.length > 0 ? { presentSections: args.presentSections } : {}),
+            ...(args.force ? { force: true } : {}),
+        });
+        const runnable = result.action === 'runnable' || result.action === 'needs-refinement';
+        if (args.json) {
+            return { exitCode: runnable ? 0 : 2, stdout: `${JSON.stringify(result, null, 2)}\n`, stderr: '' };
+        }
+        return {
+            exitCode: runnable ? 0 : 2,
+            stdout: `${result.action}${result.code ? ` ${result.code}` : ''}: ${result.reason}\n`,
+            stderr: '',
+        };
+    }
+
     const result = preflightTask({
         wbs: args.wbs,
         status: args.status,

package/plugins/sp/scripts/verify-answer-lint.ts

@@ -282,18 +282,24 @@ function stripAcWrappers(title: string): string {
  * Normalize an AC identity to its canonical key, mirroring the documented
  * matching behavior of feature-check `rowMatchesScenario` + ac-style-guide
  * "Four accepted id forms" (exact/bare title, `Scenario:` prefix, bracket
- * tags, `AC-N` ordinal) without importing that private matcher or adopting
+ * tags, `AC-N` ordinal) plus the task-side bold-trajectory paragraph
+ * (0817 R3), without importing that private matcher or adopting
  * its permissive trailing-Gherkin fallback (0804 R4). Comparison is
  * case/quote/whitespace-insensitive. A paraphrase normalizes differently
  * and still fails.
  */
 function normalizeAcTitle(title: string): string {
-    return stripAcWrappers(title)
-        .replace(/^R\d+\s*[:\-—]?\s*/, '')
-        .toLowerCase()
-        .replace(/[ʼ‘’“”]/g, '')
-        .replace(/\s+/g, ' ')
-        .trim();
+    return (
+        stripAcWrappers(title)
+            .replace(/^R\d+\s*[:\-—]?\s*/, '')
+            .toLowerCase()
+            // Exact pre-refactor removal set (0809 R5): ASCII apostrophe + the four curly
+            // quotes. Escaped form keeps U+0027 visible next to lookalike curly glyphs;
+            // U+02BC stays a meaningful character, never removable punctuation.
+            .replace(/[\u0027\u2018\u2019\u201c\u201d]/g, '')
+            .replace(/\s+/g, ' ')
+            .trim()
+    );
 }
 
 /**
@@ -302,7 +308,7 @@ function normalizeAcTitle(title: string): string {
  * A checklist-declared spelling always wins over the positional alias.
  */
 interface AcIdentityIndex {
-    /** normalized canonical title → a declared spelling (label, token, or title). */
+    /** normalized canonical title → a declared spelling (label, token, title, or bold trajectory). */
     readonly byTitle: Map<string, string>;
     /** AC-N → task scenario title at that 1-based ordinal. */
     readonly taskScenarios: string[];
@@ -326,6 +332,19 @@ function buildAcIdentityIndex(taskContent: string, featureContent: string | null
         const leading = label.split(/\s+/)[0] ?? '';
         if (leading && leading !== label) declareIdentity(leading);
     }
+    // Bold-trajectory form (task 0817 R3): answers may cite an AC by a bare
+    // `**AC id**` paragraph (house style for long/complex ids). Only whole-line
+    // bold spans count — the line-anchored lazy regex rejects lines with two
+    // spans, keeping interpolated bold text out of the index. The head (text
+    // before the first colon) is declared like a checklist label, mirroring
+    // the `(?::|$)` label extraction above.
+    for (const m of section.matchAll(/^\*\*(.+?)\*\*\s*$/gm)) {
+        const inner = (m[1] ?? '').trim();
+        if (!inner) continue;
+        declareIdentity(inner);
+        const head = inner.split(':')[0]?.trim() ?? '';
+        if (head && head !== inner) declareIdentity(head);
+    }
     const scenarioTitles = (content: string): string[] =>
         [...content.matchAll(/^[ \t]*Scenario:\s*(.+)\s*$/gm)].map((m) => (m[1] ?? '').trim()).filter((t) => t !== '');
     const taskScenarios = scenarioTitles(sectionBetween(taskContent, 'Acceptance Criteria'));
@@ -343,6 +362,10 @@ type AcIdentityResolution = { ok: true; canonical: string } | { ok: false; error
  * alias — accepted only against a real scenario ordinal, and refused with an
  * actionable diagnostic when task and feature ordinals disagree. Undeclared
  * `ACn` tokens, paraphrases and invented ordinals never resolve.
+ * `ACn` tokens, paraphrases and invented ordinals never resolve.
+ *
+ * Declared forms recognized in the index include the bold-trajectory
+ * `**AC id**` paragraph (task 0817 R3); the AC-N failure hint names it.
  */
 function resolveAcIdentity(rowId: string, index: AcIdentityIndex): AcIdentityResolution {
     const canonical = index.byTitle.get(normalizeAcTitle(rowId));
@@ -360,7 +383,7 @@ function resolveAcIdentity(rowId: string, index: AcIdentityIndex): AcIdentityRes
                 ok: false,
                 error:
                     `AC id "${rowId}" uses the AC-${n} positional alias but no scenario exists at that ordinal ` +
-                    '(task scenario list and linked-feature scenario list) — cite the exact scenario title or checklist label',
+                    '(task scenario list and linked-feature scenario list) — cite the exact scenario title, checklist label, or a bare `**AC id**` paragraph',
             };
         }
         if (candidates.length > 1) {

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

@@ -94,6 +94,12 @@ Resolve `<scope>` and `--pillar`; confirm the repository root; establish **audit
 numbered-document mutation of any kind. With `--resolve`, no write happens until a repair set is
 presented, explicitly confirmed, and freshness-revalidated.
 
+Validate every enum flag against the domain declared by the command surface
+(`plugins/sp/commands/dev-find-conflict.md`): `--pillar` ∈ `source|tasks|features|authority|all`,
+`--mode` ∈ `adaptive|full`, `--agent` ∈ `inline|auto|name`. An out-of-domain value **refuses** the
+audit before any discovery work — report the received value, the flag's valid domain, and stop;
+never silently coerce or ignore it. Only `<scope>` is free-form and exempt from this check.
+
 ### Step 2 — Discover local authority
 
 Read entry/process rules (`AGENTS.md`, `docs/99_PROJECT_CONSTITUTION.md`) before interpreting any

package/plugins/sp/skills/daily-summary/SKILL.md

@@ -166,6 +166,6 @@ Read the skill file and follow the workflow manually.
 ## Additional Resources
 
 - **Script source:** [scripts/daily-summary/daily-summary.ts](../../scripts/daily-summary/daily-summary.ts) — CLI implementation
-- **Tests:** [tests/daily-summary.test.ts](tests/daily-summary.test.ts) — unit coverage for parsing, date ranges, markdown output
+- **Tests:** [tests/daily-summary/daily-summary.test.ts](../../tests/daily-summary/daily-summary.test.ts) — unit coverage for parsing, date ranges, markdown output
 - **Related skills:** `sp:dev-handover` (blocker handoff), `sp:dev-changelog` (commit-based changelog), `sp:spur-cli` (task management)
 - **Upstream CLI:** [ccusage](https://github.com/ryoppippi/ccusage) — AI agent token usage reporter

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

@@ -4,7 +4,7 @@ description: "Evolve docs/00-05 + AGENTS.md per docs/99_PROJECT_CONSTITUTION.md:
 license: Apache-2.0
 metadata:
   author: spur
-  version: "1.0"
+  version: "1.1"
   platforms: "claude-code,codex,openclaw,opencode,antigravity"
   interactions:
     - reviewer
@@ -30,17 +30,17 @@ this skill applies it.
 
 **Read `docs/99_PROJECT_CONSTITUTION.md` first.** It is the single source of truth for *how* these
 files are maintained (authority §2, doc map §4.1, frontmatter contracts §4.3, sync triggers §5,
-per-file edit rules §6, the audit §7, lessons §8). This skill is a runbook for executing §5/§7/§8;
+per-file edit rules §6, the audit §7, lesson routing §8). This skill is a runbook for executing §5/§7/§8;
 when the two disagree, the constitution wins and this skill is the bug.
 
 ## Operations
 
 | Operation | What it does | Constitution authority | Deterministic helper |
 | --------- | ------------ | ---------------------- | -------------------- |
-| **drift-audit** | Reality (code/shipped) vs. what a key file says, and cross-doc contradictions | §7 (the 8-item checklist) | `rg` the real CLI/config surface; diff vs `04`/`AGENTS.md`/`00` |
-| **sync-check** | Did a change touch the docs its trigger obligates in the same commit? | §5 (triggers T1–T8) | git diff of code/config vs. the matching doc edit |
+| **drift-audit** | Reality (code/shipped) vs. what a key file says, and cross-doc contradictions | §7 | `rg` the real CLI/config surface; diff vs `04`/`AGENTS.md`/`00` |
+| **sync-check** | Did a change touch the docs its trigger obligates in the same commit? | §5 (applicable triggers) | git diff of code/config vs. the matching doc edit |
 | **contract-verify** | Each doc's frontmatter matches its §4.1 row; `updated_at` is plausible | §4.3 | parse frontmatter; compare `owns`/`authority` vs §4.1; `git log` recency |
-| **lesson-append** | Append a dated lesson; dedup; promote recurring ones to a rule | §8 | format-check the line; `rg` for an equivalent before adding |
+| **lesson-append** | Record a useful lesson in existing project context; deduplicate; propose governance changes separately | §8 | format-check the line; `rg` for an equivalent before adding |
 
 No thin `dev-docs` command wrapper exists (`dev-operations.md §7`). Invoke this skill directly for
 an audit or a lesson, or reach it via `/sp:dev-plan`'s docs step and `/sp:spur-init`'s `customize`.
@@ -84,48 +84,40 @@ stubs filled or deliberately documented; `bun run lint` passes where applicable.
 Walk the §7 checklist. Each item pairs a detection command with the doc it validates:
 
 ```bash
-# Real CLI surface vs. what 04 / AGENTS.md / 00 claim
+# Real CLI surface vs. owning non-UI contracts
 rg -n "\.command\('" apps/cli/src/commands/        # the true verb list
-rg -n '^#### `spur ' docs/04_DESIGN.md             # documented commands
+rg -n '^#### `spur ' docs/design/             # documented commands
 # → diff the two sets; a verb in code but not in 04 is T3 drift.
 
 # 05 status rows vs. reality
-rg -n '✅|🔶|⏳|💤' docs/05_FEATURES.md             # claimed states
+cat docs/features/INDEX.md                         # generated feature states
 # → spot-check each ✅/🔶 against code; confirm no ⏳ quietly shipped.
 
 # 02 phase bullets name real things (no dead names)
 # 03 module descriptions vs. the real tree
-fd -t d -d 2 . apps packages                       # real modules
+rg --files apps packages                       # real modules
 # Frontmatter contracts (see contract-verify) + updated_at recency
 git log -1 --format='%ci' -- docs/04_DESIGN.md     # last touch vs. recent surface changes
 ```
 
-**Repair protocol (§7, always this order):** fix the **authoritative** doc first (append-only files
-by dated amendment, never rewrite), then the derived docs that restate/sequence it, then
-`AGENTS.md`, then **flag what drifted and why** in the commit/task (a silent fix hides the systemic
-cause). Anything systemic becomes a §8 lesson — or, if it recurs, a new §6 rule.
+**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.
+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
 }`. A clean report lists the checks run and that each returned no delta.
 
 ## sync-check (§5)
 
-Given a change (a diff, or a just-finished task), check the same-commit obligations:
+Read the live constitution §5; it owns the trigger table. Classify each changed fact, identify
+its owner, and inspect the diff to confirm required synchronization. Update an index or AGENTS.md
+only when its own facts changed. A satellite edit with an unchanged index pointer is synchronized.
 
-| If the change… | Trigger | …the same commit must touch |
-| -------------- | ------- | --------------------------- |
-| adds/changes a command, flag, config key, env var, schema, DTO | **T3** | `04_DESIGN` + the `AGENTS.md` surface block |
-| ships a feature or changes its state | **T4** | its `05` row (+ a `01` scope row if new surface) |
-| makes a new cross-cutting decision (or reverses one) | **T1** | `00` first (dated), then `03`, `01` if scope shifts |
-| would contradict an existing ADR | **T2** | **stop** — add the superseding ADR entry first |
-| completes/reorders a phase | **T5** | `02` (the real shipped name) |
-| adds/cuts/defers scope | **T6** | `01` + placement in `02` |
-| changes the doc map or process | **T7** | this file → re-sync `AGENTS.md` (§4.4) → siblings |
-| plans a multi-wave batch | **T8** | schedule "doc sync" as an explicit work item |
-
-Detection is a diff read: list the changed code/config paths, map each to its trigger, then confirm
-the obligated doc was edited in the same change. A surface change with no `04` edit is the canonical
-miss (the one this whole §5 table exists to prevent).
+T1 applies only to real architectural choices passing §6.1. Feature approvals, task completion,
+bugfixes restoring an existing contract and verification receipts do not justify ADR entries.
+T7 applies only to operator-authorized governance corrections under §6.8; a routine doc edit or
+lesson does not justify touching the constitution. Portable changes include in-scope init templates.
 
 ## contract-verify (§4.3)
 
@@ -140,19 +132,13 @@ stale given recent commits?"
 
 ## lesson-append (§8)
 
-Append a lesson to the right per-file section of §8:
-
-```
-- [YYYY-MM-DD] <project>: <lesson — what went wrong / what to do instead>
-```
+Read constitution §8 for the existing project's destination. Record a useful, deduplicated
+lesson in existing learning/context storage or a dated report, with evidence. Do not append
+lessons to the constitution. Do not create a second learning ledger when one already exists.
 
-- **Low threshold** — when in doubt, append. **Check for an equivalent first** (`rg` the section);
-  bump its date instead of duplicating.
-- **Promotion is the only sanctioned deletion:** a lesson that recurs or hardens into practice is
-  promoted into a §6 rule (or §5 trigger) and removed from §8. Lessons are the inbox; §5/§6 are the
-  law.
-- Lessons carry project provenance (this file is byte-identical across projects except §8 + the §3
-  tool column) — a lesson from one project is a warning, not yet a law, for the others.
+A recurring lesson may justify proposing a document-governance correction; apply it only within
+operator-authorized §6.8 scope. Task receipts remain in task records. Fresh project templates
+contain neither inherited lessons nor fabricated decisions/status claims.
 
 ## What this skill is NOT
 

package/plugins/sp/skills/doc-evolve/references/operations.md

@@ -15,41 +15,33 @@ it enforces; the skill never invents process.
 
 | Operation | Authority § | What "done" means |
 | --------- | ----------- | ----------------- |
-| drift-audit | §7 | the 8-item §7 checklist run, each backed by a command; report lists deltas (or the zero-delta commands) |
-| sync-check | §5 (T1–T8) | every changed surface mapped to its trigger; the obligated doc confirmed edited in the same change |
+| drift-audit | §7 | the affected §7 checks run, each backed by a command; report lists deltas (or the zero-delta commands) |
+| sync-check | §5 (applicable §5 triggers) | every changed surface mapped to its trigger; the obligated doc confirmed edited in the same change |
 | contract-verify | §4.3 (+ §4.1) | each doc's frontmatter `owns`/`authority` matches its §4.1 row; `updated_at` plausible |
-| lesson-append | §8 | a dedup'd, correctly-formatted dated line in the right per-file section |
+| lesson-append | §8 | a deduplicated lesson in existing learning/context storage, never appended to 99 |
 
 ## drift-audit — §7 checklist → detection commands
 
 | §7 item | Detection (deterministic) | Authoritative doc |
 | ------- | ------------------------- | ----------------- |
-| Real CLI surface vs docs | `rg -n "\.command\('" apps/cli/src/commands/` vs `rg -n '^#### \`spur ' docs/04_DESIGN.md` | `04` + `AGENTS.md` surface, `00` committed-surface |
-| `05` ✅/🔶 spot-check; no ⏳ quietly shipped | `rg -n '✅\|🔶\|⏳\|💤' docs/05_FEATURES.md`, then check each against code | `05` |
+| Real CLI surface vs docs | Compare source-local help/registrations with owning `docs/design/` contracts | `04` satellites |
+| Feature state matches evidence | Read the feature tool's generated index, then inspect affected acceptance evidence | `05` / feature records |
 | Every shipped surface has a `01` scope row | surface set (above) vs `rg` of `01` scope table | `01` |
 | `02` phase bullets name real things | read `02` current-phase bullets; grep each name in code/docs | `02` |
-| `03` modules vs real tree | `fd -t d -d 2 . apps packages` vs `03` module list | `03` |
+| `03` modules vs real tree | `rg --files apps packages` vs `03` module map | `03` |
 | `04` covers every command/flag/config/schema | the verb/flag/config set vs `04` | `04` |
 | `AGENTS.md` doc map == §4.1 | diff the two tables | `AGENTS.md` (§4.4) |
 | frontmatter matches §4.1 + `updated_at` plausible | see contract-verify | each doc (§4.3) |
 
 **Judgment:** is a candidate real drift (vs. an intentional, documented exception)? Which doc is
-authoritative? What is the *minimal* repair (a one-line dated amendment beats a rewrite)?
+authoritative? What is the *minimal* repair (preserve decision history and condense only editorial noise under §6.1)?
 
-## sync-check — T1–T8 → obligations
+## sync-check — applicable §5 triggers → obligations
 
-Read the change (diff or finished task); for each changed path classify the trigger and confirm the
-obligated doc was touched in the same change. The high-frequency miss is **T3** (a CLI/config/schema
-change without the matching `04` + `AGENTS.md` edit) — check it first. (T1–T8 listed in the SKILL.md
-table; this reference is the detection recipe, not a restatement of the triggers.)
-
-```bash
-# Surface changed in this diff?
-git diff --name-only | rg 'apps/cli/src/commands/|packages/.*/schema|config/'
-# Was 04 / AGENTS.md touched in the same diff?
-git diff --name-only | rg 'docs/04_DESIGN.md|^AGENTS.md'
-# Both non-empty → likely synced; surface-changed-but-no-04 → T3 drift.
-```
+Read the diff and the live constitution §5. Map changed facts to their owning document and
+check that contract, not merely whether a filename appears in the diff. Unchanged index pointers
+and entry guidance need no edits. T7 additionally requires the governance reason and existing
+operator authorization under §6.8; include affected templates.
 
 ## contract-verify — §4.3
 
@@ -65,15 +57,10 @@ Compare `owns`/`authority` against the §4.1 row (verbatim in meaning; §4.1 win
 
 ## lesson-append — §8
 
-```
-- [YYYY-MM-DD] <project>: <lesson — what went wrong / what to do instead>
-```
-
-1. Identify the per-file `### Lessons for <doc>` section (or the cross-cutting one).
-2. `rg` that section for an equivalent lesson — if found, **bump its date**, don't duplicate.
-3. Append the formatted line. If the lesson restates an existing §6 rule, it's already law — skip.
-4. If it has recurred, **promote** it to a §6 rule / §5 trigger and remove from §8 (the only
-   sanctioned deletion).
+1. Resolve the existing learning/context destination from the project's conventions.
+2. Search for an equivalent lesson; skip duplicates and routine completion receipts.
+3. Record the useful lesson with evidence outside the constitution.
+4. Propose any governance correction separately; recurrence does not authorize a §6.8 edit.
 
 ## Drift-report shape
 
@@ -84,7 +71,7 @@ Checks run: <n> (§7 items)  ·  Findings: <m>
 
 | # | Doc | Reality says | Doc says | Authority | Trigger | Repair |
 |---|-----|--------------|----------|-----------|---------|--------|
-| 1 | 04_DESIGN | `spur foo` exists (apps/cli/.../foo.ts) | absent | 04 (T3) | — | add the §6.4 command block |
+| 1 | 04_DESIGN | Changed command contract | Satellite describes old behavior | 04 | T3 | update its owning satellite under §6.5 |
 
 Zero-finding checks: <list the §7 items that returned no delta, with the command used>
 ```

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

@@ -67,6 +67,20 @@ frontmatter scalar.
   wholesale. No inline-body flag. Section names: `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`.
+- **AC controls** (`--ac-altitude <graduating|task-local>`, `--ac-numbering task-local`) — independent
+  of each other (task 0818 R5). `--ac-altitude task-local` skips the **DD-09 feature-AC subset** rule
+  because the task's scenarios are intentionally not the feature's ship criteria; `--ac-numbering
+  task-local` opts the task into the **Requirements↔AC coverage** check inside the task. Setting one
+  never implies the other. `graduating` remains the default and DD-09 stays enforced for graduating
+  tasks. Use it for an issue/fix-batch task that is genuinely linked to a feature but whose
+  regression scenarios sit below that feature's ship criteria, and record the rationale in the task
+  body:
+
+  ```bash
+  # One frontmatter flag per call — `update` sets a single field and ignores the rest.
+  bun run apps/cli/src/index.ts task update 0818 --feature D6 --json
+  bun run apps/cli/src/index.ts task update 0818 --ac-altitude task-local --json
+  ```
 
 Exit code `2` when neither mode's required args are supplied (e.g. `--section` without `--from-file`,
 or no status and no `--section`/frontmatter flag).
@@ -183,7 +197,9 @@ traceability. Bare = whole corpus; with a WBS = one task. The matrix is loaded f
 
 **L4 traceability** resolves `feature_id` / `parent_wbs` / `dependencies` edges and checks **AC
 coverage** (DD-09): a task's scenarios must be a subset of its linked feature's AC by normalized
-title — orphans warn by default.
+title — orphans warn by default. A task declaring `ac_altitude: task-local` is exempt from that
+subset rule only (`--ac-altitude`, above); every graduating task is still enforced, and the exemption
+does not touch `ac_numbering`'s Requirements↔AC coverage or any other layer.
 
 `--json` emits an array of per-task results: