aaronrene / overseer-kit public
MULTI-REPO-WORKSPACE-LANES-FREEZE.md markdown
846 lines 45.9 KB
Raw
sha256:a78e7e5a8740e03315f325d19edeb3aa1b306b3337d04abbaa9a9e0f3bbeb7a1 docs: MuseHub-first before ISR #74 — staging solidify NEXT Human 11 hours ago

Phase K13a — Multi-repo workspace / constellation lanes (Thinking freeze)

Status: Reviewed → pass (K13a-r3). K13a is spec-only and frozen (includes §MR.6.5 board filename identity amendment); no CLI/consumer code lands in this phase. K13b (Auto) builds mechanically against this contract. Do not claim the feature exists until K13b + /build-verification-review → pass.

phase: K13a
outputs:
- id: multi-repo-workspace-lanes
  path: docs/archive/phases/MULTI-REPO-WORKSPACE-LANES-FREEZE.md
  frozen: true
frozen_inputs:
- id: kit-spec-config-cli
  path: docs/OVERSEER-KIT-SPEC.md
- id: governance-hygiene-9a5
  path: docs/archive/phases/PHASE-9A-5-GOVERNANCE-HYGIENE-AGENT-OUTLINE.md
- id: kh1-handover-relay
  path: docs/archive/phases/PHASE-KH1-HANDOVER-RELAY-STANDARD.md
- id: k8-multi-lane-docs
  path: docs/archive/phases/PHASE-K8-MULTI-LANE-DOCS-CONTRACT.md
- id: kh2-muse-sync
  path: docs/archive/phases/PHASE-KH2-MUSE-SYNC-HARD-GATE.md
- id: model-labels
  path: policy/model-labels.yaml
- id: decision-tiers
  path: policy/tiers.yaml
- id: test-tiers
  path: policy/test-tiers.yaml
- id: dogfood-config
  path: .overseer/config.yaml
- id: handover-template
  path: templates/OVERSEER-HANDOVER.template.md
- id: cross-repo-template
  path: templates/CROSS-REPO-COORDINATION.template.md
- id: freeze-ceremony
  path: docs/OVERSEER-KIT-SPEC.md#6
- id: agents-boundary
  path: AGENTS.md
review_stamp:
  reviewed_at: '2026-07-27T16:07:52Z'
  verdict: pass
  reviewer_mode: agent
  reviewer_model: thinking-high
  reviewer_provider: local
  kit_version: 0.1.0
  artifact_digest: sha256:df3d2754d346b4be25fbe2cd973c1e9f4560a5c6898e58d99f2360718562238e

Downstream edge: K13b Auto treats this document as ground truth without re-deriving it (SPEC §6). Consumer constellation adoption (Scooling ↔ Knowtation → MuseHub → Brain) is operator-gated migration after K13b ships; this freeze does not authorize edits in those repos.

Incident that must not recur (verified 2026-07-27): multi-root Cursor had Scooling / Knowtation / MuseHub / overseer-kit open; operator read Knowtation’s TOP NEXT SESSION (still Thinking / L-SEAM) while Scooling’s board had already advanced to L-SEAMb Auto. Knowtation also retained multiple ## NEXT SESSION — archived … headings. Operator concluded “kit failed”; ok status was healthy. Gap: kit has no first-class multi-repo / multi-lane / relay freshness model.

Hard facts verified against kit source (do not invent “it already does X”):

ID Fact Evidence
A Unit of governance = one repo, one .overseer/config.yaml, one default handover/roadmap pair SPEC §3; .overseer/config.yaml; K8 adds intra-repo lanes only
B ok governance-sync / 9A-5 = single-repo docs↔VCS drift; does not read peer roots or relay tips docs/archive/phases/PHASE-9A-5-…; tools/governance_hygiene/ (no peer/workspace symbols)
C ok status = per-repo health; green ≠ constellation consistent cli/commands/status.py; SPEC §5
D Handover templates / consumer practice allow multiple ## NEXT SESSION — headings KH1 H2 requires exactly one; Knowtation live file still has archived ## NEXT SESSION — headings
E Multi-root Cursor makes the focused tab look authoritative Incident 2026-07-27
F Muse≠Git dual history can diverge; muse_sync pending is per-repo KH2; regime backends
G SD-3 {step}a/{step}b split does not answer which repo’s {step}b is product PRIMARY policy/model-labels.yaml; KH1
H Regimes differ across members (muse+git-mirror, muse-only, git-only) SPEC §4; consumer AGENTS
I Tier 3 forbids auto-merge / live flips / staging push across repos policy/tiers.yaml

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

Round Reviewer Verdict Resolution
K13a-r1 Freeze-review loop (thinking-high); file+line citations findings R1-M1–M4 fixed in-tree (see ledger). CLI checklist --dry-run clean. Not cleared until r2.
K13a-r2 Freeze-review loop (thinking-high); independent re-read pass R1-M1–M4 confirmed RESOLVED; full §MR.0–§MR.16 regress clean; no security/irreversible/real_money/gates_tier3 escalation. Stamp via ok review --freeze. Cleared for K13b.
K13a-r3 Freeze-review loop (thinking-high); amendment review pass Operator amendment: §MR.6.5 board filename identity (repo-slug prefix for tab UX). Additive only — no redesign of §MR.2–§MR.5 authority model. S12 + template/init defaults + status filename fields + dogfood rename note. Stamp refreshed. Cleared for K13b.

Freeze-review findings ledger (K13a-r1)

ID Severity Category Citation Message
R1-M1 MAJOR consistency docs/archive/phases/MULTI-REPO-WORKSPACE-LANES-FREEZE.md §MR.6.1 (pre-fix) Lane tips reused ## NEXT SESSION —, contradicting KH1 H2 (“exactly one NEXT SESSION”) and enabling PRIMARY confusion.
R1-M2 MAJOR completeness §MR.6 / Knowtation ownership+relay pattern Ownership boards that also relay: true had no durable product tip when LIVE NEXT is ownership PRIMARY — 2026-07-27 class of bug would recur when Knowtation works SEC-* while Scooling advances.
R1-M3 MAJOR completeness §MR.8 footer states incomplete_after_primary_advance required a session oracle Auto cannot implement; collapsed to freshness predicate states.
R1-M4 MINOR consistency §MR.12.2 grace vs strict_markers Grace heuristic conflicted with default-strict honesty; replaced with explicit strict_markers bool (default true).

§MR.0 — Simple summary

When several related projects share one editor window, people paste the wrong “what’s next” note — often the tab they happen to be looking at, or an old archived prompt that still looks like a live one. The kit today keeps each project honest by itself, but it never checks whether a project that is only a pointer to the product board still matches that board.

This phase freezes a workspace (constellation) model: a small list of related repos, who owns product sequencing, who is only a relay, and how to fail closed when a relay tip is stale. Operators and other developers get the same mechanical check — no folklore required.

Technical summary

K13 freezes an optional, additive constellation layer on top of unchanged single-repo governance (SPEC §3, 9A-5, KH1, K8, SD-17):

  1. Manifest — checked into the product_order member as .overseer/workspace.yaml (Option B primary), with env / home override for path remapping (Option A override).
  2. Member config pointer — additive workspace: block in each member’s .overseer/config.yaml for discovery.
  3. Handover UX markers — machine-distinct LIVE PRIMARY / RELAY / ARCHIVED / LANE TIP blocks (amends KH1 heading discipline without replacing single-repo H1–H12).
  4. Board filename identity — repo-slug (and lane) prefixes on handover/roadmap filenames and titles so multi-root editor tabs are distinguishable without hovering the path (§MR.6.5).
  5. CLI — ok workspace status, ok workspace check-next (fail on stale relay), optional ok workspace doctor; single-repo ok status green must not imply workspace OK (S9).
  6. Session-end — advancing product_order PRIMARY without refreshing declared relays = incomplete multi-repo SD-17 (sibling gate to single-repo governance-sync).
  7. Lanes — compose with K8 intra-repo docs.lanes; add cross-member lane ids so parallel workstreams cannot steal product PRIMARY.
  8. Regime-aware — per-member vcs.regime; never issue git/gh for muse-only members.
  9. Seven-tier test matrix for K13b, including honesty fail if tools claim workspace OK while a relay disagrees with product_order PRIMARY.

§MR.1 — Scope

In scope (freeze only — this phase writes no product/CLI code beyond this artifact + kit governance doc updates):

  • Workspace / constellation model (§MR.2)
  • Manifest location decision + schema (§MR.3)
  • Member .overseer/config.yaml additive workspace: pointer (§MR.4)
  • Authority + conflict rules (§MR.5)
  • Handover UX contract + KH1 amendments + board filename identity (§MR.6, §MR.6.5)
  • CLI / skill / rule surface (§MR.7)
  • Relationship to 9A-5 / SD-17 (§MR.8)
  • Acceptance stories S1–S12 (§MR.9)
  • Seven-tier test matrix (§MR.10)
  • Tier-3 hard stops (§MR.11)
  • Migration / rollout (§MR.12)
  • Explicit non-goals (§MR.13)
  • Roadmap phase proposal + Auto deliverables list (§MR.14)

Out of scope (this Thinking session):

  • Implementing ok workspace * or parsing logic
  • Migrating Scooling / Knowtation / MuseHub / Brain handovers
  • Merging to main, staging push, live posture flips
  • Replacing product content inside consumer CROSS-REPO-COORDINATION.md
  • Building Brain firmware or any consumer product feature

§MR.2 — Workspace / constellation model (frozen)

§MR.2.1 — Definitions

Term Meaning
Constellation (workspace) Named set of related consumer (and optionally kit) repos that share product sequencing
Member One git/muse repo root with its own .overseer/config.yaml
product_order Exactly one member whose handover/roadmap wins on product sequencing (“what is NEXT” for the product)
ownership Member whose board wins on that member’s own authorization / store / domain behavior
enrichment Member that owns enrichment-only concerns (e.g. MuseHub provenance/social) — not product sequencing
edge Member for edge/device runtime (future Brain) — first-class role even if path unknown
kit Overseer Kit source — not a product lane; may be listed for doctor/status only
RELAY tip A board that publishes a tip pointing at another member’s PRIMARY (usually product_order)
LIVE PRIMARY The single paste-ready product NEXT on the product_order board (or a lane’s designated PRIMARY)
Lane Named parallel workstream (product, security, ux, …) with at most one PRIMARY tip per lane
required / optional member Required members missing locally → fail closed; optional missing → reported member_absent without failing the whole check unless --strict-all

§MR.2.2 — Roles (closed vocabulary)

product_order | ownership | enrichment | edge | kit | other

Rules:

  • Exactly one member with role: product_order per constellation.
  • Zero or more ownership / enrichment / edge / kit / other.
  • relay: true may be set on any non-product_order member (and never on product_order).
  • kit members are never product_order and never declare product RELAY tips that claim product PRIMARY authority.

§MR.2.3 — Today’s + tomorrow’s constellation (informative example)

Not normative paths — Auto fixtures use synthetic roots. Operator dogfood targets:

Member id Role Regime (typical) Notes
scooling product_order muse+git-mirror Product sequencing board
knowtation ownership + often relay: true muse+git-mirror Store/authz board; may relay product NEXT
musehub enrichment muse-only No git/gh commands from kit workspace tools
overseer-kit kit muse+git-mirror (dogfood) Not a product lane
brain edge TBD required: false until path known

External developers with only store + app use the same model with two members (product_order + ownership relay).

§MR.2.4 — Lanes vs K8

Layer Owns Frozen interaction
K8 docs.lanes Multiple handover/roadmap pairs inside one repo Unchanged; workspace tools read the member’s default lane unless a constellation lane overrides handover/roadmap paths
Constellation lanes Parallel workstreams across members Each constellation lane has id, primary (bool), optional owner_member

Frozen rules:

  • Exactly one constellation lane may have primary: true (the product lane).
  • Non-primary lanes may publish LANE TIP blocks; they MUST NOT use LIVE PRIMARY markers.
  • A member’s K8 non-default lane docs are ignored by workspace PRIMARY extraction unless the constellation lane explicitly points at those paths.

§MR.3 — Where the workspace definition lives (decision)

Options considered

Option Verdict Rationale
A Operator home / OVERSEER_WORKSPACES.yaml only OVERRIDE only Good for path remapping across machines; bad as sole source of truth (not reviewed with product, easy to drift, invisible to other developers cloning product_order)
B Declared in product_order repo and discovered by peers CHOSEN (primary) Matches existing human policy (Scooling product-order board wins); travels with the product; reviewable in VCS; peers already know to look at product_order for sequencing
C Cursor multi-root workspace metadata + kit overlay REJECTED Ephemeral, IDE-coupled, not regime-aware, not portable to Claude Code / Copilot / CI
D Kit-central registry of all consumer constellations REJECTED Kit must stay repo-agnostic; no Aaron-folklore registry inside overseer-kit

Frozen decision

  1. Canonical manifest path (primary):
    <product_order_root>/.overseer/workspace.yaml
  2. Discovery: each member’s .overseer/config.yaml carries an additive workspace: pointer (§MR.4).
  3. Path remap override (Option A): if env OVERSEER_WORKSPACE_MANIFEST is set, that file is loaded instead of the product_order path (operator machines / CI fixtures). The override file MUST declare the same id as workspace.constellation_id or the tool fails closed (CONFIG).
  4. Home index (optional convenience, never sole authority):
    ~/.overseer/workspaces/<id>.yaml MAY be a symlink or copy used only when workspace.manifest is unset and product_order_root is unset and OVERSEER_WORKSPACE_MANIFEST is unset — Auto must document this as last resort and warn manifest_source: home_index so operators do not confuse it with the reviewed product_order file.

Rejected: inventing a second parallel protocol outside kit docs / .overseer/.

§MR.4 — Schemas (frozen)

§MR.4.1 — .overseer/workspace.yaml (canonical)

overseer_workspace_version: 1
id: scooling-stack                    # constellation id (stable string)
product_order_member: scooling        # must match exactly one member.id with role product_order
strict_markers: true                  # default true when omitted (§MR.12.2)
strict_board_names: true              # default true when omitted (§MR.6.5); doctor warns on bare names

members:
  - id: scooling
    role: product_order               # closed vocabulary §MR.2.2
    root: "${SCOOLING_ROOT}"          # see §MR.4.3 root resolution
    regime: muse+git-mirror           # advisory; must match member config when readable
    required: true                    # missing root → fail closed
    relay: false                      # product_order MUST be false
    # optional path overrides (else read member .overseer/config.yaml docs.*)
    handover: null
    roadmap: null

  - id: knowtation
    role: ownership
    root: "${KNOWTATION_ROOT}"
    regime: muse+git-mirror
    required: true
    relay: true                       # may publish RELAY tip for product lane

  - id: musehub
    role: enrichment
    root: "${MUSEHUB_ROOT}"
    regime: muse-only
    required: false                   # optional until checkout present
    relay: false

  - id: overseer-kit
    role: kit
    root: "${OVERSEER_KIT_ROOT}"
    regime: muse+git-mirror
    required: false
    relay: false

  - id: brain
    role: edge
    root: "${BRAIN_ROOT}"             # may be empty / unset
    regime: null                      # unknown until joins; null allowed only if required: false
    required: false
    relay: false

lanes:
  - id: product
    primary: true
    owner_member: scooling            # defaults to product_order_member when omitted
  - id: security
    primary: false
    owner_member: knowtation
  - id: truth-harden
    primary: false
    owner_member: scooling

Validation (fail closed → exit 2 CONFIG):

  • overseer_workspace_version must be 1 (unknown → refuse).
  • id non-empty; product_order_member must reference exactly one member with role: product_order.
  • Exactly one role: product_order; that member has relay: false.
  • Exactly one lane with primary: true.
  • Member id unique; role ∈ closed vocabulary; regime ∈ {muse+git-mirror, muse-only, git-only, null} with null only when required: false.
  • No secrets, tokens, URLs with credentials, or identity claims (X-User-Id, wallet, email) in the manifest (§MR.11).

§MR.4.2 — Member .overseer/config.yaml additive block

# Additive; omitted = single-repo only (today). When present, workspace gates apply.
workspace:
  constellation_id: scooling-stack
  # Discovery (first match wins):
  # 1) manifest: <path>                         # explicit
  # 2) product_order_root: <path>               # load <root>/.overseer/workspace.yaml
  # 3) if this repo's workspace.yaml exists and this member is product_order → local file
  # 4) OVERSEER_WORKSPACE_MANIFEST env
  # 5) ~/.overseer/workspaces/<constellation_id>.yaml (warn)
  product_order_root: null
  manifest: null

Rules:

  • If workspace: is present, constellation_id is required.
  • Manifest id MUST equal constellation_id.
  • Single-repo governance-sync / status behavior unchanged when workspace: is absent.
  • K8 docs.lanes unchanged.

§MR.4.3 — Root resolution (frozen)

For each members[].root:

  1. Expand ${ENV_VAR} and ${ENV_VAR:-default} (default may use ~).
  2. Expand leading ~ to the process home directory.
  3. Resolve to an absolute filesystem path.
  4. If required: true and path missing / not a directory / no .overseer/config.yaml → fail closed (stale/missing_member, exit 35 on check-next; status reports workspace.ok: false).
  5. If required: false and missing → member_status: absent (non-fatal unless --strict-all).

No network to peer remotes for basic freshness. Local checkouts only.

§MR.5 — Authority + conflict rules (machine-checkable)

Conflict Winner Machine result if violated
Product sequencing (step id, Model, which repo’s Auto is next) product_order LIVE PRIMARY Relay tip disagree → stale_relay
Authorization / store / domain behavior of an ownership member That member’s ownership LIVE PRIMARY (its own board) Not compared to product_order for domain content
Enrichment-only concerns enrichment member board Not product PRIMARY
Relay tip vs product_order PRIMARY Must match on (step_id, Model label, repo path/id, authority=relay) stale_relay
Parallel lane tip vs product PRIMARY Lane tip allowed if marked non-PRIMARY; must not use PRIMARY marker ambiguous_primary if markers collide
Two LIVE PRIMARY markers on one board Forbidden ambiguous_primary
Archived block selected as PRIMARY Forbidden Parser ignores archived; if only archived exists → missing_primary

§MR.5.1 — Relay freshness predicate (frozen)

Extract from product_order LIVE PRIMARY (product lane):

  • step_id (from ONE NEXT STEP ID / heading)
  • model (normalized policy/model-labels.yaml display label)
  • repo_id / resolved root
  • tip_hash = SHA-256 of the canonical paste-ready fence bytes (UTF-8, LF-normalized)

Extract from each relay: true member’s product tip (product lane) — the sole block with role=relay or role=product_relay (§MR.6.1):

  • Declared target (step_id, model, product_order member id)
  • tip_hash from the marker (required)

Pass iff for every required relay member present locally:

  1. Exactly one product tip block exists (relay XOR product_relay) for the product lane, and
  2. step_id + model match product_order PRIMARY, and
  3. tip_hash matches product_order PRIMARY paste-fence hash (LF-normalized UTF-8 SHA-256).

Fail → exit code 35 (WORKSPACE_RELAY) on ok workspace check-next, with cited paths:

stale_relay: <relay_handover_path> tip=(…) != product_order <po_handover_path> primary=(…)

This predicate is exactly what would have caught the 2026-07-27 incident.

§MR.5.2 — Parallel lanes

  • Non-primary constellation lanes MAY have their own LIVE LANE TIP on owner_member.
  • Workspace check-next default scope = product lane only.
  • ok workspace check-next --lane <id> checks that lane’s owner PRIMARY vs any declared lane relays (if a future member sets relay_lanes: […]; v1 may omit cross-member lane relays — freeze allows the flag as optional additive schema, default empty).

§MR.6 — Handover UX contract (frozen)

§MR.6.1 — Machine markers (required)

Every selectable session block MUST begin with an HTML comment marker immediately above its heading:

Role Marker Heading pattern (frozen)
LIVE PRIMARY <!-- overseer:next role=primary lane=<id> status=live --> ## NEXT SESSION — <title> (PRIMARY)
LIVE RELAY (board parked on product tip) <!-- overseer:next role=relay lane=<id> status=live product_order=<member_id> tip_hash=sha256:<hex> --> ## NEXT SESSION — <title> (RELAY → <member_id> <step_id> <Model>)
PRODUCT RELAY (durable tip; ownership board busy) <!-- overseer:next role=product_relay lane=product status=live product_order=<member_id> tip_hash=sha256:<hex> --> ## PRODUCT RELAY — <member_id> <step_id> <Model>
LIVE LANE TIP <!-- overseer:next role=lane_tip lane=<id> status=live --> ## LANE TIP — <title> (LANE: <id>)
ARCHIVED <!-- overseer:next role=archived status=archived --> ## ARCHIVED SESSION — <title>

Hard rules:

  1. Exactly one ## NEXT SESSION — heading per board (preserves KH1 H2). That block is the paste target for this board’s next work: role=primary (product_order, or ownership/enrichment when that member’s own work is next) or role=relay (board intentionally parked as a product tip). Never both NEXT roles on one board.
  2. Members with relay: true MUST always expose a fresh product tip for the product lane via exactly one of:
    • the LIVE ## NEXT SESSION — … (RELAY → …) block (role=relay), or
    • a durable ## PRODUCT RELAY — … block (role=product_relay) when LIVE NEXT is an ownership / enrichment PRIMARY. Workspace check-next reads role=relay or role=product_relay (prefer NEXT relay if both somehow present → ambiguous_primary fail closed).
  3. Parallel lane tips use ## LANE TIP — (not ## NEXT SESSION —).
  4. Archived prompts MUST NOT use the heading prefix ## NEXT SESSION —.
    ## NEXT SESSION — archived … is forbidden (Knowtation failure mode).
  5. Forbidden ambiguous phrases: PRIMARY relay, primary (relay), or any ## NEXT SESSION — title containing case-insensitive archived.
  6. Parsers only honor blocks with valid markers; unmarked ## NEXT SESSION — is legacy: warn unmarked_next; with strict_markers: true (default) → check-next fails (ambiguous_primary).

§MR.6.2 — Paste-ready fence required fields

Every LIVE PRIMARY / RELAY / PRODUCT RELAY / LANE TIP paste fence MUST include these lines (substring match). PRODUCT RELAY redirect mode still includes them in a minimal fence (body may be a one-line “open product_order handover” instruction); tip_hash always hashes the product_order PRIMARY paste-fence bytes, not the redirect prose.

Model: <label>
Repo: <absolute or workspace-relative path>
Branch: <branch or "unknown">
Step: <step_id>          # e.g. L-SEAMb, K13b, FINISH-COMPLETE-APPLY-a
Authority: authoritative | relay | product_relay | lane_tip

RELAY / PRODUCT RELAY fences either:

  • (a) Redirect — instruct to open the product_order handover path (no embedded build body), and still declare matching Step / Model / tip_hash of the authoritative fence, or
  • (b) Embed — full paste body whose bytes hash to tip_hash matching product_order.

§MR.6.3 — Template + KH1 deltas (Auto must vendor)

K13b updates:

  • templates/OVERSEER-HANDOVER.template.md — PRIMARY marker + fence fields; archived example uses ## ARCHIVED SESSION —.
  • KH1 checklist gains H13–H16 (additive; do not weaken H1–H12):
ID Check
H13 Exactly one ## NEXT SESSION —; paired marker is role=primary or role=relay (not both); PRIMARY headings end with (PRIMARY); RELAY headings match (RELAY → …).
H14 No heading matching ^## NEXT SESSION — with case-insensitive archived in the title; archived uses ## ARCHIVED SESSION — only.
H15 If member relay: true: exactly one of role=relay (NEXT) or role=product_relay (## PRODUCT RELAY —) with tip_hash=sha256:; role=lane_tip uses ## LANE TIP — only.
H16 Paste fence of the live NEXT block contains Model:, Repo:, Step:, Authority: substrings.

H2 remains normative: exactly one ## NEXT SESSION — heading. Lane tips and archived sessions use distinct heading prefixes and do not count against H2.

§MR.6.4 — Cursor / operator UX rule (vendored)

New always-on rule fragment (Auto vendors via ok sync):

In a multi-root workspace, never treat a non-product_order handover as product PRIMARY without running ok workspace status (or ok workspace check-next). The focused editor tab is not authority.

Skill text for /governance-sync and orchestrator rule: when workspace: is configured and the session advanced product_order PRIMARY, SD-17 multi-repo close-out requires relay refresh or an explicit incomplete warning (§MR.8).

§MR.6.5 — Board filename identity (tab UX — frozen)

Problem: K13 markers stop paste confusion; they do not stop tab confusion. Multi-root editors show the basename only. Many consumers still use identical OVERSEER-HANDOVER.md / ROADMAP.md, so tabs look identical until the operator hovers the path (2026-07-27 class of UX failure, complementary to stale relays).

Precedent (already in kit / consumers): MuseHub MUSEHUB-OVERSEER-HANDOVER.md; VideoFactory VIDEO_OVERSEER_HANDOVER.md + K8 lane-specific names (tests/fixtures/config-two-lane.yaml, docs/archive/phases/PHASE-K8-MULTI-LANE-DOCS-CONTRACT.md). Config already supports arbitrary docs.handover / docs.roadmap paths — this section freezes the naming convention when a constellation is in play.

Frozen filename pattern

Doc Pattern Examples
Default-lane handover {REPO_SLUG}-OVERSEER-HANDOVER.md SCOOLING-OVERSEER-HANDOVER.md, KNOWTATION-OVERSEER-HANDOVER.md, MUSEHUB-OVERSEER-HANDOVER.md
Default-lane roadmap {REPO_SLUG}-ROADMAP.md SCOOLING-ROADMAP.md, KNOWTATION-ROADMAP.md
K8 / constellation non-default lane {REPO_SLUG}-{LANE}-OVERSEER-HANDOVER.md (+ matching roadmap) VIDEO-QUEUE-OVERSEER-HANDOVER.md, VIDEO-ACTIVE-HANDOVER.md (VF-style)

REPO_SLUG = uppercase of repo.name from .overseer/config.yaml with non-alphanumeric characters mapped to - and collapsed (e.g. overseer-kit → OVERSEER-KIT; scooling → SCOOLING). LANE = uppercase lane id from K8 docs.lanes or constellation lanes[].id.

Title fields (required with filenames)

  • docs.handover_title MUST include the human repo (or lane) name — e.g. Scooling Overseer Handover, Knowtation Overseer Handover, Video Queue Overseer Handover.
  • docs.roadmap_title likewise — e.g. Scooling Roadmap.
  • KH1 H1 shape remains # <handover_title> — <repo.name>.

Rejected naming options

Option Verdict Why
Bare OVERSEER-HANDOVER.md for constellation members REJECTED when workspace: configured Identical tabs
4-letter codes (KNOW-, SCOO-) as primary REJECTED Collisions; opaque to external developers
Spaced letter brands (K-N-O-W Overseer…) REJECTED Noisy; worse truncation
Suffix form (OVERSEER-HANDOVER-SCOOLING.md) REJECTED Editor tabs often truncate the end → still look identical
Full prose titles only (no filename change) REJECTED Tabs show basename, not H1

When the rule applies

Context Rule
Member has workspace: configured (or is listed in a constellation manifest) Prefixed filenames required for default-lane handover + roadmap (strict_board_names, default true when workspace: present)
Single-repo, no workspace: Prefixed names recommended; bare OVERSEER-HANDOVER.md remains allowed for backward compat
ok init after K13b Default generated config uses {REPO_SLUG}-OVERSEER-HANDOVER.md + {REPO_SLUG}-ROADMAP.md (and matching titles)
Template files in kit tree Keep template basename OVERSEER-HANDOVER.template.md (engine input); rendered/init destination uses the prefixed name
Kit dogfood (overseer-kit) May keep bare names while workspace: absent; if kit joins a constellation or operator prefers tab clarity, rename to OVERSEER-KIT-OVERSEER-HANDOVER.md / OVERSEER-KIT-ROADMAP.md

Schema (additive on workspace.yaml or implied by member config):

strict_board_names: true   # default true when omitted and workspace: is configured

When strict_board_names: true, ok workspace doctor / status emit board_name_violation if a member’s configured handover/roadmap basename is the bare legacy pair (OVERSEER-HANDOVER.md / ROADMAP.md or case variants) or does not start with the expected {REPO_SLUG}- prefix. check-next does not fail solely on board names (authority ≠ tabs); doctor surfaces the UX debt. Optional future hard-fail may flip via a follow-on freeze — not K13b.

CLI / status fields (Auto)

ok workspace status --json each member object MUST include:

handover_basename: "<filename>"
roadmap_basename: "<filename>"
handover_title: "<docs.handover_title>"
authoritative_handover: "<repo-relative or absolute path>"   # product_order only / overall

Human text MUST print basenames (not only absolute paths) so operators can match editor tabs.

KH1 additive check

ID Check
H17 When workspace: is configured and strict_board_names is true (default): handover basename matches {REPO_SLUG}-OVERSEER-HANDOVER.md or {REPO_SLUG}-{LANE}-… pattern; roadmap basename matches {REPO_SLUG}-ROADMAP.md (or lane variant); handover_title contains a non-empty repo/lane label distinct from the generic string Overseer Handover alone.

Consumer rename (dogfood — not K13b code)

Post-K13b operator migration (feature branches per repo):

  1. Scooling: docs/OVERSEER-HANDOVER.md → docs/SCOOLING-OVERSEER-HANDOVER.md; ROADMAP.md → SCOOLING-ROADMAP.md; update .overseer/config.yaml docs.* + titles.
  2. Knowtation: → KNOWTATION-OVERSEER-HANDOVER.md / KNOWTATION-ROADMAP.md.
  3. MuseHub: already close (MUSEHUB-OVERSEER-HANDOVER.md); align roadmap prefix if needed.
  4. Update constellation workspace.yaml path overrides if any; refresh PRODUCT RELAY pointers.
  5. Brain / external: use the same pattern from first ok init.

K13b does not rename live consumer files; it ships templates, init defaults, doctor warnings, fixture proof (S12), and rule text.

§MR.7 — CLI / skill surface (frozen)

§MR.7.1 — Commands

Command Writes? Behavior
ok workspace status [--json] [--strict-all] No Constellation map: members, roles, regimes, LIVE PRIMARY per member/lane, relay freshness, lane matrix, manifest_source, per-member handover_basename / roadmap_basename / titles (§MR.6.5).
ok workspace check-next [--lane ID] [--json] No Exit 0 if product-lane (or --lane) relay freshness passes; exit 35 on stale_relay / ambiguous_primary / missing_primary; exit 2 on config/manifest errors; exit 1 on usage. Cite paths. Does not fail solely on bare board filenames.
ok workspace doctor [--json] No Diagnostics: Muse≠Git (muse_sync), missing optional members, unmarked NEXT, regime mismatch, board_name_violation when strict_board_names and bare/unprefixed handover/roadmap (§MR.6.5). Never merges; never pushes.
ok status --workspace No Alias: run single-repo status and attach workspace report when configured; must not set overall success to imply workspace.ok (S9). If --exit-code, workspace failure contributes exit 35 without collapsing into “repo healthy”.

Default for mutating workspace helpers: none in v1 (relays are refreshed by humans/agents editing docs). Auto MAY add ok workspace refresh-relays --dry-run later only if a follow-on freeze adds it; not in K13b scope (§MR.13).

§MR.7.2 — Exit code

Code Name Meaning
35 WORKSPACE_RELAY Stale/missing/ambiguous workspace NEXT / relay integrity failure

Non-overlap: does not reuse 2, 3, 6, 30–34. Precedence when composed with status --exit-code --workspace (extends cli/commands/status.py docstring 2 > 6 > 3 > 0):

2 > 6 > 35 > 3 > 0

Workspace failure (35) never overrides config/substrate/muse_sync/footprint-self-integrity (2) or lock/footprint-digest integrity (6). It does override mere footprint drift (3) and clean (0), so a green single-repo status cannot hide a stale relay (S9).

§MR.7.3 — Engine layout (Auto)

tools/workspace/
  __init__.py
  manifest.py          # load/validate workspace.yaml
  next_extract.py      # PRIMARY / RELAY / ARCHIVED / LANE TIP parse
  check_next.py        # freshness predicate
  doctor.py
  types.py
cli/commands/workspace.py

Regime rule: for muse-only members, doctor/status must not invoke git/gh; Muse adapter only (S5).

§MR.7.4 — Skills / rules (Auto vendors on ok sync)

Artifact Purpose
.cursor/rules/workspace-authority.mdc (+ claude twin if applicable) Focused-tab is not authority; run workspace status
.cursor/skills/workspace-status/SKILL.md (+ .claude/skills/…) /workspace-status → ok workspace status
Extend governance-sync skill Multi-repo SD-17 incomplete until relays refreshed
Extend templates/OVERSEER-HANDOVER.template.md Markers + fence fields

§MR.8 — Relationship to 9A-5 / SD-17 (frozen)

Concern Owner Replaced?
Single-repo docs ↔ VCS drift ok governance-sync (9A-5) No — still required
Handover shape H1–H12 (+ H13–H16) KH1 / governance-sync D4 path Additive checks
Cross-repo relay freshness ok workspace check-next Additional gate
Session-end hygiene SD-17 Extended for constellations

Composition (frozen):

  1. ok governance-sync remains single-repo; default --dry-run unchanged; never opens docs-only PRs to main; never merges; never pushes staging.
  2. When workspace: is configured, governance-sync footer (and --json additive key workspace_relay) MUST report one of:
    • not_configured | ok | stale_relay | ambiguous_primary | missing_member | error by invoking the same freshness predicate as ok workspace check-next (read-only; no peer writes). There is no separate “advanced this session” oracle — staleness is sufficient and machine-checkable.
  3. Preferred close-out workflow when product_order PRIMARY advances:
    • Update product_order handover/roadmap (existing SD-17)
    • Refresh each relay: true member’s product tip (role=relay or role=product_relay)
    • Run ok workspace check-next → 0
  4. If relays are not refreshed: local governance-sync may still repair this repo’s docs↔VCS drift, but must surface workspace_relay: stale_relay (or worse) and treat multi-repo SD-17 as incomplete until check-next exits 0.
  5. Workspace check is a sibling command; governance-sync does not silently rewrite peer repos (no cross-repo writes from one cwd without explicit -C <peer> agent action).

Idempotency: workspace status / check-next / doctor are read-only and idempotent.

§MR.9 — Acceptance stories (Auto must prove)

ID Story Expected
S1 product_order advances Thinking→Auto ({step}a done → {step}b PRIMARY); relay still on Thinking ok workspace check-next FAIL exit 35, cites both handover paths
S2 Relays refreshed to match step/Model/tip_hash check-next PASS exit 0
S3 Archived headings (## ARCHIVED SESSION — or forbidden legacy ## NEXT SESSION — archived) cannot be selected as PRIMARY status/check ignore archived; legacy archived form → fail/ambiguous per §MR.6
S4 Multi-root: workspace status names product_order handover path as authoritative product NEXT Operator-visible authoritative_handover field and distinct handover_basename per member
S5 MuseHub muse-only member: workspace tools issue no git/gh Asserted in tests (adapter/regime guard)
S6 Parallel ## LANE TIP — … (LANE: security) exists; product PRIMARY unchanged check-next (product) PASS; lane tip listed as non-PRIMARY
S7 Add brain member (required: false) without schema redesign Manifest validates; absent brain → member_absent, not error
S8 External two-repo constellation (app product_order + store ownership relay) Same commands pass S1/S2
S9 Single-repo ok status green while relay stale Must not imply workspace OK; --workspace / check-next still fail
S10 Ownership board LIVE NEXT is PRIMARY (its own work) + fresh ## PRODUCT RELAY — matching product_order check-next PASS; status shows ownership PRIMARY ≠ product authoritative path
S11 Ownership PRIMARY + stale/missing PRODUCT RELAY after product_order advanced check-next FAIL exit 35 (same class as S1)
S12 Fixture members use distinct prefixed basenames (SCOOLING-OVERSEER-HANDOVER.md vs KNOWTATION-OVERSEER-HANDOVER.md); a bare OVERSEER-HANDOVER.md under strict_board_names: true status lists distinct basenames; doctor reports board_name_violation for the bare name; check-next still governed only by tip freshness

§MR.10 — Seven-tier test matrix (K13b)

Tier Proves
unit Manifest schema validate/reject; root ${ENV}/~ expansion; marker parse (PRIMARY/RELAY/ARCHIVED/LANE TIP); forbidden legacy archived heading detection; tip_hash (LF-normalize); freshness predicate true/false; role/lane cardinality rules; regime null only when optional; REPO_SLUG normalization; strict_board_names default; bare vs prefixed basename classifier
integration Fixture constellation (2–3 temp repos + manifests + handovers): ok workspace status --json shape incl. basenames/titles; check-next exit 0/35/2; status --workspace does not claim workspace OK on single-repo green (S9); muse-only member path skips git; doctor board_name_violation (S12)
e2e S1→S2 full cycle on fixtures; S3 archived; S4/S12 distinct basenames; S6 lane tip; S7 optional brain absent; S8 two-repo external shape; governance-sync footer key workspace_relay when configured; ok init defaults emit prefixed handover/roadmap destinations
stress ≥20 members / ≥10 lanes manifest + large handovers: bounded runtime; stable JSON key order for status; no unbounded recursive workspace walk
data-integrity Read-only commands never mutate repos; twice-run identical outputs; tip_hash stable; missing required member fails closed (no guessed paths); override manifest id mismatch → CONFIG 2
performance check-next on 5-member fixture completes within documented bound (Auto sets numeric budget, e.g. < 2s wall on fixture SSD); no network calls
security / honesty Fail if any surface claims workspace.ok: true (or exit 0 on check-next) while a required relay tip disagrees with product_order PRIMARY (pre-fix replica / differential: mutate relay tip, re-run, assert fail); no secrets in manifest fixtures; no X-User-Id / identity fields accepted; injection-shaped headings treated as opaque text; muse-only never shells git/gh; Tier-3 actions absent from command surface

§MR.11 — Tier 3 / hard stops (frozen)

K13 never:

  • Auto-merges main (Muse or GitHub) in any member
  • Auto-pushes Muse staging
  • Flips live capability / posture / env gates
  • Commits secrets into workspace manifests or handovers
  • Invents cross-repo identity headers or authn (X-User-Id, bearer mint, wallet bind) for governance
  • Treats GitHub as canonical under muse+git-mirror (SD-14)
  • Requires network to remotes for basic stale-relay checks
  • Writes peer-repo files from ok workspace * v1 (read-only)

§MR.12 — Migration / rollout (frozen)

§MR.12.1 — Activation

State Behavior
No workspace: in config and no discoverable manifest Single-repo only (today); workspace commands exit 2 with “not configured” or exit 0 with workspace: not_configured — freeze choice: exit 0 + not_configured for status; exit 2 for check-next when explicitly asked and not configured
workspace: present Gates apply; missing required members fail closed
Multi-root Cursor without manifest Rule text warns; no silent mandate (avoid false fails for unrelated multi-root folders)

§MR.12.2 — Marker strictness

  • Schema field strict_markers (bool) on workspace.yaml; default true when key omitted (new manifests and dogfood).
  • When strict_markers: true: unmarked ## NEXT SESSION — → check-next fails (ambiguous_primary / unmarked_next); no heuristic pass.
  • When strict_markers: false (explicit opt-out for messy migrations only): warn unmarked_next and allow step/Model heuristic match for relay freshness; still fail on explicit step/Model disagreement (S1). Dogfood Scooling+Knowtation MUST use strict_markers: true.

§MR.12.3 — Dogfood order

  1. overseer-kit — ship K13b + templates/rules/skills + init prefixed-name defaults; kit’s own workspace: remains absent by default (optional rename to OVERSEER-KIT-* for tab clarity).
  2. Scooling + Knowtation — first live constellation: rename boards per §MR.6.5, then add workspace.yaml + workspace: pointers (product_order + ownership relay).
  3. MuseHub — optional enrichment member (muse-only); confirm prefixed handover/roadmap.
  4. Brain — add as edge, required: false, when path known; init with prefixed names.

ok sync in consumers pulls template/rule/skill updates; creating workspace.yaml is operator-gated (not auto-written by sync).

§MR.12.4 — Docs-only PR policy

Unchanged: no docs-only PRs to main without operator request. Constellation adoption commits stay on feature branches per member regime.

§MR.13 — Explicit non-goals

  • Distributed locking of chats / preventing two Autos from running
  • Auto-running Auto builds in peer repos
  • Replacing consumer CROSS-REPO-COORDINATION.md product ownership tables
  • Building Brain firmware or edge runtime
  • Hosted multi-repo dashboard (Hosted governance dashboard stays read-only remote glance)
  • Cross-repo identity / auth product features
  • Making single-repo ok status green mean constellation OK
  • Silent redesign of 9A-5 single-repo governance-sync
  • ok workspace refresh-relays write path in K13b (follow-on freeze if needed)
  • Cursor-only features unavailable via CLI
  • Renaming live Scooling / Knowtation / MuseHub / Brain handover files inside K13b (dogfood after)

§MR.14 — Roadmap proposal + Auto deliverables

Phase rows (insert into docs/ROADMAP.md)

Phase Model Status after this Thinking Deliverable
K13a Freeze multi-repo workspace lanes Thinking DONE after freeze-review pass This contract
K13b Multi-repo workspace lanes build Auto TODO until K13a pass Implement §MR.4–§MR.8 (§MR.6.5 naming) + §MR.10

SD-3 split: never one combined Thinking→Auto prompt.

K13b Auto deliverable checklist (mechanical)

  1. tools/workspace/ + cli/commands/workspace.py + argparse wiring on ok workspace …
  2. Exit 35 + SPEC §5 row + help text
  3. Additive config parse for workspace: + manifest loader (strict_markers, strict_board_names)
  4. Template handover markers + KH1 H13–H17 notes (status/check-next/doctor enforce as specified)
  5. Vendored rule + skills (cursor + claude), including board-filename identity guidance
  6. governance-sync footer additive workspace_relay (no peer writes)
  7. ok init default destinations: {REPO_SLUG}-OVERSEER-HANDOVER.md + {REPO_SLUG}-ROADMAP.md
  8. Fixture pack under tests/fixtures/workspace/* covering S1–S12 (prefixed basenames)
  9. Seven-tier tests §MR.10 all green
  10. /build-verification-review → pass before ROADMAP DONE
  11. ROADMAP + HANDOVER updated together; no main merge; no live consumer renames in K13b

§MR.15 — Security / privacy checklist

  • [x] No secrets in manifest schema
  • [x] No cross-repo identity invention
  • [x] Fail closed on missing required roots (no path guessing beyond declared expansion)
  • [x] Read-only workspace commands in v1
  • [x] Regime-aware (no git in muse-only)
  • [x] Honesty tier forbids false workspace.ok
  • [x] Tier-3 actions absent

§MR.16 — Close-out (this Thinking session)

  1. Freeze-review loop → pass; stamp review_stamp via ok review --freeze.
  2. ROADMAP: K13a → DONE (Thinking); K13b → TODO (Auto).
  3. Handover NEXT → K13b Auto paste-ready prompt (only after pass).
  4. Feature-branch commit bundling this freeze + ROADMAP + HANDOVER (SD-17).
  5. No consumer migrations; no main merge.
File History 1 commit
sha256:a78e7e5a8740e03315f325d19edeb3aa1b306b3337d04abbaa9a9e0f3bbeb7a1 docs: MuseHub-first before ISR #74 — staging solidify NEXT Human 11 hours ago