@gobing-ai/spur 0.3.44 → 0.3.46

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
     },
     "plugins": [
         {
-            "version": "0.3.44",
+            "version": "0.3.46",
             "name": "sp",
             "source": "./plugins/sp",
             "description": "Spur - my harness toolkits"

package/config/rules/README.md

@@ -15,14 +15,17 @@ install or to ts-libs.
 | `structure` | `structure/` | File layout, protected files, no focused/skipped tests |
 | `quality` | `quality/` | Post-test gates (coverage) |
 | `surface` | `surface/` | CLI surface consistency (registerXxxCommand wiring, --json serialization) |
+| `migration` | `migration/` | Transitional helpers for the regex → `rg` evaluator move (`rg-dialect`) |
+| `ui` | `ui/` | Web UI seam boundaries (import seam, daisyUI class leak) |
 
 ## Presets
 
 | Preset | When | Extends |
 |---|---|---|
-| `recommended-pre-check` | Before tests | `typescript`, `structure`, `boundary`, `surface` |
+| `recommended-pre-check` | Before tests | `typescript`, `structure`, `boundary`, `surface`, `ui`, `strict` |
 | `recommended-post-check` | After tests | `quality` |
-| `strict-check` | Opt-in | `strict` |
+| `strict-check` | Opt-in single-category cherry-pick (strict only) | `strict` |
+| `rg-migration` | On-demand during the regex → `rg` evaluator migration | `migration` |
 
 ## Relationship to ts-libs
 
@@ -32,9 +35,14 @@ ts-libs/.spur/rules/...` header documenting what was re-scoped, omitted, or
 tuned for Spur's app-repo layout. After absorption, ts-libs and spur-new
 maintain their rulesets independently.
 
+## Transitional helpers
+
+- `migration/rg-dialect` (category `migration/`) and the `rg-migration` preset
+  are **shipped and live**: run `spur rule run --preset rg-migration` on demand
+  during the regex → `rg` evaluator migration. They are intentionally excluded
+  from the standing pre/post-check gates (transitional, not a permanent gate).
+
 ## Not absorbed (Spur-irrelevant)
 
 - `typescript/esm-build-conventions` — governs ts-libs' library publish/dist
   flow. Spur apps don't publish libraries this way.
-- `migration/rg-dialect` — one-time grep→rg migration helper.
-- `migration/rg-migration` — one-time grep→rg migration helper.

package/config/rules/recommended-pre-check.yaml

@@ -1,10 +1,10 @@
 $schema: "@gobing-ai/spur/schemas/preset.schema.json"
-# Recommended pre-check preset — portable rule categories from global install.
+# Recommended pre-check preset — portable rule categories bundled with the catalog.
 # Use with: spur rule run --preset recommended-pre-check
 #
-# Runs BEFORE tests (test-pre-check). TypeScript quality, structural, DB
-# boundary, CLI surface consistency, and UI seam-boundary rules. TSDoc exports
-# run in post-check alongside coverage-gate.
+# Runs BEFORE tests (test-pre-check). Extends six categories: typescript,
+# structure, boundary, surface, ui, and strict (ui since bc267cc8, strict since
+# 79186391). TSDoc exports run in post-check alongside coverage-gate.
 name: recommended-pre-check
 extends:
   - typescript

package/config/rules/strict-check.yaml

@@ -1,7 +1,9 @@
 $schema: "@gobing-ai/spur/schemas/preset.schema.json"
-# Strict-check preset — opt-in hygiene rules absorbed from ts-libs but kept OUT
-# of the default recommended-pre-check gate (they need project-specific tuning
-# or are redundant with engine-level validation). Run explicitly:
+# Strict-check preset — explicit single-category cherry-pick of the `strict/`
+# category only. The same category is already included in recommended-pre-check
+# (extends: typescript, structure, boundary, surface, ui, strict) since 79186391;
+# use this preset when you want ONLY strict rules, not the full pre-check set.
+# Run explicitly:
 #   spur rule run --preset strict-check
 # or cherry-pick a single rule:
 #   spur rule run --rule no-third-party-http-clients
@@ -11,6 +13,7 @@ $schema: "@gobing-ai/spur/schemas/preset.schema.json"
 name: strict-check
 description: >
   Opt-in boundary hygiene: HTTP-client centralization, runtime fs/spawn seams,
-  and local rule-file structural validation. Not part of recommended-pre-check.
+  and local rule-file structural validation. Included in recommended-pre-check;
+  this preset selects the strict/ category alone.
 extends:
   - strict

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.3.44",
+    "version": "0.3.46",
     "description": "Spur CLI — local-first harness for mainstream coding agents: constraint checking, workflow orchestration, agent health, and history analytics. Bun-native; exposes the `spur` command.",
     "keywords": [
         "spur",
@@ -53,14 +53,14 @@
     },
     "devDependencies": {
         "@commander-js/extra-typings": "^14.0.0",
-        "@gobing-ai/ts-db": "^0.4.27",
-        "@gobing-ai/ts-ai-runner": "^0.4.27",
-        "@gobing-ai/ts-dual-workflow-engine": "^0.4.27",
-        "@gobing-ai/ts-infra": "^0.4.27",
-        "@gobing-ai/ts-llm-jsonl-importer": "^0.4.27",
-        "@gobing-ai/ts-rule-engine": "^0.4.27",
-        "@gobing-ai/ts-runtime": "^0.4.27",
-        "@gobing-ai/ts-utils": "^0.4.27",
+        "@gobing-ai/ts-db": "^0.4.31",
+        "@gobing-ai/ts-ai-runner": "^0.4.31",
+        "@gobing-ai/ts-dual-workflow-engine": "^0.4.31",
+        "@gobing-ai/ts-infra": "^0.4.31",
+        "@gobing-ai/ts-llm-jsonl-importer": "^0.4.31",
+        "@gobing-ai/ts-rule-engine": "^0.4.31",
+        "@gobing-ai/ts-runtime": "^0.4.31",
+        "@gobing-ai/ts-utils": "^0.4.31",
         "@types/bun": "1.3.14",
         "@types/figlet": "^1.7.0",
         "@types/node-notifier": "8.0.5",

package/plugins/sp/commands/dev-find-next.md

@@ -1,6 +1,6 @@
 ---
 description: "Prompt-first feature frontier prioritizer — answers 'which feature should we work on now?' with a ranked, evidence-carrying frontier, and emits rank-distorting tree defects as proposals /sp:dev-featurechange consumes. Triggers: find next, which feature, feature ranking, frontier priority, what should I work on."
-argument-hint: "[--task [<feature-id>]] [--agent <inline|auto|name>] [--json]"
+argument-hint: "[--task [<feature-id>]] [--agent <inline|auto|name>] [--auto] [--json]"
 allowed-tools: ["Bash", "Read", "Write", "Grep", "Glob", "Skill"]
 ---
 
@@ -20,6 +20,7 @@ Answers *"which X"* — the question `/sp:dev-next` deliberately does not (next-
 | --- | --- | --- |
 | `--task` `[<feature-id>]` | After the report, confirm one target and dispatch the planning half to produce implement-ready tasks. | omitted |
 | `--agent` `<inline\|auto\|name>` | Who runs the model-bearing analysis. | inline |
+| `--auto` | Skip the `--task` confirm (accept the offered target) and forward into dispatched children. | off |
 | `--json` | Emit the ranked frontier, gated list, and proposals as a JSON envelope. | off |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
@@ -30,23 +31,30 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
 /sp:dev-find-next
 /sp:dev-find-next --json
 /sp:dev-find-next --task
+/sp:dev-find-next --task --auto
 /sp:dev-find-next --task H1 --auto
 ```
 
 **`--task` — confirm, then dispatch.** The command offers the rank-1 candidate (or the id you pass),
-takes an **explicit** confirmation, then routes on the tier the ranking already assigned: a **T3**
-feature with valid AC and no tasks goes to `/sp:dev-plan --feature <id>` and then
-`/sp:dev-refineall --feature <id> --auto --depth ready`; a **T1** feature (open tasks already exist)
-goes to refineall only, never a second decomposition; **T2** (blocked), **T4** (stale-done), and T3
-with invalid AC stop with their reason. The command creates no tasks itself — decomposition and its
-schema gate belong to `/sp:dev-plan`. The confirmation pauses **regardless of `--auto`**; `--auto`
-is forwarded only to the dispatched children. Declining writes nothing.
+then routes on the tier the ranking already assigned: a **T3** feature with valid AC and no tasks
+goes to `/sp:dev-plan --feature <id>` and then `/sp:dev-refineall --feature <id> --auto --depth ready`;
+a **T1** feature (open tasks already exist) goes to refineall only, never a second decomposition;
+**T2** (blocked), **T4** (stale-done), and T3 with invalid AC stop with their reason. The command
+creates no tasks itself — decomposition and its schema gate belong to `/sp:dev-plan`.
+
+**Confirm under `--auto`.** Without `--auto`, confirmation is interactive (accept the offer, name
+another candidate, or decline). With `--auto`, the offered target is accepted automatically —
+rank-1 for bare `--task`, or the explicit `--task <feature-id>` — and dispatch proceeds without a
+HITL pause. Passing `--auto` is operator pre-consent to take the ranking's recommendation; it is
+not a license to invent a different target or to bypass T2/T4 refuse / invalid-AC stop. `--auto`
+is also forwarded to the dispatched children. Declining (interactive path only) writes nothing.
+Without `--task`, `--auto` is a no-op (the ranking report has no HITL gate).
 
 Without `--task` the command is read-only with respect to the corpus and docs. Under `--task` the
-only mutation is the one the dispatched commands perform on `docs/tasks*/` after you confirm — the
-command still performs no `spur feature move`, no sync apply, and no write under `docs/features/**`.
-Defect proposals conform to the `docs/plans/feature-tree-restructure-map.md` schema and are applied
-only through `/sp:dev-featurechange` (dry-run → confirm → apply).
+only mutation is the one the dispatched commands perform on `docs/tasks*/` after confirm (or
+auto-accept) — the command still performs no `spur feature move`, no sync apply, and no write under
+`docs/features/**`. Defect proposals conform to the `docs/plans/feature-tree-restructure-map.md`
+schema and are applied only through `/sp:dev-featurechange` (dry-run → confirm → apply).
 
 **See also:** skill `sp:next-feature` (SSOT), `sp:next-router` (`/sp:dev-next`),
 `sp:conflict-finding` (the prompt-first template), `sp:spur-cli`.

package/plugins/sp/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "sp",
-    "version": "0.3.44",
+    "version": "0.3.46",
     "description": "Spur — a local-first harness engineering toolkit that wraps mainstream coding agents with constraint checking, workflow orchestration, and history analytics.",
     "extensions": {
         "pi": ["./hooks/pi/guard-extension.ts"]

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

@@ -40,9 +40,9 @@ in this corpus it is 76% one value (0493 measurement).
 **Propose, never apply.** This skill performs no `spur feature move` and writes nothing under
 `docs/features/**`. The only path from a structure proposal to a changed tree is
 `/sp:dev-featurechange` (dry-run → confirm → apply). Ranking runs are read-only; the sole exception is
-`--task`, which after an **explicit operator confirm** dispatches `/sp:dev-plan` and
-`/sp:dev-refineall` — commands that write `docs/tasks*/` through their own gates. This skill still
-creates no tasks itself.
+`--task`, which after an **operator confirm** (interactive, or auto-accepted under `--auto`)
+dispatches `/sp:dev-plan` and `/sp:dev-refineall` — commands that write `docs/tasks*/` through their
+own gates. This skill still creates no tasks itself.
 
 ## When to Use
 
@@ -89,13 +89,16 @@ Run the steps in order. Each step's depth lives in its reference; this file is t
    at the ranking; advancing a chosen feature is `/sp:dev-next`'s job.
 7. **`--task` only — confirm, then dispatch the planning half.** Offer the rank-1 candidate (or the
    id passed as `--task <feature-id>` — which may name a **gated** feature, since T2/T3/T4 are tiers
-   the rubric assigns to the gated list and only T1 comes from the ranked frontier), take an
-   **explicit** operator confirmation, then route on the
-   tier step 4 already assigned: T3 with zero tasks → `/sp:dev-plan --feature <id>` then
-   `/sp:dev-refineall --feature <id> --auto --depth ready`; T1 → refineall only; T3 with invalid AC,
-   T2, and T4 stop with their reason. **This skill creates no tasks itself** — the dispatched
-   commands own decomposition and its schema gate. The confirm pauses regardless of `--auto`. Full
-   contract: [references/handoff-routing.md](references/handoff-routing.md).
+   the rubric assigns to the gated list and only T1 comes from the ranked frontier). **Without
+   `--auto`:** take an explicit operator confirmation (accept the offer, name another candidate, or
+   decline). **With `--auto`:** auto-accept the offered target (rank-1 for bare `--task`, or the
+   explicit id) — the flag is operator pre-consent to take the ranking's recommendation — then
+   proceed without a HITL pause. Route on the tier step 4 already assigned: T3 with zero tasks →
+   `/sp:dev-plan --feature <id>` then `/sp:dev-refineall --feature <id> --auto --depth ready`; T1 →
+   refineall only; T3 with invalid AC, T2, and T4 stop with their reason. **This skill creates no
+   tasks itself** — the dispatched commands own decomposition and its schema gate. Forward `--auto`
+   into the dispatched children. Full contract:
+   [references/handoff-routing.md](references/handoff-routing.md).
 
 ## Anti-patterns — do not do these
 
@@ -105,9 +108,10 @@ Run the steps in order. Each step's depth lives in its reference; this file is t
 - Copying the B3 predicate into this skill. Cite it; read it at runtime.
 - Any `spur feature move`, or writing proposals anywhere `docs/features/**` — featurechange owns apply.
 - Decomposing a feature here, or calling `spur task create` / `spur task batch-create` under `--task`.
-  Dispatch `/sp:dev-plan`; it owns decomposition and the batch-create schema gate. Equally: skipping
-  the `--task` confirm because `--auto` was passed, or decomposing a T1 feature that already has a
-  live task frontier.
+  Dispatch `/sp:dev-plan`; it owns decomposition and the batch-create schema gate. Equally:
+  dispatching under `--auto` without `--task` (there is no confirm to skip), auto-accepting a target
+  other than the offer / named `--task <id>`, or decomposing a T1 feature that already has a live
+  task frontier.
 - Padding the defect list with tidiness findings that move no rank.
 - Re-proposing F31's rejected merges (B∪H, J∪K body-merge) or reading
   `## Applied mapping` as current state — letters are recycled; resolve against live features.

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

@@ -65,15 +65,20 @@ survivors would make its primary case unreachable. Offer the rank-1 ranked candi
 | **T2 — unblock first** | gated on a blocker | **Refuse.** Name the blocker and its owner. Tasks created under a blocked feature cannot run. |
 | **T4 — stale-done** | post-sync status would be `done` | **Refuse.** Route to `/sp:dev-wrapall --feature <id>` or the sync-first block; the work is finished, not startable. |
 
-### The confirmation is unconditional
+### The confirmation — interactive by default, auto-accepted under `--auto`
 
 | Rule | Detail |
 | --- | --- |
-| Default offer | The rank-1 candidate. The operator may confirm it, name another candidate from the report, or decline. |
-| `--task <feature-id>` | An explicit id skips the *default-offer* step. It does **not** skip the confirm. |
-| `--auto` | Forwarded to the dispatched children (`dev-plan --auto`, `dev-refineall --auto`). It **never** answers the confirm — choosing what to invest in is a taste decision (Auto-Decision Principle #5), and `ranking-rubric.md` already states the operator overrides the ranking. |
-| No escape | There is no `--yes` / `--force` bypass. No path exists from `--task` to a created task file without an explicit operator decision. |
-| Refusal | Declining ends the run at the report. Nothing is written. |
+| Default offer | The rank-1 candidate. Without `--auto`, the operator may confirm it, name another candidate from the report, or decline. |
+| `--task <feature-id>` | An explicit id becomes the offered target (skips the *default-offer* step). Without `--auto` it still requires confirm; with `--auto` the named id is auto-accepted. |
+| `--auto` | **Two effects:** (1) auto-accept the offered target — rank-1 for bare `--task`, or the explicit `--task <feature-id>` — without a HITL pause; (2) forward into the dispatched children (`dev-plan --auto`, `dev-refineall --auto`). Passing `--auto` is operator **pre-consent** to take the ranking's recommendation (streamline path); it does **not** invent a different target, and it does **not** bypass T2/T4 refuse or invalid-AC stop. Without `--task`, `--auto` is a no-op (ranking-only has no HITL). |
+| Report the accept | When `--auto` accepts, print a one-line note: `auto-accepted target <id> (tier <Tn>) via --auto` so the transcript records the decision. |
+| Refusal | Declining (interactive path only) ends the run at the report. Nothing is written. |
+
+**Why this is not a Principle #5 taste auto-click.** The ranking already produced the recommendation;
+`--auto` only skips the *proceed-with-offer* pause. Overriding the ranking (picking a non-offered
+candidate) still requires the interactive confirm path. Architecture / design-approval taste gates
+inside dispatched children remain governed by their own contracts (`--approve-taste` where applicable).
 
 ### What `--task` does not change
 
@@ -89,4 +94,4 @@ adds one gated path to `docs/tasks*/`, through commands that own their own gates
 | Defect proposals | stdout; optionally appended to `docs/plans/feature-tree-restructure-map.md` |
 | "Sync first" block | top of report when the dry-run proposes frontier changes |
 | Winner handoff | printed `/sp:dev-next <id>` hint — operator runs it |
-| `--task` dispatch | after an explicit confirm: `/sp:dev-plan` and/or `/sp:dev-refineall`, which write `docs/tasks*/` through their own gates |
+| `--task` dispatch | after confirm (interactive) or auto-accept (`--auto`): `/sp:dev-plan` and/or `/sp:dev-refineall`, which write `docs/tasks*/` through their own gates |

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

@@ -19,6 +19,11 @@ status on sync). Rules:
 - Urgency signals premised on raw `status` (sunk-work decay, WIP pressure, staleness) are computed
   only against the post-sync view — 0493 rejected all three as standalone signals; post-sync they
   survive only as tie-break texture (see ranking-rubric.md).
+- The dry run is captured **exactly once per run**; the captured result is the sole source of the
+  post-sync status view for protocol steps 1–4 (gating, roster completion, and signal derivation
+  all read the same in-memory capture). This is a prompt-run capture, not a cache/state file: the
+  run never issues a second `spur feature sync --all --dry-run --json` call, and no other verb
+  reproduces it in this run.
 
 ## §1 — Actionability gate (runtime citation, never restated)
 
@@ -32,11 +37,34 @@ Inputs per candidate feature:
 spur task list --feature <id> --json
 ```
 
-Apply B3 over the feature's tasks. **Zero actionable tasks ⇒ gated, not ranked.** Record the gating
+`task list --feature` is **active-folder-only**: it enumerates tasks in the active task folder
+(`.spur/config.yaml`) and omits linked tasks archived in the other configured folders. Apply B3 over
+that list. **Zero actionable tasks ⇒ gated, not ranked.** Record the gating
 reason verbatim for the report's gated list: `all tasks terminal` / `blocked: <task wbs> — <reason>`
 / `no tasks`. A blocked task with no corpus dependency is an **external** block (approval, trigger) —
 report it as such; it is not satisfiable by ranking other work first.
 
+**Complete the roster before declaring terminal or empty.** If the active view yields no B3
+frontier candidate and the tentative reason is `all tasks terminal` or `no tasks`, the active view
+is not authoritative — a frontier task may be archived outside it. Run the fallback once:
+
+1. Consult the §0 capture (the run's single `spur feature sync --all --dry-run --json` result) for
+   the feature's row as an **anomaly hint** only: it may flag the feature without naming a WBS. The
+   sync reason is never treated as a WBS source — no WBS is ever inferred from sync prose.
+2. Scan the whole corpus for linked tasks:
+   ```bash
+   rg -l '^feature_id: "?<id>"?$' docs/tasks*/
+   ```
+   Corpus ids are `[A-Z][0-9]+`-shaped, so `<id>` is regex-safe as-is; escape metacharacters if a
+   non-conforming id ever appears.
+3. Parse the leading WBS from each matched basename; resolve every corpus-only WBS (not present in
+   the active list) with `spur task show <wbs> --json`.
+4. Union the active-list records with the resolved corpus records, deduplicate by WBS, and reapply
+   runtime B3 to the complete set.
+5. Record the gating reason from the complete roster. If the union exposes a blocked task that the
+   active view omitted, the classification is `blocked: <task wbs> — <reason>` — never `all tasks
+   terminal` — with the blocker text taken from the resolved task body, not from sync prose.
+
 ## §2 — The four surviving signals
 
 0493 measured eight candidate signals over this corpus; exactly four discriminate. Derivation
@@ -44,11 +72,20 @@ commands (per candidate feature `<id>`):
 
 | Signal | Derivation | Notes |
 | --- | --- | --- |
-| **AC coverage** (readiness proxy) | `spur feature show <id> --json` → count `Scenario:` in body; `spur feature check <id> --json` for validity findings | 0 scenarios ⇒ "specify next", not "work next" (routes toward B4/B5 territory; see handoff-routing.md) |
+| **AC coverage** (readiness proxy) | `spur feature show <id> --json` → count `Scenario:` in the frozen response's `.content` (the JSON carries the full body as `.content`); `spur feature check <id> --json` for validity findings | 0 scenarios ⇒ "specify next", not "work next" (routes toward B4/B5 territory; see handoff-routing.md) |
 | **Churn exposure** (urgency proxy — WSJF cost-of-delay, numerator only) | `git rev-list --count --since="<40 days ago>" HEAD -- <dirs the feature's scope touches>` | 40d window is 0493's measured default; tune on dogfood. Scope = the paths named in the feature's Goal/Scope |
 | **Dogfood proximity** (compound leverage) | `rg -c 'plugins/sp | apps/cli | task-pipeline | sp:' docs/features/<id>_*.md` + child task bodies | Degenerate-high in this harness (everything touches itself); discriminates mainly at **zero** — a 0-hit feature is "specify, don't ship" |
 | **Authority pull** (declared intent) | `rg -n '\b<id>\b' docs/02_ROADMAP.md docs/00_ADR.md` | Presence is positive evidence; absence is not negative |
 
+**Freeze each candidate input once.** Per candidate `<id>`, capture at most one
+`spur feature show <id> --json` and at most one `spur feature check <id> --json`; reuse those
+captures wherever the four-signal pass needs feature metadata, body, or AC validity. Count
+`Scenario:` in the frozen show response's `.content` — the body is carried as `.content`, so no
+`.filePath` re-read is required (read the file only when the response does not carry the corpus text
+needed). No signal re-invokes a frozen capture. Churn, dogfood, and authority pull continue using
+their own prescribed `git`/`rg` derivations above — they do not derive from the feature show/check
+captures.
+
 **Degenerate-spread rule.** After deriving a signal across the candidate set, check its spread. One
 dominant value (as `priority` was at 76% P2) ⇒ the signal does not discriminate on this frontier:
 report it as **rejected with its measured spread** for this run, and proceed without it. A rejected

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

@@ -23,6 +23,7 @@ that before using `run` for fan-out dispatch.
 | ---- | ------- | --------- |
 | `run <prompt>` | Execute a prompt or slash command via a coding agent | `--agent <name>` `--model <name>` `--mode <mode>` `--continue` `--cwd <path>` `--drain` `--json` |
 | `loop` | Persistent self-draining inbox loop for a team member (supervisor-managed) | `--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` |
 | `list` | List detected coding agents, or team agent specs with `--specs` | `--specs` `--json` |
 | `doctor [agent]` | Check agent readiness | `--json` |
 | `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` |
@@ -46,7 +47,7 @@ through a coding agent as an external process, producing a persisted run record
 ### Flags
 
 | Flag | Purpose |
-|------|---------|
+| ------ | --------- |
 | `--agent <name>` | Agent name or `auto`. Selects which installed coding agent executes the prompt. |
 | `--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`. |
@@ -96,6 +97,38 @@ under supervision.
 The loop runs until `SIGINT` / `SIGTERM`. Each iteration: check inbox -> if messages, drain each
 into `run` with `--drain` -> else sleep for `--poll` ms.
 
+## `wait` - identity-pinned occupant wait (G4 wave 2)
+
+```bash
+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
+```
+
+`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`.
+
+### Flags
+
+| Flag | Purpose |
+| ------ | --------- |
+| `--run <runId>` | Pin a specific run id (default: the spec's latest run). |
+| `--until <state>` | Lifecycle state to wait for (repeatable OR): `idle` \| `working` \| `invoke-exit` \| `blocked`. Default `idle`. |
+| `--timeout <ms>` | Caller deadline. Undefined = no deadline (stall budget still applies). |
+| `--json` | `{ satisfied, pin }` on success; `{ error: { code, message } }` on failure. |
+
+### Exit codes + error envelope
+
+| Code | Exit | Meaning |
+| ------ | ------ | --------- |
+| `occupant_gone` | 1 | No occupant for the specId, or it disappeared mid-wait. |
+| `run_replaced` | 1 | The pinned run was replaced or its generation bumped. |
+| `wait_stalled` | 1 | Non-working occupant, no progress within `min(timeout, 5000)ms`. |
+| `timeout` | 1 | Caller `--timeout` elapsed (or aborted via SIGINT). |
+| `usage` | 2 | Invalid flags, or `--until blocked` as the sole target (no first-class signal in wave 2). |
+
 ## `list` - detected agents and team specs
 
 ```bash
@@ -132,7 +165,7 @@ agent loop` can self-drain its inbox.
 ### Flags
 
 | Flag | Purpose |
-|------|---------|
+| ------ | --------- |
 | `--type <agent-type>` | Agent spec type (e.g. `claude`, `codex`, `omp`). |
 | `--tags <a,b>` | Comma-separated team identity tags (e.g. `team:alpha,role:worker`). |
 | `--model <name>` | Agent model argument. |

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>` `--json` |
+| `send <body>` | Enqueue a message for an agent | `--to <id>` `--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` |
@@ -33,18 +33,29 @@ invalid usage.
 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
 ```
 
 Enqueues a durable message addressed to `--to <id>`. The recipient drains it on its next `agent run
 --drain` or `agent loop` iteration. `--from` defaults to `operator`.
 
+`--wait` snapshots the recipient occupant **before** enqueue, then waits on that pin in the same CLI
+process (G4 wave 2 / ADR-057). Default `--until invoke-exit`. A later occupant cannot satisfy the
+wait; enqueue is **not** rolled back if the wait later fails.
+
 ### Flags
 
 | Flag | Purpose |
-|------|---------|
+| ------ | --------- |
 | `--to <id>` | **Required.** Recipient agent id. |
 | `--from <id>` | Sender id (default: `operator`). |
-| `--json` | Output machine-readable JSON. |
+| `--wait` | Block until the recipient reaches `--until` (snapshots occupant before send). |
+| `--until <state>` | Wait target: `injected` \| `invoke-exit` (repeatable OR). Default `invoke-exit`. |
+| `--timeout <ms>` | Caller deadline in milliseconds. |
+| `--json` | Output machine-readable JSON (`{ msgId, toId, status, wait: { satisfied } }`). |
+
+`--wait` failures use the same error codes as `agent wait`: `occupant_gone`, `run_replaced`,
+`wait_stalled`, `timeout` (exit 1).
 
 ## `inbox` - list addressed messages
 
@@ -79,7 +90,7 @@ lines.
 ### Flags
 
 | Flag | Purpose |
-|------|---------|
+| ------ | --------- |
 | `--agent <id>` | **Required.** Agent id to watch. |
 | `--interval <ms>` | Poll interval in milliseconds (default: `2000`). Must be a positive integer; exit `2` otherwise. |
 | `--json` | Output one JSON object per new message. |

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

@@ -76,7 +76,22 @@ Once registered, any definition can use `kind: send-email` (in `onEnter`/`onExit
 
 ## Extension loading (trust-gated)
 
-For modules that bundle multiple actions/guards, use `loadWorkflowExtensionsIntoHost`. The trust gate
+A workflow YAML can declare extension modules next to the workflow file itself:
+
+```yaml
+name: ext-flow
+kind: state-machine
+extensions:
+  actions: ["./exts/audit.ts"]   # default-exports { name, actions: [...] }
+  guards:  ["./exts/flag.ts"]    # default-exports { name, guards: [...] }
+```
+
+`spur workflow validate`, `run` (incl. `--dry-run`), and `continue` load YAML-declared extensions
+onto the engine host before any step — the declaration itself is the `allowExtensions` gate (0533/D4).
+Paths are relative to the workflow file; absolute paths and `..` traversal are rejected with no
+import, and a missing or mis-shaped module fails the command before any step.
+
+For library callers, use `loadWorkflowExtensionsIntoHost`. The trust gate
 is **fail-closed**: `allowExtensions` defaults to `false`, and a declared-but-not-allowed extension
 **throws before any import** — never silently dropped.
 
@@ -117,8 +132,8 @@ reach for the library (`@gobing-ai/ts-dual-workflow-engine`) directly when you n
 | ---------- | --- | ------- |
 | Validate / run / list definitions | ✅ | ✅ |
 | Trace run history / continue HITL / cancel / clean orphans | ✅ | ✅ |
-| Custom action/guard runners | ✅ (built-ins only) | ✅ (`registerAction`/`registerGuard`) |
-| Extension modules | — | ✅ (`loadWorkflowExtensionsIntoHost`) |
+| Custom action/guard runners | ✅ (built-ins + YAML extensions, 0533/D4) | ✅ (`registerAction`/`registerGuard`) |
+| Extension modules | ✅ (YAML `extensions.actions`/`extensions.guards`, 0533/D4) | ✅ (`loadWorkflowExtensionsIntoHost`) |
 | DB persistence + programmatic `listRuns()` | (via configured adapter + `trace`) | ✅ (`DbWorkflowPersistenceAdapter`) |
 | Event-bus observability (progress bars, dashboards) | partial (CLI step reporter on sync human runs) | ✅ (`WorkflowEngineEvents` via `WorkflowRunOptions.events`) |
 | OTel traces / structured logs | (emitted) | ✅ (`RunLifecycle`) |

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

@@ -281,6 +281,7 @@ redirecting `agent.run` stages (ADR-047).
   both scopes (lists what would be removed, writes nothing). `--json` returns
   `{ olderThanMinutes, dryRun, cleaned, logs: { retentionDays, dryRun, reclaimed, failures } }` (with
   `--logs`, the reclamation object alone).
+
 ## Behavior
 
 This skill behaves as an **author** (choose mode → write a correct definition → prove it runs) feeding
@@ -302,8 +303,11 @@ the workflow's actions (`shell`, custom runners) do that; this skill builds and
    `.spur/workflows/basic.yaml` and `task-pipeline.yaml` quality-gate hop).
 4. **`env.allow` is an allowlist.** `${env.X}` resolves only if `X` is listed under `env.allow`;
    otherwise it resolves empty. A workflow that "loses" an environment value usually forgot to allow it.
-5. **Extensions are fail-closed.** Custom action/guard *modules* require `allowExtensions: true`; a
-   declared-but-not-allowed extension throws **before any import** — never silently dropped. Inline
+5. **Extensions are fail-closed.** The CLI loads YAML-declared extension modules itself
+   (`extensions.actions` / `extensions.guards`, resolved relative to the workflow file) — the
+   declaration is the gate (0533/D4). A declared-but-missing or mis-shaped module, an absolute
+   path, or `..` traversal throws **before any import** — never silently dropped. Library callers
+   using `loadWorkflowExtensionsIntoHost` must pass `allowExtensions: true` explicitly. Inline
    `host.registerAction`/`registerGuard` need no flag; only the module loader is gated.
 6. **A failed run does not throw.** Action/guard failures come back as `WorkflowRunResult` with
    `status: 'failed'`, preserving the run record. Read the trace; don't expect an exception. (Definition
@@ -341,11 +345,13 @@ the workflow's actions (`shell`, custom runners) do that; this skill builds and
 ## Platform Notes
 
 ### Claude Code
+
 Run `spur workflow` via the Bash tool. During development the CLI entry is a `.ts` file that runs only
 under Bun: `bun run apps/cli/src/index.ts workflow validate <file> --json`. The installed `spur` binary
 works once built.
 
 ### Codex / OpenClaw / OpenCode / Antigravity
+
 Run `spur workflow ...` via the Bash tool; parse `--json` output programmatically. Arguments are passed
 directly on the command line.
 

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

@@ -203,10 +203,11 @@ behavior:
 
 - `dev-brainstorm` `[<feature-id>]` — **creates** one task from the chosen approach, landing at
   `todo` ready for refine. Optional feature id scopes it.
-- `dev-find-next` `[<feature-id>]` — after an **explicit operator confirm**, dispatches the planning
-  half on the ranked winner (`/sp:dev-plan` to decompose, then `/sp:dev-refineall --depth ready` to
-  freeze implement-ready). Creates no task itself; the confirm pauses regardless of `--auto`.
-  Optional feature id names the target instead of offering rank 1.
+- `dev-find-next` `[<feature-id>]` — after confirm, dispatches the planning half on the ranked
+  winner (`/sp:dev-plan` to decompose, then `/sp:dev-refineall --depth ready` to freeze
+  implement-ready). Creates no task itself. Interactive by default; with `--auto`, auto-accepts the
+  offered target (rank-1 or the explicit id) and forwards `--auto` to the children. Optional feature
+  id names the target instead of offering rank 1.
 - `dev-debug` `[<wbs>]` — **attaches** findings to an existing task. Optional WBS names it.
 - `dev-dogfood` (no value) — **records** run outcomes against the task under test.