@gobing-ai/spur 0.3.78 → 0.3.81

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

@@ -130,24 +130,63 @@ The flags (`--detail`, `--verbose`, `--trace-file`, `--follow`, `--output`) are
 ## 3. Node simplicity budget
 
 Simplicity is the operating constraint, and it is already measurable — `spur workflow validate`
-reports it. Do not invent a second threshold; author to the one that is frozen (ADR-069, task 0614).
-
-| Element | Budget | What breaching it means |
-| --- | --- | --- |
-| `shell` action `command` | **<= 5** non-comment units (split on newline and `;`) | >= 6 flags the composition advisory: the program holds reusable behavior that wants an owner |
-| `agent.run` action `input` | A **slash command or skill invocation** | A raw prose prompt flags: the operation belongs behind a centralized command (ADR-043). Prompt length sets severity only |
-| Transition guard | **One** boolean predicate | Guards are exempt from the shell measure by design. A guard needing five lines is a probe node in disguise — make it one |
-| 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 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, 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
-acceptance.
+reports it with a `warn`/`error` level. Do not invent a second threshold; author to the ADR-115
+tiers frozen in [surface governance §1.2](../../../../../../docs/design/harness-surface-governance.md).
+
+| Element | Clean | Warn (advisory) | Error |
+| --- | --- | --- | --- |
+| `shell` action `command` | ≤5 logical commands (split on newline, `;`, `&&`, `||`; blank/`#`/structure tokens skipped) | **6–10** | **>10** commands or **>800** characters |
+| Shell transition guard | ≤3 logical commands — one predicate over a result file | **4–5** | **>5** |
+| `agent.run` `input` | A slash command or skill invocation (ADR-043), ≤1000 chars | non-slash prompt (severity by raw length: <200 low, ≤1000 medium) | **>1000** chars, slash-led or not |
+| `agent.run` output check | `expectFile` or `requireDiff` declared | neither declared | — |
+| 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 program breaches a cap, do not reformat to dodge the measure.** Joining lines with `&&`
+moves the complexity, not the ownership. Move the program to one of the five recorded owners from
+`docs/design/workflow-shell-ownership.md`: (a) public `spur` verb (consent-gated), (b) application
+service, (c) least-privilege built-in action kind, (d) workflow-relative external extension, or
+(e) a deliberately-stays-shell exception. (e) is valid only inside the warn band — above an error
+cap the program moves to (a)–(d).
+
+**Every remaining warn-band shell program carries a one-line `#` reason**: a YAML comment directly
+above the action or guard, e.g. `# (e) <why it stays shell>` or `# (d) <script> owns <what>`. Never
+write it as a shell `#` line inside a folded `>-` scalar — folding joins the lines, so the `#`
+comments out the rest of the program. YAML comments do not count toward the measure.
+
+**Posture is binding (ADR-115).** Warn-level findings never change a `validate` exit status and
+never block a run. An error-level finding makes `validate` exit 1 and gates the spur repository's
+shipped shared workflow layer (layer id `shared` in `spur workflow list --json`) in `spur-check`
+(task 0826). No composition finding ever blocks `run`, `run --dry-run` or `continue`, and a finding
+is never a reason to hot-edit an executing pipeline.
+
+### Consolidation and cache windows (ADR-115)
+
+Two composition rules sit next to this budget: the table above stays the measure surface, these
+decide where steps are cut. The rules are owned by the
+[workflow composition contract](../../../../../../docs/design/workflow-composition-contract.md#composition-budgets-adr-115);
+the text below is the operating summary, not a second owner.
+
+**Consolidation — one model step per judgment.** Merge adjacent `agent.run` steps only when they
+share a role and an executor **and** nothing between them must stay separate: a deterministic gate,
+a HITL state, or an independence boundary. Never merge an author step with the review or verify
+step that certifies it — those keep `freshSession: true`. A new model step in a shared workflow
+raises its `pipeline-budgets` `modelQueries`, which needs a recorded decision, and every shared
+workflow with a model query carries a budget entry.
+
+**Cache windows — step boundaries follow the cache window, not the clock.** Provider prompt caches
+expire after an idle window and refresh on every hit (Anthropic: 5 minutes by default; OpenAI:
+5–10 minutes in memory). The window W defaults to 300 s, the shortest common default:
+
+- A tool call inside `agent.run` that runs longer than W idles the model — its next request
+  re-reads a cold prefix. Run that work in a deterministic step instead.
+- An `agent.run` that resumes the inherited session after a gap longer than W (a HITL wait, a slow
+  deterministic step) rewrites the whole session into the cache. When the prior step's artifact
+  carries what the step needs, prefer `freshSession: true` with that artifact as the handoff.
+- A deterministic step should finish within W at p50. An `agent.run` with p50 above 2W is a split
+  candidate only at a real artifact seam — each split adds a model query and a cold prefix, so it
+  must pay for itself in retry granularity or observability.
+
+These are runtime budgets, judged from run traces and step profiles — never `validate` findings.
 
 ---
 

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

@@ -0,0 +1,145 @@
+---
+name: spur-composer
+description: "Select, compose and tune spur artifacts — tasks, features, rules, workflows and agent specs. Owns workflow catalog selection, the ephemeral→project→shared ladder, the ADR-115 budgets, trace-driven rule tuning, and applying accepted sp:spur-doctor proposals. Triggers: compose a workflow, tune a rule, apply doctor proposals."
+license: Apache-2.0
+version: 1.0.0
+metadata:
+  author: spur
+  platforms: "claude-code,codex,openclaw,opencode,antigravity"
+  category: artifact-composition
+  interactions:
+    - inversion
+    - companion
+  operations:
+    - select
+    - compose
+    - tune
+    - apply
+  openclaw:
+    emoji: "🎼"
+see_also:
+  - sp:spur-cli
+  - sp:spur-doctor
+  - sp:super-planner
+---
+
+# sp:spur-composer — compose, select and tune spur artifacts
+
+One cross-noun method (ADR-114, [spur artifact evolution](../../../../docs/design/spur-artifact-evolution.md)
+§2): **select** an existing artifact, **compose** a new one up the ladder, **tune** it against
+evidence, and **apply** the proposals the operator accepts from `sp:spur-doctor`. It never judges
+its own output and never runs a recurring loop — evaluation is the doctor's job.
+
+## Boundary — read before composing
+
+- **Verbs and flags live in `sp:spur-cli`.** This skill links references; it never restates a verb
+  or flag catalog: [../spur-cli/SKILL.md](../spur-cli/SKILL.md).
+- **Recurring loops and coordination go to `sp:super-planner`** or a workflow — not here. This skill
+  runs one bounded composition or tuning pass per invocation.
+- **Forbidden surfaces: `spur team` and `spur agent loop`.** Agent specs are reached only through
+  `spur agent create|edit|delete|list --specs`.
+- **Writes land only through `spur` verbs** and the ladder's gated file steps (§ below). The shared
+  step additionally needs recorded operator consent plus `build:bundle` parity.
+
+## Covered nouns
+
+| Noun | Composition / tuning method | Verb reference |
+| --- | --- | --- |
+| task | Apply accepted doctor rows via the CLI-gated corpus surface; author variants through the task reference's conventions | [../spur-cli/references/tasks.md](../spur-cli/references/tasks.md) |
+| feature | Apply accepted rows through `spur feature update --section --from-file`; keep acceptance criteria in Gherkin | [../spur-cli/references/features.md](../spur-cli/references/features.md) |
+| rule | The trace-driven tuning loop (§ Rule tuning loop) | [../spur-cli/references/rules.md](../spur-cli/references/rules.md) · [fine-tuning](../spur-cli/references/rules/fine-tuning.md) |
+| workflow | Catalog selection, the composition ladder, and the ADR-115 budgets (§ below) | [../spur-cli/references/workflows.md](../spur-cli/references/workflows.md) · [operations](../spur-cli/references/workflows/operations.md) |
+| agent spec | Compose and edit `.spur/agents/<id>.yaml` only through `spur agent create|edit|delete|list --specs` | [../spur-cli/references/agent.md](../spur-cli/references/agent.md) |
+
+Do not drive the planning→execution lifecycle from here — that is `sp:spur-dev`.
+
+## Workflow catalog selection
+
+Run this **before composing anything new**, exactly as the
+[find-existing-workflow](../spur-cli/references/workflows/operations.md#sub-procedure-find-existing-workflow)
+procedure: the catalog is `spur workflow list --json` across all layers, and each entry's
+`description` is its intent.
+
+| Catalog match | Action |
+| --- | --- |
+| Matches the intent | **Run it as is.** No new artifact. |
+| Near match | **Same-name override in the project layer** (`.spur/workflows/<name>.yaml`) — the project layer wins name resolution — and tune from there. |
+| No match | **Compose** up the ladder (§ Composition ladder). |
+
+Never glob a folder to enumerate candidates: layers you skip that way are layers a bare name
+cannot resolve from.
+
+## Composition ladder
+
+| Step | Location | Gate before use |
+| --- | --- | --- |
+| ephemeral | A scratch file outside every layer (for example under `.spur/run/`), run by explicit path | `spur workflow validate`, `spur workflow run --dry-run`, a `spur workflow show` preview |
+| project | `.spur/workflows/<name>.yaml` | The same gates |
+| shared | the spur repository's shipped shared workflow layer (layer id `shared` in `spur workflow list --json`) as `<name>.yaml` | The same gates, **plus recorded operator consent and `build:bundle` parity** |
+
+- `spur workflow validate --json` exits 1 on an error-level composition finding, so a definition
+  over a cap cannot climb. Warn-level findings do not block a step.
+- Verify each step through the shared
+  [validate-and-dry-run](../spur-cli/references/workflows/operations.md#sub-procedure-validate-and-dry-run)
+  core. The shared step is a promotion, not a copy: record the operator consent that authorizes it,
+  then rebuild the bundle (`bun run --filter @gobing-ai/spur build:bundle`) so the shipped config
+  matches.
+- In an adopting project the shared layer is the installed package and is read-only — the project
+  step is the tuning path there.
+
+## Composition budgets (ADR-115)
+
+The consolidation and cache-window rules are taught once in
+[workflow-fit-and-tuning.md](../spur-cli/references/workflows/workflow-fit-and-tuning.md#consolidation-and-cache-windows-adr-115)
+and owned by the
+[workflow composition contract](../../../../docs/design/workflow-composition-contract.md#composition-budgets-adr-115);
+link them, never restate them. While composing or tuning a workflow, apply them with the ADR-115
+budgets:
+
+- **Merge adjacent model steps** only when they share a role and an executor **and** no gate, HITL
+  state or independence boundary sits between them.
+- **Never merge an author step with the review or verify step that certifies it** — those keep
+  `freshSession: true`.
+- **Run long deterministic work outside `agent.run`** — an in-step tool call that outlasts the
+  cache window idles the model and cold-rewrites the prefix.
+
+A new model step in a shared workflow raises its `pipeline-budgets` `modelQueries`; that needs a
+recorded decision before the shared step.
+
+## Rule tuning loop
+
+Start from trace evidence, never from a guess:
+
+1. `spur rule trace <runId> --json` — read the per-rule `evaluations` findings and severities.
+2. Classify each hit: true positive, false positive, or noise.
+3. Tune with the [fine-tuning levers](../spur-cli/references/rules/fine-tuning.md) — severity,
+   glob scoping, exemptions, preset composition.
+4. `spur rule validate` on the tuned rule files.
+5. `spur rule run` on the affected inputs (constitution T11 — affected inputs, not a corpus sweep).
+6. Trace again and compare. A tuning with no trace pair behind it is a preference.
+
+## Applying doctor proposals
+
+`sp:spur-doctor` ([../spur-doctor/SKILL.md](../spur-doctor/SKILL.md)) returns a proposal table;
+the operator accepts rows; **this skill applies them**:
+
+1. For each accepted row, run its `apply` route — always the `spur` verb or ladder step named in
+   the row. Composer never invents a write route.
+2. Re-run that row's `verify` evidence and confirm it clears. An accepted row that cannot verify
+   is reported as not applied, never waved through.
+3. A `task` row carries the history-anatomy finding `key` in the task body — the existing handoff
+   route. Keep it.
+4. A row that changes a shared workflow goes through the ladder's shared step and its recorded
+   consent.
+
+A caller that wants a record saves the accepted table under `docs/reports/`; this skill creates no
+artifact store.
+
+## What this skill is not
+
+- **Not the judge.** `sp:spur-doctor` evaluates artifacts and proposes; code review is
+  `sp:super-reviewer`.
+- **Not a loop.** Recurring evolution loops and multi-agent coordination belong to
+  `sp:super-planner` or a workflow definition.
+- **Not a catalog.** Verb, flag, output and exit semantics live in the `sp:spur-cli` references
+  linked above.

package/plugins/sp/skills/spur-dev/references/ac-style-guide.md

@@ -113,6 +113,20 @@ Any of the four may additionally carry a **bracket tag** in any position — `[d
 `Scenario: [advisory] Foo`. Tags are stripped before matching (0398 R7), so tagging never breaks
 the linkage.
 
+Task-side, `verify-answer-lint` additionally accepts a fifth declared id source — a **bold-trajectory
+paragraph**: a whole-line `**AC id…**` paragraph inside the task's `### Acceptance Criteria`
+block (task 0817 R3). The id up to its first `:` and the paragraph's full spelling are both
+declared; two bold spans on one line are not a declaration (an interpolated bold id stays
+unmatchable):
+
+```markdown
+### Acceptance Criteria
+
+**AC-0817-HERM-SKIP: unpinned project-config resolution is suppressed.**
+
+| AC-0817-HERM-SKIP | MET | test | `tests/loader.test.ts:962` |        ← declared
+```
+
 ### The id is exactly the scenario title — no Gherkin body appended
 
 An AC row id must be **exactly** the scenario title (plus any of the four forms above), with the

package/plugins/sp/skills/spur-dev/references/cross-cutting.md

@@ -634,9 +634,9 @@ CLI-gated corpus artifact. The `wrapup-pipeline.yaml` `learning-capture` step wr
 
 - **Not CLI-gated.** The file is written directly by the wrap-up pipeline's `learning-capture`
   agent.run step. It does not go through `spur task update` or `spur feature update`.
-- **Not a validated corpus.** The file is a working scratchpad. High-value learnings are promoted
-  to `docs/99_PROJECT_CONSTITUTION.md §8` (lessons) by the `doc-sync` step (via `sp:doc-evolve`),
-  not by the learning-capture step itself.
+- **Not a validated corpus.** The file is a working scratchpad. Deduplicate reusable lessons in
+  existing project learning/context storage. Constitution §8 routes lessons outside that file;
+  doc-sync does not promote lessons into governance without operator-authorized §6.8 scope.
 - **Append-only within a session.** New entries are appended; existing entries are not rewritten.
 - **Grouped by date and task.** Each entry has a date and task WBS header so the operator can
   trace a learning back to its source task.

package/plugins/sp/skills/spur-dev/references/done-housekeeping.md

@@ -128,6 +128,18 @@ silently incomplete (H6 shipped at 23/48 that way, with one verdict carrying an
 `acceptanceCriteria` array and still reading PASS). See `ac-style-guide.md` §
 "Verdict AC ↔ feature scenario linkage" for the id forms and evidence vocabulary.
 
+**Parser contract (verify-answer-lint + `task verdict`, 0817 re-verify findings):**
+
+1. The requirement id cell must be the **bare** id — `| R1 | MET | … |`. Suffixes (`R1 (AC1)`) or
+   decoration (`**R1**`) fail the exact-match completeness check (`missing requirement row`).
+2. The AC table only opens when the header's **third** cell contains the word "evidence" — use
+   `| AC | Status | Evidence Type | Evidence |`. `| AC | Status | Type | Evidence |` silently
+   parses zero AC rows while lint still reports PASS.
+3. A behavioral AC marked `MET` with a non-executable evidence type (`static-ref`,
+   `manual-review`, `llm-judge`) is **downgraded to PARTIAL** by `task verdict`, making the whole
+   verdict PARTIAL. Use `test`/`command` (grep-based verification counts as `command`), or tag the
+   AC id `[non-behavior]`/`[advisory]` when executable evidence genuinely doesn't apply.
+
 **Invariant:** a force-done task has a non-empty `done_reason` naming the timeout, a verdict
 artifact whose AC rows cover every declared scenario, and a green lint/test run recorded in
 `## Testing`.

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

@@ -244,10 +244,52 @@ No token estimate, stage-size threshold, model heuristic, or configuration switc
 resolved absolute path, not the YAML's relative string, is what the dispatched agent is instructed
 to write and what post-join validation reads. Resolving once at the dispatch boundary fixes every
 surface at once; a relative path would resolve against whatever cwd the writer process happens to
-have. 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
+have.
+
+**Dispatch payload (task 0818 R2).** Send exactly these five fields. The earlier "send only the
+stage id, the slash command, and the no-recursion notice" restriction is **deliberately replaced**:
+the execution-tree cwd, the Spur invocation, and the output path are all already resolved at this
+boundary, and a delegate left to re-derive them re-derives them against its own cwd and PATH.
+
+1. The stage id.
+2. The YAML's **exact** pure slash command — unchanged, never reformulated.
+3. `execution surface already resolved: native subagent; do not dispatch this stage again`.
+4. The **confirmed execution-tree cwd** (absolute) and the **resolved absolute Spur invocation** —
+   `vars.spurBin`, i.e. `resolveSpurBin()`'s `<runtime> <mainModule>` form
+   (`apps/cli/src/workflow/resolve-spur-bin.ts`). The delegate MUST run every Spur command through
+   that invocation and MUST NOT rely on a bare `spur`: a competing `spur` earlier on the delegate's
+   PATH otherwise wins. Setting `SPUR_BIN` alone does **not** change bare-command resolution — only
+   using the supplied invocation does. Spur-owned scripted calls take it through the existing
+   `--spur-bin` flag rather than a new mechanism.
+5. The **resolved absolute output path** (`answerFile`/`expectFile`, resolved as above) and the
+   **owning stage's artifact contract** — for a verify stage, the compact contract below.
+
+Nothing else: no task/session transcripts, no machine-specific session paths. The WBS/path already
+carried by the slash command remains the task handoff.
+
+**Verify-stage artifact contract.** A verify handoff names
+[`code-verification/references/verdict-schema.md`](../../code-verification/references/verdict-schema.md)
+as the canonical answer schema and carries this compact form verbatim:
+
+```text
+Verdict: PASS|PARTIAL|FAIL                    top-level, one line
+| Req | Status | Evidence |                   Status = MET | PARTIAL | UNMET
+                                              (N/A and PASS are NOT valid requirement statuses)
+| AC | Status | Evidence Type | Evidence |    Status = MET | PARTIAL | UNMET | N/A (justified)
+Evidence Type = test | command | static-ref | manual-review | llm-judge | n/a
+AC rows use the task's exact AC identities (verbatim `Scenario:` titles / checklist text).
+A behavioral AC marked MET requires executable evidence (test | command);
+static-ref or llm-judge alone cannot carry it.
+```
+
+**Review-stage artifact contract.** A review handoff carries the Review output contract owned by
+`plugins/sp/agents/super-reviewer.md` — native `P1 (blocker)` / `P2 (major)` / `P3 (minor)` /
+`P4 (advisory)` priority cells and section-relative headings — **not** the verify answer schema.
+
+This is an invocation and handoff fix, not a runtime PATH-injection subsystem: it makes no guarantee
+about arbitrary bare commands in host shells or agent-generated shells.
+
+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:

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

@@ -270,6 +270,30 @@ missing title match. After batch creation, `handoff-finalize`:
    (runall is then omitted), otherwise `/sp:dev-runall --feature <id> --auto`. The terminal
    handoff note points at this report.
 
+**Ready preparation (ready-prepare, 0788).** The input is the `.wbs` array in
+`.spur/run/<runId>-idea-batch-create-result.json`. For EACH wbs: resolve the task file with
+`spur task path <wbs> --json` and apply the ready-refinement checklist — make requirements,
+design, plan, acceptance criteria, decisions, dependencies and premises present and
+non-placeholder so `spur task check <wbs> --json` exits 0. Write planning sections only, through
+`spur task update <wbs> --section <Name> --from-file <file>` — never Solution, Testing, Review
+or History. Record one checklist row per id, with concrete evidence of how you verified it.
+Compute the planning digest with the project's own implementation when this is a monorepo
+checkout — resolve the file with `spur task path <wbs> --json`, then run:
+
+```bash
+bun -e 'const m = await import("./packages/app/src/services/task-readiness"); console.log(m.computePlanningDigest(await Bun.file(process.argv[1]).text()))' <task-file>
+```
+
+When that is impossible in this checkout, set status `skipped` instead of guessing a digest.
+Finally write `.spur/run/<runId>-idea-ready.json` with exactly this shape:
+
+```json
+{"runId":"<runId>","depth":"ready","tasks":[{"wbs":"<wbs>","status":"ready" | "failed" | "skipped","planningDigest":"<sha256 hex>","checks":[{"id":"requirements" | "design" | "plan" | "ac" | "decisions" | "dependencies" | "premises","pass":true,"evidence":"<how verified>"}]}]}
+```
+
+A task you cannot fully prepare gets status `failed` or `skipped` — never fabricate evidence;
+the handoff degrades to refineall.
+
 ## Step 6: Refine before execute (the spec-completion gate)
 
 `batch-create` accepts optional `design` / `plan` / `acceptance_criteria` fields (plus

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

@@ -0,0 +1,138 @@
+---
+name: spur-doctor
+description: "Evaluate spur artifacts from read-only CLI evidence — tasks, features, rules, workflows, agent specs — reflect over sp:history-anatomy findings, and return a proposal table. Diagnoses spur artifacts, not runtime environments (that is spur agent doctor). Triggers: check artifact health, propose evolution, reflect over history findings."
+license: Apache-2.0
+version: 1.0.0
+metadata:
+  author: spur
+  platforms: "claude-code,codex,openclaw,opencode,antigravity,pi"
+  category: artifact-composition
+  interactions:
+    - reviewer
+    - inversion
+  operations:
+    - evaluate
+    - reflect
+    - propose
+  openclaw:
+    emoji: "🔬"
+see_also:
+  - sp:spur-cli
+  - sp:spur-composer
+  - sp:history-anatomy
+  - sp:super-planner
+---
+
+# sp:spur-doctor — evaluate spur artifacts and propose changes
+
+One cross-noun method (ADR-114, [spur artifact evolution](../../../../docs/design/spur-artifact-evolution.md)
+§2): gather **read-only CLI evidence** about tasks, features, rules, workflows and agent specs,
+**reflect** over `sp:history-anatomy` findings, and return a **proposal table**. It diagnoses spur
+**artifacts** — definitions, rules, corpus records — not runtime environments: whether an agent
+binary, host session or tool install is healthy is `spur agent doctor`'s job, not this skill's.
+
+## Read-only invariant
+
+The doctor **writes nothing and names no mutating verb**. It performs no task, feature, rule or
+workflow write — the operator accepts rows and `sp:spur-composer`
+([../spur-composer/SKILL.md](../spur-composer/SKILL.md)) applies them. A caller that wants a
+record saves the returned table under `docs/reports/`; the doctor creates no artifact store.
+
+- **History enters only through `sp:history-anatomy` findings.** Raw history records stay out
+  of scope and are never re-interpreted here; history-anatomy is the only history interpreter.
+- **Recurring reflection loops and coordination go to `sp:super-planner`** or a workflow — one
+  bounded evaluation pass per invocation.
+- **Forbidden surfaces: `spur team` and `spur agent loop`.** Agent specs are read only through
+  `spur agent list --specs --json`.
+
+## Evidence per noun
+
+| Noun | Evidence (read-only) |
+| --- | --- |
+| task | `spur task check <wbs> --json` |
+| feature | `spur feature check <id> --json` |
+| rule | `spur rule trace --json`, `spur rule validate` |
+| workflow | `spur workflow validate --json` (findings by `level`), `node "$(superskill script path sp workflow-step-profile.mjs)" <workflow> --json` |
+| agent spec | `spur agent list --specs --json`, read and written through `spur agent` with `--specs`, never `spur team` |
+| history | A `sp:history-anatomy` report ([../history-anatomy/SKILL.md](../history-anatomy/SKILL.md)), never raw history records |
+
+Every row of a proposal cites the evidence it rests on. No anchor, no proposal.
+
+## Workflow step profile and cache-window flags
+
+The step profile (`plugins/sp/scripts/workflow-step-profile`, ADR-065 plugin entrypoint) reads
+`spur workflow trace` for a workflow's last N completed, non-dry runs. Per node and action kind it
+reports run count, executions, p50 and max `durationMs`, p50 idle gap before the step, session mode
+(`fresh`, `resumed` or `mixed`) and `cacheHit` p50 with its coverage — satellite §10 step evidence.
+
+```bash
+node "$(superskill script path sp workflow-step-profile.mjs)" <workflow> --json
+```
+
+`W` is the cache window, **300** seconds by default (satellite §10). The script computes every flag
+arithmetically; doctor maps the flag ids to proposals and never re-derives numbers from prose. Each
+flag and each composition finding becomes one proposal row with action class **workflow
+optimization**, and the change comes from the §10 table:
+
+| Evidence | Flag | Proposed change |
+| --- | --- | --- |
+| Validate finding, `level: error` | always | Extract to an owner from the closed fix vocabulary |
+| Validate finding, `level: warn` | always | Extract, or record a stays-shell reason inside the warn band |
+| Deterministic step | `step-over-window` — p50 > W | Split it, or move the slow work out of the step |
+| Resumed `agent.run` | `resume-after-idle` — p50 idle gap before it > W | `freshSession: true` with the prior artifact as handoff |
+| Resumed `agent.run` | `resume-cold-cache` — `cacheHit` p50 < 0.5, with evidence | The same, or move a long in-step tool call to a deterministic step |
+| `agent.run` | `agent-run-over-2w` — p50 > 2W | Split at an artifact seam, or no-op when none exists |
+
+- The two validate finding rows classify by `level` alone and carry no flag id.
+- A row with `cacheHit.known: 0` raises no cache flag. Its cache evidence is **unknown, never a zero
+  hit rate**, and doctor reports it as unknown rather than as a 0% hit.
+- A proposal that changes a shared workflow goes through §7 of the composition ladder
+  ([spur-composer](../spur-composer/SKILL.md)), including its recorded operator consent.
+
+## Reflection map over history findings
+
+For each history-anatomy finding (`key`, `category`, `trend`, `ownerSurface`), assign **exactly
+one** action class. The first matching row wins:
+
+| # | Finding | Action class |
+| --- | --- | --- |
+| 1 | `trend` is `resolved` or `improved` | no-op |
+| 2 | `category` is `positive` | doc or learning |
+| 3 | Automatable, per step 1 of the [placement rule](../../references/environment-lens.md#placement-rule) | rule candidate |
+| 4 | `ownerSurface` is a workflow definition | workflow optimization |
+| 5 | `ownerSurface` is a doc, skill, reference or steering file | doc or learning |
+| 6 | Anything else | task |
+
+The five action classes are closed: **task**, **rule candidate**, **workflow optimization**,
+**doc or learning**, **no-op**. The doctor classifies the report's findings and never derives new
+ones from raw records — that would make it a second history interpreter.
+
+## Proposal table
+
+Return one row per actionable finding, with exactly these columns:
+
+| Column | Content |
+| --- | --- |
+| `key` | The finding key, or `<noun>:<id>:<check>` for an artifact finding |
+| `evidence` | The CLI output or report section the row rests on |
+| `action` | One action class from the reflection map (or the per-noun evaluation) |
+| `change` | The proposed change, in one line |
+| `apply` | The `spur` verb or composer procedure that lands it |
+| `verify` | The evidence to re-run after applying |
+
+Rules:
+
+- The `apply` route is always a `spur` verb or a gated composer step — never a raw file edit this
+  skill performs. Shared-workflow rows route through the composition ladder's shared step.
+- A `task` row carries the finding `key` in the task body (the history-anatomy handoff route).
+- Rows are proposals only. No applied change, diff, or command output claimed as run.
+
+## What this skill is not
+
+- **Not the applier.** `sp:spur-composer` applies accepted rows; this skill performs no
+  task/feature/rule/workflow write.
+- **Not a runtime doctor.** Environment, binary and session readiness belong to
+  `spur agent doctor`; this skill diagnoses spur artifacts from CLI evidence.
+- **Not a history interpreter.** Findings come from `sp:history-anatomy` reports, never from raw
+  history records.
+- **Not a loop.** Recurring evolution passes belong to `sp:super-planner` or a workflow.

package/plugins/sp/skills/taste-refactoring-api/README.md

@@ -0,0 +1,43 @@
+# taste-refactoring-api
+
+A reusable agent skill for designing, reviewing, and safely refactoring production APIs.
+
+## What it covers
+
+- REST/HTTP
+- RPC/gRPC
+- GraphQL
+- events/webhooks
+- domain/resource modeling
+- naming and schemas
+- errors
+- pagination/filtering/sorting
+- idempotency and retries
+- concurrency
+- versioning/deprecation/migration
+- API security
+- observability
+- reliability/performance
+- contract testing and documentation
+
+## Suggested installation
+
+Install/copy this directory as an agent skill named `taste-refactoring-api` and load `SKILL.md` as the skill instructions. Keep the `references`, `checklists`, and `examples` directories available for deeper reviews.
+
+## Daily usage examples
+
+- “Use taste-refactoring-api to review this OpenAPI spec.”
+- “Refactor these Express routes without breaking current clients.”
+- “Review this GraphQL schema for compatibility and developer experience.”
+- “Design a safe pagination and filtering contract for this endpoint.”
+- “Create a migration plan from v1 to v2 with no abrupt client breakage.”
+- “Run the daily API quality checklist on this PR.”
+
+## Files
+
+- `SKILL.md` — main agent operating instructions
+- `references/api-refactoring-playbook.md` — deeper operational guidance
+- `references/research-basis.md` — standards and sources used to build the skill
+- `checklists/daily-api-review.md` — fast daily checklist
+- `examples/review-template.md` — reusable review format
+- `examples/refactor-example.md` — worked refactoring example