@moretea-labs/forge 1.6.0 → 1.7.1

package/src/runtime/control-plane/facade/semantic-admission.ts

@@ -0,0 +1,205 @@
+import { withControllerLock, withControllerLockAsync } from '../../../cli/repositories/locks';
+import { sanitizeFileComponent } from '../../shared/json-files';
+import { isTerminalPlanContractStatus, type PlanContract } from './types';
+
+export const PLAN_ADMISSION_RELATIONS = ['extend', 'parallel'] as const;
+export type PlanAdmissionRelation = (typeof PLAN_ADMISSION_RELATIONS)[number];
+
+export type PlanAdmissionReason =
+  | 'exact_scope_authority'
+  | 'requirement_relation_required'
+  | 'extension_target_required'
+  | 'extend_existing'
+  | 'create_new';
+
+export interface PlanAdmissionInput {
+  requirementId?: string;
+  scopeKey: string;
+  planRelation?: PlanAdmissionRelation;
+  relatedPlanId?: string;
+}
+
+export interface PlanAdmissionResolution {
+  admissionDecision: 'reuse_existing' | 'resolution_required' | 'extend_existing' | 'create_new';
+  resolutionRequired: boolean;
+  reason: PlanAdmissionReason;
+  normalizedScopeKey: string;
+  plan?: PlanContract;
+  candidates: PlanContract[];
+  allowedPlanRelations?: readonly PlanAdmissionRelation[];
+}
+
+export function normalizePlanScopeKey(value: string): string {
+  const raw = String(value ?? '').trim();
+  if (!raw) return '';
+  const normalized = sanitizeFileComponent(raw).toLowerCase().slice(0, 160);
+  return normalized === 'unknown' ? '' : normalized;
+}
+
+export function resolvePlanAdmission(
+  plans: readonly PlanContract[],
+  input: PlanAdmissionInput,
+): PlanAdmissionResolution {
+  const activePlans = plans.filter((plan) => !isTerminalPlanContractStatus(plan.status));
+  const normalizedScopeKey = normalizePlanScopeKey(input.scopeKey);
+  const requirementId = input.requirementId?.trim() || undefined;
+  const requirementPlans = requirementId
+    ? activePlans.filter((candidate) => candidate.requirementId === requirementId)
+    : [];
+  const relatedPlanId = input.relatedPlanId?.trim() || undefined;
+  const explicitlyRelatedPlan = relatedPlanId
+    ? activePlans.find((candidate) => candidate.planId === relatedPlanId)
+    : undefined;
+  const relatedPlan = explicitlyRelatedPlan && (!requirementId || explicitlyRelatedPlan.requirementId === requirementId)
+    ? explicitlyRelatedPlan
+    : !relatedPlanId && requirementPlans.length === 1 ? requirementPlans[0] : undefined;
+  const exactScopeAuthority = normalizedScopeKey
+    ? activePlans.find((candidate) => candidate.scopeKey === normalizedScopeKey)
+    : undefined;
+
+  // An explicit extension is a serial replan, not a second active Plan. Resolve
+  // it before exact-scope reuse so a successor may retain the predecessor scope.
+  // If another Plan owns the requested successor scope, preserve that authority.
+  if (input.planRelation === 'extend') {
+    if (!relatedPlan) {
+      return {
+        admissionDecision: 'resolution_required',
+        resolutionRequired: true,
+        reason: 'extension_target_required',
+        normalizedScopeKey,
+        candidates: (requirementPlans.length > 0 ? requirementPlans : activePlans).slice(0, 8),
+        allowedPlanRelations: PLAN_ADMISSION_RELATIONS,
+      };
+    }
+    if (exactScopeAuthority && exactScopeAuthority.planId !== relatedPlan.planId) {
+      return {
+        admissionDecision: 'reuse_existing',
+        resolutionRequired: false,
+        reason: 'exact_scope_authority',
+        normalizedScopeKey,
+        plan: exactScopeAuthority,
+        candidates: [exactScopeAuthority],
+      };
+    }
+    return {
+      admissionDecision: 'extend_existing',
+      resolutionRequired: false,
+      reason: 'extend_existing',
+      normalizedScopeKey,
+      plan: relatedPlan,
+      candidates: requirementPlans.length > 0 ? requirementPlans.slice(0, 8) : [relatedPlan],
+    };
+  }
+
+  if (exactScopeAuthority) {
+    return {
+      admissionDecision: 'reuse_existing',
+      resolutionRequired: false,
+      reason: 'exact_scope_authority',
+      normalizedScopeKey,
+      plan: exactScopeAuthority,
+      candidates: [exactScopeAuthority],
+    };
+  }
+
+  if (requirementPlans.length > 0 && !input.planRelation) {
+    return {
+      admissionDecision: 'resolution_required',
+      resolutionRequired: true,
+      reason: 'requirement_relation_required',
+      normalizedScopeKey,
+      candidates: requirementPlans.slice(0, 8),
+      allowedPlanRelations: PLAN_ADMISSION_RELATIONS,
+    };
+  }
+
+  return {
+    admissionDecision: 'create_new',
+    resolutionRequired: false,
+    reason: 'create_new',
+    normalizedScopeKey,
+    candidates: requirementPlans.slice(0, 8),
+  };
+}
+
+/**
+ * Short per-repository semantic admission critical section. The fixed task key
+ * keeps admission independent from repository/worktree execution locks while
+ * still coordinating competing controller processes for the same repository.
+ */
+const planAdmissionLockKey = (repoId: string) => ({
+  scope: 'task' as const,
+  repoId,
+  taskId: 'semantic-plan-admission',
+});
+
+export function withPlanAdmissionLock<T>(
+  options: { controllerHome?: string; repoId?: string },
+  operation: () => T,
+): T {
+  if (!options.controllerHome?.trim() || !options.repoId?.trim()) return operation();
+  return withControllerLock(
+    options.controllerHome,
+    planAdmissionLockKey(options.repoId),
+    'semantic-plan-admission',
+    operation,
+  );
+}
+
+/** Gateway-facing admission waits briefly for a competing controller to finish
+ * its tiny create/approve decision, then re-reads canonical state under lock. */
+export async function withPlanAdmissionLockAsync<T>(
+  options: { controllerHome?: string; repoId?: string },
+  operation: () => T | Promise<T>,
+): Promise<T> {
+  if (!options.controllerHome?.trim() || !options.repoId?.trim()) return await operation();
+  return await withControllerLockAsync(
+    options.controllerHome,
+    planAdmissionLockKey(options.repoId),
+    'semantic-plan-admission',
+    async () => await operation(),
+    undefined,
+    500,
+  );
+}
+
+const primaryWorkAdmissionLockKey = (repoId: string) => ({
+  scope: 'task' as const,
+  repoId,
+  taskId: 'semantic-primary-work-admission',
+});
+
+/**
+ * Primary Work admission protects only canonical ownership resolution and
+ * persistence. It must never span workspace materialization, dependency prep,
+ * checks, worker launch, or the Work execution lifetime.
+ */
+export function withPrimaryWorkAdmissionLock<T>(
+  options: { controllerHome?: string; repoId?: string },
+  operation: () => T,
+): T {
+  if (!options.controllerHome?.trim() || !options.repoId?.trim()) return operation();
+  return withControllerLock(
+    options.controllerHome,
+    primaryWorkAdmissionLockKey(options.repoId),
+    'semantic-primary-work-admission',
+    operation,
+  );
+}
+
+/** Gateway callers wait briefly for a competing admission, then re-read the
+ * canonical Plan/Work state while holding the same short critical section. */
+export async function withPrimaryWorkAdmissionLockAsync<T>(
+  options: { controllerHome?: string; repoId?: string },
+  operation: () => T | Promise<T>,
+): Promise<T> {
+  if (!options.controllerHome?.trim() || !options.repoId?.trim()) return await operation();
+  return await withControllerLockAsync(
+    options.controllerHome,
+    primaryWorkAdmissionLockKey(options.repoId),
+    'semantic-primary-work-admission',
+    async () => await operation(),
+    undefined,
+    500,
+  );
+}

package/src/runtime/control-plane/facade/suggested-actions.ts

@@ -11,10 +11,13 @@ function expectedActionRisk(action: SuggestedNextAction): SuggestedNextAction['r
     case 'delegate':
     case 'controller_claim':
     case 'controller_release':
+    case 'controller_disposition':
     case 'launcher_start':
+    case 'requirement_create':
     case 'schedule_create':
     case 'schedule_pause':
     case 'schedule_resume':
+    case 'schedule_delete':
     case 'schedule_trigger':
       return 'workspace_write';
     case 'controller_get_owner':
@@ -26,6 +29,7 @@ function expectedActionRisk(action: SuggestedNextAction): SuggestedNextAction['r
     case 'plan_list':
       return 'readonly';
     case 'plan_approve':
+    case 'plan_accept_step':
     case 'plan_supersede':
       return 'workspace_write';
     case 'finalize':
@@ -40,7 +44,7 @@ const ALLOWED_FACADE_OPERATIONS: Record<FacadeTool, readonly string[]> = {
   rh_status: ['list', 'get', 'repair'],
   rh_inbox: ['list', 'get', 'ack', 'accept', 'resolve', 'dismiss', 'create'],
   rh_context: ['list', 'get', 'search'],
-  rh_work: ['start', 'continue', 'verify', 'repair', 'finalize', 'stop', 'delegate', 'controller_claim', 'controller_release', 'controller_get_owner', 'launcher_start', 'plan_create', 'plan_get', 'plan_list', 'plan_approve', 'plan_supersede', 'schedule_create', 'schedule_list', 'schedule_get', 'schedule_pause', 'schedule_resume', 'schedule_trigger'],
+  rh_work: ['start', 'continue', 'verify', 'repair', 'finalize', 'stop', 'delegate', 'controller_claim', 'controller_release', 'controller_disposition', 'controller_get_owner', 'launcher_start', 'requirement_create', 'plan_create', 'plan_get', 'plan_list', 'plan_approve', 'plan_accept_step', 'plan_supersede', 'schedule_create', 'schedule_list', 'schedule_get', 'schedule_pause', 'schedule_resume', 'schedule_delete', 'schedule_trigger'],
 };
 
 export interface SuggestedActionValidationOptions {

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

@@ -1,13 +1,14 @@
 import type { ProcessCheckReceiptEvidence } from '../../evidence/process-check-receipt';
 import type { CompletionReceipt as RepositoryCompletionReceipt } from '../../../cli/controller/types';
 import type { AccessMode } from '../governance/access-policy';
-import { decideRoute, type RouteDecision, type RoutePolicyInput } from '../routing/route-policy';
+import { decideRoute, type ExplicitTaskMode, type RouteDecision, type RoutePolicyInput } from '../routing/route-policy';
 
 export const EXECUTION_MODES = ['direct_control', 'goal_workloop', 'handoff_only'] as const;
 export type ExecutionMode = (typeof EXECUTION_MODES)[number];
 
 export const FACADE_TOOLS = ['rh_access', 'rh_status', 'rh_inbox', 'rh_context', 'rh_work'] as const;
 export type FacadeTool = (typeof FACADE_TOOLS)[number];
+export type CapabilityExecutionSurface = FacadeTool | 'plugin_action_execute';
 
 export const FACADE_STATUSES = ['ok', 'blocked', 'failed', 'approval_required', 'not_found'] as const;
 export type FacadeStatus = (typeof FACADE_STATUSES)[number];
@@ -119,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',
@@ -136,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
@@ -156,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;
 }
 
@@ -196,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(
@@ -347,12 +399,16 @@ 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. */
   conflictsWithThinHarnessPolicy?: boolean;
   /** True when the change alters the default routing or execution mode visible to users. */
   changesDefaultExecutionStrategy?: boolean;
+  /** Repository-change delivery must publish the exact integrated revision before Work terminalization. */
+  remoteDeliveryRequired?: boolean;
 }
 
 export interface WorkContractDriverPolicy {
@@ -476,6 +532,22 @@ export interface WorkContract {
   planStepId?: string;
   planSourceRevision?: string;
   scopeSummary?: string;
+  /**
+   * Discovery evidence, never an authorization boundary. Initial guesses,
+   * inspected paths, and observed changes remain distinct so early retrieval
+   * cannot masquerade as complete implementation scope.
+   */
+  scopeEvidence?: {
+    initialLikelyPaths: string[];
+    inspectedPaths: string[];
+    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[];
   checks: string[];
@@ -495,13 +567,12 @@ export interface WorkContract {
   continuationPrompt?: string;
   worktreeRef?: string;
   workerRef?: string;
-  /** Stable idempotency key when this Work was accepted via work_submit. */
   requestId?: string;
-  /** Accepted Kernel operation envelope. Does not imply ExecutionJob creation. */
+  /** Typed execution metadata; it does not imply ExecutionJob creation. */
   submittedOperation?: SubmittedWorkOperation;
 }
 
-/** Operation metadata retained on WorkContracts accepted through work_submit. */
+/** Typed execution metadata retained on execution-child WorkContracts. */
 export interface SubmittedWorkOperation {
   name: string;
   semanticKey: string;
@@ -630,7 +701,7 @@ export interface CapabilityDescriptor {
   group: CapabilityGroup;
   operationClass: CapabilityOperationClass;
   risk: CapabilityRisk;
-  exposedVia: FacadeTool;
+  exposedVia: CapabilityExecutionSurface;
   schemaExposure: CapabilitySchemaExposure;
   summary: string;
 }
@@ -639,6 +710,7 @@ export interface CapabilityGroupSummary {
   group: CapabilityGroup;
   capabilityCount: number;
   domains: CapabilityDomain[];
+  executionSurfaces: CapabilityExecutionSurface[];
   facadeTools: FacadeTool[];
   operationClasses: CapabilityOperationClass[];
   risks: CapabilityRisk[];
@@ -664,9 +736,14 @@ 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;
+  explicitMode?: ExplicitTaskMode;
   needsDependencies?: boolean;
   requiresRecovery?: boolean;
   /** True only when the user explicitly requested an agent/worker executor. Complexity alone must not enable workers. */
@@ -717,6 +794,7 @@ export function selectExecutionMode(input: ExecutionModeSelectionInput): Executi
       requiresInvestigation: input.requiresInvestigation,
       requiresLongRunningChecks: input.requiresLongRunningChecks,
       requiresParallelism: input.requiresParallelism,
+      explicitMode: input.explicitMode,
       needsDependencies: input.needsDependencies,
       agentRequested: input.requiresWorker,
     },
@@ -725,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,