@lumenflow/cli 2.0.0 → 2.1.1

package/README.md

@@ -140,6 +140,25 @@ The CLI integrates with other LumenFlow packages:
 
 For complete documentation, see [lumenflow.dev](https://lumenflow.dev/reference/cli).
 
+## Upgrading
+
+To upgrade LumenFlow packages:
+
+```bash
+# Check for available updates
+pnpm outdated @lumenflow/*
+
+# Update all LumenFlow packages
+pnpm update @lumenflow/cli @lumenflow/core @lumenflow/memory @lumenflow/agent @lumenflow/initiatives
+
+# Sync documentation and templates
+pnpm exec lumenflow docs:sync
+```
+
+**Important**: Always run `docs:sync` after upgrading 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).
+
 ## License
 
 Apache-2.0

package/dist/__tests__/lumenflow-upgrade.test.js

@@ -3,18 +3,50 @@
  * Tests for lumenflow-upgrade CLI command
  *
  * WU-1112: INIT-003 Phase 6 - Migrate remaining Tier 1 tools
+ * WU-1127: Add micro-worktree isolation pattern
  *
  * lumenflow-upgrade updates all @lumenflow/* packages to latest versions.
  * Key requirements:
- * - Uses worktree pattern (runs pnpm install in worktree, not main)
+ * - Uses micro-worktree pattern (atomic changes to main without requiring user worktree)
  * - Checks all 7 @lumenflow/* packages
+ * - Supports --dry-run and --latest flags
  */
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-// Import functions under test
-import { parseUpgradeArgs, LUMENFLOW_PACKAGES, buildUpgradeCommands, } from '../lumenflow-upgrade.js';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { execSync } from 'node:child_process';
+// Mock modules with inline factories (no external references)
+vi.mock('@lumenflow/core/dist/micro-worktree.js', () => ({
+    withMicroWorktree: vi.fn(),
+}));
+vi.mock('@lumenflow/core/dist/git-adapter.js', () => ({
+    getGitForCwd: vi.fn(),
+}));
+vi.mock('node:child_process', async (importOriginal) => {
+    const actual = await importOriginal();
+    return {
+        ...actual,
+        execSync: vi.fn(),
+    };
+});
+// Import mocked modules to access mock functions
+import { withMicroWorktree } from '@lumenflow/core/dist/micro-worktree.js';
+import { getGitForCwd } from '@lumenflow/core/dist/git-adapter.js';
+// Import functions under test after mocks are set up
+import { parseUpgradeArgs, LUMENFLOW_PACKAGES, buildUpgradeCommands, executeUpgradeInMicroWorktree, validateMainCheckout, } from '../lumenflow-upgrade.js';
+// Cast mocks for TypeScript
+const mockWithMicroWorktree = withMicroWorktree;
+const mockGetGitForCwd = getGitForCwd;
+const mockExecSync = execSync;
 describe('lumenflow-upgrade', () => {
     beforeEach(() => {
         vi.clearAllMocks();
+        // Default mock behavior for git adapter
+        mockGetGitForCwd.mockReturnValue({
+            raw: vi.fn().mockResolvedValue('main'),
+            getStatus: vi.fn().mockResolvedValue(''),
+        });
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
     });
     describe('LUMENFLOW_PACKAGES constant', () => {
         it('should include all 7 @lumenflow/* packages', () => {
@@ -94,14 +126,135 @@ describe('lumenflow-upgrade', () => {
             expect(packageCount).toBe(7);
         });
     });
-    describe('worktree pattern enforcement', () => {
-        it('should include note about worktree usage in commands', () => {
-            const args = { version: '1.5.0' };
-            const commands = buildUpgradeCommands(args);
-            // The command should be designed to run in worktree
-            // Actual execution is tested in integration tests
-            expect(commands.addCommand).toBeDefined();
-            expect(commands.addCommand.length).toBeGreaterThan(0);
+    // WU-1127: Tests for micro-worktree isolation pattern
+    describe('validateMainCheckout', () => {
+        let originalCwd;
+        beforeEach(() => {
+            originalCwd = process.cwd;
+        });
+        afterEach(() => {
+            process.cwd = originalCwd;
+        });
+        it('should return valid when on main branch and not in worktree', async () => {
+            // Mock process.cwd to be on main checkout (not worktree)
+            process.cwd = vi.fn().mockReturnValue('/path/to/repo');
+            mockGetGitForCwd.mockReturnValue({
+                raw: vi.fn().mockResolvedValue('main'),
+                getStatus: vi.fn().mockResolvedValue(''),
+            });
+            const result = await validateMainCheckout();
+            expect(result.valid).toBe(true);
+        });
+        it('should return invalid when not on main branch', async () => {
+            // Mock process.cwd to be on main checkout (not worktree)
+            process.cwd = vi.fn().mockReturnValue('/path/to/repo');
+            mockGetGitForCwd.mockReturnValue({
+                raw: vi.fn().mockResolvedValue('lane/framework-cli/wu-123'),
+                getStatus: vi.fn().mockResolvedValue(''),
+            });
+            const result = await validateMainCheckout();
+            expect(result.valid).toBe(false);
+            expect(result.error).toContain('must be run from main checkout');
+        });
+        it('should return invalid when in a worktree directory', async () => {
+            // Mock process.cwd() to be in a worktree
+            process.cwd = vi
+                .fn()
+                .mockReturnValue('/path/to/repo/worktrees/some-wu');
+            mockGetGitForCwd.mockReturnValue({
+                raw: vi.fn().mockResolvedValue('main'),
+                getStatus: vi.fn().mockResolvedValue(''),
+            });
+            const result = await validateMainCheckout();
+            expect(result.valid).toBe(false);
+            expect(result.error).toContain('worktree');
+        });
+    });
+    describe('executeUpgradeInMicroWorktree', () => {
+        it('should call withMicroWorktree with correct operation name', async () => {
+            mockWithMicroWorktree.mockResolvedValue({});
+            mockExecSync.mockReturnValue('');
+            const args = { version: '2.1.0' };
+            await executeUpgradeInMicroWorktree(args);
+            expect(mockWithMicroWorktree).toHaveBeenCalledTimes(1);
+            expect(mockWithMicroWorktree).toHaveBeenCalledWith(expect.objectContaining({
+                operation: 'lumenflow-upgrade',
+            }));
+        });
+        it('should use a unique ID for micro-worktree based on timestamp', async () => {
+            mockWithMicroWorktree.mockResolvedValue({});
+            mockExecSync.mockReturnValue('');
+            const args = { latest: true };
+            await executeUpgradeInMicroWorktree(args);
+            // ID should be a timestamp-like string
+            expect(mockWithMicroWorktree).toHaveBeenCalledWith(expect.objectContaining({
+                id: expect.stringMatching(/^upgrade-\d+$/),
+            }));
+        });
+        it('should execute pnpm add in the micro-worktree', async () => {
+            mockWithMicroWorktree.mockImplementation(async (options) => {
+                // Simulate calling the execute function with a worktree path
+                return options.execute({ worktreePath: '/tmp/test-worktree' });
+            });
+            const args = { version: '2.1.0' };
+            await executeUpgradeInMicroWorktree(args);
+            // Verify pnpm add was executed with correct cwd
+            expect(mockExecSync).toHaveBeenCalledWith(expect.stringContaining('pnpm add'), expect.objectContaining({
+                cwd: '/tmp/test-worktree',
+            }));
+        });
+        it('should include all 7 packages in the pnpm add command', async () => {
+            mockWithMicroWorktree.mockImplementation(async (options) => {
+                return options.execute({ worktreePath: '/tmp/test-worktree' });
+            });
+            const args = { version: '2.1.0' };
+            await executeUpgradeInMicroWorktree(args);
+            // Get the command that was executed
+            const execCall = mockExecSync.mock.calls[0][0];
+            expect(typeof execCall).toBe('string');
+            // Verify all 7 packages are included
+            for (const pkg of LUMENFLOW_PACKAGES) {
+                expect(execCall).toContain(`${pkg}@2.1.0`);
+            }
+        });
+        it('should return appropriate commit message and files', async () => {
+            let executeResult;
+            mockWithMicroWorktree.mockImplementation(async (options) => {
+                executeResult = await options.execute({ worktreePath: '/tmp/test-worktree' });
+                return executeResult;
+            });
+            const args = { version: '2.1.0' };
+            await executeUpgradeInMicroWorktree(args);
+            expect(executeResult).toBeDefined();
+            expect(executeResult.commitMessage).toContain('upgrade @lumenflow packages');
+            expect(executeResult.files).toContain('package.json');
+            expect(executeResult.files).toContain('pnpm-lock.yaml');
+        });
+        it('should use --latest version specifier when latest flag is set', async () => {
+            mockWithMicroWorktree.mockImplementation(async (options) => {
+                return options.execute({ worktreePath: '/tmp/test-worktree' });
+            });
+            const args = { latest: true };
+            await executeUpgradeInMicroWorktree(args);
+            const execCall = mockExecSync.mock.calls[0][0];
+            expect(execCall).toContain('@lumenflow/core@latest');
+        });
+    });
+    describe('dry-run mode', () => {
+        it('should not call withMicroWorktree when dryRun is true', async () => {
+            const args = { version: '2.1.0', dryRun: true };
+            // In dry-run mode, executeUpgradeInMicroWorktree should not be called
+            // This is handled by the main() function checking dryRun before calling execute
+            // We just verify the function exists and can be called
+            expect(typeof executeUpgradeInMicroWorktree).toBe('function');
+        });
+    });
+    describe('legacy worktree validation removal', () => {
+        it('should not require user to be in a worktree', () => {
+            // The old implementation required users to be inside a worktree
+            // The new implementation uses micro-worktree and runs from main checkout
+            // This test verifies the old validateWorktreeContext is no longer used
+            expect(typeof validateMainCheckout).toBe('function');
         });
     });
 });

package/dist/docs-sync.js

@@ -2,9 +2,11 @@
  * @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
+ * WU-1124: Refactored to read templates from bundled files (INIT-004 Phase 2)
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { createWUParser, WU_OPTIONS } from '@lumenflow/core';
 /**
  * WU-1085: CLI option definitions for docs-sync command
@@ -33,6 +35,40 @@ export function parseDocsSyncOptions() {
         vendor: opts.vendor ?? 'claude',
     };
 }
+/**
+ * WU-1124: Get the templates directory path
+ * Templates are bundled with the CLI package at dist/templates/
+ * Falls back to src/templates/ for development
+ */
+export function getTemplatesDir() {
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = path.dirname(__filename);
+    // In production: dist/docs-sync.js -> templates/
+    // In development: src/docs-sync.ts -> ../templates/
+    const distTemplates = path.join(__dirname, '..', 'templates');
+    if (fs.existsSync(distTemplates)) {
+        return distTemplates;
+    }
+    // Fallback for tests running from src
+    const srcTemplates = path.join(__dirname, '..', 'templates');
+    if (fs.existsSync(srcTemplates)) {
+        return srcTemplates;
+    }
+    throw new Error(`Templates directory not found at ${distTemplates}`);
+}
+/**
+ * WU-1124: Load a template file from the bundled templates directory
+ * @param templatePath - Relative path from templates directory (e.g., 'core/ai/onboarding/quick-ref-commands.md.template')
+ * @returns Template content as string
+ */
+export function loadTemplate(templatePath) {
+    const templatesDir = getTemplatesDir();
+    const fullPath = path.join(templatesDir, templatePath);
+    if (!fs.existsSync(fullPath)) {
+        throw new Error(`Template not found: ${templatePath} (looked at ${fullPath})`);
+    }
+    return fs.readFileSync(fullPath, 'utf-8');
+}
 /**
  * Get current date in YYYY-MM-DD format
  */
@@ -77,317 +113,29 @@ async function createFile(filePath, content, force, result, targetDir) {
     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  |
-`;
+/**
+ * WU-1124: Template paths for agent onboarding docs
+ * Maps output file names to template paths
+ */
+const ONBOARDING_TEMPLATE_PATHS = {
+    'quick-ref-commands.md': 'core/ai/onboarding/quick-ref-commands.md.template',
+    'first-wu-mistakes.md': 'core/ai/onboarding/first-wu-mistakes.md.template',
+    'troubleshooting-wu-done.md': 'core/ai/onboarding/troubleshooting-wu-done.md.template',
+    'agent-safety-card.md': 'core/ai/onboarding/agent-safety-card.md.template',
+    'wu-create-checklist.md': 'core/ai/onboarding/wu-create-checklist.md.template',
+};
+/**
+ * WU-1124: Template paths for Claude skills
+ * Maps skill names to template paths
+ */
+const SKILL_TEMPLATE_PATHS = {
+    'wu-lifecycle': 'vendors/claude/.claude/skills/wu-lifecycle/SKILL.md.template',
+    'worktree-discipline': 'vendors/claude/.claude/skills/worktree-discipline/SKILL.md.template',
+    'lumenflow-gates': 'vendors/claude/.claude/skills/lumenflow-gates/SKILL.md.template',
+};
 /**
  * Sync agent onboarding docs to an existing project
+ * WU-1124: Now reads templates from bundled files instead of hardcoded strings
  */
 export async function syncAgentDocs(targetDir, options) {
     const result = {
@@ -399,15 +147,17 @@ export async function syncAgentDocs(targetDir, options) {
     };
     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);
+    // WU-1124: Load and process templates from bundled files
+    for (const [outputFile, templatePath] of Object.entries(ONBOARDING_TEMPLATE_PATHS)) {
+        const templateContent = loadTemplate(templatePath);
+        const processedContent = processTemplate(templateContent, tokens);
+        await createFile(path.join(onboardingDir, outputFile), processedContent, options.force, result, targetDir);
+    }
     return result;
 }
 /**
  * Sync Claude skills to an existing project
+ * WU-1124: Now reads templates from bundled files instead of hardcoded strings
  */
 export async function syncSkills(targetDir, options) {
     const result = {
@@ -422,18 +172,14 @@ export async function syncSkills(targetDir, options) {
         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);
+    // WU-1124: Load and process skill templates from bundled files
+    for (const [skillName, templatePath] of Object.entries(SKILL_TEMPLATE_PATHS)) {
+        const skillDir = path.join(skillsDir, skillName);
+        await createDirectory(skillDir, result, targetDir);
+        const templateContent = loadTemplate(templatePath);
+        const processedContent = processTemplate(templateContent, tokens);
+        await createFile(path.join(skillDir, 'SKILL.md'), processedContent, options.force, result, targetDir);
+    }
     return result;
 }
 /**

package/dist/lumenflow-upgrade.js

@@ -3,13 +3,16 @@
  * LumenFlow Upgrade CLI Command
  *
  * Updates all @lumenflow/* packages to a specified version or latest.
- * Uses worktree pattern to ensure pnpm install runs in worktree, not main.
+ * Uses micro-worktree pattern for atomic changes to main without requiring
+ * users to be in a worktree.
  *
  * WU-1112: INIT-003 Phase 6 - Migrate remaining Tier 1 tools
+ * WU-1127: Use micro-worktree isolation pattern (fixes user blocking issue)
  *
- * Key requirements (from WU acceptance criteria):
- * - Uses worktree pattern (install runs in worktree, not main)
- * - Checks all 7 @lumenflow/* packages (not just 4)
+ * Key requirements:
+ * - Uses micro-worktree pattern (atomic changes, no user worktree needed)
+ * - Runs from main checkout (not inside a worktree)
+ * - Checks all 7 @lumenflow/* packages
  *
  * Usage:
  *   pnpm lumenflow:upgrade --version 1.5.0
@@ -17,11 +20,14 @@
  *   pnpm lumenflow:upgrade --latest --dry-run
  */
 import { execSync } from 'node:child_process';
-import { STDIO_MODES, EXIT_CODES, PKG_MANAGER, } from '@lumenflow/core/dist/wu-constants.js';
+import { STDIO_MODES, EXIT_CODES, PKG_MANAGER, DEFAULTS, BRANCHES, } from '@lumenflow/core/dist/wu-constants.js';
+import { getGitForCwd } from '@lumenflow/core/dist/git-adapter.js';
+import { withMicroWorktree } from '@lumenflow/core/dist/micro-worktree.js';
 import { runCLI } from './cli-entry-point.js';
-import { validateWorktreeContext } from './deps-add.js';
 /** Log prefix for console output */
 const LOG_PREFIX = '[lumenflow:upgrade]';
+/** Operation name for micro-worktree */
+const OPERATION_NAME = 'lumenflow-upgrade';
 /**
  * All @lumenflow/* packages that should be upgraded together
  *
@@ -85,6 +91,98 @@ export function buildUpgradeCommands(args) {
         versionSpec,
     };
 }
+/**
+ * WU-1127: Validate that the command is run from main checkout
+ *
+ * The micro-worktree pattern requires the command to be run from the main
+ * checkout (not inside a worktree). This is the inverse of the old behavior
+ * which required users to be IN a worktree.
+ *
+ * @returns Validation result with error and fix command if invalid
+ */
+export async function validateMainCheckout() {
+    const cwd = process.cwd();
+    const worktreesDir = `/${DEFAULTS.WORKTREES_DIR}/`;
+    // Check if we're inside a worktree directory
+    if (cwd.includes(worktreesDir)) {
+        return {
+            valid: false,
+            error: `Cannot run lumenflow:upgrade from inside a worktree.\n\n` +
+                `This command must be run from main checkout because it uses\n` +
+                `micro-worktree isolation to atomically update package.json and lockfile.`,
+            fixCommand: `cd to main checkout and re-run:\n  cd <main-checkout>\n  pnpm lumenflow:upgrade --latest`,
+        };
+    }
+    // Check if we're on main branch
+    try {
+        const git = getGitForCwd();
+        const currentBranch = await git.raw(['rev-parse', '--abbrev-ref', 'HEAD']);
+        const branchName = currentBranch.trim();
+        if (branchName !== BRANCHES.MAIN) {
+            return {
+                valid: false,
+                error: `lumenflow:upgrade must be run from main checkout (on main branch).\n\n` +
+                    `Current branch: ${branchName}\n` +
+                    `Expected branch: main`,
+                fixCommand: `Switch to main branch:\n  git checkout main\n  pnpm lumenflow:upgrade --latest`,
+            };
+        }
+    }
+    catch (error) {
+        // If git fails, assume we're not in a valid git repo
+        return {
+            valid: false,
+            error: `Failed to detect git branch. Ensure you're in a git repository.`,
+        };
+    }
+    return { valid: true };
+}
+/**
+ * WU-1127: Execute the upgrade in a micro-worktree
+ *
+ * Uses the shared micro-worktree pattern (like wu:create, wu:edit) to:
+ * 1. Create a temporary worktree without switching main checkout
+ * 2. Run pnpm add in the temporary worktree
+ * 3. Commit the changes
+ * 4. FF-only merge to main
+ * 5. Push to origin
+ * 6. Cleanup
+ *
+ * @param args - Parsed upgrade arguments
+ * @returns Promise resolving when upgrade is complete
+ */
+export async function executeUpgradeInMicroWorktree(args) {
+    const { addCommand, versionSpec } = buildUpgradeCommands(args);
+    // Generate unique ID for this upgrade operation using timestamp
+    const upgradeId = `upgrade-${Date.now()}`;
+    console.log(`${LOG_PREFIX} Using micro-worktree isolation (WU-1127)`);
+    console.log(`${LOG_PREFIX} Upgrading @lumenflow/* packages to ${versionSpec}`);
+    console.log(`${LOG_PREFIX} Packages: ${LUMENFLOW_PACKAGES.length} packages`);
+    await withMicroWorktree({
+        operation: OPERATION_NAME,
+        id: upgradeId,
+        logPrefix: LOG_PREFIX,
+        execute: async ({ worktreePath }) => {
+            console.log(`${LOG_PREFIX} Running: ${addCommand}`);
+            // Execute pnpm add in the micro-worktree
+            execSync(addCommand, {
+                stdio: STDIO_MODES.INHERIT,
+                cwd: worktreePath,
+            });
+            console.log(`${LOG_PREFIX} Package installation complete`);
+            // Return files to stage and commit message
+            return {
+                commitMessage: `chore: upgrade @lumenflow packages to ${versionSpec}`,
+                files: ['package.json', 'pnpm-lock.yaml'],
+            };
+        },
+    });
+    console.log(`\n${LOG_PREFIX} Upgrade complete!`);
+    console.log(`${LOG_PREFIX} Upgraded to ${versionSpec}`);
+    console.log(`\n${LOG_PREFIX} Next steps:`);
+    console.log(`  1. Run 'pnpm build' to rebuild with new versions`);
+    console.log(`  2. Run 'pnpm gates' to verify everything works`);
+}
 /**
  * Print help message for lumenflow-upgrade
  */
@@ -94,7 +192,7 @@ function printHelp() {
 Usage: lumenflow-upgrade [options]
 
 Upgrade all @lumenflow/* packages to a specified version.
-Must be run from inside a worktree to enforce worktree discipline.
+Uses micro-worktree isolation to atomically update packages from main checkout.
 
 Options:
   -v, --version <ver>   Upgrade to specific version (e.g., 1.5.0)
@@ -110,13 +208,13 @@ Examples:
   lumenflow:upgrade --latest           # Upgrade to latest
   lumenflow:upgrade --latest --dry-run # Preview upgrade commands
 
-Worktree Discipline:
-  This command only works inside a worktree to prevent lockfile
-  conflicts on main checkout. Claim a WU first:
+Micro-Worktree Pattern (WU-1127):
+  This command uses micro-worktree isolation to atomically update
+  package.json and pnpm-lock.yaml without requiring you to claim a WU.
 
-    pnpm wu:claim --id WU-XXXX --lane "Your Lane"
-    cd worktrees/<lane>-wu-<id>/
-    lumenflow:upgrade --latest
+  Run from your main checkout (NOT from inside a worktree):
+    cd /path/to/main
+    pnpm lumenflow:upgrade --latest
 `);
 }
 /**
@@ -135,40 +233,32 @@ async function main() {
         printHelp();
         process.exit(EXIT_CODES.ERROR);
     }
-    // Validate worktree context (WU-1112 requirement: must run in worktree)
-    const validation = validateWorktreeContext(process.cwd());
+    // WU-1127: Validate we're on main checkout (not in a worktree)
+    const validation = await validateMainCheckout();
     if (!validation.valid) {
         console.error(`${LOG_PREFIX} ${validation.error}`);
-        console.error(`\nTo fix:\n${validation.fixCommand}`);
+        if (validation.fixCommand) {
+            console.error(`\nTo fix:\n${validation.fixCommand}`);
+        }
         process.exit(EXIT_CODES.ERROR);
     }
-    // Build upgrade commands
+    // Build upgrade commands for dry-run display
     const { addCommand, versionSpec } = buildUpgradeCommands(args);
-    console.log(`${LOG_PREFIX} Upgrading @lumenflow/* packages to ${versionSpec}`);
-    console.log(`${LOG_PREFIX} Packages: ${LUMENFLOW_PACKAGES.length} packages`);
     if (args.dryRun) {
-        console.log(`\n${LOG_PREFIX} DRY RUN - Commands that would be executed:`);
+        console.log(`${LOG_PREFIX} DRY RUN - Commands that would be executed:`);
         console.log(`  ${addCommand}`);
+        console.log(`\n${LOG_PREFIX} Packages: ${LUMENFLOW_PACKAGES.length}`);
+        console.log(`${LOG_PREFIX} Version: ${versionSpec}`);
         console.log(`\n${LOG_PREFIX} No changes made.`);
         process.exit(EXIT_CODES.SUCCESS);
     }
-    // Execute upgrade
-    console.log(`${LOG_PREFIX} Running: ${addCommand}`);
+    // Execute upgrade using micro-worktree
     try {
-        execSync(addCommand, {
-            stdio: STDIO_MODES.INHERIT,
-            cwd: process.cwd(),
-        });
-        console.log(`\n${LOG_PREFIX} ✅ Upgrade complete!`);
-        console.log(`${LOG_PREFIX} Upgraded to ${versionSpec}`);
-        console.log(`\n${LOG_PREFIX} Next steps:`);
-        console.log(`  1. Run 'pnpm build' to rebuild with new versions`);
-        console.log(`  2. Run 'pnpm gates' to verify everything works`);
-        console.log(`  3. Commit the changes`);
+        await executeUpgradeInMicroWorktree(args);
     }
     catch (error) {
-        console.error(`\n${LOG_PREFIX} ❌ Upgrade failed`);
-        console.error(`${LOG_PREFIX} Check the error above and try again.`);
+        console.error(`\n${LOG_PREFIX} Upgrade failed`);
+        console.error(`${LOG_PREFIX} ${error instanceof Error ? error.message : String(error)}`);
         process.exit(EXIT_CODES.ERROR);
     }
 }

package/dist/sync-templates.js

@@ -0,0 +1,212 @@
+/**
+ * @file sync-templates.ts
+ * Sync internal docs to CLI templates for release-cycle maintenance (WU-1123)
+ *
+ * This script syncs source docs from the hellmai/os repo to the templates
+ * directory, applying template variable substitutions:
+ * - Onboarding docs -> templates/core/ai/onboarding/
+ * - Claude skills -> templates/vendors/claude/.claude/skills/
+ * - Core docs (LUMENFLOW.md, constraints.md) -> templates/core/
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { createWUParser } from '@lumenflow/core';
+// Template variable patterns
+const DATE_PATTERN = /\d{4}-\d{2}-\d{2}/g;
+/**
+ * CLI option definitions for sync-templates command
+ */
+const SYNC_TEMPLATES_OPTIONS = {
+    dryRun: {
+        name: 'dry-run',
+        flags: '--dry-run',
+        description: 'Show what would be synced without writing files',
+        default: false,
+    },
+    verbose: {
+        name: 'verbose',
+        flags: '--verbose',
+        description: 'Show detailed output',
+        default: false,
+    },
+};
+/**
+ * Parse sync-templates command options
+ */
+export function parseSyncTemplatesOptions() {
+    const opts = createWUParser({
+        name: 'sync-templates',
+        description: 'Sync internal docs to CLI templates for release-cycle maintenance',
+        options: Object.values(SYNC_TEMPLATES_OPTIONS),
+    });
+    return {
+        dryRun: opts['dry-run'] ?? false,
+        verbose: opts.verbose ?? false,
+    };
+}
+/**
+ * Convert source content to template format by replacing:
+ * - YYYY-MM-DD dates with {{DATE}}
+ * - Absolute project paths with {{PROJECT_ROOT}}
+ */
+export function convertToTemplate(content, projectRoot) {
+    let output = content;
+    // Replace dates with {{DATE}}
+    output = output.replace(DATE_PATTERN, '{{DATE}}');
+    // Replace absolute project paths with {{PROJECT_ROOT}}
+    // Escape special regex characters in the path
+    const escapedPath = projectRoot.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const pathPattern = new RegExp(escapedPath, 'g');
+    output = output.replace(pathPattern, '{{PROJECT_ROOT}}');
+    return output;
+}
+/**
+ * Get the templates directory path
+ */
+function getTemplatesDir(projectRoot) {
+    return path.join(projectRoot, 'packages', '@lumenflow', 'cli', 'templates');
+}
+/**
+ * Ensure directory exists
+ */
+function ensureDir(dirPath) {
+    if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true });
+    }
+}
+/**
+ * Sync a single file to templates
+ */
+function syncFile(sourcePath, targetPath, projectRoot, result, dryRun = false) {
+    try {
+        if (!fs.existsSync(sourcePath)) {
+            result.errors.push(`Source not found: ${sourcePath}`);
+            return;
+        }
+        const content = fs.readFileSync(sourcePath, 'utf-8');
+        const templateContent = convertToTemplate(content, projectRoot);
+        if (!dryRun) {
+            ensureDir(path.dirname(targetPath));
+            fs.writeFileSync(targetPath, templateContent);
+        }
+        result.synced.push(path.relative(projectRoot, targetPath));
+    }
+    catch (error) {
+        result.errors.push(`Error syncing ${sourcePath}: ${error.message}`);
+    }
+}
+/**
+ * Sync onboarding docs to templates/core/ai/onboarding/
+ */
+export async function syncOnboardingDocs(projectRoot, dryRun = false) {
+    const result = { synced: [], errors: [] };
+    const sourceDir = path.join(projectRoot, 'docs', '04-operations', '_frameworks', 'lumenflow', 'agent', 'onboarding');
+    const targetDir = path.join(getTemplatesDir(projectRoot), 'core', 'ai', 'onboarding');
+    if (!fs.existsSync(sourceDir)) {
+        result.errors.push(`Onboarding source directory not found: ${sourceDir}`);
+        return result;
+    }
+    const files = fs.readdirSync(sourceDir).filter((f) => f.endsWith('.md'));
+    for (const file of files) {
+        const sourcePath = path.join(sourceDir, file);
+        const targetPath = path.join(targetDir, `${file}.template`);
+        syncFile(sourcePath, targetPath, projectRoot, result, dryRun);
+    }
+    return result;
+}
+/**
+ * Sync Claude skills to templates/vendors/claude/.claude/skills/
+ */
+export async function syncSkillsToTemplates(projectRoot, dryRun = false) {
+    const result = { synced: [], errors: [] };
+    const sourceDir = path.join(projectRoot, '.claude', 'skills');
+    const targetDir = path.join(getTemplatesDir(projectRoot), 'vendors', 'claude', '.claude', 'skills');
+    if (!fs.existsSync(sourceDir)) {
+        result.errors.push(`Skills source directory not found: ${sourceDir}`);
+        return result;
+    }
+    // Get all skill directories
+    const skillDirs = fs
+        .readdirSync(sourceDir, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name);
+    for (const skillName of skillDirs) {
+        const skillSourceDir = path.join(sourceDir, skillName);
+        const skillTargetDir = path.join(targetDir, skillName);
+        // Look for SKILL.md file
+        const skillFile = path.join(skillSourceDir, 'SKILL.md');
+        if (fs.existsSync(skillFile)) {
+            const targetPath = path.join(skillTargetDir, 'SKILL.md.template');
+            syncFile(skillFile, targetPath, projectRoot, result, dryRun);
+        }
+    }
+    return result;
+}
+/**
+ * Sync core docs (LUMENFLOW.md, constraints.md) to templates/core/
+ */
+export async function syncCoreDocs(projectRoot, dryRun = false) {
+    const result = { synced: [], errors: [] };
+    const templatesDir = getTemplatesDir(projectRoot);
+    // Sync LUMENFLOW.md
+    const lumenflowSource = path.join(projectRoot, 'LUMENFLOW.md');
+    const lumenflowTarget = path.join(templatesDir, 'core', 'LUMENFLOW.md.template');
+    syncFile(lumenflowSource, lumenflowTarget, projectRoot, result, dryRun);
+    // Sync constraints.md
+    const constraintsSource = path.join(projectRoot, '.lumenflow', 'constraints.md');
+    const constraintsTarget = path.join(templatesDir, 'core', '.lumenflow', 'constraints.md.template');
+    syncFile(constraintsSource, constraintsTarget, projectRoot, result, dryRun);
+    return result;
+}
+/**
+ * Sync all templates
+ */
+export async function syncTemplates(projectRoot, dryRun = false) {
+    const onboarding = await syncOnboardingDocs(projectRoot, dryRun);
+    const skills = await syncSkillsToTemplates(projectRoot, dryRun);
+    const core = await syncCoreDocs(projectRoot, dryRun);
+    return { onboarding, skills, core };
+}
+/**
+ * CLI entry point
+ */
+export async function main() {
+    const opts = parseSyncTemplatesOptions();
+    const projectRoot = process.cwd();
+    console.log('[sync-templates] Syncing internal docs to CLI templates...');
+    if (opts.dryRun) {
+        console.log('  (dry-run mode - no files will be written)');
+    }
+    const result = await syncTemplates(projectRoot, opts.dryRun);
+    // Print results
+    const sections = [
+        { name: 'Onboarding docs', data: result.onboarding },
+        { name: 'Claude skills', data: result.skills },
+        { name: 'Core docs', data: result.core },
+    ];
+    let totalSynced = 0;
+    let totalErrors = 0;
+    for (const section of sections) {
+        if (section.data.synced.length > 0 || section.data.errors.length > 0) {
+            console.log(`\n${section.name}:`);
+            if (section.data.synced.length > 0) {
+                section.data.synced.forEach((f) => console.log(`  + ${f}`));
+                totalSynced += section.data.synced.length;
+            }
+            if (section.data.errors.length > 0) {
+                section.data.errors.forEach((e) => console.log(`  ! ${e}`));
+                totalErrors += section.data.errors.length;
+            }
+        }
+    }
+    console.log(`\n[sync-templates] Done! Synced ${totalSynced} files.`);
+    if (totalErrors > 0) {
+        console.log(`  ${totalErrors} error(s) occurred.`);
+        process.exitCode = 1;
+    }
+}
+// CLI entry point
+import { runCLI } from './cli-entry-point.js';
+if (import.meta.main) {
+    runCLI(main);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/cli",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "description": "Command-line interface for LumenFlow workflow framework",
   "keywords": [
     "lumenflow",
@@ -89,6 +89,8 @@
     "lumenflow": "./dist/init.js",
     "lumenflow-release": "./dist/release.js",
     "lumenflow-docs-sync": "./dist/docs-sync.js",
+    "lumenflow-sync-templates": "./dist/sync-templates.js",
+    "sync-templates": "./dist/sync-templates.js",
     "backlog-prune": "./dist/backlog-prune.js",
     "file-read": "./dist/file-read.js",
     "file-write": "./dist/file-write.js",
@@ -130,11 +132,11 @@
     "pretty-ms": "^9.2.0",
     "simple-git": "^3.30.0",
     "yaml": "^2.8.2",
-    "@lumenflow/memory": "2.0.0",
-    "@lumenflow/metrics": "1.6.0",
-    "@lumenflow/core": "2.0.0",
-    "@lumenflow/initiatives": "2.0.0",
-    "@lumenflow/agent": "2.0.0"
+    "@lumenflow/core": "2.1.1",
+    "@lumenflow/metrics": "2.1.1",
+    "@lumenflow/memory": "2.1.1",
+    "@lumenflow/initiatives": "2.1.1",
+    "@lumenflow/agent": "2.1.1"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.17",