# Feature Spec: Remove Deterministic Execution Mode

> Purpose: Delete the `deterministic` execution mode entirely — its code paths, CLI surface, configuration fields, schema entries, and documentation — leaving interactive mode as the sole execution path for all agent workers.

**Version:** 1.0
**Date:** 2026-03-16
**Status:** Outstanding
**Roadmap Mapping:** M56 (Remove Deterministic Execution Mode)
**Depends On:** None
**Follow-on Spec:** `spec-files/outstanding/agentic_orchestrator_interactive_rename_cleanup_spec.md` (M57)

---

## 0. Background & Motivation

The orchestrator was originally designed with two agent execution models:

- **Deterministic mode** — agents receive a bundled JSON payload and must return a single structured JSON object (`PLAN_SUBMISSION | PATCH | NOTE | REQUEST`). The orchestrator parses and applies patches centrally.
- **Interactive mode** — agents are pointed at real files on disk inside an isolated worktree, edit them directly, and the orchestrator captures periodic diffs via `CheckpointService`. This is the mode `agents.yaml` defaults to (`execution_mode: interactive`).

Deterministic mode has never been used in production. It creates a sustained maintenance burden: every execution-path change requires testing both branches, prompt builders must stay in sync, and the `ExecutionMode` union type propagates through types, schemas, config, and CLI flags. Since the system is pre-production, there are no downstream consumers to protect.

This spec defines the full deletion of the deterministic code path and all associated surface area.

---

## 1. Deletion Scope

### 1.1 Types Layer

| Symbol                                                    | File                                        | Action                                                                           |
| --------------------------------------------------------- | ------------------------------------------- | -------------------------------------------------------------------------------- |
| `ExecutionMode` type (`'deterministic' \| 'interactive'`) | `providers/providers.ts`                    | Delete. Downstream parameters carrying this type are updated per sections below. |
| `execution_mode?: ExecutionMode`                          | `providers/providers.ts` → `WorkerRunInput` | Remove field.                                                                    |
| `execution_mode?: 'deterministic' \| 'interactive'`       | `cli/types.ts` → `RunOptions`               | Remove field.                                                                    |
| `execution_mode?: ExecutionMode`                          | `supervisor/types.ts` → `SupervisorOptions` | Remove field.                                                                    |

### 1.2 CLI Layer

Remove the `--execution-mode` flag from **all** of the following files. In each case "remove" means deleting the parse branch, the field reference, and any associated help text:

| File                            | What changes                                                                                                         |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `cli/cli-argument-parser.ts`    | Delete the `--execution-mode` token branch (lines ~104–106).                                                         |
| `cli/types.ts`                  | Remove `execution_mode` from `RunOptions`.                                                                           |
| `cli/run-command-handler.ts`    | Remove `execution_mode: options.execution_mode` from the supervisor options object.                                  |
| `cli/resume-command-handler.ts` | Remove `execution_mode` passthrough to supervisor options.                                                           |
| `cli/attach-command-handler.ts` | Remove any `execution_mode` passthrough.                                                                             |
| `cli/completion-resolver.ts`    | Remove `--execution-mode` from completion candidates.                                                                |
| `cli/help-command-handler.ts`   | Remove the `--execution-mode` entry from `run` and `resume` command help entries.                                    |
| `CLAUDE.md`                     | Remove `--execution-mode <deterministic\|interactive>` from the `run` and `resume` bullet points in the CLI section. |

### 1.3 Provider / Prompt-Builder Layer (`providers/cli-worker-provider.ts`)

| Symbol                                                                  | Action                                                                                                         |
| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `buildDeterministicWorkerPrompt()`                                      | Delete entirely.                                                                                               |
| `buildWorkerPrompt()` dispatch function                                 | Delete entirely.                                                                                               |
| `buildInteractiveWorkerPrompt()`                                        | Rename to `buildWorkerPrompt()`. This becomes the unconditional prompt builder called at the single call site. |
| `executionMode` parameter on the former `buildWorkerPrompt()` call site | Remove; no longer needed.                                                                                      |

The `execution_mode` field passed into the output parser context in `api-worker-provider.ts` (`executionMode: input.execution_mode`) should be removed or hardcoded to `'interactive'` if the parser contract requires a value.

### 1.4 Supervisor / Runtime Layer

**`supervisor/runtime.ts`**

| Symbol                                                                           | Action                                                                                                                                            |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `asExecutionMode()` helper                                                       | Delete.                                                                                                                                           |
| `cliExecutionMode: ExecutionMode \| null` field                                  | Delete.                                                                                                                                           |
| `resolveExecutionMode()` method                                                  | Delete. All call sites that used it now hardcode `'interactive'`.                                                                                 |
| `resolveInteractiveExecutionConfig()`                                            | Retain (renamed out of scope for this spec).                                                                                                      |
| `this.cliExecutionMode = asExecutionMode(options.execution_mode)` in constructor | Delete.                                                                                                                                           |
| `acceptance_criteria` entry referencing "deterministic plan" (line ~853)         | Update wording to remove the word "deterministic" where it refers to the execution mode (preserve uses that refer to the kernel's state machine). |

**`supervisor/worker-decision-loop.ts`**

| Symbol                                                                           | Action                                                                                                                                                     |
| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `resolveExecutionMode` callback in `WorkerDecisionLoopDependencies`              | Remove field.                                                                                                                                              |
| `resolveExecutionModeOverride` private field                                     | Delete.                                                                                                                                                    |
| `resolveExecutionMode()` private method                                          | Delete.                                                                                                                                                    |
| `isInteractiveEligible()` private method                                         | The guard that prevents non-`interactive` modes from entering the interactive path becomes unconditional — `isInteractiveEligible` can be inlined/deleted. |
| Fallback `return 'deterministic'` (line ~452)                                    | Delete.                                                                                                                                                    |
| `if (requestedExecutionMode === 'interactive' && !interactiveEligible)` branch   | Delete.                                                                                                                                                    |
| The `executionMode: ExecutionMode` local variable and its conditional assignment | Delete; replace with the constant `'interactive'` where the value is passed to `buildRunInput`.                                                            |
| `interactive_fallback` event emission                                            | Delete (only fired when mode downgraded from interactive to deterministic).                                                                                |

### 1.5 Config / Schema Layer

| File                                                                   | What changes                                                                                                                                                                                                                                                                                                                                                |
| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `config/agentic/orchestrator/agents.yaml`                              | Remove the `execution_mode: interactive` field and the `interactive:` block. The interactive config values (checkpoint intervals, watchdog settings, etc.) should be moved to a new flat `supervisor:` or `execution:` block — or retained under `runtime:` without the mode qualifier — so they remain configurable. See §2 for the preferred restructure. |
| `config/agentic/orchestrator/schemas/agents.schema.json`               | Remove `execution_mode` enum field from the runtime properties.                                                                                                                                                                                                                                                                                             |
| State schema (`config/agentic/orchestrator/schemas/state.schema.json`) | Remove `execution_mode` from the front matter properties. Remove `checkpoints` array only if it is exclusively populated in interactive mode and no longer needed; otherwise retain.                                                                                                                                                                        |
| `config/agentic/orchestrator/defaults/policy.defaults.yaml`            | Remove any `execution_mode` references if present.                                                                                                                                                                                                                                                                                                          |

### 1.6 Analytics / Worker Event Journal

The `execution_mode` field appears in worker runtime event payloads in `supervisor/worker-decision-loop.ts` (line ~959). Options:

- **Preferred:** Remove the field entirely from the event schema and from `appendWorkerRuntimeEvent` calls.
- **Acceptable:** Hardcode to `'interactive'` if downstream tooling (dashboard, analytics) depends on the field being present.

The spec leaves this to the implementing agent's discretion, but the implementing agent must choose one option and apply it consistently.

---

## 2. agents.yaml Config Restructure

The current structure nests execution config under the mode name:

```yaml
runtime:
  execution_mode: interactive
  interactive:
    checkpoint_interval_ms: 30000
    watchdog_poll_interval_ms: 2000
    max_uncommitted_changes: 50
    validation_on_checkpoint: true
    revert_on_violation: false
    violation_severity: warning
```

After removal, the mode qualifier is no longer meaningful. Restructure to:

```yaml
runtime:
  execution:
    checkpoint_interval_ms: 30000
    watchdog_poll_interval_ms: 2000
    max_uncommitted_changes: 50
    validation_on_checkpoint: true
    revert_on_violation: false
    violation_severity: warning
```

The `resolveInteractiveExecutionConfig()` method in `supervisor/runtime.ts` must be updated to read from `runtime.execution` instead of `runtime.interactive`. The config key names remain unchanged.

The corresponding section in `agents.schema.json` must be updated to reflect the new path.

---

## 3. Documentation Updates

### 3.1 README.md

| Location                                        | Change                                                                              |
| ----------------------------------------------- | ----------------------------------------------------------------------------------- |
| `run` command flag table                        | Remove the `--execution-mode <deterministic\|interactive>` row.                     |
| `run` command description text                  | Remove the paragraph describing deterministic vs interactive mode semantics.        |
| `resume` command description                    | Remove `--execution-mode` override mention.                                         |
| `agents.yaml` config example block              | Update to remove `execution_mode` field; update `interactive:` key to `execution:`. |
| State schema front matter field table           | Remove `execution_mode` from the optional field list.                               |
| Any inline prose describing the two-mode system | Update to describe a single interactive execution model.                            |

Note: The README also uses "deterministic" to describe the **kernel's state machine** behavior (deterministic state transitions, canonical locks, lexical file ordering). These usages are correct and must **not** be changed.

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

- Remove the section (or table row) describing the `deterministic` vs `interactive` execution mode distinction.
- Remove any architecture diagram labels or notes referencing `--execution-mode` or deterministic worker flow.
- Update descriptions of the supervisor runtime to reflect the single interactive execution model.

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

- Remove invariants or rules that are specific to deterministic mode (e.g. "in deterministic mode the agent must return exactly one JSON object").
- Retain all invariants about checkpoint validation, worktree management, and patch application — these belong to the interactive path which is now the only path.

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

- Remove any canonical implementation example that demonstrates deterministic-mode usage or the `buildDeterministicWorkerPrompt` function.
- If an example showed how to pass `execution_mode: 'deterministic'` in `WorkerRunInput`, delete it.

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

Add a new ADR entry:

> **ADR-NNN — Remove Deterministic Execution Mode**
>
> **Status:** Accepted
>
> **Context:** The orchestrator was built with two agent execution models. Deterministic mode (structured JSON in/out) was never used in production. It created a forked code path that had to be maintained in parallel with the interactive path.
>
> **Decision:** Remove deterministic mode entirely. Interactive mode (file-system editing + periodic checkpoint diffs) is now the sole execution model.
>
> **Consequences:** Simplified supervisor, prompt-builder, and type layer. Removes the `--execution-mode` CLI flag. Removes the `ExecutionMode` union type. Follow-on spec M57 handles renaming residual "interactive" qualifiers.

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

- Remove any troubleshooting entries specific to deterministic mode failures (e.g. "agent returned non-JSON output in deterministic mode").
- Retain all troubleshooting guidance about checkpoint violations, worktree conflicts, and interactive-mode watchdog timeouts — these remain relevant.

### 3.7 `NEXT-TASKS.md`

- Remove any outstanding tasks that reference the deterministic execution path or the `--execution-mode` flag.

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

- Append a new numbered entry when M56 implementation is complete, per the standard entry format.

---

## 4. Test Updates

### 4.1 Tests to Delete

- Any test that sets `execution_mode: 'deterministic'` in `WorkerRunInput` or supervisor options.
- Any test that exercises `buildDeterministicWorkerPrompt()` directly.
- Any test that exercises the deterministic branch of `buildWorkerPrompt()`.
- Any test that verifies the `--execution-mode deterministic` CLI flag is parsed and forwarded.

### 4.2 Tests to Update

- Tests that set `execution_mode: 'interactive'` explicitly should have that field removed from their input objects (since the field no longer exists).
- Tests for `WorkerDecisionLoop` that mock `resolveExecutionMode` should remove that mock; the loop no longer accepts or calls it.
- Tests for `SupervisorRuntime` that pass `execution_mode` in supervisor options should remove the field.
- Tests for `cli-argument-parser.ts` that assert `--execution-mode` is parsed should be deleted.
- Tests for the agents.yaml config reader that assert `runtime.interactive.*` fields are read should be updated to read from `runtime.execution.*`.

### 4.3 Coverage Requirement

All coverage thresholds (90% lines/branches/functions/statements) must pass after deletions. Deleted code does not need compensating tests. Any net-new code introduced by restructuring (§2) must be covered.

---

## 5. Out of Scope

The following are **not** part of this spec and are deferred to M57:

- Renaming `interactiveOutcome`, `supportsInteractiveMode`, `isInteractiveEligible`, `InteractiveExecutionConfig`, `interactiveConfig`, `INTERACTIVE_CHECKPOINT_INVALID`, `INTERACTIVE_NO_NEW_WORK`, `runInteractive()`, and related identifiers.
- Any refactoring of `CheckpointService`, `WorktreeWatchdogService`, or related interactive infrastructure beyond what is required to remove the mode-selection branch.
- Dashboard / web UI changes.

---

## 6. Acceptance Criteria

| #   | Criterion                                                                   | Verification                                                                                  |
| --- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| 1   | `ExecutionMode` type no longer exists anywhere in `apps/control-plane/src/` | `grep -r "ExecutionMode" apps/control-plane/src/` returns no matches                          |
| 2   | `buildDeterministicWorkerPrompt` no longer exists                           | `grep -r "buildDeterministicWorkerPrompt" apps/` returns no matches                           |
| 3   | `--execution-mode` flag no longer parsed by the CLI                         | `grep -r "execution-mode" apps/control-plane/src/cli/` returns no matches                     |
| 4   | `agents.yaml` contains no `execution_mode` field                            | `grep "execution_mode" config/agentic/orchestrator/agents.yaml` returns nothing               |
| 5   | State schema contains no `execution_mode` property                          | `grep "execution_mode" config/agentic/orchestrator/schemas/state.schema.json` returns nothing |
| 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                                      | ✅                                                                                            |
| 10  | README no longer documents `--execution-mode` flag                          | Manual review                                                                                 |
| 11  | `docs/core/DECISIONS.md` contains the removal ADR                           | Manual review                                                                                 |

---

## 7. Risks

| Risk                                                                                         | Likelihood           | Mitigation                                                                                                                                       |
| -------------------------------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| A test or config still references `execution_mode: 'deterministic'` after deletion           | Low                  | Acceptance criterion #1 uses grep to catch stragglers. Run `grep -r "deterministic" apps/` post-implementation to catch any residual references. |
| `runtime.execution.*` config path change breaks an existing reader                           | Medium               | Update the `resolveInteractiveExecutionConfig()` reader and its tests in the same PR. Validate with `npm run test`.                              |
| Dashboard or analytics pipeline depends on `execution_mode` field in event payloads          | Low (pre-production) | Check `packages/web-dashboard/` for any field reads before removing from event schema.                                                           |
| Accidental removal of "deterministic" references that describe kernel state-machine behavior | Low                  | README and ARCHITECTURE updates must be reviewed against the rule in §3.1: only execution-mode usages are in scope.                              |
