okstra 0.141.3 → 0.143.0

package/runtime/python/okstra_ctl/paths.py

@@ -66,6 +66,19 @@ def _newest_report(reports_dir: Path) -> Optional[Path]:
     return max(found, key=lambda p: (p.stat().st_mtime, p.name))
 
 
+def _report_dirs(type_dir: Path, include_stages: bool) -> list[Path]:
+    """한 task-type 의 report 디렉터리들. flat 은 항상, stage-<N> 은 opt-in.
+
+    stage-isolated task-type(implementation / final-verification)만 stage 하위를
+    갖는다. `include_stages` 가 꺼져 있으면 flat `reports/` 만 돌려준다 —
+    `latest_under` 의 원래 범위이자 resume-clarification 이 의존하는 계약이다.
+    """
+    dirs = [type_dir / "reports"]
+    if include_stages and type_dir.name in _STAGED_TASK_TYPES:
+        dirs += sorted(type_dir.glob("stage-*/reports"))
+    return dirs
+
+
 def _project_root_of(task_root: Path) -> Optional[Path]:
     """canonical `<project>/.okstra/tasks/<g>/<t>` 일 때만 project root.
 
@@ -257,34 +270,48 @@ class RunRef:
         task_group: str,
         task_id: str,
         task_types: Optional[tuple[str, ...]] = None,
+        *,
+        include_stages: bool = False,
     ) -> Optional["RunRef"]:
         """여러 task-type 을 가로질러 최신 final-report 를 가리키는 ref.
 
         `task_types` 를 주지 않으면 runs/ 에 실제로 존재하는 모든 task-type 을
         훑는다. 비교 규칙은 `latest` 와 같다(mtime, 동률이면 basename).
+
+        `include_stages` 를 켜면 stage-isolated task-type 의 `stage-<N>/reports/`
+        도 함께 훑는다 — phase-cleanup 이 staged run 을 자동발견할 때 쓴다.
         """
         return cls.latest_under(
-            task_dir(project_root, task_group, task_id), task_types
+            task_dir(project_root, task_group, task_id),
+            task_types,
+            include_stages=include_stages,
         )
 
     @classmethod
     def latest_under(
-        cls, task_root: Path, task_types: Optional[tuple[str, ...]] = None
+        cls,
+        task_root: Path,
+        task_types: Optional[tuple[str, ...]] = None,
+        *,
+        include_stages: bool = False,
     ) -> Optional["RunRef"]:
         """`latest_across` 의 task_root 진입점.
 
         task-key 단축키/오타 진단을 이미 거쳐 task_root 를 손에 쥔 호출자
-        (bash resume-clarification)가 쓴다.
+        (bash resume-clarification)가 쓴다. 그 호출자는 언제나 flat 분석 phase 만
+        넘기므로 기본값(`include_stages=False`)이 그 범위를 그대로 보존한다.
         """
         runs_dir = runs_dir_of(task_root)
         if task_types is None:
             if not runs_dir.is_dir():
                 return None
             task_types = tuple(sorted(p.name for p in runs_dir.iterdir() if p.is_dir()))
-        candidates = [
-            found for task_type in task_types
-            if (found := _newest_report(runs_dir / task_type / "reports")) is not None
-        ]
+        candidates: list[Path] = []
+        for task_type in task_types:
+            for reports_dir in _report_dirs(runs_dir / task_type, include_stages):
+                found = _newest_report(reports_dir)
+                if found is not None:
+                    candidates.append(found)
         if not candidates:
             return None
         return cls.from_report_path(

package/runtime/python/okstra_ctl/phase_cleanup.py

@@ -0,0 +1,235 @@
+"""Phase-transition resource cleanup orchestrator.
+
+Reuses the existing pane-reclaim (okstra-trace-cleanup.sh) and teammate-reconcile
+(okstra-team-reconcile.sh) primitives; this module only decides tmux-vs-in-process
+mode, finds the prior run dir, and sequences the two scripts. It never
+re-implements pane kill or completion detection.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+from typing import Callable, Optional
+
+from okstra_project import StateError, parse_task_key
+
+from .paths import RunRef, okstra_home
+from .tmux import resolve_caller_pane, tmux_available
+
+_TRACE_SCRIPT = "okstra-trace-cleanup.sh"
+_RECONCILE_SCRIPT = "okstra-team-reconcile.sh"
+_MODE_TMUX = "tmux"
+_MODE_IN_PROCESS = "in-process"
+_RUNNER_TIMEOUT_SECONDS = 10
+
+
+def _recorded_lead_pane(prev_run_dir: Optional[Path]) -> Optional[str]:
+    """The pane the prior run's lead recorded, or None when unrecorded.
+
+    '<run_dir>/state/lead-pane.id' is written once at run start by the lead
+    adapter: a non-empty pane id means that run was inside a tmux pane, an empty
+    (0-byte) file means the run resolved to in-process. This on-disk fact
+    outlives the cleanup process's own context, which -- when okstra runs as a
+    daemon child -- can no longer walk its ancestry back to a pane.
+    """
+    if prev_run_dir is None:
+        return None
+    try:
+        return (prev_run_dir / "state" / "lead-pane.id").read_text().strip()
+    except OSError:
+        return None
+
+
+def resolve_mode(
+    *,
+    prev_run_dir: Optional[Path] = None,
+    pane_probe: Callable[[], str] = resolve_caller_pane,
+    tmux_probe: Callable[[], bool] = tmux_available,
+) -> str:
+    """'tmux' when the prior run had a pane to reclaim, else 'in-process'.
+
+    The prior run's recorded lead pane is authoritative: it captured that run's
+    tmux-ness at run start and survives a cleanup process that can no longer walk
+    its ancestry to a pane (daemon child). Only when nothing was recorded does
+    this fall back to the live ancestor-walk probe.
+    """
+    recorded = _recorded_lead_pane(prev_run_dir)
+    if recorded is not None:
+        return _MODE_TMUX if recorded else _MODE_IN_PROCESS
+    if pane_probe():
+        return _MODE_TMUX
+    if prev_run_dir is not None and tmux_probe():
+        # A prior run exists to reclaim from, but neither its recording nor the
+        # live probe could confirm tmux -- yet tmux is reachable. Surface the
+        # ambiguity instead of silently skipping pane reclaim.
+        sys.stderr.write(
+            "phase-cleanup: prior run has no recorded lead pane and no caller "
+            "pane could be resolved, but tmux is reachable; treating as "
+            "in-process and skipping pane reclaim\n"
+        )
+    return _MODE_IN_PROCESS
+
+
+def resolve_prev_run_dir(
+    *,
+    run_dir: Optional[str],
+    project_root: Path,
+    task_group: str,
+    task_id: str,
+) -> Optional[Path]:
+    """Explicit --run-dir wins; otherwise the newest completed run across phases.
+
+    Auto-discovery walks both FLAT runs/<type>/reports/ and staged
+    runs/<type>/stage-N/reports/ (implementation / final-verification), so a
+    staged prior run is found without an explicit run_dir; --run-dir still
+    overrides when a specific prior run is wanted.
+    """
+    if run_dir:
+        return Path(run_dir)
+    ref = RunRef.latest_across(
+        Path(project_root), task_group, task_id, include_stages=True
+    )
+    return ref.run_dir if ref is not None else None
+
+
+def _default_runner(cmd: list[str]) -> str:
+    # Cleanup must never block the next phase, so a spawn failure or a missing
+    # script degrades to "nothing to report" instead of propagating.
+    try:
+        proc = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=_RUNNER_TIMEOUT_SECONDS,
+        )
+        return proc.stdout
+    except (OSError, subprocess.SubprocessError):
+        return ""
+
+
+def _script_path(name: str) -> str:
+    # repo layout: scripts/<name>; installed layout: ~/.okstra/bin/<name>
+    candidates = [
+        Path(__file__).resolve().parent.parent / name,
+        okstra_home() / "bin" / name,
+    ]
+    for candidate in candidates:
+        if candidate.is_file():
+            return str(candidate)
+    return str(candidates[-1])  # a missing script is tolerated by _default_runner
+
+
+def _reclaim_panes(prev_run_dir: Path, runner: Callable[[list[str]], str]) -> int:
+    listing = runner(
+        [
+            _script_path(_TRACE_SCRIPT),
+            "--run-dir",
+            str(prev_run_dir),
+            "--reclaim-completed",
+            "--list",
+        ]
+    )
+    count = len([ln for ln in listing.splitlines() if ln.strip()])
+    runner(
+        [_script_path(_TRACE_SCRIPT), "--run-dir", str(prev_run_dir), "--reclaim-completed"]
+    )
+    return count
+
+
+def _dismissible_teammates(
+    project_root: Path,
+    runner: Callable[[list[str]], str],
+    fallback_team: str = "",
+) -> list[str]:
+    # The live team dir is keyed by the current session id, which Claude Code
+    # re-issues on resume/compaction; without the caller's label the resolver
+    # finds no live roster and reports nothing to dismiss.
+    cmd = [_script_path(_RECONCILE_SCRIPT), "--project-root", str(project_root)]
+    if fallback_team:
+        cmd += ["--fallback-team", fallback_team]
+    out = runner(cmd)
+    prefix = "dismissible-member:"
+    return [ln[len(prefix):].strip() for ln in out.splitlines() if ln.startswith(prefix)]
+
+
+def run_cleanup(
+    *,
+    mode: str,
+    prev_run_dir: Optional[Path],
+    project_root: Path,
+    runner: Callable[[list[str]], str] = _default_runner,
+    fallback_team: str = "",
+) -> dict:
+    # Cleanup is performed here (real pane kill + reconcile), not merely logged;
+    # the CLI's execution IS the enforcement (a caller cannot emit a "cleaned"
+    # line without this actually running).
+    panes = 0
+    if mode == _MODE_TMUX and prev_run_dir is not None:
+        panes = _reclaim_panes(prev_run_dir, runner)
+    teammates = _dismissible_teammates(project_root, runner, fallback_team)
+    return {"mode": mode, "panesReclaimed": panes, "dismissibleTeammates": teammates}
+
+
+def main(argv: list[str]) -> int:
+    ap = argparse.ArgumentParser(prog="okstra phase-cleanup")
+    ap.add_argument(
+        "--task-key",
+        help="finds the newest completed run across phases, including staged "
+             "(implementation / final-verification) stage-N runs",
+    )
+    ap.add_argument("--run-dir")
+    ap.add_argument("--project-root", required=True)
+    ap.add_argument(
+        "--fallback-team",
+        default="",
+        help="team label to resolve the roster from when the live session dir is "
+             "gone (session id re-issued by resume/compaction)",
+    )
+    ap.add_argument("--json", action="store_true")
+    args = ap.parse_args(argv)
+
+    task_group = task_id = ""
+    if args.task_key:
+        try:
+            _pid, task_group, task_id = parse_task_key(args.task_key)
+        except StateError as exc:
+            sys.stderr.write(f"phase-cleanup: {exc}\n")
+            return 0
+
+    prev = resolve_prev_run_dir(
+        run_dir=args.run_dir,
+        project_root=Path(args.project_root),
+        task_group=task_group,
+        task_id=task_id,
+    )
+    if prev is None and not args.run_dir:
+        sys.stderr.write(
+            "phase-cleanup: no prior run found for auto-discovery "
+            "(normal on a task's first phase); pass --run-dir to point at a "
+            "specific prior run\n"
+        )
+    result = run_cleanup(
+        mode=resolve_mode(prev_run_dir=prev),
+        prev_run_dir=prev,
+        project_root=Path(args.project_root),
+        fallback_team=args.fallback_team,
+    )
+    if args.json:
+        sys.stdout.write(json.dumps(result) + "\n")
+    else:
+        sys.stdout.write(f"mode: {result['mode']}\n")
+        sys.stdout.write(f"panes-reclaimed: {result['panesReclaimed']}\n")
+        sys.stdout.write(
+            "dismissible-teammates: "
+            + ", ".join(result["dismissibleTeammates"])
+            + "\n"
+        )
+    return 0  # cleanup never blocks the next phase
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/runtime/python/okstra_ctl/plan_items.py

@@ -189,12 +189,50 @@ def _extract_prep_items(
         )
 
 
+def _extract_variation_point_items(
+    planning: Mapping[str, Any], items: list[dict[str, Any]]
+) -> None:
+    analysis = planning.get("variationPointAnalysis")
+    if not isinstance(analysis, Mapping):
+        raise PlanItemContractError("variationPointAnalysis must be an object")
+    points = analysis.get("points") or []
+    if not analysis.get("hasMultipleImplementations") or not points:
+        _add_item(
+            items,
+            {
+                "id": "P-Var-0",
+                "subject": "No variation point declared",
+                "sourceSection": "5.5.11",
+                "ticketId": "",
+                "payload": _row_payload(dict(analysis)),
+            },
+        )
+        return
+    for index, point in enumerate(points, start=1):
+        if not isinstance(point, Mapping):
+            raise PlanItemContractError(
+                "variationPointAnalysis.points row must be an object"
+            )
+        _add_item(
+            items,
+            {
+                "id": f"P-Var-{index}",
+                "subject": _non_empty_string(point.get("behavior"))
+                or f"variation point {index}",
+                "sourceSection": "5.5.11",
+                "ticketId": "",
+                "payload": _row_payload(dict(point)),
+            },
+        )
+
+
 def extract_plan_items(implementation_planning: Mapping[str, Any]) -> list[dict[str, Any]]:
     """Return deterministic, lossless P-* items in contract order."""
     if not isinstance(implementation_planning, Mapping):
         raise PlanItemContractError("implementationPlanning must be an object")
     items = _extract_standard_items(implementation_planning)
     _extract_prep_items(implementation_planning, items)
+    _extract_variation_point_items(implementation_planning, items)
     return items
 
 

package/runtime/python/okstra_ctl/run.py

@@ -102,6 +102,10 @@ from .worktree import (
     WorktreeProvision,
     provision_task_worktree,
 )
+from .brief_frontmatter import (
+    has_reporter_confirmation_contract,
+    read_brief_frontmatter,
+)
 
 # Frontmatter approval-flag matcher.
 #
@@ -854,6 +858,7 @@ class _ResolvedAssets:
     final_report_template: Path
     lead_contract: Path
     run_validator: Path
+    brief_validator: Path
 
 
 def _resolve_runtime_assets(workspace_root: Path, inp: PrepareInputs) -> _ResolvedAssets:
@@ -877,7 +882,14 @@ def _resolve_runtime_assets(workspace_root: Path, inp: PrepareInputs) -> _Resolv
     )
     lead_contract = workspace_root / "prompts" / "lead" / "okstra-lead-contract.md"
     run_validator = workspace_root / "validators" / "validate-run.py"
-    for required in (task_index_template, final_report_template, run_validator, lead_contract):
+    brief_validator = workspace_root / "validators" / "validate-brief.py"
+    for required in (
+        task_index_template,
+        final_report_template,
+        run_validator,
+        brief_validator,
+        lead_contract,
+    ):
         if not required.is_file():
             raise PrepareError(
                 f"required okstra template or lead contract missing: {required}.{_INSTALL_HINT}"
@@ -889,12 +901,49 @@ def _resolve_runtime_assets(workspace_root: Path, inp: PrepareInputs) -> _Resolv
         final_report_template=final_report_template,
         lead_contract=lead_contract,
         run_validator=run_validator,
+        brief_validator=brief_validator,
     )
 
 
+def _validate_task_brief_preflight(
+    project_root: Path,
+    brief_path: Path,
+    validator_path: Path,
+) -> None:
+    """Validate canonical briefs before any prepare-time side effects."""
+    frontmatter = read_brief_frontmatter(brief_path)
+    if not has_reporter_confirmation_contract(frontmatter):
+        return
+
+    proc = _subprocess.run(
+        [
+            sys.executable,
+            str(validator_path),
+            str(brief_path),
+            "--briefs-root",
+            str(project_root / ".okstra" / "briefs"),
+        ],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if proc.returncode != 0:
+        detail = " ".join(
+            line.strip()
+            for output in (proc.stdout, proc.stderr)
+            for line in output.splitlines()
+            if line.strip()
+        )
+        raise PrepareError(f"task brief failed validation: {detail}")
+    if frontmatter["reporter-confirmations"] == "pending":
+        raise PrepareError(
+            "task brief reporter-confirmations is pending; rerun okstra-brief-gen "
+            "Step 6.5 before starting error-analysis"
+        )
+
+
 def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
-    """project_root/brief 존재와 task-type 별 입력 의미(plan 승인·stage·clarification)
-    를 검증하고, implementation 일 때 stage map 을 파싱해 돌려준다 (그 외엔 빈 리스트)."""
+    """Validate pure prepare inputs and return a final-verification stage map."""
     if not project_root.is_dir():
         raise PrepareError(f"project root not found: {project_root}")
     if inp.stages and inp.task_type != "release-handoff":
@@ -911,41 +960,14 @@ def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
         raise PrepareError(f"task brief not found: {inp.brief_path}")
     ctx_stage_map: list = []
     # implementation 과 final-verification 은 둘 다 승인된 plan 의 Stage Map 을
-    # 입력으로 받는다(전자는 실행 scope, 후자는 검증 scope). plan-presence +
-    # stage-map 파싱은 공유하고, frontmatter 승인/option 주입/구조 검증 같은
-    # implementation 전용 단계만 따로 게이트한다.
+    # 입력으로 받는다(전자는 실행 scope, 후자는 검증 scope).
     if inp.task_type in ("implementation", "final-verification"):
         if not inp.approved_plan_path:
             raise PrepareError(
                 f"task-type {inp.task_type} requires "
                 "--approved-plan <path-to-final-report.md>"
             )
-        if inp.task_type == "implementation":
-            # --approve / --implementation-option 은 공유 approved-plan 파일에
-            # read-modify-write 한다. 같은 task-key 의 동시 stage run 둘이 둘 다
-            # 이 플래그를 주면 후발 write 가 선발의 frontmatter 변경을 덮어쓴다
-            # (lost update). 두 mutation 을 per-task-key 락으로 직렬화한다.
-            if inp.approve_plan_ack or inp.implementation_option:
-                with worktree_provision_mutex(
-                    okstra_home(), inp.project_id,
-                    slugify(inp.task_group), slugify(inp.task_id),
-                ):
-                    if inp.approve_plan_ack:
-                        # 사용자가 직접 `--approve` 를 입력한 행위 자체를 승인 의사로
-                        # 모델링한다. frontmatter approved 를 true 로 toggle 한 뒤
-                        # 동일한 검증 경로(`_validate_approved_plan`)를 통과시킨다.
-                        _apply_cli_approval(inp.approved_plan_path)
-                    if inp.implementation_option:
-                        # 유저가 고른 Option Candidate 이름을 approved-plan
-                        # frontmatter 의 `implementation-option:` 라인에 기록한다.
-                        # 빈 값이면 implementation 이 plan 의 `Recommended Option`
-                        # 으로 폴백하므로 호출하지 않는다.
-                        _apply_cli_implementation_option(
-                            inp.approved_plan_path, inp.implementation_option
-                        )
-            _validate_approved_plan(inp.approved_plan_path)
-            _validate_stage_structure(inp.approved_plan_path)
-        else:
+        if inp.task_type == "final-verification":
             # final-verification 에서 --approve / --implementation-option 은
             # 의미가 없다 (승인은 implementation 진입 시 이미 끝났다).
             if inp.approve_plan_ack:
@@ -958,7 +980,7 @@ def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
                     "--implementation-option is only meaningful with --task-type "
                     "implementation and --approved-plan <path>"
                 )
-        ctx_stage_map = _parse_stage_map_into_ctx(inp.approved_plan_path)
+            ctx_stage_map = _parse_stage_map_into_ctx(inp.approved_plan_path)
     else:
         if inp.approve_plan_ack:
             # implementation 외 task-type 에서 `--approve` 는 의미가 없다. 사용자에게
@@ -988,6 +1010,24 @@ def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
     return ctx_stage_map
 
 
+def _prepare_implementation_approved_plan(inp: PrepareInputs) -> list:
+    """Apply approved-plan inputs only after canonical brief preflight succeeds."""
+    if inp.approve_plan_ack or inp.implementation_option:
+        with worktree_provision_mutex(
+            okstra_home(), inp.project_id,
+            slugify(inp.task_group), slugify(inp.task_id),
+        ):
+            if inp.approve_plan_ack:
+                _apply_cli_approval(inp.approved_plan_path)
+            if inp.implementation_option:
+                _apply_cli_implementation_option(
+                    inp.approved_plan_path, inp.implementation_option
+                )
+    _validate_approved_plan(inp.approved_plan_path)
+    _validate_stage_structure(inp.approved_plan_path)
+    return _parse_stage_map_into_ctx(inp.approved_plan_path)
+
+
 def _collect_handoff_source_report_rows(
     rows: list, nums: list,
 ) -> list:
@@ -2072,6 +2112,14 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     task_index_template = assets.task_index_template
     final_report_template = assets.final_report_template
     ctx_stage_map = _validate_prepare_inputs(project_root, inp)
+    if inp.task_type != "release-handoff":
+        _validate_task_brief_preflight(
+            project_root,
+            inp.brief_path,
+            assets.brief_validator,
+        )
+    if inp.task_type == "implementation":
+        ctx_stage_map = _prepare_implementation_approved_plan(inp)
 
     # release-handoff: 검증 보고서 인용 input 문서를 생성해 brief 자리에 채운다.
     # 이후의 모든 brief 소비 경로(material/instruction-set 복사)는 그대로 동작한다.

package/runtime/python/okstra_ctl/schema_excerpt.py

@@ -1,8 +1,9 @@
 """Build a task-type-scoped excerpt of the final-report schema.
 
 The full schema (``schemas/final-report-v1.0.schema.json``) carries the
-deliverable property blocks for ALL task-types (``implementationPlanning``,
-``releaseHandoff``, ``implementation``, ``finalVerification``) plus a
+deliverable property blocks for ALL task-types (``errorAnalysis``,
+``implementationPlanning``, ``releaseHandoff``, ``implementation``,
+``finalVerification``) plus a
 ``$defs`` library (~38% of the file) shared across them. A single run only
 authors ONE task-type's data.json, so the report-writer worker only needs
 the common structure + its own task-type's block + the ``$defs`` those
@@ -24,10 +25,11 @@ import json
 import re
 
 # task-type → the per-type deliverable property key it owns. task-types
-# absent from this map (requirements-discovery, error-analysis,
+# absent from this map (requirements-discovery,
 # improvement-discovery) have no per-type block; their excerpt keeps only
 # the common properties.
 _TASK_TYPE_PROPERTY = {
+    "error-analysis": "errorAnalysis",
     "implementation-planning": "implementationPlanning",
     "release-handoff": "releaseHandoff",
     "implementation": "implementation",

package/runtime/python/okstra_ctl/wizard.py

@@ -30,6 +30,7 @@ from pathlib import Path
 from typing import Any, Callable, Optional
 
 from okstra_ctl.ids import slugify_task_segment
+from okstra_ctl.brief_frontmatter import read_brief_frontmatter
 from okstra_ctl.models import (
     PROVIDER_MAPPINGS,
     UnknownModelError,
@@ -155,49 +156,6 @@ _RECENT_PREFIX = "__recent:"
 _REPORT_PREFIX = "__report:"
 _BRIEF_PREFIX = "__brief:"
 
-# Lines of `key: value` we pull from a brief markdown frontmatter. The
-# parser is intentionally lightweight (no yaml dep) and tolerant — a
-# malformed brief returns an empty dict.
-_BRIEF_FRONTMATTER_LINE_RE = re.compile(r"^([a-zA-Z0-9_\-]+)\s*:\s*(.*)$")
-
-
-def _parse_brief_frontmatter(path: Path) -> dict[str, str]:
-    """Read the YAML-style frontmatter at the top of a brief markdown file
-    and return a flat ``{key: value}`` map.
-
-    Returns ``{}`` if the file is unreadable, has no frontmatter, or the
-    frontmatter is malformed. Comments (``# ...``) and quoted values are
-    stripped. Placeholder values like ``<task-group>`` are kept verbatim;
-    callers decide whether to treat them as a real suggestion.
-    """
-    try:
-        text = path.read_text(encoding="utf-8")
-    except OSError:
-        return {}
-    if not text.startswith("---"):
-        return {}
-    lines = text.splitlines()
-    if not lines or lines[0].strip() != "---":
-        return {}
-    out: dict[str, str] = {}
-    for line in lines[1:]:
-        if line.strip() == "---":
-            break
-        # strip trailing inline comment
-        comment_idx = line.find("#")
-        if comment_idx >= 0:
-            line = line[:comment_idx]
-        m = _BRIEF_FRONTMATTER_LINE_RE.match(line.strip())
-        if not m:
-            continue
-        key, val = m.group(1), m.group(2).strip()
-        # strip matching quotes
-        if (len(val) >= 2 and val[0] == val[-1] and val[0] in ("'", '"')):
-            val = val[1:-1]
-        out[key] = val
-    return out
-
-
 def _looks_like_template_placeholder(value: str) -> bool:
     """Treat ``<task-group>``, ``<...>``, empty strings, and ``self`` as
     non-suggestions. Anything else (a real slug-like value) is honored."""
@@ -223,7 +181,7 @@ def _brief_suggestions(path: Path) -> tuple[str, str]:
     A brief without frontmatter, or with placeholder values, yields two
     empty strings — callers fall back to plain-text input.
     """
-    fm = _parse_brief_frontmatter(path)
+    fm = read_brief_frontmatter(path)
     tg_raw = fm.get("task-group", "")
     bid_raw = fm.get("brief-id", "")
     tg = "" if _looks_like_template_placeholder(tg_raw) else tg_raw
@@ -2402,6 +2360,15 @@ def _submit_handoff_stage_pick(state: WizardState, value: str) -> Optional[str]:
         stages=state.handoff_stages)
 
 
+def _same_file(a: Path, b_str: str) -> bool:
+    """Whether two paths resolve to the same file. False when either path
+    cannot be resolved (missing intermediate dir, permission, etc.)."""
+    try:
+        return a.resolve() == Path(b_str).resolve()
+    except OSError:
+        return False
+
+
 def _suggest_latest_final_report(state: WizardState) -> str:
     """clarification carry-in 으로 추천할 직전 final-report 의 relpath.
 
@@ -2436,6 +2403,13 @@ def _suggest_latest_final_report(state: WizardState) -> str:
         best = _newest("*/reports/final-report-*.md")
     if best is None:
         return ""
+    # The approved plan is already wired via --approved-plan. On the first run
+    # of an approved-plan consuming phase (final-verification / implementation)
+    # the newest cross-phase report IS that plan, so the fallback would
+    # re-recommend it as a clarification answer — injecting it twice, read as a
+    # user clarification it is not. Never carry the approved plan back in here.
+    if state.approved_plan_path and _same_file(best, state.approved_plan_path):
+        return ""
     try:
         return str(best.relative_to(Path(state.project_root)))
     except ValueError: