@lumenflow/cli 2.11.0 → 2.13.0

package/README.md

@@ -101,7 +101,7 @@ This package provides CLI commands for the LumenFlow workflow framework, includi
 
 | Command                      | Description                                                        |
 | ---------------------------- | ------------------------------------------------------------------ |
-| `initiative-add-wu`          | Link a WU to an initiative bidirectionally                         |
+| `initiative-add-wu`          | Link one or more WUs to an initiative bidirectionally              |
 | `initiative-bulk-assign-wus` | Bulk-assign orphaned WUs to initiatives based on lane prefix rules |
 | `initiative-create`          | Create a new Initiative with micro-worktree isolation (race-safe)  |
 | `initiative-edit`            | Edit Initiative YAML files with micro-worktree isolation           |
@@ -131,21 +131,15 @@ This package provides CLI commands for the LumenFlow workflow framework, includi
 
 ### Verification & Gates
 
-| Command           | Description                                                                                |
-| ----------------- | ------------------------------------------------------------------------------------------ |
-| `gates`           | Run quality gates with support for docs-only mode, incremental linting, and tiered testing |
-| `lumenflow-gates` | Alias for `gates` command                                                                  |
+| Command | Description                                                                                |
+| ------- | ------------------------------------------------------------------------------------------ |
+| `gates` | Run quality gates with support for docs-only mode, incremental linting, and tiered testing |
 
 ### System & Setup
 
 | Command                    | Description                                                                       |
 | -------------------------- | --------------------------------------------------------------------------------- |
 | `backlog-prune`            | Backlog Prune Command                                                             |
-| `deps-add`                 | Deps Add CLI Command                                                              |
-| `deps-remove`              | Deps Remove CLI Command                                                           |
-| `guard-locked`             |                                                                                   |
-| `guard-main-branch`        | Guard Main Branch CLI Tool                                                        |
-| `guard-worktree-commit`    |                                                                                   |
 | `init-plan`                | Link a plan file to an initiative                                                 |
 | `lumenflow`                | Initialize LumenFlow in a project\n\n                                             |
 | `lumenflow-commands`       | List all available LumenFlow CLI commands                                         |
@@ -162,19 +156,12 @@ This package provides CLI commands for the LumenFlow workflow framework, includi
 | `plan-edit`                | Edit a section in a plan file                                                     |
 | `plan-link`                | Link a plan file to a WU or initiative                                            |
 | `plan-promote`             | Promote a plan to approved status                                                 |
-| `rotate-progress`          | Rotate Progress CLI Command                                                       |
-| `session-coordinator`      | Session Coordinator CLI Command                                                   |
 | `signal-cleanup`           | Prune old signals based on TTL policy to prevent unbounded growth                 |
 | `state-bootstrap`          | State Bootstrap Command                                                           |
 | `state-cleanup`            | Orchestrate all state cleanup: signals, memory, events                            |
 | `state-doctor`             | Check state integrity and optionally repair issues                                |
 | `sync-templates`           | Sync internal docs to CLI templates for release-cycle maintenance                 |
-| `trace-gen`                | Trace Generator CLI Command                                                       |
 | `validate`                 |                                                                                   |
-| `validate-agent-skills`    |                                                                                   |
-| `validate-agent-sync`      |                                                                                   |
-| `validate-backlog-sync`    |                                                                                   |
-| `validate-skills-spec`     |                                                                                   |
 
 ### File & Git Operations
 
@@ -292,3 +279,5 @@ For detailed upgrade instructions, migration guides, and troubleshooting, see [U
 ## License
 
 Apache-2.0
+
+<!-- MODIFIED -->

package/dist/__tests__/commands.test.js

@@ -1,12 +1,23 @@
 /**
  * @file commands.test.ts
  * Tests for lumenflow commands discovery feature (WU-1378)
+ * Extended for public CLI manifest alignment (WU-1432)
  *
- * Tests the new commands subcommand that lists all available CLI commands
- * grouped by category with brief descriptions.
+ * Tests the commands subcommand that lists all available CLI commands
+ * grouped by category with brief descriptions. Also verifies alignment
+ * between public-manifest.ts, commands.ts, and package.json bin entries.
  */
 import { describe, it, expect } from 'vitest';
 import { getCommandsRegistry, formatCommandsOutput } from '../commands.js';
+import { getPublicManifest, getPublicCommandNames, getPublicBinNames, isPublicCommand, } from '../public-manifest.js';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageJsonPath = join(__dirname, '../../package.json');
+// Script commands that are NOT CLI binaries (pnpm scripts only)
+// These appear in the registry but should NOT be in the manifest
+const SCRIPT_COMMANDS = new Set(['format', 'lint', 'typecheck', 'test', 'setup']);
 describe('lumenflow commands', () => {
     describe('getCommandsRegistry', () => {
         it('should return command categories', () => {
@@ -73,3 +84,188 @@ describe('lumenflow commands', () => {
         });
     });
 });
+// ============================================================================
+// WU-1432: Public CLI Manifest Tests
+// ============================================================================
+describe('public CLI manifest (WU-1432)', () => {
+    describe('getPublicManifest', () => {
+        it('should return an array of public commands', () => {
+            const manifest = getPublicManifest();
+            expect(manifest).toBeDefined();
+            expect(Array.isArray(manifest)).toBe(true);
+            expect(manifest.length).toBeGreaterThan(0);
+        });
+        it('should have required fields for each command', () => {
+            const manifest = getPublicManifest();
+            for (const cmd of manifest) {
+                expect(cmd.name).toBeDefined();
+                expect(typeof cmd.name).toBe('string');
+                expect(cmd.name.length).toBeGreaterThan(0);
+                expect(cmd.binName).toBeDefined();
+                expect(typeof cmd.binName).toBe('string');
+                expect(cmd.binName.length).toBeGreaterThan(0);
+                expect(cmd.description).toBeDefined();
+                expect(typeof cmd.description).toBe('string');
+                expect(cmd.description.length).toBeGreaterThan(0);
+                expect(cmd.category).toBeDefined();
+                expect(typeof cmd.category).toBe('string');
+                expect(cmd.category.length).toBeGreaterThan(0);
+            }
+        });
+        it('should include core public commands', () => {
+            const names = getPublicCommandNames();
+            // WU lifecycle - must be public
+            expect(names).toContain('wu:create');
+            expect(names).toContain('wu:claim');
+            expect(names).toContain('wu:done');
+            expect(names).toContain('wu:prep');
+            expect(names).toContain('wu:status');
+            // Gates - must be public
+            expect(names).toContain('gates');
+            expect(names).toContain('lumenflow');
+            // Memory - must be public
+            expect(names).toContain('mem:checkpoint');
+            expect(names).toContain('mem:inbox');
+            // Initiatives - must be public
+            expect(names).toContain('initiative:create');
+            expect(names).toContain('initiative:status');
+        });
+        it('should NOT include internal/maintainer commands', () => {
+            const names = getPublicCommandNames();
+            // Guards are internal
+            expect(names).not.toContain('guard-worktree-commit');
+            expect(names).not.toContain('guard-locked');
+            expect(names).not.toContain('guard-main-branch');
+            // Validation internals
+            expect(names).not.toContain('validate-agent-skills');
+            expect(names).not.toContain('validate-agent-sync');
+            expect(names).not.toContain('validate-backlog-sync');
+            expect(names).not.toContain('validate-skills-spec');
+            // Session internals
+            expect(names).not.toContain('session-coordinator');
+            expect(names).not.toContain('rotate-progress');
+            // Trace/debug internals
+            expect(names).not.toContain('trace-gen');
+        });
+    });
+    describe('isPublicCommand', () => {
+        it('should return true for public commands', () => {
+            expect(isPublicCommand('wu:create')).toBe(true);
+            expect(isPublicCommand('wu:claim')).toBe(true);
+            expect(isPublicCommand('gates')).toBe(true);
+            expect(isPublicCommand('lumenflow')).toBe(true);
+        });
+        it('should return false for internal commands', () => {
+            expect(isPublicCommand('guard-worktree-commit')).toBe(false);
+            expect(isPublicCommand('validate-agent-skills')).toBe(false);
+            expect(isPublicCommand('session-coordinator')).toBe(false);
+        });
+    });
+});
+describe('manifest alignment (WU-1432)', () => {
+    describe('commands.ts derives from manifest', () => {
+        it('should have all CLI registry commands in the public manifest (excluding script commands)', () => {
+            const registry = getCommandsRegistry();
+            const publicNames = new Set(getPublicCommandNames());
+            const registryNames = [];
+            for (const category of registry) {
+                for (const cmd of category.commands) {
+                    // Skip script commands - they're not CLI binaries
+                    if (!SCRIPT_COMMANDS.has(cmd.name)) {
+                        registryNames.push(cmd.name);
+                    }
+                }
+            }
+            // Every CLI command in the registry must be a public command
+            for (const name of registryNames) {
+                expect(publicNames.has(name), `Command "${name}" in registry but not in public manifest`).toBe(true);
+            }
+        });
+        it('should have matching descriptions between manifest and registry', () => {
+            const manifest = getPublicManifest();
+            const registry = getCommandsRegistry();
+            // Build a map of registry descriptions
+            const registryDescriptions = new Map();
+            for (const category of registry) {
+                for (const cmd of category.commands) {
+                    registryDescriptions.set(cmd.name, cmd.description);
+                }
+            }
+            // For commands that appear in both, descriptions should match
+            for (const cmd of manifest) {
+                const registryDesc = registryDescriptions.get(cmd.name);
+                if (registryDesc) {
+                    expect(cmd.description, `Description mismatch for "${cmd.name}"`).toBe(registryDesc);
+                }
+            }
+        });
+        it('should have matching categories between manifest and registry', () => {
+            const manifest = getPublicManifest();
+            const registry = getCommandsRegistry();
+            // Build a map of registry categories
+            const registryCategories = new Map();
+            for (const category of registry) {
+                for (const cmd of category.commands) {
+                    registryCategories.set(cmd.name, category.name);
+                }
+            }
+            // For commands that appear in both, categories should match
+            for (const cmd of manifest) {
+                const registryCategory = registryCategories.get(cmd.name);
+                if (registryCategory) {
+                    expect(cmd.category, `Category mismatch for "${cmd.name}"`).toBe(registryCategory);
+                }
+            }
+        });
+    });
+    describe('package.json bin alignment', () => {
+        it('should only include public commands in bin', () => {
+            const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+            const binEntries = Object.keys(packageJson.bin || {});
+            const publicBinNames = new Set(getPublicBinNames());
+            // Every bin entry should be in the public manifest
+            for (const binName of binEntries) {
+                expect(publicBinNames.has(binName), `Bin "${binName}" is in package.json but not in public manifest - should it be internal?`).toBe(true);
+            }
+        });
+        it('should have all public commands in bin', () => {
+            const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+            const binEntries = new Set(Object.keys(packageJson.bin || {}));
+            const publicManifest = getPublicManifest();
+            // Every public manifest command should have a bin entry
+            for (const cmd of publicManifest) {
+                expect(binEntries.has(cmd.binName), `Public command "${cmd.name}" (bin: ${cmd.binName}) missing from package.json bin`).toBe(true);
+            }
+        });
+        it('should have correct file paths in bin', () => {
+            const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+            const publicManifest = getPublicManifest();
+            for (const cmd of publicManifest) {
+                const binPath = packageJson.bin?.[cmd.binName];
+                expect(binPath, `Missing bin path for ${cmd.binName}`).toBeDefined();
+                expect(binPath, `Bin path for ${cmd.binName} should start with ./dist/`).toMatch(/^\.\/dist\//);
+                expect(binPath, `Bin path for ${cmd.binName} should end with .js`).toMatch(/\.js$/);
+            }
+        });
+        it('should not include internal commands in bin', () => {
+            const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+            const binEntries = Object.keys(packageJson.bin || {});
+            // These internal commands should NOT be in bin
+            const internalCommands = [
+                'guard-worktree-commit',
+                'guard-locked',
+                'guard-main-branch',
+                'validate-agent-skills',
+                'validate-agent-sync',
+                'validate-backlog-sync',
+                'validate-skills-spec',
+                'session-coordinator',
+                'rotate-progress',
+                'trace-gen',
+            ];
+            for (const internalCmd of internalCommands) {
+                expect(binEntries.includes(internalCmd), `Internal command "${internalCmd}" should NOT be in package.json bin`).toBe(false);
+            }
+        });
+    });
+});

package/dist/__tests__/init-docs-structure.test.js

@@ -67,6 +67,24 @@ describe('docs-structure', () => {
             expect(fs.existsSync(path.join(tempDir, 'docs', 'tasks'))).toBe(true);
             expect(fs.existsSync(path.join(tempDir, 'docs', DOCS_04_OPERATIONS))).toBe(false);
         });
+        it('should scaffold WU template with resilient defaults (simple)', async () => {
+            const options = {
+                force: false,
+                full: true,
+                docsStructure: SIMPLE_DOCS_STRUCTURE,
+            };
+            await scaffoldProject(tempDir, options);
+            const templatePath = path.join(tempDir, 'docs', 'tasks', 'templates', 'wu-template.yaml');
+            expect(fs.existsSync(templatePath)).toBe(true);
+            const content = fs.readFileSync(templatePath, 'utf-8');
+            // Feature WUs should reference plan protocol by default (plan-less friendly).
+            expect(content).toContain('lumenflow://plans/WU-XXX-plan.md');
+            // Ensure non-empty notes to avoid strict spec-linter failures out of the box.
+            expect(content).not.toContain("notes: ''");
+            expect(content).toContain('notes:');
+            // Ensure manual test stub exists to prevent empty tests failures.
+            expect(content).toContain('Manual check:');
+        });
         it('should scaffold arc42 structure with --docs-structure arc42', async () => {
             const options = {
                 force: false,
@@ -77,6 +95,21 @@ describe('docs-structure', () => {
             // Arc42 structure: docs/04-operations/tasks
             expect(fs.existsSync(path.join(tempDir, 'docs', DOCS_04_OPERATIONS, 'tasks'))).toBe(true);
         });
+        it('should scaffold WU template with resilient defaults (arc42)', async () => {
+            const options = {
+                force: false,
+                full: true,
+                docsStructure: ARC42_DOCS_STRUCTURE,
+            };
+            await scaffoldProject(tempDir, options);
+            const templatePath = path.join(tempDir, 'docs', DOCS_04_OPERATIONS, 'tasks', 'templates', 'wu-template.yaml');
+            expect(fs.existsSync(templatePath)).toBe(true);
+            const content = fs.readFileSync(templatePath, 'utf-8');
+            expect(content).toContain('lumenflow://plans/WU-XXX-plan.md');
+            expect(content).not.toContain("notes: ''");
+            expect(content).toContain('notes:');
+            expect(content).toContain('Manual check:');
+        });
         it('should auto-detect arc42 when docs/04-operations exists', async () => {
             // Create existing arc42 structure
             fs.mkdirSync(path.join(tempDir, 'docs', DOCS_04_OPERATIONS), { recursive: true });

package/dist/__tests__/initiative-add-wu.test.js

@@ -10,7 +10,8 @@ import { describe, it, expect, vi, beforeEach, afterEach, beforeAll } from 'vite
 import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
-import { stringifyYAML } from '@lumenflow/core/dist/wu-yaml.js';
+import { stringifyYAML, readWU } from '@lumenflow/core/dist/wu-yaml.js';
+import { readInitiative } from '@lumenflow/initiatives/dist/initiative-yaml.js';
 // Test constants to avoid lint warnings about duplicate strings
 const TEST_WU_ID = 'WU-123';
 const TEST_INIT_ID = 'INIT-001';
@@ -22,6 +23,7 @@ const TEST_INIT_TITLE = 'Test Initiative';
 const TEST_INIT_STATUS = 'open';
 const TEST_DATE = '2026-01-25';
 const MIN_DESCRIPTION_LENGTH = 50;
+const TEST_WU_ID_2 = 'WU-124';
 // Valid WU document template
 const createValidWUDoc = (overrides = {}) => ({
     id: TEST_WU_ID,
@@ -324,6 +326,50 @@ describe('initiative:add-wu WU validation (WU-1330)', () => {
             expect(result.valid).toBe(true);
         });
     });
+    describe('batch linking (WU-1460)', () => {
+        it('should normalize repeatable --wu values with dedupe and order preservation', async () => {
+            const { normalizeWuIds } = await import('../initiative-add-wu.js');
+            expect(normalizeWuIds(TEST_WU_ID)).toEqual([TEST_WU_ID]);
+            expect(normalizeWuIds([TEST_WU_ID, TEST_WU_ID_2, TEST_WU_ID])).toEqual([
+                TEST_WU_ID,
+                TEST_WU_ID_2,
+            ]);
+        });
+        it('should update multiple WUs and initiative in one execute call', async () => {
+            const { buildAddWuMicroWorktreeOptions } = await import('../initiative-add-wu.js');
+            // Setup valid WUs and initiative
+            const wuDir = join(tempDir, WU_REL_PATH);
+            const initDir = join(tempDir, INIT_REL_PATH);
+            mkdirSync(wuDir, { recursive: true });
+            mkdirSync(initDir, { recursive: true });
+            const wuPath1 = join(wuDir, `${TEST_WU_ID}.yaml`);
+            const wuPath2 = join(wuDir, `${TEST_WU_ID_2}.yaml`);
+            const initPath = join(initDir, `${TEST_INIT_ID}.yaml`);
+            writeFileSync(wuPath1, stringifyYAML(createValidWUDoc({ id: TEST_WU_ID })));
+            writeFileSync(wuPath2, stringifyYAML(createValidWUDoc({ id: TEST_WU_ID_2 })));
+            writeFileSync(initPath, stringifyYAML(createValidInitDoc()));
+            process.chdir(tempDir);
+            const options = buildAddWuMicroWorktreeOptions([TEST_WU_ID, TEST_WU_ID_2], TEST_INIT_ID);
+            const result = await options.execute({ worktreePath: tempDir });
+            expect(result.files).toContain(`${WU_REL_PATH}/${TEST_WU_ID}.yaml`);
+            expect(result.files).toContain(`${WU_REL_PATH}/${TEST_WU_ID_2}.yaml`);
+            expect(result.files).toContain(`${INIT_REL_PATH}/${TEST_INIT_ID}.yaml`);
+            const updatedWu1 = readWU(wuPath1, TEST_WU_ID);
+            const updatedWu2 = readWU(wuPath2, TEST_WU_ID_2);
+            const updatedInit = readInitiative(initPath, TEST_INIT_ID);
+            expect(updatedWu1.initiative).toBe(TEST_INIT_ID);
+            expect(updatedWu2.initiative).toBe(TEST_INIT_ID);
+            expect(updatedInit.wus).toContain(TEST_WU_ID);
+            expect(updatedInit.wus).toContain(TEST_WU_ID_2);
+        });
+        it('should validate conflicting links across multiple WUs', async () => {
+            const { validateNoConflictingLinks } = await import('../initiative-add-wu.js');
+            expect(() => validateNoConflictingLinks([
+                { id: TEST_WU_ID, initiative: TEST_INIT_ID },
+                { id: TEST_WU_ID_2, initiative: 'INIT-999' },
+            ], TEST_INIT_ID)).toThrow();
+        });
+    });
     describe('error formatting', () => {
         it('should format errors in human-readable format', async () => {
             const { formatValidationErrors } = await import('../initiative-add-wu.js');
@@ -356,6 +402,24 @@ describe('initiative:add-wu WU validation (WU-1330)', () => {
             const mod = await import('../initiative-add-wu.js');
             expect(typeof mod.formatRetryExhaustionError).toBe('function');
         });
+        it('should export operation-level push retry override (WU-1459)', async () => {
+            const mod = await import('../initiative-add-wu.js');
+            expect(mod.INITIATIVE_ADD_WU_PUSH_RETRY_OVERRIDE).toBeDefined();
+            expect(mod.INITIATIVE_ADD_WU_PUSH_RETRY_OVERRIDE.retries).toBeGreaterThan(3);
+            expect(mod.INITIATIVE_ADD_WU_PUSH_RETRY_OVERRIDE.min_delay_ms).toBeGreaterThan(100);
+        });
+        it('should export helper to build micro-worktree options (WU-1459)', async () => {
+            const mod = await import('../initiative-add-wu.js');
+            expect(typeof mod.buildAddWuMicroWorktreeOptions).toBe('function');
+            const options = mod.buildAddWuMicroWorktreeOptions(TEST_WU_ID, TEST_INIT_ID);
+            expect(options.pushOnly).toBe(true);
+            expect(options.pushRetryOverride).toEqual(mod.INITIATIVE_ADD_WU_PUSH_RETRY_OVERRIDE);
+        });
+        it('should export batch helpers (WU-1460)', async () => {
+            const mod = await import('../initiative-add-wu.js');
+            expect(typeof mod.normalizeWuIds).toBe('function');
+            expect(typeof mod.validateNoConflictingLinks).toBe('function');
+        });
     });
 });
 /**
@@ -416,5 +480,11 @@ describe('initiative:add-wu retry handling (WU-1333)', () => {
             // Should mention concurrent agents as possible cause
             expect(formatted).toMatch(/concurrent|agent|traffic/i);
         });
+        it('should include git.push_retry tuning guidance', async () => {
+            const { formatRetryExhaustionError } = await import('../initiative-add-wu.js');
+            const retryError = new Error('Push failed after 3 attempts.');
+            const formatted = formatRetryExhaustionError(retryError, TEST_WU_ID, TEST_INIT_ID);
+            expect(formatted).toContain('git.push_retry.retries');
+        });
     });
 });

package/dist/__tests__/no-beacon-references-docs.test.js

@@ -0,0 +1,30 @@
+/**
+ * @file no-beacon-references-docs.test.ts
+ * Guardrail test: public + onboarding docs must not reference legacy `.beacon` paths (WU-1450).
+ */
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+function repoRootFromThisFile() {
+    // packages/@lumenflow/cli/src/__tests__/no-beacon-references-docs.test.ts -> repo root
+    const thisDir = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(thisDir, '..', '..', '..', '..', '..');
+}
+describe('no legacy .beacon references in docs (WU-1450)', () => {
+    it('should not contain .beacon references in onboarding/public docs', () => {
+        const repoRoot = repoRootFromThisFile();
+        const files = [
+            'docs/04-operations/_frameworks/lumenflow/agent/onboarding/agent-safety-card.md',
+            'docs/04-operations/_frameworks/lumenflow/agent/onboarding/lumenflow-force-usage.md',
+            'apps/docs/src/content/docs/getting-started/upgrade.mdx',
+            'apps/docs/src/content/docs/reference/changelog.mdx',
+            'apps/docs/src/content/docs/reference/compatibility.mdx',
+        ];
+        for (const relPath of files) {
+            const absPath = path.join(repoRoot, relPath);
+            const content = readFileSync(absPath, 'utf-8');
+            expect(content, `${relPath} should not reference .beacon`).not.toContain('.beacon');
+        }
+    });
+});

package/dist/__tests__/no-beacon-references.test.js

@@ -0,0 +1,39 @@
+/**
+ * @file no-beacon-references.test.ts
+ * Guardrail test: `.beacon` is legacy and must not be referenced in docs/templates/scripts (WU-1447).
+ *
+ * This keeps onboarding friction-free by ensuring `.lumenflow/` is the single canonical namespace.
+ */
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+function repoRootFromThisFile() {
+    // packages/@lumenflow/cli/src/__tests__/no-beacon-references.test.ts -> repo root (../../../../../)
+    const thisDir = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(thisDir, '..', '..', '..', '..', '..');
+}
+describe('no legacy .beacon references (WU-1447)', () => {
+    it('should not contain .beacon references in tracked onboarding docs/templates/scripts', () => {
+        const repoRoot = repoRootFromThisFile();
+        const files = [
+            'scripts/safe-git',
+            'scripts/hooks/check-lockfile.sh',
+            'scripts/hooks/scan-secrets.sh',
+            'scripts/hooks/validate-paths.sh',
+            'scripts/hooks/validate-worktree-discipline.sh',
+            'LUMENFLOW.md',
+            'packages/@lumenflow/cli/templates/core/LUMENFLOW.md.template',
+            'packages/@lumenflow/cli/templates/core/ai/onboarding/agent-safety-card.md.template',
+            'packages/@lumenflow/cli/templates/core/ai/onboarding/lumenflow-force-usage.md.template',
+            'apps/docs/src/content/docs/guides/agent-onboarding.mdx',
+            'apps/docs/src/content/docs/guides/ai-agents.mdx',
+            'packages/@lumenflow/agent/README.md',
+        ];
+        for (const relPath of files) {
+            const absPath = path.join(repoRoot, relPath);
+            const content = readFileSync(absPath, 'utf-8');
+            expect(content, `${relPath} should not reference .beacon`).not.toContain('.beacon');
+        }
+    });
+});

package/dist/__tests__/wu-create.test.js

@@ -3,7 +3,7 @@
  * Tests for wu:create helpers and warnings (WU-1429)
  */
 import { describe, it, expect } from 'vitest';
-import { buildWUContent, collectInitiativeWarnings } from '../wu-create.js';
+import { buildWUContent, collectInitiativeWarnings, validateCreateSpec } from '../wu-create.js';
 const BASE_WU = {
     id: 'WU-1429',
     lane: 'Framework: CLI',
@@ -21,6 +21,19 @@ const BASE_WU = {
     },
 };
 describe('wu:create helpers (WU-1429)', () => {
+    it('should default notes to non-empty placeholder when not provided', () => {
+        const wu = buildWUContent({
+            ...BASE_WU,
+            opts: {
+                ...BASE_WU.opts,
+                // Intentionally omit notes
+                notes: undefined,
+            },
+        });
+        expect(typeof wu.notes).toBe('string');
+        expect(wu.notes.trim().length).toBeGreaterThan(0);
+        expect(wu.notes).toContain('(auto)');
+    });
     it('should persist notes when provided', () => {
         const wu = buildWUContent({
             ...BASE_WU,
@@ -31,6 +44,42 @@ describe('wu:create helpers (WU-1429)', () => {
         });
         expect(wu.notes).toBe('Implementation notes for test');
     });
+    it('should allow creating a plan-first WU without explicit test flags when code_paths are non-code', () => {
+        const validation = validateCreateSpec({
+            id: 'WU-2000',
+            lane: 'Framework: CLI',
+            title: 'Plan-only spec creation',
+            priority: 'P2',
+            type: 'feature',
+            opts: {
+                description: 'Context: test context.\nProblem: test problem.\nSolution: test solution that exceeds minimum.',
+                acceptance: ['Acceptance criterion'],
+                exposure: 'backend-only',
+                // Non-code file path: manual-only tests are acceptable.
+                codePaths: ['docs/README.md'],
+                // No testPathsManual/unit/e2e provided - should auto-default manual stub.
+                specRefs: ['lumenflow://plans/WU-2000-plan.md'],
+                strict: false,
+            },
+        });
+        expect(validation.valid).toBe(true);
+        const wu = buildWUContent({
+            id: 'WU-2000',
+            lane: 'Framework: CLI',
+            title: 'Plan-only spec creation',
+            priority: 'P2',
+            type: 'feature',
+            created: '2026-02-05',
+            opts: {
+                description: 'Context: test context.\nProblem: test problem.\nSolution: test solution that exceeds minimum.',
+                acceptance: ['Acceptance criterion'],
+                exposure: 'backend-only',
+                codePaths: ['docs/README.md'],
+                specRefs: ['lumenflow://plans/WU-2000-plan.md'],
+            },
+        });
+        expect(wu.tests?.manual?.length).toBeGreaterThan(0);
+    });
     it('should warn when initiative has phases but no --phase is provided', () => {
         const warnings = collectInitiativeWarnings({
             initiativeId: 'INIT-TEST',

package/dist/__tests__/wu-done-docs-only-policy.test.js

@@ -0,0 +1,20 @@
+/**
+ * @file wu-done-docs-only-policy.test.ts
+ * Guardrail test: docs-only eligibility checks must not use raw type/exposure string literals (WU-1446).
+ *
+ * This keeps CLI policy logic DRY and aligned with core constants/helpers.
+ */
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+describe('wu:done docs-only policy (WU-1446)', () => {
+    it('should not use raw documentation string comparisons for type/exposure checks', () => {
+        const thisDir = path.dirname(fileURLToPath(import.meta.url));
+        const filePath = path.join(thisDir, '..', 'wu-done.ts');
+        const content = readFileSync(filePath, 'utf-8');
+        // These comparisons should use core constants/helpers instead.
+        expect(content).not.toContain("exposure === 'documentation'");
+        expect(content).not.toContain("type === 'documentation'");
+    });
+});

package/dist/__tests__/wu-prep-default-exec.test.js

@@ -0,0 +1,35 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+vi.mock('node:child_process', async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, spawnSync: vi.fn() };
+});
+vi.mock('node:fs', async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, existsSync: vi.fn() };
+});
+describe('wu-prep default exec helpers (WU-1441)', () => {
+    beforeEach(() => {
+        vi.resetModules();
+        vi.resetAllMocks();
+    });
+    it('uses node + dist wu-validate for JSON comparison when available', async () => {
+        const { spawnSync } = await import('node:child_process');
+        const { existsSync } = await import('node:fs');
+        // Pretend dist sibling exists so defaultExec picks node+dist path (not pnpm on main).
+        vi.mocked(existsSync).mockReturnValue(true);
+        // Both worktree and main should report WU-1 invalid.
+        vi.mocked(spawnSync).mockReturnValue({
+            status: 1,
+            stdout: JSON.stringify({ invalid: [{ wuId: 'WU-1' }] }),
+            stderr: '',
+        });
+        const { checkPreExistingFailures } = await import('../wu-prep.js');
+        const result = await checkPreExistingFailures({ mainCheckout: '/repo' });
+        expect(result.error).toBeUndefined();
+        expect(result.hasPreExisting).toBe(true);
+        expect(result.hasNewFailures).toBe(false);
+        // Default exec should run node directly, not "pnpm wu:validate" from the main checkout.
+        expect(vi.mocked(spawnSync).mock.calls.length).toBeGreaterThan(0);
+        expect(vi.mocked(spawnSync).mock.calls[0]?.[0]).toBe('node');
+    });
+});