Phase KH2 — Muse-sync hard gate (Thinking freeze)

Status: Reviewed → pass (KH2-r2). KH2a is spec-only and now frozen; no code lands in this phase. KH2b (Auto) is cleared to build mechanically against this frozen contract; it is the only phase that writes files.

phase: KH2
outputs:
- id: kh2-muse-sync-hard-gate
  path: docs/archive/phases/PHASE-KH2-MUSE-SYNC-HARD-GATE.md
  frozen: true
frozen_inputs:
- id: substrate-health-impl
  path: tools/substrate_health/check.py
- id: adapter-status-interface
  path: adapters/base.py
- id: adapter-types
  path: adapters/types.py
- id: muse-git-mirror-status
  path: adapters/muse_git_mirror/adapter.py
- id: cli-status-exit-precedence
  path: cli/commands/status.py
- id: cli-review-freeze
  path: cli/commands/review.py
- id: governance-hygiene-reads
  path: tools/governance_hygiene/reads.py
- id: kh1b-gate-reminder-precedent
  path: docs/archive/phases/PHASE-KH1-HANDOVER-RELAY-STANDARD.md
- id: agents-md-day-to-day-rule
  path: AGENTS.md
- id: bridge-workflow-day-to-day
  path: MUSE-BRIDGE-WORKFLOW.md
review_stamp:
  reviewed_at: '2026-07-12T23:52:32Z'
  verdict: pass
  reviewer_mode: agent
  reviewer_model: thinking-high
  reviewer_provider: local
  kit_version: 0.1.0
  artifact_digest: sha256:735cbcede8a41a4378d2fe8de6f4b8085078ba4b8dc79c6836c68f3a286f563f

Downstream edge: KH2b treats this document as ground truth without re-deriving it (SPEC §6 mandatory reviewed freeze). It extends the tools/substrate_health/ family KH1b already shipped — this contract governs the additional detection + wiring, not a redesign of KH1b.

Review record (§6.2): every freeze-review finding MUST cite file+line per SPEC §6; uncited findings are invalid and are discarded. Fixes during the loop are Tier 1 (feature branch); merge to main is Tier 3 and is never part of this loop.

§KH2.0 — Simple summary

Overseer Kit already lets a repo say "MuseHub is my real source of truth; GitHub is just a mirror." That promise is only real if MuseHub actually has everything. Right now, saving work to Git and saving work to MuseHub are two separate manual actions on two separate systems, and nothing checks that the second one actually happened. On this very repo, that gap let real work sit in Git for a while with zero trace in MuseHub, and nothing warned anyone — the kit's own health check only looks for whether MuseHub's files exist, not whether its content is current.

KH2 closes that gap with a hard, fail-closed check, not a reminder that can be ignored: whenever a repo is set up so MuseHub is canonical and Git is the mirror, and Git has already captured a change that MuseHub has not, the kit's own commands (status --exit-code, review --freeze, governance-sync) refuse to say everything is fine. It only fires on the specific, precise condition that actually happened — "Git is clean, Muse is not" — so normal mid-edit work is never falsely blocked.

Technical summary: extend StatusResult (adapters/types.py) with two new optional fields, muse_dirty and git_dirty, so the muse+git-mirror adapter's already-computed-but-discarded per-VCS dirty signals survive past the point where they are currently OR'd together and lost. Add a new tools/muse_sync/ probe, sibling to tools/substrate_health/, that derives a MuseSyncReport from those two fields: pending exactly when muse_dirty is true and git_dirty is false (Git has committed content that Muse's last commit does not reflect); not_applicable outside muse+git-mirror; unreadable when either flag could not be determined (fail closed). Wire check_muse_sync into the same three fail-closed choke points KH1b already uses for substrate health — overseer status --exit-code, overseer review --freeze, overseer governance-sync — all returning the existing exit code 2 (the same "the declared canonical VCS state cannot currently be trusted" tier substrate-health already occupies; no new exit code, no change to the frozen 2 > 6 > 3 > 0 status precedence order).

§KH2.1 — Scope

In scope (freeze only — this phase writes no code):

• The StatusResult.muse_dirty / StatusResult.git_dirty field additions and which adapters populate them (§KH2.3).
• The MuseSyncReport shape and the check_muse_sync resolution rule (§KH2.4).
• The three wiring points and the exact exit-code treatment (§KH2.5).
• The precise boundary of what this gate does and does not catch, stated plainly so it is never oversold (§KH2.6).
• The seven-tier test matrix KH2b must satisfy (§KH2.8).

Out of scope (explicit non-goals — prevent creep):

• Automatically running muse commit on the operator's behalf. This gate only detects and refuses; it never writes a Muse commit for anyone. A content commit is a decision a human or an explicitly-invoked agent action makes, never a side effect of a read-only status/gate check.
• Detecting drift that survives a subsequent edit. If Git becomes dirty again before the gate is ever run (new edits stacked on top of an already-uncaptured Muse-lagging commit), this specific check goes quiet again, because its trigger condition is specifically "Git clean, Muse dirty." This known boundary is documented, not silently ignored (§KH2.6) — closing it fully would require a persisted "last Git SHA Muse has seen" anchor, which is deliberately deferred as a separate, future-scoped enhancement so this phase stays small and provably correct for the failure mode that actually occurred.
• muse-only and git-only regimes. Both are single-VCS; there is no second history to fall behind, so the gate is not_applicable there by definition, not merely unimplemented.
• Any change to the realign / bridge-export mechanism. Those already correctly guard the opposite direction (GitHub main diverging ahead of Muse via a bypassed push). KH2 is additive and orthogonal.
• Redefining the frozen status --exit-code precedence order. KH2 reuses exit code 2 — the same tier substrate_ok already occupies — rather than inserting a new tier into 2 > 6 > 3 > 0.

§KH2.2 — What exists now (verified, do not redesign)

KH2 must not change _muse_dirty()'s algorithm, the existing dirty field's meaning, the realign/bridge mechanism, or the frozen status exit-code ordering. It only adds two StatusResult fields, one new read-only probe module, and additive checks at three existing fail-closed choke points.

§KH2.3 — StatusResult field additions (frozen)

Add two optional fields to adapters/types.py's StatusResult, appended after notes so existing positional/keyword construction in tests and adapters is unaffected:

@dataclass(frozen=True)
class StatusResult:
    regime: str
    dirty: bool
    branch: str
    notes: list[str] = field(default_factory=list)
    muse_dirty: bool | None = None   # None = not determined / not applicable to this regime
    git_dirty: bool | None = None    # None = not determined / not applicable to this regime

Population rules per adapter (frozen):

The existing combined dirty field's value and meaning are unchanged in every adapter — this is a pure addition, not a behavior change to anything already reading .dirty.

§KH2.4 — MuseSyncReport + check_muse_sync (frozen)

New module tools/muse_sync/ (sibling package to tools/substrate_health/, same shape for consistency):

@dataclass(frozen=True)
class MuseSyncReport:
    regime: str
    state: str  # synced | pending | not_applicable | unreadable
    message: str
    remediation: str | None

    @property
    def ok(self) -> bool:
        return self.state in {"synced", "not_applicable"}


def check_muse_sync(config: OverseerConfig, status: StatusResult) -> MuseSyncReport:
    ...

Resolution rule (frozen, evaluated in this order):

1. config.vcs.regime != "muse+git-mirror" → state="not_applicable" (muse-only and git-only have exactly one history each; there is nothing to fall behind).
2. status.muse_dirty is None or status.git_dirty is None → state="unreadable" — fail closed: the gate refuses to claim "synced" when it cannot prove it, exactly mirroring the fail-closed philosophy already used by read_head/read_canonical_anchor/substrate health.
3. status.muse_dirty is True and status.git_dirty is False → state="pending" — the precise, frozen trigger condition: Git's working tree is clean (the last unit of work has already been committed to Git) while Muse's working tree still differs from Muse's last commit (that same work has not been captured in Muse). message names this exactly; remediation is the literal two-command sequence muse code add -A && muse commit -m "<message>".
4. Otherwise → state="synced".

Frozen non-triggers (must not fire — this is the false-positive guard):

• git_dirty is True (regardless of muse_dirty) → never pending. Mid-edit work, before anything has been committed anywhere, is normal and must not be flagged. This is why the rule is specifically "Git clean, Muse dirty," not "Muse dirty."
• muse-only / git-only regimes → always not_applicable, never pending or unreadable.

§KH2.5 — Wiring: three fail-closed choke points (frozen)

All three reuse the existing exit code 2 — the tier not substrate_ok already occupies in each surface today. No new exit code is introduced; no existing exit-code tier is renumbered.

§KH2.6 — Boundary: what this gate does and does not catch (frozen, stated plainly)

This table is deliberately part of the frozen contract so KH2b's build — and anyone reading the result later — cannot overstate what shipped.

§KH2.7 — Config & regime interaction

No new config block. muse_sync activates automatically whenever vcs.regime == "muse+git-mirror" in the already-loaded .overseer/config.yaml — consistent with how substrate_health also requires no dedicated config flag. This keeps the gate on by default for the one regime it protects, with zero new schema surface to document or drift.

§KH2.8 — Seven-tier test matrix (KH2b Auto build must satisfy)

§KH2.9 — Close-out (execute only when KH2 marked DONE)

1. Freeze-review pass recorded in the Review record table above (stamp written by overseer review --freeze).
2. ROADMAP KH2a row: freeze DONE; KH2b (Auto build) row added against this contract.
3. Handover NEXT flips to KH2b with a paste-ready prompt + the mandatory governance-gate reminders, once KH2b itself is complete in the same session, flips onward to the next queued slice.
4. Governance sync: docs/ROADMAP.md + docs/OVERSEER-HANDOVER.md updated together in the same commit (SD-17).