Phase Gate

phase-gate

Close a phase the way a reviewer would: verify the phase's written acceptance checklist item by item against named evidence artifacts, then update the record everywhere it lives. A phase closes on evidence, not on recollection — and one open item means it does not close.

When to use

• A phase, milestone, or gate from the project plan ({{phase_plan}}) appears complete and the user wants formal closure.

When NOT to use

• Mid-phase "is this sub-task done?" — that is an execution-turn question against the current TODO buffer.
• "Where are we / what's next" — dispatch the session-historian agent.
• Declaring partial victory — there is no partial closure (see Rules).

The ritual (strict order — no step skipped, no step reordered)

1. Load the contract. Read the phase's acceptance checklist from {{phase_plan}} (and its gate registry row, if the plan keeps one). This written checklist — never memory — is what gets verified.
2. Verify each item with evidence. For every checklist item, name the artifact that proves it: fresh gate-test output, an {{evidence_dir}}/<name>_<date>/ run directory with its meta file, a decision entry, an executed notebook or committed figure. An item without an artifact is OPEN — the phase does not close. Run {{gate_command}} fresh as part of this step; a red gate blocks closure regardless of checklist state.
3. Decision sweep. Every decision this phase owed (check the plan's decision queue, if any) must exist in {{decision_log}} with a real number — assigned at write time, never reserved in advance.
4. Build-log entry. Invoke the build-log skill (phase-completion bar applies). The entry links every evidence artifact from step 2.
5. Layer-sync audit scoped to the phase. Drift found → fix in a separate approved turn per that skill's rules, then re-run the audit before closing.
6. Update the status surfaces. Mark the phase ✅ on the plan's status board, and rewrite the TODO buffer to the next phase's sub-tasks — the buffer is ephemeral; completed-phase content is deleted, not accumulated.
7. Regenerate derived views (project wiki, dashboards, generated indexes), if the project keeps any. Derived views are never hand-edited: wrong content means a source-layer fix first, then regeneration.
8. User sign-off. Present the closure summary — checklist verdicts, evidence links, decision/build-log diffs — and get explicit approval before committing. Gate decisions with branches (pass/drop calls, representative-point choices) are the user's call, never auto-resolved.

Output format

## Phase closure — <phase name> / <gate id>

| Acceptance criterion | Evidence | Status |
|---|---|---|
| ... | {{evidence_dir}}/<run>/ or build-log NN or D<n> | ✅ / ❌ OPEN |

**Gate test**: <N> tests green (summary of fresh output)
**Decisions**: D<n>, ... | **Build log**: NN_topic.md | **Layer sync**: ✅/⚠
**Verdict**: CLOSED / BLOCKED — <open items>

Rules

1. One OPEN item = no closure. Pre-declared off-ramps written into the plan (e.g. "if the result window is empty, branch to X") are legitimate closures; silent scope-shrinking is not.
2. Evidence means versioned evidence. "It ran and the output looked fine" without an {{evidence_dir}} run directory is a dark run — treat the item as OPEN (see evidence-convention).
3. Never soften a negative result to pass a gate. An infeasibility, a null effect, or a hardness finding — rigorously recorded — is a valid closure artifact; record it verbatim and close on it (see negative-results-ledger).
4. Commits happen after sign-off, following the project's git workflow.
5. Fresh runs only. Cached test output, yesterday's logs, or "it passed last week" do not satisfy step 2.

Configuration

• {{phase_plan}} — the plan document holding phase tables + acceptance checklists.
• {{gate_command}} — the named correctness gate (see correctness-gate).
• {{decision_log}}, {{build_log_dir}}, {{evidence_dir}} — the record surfaces.

Provenance & maintenance

Generalized from the gate-closure ritual of a working computational-research repository (checklist-with-evidence verification, decision sweep, build-log + sync audit coupling, sign-off-before-commit); see the pack's examples/ directory for the worked exemplar mapping. The eight-step order and rules 1–3 are verified practice; step 7 applies only if the project keeps derived views (labeled optional by construction).

Re-verify in your project:

• {{gate_command}} — must be green before any closure claim.
• grep -n "OPEN\|⬜\|🟡" <status board> — anything still open on the board contradicts a closure claim.
• ls -t {{evidence_dir}} | head -3 — the runs cited as evidence actually exist and are recent.