Files
gcp_solution_architecture_a…/app/learning/skill.py
Jonathan Boniface 71da0ed504
Some checks failed
validation / verify (push) Failing after 12s
chore: housekeeping from the runs of 2026-10-09
- An Execution's files are written as each Deliverable is submitted, marked
  in_progress, so a killed process or one waiting for its user leaves them on
  disk. A write removes files an earlier write left that it no longer has.
- A question about delivered work is answered from that Execution's solution
  guide by the reply writer; a question about the service is answered as
  before. Nothing is started for either.
- Lessons: prove writes only for lessons the Skill holds; the Skill records
  the vendored Skill versions the lessons were read against, status names any
  that changed, and a test fails until they are reviewed.
- Four more code patterns: Firestore, BigQuery, Eventarc and GKE.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-10 11:44:38 +01:00

184 lines
6.7 KiB
Python

"""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 json
import re
from collections.abc import Mapping
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))
# The versions of the Skills the lessons were written beside, kept in the lessons
# Skill. A lesson is a correction to how agents follow those Skills, so when one
# of them changes each lesson is worth a second look: it may now be said upstream,
# or contradict it.
UPSTREAM_FILE = "upstream.json"
def upstream_reviewed(skill_dir: Path) -> dict[str, str]:
"""The upstream Skill versions the lessons were last reviewed against."""
path = skill_dir / UPSTREAM_FILE
if not path.is_file():
return {}
try:
data = json.loads(path.read_text(encoding="utf-8"))
except ValueError:
return {}
return {str(k): str(v) for k, v in data.items()} if isinstance(data, dict) else {}
def mark_reviewed(skill_dir: Path, current: Mapping[str, str]) -> None:
"""Record that the lessons stand against these upstream Skill versions."""
(skill_dir / UPSTREAM_FILE).write_text(
json.dumps(dict(sorted(current.items())), indent=2) + "\n", encoding="utf-8"
)
def upstream_changes(skill_dir: Path, current: Mapping[str, str]) -> list[str]:
"""The upstream Skills that changed, appeared or went since the lessons were
last reviewed. Empty when there are no lessons, or nothing was ever recorded."""
reviewed = upstream_reviewed(skill_dir)
if not reviewed or not published(skill_dir):
return []
return sorted(
name
for name in set(reviewed) | set(current)
if reviewed.get(name) != current.get(name)
)
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