feat(deploy): install update/remove scripts into .mam_deploy/ and refine markdown staging

2026-08-04 22:17:59 +09:00
parent 2ff8b2c4a9
commit 68eff79810
7 changed files with 1092 additions and 157 deletions
@@ -0,0 +1,321 @@
+# 📐 구현 계획서 Rev.2 — `deploy/*` 배포 스크립트 개선 (Job `0d43714b`)
+
+- **작성자**: Planner (`canary-projects-multi-agent-mux-creator-claude`)
+- **개정 사유**: Creator `agy`의 이의제기(Job `029f61b1`) 반영
+- **선행 문서**: Job `101c90a2` 계획서 Rev.1 (본 문서가 이를 대체함 — 구현 시 **본 문서만** 참조)
+- **기준 커밋**: `2ff8b2c` (branch `main`)
+
+---
+
+## 0. 이의제기 판정 (Challenge Adjudication)
+
+`agy`의 지적은 **실재하는 데이터 소실 위험을 정확히 짚었고, 채택합니다.** 다만 원인 귀속과 처방 두 가지에는 실측으로 반박되는 부분이 있어 수정 채택합니다.
+
+| # | `agy`의 주장 / 처방 | 판정 | 근거 |
+| :-- | :--- | :---: | :--- |
+| ① | 로컬 커스텀 스킬 코드가 무단 덮어쓰기로 소실될 수 있다 | **채택** | E-6/E-7에서 실제 소실 재현. 잔존 사본 0건 |
+| ② | "기존 `install.sh`는 파일이 있으면 건너뛰어 안전하게 **보호되었다**" | **반박** | 프레임워크 소유 파일은 이미 `cp -f`로 **무조건 덮어쓰기**(`install.sh:166`). 보호는 정책이 아니라 fetch 블록이 통째로 스킵된 **부작용**이었음 |
+| ③ | "R-1(`MAM_REFRESH=1`)이 이 위험을 **발생시킨다**" | **반박(부분 채택)** | 위험은 **오늘 이미 존재**함 — `install.sh -f`(문서화된 플래그)와 `update.sh` 두 경로에서 재현됨. R-1은 원인이 아니라 **노출 빈도를 넓히는 요인**. 따라서 가드는 R-1의 전제조건으로 **필수**이되, R-1만 고쳐서는 부족 |
+| ④ | 처방 A: 덮어쓰기 전 `.agents/skills/.../*.user-bak` 자동 백업 | **반려 → 대체** | `.agents/`는 §5.1에서 **의도적으로 gitignore하지 않기로** 결정한 경로. 백업이 사용자 저장소에 추적 파일로 쌓이고, manifest에 없어 `remove.sh`가 절대 청소하지 못함 → `agy` 본인이 직전 라운드(`c6c43df9`)에서 지적한 **백업 무한 증식**을 재현. `.mam/skill-backups/<ts>/`로 이전 |
+| ⑤ | 처방 B: 로컬 변경 감지를 **diff/hash/mtime**로 | **반려 → 대체** | **치명적 오설계.** 수신 파일과 비교하면 "구버전 설치본"과 "사용자 수정"을 구분할 수 없어 **모든 정상 업데이트가 로컬 수정으로 오판**됨 → 갱신이 영구 no-op이 되어 R-1이 고치려던 E-4 버그로 회귀. mtime은 `cp -f`가 매 설치마다 갱신하므로 출처 정보가 아예 없음. **설치기가 마지막에 기록한 해시**와 비교해야 함(§2.2) |
+| ⑥ | 처방 C: 기본 보존 + `--overwrite-custom` 플래그 + 안내 문구 | **채택** | 안전한 기본값. 다만 "조용히 건너뛰기"는 버전 불일치를 유발하므로 **항목별 경고 + 상태 기록**을 의무화(§2.4) |
+| ⑦ | (미지적) 처방이 `install.sh` 복사 루프에만 적용됨 | **보완 추가** | `update.sh`는 `remove.sh --force`로 **스킬을 먼저 전부 삭제한 뒤** 재설치한다. install.sh에 가드를 넣어도 이 경로에서는 이미 파일이 없어 아무 효과가 없음(E-7). 3개 경로 전부를 덮어야 함(§3) |
+
+**추가 자기수정(Planner 귀책)**: Rev.1 §5.2가 `gitignore_created`를 `.mam/install_state`에 기록하도록 했으나, `update.sh`는 `.mam`에서 **명시적 allowlist 4종만** 스테이징하므로 업데이트 시 이 상태가 소실됩니다(§4). `agy`가 지적하지 않았지만 같은 계열의 결함이므로 함께 수정합니다.
+
+---
+
+## 1. 신규 실측 근거 (Evidence, Rev.2)
+
+임시 워크스페이스에 정상 설치 후 프레임워크 소유 파일 2개(`scripts/mqtt_common.py`, delegate-job 래퍼)에 로컬 커스터마이즈를 가하고 각 경로를 실행했습니다.
+
+### E-6. 오늘의 `install.sh -f`가 이미 무경고로 파괴함
+
+```
+$ bash install.sh -f "$WORK"
+exit=0
+  mqtt_common.py  CORP_CA_BUNDLE  : 1 → 0      ← 소실
+  wrapper         LOCAL marker    : 1 → 0      ← 소실
+  워크스페이스 내 잔존 사본        : (NONE)
+  로컬 변경 관련 경고               : 없음
+  실제 출력된 문구:
+      "✅ Skills staged into workspace (user documents and custom configs preserved)."
+```
+
+마지막 줄이 핵심입니다. 설치기는 **커스텀 설정을 보존했다고 명시적으로 안심시키는 문구를 출력하면서 같은 실행에서 커스텀 코드를 파괴**합니다. 문구의 원래 의도는 `.mam.env`·사용자 문서를 가리키지만, 스킬 수정본을 잃은 사용자에게는 경고가 아니라 **역방향의 오신호**입니다. 즉 `agy`가 지적한 위험은 "R-1이 도입할 미래의 위험"이 아니라 **이미 출시되어 문서화된 플래그에 존재하는 현재의 버그**입니다.
+
+### E-7. 업데이트 경로는 install.sh 가드로 막을 수 없음
+
+`update.sh:151`이 실행하는 명령을 그대로 재현했습니다.
+
+```
+$ bash remove.sh --force
+exit=0
+  .agents/skills/.../mqtt_common.py 존재 : NO — deleted
+  잔존 사본                              : (NONE)
+```
+
+`remove.sh`가 manifest에 따라 `.agents/skills/**` 28개 파일을 삭제한 **뒤에** 새 `install.sh`가 실행됩니다. 그 시점에 로컬 수정본은 이미 존재하지 않으므로, **복사 루프에 어떤 감지 로직을 넣어도 감지할 대상이 없습니다.** `agy`의 처방을 그대로 구현하면 "가드를 넣었는데도 업데이트 한 번에 코드가 사라진다"는 최악의 결과가 됩니다 — 안전하다고 믿게 만들면서 보호하지 못하는 상태.
+
+### E-8. 감지 기준의 반증
+
+`agy`가 제안한 "기존 파일이 **원본 템플릿과 다른지**" 검사를 그대로 적용하면:
+
+| 상황 | 로컬 파일 vs 수신 템플릿 | 올바른 처리 | `agy` 기준의 판정 |
+| :--- | :---: | :--- | :--- |
+| 사용자가 수정함 | 다름 | 보존 | 보존 ✅ |
+| **구버전이 설치돼 있음(정상 갱신 대상)** | **다름** | **덮어쓰기** | **보존 ❌ → 갱신 영구 실패** |
+| 최신본이 이미 설치됨 | 같음 | no-op | no-op ✅ |
+
+2행이 R-1의 **유일한 존재 이유**입니다. 수신 파일과의 비교로는 2행과 1행이 원리적으로 구분되지 않으므로, R-1을 구현하면서 이 기준을 쓰면 E-4(재실행이 조용한 no-op)로 정확히 되돌아갑니다.
+
+---
+
+## 2. 설계 R-1′ — 안전 갱신 (Safe Refresh)
+
+### 2.1 원칙
+
+> 갱신은 **설치기가 스스로 쓴 것만** 덮어쓴다. 그 외 모든 것은 사용자 것으로 간주한다.
+
+`.env` 마이그레이션에서 확립한 **증거 기반 소유 판정** 원칙과 동일합니다. 소유 증거는 manifest(경로)만으로 부족하며 **내용 지문**이 필요합니다.
+
+### 2.2 소유 지문 대장 — `.mam/asset_hashes.txt`
+
+설치기가 파일을 쓸 때마다 그 시점의 내용 해시를 기록합니다.
+
+```
+<sha256>  .agents/skills/lib.sh
+<sha256>  .agents/skills/multi-agent-mux-delegate-job/scripts/mqtt_common.py
+...
+```
+
+갱신 시 3-way 판정:
+
+| 조건 | 의미 | 처리 |
+| :--- | :--- | :--- |
+| `hash(현재) == 대장의 해시` | 설치기가 쓴 그대로 (미변경) | **덮어쓰기** + 대장 갱신 |
+| `hash(현재) != 대장의 해시` | 사용자가 수정함 | **보존** + 경고 + 상태 기록 |
+| 대장에 항목 없음 (구 설치본) | 출처 불명 | §2.5 부트스트랩 규칙 |
+| `hash(현재) == hash(수신)` | 이미 최신 | no-op (백업·경고 불필요) |
+
+대상은 `.agents/skills/**` **28개 파일**(432 KB)뿐이므로 해시 비용은 무시할 수준입니다.
+
+> ⚠️ **구현 함정**: `sha256sum`은 GNU coreutils 전용이며 **stock macOS에는 없습니다**(macOS는 `shasum`). 본 개발 머신에는 coreutils가 설치돼 있어 로컬 테스트는 통과하고 실사용자만 깨지는 전형적 분기가 발생합니다. §2.3의 `python3 hashlib` 인라인을 사용하십시오 — `install.sh`가 이미 python3를 하드 의존성으로 검증합니다(Rev.1 §2.3과 동일한 근거).
+
+### 2.3 백업 위치 — `.mam/skill-backups/<UTC타임스탬프>/<원경로>`
+
+`.user-bak` 인플레이스 방식을 쓰지 않는 이유:
+
+1. `.agents/`는 **의도적으로 gitignore 대상이 아님**(Rev.1 §5.1) → 백업이 사용자 저장소에 추적 파일로 유입.
+2. manifest에 등재되지 않으므로 `remove.sh`가 **영구히 청소하지 못함** → 언인스톨 후에도 잔재.
+3. 갱신할 때마다 누적 → `agy`가 직전 라운드에서 정확히 지적한 **백업 증식** 재현.
+
+`.mam/skill-backups/`는 ① gitignore 관리 블록의 `/.mam/`으로 이미 커버 ② `remove.sh`의 `delete_asset ".mam"`으로 자동 정리 ③ 사용자 트리 무오염을 모두 만족합니다.
+
+**중복 억제(직전 잡 `fe4e0e6f`의 교훈 적용)**: 백업 직전 기존 `skill-backups/*/<같은 경로>` 중 내용이 동일한 사본이 있으면 새로 만들지 않습니다. `cmp` 실패 시에는 **보존 쪽으로 실패**(백업 생성)합니다.
+
+### 2.4 기본 동작과 플래그
+
+```bash
+--overwrite-custom          # 로컬 수정본까지 덮어쓴다 (백업은 여전히 남김)
+MAM_OVERWRITE_CUSTOM=1      # curl | bash 파이프용 환경변수 동치
+```
+
+- **기본값 = 보존**. `agy`의 처방 C를 채택합니다.
+- 보존 시 **파일 목록을 항목별로 출력**해야 합니다. 총계만 찍으면 사용자는 무엇이 낡았는지 알 수 없습니다.
+
+```
+ℹ️  Local modifications detected — these files were NOT updated:
+      .agents/skills/multi-agent-mux-delegate-job/scripts/mqtt_common.py
+      .agents/skills/multi-agent-mux-delegate-job/multi-agent-mux-delegate-job
+    Your copies are preserved as-is. Backups: .mam/skill-backups/20260804T120000Z/
+    ⚠️  Mixing customised files with updated framework files can break the backplane.
+    To take the upstream version (a backup is still made): re-run with --overwrite-custom
+```
+
+- **버전 불일치 경고를 의무화**하는 이유: delegate-job 백플레인은 `registry.py`·`mqtt_common.py`·`publish_event.py`·래퍼가 한 벌로 동작합니다. 한 파일만 구버전으로 남으면 "업데이트 성공"이라 표시된 채 이벤트가 실패하는, 진단이 어려운 상태가 됩니다. 조용한 skip은 금지합니다.
+- `.mam/version.txt`에 `preserved_local=<n>`을 기록해 사후 진단 가능하게 합니다.
+
+### 2.5 부트스트랩(대장이 없는 기존 설치본)
+
+기존 설치본에는 `asset_hashes.txt`가 없습니다. 여기서 "출처 불명 = 보존"을 택하면 **설치 기반 전체가 첫 갱신에서 no-op**이 되어 R-1이 무력화됩니다. 따라서:
+
+> 대장 없음 + 내용이 수신본과 다름 → **백업 후 덮어쓰기**, 그리고 그 사실을 출력.
+
+신선도(R-1의 목적)와 복구 가능성(agy의 목적)을 동시에 만족하며, 이 1회 이후로는 대장이 존재하므로 정밀 판정(기본 보존)으로 전환됩니다. 내용이 수신본과 같으면 백업도 경고도 만들지 않습니다.
+
+```
+ℹ️  No asset fingerprints found (installed by an older version).
+    Backing up current skills to .mam/skill-backups/<ts>/ before refresh.
+```
+
+---
+
+## 3. 3개 경로 전수 적용 (`agy` 처방의 결정적 확장)
+
+| # | 경로 | 현재 위험 | Rev.2 처리 |
+| :-- | :--- | :--- | :--- |
+| P-A | `install.sh` 갱신(`-f` 및 R-1 기본 fetch) | E-6: 무경고 파괴 | §2 안전 갱신 적용 |
+| P-B | `update.sh` (문서화된 **주 업데이트 수단**) | E-7: `remove.sh`가 선삭제 → 가드 무효 | **remove.sh 호출 전 스냅샷**(§3.1) |
+| P-C | `remove.sh` 단독 실행(언인스톨) | 수정본이 조용히 삭제됨 | 항목별 경고 + 조건부 보존(§3.2) |
+
+### 3.1 P-B — `update.sh` 선스냅샷
+
+`update.sh`는 이미 `.mam.update-tmp` 스테이징 구조를 갖고 있으므로 여기에 얹습니다.
+
+```
+1) (remove.sh 호출 전) asset_hashes.txt 기준으로 수정된 프레임워크 파일 산출
+2) .mam.update-tmp/skill-backups/<ts>/ 로 복사   ← remove.sh가 지우지 못하는 위치
+3) bash "$REMOVER" --force "$TARGET_DIR"
+4) 새 install.sh 실행
+5) .mam.update-tmp/skill-backups → .mam/skill-backups 로 복원 + 목록 출력
+```
+
+**주의**: 이 스냅샷은 "수정본을 자동으로 되살리지 않습니다." 업데이트 후 트리에는 최신 프레임워크가 들어가고, 사용자 수정본은 백업으로만 남습니다. 자동 병합은 3-way merge가 필요해 셸 설치기의 책임 범위를 넘습니다. **출력에서 이 점을 명확히 말해야 합니다** — "백업했다"가 "복원했다"로 오해되면 안 됩니다.
+
+```
+💾 3 locally-modified skill file(s) backed up to .mam/skill-backups/<ts>/
+   The updated framework files are now in place; your changes were NOT re-applied.
+   Diff and re-apply manually if you still need them.
+```
+
+### 3.2 P-C — `remove.sh` 언인스톨
+
+- 삭제 대상 중 로컬 수정 파일이 **있을 때만** 동작합니다(없으면 출력·디렉토리 생성 모두 없음 → 일반 사용자에게 잔재 0).
+- 대화형: 확인 프롬프트에 수정 파일 목록을 포함해 사용자가 중단할 수 있게 합니다.
+- `-y/--force`: 목록을 출력하고 `<workspace>/.mam-skill-backup.<ts>/`로 보존합니다. `.mam` 내부는 언인스톨 시 삭제되므로 쓸 수 없습니다.
+- `--purge-skills` 지정 시에만 보존 없이 삭제합니다.
+
+> 이는 직전 잡(P-1)에서 확립한 "`-y`(비대화 의도)는 삭제 권한이 아니다" 원칙의 직접 적용이며, 루트에 백업을 남기는 것은 `.mam.env.mam-backup`이 이미 따르는 기존 전례와 일관됩니다. 관리 블록에 `/.mam-skill-backup.*/`를 추가합니다(§5).
+
+---
+
+## 4. 자기수정 — `.mam` 잔존 allowlist 결함
+
+`update.sh:94-120`은 `.mam`에서 **다음 4종만** 스테이징합니다: `agent-sessions.*`, `jobs/`, `delegate_job_logs/`, `install_manifest.txt`. `remove.sh`가 `.mam`을 통째로 지우므로 **여기 없는 것은 업데이트 때마다 소멸**합니다.
+
+영향:
+
+| 파일 | 도입 위치 | 소실 시 결과 |
+| :--- | :--- | :--- |
+| `.mam/install_state` (`gitignore_created`) | Rev.1 §5.2 | 언인스톨 시 `.gitignore` 소유 판정 불가 → 빈 파일 잔존(안전측 실패, 경미) |
+| `.mam/asset_hashes.txt` | Rev.2 §2.2 | **업데이트마다 대장 소실 → 매번 부트스트랩 경로 → 정밀 판정이 영구히 동작하지 않음** |
+| `.mam/version.txt` | Rev.1 §6.2 | 버전 이력 단절 |
+| `.mam/skill-backups/` | Rev.2 §2.3 | 백업이 업데이트로 삭제 |
+
+**조치**: `update.sh`의 스테이징/복원 목록에 위 4개를 추가하고, 나아가 **개별 열거 대신 `.mam` 전체를 복사한 뒤 새 manifest만 새것으로 덮는 방식**으로 바꿀 것을 권고합니다(신규 상태 파일이 추가될 때마다 이 목록을 고쳐야 하는 구조적 취약성 제거). 후자를 택할 경우 `.mam/jobs` 용량이 큰 워크스페이스에서 복사 비용이 늘 수 있으므로, `cp -a`로 한 번에 처리하고 실패 시 기존 트랩(`restore_on_failure`)에 위임합니다.
+
+---
+
+## 5. Rev.1에서 변경되는 항목 요약
+
+| 절 | 변경 |
+| :--- | :--- |
+| §5.1 관리 블록 | `/.mam-skill-backup.*/` 1행 추가 |
+| §5.2 소유권 기록 | `.mam/install_state` 유지, 단 §4에 따라 `update.sh` 잔존 목록에 반드시 포함 |
+| §6.1 fetch 기본화 | **§2 안전 갱신 가드 구현이 선행 조건**. 가드 없이 기본값만 바꾸는 커밋은 금지 |
+| §6.2 버전 스탬프 | `preserved_local=<n>` 필드 추가 |
+| §7 커밋 | C3 분할 및 C12~C14 추가(§6) |
+| §8 테스트 | T-D21~T-D28 추가(§7) |
+| §11 리스크 | RK-8 신설, RK-5 완화책 보강 |
+
+그 외 R-2(필수 마크다운), R-3(`.mam_deploy`), R-4(`.gitignore`) 설계와 B-1/B-2/B-3 차단 항목은 **Rev.1 그대로 유효**합니다. `agy`도 해당 부분에는 이의를 제기하지 않았습니다.
+
+---
+
+## 6. 개정 커밋 분해
+
+| # | 커밋 | 대상 | 비고 |
+| :-- | :--- | :--- | :--- |
+| C1 | `feat(deploy): ship only runtime-essential markdown to targets` | `install.sh` | Rev.1 §3.2 |
+| C2 | `fix(deploy): align install_mam.sh asset excludes with install.sh` | `install_mam.sh` | Rev.1 §3.3 |
+| **C3a** | `feat(deploy): record asset fingerprints on install` | `install.sh` | §2.2 — **대장 기록만**, 판정 로직 없음(동작 무변화) |
+| **C3b** | `feat(deploy): preserve locally modified skills on refresh` | `install.sh` | §2.3-2.5 — 백업·보존·`--overwrite-custom` |
+| **C3c** | `feat(deploy): fetch latest assets by default and stamp version` | `install.sh` | Rev.1 §6 — **C3b 이후에만 머지 가능** |
+| C4 | `refactor(deploy): resolve workspace from script location` | `remove.sh`, `update.sh` | Rev.1 §4.2 |
+| C5 | `feat(deploy): support .mam_deploy layout in uninstaller/updater` | `remove.sh`, `update.sh` | Rev.1 §4.3/4.4 |
+| C6 | `feat(deploy): install remove.sh/update.sh under .mam_deploy/` | `install.sh` | **C5 이후** |
+| C7 | `feat(deploy): manage a .gitignore block for installed artifacts` | `install.sh` | Rev.1 §5.1-5.3 + §5 |
+| C8 | `feat(deploy): strip the managed .gitignore block on uninstall` | `remove.sh` | **C7 이후** |
+| C9 | `feat(deploy): unify install_mam.sh gitignore and deploy scripts` | `install_mam.sh` | Rev.1 §5.4 |
+| **C12** | `fix(deploy): preserve .mam state files across the update cycle` | `update.sh` | §4 — **C3a 이후, C3c 이전** |
+| **C13** | `feat(deploy): snapshot modified skills before update removal` | `update.sh` | §3.1 |
+| **C14** | `feat(deploy): warn and preserve modified skills on uninstall` | `remove.sh` | §3.2 — GM 판단으로 분리 가능(분리 시 P-C 구멍 잔존 명시) |
+| C10 | `test(deploy): cover asset allowlist, layout, gitignore and safe refresh` | `tests/test_deploy_layout.py` | §7 |
+| C11 | `docs(deploy): document layout, refresh, gitignore and custom-skill policy` | 문서 4종 | Rev.1 §9 + `--overwrite-custom`·백업 정책 |
+
+**신규 순서 제약 (위반 시 데이터 소실 커밋이 트리에 남음):**
+
+- **C3a → C3b → C3c** — 대장 없이 판정 로직을 넣으면 전량 부트스트랩 경로로 빠지고, 가드 없이 fetch만 기본화하면 **E-6의 파괴를 전 사용자에게 기본값으로 배포**하게 됩니다. C3c를 먼저 머지하는 것은 **금지**입니다.
+- **C3a → C12** — 대장을 만들자마자 업데이트가 그것을 지우면 §2.2가 영구히 부트스트랩 모드로 동작합니다.
+- **C13은 C3a 이후** — 수정 파일 산출에 대장이 필요합니다.
+
+---
+
+## 7. 추가 테스트 (Rev.1 T-D1~T-D20에 이어서)
+
+| ID | 검증 내용 | 판정 |
+| :--- | :--- | :---: |
+| T-D21 | 커스터마이즈된 스킬 파일이 있는 상태로 갱신 → **파일 내용 보존**, exit 0, 목록이 stdout에 출력됨 | **B-4** |
+| T-D22 | 미변경 스킬 파일은 정상 갱신됨(E-4 회귀 방지가 T-D21에 의해 무력화되지 않았는지) | **B-4** |
+| T-D23 | **구버전이 설치된 상태(대장 존재, 사용자 미수정)에서 갱신 시 덮어써짐** — §E-8 2행 오판 방지 | **B-4** |
+| T-D24 | `--overwrite-custom` 시 덮어쓰되 `.mam/skill-backups/<ts>/`에 사본 존재 | |
+| T-D25 | 백업이 `.agents/` 하위에 **생성되지 않음**(`find .agents -name '*.user-bak'` → 0건) | |
+| T-D26 | 동일 내용 2회 갱신 시 백업 디렉토리 **증식하지 않음**(중복 억제) | |
+| T-D27 | `update.sh` 1회 실행 후 `.mam/asset_hashes.txt`·`install_state`·`version.txt`·`skill-backups/`가 **모두 잔존** | **B-5** |
+| T-D28 | 수정본이 있는 상태로 `update.sh` 실행 → 최신 프레임워크 적용 + 백업 존재 + "NOT re-applied" 문구 출력 | |
+| T-D29 | 대장 없는 구 설치본 갱신 → 백업 생성 후 덮어쓰기, 2회차부터는 정밀 판정 | |
+| T-D30 | `remove.sh -y` (수정본 존재) → `.mam-skill-backup.<ts>/` 생성; 수정본 없으면 **디렉토리 미생성** | C14 채택 시 |
+| T-D31 | 해시 계산이 `sha256sum`/`shasum` 존재 여부에 의존하지 않음(PATH에서 둘 다 제거해도 통과) | |
+
+**차단 항목 추가**: **B-4**(안전 갱신 3-way 판정 — 실패 시 사용자 코드 소실 또는 갱신 영구 실패), **B-5**(`.mam` 상태 파일 잔존 — 실패 시 B-4가 구조적으로 동작 불능).
+
+**차단 항목은 총 5건: B-1, B-2, B-3, B-4, B-5.**
+
+---
+
+## 8. DoD 게이트 (추가분)
+
+| 게이트 | 조건 |
+| :--- | :--- |
+| **I. 커스텀 보존** | 수정된 스킬 파일이 `install.sh` 갱신·`install.sh -f`·`update.sh` **3경로 모두**에서 소실되지 않음(원본 보존 또는 백업 존재) |
+| **J. 갱신 유효성** | 미수정 파일은 3경로 모두에서 최신본으로 갱신됨 — 보존 로직이 R-1을 무력화하지 않았음을 증명 |
+| **K. 무오염** | 갱신·업데이트·언인스톨 후 `.agents/` 하위에 백업/잔재 파일 0건 |
+| **L. 문구 정합** | "custom configs preserved" 류 문구가 **실제로 보존된 대상만** 지칭하도록 수정됨(E-6의 오신호 제거) |
+
+게이트 L은 문구 한 줄이지만 별도 항목으로 둡니다. E-6에서 확인했듯 **틀린 안심 문구는 경고가 없는 것보다 나쁩니다.**
+
+---
+
+## 9. 리스크 (개정)
+
+| ID | 리스크 | 영향 | 완화 |
+| :-- | :--- | :---: | :--- |
+| RK-1~RK-7 | Rev.1과 동일 | — | Rev.1 §11 |
+| **RK-8** | 보존 로직이 과도하게 동작해 갱신이 사실상 no-op화(E-4 회귀) | **높음** | 수신본이 아닌 **대장**과 비교(§2.2), T-D22/T-D23이 차단 |
+| **RK-9** | 백업했다는 문구를 사용자가 "복원됐다"로 오해 | 중 | §3.1 문구 규정, 게이트 L |
+| **RK-10** | C3c(fetch 기본화)를 C3b보다 먼저 머지 | **치명** | §6 순서 제약, B-4 |
+| **RK-11** | 버전 스큐(구 파일 1개 + 신 파일 다수)로 백플레인 오작동 | 중 | 항목별 경고 의무화(§2.4), `--overwrite-custom` 안내 |
+| RK-5(개정) | fetch 기본화로 오프라인/CI 실패 | 중 | `--no-refresh` + 자산 부재 시 fetch 유지 |
+
+---
+
+## 10. 결론
+
+`agy`의 이의제기는 **채택**합니다. 다만 세 가지를 수정합니다.
+
+1. 이 위험은 R-1이 만드는 것이 아니라 **`install.sh -f`와 `update.sh`에 이미 존재하는 버그**입니다(E-6/E-7). 따라서 가드는 R-1의 부속이 아니라 **선행 조건**이며, R-1을 채택하지 않더라도 독립적으로 고쳐야 합니다.
+2. 감지 기준을 **수신 템플릿과의 비교에서 설치 시점 해시 대장과의 비교로** 바꿉니다. 원안대로면 정상 갱신과 사용자 수정이 구분되지 않아 R-1이 무력화됩니다(E-8).
+3. 백업 위치를 `.agents/**/*.user-bak`에서 **`.mam/skill-backups/<ts>/`**로 옮기고, 보호 범위를 `install.sh` 복사 루프에서 **install/update/remove 3경로 전체**로 확장합니다. 원안 위치는 gitignore되지 않고 manifest에도 없어 영구 잔재가 되며, 원안 범위는 주 업데이트 경로를 전혀 보호하지 못합니다(E-7).
+
+부수적으로, `agy`가 지적하지 않았으나 같은 계열인 Planner 귀책 결함 1건(`.mam` 상태 파일이 업데이트 시 소멸, §4)을 함께 수정합니다.
+
+---
+
+## 11. 역할 경계
+
+본 문서는 설계 산출물이며 **Planner는 저장소 코드를 일절 수정하지 않았습니다**(`MULTI_AGENT_RULES.md` §4). E-6~E-8 실험은 임시 디렉토리(`/tmp/mam_cust_*`)에서 수행 후 정리했으며, 저장소 워킹트리는 클린 상태입니다. 구현은 Creator, 커밋은 GM 소관입니다.
+
+**차단 항목은 B-1, B-2, B-3, B-4, B-5 5건입니다.**
+
+[AGREEMENT: REACHED]
@@ -0,0 +1,107 @@
+# Cross Code Review Report — Job 384b7986
+
+- **Job ID**: 384b7986
+- **Reviewer**: cline (session: herdr:canary-projects-multi-agent-mux-creator-cline)
+- **Target**: Improve deployment files in `deploy/*` (4 requirements: latest updates / essential markdowns only / install remove.sh & update.sh into `{workspace}/.mam_deploy/` / generate `.gitignore`)
+- **Date**: 2026-08-04
+- **Diff scope**: 4 files modified, +516 / −157 (`deploy/install.sh` +373/−, `deploy/install_mam.sh` +96/−, `deploy/remove.sh` +152/−, `deploy/update.sh` +52/−). New untracked test suite `tests/test_deploy_layout.py` (5 tests, T-D1→T-D28).
+
+---
+
+## 1. Summary
+
+The changeset refactors the MAM deployment scripts into a Rev.2 layout that satisfies all four stated requirements. The implementation is cohesive, idempotent, and backward-compatible:
+
+1. **Latest updates (safe-refresh)** — `deploy/install.sh` now defaults to `REFRESH=1` (was opt-in `FORCE_REFRESH`) and adds a 3-way content-hash reconciliation (`COPY_NEW` / `UPDATE_UNMODIFIED` / `BOOTSTRAP_OVERWRITE` / `PRESERVE_CUSTOM` / `FORCE_OVERWRITE_CUSTOM`) against `.mam/asset_hashes.txt`. User-modified framework skills are preserved and backed up to `.mam/skill-backups/<TS>/` unless `--overwrite-custom` is passed. A `--no-refresh|--offline` flag is added for air-gapped reinstalls. `remove.sh` now backs up locally-modified skills to `.mam-skill-backup.<TS>/` before deletion (mirroring install-side preservation).
+
+2. **Essential markdowns only** — Archive/git fetch excludes `.agents/reports/*`, `.agents/references/*`, `MESSAGING.md`, `BOOTSTRAP.md`, `BOOTSTRAP.ko.md` via `tar --exclude` and `find ... *.tmp|*.log|*.pyc` skip. Default root docs limited to `AGENTS.md` (`MAM_INSTALL_DOCS=minimal`); `INSTALL.md` placed under `.agents/`. The separate `install_mam.sh` rsync gains `--exclude='/references/' --exclude='*.tmp'` (previously only excluded `.git/`, `/reports/`, `*.log`, `__pycache__/`, `*.pyc`). Verified: installed workspace contains no `reports/`, `references/`, `MESSAGING.md`, or `BOOTSTRAP.md`.
+
+3. **`.mam_deploy/` layout** — `install.sh` and `install_mam.sh` both now copy `deploy/remove.sh` and `deploy/update.sh` into `.mam_deploy/` (chmod 0755, registered in manifest). Legacy root-level `remove.sh`/`update.sh` are migrated into `.mam_deploy/` if manifest-owned. `remove.sh` and `update.sh` gain `SCRIPT_DIR`-based auto-resolution: when invoked from inside `.mam_deploy/`, they target the parent workspace; when passed `.mam_deploy` as the target arg, they normalize to its parent. `update.sh` uses dual-resolution (`REMOVER` loop over `.mam_deploy/remove.sh` then `remove.sh`) before invoking the uninstaller.
+
+4. **`.gitignore` generation** — Both installers inject an idempotent managed block (`# >>> MAM managed block ... <<<`) via a Python filter that removes any stale block before re-inserting. Block covers `/.venv/`, `/.mam/`, `/.mam_deploy/`, `/.mam.env`, `/.mam.env.*`, `!/.mam.env.example`, `/.cache/multi-agent-mux-monitor/`, `/.mam-skill-backup.*/`, `CURRENT_JOB.md`. `remove.sh` cleans the block on uninstall and removes the file entirely if it created it (`gitignore_created=1` recorded in `.mam/install_state`). `.gitignore` is **never** written to the install manifest (B-1 gate — explicitly asserted by T-D14).
+5. **State preservation across updates (B-5)** — `update.sh` now stages and restores `install_state`, `asset_hashes.txt`, `version.txt`, and `skill-backups/` alongside the pre-existing `jobs/`, `delegate_job_logs/`, and `agent-sessions.*` — verified by T-D27/T-D28.
+
+---
+
+## 2. Verification Evidence
+
+### 2.1 Syntax checks — ALL PASS
+```
+bash -n: 4/4 deploy shell scripts OK
+  - deploy/install.sh      OK
+  - deploy/install_mam.sh  OK
+  - deploy/remove.sh       OK
+  - deploy/update.sh       OK
+py_compile: tests/test_deploy_layout.py OK
+```
+
+### 2.2 Targeted test suite — 5/5 PASS (13.68s)
+```
+tests/test_deploy_layout.py::TestDeployLayout
+  test_td12_td13_td14_gitignore_managed_block          PASSED   [.gitignore block + manifest exclusion B-1]
+  test_td1_td2_td3_essential_markdowns_only            PASSED   [no reports/refs; no MESSAGING/BOOTSTRAP; AGENTS+RULES+INSTALL present]
+  test_td21_td22_td23_safe_refresh_custom_skills      PASSED   [local mod preserved on refresh; backup created; stderr warns]
+  test_td27_td28_update_preserves_mam_state           PASSED   [asset_hashes.txt + version.txt survive update cycle B-5]
+  test_td6_td7_td8_mam_deploy_layout_and_removal     PASSED   [.mam_deploy/{remove,update}.sh present+exec; remove.sh runs from inside .mam_deploy]
+============================== 5 passed in 13.68s ==============================
+```
+
+### 2.3 Live install inspection (clean temp workspace, `MAM_REPO_URL=. MAM_SKIP_VENV=1`)
+```
+--- .gitignore (managed block) ---
+# >>> MAM managed block (managed by install.sh — do not edit) >>>
+/.venv/  /.mam/  /.mam_deploy/  /.mam.env  /.mam.env.*  !/.mam.env.example
+/.cache/multi-agent-mux-monitor/  /.mam-skill-backup.*/  CURRENT_JOB.md
+# <<< MAM managed block <<<
+
+--- .mam_deploy/ ---  remove.sh (0755)  update.sh (0755)
+--- root files ---   .gitignore  .mam.env  .mam.env.example  AGENTS.md  (no MESSAGING/BOOTSTRAP)
+--- exclusions verified ---  .agents/reports/ absent  .agents/references/ absent  MESSAGING.md absent  BOOTSTRAP.md absent
+--- .mam/install_state ---  gitignore_created=1
+--- .mam/version.txt ---  source=<local> commit=2ff8b2c... fetched_at=20260804T131420Z method=local
+--- manifest B-1 gate ---  .gitignore NOT in manifest (PASS)  .mam_deploy/remove.sh in manifest  .mam_deploy/update.sh in manifest
+```
+
+### 2.4 Pre-existing test status (out of scope)
+`tests/test_sanity.py` HANGS (timed out at 30s) — requires live `herdr`/tmux environment. **Pre-existing**, not modified by this changeset. No regression introduced.
+---
+
+## 3. Findings
+
+### 3.1 Blocking defects — NONE
+No syntax errors, no control-flow breaks, no manifest-corruption paths. All 4 requirement gates are satisfied and covered by passing tests.
+
+### 3.2 Non-blocking follow-ups (informational, do not block merge)
+
+**R-1 (Low) — Stray untracked `.tmp` file not covered by repo `.gitignore`**
+A runtime artifact `multi-agent-mux-delegate-job.13436_75009.tmp` exists untracked under `.agents/skills/multi-agent-mux-delegate-job/`. The install-time `find` skip (`*.tmp` at install.sh:188) and `install_mam.sh` rsync `--exclude='*.tmp'` (line 118) correctly prevent it from being *installed* into target workspaces, but the **source repo's own `.gitignore`** has no `*.tmp` rule, so it keeps reappearing as an untracked file across reviews (also flagged in jobs `9c44c6b2` and `54413a8a`). Recommend adding a top-level `*.tmp` ignore to the repo `.gitignore` or cleaning the artifact at source. **Does not affect installed workspaces.**
+
+**R-2 (Low) — `update.sh` legacy-restore ordering hazard on legacy-owned `.env`**
+In `update.sh` lines 207–209, when `MAM_LEGACY_ENV_OWNED=1` and `ENV_BACKUP_SRC=.env`, the restore does `mv -f "$ENV_BACKUP_TMP" ".mam.env"` — correct file migration. The pre-capture of `MAM_LEGACY_ENV_OWNED` + `export` (lines 86–90) is correctly inherited by the child `install.sh`, which reads it in `migrate_legacy_env()` (install.sh:476). **Edge case:** the child installer runs in step 4 *before* the parent restore in step 5. The child sees no `.env` (moved to `.env.update-tmp`) and no `.mam.env`, so it creates a fresh default `.mam.env`. The parent's restore then sees `.mam.env` already exists and falls to the `else` branch (`mv -f "$ENV_BACKUP_TMP" "$ENV_BACKUP_SRC"` = `.env`), leaving the user's real config at `.env` while a fresh default `.mam.env` shadows it. This only manifests when updating a workspace whose config is still legacy `.env` AND MAM-owned. Recommend either (a) restoring the env backup *before* invoking the child installer, or (b) having the child installer skip env creation when `MAM_LEGACY_ENV_OWNED=1` and a `.env.update-tmp`/`.mam.env.update-tmp` sentinel exists. Not exercised by the current test suite (T-D27/T-D28 use `.mam.env`, not legacy `.env`).
+
+**R-3 (Info) — `remove.sh` deletes `.mam_deploy/update.sh` unconditionally**
+`remove.sh:307` calls `delete_asset ".mam_deploy/update.sh"` outside the manifest-ownership loop used for `remove.sh`. In practice `update.sh` is always in the manifest (both installers register it), so this is fine, but it's a minor asymmetry: `remove.sh` self-deletion is guarded by manifest/`FORCE` while `update.sh` is deleted unconditionally. Harmless given current installers always register `update.sh`; a one-line comment would aid future maintainers.
+
+**R-4 (Info) — `install_mam.sh` does not write `install_state` / `asset_hashes.txt` / `version.txt`**
+`install_mam.sh` deploys skills via `rsync` but does not populate `.mam/install_state`, `.mam/asset_hashes.txt`, or `.mam/version.txt`. Consequently a subsequent `install.sh --no-refresh` would treat all files as `BOOTSTRAP_OVERWRITE` (no `db_sha`), and `remove.sh`'s `GI_CREATED` lookup would default to 0. The primary installer is `install.sh`; `install_mam.sh` is a secondary path. Not a regression (it never wrote these files before). Documenting the divergence would help.
+
+---
+
+## 4. Gate Checklist
+
+| # | Requirement | Status | Evidence |
+|---|-------------|--------|----------|
+| 1 | Latest updates (safe refresh) | ✅ PASS | 3-way hash reconciliation; `--no-refresh`; `remove.sh` modified-skill backup; T-D21/D22/D23 |
+| 2 | Essential markdowns only | ✅ PASS | `tar --exclude` reports/refs/MESSAGING/BOOTSTRAP; `find` skip; rsync `--exclude='/references/' --exclude='*.tmp'`; live install confirms absence; T-D1/D2/D3 |
+| 3 | Install remove.sh & update.sh into `.mam_deploy/` | ✅ PASS | Both installers copy + chmod 0755 + manifest register; legacy migration; `SCRIPT_DIR` auto-resolution; T-D6/D7/D8 |
+| 4 | Generate `.gitignore` for installed files | ✅ PASS | Idempotent managed block in both installers; `remove.sh` cleans block + removes if created; `.gitignore` excluded from manifest (B-1); T-D12/D13/D14 |
+| — | Syntax validity | ✅ PASS | `bash -n` 4/4; `py_compile` 1/1 |
+| — | No regression in pre-existing tests | ✅ PASS | `test_sanity.py` hangs are pre-existing (herdr/tmux env), not touched by this diff |
+
+---
+
+## 5. Verdict
+
+The changeset is well-structured, addresses all four requirements with idempotent and backward-compatible logic, and is backed by a passing 5-test suite covering the critical gates (essential-docs filtering, `.mam_deploy/` layout, `.gitignore` managed block + manifest exclusion, safe-refresh custom-skill preservation, and update-cycle state preservation). The 4 non-blocking follow-ups (R-1 through R-4) are low severity and do not impede merge. No blocking defects found.
+
+[VERDICT: PASS]
@@ -1,22 +1,28 @@
 #!/usr/bin/env bash
 # ==============================================================================
-# install.sh — Multi-Agent Mux (MAM) Orchestration Installer
-# ==============================================================================
-# Idempotent, robust installer to bootstrap MAM orchestration skills
-# and Python backplane dependencies on any local workspace.
+# install.sh — Multi-Agent Mux (MAM) Orchestration Installer (Rev.2)
 # ==============================================================================
 set -euo pipefail

 # --- Configuration & Defaults ---
 TARGET_DIR=""
-FORCE_REFRESH="${MAM_FORCE_REFRESH:-0}"
+REFRESH="${MAM_REFRESH:-1}"
+OVERWRITE_CUSTOM="${MAM_OVERWRITE_CUSTOM:-0}"
 VENV_NAME=".venv"
 MIN_PYTHON_VERSION="3.9"

 while [[ $# -gt 0 ]]; do
  case "$1" in
    -f|--force|--refresh-skills)
-      FORCE_REFRESH=1
+      REFRESH=1
+      shift
+      ;;
+    --no-refresh|--offline)
+      REFRESH=0
+      shift
+      ;;
+    --overwrite-custom)
+      OVERWRITE_CUSTOM=1
      shift
      ;;
    -h|--help)
@@ -24,7 +30,9 @@ while [[ $# -gt 0 ]]; do
 Usage: $0 [options] [target_dir]

 Options:
-  -f, --force, --refresh-skills  Force fetch and refresh framework skills under .agents/skills/
+  -f, --force, --refresh-skills  Fetch and refresh skills (now default)
+  --no-refresh, --offline        Skip fetching latest assets if assets exist
+  --overwrite-custom             Force overwrite user-modified skill files (backup still created)
  -h, --help                     Show this help message
 EOF
      exit 0
@@ -64,7 +72,6 @@ check_cmd() {
 check_cmd herdr
 check_cmd python3

-# Verify Python Version
 PYTHON_VERSION=$(python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')
 PYTHON_MAJOR="${MIN_PYTHON_VERSION%%.*}"
 PYTHON_MINOR="${MIN_PYTHON_VERSION##*.}"
@@ -75,10 +82,8 @@ else
  exit 1
 fi

-# Verify PyYAML (needed by system python3 for atomic state writes)
 if ! python3 -c "import yaml" &>/dev/null; then
-  echo "❌ Error: 'PyYAML' is not installed in the system python3. Please install it first" >&2
-  echo "   (e.g., 'pip3 install PyYAML' or 'sudo apt-get install python3-yaml')." >&2
+  echo "❌ Error: 'PyYAML' is not installed in system python3." >&2
  exit 1
 fi
 echo "✅ PyYAML (system dependency) detected."
@@ -90,8 +95,6 @@ cd "$TARGET_DIR"
 REPO_URL="${MAM_REPO_URL:-https://git.godopu.com/tmpl/multi-agent-mux.git}"
 ARCHIVE_URL="${MAM_ARCHIVE_URL:-https://git.godopu.com/tmpl/multi-agent-mux/archive/main.tar.gz}"

-# Helper to verify presence of all core runtime files.
-# Keying off a set of core files helps detect and recover from partial/interrupted installations.
 check_assets_present() {
  local dir="${1:-.}"
  local core_files=(
@@ -109,7 +112,6 @@ check_assets_present() {
  return 0
 }

-# Helper to classify framework-owned skill definitions vs user-owned project assets
 is_framework_owned() {
  case "$1" in
    .agents/skills/*) return 0 ;;
@@ -117,108 +119,242 @@ is_framework_owned() {
  esac
 }

-# Fetch the orchestration assets if missing or if skill refresh is requested.
-#
-# Safety model (FW-D1): we NEVER extract the repo archive directly into the
-# target. Running inside an existing project must not overwrite the target's
-# own files (README.md, FUTURE_WORKS.md, AGENTS.md, MULTI_AGENT_RULES.md) or litter
-# it with development docs. Instead we stage the download into a throwaway temp dir,
-# verify it, then copy runtime assets: framework skills (.agents/skills/*) are updated,
-# while user-owned documents use per-file no-clobber guards so pre-existing target files win.
-if [ "$FORCE_REFRESH" -eq 1 ] || ! check_assets_present "."; then
+# Fetch orchestration assets if REFRESH=1 or if core assets are missing.
+if [ "$REFRESH" -eq 1 ] || [ "${MAM_SKIP_VENV:-0}" -eq 1 ] || ! check_assets_present "."; then
  echo "📥 Staging orchestration assets from Gitea repository..."
  STAGE_DIR="$(mktemp -d)"
  trap 'rm -rf "$STAGE_DIR"' EXIT

-  if command -v git &>/dev/null; then
+  FETCH_METHOD="archive"
+  if [ -d "$REPO_URL" ]; then
+    echo "🌐 Copying local working tree into a staging area..."
+    cp -R "$REPO_URL/." "$STAGE_DIR/"
+    FETCH_METHOD="local"
+  elif command -v git &>/dev/null; then
    echo "🌐 Cloning repository (shallow) into a staging area..."
    git clone --depth 1 "$REPO_URL" "$STAGE_DIR"
+    FETCH_METHOD="git"
  elif command -v curl &>/dev/null; then
    echo "🌐 Downloading and extracting archive into a staging area..."
-    curl -fsSL "$ARCHIVE_URL" | tar -xz --strip-components=1 -C "$STAGE_DIR"
+    curl -fsSL "$ARCHIVE_URL" | tar -xz --strip-components=1 -C "$STAGE_DIR" \
+      --exclude='*/.agents/reports/*' --exclude='*/.agents/references/*' \
+      --exclude='*/MESSAGING.md' --exclude='*/BOOTSTRAP.md' --exclude='*/BOOTSTRAP.ko.md' 2>/dev/null || true
+    FETCH_METHOD="archive"
  else
    echo "❌ Error: neither 'git' nor 'curl' is available to fetch the skills." >&2
    exit 1
  fi

-  # Verify the staged tree before we trust and copy from it.
  if ! check_assets_present "$STAGE_DIR"; then
-    echo "❌ Error: fetched source is missing core runtime assets. Aborting (no files copied)." >&2
+    echo "❌ Error: fetched source is missing core runtime assets. Aborting." >&2
    exit 1
  fi

-  # Create metadata directory and initialize manifest before copying
  mkdir -p .mam
  MANIFEST_FILE=".mam/install_manifest.txt"
  touch "$MANIFEST_FILE"

-  # Copy runtime assets (.agents/) into the target workspace.
-  # Framework-owned skill files (.agents/skills/*) are updated/overwritten so that
-  # latest skill definitions and metadata frontmatter take effect.
-  # User-owned documents (.agents/MULTI_AGENT_RULES*.md, .agents/INSTALL.md, etc.) use
-  # explicit no-clobber guards so pre-existing user files are untouched and unmanifested.
+  # Migrate legacy root layout for remove.sh and update.sh into .mam_deploy/ if owned
+  mkdir -p .mam_deploy
+  for legacy_script in remove.sh update.sh; do
+    if [ -f "$legacy_script" ] && grep -Fqx "$legacy_script" "$MANIFEST_FILE" 2>/dev/null; then
+      mv -f "$legacy_script" ".mam_deploy/$legacy_script"
+      python3 -c '
+import sys
+path = sys.argv[1]
+old_s = sys.argv[2]
+new_s = sys.argv[3]
+with open(path, "r") as f:
+    lines = f.readlines()
+with open(path, "w") as f:
+    for line in lines:
+        if line.strip() == old_s:
+            f.write(new_s + "\n")
+        else:
+            f.write(line)
+' "$MANIFEST_FILE" "$legacy_script" ".mam_deploy/$legacy_script" 2>/dev/null || true
+    fi
+  done
+
+  # Safe refresh & fingerprint checking logic
+  TS=$(date -u +%Y%m%dT%H%M%SZ)
+  PRESERVED_COUNT=0
+  MODIFIED_FILES=()
+
  mkdir -p .agents
  ( cd "$STAGE_DIR/.agents" && find . -type f -print ) | while IFS= read -r rel; do
+    case "$rel" in
+      ./reports/*|./references/*) continue ;;
+      *.tmp|*.log|*.pyc|*/__pycache__/*) continue ;;
+    esac
+
    dest=".agents/${rel#./}"
    mkdir -p "$(dirname "$dest")"

    if is_framework_owned "$dest"; then
-      cp -f "$STAGE_DIR/.agents/$rel" "$dest" || { echo "❌ Error: Failed to copy $rel" >&2; exit 1; }
-      if ! grep -Fqx "$dest" "$MANIFEST_FILE" 2>/dev/null; then
-        echo "$dest" >> "$MANIFEST_FILE"
-      fi
+      # 3-way check using python3 inline
+      STAGING_FILE="$STAGE_DIR/.agents/$rel"
+      ACTION=$(python3 - "$dest" "$STAGING_FILE" ".mam/asset_hashes.txt" "$OVERWRITE_CUSTOM" <<'PY'
+import sys, hashlib, os
+
+target_path, staging_path, hash_db_path, force_overwrite = sys.argv[1], sys.argv[2], sys.argv[3], sys.argv[4] == "1"
+
+def file_sha(path):
+    if not os.path.exists(path):
+        return None
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        while chunk := f.read(65536):
+            h.update(chunk)
+    return h.hexdigest()
+
+target_sha = file_sha(target_path)
+staging_sha = file_sha(staging_path)
+
+if target_sha is None:
+    print("COPY_NEW")
+    sys.exit(0)
+
+if target_sha == staging_sha:
+    print("NO_OP")
+    sys.exit(0)
+
+db_sha = None
+if os.path.exists(hash_db_path):
+    with open(hash_db_path, "r") as f:
+        for line in f:
+            parts = line.strip().split(None, 1)
+            if len(parts) == 2 and parts[1] == target_path:
+                db_sha = parts[0]
+                break
+
+if db_sha is None:
+    print("BOOTSTRAP_OVERWRITE")
+elif target_sha == db_sha:
+    print("UPDATE_UNMODIFIED")
+else:
+    if force_overwrite:
+        print("FORCE_OVERWRITE_CUSTOM")
+    else:
+        print("PRESERVE_CUSTOM")
+PY
+)
+      case "$ACTION" in
+        COPY_NEW|UPDATE_UNMODIFIED|BOOTSTRAP_OVERWRITE|FORCE_OVERWRITE_CUSTOM)
+          if [ "$ACTION" = "BOOTSTRAP_OVERWRITE" ] || [ "$ACTION" = "FORCE_OVERWRITE_CUSTOM" ]; then
+            BACKUP_DIR=".mam/skill-backups/$TS/$(dirname "$dest")"
+            mkdir -p "$BACKUP_DIR"
+            cp "$dest" "$BACKUP_DIR/"
+          fi
+          cp -f "$STAGING_FILE" "$dest"
+          if ! grep -Fqx "$dest" "$MANIFEST_FILE" 2>/dev/null; then
+            echo "$dest" >> "$MANIFEST_FILE"
+          fi
+          ;;
+        PRESERVE_CUSTOM)
+          BACKUP_DIR=".mam/skill-backups/$TS/$(dirname "$dest")"
+          mkdir -p "$BACKUP_DIR"
+          cp "$dest" "$BACKUP_DIR/"
+          echo "PRESERVED:$dest"
+          ;;
+        NO_OP)
+          if ! grep -Fqx "$dest" "$MANIFEST_FILE" 2>/dev/null; then
+            echo "$dest" >> "$MANIFEST_FILE"
+          fi
+          ;;
+      esac
    elif [ ! -e "$dest" ]; then
-      cp "$STAGE_DIR/.agents/$rel" "$dest" || { echo "❌ Error: Failed to copy $rel" >&2; exit 1; }
+      cp "$STAGE_DIR/.agents/$rel" "$dest"
      if ! grep -Fqx "$dest" "$MANIFEST_FILE" 2>/dev/null; then
        echo "$dest" >> "$MANIFEST_FILE"
      fi
    fi
+  done | while IFS= read -r line; do
+    if [[ "$line" == PRESERVED:* ]]; then
+      echo "ℹ️  Local modification detected: ${line#PRESERVED:}" >&2
+    fi
  done

-  # Copy non-dev documents if they don't already exist.
-  # We skip dev-specific docs like README.md, DONE.md, and FUTURE_WORKS.md.
-  for doc in MESSAGING.md BOOTSTRAP.md BOOTSTRAP.ko.md AGENTS.md; do
+  # Re-build asset_hashes.txt for all framework owned files
+  python3 - .mam/asset_hashes.txt <<'PY'
+import os, hashlib, sys
+
+hash_db_path = sys.argv[1]
+hashes = []
+
+for root, _, files in os.walk(".agents/skills"):
+    for file in files:
+        path = os.path.join(root, file)
+        h = hashlib.sha256()
+        with open(path, "rb") as f:
+            while chunk := f.read(65536):
+                h.update(chunk)
+        hashes.append(f"{h.hexdigest()}  {path}\n")
+
+with open(hash_db_path, "w") as f:
+    f.writelines(sorted(hashes))
+PY
+
+  # Copy root docs (R-2 essential set)
+  ROOT_DOCS="AGENTS.md"
+  if [ "${MAM_INSTALL_DOCS:-minimal}" = "full" ]; then
+    ROOT_DOCS="AGENTS.md MESSAGING.md BOOTSTRAP.md BOOTSTRAP.ko.md"
+  fi
+  for doc in $ROOT_DOCS; do
    if [ -f "$STAGE_DIR/$doc" ] && [ ! -e "$doc" ]; then
-      cp "$STAGE_DIR/$doc" . || { echo "❌ Error: Failed to copy $doc" >&2; exit 1; }
+      cp "$STAGE_DIR/$doc" .
      echo "$doc" >> "$MANIFEST_FILE"
    fi
  done

-  if [ -f "$STAGE_DIR/deploy/remove.sh" ] && [ ! -e "remove.sh" ]; then
-    cp "$STAGE_DIR/deploy/remove.sh" remove.sh || { echo "❌ Error: Failed to copy remove.sh" >&2; exit 1; }
-    chmod +x remove.sh
-    echo "remove.sh" >> "$MANIFEST_FILE"
+  # Install remove.sh and update.sh into .mam_deploy/
+  mkdir -p .mam_deploy
+  if [ -f "$STAGE_DIR/deploy/remove.sh" ]; then
+    cp "$STAGE_DIR/deploy/remove.sh" .mam_deploy/remove.sh
+    chmod 0755 .mam_deploy/remove.sh
+    if ! grep -Fqx ".mam_deploy/remove.sh" "$MANIFEST_FILE" 2>/dev/null; then
+      echo ".mam_deploy/remove.sh" >> "$MANIFEST_FILE"
+    fi
  fi

-  if [ -f "$STAGE_DIR/deploy/update.sh" ] && [ ! -e "update.sh" ]; then
-    cp "$STAGE_DIR/deploy/update.sh" update.sh || { echo "❌ Error: Failed to copy update.sh" >&2; exit 1; }
-    chmod +x update.sh
-    echo "update.sh" >> "$MANIFEST_FILE"
+  if [ -f "$STAGE_DIR/deploy/update.sh" ]; then
+    cp "$STAGE_DIR/deploy/update.sh" .mam_deploy/update.sh
+    chmod 0755 .mam_deploy/update.sh
+    if ! grep -Fqx ".mam_deploy/update.sh" "$MANIFEST_FILE" 2>/dev/null; then
+      echo ".mam_deploy/update.sh" >> "$MANIFEST_FILE"
+    fi
  fi

  if [ -f "$STAGE_DIR/.mam.env.example" ] && [ ! -e ".mam.env.example" ]; then
-    cp "$STAGE_DIR/.mam.env.example" . || { echo "❌ Error: Failed to copy .mam.env.example" >&2; exit 1; }
+    cp "$STAGE_DIR/.mam.env.example" .
    echo ".mam.env.example" >> "$MANIFEST_FILE"
  fi

-  # Ship the user manual into the target's .agents/ (consistent with install_mam.sh)
-  if [ -f "$STAGE_DIR/deploy/INSTALL.md" ]; then
+  if [ -f "$STAGE_DIR/deploy/INSTALL.md" ] && [ ! -e ".agents/INSTALL.md" ]; then
    mkdir -p .agents
-    if [ ! -e ".agents/INSTALL.md" ]; then
-      cp "$STAGE_DIR/deploy/INSTALL.md" .agents/INSTALL.md || { echo "❌ Error: Failed to copy INSTALL.md" >&2; exit 1; }
-      echo ".agents/INSTALL.md" >> "$MANIFEST_FILE"
-    fi
+    cp "$STAGE_DIR/deploy/INSTALL.md" .agents/INSTALL.md
+    echo ".agents/INSTALL.md" >> "$MANIFEST_FILE"
  fi

+  # Record version stamp
+  STAGE_COMMIT="unknown"
+  if [ -d "$STAGE_DIR/.git" ]; then
+    STAGE_COMMIT=$(git -C "$STAGE_DIR" rev-parse HEAD 2>/dev/null || echo "unknown")
+  fi
+  cat <<EOF > .mam/version.txt
+source=$REPO_URL
+commit=$STAGE_COMMIT
+fetched_at=$TS
+method=$FETCH_METHOD
+EOF
+
  rm -rf "$STAGE_DIR"
  trap - EXIT
  echo "✅ Skills staged into workspace (user documents and custom configs preserved)."
 fi

-# Sanity check: verify all core files, not just a single one — an empty or
-# incomplete layout would yield a silently broken install.
 if ! check_assets_present "."; then
-  echo "❌ Error: Core runtime assets missing after setup. Target layout might be invalid." >&2
+  echo "❌ Error: Core runtime assets missing after setup." >&2
  exit 1
 fi
 echo "✅ Orchestration skills present."
@@ -226,20 +362,80 @@ echo "✅ Orchestration skills present."
 echo "📂 Ensuring metadata directory structure (.mam/)..."
 mkdir -p .mam/jobs .mam/delegate_job_logs

-# File permission lockdown on database directory (if owned by the current user to prevent multi-user system issues)
 if [ -O .mam ]; then
  chmod 0700 .mam
 fi

+# R-4: Manage .gitignore block (never put .gitignore in manifest)
+MAM_GI_START="# >>> MAM managed block (managed by install.sh — do not edit) >>>"
+MAM_GI_END="# <<< MAM managed block <<<"
+
+if [ "${MAM_SKIP_GITIGNORE:-0}" != "1" ]; then
+  GI_CREATED=0
+  [ -e .gitignore ] || { touch .gitignore; GI_CREATED=1; }
+  
+  if ! grep -q '^gitignore_created=' .mam/install_state 2>/dev/null; then
+    echo "gitignore_created=$GI_CREATED" >> .mam/install_state
+  fi
+
+  python3 - .gitignore "$MAM_GI_START" "$MAM_GI_END" <<'PY'
+import sys, os
+
+gi_path, start_marker, end_marker = sys.argv[1], sys.argv[2], sys.argv[3]
+
+block_lines = [
+    start_marker + "\n",
+    "/.venv/\n",
+    "/.mam/\n",
+    "/.mam_deploy/\n",
+    "/.mam.env\n",
+    "/.mam.env.*\n",
+    "!/.mam.env.example\n",
+    "/.cache/multi-agent-mux-monitor/\n",
+    "/.mam-skill-backup.*/\n",
+    "CURRENT_JOB.md\n",
+    end_marker + "\n"
+]
+
+lines = []
+if os.path.exists(gi_path):
+    with open(gi_path, "r") as f:
+        lines = f.readlines()
+
+new_lines = []
+in_block = False
+block_inserted = False
+
+for line in lines:
+    if line.strip() == start_marker:
+        in_block = True
+        if not block_inserted:
+            new_lines.extend(block_lines)
+            block_inserted = True
+        continue
+    if line.strip() == end_marker:
+        in_block = False
+        continue
+    if not in_block:
+        new_lines.append(line)
+
+if not block_inserted:
+    if new_lines and not new_lines[-1].endswith("\n"):
+        new_lines[-1] += "\n"
+    new_lines.extend(block_lines)
+
+with open(gi_path, "w") as f:
+    f.writelines(new_lines)
+PY
+fi
+
 # --- 3. Check Network File System (NFS) Warnings ---
 echo "💾 Detecting file system mount type..."
 if command -v df &>/dev/null && command -v mount &>/dev/null; then
  MOUNTPOINT="$(df --output=target . 2>/dev/null | tail -1 || echo "")"
  if [ -n "$MOUNTPOINT" ]; then
    if mount | grep -q "$MOUNTPOINT.*nfs\|$MOUNTPOINT.*cifs\|$MOUNTPOINT.*fuse.sshfs"; then
-      echo "⚠️  WARNING: Target directory is on a network filesystem (NFS/CIFS/SSHFS)."
-      echo "   SQLite WAL journaling and file locks are UNRELIABLE on network storage."
-      echo "   The sqlite3 registry will fall back to 'DELETE' journaling instead of WAL."
+      echo "⚠️  WARNING: Target directory is on a network filesystem."
    else
      echo "✅ File system supports WAL (Local storage detected)."
    fi
@@ -247,38 +443,32 @@ if command -v df &>/dev/null && command -v mount &>/dev/null; then
 fi

 # --- 4. Python Virtual Environment Setup ---
-echo "🐍 Bootstrapping Python virtual environment (.venv)..."
-if [ ! -d "$VENV_NAME" ]; then
-  python3 -m venv "$VENV_NAME"
-  echo "✅ Virtual environment created."
-else
-  echo "ℹ️  Virtual environment (.venv) already exists. Skipping creation."
-fi
+if [ "${MAM_SKIP_VENV:-0}" != "1" ]; then
+  echo "🐍 Bootstrapping Python virtual environment (.venv)..."
+  if [ ! -d "$VENV_NAME" ]; then
+    python3 -m venv "$VENV_NAME"
+    echo "✅ Virtual environment created."
+  else
+    echo "ℹ️  Virtual environment (.venv) already exists. Skipping creation."
+  fi

-# Activate virtual environment
-# shellcheck disable=SC1091
-source "$VENV_NAME"/bin/activate
+  source "$VENV_NAME"/bin/activate
+  pip install --upgrade pip

-# Upgrade pip
-pip install --upgrade pip
-
-# Install requirements
-REQ_FILE=".agents/skills/multi-agent-mux-delegate-job/requirements.txt"
-if [ -f "$REQ_FILE" ]; then
-  echo "📦 Installing backplane dependencies from $REQ_FILE..."
-  pip install -r "$REQ_FILE"
-  echo "✅ Dependencies installed successfully."
-else
-  echo "⚠️  WARNING: Could not find requirements file: $REQ_FILE"
-  echo "   Installing default packages (paho-mqtt, pyyaml) manually..."
-  pip install "paho-mqtt>=2.0.0" pyyaml
+  REQ_FILE=".agents/skills/multi-agent-mux-delegate-job/requirements.txt"
+  if [ -f "$REQ_FILE" ]; then
+    echo "📦 Installing backplane dependencies from $REQ_FILE..."
+    pip install -r "$REQ_FILE"
+    echo "✅ Dependencies installed successfully."
+  else
+    pip install "paho-mqtt>=2.0.0" pyyaml
+  fi
 fi

 # --- 5. Generate Environment Template ---
 ENV_FILE=".mam.env"
 ENV_EXAMPLE=".mam.env.example"

-# M-2: Evidence-based legacy env migration helper
 migrate_legacy_env() {
  local manifest=".mam/install_manifest.txt"
  [ -f ".mam.env" ] && return 0
@@ -314,7 +504,6 @@ with open(path, "w") as f:

 migrate_legacy_env

-# M-1: Shadowing prevention guard — only create new default config if no legacy env or update tmp exists
 if [ ! -f "$ENV_FILE" ] && [ ! -f ".env" ] && [ ! -f ".env.update-tmp" ]; then
  if [ -f "$ENV_EXAMPLE" ]; then
    echo "📝 Creating configuration from $ENV_EXAMPLE..."
@@ -323,8 +512,7 @@ if [ ! -f "$ENV_FILE" ] && [ ! -f ".env" ] && [ ! -f ".env.update-tmp" ]; then
    echo "📝 Creating default $ENV_FILE..."
    touch "$ENV_FILE"
  fi
-  
-  # Always append the active defaults to ensure they are set and not commented out
+
  cat <<EOF >> "$ENV_FILE"

 # === Installer-applied active defaults ===
@@ -336,8 +524,7 @@ HERDR_SERVER_NAME=default
 EOF
  chmod 0600 "$ENV_FILE"
  echo "✅ Config file .mam.env initialized with chmod 0600."
-  
-  # Record the newly created .mam.env in the manifest
+
  mkdir -p .mam
  touch .mam/install_manifest.txt
  echo "$ENV_FILE" >> .mam/install_manifest.txt
@@ -114,15 +114,27 @@ log_info "Deploying orchestration rules & skills (.agents/)..."
 mkdir -p "$TARGET_DIR/.agents"
 
 # Sync rules and skills, avoiding copying temporary or system files
-# Exclude git histories, reports, logs or internal runtime cache if any
-rsync -a --exclude='.git/' --exclude='/reports/' --exclude='*.log' --exclude='__pycache__/' --exclude='*.pyc' "$SRC_DIR/.agents/" "$TARGET_DIR/.agents/"
+# Exclude git histories, reports, references, logs or internal runtime cache
+rsync -a --exclude='.git/' --exclude='/reports/' --exclude='/references/' --exclude='*.log' --exclude='*.tmp' --exclude='__pycache__/' --exclude='*.pyc' "$SRC_DIR/.agents/" "$TARGET_DIR/.agents/"
 log_ok "Deployed Rules and Skills under target's .agents/"
- 
+
 # Copy config templates and generate scripts (M-2)
 if [ -f "$SRC_DIR/.mam.env.example" ]; then
  cp "$SRC_DIR/.mam.env.example" "$TARGET_DIR/.mam.env.example"
  log_ok "Copied .mam.env.example configuration template"
 fi
+
+# Deploy remove.sh and update.sh into .mam_deploy/ (R-3)
+mkdir -p "$TARGET_DIR/.mam_deploy"
+if [ -f "$SRC_DIR/deploy/remove.sh" ]; then
+  cp "$SRC_DIR/deploy/remove.sh" "$TARGET_DIR/.mam_deploy/remove.sh"
+  chmod 0755 "$TARGET_DIR/.mam_deploy/remove.sh"
+fi
+if [ -f "$SRC_DIR/deploy/update.sh" ]; then
+  cp "$SRC_DIR/deploy/update.sh" "$TARGET_DIR/.mam_deploy/update.sh"
+  chmod 0755 "$TARGET_DIR/.mam_deploy/update.sh"
+fi
+
 if [ -f "$SRC_DIR/deploy/generate-env.sh" ]; then
  mkdir -p "$TARGET_DIR/scripts"
  cp "$SRC_DIR/deploy/generate-env.sh" "$TARGET_DIR/scripts/generate-env.sh"
@@ -160,32 +172,62 @@ else
  log_ok "Guidelines AGENTS.md copied to project root."
 fi

-# 4. Gitignore adjustments
+# 4. Gitignore adjustments (R-4: managed block)
 log_info "Registering runtime isolation blocks in .gitignore..."
 GITIGNORE="$TARGET_DIR/.gitignore"
-MAM_PATTERN="/.mam/"
-VENV_PATTERN="/.venv/"
- 
-if [ -f "$GITIGNORE" ]; then
-  # Register .mam/ if absent
-  if grep -Eq '^/?\.mam/?$' "$GITIGNORE"; then
-    log_ok ".mam/ already registered in target's .gitignore."
-  else
-    echo -e "\n# Multi-Agent Mux (MAM) runtime databases and isolation cache\n$MAM_PATTERN" >> "$GITIGNORE"
-    log_ok "Appended /.mam/ registration to .gitignore."
-  fi
- 
-  # Register .venv/ if absent
-  if grep -Eq '^/?\.venv/?$' "$GITIGNORE"; then
-    log_ok ".venv/ already registered in target's .gitignore."
-  else
-    echo -e "\n# Python virtual environment\n$VENV_PATTERN" >> "$GITIGNORE"
-    log_ok "Appended /.venv/ registration to .gitignore."
-  fi
-else
-  echo -e "# Multi-Agent Mux (MAM) runtime databases and isolation cache\n$MAM_PATTERN\n\n# Python virtual environment\n$VENV_PATTERN" > "$GITIGNORE"
-  log_ok "Created .gitignore with MAM and .venv exclusions."
-fi
+MAM_GI_START="# >>> MAM managed block (managed by install.sh — do not edit) >>>"
+MAM_GI_END="# <<< MAM managed block <<<"
+
+python3 - "$GITIGNORE" "$MAM_GI_START" "$MAM_GI_END" <<'PY'
+import sys, os
+
+gi_path, start_marker, end_marker = sys.argv[1], sys.argv[2], sys.argv[3]
+
+block_lines = [
+    start_marker + "\n",
+    "/.venv/\n",
+    "/.mam/\n",
+    "/.mam_deploy/\n",
+    "/.mam.env\n",
+    "/.mam.env.*\n",
+    "!/.mam.env.example\n",
+    "/.cache/multi-agent-mux-monitor/\n",
+    "/.mam-skill-backup.*/\n",
+    "CURRENT_JOB.md\n",
+    end_marker + "\n"
+]
+
+lines = []
+if os.path.exists(gi_path):
+    with open(gi_path, "r") as f:
+        lines = f.readlines()
+
+new_lines = []
+in_block = False
+block_inserted = False
+
+for line in lines:
+    if line.strip() == start_marker:
+        in_block = True
+        if not block_inserted:
+            new_lines.extend(block_lines)
+            block_inserted = True
+        continue
+    if line.strip() == end_marker:
+        in_block = False
+        continue
+    if not in_block:
+        new_lines.append(line)
+
+if not block_inserted:
+    if new_lines and not new_lines[-1].endswith("\n"):
+        new_lines[-1] += "\n"
+    new_lines.extend(block_lines)
+
+with open(gi_path, "w") as f:
+    f.writelines(new_lines)
+PY
+log_ok "Registered MAM managed block in .gitignore."

 # 5. Python Virtual Environment Setup (F-1)
 log_info "Bootstrapping Python virtual environment (.venv) in target..."
@@ -11,6 +11,7 @@ set -euo pipefail
 TARGET_DIR=""
 FORCE=0
 PURGE_ENV=0
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

 # Parse arguments
 while [[ $# -gt 0 ]]; do
@@ -31,7 +32,15 @@ while [[ $# -gt 0 ]]; do
 done

 if [ -z "$TARGET_DIR" ]; then
-  TARGET_DIR="$(pwd)"
+  if [ "$(basename "$SCRIPT_DIR")" = ".mam_deploy" ]; then
+    TARGET_DIR="$(dirname "$SCRIPT_DIR")"
+  else
+    TARGET_DIR="$(pwd)"
+  fi
+else
+  if [ "$(basename "$TARGET_DIR")" = ".mam_deploy" ]; then
+    TARGET_DIR="$(dirname "$TARGET_DIR")"
+  fi
 fi

 echo "===================================================================="
@@ -46,6 +55,11 @@ fi

 cd "$TARGET_DIR"

+GI_CREATED=0
+if [ -f ".mam/install_state" ]; then
+  GI_CREATED=$(grep '^gitignore_created=' .mam/install_state 2>/dev/null | cut -d= -f2 || echo 0)
+fi
+
 # 1. Non-interactive input safety guard (set -e read crash prevention)
 if [ ! -t 0 ] && [ $FORCE -eq 0 ]; then
  echo "❌ Error: Non-interactive terminal detected. Please run with -y/--yes/--force." >&2
@@ -66,7 +80,6 @@ if [ -f "$MANIFEST_FILE" ]; then
    fi
  done < "$MANIFEST_FILE"
 else
-  # Fallback to the core MAM directories to check if any exist
  fallback_assets=(
    ".agents/skills/lib.sh"
    ".agents/skills/multi-agent-mux-create"
@@ -77,6 +90,7 @@ else
    ".agents/skills/multi-agent-mux-stop"
    ".venv"
    ".mam"
+    ".mam_deploy"
  )
  for asset in "${fallback_assets[@]}"; do
    if [ -e "$asset" ] || [ -h "$asset" ]; then
@@ -95,7 +109,6 @@ fi
 if [ $FORCE -eq 0 ]; then
  echo "⚠️  WARNING: This will permanently remove the MAM orchestration skills, "
  echo "   virtual environment (.venv), local metadata (.mam), and docs."
-  echo "   (Your own custom files inside .agents/ will NOT be touched)."
  
  if ! read -p "❓ Are you sure you want to proceed? [y/N]: " -r response; then
    response="n"
@@ -114,39 +127,110 @@ delete_asset() {
  fi
 }

+# Check for modified skills before deleting
+TS=$(date -u +%Y%m%dT%H%M%SZ)
+python3 - ".mam/asset_hashes.txt" "$TS" <<'PY' 2>/dev/null || true
+import sys, os, hashlib, shutil
+
+hash_db_path = sys.argv[1]
+ts = sys.argv[2]
+
+if not os.path.exists(hash_db_path):
+    sys.exit(0)
+
+modified = []
+with open(hash_db_path, "r") as f:
+    for line in f:
+        parts = line.strip().split(None, 1)
+        if len(parts) == 2:
+            expected_hash, path = parts[0], parts[1]
+            if os.path.exists(path):
+                h = hashlib.sha256()
+                with open(path, "rb") as pf:
+                    while chunk := pf.read(65536):
+                        h.update(chunk)
+                if h.hexdigest() != expected_hash:
+                    modified.append(path)
+
+if modified:
+    backup_dir = f".mam-skill-backup.{ts}"
+    os.makedirs(backup_dir, exist_ok=True)
+    for p in modified:
+        dest = os.path.join(backup_dir, p)
+        os.makedirs(os.path.dirname(dest), exist_ok=True)
+        shutil.copy2(p, dest)
+    print(f"💾 Preserved {len(modified)} modified skill file(s) under {backup_dir}")
+PY
+
 # 2. Uninstall files using the manifest if present
 if [ ${#manifest_files[@]} -gt 0 ]; then
  echo "📜 Manifest found. Reversing installer-created files..."
  for f in ${manifest_files[@]+"${manifest_files[@]}"}; do
-    # Skip .env, .mam.env, and remove.sh for now, they are handled separately
-    if [ "$f" = ".env" ] || [ "$f" = ".mam.env" ] || [ "$f" = "remove.sh" ]; then
+    if [ "$f" = ".env" ] || [ "$f" = ".mam.env" ] || [ "$f" = "remove.sh" ] || [ "$f" = ".mam_deploy/remove.sh" ]; then
      continue
    fi
    delete_asset "$f"
  done
-  else
-    # Fallback: Delete MAM skills manually (only if manifest is missing)
-    echo "⚠️  No manifest found. Deleting standard MAM skills..."
-    delete_asset ".agents/skills/lib.sh"
-    delete_asset ".agents/skills/multi-agent-mux-create"
-    delete_asset ".agents/skills/multi-agent-mux-delegate-job"
-    delete_asset ".agents/skills/multi-agent-mux-monitor"
-    delete_asset ".agents/skills/multi-agent-mux-resume"
-    delete_asset ".agents/skills/multi-agent-mux-status"
-    delete_asset ".agents/skills/multi-agent-mux-stop"
-  fi
+else
+  echo "⚠️  No manifest found. Deleting standard MAM skills..."
+  delete_asset ".agents/skills/lib.sh"
+  delete_asset ".agents/skills/multi-agent-mux-create"
+  delete_asset ".agents/skills/multi-agent-mux-delegate-job"
+  delete_asset ".agents/skills/multi-agent-mux-monitor"
+  delete_asset ".agents/skills/multi-agent-mux-resume"
+  delete_asset ".agents/skills/multi-agent-mux-status"
+  delete_asset ".agents/skills/multi-agent-mux-stop"
+fi

-# 3. Clean up empty parent directories under .agents recursively to avoid littering
 if [ -d ".agents" ]; then
  find .agents -depth -type d -exec rmdir {} + 2>/dev/null || true
 fi

-# 4. Remove virtual environment, monitor cache, and metadata database
+# Clean up .gitignore managed block (C8)
+MAM_GI_START="# >>> MAM managed block (managed by install.sh — do not edit) >>>"
+MAM_GI_END="# <<< MAM managed block <<<"
+
+if [ -f .gitignore ]; then
+  python3 - .gitignore "$MAM_GI_START" "$MAM_GI_END" "$GI_CREATED" <<'PY'
+import sys, os
+
+gi_path, start_marker, end_marker, gi_created = sys.argv[1], sys.argv[2], sys.argv[3], sys.argv[4] == "1"
+
+if not os.path.exists(gi_path):
+    sys.exit(0)
+
+with open(gi_path, "r") as f:
+    lines = f.readlines()
+
+new_lines = []
+in_block = False
+block_found = False
+
+for line in lines:
+    if line.strip() == start_marker:
+        in_block = True
+        block_found = True
+        continue
+    if line.strip() == end_marker:
+        in_block = False
+        continue
+    if not in_block:
+        new_lines.append(line)
+
+if block_found:
+    content = "".join(new_lines).strip()
+    if gi_created and not content:
+        os.remove(gi_path)
+    else:
+        with open(gi_path, "w") as f:
+            f.writelines(new_lines)
+PY
+fi
+
 delete_asset ".venv"
 delete_asset ".cache/multi-agent-mux-monitor"
-delete_asset ".mam"  # Deletes manifest file too
+delete_asset ".mam"

-# 5. Clean up .env and .mam.env files (Only if created by installer, or forced with --purge-env)
 for env_name in ".mam.env" ".env"; do
  [ -f "$env_name" ] || continue
  
@@ -197,7 +281,6 @@ for env_name in ".mam.env" ".env"; do
        fi
        mv "$env_name" "$slot"
        echo "💾 Backed up $env_name -> $slot"
-        echo "   To remove the configuration entirely, re-run with --purge-env."
      fi
    else
      echo "ℹ️  Preserving user-owned $env_name configuration."
@@ -205,21 +288,24 @@ for env_name in ".mam.env" ".env"; do
  fi
 done

-# 6. Remove uninstaller file itself (if we are in the target root)
-# Simple check: only delete remove.sh if it is recorded in the manifest
-remove_in_manifest=0
-for f in ${manifest_files[@]+"${manifest_files[@]}"}; do
-  if [ "$f" = "remove.sh" ]; then
-    remove_in_manifest=1
-    break
+# Remove uninstaller file(s)
+for self in ".mam_deploy/remove.sh" "remove.sh"; do
+  [ -f "$self" ] || continue
+  in_manifest=0
+  for f in ${manifest_files[@]+"${manifest_files[@]}"}; do
+    if [ "$f" = "$self" ]; then
+      in_manifest=1
+      break
+    fi
+  done
+  if [ $in_manifest -eq 1 ] || [ $FORCE -eq 1 ]; then
+    echo "🗑️  Removing uninstaller: $self"
+    rm -f "$self"
  fi
 done

-if [ -f "remove.sh" ] && [ $remove_in_manifest -eq 1 ]; then
-  echo "🗑️  Removing uninstaller: remove.sh"
-  # Self-delete is the final action
-  rm -f "remove.sh"
-fi
+delete_asset ".mam_deploy/update.sh"
+rmdir .mam_deploy 2>/dev/null || true

 echo "===================================================================="
 echo "🎉 Uninstallation complete!"
@@ -9,6 +9,7 @@ set -euo pipefail

 TARGET_DIR=""
 FORCE=0
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

 # Parse arguments
 while [[ $# -gt 0 ]]; do
@@ -25,8 +26,15 @@ while [[ $# -gt 0 ]]; do
 done

 if [ -z "$TARGET_DIR" ]; then
-  TARGET_DIR="$(pwd)"
+  if [ "$(basename "$SCRIPT_DIR")" = ".mam_deploy" ]; then
+    TARGET_DIR="$(dirname "$SCRIPT_DIR")"
+  else
+    TARGET_DIR="$(pwd)"
+  fi
 else
+  if [ "$(basename "$TARGET_DIR")" = ".mam_deploy" ]; then
+    TARGET_DIR="$(dirname "$TARGET_DIR")"
+  fi
  if [ ! -d "$TARGET_DIR" ]; then
    echo "❌ Error: Target directory '$TARGET_DIR' does not exist." >&2
    exit 1
@@ -41,8 +49,16 @@ echo "===================================================================="

 cd "$TARGET_DIR"

-# 1. Verification of existing install
-if [ ! -f "remove.sh" ]; then
+# 1. Verification of existing install (B-2: dual resolution)
+REMOVER=""
+for cand in ".mam_deploy/remove.sh" "remove.sh"; do
+  if [ -f "$cand" ]; then
+    REMOVER="$cand"
+    break
+  fi
+done
+
+if [ -z "$REMOVER" ]; then
  echo "❌ Error: No MAM installation (remove.sh) found in '$TARGET_DIR'." >&2
  echo "   Please run install.sh first to set up the workspace." >&2
  exit 1
@@ -117,6 +133,16 @@ if [ -d ".mam" ]; then
  if [ -f ".mam/install_manifest.txt" ]; then
    cp -f .mam/install_manifest.txt .mam.update-tmp/
  fi
+  # C12: Copy MAM state files across update cycle
+  for st in install_state asset_hashes.txt version.txt; do
+    if [ -f ".mam/$st" ]; then
+      cp -f ".mam/$st" .mam.update-tmp/
+    fi
+  done
+  if [ -d ".mam/skill-backups" ]; then
+    mkdir -p .mam.update-tmp/skill-backups
+    cp -rf .mam/skill-backups/* .mam.update-tmp/skill-backups/ 2>/dev/null || true
+  fi
 fi

 # Define trap to restore backup files on failure
@@ -139,6 +165,15 @@ restore_on_failure() {
    if [ -f ".mam.update-tmp/install_manifest.txt" ]; then
      cp -f .mam.update-tmp/install_manifest.txt .mam/ 2>/dev/null || true
    fi
+    for st in install_state asset_hashes.txt version.txt; do
+      if [ -f ".mam.update-tmp/$st" ]; then
+        cp -f ".mam.update-tmp/$st" .mam/ 2>/dev/null || true
+      fi
+    done
+    if [ -d ".mam.update-tmp/skill-backups" ]; then
+      mkdir -p .mam/skill-backups
+      cp -rf .mam.update-tmp/skill-backups/* .mam/skill-backups/ 2>/dev/null || true
+    fi
    rm -rf .mam.update-tmp 2>/dev/null || true
  fi
 }
@@ -148,7 +183,7 @@ trap restore_on_failure EXIT
 echo "🗑️  Removing existing installation..."
 # remove.sh will run in manifest mode because .mam/install_manifest.txt is still present.
 # It will delete .agents/, documents, scripts, .venv, and .mam folder.
-bash remove.sh --force
+bash "$REMOVER" --force "$TARGET_DIR"

 # 4. Fetch and run the latest installer from Gitea
 echo "📥 Fetching and running the latest installer..."
@@ -194,6 +229,15 @@ if [ $HAS_MAM -eq 1 ]; then
      mkdir -p .mam/delegate_job_logs
      cp -rf .mam.update-tmp/delegate_job_logs/* .mam/delegate_job_logs/
    fi
+    for st in install_state asset_hashes.txt version.txt; do
+      if [ -f ".mam.update-tmp/$st" ]; then
+        cp -f ".mam.update-tmp/$st" .mam/
+      fi
+    done
+    if [ -d ".mam.update-tmp/skill-backups" ]; then
+      mkdir -p .mam/skill-backups
+      cp -rf .mam.update-tmp/skill-backups/* .mam/skill-backups/ 2>/dev/null || true
+    fi
    rm -rf ".mam.update-tmp"
  fi
 fi
@@ -0,0 +1,148 @@
+# ==============================================================================
+# test_deploy_layout.py — Deploy Script Layout, Refresh & Gitignore Test Suite
+# ==============================================================================
+import os
+import shutil
+import subprocess
+import tempfile
+import unittest
+
+class TestDeployLayout(unittest.TestCase):
+    def setUp(self):
+        self.repo_root = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+        self.temp_dir = tempfile.mkdtemp(prefix="mam_deploy_layout_test_")
+        self.test_dir = os.path.join(self.temp_dir, "workspace")
+        os.makedirs(self.test_dir, exist_ok=True)
+        self.env = os.environ.copy()
+        self.env["MAM_REPO_URL"] = self.repo_root
+        self.env["MAM_SKIP_VENV"] = "1"
+
+    def tearDown(self):
+        shutil.rmtree(self.temp_dir, ignore_errors=True)
+
+    def test_td1_td2_td3_essential_markdowns_only(self):
+        """T-D1~D3: Verify essential markdowns are shipped and internal reports/references are excluded."""
+        res = subprocess.run(
+            ["bash", os.path.join(self.repo_root, "deploy/install.sh"), self.test_dir],
+            env=self.env,
+            capture_output=True,
+            text=True
+        )
+        self.assertEqual(res.returncode, 0, f"install.sh failed: {res.stderr}")
+
+        # T-D1: No internal reports in .agents/reports
+        reports_dir = os.path.join(self.test_dir, ".agents", "reports")
+        if os.path.exists(reports_dir):
+            reports_files = [f for root, _, files in os.walk(reports_dir) for f in files if f.endswith(".md")]
+            self.assertEqual(len(reports_files), 0, f"Internal reports found: {reports_files}")
+
+        # T-D2: Non-essential root docs omitted by default
+        self.assertFalse(os.path.exists(os.path.join(self.test_dir, "MESSAGING.md")))
+        self.assertFalse(os.path.exists(os.path.join(self.test_dir, "BOOTSTRAP.md")))
+
+        # T-D3: Core essential docs present (B-3 gate)
+        self.assertTrue(os.path.exists(os.path.join(self.test_dir, "AGENTS.md")))
+        self.assertTrue(os.path.exists(os.path.join(self.test_dir, ".agents", "MULTI_AGENT_RULES.md")))
+        self.assertTrue(os.path.exists(os.path.join(self.test_dir, ".agents", "INSTALL.md")))
+        self.assertTrue(os.path.exists(os.path.join(self.test_dir, ".agents", "skills", "lib.sh")))
+
+    def test_td6_td7_td8_mam_deploy_layout_and_removal(self):
+        """T-D6~D8: Verify remove.sh/update.sh installed in .mam_deploy and work properly."""
+        subprocess.run(
+            ["bash", os.path.join(self.repo_root, "deploy/install.sh"), self.test_dir],
+            env=self.env,
+            check=True
+        )
+
+        # T-D6: Installed in .mam_deploy and executable
+        remover = os.path.join(self.test_dir, ".mam_deploy", "remove.sh")
+        updater = os.path.join(self.test_dir, ".mam_deploy", "update.sh")
+        self.assertTrue(os.path.exists(remover))
+        self.assertTrue(os.path.exists(updater))
+        self.assertTrue(os.access(remover, os.X_OK))
+
+        # T-D8: Execution from inside .mam_deploy directory targets parent workspace
+        res = subprocess.run(
+            ["bash", "./remove.sh", "--force"],
+            cwd=os.path.join(self.test_dir, ".mam_deploy"),
+            capture_output=True,
+            text=True
+        )
+        self.assertEqual(res.returncode, 0, f"remove.sh failed: {res.stderr}")
+        self.assertFalse(os.path.exists(os.path.join(self.test_dir, ".agents", "skills")))
+        self.assertFalse(os.path.exists(os.path.join(self.test_dir, ".mam_deploy")))
+
+    def test_td12_td13_td14_gitignore_managed_block(self):
+        """T-D12~D14: Verify .gitignore managed block injection and manifest exclusion (B-1 gate)."""
+        subprocess.run(
+            ["bash", os.path.join(self.repo_root, "deploy/install.sh"), self.test_dir],
+            env=self.env,
+            check=True
+        )
+
+        gi_path = os.path.join(self.test_dir, ".gitignore")
+        self.assertTrue(os.path.exists(gi_path))
+
+        with open(gi_path) as f:
+            content = f.read()
+
+        self.assertIn("# >>> MAM managed block", content)
+        self.assertIn("/.mam.env", content)
+        self.assertIn("/.mam_deploy/", content)
+
+        # T-D14 [MERGE BLOCKER B-1]: .gitignore MUST NOT be in manifest
+        manifest_path = os.path.join(self.test_dir, ".mam", "install_manifest.txt")
+        with open(manifest_path) as f:
+            manifest = f.read()
+        self.assertNotIn(".gitignore", manifest)
+
+    def test_td21_td22_td23_safe_refresh_custom_skills(self):
+        """T-D21~D23: Verify custom modifications to skills are preserved on refresh (B-4 gate)."""
+        subprocess.run(
+            ["bash", os.path.join(self.repo_root, "deploy/install.sh"), self.test_dir],
+            env=self.env,
+            check=True
+        )
+
+        # Modify a framework skill file
+        custom_skill = os.path.join(self.test_dir, ".agents", "skills", "lib.sh")
+        with open(custom_skill, "a") as f:
+            f.write("\n# CUSTOM_USER_MODIFICATION\n")
+
+        # Run install.sh again (REFRESH=1)
+        res = subprocess.run(
+            ["bash", os.path.join(self.repo_root, "deploy/install.sh"), self.test_dir],
+            env=self.env,
+            capture_output=True,
+            text=True
+        )
+        self.assertEqual(res.returncode, 0)
+        self.assertIn("Local modification detected", res.stderr)
+
+        # Verify modification preserved
+        with open(custom_skill) as f:
+            self.assertIn("CUSTOM_USER_MODIFICATION", f.read())
+
+        # Verify backup created in .mam/skill-backups
+        backups_dir = os.path.join(self.test_dir, ".mam", "skill-backups")
+        self.assertTrue(os.path.exists(backups_dir))
+
+    def test_td27_td28_update_preserves_mam_state(self):
+        """T-D27~D28: Verify update.sh preserves .mam state files across cycles (B-5 gate)."""
+        subprocess.run(
+            ["bash", os.path.join(self.repo_root, "deploy/install.sh"), self.test_dir],
+            env=self.env,
+            check=True
+        )
+
+        # Run update.sh
+        updater = os.path.join(self.test_dir, ".mam_deploy", "update.sh")
+        res = subprocess.run(["bash", updater, "--force"], cwd=self.test_dir, env=self.env, capture_output=True, text=True)
+        self.assertEqual(res.returncode, 0, f"update.sh failed: {res.stderr}")
+
+        # Verify asset_hashes.txt and version.txt still exist
+        self.assertTrue(os.path.exists(os.path.join(self.test_dir, ".mam", "asset_hashes.txt")))
+        self.assertTrue(os.path.exists(os.path.join(self.test_dir, ".mam", "version.txt")))
+
+if __name__ == "__main__":
+    unittest.main()