stack/docs/compaction-refresh/governance/charter-BUILD-BRIEF.md

# Compaction-Refresh Mechanism — BUILD BRIEF (Mos → MS-LEAD)

**Status:** STAGED — do NOT dispatch until PR #826 (#824 skill-CLI bridge) MERGES. Mos routes this to
MS-LEAD at #824 land. PLAN phase COMPLETE + RATIFIED; this is the BUILD-execution brief.
**Routed by:** Mos (main orchestrator). **Owner:** MS-LEAD (mosaic-100). **Runtime scope M1:** Claude + Pi.

## 1. AUTHORITY (sha256-pinned — build AGAINST these, do not re-derive)
| Artifact | Path | SHA-256 |
|---|---|---|
| **Ratification record (SSOT)** | `~/agent-work/reviews/compaction-refresh-SPEC-RATIFICATION.md` | `bac58319c9c4028b5b40e1129e0033cdb5a6b7b02033c25f06f4cb77d7779c67` |
| Ratified SPEC v5 | `~/agent-work/reviews/compaction-refresh-SPEC-v5.md` | `a6d07ade835758e8488ca10d3b0631caf0beb93ea3a6733631f151b0c2f01433` |
| sol FINAL red-team (GO) | `~/agent-work/reviews/compaction-refresh-SPEC-v5-redteam-sol.md` | `3da326a4ea91767b731e128a93b13194e8002358101e30de3fcb8ca2f8f54faa` |

The coder MUST verify these hashes before building. The in-context working spec is DERIVED and
compaction-fragile — the sha256'd records above are the recovery SSOT (durable-authority discipline).

## 2. TARGET & SCOPE
- **Framework-native `packages/mosaic/…`** in `mosaicstack/stack`. NOT jarvis-brain. NOT
  `~/.config/mosaic/` directly (that tree is WIPED on framework upgrade — durable home is SOURCE).
- **M1 = Claude + Pi orchestrators only.** Codex/other runtimes = scope-note only.
- **Hard dependency (now satisfied at dispatch):** the `mosaic skill` register/list + install/upgrade
  symlink auto-sync (#824 / PR #826) — so the durable `mosaic-context-refresh` skill ships REACHABLE
  (auto-symlinked into `~/.claude/skills/`). Do not dispatch before #826 merges.

## 3. DELIVERABLES (locked architecture — from the ratification record; do NOT redesign)
1. **Authenticated external lease broker** bound to kernel `SO_PEERCRED` `(pid, starttime,
   runtime_generation)` — the only unforgeable identity on a same-uid tmux fleet. Broker **MINTS** the
   logical `session_id` at first peercred contact (NEVER caller-asserted). Distinct-principal /
   protected socket.
2. **Whole mutator-class gate** (not per-wrapper): no consequential mutator succeeds without a valid
   VERIFIED lease. **Revoke-first / promote-last.**
3. **Compaction observers → revoke:** Claude `PreCompact` + `SessionStart(matcher=compact)`; Pi
   `session_before_compact`/`context` equivalents. Any `runtime_generation` bump (reload/resume/fork,
   same PID included) auto-revokes the prior incarnation.
4. **Verbatim-hashed normative fragments:** `B_payload` (exact fragments + deterministic metadata) and
   `H_payload = SHA256(domain_sep ‖ length_framed(B_payload))` — NO self-reference (byte-identical
   across the Claude and Pi builders).
5. **Receipt-challenge protocol (promotion prerequisite, NOT the safety mechanism):** broker mints a
   single-use `receipt_challenge` per cycle bound to `(session_id, runtime_generation,
   compaction_epoch, request_epoch, H_source, H_payload, schema_version)`. **COMPUTE = broker**
   (observes latest-assistant message, computes the binding incl `H(latest-assistant-message)`);
   **COPY = model** (verbatim copy of challenge + `H_payload` — an LLM cannot hash its own output;
   T29). Observed in the EXACT latest assistant message (Claude: latest assistant entry + pending
   challenge, NO transcript grep; Pi: `message_end`, NOT `after_provider_response`). Single-use,
   consumed before the tool batch. Broker transition order (mandatory): `revoke → build
   B_payload/H_payload → PENDING_DELIVERY(mint unique challenge) → deliver → observe exact receipt →
   evidence commit → consume challenge → promote VERIFIED (last)`.
6. **Constrained recovery command** = the single ungated mutator; the `mosaic-context-refresh` skill
   is its wrapper (uses a newly-minted challenge + identical protocol; cannot replay normal-path
   receipt). Durable skill lands here, symlink-reachable via #824.
7. **T-C server-side line = branch protection** (the irreducible guarantee; client gate is
   window-narrowing only). If ops-config rather than code, DOCUMENT the required posture explicitly.

## 4. BINDING BUILD CONDITIONS R1–R6 (MANDATORY — verbatim from ratification record)
- **R1 (honesty):** state that the receipt detects ABSENT or PREFIX-TRUNCATED terminal token, but a
  MIDDLE-DROP preserving the tail is a **T-C contract violation, NOT receipt-detectable** (covered by
  server-side). No over-claim.
- **R2 (atomicity):** evidence-commit → consume-challenge → promote-VERIFIED is ONE atomic broker
  transaction; a crash leaves neither VERIFIED-with-live-challenge nor consumed-with-ambiguous-promote;
  recovery mints a NEW challenge, never reuses.
- **R3 (parsing):** exact single current-cycle receipt parse — no unbounded grep; reject
  quoted/tool-output receipts, wrong generation/epoch, unknown/stale challenge, multiple receipts.
- **R4 (Gate0 = BUILD-ADMISSION GATE):** see §5 — runtime evidence BEFORE build admission; a failed
  Gate0 item RETURNS the design to planner review, it is NOT waived by the GO.
- **R5 (TTL):** 300 s MAX lease TTL + soak-tighten; soak may only SHORTEN, never lengthen. Mos-accepted.
- **R6 (receipt semantics):** receipt = T-A delivery/liveness ONLY, never obedience/safety/residency.
  Permanent invariant.

## 5. R4 GATE0 — RUNTIME EVIDENCE BEFORE BUILD ADMISSION (WI-0, do this FIRST)
Structure the build like gitwatch: **WI-0 is a Gate0 runtime-evidence probe; no feature build admitted
until every item produces POSITIVE runtime evidence** (not a design assertion). A failed item RETURNS
to planner — do not paper over:
- Launcher `exec`/parent topology + supported-hook ancestry (D1); broker authenticates the launcher
  chain, rejects sibling-substitution.
- Pi lifecycle: last-position invariant (last-or-closed), per-tool nonce → tool-call-id map (D5).
- Same-PID `runtime_generation` bump on reload/resume/fork revokes prior lease (D4).
- Broker socket authenticity posture (protected / distinct-principal); `SO_PEERCRED` returns the true
  `(pid, starttime)`.
- Source-invalidation fail-closed (missing/oversize/hash-mismatch fragment → no promotion).
- Claude `additionalContext` + Pi `context` inject atomically (A-v5-1) — the transport assumption
  T27 rests on; verify or class the gap T-C.

## 6. ACCEPTANCE TESTS (red-first TDD)
Carry all v4 ACs + T12b; add **T24–T30**: T24 hash-construction no-self-reference byte-identical across
builders · T25 replay rejected · T26 transcript-stale-match cannot promote · T27 partial-delivery
(prefix-trunc/tail-only/middle-drop/malformed) none promote · T28 single-use (no renew/reopen) · T29
model copies not computes · T30 dual-hook-miss matches AMENDED threat table within+after TTL.
Acceptance = full green suite + Gate0 evidence pack.

## 7. REVIEW & MERGE DISCIPLINE
- **This IS an Opus-SECREV-mandatory surface** — UNLIKE #824 (local same-uid FS). The broker is an
  authentication/identity/authorization mechanism (peercred binding, session_id minting, mutator-class
  gating, receipt protocol). Security review = **Opus-SECREV, no GPT/terra substitute** on the
  broker/gate/receipt/socket surfaces. Functional/non-security parts may take GPT review.
- **Author ≠ reviewer**, independent review, no self-merge, exact-head RoR (reviewed-SHA=merged-SHA),
  `closes #<issue>` close-keyword, full 40-char head. Never edit tests to pass / never force-merge red
  / never `--no-verify`.
- **Mos merges** (per ratification record) after Opus-SECREV + independent review pass + green suite +
  Gate0 pack. Decompose into work-items (WI-0 Gate0 first); likely a milestone, not one monolithic PR.

## 8. SEQUENCING
#826 (#824 bridge) MERGES → Mos routes this brief → MS-LEAD decomposes (WI-0 Gate0 first) → build M1
(Claude+Pi) → Gate0 evidence pack (failed item → planner) → Opus-SECREV + independent review → Mos
merges → durable `mosaic-context-refresh` skill lands symlink-reachable → jarvis-brain `CLAUDE.md`
mandate PR aligns to the shipped receipt/hash contract. Interim skill + CLAUDE.md mandate stay LIVE
until the mechanism ships.