agentic-orchestrator 0.1.4 → 0.1.6

package/.claude/settings.local.json

@@ -9,7 +9,12 @@
       "Bash(npx vitest:*)",
       "Bash(grep:*)",
       "Bash(ls:*)",
-      "Bash(wc:*)"
+      "Bash(wc:*)",
+      "Bash(npm test:*)",
+      "Bash(npx eslint:*)",
+      "Bash(node:*)",
+      "Bash(tsc:*)",
+      "Bash(./node_modules/.bin/tsc:*)"
     ]
   }
 }

package/README.md

@@ -95,39 +95,42 @@ Agentic-Orchestrator/
 ├── .aop/
 │   ├── features/                      # runtime-generated feature artifacts
 │   │   └── index.json                # global orchestration index
-│   ├── analytics/                     # agent performance analytics
 │   └── runtime/
 │       └── operation-ledger/
 ├── agentic/
-│   ├── orchestrator/                  # policy/gates/agents config + schemas + prompts
-│   │   ├── policy.yaml
-│   │   ├── gates.yaml
-│   │   ├── agents.yaml
-│   │   ├── multi-project.yaml         # optional multi-project configuration
-│   │   ├── schemas/
-│   │   └── tools.md
+│   └── orchestrator/                  # policy/gates/agents config + schemas + prompts + tools
+│       ├── policy.yaml
+│       ├── gates.yaml
+│       ├── agents.yaml
+│       ├── adapters.yaml
+│       ├── defaults/
+│       │   └── policy.defaults.yaml   # bundled canonical policy defaults (deep-merged at runtime)
+│       ├── schemas/                   # JSON schemas (policy, state, plan, gates, agents, etc.)
+│       ├── prompts/                   # role-specific system prompts
+│       └── tools/                    # MCP tool contracts: catalog.json, per-tool input/output schemas
 ├── apps/
 │   └── control-plane/
 │       ├── src/
 │       │   ├── cli/                   # aop CLI commands and handlers
-│       │   ├── core/                  # deterministic kernel
+│       │   ├── core/                  # deterministic kernel (kernel.ts, schemas.ts)
 │       │   ├── application/
-│       │   │   └── services/          # domain services (cost, reactions, pr-monitor, etc.)
+│       │   │   └── services/          # 20+ domain services (plan, patch, gates, locks, policy-loader, etc.)
+│       │   ├── interfaces/
+│       │   │   └── cli/               # bootstrap.ts — CLI command dispatch
+│       │   ├── mcp/                   # MCP tool runtime and tool-registry-loader
 │       │   ├── providers/             # provider resolution + adapter
 │       │   └── supervisor/            # runtime orchestration loop
-│       ├── test/                      # Vitest suites (68 files / 899 tests)
+│       ├── test/                      # Vitest suites (71 files / 1155 tests)
 │       ├── project.json               # Nx targets
 │       └── vitest.config.ts
-├── packages/
-│   └── web-dashboard/                 # Next.js 14 web dashboard (aop dashboard)
 ├── docker/
 │   ├── mcp.Dockerfile
 │   ├── mcp.entrypoint.sh
 │   └── mcp.compose.yaml
 ├── spec-files/
-│   ├── agentic_orchestrator_spec.md
-│   ├── agentic_orchestrator_feature_gaps_closure_spec.md
-│   └── progress.md                     # implementation continuity log
+│   ├── completed/                     # completed spec files
+│   ├── outstanding/                   # pending / in-progress specs
+│   └── progress.md                    # implementation continuity log
 └── README.md
 ```
 
@@ -373,19 +376,43 @@ When `cleanup.auto_after_merge` is enabled in `policy.yaml`, the runtime automat
 
 ### `init`
 
-Initialises agentic orchestrator configuration in the current directory. Generates `policy.yaml`, `gates.yaml`, `agents.yaml`, and system prompt templates.
+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` and `scm-provider`.
+
+Schema files are bundled with AOP and validated from the installation path; `aop init` does not copy schemas into the target repository.
 
 ```bash
-# Interactive wizard
+# Interactive wizard (generates lean policy.yaml with common controls only)
 aop init
 
-# Non-interactive (all defaults)
+# Non-interactive (all defaults, lean policy)
 aop init --auto
 
+# Generate full explicit policy.yaml with all advanced controls
+aop init --advanced-policy
+
+# Non-interactive with full policy
+aop init --auto --advanced-policy
+
 # Overwrite existing configuration
 aop init --force
 ```
 
+#### Policy Modes
+
+**Lean policy (default):** `aop init` emits a minimal `policy.yaml` containing only the common controls users typically customise — `worktree.base_branch`, `supervisor.max_parallel_gate_runs`, `dashboard`, `merge_policy`, `notifications`, and `recovery`. All other fields (RBAC, locks, execution, implementation constraints, etc.) are provided by the bundled `policy.defaults.yaml` at runtime.
+
+**Full policy (`--advanced-policy`):** Generates the complete `policy.yaml` with all controls expanded, useful for teams that need to audit or customise advanced settings.
+
+#### Runtime Policy Composition
+
+At runtime the kernel always composes a canonical full policy by:
+1. Loading bundled `agentic/orchestrator/defaults/policy.defaults.yaml`
+2. Loading `agentic/orchestrator/policy.yaml` from your repository
+3. Deep-merging user overrides over defaults (scalars replace, objects merge, arrays replace wholesale)
+4. Validating the merged result against the full `policy.schema.json`
+
+Existing repositories with full `policy.yaml` files continue to work without changes — user values override defaults entirely.
+
 ### `dashboard`
 
 Starts the web dashboard server (`packages/web-dashboard/`). Provides a real-time Kanban view of all features, review approval/denial, checkout, and SSE-based live updates.
@@ -680,41 +707,41 @@ The MCP contracts validator checks: protocol pinning, `catalog.json`/`tools.md`/
 
 ### Tool definitions
 
-| Tool                     | Purpose                                                                | Mutates state/files | Typical caller role(s)                 |
-|--------------------------|------------------------------------------------------------------------|---------------------|----------------------------------------|
-| `feature.discover_specs` | Discover canonical `spec.md` files under `.aop/features/*`             | No                  | orchestrator, system                   |
-| `feature.init`           | Initialize feature folder/state and ensure branch/worktree             | Yes                 | orchestrator, system                   |
-| `feature.get_context`    | Return spec + state + plan + latest evidence + QA index bundle         | No                  | orchestrator, planner, builder, qa     |
-| `feature.state_get`      | Read parsed state front matter/body                                    | No                  | orchestrator/planner/builder/qa/system |
-| `feature.state_patch`    | Patch canonical feature state with version guard                       | Yes                 | orchestrator, system                   |
-| `feature.log_append`     | Append stamped note to feature decision log                            | Yes                 | orchestrator, system                   |
-| `plan.submit`            | Validate and accept initial plan (schema/policy/lock/collision checks) | Yes                 | orchestrator, planner                  |
-| `plan.get`               | Get accepted plan                                                      | No                  | orchestrator, planner, builder, qa     |
-| `plan.update`            | Submit versioned plan revision (`+1` version) with full revalidation   | Yes                 | orchestrator, planner                  |
-| `repo.ensure_worktree`   | Ensure feature branch + worktree exist                                 | Yes                 | orchestrator, system                   |
-| `repo.apply_patch`       | Apply unified diff with plan/policy/path/lock enforcement              | Yes                 | builder, qa, orchestrator              |
-| `repo.status`            | Return porcelain status from feature worktree                          | No                  | builder, orchestrator                  |
-| `repo.diff`              | Return git diff for feature worktree                                   | No                  | builder, qa, orchestrator              |
-| `repo.read_file`         | Read file content from feature worktree path                           | No                  | planner, builder, qa, orchestrator     |
-| `repo.search`            | Repo-safe text search (`rg`) in feature worktree                       | No                  | planner, builder, qa, orchestrator     |
-| `repo.diff_bundle`       | Return review bundle (stat/full diff/files/latest gate summary)        | No                  | orchestrator                           |
-| `feature.ready_to_merge` | Commit + merge promotion after required gates and approval checks      | Yes                 | orchestrator, system                   |
-| `feature.delete`         | Delete feature runtime artifacts and optional local git/worktree state | Yes                 | orchestrator, system                   |
-| `feature.send_message`   | Send a message to the active agent session for a feature               | Yes                 | orchestrator, system                   |
-| `gates.list`             | List available gate profiles/modes                                     | No                  | orchestrator, builder, qa              |
-| `gates.run`              | Execute gate profile/mode, capture logs/evidence, enforce thresholds   | Yes                 | builder, qa, orchestrator              |
-| `evidence.latest`        | Return latest evidence summary for feature                             | No                  | qa, orchestrator                       |
-| `qa.test_index_get`      | Return QA index + pending obligations summary                          | No                  | qa, orchestrator                       |
-| `qa.test_index_update`   | Update QA hunk statuses with version guard and evidence refs           | Yes                 | qa, orchestrator, system               |
-| `locks.acquire`          | Acquire/renew resource lease lock for feature                          | Yes                 | orchestrator, system                   |
-| `locks.release`          | Release held resource lock                                             | Yes                 | orchestrator, system                   |
-| `collisions.scan`        | Compute collision matrix across accepted plans                         | No                  | planner, orchestrator                  |
-| `report.dashboard`       | Return global orchestration summary (includes cost and PR metadata)    | No                  | orchestrator                           |
-| `report.feature_summary` | Return per-feature state/diff/evidence summary                         | No                  | orchestrator                           |
-| `cost.record`            | Record a cost entry for a feature (token usage, API cost)              | Yes                 | orchestrator, system                   |
-| `cost.get`               | Return accumulated cost for a feature                                  | No                  | orchestrator, system                   |
-| `performance.record_outcome` | Record feature outcome (status, retries, duration, cost) for analytics | Yes             | orchestrator, system                   |
-| `performance.get_analytics`  | Return aggregated performance metrics by provider/model            | No                  | orchestrator, system                   |
+| Tool                         | Purpose                                                                | Mutates state/files | Typical caller role(s)                 |
+|------------------------------|------------------------------------------------------------------------|---------------------|----------------------------------------|
+| `feature.discover_specs`     | Discover canonical `spec.md` files under `.aop/features/*`             | No                  | orchestrator, system                   |
+| `feature.init`               | Initialize feature folder/state and ensure branch/worktree             | Yes                 | orchestrator, system                   |
+| `feature.get_context`        | Return spec + state + plan + latest evidence + QA index bundle         | No                  | orchestrator, planner, builder, qa     |
+| `feature.state_get`          | Read parsed state front matter/body                                    | No                  | orchestrator/planner/builder/qa/system |
+| `feature.state_patch`        | Patch canonical feature state with version guard                       | Yes                 | orchestrator, system                   |
+| `feature.log_append`         | Append stamped note to feature decision log                            | Yes                 | orchestrator, system                   |
+| `plan.submit`                | Validate and accept initial plan (schema/policy/lock/collision checks) | Yes                 | orchestrator, planner                  |
+| `plan.get`                   | Get accepted plan                                                      | No                  | orchestrator, planner, builder, qa     |
+| `plan.update`                | Submit versioned plan revision (`+1` version) with full revalidation   | Yes                 | orchestrator, planner                  |
+| `repo.ensure_worktree`       | Ensure feature branch + worktree exist                                 | Yes                 | orchestrator, system                   |
+| `repo.apply_patch`           | Apply unified diff with plan/policy/path/lock enforcement              | Yes                 | builder, qa, orchestrator              |
+| `repo.status`                | Return porcelain status from feature worktree                          | No                  | builder, orchestrator                  |
+| `repo.diff`                  | Return git diff for feature worktree                                   | No                  | builder, qa, orchestrator              |
+| `repo.read_file`             | Read file content from feature worktree path                           | No                  | planner, builder, qa, orchestrator     |
+| `repo.search`                | Repo-safe text search (`rg`) in feature worktree                       | No                  | planner, builder, qa, orchestrator     |
+| `repo.diff_bundle`           | Return review bundle (stat/full diff/files/latest gate summary)        | No                  | orchestrator                           |
+| `feature.ready_to_merge`     | Commit + merge promotion after required gates and approval checks      | Yes                 | orchestrator, system                   |
+| `feature.delete`             | Delete feature runtime artifacts and optional local git/worktree state | Yes                 | orchestrator, system                   |
+| `feature.send_message`       | Send a message to the active agent session for a feature               | Yes                 | orchestrator, system                   |
+| `gates.list`                 | List available gate profiles/modes                                     | No                  | orchestrator, builder, qa              |
+| `gates.run`                  | Execute gate profile/mode, capture logs/evidence, enforce thresholds   | Yes                 | builder, qa, orchestrator              |
+| `evidence.latest`            | Return latest evidence summary for feature                             | No                  | qa, orchestrator                       |
+| `qa.test_index_get`          | Return QA index + pending obligations summary                          | No                  | qa, orchestrator                       |
+| `qa.test_index_update`       | Update QA hunk statuses with version guard and evidence refs           | Yes                 | qa, orchestrator, system               |
+| `locks.acquire`              | Acquire/renew resource lease lock for feature                          | Yes                 | orchestrator, system                   |
+| `locks.release`              | Release held resource lock                                             | Yes                 | orchestrator, system                   |
+| `collisions.scan`            | Compute collision matrix across accepted plans                         | No                  | planner, orchestrator                  |
+| `report.dashboard`           | Return global orchestration summary (includes cost and PR metadata)    | No                  | orchestrator                           |
+| `report.feature_summary`     | Return per-feature state/diff/evidence summary                         | No                  | orchestrator                           |
+| `cost.record`                | Record a cost entry for a feature (token usage, API cost)              | Yes                 | orchestrator, system                   |
+| `cost.get`                   | Return accumulated cost for a feature                                  | No                  | orchestrator, system                   |
+| `performance.record_outcome` | Record feature outcome (status, retries, duration, cost) for analytics | Yes                 | orchestrator, system                   |
+| `performance.get_analytics`  | Return aggregated performance metrics by provider/model                | No                  | orchestrator, system                   |
 
 ### Role expectations at a glance
 

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

@@ -0,0 +1,212 @@
+# Canonical bundled policy defaults for AOP.
+# These values are merged with the user's policy.yaml at runtime.
+# User values override these defaults (scalars replace, objects merge recursively, arrays replace).
+# Do not edit this file in user repos — it is a bundled AOP artifact.
+version: 1
+commit_policy:
+  allow_commit: false
+  allow_merge: false
+patch_policy:
+  enforce_plan: true
+  enforce_allowed_areas: true
+locks:
+  resources:
+    - openapi
+    - events
+    - db_migrations
+  contract_to_resource:
+    openapi: openapi
+    events: events
+    db: db_migrations
+  lease_ttl_seconds: 300
+  acquire_behavior: wait
+  default_wait_timeout_seconds: 300
+  acquire_backoff:
+    initial_ms: 200
+    max_ms: 5000
+    multiplier: 2
+    jitter_ms: 150
+protected_areas:
+  - agentic/orchestrator/policy.yaml
+required_modes:
+  - fast
+  - full
+required_merge_mode: merge
+collision_policy: reject
+config_precedence:
+  policy_hard_constraints:
+    - execution.default_step_timeout_seconds
+    - testing.coverage.minimums
+    - testing.coverage.targets
+  gates_profile_defaults:
+    - profiles
+  plan_verification_overrides:
+    - verification_overrides
+path_rules:
+  matching: repo_prefix
+  normalize_paths: true
+  allow_symlink_traversal: false
+execution:
+  default_step_timeout_seconds: 600
+  retry_policy:
+    transient_max_retries: 1
+    transient_error_codes:
+      - 124
+    non_retryable_error_codes:
+      - 2
+      - 126
+      - 127
+  env_allowlist:
+    - PATH
+    - HOME
+implementation:
+  workspace: nx
+testing:
+  framework: vitest
+  coverage:
+    minimums:
+      line: 0.7
+      branch: 0.7
+    targets:
+      line: 1.0
+      branch: 1.0
+merge_policy:
+  require_user_approval: true
+  allowed_strategies:
+    - merge_commit
+    - squash
+    - rebase
+worktree:
+  base_branch: main
+rbac:
+  orchestrator:
+    - feature.discover_specs
+    - feature.init
+    - feature.get_context
+    - feature.state_get
+    - feature.state_patch
+    - feature.log_append
+    - plan.submit
+    - plan.get
+    - plan.update
+    - repo.ensure_worktree
+    - repo.apply_patch
+    - repo.status
+    - repo.diff
+    - repo.read_file
+    - repo.search
+    - repo.diff_bundle
+    - gates.list
+    - gates.run
+    - evidence.latest
+    - qa.test_index_get
+    - qa.test_index_update
+    - locks.acquire
+    - locks.release
+    - collisions.scan
+    - report.dashboard
+    - report.feature_summary
+    - feature.ready_to_merge
+    - feature.delete
+    - feature.send_message
+    - cost.record
+    - cost.get
+    - performance.record_outcome
+    - performance.get_analytics
+  planner:
+    - feature.get_context
+    - feature.state_get
+    - plan.submit
+    - plan.update
+    - collisions.scan
+    - repo.read_file
+    - repo.search
+    - performance.get_analytics
+  builder:
+    - feature.get_context
+    - feature.state_get
+    - repo.apply_patch
+    - repo.status
+    - repo.diff
+    - repo.read_file
+    - repo.search
+    - gates.run
+    - performance.get_analytics
+  qa:
+    - feature.get_context
+    - feature.state_get
+    - repo.apply_patch
+    - repo.diff
+    - repo.read_file
+    - repo.search
+    - gates.run
+    - evidence.latest
+    - qa.test_index_get
+    - qa.test_index_update
+    - performance.get_analytics
+  system:
+    - "*"
+recovery:
+  orchestrator_session_reattach_timeout_ms: 5000
+  orphan_session_cleanup_enabled: true
+supervisor:
+  max_iterations_per_phase: 6
+  max_parallel_gate_runs: 2
+  agent_idle_threshold_ms: 300000
+cleanup:
+  auto_after_merge: false
+  grace_period_seconds: 3600
+dashboard:
+  enabled: true
+  port: 3000
+notifications:
+  enabled: false
+  channels:
+    desktop:
+      enabled: false
+    slack:
+      enabled: false
+      webhook: ""
+      channel: "#aop-alerts"
+    webhook:
+      enabled: false
+      url: ""
+  routing:
+    critical:
+      - desktop
+      - slack
+    warning:
+      - slack
+      - desktop
+    info:
+      - slack
+reactions:
+  gate_failed:
+    enabled: true
+    max_retries: 2
+    action: retry_with_agent_repair
+    escalate_after: 2
+    retry_delay_ms: 30000
+  agent_stuck:
+    enabled: true
+    action: notify_only
+    idle_threshold_ms: 300000
+    escalate_after: 2
+  collision_detected:
+    enabled: true
+    action: notify_only
+  ready_to_merge:
+    enabled: true
+    action: notify_only
+  changes_requested:
+    enabled: false
+    action: send_review_context_to_agent
+    escalate_after: 2
+budget:
+  per_feature_limit_usd: 50.00
+  alert_threshold: 0.8
+issue_tracker:
+  enabled: false
+  type: github
+  config:
+    repo: ""

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

@@ -1,12 +1,25 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://example.local/agentic/adapters.schema.json",
+  "description": "Adapter slot assignments for the orchestrator. Each field names a registered adapter implementation to use for that slot. Loaded from agentic/orchestrator/adapters.yaml.",
   "type": "object",
   "additionalProperties": false,
   "properties": {
-    "notification-channel": { "type": "string" },
-    "scm-provider": { "type": "string" },
-    "issue-tracker": { "type": "string" },
-    "activity-detector": { "type": "string" }
+    "notification-channel": {
+      "type": "string",
+      "description": "Name of the registered adapter used to deliver notifications (e.g. 'slack', 'desktop'). Resolved against the adapter registry at supervisor startup."
+    },
+    "scm-provider": {
+      "type": "string",
+      "description": "Name of the registered source control adapter (e.g. 'github'). Used by PrMonitorService for PR creation, status polling, and merge operations."
+    },
+    "issue-tracker": {
+      "type": "string",
+      "description": "Name of the registered issue tracker adapter (e.g. 'github', 'linear', 'jira'). Used when issue_tracker.enabled is true in policy."
+    },
+    "activity-detector": {
+      "type": "string",
+      "description": "Name of the adapter used to detect agent activity from session output logs (e.g. 'claude-jsonl'). Defaults to 'claude-jsonl' if not specified."
+    }
   }
 }

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

@@ -1,45 +1,88 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://example.local/agentic/agents.schema.json",
+  "description": "Agent role and runtime provider configuration for the Agentic Orchestrator.",
   "type": "object",
-  "required": ["version", "roles"],
+  "required": [
+    "version",
+    "roles"
+  ],
   "additionalProperties": false,
   "properties": {
-    "version": { "type": "number" },
+    "version": {
+      "type": "number",
+      "description": "Schema version number for this agents configuration file."
+    },
     "roles": {
       "type": "object",
-      "required": ["planner", "builder", "qa"],
+      "description": "Per-role prompt configuration keyed by role name (planner, builder, qa).",
+      "required": [
+        "planner",
+        "builder",
+        "qa"
+      ],
       "properties": {
-        "planner": { "$ref": "#/$defs/roleCfg" },
-        "builder": { "$ref": "#/$defs/roleCfg" },
-        "qa": { "$ref": "#/$defs/roleCfg" }
+        "planner": {
+          "$ref": "#/$defs/roleCfg",
+          "description": "Configuration for the planner agent role."
+        },
+        "builder": {
+          "$ref": "#/$defs/roleCfg",
+          "description": "Configuration for the builder agent role."
+        },
+        "qa": {
+          "$ref": "#/$defs/roleCfg",
+          "description": "Configuration for the QA agent role."
+        }
       }
     },
     "missing_prompt_behavior": {
       "type": "string",
-      "enum": ["ignore", "error"],
+      "description": "What to do when a role's system_prompt_path file cannot be read. 'ignore' silently skips it (role gets no system prompt); 'error' throws MISSING_ROLE_PROMPT and aborts the run.",
+      "enum": [
+        "ignore",
+        "error"
+      ],
       "default": "ignore"
     },
     "runtime": {
       "type": "object",
+      "description": "Provider and model settings used to select the AI backend. CLI flags and environment variables (AOP_AGENT_PROVIDER, AOP_AGENT_MODEL) take precedence over these values.",
       "properties": {
         "default_provider": {
           "type": "string",
-          "enum": ["codex", "claude", "gemini", "custom", "kiro-cli", "copilot"]
+          "description": "Default AI provider name (e.g. 'codex', 'claude', 'gemini'). Overridden by --agent-provider CLI flag or AOP_AGENT_PROVIDER env var.",
+          "enum": [
+            "codex",
+            "claude",
+            "gemini",
+            "custom",
+            "kiro-cli",
+            "copilot"
+          ]
+        },
+        "default_model": {
+          "type": "string",
+          "description": "Default model string passed to the provider SDK. Overridden by --agent-model CLI flag or AOP_AGENT_MODEL env var."
         },
-        "default_model": { "type": "string" },
         "default_agent_config": {
-          "type": "object"
+          "type": "object",
+          "description": "Default agent configuration object forwarded to the provider SDK when no provider-specific entry exists in provider_configs."
+        },
+        "provider_config_env": {
+          "type": "string",
+          "description": "Name of an environment variable whose value is a JSON provider-config blob. Takes lower priority than the CLI flag but higher than this file."
         },
-        "provider_config_env": { "type": "string" },
         "provider_configs": {
           "type": "object",
+          "description": "Per-provider configuration objects keyed by provider name. When the active provider matches a key here its value is used instead of default_agent_config.",
           "additionalProperties": {
             "type": "object"
           }
         },
         "role_provider_overrides": {
-          "type": "object"
+          "type": "object",
+          "description": "Reserved for future per-role provider overrides. Parsed but not yet consumed by the supervisor."
         }
       }
     }
@@ -47,10 +90,12 @@
   "$defs": {
     "roleCfg": {
       "type": "object",
+      "description": "Configuration block shared by all agent roles.",
       "additionalProperties": false,
       "properties": {
         "system_prompt_path": {
-          "type": "string"
+          "type": "string",
+          "description": "Repo-relative path to the system prompt file loaded by the supervisor for this role. If missing, behaviour is controlled by missing_prompt_behavior."
         }
       }
     }