# Feature Spec: Relocate Generated Runtime Artifacts to `.aop/` (AOP)

> **Purpose of this document**: Define an implementation-ready migration plan that moves runtime-generated AOP files out of `agentic/` and into a dedicated hidden runtime directory `.aop/`, while preserving deterministic MCP/Supervisor behavior and existing CLI/tool semantics.

---

## 1. Objectives

### 1.1 Must-Have Outcomes

- Runtime-generated artifacts MUST be written under `.aop/` instead of `agentic/`.
- Deterministic orchestration guarantees MUST remain unchanged:
  - schema validation
  - optimistic concurrency/version checks
  - lock/collision behavior
  - gate/evidence behavior
  - explicit merge control
- CLI workflows (`run`, `status`, `resume`, `stop`) MUST keep existing behavior and error envelopes.
- Existing repositories with generated files under `agentic/` MUST be supported through a deterministic migration/compatibility path.
- Path ownership MUST be explicit:
  - source-managed orchestrator config stays in `agentic/orchestrator/`
  - runtime-generated feature/runtime state moves to `.aop/`

### 1.2 Non-Goals

- No changes to tool names, role permissions, or gate policy semantics.
- No replacement of file-backed state with DB-backed persistence.
- No provider/session model changes.

---

## 2. Canonical Path Contract

### 2.1 Source-Managed (unchanged)

- `agentic/orchestrator/**` remains source-managed:
  - `gates.yaml`, `policy.yaml`, `agents.yaml`
  - `schemas/**`
  - `tools/catalog.json`, `tools/protocol.json`, `tools/errors.schema.json`, `tools/schemas/**`

### 2.2 Runtime-Generated (new location)

- `.aop/features/index.json`
- `.aop/features/<feature_id>/spec.md` (canonical ingested spec copy)
- `.aop/features/<feature_id>/state.md`
- `.aop/features/<feature_id>/plan.json`
- `.aop/features/<feature_id>/qa_test_index.json`
- `.aop/features/<feature_id>/decisions.md`
- `.aop/features/<feature_id>/logs/**`
- `.aop/features/<feature_id>/evidence/**`
- `.aop/runtime/operation-ledger/<run_id>.json`

### 2.3 Discovery/Canonicalization Rules

- `feature.discover_specs` MUST discover canonical specs under `.aop/features/*/spec.md`.
- `aop run -fi/-fl` MUST ingest non-canonical input into `.aop/features/<feature_id>/spec.md`.
- Feature ID derivation rules (`.spec`, `-spec`, slug regex) MUST remain unchanged.

---

## 3. Architecture Decisions

### 3.1 Introduce a Single Runtime Path Authority

- Add a typed path-layout abstraction (for example `AopPathLayout`) used by CLI, kernel, services, and MCP runtime helpers.
- The abstraction MUST provide explicit getters for:
  - source config roots (`agentic/orchestrator`)
  - runtime data roots (`.aop/features`, `.aop/runtime`)
  - per-feature generated files (`state.md`, `plan.json`, etc.)

### 3.2 Keep Schema/Policy Roots Stable

- Schema/policy/catalog load paths remain under `agentic/orchestrator/**`.
- Only generated runtime paths move to `.aop/**`.

### 3.3 Deterministic Compatibility Window

- Startup/runtime access MUST support deterministic migration from legacy `agentic/features/**` and `agentic/runtime/**`:
  - if `.aop/**` exists, it is authoritative
  - if `.aop/**` is absent and legacy exists, migrate/copy forward
  - no destructive deletion during migration step

---

## 4. Required Code Changes

### 4.1 Core and Services

- Update runtime path ownership in:
  - `apps/control-plane/src/core/kernel.ts`
  - `apps/control-plane/src/application/services/feature-lifecycle-service.ts`
  - `apps/control-plane/src/application/services/feature-state-service.ts`
  - `apps/control-plane/src/application/services/plan-service.ts`
  - `apps/control-plane/src/application/services/qa-index-service.ts`
  - `apps/control-plane/src/application/services/gate-service.ts`
  - `apps/control-plane/src/application/services/reporting-service.ts`
  - `apps/control-plane/src/application/services/merge-service.ts`
- Ensure lock/index/state atomic-write paths now target `.aop/features/**`.

### 4.2 CLI and Spec Ingestion

- Update canonical spec detection/ingestion:
  - `apps/control-plane/src/cli/spec-utils.ts`
  - `apps/control-plane/src/cli/spec-input-resolver.ts`
  - `apps/control-plane/src/cli/spec-ingestion-service.ts`
- CLI outputs and status payload paths MUST reference `.aop/**` canonical locations.

### 4.3 MCP Runtime Helpers

- Move operation ledger storage root from `agentic/runtime/operation-ledger` to `.aop/runtime/operation-ledger` in:
  - `apps/control-plane/src/mcp/operation-ledger.ts`

### 4.4 Documentation and Ignore Rules

- Update `README.md` runtime path references from `agentic/features/**` to `.aop/features/**` where describing generated artifacts.
- Add `.aop/` to `.gitignore` (except intentional tracked placeholders if any).

---

## 5. Test Plan (Normative)

### 5.1 Unit/Integration Coverage Additions

- Add/adjust tests for:
  - canonical path detection for `.aop/features/<id>/spec.md`
  - non-canonical ingestion target path under `.aop/features/<id>/spec.md`
  - `feature.discover_specs` returning `.aop/**` paths
  - operation-ledger writes to `.aop/runtime/operation-ledger/**`
  - state/index/QA/evidence paths under `.aop/features/**`
  - legacy-to-`.aop` migration behavior and precedence

### 5.2 Regression Requirements

- Existing CLI contract tests for `run/status/resume/stop` MUST pass unchanged at envelope/exit-code level.
- Existing MCP transport parity tests MUST pass unchanged for success/failure semantics.

---

## 6. Implementation Milestones

### M19: Path Layout Foundation

- Introduce centralized path abstraction and wire kernel/service/CLI callsites to it.

### M20: Generated Artifact Relocation

- Move runtime-generated write paths to `.aop/features/**` and `.aop/runtime/**`.
- Keep orchestrator config/schema/tool contracts in `agentic/orchestrator/**`.

### M21: Compatibility + Migration

- Implement deterministic legacy detection and forward migration from `agentic/**` generated roots.
- Add explicit tests for precedence and no-data-loss behavior.

### M22: Contract/Docs/CI Hardening

- Update README/runtime docs and command examples.
- Ensure lint/typecheck/test/contract validation gates remain green.

---

## 7. File-Level Target List

- `apps/control-plane/src/core/kernel.ts`
- `apps/control-plane/src/core/schemas.ts` (no root move expected; verify unchanged orchestrator schema root)
- `apps/control-plane/src/cli/spec-utils.ts`
- `apps/control-plane/src/cli/spec-input-resolver.ts`
- `apps/control-plane/src/cli/spec-ingestion-service.ts`
- `apps/control-plane/src/application/services/feature-lifecycle-service.ts`
- `apps/control-plane/src/application/services/feature-state-service.ts`
- `apps/control-plane/src/application/services/plan-service.ts`
- `apps/control-plane/src/application/services/qa-index-service.ts`
- `apps/control-plane/src/application/services/gate-service.ts`
- `apps/control-plane/src/application/services/reporting-service.ts`
- `apps/control-plane/src/application/services/merge-service.ts`
- `apps/control-plane/src/mcp/operation-ledger.ts`
- `apps/control-plane/test/**/*.spec.ts` (path assertions and migration coverage)
- `README.md`
- `.gitignore`

---

## 8. Acceptance Criteria

1. New runs create/update runtime artifacts under `.aop/**` only.
2. No new runtime-generated files are written under `agentic/features/**` or `agentic/runtime/**`.
3. `feature.discover_specs` and CLI ingestion canonicalize to `.aop/features/<feature_id>/spec.md`.
4. Legacy repositories with prior `agentic/**` generated artifacts continue to run via deterministic migration/compatibility behavior.
5. CLI/MCP tool contracts, error envelopes, and deterministic orchestration semantics remain intact.
6. `npm run lint`, `npm run typecheck`, `npm test`, and `npm run validate:mcp-contracts` pass after migration changes.

---

## 9. Risks and Mitigations

- Risk: Partial path migration causes split state across `agentic/**` and `.aop/**`.
  - Mitigation: single path authority abstraction + explicit precedence rules + migration tests.
- Risk: Existing automation/scripts rely on `agentic/features/**`.
  - Mitigation: compatibility window, README migration notes, and deterministic fallback logic.
- Risk: Review workflows lose visibility if users are unaware of `.aop/**`.
  - Mitigation: update README review instructions and CLI output paths.

---

## 10. Dependency Notes

- This spec extends and narrows file-layout behavior from:
  - `spec-files/agentic_orchestrator_spec.md` (canonical state/runtime contracts)
  - `spec-files/agentic_orchestrator_mcp_formalization_spec.md` (formal tool/runtime boundary)
  - `spec-files/agentic_orchestrator_oop_refactor_spec.md` (path abstraction and layered responsibility discipline)
- Must also updatea progress.md filed `spec-files/progress.md` to reflect this new spec and its milestones as it is completed.
