okstra 0.127.0 → 0.129.0

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", ""),
     }
 
 
@@ -374,6 +376,22 @@ def _active_runtime_resources(ctx: dict) -> dict:
     return {
         "codingPreflightDir": ctx.get("OKSTRA_CODING_PREFLIGHT_DIR")
         or str(runtime_home / "prompts" / "coding-preflight"),
+        "workerPreamblePathByAudience": {
+            "analysis": ctx.get("ANALYSIS_WORKER_PREAMBLE_PATH")
+            or str(runtime_home / "templates" / "worker-prompt-preamble.md"),
+            "implementation-executor": ctx.get(
+                "IMPLEMENTATION_WORKER_PREAMBLE_PATH"
+            )
+            or str(runtime_home / "templates" / "implementation-worker-preamble.md"),
+            "implementation-verifier": ctx.get(
+                "IMPLEMENTATION_WORKER_PREAMBLE_PATH"
+            )
+            or str(runtime_home / "templates" / "implementation-worker-preamble.md"),
+            "report-writer": ctx.get("REPORT_WRITER_PREAMBLE_PATH")
+            or str(runtime_home / "templates" / "report-writer-prompt-preamble.md"),
+        },
+        "workerErrorContractPath": ctx.get("WORKER_ERROR_CONTRACT_PATH")
+        or str(runtime_home / "templates" / "worker-error-contract.md"),
     }
 
 
@@ -387,6 +405,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 +460,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 +1085,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 +1314,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", ""),
@@ -1761,6 +1799,19 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
     coding_preflight_dir = ctx.get("OKSTRA_CODING_PREFLIGHT_DIR") or str(
         home_prompts / "coding-preflight"
     )
+    runtime_templates = okstra_home() / "templates"
+    analysis_preamble = ctx.get("ANALYSIS_WORKER_PREAMBLE_PATH") or str(
+        runtime_templates / "worker-prompt-preamble.md"
+    )
+    implementation_preamble = ctx.get("IMPLEMENTATION_WORKER_PREAMBLE_PATH") or str(
+        runtime_templates / "implementation-worker-preamble.md"
+    )
+    report_writer_preamble = ctx.get("REPORT_WRITER_PREAMBLE_PATH") or str(
+        runtime_templates / "report-writer-prompt-preamble.md"
+    )
+    worker_error_contract = ctx.get("WORKER_ERROR_CONTRACT_PATH") or str(
+        runtime_templates / "worker-error-contract.md"
+    )
     okstra_runtime_resources_block = (
         "## Okstra Runtime Resources\n"
         "\n"
@@ -1773,7 +1824,11 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
         f"- Convergence contract: `{convergence_path}`\n"
         f"- Plan-body verification contract (implementation-planning Phase 6 sub-step only): `{plan_body_verification_path}`\n"
         f"- Report writer contract: `{report_writer_path}`\n"
-        f"- Coding preflight pack: `{coding_preflight_dir}`"
+        f"- Coding preflight pack: `{coding_preflight_dir}`\n"
+        f"- Analysis worker preamble: `{analysis_preamble}`\n"
+        f"- Implementation worker preamble: `{implementation_preamble}`\n"
+        f"- Report writer preamble: `{report_writer_preamble}`\n"
+        f"- Shared worker error contract: `{worker_error_contract}`"
     )
 
     def fmt_assignment(role: str, model: str, execution: str) -> str:
@@ -1893,10 +1948,6 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
         "the selected adapter's mapping. Follow the lifecycle core's lazy-read rules "
         "for support resources; do not invoke hidden/internal skills."
     )
-    worker_preamble_path = ctx.get(
-        "WORKER_PROMPT_PREAMBLE_PATH",
-        str(okstra_home() / "templates" / "worker-prompt-preamble.md"),
-    )
     worker_dispatch_guidance = (
         "## Worker Dispatch Contract\n"
         "\n"
@@ -1910,10 +1961,14 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
         "- Use `await_workers` through the selected adapter and confirm terminal state "
         "plus every required Result Path. File presence alone is never a signal to "
         "skip; worker selection and skipped status come from `team-state`.\n"
-        "- Every worker prompt must include the anchor header "
-        f"`**Worker Preamble Path:** {worker_preamble_path}`. That file is the canonical "
-        "source for Required Reading, Error Reporting, and Output sections; do not "
-        "re-inline those blocks into worker prompt bodies."
+        "- Resolve the worker's PromptPlan audience and inject exactly one "
+        "`**Worker Preamble Path:**` from the audience map: "
+        f"analysis=`{analysis_preamble}`, implementation executor/verifier="
+        f"`{implementation_preamble}`, report-writer=`{report_writer_preamble}`.\n"
+        "- Every initial worker prompt also injects "
+        f"`**Worker Error Contract Path:** {worker_error_contract}`. The selected "
+        "preamble owns audience procedure; the shared error contract owns error "
+        "schema and write rules. Do not re-inline either contract."
     )
 
     if lead_runtime == "external":
@@ -1984,12 +2039,24 @@ def apply_lead_prompt_defaults(ctx: dict) -> None:
     ctx.setdefault("STAGE_INTEGRATION", "")
     runtime_home = okstra_home()
     ctx.setdefault(
-        "WORKER_PROMPT_PREAMBLE_PATH",
+        "ANALYSIS_WORKER_PREAMBLE_PATH",
         str(runtime_home / "templates" / "worker-prompt-preamble.md"),
     )
+    ctx.setdefault(
+        "IMPLEMENTATION_WORKER_PREAMBLE_PATH",
+        str(runtime_home / "templates" / "implementation-worker-preamble.md"),
+    )
+    ctx.setdefault(
+        "REPORT_WRITER_PREAMBLE_PATH",
+        str(runtime_home / "templates" / "report-writer-prompt-preamble.md"),
+    )
+    ctx.setdefault(
+        "WORKER_ERROR_CONTRACT_PATH",
+        str(runtime_home / "templates" / "worker-error-contract.md"),
+    )
     # Lead resource paths the launch template references directly. paths.py
     # seeds the production values; setdefault backfills callers that render the
-    # template without the full path ctx (mirrors WORKER_PROMPT_PREAMBLE_PATH).
+    # template without the full path ctx.
     ctx.setdefault(
         "OKSTRA_LEAD_CONTRACT_PATH",
         str(runtime_home / "prompts" / "lead" / "okstra-lead-contract.md"),

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}}"
@@ -1950,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
@@ -2371,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/wizard.py

@@ -85,6 +85,7 @@ from okstra_ctl.worktree import (
     preview_worktree_decision,
 )
 from okstra_ctl.paths import task_dir, task_runs_dir
+from okstra_ctl.work_categories import resolve_work_category
 from okstra_ctl.run_context import latest_run_inputs
 from okstra_project.dirs import project_json_path
 from okstra_project.state import (
@@ -3126,6 +3127,17 @@ def _submit_fix_cycle_confirm(state: WizardState, value: str) -> Optional[str]:
     return f"fix-cycle: {v}"
 
 
+def _preview_work_category(state: WizardState) -> str:
+    """okstra-run 경로는 --work-category 를 넘기지 않는다. prepare 가 쓰는 것과
+    같은 resolver 를 태워야 미리보기 브랜치명이 실제 생성 브랜치와 일치한다."""
+    return resolve_work_category(
+        "",
+        project_root=Path(state.project_root),
+        task_group=state.task_group,
+        task_id=state.task_id,
+    )
+
+
 def _worktree_preview_line(state: WizardState) -> Optional[str]:
     """confirm 직전 요약 블록에 넣을 worktree 미리보기 한 줄.
     final-verification 은 stage worktree 를 읽기 전용 재사용하므로 None."""
@@ -3138,9 +3150,7 @@ def _worktree_preview_line(state: WizardState) -> Optional[str]:
         project_id=state.project_id,
         task_group_segment=state.task_group,
         task_id_segment=state.task_id,
-        # okstra-run 경로는 --work-category 를 넘기지 않으므로 provision 도 ""(→ "task-" prefix)로
-        # 브랜치를 만든다. 이 미리보기 브랜치명은 실제 생성 브랜치와 정확히 일치한다.
-        work_category="",
+        work_category=_preview_work_category(state),
         base_ref=state.base_ref,
     )
     key = {
@@ -3167,7 +3177,8 @@ def _worktree_preview_line_impl(state: WizardState) -> str:
                     path=str(parent_dir))
     decision = preview_stage_worktree_decision(
         project_id=state.project_id, task_group_segment=state.task_group,
-        task_id_segment=state.task_id, work_category="",
+        task_id_segment=state.task_id,
+        work_category=_preview_work_category(state),
         stage_number=int(stage),
     )
     key = ("worktree_impl_reuse" if decision.status == "reused"

package/runtime/python/okstra_ctl/work_categories.py

@@ -8,6 +8,11 @@ profile / validators / wizard 는 이 모듈에서 enum 을 import 해야 한다
 """
 from __future__ import annotations
 
+import json
+from pathlib import Path
+
+from .paths import task_dir
+
 WORK_CATEGORIES: tuple[str, ...] = (
     "bugfix",
     "feature",
@@ -16,6 +21,38 @@ WORK_CATEGORIES: tuple[str, ...] = (
     "improvement",
 )
 
+DEFAULT_WORK_CATEGORY = "feature"
+
 
 def is_valid_category(value: str) -> bool:
     return value in WORK_CATEGORIES
+
+
+def recorded_work_category(project_root: Path, task_group: str, task_id: str) -> str:
+    """task-manifest.json 에 이미 기록된 work-category. 없거나 enum 밖이면 ""."""
+    manifest = task_dir(project_root, task_group, task_id) / "task-manifest.json"
+    try:
+        data = json.loads(manifest.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return ""
+    value = str(data.get("workCategory") or "").strip()
+    return value if is_valid_category(value) else ""
+
+
+def resolve_work_category(
+    explicit: str, *, project_root: Path, task_group: str, task_id: str
+) -> str:
+    """이번 run 이 실제로 쓸 work-category: 명시값 → task 에 기록된 분류 →
+    DEFAULT_WORK_CATEGORY.
+
+    requirements-discovery 가 분류를 task-manifest 에 기록해두면 이후 phase 는
+    `--work-category` 없이 실행돼도 같은 branch namespace 로 수렴한다. 어느 쪽도
+    없을 때 `unknown`(→ `task/` 접두) 대신 기본 분류로 떨어뜨린다.
+    """
+    value = (explicit or "").strip()
+    if value:
+        return value
+    return (
+        recorded_work_category(project_root, task_group, task_id)
+        or DEFAULT_WORK_CATEGORY
+    )

package/runtime/python/okstra_ctl/worker_prompt_body.py

@@ -0,0 +1,107 @@
+"""Shared initial analysis-worker prompt body rendering."""
+from __future__ import annotations
+
+from typing import Any, Mapping, Sequence
+
+from .worker_prompt_policy import PromptPlan
+
+
+ANALYSIS_WORKER_LABELS = {
+    "claude": "Claude worker",
+    "codex": "Codex worker",
+    "antigravity": "Antigravity worker",
+}
+
+
+def analysis_prompt_body(
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    worker_id: str,
+    model: str,
+    role: str,
+    plan: PromptPlan,
+) -> list[str]:
+    """Render the provider-neutral body for an initial analysis audience."""
+    label = ANALYSIS_WORKER_LABELS.get(worker_id, f"{worker_id} worker")
+    return [
+        f"**Model:** {label}, {model}",
+        f"**Pane role:** {role}",
+        "",
+        f"# {label} Dispatch",
+        "",
+        "## Role",
+        (
+            f"You are the {label} for okstra cross-verification. "
+            "Produce an independent worker result."
+        ),
+        "",
+        "## Task",
+        f"- Task key: `{_require_string(manifest, 'taskKey')}`",
+        f"- Task type: `{_require_string(manifest, 'taskType')}`",
+        "",
+        "## Inputs",
+        *analysis_input_lines(manifest, active_context, plan),
+        "",
+        mcp_pointer_line(),
+        "",
+        "## Output Contract",
+        "- Read the Worker Preamble Path end-to-end before analysis.",
+        "- Write the worker result to Result Path and no other canonical result path.",
+        "- Write the audit sidecar and any tool-failure entries as the preamble requires.",
+        "- Cite evidence with file paths and line numbers whenever you make a claim.",
+    ]
+
+
+def analysis_input_lines(
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    plan: PromptPlan,
+) -> list[str]:
+    if plan.packet_only:
+        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")),
+        ("Analysis profile", instruction_path(manifest, active_context, "analysisProfilePath")),
+        ("Analysis material", instruction_path(manifest, active_context, "analysisMaterialPath")),
+        ("Reference expectations", instruction_path(manifest, active_context, "referenceExpectationsPath")),
+        ("Clarification response", instruction_path(manifest, active_context, "clarificationResponsePath")),
+    ]
+    return existing_input_lines(inputs)
+
+
+def existing_input_lines(inputs: Sequence[tuple[str, str]]) -> list[str]:
+    lines = [f"- {label}: `{path}`" for label, path in inputs if path]
+    return lines or ["- No input paths were recorded in active-run-context."]
+
+
+def instruction_path(
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    key: str,
+) -> str:
+    instruction_set = active_context.get("instructionSet")
+    if isinstance(instruction_set, Mapping):
+        value = _string_value(instruction_set.get(key))
+        if value:
+            return value
+    return _string_value(manifest.get(key))
+
+
+def mcp_pointer_line() -> str:
+    return (
+        '**MCP servers:** follow the task brief\'s "## Available MCP Servers" '
+        "section (already in your Required reading)."
+    )
+
+
+def _require_string(payload: Mapping[str, Any], key: str) -> str:
+    value = _string_value(payload.get(key))
+    if not value:
+        raise ValueError(f"missing required string field: {key}")
+    return value
+
+
+def _string_value(value: Any) -> str:
+    return value.strip() if isinstance(value, str) else ""