feat: the lessons loop, and six lessons approved and published
Capture, distil, review, publish, retire (ADR-0004). Lesson candidates of past Executions are grouped into what recurred; a lesson-curator role, outside any Execution, proposes a lesson per group worth one; each proposal is an issue file a person approves or rejects; an approved lesson is written into the provider's lessons Skill, which a Specialist is given only once it holds lessons for that Specialist's Deliverable. LESSONS_ENABLED off runs without them, for an evaluation with and without. The curator proposed six lessons from 21 Executions. The owner approved all six on 2026-10-09 and they are published: five for the target architect, one for the IaC author. None is proved by an evaluation yet. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -7,6 +7,7 @@ include. The provider bundle supplies each role's Skills, MCP servers and model.
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import dataclasses
|
||||
from pathlib import Path
|
||||
|
||||
from app.adk.runtime import RoleSpec
|
||||
@@ -17,11 +18,19 @@ from app.workflows.deliverables import DEPENDENCY_GRAPH, DeliverableKind
|
||||
ORCHESTRATOR = "orchestrator"
|
||||
PILLAR_ADVISOR = "pillar-advisor"
|
||||
REPLY_WRITER = "reply-writer"
|
||||
LESSON_CURATOR = "lesson-curator" # runs outside any Execution
|
||||
PARTIALS_DIR = "partials"
|
||||
|
||||
_ALLOWED_FIELDS = {"role", "deliverable", "tools", "budget", "includes"}
|
||||
|
||||
|
||||
def _deliverables_with_lessons(bundle: ProviderBundle) -> set[str]:
|
||||
if not bundle.lessons_skill:
|
||||
return set()
|
||||
folder = bundle.skills[bundle.lessons_skill].path / "references"
|
||||
return {path.stem for path in folder.glob("*.md")} if folder.is_dir() else set()
|
||||
|
||||
|
||||
class RoleConfigError(ValueError):
|
||||
"""A role file is missing or invalid."""
|
||||
|
||||
@@ -33,9 +42,14 @@ def load_roles(
|
||||
orchestrator_budget: int = 40,
|
||||
specialist_budget: int = 15,
|
||||
include_preview_mcp: bool = True,
|
||||
lessons: bool = True,
|
||||
) -> dict[str, RoleSpec]:
|
||||
"""`lessons` off leaves the lessons Skill out of every role, so an evaluation
|
||||
can run with and without what has been learned."""
|
||||
specialists = {spec.specialist: kind for kind, spec in DEPENDENCY_GRAPH.items()}
|
||||
required = {ORCHESTRATOR, PILLAR_ADVISOR, REPLY_WRITER, *specialists}
|
||||
optional = {LESSON_CURATOR}
|
||||
learned = _deliverables_with_lessons(bundle) if lessons else set()
|
||||
|
||||
roles = {}
|
||||
for path in sorted(agents_dir.glob("*.md")):
|
||||
@@ -54,7 +68,13 @@ def load_roles(
|
||||
raise RoleConfigError(
|
||||
f"{agents_dir}: missing role files for {', '.join(missing)}"
|
||||
)
|
||||
unexpected = sorted(set(roles) - required)
|
||||
for name, kind in specialists.items():
|
||||
if kind.value in learned and bundle.lessons_skill:
|
||||
# Only a Specialist whose Deliverable has lessons is given the Skill.
|
||||
roles[name] = dataclasses.replace(
|
||||
roles[name], skills=(*roles[name].skills, bundle.lessons_skill)
|
||||
)
|
||||
unexpected = sorted(set(roles) - required - optional)
|
||||
if unexpected:
|
||||
raise RoleConfigError(
|
||||
f"{agents_dir}: unexpected role files {', '.join(unexpected)}"
|
||||
|
||||
@@ -293,6 +293,7 @@ async def open_assembly(
|
||||
orchestrator_budget=settings.ORCHESTRATOR_BUDGET,
|
||||
specialist_budget=settings.SPECIALIST_BUDGET,
|
||||
include_preview_mcp=settings.MCP_ENABLE_PREVIEW,
|
||||
lessons=settings.LESSONS_ENABLED,
|
||||
)
|
||||
if runtime is None:
|
||||
from app.adk.adk_runtime import AdkAgentRuntime
|
||||
|
||||
@@ -54,6 +54,9 @@ class Settings(BaseSettings):
|
||||
A2A_PUBLIC_URL: str | None = None # advertised in the agent card
|
||||
ORCHESTRATOR_BUDGET: int = 40
|
||||
SPECIALIST_BUDGET: int = 15
|
||||
# Give Specialists the lessons Skill. Off runs without anything learned, which
|
||||
# is how the evaluation shows whether a lesson helps.
|
||||
LESSONS_ENABLED: bool = True
|
||||
# With a user present, a Specialist's first submission of a Deliverable is refused
|
||||
# until it has put its draft to them. Off: Specialists are only told to.
|
||||
CONFIRM_DRAFTS: bool = True
|
||||
|
||||
17
app/learning/__init__.py
Normal file
17
app/learning/__init__.py
Normal file
@@ -0,0 +1,17 @@
|
||||
"""The lessons loop (ADR-0004): what Executions got wrong becomes reviewed Skill changes.
|
||||
|
||||
capture each Execution records lesson candidates app/states/lessons.py
|
||||
distil recurring candidates are grouped, and a curator
|
||||
proposes a lesson for each group worth one evidence.py, curator.py
|
||||
review each proposal is an issue file a person decides proposals.py
|
||||
publish an approved lesson is written into the lessons
|
||||
Skill the provider bundle assigns to roles skill.py
|
||||
prove the evaluation runs with and without lessons
|
||||
retire a lesson that did not help, or that the upstream
|
||||
Skills now cover, is removed skill.py
|
||||
|
||||
Nothing here runs inside an Execution, and no lesson reaches an agent without a
|
||||
person's approval. Lesson candidates are client data: they are read from the
|
||||
Executions' records and never copied into the repository; a lesson and its issue
|
||||
file carry counts and a general description only.
|
||||
"""
|
||||
164
app/learning/curator.py
Normal file
164
app/learning/curator.py
Normal file
@@ -0,0 +1,164 @@
|
||||
"""The lesson curator: proposes a lesson for each recurring problem worth one.
|
||||
|
||||
It runs outside any Execution, on the evidence of many. It only proposes: every
|
||||
proposal is written as an issue file for a person to decide (ADR-0004).
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
from collections.abc import Sequence
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from app.adk.runtime import (
|
||||
AgentRuntime,
|
||||
AgentTask,
|
||||
RoleSpec,
|
||||
ToolResult,
|
||||
ToolSpec,
|
||||
TurnEnded,
|
||||
)
|
||||
from app.learning.evidence import Group
|
||||
from app.learning.proposals import ISSUES, Proposal, load, propose
|
||||
from app.workflows.deliverables import DeliverableKind
|
||||
|
||||
LESSON_CURATOR = "lesson-curator"
|
||||
MAX_GROUPS = 25
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
def _evidence(group: Group, executions: int) -> str:
|
||||
return (
|
||||
f"Seen in {len(group.executions)} of {executions} Executions, "
|
||||
f"{group.occurrences} times in all: {group.description}."
|
||||
)
|
||||
|
||||
|
||||
async def curate(
|
||||
runtime: AgentRuntime,
|
||||
role: RoleSpec,
|
||||
groups: Sequence[Group],
|
||||
*,
|
||||
executions: int,
|
||||
identifiers: set[str] = frozenset(), # type: ignore[assignment]
|
||||
folder: Path = ISSUES,
|
||||
) -> list[Proposal]:
|
||||
"""Run the curator over the groups that have no proposal yet; return what it
|
||||
proposed. Groups it judged not worth a lesson are left for the next run."""
|
||||
existing = load(folder)
|
||||
decided = {proposal.evidence_key for proposal in existing}
|
||||
fresh = [group for group in groups if group.key not in decided][:MAX_GROUPS]
|
||||
if not fresh:
|
||||
return []
|
||||
by_key = {group.key: group for group in fresh}
|
||||
kinds = [kind.value for kind in DeliverableKind]
|
||||
proposed: list[Proposal] = []
|
||||
declined: dict[str, str] = {}
|
||||
|
||||
async def propose_lesson(
|
||||
group: str, deliverable: str, title: str, rule: str, reason: str
|
||||
) -> ToolResult:
|
||||
if group not in by_key:
|
||||
return ToolResult(f"Refused: {group} is not one of the groups given.")
|
||||
if deliverable not in kinds:
|
||||
return ToolResult(
|
||||
f"Refused: deliverable must be one of {', '.join(kinds)}."
|
||||
)
|
||||
if any(p.evidence_key == group for p in proposed):
|
||||
return ToolResult(f"Refused: {group} already has a proposal.")
|
||||
text = f"{title} {rule} {reason}"
|
||||
leaked = sorted(name for name in identifiers if name in text)
|
||||
if leaked:
|
||||
return ToolResult(
|
||||
"Refused: a lesson carries no client or Execution detail; remove "
|
||||
+ ", ".join(leaked)
|
||||
)
|
||||
if not (title.strip() and rule.strip() and reason.strip()):
|
||||
return ToolResult("Refused: a lesson needs a title, a rule and a reason.")
|
||||
proposal = propose(
|
||||
title=title,
|
||||
deliverable=deliverable,
|
||||
rule=rule,
|
||||
reason=reason,
|
||||
evidence=_evidence(by_key[group], executions),
|
||||
evidence_key=group,
|
||||
folder=folder,
|
||||
)
|
||||
proposed.append(proposal)
|
||||
return ToolResult(f"Proposed {proposal.id} for a person to review.")
|
||||
|
||||
async def no_lesson(group: str, why: str) -> ToolResult:
|
||||
if group not in by_key:
|
||||
return ToolResult(f"Refused: {group} is not one of the groups given.")
|
||||
declined[group] = why
|
||||
return ToolResult(f"Noted: no lesson for {group}.")
|
||||
|
||||
async def finish() -> ToolResult:
|
||||
return ToolResult("Done.", TurnEnded("finish"))
|
||||
|
||||
text = {"type": "string"}
|
||||
tools = [
|
||||
ToolSpec(
|
||||
"propose_lesson",
|
||||
"Propose one lesson for a group. A person reviews it before any agent "
|
||||
"sees it.",
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"group": text,
|
||||
"deliverable": {"type": "string", "enum": kinds},
|
||||
"title": text,
|
||||
"rule": text,
|
||||
"reason": text,
|
||||
},
|
||||
"required": ["group", "deliverable", "title", "rule", "reason"],
|
||||
},
|
||||
propose_lesson,
|
||||
tier="execution",
|
||||
),
|
||||
ToolSpec(
|
||||
"no_lesson",
|
||||
"Say that a group is not worth a lesson, and why.",
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {"group": text, "why": text},
|
||||
"required": ["group", "why"],
|
||||
},
|
||||
no_lesson,
|
||||
tier="execution",
|
||||
),
|
||||
ToolSpec(
|
||||
"finish",
|
||||
"End your turn once every group has a proposal or a reason for none.",
|
||||
{"type": "object", "properties": {}},
|
||||
finish,
|
||||
tier="execution",
|
||||
),
|
||||
]
|
||||
context: dict[str, Any] = {
|
||||
"executions": executions,
|
||||
"groups": [group.as_context() for group in fresh],
|
||||
"published_or_proposed": [
|
||||
{
|
||||
"id": p.id,
|
||||
"deliverable": p.deliverable,
|
||||
"rule": p.rule,
|
||||
"status": p.status,
|
||||
}
|
||||
for p in existing
|
||||
],
|
||||
}
|
||||
await runtime.run(
|
||||
role,
|
||||
AgentTask(
|
||||
role=role.name,
|
||||
prompt="Propose lessons from what recurred across these Executions.",
|
||||
context=context,
|
||||
),
|
||||
tools,
|
||||
)
|
||||
for group, why in declined.items():
|
||||
logger.info("no lesson for %s: %s", group, why)
|
||||
return proposed
|
||||
155
app/learning/evidence.py
Normal file
155
app/learning/evidence.py
Normal file
@@ -0,0 +1,155 @@
|
||||
"""Lesson candidates across Executions, grouped into what recurs."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
import json
|
||||
import re
|
||||
from collections.abc import Iterable, Mapping, Sequence
|
||||
from dataclasses import dataclass, field
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
EXAMPLES = 3
|
||||
EXAMPLE_LIMIT = 400
|
||||
# Ids and numbers vary between Executions; what recurs is the shape around them.
|
||||
_VARIABLE = re.compile(r"`[^`]*`|\"[^\"]*\"|\b[A-Z]{1,4}-[\w.-]+\b|\b\d[\w.]*\b")
|
||||
# A refusal the Execution's own permissions caused is policy, not a mistake.
|
||||
_POLICY = ("Refused: reading live cloud resources", "Permission to read live cloud")
|
||||
|
||||
|
||||
@dataclass
|
||||
class Group:
|
||||
"""One thing that went wrong the same way in several Executions."""
|
||||
|
||||
key: str # stable across runs of the curator: the same evidence, the same key
|
||||
kind: str # refusal | revision | proposed_addition | failed_check | ...
|
||||
deliverable: str | None
|
||||
description: str # general: no id, name or value from any Execution
|
||||
executions: set[str] = field(default_factory=set)
|
||||
occurrences: int = 0
|
||||
examples: list[str] = field(default_factory=list) # client data: never published
|
||||
|
||||
def as_context(self) -> dict[str, Any]:
|
||||
return {
|
||||
"group": self.key,
|
||||
"kind": self.kind,
|
||||
"deliverable": self.deliverable,
|
||||
"what_happened": self.description,
|
||||
"executions": len(self.executions),
|
||||
"occurrences": self.occurrences,
|
||||
"examples": self.examples,
|
||||
}
|
||||
|
||||
|
||||
def read_candidates(roots: Iterable[Path]) -> list[dict[str, Any]]:
|
||||
"""Every Execution's lesson-candidate record under the given folders."""
|
||||
records = []
|
||||
seen: set[Path] = set()
|
||||
for root in roots:
|
||||
for path in sorted(Path(root).rglob("lessons/candidates/*/*.json")):
|
||||
# One folder may lie inside another that was also given.
|
||||
if path.resolve() in seen:
|
||||
continue
|
||||
seen.add(path.resolve())
|
||||
try:
|
||||
record = json.loads(path.read_text(encoding="utf-8"))
|
||||
except ValueError:
|
||||
continue
|
||||
if isinstance(record, dict) and isinstance(record.get("candidates"), list):
|
||||
records.append(record)
|
||||
return records
|
||||
|
||||
|
||||
def _general(text: str, limit: int = 110) -> str:
|
||||
return " ".join(_VARIABLE.sub("…", text).split())[:limit]
|
||||
|
||||
|
||||
def _shape(candidate: Mapping[str, Any]) -> tuple[str, str | None, str] | None:
|
||||
"""(kind, Deliverable, general description) of a candidate, or None to ignore it."""
|
||||
kind = str(candidate.get("type"))
|
||||
deliverable = candidate.get("deliverable")
|
||||
if kind == "refusal":
|
||||
message = str(candidate.get("message", ""))
|
||||
if message.strip() == "Refused" or message.startswith(_POLICY):
|
||||
return None
|
||||
tool = candidate.get("tool")
|
||||
return kind, deliverable, f"{tool} refused: {_general(message)}"
|
||||
if kind in ("revision", "revision_limit"):
|
||||
reason = str(candidate.get("reason", ""))
|
||||
if reason.startswith("Q: ") or "revision limit" in reason:
|
||||
return None # the router's own questions, recorded as reasons
|
||||
if reason.startswith("Add a Check"):
|
||||
why = "validation proposed a Check the design lacked"
|
||||
elif "cannot be implemented" in reason:
|
||||
why = "a Check named something its resource cannot do"
|
||||
elif " failed" in reason[:60]:
|
||||
why = "the code failed a Check"
|
||||
else:
|
||||
why = _general(reason, 70)
|
||||
return "revision", deliverable, f"revised because {why}"
|
||||
if kind == "proposed_addition":
|
||||
return (
|
||||
kind,
|
||||
"target_architecture",
|
||||
"validation proposed a Check the design lacked",
|
||||
)
|
||||
if kind in ("failed_check", "unverifiable_check"):
|
||||
what = "failed" if kind == "failed_check" else "could not be verified"
|
||||
return kind, "deployment_guidance", f"a Check {what} at validation"
|
||||
if kind == "unfinished":
|
||||
return kind, deliverable, f"the Specialist {candidate.get('reason')}"
|
||||
if kind == "change_request":
|
||||
return kind, None, "the user asked for changes at an Approval"
|
||||
return None
|
||||
|
||||
|
||||
def group_candidates(
|
||||
records: Sequence[Mapping[str, Any]], *, min_executions: int = 2
|
||||
) -> list[Group]:
|
||||
"""What recurred in at least `min_executions` Executions, most widespread first."""
|
||||
groups: dict[str, Group] = {}
|
||||
for record in records:
|
||||
execution = str(record.get("execution_id"))
|
||||
for candidate in record.get("candidates", ()):
|
||||
if not isinstance(candidate, Mapping):
|
||||
continue
|
||||
shape = _shape(candidate)
|
||||
if shape is None:
|
||||
continue
|
||||
kind, deliverable, description = shape
|
||||
key = hashlib.sha256(
|
||||
f"{kind}|{deliverable}|{description}".encode()
|
||||
).hexdigest()[:10]
|
||||
group = groups.setdefault(key, Group(key, kind, deliverable, description))
|
||||
group.executions.add(execution)
|
||||
group.occurrences += 1
|
||||
example = str(
|
||||
candidate.get("message")
|
||||
or candidate.get("reason")
|
||||
or candidate.get("statement")
|
||||
or candidate.get("evidence")
|
||||
or candidate.get("feedback")
|
||||
or ""
|
||||
)[:EXAMPLE_LIMIT]
|
||||
if (
|
||||
example
|
||||
and example not in group.examples
|
||||
and len(group.examples) < EXAMPLES
|
||||
):
|
||||
group.examples.append(example)
|
||||
return sorted(
|
||||
(g for g in groups.values() if len(g.executions) >= min_executions),
|
||||
key=lambda g: (-len(g.executions), -g.occurrences, g.key),
|
||||
)
|
||||
|
||||
|
||||
def identifiers(records: Sequence[Mapping[str, Any]]) -> set[str]:
|
||||
"""Names that identify a client or an Execution, which no lesson may carry."""
|
||||
found = set()
|
||||
for record in records:
|
||||
for name in ("execution_id", "customer_case"):
|
||||
value = record.get(name)
|
||||
if isinstance(value, str) and len(value) >= 4 and value != "unassigned":
|
||||
found.add(value)
|
||||
return found
|
||||
167
app/learning/proposals.py
Normal file
167
app/learning/proposals.py
Normal file
@@ -0,0 +1,167 @@
|
||||
"""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 = ""
|
||||
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
|
||||
|
||||
|
||||
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}")
|
||||
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", ""),
|
||||
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,
|
||||
)
|
||||
142
app/learning/skill.py
Normal file
142
app/learning/skill.py
Normal file
@@ -0,0 +1,142 @@
|
||||
"""The lessons Skill: where approved lessons are published, and retired from.
|
||||
|
||||
A lessons Skill is an ordinary Agent Skill, per Cloud provider, that the provider
|
||||
bundle names. It has one reference file per Deliverable that has lessons, so a
|
||||
Specialist reads only the lessons for its own work. Both the reference files and
|
||||
the index in SKILL.md are written here, from approved proposals, and never by hand.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
from dataclasses import replace
|
||||
from datetime import UTC, date, datetime
|
||||
from pathlib import Path
|
||||
|
||||
from app.learning.proposals import Proposal, write
|
||||
|
||||
REFERENCES = "references"
|
||||
_INDEX = re.compile(r"<!-- lessons:begin -->.*<!-- lessons:end -->", re.DOTALL)
|
||||
_ENTRY = re.compile(r"^## (L-\d+): .*?(?=^## L-\d+: |\Z)", re.MULTILINE | re.DOTALL)
|
||||
|
||||
|
||||
class NotApproved(ValueError):
|
||||
"""A lesson cannot be published: no person has approved its proposal."""
|
||||
|
||||
|
||||
def reference(skill_dir: Path, deliverable: str) -> Path:
|
||||
return skill_dir / REFERENCES / f"{deliverable}.md"
|
||||
|
||||
|
||||
def deliverables_with_lessons(skill_dir: Path) -> list[str]:
|
||||
folder = skill_dir / REFERENCES
|
||||
if not folder.is_dir():
|
||||
return []
|
||||
return sorted(
|
||||
path.stem
|
||||
for path in folder.glob("*.md")
|
||||
if _ENTRY.search(path.read_text(encoding="utf-8"))
|
||||
)
|
||||
|
||||
|
||||
def published(skill_dir: Path) -> dict[str, str]:
|
||||
"""Lesson id -> the Deliverable whose reference holds it."""
|
||||
found = {}
|
||||
for deliverable in deliverables_with_lessons(skill_dir):
|
||||
text = reference(skill_dir, deliverable).read_text(encoding="utf-8")
|
||||
for match in _ENTRY.finditer(text):
|
||||
found[match.group(1)] = deliverable
|
||||
return found
|
||||
|
||||
|
||||
def _entry(proposal: Proposal, today: str) -> str:
|
||||
return (
|
||||
f"## {proposal.id}: {proposal.title}\n\n"
|
||||
f"**Rule.** {' '.join(proposal.rule.split())}\n\n"
|
||||
f"**Why.** {' '.join(proposal.reason.split())}\n\n"
|
||||
f"Published {today}, from lesson proposal {proposal.number:02d}.\n"
|
||||
)
|
||||
|
||||
|
||||
def _write_reference(skill_dir: Path, deliverable: str, entries: list[str]) -> None:
|
||||
path = reference(skill_dir, deliverable)
|
||||
if not entries:
|
||||
path.unlink(missing_ok=True)
|
||||
return
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
title = deliverable.replace("_", " ")
|
||||
path.write_text(
|
||||
f"# Lessons: {title}\n\n"
|
||||
"Rules learned from earlier work. Follow every one that applies.\n\n"
|
||||
+ "\n".join(entries),
|
||||
encoding="utf-8",
|
||||
)
|
||||
|
||||
|
||||
def _entries(skill_dir: Path, deliverable: str) -> dict[str, str]:
|
||||
path = reference(skill_dir, deliverable)
|
||||
if not path.is_file():
|
||||
return {}
|
||||
text = path.read_text(encoding="utf-8")
|
||||
return {m.group(1): m.group(0).rstrip() + "\n" for m in _ENTRY.finditer(text)}
|
||||
|
||||
|
||||
def _reindex(skill_dir: Path) -> None:
|
||||
"""Rewrite the list of references in SKILL.md from the files that exist."""
|
||||
skill = skill_dir / "SKILL.md"
|
||||
rows = [
|
||||
f"| {name.replace('_', ' ')} | `{REFERENCES}/{name}.md` | "
|
||||
f"{len(_entries(skill_dir, name))} |"
|
||||
for name in deliverables_with_lessons(skill_dir)
|
||||
]
|
||||
table = (
|
||||
"| Deliverable | Reference | Lessons |\n| --- | --- | --- |\n" + "\n".join(rows)
|
||||
if rows
|
||||
else "No lessons have been published yet."
|
||||
)
|
||||
text = skill.read_text(encoding="utf-8")
|
||||
skill.write_text(
|
||||
_INDEX.sub(f"<!-- lessons:begin -->\n{table}\n<!-- lessons:end -->", text),
|
||||
encoding="utf-8",
|
||||
)
|
||||
|
||||
|
||||
def publish(
|
||||
proposal: Proposal, skill_dir: Path, *, today: date | None = None
|
||||
) -> Proposal:
|
||||
"""Write an approved lesson into the Skill and mark its proposal published.
|
||||
|
||||
Raises NotApproved for any proposal a person has not approved: nothing reaches
|
||||
an agent on a curator's say-so.
|
||||
"""
|
||||
if not proposal.approved:
|
||||
raise NotApproved(
|
||||
f"{proposal.id} is {proposal.status}; a person approves a lesson by "
|
||||
"setting its Status to ready-for-agent"
|
||||
)
|
||||
if not proposal.deliverable or not proposal.rule.strip():
|
||||
raise NotApproved(f"{proposal.id} has no Deliverable or no rule")
|
||||
stamp = (today or datetime.now(UTC).date()).isoformat()
|
||||
for deliverable in deliverables_with_lessons(skill_dir):
|
||||
if deliverable != proposal.deliverable:
|
||||
entries = _entries(skill_dir, deliverable)
|
||||
if entries.pop(proposal.id, None): # it moved to another Deliverable
|
||||
_write_reference(skill_dir, deliverable, list(entries.values()))
|
||||
entries = _entries(skill_dir, proposal.deliverable)
|
||||
entries[proposal.id] = _entry(proposal, stamp)
|
||||
ordered = [entries[key] for key in sorted(entries)]
|
||||
_write_reference(skill_dir, proposal.deliverable, ordered)
|
||||
_reindex(skill_dir)
|
||||
return write(replace(proposal, published=proposal.published or stamp))
|
||||
|
||||
|
||||
def retire(lesson_id: str, skill_dir: Path) -> bool:
|
||||
"""Remove a lesson from the Skill. Returns whether it was there."""
|
||||
deliverable = published(skill_dir).get(lesson_id)
|
||||
if deliverable is None:
|
||||
return False
|
||||
entries = _entries(skill_dir, deliverable)
|
||||
entries.pop(lesson_id)
|
||||
_write_reference(skill_dir, deliverable, [entries[key] for key in sorted(entries)])
|
||||
_reindex(skill_dir)
|
||||
return True
|
||||
@@ -69,6 +69,9 @@ class ProviderBundle:
|
||||
# The Terraform providers generated code is written for, pinned so the schema
|
||||
# lookup, the patterns and validation agree: {name: {source, version}}.
|
||||
terraform_providers: Mapping[str, Mapping[str, str]] = field(default_factory=dict)
|
||||
# The Skill approved lessons are published in (ADR-0004); None when the provider
|
||||
# has none. A Specialist is given it once it holds lessons for its Deliverable.
|
||||
lessons_skill: str | None = None
|
||||
|
||||
def mcp_servers_for_role(
|
||||
self, role: str, include_preview: bool = True
|
||||
@@ -194,6 +197,10 @@ def load_provider(name: str, root: Path | None = None) -> ProviderBundle:
|
||||
raise fail(f"pillar {pillar!r} references unknown skill {skill_name!r}")
|
||||
pillar_skills[str(pillar)] = skill_name
|
||||
|
||||
lessons_skill = config.get("lessons_skill") or None
|
||||
if lessons_skill is not None and lessons_skill not in skills:
|
||||
raise fail(f"'lessons_skill' references unknown skill {lessons_skill!r}")
|
||||
|
||||
return ProviderBundle(
|
||||
name=name,
|
||||
skills_dirs=skills_dirs,
|
||||
@@ -207,4 +214,5 @@ def load_provider(name: str, root: Path | None = None) -> ProviderBundle:
|
||||
role_skills=role_skills,
|
||||
pillar_skills=pillar_skills,
|
||||
terraform_providers=terraform_providers,
|
||||
lessons_skill=lessons_skill,
|
||||
)
|
||||
|
||||
Reference in New Issue
Block a user