okstra 0.5.0 → 0.6.1

package/README.kr.md

@@ -89,6 +89,18 @@ npx -y okstra@latest doctor
 
 `result: OK` 라인이 보이면 준비 완료입니다. FAIL row 가 있으면 그 줄에 바로 복구 방법이 인쇄됩니다 (대개는 install 재실행).
 
+#### (선택) `okstra` 명령을 글로벌로 설치
+
+이 README 의 모든 예제는 `npx -y okstra@latest <cmd>` 를 씁니다 — 글로벌 설치 없이도 동작합니다. 매번 npx 의 패키지 fetch / 버전 체크를 거치지 않고 `okstra` 한 단어로 호출하고 싶다면 글로벌 설치:
+
+```bash
+npm i -g okstra
+okstra --version       # CLI 가 PATH 에 잡혔는지 확인
+okstra install         # 'npx -y okstra@latest install' 와 동일
+```
+
+글로벌 설치는 Node CLI 를 PATH 에 등록할 뿐입니다. 런타임(`~/.okstra/`) 과 Claude 스킬(`~/.claude/skills/`) 은 여전히 `okstra install` 이 생성합니다 — `npm i -g` 에 포함되지 않습니다. 이후 업그레이드: `npm i -g okstra@latest && okstra install`. 글로벌 바이너리 제거: `npm uninstall -g okstra` (`~/.okstra/` 는 그대로; 그것까지 지우려면 `okstra uninstall`).
+
 ### 3.2 프로젝트 등록 (프로젝트당 1회)
 
 CLI 에서:

package/README.md

@@ -88,6 +88,18 @@ npx -y okstra@latest doctor
 
 A `result: OK` line means you're ready. Any FAIL row prints its remediation in-line (usually: rerun install).
 
+#### Optional: install the `okstra` command globally
+
+Every example in this README uses `npx -y okstra@latest <cmd>` so you don't need a global install. If you'd rather type a bare `okstra` (and skip npx's fetch / version-check on each invocation), install it globally:
+
+```bash
+npm i -g okstra
+okstra --version       # confirm the CLI is on PATH
+okstra install         # same as 'npx -y okstra@latest install'
+```
+
+The global install only registers the Node CLI on your PATH. The runtime (`~/.okstra/`) and the Claude skills (`~/.claude/skills/`) are still provisioned by `okstra install` — they are not part of `npm i -g`. To upgrade later: `npm i -g okstra@latest && okstra install`. To remove the global binary: `npm uninstall -g okstra` (leaves `~/.okstra/` untouched; remove that with `okstra uninstall`).
+
 ### 3.2 Register a project (once per project)
 
 From the CLI:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.5.0",
-  "builtAt": "2026-05-12T04:37:48.519Z",
+  "package": "0.6.1",
+  "builtAt": "2026-05-12T05:33:06.736Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/prompts/profiles/implementation.md

@@ -14,16 +14,21 @@
   - `Report writer worker` is the **author** of the final-report file; `Claude lead` reviews and approves the produced draft and does NOT write the file itself (see `okstra-team-contract` and `okstra-report-writer` for the authoritative contract).
   - default model assignments are resolved from centralised defaults; the fallback values are `Claude lead`/`Claude executor`/`Report writer worker`=`opus`, `Claude verifier`=`sonnet`, `Codex verifier`=`gpt-5.5`, `Gemini verifier`=`auto`
   - all three verifier roles (`Gemini verifier`, `Codex verifier`, `Claude verifier`) must be attempted; the final verdict waits until each has either a result or an explicit terminal status
+  - **All-verifier-failure policy**: if every required verifier (`Gemini verifier`, `Codex verifier`, `Claude verifier`) ends with a non-result terminal status (`timeout`, `error`, `not-run`) — i.e. zero independent verdicts were produced — the run MUST end with status `blocked` and route to a follow-up `error-analysis` run. `Claude lead` MUST NOT substitute its own verdict in place of the missing verifier outputs; synthesis requires at least one independent verifier's verdict. If one or two verifiers fail but at least one returns a verdict, the run proceeds with the surviving verdict(s) and the final report MUST explicitly notate which verifiers were unavailable, with the captured error / timeout evidence per failed verifier.
   - unnamed generic parallel workers must not replace the required role roster, and no additional sub-agent dispatch is allowed beyond this roster
 - Tooling — read-only MCP availability:
   - `mcp__mysql-fontsninja-{common,fontradar,fontsninja,fonthelper}` (tools: `mysql_list_tables`, `mysql_describe_table`, `mysql_select_data`) may be queried by both executor and verifiers as a read-only cross-check (sanity-checking row counts after a migration script's dry-run, comparing observed schema against the plan's expectations, etc.); the canonical usage policy is in the task brief's `## Available MCP Servers` section, and any MCP-derived evidence MUST cite server, table, and the SELECT used. MCP MUST NEVER be used as a write path — schema/data mutations go through repository migration files, never through this MCP.
 - Pre-implementation gate (mandatory — refuse to start if any item fails):
   - the run brief MUST cite `--approved-plan <path>` pointing to a `final-report.md` produced by a prior `implementation-planning` run located under `runs/implementation-planning/.../reports/final-report.md`
-  - that file MUST contain a `User Approval Request` block AND a recorded user approval marker (e.g. `APPROVED:` line, `[x] Approved`, or equivalent unambiguous evidence). If only the request block exists without an approval marker, refuse to start with status `contract-violated`.
+  - that file MUST contain a `User Approval Request` block AND a recorded user approval marker matching one of the following line-anchored, case-insensitive forms (the runtime regex in `okstra_ctl.run._validate_approved_plan` enforces this and rejects the run with `PrepareError` before any prompt is generated): `APPROVED` (alone, followed by `:`, or end-of-line), `[x] Approved`, or `User Approval: APPROVED|granted|yes`. Free-form approvals such as "lgtm", "go ahead", or paraphrased confirmations are intentionally NOT accepted; if the user's approval is informal, re-edit the plan file to add one of the exact markers above before invoking the implementation run.
   - the file's `Recommended option` and its bite-sized step list become the authoritative scope for this run; any deviation must be justified in the final report and routed back to a new `implementation-planning` run instead of being silently expanded.
 - Pre-implementation context exploration (executor before first edit):
   - re-read the approved plan end-to-end and extract: file list, step order, validation commands, rollback path
   - inspect the current state of every file the plan names; if any file has changed materially since the plan was written, stop and route to a new `implementation-planning` run instead of editing speculatively
+  - "materially changed" means: the function, class, section, or behaviour the plan targets has been edited, renamed, moved, removed, or otherwise altered in a way that invalidates the plan's reasoning. Cosmetic edits (whitespace, comment-only changes, unrelated function modifications elsewhere in the same file) do NOT trigger a re-plan; cite the diff (`git log --oneline <plan-created-at>..HEAD -- <file>`) in the final report and proceed.
+  - distinguish the two file-scope rules (they are not in conflict):
+    - **drift rule** (this section): if a file *named in the plan* has materially drifted, refuse to edit and route back to planning. This protects trust in the approved scope.
+    - **out-of-plan rule** (Allowed actions section below): if a step *requires touching a file NOT in the plan list*, that is permitted with `Out-of-plan edits` justification. This handles honest scope discovery during execution.
   - confirm the test/build commands referenced in the plan still exist and run from a clean state
 - Allowed actions during the run:
   - **Edit / Write on any project file** (no path whitelist — scope is bounded by the approved plan's file list, not by directory). Editing files outside the plan's list is permitted only when strictly needed to satisfy a step, and MUST be recorded in the final report's `Out-of-plan edits` block with rationale.
@@ -53,7 +58,10 @@
   - **Validation evidence**: actual command output (stdout/stderr) for every `pre / mid / post` validation command from the plan. Truncated output is acceptable but the command line and exit code MUST be exact. No paraphrasing of test results.
   - **TDD evidence (when applicable)**: for steps that should be TDD-ordered, show the failing-test output BEFORE the implementation commit and the passing-test output AFTER, with commit SHAs framing the transition.
   - **Verifier results**: a section per verifier (`Gemini verifier`, `Codex verifier`, `Claude verifier`) containing their independent verdict (PASS / CONCERNS / FAIL), their cited diff snippets, and any fix recommendations they declined to apply. `Claude lead` synthesises a unified verdict but MUST preserve dissent — do not collapse three opinions into one paragraph.
-  - **Rollback verification**: confirmation that the plan's rollback path is still valid after the changes (e.g. revert SHA exists, feature flag toggle works, migration down step is reachable). Dry-run rollback is preferred when feasible.
+  - **Rollback verification**: confirmation that the plan's rollback path is still valid after the changes. Strength of verification depends on the change category:
+    - **Pure code changes** (no persisted state, no infra mutation): a reachable revert SHA is sufficient. Record the exact `git revert <SHA>` command that would undo the change, and confirm `git rev-parse <SHA>` resolves.
+    - **Feature-flag-gated changes**: confirm the off-switch path was exercised in this run's validation evidence (i.e. one of the validation commands ran with the flag off and succeeded). A plan that ships a flag without exercising the off-path does NOT satisfy this requirement.
+    - **Schema migrations, config-format changes, or any change with persisted state**: a **dry-run of the rollback step is mandatory**, not preferred. Record the exact rollback command and its captured exit code / stdout. If the migration tool offers no dry-run mode (`--dry-run`, `--plan`, equivalent), the executor MUST refuse to claim rollback verification and instead end the run with a routing recommendation back to `implementation-planning` for a safer rollback strategy. Skipping this step on a stateful change is treated as a `contract-violated` outcome by `final-verification`.
   - **Routing recommendation for `final-verification`**: brief note on whether the changes are ready for final-verification phase or need a new error-analysis / planning loop first.
 - Self-review pass before finalising the report (`Claude lead` runs this; do not delegate to a generic subagent):
   1. **Plan coverage** — every step in the approved plan's recommended option must point to a commit (or an explicit `Skipped: <reason>` entry). List gaps.
@@ -61,7 +69,11 @@
   3. **Out-of-plan honesty** — files in the diff that are NOT in the plan list must appear in the `Out-of-plan edits` block. Cross-check with `git diff --name-only`.
   4. **Verifier dissent preserved** — if the three verifiers disagree, the disagreement is visible in the report? Synthesis hides nothing?
   5. **Forbidden action audit** — `git push`, publish, deploy, migration, third-party write commands: scan the run's session transcripts for any occurrence and confirm none happened.
-  6. **Placeholder scan** — committed code searched for TBD / TODO / "handle edge cases" strings introduced by this run? (Pre-existing TODOs in untouched code are out of scope.)
+  6. **Placeholder scan** — restrict the scan to lines this run actually introduced; pre-existing placeholders in unchanged regions of touched files are out of scope. Required command (substitute `<base>` with the parent of the first commit in this run's commit list):
+     ```
+     git diff <base>..HEAD | grep -E '^\+[^+].*\b(TBD|TODO|FIXME|XXX|implement later|handle edge cases|similar to|placeholder)\b' || echo 'clean'
+     ```
+     Only newly-added lines (those starting with `+` and not part of the `+++` header) are inspected. If output is anything other than `clean`, the run MUST either remove the placeholders before finalising or record an explicit justification per occurrence in the final report.
 - Skill provenance (for maintainers — these skills are referenced as inspiration, NOT invoked at runtime):
   - The pre-implementation gate, "Plan coverage" and "Evidence completeness" self-review items are adapted from the `executing-plans` skill (inline mode). The skill's "subagent-driven vs inline" choice prompt and its plan-document-header conventions are intentionally not adopted — okstra owns lifecycle handoff.
   - The "TDD evidence" requirement and the failing-test-before-implementation ordering preference are adapted from `test-driven-development`. Strict enforcement is relaxed where the touched area has no test infrastructure; in those cases the executor must add at minimum a regression test and record a justification.

package/runtime/python/okstra_ctl/run.py

@@ -285,15 +285,27 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     project_root = Path(inp.project_root)
 
     # ---- validate inputs ----
+    # Hint suffix added to every "okstra runtime asset missing" PrepareError below.
+    # These files ship with the package and live under runtime/ — if any are
+    # missing the install is incomplete or stale, not a user-content issue.
+    _INSTALL_HINT = (
+        " This file ships with the okstra package; its absence usually means a stale "
+        "or partial install. Run 'okstra ensure-installed' (or 'okstra install' again) "
+        "to repair the runtime. If the problem persists, run 'okstra doctor' for a "
+        "fuller diagnostic."
+    )
     profile_dir = workspace_root / "prompts" / "profiles"
     profile_file = profile_dir / f"{inp.task_type}.md"
     if not profile_file.is_file():
         raise PrepareError(
-            f"analysis profile file not found for task-type {inp.task_type}: {profile_file}"
+            f"analysis profile file not found for task-type {inp.task_type}: "
+            f"{profile_file}.{_INSTALL_HINT}"
         )
     prompt_template = workspace_root / "prompts" / "launch.template.md"
     if not prompt_template.is_file():
-        raise PrepareError(f"okstra prompt template not found: {prompt_template}")
+        raise PrepareError(
+            f"okstra prompt template not found: {prompt_template}.{_INSTALL_HINT}"
+        )
     task_index_template = (
         workspace_root / "templates" / "project-docs" / "task-index.template.md"
     )
@@ -304,7 +316,9 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     run_validator = workspace_root / "validators" / "validate-run.py"
     for required in (task_index_template, final_report_template, run_validator, source_skill):
         if not required.is_file():
-            raise PrepareError(f"required okstra template or source skill missing: {required}")
+            raise PrepareError(
+                f"required okstra template or source skill missing: {required}.{_INSTALL_HINT}"
+            )
     if not project_root.is_dir():
         raise PrepareError(f"project root not found: {project_root}")
     if not inp.brief_path.is_file():
@@ -329,7 +343,11 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     try:
         upsert_project_json(project_root, inp.project_id)
     except ResolverError as exc:
-        raise PrepareError(f"project.json upsert failed: {exc}") from exc
+        # Surface the project_root in the prefix so the user can tell which
+        # registration failed when multiple projects are in play. The full
+        # underlying ResolverError text (which carries remediation guidance)
+        # is preserved by the `: {exc}` suffix and the `raise ... from exc`.
+        raise PrepareError(f"project.json upsert failed for {project_root}: {exc}") from exc
 
     # ---- workers resolution ----
     profile_workers_csv = ",".join(resolve_profile_workers(profile_file))

package/runtime/python/okstra_ctl/workflow.py

@@ -98,7 +98,9 @@ PHASE_RULES: dict[str, dict[str, str]] = {
             "  - source edits or Bash mutations performed by any verifier role (`Gemini verifier`, `Codex verifier`, `Claude verifier` are read-only — recommend, do not apply)\n"
             "  - dispatching parallel sub-agents beyond the required worker roster\n"
             "  - silent scope expansion: every file edited outside the approved plan list MUST appear in the `Out-of-plan edits` block with rationale\n"
-            '  - leaving placeholders such as TBD / TODO / "implement later" / "handle edge cases" in committed code\n'
+            '  - leaving placeholders such as TBD / TODO / "implement later" / "handle edge cases" in newly-added lines of this run (check via `git diff <base>..HEAD | grep -E \'^\\+[^+].*\\b(TBD|TODO|FIXME|XXX|implement later|handle edge cases|similar to|placeholder)\\b\'`; pre-existing strings in untouched regions are out of scope)\n'
+            "  - lead substituting its own verdict when every required verifier (`Gemini verifier`, `Codex verifier`, `Claude verifier`) returned a non-result terminal status (`timeout`/`error`/`not-run`); in that case the run MUST end as `blocked` with routing recommendation back to `error-analysis`, never with a lead-only verdict\n"
+            "  - claiming rollback verification on a schema migration, config-format change, or any persisted-state mutation without a recorded dry-run of the rollback step and its captured exit code\n"
             '  - declaring overall task acceptance — that is `final-verification` ownership; this phase reports only "ready for final-verification" or "needs new planning loop"\n'
             "  - delegating the self-review pass to a generic subagent — `Claude lead` must run it"
         ),

package/runtime/python/okstra_project/resolver.py

@@ -75,9 +75,12 @@ def resolve_project_root(*, explicit_root: str = "",
     if git_top is not None:
         return git_top.resolve()
     raise ResolverError(
-        "PROJECT_ROOT 를 해석할 수 없습니다. "
-        "--project-root 를 명시하거나, 프로젝트 루트(또는 그 하위)에서 실행하거나, "
-        "git 작업 트리 안에서 실행해 주십시오.")
+        "could not resolve PROJECT_ROOT from cwd. "
+        "Pass --project-root <abs-path>, "
+        "run from inside a project (a directory with .project-docs/okstra/project.json at or above cwd), "
+        "or run from inside a git working tree. "
+        "(PROJECT_ROOT 를 해석할 수 없습니다 — --project-root 를 명시하거나, "
+        "프로젝트 루트 또는 그 하위에서 실행하거나, git 작업 트리 안에서 실행해 주십시오.)")
 
 
 def upsert_project_json(project_root: Path, project_id: str, *,
@@ -100,13 +103,20 @@ def upsert_project_json(project_root: Path, project_id: str, *,
             data = json.loads(target.read_text())
         except (OSError, json.JSONDecodeError) as exc:
             raise ResolverError(
-                f"project.json 을 읽을 수 없습니다: {target} ({exc})") from exc
+                f"failed to read project.json at {target}: {exc} "
+                f"(project.json 을 읽을 수 없습니다.) "
+                f"If the file is corrupted, delete it and re-run 'okstra setup --project-id <id>'."
+            ) from exc
         existing_id = str(data.get("projectId") or "")
         if existing_id and existing_id != project_id:
             raise ResolverError(
-                f"projectId 불일치: project.json={existing_id!r}, "
-                f"인자={project_id!r}. "
-                f"동일 PROJECT_ROOT 에서는 하나의 projectId 만 사용할 수 있습니다.")
+                f"projectId mismatch: existing project.json has {existing_id!r} "
+                f"but the supplied argument is {project_id!r}. "
+                f"okstra allows only one projectId per PROJECT_ROOT. "
+                f"To fix: re-run with --project-id {existing_id!r} to keep the existing registration, "
+                f"or manually delete {target} if you intend to re-register this directory "
+                f"under a different id. "
+                f"(projectId 불일치: 한 PROJECT_ROOT 에는 하나의 projectId 만 허용됩니다.)")
         result = {
             "projectId": project_id,
             "projectRoot": abs_root,

package/src/check-project.mjs

@@ -103,10 +103,15 @@ export async function run(args) {
   );
 
   if (probe.code !== 0) {
+    const raw = probe.stderr.trim() || probe.stdout.trim();
     emit(opts, {
       ok: false,
       stage: "python",
-      reason: `python invocation failed: ${probe.stderr.trim() || probe.stdout.trim()}`,
+      reason:
+        `python invocation failed: ${raw}. ` +
+        "This usually means the okstra runtime is stale or missing — " +
+        "run 'okstra doctor' to diagnose, then 'okstra ensure-installed' " +
+        "to repair.",
     });
     return 1;
   }

package/src/setup.mjs

@@ -1,6 +1,8 @@
 import { promises as fs } from "node:fs";
 import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
+import { homedir } from "node:os";
+import { resolve as resolvePath } from "node:path";
 import { resolvePaths } from "./paths.mjs";
 
 const USAGE = `okstra setup — register the current project with okstra
@@ -192,8 +194,51 @@ export async function run(args) {
   try {
     resolved = await resolveProjectRoot(paths, opts.projectRoot);
   } catch (err) {
+    if (err.code === "RESOLVER") {
+      const cwd = resolvePath(process.cwd());
+      const home = resolvePath(homedir());
+      const inHome = cwd === home;
+      process.stderr.write(
+        "error: 'okstra setup' registers the CURRENT directory as an okstra project,\n" +
+          "       but no project root could be resolved from here.\n" +
+          `       cwd: ${cwd}\n` +
+          (inHome
+            ? "       (this looks like your home directory — setup is project-level, not machine-level;\n" +
+              "        machine-level install is 'okstra install', which you've likely already done.)\n"
+            : "") +
+          "\nFix one of:\n" +
+          "  1. cd into the project you want to register, then re-run:\n" +
+          "       cd <your project> && okstra setup --project-id <id>\n" +
+          "  2. pass an explicit path:\n" +
+          "       okstra setup --project-root <abs-path> --project-id <id>\n" +
+          "  3. run from inside any git working tree (the toplevel becomes PROJECT_ROOT).\n" +
+          `\n(underlying error: ${err.message})\n`,
+      );
+      return 2;
+    }
+    // Non-RESOLVER path: typically python invocation failure (PYTHONPATH wrong,
+    // ~/.okstra missing, python3 not on PATH, okstra_project module missing).
+    // The user can't fix this by adjusting setup arguments — it's a runtime
+    // health issue, not a PROJECT_ROOT issue. Reword accordingly.
+    const looksLikePythonFailure = /python invocation failed|ModuleNotFoundError|No module named/.test(
+      err.message,
+    );
+    if (looksLikePythonFailure) {
+      process.stderr.write(
+        "error: 'okstra setup' could not start because the okstra runtime is not\n" +
+          "       reachable from this process. This is almost always a stale or\n" +
+          "       incomplete install, not a problem with your setup arguments.\n" +
+          "\nFix:\n" +
+          "  1. run 'okstra doctor' to see exactly what is missing\n" +
+          "  2. run 'okstra ensure-installed' (or 'npx -y okstra@latest install')\n" +
+          "     to repair the runtime\n" +
+          "  3. retry: okstra setup --project-id <id>\n" +
+          `\n(underlying error: ${err.message})\n`,
+      );
+      return 1;
+    }
     process.stderr.write(`error: could not resolve PROJECT_ROOT: ${err.message}\n`);
-    return err.code === "RESOLVER" ? 2 : 1;
+    return 1;
   }
   const { projectRoot, projectJsonPath } = resolved;