# Ql Execute

> Part of the quantum-loop autonomous development pipeline (brainstorm → spec → plan → execute → review → verify). Run the autonomous execution loop. Reads quantum.json, queries the dependency DAG, implements stories with TDD and two-stage review gates. Supports parallel execution via native worktree isolation. Use after /quantum-loop:plan has created quantum.json. Triggers on: execute, run loop, start building, ql-execute.

- Skill: `andyzengmath/ql-execute` (Agent Skill)
- Install (CLI): `npx skillmds@latest add andyzengmath/ql-execute`
- Raw SKILL.md: https://api.skillmd.com/api/skills/andyzengmath/ql-execute/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: andyzengmath (https://skillmd.com/u/andyzengmath)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/andyzengmath/ql-execute

---


# Quantum-Loop: Execute

Run the autonomous execution loop to implement all stories in quantum.json.

## Prerequisites

Before starting:
1. `quantum.json` must exist (created by `/quantum-loop:plan`)
2. The project must be a git repository
3. Project build tools must be available (npm, pip, cargo, etc.)

If prerequisites are not met, inform the user and stop.

## Execution

Read and follow the orchestrator agent instructions in `agents/orchestrator.md`.

The orchestrator will:
1. Read quantum.json state and validate the dependency DAG
2. Query for eligible stories (pending/retriable with all dependencies passed)
3. **If 1 story eligible:** execute it sequentially (implement, quality checks, review, commit)
4. **If 2+ stories eligible:** spawn parallel implementer subagents in isolated worktrees
5. Handle retries, cascade blocking, and error recovery
6. Loop until all stories pass (COMPLETE) or no stories are executable (BLOCKED)

## Orchestrator liveness gate (N14 / US-002 — v0.7.0)

**Default-on for unattended `/ql-execute` runs.** v0.6.7 + v0.6.8 + v0.6.9 all saw the orchestrator subagent abandon its cycle mid-execution (LLM context-drift). v0.6.8 N6 shipped a prose-only Self-monitoring guard. v0.6.9 N6-followup shipped `lib/orchestrator-liveness.sh::poll_orchestrator_commits` as a callable runtime helper. This v0.7.0 N14 SKILL-level wrapping is the third and final layer — auto-invoke the helper after dispatching the orchestrator, hand off to the parent on STALE.

```bash
# After dispatching the orchestrator subagent (Step 3 of Execution above):
source lib/orchestrator-liveness.sh
wrap_orchestrator_dispatch 600 60 || exit 1
```

The `wrap_orchestrator_dispatch` function (v0.7.1 N20 extraction; see
`lib/orchestrator-liveness.sh`) handles the `QL_LIVENESS_ENABLE` env-var
check, the `poll_orchestrator_commits` invocation, and the structured
handoff message internally. The SKILL just calls it and exits 1 on
STALE so CI / wrapper scripts can distinguish stale-signal exits from
clean COMPLETE / BLOCKED exits.

**Env var contract:**

| `QL_LIVENESS_ENABLE=` | Effect |
|---|---|
| (unset) or `true` | default — wrap orchestrator dispatch with `poll_orchestrator_commits` (timeout 600s, interval 60s) |
| `false` | skip the wrapping; preserve v0.6.9 dispatch semantics exactly (backwards compat for operators with their own wrappers) |
| any other value | treated as `true` (default-true semantics; warn to stderr) |

**Handoff message structure** (printed to stdout when STALE fires):
- One-line `[QL-EXECUTE] orchestrator-stale signal.` header.
- Pointer to `references/orchestrator-takeover.md` (the v0.6.9 N13 SOP).
- Numbered recovery steps the parent agent runs (drift verification + manual takeover).

The parent agent reads the handoff and either re-spawns `/ql-execute` (after confirming whether drift was a transient LLM hiccup) or takes over manually per the SOP. SKILL exits with rc=1 (`orchestrator-stale`) so CI / wrapper scripts can distinguish stale-signal exits from clean COMPLETE / BLOCKED exits.

**Testability note (presence-only AC):** the wrapping prose above is consumed by an LLM that runs `/ql-execute`. There is no runtime test that EXERCISES the env-var conditional or the handoff message structure inside the SKILL itself — those would require running the SKILL in a controlled fixture. Instead, `tests/test_ql_execute_liveness_wrapping.sh` verifies the prose contains the expected idioms (header, env var, default-true, cross-link, handoff structure). Matches v0.6.8 N6 prose-guard pattern.

## Autonomous CLI Alternative

For unattended execution outside Claude Code (Linux/Mac):
```bash
./quantum-loop.sh --max-iterations 20
./quantum-loop.sh --parallel --max-parallel 4
```

On Windows, use `/ql-execute` instead of the shell script for reliable execution.

## Signals

| Signal | Meaning |
|--------|---------|
| `<quantum>COMPLETE</quantum>` | All stories passed |
| `<quantum>BLOCKED</quantum>` | No executable stories remain |
| `<quantum>STORY_PASSED</quantum>` | One story completed (more remain) |
| `<quantum>STORY_FAILED</quantum>` | One story failed (will retry if attempts remain) |
| `<quantum>WAVE_PASSED</quantum>` | All stories in a coordinator wave passed (v0.8.0+ coordinator pattern; see `agents/coordinator.md`) |
| `<quantum>WAVE_FAILED</quantum>` | One or more wave stories failed (parent decides retry/abort) |

## Post-review slop-cleanup hook (Phase 9 / P1.6)

After each story's two-stage review gate PASSES but BEFORE the merge to the feature branch, the orchestrator SHOULD invoke `/quantum-loop:ql-deslop` on the story's changed files. Opt-out via `--no-deslop` (record the reason in commit trailer `Deslop: skipped | <reason>`).

Mandatory safety rails, enforced by `lib/deslop.sh`:

1. `validate_scope <file> BASE HEAD` — rejects any edit to a file outside the story's diff. Prevents "adjacent cleanup" scope creep.
2. `take_baseline <before.json>` — snapshots test / lint / typecheck exit codes.
3. Run ONE deslop pass at a time from the 4-pass taxonomy in `skills/ql-deslop/SKILL.md` (dead-code → duplication → consistency → test-reinforcement).
4. `take_baseline <after.json>` + `compare_baseline before.json after.json`. Any regression triggers:
5. `rollback_pass BASE <files>` and emits `<quantum>DESLOP_ROLLED_BACK</quantum>`. The next pass does NOT start until the user inspects.
6. Persist per-pass report into `quantum.deslop[<story-id>].pass_<n>`.

Language detection: `bash lib/deslop.sh detect-language` dispatches to the appropriate dead-code detector (knip / ts-prune / vulture / staticcheck / cargo-udeps). When tooling is missing, the step is skipped cleanly rather than failing the pipeline.

## Post-pipeline review hook (Phase 8 / P1.1 + P1.2)

After `COMPLETE` fires, the orchestrator SHOULD invoke `/quantum-loop:ql-deep-review` before handing the merged branch back to the user. Opt-in via `--deep-review` (or mandatory when the feature's risk tier is HIGH / CRITICAL per `lib/deep-review.sh compute_risk_score`).

Gate steps:

1. Run the wave-boundary checks on the final commit range (`BASE_SHA..HEAD_SHA`):
   - **Cross-story constant scan** — `bash lib/wave-boundary.sh scan BASE HEAD` emits JSON findings for literals that canonicalize to the same key across ≥2 stories (e.g. `'google'` vs `'google-api-key'`; the Math-Research regression class). Gate via `bash lib/wave-boundary.sh gate BASE HEAD` — exit 0 = divergence found, exit 1 = clean. Non-empty findings are treated as a `medium` (2 variants) or `high` (3+ variants) severity input to the reviewer-set dispatch.
   - **Wave-wide typecheck** (`lib/resilience.sh` `run_typecheck`).
   - **Full test suite**.
   - **Barrel + dep-manifest regeneration** (`lib/barrel-regen.sh`, `lib/dep-manifest.sh`).
2. Compute risk tier: `bash lib/deep-review.sh score BASE HEAD` → then `bash lib/deep-review.sh tier <score>`.
3. Dispatch the reviewer-set specified in `skills/ql-deep-review/SKILL.md §"Risk scoring"`.
4. Apply `lib/deep-review.sh actionability / dedup / hallucination / verdict` in sequence to aggregate findings.
5. Persist the final review object into `quantum.reviews[<feature-id>].deepReview`.
6. Verdicts:
   - `BLOCKS_MERGE` → refuse handoff; emit `STORY_FAILED` with blockers in the failureLog.
   - `REQUEST_CHANGES` → route to a targeted fix-story in the next wave.
   - `APPROVE_WITH_COMMENTS` → proceed but log comments into `codebasePatterns`.
   - `APPROVE` → proceed cleanly.

For legacy pipelines that predate this hook, `/quantum-loop:ql-deep-review` can be invoked manually post-merge.