@lumenflow/cli 3.1.2 → 3.1.3

package/README.md

@@ -152,39 +152,40 @@ This package provides CLI commands for the LumenFlow workflow framework, includi
 
 ### System & Setup
 
-| Command                    | Description                                              |
-| -------------------------- | -------------------------------------------------------- |
-| `backlog-prune`            | Clean stale backlog entries                              |
-| `config-get`               | Read and display a value from .lumenflow.config.yaml     |
-| `config-set`               | Safely update .lumenflow.config.yaml via micro-worktree  |
-| `init-plan`                | Link plan to initiative (alias)                          |
-| `lumenflow`                | Initialize LumenFlow in a project                        |
-| `lumenflow-commands`       | List all available CLI commands                          |
-| `lumenflow-docs-sync`      | Sync agent docs (for upgrades) (alias)                   |
-| `lumenflow-doctor`         | Diagnose LumenFlow configuration                         |
-| `lumenflow-init`           | Initialize LumenFlow in a project (alias)                |
-| `lumenflow-integrate`      | Generate enforcement hooks for client                    |
-| `lumenflow-onboard`        | Interactive setup wizard for LumenFlow workspace (alias) |
-| `lumenflow-release`        | Run release workflow                                     |
-| `lumenflow-sync-templates` | Sync templates to project                                |
-| `lumenflow-upgrade`        | Upgrade LumenFlow packages                               |
-| `onboard`                  | Interactive setup wizard for LumenFlow workspace         |
-| `pack-author`              | Author a secure domain pack from templates               |
-| `pack-hash`                | Compute integrity hash for a domain pack                 |
-| `pack-install`             | Install a domain pack into workspace                     |
-| `pack-publish`             | Publish a domain pack to a registry                      |
-| `pack-scaffold`            | Scaffold a new domain pack                               |
-| `pack-search`              | Search for domain packs in a registry                    |
-| `pack-validate`            | Validate a domain pack for integrity                     |
-| `plan-create`              | Create a new plan                                        |
-| `plan-edit`                | Edit plan content                                        |
-| `plan-link`                | Link plan to WU or initiative                            |
-| `plan-promote`             | Promote plan to WU                                       |
-| `state-bootstrap`          | Bootstrap state store                                    |
-| `state-cleanup`            | Clean up stale state data                                |
-| `state-doctor`             | Diagnose state store issues                              |
-| `sync-templates`           | Sync templates to project (alias)                        |
-| `workspace-init`           | Initialize workspace.yaml from interactive prompts       |
+| Command                    | Description                                                         |
+| -------------------------- | ------------------------------------------------------------------- |
+| `backlog-prune`            | Clean stale backlog entries                                         |
+| `cloud-connect`            | Connect workspace.yaml to cloud control plane                       |
+| `config-get`               | Read and display a value from workspace.yaml software_delivery      |
+| `config-set`               | Safely update workspace.yaml software_delivery via micro-worktree   |
+| `init-plan`                | Link plan to initiative (alias)                                     |
+| `lumenflow`                | Initialize LumenFlow in a project                                   |
+| `lumenflow-commands`       | List all available CLI commands                                     |
+| `lumenflow-docs-sync`      | Sync agent docs (for upgrades) (alias)                              |
+| `lumenflow-doctor`         | Diagnose LumenFlow configuration                                    |
+| `lumenflow-init`           | Initialize LumenFlow in a project (alias)                           |
+| `lumenflow-integrate`      | Generate enforcement hooks for client                               |
+| `lumenflow-onboard`        | Legacy entrypoint; use "npx lumenflow" for bootstrap-all onboarding |
+| `lumenflow-release`        | Run release workflow                                                |
+| `lumenflow-sync-templates` | Sync templates to project                                           |
+| `lumenflow-upgrade`        | Upgrade LumenFlow packages                                          |
+| `onboard`                  | Legacy entrypoint; use "npx lumenflow" for bootstrap-all onboarding |
+| `pack-author`              | Author a secure domain pack from templates                          |
+| `pack-hash`                | Compute integrity hash for a domain pack                            |
+| `pack-install`             | Install a domain pack into workspace                                |
+| `pack-publish`             | Publish a domain pack to a registry                                 |
+| `pack-scaffold`            | Scaffold a new domain pack                                          |
+| `pack-search`              | Search for domain packs in a registry                               |
+| `pack-validate`            | Validate a domain pack for integrity                                |
+| `plan-create`              | Create a new plan                                                   |
+| `plan-edit`                | Edit plan content                                                   |
+| `plan-link`                | Link plan to WU or initiative                                       |
+| `plan-promote`             | Promote plan to WU                                                  |
+| `state-bootstrap`          | Bootstrap state store                                               |
+| `state-cleanup`            | Clean up stale state data                                           |
+| `state-doctor`             | Diagnose state store issues                                         |
+| `sync-templates`           | Sync templates to project (alias)                                   |
+| `workspace-init`           | Legacy entrypoint; use "npx lumenflow" for bootstrap-all onboarding |
 
 ### File & Git Operations
 
@@ -295,9 +296,9 @@ pnpm update @lumenflow/cli @lumenflow/core @lumenflow/memory @lumenflow/agent @l
 pnpm exec lumenflow docs:sync
 ```
 
-**Important**: Always run `docs:sync` after upgrading to update agent onboarding documentation, workflow rules, and vendor-specific configurations.
+**Important**: Always run `docs:sync` after package changes to update agent onboarding documentation, workflow rules, and vendor-specific configurations.
 
-For detailed upgrade instructions, migration guides, and troubleshooting, see [UPGRADING.md](https://lumenflow.dev/upgrading).
+For current setup guidance and troubleshooting, see [LUMENFLOW.md](https://lumenflow.dev).
 
 ## License
 

package/dist/agent-issues-query.js

@@ -23,6 +23,7 @@ import chalk from 'chalk';
 import { die } from '@lumenflow/core/error-handler';
 import { LUMENFLOW_PATHS } from '@lumenflow/core/wu-constants';
 import { runCLI } from './cli-entry-point.js';
+import { TOP_ISSUES_DISPLAY_LIMIT, RECENT_ISSUES_DISPLAY_LIMIT, ISSUE_TITLE_TRUNCATION_LENGTH, ISSUE_TITLE_TRUNCATED_TEXT_LENGTH, SEVERITY_PADDING_WIDTH, CATEGORY_PADDING_WIDTH, } from './constants.js';
 /** Log prefix for console output */
 const LOG_PREFIX = '[agent:issues-query]';
 /** Default days to query */
@@ -175,7 +176,7 @@ function displaySummary(issues, sinceDays) {
         const count = bySeverity.get(severity)?.length ?? 0;
         if (count > 0) {
             const color = getSeverityColor(severity);
-            console.log(`    ${color(severity.toUpperCase().padEnd(10))} ${count}`);
+            console.log(`    ${color(severity.toUpperCase().padEnd(SEVERITY_PADDING_WIDTH))} ${count}`);
         }
     }
     console.log('');
@@ -189,7 +190,7 @@ function displaySummary(issues, sinceDays) {
         })
             .filter(Boolean)
             .join(' ');
-        console.log(`    ${String(category).padEnd(20)} ${categoryIssues.length} issues (${severityCounts})`);
+        console.log(`    ${String(category).padEnd(CATEGORY_PADDING_WIDTH)} ${categoryIssues.length} issues (${severityCounts})`);
     }
     console.log('');
     // Top 5 most common issues
@@ -200,12 +201,14 @@ function displaySummary(issues, sinceDays) {
     }
     const topIssues = Array.from(issueCount.entries())
         .sort((a, b) => b[1] - a[1])
-        .slice(0, 5);
+        .slice(0, TOP_ISSUES_DISPLAY_LIMIT);
     if (topIssues.length > 0) {
-        console.log('  Top 5 Most Common:');
+        console.log(`  Top ${TOP_ISSUES_DISPLAY_LIMIT} Most Common:`);
         for (const [key, count] of topIssues) {
             const [category, title] = key.split(':');
-            const truncatedTitle = title.length > 40 ? title.slice(0, 37) + '...' : title;
+            const truncatedTitle = title.length > ISSUE_TITLE_TRUNCATION_LENGTH
+                ? title.slice(0, ISSUE_TITLE_TRUNCATED_TEXT_LENGTH) + '...'
+                : title;
             console.log(`    ${count}x  [${category}] ${truncatedTitle}`);
         }
         console.log('');
@@ -213,13 +216,15 @@ function displaySummary(issues, sinceDays) {
     // Recent issues (last 5)
     const recentIssues = [...issues]
         .sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime())
-        .slice(0, 5);
+        .slice(0, RECENT_ISSUES_DISPLAY_LIMIT);
     console.log('  Recent Issues:');
     for (const issue of recentIssues) {
         const date = new Date(issue.timestamp).toISOString().split('T')[0];
         const badge = formatSeverityBadge(issue.severity);
         const wuInfo = issue.wuId ? ` (${issue.wuId})` : '';
-        const truncatedTitle = issue.title.length > 40 ? issue.title.slice(0, 37) + '...' : issue.title;
+        const truncatedTitle = issue.title.length > ISSUE_TITLE_TRUNCATION_LENGTH
+            ? issue.title.slice(0, ISSUE_TITLE_TRUNCATED_TEXT_LENGTH) + '...'
+            : issue.title;
         console.log(`    ${date} ${badge} ${truncatedTitle}${wuInfo}`);
     }
     console.log('');
@@ -227,7 +232,7 @@ function displaySummary(issues, sinceDays) {
 /**
  * Main function
  */
-async function main() {
+export async function main() {
     const opts = parseArgs();
     const baseDir = process.cwd();
     const sinceDate = new Date();

package/dist/agent-log-issue.js

@@ -17,7 +17,9 @@
 import { Command } from 'commander';
 import { logIncident, getCurrentSession } from '@lumenflow/agent';
 import { EXIT_CODES, INCIDENT_SEVERITY, LUMENFLOW_PATHS } from '@lumenflow/core/wu-constants';
+import { ProcessExitError } from '@lumenflow/core/error-handler';
 import chalk from 'chalk';
+import { runCLI } from './cli-entry-point.js';
 /**
  * WU-1182: Collector function for Commander.js repeatable options.
  * Accumulates multiple flag values into an array.
@@ -49,9 +51,10 @@ const program = new Command()
     try {
         const session = await getCurrentSession();
         if (!session) {
-            console.error(chalk.red('Error: No active session'));
+            const message = 'Error: No active session';
+            console.error(chalk.red(message));
             console.error('Run: pnpm agent:session --wu WU-XXX --tier N');
-            process.exit(EXIT_CODES.ERROR);
+            throw new ProcessExitError(message, EXIT_CODES.ERROR);
         }
         const incident = {
             category: opts.category,
@@ -77,6 +80,9 @@ const program = new Command()
         }
     }
     catch (err) {
+        if (err instanceof ProcessExitError) {
+            throw err;
+        }
         const error = err;
         console.error(chalk.red(`Error: ${error.message ?? 'Unknown error'}`));
         if (error.issues) {
@@ -85,8 +91,13 @@ const program = new Command()
                 console.error(chalk.red(`  - ${issue.path.join('.')}: ${issue.message}`));
             });
         }
-        process.exit(EXIT_CODES.ERROR);
+        throw new ProcessExitError(error.message ?? 'Unknown error', EXIT_CODES.ERROR);
     }
 });
-program.parse();
+export async function main() {
+    await program.parseAsync(process.argv);
+}
+if (import.meta.main) {
+    void runCLI(main);
+}
 //# sourceMappingURL=agent-log-issue.js.map

package/dist/agent-session-end.js

@@ -12,7 +12,9 @@
 import { Command } from 'commander';
 import { endSession, getCurrentSession } from '@lumenflow/agent';
 import { EXIT_CODES } from '@lumenflow/core/wu-constants';
+import { ProcessExitError } from '@lumenflow/core/error-handler';
 import chalk from 'chalk';
+import { runCLI } from './cli-entry-point.js';
 const program = new Command()
     .name('agent:session:end')
     .description('End the current agent session')
@@ -20,8 +22,9 @@ const program = new Command()
     try {
         const session = await getCurrentSession();
         if (!session) {
-            console.error(chalk.yellow('No active session to end.'));
-            process.exit(EXIT_CODES.SUCCESS);
+            const message = 'No active session to end.';
+            console.error(chalk.yellow(message));
+            throw new ProcessExitError(message, EXIT_CODES.SUCCESS);
         }
         const summary = await endSession();
         console.log(chalk.green(`✓ Session ended`));
@@ -31,10 +34,18 @@ const program = new Command()
         console.log(`  Incidents: ${summary.incidents_logged} (${summary.incidents_major} major)`);
     }
     catch (err) {
+        if (err instanceof ProcessExitError) {
+            throw err;
+        }
         const message = err instanceof Error ? err.message : String(err);
         console.error(chalk.red(`Error: ${message}`));
-        process.exit(EXIT_CODES.ERROR);
+        throw new ProcessExitError(message, EXIT_CODES.ERROR);
     }
 });
-program.parse();
+export async function main() {
+    await program.parseAsync(process.argv);
+}
+if (import.meta.main) {
+    void runCLI(main);
+}
 //# sourceMappingURL=agent-session-end.js.map

package/dist/agent-session.js

@@ -12,7 +12,9 @@
 import { Command } from 'commander';
 import { startSession, getCurrentSession } from '@lumenflow/agent';
 import { EXIT_CODES } from '@lumenflow/core/wu-constants';
+import { ProcessExitError } from '@lumenflow/core/error-handler';
 import chalk from 'chalk';
+import { runCLI } from './cli-entry-point.js';
 const program = new Command()
     .name('agent:session')
     .description('Start an agent session')
@@ -24,14 +26,16 @@ const program = new Command()
         // Check for existing session
         const existing = await getCurrentSession();
         if (existing) {
-            console.error(chalk.red(`Session already active for ${existing.wu_id}`));
+            const message = `Session already active for ${existing.wu_id}`;
+            console.error(chalk.red(message));
             console.error(`Run: pnpm agent:session:end to close it first.`);
-            process.exit(EXIT_CODES.ERROR);
+            throw new ProcessExitError(message, EXIT_CODES.ERROR);
         }
         const tier = parseInt(opts.tier, 10);
         if (![1, 2, 3].includes(tier)) {
-            console.error(chalk.red('Invalid tier. Must be 1, 2, or 3.'));
-            process.exit(EXIT_CODES.ERROR);
+            const message = 'Invalid tier. Must be 1, 2, or 3.';
+            console.error(chalk.red(message));
+            throw new ProcessExitError(message, EXIT_CODES.ERROR);
         }
         const sessionId = await startSession(opts.wu, tier, opts.agentType);
         console.log(chalk.green(`✓ Session started`));
@@ -41,10 +45,18 @@ const program = new Command()
         console.log(`  Agent: ${chalk.cyan(opts.agentType)}`);
     }
     catch (err) {
+        if (err instanceof ProcessExitError) {
+            throw err;
+        }
         const message = err instanceof Error ? err.message : String(err);
         console.error(chalk.red(`Error: ${message}`));
-        process.exit(EXIT_CODES.ERROR);
+        throw new ProcessExitError(message, EXIT_CODES.ERROR);
     }
 });
-program.parse();
+export async function main() {
+    await program.parseAsync(process.argv);
+}
+if (import.meta.main) {
+    void runCLI(main);
+}
 //# sourceMappingURL=agent-session.js.map

package/dist/backlog-prune.js

@@ -233,7 +233,7 @@ This tool:
 /**
  * Main function
  */
-async function main() {
+export async function main() {
     const args = parseBacklogPruneArgs(process.argv);
     if (args.help) {
         printHelp();

package/dist/commands/integrate.js

@@ -6,7 +6,7 @@
  * Integrate LumenFlow with Claude Code (WU-1367)
  *
  * This command generates enforcement hooks and updates Claude Code
- * configuration based on .lumenflow.config.yaml settings.
+ * configuration based on workspace.yaml software_delivery settings.
  *
  * Usage:
  *   pnpm lumenflow:integrate --client claude-code
@@ -17,7 +17,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as yaml from 'yaml';
-import { createWUParser, WU_OPTIONS, CLAUDE_HOOKS, DIRECTORIES, LUMENFLOW_CLIENT_IDS, } from '@lumenflow/core';
+import { createWUParser, WU_OPTIONS, CLAUDE_HOOKS, DIRECTORIES, LUMENFLOW_CLIENT_IDS, WORKSPACE_CONFIG_FILE_NAME, WORKSPACE_V2_KEYS, } from '@lumenflow/core';
 import { generateEnforcementHooks, generateEnforceWorktreeScript, generateRequireWuScript, generateWarnIncompleteScript, } from '../hooks/enforcement-generator.js';
 import { runCLI } from '../cli-entry-point.js';
 /**
@@ -181,22 +181,34 @@ export async function integrateClaudeCode(projectDir, config) {
     return created;
 }
 /**
- * Read enforcement config from .lumenflow.config.yaml
+ * Read software_delivery config from workspace.yaml.
  */
-function readEnforcementConfig(projectDir) {
-    const configPath = path.join(projectDir, '.lumenflow.config.yaml');
+function readWorkspaceSoftwareDeliveryConfig(projectDir) {
+    const configPath = path.join(projectDir, WORKSPACE_CONFIG_FILE_NAME);
     if (!fs.existsSync(configPath)) {
         return null;
     }
     try {
         const content = fs.readFileSync(configPath, 'utf-8');
-        const config = yaml.parse(content);
-        return config?.agents?.clients?.[LUMENFLOW_CLIENT_IDS.CLAUDE_CODE]?.enforcement ?? null;
+        const workspaceDoc = yaml.parse(content);
+        if (!workspaceDoc || typeof workspaceDoc !== 'object') {
+            return null;
+        }
+        const workspace = workspaceDoc;
+        const softwareDelivery = workspace[WORKSPACE_V2_KEYS.SOFTWARE_DELIVERY];
+        if (!softwareDelivery || typeof softwareDelivery !== 'object') {
+            return null;
+        }
+        return softwareDelivery;
     }
     catch {
         return null;
     }
 }
+function readEnforcementConfig(projectDir) {
+    const softwareDelivery = readWorkspaceSoftwareDeliveryConfig(projectDir);
+    return softwareDelivery?.agents?.clients?.[LUMENFLOW_CLIENT_IDS.CLAUDE_CODE]?.enforcement ?? null;
+}
 /**
  * Main entry point for integrate command
  */
@@ -208,20 +220,22 @@ export async function main() {
         process.exit(1);
     }
     const projectDir = process.cwd();
-    // Read enforcement config from .lumenflow.config.yaml
+    // Read enforcement config from workspace.yaml software_delivery
     const enforcement = readEnforcementConfig(projectDir);
     if (!enforcement) {
-        console.log('[integrate] No enforcement config found in .lumenflow.config.yaml');
-        console.log('[integrate] Add this to your config to enable enforcement hooks:');
+        console.log(`[integrate] No enforcement config found in ${WORKSPACE_CONFIG_FILE_NAME} ` +
+            `${WORKSPACE_V2_KEYS.SOFTWARE_DELIVERY}.agents.clients.${LUMENFLOW_CLIENT_IDS.CLAUDE_CODE}`);
+        console.log('[integrate] Add this to your workspace config to enable enforcement hooks:');
         console.log(`
-agents:
-  clients:
-    ${LUMENFLOW_CLIENT_IDS.CLAUDE_CODE}:
-      enforcement:
-        hooks: true
-        block_outside_worktree: true
-        require_wu_for_edits: true
-        warn_on_stop_without_wu_done: true
+${WORKSPACE_V2_KEYS.SOFTWARE_DELIVERY}:
+  agents:
+    clients:
+      ${LUMENFLOW_CLIENT_IDS.CLAUDE_CODE}:
+        enforcement:
+          hooks: true
+          block_outside_worktree: true
+          require_wu_for_edits: true
+          warn_on_stop_without_wu_done: true
 `);
         return;
     }

package/dist/config-get.js

@@ -3,42 +3,54 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 /**
  * @file config-get.ts
- * WU-1902: Safe config:get CLI command for reading .lumenflow.config.yaml values
+ * WU-1902 / WU-1973: Safe config:get CLI command for reading workspace.yaml values
  *
- * Reads and displays current values from the config using dotpath notation.
- * Uses getConfig from @lumenflow/core/config for consistent config loading.
+ * Reads and displays current values from workspace.yaml using dotpath notation.
+ * Canonical keys use the software_delivery prefix.
  *
  * Usage:
- *   pnpm config:get --key methodology.testing
- *   pnpm config:get --key gates.minCoverage
+ *   pnpm config:get --key software_delivery.methodology.testing
+ *   pnpm config:get --key software_delivery.gates.minCoverage
  */
 import path from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import YAML from 'yaml';
 import { findProjectRoot } from '@lumenflow/core/config';
 import { die } from '@lumenflow/core/error-handler';
-import { CONFIG_FILES, FILE_SYSTEM } from '@lumenflow/core/wu-constants';
+import { FILE_SYSTEM } from '@lumenflow/core/wu-constants';
 import { runCLI } from './cli-entry-point.js';
-import { parseConfigGetArgs, getConfigValue } from './config-set.js';
+import { parseConfigGetArgs, getConfigValue, normalizeWorkspaceConfigKey, WORKSPACE_FILE_NAME, WORKSPACE_CONFIG_PREFIX, } from './config-set.js';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 const LOG_PREFIX = '[config:get]';
+const WORKSPACE_INIT_COMMAND = 'pnpm workspace-init --yes';
 // ---------------------------------------------------------------------------
 // Main: config:get
 // ---------------------------------------------------------------------------
-async function main() {
+export async function main() {
     const userArgs = process.argv.slice(2);
     const options = parseConfigGetArgs(userArgs);
     const projectRoot = findProjectRoot();
-    const configPath = path.join(projectRoot, CONFIG_FILES.LUMENFLOW_CONFIG);
-    if (!existsSync(configPath)) {
-        die(`${LOG_PREFIX} Missing ${CONFIG_FILES.LUMENFLOW_CONFIG}. Run \`pnpm exec lumenflow init\` first.`);
+    const workspacePath = path.join(projectRoot, WORKSPACE_FILE_NAME);
+    if (!existsSync(workspacePath)) {
+        die(`${LOG_PREFIX} Missing ${WORKSPACE_FILE_NAME}. Run \`${WORKSPACE_INIT_COMMAND}\` first.`);
+    }
+    // Read raw workspace (preserving YAML structure, not Zod-parsed defaults)
+    const content = readFileSync(workspacePath, FILE_SYSTEM.UTF8);
+    const workspace = YAML.parse(content) ?? {};
+    // Canonical read path (full workspace key)
+    let value = getConfigValue(workspace, options.key);
+    if (value === undefined) {
+        // Shorthand compatibility: methodology.testing -> software_delivery.methodology.testing
+        const shorthandKey = normalizeWorkspaceConfigKey(options.key);
+        if (shorthandKey !== options.key) {
+            value = getConfigValue(workspace, `${WORKSPACE_CONFIG_PREFIX}${shorthandKey}`);
+        }
+        else {
+            value = getConfigValue(workspace, `${WORKSPACE_CONFIG_PREFIX}${options.key}`);
+        }
     }
-    // Read raw config (preserving YAML structure, not Zod-parsed)
-    const content = readFileSync(configPath, FILE_SYSTEM.UTF8);
-    const config = YAML.parse(content) ?? {};
-    const value = getConfigValue(config, options.key);
     if (value === undefined) {
         console.log(`${LOG_PREFIX} Key "${options.key}" is not set (undefined)`);
         process.exitCode = 0;