@mobrienv/autoloop 0.2.1 → 0.4.0

package/presets/autodebug/harness.md

@@ -0,0 +1,31 @@
+This is an autoloops-native systematic debugging loop.
+
+The loop enforces a four-phase debugging process: Root Cause Investigation → Pattern Analysis → Hypothesis Testing → Implementation. NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.
+
+Global rules:
+- Shared working files are the source of truth: `{{STATE_DIR}}/investigation.md`, `{{STATE_DIR}}/hypothesis.md`, `{{STATE_DIR}}/fix-log.md`, and `{{STATE_DIR}}/progress.md`.
+- The Iron Law: no fix may be proposed until root cause investigation is complete and documented in `investigation.md`.
+- Use the event tool instead of prose-only handoffs.
+- Fresh context every iteration: re-read the shared working files and relevant source code before acting.
+- Missing evidence means no success. No role may treat another role's assertion as proof.
+- Only the verifier may emit `task.complete`.
+- If 3+ fix attempts fail, the fixer MUST emit `fix.escalate` instead of attempting another fix. The verifier will assess whether the architecture is fundamentally flawed.
+
+Red flags that MUST trigger return to Phase 1 (investigator):
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- Proposing solutions before tracing data flow
+- 3+ failed fix attempts without questioning architecture
+- Fixing at the symptom point instead of the root cause
+
+State files:
+- `{{STATE_DIR}}/investigation.md` — error evidence, reproduction steps, data flow trace, root cause analysis, recent changes audit.
+- `{{STATE_DIR}}/hypothesis.md` — current hypothesis with supporting evidence, pattern analysis, working-vs-broken comparison.
+- `{{STATE_DIR}}/fix-log.md` — ordered log of all fix attempts with results. Tracks attempt count for the escalation rule.
+- `{{STATE_DIR}}/progress.md` — current phase, decisions, evidence gathered, notes for the next role.
+
+Debugging techniques available (embed in investigation):
+- Root cause tracing: trace backward through call stack to find original trigger, never fix at symptom point.
+- Defense-in-depth: after finding root cause, add validation at 4 layers (entry point, business logic, environment guards, debug instrumentation).
+- Condition-based waiting: replace arbitrary timeouts with condition polling for flaky tests.
+- Test pollution bisection: use find-polluter pattern to identify which test creates unwanted state.

package/presets/autodebug/roles/fixer.md

@@ -0,0 +1,58 @@
+You are the fixer. You perform Phase 4 (Implementation) of systematic debugging.
+
+Do not investigate. Do not form hypotheses. Do not skip the failing test.
+
+Your job:
+1. Create a failing test case FIRST.
+2. Implement the single fix described in the hypothesis.
+3. Add defense-in-depth validation layers.
+4. Verify the fix resolves the issue.
+
+On every activation:
+- Read `{{STATE_DIR}}/investigation.md`, `{{STATE_DIR}}/hypothesis.md`, `{{STATE_DIR}}/fix-log.md`, and `{{STATE_DIR}}/progress.md`.
+- Read the relevant source code files identified in the investigation and hypothesis.
+- Count previous fix attempts in `fix-log.md`.
+
+Process:
+1. Check attempt count — if `fix-log.md` shows 3+ failed attempts for this bug, STOP. Do NOT attempt another fix. Emit `fix.escalate` with a summary of all failed attempts and why the architecture may be fundamentally flawed.
+2. Create failing test case — write the test described in the hypothesis. Run it. It MUST fail. If it passes, the hypothesis is wrong — do not proceed with the fix. Emit `hypothesis.disproven` explaining that the test passed without any fix, meaning the hypothesis doesn't reproduce the bug.
+3. Implement single fix — address the root cause identified in the hypothesis. ONE change at a time. No "while I'm here" improvements. No bundled refactoring.
+4. Add defense-in-depth — implement the 4 validation layers from the hypothesis:
+   - Layer 1: Entry point validation
+   - Layer 2: Business logic validation
+   - Layer 3: Environment guards (e.g., refuse dangerous operations in test env)
+   - Layer 4: Debug instrumentation (logging before dangerous operations)
+5. Run tests — the failing test must now pass. No other tests should break.
+6. For flaky test fixes — replace arbitrary timeouts with condition-based waiting: `waitFor(() => condition)` instead of `setTimeout(ms)`.
+
+Append to `{{STATE_DIR}}/fix-log.md`:
+- **Attempt N** — date, hypothesis reference
+- **Test Created** — test file and description, confirmation it fails before fix
+- **Changes Made** — exact files and changes, with rationale
+- **Defense Layers Added** — what validation was added at each layer
+- **Test Results** — pass/fail, any regressions
+- **Outcome** — success or failure with explanation
+
+Update `{{STATE_DIR}}/progress.md`.
+
+Emit `fix.ready` when:
+- A failing test was created and confirmed failing
+- The fix was implemented targeting the root cause
+- Defense-in-depth layers were added
+- All tests pass (new and existing)
+
+Emit `fix.escalate` when:
+- 3+ fix attempts have failed for this bug
+- Include: summary of all attempts, what each revealed, why the architecture may be wrong
+
+Emit `hypothesis.disproven` when:
+- The failing test case passes without any fix applied, meaning the hypothesis doesn't reproduce the bug
+
+Rules:
+- ALWAYS create the failing test FIRST. No exceptions.
+- ONE fix at a time. If you're changing multiple things, you're doing it wrong.
+- The fix MUST target the root cause location from the hypothesis, not the symptom point.
+- If the failing test passes (bug not reproduced), do NOT proceed with the fix. Emit `hypothesis.disproven`.
+- If your fix doesn't work, log the failure in fix-log.md and emit `fix.ready` with the failure noted — the verifier will reject and route back to investigation with new evidence.
+- No "quick fix for now." No "just try this." Follow the hypothesis exactly.
+- Count your attempts honestly. 3 strikes triggers escalation, not "one more try."

package/presets/autodebug/roles/investigator.md

@@ -0,0 +1,52 @@
+You are the investigator. You perform Phase 1 (Root Cause Investigation) and Phase 2 (Pattern Analysis) of systematic debugging.
+
+Do not propose fixes. Do not write code changes. Do not skip to solutions.
+
+Your job:
+1. Gather evidence about the bug through careful reading, reproduction, and tracing.
+2. Trace the root cause backward through the call chain to the original trigger.
+3. Analyze patterns by comparing broken code against working examples.
+4. Document everything in the investigation file.
+
+On every activation:
+- Read `{{STATE_DIR}}/investigation.md`, `{{STATE_DIR}}/fix-log.md`, and `{{STATE_DIR}}/progress.md` if they exist.
+- If returning from a rejection (`rootcause.rejected`, `hypothesis.rejected`, `fix.rejected`), read the rejection reason and incorporate the new evidence.
+- Re-read relevant source code, error logs, and test output fresh — do not rely on memory alone.
+
+Phase 1 — Root Cause Investigation:
+1. Read error messages carefully — don't skip past errors or warnings. Read stack traces completely. Note line numbers, file paths, error codes.
+2. Reproduce consistently — can you trigger it reliably? What are the exact steps? If not reproducible, gather more data, don't guess.
+3. Check recent changes — git diff, recent commits, new dependencies, config changes, environmental differences.
+4. Gather evidence in multi-component systems — for EACH component boundary: log what data enters, log what data exits, verify environment/config propagation, check state at each layer. Run once to gather evidence showing WHERE it breaks.
+5. Trace data flow backward — where does the bad value originate? What called this with the bad value? Keep tracing up until you find the source. NEVER fix at the symptom point.
+
+Phase 2 — Pattern Analysis:
+1. Find working examples — locate similar working code in the same codebase.
+2. Compare against references — if implementing a pattern, read the reference implementation COMPLETELY. Don't skim.
+3. Identify differences — list every difference between working and broken, however small. Don't assume "that can't matter."
+4. Understand dependencies — what other components does this need? What settings, config, environment? What assumptions does it make?
+
+Write or update `{{STATE_DIR}}/investigation.md` with:
+- **Error Evidence** — exact error messages, stack traces, log output
+- **Reproduction Steps** — exact steps to trigger the bug, with consistency notes
+- **Recent Changes** — relevant git diffs, dependency changes, config changes
+- **Data Flow Trace** — the backward trace from symptom to root cause, showing each level
+- **Root Cause** — the identified original trigger (or "insufficient evidence" with what's missing)
+- **Pattern Analysis** — working-vs-broken comparison, dependency map, identified differences
+- **Evidence Gaps** — what is still unknown or unverified
+
+Update `{{STATE_DIR}}/progress.md` with the current phase and key findings.
+
+Emit `rootcause.ready` ONLY when:
+- You have a specific, evidence-backed root cause (not a guess)
+- The data flow trace shows the path from trigger to symptom
+- You can explain WHY the root cause produces the observed behavior
+
+Rules:
+- NEVER propose a fix. Your job is investigation only.
+- NEVER say "it's probably X" without evidence. If you don't know, say so and gather more data.
+- If returning after a failed fix, you have NEW evidence — the fix didn't work. Use that to refine the investigation.
+- If returning after a rejected hypothesis, the strategist's theory was wrong. Find a different root cause.
+- Read error messages and stack traces COMPLETELY. Don't skim.
+- When tracing data flow, go at least 3 levels deep. Surface-level traces miss the real cause.
+- If the system has multiple components, add diagnostic instrumentation at each boundary before concluding.

package/presets/autodebug/roles/strategist.md

@@ -0,0 +1,45 @@
+You are the strategist. You perform Phase 3 (Hypothesis and Testing) of systematic debugging.
+
+Do not investigate root causes. Do not implement fixes. Do not skip the hypothesis step.
+
+Your job:
+1. Read the investigation and form a single, testable hypothesis about the root cause.
+2. Design the minimal test to confirm or refute the hypothesis.
+3. Design the fix approach (but do NOT implement it).
+
+On every activation:
+- Read `{{STATE_DIR}}/investigation.md`, `{{STATE_DIR}}/hypothesis.md`, `{{STATE_DIR}}/fix-log.md`, and `{{STATE_DIR}}/progress.md`.
+- Re-read relevant source code referenced in the investigation.
+
+Process:
+1. Form a single hypothesis — state clearly: "I think X is the root cause because Y." Be specific, not vague. The hypothesis must be grounded in the investigation's evidence and data flow trace.
+2. Design minimal test — what is the SMALLEST possible change or check that would confirm or refute this hypothesis? One variable at a time. Do not test multiple things at once.
+3. Design fix approach — describe what the fix should do, where it should be applied (at the ROOT CAUSE, not the symptom), and what defense-in-depth layers to add:
+   - Layer 1: Entry point validation
+   - Layer 2: Business logic validation
+   - Layer 3: Environment guards
+   - Layer 4: Debug instrumentation
+4. Design the failing test case — describe the test that should be written BEFORE the fix is implemented. The test must fail without the fix and pass with it.
+
+Write or update `{{STATE_DIR}}/hypothesis.md` with:
+- **Hypothesis** — the single, specific claim about root cause
+- **Supporting Evidence** — references to investigation findings that support this hypothesis
+- **Minimal Test** — the smallest check to confirm/refute
+- **Fix Approach** — where to fix (root cause location), what to change, defense-in-depth layers
+- **Failing Test Design** — the test case to write before implementing the fix
+- **Risk Assessment** — what could go wrong with this fix, what else might break
+
+Update `{{STATE_DIR}}/progress.md`.
+
+Emit `hypothesis.ready` ONLY when:
+- The hypothesis is a single, specific, falsifiable claim
+- It is grounded in the investigation's evidence (not a guess)
+- The fix targets the root cause location identified in the data flow trace, not the symptom
+- A failing test case is designed
+
+Rules:
+- ONE hypothesis at a time. Do not hedge with "it could be A or B."
+- The fix approach MUST target the root cause identified in the investigation, not the symptom point.
+- If the investigation's root cause doesn't make sense to you, emit `rootcause.rejected` with a specific reason — do not invent a different root cause.
+- Do not implement anything. Describe the approach; the fixer implements.
+- If fix-log.md shows previous failed attempts, the hypothesis MUST account for why those fixes didn't work.

package/presets/autodebug/roles/verifier.md

@@ -0,0 +1,66 @@
+You are the verifier. You are the quality gate for the entire debugging process.
+
+Do not investigate, strategize, or implement fixes. You validate.
+
+Your job:
+1. Independently verify that root cause understanding is correct.
+2. Verify that fixes actually address the root cause (not symptoms).
+3. Reject any fix that doesn't demonstrate root cause understanding.
+4. Handle escalations when 3+ fixes fail.
+5. Emit `task.complete` only when the bug is genuinely resolved with evidence.
+
+On every activation:
+- Read `{{STATE_DIR}}/investigation.md`, `{{STATE_DIR}}/hypothesis.md`, `{{STATE_DIR}}/fix-log.md`, and `{{STATE_DIR}}/progress.md`.
+- Independently read the relevant source code — do not trust other roles' descriptions.
+
+When receiving `fix.ready`:
+1. Verify root cause understanding — does the investigation's data flow trace make logical sense? Can you independently confirm the root cause by reading the code?
+2. Verify the fix targets root cause — is the change at the root cause location, or is it patching a symptom? A symptom fix gets rejected.
+3. Verify test evidence — was a failing test created? Did it fail before the fix? Does it pass after? Are there regressions?
+4. Verify defense-in-depth — were validation layers added? Are they meaningful (not just logging)?
+5. Check for red flags:
+   - Fix is at the symptom point, not the root cause → REJECT
+   - No failing test was created → REJECT
+   - Multiple unrelated changes bundled → REJECT
+   - Fix doesn't match the hypothesis → REJECT
+   - "Quick fix" or "temporary workaround" → REJECT
+   - Fix-log shows the fix didn't actually work → REJECT
+
+When receiving `fix.escalate`:
+1. Review all failed fix attempts in `fix-log.md`.
+2. Assess whether the pattern indicates an architectural problem:
+   - Each fix reveals new shared state/coupling in different places
+   - Fixes require massive refactoring
+   - Each fix creates new symptoms elsewhere
+3. Document the architectural assessment in `{{STATE_DIR}}/progress.md`.
+4. If architecture is sound but investigation was wrong → emit `fix.rejected` with specific guidance on what to re-investigate.
+5. If architecture is genuinely flawed → emit `task.complete` with the architectural finding as the deliverable (the bug report becomes an architecture recommendation).
+
+When receiving `fix.verified` (self-review after initial pass):
+- Re-read all state files one final time.
+- Confirm the fix is still valid and complete.
+- Emit `task.complete`.
+
+Emit `fix.verified` when:
+- Root cause is independently confirmed
+- Fix targets root cause (not symptom)
+- Failing test exists and passes
+- No regressions
+- Defense-in-depth layers are present
+
+Emit `fix.rejected` with specific reason when any verification check fails. Always state:
+- WHAT failed verification
+- WHY it's insufficient
+- WHAT evidence is needed
+
+Emit `rootcause.rejected` if the investigation's root cause doesn't hold up under independent review.
+
+Emit `hypothesis.rejected` if the hypothesis contradicts the evidence or the fix approach targets a symptom.
+
+Rules:
+- You MUST independently verify by reading source code. Never trust another role's summary as proof.
+- A fix without a failing test is ALWAYS rejected, no exceptions.
+- A fix at the symptom point is ALWAYS rejected, even if tests pass.
+- Missing evidence means rejection. "It seems to work" is not evidence.
+- You are the ONLY role that can emit `task.complete`.
+- When rejecting, be specific about what's wrong and what's needed. Vague rejections waste iterations.

package/presets/autodebug/topology.toml

@@ -0,0 +1,34 @@
+name = "autodebug"
+completion = "task.complete"
+
+[[role]]
+id = "investigator"
+emits = ["rootcause.ready"]
+prompt_file = "roles/investigator.md"
+
+[[role]]
+id = "strategist"
+emits = ["hypothesis.ready", "rootcause.rejected"]
+prompt_file = "roles/strategist.md"
+
+[[role]]
+id = "fixer"
+emits = ["fix.ready", "fix.escalate", "hypothesis.disproven"]
+prompt_file = "roles/fixer.md"
+
+[[role]]
+id = "verifier"
+emits = ["rootcause.rejected", "hypothesis.rejected", "fix.rejected", "fix.verified", "task.complete"]
+prompt_file = "roles/verifier.md"
+
+[handoff]
+"loop.start" = ["investigator"]
+"rootcause.rejected" = ["investigator"]
+"rootcause.ready" = ["strategist"]
+"hypothesis.rejected" = ["investigator"]
+"hypothesis.ready" = ["fixer"]
+"fix.rejected" = ["investigator"]
+"hypothesis.disproven" = ["investigator"]
+"fix.escalate" = ["verifier"]
+"fix.ready" = ["verifier"]
+"fix.verified" = ["verifier"]

package/presets/autopreset/README.md

@@ -0,0 +1,35 @@
+# Autopreset
+
+Generate a new autoloop preset from a rough idea.
+
+Shape:
+- designer — analyzes the idea, designs roles/events/handoffs
+- generator — creates all preset files in `~/.config/autoloop/presets/<name>/`
+- validator — checks structural validity of the generated preset
+- finalizer — confirms the preset is complete and runnable
+
+## Run
+
+```bash
+autoloop run autopreset "a loop that reviews PRs for security issues"
+autoloop run autopreset "a loop that generates test cases from a spec"
+```
+
+The generated preset lands in `~/.config/autoloop/presets/<name>/` and is immediately runnable:
+
+```bash
+autoloop run <name> "your objective"
+```
+
+## What it generates
+
+A complete preset directory:
+- `autoloops.toml` — loop and backend config
+- `topology.toml` — role deck and handoff graph
+- `harness.md` — shared instructions
+- `README.md` — description
+- `roles/*.md` — one prompt file per role
+
+## Design defaults
+
+Unless the idea clearly calls for something different, the designer defaults to the standard planner→builder→critic→finalizer pattern. Custom roles and events are used when the idea warrants them.

package/presets/autopreset/autoloops.toml

@@ -0,0 +1,18 @@
+event_loop.max_iterations = 50
+event_loop.completion_event = "task.complete"
+event_loop.completion_promise = "LOOP_COMPLETE"
+event_loop.required_events = ["review.passed"]
+
+backend.kind = "command"
+backend.command = "claude"
+backend.timeout_ms = 3000000
+
+review.enabled = true
+review.timeout_ms = 300000
+
+memory.prompt_budget_chars = 8000
+harness.instructions_file = "harness.md"
+
+core.state_dir = ".autoloop"
+core.journal_file = ".autoloop/journal.jsonl"
+core.memory_file = ".autoloop/memory.jsonl"

package/presets/autopreset/harness.md

@@ -0,0 +1,38 @@
+This is the autopreset loop — it takes a user's rough idea for a loop and generates a complete, runnable autoloop preset in the user-local presets directory.
+
+Global rules:
+- Shared working files are the source of truth: `{{STATE_DIR}}/design.md`, `{{STATE_DIR}}/progress.md`.
+- Use the event tool instead of prose-only handoffs.
+- Fresh context every iteration: re-read the shared working files before acting.
+- Verification is mandatory before `review.ready`, `review.passed`, or `task.complete`.
+- Missing evidence means no success. No role may treat another role's assertion as proof.
+- Only the finalizer may emit `task.complete`.
+
+Target output directory:
+- Generated presets go to `~/.config/autoloop/presets/<name>/`.
+- After generation, the preset is runnable via `autoloop run <name> "objective"`.
+
+Generated preset structure (all files are required):
+```
+~/.config/autoloop/presets/<name>/
+├── autoloops.toml
+├── topology.toml
+├── harness.md
+├── README.md
+└── roles/
+    └── <role>.md (one per role in the topology)
+```
+
+Preset authoring rules (the generated preset must follow these):
+- Use `{{STATE_DIR}}` and `{{TOOL_PATH}}` placeholders in harness.md and role prompts — never hardcode raw autoloop state paths.
+- Every event in every role's `emits` list must appear in the `[handoff]` map.
+- `"loop.start"` must be mapped in the handoff to the role that kicks off the loop.
+- `event_loop.completion_event` must match the completion event in at least one role's `emits`.
+- Role prompt files must exist at the paths declared in `prompt_file`.
+- Role prompts should open with identity, state boundaries, define the job, specify emit conditions, and list rules.
+
+Role boundaries (strict):
+- The designer MUST NOT write preset files. It designs and emits `design.ready`.
+- The generator writes preset files and emits `review.ready`. It does not design or validate.
+- The validator independently checks the generated preset and emits `review.passed` or `review.rejected`. It does not generate.
+- The finalizer checks whole-task completeness and emits `queue.advance` or `task.complete`.

package/presets/autopreset/roles/designer.md

@@ -0,0 +1,33 @@
+You are the designer.
+
+Do not write preset files. Do not validate.
+
+Your job:
+1. Read the user's rough idea from the objective.
+2. Design a complete preset: name, roles, events, handoff graph, completion criteria, and harness rules.
+3. Write the design to `{{STATE_DIR}}/design.md` and emit `design.ready`.
+
+On first activation:
+- Parse the user's idea to determine:
+  - A short preset name (prefer `auto` + single lowercase word, e.g. `autolint`).
+  - The roles needed and what each one does.
+  - The event names and handoff graph.
+  - The completion event and any required events.
+  - Shared working files the generated loop will use.
+  - Harness rules appropriate for the loop's purpose.
+- Write `{{STATE_DIR}}/design.md` with the full design specification.
+- Write `{{STATE_DIR}}/progress.md` with the current state.
+
+On later activations (`queue.advance` or after rejection feedback):
+- Re-read `{{STATE_DIR}}/design.md` and `{{STATE_DIR}}/progress.md`.
+- Incorporate feedback and update the design.
+
+Emit:
+- `design.ready` with a summary of the preset name and role count.
+
+Rules:
+- One preset per run.
+- The design must be specific enough that the generator can create all files without guessing.
+- Every role needs: id, emits list, prompt guidance, and boundary constraints.
+- The handoff graph must be complete — every emitted event must route somewhere.
+- Default to the autocode-style planner→builder→critic→finalizer pattern unless the user's idea clearly calls for something different.

package/presets/autopreset/roles/finalizer.md

@@ -0,0 +1,23 @@
+You are the finalizer.
+
+You are the last gate before loop completion.
+
+Your job is to decide whether the generated preset is complete and usable, or whether the loop should continue.
+
+On activation:
+- Re-read `{{STATE_DIR}}/design.md` and `{{STATE_DIR}}/progress.md`.
+- Verify the generated preset directory exists at `~/.config/autoloop/presets/<name>/`.
+- Confirm the preset is runnable: `autoloop run <name> "test"` would resolve to the generated directory.
+
+Emit:
+- `queue.advance` if the validator passed but the design still has unaddressed aspects.
+- `finalization.failed` if the generated preset is not usable.
+- `task.complete` only when:
+  - All files from the design exist in the user-local presets directory.
+  - The validator confirmed structural validity.
+  - The preset is runnable by name via `autoloop run <name>`.
+
+Rules:
+- Prefer one more loop over premature completion.
+- Do not invent new requirements beyond the original idea.
+- Missing evidence means no completion.

package/presets/autopreset/roles/generator.md

@@ -0,0 +1,34 @@
+You are the generator.
+
+Do not design. Do not validate.
+
+Your job:
+1. Read the design from `{{STATE_DIR}}/design.md`.
+2. Create all preset files in `~/.config/autoloop/presets/<name>/`.
+3. Emit `review.ready` with the list of files created.
+
+On every activation:
+- Re-read `{{STATE_DIR}}/design.md` and `{{STATE_DIR}}/progress.md`.
+- If this is a retry after rejection, re-read the validator's feedback and fix the issues.
+
+Files to generate:
+1. `autoloops.toml` — use the design's completion event, required events, and iteration limit.
+2. `topology.toml` — use the design's roles, emits, prompt_file paths, and handoff map.
+3. `harness.md` — use `{{STATE_DIR}}` and `{{TOOL_PATH}}` placeholders. Include the design's global rules and shared working file contracts.
+4. `roles/<role>.md` — one file per role. Each must open with identity, state boundaries, define the job, specify emit conditions, and list rules.
+5. `README.md` — brief description of what the preset does and how to run it.
+
+After writing all files:
+- Verify each file exists by reading it back.
+- Update `{{STATE_DIR}}/progress.md` with the file list and paths.
+- Emit `review.ready` with the preset name and file count.
+
+If blocked:
+- Record the reason in `{{STATE_DIR}}/progress.md`.
+- Emit `generation.blocked` with a concrete blocker.
+
+Rules:
+- Use `{{STATE_DIR}}` and `{{TOOL_PATH}}` in all generated harness.md and role prompt files.
+- Never hardcode raw autoloop state paths in generated content — use {{STATE_DIR}} and {{TOOL_PATH}} placeholders instead.
+- Match the style of existing bundled presets (autocode, autofix, etc.).
+- The generated `autoloops.toml` should default to `backend.kind = "command"` and `backend.command = "claude"`.

package/presets/autopreset/roles/validator.md

@@ -0,0 +1,31 @@
+You are the validator.
+
+You are not the generator. Fresh eyes matter.
+
+Your job is to verify the generated preset is structurally valid and complete.
+
+On activation:
+- Re-read `{{STATE_DIR}}/design.md` and `{{STATE_DIR}}/progress.md`.
+- Read every generated file in `~/.config/autoloop/presets/<name>/`.
+
+Validation checklist:
+- [ ] `autoloops.toml` exists and contains valid TOML with required keys (event_loop.completion_event, backend.kind).
+- [ ] `topology.toml` exists and contains valid TOML with name, completion, at least one [[role]], and a [handoff] section.
+- [ ] Every role in topology.toml has an `id`, `emits` list, and `prompt_file`.
+- [ ] Every `prompt_file` path in topology.toml points to a file that exists.
+- [ ] Every event in every role's `emits` list appears in the `[handoff]` map.
+- [ ] `"loop.start"` is mapped in the handoff section.
+- [ ] `harness.md` exists and uses `{{STATE_DIR}}`/`{{TOOL_PATH}}` placeholders (no hardcoded raw autoloop state paths).
+- [ ] Role prompt files use `{{STATE_DIR}}`/`{{TOOL_PATH}}` placeholders where they reference state files or the event tool.
+- [ ] Role prompts open with identity and state boundaries.
+- [ ] `README.md` exists.
+- [ ] The design from `{{STATE_DIR}}/design.md` is faithfully implemented.
+
+Emit:
+- `review.rejected` with concrete issues when any check fails.
+- `review.passed` only when all checks pass.
+
+Rules:
+- Default to rejection when evidence is incomplete.
+- Be concrete about what is wrong and where.
+- Do not rewrite files — that is the generator's job.

package/presets/autopreset/topology.toml

@@ -0,0 +1,32 @@
+name = "autopreset"
+completion = "task.complete"
+
+[[role]]
+id = "designer"
+emits = ["design.ready"]
+prompt_file = "roles/designer.md"
+
+[[role]]
+id = "generator"
+emits = ["review.ready", "generation.blocked"]
+prompt_file = "roles/generator.md"
+
+[[role]]
+id = "validator"
+emits = ["review.passed", "review.rejected"]
+prompt_file = "roles/validator.md"
+
+[[role]]
+id = "finalizer"
+emits = ["queue.advance", "finalization.failed", "task.complete"]
+prompt_file = "roles/finalizer.md"
+
+[handoff]
+"loop.start" = ["designer"]
+"queue.advance" = ["designer"]
+"generation.blocked" = ["designer"]
+"design.ready" = ["generator"]
+"review.ready" = ["validator"]
+"review.rejected" = ["generator"]
+"review.passed" = ["finalizer"]
+"finalization.failed" = ["generator"]

package/presets/autoqa/README.md

@@ -1,8 +1,8 @@
-# AutoQA miniloop
+# AutoQA
 
-Use when you want comprehensive validation of a codebase without writing custom test harnesses.
+Use when you want adversarial, hands-on validation of a codebase — not just running existing test suites, but actively driving the implementation as a real user would and critiquing the UX.
 
-AutoQA inspects a target repo, discovers what validation tools are already available, plans a validation pass using only those native surfaces, executes each step, and compiles a QA report.
+AutoQA inspects a target repo, discovers what validation tools and drivable surfaces exist, plans a validation pass that exercises the implementation hands-on, executes each step while capturing UX observations, and compiles a QA report with both functional results and UX findings.
 
 Shape:
 - inspector
@@ -17,18 +17,38 @@ AutoQA is adversarial toward claims of health.
 - A repo only truly passes when critical discovered surfaces were actually executed and evidenced.
 - Missing, blocked, or unverifiable surfaces are gaps, not silent passes.
 - Only a `task.complete` report with explicit PASS evidence counts as all-clear.
-- Zero-dependency means “use what exists”, not “guess optimistically”.
+- Zero-dependency means "use what exists", not "guess optimistically".
+- A passing test suite with hollow assertions is UNVERIFIED, not PASS.
+
+## Hands-on driving
+
+AutoQA doesn't just run the test suite and report the exit code. It actively drives the implementation:
+
+- **CLIs**: runs with valid args, then with garbage — missing args, malformed input, unknown flags. Checks that error messages are helpful, exit codes are meaningful, and the process doesn't hang or crash.
+- **Servers**: starts the server, waits for ready, hits endpoints using whatever HTTP client is available — valid requests then adversarial ones (malformed bodies, wrong content types, missing auth, oversized payloads). Checks response codes, error structure, and that the server doesn't crash. Stops the server after.
+- **TUIs**: launches the app, pipes scripted input, sends Ctrl+C, verifies graceful exit and clean terminal state.
+- **Libraries**: exercises the public API with one-liner scripts — valid input then invalid input. Checks that errors are thrown and descriptive.
+
+## UX critique
+
+Every hands-on step captures UX observations:
+
+- **ux-bug**: broken or confusing UX that would frustrate a real user (stack traces shown to users, silent failures, hangs on bad input, corrupted terminal state).
+- **papercut**: minor rough edge (inconsistent flag naming, missing progress indicator, messy output formatting).
+- **ux-ok**: explicitly verified and acceptable.
+
+UX findings don't block a functional PASS but are prominently reported with enough detail for autofix to act on them. Chain `autoqa → autofix` to automatically remediate.
 
 ## How it works
 
-1. **Inspector** surveys the repo — identifies the domain and lists every native validation surface with evidence.
-2. **Planner** writes an ordered validation plan from cheapest to most expensive, using only discovered surfaces. Every surface becomes a step or an explicit skip.
-3. **Executor** runs exactly the planned step, captures real output, and records pass/fail/block status.
-4. **Reporter** compiles results into `.autoloop/qa-report.md` and decides whether to continue, fail, or complete.
+1. **Inspector** surveys the repo — identifies the domain, lists every native validation surface and drivable surface, probes for red flags and UX smells.
+2. **Planner** writes an ordered validation plan from cheapest to most expensive, including hands-on driving steps with embedded UX criteria. Every surface becomes a step or an explicit skip.
+3. **Executor** runs exactly the planned step — starts servers, drives CLIs, pipes TUI input, exercises APIs. Captures functional results and UX observations. Cleans up after (kills servers, verifies terminal state).
+4. **Reporter** compiles results into `{{STATE_DIR}}/qa-report.md` with separate functional and UX verdicts. Decides whether to continue, fail, or complete.
 
 ## Zero-dependency guarantee
 
-AutoQA never installs frameworks, test runners, linters, or any tools. It uses only what the repo already has. If the repo has nothing, the report says so honestly.
+AutoQA never installs frameworks, test runners, linters, or any tools. It uses only what the repo and environment already have. The inspector discovers what tools are available (HTTP clients, PTY wrappers, language runtimes, process managers) and the planner adapts accordingly. If a driving tool is missing, the surface is skipped with reason — not faked.
 
 ## Files
 
@@ -42,9 +62,10 @@ AutoQA never installs frameworks, test runners, linters, or any tools. It uses o
 
 ## Shared working files created by the loop
 
-- `.autoloop/qa-plan.md` — validation plan with discovered surfaces and ordered steps
-- `.autoloop/qa-report.md` — compiled validation report with pass/fail evidence
-- `.autoloop/progress.md` — current step tracking plus per-surface status
+- `.autoloop/qa-plan.md` — validation plan with discovered surfaces, drivable surfaces, and ordered steps
+- `.autoloop/qa-report.md` — compiled validation report with pass/fail evidence and UX findings
+- `.autoloop/progress.md` — current step tracking plus per-surface status and UX observations
+- `.autoloop/logs/` — captured output from hands-on driving steps
 
 ## Backend
 
@@ -70,7 +91,15 @@ From the repo root:
 autoloop run presets/autoqa /path/to/target-repo
 ```
 
+## Chaining
+
+AutoQA finds issues. AutoFix fixes them. Chain them:
+
+```bash
+autoloop run autoqa,autofix /path/to/target-repo
+```
+
 ## AutoQA vs AutoTest
 
-- **AutoQA** = validation orchestration using native, existing surfaces. Does not create tests.
-- **AutoTest** = formal test creation and test-suite tightening. Creates new test code.
+- **AutoQA** = adversarial validation using native surfaces + hands-on driving. Does not create tests. Critiques UX.
+- **AutoTest** = formal test creation and test-suite tightening. Creates new test code.

package/presets/autoqa/autoloops.toml

@@ -3,8 +3,8 @@ event_loop.completion_event = "task.complete"
 event_loop.completion_promise = "LOOP_COMPLETE"
 event_loop.required_events = ["surfaces.identified"]
 
-backend.kind = "command"
-backend.command = "claude"
+backend.kind = "pi"
+backend.command = "pi"
 backend.timeout_ms = 3000000
 # For deterministic local harness testing only:
 # backend.kind = "command"