agentic-orchestrator 0.1.28 → 0.2.1

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

@@ -0,0 +1,767 @@
+# Tasks: Scope-Aware Run Lease
+
+**Feature**: `002-scope-aware-lease`  
+**Input**: `specs/002-scope-aware-lease/` — `spec.md`, `plan.md`, `research.md`, `data-model.md`, `contracts/lease-registry.schema.json`  
+**Branch**: `002-scope-aware-lease`
+
+---
+
+## Format: `[ID] [P?] [Story?] Description — file path`
+
+- **[P]**: Parallelizable with the immediately preceding task (different files, no data dependency between them)
+- **[US?]**: User story this task primarily delivers (`US1`–`US4`)
+- Ordering: **dependency-first** — foundation → services → integration → tests → docs
+
+## User Stories (from spec.md)
+
+| ID  | Title                                          | Priority |
+| --- | ---------------------------------------------- | -------- |
+| US1 | Parallel execution of non-overlapping runs     | P1       |
+| US2 | Blocking of overlapping runs                   | P1       |
+| US3 | Conservative fallback for unknown scope        | P2       |
+| US4 | Scope declaration & persistence at acquisition | P2       |
+
+---
+
+## Phase 1: Setup — Core Types & Infrastructure
+
+**Purpose**: Add the three pure foundational additions (types, error code, path constant) that every other task in this feature depends on. None touch business logic; all can be verified with `npm run typecheck`.
+
+**⚠️ All Phase 2–6 work is blocked until T001 is complete.**
+
+- [ ] T001 Add `LeaseScope`, `LeaseScopeDeclaration`, `ActiveLeaseRecord`, and `LeaseRegistry` types to `apps/control-plane/src/core/runtime-sessions.ts`
+
+  > **Exact additions** (insert after the last existing `export interface` in the file):
+  >
+  > ```typescript
+  > export interface LeaseScope {
+  >   paths: string[];
+  >   plan_section_ids: string[];
+  > }
+  > export type LeaseScopeDeclaration = LeaseScope | null;
+  > export interface ActiveLeaseRecord {
+  >   run_id: string;
+  >   owner_instance_id: string;
+  >   instance_id: string;
+  >   scope: LeaseScopeDeclaration;
+  >   lease_expires_at: string;
+  >   acquired_at: string;
+  > }
+  > export interface LeaseRegistry {
+  >   leases: ActiveLeaseRecord[];
+  >   updated_at: string;
+  > }
+  > ```
+  >
+  > **Invariants** (from data-model.md): `paths` are relative repo-root paths; `plan_section_ids` are opaque strings (no hierarchy). Both arrays may be empty. `null` means unknown/undeclared scope.
+
+- [ ] T002 [P] Add `LEASE_SCOPE_CONFLICT: 'lease_scope_conflict'` to `apps/control-plane/src/core/error-codes.ts`
+
+  > Locate the `ERROR_CODES` const object. Insert immediately after `RUN_LEASE_NOT_OWNED`:
+  >
+  > ```typescript
+  > LEASE_SCOPE_CONFLICT: 'lease_scope_conflict',
+  > ```
+  >
+  > No other changes. Verify with `npm run typecheck`.
+
+- [ ] T003 [P] Add `leaseRegistryPath` getter to `apps/control-plane/src/core/path-layout.ts`
+
+  > Add after the existing `runLeasePath(instanceId)` method:
+  >
+  > ```typescript
+  > get leaseRegistryPath(): string {
+  >   return path.join(this.runtimeDataRoot, 'lease-registry.json');
+  > }
+  > ```
+  >
+  > No new lock path needed — the registry uses the existing index lock (`.aop/features/.index.lock`).
+
+**Checkpoint**: `npm run typecheck` passes clean. All new types compile; error code resolves; getter exists.
+
+---
+
+## Phase 2: Foundational — Pure Scope Conflict Detection Service
+
+**Purpose**: Implement the core conflict-detection logic as a **pure, side-effect-free class** (no file I/O, no async). This is a standalone service extracted from `RunLeaseService` for testability and SRP compliance (per plan §1.3 and research R-001/R-002/R-003). All user stories depend on this logic.
+
+- [ ] T004 Create `apps/control-plane/src/application/services/lease-scope-conflict-detector.ts` — pure `LeaseScopeConflictDetector` class with `normalizePath`, `pathsOverlap`, `planSectionsOverlap`, and `detectConflict`
+
+  > **File skeleton** (all imports use `import type`):
+  >
+  > ```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;
+  > }
+  >
+  > export class LeaseScopeConflictDetector {
+  >   normalizePath(p: string): string { ... }
+  >   pathsOverlap(a: string[], b: string[]): boolean { ... }
+  >   planSectionsOverlap(a: string[], b: string[]): boolean { ... }
+  >   detectConflict(
+  >     incoming: LeaseScopeDeclaration,
+  >     activeLeases: ActiveLeaseRecord[],
+  >     excludeRunId?: string,
+  >   ): ScopeConflictResult { ... }
+  > }
+  > ```
+  >
+  > **`normalizePath(p)`** (R-001): Strip all trailing `/`, then append exactly one `/`. If the result after stripping is `''`, return `'/'` (root — overlaps everything).  
+  > **`pathsOverlap(a, b)`**: Normalize every entry in both arrays. Return `true` if any `na` in `a` is a prefix of any `nb` in `b`, or any `nb` is a prefix of `na` (symmetric). Empty arrays produce no overlap.  
+  > **`planSectionsOverlap(a, b)`** (R-002): Return `true` iff the set intersection of `a` and `b` is non-empty (exact case-sensitive string equality; no hierarchy).  
+  > **`detectConflict` conflict matrix** (from data-model.md § State Transitions):
+  >
+  > | `incoming`                          | active `scope`                      | Result                                          |
+  > | ----------------------------------- | ----------------------------------- | ----------------------------------------------- |
+  > | `null`                              | anything (any lease exists)         | `{ conflict: true }`                            |
+  > | any value                           | `null`                              | `{ conflict: true }`                            |
+  > | `{ paths:[], plan_section_ids:[] }` | any                                 | `{ conflict: false }`                           |
+  > | non-empty                           | `{ paths:[], plan_section_ids:[] }` | `{ conflict: false }`                           |
+  > | non-empty                           | non-empty                           | check `pathsOverlap` then `planSectionsOverlap` |
+  >
+  > `excludeRunId`: skip any `activeLease` where `activeLease.run_id === excludeRunId` (prevents same-run re-acquisition false positives).  
+  > Return the **first** conflicting lease's `blocking_run_id`, `blocking_owner_instance_id`, and `conflicting_scope_entry` (the specific path or plan_section_id that triggered the conflict).  
+  > No `any` types. No `console.*`. No imports other than the type import above.
+
+**Checkpoint**: File compiles. Class can be instantiated with `new LeaseScopeConflictDetector()` and all four methods are callable.
+
+---
+
+## Phase 3: US4 — Scope Declaration & Persistence (P2)
+
+**Goal**: Capture and persist the declared scope so it survives heartbeat renewals and instance restarts. This is the data-capture prerequisite for US1–US3.
+
+**Independent Test**: Acquire a lease with a specific `scope`, read back the lease record and registry entry, verify the scope is preserved exactly.
+
+- [ ] T005 [US4] Add `scope?: LeaseScopeDeclaration` to `RuntimeSessionsSnapshot` in `apps/control-plane/src/core/runtime-sessions.ts`
+
+  > Locate the `RuntimeSessionsSnapshot` interface. Add at the end (before the closing `}`):
+  >
+  > ```typescript
+  > scope?: LeaseScopeDeclaration;  // NEW: declared scope; undefined normalizes to null on read
+  > ```
+  >
+  > **Backward compatibility**: Field is optional. Existing persisted `.aop/runtime/<instanceId>/run-lease.json` files without this field deserialize with `scope: undefined` — treated as `null` (conservative) at the service boundary.
+
+- [ ] T006 [P] [US4] Add `scope?: LeaseScopeDeclaration` to `AcquireRunLeaseInput` and add `ExpandRunLeaseScopeInput` interface in `apps/control-plane/src/application/services/run-lease-service.ts`
+
+  > **Two additions to `run-lease-service.ts`**:
+  >
+  > 1. In `AcquireRunLeaseInput`, append:
+  >    ```typescript
+  >    scope?: LeaseScopeDeclaration;  // undefined normalizes to null (conservative)
+  >    ```
+  > 2. Export a new interface after `AcquireRunLeaseInput`:
+  >    ```typescript
+  >    export interface ExpandRunLeaseScopeInput {
+  >      run_id: string;
+  >      owner_instance_id: string;
+  >      additional_paths?: string[];
+  >      additional_plan_section_ids?: string[];
+  >    }
+  >    ```
+  >
+  > Both interfaces must use `import type { LeaseScopeDeclaration }` from `../../core/runtime-sessions.js`. Do not modify any method implementations in this task.
+
+**Checkpoint**: `npm run typecheck` passes. `AcquireRunLeaseInput.scope` and `ExpandRunLeaseScopeInput` are exported and reachable.
+
+---
+
+## Phase 4: US1 & US2 — Registry-Backed Lease Operations (P1)
+
+**Goal — US1**: Two runs with non-overlapping scopes both receive leases simultaneously with no artificial serialization.  
+**Goal — US2**: Two runs with overlapping scopes are serialized — the second is denied with `LEASE_SCOPE_CONFLICT` until the first releases.
+
+**Independent Test**: Launch two runs with `packages/auth/` vs `packages/payments/` → both active simultaneously (US1). Launch two runs with identical scope → second throws `LEASE_SCOPE_CONFLICT` (US2).
+
+- [ ] T007 [US1] [US2] Extend `RunLeaseServicePort` interface with registry methods in `apps/control-plane/src/application/services/run-lease-service.ts`
+
+  > Add three method signatures to `RunLeaseServicePort` (the port/interface the kernel implements):
+  >
+  > ```typescript
+  > readLeaseRegistry(): Promise<LeaseRegistry>;
+  > writeLeaseRegistry(registry: LeaseRegistry): Promise<void>;
+  > emptyLeaseRegistry(at?: string): LeaseRegistry;
+  > ```
+  >
+  > Add `import type { ..., LeaseRegistry }` to the existing import from `../../core/runtime-sessions.js`. These are abstract operations — no implementation here; the concrete implementation goes in T011 (kernel).
+
+- [ ] T008 [US1] [US2] Modify `acquireRunLease` in `apps/control-plane/src/application/services/run-lease-service.ts` to integrate scope conflict detection
+
+  > **Extend the existing `withIndexLock` callback** inside `acquireRunLease`. After the existing stale-takeover check and before writing the per-instance lease file, insert:
+  >
+  > ```
+  > Step 4: const rawRegistry = await this.port.readLeaseRegistry();
+  > Step 5: const now = new Date();
+  >          const prunedLeases = rawRegistry.leases.filter(
+  >            (l) => new Date(l.lease_expires_at) > now,
+  >          );
+  > Step 6: const result = this.conflictDetector.detectConflict(
+  >            input.scope ?? null,          // normalize undefined → null
+  >            prunedLeases,
+  >            input.run_id,                 // exclude same-run re-acquisition
+  >          );
+  > Step 7: if (result.conflict) {
+  >            console.warn(
+  >              `[run-lease] scope conflict: run ${input.run_id} blocked by ` +
+  >              `${result.blocking_run_id} on ${result.conflicting_scope_entry}`,
+  >            );
+  >            return fail(
+  >              ERROR_CODES.LEASE_SCOPE_CONFLICT,
+  >              `Lease acquisition deferred: scope overlaps with active run ${result.blocking_run_id}`,
+  >              {
+  >                incoming_scope: input.scope ?? null,
+  >                blocking_run_id: result.blocking_run_id,
+  >                blocking_owner_instance_id: result.blocking_owner_instance_id,
+  >                conflicting_scope_entry: result.conflicting_scope_entry,
+  >                retryable: true,
+  >                requires_human: false,
+  >              },
+  >            );
+  >          }
+  > ```
+  >
+  > Then **after** writing the per-instance lease file (existing step 8):
+  >
+  > ```
+  > Step 9: const newEntry: ActiveLeaseRecord = {
+  >            run_id: input.run_id,
+  >            owner_instance_id: input.owner_instance_id,
+  >            instance_id: this.instanceId,  // from kernel/service config
+  >            scope: input.scope ?? null,
+  >            lease_expires_at: leaseExpiresAt,   // same value written to per-instance file
+  >            acquired_at: nowIso(),
+  >          };
+  >          const updatedLeases = [
+  >            ...prunedLeases.filter(
+  >              (l) => !(l.run_id === input.run_id && l.owner_instance_id === input.owner_instance_id),
+  >            ),
+  >            newEntry,
+  >          ];
+  >          await this.port.writeLeaseRegistry({ leases: updatedLeases, updated_at: nowIso() });
+  > ```
+  >
+  > **Constructor change**: Inject `LeaseScopeConflictDetector` as a constructor parameter (or instantiate inline as `new LeaseScopeConflictDetector()` — it has no dependencies). The conflict detector is a pure class with no I/O; instantiating it inline is acceptable per KISS (R-001).
+  >
+  > Also persist `scope` to the per-instance file: set `snapshot.scope = input.scope ?? null` before calling `atomicWriteJson`.
+  >
+  > **Imports needed**: `ActiveLeaseRecord`, `LeaseScopeDeclaration`, `LeaseRegistry` from `../../core/runtime-sessions.js`; `ERROR_CODES` from `../../core/error-codes.js`; `LeaseScopeConflictDetector` from `./lease-scope-conflict-detector.js`.  
+  > No `any`. `fail()` pattern only — never `new Error(...)`.
+
+- [ ] T009 [US2] Modify `releaseRunLease` in `apps/control-plane/src/application/services/run-lease-service.ts` to remove the entry from the registry
+
+  > **Inside the existing `withIndexLock` callback**, after the existing ownership check and per-instance file clear, append:
+  >
+  > ```typescript
+  > const registry = await this.port.readLeaseRegistry();
+  > const pruned = registry.leases.filter(
+  >   (l) => !(l.run_id === input.run_id && l.owner_instance_id === input.owner_instance_id),
+  > );
+  > await this.port.writeLeaseRegistry({ leases: pruned, updated_at: nowIso() });
+  > ```
+  >
+  > If the entry is absent (already pruned), the filter is a no-op — no error. Existing `released: false` paths (wrong owner) must NOT touch the registry.
+
+- [ ] T010 [P] [US1] Modify `renewRunLease` in `apps/control-plane/src/application/services/run-lease-service.ts` to update `lease_expires_at` in the registry
+
+  > **Inside the existing `withIndexLock` callback**, after writing the per-instance file, append:
+  >
+  > ```typescript
+  > const registry = await this.port.readLeaseRegistry();
+  > const updatedLeases = registry.leases.map((l) =>
+  >   l.run_id === input.run_id && l.owner_instance_id === input.owner_instance_id
+  >     ? { ...l, lease_expires_at: newLeaseExpiresAt } // same value written to per-instance file
+  >     : l,
+  > );
+  > await this.port.writeLeaseRegistry({ leases: updatedLeases, updated_at: nowIso() });
+  > ```
+  >
+  > If no matching entry exists (race/first-heartbeat), this is a no-op. Existing `RUN_LEASE_NOT_OWNED` early-return path must NOT be changed.
+
+- [ ] T011 Implement `readLeaseRegistry`, `writeLeaseRegistry`, and `emptyLeaseRegistry` on `AopKernel` in `apps/control-plane/src/core/kernel.ts`
+
+  > **Add to the `RunLeaseServicePort` implementation section of `AopKernel`**:
+  >
+  > ```typescript
+  > async readLeaseRegistry(): Promise<LeaseRegistry> {
+  >   const existing = await readJson<LeaseRegistry>(this.pathLayout.leaseRegistryPath, null);
+  >   return existing ?? this.emptyLeaseRegistry();
+  > }
+  >
+  > async writeLeaseRegistry(registry: LeaseRegistry): Promise<void> {
+  >   await ensureDir(path.dirname(this.pathLayout.leaseRegistryPath));
+  >   await atomicWriteJson(this.pathLayout.leaseRegistryPath, registry);
+  > }
+  >
+  > emptyLeaseRegistry(at?: string): LeaseRegistry {
+  >   return { leases: [], updated_at: at ?? nowIso() };
+  > }
+  > ```
+  >
+  > **Imports**: `import type { LeaseRegistry } from './runtime-sessions.js'`. Use existing `readJson`, `atomicWriteJson`, `ensureDir`, `nowIso`, `path` utilities already imported in `kernel.ts`. No new dependencies.  
+  > These three methods are called exclusively inside the existing `withIndexLock` callback — they do not need their own locks.
+
+**Checkpoint**: `npm run typecheck` passes. US1 and US2 acquisition logic is complete. Two non-overlapping runs can both acquire; overlapping run is denied with `LEASE_SCOPE_CONFLICT`.
+
+---
+
+## Phase 5: US4 — Scope Expansion Mid-Run (FR-007)
+
+**Goal**: Allow an active orchestrator to expand its declared scope after discovering additional files during the planning wave. Expansion is additive (union); no paths are ever removed.
+
+- [ ] T012 [US4] Implement `expandRunLeaseScope` method on `RunLeaseService` in `apps/control-plane/src/application/services/run-lease-service.ts`
+
+  > **New async method** on `RunLeaseService` (add after `releaseRunLease`):
+  >
+  > ```typescript
+  > async expandRunLeaseScope(
+  >   input: ExpandRunLeaseScopeInput,
+  > ): Promise<{ data: { scope: LeaseScopeDeclaration } }>
+  > ```
+  >
+  > **Flow inside `withIndexLock`**:
+  >
+  > 1. Read per-instance lease file; verify `run_id` and `owner_instance_id` match → if not, `return fail(ERROR_CODES.RUN_LEASE_NOT_OWNED, ...)`.
+  > 2. Read current `scope` from snapshot (normalize `undefined` → `null`).
+  > 3. Build merged scope:
+  >    ```typescript
+  >    const currentPaths = currentScope?.paths ?? [];
+  >    const currentSections = currentScope?.plan_section_ids ?? [];
+  >    const mergedScope: LeaseScope = {
+  >      paths: [...new Set([...currentPaths, ...(input.additional_paths ?? [])])].sort(),
+  >      plan_section_ids: [
+  >        ...new Set([...currentSections, ...(input.additional_plan_section_ids ?? [])]),
+  >      ].sort(),
+  >    };
+  >    ```
+  >    If `currentScope` was `null`, treat it as `{ paths: [], plan_section_ids: [] }` before merging (expanding from unknown produces a declared scope).
+  > 4. Write updated snapshot with `scope: mergedScope` to per-instance file (`atomicWriteJson`).
+  > 5. Read registry; update matching entry's `scope`; write registry.
+  > 6. Return `{ data: { scope: mergedScope } }`.
+  >
+  > No `any`. The `no-floating-promises` rule applies — all `await` calls must be awaited.
+
+- [ ] T013 [P] [US4] Add `expandRunLeaseScope` to `RunLeaseServicePort` interface and add the public kernel method in `apps/control-plane/src/core/kernel.ts`
+
+  > **In `run-lease-service.ts`**: Add to `RunLeaseServicePort`:
+  >
+  > ```typescript
+  > expandRunLeaseScope(input: ExpandRunLeaseScopeInput): Promise<{ data: { scope: LeaseScopeDeclaration } }>;
+  > ```
+  >
+  > **In `kernel.ts`**: Add public method:
+  >
+  > ```typescript
+  > async expandRunLeaseScope(
+  >   input: ExpandRunLeaseScopeInput,
+  > ): Promise<{ data: { scope: LeaseScopeDeclaration } }> {
+  >   return this.runLeaseService.expandRunLeaseScope(input);
+  > }
+  > ```
+  >
+  > Import `ExpandRunLeaseScopeInput` type from `../application/services/run-lease-service.js` in `kernel.ts`.
+
+**Checkpoint**: `npm run typecheck` passes. `kernel.expandRunLeaseScope(...)` is callable and type-safe.
+
+---
+
+## Phase 6: Supervisor Propagation — CLI Integration
+
+**Purpose**: Wire the scope declaration from feature inputs through the supervisor layer so that every `acquireRunLease` call carries the correct aggregate scope.
+
+- [ ] T014 [P] Add `scope?: LeaseScopeDeclaration` to `FeatureInput` in `apps/control-plane/src/supervisor/types.ts`
+
+  > Locate the `FeatureInput` interface. Append:
+  >
+  > ```typescript
+  > scope?: LeaseScopeDeclaration;  // declared scope at launch; undefined treated as null (conservative)
+  > ```
+  >
+  > Add `import type { LeaseScopeDeclaration } from '../core/runtime-sessions.js'` at the top if not already present.
+
+- [ ] T015 [US1] [US2] [US3] Add `deriveRunScope` and wire to `acquireRunLease` in `apps/control-plane/src/supervisor/run-coordinator.ts`
+
+  > **1. New private method** (add before `start()`):
+  >
+  > ```typescript
+  > private deriveRunScope(features: FeatureInput[]): LeaseScopeDeclaration {
+  >   if (features.some((f) => f.scope === undefined || f.scope === null)) {
+  >     return null; // conservative: any unknown feature → 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(),
+  >   };
+  > }
+  > ```
+  >
+  > **2. In `start()`**, locate the `acquireRunLease(...)` call and add `scope`:
+  >
+  > ```typescript
+  > const runScope = this.deriveRunScope(this.features); // derive before the lock
+  > // ... existing call:
+  > await this.kernel.acquireRunLease({
+  >   // ... existing fields unchanged ...
+  >   scope: runScope, // NEW
+  > });
+  > ```
+  >
+  > `LeaseScopeDeclaration` must be imported with `import type` from `../core/runtime-sessions.js`.
+
+- [ ] T016 [US4] Add `expandScopesFromPlans` post-planning-wave hook in `apps/control-plane/src/supervisor/run-coordinator.ts`
+
+  > **New private async method**:
+  >
+  > ```typescript
+  > private async expandScopesFromPlans(activeFeatureIds: string[]): Promise<void> {
+  >   for (const featureId of activeFeatureIds) {
+  >     const planResult = await this.kernel.readPlan(featureId);
+  >     if (!planResult.ok) continue;
+  >     const affectedFiles: string[] = planResult.data.affected_files ?? [];
+  >     if (affectedFiles.length === 0) continue;
+  >     await this.kernel.expandRunLeaseScope({
+  >       run_id: this.state.runId,
+  >       owner_instance_id: this.state.ownerInstanceId,
+  >       additional_paths: affectedFiles,
+  >     });
+  >   }
+  > }
+  > ```
+  >
+  > **Call site**: Inside the iteration loop, immediately after `await this.planningWaveExecutor.run(activeFeatureIds)` succeeds:
+  >
+  > ```typescript
+  > await this.expandScopesFromPlans(activeFeatureIds);
+  > ```
+  >
+  > This narrows the conservative-null window to "pre-planning only" (R-005). If `expandRunLeaseScope` throws `RUN_LEASE_NOT_OWNED`, swallow and log `console.warn` (non-fatal: the run is shutting down). All other errors propagate normally. `no-floating-promises`: the `await` is required.
+
+**Checkpoint**: `npm run typecheck` passes. `npm run lint` clean. Supervisor propagates scope end-to-end.
+
+---
+
+## Phase 7: New Test Files
+
+**Coverage target**: ≥90% lines / branches / functions / statements on all new and modified files.
+
+- [ ] T017 Create `apps/control-plane/test/lease-scope-conflict-detector.spec.ts` — 26 unit tests for pure conflict-detection logic
+
+  > **Test structure** (Vitest, no async, no mocks needed — pure functions):
+  >
+  > **Block: `normalizePath`** (4 tests, T-01→T-04)
+  > | Test | Input | Expected |
+  > |------|-------|----------|
+  > | T-01 | `"packages/auth"` | `"packages/auth/"` |
+  > | T-02 | `"packages/auth/"` | `"packages/auth/"` (idempotent) |
+  > | T-03 | `""` | `"/"` (root) |
+  > | T-04 | `"src/config.ts"` | `"src/config.ts/"` |
+  >
+  > **Block: `pathsOverlap`** (9 tests, T-05→T-13)
+  > | Test | a | b | Expected |
+  > |------|---|---|----------|
+  > | T-05 | `["packages/auth/"]` | `["packages/payments/"]` | `false` |
+  > | T-06 | `["packages/auth/"]` | `["packages/auth/"]` | `true` |
+  > | T-07 | `["packages/"]` | `["packages/auth/"]` | `true` (parent→child) |
+  > | T-08 | `["packages/auth/"]` | `["packages/"]` | `true` (symmetric) |
+  > | T-09 | `["src/"]` | `["src/config.ts"]` | `true` (file within dir) |
+  > | T-10 | `["src/"]` | `["src-old/config.ts"]` | `false` (no false positive) |
+  > | T-11 | `["packages/auth/","packages/shared/"]` | `["packages/shared/","packages/payments/"]` | `true` (partial overlap) |
+  > | T-12 | `[]` | `["packages/auth/"]` | `false` (empty set) |
+  > | T-13 | `[]` | `[]` | `false` |
+  >
+  > **Block: `planSectionsOverlap`** (4 tests, T-14→T-17)
+  > | Test | 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: `detectConflict` — full conflict matrix** (9 tests, T-18→T-26)
+  > | Test | incoming | active lease(s) | Expected |
+  > |------|----------|-----------------|----------|
+  > | T-18 | `null` | `[{ scope: { paths:["packages/auth/"], plan_section_ids:[] }, run_id:"run-A", ... }]` | `{ conflict: true }` |
+  > | T-19 | `null` | `[]` (empty) | `{ conflict: false }` |
+  > | T-20 | `{ paths:["packages/auth/"], plan_section_ids:[] }` | `[{ scope: null, run_id:"run-A", ... }]` | `{ conflict: true }` |
+  > | T-21 | `{ paths:[], plan_section_ids:[] }` | `[{ scope: { paths:["packages/auth/"], ... }, run_id:"run-A", ... }]` | `{ conflict: false }` |
+  > | T-22 | `{ paths:["packages/auth/"], plan_section_ids:[] }` | `[{ scope: { paths:["packages/payments/"], ... }, run_id:"run-A", ... }]` | `{ conflict: false }` |
+  > | T-23 | `{ paths:["packages/auth/"], plan_section_ids:[] }` | `[{ scope: { paths:["packages/auth/"], ... }, run_id:"run-A", ... }]` | `{ conflict: true, blocking_run_id:"run-A" }` |
+  > | T-24 | `{ paths:["packages/auth/utils/"], plan_section_ids:[] }` | `[{ scope: { paths:["packages/"], ... }, run_id:"run-A", ... }]` | `{ conflict: true }` |
+  > | T-25 | `{ paths:[], plan_section_ids:["plan-section-1"] }` | `[{ scope: { paths:[], plan_section_ids:["plan-section-1"] }, run_id:"run-A", ... }]` | `{ conflict: true }` |
+  > | T-26 | `{ paths:["packages/auth/"], plan_section_ids:[] }` | `[{ scope: { paths:["packages/auth/"], ... }, run_id:"run-A", ... }]` with `excludeRunId:"run-A"` | `{ conflict: false }` |
+  >
+  > Use `describe`/`it` blocks. No `any`. Each test: construct `new LeaseScopeConflictDetector()`, call method, assert result.
+
+- [ ] T018 Create `apps/control-plane/test/run-lease-service.spec.ts` — 20 integration tests using mocked `RunLeaseServicePort`
+
+  > **Mock setup**: Create a `vi.fn()`-based mock for `RunLeaseServicePort`. `readLeaseRegistry` defaults to resolving with `{ leases: [], updated_at: nowIso() }`. `writeLeaseRegistry` defaults to resolving `void`. `emptyLeaseRegistry` delegates to the real detector. Use `beforeEach` to reset mocks.
+  >
+  > **Block: Scope persistence (Story 4)** — T-30→T-33
+  >
+  > - T-30: `acquireRunLease({ scope: { paths: ["packages/auth/"], plan_section_ids: [] }, ... })` → `writeLeaseRegistry` called with entry whose `scope.paths` equals `["packages/auth/"]`
+  > - T-31: `acquireRunLease({ scope: null, ... })` → entry written with `scope: null`
+  > - T-32: `acquireRunLease({ ...no scope field... })` → entry written with `scope: null` (normalization)
+  > - T-33: `acquireRunLease(...)` → `writeLeaseRegistry` called once with `leases` array of length 1 containing correct `run_id`
+  >
+  > **Block: Parallel non-overlapping runs (Story 1)** — T-34→T-35
+  >
+  > - T-34: Registry pre-seeded with Run A (`packages/auth/`); `acquireRunLease` for Run B (`packages/payments/`) → resolves; `writeLeaseRegistry` called with 2-entry array
+  > - T-35: T-34 setup; release Run A → `writeLeaseRegistry` called with 1-entry array (Run B remains); release Run B → empty array
+  >
+  > **Block: Overlapping runs blocked (Story 2)** — T-36→T-38
+  >
+  > - T-36: Registry has Run A (`packages/auth/`); `acquireRunLease` for Run B (`packages/auth/`) → throws/rejects with error code `lease_scope_conflict`; `details.blocking_run_id` = Run A's ID
+  > - T-37: Registry has Run A (`packages/`); Run B (`packages/auth/`) → same as T-36 (parent/child overlap)
+  > - T-38: Registry has Run A (`scope: null`); Run B (any scope) → throws `lease_scope_conflict`
+  >
+  > **Block: Conservative fallback (Story 3)** — T-39→T-40
+  >
+  > - T-39: Any active lease in registry; `acquireRunLease({ scope: null })` → throws `lease_scope_conflict`
+  > - T-40: Empty registry; `acquireRunLease({ scope: null })` → resolves (no conflict, lone run)
+  >
+  > **Block: Stale takeover + scope replacement (FR-008)** — T-41→T-42
+  >
+  > - T-41: Registry has expired entry for Run A (scope `packages/auth/`, `lease_expires_at` in the past); new `acquireRunLease` for `packages/auth/` with `takeover_stale_run: true` → resolves; `writeLeaseRegistry` called without the expired entry; new entry has new `run_id`
+  > - T-42: Registry has unexpired conflicting entry; `acquireRunLease` with `takeover_stale_run: false` → throws `lease_scope_conflict`
+  >
+  > **Block: `expandRunLeaseScope` (FR-007)** — T-43→T-45
+  >
+  > - T-43: Run A holds `packages/auth/`; `expandRunLeaseScope({ additional_paths: ["packages/shared/"] })` → `writeLeaseRegistry` called with entry having `paths: ["packages/auth/", "packages/shared/"]` (sorted)
+  > - T-44: `expandRunLeaseScope` for non-existent/wrong-owner run → throws/rejects with `run_lease_not_owned`
+  > - T-45: `expandRunLeaseScope` with `additional_paths: []` and `additional_plan_section_ids: []` (no-op) → resolves with current scope unchanged
+  >
+  > **Block: `renewRunLease` updates registry TTL** — T-46→T-47
+  >
+  > - T-46: Run A has registry entry; `renewRunLease(...)` → `writeLeaseRegistry` called with same `run_id` but updated `lease_expires_at` > original
+  > - T-47: `renewRunLease` for non-owner → `writeLeaseRegistry` NOT called (existing behavior preserved)
+  >
+  > **Block: `releaseRunLease` removes registry entry** — T-48→T-49
+  >
+  > - T-48: Run A in registry; `releaseRunLease(...)` → `writeLeaseRegistry` called with empty `leases` array
+  > - T-49: Release for wrong owner → `writeLeaseRegistry` NOT called (`released: false` path)
+
+**Checkpoint**: `npx vitest run apps/control-plane/test/lease-scope-conflict-detector.spec.ts apps/control-plane/test/run-lease-service.spec.ts` passes all 46 tests.
+
+---
+
+## Phase 8: Existing Test Updates
+
+**Purpose**: Extend three existing test files with minimal additions to cover the new integration surface. These updates must not break any existing passing tests.
+
+- [ ] T019 [P] Update `apps/control-plane/test/run-coordinator.spec.ts` — add 2 scope-derivation tests
+
+  > **Add two `it()` blocks** to the existing `acquireRunLease` describe block (or nearest equivalent):
+  >
+  > 1. **"passes `scope: null` when any feature has no declared scope"**: Create a `RunCoordinator` with features where at least one has `scope: undefined`; assert that the `acquireRunLease` spy is called with `{ ..., scope: null }`.
+  > 2. **"derives aggregate scope when all features declare scope"**: Features have `scope: { paths: ["packages/auth/"], plan_section_ids: [] }` and `{ paths: ["packages/shared/"], plan_section_ids: ["section-1"] }`; assert `acquireRunLease` called with `{ ..., scope: { paths: ["packages/auth/", "packages/shared/"], plan_section_ids: ["section-1"] } }`.
+  >
+  > Use existing test helpers; do not change any existing test.
+
+- [ ] T020 [P] Update `apps/control-plane/test/supervisor.spec.ts` — add 1 `LEASE_SCOPE_CONFLICT` propagation test
+
+  > **Add one `it()` block**: Configure the kernel mock so `acquireRunLease` rejects with a `fail(ERROR_CODES.LEASE_SCOPE_CONFLICT, ...)` result; assert that the supervisor does not mask or transform the error — the rejection propagates as-is to the caller (or terminates the run with the same structured error). Do not modify any existing test.
+
+- [ ] T021 [P] Update `apps/control-plane/test/kernel.spec.ts` — add 2 registry round-trip tests
+
+  > **Add two `it()` blocks** in a new `describe('readLeaseRegistry / writeLeaseRegistry', ...)` block:
+  >
+  > 1. **"returns empty registry when file is absent"**: Call `kernel.readLeaseRegistry()` with a temp directory where `lease-registry.json` does not exist; assert result is `{ leases: [], updated_at: <any string> }`.
+  > 2. **"round-trips registry correctly"**: Call `kernel.writeLeaseRegistry(registry)` then `kernel.readLeaseRegistry()`; assert the returned value deep-equals the written value (preserving `leases` array and `updated_at`).
+  >
+  > Use the same temp-directory setup pattern as other file-based kernel tests in the file.
+
+**Checkpoint**: `npm run test` passes; no existing tests broken; coverage thresholds remain ≥90%.
+
+---
+
+## Phase 9: Polish & Documentation
+
+- [ ] T022 [P] Add Rule 19 to `docs/core/DOMAIN-LOGIC.md`
+
+  > Append a new rule after the last existing numbered rule:
+  >
+  > ```markdown
+  > ### Rule 19 — Lease Scope Semantics
+  >
+  > **Scope values**:
+  >
+  > - `null` (or `undefined`, normalized to `null` at service boundary) — unknown scope;
+  >   conflicts conservatively with **all** active leases.
+  > - `{ paths: [], plan_section_ids: [] }` — explicitly touches nothing; conflicts with **no** active leases.
+  > - `{ paths: [...], plan_section_ids: [...] }` — declared scope; checked via prefix overlap / equality.
+  >
+  > **Overlap rules**:
+  >
+  > - Path overlap: trailing-slash-normalize both sides; `A` overlaps `B` iff `normalized(A)` is a prefix
+  >   of `normalized(B)` or vice versa. Empty string normalizes to `/` (root).
+  > - Plan section overlap: case-sensitive string equality only (no hierarchy).
+  >
+  > **Registry lifecycle**:
+  >
+  > - Registry (`lease-registry.json`) is created on first acquisition; absent file → empty registry.
+  > - Expired entries (`lease_expires_at < now`) are pruned on every read inside `withIndexLock`.
+  > - Scope is replaced (not merged) on stale-lease takeover.
+  > - Scope expansion is additive (union); paths are never removed from a live lease.
+  > ```
+
+- [ ] T023 [P] Add Scope-Aware Lease Registry ADR to `docs/core/DECISIONS.md`
+
+  > Append after the last existing ADR:
+  >
+  > ```markdown
+  > ## ADR-N — Scope-Aware Lease Registry
+  >
+  > **Context**: The global run lease prevents parallel orchestration of non-overlapping codebase regions.
+  >
+  > **Decision**: Replace the global exclusive lock with a scope-based conflict detector backed by a
+  > shared `.aop/runtime/lease-registry.json` file, protected by the existing index lock (`withIndexLock`).
+  >
+  > **Rationale**:
+  >
+  > - Piggybacks on the existing serialization point — no new lock primitives, no priority-inversion risk.
+  > - Registry is plain JSON; inspectable and debuggable without tooling.
+  > - Expired-entry pruning on every read is self-healing with no GC process.
+  > - Pure conflict-detector (`LeaseScopeConflictDetector`) is isolated from I/O for full unit-test coverage.
+  >
+  > **Alternatives rejected**:
+  >
+  > - Dedicated registry lock: same critical section, adds complexity with no benefit.
+  > - `index.json active_leases[]`: mixes feature-index and lease-registry concerns (SRP violation).
+  > - Per-instance files only: cannot enumerate all active leases for cross-instance detection.
+  >
+  > **Consequences**:
+  >
+  > - ✅ Non-overlapping runs proceed concurrently without artificial serialization.
+  > - ✅ Overlapping runs serialized with observable `LEASE_SCOPE_CONFLICT` error code.
+  > - ✅ Registry is crash-safe (file-based, atomic writes) and self-healing (prune-on-read).
+  > - ⚠️ Index lock hold time slightly increased. Negligible at single-digit concurrency.
+  >
+  > **Status**: Accepted
+  > ```
+  >
+  > Replace `ADR-N` with the correct sequential number based on the last existing ADR.
+
+- [ ] T024 Append Entry 193 to `spec-files/progress.md` after all implementation tasks pass
+
+  > **Only write this entry after all T001–T023 pass `npm run test`, `npm run lint`, and `npm run typecheck`.**  
+  > Follow the required format from CLAUDE.md:
+  >
+  > ```
+  > ✅ **Entry 193 — Scope-Aware Run Lease (002-scope-aware-lease)**
+  >    - **Goal:** Replace the global exclusive run lease with scope-aware conflict detection
+  >      so non-overlapping orchestrator runs proceed in parallel.
+  >    - **Changes made:**
+  >      - `apps/control-plane/src/core/runtime-sessions.ts` — added `LeaseScope`,
+  >        `LeaseScopeDeclaration`, `ActiveLeaseRecord`, `LeaseRegistry` types;
+  >        `scope?` on `RuntimeSessionsSnapshot`.
+  >      - `apps/control-plane/src/core/error-codes.ts` — added `LEASE_SCOPE_CONFLICT`.
+  >      - `apps/control-plane/src/core/path-layout.ts` — added `leaseRegistryPath` getter.
+  >      - `apps/control-plane/src/application/services/lease-scope-conflict-detector.ts` — NEW;
+  >        pure `LeaseScopeConflictDetector` (normalizePath, pathsOverlap, planSectionsOverlap,
+  >        detectConflict); zero I/O.
+  >      - `apps/control-plane/src/application/services/run-lease-service.ts` — `scope?` on
+  >        `AcquireRunLeaseInput`; `ExpandRunLeaseScopeInput`; registry port methods added;
+  >        `acquireRunLease`/`releaseRunLease`/`renewRunLease` extended to maintain registry;
+  >        new `expandRunLeaseScope`.
+  >      - `apps/control-plane/src/core/kernel.ts` — `readLeaseRegistry`, `writeLeaseRegistry`,
+  >        `emptyLeaseRegistry` implemented; `expandRunLeaseScope` public method added.
+  >      - `apps/control-plane/src/supervisor/types.ts` — `scope?` on `FeatureInput`.
+  >      - `apps/control-plane/src/supervisor/run-coordinator.ts` — `deriveRunScope()`,
+  >        `expandScopesFromPlans()`; scope wired to `acquireRunLease`.
+  >      - `apps/control-plane/test/lease-scope-conflict-detector.spec.ts` — NEW; 26 unit tests.
+  >      - `apps/control-plane/test/run-lease-service.spec.ts` — NEW; 20 integration tests.
+  >      - `apps/control-plane/test/run-coordinator.spec.ts` — 2 tests added.
+  >      - `apps/control-plane/test/supervisor.spec.ts` — 1 test added.
+  >      - `apps/control-plane/test/kernel.spec.ts` — 2 tests added.
+  >      - `docs/core/DOMAIN-LOGIC.md` — Rule 19 (lease scope semantics).
+  >      - `docs/core/DECISIONS.md` — ADR: Scope-Aware Lease Registry.
+  >    - **Result:** `npm test` ✅ (X test files / Y tests passing). `npm run lint` ✅.
+  >      `npm run typecheck` ✅.
+  > ```
+  >
+  > Fill in the actual test counts from `npm run test` output before committing.
+
+**Checkpoint**: All Definition-of-Done criteria from `plan.md` are satisfied.
+
+---
+
+## Dependency Graph
+
+```
+T001 (types)
+ ├── T002 [P] (error code)
+ ├── T003 [P] (path layout)
+ ├── T004 (conflict detector — needs types)
+ │    └── T017 (detector unit tests)
+ ├── T005 [P] (scope on snapshot — needs LeaseScopeDeclaration)
+ └── T006 [P] (scope on AcquireInput + ExpandInput — needs LeaseScopeDeclaration)
+      ├── T007 (port interface — needs T005, T006)
+      │    ├── T008 (acquireRunLease — needs T004, T007)
+      │    │    ├── T009 [P] (releaseRunLease — needs T007)
+      │    │    ├── T010 [P] (renewRunLease — needs T007)
+      │    │    └── T018 (integration tests — needs T008, T009, T010, T012)
+      │    └── T011 (kernel port impl — needs T001, T003, T007)
+      │         └── T021 (kernel tests — needs T011)
+      └── T012 (expandRunLeaseScope — needs T004, T006)
+           └── T013 [P] (port + kernel method — needs T011, T012)
+                ├── T014 [P] (FeatureInput — needs T001)
+                ├── T015 (deriveRunScope — needs T008, T014)
+                │    ├── T019 (run-coordinator tests — needs T015)
+                │    └── T020 [P] (supervisor tests — needs T008)
+                └── T016 (expandScopesFromPlans — needs T013, T015)
+
+T022 [P] (DOMAIN-LOGIC.md — independent)
+T023 [P] (DECISIONS.md — independent)
+T024 (progress.md — after all above complete)
+```
+
+---
+
+## Parallel Execution Opportunities
+
+**After T001 completes**: T002, T003, T005, T006 can all run in parallel (different files, no inter-dependencies).
+
+**After T007 completes**: T009 and T010 can run in parallel (both modify `run-lease-service.ts` but in different method bodies — serialize if in the same PR to avoid merge conflicts; otherwise independent).
+
+**After T011 completes**: T012 and T013 can proceed; T014 can proceed in parallel with T012.
+
+**Phase 8 (T019, T020, T021)**: All three test updates are fully parallel (different test files, no shared state).
+
+**Phase 9 (T022, T023)**: Both doc updates are parallel (different files, no dependencies).
+
+---
+
+## Implementation Strategy
+
+| Increment                           | Tasks           | Deliverable                                                                                                                                            |
+| ----------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **MVP — Conflict Detection Engine** | T001–T011, T017 | Core scope conflict detection fully functional; pure-logic unit tests pass; `acquireRunLease` grants or denies based on scope. US1 + US2 complete.     |
+| **Scope Expansion**                 | T012–T013       | Mid-run scope expansion works (FR-007). US4 expanded scope complete.                                                                                   |
+| **Supervisor Wiring**               | T014–T016       | Scope flows from `FeatureInput` through `RunCoordinator` to `acquireRunLease`; post-planning expansion fires automatically. Full end-to-end path live. |
+| **Full Test Coverage**              | T018–T021       | Integration and existing-test updates; ≥90% thresholds maintained.                                                                                     |
+| **Documentation**                   | T022–T024       | DOMAIN-LOGIC.md Rule 19, DECISIONS.md ADR, progress.md Entry 193.                                                                                      |
+
+> **Recommended MVP cut**: Complete T001–T011 + T017 first. This delivers US1 + US2 (the P1 stories) with full unit-test coverage and a passing typecheck. T012–T016 (US3/US4 expansion and supervisor wiring) are safe follow-on increments.
+
+---
+
+## Definition of Done
+
+Mirrors `plan.md` Definition of Done — all items must be checked before marking this feature complete:
+
+- [ ] `npm run typecheck` passes clean (zero new type errors)
+- [ ] `npm run lint` passes with zero warnings (`--max-warnings 0`)
+- [ ] `npm run test` passes at ≥90% lines / branches / functions / statements
+- [ ] `lease-scope-conflict-detector.spec.ts` — all 26 tests pass (T-01 → T-26)
+- [ ] `run-lease-service.spec.ts` — all 20 tests pass (T-30 → T-49)
+- [ ] `run-coordinator.spec.ts` — 2 new scope tests added and passing
+- [ ] `supervisor.spec.ts` — 1 new `LEASE_SCOPE_CONFLICT` propagation test added and passing
+- [ ] `kernel.spec.ts` — 2 new registry round-trip tests added and passing
+- [ ] `docs/core/DOMAIN-LOGIC.md` — Rule 19 added
+- [ ] `docs/core/DECISIONS.md` — Scope-Aware Lease Registry ADR added
+- [ ] `spec-files/progress.md` — Entry 193 appended with final test counts