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/
2026-07-11 08:50:30 +09:00
parent 1c2ce0953d
commit 9b831932b0
8 changed files with 295 additions and 312 deletions
@@ -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 <scratch-dir>`
-   실행 → 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 시 마감.