Refresh repo agent guidance around live state

AGENTS.md

@@ -1,103 +1,129 @@
 # Repository Agent Guidance
 
-## Where to work right now (read this first)
-
-- **Repo:** `Hmbown/CodeWhale`. This repo lives on multiple devices, so do
-  **not** hard-code a device-specific checkout path here — work in whichever
-  local checkout you have and always **confirm with
-  `git branch --show-current` before editing.**
-- **Active branch:** `codex/v0.8.63-integration` (also at
-  `origin/codex/v0.8.63-integration`) for the current fix/integration lane.
-  If a newer handoff or objective file names a different branch, verify with
-  `git branch --show-current` and follow the live branch.
-- **Workspace version is `0.8.63`** in `Cargo.toml`. Do not bump versions
-  opportunistically; version bumps, tags, release artifacts, publishing, and
-  GitHub Releases require Hunter's explicit approval.
-- **Milestone guidepost:** GitHub milestone `v0.8.63`. Check live state with
-  `gh issue list --repo Hmbown/CodeWhale --milestone "v0.8.63" --state open`.
-- **Default branch is `main`.** Never commit directly to `main`; work on the
-  active integration branch or a fresh `codex/...` branch/worktree off it for
-  an isolated change. Open a PR into `main` only when a unit of work is
-  reviewable.
-- **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):**
-  `config_command_allow_shell_*` fail on machines whose `~/.codewhale/settings.toml`
-  sets `default_mode = "yolo"` (the tests aren't hermetic); `run_verifiers_background_*`
-  is flaky under full-suite parallelism but passes in isolation. Don't treat
-  these as caused by your change.
-
-## Continuous agent work conventions
-
-- One concern per commit; write a real commit body. Don't squash unrelated
-  changes.
-- 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.
-- Don't reintroduce removed machinery: the model-facing sub-agent surface is
-  **`agent` only** (no `agent_open`/`agent_eval`/`agent_close`/`delegate_to_agent`
-  /etc.); no capacity/coherence/runtime-tag systems; no lifecycle tools; no
-  runtime prompt/tag injection. `constitution.md` is the sole base prompt.
-- Configurable sub-agent depth stays. No arbitrary new limits unless clearly
-  needed and explained.
-- 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). Do not commit a speculative
-  `spawn_blocking` fix for the freeze.
-
-## 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`.
-- Do not tag, publish, create a GitHub Release, or push release artifacts
-  without Hunter approval.
-- Use CodeWhale branding while keeping DeepSeek support first-class. Retiring
-  legacy `deepseek-tui` names must never read as deprecating DeepSeek models or
+## Start With Live Truth
+
+This repo moves through release and integration lanes quickly. Do not rely on a
+hard-coded branch, milestone, or version in this file. Before editing, establish
+the current lane from live state:
+
+```sh
+git status --short --branch
+git branch --show-current
+git fetch origin main --prune --no-tags
+gh issue list --repo Hmbown/CodeWhale --state open --limit 100 --json number,title,labels,milestone,updatedAt,url
+gh pr list --repo Hmbown/CodeWhale --state open --limit 100 --json number,title,headRefName,baseRefName,isDraft,url
+```
+
+Use the user's current goal, live GitHub milestones, open PRs, and the current
+branch as the source of truth. If local notes or old handoffs disagree with live
+state, trust live state and mention the mismatch in your handoff.
+
+## Branch And Release Safety
+
+- Never commit directly to `main`.
+- Work on the active integration branch or create a focused branch such as
+  `issue/<number>-short-slug` from the correct live base.
+- Keep each branch scoped to one issue or one reviewable concern unless issues
+  are genuinely inseparable.
+- Do not bump versions, tag, publish, create GitHub Releases, or push release
+  artifacts without Hunter's explicit approval.
+- Merge to `main` only when the current user goal or handoff authorizes landing
+  the lane, or Hunter explicitly approves that PR/queue. If merge approval is
+  ambiguous, ask before merging; do not use ambiguity as an excuse to leave an
+  already-authorized queue unmerged.
+- Preserve unrelated dirty or untracked files. Do not revert work you did not
+  make.
+
+## Working A GitHub Issue
+
+1. Refresh live issue and PR state.
+2. Check whether an open PR already covers the issue.
+3. Inspect the issue body, linked PRs, comments, code, docs, and tests before
+   deciding what to change.
+4. Implement the smallest coherent slice that moves the issue toward done.
+5. Format, run targeted tests, commit, push, and open a PR. Use draft only while
+   the branch is still under active validation; open or convert to ready once
+   the branch is locally verified and reviewable.
+6. In the PR body include goal, changes, verification commands/results, risks,
+   and the linked issue.
+7. Carry the issue to a terminal disposition: merged and verified, closed as
+   already fixed with evidence, or blocked with a precise blocker comment.
+
+If the issue is already fixed, verify it from current code or CI before
+commenting or closing. If blocked, leave a precise comment with the blocker,
+attempted work, branch or commit if any, and next action.
+
+## PR Completion Loop
+
+Opening a PR is not the deliverable. The deliverable is landed code, a verified
+closure, or a documented blocker. Every agent-owned PR needs an explicit
+completion pass:
+
+1. Read back the PR body, diff, commits, linked issue, and CI/check status.
+2. If checks fail, fix the branch or leave a precise blocker comment.
+3. If the branch is verified and reviewable, remove draft status. Do not leave
+   verified work in draft because the next step is uncomfortable.
+4. When the lane is merge-authorized, merge green, scoped, reviewable PRs
+   instead of letting them pile up. Prefer the repository's normal merge method
+   and preserve contributor credit.
+5. After merge, verify the landed commit on the target branch, then update or
+   close linked issues with a short evidence-based comment.
+6. Before starting another issue, check whether your existing PRs need a
+   ready/merge/issue-cleanup pass.
+
+Do not merge just because a PR exists. Merge only after scope, tests, CI,
+review state, issue linkage, and the user's current approval posture all support
+it. If the user asks to work through a release, milestone, or issue queue,
+include ready/merge/issue-cleanup work in the normal plan instead of only
+opening more PRs.
+
+## Verification Defaults
+
+Run `cargo fmt` before pushing Rust changes. Then run the targeted tests for the
+area you touched, for example:
+
+```sh
+cargo test -p codewhale-tui --bin codewhale-tui --locked <filter>
+cargo test -p codewhale-config --locked <filter>
+cargo test -p codewhale-protocol --locked <filter>
+```
+
+Use broader gates when the change crosses crate boundaries:
+
+```sh
+cargo test --workspace
+cargo build --release -p codewhale-cli -p codewhale-tui
+```
+
+Known local-suite papercuts should be verified before blaming a new change.
+Historically, config command tests can be affected by non-hermetic user config,
+and some verifier background tests have been flaky under full-suite parallelism
+while passing in isolation.
+
+## Architecture And Product Guardrails
+
+- Keep CodeWhale branding while preserving first-class DeepSeek model and
   provider support.
-- Review PRs from code, tests, linked issues, comments, and check results.
-  Never merge, close, harvest, or defer community work from title or labels
-  alone.
-- Respect concurrent work in the tree. Do not revert or rewrite unrelated
-  edits by other people or agents.
-
-## Release PR Integration
-
-- Use scratch integration branches when triaging a crowded release queue. A
-  branch such as `scratch/v0.8.59-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. Do not tag,
-  release, or fast-forward a release branch from a scratch train. Harvest the
-  safe resolved hunks or commits back into the release branch in narrow,
-  reviewable commits.
-- 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`.
-- 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 GitHub `v0.8.63` milestone
-  (`gh issue list --repo Hmbown/CodeWhale --milestone "v0.8.63"`) and refresh
-  state before acting. Older per-version triage docs under `docs/` are
-  historical reference only.
+- Do not reintroduce removed model-facing sub-agent tool names. The current
+  model-facing sub-agent surface is `agent`.
+- Avoid speculative runtime systems such as capacity/coherence tags, lifecycle
+  tools, or prompt/tag injection unless the current issue explicitly calls for a
+  reviewed design.
+- Prefer provider/model/Fleet changes that separate provider facts, model facts,
+  offerings, route resolution, and runtime readiness.
+- Treat provider docs and hosted model catalogs as time-sensitive. When current
+  provider behavior matters, check the actual provider docs or API and add tests
+  or drift checks where practical.
+- Website work should be sparse, calm, and accurate. Prefer a simple product
+  and docs surface over busy marketing sections; keep public claims tied to
+  current repo/runtime facts and provider documentation.
+
+## Stewardship
+
+- Treat community reports and PRs as maintainer evidence. Review code, tests,
+  linked issues, comments, and check results before merging, harvesting,
+  closing, or deferring.
+- Preserve contributor credit for harvested work with authorship when possible,
+  `Co-authored-by` trailers where appropriate, and clear PR/issue references.
+- Keep gates helpful and dry-run unless Hunter approves enforcement.
+- Keep public wording neutral for local hardening and internal reliability work.

CLAUDE.md

@@ -1,60 +1,53 @@
 # Claude Repository Guidance
 
-Read `AGENTS.md` first. This file exists as a compatibility instruction source
+Read `AGENTS.md` first. This file exists only as a compact compatibility layer
 for Claude-based agents working in this repository.
 
-## Stewardship Defaults
-
-- Treat community PRs and issues as maintainer evidence. Inspect code, tests,
-  linked issues, comments, and CI before merging, harvesting, closing, or
-  deferring work.
-- Do not tag, publish, create a GitHub Release, or push release artifacts
-  without Hunter's explicit approval.
-- Keep CodeWhale branding while preserving first-class DeepSeek model/provider
-  support and legacy migration care.
-- Preserve contributor credit for harvested work with authorship,
-  `Co-authored-by`, `Harvested from PR #N by @handle`, and changelog/release
-  notes where applicable.
-
-## Scratch Integration Branches
-
-- For release queues, create disposable local branches from the real landing
-  branch, for example `scratch/vX.Y.Z-pr-train-YYYYMMDD`.
-- Use the scratch branch to merge or cherry-pick candidate PR heads in batches
-  and learn which conflicts, tests, and overlaps are real.
-- Do not ship the scratch branch itself. It may contain noisy merge commits,
-  partial conflict resolutions, and unrelated PR interactions.
-- After the scratch experiment, move only the safe result back to the release
-  branch as narrow commits or direct merges. Keep each final commit explainable
-  and testable.
-- A PR that is clean against `main` is not necessarily clean against a release
-  branch. Test mergeability against the branch that will actually receive the
-  work.
-- For already approved PRs, treat approval as a strong priority signal. Still
-  inspect diffs, comments, check results, and release-branch conflicts before
-  landing.
-
-## Current Release Work
-
-- The active branch for this release lane is `codex/v0.8.63-integration`
-  (also at `origin/codex/v0.8.63-integration`). This repo lives on multiple
-  devices, so do not hard-code a checkout path; work in whichever local
-  checkout you have and confirm with `git branch --show-current` before
-  editing. Never commit directly to `main`.
-- The workspace version is `0.8.63`. Do not tag, publish, create a GitHub
-  Release, push release artifacts, or merge to `main` without Hunter's
-  explicit approval.
-- Base release triage on the GitHub `v0.8.63` milestone
-  (`gh issue list --repo Hmbown/CodeWhale --milestone "v0.8.63" --state open`)
-  unless Hunter gives a newer branch/milestone.
-- Work the queue in this order: release blockers, recently approved PRs, clean
-  PRs with small scope, blocked PRs with obvious fixes, dirty PRs that can be
-  harvested safely, then larger architecture issues.
-- Prefer batching PR conflict discovery on scratch branches, then harvesting
-  reviewed, credited, tested slices back into the release branch.
-- Before claiming an issue is done, verify whether the branch already contains
-  equivalent work. If it does, prepare the GitHub note/closure path instead of
-  reimplementing it.
-- See `AGENTS.md` → "Where to work right now" for build/test commands, known
-  suite papercuts, and the removed-machinery guardrails (agent-only surface,
-  no lifecycle/coherence systems).
+## Current Lane
+
+Do not use this file to determine the current branch, release, or milestone.
+CodeWhale release lanes move quickly. Derive the current lane from:
+
+- the user's current goal or handoff,
+- `git status --short --branch`,
+- `git branch --show-current`,
+- live GitHub issues, milestones, and PRs,
+- CI/check state on the relevant branch or PR.
+
+If those sources disagree, trust live state and call out the mismatch.
+
+## Core Rules
+
+- Never commit directly to `main`.
+- Do not tag, publish, create GitHub Releases, or push release artifacts without
+  Hunter's explicit approval.
+- Merge only when the current user goal or handoff authorizes landing the lane,
+  or Hunter explicitly approves that PR/queue. If merge approval is ambiguous,
+  ask before merging.
+- Preserve unrelated dirty work.
+- Keep each branch and PR narrowly reviewable.
+- Inspect linked issues, PRs, comments, code, tests, and CI before claiming work
+  is fixed or safe to close.
+- Keep CodeWhale branding while preserving first-class DeepSeek provider/model
+  support.
+- Preserve contributor credit when harvesting or splitting community work.
+
+## Workflow
+
+For active issue or release work, follow `AGENTS.md`:
+
+1. Refresh live state.
+2. Check for existing PR coverage.
+3. Create or switch to the correct focused branch.
+4. Implement a coherent slice.
+5. Run formatting and targeted tests.
+6. Commit, push, and open a PR with goal, changes, verification, risks, and
+   issue linkage. Use draft only while the branch is still being validated.
+7. Revisit the PR after CI. Fix failures, mark verified branches ready for
+   review, merge when the lane is authorized to land, and update or close linked
+   issues only after verifying the landed commit.
+8. Treat merged, verified closure, or documented blocker as the terminal state;
+   do not treat an open PR as finished work.
+
+Use scratch integration branches only for learning conflicts or coupling. Do
+not ship scratch branches directly.