aaronrene / overseer-kit public
OVERSEER-KIT-SPEC.md markdown
552 lines 41.3 KB
Raw
sha256:0e9549ec7b463911bc08b7d586dc320b1ac9b1f5c943ee7e3865dcc6cb0f6f83 chore(governance): sync handover+roadmap to 84db8c8 (drift:… Human 5 hours ago

Overseer Kit — Cross-Repo Governance System Architecture (Frozen Thinking Outline)

Status: Frozen meta-architecture for the Build phases (K1–K6 + 9A-5). No implementation in this step. No kit repo created yet. No env changes. No hooks installed. No main merges. No muse push staging. No live effect of any kind.

This document freezes WHAT and HOW for extracting the overseer/governance system out of the three workspaces (Scooling, Knowtation, MuseHub) into a single canonical, versioned, standalone "Overseer Kit" that any repo injects locally — so the system can be maintained and perfected in one place, shared with every repo (mine and other developers'), and kept honest with proper hygiene and human review only where genuinely required. It follows RULE #8 (Orchestrator) and the single-model handover protocol: this is the contract layer; the kit code, CLI, adapters, and seven-tier test bodies are the K1–K6 Build phases (Thinking → Auto per the queue).

Frozen inputs it composes with (does not fork):

  • docs/CROSS-REPO-COORDINATION.md — the three-repo role/VCS table, the Standing Decisions (ADR) log (SD-1, SD-3, SD-11, SD-14, SD-17), the Decision Authority tiers (Tier 1/2/3), the overseer handover protocol, and the model-split protocol. This kit is the productized form of that doc.
  • docs/OVERSEER-HANDOVER.md — the living relay whose shape becomes the kit's handover template.
  • docs/ROADMAP.md — the phase-control doc whose shape becomes the kit's roadmap template + the Phase Model Key.
  • docs/GITHUB-MIRROR-RECONCILIATION-FOLLOWUP.md — the recurring Muse↔Git inversion failure the kit's VCS adapter is designed to detect and prevent centrally.
  • docs/archive/phases/PHASE-9A-5-GOVERNANCE-HYGIENE-AGENT-OUTLINE.md — the first agent tool the kit ships; rebased onto the kit's VCS adapter interface so it is repo-agnostic from day one.
  • knowtation/AGENTS.md, scooling/AGENTS.md, MUSE_HUB/docs/MUSEHUB-OVERSEER-HANDOVER.md — the three concrete VCS regimes the kit's adapter backends must satisfy.

Simple summary (no jargon)

Right now our "overseer system" is not really one system — it is the same set of good habits re-typed by hand into three separate projects. Each project keeps its own handover note, its own roadmap, the same rules about testing, the same rules about who is allowed to merge, and the same labels for which AI model to use. Because it is copied instead of shared, the copies drift apart, and we have already paid for that drift four times: four times someone merged on GitHub without telling the canonical history (Muse), and each time a person had to manually stitch it back together.

The fix is to put the whole system in one place of its own — a small standalone project we will call the Overseer Kit — and then "inject" a thin, version-stamped copy of it into any project that needs it. When we improve the system, we improve it once in the kit, then run one command in each project to pull the update. It works whether a project uses our special history tool (Muse), plain GitHub, or both — so it works for our three projects and for any outside developer too. The kit also carries the "robot helpers": one that keeps the handover and roadmap honest at the end of every session, and one that reviews the important "frozen" decisions and only interrupts a human when it finds something that truly needs a human. Everything a computer can safely check, the computer checks; humans are asked only for the few things that are risky, irreversible, or cost real money.

Technical summary

This freezes the design for a standalone overseer-kit repository that is the single canonical source of the governance layer, distributed into consumer repos as a pinned, vendored footprint driven by one small per-repo .overseer/config.yaml. The kit ships five layers: (1) policy + doc templates (handover/roadmap skeletons, ADR/Standing-Decisions format, Tier 1/2/3 authority table, model labels, the RULE #0 seven-tier test contract); (2) Cursor primitives (.cursor/rules/*, .cursor/skills/*, Automation templates); (3) a VCS adapter interface (read_head, read_canonical_anchor, realign, commit_feature, mirror, plus status) with three fail-closed backends — muse+git-mirror, muse-only, git-only; (4) the agent tools (Governance Hygiene Agent = Phase 9A-5, and the Freeze-Step Reviewer); and (5) a language-agnostic vendoring CLI (ok init|sync|status|governance-sync|review; compatibility synonym overseer) that writes .overseer/version.lock and warns on drift. The kit is VCS-agnostic by construction: everything that is identical everywhere lives in the kit; the only per-repo variance (VCS regime, remote names, doc paths, thresholds, SD-log location) lives in .overseer/config.yaml. The kit dogfoods its own rules by being dual-hosted (Muse canonical + GitHub mirror) and governed by its own handover/roadmap. The Freeze-Contract policy (§6) turns SD-3's Thinking → Auto boundary into a machine-checkable rule: any phase output another phase consumes as ground truth without re-deriving is a mandatory reviewed freeze, auto-reviewed by an agent that must cite file+line, with human escalation only on security/irreversibility/real-money/Tier-3 linkage.

§0 — Scope (this Outline only)

This Thinking step freezes, and only freezes:

  1. The distribution decision + rejected alternatives, with rationale (§1).
  2. The kit repository layout (§2).
  3. The .overseer/config.yaml schema — the single per-repo variance point (§3).
  4. The VCS adapter interface + the three fail-closed backends (§4).
  5. The vendoring CLI contract — commands, footprint, version.lock, drift check (§5).
  6. The Freeze-Contract review policy + automation routing (§6).
  7. Versioning, release, and update semantics (§7).
  8. The migration path for the three existing repos (§8).
  9. Security / privacy gate checklist (§9).
  10. The seven-tier test expectation per Build phase + explicit blockers + Definition of Done (§10).
  11. The Build-phase breakdown K1–K6 + governance-sync guidance (§11).

Not in scope (build-later): creating the overseer-kit repo, writing any kit code, CLI, or adapter, installing any hook or Automation, running overseer init against any repo, any env flip, any main merge, any muse push staging. This doc adds no code — only a frozen contract the K-phases implement mechanically.

Compose, do not redesign (frozen boundary): the kit is the productized, DRY form of docs/CROSS-REPO-COORDINATION.md. It does not invent new governance policy; it extracts the existing policy (tiers, model labels, seven-tier tests, handover/roadmap shape, SD log) into a shareable artifact and adds a thin distribution + automation mechanism around it. The Standing Decisions log remains authored by humans in each repo's coordination doc; the kit ships its format and validators, not its contents.

§1 — Distribution decision (frozen) + rejected alternatives

Decision: a standalone overseer-kit repository that is canonical and versioned, injected into consumer repos as a pinned vendored footprint via a language-agnostic CLI, with a .overseer/version.lock and a drift check.

Option Verdict Rationale (verifiable)
Standalone repo + vendored CLI install + pinned version + sync + drift check CHOSEN One canonical source to maintain/perfect; one command updates any workspace; works for Muse-only / Muse+Git / Git-only; usable by any teammate; carries its own governance (dogfood).
Git submodule REJECTED MuseHub is Muse-only, Git/GitHub forbidden (CROSS-REPO-COORDINATION.md VCS table) — a Git submodule cannot mount there at all. Submodules are also hostile to outside collaborators and to Muse's bridge model.
npm / pip package only (as primary) REJECTED as primary Language-locks the system; consumer repos span TypeScript (Scooling), Python (Knowtation, MuseHub plugin), and unknown teammate stacks. A registry package may still be an optional convenience wrapper for the CLI (§5), but the injected footprint must be language-agnostic vendored files.
Folder inside one product repo (e.g. keep it in Scooling) REJECTED Couples the kit's release lifecycle to one product; cannot be shared cleanly with the other repos or externally; re-creates the "one repo owns everyone's process" coupling we are trying to remove.
Status quo — hand-copied per repo REJECTED This is the drift problem: four documented Muse↔Git inversions (GITHUB-MIRROR-RECONCILIATION-FOLLOWUP.md, 2026-06-24 / 06-26 / 07-09 / 07-10) and three separately-maintained handover docs that must be updated by hand.

Why "vendored footprint" and not "runtime dependency": the governance system must keep working offline, with no cloud credentials, and must be auditable inside each repo's own history (the kit's files are visible and diffable in the consumer repo). A pinned vendored copy + version.lock gives reproducibility and an explicit, reviewable update step, which matches the "review-before- write for durable changes" boundary.

§2 — Kit repository layout (frozen)

overseer-kit/
  README.md                         # what it is, install, update, dogfood note
  VERSION                           # single source of the kit's semver (e.g. 0.1.0)
  CHANGELOG.md                      # human-readable release notes, semver-tagged
  docs/
    OVERSEER-KIT-SPEC.md            # the frozen spec (this doc, promoted to the kit)
    FREEZE-CONTRACT-POLICY.md       # §6 policy, canonical copy
    ADAPTER-CONTRACTS.md            # §4 VCS adapter interface, canonical copy
    ROADMAP.md                      # the kit's OWN roadmap (dogfood)
    OVERSEER-HANDOVER.md            # the kit's OWN handover (dogfood)
  templates/                        # copied verbatim (with token substitution) into consumers
    OVERSEER-HANDOVER.template.md
    ROADMAP.template.md
    STANDING-DECISIONS.template.md  # ADR format only, not contents
    CROSS-REPO-COORDINATION.template.md
  policy/                           # machine-readable policy the tools enforce
    tiers.yaml                      # Tier 1/2/3 authority table
    model-labels.yaml               # Thinking | Auto | Thinking → Auto | Operator + Auto
    test-tiers.yaml                 # the seven RULE #0 tiers + what each proves
    freeze-contract.schema.yaml     # phase output/frozen-input declaration schema
  cursor/                           # portable Cursor primitives
    rules/                          # .cursor/rules/* fragments (governance-sync, no-docs-only-PR, etc.)
    skills/                         # .cursor/skills/* (governance-sync, freeze-review)
    automations/                    # Automation templates (session-end, on-merge)
  adapters/                         # VCS adapter interface + three backends (§4)
    interface.md                    # frozen method contract
    muse_git_mirror/                # backend impl (build-later)
    muse_only/
    git_only/
  tools/                            # the agent tools (build-later)
    governance_hygiene/             # Phase 9A-5
    freeze_reviewer/                # §6 reviewer
  cli/                              # the vendoring CLI (build-later)
    overseer                        # entrypoint (POSIX shell shim → portable runtime)
  test/                             # seven-tier tests for kit code (RULE #0)
  .overseer/                        # the kit's OWN config (dogfood: git-only or muse+git)
    config.yaml
    version.lock

Rationale for the split: templates/ + policy/ + cursor/ are what get vendored into consumers (small, language-agnostic, diffable). adapters/ + tools/ + cli/ are the engine that the CLI runs; they are versioned in the kit and referenced by the pinned footprint, not duplicated wholesale into every consumer.

§3 — .overseer/config.yaml — the single per-repo variance point (frozen)

Everything shared is in the kit; the only thing each repo customizes is this file. Frozen schema (values shown are illustrative, not defaults to assume):

overseer_config_version: 1          # schema version, integer; fail closed if unknown

repo:
  name: scooling                    # human label used in handover/roadmap tokens
  root_relative_docs: docs          # where the living docs live in this repo

vcs:
  regime: muse+git-mirror           # one of: muse+git-mirror | muse-only | git-only
  canonical: muse                   # muse | git — which history is source of truth
  git:
    remote: origin                  # only when regime includes git
    main_branch: main
    mirror_branch: muse-mirror      # the permanent mirror branch (SD-14)
    feature_branch_pattern: "feat/{slug}"
  muse:
    staging_remote: staging         # only when regime includes muse; null for git-only
    main_branch: main

docs:
  handover: OVERSEER-HANDOVER.md
  roadmap: ROADMAP.md
  coordination: CROSS-REPO-COORDINATION.md   # null if the repo has none
  standing_decisions: CROSS-REPO-COORDINATION.md   # where the SD/ADR log lives

thresholds:
  realign_max_commits: 50           # muse realignment dry-run guard (§4, 9A-5 spec)
  drift_warn_only: true             # drift check warns; never blocks or writes

freeze_contract:
  enabled: true
  reviewer: agent                   # agent | human — default agent (auto-first)
  human_escalation:                 # conditions that force human review (§6)
    - security
    - irreversible
    - real_money
    - gates_tier3

Fail-closed rule (frozen): if .overseer/config.yaml is missing, unparseable, has an unknown overseer_config_version, or names a vcs.regime the installed kit does not implement, every kit tool stops and reports — it never guesses a regime, never writes, never realigns.

No secrets in config (frozen): .overseer/config.yaml holds names and booleans only — no tokens, no URLs with credentials, no absolute machine paths, no hostnames beyond a remote name. It is safe to commit. The kit's .museignore/.gitignore templates keep version.lock committed but exclude any local scratch the tools produce.

§4 — VCS adapter interface (frozen) + three fail-closed backends

The recurring inversion failure lives at the VCS boundary, so the kit isolates it behind one interface implemented by three backends. Every method is read-fail-closed: any underlying command failure returns a typed error that halts the caller; no method guesses state.

Frozen method contract (language-neutral; concrete signatures are K2 Build work):

Method Input Output (typed) Fail-closed behavior
status() none { regime, dirty: bool, branch, notes[] } If the VCS status command errors → ReadError{command}; caller stops.
read_head() { ref } (e.g. origin/main) { sha, kind } Missing ref / command error → ReadError; never returns a fabricated sha.
read_canonical_anchor() none { anchor_sha, source } For muse+git: the Muse↔Git bridge anchor. For muse-only: muse log main tip. For git-only: origin/main tip. Command error → ReadError.
realign() { dry_run, max_commits } { would_import: n, applied: bool, from_ref, to_ref } Only defined for regimes with a canonical/mirror split. Dry-run first; if n > max_commits → refuse + report. git-only = no-op (returns applied:false, reason:"single-history").
commit_feature() { branch, message, paths[] } { committed: bool, sha } Tier 1 only. Refuses if branch resolves to a main/canonical-main; never commits to protected refs.
mirror() { dry_run } { diff_summary, pushed: bool } Tier 3-linked; in the kit's runtime it stops for operator authorization before any push; dry_run reports the mirror delta only.

Backend behaviors (frozen):

  • muse+git-mirror (Scooling, Knowtation): canonical = Muse; read_canonical_anchor reads the bridge anchor; realign wraps the muse bridge git-import --incremental --preserve-merge-commits recovery from GITHUB-MIRROR-RECONCILIATION-FOLLOWUP.md, guarded by dry-run + realign_max_commits; mirror follows SD-14 (muse-mirror → main, never git push origin main). Never merges a feature branch directly to GitHub main.
  • muse-only (MuseHub): git/mirror methods are hard no-ops that report "git forbidden in this regime"; read_head/read_canonical_anchor use muse log; realign is a no-op (single canonical history). Honors "never run git/gh in MuseHub."
  • git-only (external developers, no Muse): canonical = Git origin/main; read_canonical_anchor = origin/main tip; realign = no-op (single history); mirror = no-op. Governance-sync, drift check, freeze review, handover/roadmap upkeep all still work — this is what makes the kit usable by any teammate with a plain GitHub repo.

Cross-repo cwd safety (frozen, from CROSS-REPO-COORDINATION.md 2026-06-20 note): every Muse invocation the backends make MUST use an explicit muse -C <absolute-repo-root> (or a genuine cd) and confirm branch + HEAD before any add/commit/checkout, so an agent's cwd cannot leak one repo's state into another.

§5 — Vendoring CLI contract (frozen)

One entrypoint, ok (compatibility synonym overseer), runnable with no global install (POSIX shell shims cli/ok and cli/overseer in the kit engine tree that locate the portable runtime; cli/overseer prints a one-line stderr deprecation per process and runs the same runtime as cli/ok; an optional published package is a convenience wrapper only, never the sole path). All commands are read-first and idempotent; running any command twice with no external change produces the same result.

Command Purpose Writes? Idempotent
ok init First install into a repo: create .overseer/config.yaml (interactive/regime-detected), vendor the footprint, write version.lock. Refuses to overwrite an existing config without --force. Yes (footprint + config) Yes (re-run = no-op if lock matches)
ok sync Update the vendored footprint to the kit version the CLI carries; rewrite version.lock; show a diff of changed template/policy/cursor files. Yes (footprint) Yes
ok status Report: kit version, version.lock version, drift (behind/ahead), VCS regime, dirty tree, last governance-sync. Read-only. PMHF additive: JSON key land_closeout ({state, ok, message, remediation, land_phase, freshness_ok, d1, optional_pr_merged}); --exit-code folds land_closeout.ok into the existing 2 tier (no renumbering; land_a_in_progress stays ok so waiting for merge never false-fails). Default status path never invokes gh for land closeout (probe_merged_pr=False). LT additive: JSON keys footprint_coverage, ide_workspace_hint, optional_feature_tips, optional verification_evidence_gate; --exit-code folds footprint_coverage.ok and verification_evidence_gate.ok (require mode only) into the existing 2 tier. Frozen: docs/archive/phases/PHASE-LT-LOOP-TIGHTENING.md. ISR additive: optional JSON key independent_second_reviewer_gate (absent when the probe skips); --exit-code folds independent_second_reviewer_gate.ok (require mode only) into the existing 2 tier. Frozen: docs/archive/phases/PHASE-ISR-INDEPENDENT-SECOND-REVIEWER.md §ISR.6. No Yes
ok governance-sync Run the Governance Hygiene Agent (Phase 9A-5) against this repo's .overseer/config.yaml: detect drift between docs and true VCS state, patch handover/roadmap, guard-realign, commit to a feature branch. --dry-run = report only. Yes (docs, feature branch) Yes
ok review --freeze <path> Run the Freeze-Step Reviewer (§6) on a freeze artifact; emit findings with file+line citations; set exit status by verdict; escalate to human per config. --dry-run prints the review only. No (review output only) Yes
ok check-ok [--path PATH] [--topic SLUG] [--scaffold-only] [--dry-run] … Check OK ad-hoc honesty check: scaffold a side-check freeze under docs/reviews/ when needed, then run the same Freeze-Step Reviewer as ok review --freeze (no new docs.lanes entry). Portable skill /check-ok ships to .cursor/skills/ and .claude/skills/; Copilot/others use CLI + docs/CHECK-OK.md. Synonym: ok check-if-ok. Yes (scaffold file only when created) Yes (re-run reuses existing artifact)
ok next [--lane NAME] Print NEXT (ONS): read-only extract of the KH1 paste-ready fence from the config-driven handover; prints under ## CURRENT NEXT — paste this. Synonym: ok governance-sync --print-next (short-circuits; no R1–R5 / patches / commits). Fail-closed exit 37 when handover/fence malformed. Not ok workspace check-next. Frozen: docs/archive/phases/PHASE-ONS-OPERATOR-NEXT-SURFACING.md. No Yes
ok handover-compact [--dry-run\|--write] [--keep N] [--lane NAME] Archive old handover change-log bullets to {docs}/archive/handover/CHANGE-LOG.md. Default dry-run when neither flag given. --keep default 15 (minimum 5). Does not regenerate NEXT. Frozen: docs/archive/phases/PHASE-LT-LOOP-TIGHTENING.md. Yes (with --write only) Yes
ok workspace status\|check-next\|doctor Multi-repo constellation / workspace lanes (K13): report members/roles/LIVE PRIMARY, fail closed on stale relays (check-next exit 35), doctor board_name_violation for bare board filenames. Read-only. ok status --workspace attaches report without implying workspace.ok from single-repo green. Frozen: docs/archive/phases/MULTI-REPO-WORKSPACE-LANES-FREEZE.md. No Yes
ok pr-land --pr <N> --authorized "<reason>" Authorized wait-for-green merge (Tier-3 operator-delegated): poll gh pr checks until settled, refuse on failure (exit 2), merge only when green — never blind --auto. PLS additive: optional close_ritual.post_land_sync ff-only post-step after a successful MERGED outcome (default off; dirty tree warn/skip, never clobber); always-present post_land_sync result object; exit 36 on hard sync fail after a real merge (never reuses 6). Frozen: docs/archive/phases/PHASE-PR-LAND-AFTER-CHECKS.md + docs/archive/phases/PHASE-PLS-POST-LAND-MAIN-SYNC.md. Yes (GitHub merge; optional local ff-only pull) Yes (already-MERGED re-run stays exit 0)
ok verify-step [--manifest PATH] [--step ID \| --through current \| --all] [--policy PATH] [--dry-run] [--json] L1 checkpoint orchestrator (K9b): run domain verify scripts in template order; update active manifest per step; optional --dry-run plan-only. Module gate: checkpoints.enabled must be true. Exit extensions: 10 verify fail, 11 step order. Yes (manifest + optional progress) Yes (re-verify overwrites)
ok honesty-status --hook HOOK --artifact PATH [--producer-session ID] [--json] L2 co-requirement check (K10): require a passing independent verdict for artifact SHA before board/handoff/register hooks. Module gate: honesty.enabled must be true. Exit extensions: 20 missing verdict, 4 hook not enabled / module off. ISR additive: Mode D --independent-second-review PHASE_ID with optional --producer-session / --frozen-spec; exit 38 + missing_independent_second_review when require_independent_second_reviewer: require and no match. Frozen: docs/archive/phases/PHASE-ISR-INDEPENDENT-SECOND-REVIEWER.md. No Yes
ok ledger append --kind KIND [--file JSON_PATH \| --stdin] L2 verdict ledger append (K10): hash-chained JSONL entry with role gates. Auto-genesis on first append. Exit extensions: 21–24, 22 on verify. Yes (ledger) Append-only
ok ledger verify L2 ledger chain verification (K10). Missing/empty ledger → 0. Break → 22. No Yes
ok ledger show [--last N] L2 ledger read (K10): print last N JSONL records. Missing/empty → 0 with no lines. Default N=20. No Yes
ok upgrade-regime --from muse-only --to muse+git-mirror [--dry-run \| --apply] [--live-bridge] [--force] [-y] Stage 3 kit ceremony (Track O / O3): ordered muse-only → muse+git-mirror upgrade composing init/sync/status + K7 bridge gates (C0–C5 / G1–G8). --dry-run default when --apply absent. --live-bridge requires gate success + -y (C6); never performs C8 merge. Frozen detail: docs/archive/phases/PHASE-TRACK-O-O2-STAGE3-UPGRADE-CEREMONY.md. Yes (config + footprint when --apply; optional C7 via deploy script) Yes (complete upgrade → exit 0)
ok hosted-dashboard [--port PORT] [--bind ADDRESS] [--config PATH] [--open] Read-only remote governance dashboard preview (Hosted governance dashboard): GitHub/MuseHub read glance of ROADMAP/HANDOVER/gates; Bearer viewer auth; default 127.0.0.1:8766. Never mutates git/muse/GitHub. Operator runbook: docs/HOSTED-GOVERNANCE-DASHBOARD-OPERATOR-RUNBOOK.md. Frozen: docs/archive/phases/PHASE-HOSTED-GOVERNANCE-DASHBOARD.md. No Yes
ok land-closeout [--json] [--probe-merged-pr\|--no-probe-merged-pr] Post-merge land closeout probe (PMHF §PMHF.6.3): print LandCloseoutReport; exit 0 when report.ok else 2. Never merges; never writes docs. Refuses “land complete” while post_merge_incomplete / land_b_in_progress / unreadable, with frozen land-b remediation. --probe-merged-pr default: on for git regimes, off for muse-only (no git/gh). Frozen: docs/archive/phases/PHASE-PMHF-POST-MERGE-HANDOVER-FRESHNESS.md. No Yes

Vendored footprint (frozen — what init/sync copy into a consumer): the contents of templates/ (token-substituted with .overseer/config.yaml values), policy/, and cursor/ (rules → .cursor/rules/; skills → both .cursor/skills/** and .claude/skills/** so Cursor and Claude Code share the same skill bytes), plus a thin pointer to the kit engine version. The engine (adapters/, tools/, cli/) is carried by the CLI itself and pinned by version.lock — it is not copied file-by-file into every repo, keeping the footprint small and diffable.

version.lock (frozen shape):

kit_version: 0.1.0                  # matches overseer-kit/VERSION at install/sync time
installed_at: "<iso-8601>"          # timestamp only, no user identity
footprint_digest: "sha256:<hex>"    # digest of the vendored files, for drift detection
config_version: 1

Drift check (frozen): ok status compares the local footprint_digest + kit_version against the kit the CLI carries. If behind, it warns with the version delta and the changed files; per thresholds.drift_warn_only it never auto-updates or blocks. Updating is always the explicit ok sync step (review-before-write).

K4a refinement (frozen detail): the per-command argument contract, exit-code taxonomy, the extended (spec-compatible, additive) version.lock shape with a per-file manifest, and the deterministic footprint_digest algorithm are frozen in docs/archive/phases/PHASE-K4-VENDORING-CLI-CONTRACT.md. K4b builds against that document.

Desktop installers (additive distribution channel): signed platform installers (.dmg / .msi / .AppImage) are an optional distribution path for the existing ok app loopback UI and Tauri shell (desktop/). They do not add a required CLI subcommand: Path A (HANDOVER) and Path B (ok app) remain complete without installers. Auto v1 installers still require host Python 3.11+. Release CI + helpers live under .github/workflows/desktop-release.yml and tools/desktop_release/; operator runbook: docs/TRACK-Q-DESKTOP-OPERATOR-RUNBOOK.md. Frozen detail: docs/archive/phases/PHASE-Q3-RELEASE-DESKTOP-INSTALLERS.md.

§6 — Freeze-Contract review policy (frozen)

This formalizes the operator's closing requirement: anything that is a frozen spec, or that a later step depends on as ground truth, must be reviewed — and the review should be as automated as possible, interrupting a human only when genuinely necessary.

§6.1 — Declarations (the machine-checkable part)

Each phase in a roadmap declares, in a small structured block (schema = policy/freeze-contract.schema.yaml):

phase: 9A-5
outputs:                            # artifacts this phase produces
  - id: hygiene-agent-spec
    path: docs/archive/phases/PHASE-9A-5-GOVERNANCE-HYGIENE-AGENT-OUTLINE.md
    frozen: true                    # declared frozen = downstream may treat as ground truth
frozen_inputs:                      # artifacts this phase consumes without re-deriving
  - id: kit-adapter-interface
    path: docs/OVERSEER-KIT-ARCHITECTURE-OUTLINE.md#4

The rule (frozen): an edge exists from phase A to phase B when B lists one of A's outputs in its frozen_inputs. If that output is frozen: true and B treats it as ground truth without re-deriving it, the edge is a mandatory reviewed freeze. This is exactly the SD-3 Thinking → Auto boundary (a Thinking phase freezes a contract; an Auto phase builds against it without re-deriving it) made explicit and machine-detectable.

Cheap heuristic the reviewer applies (operator's own test): "does a later phase treat this output as ground truth without re-deriving it?" If yes → review it. Pure mechanical Auto builds against an already-frozen, already-reviewed spec are not re-reviewed (lower value, per the operator's recommendation).

§6.2 — Automated review (default path)

  • The Freeze-Step Reviewer runs (via overseer review --freeze <path>, or the K5 Automation on freeze commits) on every artifact declared frozen: true.
  • It must cite file + line for every finding, so the parent/operator can verify rather than trust — this is the safeguard that lets a real finding be distinguished from a reviewer hallucination (the operator's explicit requirement).
  • Verdict is one of pass / findings / blocked. findings returns the cited list; pass records a review stamp in the artifact's freeze block; blocked triggers §6.3.

K5 design requirement (frozen): the reviewer is user-configurable per repo — local model, remote API, or human — via an extended freeze_contract block in .overseer/config.yaml. The K5a Thinking phase must freeze this config schema before K5b builds the reviewer. Required fields:

freeze_contract:
  reviewer:
    mode: agent            # agent | human
    model: thinking-high   # label from policy/model-labels.yaml — never a hardcoded vendor slug
    provider: local        # local | api  — portability and privacy/cost choice
    fallback: human        # what to do if the model/provider is unreachable → fail-closed to human
  human_escalation: [security, irreversible, real_money, gates_tier3]

Guardrails (frozen): (1) fail-closed — if provider is unreachable, fall back to human rather than skipping review; (2) model is a label, never a vendor slug, so the config is portable across providers; (3) provider: local is a first-class option — the kit must work fully offline with no API key required; (4) no core review capability may be api-only. These are non-negotiable: they preserve the kit's offline/repo-agnostic promise.

K5a refinement (frozen detail): the overseer review --freeze argument contract, review-specific exit codes (7 findings / 8 blocked-or-human), extended freeze_contract.reviewer schema with legacy-string normalization, finding/verdict/stamp/escalation rules, provider reachability + human packet, Automation degrade path, and the K5b seven-tier test matrix are frozen in docs/archive/phases/PHASE-K5-FREEZE-REVIEWER-CONTRACT.md. K5b builds against that document.

§6.3 — Human escalation (only when necessary)

The reviewer escalates to a human only when a finding (or the artifact's declared linkage) hits one of the human_escalation conditions in .overseer/config.yaml:

  • security — auth, scope, secrets, injection surface, redaction.
  • irreversible — data deletion, migrations, anything not cheaply revertible.
  • real_money — billing/live model spend (composes with SD-16).
  • gates_tier3 — the frozen artifact gates a Tier 3 action (merge to main, muse push staging, live-capability flip, cross-repo merge).

Everything else the agent reviewer resolves or reports without a human stop. This keeps human review rare and meaningful and satisfies "as automated as possible."

§6.4 — How it layers on Tier 1/2/3 (additive, not a rewrite)

The Freeze-Contract sits on top of the existing Decision Authority tiers:

  • Tier 1 (feature-branch commits, tests, formatting) is unchanged — no freeze review needed.
  • Tier 2 (recommend-and-confirm) is unchanged.
  • Tier 3 (main merges, staging push, live flips) is unchanged as the human hard-gate — the Freeze-Contract simply guarantees a reviewed freeze exists before a Tier-3 action consumes it, and routes the automated-vs-human decision.

§7 — Versioning, release, and update semantics (frozen)

  • Semver in overseer-kit/VERSION + CHANGELOG.md. MAJOR = breaking template/policy/adapter contract change; MINOR = additive policy/template/tool; PATCH = fixes.
  • Consumers pin via version.lock. overseer status reports drift; overseer sync performs the explicit, reviewed update and rewrites the lock.
  • Config compatibility: overseer_config_version is independent of kit semver; a kit that does not understand a config version fails closed (§3).
  • The kit governs itself (dogfood): the kit repo carries its own docs/ROADMAP.md + docs/OVERSEER-HANDOVER.md and is developed under the same phase/commit/freeze discipline it ships. Its own release is a phase with the same Definition of Done (§10).

§8 — Migration path for the three existing repos (frozen order)

Canonical-first, one repo at a time, non-destructive (the kit is added alongside existing docs; nothing is deleted until parity is proven):

  1. Scooling first (richest policy source, muse+git-mirror): overseer init with regime muse+git-mirror; vendor templates; map existing docs/OVERSEER-HANDOVER.md + docs/ROADMAP.md as the living docs in .overseer/config.yaml; confirm governance-sync --dry-run reproduces the current hand-maintained state before enabling writes. Standing Decisions log stays in CROSS-REPO-COORDINATION.md (kit ships format only).
  2. Knowtation (muse+git-mirror, plus the no-docs-only-PR-to-main rule): overseer init; confirm the kit's rule fragment matches the existing .cursor/rules/no-docs-only-pr-to-main.mdc before replacing it with the vendored version.
  3. MuseHub (muse-only): overseer init with regime muse-only; verify all git/mirror methods report "git forbidden" and do nothing; map MUSEHUB-OVERSEER-HANDOVER.md + MUSEHUB-ROADMAP.md.
  4. Parity gate: for each repo, the kit-driven governance-sync --dry-run output must match the repo's current hand-maintained handover/roadmap before any hand process is retired. Only after parity is proven (and per each repo's VCS rules) does the repo switch to kit-driven upkeep.
  5. External developer template: publish a git-only quickstart so any teammate can overseer init a plain GitHub repo and get the same discipline.

No migration step merges to main, pushes staging, or flips a gate; each is Tier-1 feature-branch work in its own repo under that repo's VCS rules.

§9 — Security / privacy gate checklist (frozen)

  • No secrets anywhere in the kit or footprint — config is names/booleans only; tools never log tokens, URLs-with-credentials, or absolute machine paths; reviewer output and version.lock carry no identity beyond a timestamp.
  • No hardcoded SHAs in any kit script or template — all shas are read at runtime via the adapter and never committed into automation logic.
  • Fail closed on every read — any status/read_head/read_canonical_anchor failure halts the caller with the exact failing command; no tool ever writes partial state or guesses.
  • Least privilege — muse-only backend cannot invoke git; git-only cannot invoke muse; a regime never gains a capability it did not declare.
  • Injection surface — templates use explicit token substitution from a fixed key set (repo name, doc paths); no arbitrary shell interpolation of doc content; reviewer treats artifact text as data, not as instructions.
  • Review-before-write — every durable change (sync, governance-sync writes, migration) is an explicit reviewable step; drift only warns.
  • Human hard-gates preserved — Tier 3 (main merge, staging push, live flip, payments, secrets) is never automated by the kit.

§10 — Seven-tier test expectation (per Build phase) + blockers + Definition of Done

Per RULE #0, every Build phase that adds code ships all seven tiers. The matrix each K-phase must satisfy (bodies are Build work):

Tier What it proves for the kit
unit Each adapter method, config parse, template token-substitution, and CLI arg-parse behaves per contract, including every fail-closed branch.
integration CLI + adapter + config compose: init/sync/status/governance-sync/review against a fixture repo per regime.
e2e A full session-end governance-sync on a fixture repo produces a correct handover/roadmap patch on a feature branch (no main, no push).
stress Large roadmaps/handovers, many phases, realign at the realign_max_commits boundary, many freeze edges.
data-integrity Idempotency (run-twice = same result); version.lock digest correctness; no partial writes on induced mid-operation failure.
performance status/drift check and a governance-sync complete within a bounded time on a realistic repo; no unbounded VCS scans.
security No secret/identity leakage in outputs/logs; injection-safe templating; regime least-privilege enforced; fail-closed on every simulated read failure.

Inert double / dry-run (frozen): the safe default for both agent tools is a dry-run mode that reports what it would do and writes nothing (governance-sync --dry-run, review --dry-run). This is the kit's equivalent of the "posture hard-false" inert-first pattern.

Blockers (explicit):

Blocker State Consequence
overseer-kit repo does not exist yet OPEN (K1) Nothing installs until K1 bootstraps it.
Muse bridge behavior for realign must be re-verified per Muse version OPEN (K2) muse+git-mirror backend gated on a verified git-import --incremental dry-run.
Cursor Automation availability differs per environment (Agents Window) OPEN (K5) Automation triggers degrade gracefully to the /overseer CLI + slash command when the editor handoff is unavailable.

Definition of Done (every K-phase): deliverables match this frozen spec; required test tiers green locally; no secrets/hardcoded SHAs; fail-closed verified; both governance docs (kit's own ROADMAP + OVERSEER-HANDOVER) updated; feature branch → commit → (push/PR per the kit repo's own VCS rules). No phase is DONE until its tests pass.

§11 — Build-phase breakdown (queued; not this session) + governance sync

| Phase | Scope | Model | | --- | --- | --- | | K1 Bootstrap | Create overseer-kit repo skeleton (§2), VERSION/CHANGELOG, dual-host + self-governance docs, README. | Thinking → Auto | | K2 Config + adapters | .overseer/config.yaml schema (§3) + the VCS adapter interface (§4) + three fail-closed backends + their unit/integration/security tests. | Thinking → Auto | | K3 Extract shared assets | Move the existing handover/roadmap/SD-format/tier/model-label/test-tier policy out of the three repos into templates/ + policy/ + cursor/, token-parameterized. | Auto | | K4 Vendoring CLI | overseer init|sync|status + version.lock + drift check (§5) + seven-tier tests. Contract frozen in docs/archive/phases/PHASE-K4-VENDORING-CLI-CONTRACT.md (K4a); K4b builds against it. | Thinking → Auto | | K5 Freeze reviewer + automation routing | The §6 reviewer (file+line citations, verdicts, escalation) + overseer review + session-end/on-merge Automation templates + tests. Contract frozen in docs/archive/phases/PHASE-K5-FREEZE-REVIEWER-CONTRACT.md (K5a); K5b builds against it. | Thinking → Auto | | 9A-5 Governance Hygiene Agent | The first shipped tool, built against its own frozen spec (PHASE-9A-5-…-OUTLINE.md), rebased onto the K2 adapter interface. | Auto | | K6 Pilot install + migration | overseer init into Scooling → Knowtation → MuseHub per §8; parity gate; external git-only quickstart. | Thinking → Auto |

Governance sync (mandatory on each phase completion): update the owning repo's ROADMAP.md status row + OVERSEER-HANDOVER.md NEXT SESSION together in the closing commit (SD-17); for Thinking → Auto phases emit {K}a/{K}b split prompts per SD-3. A phase that ends without both governance docs updated is INCOMPLETE.

Cross-references

  • docs/CROSS-REPO-COORDINATION.md — the policy source this kit productizes (tiers, SD log, handover protocol, model-split protocol). A pointer to this outline should be added there as part of the roadmap/handover update in this same session.
  • docs/archive/phases/PHASE-9A-5-GOVERNANCE-HYGIENE-AGENT-OUTLINE.md — the first tool, specified against the §4 adapter interface.
  • docs/GITHUB-MIRROR-RECONCILIATION-FOLLOWUP.md — the failure pattern §4's backends prevent.
  • docs/ROADMAP.md — Phase 9A-5 + the Overseer Kit (K1–K6) track added to the queue.
File History 1 commit
sha256:6abcf1fa82a7a621ccbc945f19acdba5bc0db54569599404a1452fb4a096a199 fix(ISR): default require_independent_second_reviewer to require Human minor ⚠ 4 hours ago