myloop v1 (knowledge-distillation orchestrator)

/architect:myloop:loop — a hard-paired THINK → EXPERIMENT → DISTILL cycle over one frozen graph, driven by a user-authored goal.md. Maximizing agent performance is the goal; distilling understanding against that goal is the implementation mechanism the loop uses to get there, not an end in itself.

shape three-phase hard-paired loop   memory 8 typed files, no archive   termination goal-driven, not iter-capped   spawns/iter 2 sub-agents

The two-spawn split — why THINK and DISTILL are separate

ADAS-family variants fold "what just happened" into the next iter's THINK — one sub-agent spawn per iter, but THINK must digest the raw eval artifacts itself. myloop pays for a second spawn so each phase has a single cognitive task: DISTILL converts raw → typed memory while the iter's context is still warm; THINK plans the next experiment from that memory. THINK may still read raw logs — but narrowly, to pick the episodes for a targeted subset, not to digest a run. The split is by cognitive task and timing, not by log access:

The two spawns are not redundant. Each has a single cognitive task on focused input:

• THINK plans the next experiment. Its primary input is the 8 distilled files + the last 3 iters' record.json + the live workspace/. It MAY read raw eval logs — selectively — to construct a targeted (e.g. failure-mode) episode subset, but it does not digest a whole run.
• DISTILL digests the freshly-produced eval — its cognitive task is raw data → typed memory, not text → plan. The warm context (this iter's spec, think-trace, expected signal, raw per-ep traces all current) makes the conversion cheap.

The iteration cycle

The eight typed memory files

myloop deliberately fans out what ADAS keeps in one archive.jsonl into eight files, each one capturing a different kind of knowledge. Confusing the kinds is the fastest way to break the loop — e.g. logging "we tried gpt-4o and failed" into knowledge.md instead of experience.jsonl would treat a lesson as a fact.

The hypothesis lifecycle — a queue, not a log

The interplay between hypotheses.jsonl and experience.jsonl is the loop's central learning mechanic. A hypothesis is a liability — it owes the loop a test. Experience is an asset — a closed case that future THINKs can reason from without re-running the experiment.

Two consequences:

• Refuted hypotheses are first-class. A failed test closes the case just as cleanly as a confirmation; both append a full experience.jsonl entry. The loop doesn't distinguish "we proved it" from "we disproved it" — both are knowledge.
• Saturation is a real termination condition. "5 consecutive iters with no resolved hypothesis and no new knowledge" is a default termination predicate. When the queue stops moving and nothing new enters, the loop has reached the edge of what it can learn at the current goal — exit cleanly rather than grind.

Two channels of persistence

Within an iter, writes go to two different places. The atomic commit at iter-end only promotes one of them — the other is already on disk.

Run-dir layout

outputs/design_runs/myloop/{graph}/v{N}/
├── goal.md                   USER-AUTHORED, read-only to orchestrator
├── constraints.md            OPTIONAL — merged from 4 layers at bootstrap
├── knowledge.md              append-only facts
├── experience.jsonl          lessons learned
├── hypotheses.jsonl          open conjectures (mutable: line-delete)
├── experiment_design.yaml    eval-profile registry
├── tools/                    orchestrator-authored *.py utilities
│   └── *.py
├── iteration/                one subdir per committed iter
│   ├── iter_0/
│   │   ├── record.json           dense IterRecord
│   │   ├── spec.json             ExperimentSpec produced by THINK
│   │   ├── think_trace.md        THINK sub-agent forensic trace
│   │   ├── eval_metadata.json    run_id + aggregate metrics + per-ep summary
│   │   ├── distill.json          DISTILL output (omitted on SKIP_*)
│   │   ├── distill_trace.md      DISTILL sub-agent forensic trace
│   │   ├── active_workspace/     patched workspace overlay (if patch applied)
│   │   └── debug_log.md          EXPERIMENT apply-step smoke-retry history (if any)
│   └── iter_1/, iter_2/, ...
├── .staging/iter_M/          transient; mv'd to iteration/iter_M/ on commit
├── .loop_state/              bookkeeping for resume / termination
│   ├── last_committed_iter
│   └── consecutive_skips
└── SUMMARY.md                written at termination

Failure semantics — recovery by reasoning

myloop has no transactions, no revert chains, no rollback semantics. When things go wrong, the design is to archive the failure as evidence and let the next iter's THINK reason about it. The invariant: every committed iter has a think block and an experiment block, even if the experiment was "the patch failed smoke retry 3 times" or "the eval crashed at episode 2".

Goal and constraints — 4-layer governance

goal.md — required pre-flight

One # Goal header plus three ## sections. Both forms below are valid; the loop refuses to start with neither.

• Detailed: a pre-authored goal.md with all three sections (Ultimate / Escalation / Termination) non-empty. Partial files abort the run.
• One-liner: --goal "<text>" on the command line, with no goal.md yet present. The loop bootstraps goal.md using <text> as Ultimate plus built-in defaults for Escalation + Termination (3-tier escalation ladder probe/custom → search → perf; saturation + stuck + budget + cap termination predicates).

# Goal

## Ultimate
<one paragraph stating what this run is for.>

## Escalation
<plain-English rules for when to upgrade probe → search → perf.>

## Termination
<predicates; loop terminates on first match.
 e.g. "perf success ≥ 0.50"   (goal-achieved)
      "5 consecutive iters with no knowledge / hypothesis movement"
                                  (saturated)
      "cumulative GPU-min ≥ 600 OR LLM-tokens ≥ 5M"  (budget)>

constraints.md — 4-layer bootstrap merge

Hard MUST / MUST NOT rules — distinct from goal.md (direction) and knowledge.md (facts). At bootstrap, up to four layers are concatenated (in order, with ## --- from <source> --- audit headers) into vN/constraints.md. A pre-authored vN/constraints.md (user edited before invocation) is left untouched.

The merged file is injected into every THINK and DISTILL prompt as a non-negotiable preamble. THINK also does a coarse string-match guard on spec.patch.intent against constraint phrases (catches the obvious "intent describes changing planner_llm.config.profile while a constraint pins it" cases). Structured validators are deferred to v2.

Edit scope

Patches proposed by THINK and applied by the EXPERIMENT phase MAY target any path under workspace/: graph JSON, top-level nodesets, server-mode nodesets, env wrappers, policies, hooks. All edits land in iteration/iter_M/active_workspace/ (isolated overlay) and never pollute the frozen workspace/ tree. The AgentCanvas backend honors the overlay via the ACTIVE_WORKSPACE_DIR mechanism (ADR-components-009).

Outside workspace/ is never editable: agentcanvas/backend/app/** (framework code) and third_party/** (vendored upstream). The EXPERIMENT apply-step enforces this at the filesystem level (via _common/lib/overlay.py).

What myloop is NOT

myloop sits in the /architect:* skill family alongside ADAS-shape variants (adas-subagent, aflow). The shared piece is _common/ infrastructure — native overlay editing, smoke retry, edit whitelist, resolve protocol. The divergence is what they choose to track.

ADAS-shape variants optimize the archive. They generate candidate agents, score them on a fitness metric, keep the winners in a flat archive.jsonl, and run until cap or saturation. Failed generations are thrown out.

myloop optimizes the file system. Each iter's output is "what changed in the 8 working-memory files"; agent performance is one signal among many. Failed patches are archived as experience. The run ends when the user-authored goal.md § Termination says so — which may be a metric-threshold predicate or a saturation predicate ("nothing new learned in 5 iters") or a budget cap.

Deferred to v2

• knowledge.md append-only. v1 corrects by superseding bullets; v2 may add explicit supersede / retract semantics.
• Hypothesis priority ordering. v1 queue is flat; THINK picks based on prompt-time judgement. v2 may make priority first-class.
• Single-objective goal. v2 may compose direction + investigation + budget trade-off.
• tools/ runtime metadata. v1 has no usage count / last-used / deprecation marker.
• Critique pass on THINK. v1 is single-pass; if that proves too shallow on harder graphs, add a critique sub-agent.
• Structured constraints. v1 enforces by in-prompt injection + coarse jsonpath string-match. v2 may add a constraints.yaml with explicit validators.

Source files

Auto-rendered execution view of each .md file is at mirror/myloop/. The page you are reading is the hand-written, stable algorithm reference; the mirror is regenerated from the skill markdown by docs/pages/aas/build_mirror.py.