agentic-orchestrator 0.1.23 → 0.1.24

package/README.md

@@ -636,15 +636,15 @@ Files the runtime creates/maintains:
 
 ### Schema mapping
 
-| Runtime file                                       | Schema file                                              | Required/expected essentials                                                                                                                                                                    |
-| -------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `.aop/features/<feature_id>/plan.json`             | `agentic/orchestrator/schemas/plan.schema.json`          | `feature_id`, `plan_version`, `summary`, `allowed_areas`, `forbidden_areas`, `base_ref`, `files.{create,modify,delete}`, `contracts.{openapi,events,db}`, `acceptance_criteria`, `gate_profile` |
-| `.aop/features/<feature_id>/state.md` front matter | `agentic/orchestrator/schemas/state.schema.json`         | `feature_id`, `version`, `branch`, `worktree_path`, `status`, `gate_profile`, `gates`, `locks.held`, `collisions`, `cluster`, `role_status`, `last_updated`                                     |
-| `.aop/features/index.json`                         | `agentic/orchestrator/schemas/index.schema.json`         | `version`, `active`, `blocked`, `merged`, `locks`, `lock_leases`, `blocked_queue`, `runtime_sessions.{run_id,orchestrator_session_id,owner_instance_id,lease_expires_at,feature_sessions}`      |
-| `config/agentic/orchestrator/gates.yaml`           | `agentic/orchestrator/schemas/gates.schema.json`         | `version`, `profiles.<profile>.modes.<mode>[{name,cmd,...}]`, optional parser/threshold metadata                                                                                                |
-| `config/agentic/orchestrator/policy.yaml`          | `agentic/orchestrator/schemas/policy.schema.json`        | commit/merge policy, patch policy, lock config, collision policy, path rules, execution policy, RBAC, Nx/Vitest implementation constraints                                                      |
-| `config/agentic/orchestrator/agents.yaml`          | `agentic/orchestrator/schemas/agents.schema.json`        | `version`, `roles`, `missing_prompt_behavior`, optional runtime defaults                                                                                                                        |
-| `.aop/features/<feature_id>/qa_test_index.json`    | `agentic/orchestrator/schemas/qa_test_index.schema.json` | `feature_id`, `version`, `source_diff_ref`, `items[]` with path/hunks/required_tests/status                                                                                                     |
+| Runtime file                                       | Schema file                                              | Required/expected essentials                                                                                                                                                                                              |
+| -------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.aop/features/<feature_id>/plan.json`             | `agentic/orchestrator/schemas/plan.schema.json`          | `feature_id`, `plan_version`, `summary`, `allowed_areas`, `forbidden_areas`, `base_ref`, `files.{create,modify,delete}`, `contracts.{openapi,events,db}`, `acceptance_criteria`, optional `gate_targets` (planner intent) |
+| `.aop/features/<feature_id>/state.md` front matter | `agentic/orchestrator/schemas/state.schema.json`         | `feature_id`, `version`, `branch`, `worktree_path`, `status`, `gate_profile`, `gates`, `locks.held`, `collisions`, `cluster`, `role_status`, `last_updated`                                                               |
+| `.aop/features/index.json`                         | `agentic/orchestrator/schemas/index.schema.json`         | `version`, `active`, `blocked`, `merged`, `locks`, `lock_leases`, `blocked_queue`, `runtime_sessions.{run_id,orchestrator_session_id,owner_instance_id,lease_expires_at,feature_sessions}`                                |
+| `config/agentic/orchestrator/gates.yaml`           | `agentic/orchestrator/schemas/gates.schema.json`         | `version`, `profiles.<profile>.modes.<mode>[{name,cmd,...}]`, optional parser/threshold metadata                                                                                                                          |
+| `config/agentic/orchestrator/policy.yaml`          | `agentic/orchestrator/schemas/policy.schema.json`        | commit/merge policy, patch policy, lock config, collision policy, gate selection defaults/healing toggles, path rules, execution policy, RBAC, Nx/Vitest implementation constraints                                       |
+| `config/agentic/orchestrator/agents.yaml`          | `agentic/orchestrator/schemas/agents.schema.json`        | `version`, `roles`, `missing_prompt_behavior`, optional runtime defaults                                                                                                                                                  |
+| `.aop/features/<feature_id>/qa_test_index.json`    | `agentic/orchestrator/schemas/qa_test_index.schema.json` | `feature_id`, `version`, `source_diff_ref`, `items[]` with path/hunks/required_tests/status                                                                                                                               |
 
 ### Important operational notes
 

package/agentic/orchestrator/defaults/policy.defaults.yaml

@@ -32,6 +32,10 @@ required_modes:
   - fast
   - full
 required_merge_mode: merge
+gate_selection:
+  default_profile: default
+  auto_heal_invalid_state_profile: true
+  legacy_mode_profile_compat: true
 collision_policy: reject
 config_precedence:
   policy_hard_constraints:

package/agentic/orchestrator/policy.yaml

@@ -32,6 +32,10 @@ required_modes:
   - fast
   - full
 required_merge_mode: merge
+gate_selection:
+  default_profile: default
+  auto_heal_invalid_state_profile: true
+  legacy_mode_profile_compat: true
 collision_policy: reject
 config_precedence:
   policy_hard_constraints:

package/agentic/orchestrator/prompts/planner.system.md

@@ -19,11 +19,11 @@ Every `PLAN_SUBMISSION` must include ALL of the following fields in `plan_json`:
 | `files`               | object           | `{ "create": [...], "modify": [...], "delete": [...] }` — all three arrays required, may be empty |
 | `contracts`           | object           | `{ "openapi": "none"\|"modify", "events": "none"\|"modify", "db": "none"\|"migration" }`          |
 | `acceptance_criteria` | string[] (min 1) | Conditions that must all be met before merge                                                      |
-| `gate_profile`        | string           | Gate profile name (e.g. `"fast"` or `"full"`)                                                     |
 
 Optional fields (with types):
 
 - `gate_targets`: `string[]` — explicit gate mode names to run
+- `gate_profile`: `string` — deprecated compatibility field; runtime owns profile selection and may ignore or rewrite this value
 - `risk`: **`string[]`** — list of risk statements (e.g. `["Schema migration may require downtime"]`). **Must be an array, never a plain string.**
 - `revision_of`: `integer` — plan_version this revises
 - `revision_reason`: `string` — why the plan was revised
@@ -48,7 +48,7 @@ Optional fields (with types):
     },
     "contracts": { "openapi": "none", "events": "none", "db": "none" },
     "acceptance_criteria": ["All tests pass at ≥90% coverage", "npm run lint passes"],
-    "gate_profile": "fast"
+    "gate_targets": ["fast", "full"]
   }
 }
 ```

package/agentic/orchestrator/schemas/gates.schema.json

@@ -12,7 +12,7 @@
     },
     "profiles": {
       "type": "object",
-      "description": "Named gate profiles. A feature's active profile is recorded in plan.gate_profile and referenced by the gate service when running checks.",
+      "description": "Named gate profiles. Runtime gate execution resolves the active profile from state.gate_profile (system-owned), with deterministic policy fallback.",
       "additionalProperties": {
         "type": "object",
         "description": "A named gate profile containing one or more execution modes.",

package/agentic/orchestrator/schemas/plan.schema.json

@@ -13,8 +13,7 @@
     "base_ref",
     "files",
     "contracts",
-    "acceptance_criteria",
-    "gate_profile"
+    "acceptance_criteria"
   ],
   "properties": {
     "feature_id": {
@@ -121,7 +120,7 @@
     "gate_profile": {
       "type": "string",
       "minLength": 1,
-      "description": "Name of the gates profile to apply to this feature. Written to state.gate_profile on plan acceptance."
+      "description": "Deprecated planner compatibility field. Planner-supplied gate_profile is advisory only and may be ignored/re-written by runtime canonicalization."
     },
     "gate_targets": {
       "type": "array",
@@ -130,7 +129,7 @@
         "minLength": 1
       },
       "minItems": 1,
-      "description": "Optional explicit list of gate mode names to run. When omitted the profile's full mode set is used."
+      "description": "Optional planner-authored list of gate mode names to prioritize. Runtime profile selection remains system-owned via state.gate_profile."
     },
     "risk": {
       "type": "array",

package/agentic/orchestrator/schemas/policy.schema.json

@@ -166,6 +166,26 @@
       "type": "string",
       "description": "Additional gate mode that must have passed immediately before merge (typically 'merge'), on top of required_modes."
     },
+    "gate_selection": {
+      "type": "object",
+      "description": "Deterministic gate profile selection policy. Runtime owns profile resolution from state/policy rather than planner input.",
+      "additionalProperties": false,
+      "properties": {
+        "default_profile": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Preferred default gate profile key from gates.profiles. If invalid/missing at runtime, deterministic fallback is used."
+        },
+        "auto_heal_invalid_state_profile": {
+          "type": "boolean",
+          "description": "When true, invalid or missing state.gate_profile values are auto-healed to resolved profile on feature touch paths."
+        },
+        "legacy_mode_profile_compat": {
+          "type": "boolean",
+          "description": "When true, planner legacy gate_profile mode tokens (fast/full/merge) are canonicalized into gate_targets for compatibility."
+        }
+      }
+    },
     "collision_policy": {
       "type": "string",
       "description": "'reject' immediately fails a colliding plan submission; 'block' queues the plan in index.blocked_queue until the conflicting feature merges.",

package/agentic/orchestrator/schemas/state.schema.json

@@ -43,7 +43,7 @@
     },
     "gate_profile": {
       "type": "string",
-      "description": "Name of the gates profile to use for this feature. Written from plan.gate_profile on plan submission."
+      "description": "System-resolved gates profile for this feature. Runtime resolves and heals this from policy/gates config; planner plan input is not authoritative."
     },
     "gates": {
       "type": "object",

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

@@ -0,0 +1,267 @@
+import { ERROR_CODES } from '../../core/error-codes.js';
+import { fail } from '../../core/response.js';
+
+type AnyRecord = Record<string, unknown>;
+
+function asRecord(value: unknown): AnyRecord {
+  return value && typeof value === 'object' && !Array.isArray(value) ? (value as AnyRecord) : {};
+}
+
+function asNonEmptyString(value: unknown): string | null {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function asStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  const normalized: string[] = [];
+  const seen = new Set<string>();
+  for (const item of value) {
+    const next = asNonEmptyString(item);
+    if (!next || seen.has(next)) {
+      continue;
+    }
+    normalized.push(next);
+    seen.add(next);
+  }
+  return normalized;
+}
+
+export interface GateSelectionServicePort {
+  getGatesConfig(): AnyRecord;
+  getPolicySnapshot(): AnyRecord;
+}
+
+export interface GateSelectionFinding {
+  code: string;
+  message: string;
+  details?: AnyRecord;
+}
+
+export interface ResolvedGateProfile {
+  profileName: string;
+  source: 'state' | 'policy_default' | 'fallback';
+  findings: GateSelectionFinding[];
+}
+
+export interface CanonicalizedPlanInput {
+  plan: AnyRecord;
+  findings: GateSelectionFinding[];
+}
+
+export class GateSelectionService {
+  private readonly port: GateSelectionServicePort;
+
+  constructor(port: GateSelectionServicePort) {
+    this.port = port;
+  }
+
+  private readProfiles(): Record<string, AnyRecord> {
+    const gatesConfig = this.port.getGatesConfig();
+    const profiles = gatesConfig['profiles'];
+    if (!profiles || typeof profiles !== 'object' || Array.isArray(profiles)) {
+      return {};
+    }
+    return profiles as Record<string, AnyRecord>;
+  }
+
+  private readGateSelectionPolicy(): AnyRecord {
+    const policy = this.port.getPolicySnapshot();
+    return asRecord(asRecord(policy)['gate_selection']);
+  }
+
+  isAutoHealInvalidStateProfileEnabled(): boolean {
+    const policy = this.readGateSelectionPolicy();
+    const value = policy['auto_heal_invalid_state_profile'];
+    return typeof value === 'boolean' ? value : true;
+  }
+
+  isLegacyModeProfileCompatEnabled(): boolean {
+    const policy = this.readGateSelectionPolicy();
+    const value = policy['legacy_mode_profile_compat'];
+    return typeof value === 'boolean' ? value : true;
+  }
+
+  private unknownGateProfileOrModeError(details: AnyRecord): never {
+    throw {
+      normalizedResponse: fail(
+        ERROR_CODES.UNKNOWN_GATE_PROFILE_OR_MODE,
+        'Unknown gate profile or mode',
+        {
+          retryable: false,
+          requires_human: true,
+          ...details,
+        },
+      ),
+    };
+  }
+
+  private resolveFallbackProfile(
+    profiles: Record<string, AnyRecord>,
+    findings: GateSelectionFinding[],
+  ): ResolvedGateProfile {
+    const profileNames = Object.keys(profiles).sort((a, b) => a.localeCompare(b));
+    if (profileNames.length === 0) {
+      this.unknownGateProfileOrModeError({
+        profile: null,
+        available_profiles: [],
+        reason: 'no_profiles_configured',
+      });
+    }
+
+    const policy = this.readGateSelectionPolicy();
+    const configuredDefault = asNonEmptyString(policy['default_profile']);
+    if (configuredDefault && Object.prototype.hasOwnProperty.call(profiles, configuredDefault)) {
+      return {
+        profileName: configuredDefault,
+        source: 'policy_default',
+        findings,
+      };
+    }
+
+    if (configuredDefault) {
+      findings.push({
+        code: 'policy_default_profile_invalid',
+        message: 'Configured default profile is not defined in gates profiles',
+        details: {
+          configured_default_profile: configuredDefault,
+          available_profiles: profileNames,
+        },
+      });
+    }
+
+    const fallback = Object.prototype.hasOwnProperty.call(profiles, 'default')
+      ? 'default'
+      : profileNames[0];
+    return {
+      profileName: fallback,
+      source: 'fallback',
+      findings,
+    };
+  }
+
+  resolveProfileFromState(stateGateProfile: unknown): ResolvedGateProfile {
+    const profiles = this.readProfiles();
+    const findings: GateSelectionFinding[] = [];
+    const normalized = asNonEmptyString(stateGateProfile);
+
+    if (normalized && Object.prototype.hasOwnProperty.call(profiles, normalized)) {
+      return {
+        profileName: normalized,
+        source: 'state',
+        findings,
+      };
+    }
+
+    if (normalized) {
+      findings.push({
+        code: 'state_gate_profile_invalid',
+        message: 'State gate_profile is not a configured profile and will be healed to fallback',
+        details: {
+          state_gate_profile: normalized,
+          available_profiles: Object.keys(profiles).sort((a, b) => a.localeCompare(b)),
+        },
+      });
+    }
+
+    return this.resolveFallbackProfile(profiles, findings);
+  }
+
+  resolveProfile(profileName: unknown): AnyRecord {
+    const normalized = asNonEmptyString(profileName);
+    const profiles = this.readProfiles();
+    if (normalized && Object.prototype.hasOwnProperty.call(profiles, normalized)) {
+      return profiles[normalized];
+    }
+
+    this.unknownGateProfileOrModeError({
+      profile: normalized,
+      available_profiles: Object.keys(profiles).sort((a, b) => a.localeCompare(b)),
+    });
+  }
+
+  resolveProfileAndMode(profileName: unknown, mode: unknown): AnyRecord {
+    const normalizedMode = asNonEmptyString(mode);
+    const profile = this.resolveProfile(profileName);
+    const modes = asRecord(profile['modes']);
+    if (normalizedMode && Array.isArray(modes[normalizedMode])) {
+      return profile;
+    }
+
+    const normalizedProfile = asNonEmptyString(profileName);
+    this.unknownGateProfileOrModeError({
+      profile: normalizedProfile,
+      mode: normalizedMode,
+      available_modes: Object.keys(modes).sort((a, b) => a.localeCompare(b)),
+    });
+  }
+
+  private listKnownModes(): Set<string> {
+    const knownModes = new Set<string>();
+    const profiles = this.readProfiles();
+    for (const profile of Object.values(profiles)) {
+      const modes = asRecord(profile['modes']);
+      for (const mode of Object.keys(modes)) {
+        knownModes.add(mode);
+      }
+    }
+    return knownModes;
+  }
+
+  canonicalizePlannerPlanInput(
+    planInput: AnyRecord,
+    resolvedProfileName: string,
+  ): CanonicalizedPlanInput {
+    const canonicalPlan: AnyRecord = structuredClone(planInput);
+    const findings: GateSelectionFinding[] = [];
+    const plannerProfile = asNonEmptyString(canonicalPlan['gate_profile']);
+    const gateTargets = asStringArray(canonicalPlan['gate_targets']);
+    const knownModes = this.listKnownModes();
+    const profiles = this.readProfiles();
+
+    if (
+      plannerProfile &&
+      this.isLegacyModeProfileCompatEnabled() &&
+      !Object.prototype.hasOwnProperty.call(profiles, plannerProfile) &&
+      knownModes.has(plannerProfile) &&
+      !gateTargets.includes(plannerProfile)
+    ) {
+      gateTargets.push(plannerProfile);
+      findings.push({
+        code: 'legacy_mode_profile_compat_applied',
+        message: 'Planner gate_profile matched a mode and was promoted into gate_targets',
+        details: {
+          promoted_mode: plannerProfile,
+        },
+      });
+    }
+
+    if (plannerProfile && plannerProfile !== resolvedProfileName) {
+      findings.push({
+        code: 'planner_gate_profile_ignored',
+        message: 'Planner gate_profile is non-authoritative and was replaced by system profile',
+        details: {
+          planner_gate_profile: plannerProfile,
+          resolved_gate_profile: resolvedProfileName,
+        },
+      });
+    }
+
+    canonicalPlan['gate_profile'] = resolvedProfileName;
+    if (gateTargets.length > 0) {
+      canonicalPlan['gate_targets'] = gateTargets;
+    } else {
+      delete canonicalPlan['gate_targets'];
+    }
+
+    return {
+      plan: canonicalPlan,
+      findings,
+    };
+  }
+}

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

@@ -7,6 +7,7 @@ import { ERROR_CODES } from '../../core/error-codes.js';
 import { fail } from '../../core/response.js';
 import { GATE_RESULT, STATUS } from '../../core/constants.js';
 import { interpolateGateCommands, isIncrementalMode } from './gate-interpolation-service.js';
+import { GateSelectionService } from './gate-selection-service.js';
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type AnyRecord = Record<string, any>;
@@ -70,9 +71,11 @@ export interface GateServicePort {
 
 export class GateService {
   private readonly port: GateServicePort;
+  private readonly gateSelectionService: GateSelectionService;
 
   constructor(port: GateServicePort) {
     this.port = port;
+    this.gateSelectionService = new GateSelectionService(port);
   }
 
   gatesList(profileName: string | null = null): { data: AnyRecord } {
@@ -94,22 +97,7 @@ export class GateService {
   }
 
   gateProfileAndMode(profileName: string, mode: string): AnyRecord {
-    const profile = this.port.getGatesConfig().profiles[profileName];
-    if (!profile || !profile.modes?.[mode]) {
-      throw {
-        normalizedResponse: fail(
-          ERROR_CODES.UNKNOWN_GATE_PROFILE_OR_MODE,
-          'Unknown gate profile or mode',
-          {
-            profile: profileName,
-            mode,
-            retryable: false,
-            requires_human: true,
-          },
-        ),
-      };
-    }
-    return profile;
+    return this.gateSelectionService.resolveProfileAndMode(profileName, mode);
   }
 
   async gatesRun(
@@ -128,7 +116,12 @@ export class GateService {
     evidence: { log_path: string };
   }> {
     const state = await this.port.readState(featureId);
-    const effectiveProfileName = profileName ?? state.frontMatter.gate_profile ?? 'default';
+    const resolvedProfile = this.gateSelectionService.resolveProfileFromState(
+      state.frontMatter.gate_profile,
+    );
+    const explicitProfileName =
+      typeof profileName === 'string' && profileName.trim().length > 0 ? profileName.trim() : null;
+    const effectiveProfileName = explicitProfileName ?? resolvedProfile.profileName;
     const profile = this.gateProfileAndMode(effectiveProfileName, mode);
     const repoRoot = this.port.getRepoRoot();
 
@@ -178,6 +171,7 @@ export class GateService {
       Promise.resolve({
         frontMatter: {
           status: nextStateStatus,
+          gate_profile: resolvedProfile.profileName,
           status_reason:
             runResult.overall === 'fail' ? `Gate mode ${mode} failed` : frontMatter.status_reason,
           gates: {

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

@@ -10,6 +10,7 @@ import { runGit } from '../../core/git.js';
 import { buildQaIndex, makeRequiredTests } from '../../core/qa-index.js';
 import { ERROR_CODES } from '../../core/error-codes.js';
 import { fail } from '../../core/response.js';
+import { GateSelectionService } from './gate-selection-service.js';
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type AnyRecord = Record<string, any>;
@@ -64,9 +65,11 @@ export interface PatchServicePort {
 
 export class PatchService {
   private readonly port: PatchServicePort;
+  private readonly gateSelectionService: GateSelectionService;
 
   constructor(port: PatchServicePort) {
     this.port = port;
+    this.gateSelectionService = new GateSelectionService(port);
   }
 
   async loadAcceptedPlan(featureId: string): Promise<AnyRecord | null> {
@@ -208,6 +211,11 @@ export class PatchService {
     };
   }> {
     const plan = await this.loadAcceptedPlan(featureId);
+    const state = await this.port.readState(featureId);
+    const resolvedProfile = this.gateSelectionService.resolveProfileFromState(
+      state.frontMatter.gate_profile,
+    );
+    const profile = this.gateSelectionService.resolveProfile(resolvedProfile.profileName);
     const parsedDiff = parseUnifiedDiff(unifiedDiff);
 
     await this.validatePatchPaths(featureId, parsedDiff, plan);
@@ -248,9 +256,7 @@ export class PatchService {
       .filter(Boolean);
 
     const previousQaIndex = await readJson(this.port.qaIndexPath(featureId), null);
-    const profileName = plan?.gate_profile ?? 'default';
-    const profile = this.port.getGatesConfig().profiles[profileName];
-    const requiredTests = makeRequiredTests(profileName, profile);
+    const requiredTests = makeRequiredTests(resolvedProfile.profileName, profile);
     const qaIndex = buildQaIndex(featureId, parsedDiff, requiredTests, previousQaIndex);
 
     const qaValidation = await this.port.validateSchema('qa_test_index.schema.json', qaIndex);
@@ -270,6 +276,7 @@ export class PatchService {
       Promise.resolve({
         frontMatter: {
           status: frontMatter.status,
+          gate_profile: resolvedProfile.profileName,
           gates: frontMatter.gates,
         },
         body,

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

@@ -4,6 +4,7 @@ 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 {
   getUnresolvedDeps,
   detectCircularDependency,
@@ -42,6 +43,7 @@ function readHeldLocks(frontMatter: AnyRecord): string[] {
 
 export interface PlanServicePort {
   getPolicySnapshot(): AnyRecord;
+  getGatesConfig(): AnyRecord;
   planPath(featureId: string): string;
   featureDiscoverSpecs(): Promise<{ data: { specs: Array<{ feature_id: string }> } }>;
   readState(featureId: string): Promise<StateReadResult>;
@@ -59,9 +61,11 @@ export interface PlanServicePort {
 
 export class PlanService {
   private readonly port: PlanServicePort;
+  private readonly gateSelectionService: GateSelectionService;
 
   constructor(port: PlanServicePort) {
     this.port = port;
+    this.gateSelectionService = new GateSelectionService(port);
   }
 
   async planGet(featureId: string): Promise<{ data: { feature_id: string; plan: unknown } }> {
@@ -355,19 +359,32 @@ export class PlanService {
       };
     }
 
-    await this.validatePlanSchema(plan);
-    await this.assertPlanLocksHeld(featureId, plan);
+    const state = await this.port.readState(featureId);
+    const resolvedProfile = this.gateSelectionService.resolveProfileFromState(
+      state.frontMatter.gate_profile,
+    );
+    const canonicalizedPlan = this.gateSelectionService.canonicalizePlannerPlanInput(
+      plan,
+      resolvedProfile.profileName,
+    );
+    const planVersion =
+      typeof canonicalizedPlan.plan.plan_version === 'number'
+        ? canonicalizedPlan.plan.plan_version
+        : 0;
+
+    await this.validatePlanSchema(canonicalizedPlan.plan);
+    await this.assertPlanLocksHeld(featureId, canonicalizedPlan.plan);
 
     // N4: Dependency-aware scheduling — check depends_on before accepting plan
     await this.checkDependencies(featureId);
 
     const existing = await readJson(this.port.planPath(featureId), null);
-    this.validatePlanRevisionRules(existing, plan, expectedVersion);
+    this.validatePlanRevisionRules(existing, canonicalizedPlan.plan, expectedVersion);
 
-    await this.checkPlanCollision(featureId, plan);
+    await this.checkPlanCollision(featureId, canonicalizedPlan.plan);
 
     await this.port.withFeatureLock(featureId, async () => {
-      await atomicWriteJson(this.port.planPath(featureId), plan);
+      await atomicWriteJson(this.port.planPath(featureId), canonicalizedPlan.plan);
     });
 
     await this.port.updateState(featureId, null, (frontMatter, body) => {
@@ -377,7 +394,7 @@ export class PlanService {
           : frontMatter.status;
       return Promise.resolve({
         frontMatter: {
-          gate_profile: plan.gate_profile,
+          gate_profile: resolvedProfile.profileName,
           gates: {
             ...frontMatter.gates,
             plan: GATE_RESULT.PASS,
@@ -397,7 +414,7 @@ export class PlanService {
       data: {
         feature_id: featureId,
         accepted: true,
-        plan_version: plan.plan_version,
+        plan_version: planVersion,
       },
     };
   }

package/apps/control-plane/src/cli/cleanup-command-handler.ts

@@ -80,6 +80,7 @@ export class CleanupCommandHandler {
   async execute(options: CliOptions): Promise<unknown> {
     const dryRun = options.dry_run ?? false;
     const yes = options.yes ?? false;
+    const force = options.force ?? false;
 
     const indexPath = path.join(this.repoRoot, '.aop', 'features', 'index.json');
     let indexData: FeatureIndex = {};
@@ -123,6 +124,13 @@ export class CleanupCommandHandler {
             continue;
           }
         }
+        if (force && runLeaseInactive) {
+          eligible.push({
+            feature_id: featureId,
+            reason: `forced: expired lease, status: ${fm.status ?? 'unknown'}`,
+          });
+          continue;
+        }
         skipped.push({ feature_id: featureId, reason: 'not eligible' });
       } catch {
         if (

package/apps/control-plane/src/cli/help-command-handler.ts

@@ -89,6 +89,11 @@ const COMMAND_HELP: Record<CliCommand, CommandHelp> = {
       },
       { flag: '--dry-run', description: 'Preview what would be cleaned without making changes' },
       { flag: '--yes', description: 'Skip confirmation prompts' },
+      {
+        flag: '--force',
+        description:
+          'Force cleanup of features with expired leases regardless of status (e.g. after a timeout)',
+      },
     ],
   },
   [CliCommand.Init]: {