okstra 0.180.0 → 0.183.2

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
 
@@ -114,7 +110,7 @@ The **default is full re-verification**. Only narrow this re-run to the impacted
    - 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 \

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.

package/runtime/prompts/lead/convergence.md

@@ -84,7 +84,9 @@ Read the worker result files generated in Phase 4/5 and extract individual findi
   - Same semantics but disjoint ticket sets → separate groups (do NOT over-merge across tickets).
   - Only one worker confirms a finding → one single-source group.
 4. When grouping is ambiguous, prefer splitting over merging (avoid over-merging). Semantic matching, ticket-set equality, and evidence interpretation remain lead judgments; the engine does not perform fuzzy matching or decide whether evidence is credible.
-5. Write `runs/<task-type>/state/convergence-groups-<task-type>-<seq>.json`. Each group carries its `ticketIds`, `originWorker`, `originEvidence`, `discoveredBy`, and every `<worker>:<item-id>` source in `sourceItems`. For analysis sidetracks where ticket tagging is not required, `ticketIds: []` is the canonical value; never synthesize `"unknown"` or another placeholder. `scripts/okstra_ctl/convergence_engine.py` and the version-selected convergence-groups schema enforce the required array field and reject non-string or blank entries while allowing the empty array. When a live command or external read produced reproducible evidence, also include `evidenceArtifacts[]` with its `.okstra/` path, SHA-256 digest, command, and environment. The field is optional because historical or inaccessible evidence may not have a captured artifact. The lead and verifier MUST NOT infer live or external evidence from wording or keyword matching; they use the finding's explicit claim, provenance, and supplied artifacts. Include the resolved worker roster in order with functional `audience` values; do not derive scope from provider or model identity. In a v2 run, set top-level `schemaVersion: "2.0"`, `executionIdentityVersion: 2`, and `runManifestPath` to the current run manifest's exact canonical project-relative path. Write the groups artifact under that same resolved run directory's `state/` directory. Every v2 worker row also carries the paired `participantRef` and `sourceRoleExecutionRef` from that run manifest's canonical role state. Set `sourceRoleExecutionRef` to the selected source `RoleExecution` row's `roleExecutionRef`, not that row's `sourceRoleExecutionRef` field; a static source row has null in the latter field. Copy `participantRef` from that same selected row. Never derive those references from the worker name, provider, model, or execution label. A legacy v1 document keeps `schemaVersion: "1.0"` and omits `executionIdentityVersion`, `runManifestPath`, and both worker reference fields. The `audience` enum is a convergence role, not a phase label: every finding-producing worker uses `analysis` and selects an `analyser`, `designer`, `planner`, or `verifier` source role. Only the report author uses `report-writer`, paired with a `report-writer` source role. There is no `implementation-verifier` audience here; map an implementation verifier to `analysis`. **Your own review findings use `audience: "lead"`.** The phases that ask you to review the deliverable yourself produce findings that belong in this state — it is what the report author reads — and declaring yourself an analysis worker to get them in is forbidden. A `lead` row is a source, never a vote: `originWorker`, `discoveredBy` and `sourceItems` accept it, and the consensus count ignores it, so a finding only you saw stays queued for verification instead of resolving itself.
+5. Author the fixed grouping Markdown accepted by `okstra convergence prepare-groups --run-manifest <run-manifest> --input <grouping.md>`, then run that command. Python owns the artifact identifier, target path, schema version, task identity, run-manifest reference, and every participant reference. Each Markdown group records ticket IDs, origin worker and evidence, discovering workers, source worker item IDs, and optional captured evidence. An analysis sidetrack with no ticket uses an empty `Tickets:` value, never a placeholder. Use the ordered functional roster: finding workers have the `analysis` audience, the report author has `report-writer`, and the lead uses `lead`. A lead source never votes. Never infer live evidence or functional scope from wording, provider, model, or execution label.
+
+   The command sets each worker's paired `participantRef` and `sourceRoleExecutionRef` from the run manifest's canonical role state. It sets `sourceRoleExecutionRef` to the selected source `RoleExecution` row's `roleExecutionRef`, not that row's `sourceRoleExecutionRef` field.
 6. Do not write a queue or classification in this grouped-input artifact. `okstra convergence seed` classifies Round 0 by mode:
    - Collaborative mode: multi-source groups become `full-consensus` immediately; only single-source groups enter the working queue.
    - Adversarial mode: every finding enters the working queue regardless of source count. Semantic grouping merges provenance only; it does not decide a finding is reliable.
@@ -254,7 +256,7 @@ row names the invocation, replacement is rejected even for v1 and the prompt is
 history. Do not delete prompt, metadata, or reservation files by hand.
 
 Run `okstra agent-prompt verify --run-manifest <path> --metadata
-<metadataPath> --json` immediately before dispatch. A failed verification is a
+<metadataPath> --text` immediately before dispatch. A failed verification is a
 pre-dispatch contract failure. For `runner=native-session`, pass only the
 returned `hostModelValue` to the host model argument. For
 `runner=cli-wrapper`, follow the planned execution surface after
@@ -298,9 +300,9 @@ Assigned worker prompt history path: <Project Root>/<Prompt History Path>
 
 Before dispatch, materialize `**Audit sidecar path:**` by passing the exact reverify `**Result Path:**` through `okstra_ctl.worker_artifact_paths.audit_sidecar_rel()` and resolving that project-relative result against `**Project Root:**`. Write the resulting absolute path into the header. The lead MUST NOT construct the audit filename from a role, task type, round, or sequence independently.
 
-The two errors paths carry the same absolute values the lead forwarded in the initial Phase 4 dispatch for that role (source: the launch prompt's `## Run Logs (error-log wiring)` section). Omitting either one makes `worker-dispatch` reject the CLI invocation before it starts the provider process — the path-delivery contract in [team-contract](./team-contract.md) "Error reporting" is not relaxed for reverify.
+The two error-path anchors carry the same absolute values the lead forwarded in the initial Phase 4 dispatch for that role (source: the launch prompt's `## Run Logs (error-log wiring)` section). Workers use the errors log path with the typed error-log command from [team-contract](./team-contract.md) "Error reporting". The errors sidecar path only reserves the runtime-owned write-artifact path used by dispatch validation; no model-authored error JSON file is part of reverify.
 
-Relative to the Phase 4 anchor set rendered by `okstra_ctl.worker_prompt_headers.worker_prompt_headers()`, a reverify prompt drops two anchors whose targets lightweight mode never reads: `**Worker Preamble Path:**` and `**Coding preflight pack:**`.
+Relative to the Phase 4 anchor set rendered by `okstra_ctl.worker_prompt_headers.worker_prompt_headers()`, a reverify prompt drops two anchors whose targets lightweight mode never reads: `**Worker Preamble Path:**` and `**Worker Error Contract Path:**`.
 
 **Where the composer's sections go.** `okstra agent-prompt materialize` (§"Invocation materialization gate") writes the dispatched body itself, as: these anchors, then the model-assignment block it appends (`**Provider:**`, `**Model:**`, `**Model execution value:**`, `**Runner:**`, `**Host runtime:**`, and `**Host model value:**` for a native host), then `## Duty Contract`, then `## Task Instructions` followed verbatim by the task-instructions file the lead wrote. So the lead authors only the last part, and every rule below about ordering — the phase boundary before the instruction headings, the `**Model:** <role>, <modelExecutionValue>` line — is about the lead's own file, not about the composed document. The composer's `**Model:** <modelExecutionValue>` anchor is a different line with a different shape; do not try to reshape it, and do not count it among the 8.
 
@@ -687,7 +689,7 @@ say so explicitly for that half; silence on one half is an incomplete result.
 ```
 
 ### Gap verification (1 adversarial reverify round)
-Each critic gap enters the verification queue as a finding with `originWorker = "<provider>-critic"` and `source = "critic"`. The lead runs ONE adversarial reverify round (§"Adversarial Verification Mode" classifier) with the Phase 4 analysers as voters, **excluding every analyser whose provider is the critic's provider** — the exclusion matches on the provider name (`codex`, `codex-worker`), not on the critic's worker id, so picking a critic provider that is already in the analyser roster removes that analyser from the vote and shrinks the quorum by one. `okstra apply-critic-gaps` refuses a vote from an excluded worker (`critic voter must be a non-critic analyser`), so dispatching one spends a worker whose verdict cannot be counted. Only gaps classified `full-consensus` / `partial-consensus` merge into the final report findings; `contested` / `worker-unique` gaps are treated as hallucinations and dropped (recorded in the convergence state, not promoted).
+Each critic gap enters the verification queue as a finding with `originWorker = "<provider>-critic"` and `source = "critic"`. The lead runs ONE adversarial reverify round (§"Adversarial Verification Mode" classifier) with **every Phase 4 analyser as a voter**. Choosing a critic provider that is already in the analyser roster costs nothing: the critic is a different role contract, a different duty and a different session, so an analyser is not disqualified by sharing its provider name (ADR-0017 — provider and model are not role identity, and the same model assigned to two roles gets two independent workers). The critic cannot judge its own gaps because it is not an analyser: the voter roster is `workers[]` filtered to `audience == "analysis"`, and a critic is not even representable there (the allowed values are `analysis` / `lead` / `report-writer`). `okstra apply-critic-gaps` refuses a vote from anyone outside that roster (`critic voter must be a non-critic analyser`). Only gaps classified `full-consensus` / `partial-consensus` merge into the final report findings; `contested` / `worker-unique` gaps are treated as hallucinations and dropped (recorded in the convergence state, not promoted).
 
 **A gap that received no verdict is NOT a rejected gap (BLOCKING).** Dropping applies only to gaps the voters actually judged. A gap can also end the round *unjudged* — the verification dispatch returned a terminal non-result (`timeout`, `error`, no result file), the returned result covered only some of the gaps, or no non-critic analyser was available to vote at all. Nobody inspected those, so classifying them as hallucinations is a fabricated verdict. Each one MUST be recorded as a `## 5. Missing Information and Risks` row (`missingInformation`, `source: "critic-unverified"`) whose `risk` names the gap and the reason verification did not complete, and counted in `config.critic.gapsUnverified`. They are **not** promoted to findings (unverified) and **not** raised as `clarification` items — an unverified gap needs an analyser to verify it on the next run, not a decision from the user. Silently losing them is a contract violation: the batch that times out is exactly the batch of gaps too expensive to check, so the highest-risk items are the ones that vanish.
 
@@ -738,7 +740,7 @@ so explicitly.
 
 ### Verification — confirm-or-downgrade (BLOCKING)
 
-Each candidate blocker is verified by the Phase 4 analysers, excluding every analyser whose provider is the critic's provider (same rule as §"critic gaps" above). Do NOT use the adversarial finding classifier's "uncertain → reject" rule here.
+Each candidate blocker is verified by the Phase 4 analysers — all of them, on the same roster rule as §"critic gaps" above; sharing the critic's provider name does not disqualify an analyser. Do NOT use the adversarial finding classifier's "uncertain → reject" rule here.
 - Do NOT run `apply-critic-gaps` for this mode. That reducer implements coverage merge/drop semantics and rejects `acceptance-devils-advocate` input.
 - **Confirmed** (an analyser reproduces it or cites supporting evidence) → promote to a `## 5.8 Acceptance Blockers` row (keep severity + recommended follow-up phase).
 - **Not confirmed** (cannot reproduce, or evidence is weak) → **downgrade to a Residual Risk row — never drop it.** Record the escalation trigger so the user can re-judge a high-severity-but-unconfirmed candidate.