seed_142_framing_notes.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# tools/seed_142_framing_notes.py
 
# OCT-LINT: disable=tests_exist reason="Covered by oc_chat/tests/registry/seed/test_framing_notes.py"
"""
Framing-section -> note records (Plan 142 prose-preservation Phase 3, GATE3 Part 2).
 
Purpose
-------
Migrate the FIVE roadmap-level framing sections of the legacy
``oc_chat/roadmap/ROADMAP-v3.38.md`` — rationale / decision content that must live
in the registry before cutover — into ``source/notes/<id>.md`` records, mirroring
the Phase-1 changelog-framing pattern (verbatim body, no prose in the renderer):
 
  ``## Sources Referenced`` · ``## Reconciliation notes`` · ``## Execution Order``
  · ``## Out Of Scope (v3.00)`` · ``## Git Workflow & Version Convention``
 
Each becomes a ``Note`` record (``id`` + ``title``, §3.5 — EXTENDED-only, never a
``roadmap_items_v3`` row) whose **body is the verbatim section** (heading + content,
trailing ``---`` rule stripped). The EXTENDED render (``render.roadmap.notes``)
emits the bodies as their own sections; the lean ROADMAP stays lean.
 
No contract change: ``Note`` is a pre-existing P1.1 model; the scanner + pipeline
already classify ``notes/``. Idempotent; canonical-stable.
 
Responsibilities
----------------
- ``parse_framing_sections`` (slice the 5 ``## `` sections), ``backfill`` (write
  the note records), ``coverage`` (the section -> record map 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 roadmap; 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 framing 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) for the 5 framing sections, in legacy reading order.
#: Each prefix is unique in the file (the ``## What's New`` blocks never match).
_SECTIONS: tuple[tuple[str, str], ...] = (
    ("## Sources Referenced", "sources-referenced"),
    ("## Reconciliation notes", "reconciliation-notes"),
    ("## Execution Order", "execution-order"),
    ("## Out Of Scope", "out-of-scope"),
    ("## Git Workflow", "git-workflow"),
)
#: A section ends at the next top-level heading / phase / the file's end note.
_BOUNDARY_RE = re.compile(r"^(# PHASE |## |\*End of )", re.MULTILINE)
_TRAILING_RULE_RE = re.compile(r"\n*-{3,}\s*$")
 
 
@dataclass
class FramingReport:
    notes_written: int = 0
    sections: dict = field(default_factory=dict)  # id -> (title, body)
 
 
def parse_framing_sections(roadmap_text: str) -> dict[str, tuple[str, str]]:
    """Return ``{note_id: (title, verbatim_body)}`` for the 5 framing sections."""
    text = roadmap_text.replace("\r\n", "\n")
    out: dict[str, tuple[str, str]] = {}
    for prefix, note_id in _SECTIONS:
        match = re.search(rf"^{re.escape(prefix)}.*$", text, re.MULTILINE)
        if match is None:
            continue
        title = match.group(0)[3:].strip()  # heading text minus "## "
        nxt = _BOUNDARY_RE.search(text, match.end())
        end = nxt.start() if nxt else len(text)
        body = text[match.start():end].strip("\n")
        body = _TRAILING_RULE_RE.sub("", body).strip("\n")
        out[note_id] = (title, body)
    return out
 
 
def backfill(roadmap_md: Path, source_dir: Path) -> FramingReport:
    """Write each framing section to ``source/notes/<id>.md`` (verbatim body)."""
    func = "backfill"
    sections = parse_framing_sections(Path(roadmap_md).read_text(encoding="utf-8"))
    out_dir = Path(source_dir) / "notes"
    out_dir.mkdir(parents=True, exist_ok=True)
    report = FramingReport()
    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} framing notes", 2)
    return report
 
 
def _main() -> int:
    func = "_main"
    repo = Path(__file__).resolve().parents[1]
    roadmap = repo / "oc_chat" / "roadmap" / "ROADMAP-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())