From e8d96dea16a7dc236723173cace92afa36c68adc Mon Sep 17 00:00:00 2001 From: Hunter B Date: Mon, 22 Jun 2026 22:48:32 -0700 Subject: [PATCH 1/3] Refresh agent guidance around live state Remove stale hard-coded release branch, version, and milestone references from the repo guidance files. Make live GitHub state, the current branch, CI, and the user's active goal the source of truth for release and issue work. Keep only durable branch safety, verification, stewardship, provider/model, and release approval guardrails. Verification: - git diff --check --- AGENTS.md | 191 ++++++++++++++++++++++++++---------------------------- CLAUDE.md | 93 +++++++++++--------------- 2 files changed, 130 insertions(+), 154 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index edf71e907..db2f990ba 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,103 +1,94 @@ # 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 `, - `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/-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, push release + artifacts, or merge to `main` without Hunter's explicit approval. +- 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 draft PR. +6. In the PR body include goal, changes, verification commands/results, risks, + and the linked issue. + +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. + +## 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 +cargo test -p codewhale-config --locked +cargo test -p codewhale-protocol --locked +``` + +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. + +## 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. diff --git a/CLAUDE.md b/CLAUDE.md index 84b81967d..0de69ec3b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,60 +1,45 @@ # 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 +## Current Lane -- 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 +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, push release artifacts, or merge 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). +- 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 draft PR with goal, changes, verification, risks, + and issue linkage. + +Use scratch integration branches only for learning conflicts or coupling. Do +not ship scratch branches directly. From 454602725869c0d52e45a28fc3e138588152f94b Mon Sep 17 00:00:00 2001 From: Hunter B Date: Mon, 22 Jun 2026 22:51:58 -0700 Subject: [PATCH 2/3] Add PR completion loop to agent guidance Document that opening a draft PR is not the end of an issue workflow. Add explicit readback, CI, ready-for-review, merge-when-authorized, and issue cleanup steps so release agents do not leave verified work piled up in drafts. Also capture the current website direction as sparse, calm, and fact-tied rather than busy marketing copy. Verification: - git diff --check --- AGENTS.md | 26 +++++++++++++++++++++++++- CLAUDE.md | 3 +++ 2 files changed, 28 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index db2f990ba..ff4bd41d2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -37,7 +37,8 @@ state, trust live state and mention the mismatch in your handoff. 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 draft PR. +5. Format, run targeted tests, commit, push, and open a draft PR while the work + is still under active validation. 6. In the PR body include goal, changes, verification commands/results, risks, and the linked issue. @@ -45,6 +46,26 @@ 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 finish line. 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 no longer needs draft protection, mark it + ready for review or say why it must remain draft. +4. When Hunter has authorized merge for the current lane, merge green, + 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. + +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 explicitly asks to advance the lane, include ready/merge/issue +cleanup work in the plan instead of only opening more PRs. + ## Verification Defaults Run `cargo fmt` before pushing Rust changes. Then run the targeted tests for the @@ -82,6 +103,9 @@ while passing in isolation. - 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 diff --git a/CLAUDE.md b/CLAUDE.md index 0de69ec3b..84f99019e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -40,6 +40,9 @@ For active issue or release work, follow `AGENTS.md`: 5. Run formatting and targeted tests. 6. Commit, push, and open a draft PR with goal, changes, verification, risks, and issue linkage. +7. Revisit the PR after CI. Fix failures, mark verified branches ready for + review, merge when Hunter has authorized merge for the lane, and update or + close linked issues only after verifying the landed commit. Use scratch integration branches only for learning conflicts or coupling. Do not ship scratch branches directly. From 465f585f589f7fe8ea5e7f04bb9475460f761ab0 Mon Sep 17 00:00:00 2001 From: Hunter B Date: Mon, 22 Jun 2026 22:54:14 -0700 Subject: [PATCH 3/3] Make merge completion the normal issue workflow Strengthen repository guidance so agent work targets a terminal disposition instead of stopping at an open PR. Clarify that draft PRs are temporary, verified branches should be made ready, and merge/issue cleanup is part of authorized release or issue queue work. Keep merge guarded by the current user goal or explicit Hunter approval, while preventing ambiguity from becoming a permanent pile of draft PRs. Verification: - git diff --check --- AGENTS.md | 35 +++++++++++++++++++++++------------ CLAUDE.md | 17 +++++++++++------ 2 files changed, 34 insertions(+), 18 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ff4bd41d2..819c3f220 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,8 +25,12 @@ state, trust live state and mention the mismatch in your handoff. `issue/-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, push release - artifacts, or merge to `main` without Hunter's explicit approval. +- 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. @@ -37,10 +41,13 @@ state, trust live state and mention the mismatch in your handoff. 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 draft PR while the work - is still under active validation. +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, @@ -48,23 +55,27 @@ attempted work, branch or commit if any, and next action. ## PR Completion Loop -Opening a PR is not the finish line. Every agent-owned PR needs an explicit +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 no longer needs draft protection, mark it - ready for review or say why it must remain draft. -4. When Hunter has authorized merge for the current lane, merge green, - reviewable PRs instead of letting them pile up. Prefer the repository's - normal merge method and preserve contributor credit. +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 explicitly asks to advance the lane, include ready/merge/issue -cleanup work in the plan instead of only opening more PRs. +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 diff --git a/CLAUDE.md b/CLAUDE.md index 84f99019e..69e17f701 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -19,8 +19,11 @@ 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, push release artifacts, or merge - without Hunter's explicit approval. +- 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 @@ -38,11 +41,13 @@ For active issue or release work, follow `AGENTS.md`: 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 draft PR with goal, changes, verification, risks, - and issue linkage. +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 Hunter has authorized merge for the lane, and update or - close linked issues only after verifying the landed commit. + 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.