@juzser/blacksmith 0.3.0 → 0.5.0

package/factory/orchestrator/dist/budgets.js

@@ -10,34 +10,122 @@
 // against the event log by src/escalation.ts. `context_window` and
 // `effort_scaling` are still prompt-level: agents read them from their own
 // templates, and nothing here parses them.
+//
+// Every number is sized per effort tier (effort.yml's small / medium / huge,
+// the tier being the epic plan's `effort`). budgets.yml declares the epic cap
+// as an explicit triplet and each task cap once, at medium, with one
+// `task_tier_scale` multiplying them for the other tiers. A policy is loaded
+// FOR a tier: parseBudgetPolicy / loadBudgetPolicy take it, and a caller with
+// no plan in hand gets effort.yml's `default_tier`.
 import { readFileSync } from 'node:fs';
 import { parse as parseYaml } from 'yaml';
+import { EFFORT_TIERS, isEffortTier } from './effortTiers.js';
+import { readEnv } from './env.js';
 import { SmithError } from './errors.js';
-import { BUDGETS_POLICY_PATH } from './paths.js';
+import { BUDGETS_POLICY_PATH, EFFORT_POLICY_PATH } from './paths.js';
 export class BudgetError extends SmithError {
 }
 /**
- * Deliberately NOT the number budgets.yml declares (4,000,000 since
- * 2026-08-11) — the one default here that does not mirror the policy file.
+ * The roles budgets.yml prices, one cap each. Every other role the factory
+ * dispatches (merger, uiux, scribe, wave-runner) has no cap, and
+ * src/budgetAlarm.ts reports a dispatch of one as a hole rather than as free.
+ */
+export const PRICED_ROLES = [
+    'coder',
+    'tester',
+    'planner',
+    'researcher',
+    'spec-reviewer',
+    'grader',
+    'reviewer',
+    'verifier',
+    'security-reviewer',
+    'auditor',
+];
+export function isPricedRole(role) {
+    return PRICED_ROLES.includes(role);
+}
+/**
+ * Deliberately NOT the number budgets.yml declares (a 4M / 16M / 32M triplet
+ * since 2026-09-29) — the one default here that does not mirror the policy
+ * file, and the same number at every tier.
  *
- * The other DEFAULT_* constants below match budgets.yml because nobody has
- * ever had cause to diverge them. This one has cause: the repo's cap was
- * raised by an operator decision sized from a single dogfood epic that
- * measured 1,529,963 tokens for two of four tasks, a figure inflated by
- * rework `smith escalation check` recorded as ladder violations. That is a
- * judgement about this repo's epics, not a floor to hand a project that
- * shipped no policy at all — such a project gets the conservative number and
- * an alarm that fires early, which is the failure direction to prefer.
+ * The other DEFAULT_* numbers below match budgets.yml's medium tier because
+ * nobody has ever had cause to diverge them. This one has cause: the repo's
+ * cap was raised by operator decisions sized from this repo's own dogfood
+ * epics. That is a judgement about this repo's epics, not a floor to hand a
+ * project that shipped no policy at all — such a project gets the
+ * conservative number and an alarm that fires early, which is the failure
+ * direction to prefer.
  *
  * Do not "fix" the mismatch by syncing them.
  */
 const DEFAULT_EPIC_CAP_TOKENS = 2_000_000;
 const DEFAULT_EPIC_ALARM_RATIO = 0.7;
-const DEFAULT_CODER_CAP_TOKENS = 150_000;
-const DEFAULT_CODER_CAP_DIFF_LINES = 400;
-const DEFAULT_RESEARCHER_CAP_TOKENS = 60_000;
-const DEFAULT_JUDGES_CAP_TOKENS = 40_000;
+const DEFAULT_CODER_CAP_DIFF_LINES = 700;
+/** budgets.yml's medium-tier task caps. */
+const DEFAULT_TASK_CAP_TOKENS = Object.freeze({
+    coder: 220_000,
+    tester: 60_000,
+    planner: 110_000,
+    researcher: 80_000,
+    'spec-reviewer': 170_000,
+    grader: 110_000,
+    reviewer: 60_000,
+    verifier: 40_000,
+    'security-reviewer': 80_000,
+    auditor: 90_000,
+});
+const DEFAULT_TASK_TIER_SCALE = Object.freeze({
+    small: 0.5,
+    medium: 1,
+    huge: 2,
+});
 const DEFAULT_PRE_CODE_SHARE_MAX = 0.15;
+/**
+ * The four judges a pre-2026-09-29 budgets.yml priced together under
+ * `task.judges`. Still read, below a role the file names itself, so an older
+ * policy file keeps its numbers.
+ */
+const LEGACY_JUDGE_BUCKET_ROLES = [
+    'spec-reviewer',
+    'reviewer',
+    'verifier',
+    'grader',
+];
+/**
+ * effort.yml's `default_tier`, read directly rather than through effort.ts:
+ * effort.ts imports plan.ts, and plan.ts imports this module. Read on every
+ * call, not cached: the file is small, and a process that outlives an edit to
+ * it (the daemon) must not keep budgeting at the tier it read first. A file
+ * that cannot be read, or whose `default_tier` is missing or names no tier, is
+ * refused the way effort.ts refuses it — a typo there must not quietly size
+ * every untiered epic at `medium`.
+ */
+function defaultBudgetTier(effortPolicyFile = EFFORT_POLICY_PATH) {
+    let doc;
+    try {
+        doc = parseYaml(readFileSync(effortPolicyFile, 'utf8'));
+    }
+    catch (error) {
+        throw new BudgetError('budgets.invalid-policy', `Cannot read effort.yml's default_tier from ${effortPolicyFile}: ${error.message}. A budget with no tier named is sized at that tier, so there is no budget without it.`, { file: effortPolicyFile });
+    }
+    const tier = doc?.default_tier;
+    if (!isEffortTier(tier)) {
+        throw new BudgetError('budgets.invalid-policy', `effort.yml default_tier must be one of ${EFFORT_TIERS.join(', ')}; got ${JSON.stringify(tier ?? null)} in ${effortPolicyFile}.`, { file: effortPolicyFile, field: 'default_tier', value: tier ?? null });
+    }
+    return tier;
+}
+/**
+ * The tier a budget is sized for: the given one when it names an effort tier,
+ * otherwise effort.yml's `default_tier`. An absent or unknown value is "no
+ * tier chosen", never an error — plan validation owns refusing a bad
+ * `effort`. Callers holding a plan pass epicBudget.ts `budgetTierForPlan`,
+ * which applies the security floor; a plan's raw `effort` is not its tier.
+ */
+export function resolveBudgetTier(tier, effortPolicyFile) {
+    return isEffortTier(tier) ? tier : defaultBudgetTier(effortPolicyFile);
+}
 function optionalString(value) {
     return typeof value === 'string' && value.length > 0 ? value : null;
 }
@@ -118,48 +206,154 @@ function capNumberOrNull(field, value) {
     }
     return value;
 }
-export function parseBudgetPolicy(yamlText) {
+/**
+ * `epic.cap_tokens` for `tier`. A scalar is one cap for every tier (the shape
+ * before 2026-09-29, still accepted); a mapping must name all three tiers —
+ * a triplet missing one is refused whichever tier is being read, because the
+ * missing tier's epics would otherwise fall to a default nobody chose, and so
+ * is a key that names no tier (`hughe:`), which would leave its number unread.
+ */
+function epicCapFor(raw, tier) {
+    if (raw === undefined || raw === null)
+        return DEFAULT_EPIC_CAP_TOKENS;
+    if (typeof raw !== 'object' || Array.isArray(raw))
+        return capNumber('epic.cap_tokens', raw);
+    const byTier = raw;
+    const unknown = Object.keys(byTier).filter((key) => !isEffortTier(key));
+    if (unknown.length > 0) {
+        throw new BudgetError('budgets.invalid-policy', `budgets.yml epic.cap_tokens names ${unknown.map((k) => `"${k}"`).join(', ')}, which ${unknown.length === 1 ? 'is not an effort tier' : 'are not effort tiers'}; the keys are ${EFFORT_TIERS.join(', ')}.`, { field: 'epic.cap_tokens', unknown, allowed: [...EFFORT_TIERS] });
+    }
+    const caps = Object.fromEntries(EFFORT_TIERS.map((t) => [t, capNumber(`epic.cap_tokens.${t}`, byTier[t])]));
+    return caps[tier];
+}
+function tierScale(raw, tier) {
+    const scales = Object.fromEntries(EFFORT_TIERS.map((t) => [
+        t,
+        capNumber(`task_tier_scale.${t}`, raw?.[t] ?? DEFAULT_TASK_TIER_SCALE[t]),
+    ]));
+    return scales[tier];
+}
+/**
+ * budgets.yml sized for `tier` (plan `effort`; absent or unknown reads as
+ * effort.yml's `default_tier`). Task caps are declared at medium and scaled by
+ * `task_tier_scale`; the epic cap is read per tier as declared.
+ */
+export function parseBudgetPolicy(yamlText, tier) {
+    const resolved = resolveBudgetTier(tier);
     const doc = (parseYaml(yamlText) ?? {});
+    const scale = tierScale(doc.task_tier_scale, resolved);
+    const scaled = (n) => Math.round(n * scale);
+    const legacyJudges = doc.task?.judges?.cap_tokens === undefined
+        ? null
+        : capNumber('task.judges.cap_tokens', doc.task.judges.cap_tokens);
+    const medium = (role) => {
+        const declared = doc.task?.[role]?.cap_tokens;
+        if (declared !== undefined)
+            return capNumber(`task.${role}.cap_tokens`, declared);
+        if (legacyJudges !== null && LEGACY_JUDGE_BUCKET_ROLES.includes(role))
+            return legacyJudges;
+        return DEFAULT_TASK_CAP_TOKENS[role];
+    };
+    const task = Object.fromEntries(PRICED_ROLES.map((role) => [role, { capTokens: scaled(medium(role)) }]));
+    task.coder = {
+        capTokens: task.coder.capTokens,
+        capDiffLines: scaled(capNumber('task.coder.cap_diff_lines', doc.task?.coder?.cap_diff_lines ?? DEFAULT_CODER_CAP_DIFF_LINES)),
+    };
     return {
+        tier: resolved,
         epic: {
-            capTokens: capNumber('epic.cap_tokens', doc.epic?.cap_tokens ?? DEFAULT_EPIC_CAP_TOKENS),
+            capTokens: epicCapFor(doc.epic?.cap_tokens, resolved),
             alarmRatio: capNumber('epic.alarm_ratio', doc.epic?.alarm_ratio ?? DEFAULT_EPIC_ALARM_RATIO),
             maxInFlightTasks: capNumberOrNull('epic.max_in_flight_tasks', doc.epic?.max_in_flight_tasks ?? null),
         },
-        task: {
-            coder: {
-                capTokens: capNumber('task.coder.cap_tokens', doc.task?.coder?.cap_tokens ?? DEFAULT_CODER_CAP_TOKENS),
-                capDiffLines: capNumber('task.coder.cap_diff_lines', doc.task?.coder?.cap_diff_lines ?? DEFAULT_CODER_CAP_DIFF_LINES),
-            },
-            researcher: {
-                capTokens: capNumber('task.researcher.cap_tokens', doc.task?.researcher?.cap_tokens ?? DEFAULT_RESEARCHER_CAP_TOKENS),
-            },
-            judges: {
-                capTokens: capNumber('task.judges.cap_tokens', doc.task?.judges?.cap_tokens ?? DEFAULT_JUDGES_CAP_TOKENS),
-            },
-        },
+        task,
         preCodeBudget: {
             shareOfEpicBudgetMax: capNumber('pre_code_budget.share_of_epic_budget_max', doc.pre_code_budget?.share_of_epic_budget_max ?? DEFAULT_PRE_CODE_SHARE_MAX),
         },
         escalationLadder: parseEscalationLadder(doc.escalation_ladder?.rungs),
     };
 }
-const INT_OVERRIDES = [
-    ['SMITH_EPIC_CAP_TOKENS', 'epicCap'],
-    ['SMITH_EPIC_MAX_IN_FLIGHT_TASKS', 'maxInFlight'],
-    ['SMITH_TASK_CODER_CAP_TOKENS', 'coderCap'],
-    ['SMITH_TASK_CODER_CAP_DIFF_LINES', 'coderDiff'],
-    ['SMITH_TASK_RESEARCHER_CAP_TOKENS', 'researcherCap'],
-    ['SMITH_TASK_JUDGES_CAP_TOKENS', 'judgesCap'],
+/**
+ * The declared per-dispatch cap for `role` in this policy's tier, or null when
+ * budgets.yml prices no such role.
+ */
+export function roleCapTokens(policy, role) {
+    return isPricedRole(role) ? policy.task[role].capTokens : null;
+}
+function envNameForRole(role) {
+    return `SMITH_TASK_${role.toUpperCase().replace(/-/g, '_')}_CAP_TOKENS`;
+}
+const ENV_FIELDS = [
+    {
+        name: 'SMITH_EPIC_CAP_TOKENS',
+        kind: 'int',
+        read: (p) => p.epic.capTokens,
+        write: (p, v) => {
+            p.epic.capTokens = v;
+        },
+    },
+    {
+        name: 'SMITH_EPIC_ALARM_RATIO',
+        kind: 'ratio',
+        read: (p) => p.epic.alarmRatio,
+        write: (p, v) => {
+            p.epic.alarmRatio = v;
+        },
+    },
+    {
+        name: 'SMITH_EPIC_MAX_IN_FLIGHT_TASKS',
+        kind: 'int',
+        read: (p) => p.epic.maxInFlightTasks,
+        write: (p, v) => {
+            p.epic.maxInFlightTasks = v;
+        },
+    },
+    {
+        name: envNameForRole('coder'),
+        kind: 'int',
+        read: (p) => p.task.coder.capTokens,
+        write: (p, v) => {
+            p.task.coder.capTokens = v;
+        },
+    },
+    {
+        name: 'SMITH_TASK_CODER_CAP_DIFF_LINES',
+        kind: 'int',
+        read: (p) => p.task.coder.capDiffLines,
+        write: (p, v) => {
+            p.task.coder.capDiffLines = v;
+        },
+    },
+    ...PRICED_ROLES.filter((role) => role !== 'coder').map((role) => ({
+        name: envNameForRole(role),
+        kind: 'int',
+        read: (p) => p.task[role].capTokens,
+        write: (p, v) => {
+            p.task[role].capTokens = v;
+        },
+    })),
 ];
-const RATIO_OVERRIDE = 'SMITH_EPIC_ALARM_RATIO';
-export const BUDGET_ENV_VARS = Object.freeze([
-    'SMITH_EPIC_CAP_TOKENS',
-    RATIO_OVERRIDE,
-    ...INT_OVERRIDES.slice(1).map(([name]) => name),
-]);
+/**
+ * The pre-2026-09-29 name for the four judges' shared cap. Still honoured —
+ * below each judge's own name — so a `.env` copied from an older
+ * `.env.example` keeps working; no longer listed there.
+ */
+const LEGACY_JUDGES_ENV = 'SMITH_TASK_JUDGES_CAP_TOKENS';
+const TIER_SUFFIXES = EFFORT_TIERS.map((t) => `_${t.toUpperCase()}`);
+function tierSuffix(tier) {
+    return `_${tier.toUpperCase()}`;
+}
+/** The documented budget env names, each one bare (the tier variants aside). */
+export const BUDGET_ENV_VARS = Object.freeze(ENV_FIELDS.map((f) => f.name));
+/** Names still read for compatibility but no longer documented. */
+export const LEGACY_BUDGET_ENV_VARS = Object.freeze([LEGACY_JUDGES_ENV]);
+/** Every name the overlay reads: bare, legacy, and each one's tier variants. */
+export const ALL_BUDGET_ENV_NAMES = Object.freeze([...BUDGET_ENV_VARS, ...LEGACY_BUDGET_ENV_VARS].flatMap((name) => [
+    name,
+    ...TIER_SUFFIXES.map((suffix) => `${name}${suffix}`),
+]));
 function envValue(env, name) {
-    const value = env[name];
+    const value = readEnv(env, name);
     return value === undefined || value === '' ? null : value;
 }
 /**
@@ -182,59 +376,83 @@ function envRatio(name, raw) {
     }
     return value;
 }
+function parseEnv(name, kind, raw) {
+    return kind === 'ratio' ? envRatio(name, raw) : envPositiveInt(name, raw);
+}
 /**
- * `policy` with every set budget env name applied on top. Pure: it reads only
- * `env` and returns a new policy. Every name is validated before any is
- * applied, so a bad value refuses the whole overlay rather than half of it.
+ * The name that supplies `field` for `tier`, or null: the tier variant, else
+ * the bare name, else (for the four old bucket judges) the legacy name with
+ * the same two-step precedence.
  */
-export function applyBudgetEnv(policy, env) {
-    const ints = new Map();
-    for (const [name, field] of INT_OVERRIDES) {
+function supplierFor(field, tier, env) {
+    const candidates = [`${field.name}${tierSuffix(tier)}`, field.name];
+    const role = PRICED_ROLES.find((r) => envNameForRole(r) === field.name);
+    if (role !== undefined && LEGACY_JUDGE_BUCKET_ROLES.includes(role)) {
+        candidates.push(`${LEGACY_JUDGES_ENV}${tierSuffix(tier)}`, LEGACY_JUDGES_ENV);
+    }
+    return candidates.find((name) => envValue(env, name) !== null) ?? null;
+}
+/**
+ * Every set name is validated — every tier's variant, not only this policy's
+ * — before any is applied, so a bad value refuses the whole overlay rather
+ * than half of it, and a typo in a tier not in play today is caught today.
+ */
+function validateBudgetEnv(env) {
+    for (const field of ENV_FIELDS) {
+        for (const name of [field.name, ...TIER_SUFFIXES.map((s) => `${field.name}${s}`)]) {
+            const raw = envValue(env, name);
+            if (raw !== null)
+                parseEnv(name, field.kind, raw);
+        }
+    }
+    for (const name of [LEGACY_JUDGES_ENV, ...TIER_SUFFIXES.map((s) => `${LEGACY_JUDGES_ENV}${s}`)]) {
         const raw = envValue(env, name);
         if (raw !== null)
-            ints.set(field, envPositiveInt(name, raw));
+            envPositiveInt(name, raw);
     }
-    const rawRatio = envValue(env, RATIO_OVERRIDE);
-    const ratio = rawRatio === null ? null : envRatio(RATIO_OVERRIDE, rawRatio);
-    return {
-        ...policy,
-        epic: {
-            capTokens: ints.get('epicCap') ?? policy.epic.capTokens,
-            alarmRatio: ratio ?? policy.epic.alarmRatio,
-            maxInFlightTasks: ints.get('maxInFlight') ?? policy.epic.maxInFlightTasks,
-        },
-        task: {
-            coder: {
-                capTokens: ints.get('coderCap') ?? policy.task.coder.capTokens,
-                capDiffLines: ints.get('coderDiff') ?? policy.task.coder.capDiffLines,
-            },
-            researcher: { capTokens: ints.get('researcherCap') ?? policy.task.researcher.capTokens },
-            judges: { capTokens: ints.get('judgesCap') ?? policy.task.judges.capTokens },
-        },
-    };
+}
+/**
+ * `policy` with every set budget env name applied on top, for the policy's
+ * own tier. Pure: it reads only `env` and returns a new policy.
+ */
+export function applyBudgetEnv(policy, env) {
+    validateBudgetEnv(env);
+    const next = structuredClone(policy);
+    for (const field of ENV_FIELDS) {
+        const supplier = supplierFor(field, policy.tier, env);
+        if (supplier === null)
+            continue;
+        field.write(next, parseEnv(supplier, field.kind, envValue(env, supplier)));
+    }
+    return next;
 }
 /**
  * The budget env names whose value actually changed a number of `base` (the
- * policy as budgets.yml has it) — names only, never values — so a report that
- * prints an effective cap can say it did not come from budgets.yml. A name
- * set to the value budgets.yml already holds overrode nothing and is left
- * out: `.env.example` ships every knob at its default, so a copied `.env`
- * sets all of them.
+ * policy as budgets.yml has it, for its tier) — names only, never values — so
+ * a report that prints an effective cap can say it did not come from
+ * budgets.yml. Each is the name that won for that tier: a variant for another
+ * tier supplies nothing here and is left out. A name set to the value
+ * budgets.yml already holds overrode nothing and is left out too.
  */
 export function budgetEnvOverrides(base, env = process.env) {
-    return BUDGET_ENV_VARS.filter((name) => {
-        if (envValue(env, name) === null)
-            return false;
-        const alone = applyBudgetEnv(base, { [name]: env[name] });
-        return JSON.stringify(alone) !== JSON.stringify(base);
-    });
+    validateBudgetEnv(env);
+    const names = [];
+    for (const field of ENV_FIELDS) {
+        const supplier = supplierFor(field, base.tier, env);
+        if (supplier === null || names.includes(supplier))
+            continue;
+        const value = parseEnv(supplier, field.kind, envValue(env, supplier));
+        if (value !== field.read(base))
+            names.push(supplier);
+    }
+    return names;
 }
 /**
- * budgets.yml, with the box's env overrides on top. Every consumer reads the
- * policy through here, so an override reaches all of them or none.
+ * budgets.yml for `tier`, with the box's env overrides on top. Every consumer
+ * reads the policy through here, so an override reaches all of them or none.
  */
-export function loadBudgetPolicy(filePath = BUDGETS_POLICY_PATH, env = process.env) {
-    return applyBudgetEnv(parseBudgetPolicy(readFileSync(filePath, 'utf8')), env);
+export function loadBudgetPolicy(filePath = BUDGETS_POLICY_PATH, env = process.env, tier) {
+    return applyBudgetEnv(parseBudgetPolicy(readFileSync(filePath, 'utf8'), tier), env);
 }
 /**
  * For each field a task budget may declare, the mechanism that reads it — or
@@ -248,7 +466,7 @@ export function loadBudgetPolicy(filePath = BUDGETS_POLICY_PATH, env = process.e
  *
  * `max_turns` is null on purpose, and not because the wiring is pending: the
  * turn limit lives in the dispatch harness, which reads the role template's
- * `maxTurns` (`.claude/agents/<role>.md`) — per role, never per task
+ * `maxTurns` (`.claude/agents/bs-<role>.md`) — per role, never per task
  * (agent-interviews.md M-4, answered (c) on 2026-08-05 and corrected
  * 2026-09-11 once the cap was measured). A plan cannot raise or lower a
  * role's ceiling, so a number here would be a second copy the harness never

package/factory/orchestrator/dist/claims.js

@@ -4,7 +4,7 @@ import { parse as parseYaml } from 'yaml';
 import { SmithError } from './errors.js';
 import { runGit, runGitRaw } from './git.js';
 import { WORKTREE_POLICY_PATH } from './paths.js';
-import { HELD_OPEN_BY_AN_OPERATOR, TERMINAL_TASK_STATUSES } from './taskStatus.js';
+import { CLOSED_TO_FURTHER_WORK } from './taskStatus.js';
 export class ClaimsError extends SmithError {
 }
 function splitPathSegments(p) {
@@ -467,20 +467,10 @@ export function resolveFindingOwner(filePath, tasks) {
     }
     return { owner: 'resolved', taskId: topId, claim: top.claim };
 }
-/**
- * Task statuses that mean "this task's diff is closed to further work". A
- * finding routed to one of these has nobody to fix it — the branch already
- * landed (`completed`), the team already accepted the gap (`waived`), or a
- * later plan version replaced the task outright (`superseded`).
- *
- * That is every terminal status except the ones an operator is still holding:
- * a finding about a `failed` or `escalated` task's files belongs on that task
- * rather than on a new one competing for the same claims. The exception is
- * declared in taskStatus.ts as HELD_OPEN_BY_AN_OPERATOR and subtracted here,
- * so the three strings this used to name by hand come from the roster the
- * dimension already keeps rather than from a fourth copy of it.
- */
-const CLOSED_TO_FURTHER_WORK = new Set([...TERMINAL_TASK_STATUSES].filter((status) => !HELD_OPEN_BY_AN_OPERATOR.has(status)));
+// CLOSED_TO_FURTHER_WORK (taskStatus.ts): a finding routed to one of those
+// statuses has nobody to fix it. A finding about a `failed` or `escalated`
+// task's files belongs on that task rather than on a new one competing for
+// the same claims, which is why the operator-held pair is subtracted.
 /**
  * Where a finding should land, given who owns its file (D-41/P9-24).
  *
@@ -559,9 +549,9 @@ export function classifyChanges(changedFiles, patterns, violationCode = 'contrac
  *
  * Collector A (P9-3): what this task branch committed, against the integration
  * branch it was cut from — derived from the branch naming convention
- * smith/<epic>/<task-id> -> smith/<epic>/integration (worktree.yml
- * `integration_branch.pattern`; a bare "smith/<epic>" ref cannot coexist with
- * "smith/<epic>/<task-id>" refs in real git — D/F ref conflict).
+ * <prefix>/<epic>/<task-id> -> <prefix>/<epic>/integration, prefix bs or legacy smith (worktree.yml
+ * `integration_branch.pattern`; a bare "<prefix>/<epic>" ref cannot coexist with
+ * "<prefix>/<epic>/<task-id>" refs in real git — D/F ref conflict).
  *
  * The convention is load-bearing here and that is fine: only an agent working
  * in a task worktree has a claims list, and only a task worktree is on such a
@@ -572,7 +562,7 @@ export function integrationBranchFor(worktreeDir) {
     const branch = runGit(worktreeDir, ['rev-parse', '--abbrev-ref', 'HEAD']);
     const lastSlash = branch.lastIndexOf('/');
     if (lastSlash === -1) {
-        throw new ClaimsError('claims.cannot-derive-integration-branch', `Branch "${branch}" does not follow the smith/<epic>/<task-id> convention.`, { branch });
+        throw new ClaimsError('claims.cannot-derive-integration-branch', `Branch "${branch}" does not follow the bs/<epic>/<task-id> convention.`, { branch });
     }
     return `${branch.slice(0, lastSlash)}/integration`;
 }