@juzser/blacksmith 0.1.1 → 0.2.0

package/.claude/agents/planner.md

@@ -58,6 +58,27 @@ types, config, shared fixtures) are never split across concurrent tasks —
 mark them `serialize-always` and give overlapping tasks a dependency edge
 instead of concurrent claims.
 
+Before signing, read the slicing back from the project, not from the plan:
+`smith claims impact --plan <plan.json> <every task id> --repo <project-dir>`
+names each import edge that crosses between tasks the plan gave no
+dependency, and `smith wave schedule <plan.json> --repo <project-dir>` says
+how wide the plan can ever run. Every crossing the first reports is one of
+three things, and the plan says which:
+
+- a **dependency edge** — the consumer needs the producer's *new* export, so
+  the producer runs first;
+- a **`keeps_exports` promise** on the producer — it only *adds* to that file
+  or leaves its exports alone, so both run now and the diff is checked
+  against the promise post-run;
+- a **re-slice**.
+
+Two shapes cross by construction, so do not draw them: a module's tests split
+from the module (a `src/x.ts` task and a `test/x.test.ts` task always cross),
+and a doc hub (runbook, README) claimed by one task and edited by many —
+each task edits its own section inside its own claims, or one docs task takes
+edges from the others. Target `widest >= 2` when the plan has two or more
+tasks, or say in `planner_notes` why the work is a chain.
+
 ## Living spec doc (architecture §11)
 
 You own the epic's living spec markdown: every worker reads it before

package/.claude/skills/bs/SKILL.md

@@ -1,33 +1,49 @@
 ---
 name: bs
-description: Operator console for the Blacksmith factory — invoke as `/bs <subcommand>` (new, plan, run, audit, status, ui, waivers, lessons, report) to scaffold a project, plan or drive an epic through the loop, audit a project on four axes and cut an epic from what the operator accepts, check live status, open the dashboard, answer a waiver batch, triage lesson candidates, or get a progress digest. This file routes; each subcommand's playbook is a sibling file read when that verb runs. Use this whenever the operator wants to interact with Blacksmith itself, from a Claude Code session inside this repo.
+description: Operator console for the Blacksmith factory — invoke as `/bs <subcommand>` (new, plan, run, audit, status, ui, waivers, lessons, report) to scaffold a project, plan or drive an epic through the loop, audit a project on four axes and cut an epic from what the operator accepts, check live status, open the dashboard, answer a waiver batch, triage lesson candidates, or get a progress digest. This file routes; each subcommand's playbook is a sibling file read when that verb runs. Use this whenever the operator wants to interact with Blacksmith itself, from any Claude Code session that has Blacksmith installed — a clone of the repo, or the plugin plus the `smith` CLI from npm.
 ---
 
 # /bs — Blacksmith operator console
 
 You (the orchestrator session running this skill) are the human's one interface
 to the factory. Every subcommand below is a **playbook**, not a script: the
-deterministic mechanics run through the real `smith` CLI
-(`node factory/orchestrator/dist/cli.js <ns> <action> ...`, or `smith ...` once
-linked — `pnpm build` first if `dist/` is stale); the judgment steps —
-planning, spec review, coding, testing, reviewing — are separate Claude Code
-sessions you dispatch from the matching `.claude/agents/<role>.md`. **This
-skill never calls an LLM directly and never embeds a role prompt** — the
-templates own that; duplicating them here would let this file drift out of
-sync with the real contracts. Cite policy files (`factory/policies/*.yml`)
-rather than restating their numbers.
+deterministic mechanics run through the real `smith` CLI, spelled `smith` in
+every command below — on PATH from `npm i -g @juzser/blacksmith`, or inside a
+clone `node factory/orchestrator/dist/cli.js` instead, `pnpm build` first if
+`dist/` is stale. The judgment steps — planning, spec review, coding, testing,
+reviewing — are separate Claude Code sessions you dispatch by role, each under
+the contract in its own agent template beside this skill
+(`.claude/agents/<role>.md`). **This skill never calls an LLM directly and
+never embeds a role prompt** — the templates own that; duplicating them here
+would let this file drift out of sync with the real contracts. Cite policy
+files (`factory/policies/*.yml`) rather than restating their numbers.
 
 **The project directory is an answer you ask for, not a path this file
 knows.** A project this factory builds is not part of it: `smith new` puts one
-*beside* this clone when no `--target-dir` says otherwise, and nothing
-downstream reads that location — `workspaces/` inside the repo is still a legal
-answer, just no longer the assumed one. Every verb that touches the project's
-git takes the directory itself: `<project-dir>` as a positional on the
-`worktree` family, `--project <dir>` on everything else. A task's worktrees
-are placed beside whatever directory it was handed, so a project outside this
-repo keeps its worktrees outside it too (`AGENTS.md` "Worktrees"). Ask for it
-once, at the top of a run, and carry that one answer through every command
-below — `<project-dir>` here means that answer, never a fixed path.
+*outside* the factory when no `--target-dir` says otherwise (beside the clone
+if you run one, in the directory you ran an installed `smith` from), and
+nothing downstream reads that location — `workspaces/` inside the repo is
+still a legal answer, just no longer the assumed one. Every verb that touches
+the project's git takes the directory itself: `<project-dir>` as a positional
+on the `worktree` family, `--project <dir>` on everything else. A task's
+worktrees are placed beside whatever directory it was handed, so a project
+outside this repo keeps its worktrees outside it too (`AGENTS.md` "Worktrees",
+a clone-only file — see "Where the files below live"). Ask for it once, at the
+top of a run, and carry that one answer through every command below —
+`<project-dir>` here means that answer, never a fixed path.
+
+**Where the files below live.** This skill cites three kinds of path and they
+do not all resolve the same way. Playbooks and agent templates are beside this
+file and always resolve. `factory/policies/*.yml`, the JSON Schemas and the
+scaffold are **read-only assets the CLI ships**: in a clone they are in the
+checkout, and in an install they are inside the package — ask `smith` rather
+than guessing, since `smith init` prints `repoRoot` (where they are) and
+`workRoot` (where everything written goes) and is safe to re-run, keeping any
+file it already seeded. `docs/` and `AGENTS.md` are **clone-only**: they are in
+the repository and in no install, so a citation to one is a pointer for an
+operator who has the repo, never a file to assume you can open. Read, do not
+assume — and when a cited file is not there, say so instead of substituting a
+remembered number.
 
 Every write command needs an event-log envelope: `--session <id>
 --plan-version <n> --causal-parent <event-id> [--actor operator]`. Open a

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

@@ -19,8 +19,10 @@ the `audit_id` the way you keep a session id.
 nothing reads a cwd and nothing keeps a "current audit" on the side, so two
 audits on two projects cannot be confused. The project must be a git
 checkout; a directory this factory did not build is as auditable as one it
-did. Then `mkdir -p state/audit` in this clone: the judges' artifacts live
-there, under runtime state, never under the project.
+did. Then `mkdir -p state/audit` in the factory's **work root** — the clone
+itself, or the `.blacksmith/` that `smith init` made beside your code; `smith
+init` prints it as `workRoot`. The judges' artifacts live there, under runtime
+state, never under the project.
 
 ## 2. Open the audit
 

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

@@ -140,11 +140,11 @@ memory of its previous attempt and will happily report round 1 forever.
   evidence that the model was too small; it is usually evidence the spec was
   unclear, and a bigger model will implement the same misreading more
   convincingly.
-- **Escalate to opus only after two failed rounds**, and log the escalation in
-  the `dispatch_decision` (`model_tier`, `model`, plus the reason). An unlogged
-  escalation is a cost you cannot attribute later — and `model_tier` alone
-  cannot even tell you *which* frontier model you escalated to, since opus and
-  fable share the tier.
+- **Escalate to the frontier tier only after two failed rounds**, and log the
+  escalation in the `dispatch_decision` (`model_tier`, `model`, plus the
+  reason). An unlogged escalation is a cost you cannot attribute later — and
+  `model_tier` alone cannot even tell you *which* frontier model you escalated
+  to, since opus and fable share the tier.
 - **The grader's 2-round cap is a hard stop, not a ladder rung.** At a round-2
   `fail` the task goes back to the planner for re-scoping. Do not re-dispatch
   the grader, and do not escalate the *grader* — the gates decide pass/fail,

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

@@ -1,8 +1,10 @@
 # `/bs new <project> [--ui]` — scaffold a target project
 
 1. Ask where the project should live, then run `smith new <project> [--ui]
-   [--target-dir <dir>]`. Without `--target-dir` it lands beside this repo, in
-   `<repo-parent>/<project>`, which is a default rather than a requirement —
+   [--target-dir <dir>]`. Without `--target-dir` it lands beside the clone, in
+   `<repo-parent>/<project>` — or, when `smith` 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
    it here rather than assuming it six steps in. The call
    copies `factory/scaffold/` (TS strict, Biome, Vitest, CI) and layers

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

@@ -37,8 +37,8 @@ there means "not looked at", not "looked at and clean".
    guessed (architecture §5) — dispatch `researcher`
    (`.claude/agents/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`, opus/
-   fable) with the goal + the claims analysis. It drafts the epic spec and
+2. Dispatch a **`planner`** session (`.claude/agents/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`)
    — a *different model* than the planner's, per its own frontmatter — to
@@ -117,9 +117,26 @@ there means "not looked at", not "looked at and clean".
    can pay it cheaply; a `widest: 1` plan serializes the whole epic while
    every gate downstream reports a healthy wave of one. Deferrals for
    `dependency-pending` never appear there, because a chain of real
-   dependencies is the shape of the work and not a defect. Exit 2 is
-   information, not a stop — decide whether to re-slice, and say which you
-   chose when you present the plan.
+   dependencies is the shape of the work and not a defect. Exit 2 whose
+   `constraints` name `symbol-coupled` is a **re-plan round**, not
+   information: hand the planner the constraint list — the file pairs from
+   the deferral detail — and ask, per pair, for a dependency edge, a
+   `keeps_exports` promise on the producer, or a re-slice.
+   `claim-overlap` / `serialize-hotspot` constraints are the re-slice case
+   above. Exit 2 with no such constraint remains information, not a stop —
+   decide whether to re-slice, and say which you chose when you present the
+   plan.
+
+   Beside the schedule, the read that names what it only counts:
+
+   ```bash
+   smith claims impact --plan factory/specs/active/<epic>/plan-v1.json \
+     <task-id>... --repo <project-dir>
+   ```
+
+   Its `crossings` are the file pairs a `symbol-coupled` constraint points
+   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",

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

@@ -9,13 +9,13 @@ 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 this clone plus every
+   register `smith 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
    left off the line is not reported as missing, it is simply never
    mentioned. (The daemon raises `unwatched-project` for a child project with
-   a checkout that is left off the line — not for this clone, which is in
+   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
    off the printed list. The two surfaces no longer answer the same
@@ -97,7 +97,7 @@ 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`, haiku) with that
+6. Dispatch **`scribe`** (`.claude/agents/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

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

@@ -53,10 +53,12 @@ file asked for would be running it below the floor.
    - The same verdict carries `symbolImpact`. `valid: true` with
      `symbolImpact.status: "coupled"` means the claims really are disjoint
      and that is not enough: the two tasks sit on either end of an import
-     edge the plan declared no dependency for. Split the wave and run the
-     producer first — there is no override for a crossing, because the
-     declared-edge case is already refused above it
-     (operator-guide/wave.md §2).
+     edge the plan declared no dependency for. A crossing is not
+     overridable. The pair runs in the same wave only when the producer's
+     spec lists the exporting file in `keeps_exports` — then the crossing
+     sits in `symbolImpact.promised`, not `crossings`, and the promise is
+     verified against the diff at wave.md step 10. Otherwise split the wave
+     and run the producer first (operator-guide/wave.md §2).
    - `wave check` is also where the wave is priced and where
      `max_in_flight_tasks` is enforced (`budgets.yml`, `over-fan-out`).
      `wave next` deliberately asks neither question: a proposer that also

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

@@ -2,11 +2,18 @@
 
 `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. Print the local
+first (builds `ui/server/dist` + `ui/dist`), then retry, and print the local
 URL (`http://127.0.0.1:<port>`).
 
+**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
+clone-only and stop, rather than sending the operator to a `pnpm` script they
+do not have.
+
 `--roadmap-path` travels with `--db`/`--state-dir`: the read path
 re-projects each session on the first request, and that rebuilds the
 milestones table from the roadmap file it was given — unset, it falls
-back to black-smith's own `factory/specs/roadmap.md`, so a dashboard
-pointed at another project's db would show this repo's roadmap.
+back to Blacksmith's own `factory/specs/roadmap.md`, so a dashboard
+pointed at another project's db would show the factory's roadmap.

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

@@ -122,7 +122,10 @@ one thing this playbook never asks you to.
 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.
+   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
@@ -207,7 +210,7 @@ one thing this playbook never asks you to.
    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 (sonnet → opus, logged — `budgets.yml`
+   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
@@ -215,13 +218,16 @@ one thing this playbook never asks you to.
    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:
+    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 — and that is a bounce to the coder, not a merge. A
-    `possible` / `signature-changed` entry exits 0 and is a note: the
-    scanner reads text, not types (operator-guide/wave.md §2). Then admit
-    into the
+    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`**

package/README.md

@@ -151,71 +151,72 @@ a chat transcript.
 
 ## Install
 
-Two ways in, and they are **not** equivalent. A clone is what drives an epic.
-The package is the `smith` CLI on a machine that has no clone.
+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.
 
-### A clone — the whole factory
+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. Open one **in the clone** and you have
-`/bs`; that is the operator surface everything under [Using it](#using-it)
-assumes.
+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.
 
-### The package — `smith` inside a project you already have
+<details>
+<summary><b>A clone instead — the whole factory</b></summary>
 
-The CLI is published 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
-cd /path/to/your-project
-npx @juzser/blacksmith init            # creates .blacksmith/ beside your code
-npx @juzser/blacksmith --help          # or: 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 ==`
 ```
 
-The tarball is the `smith` binary plus everything it reads at runtime — the
-policies, the JSON Schemas, the scaffold templates, the roadmap default, the
-agent role files, the database migrations. Installed, `smith` writes beside
-**you**, not beside itself: state, epic plans and your `.env` go under
-`.blacksmith/` in the directory you run it from, and `smith new` scaffolds
-there too. `SMITH_HOME` overrides that root if you want one home for several
-projects. (In a clone it still writes into the clone, as it always has — the
-layout under the root is identical either way, which is what makes the two
-installs one codebase.)
-
-**What a package install does not give you is `/bs`.** `/bs` is not a CLI
-command; it is a Claude Code **skill** — `.claude/skills/bs/`, a router and ten
-playbooks that a session reads and follows. The playbooks ship in the tarball,
-but they land under `node_modules/@juzser/blacksmith/`, which is not a place
-Claude Code looks for skills or agent definitions. So a package gives you the
-`smith` verbs and not the loop that drives them: validate plans, run the gates,
-append events, read stats — yes; `/bs plan` and `/bs run` — from a clone.
-Closing that gap is its own milestone, scoped and not yet cut:
+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).
 
-> **Take `latest`.** `0.1.1` is the first release that knows it is a package:
-> `smith init`, a work root beside your project, a shipped roadmap for
-> `smith new` to read. `0.1.0`, the release before it, has none of that — it
-> derives every path from a repo root and keeps state inside its own install
-> directory, which the next `npm i` replaces. Nothing above describes `0.1.0`.
+`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
 
@@ -390,10 +391,12 @@ runbook is written; the hosted UI stays deferred. Beside the phases, `/bs audit`
 is built: an existing project can be read on four axes and one epic cut from
 what you accept.
 
-The CLI is on npm as `@juzser/blacksmith`, at `0.1.1` — the first version
-that runs beside you and knows it is a package, rather than out of the
-clone-shaped install `0.1.0` was. The package is the binary and what it
-reads. The dashboard, the docs, the test suite and `/bs` itself come from a
+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).
 
@@ -418,7 +421,7 @@ version in
 | [`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) | What it would take to run `/bs` without a clone |
+| [`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 |

package/factory/orchestrator/dist/claims.js

@@ -226,7 +226,33 @@ export function readClaimList(task) {
             'wave for the reason that it may not edit anything. Admitting it defers the mistake to ' +
             'the first out-of-claim edit; task-spec.schema.json requires at least one claim.', { task_id: task.task_id });
     }
-    return { task_id: task.task_id, claims: claims };
+    const promises = readPromiseList(task);
+    return promises === undefined
+        ? { task_id: task.task_id, claims: claims }
+        : { task_id: task.task_id, claims: claims, keeps_exports: promises };
+}
+/**
+ * The `keeps_exports` half of the same door. A promise the wave gate cannot
+ * read must not read as "no promise": that direction is safe for the gate
+ * (the crossing serializes), but it also hides the plan error until a
+ * `plan validate` nobody re-ran. The field is optional; absent stays absent.
+ */
+function readPromiseList(task) {
+    const promises = task.keeps_exports;
+    if (promises === undefined)
+        return undefined;
+    if (!Array.isArray(promises)) {
+        throw new ClaimsError('claims.unreadable-promises', `Task "${task.task_id}" declares keeps_exports as ${describeType(promises)}, not a list ` +
+            'of file paths, so the wave gate cannot tell which crossings it promised to keep. ' +
+            'keeps_exports is a list of repo-relative file paths (task-spec.schema.json).', { task_id: task.task_id, received: describeType(promises) });
+    }
+    const badIndex = promises.findIndex((file) => typeof file !== 'string' || file === '');
+    if (badIndex !== -1) {
+        const received = promises[badIndex] === '' ? 'an empty string' : describeType(promises[badIndex]);
+        throw new ClaimsError('claims.unreadable-promises', `Task "${task.task_id}" declares keeps_exports entry ${badIndex} as ${received}, not a ` +
+            'file path, so the wave gate cannot tell which crossings it promised to keep.', { task_id: task.task_id, index: badIndex, received });
+    }
+    return promises;
 }
 /**
  * Refuse an edge list no traversal can read, before it is traversed.