feat(mosaic): manifest-owned upgrade guard so updates never wipe operator config (#791)

Invert the framework updater from a denylist ("framework owns everything unless
preserved") to an explicit allow-list manifest ("operator owns everything unless
framework"). A path the manifest never anticipated resolves to operator-owned by
the fail-safe default, so it is structurally unreachable by any write or prune.

Root cause (#791): `mosaic update` re-seeds via `install.sh` keep-mode, whose
`rsync -a --delete` + hand-maintained PRESERVE_PATHS denylist wiped operator
paths the denylist forgot (agents/*.conf, policy/*.md, *.local.md, harvester
SOP, tools/_lib/credentials.json, unanticipated fleet files).

- framework-manifest.txt: single SSOT ([framework]/[operator], deny-wins,
  UNKNOWN=>operator fail-safe), read by BOTH installers.
- src/framework/manifest.ts: pure resolver (parse/matchGlob/resolveOwnership/
  frameworkSubtreeRoots/planPrune) — the testable seam.
- tools/_lib/manifest.sh: bash resolver (compiled globs, fork-free hot path),
  sourced by install.sh; parity-tested against the TS resolver.
- install.sh keep mode is now manifest-driven (no --delete): overlay-copy
  framework files, scoped-prune only retired framework files inside shipped
  subtrees. Operator + unknown paths are never written or deleted.
- file-ops.syncDirectory gains an isOperatorOwned guard; file-adapter derives it
  from the shared manifest, replacing the drifted hardcoded preservePaths.

Tests (TDD, red->green):
- HARD GATE test-upgrade-manifest-guard.sh: 10 operator sentinels (incl. an
  unanticipated one) survive a keep-mode reseed byte-identical + mtime-unchanged;
  retired framework file pruned; secret value absent from output. RED 31 fail on
  the old installer -> GREEN 48 pass. Wired merge-blocking into CI.
- manifest-parity.spec.ts (§6.1): bash<->TS agree on 34 paths + subtree roots.
- manifest.spec.ts: 18 tests incl. planPrune property test + shipped-tree
  completeness (§6.2).
- test-install-migration.sh F6 flipped: an unanticipated operator fleet file now
  MUST survive keep-mode reseed.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/design/791-upgrade-config-protection.md

@@ -33,7 +33,7 @@ rsync -a --delete --exclude .git --exclude .framework-version --exclude '*.pre-c
 - `install.sh:199` — `rsync -a --delete`. **`--delete` prunes every path in `~/.config/mosaic`
   that is NOT present in the shipped framework source**, unless excluded.
 - `install.sh:47` — `PRESERVE_PATHS` is the **only** thing standing between `--delete` and operator
-  data. It is a *denylist of exclusions*:
+  data. It is a _denylist of exclusions_:
   ```
   PRESERVE_PATHS=("CONSTITUTION.md" "AGENTS.md" "SOUL.md" "USER.md" "TOOLS.md" "STANDARDS.md"
     "memory" "sources" "credentials" "fleet/roster.yaml" "fleet/roster.json" "fleet/agents"
@@ -43,22 +43,22 @@ rsync -a --delete --exclude .git --exclude .framework-version --exclude '*.pre-c
   `find "$TARGET_DIR" -mindepth 1 -maxdepth 1 ... -exec rm -rf {} +` then re-copies source, restoring
   only PRESERVE_PATHS globs.
 
-**Root-cause model:** *"Everything under `~/.config/mosaic` is framework-owned and pruneable UNLESS
-explicitly preserved."* Any operator path the list forgets is destroyed on the next upgrade.
+**Root-cause model:** _"Everything under `~/.config/mosaic` is framework-owned and pruneable UNLESS
+explicitly preserved."_ Any operator path the list forgets is destroyed on the next upgrade.
 
 ### 1.3 The exact operator paths wiped
 
 Cross-referencing the issue's operator-owned list against `PRESERVE_PATHS`:
 
-| Operator path (issue #791)            | In PRESERVE_PATHS? | Fate on `mosaic update` |
-| ------------------------------------- | ------------------ | ----------------------- |
-| `agents/*.conf` (per-agent runtime)   | **NO**             | **WIPED**               |
-| `policy/*.md` (operator overlays)     | **NO**             | **WIPED**               |
-| `*.local.md` (SOUL/USER/STANDARDS)    | **NO**             | **WIPED**               |
-| harvester / SOP artifacts + timers    | **NO**             | **WIPED**               |
-| `tools/_lib/credentials.json`         | **NO** (`credentials/` dir ≠ this path) | **WIPED** |
-| `fleet/agents/*.env`                  | yes (`fleet/agents`, added by #631) | survives |
-| `memory/`, `fleet/roster.*`, `fleet/backlog`, `fleet/roles.local` | yes | survives |
+| Operator path (issue #791)                                        | In PRESERVE_PATHS?                      | Fate on `mosaic update` |
+| ----------------------------------------------------------------- | --------------------------------------- | ----------------------- |
+| `agents/*.conf` (per-agent runtime)                               | **NO**                                  | **WIPED**               |
+| `policy/*.md` (operator overlays)                                 | **NO**                                  | **WIPED**               |
+| `*.local.md` (SOUL/USER/STANDARDS)                                | **NO**                                  | **WIPED**               |
+| harvester / SOP artifacts + timers                                | **NO**                                  | **WIPED**               |
+| `tools/_lib/credentials.json`                                     | **NO** (`credentials/` dir ≠ this path) | **WIPED**               |
+| `fleet/agents/*.env`                                              | yes (`fleet/agents`, added by #631)     | survives                |
+| `memory/`, `fleet/roster.*`, `fleet/backlog`, `fleet/roles.local` | yes                                     | survives                |
 
 The `fleet/agents`, `memory`, `fleet/backlog` entries were **retro-added after prior incidents**
 (#631). This whack-a-mole is the structural signature of a denylist.
@@ -75,10 +75,11 @@ source over target and skips preserved paths, but **never deletes** target paths
 (`file-ops.ts:77-109`). It is used by the wizard/init flow, not `mosaic update`.
 
 Two problems remain:
+
 1. Its `preservePaths` (`file-adapter.ts:164-185`) has **already diverged** from `install.sh` — it is
    **missing `fleet/backlog` and `fleet/roles.local`**. Two hand-maintained denylists, drifted. This
    is direct evidence for a single shared SSOT manifest.
-2. Even non-destructive, it will happily *overwrite* an operator file that collides with a
+2. Even non-destructive, it will happily _overwrite_ an operator file that collides with a
    framework-shipped path unless that path is on its (incomplete) preserve list.
 
 ### 1.5 Existing snapshot is inadequate for rollback
@@ -94,7 +95,7 @@ Two problems remain:
 
 ### 2.1 Ownership model (invert to allow-list)
 
-Replace *"framework-owned unless preserved"* with *"operator-owned unless framework-owned"*, resolved
+Replace _"framework-owned unless preserved"_ with _"operator-owned unless framework-owned"_, resolved
 **per target path** with operator carve-outs winning inside shared framework subtrees.
 
 Two declared lists, one SSOT data file shipped in the framework
@@ -119,7 +120,7 @@ Two declared lists, one SSOT data file shipped in the framework
 3. else (matches neither) → **UNKNOWN ⇒ operator-owned by default (fail-safe)**: never delete.
 
 Rule 3 is the actual root-cause fix: an operator path the manifest authors forget is still protected,
-because *unknown defaults to operator*. A denylist can never provide this guarantee.
+because _unknown defaults to operator_. A denylist can never provide this guarantee.
 
 ### 2.3 Sync mechanism change (the mechanically-critical part)
 
@@ -154,7 +155,7 @@ Filesystem-observation test in the existing `test-install-migration.sh` harness
    `unknown-operator-dir` surviving proves the fail-safe default — a denylist could not pass this case.
 5. **Positive controls:** framework files WERE updated; a retired framework file WAS pruned.
 6. **Property test** (TS prune-planner): for fuzzed operator paths, `deleteSet ⊆ {matches framework ∧
-   in target ∧ not in source}` and `deleteSet ∩ operatorReserved = ∅`.
+in target ∧ not in source}` and `deleteSet ∩ operatorReserved = ∅`.
 
 ---
 
@@ -192,6 +193,7 @@ The SSOT for those `.env` files is the roster. The reconciler **already** separa
 
 **`mosaic fleet regen`** is therefore a **thin recovery-framed wrapper over the existing projection
 phase** — it does NOT reimplement fleet logic and does NOT preempt in-flight FCM cards (M4/M5):
+
 - Regenerates derivable config (per-agent `*.env.generated`, unit files) from roster SSOT.
 - **Preview-first:** dry-run default; `--write` to apply. Idempotent.
 - **Never restarts agents** (the recovery order forbids restart-before-verify).
@@ -244,7 +246,7 @@ For a currently-wiped fleet EnvironmentFile state — **do NOT service-restart w
 
 1. **Regenerate:** `mosaic fleet regen --write` — rebuild `~/.config/mosaic/fleet/agents/*.env` from
    roster SSOT.
-2. **Verify each unit resolves to the intended runtime/workdir** *before* any restart:
+2. **Verify each unit resolves to the intended runtime/workdir** _before_ any restart:
    `systemctl --user show mosaic-agent@<name> -p EnvironmentFile` and confirm the generated env exists
    and carries the intended `MOSAIC_AGENT_*` runtime/workdir values.
 3. **Only then** `systemctl --user restart mosaic-agent@<name>`, one unit at a time.
@@ -256,11 +258,11 @@ step 1.
 
 ## 8. Proposed PR split (reviewable; DAG-ordered)
 
-| PR  | Scope                                                                                                   | Depends | Review focus            |
-| --- | ------------------------------------------------------------------------------------------------------- | ------- | ----------------------- |
-| PR1 | **PRIMARY** — shared `framework-manifest.json` + ownership resolver + non-deleting sync + scoped prune (bash + TS) + **HARD GATE** + prune-planner tests | —       | correctness (root fix)  |
-| PR2 | **Safety net** — pre-update snapshot (`~/.local/state`, 0700/0600, retention) + post-sync verify/restore + `mosaic restore` | PR1     | **secrev** (backup/secret) |
-| PR3 | **Recovery** — `mosaic fleet regen` (projection-only, preview-first, no restart) + docs (upgrade-safety + recovery runbook) | PR1     | correctness + docs      |
+| PR  | Scope                                                                                                                                                    | Depends | Review focus               |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------------------------- |
+| PR1 | **PRIMARY** — shared `framework-manifest.json` + ownership resolver + non-deleting sync + scoped prune (bash + TS) + **HARD GATE** + prune-planner tests | —       | correctness (root fix)     |
+| PR2 | **Safety net** — pre-update snapshot (`~/.local/state`, 0700/0600, retention) + post-sync verify/restore + `mosaic restore`                              | PR1     | **secrev** (backup/secret) |
+| PR3 | **Recovery** — `mosaic fleet regen` (projection-only, preview-first, no restart) + docs (upgrade-safety + recovery runbook)                              | PR1     | correctness + docs         |
 
 Rationale: PR1 closes the failure class on its own; if PR2/PR3 slip, the class stays fixed. Each PR is
 one reviewable unit with its own tests ≥85%. Independent review (author≠reviewer) on all; **secrev** on

docs/scratchpads/791-upgrade-config-protection.md

@@ -42,5 +42,48 @@ Design-first: write design doc, send to MS-LEAD, WAIT for confirmation before im
   regen+docs. PR2/PR3 depend on PR1.
 
 ### Status
-Design doc written: `docs/design/791-upgrade-config-protection.md`. Sent to MS-LEAD. **WAITING for
-confirmation before Phase 2 implementation.** No impl started.
+Design doc written: `docs/design/791-upgrade-config-protection.md`. Sent to MS-LEAD.
+
+## Session 1 (cont.) — MS-LEAD CONFIRMED → Phase 2 GO
+All 4 asks approved. Binding conditions:
+- TDD tests-first, red-first proof per PR; ≥85% new-code; co-located `*.spec.ts`; never `--no-verify`.
+- HARD GATE test (§2.4, unanticipated sentinel survives byte-identical + mtime unchanged) = MERGE-BLOCKING for PR1.
+- Manifest-completeness test (§6.2) required.
+- Bash+TS read ONE shared `framework-manifest.json`; parity test (§6.1) required (closes #631 drift class).
+- UNKNOWN⇒operator (rule 3) non-negotiable. Keep prune-planner PURE.
+- `fleet regen`: NEVER restart; dry-run default, `--write` to apply; "never issues restart" test mandatory.
+- Independent review every PR; PR2 dedicated secrev.
+- One PR at a time through DAG. Report PR1 exact head + red→green evidence for review commission.
+
+### Now: implementing PR1 (manifest + resolver + non-deleting sync + scoped prune + guard tests).
+
+## Session 2 (2026-07-16) — PR1 built, tests-first, red→green proven
+
+Deviation noted to MS-LEAD in PR: manifest is `framework-manifest.txt` (line-oriented), NOT `.json`.
+Rationale: keep the bash installer free of a python3/jq dependency. The "ONE shared file, parity-
+tested" requirement is honored — `manifest-parity.spec.ts` drives the bash resolver as a subprocess
+and asserts byte-identical ownership vs the TS resolver over 34 probe paths spanning every class.
+
+### PR1 artifacts
+- SSOT: `packages/mosaic/framework/framework-manifest.txt` ([framework]/[operator], deny-wins, fail-safe).
+- TS resolver: `src/framework/manifest.ts` (pure: parse/matchGlob/resolveOwnership/frameworkSubtreeRoots/
+  planPrune) + `manifest.spec.ts` (18 tests incl. planPrune property test + §6.2 completeness).
+- Bash resolver: `framework/tools/_lib/manifest.sh` (compiled globs → fork-free `manifest_is_framework`;
+  CLI `resolve|subtree-roots|classify`). Sourced by install.sh.
+- HARD GATE (§2.4): `framework/tools/quality/scripts/test-upgrade-manifest-guard.sh` — keep-mode reseed,
+  10 operator sentinels (incl. unanticipated `unknown-operator-dir/x`, `harvester/sop.md`,
+  `fleet/my-fleet.yaml`) survive byte-identical + mtime-unchanged; retired framework file pruned;
+  secret value absent from output. RED=31 fail (orig install.sh) → GREEN=48 pass (fixed).
+- install.sh: keep mode now manifest-driven (`sync_framework_keep`, no `--delete`); overwrite unchanged.
+  PRESERVE_PATHS denylist deleted.
+- TS sync: `file-ops.syncDirectory` gains `isOperatorOwned` guard; `file-adapter.syncFramework` derives
+  it from `loadManifest` — hardcoded (drifted) preservePaths deleted. Fixture uses the REAL manifest.
+- Parity: `manifest-parity.spec.ts` (§6.1) — bash↔TS agree on 34 paths + subtree roots.
+- Migration matrix `test-install-migration.sh`: F6 flipped — `my-fleet.yaml` now MUST survive (fail-safe).
+- CI: new merge-blocking `upgrade-guard` step (`.woodpecker/ci.yml`) runs both bash suites (adds rsync).
+- update-checker.ts reseed comment corrected to the manifest model.
+
+### Gates (all green)
+- `pnpm typecheck` ✓ · `pnpm lint` ✓ · `pnpm format:check` ✓
+- Full mosaic vitest: 1062 passed (cli-smoke needs `pnpm build` first — build-artifact dep, not this change).
+- HARD GATE 48/48 · migration 21/21 · parity 3/3 · manifest 18/18 · file-adapter 8/8.