@juzser/blacksmith 0.1.1 → 0.2.0

package/factory/orchestrator/dist/usage.js

@@ -198,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.',
     },
     {
@@ -300,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',
@@ -340,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',
@@ -389,12 +391,12 @@ export const COMMANDS = [
         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.',
+        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>]',
+        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.',
     },
     {

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/policies/budgets.yml

@@ -235,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/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/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:

package/factory/specs/schema/task-spec.schema.json

@@ -128,6 +128,11 @@
     "project": {
       "type": "string",
       "description": "Optional plain-string project identifier (Phase 6b, architecture §8) — NOT a closed taxonomy.yml vocabulary value (projects open/close far more often than any §8 dimension). Absent tasks default to 'black-smith' in the projection layer."
+    },
+    "keeps_exports": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Repo-relative file paths, each inside one of this task's own claims, whose existing exports this task keeps: no export removed, no export's declaration changed; adding exports is allowed. A symbol crossing whose producer promised the exporting file does not serialize the wave (impact.ts waveImpact); the promise is verified post-run by `smith claims impact <worktree> <spec.json>` against the diff."
     }
   },
   "additionalProperties": false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juzser/blacksmith",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "description": "Autonomous agent factory — loop runner and worktree engine.",
   "keywords": [
@@ -33,7 +33,8 @@
   },
   "packageManager": "pnpm@9.3.0",
   "bin": {
-    "smith": "factory/orchestrator/dist/cli.js"
+    "smith": "factory/orchestrator/dist/cli.js",
+    "smith-run": "factory/orchestrator/dist/run-cli.js"
   },
   "files": [
     "factory/orchestrator/dist",