control-graph

Load rule: This file is the formal SoT. Expand references/english-procedure.md only if a symbol, phase, or transition is still ambiguous after this spec. Expand references/clt-load-balance.md only if dual-actor load (human vs agent strain) is the decision under ambiguity.

// ── Signature ──────────────────────────────────────────────
CG          : control-graph (this skill)          // agent control plane procedure
Outer       : state machine | cyclic loop on Phases
Inner       : DAG | nested bounded loop
Phase ∈ { IDLE, ORIENT, PLAN, HITL_PLAN_GATE, EXECUTE,
          VERIFY, REPAIR, REVIEW_GATE, HITL_REVIEW,
          INTEGRATE, DONE, CANCELLED, BLOCKED }
Card        : Control Card (writable phase/budget/step surface)
Role ∈ { fast, explore, coding, deep, review }
HITL        : human-in-the-loop gate
HOOTL       : human-out-of-the-loop (auto-clear only when safe)
Budget      : { max_loop_iters, max_repair_rounds, max_step_retries,
                max_tool_calls_per_step, no_progress, wall_clock? }
Load        : { intrinsic, extraneous, germane } × Actor ∈ { human, agent }
                // CLT dual-actor; see A8 + clt-load-balance.md

// ── Axioms (never violate) ─────────────────────────────────
A1  Outer is explicit on Card  — never only in chat memory
A2  EXECUTE ⊆ finite Inner     — no open-ended ReAct
A3  Progress ≔ new evidence (diff | test | decision) on Card
A4  Budget exhaust ∨ no_progress×2  →  STOP | HITL | re-PLAN  (never silent thrash)
A5  Review ⊥ ImplementerContext     // fresh inputs: plan + diff + logs
A6  Domain skills ⊨ data plane;  CG ⊨ control plane only
A7  Evaluate(δ) ≔ (Correctness, Effectiveness, Efficiency)
A8  DualLoad — minimize Extraneous for Human ∧ Agent; preserve Germane for both;
    chunk Intrinsic by actor; Parallel/switch capacity: Agent ≥ Human
    (do not serialize independent Inner steps solely to match human WM)

// ── Mission ────────────────────────────────────────────────
Keep agent creativity, wrap it in deterministic skeleton:
  Outer(phase, transition, HITL) + Inner(DAG|subloop, done_when, retry)
  — with CLT budgets so neither actor burns capacity on waste

Activate / Skip

SkillLoad(ORIENT) ≔ description-match ∨ explicit-attach
                  ¬ catalog-dump ¬ skills-repo-grep
// Prefix filters (ai-*, web-*, …) = harness-side when present

Outer graph (state machine / loop)

                    ┌──────────────┐
                    │    IDLE      │
                    └──────┬───────┘
                           │ goal accepted
                           ▼
                    ┌──────────────┐
              ┌────►│   ORIENT     │◄── resume / re-orient
              │     └──────┬───────┘
              │            ▼
              │     ┌──────────────┐
              │     │    PLAN      │──► HITL_PLAN_GATE?
              │     └──────┬───────┘
              │            ▼
              │     ┌──────────────┐     Inner DAG / nested loop
              │     │   EXECUTE    │◄────────────────────────┐
              │     └──────┬───────┘                         │
              │            ▼                                 │
              │     ┌──────────────┐  fail+budget      ┌─────┴──────┐
              │     │   VERIFY     │──────────────────►│   REPAIR   │
              │     └──────┬───────┘                   └────────────┘
              │            │ pass
              │            ▼
              │     ┌──────────────┐
              │     │ REVIEW_GATE  │──► HITL_REVIEW?
              │     └──────┬───────┘
              │            ▼
              │     ┌──────────────┐
              │     │  INTEGRATE   │
              │     └──────┬───────┘
              │     more?──yes──► PLAN (gap only)
              │            │ no
              │            ▼
              │     ┌──────────────┐
              └─────│ DONE | CANCELLED | BLOCKED
                    └──────────────┘

Phase contract

Transitions (guards)

Budgets (defaults — set on Card before EXECUTE)

Dual-actor load (CLT middle ground)

Diagnose on Card before heavy EXECUTE. Formal detail: references/clt-load-balance.md.

Middle ground: remove shared waste (extraneous strain for AI and human); keep productive struggle (germane); allow machine multitasking where steps are independent — do not impose human working-memory caps on agent fan-out.

Inner graph (DAG | nested loop)

∀ step in EXECUTE batch:

id, name, depends_on[], done_when, retry ∈ 0..max_step_retries,
on_fail ∈ { abort_batch, continue_siblings, escalate_HITL },
cancel_when, model_role, inputs (minimal), outputs (re-enter Outer)

Rules

1. Bound first — write step list before tools; default ≤7 steps/batch
2. One primary outcome per step
3. Parallel ⇔ independent paths → concurrent-cli-agents + subagent-delegation — prefer fan-out when safe (A8); never parallelize to dump concurrent asks on the human
4. Re-enter Outer with {step_id, status, artifacts, errors, next_hint} — not full transcript
5. Nested loop allowed only if it inherits budgets + done_when (no nested unbounded ReAct)
6. Cancel is first-class — leave tree consistent; reason on Card

EXECUTE → topo(Inner) | parallel(independent)
       → ∀ step: until done_when | retry | fail
       → aggregate → VERIFY

Model routing

Single-model host: simulate roles via phase prompts; reset context for review.

Handoff: phase, step_id, status, artifacts[], verify_commands[], open_risks[]
Parent Outer owns transitions. Workers never jump PLAN→DONE.

HITL gates

Pause (no further EXECUTE side effects) when any:

Domain guards stay in domain skills; CG requires honoring pause results as Outer transitions.

Composition (no duplication)

CG = control plane · domain = data plane · orchestrator = multi-worker logistics · CLT pre-filter = DualLoad hygiene for Human∧Agent.

Anti-patterns

Control Card (minimum)

Copy references/control-card.md or:

## Control Card
- goal: …
- phase: ORIENT | PLAN | EXECUTE | VERIFY | REPAIR | REVIEW_GATE | INTEGRATE | HITL_* | DONE | …
- plan (success criteria): …
- verify commands: …
- budgets: max_loop_iters=8 rem=_; max_repair_rounds=3 rem=_; max_step_retries=2
- load_diag: actor=human|agent|both ; dominant=intrinsic|extraneous|germane ; intervene=…
- inner_mode: standard | eva
- pathway_active: (optional; when inner_mode=eva)
- token_envelope: (optional; handoff_max_tokens / prefer ai-optimization before EXECUTE)
- steps (DAG|subloop): S1 … / depends / done_when / role
- model_role now: fast | explore | coding | deep | review
- last progress: …
- pause reason: (none | signpost_fired | pathway_switch | …)
- handoff: artifacts / open_risks (compact — not transcripts)

Update Card on every phase transition. If phase unnameable → unbounded ReAct → stop → ORIENT.

Quick procedure

1. Triage (agent-orchestrator): single-shot? → do it; skip CG
2. Open Card; phase=ORIENT; set budgets; optional load_diag (A8)
3. PLAN + verify cmds; HITL if high stakes (human gate: low extraneous, high germane)
4. Route Role; write Inner DAG|subloop — parallel when independent
5. EXECUTE bounded; handoffs only
6. VERIFY real cmds; REPAIR gaps only (budgeted)
7. REVIEW_GATE / HITL when required
8. INTEGRATE + report; surplus if fusion applies
9. DONE or narrow re-PLAN for remaining gap only

Portable wiring

Rename note: formerly looper. Same contract; name matches Outer SM/loop + Inner DAG/nested-loop graph.

Reference (progressive disclosure)

• English expansion (only if needed): references/english-procedure.md
• CLT dual-actor load (only if needed): references/clt-load-balance.md
• Card template: references/control-card.md
• Library formal kernel: ../formal/AppGenMathPhyLang.kernel.md
• Thesis: @Peramanathan structured loops

Creativity inside the edges — never instead of them. Capacity for the work that builds capability — for both minds in the loop.