wu:prep

← Back to CLI Commands

wu:prep

Run gates in worktree, prep for wu:done

pnpm wu:prep --id <wuId>

Integration target binding

Prep, its gate evidence and review evidence use the claim’s pinned integration target (remote, branch, repository identity, baseline and trusted policy), never the current workspace default. A substituted remote or changed policy identity refuses instead of redirecting the claim.

When only the trusted policy content moved on the integration target after the claim (a lane:edit, a gate config change) and this WU’s own branch changed none of workspace.yaml, LUMENFLOW.md or LUMENFLOW.local.md, prep re-pins the claim itself through the governed policy refresh, records a claim_policy_refresh ledger event (old and new digest, reason main-moved), runs wu:brief for the successor generation, and re-runs, so every gate runs under the live policy with no manual repair, rebase or brief. A branch that changes trusted policy keeps the CLAIM_POLICY_PIN_STALE refusal.

Repair: a claim that predates integration-target binding is upgraded through the governed same-target route. Run pnpm wu:repair --id WU-XXXX --claim --integration-target --check first, then the same command without --check. It adopts only the destination and policy that canonical and remote evidence prove, and refuses guesses and conflicts. No command retargets an active claim.

Root and worktree release skew

When the worktree has its own installed @hellmai/lumenflow-cli whose release differs from the CLI running wu:prep or wu:done, the command refuses before the worktree gates run, naming both releases and the install command (pnpm --dir "<worktree>" install). Equal releases run as before; a framework source checkout builds its own branch source and is not compared.

A gates child started with --wu-id and --main-checkout but no --claim-generation (a previous release’s wu:done re-running gates in a newer worktree) derives the generation from the worktree’s claim binding and proves it through the same canonical loader as the explicit flag. An absent or ambiguous binding refuses. A checkpoint-reuse refusal names the base the prep validated and prints pnpm wu:rebase --id WU-XXXX, then pnpm wu:prep --id WU-XXXX.

Checkpoint reuse and the gate set

The gate checkpoint wu:prep writes records the stable ids of the gates it executed and a digest of the gate configuration that selected them. wu:done resolves the gates it requires with the same function and reuses the checkpoint only if every required gate was executed and the configuration digest is unchanged; otherwise reuse is refused with the audited code gate-set-mismatch, and wu:done runs the full gate set itself. This covers every optional or configurable gate: with software_delivery.gates.delivery_review.enabled and auto_run: false, prep does not run delivery_review, so wu:done runs it instead of skipping it. With auto_run: true prep runs it and the checkpoint is reused. A checkpoint from an older release (schema version 1) is never reused.

Options:

Flag	Description	Required
-i, --id <wuId>	Work Unit ID. Required except on wu:create, which auto-generates the next sequential ID when omitted.	Yes
--docs-only	Force the docs-only gate plan (format, spec-linter). Prep otherwise derives this automatically from the work unit’s classification (type/code_paths) via classifyDocsOnly, the same formula wu:done uses.	No
--full-tests	Run test_full once (disable tests.unit and incremental execution). Evidence reuse is disabled: —full-tests always runs gates fresh.	No
-f, --force	Force operation	No
-r, --reason <reason>	Reason for action (required with —skip-gate, —override-owner)	No
--fix-wu <wuId>	WU ID that will fix the failures (required with —skip-gate)	No
--skip-gate &lt;name&gt;	Skip a single named gate (repeatable). Requires —reason and —fix-wu. Only gates marked skippable: true (or overridden via software_delivery.gates.overrides.<name>.skippable=true) may be skipped. Per-invocation only: never inherited from a prior wu:prep or wu:done attempt. On a resumed wu:done after an earlier failed attempt used this flag, restate —skip-gate/—reason/—fix-wu identically on THIS invocation if the skip is still needed; omitting them runs the named gate and records pass or fail rather than silently reusing the earlier decision.	No
--allow-unread-signals	Allow prep to continue with unread directed mem:signal entries; requires —reason	No
--latency-budget-exception	Waive the enforced local_prep.latency_budget for this run; requires —latency-budget-reason. Waives the BUDGET only — it never skips a gate and never applies to a run whose gates did not all pass. Granted waivers and refusals are recorded to .lumenflow/latency-budget-exceptions.ndjson.	No
--latency-budget-reason &lt;reason&gt;	Mandatory justification for —latency-budget-exception. Recorded verbatim in the latency-budget audit trail; never shared with —reason.	No
--handoff-receipt &lt;receipt&gt;	Consume a durable wu:brief lifecycle handoff receipt for cross-session authority	No

---

← Back to CLI Commands