okstra 0.117.0 → 0.118.0

package/docs/architecture/storage-model.md

@@ -0,0 +1,300 @@
+# Storage model & on-disk contracts
+
+> Detailed storage and contract section from [`docs/kr/architecture.md`](../architecture.md). This section was split out after the main document exceeded 1,000 lines.
+
+## Storage model
+
+Files created by `okstra` are stored in the following three areas according to their purpose.
+
+### 1. Stable task root
+
+This is the task's primary directory.
+The task manifest, task index, instruction set, runs, and history are collected under this root.
+
+```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, created only when entering a fix cycle (append-only)
+├── recap/
+│   └── recap-log.jsonl          # optional, append-only before/after summaries and Q&A for recap (other artifacts unchanged)
+└── notes/
+    └── <slug>-<YYYY-MM-DD>.md    # optional, agent-authored notes written by `okstra recap note` (evidence/decision-draft/analysis); inert — never auto-read by a run, fed forward only via --clarification-response
+```
+
+Actual directory segments may be normalized into slugs to create safe paths.
+However, the logical task key always retains the original input values in the form `project-id:task-group:task-id`.
+
+### 2. Per-run execution artifacts
+
+Artifacts from each execution accumulate beneath the current run's resolved `run_dir`.
+`runs/<task-type>/` is the run directory for non-stage runs. As exceptions, `implementation` uses `runs/implementation/stage-<N>/`, and single-stage `final-verification` uses `runs/final-verification/stage-<N>/` as its `run_dir`. Whole-task `final-verification` retains the non-stage form `runs/final-verification/`.
+
+```text
+<target-project>/.okstra/tasks/<task-group>/<task-id>/runs/<task-type>/
+```
+
+The representative files below are all relative to the resolved run directory (`run_dir`). Therefore, report, log, carry, and session paths for stage-isolated runs include the `stage-<N>/` segment.
+
+- `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`
+
+Unless `--render-only` is used, the handed-off Claude session typically adds the following result files to the current run.
+- `sessions/claude-resume-<task-type>-<seq>.sh`
+- `reports/final-report-<task-type>-<seq>.md`
+- `reports/final-report-<task-type>-<seq>.html`     *(Phase 7 deterministic post-processing: self-contained HTML for human reviewers, with inline CSS/JS)*
+- `user-responses/user-response-<task-type>-<seq>.md` *(A sidecar downloaded under the same name by the HTML `Export user response` button; storing it here lets `--resume-clarification` automatically attach it to `clarification-response.md` in the instruction set — `clarification_items.clarification_response_with_sidecars`)*
+- `worker-results/<worker>-audit-<task-type>-<seq>.md` *(Per-worker Reading Confirmation sidecar; for auditing rather than report content)*
+- `status/final-<task-type>-<seq>.status`
+- `runs/implementation/stage-<N>/carry/stage-<N>.json` *(implementation only: execution evidence sidecar beneath stage N's resolved run directory; automatically carried into the next stage)*
+- `consumers.jsonl` *(implementation-planning only: backlinks to the impl-run that consumed each stage in this plan; append-only)*
+The final result files (`final-report` MD / status) are not files that `okstra` creates by saving stdout.
+They are results written directly into the current run by Claude, based on the task bundle prepared by `okstra`.
+The self-contained HTML view is generated deterministically from a single final-report MD input by `okstra render-views <final-report.md>` (Phase 7 step 1.5). Generating the view does not modify the original MD.
+By contrast, `sessions/claude-resume-<task-type>-<seq>.sh` is an interruption-recovery helper that `okstra` creates before launching Claude.
+
+The resolved run directory collects execution history. It divides its contents into type-specific subdirectories such as `manifests/`, `state/`, `prompts/`, `reports/`, `status/`, `sessions/`, and `worker-results/`, then distinguishes each run-level artifact and result file with a `-<task-type>-<seq>` suffix (a three-digit, zero-padded per-category counter, such as `001` or `002`).
+Worker prompt history is retained not under `/tmp`, but always as a canonical artifact under `prompts/` for the current run.
+Unlike before, `analysis-profile.md`, `analysis-material.md`, `reference-expectations.md`, `task-brief.md`, skill copies, and `final-report-template.md` are not duplicated for every run.
+These materials retain canonical copies in `instruction-set/` under the stable task root.
+When the same non-stage task type runs again, it reuses the same `runs/<task-type>/` run directory. Reruns of `implementation` and single-stage `final-verification` reuse their resolved `runs/<task-type>/stage-<N>/` run directories. In both cases, existing artifacts are not overwritten because run-level filenames are separated by `-<task-type>-<seq>` suffixes within type-specific subdirectories. Because `<seq>` is scanned independently for each category directory (`manifests/`, `prompts/`, `reports/`, `status/`, `state/`, `sessions/`, `worker-results/`) beneath the resolved run directory, values may differ by category even within the same run.
+If flat legacy artifacts remain at the top level of a task-type run directory, the next execution automatically moves them into the corresponding type-specific subdirectories.
+
+### 3. Project-level discovery and installed skill assets
+Shared project discovery pointers are created at the following paths.
+
+```text
+<target-project>/.okstra/discovery/latest-task.json
+<target-project>/.okstra/discovery/task-catalog.json
+```
+
+Division of responsibilities:
+
+- `.okstra/discovery/latest-task.json`: a current-task convenience pointer to the most recently prepared okstra task bundle in the current project
+- `.okstra/discovery/task-catalog.json`: the canonical project-level catalog that maintains the list of okstra task bundles prepared in the current project by `taskKey`, `taskGroup`, and `taskId`
+- `instruction-set/reference-expectations.md`: a task-level canonical artifact that identifies the config files, deployment manifests, and expected values the current task should reference
+- `~/.claude/skills/okstra-*/...`, `~/.agents/skills/okstra-*/...`, `~/.claude/agents/...`: skill/agent assets seeded into the user's home directory by `okstra install` (project-local seeding no longer occurs; refresh them with `okstra install --refresh`)
+
+The following former files are no longer generated by 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` does not replace the project-local `.okstra` canonical state. It stores global manager state that groups multiple project-local tasks in the user's home directory.
+
+```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
+```
+
+Storage authority:
+
+- `manager.json`: manager identity and schema version.
+- `projects.json`: the projectId / projectRoot / role / tags registered with the manager. `projectRoot` must be an existing directory, and setup-equivalent registration is performed only when project-local `.okstra/project.json` is absent.
+- `manifest.json`, `children.json`, `directives.jsonl`: manager-owned plan, child assignment, and shared/project directives.
+- `snapshots.json`: a read-side snapshot that `task sync` imports from the child project's `.okstra`. It is not the source of truth for project state.
+- `events.jsonl`: manager events such as `task-created` and `child-launch-prepared`.
+- `child-context/*.md`: child lead context prepared by `task run`. Sibling project reports/snapshots are passed only as read-side source material.
+
+Path segments are normalized into slugs. If a slug would be empty, as can happen with non-ASCII values, a `u-<sha1-prefix>` fallback segment is used. However, `manifest.json` and the child `taskKey` preserve the original input values (`project-id:task-group:task-id`).
+
+## Task manifest contract
+
+`task-manifest.json` is the canonical metadata file Claude uses to understand task continuity.
+As a general rule, this manifest records the absolute `projectRoot` path only once and expresses the remaining generated paths as project-relative fields whenever possible.
+
+Examples of key fields:
+
+- `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; for example, when the implementation carry proves that all stages passed, the implementation phase outcome may be recorded as completed even if run contract validation failures remain)*
+- `inputs`
+- `artifacts`
+- `resultContract`
+- `claudeSession`
+- `fixCycles` *(derived summary — `{count, openCycleId, latest:{cycle, symptom, targetReport, closedAt}}`; recalculated on every prepare)*
+
+This manifest serves the following purposes.
+
+- Let Claude understand task continuity before reading the brief
+- Establish which files should be read first
+- Establish how config files and deployment manifests should be interpreted against expected values
+- Establish the task key under which results accumulate
+- Make it quick to locate related tasks and the latest run
+
+## Task index contract
+
+`task-index.md` is a summary document for quick human reading.
+
+Main contents:
+- task key
+- current task type
+- work category
+- current task status
+- latest run status
+- current phase
+- current phase state
+- next recommended phase
+- reference expectations
+- latest run
+- latest report
+- resume command
+
+This document is only a quick summary and is not the source of truth.
+Always use `task-manifest.json` when checking canonical metadata.
+
+## Run manifest contract
+
+Each execution records the current run contract in the resolved `<run-dir>/manifests/run-manifest-<task-type>-<seq>.json`. The non-stage or stage-qualified rule above determines `<run-dir>`.
+
+`manifests/run-context-<task-type>-<seq>.json`, starting with schemaVersion `2.0`, stores `identity` + `pathHints` rather than directly storing every legacy path key. The host-side reader hydrates `pathHints` to reconstruct the former flat keys (`RUN_MANIFEST_RELATIVE_PATH`, `TEAM_STATE_PATH`, and so on) in memory.
+
+`state/active-run-context-<task-type>-<seq>.json` is also the compact intake for lead Phase 1 starting with schemaVersion `2.0`. It stores only `identity` + `pathHints` and worker identities instead of repeated path strings, and the deterministic dispatcher hydrates it into the legacy active context shape when reading it.
+
+The path fields in `manifests/run-manifest-<task-type>-<seq>.json` are still stored as paths relative to the target project root for validator, team dispatch, and inspect compatibility.
+Immediately after `okstra` starts the Claude handoff, the current run status is usually recorded as `in-progress`.
+Claude then continues with saving the final results and updating status.
+Before launch, `okstra` also preallocates a session ID and creates, under the same run's `sessions/` directory, `claude-resume-<task-type>-<seq>.sh`.
+
+Main contents:
+
+- 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` *(only when attached to a fix cycle; field omitted otherwise)*
+
+## Timeline contract
+
+`history/timeline.json` accumulates the history of runs belonging to a task.
+
+The history generally includes the following.
+
+- 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` *(only when attached to a fix cycle; field omitted otherwise)*
+Reruns of the same task type reuse the same resolved run directory family. Non-stage runs use `runs/<task-type>/`, while `implementation` and single-stage `final-verification` runs use `runs/<task-type>/stage-<N>/`. Sequence-specific artifacts live beneath that resolved run directory, and each execution accumulates as a separate history entry because `run-manifest-<task-type>-<seq>.json` and related artifact paths are separated by per-category sequence suffixes (`<task-type>-<seq>`). The cross-category identifier is the manifest's `runDateTimeSegment` ISO timestamp field.
+
+## Claude operating contract
+
+After `okstra` runs, Claude should follow this default sequence when reading the current task.
+
+1. If task browsing or task-id disambiguation is required, first read `.okstra/discovery/task-catalog.json`.
+2. If the current task key or task path is not specified, read `.okstra/discovery/latest-task.json` as the current-task pointer.
+3. Read `task-manifest.json`.
+4. If the current `state/active-run-context-<task-type>-<seq>.json` exists, read it as the primary input for lead Phase 1. This file is a compact intake that reconstructs run artifact paths from `identity` + `pathHints` clues. If it does not exist, fall back to the current `manifests/run-manifest-<task-type>-<seq>.json` and `team-state`.
+5. Read `instruction-set/analysis-profile.md` and `instruction-set/analysis-packet.md`.
+6. Read `task-index.md` only when a quick summary is needed.
+7. Lazily read `analysis-material.md`, `reference-expectations.md`, `task-brief.md`, and `final-report-template.md` when the packet is insufficient or when source citations/report writing require them.
+8. Consult `history/timeline.json` and previous run results if necessary.
+9. As `Claude lead`, organize roles according to the current run's worker roster (`Claude worker`, `Codex worker`, and `Report writer worker` by default; `Antigravity worker` only when explicitly included).
+10. Save each selected worker prompt under the current run's `prompts/` directory at the assigned worker prompt history path before dispatching the worker.
+14. Collect a result or terminal status for each required worker.
+15. Unless the brief requires a more specific format, write the final Markdown report using the `final-report-template.md` structure.
+16. Save the result directly to `reports/final-report-<task-type>-<seq>.md` for the current run and, if necessary, update `status/final-<task-type>-<seq>.status`, `manifests/run-manifest-<task-type>-<seq>.json`, `task-manifest.json`, and `task-index.md` to match the current state.
+
+Recommended worker status values:
+
+- `completed`
+- `timeout`
+- `error`
+- `not-run`