@lumenflow/cli 3.18.1 → 3.20.0

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`

package/templates/core/LUMENFLOW.md.template

@@ -2,10 +2,6 @@
 
 **Last updated:** {{DATE}}
 
-> **This file is managed by LumenFlow.** Do not edit — it will be overwritten on upgrade.
-> For project-specific additions, create `LUMENFLOW.local.md` (never overwritten).
-> If `LUMENFLOW.local.md` exists, agents should read it after this file.
-
 LumenFlow is a vendor-agnostic workflow framework for AI-native software development.
 
 > **Context Safety**: When approaching context limits (80% usage, 50+ tool calls), spawn a fresh agent instead of continuing after compaction. See [wu-sizing-guide.md]({{DOCS_OPERATIONS_PATH}}/_frameworks/lumenflow/wu-sizing-guide.md).
@@ -54,6 +50,9 @@ cd worktrees/<lane>-wu-xxxx
 # 4b. Build CLI in worktree (required for gates)
 pnpm bootstrap
 
+# 4c. Run wu:brief (MANDATORY — wu:done blocks without this)
+pnpm wu:brief --id WU-XXXX --client <client>
+
 # 5. Implement in worktree
 
 # 6. Prepare (runs gates in worktree) - WU-1223 NEW
@@ -141,7 +140,7 @@ When `requireRemote: true` (default):
 ## Core Principles
 
 1. **Design-First** (feature/refactor WUs): Load `/skill design-first` before implementation. Question requirements, delete unnecessary, simplify before optimizing
-2. **Fit-For-Surface Verification**: Choose the least brittle verification that gives strong confidence. Prefer TDD for runtime logic when repository policy requires it; prefer behavior-focused integration, smoke, visual, or manual verification for UI, content, and presentation work.
+2. **Fit-For-Surface Verification**: Choose the least brittle verification that gives strong confidence. Prefer TDD for runtime logic when repository policy requires it; prefer behavior-focused integration, smoke, visual, or manual verification for UI, content, and presentation work. Never assert inline styles, CSS values, exact copy, or DOM shape in E2E/integration tests.
 3. **Library-First**: Search existing libraries before custom code
 4. **DRY/SOLID/KISS/YAGNI**: No magic numbers, no hardcoded strings
 5. **Worktree Discipline**: After `wu:claim`, work ONLY in the worktree
@@ -221,6 +220,22 @@ lumenflow init --merge             # Safe merge into existing files
 
 The `--merge` flag uses bounded markers (`LUMENFLOW:START`/`END`) to safely insert or update LumenFlow config in existing files without overwriting user content.
 
+### File Ownership Model
+
+| File                           | Owner                     | On Upgrade                                                      | User Overrides           |
+| ------------------------------ | ------------------------- | --------------------------------------------------------------- | ------------------------ |
+| `LUMENFLOW.md`                 | LumenFlow (fully managed) | Force-synced from template                                      | Use `LUMENFLOW.local.md` |
+| `.lumenflow/constraints.md`    | LumenFlow (fully managed) | Force-synced from template                                      | —                        |
+| `AGENTS.md`                    | Shared (merge-block)      | Content between `LUMENFLOW:START`/`END` updated; rest preserved | Edit outside markers     |
+| `CLAUDE.md`                    | Shared (merge-block)      | Content between markers updated; rest preserved                 | Edit outside markers     |
+| `.cursor/rules/lumenflow.md`   | Shared (merge-block)      | Content between markers updated; rest preserved                 | Edit outside markers     |
+| `.windsurf/rules/lumenflow.md` | Shared (merge-block)      | Content between markers updated; rest preserved                 | Edit outside markers     |
+| `LUMENFLOW.local.md`           | User (never touched)      | Skipped entirely                                                | Full ownership           |
+| `.lumenflow/templates/`        | User (never touched)      | Skipped entirely                                                | Full ownership           |
+
+> For project-specific workflow additions, create `LUMENFLOW.local.md` (never overwritten).
+> If `LUMENFLOW.local.md` exists, agents should read it after this file.
+
 ---
 
 ## Worktree Discipline (IMMUTABLE LAW)
@@ -254,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)    |
+| 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                                    |
+| `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                                                  |
 
 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.