stack/docs/remediation/MISSION.md

Mosaic Stack Remediation — Mission Charter

Owner: project orchestrator mos-remediation (Claude, launched in /src/mosaic-stack). Origin: 2026-07-16..31 fleet lifecycle postmortem. Status: EXECUTING (planning complete; RM-01 in flight). HOLD lifted for this workstream by Jason, 2026-07-31 — "begin full mosaic fleet operation on this."

Goal

Convert the 15 accepted postmortem remediation proposals into a working, dogfooded implementation. North star: anything with a deterministic right answer moves OUT of the LLM into a deterministic gate/program; the LLM handles only genuine judgment.

First-class principle — observe the property, not the exit code

No write is done until the requested PROPERTY is observed. A success exit code is not evidence.

Success output is designed to be believed. That is the whole reason the inert-gate class exists and why P-WRAPPER-001's tri-state (verified / written-unverified / failed) is not optional. The failure is not carelessness — a green is engineered to be trusted, so trusting it is the default behaviour of a competent operator, not a lapse.

Promoted to the charter by Mos (2026-07-31) after the orchestrator committed this exact error: a --draft flag was silently dropped by a wrapper fallback that still exited 0, and the PR was reported as a draft on the strength of the exit code rather than an observed draft: true (D-12). Twelve failure instances were banked in that session; three of them were the orchestrator's own. That ratio is the point — the mechanism must catch the mechanic too, or it is not a mechanism.

Operationally: after any write, read back the property you required. Applies to gates, wrappers, PR flags, commit authorship, file installs, and message delivery alike.

First-class principle — pre-registration prevents retrofitting, and nothing else

A pre-registered check set can fail in three distinct ways:

mode	the set is…	found as
WRONG	a check does not test what it claims	D-8
INCOMPLETE	green while a criterion's requirement is untested	D-17
INTERNALLY INCONSISTENT	two criteria cannot both hold	D-18

Pre-registration protects against exactly one thing: retrofitting a check to fit the implementation it is supposed to judge. It confers neither correctness, nor coverage, nor consistency. "We pre-registered the checks" has been treated as though it settled the question — it settles one of three.

Promoted to the charter by Mos (2026-07-31). All three modes were found on this mission's own first delivery, by the machinery applied to its own work — not by inspection, and not by looking for them.

Enforceable form — RM-02's four clauses. The registry must establish that: (1) each check is right — proven red for its own stated reason before its green counts; (2) the set covers — every criterion bound to a case that actually exercises it; (3) no two criteria conflict — mutual unsatisfiability is a registry defect discoverable by construction; (4) when a criterion's meaning changes, the registry retains original text, restatement, and reason, so evolution stays auditable. A criterion with no case that can fail for its own reason is unregistered in substance, however it reads in the manifest.

Corollary — never ship an integrity claim dressed as a property

A verification artifact that can be forged by whoever it is meant to catch verifies nothing. If a manifest, marker, ledger, or receipt is writable by the same actor whose behaviour it certifies, it certifies the attack. Such an artifact must sit inside the integrity envelope it belongs to, publish atomically, and carry a tamper negative-control observed red — otherwise its integrity is a claim, not a property.

If it cannot be made tamper-evident, say so and reconsider the approach. Laundering foreign content as certified is the only unacceptable outcome; an honest "this cannot be verified" is always available and always preferable.

First-class principle — when a property cannot exist at the layer it was specified

Some required properties are impossible at the layer that asked for them — not hard, impossible. A local check cannot defend against an actor who can rewrite the check itself. When that happens, there are exactly three honest moves, and all three are mandatory:

1. Implement what the layer can guarantee. Partial protection against the class it was actually born from is worth having.
2. State the boundary precisely, in BOTH directions. What it does not defend, and beside it what it does. A reader who sees only the negative dismisses the check as worthless; one who sees only the positive over-trusts it. Both together is the honest artifact — either alone misleads.
3. Record where the real guarantee will come from — as a TRACKED DEPENDENCY, not prose. It must name a task that someone must close. A documented gap with no owner becomes a permanent gap that reads as intentional.

A written-down gap is acceptable engineering. An implied-fixed gap is this mission's core failure in a new costume — a verification artifact that verifies nothing, with a green to prove it.

Promoted to the charter by Mos (2026-07-31) from D-19. Origin: the RM-01 symlink manifest could not be made tamper-evident against a same-UID actor (CWE-345), because the manifest and its marker share one writable tree. The implementing seat escalated rather than relabelling self-authentication as tamper-resistance — the corollary above firing on its first real adversarial test, on the cheapest seat in the loop. Residual risk bound to RM-59 (depends_on: RM-12, RM-21, RM-25), where the choke-point executor and spine verify from outside the worktree's authority.

Decision record (authoritative, immutable)

• 15/15 proposals decided: 13 accept, 2 modify (P-AUTHORITY-001, P-INBOX-001), 0 reject.
• Site + annotations.json: jarvis-brain/docs/postmortem-spec/site/ (committed, origin/main).
• Discussion checkpoint (rich rationale per proposal): jarvis-brain/docs/scratchpads/postmortem/REMEDIATION-DISCUSSION-STATE.md.
• Postmortem report: mosaicstack/stack PR #107 (merged 88f4ee04).
• MACP wiring scout (verdict c=STRANDED): MACP-WIRING-SCOUT.md (copied into this dir; TODO discharged). Its findings are sound; its recommended wire-in point is superseded by DECISION-1.

The plan — 15 proposals collapse to 4 builds + hygiene

Build	Absorbs	What it is
1. One choke-point service (mechanical enforcer)	MISSION, STATE, AUDIT, WRAPPER, QUEUE	Deterministic program every task/data mutation flows through. Wire the stranded @mosaicstack/macp — typed tasks, gate-runner, event ledger, credential binding, tri-state write outcomes. ⚠ Target CORRECTED 2026-07-31 (DECISION-1, Mos): a new production Node TaskExecutor on the live dispatch path (packages/mosaic launch + packages/coord), which Coord/Forge/live-dispatch submit through. NOT mosaic_orchestrator.py::run_single_task — that controller is "enabled": false and references a dispatcher absent from this checkout; wiring it would strand the executor, reproducing this mission's own disease. The Python rail is deleted, not ported. Both planners reached this independently.
2. One durable spine + hot path	(storage under everything)	PG system-of-record + Redis hot queue (transactional-outbox). Mission/tasks/state-claims/audit-ledger/comms-inbox all land here.
3. Rotation lifecycle (finish the Mission Control Plane)	LIFECYCLE, CONTRACT, GUIDE, RECOVERY	Coordinator daemon: contract-hash binding, compaction-detected → rotate-not-compact, checkpoint→fresh-session→rehydrate, broker-independent recovery. Deterministic, not an LLM. Reuse packages/coord; existing PRD at docs/mission-control/.
4. Comms service	AUTHORITY, INBOX (+ versioning roadmap)	Envelope (comms/v1) → sole-path service → PG/Redis → pluggable adapters (tmux→Matrix/Discord/Slack/Telegram). Version the protocol, not participants.
+ Hygiene & proof	FLEET, WORKFLOW, CONFORMANCE	One roster-owned socket/host + stale GC; allowlist auto-sync; the conformance harness that fault-injects the failure classes and proves builds 1–4 hold.

The finding that sets the cost

Built-but-unwired disease. @mosaicstack/macp is stranded (nothing calls it); packages/coord primitives exist; the Mission Control PRD exists; PG + Redis already run in-stack. Three duplicate MACP islands, an orphaned context loader, a fail-open bypass. Work = wire + consolidate + retire, NOT greenfield. "Finish, don't re-spec."

Sequencing (skeleton — adversarial decomposition refines this)

1. Spine + choke-point service (builds 1+2) — foundation; unlocks MISSION/STATE/AUDIT/WRAPPER/QUEUE at one integration point. (Per DECISION-1, a P0 phase of provable-gate + activation work precedes this; see TASKS.md §3.)
2. Rotation daemon (build 3) on that spine — the drift fix proper.
3. Comms service (build 4) — envelope → service → PG/Redis → adapters; retire direct-tmux.
4. Hygiene + conformance (build 5) — fleet convergence, allowlist sync, dogfood harness.

• Cross-cutting retirements: flat-file orchestration tracking (hard cutover to DB), the 3 duplicate MACP islands, the silent MOSAIC BYPASS.

Standing directives (Jason, 2026-07-31)

• Dogfooding: validate EACH fix against the live fleet failure that motivated it. Seed acceptance tests: Pi brick (RECOVERY), scout-bounce (INBOX/FLEET), gate-6 inert + #1019 recursion (QUEUE), identity drift (WRAPPER), auto-sync sweep (WORKFLOW), #1018 stale-consumed (INBOX). The fleet is its own test bed.
• Orchestration tracking → DB, hard cutover ("rip off the bandaid"), NO flat-file interim. jarvis-brain PDA flat-files untouched. Current flat-file tracking runs as-is/unhardened until DB tracking is real, then one clean replace.
  • ⚠ QUALIFIED 2026-07-31 (DECISION-2, Mos): the DB spine must NOT be a single-point hard-stop. A broker-independent / degraded mode and a rehearsed rollback artifact are design requirements (P-RECOVERY-001), binding now on RM-12, RM-13, RM-23, RM-36 and RM-53. This supersedes the earlier orchestrator recommendation to pre-commit "no DB ⇒ the fleet stops" — that answer is not on record. Only the specific availability target remains open, queued for Jason; it does not block current work.

The 15 decisions (one-line; full rationale in the checkpoint)

1. P-ACTIVATION-001 accept — transactional CLI+hooks+broker+version release; block launch on skew, fail-SAFE.
2. P-AUTHORITY-001 MODIFY — structured authenticated inbox; envelope carries comms-PROTOCOL version; version the protocol not participants; N-version window.
3. P-LIFECYCLE-001 accept — rotation not recursive compaction; pre-empt at token threshold; enforcer = deterministic coordinator; = finish Mission Control Plane.
4. P-MISSION-001 accept — bind lanes to mission+task ledger; convention exists, ENFORCEMENT is the gap; mission+tasks → DB spine (hard cutover).
5. P-QUEUE-001 accept — repair queue transport + exit-asserting non-null-case tests (gate-6 was INERT fleet-wide; #1019 fix recursed the same bug).
6. P-STATE-001 accept — typed claims (source/confidence/TTL) not prose blob; MACP typed record; integrity fail-closed HMAC; don't fork a 4th island.
7. P-AUDIT-001 accept — MACPEvent lifecycle ledger; EXTEND enum to lifecycle events; runtime-neutral (executor-emitted); retire duplicate Python ledger.
8. P-WRAPPER-001 accept — identity derives from seat name + survives respawn; tri-state write outcomes MANDATORY; name safe target metadata.
9. P-CONTRACT-001 accept — bind session to contract hash; re-anchor on policy-change OR compaction-detected; stale generation loses authority MECHANICALLY.
10. P-INBOX-001 MODIFY — sole-path comms SERVICE; PG durable SoR + Redis hot queue (outbox, reconciliation sweeper); pluggable adapters; protocol-first, PG-first-then-Redis.
11. P-RECOVERY-001 accept — broker-independent bootstrap recovery; honest capability labeling; break-glass LOUD+AUDITED+TEMPORARY not silent permanent bypass.
12. P-GUIDE-001 accept — delete /compact and continue from orchestrator path (keep for ephemeral); removal = substitution (wire rotation trigger).
13. P-FLEET-001 accept — one roster-owned socket/host; quarantine unmanaged; stale-session GC; prerequisite for INBOX identity-addressing.
14. P-WORKFLOW-001 accept — auto-sync ALLOWLIST not denylist; worktree/lease isolation for agent docs/source; DB-tracking obviates the flat-file-sweep criterion.
15. P-CONFORMANCE-001 accept — fleet lifecycle harness on REAL runtime artifacts + fault injection; the 100-rotations-lossless bar is a test; target the DB substrate.

Fleet operating model

• Project orchestrator mos-remediation (this seat) owns the mission; coordinates under Mos (lead).
• Adversarial task decomposition: planner-opus (robustness) + planner-sol (pragmatic) each decompose the plan independently; orchestrator reconciles into TASKS.md/DB tasks. Oppositional by design.
• Delivery gates (non-negotiable): author≠reviewer, PRE-REGISTERED diff-blind acceptance checks committed before reading the diff, CI terminal-green, completion = merged PR + closed issue. rev-974 = mosaicstack reviewer.
• Compaction survival: see KICKSTART.md in this dir — the resume procedure. Persist typed state, not transcript.