.qe reads → DB: .qe/ content is stored in the SQLite store (qe_files), so a path may have no file on disk. Read .qe/ content with node scripts/qe-cat.mjs <path> (or --ls/--exists) and structured state with node scripts/qe-query.mjs … — do not assume the raw file exists. See QE_CONVENTIONS.md.

Qexecute — Unified Execution Engine

Internal PSE unit. Users start work with {adapter.commandPrefix}Qgoal {목표}; user_invocable is catalog/documentation metadata only. Runtime enforcement is the G010 PreToolUse gate, while active UUID artifacts preserve in-chain continuity.

Role

The single entry point for executing spec documents. Qexecute consolidates the three former execution engines — sequential run, parallel-wave atomic, and the code quality loop — into one skill. It reads the actual TASK_REQUEST — not the user's phrasing — to decide how to execute.

MANDATORY: All user confirmations MUST use the interaction adapter. Claude MUST use AskUserQuestion. Codex interactive may use concise plain-text choices. Codex non-interactive selects the documented recommended default only when the action is reversible and reports it; destructive ambiguity must stop.

Flag Grammar

Invocation	Mode	Behavior
Qexecute {UUID}	default	Read the spec → classify → sequential or parallel wave
Qexecute -verify {UUID}	verify	test → review → fix → retest quality loop on already-changed code
Qexecute -utopia …	modifier	Fully autonomous: no-confirmation / auto-approve, combines with default or -verify. Sub-flags -ralph, off, status. See “-utopia — Fully Autonomous Execution”.

• Flags use a single dash. -utopia is a modifier (combinable); -verify and default are mutually exclusive execution axes.

Client Adapter Compatibility

• Claude: approvals/next-task prompts use AskUserQuestion; delegation uses the Agent tool.
• Codex native: prefer native subagents via installed agent TOML (model / model_reasoning_effort derived from recommendedModel).
• Codex client adapter: role-separated inline execution only when native subagent dispatch is unavailable; mark the fallback explicitly.
• Command rendering: user-visible handoffs use adapter.commandPrefix (/Q… Claude, $Q… Codex).

---

Default Mode — Execute a Spec

Step 1: Document Discovery

Plan Knowledge Pull: Qplan performs knowledge retrieval before it creates this internal execution task. If the task needs more context, use node scripts/qe-plan-context.mjs "<task intent>" and verify selected source documents; do not invoke a user-facing wiki workflow.

1. State utility: call parseClaudeTaskTable(cwd) from hooks/scripts/lib/state.mjs (prefers .qe/TASK_LOG.md, falls back to the legacy Claude task table).
2. Glob .qe/tasks/{pending,in-progress,on-hold}/*.md for TASK_REQUEST files.
3. Backward compat: check project root if .qe/tasks/ is missing.
4. UUID argument → select directly. No argument + multiple tasks → ask which to run.
5. Multiple space-separated UUIDs → see Multiple UUID Execution.

Step 2: Summary and Approval

Read TASK_REQUEST + VERIFY_CHECKLIST and show a summary.

Chained skip: if TASK_REQUEST contains <!-- chained-from: Qgenerate-spec -->, skip the approval prompt (already approved in Qgenerate-spec) and remove the comment after reading.

Otherwise get approval via the interaction adapter. On approve:

• Move files to in-progress/.
• Status: call updateClaudeStatus(cwd, uuid, "🔶").

Step 2.5: Classification — Sequential vs Wave

Parse the TASK_REQUEST checklist and decide the execution shape:

WAVE  when ALL hold:
  1. checklist items ≥ 5
  2. topological sort by `depends`/`depends_on` tags yields a max wave width ≥ 2
     (i.e. ≥ 2 items can run at once)
  3. file ownership is non-overlapping — no two items write the same `→ output:` path
SEQUENTIAL  otherwise

• No tags → let Etask-executor infer dependencies from file paths (existing behavior).
• --worktree (opt-in) requests isolated per-item execution when two+ items must touch the same file in one wave; default is in-place.

Code Risk Gate (type: code — hard block)

Before any implementation worker starts, enforce:

• TASK_REQUEST has a ## Risk Register with all six fields filled: worst-case failure, data loss/corruption risk, security/permission risk, concurrency/race risk, rollback strategy, and unverified assumptions.
• The paired VERIFY_CHECKLIST has checks for worst-case failure, data/security/concurrency risk evaluation, unverified-assumption/residual-risk reporting, and high-risk mitigation/defer rationale.
• Empty fields, placeholder text, or missing paired checks → route back to {adapter.commandPrefix}Qgenerate-spec or amend the spec. Do not start execution.

Step 3: Execute

Plan-owned micro-Goal handoff

Qplan may invoke execution without a TASK_REQUEST only when its immutable Goal acceptance contract contains the ledger-validated assurance.lane=bounded-micro declaration defined by core/GOAL_ACCEPTANCE_CONTRACT.md. Task size alone is not an admission signal. That contract replaces only the formal Spec artifact and Spec/Supervise fan-out; it does not waive TDD applicability, locked command execution, regression evidence, distinct-session machine verification, or Goal-alignment review. Scope growth, new high-impact risk, or verification failure returns control to Qplan, which blocks the immutable micro Goal and creates a linked formal successor Plan/Goal; it never rewrites the original assurance. Direct Qexecute entry never self-declares this exception.

TDD Applicability Gate (R004 — scale-aware)

For type: code, call judgeTddPolicy() from qexecute-tdd-policy.mjs. When apply=true, enforce RED → GREEN → REFACTOR: prove the new test fails for the intended reason, implement the minimum passing behavior, then refactor without losing GREEN. Docs/analysis, config-only work, or absent test infrastructure records formatExclusionHandoff() and skips TDD. Full signal, contradiction, and completion rules: ./reference/execution-protocol.md.

Execution routing

Delegate bounded work to Etask-executor under core/AGENT_DELEGATION_CONTRACT.md. Sequential work preserves checklist order. Wave work requires five or more items, topological width of at least two, and non-overlapping output ownership; use worktree isolation or fall back to sequential. The Lead synthesizes envelopes and runs final verification once.

Lifecycle Cleanup

The Lead calls wait_agent and close_agent for every handle and records completed, failed, timed-out, or stale. The final report states open handles: 0 or lists each stale warning.

SIVS Single-AI Role Contract

The active client owns Implement, Verify, and Supervise. Native same-client subagents are preferred; unavailable delegation uses mode=degraded-inline, never a cross-client bridge. Verify is the evidence gate and Supervise is the merge-readiness gate. Detailed execution, wave, and lifecycle rules: ./reference/execution-protocol.md.

Step 4: Final Verification

Verify every checklist item with concrete evidence and run the cross-phase regression gate for code. TDD-applicable items require their test file plus a fresh post-refactor GREEN run. Auth, crypto, payment, credential, or secret changes require Esecurity-officer.

For code, invoke Esupervision-orchestrator; WARN is remediated and rechecked, FAIL creates a request using core/REMEDIATION_REQUEST_FORMAT.md. The adversarial owner remains Qcritical-review --stage supervise. Before completion run -verify, including the final Risk Proof Gate via Qcritical-review --risk {UUID}. Missing or unknown HIGH/CRITICAL risk evidence is a hard block.

The verify loop is owned by Eqa-orchestrator; see ./reference/execution-protocol.md.

Step 5: Completion

Mark both documents [x], write and verify their completed destinations before removing in-progress sources, update TASK_LOG to ✅, and reset the UUID loop counters. Preserve unrelated artifacts. Report changed files, verification, Facts, Residual Risks, Assumptions, and the next pending task. Detailed state and safe-move rules: ./reference/autonomy-and-state.md.

Verify Mode (-verify)

Run test → review → fix → retest through Eqa-orchestrator, at most three iterations. Required gates are regression, smoke, Nyquist coverage, comment coverage, adversarial Verify, and Risk Proof. The test and review first passes receive the same source evidence but not each others verdict.

Loop limit: 3 iterations (confirm continuation via the interaction adapter each round).

-utopia modifier

-utopia auto-approves only reversible recommended defaults; destructive ambiguity still stops. -ralph repeats incomplete work without weakening any gate. off disables continuation and status is read-only. Multiple UUIDs may run as a bounded wave only when write ownership is disjoint.

State, safety, autonomous-mode, and handoff details: ./reference/autonomy-and-state.md.

Role Constraints

• Execute only the selected TASK_REQUEST and paired VERIFY_CHECKLIST.
• Preserve unrelated user changes and obey build admission.
• Route commits through Qcommit and version/release work through Qrelease.
• Never report completion before checklist, evidence, safe move, and TASK_LOG are complete.