diff --git a/.gitignore b/.gitignore index d12fe74a..a985036f 100644 --- a/.gitignore +++ b/.gitignore @@ -22,8 +22,6 @@ Thumbs.db key.properties # Agent/local scratch -agent-task/ -agent-task/archive/ agent-ops/rules/private/ # Dart / Flutter diff --git a/agent-task/m-runtime-baseline/01_source_snapshots/CODE_REVIEW-cloud-G08.md b/agent-task/m-runtime-baseline/01_source_snapshots/CODE_REVIEW-cloud-G08.md new file mode 100644 index 00000000..b7b47af0 --- /dev/null +++ b/agent-task/m-runtime-baseline/01_source_snapshots/CODE_REVIEW-cloud-G08.md @@ -0,0 +1,147 @@ + + +# Code Review Reference - UPSTREAM + +> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.** +> The task is NOT complete until every implementation-owned section below is filled in. +> Complete the `구현 체크리스트`; the final checklist item is mandatory before saving. +> Fill implementation-owned sections, then stop with active files in place and report ready for review. +> Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume. +> Follow the ownership table at the bottom of this file for which sections you own. + +## 개요 + +date=2026-05-28 +task=m-runtime-baseline/01_source_snapshots, plan=0, tag=UPSTREAM + +## 이 파일을 읽는 리뷰 에이전트에게 + +> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다. + +각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요. +리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다. + +1. 판정을 append한다. +2. `CODE_REVIEW-cloud-G08.md` -> `code_review_cloud_G08_N.log`, `PLAN-cloud-G08.md` -> `plan_cloud_G08_M.log`로 아카이브한다. +3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-runtime-baseline/01_source_snapshots/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다. `USER_REVIEW.md`가 사용자 결정으로 완료/PASS 해소되면 code-review가 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log` 작성 후 archive 이동한다. +4. PASS이고 task group이 `m-`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다. +5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다. + +--- + +## 구현 항목별 완료 여부 + +| 항목 | 완료 여부 | +|------|---------| +| [UPSTREAM-1] Staging Sources And Records | [ ] | +| [UPSTREAM-2] Source Snapshot Copy | [ ] | +| [UPSTREAM-3] Workspace Index Sync | [ ] | + +## 구현 체크리스트 + +- [ ] 외부 staging clone 경로를 `MATTERMOST_APP_STAGING`와 `MATTERMOST_PUSH_PROXY_STAGING`로 받아 두 clone이 `main` branch인지 확인한다. +- [ ] staging clone의 remote URL과 commit SHA를 기준으로 `apps/mattermost/UPSTREAM.md`와 `services/push-proxy/UPSTREAM.md`를 작성한다. +- [ ] `.git`, build/cache/runtime 산출물을 제외하고 `apps/mattermost/`와 `services/push-proxy/` source snapshot을 반입한다. +- [ ] root/doc index가 실제 snapshot 상태와 어긋나면 `README.md`와 `docs/README.md`만 최소 갱신한다. +- [ ] 최종 검증 명령을 실행하고 출력에 두 snapshot 경로, upstream record, branch `main`, commit SHA가 보이는지 확인한다. +- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다. + +## 코드리뷰 전용 체크리스트 + +> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다. +> 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다. + +- [ ] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다. +- [ ] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다. +- [ ] active `CODE_REVIEW-*-G??.md`를 `code_review_cloud_G08_N.log`로 아카이브한다. +- [ ] active `PLAN-*-G??.md`를 `plan_cloud_G08_M.log`로 아카이브한다. +- [ ] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다. +- [ ] PASS이면 active task 디렉터리 `agent-task/m-runtime-baseline/01_source_snapshots/`를 `agent-task/archive/YYYY/MM/m-runtime-baseline/01_source_snapshots/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다. +- [ ] PASS이고 task group이 `m-`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다. +- [ ] PASS split 작업이면 이동 후 빈 active parent `agent-task/m-runtime-baseline/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다. +- [ ] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-cloud-G08.md`와 `CODE_REVIEW-cloud-G08.md`를 작성하고 `complete.log`를 작성하지 않는다. +- [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다. +- [ ] USER_REVIEW가 사용자 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다. + +## 계획 대비 변경 사항 + +_구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께 기록한다._ + +## 주요 설계 결정 + +_구현 에이전트가 주요 설계 결정 사항을 기록한다._ + +## 리뷰어를 위한 체크포인트 + +- source snapshot 안에 `.git`, dependency cache, build output이 들어오지 않았는지 확인한다. +- `UPSTREAM.md`의 URL, branch, commit SHA가 staging clone 실제 출력과 일치하는지 확인한다. +- `services/core/UPSTREAM.md` baseline 값이 변경되지 않았는지 확인한다. +- nexo-specific patch가 upstream snapshot 내부에 섞이지 않았는지 확인한다. + +## 검증 결과 + +_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._ + +필수 규칙: +- 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다. +- 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다. +- `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다. + +### UPSTREAM-1 중간 검증 +``` +$ test -f apps/mattermost/UPSTREAM.md +$ test -f services/push-proxy/UPSTREAM.md +$ rg --sort path -n "Source:|Branch:|Snapshot commit:|Snapshot date:|Snapshot source:" apps/mattermost/UPSTREAM.md services/push-proxy/UPSTREAM.md +(output) +``` + +### UPSTREAM-2 중간 검증 +``` +$ test -d apps/mattermost +$ test -d services/push-proxy +$ test ! -d apps/mattermost/.git +$ test ! -d services/push-proxy/.git +$ git status --short apps/mattermost services/push-proxy .gitignore +(output) +``` + +### UPSTREAM-3 중간 검증 +``` +$ rg --sort path -n "apps/mattermost|services/push-proxy|UPSTREAM.md|reserved|Snapshot" README.md docs/README.md apps/mattermost/UPSTREAM.md services/push-proxy/UPSTREAM.md +(output) +``` + +### 최종 검증 +``` +$ test -n "$MATTERMOST_APP_STAGING" +$ test -n "$MATTERMOST_PUSH_PROXY_STAGING" +$ test "$(git -C "$MATTERMOST_APP_STAGING" rev-parse --abbrev-ref HEAD)" = main +$ test "$(git -C "$MATTERMOST_PUSH_PROXY_STAGING" rev-parse --abbrev-ref HEAD)" = main +$ test -d apps/mattermost +$ test -d services/push-proxy +$ test -f apps/mattermost/UPSTREAM.md +$ test -f services/push-proxy/UPSTREAM.md +$ rg --sort path -n "Source:|Branch:|Snapshot commit:|Snapshot date:|Snapshot source:" apps/mattermost/UPSTREAM.md services/push-proxy/UPSTREAM.md +$ git status --short apps/mattermost services/push-proxy README.md docs/README.md .gitignore +$ git diff --check +(output) +``` + +--- + +> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?** +> If anything is blank, go back and fill it in before saving this file. +> Leave review-agent-only sections unchanged. + +Sections and their ownership: + +| Section | Owner | Note | +|---------|-------|------| +| Header comment, 개요, 리뷰 에이전트 지시 | Fixed at stub creation | Implementing agent must not modify or execute these (archive, complete.log, and task-directory archive move are review-agent only) | +| 구현 항목별 완료 여부 (item names) | Fixed at stub creation | Implementing agent checks `[ ]` -> `[x]` only | +| 구현 체크리스트 (item text/order) | Fixed at stub creation from plan | Implementing agent checks `[ ]` -> `[x]` only; final checkbox is mandatory before saving | +| 코드리뷰 전용 체크리스트 | Review agent only | Implementing agent must not modify or check this section | +| 계획 대비 변경 사항, 주요 설계 결정 | Implementing agent | Replace placeholder text with actual content | +| 리뷰어를 위한 체크포인트 | Fixed at stub creation | Pre-filled from plan | +| 검증 결과 (section headings + commands) | Fixed at stub creation | Implementing agent fills in command output only; command changes require a `계획 대비 변경 사항` entry | +| 코드리뷰 결과 | Review agent appends | Not included in stub | diff --git a/agent-task/m-runtime-baseline/01_source_snapshots/PLAN-cloud-G08.md b/agent-task/m-runtime-baseline/01_source_snapshots/PLAN-cloud-G08.md new file mode 100644 index 00000000..449d2b3d --- /dev/null +++ b/agent-task/m-runtime-baseline/01_source_snapshots/PLAN-cloud-G08.md @@ -0,0 +1,220 @@ + + +# Plan - UPSTREAM Source Snapshots + +## 이 파일을 읽는 구현 에이전트에게 + +구현이 끝나면 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 검증 명령을 실행하고 실제 stdout/stderr를 기록한 뒤 active 파일을 그대로 두고 리뷰 준비를 보고한다. 최종 archive, `complete.log`, 코드리뷰 판정은 code-review 스킬 전용이다. + +## 배경 + +현재 Milestone은 Mattermost 앱, 서버, push-proxy를 원본 repository clone 단위로 유지하는 방향을 이미 정했다. `services/core/`에는 upstream 기록이 있지만 `apps/mattermost/`와 `services/push-proxy/`는 아직 source snapshot 경로가 없다. 이 작업은 외부 staging clone에서 검토된 snapshot을 들여오고 각 snapshot의 upstream 기록을 남기는 큰 작업이다. + +## 분석 결과 + +### 읽은 파일 + +- `agent-roadmap/current.md` +- `agent-roadmap/phase/product-foundation/PHASE.md` +- `agent-roadmap/phase/product-foundation/milestones/runtime-baseline.md` +- `README.md` +- `docs/README.md` +- `.gitignore` +- `services/core/UPSTREAM.md` +- `services/core/compose/README.md` +- `services/core/compose/.env.example` +- `services/core/compose/docker-compose.yml` + +### 테스트 커버리지 공백 + +- `apps/mattermost/` snapshot 반입: 기존 테스트 없음. staging clone branch, commit SHA, source path, copied target existence를 명령 출력으로 검증한다. +- `services/push-proxy/` snapshot 반입: 기존 테스트 없음. staging clone branch, commit SHA, source path, copied target existence를 명령 출력으로 검증한다. +- upstream record 작성: 기존 테스트 없음. `rg --sort path`로 필수 필드가 두 `UPSTREAM.md`에 있는지 확인한다. + +### 심볼 참조 + +none. 이 작업은 코드 symbol rename/remove를 하지 않는다. + +### 분할 판단 + +split decision policy를 먼저 평가했다. shared task group은 `m-runtime-baseline`이다. + +- `01_source_snapshots`: 외부 staging clone과 대량 upstream source snapshot을 다루는 작업. 독립 실행 가능. +- `02_runtime_smoke`: Docker/SSH runtime smoke 작업. source snapshot 반입과 다른 실행 환경 리스크를 가지므로 별도 sibling으로 둔다. + +두 sibling 사이에 런타임 선행 의존성은 없다. + +### 범위 결정 근거 + +이 작업은 `apps/mattermost/`, `services/push-proxy/`, 각 module-local `UPSTREAM.md`, 필요 시 root/doc index만 다룬다. `services/core/UPSTREAM.md`의 baseline 값은 바꾸지 않는다. push-proxy local build 전환, compose image 교체, FCM/APNS credential smoke, nginx/TLS, 제품 앱 UI는 이 계획 범위 밖이다. + +### 빌드 등급 + +build=`cloud-G08`, review=`cloud-G08`. 외부 git staging clone, 대량 snapshot, 약한 자동 테스트, upstream 경계 보존이 모두 걸린 작업이다. + +## 구현 체크리스트 + +- [ ] 외부 staging clone 경로를 `MATTERMOST_APP_STAGING`와 `MATTERMOST_PUSH_PROXY_STAGING`로 받아 두 clone이 `main` branch인지 확인한다. +- [ ] staging clone의 remote URL과 commit SHA를 기준으로 `apps/mattermost/UPSTREAM.md`와 `services/push-proxy/UPSTREAM.md`를 작성한다. +- [ ] `.git`, build/cache/runtime 산출물을 제외하고 `apps/mattermost/`와 `services/push-proxy/` source snapshot을 반입한다. +- [ ] root/doc index가 실제 snapshot 상태와 어긋나면 `README.md`와 `docs/README.md`만 최소 갱신한다. +- [ ] 최종 검증 명령을 실행하고 출력에 두 snapshot 경로, upstream record, branch `main`, commit SHA가 보이는지 확인한다. +- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다. + +### [UPSTREAM-1] Staging Sources And Records + +#### 문제 + +`README.md:22`와 `README.md:24`는 `apps/mattermost/`와 `services/push-proxy/`를 original repository clone 경계로 예약하지만 실제 경로가 없다. `docs/README.md:15`는 snapshot 도입 시 module-local upstream record를 추가하라고 남겨 두었다. Milestone의 `[push-proxy-source]`도 `agent-roadmap/phase/product-foundation/milestones/runtime-baseline.md:64`에서 미완료다. + +#### 해결 방법 + +외부 staging clone을 source of truth로 삼는다. 구현 에이전트는 URL을 추정하지 말고 아래 환경 변수를 받아 확인한다. + +```sh +test -n "$MATTERMOST_APP_STAGING" +test -n "$MATTERMOST_PUSH_PROXY_STAGING" +test "$(git -C "$MATTERMOST_APP_STAGING" rev-parse --abbrev-ref HEAD)" = main +test "$(git -C "$MATTERMOST_PUSH_PROXY_STAGING" rev-parse --abbrev-ref HEAD)" = main +``` + +각 target에 다음 형식의 `UPSTREAM.md`를 추가한다. + +```markdown +# Upstream + +`/` is derived from the repository. + +- Source: `` +- Branch: `main` +- Snapshot commit: `` +- Snapshot date: `2026-05-28` +- Snapshot source: `` + +Keep nexo-specific changes outside this snapshot where possible. +``` + +#### 수정 파일 및 체크리스트 + +- [ ] `apps/mattermost/UPSTREAM.md`를 추가한다. +- [ ] `services/push-proxy/UPSTREAM.md`를 추가한다. +- [ ] `services/core/UPSTREAM.md`는 수정하지 않는다. + +#### 테스트 작성 + +테스트 파일은 작성하지 않는다. 이 항목은 source provenance 기록이며 검증은 git command와 record field 확인으로 수행한다. + +#### 중간 검증 + +```sh +test -f apps/mattermost/UPSTREAM.md +test -f services/push-proxy/UPSTREAM.md +rg --sort path -n "Source:|Branch:|Snapshot commit:|Snapshot date:|Snapshot source:" apps/mattermost/UPSTREAM.md services/push-proxy/UPSTREAM.md +``` + +### [UPSTREAM-2] Source Snapshot Copy + +#### 문제 + +`README.md:76`과 `README.md:78`는 snapshot target path를 문서화하지만 현재 repository에는 `apps/mattermost/`와 `services/push-proxy/`가 없다. snapshot이 없으면 push-proxy는 `services/core/compose/docker-compose.yml:57`부터 `latest` image runtime 참조만 남는다. + +#### 해결 방법 + +staging clone에서 source snapshot을 복사한다. `.git`, dependency cache, build output, runtime data는 제외한다. upstream repository 구조는 재배치하지 않는다. + +```sh +rsync -a --delete \ + --exclude .git \ + --exclude node_modules \ + --exclude dist \ + --exclude build \ + "$MATTERMOST_APP_STAGING"/ apps/mattermost/ + +rsync -a --delete \ + --exclude .git \ + --exclude node_modules \ + --exclude dist \ + --exclude build \ + "$MATTERMOST_PUSH_PROXY_STAGING"/ services/push-proxy/ +``` + +필요한 경우 `.gitignore`에는 새 snapshot에서 생성될 build/cache/runtime 산출물만 추가한다. source file을 ignore하지 않는다. + +#### 수정 파일 및 체크리스트 + +- [ ] `apps/mattermost/` source snapshot을 반입한다. +- [ ] `services/push-proxy/` source snapshot을 반입한다. +- [ ] 필요 시 `.gitignore`에 build/cache/runtime 산출물 예외만 추가한다. +- [ ] source snapshot 안에서 nexo-specific rename이나 formatting-only churn을 하지 않는다. + +#### 테스트 작성 + +테스트 파일은 작성하지 않는다. upstream source snapshot 반입은 기존 테스트 suite를 실행하기보다 snapshot provenance와 git status 범위를 검증한다. + +#### 중간 검증 + +```sh +test -d apps/mattermost +test -d services/push-proxy +test ! -d apps/mattermost/.git +test ! -d services/push-proxy/.git +git status --short apps/mattermost services/push-proxy .gitignore +``` + +### [UPSTREAM-3] Workspace Index Sync + +#### 문제 + +`docs/README.md:15`부터 `docs/README.md:17`는 snapshot record가 도입될 때 module-local upstream record를 추가하라고 말한다. snapshot 반입 후에도 root/doc index가 reserved 상태로 남으면 runtime baseline 문서와 실제 source tree가 어긋난다. + +#### 해결 방법 + +snapshot 반입 후 `README.md`와 `docs/README.md`에서 "reserved" 표현이 실제 상태와 충돌하는지 확인한다. 충돌하는 경우만 "is the original ... repository snapshot"처럼 현재형으로 바꾼다. + +#### 수정 파일 및 체크리스트 + +- [ ] 필요 시 `README.md`의 `apps/mattermost/`와 `services/push-proxy/` 설명을 snapshot 도입 상태로 갱신한다. +- [ ] 필요 시 `docs/README.md`의 pending 문장을 실제 upstream record 링크로 갱신한다. +- [ ] `agent-roadmap/**`는 구현 에이전트가 직접 완료 처리하지 않는다. PASS 후 runtime/update-roadmap 경로가 처리한다. + +#### 테스트 작성 + +테스트 파일은 작성하지 않는다. 문서 index 정합성은 deterministic search로 확인한다. + +#### 중간 검증 + +```sh +rg --sort path -n "apps/mattermost|services/push-proxy|UPSTREAM.md|reserved|Snapshot" README.md docs/README.md apps/mattermost/UPSTREAM.md services/push-proxy/UPSTREAM.md +``` + +## 수정 파일 요약 + +| 파일 | 항목 | +| --- | --- | +| `apps/mattermost/UPSTREAM.md` | UPSTREAM-1 | +| `services/push-proxy/UPSTREAM.md` | UPSTREAM-1 | +| `apps/mattermost/**` | UPSTREAM-2 | +| `services/push-proxy/**` | UPSTREAM-2 | +| `.gitignore` | UPSTREAM-2 | +| `README.md` | UPSTREAM-3 | +| `docs/README.md` | UPSTREAM-3 | + +## 최종 검증 + +```sh +test -n "$MATTERMOST_APP_STAGING" +test -n "$MATTERMOST_PUSH_PROXY_STAGING" +test "$(git -C "$MATTERMOST_APP_STAGING" rev-parse --abbrev-ref HEAD)" = main +test "$(git -C "$MATTERMOST_PUSH_PROXY_STAGING" rev-parse --abbrev-ref HEAD)" = main +test -d apps/mattermost +test -d services/push-proxy +test -f apps/mattermost/UPSTREAM.md +test -f services/push-proxy/UPSTREAM.md +rg --sort path -n "Source:|Branch:|Snapshot commit:|Snapshot date:|Snapshot source:" apps/mattermost/UPSTREAM.md services/push-proxy/UPSTREAM.md +git status --short apps/mattermost services/push-proxy README.md docs/README.md .gitignore +git diff --check +``` + +Expected outcome: both staging clones are on `main`, both target directories and `UPSTREAM.md` files exist, required upstream fields are present, and `git diff --check` reports no whitespace errors. + +모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다. diff --git a/agent-task/m-runtime-baseline/02_runtime_smoke/CODE_REVIEW-cloud-G07.md b/agent-task/m-runtime-baseline/02_runtime_smoke/CODE_REVIEW-cloud-G07.md new file mode 100644 index 00000000..430ad041 --- /dev/null +++ b/agent-task/m-runtime-baseline/02_runtime_smoke/CODE_REVIEW-cloud-G07.md @@ -0,0 +1,159 @@ + + +# Code Review Reference - SMOKE + +> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.** +> The task is NOT complete until every implementation-owned section below is filled in. +> Complete the `구현 체크리스트`; the final checklist item is mandatory before saving. +> Fill implementation-owned sections, then stop with active files in place and report ready for review. +> Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume. +> Follow the ownership table at the bottom of this file for which sections you own. + +## 개요 + +date=2026-05-28 +task=m-runtime-baseline/02_runtime_smoke, plan=0, tag=SMOKE + +## 이 파일을 읽는 리뷰 에이전트에게 + +> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다. + +각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요. +리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다. + +1. 판정을 append한다. +2. `CODE_REVIEW-cloud-G07.md` -> `code_review_cloud_G07_N.log`, `PLAN-cloud-G07.md` -> `plan_cloud_G07_M.log`로 아카이브한다. +3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-runtime-baseline/02_runtime_smoke/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다. `USER_REVIEW.md`가 사용자 결정으로 완료/PASS 해소되면 code-review가 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log` 작성 후 archive 이동한다. +4. PASS이고 task group이 `m-`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다. +5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다. + +--- + +## 구현 항목별 완료 여부 + +| 항목 | 완료 여부 | +|------|---------| +| [SMOKE-1] Local Compose Runtime | [ ] | +| [SMOKE-2] Remote Parity | [ ] | + +## 구현 체크리스트 + +- [ ] `command -v docker`, `docker compose version`, `docker info`로 Docker 실행 가능성을 확인한다. +- [ ] `services/core/compose`에서 `.env`를 git 밖에 준비하고 `docker compose config`가 성공하는지 확인한다. +- [ ] `docker compose up -d` 후 core ping, Mattermost app HEAD, db readiness, push-proxy service/config smoke를 실행한다. 검증: `cd services/core/compose && docker compose up -d` 후 core ping과 Mattermost 앱 접근이 성공한다. +- [ ] `NEXO_REMOTE_HOST`를 사용해 원격 `~/docker/services/nexo/compose`의 `docker-compose.yml`과 `.env.example` hash가 local과 일치하는지 확인한다. 검증: local/remote compose와 `.env.example` hash 비교가 일치한다. +- [ ] smoke 실패가 repo 설정 문제로 확인될 때만 compose 파일이나 README를 최소 수정하고 같은 smoke를 재실행한다. +- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다. + +## 코드리뷰 전용 체크리스트 + +> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다. +> 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다. + +- [ ] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다. +- [ ] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다. +- [ ] active `CODE_REVIEW-*-G??.md`를 `code_review_cloud_G07_N.log`로 아카이브한다. +- [ ] active `PLAN-*-G??.md`를 `plan_cloud_G07_M.log`로 아카이브한다. +- [ ] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다. +- [ ] PASS이면 active task 디렉터리 `agent-task/m-runtime-baseline/02_runtime_smoke/`를 `agent-task/archive/YYYY/MM/m-runtime-baseline/02_runtime_smoke/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다. +- [ ] PASS이고 task group이 `m-`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다. +- [ ] PASS split 작업이면 이동 후 빈 active parent `agent-task/m-runtime-baseline/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다. +- [ ] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-cloud-G07.md`와 `CODE_REVIEW-cloud-G07.md`를 작성하고 `complete.log`를 작성하지 않는다. +- [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다. +- [ ] USER_REVIEW가 사용자 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다. + +## 계획 대비 변경 사항 + +_구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께 기록한다._ + +## 주요 설계 결정 + +_구현 에이전트가 주요 설계 결정 사항을 기록한다._ + +## 리뷰어를 위한 체크포인트 + +- Docker daemon 부재나 port collision을 repo 설정 문제로 오판하지 않았는지 확인한다. +- `.env`와 `services/core/data/`가 git에 포함되지 않았는지 확인한다. +- local/remote `sha256sum` 출력이 실제로 일치하는지 확인한다. +- smoke 실패로 수정한 compose/doc 변경이 최소 범위인지 확인한다. + +## 검증 결과 + +_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._ + +필수 규칙: +- 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다. +- 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다. +- `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다. + +### SMOKE-1 중간 검증 +``` +$ cd services/core/compose +$ command -v docker +$ docker compose version +$ docker info +$ docker compose config +$ docker compose up -d +$ curl -fsS "http://localhost:${NEXO_CORE_PORT:-18065}/api/v4/system/ping" +$ docker compose exec db pg_isready -U mmuser -d mattermost +$ curl -fsSI "http://localhost:${NEXO_CORE_PORT:-18065}" +$ docker compose ps push-proxy +$ docker compose config | rg --fixed-strings "MM_EMAILSETTINGS_PUSHNOTIFICATIONSERVER=http://push-proxy:8066" +(output) +``` + +### SMOKE-2 중간 검증 +``` +$ test -n "$NEXO_REMOTE_HOST" +$ cd services/core/compose +$ sha256sum docker-compose.yml .env.example +$ ssh "$NEXO_REMOTE_HOST" 'cd ~/docker/services/nexo/compose && sha256sum docker-compose.yml .env.example' +$ ssh "$NEXO_REMOTE_HOST" 'cd ~/docker/services/nexo/compose && docker compose config' +$ ssh "$NEXO_REMOTE_HOST" 'cd ~/docker/services/nexo/compose && docker compose ps' +$ ssh "$NEXO_REMOTE_HOST" 'curl -fsS "http://localhost:${NEXO_CORE_PORT:-18065}/api/v4/system/ping"' +(output) +``` + +### 최종 검증 +``` +$ cd services/core/compose +$ command -v docker +$ docker compose version +$ docker info +$ docker compose config +$ docker compose up -d +$ curl -fsS "http://localhost:${NEXO_CORE_PORT:-18065}/api/v4/system/ping" +$ docker compose exec db pg_isready -U mmuser -d mattermost +$ curl -fsSI "http://localhost:${NEXO_CORE_PORT:-18065}" +$ docker compose ps push-proxy +$ docker compose config | rg --fixed-strings "MM_EMAILSETTINGS_PUSHNOTIFICATIONSERVER=http://push-proxy:8066" +$ test -n "$NEXO_REMOTE_HOST" +$ sha256sum docker-compose.yml .env.example +$ ssh "$NEXO_REMOTE_HOST" 'cd ~/docker/services/nexo/compose && sha256sum docker-compose.yml .env.example' +$ ssh "$NEXO_REMOTE_HOST" 'cd ~/docker/services/nexo/compose && docker compose config' +$ ssh "$NEXO_REMOTE_HOST" 'cd ~/docker/services/nexo/compose && docker compose ps' +$ ssh "$NEXO_REMOTE_HOST" 'curl -fsS "http://localhost:${NEXO_CORE_PORT:-18065}/api/v4/system/ping"' +$ cd ../../.. +$ git status --short services/core/compose +$ git diff --check +(output) +``` + +--- + +> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?** +> If anything is blank, go back and fill it in before saving this file. +> Leave review-agent-only sections unchanged. + +Sections and their ownership: + +| Section | Owner | Note | +|---------|-------|------| +| Header comment, 개요, 리뷰 에이전트 지시 | Fixed at stub creation | Implementing agent must not modify or execute these (archive, complete.log, and task-directory archive move are review-agent only) | +| 구현 항목별 완료 여부 (item names) | Fixed at stub creation | Implementing agent checks `[ ]` -> `[x]` only | +| 구현 체크리스트 (item text/order) | Fixed at stub creation from plan | Implementing agent checks `[ ]` -> `[x]` only; final checkbox is mandatory before saving | +| 코드리뷰 전용 체크리스트 | Review agent only | Implementing agent must not modify or check this section | +| 계획 대비 변경 사항, 주요 설계 결정 | Implementing agent | Replace placeholder text with actual content | +| 리뷰어를 위한 체크포인트 | Fixed at stub creation | Pre-filled from plan | +| 검증 결과 (section headings + commands) | Fixed at stub creation | Implementing agent fills in command output only; command changes require a `계획 대비 변경 사항` entry | +| 코드리뷰 결과 | Review agent appends | Not included in stub | diff --git a/agent-task/m-runtime-baseline/02_runtime_smoke/PLAN-cloud-G07.md b/agent-task/m-runtime-baseline/02_runtime_smoke/PLAN-cloud-G07.md new file mode 100644 index 00000000..8096c58f --- /dev/null +++ b/agent-task/m-runtime-baseline/02_runtime_smoke/PLAN-cloud-G07.md @@ -0,0 +1,202 @@ + + +# Plan - Runtime Smoke And Remote Parity + +## 이 파일을 읽는 구현 에이전트에게 + +구현이 끝나면 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 검증 명령을 실행하고 실제 stdout/stderr를 기록한 뒤 active 파일을 그대로 두고 리뷰 준비를 보고한다. 최종 archive, `complete.log`, 코드리뷰 판정은 code-review 스킬 전용이다. + +## 배경 + +현재 compose 문서는 core, db, push-proxy를 올리는 방법과 smoke 절차를 갖췄지만 실제 Docker 기동과 원격 hash parity는 아직 완료 evidence가 없다. 이 작업은 Docker-capable 환경과 remote host 접근이 필요한 실행 검증이다. smoke 실패가 compose 설정 문제로 확인될 때만 repo 파일을 최소 수정한다. + +## 분석 결과 + +### 읽은 파일 + +- `agent-roadmap/current.md` +- `agent-roadmap/phase/product-foundation/PHASE.md` +- `agent-roadmap/phase/product-foundation/milestones/runtime-baseline.md` +- `README.md` +- `docs/README.md` +- `services/core/compose/README.md` +- `services/core/compose/.env.example` +- `services/core/compose/docker-compose.yml` +- `.gitignore` + +### 테스트 커버리지 공백 + +- `local-compose`: 기존 자동 테스트 없음. 실제 `docker compose up -d`, core ping, app HEAD, db readiness, push-proxy service/config check 출력이 evidence다. +- `remote-parity`: 기존 자동 테스트 없음. local/remote `sha256sum` 출력 일치와 원격 smoke 출력이 evidence다. +- compose 수정이 발생하는 경우: unit test는 없고 `docker compose config`, smoke command, `git diff --check`로 검증한다. + +### 심볼 참조 + +none. 이 작업은 code symbol rename/remove를 하지 않는다. + +### 분할 판단 + +split decision policy를 먼저 평가했다. shared task group은 `m-runtime-baseline`이다. + +- `01_source_snapshots`: upstream source snapshot 반입. 외부 git snapshot 리스크. +- `02_runtime_smoke`: Docker/SSH smoke 검증. terminal-agent 리스크. + +두 sibling 사이에 런타임 선행 의존성은 없다. 이 plan 내부에서는 local smoke 후 remote parity를 진행한다. + +### 범위 결정 근거 + +이 작업은 `services/core/compose/docker-compose.yml`, `services/core/compose/.env.example`, `services/core/compose/README.md`, 그리고 원격 `~/docker/services/nexo/compose` parity 확인만 다룬다. nginx/TLS, production hardening, push credential validation, push-proxy source build 전환, 기존 다른 compose 서비스와의 병합은 범위 밖이다. 계획 작성 환경에서는 `command -v docker`가 빈 출력이었으므로 실제 완료는 Docker 사용 가능한 환경에서만 가능하다. + +### 빌드 등급 + +build=`cloud-G07`, review=`cloud-G07`. Docker/SSH/long-running service smoke와 stdout/stderr evidence가 핵심인 terminal-agent 작업이다. + +## 구현 체크리스트 + +- [ ] `command -v docker`, `docker compose version`, `docker info`로 Docker 실행 가능성을 확인한다. +- [ ] `services/core/compose`에서 `.env`를 git 밖에 준비하고 `docker compose config`가 성공하는지 확인한다. +- [ ] `docker compose up -d` 후 core ping, Mattermost app HEAD, db readiness, push-proxy service/config smoke를 실행한다. 검증: `cd services/core/compose && docker compose up -d` 후 core ping과 Mattermost 앱 접근이 성공한다. +- [ ] `NEXO_REMOTE_HOST`를 사용해 원격 `~/docker/services/nexo/compose`의 `docker-compose.yml`과 `.env.example` hash가 local과 일치하는지 확인한다. 검증: local/remote compose와 `.env.example` hash 비교가 일치한다. +- [ ] smoke 실패가 repo 설정 문제로 확인될 때만 compose 파일이나 README를 최소 수정하고 같은 smoke를 재실행한다. +- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다. + +### [SMOKE-1] Local Compose Runtime + +#### 문제 + +Milestone의 `[local-compose]`는 `agent-roadmap/phase/product-foundation/milestones/runtime-baseline.md:53`에서 미완료이고 실제 Docker 기동 evidence가 필요하다. `services/core/compose/docker-compose.yml:16`부터 db healthcheck가 있고 `services/core/compose/docker-compose.yml:47`은 core가 push-proxy를 compose DNS로 참조하지만, runtime smoke 출력은 아직 없다. + +#### 해결 방법 + +Docker-capable 환경에서 local compose를 detached mode로 올리고 README에 기록된 smoke를 실행한다. `.env`는 `services/core/compose/.env.example:1`부터 `services/core/compose/.env.example:4`를 복사해 만들되 git에 올리지 않는다. + +```sh +cd services/core/compose +cp -n .env.example .env +docker compose config +docker compose up -d +curl -fsS "http://localhost:${NEXO_CORE_PORT:-18065}/api/v4/system/ping" +docker compose exec db pg_isready -U mmuser -d mattermost +curl -fsSI "http://localhost:${NEXO_CORE_PORT:-18065}" +docker compose ps push-proxy +docker compose config | rg --fixed-strings "MM_EMAILSETTINGS_PUSHNOTIFICATIONSERVER=http://push-proxy:8066" +``` + +실패 원인이 repo 설정이면 `docker-compose.yml`, `.env.example`, `README.md` 중 필요한 파일만 수정한다. Docker daemon 부재, port collision, missing remote secret처럼 repo 밖 문제면 수정하지 말고 blocker로 기록한다. + +#### 수정 파일 및 체크리스트 + +- [ ] 필요 시 `services/core/compose/docker-compose.yml`을 최소 수정한다. +- [ ] 필요 시 `services/core/compose/.env.example`을 최소 수정한다. +- [ ] 필요 시 `services/core/compose/README.md`를 실제 smoke와 맞춘다. +- [ ] `.env`와 `services/core/data/`는 git에 포함하지 않는다. + +#### 테스트 작성 + +테스트 파일은 작성하지 않는다. 이 항목은 runtime smoke이며 실제 Docker command 출력이 검증이다. + +#### 중간 검증 + +```sh +cd services/core/compose +command -v docker +docker compose version +docker info +docker compose config +docker compose up -d +curl -fsS "http://localhost:${NEXO_CORE_PORT:-18065}/api/v4/system/ping" +docker compose exec db pg_isready -U mmuser -d mattermost +curl -fsSI "http://localhost:${NEXO_CORE_PORT:-18065}" +docker compose ps push-proxy +docker compose config | rg --fixed-strings "MM_EMAILSETTINGS_PUSHNOTIFICATIONSERVER=http://push-proxy:8066" +``` + +### [SMOKE-2] Remote Parity + +#### 문제 + +Milestone의 `[remote-parity]`는 `agent-roadmap/phase/product-foundation/milestones/runtime-baseline.md:54`에서 미완료다. `services/core/compose/README.md:58`부터 hash 비교 절차가 있지만 실제 remote output이 없다. + +#### 해결 방법 + +원격 host를 `NEXO_REMOTE_HOST`로 받고 local/remote hash를 비교한다. 원격 파일이 의도한 배포 copy와 다르면 원격을 동기화한 뒤 같은 명령을 재실행한다. repo 파일은 local source of truth가 틀린 경우에만 수정한다. + +```sh +test -n "$NEXO_REMOTE_HOST" +cd services/core/compose +sha256sum docker-compose.yml .env.example +ssh "$NEXO_REMOTE_HOST" 'cd ~/docker/services/nexo/compose && sha256sum docker-compose.yml .env.example' +``` + +hash가 일치하면 원격에서도 최소 smoke를 실행한다. 원격 `.env`와 runtime data는 git 밖에 있어야 한다. + +```sh +ssh "$NEXO_REMOTE_HOST" 'cd ~/docker/services/nexo/compose && docker compose config' +ssh "$NEXO_REMOTE_HOST" 'cd ~/docker/services/nexo/compose && docker compose ps' +ssh "$NEXO_REMOTE_HOST" 'curl -fsS "http://localhost:${NEXO_CORE_PORT:-18065}/api/v4/system/ping"' +``` + +#### 수정 파일 및 체크리스트 + +- [ ] local/remote hash output을 기록한다. +- [ ] 원격 drift가 있으면 원격 sync 또는 의도적 drift 사유를 기록한다. +- [ ] repo 문서가 실제 remote 기준과 다를 때만 `services/core/compose/README.md`를 수정한다. + +#### 테스트 작성 + +테스트 파일은 작성하지 않는다. 이 항목은 remote smoke이며 SSH command 출력이 검증이다. + +#### 중간 검증 + +```sh +test -n "$NEXO_REMOTE_HOST" +cd services/core/compose +sha256sum docker-compose.yml .env.example +ssh "$NEXO_REMOTE_HOST" 'cd ~/docker/services/nexo/compose && sha256sum docker-compose.yml .env.example' +ssh "$NEXO_REMOTE_HOST" 'cd ~/docker/services/nexo/compose && docker compose config' +ssh "$NEXO_REMOTE_HOST" 'cd ~/docker/services/nexo/compose && docker compose ps' +ssh "$NEXO_REMOTE_HOST" 'curl -fsS "http://localhost:${NEXO_CORE_PORT:-18065}/api/v4/system/ping"' +``` + +## 의존 관계 및 구현 순서 + +1. SMOKE-1 local compose smoke를 먼저 수행한다. +2. SMOKE-2 remote parity와 remote smoke를 수행한다. +3. 둘 중 repo 설정 문제가 발견된 경우에만 최소 수정 후 해당 smoke부터 재실행한다. + +## 수정 파일 요약 + +| 파일 | 항목 | +| --- | --- | +| `services/core/compose/docker-compose.yml` | SMOKE-1 | +| `services/core/compose/.env.example` | SMOKE-1 | +| `services/core/compose/README.md` | SMOKE-1, SMOKE-2 | + +## 최종 검증 + +```sh +cd services/core/compose +command -v docker +docker compose version +docker info +docker compose config +docker compose up -d +curl -fsS "http://localhost:${NEXO_CORE_PORT:-18065}/api/v4/system/ping" +docker compose exec db pg_isready -U mmuser -d mattermost +curl -fsSI "http://localhost:${NEXO_CORE_PORT:-18065}" +docker compose ps push-proxy +docker compose config | rg --fixed-strings "MM_EMAILSETTINGS_PUSHNOTIFICATIONSERVER=http://push-proxy:8066" +test -n "$NEXO_REMOTE_HOST" +sha256sum docker-compose.yml .env.example +ssh "$NEXO_REMOTE_HOST" 'cd ~/docker/services/nexo/compose && sha256sum docker-compose.yml .env.example' +ssh "$NEXO_REMOTE_HOST" 'cd ~/docker/services/nexo/compose && docker compose config' +ssh "$NEXO_REMOTE_HOST" 'cd ~/docker/services/nexo/compose && docker compose ps' +ssh "$NEXO_REMOTE_HOST" 'curl -fsS "http://localhost:${NEXO_CORE_PORT:-18065}/api/v4/system/ping"' +cd ../../.. +git status --short services/core/compose +git diff --check +``` + +Expected outcome: Docker is available, compose config is valid, local core ping and app HEAD succeed, db is ready, push-proxy service/config smoke succeeds, remote hashes match local hashes, remote compose config and ping succeed, and `git diff --check` reports no whitespace errors. + +모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.