@gobing-ai/spur 0.3.63 → 0.3.64

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.

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

@@ -36,21 +36,20 @@ answer. Everything below is a consequence of that sentence, not an additional ru
 **Default: execute the backing skill directly in the current coding-agent session.** Do not invoke
 `spur agent run` when no escalation trigger applies and the operator did not select subprocess via
 the `--agent` selector. Omitting `--agent` keeps the default — the backing skill runs in the
-current session, and eligible model stages may dispatch once to a native subagent (task 0508). The
-explicit value is useful in scripts and audit output but is not the default: explicit `inline`
-selects the zero-dispatch carve-out below.
+current session, and eligible model stages may dispatch once to a native subagent (task 0508).
+Explicit `inline` resolves identically (0687 R1: inline is the default selector; R2 generalized
+native-subagent eligibility from omit-only to all inline resolutions).
 
-> **Explicit `--agent inline` is a hard host-session guarantee: all model-bearing work executes in
-> the invoking host session — never a native subagent, never a subprocess, never a workflow hop.
-> The 0508 native-subagent eligibility applies to **omitted** `--agent` only. Headless surfaces
-> (`spur agent run`, workflow `agent.run`, serve-side dispatch) reject `inline` with the stable
-> special error (exit 2 at the CLI) and take no further action — no dispatch, no `agent.default`
-> fallback.**
+> **`--agent inline` (explicit or omitted) is an honest selector, not a dispatch guarantee. On a
+> host session the work runs in-session and eligible model stages may use a native subagent (0508,
+> as generalized by 0687 R2). A headless dispatch surface (`spur agent run`, workflow `agent.run`,
+> serve-side dispatch) cannot host a session; there AgentService substitutes tier resolution and
+> warns once naming the resolved executor (0687 R3) — no rejection, no `exit 2`.**
 
 | Value | Who does the work | Derived surface |
 | --- | --- | --- |
 | `(omitted)` | The agent running this session | Host session — host-controlled; eligible model stages may use a native subagent (0508) |
-| `inline` | The agent running this session | Host session — hard guarantee: zero dispatch, never a subprocess, never a workflow hop; headless surfaces reject `inline` (exit 2, stable special error) |
+| `inline` | The agent running this session | Inline host session — identical to omitted (0687 R1); on headless surfaces tier resolution substitutes with a warning (0687 R3) |
 | `auto` | The role the caller declared — this command's `role:` frontmatter or the workflow step's `role:` (Layer 1, `plugins/sp/references/roles.md`); with nothing declared, `agent.default`'s role (0542) | Subprocess — a tier-resolved executor pins a specific agent/model, which the host session cannot supply |
 | `<name>` (coding agent or configured executor) | That executor | Inline when it resolves to the current session's agent; subprocess otherwise |
 
@@ -58,15 +57,9 @@ The previous `--inline` and `--subprocess` flags (feature H82, task 0413) are co
 single selector: `--inline` → `--agent inline`, `--subprocess` → `--agent auto`. The old two-flag
 form is no longer part of the command surface.
 
-This is a prompt-runtime rule owned by the command wrapper and its backing skill, not a branch in
-`AgentService`: the current coding agent is already executing the command, so inline means continuing
-in that session. Threading an `inline` option through `AiRunner` would still start a subprocess and
-would therefore be a false implementation. On a headless surface (`spur agent run` / workflow
-`agent.run`) explicit `inline` is **rejected** (ADR-047 G5 amendment) with the stable special error —
-headless surfaces cannot host a session: `--agent inline requires a host session: this surface is
-headless and never dispatches inline runs (no fallback to agent.default). Use 'auto', a role, or an
-executor name.` (exit 2 at the CLI; the exported `AGENT_INLINE_HEADLESS_MESSAGE` in
-`agent-service`). No further action is taken — no dispatch, no `agent.default` fallback.
+The explicit-rejection carve-out above was superseded by ADR-087 (task 0687): a headless surface
+substitutes tier resolution with a warning instead of rejecting — see the substitution blockquote
+above and `resolveAgent` in `packages/app/src/services/agent-service.ts`.
 
 ### Objective triggers override the answer
 
@@ -81,9 +74,8 @@ cannot satisfy, so it wins regardless:
 | **Workspace or credential isolation required** | The work must not share the host workspace or credentials. | `trigger 4: workspace or credential isolation required` |
 
 A trigger selects subprocess when the selector is omitted, `auto`, or a name, and the applied trigger
-must be named in the dispatch or result. Explicit `--agent inline` is the hard host-session carve-out:
-a trigger requirement that cannot be satisfied in-session rejects with the stable special error rather
-than dispatching a subprocess. When the operator selected a non-current executor and no objective trigger
+must be named in the dispatch or result. Inline selections (omitted or explicit — they are now the
+same value, 0687 R1/R2) satisfy trigger requirements in-session where possible. When the operator selected a non-current executor and no objective trigger
 applies, report `operator override` rather than inventing one of the four. The trigger vocabulary and
 evidence standard are owned by
 [dispatch-surface.md](../../parallel-execution/references/dispatch-surface.md). If none can be named
@@ -125,15 +117,15 @@ model stage (task 0508): an eligible `agent.run` stage — pure-slash input, non
 native subagent with shared-worktree read/write/shell capability — dispatches **once** to that
 native subagent and joins before the driver continues; any pre-dispatch eligibility failure falls
 back to one host execution, and a failure after dispatch follows the stage's error policy with no
-automatic host replay. Explicit `--agent inline` is the zero-dispatch carve-out: every model stage
-executes in the invoking host session — no native-subagent leg. Operator
+automatic host replay. Inline resolution (omitted or explicit, 0687 R1/R2) keeps the native-subagent
+leg for eligible stages. Operator
 confirmation actions, `pause: true`, and approve/taste/ask decisions stay host-owned. Each inline
 model stage appends `stage <id> executed inline in session <session-id>` to its run log; a
 subagent-dispatched stage appends `stage <id> executed via subagent <agent-id> (host session
 <session-id>)` instead. `dev-plan` remains a workflow subprocess, as do `dev-run`/`dev-runall` with
 `--agent auto` or a name, parallel batches, and every headless `spur workflow run` / `spur agent
 run`. `dev-run --mode implement` continues to run its single competency in-session under omitted
-`--agent` or explicit `--agent inline` (zero-dispatch).
+`--agent` or explicit `--agent inline` (identical values, 0687 R1).
 
 ### Executor precedence chain (R7)
 
@@ -150,11 +142,11 @@ resolved in this order; first match wins:
 
 `--agent auto` tier-resolves an executor (stage `model_policy` → `agent.default` → tier priority)
 **before** merging, so it enters the chain at step 1 already resolved to a concrete name.
-On a headless workflow surface, explicit `--agent inline` is rejected with the stable special error
-— the surface cannot host a session. Interactive task wrappers consume omitted `--agent` (0508
-eligibility) and explicit `inline` (zero-dispatch carve-out) before this chain and use the host
-driver. Omitting the flag on a headless surface forwards nothing, so the spawned step resolves to
-`agent.default` (step 2) or the YAML literal (step 3).
+On a headless workflow surface, explicit `--agent inline` substitutes tier resolution with a warning
+(0687 R3) instead of rejecting — it resolves exactly like an omitted flag. Interactive task wrappers
+consume both inline resolutions identically (0508 eligibility as generalized by 0687 R2) before this
+chain and use the host driver. Omitting the flag on a headless surface forwards nothing, so the
+spawned step resolves to `agent.default` (step 2) or the YAML literal (step 3).
 
 ### Implement-only executor override (R6)
 

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

@@ -74,7 +74,7 @@ each would be scope creep for one-liner procedures.
 | 6   | plan       | `dev-plan`          | `Skill()`         | `sp:spur-dev` (`plan`)                                                             | `"<description>" [--feature <id>] [--parent <feature-id>] [--agent <inline\|auto\|name>] [--skip-design] [--auto] [--approve-taste]`                                                                   |
 | 7   | docs       | _(no thin wrapper)_ | `Skill()`         | `sp:doc-evolve`                                                                    | `"<change description>"`                                                                                                                                                                               |
 | 8   | changelog  | `dev-changelog`     | `inline`          | git log + conventional-commit grouping                                             | `[--since <ref>] [--until <ref>] [--version <ver>]`                                                                                                                                                    |
-| 9   | gitmsg     | `dev-gitmsg`        | `inline`          | per-file diff summary → group → conventional commit                                | `[--commit] [--squash] [--scope <path>]`                                                                                                                                                               |
+| 9   | gitmsg     | `dev-gitmsg`        | `inline`          | bounded diff capture → concern grouping → conventional commit                      | `[--commit] [--squash] [--all] [--scope <path>]`                                                                                                                            |
 | 10  | fixall     | `dev-fixall`        | `inline`          | lint + test fix loop                                                               | `[<validation-command>] [--max-retry <n>] [--scope <path>] [--gate-log <path>] [--findings <anchors>]`                                                                                                 |
 | 11  | handover   | `dev-handover`      | `inline`          | structured doc generation                                                          | `"<blocker description>"`                                                                                                                                                                              |
 | 12  | brainstorm | `dev-brainstorm`    | `Skill()`         | `sp:brainstorm` (`dev-brainstorm`)                                                 | `<topic> [--depth <basic\|detailed\|comprehensive>] [--options <n>] [--agent <inline\|auto\|name>] [--skip-discovery] [--wayfind] [--task [<feature-id>]] [--feature [<parent-id>]] [--next]`          |
@@ -140,12 +140,12 @@ must not be changed without updating the backing skill.
 ### 4. run
 
 - **Purpose:** Run a task through the execution pipeline (full) or execute a single pipeline step (implement).
-- **Inputs:** `<wbs>` (required). `--mode <full|implement>` selects the execution mode. `implement` invokes `sp:code-implementation` inline by default. Interactive `full` with omitted `--agent` or explicit `--agent inline` reads `task-pipeline.yaml` and drives its actions/guards in the host session — host-controlled and non-subprocess; **omitted** `--agent` keeps 0508 eligibility (eligible `agent.run` stages dispatch once to a native subagent, host fallback), while explicit `--agent inline` is the zero-dispatch carve-out (every stage executes in the invoking session). `--agent auto`, a name, or headless invocation launches the workflow subprocess. `--agent <inline|auto|name>` selects the execution surface (see [SSOT](cross-cutting.md#inline-default-execution-surface)). `--auto` skips the HITL approve gate / confirmations and propagates down the `--next` chain. `--next` controls chaining only and never changes the mode; a pipeline implement stage must invoke `/sp:dev-run <wbs> --mode implement`. On implement success with `--next`, transition `todo → wip → testing` through the FSM (guards honored — no `--no-lifecycle`) + chain to `/sp:dev-verify <wbs> --auto --next`. On a guard failure, stop as review-pending. **Partial-deliverable rule:** if the task ships only part of its requirements (e.g. an R1/R2 split with the rest in a follow-up task), the `## Solution` section must state that explicitly and the verify verdict will record the scope. `--worktree [<name>]` runs the full pipeline inside an isolated git worktree (create or reuse; FF-merge on success, retain on failure) — the batch lifecycle in [execution-batch.md § Worktree isolation](execution-batch.md#worktree-isolation---worktree-name) applied to a batch of one; rejected with `--mode implement`. `--wrap` hands off to `/sp:dev-wrap <wbs>` after the main step; the `--agent` selector is preserved into that handoff when supplied (omission remains omission), and the wrap hop reports its own trigger-3 subprocess override per the wrap contract.
+- **Inputs:** `<wbs>` (required). `--mode <full|implement>` selects the execution mode. `implement` invokes `sp:code-implementation` inline by default. Interactive `full` resolves the selector uniformly (task 0687): omit ≡ explicit `--agent inline`; full mode reads `task-pipeline.yaml` and drives its actions/guards in the host session — host-controlled and non-subprocess, with 0508 eligibility applying to the resolved-inline selector (eligible `agent.run` stages dispatch once to a native subagent, host fallback)). `--agent auto`, a name, or headless invocation launches the workflow subprocess. `--agent <inline|auto|name>` selects the execution surface (see [SSOT](cross-cutting.md#inline-default-execution-surface)). `--auto` skips the HITL approve gate / confirmations and propagates down the `--next` chain. `--next` controls chaining only and never changes the mode; a pipeline implement stage must invoke `/sp:dev-run <wbs> --mode implement`. On implement success with `--next`, transition `todo → wip → testing` through the FSM (guards honored — no `--no-lifecycle`) + chain to `/sp:dev-verify <wbs> --auto --next`. On a guard failure, stop as review-pending. **Partial-deliverable rule:** if the task ships only part of its requirements (e.g. an R1/R2 split with the rest in a follow-up task), the `## Solution` section must state that explicitly and the verify verdict will record the scope. `--worktree [<name>]` runs the full pipeline inside an isolated git worktree (create or reuse; FF-merge on success, retain on failure) — the batch lifecycle in [execution-batch.md § Worktree isolation](execution-batch.md#worktree-isolation---worktree-name) applied to a batch of one; rejected with `--mode implement`. `--wrap` hands off to `/sp:dev-wrap <wbs>` after the main step; the `--agent` selector is preserved into that handoff when supplied (omission remains omission), and the wrap hop reports its own trigger-3 subprocess override per the wrap contract.
 - **Backing:** `sp:spur-dev` skill — `run` operation for the full pipeline (the spine drives it); `sp:code-implementation` competency skill for the implement step (the spine dispatches to it).
 - **Modes:**
   - **`full`** (default): Drive the full pipeline — precheck → implement → test → review → approve(HITL) → verify → record → done. Interactive omit/inline uses [inline-pipeline-driver.md](inline-pipeline-driver.md) (host-controlled; eligible stages may use a native subagent); explicit/headless executor selection invokes `spur workflow run task-pipeline.yaml --vars '{"wbs":"<wbs>"}'` (with `profile: auto` when `--auto`). Both monitor/surface HITL and preserve the YAML gates. `--next` never changes this mode.
   - **`implement`** (explicit `--mode implement` only): Execute only the implement step. Read the task's `## Requirements` / `## Design` / `## Plan`, write the code that satisfies them, author the `## Solution` change-map section (file:line + what/why per changed file) via `spur task update <wbs> --section Solution --from-file`. This is the implement step the pipeline calls — it is NOT the pipeline driver. With `--next`: on success, transition `todo → wip → testing` through the FSM (guards honored — no `--no-lifecycle`) + chain to `/sp:dev-verify <wbs> --auto --next`; on a guard failure, stop as review-pending. **Partial-deliverable rule:** if the task ships only part of its requirements (e.g. an R1/R2 split with the rest in a follow-up task), the `## Solution` and `## Review` sections MUST carry a `⚠️ PARTIAL` marker naming the deferred part and the follow-up WBS — see `plugins/sp/commands/dev-run.md` → "Section ownership".
-- **Delegation:** `Skill(skill="sp:spur-dev", args="run-inline $ARGUMENTS")` for interactive full omit/inline (explicit `inline` = zero-dispatch carve-out); `Skill(skill="sp:spur-dev", args="run $ARGUMENTS")` for explicit/headless full mode; `Skill(skill="sp:code-implementation", args="$ARGUMENTS")` for implement mode.
+- **Delegation:** `Skill(skill="sp:spur-dev", args="run-inline $ARGUMENTS")` for interactive full omit/inline (resolved-inline semantics, task 0687); `Skill(skill="sp:spur-dev", args="run $ARGUMENTS")` for explicit/headless full mode; `Skill(skill="sp:code-implementation", args="$ARGUMENTS")` for implement mode.
 
 ### 5. refine
 
@@ -252,7 +252,7 @@ must not be changed without updating the backing skill.
 ### 6. plan
 
 - **Purpose:** Plan a feature from a description — intake → feature create → AC generation → feature check gate → decomposition → batch-create (with **Design by default**).
-- **Inputs:** `"<description>"` (required). `--feature <id>` links to an existing feature. `--parent <feature-id>` nests under a parent. The planning pipeline's `agent.run` stages always dispatch a subprocess; `--agent <inline|auto|name>` selector accepted — explicit `inline` is rejected on this headless surface with the stable special error (see [SSOT](cross-cutting.md#inline-default-execution-surface)). **Design package flags (unified with `/sp:dev-idea`):**
+- **Inputs:** `"<description>"` (required). `--feature <id>` links to an existing feature. `--parent <feature-id>` nests under a parent. The planning pipeline's `agent.run` stages always dispatch a subprocess; `--agent <inline|auto|name>` selector accepted — `inline` substitutes tier resolution with a warning on this headless surface (task 0687) (see [SSOT](cross-cutting.md#inline-default-execution-surface)). **Design package flags (unified with `/sp:dev-idea`):**
   - **Default:** author task `design` on every batch item + feature satellite when the seam heuristic fires (**ties lean design**). There is **no** `--design` force flag.
   - `--skip-design` — skip feature satellite **and** omit task `design` fields (scaffold only; refine fills later). Sole design opt-out.
   - `--approve-taste` — with `--auto`, pre-clear design-approval taste pause when that gate is used (`design_approved=true`). Alias: `--design-approved`.
@@ -300,7 +300,7 @@ must not be changed without updating the backing skill.
 ### 14. wrap
 
 - **Purpose:** Wrap up a single completed task — capture learnings, record metrics, sync docs, and optionally advance the feature / clean up the branch.
-- **Inputs:** `<wbs>` (required, positional). `--agent <inline|auto|name>` names the wrap's model-bearing executor (default: `agent.default`); wrap is workflow-backed, so omitted `--agent` resolves to `agent.default` under objective trigger 3 (durable auditable run record required) while explicit `--agent inline` is rejected with the stable special error (headless workflow surface), `auto` tier-resolves an executor, and a name pins that executor into `vars.agent` (see [SSOT](cross-cutting.md#inline-default-execution-surface)). `--auto` skips objective confirmations (the branch-cleanup HITL gate still pauses — irreversible). `--merge` triggers branch cleanup (irreversible HITL gate).
+- **Inputs:** `<wbs>` (required, positional). `--agent <inline|auto|name>` names the wrap's model-bearing executor (default: `inline`, resolving identically when omitted; task 0687); wrap is workflow-backed (headless), so omit ≡ explicit `inline` (task 0687): tier substitution under objective trigger 3 (durable auditable run record required) plus one warning naming the substituted executor. `auto` tier-resolves an executor, and a name pins that executor into `vars.agent` (see [SSOT](cross-cutting.md#inline-default-execution-surface)). `--auto` skips objective confirmations (the branch-cleanup HITL gate still pauses — irreversible). `--merge` triggers branch cleanup (irreversible HITL gate).
 - **Backing:** `spur workflow run wrapup-pipeline.yaml` — direct workflow invocation (no backing skill; the pipeline IS the procedure).
 - **Behavior:** Resolves the executor (`agent.default` for omit/`inline`, tier-resolved for `auto`, unchanged for a name), emits a pre-dispatch notice naming the subprocess override — `execution surface: subprocess`, `reason: trigger 3 — durable auditable run record required`, `requested agent: <selector>`, `executor: <resolved>` — then builds `--vars '{"tasks":"[\"<wbs>\"]","agent":"<resolved>","profile":"interactive|auto","merge":"true|false"}'` and invokes the wrapup pipeline. The pipeline runs: task-resolve → doc-sync → learning-capture → metrics-record → (feature-transition) → (branch-cleanup) → done. Task statuses are NOT mutated. Branch cleanup is an irreversible HITL gate that always pauses, even under `--auto`.
 - **Vars string typing:** `tasks` is a JSON-encoded **string**, not a JSON array — `spur workflow run --vars` accepts only string values (`--vars values must be strings`); the pipeline's guards parse the string with `jq length`. `jq -nc` guarantees the shape:
@@ -316,9 +316,9 @@ must not be changed without updating the backing skill.
 ### 15. wrapall
 
 - **Purpose:** Wrap up a batch of completed tasks — capture learnings, record metrics, sync docs, advance a feature through legal lifecycle edges, and optionally clean up branches.
-- **Inputs:** `--since <iso-date>` filters done tasks by frontmatter `updated_at >= date` (v1 approximation). `--feature <id>` selects all tasks under a feature AND advances the feature through legal lifecycle edges (`backlog → active → verifying → done`, guards honored). `--status <s>` (default: `done`) filters by task status. `--agent <inline|auto|name>` names the wrap's model-bearing executor (default: `agent.default`); wrap is workflow-backed, so omitted `--agent` resolves to `agent.default` under objective trigger 3 (durable auditable run record required) while explicit `--agent inline` is rejected with the stable special error (headless workflow surface), `auto` tier-resolves an executor, and a name pins that executor into `vars.agent` (see [SSOT](cross-cutting.md#inline-default-execution-surface)). `--auto` skips objective confirmations. `--merge` triggers branch cleanup (irreversible HITL gate).
+- **Inputs:** `--since <iso-date>` filters done tasks by frontmatter `updated_at >= date` (v1 approximation). `--feature <id>` selects all tasks under a feature AND advances the feature through legal lifecycle edges (`backlog → active → verifying → done`, guards honored). `--status <s>` (default: `done`) filters by task status. `--agent <inline|auto|name>` names the wrap's model-bearing executor (default: `inline`, resolving identically when omitted; task 0687); wrap is workflow-backed (headless), so omit ≡ explicit `inline` (task 0687): tier substitution under objective trigger 3 (durable auditable run record required) plus one warning naming the substituted executor. `auto` tier-resolves an executor, and a name pins that executor into `vars.agent` (see [SSOT](cross-cutting.md#inline-default-execution-surface)). `--auto` skips objective confirmations. `--merge` triggers branch cleanup (irreversible HITL gate).
 - **Backing:** `spur workflow run wrapup-pipeline.yaml` — direct workflow invocation.
-- **Behavior:** Resolves the task list via `spur task list --json` (filtered by `--feature`, `--since`, `--status`), resolves the executor (`agent.default` for omitted `--agent`, tier-resolved for `auto`, unchanged for a name; explicit `--agent inline` is rejected with the stable special error), emits a pre-dispatch notice naming the subprocess override — `execution surface: subprocess`, `reason: trigger 3 — durable auditable run record required`, `requested agent: <selector>`, `executor: <resolved>` — then builds `--vars '{"tasks":"[...]","feature":"<id>","agent":"<resolved>","profile":"interactive|auto","merge":"true|false"}'` and invokes the wrapup pipeline. The pipeline runs the same states as `wrap` but with the full task list and optional feature transition. Task statuses are NOT mutated. Feature transitions go through `spur feature update` so lifecycle guards apply. Branch cleanup is an irreversible HITL gate.
+- **Behavior:** Resolves the task list via `spur task list --json` (filtered by `--feature`, `--since`, `--status`), resolves the executor (omission and explicit `--agent inline` tier-substitute identically with a warning per task 0687, `auto` tier-resolves, a name pins), emits a pre-dispatch notice naming the subprocess override — `execution surface: subprocess`, `reason: trigger 3 — durable auditable run record required`, `requested agent: <selector>`, `executor: <resolved>` — then builds `--vars '{"tasks":"[...]","feature":"<id>","agent":"<resolved>","profile":"interactive|auto","merge":"true|false"}'` and invokes the wrapup pipeline. The pipeline runs the same states as `wrap` but with the full task list and optional feature transition. Task statuses are NOT mutated. Feature transitions go through `spur feature update` so lifecycle guards apply. Branch cleanup is an irreversible HITL gate.
 - **Vars string typing:** `tasks` is a JSON-encoded **string**, not a JSON array — `--vars` values must be strings (the CLI rejects raw arrays); `jq -nc` passes the array text through as a string value:
 
   ```bash
@@ -378,14 +378,43 @@ is the procedure. The backing is a combination of git CLI, `spur` CLI, and agent
 
 ### 9. gitmsg
 
-- **Purpose:** Generate conventional commit message(s) from staged changes via per-file summarization → concern grouping → one message per group.
-- **Inputs:** `--scope <path>` (default: all staged changes) — limits diff analysis to a path. `--commit` — execute the commit (off by default; refuses on a multi-group staging unless `--squash`). `--squash` — collapse all concerns into one combined message and let `--commit` proceed on a mixed staging.
-- **Backing:** `inline` — per-file diff summary + concern grouping + conventional commit formatting.
+- **Purpose:** Generate conventional commit message(s) for the current change set — one bounded diff capture → concern grouping → one message per concern; optionally commit.
+- **Inputs:** `--scope <path>` (default: the whole change set) — path filter; an explicit `--scope` always wins over change-set auto-discovery. `--all` (default: off) — widen the change set past the index to every change in the tree: unstaged **and untracked** files. Omitted, the change set is the index only, which keeps pre-commit semantics stable. `--commit` (default: off) — commit the change set, one commit per concern. `--squash` (default: off) — collapse every concern into one message and one commit; implies `--commit`.
+- **Backing:** `inline` — bounded diff capture + concern grouping + conventional commit formatting.
 - **Behavior:**
-  1. Run `git diff --cached --stat` (add `-- <path>` when `--scope` is given) for the outline. If the diff is empty, report "no staged changes" and stop.
-  2. Capture the full diff to a temp file (`TEMP_FILE="/tmp/gitdiff_$(date +%s)"; git diff --cached > "$TEMP_FILE" 2>&1`) so analysis reads from disk, not a giant inline blob.
-  3. Read `$TEMP_FILE` and write **one sentence per changed file** — what changed and why, not a line count.
-  4. **Group the per-file sentences by concern.** For each group derive its commit type, scope, and message:
+
+  1. **Gather once — a single shell round trip.** No temp file, no second read, no follow-up `git` call for context:
+
+     ```bash
+     # default:  RANGE=--cached        (the index)
+     # --all:    RANGE=HEAD            (plus untracked, listed below)
+     git rev-parse --abbrev-ref HEAD --git-dir --git-common-dir
+     git diff $RANGE --stat $PATHSPEC
+     git diff $RANGE --name-status $PATHSPEC
+     git diff $RANGE -U0 $PATHSPEC ':(exclude)*.lock' ':(exclude)*lock.json' ':(exclude)*.lockb' | head -c 60000
+     # --all only:
+     git ls-files --others --exclude-standard $PATHSPEC
+     ```
+
+     `$PATHSPEC` is `-- <path>` when `--scope` is given, empty otherwise.
+
+     **Empty index, no `--all`** — the dead-end this command used to hand back. Reading is
+     not a mutation, so the two cases split there:
+     - **No committing flag** → re-gather once with `--all` semantics and say so
+       (`index empty — read the whole tree instead`). A message-only run has nothing to lose by
+       looking wider, and the operator gets an answer instead of an errand.
+     - **`--commit` / `--squash`** → stop. Print the worktree counts (`N tracked, M untracked`) and
+       the exact re-run line (`/sp:dev-gitmsg <the same flags> --all`). Committing
+       untracked files is never inferred from an empty index — that is the operator's call, and it
+       is now one paste away rather than a guess.
+
+     Empty under `--all`, or still empty after the widen → report `no changes in <scope>` and stop.
+
+  2. **Stay inside the budget.** `-U0` (no context lines) plus the lockfile exclusions plus the 60 KB cap is the token contract — never re-run the diff with context to "see more", never paste diff hunks into the output. If the cap truncated the diff, say so and derive the message from `--stat` + `--name-status` alone; a large mechanical change rarely needs hunk detail to be typed and scoped correctly.
+
+  3. **Summarize only what shapes the message.** One sentence — what changed and _why_, not a line count — for each file whose change is not obvious from its path and status. Skip the obvious ones (generated files, lockfiles, pure renames, `docs/**` under a `docs` group). Past ~12 interesting files, summarize per directory instead of per file.
+
+  4. **Group by concern**, and for each group derive type, scope, message:
      - Type from the dominant change — `feat` (new functionality) · `fix` (bug fix) · `refactor` (restructuring, no behavior change) · `docs` (documentation only) · `chore` (build/config/tooling) · `perf` · `test` · `style`.
      - Scope from the affected module/package (`cli`, `domain`, `server`, `web`, `app`, …); `--scope` overrides.
      - Message:
@@ -393,16 +422,29 @@ is the procedure. The backing is a combination of git CLI, `spur` CLI, and agent
        ```
        <type>(<scope>): <summary>
 
-       <body — optional bullets from the group's per-file sentences>
+       <body — why, only when the why is not obvious>
        ```
 
-       Summary: imperative mood, ≤72 chars, lowercase first word, no period. Body: only when the change is non-obvious.
+       Summary: imperative mood, ≤72 chars, lowercase first word, no period. Body explains intent and consequence; it never restates the diff. Behavior changes and pure formatting/refactor churn are **different concerns** — never one group.
+
+  5. **Resolve the message shape without a round trip to the operator.** `--squash` → one combined
+     message (dominant type/scope, one body bullet per group). Otherwise one message per group, in
+     dependency order (refactor before the feature that uses it); a single group is that same rule
+     with one group.
+
+  6. **Report, then commit if asked.** Print the resolved message(s), a copy-paste `git commit` line per message, and a one-line context header: current branch, and `linked worktree` when `--git-dir` differs from `--git-common-dir` and `git rev-parse --show-superproject-working-tree` is empty (a non-empty result means submodule, not worktree). With neither `--commit` nor `--squash`, stop here — the operator commits.
+
+  7. **Committing (`--commit` / `--squash`).** The two flags name outcomes, not dimensions: `--commit`
+     commits **by concern**, `--squash` commits **everything as one**. `--squash` implies `--commit`,
+     so `--commit --squash` is just `--squash`, never an error.
 
-  5. **Resolve groups:** one group → emit its message; multiple groups (default) → emit one message per group **plus a split recommendation** (stage per concern, re-run); `--squash` → collapse to one combined message (dominant type/scope, per-file bullets).
-  6. Print the resolved message + a copy-paste `git commit -m` line. With `--commit`: execute it for a single group or under `--squash`; on a multi-group staging without `--squash`, **do not commit** — print the split guidance instead (one `git commit` can't honor per-group messages).
-  7. `rm "$TEMP_FILE"` once done — no `/tmp` diff residue (the F5 cleanup discipline).
+     First scan the captured diff's added lines for credentials (`password`, `secret`, `api[_-]?key`, `token`, `BEGIN [A-Z ]*PRIVATE KEY`, long base64-looking literals). On a hit: print the offending `file:line`, commit nothing, stop. Otherwise:
+     - `--all` → `git add -A $PATHSPEC` first (this is what stages the untracked files).
+     - `--squash`, or `--commit` on a single group → `git commit -m "$MESSAGE"`.
+     - `--commit` on multiple groups → **commit each group in sequence**: record the full staged file list once, then per group `git reset -q -- <all staged paths>` → `git add -- <that group's paths>` → `git commit -m "<that group's message>"`. This is the split; it needs no re-run and no re-staging by the operator.
+     - **Partial-staging guard:** if any path appears in _both_ `git diff --cached --name-only` and `git diff --name-only` (a `git add -p` staging), the sequence above would silently widen those commits to the whole file. Do not split — report the affected paths and commit nothing unless `--squash` was given.
 
-- **Invariants:** Without `--commit`, never runs `git commit` — message only, the operator commits. With `--commit`, only commits when the staging is a single concern OR `--squash` was given — a mixed staging without `--squash` is reported, never silently squashed. Never leave the temp diff file behind.
+- **Invariants:** With neither `--commit` nor `--squash`, never runs `git commit` — message only. Neither flag commits across a credential hit, and `--commit` never splits across a partial staging. Without `--all` the change set is the index, so plain `/sp:dev-gitmsg` keeps pre-commit semantics; only `--all` reaches unstaged and untracked files, and only a committing run (`--commit` / `--squash`) stages them. The empty-index widen is read-only and always announced — a committing run never widens its own scope. An explicit `--scope <path>` always bounds the change set, with or without `--all`. One diff capture per run, bounded and context-free — never a second, wider read.
 
 ### 10. fixall
 

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

@@ -147,7 +147,7 @@ On the subprocess path, when `--agent <value>` is set (passed through from the t
 `--vars '{"wbs":"<wbs>","agent":"<value>","implementAgent":"<value>"}'`. The pipeline YAML reads
 `${vars.agent}` for review/verify/test-fix and `${vars.implementAgent}` for implement — setting
 both keys ensures the pinned executor reaches every hop. The full value-semantics contract (one
-rule, value table, objective triggers, and headless `inline` rejection (stable special error) per the ADR-047 G5 amendment)
+rule, value table, objective triggers, and headless `inline` substitution (tier resolution + one warning) per ADR-087)
 lives in [cross-cutting.md](cross-cutting.md#inline-default-execution-surface) — the SSOT.
 This file documents only the **workflow-pipeline mechanics**: how the selector reaches `agent.run`
 steps. Precedence chain: `--agent` / explicit `--vars` → `agent.default` → YAML literal (see SSOT