okstra 0.159.0 → 0.160.0

package/runtime/python/okstra_ctl/plan_items_cli.py

@@ -1,4 +1,9 @@
-"""CLI adapter for deterministic implementation-planning item extraction."""
+"""CLI adapter for deterministic implementation-planning item extraction.
+
+`extract` / `validate` own the `P-*` queue; `collect-verdicts` / `apply-verdicts`
+own the round's votes on that queue. Both halves exist so the round's fidelity
+does not depend on a parser the lead re-writes each time.
+"""
 from __future__ import annotations
 
 import argparse
@@ -10,6 +15,7 @@ from typing import Any
 
 from .convergence_store import write_json_atomic
 from .plan_items import PlanItemContractError, extract_plan_items
+from .verdict_blocks import VerdictBlock, VerdictBlockError, parse_verdict_blocks
 
 
 def _load_json_object(path: Path) -> dict[str, Any]:
@@ -49,6 +55,21 @@ def _parser() -> argparse.ArgumentParser:
     validate = commands.add_parser("validate")
     validate.add_argument("--data", type=Path, required=True)
     validate.add_argument("--items", type=Path, required=True)
+    collect = commands.add_parser(
+        "collect-verdicts",
+        help="read this round's worker responses into a verdicts envelope",
+    )
+    collect.add_argument("--result", action="append", default=[], required=True,
+                         metavar="<worker-id>=<path>",
+                         help="one worker's plan-verify result file (repeatable)")
+    collect.add_argument("--items", type=Path, required=True)
+    collect.add_argument("--output", type=Path, required=True)
+    apply_verdicts = commands.add_parser(
+        "apply-verdicts",
+        help="overwrite planBodyVerification.planItems[].verdicts in data.json",
+    )
+    apply_verdicts.add_argument("--data", type=Path, required=True)
+    apply_verdicts.add_argument("--verdicts", type=Path, required=True)
     return parser
 
 
@@ -66,11 +87,154 @@ def _validate(args: argparse.Namespace) -> dict[str, Any]:
     return {"ok": True, "operation": "validate", "path": str(args.items)}
 
 
+def _split_result_arg(raw: str) -> tuple[str, Path]:
+    worker, separator, path = raw.partition("=")
+    if not separator or not worker.strip() or not path.strip():
+        raise PlanItemContractError(
+            f"--result must be <worker-id>=<path>, got: {raw}"
+        )
+    return worker.strip(), Path(path.strip())
+
+
+def _assigned_item_ids(items_path: Path) -> list[str]:
+    envelope = _load_json_object(items_path)
+    items = envelope.get("items")
+    if not isinstance(items, list):
+        raise PlanItemContractError(f"items envelope has no `items` array: {items_path}")
+    ids: list[str] = []
+    for item in items:
+        item_id = item.get("id") if isinstance(item, Mapping) else None
+        if not isinstance(item_id, str) or not item_id:
+            raise PlanItemContractError(f"every item needs an `id`: {items_path}")
+        ids.append(item_id)
+    return ids
+
+
+def _verdict_row(worker: str, block: VerdictBlock) -> dict[str, Any]:
+    """One `planItems[].verdicts[]` row. Optional fields stay absent when empty
+    so the recorded table shows what the worker actually said."""
+    row: dict[str, Any] = {"worker": worker, "verdict": block.verdict}
+    for key, value in (
+        ("breakageKind", block.breakage_kind),
+        ("fixability", block.fixability),
+        ("note", block.note),
+        ("priorDissent", block.prior_dissent),
+    ):
+        if value:
+            row[key] = value
+    return row
+
+
+def _worker_blocks(
+    raw_results: list[str], assigned: set[str]
+) -> list[tuple[str, dict[str, VerdictBlock]]]:
+    """Each worker's parsed response, refusing any queue mismatch.
+
+    A missing vote and an invented item are both silent in a hand-written
+    parser; each is a round scored on a table that does not match the queue.
+    """
+    collected: list[tuple[str, dict[str, VerdictBlock]]] = []
+    for raw in raw_results:
+        worker, path = _split_result_arg(raw)
+        try:
+            blocks = parse_verdict_blocks(path.read_text(encoding="utf-8"))
+        except (OSError, UnicodeError) as exc:
+            raise PlanItemContractError(f"cannot read result {path}: {exc}") from exc
+        answered = set(blocks)
+        missing = sorted(assigned - answered)
+        if missing:
+            raise PlanItemContractError(
+                f"worker `{worker}` was assigned {len(assigned)} items but "
+                f"returned no verdict for {missing} — an unanswered item cannot "
+                f"be scored, and dropping it silently is what makes a round look "
+                f"complete when it is not"
+            )
+        unknown = sorted(answered - assigned)
+        if unknown:
+            raise PlanItemContractError(
+                f"worker `{worker}` returned verdicts for {unknown}, which are "
+                f"not in the persisted plan-item queue"
+            )
+        collected.append((worker, blocks))
+    return collected
+
+
+def _collect_verdicts(args: argparse.Namespace) -> dict[str, Any]:
+    assigned = _assigned_item_ids(args.items)
+    collected = _worker_blocks(args.result, set(assigned))
+    envelope = {
+        "schemaVersion": "1.0",
+        "taskType": "implementation-planning",
+        "planItems": [
+            {
+                "id": item_id,
+                "verdicts": [
+                    _verdict_row(worker, blocks[item_id])
+                    for worker, blocks in collected
+                ],
+            }
+            for item_id in assigned
+        ],
+    }
+    write_json_atomic(args.output, envelope)
+    return {"ok": True, "operation": "collect-verdicts", "path": str(args.output)}
+
+
+def _plan_body_items(data: dict[str, Any], data_path: Path) -> list[dict[str, Any]]:
+    verification = _planning(data).get("planBodyVerification")
+    if not isinstance(verification, Mapping):
+        raise PlanItemContractError(
+            f"implementationPlanning.planBodyVerification must be an object: {data_path}"
+        )
+    items = verification.get("planItems")
+    if not isinstance(items, list):
+        raise PlanItemContractError(
+            f"planBodyVerification.planItems must be an array: {data_path}"
+        )
+    return items
+
+
+def _apply_verdicts(args: argparse.Namespace) -> dict[str, Any]:
+    data = _load_json_object(args.data)
+    incoming = _load_json_object(args.verdicts).get("planItems")
+    if not isinstance(incoming, list):
+        raise PlanItemContractError("verdicts envelope has no `planItems` array")
+    rows = {
+        item["id"]: item.get("verdicts", [])
+        for item in incoming
+        if isinstance(item, Mapping) and isinstance(item.get("id"), str)
+    }
+    recorded = _plan_body_items(data, args.data)
+    known = {item.get("id") for item in recorded if isinstance(item, Mapping)}
+    missing = sorted(item_id for item_id in rows if item_id not in known)
+    if missing:
+        raise PlanItemContractError(
+            f"the report's planBodyVerification has no row for {missing} — the "
+            f"gate is re-derived from that table, so a verdict with nowhere to "
+            f"land would be scored as if it were never cast"
+        )
+    for item in recorded:
+        if isinstance(item, Mapping) and item.get("id") in rows:
+            # Overwrite, never merge: the contract records one round at a time,
+            # and a merged table lets a previous round's votes keep voting.
+            item["verdicts"] = rows[item["id"]]
+    write_json_atomic(args.data, data)
+    return {"ok": True, "operation": "apply-verdicts", "path": str(args.data)}
+
+
+_HANDLERS = {
+    "extract": _extract,
+    "validate": _validate,
+    "collect-verdicts": _collect_verdicts,
+    "apply-verdicts": _apply_verdicts,
+}
+
+
 def main(argv: list[str] | None = None) -> int:
     args = _parser().parse_args(argv)
     try:
-        result = _extract(args) if args.command == "extract" else _validate(args)
-    except (PlanItemContractError, OSError, ValueError) as exc:
+        result = _HANDLERS[args.command](args)
+    except (PlanItemContractError, VerdictBlockError, OSError, ValueError) as exc:
         print(f"plan-items: {exc}", file=sys.stderr)
         return 2
     print(json.dumps(result, ensure_ascii=False, indent=2))

package/runtime/python/okstra_ctl/profile_show.py

@@ -0,0 +1,134 @@
+"""Read-only flattened view of a phase profile (`okstra profile show`).
+
+A profile is assembled from three places — the top-level body, its
+`{{INCLUDE:}}` targets, and the lazy-read sidecars the body's own table names —
+so grepping the top-level file and finding nothing does not mean the rule is
+absent. This prints the whole thing, so one grep answers "does this task-type
+cover X".
+
+Read-only is the point, not a nicety: `render-bundle` would answer the same
+question, but it writes a manifest and registers the run in `recent.jsonl`.
+That side effect is exactly why it cannot be used to look something up.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import sys
+from pathlib import Path
+
+from .paths import find_asset_root
+from .run import PrepareError, _expand_profile_includes
+
+_PROFILES_REL = ("prompts", "profiles")
+
+# The sidecar table spells its targets as inline-code repo-relative paths, e.g.
+# `prompts/profiles/_implementation-executor.md`. Reading the list from the
+# profile body rather than hard-coding it here is deliberate: a list in code
+# goes stale the moment a profile adds a sidecar, and does so silently.
+_SIDECAR_RE = re.compile(r"`(prompts/profiles/_[\w-]+\.md)`")
+
+
+def workspace_root(start: Path | None = None) -> Path:
+    """Locate the runtime root that carries the `prompts/profiles` tree."""
+    root = find_asset_root(_PROFILES_REL, start=start, is_present=Path.is_dir)
+    if root is not None:
+        return root
+
+    raise PrepareError(
+        "could not locate prompts/profiles. Set OKSTRA_HOME or run from a "
+        "checkout that contains prompts/profiles/."
+    )
+
+
+def profile_path(root: Path, task_type: str) -> Path:
+    path = root.joinpath(*_PROFILES_REL, f"{task_type}.md")
+    if not path.is_file():
+        raise PrepareError(f"unknown task-type: {task_type} (no {path})")
+    return path
+
+
+def sidecar_bodies(root: Path, profile_text: str) -> list[str]:
+    """Every lazy-read sidecar reachable from the profile body, breadth-first.
+
+    The walk runs to a fixpoint because sidecars name sidecars of their own:
+    `_implementation-executor.md` points at the coding-conventions preflight,
+    the diff-review sweep, and the completion self-check. Stopping after one
+    hop would rebuild the very false negative this command exists to prevent,
+    one level down.
+
+    Each body is expanded rather than read raw, so nested `{{INCLUDE:}}`
+    directives resolve and the maintainer-only HTML comments drop out — the
+    same treatment the lead's rendered profile gets.
+    """
+    bodies: list[str] = []
+    seen: set[str] = set()
+    pending = list(dict.fromkeys(_SIDECAR_RE.findall(profile_text)))
+    while pending:
+        relative = pending.pop(0)
+        if relative in seen:
+            continue
+        seen.add(relative)
+        path = root / relative
+        if not path.is_file():
+            continue
+        body = _expand_profile_includes(path)
+        bodies.append(f"\n\n<!-- lazy-read sidecar: {relative} -->\n\n{body}")
+        pending.extend(ref for ref in _SIDECAR_RE.findall(body) if ref not in seen)
+    return bodies
+
+
+def render(root: Path, task_type: str, *, resolved: bool) -> str:
+    path = profile_path(root, task_type)
+    if not resolved:
+        return path.read_text(encoding="utf-8")
+    expanded = _expand_profile_includes(path)
+    return expanded + "".join(sidecar_bodies(root, expanded))
+
+
+def _write_stdout(text: str) -> None:
+    """Write the profile, tolerating a reader that stops early.
+
+    The command's whole purpose is to be piped into `grep` or `head`, and both
+    close the pipe as soon as they have enough. Without this, that normal usage
+    ends in a BrokenPipeError traceback — and the interpreter raises a second
+    one when it flushes stdout at shutdown, which is why the fd is redirected
+    to devnull rather than merely swallowing the first exception.
+    """
+    try:
+        sys.stdout.write(text)
+        sys.stdout.flush()
+    except BrokenPipeError:
+        devnull = os.open(os.devnull, os.O_WRONLY)
+        try:
+            os.dup2(devnull, sys.stdout.fileno())
+        finally:
+            os.close(devnull)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="okstra profile show",
+        description="Print a phase profile, optionally fully resolved (read-only).",
+    )
+    parser.add_argument("command", choices=("show",))
+    parser.add_argument("task_type")
+    parser.add_argument(
+        "--resolved",
+        action="store_true",
+        help="expand {{INCLUDE:}} targets and append the lazy-read sidecars",
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        text = render(workspace_root(), args.task_type, resolved=args.resolved)
+    except PrepareError as exc:
+        print(f"profile show: {exc}", file=sys.stderr)
+        return 2
+    _write_stdout(text)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/runtime/python/okstra_ctl/recap.py

@@ -11,7 +11,9 @@ import json
 import sys
 from pathlib import Path
 
+from okstra_ctl.clarification_items import sidecar_answers, user_response_sidecars
 from okstra_ctl.ids import slugify_task_segment
+from okstra_ctl.incremental_scope import preview_link_availability_for_report
 from okstra_ctl.paths import task_timeline_file
 from okstra_project import read_task_key
 from okstra_ctl.run_context import dir_flock
@@ -33,6 +35,63 @@ def _load_timeline(task_root: Path) -> list[dict]:
 
 
 
+_STRUCTURAL_CHANGE_NOTE = (
+    "An answer that overturns the selected option, restructures the Stage Map, "
+    'or changes the recommended approach requires --full-reason "<what changes '
+    'and how>". The back-trace resolves stages; it cannot judge whether the '
+    "plan's shape survived, so that call is the lead's and must be declared."
+)
+
+
+def _latest_planning_report(runs: list[dict], project_root: Path) -> Path | None:
+    """The most recent `implementation-planning` report still on disk."""
+    for run in reversed(runs):
+        if not isinstance(run, dict):
+            continue
+        if run.get("taskType") != "implementation-planning":
+            continue
+        relative = str(run.get("reportPath") or "")
+        if not relative:
+            continue
+        report = project_root / relative
+        if report.is_file():
+            return report
+    return None
+
+
+def rerun_readiness(project_root: Path, runs: list[dict]) -> dict | None:
+    """What the next clarification re-run needs, assembled from disk.
+
+    Every field is derivable before the run starts, and each one used to live
+    somewhere else: the flag value in the lead prompt (read only *after* the
+    run begins), the answered ids in sidecars, the re-verification mode nowhere
+    at all until `incremental-scope --preview`. Scattering them is why the user
+    had to ask for each one instead of being told.
+
+    ``None`` when nothing is waiting to be carried — no planning report, or no
+    answered clarification beside it.
+    """
+    report = _latest_planning_report(runs, project_root)
+    if report is None:
+        return None
+    answered = sorted(sidecar_answers(report))
+    if not answered:
+        return None
+    return {
+        "sourceReport": project_rel(report, project_root),
+        "answeredClarifications": answered,
+        "answeredClarificationsCsv": ",".join(answered),
+        "sidecars": [
+            project_rel(sidecar, project_root)
+            for sidecar in user_response_sidecars(report)
+        ],
+        "reverifyPreview": preview_link_availability_for_report(
+            report, set(answered)
+        ),
+        "structuralChangeNote": _STRUCTURAL_CHANGE_NOTE,
+    }
+
+
 def assemble_recap(task_root: Path, project_root: Path) -> dict:
     runs = _load_timeline(task_root)
     transitions = []
@@ -62,6 +121,10 @@ def assemble_recap(task_root: Path, project_root: Path) -> dict:
         "runCount": len(runs),
         "transitions": transitions,
         "latestPhaseStates": latest_states,
+        # `null` when nothing is waiting to be carried — the key is always
+        # present so a consumer can tell "no re-run pending" from "this recap
+        # predates the block".
+        "rerunReadiness": rerun_readiness(project_root, runs),
     }
 
 

package/runtime/python/okstra_ctl/render_final_report.py

@@ -52,6 +52,7 @@ from okstra_ctl.final_report_schema import (
 from okstra_ctl.i18n import I18nError, SUPPORTED_LANGS, load_dictionary, make_jinja_global
 from okstra_ctl.md_table import UNESCAPED_PIPE_RE, to_cell_text
 from okstra_ctl.models import UnknownModelError, resolve_model_metadata
+from okstra_ctl.paths import find_asset_root
 from okstra_ctl.report_contract import TASK_TYPE_DATA_PROPERTY, markdown_template_for
 from okstra_ctl.report_markdown import ReportSections
 from okstra_ctl.schema_excerpt import excerpt_cut_from_version
@@ -694,17 +695,9 @@ def find_default_template(start: Path | None = None) -> Path:
 
     Raises ``FinalReportRenderError`` if neither path is present.
     """
-    okstra_home = os.environ.get("OKSTRA_HOME")
-    if okstra_home:
-        candidate = Path(okstra_home).joinpath(*DEFAULT_TEMPLATE_REL)
-        if candidate.is_file():
-            return candidate
-
-    here = Path(start or __file__).resolve()
-    for parent in [here, *here.parents]:
-        candidate = parent.joinpath(*DEFAULT_TEMPLATE_REL)
-        if candidate.is_file():
-            return candidate
+    root = find_asset_root(DEFAULT_TEMPLATE_REL, start=start)
+    if root is not None:
+        return root.joinpath(*DEFAULT_TEMPLATE_REL)
 
     raise FinalReportRenderError(
         "could not locate final-report.template.md. Set OKSTRA_HOME or "
@@ -724,17 +717,9 @@ def find_default_template_for_data(
             f"unsupported final-report schemaVersion: {version}"
         ) from exc
 
-    okstra_home = os.environ.get("OKSTRA_HOME")
-    if okstra_home:
-        candidate = Path(okstra_home).joinpath(*relative_path)
-        if candidate.is_file():
-            return candidate
-
-    here = Path(start or __file__).resolve()
-    for parent in [here, *here.parents]:
-        candidate = parent.joinpath(*relative_path)
-        if candidate.is_file():
-            return candidate
+    root = find_asset_root(relative_path, start=start)
+    if root is not None:
+        return root.joinpath(*relative_path)
 
     raise FinalReportRenderError(
         f"could not locate {relative_path[-1]}. Set OKSTRA_HOME or run from a "

package/runtime/python/okstra_ctl/report_translation.py

@@ -24,7 +24,9 @@ from typing import Any, Iterator, Mapping, NamedTuple
 # Values the renderer reads as text and nothing else.
 PROSE_KEYS = frozenset({
     "acceptance",
+    "addedWork",
     "alternativesConsidered",
+    "answer",
     "approach",
     "approvalDisposition",
     "approvalEvidence",
@@ -50,6 +52,7 @@ PROSE_KEYS = frozenset({
     "declinedFixRecommendations",
     "description",
     "details",
+    "directionChange",
     "disagreement",
     "discrepancy",
     "disproveWith",
@@ -236,6 +239,7 @@ STRUCTURAL_KEYS = frozenset({
     "runManifest",
     "runSeq",
     "scope",              # 'PF-001' alongside prose
+    "scopeImpact",        # clarification reach tokens the gate matches on
     "sections",
     "shortSha",
     "signature",

package/runtime/python/okstra_ctl/report_views.py

@@ -693,12 +693,16 @@ def _strip_leading_letter_label(text: str) -> str:
     return re.sub(r"^\([a-z]\)\s*", "", text)
 
 
-def _parse_expected_form_options(expected_form: str) -> list[tuple[str, str]]:
+def parse_expected_form_options(expected_form: str) -> list[tuple[str, str]]:
     """Parse the ``Expected form`` contract format
     (``Recommended: <answer> — <rationale>; Alternatives: <options>``,
     `_common-contract.md` §Clarification request policy) into select
     ``(value, label)`` options. Returns ``[]`` when the cell carries no
-    ``Recommended:`` cue — the caller falls back to the statement enum."""
+    ``Recommended:`` cue — the caller falls back to the statement enum.
+
+    The single parser for this cell. Both the HTML view and
+    ``user_response.show_open_rows`` call it; a second implementation is
+    exactly how the two option boards drifted apart once already."""
     if not expected_form:
         return []
     expected_form = _PICK_ONE_ANNOTATION.sub("", expected_form)
@@ -791,7 +795,7 @@ def _form_control(
     # 계약(_common-contract.md §Clarification request policy)이 1순위,
     # statement 안 (a)(b)(c) 열거가 fallback. 후보가 있으면 select+기타 input.
     if kind_lc == "decision":
-        opts = _parse_expected_form_options(expected_form)
+        opts = parse_expected_form_options(expected_form)
         if not opts:
             opts = [
                 (letter, f"({letter}) {text}")

package/runtime/python/okstra_ctl/run.py

@@ -45,6 +45,7 @@ from .clarification_items import (
     clarification_response_with_sidecars,
     scan_approval_gate,
 )
+from .error_report import prior_run_error_digest
 from .qa_commands import format_errors as _format_qa_errors, validate_qa_commands
 from .material import (
     build_analysis_material,
@@ -857,6 +858,10 @@ class _ResolvedAssets:
     lead_contract: Path
     run_validator: Path
     brief_validator: Path
+    # None when this task-type's host orchestration carries no gates; see
+    # prompts/host-orchestration/README.md. Absence is a normal state, not a
+    # broken install, so it is exempt from the _INSTALL_HINT contract above.
+    host_rules_file: Path | None
 
 
 def _resolve_runtime_assets(workspace_root: Path, inp: PrepareInputs) -> _ResolvedAssets:
@@ -892,6 +897,9 @@ def _resolve_runtime_assets(workspace_root: Path, inp: PrepareInputs) -> _Resolv
             raise PrepareError(
                 f"required okstra template or lead contract missing: {required}.{_INSTALL_HINT}"
             )
+    host_rules_file = (
+        workspace_root / "prompts" / "host-orchestration" / f"{inp.task_type}.md"
+    )
     return _ResolvedAssets(
         profile_file=profile_file,
         prompt_template=prompt_template,
@@ -900,6 +908,7 @@ def _resolve_runtime_assets(workspace_root: Path, inp: PrepareInputs) -> _Resolv
         lead_contract=lead_contract,
         run_validator=run_validator,
         brief_validator=brief_validator,
+        host_rules_file=host_rules_file if host_rules_file.is_file() else None,
     )
 
 
@@ -1766,8 +1775,24 @@ def _write_verification_target_artifact(
     ctx["VERIFICATION_TARGET"] = target_path.read_text(encoding="utf-8")
 
 
+def _write_prior_run_error_digest(ctx: dict, instruction_set: Path) -> None:
+    """Stage the earlier runs' actionable errors — only when there are any.
+
+    No file at all when the task recorded none, rather than one saying "none":
+    a staged file the lead must open to learn it is empty costs a read every
+    run and teaches the lead to stop opening that path.
+    """
+    digest = prior_run_error_digest(Path(ctx["TASK_ROOT"]))
+    if digest:
+        (instruction_set / "prior-run-errors.md").write_text(digest, encoding="utf-8")
+
+
 def _write_instruction_set_sources(
-    inp: PrepareInputs, ctx: dict, profile_content: str, review_material: str
+    inp: PrepareInputs,
+    ctx: dict,
+    profile_content: str,
+    review_material: str,
+    host_rules_file: Path | None,
 ) -> Path:
     """instruction-set 디렉터리에 profile/material/brief/clarification/directive 와
     reference-expectations 를 기록하고 디렉터리 경로를 돌려준다."""
@@ -1775,6 +1800,7 @@ def _write_instruction_set_sources(
     instruction_set.mkdir(parents=True, exist_ok=True)
     _write_analysis_evidence_artifact(ctx, instruction_set)
     _write_verification_target_artifact(inp, ctx, instruction_set)
+    _write_prior_run_error_digest(ctx, instruction_set)
     profile_rendered = profile_content
     if inp.task_type == "implementation":
         profile_rendered += "\n\n{{DESIGN_PREP_CONTEXT}}\n\n{{FIX_RUN_CONTEXT}}"
@@ -1814,6 +1840,19 @@ def _write_instruction_set_sources(
         )
     (instruction_set / "analysis-material.md").write_text(review_material, encoding="utf-8")
     shutil.copyfile(inp.brief_path, instruction_set / "task-brief.md")
+    # A rule that lives only in the conversation is one compaction away from
+    # gone, with no signal that it went. On disk it survives, and the session
+    # conformance check can ask afterwards whether it was read. The token is
+    # set unconditionally because render_template_with_ctx fail-fasts on a
+    # token the launch template references but ctx lacks.
+    host_rules_relative = ""
+    if host_rules_file is not None:
+        staged_host_rules = instruction_set / "host-orchestration-rules.md"
+        shutil.copyfile(host_rules_file, staged_host_rules)
+        host_rules_relative = relative_to_project_root(
+            staged_host_rules, Path(ctx["PROJECT_ROOT"])
+        )
+    ctx["HOST_ORCHESTRATION_RULES_RELATIVE_PATH"] = host_rules_relative
     if inp.clarification_response_path:
         (instruction_set / "clarification-response.md").write_text(
             clarification_response_with_sidecars(Path(inp.clarification_response_path)),
@@ -2556,7 +2595,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
 
     # ---- write instruction-set scaffolding + lead prompt ----
     instruction_set = _write_instruction_set_sources(
-        inp, ctx, profile_content, review_material
+        inp, ctx, profile_content, review_material, assets.host_rules_file
     )
     prompt_text = _render_lead_prompt_and_snapshot(
         inp, ctx, instruction_set, final_report_template, prompt_template