@juzser/blacksmith 0.3.0 → 0.5.0

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

@@ -10,8 +10,9 @@ bind every dispatch below: the project directory is an answer you ask for
 rather than a path anything here knows, every write carries
 `--session <id> --plan-version <n> --causal-parent <event-id>`, every
 dispatch carries the compiled lessons block and that task's open-findings
-block, and fetched text is wrapped before it is quoted. None of it is
-restated here; a second copy is a copy that drifts.
+block, every `dispatch_decision` carries a one-line plain-words `reason`
+(dispatch.md's payload contract), and fetched text is wrapped before it is
+quoted. None of it is restated here; a second copy is a copy that drifts.
 
 The step numbers are the loop's own. They start at 2 because step 1 — which
 tasks, and how wide — was answered before you were handed anything, and they
@@ -26,15 +27,17 @@ both:
 - **Inline**, in the epic session, when the wave is small enough that the
   epic's window can carry it. Nothing changes: the session id you were
   handed is the one you write to.
-- **In a session of its own** when it is not. Open one with `smith session
+- **In a session of its own** when it is not. Open one with `bs session
   start <wave-id> --continues <event-id>` and write every dispatch below
   there. The epic session then carries the admission and the result rather
   than every turn in between — which is the point, because an epic outlives
   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).
+  epic does not have for the wave after next (D13). Every event you write in
+  that session carries `--actor wave-runner` — `.claude/agents/bs-wave-runner.md`'s
+  Constraints has the rule and the check it satisfies.
 
 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 failed, a gate refusal recorded as an error — or a `bs 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
@@ -46,9 +49,9 @@ not cosmetic — it is the edge an audit walks:
 
 - **The epic ran you** and you opened a wave session yourself: continue from
   the epic event that admitted this wave.
-- **You were dispatched as a `wave-runner`**: continue from the
+- **You were dispatched as a `bs-wave-runner`**: continue from the
   `dispatch_decision` that dispatched you, the event id handed to you with
-  the wave. `smith delegation check` resolves your session by matching a
+  the wave. `bs delegation check` resolves your session by matching a
   `session-start`'s `causal_parent` against that dispatch, and it is the
   only thing that proves the dispatches you are about to write are your
   own log's rather than an agent talking about itself. Continue from
@@ -57,12 +60,12 @@ not cosmetic — it is the edge an audit walks:
   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
+  log. One session has one author, and `bs 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>`.
+  `bs 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
@@ -114,18 +117,22 @@ the difference between a factory and a queue with extra steps:
   keep the wave moving.
 
 The single place the wave rejoins is step 10's merge queue, which is
-serial on purpose — `smith queue run` rebases one task at a time onto
-`smith/<epic>/integration` and runs the cumulative tests between. Merging
+serial on purpose — `bs queue run` rebases one task at a time onto
+`bs/<epic>/integration` and runs the cumulative tests between. Merging
 is the one thing that cannot be done in parallel, and it is already the
 one thing this playbook never asks you to.
 
 ## The steps
 
-2. Per admitted task, and for all of them together: `smith worktree create
+2. Per admitted task, and for all of them together: `bs worktree create
    <project-dir> <epic> <task-id>`.
-3. Pre-code, if the task needs it: dispatch `researcher` for an unknown, or
-   `uiux` (`.claude/agents/uiux.md`) for any UI-affecting acceptance
-   criterion — before the coder starts, not after.
+3. Pre-code, if the task needs it: dispatch `bs-researcher` for an unknown, or
+   `bs-uiux` (`.claude/agents/bs-uiux.md`) for any UI-affecting acceptance
+   criterion — before the coder starts, not after. Bracket the uiux spec
+   turn with `bs judge dispatch --role uiux --kind spec` / `bs judge report
+   --role uiux --kind spec`, the same way every judge turn in steps 5–7 is
+   bracketed — the gate's uiux stage (step 7) reads this turn back and
+   blocks a flagged task that never closed it.
    - `profile.preCodeResearch` gates the researcher: `when-needed` is the
      line above, `never` (`small`) means the coder reading the repo *is* the
      brief. An epic that genuinely cannot start without a research brief is
@@ -134,44 +141,108 @@ one thing this playbook never asks you to.
      every tier: no tier ships a UI change without a spec to review it
      against. It is listed as a knob so the answer is asked for rather than
      assumed, not because a tier can turn it off.
-   - A returned brief goes through `smith research check --brief <path>`
+   - A returned brief goes through `bs research check --brief <path>`
      before it is attached to a task spec ("Fetched and quoted text goes into
      a prompt fenced" above). Exit 1 sends it back; on exit 0, carry
      `recommendation.provenance` into the coder's prompt so the task knows
      whether its research rests on this repo or on a fetched page. Any raw
-     fetched text you quote alongside it is wrapped with `smith prompt wrap`.
-4. Dispatch **`coder`** (`.claude/agents/coder.md`) in that worktree.
-   Token/diff caps (`budgets.yml`: 150k tokens, 400 diff lines) and YAGNI
+     fetched text you quote alongside it is wrapped with `bs prompt wrap`.
+4. Dispatch **`bs-coder`** (`.claude/agents/bs-coder.md`) in that worktree.
+   Token/diff caps (`budgets.yml`, sized per effort tier) and YAGNI
    are the coder's own constraints — don't restate them here, the template
    does. What the template does not read is the schema, so when the spec
    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".
-5. Dispatch **`tester`** (`.claude/agents/tester.md`) for missing unit
+
+   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: `bs 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`.
+   - `unlinked` — the wave's work merged, or was dispatched, off the epic's
+     own lineage (a wave-runner session started without `--continues`).
+     Real work, not a defect in dispatch, but its width is unmeasured —
+     record it as `error-logged` with error `contract.constraint-decay` so
+     the session gets linked under `--continues` next time.
+   - `parallel` or `single` — nothing further; the wave ran as wide as it
+     was admitted.
+5. Dispatch **`bs-tester`** (`.claude/agents/bs-tester.md`) for missing unit
    coverage and epic-level e2e/screenshots.
+   - The moment it returns, project its result: `bs results record --task
+     <task-id> --result <tester-result.json> --agent tester --provider <name>
+     --model-tier <tier> --worktree <dir> --session ... --plan-version N
+     --causal-parent ...`. `--agent` stamps the envelope, token_usage
+     included, as `gate run` does; `--worktree` is the coder's worktree the
+     tester shares, and records the HEAD that proves the screenshots fresh
+     (D2) — step 7's uiux stage blocks `screenshots-stale` when this HEAD
+     doesn't match the gate's. The tester has no tests of its own to run, so
+     it never reaches `gate run` itself — without this, its screenshots sit
+     in the result file and never reach the task page.
    - Then the **uiux visual pass**, but only when all three hold: the task
      is UI-affecting, the tester actually returned screenshot artifacts, and
-     step 3 wrote a uiux spec for this task (agent-interviews.md N-6). Miss
-     any one and skip it — say so; a "visual pass" over screenshots that do
-     not exist is worse than no pass. Dispatch it with the spec path and the
+     step 3 wrote a uiux spec for this task (agent-interviews.md N-6). For a
+     UI-affecting task, miss any one and stop, do not skip — step 7's gate
+     blocks a flagged task with no fresh, reviewed screenshot set, so a
+     missing condition here is not a quiet pass-through to the gate, it is a
+     reason to fix the condition first. Dispatch it with the spec path and the
      image paths and **nothing else**: no diff, no components, no test code.
      The pass is a judgment about the rendered screen, and a uiux session
      that reads the diff ends up reviewing intent, which the reviewer
      already covers.
-6. Dispatch **`grader`** (`.claude/agents/grader.md`) — bounded rubric
+     Bracket it with `bs judge dispatch --role uiux --kind visual` / `bs
+     judge report --role uiux --kind visual`: a dispatch with no `--kind` is
+     refused (`judges.kind-required`), because a kindless turn is one the gate's
+     uiux stage never reads.
+   - **Blast radius.** When the task's claims touch a shared primitive (a
+     design-system/kit component or a global stylesheet), a screenshot of
+     the task's own screens is not the full surface: the tester re-shoots
+     and the uiux visual pass reviews every screen that renders that
+     primitive, not only the task's screens. The tester determines that
+     list — from the screenshot suite already on disk or from the
+     primitive's importers — and records it alongside the screenshots it
+     captures. The "max 4 per feature" screenshot cap (bs-tester.md) still applies per
+     screen; it is the screen count that grows, not the shots on each one.
+6. Dispatch **`bs-grader`** (`.claude/agents/bs-grader.md`) — bounded rubric
    loop, `profile.graderRounds` rounds (2 at `huge`, 1 below; never more
    than 2, agent-constraints.md "grader (v3)"), before any gate
    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
+   `bs gate run <task-id> --worktree <dir> --checks checks.json --result
    result.json --grader state/results/<task-id>.grader-r<round>.json
-   --findings findings.json --session ... --plan-version N
+   --findings findings.json --plan <plan.json> --uiux-visual
+   state/results/<task-id>.uiux-visual.json --session ... --plan-version N
    --causal-parent ...` (schema check → grader verdict → tests → coverage
    evidence → findings intake → severity decision,
    `docs/guide/operator-guide/queue-and-gate.md` §5).
+   - `--plan` is what lets the gate's uiux stage read the task's
+     `ui_affecting` flag; without it the stage records "unverifiable" and
+     does not block. `--uiux-visual` hands over the visual pass's result
+     file when step 5 ran one — omit it for a task that is not UI-affecting.
+   - `checks.json`'s unit check must be the project's full test command,
+     never a hand-picked list of files — `gate run` runs each check command
+     literally, with no narrowing of its own. Narrowing by changed files is
+     `bs queue run --select-test-cmd` (`factory/orchestrator/src/testSelect.ts`),
+     a queue-tier flag `--batch` refuses; it does not reach `checks.json`. A
+     scoped-down unit check is how red tests have merged before.
    - `--grader` takes step 6's file, latest round. A criterion that came back
      `fail` or `partial` blocks before any check command runs — the outcome is
      `blocked` with `reason: "grader-fail"`, and the payload's
@@ -182,11 +253,11 @@ one thing this playbook never asks you to.
      add (D-40). `blocked` with `reason: "coverage-evidence"` means the run
      produced no per-file number for a file this task's claims name; fix the
      reporter or the include glob, not the code. Ask the same question
-     outside a gate run with `smith coverage check <worktree-dir> --plan
+     outside a gate run with `bs coverage check <worktree-dir> --plan
      <plan.json> --task <task-id>` (§5c).
-   - Findings come from dispatching **`reviewer`**
-     (`.claude/agents/reviewer.md`, fresh context, read-only) then
-     **`verifier`** (`.claude/agents/verifier.md`, adversarial refute
+   - Findings come from dispatching **`bs-reviewer`**
+     (`.claude/agents/bs-reviewer.md`, fresh context, read-only) then
+     **`bs-verifier`** (`.claude/agents/bs-verifier.md`, adversarial refute
      mandate) — never skip the adversarial stage on an S1/S2 finding
      (`crosscheck.yml` `asymmetric_roles`). Which findings that covers is
      `profile.verifierSeverities`, plus a
@@ -196,25 +267,26 @@ one thing this playbook never asks you to.
      thing a cheaper tier drops; `S1-stop-the-line` is in every tier's list
      and no tier may remove it. A finding outside the tier's list still goes
      to the coder — it is verified by the coder's fix, not waived.
-   - Dispatch **`security-reviewer`** only when its conditional triggers
+   - Dispatch **`bs-security-reviewer`** only when its conditional triggers
      fire — never per-task by default. Ask, do not recall:
-     `smith security triggers --task <spec.json>` and dispatch iff
+     `bs security triggers --task <spec.json>` and dispatch iff
      `dispatchSecurityReviewer` is true ("Dispatching the security-reviewer"
      above).
    - Every judge dispatched in steps 5–7 — uiux visual pass, grader,
      reviewer, verifier, security-reviewer — is bracketed by
-     `smith worktree fingerprint` / `smith worktree verify`
+     `bs worktree fingerprint` / `bs worktree verify`
      ("Fingerprint the worktree around every judge" above). Exit 1 discards
      that judge's result; it does not become a finding against the coder.
-   - Each of those is also bracketed by `smith judge dispatch` /
-     `smith judge report` ("Declare each judge's artifact before you dispatch
-     it" above). `smith judge outstanding --task <task-id>` exits 1 while any
+   - Each of those is also bracketed by `bs judge dispatch` /
+     `bs judge report` ("Declare each judge's artifact before you dispatch
+     it" above); paste `judge dispatch`'s `expected_line` inline in the
+     judge's prompt, or the `Agent` call is refused. `bs judge outstanding --task <task-id>` exits 1 while any
      judge still owes its file — re-poke it and report before running the
      gate, because the gate now refuses to score with a non-empty outstanding
      set (`reason: judges-outstanding`) rather than reading a silent judge as
      zero findings.
    - The gate scores tests it did not write, so once it has run, make the log
-     say who did: `smith tester check <session-id> --task <task-id>`
+     say who did: `bs tester check <session-id> --task <task-id>`
      (`crosscheck.yml` `role_isolation`, operator-guide/dispatch-audits.md §2d). Exit 1
      means no `tester` dispatch precedes this task's `testgate-result`, the
      coder and tester dispatches share one `agent_id`, or the answer is
@@ -223,9 +295,9 @@ one thing this playbook never asks you to.
      downstream still goes green — step 5 is what prevents that, and this is
      the log checking that step 5 happened.
 8. Every dispatch in steps 3–7 carries the compiled lessons block for that
-   role (`smith lessons for-dispatch <role> --plan … --task …`), every
+   role (`bs lessons for-dispatch <role> --plan … --task …`), every
    worktree dispatch also carries the open-findings block for that task
-   (`smith findings for-dispatch --plan … --task …`) — both under "Dispatch
+   (`bs findings for-dispatch --plan … --task …`) — both under "Dispatch
    contract" above — and each is a `dispatch_decision` event with a `causal_parent`
    chaining back to the prompt/decision that caused it (architecture §7) —
    this is the timeline, not optional bookkeeping.
@@ -236,12 +308,25 @@ one thing this playbook never asks you to.
    rung, never loop past one. Count the rounds from this task's
    `dispatch_decision` events, not from the agent's own account of itself
    — see "Round counting and escalation" above. Then have the log check
-   you: `smith escalation check <session-id> --task <task-id>`, which
+   you: `bs 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: `bs 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),
+    `unlinked` when the work merged or dispatched but off the epic's own
+    lineage (width unmeasured, not zero — usually a wave-runner session
+    started without `--continues`), 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`, exit 0 on `unlinked` — each
+    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
+    `bs claims impact <worktree-dir> <spec.json>`. Exit 1 means a
     `proven` break — this task removed an export a file outside its claims
     still imports — **or a broken promise**: a file the spec's
     `keeps_exports` names lost an export or changed one's declaration.
@@ -249,10 +334,14 @@ one thing this playbook never asks you to.
     entries in the bounce. A `possible` / `signature-changed` entry in
     `breaks` exits 0 and is a note: the scanner reads text, not types
     (operator-guide/wave.md §2). Then admit into the
-    merge queue: `smith queue run <epic> --project <project-dir>
-    --test-cmd "<cumulative test command>" --tasks tasks.json`. On a
-    `rebase-conflict` outcome, dispatch **`merger`**
-    (`.claude/agents/merger.md`) with both diffs + specs, and note three
+    merge queue: `bs queue run <epic> --project <project-dir>
+    --test-cmd "<cumulative test command>" --tasks tasks.json --plan
+    <plan.json> --session <id> --plan-version <n> --causal-parent
+    <event-id>` — the same write triple as every other dispatch above; a
+    merge that lands with no session to log it into is a fact the
+    timeline never gets. On a
+    `rebase-conflict` outcome, dispatch **`bs-merger`**
+    (`.claude/agents/bs-merger.md`) with both diffs + specs, and note three
     things the queue's own behaviour forces (agent-interviews.md N-12):
     - **Into the failing task's existing worktree** — a fresh one would not
       reproduce the conflict. The result gives you only `taskId` and
@@ -263,7 +352,7 @@ one thing this playbook never asks you to.
     - The queue already ran `git rebase --abort` (`queue.ts`), so the
       merger arrives at a clean tree and **replays** the rebase rather than
       resuming it — and it **never lands the merge**. When it returns
-      `resolution: "mechanical"`, re-run `smith queue run`; the queue stays
+      `resolution: "mechanical"`, re-run `bs queue run`; the queue stays
       the single place a merge can happen.
 
     `resolution: "escalated"` — low confidence, or both sides changed the
@@ -271,7 +360,11 @@ one thing this playbook never asks you to.
     auto-resolve a semantic conflict silently (`worktree.yml`
     `conflict_resolution_ladder`).
 
-    Once the wave is merged, check the epic's spend — `smith budget alarm
+    An `integration-dirty` outcome names a `worktree` holding
+    `bs/<epic>/integration` with uncommitted tracked changes (`dirty`):
+    commit or stash those there, then re-run `bs queue run`.
+
+    Once the wave is merged, check the epic's spend — `bs 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 —
     extension is always an operator question) **or** the log is too holey to

package/README.md

@@ -125,7 +125,7 @@ provider.
 **The log is the source of truth**
 
 Every prompt, dispatch, gate result and error is an append-only event on disk.
-The dashboard is a projection of that log, and `smith db rebuild` reconstructs
+The dashboard is a projection of that log, and `bs db rebuild` reconstructs
 the entire database from the log alone. Nothing the factory did exists only in
 a chat transcript.
 
@@ -168,18 +168,27 @@ and two inside Claude Code:
 /plugin install blacksmith@blacksmith
 ```
 
-Then `smith init` in the project you want it to work on. That creates
+Two optional plugin modules come from the same marketplace, bs-mod (a live
+HUD of your epic above the prompt) and pr-mod (the repo's open pull requests),
+and [`docs/guide/mods.md`](docs/guide/mods.md) has what each needs:
+
+```
+/plugin install bs-mod@blacksmith
+/plugin install pr-mod@blacksmith
+```
+
+Then `bs init` in the project you want it to work on. That creates
 `.blacksmith/` beside your code — the event log, your epic plans, a roadmap and
-a `stack.yml` to answer — and writes nothing anywhere else; `SMITH_HOME` moves
+a `stack.yml` to answer — and writes nothing anywhere else; `BS_HOME` moves
 that root if you want one home for several projects. You now have `/bs`.
 
 **Both halves are required.** The package
 ([`@juzser/blacksmith`](https://www.npmjs.com/package/@juzser/blacksmith)) is the
-deterministic `smith` CLI; the plugin is `/bs` and the fourteen agent roles it
-dispatches. `smith` alone never gives you `/bs`, because Claude Code loads
+deterministic `bs` CLI; the plugin is `/bs` and the fourteen agent roles it
+dispatches. `bs` alone never gives you `/bs`, because Claude Code loads
 skills from a project's `.claude/`, your `~/.claude/`, or a plugin — never from
-`node_modules` — and a `/bs` with no `smith` on PATH can run nothing. Take
-`latest`: `0.1.0` predates `smith init` and keeps state inside its own install
+`node_modules` — and a `/bs` with no `bs` on PATH can run nothing. Take
+`latest`: `0.1.0` predates `bs init` and keeps state inside its own install
 directory, which the next `npm i` replaces.
 
 <details>
@@ -197,17 +206,21 @@ bash scripts/check.sh                   # the gate CI runs; ends in `== PASS ==`
 
 Open a Claude Code session in the clone and you have `/bs` already, from the
 checkout's own `.claude/` — **do not also install the plugin there.** You would
-get two of everything (`bs` and `blacksmith:bs`, `auditor` and
-`blacksmith:auditor`, once per role), pay the always-on cost twice, and the two
+get two of everything (`bs` and `blacksmith:bs`, `bs-auditor` and
+`blacksmith:bs-auditor`, once per role), pay the always-on cost twice, and the two
 copies are free to disagree: the plugin's is a pinned checkout of `main`, the
 project's is whatever branch you have out. `claude plugin disable blacksmith`
-settles it.
+settles it. It also turns off the prompt recorder in that clone, which only
+the plugin registers; a clone that wants its prompts recorded keeps the plugin
+enabled and accepts the double listing
+([INSTALL.md](INSTALL.md#the-install--bs-and-bs)).
 
 The dashboard is clone-only because `ui/` is in neither the tarball nor the
-plugin, so `smith ui serve` answers `ui.not-built` in an install and means it.
+plugin, so `bs ui serve` answers `ui.not-built` in an install and means it.
 Enforcement is clone-only because this repo's `.claude/settings.json` deny
-rules and its policy hook resolve paths against a checkout; the plugin ships no
-`hooks/hooks.json` and loads neither (`Hooks (0)`), since a `/bs` that asked
+rules and its policy hook resolve paths against a checkout; the plugin ships one
+`hooks/hooks.json`, holding only the non-blocking prompt-capture hook, and
+loads neither the deny rules nor the policy guard, since a `/bs` that asked
 you about every Bash command would be worse than one that asks about none. The
 rest of that port is scoped in
 [`docs/specs/plugin-port-scope.md`](docs/specs/plugin-port-scope.md).
@@ -233,9 +246,9 @@ would rather drive it yourself, it is three commands:
 ```bash
 $EDITOR factory/policies/stack.yml   # your stack answers: language, frontend,
                                      # database, deploy target. `none` is fine.
-smith stack check                    # which answers the templates honour,
+bs stack check                       # which answers the templates honour,
                                      # which they only record, which they refuse
-smith new my-app --target-dir ~/code/my-app     # add --ui for a frontend
+bs new my-app --target-dir ~/code/my-app        # add --ui for a frontend
 ```
 
 The last call scaffolds (TS strict, Biome, Vitest, CI), installs, runs the
@@ -278,7 +291,7 @@ it is the ordinary loop: `/bs plan` against that epic, then `/bs run`, and
 closing the epic marks its findings fixed. There is no audit-specific run
 path; the command's value is the insight and the ranking.
 
-Underneath it is the `smith audit` family — `open`, `record`, `consolidate`,
+Underneath it is the `bs audit` family — `open`, `record`, `consolidate`,
 `decide`, `cut`, `resolve`, `close` — and
 [`docs/specs/audit-command-scope.md`](docs/specs/audit-command-scope.md) is the
 contract each of them keeps.
@@ -300,10 +313,10 @@ Day to day, from a Claude Code session opened in this repo:
 | `/bs lessons` | Review pending lesson candidates |
 | `/bs report` | Render the scribe's progress digest |
 
-Each of those is a playbook, not a script: the deterministic half is a `smith`
-command you can run yourself — `smith --help` lists all of them — and the
+Each of those is a playbook, not a script: the deterministic half is a `bs`
+command you can run yourself — `bs --help` lists all of them — and the
 judgment half is a Claude Code session the playbook dispatches. That is also
-the line between the two installs: the `smith` half travels in the package, the
+the line between the two installs: the `bs` half travels in the package, the
 playbooks are read from a clone.
 
 → **[The operator loop](docs/guide/operator-loop.md)** — the six steps, in the
@@ -319,7 +332,7 @@ v1. From there the loop admits a wave whose path claims do not overlap, sends
 researcher and UI/UX work ahead of code where the epic needs it, runs a coder
 and a tester in a worktree, grades the result against its own acceptance
 criteria, then puts it through the gates and a serial merge queue into
-`smith/<epic>/integration`. One epic, one integration PR, merged by you.
+`bs/<epic>/integration`. One epic, one integration PR, merged by you.
 
 → The pipeline diagram and the reasoning behind each stage:
 **[architecture §3 — The loop](docs/specs/black-smith-architecture.md#3-the-loop)**.
@@ -339,8 +352,10 @@ runs, plus branch protection — not by trust. Full rules:
   branch solely through the serial merge queue.
 - **No autonomous deploy or outbound sends.** Deploys, publishes and message
   sends each need per-invocation approval.
-- **Budgets are declared per role.** 4M tokens per epic with an alarm at 70%;
-  150K tokens and 400 diff lines per coder task. Fan-out is bounded by the
+- **Budgets are declared per role and sized per effort tier.** A medium epic
+  gets 16M tokens with an alarm at 70%, and a coder task 220K tokens and 700
+  diff lines; a small epic gets half the task numbers and 4M, a huge one
+  double and 32M. Fan-out is bounded by the
   claim graph, and `max_in_flight_tasks` is available on top of it, off by
   default. Which of these *block* versus *report* is spelled out in
   [`factory/policies/budgets.yml`](factory/policies/budgets.yml) — the task cap
@@ -351,11 +366,14 @@ a public issue.
 
 ## The dashboard
 
-Optional, and deliberately small: `/bs ui` (or `smith ui serve`) binds eleven
-read-only pages to `127.0.0.1`. They are a projection of the event log and
-nothing else — `smith db rebuild` reconstructs them from it, `smith stats`
-prints the same facts in a terminal, and nothing you click there dispatches an
-agent. The factory runs without ever opening it.
+Optional, and deliberately small: `/bs ui` (or `bs ui serve`) binds eleven
+read-only pages to `127.0.0.1`. They are a projection of the event log —
+`bs db rebuild` reconstructs them from it, `bs stats` prints the same facts in
+a terminal, and nothing you click there dispatches an agent. It also reads
+the local Claude Code session registry, transcripts and prompt history (read-only;
+`--claude-config-dir`, then `$CLAUDE_CONFIG_DIR`, then Claude Code's default),
+served as `GET /api/cli-sessions` to loopback requests only. The factory runs
+without ever opening the dashboard.
 
 <table>
 <tr valign="top">
@@ -386,14 +404,16 @@ shows you. It is part of the clone, not of the package.
 
 Phases 1–9 are built and merged: loop runner, worktree engine, gates, state and
 analytics, dashboard, self-extension, cross-provider judges, hardening. Phase 10
-is half in: `smith daemon` watches the factory in the background and its ops
+is half in: `bs daemon` watches the factory in the background and its ops
 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.3.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
+The CLI is on npm as `@juzser/blacksmith`, at `0.5.0`. Two binaries are
+the ones you run: `bs`, and `bs-run` (since `0.2.0`), which runs a rendered
+turn on a `cli` harness such as Codex. `bs-prompt-hook` is the lean hook
+entry that records operator prompts. `smith` and `smith-run` remain as
+deprecated aliases. `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
@@ -423,8 +443,9 @@ version in
 | [`docs/specs/audit-command-scope.md`](docs/specs/audit-command-scope.md) | What `/bs audit` promises an audited project, and why |
 | [`docs/specs/plugin-port-scope.md`](docs/specs/plugin-port-scope.md) | How `/bs` runs without a clone, and what the plugin leaves behind |
 | [`docs/guide/dashboard.md`](docs/guide/dashboard.md) | The dashboard tour |
+| [`docs/guide/mods.md`](docs/guide/mods.md) | The optional bs-mod HUD and pr-mod |
 | [`docs/runbooks/providers.md`](docs/runbooks/providers.md) | Setting up the cross-provider judges |
-| [`docs/runbooks/ops.md`](docs/runbooks/ops.md) | Running `smith daemon` unattended |
+| [`docs/runbooks/ops.md`](docs/runbooks/ops.md) | Running `bs daemon` unattended |
 | [`docs/README.md`](docs/README.md) | Everything else, one line each |
 
 Agents read [`AGENTS.md`](AGENTS.md) and [`CLAUDE.md`](CLAUDE.md) instead — this

package/factory/orchestrator/dist/agentNames.js

@@ -0,0 +1,43 @@
+/**
+ * The one place a role becomes a Claude Code subagent name, a template file
+ * name, and back. The role (`coder`) is data everywhere else: events,
+ * policies, ledgers, env names. Only the subagent carries the `bs-` prefix,
+ * so that it cannot collide with another plugin's or a user's `coder`.
+ */
+export const AGENT_PREFIX = 'bs-';
+/** `coder` -> `bs-coder`: what `subagent_type` and a template's `name:` carry. */
+export function agentNameFor(role) {
+    return `${AGENT_PREFIX}${role}`;
+}
+/** `coder` -> `bs-coder.md`: the template file under `.claude/agents/`. */
+export function templateFileFor(role) {
+    return `${agentNameFor(role)}.md`;
+}
+/** `bs-coder.md` -> `coder`; null for a file that is not a `bs-<role>.md` template. */
+export function roleOfTemplateFile(file) {
+    if (!file.endsWith('.md'))
+        return null;
+    return roleOfAgentType(file.slice(0, -'.md'.length), { bareAccepted: false });
+}
+/**
+ * What Claude Code puts in a hook's `agent_type` or a dispatch's
+ * `subagent_type` -> the role. Strips an optional `<namespace>:` and then the
+ * `bs-` prefix. For one transition the bare pre-prefix name (`reviewer`,
+ * `blacksmith:reviewer`) is accepted too, because a newer CLI can run with an
+ * older plugin still installed. Returns a *candidate* role, not a verified one:
+ * any other non-empty name (`general-purpose`) comes back as itself, so the
+ * caller must check the result against its own role set. Null only for an
+ * empty name, a bare `bs-` or `<ns>:`, or (with `bareAccepted: false`) a name
+ * without the prefix.
+ */
+export function roleOfAgentType(agentType, options = {}) {
+    const colon = agentType.lastIndexOf(':');
+    const name = colon === -1 ? agentType : agentType.slice(colon + 1);
+    if (name.startsWith(AGENT_PREFIX)) {
+        const role = name.slice(AGENT_PREFIX.length);
+        return role.length > 0 ? role : null;
+    }
+    if (options.bareAccepted === false)
+        return null;
+    return name.length > 0 ? name : null;
+}

package/factory/orchestrator/dist/agents-registry.js

@@ -289,15 +289,22 @@ export function foldAgents(events) {
         if (record.event_type === ERROR_EVENT_TYPE) {
             const payload = record.payload;
             // `task_ref` is this event's own spelling; eventTaskId covers the two
-            // the rest of the log uses (D-245).
+            // the rest of the log uses (D-245). `agent_role` is the dispatch's own
+            // key and this event's usual spelling, but a hand-written one may only
+            // carry `agent` (the Result file's spelling), so either key alone still
+            // finds the role -- `agent_role` tried first because it was already
+            // this fold's only key before `agent` was added as a fallback, same
+            // reason task-result-recorded above tries `agent` first for its own
+            // history; not the same order, because each fold keeps its own.
             const taskId = eventTaskId(record) ?? payload.task_ref;
+            const role = payload.agent_role ?? payload.agent ?? null;
             if (taskId) {
-                closeOpen(open, taskId, payload.agent_role ?? null, event_id, record.ts, 'error');
+                closeOpen(open, taskId, role, event_id, record.ts, 'error');
             }
-            else if (payload.agent_role) {
+            else if (role) {
                 // Only with a role: a session-level error names nobody, and every
                 // epic-level agent stays where it was.
-                closeOpenEpicLevel(openEpicLevel, record.session_id, payload.agent_role, payload.epic_id, event_id, record.ts, 'error');
+                closeOpenEpicLevel(openEpicLevel, record.session_id, role, payload.epic_id, event_id, record.ts, 'error');
             }
             continue;
         }