elanous 0.2.32 → 0.2.35

package/scripts/docs/generate-graph-anatomy.ts

@@ -26,6 +26,7 @@ import {
   type GraphParseIssue,
   type GraphTemplateSpec,
 } from '../../src/self-implement/graph-yaml.js';
+import { flattenGraphTemplate } from '../../src/self-implement/graph-unit-resolver.js';
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 
 /** drafts/ · overlays/ 는 스캔에서 뺀다(실측 10-05). 그 이름인 디렉터리와 그 아래는 안 읽는다. */
@@ -104,7 +105,22 @@ function graphFileNames(abs: string): string[] {
 
 /** loadGraphTemplates for harness dirs; the runner's reading for workflow-graph dirs (same result shape). */
 function loadDir(abs: string): GraphLoadResult {
-  if (!isRunnerDir(abs)) return loadGraphTemplates(abs);
+  if (!isRunnerDir(abs)) {
+    const loaded = loadGraphTemplates(abs);
+    if (loaded.scannedFiles === 0) return loaded;
+    const errors = [...loaded.errors];
+    const templates: Record<string, GraphTemplateSpec> = {};
+    for (const file of graphFileNames(abs)) {
+      let source: string;
+      try { source = readFileSync(join(abs, file), 'utf8'); }
+      catch (error) { errors.push({ path: file, message: `읽기 실패: ${String(error)}` }); continue; }
+      const parsed = parseGraphTemplateYaml(source, file);
+      if (!parsed.template || parsed.errors.length) continue;
+      try { templates[parsed.template.graphId] = flattenGraphTemplate(parsed.template, join(abs, file)); }
+      catch (error) { errors.push({ path: file, message: `unit 펼침 실패: ${error instanceof Error ? error.message : String(error)}` }); }
+    }
+    return { ...loaded, templates, errors };
+  }
   const errors: GraphParseIssue[] = [];
   const warnings: GraphParseIssue[] = [];
   const templates: Record<string, GraphTemplateSpec> = {};
@@ -120,7 +136,8 @@ function loadDir(abs: string): GraphLoadResult {
     warnings.push(...result.warnings);
     if (!result.template) continue;
     if (templates[result.template.graphId]) { errors.push({ path: file, message: `graph_id '${result.template.graphId}' 가 중복이다` }); continue; }
-    templates[result.template.graphId] = result.template;
+    try { templates[result.template.graphId] = flattenGraphTemplate(result.template, join(abs, file)); }
+    catch (error) { errors.push({ path: file, message: `unit 펼침 실패: ${error instanceof Error ? error.message : String(error)}` }); }
   }
   return { templates, errors, warnings, scannedFiles: files.length };
 }

package/scripts/graph-harvest-unit.ts

@@ -0,0 +1,22 @@
+import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { runHarvestUnit, type HarvestInput } from '../src/task-agent/harvest-unit.js';
+
+type GraphContext = { input?: HarvestInput };
+if (process.argv.includes('--dry-run')) {
+  console.log(JSON.stringify({ outcome: 'done', result: { dryRun: true }, evidence: { reviewerInvoked: false } }));
+  process.exit(0);
+}
+const contextPath = process.env.ELANOUS_GRAPH_CONTEXT;
+if (!contextPath) throw new Error('ELANOUS_GRAPH_CONTEXT is required');
+const graphContext = JSON.parse(readFileSync(contextPath, 'utf8')) as GraphContext;
+
+const result = await runHarvestUnit(graphContext.input ?? {}, async ({ pr, intent }) => {
+  const command = process.env.ELANOUS_BIN ?? 'eln';
+  const child = spawnSync(command, [
+    'self', 'review', pr, '--intent', intent, '--json', '--save', 'ta-harvest',
+  ], { encoding: 'utf8', timeout: 300_000, maxBuffer: 8 * 1024 * 1024 });
+  if (child.error) throw child.error;
+  return { stdout: child.stdout ?? '', stderr: child.stderr ?? '', exitCode: child.status };
+});
+console.log(JSON.stringify(result));

package/scripts/graph-units/journey-stub.ts

@@ -0,0 +1,6 @@
+const stage = process.argv[2] ?? 'unknown';
+process.stdout.write(`${JSON.stringify({
+  outcome: 'needs-human',
+  result: { stage, state: 'stub' },
+  evidence: { reason: 'owner unit has not been integrated' },
+})}\n`);

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;
+  });
+}