loop-system

Loop System

Goal-driven loops: an independent verifier grades a maker's work against hard criteria, memory persists across manually-restarted sessions in markdown, lessons compound into skills. The model is stateless; this system isn't.

State lives at $MINDGAP_HOME/learning/loop-system/. If a file is missing, create it from templates/<name>.stub.md — a fresh install starts with empty ledgers.

Dispatch — do this first

Scan self-learning-loop/*/STATE.md under the project root:

• None found → INIT.
• Exactly one → resume it — unless the user's prompt states a goal that does not match that loop's GOAL.md section 1; then INIT a new loop alongside it.
• Several → resume the one named in the user's prompt. Ambiguous → list each loop (name + its Last session line) and ask which.

INIT

1. Interview for the hard gate. Skim $MINDGAP_HOME/learning/loop-system/lessons.md and $MINDGAP_HOME/learning/loop-system/global-learnings.md for recorded misfires + cross-project rules first (mindgap MCP available → also mindgap_find the goal's keywords with tag global-learning). GOAL.md (templates/GOAL.md) has 7 required fields. Derive everything you can from the user's prompt first; ask one question at a time only for what's missing. The loop MUST NOT start until all 7 fields are filled — an unmeasurable gate means the verifier can never return PASS and the loop burns budget without converging.
   • Done-criteria must be measurable and checkable by a verifier that sees only the artifact. "Make it better" is not a criterion.
   • Satisfiability: a criterion must be able to PASS when the work is done well, not only fail when it isn't. When a criterion bounds a rate over simulated or sampled data (divergence-free fraction, coverage, acceptance rate), pilot it on ≥ 5 prior/simulated draws before the gate closes, or mark it provisional in GOAL §2 until the first pilot. A bar the method can't reach at part of the prior only surfaces sessions later, as an escalation (popinf-gates criterion 5, 2026-09-23).
   • Executability: when the artifact must run against an external system (SQL, an API request, a shell command), add a criterion that actually exercises it cheaply — a BigQuery dry_run, a request-schema validation, a --dry-run/-n parse — not only substring or mocked asserts. An all-offline PASS is proxy-complete, never final, until the artifact has run for real: offline asserts passed 7/7 on SQL that did not parse (lessons.md 2026-07-02).
   • If the user can't supply a measurable criterion, propose a proxy: a verifier checklist of N observable properties. If they decline proxies too, refuse to loop — do the task one-shot and say why.
2. Pick the engine per the decision rule in references/loop-patterns.md — default is workflow; use Shape 1 only for a single artifact refined in place (N=1, no parallelism) or a runtime with no workflow engine. Record choice + one-line reason in GOAL.md §7. Non-git project → note "no worktrees, sequential makers" in GOAL.md §7.
3. Scaffold self-learning-loop/<loop-name>/ in the project root:
   • <loop-name> = short kebab-case slug from the goal; offer the user the chance to rename.
   • Copy templates/GOAL.md and templates/STATE.md, fill every {{field}}. Zero {{...}} may survive scaffolding.
   • Resolve §6 routing: ceiling = the current session model (auto-detected from the in-context "powered by …" line, never asked); classifier-block sibling = opus when the ceiling is fable, else none; seed the task-class list with kebab labels derived from §2 done-criteria. The only absolute model names written are the alias-ladder constant and the resolved sibling. Advisor = fable-subagent when the ceiling is below fable and the alias spawns, else none (references/advisor-protocol.md). An opus/high orchestrator + fable advisor is the recommended setup; the advisor is the only sanctioned fable subagent (read-only, ≤3 calls/session).
   • Fill §4 auto-mode defaults (auto mode is ON by default): write Auto mode: on, Total budget ceiling = Max sessions × Max iterations per session, and the standard Stop-and-notify trigger set. A manual mode loop instead sets Auto mode: off (ceiling/triggers become informational). Seed STATE.md § Auto mode (status = the §4 value; budget spent: 0 / <ceiling>; everything else none/no). Then print ONE line to the user: "Auto mode ON (default): self-continues up to total iterations, halts+notifies on ; say 'manual mode' to disable."
   • Optional retrieval-policy artifact: if the loop tunes a selection/retrieval policy across sessions (which sources / queries / filters / connection heuristics to use — a discovery, mining, or scan loop), copy templates/STRATEGY.md, seed §1–§2 from the goal, and add it to STATE.md ## Consult. It is the separately-tuned structure-loop substrate (see references/structure-pass.md); a loop with a fixed one-shot policy skips it.
   • Create empty artifacts/ dir.
   • Seed the project ledger: if <project>/.claude/PROJECT-LEARNINGS.md is absent, create it from ../loop-distill/templates/PROJECT-LEARNINGS.md (sibling skill, relative to this skill's base dir), filling its placeholders — {{project-name}} = this project, and replace the header line "Distilled by loop-distill {{YYYY-MM-DD}}" with "Seeded by loop-system INIT <today's date> — not yet distilled." No distill has run, and RESUME step 1 reads this file every session; a header claiming a distill that never happened is a false claim every later session inherits. Zero {{...}} may survive. Then register this loop in its §2. Seeded from the FIRST loop, not the second — the project layer exists before there is anything to reconcile.
4. Optional project skill: if lessons will be procedural and project-scoped, offer to create <project>/.claude/skills/<loop-name>-lessons/SKILL.md from templates/project-skill.md. Only with user approval.
5. Permissions (with user approval): unattended sessions stall on permission prompts, so offer to write <project>/.claude/settings.local.json allowing exactly what the loop needs — Edit/Write plus the specific Bash commands derived from GOAL.md's done-criteria checks and the project's build/test commands, e.g.: