@opengsd/gsd-path 1.0.0

package/skills/gsd-path-discuss/scripts/discussion_records.py

@@ -0,0 +1,619 @@
+#!/usr/bin/env python3
+# gsd-path project runtime
+"""Manage GSD Path discussion records as a recoverable paired transaction."""
+
+import argparse
+import json
+import os
+import shutil
+import sys
+from contextlib import contextmanager
+from datetime import date
+from pathlib import Path
+from typing import Iterator, Optional, Sequence
+
+def _load_pipeline_modules():
+    try:
+        import archive_milestone
+        import pipeline_state
+        import _common
+        return _common, archive_milestone, pipeline_state
+    except ModuleNotFoundError as error:
+        if error.name not in {"archive_milestone", "pipeline_state", "_common"}:
+            raise
+    try:
+        from scripts import archive_milestone, pipeline_state, _common
+        return _common, archive_milestone, pipeline_state
+    except ModuleNotFoundError as error:
+        if error.name not in {
+            "scripts",
+            "scripts.archive_milestone",
+            "scripts.pipeline_state",
+            "scripts._common",
+        }:
+            raise
+        shared_scripts = Path(__file__).resolve().parents[2] / "gsd-path" / "scripts"
+        sys.path.insert(0, str(shared_scripts))
+        import archive_milestone
+        import pipeline_state
+        import _common
+        return _common, archive_milestone, pipeline_state
+
+
+_common, archive_milestone, pipeline_state = _load_pipeline_modules()
+
+
+class DiscussionError(RuntimeError):
+    pass
+
+
+APPEND_TRANSACTION = ".discussion-append-transaction.json"
+FILES = ("DIALOGUE.md", "ANSWERS.md")
+PHASES = {"inspect", "define", "research", "decide", "roadmap", "plan", "build", "ship"}
+
+
+atomic_write = _common.atomic_write
+
+
+def project_root(repo: Path) -> tuple[Path, Path, Path]:
+    root = repo.resolve()
+    project = root / ".project"
+    state = project / "STATE.md"
+    if project.is_symlink() or not project.is_dir():
+        raise DiscussionError(f".project must be a real directory: {project}")
+    if state.is_symlink() or not state.is_file():
+        raise DiscussionError(f"STATE.md must be a real file: {state}")
+    return root, project, state
+
+
+@contextmanager
+def state_lock(state: Path) -> Iterator[None]:
+    with archive_milestone.discussion_lock(state.parent):
+        yield
+
+
+def state_context(state: Path) -> tuple[str, str, str]:
+    try:
+        current, _content, loaded = pipeline_state.load_state(state.parent.parent)
+    except pipeline_state.PipelineStateError as error:
+        raise DiscussionError(str(error)) from error
+    if loaded != state:
+        raise DiscussionError(f"canonical STATE.md path changed: {loaded}")
+    phase = current.phase
+    status = current.status
+    configured_archive = current.archive or "null"
+    if phase not in PHASES or status not in {"active", "blocked", "done"}:
+        raise DiscussionError(f"discussion is not available in state {phase}/{status}")
+    return phase, status, configured_archive
+
+
+def template_header(path: Path, record_prefix: str) -> str:
+    if path.is_symlink() or not path.is_file() or not path.is_absolute():
+        raise DiscussionError(f"template must be an absolute real file: {path}")
+    content = path.read_text(encoding="utf-8")
+    marker = f"\n{record_prefix}"
+    if marker not in content:
+        raise DiscussionError(f"template lacks sample record: {path}")
+    return content.split(marker, 1)[0].rstrip() + "\n"
+
+
+def record_count(directory: Path) -> int:
+    lines = (directory / "DIALOGUE.md").read_text(encoding="utf-8").splitlines()
+    return sum(
+        archive_milestone.DIALOGUE_HEADING_PATTERN.fullmatch(line) is not None
+        for line in lines
+    )
+
+
+def validate_or_empty(directory: Path) -> None:
+    if directory.is_symlink() or not directory.is_dir():
+        raise DiscussionError("discussion records must be a real directory")
+    if sorted(path.name for path in directory.iterdir()) != sorted(FILES):
+        raise DiscussionError("discussion directory must contain exactly DIALOGUE.md and ANSWERS.md")
+    if record_count(directory) == 0:
+        if "### D" in (directory / "DIALOGUE.md").read_text(encoding="utf-8"):
+            raise DiscussionError("empty discussion has a malformed dialogue record")
+        if "## Answer A" in (directory / "ANSWERS.md").read_text(encoding="utf-8"):
+            raise DiscussionError("empty discussion has a malformed answer record")
+        return
+    try:
+        archive_milestone.validate_discussion_directory(
+            directory, require_dispositions=False
+        )
+    except archive_milestone.ArchiveError as error:
+        raise DiscussionError(str(error)) from error
+
+
+def finish_append(project: Path, discussion: Path) -> None:
+    transaction = project / APPEND_TRANSACTION
+    if not transaction.exists():
+        return
+    if transaction.is_symlink() or not transaction.is_file():
+        raise DiscussionError("discussion append journal must be a real file")
+    try:
+        payload = json.loads(transaction.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        raise DiscussionError(f"discussion append journal is unreadable: {error}") from error
+    if payload.get("schema") != "gsd-path/discussion-append/v1":
+        raise DiscussionError("discussion append journal has the wrong schema")
+    files = payload.get("files")
+    if (
+        not isinstance(files, dict)
+        or set(files) != set(FILES)
+        or any(not isinstance(files[name], str) for name in FILES)
+    ):
+        raise DiscussionError("discussion append journal has invalid files")
+    if project.is_symlink() or not project.is_dir():
+        raise DiscussionError("discussion recovery requires a real .project directory")
+    if discussion.is_symlink() or (
+        discussion.exists() and not discussion.is_dir()
+    ):
+        raise DiscussionError("discussion recovery destination must be a real directory")
+    if discussion.resolve(strict=False).parent != project.resolve():
+        raise DiscussionError("discussion recovery destination escapes .project")
+    discussion.mkdir(exist_ok=True)
+    for name in FILES:
+        atomic_write(discussion / name, files[name])
+    validate_or_empty(discussion)
+    transaction.unlink()
+
+
+def validate_contents(project: Path, files: dict) -> None:
+    staging = project / ".discussion-validation-tmp"
+    if staging.exists() or staging.is_symlink():
+        if staging.is_symlink() or not staging.is_dir():
+            raise DiscussionError(f"discussion validation path is invalid: {staging}")
+        shutil.rmtree(staging)
+    staging.mkdir()
+    try:
+        for name in FILES:
+            (staging / name).write_text(files[name], encoding="utf-8")
+        validate_or_empty(staging)
+    finally:
+        shutil.rmtree(staging)
+
+
+def initialize_records(discussion: Path, dialogue_template: Path, answers_template: Path) -> None:
+    if discussion.exists() or discussion.is_symlink():
+        validate_or_empty(discussion)
+        return
+    staging = discussion.parent / ".discuss.gsd-path-tmp"
+    if staging.exists() or staging.is_symlink():
+        if staging.is_symlink() or not staging.is_dir():
+            raise DiscussionError(f"discussion staging path is invalid: {staging}")
+        shutil.rmtree(staging)
+    staging.mkdir()
+    try:
+        (staging / "DIALOGUE.md").write_text(
+            template_header(dialogue_template, "### D001"), encoding="utf-8"
+        )
+        (staging / "ANSWERS.md").write_text(
+            template_header(answers_template, "## Answer A001"), encoding="utf-8"
+        )
+        os.replace(staging, discussion)
+    finally:
+        if staging.exists():
+            shutil.rmtree(staging)
+
+
+def prepare_locked(
+    root: Path,
+    project: Path,
+    state: Path,
+    dialogue_template: Path,
+    answers_template: Path,
+) -> tuple[Path, str, str]:
+    phase, status, configured = state_context(state)
+    discussion = project / "discuss"
+    finish_append(project, discussion)
+    if not archive_milestone.is_unset(configured):
+        if (phase, status) != ("ship", "active"):
+            raise DiscussionError("archive recovery is allowed only in ship/active")
+        try:
+            archive = archive_milestone.archive_from_state(root, configured)
+        except archive_milestone.ArchiveError as error:
+            raise DiscussionError(str(error)) from error
+        if archive_milestone.archive_is_committed(root, configured):
+            raise DiscussionError("committed discussion archives are immutable")
+        archived = archive / "discuss"
+        if not archived.is_dir():
+            raise DiscussionError("uncommitted archive has no discussion records to resume")
+        if not discussion.exists():
+            staging = project / ".discuss.gsd-path-tmp"
+            if staging.exists():
+                shutil.rmtree(staging)
+            shutil.copytree(archived, staging)
+            os.replace(staging, discussion)
+        else:
+            try:
+                archive_milestone.require_append_only_discussion(discussion, archived)
+            except archive_milestone.ArchiveError as error:
+                raise DiscussionError(str(error)) from error
+    else:
+        initialize_records(discussion, dialogue_template, answers_template)
+    validate_or_empty(discussion)
+    if state_context(state) != (phase, status, configured):
+        raise DiscussionError("STATE.md changed while discussion records were prepared")
+    return discussion, phase, status
+
+
+def numbered_sections(lines: Sequence[str], pattern, boundaries) -> list[tuple]:
+    return list(archive_milestone.record_sections(lines, pattern, boundaries))
+
+
+def field(lines: Sequence[str], name: str) -> str:
+    try:
+        return archive_milestone.completed_bullet_field(lines, name, "ANSWERS.md")
+    except archive_milestone.ArchiveError as error:
+        raise DiscussionError(str(error)) from error
+
+
+def disposed_answers(answer_lines: Sequence[str]) -> set[str]:
+    boundaries = (
+        archive_milestone.ANSWER_HEADING_PATTERN,
+        archive_milestone.DISPOSITION_HEADING_PATTERN,
+    )
+    dispositions = numbered_sections(
+        answer_lines, archive_milestone.DISPOSITION_HEADING_PATTERN, boundaries
+    )
+    return {field(section, "Answer") for _, section in dispositions}
+
+
+def dialogue_threads(dialogue_lines: Sequence[str]) -> dict[str, list[tuple]]:
+    sections = numbered_sections(
+        dialogue_lines,
+        archive_milestone.DIALOGUE_HEADING_PATTERN,
+        (archive_milestone.DIALOGUE_HEADING_PATTERN,),
+    )
+    threads: dict[str, list[tuple]] = {}
+    for match, section in sections:
+        threads.setdefault(field(section, "Thread"), []).append((match, section))
+    return threads
+
+
+def thread_records(discussion: Path) -> list[dict]:
+    lines = (discussion / "DIALOGUE.md").read_text(encoding="utf-8").splitlines()
+    records = []
+    for thread, sections in dialogue_threads(lines).items():
+        match, section = sections[-1]
+        records.append(
+            {
+                "thread": thread,
+                "topic": match.group(5),
+                "last_turn": f"D{int(match.group(1)):03d}",
+                "status": field(section, "Thread status"),
+            }
+        )
+    return records
+
+
+def pending_records(discussion: Path) -> list[dict]:
+    if record_count(discussion) == 0:
+        return []
+    lines = (discussion / "ANSWERS.md").read_text(encoding="utf-8").splitlines()
+    boundaries = (
+        archive_milestone.ANSWER_HEADING_PATTERN,
+        archive_milestone.DISPOSITION_HEADING_PATTERN,
+    )
+    answers = numbered_sections(lines, archive_milestone.ANSWER_HEADING_PATTERN, boundaries)
+    resolved = disposed_answers(lines)
+    pending = []
+    for match, section in answers:
+        identifier = f"A{int(match.group(1)):03d}"
+        if (
+            field(section, "Follow-up") == "required"
+            and field(section, "Status") in {"final", "NEEDS-USER"}
+            and identifier not in resolved
+        ):
+            pending.append(
+                {
+                    "answer": identifier,
+                    "owner": field(section, "Next owner"),
+                    "target": field(section, "Target artifact"),
+                    "status": field(section, "Status"),
+                }
+            )
+    return pending
+
+
+def append_disposition(discussion: Path, project: Path, payload: dict) -> dict:
+    answer = required_text(payload, "answer")
+    pending = {record["answer"]: record for record in pending_records(discussion)}
+    if answer not in pending:
+        raise DiscussionError(f"answer is not pending disposition: {answer}")
+    disposition_status = required_text(payload, "status")
+    if disposition_status not in {
+        "applied",
+        "acknowledged-no-change",
+        "superseded",
+        "rejected-by-user",
+    }:
+        raise DiscussionError("disposition status is invalid")
+    expected = pending[answer]
+    owner = single_line(payload, "owner")
+    artifact = single_line(payload, "artifact")
+    expected_owner = (
+        "user" if disposition_status == "rejected-by-user" else expected["owner"]
+    )
+    if owner != expected_owner:
+        raise DiscussionError(f"disposition owner must be {expected_owner}")
+    if artifact != expected["target"]:
+        raise DiscussionError(f"disposition artifact must be {expected['target']}")
+    lines = (discussion / "ANSWERS.md").read_text(encoding="utf-8").splitlines()
+    boundaries = (
+        archive_milestone.ANSWER_HEADING_PATTERN,
+        archive_milestone.DISPOSITION_HEADING_PATTERN,
+    )
+    existing = numbered_sections(
+        lines, archive_milestone.DISPOSITION_HEADING_PATTERN, boundaries
+    )
+    number = len(existing) + 1
+    record_date = iso_date(payload)
+    disposition = f"""\n## Disposition X{number:03d} — {record_date}
+
+- **Answer**: {answer}
+- **Status**: {disposition_status}
+- **Owner**: {owner}
+- **Artifact**: {artifact}
+- **Evidence**: {single_line(payload, "evidence")}
+"""
+    files = {
+        "DIALOGUE.md": (discussion / "DIALOGUE.md").read_text(encoding="utf-8"),
+        "ANSWERS.md": (discussion / "ANSWERS.md").read_text(encoding="utf-8").rstrip()
+        + "\n"
+        + disposition,
+    }
+    validate_contents(project, files)
+    atomic_write(
+        project / APPEND_TRANSACTION,
+        json.dumps(
+            {"schema": "gsd-path/discussion-append/v1", "files": files},
+            sort_keys=True,
+        )
+        + "\n",
+    )
+    finish_append(project, discussion)
+    return {"answer": answer, "disposition": f"X{number:03d}"}
+
+
+MULTILINE_FIELDS = ("user", "assistant")
+SINGLE_LINE_FIELDS = (
+    "topic",
+    "thread",
+    "question",
+    "status",
+    "thread_status",
+    "conclusion",
+    "reasoning",
+    "evidence",
+    "research",
+    "confidence",
+    "unresolved",
+    "next_owner",
+    "target_artifact",
+    "follow_up",
+)
+
+
+def validate_payload_fields(payload: dict) -> None:
+    problems = []
+    for name in MULTILINE_FIELDS + SINGLE_LINE_FIELDS:
+        value = payload.get(name)
+        if not isinstance(value, str) or not value.strip():
+            problems.append(f"{name} (missing or empty)")
+        elif name in SINGLE_LINE_FIELDS and ("\n" in value or "\r" in value):
+            problems.append(f"{name} (must be one line)")
+    if problems:
+        raise DiscussionError("append payload invalid: " + ", ".join(problems))
+
+
+def required_text(payload: dict, name: str) -> str:
+    value = payload.get(name)
+    if not isinstance(value, str) or not value.strip():
+        raise DiscussionError(f"append payload requires non-empty {name}")
+    return value.strip()
+
+
+def single_line(payload: dict, name: str) -> str:
+    value = required_text(payload, name)
+    if "\n" in value or "\r" in value:
+        raise DiscussionError(f"append payload {name} must be one line")
+    return value
+
+
+def quote_block(value: str) -> str:
+    return "\n".join(f"> {line}" if line else ">" for line in value.splitlines())
+
+
+def indent_block(value: str) -> str:
+    return "\n".join(f"  {line}" if line else "  " for line in value.splitlines())
+
+
+def iso_date(payload: dict) -> str:
+    value = payload.get("date", date.today().isoformat())
+    if not isinstance(value, str):
+        raise DiscussionError("date must be YYYY-MM-DD")
+    try:
+        parsed = date.fromisoformat(value)
+    except ValueError as error:
+        raise DiscussionError("date must be YYYY-MM-DD") from error
+    if parsed.isoformat() != value:
+        raise DiscussionError("date must be YYYY-MM-DD")
+    return value
+
+
+def append_record(discussion: Path, project: Path, phase: str, status: str, payload: dict) -> dict:
+    count = record_count(discussion)
+    number = count + 1
+    dialogue_id = f"D{number:03d}"
+    answer_id = f"A{number:03d}"
+    dialogue_text = (discussion / "DIALOGUE.md").read_text(encoding="utf-8")
+    dialogue_lines = dialogue_text.splitlines()
+    if count:
+        archive_milestone.validate_discussion_directory(
+            discussion, require_dispositions=False
+        )
+    validate_payload_fields(payload)
+    answers_text = (discussion / "ANSWERS.md").read_text(encoding="utf-8")
+    requested_thread = payload["thread"]
+    existing_threads = dialogue_threads(dialogue_lines) if count else {}
+    if requested_thread == "new":
+        thread_number = max((int(value[1:]) for value in existing_threads), default=0) + 1
+        thread = f"T{thread_number:03d}"
+        reply_to = supersedes = "none"
+    elif requested_thread in existing_threads:
+        thread = requested_thread
+        prior = int(existing_threads[thread][-1][0].group(1))
+        reply_to = f"D{prior:03d}"
+        prior_answer = f"A{prior:03d}"
+        # A disposed answer is settled; a continuation replies without superseding it.
+        supersedes = (
+            "none"
+            if prior_answer in disposed_answers(answers_text.splitlines())
+            else prior_answer
+        )
+    else:
+        raise DiscussionError("thread must be new or an existing T### id")
+    record_date = iso_date(payload)
+    thread_status = single_line(payload, "thread_status")
+    answer_status = single_line(payload, "status")
+    if thread_status not in {"working", "NEEDS-USER", "final"}:
+        raise DiscussionError("thread_status is invalid")
+    if answer_status not in {"working", "NEEDS-USER", "final"}:
+        raise DiscussionError("status is invalid")
+    topic = single_line(payload, "topic")
+    evidence = single_line(payload, "evidence")
+    research = single_line(payload, "research")
+    dialogue = f"""\n### {dialogue_id} — {record_date} — {phase}/{status} — {topic}
+
+- **Thread**: {thread}
+- **Reply to**: {reply_to}
+- **User (verbatim)**:
+
+{quote_block(required_text(payload, "user"))}
+
+- **Assistant**:
+
+{indent_block(required_text(payload, "assistant"))}
+
+- **Evidence checked**: {evidence}
+- **Research**: {research}
+- **Thread status**: {thread_status}
+"""
+    answer = f"""\n## Answer {answer_id} — {record_date} — {topic}
+
+- **Thread**: {thread}
+- **Turn**: {dialogue_id}
+- **Supersedes**: {supersedes}
+- **Question**: {single_line(payload, "question")}
+- **Status**: {answer_status}
+- **Phase/status**: {phase}/{status}
+- **Conclusion**: {single_line(payload, "conclusion")}
+- **Reasoning / pushback**: {single_line(payload, "reasoning")}
+- **Evidence**: {evidence}
+- **Research**: {research}
+- **Confidence**: {single_line(payload, "confidence")}
+- **Unresolved**: {single_line(payload, "unresolved")}
+- **Next owner**: {single_line(payload, "next_owner")}
+- **Target artifact**: {single_line(payload, "target_artifact")}
+- **Follow-up**: {single_line(payload, "follow_up")}
+"""
+    files = {
+        "DIALOGUE.md": dialogue_text.rstrip() + "\n" + dialogue,
+        "ANSWERS.md": answers_text.rstrip() + "\n" + answer,
+    }
+    validate_contents(project, files)
+    transaction = project / APPEND_TRANSACTION
+    atomic_write(
+        transaction,
+        json.dumps(
+            {"schema": "gsd-path/discussion-append/v1", "files": files},
+            sort_keys=True,
+        )
+        + "\n",
+    )
+    finish_append(project, discussion)
+    return {"answer": answer_id, "dialogue": dialogue_id, "thread": thread}
+
+
+def load_payload(path: Path) -> dict:
+    if path.is_symlink() or not path.is_file():
+        raise DiscussionError(f"append input must be a real file: {path}")
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        raise DiscussionError(f"append input is unreadable: {error}") from error
+    if not isinstance(payload, dict):
+        raise DiscussionError("append input must contain one JSON object")
+    return payload
+
+
+def parser() -> argparse.ArgumentParser:
+    result = argparse.ArgumentParser(description=__doc__)
+    result.add_argument(
+        "command", choices=("prepare", "append", "pending", "dispose", "threads")
+    )
+    result.add_argument("--repo", type=Path, required=True)
+    result.add_argument("--dialogue-template", type=Path)
+    result.add_argument("--answers-template", type=Path)
+    result.add_argument("--input", type=Path)
+    return result
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    try:
+        arguments = parser().parse_args(argv)
+        root, project, state = project_root(arguments.repo)
+        with state_lock(state):
+            state_context(state)
+            if arguments.command in {"pending", "dispose", "threads"}:
+                discussion = project / "discuss"
+                finish_append(project, discussion)
+                if not discussion.exists():
+                    if arguments.command == "dispose":
+                        raise DiscussionError("discussion records do not exist")
+                    result = {arguments.command: []}
+                else:
+                    validate_or_empty(discussion)
+                    if arguments.command == "pending":
+                        result = {"pending": pending_records(discussion)}
+                    elif arguments.command == "threads":
+                        result = {"threads": thread_records(discussion)}
+                    else:
+                        if arguments.input is None:
+                            raise DiscussionError("dispose requires --input")
+                        result = append_disposition(
+                            discussion, project, load_payload(arguments.input)
+                        )
+            else:
+                if arguments.dialogue_template is None or arguments.answers_template is None:
+                    raise DiscussionError("prepare and append require both bundled template paths")
+                discussion, phase, status = prepare_locked(
+                    root,
+                    project,
+                    state,
+                    arguments.dialogue_template.resolve(),
+                    arguments.answers_template.resolve(),
+                )
+                if arguments.command == "prepare":
+                    result = {
+                        "dialogue": str((discussion / "DIALOGUE.md").resolve()),
+                        "answers": str((discussion / "ANSWERS.md").resolve()),
+                        "phase_status": f"{phase}/{status}",
+                        "records": record_count(discussion),
+                    }
+                else:
+                    if arguments.input is None:
+                        raise DiscussionError("append requires --input")
+                    result = append_record(
+                        discussion, project, phase, status, load_payload(arguments.input)
+                    )
+        print(json.dumps(result, sort_keys=True))
+        return 0
+    except (DiscussionError, archive_milestone.ArchiveError) as error:
+        print(str(error), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/gsd-path-discuss/templates/answers.md

@@ -0,0 +1,29 @@
+# GSD Path Discussion — Answers
+
+<!-- Written by $gsd-path-discuss. Append one record per turn; never rewrite prior answers. -->
+
+## Answer A001 — <YYYY-MM-DD> — <topic>
+
+- **Thread**: T001
+- **Turn**: D001
+- **Supersedes**: none | A###
+- **Question**: <the question being answered>
+- **Status**: working | NEEDS-USER | final
+- **Phase/status**: <phase>/<status>
+- **Conclusion**: <answer first>
+- **Reasoning / pushback**: <why, including rejected premise or safer alternative>
+- **Evidence**: <exact repository paths and line references; commands only if run>
+- **Research**: <not needed — reason, or query, checked sources, and confidence>
+- **Confidence**: high | medium | low | unverifiable
+- **Unresolved**: <none, or NEEDS-USER / RESEARCH question>
+- **Next owner**: <none, user, or named GSD Path phase>
+- **Target artifact**: <none or canonical .project path>
+- **Follow-up**: none | required
+
+## Disposition X001 — <YYYY-MM-DD>
+
+- **Answer**: A###
+- **Status**: applied | acknowledged-no-change | superseded | rejected-by-user
+- **Owner**: <phase or router>
+- **Artifact**: <canonical path or none>
+- **Evidence**: <what was changed, why no change was needed, or the user ruling>

package/skills/gsd-path-discuss/templates/dialogue.md

@@ -0,0 +1,21 @@
+# GSD Path Discussion — Dialogue
+
+<!-- Written by $gsd-path-discuss. Append turns; never rewrite prior turns. -->
+
+## Turns
+
+### D001 — <YYYY-MM-DD> — <phase>/<status> — <topic>
+
+- **Thread**: T001
+- **Reply to**: none | D###
+- **User (verbatim)**:
+
+  > <copy the user's message exactly>
+
+- **Assistant**:
+
+  <copy the answer returned to the user>
+
+- **Evidence checked**: <repository paths, line references, commands actually run, or none>
+- **Research**: <not needed — reason, or query/sources/confidence>
+- **Thread status**: working | NEEDS-USER | final