diff --git a/.agents/reports/canary-projects-multi-agent-mux-creator-claude/report-markdown-analysis-crosscheck.md b/.agents/reports/canary-projects-multi-agent-mux-creator-claude/report-markdown-analysis-crosscheck.md new file mode 100644 index 0000000..57840f6 --- /dev/null +++ b/.agents/reports/canary-projects-multi-agent-mux-creator-claude/report-markdown-analysis-crosscheck.md @@ -0,0 +1,75 @@ +# Root Markdown Analysis — Cross-Check Report (Creator Claude) + +- **Reviewer**: Creator Claude (`canary-projects-multi-agent-mux-creator-claude`) +- **Date**: 2026-07-11 +- **Brief**: `.mam/reports/brief-root-markdowns.md` +- **Cross-checked against**: `.agents/reports/canary-projects-multi-agent-mux-reviewer-cline/report-markdown-analysis.md` (Reviewer Cline, 2026-07-11) +- **Method**: independent read of all 7 files + `git log --follow` per file + repo-wide inbound-link grep + verification of implementation claims against shipped commits. + +--- + +## Verdict Summary + +Cline's verdicts (3 DELETE / 4 KEEP) are **confirmed in substance**, with **one amendment**: `session_isolation_discussion.md` cannot be deleted standalone without breaking two inbound links in live tracked docs (see §6). + +| # | File | My Verdict | Agrees with Cline? | +|---|------|-----------|--------------------| +| 1 | `task.md` | **DELETE** | ✅ | +| 2 | `implementation_plan.md` | **DELETE** | ✅ | +| 3 | `BOOTSTRAP.md` | **KEEP** | ✅ | +| 4 | `FUTURE_WORKS.ko.md` | **KEEP** | ✅ | +| 5 | `DONE.md` | **KEEP** | ✅ | +| 6 | `session_isolation_discussion.md` | **DELETE — with link cleanup** | ⚠️ amended | +| 7 | `AGENTS.md` | **KEEP** | ✅ | + +--- + +## Per-File Analysis + +### 1. `task.md` — DELETE +- **Purpose**: Developer checklist (Rev.1) for the "deploy URL parameterization" task (`MAM_REPO_URL` / `MAM_ARCHIVE_URL` / `MAM_INSTALLER_URL`). +- **Status**: The work **shipped in commit `6408f4a`** (2026-07-09, `feat(deploy): parameterize distribution URLs via MAM_*_URL env vars`) touching exactly the four files the plan prescribed (`deploy/install.sh`, `deploy/update.sh`, `.env.example`, `deploy/README.md`). Independently verified: all three `${MAM_*_URL:-…}` patterns exist at the planned locations (`install.sh:57-58`, `update.sh:139`) and both docs carry the variables. Yet every checkbox in the file is still `[ ]`, and the file ends with a stray accidental-paste line (`agy --conversation=20cc2d8e-…`). Note the file was only ever committed once — bundled into the unrelated isolation-docs commit `d76e470`. +- **Justification**: Fully superseded by the shipped commit; retaining an all-unchecked checklist for done work actively misleads future agents. `task.md`/`implementation_plan.md` are per-cycle scratch names per `.agents/multi_agent_workflow.md` — the *convention* survives deletion of this instance. + +### 2. `implementation_plan.md` — DELETE +- **Purpose**: Planner design doc (Rev.1) for the same deploy URL parameterization task; still marked "Draft (사용자 승인 대기)". +- **Status**: Same as above — implemented byte-for-byte in `6408f4a` (default values preserved, `.env` non-sourcing decision honored, mirror examples added to `deploy/README.md:35-40`). +- **Justification**: Superseded by shipped code. The only inbound link is from `task.md`, which is deleted in the same set. Design rationale worth preserving is already encoded in the commit message, `.env.example` comments, and `deploy/README.md`. + +### 3. `BOOTSTRAP.md` — KEEP +- **Purpose**: Agent-facing setup/verification guide (env config, venv, MQTT handshake test). +- **Status**: Active. Referenced from `README.md:177,186`, and explicitly in the deploy installer's runtime-doc **allowlist** (`deploy/install.sh:131` copies `MESSAGING.md BOOTSTRAP.md BOOTSTRAP.ko.md AGENTS.md`) — deleting it would silently degrade every fresh install. Last substantively updated 2026-07-09. +- **Justification**: Load-bearing runtime asset, not a dev leftover. (Same verdict extends to `BOOTSTRAP.ko.md`.) + +### 4. `FUTURE_WORKS.ko.md` — KEEP +- **Purpose**: Korean roadmap of pending improvements (FW-P1~P7, FW-W1~W7, FW-D2~D4 open; FW-D1 resolved). +- **Status**: Active backlog — most items remain unimplemented (e.g., FW-P6 root-marker detection, FW-P7 monitor HMAC hardening). Maintained mirror of `FUTURE_WORKS.md`. +- **Justification**: This is the project's only backlog tracker; deletion loses planned work. (Same verdict for the English `FUTURE_WORKS.md`.) + +### 5. `DONE.md` — KEEP +- **Purpose**: Verified completion record for 28 items (FW-01~FW-16, FW-L1~L3, FW-N1~N7, FW-W3) with per-item commits and 3-agent cross-verification results. +- **Status**: Static historical record; explicitly linked from `FUTURE_WORKS.md:4` ("For completed items, see `DONE.md`") and its Korean twin. +- **Justification**: Deleting it dangles the FUTURE_WORKS reference and erases the audit trail mapping FW-IDs to commits. Zero maintenance cost. (Same for `DONE.ko.md`.) + +### 6. `session_isolation_discussion.md` — DELETE, **but only with link cleanup** (amendment to Cline) +- **Purpose**: Rev.3 consolidated design discussion for the session-ID isolation feature. +- **Status**: Superseded — the doc itself declares `implementation_plan.session_isolation.md` (Rev.3) the single source of truth, and the feature is fully implemented, integration-tested, and PASSed by both reviewers (commits through `dad99f5`). +- **Amendment**: Cline's report misses that **two live tracked docs still link to it**: `implementation_plan.session_isolation.md:6` (관련 자료) and `task.session_isolation.md:3` (기준 문서). Standalone deletion creates dangling links. +- **Recommendation**: Treat the whole isolation doc set (`session_isolation_discussion.md`, `Problem_Definition.md`, `implementation_plan.session_isolation.md`, `task.session_isolation.md`, `session_isolation_handover.md` — the latter four out of this brief's scope) as one unit: either delete/archive them **together** (the feature is done and PASSed; the durable outcome lives in `.agents/reports/*/report-isolation-review.md` and git history), or if only the discussion doc goes now, remove the two inbound link references in the same commit. + +### 7. `AGENTS.md` — KEEP +- **Purpose**: Core behavioral guidelines for all agents; entry pointer to `.agents/MULTI_AGENT_RULES.md`. +- **Status**: Active and essential — copied to target projects by **both** installers (`scripts/install_mam.sh:127,138` and `deploy/install.sh:131`), referenced by README and the orchestration rules. +- **Justification**: Deleting it breaks both install paths and the documented onboarding flow. + +--- + +## Out-of-Scope Observations (for the record) + +1. The root holds **18** markdown files; the brief covered 7. The undiscussed siblings share the fates above: `*.ko.md` twins follow their English counterparts; the four other session-isolation docs should be dispositioned as a set with #6. +2. The uncommitted working-tree `.gitignore` change adding `.agents/reports` (flagged in my installer verdict) is still present and would ignore the very reports directory this brief writes into — it should be resolved before committing any deletions. +3. Deletions of tracked files require `git rm` + commit; per standing constraints I have not deleted or committed anything — this report is analysis only. + +## Final Verdict + +**PASS on Cline's analysis with the §6 amendment**: 3 DELETE / 4 KEEP confirmed; `session_isolation_discussion.md` must be deleted together with cleanup of its two inbound links (or as part of archiving the whole isolation doc set). diff --git a/.agents/reports/canary-projects-multi-agent-mux-planner-claude/report-cleanup-plan.md b/.agents/reports/canary-projects-multi-agent-mux-planner-claude/report-cleanup-plan.md new file mode 100644 index 0000000..8b3428d --- /dev/null +++ b/.agents/reports/canary-projects-multi-agent-mux-planner-claude/report-cleanup-plan.md @@ -0,0 +1,127 @@ +# Root Markdown Cleanup Plan (Planner Claude — Final) + +- **Planner**: Planner Claude (`canary-projects-multi-agent-mux-planner-claude`) +- **Date**: 2026-07-11 +- **Brief**: `.mam/reports/brief-planner-cleanup.md` +- **Inputs consolidated**: + 1. Reviewer Cline — `.agents/reports/canary-projects-multi-agent-mux-reviewer-cline/report-markdown-analysis.md` + 2. Creator Claude — `.agents/reports/canary-projects-multi-agent-mux-creator-claude/report-markdown-analysis-crosscheck.md` +- **Executor**: Antigravity + +--- + +## 1. Final Verdict Checklist (Consolidated) + +Both reviewers agree on all 7 verdicts. The single discrepancy is *how* to delete #6, not *whether*. + +| # | File | Cline | Creator Claude | **Final** | +|---|------|-------|----------------|-----------| +| 1 | `task.md` | DELETE | DELETE | ☑ **DELETE** | +| 2 | `implementation_plan.md` | DELETE | DELETE | ☑ **DELETE** | +| 3 | `BOOTSTRAP.md` | KEEP | KEEP | ☑ **KEEP** | +| 4 | `FUTURE_WORKS.ko.md` | KEEP | KEEP | ☑ **KEEP** | +| 5 | `DONE.md` | KEEP | KEEP | ☑ **KEEP** | +| 6 | `session_isolation_discussion.md` | DELETE (standalone) | DELETE **+ inbound-link cleanup** | ☑ **DELETE + link cleanup** (Creator Claude's amendment adopted) | +| 7 | `AGENTS.md` | KEEP | KEEP | ☑ **KEEP** | + +**Discrepancy resolution (#6)**: Creator Claude's cross-check found two live tracked docs still linking to `session_isolation_discussion.md` (`implementation_plan.session_isolation.md:6`, `task.session_isolation.md:3`), which Cline's report missed. A standalone `git rm` would leave dangling links. **Decision: delete the file and surgically remove the two inbound link references in the same commit.** The broader option (archiving the entire session-isolation doc set — `Problem_Definition.md`, `implementation_plan.session_isolation.md`, `task.session_isolation.md`, `session_isolation_handover.md`) is **out of scope** for this plan: those four files were never analyzed under the brief's 7-file scope, so deleting them now would be an unauthorized scope expansion. They are listed in §4 as a recommended follow-up requiring separate GM authorization. + +--- + +## 2. Impact Assessment + +Verified by repo-wide grep (`--include='*.md'` plus `deploy/install.sh`, `scripts/install_mam.sh`): + +| File to delete | Inbound references | Impact after this plan | +|---|---|---| +| `task.md` | Only from `implementation_plan.md` (deleted in same commit). `.agents/multi_agent_workflow.md` references the *filename convention* for future planning cycles, not this instance. | ✅ None | +| `implementation_plan.md` | Only from `task.md:3` (deleted in same commit). | ✅ None | +| `session_isolation_discussion.md` | **Live**: `implementation_plan.session_isolation.md:6`, `task.session_isolation.md:3` → **fixed by T2/T3 edits below**. **Historical** (briefs/reports under `.agents/reports/**`): intentionally left untouched — they are immutable audit records describing a past review of a then-existing file. | ✅ None after T2/T3 | + +KEEP-file safety confirmed: `BOOTSTRAP.md` is in the deploy installer's doc allowlist (`deploy/install.sh:131`); `AGENTS.md` is copied by both installers (`deploy/install.sh:131`, `scripts/install_mam.sh:127,138`); `DONE.md` is linked from `FUTURE_WORKS.md:4`; `FUTURE_WORKS.ko.md` is the active backlog mirror. None are touched. + +No documentation build system exists in this repo (no mkdocs/sphinx config); link integrity is the only build-type concern. + +**Precondition check (resolved)**: the previously flagged uncommitted `.gitignore` change (adding `.agents/reports`) is no longer present — `git diff` is clean. No blocker remains. The only untracked files are the two reviewer reports, which must be committed per the durable-reports convention (`.agents/MULTI_AGENT_RULES.md`). + +--- + +## 3. Execution Instructions (for Antigravity) + +Run from the repo root. All steps are non-interactive. **Do not use `rm` — the three files are git-tracked; use `git rm` so the deletion is staged.** + +### T0 — Preflight (abort if it fails) +```bash +cd /home/godopu16/PuKi/laa/canary_projects/multi-agent-mux +git diff --quiet && git diff --cached --quiet || { echo "ABORT: dirty tree"; exit 1; } +``` +(Untracked files are fine and expected: the two reviewer reports.) + +### T1 — Delete the three files +```bash +git rm task.md implementation_plan.md session_isolation_discussion.md +``` + +### T2 — Remove the inbound link in `implementation_plan.session_isolation.md` (line 6) +Replace the line: +``` +- **관련 자료**: [Problem_Definition.md](Problem_Definition.md), [session_isolation_discussion.md](session_isolation_discussion.md) +``` +with: +``` +- **관련 자료**: [Problem_Definition.md](Problem_Definition.md) +``` + +### T3 — Remove the inbound link in `task.session_isolation.md` (line 3) +Replace the line: +``` +> 기준 문서: [implementation_plan.session_isolation.md](implementation_plan.session_isolation.md) (Rev.3) / [session_isolation_discussion.md](session_isolation_discussion.md) +``` +with: +``` +> 기준 문서: [implementation_plan.session_isolation.md](implementation_plan.session_isolation.md) (Rev.3) +``` +**Surgical constraint (AGENTS.md §3): change only these two lines. No other edits to either file.** + +### T4 — Verify no dangling references remain outside the immutable report archive +```bash +grep -rn --include='*.md' 'session_isolation_discussion\|\](task\.md)\|\](implementation_plan\.md)' \ + --exclude-dir=.git . | grep -v '^\./\.agents/reports/' | grep -v '^\./\.mam/' +``` +**Expected output: empty** (exit code 1). Any hit = stop and report back. + +### T5 — Stage the analysis reports and this plan, then commit (single atomic commit) +```bash +git add .agents/reports/canary-projects-multi-agent-mux-reviewer-cline/report-markdown-analysis.md \ + .agents/reports/canary-projects-multi-agent-mux-creator-claude/report-markdown-analysis-crosscheck.md \ + .agents/reports/canary-projects-multi-agent-mux-planner-claude/report-cleanup-plan.md \ + implementation_plan.session_isolation.md task.session_isolation.md +git commit -m "chore(docs): remove obsolete root planning docs per 3-agent markdown audit + +- Delete task.md / implementation_plan.md (deploy URL parameterization + shipped in 6408f4a; checklists were stale) and + session_isolation_discussion.md (superseded by + implementation_plan.session_isolation.md; feature shipped and PASSed) +- Remove the two inbound links to the deleted discussion doc +- Add reviewer analysis reports and this cleanup plan under .agents/reports/" +``` + +### T6 — Post-commit sanity +```bash +git status --short # expected: empty +bash -n scripts/install_mam.sh deploy/install.sh # unchanged, but cheap regression guard +``` + +--- + +## 4. Out-of-Scope Follow-Ups (require separate GM authorization) + +1. **Session-isolation doc set retirement**: `Problem_Definition.md`, `implementation_plan.session_isolation.md`, `task.session_isolation.md`, `session_isolation_handover.md` are also completed-work artifacts. Recommend a follow-up brief to analyze and disposition them as one unit (the durable outcomes already live in `.agents/reports/*/report-isolation-review.md` and git history). +2. **`.ko.md` twins**: verdicts here extend naturally to counterparts (`DONE.ko.md`, `FUTURE_WORKS.md`, `BOOTSTRAP.ko.md`) — all KEEP; no action. +3. The root still holds 18→15 markdown files after this cleanup; a future pass may consider moving design docs to a `docs/` subtree, but that is a layout decision, not cleanup. + +--- + +## Final Authorization + +**Plan status: APPROVED for execution** by Antigravity exactly as written in §3. Deviations (non-empty T4 output, preflight failure, edit-line mismatch) must halt execution and be reported back to the Planner. diff --git a/.agents/reports/canary-projects-multi-agent-mux-reviewer-cline/report-markdown-analysis.md b/.agents/reports/canary-projects-multi-agent-mux-reviewer-cline/report-markdown-analysis.md new file mode 100644 index 0000000..ea50b35 --- /dev/null +++ b/.agents/reports/canary-projects-multi-agent-mux-reviewer-cline/report-markdown-analysis.md @@ -0,0 +1,91 @@ +# Workspace Root Markdown Files Analysis Report + +- **Reviewer**: Reviewer Cline (`canary-projects-multi-agent-mux-reviewer-cline`, role: reviewer) +- **Date**: 2026-07-11 +- **Brief**: `.mam/reports/brief-root-markdowns.md` +- **Scope**: 7 root markdown files — purpose, status, KEEP/DELETE verdict + +--- + +## Summary Verdict Table + +| # | File | Purpose | Status | Verdict | +|---|------|---------|--------|---------| +| 1 | `task.md` | Task checklist for "deploy URL parameterization" (Rev.1) | **Obsolete** — work shipped in commit `6408f4a`, checkboxes never updated | **DELETE** | +| 2 | `implementation_plan.md` | Implementation plan for "deploy URL parameterization" (Rev.1) | **Obsolete** — superseded by shipped commit `6408f4a` | **DELETE** | +| 3 | `BOOTSTRAP.md` | Setup & verification guide for new agents | **Active** — referenced by `README.md`, in `deploy/install.sh` doc-allowlist | **KEEP** | +| 4 | `FUTURE_WORKS.ko.md` | Korean roadmap of pending improvement items | **Active** — open items FW-P1~P7/W1~W7/D2~D4; maintained KO mirror of `FUTURE_WORKS.md` | **KEEP** | +| 5 | `DONE.md` | Completed-tasks tracker (FW-01~FW-W3, verified 2026-06-21) | **Static historical record** — referenced by `FUTURE_WORKS.md`; in `deploy/install.sh` skip-list | **KEEP** | +| 6 | `session_isolation_discussion.md` | Rev.3 discussion doc for session ID isolation | **Superseded** — single source of truth moved to `implementation_plan.session_isolation.md`; work is DONE (reviewed PASS) | **DELETE** | +| 7 | `AGENTS.md` | Core behavioral guidelines for all agents | **Active & essential** — installed by `install_mam.sh`, referenced everywhere | **KEEP** | + +--- + +## Detailed Analysis + +### 1. `task.md` — DELETE ❌ + +- **Purpose**: Task checklist (Rev.1) for the "배포 스크립트 URL 파라미터화" (deploy URL parameterization) effort. References `implementation_plan.md` as its base document. +- **Current Status**: **Obsolete.** All checkboxes remain `[ ]` unchecked, but the work it describes **has been shipped**: commit `6408f4a feat(deploy): parameterize distribution URLs via MAM_*_URL env vars` implements exactly T1–T4 of this checklist. Verified in code: + - `deploy/install.sh:57` → `REPO_URL="${MAM_REPO_URL:-https://...}"` (T1 ✅) + - `deploy/install.sh:58` → `ARCHIVE_URL="${MAM_ARCHIVE_URL:-https://...}"` (T1 ✅) + - `deploy/update.sh:139` → `INSTALLER_URL="${MAM_INSTALLER_URL:-https://...}"` (T2 ✅) + - `.env.example:84-97` → all 3 variables documented (T3 ✅) + - The commit message matches the plan's §6 proposed commit message verbatim. +- **Verdict: DELETE.** Stale planning artifact for completed work. The checkboxes were never updated, leaving a misleading impression of incomplete work. The shipped commit + `.env.example` are the real records of completion. +- **Pre-deletion check**: no inbound references from `README.md`, `deploy/install.sh`, or any active code. Safe to delete. (`.agents/multi_agent_workflow.md` mentions `task.md` generically as a workflow convention, not this specific file.) + +### 2. `implementation_plan.md` — DELETE ❌ + +- **Purpose**: Implementation plan (Rev.1) for the same "deploy URL parameterization" effort, by Planner Agent dated 2026-07-09, status "Draft (사용자 승인 대기)". +- **Current Status**: **Obsolete.** Same as `task.md` — the plan was executed and shipped in commit `6408f4a`. The plan's §3.1/§3.2 code snippets match the current `deploy/install.sh`/`update.sh` line-for-line. Its status line still says "Draft (사용자 승인 대기)" which is no longer accurate. +- **Verdict: DELETE.** Stale planning artifact for completed work, paired with `task.md`. The shipped commit is the authoritative record. +- **Pre-deletion check**: no inbound references from `README.md` or active code. The only cross-reference is from `task.md` (also being deleted). Safe to delete. + +### 3. `BOOTSTRAP.md` — KEEP ✅ + +- **Purpose**: Setup & initialization guide for new agents/developers adopting the MAM workflow — scaffolding overview, `.env` configuration, directory/security audit, and bootstrap verification tests. +- **Current Status**: **Active.** Referenced by `README.md:177` (root file-tree listing) and `README.md:186` ("For detailed setup instructions, please consult the **[BOOTSTRAP.md](./BOOTSTRAP.md)** file"). Listed in `deploy/install.sh:131` doc-allowlist (`MESSAGING.md BOOTSTRAP.md BOOTSTRAP.ko.md AGENTS.md`) — intentionally shipped to installed targets. Has a Korean mirror `BOOTSTRAP.ko.md` (same bilingual convention as `MULTI_AGENT_RULES.md`/`.ko.md`). +- **Verdict: KEEP.** Active onboarding document, referenced from two authoritative surfaces (README, installer), part of the shipped doc set. + +### 4. `FUTURE_WORKS.ko.md` — KEEP ✅ + +- **Purpose**: Korean-language roadmap tracking pending improvement candidates (portability, concurrency, workflow, deployment hardening). +- **Current Status**: **Active.** Contains open items: FW-P1~P7, FW-W1~W7, FW-D2~D4 (all unchecked). Last updated 2026-06-24. One item struck through as resolved (FW-D1, 2026-06-24). This is the maintained Korean mirror of `FUTURE_WORKS.md` (same timestamp 2026-06-26 21:27, parallel bilingual convention) — NOT a stale backup. +- **Verdict: KEEP.** Living roadmap document with open work items; part of the repo's bilingual doc convention. +- **Note**: the header says "완료된 항목은 `DONE.ko.md`를 참조" — `DONE.ko.md` exists, so the cross-reference is valid. +### 5. `DONE.md` — KEEP ✅ + +- **Purpose**: Completed-tasks tracker recording FW-01 ~ FW-16, FW-L1~L3, FW-N1~N7, FW-W3 (28 items), verified by three agents (agy-new, agy-existing, claude-existing) on 2026-06-21. +- **Current Status**: **Static historical record.** All items complete and verified — this is a closed ledger, not a stale plan. Referenced by `FUTURE_WORKS.md:4` ("For completed items, see `DONE.md`") as the completion counterpart to the roadmap. Explicitly named in `deploy/install.sh:130` as a dev-doc intentionally **skipped** during install ("We skip dev-specific docs like README.md, DONE.md, and FUTURE_WORKS.md"). +- **Verdict: KEEP.** Not an obsolete plan — a permanent audit record of what was done, cross-referenced by the active roadmap. Deleting it would orphan `FUTURE_WORKS.md`'s "see DONE.md" pointer and lose the verification history (which agents verified what, with which commit SHAs). + +### 6. `session_isolation_discussion.md` — DELETE ❌ + +- **Purpose**: Rev.3 "단일 격리 디렉터리 통합본" — the integrated discussion/design doc for session ID isolation, consolidating earlier L1/L2 hybrid drafts. +- **Current Status**: **Superseded.** The single source of truth moved to `implementation_plan.session_isolation.md` (Rev.3), which lists this file as "관련 자료" (related material) — i.e., the dedicated plan is canonical, the discussion is the predecessor. The implementation is **DONE and reviewed PASS** (I verified this in my prior session-isolation review: commits `768cfe5`, `dad99f5`; T1–T6 + RK2 + T6 all PASS). The file's §5 still says "⏭️ 승인에 따라 Phase 0... 착수합니다" (proceeding to Phase 0), but Phase 0–4 are all complete. +- **Verdict: DELETE.** Superseded discussion draft. The canonical design lives in `implementation_plan.session_isolation.md`, task tracking in `task.session_isolation.md`, and the completed implementation in the codebase + my PASS review report. Keeping it creates a stale duplicate source of truth that could mislead future agents into thinking the work is still in progress. +- **Pre-deletion check**: inbound references exist only from historical reviewer briefs under `.agents/reports/.../brief-isolation-review.md` (audit trail, already completed) and from `implementation_plan.session_isolation.md`/`task.session_isolation.md` (which link to it as "관련 자료" for historical provenance — those dedicated docs are self-sufficient). No active code or `README.md` references it. Safe to delete; the audit trail in `.agents/reports/` preserves the review history. + +### 7. `AGENTS.md` — KEEP ✅ + +- **Purpose**: Core behavioral guidelines for all LLM coding agents (Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution). The repo's primary agent-behavior contract. +- **Current Status**: **Active & essential.** Referenced by `MULTI_AGENT_RULES.md` note, `BOOTSTRAP.md:184` (onboarding points agents to it), `install_mam.sh` (copies it to target project roots with marker-injection protection). It's the first file any agent is instructed to read. +- **Verdict: KEEP.** Foundational, actively enforced, non-negotiable. +--- + +## Deletion Risk Assessment (for the 3 DELETE candidates) + +| File | Inbound refs from active code/README? | Inbound refs from audit trail only? | Safe to delete? | +|------|--------------------------------------|-------------------------------------|-----------------| +| `task.md` | None (only `implementation_plan.md`, also being deleted) | No | ✅ Yes | +| `implementation_plan.md` | None (only `task.md`, also being deleted) | No | ✅ Yes | +| `session_isolation_discussion.md` | None from active code/README | Yes (`implementation_plan.session_isolation.md`, `task.session_isolation.md`, reviewer briefs) | ✅ Yes — audit trail preserved in `.agents/reports/`; the dedicated plan is self-sufficient | + +**Recommendation**: Delete the 3 files in a single atomic commit, e.g. `chore(docs): remove obsolete completed-plan and superseded discussion drafts`. The deletion is safe — no active code or README references them, and the audit trail (review reports, shipped commits, dedicated plan docs) fully preserves the history. + +--- + +## Final Statement + +Of the 7 root markdown files analyzed, **3 are safe to delete** (`task.md`, `implementation_plan.md`, `session_isolation_discussion.md`) — all are stale planning artifacts for work that has been completed, shipped, and reviewed PASS. The remaining **4 should be kept** (`BOOTSTRAP.md`, `FUTURE_WORKS.ko.md`, `DONE.md`, `AGENTS.md`) — they are either active/referenced documents or permanent audit records. No active code paths or authoritative documentation reference the 3 deletion candidates; deleting them removes misleading "in-progress" signals without losing any history. \ No newline at end of file diff --git a/implementation_plan.md b/implementation_plan.md deleted file mode 100644 index 6b4b491..0000000 --- a/implementation_plan.md +++ /dev/null @@ -1,138 +0,0 @@ -# Implementation Plan — 배포 스크립트 URL 파라미터화 (Rev.1) - -- **작성자**: Planner Agent -- **날짜**: 2026-07-09 -- **상태**: Draft (사용자 승인 대기) -- **관련 리뷰 피드백**: Reviewer A 이식성(portability) 스캔 결과 - ---- - -## 1. 배경 및 문제 정의 - -Reviewer A의 코드베이스 스캔 결과, 배포 스크립트에 배포 원본(origin) URL 3개가 하드코딩되어 있어 -포크/미러/사설 Gitea 인스턴스 환경으로의 이식성이 저해됨이 확인되었습니다. - -| # | 위치 | 변수 | 현재 하드코딩 값 | -|---|------|------|------------------| -| 1 | `deploy/install.sh:57` | `REPO_URL` | `https://git.godopu.com/tmpl/multi-agent-mux.git` | -| 2 | `deploy/install.sh:58` | `ARCHIVE_URL` | `https://git.godopu.com/tmpl/multi-agent-mux/archive/main.tar.gz` | -| 3 | `deploy/update.sh:138` | `INSTALLER_URL` | `https://git.godopu.com/tmpl/multi-agent-mux/raw/branch/main/deploy/install.sh` | - -그 외 스크립트(`lib.sh`, `create_session.sh` 등)는 상대 경로 및 `TARGET_DIR` 파라미터화가 -올바르게 적용되어 있어 이번 변경 범위에서 제외합니다. - -## 2. 목표 (Goals) - -1. 위 3개 URL을 환경변수 `MAM_REPO_URL`, `MAM_ARCHIVE_URL`, `MAM_INSTALLER_URL`로 - 오버라이드 가능하게 파라미터화하되, **미설정 시 현재 값을 그대로 기본값으로 유지**한다 - (기존 사용자에 대한 동작 변경 0). -2. 세 변수를 `.env.example`과 `deploy/README.md`에 문서화한다. -3. 검증 절차를 명문화하여 Developer가 DoD 자가 검증에 사용할 수 있게 한다. - -### Non-Goals (이번 범위 제외) - -- `README.md`/`BOOTSTRAP*.md` 본문의 원라이너 예시 URL 자체를 변수화하는 것 - (문서상의 예시는 실제 기본 배포 원본이므로 그대로 둔다). -- deploy 스크립트가 `.env` 파일을 직접 파싱/소싱하도록 만드는 것 (§3.4 설계 결정 참조). -- URL 간 파생 로직 (예: `MAM_REPO_URL`로부터 archive URL 자동 조립) — §3.5 참조. - -## 3. 설계 (Design) - -### 3.1. `deploy/install.sh` 수정 - -57–58행을 bash 기본값 확장 패턴으로 교체: - -```bash -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}" -``` - -### 3.2. `deploy/update.sh` 수정 - -138행을 동일 패턴으로 교체: - -```bash -INSTALLER_URL="${MAM_INSTALLER_URL:-https://git.godopu.com/tmpl/multi-agent-mux/raw/branch/main/deploy/install.sh}" -``` - -**체이닝 전파 주의**: `update.sh`는 140–142행에서 `curl ... | bash -s --`로 새 installer를 -실행한다. 호출자가 `MAM_REPO_URL=x bash update.sh` 형태(명령 접두 대입)로 실행하면 해당 -변수는 프로세스 환경에 export되어 자식 bash에 자동 상속되므로 별도 재-export 코드는 -불필요하다. 단, 이 상속 동작이 계약임을 스크립트 주석 및 문서에 명시한다. - -### 3.3. `.env.example` 문서화 - -새 섹션 `# deploy / distribution source`를 추가하고 기존 파일의 서식 규약 -(`#default:` 라인 + 주석 처리된 변수 예시)을 따른다. **핵심 주의 문구**를 반드시 포함: - -> 이 변수들은 deploy 스크립트가 **프로세스 환경에서** 읽는다. `install.sh`는 워크스페이스에 -> `.env`가 생기기 전(curl 원라이너) 실행될 수 있고 deploy 스크립트는 `.env`를 파싱하지 -> 않으므로, `export MAM_REPO_URL=...` 또는 명령 접두 대입으로 전달해야 한다. - -### 3.4. 설계 결정: `.env` 소싱을 하지 않는 이유 - -- `install.sh`는 설치 대상 디렉터리에 파일이 존재하기 전에 실행되므로 `.env` 의존이 불가능. -- `.env`를 `source`하면 임의 셸 코드 실행 경로가 생겨 보안·부작용 리스크 발생. -- 따라서 세 변수 모두 **환경변수 단일 경로**로 통일하고, `.env.example`에는 - "문서화 + 사용법 안내" 목적으로만 등재한다. - -### 3.5. 설계 결정: 변수 간 파생 없음 - -`MAM_REPO_URL`에서 archive/raw URL을 자동 조립하지 않는다. Gitea(`/archive/main.tar.gz`, -`/raw/branch/main/`)와 GitHub(`/archive/refs/heads/main.tar.gz`, `raw.githubusercontent.com`)의 -URL 스킴이 상이하여 파생 로직이 오히려 이식성을 해친다. 세 변수는 독립이며, 미러 운영 시 -**셋을 함께 설정**하도록 문서에 권고 문구를 넣는다. - -### 3.6. `deploy/README.md` 문서화 - -"How to Install and Deploy" 섹션에 미러/포크 설치 예시를 추가: - -```bash -# Installing from a fork/mirror -curl -fsSL https://my-mirror.example.com/.../install.sh \ - | MAM_REPO_URL=https://my-mirror.example.com/me/multi-agent-mux.git \ - MAM_ARCHIVE_URL=https://my-mirror.example.com/me/multi-agent-mux/archive/main.tar.gz \ - bash - -# Updating against a mirror -MAM_INSTALLER_URL=https://my-mirror.example.com/.../install.sh bash deploy/update.sh -``` - -(파이프 실행 시 접두 대입은 `bash` 쪽에 붙여야 함을 예시로 보여준다.) - -## 4. 파급 범위 및 리스크 분석 - -| 리스크 | 평가 | 완화책 | -|--------|------|--------| -| 기본값 오타로 기존 설치 경로 파손 | 중 | 검증 §5-3에서 기본값 문자열이 변경 전과 byte-identical한지 diff/grep으로 확인 | -| ShellCheck 경고 (SC2154 등) | 낮음 | `${VAR:-default}` 패턴은 미정의 변수 경고 없음. CI(`gitea-ci.yml`)의 shellcheck 단계로 확인 | -| `update.sh` 체이닝 시 오버라이드 미전파 | 중 | §3.2 상속 계약 주석 명시 + 검증 §5-5 | -| 문서-코드 정합성 (변수명 불일치) | 낮음 | task.md DoD에 변수명 3종 교차 대조 항목 포함 | - -## 5. 검증 절차 (Verification Steps) - -Developer는 커밋 전 아래를 순서대로 수행하고 결과를 리뷰 요청에 첨부한다. - -1. **문법 검사**: `bash -n deploy/install.sh deploy/update.sh` — 종료코드 0. -2. **린트**: `shellcheck deploy/install.sh deploy/update.sh` — 신규 경고 0 (CI와 동일 조건). -3. **기본값 무결성**: `grep -n 'MAM_\(REPO\|ARCHIVE\|INSTALLER\)_URL' deploy/*.sh` 출력에서 - `:-` 뒤 기본값 3개가 변경 전 하드코딩 문자열과 정확히 일치하는지 확인. -4. **오버라이드 동작 (install.sh)**: 빈 스크래치 디렉터리에서 - `MAM_ARCHIVE_URL=https://127.0.0.1:1/nope.tar.gz bash deploy/install.sh ` - 실행 → fetch 단계가 오버라이드된 URL로 시도하다 실패하는지 확인 - (`bash -x` 트레이스에서 `ARCHIVE_URL` 해석값 확인). **실제 워크스페이스에서 실행 금지.** -5. **오버라이드 동작 (update.sh)**: `update.sh`는 기존 설치를 파괴적으로 제거하므로 - 전체 실행 대신 `bash -x` 트레이스를 138행 부근에서 조기 중단(Ctrl-C 또는 read 삽입 없이 - 확인 후 `--force` 미사용)하거나, 디스포저블 스크래치 설치본에서만 end-to-end 수행. - 최소 기준: `MAM_INSTALLER_URL` 접두 대입 시 `INSTALLER_URL` 해석값이 오버라이드와 일치. -6. **회귀 (기본 경로)**: 리포지토리 루트에서 `bash deploy/install.sh` 재실행 → - `check_assets_present`가 충족되어 네트워크 fetch 없이 기존과 동일하게 완료되는지 확인. -7. **문서 정합**: `.env.example`·`deploy/README.md`에 세 변수명이 스크립트와 철자까지 - 일치하게 등재되었는지 교차 확인. - -## 6. 산출물 및 커밋 규약 - -- 변경 파일: `deploy/install.sh`, `deploy/update.sh`, `.env.example`, `deploy/README.md` -- 단일 원자적 커밋, 메시지 제안: - `feat(deploy): parameterize distribution URLs via MAM_*_URL env vars` -- 완료 후 Reviewer A(논리 정합) / Reviewer B(구현 세부) 이중 리뷰 → 양측 PASS 시 마감. diff --git a/implementation_plan.session_isolation.md b/implementation_plan.session_isolation.md index 110671e..eb62cba 100644 --- a/implementation_plan.session_isolation.md +++ b/implementation_plan.session_isolation.md @@ -3,7 +3,7 @@ - **작성자**: Planner Agent - **날짜**: 2026-07-10 (Rev.2 → Rev.3 개정) - **상태**: Draft (Phase 0 검증 게이트 대기 — 구현 미착수) -- **관련 자료**: [Problem_Definition.md](Problem_Definition.md), [session_isolation_discussion.md](session_isolation_discussion.md) +- **관련 자료**: [Problem_Definition.md](Problem_Definition.md) - **확정된 방향 (Rev.3)**: **all-L2 단일화** — 전 에이전트 isolation-UUID 격리 디렉터리 + 세션 row 영속화 + R1 claimed-set 불변식 --- diff --git a/session_isolation_discussion.md b/session_isolation_discussion.md deleted file mode 100644 index fafd90b..0000000 --- a/session_isolation_discussion.md +++ /dev/null @@ -1,132 +0,0 @@ -# 🛠️ 세션 ID 중복 충돌 해결 종합 설계 및 구현 계획서 (Rev.3 — 단일 격리 디렉터리 통합본) - -동일 CLI 계열(Claude / Cline)의 서로 다른 역할 에이전트가 같은 workspace에서 동시 구동될 때 대화 세션 ID를 공유하는 결함([Problem_Definition.md](Problem_Definition.md))을 해결하기 위한 최종 종합 설계안 및 구현 계획입니다. - -기존의 하이브리드 분기(L1/L2 병행) 구조를 걷어내고, **"모든 에이전트의 격리 디렉터리 관리 일원화"**라는 사용자(GM) 피드백을 반영하여 설계를 단순화한 버전입니다. Rev.3에서는 **실측 프로브 결과에 따른 격리 레버 정정 및 auth 시딩 계약**(사용자 승인 조건)을 반영했습니다. 상세 계획의 단일 원본은 [implementation_plan.session_isolation.md](implementation_plan.session_isolation.md) (Rev.3)입니다. - ---- - -## 1. 배경 및 문제 정의 - -동일한 워크스페이스에서 다중 역할 에이전트(예: `planner`와 `reviewer-a`, `developer`와 `reviewer-b`)가 기동될 때, 동일한 대화 UUID 또는 Cline 대화 ID를 공유함으로써 컨텍스트가 오염되고, 히스토리 쓰기 경합으로 인한 락 충돌 및 데이터 유실이 발생하는 문제가 발생했습니다. - -### 1.1 근본 원인 분석 -* **C1. 생성 시 고유 ID 미지정**: 세션 생성 시점에 특정 세션 ID 인자를 지정하지 않아 CLI 기본 동작인 "최근 대화 상속"이 실행됨. -* **C2. 워크스페이스 단위 키잉**: 대화 세션 매핑이 역할(role) 차원 없이 단순히 `workspace_root` 경로만을 키로 삼아 이뤄짐. -* **C3. mtime 기반 추측 바인딩 (Tier-2)**: resolver가 워크스페이스 내에서 최종 수정 시간(mtime)이 가장 최신인 세션을 바인딩하여, 다른 역할의 에이전트가 동일한 UUID를 상속받게 됨. - ---- - -## 2. 개정된 설계 방향: "단일 격리 디렉터리" 일원화 (Rev.3 정정 반영) - -각 에이전트의 ID 파라미터 지원 여부에 따라 구현을 분기하는 대신, **모든 에이전트에 대해 균일하게 격리 디렉터리 주입 방식으로 일원화**하여 아키텍처의 복잡도를 제거합니다. - -> ⚠️ **Rev.3 정정 (실측 근거)**: 이전 판의 "Claude = `CLAUDE_PROJECT_DIR` 격리"는 **동작하지 않는 설계**였습니다. `CLAUDE_PROJECT_DIR`은 MAM resolver의 **읽기 전용** 변수(`lib.sh:23,477`)로, claude CLI가 대화를 **쓰는** 위치를 바꾸지 못합니다. claude의 쓰기 위치 이동은 `CLAUDE_CONFIG_DIR`(`~/.claude` 지붕 전체 이동)로만 가능하며, 이 경우 auth/설정 시딩이 필수입니다(§2.3). 또한 cline은 실측 결과 per-session `HOME`이 아닌 **전용 `--data-dir`/`--config` 분리 플래그**를 보유해 시딩 없이 격리 가능합니다. - -```mermaid -graph TD - A[세션 생성] --> U[uuidgen: isolation-UUID 발급] - U --> B[.mam/agent_homes/<uuid>/ 생성] - B -->|Claude| B1[CLAUDE_CONFIG_DIR 주입 + auth/설정 심링크 시딩] - B -->|Cline| B2[--data-dir 격리 + --config 공유 auth] - B -->|Agy / Hermes| B3[Phase 0 프로브: 전용 레버 or HOME+시딩 폴백] - A --> C[Defense-in-depth: R1/R2 resolver 불변식] - B1 & B2 & B3 --> E[isolation 블록 세션 row 영속화 → resume/resolve/stop 재적용] -``` - -### 2.1 일원화 설계의 핵심 -* **격리 식별자 ≠ 대화 식별자**: MAM이 `uuidgen`으로 발급하는 **isolation-UUID는 디렉터리 식별자**입니다. CLI는 자기 방식대로 대화 ID를 mint하되(claude UUID, cline `epoch_rand` 등) **자기만의 격리 디렉터리 안에서** 하게 됩니다 — cline의 비-UUID 포맷 문제가 원천 소멸합니다. -* **작업 디렉터리(Cwd) 공유**: 에이전트들의 작업 디렉터리는 기존과 동일하게 같은 프로젝트 루트를 바라봅니다(`-c "$WORKSPACE"` 불변). 협업 소스코드 컨텍스트는 완벽히 일치하며, 격리는 **대화 상태 저장소의 위치만** 이동합니다. -* **격리 루트**: `/.mam/agent_homes//` — `.gitignore`(`.mam/`) 자동 커버, remove/stop 청소 계약에 자연 포함. -* **스키마 영속화**: 세션 row에 `isolation: {uuid, root, lever, seeded[]}` 블록을 `atomic_dump_yaml`로 영속화(DB+YAML). resume/resolve/stop은 이 블록만 읽는 **단일 디스패치 함수**를 경유 — agent별 레버 차이는 함수 내부에 캡슐화되어 관리 모델은 완전 통일됩니다. -* **근본 원인 해소 기전**: 신규 격리 디렉터리엔 상속할 최근 대화가 없음(C1 무해화) / UUID 네이밍으로 cwd-key 충돌 소멸(C2) / 디렉터리당 대화 1개 → resolver 항상 유일 후보(C3 소멸). - -### 2.2 agent별 격리 레버 매핑 — ✅ Phase 0 실측 확정 (2026-07-10) - -| Agent | Spawn 레버 | 시딩 (전부 **심링크**) | 격리 내 대화 경로 | 실증 | -|---|---|---|---|---| -| claude | `CLAUDE_CONFIG_DIR=` env | `.credentials.json`, `settings.json`, `plugins/` | `/projects//.jsonl` | ✅ 실호출 PASS | -| cline | `--data-dir ` 플래그 | `settings/*` + `globalState.json` (⚠️ `--config` 공유만으론 auth 미공유 — 실측 반증, 시딩 필수) | `/sessions//.json` (⚠️ 실HOME `data/sessions/`와 레이아웃 상이) | ✅ 실호출 PASS | -| agy | `HOME=` env | `~/.gemini/` auth 3종(`oauth_creds.json`, `google_accounts.json`, `antigravity-oauth-token`) + 메타(`installation_id`/`settings.json`/`state.json`) | `/.gemini/antigravity-cli/conversations/.db` | ✅ auth 검증 PASS (시딩 전 실패→후 성공) | -| hermes | `HOME=` env | `~/.hermes/{auth.json, config.yaml, .env}` | `/.hermes/state.db` | ✅ 읽기 격리 PASS ("No sessions found" + fresh state.db) | - -### 2.3 시딩 계약 (claude 및 HOME 폴백 agent) — 사용자 승인 조건 -* **심링크 강제, 복사 금지**: 복사 시 토큰 갱신이 격리 사본으로 발산해 원본과 어긋남. 심링크는 갱신이 원본 단일 파일에 수렴(현행 다중 인스턴스 동작과 동일 의미론). -* claude 시딩 목록(초안): `.credentials.json`, `settings.json`, `plugins/` — Phase 0에서 최종 확정, row의 `seeded[]`에 기록. -* stop 퍼지 시 **심링크 원본 무손상** 검증 포함. - -### 2.4 R1/R2 resolver 불변식 (2중 안전 장치) -* **R1**: resolver(`find_workspace_uuid` 등)가 최신 파일을 스캔해오기 전, 현재 실행 중인 다른 세션들이 소유한 `*_own` 대화 ID 집합을 후보군에서 제외(claimed-set filtering)합니다. -* **R2**: `atomic_dump` 시점에 새로 등록하려는 세션 ID가 이미 실행 중인 다른 세션의 ID와 중복될 경우 `SystemExit` 에러로 강제 진입 차단합니다. - -### 2.5 정리(Cleanup) 계약 (RC-2) -* 세션 정지(`stop_session.sh`) 시 `isolation.root`를 일괄 청소(`rm -rf`)하는 단순·명확한 클린업 규칙. `.mam/` 하위 배치로 `remove.sh` 전체 청소도 자동 커버. - -### 2.6 Non-Goals -* 에이전트 CLI(`claude`, `cline`, `agy`, `hermes`) 자체 바이너리/코드를 수정하지 않습니다. 구동 시 외부 환경변수·플래그 주입 인터페이스만 사용합니다. -* 기존 단일 에이전트 동작 구조의 하위 호환성은 완벽하게 보존합니다. - ---- - -## 3. 단계별 구현 계획 (Roadmap) - -**대전제: Phase 0 검증 게이트 통과 전에는 격리 주입(Phase 2 이후) 코드 구현에 착수하지 않습니다.** - -``` -Phase 0 (격리 레버 실측 및 검증 — G2 재조준) - ▼ -Phase 1 (R1/R2 공통 불변식 필터 — Phase 0 산출물 비의존, 병렬 선행 가능) - ▼ -Phase 2 (격리 프로비저닝·시딩·주입 및 isolation 스키마 영속화 구현) - ▼ -Phase 3 (stop_session.sh 클린업 계약 연동 구현) - ▼ -Phase 4 (통합 및 회귀 검증) -``` - -### Phase 0 — 격리 레버 실측 (구현 전 필수 실측) -* **G2-claude**: `CLAUDE_CONFIG_DIR=<격리경로>` 기동 시 (a) 대화 jsonl이 `<격리경로>/projects//`에 생성 (b) `.credentials.json` **심링크만으로 로그인 유지** (c) settings/plugins 심링크로 행동 드리프트 없음. -* **G2-cline**: `--data-dir <격리경로> --config ~/.cline/data/settings` 기동 시 (a) 세션이 격리경로에 생성 (b) 공유 auth 정상 동작. -* **G2-agy / G2-hermes**: 전용 레버(project/home env) 실측, 부재 시 `HOME` 오버라이드+auth 시딩 유효성. -* **DoD**: `{agent × (레버, 시딩 목록, 대화 저장 실경로)}` 매트릭스 확정 → §2.2 갱신. - -### Phase 1 — 공통 불변식 구현 (전략 무관, 선행 가능) -* *의존성 참고*: Phase 1은 격리 프로브 결과에 의존하지 않고 공통 `lib.sh`에만 적용되므로, **Phase 0 완료 여부와 무관하게 병렬로 또는 선제적으로 구현할 수 있습니다.** -* **T1. claimed-set 필터 구현**: `lib.sh` (`find_workspace_uuid` 계열) 탐색 로직 수정. 후보군 중 다른 실행 중인 row의 `*_own`을 필터링 아웃. -* **T2. 생성-시 중복 assertion**: 세션 등록/덤프 로직 부근에서 중복 assert — 중복 ID 충돌 시 즉시 거부. -* **DoD**: 동일 대화 ID 강제 주입으로 세션 2개 생성 시도 시, 두 번째 생성 요청이 거부됨을 증명. - -### Phase 2 — 격리 프로비저닝 및 영속화 구현 (전체 에이전트 적용) -* **T3. 격리 프로비저닝**: create 시 isolation-UUID 발급 → `.mam/agent_homes//` 생성 → agent별 심링크 시딩(§2.3). -* **T4. spawn 주입**: 디스패치 함수가 agent별 레버(§2.2: `CLAUDE_CONFIG_DIR` / `--data-dir` / 프로브 결과)로 격리 루트 주입. -* **T5. 스키마 영속화**: `isolation` 블록을 row에 저장하고 resume/resolve 시 재소싱 적용 — **저장+재적용은 원자적 세트**. -* **DoD**: Claude / Cline 세션 각각 2개 동시 생성 시 대화 파일 물리 분리·캐시 비공유, resume 시 올바른 복원 확인. - -### Phase 3 — stop 정리 계약 확장 -* **T6. stop 정리 계약 확장**: `stop_session.sh`가 `isolation.root`를 자동 퍼지(`rm -rf`), **심링크 원본 무손상 검증** 포함. -* **DoD**: stop 후 격리 디렉터리 잔존 0, 실HOME auth/설정 원본 무손상, 디스크 누수 없음. - -### Phase 4 — 통합 및 회귀 검증 -* **V1. 다중 기동 테스트**: planner(claude), reviewer-a(claude), developer(cline), reviewer-b(cline) 4개 동시 기동 시 4개 세션 ID 모두 유일성 확보 검증. -* **V2. 동시 쓰기 경합**: 4개 에이전트 동시 동작 시 락 경합/데이터 유실 현상 재현 불가 확인. -* **V3. 단일 세션 회귀 검증**: 격리 정책 적용 후 기존 단일 에이전트 구동 환경에서 문제없이 정상 동작함을 검증. - ---- - -## 4. 리스크 및 검수 포인트 (Reviewer 관점, Rev.3 갱신) - -| ID | 리스크 | 완화책 | -|----|--------|------| -| **RK1** | 격리 경로 주입 후 resolve/resume 시 전역 기본 경로 스캔으로 회귀 | `isolation` 블록 저장과 resume 시 재적용을 원자적 세트로 묶고 단일 디스패치 함수 강제 | -| **RK2** | **시딩 드리프트**: CLI 업데이트로 신규 파일 등장 시 심링크 목록 누락 → 격리 인스턴스 행동 이상 | `seeded[]`를 row에 기록, Phase 0 매트릭스에 시딩 파일 목록 명세 | -| **RK3** | **토큰 갱신 발산**: auth 파일을 복사 시딩하면 격리 사본의 토큰 갱신이 원본과 어긋남 | **심링크 강제** — 갱신이 원본 단일 파일에 수렴 | -| **RK4** | 비정상 종료 시 격리 디렉터리 미정리로 인한 디스크 누수 | `.mam/` 하위 배치(remove.sh 커버) + stop 퍼지 + 고아 `agent_homes/*` GC(선택) | -| **RK5** | 단일 에이전트 워크플로우 기존 사용자의 하위 호환성 회귀 | 격리 활성화를 세션 다중성 조건 혹은 명시적 플래그(`--isolate-strict`)로 제어, V3 회귀 게이트 | - ---- - -## 5. 의사결정 및 다음 단계 - -* ✅ 모든 에이전트를 격리 디렉터리 방식으로 일원화하는 방향 최종 승인 (트레이드오프 — claude `--session-id` 실측 확정 레버의 미채택 — 인지 후 결정). -* ✅ 승인 조건 반영: (1) Phase 0에 claude `CLAUDE_CONFIG_DIR`+심링크 로그인 유지 프로브 포함, (2) 시딩 계약(§2.3) 명문화. -* ⏭️ 승인에 따라 **Phase 0 (격리 레버 실측)** 및 **Phase 1 (공통 불변식 필터)** 태스크에 착수합니다. Phase 2 이후 구현은 Phase 0 매트릭스 확정 후 진행합니다. diff --git a/task.md b/task.md deleted file mode 100644 index b01924c..0000000 --- a/task.md +++ /dev/null @@ -1,40 +0,0 @@ -# Task Checklist — 배포 스크립트 URL 파라미터화 (Rev.1) - -> 기준 문서: [implementation_plan.md](implementation_plan.md) (Rev.1) -> 담당: Developer Agent | 순서대로 수행하며 완료 시 `[x]` 갱신 - -## Phase 1 — 코드 수정 - -- [ ] **T1. `deploy/install.sh` 파라미터화** (§3.1) - - 57행: `REPO_URL="${MAM_REPO_URL:-https://git.godopu.com/tmpl/multi-agent-mux.git}"` - - 58행: `ARCHIVE_URL="${MAM_ARCHIVE_URL:-https://git.godopu.com/tmpl/multi-agent-mux/archive/main.tar.gz}"` -- [ ] **T2. `deploy/update.sh` 파라미터화** (§3.2) - - 138행: `INSTALLER_URL="${MAM_INSTALLER_URL:-https://git.godopu.com/tmpl/multi-agent-mux/raw/branch/main/deploy/install.sh}"` - - 체이닝 상속 계약(접두 대입 → 자식 bash 상속) 주석 1줄 추가 - -## Phase 2 — 문서화 - -- [ ] **T3. `.env.example`에 `# deploy / distribution source` 섹션 추가** (§3.3) - - `MAM_REPO_URL` / `MAM_ARCHIVE_URL` / `MAM_INSTALLER_URL` 3종, 기존 `#default:` 서식 준수 - - "deploy 스크립트는 `.env`를 파싱하지 않음 — export/접두 대입으로 전달" 주의 문구 포함 - - 미러 운영 시 3변수 동시 설정 권고 문구 포함 (§3.5) -- [ ] **T4. `deploy/README.md`에 미러/포크 설치·업데이트 예시 추가** (§3.6) - - 파이프 실행 시 접두 대입을 `bash` 쪽에 붙이는 예시 포함 - -## Phase 3 — 검증 (plan §5, DoD) - -- [ ] **V1.** `bash -n deploy/install.sh deploy/update.sh` 통과 -- [ ] **V2.** `shellcheck deploy/install.sh deploy/update.sh` 신규 경고 0 -- [ ] **V3.** 기본값 3개가 변경 전 하드코딩 문자열과 byte-identical (grep 대조) -- [ ] **V4.** 스크래치 디렉터리에서 `MAM_ARCHIVE_URL` 오버라이드가 fetch에 반영됨 확인 -- [ ] **V5.** `MAM_INSTALLER_URL` 오버라이드 해석값 확인 (실 워크스페이스 파괴적 실행 금지) -- [ ] **V6.** 리포 루트 재실행 회귀: fetch 생략 경로 정상 동작 -- [ ] **V7.** 문서(.env.example / deploy/README.md)-코드 간 변수명 철자 교차 대조 - -## Phase 4 — 마감 - -- [ ] **T5.** 단일 원자적 커밋: `feat(deploy): parameterize distribution URLs via MAM_*_URL env vars` -- [ ] **T6.** Reviewer A / Reviewer B에 변경 범위 통지 및 이중 리뷰 요청 -- [ ] **T7.** 양측 PASS 확인 후 세션 종료 (`multi-agent-mux-stop`) / NOT PASS 시 Planner로 환류 - -agy --conversation=20cc2d8e-49f1-4a83-96b5-c49d320b42af \ No newline at end of file diff --git a/task.session_isolation.md b/task.session_isolation.md index 244120a..823988c 100644 --- a/task.session_isolation.md +++ b/task.session_isolation.md @@ -1,6 +1,6 @@ # Task Checklist — 세션 ID 격리 (Rev.3) -> 기준 문서: [implementation_plan.session_isolation.md](implementation_plan.session_isolation.md) (Rev.3) / [session_isolation_discussion.md](session_isolation_discussion.md) +> 기준 문서: [implementation_plan.session_isolation.md](implementation_plan.session_isolation.md) (Rev.3) > 담당: Developer Agent | 순서대로 수행하며 완료 시 `[x]` 갱신 > **대전제: Phase 0 매트릭스 확정 전에는 Phase 2 이후 구현 착수 금지. Phase 1은 병렬 선행 가능.**