@lumenflow/cli 4.23.0 → 5.0.0

package/templates/core/ai/onboarding/existing-project-bootstrap.md.template

@@ -0,0 +1,171 @@
+# Adopting LumenFlow on an Existing Project
+
+**Last updated:** {{DATE}}
+
+For agents running `lumenflow init` on a repo that already has code, tests, and (likely) uncommitted work. If you are in a project where LumenFlow is already configured, use [first-15-mins.md](./first-15-mins.md) instead — this doc is only for the adoption event itself.
+
+---
+
+## Why This Doc Exists
+
+The default Quick Start in [starting-prompt.md](./starting-prompt.md) assumes LumenFlow is already set up. Real adoption sessions have three extra hazards that are not obvious from the main flow:
+
+1. `lane:setup` silently lost commits when `workspace.yaml` was untracked (fixed in WU-2591; older CLI versions still exhibit the bug).
+2. Enforcement hooks activate immediately after `lumenflow:integrate`, so any pre-existing uncommitted work suddenly needs a WU to commit — but that work was authored before lane lock, so no WU exists for it.
+3. The `LUMENFLOW_FORCE` / `LUMENFLOW_FORCE_REASON` escape hatch is legitimate exactly once during adoption, and misunderstanding that window leads to either data loss (force-pushing over history) or theatre (creating fake WUs to retroactively bless existing files).
+
+Follow the sequence below to avoid all three.
+
+---
+
+## Pre-Flight: Clean Your Working Tree
+
+Before `lumenflow init`, decide what to do with any uncommitted work:
+
+```bash
+git status
+```
+
+- **Clean tree:** proceed to the next section.
+- **In-progress work you want to keep:** commit it first with your normal workflow, or `git stash` it. Do not run `lumenflow init` with uncommitted unrelated changes in the tree.
+- **Incidental scratch:** discard it (`git restore`, `git clean -f`) — easier than reasoning about whether it belongs in the baseline commit.
+
+Rule of thumb: **everything that exists in your working tree at the moment of `lumenflow init` is about to become "pre-LumenFlow baseline" from the workflow's point of view.** Make sure that framing is accurate.
+
+---
+
+## Step 1: Install and Initialize
+
+```bash
+pnpm add -D @lumenflow/cli
+pnpm lumenflow --client <claude-code | cursor | windsurf>
+```
+
+`lumenflow init` generates `workspace.yaml`, LumenFlow directories (`.lumenflow/`, `{{DOCS_OPERATIONS_PATH}}/`), vendor config (`CLAUDE.md`, `AGENTS.md`, etc.), and — for clients that support it — enforcement hooks.
+
+At this point `workspace.yaml` exists but is **untracked**. This is the trap.
+
+---
+
+## Step 2: Commit the Baseline Before `lane:setup`
+
+This single command prevents the most common adoption footgun:
+
+```bash
+git add workspace.yaml
+git commit -m "chore: workspace.yaml baseline"
+```
+
+Why: `lane:setup` uses micro-worktree isolation to produce an atomic commit of your lane definitions. It commits inside a temp branch, then merges into local main. If `workspace.yaml` is untracked in main at merge time, git refuses the merge ("would be overwritten by merge") and the cleanup step discards the temp branch — your lane setup commit is silently lost. Modern CLI versions (post-WU-2591) refuse to run and tell you to commit first. Older versions fail silently.
+
+Also commit the other init-generated files in the same logical baseline. Keep it to one commit if you can:
+
+```bash
+git add AGENTS.md CLAUDE.md LUMENFLOW.md .lumenflow/ .claude/ {{DOCS_OPERATIONS_PATH}}/
+git commit -m "chore: LumenFlow scaffold"
+```
+
+---
+
+## Step 3: Lane Lifecycle
+
+```bash
+pnpm lane:suggest             # optional: infer lane topology from project structure
+pnpm lane:setup               # generate draft lane definitions
+pnpm lane:list                # inspect what was generated
+pnpm lane:edit --name <lane> --rename <new-name> --add-path <glob>  # tailor as needed
+pnpm lane:validate
+pnpm lane:lock
+```
+
+Key points:
+
+- `lane:setup` emits a set of opinionated template lanes. To reshape them into your topology, use `lane:edit --rename` (and `lane:remove` for ones you don't want). Do not hand-edit `workspace.yaml` — that violates [Constraint 9](../../../../../.lumenflow/constraints.md) and bypasses schema validation.
+- `lane:list` is read-only and prints names, WIP limits, and code paths. Use it whenever you lose track of available lane names.
+- Once `lane:lock` runs, the workflow transitions from setup mode to delivery mode: from now on, edits flow through WUs.
+
+---
+
+## Step 4: Handling Pre-Existing Work That Was Not Committed in Step 2
+
+This is where most adoption sessions go wrong.
+
+After `lane:lock`, enforcement hooks block any file edit that is not part of a claimed WU. If you still have pre-LumenFlow files in the working tree, you have two options:
+
+### Option A (recommended): Sealed Baseline Commit
+
+Commit the pre-existing work as a single "baseline seal" using the documented escape hatch:
+
+```bash
+git status                          # confirm scope — only pre-LumenFlow files should appear
+git add <specific-files>            # avoid blanket `git add -A`
+LUMENFLOW_FORCE=1 \
+  LUMENFLOW_FORCE_REASON="Phase 0 baseline seal YYYY-MM-DD: pre-LumenFlow source (tests, docs, config) existing before lane lock. All subsequent edits route through WUs." \
+  git commit -m "chore: pre-LumenFlow baseline seal"
+```
+
+This is the **one legitimate use** of `LUMENFLOW_FORCE` during adoption. The bypass is audited to `.lumenflow/force-bypasses.log` (git-tracked) with your reason. A specific, dated reason is more useful six months later than "bootstrap".
+
+Rules:
+
+- **One commit**, not several. If you find yourself wanting a second force commit, you are past the bootstrap window — stop and claim a WU instead.
+- **Scope-check first.** Run `git diff --stat` and verify every path is genuinely pre-LumenFlow. Do not smuggle net-new work through the baseline seal.
+- **Do not `--no-verify`**. The hook has an explicit escape; use it with a reason so the audit log remains coherent.
+
+### Option B: Retroactive WUs (not recommended)
+
+Create one WU per lane, claim it, and commit the pre-existing files inside its worktree. This produces a trail of WUs whose evidence says "this WU authored these files" when the reality is "this WU ritualistically committed pre-existing content." That pollutes the evidence graph and is not a better audit trail — it is a worse one. Use this path only if you have a specific reason to split the baseline across lane boundaries for downstream metrics.
+
+---
+
+## Step 5: Verify and Commit the First Real WU
+
+```bash
+pnpm lumenflow:doctor            # expect clean or only informational notices
+pnpm lane:status                 # should report "locked"
+git status                       # should be clean
+```
+
+If all three are green, create your first real WU:
+
+```bash
+pnpm wu:create --lane "<Lane>" --title "..." --type feature --description "..."
+pnpm wu:claim --id WU-NNNN --lane "<Lane>"
+```
+
+From this point on, follow [first-15-mins.md](./first-15-mins.md) or [starting-prompt.md](./starting-prompt.md) as the canonical flow.
+
+---
+
+## When `LUMENFLOW_FORCE` Is NOT the Right Tool
+
+The baseline seal in Step 4 is the only adoption-time use. `LUMENFLOW_FORCE` is **not** a way to:
+
+- Skip a failing gate. Fix the gate or claim a bug WU.
+- Commit from main without a WU after adoption is complete. Claim a WU.
+- Work around the pre-commit hook because it is inconvenient. The hook is enforcing the rule; the rule is the point.
+- Bypass `wu:done` to "finalize" a WU. Run `wu:prep` first and fix whatever it reports.
+
+See [.lumenflow/constraints.md](../../../../../.lumenflow/constraints.md) ("Agent LUMENFLOW_FORCE Usage Policy") for the full policy. Agents must not use `LUMENFLOW_FORCE` without explicit user approval, except for the one-time baseline seal described above — and even then, a specific `LUMENFLOW_FORCE_REASON` is required.
+
+---
+
+## Common Footguns and Where to Find Them
+
+| Symptom                                                           | Cause                                          | Fix                                                                |
+| :---------------------------------------------------------------- | :--------------------------------------------- | :----------------------------------------------------------------- |
+| `lane:setup` prints "merge rejected" and exits                    | `workspace.yaml` untracked                     | Commit it first (Step 2). Modern CLI refuses before the temp merge |
+| `lane:edit --name "Foo"` → "Lane not found"                       | Typo or drift from canonical "Parent: Sublane" | Run `pnpm lane:list`; use the "Did you mean" hint in the error     |
+| Pre-commit hook blocks a commit you believe is legitimate         | Enforcement active, no claimed WU              | Claim a WU first; use `LUMENFLOW_FORCE` only for the baseline seal |
+| `lumenflow:doctor` reports managed files with uncommitted changes | Step 4 incomplete                              | Finish the baseline seal, then re-run doctor                       |
+| A second `LUMENFLOW_FORCE` commit feels necessary                 | Scope of the baseline was underestimated       | Revert the first, widen the scope, re-do as a single seal          |
+
+---
+
+## Related Documentation
+
+- [first-15-mins.md](./first-15-mins.md) — once the project is configured
+- [starting-prompt.md](./starting-prompt.md) — full onboarding reference
+- [.lumenflow/constraints.md](../../../../../.lumenflow/constraints.md) — LUMENFLOW_FORCE policy
+- [lumenflow-force-usage.md](./lumenflow-force-usage.md) — retrospective analysis of real-world force-bypass usage
+- [first-wu-mistakes.md](./first-wu-mistakes.md) — common WU-lifecycle errors after adoption

package/templates/core/ai/onboarding/first-15-mins.md.template

@@ -2,7 +2,9 @@
 
 **Last updated:** {{DATE}}
 
-A fast start for agents entering an existing LumenFlow project.
+A fast start for agents entering an **already-configured** LumenFlow project.
+
+> **Adopting LumenFlow right now?** If you are running `lumenflow init` on a project that has never used LumenFlow before, read [existing-project-bootstrap.md](./existing-project-bootstrap.md) first. This doc assumes `workspace.yaml` is committed, lanes are locked, and enforcement hooks are active.
 
 ---
 

package/templates/core/ai/onboarding/first-wu-mistakes.md.template

@@ -340,7 +340,7 @@ sizing_estimate:
 pnpm wu:brief --id WU-XXX --client claude-code --strict-sizing
 ```
 
-See the [WU Sizing Guide](../../wu-sizing-guide.md) section 1.5 for the full contract specification.
+See the [WU Sizing Guide](../../wu-sizing-guide.md) section 1.6 for the full contract specification.
 
 ---
 

package/templates/core/ai/onboarding/initiative-orchestration.md.template

@@ -25,7 +25,7 @@ Before orchestrating an initiative, ensure:
 When orchestrating an initiative, reason in these layers:
 
 1. **Planning** -- `orchestrate:initiative --dry-run` computes logical waves and bottlenecks.
-2. **Handoff** -- `wu:delegate` / `wu:brief` generate worker context and record evidence.
+2. **Handoff** -- `wu:delegate` / `wu:brief` generate the canonical worker context and record evidence. `orchestrate:initiative -c` and continuous mode print lean launch summaries by default and point at durable handoff artifacts instead of dumping prompt bodies to stdout.
 3. **Execution** -- workers claim the WU and produce work in a worktree or branch-pr lane branch.
 4. **Reconciliation** -- the orchestrator inspects WU status, worktree/branch state, gate results, stamps, and memory receipts to decide what actually happened.
 5. **Finish** -- ready WUs go through `wu:prep`, then `wu:done` (or `wu:cleanup` after merge in branch-pr mode).
@@ -61,15 +61,20 @@ Before accepting the wave plan, sanity-check the decomposition. If several WUs s
 
 ### Step 2: Choose Execution Mode
 
-| Mode                  | Command                                              | When to use                            |
-| --------------------- | ---------------------------------------------------- | -------------------------------------- |
-| Checkpoint-per-wave   | `pnpm orchestrate:initiative -i INIT-XXX -c`         | Large initiatives (>3 WUs or >2 waves) |
-| Continuous            | `pnpm orchestrate:initiative -i INIT-XXX`            | Small initiatives (<=3 WUs, 1-2 waves) |
-| Manual brief/delegate | `pnpm wu:brief --id WU-XXX --client <client>` per WU | Testing individual WUs, debugging      |
-| Manual self-implement | `pnpm wu:brief --id WU-XXX --client <client>` per WU | You are implementing without sub-agent |
+| Mode                  | Command                                                       | When to use                             |
+| --------------------- | ------------------------------------------------------------- | --------------------------------------- |
+| Checkpoint-per-wave   | `pnpm orchestrate:initiative -i INIT-XXX -c`                  | Large initiatives (>3 WUs or >2 waves)  |
+| Continuous            | `pnpm orchestrate:initiative -i INIT-XXX`                     | Small initiatives (<=3 WUs, 1-2 waves)  |
+| Inline handoff replay | `pnpm orchestrate:initiative -i INIT-XXX -c --print-handoffs` | Manual copy/paste from stored artifacts |
+| Manual brief/delegate | `pnpm wu:brief --id WU-XXX --client <client>` per WU          | Testing individual WUs, debugging       |
+| Manual self-implement | `pnpm wu:brief --id WU-XXX --client <client>` per WU          | You are implementing without sub-agent  |
 
 Checkpoint-per-wave is recommended for most initiatives. It processes one logical wave at a time and writes checkpoint artifacts before exiting, giving you control between waves.
 
+`orchestrate:initiative -c` and continuous mode print the
+wave summary, next actions, artifact bundle paths, and per-WU handoff file paths by default. Use
+`--print-handoffs` only when a human needs the stored handoff body inline for manual copy/paste.
+
 ### Step 3: Delegate WUs
 
 For each WU in the current wave, choose delegation vs self-implementation:
@@ -96,6 +101,11 @@ pnpm wu:delegate --id WU-100 --parent-wu WU-050 --client claude-code
 
 `wu:brief` always outputs full WU context and records evidence in a single step. There is no separate evidence-only mode.
 
+For supported clients, initiative orchestration uses the same canonical handoff renderer as
+`wu:brief` / `wu:delegate` when it writes launch artifacts. Treat the stored handoff artifact as the
+source of truth for launch content. Do not prepend or append a separate wrapper block around the
+generated handoff.
+
 Whether you hand off manually or via `orchestrate:initiative`, the handoff material is only a launch candidate. A WU is not truly live until a worker claims it, and it is not complete until the lifecycle reaches its completion boundary:
 
 - **Launched** -- a worker actually claims the WU (or an equivalent launch receipt exists) and the worktree / lane branch exists.
@@ -108,7 +118,8 @@ Whether you hand off manually or via `orchestrate:initiative`, the handoff mater
 2. The `</constraints>` block is present near the end
 3. The `LUMENFLOW_TRUNCATION_WARNING` banner is at the start
 
-If any of these are missing, the prompt was truncated. Re-generate it or use `--codex` for a shorter format.
+If any of these are missing, the prompt was truncated. Re-generate it or inspect the stored handoff
+artifact via `--print-handoffs`. Do not "fix" a truncated brief by inventing extra wrapper text.
 
 ### Step 4: Monitor Progress
 
@@ -180,12 +191,12 @@ Wave 2 Agent (WU-103)                          │
 
 ### Key Commands
 
-| Command                          | Who runs it    | When                          |
-| -------------------------------- | -------------- | ----------------------------- |
-| `mem:signal "msg" --wu WU-XXX`   | Worker agent   | After significant progress    |
+| Command                          | Who runs it    | When                              |
+| -------------------------------- | -------------- | --------------------------------- |
+| `mem:signal "msg" --wu WU-XXX`   | Worker agent   | After significant progress        |
 | `mem:inbox --since <duration>`   | Orchestrator   | Read signal traffic between waves |
-| `mem:checkpoint "msg" --wu WU-X` | Worker agent   | Before risky operations       |
-| `mem:ready --wu WU-XXX`          | Recovery agent | When taking over a stuck WU   |
+| `mem:checkpoint "msg" --wu WU-X` | Worker agent   | Before risky operations           |
+| `mem:ready --wu WU-XXX`          | Recovery agent | When taking over a stuck WU       |
 
 ### Signal Storage
 
@@ -204,6 +215,10 @@ When running with `--checkpoint-per-wave` (or `-c`):
 3. It writes checkpoint artifacts, including compatibility files under `.lumenflow/artifacts/waves/`
 4. It exits (does not poll or wait)
 
+Stdout stays lean in this mode. By default it prints launch receipts and per-WU handoff artifact
+paths, not inline XML/markdown bodies. `--print-handoffs` replays the stored handoff artifacts
+inline when manual copy/paste is needed.
+
 If the selected client cannot be invoked directly, checkpoint mode may stop at handoff generation and wait for the operator or agent runtime to launch workers. Treat that as **handoff prepared**, not **execution proved**.
 
 ### Checkpoint Artifact Model
@@ -431,23 +446,24 @@ pnpm delegation:list --initiative INIT-XXX --json
 
 ## Quick Reference: All Orchestration Commands
 
-| Command                                             | Description                                              |
-| --------------------------------------------------- | -------------------------------------------------------- |
-| `pnpm orchestrate:initiative -i INIT-XXX --dry-run` | Preview logical waves and bottlenecks without executing  |
-| `pnpm orchestrate:initiative -i INIT-XXX -c`        | Prepare/launch one logical wave, write checkpoints, exit |
-| `pnpm orchestrate:initiative -i INIT-XXX`           | Continue launch/reconciliation flow across waves         |
-| `pnpm orchestrate:init-status -i INIT-XXX`          | Initiative status surface (reconcile against WU truth when debugging) |
-| `pnpm orchestrate:monitor`                          | Detect stuck agents, zombie locks, and recovery signals  |
-| `pnpm wu:brief --id WU-XXX --client <client>`       | **MANDATORY after wu:claim.** Generate prompt + evidence |
-| `pnpm wu:delegate --id WU-XXX --parent-wu <P>`      | Generate prompt + record delegation                      |
-| `pnpm delegation:list --initiative INIT-XXX`        | View delegation tree / launch lineage                    |
-| `pnpm mem:signal "msg" --wu WU-XXX`                 | Broadcast coordination signal                            |
-| `pnpm mem:inbox --since <duration>`                 | Read signal traffic (not the full execution ledger)      |
-| `pnpm mem:checkpoint "msg" --wu WU-XXX`             | Save progress checkpoint                                 |
-| `pnpm mem:ready --wu WU-XXX`                        | Check pending work/checkpoints                           |
-| `pnpm wu:block --id WU-XXX --reason "..."`          | Block stuck WU                                           |
-| `pnpm wu:unblock --id WU-XXX`                       | Unblock recovered WU                                     |
-| `pnpm wu:release --id WU-XXX`                       | Release abandoned WU for re-claim                        |
+| Command                                                       | Description                                                                   |
+| ------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `pnpm orchestrate:initiative -i INIT-XXX --dry-run`           | Preview logical waves and bottlenecks without executing                       |
+| `pnpm orchestrate:initiative -i INIT-XXX -c`                  | Prepare/launch one logical wave, write checkpoints, print lean launch summary |
+| `pnpm orchestrate:initiative -i INIT-XXX`                     | Continue launch/reconciliation flow across waves with lean stdout             |
+| `pnpm orchestrate:initiative -i INIT-XXX -c --print-handoffs` | Replay stored handoff artifacts inline for manual copy/paste                  |
+| `pnpm orchestrate:init-status -i INIT-XXX`                    | Initiative status surface (reconcile against WU truth when debugging)         |
+| `pnpm orchestrate:monitor`                                    | Detect stuck agents, zombie locks, and recovery signals                       |
+| `pnpm wu:brief --id WU-XXX --client <client>`                 | **MANDATORY after wu:claim.** Generate the canonical full handoff + evidence  |
+| `pnpm wu:delegate --id WU-XXX --parent-wu <P>`                | Generate prompt + record delegation                                           |
+| `pnpm delegation:list --initiative INIT-XXX`                  | View delegation tree / launch lineage                                         |
+| `pnpm mem:signal "msg" --wu WU-XXX`                           | Broadcast coordination signal                                                 |
+| `pnpm mem:inbox --since <duration>`                           | Read signal traffic (not the full execution ledger)                           |
+| `pnpm mem:checkpoint "msg" --wu WU-XXX`                       | Save progress checkpoint                                                      |
+| `pnpm mem:ready --wu WU-XXX`                                  | Check pending work/checkpoints                                                |
+| `pnpm wu:block --id WU-XXX --reason "..."`                    | Block stuck WU                                                                |
+| `pnpm wu:unblock --id WU-XXX`                                 | Unblock recovered WU                                                          |
+| `pnpm wu:release --id WU-XXX`                                 | Release abandoned WU for re-claim                                             |
 
 ---
 

package/templates/core/ai/onboarding/quick-ref-commands.md.template

@@ -21,6 +21,9 @@ Reference for CLI commands. Organized by category for quick discovery.
 >
 > **Never conclude a command doesn't exist without running `pnpm lumenflow:commands` first.**
 >
+> Maintainers: when the public CLI surface changes, update the canonical onboarding sources and
+> rerun `pnpm docs:sync` so scaffold-like onboarding copies stay aligned.
+>
 > Repo-only scripts such as `pnpm docs:validate`, `pnpm docs:generate`, and
 > `pnpm pre-release:check` are maintainer scripts, not part of the public CLI manifest.
 >
@@ -73,9 +76,9 @@ Run `--help` first, then run the real command with explicit flags.
 | `pnpm lumenflow:upgrade`                 | Upgrade LumenFlow packages                                                              |
 | `pnpm lumenflow:doctor`                  | Diagnose LumenFlow configuration                                                        |
 | `pnpm lumenflow:integrate`               | Generate enforcement hooks for client                                                   |
-| `pnpm lumenflow:disable`                 | Turn enforcement off reversibly (regenerates hooks as no-ops)                            |
-| `pnpm lumenflow:enable`                  | Re-enable enforcement after `lumenflow:disable` (restores prior state)                   |
-| `pnpm lumenflow:uninstall`               | Remove LumenFlow-generated files (dry-run by default; `--confirm` required)              |
+| `pnpm lumenflow:disable`                 | Turn enforcement off reversibly (regenerates hooks as no-ops)                           |
+| `pnpm lumenflow:enable`                  | Re-enable enforcement after `lumenflow:disable` (restores prior state)                  |
+| `pnpm lumenflow:uninstall`               | Remove LumenFlow-generated files (dry-run by default; `--confirm` required)             |
 | `pnpm cloud:connect`                     | Configure cloud control-plane access                                                    |
 | `npx lumenflow commands`                 | List all available CLI commands                                                         |
 
@@ -196,32 +199,32 @@ without explicit human instruction.**
 
 ## Gates & Quality
 
-| Command                                                            | Description                                          |
-| ------------------------------------------------------------------ | ---------------------------------------------------- |
-| `pnpm gates`                                                       | Run all quality gates                                |
-| `pnpm gates:docs`                                                  | Preferred docs-only alias (`pnpm gates --docs-only`) |
-| `pnpm gates --docs-only`                                           | Equivalent flag form for docs-only gates             |
-| `pnpm format`                                                      | Format all files (Prettier)                          |
-| `pnpm format:check`                                                | Check formatting without changes                     |
-| `pnpm lint`                                                        | Run ESLint                                           |
-| `pnpm typecheck`                                                   | Run TypeScript type checking                         |
-| `pnpm test`                                                        | Run all tests (Vitest)                               |
-| `pnpm spec:linter`                                                 | Validate WU specs (all) ¹                            |
-| `pnpm lane:health`                                                 | Check lane config health                             |
-| `pnpm lane:suggest --output workspace.lanes.yaml`                  | Generate a workspace lane-definition snippet         |
-| `pnpm lane:status`                                                 | Show lane lifecycle status                           |
-| `pnpm lane:setup`                                                  | Create/update draft lane config                      |
-| `pnpm lane:validate`                                               | Validate lane draft artifacts                        |
-| `pnpm lane:lock`                                                   | Lock lane lifecycle for WU create                    |
-| `pnpm lane:edit --name <L>`                                        | Edit lane definition (rename, wip-limit, paths)      |
-| `pnpm gate:co-change --add --name <N> --trigger <G> --require <G>` | Add co-change gate rule                              |
-| `pnpm gate:co-change --remove --name <N>`                          | Remove co-change gate rule                           |
-| `pnpm gate:co-change --edit --name <N> --severity <S>`             | Edit co-change gate rule                             |
-| `pnpm gate:co-change --list`                                       | List all co-change rules (built-in + custom)         |
+| Command                                                              | Description                                          |
+| -------------------------------------------------------------------- | ---------------------------------------------------- |
+| `pnpm gates`                                                         | Run all quality gates                                |
+| `pnpm gates:docs`                                                    | Preferred docs-only alias (`pnpm gates --docs-only`) |
+| `pnpm gates --docs-only`                                             | Equivalent flag form for docs-only gates             |
+| `pnpm format`                                                        | Format all files (Prettier)                          |
+| `pnpm format:check`                                                  | Check formatting without changes                     |
+| `pnpm lint`                                                          | Run ESLint                                           |
+| `pnpm typecheck`                                                     | Run TypeScript type checking                         |
+| `pnpm test`                                                          | Run all tests (Vitest)                               |
+| `pnpm spec:linter`                                                   | Validate WU specs (all) ¹                            |
+| `pnpm lane:health`                                                   | Check lane config health                             |
+| `pnpm lane:suggest --output workspace.lanes.yaml`                    | Generate a workspace lane-definition snippet         |
+| `pnpm lane:status`                                                   | Show lane lifecycle status                           |
+| `pnpm lane:setup`                                                    | Create/update draft lane config                      |
+| `pnpm lane:validate`                                                 | Validate lane draft artifacts                        |
+| `pnpm lane:lock`                                                     | Lock lane lifecycle for WU create                    |
+| `pnpm lane:edit --name <L>`                                          | Edit lane definition (rename, wip-limit, paths)      |
+| `pnpm gate:co-change --add --name <N> --trigger <G> --require <G>`   | Add co-change gate rule                              |
+| `pnpm gate:co-change --remove --name <N>`                            | Remove co-change gate rule                           |
+| `pnpm gate:co-change --edit --name <N> --severity <S>`               | Edit co-change gate rule                             |
+| `pnpm gate:co-change --list`                                         | List all co-change rules (built-in + custom)         |
 | `pnpm gate:conditional --add --name <N> --trigger <G> --command <C>` | Add conditional command                              |
-| `pnpm gate:conditional --remove --name <N>`                         | Remove conditional command                           |
-| `pnpm gate:conditional --edit --name <N> --severity <S>`            | Edit conditional command                             |
-| `pnpm gate:conditional --list [--json]`                             | List conditional commands                            |
+| `pnpm gate:conditional --remove --name <N>`                          | Remove conditional command                           |
+| `pnpm gate:conditional --edit --name <N> --severity <S>`             | Edit conditional command                             |
+| `pnpm gate:conditional --list [--json]`                              | List conditional commands                            |
 
 ¹ **Script aliases:** `spec:linter` and `tasks:validate` are pnpm script aliases
 for `wu:validate --all`. They are not standalone CLI commands.
@@ -456,12 +459,12 @@ pnpm initiative:edit --id INIT-025 --phase-id 1 --phase-status in_progress
 
 ## Orchestration
 
-| Command                                      | Description                       |
-| -------------------------------------------- | --------------------------------- |
-| `pnpm orchestrate:initiative --id INIT-XXX`  | Orchestrate initiative execution  |
-| `pnpm orchestrate:init-status --id INIT-XXX` | Initiative status surface         |
+| Command                                      | Description                                    |
+| -------------------------------------------- | ---------------------------------------------- |
+| `pnpm orchestrate:initiative --id INIT-XXX`  | Orchestrate initiative execution               |
+| `pnpm orchestrate:init-status --id INIT-XXX` | Initiative status surface                      |
 | `pnpm orchestrate:monitor`                   | Monitor launches, stalls, and recovery signals |
-| `pnpm delegation:list`                       | List delegation / launch receipts |
+| `pnpm delegation:list`                       | List delegation / launch receipts              |
 
 Treat orchestration as a control plane: planning, handoff, execution, reconciliation, finish, and status are separate concerns. `mem:inbox` carries signal traffic only, and a worker reply is not WU completion; reconcile live truth against WU status, worktree / branch presence, gates, stamps, and integrity evidence. For the complete orchestration workflow (delegation, memory coordination, failure recovery, logical-wave vs launch-attempt semantics, and checkpoint-per-wave mechanics), see [initiative-orchestration.md](initiative-orchestration.md).
 

package/templates/core/ai/onboarding/release-process.md.template

@@ -33,8 +33,9 @@ pnpm release --release-version 1.3.0 --skip-publish
 3. Syncs templates with source docs (`pnpm lumenflow:sync-templates`)
 4. Bumps all `@lumenflow/*` package versions using micro-worktree isolation
 5. Builds all packages
-6. Creates and pushes git tag `vX.Y.Z`
-7. Optionally publishes to npm (unless `--skip-publish`)
+6. Validates packed artifacts against package contracts
+7. Creates and pushes git tag `vX.Y.Z`
+8. Optionally publishes to npm (unless `--skip-publish`)
 
 ### Options
 
@@ -42,7 +43,7 @@ pnpm release --release-version 1.3.0 --skip-publish
 | --------------------------- | --------------------------------------- |
 | `--release-version <X.Y.Z>` | **Required.** Semver version to release |
 | `--dry-run`                 | Preview changes without making them     |
-| `--skip-publish`            | Bump and tag only (no npm publish)      |
+| `--skip-publish`            | Skip npm publish only; validation still runs |
 | `--skip-build`              | Skip build step (use existing dist)     |
 | `--version`, `-V`           | Show CLI version                        |
 | `--help`, `-h`              | Show help                               |
@@ -50,10 +51,10 @@ pnpm release --release-version 1.3.0 --skip-publish
 ### Examples
 
 ```bash
-# Version bump and tag only (CI will publish)
+# Version bump and tag only (CI will publish after local validation passes)
 pnpm release --release-version 1.3.0 --skip-publish
 
-# Preview what would happen
+# Preview what would happen, including packed-artifact validation
 pnpm release --release-version 1.3.0 --skip-publish --dry-run
 ```
 
@@ -404,11 +405,11 @@ Use this as the standard workflow:
 # Preview first
 pnpm release --release-version 1.3.0 --skip-publish --dry-run
 
-# Execute (version bump + tag, publish delegated to GitHub Actions)
+# Execute (version bump + validation + tag, publish delegated to GitHub Actions)
 pnpm release --release-version 1.3.0 --skip-publish
 ```
 
-This handles version bump and tag locally; GitHub Actions handles npm publish, GitHub release creation, and the docs build/deploy path when the Vercel secrets are configured correctly.
+This handles version bump, packed-artifact validation, and tag creation locally; GitHub Actions handles npm publish, GitHub release creation, and the docs build/deploy path when the Vercel secrets are configured correctly.
 
 ### Release Steps (Manual)
 

package/templates/core/ai/onboarding/starting-prompt.md.template

@@ -19,6 +19,8 @@ pnpm lumenflow:commands    # List public CLI commands, aliases, and legacy surfa
 LumenFlow has commands for WU lifecycle, maintenance, memory, initiatives, orchestration, metrics, packs, and more. Never guess or assume — run `pnpm lumenflow:commands` first.
 Repo-only scripts such as `pnpm docs:validate` and `pnpm pre-release:check` are monorepo scripts,
 not part of that public command list.
+When the public CLI surface changes, update the canonical onboarding sources and rerun
+`pnpm docs:sync` so scaffold-like onboarding copies stay aligned.
 
 ### Help-First Rule
 

package/templates/core/ai/onboarding/troubleshooting-wu-done.md.template

@@ -127,6 +127,68 @@ pnpm wu:prep --id WU-XXX
 
 Feature WUs **must** include `spec_refs` (use `pnpm wu:create --plan` if the plan exists only in conversation).
 
+### Scoped Gate Parity Between `wu:prep` and `wu:done`
+
+When a WU declares `tests.unit`, both `wu:prep` and `wu:done` reuse that same scoped unit-test
+surface. A green `wu:prep` should not be followed by a broader repo-wide `wu:done` test rerun for
+the same unchanged worktree.
+
+- If `wu:done` fails outside that scope after a green `wu:prep`, treat it as real drift or a new
+  main-branch regression and investigate that root cause.
+- Use `--skip-gates` only when `wu:prep` already confirmed the failure is pre-existing on main and
+  you have a real `--fix-wu` recorded for the follow-up.
+- If you intentionally want broader coverage during prep, pass `pnpm wu:prep --id WU-XXX --full-tests`.
+
+### "Known bootstrap-trap detected"
+
+`wu:prep` now distinguishes ordinary gate failures from the two bootstrap traps that repeatedly
+showed up during the INIT-058 pack moves:
+
+- package export / cross-module resolution failures:
+  `ERR_PACKAGE_PATH_NOT_EXPORTED` or `Package subpath ... is not defined by "exports"`
+- dependency-cycle failures:
+  `Invalid package dependency graph`, `cyclic dependency`, or `turbo cycle`
+
+Use the surfaced remediation path:
+
+1. Inspect the message that `wu:prep` printed. It tells you which signature matched.
+2. Verify the worktree build with `pnpm build`.
+3. If `pnpm build` is green and `wu:prep` identified the package-export trap, use the surfaced
+   audited completion command from main:
+
+```bash
+cd /path/to/main && pnpm wu:done --id WU-XXX --skip-gates --reason "bootstrap-trap: pack file moves cause wu:prep cross-module resolution; worktree build green" --fix-wu WU-XXXX
+```
+
+4. Replace `WU-XXXX` with the follow-up WU that lands the export-surface fix.
+5. If `pnpm build` itself fails with a package-export or dependency-cycle signature, do **not**
+   skip gates. Fix the package surface or dependency graph first, then rerun `pnpm wu:prep --id WU-XXX`.
+
+### "Missing automated test diff evidence"
+
+`wu:prep` now reads the resolved
+`software_delivery.gates.tdd_diff_evidence` policy. It does **not** assume that
+every repository or every WU is governed by the same hardcoded TDD rule.
+
+Default behavior:
+
+- `software_delivery.methodology.testing: tdd` =>
+  `software_delivery.gates.tdd_diff_evidence.mode: block`
+- `software_delivery.methodology.testing: test-after` =>
+  `software_delivery.gates.tdd_diff_evidence.mode: off`
+- `software_delivery.methodology.testing: none` =>
+  `software_delivery.gates.tdd_diff_evidence.mode: off`
+- default `applies_to_types` => `feature`, `bug`
+- default `exempt_paths` => `[]`
+
+If `wu:prep` blocks on automated test diff evidence:
+
+1. Add or update the relevant automated test files in your branch, or
+2. Adjust workspace policy if the team wants different covered WU types or
+   path-based exemptions, or
+3. Use `tdd-exception: <reason>` in WU notes only when the WU is intentionally
+   exempt and policy does not already exclude it
+
 ---
 
 ### "non-fast-forward" or "branch is behind main"