agentic-orchestrator 0.1.6 → 0.1.8

package/spec-files/completed/agentic_orchestrator_feature_gaps_closure_spec.md

@@ -12,9 +12,11 @@
 ### 0.1 Testing Standards
 
 All new code MUST follow the testing standards defined in:
+
 - **`prompts/vitest-testing-standards.instructions.md`**
 
 Key requirements:
+
 - Use Vitest (`describe/it/expect`, `vi` mocks/spies)
 - Match existing repo conventions (test files in `apps/control-plane/test/*.spec.ts`)
 - Use **Given / When / Then** naming: `GIVEN_<context>_WHEN_<action>_THEN_<expected>`
@@ -25,6 +27,7 @@ Key requirements:
 ### 0.2 Reference Implementation Repository
 
 The ComposioHQ Agent Orchestrator implementation serves as the reference for feature implementations:
+
 - **Repository:** https://github.com/ComposioHQ/agent-orchestrator
 - **Tech stack:** TypeScript ESM, pnpm workspaces, Commander.js CLI, Next.js 15 + React 19 dashboard, Zod validation, Vitest + Playwright tests, tmux-based agent runtime
 - **Key directories to study:**
@@ -43,6 +46,7 @@ The ComposioHQ Agent Orchestrator implementation serves as the reference for fea
 ### 0.3 Package Dependencies (Required Additions)
 
 New dependencies to add to `apps/control-plane/package.json`:
+
 ```json
 {
   "dependencies": {
@@ -57,6 +61,7 @@ New dependencies to add to `apps/control-plane/package.json`:
 ```
 
 New package for dashboard (`packages/web-dashboard/package.json`):
+
 ```json
 {
   "name": "@aop/web-dashboard",
@@ -87,21 +92,25 @@ This specification defines a roadmap to close identified functionality gaps betw
 ### 2.1 Priority Tiers
 
 **P0 (Critical - Implement First):**
+
 - Features that eliminate major UX friction
 - Features that enable production deployment
 - Features required for multi-project workflows
 
 **P1 (High Value - Implement Soon):**
+
 - Features that significantly improve observability
 - Features that reduce manual configuration burden
 - Features that enable common use cases
 
 **P2 (Nice to Have - Future Consideration):**
+
 - Features that improve edge cases
 - Features with viable workarounds
 - Features with unclear ROI
 
 **P3 (Low Priority - Deferred):**
+
 - Features that conflict with core architecture
 - Features with marginal benefit
 - Features that require major redesigns
@@ -121,6 +130,7 @@ This specification defines a roadmap to close identified functionality gaps betw
 **AOP Design Alignment:** HIGH - Monitoring does not conflict with deterministic model.
 
 **Reference Implementation (ComposioHQ):**
+
 - SSE endpoint: `packages/web/src/app/api/events/route.ts`
 - Dashboard components: `packages/web/src/components/Dashboard.tsx`, `SessionCard.tsx`, `SessionDetail.tsx`
 - Hooks: `packages/web/src/hooks/` (real-time state management)
@@ -128,6 +138,7 @@ This specification defines a roadmap to close identified functionality gaps betw
 **Specification:**
 
 **Directory Structure:**
+
 ```
 packages/web-dashboard/
 ├── package.json
@@ -173,9 +184,10 @@ packages/web-dashboard/
 ```
 
 **SSE Implementation (Reference: ComposioHQ `packages/web/src/app/api/events/route.ts`):**
+
 ```typescript
 // packages/web-dashboard/src/app/api/events/route.ts
-export const dynamic = "force-dynamic";
+export const dynamic = 'force-dynamic';
 
 export async function GET(): Promise<Response> {
   const encoder = new TextEncoder();
@@ -187,7 +199,7 @@ export async function GET(): Promise<Response> {
       // Send initial snapshot
       void (async () => {
         const features = await readFeaturesIndex();
-        const event = { type: "snapshot", features };
+        const event = { type: 'snapshot', features };
         controller.enqueue(encoder.encode(`data: ${JSON.stringify(event)}\n\n`));
       })();
 
@@ -205,7 +217,7 @@ export async function GET(): Promise<Response> {
       updates = setInterval(() => {
         void (async () => {
           const features = await readFeaturesIndex();
-          const event = { type: "snapshot", features };
+          const event = { type: 'snapshot', features };
           controller.enqueue(encoder.encode(`data: ${JSON.stringify(event)}\n\n`));
         })();
       }, 2000);
@@ -218,16 +230,17 @@ export async function GET(): Promise<Response> {
 
   return new Response(stream, {
     headers: {
-      "Content-Type": "text/event-stream",
-      "Cache-Control": "no-cache",
-      Connection: "keep-alive",
-      "X-Accel-Buffering": "no",
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+      'X-Accel-Buffering': 'no',
     },
   });
 }
 ```
 
 **useSSE Hook Implementation:**
+
 ```typescript
 // packages/web-dashboard/src/hooks/useSSE.ts
 import { useState, useEffect, useCallback } from 'react';
@@ -248,12 +261,12 @@ export function useSSE({ url, onMessage, reconnectInterval = 5000 }: SSEOptions)
 
     const connect = () => {
       eventSource = new EventSource(url);
-      
+
       eventSource.onopen = () => {
         setConnected(true);
         setError(null);
       };
-      
+
       eventSource.onmessage = (event) => {
         try {
           const data = JSON.parse(event.data);
@@ -262,7 +275,7 @@ export function useSSE({ url, onMessage, reconnectInterval = 5000 }: SSEOptions)
           console.error('SSE parse error:', e);
         }
       };
-      
+
       eventSource.onerror = () => {
         setConnected(false);
         eventSource?.close();
@@ -283,6 +296,7 @@ export function useSSE({ url, onMessage, reconnectInterval = 5000 }: SSEOptions)
 ```
 
 **CLI Integration:**
+
 ```typescript
 // apps/control-plane/src/cli/dashboard-command-handler.ts
 import { spawn } from 'node:child_process';
@@ -292,13 +306,13 @@ export class DashboardCommandHandler {
   async execute(options: { port?: number; foreground?: boolean }): Promise<void> {
     const port = options.port ?? 3000;
     const dashboardPath = resolve(__dirname, '../../../../packages/web-dashboard');
-    
+
     const env = {
       ...process.env,
       PORT: String(port),
       AOP_ROOT: process.cwd(),
     };
-    
+
     if (options.foreground) {
       // Run in foreground
       const child = spawn('npm', ['run', 'dev'], {
@@ -323,6 +337,7 @@ export class DashboardCommandHandler {
 ```
 
 **Testing Requirements (per `prompts/vitest-testing-standards.instructions.md`):**
+
 ```typescript
 // packages/web-dashboard/src/__tests__/api-status.test.ts
 import { describe, it, expect, vi, beforeEach } from 'vitest';
@@ -336,16 +351,18 @@ describe('GET /api/status', () => {
   it('GIVEN_valid_aop_directory_WHEN_status_requested_THEN_returns_features_list', async () => {
     // Mock file reading
     vi.mock('node:fs/promises', () => ({
-      readFile: vi.fn().mockResolvedValue(JSON.stringify({
-        active: ['feature_a'],
-        blocked: [],
-        merged: ['feature_b'],
-      })),
+      readFile: vi.fn().mockResolvedValue(
+        JSON.stringify({
+          active: ['feature_a'],
+          blocked: [],
+          merged: ['feature_b'],
+        }),
+      ),
     }));
-    
+
     const response = await GET();
     const data = await response.json();
-    
+
     expect(response.status).toBe(200);
     expect(data.active).toContain('feature_a');
   });
@@ -354,10 +371,10 @@ describe('GET /api/status', () => {
     vi.mock('node:fs/promises', () => ({
       readFile: vi.fn().mockRejectedValue(new Error('ENOENT')),
     }));
-    
+
     const response = await GET();
     const data = await response.json();
-    
+
     expect(response.status).toBe(200);
     expect(data.active).toEqual([]);
   });
@@ -365,6 +382,7 @@ describe('GET /api/status', () => {
 ```
 
 **Dashboard Routes:**
+
 - `GET /` — Dashboard UI
 - `GET /api/status` — Global status snapshot (same as `aop status` JSON)
 - `GET /api/events` — SSE stream
@@ -392,15 +410,17 @@ The dashboard serves as the primary human review interface. When a feature reach
    - `{ decision: "request_changes", message: "..." }` — Sends the reviewer's feedback as a corrective prompt to the builder agent (via the reaction system) and keeps the feature in its current phase for another build/QA cycle
 
 4. **API Implementation:**
+
    ```typescript
    // POST /api/features/:id/review
    interface ReviewRequest {
      decision: 'approve' | 'deny' | 'request_changes';
-     approval_token?: string;  // required for approve
-     reason?: string;          // required for deny
-     message?: string;         // required for request_changes
+     approval_token?: string; // required for approve
+     reason?: string; // required for deny
+     message?: string; // required for request_changes
    }
    ```
+
    - `approve` → calls `ToolClient.call('feature.ready_to_merge', { feature_id, approval_token })`
    - `deny` → calls `ToolClient.call('feature.state_patch', { feature_id, patch: { status: 'blocked' } })` + `ToolClient.call('feature.log_append', { feature_id, entry: reason })`
    - `request_changes` → calls `ToolClient.call('feature.log_append', { feature_id, entry: message })` + triggers `changes_requested` reaction to inject feedback into agent
@@ -417,20 +437,21 @@ The dashboard provides a one-click checkout so the reviewer can spin up a local
    - On confirm, calls `POST /api/features/:id/checkout`
 
 3. **API Implementation:**
+
    ```typescript
    // POST /api/features/:id/checkout
    interface CheckoutRequest {
-     stash_changes?: boolean;  // default: true — auto-stash uncommitted work
-     restore_after?: boolean;  // default: false — if true, remember original branch for later restore
+     stash_changes?: boolean; // default: true — auto-stash uncommitted work
+     restore_after?: boolean; // default: false — if true, remember original branch for later restore
    }
 
    interface CheckoutResponse {
      ok: boolean;
      data?: {
-       branch: string;          // the branch checked out
+       branch: string; // the branch checked out
        previous_branch: string; // the branch before checkout (for restore)
-       stashed: boolean;        // whether changes were stashed
-       stash_ref?: string;      // stash reference if stashed
+       stashed: boolean; // whether changes were stashed
+       stash_ref?: string; // stash reference if stashed
      };
      error?: { code: string; message: string };
    }
@@ -455,11 +476,13 @@ The dashboard provides a one-click checkout so the reviewer can spin up a local
    - Only one checkout active at a time (tracked in `.aop/runtime/checkout-restore.json`)
 
 **Launch Integration:**
+
 - New CLI command: `aop dashboard [--port 3000] [--foreground]`
 - Starts dashboard server in background or foreground
 - Dashboard reads config from `agentic/orchestrator/policy.yaml` for port, auth settings
 
 **Acceptance Criteria:**
+
 - [ ] Dashboard displays all active/blocked/merged features with live updates
 - [ ] Clicking feature shows state, plan, diff, evidence
 - [ ] SSE updates within 2s of state file changes
@@ -487,9 +510,11 @@ The dashboard provides a one-click checkout so the reviewer can spin up a local
 **Specification:**
 
 **Architecture:**
+
 1. **Notifier Service** (`apps/control-plane/src/application/services/notifier-service.ts`)
    - Abstract `NotifierChannel` interface (desktop, slack, webhook, email)
    - Config in `agentic/orchestrator/policy.yaml`:
+
    ```yaml
    notifications:
      enabled: true
@@ -499,17 +524,17 @@ The dashboard provides a one-click checkout so the reviewer can spin up a local
        slack:
          enabled: true
          webhook: ${SLACK_WEBHOOK_URL}
-         channel: "#aop-alerts"
+         channel: '#aop-alerts'
        webhook:
          enabled: false
          url: ${CUSTOM_WEBHOOK_URL}
          method: POST
          headers:
-           Authorization: "Bearer ${WEBHOOK_TOKEN}"
+           Authorization: 'Bearer ${WEBHOOK_TOKEN}'
      routing:
-       critical: [desktop, slack]  # Gate failures, collisions
-       warning: [slack]             # Stale leases, retry exhaustion
-       info: [slack]                # Feature merged, gates passed
+       critical: [desktop, slack] # Gate failures, collisions
+       warning: [slack] # Stale leases, retry exhaustion
+       info: [slack] # Feature merged, gates passed
    ```
 
 2. **Notification Events:**
@@ -532,6 +557,7 @@ The dashboard provides a one-click checkout so the reviewer can spin up a local
    - Failures logged but do not block orchestration
 
 **Acceptance Criteria:**
+
 - [ ] Desktop notification on gate failure with feature ID + error summary
 - [ ] Slack notification includes clickable link to dashboard (if running)
 - [ ] Webhook payload includes full event context (feature_id, status, evidence summary)
@@ -553,6 +579,7 @@ The dashboard provides a one-click checkout so the reviewer can spin up a local
 **Specification:**
 
 **Wizard Flow:**
+
 1. **Detect repository context:**
    - Check for `.git/` in current directory
    - Parse git remote URL → derive repo owner/name
@@ -580,9 +607,10 @@ The dashboard provides a one-click checkout so the reviewer can spin up a local
 
 5. **Post-init instructions:**
    - Print next steps:
+
      ```
      ✅ Configuration created successfully!
-     
+
      Next steps:
      1. Review config files in agentic/orchestrator/
      2. Add feature specs to .aop/features/<feature_id>/spec.md
@@ -591,6 +619,7 @@ The dashboard provides a one-click checkout so the reviewer can spin up a local
      ```
 
 **Acceptance Criteria:**
+
 - [ ] Wizard detects git repo and parses remote URL
 - [ ] Generated config files pass schema validation
 - [ ] Wizard handles non-git directories gracefully (prompts for manual values)
@@ -612,9 +641,10 @@ The dashboard provides a one-click checkout so the reviewer can spin up a local
 **Specification:**
 
 **Config Schema Extension:**
+
 ```yaml
 # agentic/orchestrator/multi-project.yaml (new file)
-version: "1.0"
+version: '1.0'
 
 defaults:
   max_active_features: 5
@@ -625,17 +655,17 @@ defaults:
     channels: [desktop, slack]
 
 projects:
-  - name: "backend"
+  - name: 'backend'
     path: ~/repos/backend
-    repo: "myorg/backend"
+    repo: 'myorg/backend'
     branch: main
-    policy: agentic/orchestrator/policy.yaml  # per-project override
+    policy: agentic/orchestrator/policy.yaml # per-project override
     gates: agentic/orchestrator/gates-backend.yaml
-    dashboard_port: 3001  # override default
-    
-  - name: "frontend"
+    dashboard_port: 3001 # override default
+
+  - name: 'frontend'
     path: ~/repos/frontend
-    repo: "myorg/frontend"
+    repo: 'myorg/frontend'
     branch: main
     policy: agentic/orchestrator/policy.yaml
     gates: agentic/orchestrator/gates-frontend.yaml
@@ -643,6 +673,7 @@ projects:
 ```
 
 **Implementation:**
+
 1. **Multi-Project Loader** (`src/application/multi-project-loader.ts`)
    - Parses `multi-project.yaml` (optional; single-project mode remains default)
    - Validates each project config against schema
@@ -665,6 +696,7 @@ projects:
    - Global view showing status across all projects
 
 **Acceptance Criteria:**
+
 - [ ] Multi-project config validated against schema
 - [ ] Can run orchestrator for specific project via `--project` flag
 - [ ] Run leases isolated per project (parallel orchestration safe)
@@ -688,54 +720,60 @@ projects:
 **Specification:**
 
 **Reaction Policy Config:**
+
 ```yaml
 # agentic/orchestrator/policy.yaml
 reactions:
   gate_failed:
     enabled: true
     max_retries: 2
-    action: retry_with_agent_repair  # or 'notify_only'
-    escalate_after: 2  # escalate to human after N failures
+    action: retry_with_agent_repair # or 'notify_only'
+    escalate_after: 2 # escalate to human after N failures
     retry_delay: 30s
-  
+
   collision_detected:
     enabled: true
-    action: notify_only  # no auto-resolution
-  
+    action: notify_only # no auto-resolution
+
   ready_to_merge:
     enabled: true
-    action: notify_only  # never auto-merge
+    action: notify_only # never auto-merge
 ```
 
 **Retry Flow:**
+
 1. **Gate failure detected** (QA wave or build wave)
 2. **Check reaction policy:** If `reactions.gate_failed.enabled` and retry count < max_retries
 3. **Agent repair loop:**
    - Load gate failure evidence + logs
    - Inject repair prompt to builder/QA agent:
+
      ```
      Gate execution failed. Review the error logs below and apply fixes.
-     
+
      Gate: {gate_name}
      Exit Code: {exit_code}
-     
+
      Logs:
      {logs}
-     
+
      Evidence:
      {evidence_summary}
      ```
+
 4. **Agent generates repair patches** → apply via `repo.apply_patch`
 5. **Re-run gate** → capture new evidence
 6. **Success:** Advance to next phase
 7. **Failure:** Increment retry count, repeat or escalate
 
 **Escalation:**
+
 - After `escalate_after` failures → notification to all critical channels
 - Feature remains in current phase (does not auto-advance)
 - User can manually intervene via dashboard or `aop send <feature_id> <instruction>`
 
 **Acceptance Criteria:**
+
 - [ ] Gate failure triggers retry if policy enabled
 - [ ] Retry count tracked in feature state (`gate_retry_count`)
 - [ ] Agent receives failure context in prompt
@@ -770,7 +808,9 @@ reactions:
    - Exit with `Ctrl-D` or type `/exit`
 
 **Implementation:**
+
 1. **Provider Interface Extension:**
+
    ```typescript
    interface WorkerProvider {
      sendMessage(sessionId: string, message: string): Promise<void>;
@@ -791,6 +831,7 @@ reactions:
    - Terminal streams stdin/stdout until exit
 
 **Acceptance Criteria:**
+
 - [ ] `aop send` delivers message to active orchestrator session
 - [ ] `aop attach` launches interactive session for supported providers
 - [ ] Error handling: feature not found, session not active, provider unsupported
@@ -830,12 +871,13 @@ reactions:
    reactions:
      agent_stuck:
        enabled: true
-       action: notify_and_restart  # or: notify_only
+       action: notify_and_restart # or: notify_only
        idle_threshold: 300s
        escalate_after: 2
    ```
 
 **Acceptance Criteria:**
+
 - [ ] Activity state detected for at least Claude Code and generic providers
 - [ ] `aop status` displays activity state per feature
 - [ ] Agent stuck beyond threshold triggers notification
@@ -869,6 +911,7 @@ reactions:
    - Configurable in policy: `cleanup.auto_after_merge: true`, `cleanup.grace_period: 3600s`
 
 **Acceptance Criteria:**
+
 - [ ] `aop cleanup --dry-run` lists features eligible for cleanup
 - [ ] `aop cleanup --yes` removes terminal features + orphan worktrees
 - [ ] Auto-cleanup triggers after merge when enabled
@@ -899,6 +942,7 @@ reactions:
    - `aop status --summary` — One-line-per-feature compact view
 
 **Acceptance Criteria:**
+
 - [ ] Batch run deduplicates against existing features
 - [ ] Failed spawns don't block remaining features
 - [ ] Summary output reports counts
@@ -918,13 +962,14 @@ reactions:
 **Specification:**
 
 1. **Policy Extension:**
+
    ```yaml
    # agentic/orchestrator/policy.yaml
    worktree:
      base_branch: main
      post_create:
-       - "npm ci"
-       - "cp .env.example .env"
+       - 'npm ci'
+       - 'cp .env.example .env'
      symlinks:
        - .env
        - .claude
@@ -937,6 +982,7 @@ reactions:
    - Schema extension in `policy.schema.json`
 
 **Acceptance Criteria:**
+
 - [ ] `post_create` commands execute in new worktree directory
 - [ ] Symlinks created before post_create commands run
 - [ ] Command failures logged but don't block initialization
@@ -969,12 +1015,13 @@ reactions:
    - PR info stored in feature state: `pr_number`, `pr_url`, `ci_status`, `review_decision`
 
 2. **Feature State Extension:**
+
    ```yaml
    pr:
      number: 42
-     url: "https://github.com/org/repo/pull/42"
-     ci_status: passing  # passing | failing | pending | none
-     review_decision: approved  # approved | changes_requested | pending | none
+     url: 'https://github.com/org/repo/pull/42'
+     ci_status: passing # passing | failing | pending | none
+     review_decision: approved # approved | changes_requested | pending | none
      merge_ready: true
    ```
 
@@ -988,7 +1035,7 @@ reactions:
    reactions:
      ci_failed_upstream:
        enabled: true
-       action: notify_only  # or: retry_with_agent_repair
+       action: notify_only # or: retry_with_agent_repair
      changes_requested:
        enabled: true
        action: send_review_context_to_agent
@@ -996,6 +1043,7 @@ reactions:
    ```
 
 **Acceptance Criteria:**
+
 - [ ] PR detected automatically after feature creates a branch with open PR
 - [ ] CI status and review decisions reflected in feature state
 - [ ] Dashboard shows PR info with merge score
@@ -1044,6 +1092,7 @@ reactions:
 **Specification:**
 
 **Tracker Abstraction:**
+
 ```typescript
 interface IssueTracker {
   getIssue(issueId: string): Promise<Issue>;
@@ -1053,16 +1102,18 @@ interface IssueTracker {
 ```
 
 **Config Extension:**
+
 ```yaml
 # agentic/orchestrator/policy.yaml
 issue_tracker:
-  type: github  # or linear, jira
+  type: github # or linear, jira
   config:
     token: ${GITHUB_TOKEN}
     repo: myorg/myrepo
 ```
 
 **Integration Points:**
+
 1. **Spec enrichment:** Fetch issue details, inject into planner context
 2. **Status sync:** Update issue status when feature advances (planning → building → merged)
 3. **Comment posting:** Post gate results, evidence links as issue comments
@@ -1096,6 +1147,7 @@ issue_tracker:
 **Specification:**
 
 **Instance Isolation Strategy:**
+
 1. Derive instance ID from config path hash (SHA256)
 2. Namespace run lease file: `.aop/runtime/<instance_id>/run-lease.json`
 3. Each instance has independent dashboard port, worktree paths
@@ -1124,6 +1176,7 @@ issue_tracker:
 #### G13-G18: Deferred Gaps
 
 **Deferred due to low ROI or architectural misalignment:**
+
 - **G13: Plugin System** - Conflicts with deterministic kernel design; provider abstraction sufficient
 - **G14: Alternative Workspace Modes** - Worktrees optimal; clone/copy add complexity
 - **G15: K8s/SSH Runtimes** - MCP transport abstraction sufficient
@@ -1142,6 +1195,7 @@ These features emerged from analyzing both codebases and represent opportunities
 **Problem:** Both AOP and Composio run full test suites on every gate pass. For large codebases, this wastes minutes re-running unaffected tests.
 
 **Specification:**
+
 - After `repo.apply_patch`, compute affected file set from diff
 - Use test dependency graph (vitest `--changed`, jest `--changedSince`, pytest `--lf`) to select affected tests
 - Gate config extension:
@@ -1152,10 +1206,10 @@ These features emerged from analyzing both codebases and represent opportunities
         modes:
           fast:
             commands:
-              - "npx vitest run --changed {base_branch}"  # incremental
+              - 'npx vitest run --changed {base_branch}' # incremental
           full:
             commands:
-              - "npx vitest run"  # full suite
+              - 'npx vitest run' # full suite
   ```
 - `fast` mode uses incremental; `full` and `merge` modes run complete suite
 - Evidence captures which tests were skipped and why
@@ -1171,6 +1225,7 @@ These features emerged from analyzing both codebases and represent opportunities
 **Problem:** Gates run sequentially. Independent gates (lint, type-check, unit tests) could run concurrently.
 
 **Specification:**
+
 - Gate config supports `parallel: true` flag per command group
 - Commands within a parallel group execute concurrently via `Promise.allSettled`
 - Evidence captured per-command; overall gate fails if any parallel command fails
@@ -1185,13 +1240,14 @@ These features emerged from analyzing both codebases and represent opportunities
 **Problem:** Neither system tracks or limits LLM API costs per feature. Runaway agent loops can burn tokens.
 
 **Specification:**
+
 - Track token usage per feature via operation ledger metadata
 - Budget config:
   ```yaml
   budget:
-    per_feature_limit: 50.00  # USD
+    per_feature_limit: 50.00 # USD
     per_phase_limit: 20.00
-    alert_threshold: 0.8  # notify at 80% of budget
+    alert_threshold: 0.8 # notify at 80% of budget
   ```
 - Supervisor checks budget before each worker decision loop iteration
 - Over-budget triggers notification + feature pause (not kill)
@@ -1206,6 +1262,7 @@ These features emerged from analyzing both codebases and represent opportunities
 **Problem:** Neither system supports declaring that Feature B depends on Feature A. AOP's collision detection is file-path based, not semantic.
 
 **Specification:**
+
 - Spec metadata supports `depends_on: [feature_a]`
 - Scheduler defers dependent features to blocked queue until dependencies reach `merged` status
 - Automatic promotion when dependency chain resolves
@@ -1220,6 +1277,7 @@ These features emerged from analyzing both codebases and represent opportunities
 **Problem:** Neither system tracks which provider/model combinations succeed more often at which task types.
 
 **Specification:**
+
 - Record per-feature outcome metrics: gate pass rate, retry count, time-to-merge, cost
 - Aggregate by provider + model over time
 - Optional: feed analytics into provider selection heuristics
@@ -1232,28 +1290,33 @@ These features emerged from analyzing both codebases and represent opportunities
 
 **Problem:** AOP currently defines extension interfaces ad-hoc per feature (G2 introduces `NotifierChannel`, G6 extends `WorkerProvider`, G9 defines `IssueTracker`, G6a adds `ActivityMonitor`, G6e adds `PrMonitor`). Each is a standalone interface with its own discovery, configuration, and error handling. This leads to duplicated patterns, inconsistent adapter lifecycle, and a codebase that gets harder to extend with every new concern axis. Meanwhile the existing `ProviderSelection` in `providers.ts` uses a hardcoded union type (`'codex' | 'claude' | ... | 'copilot'`) — adding a new provider means editing the union, the resolution logic, and every switch that touches it.
 
-**Relationship to Plugin Systems:** This is *not* a plugin system. Plugins imply runtime discovery, dynamic loading, and third-party code running inside the process boundary — all of which undermine AOP's deterministic guarantees. An adapter registry is a **compile-time contract** with **config-driven selection**: the kernel knows every adapter that exists at build time, validates adapter configuration against schemas, and routes through the same deterministic pipeline (RBAC, validation, audit) as everything else. Adapters don't own state — the kernel does. Adapters don't make decisions — the kernel does. Adapters just answer "how do I talk to Slack" or "how do I parse Claude Code's session files."
+**Relationship to Plugin Systems:** This is _not_ a plugin system. Plugins imply runtime discovery, dynamic loading, and third-party code running inside the process boundary — all of which undermine AOP's deterministic guarantees. An adapter registry is a **compile-time contract** with **config-driven selection**: the kernel knows every adapter that exists at build time, validates adapter configuration against schemas, and routes through the same deterministic pipeline (RBAC, validation, audit) as everything else. Adapters don't own state — the kernel does. Adapters don't make decisions — the kernel does. Adapters just answer "how do I talk to Slack" or "how do I parse Claude Code's session files."
 
 **Specification:**
 
 1. **Core Abstraction** (`apps/control-plane/src/application/adapters/adapter-registry.ts`):
+
    ```typescript
    /** A typed slot that adapters can fill. */
    interface AdapterSlot<TContract> {
-     readonly name: string;                    // e.g. 'notification-channel', 'agent-provider'
-     readonly contract: TContract;             // the interface adapters must implement
+     readonly name: string; // e.g. 'notification-channel', 'agent-provider'
+     readonly contract: TContract; // the interface adapters must implement
    }
 
    /** Metadata every adapter must declare. */
    interface AdapterManifest {
-     readonly slot: string;                    // which slot this fills
-     readonly name: string;                    // unique adapter name within slot (e.g. 'slack', 'claude')
-     readonly configSchema?: JsonSchema;       // AJV schema for adapter-specific config
+     readonly slot: string; // which slot this fills
+     readonly name: string; // unique adapter name within slot (e.g. 'slack', 'claude')
+     readonly configSchema?: JsonSchema; // AJV schema for adapter-specific config
    }
 
    /** The registry: slot → (name → adapter instance). */
    interface AdapterRegistry {
-     register<T>(slot: AdapterSlot<T>, manifest: AdapterManifest, factory: (config: unknown) => T): void;
+     register<T>(
+       slot: AdapterSlot<T>,
+       manifest: AdapterManifest,
+       factory: (config: unknown) => T,
+     ): void;
      resolve<T>(slot: AdapterSlot<T>, name: string, config: unknown): T;
      list(slot: string): ReadonlyArray<AdapterManifest>;
      has(slot: string, name: string): boolean;
@@ -1262,13 +1325,13 @@ These features emerged from analyzing both codebases and represent opportunities
 
 2. **Adapter Slots** (formalized concern axes):
 
-   | Slot | Contract Interface | Built-in Adapters | Used By |
-   |------|-------------------|-------------------|---------|
-   | `agent-provider` | `WorkerProvider` | codex, claude, gemini, kiro-cli, copilot, custom | Supervisor runtime, G6 send/attach |
-   | `notification-channel` | `NotifierChannel` | desktop, slack, webhook | G2 NotifierService |
-   | `scm-provider` | `ScmProvider` | github (via `gh` CLI) | G6e PR lifecycle |
-   | `issue-tracker` | `IssueTracker` | github, linear, jira | G9 tracker support |
-   | `activity-detector` | `ActivityDetector` | claude-jsonl, codex-rpc, process-heuristic | G6a activity monitoring |
+   | Slot                   | Contract Interface | Built-in Adapters                                | Used By                            |
+   | ---------------------- | ------------------ | ------------------------------------------------ | ---------------------------------- |
+   | `agent-provider`       | `WorkerProvider`   | codex, claude, gemini, kiro-cli, copilot, custom | Supervisor runtime, G6 send/attach |
+   | `notification-channel` | `NotifierChannel`  | desktop, slack, webhook                          | G2 NotifierService                 |
+   | `scm-provider`         | `ScmProvider`      | github (via `gh` CLI)                            | G6e PR lifecycle                   |
+   | `issue-tracker`        | `IssueTracker`     | github, linear, jira                             | G9 tracker support                 |
+   | `activity-detector`    | `ActivityDetector` | claude-jsonl, codex-rpc, process-heuristic       | G6a activity monitoring            |
 
 3. **Registration & Resolution:**
    - All built-in adapters are registered at kernel boot time in a deterministic order
@@ -1278,17 +1341,18 @@ These features emerged from analyzing both codebases and represent opportunities
    - No dynamic imports, no runtime discovery, no third-party code — every adapter is a known import at build time
 
 4. **Config Integration:**
+
    ```yaml
    # agentic/orchestrator/policy.yaml
    adapters:
-     notification-channel: slack       # selects the 'slack' adapter for this slot
-     scm-provider: github              # selects 'github' for SCM
-     issue-tracker: github             # selects 'github' for issue tracking
-     activity-detector: claude-jsonl   # selects Claude Code JSONL parser
+     notification-channel: slack # selects the 'slack' adapter for this slot
+     scm-provider: github # selects 'github' for SCM
+     issue-tracker: github # selects 'github' for issue tracking
+     activity-detector: claude-jsonl # selects Claude Code JSONL parser
 
    # agentic/orchestrator/agents.yaml (existing, unchanged)
    runtime:
-     default_provider: claude          # selects 'claude' for agent-provider slot
+     default_provider: claude # selects 'claude' for agent-provider slot
    ```
 
 5. **Schema Validation:**
@@ -1309,6 +1373,7 @@ These features emerged from analyzing both codebases and represent opportunities
    - The kernel retains full authority over state, validation, RBAC, and audit. Adapters are leaf-node implementations behind the kernel's deterministic pipeline.
 
 **Acceptance Criteria:**
+
 - [ ] `AdapterRegistry` supports register/resolve/list/has operations with type safety
 - [ ] `agent-provider` slot migrated from hardcoded union to registry (no config changes required)
 - [ ] Adapter config validated against adapter-declared `configSchema` at boot
@@ -1323,9 +1388,11 @@ These features emerged from analyzing both codebases and represent opportunities
 ## 4. Implementation Roadmap
 
 ### Phase 1: Critical UX Improvements (M29)
+
 **Duration:** 5-6 weeks
 
 **Deliverables:**
+
 1. **G1: Web Dashboard** (2 weeks)
    - Next.js dashboard with SSE updates
    - Feature cards, diff viewer, evidence viewer
@@ -1367,6 +1434,7 @@ These features emerged from analyzing both codebases and represent opportunities
    - No config changes required — existing `agents.yaml` `default_provider` resolves through registry
 
 **Milestone Acceptance:**
+
 - [ ] Dashboard displays live feature status with SSE updates + Kanban view
 - [ ] Dashboard review panel: approve/deny/request-changes with merge control
 - [ ] Dashboard checkout: one-click switch to feature branch for local testing with stash/restore
@@ -1381,9 +1449,11 @@ These features emerged from analyzing both codebases and represent opportunities
 ---
 
 ### Phase 2: Autonomous Operations & Observability (M30)
+
 **Duration:** 4-5 weeks
 
 **Deliverables:**
+
 1. **G5: CI Failure Auto-Remediation** (2 weeks)
    - Reaction policy config
    - Retry loop with agent repair
@@ -1413,6 +1483,7 @@ These features emerged from analyzing both codebases and represent opportunities
    - Fast mode uses incremental, full/merge modes run complete suite
 
 **Milestone Acceptance:**
+
 - [ ] Gate failures trigger automatic retry with agent repair + time-based escalation
 - [ ] Agent activity state visible in `aop status` and dashboard
 - [ ] `aop send` delivers messages to active agents with idle-wait
@@ -1422,9 +1493,11 @@ These features emerged from analyzing both codebases and represent opportunities
 ---
 
 ### Phase 3: Ecosystem Integration (M31)
+
 **Duration:** 3-4 weeks
 
 **Deliverables:**
+
 1. **G9: Multi-Tracker Support** (2 weeks)
    - Register `issue-tracker` adapter slot (N6): github, linear, jira adapters
    - Issue context enrichment
@@ -1446,6 +1519,7 @@ These features emerged from analyzing both codebases and represent opportunities
    - Circular dependency detection
 
 **Milestone Acceptance:**
+
 - [ ] Planner receives issue context from GitHub/Linear
 - [ ] Feature status updates sync to issue tracker
 - [ ] Multiple orchestrator instances run safely with isolated leases
@@ -1457,6 +1531,7 @@ These features emerged from analyzing both codebases and represent opportunities
 ## 5. Testing Strategy
 
 ### 5.1 Unit Tests
+
 - **Dashboard:** SSE event emission, API route handlers, file polling, Kanban column assignment, review decision dispatch (approve/deny/request_changes → tool client calls), checkout flow (stash detection, branch switch, restore state tracking)
 - **Notifications:** Channel routing (4-tier), message formatting, failure handling, throttle/batch
 - **Init Wizard:** Git detection, template generation, schema validation, `--auto` mode
@@ -1470,6 +1545,7 @@ These features emerged from analyzing both codebases and represent opportunities
 - **Cost Tracking:** Token accumulation, budget threshold detection, pause logic
 
 ### 5.2 Integration Tests
+
 - **Dashboard E2E:** Feature status updates → SSE events → UI refresh
 - **Dashboard Review E2E:** Feature reaches ready_to_merge → reviewer approves via dashboard → merge executes → feature moves to merged
 - **Dashboard Checkout E2E:** Reviewer clicks checkout → stash created → branch switched → restore returns to original branch + stash pop
@@ -1480,6 +1556,7 @@ These features emerged from analyzing both codebases and represent opportunities
 - **PR Lifecycle E2E:** Branch push → PR detected → CI status tracked → review feedback → agent fix
 
 ### 5.3 Manual Acceptance Tests
+
 - Dashboard visual inspection (UI polish, responsiveness)
 - `aop init` wizard flow (user-friendly prompts, error messages)
 - `aop send` / `aop attach` interactive sessions (terminal streaming)
@@ -1503,7 +1580,7 @@ notifications:
     slack:
       enabled: true
       webhook: ${SLACK_WEBHOOK_URL}
-      channel: "#aop-alerts"
+      channel: '#aop-alerts'
     webhook:
       enabled: false
       url: ${CUSTOM_WEBHOOK_URL}
@@ -1532,12 +1609,12 @@ dashboard:
   enabled: true
   port: 3000
   auth:
-    enabled: false  # future: API key auth
+    enabled: false # future: API key auth
 
 # NEW: Issue Tracker (optional)
 issue_tracker:
   enabled: false
-  type: github  # or linear, jira
+  type: github # or linear, jira
   config:
     token: ${GITHUB_TOKEN}
     repo: myorg/myrepo
@@ -1547,7 +1624,7 @@ issue_tracker:
 
 ```yaml
 # agentic/orchestrator/multi-project.yaml (NEW FILE)
-version: "1.0"
+version: '1.0'
 
 defaults:
   max_active_features: 5
@@ -1557,13 +1634,13 @@ defaults:
     enabled: true
 
 projects:
-  - name: "project_a"
+  - name: 'project_a'
     path: ~/repos/project_a
-    repo: "org/project_a"
+    repo: 'org/project_a'
     branch: main
     policy: agentic/orchestrator/policy.yaml
     gates: agentic/orchestrator/gates-project-a.yaml
-    dashboard_port: 3001  # override
+    dashboard_port: 3001 # override
 ```
 
 ---
@@ -1571,6 +1648,7 @@ projects:
 ## 7. Acceptance Criteria (Phase 1 - M29)
 
 ### Dashboard (G1)
+
 - [ ] Dashboard displays features in real-time via SSE
 - [ ] Feature detail page shows state, plan, diff, evidence
 - [ ] Diff viewer renders syntax-highlighted diffs
@@ -1581,18 +1659,21 @@ projects:
 - [ ] Checkout safety: blocked when no worktree/branch or repo has conflicts
 
 ### Notifications (G2)
+
 - [ ] Desktop notification on gate failure (macOS/Linux)
 - [ ] Slack webhook receives formatted messages with links
 - [ ] Notification config validated on startup
 - [ ] Notification failures logged but do not crash orchestrator
 
 ### Init Wizard (G3)
+
 - [ ] Wizard detects git repo and parses remote URL
 - [ ] Generated config files pass schema validation
 - [ ] Template selection generates correct gates.yaml for test framework
 - [ ] Wizard handles non-git directories gracefully
 
 ### Multi-Project (G4)
+
 - [ ] Multi-project config validates against schema
 - [ ] `--project` flag selects correct project
 - [ ] Run leases isolated per project (parallel safe)
@@ -1603,6 +1684,7 @@ projects:
 ## 8. Non-Goals
 
 **Features explicitly excluded from this spec:**
+
 1. **Auto-merge on green CI** — Conflicts with explicit merge control. AOP requires human approval before merge.
 2. **Plugin system** — Conflicts with deterministic kernel design. Provider abstraction + MCP tool registry provide sufficient extensibility.
 3. **K8s/SSH runtimes** — MCP transport abstraction already supports remote MCP servers for distributed execution.
@@ -1611,6 +1693,7 @@ projects:
 6. **Meta-agent orchestration pattern** — Composio's approach (AI agent as orchestrator using CLI) is innovative but trades determinism for flexibility. AOP's code-driven supervisor provides stronger guarantees. Noted as architectural divergence, not a gap.
 
 **Revised from v1.1:**
+
 - **Review comment auto-handling (G7)** — PROMOTED from Non-Goal to P1. Pragmatic implementation (forward review comments to agent) is compatible with AOP's review model. Subsumed into G6e (PR Lifecycle Integration).
 
 ---
@@ -1620,12 +1703,14 @@ projects:
 ### 9.1 Backward Compatibility
 
 **Existing Features Unaffected:**
+
 - All core MCP tools remain unchanged
 - Existing CLI commands (`run`, `status`, `resume`, `delete`) backward compatible
 - Existing config files work without changes (new fields optional)
 - Feature state/plan/index schemas unchanged
 
 **New Features Opt-In:**
+
 - Dashboard: Launch via `aop dashboard` (opt-in)
 - Notifications: Disabled by default; enable in policy.yaml
 - Reactions: Disabled by default; enable in policy.yaml
@@ -1636,6 +1721,7 @@ projects:
 **No deprecations in M29-M31.**
 
 Future consideration (M32+):
+
 - Deprecate `--transport mcp` in favor of remote MCP server URLs
 - Deprecate in-process transport in favor of local MCP server
 
@@ -1646,17 +1732,20 @@ Future consideration (M32+):
 ### 10.1 Quantitative Metrics
 
 **M29 (Phase 1):**
+
 - Dashboard page load < 2s
 - SSE event latency < 2s (file change → UI update)
 - `aop init` completion time < 60s
 - Notification delivery latency < 5s
 
 **M30 (Phase 2):**
+
 - Retry success rate > 60% (gate failures auto-resolved)
 - Escalation rate < 20% (most failures resolved before human intervention)
 - `aop send` message delivery < 1s
 
 **M31 (Phase 3):**
+
 - Multi-project config validation time < 5s
 - Issue tracker sync latency < 10s
 - Multi-instance run lease acquisition < 1s
@@ -1664,11 +1753,13 @@ Future consideration (M32+):
 ### 10.2 Qualitative Metrics
 
 **User Experience:**
+
 - Dashboard intuitive for first-time users (user testing)
 - Init wizard reduces setup time from 30min → 5min
 - Notifications reduce "poll for status" behavior
 
 **Operational Excellence:**
+
 - Auto-remediation reduces manual intervention by 50%
 - Multi-project support enables single-dashboard management
 - Session commands reduce workflow restarts by 70%
@@ -1680,32 +1771,39 @@ Future consideration (M32+):
 ### 11.1 Technical Risks
 
 **Risk 1: SSE Scalability**
+
 - **Impact:** Dashboard becomes unresponsive with >10 features
 - **Mitigation:** Implement event batching, debounce updates, connection pooling
 
 **Risk 2: Provider API Changes**
+
 - **Impact:** `aop send` / `aop attach` break when Claude/Codex updates
 - **Mitigation:** Version provider interface, graceful fallback, release notes monitoring
 
 **Risk 3: Notification Delivery Failures**
+
 - **Impact:** Critical alerts lost (gate failures, collisions)
 - **Mitigation:** Log all notification attempts, retry failed deliveries, fallback to desktop
 
 **Risk 4: Multi-Project Config Complexity**
+
 - **Impact:** Users misconfigure run leases → orchestrator conflicts
 - **Mitigation:** Schema validation, init wizard guidance, clear error messages
 
 ### 11.2 Operational Risks
 
 **Risk 1: Dashboard Security**
+
 - **Impact:** Unauthorized access to feature diffs, evidence
 - **Mitigation:** Add API key auth (P2), limit to localhost by default
 
 **Risk 2: Retry Loop Abuse**
+
 - **Impact:** Infinite retry loops consume resources
 - **Mitigation:** Hard cap on retries (max 5), exponential backoff, manual override required
 
 **Risk 3: Slack Webhook Rate Limits**
+
 - **Impact:** Notifications dropped during high activity
 - **Mitigation:** Implement rate limiting, batch notifications, queue overflow alerts
 
@@ -1753,6 +1851,7 @@ This specification (v2.0) significantly expands the gap analysis based on a deep
 **Phase 3 (M31)** integrates with external ecosystems (issue trackers, multi-instance isolation, cost tracking, dependency scheduling) for enterprise workflows.
 
 **Key Principles:**
+
 1. Every new feature is opt-in, backward compatible, and does not compromise deterministic guarantees or explicit merge control.
 2. AOP's code-driven supervisor is an intentional architectural choice, not a gap. Meta-agent orchestration (Composio's pattern) trades determinism for flexibility — AOP chooses determinism.
 3. Novel features (N1-N5) represent competitive differentiation opportunities that neither package currently offers.