Phase KH3 — Footprint self-integrity hard gate (Thinking freeze)

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

phase: KH3
outputs:
- id: kh3-footprint-integrity-hard-gate
  path: docs/archive/phases/PHASE-KH3-FOOTPRINT-INTEGRITY-HARD-GATE.md
  frozen: true
frozen_inputs:
- id: footprint-integrity-impl
  path: cli/commands/status.py
- id: substrate-health-impl
  path: tools/substrate_health/check.py
- id: muse-sync-impl
  path: tools/muse_sync/check.py
- id: version-lock-origin
  path: cli/version_lock.py
- id: footprint-resolver
  path: cli/footprint.py
- id: cli-review-freeze
  path: cli/commands/review.py
- id: governance-hygiene-reads
  path: tools/governance_hygiene/reads.py
- id: kh2-hard-gate-precedent
  path: docs/archive/phases/PHASE-KH2-MUSE-SYNC-HARD-GATE.md
- id: k7-dogfood-seed-rule
  path: docs/archive/phases/PHASE-K7-MUSE-GIT-MIRROR-DOGFOOD.md
review_stamp:
  reviewed_at: '2026-07-13T07:42:05Z'
  verdict: pass
  reviewer_mode: agent
  reviewer_model: thinking-high
  reviewer_provider: local
  kit_version: 0.1.0
  artifact_digest: sha256:4ad2c03864f7e6935d134d92fea11506dcd7e6bf287bb153c254a640b9452267

Downstream edge: KH3b treats this document as ground truth without re-deriving it (SPEC §6 mandatory reviewed freeze). It follows the exact tools/substrate_health/ / tools/muse_sync/ family shape KH1b and KH2 already shipped — this contract governs one additive detection + wiring slice, not a redesign of either predecessor.

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.

§KH3.0 — Simple summary

This kit's whole job is catching drift before it becomes a silent, permanent gap. It just found one in itself: for three days, this very repo's own tracking file said "these 13 rule and policy files should exist" while none of them actually did — and nothing that runs automatically ever said a word, because the one check that could have caught it only runs when someone remembers to ask for it by hand.

KH3 closes that gap with a hard, fail-closed check, not an opt-in flag anyone can forget to pass: whenever the kit's own tracking file says a file it owns should exist, and that file is completely absent from the working tree, the kit's own commands (status --exit-code, review --freeze, governance-sync) refuse to say everything is fine — the same way they already refuse when MuseHub falls behind Git (KH2) or when Muse's metadata is hollow (KH1b). It deliberately does not fire on files that merely differ in content from a stale recorded hash — that softer case stays on the existing opt-in overseer status --check-footprint path, so repos that have legitimately customized a kit-owned file (and haven't yet marked it preserved) are not suddenly broken by this phase.

Technical summary: add a new tools/footprint_integrity/ probe, sibling to tools/substrate_health/ and tools/muse_sync/, exposing FootprintIntegrityReport and check_footprint_integrity(config, repo_root, kit=None). It resolves the current footprint (cli/footprint.py::resolve_footprint), reads .overseer/version.lock, and — for every lock-declared, non-preserved (origin: kit or omitted) destination — checks only whether the file exists on disk. Any absence yields state="missing" (not ok); an unreadable lock is state="unreadable" (fail closed); everything present is state="ok". This is a strict subset of the existing _compute_footprint_integrity logic in cli/commands/status.py — it never looks at byte content or hashes, only existence — which is exactly why it is safe to run unconditionally without the false-positive risk a full content-digest check would carry for repos with legitimate, not-yet-preserved customizations. Wire check_footprint_integrity into the same three fail-closed choke points KH1b/KH2 already use — overseer status --exit-code, overseer review --freeze, overseer governance-sync — all returning the existing exit code 2.

§KH3.1 — Scope

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

• The FootprintIntegrityReport shape and the check_footprint_integrity resolution rule (§KH3.4).
• The three wiring points and the exact exit-code treatment (§KH3.5).
• The precise boundary of what this gate does and does not catch, stated plainly so it is never oversold (§KH3.6).
• The seven-tier test matrix KH3b must satisfy (§KH3.8).

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

• Making the existing overseer status --check-footprint full content-digest check run by default. That check compares byte-for-byte content against recorded hashes and would fail-close on any kit-owned file a consumer has customized without yet marking origin: preserved — a real, live false-positive risk this same session hit directly (scripts/muse-bridge-deploy.sh's stale hash, docs/ROADMAP.md/docs/OVERSEER-HANDOVER.md before reclassification). Flipping that check's default posture is a materially different, higher-blast-radius decision affecting every existing consumer install (Scooling, Knowtation, VideoFactory per prior pilots) and is explicitly deferred to a future, separately-scoped phase if ever pursued.
• Automatically running overseer sync on the operator's behalf. This gate only detects and refuses; it never writes files for anyone. Seeding missing files is a decision a human or an explicitly-invoked overseer sync action makes, never a side effect of a read-only status/gate check.
• Any change to overseer sync's own conflict/classification logic (cli/sync_classify.py, cli/commands/sync.py). KH3 is a new read-only detector, wired into existing choke points; it does not alter how sync decides to write, seed, or refuse.
• Any change to the origin: preserved mechanism (§K6.4). KH3 respects it exactly as-is — preserved entries are never checked for existence by this gate, mirroring how they are already excluded from the digest in _compute_footprint_integrity.
• Redefining the frozen status --exit-code precedence order. KH3 reuses exit code 2 — the same tier substrate_ok/muse_sync_ok already occupy — rather than inserting a new tier into 2 > 6 > 3 > 0.

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

KH3 must not change _compute_footprint_integrity's existing opt-in content-digest behavior, overseer sync's classifier, the origin: preserved mechanism, or the frozen status exit-code ordering. It only adds one new read-only probe module and additive checks at three existing fail-closed choke points, scoped strictly to file-existence.

§KH3.3 — Why "missing" only, never "content differs" (frozen scope boundary)

This is the single most important design decision in this contract, and it is frozen precisely because getting it wrong has real blast radius across every consumer of this kit, not just this dogfood repo:

This means KH3's gate and the existing --check-footprint content-digest gate are complementary, non-overlapping safety nets: KH3 is the always-on floor ("nothing the kit promised is silently absent"); --check-footprint remains the opt-in, more thorough ceiling ("nothing the kit promised has silently changed either") for operators who want it, unchanged by this phase.

§KH3.4 — FootprintIntegrityReport + check_footprint_integrity (frozen)

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

@dataclass(frozen=True)
class FootprintIntegrityReport:
    state: str  # ok | missing | unreadable
    message: str
    remediation: str | None
    missing: tuple[str, ...] = ()

    @property
    def ok(self) -> bool:
        return self.state == "ok"


def check_footprint_integrity(
    config: OverseerConfig,
    repo_root: Path,
    *,
    kit: Path | None = None,
) -> FootprintIntegrityReport:
    ...

Resolution rule (frozen, evaluated in this order):

1. .overseer/version.lock cannot be read/parsed (LockError) → state="unreadable" — fail closed, mirroring the existing unreadable treatment in check_muse_sync §KH2.4 and the existing lock_error handling already present in cli/commands/status.py.
2. resolve_footprint(config, kit=kit) raises ConfigError → state="unreadable" (same fail-closed posture; a config that cannot resolve its own footprint cannot prove anything is present).
3. For every resolved FootprintFile, look up its version.lock entry (if any) and resolve its origin via the existing entry_origin helper (default "kit" when the entry is absent or the field is omitted, per current cli/version_lock.py semantics). Skip any entry whose origin is "preserved" — never check existence for those (mirrors §K6.4 exactly; a preserved living doc that somehow doesn't exist yet is sync's / the operator's concern, not this gate's).
4. Among the remaining (kit-origin) entries, collect every destination whose absolute path (repo_root / destination) is not an existing file. If that set is non-empty → state="missing", missing= the sorted tuple of those destinations, message names the count and lists them, remediation="overseer sync".
5. Otherwise → state="ok".

Frozen non-triggers (must not fire — this is the false-positive guard, per §KH3.3):

• A file that exists but whose content differs from its recorded hash → never missing. This gate performs no hashing and reads no file content at all beyond an existence check (Path.is_file()); it is a strict subset of _compute_footprint_integrity's existing logic.
• Any entry whose resolved origin is "preserved" → never checked, regardless of whether it exists.
• A destination that resolve_footprint does not currently produce for the active config.vcs.regime (e.g. MUSE-BRIDGE-WORKFLOW.md / scripts/muse-bridge-deploy.sh when the regime is not muse+git-mirror) → never considered, because it is never in the resolved set to begin with — this is unchanged, existing resolve_footprint regime-conditional behavior (§K7.2.3).
• A brand-new repo before its first overseer init (.overseer/ directory absent entirely) → this gate is never reached; run_status/run_review/perform_verified_reads all already return early (initialized: false / "not initialized" / equivalent) before any footprint or substrate check runs, unchanged by KH3.

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

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

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

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

§KH3.7 — Config & regime interaction

No new config block. check_footprint_integrity activates automatically for every regime once .overseer/ is initialized — consistent with how substrate_health and muse_sync also require no dedicated config flag (each simply becomes not_applicable/vacuously ok where irrelevant — here, vacuously ok whenever resolve_footprint yields no non-preserved destinations, e.g. a config with zero policy/rule files declared). This keeps the gate on by default with zero new schema surface to document or drift.

§KH3.8 — Seven-tier test matrix (KH3b Auto build must satisfy)

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

1. Freeze-review pass recorded in the Review record table above (stamp written by overseer review --freeze).
2. ROADMAP KH3a row: freeze DONE; KH3b (Auto build) row added against this contract.
3. Handover NEXT flips to KH3b with a paste-ready prompt + the mandatory governance-gate reminders, once KH3b 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).