@gobing-ai/spur 0.3.41 → 0.3.43

package/plugins/sp/skills/spur-dev/references/glossary.md

@@ -0,0 +1,95 @@
+---
+name: glossary
+description: "Extracted section: sp's own vocabulary — canonical terms with Avoid lists. Owns TERM DEFINITIONS only; process rules stay in cross-cutting.md (see the split note below)."
+see_also:
+  - spur-dev
+---
+
+# sp Glossary
+
+This is the single physical copy of sp's plugin-internal vocabulary — one canonical term per
+concept, each with an **Avoid:** list of near-synonyms that must not be used interchangeably.
+Every other skill body collapses its own re-explanation of these terms to the bare word and
+links here instead of repeating the definition.
+
+**Split from `cross-cutting.md`:** this file owns **term definitions** (what a word means).
+`cross-cutting.md` owns **process rules** (how writes happen, what the Iron Laws are, what
+`--auto` does). A term used inside a process rule is defined here once; the rule itself stays
+in `cross-cutting.md`. Neither file restates the other's content.
+
+## Terms
+
+**spine** — the thin orchestration skill (`sp:spur-dev`) that drives the planning→execution
+lifecycle by running gates and dispatching competency skills; it contains no domain logic of
+its own.
+Avoid: *orchestrator* (ambiguous with `sp:super-planner`, the batch orchestrator agent),
+*controller*, *coordinator*.
+
+**competency** — a deep, functionally-scoped skill (`sp:sys-architecture`,
+`sp:spec-decomposition`, `sp:code-implementation`, `sp:code-testing`, `sp:code-verification`)
+that owns one unit of work end-to-end. The spine dispatches to a competency; a competency never
+dispatches back to the spine.
+Avoid: *module* (reserved for the deep-module design vocabulary, see `sys-architecture`),
+*plugin*, *sub-skill*.
+
+**facade** — a skill that exposes CLI-verb usage for a `spur` noun (`sp:spur-cli`) without
+owning any lifecycle logic. One reference file per noun; the facade is a lookup surface, not a
+workflow driver.
+Avoid: *wrapper* (reserved for thin command docs — see **command wrapper** below), *adapter*
+(reserved for the deep-module design vocabulary).
+
+**corpus** — the validated set of task and feature files under `docs/tasks2/` and
+`docs/features/`, mutated only through `spur task` / `spur feature` CLI verbs.
+Avoid: *database*, *store*, *repo` (ambiguous with the git repository).
+
+**gate** — a deterministic CLI check that must exit clean before a lifecycle transition
+proceeds (`spur feature check`, `task-batch.schema.json` validation, `spur task check`,
+`spur rule run`). A gate either passes or blocks; there is no partial pass.
+Avoid: *checkpoint* (reserved for the Session Checkpoint Convention — a resumability artifact,
+not a pass/fail gate), *validation* (the generic verb; *gate* is the noun for the specific
+enforcement point), *step* (a gate is a property of a step, not a step itself).
+
+**verdict** — the structured PASS/PARTIAL/FAIL outcome of a verify step, recorded as an
+artifact (`.spur/run/<wbs>-verdict.json`) and consumed by `spur task record`.
+Avoid: *result* (too generic — a verdict has a fixed three-value contract), *report` (reserved
+for narrative output like the dogfood report or batch report).
+
+**noun/verb** — the two-part CLI grammar: a noun names the domain object (`task`, `feature`,
+`rule`, `workflow`, `agent`, `message`, `team`), a verb names the operation on it (`create`,
+`update`, `check`, `run`, `list`). The `sp:spur-cli` facade organizes its references one file
+per noun.
+Avoid: *command* alone (ambiguous with a `/sp:dev-*` slash command, which is a different
+grammar layer).
+
+**half** (planning / execution) — the two lifecycle phases `sp:spur-dev` drives: **planning**
+(vague description → validated, decomposed feature) and **execution** (one task → done through
+the pipeline). The two halves share this skill today but are designed to split cleanly; new
+logic belongs in exactly one half.
+Avoid: *phase* alone (the pipeline-phase table in `cross-cutting.md` uses *phase* for a
+different, finer-grained partition — ideation/design/execution/wrap-up — so *half* stays
+reserved for this specific planning/execution split).
+
+**HITL** (human-in-the-loop) — a workflow state that pauses for explicit operator approval
+before continuing (`hitl.confirm`). A HITL gate is never auto-dismissed by the engine; `--auto`
+can only route *around* one whose objective precondition is already met (see the `--auto`
+routing contract in `cross-cutting.md`).
+Avoid: *prompt* (reserved for LLM input text), *interrupt* (implies an exception, not a planned
+pause point).
+
+**WBS** (work-breakdown-structure ID) — the four-digit task identifier (e.g. `0187`) that
+names a task file and its position in the corpus. WBS IDs are assigned once and never reused.
+Avoid: *task ID* alone (acceptable in prose, but *WBS* is the canonical term when precision
+matters — e.g. distinguishing a task WBS from a feature ID).
+
+**section-write contract** — the rule that every corpus write goes through
+`spur task update <wbs> --section <name> --from-file <path>` with body-only content (no
+duplicate heading, no same-level sub-headings), gated by the section-status matrix for the
+task's current status. Fully specified in `cross-cutting.md`; this glossary only names the term.
+Avoid: *section edit* alone (too generic — *contract* signals the CLI-gated, matrix-checked
+nature of the write).
+
+## See also
+
+- [cross-cutting.md](cross-cutting.md) — the process rules that use these terms (Iron Laws,
+  Auto-Decision Principles, the section-editing workflow, pipeline phase table).
+- [spur-dev/SKILL.md](../SKILL.md) — the spine that dispatches by these terms.

package/plugins/sp/skills/spur-dev/references/idea-evaluation.md

@@ -0,0 +1,80 @@
+---
+name: idea-evaluation
+description: >-
+  Template SSOT for the post-discovery idea-evaluation report used by idea-pipeline's
+  idea-eval taste gate. Brainstorm fills an instance at .spur/run/idea-eval-report.md.
+see_also:
+  - spur-dev
+  - brainstorm
+  - decision-brief
+---
+
+# Idea Evaluation Report Template
+
+The idea-evaluation report is the operator-facing artifact between **discovery** and
+**feature-create** on `/sp:dev-idea`. It follows [decision-brief](decision-brief.md) norms:
+recommendation is mandatory, stakes in plain English, and approve/reject is the terminal choice.
+
+**Authorship:** `sp:brainstorm` (discovery) fills a concrete instance to
+`.spur/run/idea-eval-report.md`. The pipeline `idea-eval` state is HITL-only — it does not
+re-author the report.
+
+**Sidecar rule:** The enhanced idea does **not** overwrite `vars.idea`. Feature-create reads both
+the original idea and this report.
+
+## Template
+
+```markdown
+# Idea Evaluation Report
+
+## Enhanced Idea
+<one-paragraph refined statement of what the idea actually requires — the "real requirement" after discovery sharpens the vague input>
+
+## Scores
+
+| Dimension | Score (0–5) | Rationale |
+|-----------|-------------|-----------|
+| **Urgency** — how soon must this ship? | <0–5> | <one sentence: what breaks or degrades without it; 0 = no time pressure, 5 = blocking users/pipeline now> |
+| **Necessity** — does the product need this at all? | <0–5> | <one sentence: what gap this fills vs workaround quality; 0 = nice-to-have with easy workaround, 5 = core functionality missing> |
+
+Score guide:
+- 0 = no signal / not applicable
+- 1 = minimal — workaround is fine for the foreseeable future
+- 2 = low — improves quality of life, not blocking
+- 3 = moderate — noticeable gap; workaround exists but costs effort
+- 4 = high — significant pain point; workaround is fragile or expensive
+- 5 = critical — blocking users, pipeline, or a committed deliverable
+
+## Premises
+<bulleted list of assumptions the idea rests on — things that must be true for the idea to deliver value; if any premise is false, the idea collapses or must be reshaped>
+
+## Pros
+<bulleted list of concrete benefits — what ships, what improves, what risk is reduced>
+
+## Cons
+<bulleted list of costs — complexity added, maintenance burden, scope risk, opportunity cost>
+
+## Better Alternatives
+<bulleted list of alternative approaches (if any) that could achieve a similar outcome with lower cost or risk; "None identified" if the idea is the best known approach>
+
+## Recommendation
+<proceed | reshape | drop> — <one-line rationale linking scores, premises, and pros/cons>
+
+Stakes: <plain-English cost of proceeding vs not; reversibility; blast radius>
+
+---
+
+**Approve** this evaluation to continue to feature-create.
+**Reject** to cancel the run (no feature created).
+```
+
+## Pipeline contract
+
+| Item | Value |
+|------|--------|
+| Filled instance path | `.spur/run/idea-eval-report.md` |
+| Template home | this file |
+| HITL state | `idea-eval` in `idea-pipeline.yaml` |
+| Approve | continue → `feature-create` |
+| Reject / cancel | → `cancelled` (no feature) |
+| `--auto` | still pauses unless taste pre-cleared (`--approve-taste` → `idea_approved=true`) |

package/plugins/sp/skills/spur-dev/references/inline-pipeline-driver.md

@@ -0,0 +1,120 @@
+---
+name: inline-pipeline-driver
+description: "Interactive host-session interpreter for task-pipeline.yaml: execute the existing FSM without a workflow agent subprocess while preserving actions, guards, artifacts, and provenance."
+see_also:
+  - spur-dev
+  - execution-workflow
+  - execution-batch
+---
+
+# Inline Pipeline Driver
+
+This driver is the interactive control-inversion path granted by ADR-047. It applies only when an
+interactive `/sp:dev-run --mode full` or sequential `/sp:dev-runall` invocation omits `--agent` or
+passes `--agent inline`. A named executor, `--agent auto`, parallel batch mode, `spur workflow run`,
+and `spur agent run` keep the existing subprocess path.
+
+The project runtime definition at `.spur/workflows/task-pipeline.yaml` remains the sole FSM definition.
+The driver MUST read that file
+at invocation time. It must not copy the state list, actions, guards, or transition order into a
+command, skill, script, or second workflow.
+
+## Run setup
+
+1. Resolve `<wbs>`, `--auto`, and any explicit `--vars`; read the YAML and overlay its `vars` defaults
+   with those invocation values. An explicit `vars.agent` / `vars.implementAgent` is an executor
+   selection and therefore chooses the subprocess workflow path.
+2. Allocate a collision-resistant inline run id (`uuidgen`, with a timestamp/pid fallback), create
+   `.spur/run/`, and use `.spur/run/<run-id>.log` as the run log.
+3. Resolve the host session id from `.spur/context/.session.json`, accepting the normalized hook key
+   `session` and the Codex key `session_id` (in that order). If neither is available, allocate
+   `host-session-<run-id>` and record that fallback in the log; provenance must never be blank or
+   guessed from an executor subprocess.
+4. Record lifecycle provenance before entering the FSM:
+
+   ```bash
+   spur task run-link <wbs> --source inline-full --run-id <run-id> --json
+   ```
+
+   This is required for the normal `testing → done` provenance guard. It is not a guard bypass.
+
+## YAML interpreter
+
+Start at `initialState`. For each current state, execute its `onEnter` actions in declaration order,
+then evaluate outgoing transitions in declaration order and take the first passing guard. Stop only
+at a declared terminal state or a surfaced HITL pause. The `iterationBound` remains mandatory.
+
+Action semantics come from the YAML and the workflow action contract:
+
+- `shell` — run the expanded command in the project working tree with resolved vars exported as
+  environment variables. A non-zero result follows the action's existing failure policy.
+- `note` — append the expanded message to the inline run log.
+- `file.read.into-var` — read the declared file into the declared run variable before subsequent
+  actions/guards.
+- `hitl.confirm` — under `profile=auto`, follow the YAML's auto-skip transition. Otherwise pause,
+  surface the prompt, and resume from the same state with the operator's answer.
+- `agent.run` — execute the action's slash command, native-subagent-first (task 0508). Do not call
+  `spur agent run` and do not re-enter `/sp:dev-run --mode full`. Preserve the YAML options: capture
+  `answerFile`; assert `expectFile`; enforce `requireDiff` against a pre-action git snapshot,
+  including the task-scope guard; honor declared error policy. `timeoutMs` is recorded as not
+  applicable because the host session has no independent kill boundary.
+
+**Native-subagent dispatch (R2 eligibility, evaluated before each action):**
+
+1. The invocation is one of the two interactive inline full-pipeline surfaces (`dev-run --mode full`
+   or sequential `dev-runall`, omit/`inline`).
+2. The YAML action kind is `agent.run` and its input is a pure slash command. Shell, note, file,
+   guard, and operator-interaction actions remain host-executed.
+3. The current state/action has no operator-confirmation action, `pause: true`, approve/taste/ask
+   decision, or other operator prompt.
+4. The platform exposes a native subagent that shares the working tree and has read, write, shell,
+   and Spur task/run-artifact access.
+
+All four pass → dispatch. Any pre-dispatch failure → execute the stage **once** in the host session.
+No token estimate, stage-size threshold, model heuristic, or configuration switch is added.
+
+**Dispatch and join:** before dispatch, capture the same pre-action git snapshot used by
+`requireDiff` enforcement. Send only: the stage id, the YAML's exact pure slash command, and
+`execution surface already resolved: native subagent; do not dispatch this stage again`. The WBS/path
+already carried by the slash command is the handoff — do not paste task/session transcripts or embed
+machine-specific session paths. Dispatch exactly one native subagent and wait for it; the inline FSM
+must not advance actions or guards concurrently (one writer at a time). After join, validate
+`answerFile`, `expectFile`, `requireDiff`, task scope, and the action's error policy from the shared
+filesystem — a subagent success message is not evidence. On success append exactly:
+
+```text
+stage <id> executed via subagent <agent-id> (host session <session-id>)
+```
+
+Host fallback retains exactly `stage <id> executed inline in session <session-id>`. If launch fails
+before the subagent starts, log the reason and use host fallback. If a started subagent fails or
+leaves invalid artifacts, do **not** replay the stage in the host — follow the YAML error policy so
+partial mutations are not duplicated.
+
+**Host-owned interaction:** the host alone executes operator-confirmation actions, owns
+`pause: true`, and surfaces approve/taste/ask decisions. A subagent that discovers missing authority
+or an operator decision returns a blocker; the host pauses at the current state and presents it. The
+subagent cannot approve, infer consent, or recursively invoke the full pipeline.
+
+After every successful inline `agent.run` action append exactly one provenance line (inline or
+subagent form above) to `.spur/run/<run-id>.log`, where `<id>` is the current YAML state id. Also
+log start/failure and the ignored timeout value so an inline run remains auditable without
+fabricating an `AgentRunTracedResult`.
+
+Transition guards are not advisory. Execute the declared guard exactly, in order, with the same
+resolved variables and artifacts. `--no-lifecycle` remains bookkeeping only; the YAML's task checks,
+verdict gate, record step, and done guard all remain authoritative.
+
+## Batch use
+
+Sequential `/sp:dev-runall` with omit/`inline` runs this driver once per ready WBS, with a fresh run
+id and the same frozen/topologically ordered batch plan. Batch inspection, halt/keep-going policy,
+and reporting remain in `execution-batch.md`. Parallel mode cannot share one host session safely and
+therefore keeps the existing isolated subprocess/worktree path (trigger 4).
+
+## Failure contract
+
+Never silently fall back from this interactive inline path to `agent.default`. If the driver cannot
+read the YAML, allocate provenance, execute an action, or evaluate a guard, stop at that state and
+report the run id, state id, original error, and the concrete resume/retry command. The working tree
+and run artifacts are the recovery input.

package/plugins/sp/skills/spur-dev/references/planning-workflow.md

@@ -0,0 +1,302 @@
+---
+name: planning-workflow
+description: "Extracted section: the planning half — intake → feature create → AC generation → feature check gate → decomposition → batch-create gate → refine. The full step-by-step procedure for turning a vague description into a validated, decomposed feature."
+see_also:
+  - spur-dev
+  - decomposition
+  - ac-style-guide
+---
+
+# Planning Workflow
+
+```
+vague description
+  → intake (clarify scope, constraints — prompt work)
+  → spur feature create … ; AC authored/generated (spur agent run, bdd templates)
+  → GATE: spur feature check   (BDD validator; loop until clean)
+  → decomposition (prompt work) → task-batch JSON
+  → GATE: task-batch.schema.json + spur task batch-create (atomic: all-or-nothing)
+  → design doc (conditional: seam heuristic under default; skip with --skip-design) → docs/design/<slug>.md + 04 index
+```
+
+
+The planning half transforms a description into a validated feature file with acceptance
+criteria, then decomposes it into a batch of tasks. Two CLI gates make LLM regressions
+unable to corrupt the corpus: `spur feature check` validates the AC, and
+`task-batch.schema.json` validates the decomposition shape before `spur task batch-create`
+writes anything.
+
+## Step 1: Intake
+
+When given a feature description, clarify before creating:
+
+1. **Scope** — what is in, what is explicitly out. Record both.
+2. **Constraints** — existing systems it must work with, performance/security boundaries.
+3. **Success criteria** — how will we know it's done? (Feeds AC generation.)
+
+Ask only what is ambiguous. A crisp description needs no Q&A loop — proceed directly to feature
+creation.
+
+## Step 2: Feature creation + AC generation
+
+```bash
+spur feature create "<name>" [--parent <id>]
+```
+
+The feature file lands in `docs/features/<ID>_<slug>.md`. Immediately author the `## Goal`
+(single sentence) and `## Scope` (in/out bullets).
+
+Then generate **BDD acceptance criteria** in the `## Acceptance Criteria` section using the
+Gherkin template. Conventions:
+
+- **R-numbered scenarios:** each scenario carries an `R1, R2, …` prefix in its title for
+  cheap, human-readable traceability. (Coverage matching is by **normalized scenario title** —
+  the R-prefix is stripped before matching — so keep the title text stable, not just the number.)
+- **Two AC tiers:** core scenarios (the must-pass gate) and edge-case scenarios (advisory
+  warnings — the permissive start, per DD-06). Mark edge-case scenarios explicitly.
+- **Scenario-title mapping:** the scenario title is the identity key for traceability edges
+  to task files — keep them stable and unique.
+- Generate AC inline (current session) with the BDD template
+  (`.spur/templates/bdd/gherkin.md`), or escalate to `spur agent run` only when a
+  [subprocess trigger](cross-cutting.md#inline-default-execution-surface) applies. **Thread
+  `--agent` through** when the command forwarded one. See the
+  [inline-default execution-surface contract](cross-cutting.md#inline-default-execution-surface).
+
+Full authoring conventions: see [ac-style-guide.md](ac-style-guide.md).
+
+## Step 3: Feature check gate (loop)
+
+```bash
+spur feature check <id> --json
+```
+
+The BDD validator gate. A non-zero exit means findings:
+
+1. Read each finding from the JSON output.
+2. Fix the **specific** AC issue — never restructure unrelated scenarios.
+3. Re-run. Loop until exit 0.
+
+This gate catches: malformed Gherkin, missing required scenario elements, traceability gaps.
+A skill regression can never corrupt the corpus — worst case is a rejected write with findings
+the skill can react to.
+
+## Step 4: Decomposition
+
+**Default: do not decompose.** A clean feature does not automatically become many tasks. The
+default outcome is one task whose `## Plan` carries the implementation steps; splitting is the
+exception you justify with the rubric. See the `sp:spec-decomposition` skill ("Default to NOT
+decomposing") — read it before this step.
+
+1. **Score the feature with the rubric first.** Compute E/D/L/C/R for the *whole* feature. Record
+   the assessment (this is a required artifact, not optional):
+   - **Score 0–2 → keep as one task.** Stop. Author one task (Background + Requirements from the
+     feature, the implementation steps as its `## Plan`). Do NOT call `batch-create`. You're done
+     with decomposition.
+   - **Score 3–4 → decomposition optional.** Prefer one task with a rationale unless a clear
+     deliverable boundary justifies a split.
+   - **Score 5+, or a force-decompose override fires → decompose.** Continue to step 2.
+2. **Only now design the split** — by deliverable boundary, never by phase or by list-item. Read
+   the feature's scenarios (the AC); each resulting task maps to ≥1 scenario by title.
+3. **Score each candidate child.** Any candidate that scores 0–2 on its own is a `## Plan` step of
+   a sibling, not a task — merge it. This is the check that stops a 6-item finding list becoming 6
+   tiny tasks.
+4. Produce a **task-batch JSON** document conforming to `task-batch.schema.json` — a top-level
+   JSON **array** of strict task items (no `tasks` wrapper, only documented fields).
+
+Decomposition heuristics (apply only after deciding to decompose):
+- **One task = one atomic unit of work** a single agent can complete (target 2–8h; never <2h).
+- **Scenario coverage:** every core scenario maps to ≥1 task; edge-case scenarios may map
+  or be deferred.
+- **Sub-tasks:** record `parent_wbs` (quoted, e.g. `"0042"`) for sub-tasks; note ordering in
+  `background` prose (the item schema has no `dependencies` field).
+- **Template variants:** choose `feature-impl` for implementation tasks (pulls Goal →
+  Background from the linked feature, per B09).
+- **Record the rubric score** in each child's `background` (a trailing line, e.g.
+  *"Rubric: E2 D1 L1 C1 R2 = 7 → decompose (force: R=high)."*) — the assessment artifact the
+  gate below checks for.
+
+The batch JSON is the LLM→CLI contract — see the `sp:spec-decomposition` skill for the
+full schema and conventions.
+
+## Step 5: Batch-create gate
+
+**Pre-check (soundness, before the CLI gate).** Re-read each item in the batch JSON against the
+rubric before submitting. Specifically:
+
+- Would this item score 0–2 on its own? → it is a Plan step; merge it into a sibling or back into
+  the parent. Do not submit it as a task.
+- Is the batch one-item-per-list-entry (one finding → one task, one scenario → one task)? → you
+  are reflex-decomposing. Re-score and merge.
+- Does each item carry its rubric-score line in `background`? → if not, the assessment is missing;
+  score it before submitting.
+
+Only then run the CLI gate:
+
+```bash
+spur task batch-create --file <batch.json>
+```
+
+Atomic: all-or-nothing. If `task-batch.schema.json` validation fails, **nothing is written**
+and findings are returned. The schema validates shape only (it cannot reject over-decomposition —
+that is the pre-check's job above). Common shape failures:
+
+- Missing required fields per the template variant's section matrix.
+- Invalid status values (must be lowercase canonical).
+- `feature_id` referencing a non-existent feature.
+- WBS collisions (already-allocated range).
+
+Loop until the command exits 0 — then the batch is created and each task appears in the
+feature's `## Tasks` block on next `spur feature refresh`.
+
+**If you decomposed a parent task into sub-task files** (the children carry `parent_wbs`), the
+sub-task roster is **auto-generated** — `spur task batch-create` invokes `spur task refresh-roster`
+for each distinct `parent_wbs` after the atomic create lands (task 0178 F1), and transitions
+decomposed parents from `todo` to `wip` (task 0178 F2). You do **not** hand-write the roster;
+re-run `spur task refresh-roster <parent-wbs>` to re-emit it after a child status change outside
+`batch-create`. See `sp:spec-decomposition` ("Parent (umbrella) tasks") for the roster format and
+the parent-completion rule.
+
+## Step 5.5: Design package (unified `--skip-design` only)
+
+Two design surfaces, **one operator opt-out** (aligned with `/sp:dev-idea`):
+
+| Surface | What | Default |
+|---------|------|---------|
+| **Feature satellite** | `docs/design/<slug>.md` + `04_DESIGN.md` index | On when seam heuristic fires; **ties lean design**; off only with `--skip-design` |
+| **Task `### Design`** | Per-task WHAT/WHY in each batch item's `design` field | **On by default** at decompose/batch-create; off with `--skip-design` |
+
+There is **no** `--design` force flag. Design is **on by default**; **`--skip-design`** is the only
+opt-out.
+
+**`--skip-design` (unified):** skip the feature satellite **and** leave task `design` empty (scaffold
+only). Refine is the **fallback** that fills blank Design before implement.
+
+| Flags | Feature satellite | Task `### Design` in batch |
+|-------|-------------------|----------------------------|
+| (default / `--auto`) | seam heuristic (ties lean **design**) | **author `design` on each item** |
+| `--skip-design` | skip | **omit `design`** (refine later) |
+
+A task's in-file `### Design` is code-level and narrow. The feature satellite is cross-cutting. Both
+are part of the same planning "design package" controlled by `--skip-design`.
+
+**The seam heuristic (default / `--auto` decision).** A design doc is warranted when the feature
+introduces an **ADR-worthy** change — anything that shifts a boundary another engineer must reason
+about:
+
+- a **new command** or a new flag that changes a command's contract,
+- a **new module / package / service** (a new `apps/*` or `packages/*`, a new app-layer service),
+- a **new schema** — a DB table/migration, a Zod config key, a DTO/contract shape,
+- a **new transport / boundary** — an oRPC seam, an auth boundary, a job-queue or EventBus topic.
+
+If the work is clearly internal to one module, a bug fix, a doc/chore, or a refactor with no boundary
+change, **skip** — note the skip in the report. **When in doubt, lean design** (same ties rule as
+idea-path `needs_design`). Use `--skip-design` only when the operator wants no satellite and blank
+task Design.
+
+**Authoring (skill-prose — no CLI verb).** The `04` index is a hand-curated derived doc
+(constitution §4.5 rule 4 / §6.5), so write it directly, in the fixed **detail-first then index**
+order (§4.5 rule 5 / sync trigger **T9**):
+
+1. **Satellite first.** Write/update `docs/design/<slug>.md`. `<slug>` is the stable grep anchor —
+   derive it from the feature name (kebab-case), and **reuse the existing slug** on re-runs. Capture
+   the chosen approach + one-line reason, rejected alternatives, key interface/type **signatures**
+   (not bodies), invariants, and the surface it touches. Do **not** restate the satellite file format
+   here — follow the shape of existing satellites (`docs/design/server-side-adjustment-design.md`,
+   `workflow-observability.md`).
+2. **Index second.** Add or update the satellite's row in `docs/04_DESIGN.md §0` (the `| Satellite |
+   Area | Status |` table) — pointer + one-line area + status only, never a restatement of the body.
+
+**Idempotency (re-runnable).** `/sp:dev-plan` may run many times for one feature. If the
+satellite already exists: **update in place** — merge new design content into its sections, refresh
+its `updated_at`, and leave its existing `04` index row alone (or adjust only its status). **Never**
+overwrite the whole file, create a second satellite, or add a duplicate index row. The invariant
+(§4.5 rule 1): exactly one `04 §0` row per satellite, every satellite reachable from exactly one row.
+
+**Report (no confirmation pause).** Under `--auto`, generation is autonomous — when the heuristic
+fires, author the doc and **report** the chosen slug and a one-line rationale ("authored
+`docs/design/<slug>.md` — new `spur <noun>` command + config key"); when it does not fire, report the
+skip and why. Do not pause to ask; the operator reviews the satellite afterward.
+
+## Step 6: Refine before execute (the spec-completion gate)
+
+`batch-create` accepts optional `design` / `plan` / `acceptance_criteria` fields (plus
+`background` / `requirements`). **Default planning path:** the decomposition agent fills `design`
+(and preferably Plan/AC) so tasks land **content-ready**. **`--skip-design`:** leave `design`
+empty — headings only.
+
+**Refine is the fallback**, not the primary Design author:
+
+```text
+/sp:dev-refine <wbs>          # single task — fills blank Design/AC/Plan if L3 gaps
+/sp:dev-refineall --feature X --auto
+/sp:dev-refineall --feature X --auto --depth ready   # implement-ready freeze (no L3-only SKIP)
+```
+
+Under `--auto` + **`--depth standard`** (default), refine **SKIP**s when target sections
+(Background, Requirements, AC, Design, Plan) already have no L3 findings. If Design is still
+placeholder, synthesis runs (standard tier by default; escalates only on gate-fail). Under
+**`--depth ready`**, do not SKIP on L3-clean alone — run the implement-ready checklist in
+[dev-operations.md](dev-operations.md) § refine (frozen APIs, anti-patterns, file targets, handoffs)
+so another agent can implement without inventing design.
+
+**Check the variant before you write.** Which sections a task carries is decided by its `template:`
+frontmatter against `.spur/tasks/section-matrix.yaml` — NOT a fixed list. Before authoring any
+section, run `spur task check <wbs> --json` and read `requiredSections` / the L2 findings: they tell
+you exactly what this variant allows at the current status. The default `standard` variant wants
+`Acceptance Criteria` + `Design` + `Plan` at `todo`, but other variants differ — e.g. the `review`
+variant puts findings under `### Background` (`#### Review Findings`) and the fix checklist in
+`### Plan`, and does **not** use `### Requirements`/`### Acceptance Criteria`. Authoring a section
+that isn't in the variant's allowed list produces an L2 "not allowed in this variant/status" warning
+and an off-variant task. Write only what the matrix permits; route findings/checklists into the
+sections the variant actually defines.
+
+**Avoid creating off-variant sections in the first place.** There is no section-delete verb —
+intentionally none (the CLI surface stays minimal). Writing an empty body via
+`spur task update <wbs> --section <name> --from-file <empty-file>` currently leaves a **bare
+heading**, not a removal. So once an off-variant section exists, it cannot be cleanly dropped from
+the skill — the prevention (check the variant before writing, above) is the only reliable path. If
+you must correct an off-variant section, overwrite its body with a single line pointing at the
+correct section (e.g. *"See `### Plan` for the fix checklist."*) rather than leaving it empty.
+
+**Do this just-in-time, per task, immediately before execution** — not in bulk at decomposition
+time. Design written against a stale snapshot of the codebase rots; design written right before
+`implement` reflects current reality. Refine `0042`, run `0042`; refine `0043`, run `0043`.
+
+**Batch refine (optional pre-pass).** When an operator wants every planning-side task under a
+feature filled before a runall, use `/sp:dev-refineall --feature <id> --auto` (batch counterpart
+of `/sp:dev-refine`). It reuses the same per-task refine operation, freezes the set, topo-sorts by
+`dependencies[]`, and emits a batch report — see [dev-operations.md](dev-operations.md) § refineall.
+This does **not** replace just-in-time refine before each implement; it is a bulk pre-pass when the
+feature's tasks are still `backlog`/`todo` placeholders. Prefer `--auto` for batch scale; avoid
+`--next` on large features (that chains each task into run).
+
+**Refine arguments** (defined on the `/sp:dev-refine` entry point, passed through verbatim; also
+shared flags on `/sp:dev-refineall`):
+
+| Argument | Effect |
+|----------|--------|
+| `--focus <mode>` | Narrows the gap analysis to a subset of domain hints. See the `sp:dev-refine` skill for the full value table (`all`, `requirements`, `background`, `constraints`, `acceptance`, `quick`). Default `all`. |
+| `--depth <standard\|ready>` | Spec depth bar. `standard` (default) = L3 structural completeness + L3 SKIP under `--auto`. `ready` = implement-ready freeze (never L3-only SKIP). See [flag-glossary.md](flag-glossary.md#flag-depth). |
+| `--auto` | Skip interactive Q&A — synthesize improvements from the task content alone. Use for well-scoped tasks where the agent can fill gaps without operator input. **Required for practical batch use** via `dev-refineall`. |
+
+**Pre-synthesis skip gate (under `--auto` + `--depth standard`).** Before synthesizing, run `spur task check <wbs> --json`. When the **refine target sections** show no L3 findings, emit a structured SKIP instead of calling the synthesis agent. **Not applied when `--depth ready`.**
+
+**Refine target sections (anti-drift lock):** `{Background, Requirements, Acceptance Criteria, Design, Plan}`.  
+These must be solid enough that a cheaper implementer cannot invent another path. **Solution is not a refine target** — it is written by implement as the as-built change-map.
+
+```
+SKIP — sections already meet L3: sections-considered=[Background, Requirements, Acceptance Criteria, Design, Plan], reason="no L3 findings for target sections"
+```
+
+This is the expected outcome for a task that is already well-specified. Under `--auto`, a SKIP is not an error — it means no gap was found. The operator can verify by reading the check output or the task file directly. Synthesis is only invoked when a real gap exists in a target section (including empty/placeholder Design or AC).
+
+> **Requirements formatting:** author R-items as a GitHub task-list checkbox — `- [ ] R1. <text>`
+> — one per line, so progress is trackable in the file. Keep the `Rn.` (period) token inside the
+> marker so the R-numbering rule recognizes it.
+>
+> The L3 check *tolerates* `- Rn.` and bare `Rn.` for backward compatibility with the existing
+> corpus — that tolerance is **not** permission to emit them. A bare `Rn.` line carries no markdown
+> list marker, so consecutive items collapse into one run-on paragraph in the Board's markdown
+> preview while `spur task check` still passes. Emit the checkbox form on every write path
+> (refine synthesis, `spur task update --section`, and `batch-create` bodies — see
+> `sp:spec-decomposition` → `references/decomposition.md`, "Section bodies are markdown").