okstra 0.141.3 → 0.142.0

package/runtime/python/okstra_ctl/clarification_items.py

@@ -27,7 +27,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Optional
 
-from okstra_ctl.md_table import is_separator_row, split_pipe_row
+from okstra_ctl.md_table import is_separator_row, split_pipe_row, to_cell_text
 
 
 # The final-report renderer (render_final_report.py:_inject_anchors) appends a
@@ -372,6 +372,24 @@ def user_response_sidecars(source: Path) -> list[Path]:
     )
 
 
+def _sidecar_answers(source: Path) -> dict[str, str]:
+    """`user-responses/` 사이드카들의 답변을 `{clarification-id: value}` 로 모은다.
+
+    같은 id 가 여러 사이드카에 나오면 이름순 마지막(최신 seq)이 이긴다. `value`
+    가 빈 항목은 담지 않는다. `user_response` 를 지연 import 해 순환 참조를 피한다.
+    """
+    from okstra_ctl.user_response import parse_user_response_entries
+
+    answers: dict[str, str] = {}
+    for sidecar in user_response_sidecars(source):
+        for entry in parse_user_response_entries(
+            sidecar.read_text(encoding="utf-8")
+        ):
+            if entry.value:
+                answers[entry.response_id] = entry.value
+    return answers
+
+
 def attached_user_responses_section(source: Path) -> str:
     """`source` 형제 `user-responses/` 사이드카만 모은 `# Attached User Responses`
     섹션 본문. 사이드카 부재 시 빈 문자열.
@@ -410,19 +428,29 @@ def clarification_response_with_sidecars(source: Path) -> str:
     """
     text = source.read_text(encoding="utf-8")
     section = attached_user_responses_section(source)
-    body = _clarification_carry_body(source, text)
+    answers = _sidecar_answers(source)
+    body = _clarification_carry_body(source, text, answers)
     if not section:
         return body
     return body.rstrip("\n") + "\n\n---\n\n" + section
 
 
-def _clarification_carry_body(source: Path, text: str) -> str:
-    """final-report 소스는 §1 + 원문 포인터로 좁히고, 그 외는 원문 그대로."""
+def _clarification_carry_body(
+    source: Path, text: str, answers: dict[str, str]
+) -> str:
+    """final-report 소스는 §1 + 원문 포인터로 좁히고, 그 외는 원문 그대로.
+
+    §1 이 있으면 사이드카 답변을 그 표의 `User input` 열에 병합해, 답이 표 안에
+    자리하도록 한다(파일 헤더가 선언하는 "답은 User input 열에" 계약을 실제로
+    참으로 만든다)."""
     slice_ = _section_1_slice(text)
     if slice_ is None:
         return text
     heading = SECTION_HEADING_PATTERN.search(text)
     assert heading is not None  # _section_1_slice returned a slice
+    section_body = slice_.rstrip()
+    if answers:
+        section_body = _reconcile_user_input(section_body, answers)
     return (
         "# Clarification Response (carry-in)\n\n"
         f"- Source report: `{source}`\n"
@@ -430,5 +458,71 @@ def _clarification_carry_body(source: Path, text: str) -> str:
         "section; the report itself is read from the path above when a phase "
         "needs it. Do not re-read the source report to find the answers — they "
         "are in the `User input` column below.\n\n"
-        f"{heading.group(0)}\n{slice_.rstrip()}\n"
+        f"{heading.group(0)}\n{section_body}\n"
     )
+
+
+# The final-report renderer writes `Status: open` / `Status: answered` unquoted
+# in the stacked meta cell; only those two are unresolved. Resolve in place so
+# the meta cell's other fields (ID, Ticket, Kind, Blocks) are left untouched.
+_STATUS_RESOLVE_RE = re.compile(r"(Status:\s*)(?:open|answered)\b", re.IGNORECASE)
+
+
+def _locate_user_input_column(lines: list[str]) -> tuple[int, int]:
+    """§1 데이터 표의 헤더 줄 인덱스와 `User input` 열 인덱스. 표가 없으면 (-1, -1)."""
+    for idx, line in enumerate(lines):
+        if not line.lstrip().startswith("|"):
+            continue
+        cells = [c.lower() for c in _split_pipe_row(line)]
+        if "user input" in cells and any(c.startswith("statement") for c in cells):
+            return idx, cells.index("user input")
+    return -1, -1
+
+
+def _reconcile_row(line: str, ui_col: int, answers: dict[str, str]) -> str:
+    """답이 있고 open/answered 이며 `User input` 칸이 빈 행이면 답을 채우고 Status 를
+    resolved 로 바꾼 줄을, 그 외에는 원본 줄을 그대로 돌려준다. 이미 채워진 칸은
+    표에 든 값이 정본이므로 덮어쓰지 않는다.
+
+    판정은 앵커/백틱을 벗긴 셀(`_split_pipe_row`)로 — 그래야 `_meta_id` 가 스크롤
+    앵커의 소문자 slug 대신 진짜 대문자 ID 를 읽는다. 재조립은 원본 셀
+    (`split_pipe_row`)로 해서 앵커를 보존한다."""
+    norm = _split_pipe_row(line)
+    item = parse_meta_cell(norm[0]) if norm else None
+    if item is None or item.row_id not in answers:
+        return line
+    if item.status not in UNRESOLVED_STATUSES:
+        return line
+    raw = split_pipe_row(line)
+    if not (0 <= ui_col < len(raw) and raw[ui_col] == ""):
+        return line
+    raw[ui_col] = answers[item.row_id]
+    raw[0] = _STATUS_RESOLVE_RE.sub(r"\1resolved", raw[0])
+    return "| " + " | ".join(to_cell_text(c) for c in raw) + " |"
+
+
+def _reconcile_user_input(section: str, answers: dict[str, str]) -> str:
+    """§1 표에서 사이드카 답이 있는 미해결 행의 빈 `User input` 칸을 답으로 채우고
+    Status 를 resolved 로 바꾼 §1 본문을 돌려준다.
+
+    답의 정본 위치를 §1 표 안으로 옮긴다 — 표만 읽는 승인 게이트·프롬프트
+    빌더·검증 워커가 모두 답을 보게 하려는 것. 사이드카는 §1 표 밖 별도 섹션에만
+    있어서 표만 신뢰하는 소비자는 그 답을 놓쳤다."""
+    lines = section.splitlines()
+    header_idx, ui_col = _locate_user_input_column(lines)
+    if header_idx < 0:
+        return section
+    out = list(lines)
+    body = False
+    for i in range(header_idx + 1, len(lines)):
+        line = lines[i]
+        if not line.lstrip().startswith("|"):
+            if body:
+                break
+            continue
+        if is_separator_row(line):
+            body = True
+            continue
+        if body:
+            out[i] = _reconcile_row(line, ui_col, answers)
+    return "\n".join(out)

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/wizard.py

@@ -2402,6 +2402,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 +2445,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:

package/runtime/python/okstra_ctl/worker_heartbeat.py

@@ -33,17 +33,27 @@ SINGLE_WRITE_STAGES = frozenset({
 })
 SINGLE_WRITE_MAX_GAP_SECONDS = 20 * 60 + 60
 
+# report-writer 가 도구 호출 없이 모든 입력을 정독(required-reading-complete)하거나
+# 종합(synthesis-start)하는 구간. 그 사이에는 `in-stage:` 라인조차 append 할 수 없어
+# 5분 예산으로는 살아 있는 워커가 stalled 로 판정된다 (실측: synthesis-start gap 41건
+# 중 24%가 5분+60s 초과, 최대 14.9분). 단일 Write 만큼 길지는 않으므로 15분 예산.
+SYNTHESIS_STAGES = frozenset({
+    "required-reading-complete",
+    "synthesis-start",
+})
+SYNTHESIS_MAX_GAP_SECONDS = 15 * 60 + 60
+
 
 def max_gap_seconds_after(stage: str) -> int:
     """*stage* 를 알린 뒤 다음 하트비트까지 허용되는 최대 공백(초).
 
     간격이 재는 것은 직전에 선언된 단계의 작업 시간이므로, 예산은 언제나
     구간을 *여는* 단계에서 고른다."""
-    return (
-        SINGLE_WRITE_MAX_GAP_SECONDS
-        if stage in SINGLE_WRITE_STAGES
-        else HEARTBEAT_MAX_GAP_SECONDS
-    )
+    if stage in SINGLE_WRITE_STAGES:
+        return SINGLE_WRITE_MAX_GAP_SECONDS
+    if stage in SYNTHESIS_STAGES:
+        return SYNTHESIS_MAX_GAP_SECONDS
+    return HEARTBEAT_MAX_GAP_SECONDS
 
 
 @dataclass(frozen=True)

package/runtime/python/okstra_ctl/workflow.py

@@ -87,7 +87,7 @@ PHASE_RULES: dict[str, dict[str, str]] = {
             '  - validation evidence: actual stdout/stderr and exit code for every pre / mid / post command from the plan (no paraphrased "tests pass")\n'
             "  - TDD evidence for TDD-applicable steps: failing-test output before implementation commit and passing-test output after, with framing SHAs\n"
             "  - per-verifier sections for every verifier in the resolved roster (`Claude verifier`, `Codex verifier`, plus `Antigravity verifier` when opted in) with independent verdict (PASS / CONCERNS / FAIL) and cited diff snippets; dissent is preserved by `Claude lead`\n"
-            "  - rollback verification (revert SHA reachable, feature flag toggle works, migration down step valid; dry-run preferred)\n"
+            "  - rollback verification (advisory, never blocks — record the revert path for a human; `result` is ok / not-applicable / advisory — human-run)\n"
             "  - routing recommendation for `final-verification` (ready / needs new error-analysis or planning loop)"
         ),
     },

package/runtime/python/okstra_project/resolver.py

@@ -83,6 +83,31 @@ def resolve_project_root(*, explicit_root: str = "",
         "프로젝트 루트 또는 그 하위에서 실행하거나, git 작업 트리 안에서 실행해 주십시오.)")
 
 
+_ARCHITECTURE_STYLES = frozenset({"hexagonal", "layered", "none"})
+
+
+def resolve_architecture(project_root: Path | str) -> str:
+    """Return the declared architecture style, else ``"none"``.
+
+    Mirrors resolve_build_tool_tokens: any read/parse failure or an
+    unrecognised value falls back to the neutral ``"none"`` so an
+    unconfigured project keeps the layer-1 behaviour only.
+    """
+    try:
+        payload = json.loads(project_json_path(Path(project_root)).read_text(encoding="utf-8"))
+    # ValueError covers json.JSONDecodeError and UnicodeDecodeError alike — a
+    # project.json hand-saved in a non-UTF-8 encoding must fall back, not raise.
+    except (OSError, ValueError):
+        return "none"
+    if not isinstance(payload, dict):
+        return "none"
+    architecture = payload.get("architecture")
+    style = architecture.get("style") if isinstance(architecture, dict) else None
+    if not isinstance(style, str):
+        return "none"
+    return style if style in _ARCHITECTURE_STYLES else "none"
+
+
 def upsert_project_json(project_root: Path, project_id: str, *,
                          now: Optional[str] = None) -> dict:
     """project.json 을 읽거나 새로 만든다.