@lumenflow/core 2.2.2 → 2.3.2

package/dist/wu-spawn.d.ts

@@ -25,9 +25,159 @@
  * 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 type { ClientConfig, LumenFlowConfig } from './lumenflow-config-schema.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 { type TemplateContext } from './template-loader.js';
+import type { ResolvedPolicy } from './resolve-policy.js';
+/**
+ * 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 declare const TRUNCATION_WARNING_BANNER = "<!-- LUMENFLOW_TRUNCATION_WARNING -->\n<!--\n  \u26A0\uFE0F CRITICAL: DO NOT TRUNCATE THIS OUTPUT\n\n  This spawn prompt MUST be copied verbatim. Truncation causes:\n  - Missing constraints (agents ignore safety rules)\n  - Missing TDD directives (agents skip tests)\n  - Degraded agent performance\n\n  VERIFICATION: The output MUST end with: <!-- LUMENFLOW_SPAWN_END -->\n  If you don't see that sentinel at the end, the output was truncated.\n-->\n";
+export declare 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 declare function tryAssembleSpawnTemplates(baseDir: string, clientName: string, context: TemplateContext): string | null;
+/**
+ * Build template context from WU document.
+ *
+ * @param doc - WU YAML document
+ * @param id - WU ID
+ * @returns Context for template assembly
+ */
+export declare function buildTemplateContext(doc: Record<string, unknown>, id: string): TemplateContext;
+/**
+ * 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 declare function buildTemplateContextWithPolicy(doc: Record<string, unknown>, id: string, policy: ResolvedPolicy): TemplateContext & {
+    'policy.testing': string;
+    'policy.architecture': string;
+};
+/**
+ * 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 declare function generateTestGuidance(wuType: string): string;
+/**
+ * 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 declare function generateMandatoryStandards(policy: ResolvedPolicy): string;
+/**
+ * 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 declare function generatePolicyBasedTestGuidance(wuType: string, policy: ResolvedPolicy): string;
+/**
+ * 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 declare function generatePolicyBasedArchitectureGuidance(policy: ResolvedPolicy): string;
+/**
+ * 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 declare function generateEnforcementSummary(policy: ResolvedPolicy): string;
+/**
+ * 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 declare function generateWorktreeBlockRecoverySection(worktreePath: string): string;
 /**
  * Generate effort scaling rules section (WU-1986)
  *
@@ -68,15 +218,20 @@ export declare function generateTokenBudgetAwareness(id: any): string;
  */
 export declare function generateCompletionFormat(_id: any): string;
 /**
- * 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 declare function generateAgentCoordinationSection(id: any): string;
+export declare function generateAgentCoordinationSection(id: string): string;
 /**
  * Generate quick fix commands section (WU-1987)
  *
@@ -85,6 +240,16 @@ export declare function generateAgentCoordinationSection(id: any): string;
  * @returns {string} Quick fix commands section
  */
 export declare function generateQuickFixCommands(): string;
+/**
+ * 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;
 /**
  * Generate Lane Selection section (WU-2107)
  *
@@ -130,6 +295,14 @@ interface SpawnOptions {
     budget?: string;
     client?: ClientContext;
     config?: LumenFlowConfig;
+    /** WU-1240: Base directory for memory context loading */
+    baseDir?: string;
+    /** WU-1240: Include memory context section (default: false for backward compat) */
+    includeMemoryContext?: boolean;
+    /** WU-1240: Skip memory context even if includeMemoryContext is true */
+    noContext?: boolean;
+    /** WU-1240: Memory context content (pre-generated, for async integration) */
+    memoryContextContent?: string;
 }
 /**
  * Generate the complete Task tool invocation