@lumenflow/cli 3.22.0 → 4.0.0

package/templates/core/LUMENFLOW.md.template

@@ -265,40 +265,194 @@ For the full worktree lifecycle (parallel execution, bootstrap, isolation guaran
 
 ---
 
-## Core Commands
-
-> **Complete CLI reference (100+ commands):** See [quick-ref-commands.md]({{QUICK_REF_LINK}}). Always run `<command> --help` for the authoritative option list.
-
-| Command                   | Description                                                                     |
-| ------------------------- | ------------------------------------------------------------------------------- |
-| `pnpm wu:create`          | Create new WU spec                                                              |
-| `pnpm wu:claim`           | Claim WU, update canonical state, create worktree                               |
-| `pnpm wu:prep`            | Run gates in worktree, prep for wu:done                                         |
-| `pnpm wu:done`            | Complete WU (merge, stamp, cleanup)                                             |
-| `pnpm wu:status`          | Show WU status, location, and valid commands                                    |
-| `pnpm wu:recover`         | Analyze and fix WU state inconsistencies                                        |
-| `pnpm wu:block`           | Block WU (transitions to blocked, frees lane)                                   |
-| `pnpm wu:unblock`         | Unblock WU (transitions to in_progress)                                         |
-| `pnpm wu:release`         | Release orphaned WU (in_progress to ready for reclaim)                          |
-| `pnpm wu:brief`           | **MANDATORY after wu:claim.** Generate handoff prompt + record evidence         |
-| `pnpm wu:delegate`        | Generate prompt + record lineage + brief hash attestation                       |
-| `pnpm wu:escalate`        | Show or resolve WU escalation status                                            |
-| `pnpm wu:verify`          | Verify WU completion (stamp, commit, clean tree)                                |
-| `pnpm wu:delete`          | Delete WU spec and cleanup                                                      |
-| `pnpm gates`              | Run quality gates (`pnpm gates:docs` for docs WUs; `--docs-only` is equivalent) |
-| `pnpm lumenflow:commands` | List all public commands (primary + alias + legacy)                             |
-| `pnpm docs:generate`      | Regenerate CLI/config reference docs from source                                |
-| `pnpm docs:validate`      | Verify generated docs are up-to-date                                            |
-| `pnpm lane:status`        | Show lane lifecycle status + next step                                          |
-| `pnpm lane:setup`         | Create/update draft lane artifacts                                              |
-| `pnpm lane:validate`      | Validate lane artifacts before lock                                             |
-| `pnpm lane:lock`          | Lock lane lifecycle for delivery WUs                                            |
-| `pnpm mem:checkpoint`     | Save memory checkpoint                                                          |
-
-Commands include **context-aware validation** that checks location, WU status, and git state. When validation fails, commands provide copy-paste ready fix commands. Configure in `workspace.yaml` under `software_delivery.experimental.context_validation`.
-The Starlight CLI reference page is intentionally curated to primary commands; use `pnpm lumenflow:commands` for complete discovery.
-
-For recovery commands, state management, memory coordination, and orchestration tools, see [quick-ref-commands.md]({{QUICK_REF_LINK}}).
+## CLI Command Reference
+
+> **This is the canonical command reference.** All agent docs (AGENTS.md, vendor rules, onboarding) point here. Always run `<command> --help` for authoritative options. Run `pnpm lumenflow:commands` to verify against the live CLI.
+
+### WU Lifecycle
+
+| Command                 | Description                                                             |
+| ----------------------- | ----------------------------------------------------------------------- |
+| `pnpm wu:create`        | Create new WU spec (ID auto-generated)                                  |
+| `pnpm wu:claim`         | Claim WU, update canonical state, create worktree (or `--cloud`)        |
+| `pnpm wu:sandbox`       | Run command through hardened WU sandbox backend                         |
+| `pnpm wu:prep`          | Run gates in worktree, prep for wu:done                                 |
+| `pnpm wu:done`          | Complete WU (merge, stamp, cleanup)                                     |
+| `pnpm wu:edit`          | Edit WU spec fields                                                     |
+| `pnpm wu:block`         | Block WU (transitions to blocked, frees lane)                           |
+| `pnpm wu:unblock`       | Unblock WU (transitions to in_progress)                                 |
+| `pnpm wu:release`       | Release orphaned WU (in_progress to ready for reclaim)                  |
+| `pnpm wu:status`        | Show WU status, location, and valid commands                            |
+| `pnpm wu:brief`         | **MANDATORY after wu:claim.** Generate handoff prompt + record evidence |
+| `pnpm wu:delegate`      | Generate prompt + record lineage + brief hash attestation               |
+| `pnpm wu:validate`      | Validate WU spec completeness and schema                                |
+| `pnpm wu:recover`       | Analyze and fix WU state inconsistencies                                |
+| `pnpm wu:verify`        | Verify WU completion (stamp, commit, clean tree)                        |
+| `pnpm wu:escalate`      | Show or resolve WU escalation status                                    |
+| `pnpm wu:delete`        | Delete WU spec and cleanup                                              |
+| `pnpm approval:request` | Request control-plane approval for a workflow action                    |
+| `pnpm approval:review`  | Resolve a control-plane approval decision                               |
+| `pnpm approval:list`    | List control-plane approvals with optional filters                      |
+
+### WU Maintenance
+
+| Command               | Description                                                      |
+| --------------------- | ---------------------------------------------------------------- |
+| `pnpm wu:preflight`   | Pre-flight checks before wu:done                                 |
+| `pnpm wu:repair`      | Repair WU state issues (claim, admin, state, duplicate-ids mode) |
+| `pnpm wu:prune`       | Clean stale worktrees                                            |
+| `pnpm wu:cleanup`     | Cleanup after PR merge (branch-pr mode)                          |
+| `pnpm wu:deps`        | Show WU dependencies                                             |
+| `pnpm wu:infer-lane`  | Infer lane from code paths/description                           |
+| `pnpm wu:unlock-lane` | Unlock stuck lane                                                |
+| `pnpm wu:proto`       | Create WU prototype                                              |
+
+### Gates & Quality
+
+| Command                           | Description                                           |
+| --------------------------------- | ----------------------------------------------------- |
+| `pnpm gates`                      | Run all quality gates (`--docs-only` for docs WUs)    |
+| `pnpm gates:docs`                 | Run docs-only quality gates (alias)                   |
+| `pnpm validate`                   | Run validation checks                                 |
+| `pnpm lumenflow:pre-commit-check` | Run enforcement checks used by pre-commit and CI      |
+| `pnpm gate:co-change`             | Manage co-change gate rules (add, remove, edit, list) |
+| `pnpm format`                     | Format all files (Prettier)                           |
+| `pnpm lint`                       | Run ESLint                                            |
+| `pnpm typecheck`                  | Run TypeScript type checking                          |
+| `pnpm test`                       | Run all tests (Vitest)                                |
+
+### Lane Management
+
+| Command              | Description                                       |
+| -------------------- | ------------------------------------------------- |
+| `pnpm lane:create`   | Create a new lane definition                      |
+| `pnpm lane:edit`     | Edit a lane definition (rename, wip-limit, paths) |
+| `pnpm lane:health`   | Check lane config health                          |
+| `pnpm lane:suggest`  | Suggest workspace lane definitions from context   |
+| `pnpm lane:status`   | Show lane lifecycle status and next step          |
+| `pnpm lane:setup`    | Create/update draft lane artifacts                |
+| `pnpm lane:validate` | Validate lane artifacts before lock               |
+| `pnpm lane:lock`     | Lock lane lifecycle for delivery WUs              |
+
+### Memory & Sessions
+
+| Command               | Description                                |
+| --------------------- | ------------------------------------------ |
+| `pnpm mem:init`       | Initialize memory for WU                   |
+| `pnpm mem:checkpoint` | Save progress checkpoint                   |
+| `pnpm mem:start`      | Start a memory session                     |
+| `pnpm mem:ready`      | Check pending memory nodes                 |
+| `pnpm mem:export`     | Export memory as markdown                  |
+| `pnpm mem:signal`     | Broadcast coordination signal              |
+| `pnpm mem:cleanup`    | Clean up stale memory data                 |
+| `pnpm mem:context`    | Get context for current lane/WU            |
+| `pnpm mem:create`     | Create memory node (bug discovery)         |
+| `pnpm mem:inbox`      | Check coordination signals                 |
+| `pnpm mem:summarize`  | Summarize memory context                   |
+| `pnpm mem:triage`     | Triage discovered bugs                     |
+| `pnpm mem:delete`     | Delete/archive a memory node               |
+| `pnpm mem:recover`    | Generate recovery context after compaction |
+| `pnpm signal:cleanup` | Clean up stale signals                     |
+
+### Initiatives
+
+| Command                       | Description                               |
+| ----------------------------- | ----------------------------------------- |
+| `pnpm initiative:create`      | Create new initiative                     |
+| `pnpm initiative:edit`        | Edit initiative fields and phase metadata |
+| `pnpm initiative:list`        | List all initiatives                      |
+| `pnpm initiative:status`      | Show initiative status                    |
+| `pnpm initiative:add-wu`      | Add WU to initiative                      |
+| `pnpm initiative:remove-wu`   | Remove WU from initiative                 |
+| `pnpm initiative:plan`        | Link plan to initiative                   |
+| `pnpm initiative:bulk-assign` | Bulk assign WUs to initiative             |
+
+### Plans
+
+| Command             | Description                   |
+| ------------------- | ----------------------------- |
+| `pnpm plan:create`  | Create a new plan             |
+| `pnpm plan:link`    | Link plan to WU or initiative |
+| `pnpm plan:edit`    | Edit plan content             |
+| `pnpm plan:promote` | Promote plan to WU            |
+
+### Orchestration
+
+| Command                        | Description                                 |
+| ------------------------------ | ------------------------------------------- |
+| `pnpm orchestrate:initiative`  | Orchestrate initiative execution            |
+| `pnpm orchestrate:init-status` | Compact initiative progress view            |
+| `pnpm orchestrate:monitor`     | Monitor spawn/agent activity                |
+| `pnpm delegation:list`         | List active delegation records              |
+| `pnpm task:claim`              | Claim a task directly through KernelRuntime |
+| `pnpm agent:session`           | Start agent session                         |
+| `pnpm agent:session-end`       | End agent session                           |
+| `pnpm agent:log-issue`         | Log issue during agent session              |
+| `pnpm agent:issues-query`      | Query GitHub issues for agent work          |
+
+### Setup & Configuration
+
+| Command                         | Description                                           |
+| ------------------------------- | ----------------------------------------------------- |
+| `pnpm setup`                    | Install deps and build CLI (first time)               |
+| `pnpm lumenflow`                | Initialize LumenFlow in a project                     |
+| `pnpm lumenflow:doctor`         | Diagnose LumenFlow configuration                      |
+| `pnpm lumenflow:commands`       | List all available CLI commands                       |
+| `pnpm lumenflow:release`        | Run release workflow                                  |
+| `pnpm lumenflow:docs-sync`      | Refresh core docs, onboarding docs, and vendor assets |
+| `pnpm lumenflow:sync-templates` | Sync templates to project                             |
+| `pnpm lumenflow:upgrade`        | Upgrade LumenFlow packages                            |
+| `pnpm lumenflow:integrate`      | Generate enforcement hooks for client                 |
+| `pnpm config:set`               | Safely update workspace.yaml via micro-worktree       |
+| `pnpm config:get`               | Read a value from workspace.yaml                      |
+| `pnpm cloud:connect`            | Connect workspace.yaml to cloud control plane         |
+| `pnpm backlog:prune`            | Clean stale backlog entries                           |
+
+### Metrics & Flow
+
+| Command                 | Description                                            |
+| ----------------------- | ------------------------------------------------------ |
+| `pnpm flow:report`      | Generate flow metrics report                           |
+| `pnpm flow:bottlenecks` | Identify flow bottlenecks                              |
+| `pnpm metrics:snapshot` | Capture metrics snapshot                               |
+| `pnpm cost:summary`     | Summarize local cost telemetry                         |
+| `pnpm strict:progress`  | Report strict TypeScript backlog and guard regressions |
+
+### State Management
+
+| Command                | Description                          |
+| ---------------------- | ------------------------------------ |
+| `pnpm state:doctor`    | Diagnose state store issues          |
+| `pnpm state:cleanup`   | Clean up stale state data            |
+| `pnpm state:bootstrap` | Bootstrap state store                |
+| `pnpm state:emit`      | Emit corrective event to state store |
+
+### Packs
+
+| Command              | Description                                |
+| -------------------- | ------------------------------------------ |
+| `pnpm pack:author`   | Author a secure domain pack from templates |
+| `pnpm pack:scaffold` | Scaffold a new domain pack                 |
+| `pnpm pack:validate` | Validate a domain pack for integrity       |
+| `pnpm pack:hash`     | Compute integrity hash for a domain pack   |
+| `pnpm pack:publish`  | Publish a domain pack to a registry        |
+| `pnpm pack:install`  | Install a domain pack into workspace       |
+| `pnpm pack:search`   | Search for domain packs in a registry      |
+
+### Audited Wrappers
+
+| Command            | Description                      |
+| ------------------ | -------------------------------- |
+| `pnpm file:read`   | Read file with audit trail       |
+| `pnpm file:write`  | Write file with audit trail      |
+| `pnpm file:edit`   | Edit file with audit trail       |
+| `pnpm file:delete` | Delete file with audit trail     |
+| `pnpm git:status`  | Show git status with audit trail |
+| `pnpm git:diff`    | Show git diff with audit trail   |
+| `pnpm git:log`     | Show git log with audit trail    |
+| `pnpm git:branch`  | Show git branch with audit trail |
+
+Commands include **context-aware validation** that checks location, WU status, and git state. When validation fails, commands provide copy-paste ready fix commands.
 
 ---
 

package/templates/core/UPGRADING.md.template

@@ -43,7 +43,7 @@ pnpm list @lumenflow/*
 
 Before upgrading, review the changelog for breaking changes:
 
-- [GitHub Releases](https://github.com/hellmai/lumenflow-dev/releases)
+- [GitHub Releases](https://github.com/hellmai/lumenflow/releases)
 - [lumenflow.dev/changelog](https://lumenflow.dev/changelog)
 
 ### 3. Update Packages
@@ -140,5 +140,5 @@ For major version upgrades, see version-specific migration guides:
 
 ## Getting Help
 
-- [GitHub Issues](https://github.com/hellmai/lumenflow-dev/issues)
+- [GitHub Issues](https://github.com/hellmai/lumenflow/issues)
 - [lumenflow.dev/docs](https://lumenflow.dev/docs)

package/templates/core/ai/onboarding/release-process.md.template

@@ -262,11 +262,11 @@ vercel --prod
 
 - **Project**: `lumenflow-docs` (ID: `prj_myK4BzfHKctGhxfvALJaMOXVLx4g`)
 - **Domain**: lumenflow.dev
-- **Team**: hellm-ai
+- **Team**: lumenflow
 
 ### Important Notes
 
-- **No private repo links**: Starlight docs are public; never link to `github.com/hellmai/lumenflow-dev`
+- **No private repo links**: Starlight docs are public; never link to `github.com/hellmai/lumenflow`
 - **Link to npm**: Use <https://www.npmjs.com/org/lumenflow> for package links
 
 ---
@@ -286,8 +286,8 @@ Packs are published to the registry at <https://registry.lumenflow.dev>. The reg
 The `apps/web` Vercel project has `Root Directory: apps/web` configured. To deploy from the CLI, link the repo root to the `web` project:
 
 ```bash
-# From repo root — link to the 'web' project (not 'lumenflow-dev')
-vercel link --project web --scope hellm-ai --yes
+# From repo root — link to the 'web' project (not the monorepo project)
+vercel link --project web --scope lumenflow --yes
 
 # Deploy to production
 vercel --prod --yes
@@ -295,12 +295,12 @@ vercel --prod --yes
 
 **Gotcha:** Do NOT run `vercel` from inside `apps/web/` — the Vercel root directory setting doubles the path (`apps/web/apps/web`). Always deploy from the repo root.
 
-**Gotcha:** The repo root `.vercel/project.json` may be linked to `lumenflow-dev` (the monorepo project). You must re-link to `web` before deploying the registry.
+**Gotcha:** The repo root `.vercel/project.json` may be linked to the monorepo project. You must re-link to `web` before deploying the registry.
 
 After deploying, restore the link if needed:
 
 ```bash
-vercel link --project lumenflow-dev --scope hellm-ai --yes
+vercel link --project lumenflow --scope lumenflow --yes
 ```
 
 ### Step 2: Build the Tarball
@@ -345,12 +345,12 @@ rm packages/@lumenflow/packs/software-delivery/lumenflow-packs-software-delivery
 
 ### Vercel Projects Reference
 
-| Project         | Domain                   | Purpose                 |
-| --------------- | ------------------------ | ----------------------- |
-| `web`           | registry.lumenflow.dev   | Pack registry + web app |
-| `docs`          | lumenflow.dev            | Starlight documentation |
-| `lumenflow-dev` | lumenflow-dev.vercel.app | Monorepo preview        |
-| `cloud`         | cloud.lumenflow.dev      | Control plane           |
+| Project     | Domain                 | Purpose                 |
+| ----------- | ---------------------- | ----------------------- |
+| `web`       | registry.lumenflow.dev | Pack registry + web app |
+| `docs`      | lumenflow.dev          | Starlight documentation |
+| `lumenflow` | lumenflow.vercel.app   | Monorepo preview        |
+| `cloud`     | cloud.lumenflow.dev    | Control plane           |
 
 ### Troubleshooting Pack Publishing
 
@@ -368,7 +368,7 @@ Missing or wrong `Origin` header. Must be `https://registry.lumenflow.dev`.
 
 #### Vercel build fails with d2 error
 
-The `@lumenflow/docs` package requires `d2` (diagramming tool) which is not available on Vercel. Ensure you are deploying the `web` project (which uses `turbo build --filter=@lumenflow/web`) not the `lumenflow-dev` project (which builds all packages).
+The `@lumenflow/docs` package requires `d2` (diagramming tool) which is not available on Vercel. Ensure you are deploying the `web` project (which uses `turbo build --filter=@lumenflow/web`) not the monorepo project (which builds all packages).
 
 ---