agentic-orchestrator 0.1.4 → 0.1.6

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

@@ -0,0 +1,165 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.local/agentic/policy.user.schema.json",
+  "description": "User-editable policy overrides. These are deep-merged over the bundled defaults to produce the effective policy. Only the most commonly configured fields are exposed here.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "type": "number",
+      "description": "Schema version number."
+    },
+    "worktree": {
+      "type": "object",
+      "description": "Git worktree settings. See policy.schema.json for full field descriptions.",
+      "additionalProperties": false,
+      "properties": {
+        "base_branch": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Git branch that feature branches are created from and merged into (e.g. 'main')."
+        },
+        "post_create": {
+          "type": "array",
+          "description": "Shell commands run after a new feature worktree is created.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "symlinks": {
+          "type": "array",
+          "description": "Repo-relative paths to symlink into every new feature worktree.",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "supervisor": {
+      "type": "object",
+      "description": "Supervisor loop tuning. See policy.schema.json for full field descriptions.",
+      "additionalProperties": false,
+      "properties": {
+        "max_parallel_gate_runs": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum number of gate runs that may execute concurrently across features."
+        },
+        "max_iterations_per_phase": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Maximum agent iterations per phase before escalation."
+        },
+        "agent_idle_threshold_ms": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Milliseconds of agent inactivity before triggering the agent_stuck reaction."
+        }
+      }
+    },
+    "dashboard": {
+      "type": "object",
+      "description": "Dashboard HTTP server settings.",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Whether the dashboard HTTP server is started."
+        },
+        "port": {
+          "type": "number",
+          "minimum": 1,
+          "maximum": 65535,
+          "description": "Port the dashboard HTTP server listens on."
+        }
+      }
+    },
+    "merge_policy": {
+      "type": "object",
+      "description": "Merge controls.",
+      "additionalProperties": false,
+      "properties": {
+        "require_user_approval": {
+          "type": "boolean",
+          "description": "When true, a user approval token must be supplied before the orchestrator merges a feature."
+        },
+        "allowed_strategies": {
+          "type": "array",
+          "description": "Permitted merge strategies ('merge_commit', 'squash', 'rebase').",
+          "items": {
+            "type": "string",
+            "enum": [
+              "merge_commit",
+              "squash",
+              "rebase"
+            ]
+          }
+        }
+      }
+    },
+    "notifications": {
+      "type": "object",
+      "description": "Notification delivery settings. See policy.schema.json for full field descriptions.",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Master switch for all notification channels."
+        },
+        "channels": {
+          "type": "object",
+          "properties": {
+            "desktop": {
+              "type": "object",
+              "properties": {
+                "enabled": {
+                  "type": "boolean"
+                }
+              }
+            },
+            "slack": {
+              "type": "object",
+              "properties": {
+                "enabled": {
+                  "type": "boolean"
+                },
+                "webhook": {
+                  "type": "string"
+                },
+                "channel": {
+                  "type": "string"
+                }
+              }
+            },
+            "webhook": {
+              "type": "object",
+              "properties": {
+                "enabled": {
+                  "type": "boolean"
+                },
+                "url": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "recovery": {
+      "type": "object",
+      "description": "Orphaned session recovery settings.",
+      "additionalProperties": false,
+      "properties": {
+        "orchestrator_session_reattach_timeout_ms": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Milliseconds to wait for an existing orchestrator session to reattach before treating it as orphaned."
+        },
+        "orphan_session_cleanup_enabled": {
+          "type": "boolean",
+          "description": "When true, orphaned agent sessions are automatically cleaned up at startup."
+        }
+      }
+    }
+  }
+}

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

@@ -1,50 +1,107 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://example.local/agentic/qa_test_index.schema.json",
+  "description": "Per-feature test coverage index stored in .aop/features/<id>/qa_test_index.json. Built from git diffs when patches are applied; updated by the QA agent as tests are run.",
   "type": "object",
   "additionalProperties": false,
-  "required": ["feature_id", "version", "source_diff_ref", "items"],
+  "required": [
+    "feature_id",
+    "version",
+    "source_diff_ref",
+    "items"
+  ],
   "properties": {
-    "feature_id": { "type": "string" },
-    "version": { "type": "integer", "minimum": 1 },
-    "source_diff_ref": { "type": "string" },
+    "feature_id": {
+      "type": "string",
+      "description": "Feature this test index belongs to."
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Monotonically incrementing version, updated each time patches are applied or test statuses are updated."
+    },
+    "source_diff_ref": {
+      "type": "string",
+      "description": "Stable hash of the diff state used to generate this index. Used to detect whether the index is stale relative to the current worktree."
+    },
     "items": {
       "type": "array",
+      "description": "One entry per changed source file, listing the hunks modified and the tests required to cover those changes.",
       "items": {
         "type": "object",
-        "required": ["path", "hunks", "required_tests", "status"],
+        "required": [
+          "path",
+          "hunks",
+          "required_tests",
+          "status"
+        ],
         "properties": {
-          "path": { "type": "string" },
+          "path": {
+            "type": "string",
+            "description": "Repo-relative path of the changed source file."
+          },
           "hunks": {
             "type": "array",
+            "description": "Changed line ranges within this file, derived from the unified diff.",
             "items": {
               "type": "object",
-              "required": ["start_line", "end_line", "change_type"],
+              "required": [
+                "start_line",
+                "end_line",
+                "change_type"
+              ],
               "properties": {
-                "start_line": { "type": "integer", "minimum": 1 },
-                "end_line": { "type": "integer", "minimum": 1 },
+                "start_line": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "description": "First line of the changed hunk (1-indexed)."
+                },
+                "end_line": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "description": "Last line of the changed hunk (1-indexed)."
+                },
                 "change_type": {
                   "type": "string",
-                  "enum": ["add", "modify", "delete"]
+                  "enum": [
+                    "add",
+                    "modify",
+                    "delete"
+                  ],
+                  "description": "Type of change applied to this hunk: 'add', 'modify', or 'delete'."
                 }
               }
             }
           },
           "required_tests": {
             "type": "array",
-            "items": { "type": "string" }
+            "items": {
+              "type": "string"
+            },
+            "description": "Test identifiers that must run to cover the changes in this file. Populated by the gate profile's test config."
           },
           "status": {
             "type": "string",
-            "enum": ["pending", "running", "passed", "failed", "waived"]
+            "enum": [
+              "pending",
+              "running",
+              "passed",
+              "failed",
+              "waived"
+            ],
+            "description": "Current test status for this file: 'pending' (not yet run), 'running', 'passed', 'failed', or 'waived'."
           },
           "last_run_at": {
             "type": "string",
-            "format": "date-time"
+            "format": "date-time",
+            "description": "ISO 8601 timestamp of the last test run that produced results for this file."
           },
           "evidence_refs": {
             "type": "array",
-            "items": { "type": "string" }
+            "items": {
+              "type": "string"
+            },
+            "description": "Paths to gate evidence artifacts produced by test runs covering this file."
           }
         }
       }

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

@@ -1,6 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://example.local/agentic/state.schema.json",
+  "description": "Per-feature runtime state stored in .aop/features/<id>/state.md YAML frontmatter. Written on every state transition.",
   "type": "object",
   "additionalProperties": true,
   "required": [
@@ -18,91 +19,247 @@
     "last_updated"
   ],
   "properties": {
-    "feature_id": { "type": "string" },
-    "version": { "type": "integer", "minimum": 1 },
-    "branch": { "type": "string" },
-    "worktree_path": { "type": "string" },
+    "feature_id": {
+      "type": "string",
+      "description": "Unique identifier for this feature, matching the directory name under .aop/features/."
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Monotonically incrementing integer used for optimistic concurrency. Incremented on every state write by FeatureStateService."
+    },
+    "branch": {
+      "type": "string",
+      "description": "Git branch name for this feature's worktree."
+    },
+    "worktree_path": {
+      "type": "string",
+      "description": "Absolute filesystem path to this feature's git worktree."
+    },
     "status": {
       "type": "string",
-      "enum": ["planning", "building", "qa", "blocked", "ready_to_merge", "merged", "failed"]
+      "description": "Current lifecycle phase. planning \u2192 building \u2192 qa \u2192 ready_to_merge \u2192 merged. 'blocked' is a cross-cutting pause state; 'failed' is terminal.",
+      "enum": [
+        "planning",
+        "building",
+        "qa",
+        "blocked",
+        "ready_to_merge",
+        "merged",
+        "failed"
+      ]
+    },
+    "gate_profile": {
+      "type": "string",
+      "description": "Name of the gates profile to use for this feature. Written from plan.gate_profile on plan submission."
     },
-    "gate_profile": { "type": "string" },
     "gates": {
       "type": "object",
+      "description": "Map of gate mode names to their most recent result. Keys are mode names (e.g. 'fast', 'full', 'merge'); values are 'pass', 'fail', or 'na'.",
       "additionalProperties": {
         "type": "string",
-        "enum": ["pass", "fail", "na"]
+        "enum": [
+          "pass",
+          "fail",
+          "na"
+        ]
       }
     },
     "locks": {
       "type": "object",
-      "required": ["held"],
+      "description": "Lock resources currently held by this feature.",
+      "required": [
+        "held"
+      ],
       "properties": {
         "held": {
           "type": "array",
-          "items": { "type": "string" }
+          "description": "List of lock resource names this feature currently holds. Updated atomically alongside index.locks by the lock service.",
+          "items": {
+            "type": "string"
+          }
         }
       }
     },
     "collisions": {
       "type": "object",
-      "required": ["files", "areas", "contracts"],
+      "description": "Collision details detected during the most recent plan submission. Cleared on successful plan resubmission.",
+      "required": [
+        "files",
+        "areas",
+        "contracts"
+      ],
       "properties": {
-        "files": { "type": "array", "items": { "type": "object" } },
-        "areas": { "type": "array", "items": { "type": "object" } },
-        "contracts": { "type": "array", "items": { "type": "object" } }
+        "files": {
+          "type": "array",
+          "items": {
+            "type": "object"
+          },
+          "description": "File-level collisions: files that overlap with another active feature's plan."
+        },
+        "areas": {
+          "type": "array",
+          "items": {
+            "type": "object"
+          },
+          "description": "Area-level collisions: allowed_areas or exclusive_areas that overlap with another active feature's plan."
+        },
+        "contracts": {
+          "type": "array",
+          "items": {
+            "type": "object"
+          },
+          "description": "Contract-level collisions: two features both declaring changes to the same contract type (openapi, events, db)."
+        }
       }
     },
     "cluster": {
       "type": "object",
-      "description": "Compatibility cluster snapshot. Active features must match index.runtime_sessions.orchestrator_session_id.",
-      "required": ["orchestrator_session_id", "planner_session_id", "builder_session_id", "qa_session_id"],
+      "description": "Agent session IDs allocated to this feature by the current orchestrator run. Used to detect and close stale sessions when a new run starts.",
+      "required": [
+        "orchestrator_session_id",
+        "planner_session_id",
+        "builder_session_id",
+        "qa_session_id"
+      ],
       "properties": {
-        "orchestrator_session_id": { "type": "string" },
-        "planner_session_id": { "type": "string" },
-        "builder_session_id": { "type": "string" },
-        "qa_session_id": { "type": "string" }
+        "orchestrator_session_id": {
+          "type": "string",
+          "description": "AI session ID of the orchestrator agent that manages this feature's lifecycle."
+        },
+        "planner_session_id": {
+          "type": "string",
+          "description": "AI session ID of the planner agent for this feature."
+        },
+        "builder_session_id": {
+          "type": "string",
+          "description": "AI session ID of the builder agent for this feature."
+        },
+        "qa_session_id": {
+          "type": "string",
+          "description": "AI session ID of the QA agent for this feature."
+        }
       }
     },
     "role_status": {
       "type": "object",
-      "required": ["planner", "builder", "qa"],
+      "description": "Execution status of each agent role within the current lifecycle phase.",
+      "required": [
+        "planner",
+        "builder",
+        "qa"
+      ],
       "properties": {
         "planner": {
           "type": "string",
-          "enum": ["ready", "running", "blocked", "done"]
+          "enum": [
+            "ready",
+            "running",
+            "blocked",
+            "done"
+          ],
+          "description": "Planner agent status: 'ready' (not yet started), 'running', 'blocked', or 'done'."
         },
         "builder": {
           "type": "string",
-          "enum": ["ready", "running", "blocked", "done"]
+          "enum": [
+            "ready",
+            "running",
+            "blocked",
+            "done"
+          ],
+          "description": "Builder agent status: 'ready', 'running', 'blocked', or 'done'."
         },
         "qa": {
           "type": "string",
-          "enum": ["ready", "running", "blocked", "done"]
+          "enum": [
+            "ready",
+            "running",
+            "blocked",
+            "done"
+          ],
+          "description": "QA agent status: 'ready', 'running', 'blocked', or 'done'."
         }
       }
     },
     "pr": {
       "type": "object",
+      "description": "Pull request metadata populated by the PR monitor service when a PR exists for this feature.",
+      "additionalProperties": false,
       "properties": {
-        "number": { "type": "integer" },
-        "url": { "type": "string" },
-        "ci_status": { "type": "string", "enum": ["passing", "failing", "pending", "none"] },
-        "review_decision": { "type": "string", "enum": ["approved", "changes_requested", "pending", "none"] },
-        "merge_ready": { "type": "boolean" },
-        "pending_review_threads": { "type": "integer" },
-        "has_conflicts": { "type": "boolean" },
-        "merge_score": { "type": "number" }
-      },
-      "additionalProperties": false
-    },
-    "gate_retry_count": { "type": "integer", "minimum": 0, "default": 0 },
-    "last_retry_at": { "type": ["string", "null"], "format": "date-time" },
-    "last_updated": { "type": "string", "format": "date-time" },
-    "status_reason": { "type": "string" },
+        "number": {
+          "type": "integer",
+          "description": "GitHub PR number."
+        },
+        "url": {
+          "type": "string",
+          "description": "URL of the GitHub pull request."
+        },
+        "ci_status": {
+          "type": "string",
+          "enum": [
+            "passing",
+            "failing",
+            "pending",
+            "none"
+          ],
+          "description": "Aggregated CI status for the PR's head commit: 'passing', 'failing', 'pending', or 'none'."
+        },
+        "review_decision": {
+          "type": "string",
+          "enum": [
+            "approved",
+            "changes_requested",
+            "pending",
+            "none"
+          ],
+          "description": "Aggregated GitHub review decision: 'approved', 'changes_requested', 'pending', or 'none'."
+        },
+        "merge_ready": {
+          "type": "boolean",
+          "description": "Whether all merge prerequisites (CI passing, approved, no conflicts, no pending threads) are satisfied."
+        },
+        "pending_review_threads": {
+          "type": "integer",
+          "description": "Number of unresolved review comment threads on the PR."
+        },
+        "has_conflicts": {
+          "type": "boolean",
+          "description": "Whether the PR branch has merge conflicts with the base branch."
+        },
+        "merge_score": {
+          "type": "number",
+          "description": "Computed numeric merge readiness score (0\u2013100) used to prioritise which features to merge first."
+        }
+      }
+    },
+    "gate_retry_count": {
+      "type": "integer",
+      "minimum": 0,
+      "default": 0,
+      "description": "Number of automatic gate-fail repair attempts made so far. Read by the QA wave executor to enforce reactions.gate_failed.max_retries."
+    },
+    "last_retry_at": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of the most recent gate repair attempt, or null if no retry has been made."
+    },
+    "last_updated": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of the most recent state write. Set automatically by FeatureStateService on every update."
+    },
+    "status_reason": {
+      "type": "string",
+      "description": "Human-readable explanation of the current status. Set on error, blocked, and merge transitions (e.g. 'Gate mode full failed')."
+    },
     "evidence": {
       "type": "object",
-      "additionalProperties": true
+      "additionalProperties": true,
+      "description": "Freeform key-value evidence bag. Gate runs write last_gate_mode, last_gate_evidence_path, and coverage_status here; merge writes merge_sha, merge_strategy, and merge_at."
     }
   }
 }

package/apps/control-plane/scripts/validate-architecture-rules.mjs

@@ -6,7 +6,7 @@ const ARCHITECTURE_RULES = {
   'application-tools': ['cli', 'interfaces', 'mcp', 'providers', 'supervisor'],
   application: ['cli', 'interfaces', 'supervisor'],
   cli: [],
-  core: ['cli', 'interfaces', 'supervisor'],
+  core: ['cli', 'interfaces', 'supervisor', 'application-services', 'application-tools', 'application', 'mcp', 'providers'],
   interfaces: [],
   mcp: ['cli', 'interfaces', 'supervisor'],
   providers: ['cli', 'interfaces', 'mcp', 'supervisor'],
@@ -36,6 +36,10 @@ async function collectFiles(root) {
 
 function classifyLayer(filePath) {
   const relativePath = path.relative(SRC_ROOT, filePath).replaceAll('\\', '/');
+  if (relativePath === 'core/kernel.ts') {
+    // Legacy placement: kernel composes application services and adapters, so enforce application-layer rules.
+    return 'application';
+  }
   if (relativePath.startsWith('application/services/')) {
     return 'application-services';
   }
@@ -189,8 +193,6 @@ async function main() {
   if (failed) {
     process.exit(1);
   }
-
-  process.stdout.write(`architecture_rules_ok files_checked=${filesChecked} violation_count=0\n`);
 }
 
 void main();

package/apps/control-plane/scripts/validate-docker-mcp-contract.mjs

@@ -61,7 +61,6 @@ assertContains(entrypoint, /for tool in node npm npx git;/m, 'entrypoint must ve
 assertContains(entrypoint, /\bexec\s+"\$@"/, 'entrypoint must contain exec "$@" passthrough');
 
 if (!runSmoke) {
-  console.log('validate:docker-mcp: contract checks passed');
   process.exit(0);
 }
 
@@ -92,5 +91,3 @@ const smoke = spawnSync(
 if (smoke.status !== 0) {
   fail('docker compose run smoke check failed');
 }
-
-console.log('validate:docker-mcp: contract checks + smoke run passed');

package/apps/control-plane/scripts/validate-mcp-contracts.ts

@@ -1,8 +1,8 @@
 import fs from 'node:fs/promises';
 import fsSync from 'node:fs';
 import path from 'node:path';
-import Ajv from 'ajv';
-import Ajv2020 from 'ajv/dist/2020.js';
+import { Ajv } from 'ajv';
+import { Ajv2020 } from 'ajv/dist/2020.js';
 import { MCP_PROTOCOL_PIN, REQUIRED_MCP_TRANSPORTS } from '../src/mcp/protocol-contract.js';
 import { ToolsMarkdownGenerator } from '../src/mcp/tools-markdown-generator.js';
 import { ToolRegistryLoader } from '../src/mcp/tool-registry-loader.js';
@@ -140,10 +140,6 @@ async function main(): Promise<void> {
   for (const warning of warnings) {
     process.stdout.write(`[validate:mcp-contracts] warning: ${warning}\n`);
   }
-
-  process.stdout.write(
-    `[validate:mcp-contracts] ok: tools=${registry.catalog.tools.length} protocol=${protocol.mcp_protocol_version} sdk=${protocol.sdk.package}@${protocol.sdk.version}\n`
-  );
 }
 
 void main().catch((error: unknown) => {