okstra 0.116.0 → 0.118.0

package/docs/kr/architecture/storage-model.md

@@ -1,297 +0,0 @@
-# Storage model & on-disk contracts
-
-> [`docs/kr/architecture.md`](../architecture.md) 의 storage / 계약 상세 절. 본문이 1000 줄을 넘어 이 부분을 분리했습니다.
-
-## Storage model
-
-`okstra`가 만드는 파일은 용도에 따라 아래 3개 영역에 나뉘어 저장됩니다.
-
-### 1. Stable task root
-
-task 자체의 기준 폴더입니다.
-task manifest, task index, instruction-set, runs, history가 이 루트 아래에 모입니다.
-
-```text
-<target-project>/.okstra/tasks/<task-group>/<task-id>/
-├── task-manifest.json
-├── task-index.md
-├── instruction-set/
-│   ├── analysis-profile.md
-│   ├── analysis-packet.md       # analysis worker primary compact input
-│   ├── analysis-material.md
-│   ├── reference-expectations.md
-│   ├── task-brief.md
-│   ├── directive.txt                  # optional (mirrors --directive)
-│   ├── final-report-schema.json
-│   ├── final-report-template.md
-│   └── claude-execution-prompt.md
-├── runs/
-│   └── <task-type>/
-│       ├── manifests/
-│       │   └── run-manifest-<task-type>-<seq>.json
-│       ├── state/
-│       │   └── team-state-<task-type>-<seq>.json
-│       ├── prompts/
-│       │   ├── claude-execution-prompt-<task-type>-<seq>.md
-│       │   ├── claude-worker-prompt-<task-type>-<seq>.md
-│       │   ├── codex-worker-prompt-<task-type>-<seq>.md
-│       │   ├── antigravity-worker-prompt-<task-type>-<seq>.md
-│       │   └── report-writer-worker-prompt-<task-type>-<seq>.md
-│       ├── reports/
-│       │   └── final-report-<task-type>-<seq>.md
-│       ├── status/
-│       │   └── final-<task-type>-<seq>.status
-│       ├── sessions/
-│       │   └── claude-resume-<task-type>-<seq>.sh
-│       ├── logs/
-│       │   └── errors-<task-type>-<seq>.jsonl        # optional, lead-only writer
-│       └── worker-results/
-├── history/
-│   ├── timeline.json
-│   └── fix-cycles.jsonl          # optional, fix cycle 진입 시에만 생성 (append-only)
-└── recap/
-    └── recap-log.jsonl          # optional, recap facet 의 전/후 요약·Q&A append-only 로그 (다른 산출물 불변)
-```
-
-실제 디렉터리 세그먼트는 안전한 경로 생성을 위해 slug 형태로 정규화될 수 있습니다.
-하지만 논리 task key는 항상 원래 입력값 기준 `project-id:task-group:task-id`를 유지합니다.
-
-### 2. Per-run execution artifacts
-
-실행별 산출물은 아래 경로에 누적됩니다.
-
-```text
-<target-project>/.okstra/tasks/<task-group>/<task-id>/runs/<task-type>/
-```
-
-여기에 저장되는 대표 파일:
-
-- `manifests/run-manifest-<task-type>-<seq>.json`
-- `state/team-state-<task-type>-<seq>.json`
-- `prompts/claude-execution-prompt-<task-type>-<seq>.md`
-- `prompts/<worker>-worker-prompt-<task-type>-<seq>.md`
-
-그리고 `--render-only`가 아니면 handoff된 Claude session이 보통 아래 결과 파일을 현재 run에 추가합니다.
-- `sessions/claude-resume-<task-type>-<seq>.sh`
-- `reports/final-report-<task-type>-<seq>.md`
-- `reports/final-report-<task-type>-<seq>.html`     *(Phase 7 결정론적 후처리: 사람 reviewer 용 self-contained HTML, CSS/JS 인라인)*
-- `user-responses/user-response-<task-type>-<seq>.md` *(HTML 의 `Export user response` 버튼이 같은 이름으로 다운로드해 주는 사이드카; 여기 저장해 두면 `--resume-clarification` 이 instruction-set 의 `clarification-response.md` 에 자동 첨부한다 — `clarification_items.clarification_response_with_sidecars`)*
-- `worker-results/<worker>-audit-<task-type>-<seq>.md` *(워커별 Reading Confirmation 사이드카; 본문이 아니라 audit 용)*
-- `status/final-<task-type>-<seq>.status`
-- `carry/stage-<N>.json` *(implementation 전용: stage N 실행 evidence sidecar; 다음 stage 가 자동 carry-in)*
-- `consumers.jsonl` *(implementation-planning 전용: 이 plan 의 각 stage 를 소비한 impl-run 역링크; append-only)*
-최종 결과 파일 (`final-report` MD / status) 은 `okstra`가 stdout을 저장해서 만드는 파일이 아닙니다.
-`okstra`가 준비한 task bundle을 바탕으로 Claude가 현재 run 안에 직접 작성하는 결과물입니다.
-self-contained HTML view 는 `okstra render-views <final-report.md>` (Phase 7 step 1.5) 가 final-report MD 한 본을 입력으로 결정론적으로 생성합니다. 원본 MD 는 view 생성으로 인해 수정되지 않습니다.
-반면 `sessions/claude-resume-<task-type>-<seq>.sh`는 `okstra`가 Claude launch 전에 미리 생성하는 interruption recovery helper입니다.
-
-run directory는 task-type 단위로 task 실행 이력을 모으고, 내부를 `manifests/`, `state/`, `prompts/`, `reports/`, `status/`, `sessions/`, `worker-results/`처럼 유형별 하위 폴더로 나눈 뒤 각 run-level artifact와 result 파일을 `-<task-type>-<seq>` suffix(per-category 3-digit zero-padded counter, 예: `001`, `002`)로 구분합니다.
-worker prompt history는 `/tmp`가 아니라 항상 현재 run의 `prompts/` 아래 canonical artifact로 남깁니다.
-이전처럼 `analysis-profile.md`, `analysis-material.md`, `reference-expectations.md`, `task-brief.md`, skill 복사본, `final-report-template.md`를 run마다 중복 저장하지 않습니다.
-이 자료들은 stable task root의 `instruction-set/`에 canonical copy를 유지합니다.
-같은 task-type으로 다시 실행하면 동일한 `runs/<task-type>/` 폴더를 재사용하지만, 유형별 하위 폴더 아래에서 run-level 파일명이 `-<task-type>-<seq>` suffix로 분리되므로 기존 산출물을 덮어쓰지 않습니다. `<seq>`는 카테고리 디렉토리(`manifests/`, `prompts/`, `reports/`, `status/`, `state/`, `sessions/`, `worker-results/`)별로 독립 스캔되므로 같은 run에서도 카테고리별 값이 다를 수 있습니다.
-이전 flat legacy artifact가 task-type run 폴더 최상위에 남아 있으면 다음 실행 시 해당 유형별 하위 폴더로 자동 정리합니다.
-
-### 3. Project-level discovery and installed skill assets
-프로젝트 공용 discovery pointer는 아래 경로에 생성합니다.
-
-```text
-<target-project>/.okstra/discovery/latest-task.json
-<target-project>/.okstra/discovery/task-catalog.json
-```
-
-역할 구분:
-
-- `.okstra/discovery/latest-task.json`: 현재 프로젝트에서 가장 최근에 준비된 okstra task bundle을 가리키는 current-task convenience pointer
-- `.okstra/discovery/task-catalog.json`: 현재 프로젝트에 준비된 okstra task bundle 목록을 `taskKey`, `taskGroup`, `taskId` 기준으로 유지하는 canonical project-level catalog
-- `instruction-set/reference-expectations.md`: 현재 task가 참조해야 할 config files, deployment manifests, expected values를 task-level canonical artifact로 정리한 파일
-- `~/.claude/skills/okstra-*/...`, `~/.agents/skills/okstra-*/...`, `~/.claude/agents/...`: `okstra install` 이 사용자 홈에 seed하는 skill/agent asset (project-local 시딩은 더 이상 발생하지 않음 — `okstra install --refresh` 로 갱신)
-
-이전의 아래 파일들은 더 이상 okstra 생성 대상이 아닙니다.
-
-- `CLAUDE.md`
-- `.project-docs/ai/claude-project-guide.md`
-- `.project-docs/ai/claude-skill-index.md`
-- `.project-docs/ai/okstra/okstra-guide.md`
-- `.project-docs/ai/okstra/worker-catalog.md`
-
-### 4. Manager-owned cross-project state
-
-`okstra manager` 는 project-local `.okstra` 정본을 대체하지 않고, 여러 project-local task 를 묶는 전역 manager state 를 사용자 홈에 저장합니다.
-
-```text
-~/.okstra/managers/<manager-id>/
-├── manager.json
-├── projects.json
-└── task-groups/<safe-task-group>/<safe-task-id>/
-    ├── manifest.json
-    ├── children.json
-    ├── directives.jsonl
-    ├── snapshots.json
-    ├── events.jsonl
-    └── child-context/<safe-project-id>-<safe-child-task-id>.md
-```
-
-저장 권위:
-
-- `manager.json`: manager identity 와 schema version.
-- `projects.json`: manager 에 등록된 projectId / projectRoot / role / tags. `projectRoot` 는 이미 존재하는 디렉터리여야 하며, project-local `.okstra/project.json` 이 없을 때만 setup-equivalent registration 을 수행합니다.
-- `manifest.json`, `children.json`, `directives.jsonl`: manager-owned plan, child assignment, shared/project directive.
-- `snapshots.json`: `task sync` 가 child project `.okstra` 에서 읽어온 read-side snapshot. project state 의 source of truth 가 아닙니다.
-- `events.jsonl`: `task-created`, `child-launch-prepared` 같은 manager event.
-- `child-context/*.md`: `task run` 이 준비한 child lead context. sibling project report/snapshot 은 read-side source material 로만 전달합니다.
-
-Path segment 는 slug 로 정규화합니다. 비 ASCII 값처럼 slug 가 비는 경우에는 `u-<sha1-prefix>` fallback segment 를 쓰지만, `manifest.json` 과 child `taskKey` 는 원래 입력값(`project-id:task-group:task-id`)을 보존합니다.
-
-## Task manifest contract
-
-`task-manifest.json`은 Claude가 task continuity를 이해할 때 기준이 되는 canonical metadata 파일입니다.
-이 manifest는 `projectRoot` 절대경로를 한 번만 기록하고, 나머지 생성 경로들은 가능한 한 project-relative field로 정리하는 것을 기본 원칙으로 합니다.
-
-핵심 필드 예시:
-
-- `projectId`
-- `taskGroup`
-- `taskId`
-- `taskKey`
-- `projectRoot`
-- `taskType`
-- `workCategory`
-- `taskBriefPath`
-- `relatedTasks`
-- `currentStatus`
-- `taskRootPath`
-- `instructionSetPath`
-- `referenceExpectationsPath`
-- `runsPath`
-- `historyTimelinePath`
-- `latestRunPath`
-- `latestRunStatus`
-- `latestRunPromptsPath`
-- `latestReportPath`
-- `latestResumeCommandPath`
-- `workflow.currentPhase`
-- `workflow.currentPhaseState`
-- `workflow.phaseStates`
-- `workflow.lastCompletedPhase`
-- `workflow.nextRecommendedPhase`
-- `workflow.awaitingApproval`
-- `workflow.routingStatus`
-- `workflow.lastSafeCheckpoint`
-- `phaseOutcome` *(artifact-derived semantic phase outcome; 예: implementation carry 가 모든 stage 통과를 증명하면 run contract validation 실패가 남아 있어도 implementation phase outcome 은 completed 로 기록될 수 있음)*
-- `inputs`
-- `artifacts`
-- `resultContract`
-- `claudeSession`
-- `fixCycles` *(파생 요약 — `{count, openCycleId, latest:{cycle, symptom, targetReport, closedAt}}`; 매 prepare 재계산)*
-
-이 manifest는 아래 목적을 가집니다.
-
-- Claude가 brief보다 먼저 task continuity를 이해하게 함
-- 어떤 파일을 우선 읽어야 하는지 고정함
-- 어떤 config files와 deployment manifests를 어떤 expected values로 해석해야 하는지 고정함
-- 어떤 task key 아래 결과가 누적되는지 고정함
-- related task와 latest run 위치를 빠르게 확인하게 함
-
-## Task index contract
-
-`task-index.md`는 사람이 빠르게 읽기 위한 요약 문서입니다.
-
-주요 내용:
-- task key
-- current task type
-- work category
-- 현재 task 상태
-- 최신 run 상태
-- current phase
-- current phase state
-- next recommended phase
-- reference expectations
-- latest run
-- latest report
-- resume command
-
-이 문서는 quick summary일 뿐이며 source of truth가 아닙니다.
-canonical metadata는 항상 `task-manifest.json`을 기준으로 확인합니다.
-
-## Run manifest contract
-
-각 실행은 `runs/<task-type>/manifests/run-manifest-<task-type>-<seq>.json`에 현재 run 계약을 남깁니다.
-
-`manifests/run-context-<task-type>-<seq>.json`은 schemaVersion `2.0`부터 모든 legacy path key를 직접 저장하지 않고 `identity` + `pathHints`를 저장합니다. host-side reader는 `pathHints`를 hydrate해 기존 flat key(`RUN_MANIFEST_RELATIVE_PATH`, `TEAM_STATE_PATH` 등)를 메모리에서 재구성합니다.
-
-`state/active-run-context-<task-type>-<seq>.json`도 schemaVersion `2.0`부터 lead Phase 1용 compact intake입니다. 반복 path 문자열 대신 `identity` + `pathHints`와 worker identity만 저장하고, deterministic dispatcher는 읽을 때 legacy active context shape로 hydrate합니다.
-
-`manifests/run-manifest-<task-type>-<seq>.json`의 path 계열 필드는 아직 validator / team dispatch / inspect 호환을 위해 대상 프로젝트 루트 기준 상대경로로 저장합니다.
-`okstra`가 Claude handoff를 시작한 직후에는 현재 run 상태가 보통 `in-progress`로 기록됩니다.
-이후 최종 결과 저장과 상태 갱신은 Claude가 이어서 수행합니다.
-또한 `okstra`는 launch 전에 session ID를 선할당하고, 같은 run의 `sessions/` 아래에 `claude-resume-<task-type>-<seq>.sh`를 생성합니다.
-
-주요 내용:
-
-- task key
-- task type
-- work category
-- run datetime segment
-- task brief relative path
-- analysis target
-- related tasks
-- selected workers
-- worker model assignments
-- claude session id
-- resume command relative path
-- expected report relative path
-- expected status relative path
-- prompt snapshot relative path
-- `worker prompt directory relative path`
-- `worker prompt relative path by worker id`
-- current run status
-- workflow snapshot
-- team contract
-- `fixCycleId` *(fix cycle 부착 시에만; 없으면 필드 생략)*
-
-## Timeline contract
-
-`history/timeline.json`은 task에 속한 run 이력을 누적합니다.
-
-이력에는 보통 아래가 포함됩니다.
-
-- run timestamp
-- run directory relative path
-- run manifest relative path
-- run time segment
-- task type
-- work category
-- status
-- worker prompt directory relative path
-- report relative path
-- resume command relative path
-- related tasks
-- workflow snapshot
-- `fixCycleId` *(fix cycle 부착 시에만; 없으면 필드 생략)*
-같은 task-type을 다시 실행하면 같은 `runs/<task-type>/` 폴더를 재사용하더라도 `run-manifest-<task-type>-<seq>.json`과 관련 artifact 경로가 per-category sequence suffix(`<task-type>-<seq>`)로 분리되므로 각 실행이 별도 이력으로 누적됩니다. cross-category 식별자는 manifest의 `runDateTimeSegment` ISO timestamp 필드입니다.
-
-## Claude operating contract
-
-`okstra` 실행 후 Claude는 아래 순서로 현재 task를 읽는 것을 기본 규칙으로 삼아야 합니다.
-
-1. task browsing 또는 task-id disambiguation이 필요하면 `.okstra/discovery/task-catalog.json`을 먼저 읽습니다.
-2. 현재 task key나 task path가 명시되지 않았다면 `.okstra/discovery/latest-task.json`을 current-task pointer로 읽습니다.
-3. `task-manifest.json`을 읽습니다.
-4. current `state/active-run-context-<task-type>-<seq>.json`이 있으면 lead Phase 1의 1차 입력으로 읽습니다. 이 파일은 `identity` + `pathHints` 단서로 run artifact 경로를 재구성하는 compact intake입니다. 없으면 current `manifests/run-manifest-<task-type>-<seq>.json`과 `team-state`로 fallback합니다.
-5. `instruction-set/analysis-profile.md`와 `instruction-set/analysis-packet.md`를 읽습니다.
-6. `task-index.md`는 quick summary가 필요할 때만 선택적으로 읽습니다.
-7. `analysis-material.md`, `reference-expectations.md`, `task-brief.md`, `final-report-template.md`는 packet이 불충분하거나 source citation/보고서 작성에 필요할 때 lazy read합니다.
-8. 필요하면 `history/timeline.json`과 이전 run 결과를 참고합니다.
-9. `Claude lead`로서 현재 run의 worker roster (기본 `Claude worker`, `Codex worker`, `Report writer worker`; `Antigravity worker`는 명시 포함된 경우에만)에 따라 역할을 구성합니다.
-10. 각 selected worker prompt를 assigned worker prompt history path로 현재 run의 `prompts/` 아래에 먼저 저장한 뒤 worker를 dispatch합니다.
-14. 각 required worker에 대해 결과 또는 terminal status를 수집합니다.
-15. brief이 더 구체적인 형식을 강제하지 않으면 `final-report-template.md` 구조로 Markdown 최종 보고서를 작성합니다.
-16. 결과를 현재 run의 `reports/final-report-<task-type>-<seq>.md`에 직접 저장하고, 필요하면 `status/final-<task-type>-<seq>.status`, `manifests/run-manifest-<task-type>-<seq>.json`, `task-manifest.json`, `task-index.md`도 현재 상태에 맞게 갱신합니다.
-
-권장 worker 상태값:
-
-- `completed`
-- `timeout`
-- `error`
-- `not-run`