Squashed '.stage-pilot/' content from commit 2c0510c

git-subtree-dir: .stage-pilot git-subtree-split: 2c0510c68add43c50adcdedb30c174e68e730395
2026-06-03 08:56:02 +00:00
commit 9339d3d503
100 changed files with 8843 additions and 0 deletions
@@ -0,0 +1,115 @@
+schema_version: 1
+capture_mode: declared
+
+project:
+  repository_name: sample-host-project
+  display_name: Sample Host Project
+  summary: Python-based API service for curated market data analysis.
+  primary_domain: financial analytics
+
+stack:
+  tech_stack:
+    - Python
+    - FastAPI
+    - PostgreSQL
+
+runtime:
+  primary_runtime: api-service
+  primary_entrypoints:
+    - name: uvicorn src.main:app
+      purpose: serve the HTTP API
+    - name: python -m src.jobs.refresh_market_data
+      purpose: refresh curated market data snapshots
+
+interfaces:
+  contracts:
+    - name: HTTP market data API
+      type: http-api
+      actors: internal dashboards and downstream service clients
+      purpose: serve curated market data and derived analytics to clients
+      stability: experimental
+      inputs:
+        - client requests for curated market data and analytics
+      outputs:
+        - JSON market snapshot payloads and derived analytics payloads
+      errors:
+        - 404 not_found :: symbol is not available in the curated dataset
+        - 503 upstream_unavailable :: refreshed data is temporarily unavailable
+      compatibility_rules:
+        - response payload changes should remain backward compatible within the same API version
+    - name: Refresh job command
+      type: cli
+      actors: operators and scheduled automation
+      purpose: update stored market data snapshots from upstream sources
+      stability: internal
+      inputs:
+        - python -m src.jobs.refresh_market_data :: trigger a refresh of curated market data snapshots
+      outputs:
+        - refreshed local snapshot artifacts persisted for later API reads
+      errors:
+        - non-zero exit code :: refresh failed and data should be treated as stale
+      compatibility_rules:
+        - command arguments and exit-code semantics should remain stable for automation callers
+  shared_constraints:
+    - all interfaces assume symbol identifiers are validated before persistence or response rendering
+    - refresh failures must not silently overwrite previously known-good snapshots
+  current_gaps:
+    - authentication and authorization rules are not defined yet
+    - API versioning strategy is still undecided
+
+structure:
+  planned_top_level_areas:
+    - path: src/
+      responsibility: application code and background jobs
+    - path: scripts/
+      responsibility: developer and operator helper commands
+    - path: tests/
+      responsibility: automated validation and regression coverage
+
+data_model:
+  persistence_backend: PostgreSQL
+  entities:
+    - name: Market Snapshot
+      purpose: represent the latest curated market data for a tracked symbol
+      source_of_truth: PostgreSQL market_snapshots table
+      lifecycle: collected -> normalized -> published -> superseded
+      key_fields:
+        - symbol :: string :: tracked market identifier
+        - captured_at :: timestamp :: time the upstream data snapshot was collected
+        - payload :: json :: normalized market data stored for API responses and analytics inputs
+      relationships:
+        - Analytics Snapshot :: derived from one published Market Snapshot
+      state_rules:
+        - only one published snapshot per symbol should be treated as current
+        - superseded snapshots remain queryable for audit or replay use cases
+    - name: Analytics Snapshot
+      purpose: represent derived metrics computed from a market snapshot
+      source_of_truth: PostgreSQL analytics_snapshots table
+      lifecycle: queued -> computed -> published -> superseded
+      key_fields:
+        - symbol :: string :: tracked market identifier
+        - derived_at :: timestamp :: time analytics were computed
+        - metrics :: json :: derived indicators and summary values
+      relationships:
+        - Market Snapshot :: source snapshot used to compute analytics
+      state_rules:
+        - published analytics must reference an existing published or superseded market snapshot
+        - analytics should be recomputed whenever a new published market snapshot replaces the current one
+  consistency_rules:
+    - symbol identifiers must remain consistent across snapshot and analytics entities
+    - analytics records must not exist without a corresponding source market snapshot
+  persistence_notes:
+    - refresh jobs write Market Snapshot rows before recomputing Analytics Snapshot rows
+    - future retention and archival policies are not defined yet
+  current_gaps:
+    - exact table schema and indexing strategy are still undecided
+    - historical retention policy is still undecided
+
+notes:
+  known_unknowns:
+    - deployment target is undecided
+
+metadata:
+  captured_at_kst: 2026-04-30 16:20
+  source: bootstrap-baseline-questionnaire
+  updated_from: user-answer
@@ -0,0 +1,38 @@
+# Bootstrap Baseline Example
+
+이 예시는 fresh host 저장소에 StagePilot을 설치한 뒤 `/bootstrap-baseline`을 실행했을 때 남아야 하는 최소 active baseline 상태를 보여 준다.
+
+## Scenario
+
+1. host 저장소에 StagePilot을 설치했다.
+2. 아직 Discovery, REQ, Batch, Release 문서는 하나도 없었다.
+3. doctor를 실행하면 `INFO [bootstrap-required]`로 `/bootstrap-baseline`이 필요하다는 안내가 나온다.
+4. `/bootstrap-baseline`이 최소 질문 세트를 받고 `.stage-pilot/bootstrap/baseline.yaml`을 만든 뒤 baseline 문서와 active index를 초기화했다.
+5. 첫 real Discovery는 아직 시작하지 않았고, 이 예시는 그 직후 상태를 보여 준다.
+
+## Files to inspect
+
+- `doctor-before-bootstrap-output.md`
+  - bootstrap 이전 fresh host 저장소에서 기대하는 doctor 출력 예시다.
+- `bootstrap-baseline-output.md`
+  - `/bootstrap-baseline` 실행 결과 예시다.
+- `.stage-pilot/bootstrap/baseline.yaml`
+  - bootstrap 질문 답변을 저장한 seed file 예시다.
+- `docs/project-structure.md`
+  - bootstrap으로 생성된 구조 baseline 초안 예시다.
+- `docs/runtime-flows.md`
+  - bootstrap으로 생성된 runtime flow baseline 초안 예시다.
+- `docs/interface-contract.md`
+  - bootstrap으로 생성된 인터페이스 계약 baseline 초안 예시다.
+- `docs/data-model.md`
+  - bootstrap으로 생성된 데이터 모델 baseline 초안 예시다.
+- `docs/discovery/index.md`, `docs/srs/index.md`, `docs/batches/index.md`, `docs/releases/index.md`
+  - 첫 real Discovery 전까지 비어 있어도 되는 register 골격이다.
+
+## Validation
+
+이 예시 루트는 doctor로 독립 검증할 수 있다.
+
+```bash
+python3 .stage-pilot/tools/stagepilot-doctor.py examples/bootstrap-baseline
+```
@@ -0,0 +1,45 @@
+# Sample Output: bootstrap-baseline
+
+- Input:
+  - fresh host repository after StagePilot install
+- Asked Questions:
+  - `project-summary` -> `Python-based API service for curated market data analysis`
+  - `primary-domain` -> `financial analytics`
+  - `tech-stack` -> `Python, FastAPI, PostgreSQL`
+  - `primary-runtime` -> `api-service`
+  - `primary-entrypoints` -> `uvicorn src.main:app :: serve the HTTP API`, `python -m src.jobs.refresh_market_data :: refresh curated market data snapshots`
+  - `interface-contracts` -> `HTTP market data API :: http-api :: internal dashboards and downstream service clients :: serve curated market data and derived analytics to clients`, `Refresh job command :: cli :: operators and scheduled automation :: update stored market data snapshots from upstream sources`
+  - `interface-inputs` -> `HTTP market data API :: GET /markets/{symbol} :: request the current curated snapshot for a symbol`, `HTTP market data API :: GET /analytics/{symbol} :: request derived analytics for a symbol`, `Refresh job command :: python -m src.jobs.refresh_market_data :: trigger a refresh of curated market data snapshots`
+  - `interface-outputs` -> `HTTP market data API :: JSON market snapshot payload :: current normalized market data for the requested symbol`, `HTTP market data API :: JSON analytics payload :: derived analytics and summary metrics for the requested symbol`, `Refresh job command :: refreshed local snapshot artifacts :: normalized data persisted for later API reads`
+  - `interface-errors` -> `HTTP market data API :: 404 not_found :: symbol is not available in the curated dataset`, `HTTP market data API :: 503 upstream_unavailable :: refreshed data is temporarily unavailable`, `Refresh job command :: non-zero exit code :: refresh failed and data should be treated as stale`
+  - `core-entities` -> `Market Snapshot :: represent the latest curated market data for a tracked symbol`, `Analytics Snapshot :: represent derived metrics computed from a market snapshot`
+  - `persistence-backend` -> `PostgreSQL`
+  - `compatibility-rules` -> `HTTP market data API :: response payload changes should remain backward compatible within the same API version`, `Refresh job command :: command arguments and exit-code semantics should remain stable for automation callers`
+- Created Files:
+  - `.stage-pilot/bootstrap/baseline.yaml`
+  - `docs/discovery/index.md`
+  - `docs/srs/index.md`
+  - `docs/batches/index.md`
+  - `docs/releases/index.md`
+  - `docs/project-structure.md`
+  - `docs/runtime-flows.md`
+  - `docs/interface-contract.md`
+  - `docs/data-model.md`
+- Seed Status:
+  - `.stage-pilot/bootstrap/baseline.yaml`: created
+- Baseline Status:
+  - `docs/project-structure.md`: created
+  - `docs/runtime-flows.md`: created
+  - `docs/interface-contract.md`: created
+  - `docs/data-model.md`: created
+- Index Status:
+  - `docs/discovery/index.md`: created
+  - `docs/srs/index.md`: created
+  - `docs/batches/index.md`: created
+  - `docs/releases/index.md`: created
+- Notes:
+  - baseline docs were rendered from `.stage-pilot/bootstrap/baseline.yaml`
+  - no Discovery document was created
+  - no REQ, Batch, or Release unit was opened
+- Next Action:
+  - `/new-discovery <actual product or service change topic>`
@@ -0,0 +1,6 @@
+# Batch Index
+
+## Batch Register
+
+| BAT ID | Profile | Status | Included REQ | Discovery | Folder |
+| --- | --- | --- | --- | --- | --- |
@@ -0,0 +1,97 @@
+# Sample Host Project Data Model
+
+- Baseline Mode: declared
+- Baseline Seed: .stage-pilot/bootstrap/baseline.yaml
+- Status: confirmed
+- Owner: Platform Team
+- Last Updated (KST): 2026-04-30 16:30
+- Source Discovery / Batch: bootstrap-baseline
+
+## Project Summary
+- Python-based API service for curated market data analysis.
+
+## Primary Domain
+- financial analytics
+
+## Primary Persistence Backend
+- PostgreSQL
+
+## Purpose
+- This document captures the initial data model baseline after StagePilot bootstrap.
+- It provides a shared reference for later REQ, delivery, migration, and verification work.
+
+## Scope
+- Covers core entities, relationships, lifecycle rules, and persistence assumptions for the sample host project.
+- Does not replace ORM code, migrations, or detailed acceptance criteria.
+
+## Model Summary
+
+- Market Snapshot :: normalized raw and curated market data for a tracked symbol
+- Analytics Snapshot :: derived metrics computed from a Market Snapshot
+
+## Entity: `Market Snapshot`
+
+- Purpose: represent the latest curated market data for a tracked symbol
+- Source of Truth: PostgreSQL `market_snapshots` table
+- Lifecycle: collected -> normalized -> published -> superseded
+
+### Key Fields
+
+- `symbol` :: string :: tracked market identifier
+- `captured_at` :: timestamp :: time the upstream data snapshot was collected
+- `payload` :: json :: normalized market data stored for API responses and analytics inputs
+
+### Relationships
+
+- `Analytics Snapshot` :: derived from one published Market Snapshot
+
+### State Rules
+
+- only one published snapshot per symbol should be treated as current
+- superseded snapshots remain queryable for audit or replay use cases
+
+## Entity: `Analytics Snapshot`
+
+- Purpose: represent derived metrics calculated from a market snapshot
+- Source of Truth: PostgreSQL `analytics_snapshots` table
+- Lifecycle: queued -> computed -> published -> superseded
+
+### Key Fields
+
+- `symbol` :: string :: tracked market identifier
+- `derived_at` :: timestamp :: time analytics were computed
+- `metrics` :: json :: derived indicators and summary values
+
+### Relationships
+
+- `Market Snapshot` :: source snapshot used to compute analytics
+
+### State Rules
+
+- published analytics must reference an existing published or superseded market snapshot
+- analytics should be recomputed whenever a new published market snapshot replaces the current one
+
+## Shared Consistency Rules
+
+- `symbol` identifiers must remain consistent across snapshot and analytics entities
+- analytics records must not exist without a corresponding source market snapshot
+
+## Persistence / Integration Notes
+
+- refresh jobs write Market Snapshot rows before recomputing Analytics Snapshot rows
+- future retention and archival policies are not defined yet
+
+## Current Gaps / Planned Changes
+
+- exact table schema and indexing strategy are still undecided
+- historical retention policy is still undecided
+
+## 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
+
+- 2026-04-30: bootstrap-baseline created the initial data model baseline from declared project inputs.
@@ -0,0 +1,8 @@
+# Discovery 전체 인덱스
+
+<!-- 아래 테이블은 /new-discovery 실행 시 자동 갱신된다. 수동 편집 금지. -->
+
+## Discovery 목록
+
+| ID | 날짜 | 이슈명 | 문서 | 상태 |
+|---|---|---|---|---|
@@ -0,0 +1,97 @@
+# Sample Host Project Interface Contract
+
+- Baseline Mode: declared
+- Baseline Seed: .stage-pilot/bootstrap/baseline.yaml
+- Status: confirmed
+- Owner: Platform Team
+- Last Updated (KST): 2026-04-30 16:30
+- Source Discovery / Batch: bootstrap-baseline
+- Primary Runtime: api-service
+
+## Project Summary
+- Python-based API service for curated market data analysis.
+
+## Primary Domain
+- financial analytics
+
+## Purpose
+- This document captures the initial interface contract baseline after StagePilot bootstrap.
+- It provides a shared reference for future REQ, design, implementation, and verification work.
+
+## Scope
+- Covers the planned API and job interfaces exposed by the sample host project.
+- Does not duplicate detailed acceptance criteria or generated OpenAPI/schema artifacts.
+
+## Interface Summary
+
+- HTTP market data API :: serve curated market data and derived analytics to clients
+- Refresh job command :: update stored market data snapshots from upstream sources
+
+## Interface: `HTTP market data API`
+
+- Type: http-api
+- Consumers / Producers: internal dashboards and downstream service clients
+- Purpose: serve curated market data and derived analytics to clients
+- Stability: experimental
+
+### Inputs
+
+- `GET /markets/{symbol}` :: request the current curated snapshot for a symbol
+- `GET /analytics/{symbol}` :: request derived analytics for a symbol
+
+### Outputs
+
+- JSON market snapshot payload :: current normalized market data for the requested symbol
+- JSON analytics payload :: derived analytics and summary metrics for the requested symbol
+
+### Error Contract
+
+- `404 not_found` :: symbol is not available in the curated dataset
+- `503 upstream_unavailable` :: refreshed data is temporarily unavailable
+
+### Compatibility Rules
+
+- response payload changes should remain backward compatible within the same API version
+
+## Interface: `Refresh job command`
+
+- Type: cli
+- Consumers / Producers: operators and scheduled automation
+- Purpose: update stored market data snapshots from upstream sources
+- Stability: internal
+
+### Inputs
+
+- `python -m src.jobs.refresh_market_data` :: trigger a refresh of curated market data snapshots
+
+### Outputs
+
+- refreshed local snapshot artifacts :: normalized data persisted for later API reads
+
+### Error Contract
+
+- non-zero exit code :: refresh failed and data should be treated as stale
+
+### Compatibility Rules
+
+- command arguments and exit-code semantics should remain stable for automation callers
+
+## Shared Constraints
+
+- all interfaces assume symbol identifiers are validated before persistence or response rendering
+- refresh failures must not silently overwrite previously known-good snapshots
+
+## Current Gaps / Planned Changes
+
+- authentication and authorization rules are not defined yet
+- API versioning strategy is still undecided
+
+## 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
+
+- 2026-04-30: bootstrap-baseline created the initial interface contract baseline from declared project inputs.
@@ -0,0 +1,91 @@
+# Sample Host Project Structure
+
+- Baseline Mode: declared
+- Baseline Seed: .stage-pilot/bootstrap/baseline.yaml
+- Status: confirmed
+- Owner: Platform Team
+- Last Updated (KST): 2026-04-30 16:30
+- Source Discovery / Batch: bootstrap-baseline
+
+## Project Summary
+- Python-based API service for curated market data analysis.
+
+## Primary Domain
+- financial analytics
+
+## Tech Stack
+- Python
+- FastAPI
+- PostgreSQL
+
+## Primary Runtime
+- Type: api-service
+- Planned Entry Points:
+- uvicorn src.main:app :: serve the HTTP API
+- python -m src.jobs.refresh_market_data :: refresh curated market data snapshots
+
+## Purpose
+- This document captures the initial repository structure baseline after StagePilot bootstrap.
+- It becomes a shared reference before the first real Discovery starts.
+
+## Scope
+- Covers top-level repository layout and broad module boundaries.
+- Does not define feature-specific acceptance criteria or delivery units.
+
+## Top-Level Structure
+
+```text
+.
+├── .github/
+├── .stage-pilot/
+├── docs/
+├── src/
+├── scripts/
+├── tests/
+└── README.md
+```
+
+## Package / Module Responsibilities
+
+- `.github/`
+	- StagePilot skills, templates, and host instructions installed into the repository.
+- `.stage-pilot/`
+	- bootstrap declaration seed used to render the baseline documents.
+- `docs/`
+	- Active SDLC docs, index files, and cross-cutting baseline references.
+- `src/`
+	- Product and service implementation code.
+- `scripts/`
+	- developer and operator helper commands.
+- `tests/`
+	- Automated checks and regression coverage.
+
+## Dependency Rules
+
+- Delivery documents under `docs/` must not be treated as implementation modules.
+- `src/` can evolve independently, but structure changes should update this baseline.
+- `.stage-pilot/bootstrap/baseline.yaml` should be updated when the declared project identity changes before code exists.
+- Tooling automation under `.stage-pilot/` must not overwrite host source code.
+
+## Shared Boundaries
+
+- `.stage-pilot/` provides SDLC workflow assets.
+- `.stage-pilot/` stores bootstrap declarations outside active SDLC units.
+- `docs/` is the source of truth for active SDLC state.
+- `src/`, `scripts/`, and `tests/` remain host-project owned implementation surfaces.
+
+## Current Gaps / Planned Changes
+
+- The first real Discovery has not been created yet.
+- Deployment target is still undecided.
+- Actual domain module boundaries will be refined once the first delivery topic is defined.
+
+## Update Triggers
+
+- Update this document when top-level directories change.
+- Update this document when module ownership boundaries change.
+- Update this document when a batch changes the approved structure baseline.
+
+## Change Log
+
+- 2026-04-30: bootstrap-baseline created the initial repository structure baseline from `.stage-pilot/bootstrap/baseline.yaml`.
@@ -0,0 +1,6 @@
+# Release Index
+
+## Release Register
+
+| REL ID | Profile | Status | Included Batch | Discovery/REQ Input | Link |
+| --- | --- | --- | --- | --- | --- |
@@ -0,0 +1,68 @@
+# Sample Host Project Runtime Flows
+
+- Baseline Mode: declared
+- Baseline Seed: .stage-pilot/bootstrap/baseline.yaml
+- Status: confirmed
+- Owner: Platform Team
+- Last Updated (KST): 2026-04-30 16:30
+- Source Discovery / Batch: bootstrap-baseline
+- Primary Runtime: api-service
+
+## Project Summary
+- Python-based API service for curated market data analysis.
+
+## Purpose
+- This document captures the initial command and runtime flow baseline after StagePilot bootstrap.
+- It gives later Discovery and Batch work a stable reference before product-specific flows exist.
+
+## Scope
+- Covers bootstrap, discovery start, and validation entry points.
+- Does not define detailed feature behavior.
+
+## Covered Entry Points
+
+- uvicorn src.main:app :: serve the HTTP API
+- python -m src.jobs.refresh_market_data :: refresh curated market data snapshots
+- Copilot Chat /bootstrap-baseline :: initialize declared baseline docs
+
+## Shared Components
+
+- .stage-pilot/bootstrap/baseline.yaml
+- `.stage-pilot/skills/`
+- `docs/project-structure.md`
+- `docs/*/index.md`
+
+## Flow: `bootstrap baseline initialization`
+
+1. StagePilot assets are installed into the host repository.
+2. `/bootstrap-baseline` collects the minimum declaration set and writes `.stage-pilot/bootstrap/baseline.yaml`.
+3. baseline docs and active index skeletons are rendered from that seed.
+4. The repository becomes ready for the first real Discovery.
+
+## Flow: `planned host runtime`
+
+1. Operator starts `uvicorn src.main:app` to serve the planned HTTP API.
+2. Background refresh can run with `python -m src.jobs.refresh_market_data`.
+3. Detailed production flows remain subject to later Discovery and delivery work.
+
+## Flow Constraints
+
+- Fresh host repositories should complete baseline initialization before the first real Discovery.
+- Declared runtime assumptions must stay in sync with `.stage-pilot/bootstrap/baseline.yaml` until observed implementation evidence exists.
+- Structure or orchestration changes must update this document or `docs/project-structure.md`.
+
+## Current Gaps / Planned Changes
+
+- Product-specific runtime orchestration is not defined yet.
+- Deployment target is undecided.
+- Delivery and release flows will be added by later Discovery and Batch work.
+
+## Update Triggers
+
+- Update this document when command entry points change.
+- Update this document when runtime orchestration changes.
+- Update this document when a batch changes the approved flow baseline.
+
+## Change Log
+
+- 2026-04-30: bootstrap-baseline created the initial runtime flow baseline from `.stage-pilot/bootstrap/baseline.yaml`.
@@ -0,0 +1,19 @@
+# Software Requirement Specification Index
+
+## 목적
+- 이 문서는 bootstrap-baseline 직후의 requirement register 골격 예시다.
+- 첫 real Discovery 이후 `draft-req`가 실제 requirement를 추가한다.
+
+## Next Requirement ID
+
+- Current: `REQ-001`
+- Rule: `Requirement Register`에 있는 가장 큰 REQ 번호보다 정확히 1 커야 한다.
+
+## Requirement Register
+
+| ID | Title | Type | Status | Priority | Owner | Link |
+| --- | --- | --- | --- | --- | --- | --- |
+
+## Recent Change Log Summary
+
+- none
@@ -0,0 +1,9 @@
+# Sample Output: doctor before bootstrap-baseline
+
+fresh host 저장소에서 아직 baseline이 초기화되지 않은 경우 doctor는 아래처럼 bootstrap 안내를 함께 출력한다.
+
+```text
+WARN [missing-active-docs] .: No active SDLC docs were found under docs/. Workspace-specific checks were skipped.
+INFO [bootstrap-required] .: Fresh host repos should run /bootstrap-baseline in Copilot Chat before the first real Discovery. Missing bootstrap files: docs/discovery/index.md, docs/srs/index.md, docs/batches/index.md, docs/releases/index.md, docs/project-structure.md, docs/runtime-flows.md
+stagepilot-doctor: 0 error(s), 1 warning(s), 1 info message(s)
+```