okstra 0.178.0 → 0.179.0

package/runtime/python/okstra_ctl/session_transcript.py

@@ -0,0 +1,89 @@
+"""워커 세션 기록.
+
+한 줄에 시각·화자·본문 셋을 담는다. 나중에 리드가 같은 파일에 쓰면 화자만
+달라지므로, 지금 형식을 정해 두면 그때 파일이 바뀌지 않는다.
+"""
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+from typing import Callable
+
+OKSTRA = "okstra"
+_SPEAKER_WIDTH = 14
+
+# 파일 사본이 담는 워커 진행 줄의 상한. 진행은 워커 출력의 부피가 몰리는
+# 자리다 — 파일 하나만 읽는 디스패치도 킬로바이트 단위 도구 에코를 남기고,
+# 관측된 사이드카는 8MB 에 이르러 프로젝트의 `.okstra/` 바이트를 지배했다.
+# 상한은 블록이 아니라 run 전체에 건다: 블록 경계는 공급자 자신의 어휘이고
+# 이 기록기는 그것을 모른다. 그 대가로 아주 긴 run 은 표본이 아니라 앞부분을
+# 남기며, 생략 표시가 그 사실을 드러낸다.
+LOG_LINE_CAP = 5000
+_ELISION_NOTICE_EVERY = 500
+
+
+def _now() -> str:
+    return datetime.now().strftime("%H:%M:%S")
+
+
+class SessionTranscript:
+    """워커 한 명의 세션 기록. 화면 출력도 함께 맡는다."""
+
+    def __init__(
+        self,
+        path: Path,
+        *,
+        live: bool,
+        clock: Callable[[], str] = _now,
+    ) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        self._file = path.open("w", encoding="utf-8")
+        self._live = live
+        self._clock = clock
+        self._archived = 0
+        self._elided = 0
+
+    def write(self, speaker: str, line: str, *, capped: bool = True) -> None:
+        """한 줄을 화면과 기록에 남긴다.
+
+        ``capped=False`` 는 상한을 넘겨도 반드시 파일에 남길 줄이다 — 워커의
+        결론과 okstra 자신의 기록이 그렇다. 잘린 도구 에코는 세부를 잃지만
+        잘린 결론은 사후 분석 전체를 잃는다.
+        """
+        # 패딩이 본문 앞 공백을 겸한다. 뒤에 공백을 한 칸 더 넣으면
+        # `[worker:grok]`(13칸) 줄이 두 칸이 되고 `[okstra]` 정렬이 깨진다.
+        label = f"[{speaker}]".ljust(_SPEAKER_WIDTH)
+        row = f"{self._clock()} {label}{line}".rstrip()
+        # 화면은 상한과 무관하다. 사람이 보고 있는 것을 잘라 낼 이유가 없다.
+        if self._live:
+            print(row, flush=True)
+        if not capped:
+            self._append(row)
+            return
+        if self._archived < LOG_LINE_CAP:
+            self._archived += 1
+            self._append(row)
+            return
+        self._elided += 1
+        # 끝에서 한 번이 아니라 주기적으로 남긴다. 로그를 tail 하는 사람이
+        # run 이 아직 진행 중임을 봐야 하고, 멈춘 파일과 구별되어야 한다.
+        if self._elided % _ELISION_NOTICE_EVERY == 0:
+            self._note_elision()
+
+    def note(self, line: str) -> None:
+        """okstra 자신이 남기는 줄. 워커의 말과 섞이되 화자로 구분된다."""
+        self.write(OKSTRA, line, capped=False)
+
+    def close(self) -> None:
+        if self._elided % _ELISION_NOTICE_EVERY:
+            self._note_elision()
+        self._file.close()
+
+    def _append(self, row: str) -> None:
+        self._file.write(row + "\n")
+        self._file.flush()
+
+    def _note_elision(self) -> None:
+        self._append(
+            f"  [okstra log-cap] {self._elided} progress line(s) elided"
+        )

package/runtime/python/okstra_ctl/stage_ledger.py

@@ -0,0 +1,72 @@
+"""계획 저작 쪽에 넘길 Stage 원장을 디스크에서 조립한다.
+
+계획을 세우는 쪽은 지금 어느 stage 가 이미 구현됐는지 모른 채 계획을 쓴다.
+이 모듈은 그 사실만 모아 준다 — 무엇을 계획해야 하는지는 말하지 않는다.
+
+판정은 소유하지 않는다. 상태 어휘와 lifecycle 판정은 stage_targets 가, stage
+map 의 출처 판정은 stage_map.load_task_stage_map 이 소유한다. 여기서는 둘을
+잇고 직렬화만 한다.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from .consumers import read_stage_consumer_state
+from .paths import RunRef
+from .stage_map import StageMapError, load_task_stage_map
+from .stage_targets import stage_lifecycle_snapshot_from_state
+from .task_target import infer_project_root
+
+
+def build_stage_ledger(task_root: Path) -> dict[str, Any] | None:
+    """이 task 의 Stage 원장. 계획 리포트가 아직 없으면 ``None``.
+
+    ``None`` 과 빈 리스트를 구분한다 — 계획이 없는 첫 run 과 stage 가 하나도
+    없는 계획은 저작 쪽에 다른 뜻이다.
+    """
+    task_root = Path(task_root)
+    try:
+        snapshot = load_task_stage_map(task_root, {})
+    except StageMapError:
+        # 계획 출처가 충돌하거나 읽히지 않는 경우. 원장을 추측해 싣느니 싣지
+        # 않는다 — 틀린 원장은 없는 원장보다 나쁘다.
+        return None
+    if snapshot.state != "ready" or not snapshot.stages:
+        return None
+
+    plan_run_root = RunRef.from_task_root(
+        task_root, "implementation-planning"
+    ).run_dir
+    # carry 사이드카에서 done 행을 복구한다. implementation prep 이 하는 것과
+    # 같은 멱등 복구이며, 이걸 건너뛰면 크래시 창에 걸린 완료 stage 가 원장에
+    # 미완으로 실려 저작 쪽이 이미 구현된 stage 를 다시 계획한다.
+    state = read_stage_consumer_state(plan_run_root, recover_from_carry=True)
+    lifecycle = stage_lifecycle_snapshot_from_state(snapshot.stages, state)
+    return {
+        "sourcePlan": _project_relative(task_root, snapshot.source_plan_path),
+        "stages": lifecycle.ledger_records(),
+    }
+
+
+def render_stage_ledger(ledger: dict[str, Any] | None) -> str:
+    """packet 에 실릴 JSON 본문. 원장이 없으면 빈 문자열."""
+    if not ledger:
+        return ""
+    return json.dumps(ledger, ensure_ascii=False, indent=2)
+
+
+def _project_relative(task_root: Path, source_plan_path: str) -> str:
+    """절대 경로를 프로젝트 상대로 낮춘다.
+
+    packet 은 워커에게 그대로 전달된다. 절대 경로를 실으면 실행 머신의
+    디렉터리 구조가 프롬프트에 박히고, 다른 머신에서 재현할 때 어긋난다.
+    """
+    if not source_plan_path:
+        return ""
+    project_root = infer_project_root(task_root)
+    try:
+        return str(Path(source_plan_path).relative_to(project_root))
+    except ValueError:
+        return source_plan_path

package/runtime/python/okstra_ctl/stage_map.py

@@ -341,47 +341,46 @@ def _parse_schema_v2_stage_map(
     return stages
 
 
-def parse_stage_map_file(markdown_path: Path) -> list[StageMapStage]:
-    """Read one report's Stage Map, whichever schema wrote it.
-
-    THE entry point for every caller. A schema-v2 report carries the stage map
-    in its `.data.json` sidecar and has no `## 5.5 Stage Map` section at all, so
-    a caller that parses the markdown directly works only against v1 reports —
-    which is how v2 support landed on one call site and left five reading a
-    section that modern reports do not have.
+def parse_stage_map_file(plan_path: Path) -> list[StageMapStage]:
+    """Read one report's Stage Map from the report record, or v1 markdown.
+
+    `--approved-plan` now passes the `.data.json` record. A `.md` path is the
+    schema-v1 reading-copy form and is parsed as markdown only — this function
+    does not look for a sibling record.
     """
-    resolved = Path(markdown_path).resolve()
-    data_path = resolved.with_suffix(".data.json")
-    if not data_path.exists():
-        return _parse_stage_map_markdown(resolved)
-    try:
-        data = json.loads(data_path.read_text(encoding="utf-8"))
-    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
-        raise StageMapError("stage_map", str(exc), str(data_path)) from exc
-    if not isinstance(data, dict):
-        raise StageMapError(
-            "stage_map", "structured report must be an object", str(data_path)
-        )
-    if data.get("schemaVersion") != "2.0":
-        return _parse_stage_map_markdown(resolved)
-    return _parse_schema_v2_stage_map(data, str(data_path))
+    from .final_report_paths import is_report_record_path
+
+    resolved = Path(plan_path).resolve()
+    if is_report_record_path(resolved):
+        try:
+            data = json.loads(resolved.read_text(encoding="utf-8"))
+        except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+            raise StageMapError("stage_map", str(exc), str(resolved)) from exc
+        if not isinstance(data, dict):
+            raise StageMapError(
+                "stage_map", "structured report must be an object", str(resolved)
+            )
+        return _parse_schema_v2_stage_map(data, str(resolved))
+    return _parse_stage_map_markdown(resolved)
 
 
-def schema_v2_report(markdown_path: Path) -> dict[str, Any]:
-    """The schema-v2 sidecar as a whole, `{}` for a v1 report.
+def schema_v2_report(plan_path: Path) -> dict[str, Any]:
+    """The schema-v2 report record as a whole, `{}` for a v1 markdown path.
 
     Public because every caller that must branch on report schema needs it —
     including `validators/validate-implementation-plan-stages.py`, which is a
     separate process and cannot reach a private helper without copying the
     sidecar-detection rule and letting the two drift.
     """
-    data_path = Path(markdown_path).resolve().with_suffix(".data.json")
-    if not data_path.exists():
+    from .final_report_paths import is_report_record_path
+
+    resolved = Path(plan_path).resolve()
+    if not is_report_record_path(resolved) or not resolved.exists():
         return {}
     try:
-        data = json.loads(data_path.read_text(encoding="utf-8"))
+        data = json.loads(resolved.read_text(encoding="utf-8"))
     except (OSError, UnicodeError, json.JSONDecodeError) as exc:
-        raise StageMapError("stage_map", str(exc), str(data_path)) from exc
+        raise StageMapError("stage_map", str(exc), str(resolved)) from exc
     if not isinstance(data, dict) or data.get("schemaVersion") != "2.0":
         return {}
     return data

package/runtime/python/okstra_ctl/stage_targets.py

@@ -8,6 +8,8 @@ the stage lifecycle rules behind one interface instead of leaking raw
 from __future__ import annotations
 
 import heapq
+import subprocess
+import sys
 from dataclasses import dataclass, replace
 from pathlib import Path
 from typing import Any
@@ -123,6 +125,27 @@ class StageLifecycleSnapshot:
     pr_covered_stages: set[int]
     lifecycles: list[StageLifecycle]
 
+    def ledger_records(self) -> list[dict[str, Any]]:
+        """계획 저작 쪽에 넘길 stage 사실 기록.
+
+        상태 어휘는 `StageLifecycle.status` 를 그대로 쓴다 — 원장이 자기
+        어휘를 따로 가지면 같은 stage 가 소비처마다 다른 상태로 읽힌다.
+        """
+        titles = {
+            int(row["stage_number"]): str(row.get("title") or "")
+            for row in self.stage_map
+        }
+        return [
+            {
+                "stage": lifecycle.stage,
+                "title": titles.get(lifecycle.stage, ""),
+                "status": lifecycle.status,
+                "dependsOn": list(lifecycle.depends_on),
+                "headCommit": lifecycle.head_commit,
+            }
+            for lifecycle in self.lifecycles
+        ]
+
     def lifecycle_for(self, stage_number: int) -> StageLifecycle:
         for lifecycle in self.lifecycles:
             if lifecycle.stage == stage_number:
@@ -490,6 +513,7 @@ def resolve_stage_base_commit(
     pred = deps[0]
     head = (latest.get(pred) or {}).get("head_commit") or ""
     if head:
+        _warn_if_branch_moved_past(project_root, pred, head, candidate_base)
         return head
     raise StageTargetError(
         f"predecessor stage {pred} has no done row with head_commit in "
@@ -498,6 +522,43 @@ def resolve_stage_base_commit(
     )
 
 
+
+def _warn_if_branch_moved_past(
+    project_root: Path | None,
+    predecessor: int,
+    recorded_head: str,
+    branch_tip: str,
+) -> None:
+    """Say so when the branch has advanced past the commit this stage branches from.
+
+    A stage branches from its predecessor's recorded `head_commit`, not from the
+    branch tip — that is what makes the stage's base reproducible. It also means
+    a commit landing on the branch after the predecessor was settled is invisible
+    to this stage, and the divergence only surfaces later as a rebase. Two such
+    rebases were reported from one six-stage migration; both would have been
+    caught by this line. The base rule is unchanged: this only names the gap.
+    """
+    if project_root is None or not branch_tip or branch_tip == recorded_head:
+        return
+    try:
+        contains = subprocess.run(
+            ["git", "-C", str(project_root), "merge-base", "--is-ancestor",
+             recorded_head, branch_tip],
+            capture_output=True,
+        )
+    except OSError:
+        return
+    if contains.returncode != 0:
+        return
+    print(
+        f"okstra: stage branches from stage {predecessor}'s recorded head "
+        f"{recorded_head[:12]}, but the branch tip is {branch_tip[:12]} — "
+        "commits landed after that stage was settled and this stage will not "
+        "carry them. Integrate them first if they belong to this work.",
+        file=sys.stderr,
+    )
+
+
 def _resolve_whole_task_target(
     *,
     stage_map: list[dict[str, Any]],

package/runtime/python/okstra_ctl/user_response.py

@@ -33,6 +33,7 @@ from okstra_ctl.clarification_items import (
     section_1_present_but_unparsed,
     sidecar_answers,
     _section_1_slice,
+    _v2_report_data,
 )
 
 _PLAN_DECISION_HEADING_RE = re.compile(r"^## PLAN DECISION\s*$", re.MULTILINE)
@@ -105,7 +106,7 @@ _ANALYSIS_REVIEW_STATUSES = frozenset({
 })
 _ANALYSIS_REPORT_RE = re.compile(
     r"^final-report-(?P<task_type>project-analysis|feature-analysis|"
-    r"change-impact-analysis)-(?P<seq>\d{3})\.md$"
+    r"change-impact-analysis)-(?P<seq>\d{3})\.(?:md|data\.json)$"
 )
 
 
@@ -358,8 +359,18 @@ def load_authoritative_analysis_review(
     review = parse_analysis_review("".join(attached))
     if review is None:
         raise UserResponseError("analysis review sidecar is unreadable")
+    from .final_report_paths import (
+        final_report_markdown_path,
+        is_report_record_path,
+    )
+
+    report_name = (
+        final_report_markdown_path(report_path).name
+        if is_report_record_path(report_path)
+        else report_path.name
+    )
     expected_source = (
-        f"runs/{report_match.group('task_type')}/reports/{report_path.name}"
+        f"runs/{report_match.group('task_type')}/reports/{report_name}"
     )
     if review.task_key != expected_task_key:
         raise UserResponseError(
@@ -510,7 +521,9 @@ def parse_user_response_entries(sidecar_text: str) -> list[UserResponseEntry]:
     return entries
 
 
-_SEQ_FROM_REPORT_RE = re.compile(r"final-report-.+-(\w+)\.md$")
+_SEQ_FROM_REPORT_RE = re.compile(
+    r"final-report-.+-(\w+)\.(?:md|data\.json)$"
+)
 
 
 def _seq_from_report(report: Path) -> str:
@@ -557,11 +570,21 @@ def list_awaiting_tasks(home: Path, project_id: str, limit: int) -> list[dict]:
     return out[:limit] if limit > 0 else out
 
 
-# ID tokens are the report body's own cross-reference labels (RB-002, FU-001,
-# O-002, C-017 …) — always uppercase-led so `gpt-5` and lowercase slugs don't
-# match. `§x.y` and `path.ext:line` are the other two ref shapes.
+# ID tokens are the report record's own row labels (RB-002, FU-001, O-002,
+# C-017 …) — always uppercase-led so `gpt-5` and lowercase slugs don't match.
+# `§x.y` is a full-reading-copy heading and is not a record coordinate.
+# `path.ext:line` is a source pointer the record does not define.
 _SECTION_REF_RE = re.compile(r"§[\d.]+|[A-Z]{1,4}-\d+|[\w./-]+\.\w+:\d+")
 _ID_TOKEN_RE = re.compile(r"^[A-Z]{1,4}-\d+$")
+_ROW_DEFINITION_KEYS = (
+    "statement",
+    "summary",
+    "item",
+    "title",
+    "check",
+    "action",
+    "evidence",
+)
 _DEFINITION_SNIPPET_CAP = 200
 _SNIPPET_NOISE_RE = re.compile(r'<a id="[^"]*"></a>|`|\*\*')
 _OPTION_LETTER_LABEL_RE = re.compile(r"^\([a-z]\)\s*")
@@ -629,10 +652,12 @@ def _resolve_section_ref(report_text: str, ref: str) -> str | None:
 
 
 def resolve_refs(report_text: str, refs: list[str]) -> list[dict]:
-    """Resolve each context ref to its plain-text definition from the report
-    body, or None when the report text alone cannot resolve it (a `path:line`
-    pointer). The deterministic lookup the skill uses to rewrite each
-    clarification question in self-contained plain language."""
+    """Resolve each context ref from a schema-v1 reading copy.
+
+    Schema-v1 has no report record; the markdown body is the source. A
+    `path:line` pointer is left unresolved. Schema-v2 callers use
+    `resolve_refs_from_record`.
+    """
     s1_slice = _section_1_slice(report_text)
     resolved: list[dict] = []
     for ref in refs:
@@ -646,11 +671,67 @@ def resolve_refs(report_text: str, refs: list[str]) -> list[dict]:
     return resolved
 
 
+def _row_definition(row: dict) -> str | None:
+    for key in _ROW_DEFINITION_KEYS:
+        value = row.get(key)
+        if isinstance(value, str) and value.strip():
+            return _clean_snippet(value)
+        if isinstance(value, list):
+            for item in value:
+                if isinstance(item, str) and item.strip():
+                    return _clean_snippet(item)
+    return None
+
+
+def _index_record_ids(data: dict) -> dict[str, dict]:
+    """First object in the report record whose `id` is a row token."""
+    index: dict[str, dict] = {}
+
+    def walk(node: object) -> None:
+        if isinstance(node, dict):
+            row_id = node.get("id")
+            if (
+                isinstance(row_id, str)
+                and _ID_TOKEN_RE.match(row_id)
+                and row_id not in index
+            ):
+                index[row_id] = node
+            for value in node.values():
+                walk(value)
+        elif isinstance(node, list):
+            for item in node:
+                walk(item)
+
+    walk(data)
+    return index
+
+
+def resolve_refs_from_record(data: dict, refs: list[str]) -> list[dict]:
+    """Resolve each context ref from the report record.
+
+    Only row identifiers (`RB-002`) are record coordinates. A section number
+    (`§4.7`) belongs to one full reading copy and is left unresolved. A
+    `path:line` pointer is left unresolved because the record does not hold
+    that file.
+    """
+    index = _index_record_ids(data)
+    resolved: list[dict] = []
+    for ref in refs:
+        definition = None
+        if _ID_TOKEN_RE.match(ref):
+            row = index.get(ref)
+            if row is not None:
+                definition = _row_definition(row)
+        resolved.append({"ref": ref, "definition": definition})
+    return resolved
+
+
 def show_open_rows(report_path: Path) -> dict:
-    text = report_path.read_text(encoding="utf-8")
     # 사이드카에 답이 있는 행은 사용자가 이미 답한 것이다. 리포트의 `Status` 는
     # 그 답을 반영하지 않으므로, 이걸 빼지 않으면 스킬이 같은 질문을 다시 묻는다.
     answered = sidecar_answers(report_path)
+    record = _v2_report_data(report_path)
+    v1_text = None if record is not None else report_path.read_text(encoding="utf-8")
     rows = []
     for r in read_clarification_rows(report_path):
         it = r["item"]
@@ -658,13 +739,17 @@ def show_open_rows(report_path: Path) -> dict:
             continue
         statement, expected = r["statement"], r["expected_form"]
         refs = sorted(set(_SECTION_REF_RE.findall(statement + " " + expected)))
+        if record is not None:
+            resolved = resolve_refs_from_record(record, refs)
+        else:
+            resolved = resolve_refs(v1_text or "", refs)
         rows.append({"id": it.row_id, "kind": it.kind, "blocks": it.blocks,
                      "status": it.status, "statement": statement,
                      "expectedForm": expected,
                      # v2 authors the choices; v1 only ever had the string.
                      "options": r["options"] or _options_from_expected_form(expected),
                      "contextRefs": refs,
-                     "resolvedRefs": resolve_refs(text, refs)})
+                     "resolvedRefs": resolved})
     return {"reportPath": str(report_path), "rows": rows}