@gobing-ai/spur 0.3.62 → 0.3.64

package/plugins/sp/skills/redesign-web-ui/references/upgrade-techniques.md

@@ -0,0 +1,66 @@
+# Upgrade techniques
+
+Optional moves for `sp:redesign-web-ui` Plan/Apply. Load this file only when a Diagnose finding
+needs a technique from it.
+
+Every technique here is **polish**. Accessibility and token authority always win. Honor
+`prefers-reduced-motion: reduce` by disabling or replacing motion with an instant state change.
+
+Product/app chrome (dashboards, settings, editors) stays restrained. Marketing/landing pages can
+spend more on one signature moment. Spend boldness in **one** place.
+
+---
+
+## When a technique is in play
+
+Use a technique when:
+
+- The finding is `polish`, and
+- The page type supports it (landing/marketing, or a single product moment), and
+- The authority layer (`DESIGN.md` / theme) does not forbid it.
+
+Skip the technique when:
+
+- It requires a new animation library or a CSS-framework migration.
+- It hijacks scroll (inertia/custom scrollbar physics) on a product UI.
+- It would be the second signature moment on the same page.
+
+---
+
+## Typography
+
+- **Variable-font weight/width** on hover or a short scroll range — one word or one heading, not every line.
+- **Outlined-to-fill** on a display line that is the page's thesis.
+- **Text as mask** only when a real, owned video/image sits behind it.
+
+## Layout
+
+- **Broken grid / overlap** — one element bleeds or overlaps on purpose; the rest stay on the grid.
+- **Whitespace maximization** — one block gets aggressive negative space so it is the only focus.
+- **Sticky stack** — sections pin and stack on scroll on a marketing long-scroll, not inside app chrome.
+- **Split-screen scroll** — two panes moving in opposition; marketing only, and never the only way to reach content.
+
+## Motion
+
+- **Staggered entry** — small Y + opacity cascade on first paint of a group (40–80ms steps).
+- **Spring on press** — interactive controls, not page load.
+- **Scroll-driven reveal** — mask, wipe, or SVG draw tied to scroll *progress*, with a reduced-motion static end-state.
+
+Do not add smooth-scroll inertia, scrolljacking, or a custom scrollbar on product UI. Native
+`scroll-behavior: smooth` plus a reduced-motion instant fallback is the ceiling unless the operator
+asks for more.
+
+## Surfaces
+
+- **Glass** — `backdrop-filter` plus a 1px inner border and a faint inner shadow; only over content
+  that remains readable.
+- **Spotlight border** — cursor-tracking edge light on one featured card.
+- **Grain overlay** — `pointer-events: none`, fixed, very low contrast; skip on dense data tables.
+- **Tinted shadows** — shadow hue matches the surface, not generic black.
+
+---
+
+## Signature test
+
+After picking techniques, keep one memorable moment. If two techniques compete, drop the weaker
+one. The surrounding UI stays quiet so the signature can read.

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

@@ -23,9 +23,9 @@ that before using `run` for fan-out dispatch.
 | ---- | ------- | --------- |
 | `run <prompt>` | Execute a prompt or slash command via a coding agent | `--agent <name>` `--spec <id>` `--model <name>` `--mode <mode>` `--continue` `--cwd <path>` `--drain` `--json` |
 | `loop` | Persistent self-draining inbox loop for a team member (supervisor-managed) | `--spec <id>` `--agent <id>` `--poll <ms>` |
-| `wait <specId>` | Identity-pinned wait for an occupant run to reach a lifecycle state (G4 wave 2) | `--run <runId>` `--until <state>...` `--timeout <ms>` `--json` |
+| `wait [<specId>]` | Identity-pinned wait for an occupant run to reach a lifecycle state (G4 wave 2; `--role` selector per 0685) | `--role <name>` `--run <runId>` `--until <state>...` `--timeout <ms>` `--json` |
 | `list` | List detected coding agents, or team agent specs with `--specs` | `--specs` `--json` |
-| `doctor [agent]` | Check agent readiness | `--json` |
+| `doctor [agent]` | Check agent readiness | `--json` `--probe-health` `--force-refresh` |
 | `create <id>` | Write a team agent spec to `.spur/agents/<id>.yaml` | `--type` `--tags` `--model` `--autonomy` `--system-prompt` `--name` `--workspace` `--purpose` `--auto-start` `--no-identity-preamble` `--json` |
 | `edit <id>` | Open an agent spec in `$EDITOR`, or print its path | - |
 | `delete <id>` | Remove an agent spec | `--force` |
@@ -48,7 +48,7 @@ through a coding agent as an external process, producing a persisted run record
 
 | Flag | Purpose |
 | ------ | --------- |
-| `--agent <name>` | Role, executor, agent binary, `auto`, or `inline`. A **role** (`scribe`/`coder`/`reviewer`/`planner`, from `plugins/sp/references/roles.md`) selects the starting tier; an **executor** (an `agent.executors` entry) is a permanent pin; a **bare binary name** works with a one-time warning (transition shim); `auto` uses the declared/default role. **`inline` is host-session-only** (G5 / ADR-047 amendment): `agent run` is a headless subprocess surface, so explicit `inline` is rejected with exit 2 and a stable error message — it never normalizes to `agent.default`. |
+| `--agent <name>` | Role, executor, agent binary, `auto`, or `inline`. A **role** (`scribe`/`coder`/`reviewer`/`planner`, from `plugins/sp/references/roles.md`) selects the starting tier; an **executor** (an `agent.executors` entry) is a permanent pin; a **bare binary name** works with a one-time warning (transition shim); `auto` uses the declared/default role. `inline` is the default selector (0687 / ADR-087): on a host session the work runs in-session; on a headless subprocess surface like `agent run` it substitutes tier resolution and warns once naming the resolved executor — no rejection, no `agent.default` normalization. |
 | `--model <name>` | Agent model argument (e.g. `o3`, `sonnet`). Passed through to the agent's model flag. |
 | `--mode <mode>` | Agent output mode: `text` or `json`. |
 | `--continue` | Resume the previous agent session instead of starting fresh. |
@@ -108,12 +108,18 @@ into `run` with `--drain` -> else sleep for `--poll` ms.
 spur agent wait reviewer                          # default --until idle
 spur agent wait reviewer --run R3 --until invoke-exit
 spur agent wait reviewer --until working --until invoke-exit --timeout 30000 --json
+spur agent wait --role reviewer                   # role-addressed: resolves to exactly one instance
 ```
 
 `wait` pins an occupant's identity (`specId` + `runId` + `generation`) from the snapshot at wait
 start, then polls until the first satisfied `--until` (OR). `--run` pins an explicit run; default
 is the spec's latest run. Replacement, generation bump, or disappearance fails fast; a non-working
 occupant that makes no progress inside the stall budget fails `wait_stalled`.
+Addressing takes `<specId>` **or** `--role` — never both. `--role` resolves against materialized
+instances (vocabulary = `AGENT_ROLE_NAMES` ∪ executor names); zero/multi matches are hard errors
+naming `count=0` + candidates `none` or `count=N` + candidate ids
+(`selector_unmatched` / `selector_ambiguous`, exit 1), an unknown name
+exits 2 naming the accepted vocabulary. Resolution collapses onto the same identity pin.
 
 ### Flags
 
@@ -149,12 +155,15 @@ lists team agent specs (`.spur/agents/*.yaml`).
 
 ```bash
 spur agent doctor            # all detected agents
-spur agent doctor claude     # one agent
-spur agent doctor --json     # machine-readable
+spur agent doctor claude     # one agent (executor/agent name → detail block)
+spur agent doctor coder      # pipeline role id → eligible ladder with ELECTED marker
+spur agent doctor --json     # machine-readable (role selector: elected-first ordering)
 ```
 
-Checks whether each agent is installed and ready to run. Returns exit `1` if any checked agent is
-not ready.
+Checks whether each agent is installed and ready to run. Text mode renders a capability table —
+`STATUS EXECUTOR AGENT MODEL TIER VERSION ROLES` where TIER is the executor's *capability* tier
+(`cheap|standard|capable-*`), MODEL the pinned config model (`—` when undeclared), and ROLES lists
+candidate pipeline roles with `*` on the elected one. Exit `1` if any checked agent is not ready.
 
 ## `create` - author a team agent spec
 

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

@@ -19,7 +19,7 @@ use it well*.
 
 | Verb | Purpose | Key flags |
 | ---- | ------- | --------- |
-| `send <body>` | Enqueue a message for an agent | `--to <id>` `--from <id>` `--wait` `--until <state>` `--timeout <ms>` `--json` |
+| `send <body>` | Enqueue a message for an agent | `--to <id>` `--role <name>` `--from <id>` `--wait` `--until <state>` `--timeout <ms>` `--json` |
 | `inbox` | List messages addressed to an agent | `--agent <id>` `--json` |
 | `reply <msg-id> <body>` | Thread a reply to a message | `--json` |
 | `watch` | Follow an agent inbox - surface new messages as they arrive | `--agent <id>` `--interval <ms>` `--json` |
@@ -34,6 +34,7 @@ spur message send "Please review PR 42" --to reviewer
 spur message send "Task 0040 is blocked" --to worker-1 --from operator
 spur message send "Done" --to planner --json
 spur message send "Review 0042" --to reviewer --wait --until invoke-exit --timeout 30000
+spur message send "Start the pass" --role reviewer          # resolves to exactly one instance
 ```
 
 Enqueues a durable message addressed to `--to <id>`. The recipient drains it on its next `agent run
@@ -47,7 +48,8 @@ wait; enqueue is **not** rolled back if the wait later fails.
 
 | Flag | Purpose |
 | ------ | --------- |
-| `--to <id>` | **Required.** Recipient agent id. |
+| `--to <id>` | Recipient agent id. Mutually exclusive with `--role`; exactly one of the two is required. |
+| `--role <name>` | Address by Layer-1 role or executor name. Must resolve to exactly one materialized instance; zero (`count=0`, candidates `none`) or multi (`count=N` + candidates) matches are hard errors (exit 1); unknown name exits 2 naming the accepted vocabulary (`AGENT_ROLE_NAMES` ∪ executor names). Resolution yields the same spec-id path as `--to`; `--wait` snapshots that occupant pin. (0685 R6 / ADR-075 amendment) |
 | `--from <id>` | Sender id (default: `operator`). |
 | `--wait` | Block until the recipient reaches `--until` (snapshots occupant before send). |
 | `--until <state>` | Wait target: `injected` \| `invoke-exit` (repeatable OR). Default `invoke-exit`. |

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

@@ -218,9 +218,14 @@ verifying shape, or stand in a `note` action until the path is proven, then swap
 
 ## Authoring checklist
 
+- [ ] Fit gate cleared before the mode gate — replay + machine-checkable branch + durable record
+      ([workflow-fit-and-tuning.md](workflow-fit-and-tuning.md#1-fit-gate--workflow-or-prose)).
 - [ ] Mode chosen deliberately (loop → state-machine; pipeline → transition-flow); recorded the reason.
 - [ ] `kind: transition-flow` set for flows; `$schema` quoted.
 - [ ] Initial + terminal states/nodes declared; every transition/edge target exists.
 - [ ] Guards/conditions ordered so the specific case precedes the fallback.
 - [ ] `iterationBound` set for any loop; `env.allow` lists every `${env.X}` used.
+- [ ] Every node inside the simplicity budget — `shell` at or under 5 non-comment units,
+      `agent.run` input referencing a command rather than a raw prompt, guards a single predicate
+      ([workflow-fit-and-tuning.md](workflow-fit-and-tuning.md#3-node-simplicity-budget)).
 - [ ] Validates clean AND dry-run reaches the expected terminal state.

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

@@ -161,22 +161,31 @@ Turn a described process into a validated, dry-run-verified workflow in the righ
 1. **Clarify intent** — restate the process as one or two sentences: the steps, the success terminal,
    the loop/branch points. If ambiguous (which step retries? what ends it?), state the interpretation
    taken.
-2. **Mode-selection gate** — run [mode-selection gate](#sub-procedure-mode-selection-gate). This is
+2. **Fit gate** — run the three-part test in
+   [workflow-fit-and-tuning.md](workflow-fit-and-tuning.md#the-three-part-test) *before* the mode
+   gate: the process earns a workflow only if it replays, branches on a machine-checkable predicate,
+   and needs a durable per-run record. Fewer than three → recommend a descriptive procedure /
+   checklist instead and stop; do not author YAML the process will not use.
+3. **Mode-selection gate** — run [mode-selection gate](#sub-procedure-mode-selection-gate). This is
    mandatory and gating: surface the recommended mode with its reason and the rejected alternative,
    and **confirm before authoring**. Honor an explicit `--kind`.
-3. **Reconcile against existing workflows** — run [find-existing-workflow](#sub-procedure-find-existing-workflow).
+4. **Reconcile against existing workflows** — run [find-existing-workflow](#sub-procedure-find-existing-workflow).
    If the process is already covered, **stop and hand to refine (or extend the existing flow) on
    confirmation** — do not author a redundant workflow. Only the "no real match" / "add-new" branch
    proceeds to author below.
-4. **Author the YAML** — use the **real schema shape** for the chosen mode
+5. **Author the YAML** — use the **real schema shape** for the chosen mode
    ([authoring-workflows.md → Per-mode shapes](authoring-workflows.md#per-mode-shapes)). Set `name`,
    `description` (the WHY), the initial + terminal states/nodes, the steps with their actions, the
    transitions/edges with guards/conditions in the right declaration order, `iterationBound` for any
    loop, `env.allow` for any `${env.X}`, and a quoted `$schema`. For transition-flow, set
    `kind: transition-flow`.
-5. **Place the file** — default `.spur/workflows/<name>.yaml` (a `--file` arg overrides), named for
+   Keep each node inside the simplicity budget
+   ([workflow-fit-and-tuning.md](workflow-fit-and-tuning.md#3-node-simplicity-budget)): `shell`
+   commands at or under 5 non-comment units, `agent.run` inputs referencing a slash command rather
+   than carrying a raw prompt, guards a single predicate.
+6. **Place the file** — default `.spur/workflows/<name>.yaml` (a `--file` arg overrides), named for
    what the workflow does.
-6. **Verify** — run the [validate-and-dry-run core](#sub-procedure-validate-and-dry-run) with the
+7. **Verify** — run the [validate-and-dry-run core](#sub-procedure-validate-and-dry-run) with the
    expected terminal state. Not done until the definition validates AND the dry-run reaches it.
 
 Output contract: YAML workflow content + chosen mode + reason + destination path + validate result +
@@ -197,6 +206,12 @@ Adjust an existing workflow with the smallest change that meets the intent. Proc
    - missing step → add a state/node + its transition/edge in the correct declaration order
    - runaway loop → set or raise `iterationBound`
    - missing variable/env → add to `vars` or `env.allow`
+   - too slow / unreadable trace (not a correctness bug) → the
+     [optimize procedure](workflow-fit-and-tuning.md#optimize--refine-an-accepted-workflow-in-place),
+     backed by a before/after `spur workflow trace <run-id> --json` pair
+   - the whole file is the wrong surface (all nodes raw `agent.run`, no branching, edited more than
+     run) → not a refine: the
+     [demote procedure](workflow-fit-and-tuning.md#demote--workflow--descriptive-procedure)
    See [authoring-workflows.md](authoring-workflows.md) for each mechanism's real shape. **Do not
    switch mode** in a refine — a mode change is a rewrite; hand it back to `add`.
 3. **Apply the smallest change.** Preserve declaration order semantics (the first passing

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

@@ -0,0 +1,230 @@
+---
+name: workflow-fit-and-tuning
+description: Decide whether a process should be a spur workflow at all, tune an accepted one for latency and observability, keep its nodes inside the simplicity budget, and refactor across the boundary — promote a descriptive procedure into YAML, demote a YAML back to prose, or optimize one in place.
+see_also:
+  - spur-cli
+  - operations
+  - authoring-workflows
+---
+
+# Workflow Fit & Tuning
+
+Three questions that sit **before and around** the mode gate:
+
+1. **Fit** — should this be a `spur workflow` at all, or a descriptive procedure / checklist?
+2. **Tuning** — given it is one, how is it configured for low latency and legible traces?
+3. **Refactor** — how do you move a process across that boundary in either direction?
+
+**Polaris:** get things done with high efficiency, low latency, and observability. A workflow that
+does not beat prose on all three is prose with a YAML tax.
+
+---
+
+## 1. Fit gate — workflow or prose?
+
+Run this **before** the [mode-selection gate](operations.md#sub-procedure-mode-selection-gate). The
+mode gate answers *which kind of workflow*; it presumes an answer to *whether* — and that
+presumption is the more expensive one to get wrong.
+
+### What each side actually buys
+
+| | `spur workflow` YAML | Descriptive procedure (skill reference, slash command, checklist) |
+| --- | --- | --- |
+| Buys you | Durable run record, resumable HITL pause, bounded retry loops, machine-readable terminal status, `trace`/`--follow`, `cancel`/`clean`, unattended `--async` | Judgment at every step, zero authoring ceremony, edits are one-line, no subprocess per step |
+| Costs you | Authoring + `validate`/`dry-run` upkeep, one subprocess per action node, indirection an agent must read through, a definition that rots when the surface moves | Nothing is replayable, nothing is recorded, "what happened on that run" is unanswerable |
+| Fails at | Steps whose outcome only a reader can judge | Anything that must run the same way twice, unattended |
+
+### The three-part test
+
+A process earns a workflow only when **all three** hold:
+
+- **Replay** — it runs repeatedly, unattended, or across different operators.
+- **Branch** — at least one step routes on a *machine-checkable* predicate (exit code, JSON field,
+  file present), and the run may retry or gate on it.
+- **Record** — someone will later need to answer "what happened on run X" from persisted evidence.
+
+Three yes → author the workflow. Two → borderline: prefer prose plus one shell script, and revisit
+when the run count justifies it. One or zero → **descriptive procedure**; say so and stop.
+
+### Signals
+
+| Signal in the described process | Read as |
+| --- | --- |
+| "Retry until the gate passes", "loop until clean" | workflow — bounded loop is the engine's job |
+| "Pause for approval, continue later / in another session" | workflow — HITL resume needs a run record |
+| "Every night", "for each task in the batch", unattended | workflow — replay + record |
+| "Then check whether it looks right and decide" | prose — the predicate is judgment, not an exit code |
+| "It depends what the diff says" | prose — the branch has no machine-checkable condition |
+| Runs once, then the situation has changed | prose — a checklist, not a definition |
+| One operator, in-session, watching each step | prose — the trace has no second reader |
+
+### The two anti-patterns
+
+- **Prose wearing YAML.** Every node is an `agent.run` with a raw prompt, edges are all
+  unconditional. The engine adds a process spawn per node and contributes no branching, no gate, no
+  retry. This is the ADR-069 R2 measure firing on *every* node — the advisory is telling you the
+  whole file is misplaced, not that eight prompts need polish. Demote it.
+- **YAML wearing prose.** A skill reference that says "then run the checks, and if they fail fix and
+  re-run, up to three times" — a bounded retry loop written as a paragraph an agent re-interprets
+  every session, with no record of how many attempts actually happened. Promote it.
+
+### Hybrid is the usual answer
+
+The boundary runs *through* most processes, not around them. Keep judgment in the skill or slash
+command; put the deterministic gate loop in the workflow; let the workflow's judgment steps call the
+command by name. That is the ADR-043 preference restated as an architecture: **the workflow selects
+and orders capabilities, it does not contain them** (ADR-069).
+
+---
+
+## 2. Tuning — latency, efficiency, observability
+
+### Cost model — know what you are spending
+
+| Node / element | Real cost | Consequence for design |
+| --- | --- | --- |
+| `agent.run` action | A full agent session: seconds to minutes, plus tokens | **The dominant cost.** Count them; every one you remove is the largest single win available |
+| `shell` action | One `sh -c` subprocess, milliseconds | Cheap individually — but each node is also a persisted transition round-trip |
+| Guard (`kind: shell`) | One subprocess **per evaluation**, re-run on every loop iteration | A loop with a bound of 5 pays its guards 5 times |
+| Loop `iterationBound` | Worst case = bound x per-iteration cost | It is a **latency ceiling**, not only a runaway safety net |
+| HITL pause | Unbounded wall-clock (waits on a human) | Never put one inside a loop body |
+
+### Latency checklist
+
+- [ ] **Fewest `agent.run` nodes that still do the work.** Two adjacent judgment steps with no gate
+      between them are one judgment step.
+- [ ] **Soft status-file probe over repeated probing.** Run the expensive check once in an action
+      that always exits 0 and writes its verdict to a run-scoped file; branch with ordered cheap
+      guards that read that file. One subprocess instead of one per branch — the `basic.yaml` and
+      `task-pipeline.yaml` quality-gate idiom.
+- [ ] **Order guards cheapest-discriminating-first.** The first passing guard wins, so a `test -f`
+      ahead of a `spur … --json` parse skips the expensive call on the common path.
+- [ ] **No guard recomputes what a prior node already wrote to disk.**
+- [ ] **`iterationBound` from the budget, not from optimism.** Set it to the observed maximum plus
+      one; a bound of 10 on a 40-second gate is a seven-minute worst case nobody chose.
+- [ ] **Fan out only genuinely independent branches** (`type: parallel`, transition-flow). Serial
+      nodes with no data dependency are pure dead latency.
+- [ ] **`--async` when the caller does not need the terminal state inline**, then follow with
+      `spur workflow trace <run-id> --follow`.
+
+### Observability is an authoring decision, not a run flag
+
+The flags (`--detail`, `--verbose`, `--trace-file`, `--follow`, `--output`) are catalogued in
+[../workflows.md](../workflows.md); they only expose what the definition already made legible.
+
+- [ ] **Name states/nodes after the outcome they establish, not the tool they invoke.**
+      `quality-gate-passed` reads at 3am; `run-script-2` does not.
+- [ ] **`description` carries the WHY** of the workflow; a one-line comment carries the why of any
+      non-obvious guard order or `iterationBound`.
+- [ ] **Every gate writes a machine-readable verdict to a run-scoped file.** It is the guard's input
+      *and* the post-mortem's evidence — one artifact, two consumers.
+- [ ] **Declare `failureStates`** so a failed run reports `status: 'failed'` instead of finalizing as
+      a `done` run that landed somewhere bad (the 0425 reader contract).
+- [ ] **`env.allow` lists exactly what is used** — no more; an over-broad allowlist is an
+      undocumented dependency.
+- [ ] **While tuning:** `--detail full` plus `--trace-file`, and compare traces. **In production:**
+      default detail, retained run log.
+
+---
+
+## 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 an owner from the five recorded options in
+`docs/design/workflow-shell-ownership.md`: public `spur` verb (consent-gated), application service,
+least-privilege built-in action kind, workflow-relative external extension, or a recorded
+stays-shell exception with its reason in `config/workflow-composition-baseline.json`.
+
+**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.
+
+---
+
+## 4. Refactor — moving across the boundary
+
+Three named directions. All three end in the shared
+[validate-and-dry-run core](operations.md#sub-procedure-validate-and-dry-run) when a YAML definition
+survives the change.
+
+### promote — descriptive procedure → workflow
+
+Use only when the [fit gate](#the-three-part-test) clears all three parts. Steps:
+
+1. **Split the prose into spine and judgment.** The spine is every step whose outcome is
+   machine-checkable. Everything else stays judgment and does *not* become a node's inline prompt.
+2. **Name the terminals** — the success terminal, and every failure terminal that deserves its own
+   name. Declare them in `failureStates`.
+3. **Run the [mode-selection gate](operations.md#sub-procedure-mode-selection-gate)** — the spine's
+   shape decides it: retry loop → state-machine; forward pipeline → transition-flow.
+4. **Author one node per spine step.** Each judgment step becomes an `agent.run` whose `input`
+   *references the existing slash command or skill* — never a copy of the prose. If no such command
+   exists, create it first; a promotion that inlines prompts has produced anti-pattern one.
+5. **Verify** with validate-and-dry-run against the expected terminal.
+6. **Rewrite the descriptive doc as the entry point** — it now explains the WHY and delegates to
+   `spur workflow run`, rather than restating the steps. Two copies of the procedure is the drift
+   the promotion was supposed to end.
+
+### demote — workflow → descriptive procedure
+
+Triggers (any two are sufficient; the first alone is sufficient):
+
+- Every node is an `agent.run` with a raw prompt and every edge is unconditional.
+- The definition has been edited more often than it has been run.
+- The graph is a straight line — no guard, no gate, no loop.
+- The run count over its lifetime is in the single digits and not growing.
+- Its `iterationBound` has never been reached because nothing ever loops.
+
+Steps:
+
+1. **Check for live dependents** — `spur workflow trace --workflow <name> --last 20 --json` for
+   recent runs, and grep the shipped surfaces for the filename. A definition another command invokes
+   is not demoted unilaterally.
+2. **Return each node's work to its owner** — judgment nodes to the command or skill they should
+   have been calling; a genuinely useful shell sequence to one script under its owning surface.
+3. **Rewrite the entry surface as the procedure**, in the order the graph ran.
+4. **Delete the YAML and its `config/workflow-composition-baseline.json` entries** in the same
+   change. A baseline entry whose action no longer exists fails the two-sided check.
+5. **Record the demotion** and its trigger, so the next author does not re-promote it by reflex.
+
+### optimize — refine an accepted workflow in place
+
+A [refine](operations.md#refine) whose `--intent` is latency or legibility rather than correctness.
+Dimensions, highest leverage first:
+
+1. **Remove or merge `agent.run` nodes** — the dominant cost, always the first pass.
+2. **Collapse probe-then-branch into a soft status-file probe** with ordered guards.
+3. **Reorder guards** cheapest-discriminating-first.
+4. **Lower `iterationBound`** to the observed maximum plus one.
+5. **Merge nodes that always run together** with no guard between them.
+6. **Move any `>= 6`-unit shell program to a recorded owner** (never by reformatting).
+7. **Rename states/nodes to outcomes** and add the missing `failureStates`.
+
+**Measure, do not estimate.** Capture `spur workflow trace <run-id> --json` before and after and
+compare wall-clock per state and the transition sequence. An optimization with no trace pair behind
+it is a preference. Rules that still bind: the smallest change that meets the intent, no mode
+switch inside a refine (that is a rewrite — hand it to `add`), and never edit a workflow that is
+currently executing.
+
+---
+
+## Checklist
+
+- [ ] Fit gate run **before** the mode gate; the prose-vs-workflow verdict stated with its reason.
+- [ ] All three of replay / branch / record hold, or the answer was a descriptive procedure.
+- [ ] Judgment steps reference an existing command; none inline a raw prompt.
+- [ ] `agent.run` node count is the minimum the branching requires.
+- [ ] `iterationBound` chosen from a latency budget; guards ordered cheapest-first.
+- [ ] States/nodes named for outcomes; `failureStates` declared; gates write a verdict file.
+- [ ] Every `shell` action within the <= 5-unit budget, or carrying a recorded owner/disposition.
+- [ ] Refactors verified through validate-and-dry-run; optimizations backed by a before/after trace.

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

@@ -9,12 +9,24 @@ see_also:
 
 `spur workflow` runs declarative YAML workflows (powered by `@gobing-ai/ts-dual-workflow-engine`) that
 orchestrate a multi-step process — an implement→check→fix loop, an import→validate→transform→write
-pipeline, an approval gate. The engine executes **two distinct workflow kinds**, and the first act of
-any new workflow is choosing between them. Get the mode right and the rest of authoring follows the
+pipeline, an approval gate. The engine executes **two distinct workflow kinds**, and choosing between
+them is the first act of *authoring*. Get the mode right and the rest of authoring follows the
 schema; get it wrong and you fight the engine.
 
-Operating a workflow well is a full lifecycle — choose the mode, author the YAML, validate it, run it,
-read the trace, and refine. This skill covers all of it.
+Operating a workflow well is a full lifecycle — decide it should be a workflow at all, choose the mode,
+author the YAML, validate it, run it, read the trace, tune it, and refine. This skill covers all of it.
+
+## Decide it is a workflow at all — before the mode
+
+The mode gate presumes the process belongs in YAML. That presumption is the more expensive one to get
+wrong: a workflow whose nodes are all raw `agent.run` prompts is a descriptive procedure paying a
+process spawn per step, and a bounded retry loop written as a paragraph in a skill reference is a
+workflow nobody authored. Run the **fit gate** first — a process earns a workflow only when it
+replays, branches on a machine-checkable predicate, **and** needs a durable per-run record.
+
+Fit gate, cost model, latency/observability tuning, the node simplicity budget, and the
+promote / demote / optimize refactor procedures:
+[workflows/workflow-fit-and-tuning.md](workflows/workflow-fit-and-tuning.md).
 
 ## Choose the execution mode first
 
@@ -62,6 +74,9 @@ before authoring. Full procedure: [workflows/authoring-workflows.md](workflows/a
 
 Use this skill to:
 
+- **Decide fit** — judge whether a process should be a workflow at all or stay a descriptive
+  procedure / checklist, and tune an accepted one for latency and legible traces.
+  → workflows/workflow-fit-and-tuning.md
 - **Author a workflow** — turn a described process into a validated, dry-run-verified YAML definition
   in the right mode. → authoring-workflows.md
 - **Validate before trusting** — schema + semantic-check a workflow file (references, terminal
@@ -70,6 +85,9 @@ Use this skill to:
   taken, terminal status).
 - **Refine an existing workflow** — fix a stuck guard, add a state/node, retune `iterationBound`,
   re-scope variables / `env.allow`, with the smallest change. → workflows/operations.md
+- **Refactor across the prose/YAML boundary** — promote a descriptive procedure into a workflow,
+  demote a workflow back to prose, or optimize an accepted one for latency.
+  → workflows/workflow-fit-and-tuning.md
 - **Extend the engine** — register a custom action/guard runner or a trust-gated extension module when
   the built-ins (`note`, `shell`, `always`, `action-ok`) fall short. → workflows/validation-and-extension.md
 
@@ -362,6 +380,10 @@ the workflow's actions (`shell`, custom runners) do that; this skill builds and
 
 ## Additional Resources
 
+- [workflows/workflow-fit-and-tuning.md](workflows/workflow-fit-and-tuning.md) — the fit gate
+  (workflow vs. descriptive procedure), the per-node cost model, latency and observability tuning,
+  the node simplicity budget tied to the frozen ADR-069 measures, and the promote / demote /
+  optimize refactor procedures. Read before `add` and before any performance-motivated `refine`.
 - [workflows/operations.md](workflows/operations.md) — the operation procedures (validate/run/list/add/refine),
   the shared find-existing-workflow and validate-and-dry-run cores, and the mode-selection gate. The
   entry point for slash-command delegation.