@juzser/blacksmith 0.3.0 → 0.5.0

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

@@ -15,19 +15,33 @@ epic. "Hand the wave over" below says how, and says the one thing that makes
 it safe.
 
 Ask the epic's effort tier once, at the top of the run, and keep the answer
-for the whole epic — `smith effort show --plan
+for the whole epic — `bs effort show --plan
 factory/specs/active/<epic>/plan-vN.json`. Step 13 here, and steps 3, 6 and 7
 of the wave playbook, each name the `profile` field that scales them; nothing
 else in either file moves. Read `effective`, not `requested`: a plan whose
 live tasks fire a security trigger is floored, and running it at the tier the
 file asked for would be running it below the floor.
 
+Ask the cross-provider gate once too, at the top of the run and before any
+wave is admitted — `bs judge preflight --project <project-dir>`, the same
+call INSTALL.md makes at setup. When it reports the gating pool cannot
+decide (fewer active external providers than `quorum_rule.min_providers`
+after OpenRouter substitution, or a provider the project's own
+`.blacksmith/crosscheck.yml` names but this box cannot reach), STOP and ask
+the operator before admitting a wave — per `.claude/skills/bs/SKILL.md`'s
+"Talking to the operator" rules (options carry a confidence %; not restated
+here): add an OpenRouter key, add a model, pick which providers to run with,
+or continue without cross-check. Skipping this is not a shortcut — steps 15
+and 16 spend a real judge call to find the same gap mid-run, after the epic's
+work is already done. Full substitution and precedence mechanism:
+docs/runbooks/providers.md §9d.
+
 1. Ask the graph how wide this wave can be, then ask the gate whether it may
    be that wide. Two commands, two different questions — do not skip to the
    second with a set you picked by eye.
 
    ```bash
-   smith wave next factory/specs/active/<epic>/plan-vN.json \
+   bs wave next factory/specs/active/<epic>/plan-vN.json \
      --session <session-id> --repo <project-dir>
    ```
 
@@ -46,7 +60,7 @@ file asked for would be running it below the floor.
 
    Then put that proposal through the gate that actually admits it:
 
-   `smith wave check factory/specs/active/<epic>/plan-vN.json <task-id>...`
+   `bs wave check factory/specs/active/<epic>/plan-vN.json <task-id>...`
    — claims must be pairwise disjoint and share no `worktree.yml`
    `serialize_always_globs` hotspot. A violation means cut a dependency
    edge and run the pair serially instead of forcing the wave.
@@ -66,6 +80,16 @@ file asked for would be running it below the floor.
      operator's call. So a proposed wave can still be refused here. That is
      the gate working, not the proposal being wrong — drop tasks from the
      tail of `wave` and re-check.
+   - With `--session`, `wave check` admits only live tasks of an ingested
+     plan. A plan version whose tasks the log never saw is refused
+     `cli.plan-not-ingested`: run `bs plan ingest` on it, then re-check.
+     An id with no task row is refused `plan.unknown-task`, and a task
+     that is `completed`, `superseded` or `waived` is refused
+     `cli.task-not-live`, naming each task and its status. Drop those ids.
+     A `failed` or `escalated` task stays admissible: an operator still
+     holds it, and the escalation ladder re-admits it. A follow-up
+     `findings raise` minted stays admissible while it is live, and a wave
+     of follow-ups alone still needs the plan it names ingested first.
    - Never narrow a wave because a narrow one feels safer. A wave of one
      passes every check in this file — one task is disjoint with nothing,
      shares a hotspot with nothing, crosses no import edge — so `valid: true`
@@ -84,9 +108,9 @@ would cost:
 - **Inline**, in this session, when the wave is small enough for this
   window. Read `wave.md` and work it here.
 - **In a session of its own**, when it is not, but you still want to drive
-  it yourself: `smith session start <wave-id> --continues <session-id>#<n>`,
+  it yourself: `bs session start <wave-id> --continues <session-id>#<n>`,
   where `<n>` is the index of the event that admitted this wave.
-- **Dispatched**, as the **`wave-runner`** agent, when the wave would eat
+- **Dispatched**, as the **`bs-wave-runner`** agent, when the wave would eat
   the window this epic needs to reach its own end. It is the only role
   `factory/policies/delegation.yml` grants `Agent`, and it earns that by
   opening its own log first — so hand it the event id of *your dispatch*,
@@ -106,12 +130,12 @@ to make (D13, D-266). What it does not buy is a shortcut. A wave session
 opened without `--continues` writes into a log nothing here reads, and the
 verbs below then report a wave that appears never to have run rather than
 failing — which is the same silence, arriving as a green. When you dispatched
-the wave rather than ran it, `smith delegation check <session-id>` is what
+the wave rather than ran it, `bs delegation check <session-id>` is what
 turns that silence into a red: a `wave-runner` that dispatched before opening
 its log, or against the wrong event, is `unverifiable` and exits 1.
 
 **Then check that it did.** Once the wave's tasks reach a terminal state,
-`smith wave audit --session <id> --epic <epic>` reads the log back and
+`bs wave audit --session <id> --epic <epic>` reads the log back and
 reports the width the wave actually ran at, not the width it was admitted
 at. Ask it with *this* session: it folds the lineage, so it sees the
 dispatches a wave session made under the admission this one wrote. Exit `1`
@@ -123,8 +147,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 **`bs-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
@@ -132,7 +157,7 @@ playbooks are written to prevent.
     on it**, whichever step cut it:
 
     ```bash
-    smith plan ingest factory/specs/active/<epic>/plan-v<n+1>.json \
+    bs plan ingest factory/specs/active/<epic>/plan-v<n+1>.json --project <project-dir> \
       --session <session-id> --plan-version <n+1> --causal-parent <event-id>
     ```
 
@@ -147,11 +172,11 @@ playbooks are written to prevent.
     branch**. Every gate up to here ran inside a task worktree, so every
     green you have so far is a green about a worktree — the envkit epic
     shipped six green lint gates on a branch whose `pnpm lint` exited 1
-    (D-42). Check out `smith/<epic>/integration` in the project first (this
+    (D-42). Check out `bs/<epic>/integration` in the project first (this
     command refuses to move your working tree, and refuses a dirty one):
 
     ```bash
-    smith integration check --epic <epic> --project <project-dir> \
+    bs integration check --epic <epic> --project <project-dir> \
       --checks <checks.json> \
       --session <session-id> --plan-version <n> --causal-parent <event-id>
     ```
@@ -167,25 +192,35 @@ playbooks are written to prevent.
     check, the review and the close all claim to have verified a plan that
     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
+    check, passed the flag, said v3. Read the version off `bs plan ingest`'s receipt and
     pass it every time.
-13. Dispatch the **`spec-reviewer`** again — this time against the code.
+13. Dispatch the **`bs-spec-reviewer`** again — this time against the code.
     The pre-code review at `/bs plan` step 3 read the spec against nothing;
     this one reads it against the assembled branch, which is the only reading
     that can see a criterion the finished code proves wrong. The envkit epic
     deadlocked on exactly that: a correct S2 whose fix criterion 3 mandated
     and criterion 1 forbade (D-33). It writes to a close-specific path so it
-    cannot clobber the pre-code artifact; hand that file — each item naming the
+    cannot clobber the pre-code artifact. Put
+    `Declared artifact: /abs/path/to/state/results/<epic>.spec-review-close-vN.json`
+    inline on its own line in the dispatch prompt (the PreToolUse guard refuses
+    a judge dispatch without it); hand that file — each item naming the
     `criterion_ref` it is against — to:
 
     ```bash
-    smith epic spec-review --epic <epic> --project <project-dir> \
+    bs epic spec-review --epic <epic> --project <project-dir> \
       --plan factory/specs/active/<epic>/plan-vN.json \
       --reviewed-by spec-reviewer \
-      [--evidence state/results/<epic>.spec-review-close-vN.json] \
+      --evidence state/results/<epic>.spec-review-close-vN.json \
       --session <session-id> --plan-version <n> --causal-parent <event-id>
     ```
 
+    `--evidence` is required unless you pass `--no-findings` instead, and
+    the two are exclusive: a reviewer that found nothing writes `[]` to that
+    path, and `--no-findings` is the operator attesting a review that ran
+    outside the factory — recorded as `attested_by: operator`, never read as
+    a file. A missing flag is refused (`cli.missing-flag`), because an empty
+    review read from an absent file is how a capped reviewer closed clean.
+
     Its `dispatch_decision` — and step 14's, and the planner's when it
     renders a verdict — goes against the reserved `<epic>/integration` ref,
     never a `<epic>/spec-review-rN` you coin for the occasion
@@ -204,12 +239,12 @@ playbooks are written to prevent.
     distinguishes them. It
     exits 0 even when it raises findings: what it found blocks the plan, not
     this command. A spec finding is unwaivable at S1/S2 and no task's diff can
-    contain the fix, so the answer is `smith plan amend --plan … --findings …
+    contain the fix, so the answer is `bs plan amend --plan … --findings …
     --rationale … --sites …` (§6a of the operator guide). `--sites` is every
     place that shape occurs, not only the file the finding was reported
     against — answer it before writing the changes, because it is the question
     that decides how much the amendment fixes (D-123). It cuts plan v(n+1):
-    ingest it (step 11's `smith plan ingest`), go back to step 11 with the new
+    ingest it (step 11's `bs plan ingest`), go back to step 11 with the new
     version, and re-run this review against the branch that results. Never
     record a spec defect as a coder failure; that is
     the deadlock this step exists to end.
@@ -220,20 +255,22 @@ playbooks are written to prevent.
     did not write. Get the clause list first (read-only, no event):
 
     ```bash
-    smith epic goal --epic <epic>
+    bs epic goal --epic <epic>
     ```
 
-    Hand those clauses and the live plan to a **`spec-reviewer`** session —
+    Hand those clauses and the live plan to a **`bs-spec-reviewer`** session —
     a fresh one, never the planner's, and never the same dispatch as step 13:
-    `smith dispatch check` refuses to let one dispatch answer for both.
+    `bs dispatch check` refuses to let one dispatch answer for both.
     Dispatch it *after* step 13's record is written, not alongside it — a
     dispatch that predates the previous record has already answered for that
     one, so two sessions fired up front leave this record unaccounted for and
-    `smith dispatch check` reports that record `unverifiable`. Take back one
-    verdict per clause, in the goal's order, and record it:
+    `bs dispatch check` reports that record `unverifiable`. Take back one
+    verdict per clause, in the goal's order, and record it. Its prompt carries
+    `Declared artifact: /abs/path/to/state/results/<epic>.goal-coverage-vN.json`
+    inline on its own line, for the same reason:
 
     ```bash
-    smith epic goal-check --epic <epic> \
+    bs epic goal-check --epic <epic> \
       --plan factory/specs/active/<epic>/plan-vN.json \
       --coverage state/results/<epic>.goal-coverage-vN.json \
       --checked-by spec-reviewer \
@@ -243,8 +280,8 @@ playbooks are written to prevent.
     `covered` must name live plan task ids; `out-of-scope` must give a reason,
     and that reason is quoted back to the epic judge. `uncovered` mints an
     S2-major spec finding against the plan file — no task diff can contain
-    that fix, so the answer is `smith plan amend`, which cuts v(n+1) and sends
-    you back to step 11 — through `smith plan ingest`, as in step 13. The
+    that fix, so the answer is `bs plan amend`, which cuts v(n+1) and sends
+    you back to step 11 — through `bs plan ingest`, as in step 13. The
     command exits 0 even when it raises findings.
 
     **It refuses (`cli.no-epic-goal`) when the owning milestone states no
@@ -259,54 +296,155 @@ playbooks are written to prevent.
     integrable at all:
 
     ```bash
-    smith epic verdict --epic <epic> --project <project-dir> \
+    bs epic verdict --epic <epic> --project <project-dir> \
       --session <session-id> --plan-version <n> --causal-parent <event-id>
     ```
 
     Mechanical oracles first: non-terminal tasks, open blocking findings, a
-    missing/failed/stale integration-root check, a missing/stale closing spec
-    review, or a missing/stale spec-vs-goal check return `hold` (exit 1)
-    without spending a judge call. `--project` is required — the verdict
-    reads the integration branch head to decide whether the records from
-    steps 12, 13 and 14 still cover it. On `hold`, do not open the PR — report
-    the `blockers` to the operator and go back to step 11.
+    missing/failed/stale integration-root check, a closing spec review that's
+    stale or missing when the tier required one, or a missing/stale
+    spec-vs-goal check return `hold` (exit 1) without spending a judge call.
+    A tier that waived the review (step 13: `when-plan-amended` on a plan
+    still at v1) is not a hold on that ground — the verdict records the skip
+    as a fact instead of staying silent about it, same as step 13 asks. A
+    review that IS on record is still walked through every staleness check
+    regardless of tier. `--project` is required — the verdict reads the
+    integration branch head to decide whether the records from steps 12, 13
+    and 14 still cover it. On `hold`, do not open the PR — report the
+    `blockers` to the operator and go back to step 11.
 
     Once the oracles pass, the judge call is real money when an external
     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
-    (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.
+    ChatGPT quota, DeepSeek spends prepaid credit. Say which purse it is to
+    the operator before this call, not after.
+
+    Step 16 no longer pays twice for the same integration head: the
+    `quorum-decision` this call writes now carries `integration_head`, and a
+    clean `go` against an unchanged head is reused rather than re-asked
+    (issue #270). Anything that invalidates it — a new commit, a `hold`, or a
+    decision from before `integration_head` existed — still re-runs.
 16. Record the close. The verdict above is a read-only probe and writes
     nothing; `epic close` is what makes it a fact in the log (D-43):
 
     ```bash
-    smith epic close --epic <epic> --project <project-dir> \
+    bs epic close --epic <epic> --project <project-dir> \
       --session <session-id> --plan-version <n> --causal-parent <event-id>
     ```
 
-    It re-runs the verdict, then emits `epic-closed` on `go` and refuses
-    (exit 1, no event) on `hold`. **Never pass `--override-rationale`
+    It reuses step 15's `go` decision when the integration head hasn't moved
+    (see step 15), otherwise re-runs the verdict, then emits `epic-closed` on
+    `go` and refuses (exit 1, no event) on `hold`. **Never pass `--override-rationale`
     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.
-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
+    `bs 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 a scribe-written body. The head is
+    `bs/<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 — a child epic cut from `smith/<parent>/integration` opens its PR
+    first — a child epic cut from `bs/<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`).
 
+    **Build the fact pack first.** The scribe has no `Bash` and a small turn
+    cap, so it cannot run `git` or `bs`, and a scribe left to grep raw logs
+    caps and fills the gaps by invention — a wrong event id, a merged task
+    called dead, "no waivers" over two grants. Compute every fact in your own
+    session, from the epic session with `--lineage` so the waves' records
+    count. Every fact comes from the log or from git, never from the SQLite
+    projection: `stats kanban` and `stats timeline` read a projection that
+    can lag the log, and `db rebuild` clears it before it re-reads, so do
+    not refresh it for this.
+
+    ```bash
+    # one pass over the log (pass an --n that covers the whole lineage)
+    bs event tail <session-id> --lineage --n 100000
+    # the fingerprint map: finding_id, task_id and fingerprint of the epic's findings
+    bs findings list --session <session-id> --epic <epic>
+    # the goal the summary states
+    bs epic goal --epic <epic> [--roadmap-path <file>]
+    # the branch itself
+    git log --oneline <base>..bs/<epic>/integration
+    git diff --shortstat <base>...bs/<epic>/integration
+    ```
+
+    From the `event tail` pass keep, each with its `event_id`:
+    - `waiver-granted` and `waiver-denied` records whose
+      `payload.fingerprint` matches one of the epic's findings, mapped to
+      that finding's id and task. Match on the stored `fingerprint` that
+      `findings list` prints, and drop a decision that matches none: an
+      ancestor session can carry an earlier epic's decisions. Grants come
+      from here, not from
+      `findings list --status`, because a grant only moves a raised or
+      confirmed finding to `waived`; an amended or fix-verified one keeps
+      its status.
+    - `wave-merged` records: `payload.task_ids` and the event id.
+    - `epic-closed` from step 16: its event id, `machine_verdict`, and
+      `payload.summary.tasks` — each task's `task_status`, read from the log
+      at close. A follow-up cleared by closing all its findings (fixed, refuted
+      or waived) still reads `todo` there; cross-check it against the findings and never publish it
+      as an open task.
+    - `audit-resolved`, for an epic cut by `/bs audit`: every record whose
+      `payload.epic` is this epic — one epic can resolve more than once, and
+      the lineage carries a parent epic's resolve too. List each event id.
+      `fixed` and `deferred` are fingerprint arrays: fixed is the union of
+      every kept record's `fixed`; deferred is the last record's `deferred`
+      minus that union. Write the two counts into the pack yourself.
+    - `integration-check` records whose `payload.epic_id` is this epic and
+      whose `head_sha` equals the `epic-closed` record's
+      `summary.integration.check.head_sha`: each check's `name` and `pass`.
+
+    `epic goal` reads this repo's roadmap by default; when the epic's
+    roadmap lives elsewhere, pass `--roadmap-path` naming it, or the goal
+    you hand over is the wrong one. For a UI epic, take the screenshots
+    from each task's tester result, `state/results/<task-id>.tester*.json`,
+    field `artifacts` (the files sit under `state/artifacts/<task-id>/`);
+    [`docs/standards/stack.md`](../../../docs/standards/stack.md) wants
+    them on this PR. The pack carries a screenshot only as an image you
+    have uploaded or attached — never a local path, which no reviewer can
+    open; one you cannot attach stays out.
+
+    Write only these filtered facts into one pack file — never raw command
+    output, which puts the scribe back to grepping logs. Dispatch the scribe with that file as its **only source**, and the
+    PR-body scratch file as its write root, under one rule: **omit, never
+    infer**. A fact the pack does not hold stays out of the body; a count,
+    a status, or an event id is copied from the pack, never worked out. If
+    the pack is wrong, rebuild it and dispatch again; do not let the scribe
+    reach past it into `state/events/`.
+
+    The PR body opens with a short plain-language summary, written under
+    `.claude/skills/bs/SKILL.md`'s "Talking to the operator" section — cite
+    that section for how to write it, do not restate its rule here. In the
+    project's own terms, not Blacksmith's: what this epic changed, what is
+    still open, and what decision the operator must make, if any. The
+    existing fact sections below follow it as the technical part the rule
+    asks for.
+
+    The PR body has this shape and nothing else: the plain-language opening
+    above; **Summary** (the epic id
+    and its goal, one paragraph); **Tasks** (one line per task: id,
+    `task_status`, and its `wave-merged` event id when it has one);
+    **Waivers** (granted and denied, each with its finding id and event id,
+    or the word "none" only when both lists in the pack are empty);
+    **Verification** (the verdict outcome, the `epic-closed` event id, the
+    `integration-check` results, the `audit-resolved` event ids and the
+    fixed and deferred counts when there are any, the shortstat, and the
+    commit count from the log);
+    **Screenshots** (only when the pack carries them); **Timeline** (the
+    dashboard link, when you put one in the pack). The scribe's 300-word
+    cap binds the prose — Summary and the sentences around the lists; the
+    Tasks, Waivers and check lists are artifacts and are never cut to fit
+    it, since a dropped line reads as a task or waiver that was not there.
+
     Before the first push, read the authorship the branch is about to make
     public — `git log --format=%ae <base>..HEAD | sort -u` — and stop on any
     address that is not a noreply one; a coder's worktree commit carries
@@ -318,7 +456,7 @@ playbooks are written to prevent.
     Append it by hand, under the reserved ref and the live plan version:
 
     ```bash
-    smith event append '{"session_id":"<session-id>","actor":"orchestrator","event_type":"integration-pr-opened","task_id":"<epic>/integration","plan_version":<n>,"causal_parent":"<event-id>","payload":{"step":17,"pr_url":"<url>","pr_number":<n>,"repo":"<owner>/<repo>","base_ref":"<base>","head_ref":"smith/<epic>/integration","head_sha":"<sha>","base_sha":"<sha>","commits":<n>,"changed_files":<n>,"additions":<n>,"deletions":<n>}}'
+    bs event append '{"session_id":"<session-id>","actor":"orchestrator","event_type":"integration-pr-opened","task_id":"<epic>/integration","plan_version":<n>,"causal_parent":"<event-id>","payload":{"step":17,"pr_url":"<url>","pr_number":<n>,"repo":"<owner>/<repo>","base_ref":"<base>","head_ref":"bs/<epic>/integration","head_sha":"<sha>","base_sha":"<sha>","commits":<n>,"changed_files":<n>,"additions":<n>,"deletions":<n>}}'
     ```
 
     The receipt says whether the timeline reads the type; it does, and it

package/.claude/skills/bs/status.md

@@ -7,13 +7,13 @@ on demand knows only what is in the log, never whether anyone was reading it.
 
 ## 1. Ask the watcher
 
-`smith daemon status [--dir <dir>]`. It prints JSON and **exits 1 whenever a
+`bs daemon status [--dir <dir>]`. It prints JSON and **exits 1 whenever a
 current daemon is not watching** — that is the health check doing its job,
 not a command that failed, so never report the non-zero exit as an error.
-Three readings:
+Four readings:
 
 - `running: false` — nothing holds the lock. A fine steady state if the
-  operator never started one (`smith daemon start` if they want one): say so
+  operator never started one (`bs daemon start` if they want one): say so
   in a clause and go to step 2, which folds the log live anyway. What you
   must not do is render `lastTick` as though it were current.
 - `stale: true` — a daemon holds the lock and has published nothing for
@@ -24,6 +24,10 @@ Three readings:
   `<dir>/daemon.log`.
 - `running: true, stale: false` — the numbers are fresh. Say how fresh
   (`reportAgeSeconds`) rather than implying "now".
+- an `error` object with `code: "daemon.unreadable-state"` — the daemon's
+  own state is unreadable, so nobody can say whether one is running. Lead
+  with it, name the file from `error.details.path`, and pass on the
+  recovery in `error.message`. Never render it as `running: false`.
 
 When there is a `lastTick`, render its triage split before the digest below,
 because it is the only record of what happened while nobody was watching:
@@ -34,20 +38,23 @@ its own and needs no decision.
 
 ## 2. Fold the log
 
-`smith stats overview [--session <id>]`. Render the JSON as a short digest,
+`bs stats overview [--session <id>]`. Render the JSON as a short digest,
 field for field — never invent numbers the query didn't return:
 
 - **Live agents**: `liveAgents` grouped by role/model/provider,
   `liveAgentCount` as the headline (with `liveAgentCountDelta5m` as a
   ▲/▼ note).
-- **Budget**: `tokensByEpic`, called out as "X% of the 4,000,000-token epic
-  cap" (`budgets.yml`) — flag any epic ≥70% (`budgets.yml` `alarm_ratio`).
+- **Budget**: `tokensByEpic`, called out as "X% of the epic cap" — the cap
+  for the epic's effort tier in `budgets.yml` (4M small / 16M medium / 32M
+  huge; `bs budget alarm` prints the cap it judged each epic against) — flag any epic ≥70% (`budgets.yml` `alarm_ratio`).
   `tokensByEpic` counts recorded spend only, so it is a floor: say "at least
-  X%", and run `smith budget alarm <session>` for the projection that prices
+  X%", and run `bs budget alarm <session>` for the projection that prices
   the dispatches nothing recorded a Result for.
 - **In flight**: `epicsInFlight`, `recentDispatches` (last 10).
 - **Alerts**: `alerts.escalations` and `alerts.pendingWaivers` — call these
   out first if non-zero, they're what the operator came here to see.
+  `pendingWaivers` is narrower than `bs waivers pending`: only waivers on
+  finished work (completed tasks, closed epics).
 - **Milestones**: `milestoneProgress` — one line each, `%` complete.
 
 If the UI is already running, just point the operator at it instead of

package/.claude/skills/bs/ui.md

@@ -1,14 +1,30 @@
 # `/bs ui` — serve the local dashboard
 
-`smith ui serve [--port 4680] [--db state/smith.db] [--state-dir …]
-[--roadmap-path …]`. If it errors `ui.not-built`, run `pnpm build:ui`
-first (builds `ui/server/dist` + `ui/dist`), then retry, and print the local
-URL (`http://127.0.0.1:<port>`).
+`bs ui serve [--port 4680] [--db state/smith.db] [--state-dir …]
+[--roadmap-path …] [--claude-config-dir …] [--store <dir>…]`. If it errors `ui.not-built`,
+run `pnpm build:ui` first (builds `ui/server/dist` + `ui/dist`), then retry,
+and print the local URL (`http://127.0.0.1:<port>`).
+
+Besides the event log, the server reads — read-only — the local Claude Code
+session registry, transcripts and prompt history, from `--claude-config-dir`, else
+`$CLAUDE_CONFIG_DIR`, else Claude Code's default, and serves them as
+`GET /api/cli-sessions`, loopback-only.
+
+Home, Kanban and the project list also read every project with a live CLI
+session: its git toplevel is a store when `<top>/.blacksmith/state/events` or
+`<top>/state/events` exists (rechecked at most every 5 s), and `--store <dir>`
+adds one by hand. Foreign stores are strictly read; their projection lives in
+`state/ui-stores/<storeId>.db` of the served clone, kept for a grace period after a
+store drops and pruned at startup when stale. In a foreign store an untagged row reads
+as the store's label, any other explicit project as itself, so `?project=X` returns each
+matching row once. These routes and `/api/tasks/*` are local-only, like
+`/api/cli-sessions`. A foreign Kanban card opens through `?store=<storeId>`; its history,
+artifacts and waivers stay empty. Details: `docs/guide/dashboard.md`.
 
 **That build needs a clone.** `ui/` is not in the package's `files`, so an
 install — npm or plugin — ships no dashboard at all and `ui.not-built` is the
 permanent answer there, not a stale build. Check before you advise: if there
-is no `ui/` beside the `smith` you are running, say the dashboard is
+is no `ui/` beside the `bs` you are running, say the dashboard is
 clone-only and stop, rather than sending the operator to a `pnpm` script they
 do not have.
 

package/.claude/skills/bs/waivers.md

@@ -1,13 +1,89 @@
 # `/bs waivers` — answer the pending waiver batch
 
-1. `smith waivers pending <epic> --session <session-id>` — every S3/S4
+1. `bs waivers pending <epic> --session <session-id>` — every S3/S4
    finding for the epic with no waiver decision yet (a decided fingerprint
    never resurfaces).
 2. Present the whole batch to the operator as **one** question ("ignore
    these?") — never ask per-finding (architecture §11, `severity.yml`).
 3. Write the answers to `decisions.json`
    (`Array<{fingerprint, decision: "granted"|"denied", operatorNote}>`) and
-   run `smith waivers apply decisions.json --session ... --plan-version ...
+   run `bs waivers apply decisions.json --session ... --plan-version ...
    --causal-parent ... --actor operator`. S1/S2 findings are rejected by
    the command itself if attempted — they go through the escalation ladder
    instead, never a waiver.
+   Task waivers are a separate step. A task whose plan row says `waived`
+   carries no gate run, and the epic close holds it as a blocker ("waived
+   without operator approval") until the operator's approval is recorded.
+   Ask the operator, then run `bs waivers approve-task <task-id> --note
+   "<why>" --session ... --causal-parent ... --actor operator`. Only the
+   operator actor is accepted; an approval written under any other actor is
+   refused, and one appended by hand under another actor is not honoured. An
+   approval is tied to the plan version it is given under (`--plan-version`):
+   a task waived again by a newer plan needs a fresh approval.
+4. A denial discharges nothing — the finding stays open with no further
+   move of its own, and an open finding blocks the epic verdict. The
+   command's output carries `findingIdsToCarry`: every finding id this batch
+   denied. Carry the whole list forward until each id is closed — by the
+   route its **scope** allows (`bs findings list --session <id>` shows
+   the scope), by a later grant, or by `refuted`. The two scopes do not share
+   a route:
+
+   - **`spec` finding** (owned by `<epic>/integration`) — cut a
+     `bs plan amend`, and its `--findings` must name every spec id from
+     the list, or the finding stays open forever with no path back (issue
+     #221). The amendment moves it to `amend-pending`; epic close moves it to
+     `amended`. See `docs/guide/operator-guide/findings.md` §6a.
+   - **`diff` finding** — `plan amend` refuses it
+     (`plan.amendment-not-spec-scoped`): the code is wrong, not the plan. If
+     the owning task is still open, bounce the finding to it like any gate
+     finding. If the owner has already merged, fix it in a **follow-up
+     task**:
+     1. Write a draft, `Array<{filePath, finding}>` (the `gate run`
+        findings shape). `filePath` is the denied record's `file_path`;
+        `finding` is the **whole** record `bs findings list` prints,
+        minus the three fields raise derives and overwrites —
+        `fingerprint`, `file_path` and `finding_status`. Keep the rest:
+        the schema requires `failure_scenario` and `found_by` too, and a
+        draft without them fails with `findings.invalid-record`. Leave
+        `task_id`, `finding_id` and `epic_id` as they are; routing rewrites
+        them. Do not touch `finding_category` or `summary`: the follow-up
+        id is derived from the fingerprint they make.
+     2. Raise it against the plan with no `--task`:
+        `bs findings raise --plan <plan.json> --findings <draft.json>
+        --session <id> --plan-version <n> --causal-parent <event-id>
+        --actor operator`. Routing sees the owner is closed and mints
+        `<epic>/followup-<fp8>` — read `taskId` from the printed row
+        (`attribution: follow-up`). A denied fingerprint is not suppressed
+        on a re-raise; a granted one is.
+     3. Check its claims before dispatching. A follow-up **inherits the
+        owner's whole claim set** — and when ownership of the file was
+        ambiguous, the **union** of every candidate's claims — so it can
+        overlap tasks still in flight. `bs wave next <plan.json>
+        --session <id> --causal-parent <event-id>` shows it: it folds in
+        live status and logged follow-ups, and defers an overlapping task
+        with `claim-overlap`. `wave check` validates only the ids it is
+        given and cannot see the conflict.
+     4. Dispatch it like any task, with these gaps filled by hand. It
+        carries no acceptance criteria and no budget: **write the ACs into
+        the dispatch brief** (the finding's fix, plus the test that proves
+        it). `wave check` prices it at the coder cap, and `gate run` reports
+        its budget as not-declared. It is not in the plan, so
+        `lessons for-dispatch`, `findings for-dispatch` and `coverage check`
+        refuse it with `cli.task-not-in-plan`: splice
+        `bs lessons for-dispatch <role> --case-type bugfix` without
+        `--plan`/`--task` — at the cost of every claim-path lesson, since
+        claims are then `[]` and those lessons drop silently — and replace the findings block with
+        `bs findings list --session <id> --task <epic>/followup-<fp8>`.
+        At its gate, run `gate run` **without** `--plan`. With it, a judge
+        finding on the merged owner's file routes to yet another follow-up
+        (listed under `reattributedFindings`) instead of blocking this one,
+        and that stray follow-up then blocks the epic until it completes or
+        its findings are waived. Without it the finding blocks here, at the
+        cost of coverage checking the total rather than the follow-up's
+        claims.
+     5. Close **both** findings by hand once the follow-up merges — nothing
+        links the re-raised finding to the denied one, and neither moves on
+        its own. Walk each with `bs findings transition <finding-id>
+        <status> --session <id> --plan-version <n> --causal-parent
+        <event-id> --actor operator` through `confirmed`, `fix-pending`, `fix-landed`,
+        `fix-verified` (start at the first edge its status allows).