@juzser/blacksmith 0.3.0 → 0.5.0

package/factory/orchestrator/dist/db/schema.js

@@ -19,7 +19,7 @@ import { index, integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
  * operator far more often than any §8 dimension, and forcing a taxonomy PR
  * per new project would defeat the point of a multi-project hub. Nullable
  * for migration safety (every event logged before this column existed has
- * no value here); queries.ts's helpers COALESCE it to 'black-smith' so old
+ * no value here); queries.ts's helpers COALESCE it to 'blacksmith' so old
  * rows and new single-project fixtures both resolve to the same default
  * project rather than an ungrouped null bucket.
  */
@@ -40,12 +40,19 @@ export const eventsRaw = sqliteTable('events_raw', {
     // agent one of the same event_type. Nullable for migration safety —
     // events logged before this column existed simply can't be attributed.
     actor: text('actor'),
+    // The CLI session that wrote the event (EventRecord.cli_session_id,
+    // architecture §7), so a live CLI session can be linked to the factory
+    // sessions it drives. Nullable: absent outside a CLI session and on every
+    // event logged before the stamp existed. A link, never evidence -- see
+    // events.ts's cliStamp.
+    cliSessionId: text('cli_session_id'),
 }, (t) => [
     index('events_raw_session_idx').on(t.sessionId),
     index('events_raw_task_idx').on(t.taskId),
     index('events_raw_type_idx').on(t.eventType),
     index('events_raw_ts_idx').on(t.ts),
     index('events_raw_project_idx').on(t.project),
+    index('events_raw_cli_session_idx').on(t.cliSessionId),
 ]);
 /** One row per session, folded from its session-start event + last-seen ts. */
 export const sessions = sqliteTable('sessions', {
@@ -128,12 +135,30 @@ export const tasks = sqliteTable('tasks', {
     taskStatus: text('task_status').notNull(),
     planVersion: integer('plan_version'),
     objective: text('objective'),
+    title: text('title'), // DS3 — optional human-facing title (task-spec field)
+    summary: text('summary'), // DS3 — optional human-facing summary (task-spec field)
     claims: text('claims'), // JSON array
     budgetTokens: integer('budget_tokens'),
     branch: text('branch'),
     createdAt: text('created_at').notNull(),
     updatedAt: text('updated_at').notNull(),
     project: text('project'), // Phase 6b — see eventsRaw's project comment above.
+    /**
+     * DS4 S5a round 2 — the `ts` of the event that FIRST moved this task into
+     * `TERMINAL_TASK_STATUSES` (wave-merged / task-superseded / an
+     * `error-logged` naming it `escalated` / an auditor's judge-reported or
+     * task-result-recorded, since an audit axis never joins a wave), null
+     * while the task is still open. `updatedAt` keeps moving after a task is
+     * done — a later `error-logged` naming an already-terminal task (e.g.
+     * from a following lessons/audit flow) rewrites it via `touch()` without
+     * reopening the task — so it is the wrong column for "when did this
+     * finish" (db/queries.ts's taskDateRange). Written once by
+     * db/projector.ts's foldTasks() and left alone after that, with one
+     * named exception: a later auditor dispatch_decision for a completed id
+     * (an audit axis re-run) resets this to null, since the row is open
+     * again.
+     */
+    terminalAt: text('terminal_at'),
 }, (t) => [
     index('tasks_session_idx').on(t.sessionId),
     index('tasks_epic_idx').on(t.epicId),
@@ -287,14 +312,14 @@ export const milestones = sqliteTable('milestones', {
     goal: text('goal'),
     epicIds: text('epic_ids').notNull(), // JSON array
     // Phase 6b — see eventsRaw's project comment above. roadmap.ts defaults
-    // an unspecified `- project:` bullet to 'black-smith' at parse time (not
+    // an unspecified `- project:` bullet to 'blacksmith' at parse time (not
     // left null here), since factory/specs/roadmap.md (ROADMAP_PATH) is a
     // hand-authored declaration, not an event replay — there is no "old row"
     // to migrate.
-    project: text('project').notNull().default('black-smith'),
+    project: text('project').notNull().default('blacksmith'),
     // Phase 10 -- 'factory' | 'dogfood' | 'product' (roadmap.ts's
     // MilestoneKind). Defaults to 'factory' here for the same reason project
-    // defaults to 'black-smith': the column default has to agree with what
+    // defaults to 'blacksmith': the column default has to agree with what
     // roadmap.ts resolves for a milestone that declares neither bullet, and
     // for those two that answer is the factory's own.
     kind: text('kind').notNull().default('factory'),
@@ -334,3 +359,31 @@ export const artifacts = sqliteTable('artifacts', {
     path: text('path').notNull(),
     description: text('description'),
 }, (t) => [index('artifacts_session_idx').on(t.sessionId), index('artifacts_task_idx').on(t.taskId)]);
+/**
+ * Operator feedback left mid-run on a task, from the dashboard or from
+ * GitHub (feedback.ts). A GLOBAL fold, the same shape as `lessons` and
+ * `findings` above and for the same reason (D-199/D-200): a comment can be
+ * recorded in one session and resolved in a later, continuing one, so the
+ * table's primary key is the feedback id, not (session, feedback) — one
+ * global key, one global fold, rewritten whole by
+ * db/projector.ts's projectOperatorFeedback().
+ */
+export const operatorFeedback = sqliteTable('operator_feedback', {
+    id: text('id').primaryKey(),
+    taskId: text('task_id').notNull(),
+    sessionId: text('session_id').notNull(),
+    body: text('body').notNull(),
+    kind: text('kind').notNull(),
+    source: text('source').notNull(),
+    externalId: text('external_id'),
+    author: text('author'),
+    recordedAt: text('recorded_at').notNull(),
+    recordedEventId: text('recorded_event_id').notNull(),
+    resolvedAt: text('resolved_at'),
+    resolution: text('resolution'),
+    followUpTaskId: text('follow_up_task_id'),
+}, (t) => [
+    index('operator_feedback_task_idx').on(t.taskId),
+    index('operator_feedback_session_idx').on(t.sessionId),
+    index('operator_feedback_external_idx').on(t.externalId),
+]);

package/factory/orchestrator/dist/declaredArtifactLine.js

@@ -0,0 +1,18 @@
+/**
+ * The `Declared artifact: <path>` line a judge dispatch carries in its prompt.
+ *
+ * A leaf module with no local imports, so the PreToolUse hook (which must stay
+ * free of the database layer), `judgeStopHook.ts`, and `dispatchLint.ts` all
+ * read the line with one parser: what the dispatch guard accepts is exactly
+ * what judge-stop later reads. `dispatchLint.ts` re-exports these.
+ */
+const DECLARED_ARTIFACT_LINE = /^Declared artifact:[ \t]*(\S+)[ \t]*$/m;
+/** `Declared artifact: <path>` in a dispatch prompt, or null when the line is not there. */
+export function parseDeclaredArtifactLine(prompt) {
+    const match = DECLARED_ARTIFACT_LINE.exec(prompt);
+    return match?.[1] ?? null;
+}
+/** The line a dispatch is expected to carry verbatim, given the ledger's declared path. */
+export function formatDeclaredArtifactLine(artifactPath) {
+    return `Declared artifact: ${artifactPath}`;
+}

package/factory/orchestrator/dist/delegation.js

@@ -26,6 +26,7 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { parse as parseYaml } from 'yaml';
+import { AGENT_PREFIX, agentNameFor, roleOfAgentType, roleOfTemplateFile, templateFileFor, } from './agentNames.js';
 import { DISPATCH_EVENT_TYPE, ERROR_EVENT_TYPE, TASK_RESULT_EVENT_TYPE, } from './agents-registry.js';
 import { SmithError } from './errors.js';
 import { ROOT_EVENT_TYPE } from './events.js';
@@ -84,11 +85,11 @@ export function loadDelegationPolicy(filePath = DELEGATION_POLICY_PATH) {
  * because a scoped grant contains commas of its own.
  */
 const AGENT_TOOL = /\bAgent\b/;
-/** The roles a scoped grant names, e.g. `Agent(coder, tester)`. */
+/** The agents a scoped grant names, e.g. `Agent(bs-coder, bs-tester)`. */
 const AGENT_SCOPE = /\bAgent\s*\(([^)]*)\)/;
 /** The raw `tools:` line of a role template's frontmatter. Null when there is no template. */
 function templateTools(dir, role) {
-    const file = path.join(dir, `${role}.md`);
+    const file = path.join(dir, templateFileFor(role));
     if (!existsSync(file))
         return null;
     return toolsOf(readFileSync(file, 'utf8'));
@@ -135,7 +136,7 @@ export function checkDelegationGrants(policy, options) {
         }
         for (const pair of options.isolationPairs) {
             if (pair.worker === grant.role && grant.mayDispatch.includes(pair.auditor)) {
-                problems.push(`\`${grant.role}\` may dispatch \`${pair.auditor}\`, its own auditor under crosscheck.yml \`role_isolation\`. The worker would choose and prompt its grader, and \`smith tester check\` would report the isolation it was reading evidence for.`);
+                problems.push(`\`${grant.role}\` may dispatch \`${pair.auditor}\`, its own auditor under crosscheck.yml \`role_isolation\`. The worker would choose and prompt its grader, and \`bs tester check\` would report the isolation it was reading evidence for.`);
             }
         }
         for (const pair of options.asymmetricPairs) {
@@ -145,10 +146,10 @@ export function checkDelegationGrants(policy, options) {
         }
         const tools = templateTools(dir, grant.role);
         if (tools === null) {
-            problems.push(`\`${grant.role}\` holds a grant but ships no template at ${path.join(path.basename(dir), `${grant.role}.md`)}, so the grant reaches no agent (D-191).`);
+            problems.push(`\`${grant.role}\` holds a grant but ships no template at ${path.join(path.basename(dir), templateFileFor(grant.role))}, so the grant reaches no agent (D-191).`);
         }
         else if (!holdsAgent(tools)) {
-            problems.push(`${grant.role}.md does not list \`Agent\` in \`tools\`, so the grant reaches no agent (D-191).`);
+            problems.push(`${templateFileFor(grant.role)} does not list \`Agent\` in \`tools\`, so the grant reaches no agent (D-191).`);
         }
         else {
             // A scoped grant is enforced by the harness at dispatch time and this
@@ -156,10 +157,20 @@ export function checkDelegationGrants(policy, options) {
             // of both: the file an operator reads is not the file that binds.
             const scope = agentScope(tools);
             if (scope !== null) {
-                const declared = [...grant.mayDispatch].sort().join(', ');
+                for (const name of scope) {
+                    if (name.startsWith(AGENT_PREFIX))
+                        continue;
+                    // Suggest a name only for a role this grant covers: `general-purpose`
+                    // maps to itself, and `bs-general-purpose` is no agent either.
+                    const role = roleOfAgentType(name);
+                    problems.push(role !== null && grant.mayDispatch.includes(role)
+                        ? `${templateFileFor(grant.role)} scopes \`Agent\` to name \`${name}\`, which is no agent; use \`${agentNameFor(role)}\`. The harness enforces the agent names, and the bare role no longer exists as one.`
+                        : `${templateFileFor(grant.role)} scopes \`Agent\` to name \`${name}\`, which is no Blacksmith agent. A scope names only the \`${AGENT_PREFIX}<role>\` agents of the roles delegation.yml grants.`);
+                }
+                const declared = [...grant.mayDispatch].map(agentNameFor).sort().join(', ');
                 const scoped = [...scope].sort().join(', ');
                 if (declared !== scoped) {
-                    problems.push(`${grant.role}.md scopes \`Agent\` to (${scoped}) while delegation.yml grants (${declared}). The template is what the harness enforces and the policy is what the audits read, so a disagreement is a rule nobody applies.`);
+                    problems.push(`${templateFileFor(grant.role)} scopes \`Agent\` to (${scoped}) while delegation.yml grants (${declared}). The template is what the harness enforces and the policy is what the audits read, so a disagreement is a rule nobody applies.`);
                 }
             }
         }
@@ -178,11 +189,13 @@ export function checkDelegationGrants(policy, options) {
     // The converse of D-191, and the one that actually widens the topology: a
     // template may hand itself `Agent` without any grant naming it, and nothing
     // else in the repo reads the frontmatter closely enough to notice.
-    const templates = existsSync(dir) ? readdirSync(dir).filter((f) => f.endsWith('.md')) : [];
+    const templates = existsSync(dir)
+        ? readdirSync(dir).filter((f) => roleOfTemplateFile(f) !== null)
+        : [];
     const granted = new Set(policy.grants.map((g) => g.role));
     let ungrantedHolders = 0;
     for (const file of templates) {
-        const role = path.basename(file, '.md');
+        const role = roleOfTemplateFile(file);
         if (granted.has(role))
             continue;
         if (!holdsAgent(toolsOf(readFileSync(path.join(dir, file), 'utf8'))))
@@ -210,19 +223,42 @@ export function checkDelegationGrants(policy, options) {
 }
 /**
  * How a dispatched turn is recorded as over, and which payload field names the
- * role that ended it -- testerAudit.ts's table, for its reason. The fallback to
- * `actor` is that file's too: the older half of the log names the role there
- * and nowhere else, and without it a finished wave-runner reads as one still
- * running, which is the difference between `violation` and `unverifiable`.
+ * role that ended it -- testerAudit.ts's table, for its reason. Each event type
+ * lists every key its role may be spelled under, tried in order, before the
+ * fallback to `actor`: that fallback is testerAudit.ts's too -- the older half
+ * of the log names the role there and nowhere else, and without it a finished
+ * wave-runner reads as one still running, which is the difference between
+ * `violation` and `unverifiable`.
+ *
+ * `error-logged` lists both `agent` (this module's long-standing read, the
+ * Result file's own spelling) and `agent_role` (the dispatch's) because a
+ * hand-written error event may carry only one of the two, so a role named
+ * either way still finds its terminal instead of falling through to
+ * whichever actor happened to log the error. agents-registry.ts's fold of
+ * the same event type accepts the same two keys, but tries `agent_role`
+ * first where this module tries `agent` first -- not symmetric in order,
+ * because each reader keeps its own historical key first rather than the two
+ * agreeing on one: `agent_role` was already this event type's only key in
+ * agents-registry.ts's fold before `agent` was added as a fallback there,
+ * same as `agent` was here before `agent_role` was added as this module's.
  */
-const TERMINAL_ROLE_KEY = {
-    [TASK_RESULT_EVENT_TYPE]: 'agent',
-    [ERROR_EVENT_TYPE]: 'agent',
+const TERMINAL_ROLE_KEYS = {
+    [TASK_RESULT_EVENT_TYPE]: ['agent'],
+    [ERROR_EVENT_TYPE]: ['agent', 'agent_role'],
 };
 function str(payload, key) {
     const value = payload[key];
     return typeof value === 'string' && value.length > 0 ? value : null;
 }
+/** The first of `keys` that names a non-empty string in `payload`, or null. */
+function firstStr(payload, keys) {
+    for (const key of keys) {
+        const value = str(payload, key);
+        if (value !== null)
+            return value;
+    }
+    return null;
+}
 function readDispatches(events) {
     const rows = [];
     for (const { event_id, record } of events) {
@@ -246,11 +282,11 @@ function readDispatches(events) {
 function readTerminals(events) {
     const rows = [];
     for (const { record } of events) {
-        const key = TERMINAL_ROLE_KEY[record.event_type];
-        if (key === undefined)
+        const keys = TERMINAL_ROLE_KEYS[record.event_type];
+        if (keys === undefined)
             continue;
         const payload = (record.payload ?? {});
-        const role = str(payload, key) ?? record.actor;
+        const role = firstStr(payload, keys) ?? record.actor;
         if (role === null || role.length === 0)
             continue;
         rows.push({
@@ -274,6 +310,37 @@ function sessionsOpenedByDispatch(events) {
     }
     return opened;
 }
+/**
+ * The role that dispatched this session, if this session is that dispatch's
+ * own log -- the answer a write wants before it defaults its `actor` to a
+ * placeholder like `system` (issue #218). A session's `session-start` names
+ * its entry edge as `causal_parent`; when that edge is a `dispatch_decision`
+ * event elsewhere in `events`, this session was opened against it and its
+ * owner is the role that dispatch named.
+ *
+ * Returns null for every session nothing dispatched -- an operator's own
+ * top-level session, or a `--continues` split whose entry edge names some
+ * other event (P9-7's cross-session edge is not only for delegation) -- so a
+ * caller's existing `system` fallback for "no owner" is unchanged.
+ *
+ * Deliberately reads the event graph only, not delegation.yml: it answers
+ * "who dispatched this session" for a dispatch to any role, granted or not.
+ * That is wider than `checkDelegationLog`'s rule 3, which flags a mismatch
+ * only for sessions a grant opened -- but a wider *default* cannot loosen
+ * that check, because an explicit `--actor` always wins over this inference
+ * (every caller checks `ctx.actor` first) and a foreign or `system` actor
+ * stamped that way is still exactly what rule 3 flags.
+ */
+export function sessionOwnerRole(events, sessionId) {
+    const root = events.find((e) => e.record.session_id === sessionId && e.record.event_type === ROOT_EVENT_TYPE);
+    const parentId = root?.record.causal_parent;
+    if (parentId === null || parentId === undefined)
+        return null;
+    const parent = events.find((e) => e.event_id === parentId);
+    if (parent === undefined || parent.record.event_type !== DISPATCH_EVENT_TYPE)
+        return null;
+    return str((parent.record.payload ?? {}), 'agent_role');
+}
 /**
  * Asserts delegation.yml against a lineage's log.
  *

package/factory/orchestrator/dist/diffstat.js

@@ -96,9 +96,10 @@ const GIT_OUTPUT_MAX_BUFFER = 32 * 1024 * 1024;
 /**
  * The declared diff cap is only worth writing down if something measures the
  * real diff. This does: committed work on a task branch, against the
- * integration branch it was cut from (`smith/<epic>/<task-id>` ->
- * `smith/<epic>/integration`, the same convention `collectCommittedChanges`
- * relies on), or against an explicit `baseRef`.
+ * integration branch it was cut from (`<prefix>/<epic>/<task-id>` ->
+ * `<prefix>/<epic>/integration`, the same convention `collectCommittedChanges`
+ * relies on — `<prefix>` is `bs` or the legacy `smith`, echoed back from the
+ * task branch itself), or against an explicit `baseRef`.
  *
  * It throws rather than returning zero when it cannot measure. A zero that
  * means "no diff" and a zero that means "I could not look" are the same number
@@ -140,7 +141,11 @@ export function measureDiff(worktreeDir, options = {}) {
     }
     return { baseRef, diffLines, excludedLines, unmeasuredFiles, files };
 }
-const TASK_BRANCH_PATTERN = /^smith\/(?<epic>[^/]+)\/(?<task>[^/]+)$/;
+// Operator decision 2 (bs-rename): a task branch is cut under whichever
+// prefix its integration branch already used — bs/ for a new epic, smith/
+// for one that still integrates there — so the base ref this derives must
+// echo the same prefix back, not hardcode the new one.
+const TASK_BRANCH_PATTERN = /^(?<prefix>smith|bs)\/(?<epic>[^/]+)\/(?<task>[^/]+)$/;
 function deriveBaseRef(worktreeDir) {
     let branch;
     try {
@@ -156,9 +161,11 @@ function deriveBaseRef(worktreeDir) {
         // directory git has never heard of, and it deserves a code like any other.
         throw new DiffstatError('diffstat.not-a-git-worktree', `Cannot read the current branch in ${worktreeDir} — it is not a git worktree, or git refused to answer.`, { worktreeDir, cause: err instanceof Error ? err.message : String(err) });
     }
-    const epic = TASK_BRANCH_PATTERN.exec(branch)?.groups?.epic;
-    if (epic === undefined) {
-        throw new DiffstatError('diffstat.cannot-derive-base-ref', `Branch "${branch}" does not follow smith/<epic>/<task-id>, so there is no integration branch to diff against. Pass an explicit baseRef.`, { branch, worktreeDir });
+    const groups = TASK_BRANCH_PATTERN.exec(branch)?.groups;
+    const epic = groups?.epic;
+    const prefix = groups?.prefix;
+    if (epic === undefined || prefix === undefined) {
+        throw new DiffstatError('diffstat.cannot-derive-base-ref', `Branch "${branch}" does not follow <smith|bs>/<epic>/<task-id>, so there is no integration branch to diff against. Pass an explicit baseRef.`, { branch, worktreeDir });
     }
-    return `smith/${epic}/integration`;
+    return `${prefix}/${epic}/integration`;
 }

package/factory/orchestrator/dist/dispatchLint.js

@@ -0,0 +1,108 @@
+/**
+ * `smith dispatch lint` — check a dispatch prompt against two things a
+ * dispatcher can get wrong without any signal until the agent runs:
+ *
+ *   - the turn budget stated in the prompt vs the role template's
+ *     `maxTurns:`, read fresh off disk (dispatch.md "Carry into the
+ *     prompt" — a prompt that promises more than the template is a fiction
+ *     the agent plans against and gets cut in the middle of).
+ *   - a judge prompt's declared-artifact line vs what the ledger recorded
+ *     for its `judge dispatch` (dispatch.md "Declare each judge's
+ *     artifact" — a judge prompt missing that line is undetectable until
+ *     the report never lands).
+ *
+ * Both parsers and both comparisons live here so the two checks stay one
+ * source of truth for "what does a compliant dispatch prompt say", rather
+ * than every dispatcher re-deriving it.
+ */
+import path from 'node:path';
+import { readTemplateMaxTurns } from './agentsSync.js';
+import { formatDeclaredArtifactLine, parseDeclaredArtifactLine } from './declaredArtifactLine.js';
+import { JUDGE_ROLES } from './judgeRoles.js';
+import { readJudgeTurns } from './judges.js';
+import { AGENTS_DIR } from './paths.js';
+/**
+ * Re-exported, not re-declared (judgeRoles.ts is the canonical source, kept
+ * dependency-free so both this module and judges.ts can import it without a
+ * cycle -- see that file for the full set and why it is these six). This
+ * module still does its own, stricter artifact check on top of the shared
+ * set: only these six get a `mismatch`/`missing` verdict, so a coder's
+ * dispatch (never carries one) reads `not-applicable` rather than a false
+ * `undeclared`.
+ */
+export { formatDeclaredArtifactLine, JUDGE_ROLES, parseDeclaredArtifactLine };
+const JUDGE_ROLE_SET = new Set(JUDGE_ROLES);
+const TURN_BUDGET_LINE = /Turn budget:[ \t]*(\S*)/g;
+/**
+ * `Turn budget: <n>` in a dispatch prompt — mid-sentence or on its own
+ * line, since a dispatch's leading line names the role and the budget in
+ * one breath ("Role: coder. Turn budget: 40 ..."). Null for no occurrence,
+ * more than one (two numbers is no number), or a value that is not a bare
+ * non-negative integer — every one of those is "cannot state a turn count",
+ * not "states zero".
+ */
+export function parseStatedTurns(prompt) {
+    const matches = [...prompt.matchAll(TURN_BUDGET_LINE)];
+    if (matches.length !== 1)
+        return null;
+    const raw = matches[0]?.[1] ?? '';
+    return /^[0-9]+$/.test(raw) ? Number(raw) : null;
+}
+function checkTurns(prompt, role, agentsDir) {
+    const stated = parseStatedTurns(prompt);
+    const template = readTemplateMaxTurns(agentsDir, role) ?? null;
+    if (template === null)
+        return { status: 'unverifiable', stated, template: null };
+    if (stated === null)
+        return { status: 'missing', stated: null, template };
+    if (stated === template)
+        return { status: 'ok', stated, template };
+    return { status: stated < template ? 'under' : 'over', stated, template };
+}
+async function checkArtifact(prompt, role, taskId, sessionId, eventOpts) {
+    if (!JUDGE_ROLE_SET.has(role)) {
+        return { status: 'not-applicable', expected_line: null, declared_line: null };
+    }
+    const declaredLine = parseDeclaredArtifactLine(prompt);
+    const turns = await readJudgeTurns(taskId, { sessionId }, eventOpts);
+    const turn = turns.find((t) => t.role === role);
+    if (turn === undefined) {
+        return { status: 'undeclared', expected_line: null, declared_line: declaredLine };
+    }
+    const expectedLine = formatDeclaredArtifactLine(turn.declaredArtifact);
+    if (declaredLine === null) {
+        return { status: 'missing', expected_line: expectedLine, declared_line: null };
+    }
+    if (!path.isAbsolute(declaredLine)) {
+        return { status: 'relative', expected_line: expectedLine, declared_line: declaredLine };
+    }
+    if (declaredLine === turn.declaredArtifact) {
+        return { status: 'ok', expected_line: expectedLine, declared_line: declaredLine };
+    }
+    return { status: 'mismatch', expected_line: expectedLine, declared_line: declaredLine };
+}
+// Fail closed: every status but "ok" exits non-zero, including "under" (a
+// prompt that understates the template's budget still disagrees with it) and
+// "unverifiable" (an unreadable template is not a pass, exactly like `dispatch
+// check`, `tester check`, `delegation check`, and `escalation check` already
+// treat "cannot tell" as a failure, never a maybe).
+const TURNS_FAIL = new Set(['under', 'over', 'missing', 'unverifiable']);
+const ARTIFACT_FAIL = new Set([
+    'missing',
+    'relative',
+    'mismatch',
+    'undeclared',
+]);
+/**
+ * Lint one dispatch prompt. Never throws on a bad prompt — a bad prompt is
+ * exactly the finding this reports — only on a missing task/session (the
+ * caller's own mistake, same as every other verb that reads the ledger).
+ */
+export async function lintDispatchPrompt(input) {
+    const agentsDir = input.agentsDir ?? AGENTS_DIR;
+    const eventOpts = input.eventOpts ?? {};
+    const turns = checkTurns(input.prompt, input.role, agentsDir);
+    const artifact = await checkArtifact(input.prompt, input.role, input.taskId, input.sessionId, eventOpts);
+    const exitCode = TURNS_FAIL.has(turns.status) || ARTIFACT_FAIL.has(artifact.status) ? 1 : 0;
+    return { turns, artifact, exitCode };
+}

package/factory/orchestrator/dist/effort.js

@@ -2,7 +2,7 @@ import { readFileSync } from 'node:fs';
 import { parse as parseYaml } from 'yaml';
 import { SmithError } from './errors.js';
 import { EFFORT_POLICY_PATH } from './paths.js';
-import { EFFORT_TIERS, isEffortTier } from './plan.js';
+import { EFFORT_TIERS, isEffortTier, isUiAffecting, } from './plan.js';
 import { evaluatePlanSecurityTriggers } from './planQuorum.js';
 /**
  * How much judgment an epic buys — factory/policies/effort.yml's host.
@@ -51,7 +51,10 @@ function tierRank(tier) {
     return EFFORT_TIERS.indexOf(tier);
 }
 const PRE_CODE_RESEARCH = ['when-needed', 'never'];
-const PRE_CODE_UIUX = ['always', 'when-ui-criterion', 'never'];
+// 'never' is not a parseable value: wave.md already says preCodeUiux cannot
+// be turned off, so a policy file that still spells it out should fail to
+// parse rather than silently skip the uiux judge turn on every UI task (U2).
+const PRE_CODE_UIUX = ['always', 'when-ui-criterion'];
 const SPEC_REVIEW_ROUNDS = ['until-clean', 'single-pass'];
 const PLAN_QUORUM = ['always', 'when-triggered'];
 const CLOSING_SPEC_REVIEW = ['always', 'when-plan-amended'];
@@ -86,6 +89,15 @@ function requireStringList(value, where, minLength) {
     }
     return value.map(String);
 }
+/**
+ * Whether a task must get the uiux judge turn: either the task itself is
+ * flagged `ui_affecting` (plan.ts isUiAffecting), or the tier's own profile
+ * says every task does (`preCodeUiux: 'always'`). `when-ui-criterion` adds
+ * nothing here — that arm is read off the flag already.
+ */
+export function requiresUiux(spec, profile) {
+    return isUiAffecting(spec) || profile.preCodeUiux === 'always';
+}
 function parseProfile(node, tier) {
     const t = requireNode(node, `tiers.${tier}`);
     const summary = typeof t.summary === 'string' ? t.summary.trim() : '';

package/factory/orchestrator/dist/effortTiers.js

@@ -0,0 +1,13 @@
+/**
+ * How much judgment an epic buys, cheapest first — factory/policies/effort.yml
+ * declares what each tier means; this is only the closed list of names.
+ *
+ * A leaf module on purpose: plan.ts types `PlanFile.effort` with it, budgets.ts
+ * sizes its caps by it, and effort.ts is the semantic owner. plan.ts imports
+ * budgets.ts and effort.ts (transitively) imports plan.ts, so the list can live
+ * in none of them without an import cycle. plan.ts and effort.ts re-export it.
+ */
+export const EFFORT_TIERS = ['small', 'medium', 'huge'];
+export function isEffortTier(value) {
+    return typeof value === 'string' && EFFORT_TIERS.includes(value);
+}

package/factory/orchestrator/dist/env.js

@@ -0,0 +1,26 @@
+/** The current and legacy namespace prefixes, for call sites that filter a whole env object rather than read one name (e.g. `testgate.ts`'s `projectCommandEnv`). */
+export const BS_PREFIX = 'BS_';
+export const LEGACY_PREFIX = 'SMITH_';
+/**
+ * The one place that knows `BS_<X>` is the current name and `SMITH_<X>` is
+ * the transitional fallback (operator decision 3, bs-rename): `BS_` wins
+ * when both are set, `SMITH_` is read when `BS_` is unset, and neither set
+ * reads as unset — exactly what every direct `env.SMITH_*`/`env.BS_*` read
+ * in this codebase should go through instead of hand-rolling the pair.
+ *
+ * `name` may be spelled either way — as the new `BS_<X>` name, or as the
+ * legacy `SMITH_<X>` name a call site's own constant still carries — since
+ * both resolve to the same pair of variables either way.
+ */
+export function readEnv(env, name) {
+    const bsName = name.startsWith(LEGACY_PREFIX)
+        ? `${BS_PREFIX}${name.slice(LEGACY_PREFIX.length)}`
+        : name;
+    const legacyName = name.startsWith(BS_PREFIX)
+        ? `${LEGACY_PREFIX}${name.slice(BS_PREFIX.length)}`
+        : name;
+    const bsValue = env[bsName];
+    if (bsValue !== undefined)
+        return bsValue;
+    return env[legacyName];
+}