okstra 0.180.0 → 0.184.0

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

@@ -23,6 +23,7 @@ This script is the canonical single-reference-point. The Node CLI
 from __future__ import annotations
 
 import argparse
+import hashlib
 import json
 import os
 import sys
@@ -57,18 +58,77 @@ from okstra_ctl.final_report_paths import (  # noqa: E402
     translation_sidecar_path,
     translation_source_path,
 )
+from okstra_ctl.json_boundary import (  # noqa: E402
+    JsonBoundaryError,
+    load_owned_object,
+    load_owned_object_snapshot,
+    write_owned_object_atomic,
+)
+from okstra_ctl.fixed_text import line, scalar  # noqa: E402
+from okstra_ctl.convergence import (  # noqa: E402
+    ConvergenceContractError,
+    RunArtifactAuthority,
+    canonical_run_report_artifact,
+    validated_run_authority,
+)
 
 
 def _load(path: Path) -> dict:
     try:
-        payload = json.loads(path.read_text(encoding="utf-8"))
-    except OSError as exc:
-        raise SystemExit(f"error: cannot read {path}: {exc}") from exc
-    except json.JSONDecodeError as exc:
-        raise SystemExit(f"error: {path} is not valid JSON: {exc}") from exc
-    if not isinstance(payload, dict):
-        raise SystemExit(f"error: {path} must hold a JSON object")
-    return payload
+        return load_owned_object(path, artifact="report translation artifact")
+    except JsonBoundaryError as exc:
+        raise SystemExit(f"error: {exc}") from exc
+
+
+def _translation_authority(
+    manifest_path: Path,
+) -> tuple[RunArtifactAuthority, Path]:
+    try:
+        authority = validated_run_authority(manifest_path)
+        report = canonical_run_report_artifact(authority)
+    except (ConvergenceContractError, JsonBoundaryError) as exc:
+        raise SystemExit(f"error: {exc}") from exc
+    return authority, report
+
+
+def _report_snapshot(path: Path):
+    try:
+        return load_owned_object_snapshot(
+            path, artifact="report translation source"
+        )
+    except JsonBoundaryError as exc:
+        raise SystemExit(f"error: {exc}") from exc
+
+
+def _source_payload(
+    authority: RunArtifactAuthority, data_path: Path, raw_bytes: bytes, data: dict
+) -> dict:
+    return {
+        "taskKey": authority.task_key,
+        "runManifestPath": authority.manifest_ref,
+        "sourceData": data_path.name,
+        "sourceDataPath": data_path.relative_to(authority.project_root).as_posix(),
+        "sourceDataSha256": hashlib.sha256(raw_bytes).hexdigest(),
+        "lang": str((data.get("meta") or {}).get("reportLanguage") or ""),
+        "strings": extract(data),
+    }
+
+
+def _validate_source_payload(
+    source: dict, expected: dict, supplied_digest: str
+) -> None:
+    for key in (
+        "taskKey", "runManifestPath", "sourceData", "sourceDataPath",
+        "sourceDataSha256", "lang", "strings",
+    ):
+        if source.get(key) != expected.get(key):
+            raise SystemExit(
+                "error: report changed after translation source publication"
+            )
+    if supplied_digest != expected["sourceDataSha256"]:
+        raise SystemExit(
+            "error: report changed after translation source publication"
+        )
 
 
 def _english_source_failure(data_path: Path, data: dict) -> str | None:
@@ -99,18 +159,10 @@ def cmd_extract(args: argparse.Namespace) -> int:
     strings = extract(data)
     out_path = translation_source_path(data_path)
     lang = str((data.get("meta") or {}).get("reportLanguage") or "")
-    out_path.write_text(
-        json.dumps(
-            {
-                "lang": lang,
-                "sourceData": data_path.name,
-                "strings": strings,
-            },
-            ensure_ascii=False,
-            indent=2,
-        )
-        + "\n",
-        encoding="utf-8",
+    write_owned_object_atomic(
+        out_path,
+        {"lang": lang, "sourceData": data_path.name, "strings": strings},
+        artifact="translation source",
     )
     print(
         json.dumps(
@@ -128,8 +180,130 @@ def cmd_extract(args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_source(args: argparse.Namespace) -> int:
+    authority, data_path = _translation_authority(Path(args.run_manifest))
+    snapshot = _report_snapshot(data_path)
+    data = snapshot.value
+    failure = _english_source_failure(data_path, data)
+    if failure is not None:
+        sys.stderr.write(failure)
+        return 1
+    payload = _source_payload(authority, data_path, snapshot.raw_bytes, data)
+    out_path = translation_source_path(data_path)
+    if out_path.is_symlink():
+        raise SystemExit("error: translation source path is a symlink")
+    write_owned_object_atomic(
+        out_path, payload, artifact="translation source"
+    )
+    strings = payload["strings"]
+    print("# Translation work list")
+    print(line("Task key", authority.task_key), end="")
+    print(line("Report", payload["sourceDataPath"]), end="")
+    print(line("Run manifest", authority.manifest_ref), end="")
+    print(line("Source digest", payload["sourceDataSha256"]), end="")
+    print(line("String count", len(strings)), end="")
+    for index, source in enumerate(strings.values(), 1):
+        print(f"\n## T-{index:03d}\n{scalar(source)}")
+    return 0
+
+
+def _translation_blocks(path: Path) -> list[str]:
+    text = path.read_text(encoding="utf-8")
+    blocks: list[str] = []
+    current: list[str] | None = None
+    for row in text.splitlines():
+        if row.startswith("## T-"):
+            if current is not None:
+                blocks.append("\n".join(current).strip())
+            expected = f"## T-{len(blocks) + 1:03d}"
+            if row != expected:
+                raise SystemExit(f"error: expected translation heading {expected}")
+            current = []
+        elif current is not None:
+            current.append(row)
+    if current is not None:
+        blocks.append("\n".join(current).strip())
+    return blocks
+
+
+def cmd_write(args: argparse.Namespace) -> int:
+    authority, data_path = _translation_authority(Path(args.run_manifest))
+    snapshot = _report_snapshot(data_path)
+    data = snapshot.value
+    expected = _source_payload(
+        authority, data_path, snapshot.raw_bytes, data
+    )
+    source_path = translation_source_path(data_path)
+    if source_path.is_symlink():
+        raise SystemExit("error: translation source path is a symlink")
+    source = _load(source_path)
+    _validate_source_payload(source, expected, args.source_digest)
+    sources = expected["strings"]
+    translated = _translation_blocks(Path(args.translations))
+    if len(translated) != len(sources) or any(not value for value in translated):
+        raise SystemExit("error: translation blocks must match every T-NNN item")
+    lang = expected["lang"]
+    sidecar = translation_sidecar_path(data_path, lang)
+    if sidecar.is_symlink():
+        raise SystemExit("error: translation sidecar path is a symlink")
+    strings = dict(zip(sources, translated))
+    _, report = overlay(data, strings)
+    if report.unresolved or report.applied != len(strings):
+        raise SystemExit("error: translations do not validate against report source")
+    write_owned_object_atomic(
+        sidecar,
+        {
+            "taskKey": authority.task_key,
+            "runManifestPath": authority.manifest_ref,
+            "lang": lang,
+            "sourceData": data_path.name,
+            "sourceDataPath": expected["sourceDataPath"],
+            "sourceDataSha256": expected["sourceDataSha256"],
+            "strings": strings,
+        },
+        artifact="report translation sidecar",
+    )
+    print("Translation sidecar\n" + line("Status", "ready"), end="")
+    return 0
+
+
+def cmd_check_data(args: argparse.Namespace) -> int:
+    authority, data_path = _translation_authority(Path(args.run_manifest))
+    snapshot = _report_snapshot(data_path)
+    expected = _source_payload(
+        authority, data_path, snapshot.raw_bytes, snapshot.value
+    )
+    sidecar_path = translation_sidecar_path(data_path, expected["lang"])
+    if sidecar_path.is_symlink():
+        raise SystemExit("error: translation sidecar path is a symlink")
+    sidecar = _load(sidecar_path)
+    _validate_authority_sidecar(sidecar, expected)
+    payload, code = _check_sidecar(sidecar_path)
+    print("Translation check\n" + line("Status", "ready" if payload["ok"] else "error")
+          + line("Applied strings", payload["applied"])
+          + line("Unresolved strings", len(payload["unresolved"])), end="")
+    return code
+
+
+def _validate_authority_sidecar(sidecar: dict, expected: dict) -> None:
+    for key in (
+        "taskKey", "runManifestPath", "lang", "sourceData", "sourceDataPath",
+        "sourceDataSha256",
+    ):
+        if sidecar.get(key) != expected.get(key):
+            raise SystemExit(
+                "error: translation sidecar does not match run authority"
+            )
+
+
 def cmd_check(args: argparse.Namespace) -> int:
     sidecar_file = Path(args.sidecar).resolve()
+    payload, code = _check_sidecar(sidecar_file)
+    print(json.dumps(payload, ensure_ascii=False))
+    return code
+
+
+def _check_sidecar(sidecar_file: Path) -> tuple[dict, int]:
     sidecar = _load(sidecar_file)
     strings = sidecar.get("strings")
     if not isinstance(strings, dict):
@@ -150,7 +324,6 @@ def cmd_check(args: argparse.Namespace) -> int:
         "untranslated": list(report.untranslated),
         "unresolved": list(report.unresolved),
     }
-    print(json.dumps(payload, ensure_ascii=False))
     if report.unresolved:
         # A pointer that resolves nowhere means the sidecar was written against
         # a different report. Rendering it would silently drop those strings.
@@ -158,8 +331,8 @@ def cmd_check(args: argparse.Namespace) -> int:
             f"error: {len(report.unresolved)} pointer(s) do not resolve in "
             f"{data_path.name}\n"
         )
-        return 1
-    return 0
+        return payload, 1
+    return payload, 0
 
 
 def cmd_check_source(args: argparse.Namespace) -> int:
@@ -191,6 +364,20 @@ def _parser() -> argparse.ArgumentParser:
     extract_cmd.add_argument("data", help="path to final-report-<type>-<seq>.data.json")
     extract_cmd.set_defaults(func=cmd_extract)
 
+    source_view = sub.add_parser("source", help="render a fixed translation work list")
+    source_view.add_argument("--run-manifest", required=True)
+    source_view.set_defaults(func=cmd_source)
+
+    write_cmd = sub.add_parser("write", help="publish translations from T-NNN blocks")
+    write_cmd.add_argument("--run-manifest", required=True)
+    write_cmd.add_argument("--source-digest", required=True)
+    write_cmd.add_argument("--translations", required=True)
+    write_cmd.set_defaults(func=cmd_write)
+
+    check_data = sub.add_parser("check-data", help="verify the derived sidecar")
+    check_data.add_argument("--run-manifest", required=True)
+    check_data.set_defaults(func=cmd_check_data)
+
     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)

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

@@ -41,7 +41,7 @@ If `render-bundle` stdout carries an `okstra concurrent-run stages: <stages>` la
 
 If `render-bundle` fails with a `PrepareError` containing `Recorded stage SHAs no longer match the git history`, the git history changed outside okstra (rebase / squash / review-feedback amend / branch deletion). Never fix the registry/consumers by hand; recover in this order:
 
-1. Run the `okstra git-reconcile … --check --json` command printed in the error message verbatim to get the stale report. (Items whose content-identity is proven by patch-id were already auto-reconciled by prepare, so only confirm items remain here.)
+1. Run the `okstra git-reconcile … --check --text` command printed in the error message verbatim to get the stale report. (Items whose content-identity is proven by patch-id were already auto-reconciled by prepare, so only confirm items remain here.)
 2. For each confirm item, present a 3-option picker to the user:
    - **Re-record to the `stage-<N>` branch's current tip (recommended)** — when an intended change such as review feedback lives on that branch.
    - **Enter a different ref directly** — the user names a commit/branch/tag.

package/runtime/prompts/launch.template.md

@@ -49,6 +49,7 @@ For a new `implementation-planning` run, the plan-body sequence is initial verif
 ## Run Paths
 
 - Team state: `{{TEAM_STATE_RELATIVE_PATH}}`
+- Plan-body verification state: `{{PLAN_BODY_VERIFICATION_STATE_RELATIVE_PATH}}`
 - Final report: `{{FINAL_REPORT_RECORD_RELATIVE_PATH}}`
 - Final status: `{{FINAL_STATUS_RELATIVE_PATH}}`
 - Validator: `{{RUN_VALIDATOR_RELATIVE_PATH}}`
@@ -57,12 +58,7 @@ For a new `implementation-planning` run, the plan-body sequence is initial verif
 
 - Run-level errors log (absolute): `{{RUN_ERRORS_LOG_PATH}}`
 - Run-level errors log (relative): `{{RUN_ERRORS_LOG_RELATIVE_PATH}}`
-- Worker error sidecars (absolute):
-  - Claude worker: `{{CLAUDE_WORKER_ERRORS_SIDECAR_PATH}}`
-  - Codex worker: `{{CODEX_WORKER_ERRORS_SIDECAR_PATH}}`
-  - Antigravity worker: `{{ANTIGRAVITY_WORKER_ERRORS_SIDECAR_PATH}}`
-  - Report writer worker: `{{REPORT_WRITER_WORKER_ERRORS_SIDECAR_PATH}}`
-- The paths above are the values; the wiring duties — injecting the `**Errors log path:**` / `**Errors sidecar path:**` header pair into every dispatch prompt, and dumping each terminated worker's sidecar via `okstra error-log append-from-worker` — are defined once in the lifecycle core contract (`{{OKSTRA_LEAD_CONTRACT_PATH}}` "Errors log path wiring (BLOCKING)"). Follow that section; do not re-derive the rules from this block.
+- The lead injects `**Errors log path:**` into every dispatch prompt. Workers use the typed `okstra error-log append-observed` command in the shared worker error contract; runtime-owned sidecar compatibility is not a worker instruction.
 
 ## Executor Worktree
 
@@ -102,19 +98,19 @@ For a new `implementation-planning` run, the plan-body sequence is initial verif
 
 ### Incremental re-verification (implementation-planning clarification re-runs only)
 
-The **default is full re-verification**. Only narrow this re-run to the impacted stages when the deterministic `okstra incremental-scope` CLI returns `mode == "incremental"`; on any doubt, stay full. This procedure fires ONLY when this run's task-type is `implementation-planning` AND a prior final report exists for this task-key (its data.json at `runs/implementation-planning/reports/final-report-implementation-planning-<prev-seq>.data.json`, where `<prev-seq>` is the most recent prior implementation-planning run's seq). For every other task-type, ignore this block and re-verify normally. This branches on the CLI's `mode` output only — it does NOT re-implement the safety logic in the prompt.
+The **default is full re-verification**. Narrow this re-run to the impacted stages only when the deterministic `okstra incremental-scope` CLI returns `mode == "incremental"`. When the wizard pin is `auto` and the CLI returns `mode == "incremental"`, do not upgrade to full — the CLI already applied the base-ref check, the dependency closure, and the cutoff. This procedure fires ONLY when this run's task-type is `implementation-planning` AND a prior final report exists for this task-key (its data.json at `runs/implementation-planning/reports/final-report-implementation-planning-<prev-seq>.data.json`, where `<prev-seq>` is the most recent prior implementation-planning run's seq). For every other task-type, ignore this block and re-verify normally. This branches on the CLI's `mode` output only — it does NOT re-implement the safety logic in the prompt.
 
-0. **Honour the scope the user already pinned (not a judgement — an instruction).** The wizard asks for a re-verification scope whenever this re-run is narrowable, and the answer arrives as two tokens: mode `{{REVERIFY_SCOPE_MODE}}`, stages `{{REVERIFY_SCOPE_STAGES}}`. Apply it before you form your own view:
-   - `auto` — the user left the decision to this procedure. Run steps 1–6 exactly as written; nothing is pinned.
+0. **Honour the scope the user already pinned (not a judgement — an instruction).** The wizard asks for a re-verification scope whenever this re-run is narrowable or an answered id traces to no stage, and the answer arrives as two tokens: mode `{{REVERIFY_SCOPE_MODE}}`, stages `{{REVERIFY_SCOPE_STAGES}}`. Apply it before you form your own view:
+   - `auto` — the user left the decision to this procedure. Run steps 1–7 exactly as written; nothing is pinned. If the CLI returns `mode == "incremental"`, keep it; do not upgrade to full.
    - `full` — the user asked for full re-verification. Still call the CLI once (the record is the audit trail), passing `--full-reason "user requested full re-verification"` and every other CSV empty. Do not argue the user out of it with a narrower `--impacted`: the answer already weighed the cost.
    - `stages` — the user named the stages that must be re-verified. Put **every** number in `{{REVERIFY_SCOPE_STAGES}}` into `--impacted`, unioned with any stage you resolve yourself. Never drop one because your own back-trace did not reach it — the user is telling you about a blast radius the prior report failed to record, which is exactly what the back-trace cannot see. The CLI still applies the dependency closure and the cutoff on top, so a wide enough pin correctly ends in `mode == "full"`.
 1. **List the answered clarifications (a fact, not a judgement).** Collect the `C-NNN` ids you reconciled as answered in §1, and the IDs of any PREP items changed by the carried response. Pass the ids through `--answered-clarifications`; the CLI resolves which Stage Map stages each one touches by reading the prior run's own links — the `P-*` plan item that carried that `clarificationId`, and the requirement-coverage row blocked on `C-NNN` in either its `status` or its `approvalDisposition` (a `documented-deviation` row records the block in the latter). Do NOT map answers to stage numbers yourself.
-   - An id that traces to no stage in the prior report makes the CLI return `mode == "full"` for the whole re-run. That is the intended outcome: an answer whose blast radius the prior report never recorded must not narrow anything.
-   - **Structural change is your call, and you declare it.** When an answer overturns the selected Option, restructures the stages, or changes the recommended approach, pass `--full-reason "<what changes and how>"`. It forces `mode == "full"` regardless of every other input — the back-trace resolves stages, it cannot judge whether the plan's shape survived. Do NOT express this by leaving the CSVs empty: that produces the same `no impacted stages resolved` reason as a re-run that simply failed to map anything, and the two become indistinguishable in the record. `--impacted` remains available for stage numbers you resolved yourself.
+   - An id that traces to no stage in the prior report does **not** force `mode == "full"` for the whole re-run. The CLI returns `mode == "unresolved"` and names the ids. Ask the user for the stage numbers those answers affect, then call the CLI again with those numbers in `--impacted`. Do not drop the unlinked id from `--answered-clarifications`. Do not treat `unresolved` as full, and do not silently narrow to the ids that did trace. An approval blocker in this shape should have failed the prior report's back-trace; naming stages is the remaining outlet.
+   - **Structural change is your call, and you declare it.** When an answer overturns the selected Option, restructures the stages, or changes the recommended approach, pass `--full-reason "<what changes and how>"`. It forces `mode == "full"` regardless of every other input — the back-trace resolves stages, it cannot judge whether the plan's shape survived. Do NOT express this by leaving the CSVs empty. `--impacted` remains available for stage numbers you resolved yourself. `--full-reason` is the only structural path that still forces full.
    - Pass ONLY stage numbers that appear in that Stage Map when you do use `--impacted`. Never invent or guess a stage number — a number absent from the graph must never enter `--impacted` (it would leak into `reverify_stages`).
 2. **Resolve the two base SHAs (safety condition C1 — code-unchanged, decided by the CLI, not by you).**
    - Current base SHA: `{{EXECUTOR_WORKTREE_BASE_REF}}` (this run's resolved worktree base commit).
-   - Prior base SHA: read the prior run's active-run-context at `runs/implementation-planning/state/active-run-context-implementation-planning-<prev-seq>.json`, field `executorWorktree.baseRef` (a resolved commit SHA). The run-manifest does NOT carry this field — use the active-run-context. If that file or field cannot be located, treat the run as **full** and skip the rest of this procedure.
+   - Prior base SHA: run `okstra model-io active-context-input --project-root <project-root> --run-manifest <run-manifest>` and use its fixed `Executor base ref` field. Python resolves the prior active context only when it belongs to this project and run. If the command fails or the field is empty, treat the run as **full** and skip the rest of this procedure.
 3. **Call the CLI** (it is pure — same inputs always yield the same decision):
    ```
    okstra incremental-scope \
@@ -128,8 +124,9 @@ The **default is full re-verification**. Only narrow this re-run to the impacted
    ```
    The CLI reads the plan's dependency graph from the prior `implementationPlanning.stageMap`, which is authoritative for the impacted stage numbers. The CLI prints JSON `{mode, reverify_stages, carry_stages, reason}`. Instruct the report writer to record this decision in its narrative as `implementationPlanning.incrementalDecision`, using camel-case array keys `reverifyStages` and `carryStages`. Final report assembly preserves that writer-owned decision.
 4. **`mode == "full"`** → run the existing full re-verification path unchanged; ignore `reverify_stages` / `carry_stages`.
-5. **`mode == "incremental"`** → scope every worker dispatch prompt to `reverify_stages` only (the downstream closure of the impacted stages). Do NOT re-analyze `carry_stages` — their prior plan-item verdicts are carried forward verbatim (see `prompts/profiles/implementation-planning.md` "Cross-verification mode" and `prompts/lead/convergence.md` "Convergence scope").
-6. **Merge carried-forward verdicts.** In `incremental` mode, the report writer includes every `carry_stages` stage row unchanged in its narrative. After `okstra plan-items seed --narrative ... --state ...`, the lead runs:
+5. **`mode == "incremental"`** → scope every worker dispatch prompt to `reverify_stages` only (the downstream closure of the impacted stages). Do NOT re-analyze `carry_stages` — their prior plan-item verdicts are carried forward verbatim (see `prompts/profiles/implementation-planning.md` "Cross-verification mode" and `prompts/lead/convergence.md` "Convergence scope"). When the pin in step 0 was `auto`, this is the decision — do not upgrade it to full.
+6. **`mode == "unresolved"`** → ask the user for stage numbers; re-enter step 3 with those numbers in `--impacted`. Do not fall back to full. Do not record `unresolved` as `incrementalDecision`. Then continue from the new `mode`.
+7. **Merge carried-forward verdicts.** In `incremental` mode, the report writer includes every `carry_stages` stage row unchanged in its narrative. After `okstra plan-items seed --narrative ... --state ...`, the lead runs:
    ```
    okstra incremental-carry \
      --prev-data runs/implementation-planning/reports/final-report-implementation-planning-<prev-seq>.data.json \

package/runtime/prompts/lead/context-loader.md

@@ -2,154 +2,54 @@
 
 ## When to Use
 
-- When starting okstra lead Phase 1 (Task-bundle intake)
-- When the user needs to know the okstra task bundle path
-- When you need to derive all artifact paths based on `task-manifest.json`
-
-## Step 1: Resolve the Task Bundle Path
-
-(Resolve which task-root path to use; Step 2 opens `task-manifest.json` at that path.)
-
-### Default Location Rules
-
-- AI documentation root: `.project-docs/`
-- Project-level latest-task pointer: `.okstra/discovery/latest-task.json`
-- Project-level task catalog: `.okstra/discovery/task-catalog.json`
-- okstra task root: `.okstra/tasks/`
-- Task path pattern: `.okstra/tasks/<task-group>/<task-id>/`
-
-### Task Identification
-1. If the user specifies the `task-manifest.json` path or the task root path, that path is used.
-2. If the user specifies only the task key, the expected task root is calculated by converting the `task-group` and `task-id` to lowercase and applying the slug rule (`[^a-z0-9]+` → `-`), and the corresponding `task-manifest.json` is opened.
-3. If the user attempts to find a task based on `task-group` + `task-id` or `task-id`, `.okstra/discovery/task-catalog.json` is read to find candidates.
-4. If multiple candidates are found based on `task-id` alone, the situation is ambiguous, so `task-group` or the full `taskKey` is required.
-5. If the user has not provided an explicit task key/path, first read `.okstra/discovery/latest-task.json` using the current-task convenience pointer.
-6. If the latest-task pointer is missing or corrupted but the task catalog exists, list candidates from the catalog. Do not use the legacy `CLAUDE.md`, project guide, or task scan fallback.
-7. If **neither** `latest-task.json` **nor** `task-catalog.json` exists, ABORT Phase 1 with `OKSTRA_CONTEXT_NOT_INITIALIZED`. Suggest the user run `/okstra-setup` and `/okstra-brief-gen` to bootstrap the project. Do NOT crawl `.okstra/tasks/` directly — discovery pointers are the only supported entry path.
-
-## Step 2: Open and Parse task-manifest.json
-
-`task-manifest.json` (found at the task-root resolved in Step 1) is the canonical metadata source. Extract the following fields:
-
-| Field | Description |
-|------|------|
-| `taskKey` | `<project-id>:<task-group>:<task-id>` |
-| `projectId` | Project ID |
-| `taskGroup` | Task group |
-| `taskId` | Task ID |
-| `taskType` | Analysis type (requirements-discovery, error-analysis, implementation-option-selection, implementation-planning, implementation, final-verification, release-handoff, plus the sidetrack improvement-discovery) |
-| `workCategory` | bugfix / feature / improvement / refactor / ops / unknown |
-| `recommendedWorkers` | List of selected workers |
-| `currentStatus` | Current task status |
-| `workflow.phaseSequence` | Ordered lifecycle phases for the task |
-| `workflow.currentPhase` | Current lifecycle phase |
-| `workflow.currentPhaseState` | Current lifecycle phase state |
-| `workflow.phaseStates` | Phase-by-phase lifecycle state map |
-| `workflow.lastCompletedPhase` | Last completed lifecycle phase |
-| `workflow.nextRecommendedPhase` | Next-Phase Pointer — an object carrying the target phase, whether it can be started, and why. A projection of this report's Phase Routing; not authored here. Written per the Artifact Persistence Checklist in [report-writer](./report-writer.md); do not re-derive its rules here. |
-| `workflow.awaitingApproval` | Approval wait marker |
-| `workflow.lastSafeCheckpoint` | Safe resume checkpoint metadata |
-| `instructionSetPath` | Path to the `instruction-set/` **directory** containing `analysis-packet.md`, `analysis-profile.md`, `analysis-material.md`, `reference-expectations.md`, `task-brief.md`, `final-report-template.md`, and — only for task types whose host orchestration carries gates — `host-orchestration-rules.md` (see Step 4). Not a single-file path. |
-| `referenceExpectationsPath` | config/deployment expectation artifact path |
-| `latestRunPath` | latest run path |
-| `latestRunStatus` | latest run status |
-| `latestRunPromptsPath` | latest run prompt directory path |
-| `latestReportRecordPath` | latest report path |
-| `latestResumeCommandPath` | resume helper path |
-| `historyTimelinePath` | timeline path |
-| `resultContract` | team contract and expected artifact metadata |
-| `resultContract.requiredWorkerRoles[*].promptPath` | worker prompt history path by role |
-| `convergence` | convergence loop settings (`enabled`, `maxRounds`, `verificationMode`). See [convergence](./convergence.md) for the authoritative defaults — do not re-document the `maxRounds` value here. |
-
-## Step 3: Directory Structure Rules
-
-After identifying the task root in `task-manifest.json`, derive all paths according to the following rules:
-
-```
-<task-root>/
-├── task-manifest.json          (canonical metadata)
-├── task-index.md               (human-readable summary, non-canonical)
-├── instruction-set/
-│   ├── analysis-profile.md     (analysis guide by task type)
-│   ├── analysis-packet.md      (primary compact input for analysis workers)
-│   ├── analysis-material.md    (analysis materials)
-│   ├── reference-expectations.md (config/deployment expected values)
-│   ├── task-brief.md          (task brief)
-│   ├── final-report-template.md (Final Report Template)
-│   └── host-orchestration-rules.md (host gate rules; present only for task types whose host orchestration carries gates)
-├── runs/
-│   └── <task-type>/            (Run scope isolated per task-type, e.g. error-analysis)
-│       ├── manifests/          (run-manifest-<task-type>-<seq>.json)
-│       ├── state/              (team-state-<task-type>-<seq>.json, convergence-<task-type>-<seq>.json)
-│       ├── prompts/            (run prompt path and worker prompt history paths recorded in the manifest)
-│       ├── reports/            (final-report-<task-type>-<seq>.data.json + .html;
-│                                the .md reading copy is rendered on demand)
-│       ├── status/             (final-<task-type>-<seq>.status)
-│       ├── sessions/           (runtime-specific resume artifacts when the selected adapter supports them)
-│       ├── logs/               (errors-<task-type>-<seq>.jsonl, optional)
-│       └── worker-results/
-│           ├── claude-worker-<task-type>-<seq>.md
-│           ├── codex-worker-<task-type>-<seq>.md
-│           ├── antigravity-worker-<task-type>-<seq>.md
-│           └── report-writer-worker-<task-type>-<seq>.md
-└── history/
-    └── timeline.json
-```
-
-### File Naming Conventions
-
-- Run-level artifact files use the `-<task-type>-<seq>` suffix, where `<seq>` is a 3-digit zero-padded sequence number (`001`, `002`, …) scanned **per-category directory** (`manifests/`, `prompts/`, `reports/`, `status/`, `state/`, `sessions/`, `worker-results/`). Re-runs of the same task-type never overwrite each other's artifacts.
-- Because each category directory has its own counter, the `<seq>` for `manifests/` may differ from the `<seq>` for `reports/` if a previous run only wrote some categories. The shared run identifier across categories is the manifest `runDateTimeSegment` field (still ISO timestamp), not a filename infix.
-- Worker result files use the same `-<task-type>-<seq>` filename suffix as other run-level artifacts (counter scoped to `worker-results/`).
-- Worker prompt history files use role + suffix names such as `claude-worker-prompt-<task-type>-<seq>.md`.
-- A single `runs/<task-type>/` directory is reused for every run of that task type; the per-run separation comes entirely from the per-category sequence-number infix inside each typed subdirectory.
-
-### Finding the Latest Run
-
-1. If a `latest-task` pointer exists, prioritize the path to the latest run, latest run manifest, or latest team-state recorded there.
-2. If entering via an explicit task key/path, locate the current run based on the latest run metadata in `task-manifest.json`.
-3. Only if necessary, directly check `manifests/`, `state/`, `prompts/`, `reports/`, and `sessions/` within the relevant run directory.
-
-## Step 4: Instruction Set Reading Order
-
-After verifying `task-manifest.json`, read only the compact intake files needed for the current action. Do not bulk-read the whole instruction-set directory.
-
-1. `instruction-set/analysis-profile.md` (analysis guide by task type)
-2. `instruction-set/analysis-packet.md` (primary compact input for analysis workers)
-3. `runs/<task-type>/state/active-run-context-<task-type>-<seq>.json` if present (compact current-run path/worker snapshot)
-4. `instruction-set/host-orchestration-rules.md` when the launch prompt's Host Orchestration Rules path is set. Read it here even though no gate has fired yet — the gates it governs fire around `render-bundle`, so waiting for one means reading it too late, and this is the copy that survives compaction. **Enforced:** Phase 7 conformance fails an `implementation` run whose evidence source records no read of it.
-
-Read source files lazily:
-
-- `instruction-set/task-brief.md` only for reporter-confirmation checks, source verification, or report-writer synthesis.
-- `instruction-set/analysis-material.md` only when packet content is insufficient or a source citation needs verification.
-- `instruction-set/reference-expectations.md` for report-writer synthesis or when packet expectation extract is insufficient.
-- `instruction-set/final-report-template.md` only for report-writer authoring.
-- `instruction-set/host-orchestration-rules.md` — already read at Step 4; re-read it whenever you are about to act on a host gate — the conformance waiver offer, the concurrent-run branch, stale-SHA recovery, the chaining queue — and again after any compaction. Absent file means this task type carries no host gates.
+- When starting okstra lead Phase 1 task-bundle intake.
+- When the user needs the task bundle or current run paths.
+
+## JSON Boundary
+
+Do not open, parse, or infer Okstra-owned task, run, discovery, or active-context JSON. This contract uses the fixed text views below before the lead contract is loaded, so it cannot bypass that boundary.
+
+- `okstra model-io project-context --project-root <project-root> --task-ref <task-ref>` provides project identity and the pointer for one explicit task reference. `task-ref` accepts a bare task ID, full task key, or that task's manifest path.
+- `okstra model-io run-input --run-manifest <run-manifest-path>` provides the current run identity, worker roster, model assignments, and permitted artifact paths.
+
+## Step 1: Resolve the Task and Run Paths
+
+1. Determine `<project-root>` from the user request or the current project.
+2. If the user supplies a task ID, full task key, or task-manifest path, run `okstra model-io project-context --project-root <project-root> --task-ref <task-ref>`. Otherwise run `okstra model-io project-context --project-root <project-root>`.
+3. If the supplied bare task ID is ambiguous, require the full task key or task-manifest path.
+4. Use the `Task key`, `Task manifest`, and `Latest run manifest` labels from the same Project Context result.
+5. Use `Latest run manifest` as `<run-manifest-path>`. If it is `-`, request an explicit run-manifest path from the launch context or stop with `OKSTRA_CONTEXT_NOT_INITIALIZED`. Do not scan task directories or reconstruct a run path.
+6. Run `okstra model-io run-input --run-manifest <run-manifest-path>`.
+
+## Step 2: Read the Compact Intake Files
+
+Use the `Instruction set` and `Reference expectations` labels in Run Input as paths for Markdown resources. Read only the resources needed for the current action.
+
+1. `<instruction-set>/analysis-profile.md` for the task-type rules and required worker block.
+2. `<instruction-set>/analysis-packet.md` for the Phase 1 compact input.
+3. `<instruction-set>/host-orchestration-rules.md` when the launch prompt supplies that path.
+
+Read `task-brief.md`, `analysis-material.md`, `reference-expectations.md`, and `final-report-template.md` only at their phase-specific need. The report writer owns the final-report template.
 
 ### Brief Reporter-Confirmation Precondition (BLOCKING)
 
-After reading `task-brief.md`, extract the frontmatter `reporter-confirmations` field (`complete | partial | pending | skipped`) when present and apply the shared handling matrix in `prompts/profiles/_common-contract.md` "Brief handoff contract" → "Reporter confirmation precondition" — that block is the single authority on per-value semantics; do not re-derive them here.
+After reading `task-brief.md`, extract the frontmatter `reporter-confirmations` field when present and apply the shared handling matrix in `prompts/profiles/_common-contract.md` "Brief handoff contract" → "Reporter confirmation precondition". That block is the authority for the value semantics.
 
-Loader-level defensive flow control only: on `pending`, emit `REPORTER_CONFIRMATION_PENDING` and STOP — do not invoke `team-contract` or any analyser, and do not write a final report. Regenerate the brief with `okstra-brief-gen` Step 6.5 and prepare a fresh run. A missing field is a legacy brief, not `pending`, and proceeds to Step 5. Current-format missing or invalid values are rejected during preparation, before a fresh run can reach this loader. Every other value proceeds to Step 5 with the matrix's flags carried forward for the phase profile.
+On `pending`, emit `REPORTER_CONFIRMATION_PENDING` and stop. Do not invoke `team-contract` or an analyser, and do not write a final report. Regenerate the brief with `okstra-brief-gen` Step 6.5 and prepare a fresh run. A missing field is a legacy brief and proceeds with the matrix's carried flags. Current-format invalid values are rejected during preparation.
 
-## Step 5: Read Run Manifest and Team State
+## Step 3: Use Run Input as the Run-State View
 
-1. Identify the active run by reading `runDateTimeSegment` from the latest `runs/<task-type>/manifests/run-manifest-*.json` (mtime order). That segment is the shared run identifier across all category subdirectories (`state/`, `prompts/`, `reports/`, `status/`, `sessions/`, `worker-results/`).
-2. Resolve sibling artifacts for this run by matching the same `runDateTimeSegment`. Do NOT re-scan `<seq>` counters per category — they may diverge if an earlier run only wrote some categories.
-3. Current team state: the team-state file whose `runDateTimeSegment` matches the active run manifest.
-4. Extract the worker prompt directory path and per-worker prompt history paths from the current run manifest and team-state.
-5. If an existing run report is available, use it solely as historical context.
+Run Input is the only Phase 1 source for task identity, work category, workflow state, selected workers, model assignments, worker prompt paths, result paths, validator path, resume command, and configuration references.
+
+Use the `Worker Roster` section for dispatch and model assignment. Use `Artifact Paths` for prompt, result, report, status, validator, and resume locations. Use `Configuration References` for the task-level Markdown resources. Do not derive sibling paths from file names or sequence counters.
+
+Use the `Current phase` labels as the workflow view. Rules for `nextRecommendedPhase` are maintained by [report-writer](./report-writer.md); do not re-derive phase routing here.
 
 ## Output
 
 Information produced after completing this contract:
-- task key, task type, work category, workflow lifecycle snapshot, analysis profile
-- List of selected workers and model assignments by role
-- Absolute/relative paths of all artifacts (including latest-task pointer, task catalog, prompt directory, per-worker prompt history files, resume command, and timeline)
-- Reference list of config files/deployment manifests and task-level expected values
-- Current run status and presence of existing worker results
-- Current run prompt history contract for attempted workers
-- Candidate `teamName` for the manifest/team-state audit identity: `okstra-<task-key>` (with task-key slugified per Step 1's slug rule); implementation stage runs append `-s<N>`. The selected runtime adapter owns whether an adapter-specific audit label is exposed in the launch prompt's "Runtime Adapter Dispatch Gate (BLOCKING)" setup facts; this common contract does not guarantee that label for every runtime.
-- Current lead session/checkpoint identity, when supplied by the selected adapter
-- Resume artifact path from `task-manifest.json.artifacts.resumeCommandPath`; never reconstruct a runtime-specific filename
+
+- Project ID, task key, task type, work category, and workflow snapshot.
+- Selected workers and assigned models.
+- Prompt, result, report, status, validator, resume, and configuration-reference paths.
+- The compact Markdown intake paths required for Phase 1.