@juzser/blacksmith 0.1.0 → 0.2.0

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

@@ -0,0 +1,267 @@
+# `/bs run` — the wave playbook
+
+Steps 2-10 of the loop [`run.md`](run.md) opens at step 1. That file is
+the epic tier: it admits one wave and closes the epic. This file is the
+wave tier — worktrees to merge queue, one wave — and it is meant to be
+thrown away when the wave lands.
+
+**Read the console first.** `SKILL.md` and [`dispatch.md`](dispatch.md)
+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.
+
+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
+stop at 10 because the epic's own gates resume there. Nothing in this file
+decides what the next wave is, and nothing in it closes an epic.
+
+## You own the log for what you dispatch
+
+This playbook runs in one of two shapes, and is written to be correct in
+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
+  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).
+
+Which `<event-id>` depends on how you were started, and the difference is
+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
+  `dispatch_decision` that dispatched you, the event id handed to you with
+  the wave. `smith 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
+  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.
+
+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
+none of those verbs can see your work: they will not error, they will answer
+about a wave that appears never to have run.
+
+**What you are handed**, and carry through every command below: the project
+directory, the epic id, the live plan path, the admitted task ids, the
+effort `profile` the epic resolved once at the top of its run, the session
+id you write to, and the event id to hang the first dispatch off as
+`--causal-parent`.
+
+**What you hand back** when the wave lands: each task's terminal state, the
+merge-queue outcome, every finding raised with its severity, any escalation
+that reached the operator, and — if you opened one — the wave session id and
+its last event id, so the epic session goes on chaining from where you
+stopped.
+
+## Run the whole wave at once
+
+The wave is the unit of work, not the task. Three rules follow, and they are
+the difference between a factory and a queue with extra steps:
+
+- **One message, many dispatches.** When steps 3–7 reach a phase, issue
+  that phase for *every* task in the wave as parallel tool calls in a
+  single message. Five coders in one message is five agents working; five
+  messages of one coder is five agents waiting. The worktrees are
+  disjoint by construction — that is what step 1's `wave check` certified
+  before you were handed the wave — so there is nothing for them to
+  collide over.
+- **No lockstep barrier.** Each task walks 3 → 7 at its own pace. Do not
+  hold a finished coder until its neighbours finish theirs; dispatch its
+  tester the moment it returns. Waiting for the slowest task at every
+  phase boundary costs the wave the difference between its longest task
+  and the sum of its phases, which is most of what parallelism buys.
+- **A blocked task blocks itself.** Gate outcome `blocked` bounces to
+  *that* task's coder (step 9) while its neighbours carry on. One task
+  escalating to the operator does not stop the other four; report it and
+  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
+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
+   <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.
+   - `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
+     not a `small` epic — raise the tier rather than dispatching anyway.
+   - `profile.preCodeUiux` gates the uiux spec, and is `when-ui-criterion` at
+     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>`
+     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
+   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
+   coverage and epic-level e2e/screenshots.
+   - 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
+     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
+   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).
+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
+   --findings findings.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).
+   - `--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
+     `failed_criteria` is what you hand back to the coder.
+   - Name a check `coverage` and the gate reads
+     `coverage/coverage-summary.json` instead of scraping the text table,
+     which hides every file at 100% — including the file the task exists 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
+     <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
+     mandate) — never skip the adversarial stage on an S1/S2 finding
+     (`crosscheck.yml` `asymmetric_roles`). Which findings that covers is
+     `profile.verifierSeverities`, plus a
+     `profile.verifierS3SpotCheckRatio` sample of S3-minor: `[S1, S2]` + 0.2
+     at `huge`, `[S1, S2]` + 0 at `medium`, `[S1]` + 0 at `small`. The S3
+     sample is a calibration measurement on the reviewer, so it is the first
+     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
+     fire — never per-task by default. Ask, do not recall:
+     `smith 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`
+     ("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
+     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>`
+     (`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
+     unknowable. A
+     coder that writes and runs its own tests grades itself and every gate
+     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
+   worktree dispatch also carries the open-findings block for that task
+   (`smith 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.
+9. Gate outcome `blocked` → bounce to the coder on the **same branch**.
+   After 2 failed rounds on the same task, escalate model tier
+   automatically (mid → frontier, logged — `budgets.yml`
+   `escalation_ladder`); after 3, escalate to the operator. Never skip a
+   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
+   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
+    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
+    still imports — **or a broken promise**: a file the spec's
+    `keeps_exports` names lost an export or changed one's declaration.
+    Either is a bounce to the coder, not a merge; quote the `promises`
+    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
+    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
+      `conflictingFiles`, so the path is the `worktreeDir` you wrote for
+      that task in `tasks.json`; carry it into the prompt yourself.
+    - **Claims = the queue's `conflictingFiles`**, verbatim. Anything else
+      the merger touches is a claim violation like any other.
+    - 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
+      the single place a merge can happen.
+
+    `resolution: "escalated"` — low confidence, or both sides changed the
+    same logic — goes to the operator with the side-by-side. Never
+    auto-resolve a semantic conflict silently (`worktree.yml`
+    `conflict_resolution_ladder`).
+
+    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 —
+    extension is always an operator question) **or** the log is too holey to
+    rule a crossing out. Read the two numbers as what they are:
+    `measuredTokens` is a floor, never the bill (judges return findings, not
+    Results, so their tokens are in no event), and `projectedTokens` prices
+    every unmeasured dispatch at its `budgets.yml` cap. `unverifiable` with
+    `rolesWithoutCap` non-empty is a policy gap, not a spend problem: that
+    role has no cap to price it with. `unverifiable` with `tasksOverPrice`
+    non-empty means this epic has already been measured spending more on one
+    task than the projection charges an unmeasured dispatch, so its caps are
+    bounding nothing here (D-188) — the fix is to record the missing spend,
+    never to raise the cap until the number fits. Do not report an epic as
+    under budget on the strength of `measuredTokens` alone.

package/README.md

@@ -15,12 +15,15 @@ and hands you exactly one pull request.
 ![TypeScript](https://img.shields.io/badge/TypeScript-1f1f1f)
 
 **[Features](#features) · [Install](#install) · [Using it](#using-it) ·
-[How it works](#how-it-works) · [Safety](#safety) · [Status](#status) ·
-[Docs](#docs)**
+[How it works](#how-it-works) · [Safety](#safety) ·
+[Dashboard](#the-dashboard) · [Status](#status) · [Docs](#docs)**
 
-<img src="ui/e2e/__screenshots__/phase-6b/overview-desktop-dark.png" width="900" alt="Blacksmith Overview page: a 'Needs you' banner reading '1 waiver pending, 1 task escalated', counters for active agents, budget used, epics in flight and alerts, and a 'Now running' list of two live sessions" />
+<pre>
+goal → contracts you sign → one worktree per contract, run in parallel
+     → schema · tests · reviewer · verifier → one pull request you merge
+</pre>
 
-<sub>The one screen that asks something of you. The rest is the factory reporting in.</sub>
+<sub>Two touchpoints. Everything between them runs unattended.</sub>
 
 </div>
 
@@ -55,12 +58,7 @@ the moment you sign it and versioned in the event log, so a worker cannot
 quietly reinterpret the job. No contract, no dispatch.
 
 </td>
-<td width="50%"><img src="ui/e2e/__screenshots__/phase-6b/task-detail-desktop-dark.png" width="100%" alt="Task detail page for epic-9/task-3 showing a Spec contract card with case, origin, epic, plan version and claims, and an Attempts list naming each agent, provider and outcome" /></td>
-</tr>
-
-<tr valign="top">
-<td><img src="ui/e2e/__screenshots__/phase-6b/flow-desktop-dark.png" width="100%" alt="Flow page: task cards arranged in three columns labelled Wave 0 (6 tasks), Wave 1 (2 tasks) and Wave 2 (1 task), joined by dashed dependency edges" /></td>
-<td>
+<td width="50%">
 
 **Workers that cannot collide**
 
@@ -75,21 +73,6 @@ instead. An edit outside a claim fails the gate rather than reaching the queue.
 <tr valign="top">
 <td>
 
-**A frontier planner, cheap workers**
-
-Planning and judgment go to a frontier model; the bulk of the work goes to
-small, fast tiers, many at once. Every session and every live agent is visible
-with the tier that drew it, and analytics breaks cost down per task, per tier
-and per provider.
-
-</td>
-<td><img src="ui/e2e/__screenshots__/phase-6b/sessions-desktop-dark.png" width="100%" alt="Sessions page: two session cards, sess-fixture and sess-multiproject-fixture, joined by dashed edges to six live agent cards labelled coder - small, coder - mid and planner - frontier, each marked working" /></td>
-</tr>
-
-<tr valign="top">
-<td><img src="ui/e2e/__screenshots__/phase-6b/kanban-desktop-dark.png" width="100%" alt="Kanban board with Todo, In progress, Reviewing and Blocked columns; cards carry severity chips such as S2-major and agent chips such as coder - mid" /></td>
-<td>
-
 **Gates decide what merges, not confidence**
 
 Schema check → tests → coverage evidence → a fresh-context reviewer that never
@@ -98,41 +81,46 @@ the reviewer. S1 stops the line, S2 bounces back to the same branch, S3 batches
 into one waiver question per epic. Only S3 and S4 are ever waivable.
 
 </td>
-</tr>
-
-<tr valign="top">
 <td>
 
 **A second opinion from another vendor**
 
 The factory grades its own judgment calls against models from a different
 vendor — Codex over its CLI, DeepSeek over its API, beside the native Claude
-judge. They ship switched off — which of them a machine can actually
-call is a fact about that machine, not about this repo — and the one you
-switch on arrives in **shadow mode**: every verdict recorded, none of them
-gating anything, until you have read the numbers and promoted it
-deliberately.
+judge. Both external judges ship `enabled: auto`: they join the quorum on a
+machine that holds the credentials and are skipped on one that does not, so
+which of them you get is a fact about your machine, not about this repo. A
+judge earns its vote in **shadow mode** first — every verdict recorded, none
+of them gating anything — and is promoted only once you have read the numbers.
 
 </td>
-<td><img src="ui/e2e/__screenshots__/phase-6b/analytics-desktop-dark.png" width="100%" alt="Analytics page with throughput, cost-per-task, same-mistake-rate and recheck-pass-rate cards, bar charts of cost by model tier and by provider, and a cross-check quorum panel" /></td>
 </tr>
 
 <tr valign="top">
-<td><img src="ui/e2e/__screenshots__/phase-6b/lessons-desktop-dark.png" width="100%" alt="Lessons page listing lesson candidates with scope and status chips, each with approve and reject actions" /></td>
 <td>
 
 **It learns from its own errors**
 
 Errors are classified against a taxonomy, and a scribe distills them into
 lesson candidates you approve or reject. Approved lessons splice into later
-prompts — and the same-mistake rate on the analytics page tells you whether
-that is actually working. A loop you can audit, not a memory you have to trust.
+prompts — and the same-mistake rate tells you whether that is actually
+working. A loop you can audit, not a memory you have to trust.
+
+</td>
+<td>
+
+**A frontier planner, cheap workers**
+
+Planning and judgment go to a frontier model; the bulk of the work goes to
+small, fast tiers, many at once. Every session and every live agent is visible
+with the tier that drew it, and cost breaks down per task, per tier and per
+provider.
 
 </td>
 </tr>
 
 <tr valign="top">
-<td>
+<td colspan="2">
 
 **The log is the source of truth**
 
@@ -142,67 +130,93 @@ the entire database from the log alone. Nothing the factory did exists only in
 a chat transcript.
 
 </td>
-<td><img src="ui/e2e/__screenshots__/phase-6b/timeline-desktop-dark.png" width="100%" alt="Timeline page: an event list filtered by Prompts, Dispatches, Gate events, Scheduler and Errors chips, showing task-added, user_prompt and session-start entries with timestamps and task ids" /></td>
 </tr>
 </table>
 
 **Also in the box**
 
-- **Eleven dashboard pages**, dark and light, desktop and mobile: errors by
-  taxonomy category, roadmap progress joined to real task and token counts, and
-  per-project scoping. It binds to `127.0.0.1` and is read-only — clicking
-  nothing there dispatches an agent.
 - **Project scaffolding.** `/bs new <project>` generates a target project from
   the stack you answered for at install time; `/bs mcp` layers an MCP surface
   onto it.
+- **An audit that ends in an epic.** `/bs audit <project-dir>` reads a project
+  that already exists on four axes, ranks what it finds, and cuts one epic from
+  what you accept.
 - **A factory that extends itself.** New agent roles, policies and taxonomy
   values are data files, not code — see
   [extending](docs/guide/extending.md).
 - **One integration branch per epic**, one pull request at the end, merged by
   you.
+- **A local dashboard**, eleven read-only pages over the same event log —
+  optional, and [further down](#the-dashboard).
 
 ## Install
 
+Say **"install Blacksmith"** to a Claude Code session and it does the whole
+thing: [`INSTALL.md`](INSTALL.md) is an executable runbook, and it stops to ask
+before anything that touches your machine.
+
+By hand it is one command in a shell:
+
 ```bash
-git clone https://github.com/juzser/blacksmith.git && cd blacksmith
-pnpm install --frozen-lockfile
-pnpm run build                          # tsc -> factory/orchestrator/dist/
-node factory/orchestrator/dist/cli.js --help
+npm i -g @juzser/blacksmith
 ```
 
-Verify it with the same gate CI runs (this one also needs `python3` + PyYAML):
+and two inside Claude Code:
 
-```bash
-bash scripts/check.sh                   # ends in `== PASS ==` on a good install
+```
+/plugin marketplace add juzser/blacksmith
+/plugin install blacksmith@blacksmith
 ```
 
-Driving a real epic additionally needs the **Claude Code CLI** — the planner and
-every worker run as Claude Code sessions.
+Then `smith 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
+that root if you want one home for several projects. You now have `/bs`.
 
-**Rather not do this by hand?** Open a Claude Code session in the clone and say
-*"install Blacksmith"*. [`INSTALL.md`](INSTALL.md) is an executable runbook: it
-asks before touching anything outside the clone, and it doubles as the human
-version — per-platform setup (macOS, Debian/Ubuntu, Fedora, Alpine, WSL2),
-troubleshooting, and the known platform gaps stated rather than papered over.
+**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
+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
+directory, which the next `npm i` replaces.
 
-### From npm
+<details>
+<summary><b>A clone instead — the whole factory</b></summary>
 
-The CLI alone is also on the registry as
-[`@juzser/blacksmith`](https://www.npmjs.com/package/@juzser/blacksmith):
+A clone is for hacking on Blacksmith itself, and for the two things an install
+does not carry: the dashboard and this repo's own enforcement.
 
 ```bash
-npx @juzser/blacksmith --help          # one-off
-npm i -g @juzser/blacksmith && smith --help
+git clone https://github.com/juzser/blacksmith.git && cd blacksmith
+pnpm install --frozen-lockfile
+pnpm run build                          # tsc -> factory/orchestrator/dist/
+bash scripts/check.sh                   # the gate CI runs; ends in `== PASS ==`
 ```
 
-That package is the `smith` binary plus everything it reads at runtime — the
-policies, the JSON Schemas, the scaffold templates, the agent role files, the
-database migrations. It is **not** the whole factory: the `/bs` console, the
-dashboard, the docs and the roadmap stay in the clone, and a registry install
-keeps its state (`state/`, `factory/specs/active/`) under its own install
-directory rather than beside the project it is working on. Driving an epic
-still means a Claude Code session opened in a clone. Take the package when you
-want `smith` on a machine without a clone; take the clone for everything else.
+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
+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.
+
+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.
+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
+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).
+
+`INSTALL.md` Part 2 is the long form of the clone above: per-platform
+setup (macOS, Debian/Ubuntu, Fedora, Alpine, WSL2), the stack interview,
+troubleshooting, and the known platform gaps stated rather than papered over.
+
+</details>
 
 ## Using it
 
@@ -286,15 +300,16 @@ 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 |
 
-Underneath, every one of those is a `smith` command you can run yourself —
-`smith --help` lists them all.
+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
+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
+playbooks are read from a clone.
 
 → **[The operator loop](docs/guide/operator-loop.md)** — the six steps, in the
 order you meet them.<br />
 → **[Operator guide](docs/guide/operator-guide.md)** — the same ground with real
-commands and real output.<br />
-→ **[The dashboard](docs/guide/dashboard.md)** — what each of the eleven pages
-shows you.
+commands and real output.
 
 ## How it works
 
@@ -334,6 +349,39 @@ runs, plus branch protection — not by trust. Full rules:
 Found a vulnerability? [`SECURITY.md`](SECURITY.md) — report privately, not in
 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.
+
+<table>
+<tr valign="top">
+<td width="50%"><img src="ui/e2e/__screenshots__/phase-6b/overview-desktop-dark.png" width="100%" alt="Blacksmith Overview page: a 'Needs you' banner reading '1 waiver pending, 1 task escalated', counters for active agents, budget used, epics in flight and alerts, and a 'Now running' list of two live sessions" /><br /><sub><b>Overview</b> — the one screen that asks something of you.</sub></td>
+<td width="50%"><img src="ui/e2e/__screenshots__/phase-6b/task-detail-desktop-dark.png" width="100%" alt="Task detail page for epic-9/task-3 showing a Spec contract card with case, origin, epic, plan version and claims, and an Attempts list naming each agent, provider and outcome" /><br /><sub><b>Task detail</b> — the contract, and every attempt against it.</sub></td>
+</tr>
+<tr valign="top">
+<td><img src="ui/e2e/__screenshots__/phase-6b/flow-desktop-dark.png" width="100%" alt="Flow page: task cards arranged in three columns labelled Wave 0 (6 tasks), Wave 1 (2 tasks) and Wave 2 (1 task), joined by dashed dependency edges" /><br /><sub><b>Flow</b> — waves and the dependency edges that shaped them.</sub></td>
+<td><img src="ui/e2e/__screenshots__/phase-6b/kanban-desktop-dark.png" width="100%" alt="Kanban board with Todo, In progress, Reviewing and Blocked columns; cards carry severity chips such as S2-major and agent chips such as coder - mid" /><br /><sub><b>Kanban</b> — what is moving, and what is stuck and why.</sub></td>
+</tr>
+<tr valign="top">
+<td><img src="ui/e2e/__screenshots__/phase-6b/sessions-desktop-dark.png" width="100%" alt="Sessions page: two session cards, sess-fixture and sess-multiproject-fixture, joined by dashed edges to six live agent cards labelled coder - small, coder - mid and planner - frontier, each marked working" /><br /><sub><b>Sessions</b> — every live agent and the tier that drew it.</sub></td>
+<td><img src="ui/e2e/__screenshots__/phase-6b/analytics-desktop-dark.png" width="100%" alt="Analytics page with throughput, cost-per-task, same-mistake-rate and recheck-pass-rate cards, bar charts of cost by model tier and by provider, and a cross-check quorum panel" /><br /><sub><b>Analytics</b> — cost per task, per tier, per provider, and the same-mistake rate.</sub></td>
+</tr>
+<tr valign="top">
+<td><img src="ui/e2e/__screenshots__/phase-6b/lessons-desktop-dark.png" width="100%" alt="Lessons page listing lesson candidates with scope and status chips, each with approve and reject actions" /><br /><sub><b>Lessons</b> — candidates waiting on your approve or reject.</sub></td>
+<td><img src="ui/e2e/__screenshots__/phase-6b/timeline-desktop-dark.png" width="100%" alt="Timeline page: an event list filtered by Prompts, Dispatches, Gate events, Scheduler and Errors chips, showing task-added, user_prompt and session-start entries with timestamps and task ids" /><br /><sub><b>Timeline</b> — the append-only log itself, filtered.</sub></td>
+</tr>
+</table>
+
+Dark and light, desktop and mobile; errors by taxonomy category, roadmap
+progress joined to real task and token counts, and per-project scoping.
+
+→ **[The dashboard](docs/guide/dashboard.md)** — what each of the eleven pages
+shows you. It is part of the clone, not of the package.
+
 ## Status
 
 Phases 1–9 are built and merged: loop runner, worktree engine, gates, state and
@@ -341,8 +389,16 @@ analytics, dashboard, self-extension, cross-provider judges, hardening. Phase 10
 is half in: `smith 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. And the CLI is on npm as `@juzser/blacksmith` — the binary and
-what it reads, not the console or the dashboard, which still run from a clone.
+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
+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
+clone; a plugin is what would move `/bs`, and it is
+[scoped, not cut](docs/specs/plugin-port-scope.md).
 
 The one thing to know up front: **the daemon watches, it does not drive.** It
 tells you what the factory needs — budget alarms, agents that never came back,
@@ -352,7 +408,7 @@ and nothing advances.
 
 → **[What is built, what is not](docs/guide/status.md)**, and the unflinching
 version in
-[Limitations today](docs/guide/operator-guide.md#limitations-today).
+[Limitations today](docs/guide/operator-guide/limitations.md#limitations-today).
 
 ## Docs
 
@@ -361,11 +417,12 @@ version in
 | [`INSTALL.md`](INSTALL.md) | Getting it running, per platform |
 | [`docs/guide/operator-loop.md`](docs/guide/operator-loop.md) | The six steps you actually do |
 | [`docs/guide/operator-guide.md`](docs/guide/operator-guide.md) | Every command, end to end, with output |
-| [`docs/guide/dashboard.md`](docs/guide/dashboard.md) | The dashboard tour |
 | [`docs/guide/status.md`](docs/guide/status.md) | What is real today |
 | [`docs/guide/extending.md`](docs/guide/extending.md) | Adding agents, policies, taxonomy values |
 | [`docs/specs/black-smith-architecture.md`](docs/specs/black-smith-architecture.md) | Why it is shaped this way |
 | [`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/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/README.md`](docs/README.md) | Everything else, one line each |

package/factory/orchestrator/dist/actors.js

@@ -17,9 +17,10 @@
 // - 'user' — what waivers.ts, lessons.ts and prompts.ts default to when no
 //   actor is supplied, which is how every decision made through the UI is
 //   attributed (ui/server never passes one).
-// - 'operator' — what docs/guide/operator-guide.md and .claude/skills/bs/
-//   SKILL.md hand the operator, in all six of their `--actor` examples,
-//   including the `smith waivers apply` line that writes waiver-granted.
+// - 'operator' — what docs/guide/operator-guide/*.md and .claude/skills/bs/
+//   SKILL.md hand the operator, in every `--actor` example they carry (three
+//   today), including the `smith waivers apply` line in
+//   severity-and-budget.md that writes waiver-granted.
 // - 'operator-skill' — what the operator's own console passes; 467 of the 668
 //   recorded events carry it. It is a skill rather than a person, and it is
 //   here anyway: it acts only on a turn the operator took, and the decision