@lumenflow/cli 3.19.0 → 3.21.0

package/templates/core/LUMENFLOW.md.template

@@ -258,7 +258,7 @@ For the full worktree lifecycle (parallel execution, bootstrap, isolation guaran
 ## Definition of Done
 
 - Acceptance criteria satisfied
-- Gates green (`pnpm gates` or `pnpm gates --docs-only`)
+- Gates green (`pnpm gates` or `pnpm gates:docs`; `pnpm gates --docs-only` is the equivalent flag form)
 - WU YAML status = `done`
 - `.lumenflow/stamps/WU-<id>.done` exists
 - **wu:done has been run** (not just documented as "to do")
@@ -269,31 +269,31 @@ For the full worktree lifecycle (parallel execution, bootstrap, isolation guaran
 
 > **Complete CLI reference (100+ commands):** See [quick-ref-commands.md]({{QUICK_REF_LINK}}). Always run `<command> --help` for the authoritative option list.
 
-| Command                   | Description                                                             |
-| ------------------------- | ----------------------------------------------------------------------- |
-| `pnpm wu:create`          | Create new WU spec                                                      |
-| `pnpm wu:claim`           | Claim WU, update canonical state, create worktree                       |
-| `pnpm wu:prep`            | Run gates in worktree, prep for wu:done                                 |
-| `pnpm wu:done`            | Complete WU (merge, stamp, cleanup)                                     |
-| `pnpm wu:status`          | Show WU status, location, and valid commands                            |
-| `pnpm wu:recover`         | Analyze and fix WU state inconsistencies                                |
-| `pnpm wu:block`           | Block WU (transitions to blocked, frees lane)                           |
-| `pnpm wu:unblock`         | Unblock WU (transitions to in_progress)                                 |
-| `pnpm wu:release`         | Release orphaned WU (in_progress to ready for reclaim)                  |
-| `pnpm wu:brief`           | **MANDATORY after wu:claim.** Generate handoff prompt + record evidence |
-| `pnpm wu:delegate`        | Generate prompt + record lineage + brief hash attestation               |
-| `pnpm wu:escalate`        | Show or resolve WU escalation status                                    |
-| `pnpm wu:verify`          | Verify WU completion (stamp, commit, clean tree)                        |
-| `pnpm wu:delete`          | Delete WU spec and cleanup                                              |
-| `pnpm gates`              | Run quality gates (`--docs-only` for docs WUs)                          |
-| `pnpm lumenflow:commands` | List all public commands (primary + alias + legacy)                     |
-| `pnpm docs:generate`      | Regenerate CLI/config reference docs from source                        |
-| `pnpm docs:validate`      | Verify generated docs are up-to-date                                    |
-| `pnpm lane:status`        | Show lane lifecycle status + next step                                  |
-| `pnpm lane:setup`         | Create/update draft lane artifacts                                      |
-| `pnpm lane:validate`      | Validate lane artifacts before lock                                     |
-| `pnpm lane:lock`          | Lock lane lifecycle for delivery WUs                                    |
-| `pnpm mem:checkpoint`     | Save memory checkpoint                                                  |
+| Command                   | Description                                                                     |
+| ------------------------- | ------------------------------------------------------------------------------- |
+| `pnpm wu:create`          | Create new WU spec                                                              |
+| `pnpm wu:claim`           | Claim WU, update canonical state, create worktree                               |
+| `pnpm wu:prep`            | Run gates in worktree, prep for wu:done                                         |
+| `pnpm wu:done`            | Complete WU (merge, stamp, cleanup)                                             |
+| `pnpm wu:status`          | Show WU status, location, and valid commands                                    |
+| `pnpm wu:recover`         | Analyze and fix WU state inconsistencies                                        |
+| `pnpm wu:block`           | Block WU (transitions to blocked, frees lane)                                   |
+| `pnpm wu:unblock`         | Unblock WU (transitions to in_progress)                                         |
+| `pnpm wu:release`         | Release orphaned WU (in_progress to ready for reclaim)                          |
+| `pnpm wu:brief`           | **MANDATORY after wu:claim.** Generate handoff prompt + record evidence         |
+| `pnpm wu:delegate`        | Generate prompt + record lineage + brief hash attestation                       |
+| `pnpm wu:escalate`        | Show or resolve WU escalation status                                            |
+| `pnpm wu:verify`          | Verify WU completion (stamp, commit, clean tree)                                |
+| `pnpm wu:delete`          | Delete WU spec and cleanup                                                      |
+| `pnpm gates`              | Run quality gates (`pnpm gates:docs` for docs WUs; `--docs-only` is equivalent) |
+| `pnpm lumenflow:commands` | List all public commands (primary + alias + legacy)                             |
+| `pnpm docs:generate`      | Regenerate CLI/config reference docs from source                                |
+| `pnpm docs:validate`      | Verify generated docs are up-to-date                                            |
+| `pnpm lane:status`        | Show lane lifecycle status + next step                                          |
+| `pnpm lane:setup`         | Create/update draft lane artifacts                                              |
+| `pnpm lane:validate`      | Validate lane artifacts before lock                                             |
+| `pnpm lane:lock`          | Lock lane lifecycle for delivery WUs                                            |
+| `pnpm mem:checkpoint`     | Save memory checkpoint                                                          |
 
 Commands include **context-aware validation** that checks location, WU status, and git state. When validation fails, commands provide copy-paste ready fix commands. Configure in `workspace.yaml` under `software_delivery.experimental.context_validation`.
 The Starlight CLI reference page is intentionally curated to primary commands; use `pnpm lumenflow:commands` for complete discovery.

package/templates/core/_frameworks/lumenflow/wu-sizing-guide.md.template

@@ -102,7 +102,7 @@ Documentation WUs (`type: documentation`) have relaxed file count thresholds bec
 id: WU-XXX
 type: documentation
 code_paths:
-  - docs/operations/_frameworks/lumenflow/*.md
+  - {{DOCS_OPERATIONS_PATH}}/_frameworks/lumenflow/*.md
   - docs/01-product/*.md
 ```
 
@@ -320,7 +320,7 @@ The tooling operates in two modes:
 ```
 [wu:create] WARNING (WU-100): sizing: estimated_files (30) exceeds Simple
 threshold (20). Consider adding exception_type/exception_reason or splitting
-the WU. See docs/operations/_frameworks/lumenflow/wu-sizing-guide.md.
+the WU. See {{DOCS_OPERATIONS_PATH}}/_frameworks/lumenflow/wu-sizing-guide.md.
 ```
 
 **Strict mode (`--strict-sizing`):** `wu:brief` supports a `--strict-sizing` flag that blocks when:
@@ -491,7 +491,7 @@ Only use these patterns after you have confirmed the work is no longer one coher
 
 **Heading:** Default Triggers (Deviations require written justification in WU notes)
 
-If you hit ANY of these triggers during a session, you MUST perform a Standard Session Handoff (see [session-handoff.md](./agent/onboarding/session-handoff.md)):
+If you hit ANY of these triggers during a session, you MUST perform a Standard Session Handoff:
 
 - **Token Limit:** Context usage hits **50% (Warning)** or **80% (Critical)**.
 - **Tool Volume:** **50+ tool calls** in current session.
@@ -619,9 +619,7 @@ This is a case study in genuinely non-atomic work. Do not generalize it into "mu
 
 ## 8. Related Documentation
 
-- [session-handoff.md](./agent/onboarding/session-handoff.md) — Mid-WU checkpoint protocol
 - [agent-safety-card.md](./agent/onboarding/agent-safety-card.md) — Quick reference safety thresholds
-- [parallel-session-optimization.md](./agent/onboarding/parallel-session-optimization.md) — Running 4-6 WUs concurrently
 - [agent-invocation-guide.md](./agent/onboarding/agent-invocation-guide.md) — Orchestrator-worker patterns
 - [LumenFlow Agent Capsule](./lumenflow-agent-capsule.md) — Full LumenFlow framework
 - [Canonical Lifecycle Map](./lumenflow-agent-capsule.md) — Command-mode matrix and handoff points

package/templates/core/ai/onboarding/agent-safety-card.md.template

@@ -35,6 +35,8 @@ Quick reference for AI agents working in LumenFlow projects.
 
 | Action                               | Why                               |
 | ------------------------------------ | --------------------------------- |
+| Run `--help` before first use        | Prevents retry cascades           |
+| Check lanes before `wu:create`       | Lane names are project-specific   |
 | Read WU spec first                   | Understand scope                  |
 | cd to worktree after claim           | Isolation                         |
 | Write tests before code              | TDD                               |
@@ -75,13 +77,21 @@ Audit logs:
 
 ## Error Handling
 
-### Max 3 Attempts
+### Max 3 Attempts (Constraint 10 — Non-Negotiable)
 
-If same error happens 3 times:
+If the same operation fails 3 times: **STOP. Do not retry.**
+
+Retry loops create cascading mess (orphaned commits, diverged branches, locked lanes)
+that the user must clean up manually.
 
 1. Stop trying
-2. Document what happened
-3. Ask for help
+2. Summarise all 3 attempts and their errors
+3. Present your diagnosis and options to the user
+4. Wait for direction
+
+**What counts as "same operation":** Retrying `wu:create` with slightly different flags
+after each validation error is one operation failing multiple times. The fix is `--help`,
+not guess-and-retry.
 
 ### Gate Failures
 

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

@@ -344,6 +344,102 @@ See the [WU Sizing Guide](../../wu-sizing-guide.md) section 1.5 for the full con
 
 ---
 
+## Mistake 14: Not Running --help Before First Use
+
+### Wrong
+
+```bash
+# Agent guesses wu:create flags, misses required ones
+pnpm wu:create --lane "Portal: UI" --title "Add feature" --description "..."
+# Error: Unknown parent lane "Portal"
+
+pnpm wu:create --lane "Experience: Auth" --title "Add feature" --description "..."
+# Error: --test-paths-manual is required
+
+pnpm wu:create --lane "Experience: Auth" --title "Add feature" --description "..." --test-paths-manual "..."
+# Error: --spec-refs is required for type: feature
+
+pnpm wu:create --lane "Experience: Auth" --title "Add feature" --description "..." --test-paths-manual "..." --spec-refs "..."
+# Error: plan already exists
+
+# Six attempts later, agent has burned context and user patience
+```
+
+### Right
+
+```bash
+# Run --help ONCE before first use
+pnpm wu:create --help
+# Now you know every required flag, valid lane format, and option
+
+# First attempt succeeds
+pnpm wu:create --lane "Experience: Auth" --title "Add feature" \
+  --description "..." --acceptance "..." \
+  --code-paths "src/..." --test-paths-unit "src/..." \
+  --test-paths-manual "..." --spec-refs "..." --exposure ui
+```
+
+**Rule:** `--help` before first use is mandatory (see AGENTS.md rule #2). One `--help` call prevents an entire retry cascade. If you still fail after reading `--help`, that's a real problem worth escalating — not a reason to guess again.
+
+---
+
+## Mistake 15: Guessing Lane Names
+
+### Wrong
+
+```bash
+# Agent invents a lane name that doesn't exist
+pnpm wu:create --lane "Portal: UI" --title "..."
+# Error: Unknown parent lane: "Portal"
+```
+
+### Right
+
+```bash
+# Check what lanes exist first
+pnpm lane:status
+
+# Or infer the right lane from file paths
+pnpm wu:infer-lane --paths "src/app/clients/[slug]/client-portal.tsx" \
+  --desc "Add light mode to client portal"
+
+# Then use the suggested lane
+pnpm wu:create --lane "Experience: Auth" --title "..."
+```
+
+**Rule:** Lane names are project-specific and defined in `workspace.yaml`. Never guess them. Run `pnpm lane:status` or `pnpm wu:infer-lane` to discover valid lanes before creating a WU.
+
+---
+
+## Mistake 16: Retry Loops Instead of Escalating
+
+### Wrong
+
+```
+Attempt 1: wu:create fails (wrong lane) → try different lane
+Attempt 2: wu:create fails (missing field) → add field
+Attempt 3: wu:create fails (missing another field) → add field
+Attempt 4: wu:create fails (stale plan) → delete plan, retry
+Attempt 5: wu:create fails (inode exhaustion) → try to diagnose
+Attempt 6: wu:create fails (inode exhaustion) → ask user to clean up
+# Agent has burned 20 minutes on what should have been a 30-second operation
+```
+
+### Right
+
+```
+Attempt 1: wu:create fails → read the error carefully
+Attempt 2: wu:create fails → try the fix the error suggested
+Attempt 3: wu:create fails → STOP. Escalate to user:
+
+"wu:create has failed 3 times. Errors were: [X], [Y], [Z].
+Root cause appears to be [diagnosis]. Would you like me to [option]?"
+```
+
+**Rule:** See [Constraint 10](../../../../../.lumenflow/constraints.md) — stop and escalate after 3 failures. Retry loops create cascading mess (orphaned commits, diverged branches, locked lanes) that the user then has to clean up manually.
+
+---
+
 ## Quick Checklist
 
 Before starting any WU:

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

@@ -36,7 +36,7 @@ Run `--help` first, then run the real command with explicit flags.
 | Tooling Operations  | `pnpm lumenflow:upgrade --help`       | `pnpm lumenflow:upgrade --latest`                                        |
 | WU Lifecycle        | `pnpm wu:claim --help`                | `pnpm wu:claim --id WU-1561 --lane "Operations: Tooling"`                |
 | WU Maintenance      | `pnpm wu:recover --help`              | `pnpm wu:recover --id WU-1561`                                           |
-| Gates & Quality     | `pnpm gates --help`                   | `pnpm gates --docs-only`                                                 |
+| Gates & Quality     | `pnpm gates --help`                   | `pnpm gates:docs`                                                        |
 | Memory & Sessions   | `pnpm mem:checkpoint --help`          | `pnpm mem:checkpoint --wu WU-1561`                                       |
 | State Management    | `pnpm state:doctor --help`            | `pnpm state:doctor --json`                                               |
 | Repo-Only Scripts   | `pnpm docs:validate --help`           | `pnpm docs:validate`                                                     |
@@ -143,9 +143,9 @@ you want to refresh docs without upgrading packages (e.g., after manually editin
 | `pnpm approval:request --type <type> --subject <json>`         | Request control-plane approval for an action                                                                   |
 | `pnpm approval:review --id <approvalId> --decision <decision>` | Resolve an approval decision (`approved`/`rejected`/`expired`)                                                 |
 | `pnpm approval:list [--status <status>]`                       | List approvals with optional status/type filters                                                               |
-| `pnpm wu:block --id WU-XXX --reason "..."`                     | Block WU with reason                                                                                           |
-| `pnpm wu:unblock --id WU-XXX`                                  | Unblock WU                                                                                                     |
-| `pnpm wu:release --id WU-XXX`                                  | Release orphaned WU (in_progress to ready)                                                                     |
+| `pnpm wu:block --id WU-XXX --reason "..."`                     | Block WU with reason (ownership-guarded, v3.19.0)                                                              |
+| `pnpm wu:unblock --id WU-XXX`                                  | Unblock WU (ownership-guarded, v3.19.0)                                                                        |
+| `pnpm wu:release --id WU-XXX --reason "..."`                   | Release orphaned WU (ownership-guarded, v3.19.0)                                                               |
 | `pnpm wu:status --id WU-XXX`                                   | Show WU status, location, valid commands                                                                       |
 | `pnpm wu:brief --id WU-XXX --client <client>`                  | **MANDATORY after wu:claim.** Generate handoff prompt + record evidence. wu:done blocks without this (WU-2379) |
 | `pnpm wu:brief --id WU-XXX --no-context`                       | Generate prompt without memory context injection                                                               |
@@ -154,50 +154,61 @@ you want to refresh docs without upgrading packages (e.g., after manually editin
 
 ### WU Maintenance
 
-| Command                          | Description                                      |
-| -------------------------------- | ------------------------------------------------ |
-| `pnpm wu:validate --id WU-XXX`   | Validate WU spec                                 |
-| `pnpm wu:preflight --id WU-XXX`  | Pre-flight checks before wu:done                 |
-| `pnpm wu:verify --id WU-XXX`     | Verify WU completion (stamp, commit, clean tree) |
-| `pnpm wu:recover --id WU-XXX`    | Analyze and fix WU state inconsistencies         |
-| `pnpm wu:repair --id WU-XXX`     | Repair WU state issues                           |
-| `pnpm wu:prune`                  | Clean stale worktrees                            |
-| `pnpm wu:cleanup --id WU-XXX`    | Cleanup after PR merge (PR-only)                 |
-| `pnpm wu:deps --id WU-XXX`       | Show WU dependencies                             |
-| `pnpm wu:infer-lane --id WU-XXX` | Infer lane from code paths/description           |
-| `pnpm wu:delete --id WU-XXX`     | Delete WU spec and cleanup                       |
-| `pnpm wu:unlock-lane --lane <L>` | Unlock stuck lane                                |
-| `pnpm wu:proto --lane <Lane>`    | Create WU prototype (lightweight draft)          |
+| Command                          | Description                                           |
+| -------------------------------- | ----------------------------------------------------- |
+| `pnpm wu:validate --id WU-XXX`   | Validate WU spec                                      |
+| `pnpm wu:preflight --id WU-XXX`  | Pre-flight checks before wu:done                      |
+| `pnpm wu:verify --id WU-XXX`     | Verify WU completion (stamp, commit, clean tree)      |
+| `pnpm wu:recover --id WU-XXX`    | Analyze and fix WU state (ownership-guarded, v3.19.0) |
+| `pnpm wu:repair --id WU-XXX`     | Repair WU state issues                                |
+| `pnpm wu:prune`                  | Clean stale worktrees                                 |
+| `pnpm wu:cleanup --id WU-XXX`    | Cleanup after PR merge (PR-only)                      |
+| `pnpm wu:deps --id WU-XXX`       | Show WU dependencies                                  |
+| `pnpm wu:infer-lane --id WU-XXX` | Infer lane from code paths/description                |
+| `pnpm wu:delete --id WU-XXX`     | Delete WU spec and cleanup                            |
+| `pnpm wu:unlock-lane --lane <L>` | Unlock stuck lane                                     |
+| `pnpm wu:proto --lane <Lane>`    | Create WU prototype (lightweight draft)               |
+
+**Ownership guards (v3.19.0, WU-2468):** `wu:block`, `wu:unblock`, `wu:release`, and `wu:recover`
+validate session ownership before state mutations. If the WU belongs to another session, use
+`--override-owner --reason "..."` to override (audited). **AGENTS: NEVER use --override-owner
+without explicit human instruction.**
 
 ---
 
 ## Gates & Quality
 
-| Command                                                            | Description                                     |
-| ------------------------------------------------------------------ | ----------------------------------------------- |
-| `pnpm gates`                                                       | Run all quality gates                           |
-| `pnpm gates --docs-only`                                           | Run gates for docs changes                      |
-| `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)         |
 
 ¹ **Script aliases:** `spec:linter` and `tasks:validate` are pnpm script aliases
 for `wu:validate --all`. They are not standalone CLI commands.
 
+**Conditional gates (v3.19.0, WU-2448):** Define pattern-triggered commands in
+`workspace.yaml > software_delivery.gates.conditional_commands`. Commands with `trigger_patterns`
+only run when matching files change. Supports `error` (blocks), `warn` (logs), and `off` (skip)
+severity levels. See workspace-spec.mdx for schema.
+
 **Formatting: always scope to changed files only.**
 Use `pnpm prettier --write <changed-files...>` — never unscoped `pnpm format`.
 Running `pnpm format` reformats every file in the repo, creating hundreds of

package/templates/core/ai/onboarding/rapid-prototyping.md

@@ -73,7 +73,8 @@ For documentation changes, use the fast path:
 
 ```bash
 # Skip lint/typecheck/tests for docs
-pnpm gates --docs-only
+pnpm gates:docs
+# Equivalent flag form: pnpm gates --docs-only
 ```
 
 ---

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

@@ -197,12 +197,13 @@ LUMENFLOW_CLOUD=1 pnpm wu:claim --id WU-XXXX --lane "Lane Name"
 These are the mistakes agents make most often. Memorize these before reading anything else:
 
 1. **wu:done deletes the worktree.** After it completes, your shell CWD is invalid. Immediately `cd` back to the project root.
-2. **When wu:done fails with a non-fast-forward error, just rerun it.** It has built-in auto-rebase. Never manually `git rebase` on main.
+2. **When wu:done reports branch drift or a non-fast-forward error, rerun it from main.** It auto-rebases by default when it can. Never manually `git rebase` on main.
 3. **Always run `--help` before first use of any command.** Don't guess flags — 30 seconds reading help saves 5 minutes of failed attempts.
 4. **Never `pnpm update @lumenflow/*` directly.** Use `pnpm lumenflow:upgrade --latest` (uses micro-worktree isolation).
 5. **State files are auto-generated.** Never manually edit `wu-events.jsonl`, `backlog.md`, or `status.md` — lifecycle commands manage them.
 6. **wu:edit requires a clean worktree.** Commit `wu-events.jsonl` and other changes before running `wu:edit`.
 7. **Don't edit on main then stash to a worktree.** If a hook blocks you on main, that means you need a WU. Create one and work in the worktree from the start.
+8. **Don't modify another agent's WU to free a lane.** `wu:block`, `wu:unblock`, `wu:release`, and `wu:recover` enforce ownership guards (v3.19.0). If you hit a `SESSION OWNERSHIP VIOLATION`, wait for the owning WU to complete or block itself — never use `--override-owner` without explicit human instruction.
 
 ---
 
@@ -458,11 +459,11 @@ cd <project-root> && pnpm wu:done --id WU-XXX --skip-gates \
 
 Do not use `git stash`, switch local main, or otherwise mutate main just to prove a pre-existing failure.
 
-### Scenario 6: wu:done fails with non-fast-forward error
+### Scenario 6: wu:done reports branch drift or a non-fast-forward error
 
 **Cause:** Another agent or process pushed to main between your fetch and push (race condition).
 
-**Fix:** Just rerun `wu:done`. It has built-in auto-rebase that handles this cleanly.
+**Fix:** Rerun `wu:done` from main. It has built-in auto-rebase for this case. If the rerun still fails with a real conflict, resolve the conflict in the worktree, rerun `wu:prep` if needed, then return to main and rerun `wu:done`.
 
 ```bash
 # WRONG - never manually rebase main
@@ -527,7 +528,7 @@ Default profiles:
 
 - Behavior/logic changes: follow project policy (`methodology.testing`: `tdd`, `test-after`, or `none`).
 - Structured-content-only changes (`.yaml/.yml/.json/.md/.mdx`): use parse/schema/lint/eval evidence; TDD checkpoint is omitted.
-- UI presentation hints: prefer smoke/manual/integration/E2E verification and use unit tests for pure logic or explicitly required checks.
+- UI presentation hints: prefer smoke/manual/integration/E2E verification, never assert inline styles, CSS values, exact copy, or DOM shape, and use unit tests only for pure logic or explicitly required checks.
 
 Common override points include `visual-directive`, `structured-content-directive`,
 `verification-requirements`, and `design-context-ui`.

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

@@ -65,6 +65,9 @@ cd /path/to/main && pnpm wu:done --id WU-XXX
 # 3. Report success with the wu:done output
 ```
 
+If `wu:done` reports branch drift, parallel completions, or a non-fast-forward push, rerun it from
+main. It auto-rebases by default when possible. Do not manually rebase `main`.
+
 ---
 
 ## What wu:prep Does (WU-1223)
@@ -80,7 +83,7 @@ When you run `pnpm wu:prep --id WU-XXX` from a worktree:
 When you run `pnpm wu:done --id WU-XXX` from main:
 
 1. Validates you're in main checkout (errors if in worktree)
-2. Fast-forward merges the lane branch to main
+2. Merges the lane branch to main and may auto-rebase first if parallel work landed
 3. Creates the done stamp
 4. Updates status and backlog docs
 5. Removes the worktree
@@ -125,6 +128,71 @@ Feature WUs **must** include `spec_refs` (use `pnpm wu:create --plan` if the pla
 
 ---
 
+### "non-fast-forward" or "branch is behind main"
+
+If `wu:done` reports branch drift or a non-fast-forward push, another completion landed while your
+WU was in progress.
+
+```bash
+# Retry from main first
+cd /path/to/main
+pnpm wu:done --id WU-XXX
+```
+
+- If the rerun succeeds, you are done.
+- If the rerun reports an auto-rebase conflict, return to the worktree, resolve the conflict there,
+  rerun `pnpm wu:prep --id WU-XXX` if needed, then retry `wu:done` from main.
+- Do **not** manually `git rebase` the main checkout.
+
+---
+
+## wu:create Failure Recovery
+
+`wu:create` uses a micro-worktree to commit the spec atomically. If it fails mid-transaction
+(rebase conflict, disk full, inode exhaustion, network error), it can leave main in an
+inconsistent state.
+
+### Symptoms
+
+- `git log` shows main is ahead of `origin/main` by 1 commit (the orphaned spec commit)
+- `wu:delete` fails because main can't fast-forward
+- Subsequent `wu:create` or `wu:claim` operations fail
+
+### Recovery
+
+**Step 1: Check the divergence**
+
+```bash
+git log --oneline origin/main..main
+# If you see a single spec commit like "docs: create wu-XXX for ...", that's the orphan
+```
+
+**Step 2: Ask the user to discard the orphaned commit**
+
+Agents cannot run `git reset --hard` (forbidden command). Present this to the user:
+
+```
+wu:create failed mid-transaction and left an orphaned spec commit on main.
+Main is now 1 ahead of origin/main. The safe fix is:
+
+  git fetch origin && git reset --hard origin/main
+
+This discards only the failed spec commit. No other work is lost.
+Shall I proceed after you run this?
+```
+
+**Step 3: After user resets main, retry wu:create**
+
+Do NOT attempt to recover by rebasing, cherry-picking, or manually editing state files.
+The clean path is: discard the orphan, retry the command.
+
+### Prevention
+
+- Run `wu:create --help` before first use to avoid validation failures that trigger retries
+- If `wu:create` fails, check `git log --oneline -3` before retrying — if the spec commit
+  landed locally but wasn't pushed, you already have an orphan
+- After 3 failed attempts, stop and escalate (Constraint 10)
+
 ---
 
 ## Cloud / Branch-PR Mode