agentic-orchestrator 0.1.28 → 0.2.0

package/specs/002-scope-aware-lease/plan.md

@@ -0,0 +1,766 @@
+# Implementation Plan: Scope-Aware Run Lease
+
+**Branch**: `002-scope-aware-lease` | **Date**: 2025-07-23 | **Spec**: [`specs/002-scope-aware-lease/spec.md`](./spec.md)  
+**Input**: Feature specification — replace the global exclusive run lease with a scope-aware conflict detector that only blocks executions whose declared codebase scopes overlap.
+
+---
+
+## Summary
+
+The current `RunLeaseService` allows only one active run at a time, regardless of which parts of the codebase each run touches. This feature replaces that global barrier with scope-aware conflict detection: when a new run requests a lease, the system compares its declared `LeaseScope` (file-system paths + plan section IDs) against all currently active leases in a shared **Lease Registry**. Two runs with non-overlapping scopes are both granted leases; overlapping scopes are serialized. Runs with an unknown (`null`) scope follow the conservative fallback and block against everything.
+
+**Technical approach:**
+
+1. Add a `LeaseScope` / `LeaseScopeDeclaration` type and `ActiveLeaseRecord` to the data model.
+2. Introduce a new global **Lease Registry** file (`.aop/runtime/lease-registry.json`) protected by the existing index-level atomic lock.
+3. Extract pure scope-overlap logic into a new `LeaseScopeConflictDetector` service (no I/O).
+4. Update `RunLeaseService.acquireRunLease` to consult the registry and detect conflicts before granting; update `releaseRunLease` and `renewRunLease` to maintain registry state.
+5. Add `expandRunLeaseScope` for mid-run scope expansion (FR-007).
+6. Propagate scope from CLI / feature inputs through `RunCoordinator` → kernel.
+7. New error code `LEASE_SCOPE_CONFLICT` for observable deferral logging (FR-010).
+
+---
+
+## Technical Context
+
+**Language/Version**: TypeScript 5.9 strict, Node.js ESM  
+**Primary Dependencies**: AJV (JSON Schema validation), `node:crypto`, `node:path`, Vitest  
+**Storage**: File-system JSON (`.aop/runtime/lease-registry.json`); atomic writes via `atomicWriteJson`; locking via `withFileLock`  
+**Testing**: Vitest — ≥90% lines/branches/functions/statements  
+**Target Platform**: Local CLI (`aop` binary), Node.js 20+  
+**Project Type**: CLI application — Nx monorepo single app (`apps/control-plane/`)  
+**Performance Goals**: Scope conflict check adds <1 ms overhead per acquisition attempt (registry is single-digit entries; exhaustive pairwise comparison is acceptable per spec assumption)  
+**Constraints**: No `any` in source, no `@ts-ignore`, `import type` for type-only imports, `fail()` + `ERROR_CODES` for all domain failures, `withFileLock` for all state mutations  
+**Scale/Scope**: Registry holds single-digit concurrent run leases; no indexing strategy needed
+
+---
+
+## Constitution Check
+
+_GATE: Must pass before Phase 0 research. Re-checked after Phase 1 design._
+
+| Principle                                            | Status | Notes                                                                                      |
+| ---------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------ | ----- |
+| KISS — prefer the simplest design                    | ✅     | Pairwise registry scan is O(n²) but n is always single-digit; no index needed              |
+| SRP — each module has one reason to change           | ✅     | Pure conflict-detection logic isolated in `LeaseScopeConflictDetector`                     |
+| Open/Closed — extend by adding adapters/services     | ✅     | Existing `RunLeaseService` extended via new port methods; no unrelated kernel code touched |
+| DI (Hexagonal) — depend on ports, not concrete infra | ✅     | New registry read/write go through `RunLeaseServicePort` methods                           |
+| No `any` in source                                   | ✅     | All new types are fully typed; `LeaseScopeDeclaration = LeaseScope                         | null` |
+| `fail()` + `ERROR_CODES` for all failures            | ✅     | New `LEASE_SCOPE_CONFLICT` error code added before use                                     |
+| `withFileLock` for all state mutations               | ✅     | Registry writes go inside `withIndexLock` (same mechanism, same lock path)                 |
+| No `console.log` in `apps/control-plane/src/`        | ✅     | Deferral observability uses `console.warn` for SCOPE_CONFLICT logging                      |
+| `no-floating-promises`                               | ✅     | All async calls awaited; no fire-and-forget patterns introduced                            |
+
+**Constitution verdict: PASS — no violations**
+
+---
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/002-scope-aware-lease/
+├── plan.md              ← this file
+├── research.md          ← Phase 0 output
+├── data-model.md        ← Phase 1 output
+├── contracts/
+│   └── lease-registry.schema.json   ← JSON Schema for lease-registry.json
+└── quickstart.md        ← Phase 1 output
+```
+
+### Source Code — affected paths
+
+```text
+apps/control-plane/src/
+├── core/
+│   ├── runtime-sessions.ts          ← ADD LeaseScope, LeaseScopeDeclaration, ActiveLeaseRecord, LeaseRegistry types
+│   ├── error-codes.ts               ← ADD LEASE_SCOPE_CONFLICT
+│   └── path-layout.ts               ← ADD leaseRegistryPath getter
+├── application/
+│   └── services/
+│       ├── lease-scope-conflict-detector.ts   ← NEW pure logic service
+│       └── run-lease-service.ts               ← MODIFY scope conflict integration
+└── supervisor/
+    ├── run-coordinator.ts           ← MODIFY pass scope on acquireRunLease
+    └── types.ts                     ← MODIFY add scope to FeatureInput
+
+apps/control-plane/test/
+├── lease-scope-conflict-detector.spec.ts   ← NEW — primary test surface
+└── run-lease-service.spec.ts               ← NEW — integration coverage for scope paths
+```
+
+**Structure Decision**: Single-app Nx monorepo. All changes are inside `apps/control-plane/`. No new packages. New `LeaseScopeConflictDetector` is a plain service class (no framework, no DI wrapper) — pure input/output with zero side effects, consistent with the existing pattern in e.g. `gate-selection-service.ts`.
+
+---
+
+## Complexity Tracking
+
+No constitution violations. No complexity justifications needed.
+
+---
+
+## Phase 0: Research
+
+### R-001 — Scope overlap: path-prefix semantics
+
+**Decision**: Use normalized path strings with a trailing-slash normalization rule. A path `a` overlaps path `b` if and only if `normalize(a)` is a prefix of `normalize(b)` or vice versa.
+
+**Normalization rule**:
+
+- Strip any trailing slash from the raw input, then re-append exactly one `/` before prefix comparison.
+- This ensures `packages/auth` and `packages/authentication` do NOT overlap (the former only overlaps `packages/auth/…`).
+- Empty string after strip → treated as root `/` → overlaps everything.
+
+**Rationale**: Spec FR-003 requires "path-prefix containment." Trailing-slash normalization is the standard way to avoid false positives (e.g., `src/` vs `src-old/`). The spec calls out this edge case explicitly under "Partially overlapping nested paths."
+
+**Alternatives considered**:
+
+- Glob pattern matching — rejected; adds complexity, spec only requires prefix containment.
+- `path.relative()` — rejected; cross-platform normalization issues on Windows are irrelevant for a Linux/macOS CLI, but the trailing-slash approach is simpler and portable.
+
+---
+
+### R-002 — Plan section ID overlap semantics
+
+**Decision**: Two plan section IDs overlap if and only if they are **equal** (case-sensitive string equality). No hierarchical relationship between section IDs.
+
+**Rationale**: Spec Assumptions: "Plan section identifiers used as scope entries are treated as opaque strings; two identifiers overlap only if they are equal (no hierarchical relationship between plan sections)."
+
+---
+
+### R-003 — Empty scope vs. unknown (null) scope
+
+**Decision**:
+
+- `null` → unknown scope → conflicts with **all** active leases (conservative fallback, FR-004).
+- `{ paths: [], plan_section_ids: [] }` → explicitly empty → conflicts with **no** active leases.
+- `undefined` (field absent) → normalized to `null` at port boundary.
+
+**Rationale**: The spec edge case "Empty scope list vs. no scope declared" explicitly calls for this distinction. An empty list means "touches nothing" (safe to proceed). Absent/null means "unknown" (must block).
+
+---
+
+### R-004 — Lease Registry architecture
+
+**Decision**: A single shared file `.aop/runtime/lease-registry.json` containing `{ leases: ActiveLeaseRecord[] }`, protected by the **existing index lock** (`withIndexLock` / `.aop/features/.index.lock`). Per-instance lease files (`.aop/runtime/<instanceId>/run-lease.json`) are retained for per-instance session metadata (heartbeat tracking, session IDs, etc.) and are written atomically inside the same lock callback.
+
+**Rationale**:
+
+- Avoids introducing a second lock level, which could cause priority inversion.
+- The index lock is already the single serialization point for all lease operations (`acquireRunLease`, `renewRunLease`, `releaseRunLease`).
+- Registry entries are pruned on every read (expired leases removed), preventing stale-entry accumulation.
+- Single-digit concurrent runs → no performance concern.
+
+**Alternatives considered**:
+
+- Dedicated registry lock (`.aop/runtime/.lease-registry.lock`) — rejected; adds a second lock primitive, same critical section, more complexity for no benefit.
+- Storing all active leases inside `index.json` under `active_leases[]` — rejected; `index.json` is the feature index and mixing lease registry into it violates SRP; dedicated file is cleaner.
+
+---
+
+### R-005 — Scope expansion (FR-007)
+
+**Decision**: Add `expandRunLeaseScope(runId, ownerInstanceId, additionalScope)` to `RunLeaseService` and expose it as a direct kernel method. The supervisor calls this after the planning wave populates `plan.json` with the file manifest. Expansion is **additive** — existing paths are merged with new ones; no paths are removed. Pending lease requests that were blocked on this run are NOT automatically re-evaluated; they will be re-evaluated on their next acquisition retry (retryable flow).
+
+**Rationale**: The spec says scope expansion is "an infrequent operation." Making it advisory (retry-driven re-evaluation) avoids a complex push-based notification mechanism. The `LeaseHeartbeatService` already renews on every iteration; blocked runs retry on their next iteration naturally.
+
+---
+
+### R-006 — Stale lease takeover and scope replacement (FR-008)
+
+**Decision**: When a stale lease is taken over (`takeover_stale_run: true`), the expired entry in the Lease Registry is removed and the new acquisition's scope is used. This is identical to a release + re-acquire from the registry's perspective.
+
+**Rationale**: Spec FR-008: "When a stale lease is taken over, the system MUST replace the expired scope with the new orchestrator's declared scope before evaluating conflicts." The simplest implementation is: prune expired leases from the registry on every read, then add the new entry. The takeover just sets `takeover_stale_run: true` which bypasses the stale-check on the per-instance file; from the registry perspective, the expired entry is already pruned.
+
+---
+
+### R-007 — Observable deferral record (FR-010)
+
+**Decision**: When a lease acquisition is deferred due to scope conflict, the `LEASE_SCOPE_CONFLICT` error response includes `blocking_run_id`, `blocking_owner_instance_id`, and `conflicting_scope_entry` in its `details` object. Additionally, `console.warn` is emitted from `RunLeaseService` to satisfy the "log entry" requirement. This is `console.warn` (not `console.log`), which is permitted in `apps/control-plane/src/`.
+
+---
+
+## Phase 1: Design & Contracts
+
+### 1.1 Data Model
+
+See [`data-model.md`](./data-model.md) for the full entity schema. Summary:
+
+#### `LeaseScope` (new)
+
+```typescript
+// apps/control-plane/src/core/runtime-sessions.ts (additions)
+
+/**
+ * The declared set of codebase sections a run expects to touch.
+ * paths: file-system paths relative to repoRoot (prefix-matched)
+ * plan_section_ids: opaque plan section identifiers (equality-matched)
+ */
+export interface LeaseScope {
+  paths: string[];
+  plan_section_ids: string[];
+}
+
+/**
+ * null  → unknown/undeclared scope → conservative: conflicts with all active leases
+ * LeaseScope with empty arrays → explicitly empty → conflicts with nothing
+ * LeaseScope with entries → checked via prefix overlap / equality
+ */
+export type LeaseScopeDeclaration = LeaseScope | null;
+```
+
+#### `ActiveLeaseRecord` (new)
+
+```typescript
+/** One entry in the global Lease Registry. */
+export interface ActiveLeaseRecord {
+  run_id: string;
+  owner_instance_id: string;
+  instance_id: string; // kernel instanceId (for registry→lease-file correlation)
+  scope: LeaseScopeDeclaration; // null if undeclared
+  lease_expires_at: string; // ISO-8601; used for stale pruning
+  acquired_at: string; // ISO-8601
+}
+
+export interface LeaseRegistry {
+  leases: ActiveLeaseRecord[];
+  updated_at: string; // ISO-8601; last registry write timestamp
+}
+```
+
+#### `RuntimeSessionsSnapshot` (modified)
+
+```typescript
+// Existing interface — ADD one optional field:
+export interface RuntimeSessionsSnapshot {
+  // ... existing fields unchanged ...
+  scope?: LeaseScopeDeclaration; // NEW: persisted scope declaration
+}
+```
+
+#### `AcquireRunLeaseInput` (modified)
+
+```typescript
+export interface AcquireRunLeaseInput {
+  run_id: string;
+  owner_instance_id: string;
+  provider: string;
+  model: string;
+  provider_config_ref_hash: string;
+  takeover_stale_run?: boolean;
+  scope?: LeaseScopeDeclaration; // NEW: declared scope for conflict detection
+}
+```
+
+---
+
+### 1.2 New Error Code
+
+```typescript
+// apps/control-plane/src/core/error-codes.ts (addition)
+LEASE_SCOPE_CONFLICT: 'lease_scope_conflict',
+```
+
+Error payload when thrown from `acquireRunLease`:
+
+```typescript
+fail(
+  ERROR_CODES.LEASE_SCOPE_CONFLICT,
+  `Lease acquisition deferred: scope overlaps with active run ${blockingRunId}`,
+  {
+    incoming_scope: input.scope,
+    blocking_run_id: blockingRunId,
+    blocking_owner_instance_id: blockingOwnerInstanceId,
+    conflicting_scope_entry: firstConflictingEntry,
+    retryable: true, // caller should back off and retry
+    requires_human: false, // automatic — no human intervention needed
+  },
+);
+```
+
+---
+
+### 1.3 `LeaseScopeConflictDetector` (new service — pure logic)
+
+**File**: `apps/control-plane/src/application/services/lease-scope-conflict-detector.ts`
+
+```typescript
+import type { LeaseScopeDeclaration, ActiveLeaseRecord } from '../../core/runtime-sessions.js';
+
+export interface ScopeConflictResult {
+  conflict: boolean;
+  blocking_run_id?: string;
+  blocking_owner_instance_id?: string;
+  conflicting_scope_entry?: string; // the first path/id that caused the conflict
+}
+
+export class LeaseScopeConflictDetector {
+  /**
+   * Checks whether `incoming` scope conflicts with any active lease.
+   * Expired leases must be pruned by the caller before this is invoked.
+   */
+  detectConflict(
+    incoming: LeaseScopeDeclaration,
+    activeLeases: ActiveLeaseRecord[],
+    excludeRunId?: string, // exclude same-owner re-acquisition
+  ): ScopeConflictResult;
+
+  /** Path overlap: true if a is a prefix of b or b is a prefix of a (after normalization). */
+  pathsOverlap(a: string[], b: string[]): boolean;
+
+  /** Plan section overlap: set intersection by equality. */
+  planSectionsOverlap(a: string[], b: string[]): boolean;
+
+  /** Normalize a path for prefix comparison: trim trailing slash, append one slash. */
+  normalizePath(p: string): string;
+}
+```
+
+**Conflict matrix** (implemented in `detectConflict`):
+
+| Incoming \ Active    | `null` (unknown) | empty `{ paths:[], plan_section_ids:[] }` | non-empty             |
+| -------------------- | ---------------- | ----------------------------------------- | --------------------- |
+| **`null` (unknown)** | CONFLICT         | CONFLICT                                  | CONFLICT              |
+| **empty**            | CONFLICT         | no conflict                               | no conflict           |
+| **non-empty**        | CONFLICT         | no conflict                               | check prefix/equality |
+
+---
+
+### 1.4 `RunLeaseServicePort` (modified)
+
+```typescript
+export interface RunLeaseServicePort {
+  // ... existing methods unchanged ...
+
+  // NEW: Registry operations (protected by the same withIndexLock)
+  readLeaseRegistry(): Promise<LeaseRegistry>;
+  writeLeaseRegistry(registry: LeaseRegistry): Promise<void>;
+  emptyLeaseRegistry(at?: string): LeaseRegistry;
+}
+```
+
+---
+
+### 1.5 `RunLeaseService` method changes
+
+#### `acquireRunLease` — modified flow
+
+```
+withIndexLock:
+  1. read per-instance lease file (existing)
+  2. check same-owner re-acquisition (existing)
+  3. check stale takeover (existing)
+  4. read lease registry
+  5. prune expired entries from registry (lease_expires_at < now)
+  6. detectConflict(input.scope, prunedLeases, excludeRunId=input.run_id)
+  7. if conflict → console.warn + throw LEASE_SCOPE_CONFLICT
+  8. grant: write per-instance lease (existing)
+  9. upsert this run's entry in registry (remove old same-run entry, add new)
+  10. write registry
+```
+
+> **Note on interaction with `RUN_ALREADY_ACTIVE`**: The existing `RUN_ALREADY_ACTIVE` check is for per-instance file freshness (same `run_id`/`owner_instance_id`). It runs **before** the registry check. `LEASE_SCOPE_CONFLICT` is a separate, new error code for multi-run scope blocking.
+
+#### `renewRunLease` — modified
+
+Inside `withIndexLock`, after writing the per-instance file, also update the `lease_expires_at` on this run's registry entry:
+
+```
+withIndexLock:
+  1. existing ownership check + per-instance write
+  2. read registry
+  3. prune expired
+  4. update lease_expires_at for this run_id in registry
+  5. write registry
+```
+
+#### `releaseRunLease` — modified
+
+Inside `withIndexLock`, after clearing the per-instance file, also remove this run from the registry:
+
+```
+withIndexLock:
+  1. existing ownership check + per-instance clear
+  2. read registry
+  3. remove entry for this run_id/owner_instance_id
+  4. write registry
+```
+
+#### `expandRunLeaseScope` — new method
+
+```typescript
+async expandRunLeaseScope(input: {
+  run_id: string;
+  owner_instance_id: string;
+  additional_paths?: string[];
+  additional_plan_section_ids?: string[];
+}): Promise<{ data: { scope: LeaseScopeDeclaration } }>
+```
+
+Flow:
+
+```
+withIndexLock:
+  1. verify ownership (per-instance file)
+  2. read current scope from per-instance file
+  3. merge: union(current.paths, additional_paths), union(current.plan_section_ids, additional_plan_section_ids)
+  4. write updated scope to per-instance file
+  5. read registry
+  6. update registry entry's scope for this run_id
+  7. write registry
+  8. return { data: { scope: merged } }
+```
+
+---
+
+### 1.6 `AopPathLayout` additions
+
+```typescript
+// apps/control-plane/src/core/path-layout.ts
+
+get leaseRegistryPath(): string {
+  return path.join(this.runtimeDataRoot, 'lease-registry.json');
+}
+```
+
+> Uses the same `withIndexLock` (`.aop/features/.index.lock`) — no new lock path needed.
+
+---
+
+### 1.7 `AopKernel` additions (port implementation)
+
+```typescript
+// In kernel.ts — add to RunLeaseServicePort implementation:
+
+async readLeaseRegistry(): Promise<LeaseRegistry> {
+  const existing = await readJson(this.pathLayout.leaseRegistryPath, null);
+  return existing ?? this.port.emptyLeaseRegistry();
+}
+
+async writeLeaseRegistry(registry: LeaseRegistry): Promise<void> {
+  await ensureDir(path.dirname(this.pathLayout.leaseRegistryPath));
+  await atomicWriteJson(this.pathLayout.leaseRegistryPath, registry);
+}
+
+emptyLeaseRegistry(at = nowIso()): LeaseRegistry {
+  return { leases: [], updated_at: at };
+}
+
+// New public kernel method:
+async expandRunLeaseScope(input: ExpandRunLeaseScopeInput): Promise<{
+  data: { scope: LeaseScopeDeclaration };
+}> {
+  return await this.runLeaseService.expandRunLeaseScope(input);
+}
+```
+
+---
+
+### 1.8 `RunCoordinator` and `SupervisorRuntime` changes
+
+**`supervisor/types.ts`** — add optional `scope` to `FeatureInput`:
+
+```typescript
+export interface FeatureInput {
+  feature_id: string;
+  spec_file?: string;
+  // NEW:
+  scope?: LeaseScopeDeclaration; // declared scope at launch time; may be null
+}
+```
+
+**`supervisor/run-coordinator.ts`** — `start()` method, lease acquisition:
+
+```typescript
+// Derive aggregate scope across all features being processed in this run.
+// If any feature has no declared scope, the run-level scope is null (conservative).
+const runScope = this.deriveRunScope(features);
+
+const leaseResult = await this.kernel.acquireRunLease({
+  run_id: this.state.runId,
+  owner_instance_id: this.state.ownerInstanceId,
+  provider: this.provider.selection.provider,
+  model: this.provider.selection.model,
+  provider_config_ref_hash: this.providerConfigRefHash(),
+  takeover_stale_run: this.takeoverStaleRun,
+  scope: runScope, // NEW
+});
+```
+
+Add `deriveRunScope(features: FeatureInput[]): LeaseScopeDeclaration`:
+
+```typescript
+private deriveRunScope(features: FeatureInput[]): LeaseScopeDeclaration {
+  if (features.some((f) => f.scope === undefined || f.scope === null)) {
+    return null;  // conservative: any unknown → aggregate is unknown
+  }
+  return {
+    paths: [...new Set(features.flatMap((f) => f.scope!.paths))].sort(),
+    plan_section_ids: [...new Set(features.flatMap((f) => f.scope!.plan_section_ids))].sort(),
+  };
+}
+```
+
+After the planning wave (inside the iteration loop), the supervisor calls `expandRunLeaseScope` with the plan's file manifest. This is the FR-007 hook:
+
+```typescript
+// After planningWaveExecutor.run(activeFeatureIds):
+await this.expandScopesFromPlans(activeFeatureIds);
+```
+
+Where `expandScopesFromPlans` reads each active feature's `plan.json` → extracts `affected_files` → calls `this.kernel.expandRunLeaseScope(...)`.
+
+---
+
+### 1.9 Lease Registry JSON Schema
+
+**File**: `specs/002-scope-aware-lease/contracts/lease-registry.schema.json`
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "LeaseRegistry",
+  "type": "object",
+  "required": ["leases", "updated_at"],
+  "properties": {
+    "leases": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "run_id",
+          "owner_instance_id",
+          "instance_id",
+          "scope",
+          "lease_expires_at",
+          "acquired_at"
+        ],
+        "properties": {
+          "run_id": { "type": "string" },
+          "owner_instance_id": { "type": "string" },
+          "instance_id": { "type": "string" },
+          "lease_expires_at": { "type": "string", "format": "date-time" },
+          "acquired_at": { "type": "string", "format": "date-time" },
+          "scope": {
+            "oneOf": [
+              { "type": "null" },
+              {
+                "type": "object",
+                "required": ["paths", "plan_section_ids"],
+                "properties": {
+                  "paths": { "type": "array", "items": { "type": "string" } },
+                  "plan_section_ids": { "type": "array", "items": { "type": "string" } }
+                }
+              }
+            ]
+          }
+        }
+      }
+    },
+    "updated_at": { "type": "string", "format": "date-time" }
+  }
+}
+```
+
+---
+
+## Test Strategy
+
+All tests live in `apps/control-plane/test/`. Coverage targets: ≥90% lines/branches/functions/statements.
+
+---
+
+### Test File 1: `lease-scope-conflict-detector.spec.ts` (NEW)
+
+**Unit tests — pure logic, no I/O. Full coverage of the conflict matrix.**
+
+#### Block: `LeaseScopeConflictDetector.normalizePath`
+
+| #    | Input               | Expected                        |
+| ---- | ------------------- | ------------------------------- |
+| T-01 | `"packages/auth"`   | `"packages/auth/"`              |
+| T-02 | `"packages/auth/"`  | `"packages/auth/"` (idempotent) |
+| T-03 | `""` (empty string) | `"/"` (treated as root)         |
+| T-04 | `"src/config.ts"`   | `"src/config.ts/"`              |
+
+#### Block: `LeaseScopeConflictDetector.pathsOverlap`
+
+| #    | a                                        | b                                            | Expected                                      |
+| ---- | ---------------------------------------- | -------------------------------------------- | --------------------------------------------- |
+| T-05 | `["packages/auth/"]`                     | `["packages/payments/"]`                     | `false` (Story 1 — non-overlap)               |
+| T-06 | `["packages/auth/"]`                     | `["packages/auth/"]`                         | `true` (exact match)                          |
+| T-07 | `["packages/"]`                          | `["packages/auth/"]`                         | `true` (parent contains child — Story 2 AC2)  |
+| T-08 | `["packages/auth/"]`                     | `["packages/"]`                              | `true` (symmetric)                            |
+| T-09 | `["src/"]`                               | `["src/config.ts"]`                          | `true` (file within dir scope — Edge case)    |
+| T-10 | `["src/"]`                               | `["src-old/config.ts"]`                      | `false` (no false positive on similar prefix) |
+| T-11 | `["packages/auth/", "packages/shared/"]` | `["packages/shared/", "packages/payments/"]` | `true` (partial overlap — Story 2 AC3)        |
+| T-12 | `[]`                                     | `["packages/auth/"]`                         | `false` (empty set → no overlap)              |
+| T-13 | `[]`                                     | `[]`                                         | `false`                                       |
+
+#### Block: `LeaseScopeConflictDetector.planSectionsOverlap`
+
+| #    | a                            | b                            | Expected |
+| ---- | ---------------------------- | ---------------------------- | -------- |
+| T-14 | `["section-A"]`              | `["section-B"]`              | `false`  |
+| T-15 | `["section-A"]`              | `["section-A"]`              | `true`   |
+| T-16 | `["section-A", "section-B"]` | `["section-B", "section-C"]` | `true`   |
+| T-17 | `[]`                         | `["section-A"]`              | `false`  |
+
+#### Block: `LeaseScopeConflictDetector.detectConflict` — conflict matrix
+
+| #    | incoming                                            | active lease scope                                         | Expected                                                     |
+| ---- | --------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------ |
+| T-18 | `null`                                              | any active lease (non-empty scope)                         | `{ conflict: true }` — Story 3 AC1                           |
+| T-19 | `null`                                              | no active leases                                           | `{ conflict: false }` — Story 3 AC3                          |
+| T-20 | non-empty scope                                     | active with `null` scope                                   | `{ conflict: true }` — Story 3 AC2                           |
+| T-21 | empty `{ paths:[], plan_section_ids:[] }`           | any active lease                                           | `{ conflict: false }`                                        |
+| T-22 | `{ paths:["packages/auth/"], plan_section_ids:[] }` | active `{ paths:["packages/payments/"], ... }`             | `{ conflict: false }` — Story 1 AC2                          |
+| T-23 | `{ paths:["packages/auth/"], plan_section_ids:[] }` | active `{ paths:["packages/auth/"], ... }`                 | `{ conflict: true, blocking_run_id: "run-A" }` — Story 2 AC1 |
+| T-24 | `{ paths:["packages/auth/utils/"], ... }`           | active `{ paths:["packages/"], ... }`                      | `{ conflict: true }` — Spec edge case: nested path           |
+| T-25 | `{ paths:[], plan_section_ids:["plan-section-1"] }` | active `{ paths:[], plan_section_ids:["plan-section-1"] }` | `{ conflict: true }`                                         |
+| T-26 | excludeRunId matches the only conflicting lease     | (same run re-acquire)                                      | `{ conflict: false }` (excluded)                             |
+
+---
+
+### Test File 2: `run-lease-service.spec.ts` (NEW)
+
+**Integration tests for `RunLeaseService` with a mock `RunLeaseServicePort` that stubs registry I/O.**
+
+#### Block: Scope declaration persisted (Story 4)
+
+| #    | Scenario                                                                  | Expected                                                      |
+| ---- | ------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| T-30 | Acquire with `scope: { paths: ["packages/auth/"], plan_section_ids: [] }` | Lease record written to per-instance file contains that scope |
+| T-31 | Acquire with `scope: null`                                                | Lease record contains `scope: null`                           |
+| T-32 | Acquire with no `scope` field provided                                    | Normalized to `scope: null` (conservative)                    |
+| T-33 | Acquire, read back registry entry                                         | `ActiveLeaseRecord.scope` matches input                       |
+
+#### Block: Parallel non-overlapping runs (Story 1)
+
+| #    | Scenario                                                                         | Expected                                                     |
+| ---- | -------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| T-34 | Registry contains Run A (`packages/auth/`), acquire Run B (`packages/payments/`) | Returns lease granted; registry has 2 entries                |
+| T-35 | Both Run A and Run B active; both release independently                          | After each release, registry entry removed; other unaffected |
+
+#### Block: Overlapping runs blocked (Story 2)
+
+| #    | Scenario                                                                  | Expected                                                              |
+| ---- | ------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| T-36 | Run A holds `packages/auth/`; Run B attempts `packages/auth/`             | Throws `LEASE_SCOPE_CONFLICT` with `blocking_run_id = Run A's run_id` |
+| T-37 | Run A holds `packages/` (parent); Run B attempts `packages/auth/` (child) | Throws `LEASE_SCOPE_CONFLICT`                                         |
+| T-38 | Run A holds `null` scope; Run B attempts any non-empty scope              | Throws `LEASE_SCOPE_CONFLICT`                                         |
+
+#### Block: Conservative fallback (Story 3)
+
+| #    | Scenario                                                   | Expected                      |
+| ---- | ---------------------------------------------------------- | ----------------------------- |
+| T-39 | Any active lease exists; Run B requests with `scope: null` | Throws `LEASE_SCOPE_CONFLICT` |
+| T-40 | No active leases; Run A requests with `scope: null`        | Granted immediately           |
+
+#### Block: Stale lease takeover + scope replacement (FR-008)
+
+| #    | Scenario                                                                                                                         | Expected                                                                       |
+| ---- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| T-41 | Registry has expired entry for Run A (scope `packages/auth/`); new run acquires `packages/auth/` with `takeover_stale_run: true` | Old entry pruned; new entry inserted with new scope; no `LEASE_SCOPE_CONFLICT` |
+| T-42 | `takeover_stale_run: false` with stale conflicting lease                                                                         | Throws `RUN_ALREADY_ACTIVE` (existing behavior preserved)                      |
+
+#### Block: `expandRunLeaseScope` (FR-007)
+
+| #    | Scenario                                                                               | Expected                                                           |
+| ---- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| T-43 | Run A holds `packages/auth/`; expands to add `packages/shared/`                        | Registry entry updated to `["packages/auth/", "packages/shared/"]` |
+| T-44 | Run B (pending) was blocked on non-overlapping scope; Run A expands into Run B's scope | On Run B's next retry, `LEASE_SCOPE_CONFLICT` is returned          |
+| T-45 | `expandRunLeaseScope` called by non-owner                                              | Throws `RUN_LEASE_NOT_OWNED`                                       |
+
+#### Block: `renewRunLease` updates registry TTL
+
+| #    | Scenario                                                                       | Expected                           |
+| ---- | ------------------------------------------------------------------------------ | ---------------------------------- |
+| T-46 | Run A renews; registry entry `lease_expires_at` is updated                     | New `lease_expires_at` > old value |
+| T-47 | Renew for non-owner → `RUN_LEASE_NOT_OWNED` (existing behavior, no regression) |
+
+#### Block: `releaseRunLease` removes from registry
+
+| #    | Scenario                                                                       | Expected                       |
+| ---- | ------------------------------------------------------------------------------ | ------------------------------ |
+| T-48 | Run A releases; registry entry removed                                         | `registry.leases.length === 0` |
+| T-49 | Release for wrong owner → `released: false` (existing behavior, no regression) |
+
+---
+
+### Existing test file updates
+
+| File                                              | Change                                                                                                                                                                    |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `apps/control-plane/test/run-coordinator.spec.ts` | Add test: `acquireRunLease` called with `scope: null` when no feature scopes declared; add test: `acquireRunLease` called with derived scope when all features have scope |
+| `apps/control-plane/test/supervisor.spec.ts`      | Add assertion: `kernel.acquireRunLease` receives `scope` field; `LEASE_SCOPE_CONFLICT` is propagated without masking                                                      |
+| `apps/control-plane/test/kernel.spec.ts`          | Add test: `readLeaseRegistry` returns empty registry on missing file; `writeLeaseRegistry` round-trips correctly                                                          |
+
+---
+
+## File-Level Change Map
+
+| File                                                                           | Type   | Change Summary                                                                                                                                                                                                                                    |
+| ------------------------------------------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `apps/control-plane/src/core/runtime-sessions.ts`                              | MODIFY | Add `LeaseScope`, `LeaseScopeDeclaration`, `ActiveLeaseRecord`, `LeaseRegistry` types; add `scope?: LeaseScopeDeclaration` to `RuntimeSessionsSnapshot`                                                                                           |
+| `apps/control-plane/src/core/error-codes.ts`                                   | MODIFY | Add `LEASE_SCOPE_CONFLICT: 'lease_scope_conflict'`                                                                                                                                                                                                |
+| `apps/control-plane/src/core/path-layout.ts`                                   | MODIFY | Add `get leaseRegistryPath(): string`                                                                                                                                                                                                             |
+| `apps/control-plane/src/application/services/lease-scope-conflict-detector.ts` | CREATE | Pure `LeaseScopeConflictDetector` class: `normalizePath`, `pathsOverlap`, `planSectionsOverlap`, `detectConflict`                                                                                                                                 |
+| `apps/control-plane/src/application/services/run-lease-service.ts`             | MODIFY | `AcquireRunLeaseInput` gains `scope?`; `acquireRunLease`, `renewRunLease`, `releaseRunLease` extended to maintain registry; new `expandRunLeaseScope`; `RunLeaseServicePort` gets `readLeaseRegistry`, `writeLeaseRegistry`, `emptyLeaseRegistry` |
+| `apps/control-plane/src/core/kernel.ts`                                        | MODIFY | Implement `readLeaseRegistry`, `writeLeaseRegistry`, `emptyLeaseRegistry` on `RunLeaseServicePort`; add `expandRunLeaseScope` public method                                                                                                       |
+| `apps/control-plane/src/supervisor/types.ts`                                   | MODIFY | Add `scope?: LeaseScopeDeclaration` to `FeatureInput`                                                                                                                                                                                             |
+| `apps/control-plane/src/supervisor/run-coordinator.ts`                         | MODIFY | Add `deriveRunScope()`; pass `scope` to `acquireRunLease`; add `expandScopesFromPlans()` called after planning wave                                                                                                                               |
+| `apps/control-plane/test/lease-scope-conflict-detector.spec.ts`                | CREATE | 26 unit tests for pure conflict-detection logic (T-01 → T-26)                                                                                                                                                                                     |
+| `apps/control-plane/test/run-lease-service.spec.ts`                            | CREATE | 20 integration tests for `RunLeaseService` scope paths (T-30 → T-49)                                                                                                                                                                              |
+| `apps/control-plane/test/run-coordinator.spec.ts`                              | MODIFY | 2 tests for scope derivation and propagation                                                                                                                                                                                                      |
+| `apps/control-plane/test/supervisor.spec.ts`                                   | MODIFY | 1 test: `LEASE_SCOPE_CONFLICT` propagation                                                                                                                                                                                                        |
+| `apps/control-plane/test/kernel.spec.ts`                                       | MODIFY | 2 tests: `readLeaseRegistry` / `writeLeaseRegistry` round-trip                                                                                                                                                                                    |
+| `specs/002-scope-aware-lease/contracts/lease-registry.schema.json`             | CREATE | JSON Schema for `LeaseRegistry` runtime artifact                                                                                                                                                                                                  |
+| `specs/002-scope-aware-lease/data-model.md`                                    | CREATE | Full entity descriptions and field invariants                                                                                                                                                                                                     |
+| `specs/002-scope-aware-lease/research.md`                                      | CREATE | Research decisions R-001 → R-007 (formalized version)                                                                                                                                                                                             |
+| `specs/002-scope-aware-lease/quickstart.md`                                    | CREATE | How to use scope-aware leases from CLI and programmatically                                                                                                                                                                                       |
+| `docs/core/DOMAIN-LOGIC.md`                                                    | MODIFY | Add Rule 19: lease scope semantics (null vs empty, prefix overlap, registry lifecycle)                                                                                                                                                            |
+| `docs/core/DECISIONS.md`                                                       | MODIFY | Add ADR: Scope-Aware Lease Registry (global registry file vs. distributed lease files)                                                                                                                                                            |
+| `spec-files/progress.md`                                                       | MODIFY | New entry after implementation                                                                                                                                                                                                                    |
+
+---
+
+## ADR: Scope-Aware Lease Registry
+
+**Context**: The current global run lease prevents parallel orchestration of non-overlapping codebase regions. We need scope-aware conflict detection without introducing complex distributed coordination.
+
+**Decision**: A single shared file (`.aop/runtime/lease-registry.json`) protected by the existing index atomic lock, containing all active lease records with their declared scopes.
+
+**Reasoning**:
+
+- **Pro**: Piggybacks on the existing `withIndexLock` serialization — no new lock primitives, no priority-inversion risk.
+- **Pro**: Registry is simple JSON; inspectable, git-snapshotable, debuggable without tooling.
+- **Pro**: Expired-entry pruning on every read prevents stale-entry accumulation without a background GC process.
+- **Con**: All lease operations hold the index lock slightly longer (read registry + write registry added to each operation). Acceptable: lock hold time increases by a small constant; registry is tiny.
+- **Alternative Considered**: Per-instance lease files only — rejected because there's no shared structure to enumerate all active leases for cross-instance conflict detection.
+- **Alternative Considered**: `index.json` `active_leases[]` array — rejected; mixes feature index concerns with lease registry concerns (SRP violation).
+
+**Consequences**:
+
+- ✅ Two non-overlapping runs can hold leases simultaneously.
+- ✅ Overlapping runs are serialized with a clear, observable error code.
+- ✅ Lease registry survives process crashes (file-based) and is self-healing (prune-on-read).
+- ⚠️ Index lock hold time slightly increased. Negligible at single-digit concurrency.
+
+**Status**: Proposed
+
+---
+
+## Definition of Done
+
+- [ ] `npm run typecheck` passes clean (no new type errors)
+- [ ] `npm run lint` passes with zero warnings
+- [ ] `npm run test` passes at ≥90% lines/branches/functions/statements
+- [ ] `lease-scope-conflict-detector.spec.ts` — all T-01 → T-26 tests pass
+- [ ] `run-lease-service.spec.ts` — all T-30 → T-49 tests pass
+- [ ] Existing `run-coordinator.spec.ts`, `supervisor.spec.ts`, `kernel.spec.ts` updated and passing
+- [ ] `specs/002-scope-aware-lease/contracts/lease-registry.schema.json` created
+- [ ] `DOMAIN-LOGIC.md` updated with Rule 19
+- [ ] `DECISIONS.md` updated with Scope-Aware Lease Registry ADR
+- [ ] `spec-files/progress.md` updated with new numbered entry