@lumenflow/core 2.2.2 → 2.3.1

package/dist/lumenflow-config-schema.js

@@ -9,6 +9,32 @@
 import { z } from 'zod';
 // WU-1067: Import gates execution schema from canonical source
 import { GatesExecutionConfigSchema } from './gates-config.js';
+// WU-1259: Import methodology config schema for resolvePolicy()
+import { MethodologyConfigSchema } from './resolve-policy.js';
+/**
+ * Event archival configuration (WU-1207)
+ *
+ * Configures archival of old WU events from .lumenflow/state/wu-events.jsonl
+ * to .lumenflow/archive/wu-events-YYYY-MM.jsonl to prevent unbounded growth.
+ */
+export const EventArchivalConfigSchema = z.object({
+    /**
+     * Archive events older than this duration in milliseconds (default: 90 days).
+     * Completed WU events older than this are moved to monthly archive files.
+     * Active WU events (in_progress/blocked/waiting) are never archived.
+     */
+    archiveAfter: z
+        .number()
+        .int()
+        .positive()
+        .default(90 * 24 * 60 * 60 * 1000),
+    /**
+     * Whether to keep archive files (default: true).
+     * When true, archived events are preserved in monthly archive files.
+     * When false, archived events are deleted (not recommended for audit trails).
+     */
+    keepArchives: z.boolean().default(true),
+});
 /**
  * Directory paths configuration
  */
@@ -50,6 +76,8 @@ export const BeaconPathsSchema = z.object({
     base: z.string().default('.lumenflow'),
     /** State directory (default: '.lumenflow/state') */
     stateDir: z.string().default('.lumenflow/state'),
+    /** Archive directory (default: '.lumenflow/archive') */
+    archiveDir: z.string().default('.lumenflow/archive'),
     /** Stamps directory (default: '.lumenflow/stamps') */
     stampsDir: z.string().default('.lumenflow/stamps'),
     /** Merge lock file (default: '.lumenflow/merge.lock') */
@@ -64,6 +92,11 @@ export const BeaconPathsSchema = z.object({
     incidents: z.string().default('.lumenflow/incidents'),
     /** Commands log file (default: '.lumenflow/commands.log') */
     commandsLog: z.string().default('.lumenflow/commands.log'),
+    /**
+     * WU-1207: Event archival configuration
+     * Controls archival of old WU events to prevent unbounded growth.
+     */
+    eventArchival: EventArchivalConfigSchema.default(() => EventArchivalConfigSchema.parse({})),
 });
 /**
  * Git configuration
@@ -175,6 +208,87 @@ export const GatesConfigSchema = z.object({
      */
     execution: GatesExecutionConfigSchema.optional(),
 });
+/**
+ * WU-1203: Progress signals configuration for sub-agent coordination
+ *
+ * When enabled, spawn prompts will include mandatory progress signal directives
+ * at configurable triggers (milestone completion, tests pass, before gates, when blocked).
+ * Frequency-based signals (every N tool calls) also supported.
+ *
+ * Addresses sub-agent coordination needs without unnecessary token waste.
+ */
+export const ProgressSignalsConfigSchema = z.object({
+    /**
+     * Enable mandatory progress signals in spawn prompts.
+     * When true, spawn prompts show "Progress Signals (Required at Milestones)"
+     * When false, spawn prompts show "Progress Signals (Optional)"
+     * @default false
+     */
+    enabled: z.boolean().default(false),
+    /**
+     * Send progress signals every N tool calls.
+     * Set to 0 to disable frequency-based signals.
+     * @default 0
+     */
+    frequency: z.number().int().nonnegative().default(0),
+    /**
+     * Signal after each acceptance criterion is completed.
+     * @default true
+     */
+    on_milestone: z.boolean().default(true),
+    /**
+     * Signal when tests first pass.
+     * @default true
+     */
+    on_tests_pass: z.boolean().default(true),
+    /**
+     * Signal before running gates.
+     * @default true
+     */
+    before_gates: z.boolean().default(true),
+    /**
+     * Signal when work is blocked.
+     * @default true
+     */
+    on_blocked: z.boolean().default(true),
+    /**
+     * Automatically checkpoint memory at signal milestones.
+     * @default false
+     */
+    auto_checkpoint: z.boolean().default(false),
+});
+/**
+ * Signal cleanup configuration (WU-1204)
+ *
+ * Configures TTL-based cleanup for signals in .lumenflow/memory/signals.jsonl
+ * to prevent unbounded growth.
+ */
+export const SignalCleanupConfigSchema = z.object({
+    /**
+     * TTL for read signals in milliseconds (default: 7 days).
+     * Read signals older than this are removed during cleanup.
+     */
+    ttl: z
+        .number()
+        .int()
+        .positive()
+        .default(7 * 24 * 60 * 60 * 1000),
+    /**
+     * TTL for unread signals in milliseconds (default: 30 days).
+     * Unread signals get a longer TTL to ensure important signals aren't missed.
+     */
+    unreadTtl: z
+        .number()
+        .int()
+        .positive()
+        .default(30 * 24 * 60 * 60 * 1000),
+    /**
+     * Maximum number of signals to retain (default: 500).
+     * When exceeded, oldest signals are removed first (keeping newest).
+     * Active WU signals are always retained regardless of this limit.
+     */
+    maxEntries: z.number().int().positive().default(500),
+});
 /**
  * Memory layer configuration
  */
@@ -195,6 +309,23 @@ export const MemoryConfigSchema = z.object({
         .default(30 * 24 * 60 * 60 * 1000),
     /** Enable auto-cleanup (default: true) */
     enableAutoCleanup: z.boolean().default(true),
+    /**
+     * WU-1203: Progress signals configuration for sub-agent coordination.
+     * Optional - when not provided, spawn prompts show "Progress Signals (Optional)".
+     */
+    progress_signals: ProgressSignalsConfigSchema.optional(),
+    /**
+     * WU-1204: Signal cleanup configuration
+     * Controls TTL-based cleanup for signals.jsonl to prevent unbounded growth.
+     */
+    signalCleanup: SignalCleanupConfigSchema.default(() => SignalCleanupConfigSchema.parse({})),
+    /**
+     * WU-1289: Maximum size in bytes for spawn memory context.
+     * Controls the maximum size of memory context injected into wu:spawn prompts.
+     * Larger values include more context but increase token usage.
+     * @default 4096 (4KB)
+     */
+    spawn_context_max_size: z.number().int().positive().default(4096),
 });
 /**
  * UI configuration
@@ -325,6 +456,33 @@ export const ExperimentalConfigSchema = z.object({
      */
     recovery_command: z.boolean().default(true),
 });
+/**
+ * WU-1270: Methodology telemetry configuration
+ *
+ * Opt-in telemetry to track which methodology modes are being used.
+ * Privacy-preserving: No PII or project-identifying information collected.
+ */
+export const MethodologyTelemetryConfigSchema = z.object({
+    /**
+     * Enable methodology telemetry (opt-in).
+     * When true, tracks methodology.testing and methodology.architecture values
+     * on wu:spawn events. Data is privacy-preserving (no PII/project info).
+     * @default false
+     */
+    enabled: z.boolean().default(false),
+});
+/**
+ * WU-1270: Telemetry configuration
+ *
+ * Configuration for opt-in telemetry features.
+ */
+export const TelemetryConfigSchema = z.object({
+    /**
+     * Methodology telemetry configuration (opt-in).
+     * Tracks methodology selection patterns for adoption insights.
+     */
+    methodology: MethodologyTelemetryConfigSchema.default(() => MethodologyTelemetryConfigSchema.parse({})),
+});
 /**
  * Complete LumenFlow configuration schema
  */
@@ -351,6 +509,27 @@ export const LumenFlowConfigSchema = z.object({
     agents: AgentsConfigSchema.default(() => AgentsConfigSchema.parse({})),
     /** Experimental features (WU-1090) */
     experimental: ExperimentalConfigSchema.default(() => ExperimentalConfigSchema.parse({})),
+    /**
+     * WU-1270: Telemetry configuration
+     * Opt-in telemetry features for adoption tracking.
+     */
+    telemetry: TelemetryConfigSchema.default(() => TelemetryConfigSchema.parse({})),
+    /**
+     * WU-1259: Methodology configuration
+     * Single source of truth for testing/architecture methodology decisions.
+     * Used by both wu:spawn (prompt assembly) and gates (enforcement).
+     *
+     * @example
+     * ```yaml
+     * methodology:
+     *   testing: 'tdd'              # tdd | test-after | none
+     *   architecture: 'hexagonal'   # hexagonal | layered | none
+     *   overrides:
+     *     coverage_threshold: 85    # Override TDD's default 90%
+     *     coverage_mode: 'warn'     # Override TDD's default 'block'
+     * ```
+     */
+    methodology: MethodologyConfigSchema.optional(),
 });
 /**
  * Validate configuration data
@@ -358,6 +537,7 @@ export const LumenFlowConfigSchema = z.object({
  * @param data - Configuration data to validate
  * @returns Validation result with parsed config or errors
  */
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type -- Zod v4 return type inference
 export function validateConfig(data) {
     return LumenFlowConfigSchema.safeParse(data);
 }

package/dist/manual-test-validator.d.ts

@@ -11,7 +11,7 @@
  * - type: documentation only
  * - code_paths containing only documentation/config files (no code files)
  *
- * @see {@link tools/lib/wu-done-validators.mjs} - Integration point
+ * @see {@link packages/@lumenflow/cli/src/lib/wu-done-validators.ts} - Integration point
  * @see {@link docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md} - TDD requirements
  */
 /**
@@ -41,7 +41,7 @@ export declare const EXEMPT_TYPES: readonly string[];
 /**
  * Determine if a file path represents a code file requiring automated tests.
  *
- * Code files are those with extensions like .mjs, .ts, .tsx, .js
+ * Code files are those with extensions like .ts, .ts, .tsx, .js
  * EXCEPT config files (vitest.config.ts, .eslintrc.js, etc.)
  *
  * @param {string} filePath - File path to check

package/dist/manual-test-validator.js

@@ -11,7 +11,7 @@
  * - type: documentation only
  * - code_paths containing only documentation/config files (no code files)
  *
- * @see {@link tools/lib/wu-done-validators.mjs} - Integration point
+ * @see {@link packages/@lumenflow/cli/src/lib/wu-done-validators.ts} - Integration point
  * @see {@link docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md} - TDD requirements
  */
 import path from 'node:path';
@@ -20,7 +20,7 @@ import { TEST_TYPES, WU_TYPES } from './wu-constants.js';
  * Code file extensions that require automated tests.
  * @constant {string[]}
  */
-const CODE_EXTENSIONS = Object.freeze(['.js', '.ts', '.tsx', '.mjs']);
+const CODE_EXTENSIONS = Object.freeze(['.js', '.ts', '.tsx', '.ts']);
 /**
  * Non-code file extensions (documentation, data, config).
  * @constant {string[]}
@@ -67,7 +67,7 @@ export const EXEMPT_TYPES = Object.freeze([WU_TYPES.DOCUMENTATION]);
 /**
  * Determine if a file path represents a code file requiring automated tests.
  *
- * Code files are those with extensions like .mjs, .ts, .tsx, .js
+ * Code files are those with extensions like .ts, .ts, .tsx, .js
  * EXCEPT config files (vitest.config.ts, .eslintrc.js, etc.)
  *
  * @param {string} filePath - File path to check

package/dist/merge-lock.d.ts

@@ -1,5 +1,6 @@
 /**
  * WU-1747: Merge Lock Module
+ * WU-1174: Lock files moved to temp directory to avoid polluting main checkout
  *
  * Provides atomic locking mechanism for wu:done merge operations
  * to prevent race conditions during concurrent completions.
@@ -9,6 +10,7 @@
  * - Stale lock detection and auto-cleanup
  * - Idempotent re-acquisition for same WU
  * - Guaranteed cleanup via withMergeLock wrapper
+ * - Lock files stored in temp directory (not main checkout)
  *
  * @module merge-lock
  */
@@ -41,7 +43,12 @@ export declare const MERGE_LOCK_STALE_MS = 60000;
  * Options for lock file operations
  */
 interface MergeLockBaseDirOptions {
-    /** Base directory (defaults to cwd) */
+    /**
+     * Base directory override (for testing only)
+     *
+     * WU-1174: In production, locks are always stored in LUMENFLOW_PATHS.LOCK_DIR
+     * (a temp directory). This option allows tests to use isolated directories.
+     */
     baseDir?: string;
 }
 /**

package/dist/merge-lock.js

@@ -1,5 +1,6 @@
 /**
  * WU-1747: Merge Lock Module
+ * WU-1174: Lock files moved to temp directory to avoid polluting main checkout
  *
  * Provides atomic locking mechanism for wu:done merge operations
  * to prevent race conditions during concurrent completions.
@@ -9,13 +10,14 @@
  * - Stale lock detection and auto-cleanup
  * - Idempotent re-acquisition for same WU
  * - Guaranteed cleanup via withMergeLock wrapper
+ * - Lock files stored in temp directory (not main checkout)
  *
  * @module merge-lock
  */
 import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync } from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
-import { LOG_PREFIX, EMOJI, LUMENFLOW_PATHS } from './wu-constants.js';
+import { LOG_PREFIX, EMOJI, LUMENFLOW_PATHS, LOCK_DIR_NAME } from './wu-constants.js';
 import { createError, ErrorCodes } from './error-handler.js';
 /**
  * Default timeout for waiting to acquire lock (ms)
@@ -36,12 +38,19 @@ const LOCK_POLL_INTERVAL_MS = 500;
 /**
  * Get the path to the merge lock file
  *
+ * WU-1174: Lock files are stored in a temp directory to avoid polluting
+ * the main checkout. The baseDir option is only for testing isolation.
+ *
  * @param {MergeLockBaseDirOptions} [options]
  * @returns {string} Path to lock file
  */
 function getLockPath(options = {}) {
-    const baseDir = options.baseDir || process.cwd();
-    return path.join(baseDir, LUMENFLOW_PATHS.BASE, LOCK_FILE_NAME);
+    // WU-1174: Use temp directory for locks (not main checkout's .lumenflow/)
+    // baseDir is only used for test isolation
+    const lockDir = options.baseDir
+        ? path.join(options.baseDir, LOCK_DIR_NAME)
+        : LUMENFLOW_PATHS.LOCK_DIR;
+    return path.join(lockDir, LOCK_FILE_NAME);
 }
 /**
  * Read lock file contents
@@ -71,10 +80,10 @@ function readLockFile(options = {}) {
  */
 function writeLockFile(lockInfo, options = {}) {
     const lockPath = getLockPath(options);
-    const lumenflowDir = path.dirname(lockPath);
-    // Ensure .lumenflow directory exists
-    if (!existsSync(lumenflowDir)) {
-        mkdirSync(lumenflowDir, { recursive: true });
+    const lockDir = path.dirname(lockPath);
+    // WU-1174: Ensure lock directory exists (temp directory, not .lumenflow/)
+    if (!existsSync(lockDir)) {
+        mkdirSync(lockDir, { recursive: true });
     }
     writeFileSync(lockPath, JSON.stringify(lockInfo, null, 2));
 }

package/dist/micro-worktree.d.ts

@@ -1,7 +1,7 @@
 /**
  * Micro-Worktree Operations
  *
- * Race-safe micro-worktree isolation pattern extracted from wu-create.mjs (WU-1262).
+ * Race-safe micro-worktree isolation pattern extracted from wu-create.ts (WU-1262).
  * Provides shared infrastructure for commands that need to modify main branch
  * atomically without switching checkout.
  *
@@ -23,11 +23,51 @@
  * - Cleanup guaranteed even on failure
  *
  * Consumers:
- * @see {@link tools/wu-create.mjs} - WU creation (WU-1262, WU-1439)
- * @see {@link tools/wu-edit.mjs} - Spec edits (WU-1274)
- * @see {@link tools/initiative-create.mjs} - Initiative creation (WU-1439)
+ * @see {@link packages/@lumenflow/cli/src/wu-create.ts} - WU creation (WU-1262, WU-1439)
+ * @see {@link packages/@lumenflow/cli/src/wu-edit.ts} - Spec edits (WU-1274)
+ * @see {@link packages/@lumenflow/cli/src/initiative-create.ts} - Initiative creation (WU-1439)
  */
 import type { GitAdapter } from './git-adapter.js';
+/**
+ * Context passed to the execute function in withMicroWorktree
+ */
+interface MicroWorktreeContext {
+    /** Path to the micro-worktree directory */
+    worktreePath: string;
+    /** GitAdapter instance for the micro-worktree */
+    gitWorktree: GitAdapter;
+}
+/**
+ * Result returned by the execute function in withMicroWorktree
+ */
+interface MicroWorktreeExecuteResult {
+    /** Commit message for the changes */
+    commitMessage: string;
+    /** List of files that were modified */
+    files: string[];
+}
+/**
+ * Options for withMicroWorktree
+ */
+interface WithMicroWorktreeOptions {
+    /** Operation name (e.g., 'wu-create', 'wu-edit') */
+    operation: string;
+    /** WU ID (e.g., 'WU-123') */
+    id: string;
+    /** Log prefix for console output */
+    logPrefix?: string;
+    /** Skip local main merge, push directly to origin/main */
+    pushOnly?: boolean;
+    /** Async function to execute in micro-worktree */
+    execute: (context: MicroWorktreeContext) => Promise<MicroWorktreeExecuteResult>;
+}
+/**
+ * Result from withMicroWorktree
+ */
+interface WithMicroWorktreeResult extends MicroWorktreeExecuteResult {
+    /** Git ref to use for worktree creation */
+    ref: string;
+}
 /**
  * Maximum retry attempts for ff-only merge when main moves
  *
@@ -35,6 +75,14 @@ import type { GitAdapter } from './git-adapter.js';
  * concurrently. Each retry fetches latest main and rebases.
  */
 export declare const MAX_MERGE_RETRIES = 3;
+/**
+ * Maximum retry attempts for push when origin/main advances
+ *
+ * WU-1179: When push fails due to race condition (origin advanced while we
+ * were working), rollback local main to origin/main and retry.
+ * Each retry: fetch -> rebase temp branch -> re-merge -> push.
+ */
+export declare const MAX_PUSH_RETRIES = 3;
 /**
  * Environment variable name for LUMENFLOW_FORCE bypass
  *
@@ -60,14 +108,14 @@ export declare const DEFAULT_LOG_PREFIX = "[micro-wt]";
  * @param {string} id - WU ID (e.g., 'wu-123')
  * @returns {string} Temp branch name (e.g., 'tmp/wu-create/wu-123')
  */
-export declare function getTempBranchName(operation: any, id: any): string;
+export declare function getTempBranchName(operation: string, id: string): string;
 /**
  * Create micro-worktree in /tmp directory
  *
  * @param {string} prefix - Directory prefix (e.g., 'wu-create-', 'wu-edit-')
  * @returns {string} Path to created micro-worktree directory
  */
-export declare function createMicroWorktreeDir(prefix: any): string;
+export declare function createMicroWorktreeDir(prefix: string): string;
 /**
  * Parse git worktree list output to find worktrees by branch
  *
@@ -77,7 +125,7 @@ export declare function createMicroWorktreeDir(prefix: any): string;
  * @param {string} branchName - Branch name to search for (e.g., 'tmp/wu-create/wu-123')
  * @returns {string|null} Worktree path if found, null otherwise
  */
-export declare function findWorktreeByBranch(worktreeListOutput: any, branchName: any): any;
+export declare function findWorktreeByBranch(worktreeListOutput: string, branchName: string): string | null;
 /**
  * Clean up orphaned micro-worktree and temp branch from a previous interrupted operation
  *
@@ -95,7 +143,7 @@ export declare function findWorktreeByBranch(worktreeListOutput: any, branchName
  * @param {string} logPrefix - Log prefix for console output
  * @returns {Promise<{cleanedWorktree: boolean, cleanedBranch: boolean}>} Cleanup status
  */
-export declare function cleanupOrphanedMicroWorktree(operation: any, id: any, gitAdapter: any, logPrefix?: string): Promise<{
+export declare function cleanupOrphanedMicroWorktree(operation: string, id: string, gitAdapter: GitAdapter, logPrefix?: string): Promise<{
     cleanedWorktree: boolean;
     cleanedBranch: boolean;
 }>;
@@ -112,7 +160,7 @@ export declare function cleanupOrphanedMicroWorktree(operation: any, id: any, gi
  * @param {string} branchName - Temp branch name
  * @param {string} logPrefix - Log prefix for console output
  */
-export declare function cleanupMicroWorktree(worktreePath: any, branchName: any, logPrefix?: string): Promise<void>;
+export declare function cleanupMicroWorktree(worktreePath: string, branchName: string, logPrefix?: string): Promise<void>;
 /**
  * Stage changes including deletions in micro-worktree
  *
@@ -124,7 +172,7 @@ export declare function cleanupMicroWorktree(worktreePath: any, branchName: any,
  * @param {string[]|undefined} files - Files to stage (undefined/empty = stage all)
  * @returns {Promise<void>}
  */
-export declare function stageChangesWithDeletions(gitWorktree: any, files: any): Promise<void>;
+export declare function stageChangesWithDeletions(gitWorktree: GitAdapter, files: string[] | undefined): Promise<void>;
 /**
  * Format files using prettier before committing
  *
@@ -135,7 +183,7 @@ export declare function stageChangesWithDeletions(gitWorktree: any, files: any):
  * @param {string} worktreePath - Path to the micro-worktree
  * @param {string} logPrefix - Log prefix for console output
  */
-export declare function formatFiles(files: any, worktreePath: any, logPrefix?: string): Promise<void>;
+export declare function formatFiles(files: string[] | undefined, worktreePath: string, logPrefix?: string): Promise<void>;
 /**
  * Merge temp branch to main with ff-only and retry logic
  *
@@ -147,7 +195,26 @@ export declare function formatFiles(files: any, worktreePath: any, logPrefix?: s
  * @param {string} logPrefix - Log prefix for console output
  * @throws {Error} If merge fails after all retries
  */
-export declare function mergeWithRetry(tempBranchName: any, microWorktreePath: any, logPrefix?: string): Promise<void>;
+export declare function mergeWithRetry(tempBranchName: string, microWorktreePath: string, logPrefix?: string): Promise<void>;
+/**
+ * Push to origin/main with retry logic for race conditions
+ *
+ * WU-1179: When push fails because origin/main advanced (race condition with
+ * parallel agents), this function rolls back local main to origin/main and
+ * retries the full sequence: fetch -> rebase temp branch -> re-merge -> push.
+ *
+ * This prevents the scenario where local main is left diverged from origin
+ * after a push failure.
+ *
+ * @param {Object} mainGit - GitAdapter instance for main checkout
+ * @param {Object} worktreeGit - GitAdapter instance for micro-worktree
+ * @param {string} remote - Remote name (e.g., 'origin')
+ * @param {string} branch - Branch name (e.g., 'main')
+ * @param {string} tempBranchName - Temp branch that was merged (for rebase)
+ * @param {string} logPrefix - Log prefix for console output
+ * @throws {Error} If push fails after all retries
+ */
+export declare function pushWithRetry(mainGit: GitAdapter, worktreeGit: GitAdapter, remote: string, branch: string, tempBranchName: string, logPrefix?: string): Promise<void>;
 /**
  * Push using refspec with LUMENFLOW_FORCE to bypass pre-push hooks
  *
@@ -188,4 +255,5 @@ export declare function pushRefspecWithForce(gitAdapter: GitAdapter, remote: str
  * @returns {Promise<Object>} Result with ref property for worktree creation
  * @throws {Error} If any step fails (cleanup still runs)
  */
-export declare function withMicroWorktree(options: any): Promise<any>;
+export declare function withMicroWorktree(options: WithMicroWorktreeOptions): Promise<WithMicroWorktreeResult>;
+export {};