# Feature Spec: Interactive Mode Identifier Rename Cleanup

> Purpose: After deterministic mode removal (M56), rename identifiers that carry the word "interactive" as a mode qualifier — making them mode-neutral now that interactive execution is the only model.

**Version:** 1.0
**Date:** 2026-03-16
**Status:** Outstanding
**Roadmap Mapping:** M57 (Interactive Mode Identifier Rename Cleanup)
**Depends On:** M56 (Remove Deterministic Execution Mode, complete)

---

## 0. Background & Motivation

M56 removed the `deterministic` execution mode entirely. After that change, identifiers like `interactiveOutcome`, `supportsInteractiveMode`, and `INTERACTIVE_CHECKPOINT_INVALID` carry a qualifier that no longer distinguishes anything — all execution is now interactive. These names are residual noise that will mislead future maintainers into thinking a mode distinction still exists.

This spec renames those identifiers to mode-neutral equivalents. It is a pure rename pass: no logic changes, no behavioral changes, no additional deletions. Each rename must be applied consistently across all call sites, tests, docs, and schemas.

---

## 1. Rename Map

The table below defines every rename in scope. The left column is the current name; the right column is the target name. All renames are applied in the same implementation pass to avoid an intermediate broken state.

### 1.1 Type and Interface Names

| Current name                 | New name           | File(s)                                                                                                     |
| ---------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------- |
| `InteractiveExecutionConfig` | `ExecutionConfig`  | `application/services/checkpoint-service.ts`, `supervisor/runtime.ts`, `supervisor/worker-decision-loop.ts` |
| `InteractiveRunSummary`      | `WorkerRunSummary` | `supervisor/worker-decision-loop.ts`                                                                        |

### 1.2 Method and Function Names

| Current name                          | New name                   | File(s)                                                                          |
| ------------------------------------- | -------------------------- | -------------------------------------------------------------------------------- |
| `resolveInteractiveExecutionConfig()` | `resolveExecutionConfig()` | `supervisor/runtime.ts`                                                          |
| `resolveInteractiveConfig()`          | `resolveExecutionConfig()` | `supervisor/worker-decision-loop.ts` (callback name on dependencies)             |
| `isInteractiveEligible()`             | `isWorktreeEligible()`     | `supervisor/worker-decision-loop.ts`                                             |
| `runInteractive()`                    | `runWithWorktree()`        | `supervisor/worker-decision-loop.ts`                                             |
| `buildInteractiveWorkerPrompt()`      | `buildWorkerPrompt()`      | `providers/cli-worker-provider.ts` (already renamed in M56; confirm it was done) |

### 1.3 Field and Variable Names

| Current name                                           | New name           | Location                                                                              |
| ------------------------------------------------------ | ------------------ | ------------------------------------------------------------------------------------- |
| `interactiveConfig` (field on `SupervisorRuntime`)     | `executionConfig`  | `supervisor/runtime.ts`                                                               |
| `interactiveConfig` (field on `WorkerDecisionLoop`)    | `executionConfig`  | `supervisor/worker-decision-loop.ts`                                                  |
| `interactiveEligible` (local variable)                 | `worktreeEligible` | `supervisor/worker-decision-loop.ts`                                                  |
| `interactiveSummary` (local variable)                  | `workerSummary`    | `supervisor/worker-decision-loop.ts`                                                  |
| `interactiveOutcome` (field on `WorkerDecisionResult`) | `workerOutcome`    | `supervisor/worker-decision-loop.ts`, `supervisor/types.ts`                           |
| `interactiveOutcome` (field on worker event payloads)  | `worker_outcome`   | `supervisor/worker-decision-loop.ts` event emission                                   |
| `interactive_outcome` (analytics event field key)      | `worker_outcome`   | `supervisor/worker-decision-loop.ts` event emission, any downstream analytics readers |

### 1.4 Capability Flag Names

| Current name                                                | New name                    | File(s)                                                                                                                                                  |
| ----------------------------------------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `supportsInteractiveMode` (on `WorkerProviderCapabilities`) | `supportsWorktreeExecution` | `providers/providers.ts`, `providers/cli-worker-provider.ts`, `providers/api-worker-provider.ts`, `providers/worker-provider-factory.ts`, all test files |

### 1.5 Error Code Names

| Current name                     | New name             | File(s)                                                                                      |
| -------------------------------- | -------------------- | -------------------------------------------------------------------------------------------- |
| `INTERACTIVE_CHECKPOINT_INVALID` | `CHECKPOINT_INVALID` | `core/error-codes.ts`, all files that reference `ERROR_CODES.INTERACTIVE_CHECKPOINT_INVALID` |
| `INTERACTIVE_NO_NEW_WORK`        | `WORKER_NO_NEW_WORK` | `core/error-codes.ts`, all files that reference `ERROR_CODES.INTERACTIVE_NO_NEW_WORK`        |

### 1.6 Analytics File Path

| Current path                           | New path                                | File(s)                                                                                                     |
| -------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `.aop/analytics/interactive-mode.json` | `.aop/analytics/execution-metrics.json` | `application/services/checkpoint-service.ts` (`interactiveMetricsPath()` method → `executionMetricsPath()`) |

The method `interactiveMetricsPath()` should also be renamed to `executionMetricsPath()`.

### 1.7 Config Key in agents.yaml

After M56 restructures `runtime.interactive.*` to `runtime.execution.*`, there are no further config key renames needed in this spec. Confirm M56 was applied before starting M57.

---

## 2. Documentation Updates

### 2.1 `docs/core/ARCHITECTURE.md`

- Replace any remaining references to "interactive mode" as a named concept with "agent execution" or "worktree execution".
- Update type/interface names in any architecture diagrams or tables to match the new names above.

### 2.2 `docs/core/DOMAIN-LOGIC.md`

- Replace "interactive mode checkpoint" with "execution checkpoint".
- Replace "interactive outcome" with "worker outcome".
- Replace `INTERACTIVE_CHECKPOINT_INVALID` with `CHECKPOINT_INVALID`.
- Replace `INTERACTIVE_NO_NEW_WORK` with `WORKER_NO_NEW_WORK`.

### 2.3 `docs/core/PATTERNS.md`

- Update any canonical code examples that reference `interactiveOutcome`, `InteractiveExecutionConfig`, `supportsInteractiveMode`, or the old error code names.

### 2.4 `docs/core/DECISIONS.md`

Add a new ADR entry:

> **ADR-NNN — Rename Residual "Interactive" Mode Identifiers**
>
> **Status:** Accepted
>
> **Context:** M56 removed deterministic mode. Identifiers like `interactiveOutcome` and `INTERACTIVE_CHECKPOINT_INVALID` retained a mode qualifier that no longer distinguished anything.
>
> **Decision:** Rename all such identifiers to mode-neutral equivalents (see M57 spec). No behavioral change.
>
> **Consequences:** Cleaner, more maintainable API surface. Future maintainers will not be misled into thinking a mode distinction exists.

### 2.5 `docs/core/TROUBLESHOOTING.md`

- Update any troubleshooting entries that reference `INTERACTIVE_CHECKPOINT_INVALID` or `INTERACTIVE_NO_NEW_WORK` by error code name to use the new names.

### 2.6 `README.md`

- Update any references to the old error code names or capability flag names that appear in the README.

### 2.7 `spec-files/progress.md`

- Append a new numbered entry when M57 implementation is complete.

---

## 3. Test Updates

- All tests referencing `interactiveOutcome` on decision results must use `workerOutcome`.
- All tests asserting `supportsInteractiveMode` on capability objects must use `supportsWorktreeExecution`.
- All tests referencing `ERROR_CODES.INTERACTIVE_CHECKPOINT_INVALID` must use `ERROR_CODES.CHECKPOINT_INVALID`.
- All tests referencing `ERROR_CODES.INTERACTIVE_NO_NEW_WORK` must use `ERROR_CODES.WORKER_NO_NEW_WORK`.
- All tests constructing `InteractiveExecutionConfig` objects must use `ExecutionConfig`.
- All tests passing `resolveInteractiveConfig` or `resolveExecutionMode` callbacks to `WorkerDecisionLoop` must use the new dependency field names.

---

## 4. Implementation Notes

### 4.1 Order of Operations

Because these are pure renames with no logic changes, the order within a single pass does not matter as long as all call sites are updated atomically. The recommended approach is:

1. Rename the declaration (type, method, field, constant).
2. Let TypeScript compilation errors identify every call site.
3. Update all call sites.
4. Run `npm run build` to verify zero errors.
5. Run `npm run test` to verify no behavioral regressions.

### 4.2 Grep Verification

After implementation, run the following to confirm no residual occurrences remain:

```bash
grep -r "interactiveOutcome\|interactiveConfig\|interactiveEligible\|interactiveSummary" apps/control-plane/src/
grep -r "supportsInteractiveMode" apps/control-plane/src/
grep -r "InteractiveExecutionConfig\|InteractiveRunSummary" apps/control-plane/src/
grep -r "INTERACTIVE_CHECKPOINT_INVALID\|INTERACTIVE_NO_NEW_WORK" apps/control-plane/src/
grep -r "interactive-mode\.json\|interactiveMetricsPath" apps/control-plane/src/
```

All commands should return no matches.

---

## 5. Out of Scope

- Logic changes of any kind.
- Removal of checkpoint, worktree, or watchdog infrastructure.
- Dashboard / web UI changes.
- Any rename not listed in §1.

---

## 6. Acceptance Criteria

| #   | Criterion                                                                         | Verification       |
| --- | --------------------------------------------------------------------------------- | ------------------ |
| 1   | No `interactiveOutcome` references remain in source                               | Grep check (§4.2)  |
| 2   | No `supportsInteractiveMode` references remain in source                          | Grep check (§4.2)  |
| 3   | No `InteractiveExecutionConfig` references remain in source                       | Grep check (§4.2)  |
| 4   | No `INTERACTIVE_CHECKPOINT_INVALID` or `INTERACTIVE_NO_NEW_WORK` remain in source | Grep check (§4.2)  |
| 5   | No `interactive-mode.json` path reference remains in source                       | Grep check (§4.2)  |
| 6   | `npm run build` passes with zero errors and zero lint warnings                    | `npm run build` ✅ |
| 7   | `npm run test` passes all tests at ≥90% coverage thresholds                       | `npm run test` ✅  |
| 8   | `npm run validate:mcp-contracts` passes                                           | ✅                 |
| 9   | `npm run validate:architecture` passes                                            | ✅                 |

---

## 7. Risks

| Risk                                                                                                                                 | Likelihood           | Mitigation                                                                                                           |
| ------------------------------------------------------------------------------------------------------------------------------------ | -------------------- | -------------------------------------------------------------------------------------------------------------------- |
| A rename is missed in a test file, causing a type error caught only at runtime                                                       | Low                  | TypeScript strict mode and `npm run build` will catch all type-level mismatches at compile time.                     |
| Analytics event field rename (`interactive_outcome` → `worker_outcome`) breaks a dashboard query                                     | Low (pre-production) | Check `packages/web-dashboard/` for any field reads on worker event records before renaming the emitted payload key. |
| `buildInteractiveWorkerPrompt` was already renamed in M56 as `buildWorkerPrompt`; attempting to rename again in M57 causes confusion | Low                  | The M57 implementing agent should confirm M56's rename was applied and skip that entry if so.                        |
