Bootstrap Stack

---
name: bootstrap-stack
description: Decide or document the project stack, then author stack-specific setup. Input-adaptive — a concrete stack summary is documented directly, empty/vague input triggers deep research-and-rounds decision, --migrate handles a stack change.
argument-hint: "[stack summary → document | empty/vague → deep decision rounds | --migrate [new stack]]"
disable-model-invocation: true
allowed-tools: Read Glob Grep Write Edit Agent
---

너의 역할은 프로젝트 스택을 *결정하거나 문서화*하고, 이 보일러플레이트에 맞게 stack-specific 초기 세팅 문서를 정리하는 것이다. 스택이 이미 정해졌으면 문서화만, 미정이면 리서치+라운드로 결정까지 운전한다. 정책 SSOT는 ADR-055(입력 적응형 흐름·taxonomy) + ADR-071(카탈로그·disposition·HYBRID 라우팅) + ADR-041 D2(--migrate contract).

이 skill은 **메인 세션에서 직접 실행**된다(discover-product/plan-milestone 패턴 — `context: fork` 미지정). 무거운 추론은 `Agent` 도구로 architect/researcher 단발 sub-call에 위임하고 결론만 문서에 반영한다. `disable-model-invocation: true` 유지 — 후속 `/stack-guard`는 텍스트 제안이며 자동 호출하지 않는다(ADR-050 D2).

## R0 — 입력·상태 감지 + 분기 (항상 먼저 수행)
1. **상태 회수(최소)**: **활성 스택 ADR** = `docs/90-decisions/project/ADR-1NN-*.md` 중 `## Status`가 `superseded`로 시작하지 않고 스택 선택을 소유하는 파일(최초는 `ADR-101-stack-selection.md`, `--migrate` 뒤에는 `대체:` 체인의 마지막 하나). 둘 이상이면 «활성 ADR 중복 — 사용자 확인» 후 종료. 없으면 «없음». + 프로젝트 manifest(`package.json`/`pyproject.toml`/`go.mod`/`Cargo.toml` 등) 존재 여부.
2. **분기**:
   - **`--migrate`** → 아래 `## --migrate (T2) 흐름`.
   - **BASE** — 프레임워크/언어/런타임 토큰이 있고 **`stack-catalog.md`의 해당 유형 T1 행이 모두 입력에서 결정됨**(또는 brownfield manifest에서 감지됨) → `## BASE 문서화 흐름` + `## R-C 카탈로그 라운드`(T2/T3 미결정 행만).
   - **HYBRID** — 프레임워크 토큰은 있으나 T1 행에 미결정이 남음(예: "Next.js"만 주고 백엔드·DB 미정) → `## DEEP 결정 흐름`의 R1~R2를 **미결정 T1 행에 한정**해 실행 → R-C → R4 저장. (ADR-071 D4)
   - **DEEP** — 해석 가능한 프레임워크 토큰이 없거나 불확실 마커("추천"·"골라줘") → `## DEEP 결정 흐름` 전체.
3. **가드**:
   - **charter/ARCH 얕음** — DEEP인데 `PROJECT_CHARTER §4/5/6/7`·`ARCH §8`이 비었으면 persona·제품 맥락을 *만들지 말고* "먼저 `/discover-product` 또는 `/bootstrap-project`" 안내 후 종료(DISCOVERY=SSOT, ADR-035).
   - **오라우팅 방지** — 토큰이 있는데 T1 미결정이 남으면 HYBRID다. 사용자가 명시적으로 "나머지는 나중에"라고 하면 그 행들을 registry `이관`(사유 + 회수 시점)으로 적고 BASE로 간다. 조용히 건너뛰지 않는다.

반드시 먼저 읽을 파일:
- `docs/00-meta/GUARDRAILS_STRATEGY.md`
- `docs/00-meta/WORKFLOW.md`
- `docs/10-charter/PROJECT_CHARTER.md`
- `docs/20-system/ARCHITECTURE_OVERVIEW.md`
- `docs/90-decisions/boilerplate/_ADR_GUIDE.md` (ADR-101 권장 섹션·area 태그·Mutation Contract 규약)
- `docs/90-decisions/project/README.md` (project ADR 인덱스 — ADR-101 추가 후 한 줄 갱신 대상)
- `stack-brief-template.md`
- `output-checklist.md`
- `stack-catalog.md`

## DEEP 결정 흐름 (R1~R4 — 무입력/모호 시)
discover-product 라운드 패턴을 재사용한다. 각 라운드는 압축 포맷으로 출력하고 자연어 응답(`skip`/`good`/`refine: …`)만 받는다:
```
이번 결정: <1~2줄>
확인 필요: <있으면 ≤3개, 없으면 생략>
답변: skip / good / refine: …
```
사용자가 *선택해야 하는* 옵션 목록(2~3 스택 조합)은 압축하지 않고 보존한다(ADR-046#d3). architect/researcher 단발 sub-call의 *과정*은 대화에 풀지 않고 결론만 surface한다. **(Codex: 서브에이전트는 GA이나 본 저장소가 Claude persona 위임을 Codex subagent로 아직 매핑하지 않아 R1 researcher·R2 architect 위임을 순차 인라인 추론으로 degrade — ADR-040#amend-3 / ADR-053 정합.)**

**R1 — 요구 grounding + 리서치.** `PROJECT_CHARTER ## 4 목표/## 5 비목표/## 6 성공 기준/## 7 제약` + `ARCH ## 8 품질 속성`(규모·성능·확장 기대)을 읽는다. 최신 프레임워크/버전 지형이 필요하면 `Agent`로 researcher에 직접 위임(ADR-040#amend-3 — bootstrap-stack은 Agent 보유). 결과는 출처·날짜·신뢰도 라벨(ADR-040 §3). **오프라인/미발견이면 날조 금지** — 조합을 `Needs Research`·저신뢰도로 표시하거나 BASE 문서화로 폴백한다.

**R2 — 옵션 + 트레이드오프 + 추천(수렴 루프).** architect 단발 sub-call로 **2~3개 스택 조합**을 서로 다른 각도(MVP/risk/scale-first)로 생성. 각 조합에 (a) 현재 복잡도 (b) 확장·마이그레이션 비용 (c) **현재 직접 지원 범위** 정합 — web frontend/API/CLI/monorepo/Supabase + **Flutter(Android·iOS)**. **유형 수를 이 줄에 박지 않는다**(범위 SSOT는 ADR-031#amend-1·ADR-059 D1이며, 범위가 바뀌면 이 줄이 아니라 그 ADR을 본다 — 숫자를 박으면 낡는다) (d) 성장 경로("X로 시작 → Y로 성장") + **본 skill의 추천안 + 근거**를 함께 제시(ADR-006 단순성 가중 — 과한 스택 경고). 사용자가 `skip/good/refine`로 응답 → 피드백 시 재생성. **2사이클 미수렴 시 재생성 대신 brief를 고친다**(charter 재독·요구 명확화 — bootstrap-design R2 규칙). 선택 확정 전에는 R3로 진행하지 않는다.

**R3 — 고-stakes 심화(해당 시).** 되돌리기 비싼 §7-3 백엔드 결정(인증·DB·트랜잭션)이 ADR-053 게이트(S1~S4 중 1+)에 걸리면 아래 `## 고-stakes 설계 게이트`의 full 패널을 실행하고, 그 결론을 **Decision Brief로 사용자에게 제시해 확정**한다(ADR-053#amend-2 ④). 저-stakes는 R2 단발 결론. 스택 선택 자체는 R2에서 다뤘으므로 여기선 *별개의* 미해결 reversible 결정에만 발동(중복 발동 회피 — ADR-053 falsifying-eval의 과발동 방지).

**R4 — 저장/실행(절대 건너뛰지 않음).** 확정된 스택으로 아래 `## BASE 문서화 흐름`을 그대로 수행해 모든 산출물을 *한 세션에* 쓴다. R1~R3 근거는 활성 스택 ADR의 옵션≥2/신뢰도/재검토 칸에 적재한다.

**누적/단계별 출구:** R1~R3 동안 결론을 draft 활성 스택 ADR(`## 0. Status: proposed`, **인덱스 미등재**)에 누적한다. 중간에 멈춰도 proposed 활성 스택 ADR이 남아 재개·`/stack-guard` 입력으로 유효하다. R4 저장 때만 status를 accepted로 올리고 인덱스 행을 추가한다. proposed 상태·미등재를 유지해 stabilize의 §7 backstop 오탐을 막는다.

## BASE 문서화 흐름 (구체적 스택/brownfield, 또는 DEEP R4)
1. 스택 정보를 구조화한다(`stack-brief-template.md` 참조). brownfield면 manifest에서 감지.
2. 아래 문서를 갱신한다.
   - `docs/20-system/ARCHITECTURE_OVERVIEW.md` — **`## 7. 기술 선택`**(고-stakes는 §7 결정 블록: 옵션≥2/신뢰도/재검토) + 해당 **`## 7-1`~`## 7-5`** 컨벤션 + **`## 3-1` 레이어 경계·의존성 규칙에 스택별 디폴트 디렉터리 트리**(아래 표) + `## 7. 기술 선택` 하위 운영 사실(실행 명령/포트/환경변수 이름/핵심 디렉터리 역할/gotcha — `output-checklist.md`).
   - `docs/10-charter/PROJECT_CHARTER.md` **`## 7. 제약 조건`** — 허용 의존 정책 envelope(스택 핵심 라이브러리). T3 dep 판정의 기준선.
   - `docs/90-decisions/project/ADR-101-stack-selection.md`(최초 생성) 또는 활성 스택 ADR(갱신) — _ADR_GUIDE 권장 섹션 + 옵션·신뢰도·재검토 칸. API 감지 → 7-1+7-3, CLI → 7-2, 웹 프론트 → 7-4, 모바일 앱(Flutter) → 7-5.
   - **`## 7-1`~`## 7-5` 채움은 소항목별 `authority`를 따른다 (ADR-060 D9 — 구 "라운드 아님" 규정을 부분 supersede)**:

     | 섹션 | `user-approval` — Decision Brief로 제시하고 사용자가 승인 | `agent-delegated` — architect 단발 sub-call, 라운드 끝 일괄 확인 1회 |
     |------|---------------------------------------------------------|--------------------------------------------------------------------|
     | `## 7-1` API | 응답 envelope · 페이지네이션 | HTTP 상태 매핑 · error 레지스트리 · 네이밍 · Don'ts |
     | `## 7-2` CLI | 출력 포맷(기본 모드) | 플래그·명령어 · TTY/ANSI · Don'ts |
     | `## 7-3` 백엔드 | **DB migration · 인증·인가 · API versioning** | 트랜잭션 경계 · Idempotency · Rate limit · Async job · Caching |
     | `## 7-4` 프론트 | **라우팅 · SSR-CSR · 인증(토큰 저장)** | 상태관리 · i18n · SEO · 폼 validation |
     | `## 7-5` 모바일 | **대상 플랫폼·최소 OS · 화면 이동 · 권한 요청 흐름 · 로컬 저장·오프라인 · 서명·배포** | 상태관리 · 네이티브 연동 · 빌드 flavor · 백그라운드 · WebView · Don'ts |

     배정 기준: 되돌린 뒤 **이미 쓴 코드·데이터·사용자 계정에 파급**이 있으면 `user-approval`, 코드 안에서 끝나면 `agent-delegated`.
     `user-approval` 항목만 원장에 등재하고 **라운드당 3~5개 상한**을 지켜 나눠 제시한다(ADR-060 D3). 승인 후 `status: closed` + 정본 앵커(`ARCHITECTURE_OVERVIEW.md#arch-7-N`)를 채운다. `agent-delegated`는 개별 등재 없이 일괄 확인 1회로만 처리한다.
     해당 스택이 아닌 sub-section은 아래 3번대로 삭제하므로 결정 대상이 아니다.
   - `docs/90-decisions/project/README.md` 인덱스 표에 활성 스택 ADR 한 줄 추가.
3. **비해당 `## 7-1`~`## 7-5` 처리 — 단일 스택은 통째 삭제, 다중 스택(monorepo)은 KEEP-list**: 프로젝트가 스택 1종이면 비해당 sub-section을 통째 삭제한다(예: API 미포함 → `## 7-1` 삭제). **FE+API+CLI 등 다중 스택이면 해당하는 sub-section을 *모두 보존*하고 각 스택의 디렉터리 트리를 `## 3-1`에 함께 박는다(삭제 금지).** **모바일 앱 스택이면 `## 7-5`를 채우고 `## 7-4`를 삭제한다**(웹 화면이 함께 있는 경우에만 둘 다 보존 — ADR-073 D1).
4. `docs/00-meta/_templates/STACK_SETUP_PLAN_TEMPLATE.md`를 복사해 `docs/00-meta/STACK_SETUP_PLAN.md`를 **항상** 생성·갱신한다(ADR-071 D8 — 선택 산출물 아님). **복사 시 비해당 절을 통째 삭제한다**(ARCH `## 7-1`~`## 7-5` 비해당 삭제 규칙과 동형). **두 절의 조건은 다르다** — `## Dart Source Roots`는 `dart format` 대상이 있는 **모든 Dart/Flutter 스택**에서 남기고(순수 Dart CLI·패키지 포함, ADR-059 D2), `## Golden 초기 절차`는 **화면이 있는 native 스택에서만** 남긴다(runtime target에 `native/*` 포함 ∧ design surface 있음 — ADR-059 D3). golden 은 위젯 렌더 픽셀 비교라 화면 없는 Dart CLI·패키지에는 `flutter test --update-goldens` 자체가 성립하지 않으므로, 그 프로젝트에 남기면 쓸모없는 안내가 영구히 붙는다. `## E2E Smoke Registry`는 스택 무관이라 남기고 비대상이면 `status: n/a`만 적는다. **Optional MCP Connectors 백필(ADR-048#d1)**: `.codex/config.toml`에 `[mcp_servers.*]`가 있으면 STACK_SETUP_PLAN `## Optional MCP Connectors` 표에 backfill 권장(자동 연결 X — 사용자 직접).
   - **Dependency Tools 기록 (ADR-075 D14)**: 확정한 **scope별 의존성 도구**(npm/pnpm/yarn/bun · pip/poetry/uv · cargo · go · **pub(Flutter/Dart)** 등)를 STACK_SETUP_PLAN `## Dependency Tools` 표에 기록한다 — 단일 패키지는 `.` 1행, 모노레포·polyglot은 scope별 1행(경로 prefix), 비-JS 스택도 같은 표. **적는 대상은 *builder가 프로젝트·기능 의존성을 설치할 때 쓰는 PM*뿐이다** — 검증 도구 자체를 설치하는 PM은 그 도구의 registry가 기록하므로 이 표에 넣지 않는다(ADR-059 D2). 예: Flutter 루트는 `pubspec.lock`·`package-lock.json`이 함께 있어도 **`pub` 1행**이고(npm은 design gate·통합 명령용), 웹 프로젝트의 `@playwright/test`도 별도 행으로 적지 않는다. 근거 컬럼엔 그 판정을 뒷받침한 *tool-specific* 신호(lockfile·tool-manifest)를 적고, lockfile이 아직 없는 green-field는 `(신규 — lockfile 미생성)`으로 표기한다. **이 표가 downstream scope→tool SSOT**다(stack-guard 교차확인 → plan-workitem 설치 line item → implement 3-DT → builder). 도구 *선택 근거*는 ARCHITECTURE `## 7`에, 설치 소유 경계는 ADR-052.
   - **Stack Decision Registry 기록 (ADR-071 D2)**: `stack-catalog.md`의 해당 유형 행 전부를 `## Stack Decision Registry`에 적고 `scope`·disposition(`확정 | 해당 없음 | 이관 | 미결정`)·authority·정본 앵커·확인일을 채운다. **행 키는 `(scope, id)`** — 단일 패키지는 전 행 `.`, monorepo는 scope마다 갈릴 수 있는 행을 scope별로 두고 저장소 단위 행만 `*`로 둔다. **빈 행이 남으면 성공 종료하지 않는다.** 결정 본문은 앵커(ARCH `## 7-N`·활성 스택 ADR)에만 적는다 — registry는 색인이다.
5. 화면이 있는 스택(웹 프론트 또는 모바일 앱) 감지 시 마지막 출력에 "UI 스택 감지됨. `/bootstrap-design` 권장" 1줄.

## R-C — 카탈로그 라운드 (BASE·HYBRID·DEEP R4 공통, ADR-071)
1. `stack-catalog.md`에서 프로젝트 유형(들)의 행을 회수한다 — 유형은 ADR-071 D4 판별 규칙(활성 ARCH sub-section·workspace·Supabase 신호, 애매하면 사용자 확인 1회)으로 정하고 monorepo·풀스택은 해당 유형 전부. monorepo는 scope마다 값이 갈릴 수 있는 행을 scope별로 나눈다(ADR-071 D2 `(scope, id)` 키).
2. 이미 결정된 행(입력·brownfield 감지·DEEP R2 결론)은 `확정`으로 registry에 적는다.
3. 나머지 행을 authority로 나눈다 — `user-approval` 행은 Decision Brief 6블록으로 **라운드당 3~5개씩** 제시(ADR-060 D3, `skip` 불허 — 선택/설명/리서치/`이관` 중 택1). `agent-delegated` 행은 architect 단발 sub-call이 기본 후보와 근거를 정하고 **라운드 끝 일괄 확인 1회**로 제시한다. 사용자가 뒤집은 행은 `user-approval`로 원장에 등재한다.
4. 새로 정하거나 불확실한 행만 researcher 단발 sub-call로 현재 메이저·호환·발행일을 확인해 `확인일`에 적는다(ADR-071 D7). 기존 실측 스택은 재조사하지 않는다.
5. 사용자가 지금 정하지 않겠다는 행은 `이관`(사유 + 회수 시점 — 보통 `M1 plan-milestone R1`)으로 적고 **DECISION_REGISTER에 `deferred`**(무영향 근거·이관 앵커 = registry 행·회수 시점)로 등재한다(ADR-060 D4 3필드 — plan-milestone R1이 회수). 정해야 하는데 못 정한 행은 `미결정` + DECISION_REGISTER `open`(`영향: (미할당)`)으로 적는다.
6. 결정 본문은 정본 앵커에 쓴다: 7-x 소항목 → ARCH `## 7-N`, 스택·주요 라이브러리 → 활성 스택 ADR `## 결정` 표, 운영 사실 → ARCH `## 7` 하위, 설치 시점·PM → STACK_SETUP_PLAN.
7. 종료 조건: registry에 빈 행 0.

## --migrate (T2) 흐름 — 입력 적응형
스택 *변경*. R0에서 `--migrate`로 진입. contract 규약 소유는 ADR-041 D2, 적응형 진입은 ADR-055. **입력 적응형**:
- **타깃 명시**(`--migrate Nest.js`) 또는 이미 결정 → 옵션 라운드 건너뛰고 계약 authoring 직행.
- **타깃 미정**(`--migrate` 단독 / "뭐로 갈지 모르겠다") → 위 DEEP R1~R2를 *마이그레이션 프레이밍*으로 실행(트레이드오프 축에 **기존 데이터·API 호환성**과 **이전 비용**을 1급 추가) → 타깃 수렴 후 계약.

계약(항상, ADR-041 D2): 새 project ADR `docs/90-decisions/project/ADR-1NN-<migration>.md`에 old/new stack, 호환성(데이터·API·런타임), cutover 순서(expand-contract: 신규 추가 → dual-run → 구식 제거), rollback, validation(완료 판정), hook·verify 갱신 목록을 쓰고, 기존 **활성 스택 ADR**을 `superseded` + 상단 "대체: ADR-1NN". project README 인덱스에 한 줄 추가 + 옛 활성 ADR 행 상태 superseded 갱신. ARCH §7 결정 블록·§3-1 디렉터리 트리 갱신, charter §7 제약 갱신.
**진행 중 task/worktree 주의**: 마이그레이션은 진행 중 task의 §7 매핑·AC를 무효화할 수 있다. supersede 전에 진행 중 task를 freeze·재검증할 것을 출력에 명시하고, cutover는 `Type:migration` task(ADR-039)로 분해한다 — 즉시 generic `/plan-workitem`을 호출하지 않고 **다음 `/plan-milestone`의 범위에 포함한 뒤 그 M 전체 스냅샷에서 task화**한다(아직 계획 전인 draft M이면 그 안에서 반영, ADR-057#amend-3 결정 6).
작성 후 안내: `/bootstrap-stack <new stack>`(문서화) → `/stack-guard` 순 재실행(재실행의 BASE는 새 ADR-1NN을 활성 스택 ADR로 읽는다).

## 스택 결정 tier (T1/T2/T3 — ADR-055) — 판정 기준
- **T1 기초 스택**(프로젝트 birth): 본 skill의 BASE/DEEP 흐름 → ADR-101 + ARCH §7 + charter §7 제약.
- **T2 물질적 변경/마이그레이션**: ADR-053 S1~S4 중 1+ 해당(언어/런타임/프레임워크/DB·영속성/인증/배포 토폴로지/핵심 외부 의존을 건드림 **또는** ARCH §7 결정·charter §7 제약을 뒤엎음; 개별로 사소해도 *cluster*로 이 선을 넘으면 포함) → 본 skill `--migrate`.
- **T3 라이브러리 추가**(routine): 위 어느 것도 아님 → 해당 마일스톤의 `/plan-workitem M<N>`이 task `## 3` install line-item으로 처리(ADR-040#amend-1) — 해당 마일스톤 계획 범위에 포함하며 즉시 generic 호출하지 않음(ADR-057#amend-3 결정 6). 활성 스택 ADR 안 건드림. 누적이 T2 선을 넘으면 stabilize의 `[Stack-drift]`가 감지.

반드시 지켜야 할 원칙:
- shared 기본값에 OS/셸 종속 hook를 강제로 넣지 않는다. 대신 필요한 scripts/hooks/CI를 문서로 정리한다.
- 확실하지 않은 환경 전제는 가정으로 표시한다. 추측을 사실처럼 쓰지 않는다.
- 통합 검증 명령(`validate`)·verify 스크립트·hook 등록 안내는 `/stack-guard`가 별도 생성한다 — 다음 단계 안내에 포함.

마지막 출력:
- 스택 선택/문서화 요약 (DEEP면 선택된 조합 + 근거)
- 갱신/생성한 문서 목록
- 추천 guardrail 목록 + 남은 불확실성 (결정 아닌 환경·도구 가정 — 기존 슬롯 유지)
- **원장 요약**: `closed N건 / deferred M건 / open K건` (open이 있으면 `authority`·필요 시점 1줄씩). *결정*은 대화에만 두지 않고 전부 `docs/10-charter/DECISION_REGISTER.md`에 등재한다
- **연결/연결 권장 MCP가 있으면**: STACK_SETUP_PLAN `## Optional MCP Connectors`에 lifecycle usage + agent access 기록 안내 1줄(ADR-048).
- 다음 권장 단계로 `/stack-guard` 안내(자동 호출 아님 — 사용자 발화). 프론트면 `/bootstrap-design`도.
- **registry 요약**: 확정 N / 해당 없음 M / 이관 K(회수 시점 목록) / 미결정 J(0이어야 정상 종료)

## 외부 의존 부트업 권장 (감지 시 출력, ADR-025)
스택 감지 시(강제 X, 권장만):
- Postgres: `docker-compose.yml` 또는 `supabase start` 권장.
- Redis: `docker-compose.yml` 권장.
- S3: localstack 또는 MinIO 권장.

사용자가 채택 시 README에 1단락 + `make dev` / `pnpm dev` 등의 통합 진입점에 wiring. 상세는 생성될 `docs/00-meta/STACK_SETUP_PLAN.md` 참조.

## monorepo 라운드 (감지 시 자동, ADR-008#amend-1)
1. **orchestrator 결정**: turbo / nx / pnpm workspaces only / lerna 등 1종.
2. **shared 패키지 위치 + 버전 정책**: `packages/shared`, semver vs fixed.
3. **publish 정책**: 외부 publish vs internal-only.
4. **scope vocabulary**: 패키지명 목록을 ADR-008 amend의 scope 컨벤션과 정합화.
> monorepo는 위 `## BASE 문서화 흐름` 3의 다중 스택 KEEP-list를 적용한다(§7-1~7-5 삭제 금지, 패키지별 디렉터리 트리 모두 §3-1에 박음).

## 스택별 디폴트 디렉터리 구조 (권장 출력)

스캐폴드 생성은 `/stack-guard` 수행 0이 수행한다(ADR-071 D5). 본 표는 생성기 옵션·`## 3-1` 기록의 기준이다.

| 스택 | 디폴트 트리 |
|------|-----------|
| Next.js | `app/`, `components/`, `lib/`, `tests/` |
| FastAPI | `app/{api,core,domain,infra}/`, `tests/` |
| Express | `src/{routes,services,domain,infra}/`, `tests/` |
| Rust CLI | `src/{cli,core,...}/`, `tests/` |
| Go CLI | `cmd/`, `internal/{cli,core,...}/`, `tests/` |
| Python CLI | `src/<pkg>/{cli,core,...}/`, `tests/` |
| Flutter (Android·iOS) | `lib/{app,features,shared}/`, `test/`, `integration_test/` |

ARCHITECTURE_OVERVIEW.md `## 3-1` 채움 시 함께 박음. 사용자 즉흥 결정 → 스파게티 차단.

## 고-stakes 설계 게이트 (ADR-053)
설계 결정이 ADR-053 게이트(S1~S4 중 1+ → full 패널 / S5만 → 리서치-only / 전부 NO → 단발)면: ① researcher 웹 패스(must-or-flag, 오프라인 `Needs Research`) → ② architect 다각도 2~3안 → ③(S1·S3·S4 중 2+면) 두 번째 architect 적대 검토(review-doc 미사용·parallel-merge 금지, 순차 생성→비평→종합) → **④ 사용자 선택 — ②의 안을 Decision Brief 6블록으로 제시(ADR-053#amend-2 / ADR-060 D3)** → ⑤ ARCHITECTURE §7 결정 블록 기록 + 원장 `closed` 등재. 저-stakes는 단발. **S1~S4는 분석 깊이 판정이고 결정권은 원장 `authority`가 소유한다.** (Codex: 순차 단일 degrade — researcher 인라인/사전 노트.)

## 결정 마감 (ADR-060)
본 skill이 내리거나 발견하는 기획 결정 중 **사용자가 정하거나 승인해야 할 것**을 `docs/10-charter/DECISION_REGISTER.md`에 등재한다 — 대화 출력으로만 두지 않는다.

1. **등재 시점에 `authority`를 확정한다** (ADR-060 D2): 제품 의도·범위·우선순위·사용자 체감·외부 계약·데이터/보안·비용·위험 허용도·비가역 약속 → `user-choice`. 스택·인증·데이터 경계·되돌리기 비싼 구조 → `user-approval`. 승인된 경계 안의 가역적 내부 선택 → `agent-delegated`. **`user-*`를 `agent-delegated`로 낮추려면 사용자 명시 승인 + 항목에 이력 줄이 필요하다.**
2. **등재 범위 (원장을 얇게 유지)**: `user-*` 결정 전부 + 종류 불문 `open`/`deferred`로 남는 항목만 등재한다. **`agent-delegated`는 개별 등재하지 않고** 4의 일괄 확인으로만 처리한다. **코드 품질·형식 지적과 계획 결함은 원장 대상이 아니다** — 기존 `남은 미결정 사항` 출력 슬롯이 그대로 소유한다.
3. **`user-*` 결정은 Decision Brief 6블록으로 제시한다** (ADR-060 D3 / ADR-046#amend-1 — 압축 예외): 배경(왜 지금) → 용어(배경 없이도 이해되게) → 선택지 2~3안(각각 한 줄 요약·이 프로젝트에서의 체감·장점·감수할 것) → 되돌리기 비용 → 추천+근거 → 답변 방법. **라운드당 3~5개 상한**, `skip` 불허(선택 / 추가 설명 / 리서치 요청 / 연기 중 택1). 답변은 평이한 문장으로 재진술해 확인한 뒤 정본에 기록한다.
4. **라운드 종료 시 일괄 확인 1회**: 그 라운드의 `agent-delegated` 결정을 목록으로 제시하고 "바꿀 것 있으면 알려달라"를 1회 확인받는다. 사용자가 뒤집으면 그 항목은 `user-approval`로 원장에 등재한다.
5. **닫히지 않은 항목**: 현재 M 무영향 + 이관 앵커 + 회수 시점 3개를 모두 갖추면 `deferred`, 아니면 `open`으로 남긴다(ADR-060 D4). **앵커 없는 유예는 금지**한다. 현재 M을 막는 사실 조사는 `deferred`가 아니라 `/research-pack` 선행으로 종결한다.
6. 결정 *본문*은 **본 skill이 소유한 정본 문서**(DISCOVERY / Charter / ARCHITECTURE / DESIGN / ADR 중 해당 단계에 존재하는 것)에 쓰고, 원장에는 위치 앵커와 처분 상태만 적는다(ADR-005). 본 skill이 소유하지 않는 문서는 건드리지 않는다.
7. **마일스톤이 아직 없는 단계**(discover/bootstrap)에서는 `영향: (미할당)`으로 등재한다. `/plan-milestone` R1이 triage한다.

## Context 정책 (ADR-019)
`반드시 먼저 읽을 파일`은 *최소 충분*. 추가 ADR/architecture 섹션은 task 본문에서 발화 시 인용 — 사전 fork-load 금지.