# CodeWhale v0.8.68 — Agent Workflow Playbook

> **Status (2026-07-12): Historical.** v0.8.68 shipped on 2026-07-10; this
> playbook's waves are complete. Two things in it remain live and should be
> carried forward, not re-derived: the settled product vocabulary
> (**Fleet = who · Workflow = what order · Lane = running instance ·
> Runtime = where/how**) and the still-open dogfood residuals
> (#4175, #4177, #4178, #4179 — blocked on a completed live tmux stopship run
> with child receipts and a verifier gate).

This document tells autonomous agents how to systematically complete the v0.8.68
release. It pairs with:

- **Milestone:** `v0.8.68` (GitHub milestone #53)
- **Architecture tracker:** issue [#4175](https://github.com/Hmbown/CodeWhale/issues/4175) (Fleet / Workflow / Lane / Runtime)
- **Triage packet:** issue [#4092](https://github.com/Hmbown/CodeWhale/issues/4092)
- **Master checklist:** `CODEWHALE_0_8_68.md` (harness workspace) or tracker in repo root after merge
- **Workflow files:** `workflows/v0868_*.workflow.js`

### Architecture phases (post-stopship product work)

| Phase | Issue | Scope |
|-------|-------|-------|
| 1 | [#4176](https://github.com/Hmbown/CodeWhale/issues/4176) | Lane CLI + Runtime (tmux, worktrees, logs) |
| 2 | [#4177](https://github.com/Hmbown/CodeWhale/issues/4177) | Workflow steps → Fleet roles |
| 3 | [#4179](https://github.com/Hmbown/CodeWhale/issues/4179) | Gates and handoffs between roles |
| Dogfood | [#4178](https://github.com/Hmbown/CodeWhale/issues/4178) | Stopship as fleet-backed lane |

Vocabulary: **Fleet** = who · **Workflow** = what order · **Lane** = running instance · **Runtime** = where/how (tmux, VM, CI).

## Source of truth

- **Implementation base:** `main` — all v0.8.68 fix branches start here. PR #4099
  merged the quick-win cutover; do not use `work/v0.9.0-cutover` or
  `.cw-worktrees/v0867-pr4047`.
- **`codex/0868-next`:** stale reference only. Cherry-pick from it only when a
  specific issue needs a specific commit — never treat it as the active dev branch.
- **Playbook/workflow definitions:** merged in [PR #4163](https://github.com/Hmbown/CodeWhale/pull/4163) on `main`; implementation PRs branch from `main`.

## Defer policy (v0.8.69 / architecture refactors)

Defer v0.8.69 refactors and broad feature lanes unless they **directly unblock**
a stopship issue (#4090, #4093, #4094).

| Category | When | Notes |
|----------|------|-------|
| Stopship (#4090, #4093, #4094) | **Now** | Wave 1 — release-blocking |
| Dogfood regressions (#3986, #3990) | After stopship | Same lane, lower priority |
| Catalog lane (Wave 2) | After stopship green | #4109, #4114–#4119, #4139–#4141, #4184–#4188 |
| Workflow UI lane (Wave 3) | After stopship green | #4038, #4110, #4120–#4135 |
| TUI copy lane (Wave 4) | After stopship green | #4112, #4142–#4148 |
| v0.8.69 refactors / 0.9.0 architecture | **Deferred** | Unless required to fix #4090/#4093/#4094 |

Issues labeled `v0.8.69` still in milestone `v0.8.68` should be reclassified to
DEFER (0.9.0) during sweep unless tied to a stopship fix.

## Quick start

```bash
# 1. Sync and verify branch (implementation always from main)
cd CodeWhale
git fetch origin
git checkout main && git pull origin main
git checkout -b codex/v0868-fix-<issue>   # e.g. codex/v0868-fix-4090
git status -sb

# 2. Board truth
gh issue list -R Hmbown/CodeWhale --milestone "v0.8.68" --state open --limit 200
gh pr list -R Hmbown/CodeWhale --state open --limit 50 \
  --json number,title,isDraft,mergeable,milestone

# 3. Read the triage packet (do not skip)
gh issue view 4092 -R Hmbown/CodeWhale

# 4. Run verification gate before and after changes
cargo fmt --all --check
cargo clippy --workspace --all-features --locked -D warnings \
  -A clippy::uninlined_format_args -A clippy::too_many_arguments \
  -A clippy::unnecessary_map_or -A clippy::collapsible_if -A clippy::assertions_on_constants
cargo test --workspace --locked
cargo build --release -p codewhale-tui
```

## Execution order (waves)

Work top-to-bottom. **Do not start Waves 2–4 or v0.8.69 refactors until stopship
is green** (#4090, #4093, #4094 closed or verified fixed on `main`).

| Wave | Workflow file | Theme | GitHub issues | Status |
|------|---------------|-------|---------------|--------|
| 0 | `v0868_issue_sweep.workflow.js` | Triage + release plan | all milestone | On demand |
| 1 | `v0868_stopship_lane.workflow.js` | Release blockers + dogfood regressions | #4090, #4093, #4094, #3986, #3990 | **Active** |
| 2 | `v0868_catalog_lane.workflow.js` | Model catalog + Models.dev live catalog | #4109, #4114–#4119, #4139–#4141, #4184–#4188 | Deferred |
| 3 | `v0868_workflow_ui_lane.workflow.js` | Workflow orchestration UI | #4038, #4110, #4120–#4135 | Deferred |
| 4 | `v0868_tui_copy_lane.workflow.js` | Transcript/copy polish | #4112, #4142–#4148 | Deferred |
| 5 | `v0868_release_gate.workflow.js` | Final verification + handoff | milestone closeout | After Waves 1–4 |

### Models.dev live catalog chain (Wave 2)

Execute sequentially after stopship is green:

**#4184 → #4185 → #4186 → #4187 → #4188**

| Issue | Scope |
|-------|-------|
| [#4184](https://github.com/Hmbown/CodeWhale/issues/4184) | Models.dev as source of truth for provider/model metadata |
| [#4185](https://github.com/Hmbown/CodeWhale/issues/4185) | Accept current live Models.dev schema in catalog parser |
| [#4186](https://github.com/Hmbown/CodeWhale/issues/4186) | Normalize Models.dev provider IDs onto CodeWhale provider kinds |
| [#4187](https://github.com/Hmbown/CodeWhale/issues/4187) | Fetch and cache live Models.dev catalog into ProviderLake |
| [#4188](https://github.com/Hmbown/CodeWhale/issues/4188) | Demote curated bundled model data after live catalog lands |

Parent tracker: [#4109](https://github.com/Hmbown/CodeWhale/issues/4109).

## How to launch a workflow

Branch from `main` before starting implementation agents:

```bash
git checkout main && git pull origin main
git checkout -b codex/v0868-stopship-<issue>
```

### Fleet-backed stopship lane (dogfood #4178)

Named fleet file: [`fleets/v0868-stopship.toml`](../fleets/v0868-stopship.toml)
(roles: `scout`, `implementer`, `reviewer`, `verifier`, `release_lead`).
Workflow: `workflows/v0868_stopship_lane.workflow.js` (steps bind fleet
`role` — not raw provider/model identity).

**Target shape** (Phase 1 Lane CLI #4176 + Phase 2 role resolution #4177):

```bash
# Create a durable tmux-backed lane bound to stopship + fleet and launch Workflow
codewhale workflow run stopship \
  --issue 4090 \
  --fleet v0868-stopship \
  --runtime tmux \
  --goal "Fix #4090, #4093, #4094. Branch implementation from main."

codewhale lane list
codewhale lane status <lane-id>          # reconciles a finished tmux process
codewhale lane attach <lane-id>          # or: codewhale lane attach <lane-id> --print
codewhale lane logs <lane-id>
codewhale lane stop <lane-id>
```

`workflow run` validates the checked-in Workflow source and named Fleet roster,
creates the Lane record, and invokes the existing Workflow tool directly via
the selected Runtime backend. It does not spend an operator-model turn asking a
model to choose the tool. The Workflow driver resolves each `task({ role })`
through the named fleet before spawning sub-agents and emits live
`workflow_event` NDJSON receipts for run, phase, task, gate, and terminal state.
Inline writes each receipt to the Lane journal as it arrives. The tmux backend
launches a hidden Rust supervisor that frames arbitrary or binary child output
as valid NDJSON, removes its private 0600 JSON environment sidecar before the
child starts, and atomically publishes a separate bounded exit receipt.
`lane status` and `lane list` reconcile that receipt to `completed` or `failed`,
and fail a Lane closed when its tmux session vanished without a receipt. Start,
stop, and reconciliation transitions share a per-Lane lock; a failed or
unverifiable tmux kill leaves the Lane active and never triggers worktree
cleanup. Every tmux Lane also persists an explicit registry-owned server socket
and uses it for start, attach, liveness, and kill operations, so later changes
to `TMUX_TMPDIR` cannot redirect lifecycle commands to the wrong server.
Missing tmux and the not-yet-implemented VM/CI backends fail terminally instead
of reporting a fictional Running Lane.

The public `workflow run` command is the explicit approval of the Workflow
plan envelope and records `approved_explicit_cli_command` in the durable plan
receipt. That approval does not silently grant child shell or full-disk
authority: the host runner preserves the resolved profile/provider/model,
configured `allow_shell`, sandbox, external sandbox, network, and MCP posture.
Only a global `--yolo` request selects bypass/full-authority behavior. Runtime
secrets are bridged outside persisted Lane argv, and an isolated worktree run
resolves its workspace from the Runtime-owned worktree cwd rather than the
original checkout.

Validate fleet role resolution without launching agents:

```bash
# Pure unit path (CI-safe)
cargo test -p codewhale-workflow --lib named_fleet
```

### Direct tool paths

From CodeWhale TUI or the direct headless Workflow entrypoint:

```bash
# Headless stopship lane (deterministic host dispatch)
codewhale workflow run stopship \
  --fleet v0868-stopship \
  --runtime inline \
  --goal "Fix #4090, #4093, #4094. Branch implementation from main."

# Per-issue headless (single stopship issue)
codewhale exec --auto --output-format stream-json \
  "Run workflows/v0868_issue_implement.workflow.js for issue #4090. Branch from main."

# TUI explicit path
/workflow start workflows/v0868_stopship_lane.workflow.js
```

Workflows use read-only scouts first, then implementation agents in sequence.
`workflow run` is an explicit execution command and approves that checked-in
plan envelope; its children still inherit the configured durable-task
permission and sandbox posture. Interactive `/workflow` runs retain their
normal approval surfaces.
Do **not** close #4090/#4093/#4094 until human-verified on `main`.

## Per-issue implementation (single issue)

For one `agent-ready` issue:

1. `gh issue view <N> -R Hmbown/CodeWhale`
2. Confirm issue is in milestone `v0.8.68` and has label `v0.8.68`
3. Run `workflows/v0868_issue_implement.workflow.js` with the issue number in the goal
4. Or use headless: `codewhale exec --auto` with the issue body as prompt
5. Open PR referencing `Fixes #<N>`; do not close issues until merged

Label hygiene for agent execution:

```bash
gh issue edit <N> --add-label agent-in-progress --remove-label agent-ready
# after PR merged:
gh issue close <N> --comment "Fixed in PR #<PR>"
```

## PR harvest lane (parallel to waves)

Review community PRs without squashing authorship. Order from #4092:

| PR | Issue | Notes |
|----|-------|-------|
| #4088 | #4026 | Mergeable; terminal selection highlight |
| #4087 | #4082 | Draft refactor; finish review |
| #4084 | #4065 | Fleet alias cleanup |
| #3761 | #3757 | Conflicting; cherry-pick if needed |
| #3969 | #3965 | Conflicting; align with #4065 first |

## Skills to load

Copy or reference these maintainer skills from `docs/skills/`:

- `gh-compile-issues` — classify done/quick-fix/design/defer with evidence
- `codew-release-qa-sweep` — release gate commands
- `gh-find-prs` — locate related PRs before implementing

## Agent constraints

- **Do not** push to `main`, tag, release, or close issues without explicit approval
- **Do not** force-push or amend pushed commits
- **Do** cite `path:line` evidence for every "done" claim
- **Do** run the verification gate after each wave
- **Do** update issue #4092 with handoff notes when switching agents

## Milestone status (2026-07-07)

- **Source of truth:** `main` (PR #4099 merged — quick-win cutover landed)
- Milestone `v0.8.68` (#53): ~70 open / ~105 total
- Labels: `v0.8.68` synced with milestone membership
- Release blockers: #4093, #4094
- Top dogfood regression: #4090 (Ctrl+C re-prompt)
- **Deferred:** v0.8.69 refactors and Waves 2–4 until stopship green
- **Stale reference only:** `codex/0868-next` — cherry-pick per-commit when needed