agentic-orchestrator 0.1.28 → 0.2.0

package/.claude/settings.local.json

@@ -14,7 +14,52 @@
       "Bash(npx eslint:*)",
       "Bash(node:*)",
       "Bash(tsc:*)",
-      "Bash(./node_modules/.bin/tsc:*)"
+      "Bash(./node_modules/.bin/tsc:*)",
+      "mcp__plugin_serena_serena__execute_shell_command",
+      "Bash(python3 -c \"import hashlib; print\\(hashlib.sha256\\(b'empty'\\).hexdigest\\(\\)\\)\")",
+      "Bash(git add:*)",
+      "mcp__plugin_serena_serena__get_symbols_overview",
+      "mcp__plugin_serena_serena__search_for_pattern",
+      "mcp__plugin_serena_serena__list_dir",
+      "Bash(npx tsc:*)",
+      "Bash(mkdir -p /home/erictaurone/workspace/Aequitas/projects/Agentic-Orchestrator/packages/web-dashboard/src/app/api/features/[id]/conflicts/files)",
+      "Bash(mkdir -p /home/erictaurone/workspace/Aequitas/projects/Agentic-Orchestrator/packages/web-dashboard/src/app/api/features/[id]/conflicts/resolve)",
+      "Bash(mkdir -p /home/erictaurone/workspace/Aequitas/projects/Agentic-Orchestrator/packages/web-dashboard/src/app/api/features/[id]/conflicts/abort)",
+      "Bash(echo \"EXIT_CODE=$?\")",
+      "Bash(echo \"LINT_EXIT=$?\")",
+      "Bash(echo \"TEST_EXIT=$?\")",
+      "Bash(echo \"ARCH_EXIT=$?\")",
+      "Bash(echo \"MCP_EXIT=$?\")",
+      "Bash(echo \"EXIT=$?\")",
+      "Bash(find /home/erictaurone/workspace/Aequitas/projects/Agentic-Orchestrator/.aop/ -name *.jsonl -path *ledger*)",
+      "Bash(find /home/erictaurone/workspace/Aequitas/projects/Agentic-Orchestrator/.aop/ -name *.jsonl)",
+      "Bash(python3 -c \":*)",
+      "mcp__plugin_serena_serena__activate_project",
+      "mcp__plugin_serena_serena__find_symbol",
+      "mcp__plugin_serena_serena__read_file",
+      "Bash(git:*)",
+      "Bash(echo \"LINT=$?\")",
+      "Bash(python3 -c \"import json,sys; d=json.load\\(sys.stdin\\); print\\(len\\(d[''''tools'''']\\)\\)\")",
+      "Bash(python3 -c \"import json,sys; d=json.load\\(sys.stdin\\); [print\\(t[''''name'''']\\) for t in d[''''tools'''']]\")",
+      "Bash(find /home/erictaurone/workspace/Aequitas/projects/Agentic-Orchestrator/.aop -name state.md -path */global/*)",
+      "Bash(npx tsx:*)",
+      "mcp__plugin_serena_serena__find_file",
+      "mcp__plugin_serena_serena__find_referencing_symbols",
+      "mcp__plugin_serena_serena__get_current_config",
+      "Bash(WORKTREE=\"/home/erictaurone/workspace/Aequitas/projects/Agentic-Orchestrator/.worktrees/agentic_orchestrator_phase_specific_agent_profiles_and_token_telemetry_spec\")",
+      "Bash(git -C:*)",
+      "Bash(find /home/erictaurone/workspace/Aequitas/projects/Agentic-Orchestrator/.aop -name *.command-queue.json -o -name *command*queue*)",
+      "Bash(find /home/erictaurone/workspace/Aequitas/projects/Agentic-Orchestrator/packages/web-dashboard/src -type f \\\\\\(-name *.ts -o -name *.tsx \\\\\\))",
+      "Bash(find /home/erictaurone/workspace/Aequitas/projects/Agentic-Orchestrator -type f \\\\\\(-name .github -o -name ISSUES -o -name KNOWN_ISSUES -o -name DEFECTS* \\\\\\))",
+      "Bash(find /home/erictaurone/workspace/Aequitas/projects/Agentic-Orchestrator/specs -type f -name *ordering* -o -name *order*)",
+      "Bash(find /home/erictaurone/workspace/Aequitas/projects/Agentic-Orchestrator/apps/control-plane/test -name *session* -o -name *orchestrator*)",
+      "Bash(/home/erictaurone/workspace/Aequitas/projects/Agentic-Orchestrator/spec-files/progress.md:*)",
+      "Bash(find /home/erictaurone/workspace/Aequitas/projects/Agentic-Orchestrator/apps/control-plane/src -type f \\\\\\(-name *runtime* -o -name *loop* -o -name *service* \\\\\\))",
+      "Bash(/home/erictaurone/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.6/skills/brainstorming/scripts/start-server.sh --project-dir /home/erictaurone/workspace/Aequitas/projects/Agentic-Orchestrator)",
+      "Bash(/home/erictaurone/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.6/skills/brainstorming/scripts/stop-server.sh /home/erictaurone/workspace/Aequitas/projects/Agentic-Orchestrator/.superpowers/brainstorm/35874-1774801871)",
+      "Bash(npm install:*)",
+      "Bash(python3 -c \"import json,sys; d=json.load\\(sys.stdin\\); t=d.get\\(''''total'''',{}\\); print\\(''''branches:'''', t.get\\(''''branches'''',{}\\)\\)\")",
+      "Bash(python3:*)"
     ]
   }
 }

package/.cortexrc

@@ -0,0 +1,28 @@
+{
+  "version": "1.0.0",
+  "scope": "standard",
+  "paths": {
+    "docs": "docs/core",
+    "tasks": "NEXT-TASKS.md",
+    "archive": "docs/archive"
+  },
+  "limits": {
+    "NEXT-TASKS.md": 200,
+    "FUTURE-ENHANCEMENTS.md": 500,
+    "ARCHITECTURE.md": 500,
+    "PATTERNS.md": 650,
+    "DOMAIN-LOGIC.md": 400,
+    "DECISIONS.md": 400,
+    "GLOSSARY.md": 200,
+    "SCHEMA.md": 600,
+    "TROUBLESHOOTING.md": 400
+  },
+  "validation": {
+    "ignorePatterns": [],
+    "ignoreFiles": []
+  },
+  "metadata": {
+    "created": "2026-03-06T19:10:02.513Z",
+    "projectName": "agentic-orchestrator"
+  }
+}

package/.github/agents/copilot-instructions.md

@@ -0,0 +1,29 @@
+# Agentic-Orchestrator Development Guidelines
+
+Auto-generated from all feature plans. Last updated: 2026-03-07
+
+## Active Technologies
+
+- TypeScript 5.9 strict, Node.js ESM + AJV (JSON Schema validation), `node:crypto`, `node:path`, Vitest (002-scope-aware-lease)
+
+## Project Structure
+
+```text
+src/
+tests/
+```
+
+## Commands
+
+npm test && npm run lint
+
+## Code Style
+
+TypeScript 5.9 strict, Node.js ESM: Follow standard conventions
+
+## Recent Changes
+
+- 002-scope-aware-lease: Added TypeScript 5.9 strict, Node.js ESM + AJV (JSON Schema validation), `node:crypto`, `node:path`, Vitest
+
+<!-- MANUAL ADDITIONS START -->
+<!-- MANUAL ADDITIONS END -->

package/.github/copilot-instructions.md

@@ -0,0 +1,93 @@
+# AI Pair Programmer: Collaboration Protocol (TMS v2.0)
+
+## ⚡ Critical Rules (Always Apply)
+
+- **Tech Stack**: TypeScript 5.9 strict, Node.js ESM, Nx monorepo, Vitest, AJV (JSON Schema), `yaml`, `chalk`. No runtime framework — this is a CLI tool.
+- **Conventions**: Composition over inheritance. Port-based DI (services implement interfaces consumed by the kernel). Hexagonal architecture — provider CLIs are adapters, never imported by domain/application layers.
+- **Types**: ALWAYS use strict TypeScript. No `any` in source files. No `@ts-ignore`. Use `import type` for type-only imports (`consistent-type-imports` is enforced).
+- **Errors**: NEVER throw raw strings or `new Error("message")` for structured failures. Use `ERROR_CODES` from `apps/control-plane/src/core/error-codes.ts` and return `fail(ERROR_CODES.XXX, ...)` via the `response.ts` helpers.
+- **Logic**: Before implementing business logic, check `docs/core/DOMAIN-LOGIC.md`. Before writing code, check `docs/core/PATTERNS.md` for canonical examples.
+
+## 🏗️ Technical Map (Read Order)
+
+AI agents MUST follow this order before proposing or writing code:
+
+1. `NEXT-TASKS.md` (Current context — what work is planned and why)
+2. `docs/core/DOMAIN-LOGIC.md` (Invariants, state machine rules, kernel guarantees)
+3. `docs/core/PATTERNS.md` (Canonical implementation examples for this codebase)
+4. `docs/core/ARCHITECTURE.md` (Component map and data flow)
+5. `docs/core/DECISIONS.md` (ADRs — why certain technical choices were made)
+6. `docs/core/TROUBLESHOOTING.md` (Known gotchas and non-obvious workarounds)
+
+## 🚫 Prohibitions
+
+<!-- AI-DRAFT: Review before treating as canonical -->
+
+- **Never** store secrets, API keys, or tokens in source code. Provider credentials come from environment variables only.
+- **Never** bypass linting (`--max-warnings 0` is enforced) or type-checking (`tsc --noEmit` must pass).
+- **Never** use `console.log` in source files under `apps/control-plane/src/`. Only `console.warn` and `console.error` are permitted (ESLint `no-console` is enforced). `console.log` is allowed only in CLI entry points and scripts.
+- **Never** use `any` in source files. ESLint `no-explicit-any` is an error.
+- **Never** leave floating promises. `no-floating-promises` and `no-misused-promises` are errors — always `await` or explicitly handle.
+- **Never** implement features not present in `NEXT-TASKS.md` without asking first.
+- **Never** add new commands or flags to the CLI without updating ALL FIVE required files: `types.ts`, `cli-argument-parser.ts`, `bootstrap.ts`, `help-command-handler.ts`, and `CLAUDE.md` / `AGENTS.md`.
+- **Never** use `new Error(...)` for domain failures — use `fail()` + `ERROR_CODES` from `core/error-codes.ts`.
+- **Never** call provider CLI details (command templates, flags) from domain or application layers. Keep them in `providers/provider-defaults.ts`.
+
+## 🧪 Operational Loop
+
+<!-- AI-DRAFT: Review before treating as canonical -->
+
+1. Read `NEXT-TASKS.md` to understand the "Why" and "What."
+2. Check `docs/core/DOMAIN-LOGIC.md` for invariants that must be preserved.
+3. Check `docs/core/PATTERNS.md` for canonical examples to follow.
+4. Propose change → Justify against domain logic → Recommend implementation approach.
+5. After completing any meaningful change, append an entry to `spec-files/progress.md` (see `CLAUDE.md` for format).
+
+## ✔️ Pre-Submission Checklist
+
+<!-- AI-DRAFT: Review before treating as canonical -->
+
+- [ ] Logic verified against `docs/core/DOMAIN-LOGIC.md` invariants.
+- [ ] Code follows patterns in `docs/core/PATTERNS.md`.
+- [ ] Tests added/updated and passing (`npm run test`).
+- [ ] No `console.log` statements in source (`apps/control-plane/src/`).
+- [ ] No `any` types introduced in source.
+- [ ] `npm run lint` passes with zero warnings.
+- [ ] `npm run typecheck` passes clean.
+- [ ] `npm run verify` passes clean.
+- [ ] `spec-files/progress.md` updated with a new entry.
+
+## Dependency and navigation policy
+
+This repository includes an automatically generated dependency and navigation index produced by **IntentGraph**. You must use it as the primary source of truth for repository relationship questions.
+
+### Required behavior
+
+Use the IntentGraph index first whenever you need to understand:
+
+- Dependency chains between files or modules
+- Reverse dependencies
+- Import or require relationships
+- Likely impact surfaces of a code change
+- Which files should be opened next for implementation work
+
+### Index location
+
+- `./docs/core/intentgraph.index.json`
+
+### Required workflow
+
+1. Consult the IntentGraph index to identify the smallest relevant set of files.
+2. Open only those files needed to confirm implementation details.
+3. Avoid broad repo scanning when the index already answers the relationship question.
+4. If the index is missing, stale, or insufficient, regenerate it or explicitly state that analysis is proceeding without a fresh index.
+
+### Token-efficiency rule
+
+Do not load or paste the full IntentGraph output into context. Use only the relevant dependency edges, path segments, or file subsets needed for the task.
+
+### Staleness rule
+
+If the index contradicts the code, assume the index is stale until proven otherwise.
+
+<!-- @cortex-tms-version 4.0.2 -->

package/.vscode/settings.json

@@ -0,0 +1,13 @@
+{
+  "chat.promptFilesRecommendations": {
+    "speckit.constitution": true,
+    "speckit.specify": true,
+    "speckit.plan": true,
+    "speckit.tasks": true,
+    "speckit.implement": true
+  },
+  "chat.tools.terminal.autoApprove": {
+    ".specify/scripts/bash/": true,
+    ".specify/scripts/powershell/": true
+  }
+}

package/.vscode/tms.code-snippets

@@ -0,0 +1,223 @@
+{
+  "TMS: Architecture Decision Record": {
+    "scope": "markdown",
+    "prefix": "tms-adr",
+    "description": "Insert a complete Architecture Decision Record (ADR) entry",
+    "body": [
+      "## [${1:YYYY-MM-DD}] - ${2:Decision Title}",
+      "",
+      "**Context**: ${3:What problem were we solving? What constraints existed?}",
+      "",
+      "**Decision**: ${4:What did we choose? Be specific}",
+      "",
+      "**Reasoning**:",
+      "- **Pro**: ${5:Advantage 1}",
+      "- **Pro**: ${6:Advantage 2}",
+      "- **Con**: ${7:Trade-off 1}",
+      "- **Alternative Considered**: ${8:What we didn't choose and why}",
+      "",
+      "**Consequences**:",
+      "- ✅ ${9:Positive outcome}",
+      "- ⚠️ ${10:Trade-off or limitation}",
+      "",
+      "**Status**: ${11|Active,Deprecated,Superseded|}",
+      "",
+      "---",
+      "",
+    ],
+  },
+  "TMS: Implementation Pattern": {
+    "scope": "markdown",
+    "prefix": "tms-pattern",
+    "description": "Insert a new implementation pattern entry",
+    "body": [
+      "## [${1|UI,Data,Auth,API,Testing,Config,Deployment|}] ${2:Pattern Name}",
+      "",
+      "**Rule**: ${3:Short, imperative statement of the rule}",
+      "",
+      "### ❌ Anti-Pattern (What NOT to do)",
+      "",
+      "- ${4:Description of common AI mistake}",
+      "- ${5:Why it fails in this project}",
+      "",
+      "### ✅ Canonical Example",
+      "",
+      "**Source File**: \\`${6:path/to/best-example-file.ts}\\`",
+      "",
+      "\\`\\`\\`${7|typescript,javascript,python,rust,go|}",
+      "${8:// A concise, perfect implementation of the pattern}",
+      "\\`\\`\\`",
+      "",
+      "### 🔗 References",
+      "",
+      "- **Domain Logic**: \\`DOMAIN-LOGIC.md#${9:Section}\\`",
+      "- **Gotchas**: \\`TROUBLESHOOTING.md#${10:Section}\\`",
+      "",
+      "---",
+      "",
+    ],
+  },
+  "TMS: Glossary Term": {
+    "scope": "markdown",
+    "prefix": "tms-term",
+    "description": "Insert a glossary term definition",
+    "body": [
+      "### ${1:Term Name}",
+      "**Definition**: ${2:Clear, concise explanation of what this means in your project}",
+      "**Example**: ${3:Usage in context}",
+      "**Related Terms**: ${4:Links to related concepts}",
+      "",
+    ],
+  },
+  "TMS: Glossary Acronym": {
+    "scope": "markdown",
+    "prefix": "tms-acronym",
+    "description": "Insert a glossary acronym table row",
+    "body": ["| ${1:ACRONYM} | ${2:Stands For} | ${3:Meaning in This Project} |"],
+  },
+  "TMS: Task Row": {
+    "scope": "markdown",
+    "prefix": "tms-task",
+    "description": "Insert a task row for NEXT-TASKS.md",
+    "body": [
+      "| **${1:Task Name}** - ${2:Description} | [${3:TMS-XXX}] | ${4:2h} | ${5|🔴 HIGH,🟡 MED,🟢 LOW|} | ${6|⬜ Todo,🔄 In Progress,✅ Done|} |",
+    ],
+  },
+  "TMS: Sprint Section": {
+    "scope": "markdown",
+    "prefix": "tms-sprint",
+    "description": "Insert a complete sprint section for NEXT-TASKS.md",
+    "body": [
+      "## Active Sprint: ${1:v2.X} - ${2:Sprint Theme}",
+      "",
+      "**Why this matters**: ${3:Explain the value and focus of this sprint}",
+      "",
+      "| Task | Ref | Effort | Priority | Status |",
+      "| :--- | :--- | :----- | :------- | :----- |",
+      "| **${4:Task Name}** - ${5:Description} | [${6:TMS-XXX}] | ${7:2h} | 🔴 HIGH | ⬜ Todo |",
+      "",
+      "---",
+      "",
+    ],
+  },
+  "TMS: Domain Logic Section": {
+    "scope": "markdown",
+    "prefix": "tms-domain",
+    "description": "Insert a domain logic section",
+    "body": [
+      "## ${1:Domain Area Name}",
+      "",
+      "### 🎯 Purpose",
+      "${2:Why this domain area exists and what problems it solves}",
+      "",
+      "### 📐 Rules",
+      "",
+      "1. **${3:Rule Name}**: ${4:Rule description}",
+      "   - **Why**: ${5:Justification}",
+      "   - **Example**: ${6:Concrete example}",
+      "",
+      "2. **${7:Rule Name}**: ${8:Rule description}",
+      "   - **Why**: ${9:Justification}",
+      "   - **Example**: ${10:Concrete example}",
+      "",
+      "### 🔗 Related",
+      "- **Patterns**: \\`PATTERNS.md#${11:Section}\\`",
+      "- **Schema**: \\`SCHEMA.md#${12:Section}\\`",
+      "",
+      "---",
+      "",
+    ],
+  },
+  "TMS: Troubleshooting Entry": {
+    "scope": "markdown",
+    "prefix": "tms-trouble",
+    "description": "Insert a troubleshooting entry",
+    "body": [
+      "### ${1:Error/Issue Name}",
+      "",
+      "**Symptoms**: ${2:How does this problem manifest?}",
+      "",
+      "**Root Cause**: ${3:Why does this happen?}",
+      "",
+      "**Solution**:",
+      "\\`\\`\\`${4|bash,typescript,javascript,python|}",
+      "${5:Code or command to fix the issue}",
+      "\\`\\`\\`",
+      "",
+      "**Prevention**: ${6:How to avoid this in the future}",
+      "",
+      "---",
+      "",
+    ],
+  },
+  "TMS: Architecture Section": {
+    "scope": "markdown",
+    "prefix": "tms-arch",
+    "description": "Insert an architecture section",
+    "body": [
+      "## ${1:Component/Layer Name}",
+      "",
+      "### 🎯 Purpose",
+      "${2:What this component does and why it exists}",
+      "",
+      "### 🏗️ Structure",
+      "",
+      "\\`\\`\\`",
+      "${3:Directory structure or component diagram}",
+      "\\`\\`\\`",
+      "",
+      "### 🔌 Dependencies",
+      "",
+      "- **Depends On**: ${4:What this component needs}",
+      "- **Used By**: ${5:What depends on this component}",
+      "",
+      "### 🔑 Key Decisions",
+      "",
+      "- ${6:Important architectural choice 1}",
+      "- ${7:Important architectural choice 2}",
+      "",
+      "### 🔗 Related",
+      "- **ADRs**: \\`DECISIONS.md#${8:Section}\\`",
+      "- **Patterns**: \\`PATTERNS.md#${9:Section}\\`",
+      "",
+      "---",
+      "",
+    ],
+  },
+  "TMS: Code Block with Language": {
+    "scope": "markdown",
+    "prefix": "tms-code",
+    "description": "Insert a code block with language selection",
+    "body": [
+      "\\`\\`\\`${1|typescript,javascript,python,rust,go,bash,json,yaml,sql|}",
+      "${2:code}",
+      "\\`\\`\\`",
+    ],
+  },
+  "TMS: Cross-Reference Section": {
+    "scope": "markdown",
+    "prefix": "tms-xref",
+    "description": "Insert a cross-reference section",
+    "body": [
+      "## 🔗 Cross-References",
+      "",
+      "- **Architecture**: See \\`docs/core/ARCHITECTURE.md\\` for ${1:topic}",
+      "- **Patterns**: See \\`docs/core/PATTERNS.md\\` for ${2:topic}",
+      "- **Decisions**: See \\`docs/core/DECISIONS.md\\` for ${3:topic}",
+      "- **Glossary**: See \\`docs/core/GLOSSARY.md\\` for ${4:topic}",
+      "",
+    ],
+  },
+  "TMS: Definition of Done": {
+    "scope": "markdown",
+    "prefix": "tms-dod",
+    "description": "Insert a Definition of Done checklist",
+    "body": [
+      "## 🎯 Definition of Done (${1:v2.X})",
+      "- [ ] ${2:Completion criteria 1}",
+      "- [ ] ${3:Completion criteria 2}",
+      "- [ ] ${4:Completion criteria 3}",
+      "",
+    ],
+  },
+}

package/AGENTS.md

@@ -32,7 +32,7 @@ This is an MCP-first, multi-agent orchestrator control plane. The codebase lives
 
 **CLI** (`apps/control-plane/src/cli/`) -> **Supervisor** (`supervisor/`) -> **Kernel** (`core/kernel.ts`) -> **Services** (`application/services/`)
 
-- **CLI**: Entry point at `cli/aop.ts` -> delegates to `interfaces/cli/bootstrap.ts`. Commands: `run`, `status`, `resume`, `stop`, `delete`, `cleanup`, `rollback`, `init`, `dashboard`, `retry`, `send`, `attach`, `help`. `run`/`resume` support `--execution-mode <deterministic|interactive>` overrides. All responses are structured JSON with `{ ok, data/error }`. Run `aop --help` or `aop help <command>` for usage details.
+- **CLI**: Entry point at `cli/aop.ts` -> delegates to `interfaces/cli/bootstrap.ts`. Commands: `run`, `add`, `status`, `questions`, `answer`, `resume`, `stop`, `delete`, `cleanup`, `rollback`, `init`, `dashboard`, `collision`, `retry`, `merge`, `send`, `attach`, `help`. `run` and `add` accept `-fi`/`--fi` (file) and `-fl`/`--fl` (folder); `add` also supports `--resume <feature-id>` to re-enroll an existing non-terminal feature into the active execution. `run`/`resume` support `--execution-mode <deterministic|interactive>` overrides. `questions` lists persisted human-input questions for a feature, and `answer` resolves one through the shared question protocol. `collision` supports `--allow`, `--list`, `--revoke`, and `--resume` for intentional overlap approvals. `merge` supports `--sync-remote <auto|skip>` for remote/local mainline divergence handling. All responses are structured JSON with `{ ok, data/error }`. Run `aop --help` or `aop help <command>` for usage details.
 - **Kernel** (`core/kernel.ts`, ~900 lines): Deterministic orchestration engine. Manages schema validation, state, locks, plans, patches, gates, merges, and reporting. Delegates to 12+ domain services via port interfaces.
 - **Supervisor** (`supervisor/runtime.ts`): Multi-agent runtime. Resolves providers (codex, claude, gemini, etc.), loads role-specific prompts, orchestrates planning/build/QA waves, and manages lease heartbeats.
 - **MCP Tool Runtime** (`mcp/tool-runtime.ts`): Tool execution pipeline with registry-based dispatch, input/output schema validation, role-based authorization, and idempotency tracking via `operation_id`.
@@ -137,3 +137,74 @@ When beginning work from a spec file (for example `spec-files/agentic_orchestrat
 2. **As each task completes**, move it out of `## Next Tasks:` and into a new numbered `Entry N - ...` in the Completed Tasks section.
 3. **Never leave a completed task in `## Next Tasks:`**. The section must only contain work that hasn't started or isn't finished.
 4. If a task is blocked or deferred, leave it in `## Next Tasks:` with a `[BLOCKED]` or `[DEFERRED]` annotation and a one-line reason.
+
+---
+
+## TMS Operational Loop
+
+Before proposing or writing any code, follow this read order:
+
+1. `NEXT-TASKS.md` — understand current context and planned work
+2. `docs/core/DOMAIN-LOGIC.md` — invariants and kernel rules that must be preserved
+3. `docs/core/PATTERNS.md` — canonical implementation examples for this codebase
+4. `docs/core/ARCHITECTURE.md` — component map and data flow for orientation
+5. `docs/core/DECISIONS.md` — ADRs explaining why technical choices were made
+6. `docs/core/TROUBLESHOOTING.md` — known gotchas and non-obvious workarounds
+
+## Pre-Submission Checklist
+
+Before proposing or submitting any code change:
+
+- [ ] Logic verified against `docs/core/DOMAIN-LOGIC.md` invariants (state machine, lock rules, error handling).
+- [ ] Implementation follows patterns in `docs/core/PATTERNS.md` (fail + ERROR_CODES, port DI, atomic writes, import types).
+- [ ] Tests added or updated; `npm run test` passes at ≥90% coverage thresholds.
+- [ ] No `console.log` in source files under `apps/control-plane/src/` (use `console.warn`/`console.error` only).
+- [ ] No `any` types in source files; no `@ts-ignore`.
+- [ ] `npm run verify` passes clean.
+- [ ] `spec-files/progress.md` updated with a new numbered entry.
+
+## Dependency and navigation policy
+
+This repository includes an automatically generated dependency and navigation index produced by **IntentGraph**. You must use it as the primary source of truth for repository relationship questions.
+
+### Required behavior
+
+Use the IntentGraph index first whenever you need to understand:
+
+- Dependency chains between files or modules
+- Reverse dependencies
+- Import or require relationships
+- Likely impact surfaces of a code change
+- Which files should be opened next for implementation work
+
+### Index location
+
+- `./docs/core/intentgraph.index.json`
+
+### Required workflow
+
+1. Consult the IntentGraph index to identify the smallest relevant set of files.
+2. Open only those files needed to confirm implementation details.
+3. Avoid broad repo scanning when the index already answers the relationship question.
+4. If the index is missing, stale, or insufficient, regenerate it or explicitly state that analysis is proceeding without a fresh index.
+
+### Token-efficiency rule
+
+Do not load or paste the full IntentGraph output into context. Use only the relevant dependency edges, path segments, or file subsets needed for the task.
+
+### Staleness rule
+
+If the index contradicts the code, assume the index is stale until proven otherwise.
+
+## TMS Documentation References
+
+<!-- AI-DRAFT: Review before treating as canonical -->
+
+| Doc                            | Purpose                                                     |
+| :----------------------------- | :---------------------------------------------------------- |
+| `docs/core/ARCHITECTURE.md`    | Component map, data flow, deployment, security posture      |
+| `docs/core/DOMAIN-LOGIC.md`    | Business invariants (state machine, locks, patches, errors) |
+| `docs/core/PATTERNS.md`        | Canonical implementation examples with anti-patterns        |
+| `docs/core/DECISIONS.md`       | ADRs — why key technical decisions were made                |
+| `docs/core/TROUBLESHOOTING.md` | Known issues and non-obvious workarounds                    |
+| `NEXT-TASKS.md`                | Current sprint tasks and definition of done                 |

package/Agentic-Orchestrator.iml

@@ -1,12 +1,13 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<module type="WEB_MODULE" version="4">
-  <component name="NewModuleRootManager" inherit-compiler-output="true">
-    <exclude-output />
-    <content url="file://$MODULE_DIR$">
-      <excludeFolder url="file://$MODULE_DIR$/.aop" />
-      <excludeFolder url="file://$MODULE_DIR$/.worktrees" />
-    </content>
-    <orderEntry type="inheritedJdk" />
-    <orderEntry type="sourceFolder" forTests="false" />
-  </component>
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="WEB_MODULE" version="4">
+  <component name="NewModuleRootManager" inherit-compiler-output="true">
+    <exclude-output />
+    <content url="file://$MODULE_DIR$">
+      <excludeFolder url="file://$MODULE_DIR$/.aop" />
+      <excludeFolder url="file://$MODULE_DIR$/.worktrees" />
+      <excludeFolder url="file://$MODULE_DIR$/coverage" />
+    </content>
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
 </module>

package/CLAUDE.md

@@ -32,7 +32,7 @@ This is an MCP-first, multi-agent orchestrator control plane. The codebase lives
 
 **CLI** (`apps/control-plane/src/cli/`) → **Supervisor** (`supervisor/`) → **Kernel** (`core/kernel.ts`) → **Services** (`application/services/`)
 
-- **CLI**: Entry point at `cli/aop.ts` → delegates to `interfaces/cli/bootstrap.ts`. Commands: `run`, `status`, `resume`, `stop`, `delete`, `cleanup`, `rollback`, `init`, `dashboard`, `retry`, `send`, `attach`, `help`. `run`/`resume` support `--execution-mode <deterministic|interactive>` overrides. All responses are structured JSON with `{ ok, data/error }`. Run `aop --help` or `aop help <command>` for usage details.
+- **CLI**: Entry point at `cli/aop.ts` → delegates to `interfaces/cli/bootstrap.ts`. Commands: `run`, `add`, `status`, `questions`, `answer`, `resume`, `stop`, `delete`, `cleanup`, `rollback`, `init`, `dashboard`, `collision`, `retry`, `merge`, `send`, `attach`, `completion`, `help` (plus hidden `__complete` backend for generated shell scripts). `run` and `add` accept `-fi`/`--fi` (file) and `-fl`/`--fl` (folder); `add` also supports `--resume <feature-id>` to re-enroll an existing non-terminal feature into the active execution. `run`/`resume` support `--execution-mode <deterministic|interactive>` overrides. `questions` lists persisted human-input questions for a feature, and `answer` resolves one through the shared question protocol. `collision` supports `--allow`, `--list`, `--revoke`, and `--resume` for intentional overlap approvals. `merge` supports `--sync-remote <auto|skip>` for remote/local mainline divergence handling. `completion` emits Bash/Zsh/Fish registration scripts. All responses are structured JSON with `{ ok, data/error }`. Run `aop --help` or `aop help <command>` for usage details.
 - **Kernel** (`core/kernel.ts`, ~900 lines): Deterministic orchestration engine. Manages schema validation, state, locks, plans, patches, gates, merges, and reporting. Delegates to 12+ domain services via port interfaces.
 - **Supervisor** (`supervisor/runtime.ts`): Multi-agent runtime. Resolves providers (codex, claude, gemini, etc.), loads role-specific prompts, orchestrates planning/build/QA waves, manages lease heartbeats.
 - **MCP Tool Runtime** (`mcp/tool-runtime.ts`): Tool execution pipeline with registry-based dispatch, input/output schema validation, role-based authorization, and idempotency tracking via `operation_id`.
@@ -137,3 +137,74 @@ When beginning work from a spec file (e.g. `spec-files/agentic_orchestrator_*.md
 2. **As each task completes**, move it out of `## Next Tasks:` and into a new numbered `✅ **Entry N — ...`\*\* in the Completed Tasks section.
 3. **Never leave a completed task in `## Next Tasks:`**. The section must only contain work that hasn't started or isn't finished.
 4. If a task is blocked or deferred, leave it in `## Next Tasks:` with a `[BLOCKED]` or `[DEFERRED]` annotation and a one-line reason.
+
+---
+
+## TMS Operational Loop
+
+Before proposing or writing any code, follow this read order:
+
+1. `NEXT-TASKS.md` — understand current context and planned work
+2. `docs/core/DOMAIN-LOGIC.md` — invariants and kernel rules that must be preserved
+3. `docs/core/PATTERNS.md` — canonical implementation examples for this codebase
+4. `docs/core/ARCHITECTURE.md` — component map and data flow for orientation
+5. `docs/core/DECISIONS.md` — ADRs explaining why technical choices were made
+6. `docs/core/TROUBLESHOOTING.md` — known gotchas and non-obvious workarounds
+
+## Pre-Submission Checklist
+
+Before proposing or submitting any code change:
+
+- [ ] Logic verified against `docs/core/DOMAIN-LOGIC.md` invariants (state machine, lock rules, error handling).
+- [ ] Implementation follows patterns in `docs/core/PATTERNS.md` (fail + ERROR_CODES, port DI, atomic writes, import types).
+- [ ] Tests added or updated; `npm run test` passes at ≥90% coverage thresholds.
+- [ ] No `console.log` in source files under `apps/control-plane/src/` (use `console.warn`/`console.error` only).
+- [ ] No `any` types in source files; no `@ts-ignore`.
+- [ ] `npm run verify` passes clean.
+- [ ] `spec-files/progress.md` updated with a new numbered entry.
+
+## Dependency and navigation policy
+
+This repository includes an automatically generated dependency and navigation index produced by **IntentGraph**. You must use it as the primary source of truth for repository relationship questions.
+
+### Required behavior
+
+Use the IntentGraph index first whenever you need to understand:
+
+- Dependency chains between files or modules
+- Reverse dependencies
+- Import or require relationships
+- Likely impact surfaces of a code change
+- Which files should be opened next for implementation work
+
+### Index location
+
+- `./docs/core/intentgraph.index.json`
+
+### Required workflow
+
+1. Consult the IntentGraph index to identify the smallest relevant set of files.
+2. Open only those files needed to confirm implementation details.
+3. Avoid broad repo scanning when the index already answers the relationship question.
+4. If the index is missing, stale, or insufficient, regenerate it or explicitly state that analysis is proceeding without a fresh index.
+
+### Token-efficiency rule
+
+Do not load or paste the full IntentGraph output into context. Use only the relevant dependency edges, path segments, or file subsets needed for the task.
+
+### Staleness rule
+
+If the index contradicts the code, assume the index is stale until proven otherwise.
+
+## TMS Documentation References
+
+<!-- AI-DRAFT: Review before treating as canonical -->
+
+| Doc                            | Purpose                                                     |
+| :----------------------------- | :---------------------------------------------------------- |
+| `docs/core/ARCHITECTURE.md`    | Component map, data flow, deployment, security posture      |
+| `docs/core/DOMAIN-LOGIC.md`    | Business invariants (state machine, locks, patches, errors) |
+| `docs/core/PATTERNS.md`        | Canonical implementation examples with anti-patterns        |
+| `docs/core/DECISIONS.md`       | ADRs — why key technical decisions were made                |
+| `docs/core/TROUBLESHOOTING.md` | Known issues and non-obvious workarounds                    |
+| `NEXT-TASKS.md`                | Current sprint tasks and definition of done                 |