"""Lesson proposals as issue files: where a person reviews each one. .scratch/lessons/issues/NN-.md A proposal starts as `needs-triage`. A person approves it by setting its Status to `ready-for-agent`, or rejects it with `wontfix`. Only an approved proposal can be published. The file carries the rule, its reason and how widespread the evidence was, and nothing that identifies a client or an Execution. """ from __future__ import annotations import re from dataclasses import dataclass, replace from datetime import UTC, date, datetime from pathlib import Path NEEDS_TRIAGE = "needs-triage" APPROVED = "ready-for-agent" REJECTED = "wontfix" STATUSES = (NEEDS_TRIAGE, "needs-info", APPROVED, "ready-for-human", REJECTED) ISSUES = Path(".scratch") / "lessons" / "issues" _FIELD = re.compile(r"^([A-Z][\w-]*):\s*(.*)$", re.MULTILINE) _SECTION = re.compile(r"^## (.+?)\s*$", re.MULTILINE) @dataclass(frozen=True) class Proposal: number: int title: str deliverable: str rule: str reason: str evidence: str # counts and a general description evidence_key: str status: str = NEEDS_TRIAGE proposed: str = "" published: str = "" # The day it was taken out of the Skill again. A retired lesson is not # published a second time, whatever its Status still says. retired: str = "" proof: str = "" comments: str = "" path: Path | None = None @property def id(self) -> str: return f"L-{self.number:02d}" @property def approved(self) -> bool: return self.status == APPROVED and not self.retired def _slug(title: str) -> str: return re.sub(r"[^a-z0-9]+", "-", title.lower()).strip("-")[:60] or "lesson" def render(proposal: Proposal) -> str: lines = [ f"# {proposal.id}: {proposal.title}", "", f"Status: {proposal.status}", f"Deliverable: {proposal.deliverable}", f"Evidence-key: {proposal.evidence_key}", f"Proposed: {proposal.proposed}", ] if proposal.published: lines.append(f"Published: {proposal.published}") if proposal.retired: lines.append(f"Retired: {proposal.retired}") lines += [ "", "## Rule", "", proposal.rule.strip(), "", "## Why", "", proposal.reason.strip(), "", "## Evidence", "", proposal.evidence.strip(), "", "## Proof", "", proposal.proof.strip() or "Not yet measured.", "", "## Comments", "", proposal.comments.strip(), ] return "\n".join(lines).rstrip() + "\n" def parse(path: Path) -> Proposal: text = path.read_text(encoding="utf-8") heading = re.match(r"# L-(\d+): (.+)", text) if not heading: raise ValueError(f"{path}: not a lesson proposal") head = text.split("\n## ", 1)[0] fields = {name: value.strip() for name, value in _FIELD.findall(head)} sections: dict[str, str] = {} matches = list(_SECTION.finditer(text)) for index, match in enumerate(matches): end = matches[index + 1].start() if index + 1 < len(matches) else len(text) sections[match.group(1)] = text[match.end() : end].strip() status = fields.get("Status", NEEDS_TRIAGE) if status not in STATUSES: raise ValueError(f"{path}: Status must be one of {', '.join(STATUSES)}") proof = sections.get("Proof", "") return Proposal( number=int(heading.group(1)), title=heading.group(2).strip(), deliverable=fields.get("Deliverable", ""), rule=sections.get("Rule", ""), reason=sections.get("Why", ""), evidence=sections.get("Evidence", ""), evidence_key=fields.get("Evidence-key", ""), status=status, proposed=fields.get("Proposed", ""), published=fields.get("Published", ""), retired=fields.get("Retired", ""), proof="" if proof == "Not yet measured." else proof, comments=sections.get("Comments", ""), path=path, ) def load(folder: Path = ISSUES) -> list[Proposal]: if not folder.is_dir(): return [] return sorted( (parse(path) for path in folder.glob("[0-9]*-*.md")), key=lambda p: p.number ) def write(proposal: Proposal, folder: Path = ISSUES) -> Proposal: folder.mkdir(parents=True, exist_ok=True) path = proposal.path or folder / f"{proposal.number:02d}-{_slug(proposal.title)}.md" path.write_text(render(proposal), encoding="utf-8") return replace(proposal, path=path) def propose( *, title: str, deliverable: str, rule: str, reason: str, evidence: str, evidence_key: str, folder: Path = ISSUES, today: date | None = None, ) -> Proposal: """A new proposal, numbered after the last, awaiting a person's decision.""" existing = load(folder) number = max((p.number for p in existing), default=0) + 1 return write( Proposal( number=number, title=title.strip(), deliverable=deliverable, rule=rule, reason=reason, evidence=evidence, evidence_key=evidence_key, proposed=(today or datetime.now(UTC).date()).isoformat(), ), folder, )