@lumenflow/cli 2.8.0 → 2.10.0

package/templates/core/LUMENFLOW.md.template

@@ -53,6 +53,30 @@ cd /path/to/main && pnpm wu:done --id WU-XXXX
 
 ---
 
+## When to Use Initiatives
+
+Use **Initiatives** for multi-phase work spanning multiple WUs:
+
+- **Product visions**: "Build a task management app"
+- **Larger features**: Work requiring multiple WUs across lanes
+- **Complex projects**: Anything that needs phased delivery
+
+```bash
+# Create an initiative for multi-phase work
+pnpm initiative:create --id INIT-001 --title "Feature Name" \
+  --description "..." --phase "Phase 1: MVP" --phase "Phase 2: Polish"
+
+# Add WUs to the initiative
+pnpm initiative:add-wu --initiative INIT-001 --wu WU-XXX --phase 1
+
+# Track progress
+pnpm initiative:status --id INIT-001
+```
+
+**Skip initiatives** for: single-file bug fixes, small docs updates, isolated refactoring.
+
+---
+
 ## Setup Notes (Common First-Run Failures)
 
 ### Lane inference (sub-lanes)

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

@@ -224,6 +224,53 @@ pnpm prettier --write <files>  # Safe in worktree
 
 ---
 
+## Mistake 12: Not Acting on Implied Directives
+
+### Wrong
+
+```text
+Agent: [presents research findings about a bug]
+User: "so update 1348 then?"
+Agent: [no response or asks "should I update it?"]
+```
+
+### Right
+
+```text
+Agent: [presents research findings about a bug]
+User: "so update 1348 then?"
+Agent: Updating WU-1348 with these findings now.
+[Edits the WU YAML file]
+```
+
+### How to Update a WU
+
+**Option 1: CLI command**
+
+```bash
+pnpm wu:edit --id WU-1348 --notes "Research findings: ..."
+```
+
+**Option 2: Direct file edit**
+
+```bash
+# Edit docs/04-operations/tasks/wu/WU-1348.yaml directly
+```
+
+### Recognizing Implied Directives
+
+Phrases that mean "do this now":
+
+- "so do X then?" / "so X then?"
+- "update that" / "add that"
+- "fix it" / "make that change"
+- "go ahead" / "proceed"
+- "sounds good, do it"
+
+**Rule:** Information + user confirmation = immediate action. Don't ask "should I proceed?" when user already implied yes.
+
+---
+
 ## Quick Checklist
 
 Before starting any WU:

package/templates/core/ai/onboarding/lumenflow-force-usage.md.template

@@ -0,0 +1,183 @@
+# LUMENFLOW_FORCE Usage Investigation
+
+**Last updated:** {{DATE}}
+
+This document presents the findings from WU-1220, investigating improper LUMENFLOW_FORCE usage in agent sessions and providing prevention recommendations.
+
+---
+
+## Executive Summary
+
+Analysis of `.beacon/force-bypasses.log` reveals that LUMENFLOW_FORCE is used extensively, but almost exclusively by human operators (user "Tom") rather than AI agents. The vast majority of uses are for legitimate infrastructure operations such as:
+
+- Release version pushes
+- Micro-worktree recovery operations
+- State synchronization
+- Emergency fixes
+
+**Key Finding:** AI agents are NOT the primary concern. The existing safeguards (documentation, audit logging) are working as designed. The force bypass mechanism serves its intended purpose: enabling humans to perform legitimate administrative operations while maintaining an audit trail.
+
+---
+
+## Root Cause Analysis
+
+### Observations from Audit Log
+
+Analysis of 347 logged bypass events shows:
+
+| Category              | Count | Description                                     |
+| --------------------- | ----- | ----------------------------------------------- |
+| Release operations    | ~45   | Pushing version tags, npm releases              |
+| Infrastructure repair | ~100  | wu:claim auto-repair, micro-worktree recovery   |
+| State sync            | ~80   | Syncing repair commits, pushing orphan repairs  |
+| Emergency fixes       | ~30   | P0 fixes, backlog corruption recovery           |
+| No reason provided    | ~90   | Human operations without LUMENFLOW_FORCE_REASON |
+
+### Log Entry Patterns
+
+**Legitimate human operations:**
+
+```
+{{DATE}}T14:08:55.172Z | pre-push | Tom | main | release v1.6.0 | {{PROJECT_ROOT}}
+{{DATE}}T10:41:23.185Z | pre-push | Tom | main | Recovery: wu:done partially completed, merging remaining changes
+```
+
+**Missing reason (human oversight, not agent misuse):**
+
+```
+{{DATE}}T11:52:15.459Z | pre-commit | Tom | main | (no reason provided)
+```
+
+### Why Agents Are Not The Problem
+
+1. **Agents follow documented rules:** The constraints.md and agent-safety-card.md clearly state that agents MUST NOT use LUMENFLOW_FORCE without explicit user approval.
+
+2. **Hooks block direct commits:** The pre-commit hook blocks WU commits from main, forcing agents through the proper worktree workflow.
+
+3. **Most bypasses are push operations:** The audit log shows ~70% of bypasses are `pre-push` hooks, which are typically administrative operations (releases, repairs) performed by humans.
+
+4. **No evidence of agent abuse:** None of the logged entries indicate an AI agent autonomously using LUMENFLOW_FORCE to skip tests or avoid gates.
+
+---
+
+## Current Safeguards
+
+### Documentation Safeguards
+
+1. **constraints.md** (Section 7): "AI agents MUST NOT use LUMENFLOW_FORCE without explicit user approval"
+
+2. **agent-safety-card.md**: Complete section on "Emergency Override (LUMENFLOW_FORCE)" with:
+   - When emergency override is appropriate
+   - When NOT to use emergency override
+   - Step-by-step escalation process
+   - Audit trail requirements
+
+3. **starting-prompt.md** (Rule 5): Explicit guidance on LUMENFLOW_FORCE usage
+
+### Technical Safeguards
+
+1. **Audit logging:** All bypasses logged to `.beacon/force-bypasses.log` with timestamp, hook, user, branch, reason, and working directory.
+
+2. **Warning when no reason:** If LUMENFLOW_FORCE_REASON is not provided, a warning is printed.
+
+3. **Git-tracked audit log:** The `.beacon/force-bypasses.log` file is version controlled, providing historical accountability.
+
+4. **Hook enforcement:** Pre-commit, commit-msg, pre-push, and prepare-commit-msg hooks all check for LUMENFLOW_FORCE before allowing bypass.
+
+---
+
+## Investigation Conclusion
+
+**The original concern ("agent used LUMENFLOW_FORCE to commit directly to main instead of using proper worktree workflow") appears to be unfounded based on audit log analysis.**
+
+The audit log shows:
+
+- All 347 bypass events were attributed to "Tom" (human operator)
+- No entries indicate AI agent autonomous bypass
+- Legitimate use cases: releases, repairs, emergency fixes, state sync
+
+If an agent did use LUMENFLOW_FORCE improperly, it would have been:
+
+1. Logged with the agent's session context
+2. Visible as a pattern of non-administrative bypasses
+3. Associated with test skipping or gate avoidance
+
+None of these patterns appear in the audit log.
+
+---
+
+## Prevention Recommendations
+
+Despite the finding that this is not currently a problem, the following recommendations strengthen the existing safeguards:
+
+### 1. Enhanced Audit Log Format (Low Effort)
+
+Add agent/session identification to bypass log entries:
+
+```
+# Current format:
+TIMESTAMP | HOOK | USER | BRANCH | REASON | CWD
+
+# Enhanced format:
+TIMESTAMP | HOOK | USER | BRANCH | REASON | CWD | SESSION_TYPE | SESSION_ID
+```
+
+Where `SESSION_TYPE` could be: `human`, `claude-code`, `cursor`, `windsurf`, `unknown`
+
+### 2. Periodic Audit Review (Process)
+
+Establish a monthly review of `.beacon/force-bypasses.log` to identify:
+
+- High volume of "no reason provided" entries
+- Unexpected patterns in bypass usage
+- Any entries that don't match expected administrative operations
+
+### 3. Agent Context Marker (Technical)
+
+When an agent uses LUMENFLOW_FORCE with approval, require the reason to include an agent marker:
+
+```bash
+# Require format for agent-initiated bypasses
+LUMENFLOW_FORCE_REASON="agent-approved: <reason>" LUMENFLOW_FORCE=1 git ...
+```
+
+This allows filtering agent bypasses from human bypasses in audit analysis.
+
+### 4. Real-Time Alert (Optional, Higher Effort)
+
+Add optional webhook/notification when LUMENFLOW_FORCE is used without a reason containing "release", "repair", "recovery", or "sync":
+
+```yaml
+# .lumenflow.config.yaml
+force_bypass:
+  alert_webhook: https://...
+  exempt_patterns:
+    - release
+    - repair
+    - recovery
+    - sync
+    - tag
+```
+
+---
+
+## Summary
+
+| Finding                            | Status                         |
+| ---------------------------------- | ------------------------------ |
+| AI agents misusing LUMENFLOW_FORCE | **Not observed**               |
+| Human administrative use           | Working as designed            |
+| Audit trail completeness           | Good, but ~26% missing reasons |
+| Documentation coverage             | Comprehensive                  |
+| Technical enforcement              | Effective                      |
+
+**Conclusion:** The existing LUMENFLOW_FORCE mechanism and its safeguards are functioning correctly. The concern that prompted this investigation was not validated by audit log evidence. The recommendations above are incremental improvements, not urgent fixes.
+
+---
+
+## Related Documents
+
+- [.lumenflow/constraints.md](../../../../../../.lumenflow/constraints.md) - Section 7: Agent LUMENFLOW_FORCE Usage Policy
+- [agent-safety-card.md](agent-safety-card.md) - Emergency Override section
+- [starting-prompt.md](starting-prompt.md) - Rule 5: Know When to Use LUMENFLOW_FORCE
+- [WU-1070](../../../../tasks/wu/WU-1070.yaml) - Original WU for LUMENFLOW_FORCE policy

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

@@ -4,32 +4,15 @@
 
 Complete reference for all CLI commands. Organized by category for quick discovery.
 
----
-
-## Quick Start (Essential Commands)
-
-Most common workflow in 4 commands:
-
-```bash
-# 1. Claim WU and create isolated workspace
-pnpm wu:claim --id WU-XXX --lane "Lane Name"
-cd worktrees/<lane>-wu-xxx
-
-# 2. Work in worktree, then run gates
-pnpm gates                    # For code changes
-pnpm gates --docs-only        # For documentation only
-
-# 3. Prepare for completion (from worktree)
-pnpm wu:prep --id WU-XXX
-
-# 4. Complete (from main - copy command from wu:prep output)
-cd /path/to/main && pnpm wu:done --id WU-XXX
-```
-
-**Key rules:**
-- Always work in worktrees, never on main
-- Always run `wu:done` to complete (not just documenting it)
-- Use `wu:prep` first (runs gates), then `wu:done` (merges)
+> **Tip (WU-1358):** For complete option lists, always run `<package_manager> <command> --help`.
+> This shows all available flags including inline options that may not appear in generated docs.
+>
+> ```bash
+> # Examples
+> pnpm wu:edit --help      # See all wu:edit options
+> npm run wu:claim -- --help
+> yarn wu:create --help
+> ```
 
 ---
 
@@ -37,19 +20,21 @@ cd /path/to/main && pnpm wu:done --id WU-XXX
 
 **For this monorepo (development):**
 
-| Command                  | Description                             |
-| ------------------------ | --------------------------------------- |
-| `pnpm setup`             | Install deps and build CLI (first time) |
-| `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 lumenflow:init`    | Scaffold LumenFlow in a project         |
-| `pnpm docs:sync`         | Sync agent docs (for upgrades)          |
-| `pnpm sync:templates`    | Sync templates to project               |
-| `pnpm lumenflow:upgrade` | Upgrade LumenFlow packages              |
-| `pnpm lumenflow:doctor`  | Diagnose LumenFlow configuration        |
+| Command                    | Description                             |
+| -------------------------- | --------------------------------------- |
+| `pnpm setup`               | Install deps and build CLI (first time) |
+| `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 lumenflow:init`      | Scaffold LumenFlow in a project         |
+| `pnpm docs:sync`           | Sync agent docs (for upgrades)          |
+| `pnpm sync:templates`      | Sync templates to project               |
+| `pnpm lumenflow:upgrade`   | Upgrade LumenFlow packages              |
+| `pnpm lumenflow:doctor`    | Diagnose LumenFlow configuration        |
+| `pnpm lumenflow:integrate` | Generate enforcement hooks for client   |
+| `pnpm lumenflow commands`  | List all available CLI commands         |
 
 **For external projects (end users):**
 
@@ -120,22 +105,23 @@ pnpm exec lumenflow --client all      # All clients
 
 ## Memory & Sessions
 
-| Command                             | Description                        |
-| ----------------------------------- | ---------------------------------- |
-| `pnpm mem:init --wu WU-XXX`         | Initialize memory for WU           |
-| `pnpm mem:start --wu WU-XXX`        | Start a memory session             |
-| `pnpm mem:checkpoint --wu WU-XXX`   | Save progress checkpoint           |
-| `pnpm mem:ready --wu WU-XXX`        | Check pending nodes                |
-| `pnpm mem:export --wu WU-XXX`       | Export memory as markdown          |
-| `pnpm mem:create "msg" --wu WU-XXX` | Create memory node (bug discovery) |
-| `pnpm mem:signal "msg" --wu WU-XXX` | Broadcast coordination signal      |
-| `pnpm mem:inbox --wu WU-XXX`        | Check coordination signals         |
-| `pnpm mem:summarize --wu WU-XXX`    | Summarize memory context           |
-| `pnpm mem:triage --wu WU-XXX`       | Triage discovered bugs             |
-| `pnpm mem:context --wu WU-XXX`      | Get context for current lane/WU    |
-| `pnpm mem:context ... --lane <L>`   | Filter context by lane (WU-1292)   |
-| `pnpm mem:delete --id <node-id>`    | Delete/archive a memory node       |
-| `pnpm mem:cleanup`                  | Clean up stale memory data         |
+| Command                             | Description                         |
+| ----------------------------------- | ----------------------------------- |
+| `pnpm mem:init --wu WU-XXX`         | Initialize memory for WU            |
+| `pnpm mem:start --wu WU-XXX`        | Start a memory session              |
+| `pnpm mem:checkpoint --wu WU-XXX`   | Save progress checkpoint            |
+| `pnpm mem:recover --wu WU-XXX`      | Generate recovery context (WU-1390) |
+| `pnpm mem:ready --wu WU-XXX`        | Check pending nodes                 |
+| `pnpm mem:export --wu WU-XXX`       | Export memory as markdown           |
+| `pnpm mem:create "msg" --wu WU-XXX` | Create memory node (bug discovery)  |
+| `pnpm mem:signal "msg" --wu WU-XXX` | Broadcast coordination signal       |
+| `pnpm mem:inbox --wu WU-XXX`        | Check coordination signals          |
+| `pnpm mem:summarize --wu WU-XXX`    | Summarize memory context            |
+| `pnpm mem:triage --wu WU-XXX`       | Triage discovered bugs              |
+| `pnpm mem:context --wu WU-XXX`      | Get context for current lane/WU     |
+| `pnpm mem:context ... --lane <L>`   | Filter context by lane (WU-1292)    |
+| `pnpm mem:delete --id <node-id>`    | Delete/archive a memory node        |
+| `pnpm mem:cleanup`                  | Clean up stale memory data          |
 
 ---
 
@@ -444,3 +430,30 @@ pnpm mem:inbox --since 30m       # Check for signals (NOT TaskOutput)
 # Capture bug, don't fix out-of-scope
 pnpm mem:create 'Bug: description' --type discovery --tags bug --wu WU-XXX
 ```
+
+### Enforcement Hooks (WU-1367)
+
+Configure hooks that enforce workflow compliance for Claude Code:
+
+```yaml
+# In .lumenflow.config.yaml
+agents:
+  clients:
+    claude-code:
+      enforcement:
+        hooks: true
+        block_outside_worktree: true
+        require_wu_for_edits: true
+        warn_on_stop_without_wu_done: true
+```
+
+```bash
+# Generate hooks after configuration
+pnpm lumenflow:integrate --client claude-code
+```
+
+Hooks provide automatic enforcement at the tool level:
+
+- **block_outside_worktree**: Blocks Write/Edit to main when worktrees exist
+- **require_wu_for_edits**: Requires a claimed WU for Write/Edit operations
+- **warn_on_stop_without_wu_done**: Warns when session ends with active worktrees

package/templates/core/ai/onboarding/release-process.md.template

@@ -30,10 +30,11 @@ pnpm release --release-version 1.3.0
 
 1. Validates semver version format
 2. Ensures clean working directory on main branch
-3. Bumps all `@lumenflow/*` package versions using micro-worktree isolation
-4. Builds all packages
-5. Creates and pushes git tag `vX.Y.Z`
-6. Publishes to npm
+3. Syncs templates with source docs (`pnpm sync:templates`)
+4. Bumps all `@lumenflow/*` package versions using micro-worktree isolation
+5. Builds all packages
+6. Creates and pushes git tag `vX.Y.Z`
+7. Publishes to npm
 
 ### Options
 
@@ -73,6 +74,58 @@ Get a token at: https://www.npmjs.com/settings/tokens
 
 ---
 
+## Template Synchronization (WU-1353)
+
+CLI templates (`packages/@lumenflow/cli/templates/`) are synced from source docs to ensure new projects get up-to-date onboarding content.
+
+### Sync Templates
+
+```bash
+# Sync source docs to CLI templates
+pnpm sync:templates
+
+# Preview without writing files
+pnpm sync:templates --dry-run
+```
+
+### Check for Drift (CI)
+
+```bash
+# Check if templates are out of sync with source
+pnpm sync:templates --check-drift
+```
+
+The `--check-drift` flag compares templates with their source files. If drift is detected:
+
+- Exit code 1 (fails CI)
+- Lists drifting files
+- Suggests running `pnpm sync:templates`
+
+### What Gets Synced
+
+| Source                           | Template                                                      |
+| -------------------------------- | ------------------------------------------------------------- |
+| `.lumenflow/constraints.md`      | `templates/core/.lumenflow/constraints.md.template`           |
+| `LUMENFLOW.md`                   | `templates/core/LUMENFLOW.md.template`                        |
+| `docs/.../agent/onboarding/*.md` | `templates/core/ai/onboarding/*.md.template`                  |
+| `.claude/skills/*/SKILL.md`      | `templates/vendors/claude/.claude/skills/*/SKILL.md.template` |
+
+### Template Variables
+
+During sync, content is transformed:
+
+- `YYYY-MM-DD` dates become `{{DATE}}`
+- Absolute paths become `{{PROJECT_ROOT}}` (when applicable)
+
+### When to Sync
+
+- Before every release (included in release checklist)
+- After updating source onboarding docs
+- After modifying constraints or workflow rules
+- CI drift check runs on every push to main
+
+---
+
 ## Version Bumping (Manual)
 
 If you need to bump versions manually without the release command:
@@ -241,6 +294,7 @@ The `apps/github-app/package.json` must have `"private": true` to prevent npm pu
 - [ ] All acceptance criteria met
 - [ ] Gates pass (`pnpm gates`)
 - [ ] Pre-release checks pass (`pnpm pre-release:check`)
+- [ ] Templates synced (`pnpm sync:templates` - ensures CLI templates match source docs)
 - [ ] CHANGELOG updated (if maintained)
 
 ### Release Steps (Automated)

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

@@ -6,11 +6,56 @@ This is the complete onboarding document for AI agents working with LumenFlow. R
 
 ---
 
+## When Starting From Product Vision
+
+If you are starting a new project or feature from a product vision (e.g., "Build a task management app"), **do NOT create standalone WUs immediately**. Instead, follow the initiative-first workflow:
+
+### 4-Step Initiative Workflow
+
+1. **Create an Initiative**: Capture the vision as an initiative
+
+   ```bash
+   pnpm initiative:create --id INIT-001 --title "Task Management App" \
+     --description "Build a task management application with..." \
+     --phase "Phase 1: Core MVP" --phase "Phase 2: Collaboration"
+   ```
+
+2. **Define Phases**: Break the vision into logical phases (MVP, iteration, polish)
+
+3. **Create WUs under the Initiative**: Each WU belongs to a phase
+
+   ```bash
+   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
+   ```
+
+4. **Track Progress**: Use `pnpm initiative:status --id INIT-001` to see overall progress
+
+### Why Initiatives Matter
+
+- **Avoid orphan WUs**: Without initiative structure, agents create disconnected WUs that lack coherent scope
+- **Better coordination**: Phases enable parallel work across lanes
+- **Clear completion criteria**: The initiative tracks when all phases are done
+- **Visibility**: Stakeholders can see multi-phase progress
+
+### When to Skip Initiatives
+
+Only skip initiatives for:
+
+- Single-file bug fixes
+- Small documentation updates
+- Isolated refactoring tasks
+
+If work spans multiple WUs or multiple days, create an initiative first.
+
+---
+
 ## Quick Start (Copy This)
 
 ```bash
 # 1. Check your assigned WU
-cat {{DOCS_TASKS_PATH}}/wu/WU-XXXX.yaml
+cat docs/04-operations/tasks/wu/WU-XXXX.yaml
 
 # 2. Claim the WU (creates isolated worktree)
 pnpm wu:claim --id WU-XXXX --lane "Lane Name"
@@ -160,7 +205,7 @@ git add . && git commit -m "your message"
 **Fix:** Regenerate the backlog or manually add the missing WU:
 
 ```bash
-# In worktree, edit {{DOCS_TASKS_PATH}}/backlog.md
+# In worktree, edit docs/04-operations/tasks/backlog.md
 # Add the missing WU reference in the appropriate section
 ```
 
@@ -254,6 +299,7 @@ pnpm wu:spawn --id WU-XXXX --client <client-type>
 | ----------------------------------------- | --------------------------------- | --------------------- |
 | `pnpm wu:status --id WU-XXX`              | Show WU state and valid commands  | Check current state   |
 | `pnpm wu:claim --id WU-XXX --lane "Lane"` | Claim WU and create worktree      | Start working         |
+| `pnpm wu:edit --id WU-XXX --field value`  | Edit WU spec fields               | Update notes/desc     |
 | `pnpm wu:spawn --id WU-XXX --client X`    | Spawn sub-agent for parallel work | Complex WUs           |
 | `pnpm gates`                              | Run quality gates                 | Before wu:done        |
 | `pnpm gates --docs-only`                  | Run docs-only gates               | For documentation WUs |
@@ -266,7 +312,7 @@ pnpm wu:spawn --id WU-XXXX --client <client-type>
 
 ```
 /path/to/repo/
-├── {{DOCS_TASKS_PATH}}/
+├── docs/04-operations/tasks/
 │   ├── backlog.md              # All WUs listed here
 │   └── wu/WU-XXXX.yaml         # Individual WU specs
 ├── worktrees/
@@ -310,6 +356,24 @@ Before reporting a WU complete, verify:
 2. **Read error messages:** They usually include fix commands
 3. **Check gate logs:** `.logs/gates-*.log` in worktree
 4. **Recovery command:** `pnpm wu:recover --id WU-XXX`
+5. **Use --help for full options:** `<package_manager> <command> --help`
+
+### Rule: Always Check --help for Full Options (WU-1358)
+
+CLI documentation may not include all available options. Before using a command, **always run `--help`** to see the complete list:
+
+```bash
+# Examples (substitute your package manager)
+pnpm wu:edit --help
+npm run wu:claim -- --help
+yarn wu:create --help
+```
+
+This ensures you see:
+
+- All available flags (including inline options not in generated docs)
+- Required vs optional parameters
+- Default values and descriptions
 
 ---