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

Splits repo-level guidance into two clear artifacts and deprecates the
confusing WHALE.md concept (overlapped with AGENTS.md):

- AGENTS.md is the canonical cross-agent project-instructions file.
- .codewhale/constitution.json is the CodeWhale-specific repo authority /
  prioritization policy (when local sources conflict, which to trust first; what
  to verify before claiming done). Rendered into the system prompt as a
  higher-authority <codewhale_repo_constitution> block; takes precedence over a
  legacy WHALE.md.

WHALE.md migration (compat-preserving):
- AGENTS.md now ranks above WHALE.md in both project and global discovery; with
  both present, AGENTS.md wins.
- WHALE.md is still read as a legacy fallback, but now emits a deprecation
  warning and is never created or recommended (init.rs no longer suggests it).
- Discovery/docs updated; the global CodeWhale Constitution in prompts/base.md
  is unaffected (different thing).

constitution.json:
- New RepoConstitution (serde, all fields optional, unknown fields ignored,
  schema_version checked). 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/* +
negation). init.rs writes the same pattern for new repos. Dogfood: this repo's
.codewhale/constitution.json added.

find_git_root made pub(crate) and reused (no duplicate loader).

Tests: AGENTS-over-WHALE precedence, WHALE legacy-read-with-warning,
constitution render + system-block surfacing, malformed-constitution warning,
gitignore-keeps-constitution. cargo test -p codewhale-tui --bins → 3946 passed;
clippy clean.

Targets codex/v0.8.53.
This commit is contained in:
Hunter Bown
2026-06-03 12:12:34 -07:00
parent 03d1bba538
commit 9d9616e898
6 changed files with 376 additions and 37 deletions
+4 -1
View File
@@ -67,7 +67,10 @@ project_overhaul_prompt.md
.wrangler/
# Local runtime state
.codewhale/
# Ignore everything under any .codewhale/ (snapshots, auto-generated
# instructions.md, etc.) at any depth EXCEPT the committed repo authority policy.
**/.codewhale/*
!**/.codewhale/constitution.json
.deepseek/
**/session_*.json
*.db