agentic-orchestrator 0.1.6 → 0.1.7

package/spec-files/completed/agentic_orchestrator_validator_hardening_spec.md

@@ -14,6 +14,7 @@
 ### 0.1 Required Standards
 
 All implementation MUST preserve:
+
 - All three validators continue to pass on a clean codebase with zero output on success
 - CI command signatures are unchanged: `npm run validate:mcp-contracts`, `npm run validate:docker-mcp`, `npm run validate:architecture`
 - Exit code 1 on any new failure; exit code 0 only when all checks pass
@@ -22,6 +23,7 @@ All implementation MUST preserve:
 ### 0.2 Upstream Inputs
 
 Implementing agents MUST read:
+
 - `agentic/orchestrator/tools/catalog.json` — source of truth for tool metadata
 - `apps/control-plane/src/application/tools/tool-metadata.ts` — `MUTATING_TOOLS` runtime list
 - `apps/control-plane/src/core/constants.ts` — `TOOLS` constants
@@ -33,6 +35,7 @@ Implementing agents MUST read:
 ### 0.3 Feature Scope
 
 This spec implements improvements in three areas:
+
 - **V1** MCP contract cross-validation hardening
 - **V2** Docker MCP contract completeness
 - **V3** Architecture rule completeness and correctness
@@ -100,12 +103,13 @@ const mutatingInCatalog = tool.mutating === true;
 const mutatingInCode = TOOL_BEHAVIOR_METADATA[tool.handler_id]?.mutating === true;
 if (mutatingInCatalog !== mutatingInCode) {
   errors.push(
-    `Tool "${tool.handler_id}" mutating flag mismatch: catalog=${mutatingInCatalog}, code=${mutatingInCode}`
+    `Tool "${tool.handler_id}" mutating flag mismatch: catalog=${mutatingInCatalog}, code=${mutatingInCode}`,
   );
 }
 ```
 
 **Failure message example:**
+
 ```
 ✗ Tool "cost.record" mutating flag mismatch: catalog=true, code=false
   Fix: add TOOLS.COST_RECORD to MUTATING_TOOLS in tool-metadata.ts
@@ -147,11 +151,13 @@ for (const tool of catalog.tools) {
 **Check:** Collect all `.json` files under `agentic/orchestrator/tools/schemas/input/` and `schemas/output/`. Compare against the set of schema refs mentioned in the catalog. Files on disk that are not referenced by any tool are reported as orphans.
 
 **Known current orphans (informational, not blocking — these may be shared base schemas):**
+
 - `schemas/input/mutating.schema.json`
 - `schemas/input/read.schema.json`
 - `schemas/output/standard_success.schema.json`
 
 These three files should be either:
+
 1. Added as `$ref` base schemas used by at least one tool, or
 2. Explicitly listed in a `known_shared_schemas` array in the validator (not subject to orphan check).
 
@@ -169,7 +175,11 @@ const allSchemaFiles = [
   ...glob.sync('schemas/output/*.json', { cwd: toolsDir }),
 ];
 
-const knownShared = new Set(['schemas/input/mutating.schema.json', 'schemas/input/read.schema.json', 'schemas/output/standard_success.schema.json']);
+const knownShared = new Set([
+  'schemas/input/mutating.schema.json',
+  'schemas/input/read.schema.json',
+  'schemas/output/standard_success.schema.json',
+]);
 
 for (const file of allSchemaFiles) {
   if (!referencedSchemas.has(file) && !knownShared.has(file)) {
@@ -216,7 +226,7 @@ assert(fromMatch, 'Dockerfile must use a pinned Node version (e.g. node:22-bookw
 const nodeMajor = parseInt(fromMatch[1], 10);
 assert(
   nodeMajor >= MIN_NODE_MAJOR,
-  `Dockerfile Node version ${nodeMajor} is below minimum required ${MIN_NODE_MAJOR}`
+  `Dockerfile Node version ${nodeMajor} is below minimum required ${MIN_NODE_MAJOR}`,
 );
 ```
 
@@ -229,10 +239,7 @@ assert(
 ```javascript
 const entrypointPath = path.resolve(repoRoot, 'docker', 'entrypoint.sh');
 const entrypoint = fs.readFileSync(entrypointPath, 'utf8');
-assert(
-  /\bexec\s+"\$@"/.test(entrypoint),
-  'Entrypoint script must contain exec "$@" passthrough'
-);
+assert(/\bexec\s+"\$@"/.test(entrypoint), 'Entrypoint script must contain exec "$@" passthrough');
 ```
 
 ---
@@ -253,7 +260,7 @@ assert(
 function classifyFile(relativePath) {
   if (relativePath.startsWith('application/services/')) return 'application-services';
   if (relativePath.startsWith('application/tools/')) return 'application-tools';
-  if (relativePath.startsWith('application/')) return 'application';  // NEW
+  if (relativePath.startsWith('application/')) return 'application'; // NEW
   if (relativePath.startsWith('cli/')) return 'cli';
   if (relativePath.startsWith('core/')) return 'core';
   if (relativePath.startsWith('interfaces/')) return 'interfaces';
@@ -269,7 +276,7 @@ function classifyFile(relativePath) {
 ```javascript
 const ARCHITECTURE_RULES = {
   // existing rules ...
-  'application': ['cli', 'interfaces', 'supervisor'],  // NEW: same restrictions as application-services
+  application: ['cli', 'interfaces', 'supervisor'], // NEW: same restrictions as application-services
 };
 ```
 
@@ -303,6 +310,7 @@ const EXEMPT_FILES = new Set(['index.ts']);
 Before adding this rule, verify that no existing `core/` file currently imports from those layers. If any do, they must be refactored to eliminate the import first.
 
 **Verification command:**
+
 ```bash
 grep -r "from.*application\|from.*mcp\|from.*providers" apps/control-plane/src/core/ --include="*.ts"
 ```
@@ -355,11 +363,11 @@ Implement in this order to avoid false CI failures:
 
 ## 8. Files Affected
 
-| File | Change Type |
-|---|---|
-| `apps/control-plane/scripts/validate-mcp-contracts.ts` | Add checks 3.1–3.4 |
-| `apps/control-plane/scripts/validate-architecture-rules.mjs` | Add checks 5.1–5.2 |
-| `apps/control-plane/scripts/validate-docker-mcp-contract.mjs` | Add checks 4.1–4.2 |
-| `apps/control-plane/src/application/tools/tool-metadata.ts` | Add `TOOLS.COST_RECORD` to `MUTATING_TOOLS` |
-| `apps/control-plane/test/tool-metadata.spec.ts` | Add tests for `COST_RECORD` mutating behavior |
-| `spec-files/progress.md` | Update with completed milestone |
+| File                                                          | Change Type                                   |
+| ------------------------------------------------------------- | --------------------------------------------- |
+| `apps/control-plane/scripts/validate-mcp-contracts.ts`        | Add checks 3.1–3.4                            |
+| `apps/control-plane/scripts/validate-architecture-rules.mjs`  | Add checks 5.1–5.2                            |
+| `apps/control-plane/scripts/validate-docker-mcp-contract.mjs` | Add checks 4.1–4.2                            |
+| `apps/control-plane/src/application/tools/tool-metadata.ts`   | Add `TOOLS.COST_RECORD` to `MUTATING_TOOLS`   |
+| `apps/control-plane/test/tool-metadata.spec.ts`               | Add tests for `COST_RECORD` mutating behavior |
+| `spec-files/progress.md`                                      | Update with completed milestone               |

package/spec-files/outstanding/agentic_orchestrator_artifact_database_publishing_spec.md

@@ -14,6 +14,7 @@
 ### 0.1 Required Standards
 
 All implementation MUST preserve:
+
 - deterministic runtime behavior and MCP/in-process parity
 - existing command behavior when publishing is disabled
 - normalized error envelope (`{ ok: false, error: { code, message, details } }`)
@@ -23,6 +24,7 @@ All implementation MUST preserve:
 ### 0.2 Upstream Inputs
 
 Implementing agents MUST read:
+
 - `apps/control-plane/src/core/path-layout.ts`
 - `apps/control-plane/src/core/kernel.ts`
 - `apps/control-plane/src/supervisor/run-coordinator.ts`
@@ -42,6 +44,7 @@ Implementing agents MUST read:
 ### 0.3 Feature Scope
 
 This spec implements three slices:
+
 - **DB1** Configurable artifact publishing policy + database connection contract
 - **DB2** Post-run and manual publishing pipeline with idempotent checkpoints
 - **DB3** Local Docker database mode (`database.type: local`)
@@ -76,6 +79,7 @@ Database rows are derived artifacts for analytics/audit. `.aop/**` remains autho
 ### 2.2 First-Class Publisher Service
 
 All publishing must route through a single service boundary (`ArtifactPublisherService`) to centralize:
+
 - artifact enumeration
 - normalization and hashing
 - DB transaction semantics
@@ -104,8 +108,8 @@ Add `artifact_publishing` section to policy (full + defaults + schema):
 ```yaml
 artifact_publishing:
   enabled: false
-  trigger: post_run           # post_run | manual_only
-  mode: best_effort           # best_effort | required
+  trigger: post_run # post_run | manual_only
+  mode: best_effort # best_effort | required
   include_content:
     state_md: true
     plan_json: true
@@ -113,12 +117,12 @@ artifact_publishing:
     qa_index_json: true
     gate_logs_preview_bytes: 16384
   database:
-    type: postgres            # postgres | local
+    type: postgres # postgres | local
     target_id: default
     postgres:
-      connection_uri: "${AOP_AUDIT_DB_URL}"
+      connection_uri: '${AOP_AUDIT_DB_URL}'
       schema: aop_audit
-      ssl_mode: require       # disable | require
+      ssl_mode: require # disable | require
       connect_timeout_ms: 8000
     local:
       engine: postgres
@@ -136,6 +140,7 @@ artifact_publishing:
 ### 3.2 YAML Validation
 
 `agentic/orchestrator/schemas/policy.schema.json` MUST validate the new section with:
+
 - strict enums for `trigger`, `mode`, `database.type`
 - required `postgres.connection_uri` when `type: postgres`
 - required local fields when `type: local`
@@ -157,6 +162,7 @@ artifact_publishing:
 ### 4.1 Artifacts Included Per Run
 
 Minimum dataset for a run publish:
+
 - `.aop/features/index.json`
 - `.aop/runtime/operation-ledger/<run_id>.json`
 - for each feature in run scope:
@@ -170,6 +176,7 @@ Minimum dataset for a run publish:
 ### 4.2 Normalized Record Categories
 
 Publisher MUST normalize into these logical categories:
+
 - `run_summary`
 - `feature_snapshot`
 - `tool_execution`
@@ -181,6 +188,7 @@ Publisher MUST normalize into these logical categories:
 ### 4.3 Hashing and Determinism
 
 For each artifact row:
+
 - include `content_sha256`
 - include `relative_path`
 - normalize JSON key order before hashing JSON content
@@ -193,6 +201,7 @@ For each artifact row:
 ### 5.1 Required Tables
 
 1. `aop_publish_runs`
+
 - `publish_id` (PK)
 - `target_id`
 - `run_id`
@@ -202,6 +211,7 @@ For each artifact row:
 - `error_code`, `error_message`
 
 2. `aop_runs`
+
 - `run_id` (PK)
 - `project_root_hash`
 - `started_at`
@@ -210,6 +220,7 @@ For each artifact row:
 - `runtime_status`
 
 3. `aop_features`
+
 - composite PK: (`run_id`, `feature_id`)
 - `status`
 - `branch`
@@ -219,6 +230,7 @@ For each artifact row:
 - `tokens_used`
 
 4. `aop_tool_executions`
+
 - composite PK: (`run_id`, `operation_id`)
 - `feature_id`
 - `tool_name`
@@ -230,6 +242,7 @@ For each artifact row:
 - `created_at`, `updated_at`
 
 5. `aop_gate_executions`
+
 - surrogate PK + unique (`run_id`, `feature_id`, `gate_name`, `executed_at`)
 - `result`, `exit_code`
 - `mode`
@@ -237,11 +250,13 @@ For each artifact row:
 - `logs_preview`
 
 6. `aop_decisions`
+
 - surrogate PK + index (`run_id`, `feature_id`, `line_no`)
 - `entry_text`
 - `entry_hash`
 
 7. `aop_artifact_manifest`
+
 - composite PK: (`run_id`, `feature_id`, `relative_path`)
 - `size_bytes`
 - `content_sha256`
@@ -260,6 +275,7 @@ For each artifact row:
 ### 6.1 Automatic Post-Run Publishing
 
 `RunCommandHandler.execute(...)` flow extension:
+
 1. run supervisor cycle (`supervisor.start(...)`)
 2. if `artifact_publishing.enabled && trigger == post_run`, invoke publisher
 3. attach publish result under response payload:
@@ -270,9 +286,11 @@ For each artifact row:
 ### 6.2 Manual Publishing
 
 Add CLI command:
+
 - `aop publish [--run-id <id>] [--latest] [--dry-run] [--strict]`
 
 Behavior:
+
 - default `--latest` when no run id provided
 - `--dry-run` builds manifest + stats without DB writes
 - `--strict` forces non-zero exit on publish failure regardless of policy mode
@@ -280,6 +298,7 @@ Behavior:
 ### 6.3 MCP Tool Surface
 
 Add tools:
+
 - `artifacts.publish` (mutating: true)
 - `artifacts.publish_status` (mutating: false)
 
@@ -292,6 +311,7 @@ Add tools:
 ### 7.1 Behavior
 
 When `database.type: local`:
+
 1. verify Docker CLI availability
 2. verify/start container using configured image/name/port/volume
 3. wait for DB health/readiness
@@ -301,6 +321,7 @@ When `database.type: local`:
 ### 7.2 Local Runtime Artifacts
 
 Persist local DB runtime metadata under:
+
 - `.aop/runtime/artifact-publishing/local-db.json`
 
 Contract example:
@@ -321,6 +342,7 @@ Contract example:
 ### 7.3 Docker Failure Handling
 
 Errors must map cleanly:
+
 - `artifact_publish_local_docker_unavailable`
 - `artifact_publish_local_start_failed`
 - `artifact_publish_local_unhealthy`
@@ -332,6 +354,7 @@ If mode is `best_effort`, run continues and publish failure is reported in paylo
 ## 8. Error Codes
 
 Add to `apps/control-plane/src/core/error-codes.ts`:
+
 - `artifact_publish_config_invalid`
 - `artifact_publish_target_unconfigured`
 - `artifact_publish_connect_failed`
@@ -349,40 +372,49 @@ Add to `apps/control-plane/src/core/error-codes.ts`:
 ## 9.1 DB1: Configuration + Validation
 
 ### DB1-T1 Policy contract
+
 - update `policy.yaml` examples
 - update `policy.defaults.yaml`
 - extend `policy.schema.json`
 
 ### DB1-T2 Typed policy accessors
+
 - add typed readers for `artifact_publishing` section in kernel/service layer
 
 ### DB1-T3 Config normalization
+
 - implement env interpolation + normalization helper
 
 ## 9.2 DB2: Publisher pipeline
 
 ### DB2-T1 Artifact enumeration
+
 - deterministic scanner for run/feature artifacts
 - manifest builder with hashes and size
 
 ### DB2-T2 Store interface and Postgres adapter
+
 - `ArtifactAuditStore` interface
 - `PostgresArtifactAuditStore` implementation (transactional upsert)
 
 ### DB2-T3 Checkpointing and idempotency
+
 - write local checkpoint under `.aop/runtime/artifact-publishing/checkpoints/<run_id>.json`
 - support safe retries after partial failures
 
 ### DB2-T4 Trigger integration
+
 - invoke publisher from run flow and manual command path
 
 ## 9.3 DB3: Local Docker orchestration
 
 ### DB3-T1 Local DB manager
+
 - start/inspect/wait for container
 - compute connection URI for local target
 
 ### DB3-T2 Local-only smoke checks
+
 - optional smoke test command for local mode readiness
 
 ---
@@ -390,6 +422,7 @@ Add to `apps/control-plane/src/core/error-codes.ts`:
 ## 10. File Targets
 
 ### 10.1 New files
+
 - `apps/control-plane/src/application/services/artifact-publisher-service.ts`
 - `apps/control-plane/src/application/services/artifact-manifest-service.ts`
 - `apps/control-plane/src/application/services/artifact-audit-store.ts`
@@ -403,6 +436,7 @@ Add to `apps/control-plane/src/core/error-codes.ts`:
 - `apps/control-plane/src/application/services/sql/artifact-publishing/postgres/001_init.sql`
 
 ### 10.2 Existing files to modify
+
 - `apps/control-plane/src/core/kernel.ts`
 - `apps/control-plane/src/core/constants.ts`
 - `apps/control-plane/src/core/error-codes.ts`
@@ -420,6 +454,7 @@ Add to `apps/control-plane/src/core/error-codes.ts`:
 - `README.md`
 
 ### 10.3 Tests
+
 - `apps/control-plane/test/artifact-publisher.spec.ts` (new)
 - `apps/control-plane/test/local-artifact-db-manager.spec.ts` (new)
 - `apps/control-plane/test/run-command.spec.ts` (extend post-run publish assertions)

package/spec-files/outstanding/agentic_orchestrator_enterprise_governance_dashboard_spec.md

@@ -14,12 +14,14 @@
 ### 0.1 Feature Scope
 
 This spec implements:
+
 - **Q5** Compliance Policy Packs + Control Export
 - **Q6** Dashboard AuthN/AuthZ + SSO + Audit Federation
 
 ### 0.2 Required Standards
 
 Implementation MUST preserve:
+
 - deterministic evidence mapping
 - explicit authorization for all mutating dashboard actions
 - audit-log completeness for privileged operations
@@ -77,22 +79,22 @@ compliance:
 dashboard:
   auth:
     enabled: false
-    mode: oidc_or_api_key  # oidc | api_key | oidc_or_api_key
+    mode: oidc_or_api_key # oidc | api_key | oidc_or_api_key
     oidc:
-      issuer: ""
-      client_id: ""
-      audience: ""
+      issuer: ''
+      client_id: ''
+      audience: ''
     api_keys:
       env_var: AOP_DASHBOARD_API_KEYS
   rbac:
     viewer: [status_read, feature_read, evidence_read]
     reviewer: [status_read, feature_read, evidence_read, review_decide]
     operator: [status_read, feature_read, evidence_read, review_decide, feature_checkout]
-    admin: ["*"]
+    admin: ['*']
   audit:
     enabled: true
-    sink: file  # file | webhook
-    webhook_url: ""
+    sink: file # file | webhook
+    webhook_url: ''
 ```
 
 ### 3.2 Source-Managed Compliance Assets
@@ -127,16 +129,18 @@ agentic/orchestrator/schemas/compliance_pack.schema.json
 ## 4.1 Q5: Compliance Policy Packs + Control Export
 
 ### 4.1.1 Problem
+
 Enterprise adoption requires consistent control mapping from orchestrator behavior/evidence to recognized control frameworks.
 
 ### 4.1.2 Design
+
 Provide curated compliance packs plus deterministic export routine.
 
 ### 4.1.3 Pack Structure
 
 ```yaml
 id: soc2_baseline
-version: "1.0"
+version: '1.0'
 controls:
   - id: CC7.2
     title: Monitor system components for anomalies
@@ -170,9 +174,7 @@ controls:
           "observed": 0.9
         }
       ],
-      "evidence_refs": [
-        ".aop/features/feature_x/evidence/gates/full-2026-03-03.json"
-      ],
+      "evidence_refs": [".aop/features/feature_x/evidence/gates/full-2026-03-03.json"],
       "manual_evidence_required": false
     }
   ]
@@ -199,9 +201,11 @@ controls:
 ## 4.2 Q6: Dashboard AuthN/AuthZ + SSO + Audit Federation
 
 ### 4.2.1 Problem
+
 Dashboard operation in shared/production contexts needs strong identity + authorization + audit controls.
 
 ### 4.2.2 Design
+
 Add optional auth middleware, server-side action authorization, and audit sink integration.
 
 ### 4.2.3 Auth Modes
@@ -213,6 +217,7 @@ Add optional auth middleware, server-side action authorization, and audit sink i
 ### 4.2.4 Action Authorization Matrix
 
 Actions to guard:
+
 - `feature_review_decide` (approve/deny/request_changes)
 - `feature_checkout`
 - `dashboard_admin_settings`
@@ -261,28 +266,34 @@ Each action must map to role permission in policy.
 ### EGD1: Compliance Pack Foundation
 
 Tasks:
+
 1. Add compliance pack assets + schemas.
 2. Implement export service + MCP tool + CLI command.
 
 Exit gate:
+
 - deterministic export and evidence mapping verified by tests.
 
 ### EGD2: Dashboard Auth and RBAC
 
 Tasks:
+
 1. Add auth middleware and token/api key validation.
 2. Implement server-side role authorization for protected endpoints.
 
 Exit gate:
+
 - protected actions denied when unauthorized in integration tests.
 
 ### EGD3: Audit Federation
 
 Tasks:
+
 1. Add unified audit envelope and file sink.
 2. Add optional webhook sink with retry/backoff.
 
 Exit gate:
+
 - allow/deny events emitted and schema-valid in both sinks.
 
 ---
@@ -340,9 +351,9 @@ Exit gate:
 ## 9. Definition of Done
 
 A completed EGD milestone MUST include:
+
 - changed files and architecture rationale
 - schema/catalog/policy diffs
 - security + integration test coverage
 - gate command results
 - updates in `spec-files/progress.md`
-

package/spec-files/outstanding/agentic_orchestrator_knowledge_canary_spec.md

@@ -14,6 +14,7 @@
 ### 0.1 Feature Scope
 
 This spec implements:
+
 - **Q10** Cross-Feature Knowledge Graph
 - **Q12** Progressive Merge Guardrails (Canary Verification)
 
@@ -96,6 +97,7 @@ Edge contract:
 ### 3.2 Canary State Additions (Optional)
 
 `state.md` frontmatter optional fields:
+
 - `canary.status`: `na|pending|pass|fail`
 - `canary.last_run_at`: RFC3339
 - `canary.evidence_refs`: string[]
@@ -112,9 +114,11 @@ Edge contract:
 ## 4.1 Q10: Cross-Feature Knowledge Graph
 
 ### 4.1.1 Problem
+
 Historical delivery knowledge exists but is difficult to query/reuse during planning.
 
 ### 4.1.2 Design
+
 Build and maintain graph from canonical artifacts and expose deterministic search API.
 
 ### 4.1.3 Node Types
@@ -137,6 +141,7 @@ Build and maintain graph from canonical artifacts and expose deterministic searc
 ### 4.1.5 Ranking Rules (Deterministic)
 
 Ranking by tuple order:
+
 1. exact feature/status/type match
 2. recency descending
 3. frequency of relevant edge types
@@ -165,9 +170,7 @@ Output:
     {
       "node_id": "node:mitigation:retry_lock_backoff",
       "score": 0.89,
-      "evidence_refs": [
-        ".aop/features/legacy_feature/evidence/gates/full-2026-02-20.json"
-      ]
+      "evidence_refs": [".aop/features/legacy_feature/evidence/gates/full-2026-02-20.json"]
     }
   ]
 }
@@ -192,9 +195,11 @@ Output:
 ## 4.2 Q12: Progressive Merge Guardrails (Canary Verification)
 
 ### 4.2.1 Problem
+
 Pre-merge checks can miss issues that only surface on merged head.
 
 ### 4.2.2 Design
+
 Optional post-merge canary gate profile runs before final merged-state confirmation.
 
 ### 4.2.3 Canary Flow
@@ -230,6 +235,7 @@ merge_policy:
 ```
 
 Includes:
+
 - failing canary steps
 - relevant logs/evidence refs
 - deterministic git commands to revert/fix-forward (suggested, not auto-executed)
@@ -257,29 +263,35 @@ Includes:
 ### KC1: Knowledge Graph Foundation
 
 Tasks:
+
 1. implement graph model/service and build/update pipeline.
 2. add search tool contracts and query API.
 
 Exit gate:
+
 - graph file and search output deterministic under repeated runs.
 
 ### KC2: Planner Context Integration
 
 Tasks:
+
 1. wire optional knowledge retrieval into planner context bundle.
 2. add policy toggle for knowledge enrichment usage.
 
 Exit gate:
+
 - planner receives contextual patterns without changing core deterministic flow.
 
 ### KC3: Canary Merge Verification
 
 Tasks:
+
 1. implement canary verification service.
 2. integrate into merge-service finalization path.
 3. emit rollback guidance on fail.
 
 Exit gate:
+
 - merge path with canary enabled handles pass/fail transitions correctly.
 
 ---
@@ -336,9 +348,9 @@ Exit gate:
 ## 9. Definition of Done
 
 A completed KC milestone MUST include:
+
 - changed files and rationale
 - policy/schema/tool catalog diffs
 - integration + parity tests
 - command verification summary
 - `spec-files/progress.md` update with residual tasks (if any)
-