174 lines
5.2 KiB
Python
174 lines
5.2 KiB
Python
"""Lesson proposals as issue files: where a person reviews each one.
|
|
|
|
.scratch/lessons/issues/NN-<slug>.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,
|
|
)
|