@lumenflow/cli 3.2.0 → 3.2.2

package/templates/core/.lumenflow/constraints.md.template

@@ -1,13 +1,13 @@
 # LumenFlow Constraints Capsule
 
-**Version:** 1.2
+**Version:** 1.3
 **Last updated:** {{DATE}}
 
-This document contains the 8 non-negotiable constraints that every agent must keep "in working memory" from first plan through `wu:done`.
+This document contains the 9 non-negotiable constraints that every agent must keep "in working memory" from first plan through `wu:done`.
 
 ---
 
-## The 8 Non-Negotiable Constraints
+## The 9 Non-Negotiable Constraints
 
 ### 1. Worktree Discipline and Git Safety
 
@@ -179,6 +179,34 @@ If you see something broken on main (failing gates, format issues, typos, lint e
 
 ---
 
+### 9. YAML Files Must Be Modified via CLI Tooling Only (WU-1907)
+
+**Rule:** Never use raw Write/Edit tools to modify `.lumenflow.config.yaml` or WU YAML specification files. Always use the dedicated CLI commands.
+
+**Safe commands:**
+
+| File                     | Command                     | Example                                                        |
+| ------------------------ | --------------------------- | -------------------------------------------------------------- |
+| `.lumenflow.config.yaml` | `pnpm config:set`           | `pnpm config:set --key methodology.testing --value test-after` |
+| `.lumenflow.config.yaml` | `pnpm config:get` (read)    | `pnpm config:get --key methodology.testing`                    |
+| WU YAML specs            | `pnpm wu:edit`              | `pnpm wu:edit --id WU-XXX --description "..."`                 |
+| WU YAML specs            | `pnpm wu:create` (creation) | `pnpm wu:create --lane "Framework: Core" --title "..."`        |
+
+**Blocked operations:**
+
+- `Write(.lumenflow.config.yaml, ...)` -- use `pnpm config:set` instead
+- `Edit(.lumenflow.config.yaml, ...)` -- use `pnpm config:set` instead
+- `Write(docs/04-operations/tasks/wu/WU-XXX.yaml, ...)` -- use `pnpm wu:edit` instead
+- `Edit(docs/04-operations/tasks/wu/WU-XXX.yaml, ...)` -- use `pnpm wu:edit` instead
+
+**Exception:** Reading YAML files with the Read tool is acceptable for inspection purposes.
+
+**Why:** CLI tooling provides Zod schema validation, atomic commits via micro-worktree, audit trail, and automatic type coercion. Raw edits bypass all of these safeguards and can produce invalid configurations that break downstream commands.
+
+**Full policy:** See [.lumenflow/rules/yaml-editing-policy.md](rules/yaml-editing-policy.md).
+
+---
+
 ## Mini Audit Checklist
 
 Before running `wu:done`, verify:

package/templates/core/LUMENFLOW.md.template

@@ -22,23 +22,28 @@ For detailed troubleshooting, common mistakes, and recovery steps, see [troubles
 # 1. Setup (first time only)
 pnpm setup
 
-# 2. Create a WU (--id is optional, auto-generates next sequential ID if omitted)
+# 2. Configure lane lifecycle once per project (after context/plan is clear)
+pnpm lane:setup
+pnpm lane:validate
+pnpm lane:lock
+
+# 3. Create a WU (--id is optional, auto-generates next sequential ID if omitted)
 pnpm wu:create --lane <Lane> --title "Title" \
   --description "..." --acceptance "..." --code-paths "..." \
   --test-paths-unit "..." --exposure backend-only \
   --spec-refs "lumenflow://plans/WU-XXXX-plan.md"
 
-# 3. Claim (auto-merges spec branch to main if needed)
+# 4. Claim (auto-merges spec branch to main if needed)
 pnpm wu:claim --id WU-XXXX --lane <Lane>
 cd worktrees/<lane>-wu-xxxx
 
-# 4. Implement in worktree
+# 5. Implement in worktree
 
-# 5. Prepare (runs gates in worktree) - WU-1223 NEW
+# 6. Prepare (runs gates in worktree) - WU-1223 NEW
 pnpm wu:prep --id WU-XXXX
 # This prints a copy-paste instruction for the next step
 
-# 6. Complete (from main checkout - copy-paste from wu:prep output)
+# 7. Complete (from main checkout - copy-paste from wu:prep output)
 cd /path/to/main && pnpm wu:done --id WU-XXXX
 ```
 
@@ -70,14 +75,17 @@ pnpm initiative:status --id INIT-001
 
 ## Setup Notes (Common First-Run Failures)
 
-### Lane inference (sub-lanes)
+### Lane lifecycle (deferred setup)
 
-If you use sub-lanes like `Experience: UI`, you must have a lane taxonomy:
+`lumenflow init` no longer finalizes delivery lanes. Lane setup is an explicit process:
 
-- Ensure `.lumenflow.lane-inference.yaml` exists, or
-- Generate it with `pnpm lane:suggest --output .lumenflow.lane-inference.yaml`
+```bash
+pnpm lane:setup      # creates/updates draft lane artifacts
+pnpm lane:validate   # validates draft lane artifacts
+pnpm lane:lock       # finalizes lane lifecycle for delivery WUs
+```
 
-Without this file, sub-lane validation will fail.
+`wu:create` requires lane lifecycle status `locked` and prints a deterministic next step when lanes are `unconfigured` or `draft`.
 
 ### Local-only / no remote
 
@@ -86,8 +94,9 @@ By default, `wu:create` expects an `origin` remote and will fetch `origin/main`.
 For local-only or offline development, add this to `workspace.yaml`:
 
 ```yaml
-git:
-  requireRemote: false
+software_delivery:
+  git:
+    requireRemote: false
 ```
 
 When `requireRemote: false`:
@@ -156,6 +165,15 @@ For cloud agents (Codex/Claude web/CI) operating on feature branches:
 - **.lumenflow/rules/** - Workflow rules (git-safety.md, wu-workflow.md, etc.)
 - **docs/04-operations/\_frameworks/lumenflow/agent/onboarding/** - Agent onboarding documentation
 
+### Public Starlight Docs (Kernel/Packs IA)
+
+- **apps/docs/src/content/docs/kernel/** - Kernel-only user docs
+- **apps/docs/src/content/docs/packs/software-delivery/** - Software Delivery Pack docs
+- **apps/docs/src/content/docs/packs/software-delivery/languages/** - Pack-scoped language guides
+- **apps/docs/src/data/version-policy.yaml** - Published stable version source of truth
+- **apps/docs/src/data/language-support.yaml** - Language guide support metadata
+- **apps/docs/src/data/example-repos.yaml** - Companion example-repo mapping
+
 ### Client/Vendor Overlays
 
 - **CLAUDE.md** - Claude Code overlay (single file at root)
@@ -184,6 +202,15 @@ After claiming a WU, immediately `cd worktrees/<lane>-wu-xxx` and work exclusive
 
 For the full worktree lifecycle (parallel execution, bootstrap, isolation guarantees), see [lumenflow-complete.md section 2.4](docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md). For the mandatory pre-write check, see [.lumenflow/constraints.md](.lumenflow/constraints.md).
 
+### Vendor-Agnostic Dirty-Main Guard
+
+`wu:prep` and `wu:done` enforce a runtime guard (not just hooks) across all clients and tools:
+
+- In worktree mode, commands block if main checkout has non-allowlisted dirty files
+- This includes writes from MCP tools or any vendor client that bypasses hook execution
+- Allowed dirty prefixes on main: `docs/04-operations/tasks/wu/`, `.lumenflow/`, `.claude/`, `plan/`
+- `branch-pr` mode is exempt (no local worktree/main split)
+
 ---
 
 ## Definition of Done
@@ -200,21 +227,29 @@ For the full worktree lifecycle (parallel execution, bootstrap, isolation guaran
 
 > **Complete CLI reference (60+ commands):** See [quick-ref-commands.md](docs/04-operations/_frameworks/lumenflow/agent/onboarding/quick-ref-commands.md). 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 gates`          | Run quality gates (`--docs-only` for docs 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 `experimental.context_validation`.
+| 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 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.
 
 For recovery commands, state management, memory coordination, and orchestration tools, see [quick-ref-commands.md](docs/04-operations/_frameworks/lumenflow/agent/onboarding/quick-ref-commands.md).
 
@@ -222,7 +257,7 @@ For recovery commands, state management, memory coordination, and orchestration
 
 ## Constraints
 
-See [.lumenflow/constraints.md](.lumenflow/constraints.md) for the 8 non-negotiable rules:
+See [.lumenflow/constraints.md](.lumenflow/constraints.md) for the 9 non-negotiable rules:
 
 1. Worktree discipline and git safety
 2. WUs are specs, not code
@@ -232,6 +267,7 @@ See [.lumenflow/constraints.md](.lumenflow/constraints.md) for the 8 non-negotia
 6. Safety and governance
 7. Test ratchet pattern
 8. Lane-fit reasoning
+9. YAML files must be modified via CLI tooling only
 
 ---
 
@@ -277,8 +313,10 @@ Pre-configured agent definitions in `.claude/agents/`:
 | `code-reviewer`   | Quality checks             |
 | `bug-triage`      | Bug classification         |
 
-Generate handoff prompts (prompt-only, execution is a separate step): `pnpm wu:brief --id WU-XXX --client claude-code`
-Record explicit delegation lineage when needed: `pnpm wu:delegate --id WU-XXX --parent-wu WU-YYY --client claude-code`
+Generate handoff prompts (prompt-only, execution is a separate step): `pnpm wu:brief --id WU-XXX --client <client>`
+Record explicit delegation lineage when needed: `pnpm wu:delegate --id WU-XXX --parent-wu WU-YYY --client <client>`
+
+Supported clients: `claude-code`, `codex-cli`, `cursor`, `gemini-cli`, `windsurf`
 
 ---
 

package/templates/core/ai/onboarding/agent-invocation-guide.md.template

@@ -52,7 +52,7 @@ The handoff prompt is the bridge between sessions. `wu:brief` generates this pro
 pnpm mem:checkpoint "Progress: completed X, next: Y" --wu WU-XXX
 git add -A && git commit -m "checkpoint: progress on X"
 git push origin lane/<lane>/wu-xxx
-pnpm wu:brief --id WU-XXX --client claude-code
+pnpm wu:brief --id WU-XXX --client <client>
 # Copy generated prompt into Task tool to start the next agent session.
 # Exit current session; start fresh in the new session.
 ```
@@ -90,7 +90,7 @@ memory:
 Use `--no-context` when you want a clean prompt without memory context:
 
 ```bash
-pnpm wu:brief --id WU-XXX --client claude-code --no-context
+pnpm wu:brief --id WU-XXX --client <client> --no-context
 ```
 
 This is useful when:
@@ -123,6 +123,33 @@ Use this structure for sub-agent prompts:
 
 ---
 
+## 3a) Template Condition Evaluation (WU-1898)
+
+Spawn prompt templates support conditional inclusion via the `condition` field in template frontmatter. Conditions are evaluated against the WU context before templates are included in the assembled prompt.
+
+**How it works:**
+
+- Templates with a `condition` field are only included when the condition evaluates to `true`
+- The `type` context variable (from WU YAML) gates type-specific directives
+- The `policy.testing` and `policy.architecture` context variables gate methodology templates
+- Templates without a `condition` field are always included
+
+**Examples of condition gating:**
+
+| Template                  | Condition                                                              | Effect                                         |
+| ------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------- |
+| `tdd-directive`           | `type !== 'documentation' && type !== 'docs' && type !== 'config'`     | Excluded for documentation WUs                 |
+| `documentation-directive` | `type === 'documentation' \|\| type === 'docs' \|\| type === 'config'` | Included only for documentation WUs            |
+| `refactor-directive`      | `type === 'refactor'`                                                  | Included only for refactor WUs                 |
+| `methodology-tdd`         | `policy.testing === 'tdd'`                                             | Included only when TDD policy is active        |
+| `methodology-test-after`  | `policy.testing === 'test-after'`                                      | Included only when test-after policy is active |
+
+This ensures documentation WUs do not receive TDD directives, and methodology-specific directives are only included when the project's resolved policy matches.
+
+**Reference:** See the [Template Format reference](https://lumenflow.dev/reference/templates/) for full condition syntax and context variables.
+
+---
+
 ## 4) Append These Constraints at the End (Mandatory)
 
 Paste this block at the end of every multi-agent prompt:

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

@@ -271,6 +271,20 @@ Phrases that mean "do this now":
 
 ---
 
+## Lane Lock Lifecycle and Zombie Detection (WU-1901)
+
+Lane locks (`.lumenflow/locks/<lane-kebab>.lock`) enforce WIP=1. Key semantics:
+
+- **Lock acquisition**: `wu:claim` creates a lock file atomically with a PID, timestamp, and WU ID.
+- **PID becomes invalid immediately**: Since `wu:claim` is a short-lived process, the PID in the lock becomes dead as soon as the claim completes. This is expected -- the lock persists on disk.
+- **Zombie detection requires BOTH conditions**: A lock is only auto-cleared if it is BOTH stale (older than 2 hours) AND the PID is dead. A dead PID alone does NOT trigger auto-clearing.
+- **Normal release**: `wu:done` removes the lock after merging.
+- **Manual unlock**: `pnpm wu:unlock-lane --lane "<lane>" --reason "<reason>"` for genuinely abandoned locks.
+
+This means a recently claimed lane (within 2 hours) will NOT be auto-cleared even if the claiming process has exited. To reclaim a lane held by another WU, complete or release the existing WU first.
+
+---
+
 ## Quick Checklist
 
 Before starting any WU:

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

@@ -33,6 +33,7 @@ Run `--help` first, then run the real command with explicit flags.
 | Metrics & Flow      | `pnpm flow:report --help`             | `pnpm flow:report`                                                       |
 | Documentation       | `pnpm docs:validate --help`           | `pnpm docs:validate`                                                     |
 | Release             | `pnpm pre-release:check --help`       | `pnpm pre-release:check`                                                 |
+| Configuration       | `pnpm config:set --help`              | `pnpm config:set --key methodology.testing --value test-after`           |
 | Agent Utilities     | `pnpm agent:issues-query --help`      | `pnpm agent:issues-query`                                                |
 
 ---
@@ -77,21 +78,21 @@ pnpm exec lumenflow --client all      # All clients
 
 ## WU Lifecycle
 
-| Command                                        | Description                                      |
-| ---------------------------------------------- | ------------------------------------------------ |
-| `pnpm wu:create --id WU-XXX --lane <Lane> ..`  | Create new WU spec (see required fields below)   |
-| `pnpm wu:claim --id WU-XXX --lane <Lane>`      | Claim WU and create worktree (default)           |
-| `pnpm wu:claim --id WU-XXX --lane <L> --cloud` | Claim WU in cloud/branch-pr mode (no worktree)   |
-| `pnpm wu:prep --id WU-XXX [--full-tests]`      | Run gates, prep for wu:done (`tests.unit` scoped by default) |
-| `pnpm wu:done --id WU-XXX`                     | Complete WU (merge or PR, stamp, cleanup)        |
-| `pnpm wu:edit --id WU-XXX --description "..."` | Edit WU spec fields (run --help for all flags)   |
-| `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:status --id WU-XXX`                   | Show WU status, location, valid commands         |
-| `pnpm wu:brief --id WU-XXX --client <client>`  | Generate handoff prompt (does not execute)       |
-| `pnpm wu:brief --id WU-XXX --no-context`       | Generate prompt without memory context injection |
-| `pnpm wu:delegate --id WU-XXX --parent-wu <P>` | Generate prompt and record delegation lineage    |
+| Command                                         | Description                                                  |
+| ----------------------------------------------- | ------------------------------------------------------------ |
+| `pnpm wu:create --lane <Lane> --title "..." ..` | Create new WU spec (ID auto-generated; see fields below)     |
+| `pnpm wu:claim --id WU-XXX --lane <Lane>`       | Claim WU and create worktree (default)                       |
+| `pnpm wu:claim --id WU-XXX --lane <L> --cloud`  | Claim WU in cloud/branch-pr mode (no worktree)               |
+| `pnpm wu:prep --id WU-XXX [--full-tests]`       | Run gates, prep for wu:done (`tests.unit` scoped by default) |
+| `pnpm wu:done --id WU-XXX`                      | Complete WU (merge or PR, stamp, cleanup)                    |
+| `pnpm wu:edit --id WU-XXX --description "..."`  | Edit WU spec fields (run --help for all flags)               |
+| `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:status --id WU-XXX`                    | Show WU status, location, valid commands                     |
+| `pnpm wu:brief --id WU-XXX --client <client>`   | Generate handoff prompt (does not execute)                   |
+| `pnpm wu:brief --id WU-XXX --no-context`        | Generate prompt without memory context injection             |
+| `pnpm wu:delegate --id WU-XXX --parent-wu <P>`  | Generate prompt and record delegation lineage                |
 
 ### WU Maintenance
 
@@ -112,18 +113,22 @@ pnpm exec lumenflow --client all      # All clients
 
 ## 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 --paths "..."` | Suggest lane for code paths      |
+| 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 --paths "..."` | Suggest lane for code paths       |
+| `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 |
 
 ¹ **Script aliases:** `spec:linter` and `tasks:validate` are pnpm script aliases
 for `wu:validate --all`. They are not standalone CLI commands.
@@ -211,6 +216,30 @@ Supported mismatch fixes:
 
 ---
 
+## Configuration
+
+| Command                                           | Description                                     |
+| ------------------------------------------------- | ----------------------------------------------- |
+| `pnpm config:get --key <dotpath>`                 | Read a value from `workspace.yaml`              |
+| `pnpm config:set --key <dotpath> --value <value>` | Set a value in `workspace.yaml` (Zod-validated) |
+
+`config:set` validates against the Zod schema before writing and uses the micro-worktree
+pattern for atomic commits. Always use these commands instead of raw Write/Edit on
+`workspace.yaml`. See [Constraint 9](../../../../../.lumenflow/constraints.md)
+and [YAML editing policy](../../../../../.lumenflow/rules/yaml-editing-policy.md).
+
+**Common dotpaths:**
+
+| Dotpath                           | Type    | Example Values              |
+| --------------------------------- | ------- | --------------------------- |
+| `methodology.testing`             | enum    | `tdd`, `test-after`, `none` |
+| `gates.minCoverage`               | number  | `0`-`100`                   |
+| `gates.enableCoverage`            | boolean | `true`, `false`             |
+| `experimental.context_validation` | boolean | `true`, `false`             |
+| `git.requireRemote`               | boolean | `true`, `false`             |
+
+---
+
 ## Dependencies
 
 | Command                         | Description                    |
@@ -222,15 +251,15 @@ Supported mismatch fixes:
 
 ## Plans
 
-Plans are markdown documents that capture goals, scope, approach, and success criteria before implementation begins. They link to WUs (via `spec_refs`) and initiatives (via `related_plan`).
+Plans are markdown documents that capture goals, scope, approach, and success criteria before implementation begins. They link to WUs (via the `plan` field, WU-1683) and initiatives (via `related_plan`).
 
 ### Plan Storage
 
 Plans are stored in the repo at `docs/04-operations/plans/` by default (configurable via `directories.plansDir` in `workspace.yaml`).
 
 If the plan exists only in conversation, use `--plan` on `wu:create` to generate a lightweight
-stub in `$LUMENFLOW_HOME/plans/`, then summarize the conversation there and reference it via
-`spec_refs`. Feature WUs require `spec_refs`; notes do not replace the plan link.
+stub in `$LUMENFLOW_HOME/plans/` and automatically set the WU's `plan` field to the
+`lumenflow://plans/` URI. Feature WUs should have a `plan` field; notes do not replace the plan link.
 
 | Command                                                                  | Description                                                   |
 | ------------------------------------------------------------------------ | ------------------------------------------------------------- |
@@ -263,15 +292,17 @@ pnpm initiative:plan --initiative INIT-001 --create
 pnpm initiative:plan --initiative INIT-001 --plan docs/04-operations/plans/my-plan.md
 ```
 
-**To a WU (via spec_refs):**
+**To a WU (via `plan` field, WU-1683):**
 
 ```bash
-# When creating a WU
-pnpm wu:create --id WU-123 --lane "Framework: Core" --title "Feature" \
-  --spec-refs "lumenflow://plans/WU-123-plan.md"
+# When creating a WU (--plan auto-generates and links)
+pnpm wu:create --lane "Framework: Core" --title "Feature" --plan
+
+# Or edit an existing WU with a specific plan URI
+pnpm wu:edit --id WU-123 --plan "lumenflow://plans/WU-123-plan.md"
 
-# Or edit an existing WU
-pnpm wu:edit --id WU-123 --spec-refs "lumenflow://plans/WU-123-plan.md"
+# Or use plan:link
+pnpm plan:link --id WU-123 --plan lumenflow://plans/WU-123-plan.md
 ```
 
 ### Plan URI Format
@@ -396,18 +427,18 @@ pnpm gates              # Now works
 # 0. Check available options (do this before first use of any command)
 pnpm wu:create --help
 
-# 1. Create WU
-pnpm wu:create --id WU-XXX --lane "Framework: Core" --title "Add feature" \
+# 1. Create WU (ID auto-generated)
+pnpm wu:create --lane "Framework: Core" --title "Add feature" \
   --description "Context: ... Problem: ... Solution: ..." \
   --acceptance "Criterion 1" --acceptance "Criterion 2" \
   --code-paths "src/file.ts" \
   --test-paths-unit "src/__tests__/file.test.ts" \
-  --exposure backend-only \
-  --spec-refs "~/.lumenflow/plans/WU-XXX-plan.md"
+  --exposure backend-only
+# Output: Created WU-1990 at docs/.../wu/WU-1990.yaml
 
-# 2. Claim (creates worktree)
-pnpm wu:claim --id WU-XXX --lane "Framework: Core"
-cd worktrees/framework-core-wu-xxx
+# 2. Claim (creates worktree) -- use the ID from wu:create output
+pnpm wu:claim --id WU-1990 --lane "Framework: Core"
+cd worktrees/framework-core-wu-1990
 
 # 2b. Bootstrap (build CLI for dist-backed commands)
 pnpm bootstrap
@@ -419,10 +450,10 @@ pnpm bootstrap
 git add . && git commit -m "feat: description"
 
 # 5. Prep (runs gates in worktree)
-pnpm wu:prep --id WU-XXX
+pnpm wu:prep --id WU-1990
 
 # 6. Complete (from main - copy from wu:prep output)
-cd /path/to/main && pnpm wu:done --id WU-XXX
+cd /path/to/main && pnpm wu:done --id WU-1990
 ```
 
 ---
@@ -437,9 +468,24 @@ For code changes, you must include **all** of the following (or wu:create will f
 - `--test-paths-unit` or `--test-paths-e2e` (automated tests required)
 - `--exposure` (ui | api | backend-only | documentation)
 - `--spec-refs` (required for type: feature)
+- `--plan` (optional, auto-generates plan file and sets `plan` field — WU-1683)
 
 Documentation WUs can omit code/test paths but should set `--type documentation` and `--exposure documentation`.
 
+**Auto-generated IDs (recommended):** Omit `--id` and let `wu:create` assign the next sequential ID. Capture the output for dependency chaining:
+
+```bash
+# Create first WU (ID auto-generated)
+pnpm wu:create --lane "Framework: Core" --title "First WU" ...
+# Output: Created WU-1990
+
+# Create second WU blocked by the first
+pnpm wu:create --lane "Framework: Core" --title "Second WU" --blocked-by WU-1990 ...
+# Output: Created WU-1991
+```
+
+> **Note:** Use `--id` only when re-creating a specific WU or for migration tooling.
+
 ---
 
 ## Strict WU Validation (WU-1329)
@@ -498,14 +544,27 @@ Agents should:
 
 ---
 
-## Lane Inference Requirement (Sub-Lanes)
+## Lane Lifecycle Requirement
 
-If you use a sub-lane like `Experience: UI`, you **must** have a lane taxonomy:
+Before the first delivery WU, complete lane lifecycle once per project:
 
-- Ensure `.lumenflow.lane-inference.yaml` exists, or
-- Generate it with `pnpm lane:suggest --output .lumenflow.lane-inference.yaml`
+```bash
+pnpm lane:setup
+pnpm lane:validate
+pnpm lane:lock
+```
 
-Without this file, sub-lane validation will fail.
+Lifecycle states:
+
+- `unconfigured` -> next step `pnpm lane:setup`
+- `draft` -> next step `pnpm lane:lock`
+- `locked` -> delivery WUs can be created
+
+Check current lifecycle state any time:
+
+```bash
+pnpm lane:status
+```
 
 ---
 

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

@@ -56,6 +56,10 @@ If you are starting a new project or feature from a product vision (e.g., "Build
 3. **Create WUs under the Initiative**: Each WU belongs to a phase
 
    ```bash
+   pnpm lane:setup
+   pnpm lane:validate
+   pnpm lane:lock
+
    pnpm wu:create --lane "Core: Platform" --title "Add task model" \
      --description "..." --acceptance "..." --code-paths "..." \
      && pnpm initiative:add-wu --initiative INIT-001 --wu WU-XXX --phase 1
@@ -168,10 +172,15 @@ all signals are user-configured.
 
 ## Before Creating WUs
 
-If you plan to use sub-lanes like `Experience: UI`, make sure lane inference is configured:
+Before the first delivery WU in a project, complete lane lifecycle:
+
+```bash
+pnpm lane:setup
+pnpm lane:validate
+pnpm lane:lock
+```
 
-- `.lumenflow.lane-inference.yaml` must exist for sub-lane validation, or
-- Generate it with `pnpm lane:suggest --output .lumenflow.lane-inference.yaml`
+Use `pnpm lane:status` to verify lifecycle state and recommended next step.
 
 **No remote yet?** `wu:create` expects `origin/main`. If your repo is local-only, add a remote
 before running `wu:create`. `wu:claim` supports `--no-push` for local-only work.
@@ -274,6 +283,55 @@ LUMENFLOW_FORCE=1 LUMENFLOW_FORCE_REASON="backlog corruption recovery" git push
 
 ---
 
+## Safe Configuration Modification (Constraint 9)
+
+**Never use Write or Edit tools to modify YAML configuration files.** Always use the dedicated CLI commands.
+
+### Modifying workspace.yaml
+
+```bash
+# Read a config value
+pnpm config:get --key methodology.testing
+
+# Set a config value (validates against Zod schema, uses atomic commit)
+pnpm config:set --key methodology.testing --value test-after
+
+# Set a boolean
+pnpm config:set --key gates.enableCoverage --value false
+
+# Set a number
+pnpm config:set --key gates.minCoverage --value 85
+
+# Append to an array
+pnpm config:set --key agents.methodology.principles --value Library-First,KISS
+```
+
+### Modifying WU YAML Specs
+
+```bash
+# Edit WU fields (run --help for all available flags)
+pnpm wu:edit --id WU-XXX --description "Updated description"
+
+# Create new WU (never manually Write a YAML file)
+pnpm wu:create --lane "Framework: Core" --title "Add feature" \
+  --description "..." --acceptance "..."
+```
+
+### Why This Matters
+
+Raw-editing YAML files with Write/Edit tools bypasses:
+
+1. **Schema validation** -- `config:set` validates against the Zod schema
+2. **Atomic commits** -- `config:set` uses micro-worktree for safe writes
+3. **Audit trail** -- CLI commands produce structured log entries
+4. **Type coercion** -- Automatic boolean/number/array handling
+
+**Exception:** Reading YAML files with the Read tool is acceptable for inspection.
+
+For the full policy, see [.lumenflow/rules/yaml-editing-policy.md](../../../../../.lumenflow/rules/yaml-editing-policy.md) and Constraint 9 in [.lumenflow/constraints.md](../../../../../.lumenflow/constraints.md).
+
+---
+
 ## Common Failure Scenarios and Recovery
 
 ### Scenario 1: "BLOCKED: Direct commit to main"
@@ -565,7 +623,7 @@ rm -rf /tmp/nextjs-scaffold
 
 - [LUMENFLOW.md](../../../../../LUMENFLOW.md) - Main workflow documentation
 - [AGENTS.md](../../../../../AGENTS.md) - Universal agent entry point
-- [.lumenflow/constraints.md](../../../../../.lumenflow/constraints.md) - The 8 non-negotiable rules
+- [.lumenflow/constraints.md](../../../../../.lumenflow/constraints.md) - The 9 non-negotiable rules
 - [troubleshooting-wu-done.md](troubleshooting-wu-done.md) - Why agents forget wu:done
 - [first-wu-mistakes.md](first-wu-mistakes.md) - Common mistakes to avoid
 - [quick-ref-commands.md](quick-ref-commands.md) - Command reference