@gobing-ai/spur 0.3.40 → 0.3.42

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

@@ -0,0 +1,276 @@
+---
+name: remediation-routing
+description: "Confirmed, owner-routed remediation for sp:conflict-finding — audit-mode write guard, --resolve proposal/confirmation workflow, freshness revalidation, owner routing table, partial-failure and idempotency semantics."
+see_also:
+  - conflict-finding
+---
+
+# Remediation routing — confirmed, owner-routed repair
+
+`sp:conflict-finding` is, first and foremost, an **audit** capability. Remediation is a separate,
+opt-in, gated workflow. This file is the SSOT for *when a write is allowed*, *who may perform it*,
+*how the operator confirms it*, and *what happens when a repair fails midway*.
+
+The governing rule, carried through everything below: **no mutation in audit mode, and no automatic
+mutation merely because `--resolve` is present.** Every write requires (a) a presented repair set,
+(b) explicit operator confirmation, (c) a freshness revalidation of the supporting evidence, and
+(d) dispatch through the artifact owner's verified harness surface. Ambiguity or partial failure is
+reported, never silently continued.
+
+## Core invariants
+
+| Invariant | Guarantee |
+|-----------|-----------|
+| Audit mode is read-only | Without `--resolve`, no source, corpus (task/feature), or numbered-document mutation of any kind. |
+| `--resolve` is not a write | It only *opens* the proposal → confirmation → owner-routed workflow. It never authorizes automatic repair. |
+| Confirmation precedes every write | No repair executes until the operator explicitly approves the specific proposed repair set. |
+| Freshness precedes mutation | The supporting evidence anchors are re-read and compared against the finding's fingerprint before any write. |
+| Owner surface, not raw edits | Each approved repair routes through the artifact's owner (Spur CLI, `sp:doc-evolve`, Spur dev lifecycle, Superskill lifecycle) — never a direct file write where an owner surface exists. |
+| Idempotent and partial-failure aware | Already-matching artifacts resolve without a write; one repair's failure neither marks others successful nor silently rolls forward. |
+
+## 1. Audit mode — the read-only guarantee
+
+Without `--resolve`, the run performs **no mutation** of:
+
+- **Source** — implementations, contracts, tests, config, registrations.
+- **Corpus** — task files and feature files.
+- **Numbered docs and projections** — `docs/00`–`05`, `docs/99_PROJECT_CONSTITUTION.md`, and
+  `AGENTS.md` / template projections.
+
+Everything the audit produces — findings, evidence, authority provenance, coverage, unresolved
+items, proposed repairs, recommended owner — is an **envelope**, not a change. The report may
+describe what *would* be repaired and by whom, but nothing is applied.
+
+The only permitted writes in audit mode are transient and internal (temp files for composing a
+repair payload, `.spur/context/` note files when the operator explicitly opts into indexed-context
+reuse). These never touch governed artifacts.
+
+## 2. The `--resolve` workflow — proposal, confirm, revalidate, route
+
+`--resolve` changes one thing: it enables the remediation workflow. It does **not** change the
+write guard. The full workflow is:
+
+```text
+--resolve
+  → 1. PRESENT REPAIR SET   enumerate proposed repairs keyed by finding ID + evidence fingerprint,
+                            each with repair_owner and the owner surface that will apply it
+  → 2. OBTAIN CONFIRMATION  operator explicitly approves the selected set (or a subset, or none)
+  → 3. REVALIDATE FRESHNESS re-read each artifact anchor; compare against the finding fingerprint;
+                            stale anchors return to audit (see §4)
+  → 4. ROUTE BY OWNER       dispatch each approved repair through its owner surface (§3)
+  → 5. REPORT OUTCOMES      completed / failed / untouched sets; never silently roll forward (§5)
+```
+
+### 2.1 Present the repair set
+
+Before anything is applied, present a complete, itemized repair set. Each item is keyed by its
+finding `id` plus an **evidence fingerprint** — a stable digest of the artifact anchors (path +
+line/heading/symbol/WBS/feature ID) and the claim paraphrase that the finding was built on. The
+fingerprint lets the workflow detect that the world changed between audit and remediation.
+
+Each proposed item states:
+
+- **Finding ID** — links back to the audit report.
+- **Claim type + conflict type** — e.g. `stale` / `source↔authority`.
+- **Artifact(s) to change** — exact path and anchor.
+- **Repair owner + surface** — the owner and the exact command/skill that will apply it (§3).
+- **Proposed change** — the concrete edit the owner surface is expected to perform.
+
+Nothing in §2.1 is a mutation; it is a proposal. Only the confirmed subset in §2.2 proceeds.
+
+### 2.2 Obtain explicit confirmation
+
+The operator must explicitly approve the repair set — in whole, in part, or decline. Confirmation
+is:
+
+- **Explicit** — a clear affirmative ("yes", "apply these N", selection of specific findings), never
+  inferred from the mere presence of `--resolve`.
+- **Per-set** — the operator confirms the specific artifacts and changes presented, not a blanket
+  "fix everything."
+- **Recorded** — the chosen subset (approved / declined / deferred) is carried into the
+  remediation report so the audit trail shows exactly what was authorized.
+
+A declined or deferred repair is left **untouched** and reported as such; it is not re-attempted
+implicitly in the same run.
+
+### 2.3 Revalidate evidence freshness
+
+Between the audit and any write, the world may have changed. Immediately before dispatching each
+approved repair:
+
+1. Re-read the artifact at the anchor the finding recorded.
+2. Recompute (or re-compare) the evidence fingerprint.
+3. If the anchor content still matches the fingerprint → proceed to route.
+4. If the anchor has moved, the text changed, the file was deleted, or the referenced symbol/WBS/AC
+   no longer resolves → mark the item `stale-evidence` and **return to audit**. Do not "repair" a
+   stale finding on hunches; re-run the relevant audit step to re-establish evidence.
+
+Freshness is per-finding, checked at dispatch time — not once up front. This is what closes the gap
+between "the audit said X" and "the file now says Y."
+
+## 3. Owner routing table
+
+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.
+
+| 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. |
+| 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. |
+
+### 3.1 Task/feature corpus
+
+Corpus writes go through Spur CLI verbs — `spur task` / `spur feature` with the appropriate
+sub-verb (`update`, `--section`, `--from-file`, `--json`). This keeps task/feature files under the
+harness's write-guard and section/schema contracts. Never `Write`/`Edit` a task or feature file
+directly; the corpus is CLI-gated.
+
+**`--section` is not addressable at every heading level.** It resolves **`##` sections in feature
+files** and **`###` sections in task files**. A repair proposing `--section Tasks` against a feature
+whose roster sits at `###` fails with `does not contain section` and lists the `##` headings it did
+find. Before proposing a section-scoped repair, confirm the target heading exists **at the
+addressable level** — `spur feature show <id> --json` / `spur task show <wbs> --json` enumerate what
+is actually addressable. When the content is a subsection, the repair is either the enclosing `##`
+section (which rewrites the whole body, so weigh it against blast radius and any load-bearing
+evidence inside) or a different owner verb; do not silently widen the write to make the flag fit.
+
+**Frontmatter is validated before the write.** `spur task update` rejects the whole operation when
+required frontmatter (`schema_version`, `created_at`, `updated_at`, a valid `status` enum) is
+missing — the file is left byte-identical. That is an **owner-surface failure**, not
+`stale-evidence`: the finding stands and stays re-dispatchable. Report it as `failed` and stop that
+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
+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).
+
+`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.
+
+### 3.3 Source / tests
+
+Source and test repairs are **real implementation work**. By default they are dispatched as a Spur
+task routed through `sp:spur-dev` and the build competencies (`sp:code-implementation`,
+`sp:code-testing`) — so the change gets a Requirements/AC envelope, a lifecycle, and verification.
+
+The one exception: if the **active session already has explicit implementation authority** for the
+change (e.g. the operator is already inside a task implementation, or explicitly delegated the
+source edit), the repair may be applied directly in that session. When in doubt, prefer the Spur
+task route.
+
+### 3.4 Command/skill capability source
+
+A repair to a command or skill's own source (the capability being audited) goes through the
+**Superskill lifecycle** in the owning plugin source — `superskill command …` / `superskill skill …`
+for scaffold/validate/evaluate/refine. This keeps capability artifacts canonical and validated.
+Do not commit generated per-platform adapters.
+
+### 3.5 Ambiguous authority
+
+If routing cannot determine an owner — authority is ambiguous, incomparable, or missing for the
+subject + claim type — the workflow **stops for an operator decision**. It does not pick a winner,
+does not edit both sides, and does not fall back to a global ranking. The item remains
+`needs-authority-decision` (or `stale-evidence`/`unresolved` as appropriate) and is reported as
+untouched.
+
+## 4. Repairs keyed by finding ID + evidence fingerprint
+
+Every repair in the set is keyed by two things:
+
+- **Finding `id`** — the stable identifier from the audit report.
+- **Evidence fingerprint** — the digest of the anchors (path + line/heading/symbol/WBS/feature ID)
+  and the claim paraphrase the finding rests on.
+
+This key drives the freshness check (§2.3) and the outcome bookkeeping (§5). Concretely:
+
+| Condition at dispatch | Outcome |
+|-----------------------|---------|
+| Anchor content matches the fingerprint | Route the repair through its owner surface. |
+| Anchors changed (moved, edited, deleted; symbol/WBS/AC gone) | Mark `stale-evidence`, **return to audit** — re-run the affected audit step to re-establish evidence before any further repair. |
+| Artifact already matches the proposed outcome | **Resolved without a write** (idempotent). The finding is marked `resolved`; no mutation occurs. |
+| Owner surface reports a failure | Mark the item `failed`; do not mark siblings successful or roll forward (§5). |
+
+### 4.1 Idempotent resolution
+
+If, at dispatch time, the artifact already matches the repair's target state — the drift was already
+fixed by someone else, or the finding was stale in the "no longer wrong" direction — the item is
+**resolved without a write**. Idempotency is an explicit outcome, not an accident: the workflow
+recognizes "already correct" and records it as `resolved` rather than re-applying a no-op edit or
+worse, applying an edit that re-introduces a conflict.
+
+## 5. Partial failure, retry, and outcome reporting
+
+Remediation is **per-item**, not all-or-nothing. A failure in one repair:
+
+- Does **not** mark other repairs successful.
+- Does **not** silently roll forward to the remaining repairs as if nothing happened.
+- Is **reported** as a distinct outcome.
+
+The final remediation report always separates the outcome sets:
+
+| Set | Meaning |
+|-----|---------|
+| **Completed** | Owner surface confirmed the repair applied (or artifact already matched — idempotent `resolved`). |
+| **Failed** | The owner surface rejected/errored, or dispatch could not complete. |
+| **Untouched** | Declined/deferred by the operator, or blocked on `stale-evidence` / `needs-authority-decision`. |
+
+These sets are mutually exclusive and together account for every item in the approved set. The
+report surfaces the exact failed items and the reason, so the operator can decide to retry — in a
+fresh run with re-validated evidence — rather than being told, or assuming, that everything was
+applied.
+
+### 5.1 Retry
+
+Retry is the operator's decision after reading the failed set. The workflow never auto-retries
+within a run; it stops, reports, and lets the operator re-invoke with a fresh audit (and thus a
+fresh freshness check). A retry must revalidate evidence rather than blindly re-attempting the same
+stale repair.
+
+## 6. Anti-patterns
+
+These are the explicit boundaries for remediation. Each is a hard violation, not a style choice.
+
+| 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. |
+| **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. |
+| **Direct corpus writes** | Task/feature files are CLI-gated (`spur task`/`spur feature`); never raw `Write`/`Edit`. |
+| **Direct numbered-doc or capability edits** | Numbered-doc/projection writes go through `sp:doc-evolve`; capability source through the Superskill lifecycle. |
+| **Source edits without authority** | Source/test repairs default to a Spur task + dev lifecycle unless the active session already has explicit implementation authority. |
+| **Repairing stale evidence** | Changed anchors return to audit; never "repair" a finding whose evidence is no longer current. |
+
+## 7. Checklist — safe remediation
+
+Before dispatching any write, confirm each of the following:
+
+- [ ] Audit mode performed **no** governed mutation; the report is a pure envelope.
+- [ ] `--resolve` was present, and the **repair set was presented** (keyed by finding ID + fingerprint).
+- [ ] The operator **explicitly confirmed** the specific selected repair set.
+- [ ] Evidence **freshness revalidated** per finding at dispatch; `stale-evidence` items returned to audit.
+- [ ] Each approved repair routed through its **owner surface** (§3), never a raw write where an owner exists.
+- [ ] **Idempotent** already-matching items marked `resolved` without a write.
+- [ ] **Completed / failed / untouched** sets reported; failures surfaced, not silently continued.
+- [ ] Ambiguous authority **stopped for an operator decision**; neither side mutated.
+- [ ] No broad cleanup outside confirmed findings.
+
+## Related
+
+- Skill entry: [../SKILL.md](../SKILL.md) (Step 10 — Remediate)
+- Authority model and ambiguity protocol: [./authority-resolution.md](./authority-resolution.md)
+- Finding schema, status values, and evidence rules: [./finding-contract.md](./finding-contract.md)
+- Comparison and candidate-graph construction: [./comparison-protocol.md](./comparison-protocol.md)
+- Owner surfaces: `sp:spur-cli`, `sp:spur-dev`, `sp:doc-evolve`

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

@@ -0,0 +1,171 @@
+---
+name: daily-summary
+description: "Generate a daily summary report from agent usage, git history, and your notes."
+disable-model-invocation: true
+license: Apache-2.0
+version: 1.0.0
+created_at: 2026-04-17
+updated_at: 2026-04-17
+platform: sp
+tags: [summary, daily, analytics, reporting, engineering-core]
+metadata:
+  author: cc-agents
+  platforms: "claude-code,codex,antigravity,opencode,openclaw"
+  category: engineering-core
+  interactions:
+    - pipeline
+    - inversion
+  pipeline_steps:
+    - data-collection
+    - user-input
+    - generate-summary
+    - validate-output
+  openclaw:
+    emoji: "📊"
+see_also:
+  - sp:dev-handover
+  - sp:dev-changelog
+  - sp:spur-cli
+---
+
+# sp:daily-summary — Daily Summary Report Generator
+
+Generate daily summary reports for personal review and AI infrastructure optimization. Combines token usage data (via ccusage), git history, and user annotations into a structured markdown report.
+
+## When to Use
+
+**Trigger phrases:** "daily summary", "end of day", "wrap up", "daily report", "what did I do today"
+
+This command is designed to be run at the end of the workday or first thing the next morning to review previous day's activity.
+
+## Overview
+
+The daily-summary skill:
+1. Collects token usage from ccusage CLI (Claude Code, Codex, etc.)
+2. Extracts git history (commits, changes) for the day
+3. Prompts user for learnings, issues fixed, and pending tasks
+4. Generates a timestamped markdown summary
+5. Outputs to `docs/daily/summary_yyyymmdd.md`
+6. Surfaces the newest history report path when a nightly `spur history daily` artifact exists (R7)
+
+## Quick Start
+
+```bash
+# Generate summary for today
+bun plugins/sp/scripts/daily-summary/daily-summary.ts
+
+# Generate summary for a specific date
+bun plugins/sp/scripts/daily-summary/daily-summary.ts --date 2026-04-17
+
+# Show summary without writing file
+bun plugins/sp/scripts/daily-summary/daily-summary.ts --dry-run
+```
+
+## Workflows
+
+### Phase 1: Data Collection
+
+1. **Parse arguments** — Extract `--date` (default: today) and `--dry-run`
+2. **Collect token usage** — Run `ccusage daily --json` for the date range
+3. **Collect git history** — Run `git log --since` and `git diff --stat`
+4. **Detect AI-related commits** — Parse commit messages for feat/fix/refactor patterns
+
+### Phase 2: User Input
+
+**Ask one question at a time.** Do not start generating the summary until all three prompts have been answered (empty answers allowed — press Enter to skip). The skill blocks on stdin; each question must be answered before the next is shown.
+
+Interactive prompts for annotations:
+```
+Daily Summary — 2026-04-17
+
+Please provide the following (press Enter to skip):
+
+1. What did you learn today? (optional)
+   > 
+
+2. What issues did you fix? (optional)
+   > 
+
+3. What's pending for tomorrow? (optional)
+   > 
+```
+
+### Phase 3: Generate Summary
+
+Assemble sections into `docs/daily/summary_yyyymmdd.md`
+
+### Phase 4: Validate & Output
+
+- Verify file written successfully
+- Display output path to user
+- Show summary statistics
+
+## Input Modes
+
+| Input Pattern | Behavior |
+|---------------|----------|
+| `--date YYYY-MM-DD` | Generate summary for specified date |
+| `--date yesterday` | Generate summary for previous day |
+| `--dry-run` | Show summary without writing file |
+| `--output <path>` | Write to custom path instead of default |
+| `--no-git` | Skip git history collection |
+| `--no-ccusage` | Skip token usage collection |
+
+## Output
+
+**File:** `docs/daily/summary_yyyymmdd.md`
+
+**Sections:**
+
+| Section | Mandatory | Source |
+|---------|-----------|--------|
+| Meta | Yes | Auto-detected (date, platforms) |
+| Token Usage | If ccusage available | ccusage CLI |
+| Git Activity | If git available | git log/diff |
+| Commits | Yes | git log |
+| Issues Fixed | If provided | User input |
+| Learnings | If provided | User input |
+| Pending | If provided | User input |
+| History Report | If a nightly history artifact exists | `.spur/reports/history/latest.json` pointer (R7) |
+
+## Data Sources
+
+| Source | Tool | Data Retrieved |
+|--------|------|---------------|
+| Claude Code usage | ccusage daily | Tokens, cost, conversations |
+| Git history | git log/diff | Commits, files changed |
+| User annotations | Interactive prompt | Learnings, issues, pending |
+
+## Integration
+
+This skill orchestrates existing tools:
+- **ccusage** for token usage data (must be installed)
+- **git** for version control history
+- **User input** for qualitative annotations
+
+## Required Permissions
+
+The skill shells out to external tools. Ensure these are allowed in the agent's permission profile:
+
+| Command | Purpose | Required |
+|---------|---------|----------|
+| `ccusage daily --json` | Token usage telemetry | Optional (skipped with `--no-ccusage`) |
+| `git log`, `git diff`, `git status` | Commit history | Optional (skipped with `--no-git`) |
+| File write to `docs/daily/` | Output markdown report | Required unless `--dry-run` |
+
+## Platform Notes
+
+### Claude Code (primary)
+```bash
+skill(skill="sp:daily-summary", args="--date 2026-04-17")
+```
+
+### Other Platforms
+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
+- **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/daily-summary/agents/openai.yaml

@@ -0,0 +1,13 @@
+name: daily-summary
+description: Generate daily summary reports from AI coding agent usage data, git
+  history, and user annotations. Orchestrates ccusage CLI and git commands to
+  produce structured markdown summaries.
+version: 1.0.0
+icon: 📊
+category: debugging
+tags:
+  - summary
+  - daily
+  - analytics
+  - reporting
+  - engineering-core

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

@@ -0,0 +1,175 @@
+---
+name: doc-evolve
+description: "Evolve docs/00-05 + AGENTS.md per docs/99_PROJECT_CONSTITUTION.md: drift audits, same-commit sync checks, frontmatter-contract verification, lesson-append. Triggers: \"doc evolve\", \"doc drift\", \"sync docs\", \"drift audit\", \"are the docs stale\", \"append a lesson\"."
+license: Apache-2.0
+metadata:
+  author: spur
+  version: "1.0"
+  platforms: "claude-code,codex,openclaw,opencode,antigravity"
+  interactions:
+    - reviewer
+    - inversion
+  operations:
+    - customize
+    - drift-audit
+    - sync-check
+    - contract-verify
+    - lesson-append
+  openclaw:
+    emoji: "📐"
+---
+
+# Spur Doc-Evolve
+
+`sp:doc-evolve` keeps the **key documents** honest: `docs/00_ADR`, `01_PRD`, `02_ROADMAP`,
+`03_ARCHITECTURE`, `04_DESIGN`, `05_FEATURES`, the `99_PROJECT_CONSTITUTION`, and the root
+`AGENTS.md`. It is a **constitution-native** driver — every operation enforces a rule that already
+lives in `docs/99_PROJECT_CONSTITUTION.md`, and every proposed edit cites the section it enforces.
+It is *not* a generic doc generator and it does not invent process: the constitution is the law;
+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;
+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 |
+| **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 |
+
+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`.
+
+## Operating principle (R2): detect deterministically, judge with the LLM
+
+Split every operation into a **deterministic detection** half and a **judgment** half:
+
+- **Detection** is `rg` / `git` / `spur` CLI / frontmatter parsing — it finds candidate drift
+  mechanically and is the part that must not hallucinate (a missed surface or a phantom finding
+  both erode trust). Prefer a command that lists facts over prose that asserts them.
+- **Judgment** is the LLM deciding whether a candidate is real drift, which doc is authoritative,
+  and what the minimal repair is. This is where the skill earns its keep.
+
+Never assert "the docs are in sync" from reading alone — run the detection commands and show their
+output. A zero-finding audit must be backed by the commands that produced zero.
+
+## customize
+
+**Purpose:** Customize a freshly-initialized Spur project's doc templates to match the
+project's actual stack and scope. Invoked by `sp:spur-init` after scaffolding.
+
+**Procedure:**
+1. Read the project's `package.json`, `tsconfig.json`, `biome.json`, and any existing config.
+2. Read each doc in `docs/00`–`05` for any remaining template markers.
+3. For **`AGENTS.md`**, use the **`{kebab-case}`** token scheme only (task 0242). Do **not** use
+   `{{ MUSTACHE }}` for AGENTS:
+   - `{project-name}` / `{project-description}` — already filled by `spur init` when scaffolding a
+     fresh file; do not leave these braces after customize.
+   - Project-specific body slots (`## Stack & layout`, build commands, conventions) use HTML
+     comments + human stubs in the **bundled AGENTS seed** (spur init template) — replace those
+     stubs with stack/layout and lint/test/build commands detected from the project manifests.
+4. Keep portable harness sections aligned with the bundled AGENTS seed (H2 set + Harness tool
+   routing Need keys — see `apps/cli/tests/fixtures/agents-md-portable-contract.ts`).
+
+**Done when:** no residual `{project-name}` / `{project-description}` in AGENTS.md; stack/build
+stubs filled or deliberately documented; `bun run lint` passes where applicable.
+
+## drift-audit (§7)
+
+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
+rg -n "\.command\('" apps/cli/src/commands/        # the true verb list
+rg -n '^#### `spur ' docs/04_DESIGN.md             # 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
+# → 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
+# 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.
+
+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:
+
+| 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).
+
+## contract-verify (§4.3)
+
+For each key doc, confirm its YAML frontmatter is the instantiated §4.1 row:
+
+- `owns` / `authority` match the §4.1 table **verbatim in meaning** (on mismatch, §4.1 wins).
+- `edit_rules` points to the owning §6 subsection (a pointer, never restated prose).
+- `updated_at` is not older than a change it should reflect (cross-check `git log`).
+
+This is mostly mechanical (parse + compare); the judgment is only "is this `updated_at` plausibly
+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>
+```
+
+- **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.
+
+## What this skill is NOT
+
+- **Not a doc generator** — it doesn't author new prose from nothing; it audits, syncs, and repairs
+  against the constitution.
+- **Not the authority** — it never overrides `00`/`01`/§2; on any conflict the authoritative doc
+  wins and the skill defers.
+- **Not a generic doc tool** — this is constitution-native (every operation cites a §). Behaviors
+  without constitution backing are intentionally absent.
+
+## References
+
+| Reference | Covers |
+| --------- | ------ |
+| [references/operations.md](references/operations.md) | The mini-spec: each operation's detection commands, the §-mapping table, and the drift-report shape |
+
+## See also
+
+- **`docs/99_PROJECT_CONSTITUTION.md`** — the law this skill enforces. Always the tiebreaker.
+- **`dev-operations.md §7`** — the `docs` operation entry (no thin command wrapper; invoke this skill directly).