elanous 0.2.31 → 0.2.34

package/scripts/graph-units/land-enqueue.ts

@@ -0,0 +1,78 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+import { debug } from '../../src/debug/log.js';
+
+type RecordValue = Record<string, unknown>;
+type EnqueueResult = {
+  outcome: 'done' | 'needs-human';
+  result: string;
+  evidence: RecordValue;
+};
+
+function record(value: unknown): RecordValue {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value as RecordValue : {};
+}
+
+function text(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function needsHuman(reason: string, evidence: RecordValue = {}): EnqueueResult {
+  return { outcome: 'needs-human', result: reason, evidence: { enqueued: false, reason, ...evidence } };
+}
+
+const OWNERS = new Set(['TC', 'MK', 'UX', 'OPC', 'OPT', 'OP', 'tf']);
+
+/** The graph asks the existing OP train to enqueue; it never performs a merge. */
+export function runLandEnqueue(
+  envelope: unknown,
+  executable = process.env.ELANOUS_LAND_ENQUEUE,
+  spawn: typeof spawnSync = spawnSync,
+): EnqueueResult {
+  const context = record(record(envelope).context);
+  const rawPr = context.pr;
+  const pr = typeof rawPr === 'number' ? rawPr : typeof rawPr === 'string' && /^\d+$/.test(rawPr) ? Number(rawPr) : NaN;
+  const expectedHead = text(context.expectedHead);
+  const review = text(context.review);
+  const rawOwner = text(context.owner);
+  const owner = rawOwner.startsWith('train:') ? rawOwner.slice(6) : rawOwner;
+  if (!Number.isSafeInteger(pr) || pr <= 0) return needsHuman('pr-missing-or-invalid');
+  if (!/^[0-9a-f]{40}$/i.test(expectedHead)) return needsHuman('expected-head-missing-or-invalid', { pr });
+  if (!isAbsolute(review) || !existsSync(review)) return needsHuman('review-json-missing', { pr, expectedHead, review });
+  if (!OWNERS.has(owner)) return needsHuman('train-owner-missing-or-invalid', { pr, expectedHead, review });
+  if (!executable || !isAbsolute(executable) || !existsSync(executable)) {
+    return needsHuman('land-enqueue-command-unavailable', { pr, expectedHead, review, owner });
+  }
+  const args = [String(pr), `train:${owner}`, '--expected-head', expectedHead, '--review', review];
+  const result = spawn(executable, args, { encoding: 'utf8', timeout: 55_000, shell: false });
+  const evidence = {
+    pr, expectedHead, review, owner,
+    exitCode: result.status,
+    stdout: String(result.stdout ?? '').slice(-2000),
+    stderr: String(result.stderr ?? '').slice(-2000),
+  };
+  if (result.error || result.status !== 0) {
+    return needsHuman(result.error ? `land-enqueue-error: ${result.error.message}` : 'land-enqueue-refused', evidence);
+  }
+  return { outcome: 'done', result: 'train-enqueued', evidence: { enqueued: true, ...evidence } };
+}
+
+if (import.meta.main) {
+  try {
+    const path = process.env.ELANOUS_GRAPH_CONTEXT;
+    if (!path) throw new Error('ELANOUS_GRAPH_CONTEXT missing');
+    const graph = JSON.parse(readFileSync(path, 'utf8')) as { input?: unknown };
+    const result = runLandEnqueue(graph.input);
+    debug.log('harness.journey', 'land-enqueue', {
+      outcome: result.outcome,
+      reason: result.outcome === 'needs-human' ? result.result : null,
+      pr: result.evidence.pr ?? null,
+      expectedHead: result.evidence.expectedHead ?? null,
+      enqueued: result.evidence.enqueued,
+    });
+    console.log(JSON.stringify(result));
+  } catch (error) {
+    console.log(JSON.stringify(needsHuman(`land-context-invalid: ${error instanceof Error ? error.message : String(error)}`)));
+  }
+}

package/scripts/graph-units/recover-plan.ts

@@ -0,0 +1,15 @@
+import { readFileSync } from 'node:fs';
+import { planPrLandRecoveryForEntry, type PrLandRecoveryContext } from '../../src/cli/pr-land-recovery.js';
+
+type GraphContext = { nodeId?: string; input?: { context?: PrLandRecoveryContext } };
+
+try {
+  const path = process.env.ELANOUS_GRAPH_CONTEXT;
+  if (!path) throw new Error('ELANOUS_GRAPH_CONTEXT missing');
+  const graph = JSON.parse(readFileSync(path, 'utf8')) as GraphContext;
+  const context = graph.input?.context;
+  if (!context || typeof context !== 'object' || Array.isArray(context)) throw new Error('recover context missing');
+  console.log(JSON.stringify(planPrLandRecoveryForEntry(context, graph.nodeId ?? '')));
+} catch (error) {
+  console.log(JSON.stringify({ outcome: 'failed', result: { action: 'none', reason: error instanceof Error ? error.message : String(error) }, evidence: { refusal: '', label: 'invalid-input', route: null, source: 'none' } }));
+}

package/scripts/graph-units/reflect-node.ts

@@ -0,0 +1,88 @@
+import { existsSync, readFileSync, readlinkSync, realpathSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { getUserConfig } from '../../src/user-config.js';
+import { isPodImageCommit } from '../../src/task-orchestrator/surfaces/pod-image-source.js';
+import { debug } from '../../src/debug/log.js';
+
+type Rec = Record<string, unknown>;
+const rec = (v: unknown): Rec => v && typeof v === 'object' && !Array.isArray(v) ? v as Rec : {};
+const sha = (v: unknown): v is string => typeof v === 'string' && /^[0-9a-f]{40}$/i.test(v);
+const emit = (outcome: string, result: Rec, evidence: Rec) => {
+  debug.log('harness.journey', 'reflect.exit', { outcome, reason: result.reason ?? null, ...evidence });
+  console.log(JSON.stringify({ outcome, result, evidence }));
+};
+
+async function main() {
+try {
+  const contextPath = process.env.ELANOUS_GRAPH_CONTEXT;
+  if (!contextPath) throw new Error('ELANOUS_GRAPH_CONTEXT missing');
+  const envelope = rec(JSON.parse(readFileSync(contextPath, 'utf8')));
+  debug.log('harness.journey', 'reflect.enter', { runId: envelope.runId ?? null, nodeId: envelope.nodeId ?? 'reflect' });
+  const input = rec(envelope.input);
+  const context = rec(input.context);
+  const prior = rec(input.prior);
+  const landed = context.landedSha ?? context.commit;
+  if (!sha(landed)) throw new Error('context.landedSha must be a full commit SHA');
+  const attempts = Number(rec(prior.result).attempts ?? prior.attempts ?? 0);
+  const maxAttempts = Number(context.maxAttempts ?? 3);
+  if (!Number.isInteger(attempts) || attempts < 0 || !Number.isInteger(maxAttempts) || maxAttempts < 1 || maxAttempts > 10) throw new Error('invalid bounded retry counters');
+
+  // Root overrides are accepted only in an isolated test universe, never from
+  // a production graph envelope that could forge an installed/pinned identity.
+  const isolated = process.env.NODE_ENV === 'test' || Boolean(process.env.ELANOUS_TEST_HOME?.trim());
+  if (!isolated && (context.installRoot || context.sourceRoot || context.configPath)) throw new Error('identity override requires test universe');
+  const root = resolve(isolated && typeof context.installRoot === 'string' ? context.installRoot : join(homedir(), '.local', 'share', 'elanous'));
+  const installRecord = join(root, 'install.json');
+  if (!existsSync(installRecord)) throw new Error(`install record missing: ${installRecord}`);
+  const installed = rec(JSON.parse(readFileSync(installRecord, 'utf8')));
+  const source = isolated && typeof context.sourceRoot === 'string' ? resolve(context.sourceRoot) : typeof installed.source === 'string' ? resolve(installed.source) : '';
+  const currentLink = join(root, 'current');
+  if (!source || !existsSync(currentLink)) throw new Error('installed source/current identity unknown');
+  const currentPath = realpathSync(currentLink);
+  const versionDir = installed.versionDir;
+  if (typeof versionDir !== 'string' || !/^versions\/[A-Za-z0-9][A-Za-z0-9._-]*$/.test(versionDir) ||
+      readlinkSync(currentLink) !== versionDir || realpathSync(join(root, versionDir)) !== currentPath) {
+    throw new Error('current symlink does not match install.json versionDir');
+  }
+  const entryPath = join(currentPath, 'node_modules', 'elanous', 'bin', 'elanous.mjs');
+  if (!existsSync(entryPath) || !realpathSync(entryPath).startsWith(`${currentPath}/`)) {
+    throw new Error('installed current entry missing or points outside current');
+  }
+  const currentCommit = installed.commit;
+  if (!sha(currentCommit)) throw new Error('install.json commit missing/invalid');
+  // The installer records the identity in three independent positions: the
+  // version directory name, the root record and a copy inside that version.
+  // A stale or forged root record alone cannot attest the installed entry.
+  if (!versionDir.toLowerCase().endsWith(`-${currentCommit.slice(0, 12).toLowerCase()}`)) {
+    throw new Error('installed version name does not match recorded commit');
+  }
+  const inside = rec(JSON.parse(readFileSync(join(currentPath, 'install.json'), 'utf8')));
+  if (inside.versionDir !== versionDir || inside.commit !== currentCommit) {
+    throw new Error('current install identity does not match root record');
+  }
+  // Pin provenance is the live config, never the untrusted graph input.
+  const configPath = isolated && typeof context.configPath === 'string' ? resolve(context.configPath) : undefined;
+  const pin = getUserConfig(configPath).harness?.imageCommit;
+  if (!isPodImageCommit(pin)) throw new Error('harness.imageCommit pin missing/invalid');
+  const git = spawnSync('git', ['-C', source, 'merge-base', '--is-ancestor', landed, currentCommit], { encoding: 'utf8' });
+  if (git.error || git.status !== 0 && git.status !== 1) throw new Error(`installed ancestry cannot be verified: ${git.stderr || git.error?.message || git.status}`);
+  const landedInstalled = git.status === 0;
+  // The image pin may be a 12-digit abbreviation: resolve it to a unique
+  // commit before checking ancestry, never compare abbreviated strings.
+  const expanded = spawnSync('git', ['-C', source, 'rev-parse', '--verify', `${pin.trim()}^{commit}`], { encoding: 'utf8' });
+  if (expanded.error || expanded.status !== 0 || !sha(expanded.stdout.trim())) throw new Error('harness pin commit cannot be resolved');
+  const pinCommit = expanded.stdout.trim();
+  const pinCheck = spawnSync('git', ['-C', source, 'merge-base', '--is-ancestor', landed, pinCommit], { encoding: 'utf8' });
+  if (pinCheck.error || pinCheck.status !== 0 && pinCheck.status !== 1) throw new Error(`harness pin ancestry cannot be verified: ${pinCheck.stderr || pinCheck.error?.message || pinCheck.status}`);
+  const matchesPin = pinCheck.status === 0;
+  const evidence = { landedSha: landed, installedCommit: currentCommit, harnessImageCommit: pin, pinCommit, currentPath, installRecord, installedSource: source, attempts, maxAttempts };
+  if (landedInstalled && matchesPin) return emit('done', { reflected: true, attempts }, evidence);
+  if (attempts + 1 < maxAttempts) return emit('wait', { reflected: false, attempts: attempts + 1, reason: !landedInstalled ? 'not-installed-yet' : 'image-pin-not-yet-reflecting' }, { ...evidence, attempts: attempts + 1, retryAfterSeconds: 60 });
+  return emit('needs-human', { reflected: false, attempts: attempts + 1, reason: !landedInstalled ? 'landed-sha-not-in-installed-current' : 'landed-sha-not-in-harness-image-pin' }, { ...evidence, attempts: attempts + 1 });
+} catch (error) {
+  emit('needs-human', { reflected: false, reason: error instanceof Error ? error.message : String(error) }, { failClosed: true });
+}
+}
+void main();

package/scripts/graph-units/ta-journey-observe.ts

@@ -0,0 +1,109 @@
+import { readFileSync } from 'node:fs';
+import { passJourneyNode, type JourneyObservationNodeId } from '../../src/self-dev/graph-journey-nodes.js';
+import type { GoalType } from '../../src/self-implement/goal-author.js';
+
+type StepObservation = {
+  outcome?: unknown;
+  data?: Record<string, unknown>;
+};
+type JourneyContext = {
+  observations?: Record<string, StepObservation>;
+  substrate?: unknown;
+  runId?: unknown;
+  goalId?: unknown;
+  goalType?: GoalType;
+};
+type UnitId = 'entry' | 'dispatch-pod' | 'author' | 'pr';
+type UnitResult = {
+  outcome: 'done' | 'needs-human' | 'failed';
+  result: { unit: UnitId; observed: boolean; observations: Record<string, string>; reason?: string };
+  evidence: { source: 'existing-harness-observation'; nodes: string[] };
+};
+
+const STEPS: Record<UnitId, readonly string[]> = {
+  entry: ['intake', 'queue', 'launch-gate'],
+  'dispatch-pod': ['dispatch', 'pool-admit', 'image-sync', 'credential-refresh'],
+  author: ['author'],
+  pr: ['open-pr'],
+};
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+/** Record only events that the existing execution path supplied; never infer a successful step. */
+export function observeTaJourneyUnit(unit: UnitId, context: JourneyContext): UnitResult {
+  const supplied = context.observations ?? {};
+  const steps = STEPS[unit];
+  const outcomes: Record<string, string> = {};
+  const missing: string[] = [];
+
+  for (const node of steps) {
+    if (unit === 'dispatch-pod' && node !== 'dispatch' && context.substrate === 'local') continue;
+    const observation = supplied[node];
+    const outcome = stringValue(observation?.outcome);
+    if (!outcome) {
+      // A direct intake never enters the queue. Every other missing step is unresolved evidence.
+      if (unit === 'entry' && node === 'queue' && outcomes.intake === 'direct') continue;
+      missing.push(node);
+      continue;
+    }
+    outcomes[node] = outcome;
+    const helperNode = node as JourneyObservationNodeId;
+    passJourneyNode(helperNode, {
+      provenance: unit === 'author' ? 'authoring-start' : 'ta-journey-observation-wrapper',
+      ...(stringValue(context.runId) ? { runId: stringValue(context.runId) } : {}),
+      ...(context.goalType ? { goalType: context.goalType } : {}),
+      data: {
+        ...observation.data,
+        ...(stringValue(context.goalId) ? { goalId: stringValue(context.goalId) } : {}),
+        ...(unit === 'author' ? { phase: 'front' } : {}),
+      },
+      outcome,
+    });
+  }
+
+  const values = Object.values(outcomes);
+  if (values.some(value => value === 'failed' || value === 'error')) return {
+    outcome: 'failed',
+    result: { unit, observed: true, observations: outcomes, reason: 'existing-step-failed' },
+    evidence: { source: 'existing-harness-observation', nodes: Object.keys(outcomes) },
+  };
+
+  if (missing.length > 0) return {
+    outcome: 'needs-human',
+    result: { unit, observed: false, observations: outcomes, reason: `missing-observation:${missing.join(',')}` },
+    evidence: { source: 'existing-harness-observation', nodes: Object.keys(outcomes) },
+  };
+
+  const accepted: Record<string, readonly string[]> = {
+    intake: ['direct', 'queued'],
+    queue: ['launched'],
+    'launch-gate': ['pass'],
+    dispatch: ['fresh', 'pr-source'],
+    'pool-admit': ['admitted'],
+    'image-sync': ['synced', 'current'],
+    'credential-refresh': ['usable'],
+    author: ['authored', 'done'],
+    'open-pr': ['pr-opened'],
+  };
+  const rejected = Object.entries(outcomes).some(([node, value]) => !accepted[node]?.includes(value));
+  return {
+    outcome: rejected ? 'needs-human' : 'done',
+    result: { unit, observed: true, observations: outcomes, ...(rejected ? { reason: 'existing-step-needs-human' } : {}) },
+    evidence: { source: 'existing-harness-observation', nodes: Object.keys(outcomes) },
+  };
+}
+
+if (import.meta.main) {
+  const unit = process.argv[2] as UnitId;
+  try {
+    const path = process.env.ELANOUS_GRAPH_CONTEXT;
+    if (!path) throw new Error('ELANOUS_GRAPH_CONTEXT is required');
+    const graphContext = JSON.parse(readFileSync(path, 'utf8')) as { input?: { context?: JourneyContext } };
+    const result = observeTaJourneyUnit(unit, graphContext.input?.context ?? {});
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+  } catch (error) {
+    process.stdout.write(`${JSON.stringify({ outcome: 'failed', result: { unit, observed: false, reason: error instanceof Error ? error.message : String(error) }, evidence: { source: 'existing-harness-observation', nodes: [] } })}\n`);
+  }
+}

package/scripts/graph-units/verbs/headless-goal-loop.ts

@@ -0,0 +1,152 @@
+/** Executes the existing self-implement seam for a verb unit's document draft. */
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { readFileSync, realpathSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import type { ChildLlmSelection } from '../../../src/agent/run-context.js';
+import { defaultSeams } from '../../../src/self-implement/seams.js';
+
+type Context = {
+  graphId: string;
+  runId: string;
+  nodeId: string;
+  input: Record<string, unknown>;
+  outputs: Record<string, Record<string, unknown>>;
+};
+
+function required(value: unknown, name: string): string {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`verb headless-goal-loop input missing: ${name}`);
+  return value;
+}
+
+function context(): Context {
+  const path = required(process.env.ELANOUS_GRAPH_CONTEXT, 'ELANOUS_GRAPH_CONTEXT');
+  const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'));
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('invalid verb graph context');
+  const ctx = parsed as Partial<Context>;
+  if (!['verb-make-doc', 'verb-verify'].includes(ctx.graphId ?? '') || !ctx.input || !ctx.outputs || !ctx.runId || !ctx.nodeId)
+    throw new Error('invalid verb graph context');
+  if (process.env.ELANOUS_GRAPH_DRY_RUN === '1') throw new Error('dry run must use the side-effect-free recipe');
+  return ctx as Context;
+}
+
+function repositoryRoot(): string {
+  return resolve(import.meta.dir, '../../..');
+}
+
+export function appendPriorToGoal(goal: string, prior: unknown): string {
+  if (prior === null || prior === undefined) return goal;
+  const serialized = JSON.stringify(prior, null, 2);
+  if (!serialized) return goal;
+  return `${goal}\n\n## Supplied prior research and evidence\nUse only this supplied packet for prior claims. Preserve its sources and limitations, and do not invent unsupported facts.\n\n\`\`\`json\n${serialized}\n\`\`\``;
+}
+
+export function childLlmSelectionFromRecipe(provider: string | undefined, model: string | undefined): ChildLlmSelection | undefined {
+  const resolvedProvider = provider?.trim();
+  const resolvedModel = model?.trim();
+  if (!resolvedProvider && !resolvedModel) return undefined;
+  if (!resolvedProvider || !resolvedModel) throw new Error('graph recipe child LLM requires both provider and model');
+  return { provider: resolvedProvider, model: resolvedModel, source: 'config' };
+}
+
+export function implementationRequestFromContext(
+  ctx: Pick<Context, 'runId' | 'input' | 'outputs'>,
+  env: { ELANOUS_GRAPH_CHILD_LLM_PROVIDER?: string; ELANOUS_GRAPH_CHILD_LLM_MODEL?: string },
+): { runId: string; feature: string; childLlm?: ChildLlmSelection } {
+  const prepared = ctx.outputs.prepare ?? {};
+  const goal = typeof prepared.goal === 'string' && prepared.goal.trim()
+    ? prepared.goal
+    : [ctx.input.ask, ctx.input['must-fix'], ctx.input['gate-log']].filter(Boolean).map(String).join('\n\n');
+  if (!goal.trim()) throw new Error('verb headless-goal-loop input missing: goal/ask');
+  const prior = prepared.prior ?? ctx.input.prior;
+  const childLlm = childLlmSelectionFromRecipe(
+    env.ELANOUS_GRAPH_CHILD_LLM_PROVIDER,
+    env.ELANOUS_GRAPH_CHILD_LLM_MODEL,
+  );
+  return {
+    runId: ctx.runId,
+    feature: appendPriorToGoal(goal, prior),
+    ...(childLlm ? { childLlm } : {}),
+  };
+}
+
+export function assertIsolatedFeatureWorktree(path: string): string {
+  if (!isAbsolute(path)) throw new Error('verb worktree must be absolute');
+  const cwd = realpathSync(path);
+  const root = execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8' }).trim();
+  if (root !== cwd) throw new Error('verb worktree must be a git repository root');
+  const gitDir = realpathSync(execFileSync('git', ['rev-parse', '--absolute-git-dir'], { cwd, encoding: 'utf8' }).trim());
+  const commonDirValue = execFileSync('git', ['rev-parse', '--git-common-dir'], { cwd, encoding: 'utf8' }).trim();
+  const commonDir = realpathSync(isAbsolute(commonDirValue) ? commonDirValue : resolve(cwd, commonDirValue));
+  if (gitDir === commonDir) throw new Error('verb worktree must be a separate linked Git worktree');
+  const branch = execFileSync('git', ['branch', '--show-current'], { cwd, encoding: 'utf8' }).trim();
+  if (!branch || branch === 'main' || branch === 'master') throw new Error('verb worktree must use an isolated feature branch');
+  return cwd;
+}
+
+export function assertNoNewCommit(cwd: string, beforeHead: string): void {
+  const afterHead = execFileSync('git', ['rev-parse', 'HEAD'], { cwd, encoding: 'utf8' }).trim();
+  if (afterHead !== beforeHead) throw new Error('headless goal-loop must leave changes uncommitted for its caller');
+}
+
+function targetWorktree(ctx: Context): string {
+  const prepared = ctx.outputs.prepare ?? {};
+  const value = prepared.worktree ?? ctx.input.worktree;
+  return assertIsolatedFeatureWorktree(required(value, 'worktree'));
+}
+
+export function outcomeForGraph(graphId: string, ok: boolean, documentDrafts: readonly string[]): 'done' | 'failed' {
+  if (!ok) return 'failed';
+  return graphId === 'verb-make-doc' && documentDrafts.length === 0 ? 'failed' : 'done';
+}
+
+function changedFileSnapshot(cwd: string): Map<string, string> {
+  const tracked = execFileSync('git', ['diff', '--no-renames', '--name-only', '-z', 'HEAD'], { cwd, encoding: 'utf8' }).split('\0');
+  const untracked = execFileSync('git', ['ls-files', '--others', '--exclude-standard', '-z'], { cwd, encoding: 'utf8' }).split('\0');
+  const snapshot = new Map<string, string>();
+  for (const file of new Set([...tracked, ...untracked].filter(Boolean))) {
+    try {
+      snapshot.set(file, createHash('sha256').update(readFileSync(resolve(cwd, file))).digest('hex'));
+    } catch { snapshot.set(file, '<missing>'); }
+  }
+  return snapshot;
+}
+
+async function run(): Promise<void> {
+  const ctx = context();
+  const cwd = targetWorktree(ctx);
+  const implementationRequest = implementationRequestFromContext(ctx, {
+    ELANOUS_GRAPH_CHILD_LLM_PROVIDER: process.env.ELANOUS_GRAPH_CHILD_LLM_PROVIDER,
+    ELANOUS_GRAPH_CHILD_LLM_MODEL: process.env.ELANOUS_GRAPH_CHILD_LLM_MODEL,
+  });
+  const seams = defaultSeams({ elanousBinRoot: repositoryRoot() });
+  if (!seams.implement) throw new Error('self-implement seam unavailable');
+  const headBefore = execFileSync('git', ['rev-parse', 'HEAD'], { cwd, encoding: 'utf8' }).trim();
+  const beforeFiles = changedFileSnapshot(cwd);
+  const result = await seams.implement({
+    cwd,
+    ...implementationRequest,
+  });
+  assertNoNewCommit(cwd, headBefore);
+  const afterFiles = changedFileSnapshot(cwd);
+  const changed = [...afterFiles].filter(([file, hash]) => beforeFiles.get(file) !== hash).map(([file]) => file);
+  const docs = changed.filter((file) => /\.(?:md|mdx|txt|rst|adoc)$/i.test(file) && afterFiles.get(file) !== '<missing>');
+  const outcome = outcomeForGraph(ctx.graphId, result.ok, docs);
+  process.stdout.write(`${JSON.stringify({
+    outcome,
+    result: result.summary,
+    evidence: {
+      worktree: cwd,
+      'document-drafts': docs,
+      'changed-files': changed,
+      'terminal-status': result.terminalStatus ?? 'unknown',
+    },
+  })}\n`);
+}
+
+if (import.meta.main) {
+  run().catch((error: unknown) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}

package/scripts/graph-units/verbs/verify-stage.ts

@@ -0,0 +1,75 @@
+/** Runs the existing gate and review seams for verb-verify. */
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { defaultSeams } from '../../../src/self-implement/seams.js';
+import { streamLLM } from '../../../src/llm.js';
+import { resolveRoleLlm } from '../../../src/user-config.js';
+
+type Context = {
+  graphId: string;
+  runId: string;
+  nodeId: string;
+  input: Record<string, unknown>;
+  outputs: Record<string, Record<string, unknown>>;
+};
+
+export function reviewOutcome(result: { reviewed: boolean; mustFix: readonly unknown[]; verdict?: string }): 'pass' | 'fail' | 'needs-human' {
+  if (!result.reviewed || result.verdict === 'needs-human') return 'needs-human';
+  return result.mustFix.length === 0 && (result.verdict === 'pass' || result.verdict === 'warn') ? 'pass' : 'fail';
+}
+
+function required(value: unknown, name: string): string {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`verb verify input missing: ${name}`);
+  return value;
+}
+
+function context(): Context {
+  const path = required(process.env.ELANOUS_GRAPH_CONTEXT, 'ELANOUS_GRAPH_CONTEXT');
+  const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'));
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('invalid verb verify context');
+  const ctx = parsed as Partial<Context>;
+  if (ctx.graphId !== 'verb-verify' || !ctx.input || !ctx.outputs || !ctx.runId || !ctx.nodeId)
+    throw new Error('invalid verb verify context');
+  if (process.env.ELANOUS_GRAPH_DRY_RUN === '1') throw new Error('dry run must use the side-effect-free recipe');
+  return ctx as Context;
+}
+
+async function run(): Promise<void> {
+  const stage = process.argv[2];
+  const ctx = context();
+  const prepared = ctx.outputs.prepare ?? {};
+  const cwd = required(prepared.worktree ?? ctx.input.worktree, 'worktree');
+  const seams = defaultSeams({
+    repoRoot: resolve(cwd),
+    elanousBinRoot: resolve(import.meta.dir, '../../..'),
+    llmReview: async (prompt) => streamLLM([{ role: 'user', content: prompt }], () => {}, { model: resolveRoleLlm('review').model }),
+  });
+
+  if (stage === 'gate') {
+    if (ctx.nodeId !== 'gate') throw new Error(`verb verify node mismatch: ${ctx.nodeId} / gate`);
+    const result = await seams.gate(cwd, { runId: ctx.runId });
+    process.stdout.write(`${JSON.stringify({ outcome: result.passed ? 'pass' : 'fail', passed: result.passed,
+      'gate-log': result.log ?? '' })}\n`);
+    return;
+  }
+  if (stage === 'review') {
+    if (ctx.nodeId !== 'review') throw new Error(`verb verify node mismatch: ${ctx.nodeId} / review`);
+    if (!seams.reviewDiff) throw new Error('verb verify review seam unavailable');
+    const intent = required(prepared['review-intent'] ?? ctx.input.ask, 'review-intent');
+    const result = await seams.reviewDiff(cwd, { runId: ctx.runId, goal: intent,
+      gateEvidenceNote: typeof ctx.outputs.gate?.['gate-log'] === 'string' ? ctx.outputs.gate['gate-log'] : undefined });
+    const outcome = reviewOutcome(result);
+    process.stdout.write(`${JSON.stringify({ outcome, verdict: result.verdict, reviewed: result.reviewed,
+      ...(result.failureReason ? { 'failure-reason': result.failureReason } : {}),
+      'must-fix': result.mustFix, 'review-summary': result.summary })}\n`);
+    return;
+  }
+  throw new Error(`unknown verb verify stage: ${stage ?? '<missing>'}`);
+}
+
+if (import.meta.main) {
+  run().catch((error: unknown) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}

package/scripts/graph-units/verbs-envelope.ts

@@ -0,0 +1,139 @@
+import { readFileSync } from 'node:fs';
+
+type JsonMap = Record<string, unknown>;
+interface GraphContext { readonly nodeId?: string; readonly input: unknown; readonly outputs: Record<string, unknown> }
+
+function record(value: unknown): JsonMap {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as JsonMap : {};
+}
+
+function firstValue(context: GraphContext, key: string): unknown {
+  const input = record(context.input);
+  if (Object.hasOwn(input, key) && input[key] !== undefined && input[key] !== null) return input[key];
+  for (const output of Object.values(context.outputs ?? {})) {
+    const value = record(output)[key];
+    if (value !== undefined && value !== null) return value;
+  }
+  return null;
+}
+
+const VERIFY_INPUTS = ['worktree', 'changed-files', 'diff', 'review-intent', 'must-fix', 'gate-log'] as const;
+const VERIFY_STARTS = new Set(['gate', 'review', 'rework']);
+
+export interface MakeDocInputs {
+  readonly goal: string;
+  readonly worktree: unknown;
+  readonly branch: unknown;
+  readonly 'review-intent': unknown;
+  readonly 'head-sha': unknown;
+  readonly 'base-branch': unknown;
+  readonly prior: unknown;
+}
+
+/** Converts the public make-doc envelope into the existing document-loop recipe contract. */
+export function unpackMakeDocEnvelope(envelope: { readonly ask?: unknown; readonly context?: unknown; readonly prior?: unknown }): MakeDocInputs {
+  const context = record(envelope.context);
+  const contextGoal = context.goal;
+  const ask = typeof envelope.ask === 'string' ? envelope.ask : '';
+  const reviewIntent = context['review-intent'] ?? (ask.trim() ? ask : null);
+  const goal = typeof contextGoal === 'string' && contextGoal.trim() ? contextGoal : ask;
+  return {
+    goal,
+    worktree: context.worktree ?? null,
+    branch: context.branch ?? null,
+    'review-intent': reviewIntent,
+    'head-sha': context['head-sha'] ?? null,
+    'base-branch': context['base-branch'] ?? null,
+    prior: envelope.prior ?? null,
+  };
+}
+
+/** Keeps the make-doc outputs present on every declared exit. */
+export function buildMakeDocOutput(context: GraphContext): JsonMap {
+  const draft = record(context.outputs?.['document-draft']);
+  const input = record(context.input);
+  const prior = record(input.prior);
+  const priorEvidence = record(prior.evidence);
+  const inputEvidence = record(input.evidence);
+  const draftEvidence = record(draft.evidence);
+  const evidence = { ...priorEvidence, ...inputEvidence, ...draftEvidence };
+  if (prior.result !== undefined) evidence['prior-result'] = prior.result;
+  return {
+    result: draft.result ?? draft.summary ?? input.result ?? null,
+    evidence,
+  };
+}
+
+/** Selects a verify entry while keeping every unit input explicit at the call boundary. */
+export function buildVerifyEnvelope(context: GraphContext): JsonMap {
+  const input = record(context.input);
+  const detail = record(input.context);
+  const prior = record(input.prior);
+  const priorResult = record(prior.result);
+  const priorEvidence = record(prior.evidence);
+  const start = detail.start_at ?? detail.startAt;
+  const startAt = typeof start === 'string' && VERIFY_STARTS.has(start) ? start : 'gate';
+  const envelope: JsonMap = {
+    outcome: startAt,
+    ...Object.fromEntries(VERIFY_INPUTS.map(key => [key, detail[key] ?? prior[key] ?? priorEvidence[key] ?? priorResult[key] ?? firstValue(context, key)])),
+  };
+  if (detail['review-intent'] == null && typeof input.ask === 'string' && input.ask.trim()) envelope['review-intent'] = input.ask;
+  return envelope;
+}
+
+/** Emits the complete verify output contract from whichever routes ran. */
+export function buildVerifyOutput(context: GraphContext, outcome: 'done' | 'rework' | 'needs-human' | 'failed'): JsonMap {
+  const input = record(context.input);
+  const prior = record(input.prior);
+  const priorEvidence = record(prior.evidence);
+  const outputsByNode = record(context.outputs);
+  const stageOrder = outcome === 'done'
+    ? ['prepare', 'rework-loop', 'gate', 'review']
+    : outcome === 'rework'
+      ? ['prepare', 'gate', 'review', 'rework-loop']
+      : (() => {
+        const source = ['prepare', 'gate', 'review', 'rework-loop']
+          .find(node => record(outputsByNode[node]).outcome === outcome);
+        if (source === 'gate') return ['prepare', 'review', 'rework-loop', 'gate'];
+        if (source === 'review') return ['prepare', 'rework-loop', 'gate', 'review'];
+        if (source === 'rework-loop') return ['prepare', 'gate', 'review', 'rework-loop'];
+        return ['prepare'];
+      })();
+  const outputs = stageOrder.map(node => record(outputsByNode[node]));
+  const evidence = { ...priorEvidence };
+  for (const output of outputs) Object.assign(evidence, record(output.evidence));
+  const latest = (key: string, aliases: readonly string[] = []): unknown => {
+    let value: unknown = priorEvidence[key] ?? null;
+    for (const output of outputs) {
+      const nodeValue = [key, ...aliases].map(name => output[name]).find(candidate => candidate !== undefined && candidate !== null);
+      const evidenceValue = record(output.evidence)[key];
+      if (nodeValue !== undefined) value = nodeValue;
+      else if (evidenceValue !== undefined && evidenceValue !== null) value = evidenceValue;
+    }
+    return value;
+  };
+  return {
+    result: outcome,
+    evidence: {
+      ...evidence,
+      ...(prior.result === undefined ? {} : { 'prior-result': prior.result }),
+      'review-summary': latest('review-summary', ['review_summary']),
+      'must-fix': outcome === 'done' ? [] : latest('must-fix', ['must_fix']),
+      'gate-log': latest('gate-log', ['gate_log']),
+    },
+  };
+}
+
+if (import.meta.main) {
+  const contextPath = process.env.ELANOUS_GRAPH_CONTEXT;
+  if (!contextPath) throw new Error('ELANOUS_GRAPH_CONTEXT is required');
+  const context = JSON.parse(readFileSync(contextPath, 'utf8')) as GraphContext;
+  const mode = process.argv[2];
+  const output = mode === 'make-doc-input'
+    ? unpackMakeDocEnvelope(record(context.input) as { ask?: unknown; context?: unknown; prior?: unknown })
+    : mode === 'make-doc-output' ? buildMakeDocOutput(context)
+      : mode === 'verify-envelope' ? buildVerifyEnvelope(context)
+      : mode === 'verify-output' ? buildVerifyOutput(context, process.argv[3] as 'done' | 'rework' | 'needs-human' | 'failed') : undefined;
+  if (!output) throw new Error(`unknown verbs-envelope mode: ${mode ?? '<missing>'}`);
+  process.stdout.write(`${JSON.stringify(output)}\n`);
+}