agentic-orchestrator 0.1.27 → 0.2.0

package/spec-files/outstanding/agentic_orchestrator_human_input_interaction_protocol_spec.md

@@ -2,8 +2,8 @@
 
 > **Purpose of this document**: Define a first-class, deterministic protocol for cases where planner/builder/qa must pause and request human input (clarifications, approvals, permission overrides) before safe continuation.
 
-**Version:** 1.1  
-**Date:** 2026-03-04  
+**Version:** 1.2  
+**Date:** 2026-03-17  
 **Status:** Draft  
 **Roadmap Mapping:** M43
 
@@ -44,19 +44,25 @@ Implementing agents MUST read:
 
 ### 0.3 Scope
 
-This spec implements:
+This spec defines the **shared human-input protocol baseline** for the orchestrator.
+
+It covers:
 
 - explicit question/answer protocol between agents and humans
 - deterministic pause-and-resume behavior for features awaiting input
-- new MCP tools and schema artifacts for question lifecycle
-- CLI and dashboard-facing retrieval/answer workflows
+- durable question artifacts and tool contracts
+- shared operator-visible readiness rules for CLI and dashboard surfaces
+- dashboard/CLI retrieval and answer workflows
 - regression coverage for question-blocked execution and resume
+- provider compatibility requirements for automated interactive execution
 
 Out of scope:
 
 - external ticketing approval workflows (Jira/ServiceNow sync)
 - cryptographic signature workflows for approvals
 - model-vendor-specific conversational UX
+- intake-specific requirement normalization artifacts (`spec.manifest.bootstrap.json`, `spec.manifest.verified.json`, `intake.review.json`)
+- intake-only UI metadata and verified-manifest promotion rules; those belong to M59 and must extend this baseline rather than replace it
 
 ### 0.4 OOP and Architecture Guardrails (Mandatory)
 
@@ -81,17 +87,48 @@ Code organization requirements for this spec:
 
 ---
 
-## 1. Current Gap and Defect Class
+## 1. Current Repository Baseline and Remaining Gaps
+
+This spec predates a substantial amount of human-input implementation work. It must therefore be read as a **protocol refresh and consolidation spec**, not as a greenfield design.
+
+### 1.1 Current Repository Baseline
+
+The current repository already has the following baseline pieces:
+
+1. `QuestionService` exists and persists `.aop/features/<feature_id>/questions.json`.
+2. `feature.question_create`, `feature.question_list`, and `feature.question_answer` are already present in the MCP catalog and kernel wiring.
+3. `WorkerDecisionLoop` already routes `REQUEST.action=ask_user_input` to `feature.question_create`.
+4. `awaiting_input` already exists as a persisted feature status, and `state.md` already carries `human_input.*` summary fields.
+5. The dashboard already exposes:
+   - feature questions API route
+   - question answer API route
+   - focus-view `HumanInputPanel` that answers persisted questions
+6. The `claude` provider already carries `--dangerously-skip-permissions` in automated run/send templates.
+
+### 1.2 Remaining Gaps
+
+Despite that baseline, the protocol is still not fully normalized:
+
+1. this spec still describes several already-implemented protocol artifacts as if they are net-new
+2. operator-visible **question readiness** is not centralized as one authoritative contract
+3. dashboard/focus/CLI transport semantics are duplicated across specs instead of owned here
+4. dedicated CLI question workflow is still missing even though the underlying tools exist
+5. triage drawer still renders open questions passively instead of supporting first-class answers
+6. activity projection still retains heuristic waiting-input fallbacks instead of relying only on persisted state where possible
+7. `resume_status` baseline is too narrow for future pause/resume extensions such as `intake`
+8. some names in this older spec drift from current implementation (`question_already_closed` vs older wording, existing tool/schema paths, current dashboard answer path)
 
-Current system behavior is missing a first-class handshake when agents need input:
+### 1.3 Normative Role of This Spec
 
-1. worker `REQUEST` handling has no `ask_user` action contract.
-2. `waiting_input` exists only as heuristic activity derivation from `status_reason` text.
-3. there is no durable question queue artifact.
-4. no structured answer tool exists (`feature.send_message` is unstructured best-effort delivery).
-5. run loop has no deterministic pause/resume contract for unresolved questions.
+This spec is the authoritative baseline for:
 
-Result: operators must use ad hoc `send`/`attach` workflows, and orchestrator semantics are ambiguous when a role cannot proceed safely without human response.
+- generic question lifecycle
+- persisted pause/resume semantics
+- ready-state visibility rules
+- shared question payload baseline
+- operator answer transport
+
+Any later spec, including M59 intake, must extend this contract rather than silently fork it.
 
 ---
 
@@ -100,7 +137,7 @@ Result: operators must use ad hoc `send`/`attach` workflows, and orchestrator se
 ### 2.1 Must-Have Outcomes
 
 1. Agents can raise a structured blocking question via tool contract.
-2. Feature enters deterministic `awaiting_input` state until answered (or expired/escalated).
+2. Feature enters explicit `awaiting_input` state until answered (or expired/escalated).
 3. Human answers are persisted as first-class artifacts and fed back into role context.
 4. Orchestrator does not run planner/build/qa waves for features with open blocking questions.
 5. Answering a question deterministically resumes the correct phase.
@@ -183,7 +220,7 @@ Result: operators must use ad hoc `send`/`attach` workflows, and orchestrator se
 
 ### 5.1 Feature Status Contract
 
-Add new status constant and schema enum:
+Baseline status constant and schema enum:
 
 - `awaiting_input`
 
@@ -209,11 +246,11 @@ human_input:
 Rules:
 
 - `open_question_id` must be null when status is not `awaiting_input`.
-- `resume_status` must be one of `planning|building|qa|blocked|ready_to_merge` when awaiting input.
+- `resume_status` must be a resumable lifecycle phase supported by the runtime. Baseline values are `planning|building|qa|blocked|ready_to_merge`; future extension specs may add values such as `intake`.
 
 ### 5.3 Question Artifact Contract
 
-Add per-feature artifact:
+Canonical per-feature artifact:
 
 ```text
 .aop/features/<feature_id>/questions.json
@@ -247,9 +284,9 @@ Shape:
 }
 ```
 
-### 5.4 Tool Catalog Additions
+### 5.4 Tool Catalog Baseline
 
-Add new MCP tools:
+Canonical MCP tools:
 
 1. `feature.question_create` (mutating)
 2. `feature.question_list` (read)
@@ -297,14 +334,15 @@ Output:
 - `question_status` (`answered`)
 - `feature_status` (resumed phase)
 - `resumed` (boolean)
+- `resume_status` (optional in baseline, recommended when richer UI flows need deterministic resume-target display)
 
 ### 5.5 Error Taxonomy Additions
 
 Add:
 
 - `question_not_found`
-- `question_already_answered`
-- `question_invalid_answer`
+- `question_already_closed`
+- `question_answer_invalid`
 - `question_conflict_open`
 - `question_answer_not_allowed_in_terminal_state`
 
@@ -347,36 +385,73 @@ Rules:
 
 ### 6.4 Activity State Determinism
 
-Stop relying on heuristic `status_reason` parsing for waiting-input detection:
+The protocol should prefer persisted status/state over heuristic `status_reason` parsing:
 
 - if state status is `awaiting_input`, `activity_state` reports `waiting_input`
 - heuristic fallback remains only for backward compatibility during migration window
 
+### 6.5 Question Readiness Contract
+
+A question is operator-visible and answerable only when it is persisted and the feature state reflects the pause.
+
+Baseline ready-state condition:
+
+```text
+question_ready =
+  exists(open question record)
+  AND feature.status == awaiting_input
+  AND feature.human_input.open_question_id == question.question_id
+```
+
+Normative consequences:
+
+- transient model output alone is never sufficient
+- malformed or failed `REQUEST` handling must not create operator-visible question state
+- dashboard, focus view, and future CLI surfaces must all use this same persisted source of truth
+- phase-specific specs may add stricter predicates; for example M59 intake additionally requires `question.resume_status == intake`
+
 ---
 
-## 7. CLI and Dashboard Surface
+## 7. Operator Surfaces
 
-### 7.1 New CLI Commands
+### 7.1 Shared Transport Baseline
 
-Add:
+The generic protocol baseline now assumes these operator-facing paths exist or will be normalized here:
 
-1. `aop questions --feature-id <id> [--status open|answered|expired|withdrawn|all]`
-2. `aop answer --feature-id <id> --question-id <qid> --answer <value> [--answered-by <id>]`
+- dashboard:
+  - feature questions route
+  - question answer route
+  - focus-view `HumanInputPanel`
+- future CLI:
+  - `aop questions --feature-id <id> [--status open|answered|expired|withdrawn|all]`
+  - `aop answer --feature-id <id> --question-id <qid> --answer <value> [--answered-by <id>]`
 
 Behavior:
 
-- both commands return structured JSON envelopes
-- answer command validates feature/question state and idempotency
+- all answer paths terminate in `feature.question_answer`
+- all read paths derive from persisted `questions.json` and `state.md`
+- transport wrappers may differ, but the underlying lifecycle is shared
 
-### 7.2 Status Output Enhancements
+### 7.2 Status and Summary Baseline
 
-`aop status` and dashboard payload include:
+`aop status` and dashboard summary payloads must expose at least:
 
 - `open_question_count`
 - `open_question_id`
 - `awaiting_since`
+- `requested_by_role`
 - `resume_status`
 
+### 7.3 Dashboard Behavior Baseline
+
+At baseline, the dashboard must support:
+
+- rendering persisted open questions
+- showing `Awaiting Input` / waiting-input states from persisted state
+- answering a blocking question from at least one first-class surface
+
+The current focus-view answer path satisfies the last requirement today. Additional surfaces, such as the triage drawer, should be treated as parity work rather than protocol invention.
+
 ---
 
 ## 8. Planner / Builder / QA Role Semantics
@@ -414,7 +489,7 @@ human_input:
 
 Rules:
 
-- if `enabled=false`, `feature.question_create` returns `unsupported_operation`
+- if `enabled=false`, `feature.question_create` returns a structured policy/configuration error; current baseline may surface `invalid_argument` until a more specific code is introduced
 - `max_open_questions_per_feature=1` is enforced strictly in v1
 
 ---
@@ -435,7 +510,7 @@ Rules:
 
 4. Answer submitted for already answered question:
 
-- return idempotent success if same operation replay, else `question_already_answered`.
+- return idempotent success if same operation replay, else `question_already_closed`.
 
 5. Feature reaches terminal status while question open:
 
@@ -465,44 +540,55 @@ Rules:
 
 ## 11. Implementation Plan
 
-### M43.1 Core Question Service
+This plan reflects the **current repository baseline**.
+
+### M43.0 Provider Compatibility Regression Guard
 
-- add `QuestionService` for create/list/answer lifecycle
-- persist `.aop/features/<id>/questions.json`
-- enforce open-question invariant and idempotency behavior
+- preserve `--dangerously-skip-permissions` on automated `claude` run/send templates
+- preserve provider parity with `codex` and `copilot`
+- treat this as regression protection, not new design work
 
-### M43.2 Tooling and Schema Integration
+### M43.1 Protocol Baseline Hardening
 
-- add tool constants and kernel routing
-- add catalog entries and input/output schemas
-- add policy/state schema fields
+- keep `QuestionService`, question artifacts, and MCP tools as the canonical persistence boundary
+- align spec, schemas, error names, and output shapes to current implementation
+- extend resumable-state contract so later specs can add `intake`
 
-### M43.3 Runtime Integration
+### M43.2 Shared Ready-State and Payload Baseline
 
-- wire `ask_user_input` request handling in `WorkerDecisionLoop`
-- skip awaiting-input features in wave executors
-- enrich `feature.get_context` with human input data
+- define one authoritative question-ready contract for operator-visible work
+- normalize baseline dashboard / route / summary payload requirements here
+- require later specs to add only delta fields
 
-### M43.4 CLI and Reporting
+### M43.3 Operator Workflow Parity
 
-- add `questions` and `answer` commands to parser/bootstrap/help
-- extend status/dashboard payload with question summary fields
+- add dedicated CLI `questions` / `answer` workflow
+- extend the dashboard triage drawer so it can answer blocking questions directly
+- keep focus-view `HumanInputPanel` on the same backend answer path
+
+### M43.4 Deterministic Projection Cleanup
+
+- reduce waiting-input heuristics where persisted state already exists
+- make status and activity reporting prefer `awaiting_input` + `human_input.*`
 
 ### M43.5 Verify Path Coverage
 
-- add unit/integration tests and include in `npm run verify` path
+- add or update unit/integration/dashboard tests and include them in `npm run verify`
 
 ---
 
 ## 12. File-Level Change Targets
 
-- `apps/control-plane/src/application/services/question-service.ts` (new)
+- `apps/control-plane/src/providers/provider-defaults.ts` — preserve automated `claude` run/send compatibility guardrails.
+- `apps/control-plane/src/application/services/question-service.ts` — baseline protocol semantics, resumable-state widening, answer output alignment.
+- `apps/control-plane/src/core/questions.ts` — canonical question record / summary shape.
 - `apps/control-plane/src/core/constants.ts`
 - `apps/control-plane/src/core/kernel.ts`
 - `apps/control-plane/src/supervisor/worker-decision-loop.ts`
 - `apps/control-plane/src/supervisor/planning-wave-executor.ts`
 - `apps/control-plane/src/supervisor/build-wave-executor.ts`
 - `apps/control-plane/src/supervisor/qa-wave-executor.ts`
+- `apps/control-plane/src/application/services/activity-monitor-service.ts`
 - `apps/control-plane/src/cli/types.ts`
 - `apps/control-plane/src/cli/cli-argument-parser.ts`
 - `apps/control-plane/src/cli/help-command-handler.ts`
@@ -510,24 +596,28 @@ Rules:
 - `apps/control-plane/src/cli/answer-command-handler.ts` (new)
 - `apps/control-plane/src/interfaces/cli/bootstrap.ts`
 - `apps/control-plane/src/cli/status-command-handler.ts`
-- `apps/control-plane/src/application/services/activity-monitor-service.ts`
 - `agentic/orchestrator/tools/catalog.json`
-- `agentic/orchestrator/tools/schemas/input/feature.question_create.input.schema.json` (new)
-- `agentic/orchestrator/tools/schemas/output/feature.question_create.output.schema.json` (new)
-- `agentic/orchestrator/tools/schemas/input/feature.question_list.input.schema.json` (new)
-- `agentic/orchestrator/tools/schemas/output/feature.question_list.output.schema.json` (new)
-- `agentic/orchestrator/tools/schemas/input/feature.question_answer.input.schema.json` (new)
-- `agentic/orchestrator/tools/schemas/output/feature.question_answer.output.schema.json` (new)
+- `agentic/orchestrator/tools/schemas/input/feature.question_create.input.schema.json`
+- `agentic/orchestrator/tools/schemas/output/feature.question_create.output.schema.json`
+- `agentic/orchestrator/tools/schemas/input/feature.question_list.input.schema.json`
+- `agentic/orchestrator/tools/schemas/output/feature.question_list.output.schema.json`
+- `agentic/orchestrator/tools/schemas/input/feature.question_answer.input.schema.json`
+- `agentic/orchestrator/tools/schemas/output/feature.question_answer.output.schema.json`
 - `agentic/orchestrator/schemas/state.schema.json`
 - `agentic/orchestrator/schemas/policy.schema.json`
 - `agentic/orchestrator/policy.yaml`
-- `README.md`
-- `apps/control-plane/test/question-service.spec.ts` (new)
+- `packages/web-dashboard/src/app/api/features/[id]/questions/route.ts`
+- `packages/web-dashboard/src/app/api/features/[id]/questions/[questionId]/answer/route.ts`
+- `packages/web-dashboard/src/components/human-input-panel.tsx`
+- `packages/web-dashboard/src/components/dashboard/triage-drawer.tsx`
+- `packages/web-dashboard/src/lib/types.ts`
+- `packages/web-dashboard/src/lib/aop-client.ts`
+- `apps/control-plane/test/question-service.spec.ts`
 - `apps/control-plane/test/worker-decision-loop.spec.ts`
-- `apps/control-plane/test/run-coordinator.spec.ts`
+- `apps/control-plane/test/kernel-tool-wiring.spec.ts`
 - `apps/control-plane/test/cli.unit.spec.ts`
 - `apps/control-plane/test/status-command.spec.ts`
-- `apps/control-plane/test/mcp.spec.ts`
+- `packages/web-dashboard/test/**` (question/triage/focus coverage)
 
 ---
 
@@ -535,15 +625,17 @@ Rules:
 
 ### 13.1 Unit
 
+- `claude` provider automated run/send templates retain `--dangerously-skip-permissions` and remain aligned with current provider policy
 - question create transitions state to `awaiting_input`
 - answer transitions to recorded `resume_status`
 - duplicate open question is rejected
 - answer idempotency and replay behavior
+- ready-state projection requires persisted open question + `awaiting_input` state
 
 ### 13.2 Supervisor Integration
 
 - feature in `awaiting_input` is skipped by all wave executors
-- answering question resumes the next iteration in deterministic phase
+- answering question resumes the next iteration in the recorded phase
 
 ### 13.3 CLI Integration
 
@@ -552,10 +644,16 @@ Rules:
 
 ### 13.4 MCP Contract
 
-- all new tools validate schema and role authorization
+- question tools validate schema and role authorization
 - mutating tools enforce `operation_id`
 
-### 13.5 Regression
+### 13.5 Dashboard / Focus Regression
+
+- focus-view `HumanInputPanel` answers via the persisted question-answer route
+- triage drawer answer controls use the same answer path once parity work lands
+- dashboard never renders transient non-persisted questions as actionable work
+
+### 13.6 Regression
 
 - GIVEN builder asks permission override WHEN unanswered THEN no further patch/gate actions execute for that feature
 - GIVEN answer is provided WHEN next iteration runs THEN builder resumes and can continue gate repair
@@ -564,19 +662,24 @@ Rules:
 
 ## 14. Acceptance Criteria
 
-1. Agent-generated blocking questions become first-class persisted artifacts.
-2. Feature status transitions to `awaiting_input` deterministically.
-3. No planning/building/qa waves execute for features with open blocking question.
-4. Human answer flow is deterministic, idempotent, and auditable.
-5. Feature resumes from recorded phase after answer.
-6. `aop status`, `aop questions`, and `aop answer` provide complete operator workflow.
-7. `npm run verify` fails if awaiting-input pause/resume invariants regress.
-8. Implementation boundaries follow KISS/SRP/SOLID/Hexagonal requirements from Section 0.4.
+1. The spec reflects the current repository baseline rather than re-specifying already-landed behavior as future work.
+2. Agent-generated blocking questions remain first-class persisted artifacts.
+3. Feature status transitions to `awaiting_input` deterministically.
+4. No planning/building/qa waves execute for features with open blocking question.
+5. Human answer flow is deterministic, idempotent, and auditable.
+6. Feature resumes from recorded phase after answer.
+7. There is one authoritative question-ready contract based on persisted state, and later specs reuse it.
+8. Dashboard and CLI answer flows terminate in `feature.question_answer`.
+9. `npm run verify` fails if awaiting-input pause/resume invariants regress.
+10. Implementation boundaries follow KISS/SRP/SOLID/Hexagonal requirements from Section 0.4.
 
 ---
 
 ## 15. Risks and Mitigations
 
+- Risk: `--dangerously-skip-permissions` on `claude` provider removes interactive approval prompts for automated sessions.
+  - Mitigation: semantically, the orchestrator already provides equivalent protection in automated interactive execution — plan validation, kernel validation, and gate checks remain the security boundary. The flag is consistent with how `codex` and `copilot` providers are already configured. This spec only requires deterministic automated compatibility; it does not rely on a specific `attach` permission model.
+
 - Risk: status-model expansion (`awaiting_input`) causes unintended branch regressions.
   - Mitigation: add explicit status transition tests in all wave executors and coordinator.
 

package/spec-files/outstanding/agentic_orchestrator_interactive_rename_cleanup_spec.md

@@ -0,0 +1,197 @@
+# 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.                        |