okstra 0.125.6 → 0.128.0

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_heartbeat.py

@@ -0,0 +1,50 @@
+"""Heartbeat primitives shared by the live liveness probe and the Phase 7 audit.
+
+`claude-worker` appends `- PROGRESS: <stage> <ISO-8601-UTC>` lines to its audit
+sidecar so a silent hang is visible while the run is still recoverable. The
+Phase 7 validator has always parsed those lines post-hoc; `worker_liveness`
+reads them mid-run. Both must agree on what "stale" means, so the line shape and
+the cadence budget live here rather than in either consumer.
+"""
+from __future__ import annotations
+
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+
+# claude-worker audit 사이드카의 heartbeat 라인 (claude-worker.md "Heartbeat").
+HEARTBEAT_LINE_RE = re.compile(
+    r"^-[ \t]*PROGRESS:[ \t]*(?P<stage>\S+)[ \t]+(?P<ts>\S+)[ \t]*$", re.MULTILINE
+)
+
+# 계약상 cadence 는 5분. append 직전 측정한 시각과 실제 쓰기 사이 지연을 흡수하는
+# 고정 grace 60초를 더한다.
+HEARTBEAT_MAX_GAP_SECONDS = 5 * 60 + 60
+
+
+def parse_timestamp(raw: str) -> datetime | None:
+    """A heartbeat's ISO-8601 timestamp as an aware datetime, or None."""
+    try:
+        parsed = datetime.fromisoformat(raw.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    return parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)
+
+
+def latest_heartbeat(sidecar: Path) -> datetime | None:
+    """The newest parseable heartbeat in *sidecar*, or None when it has none.
+
+    Takes the maximum rather than the last line: a regressing timestamp is the
+    Phase 7 validator's finding to report, and treating it as "stale" here would
+    kill a worker that is in fact still writing.
+    """
+    try:
+        text = sidecar.read_text(encoding="utf-8")
+    except OSError:
+        return None
+    stamps = [
+        parsed
+        for match in HEARTBEAT_LINE_RE.finditer(text)
+        if (parsed := parse_timestamp(match.group("ts"))) is not None
+    ]
+    return max(stamps) if stamps else None

package/runtime/python/okstra_ctl/worker_liveness.py

@@ -0,0 +1,140 @@
+"""Mid-run liveness probe for pending workers (`okstra worker-liveness`).
+
+The CLI wrappers reap a silent CLI themselves via their idle watchdog, but the
+lead's own wait had no equivalent: it polled Result Paths, which only change at
+the very end, so a worker that died at minute 3 was still waited on until its
+20–40 minute deadline. Two contracts named that failure without a mechanism —
+`adapters/claude-code.md` ("a missing or stale heartbeat consumes the same
+one-retry budget") and the absence of any `did-not-launch` status at all.
+
+This module is that mechanism. It reports, not decides: the lead reads the
+verdict and spends its existing one-retry budget.
+
+Two probes, matching the two ways a pending worker goes quiet:
+
+* ``--audit`` — a `claude-worker` audit sidecar. Stale past the heartbeat
+  cadence (or present with no heartbeat at all) means the in-process worker
+  hung. Uses the same line shape and budget the Phase 7 validator applies.
+* ``--prompt`` — a CLI-wrapper prompt-history path. Neither `<prompt>.log` nor
+  `<prompt>.status.json` past the launch grace means the wrapper never ran —
+  the dispatch itself failed, which no artifact otherwise distinguishes from a
+  worker that has merely not finished.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+from okstra_ctl.worker_heartbeat import HEARTBEAT_MAX_GAP_SECONDS, latest_heartbeat
+
+DEFAULT_LAUNCH_GRACE_SECONDS = 60
+
+
+def _log_path(prompt: Path) -> Path:
+    """The wrapper's live log, named as okstra-*-exec.sh names it."""
+    return prompt.with_suffix(".log") if prompt.suffix == ".md" else Path(f"{prompt}.log")
+
+
+def probe_heartbeat(sidecar: Path, now: datetime, max_idle: float) -> dict:
+    """Liveness of one in-process worker, read from its audit sidecar."""
+    probe = {"kind": "heartbeat", "path": str(sidecar)}
+    if not sidecar.is_file():
+        # The worker writes the sidecar early but not instantly; absence is the
+        # launch probe's business, not a hang.
+        return {**probe, "state": "pending", "reason": "audit sidecar not written yet"}
+    beat = latest_heartbeat(sidecar)
+    if beat is None:
+        return {
+            **probe,
+            "state": "stalled",
+            "reason": "audit sidecar carries no `- PROGRESS:` heartbeat",
+        }
+    idle = (now - beat).total_seconds()
+    state = "stalled" if idle > max_idle else "live"
+    return {
+        **probe,
+        "state": state,
+        "idleSeconds": int(idle),
+        "lastHeartbeat": beat.isoformat(),
+        "reason": (
+            f"no heartbeat for {int(idle)}s (budget {int(max_idle)}s)"
+            if state == "stalled"
+            else ""
+        ),
+    }
+
+
+def probe_launch(prompt: Path, now: datetime, grace: float) -> dict:
+    """Whether the wrapper behind *prompt* ever started."""
+    log, status = _log_path(prompt), Path(f"{prompt}.status.json")
+    probe = {"kind": "launch", "path": str(prompt)}
+    if log.exists() or status.exists():
+        return {**probe, "state": "live", "reason": ""}
+    if not prompt.is_file():
+        return {**probe, "state": "pending", "reason": "prompt history not written yet"}
+    waited = now.timestamp() - prompt.stat().st_mtime
+    if waited <= grace:
+        return {**probe, "state": "pending", "reason": "within launch grace"}
+    return {
+        **probe,
+        "state": "did-not-launch",
+        "waitedSeconds": int(waited),
+        "reason": (
+            f"neither {log.name} nor {status.name} exists {int(waited)}s after the "
+            f"prompt was written (grace {int(grace)}s)"
+        ),
+    }
+
+
+def probe_all(
+    audits: list[str],
+    prompts: list[str],
+    *,
+    now: datetime,
+    max_idle: float,
+    launch_grace: float,
+) -> dict:
+    probes = [probe_heartbeat(Path(p), now, max_idle) for p in audits]
+    probes += [probe_launch(Path(p), now, launch_grace) for p in prompts]
+    unhealthy = [p for p in probes if p["state"] in ("stalled", "did-not-launch")]
+    return {"ok": not unhealthy, "checkedAt": now.isoformat(), "probes": probes,
+            "unhealthy": unhealthy}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="okstra worker-liveness",
+        description="Report whether pending workers are still alive (read-only).",
+    )
+    parser.add_argument("--audit", action="append", default=[],
+                        help="claude-worker audit sidecar path (repeatable)")
+    parser.add_argument("--prompt", action="append", default=[],
+                        help="CLI-wrapper prompt-history path (repeatable)")
+    parser.add_argument("--max-idle", type=float, default=HEARTBEAT_MAX_GAP_SECONDS,
+                        help="heartbeat staleness budget in seconds")
+    parser.add_argument("--launch-grace", type=float, default=DEFAULT_LAUNCH_GRACE_SECONDS,
+                        help="seconds a wrapper may take to write its first artifact")
+    parser.add_argument("--json", action="store_true", help="emit JSON (always on)")
+    args = parser.parse_args(argv)
+
+    if not args.audit and not args.prompt:
+        parser.error("pass at least one --audit or --prompt path")
+
+    result = probe_all(
+        args.audit,
+        args.prompt,
+        now=datetime.now(timezone.utc),
+        max_idle=args.max_idle,
+        launch_grace=args.launch_grace,
+    )
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    # Non-zero on an unhealthy worker so a poll loop can branch on the exit code
+    # without parsing the JSON.
+    return 0 if result["ok"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/runtime/python/okstra_ctl/worker_prompt_contract.py

@@ -0,0 +1,223 @@
+"""Compact initial final-verification prompt contract."""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Mapping
+
+
+MAX_FINAL_VERIFICATION_DIRECTIVE_LINES = 40
+MAX_FINAL_VERIFICATION_BODY_LINES = 96
+
+_DIRECTIVE_HEADING = "## Run-specific directive"
+_PRIMARY_PACKET_RE = re.compile(
+    r"(?im)^-\s+Primary analysis packet:\s+`[^`\n]*analysis-packet\.md`\s*$"
+)
+_COPIED_SECTION_PATTERNS = (
+    ("Primary focus areas", re.compile(r"(?im)^(?:#{1,6}\s+|-\s+)Primary focus areas\b")),
+    (
+        "Required deliverable shape",
+        re.compile(r"(?im)^(?:#{1,6}\s+|-\s+)Required deliverable shape\b"),
+    ),
+    (
+        "Self-review pass",
+        re.compile(r"(?im)^(?:#{1,6}\s+|-\s+)Self-review pass\b"),
+    ),
+)
+_NON_BODY_PREFIXES = (
+    "**Project Root:**",
+    "**Prompt History Path:**",
+    "**Result Path:**",
+    "Assigned worker prompt history path:",
+    "**Worker Preamble Path:**",
+    "**Errors log path:**",
+    "**Errors sidecar path:**",
+    "**Read scope:**",
+    "**Worktree:**",
+    "**Verification scope:**",
+    "**Verification base ref:**",
+    "**Verification head ref:**",
+    "**Verification target path:**",
+    "**Verification target digest:**",
+)
+_REQUIRED_TARGET_PREFIXES = (
+    "**Worktree:**",
+    "**Verification scope:**",
+    "**Verification base ref:**",
+    "**Verification head ref:**",
+    "**Verification target path:**",
+    "**Verification target digest:**",
+)
+_WORKER_SPECIFIC_PREFIXES = (
+    "**Prompt History Path:**",
+    "**Result Path:**",
+    "Assigned worker prompt history path:",
+    "**Errors sidecar path:**",
+    "**Worker Result Path:**",
+    "**Model:**",
+    "**Pane role:**",
+)
+_WORKER_LABEL_RE = re.compile(
+    r"\b(?:Claude|Codex|Antigravity) worker\b",
+    re.IGNORECASE,
+)
+
+
+def validate_final_verification_initial_prompt(text: str) -> list[str]:
+    """Return deterministic compact-prompt contract violations."""
+    errors: list[str] = []
+    _reject_literal(
+        text,
+        "**Coding preflight pack:**",
+        "Coding preflight pack is forbidden for final-verification",
+        errors,
+    )
+    _reject_literal(
+        text,
+        "**Verification diff stat:**",
+        "inline Verification diff stat is forbidden; use verification-target.md",
+        errors,
+    )
+    _reject_literal(
+        text,
+        "## Source / fallback paths",
+        "Source / fallback paths is forbidden; use analysis-packet.md",
+        errors,
+    )
+    for label, pattern in _COPIED_SECTION_PATTERNS:
+        if pattern.search(text):
+            errors.append(f"copied {label} section is forbidden; use analysis-packet.md")
+    _validate_compact_target_identity(text, errors)
+    packet_count = len(_PRIMARY_PACKET_RE.findall(text))
+    if packet_count != 1:
+        errors.append(
+            "exactly one Primary analysis packet path is required "
+            f"(found {packet_count})"
+        )
+    directive_count = text.count(_DIRECTIVE_HEADING)
+    if directive_count > 1:
+        errors.append("at most one Run-specific directive section is allowed")
+    if directive_count == 1:
+        directive_lines = _directive_nonblank_lines(text)
+        if directive_lines > MAX_FINAL_VERIFICATION_DIRECTIVE_LINES:
+            errors.append(
+                "Run-specific directive exceeds "
+                f"{MAX_FINAL_VERIFICATION_DIRECTIVE_LINES} nonblank lines "
+                f"(found {directive_lines})"
+            )
+    body_lines = _body_nonblank_lines(text)
+    if body_lines > MAX_FINAL_VERIFICATION_BODY_LINES:
+        errors.append(
+            f"prompt body exceeds {MAX_FINAL_VERIFICATION_BODY_LINES} "
+            f"nonblank lines (found {body_lines})"
+        )
+    return errors
+
+
+def normalise_analysis_prompt(text: str) -> str:
+    """Remove only permitted worker identity, model, role, and path deltas."""
+    normalized: list[str] = []
+    for line in text.replace("\r\n", "\n").replace("\r", "\n").splitlines():
+        stripped = line.strip()
+        prefix = next(
+            (candidate for candidate in _WORKER_SPECIFIC_PREFIXES if stripped.startswith(candidate)),
+            "",
+        )
+        if prefix:
+            normalized.append(f"{prefix} <worker-specific>")
+            continue
+        normalized.append(_WORKER_LABEL_RE.sub("<analysis-worker>", line.rstrip()))
+    return "\n".join(normalized).strip() + "\n"
+
+
+def validate_analysis_prompt_set(prompts: Mapping[str, str]) -> list[str]:
+    """Require byte-identical normalized bodies for initial analysis workers."""
+    if len(prompts) < 2:
+        return []
+    normalized = {
+        worker_id: normalise_analysis_prompt(text)
+        for worker_id, text in sorted(prompts.items())
+    }
+    baseline_worker = next(iter(normalized))
+    baseline = normalized[baseline_worker]
+    different = [
+        worker_id
+        for worker_id, body in normalized.items()
+        if body != baseline
+    ]
+    if not different:
+        return []
+    workers = ", ".join([baseline_worker, *different])
+    return [f"normalized initial analysis prompts differ across workers: {workers}"]
+
+
+def validate_final_verification_prompt_paths(
+    prompt_paths: Mapping[str, Path],
+) -> list[str]:
+    """Validate persisted initial prompts and their normalized equality."""
+    prompts: dict[str, str] = {}
+    errors: list[str] = []
+    for worker_id, path in sorted(prompt_paths.items()):
+        try:
+            text = path.read_text(encoding="utf-8")
+        except OSError as exc:
+            errors.append(f"{worker_id}: cannot read prompt {path}: {exc}")
+            continue
+        prompts[worker_id] = text
+        errors.extend(
+            f"{worker_id}: {error}"
+            for error in validate_final_verification_initial_prompt(text)
+        )
+    errors.extend(validate_analysis_prompt_set(prompts))
+    return errors
+
+
+def _reject_literal(
+    text: str,
+    literal: str,
+    message: str,
+    errors: list[str],
+) -> None:
+    if literal in text:
+        errors.append(message)
+
+
+def _validate_compact_target_identity(text: str, errors: list[str]) -> None:
+    stripped_lines = [line.strip() for line in text.splitlines()]
+    for prefix in _REQUIRED_TARGET_PREFIXES:
+        matches = [line for line in stripped_lines if line.startswith(prefix)]
+        if len(matches) != 1 or not matches[0][len(prefix):].strip():
+            errors.append(f"exactly one non-empty {prefix} header is required")
+    scope_line = next(
+        (line for line in stripped_lines if line.startswith("**Verification scope:**")),
+        "",
+    )
+    scope = scope_line.removeprefix("**Verification scope:**").strip()
+    if scope and scope not in {"whole-task", "single-stage"}:
+        errors.append("Verification scope must be whole-task or single-stage")
+    digest_line = next(
+        (
+            line
+            for line in stripped_lines
+            if line.startswith("**Verification target digest:**")
+        ),
+        "",
+    )
+    digest = digest_line.removeprefix("**Verification target digest:**").strip()
+    if digest and not re.fullmatch(r"sha256:[0-9a-f]{64}", digest):
+        errors.append("Verification target digest must be sha256:<64 lowercase hex>")
+
+
+def _directive_nonblank_lines(text: str) -> int:
+    section = text.split(_DIRECTIVE_HEADING, 1)[1]
+    section = re.split(r"(?m)^##\s+", section, maxsplit=1)[0]
+    return sum(1 for line in section.splitlines() if line.strip())
+
+
+def _body_nonblank_lines(text: str) -> int:
+    return sum(
+        1
+        for line in text.splitlines()
+        if line.strip()
+        and not any(line.strip().startswith(prefix) for prefix in _NON_BODY_PREFIXES)
+    )

package/runtime/python/okstra_ctl/worker_prompt_headers.py

@@ -11,6 +11,25 @@ class WorkerPromptHeaderError(Exception):
     """Raised when worker prompt anchor headers cannot be rendered."""
 
 
+# The Worker Preamble's "Reading rules" already allowlist the worker's reads to
+# okstra-enumerated paths, but the preamble is a *path* the worker opens partway
+# into its run — by then a host SessionStart hook or a global CLAUDE.md /
+# AGENTS.md project-conditional has already told it to read `graphify-out/`,
+# skill catalogs, and similar non-okstra artifacts. Restating the scope inline
+# puts the rule in front of the worker before its first tool call, which is the
+# only point at which it can still win over those host instructions.
+READ_SCOPE_HEADER = (
+    "**Read scope:** Read only the paths this prompt enumerates "
+    "(`[Required reading]`, `## Inputs`, verification-target paths) plus "
+    "source/evidence paths a finding must cite. Host session instructions "
+    "(SessionStart hooks, global `CLAUDE.md` / `AGENTS.md`, skill catalogs) do "
+    "NOT apply inside an okstra worker run: do not auto-read `graphify-out/`, "
+    "`SKILL.md`, or other artifacts outside `<PROJECT_ROOT>/.okstra/`. If an "
+    "un-enumerated file seems essential, record it under *Missing Information "
+    "or Assumptions* instead of reading it."
+)
+
+
 def worker_prompt_headers(
     *,
     project_root: Path,
@@ -22,18 +41,48 @@ def worker_prompt_headers(
 ) -> list[str]:
     """Render the team-contract worker prompt anchor headers."""
     prompt_path = _resolve_project_path(project_root, prompt_rel)
-    return [
+    headers = [
         f"**Project Root:** {project_root}",
         f"**Prompt History Path:** {prompt_rel}",
         f"**Result Path:** {result_rel}",
         f"Assigned worker prompt history path: {prompt_path}",
         f"**Worker Preamble Path:** {_worker_preamble_path()}",
-        f"**Coding preflight pack:** {_coding_preflight_pack_path(active_context)}",
+    ]
+    if _string_value(manifest.get("taskType")) == "implementation":
+        headers.append(
+            f"**Coding preflight pack:** {_coding_preflight_pack_path(active_context)}"
+        )
+    headers.extend([
         f"**Errors log path:** {_errors_log_path(project_root, manifest, active_context)}",
         (
             f"**Errors sidecar path:** "
             f"{_worker_errors_sidecar_path(project_root, manifest, active_context, worker_id)}"
         ),
+        READ_SCOPE_HEADER,
+    ])
+    if _string_value(manifest.get("taskType")) == "final-verification":
+        headers.extend(_final_verification_target_headers(active_context))
+    return headers
+
+
+def _final_verification_target_headers(
+    active_context: Mapping[str, Any],
+) -> list[str]:
+    target = active_context.get("verificationTarget")
+    if not isinstance(target, Mapping):
+        return []
+    fields = (
+        ("Worktree", "worktreePath"),
+        ("Verification scope", "scope"),
+        ("Verification base ref", "baseRef"),
+        ("Verification head ref", "headRef"),
+        ("Verification target path", "path"),
+        ("Verification target digest", "digest"),
+    )
+    return [
+        f"**{label}:** {_string_value(target.get(key))}"
+        for label, key in fields
+        if _string_value(target.get(key))
     ]
 
 

package/runtime/templates/reports/final-report.template.md

@@ -464,14 +464,14 @@ Carried-forward plan items retain their prior verdicts verbatim; each such item
 
 - Path (project-relative): `{{ releaseHandoff.sourceVerificationReport.path }}`
 - Quoted `Verdict Token` row from that report's `## 7.` table:
-  > {{ releaseHandoff.sourceVerificationReport.verdictTokenQuote }}
+  > {{ releaseHandoff.sourceVerificationReport.verdictTokenQuote | mdquote(2) }}
 
 ### 5.6.2 Feature Branch & Working-Tree State{% if t("releaseHandoff.branchStateAside") != "captured at run start" %} ({{ t("releaseHandoff.branchStateAside") }}){% endif %}
 
 - Feature branch: `{{ releaseHandoff.featureBranchState.branchName }}`
 - {{ t("releaseHandoff.gitStatusShortLabel") }}:
   ```
-  {{ releaseHandoff.featureBranchState.gitStatusShort }}
+  {{ releaseHandoff.featureBranchState.gitStatusShort | indent(2) }}
   ```
 - {{ t("releaseHandoff.existingPrLabel") }}: `{{ releaseHandoff.featureBranchState.existingPrUrl or '(none)' }}`
 
@@ -542,7 +542,7 @@ Carried-forward plan items retain their prior verdicts verbatim; each such item
 
 - Plan file (project-relative): `{{ implementation.approvedPlanReference.planFile }}`
 - Approval evidence:
-  > {{ implementation.approvedPlanReference.approvalEvidence }}
+  > {{ implementation.approvedPlanReference.approvalEvidence | mdquote(2) }}
 - {{ t("executionMeta.runExecutorWorktreePath") }}: `{{ implementation.approvedPlanReference.executorWorktreePath }}`
 - {{ t("executionMeta.runBaseRef") }}: `{{ implementation.approvedPlanReference.baseRefSha }}`
 
@@ -587,11 +587,11 @@ Carried-forward plan items retain their prior verdicts verbatim; each such item
 - Stage: `{{ implementation.stageSidecarEvidence.stageNumber }}` — {{ implementation.stageSidecarEvidence.stageTitle }}
 - Carry sidecar JSON:
   ```json
-  {{ implementation.stageSidecarEvidence.carryJson }}
+  {{ implementation.stageSidecarEvidence.carryJson | indent(2) }}
   ```
 - Appended `consumers.jsonl` rows:
 {% for row in implementation.stageSidecarEvidence.consumerRows -%}
-  > {{ row }}
+  > {{ row | mdquote(2) }}
 {% endfor %}
 
 ### 5.7.6 Validation Evidence
@@ -647,19 +647,19 @@ Carried-forward plan items retain their prior verdicts verbatim; each such item
 
 - Path (project-relative): `{{ finalVerification.sourceImplementationReport.path }}`
 - {{ t("evidenceMeta.commitListSummary") }}:
-  > {{ finalVerification.sourceImplementationReport.commitListQuote }}
+  > {{ finalVerification.sourceImplementationReport.commitListQuote | mdquote(2) }}
 - {{ t("evidenceMeta.diffSummaryQuote") }}:
-  > {{ finalVerification.sourceImplementationReport.diffSummaryQuote }}
+  > {{ finalVerification.sourceImplementationReport.diffSummaryQuote | mdquote(2) }}
 - {{ t("evidenceMeta.targetWorktreePath") }}: `{{ finalVerification.sourceImplementationReport.worktreePath }}`
 - {{ t("evidenceMeta.implementationBaseRef") }}: `{{ finalVerification.sourceImplementationReport.implementationBaseRef }}`
 - {{ t("evidenceMeta.capturedHeadSha") }}: `{{ finalVerification.sourceImplementationReport.capturedHeadSha }}`
 - {{ t("evidenceMeta.gitStatusAtRunStart") }}:
   ```
-  {{ finalVerification.sourceImplementationReport.gitStatusShort }}
+  {{ finalVerification.sourceImplementationReport.gitStatusShort | indent(2) }}
   ```
 - {{ t("evidenceMeta.gitDiffStatAtRunStart") }}:
   ```
-  {{ finalVerification.sourceImplementationReport.gitDiffStat }}
+  {{ finalVerification.sourceImplementationReport.gitDiffStat | indent(2) }}
   ```
 {% if verificationScope in ['whole-task', 'single-stage'] %}- {{ t("finalVerification.verificationScope") }}: `{{ verificationScope }}`
 {% endif %}{% if finalVerification.stageReports %}- {{ t("finalVerification.stageReportsLabel") }}: