agentic-orchestrator 0.1.0

package/agentic/orchestrator/tools/schemas/output/report.dashboard.output.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.local/agentic/tools/schemas/output/report.dashboard.output.schema.json",
+  "type": "object",
+  "required": [
+    "index",
+    "features"
+  ],
+  "properties": {
+    "index": {
+      "type": "object"
+    },
+    "features": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/agentic/orchestrator/tools/schemas/output/report.feature_summary.output.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.local/agentic/tools/schemas/output/report.feature_summary.output.schema.json",
+  "type": "object",
+  "required": [
+    "feature_id",
+    "state",
+    "diff_stat",
+    "touched_files",
+    "last_gate_summary",
+    "qa_summary"
+  ],
+  "properties": {
+    "feature_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "state": {
+      "type": "object"
+    },
+    "diff_stat": {
+      "type": "string"
+    },
+    "touched_files": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "last_gate_summary": {},
+    "qa_summary": {
+      "type": "object"
+    }
+  },
+  "additionalProperties": false
+}

package/agentic/orchestrator/tools/schemas/output/standard_success.schema.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.local/agentic/tools/schemas/output/standard_success.schema.json",
+  "type": "object",
+  "additionalProperties": true
+}

package/agentic/orchestrator/tools.md

@@ -0,0 +1,32 @@
+# AOP MCP Tool Surface
+
+Generated from `agentic/orchestrator/tools/catalog.json`.
+
+- collisions.scan
+- evidence.latest
+- feature.delete
+- feature.discover_specs
+- feature.get_context
+- feature.init
+- feature.log_append
+- feature.ready_to_merge
+- feature.state_get
+- feature.state_patch
+- gates.list
+- gates.run
+- locks.acquire
+- locks.release
+- plan.get
+- plan.submit
+- plan.update
+- qa.test_index_get
+- qa.test_index_update
+- repo.apply_patch
+- repo.diff
+- repo.diff_bundle
+- repo.ensure_worktree
+- repo.read_file
+- repo.search
+- repo.status
+- report.dashboard
+- report.feature_summary

package/apps/control-plane/project.json

@@ -0,0 +1,39 @@
+{
+  "name": "control-plane",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "projectType": "application",
+  "sourceRoot": "apps/control-plane/src",
+  "targets": {
+    "run": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "tsx apps/control-plane/src/cli/aop.ts"
+      }
+    },
+    "build": {
+      "executor": "nx:run-commands",
+      "dependsOn": ["lint"],
+      "options": {
+        "command": "tsc -p apps/control-plane/tsconfig.build.json"
+      }
+    },
+    "lint": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "eslint apps/control-plane --max-warnings 0"
+      }
+    },
+    "test": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "vitest run --coverage --config apps/control-plane/vitest.config.ts"
+      }
+    },
+    "typecheck": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "tsc -p tsconfig.json --noEmit"
+      }
+    }
+  }
+}

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

@@ -0,0 +1,170 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const ARCHITECTURE_RULES = {
+  'application-services': ['cli', 'interfaces', 'mcp', 'providers', 'supervisor'],
+  'application-tools': ['cli', 'interfaces', 'mcp', 'providers', 'supervisor'],
+  cli: [],
+  core: ['cli', 'interfaces', 'supervisor'],
+  interfaces: [],
+  mcp: ['cli', 'interfaces', 'supervisor'],
+  providers: ['cli', 'interfaces', 'mcp', 'supervisor'],
+  supervisor: ['cli', 'interfaces']
+};
+
+const IMPORT_PATTERN = /(?:import|export)\s+[^'"]*?from\s+['"]([^'"]+)['"]/g;
+const SRC_ROOT = path.resolve(process.cwd(), 'apps/control-plane/src');
+
+async function collectFiles(root) {
+  const entries = await fs.readdir(root, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const absolutePath = path.join(root, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await collectFiles(absolutePath)));
+      continue;
+    }
+    if (entry.isFile() && absolutePath.endsWith('.ts')) {
+      files.push(absolutePath);
+    }
+  }
+  return files.sort((a, b) => a.localeCompare(b));
+}
+
+function classifyLayer(filePath) {
+  const relativePath = path.relative(SRC_ROOT, filePath).replaceAll('\\', '/');
+  if (relativePath.startsWith('application/services/')) {
+    return 'application-services';
+  }
+  if (relativePath.startsWith('application/tools/')) {
+    return 'application-tools';
+  }
+  if (relativePath.startsWith('cli/')) {
+    return 'cli';
+  }
+  if (relativePath.startsWith('core/')) {
+    return 'core';
+  }
+  if (relativePath.startsWith('interfaces/')) {
+    return 'interfaces';
+  }
+  if (relativePath.startsWith('mcp/')) {
+    return 'mcp';
+  }
+  if (relativePath.startsWith('providers/')) {
+    return 'providers';
+  }
+  if (relativePath.startsWith('supervisor/')) {
+    return 'supervisor';
+  }
+  return 'unknown';
+}
+
+async function fileExists(filePath) {
+  try {
+    await fs.stat(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function resolveImport(sourceFile, importSpecifier) {
+  if (!importSpecifier.startsWith('.')) {
+    return null;
+  }
+
+  const sourceDir = path.dirname(sourceFile);
+  const rawTarget = path.resolve(sourceDir, importSpecifier);
+  const candidates = [
+    rawTarget,
+    rawTarget.replace(/\.js$/, '.ts'),
+    `${rawTarget}.ts`,
+    `${rawTarget}.js`,
+    path.join(rawTarget, 'index.ts'),
+    path.join(rawTarget, 'index.js')
+  ];
+
+  for (const candidate of candidates) {
+    if (await fileExists(candidate)) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+function extractImports(content) {
+  const imports = [];
+  let match;
+  while ((match = IMPORT_PATTERN.exec(content)) != null) {
+    imports.push(match[1]);
+  }
+  return imports;
+}
+
+async function collectViolations() {
+  const files = await collectFiles(SRC_ROOT);
+  const violations = [];
+
+  for (const file of files) {
+    const sourceLayer = classifyLayer(file);
+    if (sourceLayer === 'unknown') {
+      continue;
+    }
+    const forbiddenTargets = ARCHITECTURE_RULES[sourceLayer];
+    if (!forbiddenTargets || forbiddenTargets.length === 0) {
+      continue;
+    }
+
+    const content = await fs.readFile(file, 'utf8');
+    const imports = extractImports(content);
+    for (const importSpecifier of imports) {
+      const resolved = await resolveImport(file, importSpecifier);
+      if (!resolved) {
+        continue;
+      }
+
+      if (!resolved.startsWith(SRC_ROOT)) {
+        continue;
+      }
+
+      const targetLayer = classifyLayer(resolved);
+      if (forbiddenTargets.includes(targetLayer)) {
+        violations.push({
+          source: path.relative(process.cwd(), file).replaceAll('\\', '/'),
+          sourceLayer,
+          target: path.relative(process.cwd(), resolved).replaceAll('\\', '/'),
+          targetLayer,
+          importSpecifier
+        });
+      }
+    }
+  }
+
+  return { filesChecked: files.length, violations };
+}
+
+function printViolation(violation) {
+  const message =
+    `- ${violation.source} (${violation.sourceLayer}) imports ${violation.importSpecifier} ` +
+    `-> ${violation.target} (${violation.targetLayer})`;
+  process.stderr.write(`${message}\n`);
+}
+
+async function main() {
+  const { filesChecked, violations } = await collectViolations();
+  if (violations.length > 0) {
+    process.stderr.write('architecture_rule_violations_detected\n');
+    for (const violation of violations) {
+      printViolation(violation);
+    }
+    process.stderr.write(`files_checked=${filesChecked}\n`);
+    process.stderr.write(`violation_count=${violations.length}\n`);
+    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

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const repoRoot = path.resolve(import.meta.dirname, '..', '..', '..');
+const dockerDir = path.join(repoRoot, 'docker');
+const dockerfilePath = path.join(dockerDir, 'mcp.Dockerfile');
+const composePath = path.join(dockerDir, 'mcp.compose.yaml');
+const entrypointPath = path.join(dockerDir, 'mcp.entrypoint.sh');
+const runSmoke = process.argv.includes('--smoke');
+
+function fail(message) {
+  console.error(`validate:docker-mcp: ${message}`);
+  process.exit(1);
+}
+
+function readText(filePath) {
+  if (!fs.existsSync(filePath)) {
+    fail(`missing required file: ${path.relative(repoRoot, filePath)}`);
+  }
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+function assertContains(content, pattern, label) {
+  if (!pattern.test(content)) {
+    fail(`contract mismatch: ${label}`);
+  }
+}
+
+const dockerfile = readText(dockerfilePath);
+const compose = readText(composePath);
+const entrypoint = readText(entrypointPath);
+
+assertContains(dockerfile, /^FROM\s+node:/m, 'docker image must be Node-based');
+assertContains(dockerfile, /apt-get install[^]*\bgit\b/m, 'docker image must include git toolchain');
+assertContains(dockerfile, /ENV\s+AOP_REPO_ROOT=\/repo/m, 'docker image must declare /repo root');
+assertContains(
+  dockerfile,
+  /ENTRYPOINT\s+\["\/bin\/sh",\s*"\/app\/docker\/mcp\.entrypoint\.sh"\]/m,
+  'docker entrypoint must enforce runtime preflight checks'
+);
+
+assertContains(compose, /aop-mcp:/m, 'compose must declare aop-mcp service');
+assertContains(compose, /- \.\.\/:\/repo/m, 'compose must bind-mount repository to /repo');
+assertContains(compose, /working_dir:\s*\/repo/m, 'compose service must execute from /repo');
+
+assertContains(entrypoint, /if \[ ! -d "\/repo" \]/m, 'entrypoint must enforce /repo mount check');
+assertContains(entrypoint, /for tool in node npm npx git;/m, 'entrypoint must verify required toolchains');
+
+if (!runSmoke) {
+  console.log('validate:docker-mcp: contract checks passed');
+  process.exit(0);
+}
+
+const config = spawnSync('docker', ['compose', '-f', composePath, 'config'], {
+  cwd: repoRoot,
+  stdio: 'inherit'
+});
+if (config.status !== 0) {
+  fail('docker compose config validation failed');
+}
+
+const build = spawnSync('docker', ['compose', '-f', composePath, 'build', 'aop-mcp'], {
+  cwd: repoRoot,
+  stdio: 'inherit'
+});
+if (build.status !== 0) {
+  fail('docker compose build smoke check failed');
+}
+
+const smoke = spawnSync(
+  'docker',
+  ['compose', '-f', composePath, 'run', '--rm', 'aop-mcp', 'npm', 'run', 'run', '--', 'status', '--transport', 'mcp'],
+  {
+    cwd: repoRoot,
+    stdio: 'inherit'
+  }
+);
+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

@@ -0,0 +1,61 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+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';
+
+function fail(message: string): never {
+  throw new Error(message);
+}
+
+function normalizeMarkdown(content: string): string {
+  return `${content.replace(/\r\n/g, '\n').trimEnd()}\n`;
+}
+
+async function main(): Promise<void> {
+  const repoRoot = process.cwd();
+  const loader = new ToolRegistryLoader(repoRoot);
+  const registry = await loader.load();
+  const protocol = registry.protocol;
+
+  if (protocol.mcp_protocol_version !== MCP_PROTOCOL_PIN.mcp_protocol_version) {
+    fail(
+      `protocol_version_pin_mismatch expected=${MCP_PROTOCOL_PIN.mcp_protocol_version} actual=${protocol.mcp_protocol_version}`
+    );
+  }
+  if (protocol.sdk.package !== MCP_PROTOCOL_PIN.sdk.package) {
+    fail(`protocol_sdk_package_pin_mismatch expected=${MCP_PROTOCOL_PIN.sdk.package} actual=${protocol.sdk.package}`);
+  }
+  if (protocol.sdk.version !== MCP_PROTOCOL_PIN.sdk.version) {
+    fail(`protocol_sdk_version_pin_mismatch expected=${MCP_PROTOCOL_PIN.sdk.version} actual=${protocol.sdk.version}`);
+  }
+
+  for (const transport of REQUIRED_MCP_TRANSPORTS) {
+    if (!protocol.enabled_transports.includes(transport)) {
+      fail(`protocol_missing_required_transport:${transport}`);
+    }
+  }
+
+  if (registry.catalog.tools.length !== registry.toolsByName.size) {
+    fail('registry_duplicate_tool_names_detected');
+  }
+
+  const generator = new ToolsMarkdownGenerator(repoRoot);
+  const expectedToolsMarkdown = normalizeMarkdown(generator.renderFromCatalog(registry.catalog));
+  const toolsMdPath = path.join(repoRoot, 'agentic', 'orchestrator', 'tools.md');
+  const actualToolsMarkdown = normalizeMarkdown(await fs.readFile(toolsMdPath, 'utf8'));
+
+  if (actualToolsMarkdown !== expectedToolsMarkdown) {
+    fail('tools_markdown_drift_detected');
+  }
+
+  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) => {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`[validate:mcp-contracts] failed: ${message}\n`);
+  process.exitCode = 1;
+});

package/apps/control-plane/src/application/services/collision-queue-service.ts

@@ -0,0 +1,227 @@
+import { nowIso, readJson } from '../../core/fs.js';
+import { detectPlanCollisions } from '../../core/collisions.js';
+import { sortResourcesDeterministically } from '../../core/path-rules.js';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyRecord = Record<string, any>;
+
+type StateReadResult = {
+  frontMatter: AnyRecord;
+};
+
+type StateUpdater = (
+  frontMatter: AnyRecord,
+  body: string
+) => Promise<{ frontMatter?: AnyRecord; body?: string }>;
+
+function asArray<T = unknown>(value: unknown): T[] {
+  return Array.isArray(value) ? (value as T[]) : [];
+}
+
+function readObjectField(record: AnyRecord, key: string): AnyRecord {
+  const value = record[key];
+  return value && typeof value === 'object' ? (value as AnyRecord) : {};
+}
+
+function readHeldLocks(frontMatter: AnyRecord): string[] {
+  const locks = readObjectField(frontMatter, 'locks');
+  return asArray<string>(locks.held).filter((item) => typeof item === 'string');
+}
+
+interface QueueEntry {
+  feature_id: string;
+  plan_version: number;
+  detected_at: string;
+  collision_fingerprint: string;
+  required_resources: string[];
+  plan_snapshot?: AnyRecord;
+}
+
+export interface CollisionQueueServicePort {
+  getPolicySnapshot(): AnyRecord;
+  planPath(featureId: string): string;
+  statePath(featureId: string): string;
+  featureDiscoverSpecs(): Promise<{ data: { specs: Array<{ feature_id: string }> } }>;
+  readState(featureId: string): Promise<StateReadResult>;
+  withFeatureLock<T>(featureId: string, operation: () => Promise<T>): Promise<T>;
+  withIndexLock<T>(operation: () => Promise<T>): Promise<T>;
+  readIndex(): Promise<AnyRecord>;
+  writeIndex(index: AnyRecord): Promise<void>;
+  updateState(featureId: string, expectedVersion: number | null, updater: StateUpdater): Promise<AnyRecord>;
+  planSubmit(featureId: string, plan: AnyRecord, expectedVersion: number | null): Promise<{ data: { feature_id: string; accepted: boolean; plan_version: number } }>;
+}
+
+export class CollisionQueueService {
+  private readonly port: CollisionQueueServicePort;
+
+  constructor(port: CollisionQueueServicePort) {
+    this.port = port;
+  }
+
+  async collectAcceptedPlans(excludeFeatureId: string | null = null): Promise<AnyRecord[]> {
+    const specs = await this.port.featureDiscoverSpecs();
+    const plans: AnyRecord[] = [];
+    for (const item of specs.data.specs) {
+      if (item.feature_id === excludeFeatureId) {
+        continue;
+      }
+      const plan = await readJson(this.port.planPath(item.feature_id), null);
+      if (plan) {
+        plans.push(plan);
+      }
+    }
+    return plans;
+  }
+
+  requiredResourcesForPlan(plan: AnyRecord): string[] {
+    const resources: string[] = [];
+    const policy = this.port.getPolicySnapshot();
+    if (plan.contracts?.openapi === 'modify') {
+      resources.push(policy.locks.contract_to_resource.openapi);
+    }
+    if (plan.contracts?.events === 'modify') {
+      resources.push(policy.locks.contract_to_resource.events);
+    }
+    if (plan.contracts?.db === 'migration') {
+      resources.push(policy.locks.contract_to_resource.db);
+    }
+    return sortResourcesDeterministically(resources);
+  }
+
+  async assertPlanLocksHeld(featureId: string, plan: AnyRecord): Promise<boolean> {
+    const state = await this.port.readState(featureId);
+    const held = new Set(readHeldLocks(state.frontMatter));
+    const required = await this.requiredResourcesForPlan(plan);
+    const missing = required.filter((resource) => !held.has(resource));
+    return missing.length === 0;
+  }
+
+  async checkPlanCollision(featureId: string, plan: AnyRecord): Promise<{ hasCollisions: boolean; fingerprint?: string }> {
+    const policy = this.port.getPolicySnapshot();
+    const acceptedPlans = await this.collectAcceptedPlans(featureId);
+    const collisionResult = detectPlanCollisions(
+      plan as Parameters<typeof detectPlanCollisions>[0],
+      acceptedPlans as Parameters<typeof detectPlanCollisions>[1],
+      policy as Parameters<typeof detectPlanCollisions>[2]
+    );
+
+    return {
+      hasCollisions: collisionResult.hasCollisions,
+      fingerprint: collisionResult.fingerprint
+    };
+  }
+
+  async processSingleQueueEntry(entry: QueueEntry): Promise<{ retried: boolean; reason?: string }> {
+    const persistedPlan = await readJson(this.port.planPath(entry.feature_id), null);
+    const snapshotPlan =
+      entry.plan_snapshot && typeof entry.plan_snapshot === 'object' ? entry.plan_snapshot : null;
+
+    const plan =
+      persistedPlan && persistedPlan.plan_version === entry.plan_version
+        ? persistedPlan
+        : snapshotPlan && snapshotPlan.plan_version === entry.plan_version
+          ? snapshotPlan
+          : null;
+
+    if (!plan) {
+      return { retried: false, reason: 'plan_missing' };
+    }
+
+    const locksHeld = await this.assertPlanLocksHeld(entry.feature_id, plan);
+    if (!locksHeld) {
+      return { retried: false, reason: 'locks_not_held' };
+    }
+
+    const collision = await this.checkPlanCollision(entry.feature_id, plan);
+    if (collision.hasCollisions) {
+      return { retried: false, reason: 'collision_still_present' };
+    }
+
+    try {
+      const expectedVersion = Number.isInteger(plan.revision_of) ? Number(plan.revision_of) : null;
+      await this.port.planSubmit(entry.feature_id, plan, expectedVersion);
+      return { retried: true };
+    } catch (_error) {
+      return { retried: false, reason: 'plan_submit_failed' };
+    }
+  }
+
+  async reDriveBlockedQueue(): Promise<{ data: { processed: number; retried: number; still_blocked: number } }> {
+    const policy = this.port.getPolicySnapshot();
+    
+    if (policy.collision_policy !== 'block') {
+      return {
+        data: {
+          processed: 0,
+          retried: 0,
+          still_blocked: 0
+        }
+      };
+    }
+
+    return await this.port.withIndexLock(async () => {
+      const index = await this.port.readIndex();
+      const queue: QueueEntry[] = asArray<QueueEntry>(index.blocked_queue);
+      
+      if (queue.length === 0) {
+        return {
+          data: {
+            processed: 0,
+            retried: 0,
+            still_blocked: 0
+          }
+        };
+      }
+
+      const sortedQueue = [...queue].sort(
+        (a, b) => a.detected_at.localeCompare(b.detected_at) || a.feature_id.localeCompare(b.feature_id)
+      );
+
+      const stillBlocked: QueueEntry[] = [];
+      let retriedCount = 0;
+
+      for (const entry of sortedQueue) {
+        const result = await this.processSingleQueueEntry(entry);
+        if (result.retried) {
+          retriedCount += 1;
+        } else {
+          stillBlocked.push(entry);
+        }
+      }
+
+      const currentIndex = await this.port.readIndex();
+      currentIndex.blocked_queue = stillBlocked;
+      currentIndex.version += 1;
+      currentIndex.updated_at = nowIso();
+      await this.port.writeIndex(currentIndex);
+
+      return {
+        data: {
+          processed: sortedQueue.length,
+          retried: retriedCount,
+          still_blocked: stillBlocked.length
+        }
+      };
+    });
+  }
+
+  async clearQueueEntry(featureId: string): Promise<{ data: { removed: boolean } }> {
+    return await this.port.withIndexLock(async () => {
+      const index = await this.port.readIndex();
+      const queue: QueueEntry[] = asArray<QueueEntry>(index.blocked_queue);
+      const before = queue.length;
+      const filtered = queue.filter((entry) => entry.feature_id !== featureId);
+      
+      if (filtered.length === before) {
+        return { data: { removed: false } };
+      }
+
+      index.blocked_queue = filtered;
+      index.version += 1;
+      index.updated_at = nowIso();
+      await this.port.writeIndex(index);
+
+      return { data: { removed: true } };
+    });
+  }
+}