@lumenflow/core 3.2.0 → 3.2.1

package/dist/section-headings.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Default section headings (fallbacks when frontmatter is missing)
+ * Re-exports from wu-constants.ts for backwards compatibility
+ */
+export declare const DEFAULT_SECTION_HEADINGS: {
+    backlog: {
+        ready: string;
+        in_progress: string;
+        blocked: string;
+        done: string;
+    };
+    status: {
+        in_progress: string;
+        completed: string;
+        blocked: string;
+    };
+};
+/**
+ * Get section headings with frontmatter override + defaults
+ *
+ * Replaces scattered pattern: headings.done || '## ✅ Done'
+ * Centralizes fallback logic for consistent heading resolution
+ *
+ * @param {object|null} frontmatter - Parsed frontmatter from backlog.md/status.md
+ * @param {'backlog'|'status'} docType - Document type
+ * @returns {object} Section headings (configured or default)
+ */
+export declare function getSectionHeadingsWithDefaults(frontmatter: UnsafeAny, docType?: keyof typeof DEFAULT_SECTION_HEADINGS): {
+    ready: string;
+    in_progress: string;
+    blocked: string;
+    done: string;
+    completed: string;
+};
+//# sourceMappingURL=section-headings.d.ts.map

package/dist/section-headings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"section-headings.d.ts","sourceRoot":"","sources":["../src/section-headings.ts"],"names":[],"mappings":"AAgBA;;;GAGG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;CAYpC,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,8BAA8B,CAC5C,WAAW,EAAE,SAAS,EACtB,OAAO,GAAE,MAAM,OAAO,wBAAoC;;;;;;EAsB3D"}

package/dist/section-headings.js

@@ -0,0 +1,54 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Section Headings Constants
+ *
+ * Centralized section heading defaults for backlog.md and status.md
+ * Eliminates magic strings scattered throughout wu-* tools
+ *
+ * Usage: Use getSectionHeadingsWithDefaults() to get frontmatter-configured
+ * headings with sensible fallbacks if frontmatter is missing/malformed
+ */
+import { getSectionHeadings } from './backlog-parser.js';
+import { BACKLOG_SECTIONS, STATUS_SECTIONS } from './wu-constants.js';
+/**
+ * Default section headings (fallbacks when frontmatter is missing)
+ * Re-exports from wu-constants.ts for backwards compatibility
+ */
+export const DEFAULT_SECTION_HEADINGS = {
+    backlog: {
+        ready: BACKLOG_SECTIONS.READY,
+        in_progress: BACKLOG_SECTIONS.IN_PROGRESS,
+        blocked: BACKLOG_SECTIONS.BLOCKED,
+        done: BACKLOG_SECTIONS.DONE,
+    },
+    status: {
+        in_progress: STATUS_SECTIONS.IN_PROGRESS,
+        completed: STATUS_SECTIONS.COMPLETED,
+        blocked: STATUS_SECTIONS.BLOCKED,
+    },
+};
+/**
+ * Get section headings with frontmatter override + defaults
+ *
+ * Replaces scattered pattern: headings.done || '## ✅ Done'
+ * Centralizes fallback logic for consistent heading resolution
+ *
+ * @param {object|null} frontmatter - Parsed frontmatter from backlog.md/status.md
+ * @param {'backlog'|'status'} docType - Document type
+ * @returns {object} Section headings (configured or default)
+ */
+export function getSectionHeadingsWithDefaults(frontmatter, docType = 'backlog') {
+    const defaults = DEFAULT_SECTION_HEADINGS[docType];
+    const configured = frontmatter ? getSectionHeadings(frontmatter) : {};
+    return {
+        ready: configured.ready || defaults.ready || DEFAULT_SECTION_HEADINGS.backlog.ready,
+        in_progress: configured.in_progress ||
+            defaults.in_progress ||
+            DEFAULT_SECTION_HEADINGS.backlog.in_progress,
+        blocked: configured.blocked || defaults.blocked || DEFAULT_SECTION_HEADINGS.backlog.blocked,
+        done: configured.done || defaults.done || DEFAULT_SECTION_HEADINGS.backlog.done,
+        completed: configured.completed || defaults.completed || DEFAULT_SECTION_HEADINGS.status.completed,
+    };
+}
+//# sourceMappingURL=section-headings.js.map

package/dist/section-headings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"section-headings.js","sourceRoot":"","sources":["../src/section-headings.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC;AAEzC;;;;;;;;GAQG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEtE;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,OAAO,EAAE;QACP,KAAK,EAAE,gBAAgB,CAAC,KAAK;QAC7B,WAAW,EAAE,gBAAgB,CAAC,WAAW;QACzC,OAAO,EAAE,gBAAgB,CAAC,OAAO;QACjC,IAAI,EAAE,gBAAgB,CAAC,IAAI;KAC5B;IACD,MAAM,EAAE;QACN,WAAW,EAAE,eAAe,CAAC,WAAW;QACxC,SAAS,EAAE,eAAe,CAAC,SAAS;QACpC,OAAO,EAAE,eAAe,CAAC,OAAO;KACjC;CACF,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,UAAU,8BAA8B,CAC5C,WAAsB,EACtB,UAAiD,SAAS;IAE1D,MAAM,QAAQ,GAAG,wBAAwB,CAAC,OAAO,CAMhD,CAAC;IACF,MAAM,UAAU,GAAG,WAAW,CAAC,CAAC,CAAC,kBAAkB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAEtE,OAAO;QACL,KAAK,EAAE,UAAU,CAAC,KAAK,IAAI,QAAQ,CAAC,KAAK,IAAI,wBAAwB,CAAC,OAAO,CAAC,KAAK;QACnF,WAAW,EACT,UAAU,CAAC,WAAW;YACtB,QAAQ,CAAC,WAAW;YACpB,wBAAwB,CAAC,OAAO,CAAC,WAAW;QAC9C,OAAO,EAAE,UAAU,CAAC,OAAO,IAAI,QAAQ,CAAC,OAAO,IAAI,wBAAwB,CAAC,OAAO,CAAC,OAAO;QAC3F,IAAI,EAAE,UAAU,CAAC,IAAI,IAAI,QAAQ,CAAC,IAAI,IAAI,wBAAwB,CAAC,OAAO,CAAC,IAAI;QAC/E,SAAS,EACP,UAAU,CAAC,SAAS,IAAI,QAAQ,CAAC,SAAS,IAAI,wBAAwB,CAAC,MAAM,CAAC,SAAS;KAC1F,CAAC;AACJ,CAAC"}

package/dist/spawn-agent-guidance.d.ts

@@ -0,0 +1,90 @@
+import type { WUDocBase } from './wu-doc-types.js';
+export type WUDoc = WUDocBase;
+/** Generate effort scaling rules section (WU-1986) */
+export declare function generateEffortScalingRules(): string;
+/** Generate parallel tool call guidance (WU-1986) */
+export declare function generateParallelToolCallGuidance(): string;
+/** Generate iterative search heuristics (WU-1986) */
+export declare function generateIterativeSearchHeuristics(): string;
+/**
+ * Generate token budget awareness section (WU-1986)
+ *
+ * @param {string} id - WU ID
+ * @returns {string} Token budget section
+ */
+export declare function generateTokenBudgetAwareness(id: string): string;
+/**
+ * Generate structured completion format (WU-1986)
+ *
+ * @param {string} id - WU ID
+ * @returns {string} Completion format section
+ */
+export declare function generateCompletionFormat(_id: string): string;
+/**
+ * Generate agent coordination section (WU-1987, WU-1203)
+ *
+ * Provides guidance on mem:signal for parallel agent coordination,
+ * orchestrate:monitor for agent status checks, and abandoned WU handling.
+ *
+ * WU-1203: Reads progress_signals config to generate dynamic guidance.
+ * When enabled:true, shows "Progress Signals (Required at Milestones)" with
+ * configurable triggers. When enabled:false or not configured, shows
+ * "Progress Signals (Optional)".
+ *
+ * @param {string} id - WU ID
+ * @returns {string} Agent coordination section
+ */
+export declare function generateAgentCoordinationSection(id: string): string;
+/** Generate quick fix commands section (WU-1987) */
+export declare function generateQuickFixCommands(): string;
+/** Generate Lane Selection section (WU-2107) */
+export declare function generateLaneSelectionSection(): string;
+/**
+ * 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 declare function generateWorktreePathGuidance(worktreePath: string | undefined): string;
+/**
+ * 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 declare function generateBugDiscoverySection(id: string): string;
+/**
+ * Generate lane-specific guidance
+ *
+ * @param {string} lane - Lane name
+ * @returns {string} Lane-specific guidance or empty string
+ */
+export declare function generateLaneGuidance(lane: string | undefined): string;
+/**
+ * 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 declare function generateActionSection(doc: WUDoc, id: string): string;
+//# sourceMappingURL=spawn-agent-guidance.d.ts.map

package/dist/spawn-agent-guidance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-agent-guidance.d.ts","sourceRoot":"","sources":["../src/spawn-agent-guidance.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,MAAM,MAAM,KAAK,GAAG,SAAS,CAAC;AAE9B,sDAAsD;AACtD,wBAAgB,0BAA0B,WAazC;AAED,qDAAqD;AACrD,wBAAgB,gCAAgC,WAe/C;AAED,qDAAqD;AACrD,wBAAgB,iCAAiC,WAWhD;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAU/D;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA0B5D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gCAAgC,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAgGnE;AAED,oDAAoD;AACpD,wBAAgB,wBAAwB,WAYvC;AAED,gDAAgD;AAChD,wBAAgB,4BAA4B,WAgB3C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,4BAA4B,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAyCrF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,2BAA2B,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAuC9D;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAwBrE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CA4BpE"}

package/dist/spawn-agent-guidance.js

@@ -0,0 +1,431 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * @file spawn-agent-guidance.ts
+ * WU-2012: Extracted from wu-spawn.ts
+ *
+ * Agent-facing operational guidance sections for spawn prompts:
+ * - Effort scaling rules
+ * - Parallel tool call guidance
+ * - Iterative search heuristics
+ * - Token budget awareness
+ * - Completion report format
+ * - Agent coordination (parallel work)
+ * - Quick fix commands
+ * - Lane selection guidance
+ * - Worktree path guidance
+ * - Bug discovery (mid-WU capture)
+ * - Lane-specific guidance
+ * - Action section (claim/continue)
+ *
+ * Single responsibility: Generate agent-operational guidance sections
+ * that help sub-agents work effectively during WU execution.
+ *
+ * @module spawn-agent-guidance
+ */
+import { getConfig } from './lumenflow-config.js';
+import { LUMENFLOW_PATHS } from './wu-constants.js';
+/** Generate effort scaling rules section (WU-1986) */
+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) */
+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) */
+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 agent coordination section (WU-1987, WU-1203)
+ *
+ * Provides guidance on mem:signal for parallel agent coordination,
+ * orchestrate:monitor for agent status checks, and abandoned WU handling.
+ *
+ * WU-1203: Reads progress_signals config to generate dynamic guidance.
+ * When enabled:true, shows "Progress Signals (Required at Milestones)" with
+ * configurable triggers. When enabled:false or not configured, shows
+ * "Progress Signals (Optional)".
+ *
+ * @param {string} id - WU ID
+ * @returns {string} Agent coordination section
+ */
+export function generateAgentCoordinationSection(id) {
+    const config = getConfig();
+    const progressSignals = config.memory?.progress_signals;
+    // WU-1210: Default to enabled (Required at Milestones) when not explicitly configured
+    // This ensures agents signal progress at key milestones by default
+    const isEnabled = progressSignals?.enabled ?? true;
+    // Generate milestone triggers section based on config
+    const generateMilestoneTriggers = () => {
+        if (!isEnabled) {
+            // Disabled - show optional guidance only
+            return `For long-running work, send progress signals at milestones:
+
+\`\`\`bash
+pnpm mem:signal "50% complete: tests passing, implementing adapter" --wu ${id}
+pnpm mem:signal "Blocked: waiting for WU-XXX dependency" --wu ${id}
+\`\`\``;
+        }
+        // WU-1210: isEnabled is true (either by default or explicit config)
+        // Build list of enabled triggers, using defaults when progressSignals is undefined
+        const triggers = [];
+        // Default all triggers to enabled when not explicitly configured
+        if ((progressSignals?.on_milestone ?? true) !== false) {
+            triggers.push('**After each acceptance criterion completed** - helps track progress');
+        }
+        if ((progressSignals?.on_tests_pass ?? true) !== false) {
+            triggers.push('**When tests first pass** - indicates implementation is working');
+        }
+        if ((progressSignals?.before_gates ?? true) !== false) {
+            triggers.push('**Before running gates** - signals imminent completion');
+        }
+        if ((progressSignals?.on_blocked ?? true) !== false) {
+            triggers.push('**When blocked** - allows orchestrator to re-allocate or assist');
+        }
+        // Add frequency-based trigger if configured
+        const frequency = progressSignals?.frequency ?? 0;
+        let frequencyGuidance = '';
+        if (frequency > 0) {
+            frequencyGuidance = `\n5. **Every ${frequency} tool calls** - periodic progress update`;
+        }
+        const triggerList = triggers.length > 0
+            ? triggers.map((t, i) => `${i + 1}. ${t}`).join('\n') + frequencyGuidance
+            : 'Signal at key milestones to enable orchestrator visibility.';
+        return `**Signal at these milestones** to enable orchestrator visibility:
+
+${triggerList}
+
+\`\`\`bash
+pnpm mem:signal "AC1 complete: tests passing for feature X" --wu ${id}
+pnpm mem:signal "All tests passing, running gates" --wu ${id}
+pnpm mem:signal "Blocked: waiting for WU-XXX dependency" --wu ${id}
+\`\`\``;
+    };
+    const progressSectionTitle = isEnabled
+        ? '### Progress Signals (Required at Milestones)'
+        : '### Progress Signals (Optional)';
+    return `## Agent Coordination (Parallel Work)
+
+### \u26a0\ufe0f CRITICAL: Use mem:signal, NOT TaskOutput
+
+**DO NOT** use TaskOutput to check agent progress - it returns full transcripts
+and causes "prompt too long" errors. Always use the memory layer instead:
+
+\`\`\`bash
+# \u2705 CORRECT: Compact signals (~6 lines)
+pnpm mem:inbox --since 30m
+
+# \u274c WRONG: Full transcripts (context explosion)
+# TaskOutput with block=false  <-- NEVER DO THIS FOR MONITORING
+\`\`\`
+
+### Automatic Completion Signals
+
+\`wu:done\` automatically broadcasts completion signals. You do not need to
+manually signal completion - just run \`wu:done\` and orchestrators will
+see your signal via \`mem:inbox\`.
+
+${progressSectionTitle}
+
+${generateMilestoneTriggers()}
+
+### Checking Status
+
+\`\`\`bash
+pnpm orchestrate:init-status -i INIT-XXX  # Initiative progress (compact)
+pnpm mem:inbox --since 1h                  # Recent signals from all agents
+pnpm mem:inbox --lane "Experience: Web"    # Lane-specific signals
+\`\`\``;
+}
+/** Generate quick fix commands section (WU-1987) */
+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 Lane Selection section (WU-2107) */
+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** \u2014 do not fix bugs outside your scope
+3. **Reference in notes** \u2014 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/ \u00a7Bug 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_PATHS.WU_EVENTS}
+- Lane lock acquisition (WIP=1 enforcement)
+- Session tracking for context recovery`;
+}
+//# sourceMappingURL=spawn-agent-guidance.js.map

package/dist/spawn-agent-guidance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-agent-guidance.js","sourceRoot":"","sources":["../src/spawn-agent-guidance.ts"],"names":[],"mappings":"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"}

package/dist/spawn-constraints-generator.d.ts

@@ -0,0 +1,30 @@
+/**
+ * WU-1900: Options for constraints generation
+ */
+export interface ConstraintsOptions {
+    /** Whether to include TDD CHECKPOINT (constraint 1). Default: true */
+    includeTddCheckpoint?: boolean;
+}
+/**
+ * Generate the constraints block (appended at end per Lost in the Middle research)
+ *
+ * WU-2247: Aligned with LumenFlow \u00a77.2 (stop-and-ask) and \u00a77.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 declare function generateConstraints(id: string, options?: ConstraintsOptions): string;
+/**
+ * Generate Codex-specific constraints (simplified version)
+ *
+ * @param {string} id - WU ID
+ * @returns {string} Codex constraints section
+ */
+export declare function generateCodexConstraints(id: string): string;
+//# sourceMappingURL=spawn-constraints-generator.d.ts.map

package/dist/spawn-constraints-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-constraints-generator.d.ts","sourceRoot":"","sources":["../src/spawn-constraints-generator.ts"],"names":[],"mappings":"AAkBA;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,MAAM,CA4EpF;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAU3D"}