@moretea-labs/forge 1.5.0-rc.1

package/src/runtime/control-plane/governance/authorization.ts

@@ -0,0 +1,195 @@
+import { randomUUID } from 'crypto';
+import { existsSync, mkdirSync } from 'fs';
+import { join, relative, resolve } from 'path';
+import { repositoryControllerRoot } from '../../../cli/repositories/controller-home';
+import { readJsonFile, sanitizeFileComponent, writeJsonAtomic } from '../../shared/json-files';
+import type { AccessMode } from './access-policy';
+
+export type AuthorizationRiskClass =
+  | 'readonly'
+  | 'local_repo_write'
+  | 'workspace_write'
+  | 'local_command'
+  | 'dependency_change'
+  | 'local_git'
+  | 'remote_write'
+  | 'destructive'
+  | 'secret_access'
+  | 'outside_repository';
+
+export type AuthorizationDecision =
+  | { decision: 'allow'; source: 'policy' | 'full_access' | 'goal_delegation' | 'gpt_risk_delegate' | 'user_confirmation'; reason: string }
+  | { decision: 'user_confirmation_required'; approvalRequestId: string; humanSummary: string; consequences: string[]; continuation: string }
+  | { decision: 'deny'; reason: string };
+
+export interface GoalDelegation {
+  schemaVersion: 1;
+  sessionId: string;
+  repositoryId: string;
+  workId?: string;
+  goalId?: string;
+  allowedRiskClasses: AuthorizationRiskClass[];
+  deniedRiskClasses: AuthorizationRiskClass[];
+  permissionSnapshotVersion: number;
+  source: 'goal_delegation' | 'gpt_risk_delegate';
+  createdAt: string;
+  expiresAt?: string;
+  version: number;
+}
+
+export interface AuthorizationRequestRecord {
+  schemaVersion: 1;
+  approvalRequestId: string;
+  repositoryId: string;
+  sessionId?: string;
+  principalId?: string;
+  workId?: string;
+  goalId?: string;
+  command?: string | string[];
+  approvalToken?: string;
+  risk: AuthorizationRiskClass;
+  permissionSnapshotVersion: number;
+  humanSummary: string;
+  consequences: string[];
+  continuation: string;
+  status: 'pending' | 'resolved' | 'invalidated';
+  createdAt: string;
+  resolvedAt?: string;
+  invalidatedReason?: string;
+}
+
+export interface AuthorizationContext {
+  controllerHome?: string;
+  accessMode: AccessMode;
+  risk: AuthorizationRiskClass;
+  repositoryId: string;
+  currentRepositoryId?: string;
+  workId?: string;
+  boundWorkId?: string;
+  goalId?: string;
+  boundGoalId?: string;
+  sessionId?: string;
+  principalId?: string;
+  permissionSnapshotVersion: number;
+  delegation?: GoalDelegation;
+  worktreePath?: string;
+  cwd?: string;
+  command?: string | string[];
+  approvalRequestId?: string;
+  approvalToken?: string;
+  approvedByUser?: boolean;
+}
+
+function requestRoot(controllerHome: string, repoId: string): string {
+  const root = join(repositoryControllerRoot(controllerHome, repoId), 'controller', 'approval-requests');
+  mkdirSync(root, { recursive: true, mode: 0o700 });
+  return root;
+}
+
+function requestPath(controllerHome: string, repoId: string, requestId: string): string {
+  return join(requestRoot(controllerHome, repoId), `${sanitizeFileComponent(requestId)}.json`);
+}
+
+function scopeMatches(context: AuthorizationContext): boolean {
+  if (context.currentRepositoryId && context.repositoryId !== context.currentRepositoryId) return false;
+  if (context.workId && context.boundWorkId && context.workId !== context.boundWorkId) return false;
+  if (context.goalId && context.boundGoalId && context.goalId !== context.boundGoalId) return false;
+  if (context.worktreePath && context.cwd) {
+    const cwd = resolve(context.worktreePath, context.cwd);
+    const rel = relative(resolve(context.worktreePath), cwd);
+    if (rel === '..' || rel.startsWith('../') || rel.startsWith('..\\')) return false;
+  }
+  return true;
+}
+
+function delegationMatches(context: AuthorizationContext): boolean {
+  const delegation = context.delegation;
+  if (!delegation || delegation.sessionId !== context.sessionId || delegation.repositoryId !== context.repositoryId) return false;
+  if (delegation.workId && delegation.workId !== context.workId) return false;
+  if (delegation.goalId && delegation.goalId !== context.goalId && delegation.goalId !== context.boundGoalId) return false;
+  if (delegation.permissionSnapshotVersion !== context.permissionSnapshotVersion) return false;
+  if (delegation.expiresAt && Date.parse(delegation.expiresAt) <= Date.now()) return false;
+  if (delegation.deniedRiskClasses.includes(context.risk) || !delegation.allowedRiskClasses.includes(context.risk)) return false;
+  return scopeMatches(context);
+}
+
+function requestDecision(context: AuthorizationContext, reason: string): AuthorizationDecision {
+  if (!context.controllerHome) {
+    return { decision: 'deny', reason: `${reason} Controller Home is unavailable for a resumable approval request.` };
+  }
+  const approvalRequestId = `apr_${randomUUID().replace(/-/g, '')}`;
+  const record: AuthorizationRequestRecord = {
+    schemaVersion: 1,
+    approvalRequestId,
+    repositoryId: context.repositoryId,
+    ...(context.sessionId ? { sessionId: context.sessionId } : {}),
+    ...(context.principalId ? { principalId: context.principalId } : {}),
+    ...(context.workId ? { workId: context.workId } : {}),
+    ...(context.goalId ? { goalId: context.goalId } : {}),
+    ...(context.command ? { command: context.command } : {}),
+    ...(context.approvalToken ? { approvalToken: context.approvalToken } : {}),
+    risk: context.risk,
+    permissionSnapshotVersion: context.permissionSnapshotVersion,
+    humanSummary: reason,
+    consequences: [
+      `Operation risk class: ${context.risk}`,
+      `Repository: ${context.repositoryId}`,
+      ...(context.workId ? [`Work handle: ${context.workId}`] : []),
+    ],
+    continuation: context.command
+      ? `After confirming approvalRequestId=${approvalRequestId}, retry the same command with the returned approval request; changed commands require a new approval.`
+      : `After confirming approvalRequestId=${approvalRequestId}, retry the original operation in this session.`,
+    status: 'pending',
+    createdAt: new Date().toISOString(),
+  };
+  writeJsonAtomic(requestPath(context.controllerHome, context.repositoryId, approvalRequestId), record);
+  return { decision: 'user_confirmation_required', approvalRequestId, humanSummary: record.humanSummary, consequences: record.consequences, continuation: record.continuation };
+}
+
+export function decideAuthorization(context: AuthorizationContext): AuthorizationDecision {
+  if (context.risk === 'secret_access') return { decision: 'deny', reason: 'Credential, keychain, token, and raw secret access is always denied.' };
+  if (!scopeMatches(context)) return requestDecision(context, 'The operation is outside the active repository, worktree, or Goal scope.');
+  if (['outside_repository', 'destructive'].includes(context.risk)) {
+    return context.approvedByUser ? { decision: 'allow', source: 'user_confirmation', reason: 'The user explicitly confirmed the scoped catastrophic operation.' } : requestDecision(context, `Explicit user confirmation is required for ${context.risk}.`);
+  }
+  if (delegationMatches(context)) {
+    return { decision: 'allow', source: context.delegation?.source ?? 'gpt_risk_delegate', reason: 'The operation is within the current Goal and repository scope.' };
+  }
+  return { decision: 'allow', source: 'policy', reason: 'Normal scoped operations follow the host AI permission model; Forge only gates catastrophic effects.' };
+}
+
+export function createGoalDelegation(input: Omit<GoalDelegation, 'schemaVersion' | 'createdAt' | 'version'> & { expiresAt?: string }): GoalDelegation {
+  return { schemaVersion: 1, ...input, createdAt: new Date().toISOString(), version: 1 };
+}
+
+export function readAuthorizationRequest(controllerHome: string, repositoryId: string, approvalRequestId: string): AuthorizationRequestRecord {
+  const path = requestPath(controllerHome, repositoryId, approvalRequestId);
+  if (!existsSync(path)) throw new Error(`APPROVAL_REQUEST_NOT_FOUND: ${approvalRequestId}`);
+  const request = readJsonFile<AuthorizationRequestRecord>(path);
+  if (request.repositoryId !== repositoryId || request.approvalRequestId !== approvalRequestId) throw new Error('APPROVAL_REQUEST_IDENTITY_MISMATCH');
+  return request;
+}
+
+export function resolveAuthorizationRequest(input: { controllerHome: string; repositoryId: string; approvalRequestId: string; sessionId?: string; principalId?: string; workId?: string; permissionSnapshotVersion: number; confirm: boolean }): AuthorizationRequestRecord {
+  const request = readAuthorizationRequest(input.controllerHome, input.repositoryId, input.approvalRequestId);
+  if (!input.confirm) throw new Error('USER_CONFIRMATION_REQUIRED: confirm_authorization=true is required to resolve the approval request');
+  if (request.status === 'invalidated') throw new Error(`APPROVAL_REQUEST_INVALIDATED: ${request.invalidatedReason ?? 'approval request is stale'}`);
+  if (request.sessionId && request.sessionId !== input.sessionId) throw new Error('APPROVAL_REQUEST_SESSION_MISMATCH');
+  if (request.principalId && request.principalId !== input.principalId) throw new Error('APPROVAL_REQUEST_PRINCIPAL_MISMATCH');
+  if (request.workId && request.workId !== input.workId) throw new Error('APPROVAL_REQUEST_WORK_MISMATCH');
+  if (request.permissionSnapshotVersion !== input.permissionSnapshotVersion) throw new Error('APPROVAL_REQUEST_STALE_PERMISSION');
+  const resolved = { ...request, status: 'resolved' as const, resolvedAt: new Date().toISOString() };
+  writeJsonAtomic(requestPath(input.controllerHome, input.repositoryId, input.approvalRequestId), resolved);
+  return resolved;
+}
+
+export function assertResolvedAuthorization(input: { controllerHome: string; repositoryId: string; approvalRequestId: string; sessionId?: string; principalId?: string; workId?: string; permissionSnapshotVersion: number; command?: string | string[] }): AuthorizationRequestRecord {
+  const request = readAuthorizationRequest(input.controllerHome, input.repositoryId, input.approvalRequestId);
+  if (request.status !== 'resolved') throw new Error('APPROVAL_REQUEST_NOT_RESOLVED: confirm the approval request in the current conversation first');
+  if (request.sessionId && request.sessionId !== input.sessionId) throw new Error('APPROVAL_REQUEST_SESSION_MISMATCH');
+  if (request.principalId && request.principalId !== input.principalId) throw new Error('APPROVAL_REQUEST_PRINCIPAL_MISMATCH');
+  if (request.workId && request.workId !== input.workId) throw new Error('APPROVAL_REQUEST_WORK_MISMATCH');
+  if (request.permissionSnapshotVersion !== input.permissionSnapshotVersion) throw new Error('APPROVAL_REQUEST_STALE_PERMISSION');
+  if (request.command && input.command && JSON.stringify(request.command) !== JSON.stringify(input.command)) throw new Error('APPROVAL_REQUEST_COMMAND_CHANGED: request a new approval for changed parameters');
+  return request;
+}

package/src/runtime/control-plane/governance/external-effects.ts

@@ -0,0 +1,43 @@
+const EXPLICIT_AUTHORIZATION_OPERATIONS = new Set([
+  'publish_issue_to_github',
+  'close_github_issue',
+  'repository_remove',
+  'repository_disable',
+  'repository_command_execute',
+  'configure_github_plugin',
+]);
+
+
+const AUTOMATED_REQUIREMENT_OPERATIONS = new Set([
+  'create_issue',
+  'append_task',
+  'write_prd',
+  'write_prd_from_idea',
+  'write_plan',
+]);
+
+const DANGEROUS_COMMAND_PATTERNS = [
+  /\bgit\s+(?:push|merge|rebase|reset|branch\s+-[dD]|tag\s+-d)\b/i,
+  /\bgh\s+(?:pr\s+(?:merge|close)|issue\s+close|release\s+(?:create|delete))\b/i,
+  /\b(?:npm|pnpm|yarn|bun)\s+(?:publish|unpublish)\b/i,
+  /\b(?:kubectl|helm)\b.*\b(?:apply|delete|upgrade|rollback)\b/i,
+  /\b(?:drop|truncate|delete\s+from)\b/i,
+  /\b(?:deploy|publish)\b/i,
+];
+
+export function operationRequiresHumanAuthorization(operation: string, args: Record<string, unknown> = {}): boolean {
+  if (EXPLICIT_AUTHORIZATION_OPERATIONS.has(operation)) return true;
+  const command = typeof args.command === 'string' ? args.command : '';
+  const gitArgs = Array.isArray(args.args) ? args.args.map(String).join(' ') : '';
+  const text = `${operation} ${command} ${gitArgs}`;
+  return DANGEROUS_COMMAND_PATTERNS.some((pattern) => pattern.test(text));
+}
+
+export function assertAutomatedOperationAllowed(operation: string, args: Record<string, unknown> = {}): void {
+  if (AUTOMATED_REQUIREMENT_OPERATIONS.has(operation)) {
+    throw new Error(`AUTOMATED_REQUIREMENT_REQUIRES_CANDIDATE: ${operation} must first create a candidate finding for human promotion`);
+  }
+  if (operationRequiresHumanAuthorization(operation, args)) {
+    throw new Error(`EXTERNAL_EFFECT_AUTHORIZATION_REQUIRED: ${operation} cannot be executed by a Schedule, Portfolio workflow, or reconciliation loop`);
+  }
+}

package/src/runtime/control-plane/launcher/thin-launcher.ts

@@ -0,0 +1,97 @@
+import { spawn, spawnSync } from 'child_process';
+import {
+  claimControllerSession,
+  getHandoffItem,
+  getWorkContract,
+  releaseControllerSession,
+  type HandoffInboxStoreOptions,
+  type WorkContractStoreOptions,
+} from '../facade';
+import type { ControllerType } from '../facade/types';
+
+export interface ThinLauncherRequest {
+  controllerType: Exclude<ControllerType, 'human'>;
+  executable?: string;
+  args?: string[];
+  workId: string;
+  controllerId: string;
+  sessionId: string;
+  leaseMs?: number;
+  handoffId?: string;
+  cwd: string;
+}
+
+export interface ThinLauncherResult {
+  controllerType: ThinLauncherRequest['controllerType'];
+  controllerId: string;
+  sessionId: string;
+  pid: number | undefined;
+  prompt: string;
+  executable: string;
+}
+
+function resolveLauncherExecutable(request: ThinLauncherRequest): string {
+  const configured = request.executable?.trim();
+  if (configured) return configured;
+  const executable = request.controllerType === 'codex'
+    ? 'codex'
+    : request.controllerType === 'claude'
+      ? 'claude'
+      : '';
+  if (!executable) throw new Error(`LAUNCHER_EXECUTABLE_REQUIRED: ${request.controllerType} requires an external launcher executable`);
+  const probe = spawnSync(executable, ['--version'], {
+    cwd: request.cwd,
+    stdio: 'ignore',
+    timeout: 5_000,
+  });
+  if (probe.error || probe.status !== 0) {
+    throw new Error(`LAUNCHER_EXECUTABLE_UNAVAILABLE: ${executable}`);
+  }
+  return executable;
+}
+
+/**
+ * Starts one external SuperController session. This module deliberately owns
+ * provider process selection and prompt construction; the execution Kernel
+ * receives neither provider-specific arguments nor model output.
+ */
+export function launchSuperController(
+  stores: {
+    work: WorkContractStoreOptions & { controllerHome: string; repoId: string };
+    handoff: HandoffInboxStoreOptions;
+  },
+  request: ThinLauncherRequest,
+): ThinLauncherResult {
+  if (!request.controllerId.trim() || !request.sessionId.trim()) throw new Error('LAUNCHER_CONTROLLER_SESSION_REQUIRED');
+  const executable = resolveLauncherExecutable(request);
+  const work = getWorkContract(stores.work, request.workId);
+  if (!work) throw new Error(`WORK_NOT_FOUND: ${request.workId}`);
+  const session = claimControllerSession(stores.work, {
+    workId: work.workId,
+    controllerId: request.controllerId,
+    controllerType: request.controllerType,
+    sessionId: request.sessionId,
+    leaseMs: request.leaseMs,
+  });
+  const handoff = request.handoffId ? getHandoffItem(stores.handoff, request.handoffId) : undefined;
+  const prompt = [
+    `Work: ${work.workId}`,
+    `Objective: ${work.objective}`,
+    `Acceptance: ${work.acceptanceCriteria.join('; ') || 'none declared'}`,
+    `Current status: ${work.status}`,
+    handoff ? `Handoff: ${handoff.summary}\nNext: ${handoff.recommendedContinuationPrompt ?? handoff.recommendedPrompt}` : '',
+    'Use the repository MCP facade directly. Claim the Work before mutation and create a handoff when control changes.',
+  ].filter(Boolean).join('\n');
+  try {
+    const child = spawn(executable, [...(request.args ?? []), prompt], {
+      cwd: request.cwd,
+      detached: true,
+      stdio: 'ignore',
+    });
+    child.unref();
+    return { controllerType: request.controllerType, controllerId: session.controllerId, sessionId: session.sessionId, pid: child.pid, prompt, executable };
+  } catch (error) {
+    releaseControllerSession(stores.work, work.workId, request.controllerId);
+    throw error;
+  }
+}

package/src/runtime/control-plane/persistence/metadata-payload-policy.ts

@@ -0,0 +1,53 @@
+const FORBIDDEN_FIELD = /(?:^|_)(?:secret|secrets|credential|credentials|password|passwd|access_token|refresh_token|private_key|binary|blob|stdout|stderr|large_log|log_payload)(?:$|_)/i;
+const SECRET_TEXT = /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----|\bgh[pousr]_[A-Za-z0-9]{20,}\b|\bsk-[A-Za-z0-9_-]{20,}\b/;
+const MAX_STRING_BYTES = 64 * 1024;
+const DEFAULT_MAX_PAYLOAD_BYTES = 2 * 1024 * 1024;
+
+function visit(value: unknown, path: string, seen: Set<object>): void {
+  if (value === null || value === undefined || typeof value === 'boolean' || typeof value === 'number') return;
+  if (typeof value === 'string') {
+    if (Buffer.byteLength(value, 'utf8') > MAX_STRING_BYTES) {
+      throw new Error(`CONTROL_PLANE_METADATA_STRING_TOO_LARGE: ${path}`);
+    }
+    if (SECRET_TEXT.test(value)) throw new Error(`CONTROL_PLANE_METADATA_SECRET_REFUSED: ${path}`);
+    return;
+  }
+  if (typeof value === 'bigint' || typeof value === 'function' || typeof value === 'symbol') {
+    throw new Error(`CONTROL_PLANE_METADATA_TYPE_REFUSED: ${path}`);
+  }
+  if (Buffer.isBuffer(value) || ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
+    throw new Error(`CONTROL_PLANE_METADATA_BINARY_REFUSED: ${path}`);
+  }
+  if (typeof value !== 'object') return;
+  if (seen.has(value)) throw new Error(`CONTROL_PLANE_METADATA_CYCLE_REFUSED: ${path}`);
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      value.forEach((entry, index) => visit(entry, `${path}[${index}]`, seen));
+      return;
+    }
+    for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+      if (FORBIDDEN_FIELD.test(key)) throw new Error(`CONTROL_PLANE_METADATA_FIELD_REFUSED: ${path}.${key}`);
+      visit(entry, `${path}.${key}`, seen);
+    }
+  } finally {
+    seen.delete(value);
+  }
+}
+
+/**
+ * Requirement/Plan migration and offline export are metadata-only surfaces.
+ * They must not become an alternate secret store or a transport for logs and
+ * binary payloads.
+ */
+export function assertControlPlaneMetadataPayload(
+  value: unknown,
+  label: string,
+  maxPayloadBytes = DEFAULT_MAX_PAYLOAD_BYTES,
+): void {
+  visit(value, label, new Set());
+  const encoded = JSON.stringify(value);
+  if (Buffer.byteLength(encoded, 'utf8') > maxPayloadBytes) {
+    throw new Error(`CONTROL_PLANE_METADATA_PAYLOAD_TOO_LARGE: ${label}`);
+  }
+}

package/src/runtime/control-plane/persistence/requirement-store.ts

@@ -0,0 +1,241 @@
+import {
+  listControlPlaneRecords,
+  readControlPlaneRecord,
+  readControlPlaneRecordWithinTransaction,
+  withControlPlaneTransaction,
+  writeControlPlaneRecordWithinTransaction,
+  type ControlPlaneRecord,
+  type SqliteDatabase,
+} from './sqlite-store';
+import { isRepositoryCompletionReceipt, type WorkContract } from '../facade/types';
+
+export const REQUIREMENT_STATES = ['planned', 'active', 'waiting_for_user', 'done', 'cancelled'] as const;
+export type RequirementState = (typeof REQUIREMENT_STATES)[number];
+
+export interface Requirement {
+  schemaVersion: 1;
+  requirementId: string;
+  legacyAliases: string[];
+  title: string;
+  outcomeStatement: string;
+  acceptanceCriteria: string[];
+  requiredDeliveryReferences: string[];
+  activePlanId?: string;
+  state: RequirementState;
+  needsAttention: boolean;
+  attentionSummary?: string;
+  revision: number;
+  createdAt: string;
+  updatedAt: string;
+  auditRefs: string[];
+}
+
+export interface RequirementStoreOptions {
+  controllerHome: string;
+  now?: () => string;
+}
+
+export interface CreateRequirementInput {
+  requirementId: string;
+  legacyAliases?: string[];
+  title: string;
+  outcomeStatement: string;
+  acceptanceCriteria?: string[];
+  requiredDeliveryReferences?: string[];
+}
+
+const NAMESPACE = 'requirement';
+const SCOPE = 'controller';
+const SCHEMA_VERSION = 1;
+
+function nowIso(options: RequirementStoreOptions): string {
+  return options.now?.() ?? new Date().toISOString();
+}
+
+function id(value: string): string {
+  const normalized = String(value ?? '').trim();
+  if (!normalized || normalized.includes('/') || normalized.includes('\\')) throw new Error('REQUIREMENT_ID_INVALID');
+  return normalized.slice(0, 160);
+}
+
+function bounded(values: readonly string[] | undefined, limit: number, maxLength = 500): string[] {
+  return (values ?? []).map((value) => String(value).trim()).filter(Boolean).slice(0, limit).map((value) => value.slice(0, maxLength));
+}
+
+function readWithin(database: SqliteDatabase, requirementId: string): ControlPlaneRecord<Requirement> | undefined {
+  return readControlPlaneRecordWithinTransaction(database, NAMESPACE, SCOPE, requirementId);
+}
+
+export function readRequirement(
+  options: RequirementStoreOptions,
+  requirementId: string,
+): ControlPlaneRecord<Requirement> | undefined {
+  return readControlPlaneRecord<Requirement>(options.controllerHome, NAMESPACE, SCOPE, id(requirementId));
+}
+
+export function listRequirements(
+  options: RequirementStoreOptions,
+  limit = 500,
+): ControlPlaneRecord<Requirement>[] {
+  return listControlPlaneRecords<Requirement>(options.controllerHome, {
+    namespace: NAMESPACE,
+    scope: SCOPE,
+    limit,
+  });
+}
+
+export function createRequirement(
+  options: RequirementStoreOptions,
+  input: CreateRequirementInput,
+): Requirement {
+  const requirementId = id(input.requirementId);
+  const at = nowIso(options);
+  const requirement: Requirement = {
+    schemaVersion: 1,
+    requirementId,
+    legacyAliases: bounded(input.legacyAliases, 20, 160),
+    title: String(input.title ?? '').trim().slice(0, 500),
+    outcomeStatement: String(input.outcomeStatement ?? '').trim().slice(0, 2_000),
+    acceptanceCriteria: bounded(input.acceptanceCriteria, 50),
+    requiredDeliveryReferences: bounded(input.requiredDeliveryReferences, 50),
+    state: 'planned',
+    needsAttention: false,
+    revision: 1,
+    createdAt: at,
+    updatedAt: at,
+    auditRefs: [],
+  };
+  if (!requirement.title || !requirement.outcomeStatement) throw new Error('REQUIREMENT_CONTENT_REQUIRED');
+  withControlPlaneTransaction(options.controllerHome, (database) => {
+    if (readWithin(database, requirementId)) throw new Error(`REQUIREMENT_ALREADY_EXISTS: ${requirementId}`);
+    writeControlPlaneRecordWithinTransaction(database, {
+      namespace: NAMESPACE,
+      scope: SCOPE,
+      key: requirementId,
+      schemaVersion: SCHEMA_VERSION,
+      value: requirement,
+      action: 'requirement_created',
+      expectedRevision: null,
+    });
+  });
+  return requirement;
+}
+
+const ALLOWED_TRANSITIONS: Readonly<Record<RequirementState, readonly RequirementState[]>> = {
+  planned: ['planned', 'active', 'waiting_for_user', 'cancelled'],
+  active: ['active', 'waiting_for_user', 'done', 'cancelled'],
+  waiting_for_user: ['waiting_for_user', 'planned', 'active', 'cancelled'],
+  done: ['done', 'cancelled'],
+  cancelled: ['cancelled'],
+};
+
+export function updateRequirement(
+  options: RequirementStoreOptions,
+  input: {
+    requirementId: string;
+    action: string;
+    mutate: (current: Requirement) => Requirement;
+  },
+): Requirement {
+  const requirementId = id(input.requirementId);
+  return withControlPlaneTransaction(options.controllerHome, (database) => {
+    const current = readWithin(database, requirementId);
+    if (!current) throw new Error(`REQUIREMENT_NOT_FOUND: ${requirementId}`);
+    const next = input.mutate(current.value);
+    if (!ALLOWED_TRANSITIONS[current.value.state].includes(next.state)) {
+      throw new Error(`REQUIREMENT_STATE_TRANSITION_INVALID: ${current.value.state} -> ${next.state}`);
+    }
+    if (next.requirementId !== requirementId) throw new Error('REQUIREMENT_ID_IMMUTABLE');
+    const updated: Requirement = {
+      ...next,
+      schemaVersion: 1,
+      revision: current.value.revision + 1,
+      updatedAt: nowIso(options),
+    };
+    return writeControlPlaneRecordWithinTransaction(database, {
+      namespace: NAMESPACE,
+      scope: SCOPE,
+      key: requirementId,
+      schemaVersion: SCHEMA_VERSION,
+      value: updated,
+      action: input.action,
+      expectedRevision: current.revision,
+    }).value;
+  });
+}
+
+export function setRequirementPlan(
+  options: RequirementStoreOptions,
+  input: { requirementId: string; planId: string; action?: string },
+): Requirement {
+  return updateRequirement(options, {
+    requirementId: input.requirementId,
+    action: input.action ?? 'requirement_active_plan_bound',
+    mutate: (current) => ({ ...current, activePlanId: id(input.planId) }),
+  });
+}
+
+export interface RequirementCompletionInput {
+  requirementId: string;
+  work: Pick<WorkContract,
+    | 'workId'
+    | 'requirementId'
+    | 'status'
+    | 'phase'
+    | 'evidenceState'
+    | 'completionOutcome'
+    | 'completionReceipt'
+  >;
+}
+
+/**
+ * Complete a Requirement only from the Work-owned completion record.
+ *
+ * This intentionally short-circuits an already audited `done` Requirement
+ * before inspecting historical execution facts. A cancelled Run, missing
+ * legacy Task receipt, or stale Work projection therefore cannot reopen or
+ * rewrite a completed user outcome.
+ */
+export function completeRequirementFromWork(
+  options: RequirementStoreOptions,
+  input: RequirementCompletionInput,
+): Requirement {
+  const requirementId = id(input.requirementId);
+  const current = readRequirement(options, requirementId);
+  if (!current) throw new Error(`REQUIREMENT_NOT_FOUND: ${requirementId}`);
+  if (current.value.state === 'done') return current.value;
+  if (current.value.state === 'cancelled') throw new Error('REQUIREMENT_CANCELLED');
+
+  const work = input.work;
+  if (work.requirementId !== requirementId) throw new Error('REQUIREMENT_WORK_IDENTITY_MISMATCH');
+  if (work.status !== 'completed') throw new Error('REQUIREMENT_WORK_NOT_COMPLETED');
+  if (work.phase !== 'cleanup') throw new Error('REQUIREMENT_WORK_CLEANUP_REQUIRED');
+  if (work.evidenceState !== 'valid') throw new Error('REQUIREMENT_WORK_EVIDENCE_NOT_VALID');
+  if (!work.completionOutcome) throw new Error('REQUIREMENT_WORK_COMPLETION_OUTCOME_REQUIRED');
+  if (work.completionOutcome === 'superseded') throw new Error('REQUIREMENT_WORK_OUTCOME_NOT_COMPLETED');
+
+  const receipt = work.completionReceipt;
+  if (!receipt) throw new Error('REQUIREMENT_WORK_COMPLETION_RECEIPT_REQUIRED');
+  if (receipt.workId !== work.workId) throw new Error('REQUIREMENT_WORK_RECEIPT_IDENTITY_MISMATCH');
+  if (!isRepositoryCompletionReceipt(receipt)) throw new Error('REQUIREMENT_WORK_REPOSITORY_RECEIPT_REQUIRED');
+  if (receipt.delivery.kind === 'superseded' || receipt.delivery.status !== 'integrated' || !receipt.delivery.reachable) throw new Error('REQUIREMENT_WORK_DELIVERY_NOT_PROVEN');
+  if (!['complete', 'maintenance_warning'].includes(receipt.cleanup.status) || receipt.cleanup.blockers.length > 0) throw new Error('REQUIREMENT_WORK_CLEANUP_NOT_PROVEN');
+
+  return updateRequirement(options, {
+    requirementId,
+    action: 'requirement_completed_from_work_receipt',
+    mutate: (latest) => {
+      // Preserve a concurrent audited completion; stale execution evidence is
+      // never allowed to move a terminal Requirement backwards.
+      if (latest.state === 'done') return latest;
+      if (latest.state === 'cancelled') throw new Error('REQUIREMENT_CANCELLED');
+      return {
+        ...latest,
+        state: 'done',
+        needsAttention: false,
+        attentionSummary: undefined,
+        auditRefs: Array.from(new Set([...latest.auditRefs, receipt.receiptId])).slice(-50),
+      };
+    },
+  });
+}