@lumenflow/cli 2.6.0 → 2.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (88) hide show
  1. package/README.md +120 -105
  2. package/dist/__tests__/agent-spawn-coordination.test.js +451 -0
  3. package/dist/__tests__/commands/integrate.test.js +165 -0
  4. package/dist/__tests__/gates-config.test.js +0 -1
  5. package/dist/__tests__/hooks/enforcement.test.js +279 -0
  6. package/dist/__tests__/init-greenfield.test.js +247 -0
  7. package/dist/__tests__/init-quick-ref.test.js +0 -1
  8. package/dist/__tests__/init-template-portability.test.js +0 -1
  9. package/dist/__tests__/init.test.js +27 -0
  10. package/dist/__tests__/initiative-e2e.test.js +442 -0
  11. package/dist/__tests__/initiative-plan-replacement.test.js +0 -1
  12. package/dist/__tests__/memory-integration.test.js +333 -0
  13. package/dist/__tests__/release.test.js +1 -1
  14. package/dist/__tests__/safe-git.test.js +0 -1
  15. package/dist/__tests__/state-doctor.test.js +54 -0
  16. package/dist/__tests__/sync-templates.test.js +255 -0
  17. package/dist/__tests__/wu-create-required-fields.test.js +121 -0
  18. package/dist/__tests__/wu-done-auto-cleanup.test.js +135 -0
  19. package/dist/__tests__/wu-lifecycle-integration.test.js +388 -0
  20. package/dist/__tests__/wu-proto.test.js +97 -0
  21. package/dist/backlog-prune.js +0 -1
  22. package/dist/cli-entry-point.js +0 -1
  23. package/dist/commands/integrate.js +229 -0
  24. package/dist/docs-sync.js +46 -0
  25. package/dist/doctor.js +0 -2
  26. package/dist/gates.js +0 -7
  27. package/dist/hooks/enforcement-checks.js +209 -0
  28. package/dist/hooks/enforcement-generator.js +365 -0
  29. package/dist/hooks/enforcement-sync.js +243 -0
  30. package/dist/hooks/index.js +7 -0
  31. package/dist/init.js +266 -11
  32. package/dist/initiative-add-wu.js +0 -2
  33. package/dist/initiative-create.js +0 -3
  34. package/dist/initiative-edit.js +0 -5
  35. package/dist/initiative-plan.js +0 -1
  36. package/dist/initiative-remove-wu.js +0 -2
  37. package/dist/lane-health.js +0 -2
  38. package/dist/lane-suggest.js +0 -1
  39. package/dist/mem-checkpoint.js +0 -2
  40. package/dist/mem-cleanup.js +0 -2
  41. package/dist/mem-context.js +0 -3
  42. package/dist/mem-create.js +0 -2
  43. package/dist/mem-delete.js +0 -3
  44. package/dist/mem-inbox.js +0 -2
  45. package/dist/mem-index.js +0 -1
  46. package/dist/mem-init.js +0 -2
  47. package/dist/mem-profile.js +0 -1
  48. package/dist/mem-promote.js +0 -1
  49. package/dist/mem-ready.js +0 -2
  50. package/dist/mem-signal.js +0 -2
  51. package/dist/mem-start.js +0 -2
  52. package/dist/mem-summarize.js +0 -2
  53. package/dist/metrics-cli.js +1 -1
  54. package/dist/metrics-snapshot.js +1 -1
  55. package/dist/onboarding-smoke-test.js +0 -5
  56. package/dist/orchestrate-init-status.js +0 -1
  57. package/dist/orchestrate-initiative.js +0 -1
  58. package/dist/orchestrate-monitor.js +0 -1
  59. package/dist/plan-create.js +0 -2
  60. package/dist/plan-edit.js +0 -2
  61. package/dist/plan-link.js +0 -2
  62. package/dist/plan-promote.js +0 -2
  63. package/dist/signal-cleanup.js +0 -4
  64. package/dist/state-bootstrap.js +0 -1
  65. package/dist/state-cleanup.js +0 -4
  66. package/dist/state-doctor-fix.js +5 -8
  67. package/dist/state-doctor.js +0 -11
  68. package/dist/sync-templates.js +188 -34
  69. package/dist/wu-block.js +100 -48
  70. package/dist/wu-claim.js +1 -22
  71. package/dist/wu-cleanup.js +0 -1
  72. package/dist/wu-create.js +0 -2
  73. package/dist/wu-done-auto-cleanup.js +139 -0
  74. package/dist/wu-done.js +11 -4
  75. package/dist/wu-edit.js +0 -12
  76. package/dist/wu-preflight.js +0 -1
  77. package/dist/wu-prep.js +0 -1
  78. package/dist/wu-proto.js +329 -0
  79. package/dist/wu-spawn.js +0 -3
  80. package/dist/wu-unblock.js +0 -2
  81. package/dist/wu-validate.js +0 -1
  82. package/package.json +9 -7
  83. package/templates/core/.husky/pre-commit.template +93 -0
  84. package/templates/core/ai/onboarding/quick-ref-commands.md.template +27 -0
  85. package/templates/core/ai/onboarding/rapid-prototyping.md +143 -0
  86. package/templates/core/ai/onboarding/starting-prompt.md.template +3 -3
  87. package/templates/vendors/claude/.claude/CLAUDE.md.template +25 -0
  88. package/templates/vendors/claude/.claude/hooks/enforce-worktree.sh +135 -0
package/README.md CHANGED
@@ -46,134 +46,149 @@ This package provides CLI commands for the LumenFlow workflow framework, includi
46
46
 
47
47
  ## Commands
48
48
 
49
+ <!-- AUTO-GENERATED SECTION - DO NOT EDIT DIRECTLY -->
50
+ <!-- Run `pnpm docs:generate` to regenerate from source -->
51
+
49
52
  ### Work Unit Management
50
53
 
51
- | Command | Description |
52
- | ---------------- | ----------------------------------------------------------------------------------------------------------- |
53
- | `wu-block` | Block a work unit and move it from in-progress to blocked status |
54
- | `wu-claim` | Claim a work unit by creating a worktree/branch and updating status |
55
- | `wu-cleanup` | Clean up worktree and branch after PR merge (PR-based completion workflow) |
56
- | `wu-create` | Create a new Work Unit with micro-worktree isolation (race-safe). Auto-generates ID if `--id` not provided. |
57
- | `wu-delete` | Safely delete WU YAML files with micro-worktree isolation |
58
- | `wu-deps` | Visualize WU dependency graph |
59
- | `wu-done` | Complete a WU (runs gates, merges, creates stamp) |
60
- | `wu-edit` | Edit WU spec files with micro-worktree isolation |
61
- | `wu-infer-lane` | Suggest sub-lane for a WU based on content |
62
- | `wu-preflight` | Fast validation of code paths and test paths before gates |
63
- | `wu-prune` | Maintain worktree hygiene (prune stale worktrees, detect orphans) |
64
- | `wu-recover` | Analyze and fix WU state inconsistencies |
65
- | `wu-release` | Release an orphaned WU from in_progress back to ready state |
66
- | `wu-repair` | Unified WU repair tool - detect and fix WU state issues |
67
- | `wu-spawn` | Generate Task tool invocation for sub-agent WU execution |
68
- | `wu-status` | Show WU status, location, and valid commands |
69
- | `wu-unblock` | Unblock a work unit and move it from blocked to in-progress status |
70
- | `wu-unlock-lane` | Safely unlock a lane lock with audit logging |
71
- | `wu-validate` | Validate WU YAML files against schema |
54
+ | Command | Description |
55
+ | ---------------- | --------------------------------------------------------------------------- |
56
+ | `wu-block` | Block a work unit and move it from in-progress to blocked status |
57
+ | `wu-claim` | Claim a work unit by creating a worktree/branch and updating status |
58
+ | `wu-cleanup` | Clean up worktree and branch after PR merge (PR-based completion workflow) |
59
+ | `wu-create` | Create a new Work Unit with micro-worktree isolation (race-safe) |
60
+ | `wu-delete` | Safely delete WU YAML files with micro-worktree isolation |
61
+ | `wu-deps` | Visualize WU dependency graph |
62
+ | `wu-done` | WU Done Helper |
63
+ | `wu-edit` | Edit WU spec files with micro-worktree isolation |
64
+ | `wu-infer-lane` | WU Lane Inference CLI (WU-908) |
65
+ | `wu-preflight` | Fast validation of code_paths and test paths before gates run. |
66
+ | `wu-prep` | Prepare WU for completion (run gates in worktree) |
67
+ | `wu-proto` | Create and claim a prototype WU with relaxed validation (rapid prototyping) |
68
+ | `wu-prune` | WU Prune Utility |
69
+ | `wu-recover` | Analyze and fix WU state inconsistencies (WU-1090) |
70
+ | `wu-release` | Release an orphaned WU from in_progress back to ready state for reclaiming |
71
+ | `wu-repair` | WU State Repair Tool (Unified - WU-1826, WU-2240) |
72
+ | `wu-spawn` | Generate Task tool invocation for sub-agent WU execution |
73
+ | `wu-status` | Show WU status, location, and valid commands (WU-1090) |
74
+ | `wu-unblock` | Unblock a work unit and move it from blocked to in-progress status |
75
+ | `wu-unlock-lane` | Safely unlock a lane lock with audit logging |
76
+ | `wu-validate` | Validate WU YAML files against schema (strict mode by default, WU-1329) |
72
77
 
73
78
  ### Memory & Session
74
79
 
75
- | Command | Description |
76
- | --------------------- | ----------------------------------------------------------- |
77
- | `agent-issues-query` | Show summary of logged issues |
78
- | `agent-log-issue` | Log a workflow issue or incident |
79
- | `agent-session` | Start an agent session |
80
- | `agent-session-end` | End the current agent session |
81
- | `mem-checkpoint` | Create a checkpoint node for context snapshots |
82
- | `mem-cleanup` | Prune closed memory nodes based on lifecycle policy and TTL |
83
- | `mem-create` | Create a memory node with optional provenance tracking |
84
- | `mem-export` | Export memory nodes as markdown or JSON |
85
- | `mem-inbox` | Read coordination signals from other agents |
86
- | `mem-init` | Initialize memory layer in repository |
87
- | `mem-ready` | Query ready nodes for a WU (deterministic ordering) |
88
- | `mem-signal` | Send a coordination signal to other agents |
89
- | `mem-start` | Create a session node linked to a WU |
90
- | `mem-summarize` | Rollup older memory nodes into summary nodes for compaction |
91
- | `mem-triage` | Review discovery nodes and promote to WUs or archive |
92
- | `session-coordinator` | Manage agent sessions for WU work coordination |
93
- | `signal-cleanup` | Prune old signals based on TTL policy to prevent growth |
80
+ | Command | Description |
81
+ | -------------------- | ------------------------------------------------------------- |
82
+ | `agent-issues-query` | Query logged issues from agent sessions |
83
+ | `agent-log-issue` | Log an issue encountered during agent work |
84
+ | `agent-session` | Start an agent session for a WU |
85
+ | `agent-session-end` | End an agent session |
86
+ | `mem-checkpoint` | Create a checkpoint node for context snapshots |
87
+ | `mem-cleanup` | Prune closed memory nodes based on lifecycle policy and TTL |
88
+ | `mem-context` | Generate context injection block for wu:spawn prompts |
89
+ | `mem-create` | Create a memory node with optional provenance tracking |
90
+ | `mem-delete` | Delete memory nodes (soft delete via metadata.status=deleted) |
91
+ | `mem-export` | Export memory nodes as markdown or JSON |
92
+ | `mem-inbox` | Read coordination signals from other agents |
93
+ | `mem-init` | Initialize memory layer in repository |
94
+ | `mem-ready` | Query ready nodes for a WU (deterministic ordering) |
95
+ | `mem-signal` | Send a coordination signal to other agents |
96
+ | `mem-start` | Create a session node linked to a WU |
97
+ | `mem-summarize` | Rollup older memory nodes into summary nodes for compaction |
98
+ | `mem-triage` | Review discovery nodes and promote to WUs or archive |
94
99
 
95
100
  ### Initiative Orchestration
96
101
 
97
- | Command | Description |
98
- | ---------------------------- | ------------------------------------------------------------- |
99
- | `init-plan` | Link a plan file to an initiative |
100
- | `initiative-add-wu` | Link a WU to an initiative bidirectionally |
101
- | `initiative-bulk-assign-wus` | Bulk-assign orphaned WUs to initiatives based on lane rules |
102
- | `initiative-create` | Create a new Initiative with micro-worktree isolation |
103
- | `initiative-edit` | Edit Initiative YAML files with micro-worktree isolation |
104
- | `initiative-list` | List all initiatives with progress percentages |
105
- | `initiative-status` | Show detailed initiative view with phases and WUs |
106
- | `orchestrate-init-status` | Show initiative progress status |
107
- | `orchestrate-initiative` | Orchestrate initiative execution with parallel agent spawning |
108
- | `orchestrate-monitor` | Monitor spawned agent progress |
109
- | `rotate-progress` | Move completed WUs from status.md to Completed section |
110
- | `spawn-list` | Display spawn trees for WUs or initiatives |
102
+ | Command | Description |
103
+ | ---------------------------- | ------------------------------------------------------------------ |
104
+ | `initiative-add-wu` | Link a WU to an initiative bidirectionally |
105
+ | `initiative-bulk-assign-wus` | Bulk-assign orphaned WUs to initiatives based on lane prefix rules |
106
+ | `initiative-create` | Create a new Initiative with micro-worktree isolation (race-safe) |
107
+ | `initiative-edit` | Edit Initiative YAML files with micro-worktree isolation |
108
+ | `initiative-list` | List all initiatives with progress percentages |
109
+ | `initiative-plan` | Link a plan file to an initiative |
110
+ | `initiative-status` | Show detailed initiative view with phases and WUs |
111
+ | `orchestrate-init-status` | Show initiative orchestration status |
112
+ | `orchestrate-initiative` | Orchestrate initiative execution with agents |
113
+ | `orchestrate-monitor` | Monitor spawned agent progress and signals |
114
+ | `spawn-list` | Display spawn trees for WUs or initiatives |
111
115
 
112
116
  ### Metrics & Analytics
113
117
 
114
- | Command | Description |
115
- | ------------------- | -------------------------------------------------------------- |
116
- | `flow-bottlenecks` | Analyze WU dependency graph for bottlenecks and critical paths |
117
- | `flow-report` | Generate DORA/SPACE flow report from telemetry and WU data |
118
- | `lumenflow-metrics` | LumenFlow metrics CLI (lanes, dora, flow) |
119
- | `metrics` | Alias for `lumenflow-metrics` |
120
- | `metrics-snapshot` | Capture DORA metrics, lane health, and flow state snapshot |
121
- | `trace-gen` | Generate traceability reports linking WUs to code changes |
118
+ | Command | Description |
119
+ | ------------------ | ----------------------------------------------- |
120
+ | `flow-bottlenecks` | Identify workflow bottlenecks and critical path |
121
+ | `flow-report` | Generate DORA metrics flow report |
122
+ | `metrics` | Unified Metrics CLI with subcommands (WU-1110) |
123
+ | `metrics-snapshot` | Capture current metrics snapshot for dashboards |
122
124
 
123
125
  ### Lane Tooling
124
126
 
125
- | Command | Description |
126
- | -------------- | --------------------------------------------------------------------- |
127
- | `lane-health` | Check lane configuration health (overlaps, coverage gaps) |
128
- | `lane-suggest` | LLM-driven lane suggestions based on codebase context and git history |
127
+ | Command | Description |
128
+ | -------------- | -------------------------------------------------- |
129
+ | `lane-health` | Check lane configuration health (WU-1188) |
130
+ | `lane-suggest` | Suggest lane definitions based on codebase context |
129
131
 
130
132
  ### Verification & Gates
131
133
 
132
- | Command | Description |
133
- | ----------------------- | --------------------------------------------------------- |
134
- | `gates` | Run quality gates (format, lint, typecheck, tests) |
135
- | `guard-locked` | Check if a WU is locked (exits 1 if locked) |
136
- | `guard-main-branch` | Check if current branch is protected and block operations |
137
- | `guard-worktree-commit` | Check if a WU commit should be blocked from main checkout |
138
- | `lumenflow-gates` | Alias for `gates` |
139
- | `lumenflow-validate` | Validate WU YAML files for schema and quality |
140
- | `validate` | Alias for `lumenflow-validate` |
141
- | `validate-agent-skills` | Validate agent skill definitions |
142
- | `validate-agent-sync` | Validate agent configuration and sync state |
143
- | `validate-backlog-sync` | Validate that backlog.md is in sync with WU YAML files |
144
- | `validate-skills-spec` | Validate skill specification format |
134
+ | Command | Description |
135
+ | ----------------- | ------------------------------------------------------------------------------------------ |
136
+ | `gates` | Run quality gates with support for docs-only mode, incremental linting, and tiered testing |
137
+ | `lumenflow-gates` | Alias for `gates` - run quality gates |
145
138
 
146
139
  ### System & Setup
147
140
 
148
- | Command | Description |
149
- | -------------------------- | --------------------------------------------------------- |
150
- | `backlog-prune` | Maintain backlog hygiene (archive old WUs) |
151
- | `deps-add` | Add dependencies with worktree discipline enforcement |
152
- | `deps-remove` | Remove dependencies with worktree discipline enforcement |
153
- | `lumenflow` | CLI entry point (scaffold/init) |
154
- | `lumenflow-docs-sync` | Sync agent onboarding docs to existing projects |
155
- | `lumenflow-init` | Initialize LumenFlow in a project |
156
- | `lumenflow-release` | Release @lumenflow/\* packages to npm |
157
- | `lumenflow-sync-templates` | Sync internal docs to CLI templates |
158
- | `lumenflow-upgrade` | Upgrade all @lumenflow/\* packages to a specified version |
159
- | `state-bootstrap` | One-time migration utility for state sourcing |
160
- | `state-cleanup` | Unified cleanup: signals, memory, and event archival |
161
- | `state-doctor` | Check state integrity and detect inconsistencies |
162
- | `lumenflow-doctor` | Alias for `state-doctor` |
163
- | `sync-templates` | Alias for `lumenflow-sync-templates` |
141
+ | Command | Description |
142
+ | -------------------------- | --------------------------------------------------------------------------------- |
143
+ | `backlog-prune` | Backlog Prune Command |
144
+ | `deps-add` | Deps Add CLI Command |
145
+ | `deps-remove` | Deps Remove CLI Command |
146
+ | `guard-locked` | |
147
+ | `guard-main-branch` | Guard Main Branch CLI Tool |
148
+ | `guard-worktree-commit` | |
149
+ | `init-plan` | Link a plan file to an initiative |
150
+ | `lumenflow` | Initialize LumenFlow in a project |
151
+ | `lumenflow-docs-sync` | Sync agent onboarding docs to existing projects (skips existing files by default) |
152
+ | `lumenflow-doctor` | Check LumenFlow safety components and configuration |
153
+ | `lumenflow-init` | Initialize LumenFlow in a project |
154
+ | `lumenflow-integrate` | Integrate LumenFlow enforcement with AI client tools |
155
+ | `lumenflow-metrics` | Unified Metrics CLI with subcommands (WU-1110) |
156
+ | `lumenflow-release` | Release Command |
157
+ | `lumenflow-sync-templates` | Sync internal docs to CLI templates for release-cycle maintenance |
158
+ | `lumenflow-upgrade` | LumenFlow Upgrade CLI Command |
159
+ | `lumenflow-validate` | |
160
+ | `plan-create` | Create a new plan file in repo plansDir |
161
+ | `plan-edit` | Edit a section in a plan file |
162
+ | `plan-link` | Link a plan file to a WU or initiative |
163
+ | `plan-promote` | Promote a plan to approved status |
164
+ | `rotate-progress` | Rotate Progress CLI Command |
165
+ | `session-coordinator` | Session Coordinator CLI Command |
166
+ | `signal-cleanup` | Prune old signals based on TTL policy to prevent unbounded growth |
167
+ | `state-bootstrap` | State Bootstrap Command |
168
+ | `state-cleanup` | Orchestrate all state cleanup: signals, memory, events |
169
+ | `state-doctor` | Check state integrity and optionally repair issues |
170
+ | `sync-templates` | Sync internal docs to CLI templates for release-cycle maintenance |
171
+ | `trace-gen` | Trace Generator CLI Command |
172
+ | `validate` | |
173
+ | `validate-agent-skills` | |
174
+ | `validate-agent-sync` | |
175
+ | `validate-backlog-sync` | |
176
+ | `validate-skills-spec` | |
164
177
 
165
178
  ### File & Git Operations
166
179
 
167
- | Command | Description |
168
- | ------------- | -------------------------------------------------------------- |
169
- | `file-delete` | Delete a file or directory with audit logging |
170
- | `file-edit` | Edit file by replacing exact string matches with audit logging |
171
- | `file-read` | Read file content with audit logging |
172
- | `file-write` | Write content to a file with audit logging |
173
- | `git-branch` | List, create, or delete branches |
174
- | `git-diff` | Show changes between commits, commit and working tree |
175
- | `git-log` | Show commit logs |
176
- | `git-status` | Show the working tree status |
180
+ | Command | Description |
181
+ | ------------- | -------------------- |
182
+ | `file-delete` | File Delete CLI Tool |
183
+ | `file-edit` | File Edit CLI Tool |
184
+ | `file-read` | File Read CLI Tool |
185
+ | `file-write` | File Write CLI Tool |
186
+ | `git-branch` | Git Branch CLI Tool |
187
+ | `git-diff` | Git Diff CLI Tool |
188
+ | `git-log` | Git Log CLI Tool |
189
+ | `git-status` | Git Status CLI Tool |
190
+
191
+ <!-- END AUTO-GENERATED SECTION -->
177
192
 
178
193
  ## Usage
179
194