okstra 0.166.0 → 0.166.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.166.0",
+  "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.166.0",
-  "builtAt": "2026-08-11T10:29:58.327Z",
+  "package": "0.166.1",
+  "builtAt": "2026-08-11T12:28:22.915Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

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/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`);