PAI: add CONSTITUTION.md — Nine Articles of Development

[caraka]

Summary

Adds Releases/v4.0.3/.claude/PAI/CONSTITUTION.md, the file referenced by EngineerContext.md line 35 ("Required Knowledge (Pre-load from Skills): PAI/CONSTITUTION.md") and cited by Engineer.md lines 236-260 (the "Nine Articles of Development (Constitutional Law)" section). Currently no such file ships in any release (verified across v2.3 through v4.0.3), so the citations resolve to nothing.

This addresses recommendation #1 from @esciara's phantom-references audit posted in #812 (2026-03-02), which identified PAI/CONSTITUTION.md as the highest-priority phantom reference (12 agents touch it).

A note on context

I'm new to PAI — I picked it up a few days ago and discovered this gap while learning how the agent system works, by walking through Engineer.md and following its references. The Constitution citation was a natural rabbit hole; this PR is what came out the other end. I'm genuinely grateful for the tool, and have no attachment to the outcome of this PR — accept as-is, edit freely, or reject — all of those are good outcomes from where I sit. Mostly I wanted the missing reference to land somewhere useful for the next person who walks the same path.

What's in the file

Adapted from GitHub Spec Kit (github/spec-kit, MIT-licensed) — the framework Engineer.md's Articles citation appears to come from. Specifically:

• Articles I, II, III, VII, VIII, IX — text drawn near-verbatim from spec-kit's spec-driven.md
• Articles IV, V, VI — text drawn from spec-kit's templates/constitution-template.md example comments (these articles are named in spec-kit's template but not fleshed out in the spec-driven.md essay)

Articles VII and VIII carry the "Gate" suffix to match Engineer.md's existing usage. The other articles do not.

The Preamble's binding gate (important for review)

The Preamble adopts an explicit per-article, citation-based binding rule:

Each article binds an agent only when that article is explicitly cited by the agent's system prompt, a skill workflow it runs, or the task it receives. Loading this file is not binding; citation is.

This is the key design choice and it should ease any concern about merging this PR. Adding this file does not impose new rules on any existing agent. The mechanics:

• Engineer.md already cites Articles I, II, III, VII, VIII, IX inline (lines 236-260). Those articles already bind the Engineer; this PR doesn't change that.
• Articles IV, V, VI are present in the new file but not cited by any agent in the current release. They are loaded (when the EngineerContext.md pre-load directive resolves) but not binding any behaviour.
• Any agent — including custom user-authored agents — that doesn't cite an article is completely unaffected by it.

So the file changes nothing about runtime behaviour. It just gives a real source-of-truth for citations that already point at it. Future PRs (not this one) could extend article citations into more agents if desired; doing so would expand binding by explicit choice.

Testing

Tested by spawning a fresh Engineer agent from a clean claude session in a fork-clone of this repo. The Engineer:

1. Loaded ~/.claude/PAI/CONSTITUTION.md via its EngineerContext.md startup directive — successful, no errors
2. Quoted Article V (Observability) verbatim — content matched the file exactly
3. Applied the per-article binding rule across all three citation channels (system prompt, skill workflow, task) and correctly concluded NOT bound by Article V because Engineer.md does not cite it
4. Recognised the meta-distinction that while not bound by Article V on its task, the Preamble's binding rule itself bound the analysis sub-question because the user's task explicitly cited the Preamble — a sharp comprehension of the rule's mechanics

The Engineer's reasoning matched the spec-kit-derived wording exactly, demonstrating the file is intelligible and the binding rule is unambiguous.

What this PR does NOT do (scope)

• Does NOT modify Engineer.md (the inline article listing in lines 236-260 remains; it duplicates the new file's I/II/III/VII/VIII/IX content but coexists harmlessly via the per-article binding rule)
• Does NOT modify EngineerContext.md (the existing line-35 pre-load directive now resolves to a real file rather than a missing one)
• Does NOT add Article citations to other agents — the binding rule means uncited agents are unaffected

These are deliberately out of scope to keep the PR minimal and reviewable. Note: this diverges from @esciara's audit recommendation, which suggested extracting the Articles from Engineer.md into the new file (deduplication). I chose to add the file without extraction to keep the PR scope as small as possible — happy to do the extraction as a follow-up PR if preferred, or to fold it into this one if reviewers want.

Notes for review

A few things you may want to weigh in on:

1. Articles IV vs IX overlap. Spec-kit has both Article IV (Integration Testing) and Article IX (Integration-First Testing) with similar but distinct wording. Kept both for fidelity. Open to merging.
2. Articles IV/V/VI fidelity. Wording is drawn from spec-kit's template example comments (the most authoritative source available, but lighter in detail than the I/II/III/VII/VIII/IX text). Open to fuller authorship if preferred.
3. "NON-NEGOTIABLE" suffix on Article III. Kept (matches spec-kit's template comment example: III. Test-First (NON-NEGOTIABLE)). Drop if you prefer a cleaner heading.
4. File size. 89 lines, ~4 KB. Minimum viable — no Sync Impact Report machinery, no document-level versioning, no amendment-process governance overhead. Could be expanded if fuller spec-kit fidelity is wanted.

License + attribution

Spec-kit is MIT. PAI is MIT. Source attribution lives in the Preamble (markdown link to spec-kit) and Governance rule 3.

🤖 Generated with Claude Code