@lumenflow/core 2.2.2 → 2.3.1

package/dist/wu-spawn.js

@@ -25,7 +25,7 @@
  * Codex Mode:
  *   When --codex is used, outputs a Codex/GPT-friendly Markdown prompt (no antml/XML escaping).
  *
- * @see {@link docs/04-operations/_frameworks/lumenflow/agent/onboarding/agent-invocation-guide.md} - Context loading templates
+ * @see {@link https://lumenflow.dev/reference/agent-invocation-guide/} - Context loading templates
  */
 import { existsSync, readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
@@ -46,15 +46,545 @@ import { loadInvariants, INVARIANT_TYPES } from './invariants-runner.js';
 import { validateSpawnArgs, generateExecutionModeSection, generateThinkToolGuidance, recordSpawnToRegistry, formatSpawnRecordedMessage, } from './wu-spawn-helpers.js';
 // Agent skills loading removed for vendor-agnostic design
 import { validateSpawnDependencies, formatDependencyError } from './dependency-validator.js';
+/**
+ * WU-1253/WU-1291: Template System for Spawn Prompts
+ *
+ * DECISION (WU-1291): Template system is ACTIVATED with graceful degradation.
+ *
+ * The template system loads prompt sections from .lumenflow/templates/spawn-prompt/
+ * with YAML frontmatter and manifest-driven assembly order. This design provides:
+ *
+ * 1. **Maintainability**: Templates in markdown files are easier to edit than code strings
+ * 2. **Client extensibility**: Client-specific overrides via templates.{client}/ directories
+ * 3. **Conditional inclusion**: Templates selected based on WU type and policy settings
+ * 4. **Graceful fallback**: If template loading fails, hardcoded functions are used
+ *
+ * Template loading is attempted via tryAssembleSpawnTemplates(). If it returns null
+ * (templates missing or assembly fails), the spawn output uses hardcoded generator
+ * functions (generateTDDDirective, generateBugDiscoverySection, etc.).
+ *
+ * @see template-loader.ts for the loading and assembly implementation
+ * @see .lumenflow/templates/manifest.yaml for the template registry
+ */
+import { loadManifest, loadTemplatesWithOverrides, assembleTemplates, } from './template-loader.js';
+import { resolvePolicy } from './resolve-policy.js';
+// WU-1270: Import telemetry emit function for methodology tracking
+import { emit as emitTelemetry } from './telemetry.js';
 /**
  * Mandatory agent trigger patterns.
- * Mirrors MANDATORY_TRIGGERS from orchestration-advisory-loader.mjs.
+ * Mirrors MANDATORY_TRIGGERS from orchestration.constants.ts.
+ *
+ * Note: For LumenFlow framework development, this is empty since we don't have
+ * application-specific concerns like PHI, auth, or RLS. Projects using LumenFlow
+ * should configure their own triggers based on their domain requirements.
  */
 const MANDATORY_TRIGGERS = {
-    'security-auditor': ['supabase/migrations/**', '**/auth/**', '**/rls/**', '**/permissions/**'],
-    'beacon-guardian': ['**/prompts/**', '**/classification/**', '**/detector/**', '**/llm/**'],
+// No mandatory triggers for LumenFlow framework development.
 };
 const LOG_PREFIX = '[wu:spawn]';
+/**
+ * WU-1192: Truncation prevention constants (consolidated from CLI)
+ *
+ * These constants help detect when spawn output has been truncated during
+ * copy-paste operations or context loading. The warning banner alerts users
+ * to the truncation risk, and the end sentinel allows verification that
+ * the full output was received.
+ */
+export const TRUNCATION_WARNING_BANNER = `<!-- LUMENFLOW_TRUNCATION_WARNING -->
+<!--
+  ⚠️ CRITICAL: DO NOT TRUNCATE THIS OUTPUT
+
+  This spawn prompt MUST be copied verbatim. Truncation causes:
+  - Missing constraints (agents ignore safety rules)
+  - Missing TDD directives (agents skip tests)
+  - Degraded agent performance
+
+  VERIFICATION: The output MUST end with: <!-- LUMENFLOW_SPAWN_END -->
+  If you don't see that sentinel at the end, the output was truncated.
+-->
+`;
+export const SPAWN_END_SENTINEL = '<!-- LUMENFLOW_SPAWN_END -->';
+/**
+ * WU-1253/WU-1291: Try to assemble spawn prompt sections from templates.
+ *
+ * This function loads templates from .lumenflow/templates/ and assembles
+ * them according to the manifest order. Client-specific overrides are
+ * supported via templates.{client}/ directories.
+ *
+ * **Decision (WU-1291)**: Template system is ACTIVATED. This function is called
+ * by generateTaskInvocation() and generateCodexPrompt() to attempt template-based
+ * generation. If it returns null (templates missing, manifest invalid, or assembly
+ * fails), callers fall back to hardcoded generator functions.
+ *
+ * Template coverage (as of WU-1291):
+ * - Methodology directives (TDD, test-after, none)
+ * - Architecture directives (hexagonal, layered, none)
+ * - Type-specific directives (documentation, visual, refactor)
+ * - Agent guidance (effort-scaling, parallel-tool-calls, search-heuristics, token-budget)
+ * - Operational guidance (bug-discovery, quick-fix-commands, lane-selection)
+ * - Lane-specific guidance and constraints
+ *
+ * @param baseDir - Project root directory
+ * @param clientName - Client name for overrides (e.g., 'claude', 'cursor')
+ * @param context - Context for token replacement and condition evaluation
+ * @returns Assembled template content, or null if templates unavailable
+ */
+export function tryAssembleSpawnTemplates(baseDir, clientName, context) {
+    try {
+        const manifest = loadManifest(baseDir);
+        const templates = loadTemplatesWithOverrides(baseDir, clientName);
+        if (templates.size === 0) {
+            return null;
+        }
+        return assembleTemplates(templates, manifest, context);
+    }
+    catch {
+        // Template loading failed - return null for hardcoded fallback (intentional)
+        return null;
+    }
+}
+/**
+ * Build template context from WU document.
+ *
+ * @param doc - WU YAML document
+ * @param id - WU ID
+ * @returns Context for template assembly
+ */
+export function buildTemplateContext(doc, id) {
+    const lane = doc.lane || '';
+    const laneParent = lane.split(':')[0]?.trim() || '';
+    return {
+        WU_ID: id,
+        LANE: lane,
+        TYPE: (doc.type || 'feature').toLowerCase(),
+        TITLE: doc.title || '',
+        DESCRIPTION: doc.description || '',
+        WORKTREE_PATH: doc.worktree_path || '',
+        laneParent,
+        // Add lowercase aliases for condition evaluation
+        type: (doc.type || 'feature').toLowerCase(),
+        lane,
+        worktreePath: doc.worktree_path || '',
+    };
+}
+/**
+ * WU-1261: Build template context with resolved policy fields.
+ *
+ * Extends buildTemplateContext() with policy.testing and policy.architecture
+ * fields for template condition evaluation.
+ *
+ * @param doc - WU YAML document
+ * @param id - WU ID
+ * @param policy - Resolved policy from resolvePolicy()
+ * @returns Context for template assembly with policy fields
+ */
+export function buildTemplateContextWithPolicy(doc, id, policy) {
+    const baseContext = buildTemplateContext(doc, id);
+    return {
+        ...baseContext,
+        'policy.testing': policy.testing,
+        'policy.architecture': policy.architecture,
+    };
+}
+/**
+ * WU types that require TDD (failing test first)
+ * Note: Used as documentation reference. TDD is the default for any type not in other categories.
+ */
+const _TDD_REQUIRED_TYPES = ['feature', 'bug', 'tooling', 'enhancement'];
+/**
+ * WU types that require existing tests to pass (no new tests mandated)
+ */
+const EXISTING_TESTS_TYPES = ['refactor'];
+/**
+ * WU types that require smoke tests + manual QA
+ */
+const SMOKE_TEST_TYPES = ['visual', 'design', 'ui'];
+/**
+ * WU types that only need format checks (no TDD)
+ */
+const DOCS_ONLY_TYPES = ['documentation', 'docs', 'config'];
+/**
+ * Generate type-aware test guidance (WU-1142, WU-1192)
+ *
+ * Returns appropriate test guidance based on WU type:
+ * - feature/bug/tooling: Full TDD directive
+ * - documentation: Format check only
+ * - visual/design: Smoke test + manual QA
+ * - refactor: Existing tests must pass
+ *
+ * @param {string} wuType - WU type from YAML
+ * @returns {string} Test guidance section
+ */
+export function generateTestGuidance(wuType) {
+    const type = (wuType || 'feature').toLowerCase();
+    // Documentation WUs - no TDD, just format checks
+    if (DOCS_ONLY_TYPES.includes(type)) {
+        return `## Documentation Standards
+
+**Format check only** - No TDD required for documentation WUs.
+
+### Requirements
+
+1. Run \`pnpm gates --docs-only\` before completion
+2. Ensure markdown formatting is correct
+3. Verify links are valid
+4. Check spelling and grammar`;
+    }
+    // Visual/Design WUs - smoke tests + manual QA
+    if (SMOKE_TEST_TYPES.includes(type)) {
+        return `## Visual/Design Testing
+
+**Smoke test + manual QA** - Visual WUs require different verification.
+
+### Requirements
+
+1. Create smoke test for component rendering (if applicable)
+2. Verify visual appearance manually
+3. Test responsive behavior across breakpoints
+4. Check accessibility (keyboard navigation, screen reader)
+5. Document manual QA results in completion notes`;
+    }
+    // Refactor WUs - existing tests must pass
+    if (EXISTING_TESTS_TYPES.includes(type)) {
+        return `## Refactor Testing
+
+**Existing tests must pass** - Refactoring must not break current behavior.
+
+### Requirements
+
+1. Run all existing tests BEFORE refactoring
+2. Run all existing tests AFTER refactoring
+3. No new tests required unless behavior changes
+4. If tests fail after refactor, the refactor introduced a bug`;
+    }
+    // Default: TDD required (feature, bug, tooling, enhancement)
+    return generateTDDDirective();
+}
+/**
+ * Generate the TDD directive section (WU-1585, WU-1192)
+ *
+ * Positioned immediately after </task> preamble per "Lost in the Middle" research.
+ * Critical instructions at START and END of prompt improve adherence.
+ *
+ * @returns {string} TDD directive section
+ */
+function generateTDDDirective() {
+    return `## ⛔ TDD DIRECTIVE — 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`;
+}
+/**
+ * WU-1279: Generate the Mandatory Standards section based on resolved policy
+ *
+ * Instead of hardcoding TDD/90%/Hexagonal, this function generates the
+ * section dynamically based on the resolved methodology policy.
+ *
+ * @param policy - Resolved policy from resolvePolicy()
+ * @returns Mandatory Standards section content
+ */
+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: Generate test guidance based on resolved policy
+ *
+ * Selects the appropriate test guidance based on policy.testing value:
+ * - 'tdd': Full TDD directive (failing test first)
+ * - 'test-after': Implementation first, then tests
+ * - 'none': Testing is optional
+ *
+ * Type overrides still apply (documentation WUs always get docs guidance).
+ *
+ * @param wuType - WU type from YAML (e.g., 'feature', 'documentation')
+ * @param policy - Resolved policy from resolvePolicy()
+ * @returns Test guidance section
+ */
+export function generatePolicyBasedTestGuidance(wuType, policy) {
+    const type = (wuType || 'feature').toLowerCase();
+    // Type overrides take precedence (documentation never needs TDD)
+    if (DOCS_ONLY_TYPES.includes(type)) {
+        return `## Documentation Standards
+
+**Format check only** - No TDD required for documentation WUs.
+
+### Requirements
+
+1. Run \`pnpm gates --docs-only\` before completion
+2. Ensure markdown formatting is correct
+3. Verify links are valid
+4. Check spelling and grammar`;
+    }
+    // Visual/Design WUs - smoke tests + manual QA
+    if (SMOKE_TEST_TYPES.includes(type)) {
+        return `## Visual/Design Testing
+
+**Smoke test + manual QA** - Visual WUs require different verification.
+
+### Requirements
+
+1. Create smoke test for component rendering (if applicable)
+2. Verify visual appearance manually
+3. Test responsive behavior across breakpoints
+4. Check accessibility (keyboard navigation, screen reader)
+5. Document manual QA results in completion notes`;
+    }
+    // Refactor WUs - existing tests must pass
+    if (EXISTING_TESTS_TYPES.includes(type)) {
+        return `## Refactor Testing
+
+**Existing tests must pass** - Refactoring must not break current behavior.
+
+### Requirements
+
+1. Run all existing tests BEFORE refactoring
+2. Run all existing tests AFTER refactoring
+3. No new tests required unless behavior changes
+4. If tests fail after refactor, the refactor introduced a bug`;
+    }
+    // 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, WU-1279: Generate test-after directive
+ *
+ * @param coverageThreshold - Coverage threshold from resolved policy
+ * @returns Test-after guidance section
+ */
+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
+ *
+ * @returns Testing optional guidance section
+ */
+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
+ *
+ * Selects appropriate architecture guidance based on policy.architecture:
+ * - 'hexagonal': Ports and adapters, dependency inversion
+ * - 'layered': Traditional layer separation
+ * - 'none': No architecture constraints
+ *
+ * @param policy - Resolved policy from resolvePolicy()
+ * @returns Architecture guidance section, or empty string for 'none'
+ */
+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-1261: Generate enforcement summary from resolved policy
+ *
+ * Creates a "You will be judged by" section that summarizes the active
+ * enforcement rules based on the resolved policy.
+ *
+ * @param policy - Resolved policy from resolvePolicy()
+ * @returns Enforcement summary section
+ */
+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)
+ *
+ * Provides guidance when agents encounter worktree hook blocks.
+ *
+ * @param {string} worktreePath - Path to the worktree
+ * @returns {string} 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)
+
+### 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"
+\`\`\``;
+}
 /**
  * Detect mandatory agents based on code paths.
  *
@@ -209,14 +739,16 @@ function formatInvariantForOutput(inv) {
         lines.push(`**Path:** \`${inv.path}\``);
     }
     if (inv.paths) {
-        lines.push(`**Paths:** ${inv.paths.map((p) => `\`${p}\``).join(', ')}`);
+        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)) {
-        lines.push(`**Cannot Import:** ${inv.cannot_import.map((m) => `\`${m}\``).join(', ')}`);
+        const formattedImports = inv.cannot_import.map((m) => `\`${m}\``).join(', ');
+        lines.push(`**Cannot Import:** ${formattedImports}`);
     }
     // WU-2254: required-pattern specific fields
     if (inv.pattern &&
@@ -225,7 +757,8 @@ function formatInvariantForOutput(inv) {
         lines.push(`**Pattern:** \`${inv.pattern}\``);
     }
     if (inv.scope && Array.isArray(inv.scope)) {
-        lines.push(`**Scope:** ${inv.scope.map((s) => `\`${s}\``).join(', ')}`);
+        const formattedScope = inv.scope.map((s) => `\`${s}\``).join(', ');
+        lines.push(`**Scope:** ${formattedScope}`);
     }
     lines.push('');
     return lines;
@@ -274,34 +807,6 @@ function generateInvariantsPriorArtSection(codePaths) {
     ];
     return lines.join('\n');
 }
-/**
- * Generate the TDD directive section (WU-1585)
- *
- * Positioned immediately after </task> preamble per "Lost in the Middle" research.
- * Critical instructions at START and END of prompt improve adherence.
- *
- * @returns {string} TDD directive section
- */
-function generateTDDDirective() {
-    return `## ⛔ TDD DIRECTIVE — 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
-
-### 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`;
-}
 /**
  * Generate the context loading preamble
  *
@@ -358,7 +863,7 @@ CRITICAL RULES - ENFORCE BEFORE EVERY ACTION:
    - For ordinary errors: fix and retry autonomously (up to 3 attempts)
 
 4. VERIFY COMPLETION before reporting success
-   - Run: node tools/lib/agent-verification.mjs ${id} (from shared checkout)
+   - 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
 
@@ -372,32 +877,49 @@ CRITICAL RULES - ENFORCE BEFORE EVERY ACTION:
    - 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
+   - Use \`pnpm wu:prep\` from worktree, then \`pnpm wu:done\` from main (WU-1223)
 
 7. 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
-</constraints>`;
+
+8. SKIP-GATES AUTONOMY (WU-1142)
+   - If gates fail, first check if failure is pre-existing on main: \`git checkout main && pnpm gates\`
+   - If failure exists on main (not your change), use: \`pnpm wu:done --id ${id} --skip-gates --reason "pre-existing on main" --fix-wu WU-XXXX\`
+   - Do NOT ask for approval - autonomous skip-gates for pre-existing failures is correct
+   - This prevents getting stuck on infrastructure debt
+
+9. WORKTREE DISCIPLINE (WU-1282)
+   - CRITICAL: PreToolUse hooks do not propagate to sub-agents spawned via Task tool
+   - BEFORE any 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}`;
 }
 function generateCodexConstraints(id) {
     return `## Constraints (Critical)
 
 1. **TDD checkpoint**: tests BEFORE implementation; never skip RED
 2. **Stop on errors**: if any command fails, report BLOCKED (never DONE) with the error
-3. **Verify before success**: run \`pnpm gates\` in the worktree, then run \`node tools/lib/agent-verification.mjs ${id}\` (from the shared checkout)
+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\``;
+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 any Write/Edit, verify \`pwd\` shows \`worktrees/\`; hooks do not propagate to sub-agents`;
 }
 /**
  * Generate mandatory agent advisory section
  *
  * @param {string[]} mandatoryAgents - Array of mandatory agent names
- * @param {string} id - WU ID
+ * @param {string} _id - WU ID (reserved for future use)
  * @returns {string} Mandatory agent section or empty string
  */
-function generateMandatoryAgentSection(mandatoryAgents, id) {
+function generateMandatoryAgentSection(mandatoryAgents, _id) {
     if (mandatoryAgents.length === 0) {
         return '';
     }
@@ -409,7 +931,7 @@ Based on code_paths, the following agents MUST be invoked:
 
 ${agentList}
 
-Run: pnpm orchestrate:suggest --wu ${id}
+Run: pnpm orchestrate:monitor to check agent status
 `;
 }
 /**
@@ -527,15 +1049,74 @@ When finishing, provide structured output:
 This format enables orchestrator to track progress across waves.`;
 }
 /**
- * Generate agent coordination section (WU-1987)
+ * Generate agent coordination section (WU-1987, WU-1203)
  *
  * Provides guidance on mem:signal for parallel agent coordination,
- * orchestrate:status for dashboard checks, and abandoned WU handling.
+ * 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)
 
 ### ⚠️ CRITICAL: Use mem:signal, NOT TaskOutput
@@ -557,14 +1138,9 @@ pnpm mem:inbox --since 30m
 manually signal completion - just run \`wu:done\` and orchestrators will
 see your signal via \`mem:inbox\`.
 
-### Progress Signals (Optional)
+${progressSectionTitle}
 
-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}
-\`\`\`
+${generateMilestoneTriggers()}
 
 ### Checking Status
 
@@ -594,6 +1170,31 @@ pnpm typecheck   # Check TypeScript types
 
 **Use before gates** to catch simple issues early. These are faster than full \`pnpm gates\`.`;
 }
+/**
+ * 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
+    const METHODOLOGY_LOG = '.lumenflow/telemetry/methodology.ndjson';
+    emitTelemetry(METHODOLOGY_LOG, event);
+}
 /**
  * Generate Lane Selection section (WU-2107)
  *
@@ -724,7 +1325,7 @@ pnpm mem:triage --wu ${id}           # List discoveries for this WU
 pnpm mem:triage --promote <node-id> --lane "<lane>"  # Create Bug WU (human action)
 \`\`\`
 
-See: docs/04-operations/_frameworks/lumenflow/agent/onboarding/agent-invocation-guide.md §Bug Discovery`;
+See: https://lumenflow.dev/reference/agent-invocation-guide/ §Bug Discovery`;
 }
 /**
  * Generate lane-specific guidance
@@ -817,9 +1418,15 @@ export function generateTaskInvocation(doc, id, strategy, options = {}) {
     const codePaths = doc.code_paths || [];
     const mandatoryAgents = detectMandatoryAgents(codePaths);
     const preamble = generatePreamble(id, strategy);
-    const tddDirective = generateTDDDirective();
     const clientContext = options.client;
     const config = options.config || getConfig();
+    // WU-1279: Resolve policy and use policy-based test guidance
+    const policy = resolvePolicy(config);
+    const testGuidance = generatePolicyBasedTestGuidance(doc.type || 'feature', policy);
+    // WU-1279: Generate enforcement summary from resolved policy
+    const enforcementSummary = generateEnforcementSummary(policy);
+    // WU-1279: Generate mandatory standards based on resolved policy
+    const mandatoryStandards = generateMandatoryStandards(policy);
     const clientSkillsGuidance = generateClientSkillsGuidance(clientContext);
     const skillsSection = generateSkillsSelectionSection(doc, config, clientContext?.name) +
         (clientSkillsGuidance ? `\n${clientSkillsGuidance}` : '');
@@ -844,6 +1451,10 @@ export function generateTaskInvocation(doc, id, strategy, options = {}) {
     const laneSelection = generateLaneSelectionSection();
     // WU-2362: Worktree path guidance for sub-agents
     const worktreeGuidance = generateWorktreePathGuidance(doc.worktree_path);
+    // WU-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);
@@ -853,14 +1464,14 @@ export function generateTaskInvocation(doc, id, strategy, options = {}) {
         .join('\n\n---\n\n');
     const thinkingBlock = thinkingSections ? `${thinkingSections}\n\n---\n\n` : '';
     // Build the task prompt
-    // TDD directive appears immediately after </task> per "Lost in the Middle" research (WU-1585)
-    const taskPrompt = `<task>
+    // WU-1192: Truncation warning at start, test guidance after </task> per "Lost in the Middle" research
+    const taskPrompt = `${TRUNCATION_WARNING_BANNER}<task>
 ${preamble}
 </task>
 
 ---
 
-${tddDirective}
+${testGuidance}
 
 ---
 
@@ -888,19 +1499,13 @@ ${codePaths.length > 0 ? codePaths.map((p) => `- ${p}`).join('\n') : '- No code
 ${mandatorySection}${invariantsPriorArt ? `---\n\n${invariantsPriorArt}\n\n` : ''}${implementationContext ? `---\n\n${implementationContext}\n\n` : ''}---
 
 ${thinkingBlock}${skillsSection}
----
+${memoryContextSection ? `---\n\n${memoryContextSection}\n\n` : ''}---
 
-## Mandatory Standards
+${mandatoryStandards}
 
-- **LumenFlow**: Follow trunk-based flow, WIP=1, worktree discipline
-- **TDD**: Failing test first, then implementation, then passing test. 90%+ coverage on new application code
-- **Hexagonal Architecture**: Ports-first design. No application -> infrastructure imports
-- **SOLID/DRY/YAGNI/KISS**: No over-engineering, no premature abstraction
-- **Library-First**: Search context7 before writing custom code. No reinventing wheels
-- **Code Quality**: No string literals, no magic numbers, no brittle regexes when libraries exist
-- **Worktree Discipline**: ALWAYS use \`pnpm wu:claim\` to create worktrees (never \`git worktree add\` directly). Work ONLY in the worktree, never edit main
-- **Documentation**: Update tooling docs if changing tools. Keep docs in sync with code
-- **Sub-agents**: Use Explore agent for codebase investigation. Activate mandatory agents (security-auditor for PHI/auth, beacon-guardian for LLM/prompts)
+---
+
+${enforcementSummary}
 
 ${clientBlocks ? `---\n\n${clientBlocks}\n\n` : ''}${worktreeGuidance ? `---\n\n${worktreeGuidance}\n\n` : ''}---
 
@@ -971,7 +1576,6 @@ export function generateCodexPrompt(doc, id, strategy, options = {}) {
     const codePaths = doc.code_paths || [];
     const mandatoryAgents = detectMandatoryAgents(codePaths);
     const preamble = generatePreamble(id, strategy);
-    const tddDirective = generateTDDDirective();
     const mandatorySection = generateMandatoryAgentSection(mandatoryAgents, id);
     const laneGuidance = generateLaneGuidance(doc.lane);
     const bugDiscoverySection = generateBugDiscoverySection(id);
@@ -984,6 +1588,13 @@ export function generateCodexPrompt(doc, id, strategy, options = {}) {
     const skillsSection = generateSkillsSelectionSection(doc, config, clientContext?.name) +
         (clientSkillsGuidance ? `\n${clientSkillsGuidance}` : '');
     const clientBlocks = generateClientBlocksSection(clientContext);
+    // WU-1290: Resolve policy and use policy-based test guidance (same as generateTaskInvocation)
+    const policy = resolvePolicy(config);
+    const testGuidance = generatePolicyBasedTestGuidance(doc.type || 'feature', policy);
+    // WU-1290: Generate enforcement summary from resolved policy
+    const enforcementSummary = generateEnforcementSummary(policy);
+    // WU-1290: Generate mandatory standards based on resolved policy
+    const mandatoryStandards = generateMandatoryStandards(policy);
     const executionModeSection = generateExecutionModeSection(options);
     const thinkToolGuidance = generateThinkToolGuidance(options);
     const thinkingSections = [executionModeSection, thinkToolGuidance]
@@ -992,7 +1603,7 @@ export function generateCodexPrompt(doc, id, strategy, options = {}) {
     const thinkingBlock = thinkingSections ? `${thinkingSections}\n\n---\n\n` : '';
     return `# ${id}: ${doc.title || 'Untitled'}
 
-${tddDirective}
+${testGuidance}
 
 ---
 
@@ -1026,6 +1637,14 @@ ${formatAcceptance(doc.acceptance)}
 
 ---
 
+${mandatoryStandards}
+
+---
+
+${enforcementSummary}
+
+---
+
 ${skillsSection}
 
 ---
@@ -1039,7 +1658,7 @@ ${action}
 ## Verification
 
 - Run in worktree: \`pnpm gates\`
-- From shared checkout: \`node tools/lib/agent-verification.mjs ${id}\`
+- From shared checkout: \`node packages/@lumenflow/agent/dist/agent-verification.js ${id}\`
 
 ---
 
@@ -1222,6 +1841,9 @@ async function main() {
         console.log(`${LOG_PREFIX} Generated Task tool invocation for ${id}`);
         console.log(`${LOG_PREFIX} Copy the block below to spawn a sub-agent:\n`);
         console.log(invocation);
+        // WU-1270: Emit methodology telemetry (opt-in only)
+        const policy = resolvePolicy(config);
+        emitMethodologyTelemetry(config, policy);
         // WU-1945: Record spawn event to registry (non-blocking)
         // Only record if --parent-wu is provided (orchestrator context)
         if (args.parentWu) {