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

package/src/memory.ts

@@ -0,0 +1,273 @@
+import { createHash } from 'node:crypto';
+import { lstatSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import {
+  STATE_SCHEMA_VERSION,
+  type KnowledgeCategory,
+  type KnowledgeConflict,
+  type KnowledgeGap,
+  type KnowledgeSelection,
+  type KnowledgeSource,
+  type ProjectKnowledgeMap,
+  type WorkflowRole,
+} from './contracts.js';
+import { WorkflowError } from './errors.js';
+
+export const KNOWLEDGE_CATEGORIES: readonly KnowledgeCategory[] = [
+  'agent-guidance',
+  'onboarding',
+  'architecture',
+  'decisions',
+  'commands',
+  'ownership',
+  'testing',
+  'operations',
+  'domain',
+];
+
+const ignoredDirectories = new Set([
+  '.git',
+  '.worktrees',
+  '.test-dist',
+  'node_modules',
+  'dist',
+  'build',
+  'coverage',
+]);
+
+export function scanProjectKnowledge(
+  repositoryRoot: string,
+  projectId: string,
+  now: Date = new Date(),
+): ProjectKnowledgeMap {
+  const root = realpathSync(repositoryRoot);
+  const timestamp = now.toISOString();
+  const entries: KnowledgeSource[] = [];
+  walk(root, root, (absolute, relative) => {
+    const category = classifyKnowledgePath(relative);
+    if (!category) return;
+    const scope = normalizeScope(path.posix.dirname(relative));
+    entries.push({
+      id: sourceId(category, relative),
+      category,
+      path: relative,
+      scope,
+      authority: 'supporting',
+      contentHash: hashFile(absolute),
+      discoveredBy: 'repository-scan',
+      lastVerifiedAt: timestamp,
+    });
+  });
+  entries.sort(compareSources);
+  const gaps = knowledgeGaps(entries);
+  return {
+    schemaVersion: STATE_SCHEMA_VERSION,
+    revision: 0,
+    id: 'PROJECT-KNOWLEDGE-MAP',
+    projectId,
+    createdAt: timestamp,
+    updatedAt: timestamp,
+    kind: 'knowledge-map',
+    status: 'awaiting_approval',
+    entries,
+    gaps,
+    conflicts: [],
+    approval: null,
+  };
+}
+
+export function applyKnowledgeSelections(
+  map: ProjectKnowledgeMap,
+  selections: KnowledgeSelection[],
+  actor: string,
+  now: Date = new Date(),
+): ProjectKnowledgeMap {
+  const byId = new Map(map.entries.map((entry) => [entry.id, entry]));
+  const selectedIds = new Set<string>();
+  for (const selection of selections) {
+    if (selectedIds.has(selection.sourceId)) {
+      throw new WorkflowError('INVALID_ARGUMENT', `Duplicate knowledge selection: ${selection.sourceId}`);
+    }
+    selectedIds.add(selection.sourceId);
+    if (!byId.has(selection.sourceId)) {
+      throw new WorkflowError('INVALID_ARGUMENT', `Unknown knowledge source: ${selection.sourceId}`);
+    }
+  }
+  const authority = new Map(selections.map((selection) => [selection.sourceId, selection.authority]));
+  const entries = map.entries
+    .map((entry) => ({ ...entry, authority: authority.get(entry.id) ?? entry.authority }))
+    .sort(compareSources);
+  const conflicts = knowledgeConflicts(entries);
+  const candidate: ProjectKnowledgeMap = {
+    ...map,
+    entries,
+    gaps: knowledgeGaps(entries),
+    conflicts,
+    approval: null,
+    status: conflicts.length > 0 ? 'conflicted' : 'awaiting_approval',
+  };
+  if (conflicts.length > 0) return candidate;
+  const mapHash = hashKnowledgeMap(candidate);
+  return {
+    ...candidate,
+    status: 'active',
+    approval: {
+      mapHash,
+      actor: actor.trim() || 'user',
+      approvedAt: now.toISOString(),
+    },
+  };
+}
+
+export function reconcileKnowledgeMap(
+  current: ProjectKnowledgeMap,
+  scanned: ProjectKnowledgeMap,
+): ProjectKnowledgeMap {
+  const previous = new Map(current.entries.map((entry) => [`${entry.category}\0${entry.path}\0${entry.scope}`, entry]));
+  const entries = scanned.entries.map((entry) => {
+    const existing = previous.get(`${entry.category}\0${entry.path}\0${entry.scope}`);
+    return existing ? { ...entry, authority: existing.authority } : entry;
+  });
+  const conflicts = knowledgeConflicts(entries);
+  const candidate = {
+    ...scanned,
+    createdAt: current.createdAt,
+    entries: entries.sort(compareSources),
+    gaps: knowledgeGaps(entries),
+    conflicts,
+    status: conflicts.length > 0 ? 'conflicted' as const : 'awaiting_approval' as const,
+  };
+  if (current.status !== 'active' || !current.approval) return candidate;
+  return hashKnowledgeMap(candidate) === current.approval.mapHash
+    ? { ...candidate, status: 'active', approval: current.approval }
+    : { ...candidate, status: conflicts.length > 0 ? 'conflicted' : 'stale', approval: null };
+}
+
+export function inspectKnowledgeMap(
+  current: ProjectKnowledgeMap,
+  scanned: ProjectKnowledgeMap,
+): ProjectKnowledgeMap {
+  const reconciled = reconcileKnowledgeMap(current, scanned);
+  return { ...reconciled, revision: current.revision, updatedAt: current.updatedAt };
+}
+
+export function hashKnowledgeMap(map: Pick<ProjectKnowledgeMap, 'projectId' | 'entries' | 'gaps' | 'conflicts'>): string {
+  const stable = {
+    projectId: map.projectId,
+    entries: [...map.entries].sort(compareSources).map(({ lastVerifiedAt: _verified, ...entry }) => entry),
+    gaps: [...map.gaps].sort(compareGaps),
+    conflicts: [...map.conflicts].sort(compareConflicts),
+  };
+  return createHash('sha256').update(JSON.stringify(stable)).digest('hex');
+}
+
+export function selectKnowledgeSources(
+  map: ProjectKnowledgeMap,
+  role: WorkflowRole,
+  targetPaths: string[] = [],
+): string[] {
+  const targets = new Set(targetPaths.map(normalizeRelativePath));
+  const roleCategories: Record<WorkflowRole, Set<KnowledgeCategory>> = {
+    'scope-lead': new Set(KNOWLEDGE_CATEGORIES),
+    'technical-planner': new Set(['agent-guidance', 'onboarding', 'architecture', 'decisions', 'commands', 'ownership', 'testing', 'domain']),
+    'delivery-coordinator': new Set(['agent-guidance', 'commands', 'ownership', 'testing', 'operations']),
+    worker: new Set(['agent-guidance', 'commands', 'testing']),
+    'independent-reviewer': new Set(KNOWLEDGE_CATEGORIES),
+  };
+  return map.entries
+    .filter((entry) => entry.authority === 'canonical' || targets.has(entry.path))
+    .filter((entry) => roleCategories[role].has(entry.category) || targets.has(entry.path))
+    .map((entry) => entry.path)
+    .sort();
+}
+
+export function normalizeRelativePath(value: string): string {
+  const normalized = value.replaceAll('\\', '/').replace(/^\.\//, '');
+  if (!normalized || normalized === '.' || path.posix.isAbsolute(normalized)) {
+    throw new WorkflowError('INVALID_ARGUMENT', `Knowledge path must be repository-relative: ${value}`);
+  }
+  const clean = path.posix.normalize(normalized);
+  if (clean === '..' || clean.startsWith('../')) {
+    throw new WorkflowError('INVALID_ARGUMENT', `Knowledge path escapes repository root: ${value}`);
+  }
+  return clean;
+}
+
+function walk(root: string, directory: string, visit: (absolute: string, relative: string) => void): void {
+  const entries = readdirSync(directory, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name));
+  for (const entry of entries) {
+    if (entry.isDirectory() && ignoredDirectories.has(entry.name)) continue;
+    const absolute = path.join(directory, entry.name);
+    if (entry.isSymbolicLink()) continue;
+    if (entry.isDirectory()) {
+      walk(root, absolute, visit);
+      continue;
+    }
+    if (!entry.isFile() || !lstatSync(absolute).isFile()) continue;
+    const relative = path.relative(root, absolute).replaceAll(path.sep, '/');
+    visit(absolute, normalizeRelativePath(relative));
+  }
+}
+
+function classifyKnowledgePath(relative: string): KnowledgeCategory | null {
+  const lower = relative.toLowerCase();
+  const base = path.posix.basename(lower);
+  if (base === 'agents.md') return 'agent-guidance';
+  if (/^readme(?:\.[a-z0-9_-]+)?$/.test(base)) return 'onboarding';
+  if (base === 'codeowners' || base === 'owners') return 'ownership';
+  if (base === 'package.json' || base === 'makefile' || base === 'justfile' || /^taskfile(?:\..+)?$/.test(base)) return 'commands';
+  if (/(^|\/)(adr|adrs|decisions)(\/|$)/.test(lower) || /^adr[-_].+\.md$/.test(base)) return 'decisions';
+  if (/(^|\/)(architecture|architectures)(\/|$)/.test(lower) || /architecture.*\.md$/.test(base)) return 'architecture';
+  if (/(^|\/)(domain|domains)(\/|$)/.test(lower)) return 'domain';
+  if (/(^|\/)(operations|runbooks?)(\/|$)/.test(lower) || /^dockerfile/.test(base) || /^compose.*\.ya?ml$/.test(base)) return 'operations';
+  if (/(^|\/)(\.github\/workflows|tests?|testing)(\/|$)/.test(lower) || /^(vitest|jest|playwright|cypress|pytest|test).*(json|js|ts|mjs|cjs|toml|ini)$/.test(base)) return 'testing';
+  return null;
+}
+
+function knowledgeGaps(entries: KnowledgeSource[]): KnowledgeGap[] {
+  const present = new Set(entries.map((entry) => entry.category));
+  return KNOWLEDGE_CATEGORIES
+    .filter((category) => !present.has(category))
+    .map((category) => ({ category, scope: '.', reason: `No ${category} source was discovered.` }));
+}
+
+function knowledgeConflicts(entries: KnowledgeSource[]): KnowledgeConflict[] {
+  const groups = new Map<string, KnowledgeSource[]>();
+  for (const entry of entries.filter((candidate) => candidate.authority === 'canonical')) {
+    const key = `${entry.category}\0${entry.scope}`;
+    groups.set(key, [...(groups.get(key) ?? []), entry]);
+  }
+  return [...groups.values()]
+    .filter((group) => group.length > 1)
+    .map((group) => ({
+      category: group[0]!.category,
+      scope: group[0]!.scope,
+      sourceIds: group.map((entry) => entry.id).sort(),
+      reason: 'More than one canonical source exists for the same category and scope.',
+    }))
+    .sort(compareConflicts);
+}
+
+function sourceId(category: KnowledgeCategory, relative: string): string {
+  return `KS-${createHash('sha256').update(`${category}\0${relative}`).digest('hex').slice(0, 16)}`;
+}
+
+function hashFile(file: string): string {
+  return createHash('sha256').update(readFileSync(file)).digest('hex');
+}
+
+function normalizeScope(value: string): string {
+  return value === '.' || value === '' ? '.' : normalizeRelativePath(value);
+}
+
+function compareSources(left: KnowledgeSource, right: KnowledgeSource): number {
+  return `${left.category}\0${left.scope}\0${left.path}`.localeCompare(`${right.category}\0${right.scope}\0${right.path}`);
+}
+
+function compareGaps(left: KnowledgeGap, right: KnowledgeGap): number {
+  return `${left.category}\0${left.scope}`.localeCompare(`${right.category}\0${right.scope}`);
+}
+
+function compareConflicts(left: KnowledgeConflict, right: KnowledgeConflict): number {
+  return `${left.category}\0${left.scope}`.localeCompare(`${right.category}\0${right.scope}`);
+}

package/src/migration.ts

@@ -0,0 +1,161 @@
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { gzipSync } from 'node:zlib';
+import { STATE_SCHEMA_VERSION } from './contracts.js';
+import { WorkflowError } from './errors.js';
+import { ensureDirectory } from './fs-utils.js';
+import { resolveRepositoryIdentity, runGit } from './repository.js';
+import { FileStateStore } from './state/store.js';
+
+const LEGACY_CANDIDATES = ['.tasks', '.increments', '.codex-workflow.json', '.codex-workflow.lock.json'];
+
+interface SnapshotFile {
+  path: string;
+  mode: number;
+  size: number;
+  sha256: string;
+  contentBase64: string;
+}
+
+interface LegacySnapshot {
+  format: 'codex-workflow-v1-snapshot';
+  version: 1;
+  projectId: string;
+  repositoryRootFingerprint: string;
+  git: {
+    head: string;
+    branch: string | null;
+    statusPorcelainV1: string[];
+    refs: string[];
+  };
+  files: SnapshotFile[];
+}
+
+export interface MigrationReport {
+  dryRun: boolean;
+  snapshotRequested: boolean;
+  projectId: string;
+  stateSchemaVersion: number;
+  entities: { discoveries: number; tasks: number; milestones: number };
+  actions: string[];
+  legacy: {
+    detected: boolean;
+    paths: string[];
+    automaticMappingSupported: false;
+  };
+  snapshot: null | {
+    format: LegacySnapshot['format'];
+    contentHash: string;
+    file: string;
+    fileCount: number;
+  };
+}
+
+export function migrateState(
+  repository: string,
+  store: FileStateStore,
+  dryRun: boolean,
+  snapshotRequested = !dryRun,
+): MigrationReport {
+  if (dryRun && snapshotRequested) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Choose either migration dry-run or snapshot creation.');
+  }
+  const identity = resolveRepositoryIdentity(repository);
+  store.registerProject(identity);
+  const legacyPaths = LEGACY_CANDIDATES.filter((candidate) => existsSync(path.join(identity.repositoryRoot, candidate)));
+  const report: MigrationReport = {
+    dryRun,
+    snapshotRequested,
+    projectId: identity.projectId,
+    stateSchemaVersion: STATE_SCHEMA_VERSION,
+    entities: {
+      discoveries: store.listDiscoveries(identity.projectId).length,
+      tasks: store.listTasks(identity.projectId).length,
+      milestones: store.listMilestones(identity.projectId).length,
+    },
+    actions: [],
+    legacy: {
+      detected: legacyPaths.length > 0,
+      paths: legacyPaths,
+      automaticMappingSupported: false,
+    },
+    snapshot: null,
+  };
+  if (!snapshotRequested) return report;
+  if (legacyPaths.length === 0) {
+    throw new WorkflowError('NOT_FOUND', 'No legacy V1 workflow state was detected.');
+  }
+  const snapshot = buildSnapshot(identity.repositoryRoot, identity.projectId, legacyPaths);
+  const bytes = gzipSync(Buffer.from(`${JSON.stringify(snapshot)}\n`, 'utf8'), { level: 9 });
+  const contentHash = createHash('sha256').update(bytes).digest('hex');
+  const directory = store.snapshotRoot(identity.projectId);
+  const file = path.join(directory, `${contentHash}.snapshot.json.gz`);
+  ensureDirectory(directory);
+  if (!existsSync(file)) writeFileSync(file, bytes, { mode: 0o600, flag: 'wx' });
+  report.actions.push('Created immutable legacy snapshot; no V1 state was imported or modified.');
+  report.snapshot = {
+    format: snapshot.format,
+    contentHash,
+    file,
+    fileCount: snapshot.files.length,
+  };
+  return report;
+}
+
+function buildSnapshot(repositoryRoot: string, projectId: string, legacyPaths: string[]): LegacySnapshot {
+  const files = legacyPaths.flatMap((relative) => collectFiles(repositoryRoot, relative));
+  files.sort((left, right) => left.path.localeCompare(right.path));
+  const branch = safeGit(repositoryRoot, ['symbolic-ref', '--short', 'HEAD']) || null;
+  return {
+    format: 'codex-workflow-v1-snapshot',
+    version: 1,
+    projectId,
+    repositoryRootFingerprint: createHash('sha256').update(path.resolve(repositoryRoot)).digest('hex'),
+    git: {
+      head: runGit(repositoryRoot, ['rev-parse', 'HEAD']),
+      branch,
+      statusPorcelainV1: safeGit(repositoryRoot, ['status', '--porcelain=v1', '--untracked-files=all'])
+        .split('\n')
+        .filter(Boolean)
+        .sort(),
+      refs: safeGit(repositoryRoot, ['for-each-ref', '--format=%(refname) %(objectname)'])
+        .split('\n')
+        .filter(Boolean)
+        .sort(),
+    },
+    files,
+  };
+}
+
+function collectFiles(repositoryRoot: string, relative: string): SnapshotFile[] {
+  const absolute = path.join(repositoryRoot, relative);
+  const stat = lstatSync(absolute);
+  if (stat.isSymbolicLink()) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Legacy snapshot rejects symbolic link: ${relative}`);
+  }
+  if (stat.isDirectory()) {
+    return readdirSync(absolute)
+      .sort()
+      .flatMap((name) => collectFiles(repositoryRoot, path.join(relative, name)));
+  }
+  if (!stat.isFile()) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Legacy snapshot supports regular files only: ${relative}`);
+  }
+  const content = readFileSync(absolute);
+  return [{
+    path: relative.split(path.sep).join('/'),
+    mode: stat.mode & 0o777,
+    size: content.length,
+    sha256: createHash('sha256').update(content).digest('hex'),
+    contentBase64: content.toString('base64'),
+  }];
+}
+
+function safeGit(repositoryRoot: string, args: string[]): string {
+  try {
+    return runGit(repositoryRoot, args);
+  } catch {
+    return '';
+  }
+}

package/src/navigation-actions.ts

@@ -0,0 +1,70 @@
+import { isCliCommand, type CliCommand } from './cli-actions.js';
+
+type ObjectValue = Record<string, unknown>;
+const object = (value: unknown): ObjectValue =>
+  value !== null && typeof value === 'object' && !Array.isArray(value) ? value as ObjectValue : {};
+const unblocked = (value: ObjectValue) => value.eligible !== false && value.blocked !== true
+  && value.state !== 'blocked' && (!Array.isArray(value.blockers) || value.blockers.length === 0);
+
+/**
+ * Project explicit current navigation contracts, not authority from status or
+ * diagnostic prose. Core still checks actor, revision, credentials and inputs.
+ * Consumers must pass the actual successful `next` value, not a transcript's
+ * independently declared action list. This is the single action projection for
+ * maintained runners and transcript validation; the CLI registry owns spelling.
+ */
+export function projectNextActions(input: unknown): CliCommand[] {
+  const next = object(input);
+  const actions = new Set<CliCommand>();
+  const add = (action: unknown) => {
+    if (typeof action === 'string' && action !== next.blockedAction && isCliCommand(action)) actions.add(action);
+  };
+  add(next.action);
+  if (Array.isArray(next.allowedActions)) next.allowedActions.forEach(add);
+
+  for (const [location, primary] of [['strictStepReview', 'task step-review'], ['strictTaskReview', 'task review-launch']] as const) {
+    const review = object(next[location]);
+    const sealed = object(review.externalSealedReview);
+    if (next.action === primary && review.reviewRequired === true && unblocked(review) && unblocked(sealed)) {
+      add(sealed.packetCommand);
+      add(sealed.recordCommand);
+    }
+  }
+  const recovery = object(next.writerCredentialRecovery);
+  if (unblocked(recovery) && typeof recovery.requiredActor === 'string' && recovery.requiredActor.trim()) add(recovery.action);
+
+  const eligibleOption = (candidate: unknown) => {
+    const option = object(candidate);
+    if (unblocked(option) && (option.eligible === true || option.state === 'eligible')) {
+      add(option.action);
+      add(option.command);
+      if (Array.isArray(option.commands)) option.commands.forEach(add);
+    }
+  };
+  eligibleOption(next.preExecutionReplanOption);
+  eligibleOption(next.correctiveDecisionOption);
+  if (Array.isArray(next.options)) next.options.forEach(eligibleOption);
+
+  // Core emits this closed branch only after assessMilestoneInitialAssembly is
+  // eligible. Individual entries intentionally have no redundant eligible flag.
+  const assembly = object(next.milestoneInitialAssembly);
+  if (unblocked(assembly) && Array.isArray(assembly.options)) {
+    for (const candidate of assembly.options) {
+      const option = object(candidate);
+      if (!unblocked(option)) continue;
+      add(option.action);
+      add(option.command);
+      if (Array.isArray(option.commands)) option.commands.forEach(add);
+    }
+  }
+  // These options are emitted only at the Milestone authorization boundary.
+  // Listing a direct-human command never substitutes for its required consent.
+  if (next.scope === 'milestone' && next.status === 'awaiting_execution_authorization'
+    && Array.isArray(next.milestoneAuthorizationOptions)) {
+    for (const candidate of next.milestoneAuthorizationOptions) {
+      const option = object(candidate);
+      if (unblocked(option)) add(option.action);
+    }
+  }
+  return [...actions];
+}