@gobing-ai/spur 0.3.73 → 0.3.74

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

@@ -8,11 +8,11 @@
  * 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.
+ * The gate is deliberately two-sided: 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>
@@ -134,7 +134,7 @@ function scanMarkers(cwd: string, roots: string[]): Map<string, Set<string>> {
     return found;
 }
 
-/** Load the manifest; a missing file degrades to no entries (corpus-check parity). */
+/** Load the manifest; a missing file degrades to no entries (fail-open). */
 function loadManifest(path: string): { entries: ManifestEntry[]; raw: string | null } {
     if (!existsSync(path)) return { entries: [], raw: null };
     const raw = readFileSync(path, 'utf8');

package/plugins/sp/skills/pr-reviewing/SKILL.md

@@ -164,12 +164,15 @@ superskill script contract.
 8. **Collect** — `<script> collect --since "$requestedAt" --head "$requestHead" --json`. Normalize
    only the requested HEAD and request window; then invoke `status` with the same bounds for
    PR/base/CI/local state. Never turn an absent, stale, or moved-HEAD result into `clean`.
+   `--head` is mandatory on wait/collect/status (0771): an empty or missing pin fails loud
+   instead of silently reviewing whatever HEAD is current.
 
 ## Fix mode
 
 Only in `fix` mode:
 
-1. **Collect before editing.** Invoke direct `collect --json` plus `status --json` and require a
+1. **Collect before editing.** Invoke direct `collect --json --head "$(git rev-parse HEAD)"` plus
+   `status --json --head "$(git rev-parse HEAD)"` and require a
    completed result for the current pushed HEAD. If the result is pending, stale, or unavailable,
    report it and stop without source edits. If it is explicitly clean, report no fixes and stop.
 2. **Validate each finding.** Open the referenced code; trace callers/callees; verify the problem

package/plugins/sp/skills/spur-cli/references/self.md

@@ -1,14 +1,14 @@
 ---
 name: spur-cli-self
-description: "spur-cli noun reference for `spur self`: self-management verbs — scaffold (`init`), schema migrations (`migrate`), local web server (`serve`), and status overview (`status`). Each verb mounts the same command builder as its legacy top-level noun, which remains a hidden alias over the identical command."
+description: "spur-cli noun reference for `spur self`: self-management verbs — scaffold (`init`), database maintenance (`maintain`), schema migrations (`migrate`), local web server (`serve`), and status overview (`status`). Each verb mounts the same command builder as its legacy top-level noun, which remains a hidden alias over the identical command."
 see_also:
   - spur-cli
 ---
 
 # spur self - self-management verbs
 
-`spur self` hosts the four self-management verbs. Each verb is the canonical path for a command
-that also remains registered as a legacy top-level **hidden alias** (`spur init`, `spur migrate`,
+`spur self` hosts the self-management verbs. Each verb is the canonical path for a command
+that also remains registered as a legacy top-level **hidden alias** (`spur init`, `spur maintain`, `spur migrate`,
 `spur serve`, `spur status`) so existing scripts, workflow YAML, and habits keep working unchanged.
 Both paths share the same command builder: identical flags, output, and exit codes. The legacy
 top-level forms are omitted from `spur --help`, leaving `self` as the visible surface.
@@ -18,6 +18,7 @@ top-level forms are omitted from `spur --help`, leaving `self` as the visible su
 | Verb | Purpose | Key flags |
 | ---- | ------- | --------- |
 | `init` | Scaffold a new Spur project in the current directory | `--name <name>` `--force` `--minimal` `--json` |
+| `maintain` | Run database maintenance: PRAGMA optimize, WAL truncation, optional VACUUM | `--vacuum` `--json` |
 | `migrate` | Apply CLI-owned schema migrations | `--json` |
 | `serve` | Start the Spur web server (local fallback) | `--port <n>` `--host <addr>` `--no-open` `--cwd <path>` `--json` |
 | `status [path]` | Show project and git status for a Spur project | `--json` |
@@ -43,6 +44,19 @@ Materializes the `.spur/` directory tree with config, docs, rules, and workflow
 (Phase 1.5 / 1.6) run immediately after this verb completes — see **[init.md](init.md)** for the
 probe protocol and rule-glob adaptation procedure.
 
+## `self maintain` - run database maintenance
+
+```bash
+spur self maintain                    # run PRAGMA optimize + wal_checkpoint(TRUNCATE)
+spur self maintain --vacuum           # deep maintenance: VACUUM + optimize + checkpoint
+spur self maintain --json             # machine-readable
+```
+
+Executes SQLite database maintenance operations on `.spur/spur.db`:
+- `PRAGMA optimize;` to refresh query planner statistics in `sqlite_stat1`.
+- `PRAGMA wal_checkpoint(TRUNCATE);` to checkpoint committed WAL frames and truncate WAL to 0 bytes.
+- `--vacuum` runs `VACUUM;` first for page compaction and B-tree defragmentation (requires 2x free disk space).
+
 ## `self migrate` - apply CLI-owned schema migrations
 
 ```bash

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

@@ -51,7 +51,7 @@ re-reading or re-tokenizing the task.
 | `batch-create` | Create many tasks from a validated JSON array | `--file <path>` `--folder` `--json` |
 | `record <wbs>` | Write `Testing` from a verify verdict (deterministic); bare-`## Review` fallback only; optional Solution + transition | `--verdict-file <path>` `--solution-from-diff` `--transition <status>` `--folder` `--json` |
 | `verdict <wbs>` | Derive PASS/PARTIAL/FAIL/UNKNOWN from verify answer text → verdict JSON; see [answer-file shape](tasks/verbs.md#answer-file-shape-what---from-answer-parses) | `--from-answer <path>` `--folder` `--json` |
-| `check [wbs]` | Four-layer validation; the readiness matrix; `--fix` repairs structural findings in place | `--strict` `--as <status>` `--strict-core` `--fix` `--folder` `--json` |
+| `check [wbs]` | Four-layer validation; `--fix` repairs structure; `--corpus` is the explicit unsuppressed audit | `--strict` `--as <status>` `--strict-core` `--fix` `--folder` `--corpus` `--since <ref>` `--json` |
 | `resolve <file-path>` | Map a file path to its owning task WBS | `--strict` `--folder` `--json` |
 | `path <wbs>` | Map a WBS to its absolute task file path (inverse of `resolve`) | `--folder` `--json` |
 | `run-link <wbs>` | Record pipeline run provenance link for task | `--source <src>` `--run-id <id>` `--json` |

package/plugins/sp/skills/spur-cli/references/workflows/workflow-fit-and-tuning.md

@@ -140,10 +140,10 @@ reports it. Do not invent a second threshold; author to the one that is frozen (
 | Node count | Every node earns its transition round-trip | A node that always runs immediately after another, with no guard between them, is one node |
 
 **When a node breaches the budget, do not reformat to dodge the measure.** Joining five lines with
-`&&` moves the complexity, not the ownership. Pick an owner from the five recorded options in
+`&&` moves the complexity, not the ownership. Pick one of the four remaining owners from
 `docs/design/workflow-shell-ownership.md`: public `spur` verb (consent-gated), application service,
-least-privilege built-in action kind, workflow-relative external extension, or a recorded
-stays-shell exception with its reason in `config/workflow-composition-baseline.json`.
+least-privilege built-in action kind, or workflow-relative external extension. (0775 retired the
+recorded stays-shell exception along with the suppression snapshot.)
 
 **Advisory posture is binding.** Composition findings never block a run, never change a `validate`
 exit status, and are never a reason to hot-edit an executing pipeline. Surface them; fix on operator
@@ -193,8 +193,8 @@ Steps:
 2. **Return each node's work to its owner** — judgment nodes to the command or skill they should
    have been calling; a genuinely useful shell sequence to one script under its owning surface.
 3. **Rewrite the entry surface as the procedure**, in the order the graph ran.
-4. **Delete the YAML and its `config/workflow-composition-baseline.json` entries** in the same
-   change. A baseline entry whose action no longer exists fails the two-sided check.
+4. **Delete the YAML** in the same change. (0775 retired the composition-baseline entries that
+   used to be deleted alongside it; the live definition is the only artifact left.)
 5. **Record the demotion** and its trigger, so the next author does not re-promote it by reflex.
 
 ### optimize — refine an accepted workflow in place

package/plugins/sp/skills/spur-cli/references/workflows.md

@@ -231,10 +231,10 @@ agent prompts where a first-class surface would own it better?" — nothing more
   raw prompt length only sets the reported severity (<200 low / ≤1000 medium / >1000 high).
 
 **How to run it:** it is not a separate command — `spur workflow validate <file> --json` returns
-`composition: {findings[], suppressed}` on the valid path; human mode prints the advisory to stderr
-with exit 0. Actions with a recorded disposition in
-`config/workflow-composition-baseline.json` (resolved by walking up from the workflow file) are
-counted in `suppressed`, not `findings`.
+`composition: {findings[]}` on the valid path; human mode prints the advisory to stderr
+with exit 0. Findings are derived from the workflow definition itself
+(`extractResolvedWorkflowFacts`, guarded by `composition-baseline.test.ts`); 0775 retired the
+suppression snapshot, so every finding is reported — none are suppressed.
 
 **How to read it, and the fix path per defect class:**
 

package/plugins/sp/skills/spur-dev/SKILL.md

@@ -153,6 +153,23 @@ CLI does.
 
 ## Gotchas
 
+### Bounded execution and recovery (0777)
+
+- During planning/refinement of corpus-scale work, record an execution budget, persisted-artifact
+  paths and requireDiff guidance in the task Design. For classification-only work, declare
+  `mutationPolicy: none`; its task/evidence change is the deliverable, not invented source edits.
+  Preserve partial artifacts at the budget boundary; resume only against the current task contract.
+- Before accepting a child/watcher result, compare its run ID with the dispatched run ID and check
+  current trace state through Spur. If using a run log as evidence, require its mtime to be at least
+  the dispatch time. A mismatch or stale timestamp is not completion evidence. Do not scrape terminals.
+  Bound each watch invocation to 10 minutes or 20 polls, whichever comes first; persist the last
+  confirmed identity/state and report a checkpoint before continuing. A watcher timeout does not
+  cancel the owned run or authorize launching a replacement.
+- Mark superseded scratch with `SUPERSEDED` and a pointer to the authoritative task Design. Never
+  let a scratch instruction override the live task, even when its old run is still readable.
+- Checker-policy changes require one explicit unsuppressed audit (T10); ordinary corpus commit
+  prep checks affected documents and linked evidence (T11), not the corpus. No acceptance snapshots.
+
 1. **Never skip a gate.** A clean `feature check` is the only proof the AC is valid; a
    passing `batch-create` is the only proof the decomposition is well-formed. Skip either and
    you ship corrupted corpus.

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

@@ -887,9 +887,9 @@ time. Before launching a full `spur-check-new`:
    `console.*`), spawn processes via `NodeProcessExecutor` (no `Bun.spawnSync`), get a
    `runtime-boundaries` fs-io exemption for sync reads (mirrors `task.ts`), and a non-command helper
    must not live in `apps/cli/src/commands/` (the noun scan treats every file there as a noun).
-3. **Doc/TSDoc edits shift `file:line` anchors** cited by other tasks — `corpus-check` surfaces them
-   as `L4.anchor-subject-mismatch`. Repoint the shifted citations (via `spur task update --section`)
-   in the same commit, and reconcile new/stale baseline entries before the gate run.
+3. **Doc/TSDoc edits shift `file:line` anchors** cited by other tasks — the per-task gate surfaces
+   them as `L4.anchor-subject-mismatch` (0775: the corpus sweep retired; run `spur task check <wbs>`
+   on touched tasks). Repoint the shifted citations (via `spur task update --section`)
 
 ## AC traceability
 

package/plugins/sp/skills/spur-dev/references/gate-checklists.md

@@ -170,7 +170,7 @@ transition to `done`.
 > The verify skill writes this shape automatically — operators only need it when hand-authoring
 > an answer file or debugging an UNKNOWN verdict.
 
-> **Corpus baseline discipline (`corpus-check`).** `corpus-check` sweeps every task/feature and fails on any structural finding outside `config/corpus-baseline.json`. The baseline is two-sided: an unlisted finding fails, **and** a listed entry that no longer reproduces fails. When introducing or tightening finding rules, reconcile the fallout in the same commit (constitution **T10**).
+> **Finding-rule discipline (ADR-108).** When checker policy changes, run focused tests and one explicit unsuppressed `bun run corpus-check` audit; record/reconcile essential failures without waivers (T10). Ordinary corpus commit prep checks changed tasks/features and their required linked evidence, not the corpus (T11). The baseline and regenerators remain deleted; tests are not a substitute for the explicit policy-change audit.
 >
 > **Transition-shim discipline (`transition-shim-check`, task 0541 / ADR-058).** Wired as an early step of `spur-check` / `spur-check-new` (second, after `link-check` and before `lint`) so a shim violation fails in ~0.3 s rather than after the test run. Two-sided against `config/transition-shims.json`: an `@transition-shim(<id>)` marker with no manifest entry fails as a **new unregistered shim**, **and** a listed entry whose marker is gone from source fails as a **stale entry**. Emptying the manifest is the definition of the agent-role transition being complete. A removal condition must be objectively checkable against the repository. Shapes: `docs/04_DESIGN.md` §2.5.
 
@@ -188,4 +188,3 @@ transition to `done`.
 > failure is not yours. This costs seconds and mutates nothing — do **not** `git stash` to get a
 > clean baseline on a shared working tree. Treat any failure that does *not* name a port/listen/`ps`
 > cause as yours until proven otherwise; the count is a moving baseline, not a constant.
-

package/plugins/sp/skills/wayfinder/SKILL.md

@@ -147,7 +147,7 @@ Invoked when a map already exists (operator provides the feature ID). A ticket i
    — no task is claimed, and it does not consume the session's one ticket.
 
 5. **Record the resolution.** Post the answer in the task body, then `spur task update <wbs> done`. Append one line to the map's **## Decisions so far**: `- [<WBS> <title>](path) — <one-line gist of the answer>`.
-6. **Graduate fog into new tickets.** Any fog the answer has made specifiable becomes fresh child tasks (create-then-wire). Clear each graduated patch from **### Not yet specified** so it lives only as its new ticket. Doing half of this — deleting the fog without creating the ticket — destroys the only record the work was ever identified, so `corpus-check` fails the branch (`corpus.ungraduated-fog`) unless the removal is matched by a new/re-parented ticket or a line in **### Out of scope**.
+6. **Graduate fog into new tickets.** Any fog the answer has made specifiable becomes fresh child tasks (create-then-wire). Clear each graduated patch from **### Not yet specified** so it lives only as its new ticket. Doing half of this — deleting the fog without creating the ticket — destroys the only record the work was ever identified; the `corpus.ungraduated-fog` sweep retired in 0775 — enforcement is review-time discipline.
 7. **Rule out mis-scoped tickets.** If the answer reveals a ticket sits beyond the destination, close it and add one line to **### Out of scope** (the gist + why it's out of scope, linking the closed ticket). A scope boundary is not a step on the route — it stays out of **## Decisions so far**.
 8. **Stop after ONE ticket.** Never resolve more than one per session.