xoai/sage-gates

Gates

Two different mechanisms share the word "gate", and confusing them is how people end up arguing with a hook.

| | Hooks | Gates | |---|---|---| | When | Before a tool call (PreToolUse) | After work, on demand | | What | Block the edit itself | Score the result | | Failure mode | Fail open — a broken hook must not brick the session | Fail closed — an unrun gate is not a passed gate | | Examples | sage-spec-gate.sh, sage-tdd-gate.sh | Gates 1–6 |

Hooks are guards, not gates.

Why you were blocked

"Sage spec gate: no spec exists for the active cycle." A cycle in .sage/work/*/manifest.md has gate_state: pre-spec, and you tried to edit a source file. Write the spec, get [A], and the manifest advances to spec-approved. Then the edit lands.

"Sage TDD gate: tests before code." No test has been written for this change. Write the failing test first. The gate accepts a dirty/untracked test file or a red commit (tests touched, no source) as evidence.

Completion blocked. The manifest cannot reach complete while gate_state is anything short of gates-passed, and it cannot complete with an unresolved qa: disposition. This is Rule 5 with a script behind it.

Neither hook is arguing with you. Both are stating a precondition you can satisfy in about a minute.

The workflow file checks

Build (Standard+) — BEFORE implementing, verify both files exist on disk:

• .sage/work/<initiative>/spec.md — status: completed
• .sage/work/<initiative>/plan.md — status: completed

If either is missing, create it first. No exceptions.

Do not rationalize past this:

| The thought | The reality | |---|---| | "The design is clear from earlier discussion" | Not a spec file. | | "The user described what they want" | Not a spec file. | | "This is straightforward" | If it is Standard scope, a spec is required. | | "Just build it" | Write a minimal five-line spec and get [A]. |

Branch gate (Standard+, git projects). Before implementation commits begin, HEAD must not be the default branch — unless a branching decline is recorded in the initiative's decision log. Merging is always a user-gated [M] action. No workflow path merges on its own. Full protocol: sage/core/capabilities/execution/git-discipline/SKILL.md.

Gate sequence (build):

1. Spec → .sage/work/ → [A]/[R] → wait
2. Plan → .sage/work/ → [A]/[R] → wait
3. Implement (tests before code, via the build loop)
4. Verify with pasted test output → [A]/[R]

Fix — scope AFTER root cause:

1. Investigate the root cause with evidence → [A]/[R]/[S] → wait
2. Then scope the fix:
   • Surgical (1–2 files) → proceed
   • Moderate (3–5 files) → write a fix plan first → [A]/[R]
   • Systemic (5+ files, interface changes) → escalate to /build or /architect
3. Implement → verify with pasted output → [A]/[R]

Do not fix before the root cause is confirmed. Do not skip fix scoping — a "quick fix" that touches eight files is a rebuild wearing a smaller word.

Architect — brief BEFORE design:

1. Complete all three elicitation rounds (vision, constraints, gaps). Each produces visible output. brief.md must exist before design begins. Do not compress the rounds. Do not skip them because "I understand the system."
2. Design with ADRs → .sage/docs/ → spec → .sage/work/ → [A]/[R]
3. Milestone plan → [A]/[R] → phased build; each milestone follows the build gates independently.

Verify before claiming done (Rule 5, in full)

Before presenting any completion checkpoint:

• Tests exist for the new or changed functionality
• Tests pass — paste the actual output, do not summarize it
• The implementation matches the spec or plan
• If tests do not exist or do not pass, the task is not done

Spec compliance is adversarial. Do not trust your own report that the implementation matches the spec. You wrote it; you are the last one who will notice what it does not do. Verify independently, or let a fresh reviewer do it.

The three-state exit contract

Gate scripts exit 0 pass, 1 fail, 2 unverifiable.

Exit 2 is the one that matters. It exists because "the suite is green" and "there is no suite" are different claims that used to share exit 0 — which is precisely how a gate reports success on code it never looked at.

Exit 2 is never a pass. It is also not a failure: it has produced no evidence either way. On exit 2, present the choice and record it:

[P] Proceed unverified — logged as a waiver in .sage/decisions.md
[F] Fix verification setup — install the runner, then re-run