@lumenflow/cli 2.4.0 → 2.5.1

package/templates/core/LUMENFLOW.md.template

@@ -8,17 +8,18 @@ LumenFlow is a vendor-agnostic workflow framework for AI-native software develop
 
 ---
 
-## Critical Rule: ALWAYS Run wu:done
+## Critical Rule: Use wu:prep Then wu:done
 
-**After completing work on a WU, you MUST run `pnpm wu:done --id WU-XXXX` from the main checkout.**
+**WU-1223 NEW WORKFLOW:**
 
-This is the single most forgotten step. Do NOT:
+1. From worktree: `pnpm wu:prep --id WU-XXXX` (runs gates, prints copy-paste instruction)
+2. From main: `pnpm wu:done --id WU-XXXX` (merge + cleanup only)
 
-- Write "To Complete: pnpm wu:done" and stop
-- Ask if you should run wu:done
-- Forget to run wu:done
+**DO NOT:**
 
-**DO**: Run `pnpm wu:done --id WU-XXXX` immediately after gates pass.
+- Run `wu:done` from a worktree (it will error)
+- Forget to run `wu:done` after `wu:prep`
+- Skip `wu:prep` and go directly to `wu:done` (gates won't run in worktree)
 
 See: [docs/04-operations/\_frameworks/lumenflow/agent/onboarding/troubleshooting-wu-done.md](docs/04-operations/_frameworks/lumenflow/agent/onboarding/troubleshooting-wu-done.md)
 
@@ -30,8 +31,8 @@ See: [docs/04-operations/\_frameworks/lumenflow/agent/onboarding/troubleshooting
 # 1. Setup (first time only)
 pnpm setup
 
-# 2. Create a WU (default: creates spec/wu-xxxx branch, never writes to main)
-pnpm wu:create --id WU-XXXX --lane <Lane> --title "Title" \
+# 2. 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"
@@ -42,15 +43,49 @@ cd worktrees/<lane>-wu-xxxx
 
 # 4. Implement in worktree
 
-# 5. Run gates
-pnpm gates --docs-only  # for docs changes
-pnpm gates              # for code changes
+# 5. 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)
-cd /path/to/main
-pnpm wu:done --id WU-XXXX
+# 6. Complete (from main checkout - copy-paste from wu:prep output)
+cd /path/to/main && pnpm wu:done --id WU-XXXX
+```
+
+---
+
+## Setup Notes (Common First-Run Failures)
+
+### Lane inference (sub-lanes)
+
+If you use sub-lanes like `Experience: UI`, you must have a lane taxonomy:
+
+- Ensure `.lumenflow.lane-inference.yaml` exists, or
+- Generate it with `pnpm lane:suggest --output .lumenflow.lane-inference.yaml`
+
+Without this file, sub-lane validation will fail.
+
+### Local-only / no remote
+
+By default, `wu:create` expects an `origin` remote and will fetch `origin/main`.
+
+For local-only or offline development, add this to `.lumenflow.config.yaml`:
+
+```yaml
+git:
+  requireRemote: false
 ```
 
+When `requireRemote: false`:
+
+- `wu:create` skips remote fetch operations
+- `wu:claim` works without pushing to origin
+- Useful for air-gapped environments, testing/evaluation, or pre-remote development
+
+When `requireRemote: true` (default):
+
+- Operations fail with a clear error if no `origin` remote exists
+- Ensures team visibility via remote branches
+
 ---
 
 ## Core Principles
@@ -66,6 +101,18 @@ pnpm wu:done --id WU-XXXX
 
 ---
 
+## Universal Agent Safety (WU-1170)
+
+LumenFlow enforces safety at the repository level so protections apply to all agents and humans.
+
+- **Git wrapper**: `scripts/safe-git` blocks destructive operations (e.g. `worktree remove`, `reset --hard`, `clean -fd`, `push --force`).
+- **Husky hooks**: staged secret scanning, absolute-path scanning, lockfile sync, and worktree discipline.
+- **Audit logs**:
+  - `.beacon/safety-blocks.log`
+  - `.beacon/force-bypasses.log`
+
+---
+
 ## Global State
 
 Canonical global state is defined by:
@@ -83,17 +130,31 @@ air-gapped/offline work; it creates a local-only claim and warns explicitly.
 
 ### Core (Vendor-Agnostic)
 
-- **LUMENFLOW.md** - This file, main entry point
+- **AGENTS.md** - Universal entry point for AI agents (Codex, Cursor, Windsurf)
+- **LUMENFLOW.md** - This file, main workflow documentation
 - **.lumenflow/constraints.md** - Non-negotiable workflow constraints
 - **.lumenflow/rules/** - Workflow rules (git-safety.md, wu-workflow.md, etc.)
 - **docs/04-operations/\_frameworks/lumenflow/agent/onboarding/** - Agent onboarding documentation
 
-### Vendor Integrations
+### Client/Vendor Overlays
+
+- **CLAUDE.md** - Claude Code overlay (single file at root)
+- **.claude/** - Claude Code settings, hooks, skills, agents
+- **.cursor/rules/lumenflow.md** - Cursor rules overlay
+- **.windsurf/rules/lumenflow.md** - Windsurf rules overlay
+
+Use `lumenflow init --client <type>` to generate client-specific files:
+
+```bash
+lumenflow init                     # Creates AGENTS.md + LUMENFLOW.md (universal)
+lumenflow init --client claude     # + CLAUDE.md, .claude/
+lumenflow init --client cursor     # + .cursor/rules/lumenflow.md
+lumenflow init --client windsurf   # + .windsurf/rules/lumenflow.md
+lumenflow init --client all        # All of the above
+lumenflow init --merge             # Safe merge into existing files
+```
 
-- **.claude/** - Claude Code (settings.json, hooks, .claude/CLAUDE.md)
-- **.cursor/** - Cursor (rules, settings)
-- **.aider.conf.yml** - Aider configuration
-- **.continue/** - Continue configuration
+The `--merge` flag uses bounded markers (`LUMENFLOW:START`/`END`) to safely insert or update LumenFlow config in existing files without overwriting user content.
 
 ---
 
@@ -131,7 +192,7 @@ Main checkout becomes read-only after claim. Hooks will block WU commits from ma
 
 ## Core Commands
 
-> **Complete CLI reference (60+ commands):** See [quick-ref-commands.md](ai/onboarding/quick-ref-commands.md)
+> **Complete CLI reference (60+ commands):** See [quick-ref-commands.md](docs/04-operations/_frameworks/lumenflow/agent/onboarding/quick-ref-commands.md)
 
 | Command                         | Description                                            |
 | ------------------------------- | ------------------------------------------------------ |
@@ -161,7 +222,7 @@ When validation fails, commands provide copy-paste ready fix commands:
 ERROR: WRONG_LOCATION - wu:done must be run from main checkout
 
 FIX: Run this command:
-  cd {{PROJECT_ROOT}} && pnpm wu:done --id WU-1090
+  cd <repo-root> && pnpm wu:done --id WU-1090
 ```
 
 Configure validation behavior in `.lumenflow.config.yaml`:
@@ -210,6 +271,7 @@ If you're an AI agent, read the onboarding docs:
 2. [docs/04-operations/\_frameworks/lumenflow/agent/onboarding/first-wu-mistakes.md](docs/04-operations/_frameworks/lumenflow/agent/onboarding/first-wu-mistakes.md) - First WU pitfalls
 3. [docs/04-operations/\_frameworks/lumenflow/agent/onboarding/agent-safety-card.md](docs/04-operations/_frameworks/lumenflow/agent/onboarding/agent-safety-card.md) - Safety guardrails
 4. [docs/04-operations/\_frameworks/lumenflow/agent/onboarding/quick-ref-commands.md](docs/04-operations/_frameworks/lumenflow/agent/onboarding/quick-ref-commands.md) - Command reference
+5. [docs/04-operations/\_frameworks/lumenflow/agent/onboarding/test-ratchet.md](docs/04-operations/_frameworks/lumenflow/agent/onboarding/test-ratchet.md) - Test baseline ratchet pattern
 
 ---
 

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

@@ -0,0 +1,157 @@
+# Agent Invocation Guide (LumenFlow)
+
+**Last updated:** {{DATE}}
+
+This guide defines how to spawn and brief sub-agents so they start with the right context,
+follow LumenFlow constraints, and leave durable artifacts for handoff.
+
+Use this document when:
+
+- Spawning sub-agents or parallel WUs
+- Writing orchestrator prompts
+- Starting a new session after `/clear`
+- Coordinating multi-wave initiatives
+
+---
+
+## 1) Context Tiers (Load Order)
+
+Load context in this order to reduce "lost in the middle" failures:
+
+1. `LUMENFLOW.md` — workflow fundamentals
+2. `README.md` — repo structure / commands
+3. `lumenflow-complete.md` §§1-7 — constraints + governance
+4. WU YAML — current task spec
+5. Task instructions — what to do
+6. **Critical Constraints block** — append at the end (see below)
+
+**Tier guidance:**
+
+- **Tier 1 (minimal):** `LUMENFLOW.md`, `README.md`, WU YAML
+- **Tier 2 (standard):** Tier 1 + `lumenflow-complete.md` §§1-7
+- **Tier 3 (full):** Tier 2 + relevant framework/agent docs
+
+Use Tier 1 after `/clear` to stay lean, then load more only if needed.
+
+---
+
+## 2) Session Management (Spawn Fresh)
+
+When approaching context limits, **spawn a fresh agent instead of compaction**.
+The spawn prompt is the bridge between sessions.
+
+**Mandatory triggers:**
+
+- Context usage >80%
+- 50+ tool calls
+- Performance degradation (forgotten context, redundant queries)
+- About to run `/compact` or `/clear`
+
+**Spawn fresh protocol:**
+
+```bash
+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:spawn --id WU-XXX
+# Exit current session; start fresh with the generated prompt.
+```
+
+**Optional safety net:** If your client supports hooks, add a pre-clear checkpoint hook:
+
+```bash
+pnpm mem:checkpoint "Pre-clear: <summary>" --wu WU-XXX --trigger pre-clear
+```
+
+---
+
+## 2a) Memory Context Injection (Automatic)
+
+When the memory layer is initialized (`memory.jsonl` exists), `wu:spawn` automatically
+injects relevant memory context into the spawn prompt under a `## Memory Context` section.
+
+**What gets included:**
+
+- WU-specific checkpoints and notes
+- Project-level architectural decisions
+- Recent context relevant to the lane
+
+**Configuration:**
+
+Configure max context size in `.lumenflow.config.yaml`:
+
+```yaml
+memory:
+  spawn_context_max_size: 4096 # Default: 4KB
+```
+
+**Skip context injection:**
+
+Use `--no-context` when you want a clean spawn without memory context:
+
+```bash
+pnpm wu:spawn --id WU-XXX --no-context
+```
+
+This is useful when:
+
+- Starting completely fresh without prior context
+- Debugging context-related issues
+- Memory layer contains stale or irrelevant data
+
+---
+
+## 3) Spawn Prompt Structure (Recommended)
+
+Use this structure for sub-agent prompts:
+
+1. **Objective** — clear, single outcome
+2. **Scope** — what is in/out of scope
+3. **Code Paths** — allowed paths (from WU `code_paths`)
+4. **Tests/Gates** — required checks
+5. **Progress Artifacts** — checkpoints, commits, signals
+6. **Recovery** — what to do if blocked
+7. **Critical Constraints** — append at the end
+
+---
+
+## 4) Append These Constraints at the End (Mandatory)
+
+Paste this block at the end of every multi-agent prompt:
+
+```
+CRITICAL CONSTRAINTS (append at end, do not omit):
+1) Work only in worktrees after wu:claim; main is read-only for WU work.
+2) Never bypass hooks (--no-verify, HUSKY=0). Fix root causes instead.
+3) WUs are specs, not code; stay within code_paths.
+4) Run correct gates before wu:done (docs-only vs full).
+5) Use LLM-first inference; avoid brittle regex/keyword shortcuts.
+6) If uncertain about safety, stop and ask.
+```
+
+For full details, see `.lumenflow/constraints.md`.
+
+---
+
+## 5) Coordination Checklist (Orchestrators)
+
+Before spawning:
+
+- Confirm WU status and lane availability
+- Ensure worktree exists (or claim first)
+- Provide explicit code_paths and tests
+- Require `mem:checkpoint` at 50+ tool calls
+- Require `mem:signal` for milestones
+
+After spawning:
+
+- Monitor with `pnpm mem:inbox --since 30m`
+- Use `pnpm mem:ready --wu WU-XXX` for handoff status
+
+---
+
+## 6) Related Skills
+
+- `.claude/skills/context-management/SKILL.md`
+- `.claude/skills/multi-agent-coordination/SKILL.md`
+- `.claude/skills/execution-memory/SKILL.md`

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
+```