@moretea-labs/forge 1.7.2 → 1.8.1

package/src/runtime/control-plane/facade/plan-contract-store.ts

@@ -1,10 +1,12 @@
+import { createHash } from 'crypto';
 import { mkdirSync } from 'fs';
 import { join } from 'path';
-import { repositoryControllerRoot } from '../../../cli/repositories/controller-home';
+import { scopedOperationRoot } from '../../../cli/repositories/controller-home';
 import { withControllerLock } from '../../../cli/repositories/locks';
 import { readJsonFile, sanitizeFileComponent, writeJsonAtomic } from '../../shared/json-files';
 import {
   normalizePlanScopeKey,
+  isPlanExtensionPredecessor,
   resolvePlanAdmission,
   withPlanAdmissionLock,
   withPlanAdmissionLockAsync,
@@ -13,34 +15,43 @@ import {
 } from './semantic-admission';
 import {
   listControlPlaneRecords,
+  readControlPlaneRecord,
   readControlPlaneRecordWithinTransaction,
   withControlPlaneTransaction,
   writeControlPlaneRecordWithinTransaction,
 } from '../persistence/sqlite-store';
 import { readRequirement } from '../persistence/requirement-store';
+import type { ScopeRef } from '../../../../packages/kernel/identity/api/index';
 import {
   isTerminalPlanContractStatus,
   type EvidenceRef,
   type PlanContract,
   type PlanContractStatus,
   type PlanContractStore,
+  type PlanObligationDisposition,
+  type PlanRevisionDraft,
+  type PlanRevisionRecord,
   type PlanStep,
-  type WorkContract,
 } from './types';
 
 export interface PlanContractStoreLocation {
   controllerHome?: string;
   repoId?: string;
+  /** Portable semantic scope key (for example the ForgeInstance semantic scope). Takes precedence over repoId. */
+  scopeKey?: string;
   root?: string;
 }
 
 export interface PlanContractStoreOptions extends PlanContractStoreLocation {
   now?: () => string;
+  /** Prove that one delivered Git revision is contained in a later Plan source. Missing/failed proof is fail-closed. */
+  revisionContains?: (ancestorRevision: string, descendantRevision: string) => boolean;
 }
 
 export interface CreatePlanContractInput {
   planId: string;
-  repoId: string;
+  /** Optional node-local placement provenance; absent for a ForgeInstance-scoped Plan. */
+  repoId?: string;
   requirementId?: string;
   scopeKey: string;
   sourceRevision: string;
@@ -53,6 +64,7 @@ export interface CreatePlanContractInput {
   integrationStrategy?: string;
   steps: Array<Omit<PlanStep, 'status' | 'evidenceRefs'> & Partial<Pick<PlanStep, 'status' | 'evidenceRefs'>>>;
   evidenceRefs?: EvidenceRef[];
+  obligationDispositions?: PlanObligationDisposition[];
 }
 
 export interface AdmitPlanContractInput extends CreatePlanContractInput {
@@ -69,7 +81,9 @@ export type AdmitPlanContractResult = PlanAdmissionResolution;
 
 export interface PlanContractSummary {
   planId: string;
-  repoId: string;
+  revision: number;
+  /** Node-local placement provenance; absent for a ForgeInstance-scoped Plan. */
+  repoId?: string;
   requirementId?: string;
   scopeKey: string;
   sourceRevision: string;
@@ -88,10 +102,150 @@ function bounded(values: readonly string[] | undefined, limit: number, maxLength
   return (values ?? []).map((value) => String(value).trim()).filter(Boolean).slice(0, limit).map((value) => value.slice(0, maxLength));
 }
 
+function normalizePlanSemanticItems(items: readonly { id: string; objective: string; dependencies?: string[] }[] | undefined) {
+  const normalized = (items ?? []).slice(0, 100).map((item) => ({
+    id: String(item.id).trim().slice(0, 200),
+    objective: String(item.objective).trim().slice(0, 2_000),
+    dependencies: [...new Set((item.dependencies ?? []).map(String).map((value) => value.trim()).filter(Boolean))].slice(0, 100),
+  }));
+  if (normalized.some((item) => !item.id || !item.objective) || new Set(normalized.map((item) => item.id)).size !== normalized.length) {
+    throw new Error('PLAN_SEMANTIC_ITEMS_INVALID');
+  }
+  return normalized;
+}
+
 function normalizeScopeKey(value: string): string {
   return normalizePlanScopeKey(value) || 'unknown';
 }
 
+export function currentPlanRevision(plan: PlanContract): number {
+  const revision = Number(plan.revision);
+  return Number.isInteger(revision) && revision > 0 ? revision : 1;
+}
+
+export function currentPlanSemanticRevision(plan: PlanContract): number {
+  const revision = Number(plan.semanticRevision);
+  return Number.isInteger(revision) && revision > 0 ? revision : 1;
+}
+
+export interface PlanSemanticView {
+  planId: string;
+  revision: number;
+  semanticScope: ScopeRef;
+  requirementId?: string;
+  /** One-way lineage fact: this Plan is historical and its obligations continue in the named successor. */
+  supersededBy?: string;
+  requirementBasisRevision?: number;
+  sourceBasisRevision: string;
+  goal: string;
+  nonGoals: string[];
+  assumptions: string[];
+  resolvedDecisions: string[];
+  stopConditions: string[];
+  replanConditions: string[];
+  integrationStrategy?: string;
+  items: Array<{ id: string; objective: string; dependencies: string[] }>;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface PlanSemanticRevisionRecord extends PlanSemanticView {
+  schemaVersion: 1;
+  recordedAt: string;
+}
+
+export interface RevisePlanSemanticInput {
+  expectedRevision: number;
+  /** Optional one-way successor relation. Once set it cannot be cleared or changed. */
+  supersededBy?: string;
+  requirementBasisRevision?: number;
+  sourceBasisRevision?: string;
+  goal?: string;
+  nonGoals?: string[];
+  assumptions?: string[];
+  resolvedDecisions?: string[];
+  stopConditions?: string[];
+  replanConditions?: string[];
+  integrationStrategy?: string | null;
+  items?: Array<{ id: string; objective: string; dependencies?: string[] }>;
+}
+
+export interface CreatePlanSemanticInput {
+  planId: string;
+  /** Optional node-local placement provenance; absent for a ForgeInstance-scoped Plan. */
+  repoId?: string;
+  requirementId?: string;
+  requirementBasisRevision?: number;
+  scopeKey?: string;
+  sourceBasisRevision?: string;
+  goal: string;
+  nonGoals?: string[];
+  assumptions?: string[];
+  resolvedDecisions?: string[];
+  stopConditions?: string[];
+  replanConditions?: string[];
+  integrationStrategy?: string;
+  items?: Array<{ id: string; objective: string; dependencies?: string[] }>;
+}
+
+function legacyPlanSemanticContext(plan: PlanContract) {
+  return {
+    requirementBasisRevision: undefined,
+    sourceBasisRevision: plan.sourceRevision,
+    goal: plan.goal,
+    nonGoals: [...plan.nonGoals],
+    assumptions: [...plan.assumptions],
+    resolvedDecisions: [...plan.resolvedDecisions],
+    stopConditions: [...plan.stopConditions],
+    replanConditions: [...plan.replanConditions],
+    integrationStrategy: plan.integrationStrategy,
+    items: plan.steps.map((step) => ({ id: step.id, objective: step.objective, dependencies: [...step.dependencies] })),
+  };
+}
+
+export function planSemanticView(plan: PlanContract): PlanSemanticView {
+  const semantic = plan.semanticContext ?? legacyPlanSemanticContext(plan);
+  const semanticScope: ScopeRef = plan.requirementId?.trim()
+    ? { schemaVersion: 1, kind: 'requirement', id: plan.requirementId.trim() }
+    : { schemaVersion: 1, kind: 'plan', id: plan.planId };
+  return {
+    planId: plan.planId,
+    revision: currentPlanSemanticRevision(plan),
+    semanticScope,
+    requirementId: plan.requirementId,
+    ...(plan.supersededBy?.trim() ? { supersededBy: plan.supersededBy.trim() } : {}),
+    requirementBasisRevision: semantic.requirementBasisRevision,
+    sourceBasisRevision: semantic.sourceBasisRevision,
+    goal: semantic.goal,
+    nonGoals: [...semantic.nonGoals],
+    assumptions: [...semantic.assumptions],
+    resolvedDecisions: [...semantic.resolvedDecisions],
+    stopConditions: [...semantic.stopConditions],
+    replanConditions: [...semantic.replanConditions],
+    integrationStrategy: semantic.integrationStrategy,
+    items: semantic.items.map((item) => ({ id: item.id, objective: item.objective, dependencies: [...item.dependencies] })),
+    createdAt: plan.createdAt,
+    updatedAt: plan.semanticUpdatedAt ?? plan.createdAt,
+  };
+}
+
+interface PlanRevisionRecordStore {
+  schemaVersion: 1;
+  updatedAt: string;
+  revisions: PlanRevisionRecord[];
+}
+
+interface PlanSemanticRevisionStore {
+  schemaVersion: 1;
+  updatedAt: string;
+  revisions: PlanSemanticRevisionRecord[];
+}
+
+function planRevisionRecordKey(planId: string, revision: number): string {
+  return `${sanitizeFileComponent(planId)}:r${revision}`;
+}
+
+
 function normalizeStep(step: CreatePlanContractInput['steps'][number]): PlanStep {
   return {
     id: sanitizeFileComponent(step.id).slice(0, 120),
@@ -111,6 +265,60 @@ function normalizeStep(step: CreatePlanContractInput['steps'][number]): PlanStep
   };
 }
 
+function normalizeObligationDisposition(value: PlanObligationDisposition): PlanObligationDisposition {
+  const disposition = value.disposition;
+  if (!['keep', 'change', 'defer', 'drop'].includes(disposition)) throw new Error(`PLAN_OBLIGATION_DISPOSITION_INVALID: ${String(disposition)}`);
+  return {
+    predecessorPlanId: sanitizeFileComponent(value.predecessorPlanId).slice(0, 160),
+    obligationId: String(value.obligationId ?? '').trim().slice(0, 160),
+    disposition,
+    successorRefs: bounded(value.successorRefs, 20, 240),
+    ...(value.rationale?.trim() ? { rationale: value.rationale.trim().slice(0, 1_000) } : {}),
+  };
+}
+
+export interface PlanObligation {
+  obligationId: string;
+  predecessorPlanId: string;
+  kind: 'step_objective' | 'step_acceptance' | 'non_goal' | 'resolved_decision' | 'stop_condition' | 'replan_condition';
+  sourceRef: string;
+  summary: string;
+}
+
+function planObligationId(planId: string, kind: PlanObligation['kind'], sourceRef: string, summary: string): string {
+  const digest = createHash('sha256').update(JSON.stringify({ planId, kind, sourceRef, summary })).digest('hex').slice(0, 24);
+  return `obl_${digest}`;
+}
+
+function listPlanObligations(plan: PlanContract, mode: 'unresolved' | 'completed_steps'): PlanObligation[] {
+  const out: PlanObligation[] = [];
+  const add = (kind: PlanObligation['kind'], sourceRef: string, summary: string) => {
+    const normalized = summary.trim();
+    if (!normalized) return;
+    out.push({ obligationId: planObligationId(plan.planId, kind, sourceRef, normalized), predecessorPlanId: plan.planId, kind, sourceRef, summary: normalized });
+  };
+  for (const step of plan.steps) {
+    if (mode === 'unresolved' && step.status === 'completed') continue;
+    if (mode === 'completed_steps' && step.status !== 'completed') continue;
+    add('step_objective', `step:${step.id}`, step.objective);
+    step.acceptanceCriteria.forEach((criterion, index) => add('step_acceptance', `step:${step.id}:acceptance:${index}`, criterion));
+  }
+  if (mode === 'unresolved') {
+    plan.nonGoals.forEach((value, index) => add('non_goal', `non_goal:${index}`, value));
+    plan.resolvedDecisions.forEach((value, index) => add('resolved_decision', `resolved_decision:${index}`, value));
+    plan.stopConditions.forEach((value, index) => add('stop_condition', `stop_condition:${index}`, value));
+    plan.replanConditions.forEach((value, index) => add('replan_condition', `replan_condition:${index}`, value));
+  }
+  return out;
+}
+
+export function listUnresolvedPlanObligations(plan: PlanContract): PlanObligation[] {
+  return listPlanObligations(plan, 'unresolved');
+}
+
+
+
+
 function updatePlanContract(
   options: PlanContractStoreOptions,
   planId: string,
@@ -126,21 +334,24 @@ function updatePlanContract(
     writePlanContractStore(options, { schemaVersion: 1, updatedAt: next.updatedAt, contracts });
     return next;
   };
-  if (!options.controllerHome || !options.repoId) return apply();
+  if (!options.controllerHome || !planContractStoreScopeKey(options)) return apply();
   return withControllerLock(
     options.controllerHome,
-    { scope: 'task', repoId: options.repoId, taskId: `plan-${sanitizeFileComponent(planId)}` },
+    { scope: 'task', repoId: requirePlanContractStoreScopeKey(options), taskId: `plan-${sanitizeFileComponent(planId)}` },
     'plan-contract-store',
     apply,
     15_000,
   );
 }
 
+
 function assertRequirementReference(options: PlanContractStoreOptions, requirementId: string | undefined): void {
   const normalized = requirementId?.trim();
   if (!normalized || !options.controllerHome) return;
-  if (!readRequirement({ controllerHome: options.controllerHome, now: options.now }, normalized)) {
-    throw new Error(`PLAN_REQUIREMENT_NOT_FOUND: ${normalized}`);
+  const requirement = readRequirement({ controllerHome: options.controllerHome, now: options.now }, normalized)?.value;
+  if (!requirement) throw new Error(`PLAN_REQUIREMENT_NOT_FOUND: ${normalized}`);
+  if (requirement.state === 'done' || requirement.state === 'cancelled') {
+    throw new Error(`PLAN_REQUIREMENT_TERMINAL: ${normalized}:${requirement.state}`);
   }
 }
 
@@ -149,10 +360,10 @@ export function planContractRoot(location: PlanContractStoreLocation): string {
     mkdirSync(location.root, { recursive: true });
     return location.root;
   }
-  if (!location.controllerHome || !location.repoId) {
-    throw new Error('plan contract store requires either root or controllerHome + repoId');
+  if (!location.controllerHome || !planContractStoreScopeKey(location)) {
+    throw new Error('plan contract store requires either root or controllerHome + repoId/scopeKey');
   }
-  const root = join(repositoryControllerRoot(location.controllerHome, location.repoId), 'plan-contracts');
+  const root = join(scopedOperationRoot(location.controllerHome, requirePlanContractStoreScopeKey(location)), 'plan-contracts');
   mkdirSync(root, { recursive: true });
   return root;
 }
@@ -161,11 +372,151 @@ export function planContractStorePath(location: PlanContractStoreLocation): stri
   return join(planContractRoot(location), 'index.json');
 }
 
+
+
+
+
+export function planRevisionStorePath(location: PlanContractStoreLocation): string {
+  return join(planContractRoot(location), 'revisions.json');
+}
+
+function planSemanticRevisionStorePath(location: PlanContractStoreLocation): string {
+  return join(planContractRoot(location), 'semantic-revisions.json');
+}
+
+export function listPlanRevisionRecords(
+  options: PlanContractStoreOptions,
+  planId?: string,
+): PlanRevisionRecord[] {
+  const normalizedPlanId = planId ? sanitizeFileComponent(planId) : undefined;
+  if (!sqliteBacked(options)) {
+    const store = readJsonFile<PlanRevisionRecordStore>(planRevisionStorePath(options), { schemaVersion: 1, updatedAt: nowIso(options), revisions: [] });
+    return store.revisions
+      .filter((record) => !normalizedPlanId || record.planId === normalizedPlanId)
+      .sort((left, right) => right.revision - left.revision);
+  }
+  return listControlPlaneRecords<PlanRevisionRecord>(options.controllerHome, {
+    namespace: 'plan_revision', scope: requirePlanContractStoreScopeKey(options), limit: 5_000,
+  }).map((record) => record.value)
+    .filter((record) => !normalizedPlanId || record.planId === normalizedPlanId)
+    .sort((left, right) => right.revision - left.revision);
+}
+
+function appendJsonPlanRevisionRecord(options: PlanContractStoreOptions, record: PlanRevisionRecord): void {
+  const path = planRevisionStorePath(options);
+  const store = readJsonFile<PlanRevisionRecordStore>(path, { schemaVersion: 1, updatedAt: record.recordedAt, revisions: [] });
+  if (store.revisions.some((existing) => existing.planId === record.planId && existing.revision === record.revision)) {
+    throw new Error(`PLAN_REVISION_ALREADY_EXISTS: ${record.planId}:r${record.revision}`);
+  }
+  writeJsonAtomic(path, { schemaVersion: 1, updatedAt: record.recordedAt, revisions: [record, ...store.revisions] });
+}
+
+/** Exact historical lookup; revision-list limits are not version-existence gates. */
+export function getPlanSemanticRevisionRecord(
+  options: PlanContractStoreOptions,
+  planId: string,
+  revision: number,
+): PlanSemanticRevisionRecord | undefined {
+  if (!Number.isInteger(revision) || revision < 1) return undefined;
+  const normalizedPlanId = sanitizeFileComponent(planId);
+  const record = sqliteBacked(options)
+    ? readControlPlaneRecord<PlanSemanticRevisionRecord>(
+      options.controllerHome, 'plan_semantic_revision', requirePlanContractStoreScopeKey(options),
+      planRevisionRecordKey(normalizedPlanId, revision),
+    )?.value
+    : readJsonFile<PlanSemanticRevisionStore>(
+      planSemanticRevisionStorePath(options), { schemaVersion: 1, updatedAt: nowIso(options), revisions: [] },
+    ).revisions.find((entry) => entry.planId === normalizedPlanId && entry.revision === revision);
+  return record ? {
+    ...record,
+    semanticScope: record.semanticScope ?? (record.requirementId
+      ? { schemaVersion: 1, kind: 'requirement', id: record.requirementId }
+      : { schemaVersion: 1, kind: 'plan', id: record.planId }),
+  } : undefined;
+}
+
+export function listPlanSemanticRevisionRecords(options: PlanContractStoreOptions, planId?: string): PlanSemanticRevisionRecord[] {
+  const normalizedPlanId = planId ? sanitizeFileComponent(planId) : undefined;
+  if (!sqliteBacked(options)) {
+    const store = readJsonFile<PlanSemanticRevisionStore>(planSemanticRevisionStorePath(options), { schemaVersion: 1, updatedAt: nowIso(options), revisions: [] });
+    return store.revisions.filter((record) => !normalizedPlanId || record.planId === normalizedPlanId)
+      .map((record) => ({
+        ...record,
+        semanticScope: record.semanticScope ?? (record.requirementId
+          ? { schemaVersion: 1, kind: 'requirement', id: record.requirementId }
+          : { schemaVersion: 1, kind: 'plan', id: record.planId }),
+      } as PlanSemanticRevisionRecord))
+      .sort((left, right) => right.revision - left.revision);
+  }
+  return listControlPlaneRecords<PlanSemanticRevisionRecord>(options.controllerHome, {
+    namespace: 'plan_semantic_revision', scope: requirePlanContractStoreScopeKey(options), limit: 5_000,
+  }).map((record) => record.value)
+    .filter((record) => !normalizedPlanId || record.planId === normalizedPlanId)
+    .map((record) => ({
+      ...record,
+      semanticScope: record.semanticScope ?? (record.requirementId
+        ? { schemaVersion: 1, kind: 'requirement', id: record.requirementId }
+        : { schemaVersion: 1, kind: 'plan', id: record.planId }),
+    } as PlanSemanticRevisionRecord))
+    .sort((left, right) => right.revision - left.revision);
+}
+
+function appendJsonPlanSemanticRevisionRecord(options: PlanContractStoreOptions, record: PlanSemanticRevisionRecord): void {
+  const path = planSemanticRevisionStorePath(options);
+  const store = readJsonFile<PlanSemanticRevisionStore>(path, { schemaVersion: 1, updatedAt: record.recordedAt, revisions: [] });
+  if (store.revisions.some((existing) => existing.planId === record.planId && existing.revision === record.revision)) return;
+  writeJsonAtomic(path, { schemaVersion: 1, updatedAt: record.recordedAt, revisions: [record, ...store.revisions].slice(0, 5_000) });
+}
+function planRevisionRecord(plan: PlanContract, input: { recordedAt: string; reason: string; requestedRevisionLabel?: string }): PlanRevisionRecord {
+  return {
+    schemaVersion: 1, repoId: plan.repoId, planId: plan.planId, revision: currentPlanRevision(plan),
+    requirementId: plan.requirementId, scopeKey: plan.scopeKey, sourceRevision: plan.sourceRevision, goal: plan.goal,
+    nonGoals: [...plan.nonGoals], assumptions: [...plan.assumptions], resolvedDecisions: [...plan.resolvedDecisions],
+    stopConditions: [...plan.stopConditions], replanConditions: [...plan.replanConditions], integrationStrategy: plan.integrationStrategy,
+    status: plan.status, steps: structuredClone(plan.steps), evidenceRefs: structuredClone(plan.evidenceRefs),
+    obligationDispositions: plan.obligationDispositions ? structuredClone(plan.obligationDispositions) : undefined,
+    recordedAt: input.recordedAt, reason: input.reason.slice(0, 1_000), requestedRevisionLabel: input.requestedRevisionLabel,
+  };
+}
+
+function revisionDraftFromCandidate(candidate: PlanContract, input: { requestedRevisionLabel?: string; createdAt: string; updatedAt: string }): PlanRevisionDraft {
+  return {
+    revision: currentPlanRevision(candidate), requestedRevisionLabel: input.requestedRevisionLabel,
+    sourceRevision: candidate.sourceRevision, goal: candidate.goal, nonGoals: [...candidate.nonGoals], assumptions: [...candidate.assumptions],
+    resolvedDecisions: [...candidate.resolvedDecisions], stopConditions: [...candidate.stopConditions], replanConditions: [...candidate.replanConditions],
+    integrationStrategy: candidate.integrationStrategy, steps: structuredClone(candidate.steps),
+    obligationDispositions: candidate.obligationDispositions ? structuredClone(candidate.obligationDispositions) : undefined,
+    deliveryCarries: candidate.deliveryCarries ? structuredClone(candidate.deliveryCarries) : undefined,
+    createdAt: input.createdAt, updatedAt: input.updatedAt,
+  };
+}
+
+
+function assertRevisionScopeAuthority(current: PlanContract, allPlans: readonly PlanContract[]): void {
+  const conflicting = allPlans.find((plan) => plan.planId !== current.planId
+    && !isTerminalPlanContractStatus(plan.status) && plan.scopeKey === current.scopeKey);
+  if (conflicting) throw new Error(`PLAN_SCOPE_ALREADY_OWNED: ${current.scopeKey}:${conflicting.planId}`);
+}
+
+
 export function emptyPlanContractStore(updatedAt: string): PlanContractStore {
   return { schemaVersion: 1, updatedAt, contracts: [] };
 }
-function sqliteBacked(options: PlanContractStoreOptions): options is PlanContractStoreOptions & { controllerHome: string; repoId: string } {
-  return Boolean(!options.root && options.controllerHome?.trim() && options.repoId?.trim());
+/** Canonical Plan store scope key: an explicit portable scope, else repository placement. */
+export function planContractStoreScopeKey(options: PlanContractStoreLocation): string | undefined {
+  return options.scopeKey?.trim() || options.repoId?.trim() || undefined;
+}
+
+function requirePlanContractStoreScopeKey(options: PlanContractStoreLocation): string {
+  const key = planContractStoreScopeKey(options);
+  if (!key) throw new Error('PLAN_STORE_SCOPE_REQUIRED: controllerHome requires repoId or scopeKey');
+  return key;
+}
+
+type ControlPlanePlanStoreOptions = PlanContractStoreOptions & { controllerHome: string };
+
+function sqliteBacked(options: PlanContractStoreOptions): options is ControlPlanePlanStoreOptions {
+  return Boolean(!options.root && options.controllerHome?.trim() && planContractStoreScopeKey(options));
 }
 
 export function readPlanContractStore(options: PlanContractStoreOptions): PlanContractStore {
@@ -174,7 +525,7 @@ export function readPlanContractStore(options: PlanContractStoreOptions): PlanCo
   }
   const records = listControlPlaneRecords<PlanContract>(options.controllerHome, {
     namespace: 'plan_contract',
-    scope: options.repoId,
+    scope: requirePlanContractStoreScopeKey(options),
     limit: 5_000,
   });
   if (records.length > 0) {
@@ -191,10 +542,10 @@ export function readPlanContractStore(options: PlanContractStoreOptions): PlanCo
   if (legacy.contracts.length > 0) {
     withControlPlaneTransaction(options.controllerHome, (database) => {
       for (const contract of legacy.contracts) {
-        if (readControlPlaneRecordWithinTransaction<PlanContract>(database, 'plan_contract', options.repoId, contract.planId)) continue;
+        if (readControlPlaneRecordWithinTransaction<PlanContract>(database, 'plan_contract', requirePlanContractStoreScopeKey(options), contract.planId)) continue;
         writeControlPlaneRecordWithinTransaction(database, {
           namespace: 'plan_contract',
-          scope: options.repoId,
+          scope: requirePlanContractStoreScopeKey(options),
           key: contract.planId,
           schemaVersion: 1,
           value: contract,
@@ -217,12 +568,15 @@ function writePlanContractStore(options: PlanContractStoreOptions, store: PlanCo
       const current = readControlPlaneRecordWithinTransaction<PlanContract>(
         database,
         'plan_contract',
-        options.repoId,
+        requirePlanContractStoreScopeKey(options),
         contract.planId,
       );
+      // SQLite is authoritative per Plan row. A sibling Plan appearing in an
+      // aggregate compatibility snapshot is not itself a mutation.
+      if (current && JSON.stringify(current.value) === JSON.stringify(contract)) continue;
       writeControlPlaneRecordWithinTransaction(database, {
         namespace: 'plan_contract',
-        scope: options.repoId,
+        scope: requirePlanContractStoreScopeKey(options),
         key: contract.planId,
         schemaVersion: 1,
         value: contract,
@@ -234,12 +588,14 @@ function writePlanContractStore(options: PlanContractStoreOptions, store: PlanCo
   return store;
 }
 
+
 function buildPlanContract(input: CreatePlanContractInput, at: string): PlanContract {
   const planId = sanitizeFileComponent(input.planId);
   if (!String(input.planId ?? '').trim() || planId === 'unknown') throw new Error('plan_id is required');
   return {
     schemaVersion: 1,
     planId,
+    revision: 1,
     repoId: input.repoId,
     requirementId: input.requirementId?.trim().slice(0, 160) || undefined,
     scopeKey: normalizeScopeKey(input.scopeKey),
@@ -254,6 +610,7 @@ function buildPlanContract(input: CreatePlanContractInput, at: string): PlanCont
     status: 'draft',
     steps: input.steps.slice(0, 30).map(normalizeStep),
     evidenceRefs: (input.evidenceRefs ?? []).slice(0, 20),
+    obligationDispositions: (input.obligationDispositions ?? []).slice(0, 512).map(normalizeObligationDisposition),
     createdAt: at,
     updatedAt: at,
   };
@@ -285,6 +642,14 @@ function draftContentErrors(plan: PlanContract): string[] {
   return [...new Set(errors)];
 }
 
+
+
+
+
+
+
+
+
 function createPlanContractUnlocked(options: PlanContractStoreOptions, input: CreatePlanContractInput): PlanContract {
   assertRequirementReference(options, input.requirementId);
   const at = nowIso(options);
@@ -308,22 +673,39 @@ function replacePlanContractUnlocked(
   const predecessorKey = sanitizeFileComponent(predecessorId);
   const predecessorIndex = store.contracts.findIndex((contract) => contract.planId === predecessorKey);
   if (predecessorIndex < 0) throw new Error(`plan contract not found: ${predecessorKey}`);
-  const predecessor = store.contracts[predecessorIndex]!;
-  if (isTerminalPlanContractStatus(predecessor.status)) throw new Error(`plan contract ${predecessor.planId} is terminal (${predecessor.status})`);
-  const successor = buildPlanContract(input, at);
-  if (successor.planId === predecessor.planId) throw new Error('PLAN_SUCCESSOR_ID_MUST_CHANGE');
-  if (successor.repoId !== predecessor.repoId) throw new Error('PLAN_SUCCESSOR_REPOSITORY_MISMATCH');
-  if (store.contracts.some((existing) => existing.planId === successor.planId)) {
-    throw new Error(`plan contract already exists: ${successor.planId}`);
+  const current = store.contracts[predecessorIndex]!;
+  if (!isPlanExtensionPredecessor(current)) throw new Error(`plan contract ${current.planId} is terminal (${current.status})`);
+
+  // Draft extension keeps the stable Plan identity, but authored content is still
+  // a semantic revision: the previous head is archived and the current head advances.
+  if (current.status === 'draft') {
+    return repairDraftPlanContractUnlocked(options, current.planId, {
+      scopeKey: input.scopeKey, sourceRevision: input.sourceRevision, goal: input.goal, nonGoals: input.nonGoals, assumptions: input.assumptions,
+      resolvedDecisions: input.resolvedDecisions, stopConditions: input.stopConditions, replanConditions: input.replanConditions,
+      integrationStrategy: input.integrationStrategy, steps: input.steps, obligationDispositions: input.obligationDispositions,
+    });
   }
-  const conflictingScope = store.contracts.find((existing, index) => index !== predecessorIndex
-    && !isTerminalPlanContractStatus(existing.status)
-    && existing.scopeKey === successor.scopeKey);
-  if (conflictingScope) throw new Error(`PLAN_SCOPE_ALREADY_OWNED: ${successor.scopeKey}:${conflictingScope.planId}`);
+  if (current.pendingRevision) throw new Error(`PLAN_REVISION_DRAFT_ALREADY_EXISTS: ${current.planId}:r${current.pendingRevision.revision}`);
+  if (input.requirementId?.trim() !== current.requirementId?.trim()) throw new Error('PLAN_REVISION_REQUIREMENT_IDENTITY_MISMATCH');
+  if (normalizeScopeKey(input.scopeKey) !== current.scopeKey) throw new Error(`PLAN_REVISION_SCOPE_IDENTITY_MISMATCH: ${current.scopeKey}`);
+
+  const candidate = {
+    ...buildPlanContract({ ...input, planId: current.planId, repoId: current.repoId, requirementId: current.requirementId, scopeKey: current.scopeKey }, at),
+    revision: currentPlanRevision(current) + 1,
+    supersedes: current.supersedes ? [...current.supersedes] : undefined,
+  };
+  const contentErrors = draftContentErrors(candidate);
+  if (contentErrors.length > 0) throw new Error(`PLAN_REVISION_DRAFT_INVALID: ${contentErrors.join('; ')}`);
+  assertRevisionScopeAuthority(current, store.contracts);
+  const requestedRevisionLabel = sanitizeFileComponent(input.planId);
+  const pendingRevision = revisionDraftFromCandidate(candidate, {
+    requestedRevisionLabel: requestedRevisionLabel !== current.planId ? requestedRevisionLabel : undefined, createdAt: at, updatedAt: at,
+  });
+  const next: PlanContract = { ...current, status: 'replanning', pendingRevision, updatedAt: at };
   const contracts = [...store.contracts];
-  contracts[predecessorIndex] = { ...predecessor, status: 'superseded', supersededBy: successor.planId, updatedAt: at };
-  writePlanContractStore(options, { schemaVersion: 1, updatedAt: at, contracts: [successor, ...contracts] });
-  return successor;
+  contracts[predecessorIndex] = next;
+  writePlanContractStore(options, { schemaVersion: 1, updatedAt: at, contracts });
+  return next;
 }
 
 function repairDraftPlanContractUnlocked(
@@ -336,9 +718,11 @@ function repairDraftPlanContractUnlocked(
   const index = store.contracts.findIndex((contract) => contract.planId === key);
   if (index < 0) throw new Error(`plan contract not found: ${key}`);
   const current = store.contracts[index]!;
-  if (current.status !== 'draft') throw new Error(`PLAN_DRAFT_REPAIR_STATUS_INVALID: ${current.planId}:${current.status}`);
-  if (input.expectedSourceRevision !== undefined && current.sourceRevision !== input.expectedSourceRevision) {
-    throw new Error(`PLAN_DRAFT_REPAIR_STALE_SOURCE: ${current.planId}:expected=${input.expectedSourceRevision}:actual=${current.sourceRevision}`);
+  const pending = current.status === 'replanning' ? current.pendingRevision : undefined;
+  if (current.status !== 'draft' && !pending) throw new Error(`PLAN_DRAFT_REPAIR_STATUS_INVALID: ${current.planId}:${current.status}`);
+  const observedSourceRevision = pending?.sourceRevision ?? current.sourceRevision;
+  if (input.expectedSourceRevision !== undefined && observedSourceRevision !== input.expectedSourceRevision) {
+    throw new Error(`PLAN_DRAFT_REPAIR_STALE_SOURCE: ${current.planId}:expected=${input.expectedSourceRevision}:actual=${observedSourceRevision}`);
   }
   assertRequirementReference(options, current.requirementId);
   const at = nowIso(options);
@@ -349,19 +733,73 @@ function repairDraftPlanContractUnlocked(
     requirementId: current.requirementId,
     evidenceRefs: current.evidenceRefs,
   }, at);
-  const contentErrors = draftContentErrors(candidate);
+  const candidateWithLineage = {
+    ...candidate,
+    ...(current.supersedes?.length ? { supersedes: [...current.supersedes] } : {}),
+  };
+  const contentErrors = draftContentErrors(candidateWithLineage);
   if (contentErrors.length > 0) {
     throw new Error(`PLAN_DRAFT_REPAIR_INVALID: ${contentErrors.join('; ')}`);
   }
+  if (pending) {
+    if (normalizeScopeKey(input.scopeKey) !== current.scopeKey) throw new Error(`PLAN_REVISION_SCOPE_IDENTITY_MISMATCH: ${current.scopeKey}`);
+    assertRevisionScopeAuthority(current, store.contracts);
+    let revisionCandidate: PlanContract = { ...candidateWithLineage, revision: pending.revision, supersedes: current.supersedes ? [...current.supersedes] : undefined };
+    const repairedPending = revisionDraftFromCandidate(revisionCandidate, {
+      requestedRevisionLabel: pending.requestedRevisionLabel, createdAt: pending.createdAt, updatedAt: at,
+    });
+    const repairedCurrent: PlanContract = { ...current, pendingRevision: repairedPending, updatedAt: at };
+    const contracts = [...store.contracts];
+    contracts[index] = repairedCurrent;
+    writePlanContractStore(options, { schemaVersion: 1, updatedAt: at, contracts });
+    return repairedCurrent;
+  }
+  const explicitPredecessors = new Set(candidateWithLineage.supersedes ?? []);
   const conflictingScope = store.contracts.find((existing, candidateIndex) => candidateIndex !== index
     && !isTerminalPlanContractStatus(existing.status)
-    && existing.scopeKey === candidate.scopeKey);
-  if (conflictingScope) throw new Error(`PLAN_SCOPE_ALREADY_OWNED: ${candidate.scopeKey}:${conflictingScope.planId}`);
+    && existing.scopeKey === candidateWithLineage.scopeKey
+    && !explicitPredecessors.has(existing.planId));
+  if (conflictingScope) throw new Error(`PLAN_SCOPE_ALREADY_OWNED: ${candidateWithLineage.scopeKey}:${conflictingScope.planId}`);
+  const previousSemantic = planSemanticView(current);
+  const candidateSemantic = legacyPlanSemanticContext(candidateWithLineage);
   const repaired: PlanContract = {
-    ...candidate,
+    ...candidateWithLineage,
+    // Mechanical lifecycle revision is independent from the model-facing semantic
+    // head. Draft/extend compatibility must never silently overwrite semantic r1.
+    revision: current.revision,
+    semanticRevision: previousSemantic.revision + 1,
+    semanticUpdatedAt: at,
+    semanticContext: {
+      ...candidateSemantic,
+      requirementBasisRevision: previousSemantic.requirementBasisRevision,
+    },
     createdAt: current.createdAt,
     updatedAt: at,
   };
+  if (sqliteBacked(options)) {
+    return withControlPlaneTransaction(options.controllerHome, (database) => {
+      const scope = requirePlanContractStoreScopeKey(options);
+      const currentRecord = readControlPlaneRecordWithinTransaction<PlanContract>(database, 'plan_contract', scope, current.planId);
+      if (!currentRecord) throw new Error(`plan contract not found: ${current.planId}`);
+      const actualSemanticRevision = currentPlanSemanticRevision(currentRecord.value);
+      if (actualSemanticRevision !== previousSemantic.revision) {
+        throw new Error(`PLAN_REVISION_CONFLICT:${current.planId}:expected=${previousSemantic.revision}:actual=${actualSemanticRevision}`);
+      }
+      const semanticRevisionKey = `${current.planId}:r${previousSemantic.revision}`;
+      if (!readControlPlaneRecordWithinTransaction<PlanSemanticRevisionRecord>(database, 'plan_semantic_revision', scope, semanticRevisionKey)) {
+        writeControlPlaneRecordWithinTransaction(database, {
+          namespace: 'plan_semantic_revision', scope, key: semanticRevisionKey, schemaVersion: 1,
+          value: { schemaVersion: 1, ...previousSemantic, recordedAt: at },
+          action: 'plan_semantic_revision_archived', expectedRevision: null,
+        });
+      }
+      return writeControlPlaneRecordWithinTransaction(database, {
+        namespace: 'plan_contract', scope, key: current.planId, schemaVersion: 1,
+        value: repaired, action: 'plan_semantic_revised', expectedRevision: currentRecord.revision,
+      }).value;
+    });
+  }
+  appendJsonPlanSemanticRevisionRecord(options, { schemaVersion: 1, ...previousSemantic, recordedAt: at });
   const contracts = [...store.contracts];
   contracts[index] = repaired;
   writePlanContractStore(options, { schemaVersion: 1, updatedAt: at, contracts });
@@ -401,18 +839,95 @@ export function createPlanContract(options: PlanContractStoreOptions, input: Cre
   });
 }
 
+export function createPlanSemanticContext(options: PlanContractStoreOptions, input: CreatePlanSemanticInput): PlanContract {
+  return withPlanAdmissionLock(options, () => {
+    assertRequirementReference(options, input.requirementId);
+    const store = readPlanContractStore(options);
+    const planId = sanitizeFileComponent(input.planId);
+    if (!String(input.planId ?? '').trim() || planId === 'unknown') throw new Error('plan_id is required');
+    if (store.contracts.some((existing) => existing.planId === planId)) throw new Error(`plan contract already exists: ${planId}`);
+
+    // Thin Plan scope identifies one semantic planning lineage; it is not an
+    // execution mutex. The same Requirement + scope has one current Plan head,
+    // while genuinely independent goals remain free to use distinct scopes.
+    const scopeKey = normalizeScopeKey(input.scopeKey?.trim() || planId);
+    const requirementId = input.requirementId?.trim().slice(0, 160) || undefined;
+    const existingLineage = store.contracts.find((existing) =>
+      existing.planId !== planId
+      && isCurrentPlanContract(existing)
+      && existing.scopeKey === scopeKey
+      && (existing.requirementId?.trim() || undefined) === requirementId);
+    if (existingLineage) {
+      throw new Error(`PLAN_SEMANTIC_LINEAGE_ALREADY_EXISTS:${scopeKey}:${existingLineage.planId}`);
+    }
+
+    const goal = String(input.goal ?? '').trim().slice(0, 2_000);
+    if (!goal) throw new Error('PLAN_GOAL_REQUIRED');
+    const requirementBasisRevision = input.requirementBasisRevision === undefined
+      ? undefined
+      : (() => {
+          if (!Number.isInteger(input.requirementBasisRevision) || Number(input.requirementBasisRevision) < 1) {
+            throw new Error('PLAN_REQUIREMENT_BASIS_REVISION_INVALID');
+          }
+          return Number(input.requirementBasisRevision);
+        })();
+    const sourceBasisRevision = String(input.sourceBasisRevision ?? '').trim().slice(0, 200);
+    const items = normalizePlanSemanticItems(input.items);
+    const at = nowIso(options);
+    const semanticContext = {
+      requirementBasisRevision,
+      sourceBasisRevision,
+      goal,
+      nonGoals: bounded(input.nonGoals, 20),
+      assumptions: bounded(input.assumptions, 30),
+      resolvedDecisions: bounded(input.resolvedDecisions, 30),
+      stopConditions: bounded(input.stopConditions, 20),
+      replanConditions: bounded(input.replanConditions, 20),
+      integrationStrategy: input.integrationStrategy?.trim().slice(0, 1_000) || undefined,
+      items,
+    };
+    const plan: PlanContract = {
+      schemaVersion: 1,
+      planId,
+      revision: 1,
+      semanticRevision: 1,
+      semanticUpdatedAt: at,
+      semanticContext,
+      repoId: input.repoId,
+      requirementId,
+      scopeKey,
+      sourceRevision: sourceBasisRevision,
+      goal,
+      nonGoals: [...semanticContext.nonGoals],
+      assumptions: [...semanticContext.assumptions],
+      resolvedDecisions: [...semanticContext.resolvedDecisions],
+      stopConditions: [...semanticContext.stopConditions],
+      replanConditions: [...semanticContext.replanConditions],
+      integrationStrategy: semanticContext.integrationStrategy,
+      // Legacy lifecycle projection only. Thin Plan items never become PlanSteps.
+      status: 'approved',
+      steps: [],
+      evidenceRefs: [],
+      createdAt: at,
+      updatedAt: at,
+    };
+    writePlanContractStore(options, { schemaVersion: 1, updatedAt: at, contracts: [plan, ...store.contracts] });
+    return plan;
+  });
+}
+
 function admitPlanContractUnlocked(options: PlanContractStoreOptions, input: AdmitPlanContractInput): AdmitPlanContractResult {
   assertRequirementReference(options, input.requirementId);
-  const activePlans = listPlanContracts({ ...options, status: 'active', limit: 100 });
-  const resolution = resolvePlanAdmission(activePlans, {
+  const plans = listPlanContracts({ ...options, status: 'all', limit: 100 });
+  const resolution = resolvePlanAdmission(plans, {
     requirementId: input.requirementId,
     scopeKey: input.scopeKey,
     planRelation: input.planRelation,
     relatedPlanId: input.relatedPlanId,
   });
   if (resolution.admissionDecision === 'extend_existing' && resolution.plan) {
-    const successor = replacePlanContractUnlocked(options, resolution.plan.planId, input);
-    return { ...resolution, admissionDecision: 'create_new', plan: successor };
+    const revised = replacePlanContractUnlocked(options, resolution.plan.planId, input);
+    return { ...resolution, admissionDecision: 'reuse_existing', plan: revised };
   }
   if (resolution.admissionDecision !== 'create_new') return resolution;
   return { ...resolution, plan: createPlanContractUnlocked(options, input) };
@@ -430,11 +945,122 @@ export function getPlanContract(options: PlanContractStoreOptions, planId: strin
   return readPlanContractStore(options).contracts.find((contract) => contract.planId === sanitizeFileComponent(planId));
 }
 
+export function revisePlanSemanticContext(
+  options: PlanContractStoreOptions,
+  planIdInput: string,
+  input: RevisePlanSemanticInput,
+): PlanContract {
+  if (!Number.isInteger(input.expectedRevision) || input.expectedRevision < 1) throw new Error('PLAN_EXPECTED_REVISION_INVALID');
+  const planId = sanitizeFileComponent(planIdInput);
+  const requestedSuccessor = input.supersededBy === undefined
+    ? undefined
+    : (() => {
+        const raw = String(input.supersededBy).trim();
+        if (!raw) throw new Error('PLAN_SUCCESSOR_REQUIRED');
+        const successorId = sanitizeFileComponent(raw);
+        if (!successorId || successorId === 'unknown') throw new Error('PLAN_SUCCESSOR_INVALID');
+        if (successorId === planId) throw new Error(`PLAN_SUCCESSOR_SELF_REFERENCE:${planId}`);
+        return successorId;
+      })();
+  return withPlanAdmissionLock(options, () => {
+    const applyRevision = (current: PlanContract, at: string): { previous: PlanSemanticView; next: PlanContract } => {
+      const revision = currentPlanSemanticRevision(current);
+      if (revision !== input.expectedRevision) throw new Error(`PLAN_REVISION_CONFLICT:${planId}:expected=${input.expectedRevision}:actual=${revision}`);
+      const previous = planSemanticView(current);
+      const existingSuccessor = current.supersededBy?.trim() || undefined;
+      if (existingSuccessor && requestedSuccessor && existingSuccessor !== requestedSuccessor) {
+        throw new Error(`PLAN_SUCCESSOR_IMMUTABLE:${planId}:current=${existingSuccessor}:requested=${requestedSuccessor}`);
+      }
+      const supersededBy = requestedSuccessor ?? existingSuccessor;
+      const goal = input.goal === undefined ? previous.goal : String(input.goal).trim().slice(0, 2_000);
+      if (!goal) throw new Error('PLAN_GOAL_REQUIRED');
+      const requirementBasisRevision = input.requirementBasisRevision === undefined
+        ? previous.requirementBasisRevision
+        : (() => {
+            if (!Number.isInteger(input.requirementBasisRevision) || Number(input.requirementBasisRevision) < 1) throw new Error('PLAN_REQUIREMENT_BASIS_REVISION_INVALID');
+            return Number(input.requirementBasisRevision);
+          })();
+      const sourceBasisRevision = input.sourceBasisRevision === undefined ? previous.sourceBasisRevision : String(input.sourceBasisRevision).trim().slice(0, 200);
+      const items = input.items === undefined ? previous.items : normalizePlanSemanticItems(input.items);
+      const semanticContext = {
+        requirementBasisRevision,
+        sourceBasisRevision,
+        goal,
+        nonGoals: input.nonGoals === undefined ? previous.nonGoals : bounded(input.nonGoals, 20),
+        assumptions: input.assumptions === undefined ? previous.assumptions : bounded(input.assumptions, 30),
+        resolvedDecisions: input.resolvedDecisions === undefined ? previous.resolvedDecisions : bounded(input.resolvedDecisions, 30),
+        stopConditions: input.stopConditions === undefined ? previous.stopConditions : bounded(input.stopConditions, 20),
+        replanConditions: input.replanConditions === undefined ? previous.replanConditions : bounded(input.replanConditions, 20),
+        integrationStrategy: input.integrationStrategy === undefined ? previous.integrationStrategy : input.integrationStrategy === null ? undefined : String(input.integrationStrategy).trim().slice(0, 1_000) || undefined,
+        items,
+      };
+      return {
+        previous,
+        next: {
+          ...current,
+          ...(supersededBy ? { supersededBy } : {}),
+          semanticRevision: revision + 1,
+          semanticUpdatedAt: at,
+          semanticContext,
+          updatedAt: at,
+        },
+      };
+    };
+
+    if (sqliteBacked(options)) {
+      return withControlPlaneTransaction(options.controllerHome, (database) => {
+        const scope = requirePlanContractStoreScopeKey(options);
+        const currentRecord = readControlPlaneRecordWithinTransaction<PlanContract>(database, 'plan_contract', scope, planId);
+        if (!currentRecord) throw new Error(`plan contract not found: ${planId}`);
+        if (requestedSuccessor) {
+          const successorRecord = readControlPlaneRecordWithinTransaction<PlanContract>(database, 'plan_contract', scope, requestedSuccessor);
+          if (!successorRecord) throw new Error(`PLAN_SUCCESSOR_NOT_FOUND:${requestedSuccessor}`);
+          if (!isCurrentPlanContract(successorRecord.value)) throw new Error(`PLAN_SUCCESSOR_NOT_CURRENT:${requestedSuccessor}`);
+        }
+        const at = nowIso(options);
+        const { previous, next } = applyRevision(currentRecord.value, at);
+        const semanticRevisionKey = `${planId}:r${previous.revision}`;
+        if (!readControlPlaneRecordWithinTransaction<PlanSemanticRevisionRecord>(database, 'plan_semantic_revision', requirePlanContractStoreScopeKey(options), semanticRevisionKey)) {
+          writeControlPlaneRecordWithinTransaction(database, {
+            namespace: 'plan_semantic_revision', scope, key: semanticRevisionKey, schemaVersion: 1,
+            value: { schemaVersion: 1, ...previous, recordedAt: at },
+            action: 'plan_semantic_revision_archived', expectedRevision: null,
+          });
+        }
+        return writeControlPlaneRecordWithinTransaction(database, {
+          namespace: 'plan_contract', scope, key: planId, schemaVersion: 1,
+          value: next, action: 'plan_semantic_revised', expectedRevision: currentRecord.revision,
+        }).value;
+      });
+    }
+
+    const store = readPlanContractStore(options);
+    const index = store.contracts.findIndex((contract) => contract.planId === planId);
+    if (index < 0) throw new Error(`plan contract not found: ${planId}`);
+    if (requestedSuccessor) {
+      const successor = store.contracts.find((contract) => contract.planId === requestedSuccessor);
+      if (!successor) throw new Error(`PLAN_SUCCESSOR_NOT_FOUND:${requestedSuccessor}`);
+      if (!isCurrentPlanContract(successor)) throw new Error(`PLAN_SUCCESSOR_NOT_CURRENT:${requestedSuccessor}`);
+    }
+    const at = nowIso(options);
+    const { previous, next } = applyRevision(store.contracts[index]!, at);
+    appendJsonPlanSemanticRevisionRecord(options, { schemaVersion: 1, ...previous, recordedAt: at });
+    const contracts = [...store.contracts];
+    contracts[index] = next;
+    writePlanContractStore(options, { schemaVersion: 1, updatedAt: at, contracts });
+    return next;
+  });
+}
+
+export function isCurrentPlanContract(contract: PlanContract): boolean {
+  return !isTerminalPlanContractStatus(contract.status) && !contract.supersededBy?.trim();
+}
+
 export function listPlanContracts(options: PlanContractStoreOptions & { status?: PlanContractStatus | 'active' | 'all'; limit?: number }): PlanContract[] {
   const status = options.status ?? 'active';
   const limit = Math.max(1, Math.min(Math.trunc(options.limit ?? 50), 100));
   return readPlanContractStore(options).contracts
-    .filter((contract) => status === 'all' || (status === 'active' ? !isTerminalPlanContractStatus(contract.status) : contract.status === status))
+    .filter((contract) => status === 'all' || (status === 'active' ? isCurrentPlanContract(contract) : contract.status === status))
     .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))
     .slice(0, limit);
 }
@@ -442,6 +1068,7 @@ export function listPlanContracts(options: PlanContractStoreOptions & { status?:
 export function summarizePlanContract(plan: PlanContract): PlanContractSummary {
   return {
     planId: plan.planId,
+    revision: currentPlanRevision(plan),
     repoId: plan.repoId,
     requirementId: plan.requirementId,
     scopeKey: plan.scopeKey,
@@ -453,204 +1080,3 @@ export function summarizePlanContract(plan: PlanContract): PlanContractSummary {
     updatedAt: plan.updatedAt,
   };
 }
-
-function approvalErrors(plan: PlanContract, allPlans: readonly PlanContract[]): string[] {
-  const errors = draftContentErrors(plan).map((error) => `${error} before approval`);
-  const scopeIsCommitted = (status: PlanContractStatus): boolean => [
-    'approved',
-    'executing',
-    'replanning',
-    'verifying',
-    'ready_to_finalize',
-  ].includes(status);
-  if (allPlans.some((existing) => existing.planId !== plan.planId && existing.scopeKey === plan.scopeKey && scopeIsCommitted(existing.status))) {
-    errors.push(`active plan already owns scope_key ${plan.scopeKey}`);
-  }
-  return [...new Set(errors)];
-}
-
-function approvePlanContractUnlocked(options: PlanContractStoreOptions, planId: string): PlanContract {
-  const store = readPlanContractStore(options);
-  const index = store.contracts.findIndex((contract) => contract.planId === sanitizeFileComponent(planId));
-  if (index < 0) throw new Error(`plan contract not found: ${sanitizeFileComponent(planId)}`);
-  const current = store.contracts[index];
-  assertRequirementReference(options, current.requirementId);
-  if (current.status !== 'draft' && current.status !== 'reviewing') throw new Error(`plan contract ${current.planId} cannot be approved from ${current.status}`);
-  const errors = approvalErrors(current, store.contracts);
-  if (errors.length > 0) throw new Error(`plan contract ${current.planId} cannot be approved: ${errors.join('; ')}`);
-  const at = nowIso(options);
-  const next = { ...current, status: 'approved' as const, updatedAt: at };
-  const contracts = [...store.contracts];
-  contracts[index] = next;
-  writePlanContractStore(options, { schemaVersion: 1, updatedAt: at, contracts });
-  return next;
-}
-
-export function approvePlanContract(options: PlanContractStoreOptions, planId: string): PlanContract {
-  return withPlanAdmissionLock(options, () => approvePlanContractUnlocked(options, planId));
-}
-
-export async function approvePlanContractAsync(options: PlanContractStoreOptions, planId: string): Promise<PlanContract> {
-  return await withPlanAdmissionLockAsync(options, () => approvePlanContractUnlocked(options, planId));
-}
-
-export function supersedePlanContract(options: PlanContractStoreOptions, planId: string, supersededBy: string): PlanContract {
-  return withPlanAdmissionLock(options, () => {
-    const store = readPlanContractStore(options);
-    const index = store.contracts.findIndex((contract) => contract.planId === sanitizeFileComponent(planId));
-    if (index < 0) throw new Error(`plan contract not found: ${sanitizeFileComponent(planId)}`);
-    const current = store.contracts[index]!;
-    if (isTerminalPlanContractStatus(current.status)) throw new Error(`plan contract ${current.planId} is terminal (${current.status})`);
-    const replacement = sanitizeFileComponent(supersededBy);
-    if (!replacement || replacement === 'unknown') throw new Error('superseded_by is required');
-    if (replacement === current.planId) throw new Error('PLAN_SUCCESSOR_ID_MUST_CHANGE');
-    const successor = store.contracts.find((contract) => contract.planId === replacement);
-    if (!successor) throw new Error(`PLAN_SUCCESSOR_NOT_FOUND: ${replacement}`);
-    const at = nowIso(options);
-    const next = { ...current, status: 'superseded' as const, supersededBy: successor.planId, updatedAt: at };
-    const contracts = [...store.contracts];
-    contracts[index] = next;
-    writePlanContractStore(options, { schemaVersion: 1, updatedAt: at, contracts });
-    return next;
-  });
-}
-
-/**
- * Atomically reserve one eligible step for one WorkContract. This is the
- * Plan-to-Work concurrency boundary: competing callers cannot bind the same
- * step, and a stale source revision causes no WorkContract side effect.
- */
-export function claimPlanStepForWork(
-  options: PlanContractStoreOptions,
-  input: { planId: string; stepId: string; workId: string; sourceRevision: string },
-): PlanContract {
-  return updatePlanContract(options, input.planId, (current) => {
-    assertRequirementReference(options, current.requirementId);
-    if (current.status !== 'approved' && current.status !== 'executing') {
-      throw new Error(`PLAN_NOT_EXECUTABLE: ${current.planId} is ${current.status}`);
-    }
-    if (current.sourceRevision !== input.sourceRevision) {
-      return { ...current, status: 'invalidated_by_drift', updatedAt: nowIso(options) };
-    }
-    const stepIndex = current.steps.findIndex((step) => step.id === sanitizeFileComponent(input.stepId));
-    if (stepIndex < 0) throw new Error(`PLAN_STEP_NOT_FOUND: ${input.stepId}`);
-    const step = current.steps[stepIndex];
-    if (step.status === 'executing' || step.workId) throw new Error(`PLAN_STEP_ALREADY_ACTIVE: ${step.id}`);
-    if (step.status === 'completed') throw new Error(`PLAN_STEP_ALREADY_COMPLETED: ${step.id}`);
-    const unresolved = step.dependencies.filter((dependency) => current.steps.find((candidate) => candidate.id === dependency)?.status !== 'completed');
-    if (unresolved.length > 0) throw new Error(`PLAN_STEP_DEPENDENCIES_PENDING: ${unresolved.join(', ')}`);
-    const at = nowIso(options);
-    const steps = [...current.steps];
-    steps[stepIndex] = { ...step, status: 'executing', workId: input.workId };
-    return { ...current, status: 'executing', steps, updatedAt: at };
-  });
-}
-
-export function repairDanglingPlanStepWorkBinding(
-  options: PlanContractStoreOptions,
-  input: { planId: string; stepId: string; expectedWorkId: string; reason: string },
-): PlanContract {
-  const expectedWorkId = input.expectedWorkId.trim();
-  const reason = input.reason.trim();
-  if (!expectedWorkId) throw new Error('PLAN_STEP_REPAIR_EXPECTED_WORK_REQUIRED');
-  if (!reason) throw new Error('PLAN_STEP_REPAIR_REASON_REQUIRED');
-  return updatePlanContract(options, input.planId, (current) => {
-    if (isTerminalPlanContractStatus(current.status)) throw new Error(`PLAN_STEP_REPAIR_PLAN_TERMINAL: ${current.planId} is ${current.status}`);
-    const stepIndex = current.steps.findIndex((step) => step.id === sanitizeFileComponent(input.stepId));
-    if (stepIndex < 0) throw new Error(`PLAN_STEP_NOT_FOUND: ${input.stepId}`);
-    const step = current.steps[stepIndex];
-    if (step.workId !== expectedWorkId) {
-      throw new Error(`PLAN_STEP_REPAIR_BINDING_CHANGED: ${step.id} is bound to ${step.workId ?? 'no Work'}, expected ${expectedWorkId}`);
-    }
-    if (step.status !== 'executing') {
-      throw new Error(`PLAN_STEP_REPAIR_STATUS_INVALID: ${step.id} is ${step.status}`);
-    }
-    const at = nowIso(options);
-    const steps = [...current.steps];
-    steps[stepIndex] = {
-      ...step,
-      status: 'ready',
-      workId: undefined,
-      evidenceRefs: [{
-        title: 'dangling Work binding repaired',
-        summary: `${expectedWorkId}: ${reason}`.slice(0, 2_000),
-        detailLevel: 'summary' as const,
-      }, ...step.evidenceRefs].slice(0, 20),
-    };
-    // This is admission-state repair, not semantic replanning: the Plan and its
-    // acceptance criteria remain authoritative. Return the exact step to ready
-    // so a later start can atomically admit one replacement for the missing
-    // record without forcing a second Plan authority.
-    return { ...current, status: 'executing', steps, updatedAt: at };
-  });
-}
-
-export function completePlanStepForWork(
-  options: PlanContractStoreOptions,
-  input: {
-    planId: string;
-    stepId: string;
-    work: Pick<WorkContract, 'workId' | 'status' | 'phase' | 'evidenceState' | 'completionOutcome' | 'completionReceipt' | 'evidenceRefs'>;
-  },
-): PlanContract {
-  return updatePlanContract(options, input.planId, (current) => {
-    const stepIndex = current.steps.findIndex((step) => step.id === sanitizeFileComponent(input.stepId));
-    if (stepIndex < 0) throw new Error(`PLAN_STEP_NOT_FOUND: ${input.stepId}`);
-    const step = current.steps[stepIndex];
-    if (step.workId !== input.work.workId) throw new Error(`PLAN_STEP_WORK_MISMATCH: ${input.stepId}`);
-    if (step.status === 'completed') return current;
-    const delivered = input.work.status === 'completed'
-      && input.work.phase === 'cleanup'
-      && input.work.evidenceState === 'valid'
-      && Boolean(input.work.completionOutcome && input.work.completionOutcome !== 'superseded')
-      && Boolean(input.work.completionReceipt);
-    const failed = input.work.status === 'failed' || input.work.status === 'cancelled';
-    if (!delivered && !failed) throw new Error(`PLAN_STEP_WORK_NOT_TERMINAL: ${input.work.workId}`);
-    const at = nowIso(options);
-    const steps = [...current.steps];
-    steps[stepIndex] = {
-      ...step,
-      // Work completion proves machine delivery only. The Plan step remains in
-      // semantic validation until an explicit Controller acceptance records it.
-      // Failed/cancelled Work returns the slice to ready for replanning.
-      status: delivered ? 'validating' : 'ready',
-      // Successful delivery keeps the exact Work identity through semantic
-      // validation. Failed/cancelled Work releases the step authority so the
-      // replanning path cannot retain a ghost binding to a terminal Work.
-      workId: delivered ? step.workId : undefined,
-      evidenceRefs: input.work.evidenceRefs.length > 0 ? input.work.evidenceRefs.slice(0, 20) : step.evidenceRefs,
-    };
-    return { ...current, status: delivered ? 'verifying' : 'replanning', steps, updatedAt: at };
-  });
-}
-
-export function acceptPlanStepEvidence(
-  options: PlanContractStoreOptions,
-  input: { planId: string; stepId: string; reviewer: string; rationale: string; acceptedSourceRevision?: string },
-): PlanContract {
-  const reviewer = input.reviewer.trim();
-  const rationale = input.rationale.trim();
-  if (!reviewer || !rationale) throw new Error('PLAN_STEP_SEMANTIC_ACCEPTANCE_METADATA_REQUIRED');
-  return updatePlanContract(options, input.planId, (current) => {
-    const stepIndex = current.steps.findIndex((step) => step.id === sanitizeFileComponent(input.stepId));
-    if (stepIndex < 0) throw new Error(`PLAN_STEP_NOT_FOUND: ${input.stepId}`);
-    const step = current.steps[stepIndex];
-    if (step.status === 'completed') return current;
-    if (step.status !== 'validating') throw new Error(`PLAN_STEP_NOT_READY_FOR_SEMANTIC_ACCEPTANCE: ${step.id} is ${step.status}`);
-    const steps = [...current.steps];
-    steps[stepIndex] = {
-      ...step,
-      status: 'completed',
-      evidenceRefs: [{ title: 'semantic acceptance', summary: `${reviewer}: ${rationale}`, detailLevel: 'summary' as const }, ...step.evidenceRefs].slice(0, 20),
-    };
-    const allCompleted = steps.every((candidate) => candidate.status === 'completed');
-    const acceptedSourceRevision = input.acceptedSourceRevision?.trim();
-    return {
-      ...current,
-      ...(acceptedSourceRevision ? { sourceRevision: acceptedSourceRevision } : {}),
-      status: allCompleted ? 'finalized' : 'executing',
-      steps,
-      updatedAt: nowIso(options),
-    };
-  });
-}