seed_142_todo_narrative.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# tools/seed_142_todo_narrative.py
 
# OCT-LINT: disable=tests_exist reason="Covered by oc_chat/tests/registry/seed/test_todo_narrative.py"
"""
ROADMAP-TODO deferred-decision narrative -> note records (Plan 142 rework Phase 2).
 
Purpose
-------
The legacy `oc_chat/roadmap/ROADMAP-TODO-v3.38.md` (695 l.) is retired as a render
OUTPUT (``__init__.RETIRED_OUTPUTS``), but its **deferred-decision narrative** — the
organizing prose / why-deferred rationale AROUND the already-migrated 53 backlog
items — had no registry home. Migrate the three deferred-work ``## `` sections
**verbatim** into ``source/notes/<id>.md`` records (mirroring the Phase-3 framing
notes), so the living EXTENDED render carries them (no resurrected 4th file):
 
  ``## Orchestration Registry (M11) — gates, backlog & deferred design questions``
  · ``## Active deferred items`` · ``## Post-12-week backlog``
 
The ``## Recently completed`` per-round log (l.370–686) is intentionally **subsumed
by the changelog** (same disposition as the What's-New narrative);
the file's title + ``> Appendix`` framing describes the retired 4-file model and is
not migrated. (All accounted for in ``tools/142_todo_narrative_coverage.md``.)
 
No contract change: ``Note`` is the pre-existing P1.1 model. Idempotent.
 
Responsibilities
----------------
- ``parse_sections`` (slice the 3 deferred ``## `` sections), ``backfill`` (write
  the note records), reported ``sections`` for the audit.
 
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 - seed lifecycle
    L3 - per-section extraction
    L4 - per-record emission
 
Contracts
---------
- Deterministic; writes only ``source/notes/<id>.md``; never touches the live
  legacy TODO; every record validates + re-canonicalises.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_chat.registry.regenerate (imported for the contracts bootstrap it runs)
- option_c_registry_contracts (the Note model and SCHEMA_VERSION for each deferred-decision note record)
- oc_chat.registry.source.canonical (format_record_text - writes each note's frontmatter and verbatim body)
"""
from __future__ import annotations
 
import re
import sys
from dataclasses import dataclass, field
from pathlib import Path
 
# Force the WORKTREE-local oc_chat ahead of the editable main-repo install.
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
 
from oc_diagnostics import _dbg
 
import oc_chat.registry.regenerate  # noqa: F401  (contracts bootstrap)
import option_c_registry_contracts as rc
 
from oc_chat.registry.source.canonical import format_record_text
 
_dbg("OC_CHAT.MAIN", "module", "loaded", 4)
 
#: (heading-prefix, note id, clean title) for the 3 deferred-decision sections.
#: Each prefix is unique; the slicer stops at the next ``## ``/``# `` heading, so
#: the ``## Recently completed`` per-round log is excluded (subsumed by changelog).
_SECTIONS: tuple[tuple[str, str, str], ...] = (
    ("## Orchestration Registry (M11)", "m11-deferred",
     "Orchestration Registry (M11) — gates, backlog & deferred design questions"),
    ("## Active deferred items", "active-deferred",
     "Active deferred items (still relevant, folded forward, or explicitly deferred)"),
    ("## Post-12-week backlog", "post-12-week-backlog",
     # OCT-LINT: disable=no_hardcoded_secrets reason="Roadmap section headings + note ids are not secrets"
     "Post-12-week backlog (from unified-roadmap-v3 §5)"),
    ("## Branch / plans / docs hygiene", "branch-plans-docs-hygiene",
     "Branch / plans / docs hygiene (running list)"),
)
_BOUNDARY_RE = re.compile(r"^(## |# |\*End of )", re.MULTILINE)
_TRAILING_RULE_RE = re.compile(r"\n*-{3,}\s*$")
 
 
@dataclass
class TodoReport:
    notes_written: int = 0
    sections: dict = field(default_factory=dict)  # id -> (title, body)
 
 
def parse_sections(todo_text: str) -> dict[str, tuple[str, str]]:
    """Return ``{note_id: (title, verbatim_body)}`` for the 3 deferred sections."""
    text = todo_text.replace("\r\n", "\n")
    out: dict[str, tuple[str, str]] = {}
    for prefix, note_id, title in _SECTIONS:
        match = re.search(rf"^{re.escape(prefix)}.*$", text, re.MULTILINE)
        if match is None:
            continue
        nxt = _BOUNDARY_RE.search(text, match.end())
        end = nxt.start() if nxt else len(text)
        body = text[match.start():end].strip("\n")
        out[note_id] = (title, _TRAILING_RULE_RE.sub("", body).strip("\n"))
    return out
 
 
def backfill(todo_md: Path, source_dir: Path) -> TodoReport:
    """Write each deferred section to ``source/notes/<id>.md`` (verbatim body)."""
    func = "backfill"
    sections = parse_sections(Path(todo_md).read_text(encoding="utf-8"))
    out_dir = Path(source_dir) / "notes"
    out_dir.mkdir(parents=True, exist_ok=True)
    report = TodoReport()
    for note_id, (title, body) in sections.items():
        model = rc.Note(schema_version=rc.SCHEMA_VERSION, id=note_id, title=title)
        (out_dir / f"{note_id}.md").write_text(
            format_record_text(model, body=body), encoding="utf-8", newline=""
        )
        report.notes_written += 1
        report.sections[note_id] = (title, body)
        _dbg("OC_CHAT.MAIN", func, f"wrote note {note_id} ({len(body)} chars)", 3)
    _dbg("OC_CHAT.MAIN", func, f"wrote {report.notes_written} TODO-narrative notes", 2)
    return report
 
 
def _main() -> int:
    func = "_main"
    repo = Path(__file__).resolve().parents[1]
    roadmap = repo / "oc_chat" / "roadmap" / "ROADMAP-TODO-v3.38.md"
    source = repo / "oc_chat" / "roadmap" / "source"
    report = backfill(roadmap, source)
    _dbg("OC_CHAT.MAIN", func, f"notes={report.notes_written}", 2)
    for note_id, (title, body) in report.sections.items():
        print(f"{note_id}: {title!r} ({len(body)} chars)")
    print(f"notes_written={report.notes_written}")
    return 0
 
 
if __name__ == "__main__":
    raise SystemExit(_main())