okstra 0.165.4 → 0.166.1

package/docs/for-ai/skills/okstra-run.md

@@ -225,12 +225,13 @@ When `task-type == implementation` and the render-args `chain-stages` CSV has 2
 
 1. Re-call render-bundle with the same arguments but `--stage N` (the base commit is auto-computed by prepare from the predecessor's done `head_commit` — do not pass it by hand). The `io`-only conformance waiver·concurrent-run·git-reconcile gates apply identically to each stage's render-bundle.
 2. As in Step 6, become the host-native Okstra lead and run that stage's Phase 1–7 inline. Phase 6's lead persistence appends that stage's `status:"done"` row to `runs/<plan-task-key>/consumers.jsonl`.
-3. After confirming the `done` row was written, move to the next stage. Clean up context (leftover panes·finished teammates) at each stage boundary.
+3. After confirming the `done` row was written, move to the next stage. Clean up context (leftover panes·finished teammates) at each stage boundary. A `status:"failed"` row in place of `done` means the stage ended `FAIL` — stop the queue per the FAIL branch below.
 4. One-line report at each stage start/finish: `stage N/<total> start` / `stage N done → next K`.
 
 Once the whole queue is consumed, end the chain and report completion.
 
 - **Next stage not yet ready — normal termination:** When a stage in the queue is occupied by another implementation run as started/reserved and render-bundle is rejected with `--stage N already in progress or reserved by another run` (StageTargetError), this is not an exception — **terminate the chain normally** and report the remaining queue (e.g. `remaining queue: stage 4, 5 — resume with okstra-run after occupancy is released`).
+- **Stage ended FAIL — stop the queue and report:** When a stage's synthesised verdict is `FAIL`, Phase 6 writes no carry sidecar and appends a `status:"failed"` row instead of `done`. **Stop the queue there** and report the failed stage, its report path, and the remaining queue. Do not continue to the next stage even when it is dependency-independent — later work must not be stacked on a confirmed regression. The `failed` row frees the occupancy, so `--stage <N>` re-enters that stage on its preserved worktree and branch.
 - **Exception gate during chaining:** If render-bundle raises a concurrent-run conflict or git stale-SHA reconciliation, **stop the chain at that stage** and present the gate to the user per the Step 5 procedure. Once the user resolves it, resume the remaining queue in place. Data corruption·concurrent-occupancy conflicts are confirmed by a human — this is the safety boundary of unattended chaining.
 
 ## Forbidden patterns

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.165.4",
+  "version": "0.166.1",
   "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.165.4",
-  "builtAt": "2026-08-11T10:11:57.736Z",
+  "package": "0.166.1",
+  "builtAt": "2026-08-11T12:28:22.915Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/prompts/host-orchestration/implementation.md

@@ -53,5 +53,8 @@ If the anchor (`implementation_base_commit`) is reported unresolvable, run the s
 ### Next stage not yet ready — normal termination (not an exception gate)
 Because of the dependency closure, the chain queue **may include a stage that another implementation run has occupied as started/reserved.** That stage's `render-bundle` is rejected with `--stage N already in progress or reserved by another run` (StageTargetError). This is **not** an exception gate needing human judgment but a "next stage not yet ready" situation. On this rejection, **terminate the chain normally** and report the remaining queue to the user (e.g. `remaining queue: stage 4, 5 — resume with okstra-run after occupancy is released`). This is a different branch from the exception gate below (data corruption·concurrent-occupancy conflict confirmation).
 
+### Stage ended FAIL — stop the queue and report (not an exception gate)
+When a stage's synthesised verdict is `FAIL`, Phase 6 writes no carry sidecar and appends a `status:"failed"` row in place of `done` (`prompts/profiles/_implementation-deliverable.md` "Lead post-stage persistence"). **Stop the queue at that stage** and report the failed stage, its report path, and the remaining queue (e.g. `stage 1 FAIL — remaining queue: stage 2, 3, 5; re-enter with okstra-run --stage 1 after the fix`). Do **not** continue to the next stage even when that stage is dependency-independent: an unattended chain that keeps building past a confirmed regression stacks later work on top of it. The `failed` row releases the stage's occupancy, so `--stage <N>` re-enters the same stage on its preserved worktree and branch — there is nothing to unblock by hand.
+
 ### Exception gate during chaining
 If `render-bundle` raises Step 5's concurrent-run conflict detection (concurrent-run branch) or git stale-SHA reconciliation (git-reconcile branch), **stop the chain at that stage** and present the gate to the user exactly as Step 5 prescribes. Once the user resolves the gate, resume the chain in place (continue with the remaining queue). Data corruption·concurrent-occupancy conflicts are confirmed by a human — this is the safety boundary of unattended chaining. (Unlike the "not ready" rejection above, these two branches do not discard the queue; they wait for user resolution.)

package/runtime/prompts/profiles/_implementation-executor.md

@@ -82,7 +82,8 @@ persisted prompt lacks the heading `Coding-conventions preflight`
   ```
 
   The file MUST NOT exist before the run starts (overwrite is refused — see `--force-stage` non-goal). **Enforced:** `validators/validate-run.py` `_validate_stage_carry_sidecar_exists` fails a run that declares `stageSidecarEvidence` without the file on disk. Transcribing the JSON into the report is not the same as writing it: `consumers` treats the carry file as the source of truth for marking the stage `done`, so a missing file leaves the stage permanently incomplete and blocks every dependent stage with a `PrepareError` — while this run reports success.
-- **Reverse link (BLOCKING).** The runtime already appended a `status:"started"` row for this stage before the run began. On completion, append a `status:"done"` row with `carry_path` populated for this stage number.
+- **An external Tier 3 non-PASS does NOT withhold the carry evidence.** A Tier 3 entry whose `requires` include `http`, `external`, or `db` is advisory. Its FAIL, MISSING, no result, startup failure, or credential / network / service absence gets recorded honestly — exact command, exit code, output tail, marked `ADVISORY` in `Validation evidence` — and you emit the carry evidence anyway. Only Tier 1 and Tier 2 failures withhold it. Withholding on an external result is what actually blocks the stage: the carry file is the only thing that can mark a stage `done`, the verifier re-runs that same command from the host (where a call your sandbox could not complete often passes), and a stage the verifier then PASSes can never be closed because its evidence was never written.
+- **Reverse link (BLOCKING).** The runtime already appended a `status:"started"` row for this stage before the run began. The terminal row belongs to the lead's post-stage persistence and is verdict-gated — `status:"done"` with `carry_path` on a non-`FAIL` verdict, `status:"failed"` on `FAIL` (`_implementation-deliverable.md` §"Lead post-stage persistence").
 - **No PR / push in this phase.** This run produces local commits, carry sidecar evidence, verifier results, and the implementation final report only. Push and PR creation belong exclusively to the later `release-handoff` phase after `final-verification` returns `accepted`.
 
 ## Allowed actions during the run

package/runtime/prompts/profiles/implementation-planning.md

@@ -132,7 +132,7 @@
         unavailable environment is a user-owned follow-up, never a plan approval or
         later run blocker. `requires=[]` and `requires=[io]` remain blocking.
         Remote IO should also declare `external`.
-      The manifest lives at the **task level** (`<task_root>/qa/`, path token `TASK_QA_PATH`) and is shared across planning → implementation → final-verification. Layout split: executable scripts (conformance + any real-IO test) live under `<task_root>/qa/scripts/`; data sidecars (`conformance-manifest.json`, `result-*.json`) stay at the `qa/` root. This declaration is enforced at four layers: `validators/validate-implementation-plan-stages.py` check **S11** forces every stage to carry one of the two lines; at the planning boundary `validators/validate-run.py` `_validate_planning_conformance_declared` fails when a stage that declared `Conformance tests:` has no matching `-stage-<N>` entry in the shared manifest (a declaration that was never materialized); the manifest JSON structure — including each entry's `script` living under `qa/scripts/` — is enforced by `validate_conformance_manifest` (called from both the run path and validate-run); and the result policy is evaluated by `conformance.py` and `validate-run.py`.
+      The manifest lives at the **task level** (`<task_root>/qa/`, path token `TASK_QA_PATH`) and is shared across planning → implementation → final-verification. The verifier runs `runCommand` from the **worktree cwd**, and that cwd is the tree under test — it is what makes the script see this stage's diff. So `runCommand` MUST NOT repoint it: a leading `cd <checkout> &&` sends the script at whichever tree it names, which at implementation time is a checkout without the stage's changes and at final-verification is not the integrated tree either. Absolute paths are fine and usually necessary — the script and its `tsconfig` live under `<task_root>/qa/scripts/`, i.e. under `.okstra/`, and a worktree does not carry `.okstra/` (worker preamble: "`.okstra/**` artifacts remain anchored at `**Project Root:**`; the worktree may not contain them"). Point at those by absolute path; leave the cwd alone. **Enforced:** `scripts/okstra_ctl/conformance.py` `_check_entry` rejects a `runCommand` whose first word in any `&&` / `;` segment changes directory. Layout split: executable scripts (conformance + any real-IO test) live under `<task_root>/qa/scripts/`; data sidecars (`conformance-manifest.json`, `result-*.json`) stay at the `qa/` root. This declaration is enforced at four layers: `validators/validate-implementation-plan-stages.py` check **S11** forces every stage to carry one of the two lines; at the planning boundary `validators/validate-run.py` `_validate_planning_conformance_declared` fails when a stage that declared `Conformance tests:` has no matching `-stage-<N>` entry in the shared manifest (a declaration that was never materialized); the manifest JSON structure — including each entry's `script` living under `qa/scripts/` — is enforced by `validate_conformance_manifest` (called from both the run path and validate-run); and the result policy is evaluated by `conformance.py` and `validate-run.py`.
     - `### Stage Exit Contract` — predicted added/modified files, newly exposed identifiers/types/endpoints, downstream-usable resources.
     - `### Stage Validation` — pre / mid / post exact commands or observable outcomes for this stage only.
       - **Dependency precondition (stages that run the project toolchain).** The planning worktree is created without installed dependencies, so a stage whose steps call `npm` / `yarn` / `pytest` / `cargo` / equivalent cannot have those commands succeed at plan time — they exit `127`, not RED/GREEN. Declare the install **once** as a `phase: pre` row in `### Validation Checklist` (e.g. `VC-008 — the implementation run's stage worktree has workspace dependencies installed`) and have every such stage's `Stage Validation` cite that `VC-NNN` in its `pre:` line. Do not repeat the install commands per stage, and do not silently assume the tooling is present: a plan that never states the precondition produces steps whose commands never resolve, which the §5.5.9 round then reports as unverifiable. **Enforced (advisory):** `validators/validate-run.py` `_detect_missing_dependency_precondition` warns when a toolchain-invoking stage cites no `VC-NNN`, or cites one that is not `phase: pre`. Whether the cited row genuinely covers dependencies is a §5.5.9 judgement, not a machine check. Detection uses the token allowlist in `scripts/okstra_ctl/build_tools.py`; a project overrides it with `buildToolTokens` in `.okstra/project.json`.

package/runtime/python/okstra_ctl/conformance.py

@@ -14,6 +14,10 @@ import fnmatch
 import re
 from dataclasses import dataclass
 
+# 셸에서 프로세스의 cwd 를 바꾸는 명령. verifier 가 워크트리 cwd 에서 실행하는
+# 계약이 이것들로 무력화된다.
+_CWD_CHANGING_COMMANDS: frozenset[str] = frozenset({"cd", "pushd", "popd", "chdir"})
+
 # diff 가 건드린 표면과 대조할 capability 태그 화이트리스트.
 CAPABILITY_WHITELIST: tuple[str, ...] = ("db", "io", "http", "external")
 EXTERNAL_ADVISORY_CAPABILITIES: frozenset[str] = frozenset(
@@ -89,6 +93,25 @@ def _check_entry(entry: object, idx: int, errors: list[str]) -> None:
     if isinstance(script, str) and script.strip() and "qa/scripts/" not in script:
         errors.append(f"{path}.script must live under the task qa scripts dir (qa/scripts/), got {script!r}")
     _check_nonempty_str(entry.get("runCommand"), f"{path}.runCommand", errors)
+    run_command = entry.get("runCommand")
+    # 이 명령은 워크트리 cwd 에서 verbatim 실행되고(_implementation-verifier.md
+    # "Otherwise run runCommand in the worktree cwd"), **그 cwd 가 곧 검사 대상**이다.
+    # 스크립트·tsconfig 는 `.okstra/` 아래 사는데 워크트리에는 `.okstra/` 가 없으므로
+    # (implementation-worker-preamble.md "the worktree may not contain them")
+    # 그것들을 절대경로로 가리키는 것은 정상이고 사실상 필수다. 금지되는 것은 cwd
+    # 를 옮기는 일뿐이다 — 선행 `cd <메인 체크아웃>` 은 stage diff 가 없는 트리에서
+    # 검사를 돌려 미변경 코드를 통과시킨다.
+    if isinstance(run_command, str):
+        for segment in re.split(r"&&|\|\||;|\|", run_command):
+            words = segment.split()
+            if words and words[0] in _CWD_CHANGING_COMMANDS:
+                errors.append(
+                    f"{path}.runCommand must run in the worktree cwd — that cwd is "
+                    f"the tree under test; a leading `{words[0]}` repoints it, so "
+                    "the script checks whichever checkout it lands in instead of "
+                    "this stage's diff"
+                )
+                break
     _check_nonempty_str(entry.get("passContract"), f"{path}.passContract", errors)
     req_ids = entry.get("requirementIds")
     if (

package/runtime/python/okstra_ctl/initial_prompt_materialization.py

@@ -392,9 +392,33 @@ def _resource_lines(
     )
     if clarification:
         bodies.append(clarification)
+    carry = _stage_fix_carry_body(context, item.plan)
+    if carry:
+        bodies.append(carry)
     return ["", "\n\n".join(bodies)]
 
 
+def _stage_fix_carry_body(
+    context: _MaterializationContext,
+    plan: PromptPlan,
+) -> str:
+    """The fix-run carry block, for the two audiences that act on it.
+
+    The executor's scope is the carried blocking findings, and the verifier MUST
+    cite each of them as resolved or still-failing — a fix-run verifier result
+    citing none is recorded as a contract violation. Both facts live in the
+    rendered analysis profile, which no CLI worker can read, so the block used to
+    reach them only if the lead transcribed it by hand. A missed transcription
+    made the worker answerable for a list it was never given.
+    """
+    if plan.audience not in ("implementation-executor", "implementation-verifier"):
+        return ""
+    run = context.active_context.get("run")
+    if not isinstance(run, Mapping):
+        return ""
+    return _string_value(run.get("fixRunCarry")).strip()
+
+
 def _resolve_clarification_input(
     context: _MaterializationContext,
     plan: PromptPlan,

package/runtime/python/okstra_ctl/path_hints.py

@@ -58,6 +58,7 @@ def compact_active_run_context(
         "workflow": dict(_mapping(payload.get("workflow"))),
         "run": {
             "stage": ctx.get("RUN_STAGE", ""),
+            "fixRunCarry": ctx.get("FIX_RUN_CONTEXT", ""),
         },
         "inputs": _compact_active_inputs(payload),
         "workers": _compact_active_workers(payload),
@@ -186,12 +187,13 @@ def _hydrate_active_run(
     payload: Mapping[str, Any],
     ctx: Mapping[str, str],
 ) -> dict[str, str]:
-    # `stage` is a run input, not a derived path, so pathHints cannot rebuild
-    # it — it survives the round trip only by being read back off the compact
-    # payload.
+    # `stage` and `fixRunCarry` are run inputs / derived content, not paths, so
+    # pathHints cannot rebuild them — they survive the round trip only by being
+    # read back off the compact payload.
     run = _mapping(payload.get("run"))
     return {
         "stage": str(run.get("stage", "") or ""),
+        "fixRunCarry": str(run.get("fixRunCarry", "") or ""),
         "runDirectoryPath": ctx.get("RUN_DIR_RELATIVE_PATH", ""),
         "runManifestPath": ctx.get("RUN_MANIFEST_RELATIVE_PATH", ""),
         "teamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),

package/runtime/python/okstra_ctl/render.py

@@ -511,6 +511,13 @@ def _active_run(ctx: dict) -> dict:
         # stage from `consumers.jsonl`. Feeds the implementation prompt anchor
         # in `initial_prompt_materialization`.
         "stage": ctx.get("RUN_STAGE", ""),
+        # A fix run's carried findings decide what the executor fixes and what
+        # the verifier MUST cite as resolved / still-failing. The rendered
+        # analysis profile holds the same block, but no CLI worker can read that
+        # file, so this copy is what `initial_prompt_materialization` inlines
+        # into their prompts. Derived once at prepare: re-deriving it later would
+        # read a worktree HEAD the executor may have already moved.
+        "fixRunCarry": ctx.get("FIX_RUN_CONTEXT", ""),
         "runDirectoryPath": ctx.get("RUN_DIR_RELATIVE_PATH", ""),
         "runManifestPath": ctx.get("RUN_MANIFEST_RELATIVE_PATH", ""),
         "teamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),

package/runtime/python/okstra_ctl/stage_fix_carry.py

@@ -45,10 +45,10 @@ class StageFixCarry:
             "Scope rules for this fix run live in the implementation sidecars "
             "(`_implementation-verifier.md` § Fix-run incremental scope, "
             "`report-writer.md` § Fix-run incremental authoring).",
-            "Lead duties: transcribe this block verbatim into every CLI "
-            "executor/verifier prompt (CLI processes cannot read this file), "
-            "and pass the previous data.json path above to the report-writer "
-            "dispatch so it authors incrementally.",
+            "This block is inlined into the executor and verifier prompts by "
+            "`initial_prompt_materialization`; do not transcribe it by hand. "
+            "Lead duties: pass the previous data.json path above to the "
+            "report-writer dispatch so it authors incrementally.",
         ])
         return "\n".join(lines)
 

package/runtime/skills/okstra-run/SKILL.md

@@ -320,6 +320,9 @@ If the anchor (`implementation_base_commit`) is reported unresolvable, run the s
 ### Next stage not yet ready — normal termination (not an exception gate)
 Because of the dependency closure, the chain queue **may include a stage that another implementation run has occupied as started/reserved.** That stage's `render-bundle` is rejected with `--stage N already in progress or reserved by another run` (StageTargetError). This is **not** an exception gate needing human judgment but a "next stage not yet ready" situation. On this rejection, **terminate the chain normally** and report the remaining queue to the user (e.g. `remaining queue: stage 4, 5 — resume with okstra-run after occupancy is released`). This is a different branch from the exception gate below (data corruption·concurrent-occupancy conflict confirmation).
 
+### Stage ended FAIL — stop the queue and report (not an exception gate)
+When a stage's synthesised verdict is `FAIL`, Phase 6 writes no carry sidecar and appends a `status:"failed"` row in place of `done` (`prompts/profiles/_implementation-deliverable.md` "Lead post-stage persistence"). **Stop the queue at that stage** and report the failed stage, its report path, and the remaining queue (e.g. `stage 1 FAIL — remaining queue: stage 2, 3, 5; re-enter with okstra-run --stage 1 after the fix`). Do **not** continue to the next stage even when that stage is dependency-independent: an unattended chain that keeps building past a confirmed regression stacks later work on top of it. The `failed` row releases the stage's occupancy, so `--stage <N>` re-enters the same stage on its preserved worktree and branch — there is nothing to unblock by hand.
+
 ### Exception gate during chaining
 If `render-bundle` raises Step 5's concurrent-run conflict detection (concurrent-run branch) or git stale-SHA reconciliation (git-reconcile branch), **stop the chain at that stage** and present the gate to the user exactly as Step 5 prescribes. Once the user resolves the gate, resume the chain in place (continue with the remaining queue). Data corruption·concurrent-occupancy conflicts are confirmed by a human — this is the safety boundary of unattended chaining. (Unlike the "not ready" rejection above, these two branches do not discard the queue; they wait for user resolution.)
 <!-- END FRAGMENT: host-orchestration-implementation -->
@@ -341,12 +344,12 @@ Queue = the topologically-sorted stage list from splitting `orchestration.chainS
 
 1. Call Step 5's `render-bundle` with the same arguments but `--stage N` (the base commit is auto-computed by prepare from the predecessor's done `head_commit`, so do not pass it by hand). Step 5's blocking local conformance waiver offer·concurrent-run detection·git-reconcile gates apply identically to each stage's `render-bundle`.
 2. As in Step 6, become the host-native Okstra lead and run that stage's Phase 1–7 inline. Phase 6's lead post-stage persistence appends that stage's `status:"done"` row to `runs/<plan-task-key>/consumers.jsonl` (per the implementation profile directive).
-3. After confirming that `done` row was written, reclaim the completed teammate panes of the stage you just finished: run `$HOME/.okstra/bin/okstra-trace-cleanup.sh --run-dir "<the run dir of the stage you just completed>"` (add `--keep report-writer-worker` if the report writer is still in flight). Then move to the next stage.
+3. After confirming that `done` row was written, reclaim the completed teammate panes of the stage you just finished: run `$HOME/.okstra/bin/okstra-trace-cleanup.sh --run-dir "<the run dir of the stage you just completed>"` (add `--keep report-writer-worker` if the report writer is still in flight). Then move to the next stage. A `status:"failed"` row instead of `done` means the stage ended `FAIL` — reclaim the panes the same way, then stop the queue per "Stage ended FAIL" above.
 4. One-line report at each stage start/finish: `stage N/<total> start` / `stage N done → next K`.
 
 Once the whole queue is consumed, end the chain and report completion to the user.
 
-The two branches that end or pause the queue — "Next stage not yet ready" and "Exception gate during chaining" — are in the host orchestration rules block above.
+The three branches that end or pause the queue — "Next stage not yet ready", "Stage ended FAIL", and "Exception gate during chaining" — are in the host orchestration rules block above.
 
 ## Persisting the PR template scope (release-handoff)
 

package/src/commands/lifecycle/install.mjs

@@ -915,7 +915,14 @@ export async function runInstall(args) {
     await writeFileAtomic(join(paths.home, "version"), paths.package + "\n", 0o644);
   }
   if (!opts.quiet) {
-    process.stdout.write(`  version stamp: ${paths.package}\n`);
+    // The source is already named at the top of the run; what the stamp line
+    // could not say is whether this install moved anything. `copied=0 skipped=N`
+    // plus a bare version reads identically for "already current" and "an older
+    // payload just landed over a newer home" — the latter cost a full run,
+    // caught only by hand-diffing installed files.
+    process.stdout.write(
+      `  version stamp: ${formatVersionTransition(paths.version, paths.package)}\n`,
+    );
     process.stdout.write("done.\n");
     process.stdout.write(
       "\nNext step: register the current project.\n" +
@@ -1011,6 +1018,15 @@ async function agentDriftReasons(paths) {
   return reasons;
 }
 
+// What the stamp did, not just where it landed: `0.165.3 -> 0.166.0` and
+// `0.166.0 (unchanged)` are the two cases a bare version line cannot tell apart,
+// and they mean opposite things about whether the install did anything.
+export function formatVersionTransition(previous, next) {
+  const from = String(previous ?? "").trim();
+  if (!from) return next;
+  return from === next ? `${next} (unchanged)` : `${from} -> ${next}`;
+}
+
 function summarise(label, result, target) {
   if (result.missingSource) {
     process.stdout.write(`  ${label}: source directory missing — skipped\n`);