okstra 0.96.1 → 0.97.1

package/docs/project-structure-overview.md

@@ -132,7 +132,7 @@ Runtime/install asset changes follow this checklist:
 
 `--link <repo>` mode is for development and symlinks installed files back to repo sources.
 
-`src/runtime-resolver.mjs` is the single reference point for runtime auto-detection. `okstra install` defaults to `--runtime auto`, records the request and any successful resolution in `installed-runtimes.json` schemaVersion 2, and still copies the shared runtime payload from the installed package `runtime/` tree even when host detection is unavailable. Skill targets are discovered from existing agent homes: `~/.claude` and `~/.codex` are both populated when present; `~/.omp/agent` is the fallback only when neither exists. Dynamic capabilities such as `tmux` and `codex` CLI availability are checked by `doctor` and `run`, not frozen into the install manifest. Claude Code skills pass explicit `--runtime claude-code` / `--lead-runtime claude-code` so they never depend on host auto-detection.
+`src/lib/runtime-resolver.mjs` is the single reference point for runtime auto-detection. `okstra install` defaults to `--runtime auto`, records the request and any successful resolution in `installed-runtimes.json` schemaVersion 2, and still copies the shared runtime payload from the installed package `runtime/` tree even when host detection is unavailable. Skill targets are discovered from existing agent homes: `~/.claude` and `~/.codex` are both populated when present; `~/.omp/agent` is the fallback only when neither exists. Dynamic capabilities such as `tmux` and `codex` CLI availability are checked by `doctor` and `run`, not frozen into the install manifest. Claude Code skills pass explicit `--runtime claude-code` / `--lead-runtime claude-code` so they never depend on host auto-detection.
 
 ---
 
@@ -142,26 +142,29 @@ Runtime/install asset changes follow this checklist:
 
 `bin/okstra` is a thin dynamic-import router. Every command module exports `run(args) -> Promise<number>` or a named install/uninstall runner.
 
+`src/` is layered: the dispatch table (`src/cli-registry.mjs`) stays at the root, shared infrastructure with no command export lives under `src/lib/`, and command modules are grouped by domain under `src/commands/{lifecycle,execute,inspect,report,memory}/`.
+
 | Command | Module | Role |
 |---|---|---|
-| `paths` | `src/paths.mjs` | Resolve package/runtime/home paths |
-| `install`, `ensure-installed` | `src/install.mjs` | Install or refresh runtime, skills, agents, templates |
-| `uninstall` | `src/uninstall.mjs` | Remove managed runtime/skills/agents, optionally purge data |
-| `doctor` | `src/doctor.mjs` | Diagnose runtime and Python imports |
-| `setup` | `src/setup.mjs` | Create/update `<PROJECT_ROOT>/.okstra/project.json` |
-| `check-project` | `src/check-project.mjs` | Verify project registration |
-| `config` | `src/config.mjs` | Read/write project/global settings such as PR template path |
-| `task-list`, `task-show` | `src/task-list.mjs`, `src/task-show.mjs` | Task/run introspection for skills |
-| `context-cost` | `src/context-cost.mjs` | Estimate task bundle file/read context cost |
-| `worktree-lookup` | `src/worktree-lookup.mjs` | Look up a task-key's registered worktree |
-| `plan-validate` | `src/plan-validate.mjs` | Check approved-plan approval marker |
-| `render-bundle` | `src/render-bundle.mjs` | Preview `prepare_task_bundle(render_only=True)` |
-| `render-views` | `src/render-views.mjs` | Generate slim MD + self-contained HTML report views |
-| `wizard` | `src/wizard.mjs` | Drive the `okstra-run` interactive state machine |
-| `token-usage` | `src/token-usage.mjs` | Wrap installed Python token usage CLI |
-| `memory` | `src/memory.mjs` | Store/find global conversation memory under `~/.okstra/memory-book` |
-
-`src/_python-helper.mjs` centralizes Node → Python execution so command modules do not duplicate subprocess wiring.
+| `paths` | `src/commands/lifecycle/paths.mjs` | Resolve package/runtime/home paths (library at `src/lib/paths.mjs`) |
+| `install`, `ensure-installed` | `src/commands/lifecycle/install.mjs` | Install or refresh runtime, skills, agents, templates |
+| `uninstall` | `src/commands/lifecycle/uninstall.mjs` | Remove managed runtime/skills/agents, optionally purge data |
+| `doctor` | `src/commands/lifecycle/doctor.mjs` | Diagnose runtime and Python imports |
+| `setup` | `src/commands/lifecycle/setup.mjs` | Create/update `<PROJECT_ROOT>/.okstra/project.json` |
+| `check-project` | `src/commands/lifecycle/check-project.mjs` | Verify project registration |
+| `config` | `src/commands/lifecycle/config.mjs` | Read/write project/global settings such as PR template path |
+| `task-list`, `task-show` | `src/commands/inspect/task-list.mjs`, `src/commands/inspect/task-show.mjs` | Task/run introspection for skills |
+| `context-cost` | `src/commands/inspect/context-cost.mjs` | Estimate task bundle file/read context cost |
+| `worktree-lookup` | `src/commands/execute/worktree-lookup.mjs` | Look up a task-key's registered worktree |
+| `plan-validate` | `src/commands/execute/plan-validate.mjs` | Check approved-plan approval marker |
+| `render-bundle` | `src/commands/execute/render-bundle.mjs` | Preview `prepare_task_bundle(render_only=True)` |
+| `render-views` | `src/commands/report/render-views.mjs` | Generate slim MD + self-contained HTML report views |
+| `wizard` | `src/commands/execute/wizard.mjs` | Drive the `okstra-run` interactive state machine |
+| `token-usage` | `src/commands/execute/token-usage.mjs` | Wrap installed Python token usage CLI |
+| `memory` | `src/commands/memory/memory.mjs` | Store/find global conversation memory under `~/.okstra/memory-book` |
+| `recap` | `src/commands/inspect/recap.mjs` | `okstra recap <assemble\|record>` Node wrapper backing the okstra-inspect `recap` facet |
+
+`src/lib/python-helper.mjs` centralizes Node → Python execution so command modules do not duplicate subprocess wiring.
 
 ### 4.2 `scripts/` — Runtime source
 
@@ -194,7 +197,8 @@ Important modules:
 | `stage_reconcile.py` | stage prepare 흐름 공용 best-effort git reconciliation (`git_reconcile.auto_reconcile` 위임; advisory — 실패는 stderr 보고만, dependency gate 가 권위 판정 유지) |
 | `run_context.py` | Per-task mutex, run context and run-input persistence; `consumers_mutex` helper for atomic `consumers.jsonl` writes |
 | `consumers.py` | Append-only `consumers.jsonl` writer + reader — records which `implementation` runs consumed which `implementation-planning` stage |
-| `paths.py` | Path/sequence computation for task/run artifacts |
+| `paths.py` | Path/sequence computation for task/run artifacts (recap 디렉터리/로그 경로 포함) |
+| `recap.py` | okstra-inspect `recap` facet 의 결정론적 백엔드 — `assemble` 은 timeline 에서 run 간 phase 전이를 조립, `record` 는 `<task-root>/recap/recap-log.jsonl` 에 요약·Q&A append-only 기록 (다른 task 산출물 불변) |
 | `render.py` | task manifest, run manifest, timeline, task index, discovery, team-state, prompt/template render |
 | `workflow.py` | Phase sequence, allowed outputs, forbidden actions, next phase |
 | `workers.py`, `models.py` | Worker roster and model metadata resolution |
@@ -293,8 +297,8 @@ The lead operating contract moved out of `agents/` to `prompts/lead/okstra-lead-
 
 ### 4.12 `tests/` and `tests-e2e/`
 
-- `tests/`: 61 pytest modules covering project resolver, run preparation, worktrees, final-report rendering, validators, wizard, token usage, config, wrapper status, etc.
-- `tests-e2e/`: 5 shell scenarios covering record-start/reconcile, rerun, task lock, agent install, and report view rendering.
+- `tests/`: pytest modules, 도메인별 하위폴더로 계층화 — `run/`(prepare·dispatch·run-index 코어), `contract/`(validator·repo/docs 계약·phase 규칙·profile), `report/`(render·convergence·language·template), `inspect/`(recap·error·context-cost·token-usage), `worktree/`(worktree·stage 격리·reconcile·reclaim), `wizard/`, `handoff/`. 공용 경로 SSOT 는 `tests/_paths.py`(`REPO_ROOT`/`TESTS_DIR`/`FIXTURES`), `tests/` 를 import 경로에 올리는 설정은 repo 루트 `pytest.ini`(`pythonpath = tests`). 픽스처는 `tests/fixtures/`.
+- `tests-e2e/`: `scenario-<id>-<name>.sh` 셸 시나리오 (record-start/reconcile, rerun, task lock, agent install, report view 등).
 
 ---