# Track Specification: Rename `ai_client.send_result` to `ai_client.send` (sandbox test track)

**Track ID:** `send_result_to_send_20260616`
**Status:** Planned (spec pending user review)
**Priority:** A (sandbox integration test — the first track run end-to-end in the just-built `tier2_autonomous_sandbox_20260616` sandbox)
**Owner:** Tier 2 Tech Lead
**Type:** refactor (mechanical rename; no behavior change)
**Scope:** 38 files modified (6 src/, 29 tests/, 3 docs); 0 files added, 0 files deleted

**Parent tracks:**
- `tier2_autonomous_sandbox_20260616` (shipped 2026-06-16; this is the FIRST track to run in that sandbox)
- `public_api_migration_and_ui_polish_20260615` (the track that REMOVED the legacy `send` and introduced `send_result`; this track reverses that decision)

> **Note on effort estimates:** this spec measures effort by **scope** only (38 files modified, 10 atomic commits, 5 phases).

---

## 0. TL;DR

This is the **first end-to-end test** of the Tier 2 autonomous sandbox built in `tier2_autonomous_sandbox_20260616`. The task itself is mechanical: rename `ai_client.send_result()` back to `ai_client.send()` (reversing the 2026-06-15 `public_api_migration` decision) across `src/`, `tests/`, and 3 current docs. The scope (38 files) is large enough to exercise every layer of the sandbox — bootstrap, branch creation, per-task commits, failcount monitoring, and the report writer — but the task is simple enough that Tier 2 should complete it cleanly on the success path.

**Scope:** 38 files modified, 10 atomic commits, 5 phases.

**Success path:** Tier 2 runs to completion in one shot. Each commit is reviewed by the user (via `git fetch` from main + diff with Tier 1). If the user approves, they merge to main.

**Failure path:** if Tier 2 misses a call site or makes a typo, failcount fires after 3 consecutive test failures. The report writer creates a 7-section markdown report at `C:\Users\Ed\AppData\Local\manual_slop\tier2_failures\send_result_to_send_20260616_<timestamp>.md`. The user is notified via the OpenCode session banner.

---

## 1. Overview

### 1.1 The State Before This Track (as of HEAD)

The public API of `src/ai_client.py` is `send_result()` — introduced in the `public_api_migration_and_ui_polish_20260615` track on 2026-06-15 to replace the legacy `send()`. The migration was driven by the data-oriented error handling convention (the new name signals "returns `Result[T, ErrorInfo]`"). Now, with the Tier 2 autonomous sandbox in place (which can do the rename safely without the user's per-task `permission: ask` prompts), the user wants to revert to the shorter `send` name.

**Audit (per `git grep`):**
- **6 src/ files** reference `send_result`:
  - `src/ai_client.py` — 10 refs (the implementation + docstrings + the function name itself)
  - `src/app_controller.py` — 2 call sites
  - `src/conductor_tech_lead.py` — 1 call site + 1 comment + 1 print
  - `src/mcp_client.py` — 1 docstring example
  - `src/multi_agent_conductor.py` — 1 call site + 1 print
  - `src/orchestrator_pm.py` — 1 call site + 1 print
- **29 test files** reference `send_result` (top 5 by ref count: `test_conductor_engine_v2.py` — 22 refs, `test_orchestrator_pm.py` — 14, `test_ai_loop_regressions_20260614.py` — 12, `test_orchestrator_pm_history.py` — 4, `test_conductor_tech_lead.py` — 8)
- **3 current docs** that describe the public API:
  - `docs/guide_ai_client.md` — 4 refs
  - `docs/guide_app_controller.md` — refs
  - `conductor/code_styleguides/error_handling.md` — 6 refs
- **~25 historical mentions** in `conductor/tracks/*/spec.md`, `conductor/tracks/*/plan.md`, `docs/reports/*` — these document the 2026-06-15 decision and STAY as-is (historical record)

### 1.2 The Goal

Rename `ai_client.send_result` → `ai_client.send` across all 38 active files. After this track:
- `grep -r "send_result" src/ tests/ docs/guide_*.md conductor/code_styleguides/*.md` returns 0 matches
- `grep -r "ai_client.send\b" src/ tests/ docs/guide_*.md` returns the new symbol
- All tests pass (`uv run pytest` — full suite, no env vars)
- No new behavior; pure mechanical rename

### 1.3 What the Sandbox Experiences

This is the **first real use** of the just-built `tier2_autonomous_sandbox_20260616` sandbox. Tier 2 will:

1. **Invoke the slash command** `/tier-2-auto-execute send_result_to_send_20260616` in the Tier 2 sandboxed OpenCode session
2. **Fetch the spec** from `origin/main` (the main repo at `C:\projects\manual_slop\`)
3. **Create a feature branch** `tier2/send_result_to_send_20260616` via `git switch -c` (NOT `git checkout` — banned)
4. **Initialize failcount state** at `<app-data>/tier2/send_result_to_send_20260616/state.json`
5. **Execute the plan** in the order specified below (TDD red/green per commit)
6. **Commit per task** with git notes + plan.md updates
7. **On success:** print a summary, leave the user in the branch
8. **On give-up:** write the failure report and notify

The sandbox enforces 3 layers of bans:
- OpenCode permission system denies `git push*`, `git checkout*`, `git restore*`, `git reset*`
- Windows restricted token limits file access to the clone + app-data dir
- `pre-push` hook refuses all pushes (defense in depth)

The user reviews the branch in the main repo (interactive Tier 1):
```powershell
cd C:\projects\manual_slop
git fetch C:/projects/manual_slop_tier2 tier2/send_result_to_send_20260616
# review the diff
git merge --no-ff tier2/send_result_to_send_20260616
```

---

## 2. Current State Audit (as of HEAD)

### 2.1 Already Implemented (DO NOT re-implement)

- **The `send_result` function in `src/ai_client.py`** — 10 refs including the `def send_result(...)` definition. This is the implementation that gets renamed.
- **The legacy `send()` slot** — was REMOVED on 2026-06-15 in the `public_api_migration_and_ui_polish_20260615` track. The slot is now FREE; the new `send` will fill it.
- **The Tier 2 autonomous sandbox** — built in `tier2_autonomous_sandbox_20260616` (shipped 2026-06-16). This track is the first to run in it.

### 2.2 Gaps to Fill (This Track's Scope)

**Gap 1: Rename the implementation in `src/ai_client.py`.** The function definition `def send_result(...)` and all 10 internal references.

**Gap 2: Rename call sites in 5 other src/ files.** `app_controller.py`, `conductor_tech_lead.py`, `mcp_client.py` (docstring), `multi_agent_conductor.py`, `orchestrator_pm.py`. Each has 1-3 references.

**Gap 3: Rename in 29 test files.** Top 5 by ref count done individually (5 commits); remaining 24 done in 1 batch commit.

**Gap 4: Rename in 3 current docs.** `docs/guide_ai_client.md`, `docs/guide_app_controller.md`, `conductor/code_styleguides/error_handling.md`. These describe the current public API; the new name should be reflected.

**Gap 5: Verify the rename is complete and the test suite passes.** Final `uv run pytest` (no env vars) returns 0 failures.

---

## 3. Goals

- **Rename the symbol** `ai_client.send_result` → `ai_client.send` in all 38 active files. No behavior change.
- **Pass the full test suite** (`uv run pytest`, no env vars) after the rename. 100% green.
- **Exercise the sandbox** end-to-end: bootstrap (already done), branch creation, per-task commits, failcount monitoring (likely a no-op for a clean rename), report writer (no-op for success path), OpenCode permission system, branch review by user, merge to main by user.
- **Demonstrate the success path** — Tier 2 completes in one shot, all 10 commits land, no failcount fires.

## 4. Functional Requirements

### 4.1 The Rename

**FR1.1:** Rename the function definition `def send_result(...)` → `def send(...)` in `src/ai_client.py`. Update all 10 internal references (docstrings, error source strings, monitor component names).

**FR1.2:** Rename call sites in 5 other src/ files (batch commit):
- `src/app_controller.py` — 2 call sites
- `src/conductor_tech_lead.py` — 1 call site + 1 comment + 1 print
- `src/mcp_client.py` — 1 docstring example
- `src/multi_agent_conductor.py` — 1 call site + 1 print
- `src/orchestrator_pm.py` — 1 call site + 1 print

**FR1.3:** Rename in 5 test files (one commit per file, in order of impact):
- `tests/test_conductor_engine_v2.py` (22 refs — highest impact)
- `tests/test_orchestrator_pm.py` (14 refs)
- `tests/test_ai_loop_regressions_20260614.py` (12 refs)
- `tests/test_conductor_tech_lead.py` (8 refs)
- `tests/test_orchestrator_pm_history.py` (4 refs)

**FR1.4:** Rename in remaining 24 test files (single batch commit).

**FR1.5:** Rename in 3 current docs (single commit):
- `docs/guide_ai_client.md`
- `docs/guide_app_controller.md`
- `conductor/code_styleguides/error_handling.md`

### 4.2 TDD Discipline (per the sandbox's contract)

**FR2.1:** The TDD red moment is **Task 1.1** (rename in `src/ai_client.py`). After this commit, the full test suite has many failures (every test that imports or calls `send_result` now fails with `AttributeError: module 'src.ai_client' has no attribute 'send_result'`). Tier 2 confirms this in the test output before proceeding.

**FR2.2:** Each subsequent commit moves the test suite from red toward green. After **Task 1.2** (rename other src/), some test failures clear. After **Task 1.3-1.7** (top 5 tests), more clear. After **Task 1.8** (remaining 24 tests), the full suite is green.

**FR2.3:** Task 1.9 (rename docs) does not affect test results but is committed for consistency.

**FR2.4:** Task 1.10 (final verification) re-runs the full suite to confirm 100% green.

### 4.3 Sandbox Contract

**FR3.1:** Tier 2 uses `git switch -c tier2/send_result_to_send_20260616` to create the feature branch. `git checkout` is banned.

**FR3.2:** Tier 2 uses `git add <specific files>` per commit, not `git add .`. Each commit is one logical change.

**FR3.3:** Tier 2 uses `git commit -m "..."` with a clear message per the project's commit format. The git note is attached with a task summary.

**FR3.4:** Tier 2 monitors failcount after every commit. For a clean rename, the counter should not advance. If it does (e.g., a typo in a rename causes 3 consecutive failures), the report writer fires.

**FR3.5:** Tier 2 does NOT push the branch. The user reviews the branch in main and merges.

### 4.4 Branch Review (user-side)

**FR4.1:** After Tier 2 finishes, the user `cd`s back to `C:\projects\manual_slop` and runs:
```powershell
git fetch C:/projects/manual_slop_tier2 tier2/send_result_to_send_20260616
```

**FR4.2:** The user reviews the diff with Tier 1 (interactive). 10 commits, 38 files modified.

**FR4.3:** On approval, the user runs:
```powershell
git merge --no-ff tier2/send_result_to_send_20260616
```

## 5. Non-Functional Requirements

**NFR1. Behavior preservation:** the rename is mechanical; no behavior change. The same `Result[str, ErrorInfo]` return type, the same error sources, the same provider dispatch.

**NFR2. Test green:** the full `uv run pytest` (no env vars) returns 0 failures after the rename. The sandbox's opt-in tests (TIER2_SANDBOX_TESTS=1) are not affected (they don't use `send_result`).

**NFR3. Commit discipline:** 10 atomic commits, each with a clear message, git note, and plan.md update. The user can review each commit individually.

**NFR4. Sandbox exercised:** the rename touches all 4 of the sandbox's primary mechanisms (branch creation, per-task commits, failcount monitoring, no push). Even if failcount doesn't fire, the contract is exercised.

## 6. Architecture Reference

- **`docs/guide_ai_client.md`** — the current doc for the public API. Gets updated.
- **`conductor/code_styleguides/error_handling.md`** — references the migration target. Gets updated.
- **`conductor/tracks/public_api_migration_and_ui_polish_20260615/spec.md`** — the historical decision this track reverses. STAYS as-is.
- **`docs/guide_tier2_autonomous.md`** — the sandbox user guide. Tier 2 follows this.
- **`docs/reports/TRACK_COMPLETION_tier2_autonomous_sandbox_20260616.md`** — the sandbox's own completion report. Tier 2 reviews this for context.

## 7. Out of Scope

- **Historical archives** (`conductor/tracks/*/spec.md`, `conductor/tracks/*/plan.md`, `docs/reports/*`) — these document the 2026-06-15 decision. They STAY as historical record.
- **The Tier 2 sandbox itself** — that's `tier2_autonomous_sandbox_20260616`, already shipped. This track is a USER of the sandbox, not a modification of it.
- **The app's public API surface** beyond `ai_client.send_result`. No other public API changes.
- **The `conductor/AGENTS.md` file** if it references `send_result` (it's the project's agent-facing mirror of `AGENTS.md`; per its convention, it documents the current state, so update it as part of "current docs").
- **The Manual Slop app's GUI** — no GUI changes; pure code rename.
- **Adding new tests** — the existing test suite is the safety net; no new tests.

---

**Spec ends.** The implementation plan (`plan.md` + `metadata.json` + `state.toml`) follows in this directory.
