# Repository Agent Guidance

## Where to work right now (read this first)

- **Repo:** `Hmbown/CodeWhale`. This repo lives on multiple devices, so work in
  whichever local checkout you have — keep paths here device-agnostic and always
  **confirm with `git branch --show-current` before editing.**
- **Active branch:** start from live truth. Confirm the current fix/integration
  branch from the latest handoff/objective file and `git branch --show-current`;
  recent work has landed on `main` through small PRs rather than a long-lived
  `codex/...` integration branch, so verify a named integration branch still
  exists before relying on it.
- **Workspace version:** read it from `Cargo.toml` (`[workspace.package]
  version`); it advances per release lane, so treat that file as the source of
  truth over any memorized number. Bump versions deliberately, keeping a bump to
  its own commit.
- **Milestone guidepost:** use the current release milestone named in the active
  handoff and list it live, e.g.
  `gh issue list --repo Hmbown/CodeWhale --milestone "<current milestone>" --state open`.
- **Default branch is `main`.** Committing directly to `main` is fine for
  release-lane work — keep each commit to one reviewable concern with a real
  body. A fresh `codex/...` branch or worktree is still the right call for an
  isolated or risky change, opened as a PR when that reads better for review.
- **Always run before pushing a change:** `cargo fmt`, then the targeted tests
  for the area (`cargo test -p codewhale-tui --bin codewhale-tui --locked <filter>`,
  `cargo test -p codewhale-config`, `cargo test -p codewhale-protocol`, …). Full
  gate: `cargo test --workspace`. Release build:
  `cargo build --release -p codewhale-cli -p codewhale-tui`.
- **Known suite papercuts (pre-existing, not regressions):**
  `run_verifiers_background_*` is flaky under full-suite parallelism but passes
  in isolation. Attribute it to the known flake, not to your change. (The old
  `config_command_allow_shell_*` failures on machines with
  `default_mode = "yolo"` were fixed by pinning the command-test app to
  Agent mode.)

## Continuous agent work conventions

- One concern per commit; write a real commit body. Keep unrelated changes in
  separate commits.
- Commit as **WIP** unless you have actually verified the behavior (built the
  binary, ran the test, reproduced the fix). Stating "fixed" without evidence is
  worse than an honest WIP.
- Build only on the surfaces that exist today (removed machinery stays gone):
  the model-facing sub-agent surface is **`agent` only** — the
  `agent_open`/`agent_eval`/`agent_close`/`delegate_to_agent` variants,
  capacity/coherence/runtime-tag systems, lifecycle tools, and runtime prompt/tag
  injection were all removed. `constitution.md` is the sole base prompt.
- Configurable sub-agent depth stays. Add a new limit only when it's clearly
  needed, and explain why.
- **Do-not-delete guardrail** (salvaged from the 0.8.68 handoff; these were
  repeatedly misflagged as dead code and deleting them broke the build):
  `tui/src/memory.rs`, `tui/src/context_budget.rs`,
  `tui/src/model_registry.rs`, `tui/src/prompt_zones.rs`,
  `tui/src/tools/remember.rs`, and the entire `config/src/route/` directory
  are all actively imported. Verify consumers with `rg` before believing any
  dead-code audit.
- The sub-agent **TUI freeze reported in older handoffs is resolved** by the
  v0.8.61 cutover (cap-20, persist-debounce, AgentProgress redraw throttle,
  ListSubAgents coalescing, input-pump-off-render-thread). The leading
  "blocking I/O starves the worker pool" theory was measured and **disproven**
  (`git rev-parse` ~10ms, 18-core machine). Treat the freeze as closed and spend
  effort elsewhere rather than on a speculative `spawn_blocking` fix.

## CodeWhale Stewardship

- Treat community contributors as partners. Good-faith PRs, issue reports,
  repros, logs, reviews, and verification comments are maintainer evidence,
  not queue noise.
- Keep gates warm and dry-run unless Hunter explicitly approves enforcement.
  Gate copy should guide contributors clearly and respectfully.
- Credit every harvested PR, issue report, or comment that materially shaped a
  fix. Preserve authorship when possible; otherwise use mappable GitHub
  noreply `Co-authored-by` trailers from `.github/AUTHOR_MAP`.
- CodeWhale started as a DeepSeek-only harness; it's now about building the
  greatest possible coding harness with the help of an open-source community.
  Keep CodeWhale branding and every model/provider first-class — none
  privileged. When retiring legacy names like `deepseek-tui`, keep it clear that
  every model and provider stays fully supported.
- Review PRs from code, tests, linked issues, comments, and check results — let
  those, rather than the title or labels alone, drive every merge, close,
  harvest, or defer decision on community work.
- Respect concurrent work in the tree — leave unrelated edits by other people or
  agents intact.

## Release PR Integration

- Use scratch integration branches when triaging a crowded release queue. A
  branch such as `scratch/vX.Y.Z-pr-train-YYYYMMDD` may merge or cherry-pick
  many PR heads to expose conflicts, missing tests, duplicate work, and hidden
  coupling quickly.
- Treat scratch branches as evidence, not as the artifact to ship. Land work by
  harvesting the safe resolved hunks or commits back into the release branch in
  narrow, reviewable commits — keep tags, releases, and fast-forwards off the
  scratch train.
- Prefer direct GitHub merge only when the PR is clean against the real landing
  branch, has acceptable checks, and does not cross trust-boundary surfaces. A
  PR that is clean against `main` can still conflict with a release branch; test
  against the actual release head before calling it merge-ready.
- For already approved PRs, start with a scratch merge against the release
  branch, then decide between direct merge, cherry-pick with conflict
  resolution, or credited harvest. Maintainer approval is a priority signal,
  not permission to skip review or tests.
- When harvesting, preserve or add machine-readable credit: keep the original
  author where possible, add `Co-authored-by` using `.github/AUTHOR_MAP` or
  GitHub numeric noreply identity, and include `Harvested from PR #N by
  @handle` in the commit body so the auto-close workflow can close the PR with
  credit after it reaches `main`. Merge a PR whose commit carries that line
  with rebase or a merge commit so the body survives intact — a squash can
  rewrite it, drop the `Harvested from PR` line, and silently lose both the
  machine-readable credit and the auto-close.
- Keep `Co-authored-by` trailers to human contributors —
  `scripts/check-coauthor-trailers.py` rejects bot/tool ones (Claude, codex,
  cursor, `noreply@anthropic.com`) on harvest commits. Also refresh the manual
  credit surfaces that do not auto-populate from trailers: `docs/CONTRIBUTORS.md`
  and `CHANGELOG.md`.
- Close or update issues and PRs only after verifying the landed commit on the
  relevant branch. If the release branch already contains equivalent behavior,
  leave a clear note linking the commit and describing any remaining delta.
- For the active release queue, start from the current GitHub release milestone
  named in the active handoff
  (`gh issue list --repo Hmbown/CodeWhale --milestone "<current milestone>"`) and
  refresh state before acting. Older per-version triage docs under `docs/` are
  historical reference only.

## Cursor Cloud specific instructions

Standard build/test/run commands are already documented above and in
`CONTRIBUTING.md`; this section only records the non-obvious cloud-VM caveats.

- **System build dep:** the build needs `libdbus-1-dev` (pulled in by
  `crates/secrets` for the OS keyring). It is installed by the startup update
  script; if a `cargo build` fails with a `dbus`/`pkg-config` error, that dep is
  missing.
- **`rustup default` must be set:** some tests and runtime paths spawn shells in
  temp dirs *outside* this checkout (e.g. `run_verifiers_background_*`, sub-agent
  worktrees). Those spawned shells only see the repo's `rust-toolchain.toml`
  override while inside `/workspace`, so without a global default they fail with
  "rustup could not choose a version of rustc to run". The update script runs
  `rustup default stable` to fix this.
- **Known env-specific test failures at `/workspace` (not code bugs):** because
  the checkout sits directly under `/`, two `codewhale-tui` subagent tests fail
  here — `git_repo_root_reports_attempted_paths_when_no_repo_found` (cannot
  create a temp dir in the unwritable parent `/`) and
  `create_isolated_worktree_reports_friendly_error_when_no_repo_found` (walking
  up to `/` discovers `/workspace` itself as a repo). Both pass when the repo is
  checked out under a normal, writable parent. `run_verifiers_background_*` is
  the separate pre-existing flake already noted above. Everything else in
  `cargo test --workspace` passes (~6384 tests).
- **Running the agent without provider API keys:** point CodeWhale at any local
  OpenAI-compatible endpoint via the keyless `vllm`/`ollama`/`sglang` providers,
  e.g. `CODEWHALE_PROVIDER=vllm VLLM_BASE_URL=http://127.0.0.1:8000/v1
  VLLM_MODEL=<id> codewhale exec --auto "..."`. `codewhale exec` (add `--auto`
  for tool use) is the non-interactive path to exercise the full agent loop.
- **Dispatcher needs its sibling:** the `codewhale` binary shells out to a
  sibling `codewhale-tui` in the same directory (both land in `target/debug`
  after a build). If they are not co-located, set `DEEPSEEK_TUI_BIN` to the
  `codewhale-tui` path.