@juzser/blacksmith 0.1.0 → 0.1.1

package/factory/orchestrator/dist/providers/schema-validate.js

@@ -100,20 +100,71 @@ export function extractBalancedJson(text) {
  * array of evidence as a single malformed object.
  */
 const ARRAY_VALUED_SCHEMAS = new Set(['finding', 'finding-evidence']);
+/**
+ * The list a judge answered with for an array-valued schema, or undefined when
+ * it answered with some other shape. A bare array is the list. An object with
+ * exactly one key whose value is an array is the list wrapped — the shape an
+ * API judge under `response_format: json_object` has to produce, because that
+ * mode refuses a top-level array (FD-41; deepseek-chat answered
+ * `{"findings":[...]}` and lost the whole review to `schema-invalid`).
+ * Anything else — a bare record, a wrapper with a second key, a scalar — is
+ * refused: `balancedJsonCandidates` never descends into a value it has
+ * yielded, so this is the only place a wrapped list can be recognised, and it
+ * recognises exactly that one shape rather than searching for an array
+ * somewhere inside the answer.
+ */
+function unwrapArray(parsed) {
+    if (Array.isArray(parsed))
+        return parsed;
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    const keys = Object.keys(parsed);
+    if (keys.length !== 1)
+        return undefined;
+    const inner = parsed[keys[0]];
+    return Array.isArray(inner) ? inner : undefined;
+}
+function describeShape(parsed) {
+    if (Array.isArray(parsed))
+        return 'an array';
+    if (parsed === null)
+        return 'null';
+    if (typeof parsed === 'object')
+        return `an object with ${Object.keys(parsed).length} key(s)`;
+    return `a ${typeof parsed}`;
+}
 /**
  * Extract + schema-validate a judge's raw text response. `finding.schema.json`
  * describes ONE finding, but a `kind: review` judge's contract
- * (.claude/agents/reviewer.md) returns an ARRAY of findings — so an array
- * top-level value against an ARRAY_VALUED_SCHEMAS name validates element-wise;
- * every other schema (e.g. "judge-verdict") validates the parsed value
- * directly against its own object shape.
+ * (.claude/agents/reviewer.md) returns an ARRAY of findings — so against an
+ * ARRAY_VALUED_SCHEMAS name the top-level value must be that array, bare or
+ * wrapped in one single-key object (see `unwrapArray`), and validates
+ * element-wise; the value returned is the array itself, unwrapped. A bare
+ * record is refused there even when it would validate on its own: one finding
+ * where a list was asked for is a judge that misread its contract, and
+ * accepting it would file the answer as a review of exactly one issue. Every
+ * other schema (e.g. "judge-verdict") validates the parsed value directly
+ * against its own object shape.
  */
 export function extractAndValidate(rawText, schemaName, opts = {}) {
     const { taxonomy, schemas } = resolve(opts);
     const validateOne = (parsed) => {
-        if (ARRAY_VALUED_SCHEMAS.has(schemaName) && Array.isArray(parsed)) {
+        if (ARRAY_VALUED_SCHEMAS.has(schemaName)) {
+            const items = unwrapArray(parsed);
+            if (items === undefined) {
+                return {
+                    valid: false,
+                    reason: 'schema-invalid',
+                    errors: [
+                        {
+                            path: '',
+                            message: `expected an array of ${schemaName} records (or one object whose single key holds that array); got ${describeShape(parsed)}`,
+                        },
+                    ],
+                };
+            }
             const errors = [];
-            parsed.forEach((item, index) => {
+            items.forEach((item, index) => {
                 const result = validateRecord(schemas, taxonomy, schemaName, item);
                 if (!result.valid) {
                     errors.push(...result.errors.map((e) => ({ path: `/${index}${e.path}`, message: e.message })));
@@ -121,7 +172,7 @@ export function extractAndValidate(rawText, schemaName, opts = {}) {
             });
             if (errors.length > 0)
                 return { valid: false, reason: 'schema-invalid', errors };
-            return { valid: true, value: parsed };
+            return { valid: true, value: items };
         }
         const result = validateRecord(schemas, taxonomy, schemaName, parsed);
         if (!result.valid)

package/factory/orchestrator/dist/providers/types.js

@@ -15,6 +15,11 @@ export const JUDGE_SCHEMA_FAILURE_CODES = new Set([
     'provider.invalid-output',
     'provider.malformed-response',
     'provider.output-too-large',
+    // The provider stopped writing at its output cap (finish_reason `length`)
+    // before the answer closed. The answer is unusable for the same reason a
+    // malformed one is, and the fix is the same side of the wire: a cap that
+    // fits the answer, or a prompt that asks for a shorter one.
+    'provider.output-truncated',
 ]);
 /** Codes raised when no usable answer arrived -- including when no request was sent. */
 export const JUDGE_TRANSPORT_FAILURE_CODES = new Set([

package/factory/orchestrator/dist/roadmap.js

@@ -11,7 +11,7 @@
 // entry (documented as a deviation in ui/docs/DESIGN.md).
 import { readFileSync } from 'node:fs';
 import { SmithError } from './errors.js';
-import { ROADMAP_PATH } from './paths.js';
+import { roadmapReadPath } from './paths.js';
 export class RoadmapError extends SmithError {
 }
 /**
@@ -347,7 +347,7 @@ export function parseRoadmap(markdown) {
  * guard is around the read rather than an existsSync in front of it so a
  * directory, a permission error and a missing file all answer the same way.
  */
-export function readRoadmapText(roadmapPath = ROADMAP_PATH) {
+export function readRoadmapText(roadmapPath = roadmapReadPath()) {
     try {
         return readFileSync(roadmapPath, 'utf8');
     }
@@ -392,7 +392,7 @@ export function roadmapDeclaresId(markdown, id) {
     return false;
 }
 /** Read and parse roadmap.md from disk (defaults to the real repo path). */
-export function loadRoadmap(roadmapPath = ROADMAP_PATH) {
+export function loadRoadmap(roadmapPath = roadmapReadPath()) {
     return parseRoadmap(readRoadmapText(roadmapPath));
 }
 /**

package/factory/orchestrator/dist/scaffold.js

@@ -16,9 +16,10 @@ import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSyn
 import path from 'node:path';
 import { SmithError } from './errors.js';
 import { runGit as git } from './git.js';
-import { PROJECTS_DIR, REPO_ROOT, ROADMAP_PATH, SCAFFOLD_DIR } from './paths.js';
+import { PROJECTS_DIR, REPO_ROOT, SCAFFOLD_DIR } from './paths.js';
 import { readRoadmapText, roadmapDeclaresId } from './roadmap.js';
 import { loadStackAnswers, requireScaffoldable } from './stack.js';
+import { ensureWritableRoadmap } from './workroot.js';
 export class ScaffoldError extends SmithError {
 }
 const PROJECT_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
@@ -355,7 +356,7 @@ export function scaffoldProject(opts) {
  * gets a placeholder milestone so the Projects/Roadmap pages have something
  * to show the moment it exists, edited further as real epics get scoped).
  */
-export function registerProjectInRoadmap(projectName, roadmapPath = ROADMAP_PATH) {
+export function registerProjectInRoadmap(projectName, roadmapPath = ensureWritableRoadmap()) {
     const text = readRoadmapText(roadmapPath);
     const id = `${projectName}-bootstrap`;
     // See registerMcpMilestone: the substring `- id: <id>` is not what

package/factory/orchestrator/dist/stack.js

@@ -25,7 +25,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { parse as parseYaml } from 'yaml';
 import { SmithError } from './errors.js';
-import { REPO_ROOT, STACK_POLICY_PATH } from './paths.js';
+import { REPO_ROOT, stackPolicyReadPath } from './paths.js';
 export class StackError extends SmithError {
 }
 /**
@@ -124,7 +124,7 @@ export function parseStackAnswers(yamlText) {
     }
     return answers;
 }
-export function loadStackAnswers(filePath = STACK_POLICY_PATH) {
+export function loadStackAnswers(filePath = stackPolicyReadPath()) {
     return parseStackAnswers(readFileSync(filePath, 'utf8'));
 }
 /** Values `factory/scaffold/` can build. Everything else is a refusal, not a substitution. */
@@ -222,6 +222,14 @@ function reportFor(field, value, source) {
                 note: `The uiux agent is told to ground its specs in ${value}; with design_system_source empty, no kit is copied into scaffolded projects.`,
             };
         }
+        // A relative `design_system_source` is relative to the *package*, not to
+        // the operator's repository -- which is what it has always meant and what
+        // scaffold.ts resolves it against too. Stated here because this diff moved
+        // the file the value is typed into (stack.yml is now read from the work
+        // root under an install) without moving the base it resolves against, so a
+        // reader could reasonably assume the two travel together. They do not:
+        // changing the base is a behaviour change for every existing clone and
+        // needs a matching sentence in stack.yml, which is a policy file.
         const resolved = path.isAbsolute(source) ? source : path.join(REPO_ROOT, source);
         return existsSync(resolved)
             ? {

package/factory/orchestrator/dist/templateFragments.js

@@ -0,0 +1,178 @@
+import { readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { SmithError } from './errors.js';
+import { AGENTS_DIR, REPO_ROOT } from './paths.js';
+/**
+ * Shared fragments: one paragraph, stamped into several role templates.
+ *
+ * Six judges carry the same read-only rule, six workers the same
+ * `token_usage` paragraph, three judges the same finding-field rule. Before
+ * this module each copy was hand-maintained, and the copies had drifted —
+ * the same rule in three wordings, one of them a sentence short. The fix is
+ * not a template include: an agent template is what Claude Code reads
+ * *verbatim* as a system prompt, so the text has to be *in* the file. So the
+ * fragment is the source, the template carries a stamped copy inside a fence,
+ * and a test holds every fence byte-equal to its fragment. Editing the
+ * paragraph means editing the fragment and re-running the sync — editing one
+ * copy fails the gate by name.
+ */
+export class TemplateFragmentsError extends SmithError {
+}
+/**
+ * Where the fragments live. Deliberately not a `paths.ts` export: everything
+ * anchored on `REPO_ROOT` there must ship in the npm package (packaging
+ * test), and the fragments are dev-time source — the templates carry the
+ * stamped text, and nothing the CLI runs at an operator's desk reads this
+ * directory.
+ *
+ * And deliberately not `.claude/agents/_shared/`: Claude Code's agent loader
+ * recurses into `.claude/agents/`, so a fragment there with front matter
+ * registers as an agent and one without is skipped silently — neither is a
+ * fragment. `.claude/fragments/` is a directory the loader does not watch.
+ */
+export const FRAGMENTS_DIR = path.join(REPO_ROOT, '.claude', 'fragments');
+/** A fragment name is its file's basename; the fence names it the same way. */
+export const FRAGMENT_NAME = /^[a-z][a-z0-9-]*$/;
+const BEGIN_FENCE = /^<!-- BEGIN SHARED:(\S+) -->$/;
+const END_FENCE = /^<!-- END SHARED:(\S+) -->$/;
+export function beginFence(name) {
+    return `<!-- BEGIN SHARED:${name} -->`;
+}
+export function endFence(name) {
+    return `<!-- END SHARED:${name} -->`;
+}
+/**
+ * Every `<!-- BEGIN SHARED:x -->` … `<!-- END SHARED:x -->` region in a
+ * template, in file order. Fences are whole lines, so a fence quoted inside
+ * a sentence is prose, not a region. Regions do not nest: a BEGIN inside a
+ * region and an END with no open region are both errors, as is an END that
+ * names a different fragment than the BEGIN it closes — the fence pair is the
+ * unit the sync rewrites, and a mismatched pair has no single body to rewrite.
+ */
+export function parseSharedRegions(text, file = '<template>') {
+    const lines = text.split('\n');
+    const regions = [];
+    let open = null;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const begin = BEGIN_FENCE.exec(line);
+        if (begin) {
+            const name = begin[1];
+            if (open) {
+                throw new TemplateFragmentsError('fragments.nested-fence', `${file}:${i + 1}: BEGIN SHARED:${name} opens inside SHARED:${open.name} (opened at line ${open.start + 1}); regions do not nest.`, { file, line: i + 1, name, open: open.name });
+            }
+            assertFragmentName(name, `${file}:${i + 1}`);
+            open = { name, start: i };
+            continue;
+        }
+        const end = END_FENCE.exec(line);
+        if (end) {
+            const name = end[1];
+            if (!open || open.name !== name) {
+                throw new TemplateFragmentsError('fragments.unbalanced-fence', open
+                    ? `${file}:${i + 1}: END SHARED:${name} closes SHARED:${open.name} (opened at line ${open.start + 1}).`
+                    : `${file}:${i + 1}: END SHARED:${name} has no open BEGIN.`, { file, line: i + 1, name, open: open?.name ?? null });
+            }
+            const between = lines.slice(open.start + 1, i);
+            regions.push({
+                name,
+                start: open.start,
+                end: i,
+                body: between.length === 0 ? '' : `${between.join('\n')}\n`,
+            });
+            open = null;
+        }
+    }
+    if (open) {
+        throw new TemplateFragmentsError('fragments.unbalanced-fence', `${file}:${open.start + 1}: BEGIN SHARED:${open.name} is never closed.`, { file, line: open.start + 1, name: open.name, open: open.name });
+    }
+    return regions;
+}
+function assertFragmentName(name, where) {
+    if (!FRAGMENT_NAME.test(name)) {
+        throw new TemplateFragmentsError('fragments.invalid-fragment-name', `${where}: ${JSON.stringify(name)} is not a fragment name (expected ${FRAGMENT_NAME}).`, { name, where });
+    }
+}
+/**
+ * The fragments in a directory, by name. Every `.md` file there is a
+ * fragment and its basename is the name — the directory holds nothing else,
+ * so a README or a draft dropped in it fails by name rather than stamping
+ * itself into a template that asks for it.
+ */
+export function listFragments(dir = FRAGMENTS_DIR) {
+    const fragments = new Map();
+    const files = readdirSync(dir)
+        .filter((f) => f.endsWith('.md'))
+        .sort();
+    for (const file of files) {
+        const name = path.basename(file, '.md');
+        assertFragmentName(name, path.join(dir, file));
+        fragments.set(name, readFileSync(path.join(dir, file), 'utf8'));
+    }
+    return fragments;
+}
+/**
+ * Rewrite every fenced region so its body equals the named fragment. The
+ * fences stay; only the lines between them change. Stamping a template that
+ * is already in sync returns it byte-for-byte, which is what lets the sync
+ * script run on every template without a diff to explain.
+ */
+export function stampFragments(text, fragments, file = '<template>') {
+    const regions = parseSharedRegions(text, file);
+    const lines = text.split('\n');
+    const out = [];
+    const stamped = [];
+    let cursor = 0;
+    for (const region of regions) {
+        const fragment = fragments.get(region.name);
+        if (fragment === undefined) {
+            throw new TemplateFragmentsError('fragments.unknown-fragment', `${file}:${region.start + 1}: SHARED:${region.name} names no file under the fragments directory (have: ${[...fragments.keys()].join(', ') || 'none'}).`, { file, line: region.start + 1, name: region.name, known: [...fragments.keys()] });
+        }
+        out.push(...lines.slice(cursor, region.start + 1));
+        if (fragment !== '')
+            out.push(...fragment.replace(/\n$/, '').split('\n'));
+        out.push(lines[region.end]);
+        cursor = region.end + 1;
+        stamped.push({ name: region.name, drifted: region.body !== fragment });
+    }
+    out.push(...lines.slice(cursor));
+    return { text: out.join('\n'), regions: stamped };
+}
+/**
+ * Stamp every fragment into every role template. Reads the templates
+ * non-recursively, the same set `scripts/check.sh` validates, so a file in a
+ * subdirectory is neither a template here nor an agent there.
+ */
+export function syncTemplates(opts = {}) {
+    const agentsDir = opts.agentsDir ?? AGENTS_DIR;
+    const fragments = listFragments(opts.fragmentsDir ?? FRAGMENTS_DIR);
+    const used = new Set();
+    const report = {
+        fragments: [...fragments.keys()],
+        templates: [],
+        drifted: [],
+        unused: [],
+        written: [],
+    };
+    const files = readdirSync(agentsDir, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
+        .map((entry) => entry.name)
+        .sort();
+    for (const file of files) {
+        const templatePath = path.join(agentsDir, file);
+        const before = readFileSync(templatePath, 'utf8');
+        const { text, regions } = stampFragments(before, fragments, templatePath);
+        report.templates.push({ file, regions });
+        for (const region of regions) {
+            used.add(region.name);
+            if (region.drifted)
+                report.drifted.push({ file, name: region.name });
+        }
+        if (opts.write && text !== before) {
+            writeFileSync(templatePath, text, 'utf8');
+            report.written.push(file);
+        }
+    }
+    report.unused = report.fragments.filter((name) => !used.has(name));
+    return report;
+}

package/factory/orchestrator/dist/usage.js

@@ -88,8 +88,8 @@ export const COMMANDS = [
     {
         command: 'plan quorum',
         positionals: '',
-        flags: '--epic <id> --plan-version <n> --session <id> --causal-parent <event-id> [--confidence <0-1>] [--actor <name>] [--state-dir <dir>]',
-        summary: 'Critique-only review of a drafted plan. Exit 1 means the operator must look first.',
+        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>]',
+        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',
@@ -162,6 +162,13 @@ export const COMMANDS = [
             'wide, or were dispatched one task at a time. Reads, never writes. Exit 1 on a wave that ' +
             'ran strictly serially, 2 when a wave was admitted and the log shows no work for it.',
     },
+    {
+        command: 'init',
+        positionals: '',
+        flags: '[--work-root <dir>]',
+        summary: 'Prepare a work root in the current directory: the state directories, and a copy of every ' +
+            'file the factory ships a default of for you to edit. Idempotent; a clone needs none of it.',
+    },
     {
         command: 'new',
         positionals: '<project>',
@@ -378,6 +385,18 @@ export const COMMANDS = [
         flags: '--task <task.json> [--policy <file>] [--case <case>] [--epic-tag <tag>...] [--recheck]',
         summary: 'Compute whether the security reviewer must be dispatched. A fired trigger is not a red.',
     },
+    {
+        command: 'harness list',
+        positionals: '',
+        flags: '[--policy <file>]',
+        summary: 'The harnesses that may run a worker turn, and which roles each one serves. Built-in unless --policy names a file.',
+    },
+    {
+        command: 'harness plan',
+        positionals: '',
+        flags: '--role <role> --task <id> --prompt-file <path> [--harness <name>] [--worktree <dir>] [--policy <file>]',
+        summary: 'Render the invocation that would run one worker turn, as JSON. Prints it; never starts it.',
+    },
     {
         command: 'sandbox open',
         positionals: '<worktree-dir>',
@@ -637,7 +656,7 @@ export const COMMANDS = [
     {
         command: 'crossfind request',
         positionals: '',
-        flags: '--task <id> --diff <file> --diff-ref <ref> [--criterion <text>...] [--timeout-ms <n>] [--max-output-bytes <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>]',
         summary: 'Print the finder request without sending it — exactly what would leave the machine. Refuses when send_diff is false.',
     },
     {
@@ -649,13 +668,13 @@ export const COMMANDS = [
     {
         command: 'crossfind run',
         positionals: '',
-        flags: `--task <id> --diff <file> --diff-ref <ref> [--criterion <text>...] [--status <status>] [--timeout-ms <n>] [--max-output-bytes <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>] ${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>]',
+        flags: '[--port <n>] [--db <file>] [--state-dir <dir>] [--roadmap-path <file>] [--specs-dir <dir>] [--now-iso <iso>]',
         summary: 'Serve the dashboard from the built ui/server.',
     },
     {

package/factory/orchestrator/dist/workroot.js

@@ -0,0 +1,113 @@
+import { copyFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { REPO_ROOT, ROADMAP_DEFAULT_PATH, ROADMAP_PATH, SPECS_ACTIVE_DIR, STACK_POLICY_DEFAULT_PATH, STATE_ARTIFACTS_DIR, STATE_EVENTS_DIR, WORK_ROOT, } from './paths.js';
+/**
+ * The files `paths.ts` declares twice: a default that ships and a copy the
+ * operator then edits. Spelled relative to their own root, because the pairing
+ * rule -- enforced in packaging.test.ts -- is that both halves are the same
+ * relative path under two roots, which is what lets seeding be a plain copy.
+ *
+ * Derived from the constants rather than retyped, so a third overlay file
+ * added to `paths.ts` is seeded without anyone remembering to edit this list.
+ */
+export const OVERLAY_FILES = [
+    path.relative(REPO_ROOT, ROADMAP_DEFAULT_PATH),
+    path.relative(REPO_ROOT, STACK_POLICY_DEFAULT_PATH),
+];
+// `factory/policies/lessons.md` is the third overlay in `paths.ts` and is
+// deliberately not in that list. The two above are seeded because INSTALL.md
+// has the operator open them and edit them in place -- they must exist before
+// anyone can answer. Nobody hand-edits lessons.md: it appears the first time
+// `smith lessons compile` runs, and until then reading the shipped set is the
+// right answer. Seeding a copy would freeze the lessons at install time and
+// stop every later upgrade from delivering new ones.
+/**
+ * The directories the CLI writes into. Same derivation, same reason: the
+ * relative spelling is `paths.ts`'s to decide, and this module should follow
+ * it rather than hold a second opinion about where `state/events` is.
+ */
+const WORK_DIRS = [
+    path.relative(WORK_ROOT, STATE_EVENTS_DIR),
+    path.relative(WORK_ROOT, STATE_ARTIFACTS_DIR),
+    path.relative(WORK_ROOT, SPECS_ACTIVE_DIR),
+];
+/**
+ * `state/` is a cache of the event log and `workspaces/` holds worktrees; both
+ * are this machine's, not the project's. `factory/` is deliberately absent:
+ * the roadmap and the stack answers are declarations the operator made, and a
+ * team sharing the repository should share them.
+ */
+const WORK_ROOT_GITIGNORE = `# Written by \`smith init\`. Blacksmith's state is a cache of its event log
+# and belongs to this machine; the answers under factory/ are declarations
+# this project made, so they are tracked.
+state/
+workspaces/
+.env
+`;
+/**
+ * Give the operator their own copy of a file the factory ships a default of.
+ *
+ * Never overwrites: an operator who answers the stack questionnaire, upgrades,
+ * and runs init again out of habit must not find the defaults back. And never
+ * copies a file onto itself, which is the clone case -- there the personal
+ * copy *is* the shipped default, and the honest report is that nothing needed
+ * doing.
+ */
+export function seedFromShipped(personal, shipped) {
+    if (personal === shipped || existsSync(personal)) {
+        return { personal, shipped, status: 'kept' };
+    }
+    if (!existsSync(shipped)) {
+        // Not an throw: a missing default is a packaging defect, and the caller --
+        // `smith init`, which is reporting a list -- can say which file is missing
+        // more usefully than an exception thrown halfway through the list can.
+        return { personal, shipped, status: 'missing-default' };
+    }
+    mkdirSync(path.dirname(personal), { recursive: true });
+    copyFileSync(shipped, personal);
+    return { personal, shipped, status: 'seeded' };
+}
+/**
+ * The roadmap, guaranteed writable, returned.
+ *
+ * Used as the *default argument* of the functions that append to the roadmap,
+ * so that an explicitly-passed path is never seeded -- a caller naming a file
+ * is naming the file it means, and a missing one is still an error there.
+ */
+export function ensureWritableRoadmap() {
+    seedFromShipped(ROADMAP_PATH, ROADMAP_DEFAULT_PATH);
+    return ROADMAP_PATH;
+}
+/**
+ * Make a work root that the CLI can run against: the directories it writes
+ * into, a copy of each file the operator is expected to edit, and -- only when
+ * the work root is a directory of our own inside somebody else's repository --
+ * a `.gitignore` saying which half of it is state.
+ *
+ * Idempotent by construction: every step asks whether it has already been
+ * done. Running it twice is not an undo.
+ */
+export function initWorkRoot(options = {}) {
+    const workRoot = options.workRoot ?? WORK_ROOT;
+    const repoRoot = options.repoRoot ?? REPO_ROOT;
+    const inPlace = path.resolve(workRoot) === path.resolve(repoRoot);
+    for (const rel of WORK_DIRS) {
+        mkdirSync(path.join(workRoot, rel), { recursive: true });
+    }
+    const files = OVERLAY_FILES.map((rel) => seedFromShipped(path.join(workRoot, rel), path.join(repoRoot, rel)));
+    // In a clone this is the repository's own .gitignore, which means something
+    // already. Appending to it would be a surprise and replacing it would be
+    // data loss, so the only correct move is to leave it entirely alone.
+    let gitignore = 'not-applicable';
+    if (!inPlace) {
+        const ignorePath = path.join(workRoot, '.gitignore');
+        if (existsSync(ignorePath)) {
+            gitignore = 'kept';
+        }
+        else {
+            writeFileSync(ignorePath, WORK_ROOT_GITIGNORE, 'utf8');
+            gitignore = 'written';
+        }
+    }
+    return { workRoot, repoRoot, inPlace, directories: WORK_DIRS, files, gitignore };
+}

package/factory/orchestrator/drizzle/0011_findings_spec_ref.sql

@@ -0,0 +1,3 @@
+ALTER TABLE `findings` ADD `finding_scope` text DEFAULT 'diff' NOT NULL;--> statement-breakpoint
+ALTER TABLE `findings` ADD `spec_plan_version` integer;--> statement-breakpoint
+ALTER TABLE `findings` ADD `criterion_ref` text;

package/factory/orchestrator/drizzle/meta/_journal.json

@@ -78,6 +78,13 @@
       "when": 1788429177107,
       "tag": "0010_milestone_kind",
       "breakpoints": true
+    },
+    {
+      "idx": 11,
+      "version": "6",
+      "when": 1789391823211,
+      "tag": "0011_findings_spec_ref",
+      "breakpoints": true
     }
   ]
 }

package/factory/policies/budgets.yml

@@ -62,9 +62,12 @@
 # Every other number below is prompt-level: read by agents from their own
 # template and by the operator from the /bs playbook. They are requests, not
 # limits, and the sections that follow say which is which. `max_turns` is no
-# longer among them at all — no dispatch harness can enforce a turn limit
-# (agent-interviews.md M-4), so plan validation now rejects it as a task budget
-# field and the number belongs in the dispatch prompt.
+# longer among them at all: the turn ceiling is the role template's
+# `maxTurns` (`.claude/agents/<role>.md`), which Claude Code enforces per
+# dispatch (measured 2026-09-07/-11, dogfood-csb-audit-1 FD-7 and FD-14 —
+# agent-interviews.md M-4 had called it inert), and a plan cannot raise or
+# lower a role's ceiling. So plan validation rejects it as a task budget
+# field, and the dispatch prompt restates the template's number verbatim.
 #
 # No concurrency cap on cost grounds, by design (removed 2026-08-05). Workers
 # run in isolated worktrees on disjoint path claims, so parallelism is bounded

package/factory/policies/crosscheck.yml

@@ -113,14 +113,16 @@ providers:
     #
     # Funded for THIS box, 2026-09-04, by the operator who owns the key.
     enabled: auto
-    # `shadow`, deliberately, and the difference from codex above is the point:
-    # this box declined shadow for codex and chose it here. A shadow provider
-    # is still called and still recorded as a participant -- it forfeits only
-    # gating power -- so what the mode buys is a run of recorded disagreement
-    # to read before a second vendor gets a vote (docs/runbooks/providers.md
-    # §3). Promote by editing this to `active`; that is the calibration pass,
-    # and it is an operator decision, not a default.
-    mode: shadow
+    # Promoted shadow -> active by the operator on 2026-09-14, after the
+    # csb-signing-policy-1 epic-final verdict held on `insufficient-providers`
+    # with all three participants at `confirm`: with claude excluded as the
+    # finder and deepseek in shadow, the gating pool was codex alone (1 <
+    # `quorum_rule.min_providers` 2), so no mechanically-ready epic could ever
+    # reach quorum on this box (epic.ts, "exactly 1 active external"). The
+    # calibration run it replaced is the recorded shadow verdicts from
+    # csb-audit-1 and csb-signing-policy-1 (docs/runbooks/providers.md §3).
+    # Rollback is `mode: shadow` here; nothing else remembers the promotion.
+    mode: active
 
 quorum_triggers:
   # architecture §6, agent-constraints.md "cross-check (phase 8)" — all four,