@moretea-labs/forge 1.7.0 → 1.7.2

package/src/runtime/control-plane/facade/index.ts

@@ -15,3 +15,5 @@ export * from './goal-workloop-access';
 export * from './codex-delegation';
 export * from './self-healing-loop';
 export * from './operation-digest';
+export * from './requirement-authority';
+export * from './repository-work-admission';

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

@@ -60,6 +60,11 @@ export interface AdmitPlanContractInput extends CreatePlanContractInput {
   relatedPlanId?: string;
 }
 
+export interface RepairDraftPlanContractInput extends Omit<CreatePlanContractInput, 'planId' | 'repoId' | 'requirementId' | 'evidenceRefs'> {
+  /** Source revision observed before entering the admission lock; rejects stale draft writers. */
+  expectedSourceRevision?: string;
+}
+
 export type AdmitPlanContractResult = PlanAdmissionResolution;
 
 export interface PlanContractSummary {
@@ -254,6 +259,32 @@ function buildPlanContract(input: CreatePlanContractInput, at: string): PlanCont
   };
 }
 
+function draftContentErrors(plan: PlanContract): string[] {
+  const errors: string[] = [];
+  if (!plan.sourceRevision) errors.push('source_revision is required');
+  if (!plan.scopeKey || plan.scopeKey === 'unknown') errors.push('scope_key is required');
+  if (!plan.goal) errors.push('goal is required');
+  if (plan.steps.length === 0) errors.push('at least one plan step is required');
+  const ids = new Set<string>();
+  for (const step of plan.steps) {
+    if (!step.id || step.id === 'unknown') errors.push('every plan step needs an id');
+    else if (ids.has(step.id)) errors.push(`duplicate plan step id: ${step.id}`);
+    else ids.add(step.id);
+    if (!step.objective) errors.push(`step ${step.id || 'unknown'} needs an objective`);
+    if (step.checks.length === 0) errors.push(`step ${step.id || 'unknown'} needs at least one machine-checkable check`);
+    if (step.acceptanceCriteria.length === 0) errors.push(`step ${step.id || 'unknown'} needs acceptance criteria`);
+    if (step.status !== 'pending') errors.push(`step ${step.id || 'unknown'} must be pending before approval`);
+  }
+  for (const step of plan.steps) {
+    for (const dependency of step.dependencies) {
+      const dependencyStep = plan.steps.find((candidate) => candidate.id === dependency);
+      if (!dependencyStep) errors.push(`step ${step.id} references unknown dependency ${dependency}`);
+      else if (dependencyStep.status !== 'pending') errors.push(`step ${step.id} dependency ${dependency} must be pending before approval`);
+    }
+  }
+  return [...new Set(errors)];
+}
+
 function createPlanContractUnlocked(options: PlanContractStoreOptions, input: CreatePlanContractInput): PlanContract {
   assertRequirementReference(options, input.requirementId);
   const at = nowIso(options);
@@ -295,6 +326,64 @@ function replacePlanContractUnlocked(
   return successor;
 }
 
+function repairDraftPlanContractUnlocked(
+  options: PlanContractStoreOptions,
+  planId: string,
+  input: RepairDraftPlanContractInput,
+): PlanContract {
+  const store = readPlanContractStore(options);
+  const key = sanitizeFileComponent(planId);
+  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}`);
+  }
+  assertRequirementReference(options, current.requirementId);
+  const at = nowIso(options);
+  const candidate = buildPlanContract({
+    ...input,
+    planId: current.planId,
+    repoId: current.repoId,
+    requirementId: current.requirementId,
+    evidenceRefs: current.evidenceRefs,
+  }, at);
+  const contentErrors = draftContentErrors(candidate);
+  if (contentErrors.length > 0) {
+    throw new Error(`PLAN_DRAFT_REPAIR_INVALID: ${contentErrors.join('; ')}`);
+  }
+  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}`);
+  const repaired: PlanContract = {
+    ...candidate,
+    createdAt: current.createdAt,
+    updatedAt: at,
+  };
+  const contracts = [...store.contracts];
+  contracts[index] = repaired;
+  writePlanContractStore(options, { schemaVersion: 1, updatedAt: at, contracts });
+  return repaired;
+}
+
+export function repairDraftPlanContract(
+  options: PlanContractStoreOptions,
+  planId: string,
+  input: RepairDraftPlanContractInput,
+): PlanContract {
+  return withPlanAdmissionLock(options, () => repairDraftPlanContractUnlocked(options, planId, input));
+}
+
+export async function repairDraftPlanContractAsync(
+  options: PlanContractStoreOptions,
+  planId: string,
+  input: RepairDraftPlanContractInput,
+): Promise<PlanContract> {
+  return await withPlanAdmissionLockAsync(options, () => repairDraftPlanContractUnlocked(options, planId, input));
+}
+
 export function createPlanContract(options: PlanContractStoreOptions, input: CreatePlanContractInput): PlanContract {
   return withPlanAdmissionLock(options, () => {
     const store = readPlanContractStore(options);
@@ -366,28 +455,7 @@ export function summarizePlanContract(plan: PlanContract): PlanContractSummary {
 }
 
 function approvalErrors(plan: PlanContract, allPlans: readonly PlanContract[]): string[] {
-  const errors: string[] = [];
-  if (!plan.sourceRevision) errors.push('source_revision is required before approval');
-  if (!plan.scopeKey || plan.scopeKey === 'unknown') errors.push('scope_key is required before approval');
-  if (!plan.goal) errors.push('goal is required before approval');
-  if (plan.steps.length === 0) errors.push('at least one plan step is required before approval');
-  const ids = new Set<string>();
-  for (const step of plan.steps) {
-    if (!step.id || step.id === 'unknown') errors.push('every plan step needs an id');
-    else if (ids.has(step.id)) errors.push(`duplicate plan step id: ${step.id}`);
-    else ids.add(step.id);
-    if (!step.objective) errors.push(`step ${step.id || 'unknown'} needs an objective`);
-    if (step.checks.length === 0) errors.push(`step ${step.id || 'unknown'} needs at least one machine-checkable check`);
-    if (step.acceptanceCriteria.length === 0) errors.push(`step ${step.id || 'unknown'} needs acceptance criteria`);
-    if (step.status !== 'pending') errors.push(`step ${step.id || 'unknown'} must be pending before approval`);
-  }
-  for (const step of plan.steps) {
-    for (const dependency of step.dependencies) {
-      const dependencyStep = plan.steps.find((candidate) => candidate.id === dependency);
-      if (!dependencyStep) errors.push(`step ${step.id} references unknown dependency ${dependency}`);
-      else if (dependencyStep.status !== 'pending') errors.push(`step ${step.id} dependency ${dependency} must be pending before approval`);
-    }
-  }
+  const errors = draftContentErrors(plan).map((error) => `${error} before approval`);
   const scopeIsCommitted = (status: PlanContractStatus): boolean => [
     'approved',
     'executing',

package/src/runtime/control-plane/facade/repository-work-admission.ts

@@ -0,0 +1,147 @@
+import type { AccessMode } from '../governance/access-policy';
+import type { RouteDecision } from '../routing/route-policy';
+import { createWorkContract, getWorkContract, updateWorkContract, type WorkContractStoreOptions } from './work-contract-store';
+import type { WorkContract } from './types';
+
+export interface PreparedRepositoryWorkAdmissionInput {
+  workId: string;
+  repoId: string;
+  objective: string;
+  acceptanceCriteria: string[];
+  allowedPaths: string[];
+  checks: string[];
+  accessMode: AccessMode;
+  isolated: boolean;
+  requestedBy: WorkContract['requestedBy'];
+  requestId: string;
+}
+
+/**
+ * Canonical WorkContract admission for the compatibility work_prepare surface.
+ * Workspace materialization remains an execution concern; this function owns
+ * the semantic contract shape so transports cannot invent a parallel policy.
+ */
+export function admitPreparedRepositoryWorkContract(
+  store: WorkContractStoreOptions,
+  input: PreparedRepositoryWorkAdmissionInput,
+): WorkContract {
+  return createWorkContract(store, {
+    workId: input.workId,
+    repoId: input.repoId,
+    mode: input.isolated ? 'goal_workloop' : 'direct_control',
+    objective: input.objective,
+    acceptanceCriteria: input.acceptanceCriteria,
+    allowedPaths: input.allowedPaths,
+    forbiddenPaths: [],
+    checks: input.checks,
+    constraints: {
+      accessMode: input.accessMode,
+      workspaceMode: input.isolated ? 'isolated' : 'current',
+      requireWorktree: input.isolated,
+      directMainProhibited: input.isolated,
+      allowCommit: true,
+      allowMerge: true,
+      allowCleanup: true,
+    },
+    worktreePolicy: {
+      required: input.isolated,
+      reason: input.isolated ? 'work_prepare selected isolated worktree execution' : 'explicitly reused a registered checkout',
+    },
+    requestedBy: input.requestedBy,
+    requestId: input.requestId,
+  });
+}
+
+export interface DirectEditWorkAdmissionInput {
+  workId: string;
+  repoId: string;
+  checkoutId?: string;
+  principalId?: string;
+  controllerInstanceId?: string;
+  baseRevision?: string;
+  workspaceFingerprint: string;
+  routeDecision: RouteDecision;
+  objective: string;
+  issueId?: string;
+  taskId?: string;
+  allowedPaths: string[];
+  checks: string[];
+  requestedBy: WorkContract['requestedBy'];
+}
+
+/**
+ * Canonical compatibility admission for an Edit Session bound to Direct Work.
+ * The caller supplies the canonical Route Policy decision as evidence; this
+ * boundary rejects any decision that requires isolation or a non-direct lane.
+ */
+export function admitDirectEditWorkContract(
+  store: WorkContractStoreOptions,
+  input: DirectEditWorkAdmissionInput,
+): WorkContract {
+  if (input.routeDecision.executionMode !== 'direct_control' || input.routeDecision.requiresIsolation) {
+    throw new Error('DIRECT_EDIT_WORK_ROUTE_CONFLICT: canonical Route Policy does not permit Direct Control');
+  }
+  return createWorkContract(store, {
+    workId: input.workId,
+    repoId: input.repoId,
+    checkoutId: input.checkoutId,
+    principalId: input.principalId,
+    controllerInstanceId: input.controllerInstanceId,
+    baseRevision: input.baseRevision,
+    workspaceFingerprint: input.workspaceFingerprint,
+    routeDecisionFingerprint: input.routeDecision.inputFingerprint,
+    routeDecision: input.routeDecision,
+    mode: 'direct_control',
+    objective: input.objective,
+    acceptanceCriteria: [],
+    constraints: { workspaceMode: 'current', requireWorktree: false, requireHandoffOnAmbiguity: true },
+    risk: 'low',
+    status: 'running',
+    phase: 'implementation',
+    issueId: input.issueId,
+    taskId: input.taskId,
+    scopeSummary: input.objective,
+    allowedPaths: input.allowedPaths,
+    forbiddenPaths: [],
+    checks: input.checks,
+    requestedBy: input.requestedBy,
+    evidenceRefs: [],
+    handoffRefs: [],
+    suggestedNextActions: [],
+    policyDecisions: [],
+    checkRefs: [],
+    reconciliations: [],
+  });
+}
+
+
+export interface MaterializedRepositoryWorkspace {
+  managed: boolean;
+  checkoutId?: string;
+  root?: string;
+  baseRevision?: string | null;
+}
+
+/**
+ * Canonical placement materialization transition for an admitted isolated
+ * WorkContract. The concrete worktree creator is injected by the execution
+ * boundary; only this authority decides how its evidence updates the Work.
+ */
+export function materializeRepositoryWorkPlacement(
+  store: WorkContractStoreOptions,
+  workId: string,
+  materialize: (contract: WorkContract) => MaterializedRepositoryWorkspace,
+): WorkContract | undefined {
+  const contract = getWorkContract(store, workId);
+  if (!contract || contract.worktreePolicy.required !== true || contract.worktreeRef) return contract;
+  const workspace = materialize(contract);
+  if (!workspace.managed || !workspace.checkoutId || !workspace.root) {
+    throw new Error('MANAGED_WORKSPACE_NOT_MATERIALIZED');
+  }
+  return updateWorkContract(store, workId, {
+    checkoutId: workspace.checkoutId,
+    baseRevision: workspace.baseRevision ?? contract.baseRevision,
+    worktreeRef: workspace.root,
+    driver: { ...contract.driver, preferred: 'isolated_worktree', allowDirectEdit: false },
+  });
+}

package/src/runtime/control-plane/facade/requirement-authority.ts

@@ -0,0 +1,83 @@
+import {
+  createRequirement,
+  readRequirement,
+  type CreateRequirementInput,
+  type Requirement,
+  type RequirementStoreOptions,
+} from '../persistence/requirement-store';
+
+export type RequirementAdmissionDecision = 'created' | 'reuse_existing' | 'existing_conflict';
+
+export interface RequirementAdmissionResult {
+  decision: RequirementAdmissionDecision;
+  requirement: Requirement;
+  created: boolean;
+}
+
+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));
+}
+
+/**
+ * Canonical Requirement bootstrap request. Persistence performs the same
+ * defensive bounds before writing, but create/reuse/conflict admission lives
+ * only here so MCP/CLI adapters cannot grow their own Requirement lifecycle.
+ */
+export function normalizeRequirementAdmissionInput(input: CreateRequirementInput): CreateRequirementInput {
+  const requirementId = String(input.requirementId ?? '').trim();
+  if (!requirementId || requirementId.includes('/') || requirementId.includes('\\')) throw new Error('REQUIREMENT_ID_INVALID');
+  const normalized: CreateRequirementInput = {
+    requirementId: requirementId.slice(0, 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),
+    legacyAliases: bounded(input.legacyAliases, 20, 160),
+  };
+  if (!normalized.title || !normalized.outcomeStatement) throw new Error('REQUIREMENT_CONTENT_REQUIRED');
+  return normalized;
+}
+
+function sameBootstrapIdentity(existing: Requirement, requested: CreateRequirementInput): boolean {
+  return existing.requirementId === requested.requirementId
+    && existing.title === requested.title
+    && existing.outcomeStatement === requested.outcomeStatement
+    && JSON.stringify(existing.acceptanceCriteria) === JSON.stringify(requested.acceptanceCriteria ?? [])
+    && JSON.stringify(existing.requiredDeliveryReferences) === JSON.stringify(requested.requiredDeliveryReferences ?? [])
+    && JSON.stringify(existing.legacyAliases) === JSON.stringify(requested.legacyAliases ?? []);
+}
+
+function existingDecision(existing: Requirement, requested: CreateRequirementInput): RequirementAdmissionResult {
+  return {
+    decision: sameBootstrapIdentity(existing, requested) ? 'reuse_existing' : 'existing_conflict',
+    requirement: existing,
+    created: false,
+  };
+}
+
+/**
+ * Sole bootstrap admission authority for Requirement identity. A create race is
+ * closed by rereading the winner and applying the same identity comparison;
+ * adapters therefore never need read/compare/create policy of their own.
+ */
+export function admitRequirement(
+  options: RequirementStoreOptions,
+  input: CreateRequirementInput,
+): RequirementAdmissionResult {
+  const requested = normalizeRequirementAdmissionInput(input);
+  const existing = readRequirement(options, requested.requirementId)?.value;
+  if (existing) return existingDecision(existing, requested);
+
+  try {
+    return { decision: 'created', requirement: createRequirement(options, requested), created: true };
+  } catch (error) {
+    if (!(error instanceof Error) || !error.message.startsWith('REQUIREMENT_ALREADY_EXISTS:')) throw error;
+    const raced = readRequirement(options, requested.requirementId)?.value;
+    if (!raced) throw error;
+    return existingDecision(raced, requested);
+  }
+}

package/src/runtime/control-plane/facade/types.ts

@@ -120,6 +120,7 @@ export const TERMINAL_WORK_CONTRACT_STATUSES: readonly WorkContractStatus[] = [
 export const WORK_KINDS = [
   'repository_change',
   'completed_no_change',
+  'read_only_review',
   'investigation',
   'local_effect',
   'remote_effect',
@@ -137,6 +138,44 @@ export type EvidenceState = (typeof EVIDENCE_STATES)[number];
 export const COMPLETION_OUTCOMES = ['completed_changed', 'completed_no_change', 'completed_local', 'completed_remote', 'superseded'] as const;
 export type CompletionOutcome = (typeof COMPLETION_OUTCOMES)[number];
 
+/** Source-bound semantic evidence accumulated by a recoverable read-only review. */
+export interface ReadOnlyReviewEvidence {
+  sourceRevision: string;
+  workspaceFingerprint?: string;
+  inspectedPaths: string[];
+  findings: string[];
+  recordedAt: string;
+}
+
+/** Controller-reviewed binding from one exact Work acceptance criterion to durable evidence. */
+export interface WorkSemanticAcceptanceEvidence {
+  criterion: string;
+  evidenceIds: string[];
+  rationale: string;
+  recordedAt: string;
+}
+
+/**
+ * Terminal authority for a clean read-only review. This deliberately does not
+ * impersonate repository delivery: it proves the reviewed source stayed at the
+ * frozen base revision with no workspace delta and records the bounded review
+ * scope that justified completed_no_change.
+ */
+export interface ReadOnlyReviewCompletionReceipt {
+  schemaVersion: 1;
+  receiptId: string;
+  source: 'read_only_review';
+  workId: string;
+  baseRevision: string;
+  sourceRevision: string;
+  workspaceFingerprint?: string;
+  /** Explicit unchanged-workspace proof captured by the trusted finalizer. Must be empty. */
+  workspaceChangedPaths: string[];
+  inspectedPaths: string[];
+  findingCount: 0;
+  recordedAt: string;
+}
+
 /**
  * Terminal receipt for a bounded Controller-local side effect that is not a
  * repository delivery. Repository Task/Issue completion keeps using the
@@ -157,18 +196,21 @@ export interface LocalEffectCompletionReceipt {
   recordedAt: string;
 }
 
-/** Durable completion authority for one typed remote plugin effect. */
+/** Durable completion authority for one typed remote effect. */
 export interface RemoteEffectCompletionReceipt {
   schemaVersion: 1;
-  /** Reuse the authoritative PLG-* receipt id rather than manufacturing parallel evidence. */
+  /** Plugin receipts retain their PLG-* id; repository Process effects use their canonical Process id. */
   receiptId: string;
   source: 'remote_effect';
   workId: string;
-  pluginId: string;
+  /** Historical receipts omit this field and are interpreted as plugin_action. */
+  authority?: 'plugin_action' | 'repository_process';
+  pluginId?: string;
   actionId: string;
   requestId: string;
   semanticKey: string;
   resultDigest: string;
+  processId?: string;
   recordedAt: string;
 }
 
@@ -197,12 +239,21 @@ export interface DirectEditWorkCompletionReceipt {
   recordedAt: string;
 }
 
-export type WorkCompletionReceipt = RepositoryCompletionReceipt | DirectEditWorkCompletionReceipt | LocalEffectCompletionReceipt | RemoteEffectCompletionReceipt;
+export type WorkCompletionReceipt = RepositoryCompletionReceipt | DirectEditWorkCompletionReceipt | ReadOnlyReviewCompletionReceipt | LocalEffectCompletionReceipt | RemoteEffectCompletionReceipt;
 
 export function isRepositoryCompletionReceipt(
   receipt: WorkCompletionReceipt,
 ): receipt is RepositoryCompletionReceipt {
-  return receipt.source !== 'local_effect' && receipt.source !== 'remote_effect' && receipt.source !== 'direct_edit_work';
+  return receipt.source !== 'local_effect'
+    && receipt.source !== 'remote_effect'
+    && receipt.source !== 'direct_edit_work'
+    && receipt.source !== 'read_only_review';
+}
+
+export function isReadOnlyReviewCompletionReceipt(
+  receipt: WorkCompletionReceipt,
+): receipt is ReadOnlyReviewCompletionReceipt {
+  return receipt.source === 'read_only_review';
 }
 
 export function isRemoteEffectCompletionReceipt(
@@ -348,6 +399,8 @@ export interface WorkContractConstraints {
   /** current is the stability-first default; isolated is opt-in or used for explicit parallelism. */
   workspaceMode?: 'current' | 'isolated' | 'auto';
   requireWorktree?: boolean;
+  /** Admission fence: repository mutation must not use the Direct Control/current-main lane. */
+  directMainProhibited?: boolean;
   /** True when a change alters the agreed architecture direction rather than only implementation details. */
   architectureStrategyChange?: boolean;
   /** True when the proposed change weakens the thin-harness / high-performance execution policy. */
@@ -490,6 +543,10 @@ export interface WorkContract {
     actualChangedPaths: string[];
     recordedAt: string;
   };
+  /** Source-bound semantic findings/scope for first-class recoverable read-only review Work. */
+  readOnlyReviewEvidence?: ReadOnlyReviewEvidence;
+  /** Explicit Controller-reviewed acceptance bindings. Mechanical evidence attribution alone never writes this field. */
+  semanticAcceptanceEvidence?: WorkSemanticAcceptanceEvidence[];
   /** Explicit policy fence. This is not semantic completeness evidence. */
   allowedPaths: string[];
   forbiddenPaths: string[];
@@ -679,6 +736,10 @@ export interface ExecutionModeSelectionInput {
   workspaceDirty?: boolean;
   workspaceFingerprint?: string;
   checkoutId?: string;
+  /** Canonical typed placement constraint; never inferred from objective text. */
+  workspacePlacement?: 'current' | 'isolated' | 'auto';
+  /** Admission fence that has precedence over explicit Direct routing. */
+  directMainProhibited?: boolean;
   requiresInvestigation?: boolean;
   requiresLongRunningChecks?: boolean;
   requiresParallelism?: boolean;
@@ -742,6 +803,8 @@ export function selectExecutionMode(input: ExecutionModeSelectionInput): Executi
       dirty: input.workspaceDirty,
       checkoutId: input.checkoutId,
       fingerprint: input.workspaceFingerprint,
+      placement: input.workspacePlacement,
+      directMainProhibited: input.directMainProhibited,
     },
     policy: {
       risk: input.risk,