@lumenflow/core 1.3.0 → 1.3.3

package/dist/wu-create-validators.js

@@ -1,16 +1,51 @@
 /**
- * WU Create Validators (WU-2107)
+ * WU Create Validators (WU-2107, WU-1062)
  *
- * Validation helpers for wu:create, including lane inference surfacing.
+ * Validation helpers for wu:create, including:
+ * - Lane inference surfacing (WU-2107)
+ * - External spec_refs validation (WU-1062)
  *
  * When agents create WUs, this module helps surface lane inference suggestions
  * to guide better lane selection and improve parallelization.
  *
+ * WU-1062: Validates spec_refs paths, accepting both repo-relative paths
+ * and external paths (lumenflow://, ~/.lumenflow/, $LUMENFLOW_HOME/).
+ *
  * NOTE: This is domain-specific WU workflow code, not a general utility.
  * No external library exists for LumenFlow lane inference validation.
  */
+import { isExternalPath, normalizeSpecRef } from './lumenflow-home.js';
 /** Confidence threshold for showing suggestion (percentage) */
 const CONFIDENCE_THRESHOLD_LOW = 30;
+/** Prefixes that indicate repo-internal paths (WU-1069) */
+const REPO_INTERNAL_PREFIXES = ['./', '.lumenflow/'];
+/**
+ * WU-1069: Check if a path is a repo-internal path that should be rejected
+ *
+ * Repo-internal paths start with ./ or .lumenflow/ and indicate the agent
+ * is attempting to store plans inside the repository instead of externally.
+ *
+ * @param {string} path - Path to check
+ * @returns {boolean} True if path is repo-internal and should be rejected
+ */
+export function isRepoInternalPath(path) {
+    return REPO_INTERNAL_PREFIXES.some((prefix) => path.startsWith(prefix));
+}
+/**
+ * WU-1069: Build error message for repo-internal path rejection
+ *
+ * @param {string} path - The rejected path
+ * @returns {string} Error message with correct format examples
+ */
+export function buildRepoInternalPathError(path) {
+    return (`Rejected repo-internal spec_ref path: "${path}"\n` +
+        `Plans must be stored externally, not inside the repository.\n\n` +
+        `Valid path formats:\n` +
+        `  - lumenflow://plans/WU-XXXX-plan.md (recommended)\n` +
+        `  - ~/.lumenflow/plans/WU-XXXX-plan.md\n` +
+        `  - $LUMENFLOW_HOME/plans/WU-XXXX-plan.md\n\n` +
+        `Use --plan flag to auto-create: pnpm wu:create --plan --id WU-XXXX ...`);
+}
 /**
  * Generate a warning message when provided lane differs from inferred lane.
  *
@@ -91,3 +126,77 @@ export function validateLaneWithInference(providedLane, codePaths, description,
         return { shouldWarn: false, warning: '' };
     }
 }
+/**
+ * WU-1062: Validate spec_refs paths
+ *
+ * Accepts:
+ * - Repo-relative paths: docs/04-operations/plans/WU-XXX-plan.md
+ * - External paths: lumenflow://plans/WU-XXX-plan.md
+ * - Tilde paths: ~/.lumenflow/plans/WU-XXX-plan.md
+ * - Env var paths: $LUMENFLOW_HOME/plans/WU-XXX-plan.md
+ *
+ * @param {string[]} specRefs - Array of spec reference paths
+ * @returns {{ valid: boolean, errors: string[], warnings: string[] }} Validation result
+ */
+export function validateSpecRefs(specRefs) {
+    const errors = [];
+    const warnings = [];
+    if (!specRefs || specRefs.length === 0) {
+        return { valid: true, errors, warnings };
+    }
+    for (const ref of specRefs) {
+        // Check for empty refs
+        if (!ref || ref.trim().length === 0) {
+            errors.push('Empty spec_ref detected');
+            continue;
+        }
+        // WU-1069: Reject repo-internal paths (paths starting with ./ or .lumenflow/)
+        // This prevents agents from storing plans inside the repository
+        if (isRepoInternalPath(ref)) {
+            errors.push(buildRepoInternalPathError(ref));
+            continue;
+        }
+        // External paths are valid (will be resolved at runtime)
+        if (isExternalPath(ref)) {
+            // Add informational warning about external paths
+            warnings.push(`External spec_ref: "${ref}" - ensure plan exists at ${normalizeSpecRef(ref)}`);
+            continue;
+        }
+        // Repo-relative paths should follow conventions (docs/ without ./ prefix)
+        const isValidRepoPath = ref.startsWith('docs/') || ref.endsWith('.md');
+        if (!isValidRepoPath) {
+            warnings.push(`Unconventional spec_ref path: "${ref}" - consider using docs/04-operations/plans/ or lumenflow://plans/`);
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}
+/**
+ * WU-1062: Check if spec_refs contains external paths
+ *
+ * @param {string[]} specRefs - Array of spec reference paths
+ * @returns {boolean} True if any spec_ref is an external path
+ */
+export function hasExternalSpecRefs(specRefs) {
+    if (!specRefs || specRefs.length === 0) {
+        return false;
+    }
+    return specRefs.some((ref) => isExternalPath(ref));
+}
+/**
+ * WU-1062: Normalize all spec_refs paths
+ *
+ * Expands external paths to absolute paths while keeping repo-relative paths unchanged.
+ *
+ * @param {string[]} specRefs - Array of spec reference paths
+ * @returns {string[]} Normalized paths
+ */
+export function normalizeSpecRefs(specRefs) {
+    if (!specRefs || specRefs.length === 0) {
+        return [];
+    }
+    return specRefs.map((ref) => normalizeSpecRef(ref));
+}

package/dist/wu-done-branch-only.js

@@ -23,6 +23,8 @@ import { die, createError, ErrorCodes } from './error-handler.js';
 import { validateWU, validateDoneWU } from './wu-schema.js';
 import { assertTransition } from './state-machine.js';
 import { detectZombieState, recoverZombieState } from './wu-recovery.js';
+// WU-1061: Import docs regeneration utilities
+import { maybeRegenerateAndStageDocs } from './wu-done-docs-generate.js';
 /**
  * @typedef {Object} BranchOnlyContext
  * @property {string} id - WU ID (e.g., "WU-1215")
@@ -119,6 +121,13 @@ export async function executeBranchOnlyCompletion(context) {
             statusPath: metadataStatusPath,
             backlogPath: metadataBacklogPath,
         });
+        // WU-1061: Regenerate docs if doc-source files changed
+        // This runs BEFORE stageAndFormatMetadata to include doc outputs
+        // in the single atomic commit
+        await maybeRegenerateAndStageDocs({
+            baseBranch: BRANCHES.MAIN,
+            repoRoot: metadataBasePath,
+        });
         // Step 7: Stage and format files
         await stageAndFormatMetadata({
             id,

package/dist/wu-done-docs-generate.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @file wu-done-docs-generate.ts
+ * @description Documentation regeneration utilities for wu:done
+ *
+ * WU-1061: Integrate docs:generate into wu:done for @lumenflow/* changes
+ *
+ * Detects changes to files that affect generated documentation and triggers
+ * regeneration during wu:done (after gates pass, before metadata commit).
+ */
+/**
+ * Pathspecs for files that affect generated documentation.
+ * When any of these files change, docs:generate should be run.
+ *
+ * Based on .husky/hooks/docs-sync.mjs patterns, expanded to match
+ * all files that can affect CLI/config documentation.
+ */
+export declare const DOC_SOURCE_PATHSPECS: readonly ["tools/generate-cli-docs.ts", "packages/@lumenflow/core/src/arg-parser.ts", "packages/@lumenflow/core/src/lumenflow-config-schema.ts", "packages/@lumenflow/core/src/index.ts", "packages/@lumenflow/cli/package.json", "packages/@lumenflow/cli/src/"];
+/**
+ * Output files generated by docs:generate.
+ * These files are staged before the metadata commit.
+ */
+export declare const DOC_OUTPUT_FILES: readonly ["apps/docs/src/content/docs/reference/cli.mdx", "apps/docs/src/content/docs/reference/config.mdx"];
+/**
+ * Check if any doc-source files changed compared to the base branch.
+ * Uses git diff with pathspecs for efficient detection.
+ *
+ * @param baseBranch - Base branch for comparison (e.g., 'main', 'origin/main')
+ * @returns Promise<boolean> - True if doc-source files changed
+ */
+export declare function hasDocSourceChanges(baseBranch: string): Promise<boolean>;
+/**
+ * Stage doc output files for the metadata commit.
+ *
+ * @returns Promise<void>
+ */
+export declare function stageDocOutputs(): Promise<void>;
+/**
+ * Run turbo docs:generate to regenerate documentation.
+ * Turbo handles build dependencies and caching.
+ *
+ * @param repoRoot - Repository root directory
+ * @returns void
+ */
+export declare function runDocsGenerate(repoRoot: string): void;
+/**
+ * Result of the docs regeneration check.
+ */
+export interface DocsRegenerationResult {
+    /** Whether doc-source files changed */
+    docsChanged: boolean;
+    /** Whether docs were regenerated */
+    regenerated: boolean;
+}
+/**
+ * Options for maybeRegenerateAndStageDocs.
+ */
+export interface MaybeRegenerateDocsOptions {
+    /** Base branch for comparison (e.g., 'main', calculated from defaultBranchFrom) */
+    baseBranch: string;
+    /** Repository root directory for running turbo */
+    repoRoot: string;
+}
+/**
+ * Detect doc-source changes and regenerate docs if needed.
+ * This is the main integration point for wu:done.
+ *
+ * Call this BEFORE stageAndFormatMetadata() to include doc outputs
+ * in the single atomic commit.
+ *
+ * @param options - Detection and regeneration options
+ * @returns Promise<DocsRegenerationResult> - Whether docs changed and were regenerated
+ */
+export declare function maybeRegenerateAndStageDocs(options: MaybeRegenerateDocsOptions): Promise<DocsRegenerationResult>;

package/dist/wu-done-docs-generate.js

@@ -0,0 +1,108 @@
+/**
+ * @file wu-done-docs-generate.ts
+ * @description Documentation regeneration utilities for wu:done
+ *
+ * WU-1061: Integrate docs:generate into wu:done for @lumenflow/* changes
+ *
+ * Detects changes to files that affect generated documentation and triggers
+ * regeneration during wu:done (after gates pass, before metadata commit).
+ */
+import { execSync } from 'node:child_process';
+import { getGitForCwd } from './git-adapter.js';
+import { STDIO } from './wu-constants.js';
+/**
+ * Pathspecs for files that affect generated documentation.
+ * When any of these files change, docs:generate should be run.
+ *
+ * Based on .husky/hooks/docs-sync.mjs patterns, expanded to match
+ * all files that can affect CLI/config documentation.
+ */
+export const DOC_SOURCE_PATHSPECS = [
+    'tools/generate-cli-docs.ts',
+    'packages/@lumenflow/core/src/arg-parser.ts',
+    'packages/@lumenflow/core/src/lumenflow-config-schema.ts',
+    'packages/@lumenflow/core/src/index.ts',
+    'packages/@lumenflow/cli/package.json',
+    'packages/@lumenflow/cli/src/',
+];
+/**
+ * Output files generated by docs:generate.
+ * These files are staged before the metadata commit.
+ */
+export const DOC_OUTPUT_FILES = [
+    'apps/docs/src/content/docs/reference/cli.mdx',
+    'apps/docs/src/content/docs/reference/config.mdx',
+];
+/**
+ * Check if any doc-source files changed compared to the base branch.
+ * Uses git diff with pathspecs for efficient detection.
+ *
+ * @param baseBranch - Base branch for comparison (e.g., 'main', 'origin/main')
+ * @returns Promise<boolean> - True if doc-source files changed
+ */
+export async function hasDocSourceChanges(baseBranch) {
+    try {
+        const gitAdapter = getGitForCwd();
+        const diff = await gitAdapter.raw([
+            'diff',
+            `${baseBranch}...HEAD`,
+            '--name-only',
+            '--',
+            ...DOC_SOURCE_PATHSPECS,
+        ]);
+        return diff.trim().length > 0;
+    }
+    catch {
+        // Fail-safe: don't regenerate on git errors
+        return false;
+    }
+}
+/**
+ * Stage doc output files for the metadata commit.
+ *
+ * @returns Promise<void>
+ */
+export async function stageDocOutputs() {
+    const gitAdapter = getGitForCwd();
+    await gitAdapter.add([...DOC_OUTPUT_FILES]);
+}
+/**
+ * Run turbo docs:generate to regenerate documentation.
+ * Turbo handles build dependencies and caching.
+ *
+ * @param repoRoot - Repository root directory
+ * @returns void
+ */
+export function runDocsGenerate(repoRoot) {
+    execSync('pnpm turbo docs:generate', {
+        cwd: repoRoot,
+        stdio: STDIO.INHERIT,
+        encoding: 'utf-8',
+    });
+}
+/**
+ * Detect doc-source changes and regenerate docs if needed.
+ * This is the main integration point for wu:done.
+ *
+ * Call this BEFORE stageAndFormatMetadata() to include doc outputs
+ * in the single atomic commit.
+ *
+ * @param options - Detection and regeneration options
+ * @returns Promise<DocsRegenerationResult> - Whether docs changed and were regenerated
+ */
+export async function maybeRegenerateAndStageDocs(options) {
+    const { baseBranch, repoRoot } = options;
+    // Check if doc-source files changed
+    const docsChanged = await hasDocSourceChanges(baseBranch);
+    if (!docsChanged) {
+        console.log('[wu:done] No doc-source changes detected, skipping docs:generate');
+        return { docsChanged: false, regenerated: false };
+    }
+    console.log('[wu:done] Doc-source changes detected, running turbo docs:generate...');
+    // Run turbo docs:generate (Turbo handles caching and dependencies)
+    runDocsGenerate(repoRoot);
+    // Stage the doc output files
+    await stageDocOutputs();
+    console.log('[wu:done] Documentation regenerated and staged');
+    return { docsChanged: true, regenerated: true };
+}

package/dist/wu-done-worktree.js

@@ -36,6 +36,8 @@ import { isPRModeEnabled, createPR, printPRCreatedMessage } from './wu-done-pr.j
 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
@@ -261,6 +263,16 @@ export async function executeWorktreeCompletion(context) {
         // 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,

package/dist/wu-schema.js

@@ -826,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.js

@@ -89,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
  */
@@ -96,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
@@ -733,7 +746,7 @@ function generateLaneGuidance(lane) {
 - Follow prompt versioning guidelines in ai/prompts/README.md`,
         Experience: `## Lane-Specific: Experience
 
-- Follow design system tokens in packages/@patientpath/design-system
+- Follow design system tokens defined in the project
 - Ensure accessibility compliance (WCAG 2.1 AA)`,
         Core: `## Lane-Specific: Core
 

package/dist/wu-yaml-fixer.js

@@ -15,7 +15,7 @@
  */
 import { readFileSync, writeFileSync, copyFileSync } from 'node:fs';
 import { parseYAML, stringifyYAML } from './wu-yaml.js';
-import { STRING_LITERALS } from './wu-constants.js';
+import { DEFAULTS, STRING_LITERALS } from './wu-constants.js';
 // Valid type values from wu-schema.mjs
 const VALID_TYPES = ['feature', 'bug', 'documentation', 'process', 'tooling', 'chore', 'refactor'];
 // Common type aliases that should be auto-fixed
@@ -30,8 +30,11 @@ const TYPE_ALIASES = {
     ref: 'refactor',
     proc: 'process',
 };
-// Default email domain for username → email conversion
-const DEFAULT_EMAIL_DOMAIN = 'patientpath.co.uk';
+/**
+ * Default email domain for username -> email conversion
+ * WU-1068: Changed from hardcoded 'patientpath.co.uk' to configurable default
+ */
+const DEFAULT_EMAIL_DOMAIN = DEFAULTS.EMAIL_DOMAIN;
 /**
  * Issue types that can be detected and auto-fixed
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/core",
-  "version": "1.3.0",
+  "version": "1.3.3",
   "description": "Core WU lifecycle tools for LumenFlow workflow framework",
   "keywords": [
     "lumenflow",
@@ -65,6 +65,13 @@
     "LICENSE",
     "README.md"
   ],
+  "scripts": {
+    "build": "tsc",
+    "build:dist": "tsc -p tsconfig.build.json",
+    "pack:dist": "pnpm pack",
+    "clean": "rm -rf dist *.tgz",
+    "test": "vitest run"
+  },
   "dependencies": {
     "change-case": "^5.4.4",
     "cli-progress": "^3.12.0",
@@ -76,6 +83,7 @@
     "gray-matter": "^4.0.3",
     "micromatch": "^4.0.8",
     "minimatch": "^10.1.1",
+    "ms": "^2.1.3",
     "picocolors": "^1.1.1",
     "pretty-ms": "^9.2.0",
     "ps-list": "^8.1.1",
@@ -90,8 +98,8 @@
     "vitest": "^4.0.17"
   },
   "peerDependencies": {
-    "@lumenflow/memory": "1.3.0",
-    "@lumenflow/initiatives": "1.3.0"
+    "@lumenflow/memory": "workspace:*",
+    "@lumenflow/initiatives": "workspace:*"
   },
   "peerDependenciesMeta": {
     "@lumenflow/memory": {
@@ -106,12 +114,5 @@
   },
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "build": "tsc",
-    "build:dist": "tsc -p tsconfig.build.json",
-    "pack:dist": "pnpm pack",
-    "clean": "rm -rf dist *.tgz",
-    "test": "vitest run"
   }
-}
+}