@juzser/blacksmith 0.4.0 → 0.5.0

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

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
@@ -67,7 +67,7 @@ export const COMMANDS = [
         command: 'audit resolve',
         positionals: '<project-dir>',
         flags: `--epic <epic-id> [--except <fp[,fp...]>] [--plan <plan.json>] [--specs-dir <dir>] ${EVENTS_DIR}`,
-        summary: "Append a fixed line for every carried finding the epic's newest plan still claims; list the rest as deferred. Run from the epic-close step.",
+        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',
@@ -275,8 +278,10 @@ export const COMMANDS = [
     {
         command: 'queue run',
         positionals: '<epic>',
-        flags: '--project <dir> --test-cmd <cmd> --tasks <tasks.json> [--select-test-cmd <cmd>] [--batch] [--session <id> --causal-parent <event-id> --plan <plan.json> [--plan-version <n>] [--actor <name>]] [--state-dir <dir>]',
+        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.',
     },
@@ -293,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',
@@ -327,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',
@@ -423,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.',
     },
     {
@@ -460,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',
@@ -477,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>',
@@ -489,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.',
     },
     {
@@ -513,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',
@@ -553,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',
@@ -595,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.',
     },
     {
@@ -655,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',
@@ -679,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',
@@ -691,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.',
     },
     {
@@ -791,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) {
@@ -833,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));
@@ -861,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) {
@@ -903,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)
@@ -916,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) {

package/factory/orchestrator/dist/waivers.js

@@ -1,8 +1,11 @@
+import { isOperatorActor } from './actors.js';
 import { SmithError } from './errors.js';
 import { appendEvent, readLineageEvents } from './events.js';
 import { computeFingerprint, foldFindings, listFindings, preWaiverStatus, staleFindings, transition, WAIVABLE_STATUSES, } from './findings.js';
 export class WaiverError extends SmithError {
 }
+/** The event `approveTaskWaiver` writes and epic.ts's withGateEvidence reads. */
+export const TASK_WAIVER_APPROVED_EVENT = 'task-waiver-approved';
 /**
  * Only S3/S4 findings are ever waived (severity.yml waiver_semantics) —
  * single source of truth, reused by findings.ts's transition() so `→ waived`
@@ -129,6 +132,33 @@ export async function grantWaiver(fingerprint, operatorNote, ctx, opts = {}) {
     await reconcileFindingsToWaived(fingerprint, waiverEvent.event_id, ctx, opts);
     return waiverEvent;
 }
+/**
+ * Record the operator's approval of one task's waiver. A task reaches
+ * `waived` through its plan row, which carries no gate run; this event is the
+ * evidence the epic gate (epic.ts's withGateEvidence) looks for instead.
+ *
+ * Refused unless the actor is the operator (actors.ts) and a rationale is
+ * given: the approval is only worth anything as a person's recorded decision.
+ * The default actor is the one every other operator decision defaults to.
+ */
+export async function approveTaskWaiver(taskId, operatorNote, ctx, opts = {}) {
+    const actor = ctx.actor ?? 'user';
+    if (!isOperatorActor(actor)) {
+        throw new WaiverError('waivers.not-operator', `Actor "${actor}" cannot approve a task waiver — only the operator can. Pass --actor operator.`, { actor, taskId });
+    }
+    if (operatorNote.trim() === '') {
+        throw new WaiverError('waivers.note-required', `Approving the waiver of task "${taskId}" needs a short rationale (--note).`, { taskId });
+    }
+    return appendEvent({
+        session_id: ctx.sessionId,
+        actor,
+        event_type: TASK_WAIVER_APPROVED_EVENT,
+        task_id: taskId,
+        plan_version: ctx.planVersion,
+        causal_parent: ctx.causalParent,
+        payload: { operator_note: operatorNote },
+    }, opts);
+}
 /**
  * The mirror of reconcileFindingsToWaived, and it exists for the same reason
  * (D-180). A denial that follows a grant revokes it — isWaived() folds
@@ -256,7 +286,7 @@ export async function applyBatch(decisions, ctx, opts = {}) {
                     `"${evidence.mergedTaskId}" has merged over since the finding was raised (matched by ` +
                     `${evidence.basis}: ${evidence.matched}). Its evidence describes code that no longer ` +
                     'exists, so this waiver would answer a question about a deleted file. Re-read it first: ' +
-                    `smith findings reverify --finding ${finding.finding_id}`, {
+                    `bs findings reverify --finding ${finding.finding_id}`, {
                     fingerprint: decision.fingerprint,
                     findingId: finding.finding_id,
                     filePath: evidence.filePath,
@@ -266,14 +296,18 @@ export async function applyBatch(decisions, ctx, opts = {}) {
             }
         }
     }
-    const results = [];
+    const events = [];
+    const findingIdsToCarry = new Set();
     for (const decision of decisions) {
         if (decision.decision === 'granted') {
-            results.push(await grantWaiver(decision.fingerprint, decision.operatorNote, ctx, opts));
+            events.push(await grantWaiver(decision.fingerprint, decision.operatorNote, ctx, opts));
         }
         else {
-            results.push(await denyWaiver(decision.fingerprint, decision.operatorNote, ctx, opts));
+            events.push(await denyWaiver(decision.fingerprint, decision.operatorNote, ctx, opts));
+            for (const finding of findingsByFingerprint.get(decision.fingerprint) ?? []) {
+                findingIdsToCarry.add(finding.finding_id);
+            }
         }
     }
-    return results;
+    return { events, findingIdsToCarry: [...findingIdsToCarry] };
 }

package/factory/orchestrator/dist/waveBudget.js

@@ -153,6 +153,7 @@ export function checkWaveBudget(events, policy, proposed, options) {
     if (options.epicId.trim().length === 0) {
         return {
             epicId: null,
+            tier: policy.tier,
             capTokens,
             measuredTokens: 0,
             projectedTokens: 0,
@@ -189,6 +190,7 @@ export function checkWaveBudget(events, policy, proposed, options) {
     const inFlight = inFlightTasks(events, epicId).length;
     const base = {
         epicId,
+        tier: policy.tier,
         capTokens,
         measuredTokens,
         projectedTokens,