@lumenflow/core 3.2.0 → 3.2.2

package/dist/spawn-constraints-generator.js

@@ -0,0 +1,121 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * @file spawn-constraints-generator.ts
+ * WU-2012: Extracted from wu-spawn.ts
+ *
+ * Generates the constraints block appended at the end of spawn prompts
+ * per "Lost in the Middle" research. Also generates Codex-specific constraints.
+ *
+ * Single responsibility: Generate critical constraints and rules
+ * that sub-agents must enforce during WU execution.
+ *
+ * @module spawn-constraints-generator
+ */
+import { SPAWN_END_SENTINEL } from './spawn-template-assembler.js';
+/**
+ * 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 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 \u2014 failing tests prove the test works
+
+`
+        : '';
+    // 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;
+    const worktreeNum = includeTdd ? 9 : 8;
+    return `---
+
+<constraints>
+CRITICAL RULES - ENFORCE BEFORE EVERY ACTION:
+${tddCheckpointBlock}${antiLoopNum}. ANTI-LOOP GUARD (LumenFlow \u00a77.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 \u00a77.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/verification ${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
+   - Use \`pnpm wu:prep\` from worktree, then \`pnpm wu:done\` from main (WU-1223)
+
+${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
+
+${worktreeNum}. WORKTREE DISCIPLINE (WU-1282)
+   - CRITICAL: PreToolUse hooks do not propagate to sub-agents spawned via Task tool
+   - BEFORE UnsafeAny Write/Edit operation, manually verify you are in a worktree:
+   - Run: \`pwd\` and confirm output contains \`worktrees/\`
+   - If not in worktree, STOP and navigate: \`cd worktrees/<lane>-wu-xxx\`
+   - Use RELATIVE paths only (never full absolute paths starting with root directory)
+   - This constraint exists because Claude Code does not inherit settings.json hooks in sub-agent sessions
+</constraints>
+
+${SPAWN_END_SENTINEL}`;
+}
+/**
+ * Generate Codex-specific constraints (simplified version)
+ *
+ * @param {string} id - WU ID
+ * @returns {string} Codex constraints section
+ */
+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/verification ${id}\` (from the shared checkout)
+4. **No fabrication**: if blockers remain or verification fails, report INCOMPLETE
+5. **Git workflow**: avoid merge commits; use \`wu:prep\` from worktree, then \`wu:done\` from main
+6. **Scope discipline**: stay within \`code_paths\`; capture out-of-scope issues via \`pnpm mem:create\`
+7. **Worktree discipline (WU-1282)**: BEFORE UnsafeAny Write/Edit, verify \`pwd\` shows \`worktrees/\`; hooks do not propagate to sub-agents`;
+}
+//# sourceMappingURL=spawn-constraints-generator.js.map

package/dist/spawn-constraints-generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-constraints-generator.js","sourceRoot":"","sources":["../src/spawn-constraints-generator.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC;AAEzC;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAUnE;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CAAC,EAAU,EAAE,OAA4B;IAC1E,MAAM,UAAU,GAAG,OAAO,EAAE,oBAAoB,KAAK,KAAK,CAAC;IAE3D,MAAM,kBAAkB,GAAG,UAAU;QACnC,CAAC,CAAC;;;;;;CAML;QACG,CAAC,CAAC,EAAE,CAAC;IAEP,wDAAwD;IACxD,MAAM,WAAW,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACvC,MAAM,UAAU,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACtC,MAAM,SAAS,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACrC,MAAM,WAAW,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACvC,MAAM,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAClC,MAAM,YAAY,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxC,MAAM,WAAW,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAEvC,OAAO;;;;EAIP,kBAAkB,GAAG,WAAW;;;;;EAKhC,UAAU;;;;;;EAMV,SAAS;wDAC6C,EAAE;;;;EAIxD,WAAW;;;;;EAKX,MAAM;;;;;;;EAON,MAAM;sCAC8B,EAAE;mCACL,EAAE;;;EAGnC,YAAY;;6EAE+D,EAAE;;;;EAI7E,WAAW;;;;;;;;;EASX,kBAAkB,EAAE,CAAC;AACvB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CAAC,EAAU;IACjD,OAAO;;;;2HAIkH,EAAE;;;;6IAIgB,CAAC;AAC9I,CAAC"}

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

@@ -0,0 +1,47 @@
+/**
+ * @file spawn-guidance-generators.ts
+ * WU-2012: Extracted from wu-spawn.ts
+ *
+ * Generates methodology-aware guidance sections for spawn prompts:
+ * - Test guidance (TDD, test-after, smoke-test, refactor, docs-only)
+ * - Architecture guidance (hexagonal, layered, none)
+ * - Design context for UI-classified work
+ * - Enforcement summary from resolved policy
+ * - Mandatory standards section
+ * - Worktree block recovery guidance
+ *
+ * Single responsibility: Generate type-aware and policy-aware guidance sections
+ * for test methodology, architecture patterns, and UI design context.
+ *
+ * @module spawn-guidance-generators
+ */
+import type { ResolvedPolicy } from './resolve-policy.js';
+/** Generate type-aware test guidance (WU-1142, WU-1192) */
+export declare function generateTestGuidance(wuType: string): string;
+/**
+ * WU-1900: Options for classifier-aware test guidance
+ */
+export interface TestGuidanceOptions {
+    /** Test methodology hint from work classifier (e.g., 'smoke-test' for UI work) */
+    testMethodologyHint?: string;
+}
+/** WU-1279: Generate the Mandatory Standards section based on resolved policy */
+export declare function generateMandatoryStandards(policy: ResolvedPolicy): string;
+/**
+ * WU-1261, WU-1900: Generate test guidance based on resolved policy and classifier hint.
+ * Type overrides take precedence (docs, visual, refactor). WU-1900: classifier-driven
+ * smoke-test for bug WUs with UI code_paths.
+ */
+export declare function generatePolicyBasedTestGuidance(wuType: string, policy: ResolvedPolicy, options?: TestGuidanceOptions): string;
+/** WU-1261: Generate architecture guidance based on resolved policy */
+export declare function generatePolicyBasedArchitectureGuidance(policy: ResolvedPolicy): string;
+/** WU-1900: Generate design context section for UI-classified work */
+export declare function generateDesignContextSection(classification: {
+    domain: string;
+    capabilities: string[];
+}): string;
+/** WU-1261: Generate enforcement summary from resolved policy */
+export declare function generateEnforcementSummary(policy: ResolvedPolicy): string;
+/** Generate worktree block recovery section (WU-1192) */
+export declare function generateWorktreeBlockRecoverySection(worktreePath: string): string;
+//# sourceMappingURL=spawn-guidance-generators.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-guidance-generators.d.ts","sourceRoot":"","sources":["../src/spawn-guidance-generators.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAQ1D,2DAA2D;AAC3D,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAoB3D;AAmFD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,kFAAkF;IAClF,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,iFAAiF;AACjF,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAkDzE;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,cAAc,EACtB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,MAAM,CAkCR;AAiDD,uEAAuE;AACvE,wBAAgB,uCAAuC,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CA8CtF;AAED,sEAAsE;AACtE,wBAAgB,4BAA4B,CAAC,cAAc,EAAE;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB,GAAG,MAAM,CAiCT;AAED,iEAAiE;AACjE,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAqBzE;AAED,yDAAyD;AACzD,wBAAgB,oCAAoC,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CA6BjF"}

package/dist/spawn-guidance-generators.js

@@ -0,0 +1,346 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/** WU types by test methodology */
+const _TDD_REQUIRED_TYPES = ['feature', 'bug', 'tooling', 'enhancement'];
+const EXISTING_TESTS_TYPES = ['refactor'];
+const SMOKE_TEST_TYPES = ['visual', 'design', 'ui'];
+const DOCS_ONLY_TYPES = ['documentation', 'docs', 'config'];
+/** Generate type-aware test guidance (WU-1142, WU-1192) */
+export function generateTestGuidance(wuType) {
+    const type = (wuType || 'feature').toLowerCase();
+    // Documentation WUs - no TDD, just format checks
+    if (DOCS_ONLY_TYPES.includes(type)) {
+        return generateDocsGuidance();
+    }
+    // Visual/Design WUs - smoke tests + manual QA
+    if (SMOKE_TEST_TYPES.includes(type)) {
+        return generateSmokeTestGuidance();
+    }
+    // Refactor WUs - existing tests must pass
+    if (EXISTING_TESTS_TYPES.includes(type)) {
+        return generateRefactorGuidance();
+    }
+    // Default: TDD required (feature, bug, tooling, enhancement)
+    return generateTDDDirective();
+}
+/** Generate the TDD directive section (WU-1585, WU-1192) */
+function generateTDDDirective() {
+    return `## \u26d4 TDD DIRECTIVE \u2014 READ BEFORE CODING
+
+**IF YOU WRITE IMPLEMENTATION CODE BEFORE A FAILING TEST, YOU HAVE FAILED THIS WU.**
+
+### Test-First Workflow (MANDATORY)
+
+1. Write a failing test for the acceptance criteria
+2. Run the test to confirm it fails (RED)
+3. Implement the minimum code to pass the test
+4. Run the test to confirm it passes (GREEN)
+5. Refactor if needed, keeping tests green
+
+### Test Ratchet Rule (WU-1253)
+
+Gates compare test results against \`.lumenflow/test-baseline.json\`:
+
+- **NEW failures** (not in baseline) **BLOCK** gates - you must fix them
+- **Pre-existing failures** (in baseline) show **WARNING** - do not block your WU
+- When tests are **fixed**, baseline auto-updates (ratchet forward)
+
+If gates fail due to test failures:
+1. Check if failure is in baseline: \`cat .lumenflow/test-baseline.json\`
+2. If pre-existing: continue, it will warn but not block
+3. If NEW: fix the test or add to baseline with reason and fix-wu
+
+### Why This Matters
+
+- Tests document expected behavior BEFORE implementation
+- Prevents scope creep and over-engineering
+- Ensures every feature has verification
+- Failing tests prove the test actually tests something
+- Ratchet pattern prevents being blocked by unrelated failures`;
+}
+/** Generate documentation-only guidance */
+function generateDocsGuidance() {
+    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`;
+}
+/**
+ * WU-1900: Generate smoke-test guidance (extracted from inline)
+ */
+function generateSmokeTestGuidance() {
+    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`;
+}
+/** Generate refactor testing guidance */
+function generateRefactorGuidance() {
+    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`;
+}
+/** WU-1279: Generate the Mandatory Standards section based on resolved policy */
+export function generateMandatoryStandards(policy) {
+    const lines = ['## Mandatory Standards', ''];
+    // LumenFlow workflow is always required
+    lines.push('- **LumenFlow**: Follow trunk-based flow, WIP=1, worktree discipline');
+    // Testing methodology based on policy
+    if (policy.testing === 'tdd') {
+        lines.push(`- **TDD**: Failing test first, then implementation, then passing test. ${policy.coverage_threshold}%+ coverage on new application code`);
+    }
+    else if (policy.testing === 'test-after') {
+        lines.push(`- **Test-After**: Write implementation first, then add tests. ${policy.coverage_threshold}%+ coverage on new application code`);
+    }
+    else if (policy.testing === 'none') {
+        lines.push('- **Testing**: Tests are optional for this project');
+    }
+    // Architecture based on policy
+    if (policy.architecture === 'hexagonal') {
+        lines.push('- **Hexagonal Architecture**: Ports-first design. No application -> infrastructure imports');
+    }
+    else if (policy.architecture === 'layered') {
+        lines.push('- **Layered Architecture**: Clear layer separation. Each layer can only depend on layers below it');
+    }
+    // For architecture: 'none', we don't add any architecture guidance
+    // Always include these standards
+    lines.push('- **SOLID/DRY/YAGNI/KISS**: No over-engineering, no premature abstraction');
+    lines.push('- **Library-First**: Search context7 before writing custom code. No reinventing wheels');
+    lines.push('- **Code Quality**: No string literals, no magic numbers, no brittle regexes when libraries exist');
+    lines.push('- **Worktree Discipline**: ALWAYS use `pnpm wu:claim` to create worktrees (never `git worktree add` directly). Work ONLY in the worktree, never edit main');
+    lines.push('- **Documentation**: Update tooling docs if changing tools. Keep docs in sync with code');
+    lines.push('- **Sub-agents**: Use Explore agent for codebase investigation. Activate mandatory agents as configured for your project');
+    return lines.join('\n');
+}
+/**
+ * WU-1261, WU-1900: Generate test guidance based on resolved policy and classifier hint.
+ * Type overrides take precedence (docs, visual, refactor). WU-1900: classifier-driven
+ * smoke-test for bug WUs with UI code_paths.
+ */
+export function generatePolicyBasedTestGuidance(wuType, policy, options) {
+    const type = (wuType || 'feature').toLowerCase();
+    // Type overrides take precedence (documentation never needs TDD)
+    if (DOCS_ONLY_TYPES.includes(type)) {
+        return generateDocsGuidance();
+    }
+    // Visual/Design WUs - smoke tests + manual QA
+    if (SMOKE_TEST_TYPES.includes(type)) {
+        return generateSmokeTestGuidance();
+    }
+    // WU-1900: Classifier-driven smoke-test for bug WUs with UI code_paths
+    // This makes SMOKE_TEST_TYPES reachable through classifier signals
+    if (type === 'bug' && options?.testMethodologyHint === 'smoke-test') {
+        return generateSmokeTestGuidance();
+    }
+    // Refactor WUs - existing tests must pass
+    if (EXISTING_TESTS_TYPES.includes(type)) {
+        return generateRefactorGuidance();
+    }
+    // Policy-based selection for feature/bug/enhancement/tooling types
+    switch (policy.testing) {
+        case 'test-after':
+            return generateTestAfterDirective(policy.coverage_threshold);
+        case 'none':
+            return generateTestingOptionalDirective();
+        case 'tdd':
+        default:
+            return generateTDDDirective();
+    }
+}
+/** WU-1261: Generate test-after directive */
+function generateTestAfterDirective(coverageThreshold) {
+    return `## Test-After Methodology
+
+**Write implementation first, then add tests** - Focus on solving the problem, then verify.
+
+### Test-After Workflow
+
+1. Understand the acceptance criteria
+2. Write implementation first
+3. Add tests to verify behavior
+4. Aim for ${coverageThreshold}% coverage on new code
+
+### When This Works
+
+- Exploratory prototyping where requirements are unclear
+- Quick iterations where test-first slows discovery
+- Projects configured with \`methodology.testing: 'test-after'\`
+
+### Requirements
+
+- Tests must be added before \`wu:done\`
+- Coverage target: ${coverageThreshold}%+ on new application code
+- All existing tests must still pass`;
+}
+/** WU-1261: Generate testing optional directive */
+function generateTestingOptionalDirective() {
+    return `## Testing Optional
+
+**Tests are not required** - Project is configured without test requirements.
+
+### Focus
+
+- Code quality and functionality
+- Run \`pnpm gates\` before completion (will skip coverage checks)
+
+### If You Want to Add Tests
+
+You can still add tests for critical functionality:
+\`\`\`bash
+pnpm test -- --coverage
+\`\`\`
+
+But they are not required for WU completion.`;
+}
+/** WU-1261: Generate architecture guidance based on resolved policy */
+export function generatePolicyBasedArchitectureGuidance(policy) {
+    switch (policy.architecture) {
+        case 'hexagonal':
+            return `## Hexagonal Architecture
+
+**Ports and Adapters** - Keep domain logic pure, infrastructure at the edges.
+
+### Key Principles
+
+- **Ports**: Interfaces defining what the domain needs (inbound) or uses (outbound)
+- **Adapters**: Implementations connecting ports to infrastructure
+- **Domain**: Pure business logic with no infrastructure imports
+- **Dependency Rule**: Domain -> Ports <- Adapters (never domain -> adapters)
+
+### Directory Structure
+
+\`\`\`
+src/
+  domain/           # Pure business logic
+  ports/            # Interfaces
+  adapters/         # Infrastructure implementations
+  application/      # Use cases orchestrating domain + ports
+\`\`\``;
+        case 'layered':
+            return `## Layered Architecture
+
+**Traditional layer separation** - Clear boundaries between concerns.
+
+### Layers (Top to Bottom)
+
+1. **Presentation**: UI, API controllers, CLI
+2. **Application**: Use cases, orchestration
+3. **Domain**: Business logic, entities
+4. **Infrastructure**: Database, external services
+
+### Dependency Rule
+
+- Each layer can only depend on layers below it
+- Presentation -> Application -> Domain -> Infrastructure
+- Never skip layers (Presentation should not directly use Infrastructure)`;
+        case 'none':
+        default:
+            return '';
+    }
+}
+/** WU-1900: Generate design context section for UI-classified work */
+export function generateDesignContextSection(classification) {
+    if (classification.domain !== 'ui') {
+        return '';
+    }
+    return `## Design Context
+
+This work involves UI components or styling. Follow these guidelines:
+
+### Pattern Check
+
+- Before creating new components, check for existing patterns in the codebase
+- Search for similar components that may already solve the problem
+- Verify design system tokens and variables are used instead of hardcoded values
+
+### Viewport Verification
+
+- Test across common viewport sizes (mobile: 375px, tablet: 768px, desktop: 1280px)
+- Verify responsive behavior at breakpoints
+- Check for overflow, text truncation, and layout shifts
+
+### Accessibility
+
+- Verify keyboard navigation works for interactive elements
+- Ensure sufficient color contrast (WCAG 2.1 AA minimum)
+- Add appropriate ARIA attributes where needed
+- Test with screen reader if applicable
+
+### Codebase Exploration
+
+- Check the project's design system or component library before building custom
+- Look for CSS variables, theme tokens, or shared style utilities
+- Review existing component patterns for consistency`;
+}
+/** WU-1261: Generate enforcement summary from resolved policy */
+export function generateEnforcementSummary(policy) {
+    const lines = ['## You will be judged by', ''];
+    // Testing methodology
+    const testingStatus = policy.tests_required ? 'required' : 'optional';
+    lines.push(`- **Testing**: ${policy.testing} (tests ${testingStatus})`);
+    // Coverage
+    if (policy.coverage_mode === 'off') {
+        lines.push('- **Coverage**: disabled');
+    }
+    else {
+        const modeLabel = policy.coverage_mode === 'block' ? 'blocking' : 'warn only';
+        lines.push(`- **Coverage**: ${policy.coverage_threshold}% (${modeLabel})`);
+    }
+    // Architecture
+    if (policy.architecture !== 'none') {
+        lines.push(`- **Architecture**: ${policy.architecture}`);
+    }
+    return lines.join('\n');
+}
+/** Generate worktree block recovery section (WU-1192) */
+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)
+
+### 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"
+\`\`\``;
+}
+//# sourceMappingURL=spawn-guidance-generators.js.map

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

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

package/dist/spawn-policy-resolver.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @file spawn-policy-resolver.ts
+ * WU-2012: Extracted from wu-spawn.ts
+ *
+ * Generates policy-based sections for spawn prompts: mandatory standards,
+ * enforcement summaries, and methodology telemetry.
+ *
+ * Single responsibility: Transform resolved methodology policies into
+ * prompt sections that communicate standards and enforcement to sub-agents.
+ *
+ * @module spawn-policy-resolver
+ */
+import type { ResolvedPolicy } from './resolve-policy.js';
+import type { LumenFlowConfig } from './lumenflow-config-schema.js';
+export { generateMandatoryStandards, generateEnforcementSummary, } from './spawn-guidance-generators.js';
+/**
+ * WU-1270: Emit methodology telemetry event (opt-in)
+ *
+ * Emits privacy-preserving telemetry about methodology selection.
+ * Only emits if telemetry.methodology.enabled is true in config.
+ *
+ * @param config - LumenFlow configuration
+ * @param policy - Resolved methodology policy
+ */
+export declare function emitMethodologyTelemetry(config: LumenFlowConfig, policy: ResolvedPolicy): void;
+//# sourceMappingURL=spawn-policy-resolver.d.ts.map

package/dist/spawn-policy-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-policy-resolver.d.ts","sourceRoot":"","sources":["../src/spawn-policy-resolver.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAG1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAGpE,OAAO,EACL,0BAA0B,EAC1B,0BAA0B,GAC3B,MAAM,gCAAgC,CAAC;AAExC;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI,CAgB9F"}

package/dist/spawn-policy-resolver.js

@@ -0,0 +1,31 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+import { emit as emitTelemetryEvent } from './telemetry.js';
+import { LUMENFLOW_PATHS } from './wu-constants.js';
+// Re-export from spawn-guidance-generators where the canonical implementations live
+export { generateMandatoryStandards, generateEnforcementSummary, } from './spawn-guidance-generators.js';
+/**
+ * WU-1270: Emit methodology telemetry event (opt-in)
+ *
+ * Emits privacy-preserving telemetry about methodology selection.
+ * Only emits if telemetry.methodology.enabled is true in config.
+ *
+ * @param config - LumenFlow configuration
+ * @param policy - Resolved methodology policy
+ */
+export function emitMethodologyTelemetry(config, policy) {
+    // Check if methodology telemetry is opt-in enabled
+    if (!config.telemetry?.methodology?.enabled) {
+        return;
+    }
+    const event = {
+        timestamp: new Date().toISOString(),
+        event_type: 'methodology.selection',
+        methodology_testing: policy.testing,
+        methodology_architecture: policy.architecture,
+        event_context: 'spawn',
+    };
+    // Use the telemetry emit function from telemetry.ts - WU-1430: Use centralized constant
+    emitTelemetryEvent(LUMENFLOW_PATHS.METHODOLOGY_LOG, event);
+}
+//# sourceMappingURL=spawn-policy-resolver.js.map

package/dist/spawn-policy-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-policy-resolver.js","sourceRoot":"","sources":["../src/spawn-policy-resolver.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC;AAgBzC,OAAO,EAAE,IAAI,IAAI,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGpD,oFAAoF;AACpF,OAAO,EACL,0BAA0B,EAC1B,0BAA0B,GAC3B,MAAM,gCAAgC,CAAC;AAExC;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB,CAAC,MAAuB,EAAE,MAAsB;IACtF,mDAAmD;IACnD,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;QAC5C,OAAO;IACT,CAAC;IAED,MAAM,KAAK,GAAG;QACZ,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,UAAU,EAAE,uBAAuB;QACnC,mBAAmB,EAAE,MAAM,CAAC,OAAO;QACnC,wBAAwB,EAAE,MAAM,CAAC,YAAY;QAC7C,aAAa,EAAE,OAAO;KACvB,CAAC;IAEF,wFAAwF;IACxF,kBAAkB,CAAC,eAAe,CAAC,eAAe,EAAE,KAAK,CAAC,CAAC;AAC7D,CAAC"}

package/dist/spawn-prompt-helpers.d.ts

@@ -0,0 +1,45 @@
+import type { ClientConfig } from './lumenflow-config-schema.js';
+import type { SpawnStrategy } from './spawn-strategy.js';
+import type { WUDoc } from './spawn-agent-guidance.js';
+/**
+ * Client context for spawn generation
+ */
+export interface ClientContext {
+    name: string;
+    config?: ClientConfig;
+}
+/**
+ * Format acceptance criteria as markdown list
+ */
+export declare function formatAcceptance(acceptance: string[] | undefined): string;
+/**
+ * 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.
+ */
+export declare function generateImplementationContext(doc: WUDoc): string;
+/**
+ * Detect mandatory agents based on code paths.
+ */
+export declare function detectMandatoryAgents(codePaths: string[] | undefined): string[];
+/**
+ * Generate the mandatory agents section
+ */
+export declare function generateMandatoryAgentSection(mandatoryAgents: string[], _id: string): string;
+/**
+ * Generate the context loading preamble using the strategy
+ */
+export declare function generatePreamble(id: string, strategy: SpawnStrategy): string;
+/**
+ * Generate client blocks section from config
+ */
+export declare function generateClientBlocksSection(clientContext: ClientContext | undefined): string;
+/**
+ * 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.
+ */
+export declare function generateInvariantsPriorArtSection(codePaths: string[]): string;
+//# sourceMappingURL=spawn-prompt-helpers.d.ts.map

package/dist/spawn-prompt-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-prompt-helpers.d.ts","sourceRoot":"","sources":["../src/spawn-prompt-helpers.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,2BAA2B,CAAC;AAqBvD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAkBD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM,CAKzE;AAoDD;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,KAAK,GAAG,MAAM,CA2BhE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM,EAAE,CAkB/E;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAAC,eAAe,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAe5F;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,MAAM,CAE5E;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,aAAa,EAAE,aAAa,GAAG,SAAS,GAAG,MAAM,CAM5F;AA2FD;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAqC7E"}