@lumenflow/cli 2.5.0 → 2.6.0

package/templates/core/ai/onboarding/agent-safety-card.md.template

@@ -44,6 +44,35 @@ Quick reference for AI agents working in LumenFlow projects.
 
 ---
 
+## Universal Safety Mechanisms
+
+### Git Safety Wrapper
+
+Use `scripts/safe-git` instead of system `git` when possible.
+
+It blocks:
+
+- `git worktree remove`
+- `git reset --hard`
+- `git clean -fd`
+- `git push --force`
+
+### Repo Hooks (Husky)
+
+These run for everyone:
+
+- Secret scanning on staged content
+- Absolute path scanning on staged content
+- Lockfile sync checks
+- Worktree discipline checks
+
+Audit logs:
+
+- `.beacon/safety-blocks.log` (blocked safety actions)
+- `.beacon/force-bypasses.log` (LUMENFLOW_FORCE bypasses)
+
+---
+
 ## Error Handling
 
 ### Max 3 Attempts
@@ -104,3 +133,201 @@ Choose the safer path:
 - Don't bypass hooks
 - Don't skip gates
 - Ask rather than assume
+
+---
+
+## Emergency Override (LUMENFLOW_FORCE)
+
+In rare cases, you may need to bypass safety mechanisms. This requires explicit user approval and creates an audit trail.
+
+### When Emergency Override is Appropriate
+
+- Fixing YAML parsing bugs in WU specs (spec infrastructure issue)
+- Emergency production hotfixes (with user present)
+- Recovering from corrupted workflow state
+- Bootstrap operations when CLI not yet built
+
+### When NOT to Use Emergency Override
+
+- Skipping failing tests
+- Avoiding code review
+- Working around gate failures
+- Convenience or speed
+
+### How to Use LUMENFLOW_FORCE
+
+**Step 1: Get user approval**
+
+Agents MUST stop and ask before using LUMENFLOW_FORCE. Present the situation to the user:
+
+```
+I need to bypass the safety check for [reason].
+This will be logged to .beacon/force-bypasses.log.
+Do you approve? (yes/no)
+```
+
+**Step 2: Execute with audit trail**
+
+```bash
+# With reason (preferred)
+LUMENFLOW_FORCE_REASON="user-approved: <reason>" LUMENFLOW_FORCE=1 git <command>
+
+# Example: bypass safe-git for reset --hard
+LUMENFLOW_FORCE_REASON="user-approved: recovering corrupted state" LUMENFLOW_FORCE=1 git reset --hard HEAD
+
+# Example: bypass hook for commit
+LUMENFLOW_FORCE_REASON="user-approved: false positive secret detection" LUMENFLOW_FORCE=1 git commit -m "fix: update config"
+```
+
+**Step 3: Document in WU notes**
+
+Add a note to the WU YAML explaining the bypass:
+
+```yaml
+notes: |
+  Used LUMENFLOW_FORCE to bypass [mechanism] because [reason].
+  Approved by user at [timestamp].
+```
+
+### Audit Log Format
+
+All bypasses are logged to `.beacon/force-bypasses.log`:
+
+```
+ISO_TIMESTAMP|BYPASSED|COMMAND_OR_HOOK|USER|BRANCH|REASON|CWD
+```
+
+Example:
+
+```
+{{DATE}}T12:34:56Z|BYPASSED|git reset --hard HEAD|tom|lane/core/wu-1172|user-approved: recovering state|/home/tom/source/project
+```
+
+### Warning When No Reason Provided
+
+If LUMENFLOW_FORCE=1 is used without LUMENFLOW_FORCE_REASON, a warning is printed:
+
+```
+=== LUMENFLOW FORCE WARNING ===
+LUMENFLOW_FORCE used without LUMENFLOW_FORCE_REASON.
+Please provide a reason for audit trail:
+  LUMENFLOW_FORCE_REASON="your reason" LUMENFLOW_FORCE=1 git ...
+===============================
+```
+
+The command still proceeds, but "NO_REASON" is logged.
+
+---
+
+## Task Tool Hook Limitation (WU-1282)
+
+**Critical**: Claude Code's Task tool spawns sub-agents in a new session that does NOT inherit PreToolUse hooks from `.claude/settings.json`.
+
+### What This Means
+
+When you spawn a sub-agent via Task tool:
+
+- The sub-agent runs in a fresh context
+- PreToolUse hooks (like `validate-worktree-path.sh`) do NOT run
+- Sub-agents can write to main checkout even when worktrees exist
+
+### Workaround for Sub-Agents
+
+Sub-agents MUST manually verify worktree discipline before any Write/Edit:
+
+```bash
+# BEFORE any file operation, verify location
+pwd
+# Must show: /path/to/repo/worktrees/<lane>-wu-xxx
+
+# If not in worktree, navigate first
+cd worktrees/<lane>-wu-xxx
+```
+
+### For Orchestrators
+
+When spawning sub-agents via `pnpm wu:spawn`:
+
+1. The spawn prompt includes constraint #9 (WORKTREE DISCIPLINE)
+2. Sub-agents are instructed to manually verify worktree location
+3. This constraint compensates for the missing hook enforcement
+
+### Root Cause
+
+This is a Claude Code platform limitation, not a LumenFlow bug. Hooks defined in `.claude/settings.json` only apply to the parent session that loaded the settings file. Task-spawned sub-agents start fresh sessions without hook inheritance.
+
+---
+
+## Setup and Verification
+
+### Claude Code
+
+Claude Code automatically respects LumenFlow safety through:
+
+1. **CLAUDE.md** - Entry point that references safety rules
+2. **.claude/skills/** - Skills include safety context
+3. **.claude/agents/** - Agent definitions include constraints
+
+No additional setup required. Claude Code will read these files on startup.
+
+### Cursor
+
+Cursor uses `.cursor/rules/lumenflow.md` for safety rules.
+
+**Setup:**
+
+```bash
+# Initialize LumenFlow with Cursor overlay
+lumenflow init --client cursor
+
+# Or add to existing project
+mkdir -p .cursor/rules
+# Copy lumenflow.md template to .cursor/rules/
+```
+
+**Verification:**
+
+1. Open a file in Cursor
+2. Start a chat with Cursor AI
+3. Ask: "What are the LumenFlow safety rules?"
+4. Verify it mentions: worktree discipline, forbidden git commands, LUMENFLOW_FORCE
+
+### Windsurf
+
+Windsurf uses `.windsurf/rules/lumenflow.md` for safety rules.
+
+**Setup:**
+
+```bash
+# Initialize LumenFlow with Windsurf overlay
+lumenflow init --client windsurf
+
+# Or add to existing project
+mkdir -p .windsurf/rules
+# Copy lumenflow.md template to .windsurf/rules/
+```
+
+**Verification:**
+
+1. Open project in Windsurf
+2. Start a Cascade session
+3. Ask: "What safety mechanisms does this project use?"
+4. Verify it mentions: safe-git wrapper, Husky hooks, audit logs
+
+### Manual Verification
+
+Test that safety mechanisms work:
+
+```bash
+# Verify safe-git blocks dangerous commands
+./scripts/safe-git reset --hard HEAD
+# Should show: === LUMENFLOW SAFETY BLOCK ===
+
+# Verify hooks are installed
+ls -la .husky/
+# Should show: pre-commit, commit-msg, etc.
+
+# Verify bypass works with audit
+LUMENFLOW_FORCE_REASON="testing" LUMENFLOW_FORCE=1 ./scripts/safe-git --version
+# Should succeed and log to .beacon/force-bypasses.log
+```

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

@@ -0,0 +1,277 @@
+# Automatic CLI/Config Documentation Generation
+
+**Last updated:** {{DATE}}
+
+This document explains LumenFlow's automatic documentation generation system, which keeps Starlight docs in sync with code using a single-source-of-truth pattern.
+
+---
+
+## Overview
+
+LumenFlow automatically generates CLI and configuration reference documentation from source code. This ensures documentation never drifts from implementation.
+
+| Component        | Source                                                    | Output                                            |
+| ---------------- | --------------------------------------------------------- | ------------------------------------------------- |
+| 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` |
+
+---
+
+## Single-Source-of-Truth Pattern
+
+The documentation generator imports directly from built packages rather than parsing source files with regex:
+
+```typescript
+// tools/generate-cli-docs.ts
+import {
+  WU_OPTIONS,
+  DirectoriesSchema,
+  GatesConfigSchema,
+  // ... other schemas
+} from '../packages/@lumenflow/core/dist/index.js';
+```
+
+**Benefits:**
+
+- **No regex parsing**: Uses proper TypeScript imports
+- **Type safety**: Schemas validate at build time
+- **Consistent**: Same definitions used by CLI and docs
+- **Maintainable**: Update code once, docs follow automatically
+
+---
+
+## Trigger Files
+
+Changes to these files trigger documentation regeneration:
+
+| File/Directory                                            | Description                           |
+| --------------------------------------------------------- | ------------------------------------- |
+| `tools/generate-cli-docs.ts`                              | The generator script itself           |
+| `packages/@lumenflow/core/src/arg-parser.ts`              | CLI argument definitions (WU_OPTIONS) |
+| `packages/@lumenflow/core/src/lumenflow-config-schema.ts` | Config schema definitions             |
+| `packages/@lumenflow/core/src/index.ts`                   | Core exports                          |
+| `packages/@lumenflow/cli/package.json`                    | CLI bin entries                       |
+| `packages/@lumenflow/cli/src/**`                          | All CLI command sources               |
+
+These pathspecs are defined in `DOC_SOURCE_PATHSPECS` within `packages/@lumenflow/core/src/wu-done-docs-generate.ts`.
+
+---
+
+## wu:done Auto-Detection Flow
+
+When you run `pnpm wu:done`, the system automatically detects if docs need regeneration:
+
+```mermaid
+flowchart TD
+    A[wu:done starts] --> B[Run gates in worktree]
+    B --> C{Gates pass?}
+    C -->|No| D[Fix gates first]
+    C -->|Yes| E[Check doc-source changes]
+    E --> F{Any trigger files changed?}
+    F -->|No| G[Skip docs:generate]
+    F -->|Yes| H[Run turbo docs:generate]
+    H --> I[Format doc outputs]
+    I --> J[Stage doc files]
+    J --> K[Continue with metadata commit]
+    G --> K
+```
+
+### Detection Logic
+
+The detection uses efficient `git diff` with pathspecs:
+
+```bash
+git diff main...HEAD --name-only -- <pathspecs>
+```
+
+- **Zero overhead** when no doc-source files changed (~0ms)
+- **Turbo caching** when docs:generate runs (incremental builds)
+
+### Integration Point
+
+In `executeWorktreeCompletion()` (after gates pass, before metadata commit):
+
+```typescript
+await maybeRegenerateAndStageDocs({
+  baseBranch: 'main',
+  repoRoot: repoRoot,
+});
+```
+
+This ensures regenerated docs are included in the single atomic completion commit.
+
+---
+
+## Manual Commands
+
+### Generate Documentation
+
+Regenerate all CLI/config documentation:
+
+```bash
+pnpm docs:generate
+```
+
+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
+
+### Validate Documentation
+
+Check if documentation is in sync with code (useful for CI):
+
+```bash
+pnpm docs:validate
+```
+
+- **Exit 0**: Documentation is up to date
+- **Exit 1**: Documentation drift detected, run `pnpm docs:generate`
+
+### Turbo Integration
+
+The generator is integrated into Turbo for caching:
+
+```json
+// turbo.json
+"docs:generate": {
+  "dependsOn": ["@lumenflow/core#build"],
+  "inputs": [
+    "tools/generate-cli-docs.ts",
+    "packages/@lumenflow/core/src/arg-parser.ts",
+    "packages/@lumenflow/core/src/lumenflow-config-schema.ts",
+    "packages/@lumenflow/core/src/index.ts",
+    "packages/@lumenflow/cli/src/**/*.ts",
+    "packages/@lumenflow/cli/package.json"
+  ],
+  "outputs": [
+    "apps/docs/src/content/docs/reference/cli.mdx",
+    "apps/docs/src/content/docs/reference/config.mdx"
+  ]
+}
+```
+
+**Key points:**
+
+- Depends on `@lumenflow/core#build` (requires built packages for imports)
+- Inputs match `DOC_SOURCE_PATHSPECS` for consistent detection
+- Outputs are cached; unchanged inputs skip regeneration
+
+---
+
+## Output Files
+
+The generator produces two MDX files:
+
+### CLI Reference (`cli.mdx`)
+
+- Generated from CLI package.json bin entries
+- Options extracted from WU_OPTIONS in `@lumenflow/core`
+- Grouped by category (Work Units, Memory Layer, Initiatives, etc.)
+- Includes required/optional flags and descriptions
+
+### Config Reference (`config.mdx`)
+
+- Generated from Zod schemas in `@lumenflow/core`
+- Each config section documented with fields, types, defaults
+- Environment variable overrides documented
+- Validation command shown
+
+---
+
+## Adding New CLI Commands
+
+When you add a new CLI command:
+
+1. **Add bin entry** to `packages/@lumenflow/cli/package.json`
+2. **Add options** to `WU_OPTIONS` in `packages/@lumenflow/core/src/arg-parser.ts`
+3. **Run** `pnpm docs:generate` to update documentation
+4. **Verify** the command appears in `cli.mdx`
+
+The generator automatically:
+
+- Discovers the new command from package.json
+- Extracts options from WU_OPTIONS references in source
+- Categorizes based on command prefix (wu-, mem-, etc.)
+
+---
+
+## Adding New Config Options
+
+When you add new configuration options:
+
+1. **Add to schema** in `packages/@lumenflow/core/src/lumenflow-config-schema.ts`
+2. **Export** from `packages/@lumenflow/core/src/index.ts`
+3. **Add to SCHEMA_DEFINITIONS** in `tools/generate-cli-docs.ts`
+4. **Run** `pnpm docs:generate` to update documentation
+
+---
+
+## Troubleshooting
+
+### Documentation Drift in CI
+
+If CI fails with documentation drift:
+
+```bash
+# Regenerate and commit
+pnpm docs:generate
+git add apps/docs/src/content/docs/reference/
+git commit -m "docs: regenerate CLI/config reference"
+```
+
+### Import Errors in Generator
+
+If `tools/generate-cli-docs.ts` fails with import errors:
+
+```bash
+# Ensure packages are built
+pnpm build
+# Then regenerate
+pnpm docs:generate
+```
+
+### Turbo Cache Issues
+
+If docs aren't regenerating when they should:
+
+```bash
+# Clear Turbo cache and regenerate
+pnpm clean
+pnpm build
+pnpm docs:generate
+```
+
+---
+
+## Architecture Summary
+
+```
+Source Code                    Generator                      Output
+────────────────────────────────────────────────────────────────────────
+@lumenflow/core
+  └── arg-parser.ts      ─┐
+  └── lumenflow-config-  ─┼── tools/generate-cli-docs.ts ──┬─► cli.mdx
+      schema.ts          ─┤       (imports from dist/)      │
+@lumenflow/cli             │                                  │
+  └── package.json       ─┤                                  └─► config.mdx
+  └── src/**/*.ts        ─┘
+```
+
+**Key design decisions:**
+
+- **Library imports over regex**: Reliable, type-safe extraction
+- **Turbo integration**: Caching, dependency management
+- **wu:done integration**: Zero-effort doc updates
+- **CI validation**: Drift detection prevents stale docs
+
+---
+
+## Related Documentation
+
+- [Release Process](./release-process.md) - Deployment workflow including docs
+- [LumenFlow Complete Guide](../../lumenflow-complete.md) - Full framework reference
+- [Quick Reference Commands](./quick-ref-commands.md) - Command cheat sheet

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

@@ -26,17 +26,20 @@ cd worktrees/core-wu-123
 vim src/feature.ts
 git commit -m "feat: add feature"
 git push origin lane/core/wu-123
-cd /path/to/main
-pnpm wu:done --id WU-123
+pnpm wu:prep --id WU-123  # WU-1223: runs gates, prints copy-paste instruction
+cd /path/to/main && pnpm wu:done --id WU-123  # Copy-paste from wu:prep output
 ```
 
 ---
 
-## Mistake 2: Forgetting to Run wu:done
+## Mistake 2: Forgetting to Run wu:prep and wu:done
 
 See [troubleshooting-wu-done.md](troubleshooting-wu-done.md) for the full explanation.
 
-**TL;DR:** After gates pass, ALWAYS run `pnpm wu:done --id WU-XXX`.
+**TL;DR (WU-1223):**
+
+1. From worktree: `pnpm wu:prep --id WU-XXX` (runs gates)
+2. From main: `pnpm wu:done --id WU-XXX` (copy-paste from wu:prep output)
 
 ---
 
@@ -159,7 +162,8 @@ Start coding immediately based on the title.
 2. Understand acceptance criteria
 3. Review code_paths
 4. Check dependencies
-5. Then start
+5. Check spec_refs for linked plans (if present, read the plan document)
+6. Then start
 
 ---
 
@@ -183,16 +187,54 @@ vim src/feature.ts  # Now it's safe
 
 ---
 
+## Mistake 11: "Quick Fixing" on Main
+
+### Wrong
+
+```bash
+# On main, see failing format check
+pnpm gates
+# Output: format:check failed
+
+# Instinct: "I should help fix this!"
+pnpm prettier --write apps/docs/src/content/docs/concepts/lanes.mdx
+# Files modified on main - BAD!
+```
+
+### Right
+
+```bash
+# On main, see failing format check
+pnpm gates
+# Output: format:check failed
+
+# Report to user or create a WU
+# "Format check is failing on main. Should I create a WU to fix it?"
+
+# If yes:
+pnpm wu:create --lane "Content: Documentation" --title "Fix format issues" ...
+pnpm wu:claim --id WU-XXX --lane "Content: Documentation"
+cd worktrees/content-documentation-wu-xxx
+pnpm prettier --write <files>  # Safe in worktree
+```
+
+**Why:** The "helpful fix" instinct is dangerous. Even small fixes (format, typos, lint) must go through a worktree. Commits are blocked by hooks, but files are still modified, requiring cleanup with `git checkout -- <files>`.
+
+**Rule:** If you're on main and want to change something—STOP. Create a WU first.
+
+---
+
 ## Quick Checklist
 
 Before starting any WU:
 
 - [ ] Read the full WU spec
 - [ ] Understand acceptance criteria
+- [ ] Check spec_refs for plans (read linked plans if present)
 - [ ] Claim the WU with `pnpm wu:claim`
 - [ ] cd to the worktree IMMEDIATELY
 - [ ] Work only in the worktree
 - [ ] Stay within code_paths
 - [ ] Follow TDD
-- [ ] Run gates before wu:done
-- [ ] ALWAYS run wu:done
+- [ ] Run wu:prep from worktree (runs gates)
+- [ ] Run wu:done from main (copy-paste from wu:prep output)