agentic-orchestrator 0.1.0

package/agentic/orchestrator/gates.yaml

@@ -0,0 +1,31 @@
+version: 1
+profiles:
+  default:
+    modes:
+      fast:
+        - name: lint
+          cmd: ["npm", "run", "nx", "--", "run", "control-plane:test", "--", "--runInBand"]
+          timeout_seconds: 600
+      full:
+        - name: test_with_coverage
+          cmd: ["npm", "run", "nx", "--", "run", "control-plane:test"]
+          timeout_seconds: 1200
+      merge:
+        - name: merge_safety
+          cmd: ["npm", "run", "nx", "--", "run", "control-plane:test"]
+          timeout_seconds: 1200
+    parsers:
+      coverage:
+        type: lcov
+        path: coverage/control-plane/lcov.info
+    thresholds:
+      coverage_line_min: 0.9
+      coverage_branch_min: 0.9
+      coverage_line_target: 1.0
+      coverage_branch_target: 1.0
+capabilities:
+  - none
+  - lcov
+  - junit_xml
+  - jacoco_xml
+  - cobertura_xml

package/agentic/orchestrator/policy.yaml

@@ -0,0 +1,145 @@
+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
+    - protected:libs/core
+  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/schemas
+  - agentic/orchestrator/policy.yaml
+exclusive_areas:
+  - libs/core
+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.9
+      branch: 0.9
+    targets:
+      line: 1.0
+      branch: 1.0
+merge_policy:
+  require_user_approval: true
+  allowed_strategies:
+    - merge_commit
+    - squash
+    - rebase
+worktree:
+  base_branch: main
+recovery:
+  orchestrator_session_reattach_timeout_ms: 5000
+  orphan_session_cleanup_enabled: true
+supervisor:
+  max_iterations_per_phase: 6
+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
+  planner:
+    - feature.get_context
+    - feature.state_get
+    - plan.submit
+    - plan.update
+    - collisions.scan
+    - repo.read_file
+    - repo.search
+  builder:
+    - feature.get_context
+    - feature.state_get
+    - repo.apply_patch
+    - repo.status
+    - repo.diff
+    - repo.read_file
+    - repo.search
+    - gates.run
+  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
+  system:
+    - "*"

package/agentic/orchestrator/prompts/builder.system.md

@@ -0,0 +1 @@
+You are the builder role. Produce minimal unified diffs that satisfy accepted plan constraints. Call gates after meaningful patch batches.

package/agentic/orchestrator/prompts/planner.system.md

@@ -0,0 +1,15 @@
+You are the planner role.
+
+Produce deterministic plan submissions and plan updates that conform to plan schema and policy constraints.
+Avoid speculative edits outside the declared file scope.
+
+After each QA wave, perform an explicit reconciliation pass:
+- re-read feature context (`feature.get_context`) including spec, accepted plan, QA index summary, and latest gate evidence
+- verify builder/QA outcomes still satisfy the accepted plan and spec intent
+- emit `plan.update` when correction gaps exist, with concrete revision reasons
+- document edge-case hardening in plan risk/acceptance coverage:
+  - boundary values and size limits
+  - negative/error paths
+  - dependency failures, timeout/retry behavior, and race/concurrency conditions when relevant
+
+If no correction is required, keep the existing plan unchanged.

package/agentic/orchestrator/prompts/qa.system.md

@@ -0,0 +1 @@
+You are the QA role. Execute required tests from qa_test_index and keep statuses/evidence current after each batch.

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

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.local/agentic/agents.schema.json",
+  "type": "object",
+  "required": ["version", "roles"],
+  "additionalProperties": false,
+  "properties": {
+    "version": { "type": "number" },
+    "roles": {
+      "type": "object",
+      "required": ["planner", "builder", "qa"],
+      "properties": {
+        "planner": { "$ref": "#/$defs/roleCfg" },
+        "builder": { "$ref": "#/$defs/roleCfg" },
+        "qa": { "$ref": "#/$defs/roleCfg" }
+      }
+    },
+    "missing_prompt_behavior": {
+      "type": "string",
+      "enum": ["ignore", "error"],
+      "default": "ignore"
+    },
+    "runtime": {
+      "type": "object",
+      "properties": {
+        "default_provider": {
+          "type": "string",
+          "enum": ["codex", "claude", "gemini", "custom"]
+        },
+        "default_model": { "type": "string" },
+        "provider_config_env": { "type": "string" },
+        "role_provider_overrides": {
+          "type": "object"
+        }
+      }
+    }
+  },
+  "$defs": {
+    "roleCfg": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "system_prompt_path": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.local/agentic/gates.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "profiles"],
+  "properties": {
+    "version": { "type": "number" },
+    "profiles": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["modes"],
+        "properties": {
+          "modes": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["name", "cmd"],
+                "additionalProperties": false,
+                "properties": {
+                  "name": { "type": "string", "minLength": 1 },
+                  "cmd": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": { "type": "string", "minLength": 1 }
+                  },
+                  "cwd": { "type": "string" },
+                  "env": {
+                    "type": "object",
+                    "additionalProperties": { "type": "string" }
+                  },
+                  "timeout_seconds": { "type": "number", "minimum": 1 }
+                }
+              }
+            }
+          },
+          "parsers": {
+            "type": "object",
+            "additionalProperties": true
+          },
+          "thresholds": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "coverage_line_min": { "type": "number", "minimum": 0, "maximum": 1 },
+              "coverage_branch_min": { "type": "number", "minimum": 0, "maximum": 1 },
+              "coverage_line_target": { "type": "number", "minimum": 0, "maximum": 1 },
+              "coverage_branch_target": { "type": "number", "minimum": 0, "maximum": 1 }
+            }
+          }
+        }
+      }
+    },
+    "capabilities": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": ["none", "lcov", "junit_xml", "jacoco_xml", "cobertura_xml", "custom"]
+      }
+    }
+  }
+}

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

@@ -0,0 +1,108 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.local/agentic/index.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "active", "blocked", "merged", "locks", "lock_leases", "blocked_queue", "runtime_sessions"],
+  "properties": {
+    "version": { "type": "integer", "minimum": 1 },
+    "active": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "blocked": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "merged": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "locks": {
+      "type": "object",
+      "additionalProperties": {
+        "anyOf": [
+          { "type": "string" },
+          { "type": "null" }
+        ]
+      }
+    },
+    "lock_leases": {
+      "type": "object",
+      "additionalProperties": {
+        "anyOf": [
+          {
+            "type": "object",
+            "required": ["holder", "lease_id", "expires_at"],
+            "properties": {
+              "holder": { "type": "string" },
+              "lease_id": { "type": "string" },
+              "expires_at": { "type": "string", "format": "date-time" }
+            }
+          },
+          { "type": "null" }
+        ]
+      }
+    },
+    "blocked_queue": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["feature_id", "plan_version", "detected_at", "collision_fingerprint", "required_resources"],
+        "properties": {
+          "feature_id": { "type": "string" },
+          "plan_version": { "type": "integer", "minimum": 1 },
+          "detected_at": { "type": "string", "format": "date-time" },
+          "collision_fingerprint": { "type": "string" },
+          "required_resources": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        }
+      }
+    },
+    "updated_at": { "type": "string", "format": "date-time" },
+    "runtime_sessions": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "run_id",
+        "orchestrator_session_id",
+        "provider",
+        "model",
+        "provider_config_ref_hash",
+        "owner_instance_id",
+        "lease_id",
+        "started_at",
+        "last_heartbeat_at",
+        "lease_expires_at"
+      ],
+      "properties": {
+        "run_id": { "type": "string" },
+        "orchestrator_session_id": { "type": "string" },
+        "provider": { "type": "string" },
+        "model": { "type": "string" },
+        "provider_config_ref_hash": { "type": "string" },
+        "owner_instance_id": { "type": "string" },
+        "lease_id": { "type": "string" },
+        "started_at": { "type": "string", "format": "date-time" },
+        "last_heartbeat_at": { "type": "string", "format": "date-time" },
+        "lease_expires_at": { "type": "string", "format": "date-time" },
+        "orchestrator_epoch": { "type": "integer", "minimum": 0 },
+        "feature_sessions": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["planner_session_id", "builder_session_id", "qa_session_id"],
+            "properties": {
+              "planner_session_id": { "type": "string" },
+              "builder_session_id": { "type": "string" },
+              "qa_session_id": { "type": "string" }
+            }
+          }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,127 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.local/agentic/plan.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "feature_id",
+    "plan_version",
+    "summary",
+    "allowed_areas",
+    "forbidden_areas",
+    "base_ref",
+    "files",
+    "contracts",
+    "acceptance_criteria",
+    "gate_profile"
+  ],
+  "properties": {
+    "feature_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9_][a-z0-9_-]*$"
+    },
+    "plan_version": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 5
+    },
+    "allowed_areas": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "minItems": 1
+    },
+    "forbidden_areas": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "base_ref": {
+      "type": "string",
+      "minLength": 1
+    },
+    "files": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["create", "modify", "delete"],
+      "properties": {
+        "create": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "modify": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "delete": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+      }
+    },
+    "contracts": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["openapi", "events", "db"],
+      "properties": {
+        "openapi": { "type": "string", "enum": ["none", "modify"] },
+        "events": { "type": "string", "enum": ["none", "modify"] },
+        "db": { "type": "string", "enum": ["none", "migration"] }
+      }
+    },
+    "acceptance_criteria": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "minItems": 1
+    },
+    "gate_profile": { "type": "string", "minLength": 1 },
+    "gate_targets": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "minItems": 1
+    },
+    "risk": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "revision_of": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "revision_reason": {
+      "type": "string",
+      "minLength": 1
+    },
+    "verification_overrides": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "modes": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "fast": { "$ref": "#/$defs/modeOverride" },
+            "full": { "$ref": "#/$defs/modeOverride" }
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "modeOverride": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "steps": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name", "cmd"],
+            "properties": {
+              "name": { "type": "string", "minLength": 1 },
+              "cmd": {
+                "type": "array",
+                "items": { "type": "string", "minLength": 1 },
+                "minItems": 1
+              },
+              "timeout_seconds": { "type": "number", "minimum": 1 }
+            }
+          }
+        }
+      }
+    }
+  }
+}