@lumenflow/core 1.0.0 → 1.3.2

package/dist/wu-done-worktree.d.ts

@@ -132,7 +132,6 @@ export declare function checkMergeConflicts(branch: any): Promise<void>;
  * @throws {Error} When code_paths defined but files not modified in commits
  */
 export declare function checkEmptyMerge(branch: any, doc?: any): Promise<void>;
-export declare function isBranchAlreadyMerged(branch: any): Promise<boolean>;
 /**
  * Merge lane branch to main with exponential backoff retry (WU-1747)
  *

package/dist/wu-done-worktree.js

@@ -28,12 +28,16 @@ import { BRANCHES, REMOTES, THRESHOLDS, LOG_PREFIX, EMOJI, COMMIT_FORMATS, BOX,
 import { RECOVERY, REBASE, PREFLIGHT, MERGE } from './wu-done-messages.js';
 import { getDriftLevel, DRIFT_LEVELS } from './branch-drift.js';
 import { createError, ErrorCodes } from './error-handler.js';
+import { createRecoveryError, createValidationError } from './wu-done-errors.js';
 import { validateDoneWU, validateAndNormalizeWUYAML } from './wu-schema.js';
 import { assertTransition } from './state-machine.js';
 import { detectZombieState, resetWorktreeYAMLForRecovery, getRecoveryAttemptCount, incrementRecoveryAttempt, clearRecoveryAttempts, shouldEscalateToManualIntervention, MAX_RECOVERY_ATTEMPTS, } from './wu-recovery.js';
 import { isPRModeEnabled, createPR, printPRCreatedMessage } from './wu-done-pr.js';
+import { isBranchAlreadyMerged } from './wu-done-branch-utils.js';
 // WU-1371: Import rebase artifact cleanup functions
 import { detectRebasedArtifacts, cleanupRebasedArtifacts } from './rebase-artifact-cleanup.js';
+// WU-1061: Import docs regeneration utilities
+import { maybeRegenerateAndStageDocs } from './wu-done-docs-generate.js';
 import { WUTransaction, createTransactionSnapshot, restoreFromSnapshot } from './wu-transaction.js';
 // WU-1506: Import backlog invariant repair
 // WU-1574: Removed repairBacklogInvariants - no longer needed with state store architecture
@@ -113,7 +117,7 @@ export async function executeWorktreeCompletion(context) {
             console.log(`${BOX.SIDE}  Or reset the recovery counter:`);
             console.log(`${BOX.SIDE}  rm .beacon/recovery/${id}.recovery`);
             console.log(BOX.BOT);
-            throw createError(ErrorCodes.RECOVERY_ERROR, `Recovery loop detected for ${id} after ${attemptCount} attempts. Manual intervention required.`, { wuId: id, attemptCount, maxAttempts: MAX_RECOVERY_ATTEMPTS });
+            throw createRecoveryError(`Recovery loop detected for ${id} after ${attemptCount} attempts. Manual intervention required.`, { wuId: id, attemptCount, maxAttempts: MAX_RECOVERY_ATTEMPTS });
         }
         // Increment attempt counter before trying recovery
         const newAttemptCount = incrementRecoveryAttempt(id);
@@ -184,7 +188,7 @@ export async function executeWorktreeCompletion(context) {
         // This catches schema issues early and auto-fixes normalizable problems
         const normalizeResult = validateAndNormalizeWUYAML(docForUpdate);
         if (!normalizeResult.valid) {
-            throw createError(ErrorCodes.VALIDATION_ERROR, `WU YAML validation failed:\n  - ${normalizeResult.errors.join('\n  - ')}\n\nNext step: Fix the validation errors in ${workingWUPath} and rerun wu:done`, { wuId: id });
+            throw createValidationError(`WU YAML validation failed:\n  - ${normalizeResult.errors.join('\n  - ')}\n\nNext step: Fix the validation errors in ${workingWUPath} and rerun wu:done`, { wuId: id });
         }
         // WU-1811: If normalizations were applied, write back to YAML file
         if (normalizeResult.wasNormalized) {
@@ -197,7 +201,7 @@ export async function executeWorktreeCompletion(context) {
         // Validate done-specific completeness (uses normalized data)
         const completenessResult = validateDoneWU(normalizeResult.normalized);
         if (!completenessResult.valid) {
-            throw createError(ErrorCodes.VALIDATION_ERROR, `Cannot mark WU as done - spec incomplete:\n  ${completenessResult.errors.join('\n  ')}\n\nNext step: Update ${workingWUPath} to meet completion requirements and rerun wu:done`, { wuId: id });
+            throw createValidationError(`Cannot mark WU as done - spec incomplete:\n  ${completenessResult.errors.join('\n  ')}\n\nNext step: Update ${workingWUPath} to meet completion requirements and rerun wu:done`, { wuId: id });
         }
         console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} All validations passed`);
         // ======================================================================
@@ -252,13 +256,23 @@ export async function executeWorktreeCompletion(context) {
             stampPath: workingStampPath,
         });
         if (!postMutationResult.valid) {
-            throw createError(ErrorCodes.VALIDATION_ERROR, `Post-mutation validation failed:\n  ${postMutationResult.errors.join('\n  ')}`, { wuId: id, errors: postMutationResult.errors });
+            throw createValidationError(`Post-mutation validation failed:\n  ${postMutationResult.errors.join('\n  ')}`, { wuId: id, errors: postMutationResult.errors });
         }
         console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Post-mutation validation passed (WU-1617)`);
         // ======================================================================
         // PHASE 4: GIT OPERATIONS (stage, format, commit)
         // Files are now written - proceed with git operations
         // ======================================================================
+        // ======================================================================
+        // WU-1061: Regenerate docs if doc-source files changed
+        // This runs BEFORE stageAndFormatMetadata to include doc outputs
+        // in the single atomic commit
+        // Uses main as base to detect changes introduced by this WU
+        // ======================================================================
+        await maybeRegenerateAndStageDocs({
+            baseBranch: BRANCHES.MAIN,
+            repoRoot: worktreePath,
+        });
         // Stage and format files
         await stageAndFormatMetadata({
             id,
@@ -930,7 +944,12 @@ export async function checkEmptyMerge(branch, doc = null) {
             const missingCodePaths = codePaths.filter((codePath) => !modifiedFiles.some((modified) => modified.includes(codePath) || codePath.includes(modified)));
             if (missingCodePaths.length > 0) {
                 // BLOCK: code_paths defined but files not modified
-                throw createError(ErrorCodes.VALIDATION_ERROR, PREFLIGHT.CODE_PATHS_NOT_MODIFIED(missingCodePaths), { branch, codePaths, missingCodePaths, modifiedFiles });
+                throw createValidationError(PREFLIGHT.CODE_PATHS_NOT_MODIFIED(missingCodePaths), {
+                    branch,
+                    codePaths,
+                    missingCodePaths,
+                    modifiedFiles,
+                });
             }
             // All code_paths files were modified
             console.log(PREFLIGHT.CODE_PATHS_VERIFIED);
@@ -951,31 +970,6 @@ export async function checkEmptyMerge(branch, doc = null) {
         console.warn(`${LOG_PREFIX.DONE} Warning: Could not check for empty merge: ${e.message}`);
     }
 }
-/**
- * Check if branch is already merged to main
- *
- * @param {string} branch - Lane branch name
- * @returns {Promise<boolean>} Whether branch is already merged
- */
-/** @constant {number} SHA_SHORT_LENGTH - Length of shortened git SHA hashes for display */
-const SHA_SHORT_LENGTH = 8;
-export async function isBranchAlreadyMerged(branch) {
-    const gitAdapter = getGitForCwd();
-    try {
-        const branchTip = (await gitAdapter.getCommitHash(branch)).trim();
-        const mergeBase = (await gitAdapter.mergeBase(BRANCHES.MAIN, branch)).trim();
-        const mainHead = (await gitAdapter.getCommitHash(BRANCHES.MAIN)).trim();
-        if (branchTip === mergeBase) {
-            console.log(PREFLIGHT.BRANCH_INFO(branch, branchTip.substring(0, SHA_SHORT_LENGTH), mergeBase.substring(0, SHA_SHORT_LENGTH), mainHead.substring(0, SHA_SHORT_LENGTH)));
-            return true;
-        }
-        return false;
-    }
-    catch (e) {
-        console.warn(`${LOG_PREFIX.DONE} Warning: Could not check if branch is merged: ${e.message}`);
-        return false;
-    }
-}
 async function isMainAncestorOfBranch(gitAdapter, branch) {
     try {
         await gitAdapter.raw([GIT_COMMANDS.MERGE_BASE, GIT_FLAGS.IS_ANCESTOR, BRANCHES.MAIN, branch]);

package/dist/wu-schema.js

@@ -109,9 +109,7 @@ const normalizedMultilineString = z.string().transform((s) => s.replace(/\\n/g,
  *
  * WU-1750: After normalization, paths should be clean. This catches any edge cases.
  */
-const filePathItem = z
-    .string()
-    .refine((s) => !s.includes('\n') && !s.includes('\\n'), {
+const filePathItem = z.string().refine((s) => !s.includes('\n') && !s.includes('\\n'), {
     message: 'File path cannot contain newlines - split into separate array items',
 });
 /**
@@ -828,10 +826,12 @@ export function validateWUCompleteness(wu) {
         warnings.push(`${wu.id}: Missing 'tests.manual' field. Add manual verification steps for acceptance criteria.`);
     }
     // Check for spec_refs (features should link to plans/specs)
+    // WU-1062: Accepts both repo-relative paths (docs/04-operations/plans/) and
+    // external paths (~/.lumenflow/plans/, $LUMENFLOW_HOME/plans/, lumenflow://plans/)
     if (type === 'feature') {
         const hasSpecRefs = wu.spec_refs && wu.spec_refs.length > 0;
         if (!hasSpecRefs) {
-            warnings.push(`${wu.id}: Missing 'spec_refs' field. Link to plan file in docs/04-operations/plans/ for traceability.`);
+            warnings.push(`${wu.id}: Missing 'spec_refs' field. Link to plan file (docs/04-operations/plans/, lumenflow://plans/, or ~/.lumenflow/plans/) for traceability.`);
         }
     }
     return { warnings };

package/dist/wu-spawn-skills.d.ts

@@ -0,0 +1,19 @@
+import type { ClientConfig } from './lumenflow-config-schema.js';
+interface ClientContext {
+    name: string;
+    config?: ClientConfig;
+}
+export declare function resolveClientConfig(config: any, clientName: any): any;
+export declare function resolveSkillsPaths(config: any, clientName: any): {
+    clientConfig: any;
+    configuredSkillsDir: any;
+    configuredAgentsDir: any;
+    skillsDir: any;
+    agentsDir: any;
+    configuredSkillsMissing: boolean;
+    configuredAgentsMissing: boolean;
+};
+export declare function generateSkillsCatalogGuidance(config: any, clientName: any): string;
+export declare function generateClientSkillsGuidance(clientContext: ClientContext): string;
+export declare function generateSkillsSelectionSection(doc: any, config: any, clientName: any): string;
+export {};

package/dist/wu-spawn-skills.js

@@ -0,0 +1,148 @@
+import { existsSync } from 'node:fs';
+const KNOWN_SKILLS_DIRS = [
+    '.lumenflow/skills',
+    '.claude/skills',
+    '.codex/skills',
+    '.gemini/skills',
+];
+const KNOWN_AGENTS_DIRS = [
+    '.lumenflow/agents',
+    '.claude/agents',
+    '.codex/agents',
+    '.gemini/agents',
+];
+const SECTION = {
+    skillsSelection: '## Skills Selection',
+    skillsCatalog: '### Skills Catalog',
+    softPolicy: '### Soft Policy (baselines for this WU)',
+    additionalSkills: '### Additional Skills (load if needed)',
+    gracefulDegradation: '### Graceful Degradation',
+    clientSkills: '### Client Skills Guidance',
+};
+const MESSAGES = {
+    skillsIntro: '**IMPORTANT**: Before starting work, select and load relevant skills.',
+    catalogMissing: 'No skills directories configured or found. Set `directories.skillsDir` or `agents.clients.<client>.skillsDir` in .lumenflow.config.yaml.',
+    baselineFallback: '- Load baseline skills: `/skill wu-lifecycle`, `/skill tdd-workflow` (for features)\n- Continue with implementation using Mandatory Standards below',
+};
+const CONTEXT_HINTS = {
+    wuLifecycle: '- `wu-lifecycle` — ALL WUs need workflow automation',
+    worktreeDiscipline: '- `worktree-discipline` — ALL WUs need path safety',
+    tddWorkflow: '- `tdd-workflow` — TDD is mandatory for feature/enhancement WUs',
+    bugClassification: '- `bug-classification` — Bug severity assessment',
+    lumenflowGates: '- `lumenflow-gates` — Tooling often affects gates',
+    beaconCompliance: '- `beacon-compliance` — Intelligence lane requires Beacon validation',
+    promptManagement: '- `prompt-management` — For prompt template work',
+    frontendDesign: '- `frontend-design` — For UI component work',
+};
+const ADDITIONAL_SKILLS_TABLE = `| 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 |`;
+export function resolveClientConfig(config, clientName) {
+    const clients = config?.agents?.clients || {};
+    if (!clientName)
+        return undefined;
+    if (clients[clientName])
+        return clients[clientName];
+    const matchKey = Object.keys(clients).find((key) => key.toLowerCase() === clientName.toLowerCase());
+    return matchKey ? clients[matchKey] : undefined;
+}
+function uniqueNonEmpty(values) {
+    const seen = new Set();
+    const result = [];
+    for (const value of values) {
+        if (!value)
+            continue;
+        if (seen.has(value))
+            continue;
+        seen.add(value);
+        result.push(value);
+    }
+    return result;
+}
+export function resolveSkillsPaths(config, clientName) {
+    const clientConfig = resolveClientConfig(config, clientName);
+    const configuredSkillsDir = clientConfig?.skillsDir || config?.directories?.skillsDir;
+    const configuredAgentsDir = config?.directories?.agentsDir;
+    const skillsCandidates = uniqueNonEmpty([configuredSkillsDir, ...KNOWN_SKILLS_DIRS]);
+    const agentsCandidates = uniqueNonEmpty([configuredAgentsDir, ...KNOWN_AGENTS_DIRS]);
+    const skillsDir = skillsCandidates.find((candidate) => existsSync(candidate));
+    const agentsDir = agentsCandidates.find((candidate) => existsSync(candidate));
+    const configuredSkillsMissing = Boolean(configuredSkillsDir && !existsSync(configuredSkillsDir));
+    const configuredAgentsMissing = Boolean(configuredAgentsDir && !existsSync(configuredAgentsDir));
+    return {
+        clientConfig,
+        configuredSkillsDir,
+        configuredAgentsDir,
+        skillsDir,
+        agentsDir,
+        configuredSkillsMissing,
+        configuredAgentsMissing,
+    };
+}
+export function generateSkillsCatalogGuidance(config, clientName) {
+    const resolution = resolveSkillsPaths(config, clientName);
+    const lines = [];
+    if (resolution.skillsDir) {
+        lines.push(`- Check \`${resolution.skillsDir}\` for available skills.`);
+    }
+    if (resolution.agentsDir) {
+        lines.push(`- Check \`${resolution.agentsDir}\` for agent configs (optional).`);
+    }
+    if (lines.length > 0) {
+        return `${SECTION.skillsCatalog}\n\n${lines.join('\n')}\n`;
+    }
+    const configuredHint = resolution.configuredSkillsDir
+        ? `Configured skillsDir \`${resolution.configuredSkillsDir}\` was not found. `
+        : '';
+    const clientHint = clientName
+        ? `agents.clients.${clientName}.skillsDir`
+        : 'agents.clients.<client>.skillsDir';
+    return `${SECTION.skillsCatalog}\n\n${configuredHint}No skills directories configured or found. Set \`directories.skillsDir\` or \`${clientHint}\` in .lumenflow.config.yaml.\n`;
+}
+export function generateClientSkillsGuidance(clientContext) {
+    const skills = clientContext?.config?.skills;
+    if (!skills ||
+        (!skills.instructions && (!skills.recommended || skills.recommended.length === 0))) {
+        return '';
+    }
+    const instructions = skills.instructions ? `${skills.instructions.trim()}\n\n` : '';
+    const recommended = skills.recommended && skills.recommended.length > 0
+        ? `Recommended skills:\n${skills.recommended.map((s) => `- \`${s}\``).join('\n')}\n`
+        : '';
+    return `${SECTION.clientSkills} (${clientContext.name})\n\n${instructions}${recommended}`;
+}
+export function generateSkillsSelectionSection(doc, config, clientName) {
+    const lane = doc.lane || '';
+    const type = doc.type || 'feature';
+    const laneParent = lane.split(':')[0].trim();
+    const contextHints = [];
+    contextHints.push(CONTEXT_HINTS.wuLifecycle);
+    contextHints.push(CONTEXT_HINTS.worktreeDiscipline);
+    if (type === 'feature' || type === 'enhancement') {
+        contextHints.push(CONTEXT_HINTS.tddWorkflow);
+    }
+    if (type === 'bug') {
+        contextHints.push(CONTEXT_HINTS.bugClassification);
+    }
+    if (laneParent === 'Operations' && lane.includes('Tooling')) {
+        contextHints.push(CONTEXT_HINTS.lumenflowGates);
+    }
+    if (laneParent === 'Intelligence') {
+        contextHints.push(CONTEXT_HINTS.beaconCompliance);
+        contextHints.push(CONTEXT_HINTS.promptManagement);
+    }
+    if (laneParent === 'Experience') {
+        contextHints.push(CONTEXT_HINTS.frontendDesign);
+    }
+    const softPolicySection = `${SECTION.softPolicy}\n\nBased on WU context, consider loading:\n\n${contextHints.join('\n')}\n\n`;
+    const catalogGuidance = generateSkillsCatalogGuidance(config, clientName);
+    return `${SECTION.skillsSelection}\n\n${MESSAGES.skillsIntro}\n\n${catalogGuidance}${softPolicySection}${SECTION.additionalSkills}\n\n${ADDITIONAL_SKILLS_TABLE}\n\n${SECTION.gracefulDegradation}\n\nIf the skill catalogue is missing or invalid:\n${MESSAGES.baselineFallback}\n`;
+}

package/dist/wu-spawn.d.ts

@@ -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,8 +25,9 @@
  * 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 type { ClientConfig, LumenFlowConfig } from './lumenflow-config-schema.js';
 /**
  * Generate effort scaling rules section (WU-1986)
  *
@@ -119,19 +120,31 @@ export declare function generateWorktreePathGuidance(worktreePath: any): string;
  * @returns {string} Action section content
  */
 export declare function generateActionSection(doc: any, id: any): string;
+interface ClientContext {
+    name: string;
+    config?: ClientConfig;
+}
+interface SpawnOptions {
+    thinking?: boolean;
+    noThinking?: boolean;
+    budget?: string;
+    client?: ClientContext;
+    config?: LumenFlowConfig;
+}
 /**
  * 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 declare function generateTaskInvocation(doc: any, id: any, options?: {}): string;
-export declare function generateCodexPrompt(doc: any, id: any, options?: {}): string;
+export declare function generateTaskInvocation(doc: any, id: any, strategy: any, options?: SpawnOptions): string;
+export declare function generateCodexPrompt(doc: any, id: any, strategy: any, options?: SpawnOptions): string;
 /**
  * WU-1603: Check if a lane is currently occupied by another WU
  *