codex-workflow-v2 2.0.0-beta.13.14 → 2.0.0-beta.13.16

package/src/domain/completed-step-carryover.ts

@@ -0,0 +1,76 @@
+import type { PlanStepInput, TaskPlanInput, TaskState } from '../contracts.js';
+
+type TaskStep = TaskState['steps'][number];
+
+/**
+ * Derive the completed Steps whose authority remains valid under a replacement Plan.
+ *
+ * A completed Step is retained only when its executable definition is unchanged and
+ * every dependency is itself retained. The recursive dependency check makes the
+ * result independent from candidate Plan ordering and fails closed on malformed
+ * dependency cycles even though ordinary Plan validation rejects cycles earlier.
+ */
+export function deriveCompletedStepCarryover(
+  task: TaskState,
+  candidateSteps: readonly TaskPlanInput['steps'][number][],
+): ReadonlyMap<string, TaskStep> {
+  const duplicateCandidateIds = new Set<string>();
+  const candidateById = new Map<string, PlanStepInput>();
+  for (const candidate of candidateSteps) {
+    if (candidateById.has(candidate.id)) duplicateCandidateIds.add(candidate.id);
+    else candidateById.set(candidate.id, normalizePlanStepDefinition(candidate));
+  }
+
+  const exactCompletedById = new Map<string, TaskStep>();
+  for (const previous of task.steps) {
+    if (previous.status !== 'completed' || duplicateCandidateIds.has(previous.id)) continue;
+    const candidate = candidateById.get(previous.id);
+    if (!candidate) continue;
+    if (samePlanStepDefinition(previous, candidate)) exactCompletedById.set(previous.id, previous);
+  }
+
+  const retained = new Map<string, TaskStep>();
+  const rejected = new Set<string>();
+  const visiting = new Set<string>();
+  const retain = (stepId: string): boolean => {
+    if (retained.has(stepId)) return true;
+    if (rejected.has(stepId) || visiting.has(stepId)) return false;
+    const previous = exactCompletedById.get(stepId);
+    if (!previous) {
+      rejected.add(stepId);
+      return false;
+    }
+    visiting.add(stepId);
+    const dependenciesRetained = previous.dependencies.every((dependencyId) => retain(dependencyId));
+    visiting.delete(stepId);
+    if (!dependenciesRetained) {
+      rejected.add(stepId);
+      return false;
+    }
+    retained.set(stepId, previous);
+    return true;
+  };
+
+  for (const stepId of exactCompletedById.keys()) retain(stepId);
+  return retained;
+}
+
+export function normalizePlanStepDefinition(
+  step: PlanStepInput | TaskStep,
+): PlanStepInput {
+  return {
+    id: step.id,
+    title: step.title,
+    objective: step.objective,
+    requirements: [...step.requirements],
+    dependencies: [...step.dependencies],
+    expectedOutputs: [...step.expectedOutputs],
+    allowedWrites: [...step.allowedWrites],
+    forbiddenScope: [...step.forbiddenScope],
+    checks: [...step.checks],
+  };
+}
+
+function samePlanStepDefinition(previous: TaskStep, candidate: PlanStepInput): boolean {
+  return JSON.stringify(normalizePlanStepDefinition(previous)) === JSON.stringify(candidate);
+}

package/src/domain/discovery.ts

@@ -0,0 +1,27 @@
+import type { DiscoveryState } from '../contracts.js';
+
+export interface DiscoveryReadiness {
+  ready: boolean;
+  status: 'needs_discovery' | 'needs_clarification' | 'ready_to_materialize';
+  missing: string[];
+}
+
+export function assessDiscovery(discovery: DiscoveryState): DiscoveryReadiness {
+  const missing: string[] = [];
+  if (!discovery.goal.trim()) missing.push('goal');
+  if (!discovery.outcome?.trim()) missing.push('observable outcome');
+  if (discovery.scope.length === 0) missing.push('scope');
+  if (discovery.acceptance.length === 0) missing.push('acceptance scenario');
+  if (discovery.blockingUnknowns.length > 0) missing.push('resolved blocking unknowns');
+  if (missing.length === 0) return { ready: true, status: 'ready_to_materialize', missing };
+  const hasInitialUnderstanding = Boolean(discovery.goal.trim() && (discovery.outcome || discovery.scope.length > 0));
+  return {
+    ready: false,
+    status: hasInitialUnderstanding ? 'needs_clarification' : 'needs_discovery',
+    missing,
+  };
+}
+
+export function mergeUnique(current: string[], additions: string[]): string[] {
+  return [...new Set([...current, ...additions].map((value) => value.trim()).filter(Boolean))];
+}

package/src/domain/plan-semantics.ts

@@ -0,0 +1,58 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { WorkflowError } from '../errors.js';
+
+const HASH64 = /^[a-f0-9]{64}$/;
+const KNOWLEDGE_LINE = /^- Knowledge map: revision ([1-9]\d*), hash ([a-f0-9]{64})$/gm;
+const KNOWLEDGE_SENTINEL = '- Knowledge map: revision <context>, hash <context>';
+
+export interface NormalizedPlanSemantics {
+  normalized: string;
+  semanticHash: string;
+  binding: { revision: number; hash: string };
+}
+
+export function normalizePlanKnowledgeBinding(content: string, label: string): NormalizedPlanSemantics {
+  const matches = [...content.matchAll(KNOWLEDGE_LINE)];
+  if (matches.length !== 1) {
+    throw new WorkflowError('STATE_CORRUPT', `${label} Plan must contain exactly one canonical Knowledge Map binding line.`, {
+      matchCount: matches.length,
+    });
+  }
+  const match = matches[0]!;
+  const normalized = content.slice(0, match.index) + KNOWLEDGE_SENTINEL + content.slice(match.index! + match[0].length);
+  return {
+    normalized,
+    semanticHash: sha256Hex(normalized),
+    binding: { revision: Number(match[1]), hash: match[2]! },
+  };
+}
+
+export function assertKnowledgeBindingOnlyPlanChange(historical: string, current: string): string {
+  const source = normalizePlanKnowledgeBinding(historical, 'historical');
+  const target = normalizePlanKnowledgeBinding(current, 'current');
+  if (source.normalized !== target.normalized) {
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Corrective recovery permits only the Knowledge Map binding line to change.');
+  }
+  return source.semanticHash;
+}
+
+export function readVerifiedPlanArtifact(taskRoot: string, planHash: string, currentPlanHash: string): string {
+  if (!HASH64.test(planHash)) throw new WorkflowError('STATE_CORRUPT', 'Plan hash is malformed.', { planHash });
+  const file = planHash === currentPlanHash
+    ? path.join(taskRoot, 'plan.md')
+    : path.join(taskRoot, '.versions', `plan.md.${planHash}`);
+  if (!existsSync(file)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Plan artifact required by lifecycle evidence is missing.', { planHash, file });
+  }
+  const content = readFileSync(file, 'utf8');
+  if (sha256Hex(content) !== planHash) {
+    throw new WorkflowError('STATE_CORRUPT', 'Plan artifact content does not match its recorded hash.', { planHash, file });
+  }
+  return content;
+}
+
+function sha256Hex(value: string): string {
+  return createHash('sha256').update(value).digest('hex');
+}

package/src/domain/validation.ts

@@ -0,0 +1,177 @@
+import type {
+  PlanRiskAuditStepClassification,
+  TaskPlanInput,
+  TaskState,
+} from '../contracts.js';
+import { WorkflowError } from '../errors.js';
+
+export function validatePlan(plan: TaskPlanInput): void {
+  const issues: string[] = [];
+  if (!plan.objective.trim()) issues.push('Plan objective is required.');
+  if (plan.requirements.length === 0) issues.push('At least one requirement is required.');
+  if (plan.acceptance.length === 0) issues.push('At least one acceptance scenario is required.');
+  if (plan.steps.length === 0) issues.push('At least one STEP-* is required.');
+  if (!plan.knowledgeImpactReason.trim()) issues.push('knowledgeImpactReason is required.');
+  if (!Number.isInteger(plan.knowledgeMapRevision) || plan.knowledgeMapRevision < 1) {
+    issues.push('knowledgeMapRevision must be a positive integer.');
+  }
+  if (!/^[a-f0-9]{64}$/.test(plan.knowledgeMapHash)) issues.push('knowledgeMapHash must be a SHA-256 hash.');
+  if (plan.knowledgeImpact === 'none' && plan.knowledgeTargets.length > 0) {
+    issues.push('knowledgeImpact none cannot declare knowledgeTargets.');
+  }
+  if (plan.knowledgeImpact !== 'none' && plan.knowledgeTargets.length === 0) {
+    issues.push(`knowledgeImpact ${plan.knowledgeImpact} requires at least one knowledgeTarget.`);
+  }
+  for (const target of plan.knowledgeTargets) {
+    if (!target.reason.trim()) issues.push(`Knowledge target ${target.path} requires a reason.`);
+    if (target.requirementIds.length === 0) issues.push(`Knowledge target ${target.path} requires requirementIds.`);
+  }
+
+  const ids = new Set<string>();
+  for (const step of plan.steps) {
+    if (!/^STEP-[0-9]{3}(?:-[A-Z0-9-]+)?$/.test(step.id)) issues.push(`Invalid Step id: ${step.id}`);
+    if (ids.has(step.id)) issues.push(`Duplicate Step id: ${step.id}`);
+    ids.add(step.id);
+    if (!step.title.trim() || !step.objective.trim()) issues.push(`${step.id} requires title and objective.`);
+    if (step.requirements.length === 0) issues.push(`${step.id} must cover at least one requirement.`);
+    if (step.allowedWrites.length === 0) issues.push(`${step.id} must declare allowedWrites.`);
+    if (step.expectedOutputs.length === 0) issues.push(`${step.id} must declare expectedOutputs.`);
+    if (step.checks.length === 0) issues.push(`${step.id} must declare at least one executable check.`);
+  }
+
+  for (const step of plan.steps) {
+    for (const dependency of step.dependencies) {
+      if (!ids.has(dependency)) issues.push(`${step.id} depends on missing ${dependency}.`);
+      if (dependency === step.id) issues.push(`${step.id} cannot depend on itself.`);
+    }
+  }
+
+  const covered = new Set(plan.steps.flatMap((step) => step.requirements));
+  for (const requirement of plan.requirements) {
+    if (!covered.has(requirement)) issues.push(`Requirement is not covered by any Step: ${requirement}`);
+  }
+
+  const visiting = new Set<string>();
+  const visited = new Set<string>();
+  const byId = new Map(plan.steps.map((step) => [step.id, step]));
+  const visit = (stepId: string): void => {
+    if (visited.has(stepId)) return;
+    if (visiting.has(stepId)) {
+      issues.push(`Step dependency cycle includes ${stepId}.`);
+      return;
+    }
+    visiting.add(stepId);
+    for (const dependency of byId.get(stepId)?.dependencies ?? []) visit(dependency);
+    visiting.delete(stepId);
+    visited.add(stepId);
+  };
+  for (const step of plan.steps) visit(step.id);
+
+  const productionEdges = plan.productionEdges ?? [];
+  if (plan.requiresProductionEdges && productionEdges.length === 0) {
+    issues.push('Plan requiresProductionEdges but declares no explicit production edge.');
+  }
+  if (!plan.requiresProductionEdges && productionEdges.length > 0) {
+    issues.push('Plan declares productionEdges without the explicit requiresProductionEdges boundary.');
+  }
+  const edgeKeys = new Set<string>();
+  for (const edge of productionEdges) {
+    const key = `${edge.ownerStepId}\0${edge.consumerStepId}\0${edge.checkRef}`;
+    if (edgeKeys.has(key)) issues.push(`Duplicate production edge: ${edge.ownerStepId} -> ${edge.consumerStepId}.`);
+    edgeKeys.add(key);
+    const owner = byId.get(edge.ownerStepId);
+    const consumer = byId.get(edge.consumerStepId);
+    if (!owner) issues.push(`Production edge owner is missing: ${edge.ownerStepId}.`);
+    if (!consumer) issues.push(`Production edge consumer is missing: ${edge.consumerStepId}.`);
+    if (owner && consumer && owner.id === consumer.id) issues.push(`Production edge cannot self-reference ${owner.id}.`);
+    if (owner && consumer && !transitiveDependencies(consumer.id, byId).has(owner.id)) {
+      issues.push(`Production edge owner ${owner.id} is not a transitive dependency of consumer ${consumer.id}.`);
+    }
+    if (consumer && !consumer.checks.includes(edge.checkRef)) {
+      issues.push(`Production edge ${edge.ownerStepId} -> ${edge.consumerStepId} names a check not executed by its consumer.`);
+    }
+  }
+
+  if (issues.length > 0) throw new WorkflowError('TRANSITION_BLOCKED', 'Plan is not execution-ready.', { issues });
+}
+
+/**
+ * Derive the narrow beta.13 structural integration obligation from the independent
+ * Plan Risk Audit rather than trusting the planner-owned opt-in flag. This is not
+ * semantic output-to-evidence authority (P02): it only proves that a multi-Step
+ * runtime-composition Plan names an inbound production hand-off and executes its
+ * exact check in the consumer Step.
+ */
+export function validateStructuralProductionEdgeAuthority(
+  task: Pick<TaskState, 'id' | 'steps' | 'productionEdges' | 'requiresProductionEdges'>,
+  classifications: readonly PlanRiskAuditStepClassification[],
+): void {
+  if (task.steps.length < 2) return;
+  const integrationConsumerIds = classifications
+    .filter((classification) => classification.categories.includes('runtime-composition'))
+    .map((classification) => classification.stepId)
+    .sort();
+  if (integrationConsumerIds.length === 0) return;
+
+  const edges = task.productionEdges ?? [];
+  const byId = new Map(task.steps.map((step) => [step.id, step]));
+  const missingConsumerEdgeIds = integrationConsumerIds.filter((consumerStepId) =>
+    !edges.some((edge) => edge.consumerStepId === consumerStepId));
+  const blockingGuardIds = [
+    ...(task.requiresProductionEdges === true ? [] : ['task.production-edge.explicit-boundary']),
+    ...(edges.length > 0 ? [] : ['task.production-edge.non-empty']),
+    ...(missingConsumerEdgeIds.length > 0 ? ['task.production-edge.runtime-consumer-covered'] : []),
+  ];
+  for (const edge of edges) {
+    const consumer = byId.get(edge.consumerStepId);
+    const owner = byId.get(edge.ownerStepId);
+    if (!consumer || !owner || !transitiveDependencies(consumer.id, byId).has(owner.id)
+      || !consumer.checks.includes(edge.checkRef)) {
+      blockingGuardIds.push('task.production-edge.executable-predecessor-binding');
+      break;
+    }
+  }
+  if (blockingGuardIds.length === 0) return;
+  throw new WorkflowError(
+    'TRANSITION_BLOCKED',
+    `Runtime-composition authority for Task ${task.id} requires explicit production-edge coverage.`,
+    {
+      diagnosticCode: 'STRUCTURAL_PRODUCTION_EDGE_REQUIRED',
+      triggerAuthority: 'plan-risk-audit.runtime-composition',
+      integrationConsumerStepIds: integrationConsumerIds,
+      missingConsumerEdgeIds,
+      blockingGuardIds: [...new Set(blockingGuardIds)],
+      semanticAuthorityClaimed: false,
+      requiredAction: 'Declare requiresProductionEdges=true and bind each runtime-composition consumer to a transitive owner and one exact consumer check.',
+    },
+  );
+}
+
+function transitiveDependencies(
+  stepId: string,
+  byId: ReadonlyMap<string, TaskPlanInput['steps'][number]>,
+): Set<string> {
+  const result = new Set<string>();
+  const visit = (candidateId: string): void => {
+    for (const dependency of byId.get(candidateId)?.dependencies ?? []) {
+      if (result.has(dependency)) continue;
+      result.add(dependency);
+      visit(dependency);
+    }
+  };
+  visit(stepId);
+  return result;
+}
+
+export function pathAllowed(file: string, patterns: string[]): boolean {
+  const normalized = file.replaceAll('\\', '/').replace(/^\.\//, '');
+  return patterns.some((pattern) => {
+    const candidate = pattern.replaceAll('\\', '/').replace(/^\.\//, '');
+    if (candidate.endsWith('/**')) return normalized === candidate.slice(0, -3) || normalized.startsWith(candidate.slice(0, -2));
+    if (candidate.endsWith('/*')) {
+      const prefix = candidate.slice(0, -1);
+      return normalized.startsWith(prefix) && !normalized.slice(prefix.length).includes('/');
+    }
+    return normalized === candidate;
+  });
+}

package/src/errors.ts

@@ -0,0 +1,23 @@
+export type WorkflowErrorCode =
+  | 'INVALID_ARGUMENT'
+  | 'NOT_FOUND'
+  | 'STATE_CONFLICT'
+  | 'STATE_CORRUPT'
+  | 'LOCKED'
+  | 'LOCK_TOKEN_INVALID'
+  | 'TASK_RECOVERY_REQUIRED'
+  | 'TRANSITION_BLOCKED'
+  | 'GIT_PRECONDITION_FAILED'
+  | 'COMMAND_FAILED';
+
+export class WorkflowError extends Error {
+  readonly code: WorkflowErrorCode;
+  readonly details: Record<string, unknown>;
+
+  constructor(code: WorkflowErrorCode, message: string, details: Record<string, unknown> = {}) {
+    super(message);
+    this.name = 'WorkflowError';
+    this.code = code;
+    this.details = details;
+  }
+}

package/src/fs-utils.ts

@@ -0,0 +1,61 @@
+import {
+  chmodSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { WorkflowError } from './errors.js';
+
+export function ensureDirectory(directory: string): void {
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  if (lstatSync(directory).isSymbolicLink()) {
+    throw new WorkflowError('STATE_CORRUPT', `State directory must not be a symlink: ${directory}`);
+  }
+}
+
+export function readJson<T>(file: string): T {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8')) as T;
+  } catch (error) {
+    throw new WorkflowError('STATE_CORRUPT', `Cannot read JSON state: ${file}`, {
+      cause: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
+export function writeJsonAtomic(file: string, value: unknown): void {
+  const directory = path.dirname(file);
+  ensureDirectory(directory);
+  if (existsSync(file) && lstatSync(file).isSymbolicLink()) {
+    throw new WorkflowError('STATE_CORRUPT', `Refusing to replace state symlink: ${file}`);
+  }
+  const temporary = path.join(directory, `.${path.basename(file)}.${randomUUID()}.tmp`);
+  try {
+    writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    chmodSync(temporary, 0o600);
+    renameSync(temporary, file);
+  } finally {
+    rmSync(temporary, { force: true });
+  }
+}
+
+export function writeTextAtomic(file: string, content: string): void {
+  const directory = path.dirname(file);
+  ensureDirectory(directory);
+  const temporary = path.join(directory, `.${path.basename(file)}.${randomUUID()}.tmp`);
+  try {
+    writeFileSync(temporary, content.endsWith('\n') ? content : `${content}\n`, {
+      encoding: 'utf8',
+      mode: 0o600,
+    });
+    renameSync(temporary, file);
+  } finally {
+    rmSync(temporary, { force: true });
+  }
+}

package/src/gateway-handshake.ts

@@ -0,0 +1,103 @@
+import { PROTOCOL_VERSION, STATE_SCHEMA_VERSION } from './contracts.js';
+import { PACKAGE_NAME, PACKAGE_VERSION } from './version.js';
+
+export interface GatewayHandshake {
+  packageName: typeof PACKAGE_NAME;
+  packageVersion: typeof PACKAGE_VERSION;
+  protocolVersion: typeof PROTOCOL_VERSION;
+  stateSchemaVersion: typeof STATE_SCHEMA_VERSION;
+  capabilities: string[];
+}
+
+export function gatewayHandshake(): GatewayHandshake {
+  return {
+    packageName: PACKAGE_NAME,
+    packageVersion: PACKAGE_VERSION,
+    protocolVersion: PROTOCOL_VERSION,
+    stateSchemaVersion: STATE_SCHEMA_VERSION,
+    capabilities: workflowCapabilities(),
+  };
+}
+
+export function workflowCapabilities(): string[] {
+  return [
+    'project-memory-v1',
+    'graph-binding-v1',
+    'local-state-v1',
+    'milestone-lifecycle-v1',
+    'milestone-human-final-gate-v1',
+    'delegated-approval-v1',
+    'task-knowledge-rebind-v1',
+    'task-context-refresh-v1',
+    'corrective-plan-audit-v1',
+    'safe-update-preflight-v1',
+    'pending-strict-review-dependency-bridge-v1',
+    'bounded-dependency-provenance-recovery-v1',
+    'task-local-dependency-provenance-recovery-v1',
+    'root-cause-corrective-replan-dirty-carryover-v1',
+    'legacy-stop-escalate-override-v1',
+    'stop-override-context-rebind-v1',
+    'stop-override-context-rebind-chain-v1',
+    'stop-override-post-audit-dependency-revision-v1',
+    'retained-reviewed-history-recovery-v1',
+    'historical-step-provenance-recovery-v1',
+    'milestone-progress-projection-v1',
+    'bounded-plan-integrity-recovery-v1',
+    'check-support-scope-augmentation-v1',
+    'coherent-plan-integrity-update-source-v1',
+    'historical-check-support-scope-adoption-v1',
+    'historical-check-support-dirty-carryover-v1',
+    'downstream-proof-predecessor-recovery-v1',
+    'downstream-proof-replan-recovery-v1',
+    'active-downstream-proof-dependency-recovery-v1',
+    'downstream-proof-replan-update-recovery-v1',
+    'plan-integrity-update-recovery-v1',
+    'task-mechanical-feasibility-v1',
+    'task-human-gate-lease-release-v1',
+    'strict-reviewer-v1',
+    'legacy-snapshot-v1',
+    'plan-risk-audit-sidecar-v1',
+    'step-strict-review-sidecar-v1',
+    'step-remediation-circuit-breaker-sidecar-v1',
+    'milestone-scope-change-sidecar-v1',
+    'milestone-membership-integrity-v1',
+    'milestone-task-dependency-dag-v1',
+    'milestone-initial-plan-transaction-v1',
+    'task-c1-handoff-sidecar-v1',
+    'semantic-plan-risk-audit-v2',
+    'guarded-remediation-continuation-v1',
+    'cause-bound-rolling-refinement-v1',
+    'failed-step-continuation-transaction-v1',
+    'host-safe-credential-reference-v1',
+    'structural-production-edge-contract-v1',
+    'structural-production-edge-authority-v1',
+    'observed-route-matrix-v2',
+    'compact-status-v1',
+    'reviewer-runtime-preflight-v1',
+    'explicit-review-mode-v1',
+    'app-owned-operational-preflight-v1',
+    'milestone-reverse-membership-integrity-v1',
+    'task-c1-handoff-bundle-v2',
+    'alpha6-adoption-posture-v1',
+    'alpha6-strict-review-rescue-v1',
+    'milestone-initial-assembly-v1',
+    'milestone-initial-assembly-navigation-v2',
+    'milestone-autonomy-contract-v1',
+    'milestone-autonomy-content-refresh-v1',
+    'milestone-autonomous-membership-evolution-v1',
+    'audited-remediation-topology-v1',
+    'audited-remediation-dependency-knowledge-refresh-v1',
+    'corrective-derived-task-authority-v1',
+    'task-c1-derived-worker-actor-v1',
+    'guarded-corrective-auditor-routing-v1',
+    'corrective-decision-context-recovery-v1',
+    'remediation-mode-recovery-v1',
+    'plan-proof-obligations-v1',
+    'structural-task-replacement-disabled-v1',
+    'project-composite-transaction-journal-v1',
+    'corrective-yield-journal-v1',
+    'corrective-replan-journal-v1',
+    'corrective-replan-human-gate-v1',
+    'corrective-replan-protocol-v2',
+  ];
+}