okstra 0.150.0 → 0.151.0

package/docs/cli.md

@@ -720,7 +720,7 @@ The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and
 | `okstra convergence apply-critic-gaps --work-state <path> --results <path>` | Apply one verified coverage-critic batch after the main queue reaches a terminal state |
 | `okstra convergence finalize --work-state <path> --output <path>` | Materialize the terminal schema v1.3 convergence state |
 | `okstra convergence validate --state <path> --kind <working\|final>` | Validate replayable working state or a terminal final state |
-| `okstra convergence example --kind <groups\|round-results\|critic-results>` | Print one deterministic valid input example as JSON |
+| `okstra convergence example --kind <groups\|round-results\|critic-results>` | Print one deterministic valid input example as JSON. `groups` feeds `seed --groups` and `round-results` feeds `apply-round --results`; `critic-results` is the critic worker's own result document and is **not** the `apply-critic-gaps --results` input — that input is the coverage batch the lead assembles from those candidates plus each analyser's vote (`dispatches[]` / `gaps[]` / `modelExecutionValue`) |
 | `okstra plan-items extract --data <data.json> --output <items.json>` | Deterministically extract the complete implementation-planning `P-*` queue from report-writer data.json |
 | `okstra plan-items validate --data <data.json> --items <items.json>` | Require the persisted `P-*` queue to match a fresh deterministic extraction exactly |
 | `okstra config <get\|set\|unset\|show> [key] [value] [--scope project\|global\|all]` | Manage persistent settings such as `pr-template-path` with atomic JSON writes |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.150.0",
+  "version": "0.151.0",
   "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",
@@ -38,6 +38,7 @@
     "test:js": "node --test tests-js/*.test.mjs",
     "test:py": "python3 -m pytest tests/",
     "test:workflow": "bash validators/validate-workflow.sh",
-    "check": "npm run build && npm run test:js && npm run test:py && npm run test:workflow"
+    "test:e2e": "bash tests-e2e/run-all.sh",
+    "check": "npm run build && npm run test:js && npm run test:py && npm run test:workflow && npm run test:e2e"
   }
 }

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.150.0",
-  "builtAt": "2026-08-05T03:48:23.472Z",
+  "package": "0.151.0",
+  "builtAt": "2026-08-05T06:06:04.770Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/workers/report-writer-worker.md

@@ -19,6 +19,14 @@ tools: ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "TodoWrite", "WebFetch"
 - The `**Report Language:**` header in your dispatch prompt is already
   resolved to `en` or `ko` by the lead. Copy it verbatim into
   `data.json.meta.reportLanguage`. Never write `auto` here.
+- **That header is not the language you write in — you always write English.**
+  It names the language the human HTML renders in, and Phase 7 reads it to
+  decide whether to dispatch a translator. The data.json is the SSOT every
+  later phase, validator and agent reads, so authoring it in anything but
+  English splits the record. **Enforced:** `okstra report-finalize` runs
+  `report-translate check-source` as its first Phase 7 step and fails the run
+  when the data.json's authored prose is not English. You can run that check
+  yourself before returning.
 
 ## Authority
 

package/runtime/bin/okstra-report-translate.py

@@ -44,7 +44,12 @@ if (SCRIPTS_DIR / "okstra_ctl" / "report_translation.py").is_file():
 elif HOME_LIB.is_dir() and str(HOME_LIB) not in sys.path:
     sys.path.insert(0, str(HOME_LIB))
 
-from okstra_ctl.report_translation import extract, overlay  # noqa: E402
+from okstra_ctl.report_translation import (  # noqa: E402
+    HANGUL_PROSE_LIMIT,
+    extract,
+    hangul_share,
+    overlay,
+)
 from okstra_ctl.final_report_paths import (  # noqa: E402
     translation_sidecar_path,
     translation_source_path,
@@ -132,6 +137,28 @@ def cmd_check(args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_check_source(args: argparse.Namespace) -> int:
+    data_path = Path(args.data).resolve()
+    share, length = hangul_share(_load(data_path))
+    payload = {
+        "ok": share < HANGUL_PROSE_LIMIT,
+        "hangulShare": round(share, 4),
+        "limit": HANGUL_PROSE_LIMIT,
+        "proseChars": length,
+    }
+    print(json.dumps(payload, ensure_ascii=False))
+    if not payload["ok"]:
+        sys.stderr.write(
+            f"error: {data_path.name} was authored in Korean "
+            f"({share:.0%} of its prose, limit {HANGUL_PROSE_LIMIT:.0%}). "
+            "The data.json is the English SSOT every later phase reads; the "
+            "report language selects the human HTML's language and is served "
+            "by the Phase 7 translator, not by authoring the SSOT in it.\n"
+        )
+        return 1
+    return 0
+
+
 def _parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="okstra-report-translate.py",
@@ -146,6 +173,12 @@ def _parser() -> argparse.ArgumentParser:
     check_cmd = sub.add_parser("check", help="verify a filled sidecar against its report")
     check_cmd.add_argument("sidecar", help="path to final-report-<type>-<seq>.i18n.<lang>.json")
     check_cmd.set_defaults(func=cmd_check)
+
+    source_cmd = sub.add_parser(
+        "check-source", help="verify the data.json itself was authored in English"
+    )
+    source_cmd.add_argument("data", help="path to final-report-<type>-<seq>.data.json")
+    source_cmd.set_defaults(func=cmd_check_source)
     return parser
 
 

package/runtime/prompts/lead/plan-body-verification.md

@@ -175,7 +175,7 @@ Plan-body verification stays **lightweight** even under this posture — the `ve
 
 1. Lead runs `okstra plan-items extract --data <data.json> --output <state>/plan-items-....json`, places the persisted `items[]` verbatim in every verifier prompt with the compact `subject` and lossless `payload`, then runs `okstra plan-items validate --data <data.json> --items <state>/plan-items-....json`. Dispatch only after that exact-match validation succeeds.
 2. For each analyser worker in the roster (`claude`, `codex`, and `antigravity` if opted in), lead constructs a reverify prompt using the template in §"Plan-body reverify prompt" below.
-3. Dispatch uses the same wrapper infrastructure as finding convergence. The `--role-slug` is `<role>-plan-verify-r<N>`. Result file path: `runs/<task-type>/worker-results/<role-slug>-plan-verify-r<N>-implementation-planning-<seq>.md`.
+3. Dispatch uses the same wrapper infrastructure as finding convergence, so the `--role-slug` is the same canonical `<role>-worker` that convergence uses — not a round-specific slug. Result file path: `runs/<task-type>/worker-results/<role>-worker-plan-verify-r<N>-implementation-planning-<seq>.md` (e.g. `codex-worker-plan-verify-r1-implementation-planning-003.md`). The `-worker-` token is load-bearing twice over: §"Plan-body reverify prompt" requires the same anchor headers as convergence, whose `**Audit sidecar path:**` is derived by `okstra_ctl.worker_artifact_paths.audit_sidecar_rel()` inserting `-audit-` after that token — a slug without it makes the header underivable and the helper raises. Record each `planItems[].verdicts[].worker` as the same `<role>-worker` string, because provenance compares it to this filename's prefix. **Enforced:** `tests/contract/test_reverify_dispatch_anchors.py` derives the sidecar from the documented name and re-extracts the prefix the provenance resolver uses.
    **Verdict provenance (BLOCKING).** Every verdict recorded in `planItems[].verdicts[]` MUST trace back to a dispatch that actually returned a result file at the path above. The whole gate — classification, self-fix eligibility, promotion, `gateBlockedBy` — is computed from these votes, so an unbacked vote lets the round be skipped while the gate still reads `passed`. **Enforced:** `validators/validate-run.py` `_validate_plan_body_verdict_provenance` fails any `verdicts[].worker` with no matching `<worker>-plan-verify-r<N>-<task-type>-<seq>.md` result file. Recording a `verification-error` for a dispatch that produced no result is the correct way to represent a failed worker — inventing an `AGREE` is a contract violation.
 
 4. After all dispatches return, lead aggregates verdicts per `P-*` item across workers and classifies each:

package/runtime/prompts/lead/report-writer.md

@@ -176,7 +176,7 @@ Table Generation Rules:
 
 Place this section immediately after the execution status table.
 
-Example (English mode shown — the renderer substitutes Korean when `meta.reportLanguage = "ko"`):
+Example (the Markdown renders in English whatever `meta.reportLanguage` says):
 
 ```markdown
 ### Token Usage Summary
@@ -233,7 +233,7 @@ The rows below mirror `PLANNING_REQUIRED_SECTIONS` in `validators/validate-run.p
 
 `Implementation Design Preparation` is NOT in the substring list: `templates/reports/final-report.template.md` §5.5.10 renders that heading from `implementationPlanning.designPreparation`, so it is enforced by the schema + renderer rather than by a heading scan.
 
-The Korean translation in parentheses is optional but the English keyword is mandatory. The body of each section is written in the Report Language per the writing rules below. For non-`implementation-planning` runs, omit this entire block — these headings are NOT validator-checked for other task-types.
+The English keyword is mandatory and the body of each section is written in English, like everything else you author — see "Writing Guidelines" below. For non-`implementation-planning` runs, omit this entire block — these headings are NOT validator-checked for other task-types.
 
 The final-report template `templates/reports/final-report.template.md` Section 5.5 already encodes this contract — copy that block verbatim and fill in.
 

package/runtime/python/okstra_ctl/convergence.py

@@ -123,7 +123,21 @@ def _parser() -> argparse.ArgumentParser:
     subparsers = parser.add_subparsers(dest="operation", required=True)
 
     example = subparsers.add_parser(
-        "example", help="print a deterministic input artifact example"
+        "example",
+        help="print a deterministic input artifact example",
+        description=(
+            "Print one deterministic valid example as JSON.\n\n"
+            "`groups` feeds `seed --groups` and `round-results` feeds "
+            "`apply-round --results`, but `critic-results` is the critic "
+            "worker's own result document — NOT the `apply-critic-gaps "
+            "--results` input. That input is the coverage batch the lead "
+            "assembles from those candidates plus each analyser's vote "
+            '({schemaVersion, taskKey, mode: "coverage", provider, '
+            "modelExecutionValue, dispatches[], gaps[]}); see "
+            'prompts/lead/convergence.md §"Coverage critic". Feeding this '
+            "example straight into `apply-critic-gaps` is rejected, by design."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     example.add_argument(
         "--kind",

package/runtime/python/okstra_ctl/report_finalize.py

@@ -24,12 +24,17 @@ from .final_report_paths import final_report_data_path, final_report_markdown_pa
 from .paths import task_dir, task_manifest_file
 
 
+STEP_CHECK_SOURCE = "check-source"
 STEP_TOKEN_USAGE = "token-usage"
 STEP_RENDER_VIEWS = "render-views"
 STEP_SPAWN_FOLLOWUPS = "spawn-followups"
 STEP_VALIDATE_RUN = "validate-run"
 
 STEP_ORDER = (
+    # First, because everything after it derives from the data.json: rendering
+    # a Korean SSOT into English chrome, spawning follow-ups from it, and
+    # validating it all succeed on a record the next phase cannot read.
+    STEP_CHECK_SOURCE,
     STEP_TOKEN_USAGE,
     STEP_RENDER_VIEWS,
     STEP_SPAWN_FOLLOWUPS,
@@ -205,6 +210,19 @@ def build_commands(ctx: FinalizeContext) -> list[tuple[str, list[str]]]:
     """Assemble the ordered Phase 7 argv list. Order is contractual."""
     markdown_path = ctx.markdown_path
     return [
+        (
+            STEP_CHECK_SOURCE,
+            [
+                sys.executable,
+                str(
+                    resolve_workspace_script(
+                        ctx.workspace_root, "okstra-report-translate.py"
+                    )
+                ),
+                "check-source",
+                str(ctx.data_path),
+            ],
+        ),
         (
             STEP_TOKEN_USAGE,
             [

package/runtime/python/okstra_ctl/report_translation.py

@@ -393,6 +393,35 @@ def overlay(
     return out, OverlayReport(applied, untranslated, tuple(sorted(unresolved)))
 
 
+# Above this share of Hangul, the prose was authored in Korean rather than
+# quoting some. Measured across real reports: Korean-authored ones sit at
+# 35-38%, English ones that quote a Korean brief or a worker's Korean phrase
+# reach 8% at most. The gap is wide enough that no threshold inside it is
+# delicate. Only the strings `extract` offers are counted — a verbatim quote of
+# the user's request is structural and never reaches this.
+HANGUL_PROSE_LIMIT = 0.20
+
+
+def hangul_share(data: Mapping[str, Any]) -> tuple[float, int]:
+    """Return the Hangul share of the report's authored prose, and its length."""
+    text = "".join(extract(data).values())
+    if not text:
+        return 0.0, 0
+    hangul = sum(1 for char in text if "가" <= char <= "힣")
+    return hangul / len(text), len(text)
+
+
+def prose_is_english(data: Mapping[str, Any]) -> bool:
+    """Whether the data.json was authored in English, as the SSOT contract requires.
+
+    The report language names what the human HTML renders in, not what the
+    worker writes. A worker that authors Korean anyway hands every later phase,
+    validator and agent a record in a language they do not read.
+    """
+    share, _ = hangul_share(data)
+    return share < HANGUL_PROSE_LIMIT
+
+
 def _schema_string_keys(schema: Mapping[str, Any], *, enums: bool) -> set[str]:
     found: set[str] = set()
 

package/runtime/validators/validate-run.py

@@ -61,6 +61,10 @@ from okstra_ctl.mutation_probe import (  # noqa: E402
     classify_reason,
 )
 from okstra_ctl.self_mock_signals import selfmock_path_key  # noqa: E402
+from okstra_ctl.report_translation import (  # noqa: E402
+    HANGUL_PROSE_LIMIT,
+    hangul_share,
+)
 from okstra_ctl.stage_citations import cited_stage_numbers  # noqa: E402
 from okstra_ctl.workflow import DEFAULT_NEXT_PHASE, PHASE_SEQUENCE  # noqa: E402
 from okstra_ctl.md_table import (  # noqa: E402
@@ -6316,6 +6320,32 @@ def _validate_improvement_discovery(
             failures.append(f"improvement-discovery: {err}")
 
 
+def _validate_ssot_is_english(data: dict, failures: list[str]) -> None:
+    """Enforce: the final-report data.json is authored in English.
+
+    `meta.reportLanguage` names the language the human HTML renders in, and
+    Phase 7's translator serves it from a sidecar. The data.json itself is the
+    record every later phase, validator and agent reads, so a worker that
+    authors it in the reader's language instead splits the record — and does so
+    silently, because rendering, follow-up spawning and validation all succeed
+    on it.
+
+    `report-finalize` runs the same check as its first step, before anything
+    derives from the report. This is the second gate, for a report that reached
+    validation by some other path.
+    """
+    if not data:
+        return
+    share, length = hangul_share(data)
+    if length and share >= HANGUL_PROSE_LIMIT:
+        failures.append(
+            f"final-report data.json was authored in Korean ({share:.0%} of its "
+            f"prose, limit {HANGUL_PROSE_LIMIT:.0%}). The data.json is the "
+            "English SSOT; meta.reportLanguage selects the human HTML's "
+            "language and is served by the Phase 7 translator sidecar."
+        )
+
+
 def _validate_fix_cycle(run_manifest: dict, data: dict, failures: list[str]) -> None:
     """Enforce: when the run-manifest carries a fixCycleId, the final-report
     data.json MUST contain a fixCycle block whose ``cycle`` matches it.
@@ -7206,6 +7236,7 @@ def main() -> int:
         ),
     )
     validation_data = report_data if isinstance(report_data, Mapping) else {}
+    _validate_ssot_is_english(validation_data, failures)
     _validate_fix_cycle(run_manifest, validation_data, failures)
     validate_report(
         report_path,