diff --git a/docs/design/82-maestro-policy-skill.md b/docs/design/82-maestro-policy-skill.md new file mode 100644 index 0000000..0e51e1f --- /dev/null +++ b/docs/design/82-maestro-policy-skill.md @@ -0,0 +1,90 @@ +# The maestro as a skill tree — orchestration policy, explicit (#465 S1) + +This is the maestro's orchestration written down as a **skill tree**: each tick +is a walk over the nodes below. Today the *tick executes this in Python* +(`runner/tick.py` + `runner/repairs.py`); this document is the explicit, +declarative form — the literal "one skill that explains to the maestro what to +do." It is the spec the interpreter seam (S2) will read, and the artifact the +self-improvement loop (S3) will evolve. + +## The hard boundary (read first) + +Every node is tagged: + +- **[HARD]** — mechanism or a safety gate. Deterministic Python. **NEVER** + interpreted from a skill, NEVER overridable by an evolved policy. The loop is + money- and merge-safe *because* these are code. A test must prove a tampered + policy cannot bypass any [HARD] node. +- **[SOFT]** — judgment/policy. Currently hardcoded, but legitimately + expressible as an interpreted + evolvable skill (S2/S3). Degrading a [SOFT] + node falls back to its documented default; it can never escalate privilege or + skip a [HARD] gate. + +## The tick, as a tree + +``` +tick +├─ 1. sense +│ ├─ [HARD] load Settings + Config (settings.py); resolve events log +│ ├─ [HARD] fetch open issues, open PRs, repo state (githubkit) +│ └─ [SOFT] axis filter: an issue is eligible iff it carries a matching +│ axis: (derived from .forge/axes.yaml names) AND loop:ready +│ +├─ 2. triage / shape work [SOFT] +│ ├─ [SOFT] PO expansion: a thin/underspecified ready ticket is rewritten to +│ │ the 5 falsifiable sections before dispatch (skip if already shaped) +│ └─ [SOFT] selection: which ready issue(s) to dispatch this tick, honoring +│ parallel cap; promotion of triage→ready in dep order when ready