aaronrene / overseer-kit public
CONSUMER-ADAPTER-PATTERN.md markdown
125 lines 5.7 KB
Raw
sha256:0e9549ec7b463911bc08b7d586dc320b1ac9b1f5c943ee7e3865dcc6cb0f6f83 chore(governance): sync handover+roadmap to 84db8c8 (drift:… Human 21 hours ago

Consumer adapter pattern

Purpose: How any repo adopts Overseer Kit without forking kit core.
Normative freeze: docs/archive/phases/PHASE-K9A-L1-L2-MODULE-FREEZE.md §K9.0 / §K9.12.

Simple version

Install the kit, point .overseer/config.yaml at your docs, and keep your product-specific checks in your repo. The kit supplies the shared machinery; you supply what “good” means for your domain.

Technical version

Layer Kit owns Consumer owns
L0 init/sync/status/review/governance-sync, templates, adapters Living docs content, docs.lanes, VCS regime
L1 Orchestrator + policy/manifest schemas + verify-step policy/checkpoints.yaml, verify scripts, manifests
L2 Ledger engine + roles + co-requirement hooks Hook call sites, domain DoD, optional roster path (roles_file — v1 warn/ignore)
L3 Regime adapters (realign/mirror) Choosing muse+git-mirror when ready

Install skeleton

KIT=/path/to/overseer-kit
REPO=/path/to/consumer

$KIT/cli/ok -C $REPO init --migrate \
  --from-config $KIT/tests/fixtures/pilot/config-<consumer>.yaml \
  --non-interactive --dry-run
# then apply without --dry-run
$KIT/cli/ok -C $REPO status --check-footprint

Customize only .overseer/config.yaml (regime, doc paths, future checkpoints: / honesty:).

L0 — lanes vs rows vs repos

  • Lanes — few durable handover/roadmap pairs (docs.lanes).
  • Rows / L1 manifests — many instances of the same concern (videos, papers, closes).
  • Repos — different trust boundaries or VCS regimes.

See docs/archive/phases/PHASE-K8-MULTI-LANE-DOCS-CONTRACT.md and vision §5.2.

L1 — domain pack checklist

  1. Write policy/checkpoints.yaml (steps + templates + optional overrides).
  2. Ship scripts/verify/* that exit 0/≠0 (no placeholders in verified paths).
  3. Point checkpoints.active_manifest at the active work-unit manifest.
  4. Call overseer verify-step --step … after every step; never hand-set verified: true.
  5. Keep detailed grids in consumer boards/JSON; L0 board stays a summary row if needed.

L2 — honesty wiring checklist

  1. Enable honesty: and set ledger path.
  2. Set require_verdict_on to the hooks you enforce (absent → all three; hook not in list → honesty-status refuses 4).
  3. At every enabled board_done / handoff / register boundary, call
    overseer honesty-status --hook … --artifact … (pass --producer-session when known).
  4. Verifier sessions re-run L1/domain scripts and overseer ledger append --kind verdict (first append auto-writes a genesis line when the ledger is empty — no manual init required).
  5. Do not treat producer self-reports as evidence. Optional roles_file is path-checked only in v1 (enum roles still apply; roster content is not loaded for enforcement).

Reference consumers

Public stubs (boundary only). Sister-product pilot packs are not mirrored into this repository — use fixtures + the migrate guide.

Consumer Public stub Fixture
Example / custom doc names docs/consumers/videofactory/OVERSEER-SETUP.md tests/fixtures/pilot/config-videofactory.yaml
Scooling docs/consumers/scooling/OVERSEER-SETUP.md tests/fixtures/pilot/config-scooling.yaml
Knowtation docs/consumers/knowtation/OVERSEER-SETUP.md tests/fixtures/pilot/config-knowtation.yaml

Migrate steps: docs/MIGRATE-EXISTING-REPO.md. Fixture configs: tests/fixtures/pilot/.

Positioning (developer-centric — way forward)

Overseer Kit is governance machinery for developers, not an end-user frontend product. The public site and optional local UI explain patterns and point into the suite — they are not where people “run Overseer” day to day.

Surface Role Audience
Public site (overseerkit.com → static docs/landing/) Explain L0→L3 / scenarios; door into the suite Devs & operators (marketing clarity)
GitHub overseer-kit Clone, ok init / migrate, dogfood, contribute Primary adopt path
MuseHub Optional L3 substrate (signed identity, content-addressed history) When provenance depth pays
Knowtation Sister product — personal knowledge / vault; optional Track O Stage 4 bind Separate product, not kit core
Scooling Sister product runtime (task/agent orchestration under src/phase9a/) that consumes the kit for governance Product owns runtime; kit never vendors Scooling code
VideoFactory / other repos Peer consumers — same kit pattern, domain packs stay in-repo Same L0–L2 sockets
ok app / desktop / hosted-dashboard Optional operator tools in the kit checkout Devs/operators — not a public SaaS

Kit vs Scooling (do not conflate):

  • Kit = portable governance (ok, roadmap/handover, freeze/BV, verify-step, honesty ledger, VCS adapters).
  • Scooling = the product that can run multi-agent task work and wrap kit discipline for its users.
  • Other products (Knowtation, VideoFactory, MuseHub) plug in the same kit; they are not forks of kit core.

Public site CTAs (frozen intent): explain patterns → GitHub (kit) → also MuseHub / Knowtation / product docs as sibling doors. No browser signup, no chatbot-hosted runtime on overseerkit.com.

Hard rules

  • Never hardcode another product’s paths into kit core.
  • Never require MuseHub for L0–L2 baseline.
  • Never use an LLM as the pass/fail authority for measurable artifacts.
  • Never claim the kit website or Track Q UI is an end-user product runtime (that lives in consumers such as Scooling).
  • Never claim a browser-only signup or zero-install Path A until a product surface ships it.
File History 1 commit
sha256:6abcf1fa82a7a621ccbc945f19acdba5bc0db54569599404a1452fb4a096a199 fix(ISR): default require_independent_second_reviewer to require Human minor ⚠ 21 hours ago