agentic-orchestrator 0.1.6 → 0.1.8

package/spec-files/completed/agentic_orchestrator_init_policy_ux_simplification_spec.md

@@ -14,6 +14,7 @@
 ### 0.1 Required Standards
 
 All implementation MUST preserve:
+
 - deterministic runtime behavior and MCP contract semantics
 - existing CLI command names (`aop init`, `aop run`, etc.)
 - schema validation as a hard gate for loaded policy
@@ -23,6 +24,7 @@ All implementation MUST preserve:
 ### 0.2 Upstream Inputs
 
 Implementing agents MUST read:
+
 - `apps/control-plane/src/cli/init-command-handler.ts`
 - `apps/control-plane/src/cli/cli-argument-parser.ts`
 - `apps/control-plane/src/cli/types.ts`
@@ -38,6 +40,7 @@ Implementing agents MUST read:
 ### 0.3 Current Baseline (Already Implemented in M39 Pre-Work)
 
 As of 2026-03-03, these pieces are already done:
+
 - `aop init` no longer copies schema files into target repos.
 - schema loading can fall back to bundled AOP schemas when repo-local schemas are absent.
 - `aop init` captures provider/model/SCM defaults.
@@ -89,6 +92,7 @@ Default users should configure only common controls; advanced users can opt into
 ### ADP-1: Defaults-First Policy Composition
 
 Runtime will always build a canonical full policy by:
+
 1. loading bundled `policy.defaults.yaml`,
 2. loading user `agentic/orchestrator/policy.yaml`,
 3. deep-merging user overrides over defaults,
@@ -105,6 +109,7 @@ Default `aop init` generates lean policy.
 ### ADP-3: Deterministic Merge Semantics
 
 Policy merge must use deterministic rules:
+
 - scalar values: override defaults
 - objects: recursive merge
 - arrays: replace when key exists in user policy
@@ -114,6 +119,7 @@ Policy merge must use deterministic rules:
 ### ADP-4: Validation of User Shape + Canonical Shape
 
 Two validations are required:
+
 1. optional user-shape validation (`policy.user.schema.json`) for clearer authoring errors
 2. mandatory canonical full validation (`policy.schema.json`) after merge
 
@@ -126,6 +132,7 @@ If user-shape validation is omitted for MVP, canonical full validation remains m
 ### 4.1 Default `aop init` Output (Lean Policy)
 
 Lean policy should include only common knobs:
+
 - `version`
 - `worktree.base_branch`
 - `supervisor.max_parallel_gate_runs`
@@ -155,11 +162,11 @@ notifications:
       enabled: false
     slack:
       enabled: false
-      webhook: ""
-      channel: "#aop-alerts"
+      webhook: ''
+      channel: '#aop-alerts'
     webhook:
       enabled: false
-      url: ""
+      url: ''
 ```
 
 ### 4.2 Advanced `aop init --advanced-policy` Output
@@ -169,6 +176,7 @@ Generates current fully expanded `policy.yaml` template with all advanced fields
 ### 4.3 Init Prompt Surface
 
 Interactive wizard continues to collect:
+
 - default provider
 - default model
 - SCM provider
@@ -179,6 +187,7 @@ Interactive wizard continues to collect:
 - framework for gates
 
 `adapters.yaml` activity-detector mapping:
+
 - `claude` -> `claude-jsonl`
 - `codex` -> `codex-rpc`
 - everything else -> `process-heuristic`
@@ -192,12 +201,14 @@ Interactive wizard continues to collect:
 ### INIT-T-001: Add Advanced Policy CLI Flag
 
 **Files:**
+
 - `apps/control-plane/src/cli/types.ts`
 - `apps/control-plane/src/cli/cli-argument-parser.ts`
 - `apps/control-plane/src/cli/help-command-handler.ts`
 - `apps/control-plane/src/interfaces/cli/bootstrap.ts`
 
 **Changes:**
+
 - add `advanced_policy?: boolean` to `CliOptions`
 - parse `--advanced-policy`
 - pass through to `InitCommandHandler.execute({ auto, force, advanced_policy })`
@@ -208,6 +219,7 @@ Interactive wizard continues to collect:
 **File:** `apps/control-plane/src/cli/init-command-handler.ts`
 
 **Changes:**
+
 - add `advanced_policy?: boolean` to `InitOptions`
 - branch policy template generation:
   - `advanced_policy === true` -> full template
@@ -218,6 +230,7 @@ Interactive wizard continues to collect:
 **File:** `apps/control-plane/src/cli/init-command-handler.ts`
 
 **Changes:**
+
 - keep existing full generator as `generateFullPolicyYaml(...)`
 - add `generateLeanPolicyYaml(...)`
 - keep `gates.yaml`, `agents.yaml`, `adapters.yaml`, prompts generation unchanged
@@ -229,15 +242,18 @@ Interactive wizard continues to collect:
 ### INIT-T-004: Add Bundled Defaults Artifact
 
 **New file:**
+
 - `agentic/orchestrator/defaults/policy.defaults.yaml`
 
 **Requirements:**
+
 - this file represents canonical defaults equivalent to current full template semantics
 - should be versioned and reviewed like other bundled contracts
 
 ### INIT-T-005: Implement Policy Composition Loader
 
 **New file (recommended):**
+
 - `apps/control-plane/src/application/services/policy-loader-service.ts`
 
 **Interface (suggested):**
@@ -248,10 +264,15 @@ interface LoadPolicyResult {
   mergedPolicy: Record<string, unknown>;
 }
 
-async function loadComposedPolicy(repoRoot: string, policyPath: string, schemaRegistry: SchemaRegistry): Promise<LoadPolicyResult>;
+async function loadComposedPolicy(
+  repoRoot: string,
+  policyPath: string,
+  schemaRegistry: SchemaRegistry,
+): Promise<LoadPolicyResult>;
 ```
 
 **Behavior:**
+
 - read defaults YAML (bundled path, not repo path)
 - read user policy YAML (repo path)
 - deep merge according to ADP-3 semantics
@@ -308,13 +329,16 @@ function mergePolicy(defaults: unknown, user: unknown): unknown {
 ### INIT-T-007: Optional User-Shape Schema
 
 **New file (optional but recommended):**
+
 - `agentic/orchestrator/schemas/policy.user.schema.json`
 
 **Purpose:**
+
 - validate lean authoring keys for better error messages before merge
 - canonical enforcement still happens via full schema on merged result
 
 **Schema policy:**
+
 - `additionalProperties: false` at top level for lean mode.
 - explicitly allow only intended user-editable sections.
 - do not include internal sections (`locks`, `rbac`, `config_precedence`, etc.) in lean schema.
@@ -326,11 +350,13 @@ function mergePolicy(defaults: unknown, user: unknown): unknown {
 ### INIT-T-008: Documentation Updates
 
 **Files:**
+
 - `README.md`
 - `agentic/orchestrator/tools.md` (if references policy generation behavior)
 - any init command docs/examples
 
 **Documentation requirements:**
+
 - clearly separate “common config” vs “advanced policy config”
 - add `--advanced-policy` usage examples
 - document merge semantics and where defaults live
@@ -340,6 +366,7 @@ function mergePolicy(defaults: unknown, user: unknown): unknown {
 **File:** `apps/control-plane/src/cli/init-command-handler.ts`
 
 **Changes:**
+
 - `next_steps` output should state whether lean or advanced policy was generated
 - mention `--advanced-policy` as escape hatch when lean mode is used
 
@@ -347,18 +374,18 @@ function mergePolicy(defaults: unknown, user: unknown): unknown {
 
 ## 6. File-Level Delta Matrix
 
-| File | Change Type | Scope |
-|---|---|---|
-| `apps/control-plane/src/cli/types.ts` | modify | add `advanced_policy` option |
-| `apps/control-plane/src/cli/cli-argument-parser.ts` | modify | parse `--advanced-policy` |
-| `apps/control-plane/src/cli/help-command-handler.ts` | modify | help text for new flag |
-| `apps/control-plane/src/interfaces/cli/bootstrap.ts` | modify | pass flag into init handler |
-| `apps/control-plane/src/cli/init-command-handler.ts` | modify | lean/full policy generation |
-| `apps/control-plane/src/core/kernel.ts` | modify | use composed policy loader |
-| `apps/control-plane/src/application/services/policy-loader-service.ts` | add | defaults + user merge + validate |
-| `agentic/orchestrator/defaults/policy.defaults.yaml` | add | bundled canonical defaults |
-| `agentic/orchestrator/schemas/policy.user.schema.json` | add (optional) | lean user policy shape |
-| `README.md` | modify | init UX and policy authoring docs |
+| File                                                                   | Change Type    | Scope                             |
+| ---------------------------------------------------------------------- | -------------- | --------------------------------- |
+| `apps/control-plane/src/cli/types.ts`                                  | modify         | add `advanced_policy` option      |
+| `apps/control-plane/src/cli/cli-argument-parser.ts`                    | modify         | parse `--advanced-policy`         |
+| `apps/control-plane/src/cli/help-command-handler.ts`                   | modify         | help text for new flag            |
+| `apps/control-plane/src/interfaces/cli/bootstrap.ts`                   | modify         | pass flag into init handler       |
+| `apps/control-plane/src/cli/init-command-handler.ts`                   | modify         | lean/full policy generation       |
+| `apps/control-plane/src/core/kernel.ts`                                | modify         | use composed policy loader        |
+| `apps/control-plane/src/application/services/policy-loader-service.ts` | add            | defaults + user merge + validate  |
+| `agentic/orchestrator/defaults/policy.defaults.yaml`                   | add            | bundled canonical defaults        |
+| `agentic/orchestrator/schemas/policy.user.schema.json`                 | add (optional) | lean user policy shape            |
+| `README.md`                                                            | modify         | init UX and policy authoring docs |
 
 ---
 
@@ -393,6 +420,7 @@ function mergePolicy(defaults: unknown, user: unknown): unknown {
 **File:** `apps/control-plane/test/init-wizard.spec.ts`
 
 Add:
+
 - `GIVEN_default_init_WHEN_policy_generated_THEN_policy_is_lean_shape`
 - `GIVEN_advanced_policy_flag_WHEN_policy_generated_THEN_policy_is_full_shape`
 - `GIVEN_advanced_policy_flag_WHEN_help_rendered_THEN_flag_is_documented`
@@ -402,6 +430,7 @@ Add:
 **New file:** `apps/control-plane/test/policy-loader-service.spec.ts`
 
 Add:
+
 - `GIVEN_defaults_and_lean_user_policy_WHEN_composed_THEN_merged_policy_is_valid`
 - `GIVEN_full_user_policy_WHEN_composed_THEN_user_values_override_defaults`
 - `GIVEN_array_override_WHEN_composed_THEN_array_replaces_default_array`
@@ -412,12 +441,14 @@ Add:
 **File:** `apps/control-plane/test/kernel.spec.ts`
 
 Add:
+
 - `GIVEN_lean_policy_repo_WHEN_kernel_loads_THEN_runtime_boots_successfully`
 - `GIVEN_full_policy_repo_WHEN_kernel_loads_THEN_runtime_boots_successfully`
 
 ### 8.4 Regression Test Runs
 
 Required run list:
+
 - `npm run lint`
 - `npm run typecheck`
 - `npm test`
@@ -427,6 +458,7 @@ Required run list:
 ### 8.5 Determinism and Edge Cases (Required)
 
 Add explicit tests for:
+
 - merge determinism with object key order differences (same result hash)
 - array replacement semantics for `required_modes` and `protected_areas`
 - missing defaults artifact error path (clear actionable message)
@@ -467,6 +499,7 @@ Document lean default and advanced mode; include migration note for teams that p
 ## 11. Definition of Done
 
 This spec is complete when:
+
 1. INIT-T-001 through INIT-T-009 are implemented.
 2. acceptance criteria in Section 7 are all checked.
 3. test plan in Section 8 passes in CI.

package/spec-files/completed/agentic_orchestrator_mcp_formalization_spec.md

@@ -82,6 +82,7 @@ All mutating tools MUST require `operation_id`.
 ### 3.5 Hybrid Transport Rollout
 
 `ToolClient` abstraction is mandatory:
+
 - `InProcessToolClient` for tests/fallback.
 - `McpToolClient` for production path.
 
@@ -109,6 +110,7 @@ agentic/
 ### 4.1 `catalog.json` Contract
 
 Each tool entry MUST contain:
+
 - `name`
 - `description`
 - `input_schema_ref`
@@ -121,6 +123,7 @@ Each tool entry MUST contain:
 ### 4.2 `protocol.json` Contract
 
 Must pin:
+
 - MCP protocol version supported
 - SDK package + version
 - enabled transport modes (`stdio` required; others optional)
@@ -128,6 +131,7 @@ Must pin:
 ### 4.3 Error Envelope
 
 All failures MUST return:
+
 - `ok: false`
 - `error.code`
 - `error.message`
@@ -139,28 +143,35 @@ All failures MUST return:
 ## 5. Runtime Components
 
 1. `ToolRegistryLoader`
+
 - loads registry
 - validates uniqueness and schema refs
 
 2. `ToolContractValidator`
+
 - validates input pre-handler
 - validates output post-handler
 
 3. `TokenAuthVerifier`
+
 - verifies signature and expiry
 - extracts trusted actor claims
 
 4. `ToolAuthorizer`
+
 - applies intersection of registry roles and policy roles
 
 5. `OperationLedger`
+
 - writes and resolves idempotent operation outcomes for mutating calls
 
 6. `KernelToolExecutor`
+
 - maps `handler_id` to domain method call
 - normalizes errors
 
 7. `McpServerAdapter`
+
 - implements protocol endpoints via registry/executor
 
 ---
@@ -170,6 +181,7 @@ All failures MUST return:
 ### 6.1 Token Claims
 
 Required claims:
+
 - `run_id`
 - `session_id`
 - `actor_type`
@@ -178,6 +190,7 @@ Required claims:
 - `expires_at`
 
 Optional claims:
+
 - `feature_scope` (for feature-limited workers)
 
 ### 6.2 Validation Rules
@@ -200,6 +213,7 @@ Optional claims:
 ### 7.1 Mutating Tools
 
 Mutating tools include at least:
+
 - `feature.init`
 - `feature.state_patch`
 - `feature.log_append`
@@ -227,6 +241,7 @@ Mutating tools include at least:
 ### 8.1 Pinning Requirement
 
 Implementation MUST pin and document:
+
 - MCP protocol version
 - SDK package/version
 - transport implementation details
@@ -242,6 +257,7 @@ Implementation MUST pin and document:
 ## 9. Observability Contract
 
 Every tool call MUST emit structured logs with:
+
 - `run_id`
 - `operation_id` (if mutating)
 - `feature_id` (if applicable)
@@ -252,6 +268,7 @@ Every tool call MUST emit structured logs with:
 - `error_code` (if any)
 
 Metrics MUST include:
+
 - calls by tool/role
 - failure rates by error code
 - retry and idempotency hit rates
@@ -286,6 +303,7 @@ This plan coordinates this spec and `agentic_orchestrator_single_global_orchestr
 - bind existing handlers via `handler_id`
 
 Exit gate:
+
 - registry validates
 - generated tools doc matches registry
 
@@ -295,6 +313,7 @@ Exit gate:
 - operation ledger and mutating call idempotency
 
 Exit gate:
+
 - auth failure paths tested
 - duplicate mutation calls are safe
 
@@ -304,6 +323,7 @@ Exit gate:
 - pin protocol and sdk versions
 
 Exit gate:
+
 - protocol conformance tests pass
 
 ### M13: ToolClient Migration
@@ -312,6 +332,7 @@ Exit gate:
 - migrate CLI/Supervisor call paths
 
 Exit gate:
+
 - end-to-end runs on both transports
 
 ### M14-M17: Global Orchestrator Topology Refactor
@@ -319,6 +340,7 @@ Exit gate:
 - executed per global-orchestrator spec milestones
 
 Exit gate:
+
 - session topology invariants pass (`1 + 3N`)
 
 ### M18: Production Promotion
@@ -327,6 +349,7 @@ Exit gate:
 - maintain in-process fallback for tests/recovery only
 
 Exit gate:
+
 - parity suite green
 - rollout checklist signed off
 
@@ -343,6 +366,7 @@ Exit gate:
 ### 12.2 Conformance Suite
 
 Same scenario must pass via both transports for critical paths:
+
 - init -> plan -> patch -> gates -> merge
 - lock conflict and collision outcomes
 - retried mutation calls
@@ -376,4 +400,3 @@ Same scenario must pass via both transports for critical paths:
   - Mitigation: keep in-process fallback until M18 exit gate.
 - Risk: schema churn causing breakages.
   - Mitigation: strict versioning and migration policy.
-

package/spec-files/completed/agentic_orchestrator_single_global_orchestrator_spec.md

@@ -37,6 +37,7 @@
 Current behavior creates per-feature orchestrator sessions (`4N`).
 
 Target behavior:
+
 - one global orchestrator session per run
 - worker sessions per active feature
 - queued features do not allocate worker sessions
@@ -55,6 +56,7 @@ Queued features are excluded from `N` until promoted to active.
 A repo must have at most one active orchestrator run at a time.
 
 Canonical lease fields in index:
+
 - `runtime_sessions.run_id`
 - `runtime_sessions.owner_instance_id`
 - `runtime_sessions.lease_id`
@@ -63,11 +65,13 @@ Canonical lease fields in index:
 ### 3.2 Start Behavior
 
 On `aop run` start:
+
 1. acquire run lease if absent
 2. if active lease exists and is fresh -> fail with `run_already_active`
 3. if active lease stale and caller passed takeover flag -> claim lease and continue
 
 Takeover contract:
+
 - CLI flag: `--takeover-stale-run`
 - default (flag absent): stale lease does not get reclaimed automatically
 - when flag present: reclaim stale lease deterministically and continue
@@ -108,6 +112,7 @@ Queued features MUST NOT consume session slots or violate `1 + 3N`.
 ### 5.1 `index.json` Runtime Session Object
 
 Standardize on one object:
+
 - `runtime_sessions.run_id` (string)
 - `runtime_sessions.orchestrator_session_id` (string)
 - `runtime_sessions.provider` (string)
@@ -124,6 +129,7 @@ Standardize on one object:
 Keep existing `cluster` fields for compatibility.
 
 Invariant:
+
 - For each active feature:
   - `state.cluster.orchestrator_session_id == index.runtime_sessions.orchestrator_session_id`
 
@@ -137,6 +143,7 @@ Invariant:
 ## 6. Supervisor Loop Under Global Orchestrator
 
 Each loop iteration:
+
 1. collect per-feature summaries
 2. global orchestrator decides prioritization/arbitration
 3. dispatch planner/builder/qa work
@@ -144,6 +151,7 @@ Each loop iteration:
 5. reconcile outcomes and update canonical state
 
 Global orchestrator decisions MUST govern:
+
 - lock contention strategy
 - collision resolution ordering
 - merge readiness sequencing
@@ -258,6 +266,7 @@ Global orchestrator decisions MUST govern:
 ## 12. Dependency Note
 
 This spec depends on security, idempotency, and transport contracts from:
+
 - `agentic_orchestrator_mcp_formalization_spec.md`
 
 Status note (as of February 28, 2026): foundational MCP formalization artifacts and runtime boundaries are implemented; this topology spec now targets the remaining M14-M18 topology changes on top of that baseline.