agentic-orchestrator 0.1.0

package/prompts/vitest-testing-standards.instructions.md

@@ -0,0 +1,204 @@
+# Agentic Vitest Test Generation Prompt (TypeScript Package)
+
+You are a senior TypeScript engineer and testing specialist. Your job is to add **production-grade Vitest tests** to an existing TypeScript package with **minimal churn** and **maximum correctness**.
+
+---
+
+## Mission
+
+Given a repository/package, produce a **complete, reliable** test suite using **Vitest** that:
+
+- Validates behavior (not implementation details)
+- Covers edge cases and failure modes
+- Is deterministic (no flaky timing/network/randomness)
+- Integrates cleanly with the repo’s existing tooling and conventions
+
+---
+
+## Non-Negotiables
+
+- **Use Vitest** (`describe/it/expect`, `vi` mocks/spies, fake timers when needed).
+- **Match existing repo conventions**: folder structure, naming, lint rules, tsconfig, ESM/CJS style, path aliases, formatting.
+- **No brittle tests**: avoid testing private functions via hacks; test through public API unless explicitly instructed.
+- **No snapshot spam**: only use snapshots when they clearly add value (e.g., stable formatted outputs).
+- **Deterministic tests**: do not depend on real time, environment, network, filesystem state, or execution order.
+- **Minimal churn**: don’t refactor product code unless a tiny change is necessary for testability; if needed, propose the smallest safe change.
+
+---
+
+## Phase 0 — Setup Recon (Repository Understanding)
+
+1. Inspect and summarize:
+   - Package type: ESM/CJS, Node/browser, library entrypoints
+   - Build tool (tsup, tsc, rollup, vite, etc.)
+   - Test setup: `vitest.config.*`, existing test files, setup files, globals config
+   - Lint/format rules and strictness
+   - Any existing mocking utilities / test helpers
+2. Identify **how tests should be run in this repo**, including:
+   - `pnpm/yarn/npm` commands
+   - coverage commands
+   - watch mode conventions
+
+**Output:** A short **Test Environment Summary** and the exact commands to run tests locally.
+
+---
+
+## Phase 1 — Test Strategy + Coverage Map (Before Writing Tests)
+
+1. List the **public API surface** (exports) and important internal modules.
+2. Create a **coverage map**:
+   - Each function/class/module → key behaviors to test
+   - Happy path + edge cases + error handling
+   - Any concurrency/async behavior
+   - Any parsing/validation boundaries
+3. Call out what should be mocked vs. tested real:
+   - External I/O (fs, http, database): mock (or use temp dirs if explicitly permitted)
+   - Pure logic: test directly
+   - Time: fake timers / fixed clocks
+4. Identify “hard parts” (e.g., timers, retries, nondeterminism) and specify the approach.
+
+**Output:** A structured test plan with a checklist of tests to implement.
+
+---
+
+## Phase 2 — Implementation Rules (How to Write Tests)
+
+### File placement and naming
+
+- Follow the repo’s pattern (e.g., `src/**/__tests__/*.test.ts` or `test/*.spec.ts`).
+- Prefer co-located tests near modules unless repo uses centralized `test/`.
+
+### Test design principles
+
+- Use **Given / When / Then** structure in test naming:
+  - `GIVEN_<context>_WHEN_<action>_THEN_<expected>`
+- One behavior per test.
+- Prefer black-box tests through exported functions/classes.
+- Avoid over-mocking. Mock only what introduces nondeterminism or heavy I/O.
+
+### Mocking and isolation
+
+- Use `vi.mock()` for module mocks; `vi.spyOn()` for selective mocking.
+- Reset state between tests:
+  - `beforeEach(() => { vi.restoreAllMocks(); vi.clearAllMocks(); })` as appropriate
+- Ensure module isolation when needed:
+  - Use `vi.resetModules()` only when truly necessary (it can slow down and hide issues).
+
+### Async + timers
+
+- For async:
+  - Use `await` and proper assertions (no dangling promises).
+- For timers/retries:
+  - Use `vi.useFakeTimers()` and `vi.advanceTimersByTimeAsync()` / `vi.runAllTimersAsync()`.
+
+### Error handling assertions
+
+- Assert on error type and message (when stable), e.g.:
+  - `await expect(fn()).rejects.toThrow(/pattern/)`
+
+---
+
+## Phase 3 — Change Policy (When You Must Touch Product Code)
+
+If tests are blocked because the code is untestable:
+
+1. Propose the smallest change (e.g., dependency injection, parameterizing time, separating pure logic).
+2. Explain why it’s necessary.
+3. Implement only after ensuring it doesn’t change runtime behavior.
+
+---
+
+## Phase 4 — Deliverables
+
+You must provide:
+
+1. **A list of files created/modified** (with short purpose notes).
+2. The **complete test code** for each new/modified file.
+3. Any **config changes** required for Vitest (aliases, setup files, environment, coverage).
+4. The exact commands to run:
+   - unit tests
+   - coverage
+   - a focused subset (single file / single test name)
+
+---
+
+## Test Coverage Requirements (Required Section)
+
+You must include a dedicated coverage section in your output and ensure coverage is configured correctly.
+
+### Coverage configuration
+
+1. Detect current coverage tooling:
+   - Vitest coverage provider (`v8` or `istanbul`)
+   - Existing thresholds (global and per-file) from config or CI
+2. Ensure include/exclude patterns align with the package layout:
+   - Include: `src/**/*.{ts,tsx}` (or repo-specific)
+   - Exclude: `**/*.d.ts`, `**/*.test.*`, `**/*.spec.*`, `**/__tests__/**`, build outputs (`dist/**`), generated files
+3. If the repo uses path aliases, ensure coverage maps to original TS sources (not built JS).
+
+### Coverage goals
+
+- Prioritize **meaningful coverage**:
+  - Core logic, branching conditions, error paths, parsing/validation boundaries
+  - Avoid chasing trivial lines (barrel exports, constants with no logic, type-only files)
+- If no thresholds exist, propose sensible defaults:
+  - **Statements/Lines:** 85–95% on core modules
+  - **Branches:** 80–90% on core modules
+  - **Functions:** 85–95% on core modules
+  - Note: do **not** set aggressive global thresholds if the repo is currently far below; instead, propose incremental improvement.
+
+### Coverage reporting output
+
+In your final response, include:
+
+- Coverage command(s) to run
+- Summary of what improved (which modules are now covered)
+- Any gaps you intentionally left and why (e.g., thin wrappers, environment-specific code)
+
+---
+
+## Quality Gates (You Must Pass These)
+
+Before finalizing, verify:
+
+- Tests pass locally with the repo’s package manager command.
+- Coverage meets or improves existing thresholds (or your proposed incremental target).
+- No flaky behavior:
+  - time is controlled
+  - random is seeded or stubbed
+  - network/fs not used unless explicitly allowed
+- CI friendliness:
+  - no reliance on machine-specific paths
+  - no long sleeps; use fake timers
+
+---
+
+## Required Questions (Ask Early, Then Proceed With Best Assumptions)
+
+Ask only what you truly need. If unanswered, proceed with **sensible defaults** and clearly state assumptions.
+
+1. Package manager: pnpm / yarn / npm?
+2. Runtime target: Node / browser / both?
+3. ESM or CJS?
+4. Coverage expectations: any thresholds or “must test” modules?
+5. Should we mock I/O or run in temp dirs (if filesystem is involved)?
+
+---
+
+## Output Format
+
+Produce your response in this exact structure:
+
+1. **Test Environment Summary**
+2. **Test Plan + Coverage Map**
+3. **Test Coverage**
+4. **Changes Made (Files + Rationale)**
+5. **Patch (Code)**
+6. **How to Run (Commands)**
+7. **Notes / Assumptions**
+
+---
+
+## Optional Add-On: Existing Tests
+
+If tests already exist, **extend them** rather than rewriting. Only introduce new helpers if they reduce duplication meaningfully.

package/scripts/dev-shell-env.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env sh
+
+# Source this script to configure Nx for environments that disallow
+# Unix socket listeners used by daemon/plugin worker isolation.
+export NX_DAEMON="${NX_DAEMON:-false}"
+export NX_ISOLATE_PLUGINS="${NX_ISOLATE_PLUGINS:-false}"
+

package/scripts/nx-safe.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import process from "node:process";
+
+const require = createRequire(import.meta.url);
+const nxCliPath = require.resolve("nx/bin/nx.js");
+
+const env = {
+  ...process.env,
+  NX_DAEMON: process.env.NX_DAEMON ?? "false",
+  NX_ISOLATE_PLUGINS: process.env.NX_ISOLATE_PLUGINS ?? "false"
+};
+
+const child = spawn(process.execPath, [nxCliPath, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  env
+});
+
+child.on("error", (error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`[nx-safe] Failed to execute Nx CLI: ${message}`);
+  process.exit(1);
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+
+  process.exit(code ?? 1);
+});

package/spec-files/agentic_orchestrator_cli_delete_command_spec.md

@@ -0,0 +1,310 @@
+# Feature Spec: CLI `delete` Command with Deterministic Feature Cleanup (AOP)
+
+> **Purpose of this document**: Define an implementation-ready, safety-first `aop delete` command that replaces the current CLI placeholder behavior with deterministic cleanup of feature runtime artifacts, index/session references, locks/queue residue, and optional git worktree/branch state.
+
+---
+
+## 1. Objectives
+
+### 1.1 Must-Have Outcomes
+
+- Provide a real `aop delete` command for feature cleanup.
+- Keep deterministic behavior aligned with MCP/kernel architecture:
+  - schema-validated tool contracts
+  - atomic canonical state mutation
+  - role authorization and idempotent mutation semantics
+- Delete command MUST safely clean orchestration residue for a feature:
+  - feature runtime files
+  - index references (`active`, `blocked`, `merged`, blocked queue entries, runtime session assignment)
+  - held lock references and lock leases
+  - optional git worktree cleanup
+  - optional local branch cleanup
+- Command MUST be safe-by-default (preview path before destructive mutation).
+- Preserve current `run/status/resume/stop` behavior while introducing `delete`.
+
+### 1.2 Non-Goals
+
+- No change to orchestration algorithm, gate policy, or merge semantics.
+- No implementation of remote branch deletion.
+- No stop-command redesign in this phase beyond clarifying placeholder status.
+
+---
+
+## 2. Current State Analysis (Codebase)
+
+1. CLI supports only `run|status|resume|stop` (`apps/control-plane/src/interfaces/cli/bootstrap.ts`).
+2. Placeholder behavior exists in `StopCommandHandler` only:
+   - returns `{ status: "stop_not_implemented_yet" }`
+   - no lease/session/worktree cleanup (`apps/control-plane/src/cli/stop-command-handler.ts`).
+3. There is no `delete` command parser path and no `DeleteCommandHandler`.
+4. There is no MCP tool contract for feature deletion:
+   - no `feature.delete` in `agentic/orchestrator/tools/catalog.json`
+   - no input/output schemas for deletion.
+5. Kernel/service layer has no cohesive feature cleanup use case:
+   - no API for deleting feature artifacts + index/runtime/lock residue in one deterministic operation.
+
+---
+
+## 3. CLI Contract for `delete`
+
+### 3.1 Primary Command
+
+```bash
+aop delete --feature-id <feature_id> [options]
+```
+
+### 3.2 Options
+
+- `--feature-id <id>` (required)
+- `--dry-run` (optional; default when `--yes` is absent)
+- `--yes` (required for destructive execution)
+- `--remove-worktree` (optional; default `true`)
+- `--remove-branch <none|safe|force>` (optional; default `none`)
+- `--transport <mcp|inprocess>` (existing behavior retained)
+
+### 3.3 Safety Rules
+
+- If `--yes` is not provided, command MUST run preview-only and perform no mutations.
+- `--dry-run` and `--yes` MAY both be provided only if `--dry-run=true` semantics are explicitly chosen; otherwise fail `invalid_cli_args`.
+- If a fresh active run lease exists, deletion MUST fail with `run_already_active` (unless later explicitly expanded by policy in a separate spec).
+
+### 3.4 Response Contract
+
+On success:
+- `ok: true`
+- `data.command: "delete"`
+- `data.feature_id`
+- `data.dry_run`
+- `data.plan` (preview) and/or `data.applied` (execution)
+- `data.summary` with explicit booleans/counts:
+  - `feature_dir_removed`
+  - `worktree_removed`
+  - `branch_removed`
+  - `index_updated`
+  - `locks_released[]`
+  - `blocked_queue_entries_removed`
+  - `runtime_session_assignment_removed`
+
+On failure:
+- standard normalized error envelope already used by CLI.
+
+---
+
+## 4. Core Capabilities (Required)
+
+1. Deterministic preview:
+   - enumerate exactly what will be removed/updated before execution.
+2. Active-run guard:
+   - block deletion when lease is fresh to prevent state/session races.
+3. Lock and queue residue cleanup:
+   - release held locks for target feature.
+   - remove blocked-queue entries for target feature.
+4. Canonical index/session cleanup:
+   - remove feature from `active`, `blocked`, `merged`.
+   - remove `runtime_sessions.feature_sessions[feature_id]`.
+5. Runtime artifact deletion:
+   - remove feature runtime directory recursively.
+6. Git cleanup options:
+   - remove feature worktree (`git worktree remove --force`).
+   - optional local branch delete (`git branch -d` safe, `-D` force).
+7. Idempotent mutation behavior:
+   - tool-level mutation participates in existing operation ledger semantics.
+
+---
+
+## 5. Optimal Architecture
+
+### 5.1 Implement as MCP Mutating Tool, not CLI-Local FS Logic
+
+Add new tool: `feature.delete`
+
+- Rationale:
+  - keeps deterministic mutation in control plane (kernel/service), not ad-hoc CLI code
+  - preserves MCP/in-process parity
+  - preserves RBAC + schema + idempotency guarantees
+  - enables future orchestrator/system-initiated cleanup reuse
+
+### 5.2 Add Dedicated Service
+
+- New application service:
+  - `apps/control-plane/src/application/services/feature-deletion-service.ts`
+- Kernel registers tool handler that delegates to service.
+- Service owns cleanup algorithm and returns structured deterministic summary.
+
+### 5.3 Path Layout Compatibility
+
+- Service MUST use kernel/path accessors (`featurePath`, `worktreePath`, etc.) and MUST NOT hardcode layout roots.
+- This keeps compatibility with current `agentic/features/**` and upcoming `.aop/**` runtime-root migration spec.
+
+---
+
+## 6. Tool Contract Additions
+
+### 6.1 Catalog and Metadata
+
+- Add `feature.delete` entry to:
+  - `agentic/orchestrator/tools/catalog.json`
+  - `apps/control-plane/src/core/constants.ts` (`TOOLS.FEATURE_DELETE`)
+  - `apps/control-plane/src/application/tools/tool-metadata.ts` (mutating, requires operation id)
+  - `agentic/orchestrator/policy.yaml` RBAC:
+    - allow `system`
+    - optional `orchestrator` (recommended)
+
+### 6.2 Schemas
+
+Add:
+- `agentic/orchestrator/tools/schemas/input/feature.delete.input.schema.json`
+- `agentic/orchestrator/tools/schemas/output/feature.delete.output.schema.json`
+
+Input MUST include:
+- `operation_id`
+- `feature_id`
+- execution mode fields (`dry_run`/`confirm` or equivalent)
+- cleanup toggles (`remove_worktree`, `remove_branch`)
+
+Output MUST include:
+- target `feature_id`
+- mode (`dry_run`)
+- deterministic summary fields listed in Section 3.4.
+
+### 6.3 Tools Markdown and Contract Validation
+
+- Regenerate `agentic/orchestrator/tools.md`.
+- `npm run validate:mcp-contracts` MUST pass with the new tool included.
+
+---
+
+## 7. Deterministic Delete Algorithm (Normative)
+
+For target `feature_id`:
+
+1. Validate arguments and feature identifier.
+2. Load index/runtime sessions and fail if run lease is fresh.
+3. Build preflight snapshot:
+   - feature files present/missing
+   - held locks in state
+   - blocked queue entries
+   - runtime session assignment
+   - worktree/branch existence
+4. If preview mode: return preflight summary only.
+5. Execution mode:
+   - release each held lock via existing lock service path
+   - remove blocked queue entries for feature
+   - atomically update index:
+     - remove feature from `active|blocked|merged`
+     - clear any `locks`/`lock_leases` still pointing to feature
+     - remove `runtime_sessions.feature_sessions[feature_id]`
+     - increment index version and timestamp
+   - remove feature runtime directory recursively
+   - remove worktree if enabled
+   - remove local branch per `remove_branch` policy
+6. Return applied summary with explicit per-step results.
+
+---
+
+## 8. File-Level Change Targets
+
+- CLI:
+  - `apps/control-plane/src/cli/cli-argument-parser.ts`
+  - `apps/control-plane/src/cli/types.ts`
+  - `apps/control-plane/src/cli/delete-command-handler.ts` (new)
+  - `apps/control-plane/src/interfaces/cli/bootstrap.ts`
+- Core/Application:
+  - `apps/control-plane/src/core/constants.ts`
+  - `apps/control-plane/src/core/kernel.ts`
+  - `apps/control-plane/src/application/services/feature-deletion-service.ts` (new)
+  - `apps/control-plane/src/application/tools/tool-metadata.ts`
+  - `apps/control-plane/src/core/error-codes.ts` (if new delete-specific codes are introduced)
+- MCP contracts:
+  - `agentic/orchestrator/tools/catalog.json`
+  - `agentic/orchestrator/tools/schemas/input/feature.delete.input.schema.json` (new)
+  - `agentic/orchestrator/tools/schemas/output/feature.delete.output.schema.json` (new)
+  - `agentic/orchestrator/tools.md` (generated)
+  - `agentic/orchestrator/policy.yaml` (rbac entries as needed)
+- Docs:
+  - `README.md`
+
+---
+
+## 9. Test Plan (Vitest, Normative)
+
+### 9.1 CLI Tests
+
+- `delete` command recognized by parser/bootstrap.
+- `--feature-id` required.
+- preview mode default (no `--yes`) performs no mutation.
+- destructive mode requires explicit confirmation.
+- invalid option combinations return `invalid_cli_args`.
+
+### 9.2 Service and Kernel Tests
+
+- delete fails when fresh run lease exists (`run_already_active`).
+- delete releases locks and removes blocked-queue entries.
+- delete removes index membership and feature session assignment.
+- delete removes feature directory and optional worktree.
+- branch deletion mode `safe` vs `force` behavior.
+- idempotent re-run behavior on already-deleted feature (defined and tested).
+
+### 9.3 MCP Contract Tests
+
+- `feature.delete` listed in tools list with expected mutating contract.
+- input/output schema validation enforced.
+- role authorization intersection behavior verified.
+
+---
+
+## 10. Milestones
+
+### M23: CLI + Contract Surface
+
+- Add `delete` command parsing/dispatch and command handler.
+- Add tool catalog entry + schemas + generated tools doc.
+
+### M24: Service Implementation
+
+- Implement `FeatureDeletionService` and kernel handler wiring.
+- Implement deterministic cleanup algorithm and summaries.
+
+### M25: Safety and Git Cleanup
+
+- Implement fresh-lease guard, preview/confirm flow, optional worktree/branch cleanup.
+
+### M26: Docs + Validation
+
+- Update README command docs and examples.
+- Re-verify with `lint`, `typecheck`, `test`, and `validate:mcp-contracts`.
+
+---
+
+## 11. Acceptance Criteria
+
+1. `aop delete --feature-id <id>` exists and returns deterministic preview output by default.
+2. Destructive execution requires explicit confirmation and returns explicit cleanup summary.
+3. No deletion proceeds while a fresh run lease is active.
+4. Feature deletion clears feature state from index + runtime session assignment + blocked queue + lock residue.
+5. Optional worktree/branch cleanup behaves as specified.
+6. MCP contract artifacts and validation gates remain green.
+7. Existing `run/status/resume` behavior remains unchanged; `stop` placeholder remains explicitly documented until separately implemented.
+
+---
+
+## 12. Risks and Mitigations
+
+- Risk: accidental destructive deletion.
+  - Mitigation: preview-by-default + explicit `--yes` requirement.
+- Risk: deleting during active run corrupts orchestration state.
+  - Mitigation: hard fresh-lease guard (`run_already_active`).
+- Risk: partial cleanup leaves stale references.
+  - Mitigation: ordered deterministic algorithm + summary assertions + tests.
+- Risk: contract drift after adding tool.
+  - Mitigation: catalog/schema/tools.md regeneration and contract CI validation.
+
+---
+
+## 13. Dependency Notes
+
+- Aligns with:
+  - `spec-files/agentic_orchestrator_spec.md` (CLI/runtime deterministic contract)
+  - `spec-files/agentic_orchestrator_mcp_formalization_spec.md` (formal tool contract + idempotency requirements)
+  - `spec-files/agentic_orchestrator_oop_refactor_spec.md` (service-oriented extension points)
+  - `spec-files/agentic_orchestrator_dot_aop_generated_artifacts_spec.md` (runtime path abstraction compatibility)