CodeWhale Constitution vs Code Knowledge Graphs

A CodeWhale constitution controls how an agent ranks authority, protects selected paths, escalates risk, and verifies completion; a code knowledge graph describes repository entities and relationships for a particular revision. Use .codewhale/constitution.json for governance. Use an external graph for calls, imports, schemas, tests, ownership, and dependency paths. Verify both against current code and live evidence.

This comparison uses Codewhale for the project’s factual spelling while retaining CodeWhale constitution as the target query. It is based on the v0.9.0 configuration documentation and CodeWhale’s public constitution page as checked on July 23, 2026.

Quick Verdict

Do not turn a constitution into a manually maintained architecture map, and do not let a graph decide policy.

Layer	Primary question	Appropriate contents	Authority and freshness
.codewhale/constitution.json	How should Codewhale decide and verify work in this repo?	authority order, protected invariants, branch policy, verification rules, escalation conditions	human-reviewed policy; changes when governance changes
AGENTS.md	How should agents work on this project?	prose instructions, commands, conventions, contribution workflow	human-reviewed instructions; changes with team practice
External code knowledge graph	What repository entities relate at this revision?	files, symbols, imports, calls, tests, schemas, documents, owners	regenerated or incrementally refreshed from evidence
Current source and tools	Is this claim true for the active task now?	checked-out code, configuration, test results, logs, diff	highest practical factual check for the active turn
Opt-in user memory	What durable personal preferences follow the user?	concise preferences across repositories and sessions	user-scoped; not a repo fact database

The split is operational, not semantic hair-splitting. A constitution may require an agent to trace consumers before changing a public API. The graph can return candidate consumers. Current source and tests determine whether the returned path is accurate and whether the change is acceptable.

The same pattern applies beyond Codewhale. AGENTS.md vs Knowledge Graph explains why human-authored instructions and generated repository relationships should keep different owners and refresh triggers.

What a Constitution Controls

Codewhale v0.9.0 documents several authority layers. The bundled constitution is compiled into the binary. A user-global constitution lives under $CODEWHALE_HOME/constitution.json—normally ~/.codewhale/constitution.json—and expresses standing preferences and stop conditions. A repository can add .codewhale/constitution.json for repo-specific authority and prioritization.

The repo-local file can contain:

• an authority order for resolving conflicting sources;
• protected invariants, optionally scoped to path globs;
• branch policy;
• verification requirements before claiming completion;
• escalation conditions for risky or unclear work.

These fields govern decisions. For example, an authority list can place live code and tests above an old handoff. A verification policy can require focused tests and a readback of changed files. A protected invariant can require approval or block writes to matched paths when expressed in the supported object form.

Codewhale’s documentation also establishes limits. Managing the constitution does not alter sandbox, network, trust, shell, MCP, or approval posture. Runtime security controls remain enforced in code. The constitution can tighten behavior or define authority; it cannot grant broader runtime permission.

Most importantly, constitution entries do not establish repository facts. A rule such as “preserve the billing event schema” tells the agent what matters. It does not enumerate the schema’s producers, consumers, generated clients, migration history, or tests. Those relationships must come from current evidence.

The public CodeWhale constitution page summarizes the same three-layer model and says the repo law sits above project instructions, memory, and handoffs. It also preserves the honest boundary: current requests and live tool evidence control factual reporting.

What a Code Knowledge Graph Describes

A code knowledge graph is a structured, queryable view of repository entities and their relationships. For agent work, useful nodes include files, packages, symbols, endpoints, schemas, tests, owners, configuration keys, and architecture records. Useful edges include imports, calls, implements, generates, publishes, consumes, configures, tests, and owns.

The graph should be external and revision-bound in this workflow. Codewhale v0.9.0 does not document a native code graph or repository index. An external tool can produce the graph, while Codewhale queries or receives the relevant evidence through its normal task context and tools.

Revision binding prevents a generated relationship from becoming timeless lore. Every graph view should identify the commit or snapshot from which it was built. It should also preserve provenance:

• parsed imports and definitions can cite exact locations;
• generated-code relationships should name the generator and artifact;
• inferred runtime paths should carry confidence and an explanation;
• decision links should point to dated records and owners;
• stale or unresolved edges should be visible, not silently omitted.

A graph helps answer “what appears connected?” It cannot prove every runtime path, infer every dynamic registration, or decide which behavior a team wants. Source inspection, focused tests, logs, and reviewers remain necessary.

Why Rules Cannot Replace Repository Facts

Rules age differently from code relationships. A verification rule may remain valid for years. A caller list can become stale after one refactor.

Putting repository structure into constitution prose creates three problems. First, changes to the code do not automatically update the rule. Second, reviewers cannot easily distinguish policy from generated observation. Third, an agent may treat a high-authority constitution block as proof even when current source contradicts it.

The opposite mistake is equally risky. A graph can show that a package imports another package, but it should not decide whether direct dependency is forbidden, whether a migration needs security review, or whether the team permits edits on a release branch. Those are governance decisions.

Consider a database migration:

1. The constitution says migrations require rollback steps, focused verification, and owner escalation.
2. AGENTS.md names the approved commands and contribution flow.
3. The graph identifies schema consumers, generated clients, migration files, and contract tests.
4. The task packet selects the relevant evidence for the active revision.
5. Codewhale reads current files, proposes the change, and runs the required checks.
6. A reviewer evaluates the diff and evidence.

Each layer contributes something the others cannot safely replace. Collapsing them into “agent memory” obscures authority and makes stale data harder to detect.

Codewhale’s optional memory feature reinforces this boundary. It is disabled by default and intentionally user-scoped. The documentation recommends project instructions for repo-specific conventions. Personal memory should not carry an unreviewed architecture summary from one repository into another.

How Governance and Understanding Work Together

Connect the layers with explicit gates rather than a single global context dump.

1. Ratify governance. Review .codewhale/constitution.json like policy code. Confirm its authority order, protected paths, branch rules, verification requirements, and escalation owners.
2. Build repository evidence. Generate a module, dependency, test, and ownership graph from a pinned revision.
3. Retrieve by task. Query only the affected relationships and include source locations, confidence, and unresolved edges.
4. Apply the rules. Use the constitution to decide which sources outrank old summaries and which gates the work must pass.
5. Inspect live source. Read the files behind every load-bearing graph path.
6. Verify behavior. Run the required focused tests and any broader contract or integration checks justified by the impact path.
7. Record the result. Preserve the revision, graph version, commands, test output, diff, reviewer, and remaining uncertainty.
8. Refresh separately. Update the graph after code changes; update the constitution only when governance changes.

This sequence keeps the graph useful without granting it policy authority. It also keeps the constitution authoritative without asking humans to maintain a brittle list of repository relationships.

For large Codewhale tasks, the CodeWhale Large Codebase Context guide shows how the same evidence layer stays portable when models or providers change.

FAQ

Can rules conflict with graph evidence?

Yes, but the conflict often reveals a category error. A rule might claim a path is protected while the graph shows the component moved; current source should resolve the location, and an owner should update the rule. A graph might expose a forbidden dependency; the constitution determines escalation or remediation. Never edit governance automatically just to make it agree with generated evidence.

Who reviews constitution changes?

Repository owners should review them with the people responsible for security, release, and the affected protected paths. Treat changes as policy changes: explain the reason, verify the schema, test any mechanically enforced path globs, and require normal code review. A model may draft text, but Codewhale’s constitution setup distinguishes drafting from ratification.

How should stale repository facts be flagged?

Store the source revision, generation time, provenance, and confidence on graph data. Mark the graph stale when the checkout differs, relevant files change, extraction fails, or a current source check contradicts an edge. Block high-impact use until the affected slice is refreshed. Preserve the failed edge and reason so the indexing process can improve.

Conclusion

The Codewhale constitution and a code knowledge graph are complementary because they answer different questions. The constitution governs priority, invariants, verification, and escalation. The graph organizes revision-bound repository facts and dependencies. Current source and tests arbitrate factual claims.

Keep those boundaries visible. Ratify rules with human owners, refresh graphs from code, retrieve only task-relevant evidence, and record verification. If a statement changes when the repository changes, it belongs in the evidence layer—not in constitution prose. If it expresses how the team must decide or verify work, it belongs in governance—not in a generated graph.