@lumenflow/cli 2.1.1 → 2.2.0

package/dist/wu-done.d.ts

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+/**
+ * WU Done Helper
+ *
+ * Canonical sequence (Worktree mode - DEFAULT):
+ * 1) Run gates in lane worktree (validates the change, not just main)
+ * 2) Pre-flight validation: run ALL pre-commit hooks before merge (prevents partial completion)
+ * 3) cd into worktree
+ * 4) Auto-update WU YAML/backlog/status to Done in worktree (unless --no-auto)
+ * 5) Create `.lumenflow/stamps/WU-{id}.done` in worktree
+ * 6) Validate staged files against whitelist
+ * 7) Commit metadata changes in worktree (on lane branch)
+ * 8) cd back to main
+ * 9) Merge lane branch to main with --ff-only (metadata + code merged atomically)
+ * 10) Push to `main`
+ * 11) Remove the associated worktree (unless --no-remove)
+ * 12) Optionally delete the lane branch (with --delete-branch)
+ * 13) Emit telemetry to .lumenflow/flow.log
+ *
+ * Canonical sequence (Branch-Only mode - LEGACY):
+ * 1) Run gates on lane branch (in main checkout)
+ * 2) Pre-flight validation
+ * 3) Merge lane branch to main
+ * 4) Update metadata on main
+ * 5) Commit and push
+ * 6) Delete lane branch
+ *
+ * Usage:
+ *   pnpm wu:done --id WU-334 [--worktree worktrees/intelligence-wu-334] [--no-auto] [--no-remove] [--no-merge] [--delete-branch]
+ *
+ * WU-2542: This script imports utilities from @lumenflow/core package.
+ * Full migration to thin shim pending @lumenflow/core CLI export implementation.
+ */
+/**
+ * WU-1999: Print exposure validation warnings.
+ *
+ * Validates exposure field and UI pairing for user-facing WUs.
+ * Non-blocking - logs warnings but doesn't prevent completion.
+ *
+ * Checks:
+ * - exposure field is present (warn if missing)
+ * - If exposure=api, warns if no ui_pairing_wus specified
+ * - If exposure=api, checks acceptance criteria for UI verification mention
+ * - If exposure=ui, recommends user_journey field if not present
+ *
+ * @param {object} wu - WU YAML document
+ * @param {object} options - Validation options
+ * @param {boolean} [options.skipExposureCheck=false] - Skip all exposure validation
+ * @returns {void}
+ */
+interface ExposureOptions {
+    skipExposureCheck?: boolean;
+}
+export declare function printExposureWarnings(wu: Record<string, unknown>, options?: ExposureOptions): void;
+/**
+ * WU-2022: Validate feature accessibility for UI-exposed WUs.
+ *
+ * BLOCKING validation - prevents wu:done if exposure=ui but feature is not accessible.
+ * This prevents "orphaned code" where UI features exist but users cannot navigate to them.
+ *
+ * Accessibility is verified by ANY of:
+ * 1. navigation_path field is specified (explicit route)
+ * 2. code_paths includes a page.tsx file (Next.js page)
+ * 3. tests.manual includes navigation/accessibility verification
+ *
+ * @param {object} wu - WU YAML document
+ * @param {object} options - Validation options
+ * @param {boolean} [options.skipAccessibilityCheck=false] - Skip accessibility validation
+ * @returns {void} Calls die() if validation fails
+ */
+interface AccessibilityOptions {
+    skipAccessibilityCheck?: boolean;
+}
+export declare function validateAccessibilityOrDie(wu: Record<string, unknown>, options?: AccessibilityOptions): void;
+/**
+ * WU-1012: Validate --docs-only flag usage.
+ *
+ * The --docs-only flag can only be used when the WU is documentation-focused:
+ * 1. exposure field is 'documentation'
+ * 2. OR all code_paths are documentation paths (docs/, ai/, .claude/, *.md)
+ * 3. OR type is 'documentation'
+ *
+ * @param {object} wu - WU YAML document
+ * @param {object} args - Parsed CLI arguments
+ * @param {boolean} args.docsOnly - Whether --docs-only flag was passed
+ * @returns {{ valid: boolean, errors: string[] }} Validation result
+ */
+interface DocsOnlyArgs {
+    docsOnly?: boolean;
+}
+export declare function validateDocsOnlyFlag(wu: Record<string, unknown>, args: DocsOnlyArgs): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * WU-1012: Build gates command with --docs-only flag support.
+ *
+ * Returns the appropriate gates command based on:
+ * - Explicit --docs-only flag from CLI
+ * - Auto-detected isDocsOnly from code_paths analysis
+ *
+ * @param {object} options - Build options
+ * @param {boolean} options.docsOnly - Explicit --docs-only flag from CLI
+ * @param {boolean} options.isDocsOnly - Auto-detected docs-only from code_paths
+ * @returns {string} Gates command string
+ */
+interface BuildGatesOptions {
+    docsOnly?: boolean;
+    isDocsOnly?: boolean;
+}
+export declare function buildGatesCommand(options: BuildGatesOptions): string;
+/**
+ * WU-1946: Update spawn registry on WU completion.
+ * Non-blocking wrapper - failures logged as warnings.
+ *
+ * When a WU is completed via wu:done, this function updates the spawn registry
+ * to mark the spawned entry as completed (if one exists). This allows orchestrators
+ * to track sub-agent spawn completion status.
+ *
+ * Gracefully skips if:
+ * - No spawn entry found for this WU (legacy WU created before registry)
+ * - Registry file doesn't exist
+ * - Any error during update
+ *
+ * @param {string} id - WU ID being completed
+ * @param {string} baseDir - Base directory containing .lumenflow/state/
+ * @returns {Promise<void>}
+ */
+export declare function updateSpawnRegistryOnCompletion(id: any, baseDir?: string): Promise<void>;
+/**
+ * WU-1234: Normalize username for ownership comparison
+ * Extracts username from email address for comparison.
+ * This allows tom@hellm.ai to match 'tom' assigned_to field.
+ *
+ * @param {string|null|undefined} value - Email address or username
+ * @returns {string} Normalized username (lowercase)
+ */
+export declare function normalizeUsername(value: any): string;
+/**
+ * WU-1234: Detect if branch is already merged to main
+ * Checks if branch tip is an ancestor of main HEAD (i.e., already merged).
+ * This prevents merge loops when code was merged via emergency fix or manual merge.
+ *
+ * @param {string} branch - Lane branch name
+ * @returns {Promise<boolean>} True if branch is already merged to main
+ */
+export declare function isBranchAlreadyMerged(branch: any): Promise<boolean>;
+export { shouldSkipWebTests as isDocsOnlyByPaths } from '@lumenflow/core/dist/path-classifiers.js';
+/**
+ * WU-1234: Pre-flight check for backlog state consistency
+ * Fails fast if the WU appears in both Done and In Progress sections.
+ *
+ * @param {string} id - WU ID to check
+ * @param {string} backlogPath - Path to backlog.md
+ * @returns {{ valid: boolean, error: string|null }}
+ */
+export declare function checkBacklogConsistencyForWU(id: any, backlogPath: any): {
+    valid: boolean;
+    error: string;
+};
+/**
+ * WU-1084: Check for uncommitted changes on main after merge completes.
+ *
+ * This catches cases where pnpm format (or other tooling) touched files
+ * outside the WU's code_paths during worktree work. These changes survive
+ * the merge and would be silently left behind when the worktree is removed.
+ *
+ * @param gitStatus - Output from git status (porcelain format)
+ * @param wuId - The WU ID for error messaging
+ * @returns Object with isDirty flag and optional error message
+ */
+export declare function checkPostMergeDirtyState(gitStatus: string, wuId: string): {
+    isDirty: boolean;
+    error?: string;
+};
+export declare function emitTelemetry(event: any): void;
+/**
+ * Print State HUD for visibility
+ * Extracted from main() to reduce complexity (WU-1215 Phase 2 Extraction #4)
+ * @param {object} params - Parameters
+ * @param {string} params.id - WU ID
+ * @param {object} params.docMain - Main WU YAML document
+ * @param {boolean} params.isBranchOnly - Whether in branch-only mode
+ * @param {boolean} params.isDocsOnly - Whether this is a docs-only WU
+ * @param {string|null} params.derivedWorktree - Derived worktree path
+ * @param {string} params.STAMPS_DIR - Stamps directory path
+ */
+export declare function computeBranchOnlyFallback({ isBranchOnly, branchOnlyRequested, worktreeExists, derivedWorktree, }: {
+    isBranchOnly: boolean;
+    branchOnlyRequested: boolean | undefined;
+    worktreeExists: boolean;
+    derivedWorktree: string | null;
+}): {
+    allowFallback: boolean;
+    effectiveBranchOnly: boolean;
+};
+/**
+ * WU-1983: Print migration deployment nudge when WU includes supabase changes.
+ * Notifies agent to deploy new migrations to production via MCP tools.
+ * Conditional output - only prints when migrations are in scope and new migrations exist.
+ *
+ * @param {string[]} codePaths - WU code_paths array
+ * @param {string} baseDir - Base directory for migration discovery
+ * @returns {Promise<void>}
+ */
+export declare function printMigrationDeploymentNudge(codePaths: any, baseDir: any): Promise<void>;
+/**
+ * WU-1763: Print discovery summary nudge when discoveries exist for this WU.
+ * Conditional output - only prints when discoveryCount > 0.
+ * Non-blocking, single-line output to avoid flooding the console.
+ *
+ * @param {string} id - WU ID being completed
+ * @param {number} discoveryCount - Number of open discoveries for this WU
+ * @param {string[]} discoveryIds - List of discovery IDs (limited to 5 in output)
+ */
+export declare function printDiscoveryNudge(id: any, discoveryCount: any, discoveryIds: any): void;
+/**
+ * WU-1763: Print documentation validation nudge when docs changed.
+ * Conditional output - only prints when changedDocPaths.length > 0.
+ * Non-blocking, single-line output to avoid flooding the console.
+ *
+ * @param {string} id - WU ID being completed
+ * @param {string[]} changedDocPaths - List of documentation paths that changed
+ */
+export declare function printDocValidationNudge(id: any, changedDocPaths: any): void;

package/dist/wu-done.js

@@ -1975,9 +1975,15 @@ async function main() {
     // This prevents partial completion states where merge succeeds but commit fails
     // Validates all 8 gates: secrets, file size, ESLint, Prettier, TypeScript, audit, architecture, tasks
     // WU-2308: Pass worktreePath to run audit from worktree (checks fixed deps, not stale main deps)
-    const hookResult = validateAllPreCommitHooks(id, worktreePath);
-    if (!hookResult.valid) {
-        die('Pre-flight validation failed. Fix hook issues and try again.');
+    // WU-1145: Skip pre-flight when skipGates is true (pre-flight runs gates which was already skipped)
+    if (!args.skipGates) {
+        const hookResult = validateAllPreCommitHooks(id, worktreePath);
+        if (!hookResult.valid) {
+            die('Pre-flight validation failed. Fix hook issues and try again.');
+        }
+    }
+    else {
+        console.log(`${LOG_PREFIX.DONE} Skipping pre-flight hook validation (--skip-gates)`);
     }
     // Step 0.6: WU-1781 - Run tasks:validate preflight BEFORE any merge/push operations
     // This prevents deadlocks where validation fails after merge, leaving local main ahead of origin

package/dist/wu-edit.d.ts

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * WU Edit Helper
+ *
+ * Race-safe WU spec editing using micro-worktree isolation (WU-1274).
+ *
+ * Enables editing WU YAML files without claiming the WU, perfect for:
+ * - Filling in placeholder content after wu:create
+ * - Updating description/acceptance criteria
+ * - Adding code_paths, notes, or other spec fields
+ *
+ * Uses the same micro-worktree pattern as wu:create (WU-1262):
+ * 1) Validate inputs (WU exists, status is ready)
+ * 2) Ensure main is clean and up-to-date with origin
+ * 3) Create temp branch WITHOUT switching (main checkout stays on main)
+ * 4) Create micro-worktree in /tmp pointing to temp branch
+ * 5) Apply edits in micro-worktree
+ * 6) Commit, ff-only merge, push
+ * 7) Cleanup temp branch and micro-worktree
+ *
+ * Usage:
+ *   pnpm wu:edit --id WU-123 --spec-file /path/to/spec.yaml
+ *   pnpm wu:edit --id WU-123 --description "New description text"
+ *   pnpm wu:edit --id WU-123 --acceptance "Criterion 1" --acceptance "Criterion 2"
+ *
+ * Part of WU-1274: Add wu:edit command for spec-only changes
+ * @see {@link tools/lib/micro-worktree.mjs} - Shared micro-worktree logic
+ */
+/**
+ * WU-1039: Validate which edits are allowed on done WUs
+ *
+ * Done WUs only allow metadata reassignment: initiative, phase, and exposure.
+ * All other edits are blocked to preserve WU immutability after completion.
+ *
+ * @param opts - Parsed CLI options
+ * @returns { valid: boolean, disallowedEdits: string[] }
+ */
+export declare function validateDoneWUEdits(opts: Record<string, unknown>): {
+    valid: boolean;
+    disallowedEdits: string[];
+};
+/**
+ * WU-1039: Validate exposure value against schema
+ *
+ * Uses WU_EXPOSURE_VALUES from core constants (Library-First, no magic strings).
+ *
+ * @param exposure - Exposure value to validate
+ * @returns { valid: boolean, error?: string }
+ */
+export declare function validateExposureValue(exposure: string): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * WU-1039: Apply exposure edit to WU object
+ *
+ * Returns a new WU object with updated exposure (immutable pattern).
+ *
+ * @param wu - Original WU object
+ * @param exposure - New exposure value
+ * @returns Updated WU object (does not mutate original)
+ */
+export declare function applyExposureEdit(wu: Record<string, unknown>, exposure: string): Record<string, unknown>;

package/dist/wu-edit.js

@@ -84,6 +84,9 @@ export function validateDoneWUEdits(opts) {
     if (opts.codePaths && Array.isArray(opts.codePaths) && opts.codePaths.length > 0) {
         disallowedEdits.push('--code-paths');
     }
+    if (opts.risks && Array.isArray(opts.risks) && opts.risks.length > 0) {
+        disallowedEdits.push('--risks');
+    }
     if (opts.lane)
         disallowedEdits.push('--lane');
     if (opts.type)
@@ -157,13 +160,24 @@ const EDIT_OPTIONS = {
     acceptance: {
         name: 'acceptance',
         flags: '--acceptance <criterion>',
-        description: 'Acceptance criterion (repeatable, replaces existing; use --append to add)',
+        description: 'Acceptance criterion (repeatable, appends to existing; use --replace-acceptance to overwrite)',
         isRepeatable: true,
     },
     notes: {
         name: 'notes',
         flags: '--notes <text>',
-        description: 'New notes text (replaces existing)',
+        description: 'Notes text (appends to existing; use --replace-notes to overwrite)',
+    },
+    // WU-1144: Add explicit replace flags for notes and acceptance
+    replaceNotes: {
+        name: 'replaceNotes',
+        flags: '--replace-notes',
+        description: 'Replace existing notes instead of appending',
+    },
+    replaceAcceptance: {
+        name: 'replaceAcceptance',
+        flags: '--replace-acceptance',
+        description: 'Replace existing acceptance criteria instead of appending',
     },
     codePaths: {
         name: 'codePaths',
@@ -171,10 +185,16 @@ const EDIT_OPTIONS = {
         description: 'Code path (repeatable, replaces existing; use --append to add)',
         isRepeatable: true,
     },
+    risks: {
+        name: 'risks',
+        flags: '--risks <risk>',
+        description: 'Risk entry (repeatable, replaces existing; use --append to add)',
+        isRepeatable: true,
+    },
     append: {
         name: 'append',
         flags: '--append',
-        description: 'Append to existing array values instead of replacing (for --acceptance, --code-paths)',
+        description: 'Append to existing array values instead of replacing (for --code-paths, --test-paths-*, --blocked-by, --add-dep)',
     },
     // WU-1456: Add lane reassignment support
     lane: {
@@ -310,7 +330,11 @@ function parseArgs() {
             EDIT_OPTIONS.description,
             EDIT_OPTIONS.acceptance,
             EDIT_OPTIONS.notes,
+            // WU-1144: Add explicit replace flags for notes and acceptance
+            EDIT_OPTIONS.replaceNotes,
+            EDIT_OPTIONS.replaceAcceptance,
             EDIT_OPTIONS.codePaths,
+            EDIT_OPTIONS.risks,
             EDIT_OPTIONS.append,
             // WU-1390: Add test path flags
             WU_OPTIONS.testPathsManual,
@@ -581,6 +605,25 @@ function mergeArrayField(existing, newValues, shouldAppend) {
     const existingArray = Array.isArray(existing) ? existing : [];
     return [...existingArray, ...newValues];
 }
+/**
+ * WU-1144: Merge string field values with append-by-default behavior
+ *
+ * Notes and acceptance criteria should append by default (preserving original),
+ * with explicit --replace-notes and --replace-acceptance flags for overwrite.
+ *
+ * @param {string | undefined} existing - Current string value from WU
+ * @param {string} newValue - New value from CLI
+ * @param {boolean} shouldReplace - Whether to replace instead of append
+ * @returns {string} Merged string value
+ */
+export function mergeStringField(existing, newValue, shouldReplace) {
+    // If replace mode or no existing value, just use new value
+    if (shouldReplace || !existing || existing.trim() === '') {
+        return newValue;
+    }
+    // Append with double newline separator
+    return `${existing}\n\n${newValue}`;
+}
 /**
  * Load spec file and merge with original WU (preserving id and status)
  * @param {string} specPath - Path to spec file
@@ -610,7 +653,7 @@ function loadSpecFile(specPath, originalWU) {
  * Returns the updated WU object
  */
 // eslint-disable-next-line sonarjs/cognitive-complexity -- Pre-existing complexity, refactor tracked separately
-function applyEdits(wu, opts) {
+export function applyEdits(wu, opts) {
     // Full spec replacement from file
     if (opts.specFile) {
         return loadSpecFile(opts.specFile, wu);
@@ -620,12 +663,17 @@ function applyEdits(wu, opts) {
     if (opts.description) {
         updated.description = opts.description;
     }
-    // Handle repeatable --acceptance flags (WU-1388: replace by default, append with --append)
+    // WU-1144: Handle --acceptance with append-by-default behavior
+    // Appends to existing acceptance criteria unless --replace-acceptance is set
     if (opts.acceptance && opts.acceptance.length > 0) {
-        updated.acceptance = mergeArrayField(wu.acceptance, opts.acceptance, opts.append);
+        // Invert the logic: append by default, replace with --replace-acceptance
+        const shouldAppend = !opts.replaceAcceptance;
+        updated.acceptance = mergeArrayField(wu.acceptance, opts.acceptance, shouldAppend);
     }
+    // WU-1144: Handle --notes with append-by-default behavior
+    // Appends to existing notes unless --replace-notes is set
     if (opts.notes) {
-        updated.notes = opts.notes;
+        updated.notes = mergeStringField(wu.notes, opts.notes, opts.replaceNotes ?? false);
     }
     // WU-1456: Handle lane reassignment
     if (opts.lane) {
@@ -670,6 +718,21 @@ function applyEdits(wu, opts) {
                 .filter(Boolean);
         updated.code_paths = mergeArrayField(wu.code_paths, codePaths, opts.append);
     }
+    // WU-1073: Handle repeatable --risks flags (replace by default, append with --append)
+    // Split comma-separated values within each entry for consistency with other list fields
+    if (opts.risks && opts.risks.length > 0) {
+        const rawRisks = opts.risks;
+        const risks = Array.isArray(rawRisks)
+            ? rawRisks
+                .flatMap((risk) => risk.split(','))
+                .map((risk) => risk.trim())
+                .filter(Boolean)
+            : rawRisks
+                .split(',')
+                .map((risk) => risk.trim())
+                .filter(Boolean);
+        updated.risks = mergeArrayField(wu.risks, risks, opts.append);
+    }
     // WU-1390: Handle test path flags (DRY refactor)
     const testPathMappings = [
         { optKey: 'testPathsManual', field: 'manual' },
@@ -757,6 +820,7 @@ async function main() {
         (opts.acceptance && opts.acceptance.length > 0) ||
         opts.notes ||
         (opts.codePaths && opts.codePaths.length > 0) ||
+        (opts.risks && opts.risks.length > 0) ||
         // WU-1390: Add test path flags to hasEdits check
         (opts.testPathsManual && opts.testPathsManual.length > 0) ||
         (opts.testPathsUnit && opts.testPathsUnit.length > 0) ||
@@ -779,9 +843,12 @@ async function main() {
             'Provide one of:\n' +
             '  --spec-file <path>        Replace full spec from YAML file\n' +
             '  --description <text>      Update description field\n' +
-            '  --acceptance <text>       Replace acceptance criteria (repeatable; use --append to add)\n' +
-            '  --notes <text>            Update notes field\n' +
+            '  --acceptance <text>       Append acceptance criteria (repeatable; use --replace-acceptance to overwrite)\n' +
+            '  --notes <text>            Append to notes (use --replace-notes to overwrite)\n' +
+            '  --replace-notes           Replace existing notes instead of appending\n' +
+            '  --replace-acceptance      Replace existing acceptance instead of appending\n' +
             '  --code-paths <paths>      Replace code paths (repeatable; use --append to add)\n' +
+            '  --risks <risk>            Replace risks (repeatable; use --append to add)\n' +
             '  --lane <lane>             Update lane assignment (e.g., "Operations: Tooling")\n' +
             '  --type <type>             Update WU type (feature, bug, refactor, documentation)\n' +
             '  --priority <priority>     Update priority (P0, P1, P2, P3)\n' +

package/dist/wu-infer-lane.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * WU Lane Inference CLI (WU-908)
+ *
+ * Suggests sub-lane for a WU based on code paths and description.
+ * Wrapper around lib/lane-inference.mjs for standalone CLI usage.
+ *
+ * Usage:
+ *   # Infer from existing WU
+ *   node tools/wu-infer-lane.mjs --id WU-123
+ *
+ *   # Infer from manual inputs
+ *   node tools/wu-infer-lane.mjs --paths "tools/**" "docs/**" --desc "Tooling improvements"
+ *
+ * Returns suggested lane and confidence score (0-100).
+ */
+export {};

package/dist/wu-preflight.d.ts

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * WU Preflight Validation
+ *
+ * WU-1803: Fast validation of code_paths and test paths before gates run.
+ * Completes in under 5 seconds vs 2+ minutes for full gates.
+ *
+ * This catches YAML mismatches early, preventing wasted time running full
+ * gates only to fail on code_paths validation at the end of wu:done.
+ *
+ * Usage:
+ *   pnpm wu:preflight --id WU-1803          # Validate from main checkout
+ *   pnpm wu:preflight --id WU-1803 --worktree worktrees/operations-gates-wu-1803
+ *
+ * Validates:
+ *   - code_paths files exist
+ *   - test file paths exist (unit, e2e, integration)
+ *   - WU YAML schema is valid
+ */
+/**
+ * Parse command-line arguments
+ * @param {string[]} argv - Process arguments
+ * @returns {object} Parsed arguments
+ */
+declare function parseArgs(argv: any): {
+    help: boolean;
+    error?: undefined;
+    id?: undefined;
+    worktree?: undefined;
+} | {
+    error: string;
+    help?: undefined;
+    id?: undefined;
+    worktree?: undefined;
+} | {
+    id: any;
+    worktree: any;
+    help: boolean;
+    error?: undefined;
+};
+/**
+ * Detect worktree path from WU YAML or calculate from lane
+ * @param {string} id - WU ID
+ * @returns {string|null} Worktree path or null if not found
+ */
+declare function detectWorktreePath(id: any): string;
+export { parseArgs, detectWorktreePath };

package/dist/wu-prune.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * WU Prune Utility
+ *
+ * Maintains worktree hygiene by:
+ * - Running git worktree prune to clean stale metadata
+ * - Validating worktree ↔ WU ↔ lane mappings
+ * - Warning on orphaned worktrees (no matching WU YAML)
+ * - Warning on stale worktrees (WU status is done/blocked)
+ * - Warning on invalid branch naming conventions
+ *
+ * Usage:
+ *   pnpm wu:prune          # Dry-run mode (shows what would be done)
+ *   pnpm wu:prune --execute # Actually run cleanup
+ */
+export {};

package/dist/wu-recover.d.ts

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+/**
+ * WU Recovery Command
+ *
+ * WU-1090: Context-aware state machine for WU lifecycle commands
+ *
+ * Analyzes WU state inconsistencies and offers recovery actions:
+ * - resume: Reconcile state and continue working (preserves work)
+ * - reset: Discard worktree and reset WU to ready
+ * - nuke: Remove all artifacts completely (requires --force)
+ * - cleanup: Remove leftover worktree for done WUs
+ *
+ * Usage:
+ *   pnpm wu:recover --id WU-123             # Analyze issues
+ *   pnpm wu:recover --id WU-123 --action resume  # Apply fix
+ *   pnpm wu:recover --id WU-123 --action nuke --force  # Destructive
+ */
+import { type RecoveryAnalysis } from '@lumenflow/core/dist/recovery/recovery-analyzer.js';
+/**
+ * Check if action requires --force flag
+ */
+export declare function requiresForceFlag(action: string): boolean;
+/**
+ * Validate recovery action
+ */
+export declare function validateRecoveryAction(action: string): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Format recovery analysis output
+ */
+export declare function formatRecoveryOutput(analysis: RecoveryAnalysis): string;
+/**
+ * Get exit code for recovery command
+ */
+export declare function getRecoveryExitCode(analysis: RecoveryAnalysis, actionFailed: boolean): number;

package/dist/wu-release.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * WU Release Command (WU-1080)
+ *
+ * Releases an orphaned WU from in_progress back to ready state.
+ * Use when an agent is interrupted mid-WU and the WU needs to be reclaimed.
+ *
+ * Sequence (micro-worktree pattern):
+ * 1) Validate WU is in_progress
+ * 2) Create micro-worktree from main
+ * 3) Append release event to state store
+ * 4) Regenerate backlog.md and status.md
+ * 5) Commit in micro-worktree, push directly to origin/main
+ * 6) Optionally remove the work worktree
+ *
+ * Usage:
+ *   pnpm wu:release --id WU-1080 --reason "Agent interrupted"
+ */
+export {};

package/dist/wu-repair.d.ts

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * WU State Repair Tool (Unified - WU-1826, WU-2240)
+ *
+ * Layer 2 defense-in-depth: detect and repair WU state inconsistencies.
+ *
+ * This unified tool consolidates four repair modes:
+ * - Consistency mode (default): detect/repair state inconsistencies
+ * - Claim mode (--claim): repair missing claim metadata in worktrees
+ * - Admin mode (--admin): administrative fixes for done WUs
+ * - State mode (--repair-state): repair corrupted wu-events.jsonl (WU-2240)
+ *
+ * Usage:
+ *   # Consistency mode (default)
+ *   pnpm wu:repair --id WU-123           # Repair single WU
+ *   pnpm wu:repair --id WU-123 --check   # Audit only, no changes
+ *   pnpm wu:repair --all                 # Batch repair all WUs
+ *   pnpm wu:repair --all --check         # Audit all WUs
+ *
+ *   # Claim mode
+ *   pnpm wu:repair --claim --id WU-123           # Repair claim metadata
+ *   pnpm wu:repair --claim --id WU-123 --check   # Check only
+ *   pnpm wu:repair --claim --id WU-123 --worktree /path/to/worktree
+ *
+ *   # Admin mode
+ *   pnpm wu:repair --admin --id WU-123 --lane "Operations: Tooling"
+ *   pnpm wu:repair --admin --id WU-123 --status cancelled
+ *   pnpm wu:repair --admin --id WU-123 --notes "Administrative fix"
+ *   pnpm wu:repair --admin --id WU-123 --initiative INIT-001
+ *
+ *   # State mode (WU-2240)
+ *   pnpm wu:repair --repair-state                    # Repair default state file
+ *   pnpm wu:repair --repair-state --path /path/to/wu-events.jsonl  # Repair specific file
+ *
+ * Exit codes:
+ *   0: Success (no issues or all repaired)
+ *   1: Issues detected (--check mode)
+ *   2: Repair failed
+ *
+ * DEPRECATION NOTICE:
+ *   - pnpm wu:repair-claim is deprecated. Use: pnpm wu:repair --claim
+ *   - pnpm wu:admin-repair is deprecated. Use: pnpm wu:repair --admin
+ *
+ * @see {@link tools/lib/wu-repair-core.mjs} - Core repair logic
+ * @see {@link tools/lib/wu-consistency-checker.mjs} - Consistency detection/repair
+ * @see {@link tools/lib/wu-state-store.mjs} - State file repair (repairStateFile)
+ */
+/**
+ * Normalise WU ID to uppercase with WU- prefix
+ * @param {string} id - Raw WU ID
+ * @returns {string} Normalised WU ID
+ */
+declare function normaliseWUId(id: any): any;
+/**
+ * Validate WU ID format
+ * @param {string} id - WU ID to validate
+ * @returns {boolean} True if valid
+ */
+declare function isValidWUId(id: any): boolean;
+export { normaliseWUId, isValidWUId };