@gobing-ai/spur 0.3.41 → 0.3.43

package/plugins/sp/skills/issue-finding/examples/session-test-loop.jsonl

@@ -0,0 +1,23 @@
+{"type":"session","timestamp":"2026-07-29T12:00:00.000Z","id":"fixture-session-test-loop"}
+{"type":"title","title":"Run0376 fixture — repeated failing tests"}
+{"type":"message","timestamp":"2026-07-29T12:01:00.000Z","message":{"role":"assistant","content":[{"type":"toolCall","name":"bash","input":{"command":"bun test packages/app/tests/services/feature-check.test.ts"}}]}}
+{"type":"message","timestamp":"2026-07-29T12:03:00.000Z","message":{"role":"tool","content":[{"type":"toolResult","name":"bash","output":"error: 2 tests failed\nGuardDeniedError: not applicable here"}]}}
+{"type":"message","timestamp":"2026-07-29T12:04:00.000Z","message":{"role":"assistant","content":[{"type":"toolCall","name":"bash","input":{"command":"bun test packages/app/tests/services/feature-check.test.ts"}}]}}
+{"type":"message","timestamp":"2026-07-29T12:06:00.000Z","message":{"role":"tool","content":[{"type":"toolResult","name":"bash","output":"error: 2 tests failed"}]}}
+{"type":"message","timestamp":"2026-07-29T12:07:00.000Z","message":{"role":"assistant","content":[{"type":"toolCall","name":"bash","input":{"command":"bun test packages/app/tests/services/feature-check.test.ts"}}]}}
+{"type":"message","timestamp":"2026-07-29T12:09:00.000Z","message":{"role":"tool","content":[{"type":"toolResult","name":"bash","output":"error: 2 tests failed"}]}}
+{"type":"message","timestamp":"2026-07-29T12:10:00.000Z","message":{"role":"assistant","content":[{"type":"toolCall","name":"bash","input":{"command":"bun test packages/app/tests/services/feature-check.test.ts"}}]}}
+{"type":"message","timestamp":"2026-07-29T12:12:00.000Z","message":{"role":"tool","content":[{"type":"toolResult","name":"bash","output":"error: 2 tests failed"}]}}
+{"type":"message","timestamp":"2026-07-29T12:13:00.000Z","message":{"role":"assistant","content":[{"type":"toolCall","name":"bash","input":{"command":"git stash"}}]}}
+{"type":"message","timestamp":"2026-07-29T12:14:00.000Z","message":{"role":"assistant","content":[{"type":"toolCall","name":"bash","input":{"command":"git status && git diff"}}]}}
+{"type":"message","timestamp":"2026-07-29T12:15:00.000Z","message":{"role":"assistant","content":[{"type":"toolCall","name":"bash","input":{"command":"spur task check 0376"}}]}}
+{"type":"message","timestamp":"2026-07-29T12:16:00.000Z","message":{"role":"tool","content":[{"type":"toolResult","name":"bash","output":"error: L3 format failure — bare :line citation"}]}}
+{"type":"message","timestamp":"2026-07-29T12:17:00.000Z","message":{"role":"assistant","content":[{"type":"toolCall","name":"bash","input":{"command":"spur task check 0376"}}]}}
+{"type":"message","timestamp":"2026-07-29T12:18:00.000Z","message":{"role":"tool","content":[{"type":"toolResult","name":"bash","output":"error: L3 format failure"}]}}
+{"type":"message","timestamp":"2026-07-29T12:19:00.000Z","message":{"role":"assistant","content":[{"type":"toolCall","name":"bash","input":{"command":"spur task check 0376"}}]}}
+{"type":"compaction","timestamp":"2026-07-29T12:20:00.000Z"}
+{"type":"compaction","timestamp":"2026-07-29T12:25:00.000Z"}
+{"type":"compaction","timestamp":"2026-07-29T12:30:00.000Z"}
+{"type":"compaction","timestamp":"2026-07-29T12:35:00.000Z"}
+{"type":"compaction","timestamp":"2026-07-29T12:40:00.000Z"}
+{"type":"compaction","timestamp":"2026-07-29T12:45:00.000Z"}

package/plugins/sp/skills/issue-finding/references/session-formats.md

@@ -0,0 +1,151 @@
+---
+name: session-formats
+description: "Multi-source session log roots, tool-call field maps, OMP deep dive, and spur history bridge for sp:issue-finding."
+see_also:
+  - issue-finding
+---
+
+# Session log formats — multi-source discovery
+
+`sp:issue-finding` analyzes **raw session JSONL** for tool-loop forensics. Layout and event
+shapes differ by coding agent. This file is the SSOT for DISCOVER path selection and ANALYZE
+field mapping.
+
+**Confidence legend**
+
+| Level | Meaning |
+|-------|---------|
+| High | Documented adapter used successfully on real sessions (OMP) |
+| Medium | Default roots from Spur history help / importer sources; parse best-effort |
+| Low | Operator must pass `--sessions`; field map incomplete |
+
+## Source → default root
+
+| `--source` | Default root (expand `~`) | History import source | Fidelity |
+|------------|---------------------------|----------------------|----------|
+| `omp` | `~/.omp/agent/sessions/-<project-slug>/` | *(not a history source name)* | High |
+| `claude` | `~/.claude/projects/` | `claude` | Medium |
+| `codex` | `~/.codex/sessions/` | `codex` | Medium |
+| `gemini` | `~/.gemini/sessions/` | `gemini` | Medium |
+| `opencode` | agent-specific OpenCode session store (varies by install) | `opencode` | Low–Medium |
+| `antigravity` | agent-specific Antigravity session store | `antigravity` | Low–Medium |
+| `openclaw` | OpenClaw / `~/.agents/` session trees when present | `openclaw` | Low–Medium |
+| `pi` | Pi conversation/session roots (see `spur history` examples) | `pi` | Medium |
+| `auto` | Detect: prefer explicit agent if known; else first existing root among `omp`, `claude`, `codex`, `pi`, `gemini` | maps when importing | — |
+
+**Project slug (OMP):** path under the sessions root is typically the project path with `/`
+replaced (e.g. `/Users/…/xprojects/spur-new` → `-Users-…-xprojects-spur-new` or
+`-xprojects-spur-new` depending on host layout). List the sessions parent and pick the directory
+that matches the cwd project when ambiguous.
+
+**When the default root is missing or empty:** stop guessing. Ask for a path or require
+`--sessions <glob>`.
+
+## Portable tool-call map
+
+When parsing a line of JSONL, look for tool/function invocations under common shapes:
+
+| Source family | Typical tool block type / path | Bash/command field |
+|---------------|--------------------------------|--------------------|
+| OMP / omp-agent | `message.content[]` entries with `type: "toolCall"` | `input.command` |
+| Claude Code | `type: "tool_use"` (or nested message content) | `input.command` / `input` |
+| Codex / others | Importer-normalized or vendor-specific; search for `command`, `tool_name`, `name` | best-effort |
+
+Always record **what field path you used** in the inventory Notes so evidence is auditable.
+
+**Loop detection (all sources):** normalize the shell command string and count consecutive or
+near-consecutive identical invocations (≥3) without an intervening source-file edit tool call.
+
+## OMP deep dive (High fidelity)
+
+OMP/agent session logs are JSONL under `~/.omp/agent/sessions/-<project>/`:
+
+- Each line is a JSON object with a `type` field
+- Key event types: `session`, `message`, `compaction`, `title`, `title_change`, `custom`
+- Tool calls live in `message.content` as blocks with `type: "toolCall"` (**not** `tool_use`)
+- Bash tool calls expose `input.command`
+- Subagent sessions live in subdirectories (e.g. `Run0376/`, `Refine0378/`)
+- Subagents may have `*.log` beside the JSONL session file
+- Session start: `session.timestamp`
+- Session title: `title.title` (often auto-generated from the first user message)
+- Session id pattern: `<ISO-timestamp>_<UUID>.jsonl`
+- Cross-session: subagent messages may carry `parentId` linking to the parent session
+
+**Discovery without `--sessions`:** list the project sessions directory; take the newest
+timestamped main session file; include sibling subagent JSONL under that session’s tree.
+
+## Claude / Codex / Pi / Gemini (Medium)
+
+Documented import examples (see `docs/help/cmd_history.md`):
+
+```bash
+spur history import --source claude --root ~/.claude/projects --mode incremental
+spur history import --source codex --root ~/.codex/sessions/ --mode incremental
+spur history import --source gemini --root ~/.gemini/sessions/ --mode full
+spur history import --source pi --file ~/pi/logs/conversation.jsonl
+```
+
+For issue-finding:
+
+1. Prefer raw JSONL under those roots for tool-loop analysis.
+2. Use `--sessions` when multiple projects share a root.
+3. Tool event shapes may differ from OMP — use the portable map; do not force `toolCall`-only parsing.
+
+## History bridge (`--use-history`)
+
+`spur history` holds **validated ETL + ledger**, not a full replacement for forensic JSONL:
+
+| Need | Use |
+|------|-----|
+| Token / cost aggregates | `spur history analyze [--since …] --json` after import |
+| Identical test-command loops, guard retries, git red herrings | Raw session JSONL (this skill’s primary path) |
+| Multi-agent cost rollups | Import per source, then analyze |
+
+Import does not invent bottleneck categories. If import fails or the DB is empty, continue with
+raw logs and note that cost data is unavailable.
+
+**Schema-first rule (task 0506 R3):** history tables are owned by
+`@gobing-ai/ts-llm-jsonl-importer` and can change between versions — never copy column lists
+into this skill. Before any ad-hoc verification SQL that references importer-owned `history_*`
+tables, run **one** schema-introspection query for every table you need and compose the data
+queries from that result:
+
+```bash
+# one introspection pass, then write data queries against what it reports
+sqlite3 <db> "SELECT name, sql FROM sqlite_schema WHERE type='table' AND name LIKE 'history_%';"
+# (or a single `.schema history_<table>` invocation per referenced table)
+```
+
+If a column you expected is absent, trust the live schema — do not guess. The importer's
+`HISTORY_IMPORT_SCHEMA_SQL` is the authority; this skill holds no duplicate column contract.
+
+**Selected-file bridge (task 0507 R3):** `--use-history` imports the frozen Phase-1 file set one
+file at a time — never a root scan, never a full reconciliation. Ambient discovery covers the
+normal OMP root (`~/.omp/agent/sessions/`) **and** workflow subprocess sessions under
+`.spur/run/<run-id>/agent-sessions/<omp-executor>/*.jsonl` (same `type: "message"` envelope). For
+each file, the session key is the JSONL filename stem (importer `sessionIdFromContext`); import and
+analyze per key:
+
+```bash
+bun run apps/cli/src/index.ts history import --source omp --file <absolute-file> --mode force-file --json
+bun run apps/cli/src/index.ts history analyze --session <filename-stem> --json
+```
+
+ETL owns token/cost/message/tool/loop/assistant-duration aggregates; raw JSONL stays authoritative
+for command text, compactions, test/guard retries, and tool execution duration/status/errors.
+
+## Edge cases
+
+| Scenario | Handling |
+|----------|----------|
+| No session root found | Fail DISCOVER with a clear message; request `--sessions` |
+| Huge multi-hour JSONL | Prefer Grep/rg for signal patterns first; sample then deep-read hot regions |
+| Mixed agents in one investigation | Run per `--source` or pass an explicit multi-file `--sessions` glob; label each session’s source |
+| Only transcript markdown available | Medium/Low confidence; extract commands from fenced blocks if present; mark evidence quality |
+| Redacted / truncated logs | Analyze what remains; do not invent tool counts |
+
+## Related
+
+- Skill entry: [../SKILL.md](../SKILL.md)
+- History CLI: `spur history --help`, `docs/help/cmd_history.md`
+- Daily usage (not session forensics): `sp:daily-summary` / ccusage

package/plugins/sp/skills/next-feature/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: next-feature
+description: "Prompt-first feature frontier prioritizer — answers 'which feature should we work on now?' by deriving importance/urgency from corpus, git, and authority-doc evidence, and emits rank-distorting tree defects as proposals /sp:dev-featurechange consumes. Triggers: find next, which feature, feature ranking, frontier priority, what should I work on."
+license: Apache-2.0
+version: 1.0.0
+metadata:
+  author: spur
+  platforms: "claude-code,codex,openclaw,opencode,antigravity,pi"
+  category: analysis-core
+  interactions:
+    - audit
+    - recommendation
+  pipeline_steps:
+    - sync-check
+    - gate
+    - derive
+    - rank
+    - report
+    - dispatch
+see_also:
+  - sp:next-router
+  - sp:spur-cli
+  - sp:conflict-finding
+  - sp:spur-dev
+---
+
+# sp:next-feature — Feature Frontier Prioritizer
+
+A prompt-first prioritizer that answers **"which feature should we work on now?"** — the question
+`sp:next-router` deliberately does not answer (`routing-table.md` §0 step 1c: target omitted → not
+v1). It derives importance and urgency from evidence already in the corpus, ranks the actionable
+frontier in **tiers with per-candidate evidence**, and emits rank-distorting tree defects as
+**proposals** `/sp:dev-featurechange` consumes.
+
+**Honesty contract:** prompt-first. The model applies the rubric; existing deterministic tools
+(`spur feature|task … --json`, `git`, `rg`) gather facts. No TypeScript analyzer, no numeric scores,
+no new spur verbs, no feature frontmatter fields. The `priority` field is never used as an ordering —
+in this corpus it is 76% one value (0493 measurement).
+
+**Propose, never apply.** This skill performs no `spur feature move` and writes nothing under
+`docs/features/**`. The only path from a structure proposal to a changed tree is
+`/sp:dev-featurechange` (dry-run → confirm → apply). Ranking runs are read-only; the sole exception is
+`--task`, which after an **explicit operator confirm** dispatches `/sp:dev-plan` and
+`/sp:dev-refineall` — commands that write `docs/tasks*/` through their own gates. This skill still
+creates no tasks itself.
+
+## When to Use
+
+- "Which feature next?" / "what should I work on?" / "rank the frontier" / "find next"
+- Portfolio hygiene: which features are stale-done, blocked, or ill-specified.
+
+**Do NOT use for:**
+
+- Advancing an already-chosen task or feature — that is `/sp:dev-next` (`sp:next-router`).
+- Applying tree changes — that is `/sp:dev-featurechange` (feature F31).
+- Task-level ordering inside a feature — next-router's TABLE A owns that.
+
+## Protocol
+
+Run the steps in order. Each step's depth lives in its reference; this file is the spine.
+
+0. **Sync-first precondition.** `spur feature sync --all --dry-run --json`. Feature `status` is
+   bookkeeping, not ground truth (0493 measured 96% drift on this tree). If any proposal would
+   change a frontier feature's status, the report **leads with the drift summary** ("sync first")
+   and the ranking is computed over the *post-sync* status view. Details:
+   [references/signal-derivation.md](references/signal-derivation.md) §0.
+1. **Assemble the candidate set.** `spur feature list --json`; drop `done`/`cancelled`, drop
+   structural containers (has children, no own open tasks — defect D1), drop the map/feature that
+   owns this investigation if present. The `group` tag is **not** a reliable container marker (D3).
+2. **Gate on actionability.** Read the frontier predicate **at runtime** from
+   `plugins/sp/skills/next-router/references/routing-table.md` row **B3** — this skill intentionally
+   does not copy it. A feature with zero open, unblocked child tasks is **gated, not ranked**;
+   record the reason (all tasks terminal / blocked on X / no tasks). See
+   [references/signal-derivation.md](references/signal-derivation.md) §1.
+3. **Derive the four surviving signals** per gated survivor — AC coverage, churn exposure, dogfood
+   proximity, authority pull — with the exact commands in
+   [references/signal-derivation.md](references/signal-derivation.md) §2. A signal that comes back
+   degenerate on the current frontier is reported as rejected-with-spread, never silently dropped.
+4. **Tier, don't score.** Place each candidate per
+   [references/ranking-rubric.md](references/ranking-rubric.md): ordinal tiers, explicit
+   tie-breaks, evidence per candidate. No candidate carries a number derived from estimates the
+   corpus does not hold.
+5. **Defect pass.** Check the tree for rank-distorting defects D1–D4 per
+   [references/proposal-contract.md](references/proposal-contract.md). Each emitted proposal
+   conforms to the `docs/plans/feature-tree-restructure-map.md` schema and clears the evidence bar
+   (`false_positive_check` mandatory). **Silence is a valid outcome.**
+6. **Report + handoff.** Ranked frontier table + gated list + proposals, per
+   [references/handoff-routing.md](references/handoff-routing.md). Without `--task` the report stops
+   at the ranking; advancing a chosen feature is `/sp:dev-next`'s job.
+7. **`--task` only — confirm, then dispatch the planning half.** Offer the rank-1 candidate (or the
+   id passed as `--task <feature-id>` — which may name a **gated** feature, since T2/T3/T4 are tiers
+   the rubric assigns to the gated list and only T1 comes from the ranked frontier), take an
+   **explicit** operator confirmation, then route on the
+   tier step 4 already assigned: T3 with zero tasks → `/sp:dev-plan --feature <id>` then
+   `/sp:dev-refineall --feature <id> --auto --depth ready`; T1 → refineall only; T3 with invalid AC,
+   T2, and T4 stop with their reason. **This skill creates no tasks itself** — the dispatched
+   commands own decomposition and its schema gate. The confirm pauses regardless of `--auto`. Full
+   contract: [references/handoff-routing.md](references/handoff-routing.md).
+
+## Anti-patterns — do not do these
+
+- Ranking by the `priority` frontmatter field (degenerate; fakes a signal).
+- Ranking a feature whose actionability gate fails. Gate first, rank second.
+- Emitting a numeric score (WSJF/RICE arithmetic) from absent value/effort estimates.
+- Copying the B3 predicate into this skill. Cite it; read it at runtime.
+- Any `spur feature move`, or writing proposals anywhere `docs/features/**` — featurechange owns apply.
+- Decomposing a feature here, or calling `spur task create` / `spur task batch-create` under `--task`.
+  Dispatch `/sp:dev-plan`; it owns decomposition and the batch-create schema gate. Equally: skipping
+  the `--task` confirm because `--auto` was passed, or decomposing a T1 feature that already has a
+  live task frontier.
+- Padding the defect list with tidiness findings that move no rank.
+- Re-proposing F31's rejected merges (B∪H, J∪K body-merge) or reading
+  `## Applied mapping` as current state — letters are recycled; resolve against live features.
+
+## References
+
+| File | Owns |
+| --- | --- |
+| [references/signal-derivation.md](references/signal-derivation.md) | Sync precondition, B3 runtime citation, per-signal derivation commands, degenerate-spread rejection |
+| [references/ranking-rubric.md](references/ranking-rubric.md) | Tier definitions, tie-breaks, evidence-per-candidate output contract |
+| [references/proposal-contract.md](references/proposal-contract.md) | D1–D4 defect set, evidence bar, mapping-schema conformance, silence |
+| [references/handoff-routing.md](references/handoff-routing.md) | featurechange handoff, next-router seam, the `--task` tier→hop routing table and its confirm contract |
+
+Grounding: tickets 0493 (measured signals), 0494 (reuse ledger), 0495 (defect contract) under
+feature H12.

package/plugins/sp/skills/next-feature/references/handoff-routing.md

@@ -0,0 +1,92 @@
+# Handoff routing — featurechange handoff, next-router seam, conditional dispatch
+
+## The seam with `/sp:dev-next` (next-router)
+
+- `/sp:dev-find-next` answers **"which X"**; `/sp:dev-next` answers **"what step for chosen X"**.
+- next-router's routing-table §0 step 1c declares the target-omitted case out of v1 — this command
+  fills exactly that hole and no more. Never re-implement within-target routing (TABLE A/B).
+- When the operator picks a winner from the ranked report, the printed handoff line is:
+  `/sp:dev-next <feature-id>`.
+
+## The handoff to `/sp:dev-featurechange` (feature F31)
+
+Defect proposals follow the 0495 Artifact C boundary, traced end to end:
+
+| Step | Actor | Mutates `docs/features`? |
+| --- | --- | --- |
+| 1. Detect + emit proposal rows | this skill | No |
+| 2. Handoff | printed inline in the report (report reading of OQ1) | No |
+| 3. `--dry-run` | `/sp:dev-featurechange` | No |
+| 4. Confirm | operator | — |
+| 5. `--apply` (`spur feature move`) | `/sp:dev-featurechange` only | **Yes — sole writer** |
+
+There is no path from this skill to a mutated tree that bypasses step 4. Proposal rows are printed
+inline in the default report; writing them into `docs/plans/feature-tree-restructure-map.md` as new
+rows is allowed (that file is the handoff artifact, not corpus) but never required.
+
+## `--task` — confirmed dispatch into the planning half
+
+OQ1 (dispatch vs report) is **resolved** (task 0498): the command dispatches, and the dispatch target
+is the **planning half**, not `/sp:dev-next`. The useful follow-on to "which feature should we work on
+now?" is a set of implement-ready tasks under that feature, not within-target step routing.
+
+Without `--task`, behaviour is unchanged — print the report and stop.
+
+### Compose, never rebuild
+
+This skill **creates no tasks**. It invokes neither `spur task create` nor `spur task batch-create`,
+and it carries no decomposition procedure. Two existing surfaces already own that work, both gated:
+
+| Need | Owner | Gate it enforces |
+| --- | --- | --- |
+| Feature → task set | `/sp:dev-plan --feature <id>` | `spur feature check`, then `task-batch.schema.json` + atomic `spur task batch-create` |
+| Tasks → implement-ready | `/sp:dev-refineall --feature <id> --auto --depth ready` | the implement-ready checklist (`dev-operations.md` §5) |
+
+A decomposer inside this skill would duplicate `sp:spec-decomposition` and bypass the batch-create
+schema gate. That is the CLI-gated-corpus-writes non-negotiable, not a style preference.
+
+### Routing — keyed to the tier already assigned
+
+Read the tier from protocol step 4. **Do not re-derive it.** No new classification logic exists here,
+so a change to `ranking-rubric.md` cannot desynchronise this table.
+
+**`--task` spans the ranked frontier *and* the gated list.** Only **T1** comes from the ranked
+frontier; **T2/T3/T4** are tiers the rubric assigns to *gated* features (`ranking-rubric.md`: T2 is
+"fails the gate, but would be T1 if unblocked"; T4 is the gate reason "all tasks terminal"). A
+feature with zero tasks is gated at step 2 and tiered **T3** — so restricting `--task` to gate
+survivors would make its primary case unreachable. Offer the rank-1 ranked candidate by default;
+`--task <feature-id>` may name any tiered feature, gated or not.
+
+| Tier of confirmed target | State | Action |
+| --- | --- | --- |
+| **T3 — specify first** | valid AC, zero tasks | `/sp:dev-plan --feature <id>` → then `/sp:dev-refineall --feature <id> --auto --depth ready`. **The primary case** — automates `ranking-rubric.md`'s own "decompose T3 candidates". |
+| **T3 — specify first** | AC placeholder / invalid | **Stop.** Print `/sp:dev-plan --feature <id>` and the reason. This is next-router row **B4**: plan continuation needs an operator description — never invent idea text. |
+| **T1 — work now** | open unblocked tasks exist (B3 passed) | `/sp:dev-refineall --feature <id> --auto --depth ready` **only**. Never decompose — a T1 feature has a live frontier by construction, so a second decomposition manufactures duplicates. |
+| **T2 — unblock first** | gated on a blocker | **Refuse.** Name the blocker and its owner. Tasks created under a blocked feature cannot run. |
+| **T4 — stale-done** | post-sync status would be `done` | **Refuse.** Route to `/sp:dev-wrapall --feature <id>` or the sync-first block; the work is finished, not startable. |
+
+### The confirmation is unconditional
+
+| Rule | Detail |
+| --- | --- |
+| Default offer | The rank-1 candidate. The operator may confirm it, name another candidate from the report, or decline. |
+| `--task <feature-id>` | An explicit id skips the *default-offer* step. It does **not** skip the confirm. |
+| `--auto` | Forwarded to the dispatched children (`dev-plan --auto`, `dev-refineall --auto`). It **never** answers the confirm — choosing what to invest in is a taste decision (Auto-Decision Principle #5), and `ranking-rubric.md` already states the operator overrides the ranking. |
+| No escape | There is no `--yes` / `--force` bypass. No path exists from `--task` to a created task file without an explicit operator decision. |
+| Refusal | Declining ends the run at the report. Nothing is written. |
+
+### What `--task` does not change
+
+The defect half is untouched: still no `spur feature move`, still nothing written under
+`docs/features/**`, still `/sp:dev-featurechange` as the sole applier of structure proposals. `--task`
+adds one gated path to `docs/tasks*/`, through commands that own their own gates.
+
+## Where outputs go
+
+| Output | Destination |
+| --- | --- |
+| Ranked frontier + gated list | stdout report (markdown table; `--json` envelope if the flag is passed) |
+| Defect proposals | stdout; optionally appended to `docs/plans/feature-tree-restructure-map.md` |
+| "Sync first" block | top of report when the dry-run proposes frontier changes |
+| Winner handoff | printed `/sp:dev-next <id>` hint — operator runs it |
+| `--task` dispatch | after an explicit confirm: `/sp:dev-plan` and/or `/sp:dev-refineall`, which write `docs/tasks*/` through their own gates |

package/plugins/sp/skills/next-feature/references/proposal-contract.md

@@ -0,0 +1,49 @@
+# Proposal contract — D1–D4 defect set, evidence bar, mapping-schema conformance
+
+Structure-defect detection is bounded by ranking: a defect qualifies only if it measurably moves a
+rank (0495). Untidiness that moves no rank is not emitted. **Silence is the expected steady state.**
+
+## The defect set (0495 Artifact A, frozen)
+
+| # | Defect | Signal corrupted | Direction | Detection |
+| --- | --- | --- | --- | --- |
+| **D1** | Container counted as rankable work-item (has children, zero own open tasks) | All four — dilutes the denominator | Suppresses real ranks | Feature has children AND no own open tasks, yet appears in the candidate set |
+| **D2** | Near-duplicate features (two ids, one product surface) | Churn, AC coverage — splits one concept across two ids | Inflates spread / suppresses the true concept | Name + Goal/Scope overlap; **requires the intentional-split check below** |
+| **D3** | Unreliable container marker (children present, no `group` tag) | Dogfood, AC coverage — lets containers into the candidate set | Inflates candidate set | `frontmatter.tags` vs child-count mismatch |
+| **D4** | Historical mapping read as current tree (recycled letters) | Authority pull, churn — proposes moves for dead features or the wrong live one | Corrupts the tree, not just the rank | Resolve every `old_id` against `spur feature list --json`; a live feature whose `created_at` post-dates the applied mapping is a different feature |
+
+Defects justified only by a 0493-rejected signal (fan-out, status-based urgency, staleness) are
+dropped by construction. Hygiene conditions owned by next-router rows B4–B7 (missing/invalid AC,
+zero tasks, all-done-but-open, mixed cancelled/done) are **deferred** — the de-duplication invariant:
+B4–B7 fire on `frontier tasks == 0`; this detector fires on frontier-corrupting structure. One
+surface speaks per feature (0495 Artifact B).
+
+## Evidence bar (mirrors `sp:conflict-finding` finding-contract)
+
+Every emitted proposal carries:
+
+1. **The signal corrupted** (from the four survivors), the direction of error, and the detection
+   method — not just "K and F8 overlap".
+2. **A `false_positive_check`** ruling out the four challenge classes
+   (`plugins/sp/skills/conflict-finding/references/finding-contract.md:100`, classes at `:105-110`):
+   lifecycle, supersession, abstraction level, **intentional deprecation**. A proposal that cannot
+   clear them is demoted to `confidence: low` candidate or dropped. (Worked example: the K⊕F8
+   near-duplicate is a **low-confidence candidate**, because K's Scope documents the split as
+   intentional — `docs/features/K_features-module-spur-board.md:26`.)
+3. **Two opposing anchors** for contradiction/stale types (`finding-contract.md:153`): D2 quotes both
+   features' Goal/Scope; D4 cites both the map row and the live feature's `created_at`.
+
+## Proposal format — conformance to the existing mapping schema
+
+Proposals conform to `docs/plans/feature-tree-restructure-map.md` `## Schema` (`:10`; dispositions at
+`:15`): `old_id | disposition | new_parent | expected_new_id | rationale | conf | task_edge_notes |
+docs_root_refs`. No second schema. Detector rules that need no tree edit (D1/D3 exclusion, D4
+live-resolution) are reported as **rules**, not proposal rows.
+
+**Suppression list.** `## Rejected merges` (`:54`) is loaded at start: B∪H and the J∪K body-merge are
+never re-proposed. `## Applied mapping` (`:78`) is a historical record, never current state (D4).
+
+## Silence
+
+A tree with no D1–D4 instances produces **zero proposals** — the expected steady state, printed as a
+one-line "no rank-distorting defects found", never padded with tidiness findings.

package/plugins/sp/skills/next-feature/references/ranking-rubric.md

@@ -0,0 +1,52 @@
+# Ranking rubric — ordinal tiers, explicit tie-breaks, evidence per candidate
+
+The corpus carries no value/effort estimates, so no numeric score is honest (0493: WSJF/RICE/CD3
+rejected for absent denominators; Eisenhower's tiered shape selected with modification). The rubric
+produces **tiers with evidence**, and the operator overrides.
+
+## Tiers
+
+| Tier | Meaning | Placement rule |
+| --- | --- | --- |
+| **T1 — work now** | Actionable and high-leverage | Passes the gate; strong on ≥2 surviving signals |
+| **T2 — unblock first** | Highest-value work that is gated | Fails the gate, but would be T1 if unblocked; report the blocker and who owns it |
+| **T3 — specify first** | Not ready to be worked | 0 AC scenarios, or zero dogfood contact, or a container with no own work — most valuable to *specify*, not to start |
+| **T4 — stale-done / hygiene** | Finished work wearing an open status | Post-sync would be `done`; the valuable action is wrap/sync, not ranking |
+
+A candidate appears in exactly one tier. T2 exists because the gate is not a trash bin: H1-class
+features (blocked externally, highest churn, richest AC) must stay visible with their blocker named.
+
+## Tie-breaks (in order, within a tier)
+
+1. **Churn exposure** — higher cost of delay first.
+2. **AC coverage** — more completely specified first.
+3. **Authority pull** — named in roadmap/ADR first.
+4. **Closure pressure** — work that reduces the count of open/active features outranks work that
+   raises it (finish-before-start; post-sync WIP makes this a weak tie-break, not a dominant axis).
+5. **Feature id** — deterministic final ordering.
+
+## Output contract — per candidate row
+
+Every ranked candidate row carries the evidence that placed it:
+
+```text
+| rank | feature id + name | tier | evidence |
+```
+
+`evidence` cites the derived signals with their numbers (`churn 368 commits/40d on packages/app +
+plugins/sp; 70 AC scenarios; named in roadmap §3`) — not adjectives. A rank with prose justification
+and no command-derived number or `file:line` citation is a defect in the report, not a ranking.
+
+## The gated list
+
+Gated features are listed **separately, never ranked**, each with its gate reason from the
+actionability pass (`blocked: 0142 — external trigger` / `no open tasks` / `all tasks terminal`).
+Features whose gate reason is "all tasks terminal" are T4 candidates — say so once, in the sync-first
+block, rather than repeating per row.
+
+## The empty-frontier case
+
+If the post-sync actionable frontier is empty, the honest report is: **"None — sync first, unblock
+T2 candidates, or decompose T3 candidates."** An empty frontier is a finding, not a failure. 0493
+measured exactly this state on 2026-08-10: 25 candidates → 22 stale-done, 2 externally blocked,
+1 stale stub → 0 actionable.

package/plugins/sp/skills/next-feature/references/signal-derivation.md

@@ -0,0 +1,67 @@
+# Signal derivation — sync precondition, actionability gate, measured signals
+
+Every signal derives from the corpus as it stands: existing `spur … --json` verbs, `git`, `rg`, and
+authority docs. No frontmatter field, schema, or verb is added to support a signal. A signal that
+cannot be derived is reported as **unavailable**, never fabricated.
+
+## §0 — Sync-first precondition (step zero)
+
+```bash
+spur feature sync --all --dry-run --json
+```
+
+Feature `status` is manual bookkeeping and drifts (0493: 24 of 25 rankable features would change
+status on sync). Rules:
+
+- If the dry run proposes status changes for any candidate-set feature: the report leads with a
+  **"sync first"** block listing the proposals, and all downstream ranking uses the **post-sync**
+  status view (apply the proposals in memory; do not run the mutating sync).
+- Urgency signals premised on raw `status` (sunk-work decay, WIP pressure, staleness) are computed
+  only against the post-sync view — 0493 rejected all three as standalone signals; post-sync they
+  survive only as tie-break texture (see ranking-rubric.md).
+
+## §1 — Actionability gate (runtime citation, never restated)
+
+**The predicate is SSOT'd in `plugins/sp/skills/next-router/references/routing-table.md` row B3.**
+Read that row at execution time; this file intentionally does not copy it. (If the row is ever
+renamed, the fallback key is its content: "frontier = open ∧ unblocked".)
+
+Inputs per candidate feature:
+
+```bash
+spur task list --feature <id> --json
+```
+
+Apply B3 over the feature's tasks. **Zero actionable tasks ⇒ gated, not ranked.** Record the gating
+reason verbatim for the report's gated list: `all tasks terminal` / `blocked: <task wbs> — <reason>`
+/ `no tasks`. A blocked task with no corpus dependency is an **external** block (approval, trigger) —
+report it as such; it is not satisfiable by ranking other work first.
+
+## §2 — The four surviving signals
+
+0493 measured eight candidate signals over this corpus; exactly four discriminate. Derivation
+commands (per candidate feature `<id>`):
+
+| Signal | Derivation | Notes |
+| --- | --- | --- |
+| **AC coverage** (readiness proxy) | `spur feature show <id> --json` → count `Scenario:` in body; `spur feature check <id> --json` for validity findings | 0 scenarios ⇒ "specify next", not "work next" (routes toward B4/B5 territory; see handoff-routing.md) |
+| **Churn exposure** (urgency proxy — WSJF cost-of-delay, numerator only) | `git rev-list --count --since="<40 days ago>" HEAD -- <dirs the feature's scope touches>` | 40d window is 0493's measured default; tune on dogfood. Scope = the paths named in the feature's Goal/Scope |
+| **Dogfood proximity** (compound leverage) | `rg -c 'plugins/sp | apps/cli | task-pipeline | sp:' docs/features/<id>_*.md` + child task bodies | Degenerate-high in this harness (everything touches itself); discriminates mainly at **zero** — a 0-hit feature is "specify, don't ship" |
+| **Authority pull** (declared intent) | `rg -n '\b<id>\b' docs/02_ROADMAP.md docs/00_ADR.md` | Presence is positive evidence; absence is not negative |
+
+**Degenerate-spread rule.** After deriving a signal across the candidate set, check its spread. One
+dominant value (as `priority` was at 76% P2) ⇒ the signal does not discriminate on this frontier:
+report it as **rejected with its measured spread** for this run, and proceed without it. A rejected
+signal with its spread is a result, not an omission — it stops the next run re-testing it.
+
+**Rejected signals (0493, do not revive without new corpus evidence):** unblocking fan-out (1 genuine
+cross-root dependency edge in 495 tasks — graph too sparse), sunk-work decay / WIP pressure /
+staleness as standalone urgency (all artifacts of status drift; post-sync texture only).
+
+## §3 — What each signal reads (for the defect pass)
+
+The proposal contract keys defects to the tree property a signal reads: AC coverage → feature body;
+churn → git scope; dogfood → body text; authority → roadmap/ADR mentions; the gate → child-task set.
+A malformation of one of those properties that moves a rank is a candidate defect (D1–D4,
+proposal-contract.md). A malformation with no corrupting path to a surviving signal is noise — do
+not emit it.