okstra 0.189.3 → 0.190.0

package/runtime/python/okstra_ctl/group_context.py

@@ -6,13 +6,25 @@
 `cache` 그룹: 브리프 15개 중 가용성 사고를 말한 것이 0개였고 option-selection 이
 분모를 페이지당 요청 수로 바꿔 판단했다).
 
-세 소비자가 이 모듈 하나를 쓴다.
+파일은 두 소유자가 나눠 쓴다. 위의 네 절은 사용자가 쓰고, 파일 끝의 마커 영역
+(`MEMORY_BEGIN`…`MEMORY_END`, `## Task Memory`)은 okstra 가 report-finalize 마다
+다시 쓴다 — 그룹의 각 task 가 마지막 run 에서 낸 결론(headline·decisions·
+follow-up·레코드 경로)이다. 형제 task 의 run 은 이 영역을 패킷의
+`## Task-Group Memory` 로 받는다(2026-09-07: cache 그룹 15개 티켓 중 첫 티켓의
+run 8개 결론이 나머지 14개에 닿는 통로가 없었다).
 
-- `okstra group-context init` — 템플릿에서 뼈대를 쓴다(있으면 거절).
+네 소비자가 이 모듈 하나를 쓴다.
+
+- `okstra group-context init` — 템플릿에서 뼈대를 쓴다. okstra 가 메모리만 써 둔
+  파일이면 그 위에 사람 절 뼈대를 끼워 넣고, 사람 절이 있는 파일은 덮지 않는다.
 - `validators/validate-brief.py` — 프론트매터 `type: group-context` 를 만나면
-  `validate_group_context` 로 검사한다.
+  `validate_group_context` 로 검사한다. 사람 절이 하나도 없는 메모리 전용 파일은
+  네 절 규칙을 적용하지 않는다.
 - prepare(`run.py`) — 파일이 있으면 같은 검사를 통과해야 진행하고, 통과하면
   `instruction-set/task-group-context.md` 로 복사해 analysis packet 에 싣는다.
+  패킷은 `split_memory_region` 으로 사람 절과 메모리를 갈라 따로 배치한다.
+- report-finalize `record-group-memory` — `record_task_memory` 로 이 run 의
+  항목을 영역에 쓴다. 파일이 없으면 메모리 전용 파일을 만든다.
 """
 from __future__ import annotations
 
@@ -20,15 +32,24 @@ import argparse
 import datetime as dt
 import re
 import sys
+from dataclasses import dataclass, replace
 from pathlib import Path
+from typing import Any, Mapping
+
+from okstra_project import list_project_tasks
+from okstra_project.phase_pointer import STATUS_TERMINAL
 
 from .brief_frontmatter import read_brief_frontmatter
 from .ids import slugify_task_segment
 from .paths import find_asset_root
+from .run_context import dir_flock
 
 GROUP_CONTEXT_FILENAME = "group-context.md"
 GROUP_CONTEXT_TYPE = "group-context"
 GROUP_CONTEXT_GENERATOR = "okstra-brief-gen"
+# 파일이 없을 때 finalize 가 메모리 전용 파일을 만들며 적는 생성자.
+MEMORY_GENERATOR = "okstra-report-finalize"
+GENERATORS = (GROUP_CONTEXT_GENERATOR, MEMORY_GENERATOR)
 INSTRUCTION_SET_FILENAME = "task-group-context.md"
 REQUIRED_FRONTMATTER_KEYS = ("type", "task-group", "created", "generator")
 SECTIONS = (
@@ -44,6 +65,431 @@ TEMPLATE_RELATIVE = ("templates", "reports", "group-context.template.md")
 _HTML_COMMENT_RE = re.compile(r"<!--.*?-->", re.DOTALL)
 _NONE_MARKERS = {"_(none)_", ""}
 
+# --- okstra 소유 영역 ----------------------------------------------------------
+
+MEMORY_BEGIN = "<!-- okstra:task-memory:begin -->"
+MEMORY_END = "<!-- okstra:task-memory:end -->"
+MEMORY_NOTE = (
+    "<!-- okstra rewrites this region at every report-finalize. "
+    "Edit the sections above it, not this one. -->"
+)
+MEMORY_HEADING = "## Task Memory"
+MEMORY_EMPTY = "_(no runs recorded yet)_"
+# 실측(2026-09-07 cache 그룹 dev-10626): decisions 한 줄이 250~400자, 캡 없이 한 task 가
+# 3.5KB 였다. 15개 task 그룹이 패킷에 실리므로 task 당 1.5KB 안팎으로 잡는다.
+HEADLINE_MAX = 240
+ITEM_MAX = 160
+DECISIONS_MAX = 3
+FOLLOW_UPS_MAX = 3
+WATCH_OUT_MAX = 2
+LOCK_FILENAME = ".group-context.lock"
+_FOLLOW_UP_SEP = "; "
+_LATEST_RE = re.compile(r"^- latest: (?P<type>\S+) #(?P<seq>\S+) · (?P<date>\S+) · next: (?P<next>.*)$")
+
+
+@dataclass(frozen=True)
+class MemoryEntry:
+    """한 task 의 마지막 run 결론. `decisions` 만 이전 항목과 합쳐 누적한다."""
+
+    task_id: str
+    task_type: str
+    seq: str
+    date: str
+    next_phase: str
+    headline: str
+    decisions: tuple[str, ...]
+    follow_ups: tuple[str, ...]
+    record: str
+    watch_out: tuple[str, ...] = ()
+
+
+def memory_entry_from_record(
+    data: Mapping[str, Any],
+    *,
+    task_id: str,
+    task_type: str,
+    seq: str,
+    record: str,
+    next_phase: str,
+    today: dt.date,
+) -> MemoryEntry:
+    """final-report 레코드에서 항목을 뽑는다. 없는 필드는 빈 값이지 실패가 아니다."""
+    summary = data.get("humanSummary")
+    summary = summary if isinstance(summary, Mapping) else {}
+    header = data.get("header")
+    header = header if isinstance(header, Mapping) else {}
+    created = header.get("createdAt")
+    date = created[:10] if isinstance(created, str) and len(created) >= 10 else today.isoformat()
+    follow_ups = tuple(
+        _clip(_one_line(row["title"]), ITEM_MAX)
+        for row in (data.get("followUpTasks") or [])
+        if isinstance(row, Mapping)
+        and row.get("origin") != "phase-continuation"
+        and isinstance(row.get("title"), str)
+        and row["title"].strip()
+    )
+    return MemoryEntry(
+        task_id=slugify_task_segment(task_id),
+        task_type=task_type,
+        seq=seq,
+        date=date,
+        next_phase=next_phase,
+        headline=_clip(_one_line(summary.get("headline")), HEADLINE_MAX),
+        decisions=tuple(
+            _clip(_one_line(item), ITEM_MAX) for item in (summary.get("decisions") or [])
+            if isinstance(item, str) and item.strip()
+        ),
+        follow_ups=follow_ups,
+        record=record,
+        watch_out=tuple(
+            _clip(_one_line(item), ITEM_MAX) for item in (summary.get("blockers") or [])
+            if isinstance(item, str) and item.strip()
+        ),
+    )
+
+
+def _one_line(value: Any) -> str:
+    return " ".join(str(value).split()) if isinstance(value, str) else ""
+
+
+def _clip(text: str, limit: int) -> str:
+    return text if len(text) <= limit else text[: limit - 1].rstrip() + "…"
+
+
+def split_memory_region(text: str) -> tuple[str, str, str]:
+    """(마커 앞, 마커 사이, 마커 뒤). 영역이 없으면 사이와 뒤는 빈 문자열.
+
+    begin 만 있으면 파일 끝까지를 영역으로 본다. end 만 있으면 영역이 없는 것으로
+    본다 — 어느 쪽이든 다음 쓰기가 균형 잡힌 영역으로 다시 쓴다.
+    """
+    begin = text.find(MEMORY_BEGIN)
+    if begin < 0:
+        return text, "", ""
+    inner_start = begin + len(MEMORY_BEGIN)
+    end = text.find(MEMORY_END, inner_start)
+    if end < 0:
+        return text[:begin], text[inner_start:], ""
+    return text[:begin], text[inner_start:end], text[end + len(MEMORY_END):]
+
+
+def parse_memory_entries(region: str) -> list[MemoryEntry]:
+    """영역 본문 → 항목. `### <task-id>` 가 항목을 연다. 모르는 줄은 버린다."""
+    entries: list[MemoryEntry] = []
+    current: dict[str, Any] | None = None
+    in_decisions = in_watch_out = False
+    for raw in region.splitlines():
+        line = raw.rstrip()
+        if line.startswith("### "):
+            if current is not None:
+                entries.append(_entry_from_fields(current))
+            current = {"task_id": line[4:].strip(), "decisions": [], "watch_out": []}
+            in_decisions = in_watch_out = False
+            continue
+        if current is None:
+            continue
+        if line.startswith("  - ") and (in_decisions or in_watch_out):
+            current["decisions" if in_decisions else "watch_out"].append(line[4:].strip())
+            continue
+        in_decisions = in_watch_out = False
+        match = _LATEST_RE.match(line)
+        if match:
+            current.update(
+                task_type=match.group("type"), seq=match.group("seq"),
+                date=match.group("date"), next_phase=match.group("next").strip(),
+            )
+        elif line.startswith("- headline: "):
+            current["headline"] = line[len("- headline: "):].strip()
+        elif line == "- decisions:":
+            in_decisions = True
+        elif line.startswith("- open follow-ups: "):
+            value = line[len("- open follow-ups: "):].strip()
+            current["follow_ups"] = [] if value in _NONE_MARKERS else value.split(_FOLLOW_UP_SEP)
+        elif line == "- watch out:":
+            in_watch_out = True
+        elif line.startswith("- record: "):
+            current["record"] = line[len("- record: "):].strip().strip("`")
+    if current is not None:
+        entries.append(_entry_from_fields(current))
+    return entries
+
+
+def _entry_from_fields(fields: Mapping[str, Any]) -> MemoryEntry:
+    return MemoryEntry(
+        task_id=fields.get("task_id", ""),
+        task_type=fields.get("task_type", ""),
+        seq=fields.get("seq", ""),
+        date=fields.get("date", ""),
+        next_phase=fields.get("next_phase", ""),
+        headline=fields.get("headline", ""),
+        decisions=tuple(fields.get("decisions", [])),
+        follow_ups=tuple(fields.get("follow_ups", [])),
+        record=fields.get("record", ""),
+        watch_out=tuple(fields.get("watch_out", [])),
+    )
+
+
+def render_memory_entries(entries: list[MemoryEntry]) -> str:
+    """항목들 → `### ` 블록. 빈 목록은 `MEMORY_EMPTY` 한 줄."""
+    if not entries:
+        return MEMORY_EMPTY + "\n"
+    blocks: list[str] = []
+    for entry in entries:
+        lines = [
+            f"### {entry.task_id}",
+            f"- latest: {entry.task_type} #{entry.seq} · {entry.date} · next: {entry.next_phase or '_(none)_'}",
+            f"- headline: {entry.headline or '_(none)_'}",
+        ]
+        if entry.decisions:
+            lines.append("- decisions:")
+            lines.extend(f"  - {item}" for item in entry.decisions)
+        if entry.watch_out:
+            lines.append("- watch out:")
+            lines.extend(f"  - {item}" for item in entry.watch_out)
+        lines.append(
+            "- open follow-ups: "
+            + (_FOLLOW_UP_SEP.join(entry.follow_ups) if entry.follow_ups else "_(none)_")
+        )
+        lines.append(f"- record: `{entry.record}`" if entry.record else "- record: _(none)_")
+        blocks.append("\n".join(lines) + "\n")
+    return "\n".join(blocks)
+
+
+def render_memory_region(entries: list[MemoryEntry], queue: list[QueueRow] | None = None) -> str:
+    parts = [MEMORY_BEGIN, MEMORY_NOTE, MEMORY_HEADING, ""]
+    queue_text = render_queue(queue or [])
+    if queue_text:
+        parts.extend([queue_text.rstrip("\n"), ""])
+    parts.extend([render_memory_entries(entries).rstrip("\n"), MEMORY_END])
+    return "\n".join(parts) + "\n"
+
+
+def merge_memory_entry(entries: list[MemoryEntry], entry: MemoryEntry) -> list[MemoryEntry]:
+    """같은 task 의 항목을 갈아 끼우고 decisions 는 새 것 우선으로 합쳐 상한까지 남긴다."""
+    previous = next((e for e in entries if e.task_id == entry.task_id), None)
+    decisions: list[str] = []
+    for item in (*entry.decisions, *(previous.decisions if previous else ())):
+        if item and item not in decisions:
+            decisions.append(item)
+    merged = replace(
+        entry,
+        decisions=tuple(decisions[:DECISIONS_MAX]),
+        follow_ups=entry.follow_ups[:FOLLOW_UPS_MAX],
+        watch_out=entry.watch_out[:WATCH_OUT_MAX],
+    )
+    rest = [e for e in entries if e.task_id != entry.task_id]
+    return sorted([*rest, merged], key=lambda e: (e.date, e.task_id), reverse=True)
+
+
+def memory_only_document(task_group: str, created: str) -> str:
+    """사람 절 없이 프론트매터·제목·빈 영역만 있는 파일. finalize 가 파일이 없을 때 만든다."""
+    slug = slugify_task_segment(task_group)
+    return (
+        "---\n"
+        f"type: {GROUP_CONTEXT_TYPE}\n"
+        f"task-group: {slug}\n"
+        f"created: {created}\n"
+        f"generator: {MEMORY_GENERATOR}\n"
+        "---\n"
+        "\n"
+        f"# Task-Group Context: {slug}\n"
+        "\n"
+        + render_memory_region([])
+    )
+
+
+def record_task_memory(
+    project_root: Path, task_group: str, entry: MemoryEntry, *, today: dt.date
+) -> tuple[Path, list[QueueRow]]:
+    """이 run 의 항목을 그룹 문서의 okstra 영역에 쓰고 (경로, 시작 순서 큐)를 돌려준다.
+
+    파일이 없으면 만든다. 사람 절은 바이트 그대로 둔다. 같은 그룹의 finalize 가
+    동시에 돌 수 있으므로 디렉터리 flock 아래에서 읽고-바꾸고-쓴다.
+    """
+    target = group_context_file(project_root, task_group)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    with dir_flock(target.parent, LOCK_FILENAME):
+        text = (
+            target.read_text(encoding="utf-8") if target.is_file()
+            else memory_only_document(task_group, today.isoformat())
+        )
+        before, region, after = split_memory_region(text)
+        entries = merge_memory_entry(parse_memory_entries(region), entry)
+        queue = group_queue(project_root, task_group, entries)
+        if not before.endswith("\n"):
+            before += "\n"
+        if before.strip() and not before.endswith("\n\n"):
+            before += "\n"
+        target.write_text(before + render_memory_region(entries, queue) + after, encoding="utf-8")
+    return target, queue
+
+
+# --- 시작 순서 ----------------------------------------------------------------
+#
+# 그룹의 task 는 순서가 있을 수 있다. 순서는 brief-gen 이 매긴 브리프 순번
+# (`DEV-10627-2-…` 의 `2`)이다 — 사용자가 분할 때 정한 순서다. 브리프의 Related
+# Task Graph 에 적힌 `depends-on` / `blocks` / `blocked-by` 간선은 재정렬하지 않고
+# `waits for` 로 붙여 보이기만 한다: 실측(2026-09-07 cache 그룹) 에서 그래프는
+# 15번 가드 티켓이 1번을 `blocks` 한다고 적었지만 사용자는 1번을 먼저 끝냈다.
+# 큐는 영역 머리에 실리고, 이 task 가 끝나는 closeout 은 큐의 다음 task 를 이름한다.
+
+QUEUE_DONE = "done"
+QUEUE_IN_PROGRESS = "in progress"
+QUEUE_NOT_STARTED = "not started"
+_ORDINAL_RE = re.compile(r"^(?P<ticket>[A-Za-z]+-\d+)-(?P<ordinal>\d+)-")
+_WAIT_RELATIONS = {"depends-on", "blocked-by"}
+_BLOCK_RELATIONS = {"blocks"}
+_QUEUE_INTRO = (
+    "Start order (brief ordinal; `waits for` quotes `depends-on` / `blocks` edges "
+    "from the briefs' Related Task Graph whose named ticket is not done):"
+)
+_QUEUE_LINE_RE = re.compile(r"^\d+\. \[(?P<status>[^\]]*)\] (?P<task>\S+)")
+
+
+@dataclass(frozen=True)
+class QueueRow:
+    task_id: str        # slugified brief-id — the task directory name
+    brief_id: str
+    ticket_id: str
+    brief: str          # project-relative brief path
+    status: str         # QUEUE_*
+    progress: str       # "<task-type> #<seq>" for a recorded task, else ""
+    waits_for: tuple[str, ...] = ()   # ticket ids the graph says come first and are not done
+
+
+def group_briefs(project_root: Path, task_group: str) -> list[dict[str, Any]]:
+    """그룹 디렉터리의 브리프(프론트매터 `type: brief`)와 각 브리프의 대기 간선."""
+    group_dir = group_context_file(project_root, task_group).parent
+    if not group_dir.is_dir():
+        return []
+    briefs: list[dict[str, Any]] = []
+    for path in sorted(group_dir.rglob("*.md")):
+        if is_group_context_file(path) or not path.is_file():
+            continue
+        frontmatter = read_brief_frontmatter(path)
+        if frontmatter.get("type") != "brief":
+            continue
+        brief_id = frontmatter.get("brief-id") or path.stem
+        match = _ORDINAL_RE.match(brief_id)
+        briefs.append({
+            "brief_id": brief_id,
+            "ticket_id": frontmatter.get("ticket-id") or (match.group("ticket") if match else brief_id),
+            "ordinal": int(match.group("ordinal")) if match else None,
+            "brief": path.relative_to(project_root).as_posix(),
+            "waits_for": _wait_edges(path.read_text(encoding="utf-8")),
+        })
+    return briefs
+
+
+def _wait_edges(text: str) -> dict[str, set[str]]:
+    """Related Task Graph 표 → {ticket: 먼저 끝나야 하는 ticket 들}."""
+    waits: dict[str, set[str]] = {}
+    for line in _section_bodies(text).get("Related Task Graph", "").splitlines():
+        cells = [cell.strip() for cell in line.strip().strip("|").split("|")]
+        if len(cells) < 3:
+            continue
+        source, relation, target = cells[0], cells[1], cells[2]
+        if relation in _WAIT_RELATIONS:
+            waits.setdefault(source, set()).add(target)
+        elif relation in _BLOCK_RELATIONS:
+            waits.setdefault(target, set()).add(source)
+    return waits
+
+
+def catalog_progress(project_root: Path, task_group: str) -> dict[str, tuple[str, str]]:
+    """카탈로그에 있는 그룹 task → (큐 상태, 진행 표기). task-manifest 가 정본이다.
+
+    메모리 항목은 2026-09-07 이후의 finalize 만 쓰므로 그 전에 끝난 task 는 항목이
+    없다(실측: cache 그룹 dev-10626 — run 13개, release-handoff 완료인데 큐는
+    `[not started]`). 카탈로그 항목은 `list_project_tasks` 가 task-manifest 의
+    phase·상태·다음 phase 포인터로 덮어 돌려주므로 여기서 다시 읽지 않는다.
+    """
+    wanted = slugify_task_segment(task_group)
+    out: dict[str, tuple[str, str]] = {}
+    for entry in list_project_tasks(project_root):
+        if slugify_task_segment(str(entry.get("taskGroup") or "")) != wanted:
+            continue
+        task_id = slugify_task_segment(str(entry.get("taskId") or ""))
+        if not task_id:
+            continue
+        pointer = entry.get("nextRecommendedPhase")
+        pointer = pointer if isinstance(pointer, Mapping) else {}
+        phase = str(entry.get("currentPhase") or entry.get("taskType") or "")
+        state = str(entry.get("currentPhaseState") or entry.get("latestRunStatus") or "")
+        progress = f"{phase} ({state})" if phase and state else phase
+        status = QUEUE_DONE if pointer.get("status") == STATUS_TERMINAL else QUEUE_IN_PROGRESS
+        out[task_id] = (status, progress)
+    return out
+
+
+def group_queue(
+    project_root: Path, task_group: str, entries: list[MemoryEntry]
+) -> list[QueueRow]:
+    """브리프를 순번 순서로 늘어놓고 카탈로그, 그 다음 기록된 항목으로 상태를 매긴다.
+
+    순번이 없는 브리프는 뒤에 id 순이다. 그래프 간선은 순서를 바꾸지 않고 아직
+    끝나지 않은 선행 ticket 을 `waits_for` 로 붙인다. 카탈로그에 있는 task 는
+    task-manifest 가 상태를 정하고, 메모리 항목은 카탈로그가 모르는 task 에만
+    쓰인다(`catalog_progress`).
+    """
+    briefs = group_briefs(project_root, task_group)
+    if not briefs:
+        return []
+    by_ticket = {brief["ticket_id"]: brief for brief in briefs}
+    waits: dict[str, set[str]] = {}
+    for brief in briefs:
+        for ticket, before in brief["waits_for"].items():
+            waits.setdefault(ticket, set()).update((before & by_ticket.keys()) - {ticket})
+    ordered = sorted(briefs, key=lambda b: (b["ordinal"] is None, b["ordinal"] or 0, b["brief_id"]))
+    by_task = {entry.task_id: entry for entry in entries}
+    recorded = catalog_progress(project_root, task_group)
+
+    def _status(brief: dict[str, Any]) -> tuple[str, str]:
+        task_id = slugify_task_segment(brief["brief_id"])
+        if task_id in recorded:
+            return recorded[task_id]
+        entry = by_task.get(task_id)
+        if entry is None:
+            return QUEUE_NOT_STARTED, ""
+        done = entry.next_phase.endswith("(terminal)")
+        return (QUEUE_DONE if done else QUEUE_IN_PROGRESS), f"{entry.task_type} #{entry.seq}"
+
+    status_by_ticket = {brief["ticket_id"]: _status(brief) for brief in ordered}
+    rows: list[QueueRow] = []
+    for brief in ordered:
+        status, progress = status_by_ticket[brief["ticket_id"]]
+        open_waits = tuple(sorted(
+            ticket for ticket in waits.get(brief["ticket_id"], set())
+            if status_by_ticket[ticket][0] != QUEUE_DONE
+        ))
+        rows.append(QueueRow(
+            slugify_task_segment(brief["brief_id"]), brief["brief_id"], brief["ticket_id"],
+            brief["brief"], status, progress, open_waits,
+        ))
+    return rows
+
+
+def next_in_group(queue: list[QueueRow]) -> QueueRow | None:
+    """시작 순서에서 아직 시작하지 않은 첫 task."""
+    return next((row for row in queue if row.status == QUEUE_NOT_STARTED), None)
+
+
+def render_queue(queue: list[QueueRow]) -> str:
+    if not queue:
+        return ""
+    lines = [_QUEUE_INTRO, ""]
+    for number, row in enumerate(queue, start=1):
+        tail = f" — {row.progress}" if row.progress else ""
+        if row.waits_for:
+            tail += f" (waits for {', '.join(row.waits_for)})"
+        lines.append(f"{number}. [{row.status}] {row.task_id}{tail}")
+    return "\n".join(lines) + "\n"
+
+
+def has_human_sections(text: str) -> bool:
+    """마커 밖에 `## ` 절이 하나라도 있는가. 없으면 메모리 전용 문서다."""
+    before, _, after = split_memory_region(text)
+    return any(line.startswith("## ") for line in (before + after).splitlines())
+
 
 def briefs_root(project_root: Path) -> Path:
     return Path(project_root) / ".okstra" / "briefs"
@@ -60,7 +506,7 @@ def is_group_context_file(path: Path) -> bool:
 
 def validate_group_context(path: Path, root: Path) -> list[str]:
     """결함 목록. 비어 있으면 통과. 결함마다 사람이 고칠 자리를 이름한다."""
-    text = _HTML_COMMENT_RE.sub("", path.read_text(encoding="utf-8"))
+    raw = path.read_text(encoding="utf-8")
     errors: list[str] = []
     frontmatter = read_brief_frontmatter(path)
     if not frontmatter:
@@ -72,13 +518,17 @@ def validate_group_context(path: Path, root: Path) -> list[str]:
         errors.append(
             f"frontmatter type must be {GROUP_CONTEXT_TYPE!r}, got {frontmatter.get('type')!r}"
         )
-    if frontmatter.get("generator") != GROUP_CONTEXT_GENERATOR:
+    if frontmatter.get("generator") not in GENERATORS:
         errors.append(
-            f"frontmatter generator must be {GROUP_CONTEXT_GENERATOR!r}, "
+            f"frontmatter generator must be one of {list(GENERATORS)}, "
             f"got {frontmatter.get('generator')!r}"
         )
     errors.extend(_path_errors(path, root, frontmatter.get("task-group", "")))
-    errors.extend(_section_errors(text))
+    # okstra 가 쓴 영역은 검사하지 않는다. 사람 절이 하나라도 있으면 네 절 규칙.
+    # 마커가 HTML 주석이라 영역을 가른 뒤에 주석을 지운다.
+    if has_human_sections(raw):
+        human_text, _, human_tail = split_memory_region(raw)
+        errors.extend(_section_errors(_HTML_COMMENT_RE.sub("", human_text + human_tail)))
     return errors
 
 
@@ -161,12 +611,23 @@ def render_skeleton(task_group: str, created: str) -> str:
 
 
 def init_group_context(project_root: Path, task_group: str, *, today: dt.date) -> Path:
-    """뼈대를 쓴다. 이미 있으면 `FileExistsError` — 채운 문서를 덮어쓰지 않는다."""
+    """뼈대를 쓴다. 사람 절이 있는 파일은 `FileExistsError` — 채운 문서를 덮어쓰지 않는다.
+
+    okstra 가 메모리만 써 둔 파일이면 그 영역을 그대로 두고 사람 절 뼈대를 앞에 끼운다.
+    """
     target = group_context_file(project_root, task_group)
+    skeleton = render_skeleton(task_group, today.isoformat())
     if target.exists():
-        raise FileExistsError(str(target))
+        existing = target.read_text(encoding="utf-8")
+        if has_human_sections(existing):
+            raise FileExistsError(str(target))
+        _, region, after = split_memory_region(existing)
+        human, _, _ = split_memory_region(skeleton)
+        entries = parse_memory_entries(region)
+        target.write_text(human + render_memory_region(entries) + after, encoding="utf-8")
+        return target
     target.parent.mkdir(parents=True, exist_ok=True)
-    target.write_text(render_skeleton(task_group, today.isoformat()), encoding="utf-8")
+    target.write_text(skeleton, encoding="utf-8")
     return target
 
 
@@ -195,6 +656,10 @@ def _init_command(args: argparse.Namespace) -> int:
         f"`{slugify_task_segment(args.task_group)}` refuses to prepare while a placeholder "
         "line remains; delete the file if the group needs no context."
     )
+    print(
+        f"The trailing `{MEMORY_HEADING}` region is written by okstra at every "
+        "report-finalize; leave it alone."
+    )
     return 0