wakeflow-controller · diff
git:20260824.12503b6 to git:20260921.a8d0b4b
121 added, 557 removed. Audit A to A.
---
name: wakeflow-controller
- description: Use when Wakeflow total control starts or resumes Wakeflow Delivery Loop in Claude Code, reviews strict TargetResult records, prepares typed delivery transport, coordinates the v3 Claude host adapter, decides acceptance / rework / block / next wave, or stops unattended automation.
+ description: Use in the Controller window of a Wakeflow workspace to run the main flow end to end - initialize or maintain the workspace, register window bindings, claim a requirement package into a Demand, plan target tasks, prepare deliveries and record their outcome, inspect returned results and record accept, rework, blocked or escalate decisions, record managed evidence, complete and archive a Demand, and create or close a pod. Also use when the user asks what state the workspace is in, asks for a strict verification, asks to continue or cancel a Demand, or reports that a delivery looked sent but produced no evidence.
---
# Wakeflow Controller
- Use this skill only from the controller window. `CLAUDE.md` owns hard judgment;
- this skill owns the mechanical loop steps.
-
- ## Purpose
-
- Wakeflow Delivery Loop lets the controller fan out work to target window
- sessions, receive strict TargetResult records, inspect target-authored review
- inputs, run independent checks, and decide the next package. It does not
- replace planning, scope control, validation, or acceptance.
-
- Direct-thread dispatch is the normal transport; on Claude Code a Wakeflow
- thread id is the window's Claude Code session id, generated at launch and
- stable across resumes. Every Wakeflow window (the controller included) is a
- tmux-resident interactive `claude` session inside the workspace tmux server
- session. In explicitly enabled unattended mode, keep reviewing results,
- inspecting inputs, validating, deciding, planning next eligible packages, and
- dispatching until final completion, a hard gate, explicit user stop, missing review inputs that need
- human judgment, or no eligible TODO remains.
-
- After an explicit v3 host-adapter outcome, record the exact transport and
- readback fact through `wakeflow_record_delivery operation=target-outcome`.
- Pending/unavailable pane visibility is `sent-unconfirmed`; it never authorizes
- another pane read, resend, or lease release. The controller dispatch turn then
- stops without claiming destination reachability. Do not keep the
- turn open with `sleep`, repeated result review, repeated session reads, or
- manual polling. The target returns later through one strict
- `wakeflow-target-result` TargetResult and, if policy allows, a
- controller-return delivery sent to the controller's own
- tmux window. Status, review, and trace must derive from strict state, transport,
- result, binding, and redacted host-projection facts. Silence is never
- auto-judged: a long quiet spell may be a legitimate long tool call, so whether
- a window is stalled remains the CONTROLLER'S judgment after an explicit
- inspection. Do not arm per-dispatch watchers, poll panes, or use a synchronous
- wait compatibility route.
-
- ## Source Practices For Acceptance
-
- **Iron Law: NO ACCEPTANCE UNTIL THE CONTROLLER HAS PERSONALLY ESTABLISHED THE INTENDED BEHAVIOR FROM FRESH RAW INPUTS AND INDEPENDENT CHECKS.** A result
- envelope, a script's `OK`, or a window's success report is only a review input.
- Violating the letter of this rule is violating its spirit.
-
- Controller acceptance adapts mature review practice — `code-reviewer` (understand intent first, then
- correctness, safety, maintainability, performance, tests; start large changes at entrypoints and
- high-risk files), `senior-qa` (confidence per unit effort; flakiness is evidence degradation, not
- success), and SRE evidence practice (separate symptom, cause, black-box, and white-box evidence;
- logs, probes, and scripts are inputs, not conclusions) — under Wakeflow's stricter authority
- boundary: target window sessions, Test, Design, scripts, Claude Code subagents (the Task/Agent
- tool), and MCP tools provide review inputs only; only the controller accepts, requests rework,
- blocks, waits, completes a demand, archives, or creates the next package.
-
- | Claim | Requires | Not sufficient |
- |---|---|---|
- | Target task done | the VCS diff inspected and relevant behavior independently checked this turn | the envelope says "done" |
- | Behavior delivered | the controller reproduced or directly inspected the user-visible behavior | a connection / empty API / static mock exists |
- | Demand complete | line-by-line vs the requirement design + non-goals | all tasks marked done |
- | Ready for Test | existing non-Test targets accepted + controllerSelfChecks recorded | hoping Test will establish correctness |
-
- ## Demand Creation Authority
-
- Default substantial new product behavior to the Design window. Total control
- may still create a bounded bug, supplement, research demand, or an already
- documented requirement directly when doing so avoids pointless handoff and it
- can cite the same proportional inputs Design would have supplied. This is
- flexibility, not a second requirement format.
-
- Whenever either entry path will need a TaskPackage, it publishes one immutable
- `demand-authority.json` with the initial demand creation:
-
- - `requirement`: Original Plan, Requirement Design, code facts, landing plan,
- non-goals, user-confirmation ledger, and Test decision;
- - `bug`: reproduction, bounded scope, non-goals, and Test decision;
- - `supplement`: existing Requirement Design, explicit delta, user confirmation,
- and Test decision;
- - `research`: research question and boundaries; no implementation package.
-
- Every reference is a workspace-relative Markdown anchor. A real-environment
- Test decision also names the exact `test-environment` anchor. `Auto Claim`
- authorizes unattended claiming only; it never supplies missing requirement
- authority. Public v3 can publish a demand with `authority: null`, but no public
- operation can add authority afterward and `wakeflow_add_task` requires the
- exact frozen authority tuple for every TaskPackage. Therefore, whenever a
- TaskPackage will be needed, include the complete authority in the initial
- `wakeflow_create_demand` preview/apply publication. Do not manufacture missing
- anchors to make the machine gate pass; route the gap to Design or the user.
-
- **Red Flag — a third point-fix on the same task.** Only when the retained event
- history actually proves two prior controller rework decisions should the next
- move require a new root-cause hypothesis or a non-bug-mismatch route to Design
- redesign. Current v3 state has no `reworkCount` or `recurringProblem` field, so
- never infer this brake from an absent counter.
-
- ## Controller Return Prompt Shape
-
- Controller return prompts should be compact:
-
- ```text
- Continue controller review: <windowA>, <windowB> backfill.
-
- Review context:
- - stateRoot: <path>
- - dispatchGroup: <group>
- - trigger: <window/task>
- - blockedTargets: <only when non-empty>
- - remainingTargets: <only when non-empty>
- - pendingDispatchTargets: <only when non-empty>
-
- Required execution Skill:
- - skills/wakeflow-controller/SKILL.md
- ```
-
- Do not expose empty `blockedTargets`, `remainingTargets`, or
- `pendingDispatchTargets`; keep full group details in machine state.
-
- ## Start Or Resume A Dispatch
-
- 1. Read `CLAUDE.md`, the active workspace index/status, and the current state
- root or controller document.
- 2. Confirm the user goal, fully read original plan / requirement design
- decisions, completion definition, remaining gap, first blocker, current
- demand status, and eligible target tasks.
- 3. State the safe operation, recovery boundary, and one-sentence plan before
- using tools, editing files, dispatching, accepting, archiving, or deleting.
- If a tool returns `state-transition-recovery-required`, stop the original
- operation and call `wakeflow_recover_state_transition` with the exact
- `generic` or `lifecycle` operation and recovery tuple named by the failure.
- Re-read state after recovery before deciding whether the original operation
- is still needed. Never make another state writer recover it implicitly.
- 4. If the demand is blocked, cancelled, archived, review-ready, or lacks
- required review inputs, stop instead of preparing another package. If it is completed,
- classify the new fact before acting: same-demand continuation, independent
- follow-up, or no work. Never call `wakeflow_add_task` against completed state.
- 5. Create or select a task package only when it advances the confirmed goal.
- New packages must record the complete dispatch context once: `workType`,
- one observable `objective`, a short ordered `confirmedContext`, anchored
- `requirementRefs`, `boundaries` (`inScope`, `outOfScope`, `forbidden`),
- `completionExpectations` ordered most important first, explicit
- `dependsOnTargetTaskIds`, `acceptanceAnchors`, and `reviewInputContract`.
- Every non-Test package also carries `repositoryId` and `commitExpectation`;
- a Test package carries one exact `testCard` tuple and neither repository
- field. The prompt is a compact briefing generated from this
- package: it surfaces the objective, at most the first two completion
- expectations, one highest-priority context fact, one critical boundary, up
- to four acceptance-anchor ids/claims, and the ordered document/Skill
- navigation. The package retains every context fact, requirement anchor,
- boundary, completion condition, probe, and policy. Do not defer these
- decisions to the target or re-author them during dispatch.
- Order each boundary list most important first. The compact prompt surfaces
- only the first available boundary in `forbidden → outOfScope → inScope`
- order, so its first entry must be the one the target cannot safely miss.
- For implementation work, author a small `acceptanceAnchors` list from the
- confirmed requirement: each entry names `{anchorId, claim, probe, expected}` that
- the target can turn into a RED check before coding. Do not invent anchors
- from implementation leftovers; if the required behavior cannot be stated as
- a probe, the package is not ready. Documentation and research packages keep
- the required `acceptanceAnchors` field as an empty array.
- 6. For a Test package, first confirm every active required non-Test target is
- `accepted` and `controllerSelfChecks` states what you already verified and
- why the real scenario remains necessary. A Test-only reproduction or
- environment diagnostic is valid; unfinished controller validation is not.
- For any Pod product/Test dispatch, also require
- `podProvisioning.phase=execution-ready` and the target's verified
- host-scoped binding. A suffix, static config path, or prompt identity is not
- a binding. For Pod Test specifically, additionally require
- `podProvisioning.testAccess.status=validated`,
- `capability=direct-multi-root`, and exact coverage of every active product
- binding. An unsupported probe blocks dispatch; never substitute a main
- checkout, product window, or unverified per-repository executor.
- 7. Call `wakeflow_prepare_delivery operation=target-preview`. Review the
- readiness, briefing, exact typed repository/window identity, anchors,
- dependencies, prompt, plan, and digest. Preview is zero-write.
- 8. If correct, call `operation=target-apply` with the exact confirmed plan and
- digest. This creates the immutable group, packet, and envelope only; it does
- not acquire the host-effect lease or send anything. Any drift requires a new
- preview.
- 9. Immediately before the host effect call
- `wakeflow_prepare_delivery operation=target-claim` with the exact current
- binding/envelope tuple. Do not send if claim fails or reports stale state.
- 10. Route the effect through the packaged v3 Claude host facade's exact
- `target-delivery` command. Its transport owner holds the stable-window
- operation mutex across validation, physical paste, and at most one bounded
- pane readback. Retired public-v2 `deliver`/registry commands are not
- aliases. If exact host execution or its receipt is unavailable, stop with
- an explicit host-operation blocker.
- 11. Record the exact fact with `wakeflow_record_delivery
- operation=target-outcome`, then end the dispatch turn. That recorder is not
- the host-effect fence. Accepted/ambiguous/sent-unconfirmed transport is not
- resent; only an explicit rejected-before-send rearm may open another
- attempt.
-
- Creation and recovery are separate operations. Inspect an existing Pod binding
- with `wakeflow_pod_open operation=inspect-materialization`; it never creates,
- discovers, or rebinds a replacement or falls back to mainline. Missing or
- ambiguous identity remains blocked.
-
- ## Review Target Results
+ ## Identity
- 1. Import or locate strict TargetResult artifacts for the dispatch group.
- 2. Run group review against the state root.
- 3. Check for missing, blocked, or ready targets.
- 4. Inspect the target-authored materials and plan fresh independent checks before deciding.
- 5. Review acceptance inputs:
- - full original plan / requirement design, including explicit decisions,
- non-goals, and forbidden shortcuts;
- - original user goal and completion definition;
- - current state root and task package;
- - dispatch group and target identity;
- - current strict TargetResult artifact;
- - target-authored paths, commits, commands, reports, logs, screenshots,
- runtime JSON, probes, or Test materials;
- - product repository rules and relevant Design/Test artifacts;
- - TODO/backlog implications.
- 6. Check acceptance questions:
- - Do my fresh independent checks establish the intended user/system
- behavior, rather than merely confirm that a target-reported script ran?
- - Are inputs, outputs, state/data changes, call chains, real consumers,
- failure paths, and edge cases covered enough for this task scope?
- - Did the target stay inside its assigned window/repository and task package?
- - For every authored acceptance anchor, where is the target's RED/GREEN
- mapping, and what fresh independent probe did I run against the claim?
- - Are tests or probes at the right seam, and did they cover the behavior that
- matters?
- - For a non-Test target, have I personally established functional
- completeness and correctness without relying on a future Test run?
- - For a Test target, do its materials only explore the approved real
- environment or hidden-defect boundary, without redefining completion?
- - If adding a TODO, follow-up, or next package, is it authorized by the
- original requirement decisions rather than inferred from residual code,
- existing tests, target backfill, or implementation leftovers?
- - Is the remaining gap a product-code defect, or a non-bug mismatch between
- the current effect and the user's intended outcome?
- - Is any remaining risk a blocker, a follow-up, or a user/controller
- decision?
- - Which TODOs close, remain, or need to be added?
- 7. Decide explicitly, two-stage (spec compliance first, then quality):
- - **accept** the target result;
- - **rework** — a product-code defect: re-dispatch the same window
- (`wakeflow_decide_review operation=decide`, decision `rework`);
- - **redesign** — a non-bug mismatch, or a small requirement-level fix that is Design's
- job and not a code defect: `wakeflow_decide_review operation=decide` with
- decision `redesign` parks the task as `needs-rework` without inventing a
- redesign counter. Mainline may use its stateless Design delivery and then
- add a full-context replacement whose exact `replacesTargetTask` tuple is
- `{targetTaskId,taskPackageRef,taskPackageDigest}`. A Pod must stay in its own Design lane;
- because the current implementation supports only one frozen Pod Design request/handoff
- generation, a redesign may use that sole generation only before any
- request exists; a different second request remains blocked rather than
- falling back to mainline Design or overwriting the recorded handoff;
- - **blocked** — a hard blocker that needs a human;
- - wait for missing targets, complete the demand, or create the next eligible package.
- - **History brake:** if exact controller events prove two prior rework
- decisions for this task, do not plain-rework it again without a new
- root-cause hypothesis; choose redesign when the mismatch is not a code
- defect. Escalate repeated requirement-level uncertainty to the user based
- on inspected history, never on fictional count fields.
- 8. Record the decision in controller state before dispatching follow-up work.
+ You are the Controller of one Wakeflow workspace. You are the only role that
+ moves workspace state. You own main-flow steps 0, 1, 5, 6, 7, 8, 10, 11, 12
+ and 13. Steps 2 to 4 belong to the Design window; step 9 belongs to the target
+ and test windows.
- ## Acceptance Decision Format
+ One Controller advances one Demand at a time. Concurrency is a second pod with
+ its own Controller, never a second Demand here.
- Use this shape when recording or reporting controller acceptance:
+ Entry points for the user: `/wakeflow-init` sets up or repairs the workspace, `/wakeflow-status` reports where it stands, `/wakeflow-next` takes the next step on the active Demand, and `/wakeflow-pod` creates or closes a pod.
- ```markdown
- ## Controller Acceptance
+ ## Reading order
- - User goal:
- - Scope reviewed:
- - Original requirement authority:
- - Target/window:
- - Target inputs inspected:
- - Independent checks run:
- - Implementation reality:
- - Validation result:
- - Blockers:
- - Missing review inputs:
- - Residual risks:
- - TODO/backlog rollup:
- - Decision:
- - Next action:
- ```
+ 1. This file, top to bottom, before your first tool call.
+ 2. `wakeflow_status` - the workspace's own answer to "what is next". Start
+ every turn here instead of guessing from the conversation.
+ 3. The step section below that matches what `status` named.
+ 4. `references/workspace-and-windows.md` - only when initializing or
+ reconfiguring the workspace, launching or retiring a window, or creating or
+ closing a pod.
+ 5. `references/delivery-and-review.md` - only when planning a task, preparing
+ a delivery, or deciding on a returned result.
+ 6. `references/evidence.md` - only before you record managed evidence.
- `Decision` must be one of:
+ Read a reference when you reach the step it covers, not in advance.
- - `accept-target-result`
- - `request-rework`
- - `request-redesign`
- - `mark-blocked`
- - `wait-for-missing-target`
- - `needs-user-decision`
- - `complete-demand`
- - `archive-completed-work`
- - `create-next-package`
+ ## Bounded expectations
- Never use `accepted` as a shorthand unless the independent checks, scope, and
- TODO rollup are already stated.
+ - Wakeflow holds state authority; you hold judgment. An inspection result or a
+ returned report is evidence, never acceptance. You accept by recording a
+ decision in your own words.
+ - Wakeflow never opens, inspects or closes a window, never sends a prompt, and
+ never edits a product repository. Those are your host actions, and each one
+ must be reported back through the tool that expects it.
+ - Never edit an active Demand root, a ledger record, a config file or a binding
+ file by hand. If a call is refused, read what it returned, fix the cause, and
+ call again. Do not route around a refusal.
+ - Never invent an identifier, a digest, a revision or an acceptance anchor.
+ Carry back exactly what the previous call returned.
+ - A preview writes nothing. Apply only with what that same preview returned; if
+ anything changed in between, preview again.
+ - Product repository and workspace `CLAUDE.md` files bind you.
- ## Target Craft Inputs At Acceptance
+ ## Main flow
- Every TaskPackage carries `reviewInputContract`. The machinery checks structural
- closure, not truth; validation and judgment remain yours:
+ ### Step 0 - Initialize or maintain the workspace
- - A completed TargetResult must provide an `evidenceLocators` entry for every
- package `requiredKinds` value. Each locator is exactly `{kind,ref,digest}`.
- Blocked or needs-review results may be partial, but must remain honest.
- - For a completed non-Test result, `craftMapping` contains exactly one
- `{kind:"acceptance-anchor",anchorId,evidenceRefs:[{ref,digest}]}` per package
- anchor. For a completed Test result, it contains each approved plan step once
- and in order as `{kind:"test-step",planIndex,step,ref}`. Mapping completeness
- is review readiness, not proof.
- - Independently inspect or rerun the referenced evidence. A locator proves only
- which bytes the target cited; it does not prove the claim or run repository
- commands for the controller.
- - A product result has exactly one `repositoryChanges` entry for its assigned
- repository, with `{repositoryId,disposition,commits}` consistent with the
- package's `commitExpectation`; a Test result has an empty array. The result
- contract does not carry a changed-files list, so inspect the cited VCS diff
- and evidence directly.
- - Read `verification`, `risks`, the summary, and exact prior review events. A
- corrected result may use the strict `supersedes` tuple, but current v3 exposes
- no rework/redesign counters or advisory craft taxonomy.
+ Collect the user's choices first (program identity, repositories, surfaces,
+ storage root). Call `wakeflow_maintain_workspace` in preview, show the plan and
+ its blockers to the user, and apply only after they confirm. Depth:
+ `references/workspace-and-windows.md`.
- ## Group Policies
+ ### Step 1 - Open windows and register their bindings
- - `group-ready`: wait until every expected target is ready or a blocker makes
- the group impossible. Then return once to the controller.
- - `per-target`: return when a target result arrives, still with group context.
- - Empty target groups are not grounds for completion.
- - A single target result is not group completion unless the group expected only
- that target.
+ Maintenance and pod creation return launch intents: a role, a root and the
+ parameters to start with. For each one: open a tmux window at the root the intent names, start `claude` in it with the parameters it lists, and let the session finish starting before you read its id. Then register the
+ handle you observed with `wakeflow_register_window_binding`. Registration needs
+ a real `session-start` hook record for that session and root - if none exists,
+ the window did not start where you think it did. Use the same tool to inspect a
+ window, replace a stale binding, retire a window, or force-release an expired
+ work claim.
- ## One Window Per Repo Within A Demand
+ ### Step 5 - Claim a requirement package into a Demand
- - WITHIN one demand, each repository has one active task lineage at a time and
- each target task binds one immutable TaskPackage. A package objective may
- describe coherent ordered steps, but the schema has no `items` collection.
- More work for the same repository arrives only through an exact replacement
- or completed-lineage continuation after the current lineage closes, never as
- a parallel target task.
- - Mainline work uses the configured mainline product window. A Pod product
- window (`<repo>__<pod>`) exists only after explicit user Pod authorization
- and a Claude-created worktree receipt. Wakeflow refuses a second active
- binding for the same `(host, demand, repo)`; it does not impose a numeric
- Pod or per-repository limit.
- - Merge/integration remains a human-reviewed repository decision. Logical Pod
- close records the host's disposition; it never treats a closed tmux session
- as proof that Claude removed a worktree or branch.
+ Call `wakeflow_inspect_board` to list what Design has published, choose one
+ pending package with the user, then call `wakeflow_create_demand` on it. The
+ Demand type, testing decision and authority members come from the package; you
+ do not restate them.
- ## Demand Pods (explicit parallel execution, never automatic placement)
+ ### Step 6 - Plan the target task
- - **Default:** ordinary and Auto Claim work uses the idle, healthy mainline.
- If mainline is busy, wait. Missing/unhealthy required mainline identity
- returns `mainline-unavailable` before demand/TODO mutation; repair the
- mainline. Never infer Pod placement from another active demand or a
- `Controller__*` name.
- - **Authorization:** a Pod demand must already carry
- `executionPlacement.selection=explicit-user-pod` and an auditable
- `authorizationRef`. Legacy `maxActiveDemands` / `maxStreamsPerRepo` fields
- are migration warnings only; they neither authorize nor reject a Pod.
- - One Pod = independent `Controller__<pod>`, `Design__<pod>`,
- `Test__<pod>`, and one product session per selected repository, all in the
- Pod's tmux container. Pods are mutually unaware and every controller-return
- uses that demand's stamped controller window.
- - Core `wakeflow_pod_open` is plan/reserve only. The v3 host adapter materializes its
- launch operations: control roles use distinct Claude sessions; each product
- starts from the exact repository root with native `claude --worktree`.
- Never nest Claude's `--tmux`, run Git worktree commands as a substitute, or
- grant the entire workspace root with a default `--add-dir`.
- - Record launch progress through `wakeflow_pod_record operation=record-materialization` immediately
- before the host call and `finalized` only after it returns the final
- Claude session id. Claude has no Codex `clientThreadId` pending state; never
- invent one or put a temporary request id in the registry.
- - Register only the final Claude session id, collect pane cwd/Git identity,
- then call `wakeflow_pod_bind`. A prompt assertion, suffix, or guessed path is
- not a binding. `control-ready` requires all three control bindings;
- `execution-ready` additionally requires the recorded Pod Design handoff and
- every planned product binding.
- - The Pod's single Design generation uses
- `wakeflow_pod_plan operation=design-request → PodDesignRequest →
- PodDesignHandoffEnvelope → wakeflow_pod_record operation=design-handoff`; the frozen
- request supplies exact lineage and cannot be replaced by a different
- request. Wakeflow does not yet persist multiple Pod Design generations:
- if a later supplement or redesign needs a new request/handoff, stop with a
- capability blocker. Never overwrite the frozen request, route the Pod
- through the mainline Design window, or create a duplicate global TODO.
- - Before Pod Test dispatch, call `wakeflow_pod_plan operation=test-access-plan`, execute
- that exact host-local probe from `Test__<pod>`, and record the redacted
- receipt with `wakeflow_pod_record operation=test-access-receipt`. Only validated
- `direct-multi-root` access across all active product bindings opens dispatch.
- Unsupported access stays blocked; a verifiable per-repository executor is
- not currently implemented.
- - Test ENVIRONMENTS may be physical singletons even though Test windows are
- per-pod: an exclusive environment (per the S1 Test Environment Spec) is a
- cross-pod serial resource — confirm no other pod is using it before
- dispatching the card.
- - Close is two-stage: core `wakeflow_pod_plan operation=close-intent` emits host-close intent;
- the v3 host adapter closes the exact tmux/Claude session and returns a separate worktree
- disposition for `wakeflow_pod_record operation=close-observe/close-receipt`. Only then does Wakeflow
- close the logical binding. Claude/user owns physical worktree cleanup.
- - `wakeflow_pod_open operation=inspect-materialization` plus
- `wakeflow_pod_plan operation=test-access-inspect/close-inspect` read the
- relevant Pod facts. They never guess identity from a worktree path or
- dynamic overlay. The legacy helper `pod-list` is not v3 authority.
- - Cancelling instead of finishing: `wakeflow_cancel_demand` stops an
- in-flight demand WITHOUT pretending completion — no acceptance, result
- history stays, open tasks keep their last honest status. A cancelled Pod still needs
- the same logical close receipts before archive.
+ Call `wakeflow_plan_target_task`. You write the goal, the boundary, the
+ completion expectation and the acceptance anchors; Wakeflow derives the window,
+ the environment and the baselines. Anchors must point at acceptance-criteria
+ items that exist in the package - an invented one is refused. When the package
+ asks for user review of the task plan, show the plan to the user before you
+ call apply. Depth: `references/delivery-and-review.md`.
- ## Completed Demand Continuations
+ ### Step 7 - Prepare the delivery
- - Completion is an accepted checkpoint, not permission to rewrite history. If
- a completed but unarchived demand later has a verified bug inside its
- original completion definition, a confirmed supplement to that definition,
- or an explicitly authorized optimization that the user says belongs to the
- same demand, use `wakeflow_continue_demand operation=create`.
- - Read the original plan / Requirement Design, accepted result history, and
- controller validation record first. Submit one complete new TaskPackage with
- `continuation:{kind,previousTaskPackageId,ref,digest,reason}`, where `kind` is
- exactly `verified-bug`, `requirement-supplement`, or `optimization`. It must
- extend the exact accepted/closed lineage head for the same repository,
- window, and work type; all prior tasks/packages must already be closed and
- the predecessor cannot already have a continuation child. The operation
- retains the earlier `demand.completed` event and returns state to `planned`;
- it does not dispatch or accept anything. The demand must pass normal review
- and `wakeflow_complete_demand` again.
- - Do not split the operation into a manual state edit followed by
- `wakeflow_add_task`, and do not create a temporary demand/pod to work around
- the terminal-state guard. If the operation fails, the completed state must
- remain unchanged.
- - Archived demand roots are immutable to workflow continuation. Public v3 has
- no sanitize or reopen target. A polluted legacy archive is explicit-migration
- input and must not be hand-edited. Independently scoped optimization, backlog
- work, or anything discovered after archive goes through the normal TODO /
- `wakeflow_create_demand` path with an explicit reference to the prior demand;
- never move or edit archived authority back into current state.
+ Call `wakeflow_prepare_delivery`. Write three short paragraphs in plain words:
+ what the target must achieve, where to focus, what is out of bounds. Wakeflow
+ takes the work claim, renders the prompt around your text and returns a
+ one-shot permit.
- ## Storage Hygiene (idle-moment habit)
+ ### Step 8 - Perform the host effect and record the outcome
- - Archive one completed/cancelled demand with `wakeflow_archive
- operation=preview`, review the portable whole-demand plan and privacy
- blockers, then use `operation=apply` only with the exact confirmed plan and
- digest. `inspect` is read-only and `recover` resumes only the named owner.
- - Public v3 has no docs/TODO/sanitize archive target. A polluted legacy archive
- is explicit-migration input; never hand-edit it or move it back into current
- authority.
- - In an idle moment, use `wakeflow_view operation=storage` for orientation.
- Legacy/unknown/preserved entries never authorize cleanup by themselves.
- - An unknown local tree routes to the user. For an explicitly selected keeper,
- use `wakeflow_storage_preserve operation=preview`, then apply only the exact
- confirmed plan. Never invent another holding location or auto-delete.
- - Release a preservation only through `operation=preview-release` followed by
- exact apply/recover. `wakeflow_prune_runtime` owns only whole-demand transport
- retention through preview/apply/recover after BusinessArchive and lease
- closure; audit preservation is not a prune target.
- - Context degradation runbook: when your context has been compacted to
- unreliability, stop and ask for a controller replacement — the controller
- is replaceable, the state roots are the memory.
+ Perform the host effect exactly once: paste the permit's prompt into the target window's pane and press Return, once, then capture that pane a single time. Then call
+ `wakeflow_record_delivery_outcome` with the permit's delivery identity and
+ fence. Wakeflow derives the disposition from evidence, not from your
+ impression: an accepted delivery needs the target session's
+ `user-prompt-submit` record matching the permit's prompt, or the host send
+ call's own success return. A missing readback is indeterminate, never a
+ failure, and an indeterminate delivery is never resent. Only a send call that
+ provably failed before touching the session may be re-armed with
+ `wakeflow_rearm_delivery`.
- ## Intent Alignment
+ ### Step 10 - Inspect the review unit
- - Two flexible sides, one check: Design's `designIntent` is a sketch, not a
- contract; the controller's `objective` is today's best arrangement, not a
- transcription. Deviation is often adaptation, not error — the check turns
- unconscious drift into a conscious confirmation, nothing more.
- - Dispatch moment: when the task package carries a designIntent, the prepare
- output shows it beside your objective. Authoring the objective IS the
- confirmation; make an intentional adaptation visible in its wording (author
- it at the FIRST prepare — same-revision re-prepares must not change content).
- - Review moment: the review pack shows designIntent / objective / result per
- task plus one `intentCheck` line. If the delivery departs from the design
- intent without a declared adaptation, run a requirement review (Original
- Plan / Requirement Design) first; if the requirement itself must change,
- decide `redesign`. Your decide-review reason is the confirmation record.
- - No scores, no gates: intent alignment never blocks anything;
- controller-validated acceptance stays the only verdict.
+ When the wake-controller callback lands in this window, call
+ `wakeflow_inspect_target_result_review`. It is read-only: it shows the task
+ package, the returned report, prior decisions, the callback landing, the
+ target's completion evidence and which decisions the rules currently allow.
+ Reading it is what acknowledges the callback.
- ## Stage Gates (route map: wakeflow-governance/references/stage-route-map.md)
+ Record any artifact you want to keep as evidence with `wakeflow_record_evidence`
+ before you rely on it in a decision. Depth: `references/evidence.md`.
- - Before the FIRST implementation dispatch of a demand, verify the frozen
- demand authority AT THE DEMAND'S SCALE: full six-role contract for a requirement; a bug
- needs reproduction + scope + non-goals + Test decision (no Original Plan
- ceremony); a supplement needs a delta against the existing Requirement
- Design; research never gets an implementation dispatch. Any missing item
- remains S1 and routes to its actual owner (Design or user). Total control may
- author an inline authority only for bounded/already-documented work whose
- anchors already exist; never invent a gate artifact to pass.
- - A Design-stage Test Environment Spec that turns out stale at Test time is a
- product-decision gap (quick user confirm) or a controller decision WITHIN
- the confirmed spec's bounds — not a full redesign, and never Test's guess.
- - Before adding or dispatching a Test package, verify every active required non-Test
- target is accepted, record the concrete controller reruns in
- `controllerSelfChecks`, and copy the Design-stage Test Environment Spec
- into the card's realScenarioConditions/allowedOperations. You DECIDE which
- confirmed environment applies; the user CONFIRMED it at Design; Test only
- EXECUTES. Never send Test hunting for env vars, endpoints, or credentials.
- - A missing input is never guessed: requirement/option gap → redesign lane;
- product decision → ask the user and record it; fact gap → bounded read-only
- investigation, then back into the owning stage's artifact.
+ ### Step 11 - Decide
- ## Stop Conditions
+ Form your own judgment from the code and the evidence, not from the report's
+ self-assessment. Record it with
+ `wakeflow_record_implementation_review_decision` for an implementation result
+ or `wakeflow_record_test_review_decision` for a test result. On escalate, hand
+ the user the issue, the options and your recommendation, then bring their
+ answer back through `wakeflow_continue_demand`. Depth:
+ `references/delivery-and-review.md`.
- Stop instead of dispatching when:
+ ### Step 12 - Complete and archive
- - The user goal or completion definition is unclear.
- - The proportional demand authority is incomplete for a new demand's first implementation
- dispatch, or a Test dispatch leaves an existing non-Test target unaccepted,
- omits the controller's self-checks, or lacks its confirmed environment block.
- - Required review inputs are missing or unreadable.
- - The state root is not current or cannot be trusted.
- - The controller is reacting to a keyword, familiar command shape, script hint,
- or urgency before naming the safe operation, recovery boundary, explicit
- plan, and smallest valid next step.
- - A target window session, repository, upstream dependency, or real thread id
- (the registered Claude Code session id) is missing.
- - The next action would change scope, delete capability, downgrade capability,
- or make a product decision without user confirmation.
- - The next action would add a TODO, follow-up requirement, task package, or
- scope expansion from code facts, test output, target backfill, implementation
- leftovers, or residual fields without first reading the full original plan /
- requirement design and confirming that the addition stays inside the original
- decisions and non-goals.
- - A target result lacks reviewable inputs.
- - Review inputs are only target prose, superficial script output, or status-table
- motion.
- - Test says its result is acceptable but the controller has not inspected the
- named materials and run its own relevant probe.
- - The result is only an empty interface, static mock, unused adapter, type-only
- contract, unreachable route, or documentation motion without a real consumer
- and validation path.
- - Test exposed a product defect after the owning repository lineage was already
- accepted. Preserve the exact Test evidence and stop: current public v3 cannot
- reopen that lineage or add its same-demand fix before completion. Do not
- rework the Test task as a product repair or complete a known-defective demand
- merely to unlock continuation.
- - Controller validation establishes a non-bug outcome mismatch, or a small requirement-level fix that is
- Design's job and not a code defect: `wakeflow_decide_review operation=decide`
- with decision `redesign` parks the affected task as `needs-rework` instead of
- bouncing point fixes between product windows.
- For a mainline demand, surface the redesign to the stateless mainline Design window with
- `wakeflow_deliver`; after the corrected requirement returns, add a full-context replacement
- package to the SAME demand with `replacesTargetTask` bound to the parked
- target's exact task/package tuple. Do
- not create a new demand or re-dispatch the old task. For a Pod demand, do not use mainline
- Design: Wakeflow cannot create a second frozen Pod Design generation, so keep the
- demand blocked and report that capability gap rather than overwriting the recorded handoff.
- Accepting a valid replacement marks the old task/package `superseded`; the
- parked demand's event history remains intact.
- - A completed result would leave TODO/backlog, archive state, or current status
- inconsistent.
- - The controller is about to poll/wait for targets after a send was recorded
- (the controller-return delivery and the activity-monitor sentinel are the
- wake-ups; in-turn waiting is never allowed).
- - There are no eligible tasks.
+ When every target is accepted, call `wakeflow_complete_demand`. Preview runs
+ the gates and lists blockers without writing; apply seals the archive and
+ deletes the active root in one transaction. To end a Demand that will not be
+ finished, use `wakeflow_cancel_demand` - results and evidence are kept. To
+ reopen a completed Demand for follow-up work, use `wakeflow_continue_demand`.
- ## Verification
+ ### Step 13 - Close the pod
- Use the smallest verification that covers the changed surface. For Wakeflow
- total-control work in an installed workspace, use MCP tools instead of direct
- runtime scripts:
+ After the user has merged or abandoned the pod's branch and its Demand is
+ archived, close the pod with `wakeflow_pod`. Closing is two phases: record the
+ branch dispositions, then remove the pod once its windows are retired and its
+ checkouts are gone. Depth: `references/workspace-and-windows.md`.
- - `wakeflow_verify operation=inspect` for the strict workspace verdict.
- - `wakeflow_status operation=inspect` for current v3 orientation.
- - `wakeflow_next_work operation=inspect` for TODO authority inspection.
- - `wakeflow_archive operation=preview/apply/inspect/recover` for one portable
- whole-demand BusinessArchive.
- - `wakeflow_create_demand`, `wakeflow_add_task`, `wakeflow_complete_demand`,
- `wakeflow_continue_demand`,
- `wakeflow_prepare_delivery`, `wakeflow_record_delivery`,
- `wakeflow_record_target_result`, `wakeflow_review_pack`,
- `wakeflow_reduce_results`, and `wakeflow_decide_review` for state-root,
- result review, and delivery mechanics.
+ ## Checking the workspace
- Do not run `node .../plugins/cache/.../wakeflow/.../scripts/*.mjs`, copy
- installed runtime script paths, or infer script flags from old docs during
- normal total control. If the Wakeflow MCP tool surface is unavailable, stop and
- report that the plugin must be reloaded or reinstalled.
+ `wakeflow_status` is one read across every domain and always names the next
+ actions. `wakeflow_verify` is the strict read: each gate passes, fails, or is
+ unavailable, and it repairs nothing. Run `wakeflow_verify` when `status` looks
+ wrong, before completing a Demand, and whenever a delivery looked sent but no
+ evidence arrived.
- Only when the current repository is Wakeflow source and the user is maintaining
- Wakeflow scripts or automation, source-repo verification may use:
+ ## What you must return to the user
- - `npm run validate`
- - `npm run validate:claude`
- - `npm run smoke`
- - `npm run smoke:claude`
- - `npm run check:core`
- - `npm test`
+ - What you did, in their words, and what Wakeflow recorded.
+ - The evidence behind any claim of success - which record, which gate, which
+ hook observation. Never report a host effect as done on the strength of
+ having attempted it.
+ - What is next and who owns it.
+ - Anything you could not verify, named as unverified.
- Script output is a review input, not acceptance.
+ ## Stop conditions
- - Use `wakeflow_release_window_lock operation=release` only when the owning
- operation explicitly returns the exact current binding/lease/delivery CAS
- tuple. Never release by semantic window name, omit identity, infer rejection
- from prose, or delete a lease file. Accepted, ambiguous, and
- sent-unconfirmed target effects retain their authority until the proper
- result/rearm/lifecycle owner closes it.
+ Stop and ask the user when: a preview reports a blocker you cannot resolve
+ without a decision; a host effect is unavailable; evidence contradicts a
+ report; or an action would need a second active Demand in this Controller.