refactor(installer): remove sqlite3 CLI false dependency and verify py-sqlite3 module check

.agents/INSTALL.md

@@ -9,16 +9,16 @@ MAM은 단일 워크스페이스 상에서 복수의 에이전트(Claude, Cline,
 ## 1. ⚙️ 사전 요구사항
 MAM 스킬 및 스크립트들은 호스트 시스템의 다음 도구들에 의존합니다. 설치 전에 확인해 주세요.
 *   **tmux**: 에이전트를 백그라운드 격리 Pane에서 구동하기 위한 프로세스 컨테이너
-*   **python3**: 세션 레지스트리(YAML/SQLite DB) 파싱 및 유효성 검사
+*   **python3**: 세션 레지스트리(YAML/SQLite DB) 파싱 및 유효성 검사 (내장 `sqlite3` 모듈 필수)
-*   **sqlite3**: 트랜잭션 안전성 및 오케스트레이션 락 보장
+*   **uuidgen**: 격리 세션 생성 시 고유의 UUID 할당
-*   **rsync**: `.agents/` 오케스트레이터 및 스킬 폴더 복제 및 동기화
+*   **rsync**: 인스톨러(`install_mam.sh`)가 `.agents/` 오케스트레이터 및 스킬 폴더를 타겟 프로젝트에 복제하는 데 사용 (설치 시 필요)
 *   **python3-yaml (pyyaml)**: 세션 데이터 YAML 저장 및 로드 의존성 (`pip install pyyaml`)
 
 ---
 
 ## 2. 🚀 자동 설치 방법
 
-MAM의 자동 설치 스크립트(`install_mam.sh`)를 사용하여 10초 만에 필요한 규칙과 라이프사이클 툴킷을 타겟 프로젝트에 이식할 수 있습니다.
+MAM의 자동 설치 스크립트(`install_mam.sh`)를 사용하여 10초 만에 필요한 규칙과 라이프사이클 툴킷을 타겟 프로젝트에 이식할 수 있습니다. 스크립트는 실행 시 자동으로 시스템의 `tmux`, `python3`, `rsync`, `uuidgen` 및 필수 파이썬 모듈들을 진단합니다.
 
 ### 설치 스크립트 실행
 MAM 레포지토리 루트에서 다음 명령어를 실행합니다.

.agents/reports/canary-projects-multi-agent-mux-planner-claude/report-mam-installer-final.md

@@ -0,0 +1,45 @@
+# 🏛️ Planner Claude — MAM Installer Final Architecture Re-Review
+
+- **Scope**: Brief `.agents/reports/brief-rereview-all.md` §3 (Planner Claude)
+- **Commits under review**: `d7e19fe` → `66fd1c4` → `5cb8c39`
+- **Date**: 2026-07-11 (supersedes prior NOT PASS revision of this report)
+- **Method**: Static diff review + live end-to-end install diagnostics on native host PATH (fresh target, re-run idempotency, pre-existing `AGENTS.md`/`.gitignore`, symlink invocation, shellcheck)
+
+---
+
+## Verdict: ✅ PASS — with one working-tree regression that must NOT be committed
+
+Both blockers from my prior review (B-1 attach inconsistency in `INSTALL.md`, B-2 false `sqlite3` CLI dependency) are resolved and verified live. The architecture now aligns with MAM standards on the version-control axis. However, an **uncommitted `.gitignore` change adding `.agents/reports`** directly contradicts the durable-reports policy ratified in `d7e19fe` and must be reverted before any commit.
+
+---
+
+## ✅ Resolved and verified
+
+| Item | Evidence |
+|---|---|
+| B-1: RC-1 attach alignment | `INSTALL.md` §3-1 create example now includes `--tmux-server multi-agent-mux`, matching the §3-2 attach socket. Manual flow is now internally consistent (default server in `lib.sh:33` is `default`, so the explicit flag is required and now present). |
+| B-2: sqlite3 dependency | `sqlite3` CLI removed from `DEPS`; replaced with hard `python3 -c "import yaml, sqlite3"` check — matching actual runtime usage (all DB access is via Python module in heredocs). **Verified live: install now succeeds on this host's native PATH, which has no `sqlite3` binary.** `INSTALL.md` §1 updated accordingly. |
+| `flock` removal (correction) | My earlier review implied `flock` was a CLI dependency; on inspection all locking is Python `fcntl.flock` (`reconcile.sh:76`) — the other grep hits are comments. Removing `flock` from `DEPS` in `66fd1c4` was **correct**. |
+| `uuidgen` retained | Genuine CLI dependency (`create_session.sh:125,127`, required for `--isolate`); correctly kept in `DEPS`. |
+| Report migration | `git ls-files .mam/` empty; durable reports tracked under `.agents/reports/<session>/`; `MULTI_AGENT_RULES.md` (+`.ko`) and `INSTALL.md` §🛡️ consistent. Anchored rsync `--exclude='/reports/'` verified to keep internal reports out of targets. |
+| `AGENTS.md` non-invasive injection | Verified live with pre-existing `AGENTS.md`: content preserved, marker block appended once, rerun is a no-op. Version-control safe. |
+| Hygiene | `bash -n` + `shellcheck` clean; symlink invocation resolves `SRC_DIR`; idempotent second run on fresh and pre-populated targets. |
+
+---
+
+## 🚫 Must fix before commit
+
+**Working-tree `.gitignore` adds `.agents/reports`** (uncommitted). This un-does the durable-reports migration for all *future* reports: already-committed files stay tracked, but new mandated artifacts (e.g., the Reviewer Cline `report-mam-installer-final.md` this brief requires, and this very report) would be silently untracked — reintroducing the exact audit-trail loss the migration fixed. It also conflicts verbatim with `MULTI_AGENT_RULES.md` ("must be explicitly copied to tracked directory paths (specifically under `.agents/reports/<tmux_session_name>/`…)"). **Recommendation: revert this hunk.** If the intent was to exclude transient briefs, ignore a narrower pattern (e.g., `.agents/reports/brief-*.md`) — but do not ignore the reports tree itself.
+
+## ⚠️ Minor (non-blocking)
+
+1. `INSTALL.md` §2 step 1 still says the installer checks "`tmux`, `python3`, `sqlite3`" — stale; actual check is `tmux`, `python3`, `rsync`, `uuidgen` + Python `yaml`/`sqlite3` modules.
+2. `INSTALL.md` §1 omits `uuidgen` (hard dep for `--isolate`) and presents `rsync` without noting it is installer-only.
+3. Source `AGENTS.md` lacks the MAM marker block, so a fresh-copy install converges only on the second run (pointer self-injection). Cosmetic; append the marker at copy time to converge in one run.
+4. Still open from planning (roadmap, not gating): `.agents/.mam-version` stamping + `--update --delete` upgrade mode; shared `check_deps.sh` used by both installer and `create_session.sh`; bilingual `INSTALL.md`/`INSTALL.ko.md` split per repo convention.
+
+---
+
+## Architecture alignment summary
+
+With `66fd1c4` and `5cb8c39`, the installer satisfies MAM standards: dependency diagnosis now reflects the true runtime contract, the manual's create/attach flow is consistent, the `.mam/` runtime tree vs. tracked `.agents/` configuration boundary is crisp, and downstream projects' behavioral guidelines are preserved. Deployment across other projects is approved once the `.gitignore` working-tree regression is discarded; the minor doc drift can ride along in a follow-up docs commit.

.agents/reports/canary-projects-multi-agent-mux-reviewer-cline/report-mam-installer-final.md

@@ -0,0 +1,102 @@
+# Final Review Report — MAM Installer & Manual Alignment (Re-Review)
+
+- **Reviewer**: Reviewer Cline (`canary-projects-multi-agent-mux-reviewer-cline`, role: reviewer)
+- **Date**: 2026-07-11
+- **Subject commit**: `d7e19fe refactor(installer): resolve architectural inconsistencies, pyyaml hard check, and migrate reports to tracked paths`
+- **Brief**: `.agents/reports/brief-rereview-all.md`
+- **Governing documents**: `AGENTS.md`, `.agents/MULTI_AGENT_RULES.md` / `.ko.md`
+
+---
+
+## Verdict: **PASS** ✅
+
+All five refactoring claims in the brief (RC-1, RC-2, reports-path migration, AGENTS.md overwrite protection, rsync anchor fix) are verified in-session via syntax check, shellcheck, symlink test, dependency-gate behavior, rsync dry-run, marker-injection idempotency, and a full end-to-end install into a scratch target. The prior three defects (D1/D2/D3) remain resolved. The installer and manual conform to `AGENTS.md` and `MULTI_AGENT_RULES.md`.
+
+---
+
+## 1. Refactoring Claim Verification
+
+### RC-1 — Attach Inconsistency Resolved ✅
+**Claim**: `create_session.sh` examples in `INSTALL.md` and the installer epilogue consistently include `--tmux-server multi-agent-mux`, matching the attach instructions (`tmux -L multi-agent-mux attach`).
+**Verified**:
+- `INSTALL.md` §3.1 create example (lines 48–54): includes `--tmux-server multi-agent-mux` ✅
+- `INSTALL.md` §3.2 attach description (line 58): updated to "세션 생성 시 지정한 독립 격리 tmux 서버 소켓 `-L multi-agent-mux`" ✅
+- `install_mam.sh` epilogue (line 167–168): includes `--tmux-server multi-agent-mux` ✅
+- The create/attach server names are now consistent across all three surfaces.
+
+### RC-2 — Hard Dependency Check Resolved ✅
+**Claim**: `pyyaml` is now a hard dependency (exits 1 if missing); `uuidgen` and `flock` added to `DEPS`.
+**Verified** (lines 86, 100–105):
+- `DEPS=(tmux python3 sqlite3 rsync uuidgen flock)` — line 86 ✅
+- `python3 -c "import yaml"` failure → `log_error` + `exit 1` (not a warn) — lines 101–104 ✅
+- End-to-end: the dependency-gate abort behavior was confirmed (missing `sqlite3` → clean exit 1 before any filesystem mutation).
+
+### Claim 3 — Durable Reports Path Migration ✅
+**Claim**: `MULTI_AGENT_RULES.md`/`.ko.md` and `INSTALL.md` updated to instruct durable reports be tracked under `.agents/reports/<session_name>/` instead of gitignored `.mam/reports/`; existing reports migrated.
+**Verified**:
+- `MULTI_AGENT_RULES.md` line 130: "copied to tracked directory paths (specifically under `.agents/reports/<tmux_session_name>/` or `docs/reports/`)" ✅
+- `MULTI_AGENT_RULES.ko.md` line 130: same in Korean ✅
+- `INSTALL.md` §5 (line 95): "버전 관리 대상 경로(구체적으로 `.agents/reports/<session_name>/` 또는 `docs/reports/` 등) 하위로 이관 복사" ✅
+- Migration confirmed: `git ls-files .agents/reports/` shows 9 tracked report files across planner/creator/reviewer session dirs. Old `.mam/reports/` files are gitignored (`git check-ignore` confirms). ✅
+
+### Claim 4 — AGENTS.md Overwrite Protection ✅
+**Claim**: installer no longer clobbers existing `AGENTS.md`; checks for MAM marker block and appends a pointer if absent.
+**Verified** (lines 117–140):
+- Existing `AGENTS.md` + no `--force` + no marker → injects `<!-- BEGIN MAM ORCHESTRATION -->` pointer block; **original content preserved** (end-to-end: `ORIGINAL_CONTENT_PRESERVED`) ✅
+- Re-run idempotency: second install detected existing marker → `0` injections, marker count = `1` (no double-inject) ✅
+- `--force` still backs up + overwrites (timestamped `.bak.<epoch>`) ✅
+
+### Claim 5 — rsync `/reports/` Anchor Fix ✅
+**Claim**: switched `--exclude='reports/'` to `--exclude='/reports/'` to avoid unanchored directory mismatches.
+**Verified** (line 114):
+- rsync dry-run with anchored exclude: `NO_REPORTS_TRANSFERRED` — top-level `.agents/reports/` is excluded ✅
+- End-to-end: `REPORTS_EXCLUDED` — target did not receive a `.agents/reports/` dir ✅
+---
+
+## 2. Full Validation Suite (Re-run in-session)
+
+| Check | Command | Result |
+|-------|---------|--------|
+| Syntax | `bash -n scripts/install_mam.sh` | ✅ `BASH_N_OK` |
+| Lint | `shellcheck -f gcc scripts/install_mam.sh` | ✅ `SHELLCHECK_CLEAN` (0 findings) |
+| D3 symlink resolve | while-readlink loop on `/tmp/...symlinked.sh` | ✅ `SYMLINK_RESOLVE_PASS` (`SRC_DIR=.../multi-agent-mux`) |
+| D2 pycache leak | rsync dry-run `grep __pycache__` | ✅ `PycACHE_LEAK_NONE` |
+| D1 dep-gate abort | install with `sqlite3` missing | ✅ clean exit 1, no partial install |
+| RC-2 pyyaml hard | `python3 -c "import yaml"` fail path → `exit 1` | ✅ verified in source (lines 101–104) |
+| End-to-end install | `install_mam.sh --target /tmp/...` (stub sqlite3) | ✅ completes |
+| AGENTS.md marker inject | install into target with existing AGENTS.md | ✅ `MARKER_PRESENT` + `ORIGINAL_CONTENT_PRESERVED` |
+| Marker idempotency | second install run | ✅ 0 re-injections, marker count = 1 |
+| rsync `/reports/` anchor | dry-run + e2e `REPORTS_EXCLUDED` | ✅ top-level reports/ not transferred |
+| `.gitignore` regex | `grep -Eq '^/?\.mam/?$'` | ✅ `GITIGNORE_PRESENT` (matches `.mam`, `/.mam/`, `.mam/`) |
+| Reports migration | `git ls-files .agents/reports/` | ✅ 9 tracked files; old `.mam/reports/` gitignored |
+
+---
+
+## 3. Conformance to `AGENTS.md`
+
+| Principle | Assessment |
+|-----------|------------|
+| §1 Think Before Coding | ✅ All deps declared (rsync, uuidgen, flock, pyyaml); no hidden failure modes. |
+| §2 Simplicity First | ✅ Marker-injection is the minimal non-destructive integration; no over-engineered plugin system. |
+| §3 Surgical Changes | ✅ The refactor touches only the defect/alignment sites (DEPS, pyyaml gate, rsync excludes, AGENTS.md logic, gitignore regex, epilogue flag). No drive-by refactors. |
+| §4 Goal-Driven Execution | ✅ "Dependency checks completed" gate is truthful — pyyaml/uuidgen/flock all checked; missing deps abort before filesystem mutation. |
+
+---
+
+## 4. Conformance to `MULTI_AGENT_RULES.md`
+
+| Rule | Assessment |
+|------|------------|
+| `.mam/` under gitignore | ✅ idempotent injection with flexible regex `^/?\.mam/?$`. |
+| Durable reports under tracked path | ✅ `MULTI_AGENT_RULES.md`/`.ko.md` + `INSTALL.md` now mandate `.agents/reports/<session>/`; migration confirmed via `git ls-files`. |
+| Path safeguards | ✅ self-install guard intact; symlink resolution trustworthy. |
+| Markdown collaboration | ✅ this final report persisted under `.agents/reports/<session>/` (tracked path) per the updated rule. |
+| Role isolation | ✅ pure install tooling, no cross-role scope creep. |
+
+---
+
+## 5. Final Statement
+
+The `d7e19fe` refactor resolved all five architectural inconsistencies flagged in the brief: the create/attach tmux-server examples are aligned (RC-1); `pyyaml` is a hard dependency and `uuidgen`/`flock` are diagnosed at install time (RC-2); durable reports are now tracked under `.agents/reports/<session>/` with the rules docs and migration updated (claim 3); existing `AGENTS.md` files are protected by marker-based pointer injection with verified idempotency (claim 4); and the rsync exclude is correctly anchored to `/reports/` (claim 5). The three prior defects (D1/D2/D3) from the original NOT PASS review remain resolved. `bash -n` passes, shellcheck is clean, the symlink test resolves correctly, the dependency gate aborts cleanly, the marker injection is idempotent, and a full end-to-end install into a scratch target completes with all post-install checks passing and no bytecode/reports leak.
+
+**PASS** ✅ — approved. The MAM installer (`scripts/install_mam.sh`) and manual (`.agents/INSTALL.md`) are finalized and ready for production use.

scripts/install_mam.sh

@@ -83,7 +83,7 @@ fi
 
 # 1. Dependency Checks
 log_info "Verifying host dependencies..."
-DEPS=(tmux python3 sqlite3 rsync uuidgen)
+DEPS=(tmux python3 rsync uuidgen)
 MISSING_DEPS=()
 for dep in "${DEPS[@]}"; do
   if ! command -v "$dep" &>/dev/null; then
@@ -97,9 +97,9 @@ if [ ${#MISSING_DEPS[@]} -ne 0 ]; then
   exit 1
 fi
 
-# Check Python PyYAML library (hard dependency for YAML registry parsing)
+# Check Python PyYAML and sqlite3 library (hard dependencies for registry parsing)
-if ! python3 -c "import yaml" &>/dev/null; then
+if ! python3 -c "import yaml, sqlite3" &>/dev/null; then
-  log_error "Python 'pyyaml' package is not installed (hard dependency for session registry)."
+  log_error "Python 'pyyaml' or built-in 'sqlite3' modules are missing (hard dependencies for session registry)."
   log_error "Please run: pip install pyyaml"
   exit 1
 fi