feat(project): deprecate WHALE.md; add .codewhale/constitution.json authority layer (v0.8.53)

[Hmbown]

Part of the v0.8.53 cutover. Splits repo-level guidance into two clear artifacts and deprecates the confusing WHALE.md concept (it overlapped with AGENTS.md and sounded like CodeWhale-native authority — which now has a real home).

The model

• AGENTS.md — canonical cross-agent project instructions (prose, for humans and any agent).
• .codewhale/constitution.json — CodeWhale-specific repo authority / prioritization policy (JSON): when local sources conflict, which to trust first, and what to verify before claiming done. .codewhale/ lives inside the repo like .github/. Rendered into the system prompt as a higher-authority <codewhale_repo_constitution> block.
• prompts/base.md — the global CodeWhale Constitution. Unaffected (different thing).
• WHALE.md — deprecated, legacy fallback only.

WHALE.md migration (compat-preserving)

• AGENTS.md now ranks above WHALE.md in both project and global discovery — with both present, AGENTS.md wins (rationale: stop the overlap).
• WHALE.md is still read as a legacy fallback, but now emits a deprecation warning and is never created or recommended (/init no longer suggests it).
• Eventual removal from default discovery is left for a future release (point 7 of the migration plan) — not done here.

constitution.json

• New RepoConstitution (serde; all fields optional; unknown fields ignored; schema_version checked with a best-effort warning on mismatch). Discovered at .codewhale/constitution.json in the workspace or any parent up to the git root. Malformed JSON warns, never panics. Loaded after the auto-generate fallback so it can't be clobbered.
• .gitignore: ignore .codewhale/ contents at any depth except the committed constitution.json (a directory exclude can't be negated, so **/.codewhale/* + !**/.codewhale/constitution.json). init.rs writes the same pattern for new repos. This repo's own .codewhale/constitution.json added as dogfood.
• find_git_root made pub(crate) and reused — no duplicate loader.

Files

crates/tui/src/project_context.rs, project_doc.rs, commands/init.rs, docs/CONFIGURATION.md, .gitignore, .codewhale/constitution.json.

Verification

• cargo test -p codewhale-tui --bins → 3946 passed, 0 failed. New tests: AGENTS-over-WHALE precedence, WHALE legacy-read-with-deprecation-warning, constitution render + system-block surfacing, malformed-constitution warns-not-crashes, gitignore-keeps-constitution.
• cargo clippy -p codewhale-tui --bins → clean.

Notes / not in this PR (tracked as follow-ups)

• Removing the silent auto-generation of .codewhale/instructions.md (an agent suggested /init should be the only thing that writes instruction files) — deliberately not changed here to keep the PR focused; tracked as a follow-up.
• Aligns with the design in PR docs: v0.8.53 tool-surface-diet design + north-star direction (#2681, #2680) #2686 (docs/VISION_NORTH_STAR.md command-surface taxonomy: /memory small, /context dashboard, /rules, .codewhale/constitution.json authority).

🤖 Generated with Claude Code

[greptile-apps]

Hmbown has reached the 50-review limit for trial accounts. To continue receiving code reviews, upgrade your plan.

[gemini-code-assist]

Code Review

This pull request introduces a new CodeWhale-specific repo authority and prioritization policy loaded from .codewhale/constitution.json, which is rendered as a higher-authority block in the system prompt. It also deprecates the legacy WHALE.md in favor of AGENTS.md for cross-agent project instructions. The .gitignore handling is updated to ignore other .codewhale/ runtime state while keeping constitution.json committable. Feedback suggests adding a file size limit check when reading .codewhale/constitution.json to prevent potential out-of-memory issues or high latency.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

To prevent potential Out Of Memory (OOM) crashes or high latency when loading extremely large or malformed files, it is recommended to enforce a size limit check on the .codewhale/constitution.json file before reading it entirely into memory, similar to how other context files are loaded via load_context_file.

        if path.is_file() {
            if let Ok(metadata) = fs::metadata(&path) {
                if metadata.len() > MAX_CONTEXT_SIZE as u64 {
                    warnings.push(format!(
                        "Constitution file {} is too large ({} bytes, max {})",
                        path.display(),
                        metadata.len(),
                        MAX_CONTEXT_SIZE
                    ));
                    return (None, warnings);
                }
            }
            match fs::read_to_string(&path) {

[greptile-apps]

Hmbown has reached the 50-review limit for trial accounts. To continue receiving code reviews, upgrade your plan.