okstra 0.125.6 → 0.128.0

package/runtime/python/okstra_ctl/analysis_packet.py

@@ -41,8 +41,7 @@ PROFILE_SECTIONS_BY_TASK_TYPE = {
         "Self-review pass before finalising the report",
     ),
     "final-verification": (
-        "Required deliverable shape",
-        "Self-review pass before finalising the report",
+        "Worker verification procedure",
     ),
     "improvement-discovery": (
         "Phase 1.5 — Lead reflect-back grilling",
@@ -81,6 +80,7 @@ def build_analysis_packet(
     parts.extend(
         _intro_block(
             task_key,
+            task_type,
             instruction_set_relative_path,
             bool(clarification_response_path),
         )
@@ -113,6 +113,7 @@ def _packet_frontmatter(brief_text: str, task_key: str) -> str:
 
 def _intro_block(
     task_key: str,
+    task_type: str,
     instruction_set: str,
     has_clarification: bool,
 ) -> list[str]:
@@ -132,6 +133,10 @@ def _intro_block(
         f"- Analysis material: `{instruction_set}/analysis-material.md`",
         f"- Reference expectations: `{instruction_set}/reference-expectations.md`",
     ]
+    if task_type == "final-verification":
+        lines.append(
+            f"- Verification target: `{instruction_set}/verification-target.md`"
+        )
     if has_clarification:
         lines.append(
             f"- Clarification response: `{instruction_set}/clarification-response.md`"

package/runtime/python/okstra_ctl/codex_dispatch.py

@@ -27,6 +27,7 @@ from .path_hints import hydrate_active_run_context
 from .wrapper_status import status_path_for_prompt
 from .paths import task_dir
 from .worker_prompt_headers import WorkerPromptHeaderError, worker_prompt_headers
+from .worker_prompt_contract import validate_final_verification_prompt_paths
 
 
 SUPPORTED_CLI_WORKERS = {
@@ -182,6 +183,7 @@ def build_dispatch_plan(
         )
         for worker_id in selected_workers
     )
+    _validate_initial_final_verification_prompts(manifest, workers)
     return DispatchPlan(
         project_root=project_root,
         workspace_root=workspace_root,
@@ -193,6 +195,23 @@ def build_dispatch_plan(
     )
 
 
+def _validate_initial_final_verification_prompts(
+    manifest: Mapping[str, Any],
+    workers: Sequence[WorkerDispatch],
+) -> None:
+    if manifest.get("taskType") != "final-verification":
+        return
+    prompt_paths = {
+        worker.worker_id: worker.prompt_path
+        for worker in workers
+        if worker.worker_id != REPORT_WRITER_WORKER_ID
+        and "-reverify-r" not in worker.prompt_path.name
+    }
+    errors = validate_final_verification_prompt_paths(prompt_paths)
+    if errors:
+        raise DispatchError("final-verification prompt contract: " + "; ".join(errors))
+
+
 def dispatch_plan(plan: DispatchPlan) -> int:
     _set_dispatch_mode(plan.team_state_path, _dispatch_mode(plan.workers))
     for worker in plan.workers:
@@ -702,6 +721,13 @@ def _analysis_input_lines(
     manifest: Mapping[str, Any],
     active_context: Mapping[str, Any],
 ) -> list[str]:
+    if manifest.get("taskType") == "final-verification":
+        packet_path = _instruction_path(
+            manifest,
+            active_context,
+            "analysisPacketPath",
+        )
+        return _existing_input_lines((("Primary analysis packet", packet_path),))
     inputs = [
         ("Primary analysis packet", _instruction_path(manifest, active_context, "analysisPacketPath")),
         ("Task brief", _instruction_path(manifest, active_context, "taskBriefPath")),
@@ -800,7 +826,7 @@ def _worktree_headers(
 ) -> list[str]:
     task_type = _require_string(manifest, "taskType")
     worktree = _worktree_path(manifest, active_context)
-    if task_type not in {"implementation", "final-verification"} or not worktree:
+    if task_type != "implementation" or not worktree:
         return []
     headers = [f"**Worktree:** {worktree}"]
     if role == "executor":

package/runtime/python/okstra_ctl/design_surfaces.py

@@ -180,11 +180,28 @@ def _stage_rows(planning: Mapping[str, Any]) -> dict[int, Mapping[str, Any]]:
     return rows
 
 
-def _stage_for_selected_path(
+_LINE_RANGE_SUFFIX = re.compile(r":\d+(?:-\d+)?$")
+
+
+def _stages_for_selected_path(
     path: str,
     stages: Mapping[int, Mapping[str, Any]],
-) -> int:
-    normalised = _normalise(path)
+) -> list[int]:
+    """Every stage whose stepwise ``files`` cells touch *path*.
+
+    A file legitimately edited by more than one stage — the task-level
+    ``qa/conformance-manifest.json`` is the standard case, since each
+    conformance-declaring stage registers its own entry — yields one design
+    surface per stage, which is what the consumer keys on. Requiring a single
+    owner instead would force the plan to hide an edit, collapse stage
+    boundaries, or re-add the line-range suffixes that used to disambiguate
+    stages by accident.
+
+    Zero stages is still an error: the recommended option declares a file that
+    no step creates or edits.
+    """
+    normalised = _LINE_RANGE_SUFFIX.sub("", _normalise(path))
+    path_pattern = rf"(?<![\w./@-]){re.escape(normalised)}(?![\w./@-])"
     matched = []
     for stage_number, stage in stages.items():
         files = [
@@ -192,14 +209,13 @@ def _stage_for_selected_path(
             for step in stage.get("stepwiseExecution") or []
             if isinstance(step, Mapping)
         ]
-        path_pattern = rf"(?<![\w./@-]){re.escape(normalised)}(?![\w./@-])"
         if any(re.search(path_pattern, cell) is not None for cell in files):
             matched.append(stage_number)
-    if len(matched) != 1:
+    if not matched:
         raise DesignSurfaceError(
-            f"selected option path {path!r} is not mapped to a stage exactly once"
+            f"selected option path {path!r} is not mapped to a stage"
         )
-    return matched[0]
+    return matched
 
 
 def detect_design_surfaces(
@@ -226,13 +242,13 @@ def detect_design_surfaces(
         if not isinstance(row, Mapping):
             continue
         path = str(row.get("path") or "")
-        stage_number = _stage_for_selected_path(path, stages)
-        for kind, evidence in _matching_rule_evidence(
-            step=None,
-            field="files",
-            value=path,
-        ):
-            grouped.setdefault((stage_number, kind), []).append(evidence)
+        for stage_number in _stages_for_selected_path(path, stages):
+            for kind, evidence in _matching_rule_evidence(
+                step=None,
+                field="files",
+                value=path,
+            ):
+                grouped.setdefault((stage_number, kind), []).append(evidence)
     rule_order = {rule.kind: index for index, rule in enumerate(RULES)}
     return [
         DesignSurfaceTrigger(stage, kind, tuple(grouped[(stage, kind)]))

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -18,6 +18,7 @@ from .final_report_paths import (
 from .lead_events import LeadEvent, append_lead_event
 from .path_hints import hydrate_active_run_context
 from .worker_prompt_headers import WorkerPromptHeaderError, worker_prompt_headers
+from .worker_prompt_contract import validate_final_verification_prompt_paths
 from .wrapper_status import read_wrapper_status, status_path_for_prompt
 
 
@@ -183,6 +184,7 @@ def build_dispatch_plan(
         report_writer_model,
         options,
     )
+    _validate_initial_final_verification_prompts(manifest, jobs)
     return DispatchPlan(
         project_root=project_root,
         workspace_root=workspace_root.resolve(),
@@ -195,6 +197,24 @@ def build_dispatch_plan(
     )
 
 
+def _validate_initial_final_verification_prompts(
+    manifest: Mapping[str, Any],
+    jobs: Sequence[WorkerJob],
+) -> None:
+    if manifest.get("taskType") != "final-verification":
+        return
+    prompt_paths = {
+        job.worker_id: job.prompt_path
+        for job in jobs
+        if job.worker_id != REPORT_WRITER_WORKER_ID
+        and job.dispatch_kind == "initial"
+        and "-reverify-r" not in job.prompt_path.name
+    }
+    errors = validate_final_verification_prompt_paths(prompt_paths)
+    if errors:
+        raise DispatchError("final-verification prompt contract: " + "; ".join(errors))
+
+
 def dispatch_plan(plan: DispatchPlan, *, wait: bool = True) -> int:
     if wait:
         if any(job.backend == BACKEND_TMUX_PANE for job in plan.jobs):

package/runtime/python/okstra_ctl/log_report.py

@@ -53,6 +53,34 @@ def _per_task(files: list[dict]) -> list[dict]:
     return sorted(acc.values(), key=lambda a: a["totalBytes"], reverse=True)
 
 
+def _prompt_pair(log_path: Path, transcript_bytes: int) -> dict:
+    prompt_path = log_path.with_suffix(".md")
+    if not prompt_path.is_file():
+        return {
+            "transcriptPath": str(log_path),
+            "transcriptBytes": transcript_bytes,
+            "promptPath": "",
+            "promptBytes": 0,
+            "transcriptToPromptRatio": None,
+        }
+    try:
+        prompt_bytes = prompt_path.stat().st_size
+    except OSError:
+        prompt_bytes = 0
+    ratio = (
+        round(transcript_bytes / prompt_bytes, 2)
+        if prompt_bytes > 0
+        else None
+    )
+    return {
+        "transcriptPath": str(log_path),
+        "transcriptBytes": transcript_bytes,
+        "promptPath": str(prompt_path),
+        "promptBytes": prompt_bytes,
+        "transcriptToPromptRatio": ratio,
+    }
+
+
 def scan_logs(logs_root: Path, project_root: Path, top: int = 20) -> dict:
     project_id = _project_id(project_root)
     files: list[dict] = []
@@ -68,16 +96,27 @@ def scan_logs(logs_root: Path, project_root: Path, top: int = 20) -> dict:
                 continue
             meta = _parse(parts, p.stem)
             tk = f"{project_id}:{meta['taskGroup']}:{meta['taskId']}" if meta["taskGroup"] else ""
-            files.append({"path": str(p), "sizeBytes": size, "mtimeEpoch": mtime,
-                          "taskKey": tk, **meta})
+            files.append({
+                "path": str(p),
+                "sizeBytes": size,
+                "mtimeEpoch": mtime,
+                "taskKey": tk,
+                **meta,
+                **_prompt_pair(p, size),
+            })
     files.sort(key=lambda f: f["sizeBytes"], reverse=True)
     return {
         "logsRoot": str(logs_root),
         "topLargest": files[:top],
         "perTask": _per_task(files),
-        "totals": {"fileCount": len(files),
-                   "totalBytes": sum(f["sizeBytes"] for f in files),
-                   "taskCount": len({f["taskKey"] for f in files if f["taskKey"]})},
+        "totals": {
+            "fileCount": len(files),
+            "totalBytes": sum(f["sizeBytes"] for f in files),
+            "taskCount": len({f["taskKey"] for f in files if f["taskKey"]}),
+            "promptBytes": sum(f["promptBytes"] for f in files),
+            "transcriptBytes": sum(f["transcriptBytes"] for f in files),
+            "pairedFileCount": sum(1 for f in files if f["promptPath"]),
+        },
     }
 
 

package/runtime/python/okstra_ctl/path_hints.py

@@ -59,6 +59,7 @@ def compact_active_run_context(
         "inputs": _compact_active_inputs(payload),
         "workers": _compact_active_workers(payload),
         "executorWorktree": dict(_mapping(payload.get("executorWorktree"))),
+        "verificationTarget": dict(_mapping(payload.get("verificationTarget"))),
         "lazyReadPlan": dict(_mapping(payload.get("lazyReadPlan"))),
     }
 
@@ -99,6 +100,7 @@ def hydrate_active_run_context(payload: Mapping[str, Any]) -> dict[str, Any]:
             "codingPreflightDir": ctx.get("OKSTRA_CODING_PREFLIGHT_DIR", ""),
         },
         "executorWorktree": dict(_mapping(payload.get("executorWorktree"))),
+        "verificationTarget": dict(_mapping(payload.get("verificationTarget"))),
         "sourceArtifacts": _hydrate_active_source_artifacts(ctx),
         "lazyReadPlan": dict(_mapping(payload.get("lazyReadPlan"))),
     }
@@ -190,6 +192,7 @@ def _hydrate_active_instruction_set(
     clarification_response = ""
     if inputs.get("hasClarificationResponse"):
         clarification_response = f"{instruction_set}/clarification-response.md"
+    target = _mapping(payload.get("verificationTarget"))
     return {
         "path": instruction_set,
         "analysisPacketPath": ctx.get("ANALYSIS_PACKET_RELATIVE_PATH", ""),
@@ -200,6 +203,8 @@ def _hydrate_active_instruction_set(
         "clarificationResponsePath": clarification_response,
         "finalReportTemplatePath": ctx.get("FINAL_REPORT_TEMPLATE_RELATIVE_PATH", ""),
         "finalReportSchemaPath": ctx.get("FINAL_REPORT_SCHEMA_RELATIVE_PATH", ""),
+        "verificationTargetPath": str(target.get("path") or ""),
+        "verificationTargetDigest": str(target.get("digest") or ""),
     }
 
 

package/runtime/python/okstra_ctl/render.py

@@ -354,6 +354,8 @@ def _active_instruction_set(ctx: dict) -> dict:
         "clarificationResponsePath": clarification,
         "finalReportTemplatePath": ctx.get("FINAL_REPORT_TEMPLATE_RELATIVE_PATH", ""),
         "finalReportSchemaPath": ctx.get("FINAL_REPORT_SCHEMA_RELATIVE_PATH", ""),
+        "verificationTargetPath": ctx.get("VERIFICATION_TARGET_RELATIVE_PATH", ""),
+        "verificationTargetDigest": ctx.get("VERIFICATION_TARGET_DIGEST", ""),
     }
 
 
@@ -387,6 +389,19 @@ def _active_executor_worktree(ctx: dict) -> dict:
     }
 
 
+def _active_verification_target(ctx: dict) -> dict:
+    if ctx.get("TASK_TYPE") != "final-verification":
+        return {}
+    return {
+        "scope": ctx.get("VERIFICATION_SCOPE", ""),
+        "worktreePath": ctx.get("VERIFICATION_WORKTREE_PATH", ""),
+        "baseRef": ctx.get("VERIFICATION_BASE_REF", ""),
+        "headRef": ctx.get("VERIFICATION_HEAD_REF", ""),
+        "path": ctx.get("VERIFICATION_TARGET_RELATIVE_PATH", ""),
+        "digest": ctx.get("VERIFICATION_TARGET_DIGEST", ""),
+    }
+
+
 def _active_source_artifacts(ctx: dict) -> dict:
     return {
         "taskManifestPath": ctx.get("TASK_MANIFEST_RELATIVE_PATH", ""),
@@ -429,6 +444,7 @@ def render_active_run_context(active_context_path: str, ctx: dict) -> None:
         "errorLogs": _active_error_logs(ctx),
         "runtimeResources": _active_runtime_resources(ctx),
         "executorWorktree": _active_executor_worktree(ctx),
+        "verificationTarget": _active_verification_target(ctx),
         "sourceArtifacts": _active_source_artifacts(ctx),
         "lazyReadPlan": _active_lazy_read_plan(),
     }
@@ -1053,6 +1069,10 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
             "analysisMaterialPath": ctx.get("INSTRUCTION_SET_RELATIVE_PATH", "")
             + "/analysis-material.md",
             "analysisPacketPath": ctx.get("ANALYSIS_PACKET_RELATIVE_PATH", ""),
+            "verificationTargetPath": ctx.get(
+                "VERIFICATION_TARGET_RELATIVE_PATH", ""
+            ),
+            "verificationTargetDigest": ctx.get("VERIFICATION_TARGET_DIGEST", ""),
             "taskBriefCopyPath": ctx.get("INSTRUCTION_SET_RELATIVE_PATH", "")
             + "/task-brief.md",
             "referenceExpectationsPath": ctx.get(
@@ -1278,6 +1298,8 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
         "teamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
         "activeRunContextPath": ctx.get("ACTIVE_RUN_CONTEXT_RELATIVE_PATH", ""),
         "analysisPacketPath": ctx.get("ANALYSIS_PACKET_RELATIVE_PATH", ""),
+        "verificationTargetPath": ctx.get("VERIFICATION_TARGET_RELATIVE_PATH", ""),
+        "verificationTargetDigest": ctx.get("VERIFICATION_TARGET_DIGEST", ""),
         "workerResultsDirectoryPath": ctx.get("WORKER_RESULTS_RELATIVE_PATH", ""),
         "reportTemplatePath": ctx.get("FINAL_REPORT_TEMPLATE_RELATIVE_PATH", ""),
         "validatorScriptPath": ctx.get("RUN_VALIDATOR_RELATIVE_PATH", ""),

package/runtime/python/okstra_ctl/render_final_report.py

@@ -52,6 +52,8 @@ from okstra_ctl.final_report_schema import SchemaError, load_schema, validate as
 from okstra_ctl.i18n import I18nError, SUPPORTED_LANGS, load_dictionary, make_jinja_global
 from okstra_ctl.md_table import UNESCAPED_PIPE_RE, escape_pipes
 from okstra_ctl.models import UnknownModelError, resolve_model_metadata
+from okstra_ctl.schema_excerpt import excerpt_cut_from_version
+from okstra_ctl.seeding import installed_version
 
 
 DEFAULT_TEMPLATE_REL = ("templates", "reports", "final-report.template.md")
@@ -125,6 +127,21 @@ def _yaml_inline_list(values: list[str]) -> str:
     return "[" + ", ".join(_yaml_scalar(v) for v in values) + "]"
 
 
+def _md_quote(value: str | None, width: int = 2) -> str:
+    """Re-mark every continuation line of a multi-line blockquote value.
+
+    The template supplies the first line's ``  > ``; lines 2..n arrive at
+    column 0, where they end the enclosing list item and drag the bullets
+    that follow into one run-on paragraph.
+    """
+    text = "" if value is None else str(value)
+    pad = " " * width
+    lines = text.split("\n")
+    return "\n".join(
+        [lines[0]] + [f"{pad}>{' ' + line if line else ''}" for line in lines[1:]]
+    )
+
+
 # --- Index / scroll-anchor post-render pass -------------------------------
 # After Jinja2 renders the body, every report gets a top-of-report index and
 # clickable scroll anchors. An ID is *defined* when it is the leading token of
@@ -424,6 +441,11 @@ def _build_environment(template_dir: Path) -> Environment:
     # cannot split a markdown table row. Table-cell interpolations only —
     # never code blocks / headings / prose, where `\|` would render verbatim.
     env.filters["mdcell"] = escape_pipes
+    # `mdquote` re-marks continuation lines of a blockquote nested in a list
+    # item; the fenced siblings use Jinja's builtin `indent` for the same
+    # reason. Both exist because only the first line of an interpolation
+    # inherits the template's leading indent.
+    env.filters["mdquote"] = _md_quote
     return env
 
 
@@ -516,6 +538,47 @@ def find_default_template(start: Path | None = None) -> Path:
     )
 
 
+def _bundle_excerpt_path(data_path: Path) -> Path | None:
+    """The task bundle's schema excerpt, found by walking up from *data_path*."""
+    for ancestor in data_path.resolve().parents:
+        candidate = ancestor / "instruction-set" / "final-report-schema.json"
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _with_excerpt_drift_hint(
+    exc: FinalReportRenderError, data_path: Path
+) -> FinalReportRenderError:
+    """Name the version skew behind a schema failure, when that is the cause.
+
+    A long run straddles its own runtime upgrade: the report-writer authors
+    against the excerpt frozen into the bundle at prep time, while the renderer
+    validates against the installed schema. Without this the author sees only
+    `additional property ... not allowed` for a field the excerpt told it to
+    write, and has no way to tell a real mistake from a stale bundle.
+    """
+    if "schema validation" not in str(exc):
+        return exc
+    excerpt_path = _bundle_excerpt_path(data_path)
+    if excerpt_path is None:
+        return exc
+    try:
+        cut_from = excerpt_cut_from_version(
+            json.loads(excerpt_path.read_text(encoding="utf-8"))
+        )
+    except (OSError, json.JSONDecodeError):
+        return exc
+    current = installed_version()
+    if not cut_from or not current or cut_from == current:
+        return exc
+    return FinalReportRenderError(
+        f"{exc} — the bundle's schema excerpt ({excerpt_path}) was cut from okstra "
+        f"{cut_from} but validation ran on {current}; author against the installed "
+        "schema, not the excerpt, or re-prepare the bundle."
+    )
+
+
 def render_to_file(
     data_path: Path,
     output_path: Path,
@@ -542,11 +605,14 @@ def render_to_file(
     # 설치본에서 항상 'could not locate template' 으로 실패한다(OKSTRA_HOME 을
     # 수동 설정해야 했던 원인). 프로젝트별 override 는 --template 으로 한다.
     resolved_template = template_path or find_default_template()
-    rendered = render(
-        data,
-        template_path=resolved_template,
-        report_language=report_language,
-    )
+    try:
+        rendered = render(
+            data,
+            template_path=resolved_template,
+            report_language=report_language,
+        )
+    except FinalReportRenderError as exc:
+        raise _with_excerpt_drift_hint(exc, data_path) from exc
 
     output_path.parent.mkdir(parents=True, exist_ok=True)
     tmp = output_path.with_suffix(output_path.suffix + f".tmp.{os.getpid()}")

package/runtime/python/okstra_ctl/run.py

@@ -16,6 +16,7 @@ state passing, and are read once at the start.
 from __future__ import annotations
 
 import importlib.util
+import hashlib
 import json
 import os
 import re
@@ -100,6 +101,7 @@ from . import implementation_stage as _implementation_stage
 from .stage_reconcile import (
     auto_reconcile_best_effort as _stage_auto_reconcile_best_effort,
 )
+from .work_categories import resolve_work_category
 from .worktree import (
     WorktreeProvision,
     provision_task_worktree,
@@ -1578,20 +1580,70 @@ def _reserve_final_verification_target(
 
     diff_stat = _git_out(target.worktree_path, "diff", "--stat",
                          f"{target.base}..{target.head}")
+    ctx["VERIFICATION_SCOPE"] = target.scope
+    ctx["VERIFICATION_WORKTREE_PATH"] = target.worktree_path
+    ctx["VERIFICATION_BASE_REF"] = target.base
+    ctx["VERIFICATION_HEAD_REF"] = target.head
+    ctx["VERIFICATION_TARGET"] = _format_verification_target(target, diff_stat)
+
+
+def _format_verification_target(
+    target: _stage_targets.FinalVerificationTarget,
+    diff_stat: str,
+) -> str:
     reports = "\n".join(
         f"  - stage {s}: `{rp or '(report_path unrecorded)'}`"
         for s, rp in zip(target.stages, target.reports)
     )
-    ctx["VERIFICATION_TARGET"] = (
+    return (
         f"- **Verification scope:** `{target.scope}`\n"
         f"- **Worktree:** `{target.worktree_path}`\n"
         f"- **Verification base ref:** `{target.base}`\n"
+        f"- **Verification head ref:** `{target.head}`\n"
         f"- **Stages under verification:** {target.stages}\n"
         f"- **Source implementation reports:**\n{reports}\n"
         f"- **Verification diff stat:**\n```\n{diff_stat}\n```"
     )
 
 
+def write_verification_target_snapshot(
+    instruction_set: Path,
+    target_markdown: str,
+) -> tuple[Path, str]:
+    """Persist one normalized final-verification target and return its digest."""
+    normalized = target_markdown.replace("\r\n", "\n").replace("\r", "\n")
+    normalized = normalized.rstrip() + "\n"
+    digest = "sha256:" + hashlib.sha256(normalized.encode("utf-8")).hexdigest()
+    path = instruction_set / "verification-target.md"
+    path.write_text(
+        normalized + f"- **Verification target digest:** `{digest}`\n",
+        encoding="utf-8",
+    )
+    return path, digest
+
+
+def _write_verification_target_artifact(
+    inp: PrepareInputs,
+    ctx: dict,
+    instruction_set: Path,
+) -> None:
+    if inp.task_type != "final-verification":
+        return
+    target_markdown = str(ctx.get("VERIFICATION_TARGET") or "")
+    if not target_markdown:
+        raise PrepareError("final-verification target snapshot is missing")
+    target_path, target_digest = write_verification_target_snapshot(
+        instruction_set,
+        target_markdown,
+    )
+    ctx["VERIFICATION_TARGET_PATH"] = str(target_path)
+    ctx["VERIFICATION_TARGET_RELATIVE_PATH"] = (
+        f"{ctx['INSTRUCTION_SET_RELATIVE_PATH']}/verification-target.md"
+    )
+    ctx["VERIFICATION_TARGET_DIGEST"] = target_digest
+    ctx["VERIFICATION_TARGET"] = target_path.read_text(encoding="utf-8")
+
+
 def _write_instruction_set_sources(
     inp: PrepareInputs, ctx: dict, profile_content: str, review_material: str
 ) -> Path:
@@ -1599,6 +1651,7 @@ def _write_instruction_set_sources(
     reference-expectations 를 기록하고 디렉터리 경로를 돌려준다."""
     instruction_set = Path(ctx["INSTRUCTION_SET_PATH"])
     instruction_set.mkdir(parents=True, exist_ok=True)
+    _write_verification_target_artifact(inp, ctx, instruction_set)
     profile_rendered = profile_content
     if inp.task_type == "implementation":
         profile_rendered += "\n\n{{DESIGN_PREP_CONTEXT}}\n\n{{FIX_RUN_CONTEXT}}"
@@ -1709,7 +1762,9 @@ def _render_lead_prompt_and_snapshot(
     # still has the phase-stripped template + skill structure guide, and
     # validation runs against the full schema regardless.
     try:
-        _excerpt = build_schema_excerpt(load_schema(), inp.task_type)
+        _excerpt = build_schema_excerpt(
+            load_schema(), inp.task_type, installed_version()
+        )
         Path(ctx["FINAL_REPORT_SCHEMA_PATH"]).write_text(
             json.dumps(_excerpt, indent=2, ensure_ascii=False) + "\n",
             encoding="utf-8",
@@ -1948,6 +2003,16 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     task_id_segment = slugify(inp.task_id)
     task_key = f"{inp.project_id}:{inp.task_group}:{inp.task_id}"
 
+    # Worktree branch namespace, workflow state and every rendered manifest read
+    # the same resolved value, so a phase invoked without --work-category still
+    # lands on the branch namespace the task was classified with.
+    inp.work_category = resolve_work_category(
+        inp.work_category,
+        project_root=project_root,
+        task_group=inp.task_group,
+        task_id=inp.task_id,
+    )
+
     # ---- task worktree provisioning (every phase, every task-type) ----
     # One worktree per task-key: requirements-discovery, error-analysis,
     # implementation-planning and implementation phases of the same task
@@ -2369,7 +2434,8 @@ def main(argv: list[str]) -> int:
         help=(
             "Work-category classification for this task "
             "(bugfix / feature / refactor / ops / improvement). "
-            "Falls back to `unknown` when omitted."
+            "When omitted, falls back to the category already recorded in "
+            "task-manifest.json, then to `feature`."
         ),
     )
     p.add_argument(

package/runtime/python/okstra_ctl/schema_excerpt.py

@@ -72,7 +72,16 @@ def _conditional_applies(entry: dict, task_type: str) -> bool:
     return task_type in (enum or [])
 
 
-def build_schema_excerpt(schema: dict, task_type: str) -> dict:
+EXCERPT_VERSION_KEY = "x-okstraCutFromVersion"
+
+
+def excerpt_cut_from_version(excerpt: dict) -> str:
+    """The okstra version *excerpt* was cut from; empty when unstamped."""
+    value = excerpt.get(EXCERPT_VERSION_KEY)
+    return value if isinstance(value, str) else ""
+
+
+def build_schema_excerpt(schema: dict, task_type: str, cut_from_version: str = "") -> dict:
     """Return a task-type-scoped copy of *schema*.
 
     Drops the per-type property blocks that do not belong to *task_type*,
@@ -81,6 +90,11 @@ def build_schema_excerpt(schema: dict, task_type: str) -> dict:
     def reachable from a kept property or conditional). Top-level metadata
     and ``required`` are preserved (``required`` never lists per-type
     blocks, but it is filtered defensively).
+
+    *cut_from_version* stamps the excerpt with the runtime that produced it.
+    Bundle prep and report render can be hours apart and the runtime upgrades
+    itself in between, so a mismatch is what turns an opaque "additional
+    property … not allowed" into "the bundle excerpt is from an older okstra".
     """
     keep_per_type = _TASK_TYPE_PROPERTY.get(task_type)
     drop_props = _ALL_PER_TYPE_PROPERTIES - ({keep_per_type} if keep_per_type else set())
@@ -119,4 +133,6 @@ def build_schema_excerpt(schema: dict, task_type: str) -> dict:
         excerpt["allOf"] = all_of
     if reachable:
         excerpt["$defs"] = {k: v for k, v in defs.items() if k in reachable}
+    if cut_from_version:
+        excerpt[EXCERPT_VERSION_KEY] = cut_from_version
     return excerpt