@lumenflow/cli 2.2.2 → 2.3.1

package/dist/wu-status.js

@@ -180,9 +180,10 @@ async function main() {
     // Exit with appropriate code
     process.exit(getStatusExitCode(context));
 }
-// Guard main() for testability
-import { fileURLToPath } from 'node:url';
+// WU-1181: Use import.meta.main instead of process.argv[1] comparison
+// The old pattern fails with pnpm symlinks because process.argv[1] is the symlink
+// path but import.meta.url resolves to the real path - they never match
 import { runCLI } from './cli-entry-point.js';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
+if (import.meta.main) {
     runCLI(main);
 }

package/dist/wu-unblock.js

@@ -32,13 +32,13 @@ import { withMicroWorktree } from '@lumenflow/core/dist/micro-worktree.js';
 import { WUStateStore } from '@lumenflow/core/dist/wu-state-store.js';
 // WU-1574: Import backlog generator to replace BacklogManager
 import { generateBacklog, generateStatus } from '@lumenflow/core/dist/backlog-generator.js';
-// ensureOnMain() moved to wu-helpers.mjs (WU-1256)
-// ensureStaged() moved to git-staged-validator.mjs (WU-1341)
-// defaultWorktreeFrom() moved to wu-paths.mjs (WU-1341)
+// ensureOnMain() moved to wu-helpers.ts (WU-1256)
+// ensureStaged() moved to git-staged-validator.ts (WU-1341)
+// defaultWorktreeFrom() moved to wu-paths.ts (WU-1341)
 const PREFIX = LOG_PREFIX.UNBLOCK;
 // WU-1574: Removed legacy backlog manipulation functions
 // All backlog/status updates now use WUStateStore + backlog generator
-// defaultBranchFrom() consolidated to wu-done-validators.mjs (emergency fix)
+// defaultBranchFrom() consolidated to wu-done-validators.ts (emergency fix)
 function branchExists(branch) {
     try {
         getGitForCwd().run(`git rev-parse --verify ${JSON.stringify(branch)}`);
@@ -64,7 +64,7 @@ function createWorktree(doc, worktreePath, branchName) {
         getGitForCwd().run(`git worktree add ${JSON.stringify(worktreePath)} -b ${JSON.stringify(branchName)} ${GIT_REFS.ORIGIN_MAIN}`);
     }
 }
-// emitTelemetry() moved to telemetry.mjs as emitWUFlowEvent() (WU-1256)
+// emitTelemetry() moved to telemetry.ts as emitWUFlowEvent() (WU-1256)
 /**
  * Handle lane occupancy check and enforce WIP=1 policy
  */

package/dist/wu-unlock-lane.js

@@ -155,9 +155,10 @@ async function main() {
     console.log(`${PREFIX} Previous owner: ${result.previousLock?.wuId || 'unknown'}`);
     console.log(`${PREFIX} Reason: ${result.reason}`);
 }
-// Guard main() for testability (WU-1064)
-import { fileURLToPath } from 'node:url';
+// WU-1181: Use import.meta.main instead of process.argv[1] comparison
+// The old pattern fails with pnpm symlinks because process.argv[1] is the symlink
+// path but import.meta.url resolves to the real path - they never match
 import { runCLI } from './cli-entry-point.js';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
+if (import.meta.main) {
     runCLI(main);
 }

package/dist/wu-validate.js

@@ -11,7 +11,7 @@
  *   pnpm wu:validate --all               # Validate all WUs
  *   pnpm wu:validate --all --strict      # Fail on warnings too
  *
- * @see {@link tools/lib/wu-schema.mjs} - Schema definitions
+ * @see {@link packages/@lumenflow/cli/src/lib/wu-schema.ts} - Schema definitions
  */
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import path from 'node:path';
@@ -186,9 +186,10 @@ async function main() {
         }
     }
 }
-// Guard main() for testability
-import { fileURLToPath } from 'node:url';
+// WU-1181: Use import.meta.main instead of process.argv[1] comparison
+// The old pattern fails with pnpm symlinks because process.argv[1] is the symlink
+// path but import.meta.url resolves to the real path - they never match
 import { runCLI } from './cli-entry-point.js';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
+if (import.meta.main) {
     runCLI(main);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/cli",
-  "version": "2.2.2",
+  "version": "2.3.1",
   "description": "Command-line interface for LumenFlow workflow framework",
   "keywords": [
     "lumenflow",
@@ -36,6 +36,7 @@
   "bin": {
     "wu-claim": "./dist/wu-claim.js",
     "wu-done": "./dist/wu-done.js",
+    "wu-prep": "./dist/wu-prep.js",
     "wu-block": "./dist/wu-block.js",
     "wu-unblock": "./dist/wu-unblock.js",
     "wu-create": "./dist/wu-create.js",
@@ -60,10 +61,12 @@
     "mem-export": "./dist/mem-export.js",
     "mem-signal": "./dist/mem-signal.js",
     "mem-cleanup": "./dist/mem-cleanup.js",
+    "signal-cleanup": "./dist/signal-cleanup.js",
     "mem-create": "./dist/mem-create.js",
     "mem-inbox": "./dist/mem-inbox.js",
     "mem-summarize": "./dist/mem-summarize.js",
     "mem-triage": "./dist/mem-triage.js",
+    "mem-delete": "./dist/mem-delete.js",
     "initiative-create": "./dist/initiative-create.js",
     "initiative-edit": "./dist/initiative-edit.js",
     "initiative-list": "./dist/initiative-list.js",
@@ -88,6 +91,7 @@
     "lumenflow-gates": "./dist/gates.js",
     "lumenflow-init": "./dist/init.js",
     "lumenflow": "./dist/init.js",
+    "lumenflow-doctor": "./dist/doctor.js",
     "lumenflow-release": "./dist/release.js",
     "lumenflow-docs-sync": "./dist/docs-sync.js",
     "lumenflow-sync-templates": "./dist/sync-templates.js",
@@ -116,10 +120,15 @@
     "git-log": "./dist/git-log.js",
     "git-branch": "./dist/git-branch.js",
     "guard-main-branch": "./dist/guard-main-branch.js",
-    "state-bootstrap": "./dist/state-bootstrap.js"
+    "state-bootstrap": "./dist/state-bootstrap.js",
+    "lane-health": "./dist/lane-health.js",
+    "lane-suggest": "./dist/lane-suggest.js",
+    "state-cleanup": "./dist/state-cleanup.js",
+    "state-doctor": "./dist/state-doctor.js"
   },
   "files": [
     "dist",
+    "templates",
     "LICENSE",
     "README.md"
   ],
@@ -133,11 +142,11 @@
     "pretty-ms": "^9.2.0",
     "simple-git": "^3.30.0",
     "yaml": "^2.8.2",
-    "@lumenflow/core": "2.2.2",
-    "@lumenflow/metrics": "2.2.2",
-    "@lumenflow/memory": "2.2.2",
-    "@lumenflow/initiatives": "2.2.2",
-    "@lumenflow/agent": "2.2.2"
+    "@lumenflow/core": "2.3.1",
+    "@lumenflow/metrics": "2.3.1",
+    "@lumenflow/memory": "2.3.1",
+    "@lumenflow/agent": "2.3.1",
+    "@lumenflow/initiatives": "2.3.1"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.17",

package/templates/core/.lumenflow/constraints.md.template

@@ -0,0 +1,192 @@
+# LumenFlow Constraints Capsule
+
+**Version:** 1.0
+**Last updated:** {{DATE}}
+
+This document contains the 6 non-negotiable constraints that every agent must keep "in working memory" from first plan through `wu:done`.
+
+---
+
+## The 6 Non-Negotiable Constraints
+
+### 1. Worktree Discipline and Git Safety
+
+**Rule:** Work only in worktrees, treat main as read-only, never run destructive git commands on main.
+
+**Enforcement:**
+
+- After `pnpm wu:claim`, immediately `cd worktrees/<lane>-wu-xxx`
+- Hooks block WU commits from main checkout
+- Forbidden commands on main: `git reset --hard`, `git stash`, `git clean -fd`, `git push --force`
+
+**Why:** Worktree isolation prevents cross-contamination between parallel WUs and protects the main branch.
+
+---
+
+### 2. WUs Are Specs, Not Code
+
+**Rule:** Respect code_paths boundaries, no feature creep, no code blocks in WU YAML files.
+
+**Enforcement:**
+
+- Only modify files listed in `code_paths`
+- WU YAML contains acceptance criteria, not implementation code
+- Scope discipline: implement only what the spec requires
+
+**Why:** WUs define WHAT to build, not HOW. Implementation decisions belong in code, not specs.
+
+---
+
+### 3. Docs-Only vs Code WUs
+
+**Rule:** Documentation WUs use `--docs-only` gates, code WUs run full gates.
+
+**Enforcement:**
+
+- `type: documentation` in WU YAML triggers docs-only mode
+- `pnpm gates --docs-only` skips lint/typecheck/tests
+- Path validation prevents code files in docs WUs
+
+**Why:** Docs changes shouldn't require full test suite. Code changes must pass all gates.
+
+---
+
+### 4. LLM-First, Zero-Fallback Inference
+
+**Rule:** Use LLMs for semantic tasks, fall back to safe defaults (never regex/keywords).
+
+**Enforcement:**
+
+- Prompt-based classification for ambiguous inputs
+- Structured output parsing for LLM responses
+- No brittle keyword matching for semantic decisions
+
+**Why:** Regex and keyword matching are brittle. LLMs handle edge cases better.
+
+---
+
+### 5. Gates and Skip-Gates
+
+**Rule:** Complete via `pnpm wu:done`; skip-gates only for pre-existing failures with `--reason` and `--fix-wu`.
+
+**Enforcement:**
+
+- `pnpm wu:done` runs gates before merge
+- `--skip-gates` requires both `--reason` and `--fix-wu`
+- Skip events logged to `.lumenflow/skip-gates-audit.log`
+
+**Why:** Gates ensure quality. Skipping requires accountability and a fix plan.
+
+---
+
+### 6. Safety and Governance
+
+**Rule:** Respect privacy rules, approved sources, security policies; when uncertain, choose safer path.
+
+**Enforcement:**
+
+- No hardcoded secrets (gitleaks scanning)
+- RLS policies on sensitive data
+- Redaction before sending to LLMs
+- Stop-and-ask for auth/PII/spend changes
+
+**Why:** Safety first. Some mistakes are irreversible.
+
+---
+
+## Mini Audit Checklist
+
+Before running `wu:done`, verify:
+
+- [ ] Working in worktree (not main)
+- [ ] Only modified files in `code_paths`
+- [ ] Gates pass (`pnpm gates` or `pnpm gates --docs-only`)
+- [ ] No forbidden git commands used
+- [ ] No secrets committed
+- [ ] Acceptance criteria satisfied
+
+---
+
+## Quick Reference: Forbidden Commands
+
+These commands are blocked on main checkout:
+
+```bash
+# Data destruction
+git reset --hard
+git clean -fd
+
+# Hidden work
+git stash
+
+# History rewrite
+git push --force
+git push -f
+git rebase -i main
+
+# Bypass safety
+--no-verify
+HUSKY=0
+
+# Worktree manipulation (agents must not delete worktrees)
+git worktree remove
+git worktree prune
+```
+
+**Allowed in worktrees:** Most commands are safe in isolated worktrees on lane branches.
+
+---
+
+## Agent LUMENFLOW_FORCE Usage Policy (WU-1070)
+
+**Rule:** AI agents MUST NOT use LUMENFLOW_FORCE without explicit user approval.
+
+**Rationale:** LUMENFLOW_FORCE bypasses all git hook protections (pre-commit, pre-push, commit-msg). While legitimate for emergency human interventions, agents using it autonomously undermines the entire workflow enforcement model.
+
+**Enforcement:**
+
+- All LUMENFLOW_FORCE usage is logged to `.beacon/force-bypasses.log` (git-tracked)
+- Log format: `ISO_TIMESTAMP | HOOK_NAME | USER | BRANCH | REASON | CWD`
+- Missing `LUMENFLOW_FORCE_REASON` triggers stderr warning
+
+**Agent Escalation Path:**
+
+1. **Detect need:** Agent encounters hook blocking operation
+2. **Stop and ask:** Present situation to user with context
+3. **Get approval:** User must explicitly approve bypass with reason
+4. **Execute with audit:** Use `LUMENFLOW_FORCE_REASON="user-approved: <reason>" LUMENFLOW_FORCE=1`
+5. **Document:** Note the bypass in commit message or WU notes
+
+**Legitimate bypass scenarios:**
+
+- Fixing YAML parsing bugs in WU specs (spec infrastructure issue)
+- Emergency production hotfixes (with user present)
+- Recovering from corrupted workflow state
+- Bootstrap operations when CLI not yet built
+
+**Never bypass for:**
+
+- Skipping failing tests
+- Avoiding code review
+- Working around gate failures
+- Convenience or speed
+
+---
+
+## Context Limits
+
+**When approaching context limits, spawn a fresh agent instead of continuing after compaction.**
+
+Context compaction causes agents to lose critical rules. See [wu-sizing-guide.md](../docs/04-operations/_frameworks/lumenflow/wu-sizing-guide.md) for mandatory thresholds and the spawn-fresh protocol.
+
+---
+
+## Escalation Triggers
+
+Stop and ask a human when:
+
+- Same error repeats 3 times
+- Auth or permissions changes required
+- PII/PHI/safety issues discovered
+- Cloud spend or secrets involved
+- Policy changes needed

package/templates/core/.lumenflow/rules/git-safety.md.template

@@ -0,0 +1,27 @@
+# Git Safety Rules
+
+**Last updated:** {{DATE}}
+
+## Forbidden Commands on Main
+
+```bash
+git reset --hard
+git clean -fd
+git stash
+git push --force
+--no-verify
+```
+
+## Safe Commands
+
+```bash
+git status
+git log
+git diff
+git add .
+git commit -m "message"
+```
+
+## Merge Strategy
+
+Use `pnpm wu:done` for all merges. Never merge manually.

package/templates/core/.lumenflow/rules/wu-workflow.md.template

@@ -0,0 +1,48 @@
+# WU Workflow Rules
+
+**Last updated:** {{DATE}}
+
+## WU Lifecycle
+
+```
+ready -> in_progress -> done
+              |
+              v
+          blocked -> in_progress (unblocked)
+```
+
+## Claiming a WU
+
+```bash
+# 1. Check lane is free
+cat docs/04-operations/tasks/status.md
+
+# 2. Claim the WU (creates worktree)
+pnpm wu:claim --id WU-XXX --lane <Lane>
+
+# 3. IMMEDIATELY cd to worktree
+cd worktrees/<lane>-wu-xxx
+```
+
+## Completing a WU
+
+**CRITICAL: ALWAYS run wu:done to complete a WU.**
+
+```bash
+# 1. Ensure gates pass in worktree
+pnpm gates
+
+# 2. Return to main checkout
+cd {{PROJECT_ROOT}}
+
+# 3. Complete the WU
+pnpm wu:done --id WU-XXX
+```
+
+## Definition of Done
+
+- [ ] Acceptance criteria satisfied
+- [ ] Gates pass
+- [ ] WU YAML status = `done`
+- [ ] `.beacon/stamps/WU-<id>.done` exists
+- [ ] `pnpm wu:done` has been run

package/templates/core/AGENTS.md.template

@@ -0,0 +1,60 @@
+# Universal Agent Instructions
+
+**Last updated:** {{DATE}}
+
+This project uses LumenFlow workflow. For complete documentation, see [LUMENFLOW.md](LUMENFLOW.md).
+
+---
+
+## Quick Start
+
+```bash
+# 1. Claim a WU
+pnpm wu:claim --id WU-XXXX --lane <Lane>
+cd worktrees/<lane>-wu-xxxx
+
+# 2. Work in worktree, run gates
+pnpm gates
+
+# 3. Complete (ALWAYS run this!)
+cd {{PROJECT_ROOT}}
+pnpm wu:done --id WU-XXXX
+```
+
+> **Complete CLI reference:** See [quick-ref-commands.md](ai/onboarding/quick-ref-commands.md)
+
+---
+
+## Critical: Always wu:done
+
+After completing work, ALWAYS run `pnpm wu:done --id WU-XXXX` from the main checkout.
+
+This is the single most forgotten step. See [LUMENFLOW.md](LUMENFLOW.md) for details.
+
+---
+
+## Core Principles
+
+1. **TDD**: Write tests first, then implementation
+2. **Worktree Discipline**: After `wu:claim`, work ONLY in the worktree
+3. **Gates Before Done**: Run `pnpm gates` before `wu:done`
+4. **Never Bypass Hooks**: No `--no-verify`
+
+---
+
+## Forbidden Commands
+
+- `git reset --hard`
+- `git push --force`
+- `git stash` (on main)
+- `--no-verify`
+
+---
+
+## Vendor-Specific Overlays
+
+This file provides universal guidance for all AI agents. Additional vendor-specific configuration:
+
+- **Claude Code**: See `CLAUDE.md` (if present)
+- **Cursor**: See `.cursor/rules/lumenflow.md` (if present)
+- **Windsurf**: See `.windsurf/rules/lumenflow.md` (if present)