Planning state → DB: .qe/planning/** is a DB-only namespace in the SQLite qe_files store. Its directories are logical paths, not folders to create on disk. Read them with node scripts/qe-cat.mjs <path> (or --ls/--exists) and mutate them only through QE state/store utilities. See QE_CONVENTIONS.md.

Qplan — Plan-owned Goal Controller

Qplan is the user-facing control surface for work. A Plan owns an ordered Goal queue; Goals are not separate user commands. The user supplies an intent, reviews material Plan changes, and receives results. QE runs the internal work.

Qplan is an explicit high-assurance entry. Only active-prefix $Qplan//Qplan or the $Qgoal//Qgoal alias activates Full SIVS. Ordinary requests use the native client execution path while the Safety Kernel and QE response style stay active; prompt size, file count, and risk words never activate this workflow.

Model

Plan → Goal 1 → Goal 2 → … → Goal N
          │
          ├─ knowledge preflight
          ├─ assurance lane (bounded micro contract | formal spec)
          ├─ execute
          ├─ verify
          └─ verified knowledge write-back

Plan is the durable contract: roadmap, requirements, phases, and ordered Goals.
Goal is the smallest independently verifiable Plan outcome.
Canonical .qe/ document rows in qe.db are evidence; derived index tables and .qe/wiki/ projections are lookup/knowledge layers. Do not treat an index row or LLM summary as the source of truth.
Only a verified Goal with explicit evidence may write back to the wiki.

Deterministic tacit-knowledge intake

For a broad or ambiguous intent, Qplan owns one durable intake before it finalizes execution artifacts. This is a bounded decision-discovery stage, not an invitation to interview the user about facts already available in the repository.

Reconnaissance first: inspect the minimum relevant sources and record source facts. Build a canonical base-question inventory only for unresolved decisions, with stable ordinals and material dimensions from core/KNOWLEDGE_ELICITATION_CONTRACT.md.
Initialize .qe/planning/plans/{slug}/INTAKE.json with node scripts/qe-intake.mjs init, the current full session UUID, and the inventory JSON. Before asking, disclose the actual base total, the maximum 12 allocated follow-ups, and the maximum batch size of 3.
Run node scripts/qe-intake.mjs next with the stored revision. Render only the returned batch through core/INTERACTION_ADAPTER.md; preserve engine labels such as [17/30] and [17-1/3] exactly. Persist every answer, skip, correction, pause, resume, re-baseline, or stop through the CLI using the returned revision. Never hand-edit counters or INTAKE.json.
When no material question remains, run the CLI synthesize operation and show the synthesis to the user. Persist corrections or a material re-baseline, and run confirm only after the user accepts the synthesis.
A pause preserves the earliest unresolved label and returns control to the user. A stop persists a blocked terminal. Do not convert either state into an inferred answer.

Interactive Claude and Codex sessions ask the same labeled open questions and wait for answers. In non-interactive mode, skip only a question that the engine classifies as explicitly reversible and non-material; record that resolution as an assumption. If any material question remains, retain the intake draft, report the earliest unresolved label, and block Plan finalization without fabricating an answer.

The intake may be omitted only when reconnaissance proves that the intent is already bounded and has no unresolved material decision. Record that reason in the Plan decision log; convenience or non-interactive execution is not a bypass. Qplan is the sole owner of this stage. Qgoal and downstream PSE stages must not duplicate its questions, counters, or transitions.

Entry and bootstrap

Ensure the shared QE.md and active-client instruction pointer exist before planning. The explicit /Qplan or $Qplan entry bootstrap creates them without overwriting user instructions. Then check .qe/; if it is absent, bootstrap the minimal Plan state (.qe/state/, .qe/planning/, and .qe/tasks/) through the existing QE state/store utilities before continuing. Initialization is part of Qplan; there is no separate initialization skill or user command.
Derive a unique slug from the intent (2–4 salient Latin keywords, lowercase [a-z0-9-], max 40 chars; append -2, -3 on collision).
Run the deterministic intake above when the intent is broad, ambiguous, or has an unresolved material decision. Reach confirmed, or block and return without finalizing a Plan. A bounded intent with no material gap may use the documented omission path.
Only after confirmed intake (or a recorded safe omission), build the exact input from core/PLAN_INITIALIZATION_CONTRACT.md and run node scripts/qe-plan.mjs init --slug {slug} --session {full UUID} --input {path}. This atomically creates the DB-authoritative Plan documents, Goal ledger, active pointer, and session binding. Do not write canonical planning paths with raw filesystem tools. Full Plans must divide work into ordered, independently verifiable Wave bullets; these become Goals. Split until every Goal has one user-visible outcome, 1–5 allowed paths, at most three criteria, at most two journeys, explicit dependencies, and explicit non-goals. A broad feature area is a Phase, never a Goal.
For every Goal, select its assurance lane after reconnaissance and before activation. A bounded micro Goal includes the exact admission request from core/GOAL_ACCEPTANCE_CONTRACT.md; the ledger replaces it with a session- and digest-bound plan-controller admission. Otherwise omit assurance and use the formal lane. Then define the pre-execution acceptance contract from core/GOAL_ACCEPTANCE_CONTRACT.md: schema 2 with exactly one structured outcome, the same outcomeId on every requirement, journey, regression, and alignment, verbatim Goal alignment, requirement criteria, at least one runnable user-journey scenario, a regression command, risk assessment, and whether human acceptance is required. High-impact risk categories (authentication, authorization, payment, deployment, data migration, destructive data changes, external integrations, or security) require human acceptance. Save it as evidence/{goalId}.acceptance.json, then run node hooks/scripts/lib/ledger.mjs set-acceptance --slug {slug} --goal-id {goalId} --file {path}. Stored schema 1 contracts may resume, but never create a new schema 1 contract. Do not let tests or implementation retrospectively define what success means.
On resume, run node scripts/qe-plan.mjs bind --slug {slug} --session {full UUID}; if an active Goal's prior session ended, use the explicit CAS takeover protocol in core/PLAN_INITIALIZATION_CONTRACT.md.
Run node hooks/scripts/lib/ledger.mjs render-state --slug {slug}. Never hand-edit the ## Phase Progress block.

Internal Goal loop

Run this loop until the Plan is complete, blocked, or needs a material user decision. Do not expose Qgenerate-spec, Qexecute, derived-wiki internals, or a copied next-command handoff.

Select: Run node hooks/scripts/lib/ledger.mjs advance --slug {slug} --action next --session {current full session UUID}. It starts only the first pending Goal and binds that Goal to the execution-owner session. An active or blocked Goal prevents skipping, and another live session cannot continue, block, fail, or complete the owned Goal.
Knowledge preflight: Run node scripts/qe-plan-context.mjs "{Goal objective}". Then run node scripts/qe-analysis-drift.mjs --json. When it reports actionRequired: true, generated analysis is advisory-only for the returned affectedPaths: read the live source in those paths before planning, execution, or verification. Drift detection is non-blocking and a missing baseline does not fail the Goal; it only removes analysis freshness as usable evidence. Use the returned reviewed wiki entries and QE artifact paths as pointers. Read only the source documents required for the Goal; source files override summaries.
Assurance lane execution: consume the immutable lane selected and ledger-validated before activation; prompt length alone never decides it.

Bounded micro-Goal lane applies only when all conditions hold: one low-risk implementation outcome, at most three allowed paths, fewer than three work items, no unresolved material decision, and no authentication, authorization, payment, deployment, migration, destructive-data, security-boundary, or external- integration impact. The stored contract must contain the ledger-issued assurance admission defined by core/GOAL_ACCEPTANCE_CONTRACT.md; absence or rejection means the formal lane. The immutable Goal acceptance contract is the executable micro spec. Do not create a TASK_REQUEST or run the three-reviewer Spec gate. The ledger seals a Git scope baseline at admission and rejects evidence or completion when observed changes escape allowedPaths; without a Git worktree the bounded-micro lane is unavailable. Execute in the main thread or one bounded worker, apply the Qexecute TDD gate, run the locked commands, and retain the distinct-session independent machine verification and Goal-alignment verdict required by Step 4. Do not run a separate Supervise fan-out unless changed risk evidence requires escalation.

Formal Goal lane applies otherwise. Generate the Goal's TASK_REQUEST and VERIFY_CHECKLIST, execute it, then run the complete SIVS verification loop. These are internal units, not user commands.

After implementation and before verification, rerun node scripts/qe-analysis-drift.mjs --json. If the Goal introduced actionable structural drift, include the returned paths in live-source verification and do not claim that the generated analysis map is current. This advisory check never substitutes for the locked regression and Goal-alignment gates.

If a micro Goal grows beyond any limit, reveals a high-impact risk, or fails verification, do not mutate its immutable acceptance. Stop before expanded work, block it through the audited Goal transition, and create a new linked formal Plan/Goal with a fresh acceptance contract and dependency on the blocked micro Goal. The original micro Goal cannot later claim completion.
Completion evidence: Before completion, record evidence/{goalId}.completion.json against the immutable acceptance contract. It must show every requirement and user-journey scenario passing, a passing regression result, machine re-execution by a named verifier, that verifier's Goal-to-evidence alignment verdict, known limitations, and required human acceptance. Run every locked contract command via ledger.mjs run-evidence first for implementation and again from a distinct QE session for verification --verifier {identity}; then run record-evidence.
Gate: If verification fails, evidence is incomplete, or a required decision is unresolved, keep the Goal active or call advance --action block --evidence "{specific blocker}" --session {owner UUID}; do not start another Goal. Ask the user only for a material scope, risk, or irreversible choice.
Complete: Only after the acceptance evidence has been recorded, run node hooks/scripts/lib/ledger.mjs advance --slug {slug} --action complete --session {owner UUID}. Formal Goals are accepted only when a Goal-bound SIVS controller has already reached complete with matching TASK_REQUEST, VERIFY_CHECKLIST, Verify, and Supervise proof. This records the lifecycle event, updates STATE, and writes a provenance-linked reviewed project-wiki page.
Repeat at Step 1. When advance --action next returns complete, report the Plan outcome, remaining risks, and evidence.
At each completed Phase boundary, advance next requires the sealed proof from core/PHASE_RETROSPECTIVE_CONTRACT.md. Run node scripts/qe-plan.mjs retrospective --slug {slug} --session {full UUID} --input {path}; it generates the Phase report, executes fresh regression, and records the retrospective.

Goal quality rules

One active Goal at a time. A safe parallel Wave is internal execution within that Goal; it never creates multiple active Goals.
A Goal must state its verbatim objective alignment, one primary outcome, bounded file scope, explicit non-goals, dependencies, at most three requirement criteria, at most two user-journey scenarios, regression scope, risk assessment, and evidence before work starts.
Draft plans, model hypotheses, and unverified research never become reviewed project knowledge.
Use source-backed contracts, tests, verification reports, and decisions as first-class evidence.
Preserve an append-only ledger. Do not rewrite prior Goal events or fabricate completion.

User communication

At Plan creation or material replan, show the ordered Goal list, current Goal, success criteria, and any required decision. During normal progression, report concise status rather than internal commands. On completion, provide the evidence-backed Plan result.

Will

Create, resume, and advance Plan-owned Goals.
Use QE knowledge internally before each Goal and write back only verified outcomes.
Run internal spec, execution, and verification units without user command choreography.

Will Not

Ask the user to invoke internal PSE stages, derived-wiki internals, or a raw ledger command.
Skip an active or blocked Goal.
Mark a Goal complete from a bare test claim, implementation report, or self-verification.
Promote LLM-generated text to reviewed knowledge without verification evidence.

Qplan

SKILL.mdskills/Qplan/SKILL.md