codex-workflow-v2 2.0.0-beta.13.8 → 2.0.0-beta.14

package/src/artifacts.ts

@@ -0,0 +1,130 @@
+import type { DiscoveryState, TaskPlanInput, TaskState } from './contracts.js';
+
+function list(values: string[], fallback = 'None.'): string {
+  return values.length > 0 ? values.map((value) => `- ${value}`).join('\n') : fallback;
+}
+
+export function renderBrief(discovery: DiscoveryState, title: string): string {
+  return [
+    `# ${title} Brief`,
+    '',
+    '## Goal',
+    '',
+    discovery.goal,
+    '',
+    '## Observable Outcome',
+    '',
+    discovery.outcome ?? '',
+    '',
+    '## Requirements',
+    '',
+    ...discovery.acceptance.map((value, index) => `- REQ-${String(index + 1).padStart(3, '0')}: ${value}`),
+    '',
+    '## Scope',
+    '',
+    list(discovery.scope),
+    '',
+    '## Out of Scope',
+    '',
+    list(discovery.outOfScope),
+    '',
+    '## Constraints',
+    '',
+    list(discovery.constraints),
+    '',
+    '## Acceptance Scenarios',
+    '',
+    ...discovery.acceptance.map((value, index) => `- AC-${String(index + 1).padStart(3, '0')}: ${value}`),
+    '',
+    '## Assumptions',
+    '',
+    list(discovery.assumptions),
+    '',
+    '## Non-Blocking Unknowns',
+    '',
+    list(discovery.unknowns.filter((value) => !discovery.blockingUnknowns.includes(value))),
+    '',
+  ].join('\n');
+}
+
+export function renderPlan(task: TaskState, plan: TaskPlanInput): string {
+  const lines = [
+    `# ${task.id} Plan`,
+    '',
+    '## Objective',
+    '',
+    plan.objective,
+    '',
+    '## Requirements',
+    '',
+    ...plan.requirements.map((value) => `- ${value}`),
+    '',
+    '## Acceptance',
+    '',
+    ...plan.acceptance.map((value) => `- ${value}`),
+    '',
+    '## Risks',
+    '',
+    list(plan.risks),
+    '',
+    '## Project Knowledge Impact',
+    '',
+    `- Impact: ${plan.knowledgeImpact}`,
+    `- Reason: ${plan.knowledgeImpactReason}`,
+    `- Knowledge map: revision ${plan.knowledgeMapRevision}, hash ${plan.knowledgeMapHash}`,
+    `- Graph use: ${plan.graphUse}`,
+    ...plan.knowledgeTargets.map((target) => `- ${target.category}: ${target.path} — ${target.reason} (${target.requirementIds.join(', ')})`),
+    '',
+    '## Production Edges',
+    '',
+    `- Required: ${plan.requiresProductionEdges === true ? 'yes' : 'no'}`,
+    ...(plan.productionEdges ?? []).map((edge) =>
+      `- ${edge.ownerStepId} -> ${edge.consumerStepId}; check: ${edge.checkRef}`),
+    ...((plan.productionEdges ?? []).length === 0 ? ['- none'] : []),
+    '',
+
+    '## Steps',
+    '',
+  ];
+  for (const step of plan.steps) {
+    lines.push(
+      `### ${step.id}: ${step.title}`,
+      '',
+      step.objective,
+      '',
+      `- Requirements: ${step.requirements.join(', ')}`,
+      `- Dependencies: ${step.dependencies.join(', ') || 'none'}`,
+      `- Expected outputs: ${step.expectedOutputs.join(', ')}`,
+      `- Allowed writes: ${step.allowedWrites.join(', ')}`,
+      `- Forbidden scope: ${step.forbiddenScope.join(', ') || 'none'}`,
+      `- Checks: ${step.checks.join(' ; ') || 'UNVERIFIED'}`,
+      '',
+    );
+  }
+  return lines.join('\n');
+}
+
+export function renderResult(task: TaskState, summary: string, limitations: string[]): string {
+  return [
+    `# ${task.id} Result`,
+    '',
+    '## Summary',
+    '',
+    summary,
+    '',
+    '## Completed Steps',
+    '',
+    ...task.steps.filter((step) => step.status === 'completed').map((step) => `- ${step.id}: ${step.title}`),
+    '',
+    '## Commits',
+    '',
+    ...task.steps
+      .filter((step) => step.evidence)
+      .map((step) => `- ${step.id}: ${step.evidence?.commitSha ?? 'missing'}`),
+    '',
+    '## Limitations',
+    '',
+    list(limitations),
+    '',
+  ].join('\n');
+}

package/src/beta1/project-transaction.ts

@@ -0,0 +1,355 @@
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { WorkflowError } from '../errors.js';
+import { ensureDirectory, writeJsonAtomic, writeTextAtomic } from '../fs-utils.js';
+
+type TransactionPhase = 'prepared' | 'applying' | 'applied' | 'rolled_back';
+
+interface Snapshot {
+  exists: boolean;
+  contentHash: string | null;
+  contentBase64: string | null;
+}
+
+interface JournalTarget {
+  path: string;
+  preimage: Snapshot;
+  staged: Snapshot;
+}
+
+interface ProjectTransactionJournal {
+  schemaVersion: 1;
+  transactionId: string;
+  kind: string;
+  projectId: string;
+  phase: TransactionPhase;
+  recoveryMode: 'roll-forward' | 'roll-back';
+  ownerPid: number;
+  ownerHostname: string;
+  targets: JournalTarget[];
+  preparedAt: string;
+  updatedAt: string;
+}
+
+export interface ProjectTransactionTarget {
+  path: string;
+  content: string | null;
+}
+
+export interface ProjectTransactionOptions {
+  projectRoot: string;
+  projectId: string;
+  transactionId: string;
+  kind: string;
+  targets: ProjectTransactionTarget[];
+  now: Date;
+  validate?: () => void;
+  afterTargetWrite?: (index: number, target: ProjectTransactionTarget) => void;
+}
+
+const TRANSACTION_ID = /^[a-z0-9][a-z0-9-]{7,127}$/;
+const activeProjectRoots = new Set<string>();
+
+export function applyProjectTransaction(options: ProjectTransactionOptions): void {
+  recoverProjectTransactions(options.projectRoot, options.projectId);
+  validateTransactionId(options.transactionId);
+  if (!options.kind.trim()) throw new WorkflowError('INVALID_ARGUMENT', 'Project transaction kind is required.');
+  if (options.targets.length === 0) throw new WorkflowError('INVALID_ARGUMENT', 'Project transaction requires targets.');
+  const paths = options.targets.map((target) => normalizeTargetPath(target.path));
+  if (new Set(paths).size !== paths.length) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Project transaction target paths must be unique.');
+  }
+  const journal: ProjectTransactionJournal = {
+    schemaVersion: 1,
+    transactionId: options.transactionId,
+    kind: options.kind.trim(),
+    projectId: options.projectId,
+    phase: 'prepared',
+    recoveryMode: 'roll-forward',
+    ownerPid: process.pid,
+    ownerHostname: os.hostname(),
+    targets: options.targets.map((target, index) => ({
+      path: paths[index]!,
+      preimage: captureSnapshot(resolveTarget(options.projectRoot, paths[index]!)),
+      staged: snapshotFromContent(target.content),
+    })),
+    preparedAt: options.now.toISOString(),
+    updatedAt: options.now.toISOString(),
+  };
+  writeJournal(options.projectRoot, journal);
+  const activeKey = path.resolve(options.projectRoot);
+  activeProjectRoots.add(activeKey);
+  try {
+    writeJournal(options.projectRoot, { ...journal, phase: 'applying', updatedAt: options.now.toISOString() });
+    journal.targets.forEach((target, index) => {
+      restoreSnapshot(resolveTarget(options.projectRoot, target.path), target.staged);
+      options.afterTargetWrite?.(index, options.targets[index]!);
+    });
+    options.validate?.();
+    writeJournal(options.projectRoot, { ...journal, phase: 'applied', updatedAt: options.now.toISOString() });
+    removeJournal(options.projectRoot, options.transactionId);
+  } catch (error) {
+    rollback(options.projectRoot, journal);
+    throw error;
+  } finally {
+    activeProjectRoots.delete(activeKey);
+  }
+}
+
+export function recoverProjectTransactions(projectRoot: string, projectId: string): string[] {
+  if (activeProjectRoots.has(path.resolve(projectRoot))) return [];
+  const directory = transactionDirectory(projectRoot);
+  if (!existsSync(directory)) return [];
+  const recovered: string[] = [];
+  for (const entry of readdirSync(directory, { withFileTypes: true }).filter((item) => item.isFile() && item.name.endsWith('.json'))) {
+    const file = path.join(directory, entry.name);
+    const journal = parseJournal(file, projectRoot, projectId);
+    if ((journal.phase === 'prepared' || journal.phase === 'applying') && journal.ownerHostname === os.hostname() && processIsAlive(journal.ownerPid)) {
+      throw new WorkflowError('TRANSITION_BLOCKED', 'A project transaction is still owned by a live process.', {
+        transactionId: journal.transactionId,
+        kind: journal.kind,
+        ownerPid: journal.ownerPid,
+        requiredAction: 'Wait for the active command to finish; after its owner exits, obtain fresh next and run the advertised recovery.',
+      });
+    }
+    if (journal.phase === 'prepared' || journal.phase === 'rolled_back') {
+      rollback(projectRoot, journal);
+      recovered.push(journal.transactionId);
+      continue;
+    }
+    if (journal.phase === 'applied') {
+      if (journal.recoveryMode === 'roll-forward') {
+        for (const target of journal.targets) restoreSnapshot(resolveTarget(projectRoot, target.path), target.staged);
+      }
+      removeJournal(projectRoot, journal.transactionId);
+      recovered.push(journal.transactionId);
+      continue;
+    }
+    if (journal.recoveryMode === 'roll-back') {
+      rollback(projectRoot, journal);
+      recovered.push(journal.transactionId);
+      continue;
+    }
+    for (const target of journal.targets) {
+      const current = captureSnapshot(resolveTarget(projectRoot, target.path));
+      if (!snapshotsEqual(current, target.preimage) && !snapshotsEqual(current, target.staged)) {
+        throw new WorkflowError('STATE_CORRUPT', 'Project transaction target diverged during recovery.', {
+          transactionId: journal.transactionId,
+          target: target.path,
+        });
+      }
+    }
+    for (const target of journal.targets) restoreSnapshot(resolveTarget(projectRoot, target.path), target.staged);
+    removeJournal(projectRoot, journal.transactionId);
+    recovered.push(journal.transactionId);
+  }
+  return recovered;
+}
+
+export function runRollbackProjectTransaction<T>(options: {
+  projectRoot: string;
+  projectId: string;
+  transactionId: string;
+  kind: string;
+  targetPaths: string[];
+  now: Date;
+  mutate: () => T;
+  validate?: (result: T) => void;
+}): T {
+  recoverProjectTransactions(options.projectRoot, options.projectId);
+  validateTransactionId(options.transactionId);
+  const paths = options.targetPaths.map(normalizeTargetPath);
+  if (paths.length === 0 || new Set(paths).size !== paths.length) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Rollback project transaction requires unique targets.');
+  }
+  const targets = paths.map((targetPath) => {
+    const preimage = captureSnapshot(resolveTarget(options.projectRoot, targetPath));
+    return { path: targetPath, preimage, staged: preimage };
+  });
+  const journal: ProjectTransactionJournal = {
+    schemaVersion: 1,
+    transactionId: options.transactionId,
+    kind: options.kind,
+    projectId: options.projectId,
+    phase: 'prepared',
+    recoveryMode: 'roll-back',
+    ownerPid: process.pid,
+    ownerHostname: os.hostname(),
+    targets,
+    preparedAt: options.now.toISOString(),
+    updatedAt: options.now.toISOString(),
+  };
+  const activeKey = path.resolve(options.projectRoot);
+  writeJournal(options.projectRoot, journal);
+  activeProjectRoots.add(activeKey);
+  try {
+    writeJournal(options.projectRoot, { ...journal, phase: 'applying', updatedAt: options.now.toISOString() });
+    const result = options.mutate();
+    options.validate?.(result);
+    writeJournal(options.projectRoot, { ...journal, phase: 'applied', updatedAt: options.now.toISOString() });
+    removeJournal(options.projectRoot, journal.transactionId);
+    return result;
+  } catch (error) {
+    rollback(options.projectRoot, journal);
+    throw error;
+  } finally {
+    activeProjectRoots.delete(activeKey);
+  }
+}
+
+export function listProjectTransactions(projectRoot: string, projectId: string): Array<Pick<ProjectTransactionJournal, 'transactionId' | 'kind' | 'phase' | 'preparedAt'> & { ownerActive: boolean }> {
+  const directory = transactionDirectory(projectRoot);
+  if (!existsSync(directory)) return [];
+  return readdirSync(directory, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+    .map((entry) => parseJournal(path.join(directory, entry.name), projectRoot, projectId))
+    .map(({ transactionId, kind, phase, preparedAt, ownerPid, ownerHostname }) => ({
+      transactionId, kind, phase, preparedAt,
+      ownerActive: (phase === 'prepared' || phase === 'applying')
+        && ownerHostname === os.hostname() && processIsAlive(ownerPid),
+    }));
+}
+
+function rollback(projectRoot: string, journal: ProjectTransactionJournal): void {
+  for (const target of journal.targets) restoreSnapshot(resolveTarget(projectRoot, target.path), target.preimage);
+  writeJournal(projectRoot, { ...journal, phase: 'rolled_back', updatedAt: new Date().toISOString() });
+  removeJournal(projectRoot, journal.transactionId);
+}
+
+function transactionDirectory(projectRoot: string): string {
+  return path.join(projectRoot, '.transactions-beta1');
+}
+
+function journalPath(projectRoot: string, transactionId: string): string {
+  validateTransactionId(transactionId);
+  return path.join(transactionDirectory(projectRoot), `${transactionId}.json`);
+}
+
+function writeJournal(projectRoot: string, journal: ProjectTransactionJournal): void {
+  ensureDirectory(transactionDirectory(projectRoot));
+  writeJsonAtomic(journalPath(projectRoot, journal.transactionId), journal);
+}
+
+function removeJournal(projectRoot: string, transactionId: string): void {
+  rmSync(journalPath(projectRoot, transactionId), { force: true });
+}
+
+function parseJournal(file: string, projectRoot: string, projectId: string): ProjectTransactionJournal {
+  let value: unknown;
+  try {
+    value = JSON.parse(readFileSync(file, 'utf8'));
+  } catch (error) {
+    throw new WorkflowError('STATE_CORRUPT', `Cannot read project transaction journal: ${file}`, {
+      cause: error instanceof Error ? error.message : String(error),
+    });
+  }
+  const journal = value as Partial<ProjectTransactionJournal>;
+  if (journal.schemaVersion !== 1 || journal.projectId !== projectId || !journal.transactionId || !journal.kind
+    || !['roll-forward', 'roll-back'].includes(journal.recoveryMode ?? '')
+    || !Number.isInteger(journal.ownerPid) || (journal.ownerPid ?? 0) < 1 || !journal.ownerHostname
+    || !['prepared', 'applying', 'applied', 'rolled_back'].includes(journal.phase ?? '') || !Array.isArray(journal.targets)) {
+    throw new WorkflowError('STATE_CORRUPT', `Invalid project transaction journal: ${file}`);
+  }
+  validateTransactionId(journal.transactionId);
+  const expectedFile = journalPath(projectRoot, journal.transactionId);
+  if (path.resolve(file) !== path.resolve(expectedFile)) {
+    throw new WorkflowError('STATE_CORRUPT', `Project transaction journal filename mismatch: ${file}`);
+  }
+  for (const target of journal.targets) {
+    normalizeTargetPath(target.path);
+    validateSnapshot(target.preimage);
+    validateSnapshot(target.staged);
+  }
+  return journal as ProjectTransactionJournal;
+}
+
+function normalizeTargetPath(value: string): string {
+  const normalized = value.split(path.sep).join('/');
+  if (!normalized || path.isAbsolute(normalized) || normalized.split('/').some((part) => !part || part === '.' || part === '..')) {
+    throw new WorkflowError('INVALID_ARGUMENT', `Invalid project transaction target: ${value}`);
+  }
+  if (normalized === '.transactions-beta1' || normalized.startsWith('.transactions-beta1/')) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Project transaction cannot target its journal directory.');
+  }
+  return normalized;
+}
+
+function resolveTarget(projectRoot: string, relativePath: string): string {
+  const root = path.resolve(projectRoot);
+  const target = path.resolve(root, normalizeTargetPath(relativePath));
+  if (!target.startsWith(`${root}${path.sep}`)) throw new WorkflowError('INVALID_ARGUMENT', 'Project transaction target escaped project root.');
+  let current = root;
+  for (const part of path.relative(root, path.dirname(target)).split(path.sep).filter(Boolean)) {
+    current = path.join(current, part);
+    if (existsSync(current) && lstatSync(current).isSymbolicLink()) {
+      throw new WorkflowError('STATE_CORRUPT', `Project transaction target traverses a symlink: ${relativePath}`);
+    }
+  }
+  if (existsSync(target) && lstatSync(target).isSymbolicLink()) {
+    throw new WorkflowError('STATE_CORRUPT', `Project transaction target is a symlink: ${relativePath}`);
+  }
+  return target;
+}
+
+function captureSnapshot(file: string): Snapshot {
+  if (!existsSync(file)) return { exists: false, contentHash: null, contentBase64: null };
+  const content = readFileSync(file);
+  return { exists: true, contentHash: sha256(content), contentBase64: content.toString('base64') };
+}
+
+function snapshotFromContent(content: string | null): Snapshot {
+  if (content === null) return { exists: false, contentHash: null, contentBase64: null };
+  const normalized = Buffer.from(content.endsWith('\n') ? content : `${content}\n`);
+  return { exists: true, contentHash: sha256(normalized), contentBase64: normalized.toString('base64') };
+}
+
+function restoreSnapshot(file: string, snapshot: Snapshot): void {
+  validateSnapshot(snapshot);
+  if (!snapshot.exists) {
+    rmSync(file, { force: true });
+    return;
+  }
+  writeTextAtomic(file, Buffer.from(snapshot.contentBase64!, 'base64').toString('utf8'));
+  if (!snapshotsEqual(captureSnapshot(file), snapshot)) {
+    throw new WorkflowError('STATE_CORRUPT', `Project transaction snapshot restore failed: ${file}`);
+  }
+}
+
+function validateSnapshot(snapshot: Snapshot): void {
+  if (!snapshot || typeof snapshot !== 'object' || typeof snapshot.exists !== 'boolean') {
+    throw new WorkflowError('STATE_CORRUPT', 'Invalid project transaction snapshot.');
+  }
+  if (!snapshot.exists) {
+    if (snapshot.contentHash !== null || snapshot.contentBase64 !== null) throw new WorkflowError('STATE_CORRUPT', 'Absent snapshot contains data.');
+    return;
+  }
+  if (!snapshot.contentHash || !/^[a-f0-9]{64}$/.test(snapshot.contentHash) || snapshot.contentBase64 === null) {
+    throw new WorkflowError('STATE_CORRUPT', 'Existing project transaction snapshot is incomplete.');
+  }
+  if (sha256(Buffer.from(snapshot.contentBase64, 'base64')) !== snapshot.contentHash) {
+    throw new WorkflowError('STATE_CORRUPT', 'Project transaction snapshot hash mismatch.');
+  }
+}
+
+function snapshotsEqual(left: Snapshot, right: Snapshot): boolean {
+  return left.exists === right.exists && left.contentHash === right.contentHash;
+}
+
+function sha256(content: Buffer): string {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+function validateTransactionId(value: string): void {
+  if (!TRANSACTION_ID.test(value)) throw new WorkflowError('INVALID_ARGUMENT', `Invalid project transaction id: ${value}`);
+}
+
+function processIsAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return Boolean(error && typeof error === 'object' && 'code' in error && error.code === 'EPERM');
+  }
+}

package/src/change-explanation.ts

@@ -0,0 +1,153 @@
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import type { TaskState } from './contracts.js';
+import { pathAllowed } from './domain/validation.js';
+import { WorkflowError } from './errors.js';
+import { currentBranch, headCommit, resolveRepositoryIdentity, runGit } from './repository.js';
+import { hashDirtyWorktree } from './alpha6/downstream-proof.js';
+
+export interface ChangeExplanationInput {
+  reason: string;
+  paths: string[];
+  intent?: 'implementation' | 'membership' | 'semantic-scope';
+  expectedRevision?: number;
+  expectedPlanHash?: string;
+  executionContext?: { cwd: string; writeRoot: string; expectedBranch: string };
+  externalDecision?: 'denied' | 'unknown';
+}
+
+type Blocker = { layer: string; code: string; resolution: string };
+const object = (value: unknown): Record<string, unknown> => value !== null && typeof value === 'object'
+  && !Array.isArray(value) ? value as Record<string, unknown> : {};
+
+function validate(input: ChangeExplanationInput) {
+  const keys = ['reason', 'paths', 'intent', 'expectedRevision', 'expectedPlanHash', 'executionContext', 'externalDecision'];
+  if (!input || typeof input !== 'object' || Object.keys(input).some(key => !keys.includes(key))
+    || typeof input.reason !== 'string' || !input.reason.trim() || input.reason.length > 4000
+    || !Array.isArray(input.paths) || input.paths.length > 256
+    || input.paths.some(p => typeof p !== 'string' || !p || p.includes('\\') || p.includes('\0')
+      || /[*?\[\]{}]/.test(p) || path.isAbsolute(p) || p.split('/').some(x => !x || x === '.' || x === '..'))
+    || (input.intent !== undefined && !['implementation', 'membership', 'semantic-scope'].includes(input.intent))
+    || (input.externalDecision !== undefined && !['denied', 'unknown'].includes(input.externalDecision))
+    || (input.expectedRevision !== undefined && (!Number.isSafeInteger(input.expectedRevision) || input.expectedRevision < 1))
+    || (input.expectedPlanHash !== undefined && !/^[a-f0-9]{64}$/.test(input.expectedPlanHash))) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Expected a closed change explanation with reason and normalized repository-relative paths.');
+  }
+  const ctx = input.executionContext;
+  if (ctx !== undefined && (!ctx || typeof ctx !== 'object'
+    || Object.keys(ctx).sort().join(',') !== 'cwd,expectedBranch,writeRoot'
+    || [ctx.cwd, ctx.writeRoot, ctx.expectedBranch].some(x => typeof x !== 'string' || !x.trim())
+    || !path.isAbsolute(ctx.cwd) || !path.isAbsolute(ctx.writeRoot))) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'executionContext requires absolute cwd/writeRoot and expectedBranch.');
+  }
+}
+
+// Resolve existing ancestors as well as non-existing destinations; do not read through symlinks.
+function outsideRoot(root: string, file: string): boolean {
+  let ancestor = path.join(root, file);
+  while (!existsSync(ancestor)) {
+    try { if (lstatSync(ancestor).isSymbolicLink()) return true; } catch { /* missing path */ }
+    const parent = path.dirname(ancestor);
+    if (parent === ancestor) return true;
+    ancestor = parent;
+  }
+  const relative = path.relative(root, realpathSync(ancestor));
+  return relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative);
+}
+
+/** Explanation only: never issues a credential, writes state, or grants permission to apply a patch. */
+export function explainChange(input: ChangeExplanationInput, repository: string,
+  task: TaskState | undefined, next: Record<string, unknown>) {
+  validate(input);
+  const identity = resolveRepositoryIdentity(repository);
+  const root = realpathSync(identity.repositoryRoot);
+  const blockers: Blocker[] = [];
+  const add = (layer: string, code: string, resolution: string) => blockers.push({ layer, code, resolution });
+  const dirty = [...new Set([
+    ...runGit(root, ['diff', 'HEAD', '--name-only', '-z']).split('\0'),
+    ...runGit(root, ['ls-files', '--others', '--exclude-standard', '-z']).split('\0'),
+  ].filter(Boolean))].sort();
+  const paths = [...new Set([...input.paths, ...dirty])].sort();
+  const escaped = paths.filter(p => outsideRoot(root, p));
+  if (escaped.length) add('execution-context', 'WRITE_PATH_ESCAPES_CHECKOUT', 'Resolve the symlink or target mismatch before proposing a write.');
+  let contextState = 'not-supplied';
+  if (input.executionContext) {
+    contextState = 'matched';
+    try {
+      const ctx = input.executionContext;
+      const observed = resolveRepositoryIdentity(ctx.cwd);
+      if (realpathSync(observed.repositoryRoot) !== root || realpathSync(ctx.writeRoot) !== root
+        || currentBranch(root) !== ctx.expectedBranch
+        || (task?.taskBranch !== null && task?.taskBranch !== undefined && ctx.expectedBranch !== task.taskBranch)) {
+        contextState = 'mismatch';
+        add('execution-context', 'EXECUTION_CONTEXT_MISMATCH', 'Reconcile the existing Worker checkout and fresh Task branch; do not retry in another chat or silently change the target.');
+      }
+    } catch {
+      contextState = 'unverified';
+      add('execution-context', 'EXECUTION_CONTEXT_UNVERIFIED', 'Obtain a readable current checkout observation.');
+    }
+  }
+  if (input.externalDecision === 'denied') add('external-approval', 'EXTERNAL_OPERATION_DENIED',
+    'Preserve the denial. Prepare safe evidence or obtain the exact external authorization; a Workflow grant does not override it.');
+  if (input.expectedRevision !== undefined && input.expectedRevision !== task?.revision
+    || input.expectedPlanHash !== undefined && input.expectedPlanHash !== task?.planHash) {
+    add('integrity', 'STALE_CHANGE_BINDING', 'Refresh the proposal from the current Task revision and Plan.');
+  }
+  const action = typeof next.action === 'string' ? next.action : 'blocked';
+  if (next.status === 'observation-blocked' || next.status === 'repair-required') {
+    add('integrity', 'CORE_OBSERVATION_UNAVAILABLE', 'Complete the exact Core observation/recovery route before changing work.');
+  }
+  const step = task?.steps.find(s => s.id === next.stepId)
+    ?? task?.steps.find(s => s.status === 'in_progress' || s.status === 'failed');
+  const outOfPlan = paths.filter(p => !step || !pathAllowed(p, step.allowedWrites) || pathAllowed(p, step.forbiddenScope));
+  const recovery = object(next.planIntegrityRecovery);
+  const supporting = recovery.state === 'eligible'
+    && (action === 'task plan-integrity-recover' || next.blockedAction === 'task plan-integrity-recover')
+    && recovery.boundedEffect === 'record-machine-derived-check-support-scope';
+  const evidence = object(recovery.evidence);
+  const scope = Array.isArray(evidence.scopeExtensions) ? evidence.scopeExtensions.filter((x): x is string => typeof x === 'string') : [];
+  const bounded = supporting && outOfPlan.every(p => scope.includes(p));
+  let kind = 'implementation';
+  let decisionBasis = 'No automatic conclusion about semantic safety; follow the current Core route.';
+  if (input.intent === 'semantic-scope') {
+    kind = 'semantic-scope';
+    add('workflow', 'HUMAN_SEMANTIC_DECISION', 'Resolve the changed outcome or acceptance with the user through the scope-change route.');
+  } else if (input.intent === 'membership' || next.auditedRemediation) {
+    kind = 'membership';
+    decisionBasis = 'Membership is separate from Step implementation. Use only the advertised bounded topology route or a separately confirmed scope change.';
+  } else if (bounded) {
+    kind = 'bounded-plan-amendment';
+    decisionBasis = 'Core derived an exact check-support extension. Use its existing recovery; do not edit allowedWrites or grant authority manually.';
+  } else if (/replan|corrective-yield|downstream-proof/.test(action) || recovery.boundedEffect === 'record-replan-required-decision') {
+    kind = 'corrective-plan';
+    decisionBasis = 'Core identified a Plan/recovery conflict; preserve historical evidence and the existing Task.';
+  } else if (action === 'task context-refresh' || action === 'task knowledge-rebind') {
+    kind = 'context-refresh';
+    decisionBasis = 'Context refresh is independent of Plan correction and cannot acknowledge a Plan conflict.';
+  } else if (outOfPlan.length) {
+    kind = 'plan-review';
+    add('workflow', 'UNPROVED_SCOPE_EXTENSION', 'Establish a Core-supported extension or revise the Plan. File count and user-declared intent are not safety evidence.');
+  }
+  const delegated = Array.isArray(next.delegatedApprovalOptions) && next.delegatedApprovalOptions.length > 0;
+  const derived = object(next.correctiveDerivedApproval).humanApprovalRequired === false;
+  const humanGate = !!next.requiredHumanGate || ['task authorize', 'task accept', 'milestone authorize', 'milestone accept', 'project-memory approve'].includes(action);
+  if (humanGate && !delegated && !derived) add('workflow', 'CURRENT_HUMAN_GATE', 'Use the current exact human gate; this explanation issues no authority.');
+  const head = headCommit(root);
+  const binding = { projectId: identity.projectId, repositoryRoot: root, taskId: task?.id ?? null,
+    revision: task?.revision ?? null, planHash: task?.planHash ?? null, head,
+    proposedPaths: [...new Set(input.paths)].sort(), observedDirtyPaths: dirty, proposedPathBytesHash: escaped.length ? null : hashDirtyWorktree(root, paths),
+    requestHash: createHash('sha256').update(JSON.stringify(input)).digest('hex'), existingAction: action };
+  return { kind: 'change-explanation', version: 1, readOnly: true, authority: 'none', changeKind: kind,
+    decisionBasis, binding, proposalHash: createHash('sha256').update(JSON.stringify(binding)).digest('hex'),
+    executionContext: { state: contextState, externallyEnforced: false }, blockers,
+    existingRoute: { action, blockedByExplanation: blockers.length > 0, recheckNextBeforeMutation: true },
+    proposedPaths: paths, outsideCurrentStep: outOfPlan,
+    boundedAmendment: bounded && kind === 'bounded-plan-amendment' ? { route: 'task plan-integrity-recover', prerequisite: action === 'task plan-integrity-recover' ? null : action, scopeExtensions: scope, effect: recovery.boundedEffect } : null,
+    requiresUser: blockers.some(b => ['EXTERNAL_OPERATION_DENIED', 'HUMAN_SEMANTIC_DECISION', 'CURRENT_HUMAN_GATE'].includes(b.code)) ? true : null,
+    validationNeeded: ['Fresh status and next; current revision, Plan, HEAD and file bytes.',
+      'Current Worker checkout, branch and writer credential; external approval remains independent.',
+      'Preserve requirements, acceptance, checks and historical evidence; review the exact diff.'],
+    limitations: ['Not an apply command or proof of external permission.',
+      'Unspecified risks and blockers may remain. No inference of semantic safety from paths or diff size.'] };
+}