@lumenflow/cli 3.20.0 → 3.22.0

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

@@ -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`                                                     |
@@ -178,27 +178,28 @@ 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.

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,7 +197,7 @@ 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.
@@ -459,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

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