diff --git a/.agents/INSTALL.md b/.agents/INSTALL.md index a3813ab..a3d455b 100644 --- a/.agents/INSTALL.md +++ b/.agents/INSTALL.md @@ -9,16 +9,16 @@ MAM은 단일 워크스페이스 상에서 복수의 에이전트(Claude, Cline, ## 1. ⚙️ 사전 요구사항 MAM 스킬 및 스크립트들은 호스트 시스템의 다음 도구들에 의존합니다. 설치 전에 확인해 주세요. * **tmux**: 에이전트를 백그라운드 격리 Pane에서 구동하기 위한 프로세스 컨테이너 -* **python3**: 세션 레지스트리(YAML/SQLite DB) 파싱 및 유효성 검사 -* **sqlite3**: 트랜잭션 안전성 및 오케스트레이션 락 보장 -* **rsync**: `.agents/` 오케스트레이터 및 스킬 폴더 복제 및 동기화 +* **python3**: 세션 레지스트리(YAML/SQLite DB) 파싱 및 유효성 검사 (내장 `sqlite3` 모듈 필수) +* **uuidgen**: 격리 세션 생성 시 고유의 UUID 할당 +* **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 레포지토리 루트에서 다음 명령어를 실행합니다. diff --git a/.agents/reports/canary-projects-multi-agent-mux-planner-claude/report-mam-installer-final.md b/.agents/reports/canary-projects-multi-agent-mux-planner-claude/report-mam-installer-final.md new file mode 100644 index 0000000..85a3e5a --- /dev/null +++ b/.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//`; `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//`…)"). **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. diff --git a/.agents/reports/canary-projects-multi-agent-mux-reviewer-cline/report-mam-installer-final.md b/.agents/reports/canary-projects-multi-agent-mux-reviewer-cline/report-mam-installer-final.md new file mode 100644 index 0000000..df44da9 --- /dev/null +++ b/.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//` instead of gitignored `.mam/reports/`; existing reports migrated. +**Verified**: +- `MULTI_AGENT_RULES.md` line 130: "copied to tracked directory paths (specifically under `.agents/reports//` or `docs/reports/`)" ✅ +- `MULTI_AGENT_RULES.ko.md` line 130: same in Korean ✅ +- `INSTALL.md` §5 (line 95): "버전 관리 대상 경로(구체적으로 `.agents/reports//` 또는 `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 `` 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.`) ✅ + +### 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//`; migration confirmed via `git ls-files`. | +| Path safeguards | ✅ self-install guard intact; symlink resolution trustworthy. | +| Markdown collaboration | ✅ this final report persisted under `.agents/reports//` (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//` 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. \ No newline at end of file diff --git a/scripts/install_mam.sh b/scripts/install_mam.sh index 1797f21..3567ea4 100755 --- a/scripts/install_mam.sh +++ b/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) -if ! python3 -c "import yaml" &>/dev/null; then - log_error "Python 'pyyaml' package is not installed (hard dependency for session registry)." +# Check Python PyYAML and sqlite3 library (hard dependencies for registry parsing) +if ! python3 -c "import yaml, sqlite3" &>/dev/null; then + 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