@lumenflow/cli 1.0.0 → 1.3.0

package/dist/init.js

@@ -0,0 +1,297 @@
+/**
+ * @file init.ts
+ * LumenFlow project scaffolding command (WU-1045)
+ * WU-1006: Library-First - use core defaults for config generation
+ * WU-1028: Vendor-agnostic core + vendor overlays
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as yaml from 'yaml';
+import { getDefaultConfig } from '@lumenflow/core';
+const CONFIG_FILE_NAME = '.lumenflow.config.yaml';
+const FRAMEWORK_HINT_FILE = '.lumenflow.framework.yaml';
+const LUMENFLOW_DIR = '.lumenflow';
+const LUMENFLOW_AGENTS_DIR = `${LUMENFLOW_DIR}/agents`;
+const CLAUDE_DIR = '.claude';
+const CLAUDE_AGENTS_DIR = path.join(CLAUDE_DIR, 'agents');
+/**
+ * Generate YAML configuration with header comment
+ */
+function generateLumenflowConfigYaml() {
+    const header = `# LumenFlow Configuration\n# Generated by: lumenflow init\n# Customize paths based on your project structure\n\n`;
+    const config = getDefaultConfig();
+    config.directories.agentsDir = LUMENFLOW_AGENTS_DIR;
+    return header + yaml.stringify(config);
+}
+/**
+ * Get current date in YYYY-MM-DD format
+ */
+function getCurrentDate() {
+    return new Date().toISOString().split('T')[0];
+}
+/**
+ * Normalize a framework name into display + slug
+ */
+function normalizeFrameworkName(framework) {
+    const name = framework.trim();
+    const slug = name
+        .toLowerCase()
+        .replace(/[^a-z0-9-_]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    if (!slug) {
+        throw new Error(`Invalid framework name: "${framework}"`);
+    }
+    return { name, slug };
+}
+/**
+ * Process template content by replacing placeholders
+ */
+function processTemplate(content, tokens) {
+    let output = content;
+    for (const [key, value] of Object.entries(tokens)) {
+        output = output.replace(new RegExp(`\\{\\{${key}\\}\\}`, 'g'), value);
+    }
+    return output;
+}
+function getRelativePath(targetDir, filePath) {
+    return path.relative(targetDir, filePath).split(path.sep).join('/');
+}
+// Template for LUMENFLOW.md (main entry point)
+const LUMENFLOW_MD_TEMPLATE = `# LumenFlow Workflow Guide\n\n**Last updated:** {{DATE}}\n\nLumenFlow is a vendor-agnostic workflow framework for AI-native software development.\n\n---\n\n## Critical Rule: ALWAYS Run wu:done\n\n**After completing work on a WU, you MUST run \`pnpm wu:done --id WU-XXXX\` from the main checkout.**\n\nThis is the single most forgotten step. Do NOT:\n- Write "To Complete: pnpm wu:done" and stop\n- Ask if you should run wu:done\n- Forget to run wu:done\n\n**DO**: Run \`pnpm wu:done --id WU-XXXX\` immediately after gates pass.\n\n---\n\n## Quick Start\n\n\`\`\`bash\n# 1. Create a WU\npnpm wu:create --id WU-XXXX --lane <Lane> --title "Title"\n\n# 2. Edit WU spec with acceptance criteria, then claim:\npnpm wu:claim --id WU-XXXX --lane <Lane>\ncd worktrees/<lane>-wu-xxxx\n\n# 3. Implement in worktree\n\n# 4. Run gates\npnpm gates --docs-only  # for docs changes\npnpm gates              # for code changes\n\n# 5. Complete (from main checkout)\ncd {{PROJECT_ROOT}}\npnpm wu:done --id WU-XXXX\n\`\`\`\n\n---\n\n## Core Principles\n\n1. **TDD**: Failing test -> implementation -> passing test (>=90% coverage on new code)\n2. **Library-First**: Search existing libraries before custom code\n3. **DRY/SOLID/KISS/YAGNI**: No magic numbers, no hardcoded strings\n4. **Worktree Discipline**: After \`wu:claim\`, work ONLY in the worktree\n5. **Gates Before Done**: All gates must pass before \`wu:done\`\n6. **Do Not Bypass Hooks**: No \`--no-verify\`, fix issues properly\n7. **Always wu:done**: Complete every WU by running \`pnpm wu:done\`\n\n---\n\n## Documentation Structure\n\n### Core (Vendor-Agnostic)\n\n- **LUMENFLOW.md** - This file, main entry point\n- **.lumenflow/constraints.md** - Non-negotiable workflow constraints\n- **.lumenflow/agents/** - Agent instructions (vendor-agnostic)\n- **.lumenflow.config.yaml** - Workflow configuration\n\n### Optional Overlays\n\n- **CLAUDE.md + .claude/agents/** - Claude Code overlay (auto if Claude Code detected)\n- **docs/04-operations/tasks/** - Task boards and WU storage (\`lumenflow init --full\`)\n- **docs/04-operations/_frameworks/<framework>/** - Framework overlay docs (\`lumenflow init --framework <name>\`)\n- **.lumenflow.framework.yaml** - Framework hint file (created with \`--framework\`)\n\n---\n\n## Worktree Discipline (IMMUTABLE LAW)\n\nAfter claiming a WU, you MUST work in its worktree:\n\n\`\`\`bash\n# 1. Claim creates worktree\npnpm wu:claim --id WU-XXX --lane <lane>\n\n# 2. IMMEDIATELY cd to worktree\ncd worktrees/<lane>-wu-xxx\n\n# 3. ALL work happens here\n\n# 4. Return to main ONLY to complete\ncd {{PROJECT_ROOT}}\npnpm wu:done --id WU-XXX\n\`\`\`\n\n---\n\n## Definition of Done\n\n- Acceptance criteria satisfied\n- Gates green (\`pnpm gates\` or \`pnpm gates --docs-only\`)\n- WU YAML status = \`done\`\n- \`wu:done\` has been run\n\n---\n\n## Commands Reference\n\n| Command           | Description                         |\n| ----------------- | ----------------------------------- |\n| \`pnpm wu:create\` | Create new WU spec                  |\n| \`pnpm wu:claim\`  | Claim WU and create worktree        |\n| \`pnpm wu:done\`   | Complete WU (merge, stamp, cleanup) |\n| \`pnpm gates\`     | Run quality gates                   |\n\n---\n\n## Constraints\n\nSee [.lumenflow/constraints.md](.lumenflow/constraints.md) for the 6 non-negotiable rules.\n\n---\n\n## Agent Onboarding\n\n- Start with **CLAUDE.md** if present (Claude Code overlay).\n- Add vendor-agnostic guidance in **.lumenflow/agents/**.\n- Add framework-specific notes in **docs/04-operations/_frameworks/<framework>/**.\n`;
+// Template for .lumenflow/constraints.md
+const CONSTRAINTS_MD_TEMPLATE = `# LumenFlow Constraints Capsule\n\n**Version:** 1.0\n**Last updated:** {{DATE}}\n\n## The 6 Non-Negotiable Constraints\n\n### 1. Worktree Discipline and Git Safety\nWork only in worktrees, treat main as read-only, never run destructive git commands on main.\n\n### 2. WUs Are Specs, Not Code\nRespect code_paths boundaries, no feature creep, no code blocks in WU YAML files.\n\n### 3. Docs-Only vs Code WUs\nDocumentation WUs use \`--docs-only\` gates, code WUs run full gates.\n\n### 4. LLM-First, Zero-Fallback Inference\nUse LLMs for semantic tasks, fall back to safe defaults (never regex/keywords).\n\n### 5. Gates and Skip-Gates\nComplete via \`pnpm wu:done\`; skip-gates only for pre-existing failures with \`--reason\` and \`--fix-wu\`.\n\n### 6. Safety and Governance\nRespect privacy rules, approved sources, security policies; when uncertain, choose safer path.\n\n---\n\n## Mini Audit Checklist\n\nBefore running \`wu:done\`, verify:\n\n- [ ] Working in worktree (not main)\n- [ ] Only modified files in \`code_paths\`\n- [ ] Gates pass\n- [ ] No forbidden git commands used\n- [ ] Acceptance criteria satisfied\n\n---\n\n## Escalation Triggers\n\nStop and ask a human when:\n- Same error repeats 3 times\n- Auth or permissions changes required\n- PII/PHI/safety issues discovered\n- Cloud spend or secrets involved\n`;
+// Template for root CLAUDE.md
+const CLAUDE_MD_TEMPLATE = `# Claude Code Instructions\n\n**Last updated:** {{DATE}}\n\nThis project uses LumenFlow workflow. For workflow documentation, see [LUMENFLOW.md](LUMENFLOW.md).\n\n---\n\n## Quick Start\n\n\`\`\`bash\n# 1. Claim a WU\npnpm wu:claim --id WU-XXXX --lane <Lane>\ncd worktrees/<lane>-wu-xxxx\n\n# 2. Work in worktree, run gates\npnpm gates\n\n# 3. Complete (ALWAYS run this!)\ncd {{PROJECT_ROOT}}\npnpm wu:done --id WU-XXXX\n\`\`\`\n\n---\n\n## Critical: Always wu:done\n\nAfter completing work, ALWAYS run \`pnpm wu:done --id WU-XXXX\`.\n\nSee [LUMENFLOW.md](LUMENFLOW.md) for full workflow documentation.\n`;
+// Template for .claude/settings.json
+const CLAUDE_SETTINGS_TEMPLATE = `{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "allow": [
+      "Bash",
+      "Read",
+      "Write",
+      "Edit",
+      "WebFetch",
+      "WebSearch"
+    ],
+    "deny": [
+      "Read(./.env)",
+      "Read(./.env.*)",
+      "Write(./.env*)",
+      "Bash(git reset --hard *)",
+      "Bash(git stash *)",
+      "Bash(git clean -fd *)",
+      "Bash(git push --force *)",
+      "Bash(git push -f *)",
+      "Bash(git commit --no-verify *)",
+      "Bash(HUSKY=0 *)",
+      "Bash(rm -rf /*)",
+      "Bash(sudo *)",
+      "Bash(git worktree remove *)",
+      "Bash(git worktree prune *)"
+    ]
+  }
+}
+`;
+// Template for .cursor/rules.md
+const CURSOR_RULES_TEMPLATE = `# Cursor Rules\n\nThis project uses LumenFlow workflow. See [LUMENFLOW.md](../LUMENFLOW.md).\n\n## Critical Rules\n\n1. **Always run wu:done** - After gates pass, run \`pnpm wu:done --id WU-XXX\`\n2. **Work in worktrees** - After \`wu:claim\`, work only in the worktree\n3. **Never bypass hooks** - No \`--no-verify\`\n4. **TDD** - Write tests first\n\n## Forbidden Commands\n\n- \`git reset --hard\`\n- \`git push --force\`\n- \`git stash\` (on main)\n- \`--no-verify\`\n`;
+// Template for .aider.conf.yml
+const AIDER_CONF_TEMPLATE = `# Aider Configuration for LumenFlow Projects\n# See LUMENFLOW.md for workflow documentation\n\nmodel: gpt-4-turbo\nauto-commits: false\ndirty-commits: false\n\nread:\n  - LUMENFLOW.md\n  - .lumenflow/constraints.md\n`;
+// Template for docs/04-operations/tasks/backlog.md
+const BACKLOG_TEMPLATE = `---\nsections:\n  ready:\n    heading: '## 🚀 Ready (pull from here)'\n    insertion: after_heading_blank_line\n  in_progress:\n    heading: '## 🔧 In progress'\n    insertion: after_heading_blank_line\n  blocked:\n    heading: '## ⛔ Blocked'\n    insertion: after_heading_blank_line\n  done:\n    heading: '## ✅ Done'\n    insertion: after_heading_blank_line\n---\n\n# Backlog (single source of truth)\n\n## 🚀 Ready (pull from here)\n\n(No items ready)\n\n## 🔧 In progress\n\n(No items in progress)\n\n## ⛔ Blocked\n\n(No items blocked)\n\n## ✅ Done\n\n(No items completed yet)\n`;
+// Template for docs/04-operations/tasks/status.md
+const STATUS_TEMPLATE = `# Status (active work)\n\n## In Progress\n\n(No items in progress)\n\n## Blocked\n\n(No items blocked)\n\n## Completed\n\n(No items completed yet)\n`;
+// Template for docs/04-operations/tasks/templates/wu-template.yaml
+const WU_TEMPLATE_YAML = `# Work Unit Template (LumenFlow WU Schema)\n#\n# Copy this template when creating new WUs. Fill in all required fields and\n# remove optional fields if not needed.\n#\n# If you used "lumenflow init --full", this template lives at:\n# docs/04-operations/tasks/templates/wu-template.yaml\n\n# Required: Unique work unit identifier (format: WU-NNN)\nid: WU-XXX\n\n# Required: Short, descriptive title (max 80 chars)\ntitle: 'Your WU title here'\n\n# Required: Lane (Parent: Sublane format)\nlane: 'Framework: CLI'\n\n# Required: Type of work\ntype: 'feature' # feature | bug | documentation | process | tooling | chore | refactor\n\n# Required: Current status\nstatus: 'ready' # ready | in_progress | blocked | done | cancelled\n\n# Required: Priority\npriority: P2 # P0 | P1 | P2 | P3\n\n# Required: Creation date (YYYY-MM-DD)\ncreated: {{DATE}}\n\n# Required: Owner/assignee (email)\nassigned_to: 'unassigned@example.com'\n\n# Required: Description\ndescription: |\n  Context: ...\n  Problem: ...\n  Solution: ...\n\n# Required: Acceptance criteria (testable, binary)\nacceptance:\n  - Criterion 1 (specific, measurable, testable)\n  - Criterion 2 (binary pass/fail)\n  - Documentation updated\n\n# Required: References to plans/specs (required for type: feature)\nspec_refs:\n  - docs/04-operations/plans/WU-XXX-plan.md\n\n# Required: Code files changed or created (empty only for docs/process WUs)\ncode_paths:\n  - path/to/file.ts\n\n# Required: Test paths (at least one of manual/unit/e2e/integration for non-doc WUs)\ntests:\n  manual:\n    - Manual test: Verify behavior\n  unit:\n    - path/to/test.test.ts\n  e2e: []\n  integration: []\n\n# Required: Exposure level\nexposure: 'backend-only' # ui | api | backend-only | documentation\n\n# Optional: User journey (recommended for ui/api)\n# user_journey: |\n#   User navigates to ...\n#   User performs ...\n\n# Optional: UI pairing WUs (for api exposure)\n# ui_pairing_wus:\n#   - WU-1234\n\n# Optional: Navigation path (required when exposure=ui and no page file)\n# navigation_path: '/settings'\n\n# Required: Deliverable artifacts (stamps, docs, etc.)\nartifacts:\n  - .beacon/stamps/WU-XXX.done\n\n# Optional: Dependencies (other WUs that must complete first)\ndependencies: []\n\n# Optional: Risks\nrisks:\n  - Risk 1\n\n# Optional: Notes\nnotes: ''\n\n# Optional: Requires human review\nrequires_review: false\n\n# Optional: Claimed mode (worktree or branch-only)\n# Automatically set by wu:claim, usually don't need to specify\n# claimed_mode: worktree\n\n# Optional: Assigned to (email of current claimant)\n# Automatically set by wu:claim\n# assigned_to: engineer@example.com\n\n# Optional: Locked status (prevents concurrent edits)\n# Automatically set by wu:claim and wu:done\n# locked: false\n\n# Optional: Completion date (ISO 8601 format)\n# Automatically set by wu:done\n# completed: 2025-10-23\n\n# Optional: Completion notes (added by wu:done)\n# completion_notes: |\n#   Additional notes added during wu:done.\n#   Any deviations from original plan.\n#   Lessons learned.\n\n# ============================================================================\n# GOVERNANCE BLOCK (WU Schema v2.0)\n# ============================================================================\n# Optional: COS governance rules that apply to this WU\n# Only include if this WU needs specific governance enforcement\n\n# governance:\n#   # Rules that apply to this WU (evaluated during cos:gates)\n#   rules:\n#     - rule_id: UPAIN-01\n#       satisfied: false  # Initially false, set true when evidence provided\n#       evidence:\n#         - type: link\n#           value: docs/product/voc/feature-user-pain.md\n#           description: "Voice of Customer analysis showing user pain"\n#       notes: |\n#         VOC analysis shows 40% of support tickets request this feature.\n#         Average time wasted: 15min/user/week.\n#\n#     - rule_id: CASH-03\n#       satisfied: false\n#       evidence:\n#         - type: link\n#           value: docs/finance/spend-reviews/2025-10-cloud-infra.md\n#           description: "Spend review for £1200/month cloud infrastructure"\n#         - type: approval\n#           value: owner@example.com\n#           description: "Owner approval for spend commitment"\n#       notes: |\n#         New cloud infrastructure commitment: £1200/month for 12 months.\n#         ROI: Reduces latency by 50%, improves user retention.\n#\n#   # Gate checks (enforced by cos-gates.mjs)\n#   gates:\n#     narrative: "pending"  # Status: pending, passed, skipped, failed\n#     finance: "pending"\n#\n#   # Exemptions (only if rule doesn't apply)\n#   exemptions:\n#     - rule_id: FAIR-01\n#       reason: "No user-facing pricing changes in this WU"\n#       approved_by: product-owner@example.com\n#       approved_at: 2025-10-23\n\n# ============================================================================\n# USAGE NOTES\n# ============================================================================\n#\n# 1. Remove this entire governance block if no COS rules apply to your WU\n# 2. Only include rules that require enforcement (not all rules apply to all WUs)\n# 3. Evidence types: link:, metric:, screenshot:, approval:\n# 4. Gates are checked during wu:done (before merge)\n# 5. Exemptions require approval from rule owner\n#\n# For more details, see:\n# - docs/04-operations/_frameworks/cos/system-prompt-v1.3.md\n# - docs/04-operations/_frameworks/cos/evidence-format.md\n`;
+// Template for .lumenflow.framework.yaml
+const FRAMEWORK_HINT_TEMPLATE = `# LumenFlow Framework Hint\n# Generated by: lumenflow init --framework {{FRAMEWORK_NAME}}\n\nframework: "{{FRAMEWORK_NAME}}"\nslug: "{{FRAMEWORK_SLUG}}"\n`;
+// Template for docs/04-operations/_frameworks/<framework>/README.md
+const FRAMEWORK_OVERLAY_TEMPLATE = `# {{FRAMEWORK_NAME}} Framework Overlay\n\n**Last updated:** {{DATE}}\n\nThis overlay captures framework-specific conventions, constraints, and references for {{FRAMEWORK_NAME}} projects.\n\n## Scope\n\n- Project structure conventions\n- Framework-specific testing guidance\n- Common pitfalls and mitigations\n\n## References\n\n- Add official docs links here\n`;
+/**
+ * Detect default client from environment
+ */
+function detectDefaultClient() {
+    if (process.env.CLAUDE_PROJECT_DIR || process.env.CLAUDE_CODE) {
+        return 'claude-code';
+    }
+    return 'none';
+}
+/**
+ * Parse vendor flag from arguments
+ */
+function parseVendorArg(args) {
+    const vendorIndex = args.findIndex((arg) => arg === '--vendor');
+    if (vendorIndex !== -1 && args[vendorIndex + 1]) {
+        const vendor = args[vendorIndex + 1].toLowerCase();
+        if (['claude', 'cursor', 'aider', 'all', 'none'].includes(vendor)) {
+            return vendor;
+        }
+    }
+    return undefined;
+}
+/**
+ * Parse framework flag from arguments
+ */
+function parseFrameworkArg(args) {
+    const frameworkArg = args.find((arg) => arg.startsWith('--framework='));
+    if (frameworkArg) {
+        const [, value] = frameworkArg.split('=', 2);
+        return value?.trim() || undefined;
+    }
+    const frameworkIndex = args.findIndex((arg) => arg === '--framework');
+    if (frameworkIndex !== -1 && args[frameworkIndex + 1]) {
+        return args[frameworkIndex + 1];
+    }
+    return undefined;
+}
+function shouldUseVendor(vendor, defaultClient) {
+    if (vendor) {
+        return vendor;
+    }
+    return defaultClient === 'claude-code' ? 'claude' : 'none';
+}
+/**
+ * Scaffold a new LumenFlow project
+ */
+export async function scaffoldProject(targetDir, options) {
+    const result = {
+        created: [],
+        skipped: [],
+    };
+    const defaultClient = options.defaultClient ?? detectDefaultClient();
+    const vendor = shouldUseVendor(options.vendor, defaultClient);
+    // Ensure target directory exists
+    if (!fs.existsSync(targetDir)) {
+        fs.mkdirSync(targetDir, { recursive: true });
+    }
+    const tokenDefaults = {
+        DATE: getCurrentDate(),
+        PROJECT_ROOT: targetDir,
+    };
+    // Create .lumenflow.config.yaml
+    await createFile(path.join(targetDir, CONFIG_FILE_NAME), generateLumenflowConfigYaml(), options.force, result, targetDir);
+    // Create LUMENFLOW.md (main entry point)
+    await createFile(path.join(targetDir, 'LUMENFLOW.md'), processTemplate(LUMENFLOW_MD_TEMPLATE, tokenDefaults), options.force, result, targetDir);
+    // Create .lumenflow/constraints.md
+    await createFile(path.join(targetDir, LUMENFLOW_DIR, 'constraints.md'), processTemplate(CONSTRAINTS_MD_TEMPLATE, tokenDefaults), options.force, result, targetDir);
+    // Create .lumenflow/agents directory with .gitkeep
+    await createDirectory(path.join(targetDir, LUMENFLOW_AGENTS_DIR), result, targetDir);
+    await createFile(path.join(targetDir, LUMENFLOW_AGENTS_DIR, '.gitkeep'), '', options.force, result, targetDir);
+    // Optional: full docs scaffolding
+    if (options.full) {
+        await scaffoldFullDocs(targetDir, options, result, tokenDefaults);
+    }
+    // Optional: framework overlay
+    if (options.framework) {
+        await scaffoldFrameworkOverlay(targetDir, options, result, tokenDefaults);
+    }
+    // Scaffold vendor-specific files
+    await scaffoldVendorFiles(targetDir, options, result, tokenDefaults, vendor);
+    return result;
+}
+async function scaffoldFullDocs(targetDir, options, result, tokens) {
+    const tasksDir = path.join(targetDir, 'docs', '04-operations', 'tasks');
+    const wuDir = path.join(tasksDir, 'wu');
+    const templatesDir = path.join(tasksDir, 'templates');
+    await createDirectory(wuDir, result, targetDir);
+    await createDirectory(templatesDir, result, targetDir);
+    await createFile(path.join(wuDir, '.gitkeep'), '', options.force, result, targetDir);
+    await createFile(path.join(tasksDir, 'backlog.md'), BACKLOG_TEMPLATE, options.force, result, targetDir);
+    await createFile(path.join(tasksDir, 'status.md'), STATUS_TEMPLATE, options.force, result, targetDir);
+    await createFile(path.join(templatesDir, 'wu-template.yaml'), processTemplate(WU_TEMPLATE_YAML, tokens), options.force, result, targetDir);
+}
+async function scaffoldFrameworkOverlay(targetDir, options, result, tokens) {
+    if (!options.framework) {
+        return;
+    }
+    const { name, slug } = normalizeFrameworkName(options.framework);
+    const frameworkTokens = {
+        ...tokens,
+        FRAMEWORK_NAME: name,
+        FRAMEWORK_SLUG: slug,
+    };
+    await createFile(path.join(targetDir, FRAMEWORK_HINT_FILE), processTemplate(FRAMEWORK_HINT_TEMPLATE, frameworkTokens), options.force, result, targetDir);
+    const overlayDir = path.join(targetDir, 'docs', '04-operations', '_frameworks', slug);
+    await createDirectory(overlayDir, result, targetDir);
+    await createFile(path.join(overlayDir, 'README.md'), processTemplate(FRAMEWORK_OVERLAY_TEMPLATE, frameworkTokens), options.force, result, targetDir);
+}
+/**
+ * Scaffold vendor-specific files based on --vendor option
+ */
+async function scaffoldVendorFiles(targetDir, options, result, tokens, vendor) {
+    // Claude Code
+    if (vendor === 'claude' || vendor === 'all') {
+        await createFile(path.join(targetDir, 'CLAUDE.md'), processTemplate(CLAUDE_MD_TEMPLATE, tokens), options.force, result, targetDir);
+        await createDirectory(path.join(targetDir, CLAUDE_AGENTS_DIR), result, targetDir);
+        await createFile(path.join(targetDir, CLAUDE_AGENTS_DIR, '.gitkeep'), '', options.force, result, targetDir);
+        await createFile(path.join(targetDir, CLAUDE_DIR, 'settings.json'), CLAUDE_SETTINGS_TEMPLATE, options.force, result, targetDir);
+    }
+    // Cursor
+    if (vendor === 'cursor' || vendor === 'all') {
+        const cursorDir = path.join(targetDir, '.cursor');
+        await createDirectory(cursorDir, result, targetDir);
+        await createFile(path.join(cursorDir, 'rules.md'), processTemplate(CURSOR_RULES_TEMPLATE, tokens), options.force, result, targetDir);
+    }
+    // Aider
+    if (vendor === 'aider' || vendor === 'all') {
+        await createFile(path.join(targetDir, '.aider.conf.yml'), AIDER_CONF_TEMPLATE, options.force, result, targetDir);
+    }
+}
+/**
+ * Create a directory if missing
+ */
+async function createDirectory(dirPath, result, targetDir) {
+    if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true });
+        result.created.push(getRelativePath(targetDir, dirPath));
+    }
+}
+/**
+ * Create a file, respecting force option
+ */
+async function createFile(filePath, content, force, result, targetDir) {
+    const relativePath = getRelativePath(targetDir, filePath);
+    if (fs.existsSync(filePath) && !force) {
+        result.skipped.push(relativePath);
+        return;
+    }
+    const parentDir = path.dirname(filePath);
+    if (!fs.existsSync(parentDir)) {
+        fs.mkdirSync(parentDir, { recursive: true });
+    }
+    fs.writeFileSync(filePath, content);
+    result.created.push(relativePath);
+}
+/**
+ * CLI entry point
+ */
+export async function main() {
+    const args = process.argv.slice(2);
+    const force = args.includes('--force') || args.includes('-f');
+    const full = args.includes('--full');
+    const vendor = parseVendorArg(args);
+    const framework = parseFrameworkArg(args);
+    const targetDir = process.cwd();
+    console.log('[lumenflow init] Scaffolding LumenFlow project...');
+    console.log(`  Mode: ${full ? 'full' : 'minimal'}`);
+    console.log(`  Framework: ${framework ?? 'none'}`);
+    console.log(`  Vendor overlays: ${vendor ?? 'auto'}`);
+    const result = await scaffoldProject(targetDir, {
+        force,
+        full,
+        vendor,
+        framework,
+    });
+    if (result.created.length > 0) {
+        console.log('\nCreated:');
+        result.created.forEach((f) => console.log(`  + ${f}`));
+    }
+    if (result.skipped.length > 0) {
+        console.log('\nSkipped (already exists, use --force to overwrite):');
+        result.skipped.forEach((f) => console.log(`  - ${f}`));
+    }
+    console.log('\n[lumenflow init] Done! Next steps:');
+    console.log('  1. Review LUMENFLOW.md for workflow documentation');
+    console.log(`  2. Edit ${CONFIG_FILE_NAME} to match your project structure`);
+    console.log('  3. Run: pnpm wu:create --id WU-0001 --lane <lane> --title "First WU"');
+}

package/dist/initiative-bulk-assign-wus.js

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+/**
+ * Initiative Bulk Assign WUs CLI (WU-1018)
+ *
+ * Bulk-assigns orphaned WUs to initiatives based on lane prefix rules.
+ * Uses micro-worktree isolation for race-safe commits.
+ *
+ * Usage:
+ *   pnpm initiative:bulk-assign                              # Dry-run (default)
+ *   LUMENFLOW_ADMIN=1 pnpm initiative:bulk-assign --apply    # Apply changes
+ *   pnpm initiative:bulk-assign --config custom-config.yaml  # Custom config
+ *   pnpm initiative:bulk-assign --reconcile-initiative INIT-001
+ *
+ * @module initiative-bulk-assign-wus
+ */
+import { readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import fg from 'fast-glob';
+import { parse as parseYaml } from 'yaml';
+import { createWUParser, WU_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
+import { die } from '@lumenflow/core/dist/error-handler.js';
+import { withMicroWorktree } from '@lumenflow/core/dist/micro-worktree.js';
+/** Log prefix for console output */
+const LOG_PREFIX = '[initiative:bulk-assign]';
+/** Default lane bucket configuration path */
+const DEFAULT_CONFIG_PATH = 'tools/config/initiative-lane-buckets.yaml';
+/** WU directory relative to repo root */
+const WU_DIR = 'docs/04-operations/tasks/wu';
+/** Initiative directory relative to repo root */
+const INIT_DIR = 'docs/04-operations/tasks/initiatives';
+/** Environment variable required for apply mode */
+const ADMIN_ENV_VAR = 'LUMENFLOW_ADMIN';
+/** Micro-worktree operation name */
+const OPERATION_NAME = 'initiative-bulk-assign';
+/**
+ * Load lane bucket configuration
+ */
+async function loadConfig(configPath) {
+    const fullPath = join(process.cwd(), configPath);
+    if (!existsSync(fullPath)) {
+        console.log(`${LOG_PREFIX} Config not found: ${configPath}`);
+        console.log(`${LOG_PREFIX} Using empty rules (no auto-assignment)`);
+        return { rules: [] };
+    }
+    const content = await readFile(fullPath, { encoding: 'utf-8' });
+    return parseYaml(content);
+}
+/**
+ * Scan top-level meta from WU YAML content (text-based to preserve formatting)
+ */
+function scanTopLevelMeta(text, filePath) {
+    const lines = text.split('\n');
+    let id;
+    let lane;
+    let initiative;
+    let laneLineIndex = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        // Skip comments and empty lines
+        if (trimmed.startsWith('#') || trimmed === '' || trimmed === '---') {
+            continue;
+        }
+        // Extract id
+        if (trimmed.startsWith('id:')) {
+            id = trimmed.replace('id:', '').trim();
+        }
+        // Extract lane
+        if (trimmed.startsWith('lane:')) {
+            lane = trimmed.replace('lane:', '').trim();
+            laneLineIndex = i;
+        }
+        // Extract initiative
+        if (trimmed.startsWith('initiative:')) {
+            initiative = trimmed.replace('initiative:', '').trim();
+        }
+    }
+    if (!id || !lane || laneLineIndex === -1) {
+        return null;
+    }
+    return {
+        id,
+        lane,
+        initiative,
+        filePath,
+        laneLineIndex,
+        rawContent: text,
+    };
+}
+/**
+ * Insert initiative line after lane line (text-based)
+ */
+function insertInitiativeLine(text, laneLineIndex, initiativeId) {
+    const lines = text.split('\n');
+    const initLine = `initiative: ${initiativeId}`;
+    // Insert after lane line
+    lines.splice(laneLineIndex + 1, 0, initLine);
+    return lines.join('\n');
+}
+/**
+ * Match lane against rules to find initiative
+ */
+function pickInitiativeForLane(lane, rules) {
+    for (const rule of rules) {
+        if (lane.toLowerCase().startsWith(rule.lane_prefix.toLowerCase())) {
+            return rule.initiative;
+        }
+    }
+    return null;
+}
+/**
+ * List all WU files
+ */
+async function listWUFiles() {
+    const wuDir = join(process.cwd(), WU_DIR);
+    return fg('WU-*.yaml', { cwd: wuDir, absolute: true });
+}
+/**
+ * List all initiative files
+ */
+async function listInitiativeFiles() {
+    const initDir = join(process.cwd(), INIT_DIR);
+    if (!existsSync(initDir)) {
+        return [];
+    }
+    return fg('INIT-*.yaml', { cwd: initDir, absolute: true });
+}
+/**
+ * Load WU IDs from initiative files
+ */
+async function loadInitiativeWUs() {
+    const initFiles = await listInitiativeFiles();
+    const initWUs = new Map();
+    for (const file of initFiles) {
+        try {
+            const content = await readFile(file, { encoding: 'utf-8' });
+            const init = parseYaml(content);
+            if (init.id && Array.isArray(init.wus)) {
+                initWUs.set(init.id, init.wus);
+            }
+        }
+        catch {
+            // Skip invalid initiative files
+        }
+    }
+    return initWUs;
+}
+/**
+ * Compute all changes without writing
+ */
+async function computeChanges(config) {
+    const wuFiles = await listWUFiles();
+    const initWUs = await loadInitiativeWUs();
+    const changes = [];
+    const stats = {
+        total: wuFiles.length,
+        alreadyAssigned: 0,
+        newlyAssigned: 0,
+        synced: 0,
+        skipped: 0,
+    };
+    // Build reverse lookup: WU ID -> Initiative ID
+    const wuToInit = new Map();
+    for (const [initId, wuList] of initWUs.entries()) {
+        for (const wuId of wuList) {
+            wuToInit.set(wuId, initId);
+        }
+    }
+    for (const file of wuFiles) {
+        try {
+            const content = await readFile(file, { encoding: 'utf-8' });
+            const meta = scanTopLevelMeta(content, file);
+            if (!meta) {
+                stats.skipped++;
+                continue;
+            }
+            // Check if already assigned
+            if (meta.initiative) {
+                stats.alreadyAssigned++;
+                continue;
+            }
+            // Check if initiative assigns this WU
+            const assignedInit = wuToInit.get(meta.id);
+            if (assignedInit) {
+                // Sync from initiative
+                const newContent = insertInitiativeLine(content, meta.laneLineIndex, assignedInit);
+                changes.push({
+                    wuId: meta.id,
+                    type: 'sync',
+                    initiative: assignedInit,
+                    filePath: file,
+                    newContent,
+                });
+                stats.synced++;
+                continue;
+            }
+            // Try to auto-assign by lane prefix
+            const matchedInit = pickInitiativeForLane(meta.lane, config.rules);
+            if (matchedInit) {
+                const newContent = insertInitiativeLine(content, meta.laneLineIndex, matchedInit);
+                changes.push({
+                    wuId: meta.id,
+                    type: 'assign',
+                    initiative: matchedInit,
+                    filePath: file,
+                    newContent,
+                });
+                stats.newlyAssigned++;
+            }
+            else {
+                stats.skipped++;
+            }
+        }
+        catch {
+            stats.skipped++;
+        }
+    }
+    return { changes, stats };
+}
+/**
+ * Print summary of changes
+ */
+function printSummary(stats) {
+    console.log('');
+    console.log('═══════════════════════════════════════════════════════════════');
+    console.log('  BULK ASSIGNMENT SUMMARY');
+    console.log('═══════════════════════════════════════════════════════════════');
+    console.log(`  Total WUs scanned:       ${stats.total}`);
+    console.log(`  Already assigned:        ${stats.alreadyAssigned}`);
+    console.log(`  Synced from initiatives: ${stats.synced}`);
+    console.log(`  Newly assigned by lane:  ${stats.newlyAssigned}`);
+    console.log(`  Skipped (no match):      ${stats.skipped}`);
+    console.log('═══════════════════════════════════════════════════════════════');
+    console.log('');
+}
+/**
+ * Main function
+ */
+async function main() {
+    const args = createWUParser({
+        name: 'initiative-bulk-assign-wus',
+        description: 'Bulk-assign orphaned WUs to initiatives based on lane prefix rules',
+        options: [WU_OPTIONS.config, WU_OPTIONS.apply, WU_OPTIONS.syncFromInitiative],
+        required: [],
+    });
+    const configPath = args.config || DEFAULT_CONFIG_PATH;
+    const applyMode = args.apply === true;
+    console.log(`${LOG_PREFIX} Bulk assign WUs to initiatives`);
+    console.log(`${LOG_PREFIX} Config: ${configPath}`);
+    console.log(`${LOG_PREFIX} Mode: ${applyMode ? 'APPLY' : 'dry-run'}`);
+    // Check admin mode for apply
+    if (applyMode && process.env[ADMIN_ENV_VAR] !== '1') {
+        die(`Apply mode requires ${ADMIN_ENV_VAR}=1 environment variable.\n\n` +
+            `This prevents accidental use by agents.\n\n` +
+            `Usage: ${ADMIN_ENV_VAR}=1 pnpm initiative:bulk-assign --apply`);
+    }
+    // Load configuration
+    const config = await loadConfig(configPath);
+    console.log(`${LOG_PREFIX} Loaded ${config.rules.length} lane assignment rules`);
+    // Compute changes
+    console.log(`${LOG_PREFIX} Scanning WUs...`);
+    const { changes, stats } = await computeChanges(config);
+    // Print summary
+    printSummary(stats);
+    if (changes.length === 0) {
+        console.log(`${LOG_PREFIX} No changes to apply.`);
+        return;
+    }
+    // Show changes
+    console.log(`${LOG_PREFIX} Changes to apply (${changes.length}):`);
+    for (const change of changes) {
+        const icon = change.type === 'sync' ? '↻' : '→';
+        console.log(`  ${icon} ${change.wuId} ${change.type} ${change.initiative}`);
+    }
+    if (!applyMode) {
+        console.log('');
+        console.log(`${LOG_PREFIX} Dry-run complete. Use --apply to write changes.`);
+        console.log(`${LOG_PREFIX}   ${ADMIN_ENV_VAR}=1 pnpm initiative:bulk-assign --apply`);
+        return;
+    }
+    // Apply changes via micro-worktree
+    console.log('');
+    console.log(`${LOG_PREFIX} Applying changes via micro-worktree...`);
+    await withMicroWorktree({
+        operation: OPERATION_NAME,
+        id: `bulk-${Date.now()}`,
+        logPrefix: LOG_PREFIX,
+        execute: async ({ worktreePath }) => {
+            const filesChanged = [];
+            for (const change of changes) {
+                if (!change.newContent)
+                    continue;
+                // Calculate relative path from repo root
+                const relativePath = change.filePath.replace(process.cwd() + '/', '');
+                const worktreeFilePath = join(worktreePath, relativePath);
+                await writeFile(worktreeFilePath, change.newContent, { encoding: 'utf-8' });
+                filesChanged.push(relativePath);
+            }
+            const commitMessage = `chore: bulk-assign ${changes.length} WUs to initiatives\n\nAuto-assigned by initiative-bulk-assign-wus`;
+            return {
+                commitMessage,
+                files: filesChanged,
+            };
+        },
+    });
+    console.log(`${LOG_PREFIX} ✅ Successfully applied ${changes.length} changes`);
+}
+// Guard main() for testability (WU-1366)
+import { fileURLToPath } from 'node:url';
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    main().catch((err) => {
+        die(`Bulk assign failed: ${err.message}`);
+    });
+}

package/dist/initiative-create.js

@@ -30,11 +30,11 @@ import { getGitForCwd } from '@lumenflow/core/dist/git-adapter.js';
 import { die } from '@lumenflow/core/dist/error-handler.js';
 import { existsSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
-import yaml from 'js-yaml';
+import { stringifyYAML } from '@lumenflow/core/dist/wu-yaml.js';
 import { createWUParser, WU_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
 import { INIT_PATHS } from '@lumenflow/initiatives/dist/initiative-paths.js';
 import { INIT_PATTERNS, INIT_COMMIT_FORMATS, INIT_DEFAULTS, } from '@lumenflow/initiatives/dist/initiative-constants.js';
-import { FILE_SYSTEM, YAML_OPTIONS } from '@lumenflow/core/dist/wu-constants.js';
+import { FILE_SYSTEM } from '@lumenflow/core/dist/wu-constants.js';
 import { ensureOnMain } from '@lumenflow/core/dist/wu-helpers.js';
 import { withMicroWorktree } from '@lumenflow/core/dist/micro-worktree.js';
 // WU-1428: Use date-utils for consistent YYYY-MM-DD format (library-first)
@@ -97,11 +97,7 @@ function createInitiativeYamlInWorktree(worktreePath, id, slug, title, options =
         success_metrics: [],
         labels: [],
     };
-    const yamlContent = yaml.dump(initContent, {
-        lineWidth: YAML_OPTIONS.LINE_WIDTH,
-        quotingType: '"',
-        forceQuotes: false,
-    });
+    const yamlContent = stringifyYAML(initContent);
     writeFileSync(initAbsolutePath, yamlContent, { encoding: FILE_SYSTEM.UTF8 });
     console.log(`${LOG_PREFIX} ✅ Created ${id}.yaml in micro-worktree`);
     return initRelativePath;