okstra 0.1.0

package/README.md

@@ -0,0 +1,36 @@
+# okstra
+
+Runtime installer and path resolver for [okstra](https://github.com/Devonshin/okstra) cross-verification skills.
+
+This package is **not** the okstra skills themselves. It carries the python and bash runtime that the skills depend on, and exposes commands that the skills invoke to discover where everything lives.
+
+## Companion: skills
+
+Skills are distributed separately through the `skills` CLI:
+
+```bash
+npx skills@latest add Devonshin/okstra
+```
+
+## Install runtime
+
+```bash
+npx okstra@latest install
+```
+
+This populates `~/.okstra/lib/python/`, `~/.okstra/bin/`, and `~/.okstra/version`. The `agents/` directory stays inside this package — skills resolve its path with `okstra paths --field agents`.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `okstra install` | Install runtime into `~/.okstra` |
+| `okstra ensure-installed` | Idempotent check + reinstall if stale; skills call this on every run |
+| `okstra paths` | Print runtime paths (`agents`, `pythonpath`, `bin`, `home`, `version`) |
+| `okstra doctor` | Diagnose the installed runtime |
+
+Run `okstra --help` for full usage.
+
+## Status
+
+Pre-release (`0.1.0-pre.x`). Layout and command surface may change before `0.1.0`.

package/bin/okstra

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+import { getPackageVersion } from "../src/version.mjs";
+
+const COMMANDS = new Map([
+  ["paths", () => import("../src/paths.mjs").then((m) => m.run)],
+  ["install", () => import("../src/install.mjs").then((m) => m.runInstall)],
+  ["ensure-installed", () => import("../src/install.mjs").then((m) => m.runEnsureInstalled)],
+  ["uninstall", () => import("../src/uninstall.mjs").then((m) => m.runUninstall)],
+  ["doctor", () => import("../src/doctor.mjs").then((m) => m.run)],
+]);
+
+const USAGE = `okstra-cli — runtime installer and path resolver for okstra skills
+
+Usage:
+  okstra <command> [options]
+
+Commands:
+  install                Install okstra runtime into ~/.okstra
+  ensure-installed       Verify install is fresh; reinstall if stale (idempotent)
+  uninstall              Remove installed runtime (user data preserved by default)
+  paths                  Print runtime paths (agents/pythonpath/bin/home/version)
+  doctor                 Diagnostic check of the installed runtime
+
+Global options:
+  --version              Print okstra-cli version and exit
+  --help                 Print this help
+
+Run 'okstra <command> --help' for command-specific options.
+`;
+
+async function main(argv) {
+  const args = argv.slice(2);
+
+  if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+
+  if (args[0] === "--version" || args[0] === "-v") {
+    process.stdout.write(`${await getPackageVersion()}\n`);
+    return 0;
+  }
+
+  const [cmd, ...rest] = args;
+  const loader = COMMANDS.get(cmd);
+  if (!loader) {
+    process.stderr.write(`unknown command: ${cmd}\n\n${USAGE}`);
+    return 2;
+  }
+
+  try {
+    const run = await loader();
+    const exitCode = await run(rest);
+    return typeof exitCode === "number" ? exitCode : 0;
+  } catch (err) {
+    process.stderr.write(`error: ${err.message}\n`);
+    if (process.env.OKSTRA_DEBUG) process.stderr.write(`${err.stack}\n`);
+    return 1;
+  }
+}
+
+main(process.argv).then((code) => process.exit(code));

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "okstra",
+  "version": "0.1.0",
+  "description": "Runtime installer and path resolver for okstra cross-verification skills",
+  "license": "MIT",
+  "author": "devonshin",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Devonshin/okstra.git",
+    "directory": "packages/okstra"
+  },
+  "type": "module",
+  "bin": {
+    "okstra": "bin/okstra"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "runtime/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepack": "node scripts/build.mjs",
+    "test": "node --test test/"
+  }
+}

package/runtime/BUILD.json

@@ -0,0 +1,5 @@
+{
+  "package": "0.1.0",
+  "builtAt": "2026-05-11T08:09:27.712Z",
+  "repoRoot": "/Volumes/Workspaces/workspace/projects/Okstra"
+}

package/runtime/agents/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: okstra
+description: Use when the user says "okstra", "cross verify", "cross-check with other AIs", "compare Claude, Codex, and Gemini", or asks for multi-agent comparison against a prepared task bundle.
+---
+
+# OKSTRA Skill
+
+## Overview
+
+Claude lead orchestrates multiple AI workers (Claude, Codex, Gemini) against a prepared task bundle, collects their independent outputs, supervises convergence, and ensures the final report is produced. When `Report writer worker` is in the selected roster, the final report file is **authored by the Report writer worker** — Claude lead reviews and approves but does not write the file itself. Claude lead never substitutes its own reasoning for a worker result, and never bypasses a rostered Report writer worker by writing the report directly.
+
+## When to Use
+
+- User explicitly says "okstra", "cross verify", or "cross-check with other AIs"
+- User wants multi-agent comparison or cross-check
+- A prepared task bundle exists with `task-manifest.json`
+
+**Do NOT use** for single-agent tasks or when no task bundle is prepared.
+
+## Sub-skill index
+
+This SKILL.md is the operating contract and phase index. Detailed procedures live in the sub-skills below; consult them whenever the corresponding phase is active.
+
+| Skill | Scope |
+|-------|-------|
+| [okstra-context-loader](./skills/okstra-context-loader/SKILL.md) | Phase 1 task-bundle discovery, manifest fields, run-directory layout |
+| [okstra-team-contract](./skills/okstra-team-contract/SKILL.md) | Phase 2–5 worker roster, model assignment rules, prompt composition (anchor headers, `[Required reading]`, `[Error reporting]`), worker output contract, terminal statuses, usage tracking |
+| [okstra-convergence](./skills/okstra-convergence/SKILL.md) | Phase 5.5 convergence loop, finding categories, reverify dispatch (anchor headers, required-reading suppression), convergence state schema |
+| [okstra-report-writer](./skills/okstra-report-writer/SKILL.md) | Phase 6 final-report authorship, dispatch template, resume-safe dispatch, shared-graph integrity check, Phase 7 token-usage collector |
+| [okstra-status](./skills/okstra-status/SKILL.md) | Project/task status views and `workStatus` updates |
+| [okstra-history](./skills/okstra-history/SKILL.md) | Past-run history, re-run command assembly, resume helper |
+| [okstra-report-finder](./skills/okstra-report-finder/SKILL.md) | Locate the final report for a given task key |
+| [okstra-schedule](./skills/okstra-schedule/SKILL.md) | Generate a consolidated work schedule for a task-group |
+| [okstra-time-summary](./skills/okstra-time-summary/SKILL.md) | Per-task / per-worker elapsed-time breakdown |
+
+## Quick Reference
+
+| Phase | Action | Key sub-skill |
+|-------|--------|---------------|
+| 1. Intake | Read task bundle in order | `okstra-context-loader` |
+| 1.5 Graph hint | Build shared knowledge graph (optional) | this SKILL — see "Optional shared knowledge graph" below |
+| 2. Prompts | Prepare shared + role-specific prompts | `okstra-team-contract` |
+| 2.5 Team contract | Load operating rules for selected roster | `okstra-team-contract` |
+| 3. Team creation | Create team, fallback if it fails | this SKILL — see "Phase 3" below |
+| 4. Execution | Spawn analysis workers (Teams preferred) | `okstra-team-contract` |
+| 5. Fallback | Sequential/background dispatch when Teams unavailable | `okstra-team-contract` |
+| 5.5 Convergence | Cross-verify findings across workers | `okstra-convergence` |
+| 6. Synthesis | Dispatch Report writer worker, review draft | `okstra-report-writer` |
+| 7. Persist | Run token-usage collector, update manifests | `okstra-report-writer` |
+
+## Core operating contract
+
+- `Claude lead` owns orchestration, convergence supervision, and final-report ownership (review/approval). It does NOT author the final-report file when `Report writer worker` is in the roster.
+- Standard worker roles: `Claude worker`, `Codex worker`, `Gemini worker`, `Report writer worker`. If the current run selects a subset, use only that subset with exact role labels from the task bundle.
+- `Report writer worker`, when in the roster, is the **author** of the final-report file. Lead reviews the draft and may request a revision via a follow-up dispatch, but MUST NOT write the report itself as a "shortcut". The only legal lead-authored fallback is when a Report writer worker dispatch was actually attempted and recorded a terminal status of `error`/`timeout`/`not-run` with an explicit reason in team-state — see [okstra-report-writer](./skills/okstra-report-writer/SKILL.md) "Lead-authored fallback".
+- "Session resume", "team is no longer alive", and similar are NOT valid reasons to skip Report writer worker dispatch — see [okstra-report-writer](./skills/okstra-report-writer/SKILL.md) "Resume-safe dispatch".
+- If the brief is incomplete, continue with explicit uncertainty markers rather than fabricating confidence.
+- Required roles must not be replaced by unnamed generic parallel workers. Before the final verdict, every selected worker must have either a saved result file or an explicit terminal status with reason. Any attempted worker with status `completed`, `timeout`, or `error` must also have a saved worker prompt history file at its assigned run-level prompt path.
+
+## Lifecycle Phase Boundaries (BLOCKING)
+
+A single okstra run executes **exactly one** lifecycle phase. The phase is given by `task-manifest.json.workflow.currentPhase` (or, equivalently, the run's `Task Type`). The lead and every worker MUST stay inside that phase's boundary for the duration of the run. Crossing the boundary is a contract violation, not a productivity gain.
+
+| Lifecycle phase | Allowed outputs | Forbidden actions |
+|-----------------|-----------------|-------------------|
+| `requirements-discovery` | classification, routing decision, missing-input list, next-phase recommendation | code edits, plan documents, build/test execution that mutates state |
+| `error-analysis` | evidence, root-cause hypotheses, reproduction gaps, validation paths | code edits, implementation design, build/migration/deploy execution |
+| `implementation-planning` | option matrix, trade-offs, dependencies, recommended order, validation/rollback strategy, **explicit user-approval request** | source code edits, file writes outside the run's `reports/`, `prompts/`, `state/`, `manifests/`, `worker-results/`, `status/`, `sessions/` directories, build/migration/deploy execution |
+| `implementation` | code edits authorised by an approved plan, accompanying tests | starting work without an approved `implementation-planning` final report carried in via `--clarification-response` or referenced in the brief |
+| `final-verification` | acceptance verdict, residual risk, regression notes; read-only execution of existing test/validation commands is permitted | source code edits, refactors, scope expansion |
+
+Phase-transition checklist (lead, end of run):
+
+1. Confirm the current phase's required outputs are complete and recorded in the final report.
+2. Set `workflow.phaseStates.<currentPhase>.state = "completed"` in `task-manifest.json` (validator does this when the run passes; verify the value).
+3. Update `workflow.lastCompletedPhase` and `workflow.nextRecommendedPhase`.
+4. **Do NOT start the next phase inside the current run.** A new okstra invocation with the new `--task-type` is the only legal way to advance.
+
+User-utterance interpretation rule:
+
+- "다음 단계 진행해" / "proceed to the next step" / equivalent phrases are scoped to **the current phase only**. Interpret them as "produce the remaining outputs of the current phase," never as "start the next lifecycle phase."
+- If the current phase's outputs are already complete and the user clearly wants to advance, reply with the phase-transition checklist above and the exact next-run command. Wait for explicit user confirmation before any action that belongs to the next phase.
+- If `nextRecommendedPhase` is `implementation-planning`, the next run produces a **plan**, not code. The next run after that is `implementation`.
+
+## Default model assignments
+
+Unless the task bundle overrides:
+
+| Role | Model | subagent_type | Notes |
+|------|-------|---------------|-------|
+| Claude lead | opus | -- | orchestration + synthesis |
+| Report writer worker | opus | report-writer-worker | authors the final report file (`agents/report-writer-worker.md`) |
+| Claude worker | sonnet | claude-worker | defined in `agents/claude-worker.md` |
+| Codex worker | gpt-5.5 | codex-worker | defined in `agents/codex-worker.md` |
+| Gemini worker | auto | gemini-worker | defined in `agents/gemini-worker.md` |
+
+If the prepared task bundle contains explicit model assignments, those assignments are canonical for the run. All three analysis workers use dedicated agent definitions; Codex/Gemini wrappers handle external CLI invocation internally; Claude worker runs as an in-process subagent with explicitly registered MCP tools so it does not fall back to `claude --mcp-cli` Bash invocations.
+
+## Phase 1: Task-bundle intake and required reading order
+
+**REQUIRED SUB-SKILL:** Invoke [okstra-context-loader](./skills/okstra-context-loader/SKILL.md) first to discover task bundle paths.
+
+Treat cross verify input as a task bundle, not as a single file. If the user did not specify an explicit task key or task path, use `.project-docs/okstra/discovery/latest-task.json` as the current-task convenience pointer. If task browsing, task-id disambiguation, or project-level task inventory is needed, inspect `.project-docs/okstra/discovery/task-catalog.json` first.
+
+After context-loader completes, read the following files. The ordering below reflects logical priority for synthesis; for execution, lead MUST issue all Read calls **in a single message (parallel reads)** — these files are independent and serial reads waste several seconds per run with no benefit.
+
+1. `task-manifest.json` (found by context-loader)
+2. `task-index.md` only if a quick human summary is useful
+3. `instruction-set/analysis-profile.md`
+4. `instruction-set/analysis-material.md`
+5. `instruction-set/reference-expectations.md`
+6. `instruction-set/task-brief.md`
+7. `instruction-set/final-report-template.md`
+8. the current run manifest under `runs/<task-type>/manifests/`
+9. the current run team-state artifact
+
+Extract: task key, task type, work category, workflow lifecycle snapshot, selected worker roster, assigned models, worker result paths, worker prompt history paths, current run prompt directory, final report path, final status path, validator path, resume helper path, config-file references, deployment-manifest references, and their expected values or invariants.
+
+If previous run reports exist, use as historical context only. If `history/timeline.json` exists, use it to review past runs. If discovery metadata or current artifacts conflict with a newer user instruction, prefer the user instruction. If `reference-expectations.md` explicitly says expectations were not provided, treat that as missing information and say `I don't know` rather than inventing expected states.
+
+## Phase 2 — Phase 5: Prompt preparation, team creation, execution, fallback
+
+These phases are governed by [okstra-team-contract](./skills/okstra-team-contract/SKILL.md). It is the canonical source for:
+
+- Worker prompt anchor headers and body composition rules.
+- The `[Required reading]` clause (audience-scoped enumeration: analysis workers vs report-writer vs reverify dispatches).
+- The `[Error reporting]` clause and the asymmetry between claude-worker and codex/gemini-worker prompts.
+- Worker output contract (sections 0–5), header standard, terminal statuses, errors-sidecar schema.
+- Token-usage tracking conventions.
+
+`Report writer worker` is NOT an analysis worker. Do not dispatch it in Phase 4/5 alongside analysis workers. It is invoked only in Phase 6 — see [okstra-report-writer](./skills/okstra-report-writer/SKILL.md).
+
+### Phase 3 — Team creation
+
+Always attempt team creation first. Do not check environment variables or guess availability.
+
+1. Call `TeamCreate(team_name: "okstra-<task-key>", description: "Lead-plus-worker okstra run for <task-key>")`.
+2. If `TeamCreate` succeeds, proceed to Phase 4.
+3. If `TeamCreate` fails (tool error, permission denied, or unavailable), proceed to Phase 5 fallback.
+
+Use agent and subagent names that map cleanly to the selected worker roles. Do not create ambiguous role names that differ from `Claude worker`, `Codex worker`, `Gemini worker`, or `Report writer worker`.
+
+### Phase 4 / Phase 5 — Execution and error-log dump
+
+Spawn **analysis workers only** in the same turn (Phase 4 in Teams mode; Phase 5 with `run_in_background: true` and no `team_name` when Teams unavailable). Preserve exact roster, role labels, assigned models from the task bundle.
+
+After each worker terminates (any terminal status), if a worker errors sidecar exists at `runs/.../worker-results/<role-slug>-errors.json`, dump it to the run error log:
+
+```bash
+python3 scripts/okstra-error-log.py append-from-worker \
+  --sidecar <sidecar> \
+  --out <runDir>/logs/errors-<task-type>-<seq>.jsonl \
+  --task-key <taskKey> --agent <agent> --agent-role <role> --model <model>
+```
+
+For Codex/Gemini wrappers: if the CLI returns non-zero, times out, or hits a rate limit, immediately call `okstra-error-log.py append-observed --error-type cli-failure ...` with the captured exit code, duration, message, and stderr excerpt. The wrapper subagent does this from inside its own Bash tool — Lead does NOT need to re-record. Token usage is NOT available from Agent tool results in real time; it is collected post-hoc at the start of Phase 7.
+
+## Phase 5.5: Convergence loop
+
+**REQUIRED SUB-SKILL:** Invoke [okstra-convergence](./skills/okstra-convergence/SKILL.md) for iterative cross-verification.
+
+Convergence is enabled by default. Configure via task-manifest.json:
+
+- `convergence.enabled`: true/false (default: true)
+- `convergence.maxRounds`: 1–3 — **phase-aware default**: `1` for `requirements-discovery`, `2` for all other task types
+- `convergence.verificationMode`: `"lightweight"` | `"full-reanalysis"` (default: `"lightweight"`)
+
+When `task-manifest.json` does not set `convergence.maxRounds`, lead MUST resolve the effective value via the phase-aware default above before entering Phase 5.5, and record the resolved value in the convergence state artifact.
+
+If any re-verification batch yields a `verification-error` terminal status, or a worker result fails the contract, Lead MUST record one event per violation via `python3 scripts/okstra-error-log.py append-observed --error-type contract-violation --agent <offending-agent> ...`. Use `agent: "claude-lead"` only when the violation is detected internally without a specific worker.
+
+If convergence is disabled, proceed directly to Phase 6 with the raw worker results.
+
+## Phase 6: Final report assembly
+
+**REQUIRED SUB-SKILL:** Invoke [okstra-report-writer](./skills/okstra-report-writer/SKILL.md) for report structure, dispatch template, resume-safe dispatch, shared-graph integrity check, and lead-authored fallback rules.
+
+### Authoring ownership (BLOCKING)
+
+If `Report writer worker` is in the selected roster (`recommendedWorkers` / `resultContract.requiredWorkerRoles`), **Lead MUST dispatch it to write `runs/<task-type>/reports/final-report-<task-type>-<seq>.md`**. Lead does NOT write that file. Lead's role in this phase is: prepare the report-writer prompt (carrying convergence output, all worker results, and reference expectations), dispatch, then review the produced file.
+
+Do not write the final verdict until every analysis worker role has either a saved result or a terminal status entry. The convergence output provides four finding categories:
+
+1. Full Consensus
+2. Partial Consensus
+3. Contested
+4. Worker-Unique
+
+All categories must appear in the final synthesis. Do not omit contested or worker-unique findings. If the brief does not define a stricter format, follow `instruction-set/final-report-template.md`. If `reference-expectations.md` defines explicit expected states for config files or deployment manifests, include a clear match/gap assessment.
+
+If only one worker result is usable: reduced-confidence synthesis. If evidence is missing: say `I don't know`. If no meaningful worker differences: say so explicitly.
+
+## Phase 7: Artifact persistence and validator handoff
+
+The detailed persistence checklist and the BLOCKING token-usage collector invocation live in [okstra-report-writer](./skills/okstra-report-writer/SKILL.md). Persist the run yourself — do not assume okstra saves the final artifacts for you.
+
+Order of operations:
+
+1. Run the token-usage collector with `--substitute-final-report`. The final-report file MUST already exist before this step runs.
+2. Verify final report exists at the expected report path. When `Report writer worker` is in the roster, that worker authored the file in Phase 6 — Lead's job here is to **verify** structure and template conformance.
+3. Update team-state artifact (preserve usage fields written by the script).
+4. Update run manifest.
+5. Update `task-manifest.json`, including lifecycle fields (work category, phase states, next recommended phase, approval markers, safe-resume checkpoint).
+6. Update `task-index.md`.
+7. Write final status file if expected.
+
+Keep the assigned worker prompt history paths stable in `team-state`, `run-manifest`, and `task-manifest`. Do not rewrite prompt artifacts to `/tmp` or omit prompt metadata for attempted workers.
+
+After persistence, the run-level error log lives at `<runDir>/logs/errors-<task-type>-<seq>.jsonl`. Useful jq one-liners for retrospective review:
+
+```bash
+# Counts per agent
+jq -s 'group_by(.agent) | map({agent: .[0].agent, count: length})' <runDir>/logs/errors-<task-type>-<seq>.jsonl
+
+# Counts per errorType
+jq -s 'group_by(.errorType) | map({type: .[0].errorType, count: length})' <runDir>/logs/errors-<task-type>-<seq>.jsonl
+```
+
+The errors log is informational. Its presence/absence does not affect the final verdict. Do not block report writing on it.
+
+After persistence, reply briefly in Korean with: completion status, final report path, team-state path, validator result, resume command path, any remaining blocker.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Substituting Claude lead reasoning for a worker result | Claude lead synthesizes only — spawn the worker |
+| Skipping a worker silently | Always record terminal status with reason |
+| Writing verdict before all workers report | Wait for all results or explicit terminal statuses |
+| Ignoring task bundle model assignments | Task bundle overrides are canonical |
+| Sending identical prompts to all workers | Add role-specific emphasis per [okstra-team-contract](./skills/okstra-team-contract/SKILL.md) |
+| Omitting contested or worker-unique findings | All categories must appear in the report |
+| Running full re-analysis when lightweight suffices | Default lightweight; full only when manifest opts in |
+| Using `/tmp/*prompt*.txt` for worker prompt persistence | Persist the exact worker prompt to the assigned run-level `prompts/` path |
+| Lead writes `final-report-<suffix>.md` itself when `Report writer worker` is in the roster | Dispatch the Report writer worker per [okstra-report-writer](./skills/okstra-report-writer/SKILL.md) "Phase 6 dispatch template" |
+| Skipping Report writer worker dispatch citing "session resume constraint" or "team is gone" | No such constraint exists — see [okstra-report-writer](./skills/okstra-report-writer/SKILL.md) "Resume-safe dispatch" |
+| Using `subagent_type: "general-purpose"` for Report writer worker | Use `subagent_type: "report-writer-worker"` |
+| Including `final-report-template.md` in analysis worker `[Required reading]` | Template belongs only in the report-writer prompt — see [okstra-team-contract](./skills/okstra-team-contract/SKILL.md) audience-scoped enumeration |
+| Injecting `[Required reading]` into lightweight reverify prompts | Lightweight reverify forbids re-reading source materials — see [okstra-convergence](./skills/okstra-convergence/SKILL.md) "Reverify prompt: required-reading suppression" |
+| Letting `convergence.maxRounds` default to 2 for `requirements-discovery` | Resolve effective default to `1` for discovery and record in convergence state artifact |
+| Issuing serial Read calls in Phase 1 | The intake files are independent — issue all Read calls in a single message (parallel) |
+| Flagging the claude-worker dispatch prompt as "incomplete" because it lacks `[Required reading]` / `[Error reporting]` blocks | Intentional asymmetry — see [okstra-team-contract](./skills/okstra-team-contract/SKILL.md) "Asymmetry between claude-worker and codex/gemini-worker prompts" |
+| Skipping `--substitute-final-report` in the Phase 7 collector run | Always pass the flag — see [okstra-report-writer](./skills/okstra-report-writer/SKILL.md) "Phase 7 token-usage collector" |

package/runtime/agents/TODO.md

@@ -0,0 +1,168 @@
+# okstra (okstra) — 후속 개선 TODO
+
+이 파일은 okstra 워크플로우의 워커 종료 / Phase 4 대기 시간 개선 작업, 그리고 워커 설정 일관성 감사(2026-05-03)에서 도출됐지만 단일 라운드에서 안전하게 처리할 수 없어 별도 라운드로 미룬 항목을 기록한다.
+
+---
+
+## 항목 C2 — Worker-results 경로 표준 결정 [해결됨, 2026-05-03]
+
+### 결정
+
+런타임이 도달한 layout을 canonical로 채택했다(`scripts/okstra.sh:1495-1523` 기준):
+
+```
+runs/<task-type>/
+├── manifests/  (run-manifest-<task-type>-<seq>.json)
+├── state/      (team-state-<task-type>-<seq>.json, convergence-<task-type>-<seq>.json)
+├── prompts/    (claude-execution-prompt-<task-type>-<seq>.md, <role>-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)
+└── worker-results/
+    ├── claude-worker-<task-type>-<seq>.md
+    ├── codex-worker-<task-type>-<seq>.md
+    ├── gemini-worker-<task-type>-<seq>.md
+    └── report-writer-worker-<task-type>-<seq>.md
+```
+
+규칙:
+- `<seq>` = 3-digit zero-padded sequence number (`001`, `002`, …) scoped **per-category directory** (i.e., scanned independently per `manifests/`, `prompts/`, `reports/`, `status/`, `state/`, `sessions/`, `worker-results/`). 파일명 infix이며 디렉토리 세그먼트가 아님.
+- 카테고리별 카운터이므로 같은 run에서도 디렉토리마다 `<seq>` 값이 다를 수 있다(이전 run이 일부 카테고리만 기록한 경우). 한 run의 cross-category 식별자는 manifest의 `runDateTimeSegment`(ISO timestamp) 필드이며, 파일명 infix가 아니다.
+- `runs/<date>/...` 옛 패턴(date-first)은 폐기. `<date>` 디렉토리 세그먼트는 더 이상 사용하지 않음.
+- 같은 task-type 재실행 시 같은 디렉토리를 재사용하되, 모든 run-level artifact는 `<task-type>-<seq>` infix로 분리되므로 덮어쓰지 않는다.
+
+### 수정 내역
+
+- `scripts/okstra.sh` 의 `CLAUDE_WORKER_RESULT_FILE` 외 4종 파일명에 `$RUN_FILE_SUFFIX` 추가 (이전엔 suffix가 없어 재실행 시 덮어쓰기됨).
+- 옛 `runs/<task-type>/<task-type>-<seq>/...` 및 `runs/<date>/<task-type>/...` 표기를 모두 정리해 reality에 맞춤. 영향 파일:
+  - `agents/SKILL.md`
+  - `agents/workers/{claude,codex,gemini,report-writer}-worker.md`
+  - `skills/okstra-context-loader/SKILL.md` (canonical 트리 갱신)
+  - `skills/okstra-team-contract/SKILL.md`
+  - `skills/okstra-convergence/SKILL.md`
+  - `skills/okstra-report-writer/SKILL.md`
+  - `OKSTRA_USAGE_MANUAL.md`
+
+---
+
+## 항목 F4 — `implementation.md` 프로필의 워커 이름 매핑 누락 [블로킹: 설계 결정 필요]
+
+### 문제
+
+[prompts/profiles/implementation.md](../../../prompts/profiles/implementation.md) 프로필은 다른 4개 프로필과 달리 다음 워커 이름을 사용한다:
+
+- `Claude executor` (유일하게 Edit/Write/state-mutating Bash 허용)
+- `Claude verifier`
+- `Codex verifier`
+- `Gemini verifier`
+
+그런데 **이 4개 역할 이름 중 어느 것도 [agents/workers/](agents/) 의 `*.md` 파일로 등록돼 있지 않음**. 등록된 워커 정의는 `claude-worker.md`, `codex-worker.md`, `gemini-worker.md`, `report-writer-worker.md` 4종.
+
+### 결과로 발생 가능한 모호성
+
+Lead가 implementation.md 프로필을 따라 Phase 4 dispatch를 시도할 때:
+
+- `subagent_type: "claude-executor"` 같은 값이 실제로는 등록 안 돼 있어 dispatch 실패.
+- 또는 Lead가 임의로 `subagent_type: "claude-worker"` 로 매핑해 dispatch — 그러면 implementation 프로필의 핵심 안전장치(`Claude executor`만 Edit/Write 허용) 가 작동하지 않음. `claude-worker.md` 정의는 read-only를 강제하지 않음.
+
+### 결정해야 할 것
+
+1. **별도 워커 정의 파일 신설**: `agents/claude-executor.md`, `agents/claude-verifier.md`, `agents/codex-verifier.md`, `agents/gemini-verifier.md` 4종을 만들어 등록 — 각 정의에 read-only / write-allowed 제약을 직접 인코딩.
+2. **기존 워커 재사용 + 프롬프트 레벨 제약**: `claude-worker` 등을 그대로 쓰되 lead의 dispatch 프롬프트에서 "이번 dispatch에서는 Edit/Write 금지" 같은 룰을 주입. 단점: 프롬프트만으로 강제되며 도구 레벨 차단이 아님.
+3. **implementation.md 프로필 자체 폐기/리네임**: 다른 프로필이 `claude-worker` 등 표준 이름을 쓰므로 implementation도 같은 이름 체계로 재작성.
+
+### 권장
+
+옵션 1이 가장 안전(`tools` 화이트리스트로 도구 레벨 차단 가능). 다만 신규 워커 정의 4개 작성은 작업량이 있어 별도 라운드에서 다룬다.
+
+### 추가로 점검할 것
+
+- okstra-team-contract / SKILL.md 에 implementation 워크플로우의 워커 명단이 따로 등재돼 있는지(현재 Role Definitions 표는 4종만 등재).
+- okstra runtime이 `subagent_type` 미등록 시 어떻게 동작하는지(silent fallback vs 명시적 에러).
+
+---
+
+## 수정 B — Leader-side 워커 soft timeout 도입
+
+### 배경
+
+okstra는 Phase 4에서 Claude / Codex / Gemini 워커 3종을 동시에 spawn한다. 현재 leader는:
+
+- Agent 호출을 foreground(blocking)로 발사하므로 가장 느린 워커가 phase 전체를 잡아둔다.
+- `terminal status: timeout` 카테고리는 [`okstra-team-contract` SKILL.md](skills/okstra-team-contract/SKILL.md) 에 정의돼 있지만, **누가 어떤 조건으로 timeout을 트리거하는지에 대한 룰이 없다**.
+- 결과적으로 Claude worker의 ack가 늦으면 leader는 무한정 기다리고, convergence(Phase 5.5)가 지연된다.
+
+수정 A(Claude worker Stop Condition)는 워커 측 자율 종료를 강제하지만, 워커가 규칙을 따르지 않거나 in-process subagent runtime이 멈춘 경우의 안전장치는 여전히 없다. 수정 B는 그 안전장치를 leader 쪽에 추가한다.
+
+### 변경 대상 파일
+
+- [SKILL.md](SKILL.md) Phase 4 섹션 (대략 380~410 라인 부근, "Phase 4: Preferred Agent Teams execution")
+- [skills/okstra-team-contract/SKILL.md](skills/okstra-team-contract/SKILL.md) — terminal status 표 보강 (필요 시)
+
+### 추가할 룰 초안
+
+Phase 4 실행 섹션에 아래 블록을 추가한다.
+
+```markdown
+### Per-worker soft timeout
+
+Lead must establish an internal expected-duration window per worker based on
+task type:
+
+| Task type                | Expected per-worker duration |
+| ------------------------ | ----------------------------- |
+| requirements-discovery   | 10 minutes                    |
+| error-analysis           | 15 minutes                    |
+| implementation-planning  | 20 minutes                    |
+| final-verification       | 10 minutes                    |
+
+If a worker has not returned within **2× the expected duration** AND the
+worker-results file already exists on disk with a valid standardized header,
+Lead MUST:
+
+1. Record terminal status `timeout` in team-state for that worker, with
+   `reason: "worker-overran-after-write"` and the wall-clock duration.
+2. Append a `cli-failure` (Codex/Gemini) or `tool-failure` (Claude worker)
+   event via `okstra-error-log.py append-observed`.
+3. Proceed with Phase 5.5 using the on-disk worker-results file as the
+   canonical worker output. Do NOT invent results — if the file does not exist
+   or fails header validation, record `not-run` instead of `timeout` and skip
+   that worker's contribution to convergence.
+
+Lead does NOT have a runtime-level "cancel Agent call" capability. The Agent
+call may continue to run in the background and eventually return; Lead simply
+ignores the late return if a `timeout` status was already recorded.
+
+If the worker-results file does NOT exist when the soft timeout fires, Lead
+must wait for either the file to appear or the Agent call to return — do not
+fabricate a `timeout` status against a missing artifact.
+```
+
+### 검증 체크리스트
+
+수정 B를 머지하기 전에 다음을 확인한다.
+
+- [ ] `okstra-team-contract` 의 terminal status 표(`completed | timeout | error | not-run`)와 새 룰의 의미가 정확히 일치하는가
+- [ ] `okstra-error-log.py append-observed` 의 `--error-type cli-failure` / `tool-failure` 파라미터가 새 룰에서 요구하는 형태와 일치하는가 (`scripts/okstra-error-log.py` 시그니처 점검)
+- [ ] team-state JSON 스키마에 `reason`, `durationSeconds` 필드가 이미 존재하는가, 없다면 스키마 마이그레이션 필요
+- [ ] Phase 5.5 (`okstra-convergence`) 가 일부 워커 결과 누락 상태에서도 정상 동작하는가 — 적어도 1개 워커 결과만으로는 convergence 진행을 거부해야 하는가, 아니면 partial 모드를 허용하는가 정책 결정
+- [ ] 이 룰을 Phase 5 (sequential/background fallback)에도 동일하게 적용할지 결정
+
+### 의존 / 선행 작업
+
+- 수정 A (Claude worker Stop Condition) 가 먼저 머지되어 일정 기간 사용 데이터를 수집해야, 위 표의 expected duration 값을 실측 기반으로 조정할 수 있다. 초안 값은 보수적으로 잡았으므로 1~2주 사용 후 조정 권장.
+
+### 참고 — 적용 범위 밖 (수정 C 후보)
+
+다음은 수정 B와 별개의 더 큰 설계 변경이며, 별도 브랜치에서 다룬다.
+
+- Phase 4를 foreground multi-Agent에서 `run_in_background: true` + leader polling 방식으로 전환
+- Lead 가 worker-results 파일 존재 + 헤더 검증으로 완료를 판단하는 폴링 루프 추가
+- 진짜 cancellation (Agent 강제 종료) 가 가능해지면 그 시점에 통합
+
+---
+
+## 변경 이력
+
+- 2026-05-03 — 작성. 수정 A(Claude worker Stop Condition) 동시 머지에 따른 후속 항목 기록.