@lumenflow/core 1.0.0 → 1.3.2

package/dist/wu-spawn.js

@@ -11,7 +11,7 @@
  *
  * Output:
  *   A complete Task tool invocation block with:
- *   - Context loading preamble (CLAUDE-core.md, README, lumenflow, WU YAML)
+ *   - Context loading preamble (.claude/CLAUDE.md, README, lumenflow, WU YAML)
  *   - WU details and acceptance criteria
  *   - Skills Selection section (sub-agent reads catalogue and selects at runtime)
  *   - Mandatory agent advisory
@@ -25,9 +25,10 @@
  * Codex Mode:
  *   When --codex is used, outputs a Codex/GPT-friendly Markdown prompt (no antml/XML escaping).
  *
- * @see {@link ai/onboarding/agent-invocation-guide.md} - Context loading templates
+ * @see {@link docs/04-operations/_frameworks/lumenflow/agent/onboarding/agent-invocation-guide.md} - Context loading templates
  */
 import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import { createWUParser, WU_OPTIONS } from './arg-parser.js';
 import { WU_PATHS } from './wu-paths.js';
@@ -37,6 +38,9 @@ import { WU_STATUS, PATTERNS, EMOJI } from './wu-constants.js';
 // WU-1603: Check lane lock status before spawning
 import { checkLaneLock } from './lane-lock.js';
 import { minimatch } from 'minimatch';
+import { SpawnStrategyFactory } from './spawn-strategy.js';
+import { getConfig } from './lumenflow-config.js';
+import { generateClientSkillsGuidance, generateSkillsSelectionSection, resolveClientConfig, } from './wu-spawn-skills.js';
 // WU-2252: Import invariants loader for spawn output injection
 import { loadInvariants, INVARIANT_TYPES } from './invariants-runner.js';
 import { validateSpawnArgs, generateExecutionModeSection, generateThinkToolGuidance, recordSpawnToRegistry, formatSpawnRecordedMessage, } from './wu-spawn-helpers.js';
@@ -51,27 +55,6 @@ const MANDATORY_TRIGGERS = {
     'beacon-guardian': ['**/prompts/**', '**/classification/**', '**/detector/**', '**/llm/**'],
 };
 const LOG_PREFIX = '[wu:spawn]';
-/** @type {string} */
-const AGENTS_DIR = '.claude/agents';
-/**
- * Load skills configured in agent's frontmatter
- *
- * @param {string} agentName - Agent name (e.g., 'general-purpose')
- * @returns {string[]} Array of skill names or empty array if not found
- */
-function loadAgentConfiguredSkills(agentName) {
-    const agentPath = `${AGENTS_DIR}/${agentName}.md`;
-    if (!existsSync(agentPath)) {
-        return [];
-    }
-    try {
-        const content = readFileSync(agentPath, { encoding: 'utf-8' });
-        return []; // Removed: vendor-specific skill loading
-    }
-    catch {
-        return [];
-    }
-}
 /**
  * Detect mandatory agents based on code paths.
  *
@@ -106,6 +89,9 @@ function formatAcceptance(acceptance) {
 /**
  * Format spec_refs as markdown links
  *
+ * WU-1062: Handles external paths (lumenflow://, ~/.lumenflow/, $LUMENFLOW_HOME/)
+ * by expanding them to absolute paths and adding a note about reading them.
+ *
  * @param {string[]|undefined} specRefs - Spec references array
  * @returns {string} Formatted references or empty string if none
  */
@@ -113,7 +99,17 @@ function formatSpecRefs(specRefs) {
     if (!specRefs || specRefs.length === 0) {
         return '';
     }
-    return specRefs.map((ref) => `- ${ref}`).join('\n');
+    const formattedRefs = specRefs.map((ref) => {
+        // WU-1062: Add note for external paths
+        if (ref.startsWith('lumenflow://') ||
+            ref.startsWith('~/') ||
+            ref.startsWith('$LUMENFLOW_HOME') ||
+            (ref.startsWith('/') && ref.includes('.lumenflow'))) {
+            return `- ${ref} (external - read with filesystem access)`;
+        }
+        return `- ${ref}`;
+    });
+    return formattedRefs.join('\n');
 }
 /**
  * Format risks as markdown list
@@ -320,27 +316,15 @@ function generateTDDDirective() {
  * @param {string} id - WU ID
  * @returns {string} Context loading preamble
  */
-function generatePreamble(id) {
-    return `Load the following context in this order:
-
-1. Read CLAUDE.md (workflow fundamentals and critical rules)
-2. Read README.md (project structure and tech stack)
-3. Read docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md sections 1-7 (TDD, gates, Definition of Done)
-4. Read docs/04-operations/tasks/wu/${id}.yaml (the specific WU you're working on)
-
-## WIP=1 Lane Check (BEFORE claiming)
-
-Before running wu:claim, check docs/04-operations/tasks/status.md to ensure the lane is free.
-Only ONE WU can be in_progress per lane at any time.
-
-## Context Recovery (Session Resumption)
-
-Before starting work, check for prior context from previous sessions:
-
-1. \`pnpm mem:ready --wu ${id}\` — Query pending nodes (what's next?)
-2. \`pnpm mem:inbox --wu ${id}\` — Check coordination signals from parallel agents
-
-If prior context exists, resume from the last checkpoint. Otherwise, proceed with the task below.`;
+/**
+ * Generate the context loading preamble using the strategy
+ *
+ * @param {string} id - WU ID
+ * @param {import('./spawn-strategy.js').SpawnStrategy} strategy - Client strategy
+ * @returns {string} Context loading preamble
+ */
+function generatePreamble(id, strategy) {
+    return strategy.getPreamble(id);
 }
 /**
  * Generate the constraints block (appended at end per Lost in the Middle research)
@@ -740,7 +724,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: ai/onboarding/agent-invocation-guide.md §Bug Discovery`;
+See: docs/04-operations/_frameworks/lumenflow/agent/onboarding/agent-invocation-guide.md §Bug Discovery`;
 }
 /**
  * Generate lane-specific guidance
@@ -809,128 +793,37 @@ Then implement following all standards above.
 - Lane lock acquisition (WIP=1 enforcement)
 - Session tracking for context recovery`;
 }
-/**
- * Generate the Skills Selection section for sub-agents.
- *
- * Unlike /wu-prompt (human-facing, skills selected at generation time),
- * wu:spawn instructs the sub-agent to read the catalogue and select skills
- * at execution time based on WU context.
- *
- * If an agentName is provided, that agent's configured skills (from frontmatter)
- * are auto-loaded at the top.
- *
- * @param {object} doc - WU YAML document
- * @param {string} [agentName='general-purpose'] - Agent to spawn
- * @returns {string} Skills Selection section
- */
-// eslint-disable-next-line sonarjs/cognitive-complexity -- WU-2025: Pre-existing complexity, refactor tracked
-function generateSkillsSection(doc, agentName = 'general-purpose') {
-    const lane = doc.lane || '';
-    const type = doc.type || 'feature';
-    const laneParent = lane.split(':')[0].trim();
-    // Load agent's configured skills from frontmatter
-    const agentSkills = loadAgentConfiguredSkills(agentName);
-    const hasAgentSkills = agentSkills.length > 0;
-    // Build auto-load section if agent has configured skills
-    const autoLoadSection = hasAgentSkills
-        ? `### Auto-Loaded Skills (from ${agentName} agent config)
-
-These skills are pre-configured for this agent and should be loaded first:
-
-${agentSkills.map((s) => `- \`${s}\` — Load via \`/skill ${s}\``).join('\n')}
-
-`
-        : '';
-    // Build context hints for the sub-agent
-    const contextHints = [];
-    // Universal baselines (only if not already in agent skills)
-    if (!agentSkills.includes('wu-lifecycle')) {
-        contextHints.push('- `wu-lifecycle` — ALL WUs need workflow automation');
-    }
-    if (!agentSkills.includes('worktree-discipline')) {
-        contextHints.push('- `worktree-discipline` — ALL WUs need path safety');
-    }
-    // Type-based hints
-    if ((type === 'feature' || type === 'enhancement') && !agentSkills.includes('tdd-workflow')) {
-        contextHints.push('- `tdd-workflow` — TDD is mandatory for feature/enhancement WUs');
-    }
-    if (type === 'bug' && !agentSkills.includes('bug-classification')) {
-        contextHints.push('- `bug-classification` — Bug severity assessment');
-    }
-    // Lane-based hints
-    if (laneParent === 'Operations' &&
-        lane.includes('Tooling') &&
-        !agentSkills.includes('lumenflow-gates')) {
-        contextHints.push('- `lumenflow-gates` — Tooling often affects gates');
-    }
-    if (laneParent === 'Intelligence') {
-        if (!agentSkills.includes('beacon-compliance')) {
-            contextHints.push('- `beacon-compliance` — Intelligence lane requires Beacon validation');
-        }
-        if (!agentSkills.includes('prompt-management')) {
-            contextHints.push('- `prompt-management` — For prompt template work');
-        }
-    }
-    if (laneParent === 'Experience' && !agentSkills.includes('frontend-design')) {
-        contextHints.push('- `frontend-design` — For UI component work');
-    }
-    const softPolicySection = contextHints.length > 0
-        ? `### Soft Policy (baselines for this WU)
-
-Based on WU context, consider loading:
-
-${contextHints.join('\n')}
-
-`
-        : '';
-    return `## Skills Selection
-
-**IMPORTANT**: Before starting work, select and load relevant skills.
-
-${autoLoadSection}### How to Select Skills
-
-1. Read the skill catalogue frontmatter from \`.claude/skills/*/SKILL.md\`
-2. Match skills to WU context (lane, type, code_paths, description)
-3. Load selected skills via \`/skill <skill-name>\`
-
-${softPolicySection}### Additional Skills (load if needed)
-
-| Skill | Use When |
-|-------|----------|
-| lumenflow-gates | Gates fail, debugging format/lint/typecheck errors |
-| bug-classification | Bug discovered mid-WU, need priority classification |
-| beacon-compliance | Code touches LLM, prompts, classification |
-| prompt-management | Working with prompt templates, golden datasets |
-| frontend-design | Building UI components, pages |
-| initiative-management | Multi-phase projects, INIT-XXX coordination |
-| multi-agent-coordination | Spawning sub-agents, parallel WU work |
-| orchestration | Agent coordination, mandatory agent checks |
-| ops-maintenance | Metrics, validation, health checks |
-
-### Graceful Degradation
-
-If the skill catalogue is missing or invalid:
-- Load baseline skills: \`/skill wu-lifecycle\`, \`/skill tdd-workflow\` (for features)
-- Continue with implementation using Mandatory Standards below
-`;
+function generateClientBlocksSection(clientContext) {
+    if (!clientContext?.config?.blocks?.length)
+        return '';
+    const blocks = clientContext.config.blocks
+        .map((block) => `### ${block.title}\n\n${block.content}`)
+        .join('\n\n');
+    return `## Client Guidance (${clientContext.name})\n\n${blocks}`;
 }
 /**
  * Generate the complete Task tool invocation
  *
  * @param {object} doc - WU YAML document
  * @param {string} id - WU ID
+ * @param {SpawnStrategy} strategy - Client strategy
  * @param {object} [options={}] - Thinking mode options
  * @param {boolean} [options.thinking] - Whether extended thinking is enabled
  * @param {boolean} [options.noThinking] - Whether thinking is explicitly disabled
  * @param {string} [options.budget] - Token budget for thinking
  * @returns {string} Complete Task tool invocation
  */
-export function generateTaskInvocation(doc, id, options = {}) {
+export function generateTaskInvocation(doc, id, strategy, options = {}) {
     const codePaths = doc.code_paths || [];
     const mandatoryAgents = detectMandatoryAgents(codePaths);
-    const preamble = generatePreamble(id);
+    const preamble = generatePreamble(id, strategy);
     const tddDirective = generateTDDDirective();
-    const skillsSection = generateSkillsSection(doc);
+    const clientContext = options.client;
+    const config = options.config || getConfig();
+    const clientSkillsGuidance = generateClientSkillsGuidance(clientContext);
+    const skillsSection = generateSkillsSelectionSection(doc, config, clientContext?.name) +
+        (clientSkillsGuidance ? `\n${clientSkillsGuidance}` : '');
+    const clientBlocks = generateClientBlocksSection(clientContext);
     const mandatorySection = generateMandatoryAgentSection(mandatoryAgents, id);
     const laneGuidance = generateLaneGuidance(doc.lane);
     const bugDiscoverySection = generateBugDiscoverySection(id);
@@ -1009,7 +902,7 @@ ${thinkingBlock}${skillsSection}
 - **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)
 
-${worktreeGuidance ? `---\n\n${worktreeGuidance}\n\n` : ''}---
+${clientBlocks ? `---\n\n${clientBlocks}\n\n` : ''}${worktreeGuidance ? `---\n\n${worktreeGuidance}\n\n` : ''}---
 
 ${bugDiscoverySection}
 
@@ -1074,10 +967,10 @@ ${constraints}`;
     ].join('\n');
     return invocation;
 }
-export function generateCodexPrompt(doc, id, options = {}) {
+export function generateCodexPrompt(doc, id, strategy, options = {}) {
     const codePaths = doc.code_paths || [];
     const mandatoryAgents = detectMandatoryAgents(codePaths);
-    const preamble = generatePreamble(id);
+    const preamble = generatePreamble(id, strategy);
     const tddDirective = generateTDDDirective();
     const mandatorySection = generateMandatoryAgentSection(mandatoryAgents, id);
     const laneGuidance = generateLaneGuidance(doc.lane);
@@ -1085,6 +978,12 @@ export function generateCodexPrompt(doc, id, options = {}) {
     const implementationContext = generateImplementationContext(doc);
     const action = generateActionSection(doc, id);
     const constraints = generateCodexConstraints(id);
+    const clientContext = options.client;
+    const config = options.config || getConfig();
+    const clientSkillsGuidance = generateClientSkillsGuidance(clientContext);
+    const skillsSection = generateSkillsSelectionSection(doc, config, clientContext?.name) +
+        (clientSkillsGuidance ? `\n${clientSkillsGuidance}` : '');
+    const clientBlocks = generateClientBlocksSection(clientContext);
     const executionModeSection = generateExecutionModeSection(options);
     const thinkToolGuidance = generateThinkToolGuidance(options);
     const thinkingSections = [executionModeSection, thinkToolGuidance]
@@ -1127,6 +1026,10 @@ ${formatAcceptance(doc.acceptance)}
 
 ---
 
+${skillsSection}
+
+---
+
 ## Action
 
 ${action}
@@ -1140,7 +1043,7 @@ ${action}
 
 ---
 
-${mandatorySection}${implementationContext ? `${implementationContext}\n\n---\n\n` : ''}${thinkingBlock}${bugDiscoverySection}
+${mandatorySection}${implementationContext ? `${implementationContext}\n\n---\n\n` : ''}${clientBlocks ? `${clientBlocks}\n\n---\n\n` : ''}${thinkingBlock}${bugDiscoverySection}
 
 ---
 
@@ -1196,12 +1099,19 @@ async function main() {
         name: 'wu-spawn',
         description: 'Generate Task tool invocation for sub-agent WU execution',
         options: [
+            WU_OPTIONS.id,
+            WU_OPTIONS.thinking,
+            WU_OPTIONS.noThinking,
+            WU_OPTIONS.budget,
+            WU_OPTIONS.codex,
             WU_OPTIONS.id,
             WU_OPTIONS.thinking,
             WU_OPTIONS.noThinking,
             WU_OPTIONS.budget,
             WU_OPTIONS.codex,
             WU_OPTIONS.parentWu, // WU-1945: Parent WU for spawn registry tracking
+            WU_OPTIONS.client,
+            WU_OPTIONS.vendor,
         ],
         required: ['id'],
         allowPositionalId: true,
@@ -1274,33 +1184,59 @@ async function main() {
         noThinking: args.noThinking,
         budget: args.budget,
     };
+    // Client Resolution
+    const config = getConfig();
+    let clientName = args.client;
+    if (!clientName && args.vendor) {
+        console.warn(`${LOG_PREFIX} ${EMOJI.WARNING} Warning: --vendor is deprecated. Use --client.`);
+        clientName = args.vendor;
+    }
+    // Codex handling (deprecated legacy flag)
     if (args.codex) {
-        const prompt = generateCodexPrompt(doc, id, thinkingOptions);
+        if (!clientName) {
+            console.warn(`${LOG_PREFIX} ${EMOJI.WARNING} Warning: --codex is deprecated. Use --client codex-cli.`);
+            clientName = 'codex-cli';
+        }
+    }
+    if (!clientName) {
+        clientName = config.agents.defaultClient || 'claude-code';
+    }
+    // Create strategy
+    const strategy = SpawnStrategyFactory.create(clientName);
+    const clientContext = { name: clientName, config: resolveClientConfig(config, clientName) };
+    if (clientName === 'codex-cli' || args.codex) {
+        const prompt = generateCodexPrompt(doc, id, strategy, {
+            ...thinkingOptions,
+            client: clientContext,
+            config,
+        });
         console.log(`${LOG_PREFIX} Generated Codex/GPT prompt for ${id}`);
         console.log(`${LOG_PREFIX} Copy the Markdown below:\n`);
-        console.log(prompt.trimEnd());
-        return;
-    }
-    // Generate and output the Task invocation
-    const invocation = generateTaskInvocation(doc, id, thinkingOptions);
-    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-1945: Record spawn event to registry (non-blocking)
-    // Only record if --parent-wu is provided (orchestrator context)
-    if (args.parentWu) {
-        const registryResult = await recordSpawnToRegistry({
-            parentWuId: args.parentWu,
-            targetWuId: id,
-            lane: doc.lane || 'Unknown',
-            baseDir: '.beacon/state',
+        // ...
+        // Generate and output the Task invocation
+        const invocation = generateTaskInvocation(doc, id, strategy, {
+            ...thinkingOptions,
+            client: clientContext,
+            config,
         });
-        const registryMessage = formatSpawnRecordedMessage(registryResult.spawnId, registryResult.error);
-        console.log(`\n${registryMessage}`);
+        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-1945: Record spawn event to registry (non-blocking)
+        // Only record if --parent-wu is provided (orchestrator context)
+        if (args.parentWu) {
+            const registryResult = await recordSpawnToRegistry({
+                parentWuId: args.parentWu,
+                targetWuId: id,
+                lane: doc.lane || 'Unknown',
+                baseDir: '.beacon/state',
+            });
+            const registryMessage = formatSpawnRecordedMessage(registryResult.spawnId, registryResult.error);
+            console.log(`\n${registryMessage}`);
+        }
     }
 }
 // Guard main() for testability
-import { fileURLToPath } from 'node:url';
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
     main();
 }

package/dist/wu-validation.d.ts

@@ -13,6 +13,7 @@
  * @see {@link tools/lib/wu-schema.mjs} - WU schema with exposure field
  * @see {@link tools/lib/wu-constants.mjs} - WU_EXPOSURE values
  */
+export declare function resolveExposureDefault(lane: any): "documentation" | "backend-only";
 /**
  * Warning message templates with remediation guidance.
  * All messages include the WU ID for context.

package/dist/wu-validation.js

@@ -14,6 +14,26 @@
  * @see {@link tools/lib/wu-constants.mjs} - WU_EXPOSURE values
  */
 import { WU_EXPOSURE } from './wu-constants.js';
+const LANE_PARENTS = {
+    CONTENT: 'content',
+    FRAMEWORK: 'framework',
+    OPERATIONS: 'operations',
+};
+function getLaneParent(lane) {
+    if (!lane || typeof lane !== 'string')
+        return '';
+    return lane.split(':')[0].trim().toLowerCase();
+}
+export function resolveExposureDefault(lane) {
+    const parent = getLaneParent(lane);
+    if (parent === LANE_PARENTS.CONTENT) {
+        return WU_EXPOSURE.DOCUMENTATION;
+    }
+    if (parent === LANE_PARENTS.FRAMEWORK || parent === LANE_PARENTS.OPERATIONS) {
+        return WU_EXPOSURE.BACKEND_ONLY;
+    }
+    return undefined;
+}
 /**
  * UI verification keywords to search for in acceptance criteria.
  * Case-insensitive patterns that indicate the acceptance criteria
@@ -99,7 +119,7 @@ export function validateExposure(wu, options = {}) {
         return { valid: true, warnings: [] };
     }
     const wuId = wu.id || 'WU-???';
-    const exposure = wu.exposure;
+    const exposure = wu.exposure || resolveExposureDefault(wu.lane);
     // Check 1: exposure field presence
     if (!exposure) {
         warnings.push(EXPOSURE_WARNING_MESSAGES.MISSING_EXPOSURE(wuId));

package/dist/wu-validator.d.ts

@@ -60,3 +60,54 @@ export declare function validateWUCodePaths(codePaths: any, options?: ValidateWU
     errors: any[];
     warnings: any[];
 };
+/**
+ * Result of placeholder validation
+ */
+export interface PlaceholderValidationResult {
+    /** Whether validation passed (no placeholders found) */
+    valid: boolean;
+    /** List of validation errors */
+    errors: string[];
+    /** Fields that contain placeholders */
+    fieldsWithPlaceholders: string[];
+}
+/**
+ * WU-1025: Validate that WU spec content does not contain PLACEHOLDER markers
+ *
+ * Used by wu:create (for inline content) and wu:claim (for full spec).
+ * Provides clear error messages telling the user which fields need to be fixed.
+ *
+ * @param {object} spec - WU spec content to validate
+ * @param {string} [spec.description] - WU description
+ * @param {string[]|object} [spec.acceptance] - Acceptance criteria (array or object)
+ * @returns {PlaceholderValidationResult} Validation result with errors and affected fields
+ *
+ * @example
+ * // wu:create validation (inline content only)
+ * const result = validateNoPlaceholders({ description: args.description });
+ * if (!result.valid) {
+ *   die(`Cannot create WU:\n${result.errors.join('\n')}`);
+ * }
+ *
+ * @example
+ * // wu:claim validation (full spec)
+ * const result = validateNoPlaceholders(wuDoc);
+ * if (!result.valid) {
+ *   die(`Cannot claim WU:\n${result.errors.join('\n')}`);
+ * }
+ */
+export declare function validateNoPlaceholders(spec: {
+    description?: string;
+    acceptance?: string[] | Record<string, string[]>;
+}): PlaceholderValidationResult;
+/**
+ * WU-1025: Build error message for placeholder validation failure
+ *
+ * Creates a user-friendly error message with actionable guidance.
+ *
+ * @param {string} command - Command that failed ('wu:create' or 'wu:claim')
+ * @param {PlaceholderValidationResult} result - Validation result
+ * @param {string} [wuId] - WU ID (for wu:claim error messages)
+ * @returns {string} Formatted error message
+ */
+export declare function buildPlaceholderErrorMessage(command: string, result: PlaceholderValidationResult, wuId?: string): string;

package/dist/wu-validator.js

@@ -14,6 +14,7 @@ import { readFileSync, existsSync } from 'node:fs';
 import path from 'node:path';
 import { execSync } from 'node:child_process';
 import { STDIO } from './wu-constants.js';
+import { PLACEHOLDER_SENTINEL } from './wu-schema.js';
 /**
  * Check if a file path is a test file
  * @param {string} filePath - Path to check
@@ -323,3 +324,110 @@ function formatMockFindings(findings) {
     msg += '\nVerify these are actual implementations, not placeholder code.';
     return msg;
 }
+/**
+ * WU-1025: Validate that WU spec content does not contain PLACEHOLDER markers
+ *
+ * Used by wu:create (for inline content) and wu:claim (for full spec).
+ * Provides clear error messages telling the user which fields need to be fixed.
+ *
+ * @param {object} spec - WU spec content to validate
+ * @param {string} [spec.description] - WU description
+ * @param {string[]|object} [spec.acceptance] - Acceptance criteria (array or object)
+ * @returns {PlaceholderValidationResult} Validation result with errors and affected fields
+ *
+ * @example
+ * // wu:create validation (inline content only)
+ * const result = validateNoPlaceholders({ description: args.description });
+ * if (!result.valid) {
+ *   die(`Cannot create WU:\n${result.errors.join('\n')}`);
+ * }
+ *
+ * @example
+ * // wu:claim validation (full spec)
+ * const result = validateNoPlaceholders(wuDoc);
+ * if (!result.valid) {
+ *   die(`Cannot claim WU:\n${result.errors.join('\n')}`);
+ * }
+ */
+export function validateNoPlaceholders(spec) {
+    const errors = [];
+    const fieldsWithPlaceholders = [];
+    // Check description
+    if (spec.description && spec.description.includes(PLACEHOLDER_SENTINEL)) {
+        fieldsWithPlaceholders.push('description');
+        errors.push(`Description contains ${PLACEHOLDER_SENTINEL} marker.\n` +
+            `  Fix: Replace placeholder text with actual description.\n` +
+            `  Example: --description "Implement X feature to enable Y functionality"`);
+    }
+    // Check acceptance criteria (supports both array and object formats)
+    if (spec.acceptance) {
+        const hasPlaceholder = checkForPlaceholderInAcceptance(spec.acceptance);
+        if (hasPlaceholder) {
+            fieldsWithPlaceholders.push('acceptance');
+            errors.push(`Acceptance criteria contain ${PLACEHOLDER_SENTINEL} markers.\n` +
+                `  Fix: Replace placeholder text with actual acceptance criteria.\n` +
+                `  Example: --acceptance "Feature X works as expected" --acceptance "Tests pass"`);
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        fieldsWithPlaceholders,
+    };
+}
+/**
+ * Helper: Recursively check acceptance criteria for placeholder markers
+ *
+ * Supports both formats:
+ * - Flat array: ["criterion 1", "criterion 2"]
+ * - Nested object: { functional: ["criterion"], technical: ["criterion"] }
+ *
+ * @param {string[]|object} acceptance - Acceptance criteria
+ * @returns {boolean} True if any placeholder found
+ */
+function checkForPlaceholderInAcceptance(acceptance) {
+    if (Array.isArray(acceptance)) {
+        return acceptance.some((item) => typeof item === 'string' && item.includes(PLACEHOLDER_SENTINEL));
+    }
+    if (typeof acceptance === 'object' && acceptance !== null) {
+        return Object.values(acceptance).some((value) => {
+            if (Array.isArray(value)) {
+                return value.some((item) => typeof item === 'string' && item.includes(PLACEHOLDER_SENTINEL));
+            }
+            return false;
+        });
+    }
+    return false;
+}
+/**
+ * WU-1025: Build error message for placeholder validation failure
+ *
+ * Creates a user-friendly error message with actionable guidance.
+ *
+ * @param {string} command - Command that failed ('wu:create' or 'wu:claim')
+ * @param {PlaceholderValidationResult} result - Validation result
+ * @param {string} [wuId] - WU ID (for wu:claim error messages)
+ * @returns {string} Formatted error message
+ */
+export function buildPlaceholderErrorMessage(command, result, wuId) {
+    const header = command === 'wu:create'
+        ? `Cannot create WU with placeholder markers`
+        : `Cannot claim ${wuId || 'WU'} - spec contains placeholder markers`;
+    const fieldsText = result.fieldsWithPlaceholders.join(', ');
+    let message = `
+❌ ${header}
+
+Fields with ${PLACEHOLDER_SENTINEL} markers: ${fieldsText}
+
+${result.errors.join('\n\n')}
+`;
+    if (command === 'wu:claim' && wuId) {
+        message += `
+To fix, edit the WU spec:
+  pnpm wu:edit --id ${wuId} --description "..." --acceptance "..."
+
+Or manually edit: docs/04-operations/tasks/wu/${wuId}.yaml
+`;
+    }
+    return message;
+}