@juzser/blacksmith 0.3.0 → 0.5.0

package/factory/orchestrator/dist/testerAudit.js

@@ -8,18 +8,37 @@ import { taskIdsMatch } from './taskId.js';
  */
 const TEST_GATE_EVENT = 'testgate-result';
 /**
- * How a dispatched agent's turn is recorded as over, and which payload field
- * names the role that ended it. Falling back to the record's `actor` is not a
- * nicety: the older half of the log names the role there and nowhere else,
- * and reading only the payload would report those runs as testers that never
- * reported — an `unverifiable` about evidence the log is holding.
+ * How a dispatched agent's turn is recorded as over, and which payload
+ * field(s) name the role that ended it, tried in order. Falling back to the
+ * record's `actor` is not a nicety: the older half of the log names the role
+ * there and nowhere else, and reading only the payload would report those
+ * runs as testers that never reported — an `unverifiable` about evidence the
+ * log is holding.
+ *
+ * `error-logged` tries `agent` before `agent_role`: this reader's own
+ * historical key first, `agent_role` (the dispatch's) as the fallback for a
+ * hand-written event that only carries that one — the same either-key
+ * reading delegation.ts and agents-registry.ts already give this event type.
+ * Each of the three readers keeps its own historical key first rather than
+ * all agreeing on one order, since `agent` and `agent_role` were each the
+ * only key some reader ever had for this event type before the other was
+ * added as a fallback.
  */
 const TERMINAL_ROLE_EVENTS = {
-    'task-result-recorded': 'agent',
-    'error-logged': 'agent',
-    'judge-reported': 'agent_role',
-    'judge-verdict': 'agent',
+    'task-result-recorded': ['agent'],
+    'error-logged': ['agent', 'agent_role'],
+    'judge-reported': ['agent_role'],
+    'judge-verdict': ['agent'],
 };
+/** The first of `keys` that names a non-empty string in `payload`, or null. */
+function firstPayloadString(payload, keys) {
+    for (const key of keys) {
+        const value = payloadString(payload, key);
+        if (value !== null)
+            return value;
+    }
+    return null;
+}
 function payloadString(payload, key) {
     const value = payload[key];
     return typeof value === 'string' && value.length > 0 ? value : null;
@@ -46,11 +65,11 @@ export function readTerminalRoleRecords(events) {
     const records = [];
     for (const stored of events) {
         const record = stored.record;
-        const field = TERMINAL_ROLE_EVENTS[record.event_type];
-        if (!field)
+        const fields = TERMINAL_ROLE_EVENTS[record.event_type];
+        if (!fields)
             continue;
         const payload = (record.payload ?? {});
-        const role = payloadString(payload, field) ?? record.actor;
+        const role = firstPayloadString(payload, fields) ?? record.actor;
         if (!role)
             continue;
         records.push({

package/factory/orchestrator/dist/testgate.js

@@ -1,5 +1,6 @@
 import { spawn } from 'node:child_process';
 import { constants as osConstants } from 'node:os';
+import { BS_PREFIX, LEGACY_PREFIX } from './env.js';
 const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
 const TAIL_LINES = 50;
 /**
@@ -63,27 +64,29 @@ function signalNote(code, signal) {
  * factory's own namespace.
  *
  * A command the factory launches on a project's behalf belongs to the
- * project, not to the factory that launched it. Every `SMITH_*` variable in
- * this process was set for *this* process, and letting one through silently
- * makes the factory's own invocation part of the project's verdict.
- * `SMITH_HOME` is the one that bites: it moves `WORK_ROOT` off the worktree,
- * so a suite that asserts its own layout fails on the launcher's environment
- * alone, and anything the suite writes to state lands in the factory's live
- * `state/` instead of the worktree's. The verdict then depends on how the
- * factory happened to be invoked, which is not a verdict about the branch.
+ * project, not to the factory that launched it. Every `BS_*` variable — and,
+ * for the transition period, every legacy `SMITH_*` one — in this process
+ * was set for *this* process, and letting one through silently makes the
+ * factory's own invocation part of the project's verdict. `BS_HOME` (nee
+ * `SMITH_HOME`) is the one that bites: it moves `WORK_ROOT` off the
+ * worktree, so a suite that asserts its own layout fails on the launcher's
+ * environment alone, and anything the suite writes to state lands in the
+ * factory's live `state/` instead of the worktree's. The verdict then
+ * depends on how the factory happened to be invoked, which is not a verdict
+ * about the branch.
  *
  * The strip is a rule rather than a roster, deliberately: a roster is a list
- * that goes stale the next time a `SMITH_*` variable is added, and it goes
- * stale silently. Not every one of them is the factory configuring itself —
- * `SMITH_CROSSCHECK_OFFLINE` is an operator switch — but the runbook already
- * says of that one "pass it per command"
+ * that goes stale the next time a `BS_*`/`SMITH_*` variable is added, and it
+ * goes stale silently. Not every one of them is the factory configuring
+ * itself — `BS_CROSSCHECK_OFFLINE` is an operator switch — but the runbook
+ * already says of that one "pass it per command"
  * (`docs/runbooks/providers.md`, and it names an ambient copy of that switch
  * as its own hazard). The command the operator means is the one running
  * here, not the factory that spawned it, and stating it inside the command
  * string works: the shell applies it after this strip.
  */
 export function projectCommandEnv(env) {
-    return Object.fromEntries(Object.entries(env).filter(([name]) => !name.startsWith('SMITH_')));
+    return Object.fromEntries(Object.entries(env).filter(([name]) => !name.startsWith(BS_PREFIX) && !name.startsWith(LEGACY_PREFIX)));
 }
 /**
  * Run one check command in its own process group (POSIX `setsid`, via
@@ -94,8 +97,9 @@ export function projectCommandEnv(env) {
  * jobs, long-lived children) running as orphans after the parent shell
  * dies — a real leak in a 24/7 factory (reproduced: manual kill -9 needed).
  */
-function runOne(check, cwd, timeoutMs) {
+function runOne(check, cwd, defaultTimeoutMs) {
     return new Promise((resolve) => {
+        const timeoutMs = check.timeout_ms ?? defaultTimeoutMs;
         const child = spawn(check.cmd, {
             cwd,
             shell: true,
@@ -176,10 +180,10 @@ function runOne(check, cwd, timeoutMs) {
  * no test-output parsing beyond the process exit code.
  */
 export async function run(checks, opts) {
-    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const defaultTimeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const results = [];
     for (const check of checks) {
-        const result = await runOne(check, opts.cwd, timeoutMs);
+        const result = await runOne(check, opts.cwd, defaultTimeoutMs);
         results.push(result);
         if (!result.pass && !opts.runAll)
             break;

package/factory/orchestrator/dist/uiuxGate.js

@@ -0,0 +1,83 @@
+import { resolveArtifactPath } from './artifacts.js';
+import { eventTaskId, readLineageEvents } from './events.js';
+import { foldJudgeTurns, JUDGE_DISPATCH_EVENT_TYPE } from './judges.js';
+import { taskIdsMatch } from './taskId.js';
+/** `judges.ts`'s uiux role, spelled out here rather than imported: the string is the taxonomy value, not an implementation detail of judges.ts. */
+const UIUX_ROLE = 'uiux';
+/** desktop × mobile, light × dark — the four shots a visual pass has to cover. */
+const REQUIRED_COMBOS = [
+    ['desktop', 'light'],
+    ['desktop', 'dark'],
+    ['mobile', 'light'],
+    ['mobile', 'dark'],
+];
+function latestTesterRecord(events, taskId) {
+    let latest = null;
+    events.forEach(({ record }, index) => {
+        if (record.event_type !== 'artifact-check-result')
+            return;
+        if (!taskIdsMatch(eventTaskId(record) ?? undefined, taskId))
+            return;
+        const head = record.payload.head;
+        if (typeof head !== 'string')
+            return; // an artifact-check-result with no --worktree behind it
+        const screenshots = Array.isArray(record.payload.screenshots)
+            ? record.payload.screenshots
+            : [];
+        latest = { index, head, screenshots };
+    });
+    return latest;
+}
+/** The lineage position of the dispatch that opened a judge turn — `JudgeTurn.dispatchedAt` is wall-clock only. */
+function dispatchIndex(events, taskId, role, kind, round) {
+    let found = -1;
+    events.forEach(({ record }, index) => {
+        if (record.event_type !== JUDGE_DISPATCH_EVENT_TYPE)
+            return;
+        if (!taskIdsMatch(eventTaskId(record) ?? undefined, taskId))
+            return;
+        if (record.payload.agent_role !== role)
+            return;
+        if (record.payload.judge_kind !== kind)
+            return;
+        if (record.payload.round !== round)
+            return;
+        found = index;
+    });
+    return found;
+}
+/**
+ * `checkUiux`: the one function both the gate stage and `bs uiux check`
+ * (the preflight verb, D4) call, so the two can never disagree about the same
+ * fixture. Reads the lineage once and folds both judge turns and the tester's
+ * freshness record out of it — no separate dispatch, no separate store.
+ */
+export async function checkUiux(input, ctx, opts = {}) {
+    const events = await readLineageEvents(ctx.sessionId, opts);
+    const turns = foldJudgeTurns(events, input.taskId);
+    const specTurn = turns.find((t) => t.role === UIUX_ROLE && t.kind === 'spec');
+    if (!specTurn?.reported) {
+        return { outcome: 'blocked', reason: 'uiux-spec-missing' };
+    }
+    const tester = latestTesterRecord(events, input.taskId);
+    if (tester === null) {
+        return { outcome: 'blocked', reason: 'screenshots-missing' };
+    }
+    const haveCombos = new Set(tester.screenshots.map((s) => `${s.viewport}:${s.theme}`));
+    const allCombosPresent = REQUIRED_COMBOS.every(([viewport, theme]) => haveCombos.has(`${viewport}:${theme}`));
+    const allOnDisk = tester.screenshots.every((s) => resolveArtifactPath(input.taskId, s.path, input.artifactsDir) !== null);
+    if (!allCombosPresent || !allOnDisk) {
+        return { outcome: 'blocked', reason: 'screenshots-missing' };
+    }
+    if (input.head !== undefined && tester.head !== input.head) {
+        return { outcome: 'blocked', reason: 'screenshots-stale' };
+    }
+    const visualTurn = turns.find((t) => t.role === UIUX_ROLE && t.kind === 'visual');
+    const visualDispatchIndex = visualTurn === undefined
+        ? -1
+        : dispatchIndex(events, input.taskId, UIUX_ROLE, 'visual', visualTurn.round);
+    if (!visualTurn?.reported || !(visualDispatchIndex > tester.index)) {
+        return { outcome: 'blocked', reason: 'uiux-visual-missing' };
+    }
+    return { outcome: 'pass' };
+}

package/factory/orchestrator/dist/usage.js

@@ -1,5 +1,5 @@
 /**
- * What `smith` can be asked to do, written down once (P9-21).
+ * What `bs` can be asked to do, written down once (P9-21).
  *
  * Before this, `smith` and `smith --help` both answered
  * `{"error":{"message":"Unknown command: "}}`, so the only way to learn a
@@ -31,7 +31,7 @@ const EVENTS_DIR = `${EVENTS} [--state-dir <dir>]`;
  */
 const STATS = '[--db <file>] [--session <id>] [--lineage]';
 /** The scope both `issues` actions accept: a session's lineage, narrowed by epic and ISO since. */
-const ISSUES = '--session <id> [--epic <id>] [--since <iso>] [--state-dir <dir>] [--roadmap-path <file>]';
+const ISSUES = '--session <id> [--epic <id>] [--since <iso>] [--state-dir <dir>] [--roadmap-path <file>] [--specs-dir <dir>]';
 export const COMMANDS = [
     {
         command: 'audit open',
@@ -66,8 +66,8 @@ export const COMMANDS = [
     {
         command: 'audit resolve',
         positionals: '<project-dir>',
-        flags: `--epic <epic-id> ${EVENTS_DIR}`,
-        summary: 'Append a fixed line for every finding the epic carried. Run from the epic-close step.',
+        flags: `--epic <epic-id> [--except <fp[,fp...]>] [--plan <plan.json>] [--specs-dir <dir>] ${EVENTS_DIR}`,
+        summary: "Append a fixed line for every carried finding a task in the epic's newest plan still claims, or a superseded task's change already merged; list the rest as deferred. Run from the epic-close step.",
     },
     {
         command: 'audit close',
@@ -90,14 +90,14 @@ export const COMMANDS = [
     {
         command: 'plan quorum',
         positionals: '',
-        flags: '--plan-version <n> --session <id> --causal-parent <event-id> [--epic <id>] [--plan <draft.json>] [--confidence <0-1>] [--out <file>] [--actor <name>] [--specs-dir <dir>] [--state-dir <dir>]',
+        flags: '--plan-version <n> --session <id> --causal-parent <event-id> [--epic <id>] [--plan <draft.json>] [--confidence <0-1>] [--project <dir>] [--out <file>] [--actor <name>] [--specs-dir <dir>] [--state-dir <dir>]',
         summary: 'Critique-only review of a drafted plan: --plan <draft.json> before it is filed, or --epic for the filed version. Exit 1 means the operator must look first.',
     },
     {
         command: 'plan amend',
         positionals: '',
         flags: `--plan <plan.json> --findings <id[,id...]> --rationale <text> --sites <path[,path...]> [--changes <changes.json>] [--specs-dir <dir>] ${EVENTS_DIR}`,
-        summary: 'Cut a new plan version against the spec findings that forced it. No finding, no amendment. --sites is every place the shape occurs, not only where it was reported.',
+        summary: 'Cut a new plan version against the spec findings that forced it. No finding, no amendment. --sites is every place the shape occurs, not only where it was reported. --specs-dir defaults to the directory --plan already lives in (#219), not factory/specs/active; an explicit --specs-dir that disagrees with it is refused rather than silently preferred.',
     },
     {
         command: 'plan propose',
@@ -126,8 +126,11 @@ export const COMMANDS = [
     {
         command: 'plan ingest',
         positionals: '<plan.json>',
-        flags: EVENTS_DIR,
-        summary: 'Record every task and dependency the plan declares, before any wave names them.',
+        flags: `[--project <dir>] ${EVENTS_DIR}`,
+        summary: 'Record every task and dependency the plan declares, before any wave names them. ' +
+            '--project resolves the branch prefix a legacy `smith/<epic>/integration` epic keeps ' +
+            'using, rather than declaring `bs/...` for a branch `worktree create` will cut as ' +
+            '`smith/...`.',
     },
     {
         command: 'wave check',
@@ -198,7 +201,7 @@ export const COMMANDS = [
     {
         command: 'daemon run',
         positionals: '',
-        flags: `[--interval <seconds>] [--once] [--dir <dir>] [--project <dir>...] [--no-self] [--db <path>] [--no-db] [--state-dir <dir>]`,
+        flags: `[--interval <seconds>] [--once] [--dir <dir>] [--project <dir>...] [--no-self] [--db <path>] [--no-db] [--state-dir <dir>] [--specs-dir <dir>]`,
         summary: 'Watch the event log in the foreground: budgets, stale agents, work that is due. ' +
             'Prints one report per tick, one JSON line each; --once prints one document and exits. ' +
             'Never dispatches.',
@@ -232,21 +235,21 @@ export const COMMANDS = [
     {
         command: 'scheduler run',
         positionals: '',
-        flags: `[--dry] [--now <iso>] [--project <dir>...] [--no-self] ${EVENTS_DIR}`,
+        flags: `[--dry] [--now <iso>] [--project <dir>...] [--no-self] [--specs-dir <dir>] ${EVENTS_DIR}`,
         summary: 'Propose and enact the next scheduler moves for a session. --dry proposes only.',
     },
     {
         command: 'scheduler admit',
         positionals: '',
         flags: '--session <id> [--state-dir <dir>] [--now <iso>] [--project <dir>...] [--no-self] ' +
-            '[--policy <file>] [--crosscheck <file>]',
+            '[--specs-dir <dir>] [--policy <file>] [--crosscheck <file>]',
         summary: "Classify what's due into auto or operator per scheduler.yml autonomy. Enacts nothing.",
     },
     {
         command: 'worktree create',
         positionals: '<project-dir> <epic> <task-id>',
-        flags: '',
-        summary: 'Cut the isolated worktree and task branch one task is allowed to write in.',
+        flags: '[--from <predecessor-task-id> --session <id> [--state-dir <dir>]]',
+        summary: 'Cut the isolated worktree and task branch one task is allowed to write in. --from cuts it from a predecessor branch instead of integration, and requires --session (which supplies the log --from is checked against): refused unless that session records <epic>/<task-id> as the logged successor of <epic>/<predecessor-task-id>.',
     },
     {
         command: 'worktree rm',
@@ -275,8 +278,12 @@ export const COMMANDS = [
     {
         command: 'queue run',
         positionals: '<epic>',
-        flags: '--project <dir> --test-cmd <cmd> --tasks <tasks.json> [--select-test-cmd <cmd>] [--session <id> --causal-parent <event-id> --plan <plan.json> [--plan-version <n>] [--actor <name>]] [--state-dir <dir>]',
-        summary: 'Serially rebase, test, and merge task branches into the integration branch.',
+        flags: '--project <dir> --test-cmd <cmd> --tasks <tasks.json> --session <id> --causal-parent <event-id> --plan <plan.json> [--plan-version <n>] [--actor <name>] [--select-test-cmd <cmd>] [--batch] [--state-dir <dir>]',
+        summary: 'Serially rebase, test, and merge task branches into the integration branch. ' +
+            'A merge is a fact the log must carry, so --session/--causal-parent/--plan are required — ' +
+            'refuses before any git write without them. ' +
+            '--batch (roadmap merge-lanes) groups claim-disjoint tasks with groupForBatch and ' +
+            'tests each group once instead of once per task — see queue.ts and the operator guide.',
     },
     {
         command: 'queue adopt',
@@ -291,8 +298,8 @@ export const COMMANDS = [
     {
         command: 'session start',
         positionals: '<session-id>',
-        flags: '[--continues <event-id>] [--actor <name>] [--state-dir <dir>]',
-        summary: 'Open a session log with the one root event it is allowed. Exit 1 if the session is already open.',
+        flags: '[--continues <event-id>] [--prompt <event-id>] [--actor <name>] [--state-dir <dir>]',
+        summary: 'Open a session log with the one root event it is allowed; --prompt links the user_prompt that asked for it. Exit 1 if the session is already open.',
     },
     {
         command: 'event append',
@@ -325,6 +332,36 @@ export const COMMANDS = [
         flags: EVENTS_DIR,
         summary: "Put the operator's own words on the timeline verbatim, and print the event id a dispatch hangs off.",
     },
+    {
+        command: 'prompt capture',
+        positionals: '',
+        flags: '',
+        summary: 'Read one UserPromptSubmit hook payload on stdin and record it where the cwd is managed. Print one line, or nothing; always exit 0.',
+    },
+    {
+        command: 'prompt import',
+        positionals: '',
+        flags: '--transcript <file> [--dry-run]',
+        summary: "Replay a Claude Code transcript's prompts and option answers into prompts-<cli session>, keeping their timestamps. Re-running imports nothing; --dry-run prints each event and writes none. Print a summary line.",
+    },
+    {
+        command: 'feedback record',
+        positionals: '',
+        flags: `--task <task-id> [--body <text>|--body-file <file>] [--kind <must-fix|nice-to-have>] [--source <dashboard|github|cli>] [--external-id <id>] [--author <name>] ${EVENTS_DIR}`,
+        summary: "Record the operator's mid-run comment on a task. Print { event_id, feedback_id, deduped }; a repeated --external-id dedupes rather than appending.",
+    },
+    {
+        command: 'feedback pending',
+        positionals: '',
+        flags: '--session <id> [--task <task-id>] [--epic <id>] [--state-dir <dir>]',
+        summary: "List this session lineage's unresolved feedback, each with a suggestedAction: follow-up once its task is closed to further work, bounce otherwise.",
+    },
+    {
+        command: 'feedback resolve',
+        positionals: '',
+        flags: `--feedback <id> --resolution <bounced|follow-up|dismissed> [--note <text>] [--follow-up-task <task-id>] ${EVENTS_DIR}`,
+        summary: 'Resolve one recorded feedback item. Rejects an unknown or already-resolved feedback id.',
+    },
     {
         command: 'claims check',
         form: '--roots',
@@ -359,6 +396,12 @@ export const COMMANDS = [
         flags: '[--task <id>] [--policy <path>] [--state-dir <dir>]',
         summary: 'Assert crosscheck.yml’s role asymmetry against the log. Exit 1 on a violation OR an unverifiable answer.',
     },
+    {
+        command: 'dispatch lint',
+        positionals: '<prompt-file>',
+        flags: '--role <role> --task <id> --session <id> [--agents-dir <dir>] [--state-dir <dir>]',
+        summary: "Check a composed dispatch prompt's stated turn budget against the role template's maxTurns, and a judge prompt's declared-artifact line against the ledger. Exit 1 on a violation OR an unverifiable answer. `-` reads stdin.",
+    },
     {
         command: 'tester check',
         positionals: '<session-id>',
@@ -415,7 +458,7 @@ export const COMMANDS = [
     {
         command: 'harness plan',
         positionals: '',
-        flags: '--role <role> --task <id> --prompt-file <path> [--harness <name>] [--worktree <dir>] [--policy <file>] [--tier <frontier|mid|small>] [--schema <name>]',
+        flags: '--role <role> --task <id> --prompt-file <path> [--harness <name>] [--worktree <dir>] [--policy <file>] [--tier <frontier|mid|small>] [--schema <name>] [--specs-dir <dir>]',
         summary: 'Render the invocation that would run one worker turn, as JSON. Prints it; never starts it.',
     },
     {
@@ -452,7 +495,7 @@ export const COMMANDS = [
         command: 'stack check',
         positionals: '',
         flags: '[--policy <file>]',
-        summary: 'Which stack answers the shipped templates honour, which they only record, and which make `smith new` refuse. Exit 1 on a refusal.',
+        summary: 'Which stack answers the shipped templates honour, which they only record, and which make `bs new` refuse. Exit 1 on a refusal.',
     },
     {
         command: 'policy check',
@@ -469,9 +512,21 @@ export const COMMANDS = [
     {
         command: 'gate run',
         positionals: '<task-id>',
-        flags: `--worktree <dir> --checks <checks.json> --result <result.json> [--base <ref>] [--grader <file>] [--agent <role> --provider <name> --model-tier <tier> --input-tokens <n> --output-tokens <n>] [--evidence <file> --found-by <role> [--found-by-provider <name>]] [--findings <file>] [--no-findings <role>] [--lessons <lessons.md>] [--plan <file>] [--run-all] [--artifacts-dir <dir>] ${EVENTS_DIR}`,
+        flags: `--worktree <dir> --checks <checks.json> --result <result.json> [--project <dir>] [--base <ref>] [--grader <file>] [--agent <role> --provider <name> --model-tier <tier> --input-tokens <n> --output-tokens <n>] [--evidence <file> --found-by <role> [--found-by-provider <name>]] [--findings <file>] [--no-findings <role>] [--uiux-visual <file>] [--lessons <lessons.md>] [--plan <file>] [--run-all] [--artifacts-dir <dir>] ${EVENTS_DIR}`,
         summary: 'The per-task gate: schema, tests, coverage, findings. Exit 1 when blocked.',
     },
+    {
+        command: 'results record',
+        positionals: '',
+        flags: `--task <task-id> --result <result.json> [--agent <role> --provider <name> --model-tier <tier> [--input-tokens <n> --output-tokens <n>]] [--artifacts-dir <dir>] [--worktree <dir>] ${EVENTS_DIR}`,
+        summary: "Project a worker's Result on its own, with no worktree to certify and no tests to run: schema-check, task-result-recorded, artifact-check. Wave.md's tester has no gate to run one through; this is how its screenshots reach the dashboard the moment it finishes. --worktree records that worktree's HEAD and the Result's screenshot artifacts, the freshness evidence the uiux gate stage reads back. Exit 1 when blocked.",
+    },
+    {
+        command: 'uiux check',
+        positionals: '',
+        flags: `--task <task-id> --plan <plan.json> [--worktree <dir>] [--artifacts-dir <dir>] ${EVENTS_DIR}`,
+        summary: 'Preflight for the gate uiux stage: the same checkUiux a flagged task is gated on, so a dispatcher can ask before running the whole gate. Exit 1 when blocked.',
+    },
     {
         command: 'coverage check',
         positionals: '<worktree-dir>',
@@ -481,7 +536,7 @@ export const COMMANDS = [
     {
         command: 'budget alarm',
         positionals: '<session-id>',
-        flags: '[--epic <id>] [--policy <path>] [--state-dir <dir>]',
+        flags: '[--epic <id>] [--policy <path>] [--specs-dir <dir>] [--state-dir <dir>]',
         summary: 'Epic spend against budgets.yml’s epic.alarm_ratio. Exit 1 on a crossing OR on a record too holey to rule one out.',
     },
     {
@@ -505,8 +560,8 @@ export const COMMANDS = [
     {
         command: 'epic spec-review',
         positionals: '',
-        flags: `--epic <id> --project <dir> --plan <plan.json> --reviewed-by <role> [--reviewed-by-provider <name>] [--evidence <file>] ${EVENTS_DIR}`,
-        summary: 'Record the closing spec review, pinned to the integration head it was read at.',
+        flags: `--epic <id> --project <dir> --plan <plan.json> --reviewed-by <role> [--reviewed-by-provider <name>] [--evidence <file>] [--no-findings] ${EVENTS_DIR}`,
+        summary: 'Record the closing spec review, pinned to the integration head it was read at. Exactly one of --evidence or --no-findings; --no-findings attests the clean case.',
     },
     {
         command: 'epic goal',
@@ -545,8 +600,8 @@ export const COMMANDS = [
     {
         command: 'findings for-dispatch',
         positionals: '',
-        flags: '--session <id> --plan <plan.json> --task <task-id> [--state-dir <dir>]',
-        summary: "Print the open findings a dispatching task's own claims cover, as a prompt block.",
+        flags: '--session <id> [--plan <plan.json> --task <task-id>] [--state-dir <dir>]',
+        summary: "Print the open findings a dispatching task's own claims cover, as a prompt block; with no --plan/--task, every open finding in the epic.",
     },
     {
         command: 'findings list',
@@ -587,10 +642,20 @@ export const COMMANDS = [
         flags: EVENTS_DIR,
         summary: 'Apply a batch of operator waiver decisions.',
     },
+    {
+        command: 'waivers approve-task',
+        positionals: '<task-id>',
+        flags: `--note <why> ${EVENTS_DIR}`,
+        summary: 'Record the operator approval of one waived task. Without it a waived task blocks the epic close; an approval counts only for the plan version it was given at or later. Requires --actor operator.',
+    },
     {
         command: 'lessons candidates',
         positionals: '',
-        flags: STATS,
+        // Only `candidates` takes `--state-dir` alongside STATS: it validates
+        // `--session` against the event log the same way `raise`/`approve`/
+        // `reject`/`db rebuild` do (P9-28), which is a per-session log, not a
+        // per-DB-query concern the other STATS-flagged commands share.
+        flags: `${STATS} [--state-dir <dir>]`,
         summary: 'List the lesson candidates awaiting an approve or a reject.',
     },
     {
@@ -647,20 +712,20 @@ export const COMMANDS = [
     {
         command: 'judge dispatch',
         positionals: '',
-        flags: `--task <task-id> --role <role> --artifact <file> --model <id> [--round <n>] [--provider <name>] [--model-tier <tier>] ${EVENTS_DIR}`,
-        summary: 'Declare the file a judge owes, so a turn that never came back is visible.',
+        flags: `--task <task-id> --role <role> --artifact <absolute-path> --model <id> [--round <n>] [--provider <name>] [--model-tier <tier>] [--kind <spec|visual>] ${EVENTS_DIR}`,
+        summary: 'Declare the file a judge owes, so a turn that never came back is visible. --kind only applies to uiux, which opens a spec turn and a visual turn per task.',
     },
     {
         command: 'judge report',
         positionals: '',
-        flags: `--task <task-id> --role <role> [--round <n>] [--artifact <file>] [--no-findings] ${EVENTS_DIR}`,
-        summary: 'Close a judge turn against the artifact it declared. --no-findings attests the clean case.',
+        flags: `--task <task-id> --role <role> [--round <n>] [--artifact <file>] [--no-findings] [--kind <spec|visual>] ${EVENTS_DIR}`,
+        summary: "Close a judge turn against the artifact it declared, written during this turn. --no-findings attests the clean case. --kind picks which of uiux's two open turns to close when both are open.",
     },
     {
         command: 'judge outstanding',
         positionals: '',
-        flags: '--session <id> --task <task-id> [--state-dir <dir>]',
-        summary: 'List the judge turns still owed on a task. Exit 1 while the list is non-empty.',
+        flags: '--session <id> --task <task-id> [--kind <spec|visual>] [--state-dir <dir>]',
+        summary: 'Print { taskId, sessionId, outstanding, count } for the judge turns still owed on a task. Exit 1 while count is non-zero.',
     },
     {
         command: 'judge escalations',
@@ -671,8 +736,8 @@ export const COMMANDS = [
     {
         command: 'judge preflight',
         positionals: '',
-        flags: '[--policy <file>]',
-        summary: 'Can the enabled providers be called at all, and would a promotion decide anything? Exit 1 on a provider that costs a call it cannot make.',
+        flags: '[--policy <file>] [--project <dir>]',
+        summary: 'Can the enabled providers be called at all, and would a promotion decide anything? Exit 1 on a provider that costs a call it cannot make. --project merges <dir>/.blacksmith/crosscheck.yml over the policy (OpenRouter substitution/extra judges).',
     },
     {
         command: 'judge run',
@@ -683,25 +748,25 @@ export const COMMANDS = [
     {
         command: 'crossfind request',
         positionals: '',
-        flags: '--task <id> --diff <file> --diff-ref <ref> [--criterion <text>...] [--timeout-ms <n>] [--max-output-bytes <n>] [--max-output-tokens <n>] [--policy <file>]',
+        flags: '--task <id> --diff <file> --diff-ref <ref> [--criterion <text>...] [--timeout-ms <n>] [--max-output-bytes <n>] [--max-output-tokens <n>] [--policy <file>] [--project <dir>] [--worktree <dir>]',
         summary: 'Print the finder request without sending it — exactly what would leave the machine. Refuses when send_diff is false.',
     },
     {
         command: 'crossfind reconcile',
         positionals: '',
-        flags: '--task <id> --native <findings.json> --independent <runs.json> [--policy <file>]',
+        flags: '--task <id> --native <findings.json> --independent <runs.json> [--policy <file>] [--project <dir>] [--worktree <dir>]',
         summary: 'Reconcile two saved finding lists offline. No provider, no log. Exit 1 when the result would change a gate.',
     },
     {
         command: 'crossfind run',
         positionals: '',
-        flags: `--task <id> --diff <file> --diff-ref <ref> [--criterion <text>...] [--status <status>] [--timeout-ms <n>] [--max-output-bytes <n>] [--max-output-tokens <n>] [--policy <file>] ${EVENTS_DIR}`,
+        flags: `--task <id> --diff <file> --diff-ref <ref> [--criterion <text>...] [--status <status>] [--timeout-ms <n>] [--max-output-bytes <n>] [--max-output-tokens <n>] [--policy <file>] [--project <dir>] [--worktree <dir>] ${EVENTS_DIR}`,
         summary: 'Run the independent finder over a diff and reconcile it against the native findings. Exit 1 when the result would change a gate.',
     },
     {
         command: 'ui serve',
         positionals: '',
-        flags: '[--port <n>] [--db <file>] [--state-dir <dir>] [--roadmap-path <file>] [--specs-dir <dir>] [--now-iso <iso>]',
+        flags: '[--port <n>] [--db <file>] [--state-dir <dir>] [--roadmap-path <file>] [--specs-dir <dir>] [--now-iso <iso>] [--claude-config-dir <dir>] [--store <dir>...]',
         summary: 'Serve the dashboard from the built ui/server.',
     },
     {
@@ -783,7 +848,7 @@ const COMMAND_NAMES = new Set(COMMANDS.map((doc) => doc.command));
 const NAMESPACES = new Set(COMMANDS.map(namespaceOf));
 /** The line that would have worked. Empty parts are dropped, never printed as a double space. */
 export function usageLine(doc) {
-    return ['smith', doc.command, doc.positionals, doc.flags].filter((part) => part !== '').join(' ');
+    return ['bs', doc.command, doc.positionals, doc.flags].filter((part) => part !== '').join(' ');
 }
 /** The positional argument names, in order — what a missing-argument error names. */
 export function positionalNames(doc) {
@@ -825,7 +890,7 @@ export function flagSpecFor(namespace, action) {
     if (namespace === undefined)
         return undefined;
     const key = action === undefined ? namespace : `${namespace} ${action}`;
-    // The second arm is what keeps the action-less verbs working: `smith new
+    // The second arm is what keeps the action-less verbs working: `bs new
     // my-project` spends its action slot on a positional. Same fallback as
     // isDocumented, deliberately — a command that dispatches must also parse.
     const docs = COMMANDS.filter((doc) => doc.command === key || doc.command === namespace).filter((doc) => doc.command === key || !COMMAND_NAMES.has(key));
@@ -853,23 +918,23 @@ function renderCommands(docs) {
 }
 /**
  * The whole command list, or one namespace's slice of it. An unknown namespace
- * throws rather than printing an empty list: "smith has no such namespace" and
+ * throws rather than printing an empty list: "bs has no such namespace" and
  * "that namespace has no commands" must not be the same observable answer.
  */
 export function usageText(namespace) {
     if (namespace !== undefined && !NAMESPACES.has(namespace)) {
-        throw new SmithError('usage.unknown-namespace', `No such namespace: ${namespace}. Run "smith --help" for the list.`, { namespace });
+        throw new SmithError('usage.unknown-namespace', `No such namespace: ${namespace}. Run "bs --help" for the list.`, { namespace });
     }
     const docs = namespace === undefined ? COMMANDS : COMMANDS.filter((doc) => namespaceOf(doc) === namespace);
     const header = namespace === undefined
         ? [
-            'Usage: smith <namespace> <action> [args] [--flags]',
+            'Usage: bs <namespace> <action> [args] [--flags]',
             '',
-            '  smith <namespace> --help   list one namespace',
-            '  smith <command> --help     show one command',
+            '  bs <namespace> --help      list one namespace',
+            '  bs <command> --help        show one command',
             '',
         ].join('\n')
-        : `Usage: smith ${namespace} <action> [args] [--flags]\n`;
+        : `Usage: bs ${namespace} <action> [args] [--flags]\n`;
     let out = `${header}\n`;
     let current = '';
     for (const doc of docs) {
@@ -895,7 +960,7 @@ export function helpText(namespace, action) {
     const exact = COMMANDS.filter((doc) => doc.command === key);
     if (exact.length > 0)
         return renderCommands(exact);
-    // `smith new my-project --help`: the action slot holds a positional, so the
+    // `bs new my-project --help`: the action slot holds a positional, so the
     // namespace alone is the command.
     const bare = COMMANDS.filter((doc) => doc.command === namespace);
     if (bare.length > 0)
@@ -908,7 +973,7 @@ export function helpText(namespace, action) {
  * Whether cli.ts's dispatcher has a branch for this pair. Checked before
  * dispatch, so an undocumented command cannot run — which is the half of
  * "the table and the dispatcher agree" that a test cannot enforce at runtime.
- * The second arm is what keeps the action-less verbs working: `smith new
+ * The second arm is what keeps the action-less verbs working: `bs new
  * my-project` spends its action slot on a positional.
  */
 export function isDocumented(namespace, action) {