Files
orchestration_engine/execution_engine/learning/proposals.py

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,
)