@lumenflow/cli 2.5.0 → 2.6.0

package/dist/wu-prep.js

@@ -1,21 +1,28 @@
 #!/usr/bin/env node
+/* eslint-disable no-console -- CLI command uses console for status output */
 /**
  * WU Prep Helper (WU-1223)
  *
  * Prepares a WU for completion by running gates and generating docs in the worktree.
  * After successful prep, prints copy-paste instruction to run wu:done from main.
  *
+ * WU-1344: When gates fail on spec:linter due to pre-existing WU validation errors
+ * (not caused by the current WU), prints a ready-to-copy wu:done --skip-gates
+ * command with reason and fix-wu placeholders.
+ *
  * Workflow:
  * 1. Verify we're in a worktree (error if in main checkout)
  * 2. Run gates in the worktree
- * 3. Generate docs (if applicable)
- * 4. Print copy-paste instruction for wu:done from main
+ * 3. If gates fail, check if failures are pre-existing on main
+ * 4. If pre-existing, print skip-gates command; otherwise, print fix guidance
+ * 5. On success, print copy-paste instruction for wu:done from main
  *
  * Usage:
  *   pnpm wu:prep --id WU-XXX [--docs-only]
  *
  * @module
  */
+import { spawnSync } from 'node:child_process';
 import { createWUParser, WU_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
 import { die } from '@lumenflow/core/dist/error-handler.js';
 import { resolveLocation } from '@lumenflow/core/dist/context/location-resolver.js';
@@ -39,6 +46,84 @@ const PREP_OPTIONS = {
         description: 'Run docs-only gates (format, spec-linter)',
     },
 };
+/**
+ * WU-1344: Check if a gate name is the spec:linter gate.
+ * Used to identify when spec:linter fails so we can check for pre-existing failures.
+ *
+ * @param gateName - Name of the gate that failed
+ * @returns true if this is the spec:linter gate
+ */
+export function isPreExistingSpecLinterFailure(gateName) {
+    const normalizedName = gateName.toLowerCase().replace(/[:-]/g, '');
+    return normalizedName === 'speclinter';
+}
+/**
+ * WU-1344: Format a skip-gates command for wu:done.
+ * Includes --reason and --fix-wu placeholders.
+ *
+ * @param options - Configuration options
+ * @param options.wuId - The WU ID being completed
+ * @param options.mainCheckout - Path to main checkout
+ * @returns Formatted command string ready to copy-paste
+ */
+export function formatSkipGatesCommand(options) {
+    const { wuId, mainCheckout } = options;
+    return `cd ${mainCheckout} && pnpm wu:done --id ${wuId} --skip-gates --reason "pre-existing on main" --fix-wu WU-XXXX`;
+}
+/**
+ * WU-1344: Default implementation of execOnMain using spawnSync.
+ * Uses spawnSync with pnpm executable for safety (no shell injection risk).
+ */
+function defaultExecOnMain(mainCheckout) {
+    return async (cmd) => {
+        // Parse command to extract pnpm script name and args
+        // Expected format: "pnpm spec:linter" or similar
+        const parts = cmd.split(/\s+/);
+        const executable = parts[0];
+        const args = parts.slice(1);
+        const result = spawnSync(executable, args, {
+            cwd: mainCheckout,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return {
+            exitCode: result.status ?? 1,
+            stdout: result.stdout ?? '',
+            stderr: result.stderr ?? '',
+        };
+    };
+}
+/**
+ * WU-1344: Check if spec:linter failures are pre-existing on main branch.
+ *
+ * Runs spec:linter on the main checkout to determine if the failures
+ * already exist there (i.e., not caused by the current WU).
+ *
+ * @param options - Configuration options
+ * @param options.mainCheckout - Path to main checkout
+ * @param options.execOnMain - Optional function to execute commands on main (for testing)
+ * @returns Result indicating whether failures are pre-existing
+ */
+export async function checkPreExistingFailures(options) {
+    const { mainCheckout, execOnMain = defaultExecOnMain(mainCheckout) } = options;
+    try {
+        // Run spec:linter on main checkout
+        const result = await execOnMain('pnpm spec:linter');
+        // If spec:linter fails on main, the failures are pre-existing
+        if (result.exitCode !== 0) {
+            return { hasPreExisting: true };
+        }
+        return { hasPreExisting: false };
+    }
+    catch (error) {
+        // If we can't check main, assume failures are NOT pre-existing
+        // (safer to require fixing rather than skipping)
+        return {
+            hasPreExisting: false,
+            error: error.message,
+        };
+    }
+}
 /**
  * Print success message with copy-paste instruction.
  */
@@ -106,6 +191,34 @@ async function main() {
     console.log(`${PREP_PREFIX} Location: ${location.cwd}`);
     console.log(`${PREP_PREFIX} Main checkout: ${location.mainCheckout}`);
     console.log('');
+    // WU-1344: Check for pre-existing spec:linter failures on main BEFORE running gates.
+    // We do this first because runGates() calls die() on failure, which exits the process
+    // before we can check. By checking first, we can set up an exit handler to show
+    // the skip-gates command if gates fail.
+    console.log(`${PREP_PREFIX} Checking for pre-existing spec:linter failures on main...`);
+    const preExistingCheck = await checkPreExistingFailures({
+        mainCheckout: location.mainCheckout,
+    });
+    if (preExistingCheck.hasPreExisting) {
+        console.log(`${PREP_PREFIX} ${EMOJI.WARNING} Pre-existing failures detected on main.`);
+        // Set up an exit handler to print the skip-gates command when gates fail
+        // This runs before process.exit() fully terminates the process
+        process.on('exit', (code) => {
+            if (code !== EXIT_CODES.SUCCESS) {
+                console.log('');
+                console.log(`${PREP_PREFIX} ${EMOJI.WARNING} Since failures are pre-existing on main, you can skip gates:`);
+                console.log('');
+                console.log(`    ${formatSkipGatesCommand({ wuId: id, mainCheckout: location.mainCheckout })}`);
+                console.log('');
+                console.log(`${PREP_PREFIX} Replace WU-XXXX with the WU that will fix these spec issues.`);
+                console.log('');
+            }
+        });
+    }
+    else {
+        console.log(`${PREP_PREFIX} No pre-existing failures on main.`);
+    }
+    console.log('');
     // Run gates in the worktree
     console.log(`${PREP_PREFIX} Running gates in worktree...`);
     const gatesResult = await runGates({
@@ -113,13 +226,23 @@ async function main() {
         docsOnly: args.docsOnly,
     });
     if (!gatesResult) {
-        die(`${EMOJI.FAILURE} Gates failed in worktree.\n\n` +
-            `Fix the gate failures and run wu:prep again.`);
+        // Gates failed - if pre-existing check was already done and showed failures,
+        // the exit handler above will print the skip-gates command.
+        // Otherwise, tell the user to fix the failures.
+        if (!preExistingCheck.hasPreExisting) {
+            die(`${EMOJI.FAILURE} Gates failed in worktree.\n\n` +
+                `Fix the gate failures and run wu:prep again.`);
+        }
+        // Pre-existing failures - exit with error, handler will print skip-gates command
+        process.exit(EXIT_CODES.ERROR);
     }
     // Success - print copy-paste instruction
     printSuccessMessage(id, location.mainCheckout);
 }
-main().catch((e) => {
-    console.error(e.message);
-    process.exit(EXIT_CODES.ERROR);
-});
+// WU-1181: Use import.meta.main instead of process.argv[1] comparison
+// The old pattern fails with pnpm symlinks because process.argv[1] is the symlink
+// path but import.meta.url resolves to the real path - they never match
+import { runCLI } from './cli-entry-point.js';
+if (import.meta.main) {
+    void runCLI(main);
+}

package/dist/wu-spawn.js

@@ -38,11 +38,12 @@ import { WU_STATUS, PATTERNS, FILE_SYSTEM, EMOJI } from '@lumenflow/core/dist/wu
 // WU-1603: Check lane lock status before spawning
 // WU-1325: Import lock policy getter for lane availability check
 import { checkLaneLock } from '@lumenflow/core/dist/lane-lock.js';
-import { getLockPolicyForLane } from '@lumenflow/core/dist/lane-checker.js';
+import { getLockPolicyForLane, getWipLimitForLane } from '@lumenflow/core/dist/lane-checker.js';
 import { minimatch } from 'minimatch';
 // WU-2252: Import invariants loader for spawn output injection
 import { loadInvariants, INVARIANT_TYPES } from '@lumenflow/core/dist/invariants-runner.js';
 import { validateSpawnArgs, generateExecutionModeSection, generateThinkToolGuidance, recordSpawnToRegistry, formatSpawnRecordedMessage, } from '@lumenflow/core/dist/wu-spawn-helpers.js';
+// eslint-disable-next-line sonarjs/deprecation -- legacy factory used by CLI spawns
 import { SpawnStrategyFactory } from '@lumenflow/core/dist/spawn-strategy.js';
 import { getConfig } from '@lumenflow/core/dist/lumenflow-config.js';
 import { generateClientSkillsGuidance, generateSkillsSelectionSection, resolveClientConfig, } from '@lumenflow/core/dist/wu-spawn-skills.js';
@@ -1168,7 +1169,10 @@ export function checkLaneOccupation(lane) {
 export function generateLaneOccupationWarning(lockMetadata, targetWuId, options = {}) {
     const { isStale = false } = options;
     let warning = `⚠️  Lane "${lockMetadata.lane}" is occupied by ${lockMetadata.wuId}\n`;
-    warning += `   This violates WIP=1 (Work In Progress limit of 1 per lane).\n\n`;
+    // WU-1346: Use injected values if provided, otherwise look up from config
+    const lockPolicy = options.lockPolicy ?? getLockPolicyForLane(lockMetadata.lane);
+    const wipLimit = options.wipLimit ?? getWipLimitForLane(lockMetadata.lane);
+    warning += `   This violates WIP=${wipLimit} (lock_policy=${lockPolicy}).\n\n`;
     if (isStale) {
         warning += `   ⏰ This lock is STALE (>24 hours old) - the WU may be abandoned.\n`;
         warning += `   Consider using pnpm wu:block --id ${lockMetadata.wuId} if work is stalled.\n\n`;
@@ -1327,6 +1331,7 @@ async function main() {
         }
     }
     // Create strategy
+    // eslint-disable-next-line sonarjs/deprecation -- legacy factory used by CLI spawns
     const strategy = SpawnStrategyFactory.create(clientName);
     const clientContext = { name: clientName, config: resolveClientConfig(config, clientName) };
     if (clientName === 'codex-cli' || args.codex) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/cli",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Command-line interface for LumenFlow workflow framework",
   "keywords": [
     "lumenflow",
@@ -74,7 +74,7 @@
     "initiative-status": "./dist/initiative-status.js",
     "initiative-add-wu": "./dist/initiative-add-wu.js",
     "initiative-plan": "./dist/initiative-plan.js",
-    "init-plan": "./dist/init-plan.js",
+    "init-plan": "./dist/initiative-plan.js",
     "plan-create": "./dist/plan-create.js",
     "plan-link": "./dist/plan-link.js",
     "plan-edit": "./dist/plan-edit.js",
@@ -148,11 +148,11 @@
     "pretty-ms": "^9.2.0",
     "simple-git": "^3.30.0",
     "yaml": "^2.8.2",
-    "@lumenflow/core": "2.5.0",
-    "@lumenflow/initiatives": "2.5.0",
-    "@lumenflow/memory": "2.5.0",
-    "@lumenflow/agent": "2.5.0",
-    "@lumenflow/metrics": "2.5.0"
+    "@lumenflow/core": "2.6.0",
+    "@lumenflow/initiatives": "2.6.0",
+    "@lumenflow/metrics": "2.6.0",
+    "@lumenflow/agent": "2.6.0",
+    "@lumenflow/memory": "2.6.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.17",

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

@@ -1,13 +1,13 @@
 # LumenFlow Constraints Capsule
 
-**Version:** 1.0
+**Version:** 1.1
 **Last updated:** {{DATE}}
 
-This document contains the 6 non-negotiable constraints that every agent must keep "in working memory" from first plan through `wu:done`.
+This document contains the 7 non-negotiable constraints that every agent must keep "in working memory" from first plan through `wu:done`.
 
 ---
 
-## The 6 Non-Negotiable Constraints
+## The 7 Non-Negotiable Constraints
 
 ### 1. Worktree Discipline and Git Safety
 
@@ -19,8 +19,40 @@ This document contains the 6 non-negotiable constraints that every agent must ke
 - Hooks block WU commits from main checkout
 - Forbidden commands on main: `git reset --hard`, `git stash`, `git clean -fd`, `git push --force`
 
+**MANDATORY PRE-WRITE CHECK**
+
+Before ANY Write/Edit/Read operation:
+
+1. **Verify worktree location**:
+
+   ```bash
+   pwd
+   # Must show: .../worktrees/<lane>-wu-xxx
+   ```
+
+2. **Verify relative paths only**:
+   - ✅ `docs/...`, `packages/...`, `apps/...`, `./...`
+   - ❌ `/home/...`, `/Users/...`, or full repo paths
+
+3. **Docs-only exception (documentation WUs)**:
+   - You may run **read-only** commands from main (e.g., `pnpm gates --docs-only`).
+   - **All file writes still require a worktree**. If no worktree exists, claim one first.
+
 **Why:** Worktree isolation prevents cross-contamination between parallel WUs and protects the main branch.
 
+**NEVER "QUICK FIX" ON MAIN**
+
+If you see something broken on main (failing gates, format issues, typos, lint errors):
+
+- ❌ **Don't** fix it directly, even if it seems small or helpful
+- ❌ **Don't** run `prettier --write`, `pnpm lint --fix`, or any command that modifies files
+- ✅ **Do** report the issue to the user
+- ✅ **Do** create a WU if a fix is needed
+
+**Why this matters:** The "helpful fix" instinct causes agents to modify files on main without a worktree. While commits are blocked by hooks, the files are still modified, requiring manual cleanup. Every change—no matter how small—needs a worktree.
+
+**If you're on main and want to change something: STOP. Create a WU first.**
+
 ---
 
 ### 2. WUs Are Specs, Not Code
@@ -94,6 +126,32 @@ This document contains the 6 non-negotiable constraints that every agent must ke
 
 ---
 
+### 7. Test Ratchet Pattern (WU-1253)
+
+**Rule:** NEW test failures block gates; pre-existing failures (in baseline) warn but do not block.
+
+**Baseline File:** `.lumenflow/test-baseline.json`
+
+**Enforcement:**
+
+- Gates compare current test results against baseline
+- NEW failures (not in baseline) = **BLOCK** (must fix or add to baseline)
+- Pre-existing failures (in baseline) = **WARNING** (continue, do not block WU)
+- Fixed tests auto-removed from baseline (ratchet forward)
+
+**When gates fail due to tests:**
+
+1. Check baseline: `cat .lumenflow/test-baseline.json`
+2. If failure is pre-existing: warning shown, WU proceeds
+3. If failure is NEW: fix the test or add to baseline with:
+   ```bash
+   pnpm baseline:add --test "<test_name>" --reason "<why>" --fix-wu WU-XXXX
+   ```
+
+**Why:** Agents should not be blocked by unrelated failures. The ratchet ensures quality improves over time (failures can only be removed, never added without justification).
+
+---
+
 ## Mini Audit Checklist
 
 Before running `wu:done`, verify:

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`