diff --git a/AGENTS.md b/AGENTS.md index edf71e907..819c3f220 100644 --- a/AGENTS.md +++ b/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 `, - `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, 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 +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. +- 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. diff --git a/CLAUDE.md b/CLAUDE.md index 84b81967d..69e17f701 100644 --- a/CLAUDE.md +++ b/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.