@lumenflow/cli 1.3.6 → 1.5.0

package/README.md

@@ -1,6 +1,11 @@
 # @lumenflow/cli
 
-Command-line interface for LumenFlow workflow management.
+[![npm version](https://img.shields.io/npm/v/@lumenflow/cli.svg)](https://www.npmjs.com/package/@lumenflow/cli)
+[![npm downloads](https://img.shields.io/npm/dm/@lumenflow/cli.svg)](https://www.npmjs.com/package/@lumenflow/cli)
+[![license](https://img.shields.io/npm/l/@lumenflow/cli.svg)](https://github.com/hellmai/os/blob/main/LICENSE)
+[![node](https://img.shields.io/node/v/@lumenflow/cli.svg)](https://nodejs.org)
+
+> Command-line interface for LumenFlow workflow framework
 
 ## Installation
 
@@ -63,6 +68,13 @@ This package provides CLI commands for the LumenFlow workflow framework, includi
 | `initiative-status` | Show initiative status and progress |
 | `initiative-add-wu` | Link a WU to an initiative          |
 
+### Setup Commands
+
+| Command     | Description                                         |
+| ----------- | --------------------------------------------------- |
+| `init`      | Scaffold LumenFlow into a project                   |
+| `docs-sync` | Sync agent onboarding docs (for upgrading projects) |
+
 ### Other Commands
 
 | Command      | Description                                        |
@@ -98,6 +110,23 @@ npx wu-claim --id WU-123 --lane operations
 npx gates
 ```
 
+## Global Flags
+
+All commands support these flags:
+
+| Flag              | Description               |
+| ----------------- | ------------------------- |
+| `--help`, `-h`    | Show help for the command |
+| `--version`, `-V` | Show version number       |
+| `--no-color`      | Disable colored output    |
+
+## Environment Variables
+
+| Variable      | Description                                                                            |
+| ------------- | -------------------------------------------------------------------------------------- |
+| `NO_COLOR`    | Disable colored output when set (any value, per [no-color.org](https://no-color.org/)) |
+| `FORCE_COLOR` | Override color level: `0` (disabled), `1` (basic), `2` (256 colors), `3` (16m colors)  |
+
 ## Integration
 
 The CLI integrates with other LumenFlow packages:
@@ -109,7 +138,7 @@ The CLI integrates with other LumenFlow packages:
 
 ## Documentation
 
-For complete documentation, see the [LumenFlow documentation](https://github.com/hellmai/os).
+For complete documentation, see [lumenflow.dev](https://lumenflow.dev/reference/cli).
 
 ## License
 

package/dist/cli-entry-point.js

@@ -10,6 +10,8 @@
  * path but import.meta.url resolves to the real path - they never match
  * so main() is never called.
  *
+ * WU-1085: Initializes color support respecting NO_COLOR/FORCE_COLOR/--no-color
+ *
  * @example
  * ```typescript
  * // At the bottom of each CLI file:
@@ -21,13 +23,17 @@
  * ```
  */
 import { EXIT_CODES } from '@lumenflow/core/dist/wu-constants.js';
+import { initColorSupport } from '@lumenflow/core';
 /**
  * Wraps an async main function with proper error handling.
+ * WU-1085: Also initializes color support based on NO_COLOR/FORCE_COLOR/--no-color
  *
  * @param main - The async main function to execute
  * @returns Promise that resolves when main completes (or after error handling)
  */
 export async function runCLI(main) {
+    // WU-1085: Initialize color support before running command
+    initColorSupport();
     try {
         await main();
     }

package/dist/docs-sync.js

@@ -0,0 +1,467 @@
+/**
+ * @file docs-sync.ts
+ * LumenFlow docs:sync command for syncing agent docs to existing projects (WU-1083)
+ * WU-1085: Added createWUParser for proper --help support
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { createWUParser, WU_OPTIONS } from '@lumenflow/core';
+/**
+ * WU-1085: CLI option definitions for docs-sync command
+ */
+const DOCS_SYNC_OPTIONS = {
+    vendor: {
+        name: 'vendor',
+        flags: '--vendor <type>',
+        description: 'Vendor type (claude, cursor, aider, all, none)',
+        default: 'claude',
+    },
+    force: WU_OPTIONS.force,
+};
+/**
+ * WU-1085: Parse docs-sync command options using createWUParser
+ * Provides proper --help, --version, and option parsing
+ */
+export function parseDocsSyncOptions() {
+    const opts = createWUParser({
+        name: 'lumenflow-docs-sync',
+        description: 'Sync agent onboarding docs to existing projects (skips existing files by default)',
+        options: Object.values(DOCS_SYNC_OPTIONS),
+    });
+    return {
+        force: opts.force ?? false,
+        vendor: opts.vendor ?? 'claude',
+    };
+}
+/**
+ * Get current date in YYYY-MM-DD format
+ */
+function getCurrentDate() {
+    return new Date().toISOString().split('T')[0];
+}
+/**
+ * Process template content by replacing placeholders
+ */
+function processTemplate(content, tokens) {
+    let output = content;
+    for (const [key, value] of Object.entries(tokens)) {
+        output = output.replace(new RegExp(`\\{\\{${key}\\}\\}`, 'g'), value);
+    }
+    return output;
+}
+function getRelativePath(targetDir, filePath) {
+    return path.relative(targetDir, filePath).split(path.sep).join('/');
+}
+/**
+ * Create a directory if missing
+ */
+async function createDirectory(dirPath, result, targetDir) {
+    if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true });
+        result.created.push(getRelativePath(targetDir, dirPath));
+    }
+}
+/**
+ * Create a file, respecting force option
+ */
+async function createFile(filePath, content, force, result, targetDir) {
+    const relativePath = getRelativePath(targetDir, filePath);
+    if (fs.existsSync(filePath) && !force) {
+        result.skipped.push(relativePath);
+        return;
+    }
+    const parentDir = path.dirname(filePath);
+    if (!fs.existsSync(parentDir)) {
+        fs.mkdirSync(parentDir, { recursive: true });
+    }
+    fs.writeFileSync(filePath, content);
+    result.created.push(relativePath);
+}
+// Agent onboarding docs templates (duplicated from init.ts for modularity)
+const QUICK_REF_COMMANDS_TEMPLATE = `# Quick Reference: LumenFlow Commands
+
+**Last updated:** {{DATE}}
+
+---
+
+## Project Setup
+
+| Command                                       | Description                             |
+| --------------------------------------------- | --------------------------------------- |
+| \`pnpm exec lumenflow init\`                    | Scaffold minimal LumenFlow core         |
+| \`pnpm exec lumenflow init --full\`             | Add docs/04-operations task scaffolding |
+| \`pnpm exec lumenflow init --framework <name>\` | Add framework hint + overlay docs       |
+| \`pnpm exec lumenflow init --force\`            | Overwrite existing files                |
+
+---
+
+## WU Management
+
+| Command                                                                                                                                                                                                               | Description                                   |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
+| \`pnpm wu:create --id WU-XXX --lane <Lane> --title "Title" --description "..." --acceptance "..." --code-paths "path" --test-paths-unit "path" --exposure backend-only --spec-refs "~/.lumenflow/plans/WU-XXX.md"\` | Create new WU                                 |
+| \`pnpm wu:claim --id WU-XXX --lane <Lane>\`                                                                                                                                                                             | Claim WU (creates worktree)                   |
+| \`pnpm wu:done --id WU-XXX\`                                                                                                                                                                                            | Complete WU (merge, stamp, cleanup)           |
+| \`pnpm wu:block --id WU-XXX --reason "Reason"\`                                                                                                                                                                         | Block a WU                                    |
+| \`pnpm wu:unblock --id WU-XXX\`                                                                                                                                                                                         | Unblock a WU                                  |
+
+---
+
+## Gates
+
+| Command                  | Description                |
+| ------------------------ | -------------------------- |
+| \`pnpm gates\`             | Run all quality gates      |
+| \`pnpm gates --docs-only\` | Run gates for docs changes |
+| \`pnpm format\`            | Format all files           |
+| \`pnpm lint\`              | Run linter                 |
+| \`pnpm typecheck\`         | Run TypeScript check       |
+
+---
+
+## File Paths
+
+| Path                                      | Description          |
+| ----------------------------------------- | -------------------- |
+| \`docs/04-operations/tasks/wu/WU-XXX.yaml\` | WU specification     |
+| \`docs/04-operations/tasks/status.md\`      | Current status board |
+| \`.lumenflow/stamps/WU-XXX.done\`           | Completion stamp     |
+| \`worktrees/<lane>-wu-xxx/\`                | Worktree directory   |
+`;
+const FIRST_WU_MISTAKES_TEMPLATE = `# First WU Mistakes
+
+**Last updated:** {{DATE}}
+
+Common mistakes agents make on their first WU, and how to avoid them.
+
+---
+
+## Mistake 1: Not Using Worktrees
+
+### Wrong
+
+\`\`\`bash
+# Working directly in main
+vim src/feature.ts
+git commit -m "feat: add feature"
+git push origin main
+\`\`\`
+
+### Right
+
+\`\`\`bash
+# Claim first, then work in worktree
+pnpm wu:claim --id WU-123 --lane Core
+cd worktrees/core-wu-123
+vim src/feature.ts
+git commit -m "feat: add feature"
+git push origin lane/core/wu-123
+cd /path/to/main
+pnpm wu:done --id WU-123
+\`\`\`
+
+---
+
+## Mistake 2: Forgetting to Run wu:done
+
+**TL;DR:** After gates pass, ALWAYS run \`pnpm wu:done --id WU-XXX\`.
+
+---
+
+## Mistake 3: Working Outside code_paths
+
+Only edit files within the specified \`code_paths\`.
+
+---
+
+## Quick Checklist
+
+- [ ] Claim the WU with \`pnpm wu:claim\`
+- [ ] cd to the worktree IMMEDIATELY
+- [ ] Work only in the worktree
+- [ ] Run gates before wu:done
+- [ ] ALWAYS run wu:done
+`;
+const TROUBLESHOOTING_WU_DONE_TEMPLATE = `# Troubleshooting: wu:done Not Run
+
+**Last updated:** {{DATE}}
+
+This is the most common mistake agents make.
+
+---
+
+## The Fix
+
+### Rule: ALWAYS Run wu:done
+
+After gates pass, you MUST run:
+
+\`\`\`bash
+cd /path/to/main
+pnpm wu:done --id WU-XXX
+\`\`\`
+
+Do NOT:
+
+- Ask "Should I run wu:done?"
+- Write "To Complete: pnpm wu:done"
+- Wait for permission
+
+---
+
+## What wu:done Does
+
+1. Validates the worktree exists and has commits
+2. Runs gates in the worktree (not main)
+3. Fast-forward merges to main
+4. Creates the done stamp
+5. Updates status and backlog docs
+6. Removes the worktree
+7. Pushes to origin
+`;
+const AGENT_SAFETY_CARD_TEMPLATE = `# Agent Safety Card
+
+**Last updated:** {{DATE}}
+
+Quick reference for AI agents working in LumenFlow projects.
+
+---
+
+## Stop and Ask When
+
+- Same error repeats 3 times
+- Auth or permissions changes needed
+- PII/PHI/secrets involved
+- Cloud spend decisions
+
+---
+
+## Never Do
+
+| Action                   | Why              |
+| ------------------------ | ---------------- |
+| \`git reset --hard\`       | Data loss        |
+| \`git push --force\`       | History rewrite  |
+| \`--no-verify\`            | Bypasses safety  |
+| Work in main after claim | Breaks isolation |
+| Skip wu:done             | Incomplete WU    |
+
+---
+
+## Always Do
+
+| Action                     | Why              |
+| -------------------------- | ---------------- |
+| Read WU spec first         | Understand scope |
+| cd to worktree after claim | Isolation        |
+| Write tests before code    | TDD              |
+| Run gates before wu:done   | Quality          |
+| Run wu:done                | Complete WU      |
+`;
+const WU_CREATE_CHECKLIST_TEMPLATE = `# WU Creation Checklist
+
+**Last updated:** {{DATE}}
+
+Before running \`pnpm wu:create\`, verify these items.
+
+---
+
+## Step 1: Check Valid Lanes
+
+\`\`\`bash
+grep -A 30 "lanes:" .lumenflow.config.yaml
+\`\`\`
+
+**Format:** \`"Parent: Sublane"\` (colon + single space)
+
+---
+
+## Step 2: Required Fields
+
+| Field | Required For | Example |
+|-------|--------------|---------|
+| \`--id\` | All | \`WU-1234\` |
+| \`--lane\` | All | \`"Experience: Chat"\` |
+| \`--title\` | All | \`"Add feature"\` |
+| \`--description\` | All | \`"Context: ... Problem: ... Solution: ..."\` |
+| \`--acceptance\` | All | \`--acceptance "Works"\` (repeatable) |
+| \`--exposure\` | All | \`ui\`, \`api\`, \`backend-only\`, \`documentation\` |
+| \`--code-paths\` | Code WUs | \`"src/a.ts,src/b.ts"\` |
+| \`--test-paths-unit\` | Code WUs | \`"src/__tests__/a.test.ts"\` |
+| \`--spec-refs\` | Feature WUs | \`"~/.lumenflow/plans/WU-XXX.md"\` |
+
+---
+
+## Step 3: Plan Storage
+
+Plans go in \`~/.lumenflow/plans/\` (NOT in project):
+
+\`\`\`bash
+mkdir -p ~/.lumenflow/plans
+vim ~/.lumenflow/plans/WU-XXX-plan.md
+\`\`\`
+
+Reference in wu:create:
+\`\`\`bash
+--spec-refs "~/.lumenflow/plans/WU-XXX-plan.md"
+\`\`\`
+
+---
+
+## Step 4: Validate First
+
+\`\`\`bash
+pnpm wu:create --id WU-XXX ... --validate
+\`\`\`
+
+Fix errors, then remove \`--validate\` to create.
+`;
+// Claude skills templates
+const WU_LIFECYCLE_SKILL_TEMPLATE = `---
+name: wu-lifecycle
+description: Work Unit claim/block/done workflow automation.
+version: 1.0.0
+---
+
+# WU Lifecycle Skill
+
+## State Machine
+
+\`\`\`
+ready -> in_progress -> waiting/blocked -> done
+\`\`\`
+
+## Core Commands
+
+\`\`\`bash
+# Claim WU
+pnpm wu:claim --id WU-XXX --lane <lane>
+cd worktrees/<lane>-wu-xxx   # IMMEDIATELY
+
+# Complete WU (from main)
+cd ../..
+pnpm wu:done --id WU-XXX
+\`\`\`
+`;
+const WORKTREE_DISCIPLINE_SKILL_TEMPLATE = `---
+name: worktree-discipline
+description: Prevents the "absolute path trap" in Write/Edit/Read tools.
+version: 1.0.0
+---
+
+# Worktree Discipline: Absolute Path Trap Prevention
+
+**Purpose**: Prevent AI agents from bypassing worktree isolation via absolute file paths.
+
+## The Absolute Path Trap
+
+**Problem**: AI agents using Write/Edit/Read tools can bypass worktree isolation by passing absolute paths.
+
+## Golden Rules
+
+1. **Always verify pwd** before file operations
+2. **Never use absolute paths** in Write/Edit/Read tools
+3. **When in doubt, use relative paths**
+`;
+const LUMENFLOW_GATES_SKILL_TEMPLATE = `---
+name: lumenflow-gates
+description: Quality gates troubleshooting (format, lint, typecheck, tests).
+version: 1.0.0
+---
+
+# LumenFlow Gates Skill
+
+## Gate Sequence
+
+\`\`\`
+pnpm gates = format:check -> lint -> typecheck -> spec:linter -> tests
+\`\`\`
+
+## Fix Patterns
+
+| Gate      | Auto-fix        | Manual                              |
+| --------- | --------------- | ----------------------------------- |
+| Format    | \`pnpm format\`   | -                                   |
+| Lint      | \`pnpm lint:fix\` | Fix reported issues                 |
+| Typecheck | -               | Fix type errors (first error first) |
+| Tests     | -               | Debug, fix mocks, update snapshots  |
+`;
+/**
+ * Sync agent onboarding docs to an existing project
+ */
+export async function syncAgentDocs(targetDir, options) {
+    const result = {
+        created: [],
+        skipped: [],
+    };
+    const tokens = {
+        DATE: getCurrentDate(),
+    };
+    const onboardingDir = path.join(targetDir, 'docs', '04-operations', '_frameworks', 'lumenflow', 'agent', 'onboarding');
+    await createDirectory(onboardingDir, result, targetDir);
+    await createFile(path.join(onboardingDir, 'quick-ref-commands.md'), processTemplate(QUICK_REF_COMMANDS_TEMPLATE, tokens), options.force, result, targetDir);
+    await createFile(path.join(onboardingDir, 'first-wu-mistakes.md'), processTemplate(FIRST_WU_MISTAKES_TEMPLATE, tokens), options.force, result, targetDir);
+    await createFile(path.join(onboardingDir, 'troubleshooting-wu-done.md'), processTemplate(TROUBLESHOOTING_WU_DONE_TEMPLATE, tokens), options.force, result, targetDir);
+    await createFile(path.join(onboardingDir, 'agent-safety-card.md'), processTemplate(AGENT_SAFETY_CARD_TEMPLATE, tokens), options.force, result, targetDir);
+    await createFile(path.join(onboardingDir, 'wu-create-checklist.md'), processTemplate(WU_CREATE_CHECKLIST_TEMPLATE, tokens), options.force, result, targetDir);
+    return result;
+}
+/**
+ * Sync Claude skills to an existing project
+ */
+export async function syncSkills(targetDir, options) {
+    const result = {
+        created: [],
+        skipped: [],
+    };
+    const vendor = options.vendor ?? 'none';
+    if (vendor !== 'claude' && vendor !== 'all') {
+        return result;
+    }
+    const tokens = {
+        DATE: getCurrentDate(),
+    };
+    const skillsDir = path.join(targetDir, '.claude', 'skills');
+    // wu-lifecycle skill
+    const wuLifecycleDir = path.join(skillsDir, 'wu-lifecycle');
+    await createDirectory(wuLifecycleDir, result, targetDir);
+    await createFile(path.join(wuLifecycleDir, 'SKILL.md'), processTemplate(WU_LIFECYCLE_SKILL_TEMPLATE, tokens), options.force, result, targetDir);
+    // worktree-discipline skill
+    const worktreeDir = path.join(skillsDir, 'worktree-discipline');
+    await createDirectory(worktreeDir, result, targetDir);
+    await createFile(path.join(worktreeDir, 'SKILL.md'), processTemplate(WORKTREE_DISCIPLINE_SKILL_TEMPLATE, tokens), options.force, result, targetDir);
+    // lumenflow-gates skill
+    const gatesDir = path.join(skillsDir, 'lumenflow-gates');
+    await createDirectory(gatesDir, result, targetDir);
+    await createFile(path.join(gatesDir, 'SKILL.md'), processTemplate(LUMENFLOW_GATES_SKILL_TEMPLATE, tokens), options.force, result, targetDir);
+    return result;
+}
+/**
+ * CLI entry point for docs:sync command
+ * WU-1085: Updated to use parseDocsSyncOptions for proper --help support
+ */
+export async function main() {
+    const opts = parseDocsSyncOptions();
+    const targetDir = process.cwd();
+    console.log('[lumenflow docs:sync] Syncing agent documentation...');
+    console.log(`  Vendor: ${opts.vendor}`);
+    console.log(`  Force: ${opts.force}`);
+    const docsResult = await syncAgentDocs(targetDir, { force: opts.force });
+    const skillsResult = await syncSkills(targetDir, { force: opts.force, vendor: opts.vendor });
+    const created = [...docsResult.created, ...skillsResult.created];
+    const skipped = [...docsResult.skipped, ...skillsResult.skipped];
+    if (created.length > 0) {
+        console.log('\nCreated:');
+        created.forEach((f) => console.log(`  + ${f}`));
+    }
+    if (skipped.length > 0) {
+        console.log('\nSkipped (already exists, use --force to overwrite):');
+        skipped.forEach((f) => console.log(`  - ${f}`));
+    }
+    console.log('\n[lumenflow docs:sync] Done!');
+}
+// CLI entry point (WU-1071 pattern: import.meta.main)
+import { runCLI } from './cli-entry-point.js';
+if (import.meta.main) {
+    runCLI(main);
+}

package/dist/gates.js

@@ -54,35 +54,92 @@ import { buildGatesLogPath, shouldUseGatesAgentMode, updateGatesLatestSymlink, }
 import { detectRiskTier, RISK_TIERS, } from '@lumenflow/core/dist/risk-detector.js';
 // WU-2252: Import invariants runner for first-check validation
 import { runInvariants } from '@lumenflow/core/dist/invariants-runner.js';
-import { Command } from 'commander';
+import { createWUParser } from '@lumenflow/core/dist/arg-parser.js';
 import { BRANCHES, PACKAGES, PKG_MANAGER, PKG_FLAGS, ESLINT_FLAGS, ESLINT_COMMANDS, ESLINT_DEFAULTS, SCRIPTS, CACHE_STRATEGIES, DIRECTORIES, GATE_NAMES, GATE_COMMANDS, TOOL_PATHS, CLI_MODES, EXIT_CODES, FILE_SYSTEM, PRETTIER_ARGS, PRETTIER_FLAGS, } from '@lumenflow/core/dist/wu-constants.js';
-// WU-2457: Add Commander.js for --help support
-function parseGatesArgs(argv = process.argv) {
+/**
+ * WU-1087: Gates-specific option definitions for createWUParser.
+ * Exported for testing and consistency with other CLI commands.
+ */
+export const GATES_OPTIONS = {
+    docsOnly: {
+        name: 'docsOnly',
+        flags: '--docs-only',
+        description: 'Run docs-only gates (format, spec-linter, prompts-lint, backlog-sync)',
+    },
+    fullLint: {
+        name: 'fullLint',
+        flags: '--full-lint',
+        description: 'Run full lint instead of incremental',
+    },
+    fullTests: {
+        name: 'fullTests',
+        flags: '--full-tests',
+        description: 'Run full test suite instead of incremental',
+    },
+    fullCoverage: {
+        name: 'fullCoverage',
+        flags: '--full-coverage',
+        description: 'Force full test suite and coverage gate (implies --full-tests)',
+    },
+    coverageMode: {
+        name: 'coverageMode',
+        flags: '--coverage-mode <mode>',
+        description: 'Coverage gate mode: "warn" logs warnings, "block" fails gate',
+        default: 'block',
+    },
+    verbose: {
+        name: 'verbose',
+        flags: '--verbose',
+        description: 'Stream output in agent mode instead of logging to file',
+    },
+};
+/**
+ * WU-1087: Parse gates options using createWUParser for consistency.
+ * Handles pnpm's `--` separator and provides automatic --help support.
+ *
+ * @returns Parsed options object
+ */
+export function parseGatesOptions() {
     // WU-2465: Pre-filter argv to handle pnpm's `--` separator
     // When invoked via `pnpm gates -- --docs-only`, pnpm passes ["--", "--docs-only"]
-    // Commander treats `--` as "everything after is positional", causing errors.
-    // Solution: Remove standalone `--` from argv before parsing.
-    const filteredArgv = argv.filter((arg, index, arr) => {
-        // Keep `--` only if it's followed by a non-option (actual positional arg)
-        // Remove it if it's followed by an option (starts with -)
+    // createWUParser's default filtering removes all `--`, but we need smarter handling:
+    // Remove `--` only if it's followed by an option (starts with -)
+    const originalArgv = process.argv;
+    const filteredArgv = originalArgv.filter((arg, index, arr) => {
         if (arg === '--') {
             const nextArg = arr[index + 1];
             return nextArg && !nextArg.startsWith('-');
         }
         return true;
     });
-    const program = new Command()
-        .name('gates')
-        .description('Run quality gates with support for docs-only mode, incremental linting, and tiered testing')
-        .option('--docs-only', 'Run docs-only gates (format, spec-linter, prompts-lint, backlog-sync)')
-        .option('--full-lint', 'Run full lint instead of incremental')
-        .option('--full-tests', 'Run full test suite instead of incremental')
-        .option('--full-coverage', 'Force full test suite and coverage gate (implies --full-tests)')
-        .option('--coverage-mode <mode>', 'Coverage gate mode: "warn" logs warnings, "block" fails gate (default)', 'block')
-        .option('--verbose', 'Stream output in agent mode instead of logging to file')
-        .helpOption('-h, --help', 'Display help for command');
-    program.parse(filteredArgv);
-    return program.opts();
+    // Temporarily replace process.argv for createWUParser
+    process.argv = filteredArgv;
+    try {
+        const opts = createWUParser({
+            name: 'gates',
+            description: 'Run quality gates with support for docs-only mode, incremental linting, and tiered testing',
+            options: Object.values(GATES_OPTIONS),
+        });
+        return {
+            docsOnly: opts.docsOnly,
+            fullLint: opts.fullLint,
+            fullTests: opts.fullTests,
+            fullCoverage: opts.fullCoverage,
+            coverageMode: opts.coverageMode ?? 'block',
+            verbose: opts.verbose,
+        };
+    }
+    finally {
+        // Restore original process.argv
+        process.argv = originalArgv;
+    }
+}
+/**
+ * @deprecated Use parseGatesOptions() instead (WU-1087)
+ * Kept for backward compatibility during migration.
+ */
+function parseGatesArgs(argv = process.argv) {
+    return parseGatesOptions();
 }
 /**
  * Build a pnpm command string

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * @lumenflow/cli - Command-line interface for LumenFlow workflow framework
+ *
+ * This package provides CLI commands for the LumenFlow workflow framework.
+ * Most functionality is exposed via bin commands, but the cli-entry-point
+ * helper is exported for use in custom CLI wrappers.
+ *
+ * @see https://lumenflow.dev/reference/cli
+ */
+export { runCLI } from './cli-entry-point.js';