xoai/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. |