@juzser/blacksmith 0.4.0 → 0.5.0

package/.claude/skills/bs/new.md

@@ -1,8 +1,8 @@
 # `/bs new <project> [--ui]` — scaffold a target project
 
-1. Ask where the project should live, then run `smith new <project> [--ui]
+1. Ask where the project should live, then run `bs new <project> [--ui]
    [--target-dir <dir>]`. Without `--target-dir` it lands beside the clone, in
-   `<repo-parent>/<project>` — or, when `smith` is an installed package rather
+   `<repo-parent>/<project>` — or, when `bs` is an installed package rather
    than a clone, in the directory you run it from, never inside the package.
    Either way that is a default rather than a requirement —
    the answer becomes the `<project-dir>` every later command takes, so take
@@ -15,7 +15,7 @@
    bootstrap milestone in `factory/specs/roadmap.md` — all in one call.
    An answer the templates cannot build (`frontend: react`) makes it **refuse
    before creating anything**, rather than quietly handing over the frontend
-   they do ship. `smith stack check` says in advance which answers are
+   they do ship. `bs stack check` says in advance which answers are
    honoured, merely recorded, or refused.
 2. The gate run is `pnpm install` then `lint`, `typecheck`, `test:coverage`,
    `build` — `ci.yml`'s order, so the lockfile lands in the first commit and no

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

@@ -11,8 +11,8 @@ one — and it scales steps 3–4 below plus most of `/bs run`. Ask, do not
 recall:
 
 ```bash
-smith effort show --effort <small|medium|huge>   # no plan file exists yet
-smith effort show --plan factory/specs/active/<epic>/plan-vN.json
+bs effort show --effort <small|medium|huge>      # no plan file exists yet
+bs effort show --plan factory/specs/active/<epic>/plan-vN.json
 ```
 
 `profile` is what this epic buys, and every step below that a tier touches
@@ -34,13 +34,13 @@ there means "not looked at", not "looked at and clean".
 
 1. **Static analysis for claims first.** Before any decomposition, get the
    target repo's import/dependency graph so claims are computed, not
-   guessed (architecture §5) — dispatch `researcher`
-   (`.claude/agents/researcher.md`) for an unfamiliar repo, or do it
+   guessed (architecture §5) — dispatch `bs-researcher`
+   (`.claude/agents/bs-researcher.md`) for an unfamiliar repo, or do it
    directly with Grep/Read for a small one.
-2. Dispatch a **`planner`** session (`.claude/agents/planner.md`, frontier
+2. Dispatch a **`bs-planner`** session (`.claude/agents/bs-planner.md`, frontier
    tier) with the goal + the claims analysis. It drafts the epic spec and
    task specs (`factory/specs/schema/task-spec.schema.json` shape).
-3. Dispatch a **`spec-reviewer`** session (`.claude/agents/spec-reviewer.md`)
+3. Dispatch a **`bs-spec-reviewer`** session (`.claude/agents/bs-spec-reviewer.md`)
    — a *different model* than the planner's, per its own frontmatter — to
    hunt spec gaps/ambiguities/missing-nonfunctional clauses
    (`docs/standards/agent-constraints.md` "planner"; `severity.yml`: most
@@ -49,7 +49,7 @@ there means "not looked at", not "looked at and clean".
    back tagged to one of them:
 
    1. Claims and dependency edges, cross-checked against
-      `smith claims impact`.
+      `bs claims impact`.
    2. TDD-ability -- a named failing test per task, before its code.
    3. Nonfunctional and security clauses.
    4. Budget and diff-cap fit.
@@ -57,8 +57,13 @@ there means "not looked at", not "looked at and clean".
    6. From round 2 on, only the previous round's findings plus any task
       that changed since then.
 
-   When `size.small` reads true on the draft (`smith wave schedule` or
-   `smith plan ingest`'s `parallelism.size`, run against the draft plan
+   The prompt also carries, inline on its own line,
+   `Declared artifact: /abs/path/to/state/results/<epic-id>.spec-review.json`
+   — the absolute form of the path `bs-spec-reviewer.md` names. The PreToolUse
+   guard refuses a judge dispatch without it.
+
+   When `size.small` reads true on the draft (`bs wave schedule` or
+   `bs plan ingest`'s `parallelism.size`, run against the draft plan
    file), recommend effort tier `small` -- single-pass spec review -- to
    the operator unless a security trigger floors it first, and say why in
    the same message: a plan that cannot spread past a few tasks and a
@@ -74,9 +79,10 @@ there means "not looked at", not "looked at and clean".
    confidence) for you:
 
    ```bash
-   smith plan quorum --plan <the draft's plan.json> --plan-version <n> \
+   bs plan quorum --plan <the draft's plan.json> --plan-version <n> \
      --session <session-id> --causal-parent <event-id> \
      --confidence <your own 0–1 confidence in this plan> \
+     --project <project-dir> \
      --out <scratch>/quorum-v<n>.json
    ```
 
@@ -86,7 +92,10 @@ there means "not looked at", not "looked at and clean".
    exist. (`--epic <epic>` instead of `--plan` critiques a version already
    filed.) The draft's own `epic_id`/`version` must be the ones the command
    names, or it refuses (`plan.identity-mismatch`) rather than record one
-   plan's identity with another plan's triggers. `--out` keeps the outcome
+   plan's identity with another plan's triggers. `--project <project-dir>`
+   has no worktree to derive from at this step — no task has one yet — so
+   name it directly, or a `<project-dir>/.blacksmith/crosscheck.yml` overlay
+   never reaches the providers this quorum weighs. `--out` keeps the outcome
    — three rationales of several kB each — where step 5 can hand it to the
    operator whole instead of quoting a terminal.
 
@@ -109,10 +118,10 @@ there means "not looked at", not "looked at and clean".
    "planner: autonomy — spec sign-off per epic").
 6. On approval, write task specs to
    `factory/specs/active/<epic>/plan-v1.json` and validate:
-   `smith plan validate factory/specs/active/<epic>/plan-v1.json` must
+   `bs plan validate factory/specs/active/<epic>/plan-v1.json` must
    report `{"valid":true}` before anything else touches this plan. Write the
    tier onto the plan file as a top-level `"effort": "<tier>"` — that is
-   where `/bs run` reads it, and `smith plan amend` carries it into
+   where `/bs run` reads it, and `bs plan amend` carries it into
    v(n+1) so a re-plan is not a fresh choice. Omit the field to take the
    policy default; a value that is not `small`/`medium`/`huge` fails
    validation rather than degrading to it.
@@ -121,7 +130,7 @@ there means "not looked at", not "looked at and clean".
    against it:
 
    ```bash
-   smith wave schedule factory/specs/active/<epic>/plan-v1.json \
+   bs wave schedule factory/specs/active/<epic>/plan-v1.json \
      --session <session-id> --repo <project-dir>
    ```
 
@@ -154,7 +163,7 @@ there means "not looked at", not "looked at and clean".
    Beside the schedule, the read that names what it only counts:
 
    ```bash
-   smith claims impact --plan factory/specs/active/<epic>/plan-v1.json \
+   bs claims impact --plan factory/specs/active/<epic>/plan-v1.json \
      <task-id>... --repo <project-dir>
    ```
 
@@ -162,8 +171,8 @@ there means "not looked at", not "looked at and clean".
    at; `promised` holds the ones a producer's `keeps_exports` already
    answers, which the schedule admits and the diff is later checked against.
 7. Log the sign-off itself as a decision checkpoint (this is exactly what
-   `smith dream`'s "plan sign-off" extraction looks for, `lessons.ts`):
-   `smith event append '{"session_id":"...","actor":"operator",
+   `bs dream`'s "plan sign-off" extraction looks for, `lessons.ts`):
+   `bs event append '{"session_id":"...","actor":"operator",
    "event_type":"plan-version-created","plan_version":1,
    "causal_parent":"...","payload":{"epic_id":"<epic>","version":1,
    "note":"<operator's own words>"}}'`.
@@ -172,7 +181,7 @@ there means "not looked at", not "looked at and clean".
    the sign-off event:
 
    ```bash
-   smith plan ingest factory/specs/active/<epic>/plan-v1.json \
+   bs plan ingest factory/specs/active/<epic>/plan-v1.json --project <project-dir> \
      --session <session-id> --plan-version 1 --causal-parent <sign-off event id>
    ```
 

package/.claude/skills/bs/report.md

@@ -8,8 +8,8 @@ duties, v3.2)"), plus running the scheduler first — a report that omits
 pending proposals lets them sit invisible instead of surfacing them.
 
 1. **Ask what the factory is answerable for, then run the scheduler.**
-   `smith projects list` reads the roadmap's `- project:` bullets — the
-   register `smith new` writes to — and prints the factory itself plus every
+   `bs projects list` reads the roadmap's `- project:` bullets — the
+   register `bs new` writes to — and prints the factory itself plus every
    project it built that has a checkout, ending in the `--project` line to
    pass on. Do not assemble that list from memory: the maintenance pass
    reads one lockfile per flag and reports one proposal per repo, so a repo
@@ -17,9 +17,9 @@ pending proposals lets them sit invisible instead of surfacing them.
    mentioned. (The daemon raises `unwatched-project` for a child project with
    a checkout that is left off the line — not for the factory itself, which is in
    the pass by default, and not for a declared project with no checkout at
-   all, which `smith projects list` marks with `?` instead of leaving it
+   all, which `bs projects list` marks with `?` instead of leaving it
    off the printed list. The two surfaces no longer answer the same
-   question.) Then run `smith scheduler run
+   question.) Then run `bs scheduler run
    [--dry] --session <id> [--project <dir>...]` with those flags — a
    deterministic pass over the event log, it never dispatches an agent
    itself (`factory/policies/scheduler.yml`, architecture §12). Read its
@@ -42,7 +42,7 @@ pending proposals lets them sit invisible instead of surfacing them.
      where the planner reads the living spec/analytics/recheck outcomes
      and proposes new epics — the operator's tick is required regardless
      of confidence, same as any other plan sign-off.
-2. **Ask who may say yes.** `smith scheduler admit --session <id>
+2. **Ask who may say yes.** `bs scheduler admit --session <id>
    [--project <dir>...]`, with the same flag line step 1 printed, re-reads
    the same proposals and classifies
    each one `auto` or `operator` against `scheduler.yml`'s `autonomy:`
@@ -66,9 +66,9 @@ pending proposals lets them sit invisible instead of surfacing them.
      `confidence_floor` is an operator decision about standing policy, not
      a way past one proposal — and a `security-surface` denial is the one
      nothing in the file can lift.
-3. Gather `smith stats overview [--session <id>]` and `smith stats roadmap
+3. Gather `bs stats overview [--session <id>]` and `bs stats roadmap
    [--session <id>]` (milestone progress + budget burn per milestone).
-4. **Read back the disagreements.** `smith judge escalations --session
+4. **Read back the disagreements.** `bs judge escalations --session
    <id>` folds the lineage for `quorum-decision` events whose latest word
    was `escalate` — a gate finding, an epic verdict or a plan critique the
    cross-provider quorum could not settle. It exits `1` on an open
@@ -83,7 +83,7 @@ pending proposals lets them sit invisible instead of surfacing them.
    `mode: shadow` disagreement, which the gate outcome never reported to
    anyone). Resolving one is an operator reading, never this session
    deciding on its own which provider was right.
-5. **Read back the parallelism.** `smith wave audit --session <id>
+5. **Read back the parallelism.** `bs wave audit --session <id>
    [--epic <id>]` folds every `wave-admitted` against the
    `dispatch_decision` intervals underneath it and says whether a wave
    admitted N wide actually *ran* N wide. `wave check` only ever certified
@@ -97,11 +97,11 @@ pending proposals lets them sit invisible instead of surfacing them.
    check before reporting it as a stall. A `partial` verdict is **not** a
    finding; put `widest` in the digest as the one number that says how wide
    this factory has ever actually run.
-6. Dispatch **`scribe`** (`.claude/agents/scribe.md`, small tier) with that
+6. Dispatch **`bs-scribe`** (`.claude/agents/bs-scribe.md`, small tier) with that
    JSON plus step 2's admissions as input: shipped / in-flight / blocked /
    budget burn / next milestone / **N rechecks pending, M maintenance
    bumps auto-schedulable** (never silently dropped), ≤300 words, linking
-   into the dashboard (`smith ui serve`'s URL) — never paraphrase numbers
+   into the dashboard (`bs ui serve`'s URL) — never paraphrase numbers
    the query didn't return.
 7. This fires automatically on a weekly cadence and immediately on any
    milestone completion (architecture §12) — for an ad hoc `/bs report`,
@@ -114,7 +114,7 @@ pending proposals lets them sit invisible instead of surfacing them.
 
 **Provider calibration note (Phase 8).** While any provider in
 `factory/policies/crosscheck.yml` is still `mode: shadow`, run
-`smith stats providers [--session <id>] [--since <iso-date>]` alongside the
+`bs stats providers [--session <id>] [--since <iso-date>]` alongside the
 scheduler pass and fold a one-line mention into the digest when a provider
 has accumulated enough runs to review (`runs`, `verdicts`, `agreementRate`,
 `schemaFailureRate`, `transportFailureRate`, `failuresByCode` per provider —

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`
@@ -125,7 +149,7 @@ playbooks are written to prevent.
 
 11. Repeat until every task in the live plan version is `completed`/`waived`,
     or `superseded` by a successor that is itself terminal-OK (recursively —
-    a successor chain counts too). Dispatch the **`planner`** again for
+    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
@@ -133,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>
     ```
 
@@ -148,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>
     ```
@@ -168,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
@@ -205,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.
@@ -221,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 \
@@ -244,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
@@ -260,40 +296,48 @@ 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> [--specs-dir <dir>]`
+    `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
@@ -301,18 +345,106 @@ playbooks are written to prevent.
     newest plan from the work root's specs dir by default; when this
     project's plans live elsewhere, pass `--specs-dir` naming the same specs
     dir the epic was run from, or it refuses rather than guess.
-17. Open **one integration PR per epic** with the scribe-written body
-    (`/bs report`'s playbook, [`report.md`](report.md)) — screenshots, test
-    results, reviewer verdict, waivers granted, timeline link. The head is
-    `smith/<epic>/integration`. The base is the target repo's `main` unless
+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
@@ -324,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