@lumenflow/core 1.3.0 → 1.3.3

package/dist/spec-branch-helpers.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Spec Branch Helpers
+ *
+ * WU-1062: External plan storage and no-main-write mode
+ *
+ * Provides helpers for working with spec branches (spec/wu-XXXX).
+ * wu:create writes to spec branches by default; wu:claim merges them to main.
+ *
+ * @module
+ */
+import type { GitAdapter } from './git-adapter.js';
+/**
+ * Spec branch prefix
+ */
+export declare const SPEC_BRANCH_PREFIX = "spec/";
+/**
+ * WU source location constants
+ */
+export declare const WU_SOURCE: {
+    /** WU exists on main branch only */
+    readonly MAIN: "main";
+    /** WU exists on spec branch only */
+    readonly SPEC_BRANCH: "spec_branch";
+    /** WU exists on both main and spec branch */
+    readonly BOTH: "both";
+    /** WU not found anywhere */
+    readonly NOT_FOUND: "not_found";
+};
+export type WUSourceType = (typeof WU_SOURCE)[keyof typeof WU_SOURCE];
+/**
+ * Get the spec branch name for a WU
+ *
+ * @param {string} wuId - Work Unit ID (e.g., 'WU-1062')
+ * @returns {string} Spec branch name (e.g., 'spec/wu-1062')
+ *
+ * @example
+ * getSpecBranchName('WU-1062') // 'spec/wu-1062'
+ */
+export declare function getSpecBranchName(wuId: string): string;
+/**
+ * Get the origin-qualified spec branch name
+ *
+ * @param {string} wuId - Work Unit ID
+ * @returns {string} Origin-qualified branch name (e.g., 'origin/spec/wu-1062')
+ */
+export declare function getOriginSpecBranch(wuId: string): string;
+/**
+ * Check if a spec branch exists on origin
+ *
+ * @param {string} wuId - Work Unit ID
+ * @param {SimpleGit} git - Git adapter instance
+ * @returns {Promise<boolean>} True if spec branch exists
+ *
+ * @example
+ * const exists = await specBranchExists('WU-1062', git);
+ */
+export declare function specBranchExists(wuId: string, git: GitAdapter): Promise<boolean>;
+/**
+ * Check if a WU exists on main branch
+ *
+ * @param {string} wuId - Work Unit ID
+ * @param {SimpleGit} git - Git adapter instance
+ * @returns {Promise<boolean>} True if WU YAML exists on main
+ */
+export declare function isWUOnMain(wuId: string, git: GitAdapter): Promise<boolean>;
+/**
+ * Merge spec branch to main branch (fast-forward only)
+ *
+ * This is used by wu:claim when a WU exists only on a spec branch.
+ * The spec branch is merged to main before creating the worktree.
+ *
+ * @param {string} wuId - Work Unit ID
+ * @param {SimpleGit} git - Git adapter instance
+ * @throws {Error} If merge fails (e.g., due to conflicts)
+ *
+ * @example
+ * await mergeSpecBranchToMain('WU-1062', git);
+ */
+export declare function mergeSpecBranchToMain(wuId: string, git: GitAdapter): Promise<void>;
+/**
+ * Delete spec branch after merge
+ *
+ * @param {string} wuId - Work Unit ID
+ * @param {SimpleGit} git - Git adapter instance
+ */
+export declare function deleteSpecBranch(wuId: string, git: GitAdapter): Promise<void>;
+/**
+ * Determine the source of a WU (main, spec branch, both, or not found)
+ *
+ * Used by wu:claim to decide whether to merge spec branch before creating worktree.
+ *
+ * @param {string} wuId - Work Unit ID
+ * @param {SimpleGit} git - Git adapter instance
+ * @returns {Promise<WUSourceType>} Source location constant
+ *
+ * @example
+ * const source = await getWUSource('WU-1062', git);
+ * if (source === WU_SOURCE.SPEC_BRANCH) {
+ *   await mergeSpecBranchToMain('WU-1062', git);
+ * }
+ */
+export declare function getWUSource(wuId: string, git: GitAdapter): Promise<WUSourceType>;
+/**
+ * Create a spec branch from current HEAD
+ *
+ * Used by wu:create in default mode (no --direct flag).
+ *
+ * @param {string} wuId - Work Unit ID
+ * @param {SimpleGit} git - Git adapter instance
+ */
+export declare function createSpecBranch(wuId: string, git: GitAdapter): Promise<void>;
+/**
+ * Push spec branch to origin
+ *
+ * @param {string} wuId - Work Unit ID
+ * @param {SimpleGit} git - Git adapter instance
+ */
+export declare function pushSpecBranch(wuId: string, git: GitAdapter): Promise<void>;

package/dist/spec-branch-helpers.js

@@ -0,0 +1,199 @@
+/**
+ * Spec Branch Helpers
+ *
+ * WU-1062: External plan storage and no-main-write mode
+ *
+ * Provides helpers for working with spec branches (spec/wu-XXXX).
+ * wu:create writes to spec branches by default; wu:claim merges them to main.
+ *
+ * @module
+ */
+import { WU_PATHS } from './wu-paths.js';
+import { REMOTES, GIT_REFS, GIT_COMMANDS, GIT_FLAGS } from './wu-constants.js';
+/**
+ * Spec branch prefix
+ */
+export const SPEC_BRANCH_PREFIX = 'spec/';
+/**
+ * WU source location constants
+ */
+export const WU_SOURCE = {
+    /** WU exists on main branch only */
+    MAIN: 'main',
+    /** WU exists on spec branch only */
+    SPEC_BRANCH: 'spec_branch',
+    /** WU exists on both main and spec branch */
+    BOTH: 'both',
+    /** WU not found anywhere */
+    NOT_FOUND: 'not_found',
+};
+/**
+ * Get the spec branch name for a WU
+ *
+ * @param {string} wuId - Work Unit ID (e.g., 'WU-1062')
+ * @returns {string} Spec branch name (e.g., 'spec/wu-1062')
+ *
+ * @example
+ * getSpecBranchName('WU-1062') // 'spec/wu-1062'
+ */
+export function getSpecBranchName(wuId) {
+    return `${SPEC_BRANCH_PREFIX}${wuId.toLowerCase()}`;
+}
+/**
+ * Get the origin-qualified spec branch name
+ *
+ * @param {string} wuId - Work Unit ID
+ * @returns {string} Origin-qualified branch name (e.g., 'origin/spec/wu-1062')
+ */
+export function getOriginSpecBranch(wuId) {
+    return GIT_REFS.remote(REMOTES.ORIGIN, getSpecBranchName(wuId));
+}
+/**
+ * Check if a spec branch exists on origin
+ *
+ * @param {string} wuId - Work Unit ID
+ * @param {SimpleGit} git - Git adapter instance
+ * @returns {Promise<boolean>} True if spec branch exists
+ *
+ * @example
+ * const exists = await specBranchExists('WU-1062', git);
+ */
+export async function specBranchExists(wuId, git) {
+    try {
+        const originBranch = getOriginSpecBranch(wuId);
+        // Use branchExists if available, otherwise check with ls-remote
+        if ('branchExists' in git && typeof git.branchExists === 'function') {
+            return await git.branchExists(originBranch);
+        }
+        // Fallback: use ls-remote to check if branch exists
+        const result = await git.raw([
+            GIT_COMMANDS.LS_REMOTE,
+            GIT_FLAGS.HEADS,
+            REMOTES.ORIGIN,
+            getSpecBranchName(wuId),
+        ]);
+        return result.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if a WU exists on main branch
+ *
+ * @param {string} wuId - Work Unit ID
+ * @param {SimpleGit} git - Git adapter instance
+ * @returns {Promise<boolean>} True if WU YAML exists on main
+ */
+export async function isWUOnMain(wuId, git) {
+    try {
+        const wuPath = WU_PATHS.WU(wuId);
+        // Check if file exists on origin/main
+        // git ls-tree returns exit 0 with empty output if file doesn't exist
+        const result = await git.raw([GIT_COMMANDS.LS_TREE, GIT_REFS.ORIGIN_MAIN, GIT_FLAGS.PATH_SEPARATOR, wuPath]);
+        return result.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Merge spec branch to main branch (fast-forward only)
+ *
+ * This is used by wu:claim when a WU exists only on a spec branch.
+ * The spec branch is merged to main before creating the worktree.
+ *
+ * @param {string} wuId - Work Unit ID
+ * @param {SimpleGit} git - Git adapter instance
+ * @throws {Error} If merge fails (e.g., due to conflicts)
+ *
+ * @example
+ * await mergeSpecBranchToMain('WU-1062', git);
+ */
+export async function mergeSpecBranchToMain(wuId, git) {
+    const specBranch = getSpecBranchName(wuId);
+    const originSpecBranch = getOriginSpecBranch(wuId);
+    // Fetch the spec branch
+    await git.fetch(REMOTES.ORIGIN, specBranch);
+    // Merge with fast-forward only (safe merge)
+    await git.merge(originSpecBranch, { ffOnly: true });
+}
+/**
+ * Delete spec branch after merge
+ *
+ * @param {string} wuId - Work Unit ID
+ * @param {SimpleGit} git - Git adapter instance
+ */
+export async function deleteSpecBranch(wuId, git) {
+    const specBranch = getSpecBranchName(wuId);
+    try {
+        // Delete local branch if exists
+        await git.deleteBranch(specBranch);
+    }
+    catch {
+        // Ignore if local branch doesn't exist
+    }
+    try {
+        // Delete remote branch
+        await git.raw([GIT_COMMANDS.PUSH, REMOTES.ORIGIN, GIT_FLAGS.DELETE_REMOTE, specBranch]);
+    }
+    catch {
+        // Ignore if remote branch doesn't exist
+    }
+}
+/**
+ * Determine the source of a WU (main, spec branch, both, or not found)
+ *
+ * Used by wu:claim to decide whether to merge spec branch before creating worktree.
+ *
+ * @param {string} wuId - Work Unit ID
+ * @param {SimpleGit} git - Git adapter instance
+ * @returns {Promise<WUSourceType>} Source location constant
+ *
+ * @example
+ * const source = await getWUSource('WU-1062', git);
+ * if (source === WU_SOURCE.SPEC_BRANCH) {
+ *   await mergeSpecBranchToMain('WU-1062', git);
+ * }
+ */
+export async function getWUSource(wuId, git) {
+    // Check both locations in parallel for efficiency
+    const [onMain, hasSpecBranch] = await Promise.all([
+        isWUOnMain(wuId, git),
+        specBranchExists(wuId, git),
+    ]);
+    if (onMain && hasSpecBranch) {
+        return WU_SOURCE.BOTH;
+    }
+    if (onMain) {
+        return WU_SOURCE.MAIN;
+    }
+    if (hasSpecBranch) {
+        return WU_SOURCE.SPEC_BRANCH;
+    }
+    return WU_SOURCE.NOT_FOUND;
+}
+/**
+ * Create a spec branch from current HEAD
+ *
+ * Used by wu:create in default mode (no --direct flag).
+ *
+ * @param {string} wuId - Work Unit ID
+ * @param {SimpleGit} git - Git adapter instance
+ */
+export async function createSpecBranch(wuId, git) {
+    const specBranch = getSpecBranchName(wuId);
+    // Create local branch and checkout
+    await git.createBranch(specBranch);
+}
+/**
+ * Push spec branch to origin
+ *
+ * @param {string} wuId - Work Unit ID
+ * @param {SimpleGit} git - Git adapter instance
+ */
+export async function pushSpecBranch(wuId, git) {
+    const specBranch = getSpecBranchName(wuId);
+    // Push to origin
+    await git.push(REMOTES.ORIGIN, specBranch);
+}

package/dist/user-normalizer.d.ts

@@ -4,11 +4,15 @@
  * Provides email normalization and domain inference for WU ownership.
  * Converts plain usernames (e.g., "tom") to email format (e.g., "tom@hellm.ai")
  * using domain from git config or .lumenflow.config.yaml.
+ *
+ * WU-1068: Removed hardcoded patientpath.co.uk domain. Domain is now inferred
+ * from git config user.email or .lumenflow.config.yaml OWNER_EMAIL.
  */
 /**
  * Default domain fallback when git config and lumenflow config unavailable
+ * WU-1068: Changed from hardcoded 'patientpath.co.uk' to generic default
  */
-export declare const DEFAULT_DOMAIN = "patientpath.co.uk";
+export declare const DEFAULT_DOMAIN: string;
 /**
  * Check if a value is a valid email address (simple check)
  *

package/dist/user-normalizer.js

@@ -4,14 +4,19 @@
  * Provides email normalization and domain inference for WU ownership.
  * Converts plain usernames (e.g., "tom") to email format (e.g., "tom@hellm.ai")
  * using domain from git config or .lumenflow.config.yaml.
+ *
+ * WU-1068: Removed hardcoded patientpath.co.uk domain. Domain is now inferred
+ * from git config user.email or .lumenflow.config.yaml OWNER_EMAIL.
  */
 import { readFile, access } from 'node:fs/promises';
 import { join } from 'node:path';
 import { getGitForCwd } from './git-adapter.js';
+import { DEFAULTS } from './wu-constants.js';
 /**
  * Default domain fallback when git config and lumenflow config unavailable
+ * WU-1068: Changed from hardcoded 'patientpath.co.uk' to generic default
  */
-export const DEFAULT_DOMAIN = 'patientpath.co.uk';
+export const DEFAULT_DOMAIN = DEFAULTS.EMAIL_DOMAIN;
 /**
  * Minimum length for a valid email local part
  */

package/dist/validators/phi-scanner.js

@@ -13,6 +13,7 @@
 import nhsValidator from 'nhs-number-validator';
 import { isValid as isValidPostcode, parse as parsePostcode } from 'postcode';
 import { PHI_TYPES, MEDICAL_CONTEXT_KEYWORDS, MEDICAL_CONTEXT_WINDOW_SIZE, TEST_NHS_NUMBERS, NHS_TEST_PREFIX, TEST_POSTCODES, TEST_DATA_MARKERS, EXCLUDED_PATH_PATTERNS, NHS_CANDIDATE_PATTERN, } from './phi-constants.js';
+import { PHI_CONFIG } from '../wu-constants.js';
 /**
  * Check if a file path should be excluded from PHI scanning
  *
@@ -137,6 +138,11 @@ export function scanForPHI(content, options = {}) {
         matches: [],
         warnings: [],
     };
+    // WU-1068: PHI scanning is gated behind config flag
+    // Projects must explicitly opt-in via LUMENFLOW_PHI_ENABLED=1 or config
+    if (!PHI_CONFIG.ENABLED) {
+        return result;
+    }
     // Handle null/undefined/empty content
     if (!content || typeof content !== 'string' || content.trim() === '') {
         return result;

package/dist/worktree-symlink.d.ts

@@ -18,6 +18,10 @@
  * pnpm monorepos create node_modules in each package with symlinks
  * to the .pnpm store. turbo typecheck and tests need these to resolve imports.
  *
+ * WU-1068: Removed @patientpath references. Only @lumenflow packages are
+ * relevant to the LumenFlow framework. Project-specific paths should be
+ * configured in .lumenflow.config.yaml.
+ *
  * @type {string[]}
  */
 export declare const NESTED_PACKAGE_PATHS: string[];

package/dist/worktree-symlink.js

@@ -43,30 +43,24 @@ const PNPM_DIR = '.pnpm';
  * pnpm monorepos create node_modules in each package with symlinks
  * to the .pnpm store. turbo typecheck and tests need these to resolve imports.
  *
+ * WU-1068: Removed @patientpath references. Only @lumenflow packages are
+ * relevant to the LumenFlow framework. Project-specific paths should be
+ * configured in .lumenflow.config.yaml.
+ *
  * @type {string[]}
  */
 export const NESTED_PACKAGE_PATHS = [
-    // Packages - supabase
-    'packages/supabase',
-    // Packages - @patientpath/*
-    'packages/@patientpath/prompts',
-    'packages/@patientpath/shared',
-    'packages/@patientpath/application',
-    'packages/@patientpath/ports',
-    'packages/@patientpath/infrastructure',
-    // Packages - @lumenflow/* (WU-2427: added for typecheck resolution)
-    'packages/@lumenflow/api',
-    'packages/@lumenflow/application',
-    'packages/@lumenflow/infrastructure',
-    // Packages - lumenflow-*
-    'packages/lumenflow-cli',
-    'packages/lumenflow-tools',
-    // Packages - beacon-explainer (WU-2427: added for typecheck resolution)
-    'packages/beacon-explainer',
-    // Apps
+    // Packages - @lumenflow/*
+    'packages/@lumenflow/core',
+    'packages/@lumenflow/cli',
+    'packages/@lumenflow/memory',
+    'packages/@lumenflow/agent',
+    'packages/@lumenflow/metrics',
+    'packages/@lumenflow/initiatives',
+    'packages/@lumenflow/shims',
+    // Apps (generic placeholders)
     'apps/web',
-    'apps/mobile',
-    'apps/hellm-ai', // WU-2427: added for typecheck resolution
+    'apps/docs',
 ];
 /**
  * Check if a symlink target points into a worktrees directory

package/dist/wu-consistency-checker.d.ts

@@ -30,6 +30,7 @@ export declare function checkWUConsistency(id: any, projectRoot?: string): Promi
         backlogInProgress?: undefined;
         statusInProgress?: undefined;
         hasWorktree?: undefined;
+        worktreePathExists?: undefined;
     };
 } | {
     valid: boolean;
@@ -41,6 +42,7 @@ export declare function checkWUConsistency(id: any, projectRoot?: string): Promi
         backlogInProgress: boolean;
         statusInProgress: boolean;
         hasWorktree: boolean;
+        worktreePathExists: boolean;
         wuExists?: undefined;
     };
 }>;

package/dist/wu-consistency-checker.js

@@ -17,7 +17,7 @@ import { constants } from 'node:fs';
 import path from 'node:path';
 import { parseYAML, stringifyYAML } from './wu-yaml.js';
 import { WU_PATHS } from './wu-paths.js';
-import { CONSISTENCY_TYPES, LOG_PREFIX, REMOTES, STRING_LITERALS, toKebab, WU_STATUS, YAML_OPTIONS, } from './wu-constants.js';
+import { CONSISTENCY_TYPES, CONSISTENCY_MESSAGES, LOG_PREFIX, REMOTES, STRING_LITERALS, toKebab, WU_STATUS, YAML_OPTIONS, } from './wu-constants.js';
 import { todayISO } from './date-utils.js';
 import { createGitForPath } from './git-adapter.js';
 /**
@@ -45,6 +45,7 @@ export async function checkWUConsistency(id, projectRoot = process.cwd()) {
     const yamlStatus = wuDoc?.status || 'unknown';
     const lane = wuDoc?.lane || '';
     const title = wuDoc?.title || '';
+    const worktreePathFromYaml = wuDoc?.worktree_path || '';
     // Check stamp existence
     let hasStamp = false;
     try {
@@ -74,6 +75,7 @@ export async function checkWUConsistency(id, projectRoot = process.cwd()) {
     const { inProgress: statusInProgress } = parseStatusSections(statusContent, id);
     // Check for worktree
     const hasWorktree = await checkWorktreeExists(id, projectRoot);
+    const worktreePathExists = await checkWorktreePathExists(worktreePathFromYaml);
     // Detection logic
     // 1. YAML done but in status.md In Progress
     if (yamlStatus === WU_STATUS.DONE && statusInProgress) {
@@ -129,6 +131,19 @@ export async function checkWUConsistency(id, projectRoot = process.cwd()) {
             canAutoRepair: true,
         });
     }
+    // 6. Claimed WU missing worktree directory
+    if (worktreePathFromYaml &&
+        !worktreePathExists &&
+        (yamlStatus === WU_STATUS.IN_PROGRESS || yamlStatus === WU_STATUS.BLOCKED)) {
+        errors.push({
+            type: CONSISTENCY_TYPES.MISSING_WORKTREE_CLAIMED,
+            wuId: id,
+            title,
+            description: CONSISTENCY_MESSAGES.MISSING_WORKTREE_CLAIMED(id, yamlStatus, worktreePathFromYaml),
+            repairAction: CONSISTENCY_MESSAGES.MISSING_WORKTREE_CLAIMED_REPAIR,
+            canAutoRepair: false,
+        });
+    }
     return {
         valid: errors.length === 0,
         errors,
@@ -139,6 +154,7 @@ export async function checkWUConsistency(id, projectRoot = process.cwd()) {
             backlogInProgress,
             statusInProgress,
             hasWorktree,
+            worktreePathExists,
         },
     };
 }
@@ -565,3 +581,21 @@ async function checkWorktreeExists(id, projectRoot) {
         return false;
     }
 }
+/**
+ * Check whether a worktree path exists on disk
+ *
+ * @param {string} worktreePath - Worktree path from WU YAML
+ * @returns {Promise<boolean>} True if path exists
+ */
+async function checkWorktreePathExists(worktreePath) {
+    if (!worktreePath) {
+        return false;
+    }
+    try {
+        await access(worktreePath, constants.R_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}