@lumenflow/cli 3.18.0 → 3.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/cli",
-  "version": "3.18.0",
+  "version": "3.19.0",
   "description": "Command-line interface for LumenFlow workflow framework",
   "keywords": [
     "lumenflow",
@@ -31,127 +31,128 @@
     }
   },
   "bin": {
-    "wu-claim": "./dist/wu-claim.js",
-    "wu-sandbox": "./dist/wu-sandbox.js",
-    "wu-done": "./dist/wu-done.js",
-    "wu-prep": "./dist/wu-prep.js",
-    "wu-block": "./dist/wu-block.js",
-    "wu-unblock": "./dist/wu-unblock.js",
-    "wu-create": "./dist/wu-create.js",
-    "wu-proto": "./dist/wu-proto.js",
-    "wu-edit": "./dist/wu-edit.js",
-    "wu-escalate": "./dist/wu-escalate.js",
-    "approval-request": "./dist/approval-request.js",
-    "approval-review": "./dist/approval-review.js",
-    "approval-list": "./dist/approval-list.js",
-    "wu-brief": "./dist/wu-brief.js",
-    "wu-delegate": "./dist/wu-delegate.js",
-    "wu-validate": "./dist/wu-validate.js",
-    "wu-preflight": "./dist/wu-preflight.js",
-    "wu-repair": "./dist/wu-repair.js",
-    "wu-prune": "./dist/wu-prune.js",
-    "wu-cleanup": "./dist/wu-cleanup.js",
-    "wu-deps": "./dist/wu-deps.js",
-    "wu-infer-lane": "./dist/wu-infer-lane.js",
-    "wu-delete": "./dist/wu-delete.js",
-    "wu-unlock-lane": "./dist/wu-unlock-lane.js",
-    "wu-release": "./dist/wu-release.js",
-    "wu-status": "./dist/wu-status.js",
-    "task-claim": "./dist/task-claim.js",
-    "wu-recover": "./dist/wu-recover.js",
-    "wu-verify": "./dist/wu-verify.js",
-    "mem-init": "./dist/mem-init.js",
-    "mem-checkpoint": "./dist/mem-checkpoint.js",
-    "mem-start": "./dist/mem-start.js",
-    "mem-ready": "./dist/mem-ready.js",
-    "mem-export": "./dist/mem-export.js",
-    "mem-signal": "./dist/mem-signal.js",
-    "mem-cleanup": "./dist/mem-cleanup.js",
-    "mem-context": "./dist/mem-context.js",
-    "signal-cleanup": "./dist/signal-cleanup.js",
-    "mem-create": "./dist/mem-create.js",
-    "mem-inbox": "./dist/mem-inbox.js",
-    "mem-summarize": "./dist/mem-summarize.js",
-    "mem-triage": "./dist/mem-triage.js",
-    "mem-delete": "./dist/mem-delete.js",
-    "mem-recover": "./dist/mem-recover.js",
-    "initiative-create": "./dist/initiative-create.js",
-    "initiative-edit": "./dist/initiative-edit.js",
-    "initiative-list": "./dist/initiative-list.js",
-    "initiative-status": "./dist/initiative-status.js",
-    "initiative-add-wu": "./dist/initiative-add-wu.js",
-    "initiative-remove-wu": "./dist/initiative-remove-wu.js",
-    "initiative-plan": "./dist/initiative-plan.js",
-    "init-plan": "./dist/initiative-plan.js",
-    "plan-create": "./dist/plan-create.js",
-    "plan-link": "./dist/plan-link.js",
-    "plan-edit": "./dist/plan-edit.js",
-    "plan-promote": "./dist/plan-promote.js",
+    "agent-issues-query": "./dist/agent-issues-query.js",
+    "agent-log-issue": "./dist/agent-log-issue.js",
     "agent-session": "./dist/agent-session.js",
     "agent-session-end": "./dist/agent-session-end.js",
-    "agent-log-issue": "./dist/agent-log-issue.js",
-    "orchestrate-initiative": "./dist/orchestrate-initiative.js",
-    "orchestrate-init-status": "./dist/orchestrate-init-status.js",
-    "orchestrate-monitor": "./dist/orchestrate-monitor.js",
-    "delegation-list": "./dist/delegation-list.js",
-    "flow-report": "./dist/flow-report.js",
-    "flow-bottlenecks": "./dist/flow-bottlenecks.js",
-    "metrics-snapshot": "./dist/metrics-snapshot.js",
-    "cost-summary": "./dist/cost-summary.js",
-    "metrics": "./dist/metrics-cli.js",
-    "lumenflow-metrics": "./dist/metrics-cli.js",
-    "initiative-bulk-assign-wus": "./dist/initiative-bulk-assign-wus.js",
-    "agent-issues-query": "./dist/agent-issues-query.js",
-    "gates": "./dist/gates.js",
-    "lumenflow-gates": "./dist/gates.js",
-    "lumenflow-init": "./dist/init.js",
-    "lumenflow": "./dist/init.js",
-    "lumenflow-doctor": "./dist/doctor.js",
-    "lumenflow-commands": "./dist/commands.js",
-    "lumenflow-release": "./dist/release.js",
-    "lumenflow-docs-sync": "./dist/docs-sync.js",
-    "lumenflow-sync-templates": "./dist/sync-templates.js",
-    "sync-templates": "./dist/sync-templates.js",
-    "templates-sync": "./dist/sync-templates.js",
+    "approval-list": "./dist/approval-list.js",
+    "approval-request": "./dist/approval-request.js",
+    "approval-review": "./dist/approval-review.js",
     "backlog-prune": "./dist/backlog-prune.js",
+    "cloud-connect": "./dist/init.js",
+    "config-get": "./dist/config-get.js",
+    "config-set": "./dist/config-set.js",
+    "cost-summary": "./dist/cost-summary.js",
+    "delegation-list": "./dist/delegation-list.js",
+    "file-delete": "./dist/file-delete.js",
+    "file-edit": "./dist/file-edit.js",
     "file-read": "./dist/file-read.js",
     "file-write": "./dist/file-write.js",
-    "file-edit": "./dist/file-edit.js",
-    "file-delete": "./dist/file-delete.js",
-    "validate": "./dist/validate.js",
-    "lumenflow-validate": "./dist/validate.js",
-    "lumenflow-upgrade": "./dist/lumenflow-upgrade.js",
-    "lumenflow-pre-commit-check": "./dist/pre-commit-check.js",
-    "git-status": "./dist/git-status.js",
+    "flow-bottlenecks": "./dist/flow-bottlenecks.js",
+    "flow-report": "./dist/flow-report.js",
+    "gate-co-change": "./dist/gate-co-change.js",
+    "gates": "./dist/gates.js",
+    "git-branch": "./dist/git-branch.js",
     "git-diff": "./dist/git-diff.js",
     "git-log": "./dist/git-log.js",
-    "git-branch": "./dist/git-branch.js",
-    "state-bootstrap": "./dist/state-bootstrap.js",
+    "git-status": "./dist/git-status.js",
+    "init-plan": "./dist/initiative-plan.js",
+    "initiative-add-wu": "./dist/initiative-add-wu.js",
+    "initiative-bulk-assign-wus": "./dist/initiative-bulk-assign-wus.js",
+    "initiative-create": "./dist/initiative-create.js",
+    "initiative-edit": "./dist/initiative-edit.js",
+    "initiative-list": "./dist/initiative-list.js",
+    "initiative-plan": "./dist/initiative-plan.js",
+    "initiative-remove-wu": "./dist/initiative-remove-wu.js",
+    "initiative-status": "./dist/initiative-status.js",
     "lane-create": "./dist/lane-create.js",
     "lane-edit": "./dist/lane-edit.js",
     "lane-health": "./dist/lane-health.js",
-    "lane-suggest": "./dist/lane-suggest.js",
-    "lane-status": "./dist/lane-status.js",
+    "lane-lock": "./dist/lane-lock.js",
     "lane-setup": "./dist/lane-setup.js",
+    "lane-status": "./dist/lane-status.js",
+    "lane-suggest": "./dist/lane-suggest.js",
     "lane-validate": "./dist/lane-validate.js",
-    "lane-lock": "./dist/lane-lock.js",
-    "state-cleanup": "./dist/state-cleanup.js",
-    "state-doctor": "./dist/state-doctor.js",
-    "state-emit": "./dist/state-emit.js",
+    "lumenflow": "./dist/init.js",
+    "lumenflow-commands": "./dist/commands.js",
+    "lumenflow-docs-sync": "./dist/docs-sync.js",
+    "lumenflow-doctor": "./dist/doctor.js",
+    "lumenflow-gates": "./dist/gates.js",
+    "lumenflow-init": "./dist/init.js",
     "lumenflow-integrate": "./dist/commands/integrate.js",
+    "lumenflow-metrics": "./dist/metrics-cli.js",
+    "lumenflow-onboard": "./dist/onboard.js",
+    "lumenflow-pre-commit-check": "./dist/pre-commit-check.js",
+    "lumenflow-release": "./dist/release.js",
+    "lumenflow-sync-templates": "./dist/sync-templates.js",
+    "lumenflow-upgrade": "./dist/lumenflow-upgrade.js",
+    "lumenflow-validate": "./dist/validate.js",
+    "mem-checkpoint": "./dist/mem-checkpoint.js",
+    "mem-cleanup": "./dist/mem-cleanup.js",
+    "mem-context": "./dist/mem-context.js",
+    "mem-create": "./dist/mem-create.js",
+    "mem-delete": "./dist/mem-delete.js",
+    "mem-export": "./dist/mem-export.js",
+    "mem-inbox": "./dist/mem-inbox.js",
+    "mem-init": "./dist/mem-init.js",
+    "mem-ready": "./dist/mem-ready.js",
+    "mem-recover": "./dist/mem-recover.js",
+    "mem-signal": "./dist/mem-signal.js",
+    "mem-start": "./dist/mem-start.js",
+    "mem-summarize": "./dist/mem-summarize.js",
+    "mem-triage": "./dist/mem-triage.js",
+    "metrics": "./dist/metrics-cli.js",
+    "metrics-snapshot": "./dist/metrics-snapshot.js",
+    "onboard": "./dist/onboard.js",
+    "orchestrate-init-status": "./dist/orchestrate-init-status.js",
+    "orchestrate-initiative": "./dist/orchestrate-initiative.js",
+    "orchestrate-monitor": "./dist/orchestrate-monitor.js",
     "pack-author": "./dist/pack-author.js",
-    "pack-scaffold": "./dist/pack-scaffold.js",
-    "pack-validate": "./dist/pack-validate.js",
     "pack-hash": "./dist/pack-hash.js",
     "pack-install": "./dist/pack-install.js",
     "pack-publish": "./dist/pack-publish.js",
+    "pack-scaffold": "./dist/pack-scaffold.js",
     "pack-search": "./dist/pack-search.js",
+    "pack-validate": "./dist/pack-validate.js",
+    "plan-create": "./dist/plan-create.js",
+    "plan-edit": "./dist/plan-edit.js",
+    "plan-link": "./dist/plan-link.js",
+    "plan-promote": "./dist/plan-promote.js",
+    "signal-cleanup": "./dist/signal-cleanup.js",
+    "state-bootstrap": "./dist/state-bootstrap.js",
+    "state-cleanup": "./dist/state-cleanup.js",
+    "state-doctor": "./dist/state-doctor.js",
+    "state-emit": "./dist/state-emit.js",
+    "sync-templates": "./dist/sync-templates.js",
+    "task-claim": "./dist/task-claim.js",
+    "templates-sync": "./dist/sync-templates.js",
+    "validate": "./dist/validate.js",
     "workspace-init": "./dist/workspace-init.js",
-    "config-set": "./dist/config-set.js",
-    "config-get": "./dist/config-get.js",
-    "cloud-connect": "./dist/init.js",
-    "lumenflow-onboard": "./dist/onboard.js",
-    "onboard": "./dist/onboard.js"
+    "wu-block": "./dist/wu-block.js",
+    "wu-brief": "./dist/wu-brief.js",
+    "wu-claim": "./dist/wu-claim.js",
+    "wu-cleanup": "./dist/wu-cleanup.js",
+    "wu-create": "./dist/wu-create.js",
+    "wu-delegate": "./dist/wu-delegate.js",
+    "wu-delete": "./dist/wu-delete.js",
+    "wu-deps": "./dist/wu-deps.js",
+    "wu-done": "./dist/wu-done.js",
+    "wu-edit": "./dist/wu-edit.js",
+    "wu-escalate": "./dist/wu-escalate.js",
+    "wu-infer-lane": "./dist/wu-infer-lane.js",
+    "wu-preflight": "./dist/wu-preflight.js",
+    "wu-prep": "./dist/wu-prep.js",
+    "wu-proto": "./dist/wu-proto.js",
+    "wu-prune": "./dist/wu-prune.js",
+    "wu-recover": "./dist/wu-recover.js",
+    "wu-release": "./dist/wu-release.js",
+    "wu-repair": "./dist/wu-repair.js",
+    "wu-sandbox": "./dist/wu-sandbox.js",
+    "wu-status": "./dist/wu-status.js",
+    "wu-unblock": "./dist/wu-unblock.js",
+    "wu-unlock-lane": "./dist/wu-unlock-lane.js",
+    "wu-validate": "./dist/wu-validate.js",
+    "wu-verify": "./dist/wu-verify.js"
   },
   "files": [
     "dist",
@@ -185,13 +186,13 @@
     "xstate": "^5.28.0",
     "yaml": "^2.8.2",
     "zod": "^4.3.6",
-    "@lumenflow/agent": "3.18.0",
-    "@lumenflow/initiatives": "3.18.0",
-    "@lumenflow/core": "3.18.0",
-    "@lumenflow/kernel": "3.18.0",
-    "@lumenflow/control-plane-sdk": "3.18.0",
-    "@lumenflow/memory": "3.18.0",
-    "@lumenflow/metrics": "3.18.0"
+    "@lumenflow/agent": "3.19.0",
+    "@lumenflow/control-plane-sdk": "3.19.0",
+    "@lumenflow/core": "3.19.0",
+    "@lumenflow/initiatives": "3.19.0",
+    "@lumenflow/metrics": "3.19.0",
+    "@lumenflow/memory": "3.19.0",
+    "@lumenflow/kernel": "3.19.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.18",

package/packs/agent-runtime/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @lumenflow/packs-agent-runtime@3.18.0 build /home/runner/work/lumenflow-dev/lumenflow-dev/packages/@lumenflow/packs/agent-runtime
+> @lumenflow/packs-agent-runtime@3.19.0 build /home/runner/work/lumenflow-dev/lumenflow-dev/packages/@lumenflow/packs/agent-runtime
 > tsc
 

package/packs/agent-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/packs-agent-runtime",
-  "version": "3.18.0",
+  "version": "3.19.0",
   "description": "Agent runtime pack scaffold for LumenFlow — governed model-turn execution, pack config, and provider capability baselines",
   "keywords": [
     "lumenflow",

package/packs/sidekick/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @lumenflow/packs-sidekick@3.18.0 build /home/runner/work/lumenflow-dev/lumenflow-dev/packages/@lumenflow/packs/sidekick
+> @lumenflow/packs-sidekick@3.19.0 build /home/runner/work/lumenflow-dev/lumenflow-dev/packages/@lumenflow/packs/sidekick
 > tsc
 

package/packs/sidekick/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/packs-sidekick",
-  "version": "3.18.0",
+  "version": "3.19.0",
   "description": "Sidekick personal assistant pack for LumenFlow — 16 tools for task management, typed memory, channels, routines, and audit",
   "keywords": [
     "lumenflow",

package/packs/software-delivery/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @lumenflow/packs-software-delivery@3.18.0 build /home/runner/work/lumenflow-dev/lumenflow-dev/packages/@lumenflow/packs/software-delivery
+> @lumenflow/packs-software-delivery@3.19.0 build /home/runner/work/lumenflow-dev/lumenflow-dev/packages/@lumenflow/packs/software-delivery
 > tsc
 

package/packs/software-delivery/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/packs-software-delivery",
-  "version": "3.18.0",
+  "version": "3.19.0",
   "description": "Software delivery pack for LumenFlow — work units, gates, lanes, initiatives, and agent coordination",
   "keywords": [
     "lumenflow",

package/templates/core/AGENTS.md.template

@@ -2,6 +2,8 @@
 
 **Last updated:** {{DATE}}
 
+> **Works with any AI coding assistant.** This file provides instructions that work regardless of which AI tool you're using -- Claude Code, Cursor, Windsurf, Cline, Codex, Aider, or any other. Just read this file and follow the workflow.
+
 This project uses LumenFlow workflow. For complete documentation, see [LUMENFLOW.md](LUMENFLOW.md).
 If `LUMENFLOW.local.md` exists, read it after LUMENFLOW.md for project-specific additions.
 
@@ -26,51 +28,102 @@ For the full workflow, principles, and setup instructions, read [LUMENFLOW.md](L
 
 ---
 
-## Quick Start
+## Quick Start (Local Worktree -- Default)
+
+First-time lane setup (once per project, after plan/context is known):
+
+```bash
+pnpm lane:setup
+pnpm lane:validate
+pnpm lane:lock
+```
 
 ```bash
 # 1. Claim a WU
 pnpm wu:claim --id WU-XXXX --lane <Lane>
 cd worktrees/<lane>-wu-xxxx
 
-# 2. Work in worktree, run gates
-pnpm gates
+# 2. Work in worktree
 
-# 3. Complete (ALWAYS run this!)
-cd <project-root>
-pnpm wu:done --id WU-XXXX
+# 3. Prep (runs gates in worktree)
+pnpm wu:prep --id WU-XXXX
+# This prints a copy-paste command for step 4
+
+# 4. Complete (from main - copy-paste from wu:prep output)
+cd <project-root> && pnpm wu:done --id WU-XXXX
 ```
 
-> **Complete CLI reference:** See [quick-ref-commands.md]({{QUICK_REF_LINK}})
+## Quick Start (Cloud / Branch-PR)
 
----
+Cloud agents (Codex, Claude web, CI bots) that cannot use local worktrees use the **branch-pr** mode. This is a first-class lifecycle, not a workaround.
+
+**Activation is explicit-only:** cloud mode is enabled only by `--cloud` or `LUMENFLOW_CLOUD=1`. Runtime identity env vars such as `CLAUDECODE`, `CODEX`, or `CI` do not activate cloud mode.
+
+```bash
+# 1. Create in cloud mode (ID auto-generated; optional if WU already exists)
+pnpm wu:create --lane <Lane> --title "..." ... --cloud
+# Output: Created WU-XXXX
+
+# 2. Claim in cloud mode (creates lane branch, no worktree)
+pnpm wu:claim --id WU-XXXX --lane <Lane> --cloud
+# Or: LUMENFLOW_CLOUD=1 pnpm wu:claim --id WU-XXXX --lane <Lane>
 
-## Critical: Always wu:done
+# 3. Work on the lane branch in your cloud environment
 
-After completing work, ALWAYS run `pnpm wu:done --id WU-XXXX` from the main checkout.
+# 4. Prep (validates branch, runs gates)
+pnpm wu:prep --id WU-XXXX
 
-This is the single most forgotten step. See [LUMENFLOW.md](LUMENFLOW.md) for details.
+# 5. Complete (creates PR instead of merging to main)
+pnpm wu:done --id WU-XXXX
+# Output: PR created. After merge, run: pnpm wu:cleanup --id WU-XXXX
+
+# 6. Post-merge cleanup (after PR is merged)
+pnpm wu:cleanup --id WU-XXXX
+```
+
+**Key differences from worktree mode:**
+
+- `wu:claim --cloud` sets `claimed_mode: branch-pr` (no worktree created)
+- `wu:create --cloud` writes WU specs on the active branch (no main checkout requirement)
+- `wu:done` creates a PR instead of fast-forward merging to main
+- `wu:cleanup` handles post-merge stamp creation and state updates
+- `wu:recover` and `wu:repair` respect branch-pr claimed branches for recovery/admin fixes
+- Cloud mode is never auto-enabled by runtime identity env vars (`CLAUDECODE`, `CODEX`, `CI`)
 
 ---
 
-## Essential Commands
+## CLI Commands and Lifecycle Reference
+
+For complete CLI command documentation (100+ commands), see [quick-ref-commands.md]({{QUICK_REF_LINK}}).
+
+**Essential commands:**
 
-| Command                   | Description                                           |
-| ------------------------- | ----------------------------------------------------- |
-| `pnpm wu:create`          | Create new WU spec (ID auto-generated)                |
-| `pnpm wu:claim`           | Claim WU and create worktree (or `--cloud`)           |
-| `pnpm wu:prep`            | Run gates in worktree, prep for wu:done               |
-| `pnpm wu:done`            | Complete WU (merge or PR, stamp, cleanup)             |
-| `pnpm wu:status`          | Show WU status, location, valid commands              |
+| Command                   | Description                                                             |
+| ------------------------- | ----------------------------------------------------------------------- |
+| `pnpm wu:create`          | Create new WU spec (ID auto-generated)                                  |
+| `pnpm wu:claim`           | Claim WU and create worktree (or `--cloud`)                             |
+| `pnpm wu:prep`            | Run gates in worktree, prep for wu:done                                 |
+| `pnpm wu:done`            | Complete WU (merge or PR, stamp, cleanup)                               |
+| `pnpm wu:status`          | Show WU status, location, valid commands                                |
 | `pnpm wu:brief`           | **MANDATORY after wu:claim.** Generate handoff prompt + record evidence |
-| `pnpm wu:delegate`        | Generate prompt + record delegation lineage           |
-| `pnpm wu:recover`         | Analyze and fix WU state inconsistencies              |
-| `pnpm wu:escalate`        | Show or resolve WU escalation status                  |
-| `pnpm wu:delete`          | Delete WU spec and cleanup                            |
-| `pnpm gates`              | Run all quality gates (`--docs-only` for docs)        |
-| `pnpm lumenflow:commands` | List all public commands (primary + aliases + legacy) |
-| `pnpm mem:checkpoint`     | Save progress checkpoint                              |
-| `pnpm mem:recover`        | Generate recovery context                             |
+| `pnpm wu:delegate`        | Generate prompt + record lineage + brief hash attestation               |
+| `pnpm wu:recover`         | Analyze and fix WU state inconsistencies                                |
+| `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 all quality gates (`--docs-only` for docs)                          |
+| `pnpm lumenflow:commands` | List all public commands (primary + aliases + legacy)                   |
+| `pnpm lane:status`        | Show lane lifecycle status and next step                                |
+| `pnpm lane:setup`         | Create/update draft lane artifacts                                      |
+| `pnpm lane:lock`          | Lock lane lifecycle for delivery WUs                                    |
+| `pnpm mem:checkpoint`     | Save progress checkpoint                                                |
+| `pnpm mem:recover`        | Generate recovery context                                               |
+
+**Two-step completion (wu:prep then wu:done):**
+
+The completion workflow is a two-step process. Run `wu:prep` from the worktree (runs gates, prints copy-paste instruction), then run `wu:done` from main (merge + cleanup). Do NOT run `wu:done` from a worktree.
+
+For detailed troubleshooting, see [troubleshooting-wu-done.md]({{DOCS_ONBOARDING_PATH}}/troubleshooting-wu-done.md).
 
 ---
 
@@ -80,15 +133,17 @@ This is the single most forgotten step. See [LUMENFLOW.md](LUMENFLOW.md) for det
 2. **Worktree Discipline**: After `wu:claim`, work ONLY in the worktree
 3. **Gates Before Done**: Run `pnpm gates` before `wu:done`
 4. **Never Bypass Hooks**: No `--no-verify`
+5. **Vendor-Agnostic Dirty-Main Guard**: `wu:prep` and `wu:done` hard-block when main has non-allowlisted dirty files during worktree WUs (including MCP/tool-originated writes). `branch-pr` mode is exempt.
+
+For the complete set of non-negotiable constraints (git safety, forbidden commands, skip-gates policy, and more), see [.lumenflow/constraints.md](.lumenflow/constraints.md).
 
 ---
 
-## Forbidden Commands
+## Safety: Forbidden Commands and Safe Alternatives
+
+LumenFlow enforces safety at the repository level via git wrappers and hooks. For the full list of forbidden commands and their safe `wu:` alternatives, see [.lumenflow/constraints.md](.lumenflow/constraints.md).
 
-- `git reset --hard`
-- `git push --force`
-- `git stash` (on main)
-- `--no-verify`
+**Key rule:** Always use `wu:` commands for worktree and branch management -- never raw `git worktree` or `git branch -D` commands. Use `wu:recover` for state inconsistencies, `wu:release` for abandoned WUs, and `wu:prune` for stale worktrees.
 
 ---
 
@@ -99,3 +154,73 @@ This file provides universal guidance for all AI agents. Additional vendor-speci
 - **Claude Code**: See `CLAUDE.md` (if present)
 - **Cursor**: See `.cursor/rules/lumenflow.md` (if present)
 - **Windsurf**: See `.windsurf/rules/lumenflow.md` (if present)
+- **Cline**: See `.clinerules` (if present)
+
+---
+
+## Workflow Summary
+
+### Local (Worktree Mode -- Default)
+
+| Step         | Location | Command                                                                                                                                                                      |
+| ------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1. Create WU | main     | `pnpm wu:create --lane <Lane> --title "Title" --description "..." --acceptance "..." --code-paths "..." --test-paths-unit "..." --exposure backend-only` (ID auto-generated) |
+| 2. Claim     | main     | `pnpm wu:claim --id WU-XXX --lane <Lane>`                                                                                                                                    |
+| 3. Brief     | worktree | `cd worktrees/<lane>-wu-xxx && pnpm wu:brief --id WU-XXX --client <client>` **(mandatory — wu:done blocks without this)**                                                    |
+| 4. Work      | worktree | Implement changes per acceptance criteria                                                                                                                                    |
+| 5. Prep      | worktree | `pnpm wu:prep --id WU-XXX` (runs gates)                                                                                                                                      |
+| 6. Complete  | main     | `pnpm wu:done --id WU-XXX` (copy-paste from wu:prep)                                                                                                                         |
+
+### Cloud (Branch-PR Mode)
+
+| Step         | Location    | Command                                                                                     |
+| ------------ | ----------- | ------------------------------------------------------------------------------------------- |
+| 1. Create WU | lane branch | `pnpm wu:create --lane <Lane> --title "..." ... --cloud` (ID auto-generated)                |
+| 2. Claim     | lane branch | `pnpm wu:claim --id WU-XXX --lane <Lane> --cloud`                                           |
+| 3. Brief     | lane branch | `pnpm wu:brief --id WU-XXX --client <client>` **(mandatory — wu:done blocks without this)** |
+| 4. Work      | lane branch | Work on `lane/<lane>/wu-xxx` in cloud environment                                           |
+| 5. Prep      | lane branch | `pnpm wu:prep --id WU-XXX` (validates branch, runs gates)                                   |
+| 6. Complete  | lane branch | `pnpm wu:done --id WU-XXX` (creates PR)                                                     |
+| 7. Cleanup   | after merge | `pnpm wu:cleanup --id WU-XXX` (post-merge stamps)                                           |
+
+---
+
+## Public Docs IA (Kernel + Packs)
+
+- Kernel docs source: `apps/docs/src/content/docs/kernel/**`
+- Software Delivery Pack docs source: `apps/docs/src/content/docs/packs/software-delivery/**`
+- Language guides (pack-scoped): `apps/docs/src/content/docs/packs/software-delivery/languages/**`
+- Docs truth YAML files:
+  - `apps/docs/src/data/version-policy.yaml`
+  - `apps/docs/src/data/language-support.yaml`
+  - `apps/docs/src/data/example-repos.yaml`
+
+---
+
+## Further Reading
+
+- [LUMENFLOW.md](LUMENFLOW.md) -- Main workflow documentation (principles, setup, initiatives, skills)
+- [.lumenflow/constraints.md](.lumenflow/constraints.md) -- Non-negotiable rules and forbidden commands
+- [Quick Reference: Commands]({{QUICK_REF_LINK}}) -- Complete CLI reference (100+ commands)
+- [Troubleshooting wu:done]({{DOCS_ONBOARDING_PATH}}/troubleshooting-wu-done.md) -- Most common completion mistakes
+- [LumenFlow Agent Capsule]({{DOCS_OPERATIONS_PATH}}/_frameworks/lumenflow/lumenflow-agent-capsule.md) -- Full framework reference (lifecycle, lanes, gates, DoD)
+
+---
+
+## Context Recovery (WU-2157)
+
+If you are resuming work or have lost context, check for recovery files:
+
+```bash
+# Check for pending recovery
+ls .lumenflow/state/recovery-pending-*.md 2>/dev/null
+
+# Generate fresh recovery context
+pnpm mem:recover --wu WU-XXX
+
+# Or generate a full handoff prompt
+pnpm wu:brief --id WU-XXX --client codex-cli
+```
+
+Recovery files contain your last checkpoint, acceptance criteria, code paths, and changed files.
+Always save checkpoints before long operations: `pnpm mem:checkpoint "progress note" --wu WU-XXX`