@lumenflow/cli 3.18.1 → 3.20.0

package/templates/core/ai/onboarding/docs-generation.md.template

@@ -14,6 +14,87 @@ LumenFlow automatically generates CLI and configuration reference documentation
 | ---------------- | --------------------------------------------------------- | ------------------------------------------------- |
 | CLI Reference    | `packages/@lumenflow/cli/src/**`                          | `apps/docs/src/content/docs/reference/cli.mdx`    |
 | Config Reference | `packages/@lumenflow/core/src/lumenflow-config-schema.ts` | `apps/docs/src/content/docs/reference/config.mdx` |
+| MCP Reference    | `packages/@lumenflow/mcp/src/tools.ts`                    | `apps/docs/src/content/docs/reference/mcp.mdx`    |
+
+## Example Tagging Conventions
+
+Docs example parity now distinguishes between copy-paste workflow examples and illustrative
+snippets:
+
+- `<!-- lumenflow-example: strict -->` marks a code block as a copy-paste example. Use this when
+  the block is intended to reflect the current command surface and full workflow ordering.
+- `<!-- lumenflow-example: illustrative -->` marks a block as explanatory only. It is still
+  scanned for obvious command drift where practical, but it is excluded from strict workflow checks
+  such as `wu:claim` → `wu:brief` → `wu:prep` → `wu:done`.
+- `<!-- lumenflow-example: historical -->`, `legacy`, and `placeholder` are reserved for
+  compatibility, migration, or incomplete examples that intentionally do not match the current
+  live command surface.
+- Strict CLI shell examples are additionally validated against the live `pnpm <command> --help`
+  surface for each referenced public command. Unknown flags, retired option names, and missing
+  required option values fail docs parity.
+- Strict YAML and JSON config examples are additionally validated against the live configuration
+  schemas. Unknown keys, invalid shapes, and stale config forms fail docs parity.
+- Strict MCP JSON payload examples with `"name"` and `"arguments"` are additionally validated
+  against the live MCP registry and the target tool's input schema. Required fields, enum values,
+  and payload shapes must all remain valid.
+
+Place the comment immediately above the fenced code block it applies to:
+
+````md
+<!-- lumenflow-example: illustrative -->
+
+```bash
+pnpm wu:status --id WU-123
+```
+````
+
+If no tag is present, shell code blocks are treated as illustrative by default. Add a `strict` tag
+whenever readers are expected to copy-paste a current workflow or command sequence.
+
+For strict CLI examples, prefer complete commands that reflect the live flag surface:
+
+````md
+<!-- lumenflow-example: strict -->
+
+```bash
+pnpm wu:create --lane "Framework: Core" --title "Add feature" \
+  --description "Context: ... Problem: ... Solution: ..." \
+  --acceptance "Criterion 1" \
+  --code-paths "src/file.ts" \
+  --test-paths-unit "src/__tests__/file.test.ts" \
+  --exposure backend-only
+```
+````
+
+For strict config examples, prefer a real schema-backed snippet instead of pseudocode:
+
+````md
+<!-- lumenflow-example: strict -->
+
+```yaml
+software_delivery:
+  gates:
+    minCoverage: 90
+```
+````
+
+For MCP payload examples, prefer:
+
+````md
+<!-- lumenflow-example: strict -->
+
+```json
+{
+  "name": "wu_status",
+  "arguments": {
+    "id": "WU-1234"
+  }
+}
+```
+````
+
+Use `illustrative` when a payload is intentionally partial or schematic and should not be enforced
+against the full schema.
 
 ---
 
@@ -117,8 +198,9 @@ This runs `tools/generate-cli-docs.ts` which:
 1. Extracts command metadata from CLI package.json bin entries
 2. Imports WU_OPTIONS from `@lumenflow/core` for option definitions
 3. Extracts config schemas using Zod 4's native `toJSONSchema()`
-4. Generates MDX files with tables and code blocks
-5. Formats output with Prettier
+4. Reads the built MCP tool registry from `packages/@lumenflow/mcp/dist/tools.js`
+5. Generates MDX files with tables and code blocks
+6. Formats output with Prettier
 
 ### Validate Documentation
 
@@ -149,7 +231,8 @@ The generator is integrated into Turbo for caching:
   ],
   "outputs": [
     "apps/docs/src/content/docs/reference/cli.mdx",
-    "apps/docs/src/content/docs/reference/config.mdx"
+    "apps/docs/src/content/docs/reference/config.mdx",
+    "apps/docs/src/content/docs/reference/mcp.mdx"
   ]
 }
 ```
@@ -164,7 +247,7 @@ The generator is integrated into Turbo for caching:
 
 ## Output Files
 
-The generator produces two MDX files:
+The generator produces three MDX files:
 
 ### CLI Reference (`cli.mdx`)
 
@@ -180,6 +263,13 @@ The generator produces two MDX files:
 - Environment variable overrides documented
 - Validation command shown
 
+### MCP Reference (`mcp.mdx`)
+
+- Generated from the live MCP tool registry in `packages/@lumenflow/mcp/src/tools.ts`
+- Category counts derived from the registered tool set at generation time
+- Per-tool headings and input parameter tables generated from tool schemas
+- Validation fails if the committed MCP reference drifts from the registry
+
 ---
 
 ## Adding New CLI Commands

package/templates/core/ai/onboarding/first-15-mins.md.template

@@ -10,7 +10,7 @@ A fast start for agents entering an existing LumenFlow project.
 
 ```bash
 ls LUMENFLOW.md AGENTS.md workspace.yaml
-pnpm exec lumenflow doctor
+pnpm lumenflow:doctor
 ```
 
 If the doctor reports a repo-level problem, stop there and fix it before claiming work.

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

@@ -22,6 +22,7 @@ git push origin main
 ```bash
 # Claim first, then work in worktree
 pnpm wu:claim --id WU-123 --lane Core
+pnpm wu:brief --id WU-123 --client <client>
 cd worktrees/core-wu-123
 vim src/feature.ts
 git commit -m "feat: add feature"
@@ -330,7 +331,7 @@ sizing_estimate:
   strategy: checkpoint-resume
 ```
 
-3. **Split the WU** only if the work is no longer atomic or should land independently (see [wu-sizing-guide.md](../../wu-sizing-guide.md) section 3 for splitting patterns).
+3. **Split the WU** only if the work is no longer atomic or should land independently (see [wu-sizing-guide.md](./wu-sizing-guide.md) section 3 for splitting patterns).
 
 **Strict mode:** Teams can enforce sizing compliance for delegated work with `--strict-sizing` on `wu:brief`. In strict mode, missing or non-compliant sizing metadata blocks the operation.
 

package/templates/core/ai/onboarding/initiative-orchestration.md.template

@@ -45,7 +45,7 @@ Before accepting the wave plan, sanity-check the decomposition. If several WUs s
 | Checkpoint-per-wave   | `pnpm orchestrate:initiative -i INIT-XXX -c`         | Large initiatives (>3 WUs or >2 waves) |
 | Continuous            | `pnpm orchestrate:initiative -i INIT-XXX`            | Small initiatives (<=3 WUs, 1-2 waves) |
 | Manual brief/delegate | `pnpm wu:brief --id WU-XXX --client <client>` per WU | Testing individual WUs, debugging      |
-| Manual self-implement | `pnpm wu:brief --id WU-XXX --client <client>` per WU | Self-implementation (records evidence) |
+| Manual self-implement | `pnpm wu:brief --id WU-XXX --client <client>` per WU | You are implementing without sub-agent |
 
 Checkpoint-per-wave is recommended for most initiatives. It processes one wave at a time and writes a manifest before exiting, giving you control between waves.
 
@@ -61,8 +61,6 @@ pnpm wu:brief --id WU-100 --client claude-code
 pnpm wu:delegate --id WU-100 --parent-wu WU-050 --client claude-code
 ```
 
-`wu:brief` always outputs full WU context AND records evidence. Use it for both delegation and self-implementation.
-
 **Use `wu:delegate` (not `wu:brief`) when:**
 
 - You are the orchestrator agent managing the initiative
@@ -75,6 +73,8 @@ pnpm wu:delegate --id WU-100 --parent-wu WU-050 --client claude-code
 - You still need `wu:brief` evidence for `wu:done` policy
 - You will implement directly in the current session
 
+`wu:brief` always outputs full WU context and records evidence in a single step. There is no separate evidence-only mode.
+
 **Verification checklist before spawning:**
 
 1. The generated prompt ends with `<!-- LUMENFLOW_SPAWN_END -->`
@@ -270,7 +270,7 @@ pnpm wu:brief --id WU-100 --client claude-code
 pnpm orchestrate:monitor  # Shows "Zombie lock (PID XXXXX not running)"
 
 # 2. Unlock the lane
-pnpm lane:unlock "Framework: Core" --reason "Zombie lock (PID 12345 not running)"
+pnpm wu:unlock-lane --lane "Framework: Core" --reason "Zombie lock (PID 12345 not running)"
 
 # 3. Release and re-claim the WU
 pnpm wu:release --id WU-100
@@ -375,23 +375,23 @@ pnpm delegation:list --initiative INIT-XXX --json
 
 ## Quick Reference: All Orchestration Commands
 
-| Command                                             | Description                                                   |
-| --------------------------------------------------- | ------------------------------------------------------------- |
-| `pnpm orchestrate:initiative -i INIT-XXX --dry-run` | Preview wave plan without executing                           |
-| `pnpm orchestrate:initiative -i INIT-XXX -c`        | Execute one wave then checkpoint and exit                     |
-| `pnpm orchestrate:initiative -i INIT-XXX`           | Execute all waves continuously                                |
-| `pnpm orchestrate:init-status -i INIT-XXX`          | Compact progress view                                         |
-| `pnpm orchestrate:monitor`                          | Detect stuck agents and zombie locks                          |
-| `pnpm wu:brief --id WU-XXX --client <client>`       | **MANDATORY after wu:claim.** Generate prompt + evidence      |
-| `pnpm wu:delegate --id WU-XXX --parent-wu <P>`      | Generate prompt + record delegation                           |
-| `pnpm delegation:list --initiative INIT-XXX`        | View delegation tree                                          |
-| `pnpm mem:signal "msg" --wu WU-XXX`                 | Broadcast coordination signal                                 |
-| `pnpm mem:inbox --since <duration>`                 | Read coordination signals                                     |
-| `pnpm mem:checkpoint "msg" --wu WU-XXX`             | Save progress checkpoint                                      |
-| `pnpm mem:ready --wu WU-XXX`                        | Check pending work/checkpoints                                |
-| `pnpm wu:block --id WU-XXX --reason "..."`          | Block stuck WU                                                |
-| `pnpm wu:unblock --id WU-XXX`                       | Unblock recovered WU                                          |
-| `pnpm wu:release --id WU-XXX`                       | Release abandoned WU for re-claim                             |
+| Command                                             | Description                                              |
+| --------------------------------------------------- | -------------------------------------------------------- |
+| `pnpm orchestrate:initiative -i INIT-XXX --dry-run` | Preview wave plan without executing                      |
+| `pnpm orchestrate:initiative -i INIT-XXX -c`        | Execute one wave then checkpoint and exit                |
+| `pnpm orchestrate:initiative -i INIT-XXX`           | Execute all waves continuously                           |
+| `pnpm orchestrate:init-status -i INIT-XXX`          | Compact progress view                                    |
+| `pnpm orchestrate:monitor`                          | Detect stuck agents and zombie locks                     |
+| `pnpm wu:brief --id WU-XXX --client <client>`       | **MANDATORY after wu:claim.** Generate prompt + evidence |
+| `pnpm wu:delegate --id WU-XXX --parent-wu <P>`      | Generate prompt + record delegation                      |
+| `pnpm delegation:list --initiative INIT-XXX`        | View delegation tree                                     |
+| `pnpm mem:signal "msg" --wu WU-XXX`                 | Broadcast coordination signal                            |
+| `pnpm mem:inbox --since <duration>`                 | Read coordination signals                                |
+| `pnpm mem:checkpoint "msg" --wu WU-XXX`             | Save progress checkpoint                                 |
+| `pnpm mem:ready --wu WU-XXX`                        | Check pending work/checkpoints                           |
+| `pnpm wu:block --id WU-XXX --reason "..."`          | Block stuck WU                                           |
+| `pnpm wu:unblock --id WU-XXX`                       | Unblock recovered WU                                     |
+| `pnpm wu:release --id WU-XXX`                       | Release abandoned WU for re-claim                        |
 
 ---
 

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

@@ -56,25 +56,25 @@ Run `--help` first, then run the real command with explicit flags.
 
 **For this monorepo (development):**
 
-| Command                                            | Description                                                    |
-| -------------------------------------------------- | -------------------------------------------------------------- |
-| `pnpm setup`                                       | Install deps and build CLI (first time)                        |
-| `pnpm bootstrap`                                   | Build CLI with dependency closure (worktree-safe)              |
-| `pnpm build`                                       | Build all packages                                             |
-| `pnpm build:dist`                                  | Build distribution packages                                    |
-| `pnpm dev`                                         | Start development mode                                         |
-| `pnpm clean`                                       | Clean build artifacts and caches                               |
-| `pnpm pack:all`                                    | Pack all packages for distribution                             |
-| `pnpm exec lumenflow init`                         | Scaffold LumenFlow in a project                                |
-| `pnpm exec lumenflow init --docs-structure simple` | Use simple docs structure (`docs/tasks`)                       |
-| `pnpm exec lumenflow init --docs-structure arc42`  | Use arc42 docs structure (`{{DOCS_OPERATIONS_PATH}}`)                |
-| `pnpm docs:sync --vendor <type>`                  | Refresh selected vendor bootstrap assets outside upgrade |
-| `pnpm sync:templates`                              | Sync repo docs into bundled templates                          |
-| `pnpm lumenflow:upgrade`                           | Upgrade LumenFlow packages                                     |
-| `pnpm lumenflow:doctor`                            | Diagnose LumenFlow configuration                               |
-| `pnpm lumenflow:integrate`                         | Generate enforcement hooks for client                          |
-| `pnpm cloud:connect`                               | Configure cloud control-plane access                           |
-| `npx lumenflow commands`                           | List all available CLI commands                                |
+| Command                                  | Description                                                                             |
+| ---------------------------------------- | --------------------------------------------------------------------------------------- |
+| `pnpm setup`                             | Install deps and build CLI (first time)                                                 |
+| `pnpm bootstrap`                         | Build CLI with dependency closure (worktree-safe)                                       |
+| `pnpm build`                             | Build all packages                                                                      |
+| `pnpm build:dist`                        | Build distribution packages                                                             |
+| `pnpm dev`                               | Start development mode                                                                  |
+| `pnpm clean`                             | Clean build artifacts and caches                                                        |
+| `pnpm pack:validate`                     | Validate a pack manifest and implementation surface                                     |
+| `pnpm lumenflow`                         | Scaffold LumenFlow in a project                                                         |
+| `pnpm lumenflow --docs-structure simple` | Use simple docs structure (`docs/tasks`)                                                |
+| `pnpm lumenflow --docs-structure arc42`  | Use arc42 docs structure (`{{DOCS_OPERATIONS_PATH}}`)                                            |
+| `pnpm docs:sync`                         | Refresh managed docs, onboarding docs, and vendor assets (run by upgrade automatically) |
+| `pnpm sync:templates`                    | Sync repo docs into bundled templates                                                   |
+| `pnpm lumenflow:upgrade`                 | Upgrade LumenFlow packages                                                              |
+| `pnpm lumenflow:doctor`                  | Diagnose LumenFlow configuration                                                        |
+| `pnpm lumenflow:integrate`               | Generate enforcement hooks for client                                                   |
+| `pnpm cloud:connect`                     | Configure cloud control-plane access                                                    |
+| `npx lumenflow commands`                 | List all available CLI commands                                                         |
 
 **For external projects (end users):**
 
@@ -83,12 +83,12 @@ Run `--help` first, then run the real command with explicit flags.
 pnpm add -D @lumenflow/cli  # or: npm install -D @lumenflow/cli
 
 # Initialize LumenFlow
-pnpm exec lumenflow init
+pnpm lumenflow
 
 # With client-specific overlays
-pnpm exec lumenflow init --client claude   # Claude Code
-pnpm exec lumenflow init --client cursor   # Cursor IDE
-pnpm exec lumenflow init --client all      # All clients
+pnpm lumenflow --client claude   # Claude Code
+pnpm lumenflow --client cursor   # Cursor IDE
+pnpm lumenflow --client all      # All clients
 ```
 
 ---
@@ -98,30 +98,29 @@ pnpm exec lumenflow init --client all      # All clients
 These commands use **micro-worktree isolation** internally — they handle their own
 commit and push atomically. Do NOT wrap them in a WU or use raw `pnpm update`/`git commit`.
 
-| Command                                           | Description                                      |
-| ------------------------------------------------- | ------------------------------------------------ |
-| `pnpm lumenflow:upgrade --version 3.5.0`          | Upgrade all 7 @lumenflow/\* packages             |
-| `pnpm lumenflow:upgrade --latest`                 | Upgrade to latest version                        |
-| `pnpm lumenflow:upgrade --latest --dry-run`       | Preview upgrade without executing                |
-| `pnpm config:set --key <dotpath> --value <value>` | Set workspace.yaml config (Zod-validated)        |
-| `pnpm config:get --key <dotpath>`                 | Read workspace.yaml config                       |
-| `pnpm cloud:connect`                              | Configure cloud control-plane access             |
-| `pnpm docs:sync --vendor <type>`                 | Optional targeted refresh for vendor/bootstrap assets |
-| `pnpm sync:templates`                             | Sync repo docs into bundled templates            |
+| Command                                           | Description                                                           |
+| ------------------------------------------------- | --------------------------------------------------------------------- |
+| `pnpm lumenflow:upgrade --version 3.5.0`          | Upgrade all 7 @lumenflow/\* packages                                  |
+| `pnpm lumenflow:upgrade --latest`                 | Upgrade to latest version                                             |
+| `pnpm lumenflow:upgrade --latest --dry-run`       | Preview upgrade without executing                                     |
+| `pnpm config:set --key <dotpath> --value <value>` | Set workspace.yaml config (Zod-validated)                             |
+| `pnpm config:get --key <dotpath>`                 | Read workspace.yaml config                                            |
+| `pnpm cloud:connect`                              | Configure cloud control-plane access                                  |
+| `pnpm docs:sync`                                  | Refresh managed docs, onboarding docs, and vendor assets (standalone) |
+| `pnpm sync:templates`                             | Sync repo docs into bundled templates                                 |
 
 **Key principle:** If a LumenFlow CLI command exists for the operation, use it instead of
 raw pnpm/git. These tooling commands commit directly to main via micro-worktree — no dirty
 files, no manual git, no WU ceremony. Only actual **code changes** need WUs.
 
-`docs:sync` refreshes managed docs, the scaffolded onboarding set, and selected vendor bootstrap
-assets. Managed docs are refreshed automatically during `pnpm lumenflow:upgrade --latest`, and
-bootstrap files update safely via merge-block markers.
+`lumenflow:upgrade` runs `docs:sync` internally as part of the upgrade transaction. You do not
+need to run `docs:sync` separately after upgrading. Standalone `docs:sync` is only needed when
+you want to refresh docs without upgrading packages (e.g., after manually editing templates).
 
-For existing installs, upgrade packages first with `pnpm lumenflow:upgrade --latest`. That command
-automatically syncs managed docs, onboarding docs, and configured vendor assets. Use
-`pnpm docs:sync --vendor <type>` only when you want an additional targeted refresh outside upgrade.
-The improved default `wu:brief` behavior comes from the package upgrade itself. New installs get
-those defaults automatically, and `.lumenflow/templates/` remains optional unless you want custom overrides.
+`docs:sync` handles two categories of files:
+
+- **Managed docs** (`LUMENFLOW.md`, `.lumenflow/constraints.md`) — always force-synced from templates
+- **Bootstrap docs** (`AGENTS.md`, vendor files) — merge-block update only (user content outside `LUMENFLOW:START`/`END` markers is preserved)
 
 > **Anti-pattern:** Do NOT use `pnpm update @lumenflow/*` to upgrade packages.
 > This leaves dirty `package.json` and `pnpm-lock.yaml` on main.
@@ -131,70 +130,84 @@ those defaults automatically, and `.lumenflow/templates/` remains optional unles
 
 ## WU Lifecycle
 
-| 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:escalate --id WU-XXX`                                 | Show escalation status for a WU                                       |
-| `pnpm wu:escalate --resolve --id WU-XXX`                       | Resolve escalation (sets resolved_by/resolved_at)                     |
-| `pnpm approval:request --type <type> --subject <json>`         | Request control-plane approval for an action                          |
-| `pnpm approval:review --id <approvalId> --decision <decision>` | Resolve an approval decision (`approved`/`rejected`/`expired`)        |
-| `pnpm approval:list [--status <status>]`                       | List approvals with optional status/type filters                      |
-| `pnpm wu:block --id WU-XXX --reason "..."`                     | Block WU with reason                                                  |
-| `pnpm wu:unblock --id WU-XXX`                                  | Unblock WU                                                            |
-| `pnpm wu:release --id WU-XXX`                                  | Release orphaned WU (in_progress to ready)                            |
-| `pnpm wu:status --id WU-XXX`                                   | Show WU status, location, valid commands                              |
-| `pnpm wu:brief --id WU-XXX --client <client>`                  | **MANDATORY after wu:claim.** Generate handoff prompt + record evidence. wu:done blocks without this |
-| `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, record lineage, and store brief hash attestation     |
-| `pnpm wu:sandbox --id WU-XXX -- <cmd>`                         | Run command through hardened WU sandbox backend                       |
+| 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:escalate --id WU-XXX`                                 | Show escalation status for a WU                                                                                |
+| `pnpm wu:escalate --resolve --id WU-XXX`                       | Resolve escalation (sets resolved_by/resolved_at)                                                              |
+| `pnpm approval:request --type <type> --subject <json>`         | Request control-plane approval for an action                                                                   |
+| `pnpm approval:review --id <approvalId> --decision <decision>` | Resolve an approval decision (`approved`/`rejected`/`expired`)                                                 |
+| `pnpm approval:list [--status <status>]`                       | List approvals with optional status/type filters                                                               |
+| `pnpm wu:block --id WU-XXX --reason "..."`                     | Block WU with reason (ownership-guarded, v3.19.0)                                                              |
+| `pnpm wu:unblock --id WU-XXX`                                  | Unblock WU (ownership-guarded, v3.19.0)                                                                        |
+| `pnpm wu:release --id WU-XXX --reason "..."`                   | Release orphaned WU (ownership-guarded, v3.19.0)                                                               |
+| `pnpm wu:status --id WU-XXX`                                   | Show WU status, location, valid commands                                                                       |
+| `pnpm wu:brief --id WU-XXX --client <client>`                  | **MANDATORY after wu:claim.** Generate handoff prompt + record evidence. wu:done blocks without this (WU-2379) |
+| `pnpm wu:brief --id WU-XXX --no-context`                       | Generate prompt without memory context injection                                                               |
+| `pnpm wu:delegate --id WU-XXX --parent-wu <P>`                 | Generate prompt, record lineage, and store brief hash attestation                                              |
+| `pnpm wu:sandbox --id WU-XXX -- <cmd>`                         | Run command through hardened WU sandbox backend                                                                |
 
 ### WU Maintenance
 
-| Command                          | Description                                      |
-| -------------------------------- | ------------------------------------------------ |
-| `pnpm wu:validate --id WU-XXX`   | Validate WU spec                                 |
-| `pnpm wu:preflight --id WU-XXX`  | Pre-flight checks before wu:done                 |
-| `pnpm wu:verify --id WU-XXX`     | Verify WU completion (stamp, commit, clean tree) |
-| `pnpm wu:recover --id WU-XXX`    | Analyze and fix WU state inconsistencies         |
-| `pnpm wu:repair --id WU-XXX`     | Repair WU state issues                           |
-| `pnpm wu:prune`                  | Clean stale worktrees                            |
-| `pnpm wu:cleanup --id WU-XXX`    | Cleanup after PR merge (PR-only)                 |
-| `pnpm wu:deps --id WU-XXX`       | Show WU dependencies                             |
-| `pnpm wu:infer-lane --id WU-XXX` | Infer lane from code paths/description           |
-| `pnpm wu:delete --id WU-XXX`     | Delete WU spec and cleanup                       |
-| `pnpm wu:unlock-lane --lane <L>` | Unlock stuck lane                                |
-| `pnpm wu:proto --lane <Lane>`    | Create WU prototype (lightweight draft)          |
+| Command                          | Description                                           |
+| -------------------------------- | ----------------------------------------------------- |
+| `pnpm wu:validate --id WU-XXX`   | Validate WU spec                                      |
+| `pnpm wu:preflight --id WU-XXX`  | Pre-flight checks before wu:done                      |
+| `pnpm wu:verify --id WU-XXX`     | Verify WU completion (stamp, commit, clean tree)      |
+| `pnpm wu:recover --id WU-XXX`    | Analyze and fix WU state (ownership-guarded, v3.19.0) |
+| `pnpm wu:repair --id WU-XXX`     | Repair WU state issues                                |
+| `pnpm wu:prune`                  | Clean stale worktrees                                 |
+| `pnpm wu:cleanup --id WU-XXX`    | Cleanup after PR merge (PR-only)                      |
+| `pnpm wu:deps --id WU-XXX`       | Show WU dependencies                                  |
+| `pnpm wu:infer-lane --id WU-XXX` | Infer lane from code paths/description                |
+| `pnpm wu:delete --id WU-XXX`     | Delete WU spec and cleanup                            |
+| `pnpm wu:unlock-lane --lane <L>` | Unlock stuck lane                                     |
+| `pnpm wu:proto --lane <Lane>`    | Create WU prototype (lightweight draft)               |
+
+**Ownership guards (v3.19.0, WU-2468):** `wu:block`, `wu:unblock`, `wu:release`, and `wu:recover`
+validate session ownership before state mutations. If the WU belongs to another session, use
+`--override-owner --reason "..."` to override (audited). **AGENTS: NEVER use --override-owner
+without explicit human instruction.**
 
 ---
 
 ## Gates & Quality
 
-| Command                                           | Description                                     |
-| ------------------------------------------------- | ----------------------------------------------- |
-| `pnpm gates`                                      | Run all quality gates                           |
-| `pnpm gates --docs-only`                          | Run gates for docs changes                      |
-| `pnpm format`                                     | Format all files (Prettier)                     |
-| `pnpm format:check`                               | Check formatting without changes                |
-| `pnpm lint`                                       | Run ESLint                                      |
-| `pnpm typecheck`                                  | Run TypeScript type checking                    |
-| `pnpm test`                                       | Run all tests (Vitest)                          |
-| `pnpm spec:linter`                                | Validate WU specs (all) ¹                       |
-| `pnpm lane:health`                                | Check lane config health                        |
-| `pnpm lane:suggest --output workspace.lanes.yaml` | Generate a workspace lane-definition snippet    |
-| `pnpm lane:status`                                | Show lane lifecycle status                      |
-| `pnpm lane:setup`                                 | Create/update draft lane config                 |
-| `pnpm lane:validate`                              | Validate lane draft artifacts                   |
-| `pnpm lane:lock`                                  | Lock lane lifecycle for WU create               |
-| `pnpm lane:edit --name <L>`                       | Edit lane definition (rename, wip-limit, paths) |
+| 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)    |
 
 ¹ **Script aliases:** `spec:linter` and `tasks:validate` are pnpm script aliases
 for `wu:validate --all`. They are not standalone CLI commands.
 
+**Conditional gates (v3.19.0, WU-2448):** Define pattern-triggered commands in
+`workspace.yaml > software_delivery.gates.conditional_commands`. Commands with `trigger_patterns`
+only run when matching files change. Supports `error` (blocks), `warn` (logs), and `off` (skip)
+severity levels. See workspace-spec.mdx for schema.
+
 **Formatting: always scope to changed files only.**
 Use `pnpm prettier --write <changed-files...>` — never unscoped `pnpm format`.
 Running `pnpm format` reformats every file in the repo, creating hundreds of
@@ -327,18 +340,18 @@ If the plan exists only in conversation, use `--plan` on `wu:create` to generate
 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                                                         |
-| ------------------------------------------------------------------------ | ------------------------------------------------------------------- |
-| `pnpm plan:create --id INIT-XXX --title "..."`                           | Create a repo-native plan file in configured `directories.plansDir` |
-| `pnpm plan:create --id INIT-XXX --title "..." --from <path>`             | Import external plan file into repo plansDir                        |
+| Command                                                                       | Description                                                         |
+| ----------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `pnpm plan:create --id INIT-XXX --title "..."`                                | Create a repo-native plan file in configured `directories.plansDir` |
+| `pnpm plan:create --id INIT-XXX --title "..." --from <path>`                  | Import external plan file into repo plansDir                        |
 | `pnpm plan:edit --id INIT-XXX --section Goal --content "..."`                 | Edit plan section (auto-resolves file from initiative metadata)     |
-| `pnpm plan:edit --id WU-XXX --file my-plan.md --section Goal --content "..."` | Edit plan by explicit filename                                     |
-| `pnpm plan:link --id INIT-XXX --plan lumenflow://plans/INIT-XXX-plan.md`      | Link plan URI to initiative or WU                                  |
-| `pnpm plan:promote --id INIT-XXX`                                             | Promote plan to approved (auto-resolves from initiative metadata)  |
-| `pnpm plan:promote --id WU-XXX --file my-plan.md`                             | Promote plan by explicit filename                                  |
-| `pnpm initiative:plan --initiative INIT-XXX --plan <path>`               | Link plan to initiative (auto-imports external files into repo)     |
-| `pnpm initiative:plan --initiative INIT-XXX --create`                    | Create blank plan template and link to initiative                   |
-| `pnpm initiative:plan --initiative INIT-XXX --create --plan <path>`      | Import external plan content into new template and link             |
+| `pnpm plan:edit --id WU-XXX --file my-plan.md --section Goal --content "..."` | Edit plan by explicit filename                                      |
+| `pnpm plan:link --id INIT-XXX --plan lumenflow://plans/INIT-XXX-plan.md`      | Link plan URI to initiative or WU                                   |
+| `pnpm plan:promote --id INIT-XXX`                                             | Promote plan to approved (auto-resolves from initiative metadata)   |
+| `pnpm plan:promote --id WU-XXX --file my-plan.md`                             | Promote plan by explicit filename                                   |
+| `pnpm initiative:plan --initiative INIT-XXX --plan <path>`                    | Link plan to initiative (auto-imports external files into repo)     |
+| `pnpm initiative:plan --initiative INIT-XXX --create`                         | Create blank plan template and link to initiative                   |
+| `pnpm initiative:plan --initiative INIT-XXX --create --plan <path>`           | Import external plan content into new template and link             |
 
 ### Linking Plans
 
@@ -544,6 +557,8 @@ pnpm gates              # Now works
 
 ## Workflow Sequence (Quick Reference)
 
+<!-- lumenflow-example: strict -->
+
 ```bash
 # 0. Check available options (do this before first use of any command)
 pnpm wu:create --help
@@ -559,6 +574,7 @@ pnpm wu:create --lane "Framework: Core" --title "Add feature" \
 
 # 2. Claim (creates worktree) -- use the ID from wu:create output
 pnpm wu:claim --id WU-1990 --lane "Framework: Core"
+pnpm wu:brief --id WU-1990 --client <client>
 cd worktrees/framework-core-wu-1990
 
 # 2b. Bootstrap (build CLI for dist-backed commands)
@@ -727,13 +743,13 @@ When `requireRemote: true` (default):
 
 ## Key File Paths
 
-| Path                                      | Description          |
-| ----------------------------------------- | -------------------- |
+| Path                                   | Description          |
+| -------------------------------------- | -------------------- |
 | `{{DOCS_TASKS_PATH}}/wu/WU-XXX.yaml` | WU specification     |
 | `{{DOCS_TASKS_PATH}}/status.md`      | Current status board |
 | `{{DOCS_TASKS_PATH}}/backlog.md`     | Backlog summary      |
-| `.lumenflow/stamps/WU-XXX.done`           | Completion stamp     |
-| `worktrees/<lane>-wu-xxx/`                | Worktree directory   |
+| `.lumenflow/stamps/WU-XXX.done`        | Completion stamp     |
+| `worktrees/<lane>-wu-xxx/`             | Worktree directory   |
 
 ---
 
@@ -772,6 +788,7 @@ For cloud agents that cannot use local worktrees:
 # 1. Claim in cloud mode
 pnpm wu:claim --id WU-XXX --lane "<Lane>" --cloud
 # Or: LUMENFLOW_CLOUD=1 pnpm wu:claim --id WU-XXX --lane "<Lane>"
+pnpm wu:brief --id WU-XXX --client <client>
 
 # 2. Work on lane branch, push commits
 
@@ -835,4 +852,4 @@ For a complete picture of how all WU commands, memory tools, and orchestration t
 - **[Failure-Mode Runbook](../../lumenflow-agent-capsule.md)** -- Concrete remediation for main-behind-origin, partial-claim state, spawn-provenance enforcement, and wu:recover usage
 - **[Troubleshooting wu:done](./troubleshooting-wu-done.md)** -- Most common agent mistake (two-step wu:prep + wu:done workflow)
 - **[First WU Mistakes](./first-wu-mistakes.md)** -- Common first-time pitfalls and how to avoid them
-- **[WU Sizing Guide](../../wu-sizing-guide.md)** -- Context safety triggers, complexity assessment, and session strategies
+- **[WU Sizing Guide](./wu-sizing-guide.md)** -- Context safety triggers, complexity assessment, and session strategies