aaronrene / overseer-kit public
ROADMAP.md markdown
123 lines 16.0 KB
Raw
sha256:4671b7f787ddbe63ced31c895b688c77ab495653b65a730b423329f26b3c1439 feat: K1-P1 complete — agent provenance, build-verification… Sonnet 4.6 patch 57 days ago

Overseer Kit — Roadmap

Phase Model Key

Label Meaning
Thinking Design + freeze spec before any build
Auto Mechanical implementation against frozen spec
Thinking → Auto Thinking design + tests, then Auto build

Build queue

Phase Model Status Deliverable
K1 Bootstrap Thinking → Auto DONE Repo skeleton, promoted spec, dogfood governance docs
K2 Config + adapters Thinking → Auto DONE .overseer/config.yaml schema + VCS adapter interface + three fail-closed backends
K3 Extract shared assets Auto DONE Templates + policy + cursor fragments; adapters/templating.py
K4a Freeze CLI contract Thinking DONE Frozen init\|sync\|status arg contract + version.lock shape + footprint_digest algorithm + K4b seven-tier matrix (docs/PHASE-K4-VENDORING-CLI-CONTRACT.md)
K4b Vendoring CLI build Auto DONE overseer init\|sync\|status + version.lock + footprint_digest + drift check; POSIX shim → cli/ Python runtime; 108 tests green (§K4.10 seven tiers)
K5a Freeze reviewer contract Thinking DONE Frozen overseer review --freeze arg contract + exit codes 7/8 + extended freeze_contract.reviewer.{mode,model,provider,fallback} schema (legacy string normalization; local\|api; fallback: human fail-closed; reviewer_models labels) + findings/verdicts/stamp/escalation + Automation degrade path + K5b seven-tier matrix (docs/PHASE-K5-FREEZE-REVIEWER-CONTRACT.md). Independent freeze review round 3 → pass (F1–F9 + N1–N3 resolved). Cleared for K5b.
K5b Freeze reviewer build Auto DONE overseer review --freeze + nested freeze_contract.reviewer parse (legacy string normalization) + reviewer_models in policy/model-labels.yaml + tools/freeze_reviewer/ engine (injectable local|api; fallback: human fail-closed) + §K5.9 report + stamp write + Automation templates + seven-tier tests. Cleared by K5b-r2 pass + PR #6 on main (not by premature PR #5 merge alone).
K5b-r Merge gate review Thinking DONE Round 1 blocked (F1–F6 on PR #5). F1–F5 fixed (PR #6). K5b-r2 → pass (review). K5b cleared.
9A-5 Governance Hygiene Agent Auto DONE overseer governance-sync [--dry-run] against kit VCS adapter — tools/governance_hygiene/ + seven-tier tests (181 green)
K6a Freeze pilot install matrix Thinking DONE Frozen install order + per-repo config matrix + init --migrate preserve contract + parity gate (P1–P7 + per-repo extras) + Muse working_dir / VF . docs-root seams + K6b seven-tier matrix (docs/PHASE-K6-PILOT-INSTALL-MATRIX.md). Rounds 1–5 blocked → fixes through 5-fix; Round 6 findings (R6-M1) → 6-fix; K6a-r7 → pass (R6-M1 + R5/R4 spot-check + full §K6.0–§K6.10 regress). Cleared for K6b.
K6b Pilot install build Auto DONE Additive init --migrate + --include-preserved; vcs.muse.working_dir + root_relative_docs: "." seams; origin: preserved\|kit lock + kit-only digest; tests/fixtures/pilot/*; docs/GIT-ONLY-QUICKSTART.md + docs/K6-PILOT-OPERATOR-RUNBOOK.md; seven-tier tests (224 green). Live consumer inits remain operator-gated; no gate flips; no K7 muse dogfood.
K7a Freeze muse+git-mirror dogfood Thinking DONE Frozen dogfood steps + regime-conditional footprint + parity K7.P1–P10 + §K7.5 guardrail + §K7.8 matrix (docs/PHASE-K7-MUSE-GIT-MIRROR-DOGFOOD.md). K7a-r1 → findings → 1-fix → K7a-r2 → pass (M1/M2/N1–N3 confirmed RESOLVED; full §K7.0–§K7.10 regress clean). Cleared for K7b. No Build; no live muse bridge export on the dev tree.
K7b Dogfood muse+git-mirror build Auto DONE Footprint assets (MUSE-BRIDGE-WORKFLOW.template.md, muse-bridge-deploy.sh S1–S13), regime-conditional resolve_footprint, executable script write, config-overseer-kit-dogfood.yaml fixture, docs/K7-DOGFOOD-OPERATOR-RUNBOOK.md, seven-tier tests (254 green). No live git-export on dev tree.
K7 operator live dogfood Operator DONE D2–D5 flip to muse+git-mirror; first safe bridge via .muse/mirror/ (209cd3f); PR #10 merged (Tier-3); adapter rev-parse --abbrev-ref HEAD fix; deploy template re-synced; 255 tests green.
K8a Freeze multi-lane docs Thinking DONE Frozen docs.lanes + docs.default_lane schema + governance-sync --lane / --all-lanes contract (docs/PHASE-K8-MULTI-LANE-DOCS-CONTRACT.md).
K8b Multi-lane docs build Auto DONE docs.lanes + default_lane in config; governance-sync --lane / --all-lanes; all-lane footprint; fixture config-two-lane.yaml; 266 tests green.
K9a Freeze L1+L2 modules Thinking DONE Contract in docs/PHASE-K9A-L1-L2-MODULE-FREEZE.md. Rounds 1–8 → findings + fixes; K9a-r9 → pass (all prior findings confirmed RESOLVED; full §K9.0–§K9.19 regress clean). Cleared for K9b (L1) and K10 (L2).
K9b Checkpoint plugin build Auto DONE L1 verify-step orchestrator + config parse + fixture pack + seven-tier tests (302 green)
KH1 Handover relay standard Thinking DONE KH1-r2 → pass. Contract + dogfood handover aligned; §KH1.6 close-out complete (🆗 branding lock + Track P seed).
KH1b Substrate + gate reminders Auto DONE §1 substrate health: tools/substrate_health/ fail-closed on hollow .muse/. §2 gate reminders: tools/governance_gates/ + governance_gates config + overseer status pending-gates + governance-sync footer + handover template checklist (§KH1.9). 399 tests green.
Track P / P0 Thinking DONE Agent identity & signed provenance freeze — docs/PHASE-TRACK-P-P0-AGENT-PROVENANCE.md reviewed → pass (P0-r2), stamp digest sha256:7db8681…. Optional provenance envelope (agent_id/model_id/Ed25519 sig) on ledger entries; canonical hash excludes provenance.sig (v1 chain unbroken); soft under git-only, hard under Muse. Shared schema with Muse social domain. Social stays consumer-only.
Track P / P1 Auto DONE Build verified → pass (P1-BV-r2). Optional provenance envelope + Ed25519 verify + require_agent_signature + exit codes 25/26; canonical hash excludes provenance.sig (v1 chain unbroken). Build-verification round 1 raised BV1 (§P0.6 parity: verify did not emit 2 on hash-consistent malformed provenance) → fixed in tools/honesty/ledger.py verify_chain + CLI message + regression test; round 2 pass. 429 tests green (+30 §P0.8).
Track P / P-route Thinking → Auto TODO Declarative model-routing policy (not a runtime dispatcher). policy/model-routing.yaml: map position/phase-tier/gate → model tier + fallback; the runtime (Cursor, OpenRouter, Scooling) consumes it. Kit stays the rule-holder, never the executor. Extends policy/model-labels.yaml. Needs Thinking freeze (P0-style) before build. No model calls added to the kit.
Track P / P-cost Thinking → Auto TODO Cost-awareness surface (not a dollar pricer). Surface each phase's tier/position + a "paid step before spend" flag on overseer status / handover (aligns with vision §1.2 fail-closed-before-spend). Actual dollar math stays in the runtime that knows its provider/OpenRouter prices — kit is price-agnostic by design. Needs Thinking freeze before build.
Track P / P-evidence Thinking → Auto TODO Verification evidence capture. Extend build-verification + honesty ledger to record verification artifacts (test-output hash, deploy/health check ref, screenshot ref) as ledger evidence — closes the "claims vs verifiable state" gap (build-verification V8). Reuses the L2 ledger. Needs Thinking freeze before build.
Track Q / Q0 Freeze Overseer App Thinking TODO Freeze contract for overseer app: local-only web UI over the existing Python engine (zero engine rewrite — reuses cli//tools//adapters/ as-is); scope = read/act on status, ROADMAP/HANDOVER, review --freeze, governance-sync, ledger/honesty-status; bind 127.0.0.1-only (no LAN/remote exposure by default); auth story for a local server; fail-closed parity with the CLI (no new capabilities, no bypass of gates); seven-tier matrix. Boundary: a frontend/distribution of governance, never a runtime/dispatcher/model-host. Contract doc: docs/PHASE-TRACK-Q-Q0-OVERSEER-APP.md (to be drafted).
Track Q / Q1 Local web UI build Auto TODO Build overseer app against the frozen Q0 contract: FastAPI/stdlib localhost server + minimal web frontend calling the existing engine functions directly (no HTTP re-implementation of CLI logic); read-only views first (status/roadmap/handover/gates), then gated write actions (review --freeze, governance-sync) behind the same fail-closed checks as the CLI. Gated on /build-verification-review.
Track Q / Q2 Tauri desktop packaging Auto TODO Package Q1's local web UI into an installable cross-platform desktop app using Tauri (bundles the Python engine + serves the same localhost UI in a native window; macOS/Windows/Linux from one codebase). No new engine logic — packaging only. Native macOS/SwiftUI explicitly deferred (would either shell out to the same CLI or require a full parallel rewrite — not worth it before Q1 proves demand). Gated on /build-verification-review.
K10 Honesty module Auto DONE L2 honesty-status + ledger {append,verify,show} + role gates + fixture pack + seven-tier tests (340 green); SPEC §5 updated
K11 API/CI freeze provider Auto DONE Headless provider: api HTTP client (/health, /review) + OVERSEER_REVIEW_API_KEY/OVERSEER_REVIEW_API_URL + GitHub Actions example + templates/ci/ vendored workflow; seven-tier K11 tests (361 green)
K12 / Track N Thinking → Auto DONE Public landing, scenario gallery, GitHub→MuseHub funnel, Apache-2.0 LICENSE, SECURITY.md; tools/landing/ validator; seven-tier K12 tests (380 total green)

Vision baton: docs/OVERSEER-KIT-LAYERED-HONESTY-VISION.md (expanded)
K9a contract: docs/PHASE-K9A-L1-L2-MODULE-FREEZE.md
Consumer pattern: docs/CONSUMER-ADAPTER-PATTERN.md
Handover UX debt: none (KH1 + KH1b DONE)

Exploration backlog (ideas — NOT queued; each needs its own Thinking freeze before it becomes a phase)

These are captured so they are not lost. None are committed scope. Each must pass a P0-style Thinking freeze (and clear the "governance, not runtime" boundary) before entering the build queue.

Idea Sketch Boundary check
P-deploy — deployment gate Live-deploy sibling of build-verification: a gate that records a verifiable deploy/health check before a "shipped" claim can be marked DONE. Fits the transcript's "always-on agent with root access deploying to public URLs" risk. Kit records/gates the claim; it never performs the deploy.
Hosted governance dashboard Read-only web view of a repo's governance state (roadmap/handover/gates) sourced from GitHub/MuseHub APIs — for "see my org's governance at a glance" without a local install. Distinct from Track Q (queued below): this variant is hosted/remote and read-only; it cannot touch local repos, git, or muse. Read-only; the authoritative workflow stays local (repo + git/muse).
P-route runtime reference An example runtime adapter (in a consumer repo, e.g. Scooling) that consumes P-route policy + OpenRouter — to prove the policy end-to-end. Lives in a consumer, not the kit (per AGENTS.md — Scooling 9A router is reference-only).

Dogfood integrity gate (mandatory — not optional)

When vcs.regime is muse+git-mirror or muse-only, overseer status --exit-code must report substrate.ok: true before any phase on this repo is marked DONE. Hollow .muse/ (config flip without K7 D2 muse init) is the exact Muse↔Git inversion failure mode this kit exists to catch. Remediation: muse init --force . (Tier 1).

Regime capability tiers (git-only baseline → MuseHub-enhanced)

The kit is fully usable on GitHub alone; MuseHub is an optional substrate that unlocks deeper capability. Same commands, same governance — more power when the canonical history is Muse.

Capability git-only (baseline, no Muse) muse+git-mirror (MuseHub substrate)
init / sync / status / drift Full Full
Governance docs + freeze review Full Full
Canonical history GitHub main MuseHub (content-addressed, sha256: commit ids)
realign (drift-repair vs canonical anchor) No-op (single history) Active — detects/repairs Muse↔Git inversion (the GITHUB-MIRROR-RECONCILIATION-FOLLOWUP.md failure)
mirror (SD-14 safe export) No-op Active — isolated .muse/mirror/ export → muse-mirror PR
Provenance / version enrichment Git commit metadata only MuseHub version + provenance + social layer
Route to MuseHub onboarding — The vendored bridge workflow is the introduction path

Frozen guardrail (K7 design principle): No core governance feature may ever be MuseHub-only. Every baseline capability (init/sync/status, drift, footprint digest, templates, policy, freeze review, governance-sync) must remain fully functional on git-only. MuseHub may deepen a capability (realign, mirror, provenance/version enrichment) but never gate the baseline. This keeps the GitHub-only promise credible and makes the MuseHub value proposition about superior depth, not withheld function. The VCS adapter interface (spec §4) enforces this seam: git-only implements realign/mirror as reporting no-ops; muse+git-mirror implements them for real; the CLI calls the same method names in both regimes.

Reference repos (consumers, not owners)

Repo Regime Customization point
Scooling muse+git-mirror Product runtime in src/phase9a/ (reference, not vendored)
Knowtation muse+git-mirror Canonical Flow/store; kit owns governance only
MuseHub muse-only Plugin governance; git forbidden
VideoFactory git-only Track H honest-factory domain freeze specs
Any external project git-only .overseer/config.yaml only

Definition of Done (every phase)

  • Deliverables match docs/OVERSEER-KIT-SPEC.md
  • Required seven-tier tests green locally
  • No secrets committed
  • Both docs/ROADMAP.md and docs/OVERSEER-HANDOVER.md updated together

Cross-references

  • docs/OVERSEER-KIT-SPEC.md — frozen architecture
  • docs/PHASE-K4-VENDORING-CLI-CONTRACT.md — frozen K4 CLI contract (K4a); K4b builds against it
  • docs/PHASE-K5-FREEZE-REVIEWER-CONTRACT.md — frozen K5 reviewer contract (K5a); K5b builds against it
  • docs/PHASE-K6-PILOT-INSTALL-MATRIX.md — frozen K6 pilot install matrix (K6a); K6b builds against it
  • docs/PHASE-K7-MUSE-GIT-MIRROR-DOGFOOD.md — frozen K7 dogfood design (K7a); K7b builds against it
  • docs/PHASE-K8-MULTI-LANE-DOCS-CONTRACT.md — frozen K8 multi-lane docs (K8a); K8b builds against it
  • docs/PHASE-K9A-L1-L2-MODULE-FREEZE.md — K9a L1+L2 module freeze (K9a-r9 → pass); K9b/K10 build against it
  • docs/PHASE-K12-TRACK-N-LANDING-CONTRACT.md — K12 Track N landing freeze (K12 build against it)
  • docs/PHASE-KH1-HANDOVER-RELAY-STANDARD.md — KH1 handover relay standard (Thinking freeze; D4 shape checklist)
  • docs/CONSUMER-ADAPTER-PATTERN.md — consumer plug-in pattern
  • docs/consumers/ — per-consumer reference adapters (not kit architecture)
  • templates/ + policy/ + cursor/ — vendored footprint (K3)
  • docs/PHASE-9A-5-GOVERNANCE-HYGIENE-AGENT-OUTLINE.md — first agent tool
  • Scooling docs/PHASE-9A-MULTI-AGENT-OVERSEER-ROUTER-OUTLINE.md — runtime org-chart reference
File History 1 commit
sha256:4671b7f787ddbe63ced31c895b688c77ab495653b65a730b423329f26b3c1439 feat: K1-P1 complete — agent provenance, build-verification… Sonnet 4.6 patch 57 days ago