@juzser/blacksmith 0.1.0 → 0.2.0

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>',
@@ -191,6 +198,7 @@ export const COMMANDS = [
         positionals: '',
         flags: `[--interval <seconds>] [--once] [--dir <dir>] [--project <dir>...] [--no-self] [--db <path>] [--no-db] [--state-dir <dir>]`,
         summary: 'Watch the event log in the foreground: budgets, stale agents, work that is due. ' +
+            'Prints one report per tick, one JSON line each; --once prints one document and exits. ' +
             'Never dispatches.',
     },
     {
@@ -293,8 +301,9 @@ export const COMMANDS = [
     {
         command: 'event tail',
         positionals: '<session-id>',
-        flags: '[--n <count>] [--task <task-id>] [--lineage] [--state-dir <dir>]',
-        summary: 'Print the last n records of a session that exists. Exit 1 if it does not.',
+        flags: '[--n <count>] [--task <task-id>] [--lineage] [--follow] [--state-dir <dir>]',
+        summary: 'Print the last n records of a session that exists. Exit 1 if it does not. ' +
+            '--follow keeps printing as the log grows, one JSON record per line, until ^C.',
     },
     {
         command: 'event lineage',
@@ -333,14 +342,14 @@ export const COMMANDS = [
         form: '--plan',
         positionals: '<task-id>...',
         flags: '--plan <file> [--repo <dir>]',
-        summary: 'Pre-run: refuse a wave whose tasks sit on either end of an import edge. Exit 1 when coupled.',
+        summary: 'Pre-run: refuse a wave whose tasks sit on either end of an import edge the producer did not promise in keeps_exports. Exit 1 when coupled.',
     },
     {
         command: 'claims impact',
         form: 'spec',
         positionals: '<worktree-dir> <spec.json>',
         flags: '',
-        summary: 'Post-run: an export this task removed, still imported outside its claims. Exit 1 on a proven break.',
+        summary: "Post-run: an export this task removed, still imported outside its claims, and verifies the spec's keeps_exports promises. Exit 1 on a proven break or a broken promise.",
     },
     {
         command: 'dispatch check',
@@ -378,6 +387,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. Shipped policy unless --policy names a file.',
+    },
+    {
+        command: 'harness plan',
+        positionals: '',
+        flags: '--role <role> --task <id> --prompt-file <path> [--harness <name>] [--worktree <dir>] [--policy <file>] [--tier <frontier|mid|small>] [--schema <name>]',
+        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 +658,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 +670,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/waveNext.js

@@ -85,10 +85,36 @@ function admissionOrder(candidates, edges, crossings) {
  * until `computeNextWave` has partitioned them by status.
  */
 export function liveWaveTasks(plan) {
-    return livePlanTasks(plan).map((record) => readClaimList({
-        task_id: record.task_id,
-        claims: record.claims,
-    }));
+    return livePlanTasks(plan).map((record) => readClaimList(proposedFrom(record)));
+}
+/**
+ * The plan record as `readClaimList` wants it: claims always, the
+ * `keeps_exports` promise only when the record has one, so a task that
+ * promised nothing reads back without the key rather than with `undefined`.
+ */
+function proposedFrom(record) {
+    const { claims, keeps_exports } = record;
+    return keeps_exports === undefined
+        ? { task_id: record.task_id, claims }
+        : { task_id: record.task_id, claims, keeps_exports };
+}
+const NAMED_SYMBOLS = 3;
+/**
+ * The deferral names both files and both remedies, because the operator's
+ * choice is between them: order the tasks, or have the producer promise the
+ * exporting file in `keeps_exports` (impact.ts verifies it post-run). Only
+ * the producer can promise, so the sentence names the producer either way.
+ */
+function describeCoupling(taskId, blocker, coupling) {
+    const { crossing, role } = coupling;
+    const shown = crossing.symbols.slice(0, NAMED_SYMBOLS);
+    const symbols = [...shown, ...(crossing.symbols.length > NAMED_SYMBOLS ? ['…'] : [])].join(', ');
+    const typeOnly = crossing.typeOnly ? ', type-only' : '';
+    return role === 'consumes'
+        ? `Imports ${symbols} from ${crossing.exportedBy} (${blocker}) into ${crossing.importedBy}${typeOnly}: ` +
+            `the producer runs first, or ${blocker} promises the file in keeps_exports and both run now.`
+        : `${blocker} imports ${symbols} from ${crossing.exportedBy} into ${crossing.importedBy}${typeOnly}${typeOnly ? ',' : ''} ` +
+            `and is already scheduled, so this one follows, or ${taskId} promises the file in keeps_exports and both run now.`;
 }
 export function computeNextWave(input) {
     const { plan, policy } = input;
@@ -107,7 +133,7 @@ export function computeNextWave(input) {
         }
         // Past this door claims are a real string[], for a candidate and for a
         // task merely holding ground — the wave is unanswerable either way.
-        const task = readClaimList({ task_id: id, claims: record.claims });
+        const task = readClaimList(proposedFrom(record));
         if (CANDIDATE_TASK_STATUSES.has(status)) {
             candidates.push(task);
         }
@@ -125,15 +151,19 @@ export function computeNextWave(input) {
         list.push(edge.dependsOn);
         dependsByTask.set(edge.task, list);
     }
+    // task -> (other task -> the first crossing between them, and this task's
+    // side of it). First wins: the caller hands crossings in a stable order,
+    // and one named crossing is what the deferral renders.
     const coupledWith = new Map();
-    const link = (a, b, role) => {
+    const link = (a, b, coupling) => {
         const map = coupledWith.get(a) ?? new Map();
-        map.set(b, role);
+        if (!map.has(b))
+            map.set(b, coupling);
         coupledWith.set(a, map);
     };
     for (const crossing of crossings) {
-        link(crossing.consumer, crossing.producer, 'consumes');
-        link(crossing.producer, crossing.consumer, 'produces');
+        link(crossing.consumer, crossing.producer, { role: 'consumes', crossing });
+        link(crossing.producer, crossing.consumer, { role: 'produces', crossing });
     }
     const admitted = [];
     const deferred = [];
@@ -189,11 +219,9 @@ export function computeNextWave(input) {
         const couplings = coupledWith.get(id);
         const coupled = couplings ? holders.filter((h) => couplings.has(h.task_id)) : [];
         const blocker = coupled[0];
-        if (couplings !== undefined && blocker !== undefined) {
-            const detail = couplings.get(blocker.task_id) === 'consumes'
-                ? `Imports symbols from ${blocker.task_id}, which has not merged: the producer runs first.`
-                : `${blocker.task_id} imports symbols from it and is already scheduled, so this one follows.`;
-            defer(id, 'symbol-coupled', coupled.map((h) => h.task_id), detail);
+        const coupling = couplings?.get(blocker?.task_id ?? '');
+        if (blocker !== undefined && coupling !== undefined) {
+            defer(id, 'symbol-coupled', coupled.map((h) => h.task_id), describeCoupling(id, blocker.task_id, coupling));
             continue;
         }
         admitted.push(task);

package/factory/orchestrator/dist/waveSchedule.js

@@ -65,10 +65,16 @@ function buildHint(stalled, occupied, constraints, depth) {
     }
     if (constraints.length > 0) {
         const reasons = constraints.map((c) => c.reason);
+        // A crossing has a remedy that is not a re-slice, and the hint is where
+        // the operator learns it exists: the producer promises the exporting file
+        // in `keeps_exports`, and `claims impact` verifies the promise post-run.
+        const promise = reasons.includes('symbol-coupled')
+            ? ' A symbol-coupled task widens when its producer lists the exporting file in keeps_exports (verified post-run).'
+            : '';
         return (`This plan runs in ${depth} ${depth === 1 ? 'round' : 'rounds'}, and some of that ` +
             `depth is claim geometry rather than dependencies (${nameList(reasons)}). ` +
             'Re-slicing the claims may widen it; whether it does depends on the dependency graph, ' +
-            'which this command does not speculate about.');
+            `which this command does not speculate about.${promise}`);
     }
     return '';
 }

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
@@ -232,7 +235,7 @@ escalation_ladder:
       trigger: 2 failed rounds on the same task
       failed_rounds: 2
       enforce: model-tier
-      action: escalate model tier automatically (sonnet -> opus), logged
+      action: escalate model tier automatically (mid -> frontier, taxonomy.yml model_tier), logged
     - rung: 3
       trigger: 3 failed rounds on the same task
       failed_rounds: 3

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,

package/factory/policies/harness.yml

@@ -0,0 +1,82 @@
+# Blacksmith — worker harness policy
+#
+# architecture §19 "Worker harness port". A *provider* is the model vendor a
+# judge's verdict comes from (crosscheck.yml); a *harness* is the program
+# that holds a worker turn — gives the agent its tools, its working directory,
+# its turn limit. HOST: `smith harness list` / `smith harness plan`
+# (factory/orchestrator/src/harness.ts), which read this file when `--policy`
+# names no other. `smith` renders an invocation from it and never starts one
+# (§18 rule 3); `smith-run` (src/run-cli.ts) is the separate binary that does.
+#
+# Shape, per harness:
+#   kind          `in-process` — the Claude Code Agent tool, no program started
+#                 (`command`/`args` unused); `cli` — a program `smith-run` spawns
+#                 with the rendered prompt on stdin.
+#   roles         taxonomy roles this harness serves; empty = every role that
+#                 ships a `.claude/agents/<role>.md`.
+#   args          argv for every turn. Placeholders, closed set:
+#                 {prompt_file} {worktree} {role} {task} {model} {schema_file}.
+#   worker_args   appended for a worker or write-scoped role (guardrails.yml
+#                 `role_write_scopes`).
+#   judge_args    appended for a judge role (guardrails.yml `judge_sandbox.roles`).
+#                 Non-empty means the program itself enforces read-only, and
+#                 only then may a judge on this harness be handed a worktree
+#                 (§18 rule 5 — the refusal `harness.judge-worktree` stands
+#                 when this is empty). Rule 6's fingerprint runs regardless.
+#   schema_args   appended only when the turn names a schema (`--schema`), so a
+#                 turn that validates nothing renders without one.
+#   output        how smith-run reads the program's output: `text` (default),
+#                 `codex-json` (the `codex exec --json` JSONL stream),
+#                 `claude-json` (the `claude -p --output-format json` object).
+#   models        tier → model id for `{model}`; tiers are taxonomy.yml
+#                 `model_tier` (frontier | mid | small). Optional.
+#   env           variable NAMES the child may read. Never values.
+#   timeout_ms    wall-clock cap per turn; max_output_bytes defaults to 2 MiB.
+#
+# A cli harness runs in the worktree it is handed (`cwd` on the rendered
+# invocation), so no `-C`/`--add-dir` is needed to point it there, and a turn
+# with no worktree still renders.
+
+version: 2
+default: claude-code
+harnesses:
+  # The Claude Code Agent tool: in-process, starts no program. Serves every
+  # role with a template. Still the default (§19: switching harnesses is a
+  # `--harness` flag on `plan`, not an edit here).
+  - name: claude-code
+    kind: in-process
+
+  # OpenAI Codex CLI. `-s workspace-write` / `-s read-only` are Codex's own
+  # sandbox modes, which is what lets a judge role hold a worktree here. They
+  # land after the `-` (read the prompt from stdin) positional, which Codex's
+  # parser accepts: `codex exec - -s bogus` is refused as an invalid --sandbox
+  # value, not taken as a second prompt.
+  # No `-m {model}` and no `models:` are shipped: Codex runs whatever model its
+  # own config names, and this file does not guess which of its models is
+  # frontier, mid or small. An operator who wants tier routing adds
+  # `models: { frontier: <id>, mid: <id>, small: <id> }` and `-m`, `{model}`
+  # to `args`; the templates' move to `tier:` frontmatter (PR 2) fills it in.
+  - name: codex-cli
+    kind: cli
+    command: codex
+    args: ["exec", "--json", "--color", "never", "--skip-git-repo-check", "-"]
+    worker_args: ["-s", "workspace-write"]
+    judge_args: ["-s", "read-only"]
+    schema_args: ["--output-schema", "{schema_file}"]
+    output: codex-json
+    env: [HOME, PATH, CODEX_HOME]
+    timeout_ms: 1800000
+
+  # Claude Code as a separate process, for a runner that is not itself a Claude
+  # Code session. A judge gets no write tools at all (`--disallowedTools`),
+  # which is the read-only promise `judge_args` requires.
+  - name: claude-cli
+    kind: cli
+    command: claude
+    args: ["-p", "--output-format", "json", "--model", "{model}"]
+    worker_args: []
+    judge_args: ["--disallowedTools", "Write,Edit,MultiEdit,NotebookEdit"]
+    output: claude-json
+    models: { frontier: opus, mid: sonnet, small: haiku }
+    env: [HOME, PATH, ANTHROPIC_API_KEY, CLAUDE_CONFIG_DIR]
+    timeout_ms: 1800000

package/factory/policies/lessons.md

@@ -138,6 +138,43 @@ nothing.
 - claim_path: **
 - statement: A wrapper that collapses a child's exit signal into an exit code has deleted the only evidence that distinguishes a crash from a failure, and every diagnosis downstream of it will be about the wrong subsystem.
 
+### lesson-raised-7299eef43e7d: npm-packlist drops `.gitignore` and `.npmignore` unconditionally, eve...
+
+- lesson_id: lesson-raised-7299eef43e7d
+- claim_path: {package.json,factory/scaffold/**}
+- statement: npm-packlist drops `.gitignore` and `.npmignore` unconditionally, even inside directories the `files` allowlist names; a scaffold that must ship one ships a template under another name (`.gitignore.tmpl`) and renames it on write.
+
+### lesson-raised-699f909a6ab2: `npm pack --json` stdout carries the `prepare` script's echo before t...
+
+- lesson_id: lesson-raised-699f909a6ab2
+- claim_path: package.json
+- statement: `npm pack --json` stdout carries the `prepare` script's echo before the JSON; parse from the first `[` or `{`, not the whole stream.
+
+### lesson-raised-fee67ee36513: In a backtick `smith` span, the `docCommands` lint reads an unspaced ...
+
+- lesson_id: lesson-raised-fee67ee36513
+- claim_path: {docs,.claude}/**
+- statement: In a backtick `smith` span, the `docCommands` lint reads an unspaced `|` as alternation between verbs and a spaced ` | ` as a shell pipe; write the one you mean.
+
+### lesson-raised-96cb1b268004: `tsc` does not delete orphaned outputs; a deleted source leaves its `...
+
+- lesson_id: lesson-raised-96cb1b268004
+- claim_path: factory/orchestrator/dist/**
+- statement: `tsc` does not delete orphaned outputs; a deleted source leaves its `dist/*.js` behind and the tarball ships it. Clean `dist/` before a pack.
+
+### lesson-raised-f78f3641f4bd: A `files` allowlist is a claim about what the product is, true only o...
+
+- lesson_id: lesson-raised-f78f3641f4bd
+- finding_category: correctness
+- claim_path: package.json
+- statement: A `files` allowlist is a claim about what the product is, true only once someone installs the tarball into an empty directory and runs it; a packaging change is not done until that install proof has run.
+
+### lesson-raised-ccadfedf2299: A packaging guard reads each path constant's spelling from source tex...
+
+- lesson_id: lesson-raised-ccadfedf2299
+- claim_path: factory/orchestrator/test/packaging.test.ts
+- statement: A packaging guard reads each path constant's spelling from source text, not its runtime value, because under an install the roots resolve to places the test suite can never stand.
+
 ## case-type
 
 _(none yet)_
@@ -234,6 +271,91 @@ _(none yet)_
 - lesson_id: lesson-raised-b8db8efe922d
 - statement: An agent that owes a file should write it before refining it: the declared-artifact check catches an agent that ended on an intention only after the tokens are spent, and if that agent could write to shared state, only after the damage has spread.
 
+### lesson-raised-66bfd37ce01a: Never override the commit author with `git -c user.email=...`; the re...
+
+- lesson_id: lesson-raised-66bfd37ce01a
+- statement: Never override the commit author with `git -c user.email=...`; the repo's configured identity is the author, and a per-command override writes a commit under the wrong name that a rewrite has to undo.
+
+### lesson-raised-962e5eed0b7b: A skill's `description:` frontmatter is system-prompt cost on every t...
+
+- lesson_id: lesson-raised-962e5eed0b7b
+- statement: A skill's `description:` frontmatter is system-prompt cost on every turn; keep it to routing, not prose.
+
+### lesson-raised-c11ee5a1819d: A truncated listing (`| head -N`) is not a measurement; count from th...
+
+- lesson_id: lesson-raised-c11ee5a1819d
+- statement: A truncated listing (`| head -N`) is not a measurement; count from the full output or a counter before stating a number.
+
+### lesson-raised-cf980af1e570: After a pipe, `$?` is the last stage's exit code; use `${pipestatus[n...
+
+- lesson_id: lesson-raised-cf980af1e570
+- statement: After a pipe, `$?` is the last stage's exit code; use `${pipestatus[n]}` (zsh) and read it before any subshell, which discards it. The "unknown flag exits 0" observation was this.
+
+### lesson-raised-fc0191ec66ae: `cd` inside a compound command re-scopes the rest of it, and the work...
+
+- lesson_id: lesson-raised-fc0191ec66ae
+- statement: `cd` inside a compound command re-scopes the rest of it, and the working directory resets between tool calls; use absolute paths or `git -C <dir>` rather than relying on a prior `cd`.
+
+### lesson-raised-0d7ff58845b2: `pnpm biome check` must run from the repo root; run from `factory/orc...
+
+- lesson_id: lesson-raised-0d7ff58845b2
+- statement: `pnpm biome check` must run from the repo root; run from `factory/orchestrator` it checks a different file set and reports a different baseline.
+
+### lesson-raised-720003607334: Resolve another branch's merge conflict in a throwaway worktree off `...
+
+- lesson_id: lesson-raised-720003607334
+- statement: Resolve another branch's merge conflict in a throwaway worktree off `origin/<branch>` (`git worktree add --quiet <dir> -b <branch> origin/<ref>`), never by switching the current tree.
+
+### lesson-raised-49b3f7dc407d: When both sides of a conflict appended to the same list (a CHANGELOG ...
+
+- lesson_id: lesson-raised-49b3f7dc407d
+- statement: When both sides of a conflict appended to the same list (a CHANGELOG section, a `files` allowlist), the resolution is the union of both additions, not a pick of one side.
+
+### lesson-raised-5b1e157a4b4d: A red `main` makes every PR's check meaningless; fix `main` first, th...
+
+- lesson_id: lesson-raised-5b1e157a4b4d
+- statement: A red `main` makes every PR's check meaningless; fix `main` first, then re-run the PR checks against it.
+
+### lesson-raised-47c273e5949b: Every `.md` under the instruction surface is doc-linted, so a scope d...
+
+- lesson_id: lesson-raised-47c273e5949b
+- statement: Every `.md` under the instruction surface is doc-linted, so a scope doc that names a verb not yet built turns `main` red; declare it with a self-expiring `<!-- PLANNED-NAMESPACE: <ns> -->` marker rather than widening the lint's exclusion list.
+
+### lesson-raised-6e713c40cfc7: `git stash` unstages a `git mv`; the rename comes back as a delete pl...
+
+- lesson_id: lesson-raised-6e713c40cfc7
+- statement: `git stash` unstages a `git mv`; the rename comes back as a delete plus an untracked file, so re-stage the rename after `stash pop`.
+
+### lesson-raised-9b485954d931: `rm -rf` is hook-blocked outside `workspaces/` and `state/`; remove a...
+
+- lesson_id: lesson-raised-9b485954d931
+- statement: `rm -rf` is hook-blocked outside `workspaces/` and `state/`; remove a worktree with `git worktree remove --force` and a file with a targeted `rm`.
+
+### lesson-raised-ffadc4019340: Verify a new guard by mutation, not by a green run: reintroduce each ...
+
+- lesson_id: lesson-raised-ffadc4019340
+- statement: Verify a new guard by mutation, not by a green run: reintroduce each defect it claims to catch and watch it fail by name before trusting the pass.
+
+### lesson-raised-3c9f8b1c9d17: `npm publish` answering `404 ...
+
+- lesson_id: lesson-raised-3c9f8b1c9d17
+- statement: `npm publish` answering `404 ... is not in this registry` for a scoped package is an authentication failure in disguise, not a missing package; check `npm whoami` before anything else.
+
+### lesson-raised-43a115153ca8: npm's read path lags a first publish by roughly 45 seconds; confirm a...
+
+- lesson_id: lesson-raised-43a115153ca8
+- statement: npm's read path lags a first publish by roughly 45 seconds; confirm a publish with `npm access list packages`, not `npm view`, before concluding it failed.
+
+### lesson-raised-b223426aa4f6: `grep -r ...
+
+- lesson_id: lesson-raised-b223426aa4f6
+- statement: `grep -r ... --include=...` with no path argument reads stdin and hangs the tool call forever; always pass an explicit root.
+
+### lesson-raised-bc8c041f3a8c: A hand-maintained list inside a guard is the hole the guard was built...
+
+- lesson_id: lesson-raised-bc8c041f3a8c
+- statement: A hand-maintained list inside a guard is the hole the guard was built to close; derive the list from the source it checks (a `roots` array in `packaging.test.ts` did not name `ROADMAP_PATH`, so the guard passed the very gap it existed to catch).
+
 ## security
 
 _(none yet)_

package/factory/policies/severity.yml

@@ -33,7 +33,7 @@ levels:
       - behavioral-drift touching a core flow
     on_trigger: >
       bounce to coder on the same branch; after 2 failed rounds, escalate
-      model tier (sonnet -> opus, budgets.yml); after 3, escalate to
+      model tier (mid -> frontier, budgets.yml); after 3, escalate to
       operator.
 
   S3-minor: