@lumenflow/cli 2.1.2 → 2.2.0

package/dist/wu-spawn.js

@@ -53,6 +53,28 @@ const MANDATORY_TRIGGERS = {
     'beacon-guardian': ['**/prompts/**', '**/classification/**', '**/detector/**', '**/llm/**'],
 };
 const LOG_PREFIX = '[wu:spawn]';
+/**
+ * WU-1131: Truncation prevention constants
+ *
+ * These constants help detect when spawn output has been truncated during
+ * copy-paste operations or context loading. The warning banner alerts users
+ * to the truncation risk, and the end sentinel allows verification that
+ * the full output was received.
+ */
+export const TRUNCATION_WARNING_BANNER = `<!-- LUMENFLOW_TRUNCATION_WARNING -->
+<!--
+  ⚠️ CRITICAL: DO NOT TRUNCATE THIS OUTPUT
+
+  This spawn prompt MUST be copied verbatim. Truncation causes:
+  - Missing constraints (agents ignore safety rules)
+  - Missing TDD directives (agents skip tests)
+  - Degraded agent performance
+
+  VERIFICATION: The output MUST end with: <!-- LUMENFLOW_SPAWN_END -->
+  If you don't see that sentinel at the end, the output was truncated.
+-->
+`;
+export const SPAWN_END_SENTINEL = '<!-- LUMENFLOW_SPAWN_END -->';
 /**
  * Detect mandatory agents based on code paths.
  *
@@ -259,6 +281,79 @@ function generateInvariantsPriorArtSection(codePaths) {
     ];
     return lines.join('\n');
 }
+/**
+ * WU types that require TDD (failing test first)
+ */
+const TDD_REQUIRED_TYPES = ['feature', 'bug', 'tooling', 'enhancement'];
+/**
+ * WU types that require existing tests to pass (no new tests mandated)
+ */
+const EXISTING_TESTS_TYPES = ['refactor'];
+/**
+ * WU types that require smoke tests + manual QA
+ */
+const SMOKE_TEST_TYPES = ['visual', 'design', 'ui'];
+/**
+ * WU types that only need format checks (no TDD)
+ */
+const DOCS_ONLY_TYPES = ['documentation', 'docs', 'config'];
+/**
+ * Generate type-aware test guidance (WU-1142)
+ *
+ * Returns appropriate test guidance based on WU type:
+ * - feature/bug/tooling: Full TDD directive
+ * - documentation: Format check only
+ * - visual/design: Smoke test + manual QA
+ * - refactor: Existing tests must pass
+ *
+ * @param {string} wuType - WU type from YAML
+ * @returns {string} Test guidance section
+ */
+export function generateTestGuidance(wuType) {
+    const type = (wuType || 'feature').toLowerCase();
+    // Documentation WUs - no TDD, just format checks
+    if (DOCS_ONLY_TYPES.includes(type)) {
+        return `## Documentation Standards
+
+**Format check only** - No TDD required for documentation WUs.
+
+### Requirements
+
+1. Run \`pnpm gates --docs-only\` before completion
+2. Ensure markdown formatting is correct
+3. Verify links are valid
+4. Check spelling and grammar`;
+    }
+    // Visual/Design WUs - smoke tests + manual QA
+    if (SMOKE_TEST_TYPES.includes(type)) {
+        return `## Visual/Design Testing
+
+**Smoke test + manual QA** - Visual WUs require different verification.
+
+### Requirements
+
+1. Create smoke test for component rendering (if applicable)
+2. Verify visual appearance manually
+3. Test responsive behavior across breakpoints
+4. Check accessibility (keyboard navigation, screen reader)
+5. Document manual QA results in completion notes`;
+    }
+    // Refactor WUs - existing tests must pass
+    if (EXISTING_TESTS_TYPES.includes(type)) {
+        return `## Refactor Testing
+
+**Existing tests must pass** - Refactoring must not break current behavior.
+
+### Requirements
+
+1. Run all existing tests BEFORE refactoring
+2. Run all existing tests AFTER refactoring
+3. No new tests required unless behavior changes
+4. If tests fail after refactor, the refactor introduced a bug`;
+    }
+    // Default: TDD required (feature, bug, tooling, enhancement)
+    return generateTDDDirective();
+}
 /**
  * Generate the TDD directive section (WU-1585)
  *
@@ -363,6 +458,12 @@ CRITICAL RULES - ENFORCE BEFORE EVERY ACTION:
    - Use \`pnpm mem:checkpoint --wu ${id}\` to save progress before risky operations
    - Check \`pnpm mem:inbox --wu ${id}\` periodically for parallel signals from other agents
    - Checkpoint triggers (WU-1943): checkpoint after each acceptance criterion completed, checkpoint before gates, checkpoint every 30 tool calls
+
+8. SKIP-GATES AUTONOMY (WU-1142)
+   - If gates fail, first check if failure is pre-existing on main: \`git checkout main && pnpm gates\`
+   - If failure exists on main (not your change), use: \`pnpm wu:done --id ${id} --skip-gates --reason "pre-existing on main" --fix-wu WU-XXXX\`
+   - Do NOT ask for approval - autonomous skip-gates for pre-existing failures is correct
+   - This prevents getting stuck on infrastructure debt
 </constraints>`;
 }
 function generateCodexConstraints(id) {
@@ -373,7 +474,8 @@ function generateCodexConstraints(id) {
 3. **Verify before success**: run \`pnpm gates\` in the worktree, then run \`node tools/lib/agent-verification.mjs ${id}\` (from the shared checkout)
 4. **No fabrication**: if blockers remain or verification fails, report INCOMPLETE
 5. **Git workflow**: avoid merge commits; let \`pnpm wu:done\` handle completion
-6. **Scope discipline**: stay within \`code_paths\`; capture out-of-scope issues via \`pnpm mem:create\``;
+6. **Scope discipline**: stay within \`code_paths\`; capture out-of-scope issues via \`pnpm mem:create\`
+7. **Skip-gates for pre-existing**: if gates fail due to pre-existing issue on main, use \`--skip-gates --reason "pre-existing" --fix-wu WU-XXX\``;
 }
 /**
  * Generate mandatory agent advisory section
@@ -579,6 +681,45 @@ pnpm typecheck   # Check TypeScript types
 
 **Use before gates** to catch simple issues early. These are faster than full \`pnpm gates\`.`;
 }
+/**
+ * Generate Worktree Block Recovery section (WU-1134)
+ *
+ * Provides guidance for agents when they're blocked by the worktree hook.
+ * This happens when agents try to commit from main instead of the worktree.
+ *
+ * @param {string} worktreePath - Worktree path from WU YAML
+ * @returns {string} Worktree block recovery section
+ */
+export function generateWorktreeBlockRecoverySection(worktreePath) {
+    return `## When Blocked by Worktree Hook
+
+If you encounter a "worktree required" or "commit blocked" error:
+
+1. **Check existing worktrees**: \`git worktree list\`
+2. **Navigate to the worktree**: \`cd ${worktreePath || 'worktrees/<lane>-wu-xxx'}\`
+3. **Retry your operation** from within the worktree
+4. **Use relative paths only** (never absolute paths like \`/home/...\`)
+
+### Common Causes
+
+- Running \`git commit\` from main checkout instead of worktree
+- Using absolute paths that bypass worktree isolation
+- Forgetting to \`cd\` to worktree after \`wu:claim\`
+
+### Quick Fix
+
+\`\`\`bash
+# Check where you are
+pwd
+git worktree list
+
+# Navigate to your worktree
+cd ${worktreePath || 'worktrees/<lane>-wu-xxx'}
+
+# Retry your commit
+git add . && git commit -m "your message"
+\`\`\``;
+}
 /**
  * Generate Lane Selection section (WU-2107)
  *
@@ -832,10 +973,12 @@ export function generateTaskInvocation(doc, id, strategy, options = {}) {
     const codePaths = doc.code_paths || [];
     const mandatoryAgents = detectMandatoryAgents(codePaths);
     const preamble = generatePreamble(id, strategy);
-    const tddDirective = generateTDDDirective();
+    // WU-1142: Use type-aware test guidance instead of hardcoded TDD directive
+    const testGuidance = generateTestGuidance(doc.type);
     const clientContext = options.client;
     const config = options.config || getConfig();
-    const clientSkillsGuidance = generateClientSkillsGuidance(clientContext);
+    // WU-1142: Pass lane to get byLane skills
+    const clientSkillsGuidance = generateClientSkillsGuidance(clientContext, doc.lane);
     const skillsSection = generateSkillsSelectionSection(doc, config, clientContext?.name) +
         (clientSkillsGuidance ? `\n${clientSkillsGuidance}` : '');
     const clientBlocks = generateClientBlocksSection(clientContext);
@@ -859,6 +1002,8 @@ export function generateTaskInvocation(doc, id, strategy, options = {}) {
     const laneSelection = generateLaneSelectionSection();
     // WU-2362: Worktree path guidance for sub-agents
     const worktreeGuidance = generateWorktreePathGuidance(doc.worktree_path);
+    // WU-1134: Worktree block recovery guidance
+    const worktreeBlockRecovery = generateWorktreeBlockRecoverySection(doc.worktree_path);
     // Generate thinking mode sections if applicable
     const executionModeSection = generateExecutionModeSection(options);
     const thinkToolGuidance = generateThinkToolGuidance(options);
@@ -868,14 +1013,15 @@ export function generateTaskInvocation(doc, id, strategy, options = {}) {
         .join('\n\n---\n\n');
     const thinkingBlock = thinkingSections ? `${thinkingSections}\n\n---\n\n` : '';
     // Build the task prompt
-    // TDD directive appears immediately after </task> per "Lost in the Middle" research (WU-1585)
-    const taskPrompt = `<task>
+    // WU-1131: Warning banner at start, end sentinel after constraints
+    // WU-1142: Type-aware test guidance (TDD for code, format-only for docs, etc.)
+    const taskPrompt = `${TRUNCATION_WARNING_BANNER}<task>
 ${preamble}
 </task>
 
 ---
 
-${tddDirective}
+${testGuidance}
 
 ---
 
@@ -959,7 +1105,13 @@ ${laneGuidance}${laneGuidance ? '\n\n---\n\n' : ''}## Action
 
 ${generateActionSection(doc, id)}
 
-${constraints}`;
+---
+
+${worktreeBlockRecovery}
+
+${constraints}
+
+${SPAWN_END_SENTINEL}`;
     // Escape special characters for XML output
     const escapedPrompt = taskPrompt
         .replace(/&/g, '&amp;')
@@ -986,7 +1138,8 @@ export function generateCodexPrompt(doc, id, strategy, options = {}) {
     const codePaths = doc.code_paths || [];
     const mandatoryAgents = detectMandatoryAgents(codePaths);
     const preamble = generatePreamble(id, strategy);
-    const tddDirective = generateTDDDirective();
+    // WU-1142: Use type-aware test guidance instead of hardcoded TDD directive
+    const testGuidance = generateTestGuidance(doc.type);
     const mandatorySection = generateMandatoryAgentSection(mandatoryAgents, id);
     const laneGuidance = generateLaneGuidance(doc.lane);
     const bugDiscoverySection = generateBugDiscoverySection(id);
@@ -995,7 +1148,8 @@ export function generateCodexPrompt(doc, id, strategy, options = {}) {
     const constraints = generateCodexConstraints(id);
     const clientContext = options.client;
     const config = options.config || getConfig();
-    const clientSkillsGuidance = generateClientSkillsGuidance(clientContext);
+    // WU-1142: Pass lane to get byLane skills
+    const clientSkillsGuidance = generateClientSkillsGuidance(clientContext, doc.lane);
     const skillsSection = generateSkillsSelectionSection(doc, config, clientContext?.name) +
         (clientSkillsGuidance ? `\n${clientSkillsGuidance}` : '');
     const clientBlocks = generateClientBlocksSection(clientContext);
@@ -1005,9 +1159,13 @@ export function generateCodexPrompt(doc, id, strategy, options = {}) {
         .filter((section) => section.length > 0)
         .join('\n\n---\n\n');
     const thinkingBlock = thinkingSections ? `${thinkingSections}\n\n---\n\n` : '';
-    return `# ${id}: ${doc.title || 'Untitled'}
+    // WU-1134: Worktree block recovery guidance
+    const worktreeBlockRecovery = generateWorktreeBlockRecoverySection(doc.worktree_path);
+    // WU-1131: Warning banner at start, end sentinel after constraints
+    // WU-1142: Type-aware test guidance
+    return `${TRUNCATION_WARNING_BANNER}# ${id}: ${doc.title || 'Untitled'}
 
-${tddDirective}
+${testGuidance}
 
 ---
 
@@ -1062,7 +1220,13 @@ ${mandatorySection}${implementationContext ? `${implementationContext}\n\n---\n\
 
 ---
 
-${laneGuidance}${laneGuidance ? '\n\n---\n\n' : ''}${constraints}
+${laneGuidance}${laneGuidance ? '\n\n---\n\n' : ''}${worktreeBlockRecovery}
+
+---
+
+${constraints}
+
+${SPAWN_END_SENTINEL}
 `;
 }
 /**

package/dist/wu-status.d.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * WU Status Command
+ *
+ * WU-1090: Context-aware state machine for WU lifecycle commands
+ *
+ * Shows:
+ * - Current location (main checkout vs worktree)
+ * - WU state if in worktree or --id provided
+ * - Git state (branch, dirty, ahead/behind)
+ * - Valid commands for current context
+ *
+ * Usage:
+ *   pnpm wu:status              # Auto-detect from current directory
+ *   pnpm wu:status --id WU-123  # Show status for specific WU
+ */
+import type { WuContext } from '@lumenflow/core/dist/validation/types.js';
+/**
+ * Format complete status output
+ */
+export declare function formatStatusOutput(context: WuContext): string;
+/**
+ * Get exit code based on context state
+ */
+export declare function getStatusExitCode(context: WuContext): number;

package/dist/wu-unblock.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * WU Unblock Helper
+ *
+ * Sequence (micro-worktree pattern):
+ * 1) Create micro-worktree from main
+ * 2) Auto-update WU YAML/backlog/status to In Progress in micro-worktree
+ * 3) Commit in micro-worktree, push directly to origin/main
+ * 4) Optionally create a fresh work worktree/branch (default: skip unless --create-worktree)
+ *
+ * Uses micro-worktree pattern to avoid pre-commit hook blocking commits to main.
+ *
+ * Usage:
+ *   pnpm wu:unblock --id WU-334 [--reason "Dependency cleared"] [--create-worktree] [--worktree ...] [--branch ...] [--no-auto]
+ */
+export {};

package/dist/wu-unlock-lane.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * WU Unlock Lane Helper
+ *
+ * Provides a dedicated audited command for operators to safely clear lane locks.
+ *
+ * Safety-first approach:
+ * - Zombie locks (PID not running): Can be unlocked without --force
+ * - Stale locks (>24h old): Can be unlocked without --force
+ * - Active locks (recent, PID running): Require --force to unlock
+ *
+ * All unlocks require a --reason parameter for audit purposes.
+ *
+ * Usage:
+ *   pnpm wu:unlock-lane --lane "Core" --reason "Process crashed"
+ *   pnpm wu:unlock-lane --lane "Core" --reason "Emergency" --force
+ *   pnpm wu:unlock-lane --list  # List all current locks
+ */
+export {};

package/dist/wu-validate.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * WU Validation Tool
+ *
+ * Validates WU YAML files against schema and checks for quality warnings.
+ * Returns exit code 0 if valid (warnings are advisory, not blocking).
+ * Returns exit code 1 only for schema errors.
+ *
+ * Usage:
+ *   pnpm wu:validate --id WU-123         # Validate specific WU
+ *   pnpm wu:validate --all               # Validate all WUs
+ *   pnpm wu:validate --all --strict      # Fail on warnings too
+ *
+ * @see {@link tools/lib/wu-schema.mjs} - Schema definitions
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/cli",
-  "version": "2.1.2",
+  "version": "2.2.0",
   "description": "Command-line interface for LumenFlow workflow framework",
   "keywords": [
     "lumenflow",
@@ -57,6 +57,7 @@
     "mem-checkpoint": "./dist/mem-checkpoint.js",
     "mem-start": "./dist/mem-start.js",
     "mem-ready": "./dist/mem-ready.js",
+    "mem-export": "./dist/mem-export.js",
     "mem-signal": "./dist/mem-signal.js",
     "mem-cleanup": "./dist/mem-cleanup.js",
     "mem-create": "./dist/mem-create.js",
@@ -132,11 +133,11 @@
     "pretty-ms": "^9.2.0",
     "simple-git": "^3.30.0",
     "yaml": "^2.8.2",
-    "@lumenflow/core": "2.1.2",
-    "@lumenflow/metrics": "2.1.2",
-    "@lumenflow/memory": "2.1.2",
-    "@lumenflow/initiatives": "2.1.2",
-    "@lumenflow/agent": "2.1.2"
+    "@lumenflow/memory": "2.2.0",
+    "@lumenflow/metrics": "2.2.0",
+    "@lumenflow/initiatives": "2.2.0",
+    "@lumenflow/agent": "2.2.0",
+    "@lumenflow/core": "2.2.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.17",