sage-constitution

# The constitution The eager layer carries each principle as one line naming the mechanism that enforces it. This carries the reasoning, and the rules that have no mechanism behind them. ## Engineering principles The base set, present in every project: | # | Principle | Enforced by | |---|---|---| | 1 | **Tests before code** — every behavior has a test before implementation | `sage-tdd-gate.sh` (PreToolUse — blocks the edit) | | 2 | **No silent failures** — errors handled, logged, or propagated | Gate 3 (judgment) | | 3 | **Secrets never in code** — env vars or a secret manager | Gate 3 (judgment) | | 4 | **Dependencies explicit** — declared, pinned | Gate 4 (`sage-hallucination-check.sh`) | | 5 | **Changes reversible** — migrations reversible, deploys rollbackable | Gate 3 (judgment) | Principles 6+ come from the project's preset and its own `.sage/constitution.md`. They are appended by the generator, numbered continuously, and they carry exactly the same weight as the base five. A project addition is not a suggestion. **Read the project's own additions before assuming the base five are the whole story.** They are in `.sage/constitution.md`, and they are where the rules that actually bite in *this* codebase live. ## The distinction that matters Three of the five principles above are enforced by a *judgment* gate — which means they are enforced by a reviewer noticing, and reviewers are exactly as reliable as their attention. Two are enforced by a script that blocks the tool call, and those two hold whether or not anyone is paying attention. That is not a criticism of the three. Some rules genuinely cannot be checked mechanically ("no silent failures" requires knowing what a silent failure looks like *here*). But it is worth being honest about which rules are load-bearing and which are aspirational, because the eval that produced this version of Sage found that the mechanically-enforced rules moved behavior and the prose ones, on their own, did not. If a principle matters and has no mechanism, that is a gap in the mechanism — not a reason to write the prose more forcefully. ## Process rules with no script behind them These are enforced by the model reading them, which is a real but weaker thing. **Rule 2 — Skills before assumptions.** If a Sage skill exists for the task at hand, read it and follow it. Do not fall back on general training when a skill provides a specific methodology. (This is the dispatcher rule, and it is in the eager layer for a reason: if it fails to fire, nothing else here loads.) **Rule 3 — Document decisions.** Decisions that affect the project get recorded — for agents *and* for the humans who arrive later. Specs, plans, ADRs, and briefs go to `.sage/work/` or `.sage/docs/`. Even a Tier 2 task leaves a record of what was decided and why. Partially mechanical: the spec-gate hook blocks source edits while a cycle is `pre-spec`, so the *spec* half has teeth. The rest is on you. ## Rationalizations | The thought | Why it fails | |---|---| | "This principle does not apply to test code" | Test code is code. It is also the code you will trust the most and read the least. | | "The project preset does not mention it, so it is optional" | The base five apply everywhere. Presets add; they do not subtract. | | "I will follow the principle, just not right now" | The commit is the artifact. "Later" does not appear in it. | | "It is a prototype" | Prototypes ship. That is what makes them prototypes rather than sketches. |