@dv.nghiem/flowdeck 0.4.11 → 0.5.0

package/docs/concepts/HARNESS_ARCHITECTURE.md

@@ -0,0 +1,241 @@
+# FlowDeck Target Harness Architecture
+
+**Status**: Proposed  
+**Scope**: Transform FlowDeck from a prompt-heavy plugin into a real agent-harness engineering runtime while staying OpenCode-native.
+
+## 1. Core idea
+
+Today FlowDeck registers agents, rules, skills, commands, hooks and tools, but most critical behavior lives in prompts (orchestrator prompt, command markdown). Several runtime services exist as code and tests but are not wired into the plugin lifecycle. The target architecture moves three things into runtime enforcement:
+
+1. **Delegation is explicit.** The orchestrator no longer "asks" the model to route; it calls a `delegate` tool that the harness executes, tracks, and budgets.
+2. **Policy is executable.** Agent contracts, supervisor review, approval gates, and loop/deadlock detection run in hooks/services, not only in prompt text.
+3. **State is first-class.** Workflow state, run traces, agent spans, approvals, and observations are persisted, queryable, and used for recovery, review, and audit.
+
+The model is still the reasoner, but the harness owns execution, state, and governance.
+
+## 2. Design principles
+
+- **Correctness first**: use existing working services before inventing new ones.
+- **OpenCode-native**: keep tools, permissions allow/deny/ask, agents, skills, hooks, and config.
+- **Prompts describe, runtime enforces**: contracts, budgets, gates, and routing are checked in code.
+- **Minimum surface area**: only expose what callers (agents/commands) need.
+- **Testable layers**: each layer has narrow interfaces and can be exercised without the full OpenCode runtime.
+
+## 3. High-level component diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                          OpenCode host                                  │
+│  (model, session, native tools, permissions, agents, commands, skills)  │
+└─────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         FlowDeck plugin (src/index.ts)                  │
+│  registers agents, tools, hooks, MCPs, commands, skills, rules          │
+└─────────────────────────────────────────────────────────────────────────┘
+                                    │
+        ┌───────────────────────────┼───────────────────────────┐
+        ▼                           ▼                           ▼
+┌───────────────┐          ┌───────────────┐          ┌───────────────┐
+│ ContextIngress│          │ ActionMediator│          │ExecutionSubstrate
+│  Service      │          │   Service     │          │   Service     │
+└───────┬───────┘          └───────┬───────┘          └───────┬───────┘
+        │                          │                          │
+        ▼                          ▼                          ▼
+┌───────────────┐          ┌───────────────┐          ┌───────────────┐
+│StatePersistence│         │Verification&  │          │Recovery&      │
+│   Service     │          │   Review      │          │   Debugging   │
+└───────┬───────┘          └───────┬───────┘          └───────┬───────┘
+        │                          │                          │
+        └──────────────────────────┼──────────────────────────┘
+                                   ▼
+                    ┌─────────────────────────────┐
+                    │  Delegation & Coordination  │
+                    │   (orchestrator + router)   │
+                    └─────────────────────────────┘
+                                   │
+                                   ▼
+                    ┌─────────────────────────────┐
+                    │   Governance & Audit        │
+                    │ (contracts, approvals, logs)│
+                    └─────────────────────────────┘
+```
+
+## 4. End-to-end data flow
+
+A typical user request (`/fd-quick "add auth middleware"`) flows through the harness:
+
+1. **Command entry** — OpenCode fires `command.execute.before`/`after`. The harness starts a `RunTrace` (run_id).
+2. **Context ingress** — `ContextIngressService` assembles `STATE.md`, `PLAN.md`, `.codebase/` docs, recent events, relevant skills/rules, and a token-budget snapshot. It short-circuits to the trivial-chat path if the request is a simple question.
+3. **Routing** — `quick-router` + `workflow-router` classify the task and produce a `WorkflowRoute` (workflow class + stage sequence). `model-router` provides complexity/eligible-agent hints.
+4. **Delegation** — The orchestrator calls the `delegate` tool. `ActionMediator` validates the target agent against `agent-contract-registry`, runs `agent-validator`, checks `supervisor-binding`, and enforces the delegation budget.
+5. **Execution** — `ExecutionSubstrate` opens an `AgentSpan` (agent-trace-graph), tracks the child session, applies tool lifecycle hooks, and records cost/time.
+6. **Tool mediation** — On every `tool.execute.before`, `ActionMediator` normalizes args, classifies risk, runs approval gates (`approval-manager`), arch constraints, phase gates, loop detection, and orchestrator guard.
+7. **State persistence** — Each meaningful change writes to `.planning/STATE.md`, `.codebase/RUNS.jsonl`, `.codebase/AGENT_SPANS.jsonl`, `.opencode/flowdeck-events.jsonl`, or `.codebase/APPROVALS.json`.
+8. **Verification** — At stage boundaries `VerificationService` checks tests, coverage, review verdict, and design approval before allowing the next stage.
+9. **Recovery** — If a span fails or a deadlock/loop signal fires, `RecoveryService` classifies the failure, bounds retries, and either re-routes, escalates, or stops.
+10. **Audit** — On run end, `WorkflowScorecard` is generated and `AGENT_PERF.json` is updated.
+
+## 5. Key interface contracts
+
+These interfaces are the contracts between layers. Implementations may be added incrementally.
+
+### 5.1 Context ingress
+
+```typescript
+// src/services/context-ingress.ts
+export interface AssembledContext {
+  runId: string;
+  sessionId: string;
+  projectRoot: string;
+  state: PlanningState;
+  route: WorkflowRoute | null;
+  relevantRules: string[];
+  relevantSkills: string[];
+  recentEvents: ToolEvent[];
+  observations: Observation[];
+  tokenBudget: TokenBudgetSnapshot;
+  isTrivialChat: boolean;
+}
+
+export interface ContextIngressService {
+  assemble(input: { command: string; args: string; sessionId: string }): Promise<AssembledContext>;
+  refreshRunId(ctx: AssembledContext): AssembledContext;
+  snapshotBudget(ctx: AssembledContext): TokenBudgetSnapshot;
+}
+```
+
+### 5.2 Action mediator
+
+```typescript
+// src/services/action-mediator.ts
+export interface ActionRequest {
+  toolName: string;
+  args: Record<string, unknown>;
+  agentName?: string;
+  runId: string;
+  sessionId: string;
+}
+
+export interface ActionDecision {
+  action: "allow" | "block" | "ask" | "escalate";
+  reason: string;
+  riskScore: number;
+  requiredApprovalId?: string;
+}
+
+export interface ActionMediatorService {
+  check(request: ActionRequest): ActionDecision;
+  recordOutcome(request: ActionRequest, decision: ActionDecision, output: unknown): void;
+}
+```
+
+### 5.3 Delegation
+
+```typescript
+// src/tools/delegate.ts
+export interface DelegateInput {
+  target: "agent" | "command";
+  name: string;                 // e.g. "backend-coder" or "fd-plan"
+  taskDescription: string;
+  contextSummary?: string;
+  mode?: "quick" | "standard" | "explore" | "verify-heavy";
+  parentSpanId?: string;
+}
+
+export interface DelegateResult {
+  spanId: string;
+  childSessionId?: string;
+  status: "running" | "blocked" | "escalated";
+  reason?: string;
+}
+```
+
+### 5.4 Run pipeline
+
+```typescript
+// src/tools/run-pipeline.ts
+export interface RunPipelineInput {
+  workflowClass: WorkflowClass;
+  stages?: string[];            // optional override
+  taskDescription: string;
+  confirm?: boolean;
+}
+
+export interface RunPipelineResult {
+  runId: string;
+  completedStages: string[];
+  currentStage: string | null;
+  blocked: boolean;
+  blockedReason?: string;
+}
+```
+
+### 5.5 Delegation budget
+
+```typescript
+// src/services/delegation-budget.ts
+export interface DelegationBudget {
+  runId: string;
+  maxToolCalls: number;
+  maxDepth: number;
+  maxSameStepRetries: number;
+  spentToolCalls: number;
+  currentDepth: number;
+}
+
+export interface DelegationBudgetService {
+  init(runId: string, config?: Partial<DelegationBudget>): DelegationBudget;
+  checkSpend(runId: string, toolName: string): { ok: boolean; remaining: number };
+  recordDelegation(parentRunId: string, childRunId: string): boolean;
+}
+```
+
+## 6. State files
+
+| File | Owner | Purpose | Lifecycle |
+|------|-------|---------|-----------|
+| `.planning/STATE.md` | `planning-state` tool | Current phase, plan confirmation, design gates | Long-lived, updated per phase |
+| `.planning/PLAN.md` | `planning-state` tool | Numbered plan steps | Long-lived, created per feature |
+| `.codebase/RUNS.jsonl` | `run-trace` service | Command-level run history | Append-only |
+| `.codebase/AGENT_SPANS.jsonl` | `agent-trace-graph` service | Causal agent delegation spans | Append-only |
+| `.codebase/SCORECARDS.jsonl` | `workflow-scorecard` service | 10-dimension run quality scores | Append-only |
+| `.codebase/DEADLOCK_SIGNALS.jsonl` | `deadlock-detector` service | Detected loop/deadlock signals | Append-only |
+| `.codebase/APPROVALS.json` | `approval-manager` service | Pending/approved sensitive operations | Mutable |
+| `.codebase/AGENT_PERF.json` | `agent-performance` service | Per-agent/model/task success stats | Mutable |
+| `.codebase/WORKFLOW_ROUTING.jsonl` | `workflow-router` service | Routing decisions and escalations | Append-only |
+| `.opencode/flowdeck-events.jsonl` | `event-logger` service | Raw tool/session events | Append-only, rotated |
+
+## 7. Failure modes and recovery
+
+| Failure | Detection | Recovery |
+|---------|-----------|----------|
+| Same tool repeated with same result | `LoopDetector` in `tool.execute.before` | Block + escalation message |
+| Agent bounce / circular delegation | `deadlock-detector` over `AGENT_SPANS.jsonl` | Log signal, auto-stop if configured |
+| Budget exhausted | `DelegationBudgetService` | Warn / stop / escalate based on `governance.costBudget.onExhaustion` |
+| Approval missing | `approval-hook` + `ActionMediator` | Block with `APPROVAL_REQUIRED` and approval id |
+| Contract violation | `agent-validator` | Advisory warning or strict block |
+| Child session error | `event` hook `session.error` | Close span as `failed`, surface to parent |
+| Tool persistence failure | `event-logger` health flag | Loop detection falls back to in-memory, logs warning |
+| Unregistered target | `supervisor-binding` + `command-validator` | Block before execution |
+
+## 8. Security considerations
+
+- Secrets never enter state files; event args are sanitized by `sanitizeArgs`.
+- Sensitive paths require explicit approval stored in `.codebase/APPROVALS.json` with TTL.
+- Orchestrator cannot use write/edit/bash tools; `OrchestratorGuard` throws.
+- Arch constraints in `.codebase/CONSTRAINTS.md` block edits to forbidden paths.
+- Phase gates block implementation during discuss/plan phases.
+- Tool guard blocks dangerous bash/read/write patterns when enabled.
+
+## 9. Migration path
+
+The harness is built incrementally. Each layer can be merged independently:
+
+1. Wire existing unwired services into `src/index.ts` (agent validator, trace graph, run trace, scorecard, deadlock detector, delegation budget). Existing behavior remains opt-in or advisory.
+2. Add `delegate` and `run-pipeline` tools behind feature flags; keep markdown commands as fallback.
+3. Replace prompt-based routing directives with tool calls once delegation is stable.
+4. Promote governance from advisory to strict via `flowdeck.json`.
+
+No existing public API is broken in step 1.

package/docs/concepts/HARNESS_LAYERS.md

@@ -0,0 +1,378 @@
+# FlowDeck Harness Layers
+
+This document maps each of the eight target harness layers to concrete responsibilities, interfaces, and existing FlowDeck code.
+
+---
+
+## Layer 1: Context ingress
+
+**Responsibilities**
+
+- Assemble prompt/context from `STATE.md`, `PLAN.md`, `.codebase/` docs, recent events, skills, and rules.
+- Provide a lightweight trivial-chat path for questions that need no workflow.
+- Lazy-load rules/skills based on stage and detected language.
+- Deduplicate context, prune stale entries, and summarize oversized content.
+- Emit token-budget diagnostics so the orchestrator knows how much context remains.
+
+**Key types/interfaces**
+
+```typescript
+interface ContextIngressService {
+  assemble(input: {
+    command: string;
+    args: string;
+    sessionId: string;
+    projectRoot: string;
+  }): Promise<AssembledContext>;
+}
+
+interface AssembledContext {
+  runId: string;
+  sessionId: string;
+  state: PlanningState;
+  route: WorkflowRoute | null;
+  relevantRules: string[];
+  relevantSkills: string[];
+  recentEvents: ToolEvent[];
+  observations: Observation[];
+  tokenBudget: TokenBudgetSnapshot;
+  isTrivialChat: boolean;
+}
+```
+
+**Reused**
+
+- `src/services/lazy-rule-loader.ts` — language/stage-based rule discovery and selection.
+- `src/tools/planning-state.ts` + `planning-state-lib.ts` — read/write `STATE.md` and `PLAN.md`.
+- `src/tools/codebase-state.ts` + `repo-memory.ts` — read `.codebase/` docs and architecture graph.
+- `src/services/preflight-explorer.ts` — repo evidence and task-relative context.
+- `src/services/model-router.ts` — complexity classification and stage-aware agent filtering.
+- `src/hooks/context-window-monitor.ts` — token-usage reminder.
+
+**Replaced / new**
+
+- A new `ContextIngressService` consolidates the current ad-hoc reads scattered across orchestrator prompts and command markdown.
+- Trivial-chat short-circuit is currently implicit in prompts; it becomes an explicit `isTrivialChat` flag.
+- Token-budget diagnostics move from a passive monitor to an active input into routing decisions.
+
+---
+
+## Layer 2: Action mediation
+
+**Responsibilities**
+
+- Expose the allowed tool surface per agent/role.
+- Normalize and validate tool arguments.
+- Classify risky actions and compute a risk score.
+- Enforce approval gates, arch constraints, phase gates, and orchestrator guard.
+- Prevent unsafe and duplicate execution through a single policy path.
+
+**Key types/interfaces**
+
+```typescript
+interface ActionRequest {
+  toolName: string;
+  args: Record<string, unknown>;
+  agentName?: string;
+  runId: string;
+  sessionId: string;
+}
+
+interface ActionDecision {
+  action: "allow" | "block" | "ask" | "escalate";
+  reason: string;
+  riskScore: number;
+  requiredApprovalId?: string;
+}
+
+interface ActionMediatorService {
+  check(request: ActionRequest): ActionDecision;
+  recordOutcome(request: ActionRequest, decision: ActionDecision, output: unknown): void;
+}
+```
+
+**Reused**
+
+- `src/services/agent-contract-registry.ts` — allowed/forbidden tools and escalation conditions.
+- `src/services/agent-validator.ts` — contract violation detection.
+- `src/services/supervisor-binding.ts` — preflight policy review for commands/agents.
+- `src/services/approval-manager.ts` — approval request/check storage.
+- `src/hooks/orchestrator-guard-hook.ts` — blocks orchestrator from write/edit/bash tools.
+- `src/hooks/tool-guard.ts` — blocks dangerous read/write/bash patterns and arch constraints.
+- `src/hooks/guard-rails.ts` — phase enforcement and design gates.
+- `src/hooks/approval-hook.ts` — sensitive-file approval gate.
+- `src/services/loop-detector.ts` — duplicate/no-progress execution prevention.
+
+**Replaced / new**
+
+- A new `ActionMediatorService` becomes the single policy path. Today each hook runs independently in `src/index.ts`; the mediator composes them in a defined order and returns one decision.
+- Risk scoring is currently fragmented; the mediator centralizes it.
+
+---
+
+## Layer 3: Execution substrate
+
+**Responsibilities**
+
+- Provide the real execution environment for commands, tools, and agent delegations.
+- Track command and tool lifecycle.
+- Apply timeouts and budgets.
+- Isolate long-running or risky operations.
+- Emit observability events.
+
+**Key types/interfaces**
+
+```typescript
+interface ExecutionSubstrate {
+  startRun(command: string, args: Record<string, unknown>, sessionId: string): RunTrace;
+  openSpan(input: OpenSpanInput): AgentSpan;
+  closeSpan(spanId: string, status: SpanStatus, opts?: CloseSpanOptions): void;
+  recordToolCall(spanId: string, toolName: string): void;
+  attachTimeout(runId: string, ms: number): void;
+}
+```
+
+**Reused**
+
+- `src/services/run-trace.ts` — command-level run lifecycle.
+- `src/services/agent-trace-graph.ts` — causal agent spans.
+- `src/services/event-logger.ts` + `src/hooks/event-log-hook.ts` — tool/session events.
+- `src/services/cost-estimator.ts` — USD cost estimation.
+- `src/services/delegation-budget.ts` (new) — budget envelope.
+- OpenCode native tool execution (the harness wraps it, does not replace it).
+
+**Replaced / new**
+
+- A new `ExecutionSubstrate` service owns the lifecycle coordination between run trace, agent spans, events, and budget. Currently these are updated separately from hooks.
+- Timeout/budget isolation is mostly absent today; the substrate adds explicit timeouts and long-running-op markers.
+
+---
+
+## Layer 4: State persistence
+
+**Responsibilities**
+
+- Persist workflow/run state, action history, and observations.
+- Support resumption and recovery across sessions.
+- Prevent loops via remembered attempts.
+- Separate ephemeral state (session cache) from long-lived state (`.planning/`, `.codebase/`).
+
+**Key types/interfaces**
+
+```typescript
+interface StatePersistenceService {
+  loadRunState(runId: string): RunState | null;
+  saveRunState(runId: string, state: RunState): void;
+  appendObservation(runId: string, observation: Observation): void;
+  getRecentObservations(runId: string, limit?: number): Observation[];
+}
+
+interface RunState {
+  runId: string;
+  workflowClass: WorkflowClass;
+  completedStages: string[];
+  currentStage: string | null;
+  blocked: boolean;
+  blockedReason?: string;
+  observations: Observation[];
+}
+```
+
+**Reused**
+
+- `src/tools/planning-state.ts` — `STATE.md`/`PLAN.md` persistence.
+- `src/services/run-trace.ts` — `RUNS.jsonl`.
+- `src/services/agent-trace-graph.ts` — `AGENT_SPANS.jsonl`.
+- `src/services/event-logger.ts` — `.opencode/flowdeck-events.jsonl`.
+- `src/services/loop-detector.ts` — in-memory remembered attempts.
+- `src/hooks/session-persistence` skill and `src/hooks/session-idle-hook.ts` — session summaries.
+
+**Replaced / new**
+
+- A new `StatePersistenceService` unifies run, stage, and observation access.
+- Ephemeral vs long-lived state separation is currently implicit; it becomes explicit in the interface.
+
+---
+
+## Layer 5: Verification and review
+
+**Responsibilities**
+
+- Verify that actions actually happened.
+- Run checks/tests and collect evidence.
+- Distinguish claimed success from verified success.
+- Gate risky completion before the next stage.
+
+**Key types/interfaces**
+
+```typescript
+interface VerificationService {
+  verifyStage(stage: string, runId: string): VerificationResult;
+  checkTests(runId: string): TestResult;
+  checkReview(runId: string): ReviewResult;
+}
+
+interface VerificationResult {
+  passed: boolean;
+  evidence: string[];
+  blockers: string[];
+}
+```
+
+**Reused**
+
+- `src/services/workflow-scorecard.ts` — quality dimensions (TDD, approvals, reviews).
+- `src/services/agent-validator.ts` — contract compliance.
+- `src/services/supervisor-binding.ts` — post-stage review when `postExecutionReview=true`.
+- Existing test-running via bash hooks.
+
+**Replaced / new**
+
+- A new `VerificationService` moves verification from prompt instructions (`fd-verify`) to runtime checks.
+- Claimed vs verified success is tracked by comparing tool output claims with later verification evidence.
+
+---
+
+## Layer 6: Recovery and debugging
+
+**Responsibilities**
+
+- Detect no-progress loops and stuck runs.
+- Classify failures and bound retries.
+- Explain blockages to the orchestrator/user.
+- Recover from failures or escalate cleanly.
+- Surface diagnostics.
+
+**Key types/interfaces**
+
+```typescript
+interface RecoveryService {
+  assessFailure(runId: string, error: unknown): FailureAssessment;
+  decideRecovery(assessment: FailureAssessment): RecoveryPlan;
+  executeRecovery(plan: RecoveryPlan): RecoveryResult;
+}
+
+interface FailureAssessment {
+  type: "loop" | "deadlock" | "transient" | "contract" | "budget" | "unknown";
+  evidence: string[];
+  retryable: boolean;
+}
+```
+
+**Reused**
+
+- `src/services/loop-detector.ts` — same-result / no-progress detection.
+- `src/services/deadlock-detector.ts` — agent bounce, circular delegation, stage stall.
+- `src/services/failure-replay.ts` tool — historical failure lookup.
+- `src/services/agent-performance.ts` — success-rate guidance for re-routing.
+
+**Replaced / new**
+
+- A new `RecoveryService` coordinates loop detector, deadlock detector, and failure replay into one decision path.
+- Retry bounding is currently per-tool; the service bounds retries per-run and per-stage.
+
+---
+
+## Layer 7: Delegation and coordination
+
+**Responsibilities**
+
+- Orchestrator routes and supervises work.
+- Select the minimal workflow class.
+- Coordinate specialists and the default executor.
+- Maintain parent-child visibility across sessions.
+- Escalate when the initial workflow class is insufficient.
+
+**Key types/interfaces**
+
+```typescript
+interface DelegateTool {
+  execute(input: DelegateInput): Promise<DelegateResult>;
+}
+
+interface RunPipelineTool {
+  execute(input: RunPipelineInput): Promise<RunPipelineResult>;
+}
+
+interface CoordinationService {
+  route(task: string, ctx: AssembledContext): WorkflowRoute;
+  escalate(runId: string, from: WorkflowClass, to: WorkflowClass, reason: string): void;
+}
+```
+
+**Reused**
+
+- `src/agents/orchestrator.ts` — agent definition and routing prompt.
+- `src/agents/default-executor.ts` — direct execution worker.
+- `src/services/quick-router.ts` — task classification and stage sequence.
+- `src/services/workflow-router.ts` — adaptive workflow class selection.
+- `src/services/model-router.ts` — complexity/agent-tier hints.
+- `src/services/agent-trace-graph.ts` — parent/child span linkage.
+
+**Replaced / new**
+
+- New `delegate` and `run-pipeline` tools turn prompt-based routing into imperative calls.
+- A new `CoordinationService` owns workflow class selection and escalation logic that currently lives in the orchestrator prompt.
+
+---
+
+## Layer 8: Governance and audit
+
+**Responsibilities**
+
+- Enforce permissions and approvals.
+- Track sensitive actions.
+- Log workflow decisions.
+- Provide auditability.
+- Keep destructive actions human-governed.
+
+**Key types/interfaces**
+
+```typescript
+interface GovernanceService {
+  reviewTarget(target: string, ctx: SupervisorContext): SupervisorDecision;
+  recordDecision(decision: SupervisorDecision): void;
+  isActionAllowed(action: string, runId: string): boolean;
+}
+
+interface AuditLogEntry {
+  runId: string;
+  timestamp: string;
+  actor: string;
+  action: string;
+  decision: string;
+  reason: string;
+}
+```
+
+**Reused**
+
+- `src/services/agent-contract-registry.ts` — capability contracts.
+- `src/services/agent-validator.ts` — contract enforcement.
+- `src/services/supervisor-binding.ts` — structured approve/revise/block/escalate decisions.
+- `src/services/approval-manager.ts` — approval workflow.
+- `src/services/command-validator.ts` — registered command validation.
+- `src/services/workflow-scorecard.ts` — run-level audit score.
+- `src/services/run-trace.ts` + `agent-trace-graph.ts` + `event-logger.ts` — decision and action logs.
+- `src/tools/decision-trace.ts` — explicit decision recording.
+- `src/tools/policy-engine.ts` — policy storage and query.
+
+**Replaced / new**
+
+- A new `GovernanceService` composes contracts, supervisor, approvals, and command validation into a single governance surface.
+- Sensitive-action tracking moves from opt-in hooks to always-on audit logging.
+
+---
+
+## Layer-to-file quick reference
+
+| Layer | Primary new file | Main existing files reused |
+|-------|------------------|----------------------------|
+| Context ingress | `src/services/context-ingress.ts` | `lazy-rule-loader`, `planning-state`, `codebase-state`, `repo-memory`, `preflight-explorer`, `model-router`, `context-window-monitor` |
+| Action mediation | `src/services/action-mediator.ts` | `agent-contract-registry`, `agent-validator`, `supervisor-binding`, `approval-manager`, `orchestrator-guard-hook`, `tool-guard`, `guard-rails`, `approval-hook`, `loop-detector` |
+| Execution substrate | `src/services/execution-substrate.ts` | `run-trace`, `agent-trace-graph`, `event-logger`, `event-log-hook`, `cost-estimator`, `delegation-budget` |
+| State persistence | `src/services/state-persistence.ts` | `planning-state`, `run-trace`, `agent-trace-graph`, `event-logger`, `loop-detector`, `session-idle-hook` |
+| Verification & review | `src/services/verification.ts` | `workflow-scorecard`, `agent-validator`, `supervisor-binding` |
+| Recovery & debugging | `src/services/recovery.ts` | `loop-detector`, `deadlock-detector`, `failure-replay`, `agent-performance` |
+| Delegation & coordination | `src/tools/delegate.ts`, `src/tools/run-pipeline.ts`, `src/services/coordination.ts` | `agents/orchestrator`, `agents/default-executor`, `quick-router`, `workflow-router`, `model-router`, `agent-trace-graph` |
+| Governance & audit | `src/services/governance.ts` | `agent-contract-registry`, `agent-validator`, `supervisor-binding`, `approval-manager`, `command-validator`, `workflow-scorecard`, `run-trace`, `agent-trace-graph`, `event-logger`, `decision-trace`, `policy-engine` |