@juzser/blacksmith 0.2.0 → 0.4.0

package/.claude/agents/auditor.md

@@ -5,6 +5,9 @@ model: sonnet
 effort: high
 tools: Read, Grep, Glob, Bash
 maxTurns: 15
+hooks:
+  Stop:
+    - hooks: [{type: command, command: "[ -f \"$CLAUDE_PROJECT_DIR/.claude/hooks/judge-stop.sh\" ] && \"$CLAUDE_PROJECT_DIR/.claude/hooks/judge-stop.sh\" || exit 0"}]
 ---
 
 # Auditor

package/.claude/agents/grader.md

@@ -5,6 +5,9 @@ model: sonnet
 effort: low
 tools: Read, Grep, Glob, Bash
 maxTurns: 15
+hooks:
+  Stop:
+    - hooks: [{type: command, command: "[ -f \"$CLAUDE_PROJECT_DIR/.claude/hooks/judge-stop.sh\" ] && \"$CLAUDE_PROJECT_DIR/.claude/hooks/judge-stop.sh\" || exit 0"}]
 ---
 
 # Grader
@@ -43,7 +46,9 @@ edit does not save a round-trip, it costs the whole one.
   rubric — nothing broader.
 - Bounce back to the worker with specific, itemized gaps (not vibes).
 - **Max 2 rounds.** After that, pass whatever exists through to the gates —
-  the gates, not the grader, decide final pass/fail.
+  the gates, not the grader, decide final pass/fail. The re-scope path after a
+  round-2 `fail` is `.claude/skills/bs/dispatch.md`'s "Round counting and
+  escalation" — read it there rather than here.
 - Grader never edits code and never talks to the operator.
 - **Never compact your context** (`budgets.yml` `context_window`,
   `narrowing_roles`). You grade evidence rather than build on it; a
@@ -101,10 +106,12 @@ harness counts the tokens; the dispatcher stamps them.
 {"status": "done", "overall": "fail", "round": 2, "artifact_path": "state/results/<task-id>.grader-r2.json"}
 ```
 
-Two rounds is a hard stop, not a suggestion. A `fail` at round 2 goes back to
-the planner for re-scoping; you do not open round 3, and you do not soften the
-verdict to avoid the stop. The schema caps `round` at 2, so a round-3 file
-does not quietly pass the gate — it blocks it as invalid.
+Two rounds is a hard stop, not a suggestion. A `fail` at round 2 is re-scoped
+through dispatch.md's "Round counting and escalation" (plan propose/approve a
+successor task id, then `worktree create --from`); you do not open round 3 on
+this id, and you do not soften the verdict to avoid the stop. The schema caps
+`round` at 2, so a round-3 file does not quietly pass the gate — it blocks it
+as invalid.
 
 ## What the gate does with this file
 

package/.claude/agents/reviewer.md

@@ -5,6 +5,9 @@ model: sonnet
 effort: medium
 tools: Read, Grep, Glob, Bash
 maxTurns: 15
+hooks:
+  Stop:
+    - hooks: [{type: command, command: "[ -f \"$CLAUDE_PROJECT_DIR/.claude/hooks/judge-stop.sh\" ] && \"$CLAUDE_PROJECT_DIR/.claude/hooks/judge-stop.sh\" || exit 0"}]
 ---
 
 # Reviewer

package/.claude/agents/security-reviewer.md

@@ -5,6 +5,9 @@ model: sonnet
 effort: high
 tools: Read, Grep, Glob, Bash
 maxTurns: 15
+hooks:
+  Stop:
+    - hooks: [{type: command, command: "[ -f \"$CLAUDE_PROJECT_DIR/.claude/hooks/judge-stop.sh\" ] && \"$CLAUDE_PROJECT_DIR/.claude/hooks/judge-stop.sh\" || exit 0"}]
 ---
 
 # Security Reviewer

package/.claude/agents/spec-reviewer.md

@@ -5,6 +5,9 @@ model: sonnet
 effort: high
 tools: Read, Grep, Glob, Bash
 maxTurns: 15
+hooks:
+  Stop:
+    - hooks: [{type: command, command: "[ -f \"$CLAUDE_PROJECT_DIR/.claude/hooks/judge-stop.sh\" ] && \"$CLAUDE_PROJECT_DIR/.claude/hooks/judge-stop.sh\" || exit 0"}]
 ---
 
 # Spec Reviewer

package/.claude/agents/verifier.md

@@ -5,6 +5,9 @@ model: opus
 effort: xhigh
 tools: Read, Grep, Glob, Bash
 maxTurns: 15
+hooks:
+  Stop:
+    - hooks: [{type: command, command: "[ -f \"$CLAUDE_PROJECT_DIR/.claude/hooks/judge-stop.sh\" ] && \"$CLAUDE_PROJECT_DIR/.claude/hooks/judge-stop.sh\" || exit 0"}]
 ---
 
 # Verifier

package/.claude/skills/bs/audit.md

@@ -218,10 +218,19 @@ smith audit cut <project-dir> --epic <epic-id> --title "<milestone title>" \
 ```
 
 It stamps the epic id onto every accepted finding, emits `audit-cut`,
-and prints two strings; **it edits no file**. Paste `milestone` into
-`factory/specs/roadmap.md` as the next milestone block — it already
-carries `- project: <basename>` and `- kind: product` — and write `spec`
-to `factory/specs/active/<epic-id>/epic-spec.md`. `audit.nothing-accepted`
+and prints two strings; **it edits no file**. Both belong to the audited
+project, so both are written under the **work root** of step 1 and never
+into the factory's own checkout: paste `milestone` into
+`<work-root>/factory/specs/roadmap.md` as the next milestone block — it
+already carries `- project: <basename>` and `- kind: product` — and write
+`spec` to `<work-root>/factory/specs/active/<epic-id>/epic-spec.md`. If
+that roadmap does not exist yet, create it: the parser
+(`factory/orchestrator/src/roadmap.ts`) asks only that milestones be `##`
+blocks, so a title line above the first one is a whole file. A milestone
+for someone else's project is a declaration *they* made, and a factory
+that keeps those in its own repository ships them to everyone who clones
+it — which is also what step 7's `.gitignore` question is about, since
+the work root is where these two files now live. `audit.nothing-accepted`
 means step 7 accepted nothing: there is no epic to cut, and closing is
 the right next move. One audit cuts one epic; findings accepted after a
 cut belong to the next audit's cut, not to a second cut from this one.
@@ -245,8 +254,15 @@ is already gone closes with `verified: false` and no refusal.
 The epic is now an ordinary roadmap milestone: run `/bs plan` on it
 ([`plan.md`](plan.md)), then `/bs run`. When that run reaches its epic-close
 step, it runs
-`smith audit resolve <project-dir> --epic <epic-id> --session <session-id> --causal-parent <event-id>`,
-which appends `fixed` for every finding the epic carried — repeatable, and
-`audit.unknown-epic` if the id was never cut from this store. That is the
-only step of an audit that runs outside this playbook, and it is why the
-store, not this transcript, is where a finding's life is kept.
+`smith audit resolve <project-dir> --epic <epic-id> --session <session-id> --causal-parent <event-id> [--specs-dir <dir>]`,
+which reads the epic's newest plan and appends `fixed` only for a carried
+finding some task in it still claims — the rest come back `deferred`, still
+`accepted`, because the plan scoped them out on purpose. Repeatable;
+`audit.unknown-epic` if the id was never cut from this store, `audit.no-plan`
+if no plan can be found (refuses rather than guess). The default search is
+the work root's specs dir; when this project's plans live elsewhere, pass
+`--specs-dir` naming the same specs dir the epic was run from. `--except
+<fp[,fp...]>` forces specific fingerprints into `deferred` even when a task
+claims them. That is the only step of an audit that runs outside this
+playbook, and it is why the store, not this transcript, is where a finding's
+life is kept.

package/.claude/skills/bs/dispatch.md

@@ -11,7 +11,7 @@ task spec or the one question · the **absolute** worktree path · the path
 claims it may touch · its token cap · **its turn budget, copied verbatim
 from the template's `maxTurns`**. That last one is why it is listed: Claude
 Code enforces the template's `maxTurns` on every `Agent`-tool dispatch
-(dogfood-csb-audit-1 FD-7, FD-14),
+(measured on two dogfood runs, 2026-09-07 and 2026-09-11),
 and the agent cannot see how many turns it has left. A prompt that promises
 more than the template is a fiction the agent plans against and gets cut in
 the middle of (a planner told 40 under a template saying 20 stopped twice
@@ -19,6 +19,22 @@ with nothing written). So state the template's number, never a higher one,
 and tell every role that owes a file to write it before it refines it. A
 role that keeps running out is a template to raise, not a prompt to inflate.
 
+Read that number from `.claude/agents/<role>.md` as the file stands now, at
+dispatch time — not from memory, an earlier dispatch, or a doc that quotes
+it. `smith agents sync` may have rewritten it locally from
+`SMITH_MAXTURNS_<ROLE>` (an uncommitted, per-box edit), and Claude Code
+enforces what the file says. A sync reaches only agents spawned after it.
+
+State it on its own line, verbatim — `Turn budget: 40` — and, on a judge
+dispatch, the declared-artifact line below verbatim too. `smith dispatch
+lint <prompt-file> --role <role> --task <id> --session <id>` reads a
+composed prompt back and checks both against the template and the ledger,
+before the agent ever runs. It fails closed: a number that does not match
+the template — higher (the promise-more-than-the-template mistake above) or
+lower — a missing turn-budget line, a template it cannot read at all, and a
+judge prompt missing or mismatching its artifact line are each a lint
+failure, not a maybe.
+
 ## Splice the compiled lessons into every prompt (agent-interviews.md N-9, P9-2)
 
 Before you dispatch, run
@@ -145,10 +161,30 @@ memory of its previous attempt and will happily report round 1 forever.
   reason). An unlogged escalation is a cost you cannot attribute later — and
   `model_tier` alone cannot even tell you *which* frontier model you escalated
   to, since opus and fable share the tier.
-- **The grader's 2-round cap is a hard stop, not a ladder rung.** At a round-2
-  `fail` the task goes back to the planner for re-scoping. Do not re-dispatch
-  the grader, and do not escalate the *grader* — the gates decide pass/fail,
-  and a third grading round only buys a more expensive opinion.
+- **The grader's 2-round cap is a hard stop, not a ladder rung.** At a
+  round-2 `fail` the operator re-scopes through a concrete, logged path, not
+  a bare re-dispatch:
+  1. `smith plan propose` with a `supersede` pairing the failing task id to a
+     new one (`PlanChanges.supersede`, spec.ts's `amendPlan`) — the operator
+     approves the re-scoping, this command only records the proposal.
+  2. `smith plan approve` the proposed version. This is what writes the
+     `successors{old->new}` pairing (spec.ts's `taskSuccessors`) that
+     everything below checks against.
+  3. `smith worktree create --from <old-task-id> --session <id> ...` to cut
+     the successor's branch from the predecessor's HEAD instead of
+     integration — refused as `worktree.not-a-successor` unless step 2 logged
+     that exact pairing.
+  4. Rerun wave steps 5-7 (dispatch, review, gate) under the new task id. The
+     grader starts that id at round 1 — the ledger's round counter is per
+     `(task_id, role)`, and a new id has never opened a round.
+  5. Gate with `--plan` naming the new plan version.
+
+  A same-id re-dispatch of round 3 is never legal, superseded or not: the cap
+  binds the id, and a kept-id supersede (same task_id, new claims/criteria)
+  does not reset the round either — only a **new** task id starts a fresh
+  ledger. Do not re-dispatch the grader on the old id, and do not escalate the
+  *grader* — the gates decide pass/fail, and a third grading round on the same
+  id only buys a more expensive opinion.
 - **Never escalate a judge to break a tie with another judge.** That is what
   the cross-check quorum is for (`crosscheck.yml`); a bigger critic is still
   one critic.
@@ -210,8 +246,8 @@ stamp) and `<epic>/plan-v<n>` (a plan version, the ref `plan quorum`
 stamps). Anything else — `<epic>/plan-draft`, `<epic>/spec-review-r27` —
 folds a real row that nothing can ever move on, because no planner or
 spec-reviewer dispatch produces the `wave-merged` or `gate-outcome` that
-would: twenty-one of csb-audit-1's twenty-four non-terminal rows were these
-(`docs/specs/dogfood-csb-audit-1-findings.md` FD-27).
+would: on one dogfooded product epic, twenty-one of its twenty-four
+non-terminal rows were these.
 
 So: the closing spec-reviewer, the goal-check spec-reviewer, the planner
 rendering a verdict and the scribe are dispatched against
@@ -318,6 +354,12 @@ true one on the record. `--no-findings` records an operator
 *attestation* rather than a review — use it only for a judge that ran outside
 the factory; a judge that genuinely found nothing writes `[]` and reports.
 
+Tell the judge the exact path on its own line, verbatim —
+`Declared artifact: /abs/path/<task-id>.reviewer.json` — the spelling `smith
+dispatch lint` checks the composed prompt against once the dispatch above
+has landed in the ledger. Missing, relative, or a path that does not match
+what `--artifact` declared are each a lint failure, not a maybe.
+
 ## Dispatching the security-reviewer (agent-interviews.md N-7)
 
 Do not eyeball the path list — ask:
@@ -347,6 +389,17 @@ exceptions — today one, `wave-runner` — and each of them earns it by opening
 session of its own against your dispatch's event id before it dispatches
 anything.
 
+Run `smith issues report --session <session-id> --state-dir <dir> [--epic
+<id>]` right after any of the three things this log can hold: the
+`error-logged` you just wrote, a `gate-outcome` that `smith gate run` records
+with outcome `blocked`, or a `task-added` whose payload sets `task_status:
+failed`. The reporting verb re-reads the whole session lineage log and folds
+all three source event types, so calling it once after any of them covers
+the others too; a repeated call over the same error finds the recorded
+`issue-reported` outcome and moves on, so calling it again is never a
+mistake. A non-zero exit is logged and does not fail the dispatch that owns
+this log; the run keeps going.
+
 ## The task id goes on the event, not in the payload
 
 `smith event append` reads `task_id` at the top level of the JSON, beside

package/.claude/skills/bs/plan.md

@@ -44,7 +44,26 @@ there means "not looked at", not "looked at and clean".
    — a *different model* than the planner's, per its own frontmatter — to
    hunt spec gaps/ambiguities/missing-nonfunctional clauses
    (`docs/standards/agent-constraints.md` "planner"; `severity.yml`: most
-   spec gaps land S2, blocking sign-off).
+   spec gaps land S2, blocking sign-off). Name the review focus in the
+   dispatch itself, as a short list of at most six items, so findings come
+   back tagged to one of them:
+
+   1. Claims and dependency edges, cross-checked against
+      `smith claims impact`.
+   2. TDD-ability -- a named failing test per task, before its code.
+   3. Nonfunctional and security clauses.
+   4. Budget and diff-cap fit.
+   5. Acceptance-criterion coverage -- every epic criterion maps to a task.
+   6. From round 2 on, only the previous round's findings plus any task
+      that changed since then.
+
+   When `size.small` reads true on the draft (`smith wave schedule` or
+   `smith plan ingest`'s `parallelism.size`, run against the draft plan
+   file), recommend effort tier `small` -- single-pass spec review -- to
+   the operator unless a security trigger floors it first, and say why in
+   the same message: a plan that cannot spread past a few tasks and a
+   handful of claim paths does not need a second review round to find what
+   one pass already covers.
 4. Planner fixes flagged issues; repeat 2–3 until the spec-reviewer has
    nothing S1/S2 left — or exactly once when `profile.specReviewRounds` is
    `single-pass` (`small`), where the planner fixes what came back and
@@ -127,6 +146,11 @@ there means "not looked at", not "looked at and clean".
    decide whether to re-slice, and say which you chose when you present the
    plan.
 
+   The same JSON also carries `size` -- `{tasks, claims, small}` over live
+   tasks only -- the block `plan ingest` prints again under `parallelism`
+   at step 7; `small` is true at or under 3 live tasks and 10 distinct
+   claim paths, and this is where the step 3 tier read gets confirmed.
+
    Beside the schedule, the read that names what it only counts:
 
    ```bash
@@ -163,6 +187,14 @@ there means "not looked at", not "looked at and clean".
    UI check found behind two epics. It is idempotent, so run it again on a
    resumed session; read `added` and `edges` back, and say so when either is
    0 on a plan that has tasks or edges.
+
+   Read `parallelism.widest` back from that same output, too. `parallel_with`
+   underneath it is claims-and-edges only -- import-graph crossings stay
+   `wave schedule --repo`'s job, not this key's -- so it can only ever name
+   a width that job would not contradict. A `widest` of 1 on a
+   plan of two or more tasks means every task the wave loop will ever run
+   sits behind some claim or edge that serializes it: flag that to the
+   operator now, before a run discovers it as a stalled wave.
 8. If this epic opens a new roadmap milestone, add it to
    `factory/specs/roadmap.md` (planner-maintained, architecture §12) — a
    roadmap change is itself a scope change and needs the same operator nod.

package/.claude/skills/bs/run.md

@@ -123,8 +123,9 @@ under it, which is the wrong `--state-dir`, or a wave session opened without
 done; a green gate on serialized work is exactly the outcome the two
 playbooks are written to prevent.
 
-11. Repeat until every task in the live plan version is
-    `completed`/`superseded`/`waived`. Dispatch the **`planner`** again for
+11. Repeat until every task in the live plan version is `completed`/`waived`,
+    or `superseded` by a successor that is itself terminal-OK (recursively —
+    a successor chain counts too). Dispatch the **`planner`** again for
     the epic verdict against acceptance criteria — gaps found → a NEW
     `plan-v(n+1)` with inferred tasks (never a live-graph mutation,
     architecture §12), auto-scheduled at confidence ≥0.8 else parked for an
@@ -165,10 +166,9 @@ playbooks are written to prevent.
     13-16 write. The envelope leaves the flag optional, and an omitted one
     stamps the record `plan_version: 1` — so on an epic that amended, the
     check, the review and the close all claim to have verified a plan that
-    no longer exists. csb-signing-policy-1 closed at v3 with its integration
-    check and its closing spec review both stamped v1
-    (`csb-signing-policy-1-2026-09-11#197`, `#202`); the goal check, passed
-    the flag, says v3. Read the version off `smith plan ingest`'s receipt and
+    no longer exists. One dogfooded product epic closed at v3 with its
+    integration check and its closing spec review both stamped v1; the goal
+    check, passed the flag, said v3. Read the version off `smith plan ingest`'s receipt and
     pass it every time.
 13. Dispatch the **`spec-reviewer`** again — this time against the code.
     The pre-code review at `/bs plan` step 3 read the spec against nothing;
@@ -276,8 +276,8 @@ playbooks are written to prevent.
     provider is `active` in `crosscheck.yml`: codex spends the operator's
     ChatGPT quota, DeepSeek spends prepaid credit, and step 16 runs the
     verdict again before it writes, so a clean close is two spends, not one
-    (csb-signing-policy-1 wrote two `quorum-decision`s against its
-    integration ref, `#210` from the verdict and `#215` from the close).
+    (one dogfooded epic wrote two `quorum-decision`s against its
+    integration ref, one from the verdict and one from the close).
     Nothing in the `quorum-decision` payload names the purse, so say which
     one it is to the operator before the first call, not after the second.
 16. Record the close. The verdict above is a read-only probe and writes
@@ -293,17 +293,22 @@ playbooks are written to prevent.
     yourself** — closing over a hold is the operator's call; ask for it and
     quote the blockers. If the epic was cut by `/bs audit`
     ([`audit.md`](audit.md) step 10), follow the close with
-    `smith audit resolve <project-dir> --epic <epic> --session <session-id> --causal-parent <event-id>`
-    so every finding the epic carried is marked `fixed` in the project's
-    audit store — the store, not the epic, is where a finding's life ends.
+    `smith audit resolve <project-dir> --epic <epic> --session <session-id> --causal-parent <event-id> [--specs-dir <dir>]`
+    so every finding this plan still claims is marked `fixed` in the
+    project's audit store — the rest come back `deferred`, left exactly as
+    they were, because the plan scoped them out on purpose. The store, not
+    the epic, is where a finding's life ends. `resolve` reads the epic's
+    newest plan from the work root's specs dir by default; when this
+    project's plans live elsewhere, pass `--specs-dir` naming the same specs
+    dir the epic was run from, or it refuses rather than guess.
 17. Open **one integration PR per epic** with the scribe-written body
     (`/bs report`'s playbook, [`report.md`](report.md)) — screenshots, test
     results, reviewer verdict, waivers granted, timeline link. The head is
     `smith/<epic>/integration`. The base is the target repo's `main` unless
     the epic was cut from another epic's integration branch, in which case
     the PR stacks on that branch and the operator merges the parent's PR
-    first — csb-signing-policy-1 was cut from `smith/csb-audit-1/integration`
-    and opened PR #54 against it, behind PR #53; once the parent has merged
+    first — a child epic cut from `smith/<parent>/integration` opens its PR
+    against that branch, behind the parent's PR; once the parent has merged
     and its branch is deleted, GitHub retargets the child to `main`. The
     operator reviews on GitHub; this session never merges to `main`
     (`docs/standards/guardrails.md`).

package/.claude/skills/bs/wave.md

@@ -33,6 +33,14 @@ both:
   its waves, and a window spent on this wave's dispatches is a window the
   epic does not have for the wave after next (D13).
 
+After any `error-logged` this wave writes — a worker that died, a judge turn
+that failed, a gate refusal recorded as an error — or a `smith gate run`
+that came back `blocked` (its `gate-outcome` event with outcome `blocked`),
+or a task the wave marks `failed` (its `task-added` event with payload
+`task_status: failed`), the wave runs the reporting verb once, per
+[`dispatch.md`](dispatch.md)'s paragraph of this same heading, which owns
+the rule.
+
 Which `<event-id>` depends on how you were started, and the difference is
 not cosmetic — it is the edge an audit walks:
 
@@ -47,14 +55,27 @@ not cosmetic — it is the edge an audit walks:
   anything else and the check reports you as `unverifiable` — not as a
   pass — however well the wave ran. Open it **before** your first dispatch,
   for the same reason: a grant is earned by owning the log first.
+- **You are taking over a wave whose runner died or capped**: continue from
+  that runner's last event, in a session of your own. Do not write into its
+  log. One session has one author, and `smith delegation check` reads exactly
+  that: dispatches appended to a dead delegate's log by whoever picked the
+  wave up are reported as violations, correctly, because from the log's side
+  they cannot be told apart from an agent narrating its own work. Open your
+  own instead:
+  `smith session start <wave-id>-takeover --continues <dead-session>#<n>`.
+  That keeps the chain whole — the epic's folded reads still see every
+  dispatch on both sides of the handover — and it makes the takeover a fact
+  in the log rather than something a reader has to infer from two agents and
+  one timeline.
 
-Either way, one rule holds: **the log you write is the log the epic reads**,
-and `--continues` is the whole of what makes that true. Every deciding read
-at the epic tier folds the lineage rather than one session — `wave audit`,
-`budget alarm`, `tester check`, `judge outstanding`, `escalation check`,
-`dispatch check`, `delegation check` — so a dispatch recorded in a wave
-session is visible from the epic session that admitted it, and is *not*
-visible from a sibling wave's. Open a wave session without `--continues` and
+Whatever the case, one rule holds: **the log you write is the log the
+epic reads**, and `--continues` is the whole of what makes that true.
+Every deciding read at the epic tier folds the lineage rather than one
+session — `wave audit`, `budget alarm`, `tester check`,
+`judge outstanding`, `escalation check`, `dispatch check`,
+`delegation check` — so a dispatch recorded in a wave session is visible
+from the epic session that admitted it, and is *not* visible from a
+sibling wave's. Open a wave session without `--continues` and
 none of those verbs can see your work: they will not error, they will answer
 about a wave that appears never to have run.
 
@@ -126,6 +147,28 @@ one thing this playbook never asks you to.
    carries `keeps_exports`, restate the promise in the dispatch in one line:
    the file list, and "keep every existing export's name and declaration;
    adding is fine".
+
+   Once every coder of the wave has been dispatched — this fan-out has gone
+   out for every admitted task — audit the wave's own parallelism while it
+   can still be corrected: `smith wave audit --session <id> --epic <epic>`.
+   `wave check` is the step-1 gate that certified, before any dispatch, that
+   these tasks could run together; `wave audit` reads the log back after
+   dispatch and says whether they did.
+   It is a read, so it costs nothing against "No lockstep barrier" above and
+   waits for no task. Read the `verdict` field (`WAVE_VERDICTS`,
+   `waveConcurrency.ts`), not only the exit code — `partial` also exits 0:
+   - `serialized` or `partial` — the wave is not running the width it was
+     admitted at, and steps 5–7 have not gone out yet, so it can still be
+     fixed: dispatch every remaining phase of this wave as one message of
+     parallel calls, per "One message, many dispatches" above, and record
+     the verdict as an operator-visible event — `error-logged` with error
+     `contract.constraint-decay` (`taxonomy.yml`): the wave-runner stopped
+     honoring that section's standing constraint.
+   - `unobserved` — the log holds no dispatch for any task this wave
+     admitted. That is a defect in the log, not in how the wave ran; record
+     it the same way, as `error-logged` with error `execution.env-failure`.
+   - `parallel` or `single` — nothing further; the wave ran as wide as it
+     was admitted.
 5. Dispatch **`tester`** (`.claude/agents/tester.md`) for missing unit
    coverage and epic-level e2e/screenshots.
    - Then the **uiux visual pass**, but only when all three hold: the task
@@ -143,7 +186,8 @@ one thing this playbook never asks you to.
    runs; it never decides pass/fail itself. At one round the grader scores
    once and a failed criterion is the coder's bounce, not a re-grade. Its result file is an **input to
    step 7**, not a note to the operator: pass it as `--grader` or the rubric
-   gates nothing (D-34).
+   gates nothing (D-34). A round-2 `fail` re-scopes via dispatch.md's "Round
+   counting and escalation", not a round 3 on this id.
 7. Run the gate pipeline:
    `smith gate run <task-id> --worktree <dir> --checks checks.json --result
    result.json --grader state/results/<task-id>.grader-r<round>.json
@@ -217,8 +261,18 @@ one thing this playbook never asks you to.
    — see "Round counting and escalation" above. Then have the log check
    you: `smith escalation check <session-id> --task <task-id>`, which
    exits 1 if the rung you just climbed is not evidenced.
-10. Gate outcome `pass`/`pass-with-waivers-pending` → before admitting,
-    ask what the diff did to everyone outside the claims, and whether it
+10. Gate outcome `pass`/`pass-with-waivers-pending` → before admitting, audit
+    the wave's own parallelism: `smith wave audit --session <id> --epic
+    <epic>`. It reads the log back and says whether the tasks admitted
+    together actually ran together — `parallel` when every admitted task was
+    in flight at once, `partial` when two or more overlapped but never all,
+    `serialized` when work is recorded but no two tasks ever overlapped,
+    `single` when the wave admitted one task (nothing to be parallel about),
+    and `unobserved` when the wave was admitted and the log shows no work for
+    any of its tasks. Exit 1 on `serialized`, exit 2 on `unobserved` — either
+    is a fact for the wave-loop's hand-back, not a reason to hold the merge:
+    report the verdict and keep going to admission. Then ask what the diff
+    did to everyone outside the claims, and whether it
     kept what the spec promised:
     `smith claims impact <worktree-dir> <spec.json>`. Exit 1 means a
     `proven` break — this task removed an export a file outside its claims
@@ -250,6 +304,10 @@ one thing this playbook never asks you to.
     auto-resolve a semantic conflict silently (`worktree.yml`
     `conflict_resolution_ladder`).
 
+    An `integration-dirty` outcome names a `worktree` holding
+    `smith/<epic>/integration` with uncommitted tracked changes (`dirty`):
+    commit or stash those there, then re-run `smith queue run`.
+
     Once the wave is merged, check the epic's spend — `smith budget alarm
     <session-id> [--epic <epic>]`. Exit 1 means either the epic crossed
     `alarm_ratio` (re-plan the remaining work to fit, or ask the operator —

package/README.md

@@ -331,7 +331,7 @@ runs, plus branch protection — not by trust. Full rules:
 **[`docs/standards/guardrails.md`](docs/standards/guardrails.md)**.
 
 - **Secrets are environment-only.** `.env.example` is the only committed env
-  file (variable names, never values), and the event logger redacts
+  file (variable names, never a secret's value), and the event logger redacts
   credential-shaped strings before write.
 - **Only you merge to `main`.** No agent may push or merge to a protected
   branch, and force-push is refused on every branch, protected or not — an
@@ -391,9 +391,9 @@ runbook is written; the hosted UI stays deferred. Beside the phases, `/bs audit`
 is built: an existing project can be read on four axes and one epic cut from
 what you accept.
 
-The CLI is on npm as `@juzser/blacksmith`, at `0.2.0` — two binaries now,
-`smith` and `smith-run`, the second being what runs a rendered turn on a
-`cli` harness such as Codex. `0.1.1` was the first version that ran beside
+The CLI is on npm as `@juzser/blacksmith`, at `0.4.0` — two binaries,
+`smith` and `smith-run`, the second (since `0.2.0`) being what runs a
+rendered turn on a `cli` harness such as Codex. `0.1.1` was the first version that ran beside
 you and knew it was a package, rather than out of the clone-shaped install
 `0.1.0` was. The package is the binaries and what they
 read. The dashboard, the docs, the test suite and `/bs` itself come from a