Phase integrity

Phase integrity is the write-time gate that keeps a repo’s phase ledger coherent. It is checked at read time (surfaced on the dashboard) and enforced at act time — a start_phase or close_phase verb that would make integrity strictly worse is blocked before it opens a PR.

The findings

host/src/sources/phase-integrity.ts (validatePhaseIntegrity) walks a repo’s phase list and emits findings, each with a rule and a severity of hard or soft:

Rule	Meaning
multi_open	More than one phase is open at once.
current_behind	currentPhase points behind the furthest open/closed phase.
current_ahead	currentPhase points past any phase that actually exists.
non_monotonic	Phase numbers are out of order / skip backwards.
closed_gap	A closed phase sits above an open or missing lower phase.

Soft findings inform; they never block. Hard findings block a transition that would introduce them.

Act-time enforcement

host/src/tools/phase-guard.ts (phaseTransitionGuard) runs inside the start_phase / close_phase verbs. It:

1. Loads the repo’s current phase ledger from the registry-backed source.
2. Builds the prospective ledger the verb would produce (setting phase N open for a start, closed for a close).
3. Compares hard findings via wouldRegressHardIntegrity — true iff the prospective ledger carries a hard finding absent from the current one.

If it would regress, the verb short-circuits with:

REPO_PHASE_INTEGRITY: <start|close>_phase Phase-N on <slug> would
introduce a hard phase-integrity violation; reconcile the phase ledger
first.

Pre-existing hard findings do not block — the gate only rejects new regressions, so an already-messy ledger can still be repaired one transition at a time.

Fail-open by design

Any error inside the guard (missing repo, source failure, unexpected throw) logs [phase-guard] fail-open and lets the act proceed. Enforcement must never wedge governance: a broken guard degrades to the verb’s own validation, it does not freeze the write surface. This mirrors the broader principle that governance gates protect coherence without becoming a single point of failure.

Recovering from a block

When you hit REPO_PHASE_INTEGRITY, reconcile the ledger before retrying:

1. petrova diagnose <slug> (or the dashboard phases view) to see the current hard findings.
2. Fix the ledger through the normal verbs — close the stray open phase, correct currentPhase, or fill the gap — each as its own PR.
3. Re-run the original start_phase / close_phase.

See also

• Governance model — where this gate sits in the write path.
• Governance audit — the read-time conformance surface.
• Spec: docs/superpowers/specs/2026-05-16-phase-integrity-design.md.