agentic-orchestrator 0.1.27 → 0.2.0

package/apps/control-plane/src/application/services/plan-service.ts

@@ -1,15 +1,23 @@
-import { atomicWriteJson, nowIso, readJson } from '../../core/fs.js';
-import { detectPlanCollisions } from '../../core/collisions.js';
+import path from 'node:path';
+import { atomicWriteFile, atomicWriteJson, nowIso, readJson } from '../../core/fs.js';
+import {
+  collectCollisionFeatureIds,
+  detectPlanCollisions,
+  hasContractCollisions,
+} from '../../core/collisions.js';
 import { sortResourcesDeterministically } from '../../core/path-rules.js';
 import { ERROR_CODES } from '../../core/error-codes.js';
 import { fail } from '../../core/response.js';
 import { GATE_RESULT, STATUS } from '../../core/constants.js';
 import { GateSelectionService } from './gate-selection-service.js';
+import { CollisionOverrideService } from './collision-override-service.js';
 import {
   getUnresolvedDeps,
   detectCircularDependency,
   addToDepBlocked,
 } from './dependency-scheduler-service.js';
+import type { VerifiedManifest } from '../../core/intake-artifacts.js';
+import { validatePlanTraceAgainstObligationIds } from '../../core/intake-artifacts.js';
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type AnyRecord = Record<string, any>;
@@ -41,6 +49,159 @@ function readHeldLocks(frontMatter: AnyRecord): string[] {
   return asArray<string>(locks.held).filter((item) => typeof item === 'string');
 }
 
+function asStringArray(value: unknown): string[] {
+  return asArray<string>(value).filter((item): item is string => typeof item === 'string');
+}
+
+function formatBulletSection(values: string[]): string[] {
+  return values.length > 0 ? values.map((value) => `- ${value}`) : ['- None'];
+}
+
+function asVerifiedManifest(value: unknown): VerifiedManifest | null {
+  if (!value || typeof value !== 'object') {
+    return null;
+  }
+  const record = value as Record<string, unknown>;
+  if (
+    typeof record.feature_id !== 'string' ||
+    typeof record.manifest_version !== 'number' ||
+    record.artifact_type !== 'verified' ||
+    !Array.isArray(record.obligations)
+  ) {
+    return null;
+  }
+  return record as unknown as VerifiedManifest;
+}
+
+function readIntakeStatus(frontMatter: AnyRecord): string | null {
+  const intake = readObjectField(frontMatter, 'intake');
+  return typeof intake.status === 'string' ? intake.status : null;
+}
+
+function formatNumberedSection(values: string[]): string[] {
+  return values.length > 0
+    ? values.map((value, index) => `${index + 1}. ${value}`)
+    : ['1. Keep execution scoped to the accepted plan artifacts.'];
+}
+
+function describePlannedSteps(plan: AnyRecord): string[] {
+  const files = readObjectField(plan, 'files');
+  const create = asStringArray(files.create);
+  const modify = asStringArray(files.modify);
+  const remove = asStringArray(files.delete);
+  const acceptanceCriteria = asStringArray(plan.acceptance_criteria);
+  const steps: string[] = [];
+
+  if (create.length > 0) {
+    steps.push(`Create the planned files: ${create.join(', ')}.`);
+  }
+  if (modify.length > 0) {
+    steps.push(`Modify the planned files: ${modify.join(', ')}.`);
+  }
+  if (remove.length > 0) {
+    steps.push(`Delete the planned files: ${remove.join(', ')}.`);
+  }
+  if (acceptanceCriteria.length > 0) {
+    steps.push(`Satisfy the acceptance criteria: ${acceptanceCriteria.join('; ')}.`);
+  }
+
+  return steps;
+}
+
+export function renderPlanMarkdown(
+  featureId: string,
+  plan: AnyRecord,
+  frontMatter: AnyRecord,
+): string {
+  const files = readObjectField(plan, 'files');
+  const contracts = readObjectField(plan, 'contracts');
+  const planVersion =
+    typeof plan.plan_version === 'number' && Number.isFinite(plan.plan_version)
+      ? String(plan.plan_version)
+      : 'unknown';
+  const revisionOf =
+    typeof plan.revision_of === 'number' && Number.isFinite(plan.revision_of)
+      ? String(plan.revision_of)
+      : 'none';
+  const status =
+    typeof frontMatter.status === 'string' && frontMatter.status.trim().length > 0
+      ? frontMatter.status.trim()
+      : 'unknown';
+  const branch =
+    typeof frontMatter.branch === 'string' && frontMatter.branch.trim().length > 0
+      ? frontMatter.branch.trim()
+      : 'unknown';
+  const worktreePath =
+    typeof frontMatter.worktree_path === 'string' && frontMatter.worktree_path.trim().length > 0
+      ? frontMatter.worktree_path.trim()
+      : 'unknown';
+  const gateProfile =
+    typeof frontMatter.gate_profile === 'string' && frontMatter.gate_profile.trim().length > 0
+      ? frontMatter.gate_profile.trim()
+      : typeof plan.gate_profile === 'string' && plan.gate_profile.trim().length > 0
+        ? plan.gate_profile.trim()
+        : 'default';
+  const summary =
+    typeof plan.summary === 'string' && plan.summary.trim().length > 0
+      ? plan.summary.trim()
+      : 'Pending planner summary.';
+
+  return [
+    `# Plan for ${featureId}`,
+    '',
+    `Plan version: ${planVersion}`,
+    `Revision of: ${revisionOf}`,
+    `Status: ${status}`,
+    `Gate profile: ${gateProfile}`,
+    `Updated at: ${nowIso()}`,
+    '',
+    '## Summary',
+    summary,
+    '',
+    '## Current State',
+    `- Status: ${status}`,
+    `- Branch: ${branch}`,
+    `- Worktree: ${worktreePath}`,
+    '',
+    '## Step-by-Step Plan',
+    ...formatNumberedSection(describePlannedSteps(plan)),
+    '',
+    '## Allowed Areas',
+    ...formatBulletSection(asStringArray(plan.allowed_areas)),
+    '',
+    '## Forbidden Areas',
+    ...formatBulletSection(asStringArray(plan.forbidden_areas)),
+    '',
+    '## Files',
+    ...formatBulletSection([
+      `Create: ${asStringArray(files.create).join(', ') || 'None'}`,
+      `Modify: ${asStringArray(files.modify).join(', ') || 'None'}`,
+      `Delete: ${asStringArray(files.delete).join(', ') || 'None'}`,
+    ]),
+    '',
+    '## Contracts',
+    ...formatBulletSection([
+      `OpenAPI: ${typeof contracts.openapi === 'string' ? contracts.openapi : 'none'}`,
+      `Events: ${typeof contracts.events === 'string' ? contracts.events : 'none'}`,
+      `Database: ${typeof contracts.db === 'string' ? contracts.db : 'none'}`,
+    ]),
+    '',
+    '## Acceptance Criteria',
+    ...formatBulletSection(asStringArray(plan.acceptance_criteria)),
+    '',
+    '## Risks',
+    ...formatBulletSection(asStringArray(plan.risk)),
+    '',
+    '## Gate Targets',
+    ...formatBulletSection(asStringArray(plan.gate_targets)),
+    '',
+    '## Comparison Baseline',
+    `- Future planning, build, and QA states must be reconciled against this plan.md and plan.json version ${planVersion}.`,
+    '- Keep plan.md and plan.json aligned when the plan changes.',
+    '',
+  ].join('\n');
+}
+
 /**
  * Port interface for plan operations.
  *
@@ -203,10 +364,12 @@ export interface PlanServicePort {
 export class PlanService {
   private readonly port: PlanServicePort;
   private readonly gateSelectionService: GateSelectionService;
+  private readonly collisionOverrideService: CollisionOverrideService;
 
   constructor(port: PlanServicePort) {
     this.port = port;
     this.gateSelectionService = new GateSelectionService(port);
+    this.collisionOverrideService = new CollisionOverrideService(port);
   }
 
   /**
@@ -248,9 +411,11 @@ export class PlanService {
    */
   async collectAcceptedPlans(excludeFeatureId: string | null = null): Promise<AnyRecord[]> {
     const specs = await this.port.featureDiscoverSpecs();
+    const index = await this.port.readIndex();
+    const merged = new Set(asArray<string>(index.merged));
     const plans: AnyRecord[] = [];
     for (const item of specs.data.specs) {
-      if (item.feature_id === excludeFeatureId) {
+      if (item.feature_id === excludeFeatureId || merged.has(item.feature_id)) {
         continue;
       }
       const plan = await readJson(this.port.planPath(item.feature_id), null);
@@ -443,6 +608,56 @@ export class PlanService {
       return collisionResult;
     }
 
+    const context = {
+      actorType: 'system',
+      actorId: 'plan-service',
+    };
+    const hasContracts = hasContractCollisions(collisionResult.collisions);
+    const collisionFingerprint = collisionResult.fingerprint ?? '';
+    const collisionRecord = await this.collisionOverrideService.recordCollision({
+      featureId,
+      sourceTool: Number.isInteger(plan.revision_of) ? 'plan.update' : 'plan.submit',
+      planVersion: plan.plan_version,
+      collisionFingerprint,
+      collisions: collisionResult.collisions,
+      planSnapshot: plan,
+      resolution: hasContracts
+        ? 'rejected'
+        : policy.collision_policy === 'block'
+          ? 'blocked'
+          : 'rejected',
+      context,
+    });
+    const approval = hasContracts
+      ? {
+          approved: false,
+          matched_overrides: [],
+          blocking_feature_ids: normalizeSet(
+            collisionResult.collisions.contracts.map((entry) => entry.with_feature_id),
+          ),
+        }
+      : await this.collisionOverrideService.evaluateApprovals(
+          featureId,
+          collisionResult.collisions,
+          context,
+        );
+
+    if (approval.approved) {
+      await this.collisionOverrideService.markCollisionRecordResolution(
+        collisionRecord.collision_id,
+        'override_applied',
+        {
+          override_id: approval.matched_overrides[0]?.override_id,
+          resolved_at: nowIso(),
+          note: `Applied overrides for ${approval.matched_overrides
+            .map((override) => override.override_id)
+            .join(', ')}`,
+        },
+        context,
+      );
+      return collisionResult;
+    }
+
     if (policy.collision_policy === 'reject') {
       throw {
         normalizedResponse: fail(
@@ -452,21 +667,21 @@ export class PlanService {
             feature_id: featureId,
             collisions: collisionResult.collisions,
             collision_fingerprint: collisionResult.fingerprint,
-            conflicting_feature_ids: normalizeSet(
-              collisionResult.collisions.files
-                .map((x) => x.with_feature_id)
-                .concat(
-                  collisionResult.collisions.areas.map((x) => x.with_feature_id),
-                  collisionResult.collisions.contracts.map((x) => x.with_feature_id),
-                ),
-            ),
+            conflicting_feature_ids: collectCollisionFeatureIds(collisionResult.collisions),
             retryable: false,
             requires_human: true,
-            suggested_next_actions: [
-              'Acquire relevant lock and resubmit',
-              'Revise plan scope to avoid overlap',
-              'Create shared prerequisite feature',
-            ],
+            suggested_next_actions: hasContracts
+              ? [
+                  'Acquire relevant lock and resubmit',
+                  'Revise plan scope to avoid shared contract changes',
+                  'Create shared prerequisite feature',
+                ]
+              : [
+                  `Approve the expected overlap with aop collision --allow --feature-id ${featureId} --with-feature-id <feature-id> --reason "<text>"`,
+                  'Acquire relevant lock and resubmit',
+                  'Revise plan scope to avoid overlap',
+                  'Create shared prerequisite feature',
+                ],
           },
         ),
       };
@@ -605,10 +820,11 @@ export class PlanService {
    * console.log(`Plan accepted: version ${result.data.plan_version}`);
    * ```
    */
-  async planSubmit(
+  private async submitPlan(
     featureId: string | null,
     plan: AnyRecord | null,
     expectedVersion: number | null = null,
+    sourceTool: 'plan.submit' | 'plan.update' = 'plan.submit',
   ): Promise<{ data: { feature_id: string | null; accepted: boolean; plan_version: number } }> {
     if (!plan || typeof plan !== 'object') {
       throw {
@@ -635,6 +851,7 @@ export class PlanService {
     }
 
     const state = await this.port.readState(featureId);
+    await this.assertVerifiedManifestReady(featureId, state.frontMatter, plan);
     const resolvedProfile = this.gateSelectionService.resolveProfileFromState(
       state.frontMatter.gate_profile,
     );
@@ -656,13 +873,18 @@ export class PlanService {
     const existing = await readJson(this.port.planPath(featureId), null);
     this.validatePlanRevisionRules(existing, canonicalizedPlan.plan, expectedVersion);
 
-    await this.checkPlanCollision(featureId, canonicalizedPlan.plan);
+    await this.checkPlanCollision(
+      featureId,
+      sourceTool === 'plan.update'
+        ? { ...canonicalizedPlan.plan, revision_of: canonicalizedPlan.plan.revision_of }
+        : canonicalizedPlan.plan,
+    );
 
     await this.port.withFeatureLock(featureId, async () => {
       await atomicWriteJson(this.port.planPath(featureId), canonicalizedPlan.plan);
     });
 
-    await this.port.updateState(featureId, null, (frontMatter, body) => {
+    const updatedFrontMatter = await this.port.updateState(featureId, null, (frontMatter, body) => {
       const nextStatus =
         frontMatter.status === STATUS.PLANNING || frontMatter.status === STATUS.BLOCKED
           ? STATUS.BUILDING
@@ -685,6 +907,19 @@ export class PlanService {
       });
     });
 
+    const planMarkdownPath = path.join(path.dirname(this.port.planPath(featureId)), 'plan.md');
+    await this.port.withFeatureLock(featureId, async () => {
+      await atomicWriteFile(
+        planMarkdownPath,
+        renderPlanMarkdown(featureId, canonicalizedPlan.plan, updatedFrontMatter),
+      );
+    });
+
+    await this.collisionOverrideService.clearResolvedCollisionRecords(featureId, planVersion, {
+      actorType: 'system',
+      actorId: 'plan-service',
+    });
+
     return {
       data: {
         feature_id: featureId,
@@ -694,6 +929,14 @@ export class PlanService {
     };
   }
 
+  async planSubmit(
+    featureId: string | null,
+    plan: AnyRecord | null,
+    expectedVersion: number | null = null,
+  ): Promise<{ data: { feature_id: string | null; accepted: boolean; plan_version: number } }> {
+    return await this.submitPlan(featureId, plan, expectedVersion, 'plan.submit');
+  }
+
   /**
    * Submits versioned plan revision with full revalidation.
    *
@@ -721,6 +964,79 @@ export class PlanService {
     expectedPlanVersion: number | null,
     plan: AnyRecord | null,
   ) {
-    return await this.planSubmit(featureId, plan, expectedPlanVersion);
+    return await this.submitPlan(featureId, plan, expectedPlanVersion, 'plan.update');
+  }
+
+  private async readVerifiedManifest(featureId: string): Promise<VerifiedManifest | null> {
+    const manifestPath = path.join(
+      path.dirname(this.port.planPath(featureId)),
+      'spec.manifest.verified.json',
+    );
+    const rawManifest = await readJson(manifestPath, null);
+    if (!rawManifest) {
+      return null;
+    }
+    const validation = await this.port.validateSchema(
+      'spec.manifest.verified.schema.json',
+      rawManifest,
+    );
+    if (!validation.valid) {
+      return null;
+    }
+    return asVerifiedManifest(rawManifest);
+  }
+
+  private async assertVerifiedManifestReady(
+    featureId: string,
+    frontMatter: AnyRecord,
+    plan: AnyRecord,
+  ): Promise<void> {
+    const verifiedManifest = await this.readVerifiedManifest(featureId);
+    const intakeStatus = readIntakeStatus(frontMatter);
+    if (!verifiedManifest) {
+      if (
+        frontMatter.status === STATUS.INTAKE ||
+        intakeStatus === 'verified' ||
+        intakeStatus === 'in_progress' ||
+        intakeStatus === 'awaiting_input'
+      ) {
+        throw {
+          normalizedResponse: fail(
+            ERROR_CODES.VERIFIED_MANIFEST_REQUIRED,
+            'verified manifest is required before execution planning can begin',
+            {
+              feature_id: featureId,
+              retryable: false,
+              requires_human: true,
+            },
+          ),
+        };
+      }
+      return;
+    }
+
+    const traceValidation = validatePlanTraceAgainstObligationIds(
+      plan,
+      verifiedManifest.obligations.map((obligation) => obligation.obligation_id),
+    );
+
+    if (!traceValidation.valid) {
+      throw {
+        normalizedResponse: fail(
+          ERROR_CODES.PLAN_TRACE_INVALID,
+          'plan trace does not match the verified manifest contract',
+          {
+            feature_id: featureId,
+            missing_obligation_ids: traceValidation.missing_obligation_ids,
+            unknown_obligation_ids: traceValidation.unknown_obligation_ids,
+            duplicate_obligation_ids: traceValidation.duplicate_obligation_ids,
+            invalid_mappings: traceValidation.invalid_mappings,
+            invalid_mapping_details: traceValidation.invalid_mapping_details,
+            retryable: false,
+            requires_human: true,
+          },
+        ),
+      };
+    }
   }
 }