agentic-orchestrator 0.1.25 → 0.1.27

package/AGENTS.md

@@ -32,7 +32,7 @@ This is an MCP-first, multi-agent orchestrator control plane. The codebase lives
 
 **CLI** (`apps/control-plane/src/cli/`) -> **Supervisor** (`supervisor/`) -> **Kernel** (`core/kernel.ts`) -> **Services** (`application/services/`)
 
-- **CLI**: Entry point at `cli/aop.ts` -> delegates to `interfaces/cli/bootstrap.ts`. Commands: `run`, `status`, `resume`, `stop`, `delete`, `cleanup`, `init`, `dashboard`, `retry`, `send`, `attach`, `help`. All responses are structured JSON with `{ ok, data/error }`. Run `aop --help` or `aop help <command>` for usage details.
+- **CLI**: Entry point at `cli/aop.ts` -> delegates to `interfaces/cli/bootstrap.ts`. Commands: `run`, `status`, `resume`, `stop`, `delete`, `cleanup`, `rollback`, `init`, `dashboard`, `retry`, `send`, `attach`, `help`. `run`/`resume` support `--execution-mode <deterministic|interactive>` overrides. All responses are structured JSON with `{ ok, data/error }`. Run `aop --help` or `aop help <command>` for usage details.
 - **Kernel** (`core/kernel.ts`, ~900 lines): Deterministic orchestration engine. Manages schema validation, state, locks, plans, patches, gates, merges, and reporting. Delegates to 12+ domain services via port interfaces.
 - **Supervisor** (`supervisor/runtime.ts`): Multi-agent runtime. Resolves providers (codex, claude, gemini, etc.), loads role-specific prompts, orchestrates planning/build/QA waves, and manages lease heartbeats.
 - **MCP Tool Runtime** (`mcp/tool-runtime.ts`): Tool execution pipeline with registry-based dispatch, input/output schema validation, role-based authorization, and idempotency tracking via `operation_id`.
@@ -42,7 +42,7 @@ This is an MCP-first, multi-agent orchestrator control plane. The codebase lives
 
 - `policy.yaml` - Commit/patch/merge policies, lock TTL, RBAC, supervisor iteration limits
 - `gates.yaml` - Gate profiles (fast/full/merge) with commands and coverage thresholds
-- `agents.yaml` - Agent roles (planner/builder/qa), provider defaults, prompt paths
+- `agents.yaml` - Agent roles (planner/builder/qa), provider defaults, execution mode defaults (`deterministic|interactive`), prompt paths
 - `prompts/` - Role-specific system prompts
 - `tools/` - MCP tool contracts: `catalog.json` (33 tools), per-tool `schemas/input/` and `schemas/output/`
 - `schemas/` - JSON schemas for policy, state, plan, index, gates, agents, qa_test_index

package/CLAUDE.md

@@ -32,7 +32,7 @@ This is an MCP-first, multi-agent orchestrator control plane. The codebase lives
 
 **CLI** (`apps/control-plane/src/cli/`) → **Supervisor** (`supervisor/`) → **Kernel** (`core/kernel.ts`) → **Services** (`application/services/`)
 
-- **CLI**: Entry point at `cli/aop.ts` → delegates to `interfaces/cli/bootstrap.ts`. Commands: `run`, `status`, `resume`, `stop`, `delete`, `cleanup`, `init`, `dashboard`, `retry`, `send`, `attach`, `help`. All responses are structured JSON with `{ ok, data/error }`. Run `aop --help` or `aop help <command>` for usage details.
+- **CLI**: Entry point at `cli/aop.ts` → delegates to `interfaces/cli/bootstrap.ts`. Commands: `run`, `status`, `resume`, `stop`, `delete`, `cleanup`, `rollback`, `init`, `dashboard`, `retry`, `send`, `attach`, `help`. `run`/`resume` support `--execution-mode <deterministic|interactive>` overrides. All responses are structured JSON with `{ ok, data/error }`. Run `aop --help` or `aop help <command>` for usage details.
 - **Kernel** (`core/kernel.ts`, ~900 lines): Deterministic orchestration engine. Manages schema validation, state, locks, plans, patches, gates, merges, and reporting. Delegates to 12+ domain services via port interfaces.
 - **Supervisor** (`supervisor/runtime.ts`): Multi-agent runtime. Resolves providers (codex, claude, gemini, etc.), loads role-specific prompts, orchestrates planning/build/QA waves, manages lease heartbeats.
 - **MCP Tool Runtime** (`mcp/tool-runtime.ts`): Tool execution pipeline with registry-based dispatch, input/output schema validation, role-based authorization, and idempotency tracking via `operation_id`.
@@ -42,7 +42,7 @@ This is an MCP-first, multi-agent orchestrator control plane. The codebase lives
 
 - `policy.yaml` — Commit/patch/merge policies, lock TTL, RBAC, supervisor iteration limits
 - `gates.yaml` — Gate profiles (fast/full/merge) with commands and coverage thresholds
-- `agents.yaml` — Agent roles (planner/builder/qa), provider defaults, prompt paths
+- `agents.yaml` — Agent roles (planner/builder/qa), provider defaults, execution mode defaults (`deterministic|interactive`), prompt paths
 - `prompts/` — Role-specific system prompts
 - `tools/` — MCP tool contracts: `catalog.json` (33 tools), per-tool `schemas/input/` and `schemas/output/`
 - `schemas/` — JSON schemas for policy, state, plan, index, gates, agents, qa_test_index

package/README.md

@@ -1,4 +1,4 @@
-# Agentic-Orchestrator
+# Agentic-Orchestrator Project
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-NodeNext-3178C6.svg)](https://www.typescriptlang.org/)
 [![Nx Workspace](https://img.shields.io/badge/Nx-Monorepo-143055.svg)](https://nx.dev/)
@@ -10,7 +10,7 @@ It combines:
 
 - a **deterministic kernel** (state, locks, collisions, gates, evidence)
 - a **supervisor runtime** (orchestrator/planner/builder/qa session coordination)
-- a **CLI contract** (`aop <run|status|resume|stop|delete|cleanup|init|dashboard|retry|send|attach>`) with deterministic spec ingestion, runtime control, monitoring, and cleanup
+- a **CLI contract** (`aop <run|status|resume|stop|delete|cleanup|rollback|init|dashboard|retry|send|attach>`) with deterministic spec ingestion, runtime control, monitoring, and cleanup
 
 > For complete normative requirements, see [agentic_orchestrator_spec.md](spec-files/agentic_orchestrator_spec.md).
 > For implementation continuity and the latest status, see [progress.md](spec-files/progress.md).
@@ -216,7 +216,7 @@ All commands print JSON to stdout. Errors use:
 { "ok": false, "error": { "code": "...", "message": "...", "details": { ... } } }
 ```
 
-Available commands: `run`, `status`, `resume`, `stop`, `delete`, `cleanup`, `init`, `dashboard`, `retry`, `send`, `attach`, `help`.
+Available commands: `run`, `status`, `resume`, `stop`, `delete`, `cleanup`, `rollback`, `init`, `dashboard`, `retry`, `send`, `attach`, `help`.
 
 ### `run`
 
@@ -257,6 +257,9 @@ Behavior:
   - starts `SupervisorRuntime` with `max_active_features=5`, `max_parallel_gate_runs=3`.
   - `max_iterations_per_phase` resolves from `policy.yaml` (`supervisor.max_iterations_per_phase`, default `6`).
   - `--takeover-stale-run` enables stale run-lease takeover when another run is stale.
+  - `--execution-mode <deterministic|interactive>` overrides worker execution mode for the run:
+    - `deterministic` (default): PATCH outputs are validated/applied through `repo.apply_patch`.
+    - `interactive`: builder/qa workers get direct `working_directory` access and checkpoint validation snapshots are written under `.aop/features/<feature_id>/checkpoints/`.
 
 ### `status`
 
@@ -288,6 +291,7 @@ Runs recovery (`kernel.recoverFromState`), reconstructs resumable non-terminal f
 - runtime restart:
   - reuses persisted `runtime_sessions.run_id` and `owner_instance_id` when present
   - starts supervisor loop with reconstructed feature set
+  - supports `--execution-mode <deterministic|interactive>` override for resumed worker waves
 
 If no resumable features are found, `resume` returns recovery metadata only and does not start a new loop.
 
@@ -377,6 +381,18 @@ aop cleanup --yes
 
 When `cleanup.auto_after_merge` is enabled in `policy.yaml`, the runtime automatically triggers cleanup after a successful merge.
 
+### `rollback`
+
+Reverses a checkpoint snapshot in the feature worktree using `git apply -R`.
+
+```bash
+# Preview rollback inputs
+aop rollback --feature-id my_feature --checkpoint checkpoint-123 --dry-run
+
+# Apply rollback
+aop rollback --feature-id my_feature --checkpoint checkpoint-123
+```
+
 ### `init`
 
 Initialises agentic orchestrator configuration in the current directory. Generates `policy.yaml`, `gates.yaml`, `agents.yaml`, `adapters.yaml`, and system prompt templates. The wizard also captures default agent `provider`/`model`, `scm-provider`, and provider-auth mode.
@@ -499,8 +515,9 @@ Supported options:
 | `--transport <mcp\\               | inprocess>`                                                                       | Tool transport selection (default `mcp`)                     |
 | `--takeover-stale-run`            | Allow stale run-lease takeover during `run`                                       |
 | `--project <name>`                | Select project from `multi-project.yaml` (run, status, resume, retry)             |
-| `--feature-id <id>`               | Target feature for `delete`, `cleanup`, `retry`, `send`, `attach`                 |
-| `--dry-run [true\\                | false]`                                                                           | Preview-only mode for `delete` and `cleanup`                 |
+| `--feature-id <id>`               | Target feature for `delete`, `cleanup`, `rollback`, `retry`, `send`, `attach`     |
+| `--checkpoint <id>`               | Target checkpoint id for `rollback`                                               |
+| `--dry-run [true\\                | false]`                                                                           | Preview-only mode for `delete`, `cleanup`, and `rollback`    |
 | `--yes`                           | Confirm destructive `delete` or `cleanup` execution                               |
 | `--remove-worktree [true\\        | false]`                                                                           | Whether to remove `.worktrees/<feature_id>` (default `true`) |
 | `--remove-branch <none\\          | safe\\                                                                            | force>`                                                      | Local branch cleanup mode (default `none`) |
@@ -592,9 +609,24 @@ Coverage parser:
 - role-specific system prompt paths
 - default provider/model values with optional `runtime.provider_config_env` for API-backed providers
 - optional `runtime.provider_configs.<provider>` objects for provider-specific payloads (for example `kiro-cli chat --agent dev`)
+- `runtime.execution_mode` default (`deterministic|interactive`) plus `runtime.interactive.*` checkpoint/watchdog controls (`checkpoint_interval_ms`, `watchdog_poll_interval_ms`, `max_uncommitted_changes`, `validation_on_checkpoint`, `revert_on_violation`, `violation_severity`)
 - `worktree.post_create` commands and `worktree.symlinks` for workspace hook automation
 - stack-specific examples: [`example-configurations/node/`](example-configurations/node) and [`example-configurations/java/`](example-configurations/java)
 
+Interactive mode example:
+
+```yaml
+runtime:
+  execution_mode: interactive
+  interactive:
+    checkpoint_interval_ms: 30000
+    watchdog_poll_interval_ms: 2000
+    max_uncommitted_changes: 50
+    validation_on_checkpoint: true
+    revert_on_violation: false
+    violation_severity: warning
+```
+
 ### Multi-Project (`config/agentic/orchestrator/multi-project.yaml`)
 
 Optional. Defines multiple independent projects in one repository. Pass `--project <name>` on the CLI to scope commands to a project. `aop status --all` aggregates across all projects. Each project can override `policy` and `gates` paths.
@@ -631,20 +663,21 @@ Files the runtime creates/maintains:
 - `.aop/features/<feature_id>/state.md`
 - `.aop/features/<feature_id>/plan.json`
 - `.aop/features/<feature_id>/qa_test_index.json`
+- `.aop/features/<feature_id>/checkpoints/*.diff` (interactive-mode checkpoint audit snapshots)
 - `.aop/features/<feature_id>/logs/*`
 - `.aop/features/<feature_id>/evidence/*`
 
 ### 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`, 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                                                                                                                               |
+| 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`, optional `execution_mode` override and `checkpoints[]` audit metadata |
+| `.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/agents.yaml

@@ -10,6 +10,19 @@ missing_prompt_behavior: ignore
 runtime:
   default_provider: custom
   default_model: local-default
+  execution_mode: deterministic
+  interactive:
+    watchdog_poll_interval_ms: 2000
+    checkpoint_interval_ms: 30000
+    max_uncommitted_changes: 50
+    validation_on_checkpoint: true
+    revert_on_violation: false
+    violation_severity: warning
+    shadow_workspace:
+      enabled: false
+      promotion_strategy: atomic
+      cleanup_on_failure: true
+      max_shadow_size_mb: 2048
   worker_provider_mode: live
   worker_response_timeout_ms: 600000
   worker_spawn_timeout_ms: 15000

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

@@ -171,6 +171,7 @@ cleanup:
 dashboard:
   enabled: true
   port: 3000
+  quick_launch: false
 notifications:
   enabled: false
   channels:

package/agentic/orchestrator/policy.yaml

@@ -105,6 +105,9 @@ supervisor:
 cleanup:
   auto_after_merge: false
   grace_period_seconds: 3600
+observability:
+  raw_agent_logs_enabled: false
+  raw_agent_logs_retention_days: 60
 notifications:
   enabled: false
   channels:
@@ -193,6 +196,7 @@ rbac:
 dashboard:
   enabled: true
   port: 3000
+  quick_launch: false
 reactions:
   gate_failed:
     enabled: true

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

@@ -48,6 +48,82 @@
           "type": "string",
           "description": "Default model string passed to the provider SDK. Overridden by --agent-model CLI flag or AOP_AGENT_MODEL env var."
         },
+        "execution_mode": {
+          "type": "string",
+          "enum": ["deterministic", "interactive"],
+          "default": "deterministic",
+          "description": "Execution mode used by worker roles. deterministic routes PATCH outputs through repo.apply_patch; interactive allows direct worktree edits with checkpoint validation."
+        },
+        "interactive": {
+          "type": "object",
+          "description": "Interactive execution mode settings used by the worker decision loop checkpoint/watchdog runtime.",
+          "additionalProperties": false,
+          "properties": {
+            "watchdog_poll_interval_ms": {
+              "type": "integer",
+              "minimum": 1,
+              "default": 2000,
+              "description": "Polling interval in milliseconds for worktree watchdog status scans."
+            },
+            "checkpoint_interval_ms": {
+              "type": "integer",
+              "minimum": 1,
+              "default": 30000,
+              "description": "Time-based checkpoint cadence in milliseconds."
+            },
+            "max_uncommitted_changes": {
+              "type": "integer",
+              "minimum": 1,
+              "default": 50,
+              "description": "Change-count threshold that triggers a checkpoint before the time-based interval."
+            },
+            "validation_on_checkpoint": {
+              "type": "boolean",
+              "default": true,
+              "description": "When true, each checkpoint validates diff changes against plan/policy/lock constraints."
+            },
+            "revert_on_violation": {
+              "type": "boolean",
+              "default": false,
+              "description": "When true, invalid checkpoint files are reverted automatically after validation failure."
+            },
+            "violation_severity": {
+              "type": "string",
+              "enum": ["info", "warning", "error", "critical"],
+              "default": "warning",
+              "description": "Severity assigned to checkpoint validation violations for notification and enforcement."
+            },
+            "shadow_workspace": {
+              "type": "object",
+              "description": "Reserved shadow-workspace strategy controls for future validation-before-promotion runtime.",
+              "additionalProperties": false,
+              "properties": {
+                "enabled": {
+                  "type": "boolean",
+                  "default": false,
+                  "description": "Enable the shadow workspace interactive strategy."
+                },
+                "promotion_strategy": {
+                  "type": "string",
+                  "enum": ["atomic", "incremental"],
+                  "default": "atomic",
+                  "description": "How validated shadow changes are promoted into the feature worktree."
+                },
+                "cleanup_on_failure": {
+                  "type": "boolean",
+                  "default": true,
+                  "description": "Delete the shadow workspace on validation failure."
+                },
+                "max_shadow_size_mb": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "default": 2048,
+                  "description": "Maximum allowed shadow workspace size in megabytes."
+                }
+              }
+            }
+          }
+        },
         "worker_provider_mode": {
           "type": "string",
           "description": "Execution mode for worker providers. 'live' uses provider-backed execution, 'stub' uses NullWorkerProvider.",

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

@@ -483,6 +483,22 @@
         }
       }
     },
+    "observability": {
+      "type": "object",
+      "description": "Controls persistence and retention of sensitive raw worker provider output logs.",
+      "additionalProperties": false,
+      "properties": {
+        "raw_agent_logs_enabled": {
+          "type": "boolean",
+          "description": "When true, provider stdout from planner/builder/qa invocations is persisted under `.aop/features/<feature_id>/logs/`."
+        },
+        "raw_agent_logs_retention_days": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum age in days for persisted raw provider log files before best-effort cleanup removes them."
+        }
+      }
+    },
     "dashboard": {
       "type": "object",
       "description": "Real-time status dashboard HTTP server settings.",
@@ -496,6 +512,10 @@
           "minimum": 1,
           "maximum": 65535,
           "description": "Port the dashboard HTTP server listens on."
+        },
+        "quick_launch": {
+          "type": "boolean",
+          "description": "Enables dashboard quick-launch feature creation flow (`POST /api/run`)."
         }
       }
     },

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

@@ -71,6 +71,26 @@
           "minimum": 1,
           "maximum": 65535,
           "description": "Port the dashboard HTTP server listens on."
+        },
+        "quick_launch": {
+          "type": "boolean",
+          "description": "Enable dashboard quick-launch feature initialization flow."
+        }
+      }
+    },
+    "observability": {
+      "type": "object",
+      "description": "Raw worker output observability controls.",
+      "additionalProperties": false,
+      "properties": {
+        "raw_agent_logs_enabled": {
+          "type": "boolean",
+          "description": "When true, planner/builder/qa raw stdout is persisted in feature log artifacts."
+        },
+        "raw_agent_logs_retention_days": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Number of days raw agent log files are retained before cleanup."
         }
       }
     },

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

@@ -41,6 +41,11 @@
       "description": "Current lifecycle phase. planning \u2192 building \u2192 qa \u2192 ready_to_merge \u2192 merged. 'blocked' is a cross-cutting pause state; 'failed' is terminal.",
       "enum": ["planning", "building", "qa", "blocked", "ready_to_merge", "merged", "failed"]
     },
+    "execution_mode": {
+      "type": "string",
+      "enum": ["deterministic", "interactive"],
+      "description": "Optional per-feature execution mode override used by the supervisor mode resolver."
+    },
     "gate_profile": {
       "type": "string",
       "description": "System-resolved gates profile for this feature. Runtime resolves and heals this from policy/gates config; planner plan input is not authoritative."
@@ -145,6 +150,54 @@
         }
       }
     },
+    "checkpoints": {
+      "type": "array",
+      "description": "Checkpoint history captured during interactive execution mode. Each item records the diff snapshot, validation status, and any violations.",
+      "items": {
+        "type": "object",
+        "required": ["checkpoint_id", "timestamp", "files_changed", "validation_status"],
+        "additionalProperties": false,
+        "properties": {
+          "checkpoint_id": {
+            "type": "string",
+            "description": "Stable checkpoint identifier used for audit and rollback references."
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Checkpoint creation timestamp in RFC3339 format."
+          },
+          "files_changed": {
+            "type": "array",
+            "description": "Set of worktree-relative file paths changed when the checkpoint snapshot was captured.",
+            "items": {
+              "type": "string"
+            }
+          },
+          "validation_status": {
+            "type": "string",
+            "enum": ["valid", "invalid", "skipped"],
+            "description": "Constraint-validation outcome for the checkpoint snapshot."
+          },
+          "violations": {
+            "type": "array",
+            "description": "Human-readable validation violation details collected at checkpoint time.",
+            "items": {
+              "type": "string"
+            }
+          },
+          "severity": {
+            "type": "string",
+            "enum": ["info", "warning", "error", "critical"],
+            "description": "Normalized severity assigned to checkpoint validation violations."
+          },
+          "diff_snapshot": {
+            "type": "string",
+            "description": "Repository-relative path to the stored checkpoint diff artifact."
+          }
+        }
+      }
+    },
     "pr": {
       "type": "object",
       "description": "Pull request metadata populated by the PR monitor service when a PR exists for this feature.",

package/apps/control-plane/src/application/configuration-service.ts

@@ -0,0 +1,181 @@
+import path from 'node:path';
+import { pathExists } from '../core/fs.js';
+import type { SchemaRegistry } from '../core/schemas.js';
+import { loadAndValidateYaml } from '../core/schemas.js';
+import type { AopPathLayout } from '../core/path-layout.js';
+import { ensureAopRuntimeLayout } from '../core/path-layout.js';
+import { loadComposedPolicy } from './services/policy-loader-service.js';
+import {
+  ACTIVITY_DETECTOR_SLOT,
+  NOTIFICATION_CHANNEL_SLOT,
+  SCM_PROVIDER_SLOT,
+  globalAdapterRegistry,
+} from './adapters/adapter-registry.js';
+import { ToolRegistryLoader } from '../mcp/tool-registry-loader.js';
+import { ERROR_CODES } from '../core/error-codes.js';
+import type {
+  AnyRecord,
+  KernelConfigOverrides,
+  AgentsConfigSnapshot,
+  PolicyConfigSnapshot,
+} from '../core/kernel-types.js';
+import {
+  readStringField,
+  readObjectField,
+  readPositiveIntegerField,
+} from '../core/utils/field-readers.js';
+
+export interface LoadedConfiguration {
+  gatesConfig: AnyRecord;
+  policy: PolicyConfigSnapshot;
+  agentsConfig: AgentsConfigSnapshot;
+  adaptersConfig: Record<string, unknown>;
+  toolRegistry: AnyRecord | null;
+}
+
+function validateAgentRuntimeTimeoutRelationships(agentsConfig: AnyRecord): void {
+  const runtime = readObjectField(agentsConfig, 'runtime');
+  if (Object.keys(runtime).length === 0) {
+    return;
+  }
+  const responseTimeoutMs = readPositiveIntegerField(runtime, 'worker_response_timeout_ms');
+  const spawnTimeoutMs = readPositiveIntegerField(runtime, 'worker_spawn_timeout_ms');
+  const idleTimeoutMs = readPositiveIntegerField(runtime, 'worker_idle_timeout_ms');
+
+  if (responseTimeoutMs != null && spawnTimeoutMs != null && spawnTimeoutMs >= responseTimeoutMs) {
+    throw new Error(
+      'invalid_agents_yaml:runtime.worker_spawn_timeout_ms must be less than runtime.worker_response_timeout_ms',
+    );
+  }
+  if (responseTimeoutMs != null && idleTimeoutMs != null && idleTimeoutMs > responseTimeoutMs) {
+    throw new Error(
+      'invalid_agents_yaml:runtime.worker_idle_timeout_ms must be less than or equal to runtime.worker_response_timeout_ms',
+    );
+  }
+}
+
+export class ConfigurationService {
+  private readonly repoRoot: string;
+  private readonly pathLayout: AopPathLayout;
+  private readonly schemaRegistry: SchemaRegistry;
+  private readonly configOverrides: KernelConfigOverrides;
+
+  constructor(
+    repoRoot: string,
+    pathLayout: AopPathLayout,
+    schemaRegistry: SchemaRegistry,
+    configOverrides: KernelConfigOverrides,
+  ) {
+    this.repoRoot = repoRoot;
+    this.pathLayout = pathLayout;
+    this.schemaRegistry = schemaRegistry;
+    this.configOverrides = configOverrides;
+  }
+
+  private async resolveDefaultConfigPath(fileName: string): Promise<string> {
+    const primary = path.join(this.pathLayout.orchestratorRoot, fileName);
+    if (await pathExists(primary)) {
+      return primary;
+    }
+    const legacy = path.join(this.pathLayout.legacyOrchestratorRoot, fileName);
+    if (await pathExists(legacy)) {
+      return legacy;
+    }
+    return primary;
+  }
+
+  async loadAll(): Promise<LoadedConfiguration> {
+    await ensureAopRuntimeLayout(this.pathLayout);
+
+    const gatesPath =
+      this.configOverrides.gatesPath ?? (await this.resolveDefaultConfigPath('gates.yaml'));
+    const policyPath =
+      this.configOverrides.policyPath ?? (await this.resolveDefaultConfigPath('policy.yaml'));
+    const agentsPath =
+      this.configOverrides.agentsPath ?? (await this.resolveDefaultConfigPath('agents.yaml'));
+    const adaptersPath =
+      this.configOverrides.adaptersPath ?? (await this.resolveDefaultConfigPath('adapters.yaml'));
+
+    const gates = await loadAndValidateYaml(this.schemaRegistry, 'gates.schema.json', gatesPath);
+    if (!gates.validation.valid) {
+      throw new Error(`invalid_gates_yaml:${JSON.stringify(gates.validation.errors)}`);
+    }
+
+    const { mergedPolicy } = await loadComposedPolicy(
+      this.repoRoot,
+      policyPath,
+      this.schemaRegistry,
+    );
+    const parsedPolicy = mergedPolicy as PolicyConfigSnapshot;
+    const implementation = readObjectField(parsedPolicy, 'implementation');
+    const testing = readObjectField(parsedPolicy, 'testing');
+
+    if (readStringField(implementation, 'workspace') !== 'nx') {
+      throw new Error(ERROR_CODES.INVALID_WORKSPACE_IMPLEMENTATION);
+    }
+    if (readStringField(testing, 'framework') !== 'vitest') {
+      throw new Error(ERROR_CODES.INVALID_WORKSPACE_IMPLEMENTATION);
+    }
+
+    const agentsExists = await pathExists(agentsPath);
+    let agents = { parsed: { version: 1, roles: {} }, validation: { valid: true, errors: [] } };
+    if (agentsExists) {
+      agents = await loadAndValidateYaml(this.schemaRegistry, 'agents.schema.json', agentsPath);
+      if (!agents.validation.valid) {
+        throw new Error(`invalid_agents_yaml:${JSON.stringify(agents.validation.errors)}`);
+      }
+      validateAgentRuntimeTimeoutRelationships(agents.parsed as AnyRecord);
+    }
+
+    const adaptersExists = await pathExists(adaptersPath);
+    let adapters = { parsed: {}, validation: { valid: true, errors: [] as unknown[] } };
+    if (adaptersExists) {
+      adapters = await loadAndValidateYaml(
+        this.schemaRegistry,
+        'adapters.schema.json',
+        adaptersPath,
+      );
+      if (!adapters.validation.valid) {
+        throw new Error(`invalid_adapters_yaml:${JSON.stringify(adapters.validation.errors)}`);
+      }
+      const parsedAdapters = readObjectField(adapters, 'parsed');
+      const notificationChannel = readStringField(parsedAdapters, NOTIFICATION_CHANNEL_SLOT.name);
+      if (notificationChannel) {
+        try {
+          globalAdapterRegistry.resolve(NOTIFICATION_CHANNEL_SLOT, notificationChannel, {});
+        } catch {
+          throw new Error(
+            `adapter_not_found:${NOTIFICATION_CHANNEL_SLOT.name}:${notificationChannel}`,
+          );
+        }
+      }
+      const activityDetector = readStringField(parsedAdapters, ACTIVITY_DETECTOR_SLOT.name);
+      if (activityDetector) {
+        try {
+          globalAdapterRegistry.resolve(ACTIVITY_DETECTOR_SLOT, activityDetector, {});
+        } catch {
+          throw new Error(`adapter_not_found:${ACTIVITY_DETECTOR_SLOT.name}:${activityDetector}`);
+        }
+      }
+      const scmProvider = readStringField(parsedAdapters, SCM_PROVIDER_SLOT.name);
+      if (scmProvider) {
+        try {
+          globalAdapterRegistry.resolve(SCM_PROVIDER_SLOT, scmProvider, {});
+        } catch {
+          throw new Error(`adapter_not_found:${SCM_PROVIDER_SLOT.name}:${scmProvider}`);
+        }
+      }
+    }
+
+    const registryLoader = new ToolRegistryLoader(this.repoRoot);
+    const toolRegistry = await registryLoader.load();
+
+    return {
+      gatesConfig: gates.parsed,
+      policy: parsedPolicy,
+      agentsConfig: agents.parsed as AgentsConfigSnapshot,
+      adaptersConfig: readObjectField(adapters, 'parsed'),
+      toolRegistry,
+    };
+  }
+}