@lumenflow/cli 3.1.2 → 3.1.3

package/dist/wu-spawn-prompt-builders.js

@@ -1,1197 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: AGPL-3.0-only
-/**
- * WU Spawn Prompt Builders
- *
- * Extracted from wu-spawn.ts (WU-1652).
- * Contains all prompt section generators, formatters, and template helpers
- * used to build spawn/handoff prompts for sub-agents.
- *
- * @module wu-spawn-prompt-builders
- */
-import { existsSync } from 'node:fs';
-import path from 'node:path';
-import { minimatch } from 'minimatch';
-// WU-2252: Import invariants loader for spawn output injection
-import { loadInvariants, INVARIANT_TYPES } from '@lumenflow/core/invariants-runner';
-import { validateSpawnArgs, generateExecutionModeSection, generateThinkToolGuidance, } from '@lumenflow/core/wu-spawn-helpers';
-import { getConfig } from '@lumenflow/core/config';
-import { generateClientSkillsGuidance, generateSkillsSelectionSection, } from '@lumenflow/core/wu-spawn-skills';
-// WU-1253: Template loader for extracted prompt templates
-// WU-1898: Import evaluateCondition to gate templates by frontmatter conditions
-import { loadTemplatesWithOverrides, replaceTokens, evaluateCondition, } from '@lumenflow/core/template-loader';
-// WU-1192: Import prompt generation from Core (single source of truth)
-// WU-1203: Import generateAgentCoordinationSection from core for config-driven progress signals
-// WU-1288: Import policy-based test guidance and mandatory standards generators
-// WU-1900: Import generateDesignContextSection for UI-classified work
-import { TRUNCATION_WARNING_BANNER, SPAWN_END_SENTINEL, generateTestGuidance, generateAgentCoordinationSection, generatePolicyBasedTestGuidance, generateMandatoryStandards, generateEnforcementSummary, generateDesignContextSection, } from '@lumenflow/core/wu-spawn';
-// WU-1900: Import work classifier for domain-aware prompt generation
-import { classifyWork } from '@lumenflow/core/work-classifier';
-// WU-1288: Import resolvePolicy for methodology policy resolution
-import { resolvePolicy } from '@lumenflow/core/resolve-policy';
-// WU-1240: Import memory context integration for spawn prompts
-import { generateMemoryContextSection, checkMemoryLayerInitialized, getMemoryContextMaxSize, } from '@lumenflow/core/wu-spawn-context';
-// Re-export core constants for backwards compatibility
-export { TRUNCATION_WARNING_BANNER, SPAWN_END_SENTINEL, generateTestGuidance, generateAgentCoordinationSection, };
-// Re-export helper functions used by orchestration layer
-export { validateSpawnArgs, generateExecutionModeSection, generateThinkToolGuidance, generateMemoryContextSection, checkMemoryLayerInitialized, getMemoryContextMaxSize, };
-// Re-export skills functions used by orchestration layer
-export { generateClientSkillsGuidance, generateSkillsSelectionSection };
-// Re-export config
-export { getConfig };
-// Re-export policy resolver
-export { resolvePolicy };
-// ─── Mandatory Agent Detection ───
-/**
- * Mandatory agent trigger patterns.
- * Mirrors MANDATORY_TRIGGERS from orchestration.constants.ts.
- *
- * Note: For LumenFlow framework development, this is empty since we don't have
- * application-specific concerns. Projects using LumenFlow
- * should configure their own triggers based on their domain requirements.
- */
-const MANDATORY_TRIGGERS = {
-// No mandatory triggers for LumenFlow framework development.
-};
-/**
- * Detect mandatory agents based on code paths.
- *
- * @param {string[]} codePaths - Array of file paths
- * @returns {string[]} Array of mandatory agent names
- */
-export function detectMandatoryAgents(codePaths) {
-    if (!codePaths || codePaths.length === 0) {
-        return [];
-    }
-    const triggeredAgents = new Set();
-    for (const [agentName, patterns] of Object.entries(MANDATORY_TRIGGERS)) {
-        const isTriggered = codePaths.some((filePath) => patterns.some((pattern) => minimatch(filePath, pattern)));
-        if (isTriggered) {
-            triggeredAgents.add(agentName);
-        }
-    }
-    return Array.from(triggeredAgents);
-}
-// ─── Formatters ───
-/**
- * Format acceptance criteria as markdown list
- *
- * @param {string[]|undefined} acceptance - Acceptance criteria array
- * @returns {string} Formatted acceptance criteria
- */
-export function formatAcceptance(acceptance) {
-    if (!acceptance || acceptance.length === 0) {
-        return '- No acceptance criteria defined';
-    }
-    return acceptance.map((item) => `- [ ] ${item}`).join('\n');
-}
-/**
- * Format spec_refs as markdown links
- *
- * @param {string[]|undefined} specRefs - Spec references array
- * @returns {string} Formatted references or empty string if none
- */
-function formatSpecRefs(specRefs) {
-    if (!specRefs || specRefs.length === 0) {
-        return '';
-    }
-    return specRefs.map((ref) => `- ${ref}`).join('\n');
-}
-/**
- * Format risks as markdown list
- *
- * @param {string[]|undefined} risks - Risks array
- * @returns {string} Formatted risks or empty string if none
- */
-function formatRisks(risks) {
-    if (!risks || risks.length === 0) {
-        return '';
-    }
-    return risks.map((risk) => `- ${risk}`).join('\n');
-}
-/**
- * Format manual tests as markdown checklist
- *
- * @param {string[]|undefined} manualTests - Manual test steps
- * @returns {string} Formatted tests or empty string if none
- */
-function formatManualTests(manualTests) {
-    if (!manualTests || manualTests.length === 0) {
-        return '';
-    }
-    return manualTests.map((test) => `- [ ] ${test}`).join('\n');
-}
-// ─── Implementation Context ───
-/**
- * Generate implementation context section (WU-1833)
- *
- * Includes spec_refs, notes, risks, and tests.manual if present.
- * Sections with no content are omitted to keep prompts lean.
- *
- * @param {object} doc - WU YAML document
- * @returns {string} Implementation context section or empty string
- */
-export function generateImplementationContext(doc) {
-    const sections = [];
-    // References (spec_refs)
-    const refs = formatSpecRefs(doc.spec_refs);
-    if (refs) {
-        sections.push(`## References\n\n${refs}`);
-    }
-    // Implementation Notes
-    if (doc.notes && doc.notes.trim()) {
-        sections.push(`## Implementation Notes\n\n${doc.notes.trim()}`);
-    }
-    // Risks
-    const risks = formatRisks(doc.risks);
-    if (risks) {
-        sections.push(`## Risks\n\n${risks}`);
-    }
-    // Manual Verification (tests.manual)
-    const manualTests = formatManualTests(doc.tests?.manual);
-    if (manualTests) {
-        sections.push(`## Manual Verification\n\n${manualTests}`);
-    }
-    if (sections.length === 0) {
-        return '';
-    }
-    return sections.join('\n\n---\n\n');
-}
-// ─── Invariants ───
-/**
- * Check if a code path matches an invariant based on type
- *
- * @param {object} invariant - Invariant definition
- * @param {string[]} codePaths - Array of code paths
- * @returns {boolean} True if code paths match the invariant
- */
-function codePathMatchesInvariant(invariant, codePaths) {
-    switch (invariant.type) {
-        case INVARIANT_TYPES.FORBIDDEN_FILE:
-        case INVARIANT_TYPES.REQUIRED_FILE: {
-            const invariantPath = invariant.path;
-            if (!invariantPath) {
-                return false;
-            }
-            return codePaths.some((p) => p === invariantPath || minimatch(p, invariantPath) || minimatch(invariantPath, p));
-        }
-        case INVARIANT_TYPES.MUTUAL_EXCLUSIVITY: {
-            const invariantPaths = invariant.paths;
-            if (!invariantPaths || invariantPaths.length === 0) {
-                return false;
-            }
-            return codePaths.some((p) => invariantPaths.some((invPath) => p === invPath || minimatch(p, invPath)));
-        }
-        case INVARIANT_TYPES.FORBIDDEN_PATTERN:
-        case INVARIANT_TYPES.REQUIRED_PATTERN:
-            return (invariant.scope?.some((scopePattern) => codePaths.some((p) => minimatch(p, scopePattern))) ?? false);
-        // WU-2254: forbidden-import uses 'from' glob instead of 'scope'
-        case INVARIANT_TYPES.FORBIDDEN_IMPORT:
-            return invariant.from ? codePaths.some((p) => minimatch(p, invariant.from)) : false;
-        default:
-            return false;
-    }
-}
-/**
- * Format a single invariant for output
- *
- * @param {object} inv - Invariant definition
- * @returns {string[]} Lines of formatted output
- */
-function formatInvariantForOutput(inv) {
-    const lines = [`### ${inv.id} (${inv.type})`, '', inv.description, ''];
-    if (inv.message) {
-        lines.push(`**Action:** ${inv.message}`, '');
-    }
-    if (inv.path) {
-        lines.push(`**Path:** \`${inv.path}\``);
-    }
-    if (inv.paths) {
-        const formattedPaths = inv.paths.map((p) => `\`${p}\``).join(', ');
-        lines.push(`**Paths:** ${formattedPaths}`);
-    }
-    // WU-2254: forbidden-import specific fields
-    if (inv.from) {
-        lines.push(`**From:** \`${inv.from}\``);
-    }
-    if (inv.cannot_import && Array.isArray(inv.cannot_import)) {
-        const formattedImports = inv.cannot_import.map((m) => `\`${m}\``).join(', ');
-        lines.push(`**Cannot Import:** ${formattedImports}`);
-    }
-    // WU-2254: required-pattern specific fields
-    if (inv.pattern &&
-        (inv.type === INVARIANT_TYPES.REQUIRED_PATTERN ||
-            inv.type === INVARIANT_TYPES.FORBIDDEN_PATTERN)) {
-        lines.push(`**Pattern:** \`${inv.pattern}\``);
-    }
-    if (inv.scope && Array.isArray(inv.scope)) {
-        const formattedScope = inv.scope.map((s) => `\`${s}\``).join(', ');
-        lines.push(`**Scope:** ${formattedScope}`);
-    }
-    lines.push('');
-    return lines;
-}
-/**
- * WU-2252: Generate invariants/prior-art section for code_paths
- *
- * Loads relevant invariants from invariants.yml and generates a section
- * that surfaces constraints and prior-art for the WU's code_paths.
- *
- * @param {string[]} codePaths - Array of code paths from the WU
- * @returns {string} Invariants/prior-art section or empty string if none relevant
- */
-export function generateInvariantsPriorArtSection(codePaths) {
-    if (!codePaths || codePaths.length === 0) {
-        return '';
-    }
-    // Try to load tools/invariants.yml
-    const invariantsPath = path.resolve('tools/invariants.yml');
-    if (!existsSync(invariantsPath)) {
-        return '';
-    }
-    let invariants;
-    try {
-        invariants = loadInvariants(invariantsPath);
-    }
-    catch {
-        return '';
-    }
-    if (!invariants || invariants.length === 0) {
-        return '';
-    }
-    // Find relevant invariants based on code_paths
-    const relevantInvariants = invariants.filter((inv) => codePathMatchesInvariant(inv, codePaths));
-    if (relevantInvariants.length === 0) {
-        return '';
-    }
-    // Format the section
-    const lines = [
-        '## Invariants/Prior-Art (WU-2252)',
-        '',
-        'The following repo invariants are relevant to your code_paths:',
-        '',
-        ...relevantInvariants.flatMap(formatInvariantForOutput),
-        '**IMPORTANT:** Do not create specs or acceptance criteria that conflict with these invariants.',
-    ];
-    return lines.join('\n');
-}
-// ─── Preamble and Constraints ───
-/**
- * Generate the context loading preamble using the strategy
- *
- * @param {string} id - WU ID
- * @param {SpawnStrategy} strategy - Client strategy
- * @returns {string} Context loading preamble
- */
-export function generatePreamble(id, strategy) {
-    return strategy.getPreamble(id);
-}
-/**
- * Generate the constraints block (appended at end per Lost in the Middle research)
- *
- * WU-2247: Aligned with LumenFlow section 7.2 (stop-and-ask) and section 7.3 (anti-loop guard).
- * Includes item 6: MEMORY LAYER COORDINATION (WU-1589).
- *
- * WU-1900: TDD CHECKPOINT (constraint 1) is now conditional. It is omitted when:
- * - Work is classified as UI domain (smoke-test methodology)
- * - Policy methodology is 'none'
- *
- * @param {string} id - WU ID
- * @param {ConstraintsOptions} options - Options for conditional constraints
- * @returns {string} Constraints block
- */
-export function generateConstraints(id, options) {
-    const includeTdd = options?.includeTddCheckpoint !== false;
-    const tddCheckpointBlock = includeTdd
-        ? `
-1. TDD CHECKPOINT (VERIFY BEFORE IMPLEMENTATION)
-   - Did you write tests BEFORE implementation?
-   - Is there at least one failing test for each acceptance criterion?
-   - Never skip the RED phase — failing tests prove the test works
-
-`
-        : '';
-    // WU-1900: Renumber constraints based on whether TDD is included
-    const antiLoopNum = includeTdd ? 2 : 1;
-    const stopAskNum = includeTdd ? 3 : 2;
-    const verifyNum = includeTdd ? 4 : 3;
-    const neverFabNum = includeTdd ? 5 : 4;
-    const gitNum = includeTdd ? 6 : 5;
-    const memNum = includeTdd ? 7 : 6;
-    const skipGatesNum = includeTdd ? 8 : 7;
-    return `---
-
-<constraints>
-CRITICAL RULES - ENFORCE BEFORE EVERY ACTION:
-${tddCheckpointBlock}${antiLoopNum}. ANTI-LOOP GUARD (LumenFlow §7.3)
-   - Max 3 attempts per unique error before escalating
-   - If same error repeats 3x, STOP and report with full context
-   - Retry with different approach, not same command
-
-${stopAskNum}. STOP-AND-ASK TRIGGERS (LumenFlow §7.2 - narrow scope)
-   - Policy changes, auth/permissions modifications
-   - PII/safety issues, cloud spend, secrets, backups
-   - Same error repeats 3x
-   - For ordinary errors: fix and retry autonomously (up to 3 attempts)
-
-${verifyNum}. VERIFY COMPLETION before reporting success
-   - Run: node packages/@lumenflow/agent/dist/agent-verification.js ${id} (from shared checkout)
-   - Exit 0 = passed, Exit 1 = INCOMPLETE
-   - Never report "done" if verification fails
-
-${neverFabNum}. NEVER FABRICATE COMPLETION
-   - If blockers remain, report INCOMPLETE
-   - If verification fails, summarize failures
-   - Honesty over false completion
-
-${gitNum}. GIT WORKFLOW (CRITICAL - GitHub rules reject merge commits)
-   - GitHub REJECTS merge commits on main
-   - ALWAYS use \`git rebase origin/main\` before push
-   - Push to main via \`git push origin lane/...:main\` (fast-forward only)
-   - NEVER use \`git merge\` on main branch
-   - Let \`pnpm wu:done\` handle the merge workflow
-
-${memNum}. MEMORY LAYER COORDINATION (INIT-007)
-   - 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
-
-${skipGatesNum}. 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>`;
-}
-export function generateCodexConstraints(id) {
-    return `## Constraints (Critical)
-
-1. **TDD checkpoint**: tests BEFORE implementation; never skip RED
-2. **Stop on errors**: if UnsafeAny command fails, report BLOCKED (never DONE) with the error
-3. **Verify before success**: run \`pnpm gates\` in the worktree, then run \`node packages/@lumenflow/agent/dist/agent-verification.js ${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\`
-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\``;
-}
-// ─── Section Generators ───
-/**
- * Generate mandatory agent advisory section
- *
- * @param {string[]} mandatoryAgents - Array of mandatory agent names
- * @param {string} _id - WU ID (reserved for future use)
- * @returns {string} Mandatory agent section or empty string
- */
-export function generateMandatoryAgentSection(mandatoryAgents, _id) {
-    if (mandatoryAgents.length === 0) {
-        return '';
-    }
-    const agentList = mandatoryAgents.map((agent) => `  - ${agent}`).join('\n');
-    return `
-## Mandatory Agents (MUST invoke before wu:done)
-
-Based on code_paths, the following agents MUST be invoked:
-
-${agentList}
-
-Run: pnpm orchestrate:monitor to check agent status
-`;
-}
-/**
- * Generate effort scaling rules section (WU-1986)
- *
- * Based on Anthropic multi-agent research: helps agents decide when to
- * spawn sub-agents vs handle inline.
- *
- * @returns {string} Effort scaling section
- */
-export function generateEffortScalingRules() {
-    return `## Effort Scaling (When to Spawn Sub-Agents)
-
-Use this heuristic to decide complexity:
-
-| Complexity | Approach | Tool Calls |
-|------------|----------|------------|
-| **Simple** (single file, <50 lines) | Handle inline | 3-10 |
-| **Moderate** (2-3 files, clear scope) | Handle inline | 10-20 |
-| **Complex** (4+ files, exploration needed) | Spawn Explore agent first | 20+ |
-| **Multi-domain** (cross-cutting concerns) | Spawn specialized sub-agents | Varies |
-
-**Rule**: If you need >30 tool calls for a subtask, consider spawning a sub-agent with a focused scope.`;
-}
-/**
- * Generate parallel tool call guidance (WU-1986)
- *
- * Based on Anthropic research: 3+ parallel tool calls significantly improve performance.
- *
- * @returns {string} Parallel tool call guidance
- */
-export function generateParallelToolCallGuidance() {
-    return `## Parallel Tool Calls (Performance)
-
-**IMPORTANT**: Make 3+ tool calls in parallel when operations are independent.
-
-Good examples:
-- Reading multiple files simultaneously
-- Running independent grep searches
-- Spawning multiple Explore agents for different areas
-
-Bad examples:
-- Reading a file then editing it (sequential dependency)
-- Running tests then checking results (sequential)
-
-Parallelism reduces latency by 50-90% for complex tasks.`;
-}
-/**
- * Generate iterative search heuristics (WU-1986)
- *
- * Based on Anthropic research: start broad, narrow focus.
- *
- * @returns {string} Search heuristics section
- */
-export function generateIterativeSearchHeuristics() {
-    return `## Search Strategy (Broad to Narrow)
-
-When exploring the codebase:
-
-1. **Start broad**: Use Explore agent or glob patterns to understand structure
-2. **Evaluate findings**: What patterns exist? What's relevant?
-3. **Narrow focus**: Target specific files/functions based on findings
-4. **Iterate**: Refine if initial approach misses the target
-
-Avoid: Jumping directly to specific file edits without understanding context.`;
-}
-/**
- * Generate token budget awareness section (WU-1986)
- *
- * @param {string} id - WU ID
- * @returns {string} Token budget section
- */
-export function generateTokenBudgetAwareness(id) {
-    return `## Token Budget Awareness
-
-Context limit is ~200K tokens. Monitor your usage:
-
-- **At 50+ tool calls**: Create a checkpoint (\`pnpm mem:checkpoint --wu ${id}\`)
-- **At 100+ tool calls**: Consider spawning fresh sub-agent with focused scope
-- **Before risky operations**: Always checkpoint first
-
-If approaching limits, summarize progress and spawn continuation agent.`;
-}
-/**
- * Generate structured completion format (WU-1986)
- *
- * @param {string} id - WU ID
- * @returns {string} Completion format section
- */
-export function generateCompletionFormat(_id) {
-    return `## Completion Report Format
-
-When finishing, provide structured output:
-
-\`\`\`
-## Summary
-<1-3 sentences describing what was accomplished>
-
-## Artifacts
-- Files modified: <list>
-- Tests added: <list>
-- Documentation updated: <list>
-
-## Verification
-- Gates: <pass/fail>
-- Tests: <X passing, Y failing>
-
-## Blockers (if UnsafeAny)
-- <blocker description>
-
-## Follow-up (if needed)
-- <suggested next WU or action>
-\`\`\`
-
-This format enables orchestrator to track progress across waves.`;
-}
-/**
- * Generate quick fix commands section (WU-1987)
- *
- * Provides format/lint/typecheck commands for quick fixes before gates.
- *
- * @returns {string} Quick fix commands section
- */
-export function generateQuickFixCommands() {
-    return `## Quick Fix Commands
-
-If gates fail, try these before investigating:
-
-\`\`\`bash
-pnpm format      # Auto-fix formatting issues
-pnpm lint        # Check linting (use --fix for auto-fix)
-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 starting with /)
-
-### 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)
- *
- * Provides guidance on lane selection when creating new WUs.
- * Points agents to wu:infer-lane for automated lane suggestions.
- *
- * @returns {string} Lane Selection section
- */
-export function generateLaneSelectionSection() {
-    return `## Lane Selection
-
-When creating new WUs, use the correct lane to enable parallelization:
-
-\`\`\`bash
-# Get lane suggestion based on code paths and description
-pnpm wu:infer-lane --id WU-XXX
-
-# Or infer from manual inputs
-pnpm wu:infer-lane --paths "tools/**" --desc "CLI improvements"
-\`\`\`
-
-**Lane taxonomy**: See \`.lumenflow.lane-inference.yaml\` for valid lanes and patterns.
-
-**Why lanes matter**: WIP=1 per lane means correct lane selection enables parallel work across lanes.`;
-}
-/**
- * Generate Worktree Path Guidance section (WU-2362)
- *
- * Provides guidance for sub-agents on working within worktrees, including
- * how to determine the worktree root and where to create stamps.
- *
- * Problem: CLAUDE_PROJECT_DIR is hook-only; sub-agents inherit parent cwd (main).
- * Solution: Use git rev-parse --show-toplevel to determine actual worktree root.
- *
- * @param {string|undefined} worktreePath - Worktree path from WU YAML
- * @returns {string} Worktree path guidance section
- */
-export function generateWorktreePathGuidance(worktreePath) {
-    if (!worktreePath) {
-        return '';
-    }
-    return `## Worktree Path Guidance (WU-2362)
-
-**Your worktree:** \`${worktreePath}\`
-
-### Finding the Worktree Root
-
-Sub-agents may inherit the parent's cwd (main checkout). To find the actual worktree root:
-
-\`\`\`bash
-# Get the worktree root (not main checkout)
-git rev-parse --show-toplevel
-\`\`\`
-
-### Stamp Creation
-
-When creating \`.lumenflow/\` stamps or other artifacts:
-
-1. **ALWAYS** create stamps in the **worktree**, not main
-2. Use \`git rev-parse --show-toplevel\` to get the correct base path
-3. Stamps created on main will be lost when the worktree merges
-
-\`\`\`bash
-# CORRECT: Create stamp in worktree
-WORKTREE_ROOT=$(git rev-parse --show-toplevel)
-mkdir -p "$WORKTREE_ROOT/.lumenflow/agent-runs"
-touch "$WORKTREE_ROOT/.lumenflow/agent-runs/code-reviewer.stamp"
-
-# WRONG: Hardcoded path to main
-# touch /path/to/main/.lumenflow/agent-runs/code-reviewer.stamp
-\`\`\`
-
-### Why This Matters
-
-- Stamps on main get overwritten by worktree merge
-- \`wu:done\` validates stamps exist in the worktree branch
-- Parallel WUs in other lanes won't see your stamps if on main`;
-}
-/**
- * Generate the Bug Discovery section (WU-1592, WU-2284)
- *
- * Instructs sub-agents to capture bugs found mid-WU via mem:create.
- * This enables scope-creep tracking and ensures discovered bugs
- * are not lost when agents encounter issues outside their WU scope.
- *
- * WU-2284: Added explicit prohibition against using wu:create directly
- * for discovered issues. Agents must use mem:create for capture, then
- * human triage decides whether to promote to a WU.
- *
- * @param {string} id - WU ID
- * @returns {string} Bug Discovery section
- */
-export function generateBugDiscoverySection(id) {
-    return `## Bug Discovery (Mid-WU Issue Capture)
-
-If you discover a bug or issue **outside the scope of this WU**:
-
-1. **Capture it immediately** using:
-   \`\`\`bash
-   pnpm mem:create 'Bug: <description>' --type discovery --tags bug,scope-creep --wu ${id}
-   \`\`\`
-
-2. **Continue with your WU** — do not fix bugs outside your scope
-3. **Reference in notes** — mention the mem node ID in your completion notes
-
-### NEVER use wu:create for discovered issues
-
-**Do NOT use \`wu:create\` directly for bugs discovered mid-WU.**
-
-- \`mem:create\` = **capture** (immediate, no human approval needed)
-- \`wu:create\` = **planned work** (requires human triage and approval)
-
-Discovered issues MUST go through human triage before becoming WUs.
-Using \`wu:create\` directly bypasses the triage workflow and creates
-unreviewed work items.
-
-### When to Capture
-
-- Found a bug in code NOT in your \`code_paths\`
-- Discovered an issue that would require >10 lines to fix
-- Encountered broken behaviour unrelated to your acceptance criteria
-
-### Triage Workflow
-
-After WU completion, bugs can be promoted to Bug WUs by humans:
-\`\`\`bash
-pnpm mem:triage --wu ${id}           # List discoveries for this WU
-pnpm mem:triage --promote <node-id> --lane "<lane>"  # Create Bug WU (human action)
-\`\`\`
-
-See: https://lumenflow.dev/reference/agent-invocation-guide/ §Bug Discovery`;
-}
-/**
- * Generate lane-specific guidance
- *
- * @param {string} lane - Lane name
- * @returns {string} Lane-specific guidance or empty string
- */
-export function generateLaneGuidance(lane) {
-    if (!lane)
-        return '';
-    const laneParent = lane.split(':')[0].trim();
-    const guidance = {
-        Operations: `## Lane-Specific: Tooling
-
-- Update tool documentation in tools/README.md or relevant docs if adding new CLI commands`,
-        Intelligence: `## Lane-Specific: Intelligence
-
-- All prompt changes require golden dataset evaluation (pnpm prompts:eval)
-- Follow prompt versioning guidelines in ai/prompts/README.md`,
-        Experience: `## Lane-Specific: Experience
-
-- Follow design system tokens defined in the project
-- Ensure accessibility compliance (WCAG 2.1 AA)`,
-        Core: `## Lane-Specific: Core
-
-- Maintain hexagonal architecture boundaries
-- Update domain model documentation if changing entities`,
-    };
-    return guidance[laneParent] || '';
-}
-/**
- * Generate the Action section based on WU claim status (WU-1745).
- *
- * If WU is already claimed (has claimed_at and worktree_path), tells agent
- * to continue in the existing worktree.
- *
- * If WU is unclaimed (status: ready), tells agent to run wu:claim first.
- *
- * @param {object} doc - WU YAML document
- * @param {string} id - WU ID
- * @returns {string} Action section content
- */
-export function generateActionSection(doc, id) {
-    const isAlreadyClaimed = doc.claimed_at && doc.worktree_path;
-    if (isAlreadyClaimed) {
-        return `This WU is already claimed. Continue implementation in worktree following all standards above.
-
-cd ${doc.worktree_path}`;
-    }
-    // WU is unclaimed - agent needs to claim first
-    const laneSlug = (doc.lane || 'unknown')
-        .toLowerCase()
-        .replace(/[:\s]+/g, '-')
-        .replace(/-+/g, '-');
-    return `**FIRST: Claim this WU before starting work:**
-
-\`\`\`bash
-pnpm wu:claim --id ${id} --lane "${doc.lane}"
-cd worktrees/${laneSlug}-${id.toLowerCase()}
-\`\`\`
-
-Then implement following all standards above.
-
-**CRITICAL:** Never use \`git worktree add\` directly. Always use \`pnpm wu:claim\` to ensure:
-- Event tracking in .lumenflow/state/wu-events.jsonl
-- Lane lock acquisition (WIP=1 enforcement)
-- Session tracking for context recovery`;
-}
-/**
- * Generate the Completion Workflow section for sub-agents (WU-2682).
- *
- * Explicitly instructs sub-agents to run wu:done autonomously after gates pass.
- * This prevents agents from asking permission instead of completing.
- *
- * @param {string} id - WU ID
- * @returns {string} Completion Workflow section
- */
-export function generateCompletionWorkflowSection(id) {
-    return `## Completion Workflow
-
-**CRITICAL: Complete autonomously. Do NOT ask for permission.**
-
-After all acceptance criteria are satisfied:
-
-1. Run gates in the worktree: \`pnpm gates\`
-2. If gates pass, cd back to main checkout
-3. Run: \`pnpm wu:done --id ${id}\`
-
-\`\`\`bash
-# From worktree, after gates pass:
-cd /path/to/main  # NOT the worktree
-pnpm wu:done --id ${id}
-\`\`\`
-
-**wu:done** handles: merge to main, stamp creation, worktree cleanup.
-
-**Do not ask** "should I run wu:done?" — just run it when gates pass.`;
-}
-export function generateClientBlocksSection(clientContext) {
-    if (!clientContext?.config?.blocks?.length)
-        return '';
-    const blocks = clientContext.config.blocks
-        .map((block) => `### ${block.title}\n\n${block.content}`)
-        .join('\n\n');
-    return `## Client Guidance (${clientContext.name})\n\n${blocks}`;
-}
-// ─── Template Helpers ───
-/**
- * WU-1253: Try to load templates for spawn prompt sections.
- * WU-1898: Evaluates frontmatter conditions before including templates.
- *
- * Implements shadow mode: tries templates first, returns empty map
- * if templates aren't available (caller uses hardcoded fallback).
- *
- * Templates with conditions (e.g., "type !== 'documentation'") are
- * evaluated against the provided context. Templates whose condition
- * evaluates to false are excluded from the result map.
- *
- * @param clientName - Client name for overrides (e.g., 'claude-code', 'cursor')
- * @param context - Token values for replacement and condition evaluation
- * @returns Map of template id to processed content, empty if templates unavailable
- */
-export function tryLoadTemplates(clientName, context) {
-    const result = new Map();
-    try {
-        const baseDir = process.cwd();
-        const templates = loadTemplatesWithOverrides(baseDir, clientName);
-        // WU-1898: Evaluate frontmatter conditions before including templates
-        for (const [id, template] of templates) {
-            const condition = template.frontmatter.condition;
-            if (!evaluateCondition(condition, context)) {
-                continue;
-            }
-            const processed = replaceTokens(template.content, context);
-            result.set(id, processed);
-        }
-    }
-    catch {
-        // Template loading failed - return empty map for hardcoded fallback
-    }
-    return result;
-}
-/**
- * WU-1253: Build template context from WU document.
- * WU-1898: Accepts optional policy for condition evaluation of methodology templates.
- *
- * @param doc - WU YAML document
- * @param id - WU ID
- * @param policy - Optional resolved policy for methodology condition evaluation
- * @returns Context for template token replacement and condition evaluation
- */
-export function buildSpawnTemplateContext(doc, id, policy) {
-    const lane = doc.lane || '';
-    const laneParent = lane.split(':')[0]?.trim() || '';
-    const type = (doc.type || 'feature').toLowerCase();
-    const context = {
-        WU_ID: id,
-        LANE: lane,
-        TYPE: type,
-        TITLE: doc.title || '',
-        DESCRIPTION: doc.description || '',
-        WORKTREE_PATH: doc.worktree_path || '',
-        laneParent,
-        // Lowercase aliases for condition evaluation
-        type,
-        lane,
-        worktreePath: doc.worktree_path || '',
-    };
-    // WU-1898: Add policy fields for methodology template condition evaluation
-    if (policy) {
-        context['policy.testing'] = policy.testing;
-        context['policy.architecture'] = policy.architecture;
-    }
-    return context;
-}
-// ─── Full Prompt Generators ───
-/**
- * Generate the complete Task tool invocation
- *
- * @param {object} doc - WU YAML document
- * @param {string} id - WU ID
- * @param {SpawnStrategy} strategy - Client strategy
- * @param {object} [options={}] - Thinking mode options
- * @param {boolean} [options.thinking] - Whether extended thinking is enabled
- * @param {boolean} [options.noThinking] - Whether thinking is explicitly disabled
- * @param {string} [options.budget] - Token budget for thinking
- * @returns {string} Complete Task tool invocation
- */
-export function generateTaskInvocation(doc, id, strategy, options = {}) {
-    const codePaths = doc.code_paths || [];
-    const mandatoryAgents = detectMandatoryAgents(codePaths);
-    const preamble = generatePreamble(id, strategy);
-    const clientContext = options.client;
-    const config = options.config || getConfig();
-    // WU-1288: Resolve methodology policy from config
-    // WU-1898: Moved before template loading so policy is available for condition evaluation
-    const policy = resolvePolicy(config);
-    // WU-1900: Run work classifier for domain-aware prompt generation
-    const classificationConfig = config?.methodology?.work_classification;
-    const classification = classifyWork({
-        code_paths: doc.code_paths,
-        lane: doc.lane,
-        type: doc.type,
-        description: doc.description,
-    }, classificationConfig);
-    // WU-1253: Try loading templates (shadow mode - falls back to hardcoded if unavailable)
-    // WU-1681: Use resolved client from caller; fall back for template loading only
-    // WU-1898: Pass policy to context for methodology template condition evaluation
-    const clientName = options.client?.name || 'claude-code';
-    const templateContext = buildSpawnTemplateContext(doc, id, policy);
-    const templates = tryLoadTemplates(clientName, templateContext);
-    // WU-1142: Use type-aware test guidance instead of hardcoded TDD directive
-    // WU-1288: Use policy-based test guidance that respects methodology.testing config
-    // WU-1253: Try template first, fall back to policy-based guidance
-    // WU-1900: Pass classifier hint to test guidance
-    const testGuidance = templates.get('tdd-directive') ||
-        generatePolicyBasedTestGuidance(doc.type || 'feature', policy, {
-            testMethodologyHint: classification.testMethodologyHint,
-        });
-    // WU-1288: Generate enforcement summary from resolved policy
-    const enforcementSummary = generateEnforcementSummary(policy);
-    // WU-1288: Generate mandatory standards based on resolved policy
-    const mandatoryStandards = generateMandatoryStandards(policy);
-    // WU-1142: Pass lane to get byLane skills
-    const clientSkillsGuidance = generateClientSkillsGuidance(clientContext, doc.lane);
-    // WU-1253: Try template for skills-selection, build skills section
-    const skillsTemplateContent = templates.get('skills-selection');
-    const skillsGuidanceSuffix = clientSkillsGuidance ? '\n' + clientSkillsGuidance : '';
-    const skillsBaseContent = skillsTemplateContent || generateSkillsSelectionSection(doc, config, clientContext?.name);
-    const skillsSection = skillsBaseContent + skillsGuidanceSuffix;
-    const clientBlocks = generateClientBlocksSection(clientContext);
-    const mandatorySection = generateMandatoryAgentSection(mandatoryAgents, id);
-    const laneGuidance = generateLaneGuidance(doc.lane);
-    // WU-1253: Try template for bug-discovery
-    const bugDiscoverySection = templates.get('bug-discovery') || generateBugDiscoverySection(id);
-    // WU-1253: Try template for constraints
-    // WU-1900: Generate constraints with conditional TDD CHECKPOINT
-    const shouldIncludeTddCheckpoint = classification.domain !== 'ui' && policy.testing !== 'none';
-    const constraints = templates.get('constraints') ||
-        generateConstraints(id, {
-            includeTddCheckpoint: shouldIncludeTddCheckpoint,
-        });
-    const implementationContext = generateImplementationContext(doc);
-    // WU-1900: Generate design context section for UI-classified work
-    const designContextSection = generateDesignContextSection(classification);
-    // WU-2252: Generate invariants/prior-art section for code_paths
-    const invariantsPriorArt = generateInvariantsPriorArtSection(codePaths);
-    // WU-1986: Anthropic multi-agent best practices sections
-    // WU-1253: Try templates for these sections
-    const effortScaling = templates.get('effort-scaling') || generateEffortScalingRules();
-    const parallelToolCalls = templates.get('parallel-tool-calls') || generateParallelToolCallGuidance();
-    const searchHeuristics = templates.get('search-heuristics') || generateIterativeSearchHeuristics();
-    const tokenBudget = templates.get('token-budget') || generateTokenBudgetAwareness(id);
-    const completionFormat = generateCompletionFormat(id);
-    // WU-1987: Agent coordination and quick fix sections
-    const agentCoordination = generateAgentCoordinationSection(id);
-    // WU-1253: Try template for quick-fix-commands
-    const quickFix = templates.get('quick-fix-commands') || generateQuickFixCommands();
-    // WU-2107: Lane selection guidance
-    // WU-1253: Try template for lane-selection
-    const laneSelection = templates.get('lane-selection') || generateLaneSelectionSection();
-    // WU-2362: Worktree path guidance for sub-agents
-    const worktreeGuidance = generateWorktreePathGuidance(doc.worktree_path);
-    const worktreePathHint = doc.worktree_path || `worktrees/<lane>-${id.toLowerCase()}`;
-    // WU-1134: Worktree block recovery guidance
-    // WU-1253: Try template for worktree-recovery
-    const worktreeBlockRecovery = templates.get('worktree-recovery') || generateWorktreeBlockRecoverySection(worktreePathHint);
-    // WU-1240: Memory context section
-    // Include if explicitly enabled and not disabled via noContext
-    const shouldIncludeMemoryContext = options.includeMemoryContext && !options.noContext;
-    const memoryContextSection = shouldIncludeMemoryContext ? options.memoryContextContent || '' : '';
-    // Generate thinking mode sections if applicable
-    const executionModeSection = generateExecutionModeSection(options);
-    const thinkToolGuidance = generateThinkToolGuidance(options);
-    // Build optional sections string
-    const thinkingSections = [executionModeSection, thinkToolGuidance]
-        .filter((section) => section.length > 0)
-        .join('\n\n---\n\n');
-    const thinkingBlock = thinkingSections ? `${thinkingSections}\n\n---\n\n` : '';
-    // Build the task prompt
-    // 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>
-
----
-
-${testGuidance}
-
----
-
-# ${id}: ${doc.title || 'Untitled'}
-
-## WU Details
-
-- **ID:** ${id}
-- **Lane:** ${doc.lane || 'Unknown'}
-- **Type:** ${doc.type || 'feature'}
-- **Status:** ${doc.status || 'unknown'}
-- **Worktree:** ${doc.worktree_path || `worktrees/<lane>-${id.toLowerCase()}`}
-
-## Description
-
-${doc.description || 'No description provided.'}
-
-## Acceptance Criteria
-
-${formatAcceptance(doc.acceptance)}
-
-## Code Paths
-
-${codePaths.length > 0 ? codePaths.map((p) => `- ${p}`).join('\n') : '- No code paths defined'}
-${mandatorySection}${invariantsPriorArt ? `---\n\n${invariantsPriorArt}\n\n` : ''}${implementationContext ? `---\n\n${implementationContext}\n\n` : ''}---
-
-${thinkingBlock}${skillsSection}
-${memoryContextSection ? `---\n\n${memoryContextSection}\n\n` : ''}---
-
-${mandatoryStandards}
-
----
-
-${enforcementSummary}
-
-${designContextSection ? `---\n\n${designContextSection}\n\n` : ''}${clientBlocks ? `---\n\n${clientBlocks}\n\n` : ''}${worktreeGuidance ? `---\n\n${worktreeGuidance}\n\n` : ''}---
-
-${bugDiscoverySection}
-
----
-
-${effortScaling}
-
----
-
-${parallelToolCalls}
-
----
-
-${searchHeuristics}
-
----
-
-${tokenBudget}
-
----
-
-${completionFormat}
-
----
-
-${agentCoordination}
-
----
-
-${quickFix}
-
----
-
-${laneSelection}
-
----
-
-${laneGuidance}${laneGuidance ? '\n\n---\n\n' : ''}## Action
-
-${generateActionSection(doc, id)}
-
----
-
-${worktreeBlockRecovery}
-
-${constraints}
-
-${SPAWN_END_SENTINEL}`;
-    // Escape special characters for XML output
-    const escapedPrompt = taskPrompt
-        .replace(/&/g, '&amp;')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;');
-    // Build the Task tool invocation block using antml format
-    // Using array join to avoid XML parsing issues
-    const openTag = '<' + 'antml:invoke name="Task">';
-    const closeTag = '</' + 'antml:invoke>';
-    const paramOpen = '<' + 'antml:parameter name="';
-    const paramClose = '</' + 'antml:parameter>';
-    const invocation = [
-        '<' + 'antml:function_calls>',
-        openTag,
-        `${paramOpen}subagent_type">general-purpose${paramClose}`,
-        `${paramOpen}description">Execute ${id}${paramClose}`,
-        `${paramOpen}prompt">${escapedPrompt}${paramClose}`,
-        closeTag,
-        '</' + 'antml:function_calls>',
-    ].join('\n');
-    return invocation;
-}
-export function generateCodexPrompt(doc, id, strategy, options = {}) {
-    const codePaths = doc.code_paths || [];
-    const mandatoryAgents = detectMandatoryAgents(codePaths);
-    const preamble = generatePreamble(id, strategy);
-    // WU-1142: Use type-aware test guidance instead of hardcoded TDD directive
-    const testGuidance = generateTestGuidance(doc.type || 'feature');
-    const mandatorySection = generateMandatoryAgentSection(mandatoryAgents, id);
-    const laneGuidance = generateLaneGuidance(doc.lane);
-    const bugDiscoverySection = generateBugDiscoverySection(id);
-    const implementationContext = generateImplementationContext(doc);
-    const action = generateActionSection(doc, id);
-    const constraints = generateCodexConstraints(id);
-    const clientContext = options.client;
-    const config = options.config || getConfig();
-    // 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);
-    const executionModeSection = generateExecutionModeSection(options);
-    const thinkToolGuidance = generateThinkToolGuidance(options);
-    const thinkingSections = [executionModeSection, thinkToolGuidance]
-        .filter((section) => section.length > 0)
-        .join('\n\n---\n\n');
-    const thinkingBlock = thinkingSections ? `${thinkingSections}\n\n---\n\n` : '';
-    // WU-1134: Worktree block recovery guidance
-    const worktreePathHint = doc.worktree_path || `worktrees/<lane>-${id.toLowerCase()}`;
-    const worktreeBlockRecovery = generateWorktreeBlockRecoverySection(worktreePathHint);
-    // WU-1240: Memory context section
-    const shouldIncludeMemoryContext = options.includeMemoryContext && !options.noContext;
-    const memoryContextSection = shouldIncludeMemoryContext ? options.memoryContextContent || '' : '';
-    // WU-1131: Warning banner at start, end sentinel after constraints
-    // WU-1142: Type-aware test guidance
-    return `${TRUNCATION_WARNING_BANNER}# ${id}: ${doc.title || 'Untitled'}
-
-${testGuidance}
-
----
-
-## Context
-
-${preamble}
-
----
-
-## WU Details
-
-- **ID:** ${id}
-- **Lane:** ${doc.lane || 'Unknown'}
-- **Type:** ${doc.type || 'feature'}
-- **Status:** ${doc.status || 'unknown'}
-- **Worktree:** ${doc.worktree_path || `worktrees/<lane>-${id.toLowerCase()}`}
-
-## Description
-
-${doc.description || 'No description provided.'}
-
-## Scope (code_paths)
-
-Only change files within these paths:
-
-${codePaths.length > 0 ? codePaths.map((p) => `- ${p}`).join('\n') : '- No code paths defined'}
-
-## Acceptance Criteria
-
-${formatAcceptance(doc.acceptance)}
-
----
-
-${skillsSection}
-${memoryContextSection ? `---\n\n${memoryContextSection}\n\n` : ''}---
-
-## Action
-
-${action}
-
----
-
-## Verification
-
-- Run in worktree: \`pnpm gates\`
-- From shared checkout: \`node packages/@lumenflow/agent/dist/agent-verification.js ${id}\`
-
----
-
-${mandatorySection}${implementationContext ? `${implementationContext}\n\n---\n\n` : ''}${clientBlocks ? `${clientBlocks}\n\n---\n\n` : ''}${thinkingBlock}${bugDiscoverySection}
-
----
-
-${laneGuidance}${laneGuidance ? '\n\n---\n\n' : ''}${worktreeBlockRecovery}
-
----
-
-${constraints}
-
-${SPAWN_END_SENTINEL}
-`;
-}
-//# sourceMappingURL=wu-spawn-prompt-builders.js.map