update stage-pilot

2026-04-30 13:03:56 +00:00
parent d9363af773
commit 7e9fbc1418
40 changed files with 5349 additions and 0 deletions
@@ -0,0 +1,25 @@
+# {{BAT_ID}}: <배치 제목>
+
+- Status: draft | in-delivery | release-candidate | released | archived
+- Profile: standard | batch-lite
+- Source Discovery: <dcy-id 또는 없음>
+- Included REQ: <REQ-ID 목록>
+- Excluded REQ: <REQ-ID 목록 또는 없음>
+
+## Summary
+- <이 batch를 왜 묶었는지>
+
+## Scope
+- In Scope:
+  - <포함 범위>
+- Out of Scope:
+  - <제외 범위>
+
+## Documents
+- Planning: [planning.md](./planning.md)
+- Design: <`[design.md](./design.md)` 또는 `none (batch-lite with no architecture impact)`>
+- Implementation: <`[implementation.md](./implementation.md)` 또는 `create at implementation stage`>
+- Verification: <`[verification.md](./verification.md)` 또는 `create at verification stage`>
+
+## Notes
+- <공통 리스크, 공통 결정 사항>
@@ -0,0 +1,26 @@
+# {{BAT_ID}} Design
+
+- Status: draft | confirmed
+- Batch: {{BAT_ID}}
+
+## Architecture Summary
+- <배치 수준 설계 요약>
+
+## Changed Areas
+- Docs: <문서 경로>
+- Modules: <모듈/컴포넌트>
+- Interfaces: <인터페이스>
+
+## Key Decisions
+1. <결정 1>
+2. <결정 2>
+
+## Edge Cases
+- <예외 처리 및 설계 경계>
+
+## Architecture Impact
+- <none | project-structure | runtime-flows | both>
+
+## Reference Doc Update Plan
+- project-structure.md: <갱신 계획 또는 none>
+- runtime-flows.md: <갱신 계획 또는 none>
@@ -0,0 +1,20 @@
+# {{BAT_ID}} Implementation
+
+- Status: draft | in-progress | completed
+- Batch: {{BAT_ID}}
+
+## Plan Summary
+- <이번 구현에서 실제 변경할 범위>
+
+## Changed Files
+- <파일 목록>
+
+## Execution Log
+1. <실행 항목>
+2. <실행 항목>
+
+## Validation
+- <실행한 테스트, lint, typecheck, 수동 점검>
+
+## Remaining Risks
+- <잔여 이슈>
@@ -0,0 +1,10 @@
+# Batch Index
+
+## 목적
+- 이 문서는 batch delivery 단위의 전역 인덱스다.
+- 각 batch는 `docs/batches/<BAT_ID>/` 아래에서 profile(`standard` | `batch-lite`)에 맞는 산출물을 관리한다.
+
+## Batch Register
+
+| BAT ID | Profile | Status | Included REQ | Discovery | Folder |
+| --- | --- | --- | --- | --- | --- |
@@ -0,0 +1,28 @@
+# {{BAT_ID}} Planning
+
+- Status: draft | confirmed
+- Batch: {{BAT_ID}}
+- Profile: standard | batch-lite
+
+## Included REQ
+- <REQ-ID 목록>
+
+## Delivery Plan
+- <구현 범위, 순서, 선행 조건>
+
+## Dependencies
+- Internal:
+  - <내부 의존성>
+- External:
+  - <외부 의존성>
+
+## Design Gate
+- Design Required Before Implementation: yes | no
+- Reason: <왜 즉시 design이 필요한지 또는 왜 생략 가능한지>
+
+## Milestones
+1. <마일스톤>
+2. <마일스톤>
+
+## Risks
+- <리스크와 대응>
@@ -0,0 +1,21 @@
+# {{BAT_ID}} Verification
+
+- Status: draft | confirmed
+- Batch: {{BAT_ID}}
+
+## Acceptance Mapping
+- <REQ-ID>:
+  - <AC와 evidence 연결>
+
+## Evidence
+- Test:
+  - <테스트 결과>
+- Manual:
+  - <수동 검증 결과>
+- Logs:
+  - <로그 또는 스크린샷 경로>
+
+## Result
+- Ready for Release: false
+- Blocking Issues:
+  - <차단 이슈 또는 없음>
@@ -0,0 +1,95 @@
+schema_version: 1
+capture_mode: declared # declared | observed | mixed
+
+project:
+  repository_name: {{REPOSITORY_NAME:repo-folder-name}}
+  display_name: {{PROJECT_NAME:display name or repo name}}
+  summary: {{PROJECT_SUMMARY:one-sentence project summary}}
+  primary_domain: {{PRIMARY_DOMAIN:short domain phrase or undecided}}
+
+stack:
+  tech_stack:
+    - {{TECH_STACK_ITEM_1:primary language or framework}}
+
+runtime:
+  primary_runtime: {{PRIMARY_RUNTIME:cli|api-service|web-app|worker|library|mixed|other}}
+  primary_entrypoints:
+    - name: {{ENTRYPOINT_NAME_1:command or interface name}}
+      purpose: {{ENTRYPOINT_PURPOSE_1:brief purpose}}
+
+interfaces:
+  contracts:
+    - name: {{INTERFACE_NAME_1:primary interface name}}
+      type: {{INTERFACE_TYPE_1:http-api|cli|event|file|internal-service|other}}
+      actors: {{INTERFACE_ACTORS_1:who calls or receives it}}
+      purpose: {{INTERFACE_PURPOSE_1:what this interface exists to do}}
+      stability: {{INTERFACE_STABILITY_1:experimental|internal|stable}}
+      inputs:
+        - {{INTERFACE_INPUT_1_1:input contract or invocation note}}
+      outputs:
+        - {{INTERFACE_OUTPUT_1_1:output contract or artifact}}
+      errors:
+        - {{INTERFACE_ERROR_1_1:error code or failure behavior}}
+      compatibility_rules:
+        - {{INTERFACE_COMPATIBILITY_1_1:compatibility or versioning rule}}
+    - name: {{INTERFACE_NAME_2:secondary interface name}}
+      type: {{INTERFACE_TYPE_2:http-api|cli|event|file|internal-service|other}}
+      actors: {{INTERFACE_ACTORS_2:who calls or receives it}}
+      purpose: {{INTERFACE_PURPOSE_2:what this interface exists to do}}
+      stability: {{INTERFACE_STABILITY_2:experimental|internal|stable}}
+      inputs:
+        - {{INTERFACE_INPUT_2_1:input contract or invocation note}}
+      outputs:
+        - {{INTERFACE_OUTPUT_2_1:output contract or artifact}}
+      errors:
+        - {{INTERFACE_ERROR_2_1:error code or failure behavior}}
+      compatibility_rules:
+        - {{INTERFACE_COMPATIBILITY_2_1:compatibility or versioning rule}}
+  shared_constraints:
+    - {{INTERFACE_SHARED_CONSTRAINT_1:cross-cutting interface constraint}}
+  current_gaps:
+    - {{INTERFACE_GAP_1:known contract gap or planned change}}
+
+structure:
+  planned_top_level_areas:
+    - path: {{TOP_LEVEL_PATH_1:path such as src/ or app/}}
+      responsibility: {{TOP_LEVEL_RESPONSIBILITY_1:brief responsibility}}
+
+data_model:
+  persistence_backend: {{PERSISTENCE_BACKEND:primary persistence backend or storage system}}
+  entities:
+    - name: {{ENTITY_NAME_1:primary entity}}
+      purpose: {{ENTITY_PURPOSE_1:what this entity represents}}
+      source_of_truth: {{ENTITY_SOURCE_1:table, collection, file, or service}}
+      lifecycle: {{ENTITY_LIFECYCLE_1:created -> updated -> archived}}
+      key_fields:
+        - {{ENTITY_FIELD_1_1:field :: type :: meaning}}
+      relationships:
+        - {{ENTITY_RELATIONSHIP_1_1:related entity :: relationship meaning}}
+      state_rules:
+        - {{ENTITY_STATE_RULE_1_1:state or invariant rule}}
+    - name: {{ENTITY_NAME_2:secondary entity}}
+      purpose: {{ENTITY_PURPOSE_2:what this entity represents}}
+      source_of_truth: {{ENTITY_SOURCE_2:table, collection, file, or service}}
+      lifecycle: {{ENTITY_LIFECYCLE_2:created -> updated -> archived}}
+      key_fields:
+        - {{ENTITY_FIELD_2_1:field :: type :: meaning}}
+      relationships:
+        - {{ENTITY_RELATIONSHIP_2_1:related entity :: relationship meaning}}
+      state_rules:
+        - {{ENTITY_STATE_RULE_2_1:state or invariant rule}}
+  consistency_rules:
+    - {{CONSISTENCY_RULE_1:consistency or referential rule}}
+  persistence_notes:
+    - {{PERSISTENCE_NOTE_1:mapping, storage, or migration note}}
+  current_gaps:
+    - {{MODEL_GAP_1:known model gap or planned schema change}}
+
+notes:
+  known_unknowns:
+    - {{KNOWN_UNKNOWN_1:optional unresolved bootstrap item or none}}
+
+metadata:
+  captured_at_kst: {{CAPTURED_AT_KST:YYYY-MM-DD HH:MM}}
+  source: bootstrap-baseline-questionnaire
+  updated_from: {{UPDATED_FROM:user-answer|repo-observation|mixed}}
@@ -0,0 +1,88 @@
+# {{PROJECT_NAME}} Data Model
+
+- Baseline Mode: {{BASELINE_MODE:declared|observed|mixed}}
+- Baseline Seed: {{BASELINE_SEED_PATH:.stagepilot/bootstrap/baseline.yaml}}
+- Status: draft | confirmed
+- Owner: {{OWNER_OR_TEAM}}
+- Last Updated (KST): {{UPDATED_AT_KST}}
+- Source Discovery / Batch: {{SOURCE_REF}}
+
+## Project Summary
+- {{PROJECT_SUMMARY:one-sentence summary of the project}}
+
+## Primary Domain
+- {{PRIMARY_DOMAIN:short domain phrase or undecided}}
+
+## Primary Persistence Backend
+- {{PERSISTENCE_BACKEND:primary persistence backend or storage system}}
+
+## Purpose
+- This document captures the approved cross-cutting data model baseline for the project.
+- It is a shared reference for REQ drafting, batch design, implementation, verification, migration planning, and handoff.
+
+## Scope
+- Covers core entities, relationships, states, persistence mappings, and shared consistency rules.
+- Does not duplicate full functional acceptance criteria already owned by REQ documents.
+- Does not replace ORM definitions, migration files, or generated schema artifacts.
+
+## Model Summary
+
+{{MODEL_SUMMARY_BULLETS:- - <entity name> :: <role in the system>}}
+
+## Entity: `{{ENTITY_NAME_1:primary entity}}`
+
+- Purpose: {{ENTITY_PURPOSE_1:what this entity represents}}
+- Source of Truth: {{ENTITY_SOURCE_1:table, collection, file, or service}}
+- Lifecycle: {{ENTITY_LIFECYCLE_1:created -> updated -> archived}}
+
+### Key Fields
+
+{{ENTITY_FIELDS_1:- <field name> :: <type or shape> :: <meaning>}}
+
+### Relationships
+
+{{ENTITY_RELATIONSHIPS_1:- <related entity> :: <relationship meaning>}}
+
+### State Rules
+
+{{ENTITY_STATE_RULES_1:- <state or invariant rule>}}
+
+## Entity: `{{ENTITY_NAME_2:secondary entity}}`
+
+- Purpose: {{ENTITY_PURPOSE_2:what this entity represents}}
+- Source of Truth: {{ENTITY_SOURCE_2:table, collection, file, or service}}
+- Lifecycle: {{ENTITY_LIFECYCLE_2:created -> updated -> archived}}
+
+### Key Fields
+
+{{ENTITY_FIELDS_2:- <field name> :: <type or shape> :: <meaning>}}
+
+### Relationships
+
+{{ENTITY_RELATIONSHIPS_2:- <related entity> :: <relationship meaning>}}
+
+### State Rules
+
+{{ENTITY_STATE_RULES_2:- <state or invariant rule>}}
+
+## Shared Consistency Rules
+
+{{CONSISTENCY_RULE_BULLETS:- - <uniqueness, referential, or retention rule>}}
+
+## Persistence / Integration Notes
+
+{{PERSISTENCE_NOTES_BULLETS:- - <mapping, indexing, migration, or synchronization note>}}
+
+## Current Gaps / Planned Changes
+
+{{MODEL_CURRENT_GAPS_BULLETS:- - <known model gap or planned schema change>}}
+
+## Update Triggers
+
+- Update this document when a core entity, key field, or relationship changes.
+- Update this document when lifecycle or persistence behavior changes.
+- Update this document when a batch introduces a migration, backfill, or breaking data assumption.
+
+## Change Log
+
+{{CHANGE_LOG_BULLETS:- - <change log entry>}}
@@ -0,0 +1,224 @@
+# 0. 문서 상태
+이 문서의 현재 상태와 식별 정보를 기록한다. 문서 추적과 승인 흐름에 필요한 최소 메타데이터를 적는다.
+
+- 상태: {{DOC_STATUS:draft|review|confirmed}}
+- 문서 ID: {{DISCOVERY_ID:dcy-<3자리>_<YYYYMMDD>_<topic-slug>}}
+- 이슈명: {{ISSUE_NAME:짧은 한글 또는 영문 이슈명}}
+- 작성 시각(KST): {{CREATED_AT_KST:TBD}}
+- 마지막 갱신 시각(KST): {{UPDATED_AT_KST:TBD}}
+- 대체됨: {{SUPERSEDED_BY_DISCOVERY:없음 또는 docs/discovery/<DISCOVERY_ID>.md}}
+- 후속 Discovery 참조: {{FOLLOW_UP_DISCOVERY_REF:없음 또는 docs/discovery/<DISCOVERY_ID>.md}}
+- 생성된 REQ 참조: 없음
+
+# 1. 계획 상태 요약
+현재 Discovery가 어떤 배경에서 작성되고 있는지, 연계 문서가 있는지, 지금 시점의 해석이 무엇인지 짧게 요약한다.
+
+- 연계 문서 현황:
+	- 관련 점수 파일: {{RELATED_SCORE_FILE:미생성 또는 경로}}
+	- 관련 TODO/메모: {{TODO_FILE:경로 또는 없음}}
+- 해석:
+	- {{SUMMARY_LINE_1:현재 검토/작성 배경 요약}}
+	- {{SUMMARY_LINE_2:이번 Discovery에서 판단해야 할 핵심 요약}}
+
+# 2. 요구사항 판정 결과
+이번 요청이 기존 요구사항과 비교해 신규인지, 유사한지, 중복인지 판단하고 그 근거를 남긴다.
+
+- 판정: {{REQUIREMENT_CLASSIFICATION:완전 중복|유사|신규}}
+- 근거
+	- {{CLASSIFICATION_REASON_1}}
+	- {{CLASSIFICATION_REASON_2}}
+
+> **판정이 `완전 중복`인 경우**: 이하 섹션 작성을 중단하고 `# 9. 파일 처리 결과`에 중복 판정 사유와 참조 문서 경로를 기록한 뒤 문서를 닫는다. REQ 초안 작성으로 넘기지 않는다.
+
+# 3. 문제점의 요약
+문제의 현재 상태, 기대 상태, 관련 이해관계자, 제약사항을 정리한다. Discovery의 핵심 맥락을 가장 먼저 이해할 수 있어야 한다.
+
+- 현재 상태
+	- {{CURRENT_STATE_1}}
+	- {{CURRENT_STATE_2}}
+- 기대 상태
+	- {{TARGET_STATE_1}}
+	- {{TARGET_STATE_2}}
+- 이해관계자
+	- {{STAKEHOLDER_1:예. 문서 작성자(AI agent)}}
+	- {{STAKEHOLDER_2:예. 리뷰어/승인자}}
+	- {{STAKEHOLDER_3:예. 운영 담당자}}
+- 제약사항
+	- {{CONSTRAINT_1}}
+	- {{CONSTRAINT_2}}
+
+## 주요 사용자 시나리오
+사용자 또는 운영자가 실제로 어떤 상황에서 이 변경을 필요로 하는지 대표 시나리오를 적는다.
+
+- {{USER_SCENARIO_1}}
+- {{USER_SCENARIO_2}}
+- {{USER_SCENARIO_3}}
+
+# 4. 이번에 정의할 변경
+이번 Discovery에서 다루는 핵심 변경 항목을 목록으로 적는다. 기능, 구조, 규칙 변경을 함께 포함해도 된다.
+
+- {{CHANGE_ITEM_1}}
+- {{CHANGE_ITEM_2:필요 없으면 삭제}}
+- {{CHANGE_ITEM_3:필요 없으면 삭제}}
+
+## 영향 범위
+변경이 미칠 코드/문서/운영 범위를 명시해 REQ 정제와 batch planning에서 추정 누락을 줄인다.
+
+- 코드 영향:
+	- {{CODE_IMPACT_1:예. docs/discovery/index.md 갱신 로직}}
+	- {{CODE_IMPACT_2:필요 없으면 삭제}}
+- 문서 영향:
+	- {{DOC_IMPACT_1}}
+	- {{DOC_IMPACT_2:필요 없으면 삭제}}
+- 운영 영향:
+	- {{OPS_IMPACT_1:예. 배포/운영 절차 변경 없음}}
+	- {{OPS_IMPACT_2:필요 없으면 삭제}}
+
+# 5. 요구사항 목록
+실제로 구현과 검증으로 이어질 요구사항을 기능/비기능으로 나누어 정리하고, 범위 경계를 명확히 적는다.
+
+## 기능 요구사항
+- FR-1: {{FR_1}}
+- FR-2: {{FR_2}}
+- FR-3: {{FR_3:필요 없으면 삭제}}
+- FR-4: {{FR_4:필요 없으면 삭제}}
+
+## 비기능 요구사항
+성능, 운영성, 일관성, 자동화 안정성 등 기능 외 요구사항을 적는다.
+
+- NFR-1: {{NFR_1}}
+- NFR-2: {{NFR_2}}
+- NFR-3: {{NFR_3:필요 없으면 삭제}}
+
+## 범위 경계
+이번 반복에서 반드시 포함할 범위와 명시적으로 제외할 범위를 구분한다.
+
+- In Scope
+	- {{IN_SCOPE_1}}
+	- {{IN_SCOPE_2}}
+- Out of Scope
+	- {{OUT_OF_SCOPE_1}}
+	- {{OUT_OF_SCOPE_2}}
+
+# 6. 리스크/가정 목록
+불확실성과 전제 조건을 분리해서 적는다. 리스크는 영향과 완화 방안을, 가정은 현재 판단의 전제를 기록한다.
+
+## 리스크
+- R-1 ({{RISK_LEVEL_1:High|Medium|Low}}): {{RISK_1}}
+	- 완화 방안: {{MITIGATION_1}}
+- R-2 ({{RISK_LEVEL_2:High|Medium|Low}}): {{RISK_2}}
+	- 완화 방안: {{MITIGATION_2}}
+- R-3 ({{RISK_LEVEL_3:High|Medium|Low}}): {{RISK_3:필요 없으면 삭제}}
+	- 완화 방안: {{MITIGATION_3:필요 없으면 삭제}}
+
+## 가정
+아직 확정되지 않았지만 현재 문서 작성의 기반이 되는 전제를 적는다.
+
+- A-1: {{ASSUMPTION_1}}
+- A-2: {{ASSUMPTION_2}}
+- A-3: {{ASSUMPTION_3:필요 없으면 삭제}}
+
+## 오픈 질문
+답을 아직 모르는 항목을 적는다. 추정으로 덮지 말고 REQ 초안 작성 이전에 확인할 질문으로 남긴다.
+
+- OQ-1: {{OPEN_QUESTION_1}}
+	- 상태: {{OPEN_QUESTION_STATUS_1:Open|Answered|Deferred|Dropped}}
+	- 처리 방안: {{OPEN_QUESTION_ACTION_1:누가 어떤 방식으로 결정/확인할지}}
+	- 종료 조건: {{OPEN_QUESTION_EXIT_1:언제 이 질문을 Answered/Deferred/Dropped로 처리할지}}
+- OQ-2: {{OPEN_QUESTION_2}}
+	- 상태: {{OPEN_QUESTION_STATUS_2:Open|Answered|Deferred|Dropped}}
+	- 처리 방안: {{OPEN_QUESTION_ACTION_2:누가 어떤 방식으로 결정/확인할지}}
+	- 종료 조건: {{OPEN_QUESTION_EXIT_2:언제 이 질문을 Answered/Deferred/Dropped로 처리할지}}
+- OQ-3: {{OPEN_QUESTION_3:필요 없으면 삭제}}
+	- 상태: {{OPEN_QUESTION_STATUS_3:Open|Answered|Deferred|Dropped}}
+	- 처리 방안: {{OPEN_QUESTION_ACTION_3:누가 어떤 방식으로 결정/확인할지}}
+	- 종료 조건: {{OPEN_QUESTION_EXIT_3:언제 이 질문을 Answered/Deferred/Dropped로 처리할지}}
+
+### 오픈 질문 처리 기준
+- `Open`: 아직 답이 없고 다음 단계 진행에 영향이 있는 상태다. 문서에 유지한다.
+- `Answered`: 답이 확정된 상태다. 관련 본문/요구사항에 반영한 뒤 오픈 질문 목록에서는 제거하거나 resolved 기록으로 이동한다.
+- `Deferred`: 지금 단계에서 결정하지 않고 다음 단계 또는 후속 이슈로 넘기는 상태다. 넘길 대상과 이유를 반드시 적는다.
+- `Dropped`: 더 이상 유효하지 않은 질문이다. 삭제 사유를 짧게 남기고 목록에서 제거한다.
+- 처리 원칙 1: 질문만 남기지 말고 반드시 `상태`, `처리 방안`, `종료 조건`을 함께 적는다.
+- 처리 원칙 2: 답이 나온 질문은 본문 반영 없이 단순 삭제하지 않는다. 반영 위치를 먼저 갱신한다.
+- 처리 원칙 3: High 영향 질문은 `Deferred` 처리 후 처리 방안에 REQ 인계 추적 방식을 명시한다.
+
+# 7. 초기 성공 기준
+이 변경이 성공했다고 판단할 기준을 측정 가능하게 정의한다. 가능하면 데이터 출처까지 연결한다.
+
+- S-1: {{SUCCESS_METRIC_1}}
+- S-2: {{SUCCESS_METRIC_2}}
+- S-3: {{SUCCESS_METRIC_3:필요 없으면 삭제}}
+
+## 측정 방식 및 데이터 출처
+각 성공 기준을 어떻게 측정할지와 어떤 데이터나 문서를 근거로 쓸지 적는다.
+
+- S-1 측정 방식: {{MEASURE_METHOD_1}} / 데이터 출처: {{MEASURE_SOURCE_1}}
+- S-2 측정 방식: {{MEASURE_METHOD_2}} / 데이터 출처: {{MEASURE_SOURCE_2}}
+- S-3 측정 방식: {{MEASURE_METHOD_3:필요 없으면 삭제}} / 데이터 출처: {{MEASURE_SOURCE_3:필요 없으면 삭제}}
+
+# 8. REQ로 넘기기 전 확인 체크
+REQ 초안 작성 단계로 넘기기 전에 무엇이 확정되어야 하는지 확인한다. 미완료 항목은 후속 결정이 필요함을 뜻한다.
+
+- [ ] 범위(In Scope/Out of Scope) 확정
+	- 기준: {{CHECK_SCOPE_CRITERIA}}
+- [ ] 성공 지표의 측정 방식/데이터 출처 확정
+	- 기준: {{CHECK_METRICS_CRITERIA}}
+- [ ] High 영향 리스크 우선순위 및 해소 책임자 지정
+	- 기준: {{CHECK_RISK_OWNER_CRITERIA}}
+- [ ] 모든 오픈 질문(OQ) `Open` 상태 없음 확인
+	- 기준: OQ 목록에 `Open` 상태 항목이 0개이거나, 잔여 항목 전부 `Deferred` 처리 완료
+- [ ] Freeze 확정 담당자(CONFIRMED_BY) 지정
+	- 기준: {{CHECK_CONFIRMEDBY_CRITERIA}}
+
+# 9. 파일 처리 결과
+이 Discovery 문서 생성/갱신 결과와 참조 문서를 기록한다. 이후 추적과 리뷰 시 근거로 사용한다.
+
+- 처리 결과: {{FILE_RESULT:생성|갱신|미생성}}
+- 생성 경로: {{OUTPUT_PATH}}
+- 참조 문서:
+	- {{REFERENCE_1}}
+	- {{REFERENCE_2}}
+	- {{REFERENCE_3:필요 없으면 삭제}}
+
+# 10. 사용자 결정 필요 항목 요약
+사용자나 승인자가 결정해야 하는 항목만 모아 정리한다. 결정, 확인, 데이터 요청을 구분해서 적는다.
+
+## DECIDE
+- {{DECIDE_ITEM_1}}
+- {{DECIDE_ITEM_2:필요 없으면 삭제}}
+
+## CONFIRM
+- {{CONFIRM_ITEM_1}}
+- {{CONFIRM_ITEM_2:필요 없으면 삭제}}
+
+## DATA
+- {{DATA_ITEM_1}}
+- {{DATA_ITEM_2:필요 없으면 삭제}}
+
+# 11. Discovery Freeze
+REQ 초안 작성 인계 시점의 확정 플래그와 섹션 참조만 기록한다. 내용 재작성 없이 원본 섹션을 링크로 대신한다.
+
+## 섹션 참조
+- 범위: [# 5. 요구사항 목록 > 범위 경계](#5-요구사항-목록)
+- 리스크/오픈 질문: [# 6. 리스크/가정 목록](#6-리스크가정-목록)
+- 성공 기준: [# 7. 초기 성공 기준](#7-초기-성공-기준)
+- 인계 전 확인: [# 8. REQ로 넘기기 전 확인 체크](#8-req로-넘기기-전-확인-체크)
+- 사용자 결정 필요: [# 10. 사용자 결정 필요 항목 요약](#10-사용자-결정-필요-항목-요약)
+
+## Freeze 플래그
+- Handoff Decision: {{FREEZE_HANDOFF_DECISION:REQ Drafting 진행 가능|보류}}
+- Handoff Rationale: {{FREEZE_HANDOFF_RATIONALE:진행 가능 또는 보류 판단 근거 1-2줄}}
+- Ready for REQ Drafting: {{READY_FOR_REQ_DRAFTING:false}}
+- Confirmed By: {{CONFIRMED_BY:TBD}}
+- Confirmed At (KST): {{CONFIRMED_AT_KST:TBD}}
+
+# 12. 작성 가이드
+템플릿 사용 시의 기본 규칙을 적는다. 실제 문서를 만들 때는 이 가이드를 기준으로 플레이스홀더를 치환한다.
+
+- 이 파일은 템플릿이다. 실제 문서 작성 시 `{{...}}` 플레이스홀더를 구체 값으로 교체한다.
+- 필요 없는 항목은 삭제하고, 부족한 항목은 같은 형식으로 추가한다.
+- Open Questions는 가정으로 대체하지 말고 그대로 유지한다.
+- `대체됨`은 현재 Discovery가 더 이상 기준 문서가 아닐 때 대체 Discovery 경로를 기록하고, 해당 사항이 없으면 `없음`으로 둔다.
+- `후속 Discovery 참조`는 범위를 이어받는 별도 Discovery가 생성된 경우 그 Discovery 경로를 기록하고, 없으면 `없음`으로 둔다.
+- Discovery Freeze는 문서 하단에 반드시 유지한다.
@@ -0,0 +1,8 @@
+# Discovery 전체 인덱스
+
+<!-- 아래 테이블은 /new-discovery 실행 시 자동 갱신된다. 수동 편집 금지. -->
+
+## Discovery 목록
+
+| ID | 날짜 | 이슈명 | 문서 | 상태 |
+|---|---|---|---|---|
@@ -0,0 +1,92 @@
+# {{PROJECT_NAME}} Interface Contract
+
+- Baseline Mode: {{BASELINE_MODE:declared|observed|mixed}}
+- Baseline Seed: {{BASELINE_SEED_PATH:.stagepilot/bootstrap/baseline.yaml}}
+- Status: draft | confirmed
+- Owner: {{OWNER_OR_TEAM}}
+- Last Updated (KST): {{UPDATED_AT_KST}}
+- Source Discovery / Batch: {{SOURCE_REF}}
+- Primary Runtime: {{PRIMARY_RUNTIME:cli|api-service|web-app|worker|library|mixed|other}}
+
+## Project Summary
+- {{PROJECT_SUMMARY:one-sentence summary of the project}}
+
+## Primary Domain
+- {{PRIMARY_DOMAIN:short domain phrase or undecided}}
+
+## Purpose
+- This document captures the approved external and cross-boundary interface contracts for the project.
+- It is a cross-cutting reference for REQ drafting, batch design, implementation, verification, and handoff.
+
+## Scope
+- Covers externally visible APIs, CLI surfaces, events, files, or batch I/O contracts.
+- Does not duplicate full business requirements already owned by REQ documents.
+- Does not replace low-level code references or generated API artifacts.
+
+## Interface Summary
+
+{{INTERFACE_SUMMARY_BULLETS:- - <interface name> :: <purpose>}}
+
+## Interface: `{{INTERFACE_NAME_1:primary interface name}}`
+
+- Type: {{INTERFACE_TYPE_1:http-api|cli|event|file|internal-service|other}}
+- Consumers / Producers: {{INTERFACE_ACTORS_1:who calls or receives it}}
+- Purpose: {{INTERFACE_PURPOSE_1:what this interface exists to do}}
+- Stability: {{INTERFACE_STABILITY_1:experimental|internal|stable}}
+
+### Inputs
+
+{{INTERFACE_INPUTS_1:- <input field or argument> :: <meaning>}}
+
+### Outputs
+
+{{INTERFACE_OUTPUTS_1:- <output field or artifact> :: <meaning>}}
+
+### Error Contract
+
+{{INTERFACE_ERRORS_1:- <error code or condition> :: <behavior>}}
+
+### Compatibility Rules
+
+{{INTERFACE_COMPATIBILITY_1:- <versioning or compatibility rule>}}
+
+## Interface: `{{INTERFACE_NAME_2:secondary interface name}}`
+
+- Type: {{INTERFACE_TYPE_2:http-api|cli|event|file|internal-service|other}}
+- Consumers / Producers: {{INTERFACE_ACTORS_2:who calls or receives it}}
+- Purpose: {{INTERFACE_PURPOSE_2:what this interface exists to do}}
+- Stability: {{INTERFACE_STABILITY_2:experimental|internal|stable}}
+
+### Inputs
+
+{{INTERFACE_INPUTS_2:- <input field or argument> :: <meaning>}}
+
+### Outputs
+
+{{INTERFACE_OUTPUTS_2:- <output field or artifact> :: <meaning>}}
+
+### Error Contract
+
+{{INTERFACE_ERRORS_2:- <error code or condition> :: <behavior>}}
+
+### Compatibility Rules
+
+{{INTERFACE_COMPATIBILITY_2:- <versioning or compatibility rule>}}
+
+## Shared Constraints
+
+{{INTERFACE_SHARED_CONSTRAINTS_BULLETS:- - <authentication, timeout, idempotency, or size constraint>}}
+
+## Current Gaps / Planned Changes
+
+{{INTERFACE_CURRENT_GAPS_BULLETS:- - <known contract gap or planned interface change>}}
+
+## Update Triggers
+
+- Update this document when an externally visible API, event, CLI, or file contract changes.
+- Update this document when a batch changes compatibility, validation, or error behavior.
+- Update this document when a new external consumer or producer is introduced.
+
+## Change Log
+
+{{CHANGE_LOG_BULLETS:- - <change log entry>}}
@@ -0,0 +1,64 @@
+# {{PROJECT_NAME}} Project Structure
+
+- Baseline Mode: {{BASELINE_MODE:declared|observed|mixed}}
+- Baseline Seed: {{BASELINE_SEED_PATH:.stagepilot/bootstrap/baseline.yaml}}
+- Status: draft | confirmed
+- Owner: {{OWNER_OR_TEAM}}
+- Last Updated (KST): {{UPDATED_AT_KST}}
+- Source Discovery / Batch: {{SOURCE_REF}}
+
+## Project Summary
+- {{PROJECT_SUMMARY:one-sentence summary of the project}}
+
+## Primary Domain
+- {{PRIMARY_DOMAIN:short domain phrase or undecided}}
+
+## Tech Stack
+{{TECH_STACK_BULLETS:- <planned stack item 1>
+- <planned stack item 2>}}
+
+## Primary Runtime
+- Type: {{PRIMARY_RUNTIME:cli|api-service|web-app|worker|library|mixed|other}}
+- Planned Entry Points:
+{{PRIMARY_ENTRYPOINT_BULLETS:- <entrypoint> :: <purpose>}}
+
+## Purpose
+- This document is the current approved repository and package structure baseline.
+- It is a cross-cutting reference document for Discovery, REQ, Batch Design, Batch Verification, and implementation updates.
+
+## Scope
+- Covers the top-level repository layout and package/module boundaries.
+- Does not duplicate detailed business rules, acceptance criteria, or implementation-only function signatures.
+
+## Top-Level Structure
+
+```text
+{{TOP_LEVEL_STRUCTURE_TREE:<text tree baseline>}}
+```
+
+## Package / Module Responsibilities
+
+{{MODULE_RESPONSIBILITY_BULLETS:- `<path-or-package-1>`
+  - <responsibility summary>}}
+
+## Dependency Rules
+
+{{DEPENDENCY_RULE_BULLETS:- <dependency rule 1>}}
+
+## Shared Boundaries
+
+{{SHARED_BOUNDARY_BULLETS:- <shared boundary 1>}}
+
+## Current Gaps / Planned Changes
+
+{{CURRENT_GAPS_BULLETS:- <gap or planned structural change 1>}}
+
+## Update Triggers
+
+- Update this document when package boundaries change.
+- Update this document when new top-level runtime or domain modules are added.
+- Update this document when a batch changes the approved structure baseline.
+
+## Change Log
+
+{{CHANGE_LOG_BULLETS:- - <change log entry>}}
@@ -0,0 +1,10 @@
+# Release Index
+
+## 목적
+- 이 문서는 release 단위의 전역 인덱스다.
+- 각 release는 하나 이상의 release-candidate batch를 묶고, profile(`docs-only` | `tooling` | `app-service`)에 맞는 배포와 후속 환류를 추적한다.
+
+## Release Register
+
+| REL ID | Profile | Status | Included Batch | Discovery/REQ Input | Link |
+| --- | --- | --- | --- | --- | --- |
@@ -0,0 +1,92 @@
+# {{REL_ID}}: <릴리즈 제목>
+
+- Status: draft | confirmed | released | feedback-captured
+- Profile: docs-only | tooling | app-service
+- Included Batch: <BAT-ID 목록>
+
+## Scope
+- Included:
+  - <포함 batch 또는 REQ>
+- Excluded:
+  - <제외 범위>
+
+## Rollout Plan
+1. <배포 순서>
+2. <배포 순서>
+
+## Rollback Plan
+- <롤백 조건과 절차>
+
+## Verification Checklist
+- <배포 전 확인>
+- <배포 후 확인>
+
+## Release Execution Evidence
+- Release Status Transition Target: released
+
+### Deployment Facts
+- Executed At:
+  - <배포 시작 시각>
+- Completed At:
+  - <배포 완료 시각>
+- Environment:
+  - <배포 대상 환경>
+- Operator:
+  - <배포 수행자>
+- Revision or Artifact:
+  - <커밋 SHA 또는 배포 artifact 식별자>
+- Commands or Procedure:
+  - <실행 명령 또는 배포 절차 요약>
+
+### Profile-Specific Checks
+- docs-only:
+  - Published or Packaged Targets:
+    - <문서 경로, 배포 산출물 또는 none>
+  - Link or Rendering Check:
+    - <링크 점검, 렌더링 확인 또는 none>
+  - Navigation or Consumer Update:
+    - <목차/가이드/릴리즈 노트 반영 결과 또는 none>
+- tooling:
+  - Install or Upgrade Smoke:
+    - <설치/업데이트/부트스트랩 결과 또는 none>
+  - CLI or Script Execution:
+    - <명령 실행 결과 또는 none>
+  - Compatibility Note:
+    - <하위 호환성/운영자 영향 또는 none>
+- app-service:
+  - Health Endpoint:
+    - <호출 결과와 확인 시각>
+  - Startup Log Fields:
+    - <app, event, command, run_id 확인 결과>
+  - Request Log Fields:
+    - <request_id 포함 여부와 확인 결과>
+  - Smoke or Manual Verification:
+    - <배포 후 재실행한 검증과 결과>
+
+### Rollback Outcome
+- Rollback Required:
+  - <yes 또는 no>
+- Rollback Trigger:
+  - <발생 시 원인, 없으면 none>
+- Rollback Action:
+  - <수행한 조치, 없으면 none>
+
+### Release Decision Evidence
+- Released Decision:
+  - <released 전환 여부>
+- Rationale:
+  - <released 전환 판단 근거>
+- Recorded By:
+  - <기록자>
+- Recorded At:
+  - <기록 시각>
+
+## Feedback Handoff
+- Observation Summary:
+  - <운영 관찰 사실 요약 또는 없음>
+- Discovery Input:
+  - <후속 discovery 후보>
+- REQ Input:
+  - <후속 req 후보>
+- Change Request Input:
+  - <기존 req 변경 후보>
@@ -0,0 +1,58 @@
+# {{PROJECT_NAME}} Runtime Flows
+
+- Baseline Mode: {{BASELINE_MODE:declared|observed|mixed}}
+- Baseline Seed: {{BASELINE_SEED_PATH:.stagepilot/bootstrap/baseline.yaml}}
+- Status: draft | confirmed
+- Owner: {{OWNER_OR_TEAM}}
+- Last Updated (KST): {{UPDATED_AT_KST}}
+- Source Discovery / Batch: {{SOURCE_REF}}
+- Primary Runtime: {{PRIMARY_RUNTIME:cli|api-service|web-app|worker|library|mixed|other}}
+
+## Project Summary
+- {{PROJECT_SUMMARY:one-sentence summary of the project}}
+
+## Purpose
+- This document is the current approved execution-flow baseline for the project.
+- It is a cross-cutting reference document for Discovery, REQ, Batch Design, Batch Verification, and implementation updates.
+
+## Scope
+- Covers representative command and runtime flows.
+- Does not duplicate full acceptance criteria or low-level implementation details.
+
+## Covered Entry Points
+
+{{PRIMARY_ENTRYPOINT_BULLETS:- <entry-point-1> :: <purpose>}}
+
+## Shared Components
+
+{{SHARED_COMPONENT_BULLETS:- <shared component or service 1>}}
+
+## Flow: `{{FLOW_NAME_1:bootstrap or first runtime flow}}`
+
+{{FLOW_STEPS_1:1. <step 1>
+2. <step 2>
+3. <step 3>}}
+
+## Flow: `{{FLOW_NAME_2:secondary runtime flow or operation}}`
+
+{{FLOW_STEPS_2:1. <step 1>
+2. <step 2>
+3. <step 3>}}
+
+## Flow Constraints
+
+{{FLOW_CONSTRAINT_BULLETS:- <flow constraint 1>}}
+
+## Current Gaps / Planned Changes
+
+{{CURRENT_GAPS_BULLETS:- <gap or planned flow change 1>}}
+
+## Update Triggers
+
+- Update this document when a command entry point changes.
+- Update this document when a runtime orchestration path changes.
+- Update this document when a batch changes the approved flow baseline.
+
+## Change Log
+
+{{CHANGE_LOG_BULLETS:- - <change log entry>}}
@@ -0,0 +1,87 @@
+# Software Requirement Specification Index
+
+## 목적
+- 이 문서는 프로젝트의 SRS 운영 기준과 requirement 목록을 관리하는 entry point이다.
+- 개별 requirement의 상세 내용은 타입별 폴더 하위 `req-XXX_*.md` 파일에서 관리한다.
+
+## 사용 방법
+1. 새로운 requirement가 필요하면 `Next Requirement ID`를 확인하고 `docs/srs/req-template.md`를 복사해 `docs/srs/<Type>/req-XXX_<slug>.md` 파일을 생성한다.
+2. 초안 작성은 `draft-req`, 승인 전환은 `confirm-req`, 변경 대응은 `change-req`, 구현 완료 전환은 `confirm-req-implemented` skill을 기준으로 수행한다.
+3. 작성 또는 수정 후 누락과 모호성을 점검한다.
+4. requirement 추가 또는 변경 후 `Next Requirement ID`, `Requirement Register`, `Recent Change Log Summary`를 함께 갱신한다.
+5. `Proposed` requirement를 승인하려면 승인 준비 상태와 blocker를 점검한다.
+6. `Approved` requirement는 구현 이슈나 작업 항목으로 연결한다.
+7. 구현과 검증이 끝난 requirement는 `confirm-req-implemented` skill로 완료 전환 가능 여부를 점검한다.
+8. requirement 변경 시 `change-req` skill을 기준으로 해당 REQ 파일의 `Change Log`를 먼저 갱신한 뒤 본문을 수정한다.
+9. 구현 전에는 관련 REQ 파일과 최근 `Change Log`를 기준으로 변경 범위를 판단한다.
+
+## 상태 정의
+- Proposed: 초안 상태이며 구현 기준으로 확정되지 않음
+- Approved: 구현 기준으로 승인됨
+- Implemented: 구현과 검증이 완료됨
+- Deprecated: 더 이상 유지하지 않음
+
+## Status Transition Evidence
+
+### Proposed -> Approved
+- `Status`, `Type`, `Priority`, `Owner`, `Intent`, `Requirement`, `Acceptance Criteria`, `Impacted Area`, `Change Log`가 모두 존재해야 한다.
+- `Type`은 아래 분류 도표에서 정확하게 하나로 지정되어야 한다.
+- `Acceptance Criteria`는 구현 판단에 사용할 수 있을 정도로 구체적이어야 한다.
+- 미해결 assumption 또는 open question이 있으면 `Notes`에 명시하고, 승인 blocker 여부를 판단해야 한다.
+- 승인 전환 시 해당 REQ 파일의 `Change Log`에 status 변경 사유를 기록해야 한다.
+
+### Approved -> Implemented
+- 각 `Acceptance Criteria`에 대해 test, manual verification, 또는 구현 결과 중 최소 1개의 evidence가 있어야 한다.
+- evidence는 requirement 문서 자체 또는 연결된 구현/검증 결과에서 추적 가능해야 한다.
+- 미충족 `Acceptance Criteria`가 있으면 `Implemented`로 전환하지 않는다.
+- 구현 완료 전환 시 잔여 리스크와 미검증 영역이 있으면 `Change Log`에 기록해야 한다.
+- 상태 전환은 `confirm-req-implemented` skill을 기준으로 수행한다.
+
+### Requirement Change Handling
+- 기존 REQ 본문(`Requirement`, `Acceptance Criteria`, `Impacted Area`)을 수정하기 전에는 새 `Change Log` 항목을 만든다.
+- `Change Log`에는 최소한 `Acceptance Criteria Delta`, `Impacted Area Delta`, `Delivery Trace Delta`, `Revalidation Impact`, `Validation Plan`이 포함되어야 한다.
+- 변경이 기존 구현 또는 verification evidence를 무효화하면 `Implemented` requirement는 `Approved`로 되돌린다.
+- 변경이 승인 전제 자체를 다시 검토하게 만들면 `Approved` 또는 `Implemented` requirement를 `Proposed`로 되돌릴 수 있다.
+- 상태 되돌림이 발생하면 `Requirement Register`와 `Recent Change Log Summary`도 함께 갱신한다.
+
+## Requirement 타입 분류 도표
+
+| 타입 | 정의 | 예시 |
+|------|------|------|
+| **Configuration** | 설정 옵션, 커스터마이징 포인트 | 설정 파라미터, 환경 변수, 옵션 항목 |
+| **Data** | 데이터 구조, 저장/로드, 파일 형식, 스키마 | 설정 파일 형식, DB 스키마, API 구조 |
+| **Deployment** | 배포 방식, 운영 절차, 배포 환경 | 컨테이너 배포, 스택 관리, 운영 가이드 |
+| **Documentation** | 문서 작성, 가이드, 매뉴얼, 안내서 | 사용자 가이드, API 문서, 튜토리얼 |
+| **Exception** | 오류 처리, 예외 복구, 재시도 전략 | 오류 복구, 검증 실패 처리, 폴백 전략 |
+| **Installation** | 시스템 설치, 환경 구성, 초기화 절차 | Docker 이미지 빌드, DB 마이그레이션, 사전 조건 설정 |
+| **Integration** | 외부 시스템 연동, 플러그인, 확장 | 3rd party 연동, 플러그인 인터페이스 |
+| **Interface** | 사용자 상호작용 방식 (UI, API, CLI, 제어방식) | CLI 명령어, API 엔드포인트, 웹 UI 기능 |
+| **Migration** | 데이터 이전, 버전 업그레이드 | 데이터 마이그레이션, 버전 호환성 |
+| **Non-Functional** | 성능, 보안, 확장성, 호환성, 신뢰성 | 성능 목표, 보안 정책, 확장성 |
+| **Testing** | 테스트 전략, QA 요구사항, 검증 방식 | 테스트 커버리지, 회귀 테스트, 수락 기준 |
+
+## Requirement 작성 규칙
+- 각 requirement는 고유 ID를 가진다. 예: `REQ-001`
+- 다음 신규 requirement 번호의 source of truth는 이 문서의 `Next Requirement ID` 섹션이다.
+- 새 requirement를 추가하거나 ID 충돌이 발생할 수 있는 변경을 했으면 `Next Requirement ID`를 함께 갱신한다.
+- 각 requirement는 `Type`을 명시해야 한다. 위 분류 도표 중 정확하게 하나로 선택하며, `docs/srs/<Type>/` 폴더명도 같은 문자열을 사용한다.
+- 각 requirement는 `Intent`, `Requirement`, `Acceptance Criteria`, `Impacted Area`를 반드시 포함한다.
+- 모호한 표현("개선한다", "적절히 처리한다") 대신 관찰 가능하고 test 가능한 문장을 사용한다.
+- requirement 변경 사항은 해당 REQ 파일의 `Change Log`에 기록한다.
+- requirement 변경 시 영향 받는 batch/release와 재검증 필요 여부를 `Change Log`에 남긴다.
+- `Recent Change Log Summary`는 최신 5건만 유지한다.
+- status 전환은 `Status Transition Evidence` 기준을 따른다.
+
+## Next Requirement ID
+
+- Current: `REQ-001`
+- Rule: `Requirement Register`에 있는 가장 큰 REQ 번호보다 정확히 1 커야 한다.
+
+## Requirement Register
+
+| ID | Title | Type | Status | Priority | Owner | Link |
+| --- | --- | --- | --- | --- | --- | --- |
+
+## Recent Change Log Summary
+
+- 없음
@@ -0,0 +1,67 @@
+# req-XXX: <요구사항 제목>
+
+- Status: Proposed | Approved | Implemented | Deprecated
+- Type: Configuration | Data | Deployment | Documentation | Exception | Installation | Integration | Interface | Migration | Non-Functional | Testing
+- Priority: High | Medium | Low
+- Owner: <담당자 또는 팀>
+
+## Intent
+- <이 요구사항이 필요한 이유와 달성하려는 목표를 1~3문장으로 작성>
+
+## Requirement
+- <시스템이 반드시 수행해야 하는 동작을 단정형 문장으로 작성>
+
+## Acceptance Criteria
+1. Given <선행 조건>, When <행동>, Then <기대 결과>
+2. Given <선행 조건>, When <행동>, Then <기대 결과>
+
+## Impacted Area
+- Docs: <영향 받는 문서 경로>
+- Modules: <영향 받는 모듈/컴포넌트>
+- Tests: <추가/수정해야 하는 테스트>
+
+## Notes
+- <가정, 제약, 미해결 이슈>
+
+## Change Log
+
+### CHG-YYYYMMDD-01
+- Date: YYYY-MM-DD
+- Author: <작성자>
+
+#### Change Summary
+- <무엇이 변경되었는지>
+
+#### Intent
+- <왜 변경했는지>
+
+#### Acceptance Criteria Delta
+- Added:
+  - <추가된 기준>
+- Updated:
+  - <변경된 기준>
+- Removed:
+  - <삭제된 기준>
+
+#### Impacted Area Delta
+- Docs:
+  - <문서 영향>
+- Modules:
+  - <코드 영향>
+- Tests:
+  - <테스트 영향>
+
+#### Delivery Trace Delta
+- Batches:
+  - <영향 받는 batch 또는 none>
+- Releases:
+  - <영향 받는 release 또는 none>
+
+#### Revalidation Impact
+- Reverification Needed: yes | no
+- Existing Implementation Invalidated: yes | no
+- Status Recommendation: keep-current | revert-to-approved | revert-to-proposed
+- Follow-up Action: <필요한 재검증, 재배치, 후속 작업>
+
+#### Validation Plan
+- <검증 방법과 완료 조건>