@lumenflow/cli 5.7.17 → 5.7.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/cli",
-  "version": "5.7.17",
+  "version": "5.7.21",
   "description": "Command-line interface for LumenFlow workflow framework",
   "keywords": [
     "lumenflow",
@@ -45,6 +45,7 @@
     "cost-summary": "./dist/cost-summary.js",
     "db-journal-recover": "./dist/db-journal-recover.js",
     "delegation-list": "./dist/delegation-list.js",
+    "events-validate": "./dist/events-validate.js",
     "file-delete": "./dist/file-delete.js",
     "file-edit": "./dist/file-edit.js",
     "file-read": "./dist/file-read.js",
@@ -120,6 +121,7 @@
     "orchestrate-init-status": "./dist/orchestrate-init-status.js",
     "orchestrate-initiative": "./dist/orchestrate-initiative.js",
     "orchestrate-monitor": "./dist/orchestrate-monitor.js",
+    "orchestrate-pre-phase-audit": "./dist/orchestrate-pre-phase-audit.js",
     "pack-author": "./dist/pack-author.js",
     "pack-hash": "./dist/pack-hash.js",
     "pack-install": "./dist/pack-install.js",
@@ -201,16 +203,16 @@
     "xstate": "^5.28.0",
     "yaml": "^2.8.2",
     "zod": "^4.3.6",
-    "@lumenflow/initiatives": "5.7.17",
-    "@lumenflow/agent": "5.7.17",
-    "@lumenflow/control-plane-sdk": "5.7.17",
-    "@lumenflow/core": "5.7.17",
-    "@lumenflow/host": "^5.7.17",
-    "@lumenflow/memory": "5.7.17",
-    "@lumenflow/kernel": "5.7.17",
-    "@lumenflow/packs-software-delivery": "^5.7.17",
-    "@lumenflow/metrics": "5.7.17",
-    "@lumenflow/packs-agent-runtime": "^5.7.17"
+    "@lumenflow/initiatives": "5.7.21",
+    "@lumenflow/host": "^5.7.21",
+    "@lumenflow/agent": "5.7.21",
+    "@lumenflow/memory": "5.7.21",
+    "@lumenflow/kernel": "5.7.21",
+    "@lumenflow/metrics": "5.7.21",
+    "@lumenflow/packs-agent-runtime": "^5.7.21",
+    "@lumenflow/control-plane-sdk": "5.7.21",
+    "@lumenflow/packs-software-delivery": "^5.7.21",
+    "@lumenflow/core": "5.7.21"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.18",

package/packs/agent-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/packs-agent-runtime",
-  "version": "5.7.17",
+  "version": "5.7.21",
   "description": "Agent runtime pack scaffold for LumenFlow — governed model-turn execution, pack config, and provider capability baselines",
   "keywords": [
     "lumenflow",

package/packs/sidekick/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/packs-sidekick",
-  "version": "5.7.17",
+  "version": "5.7.21",
   "description": "Sidekick personal assistant pack for LumenFlow — 16 tools for task management, typed memory, channels, routines, and audit",
   "keywords": [
     "lumenflow",

package/packs/software-delivery/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/packs-software-delivery",
-  "version": "5.7.17",
+  "version": "5.7.21",
   "description": "Software delivery pack for LumenFlow — work units, gates, lanes, initiatives, and agent coordination",
   "keywords": [
     "lumenflow",

package/templates/core/AGENTS.md.template

@@ -45,7 +45,7 @@ pnpm lane:lock
 pnpm wu:claim --id WU-XXXX --lane <Lane>
 cd worktrees/<lane>-wu-xxxx
 
-# 2. Record handoff evidence (MANDATORY — wu:done blocks without this)
+# 2. Record canonical handoff evidence (MANDATORY — wu:done blocks without this)
 pnpm wu:brief --id WU-XXXX --client <client>
 
 # 3. Engage disciplines (see below)
@@ -71,7 +71,7 @@ cd <project-root> && pnpm wu:done --id WU-XXXX
 
 Step 2 above is not optional:
 
-- `wu:brief` records checkpoint evidence; `wu:done` **blocks** without it for feature/bug WUs.
+- `wu:brief` is the singular canonical handoff source of truth after `wu:claim`; it records checkpoint evidence, and `wu:done` **blocks** without it for feature/bug WUs.
 - `wu:brief` also auto-loads shared memory and coordination signals into the generated prompt (WU-1240, WU-2607) — read the `## Memory Context` section in the brief output before coding. Manual `mem:context`/`mem:inbox` calls are still available as ad-hoc lookups mid-WU.
 - Load relevant skills (`design-first`, `tdd-workflow`, `frontend-design`, `worktree-discipline`, `lumenflow-gates`) via your vendor's skill primitive. Claude Code, Codex, Cursor, and Windsurf all support `SKILL.md`-based skills (with minor invocation differences); Aider uses `CONVENTIONS.md`; Cline uses `.clinerules`. See [LUMENFLOW.md "Skills & Agents"](LUMENFLOW.md#skills--agents) for the invocation table, and your per-vendor rules file for specifics.
 
@@ -381,7 +381,7 @@ A skill named in prose does nothing — load it through the vendor's invocation
 | ------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | 1. Create WU | main     | `pnpm wu:create --lane <Lane> --title "Title" --description "..." --acceptance "..." --code-paths "..." --test-paths-unit "..." --exposure backend-only` (ID auto-generated) |
 | 2. Claim     | main     | `pnpm wu:claim --id WU-XXX --lane <Lane>`                                                                                                                                    |
-| 3. Brief     | worktree | `cd worktrees/<lane>-wu-xxx && pnpm wu:brief --id WU-XXX --client <client>` **(mandatory — wu:done blocks without this)**                                                    |
+| 3. Brief     | worktree | `cd worktrees/<lane>-wu-xxx && pnpm wu:brief --id WU-XXX --client <client>` **(canonical handoff; mandatory — wu:done blocks without this)**                                   |
 | 4. Work      | worktree | Implement changes per acceptance criteria                                                                                                                                    |
 | 5. Prep      | worktree | `pnpm wu:prep --id WU-XXX` (runs gates)                                                                                                                                      |
 | 6. Complete  | main     | `pnpm wu:done --id WU-XXX` (copy-paste from wu:prep)                                                                                                                         |
@@ -392,7 +392,7 @@ A skill named in prose does nothing — load it through the vendor's invocation
 | ------------ | ----------- | ------------------------------------------------------------------------------------------- |
 | 1. Create WU | lane branch | `pnpm wu:create --lane <Lane> --title "..." ... --cloud` (ID auto-generated)                |
 | 2. Claim     | lane branch | `pnpm wu:claim --id WU-XXX --lane <Lane> --cloud`                                           |
-| 3. Brief     | lane branch | `pnpm wu:brief --id WU-XXX --client <client>` **(mandatory — wu:done blocks without this)** |
+| 3. Brief     | lane branch | `pnpm wu:brief --id WU-XXX --client <client>` **(canonical handoff; mandatory — wu:done blocks without this)** |
 | 4. Work      | lane branch | Work on `lane/<lane>/wu-xxx` in cloud environment                                           |
 | 5. Prep      | lane branch | `pnpm wu:prep --id WU-XXX` (validates branch, runs gates)                                   |
 | 6. Complete  | lane branch | `pnpm wu:done --id WU-XXX` (creates PR)                                                     |

package/templates/core/LUMENFLOW.md.template

@@ -50,7 +50,7 @@ cd worktrees/<lane>-wu-xxxx
 # 4b. Build CLI in worktree (required for gates)
 pnpm bootstrap
 
-# 4c. Run wu:brief (MANDATORY — wu:done blocks without this)
+# 4c. Run wu:brief (canonical handoff; MANDATORY — wu:done blocks without this)
 pnpm wu:brief --id WU-XXXX --client <client>
 
 # 5. Implement in worktree
@@ -238,7 +238,7 @@ If a fact would help a different vendor working the same repo, it belongs in sha
 
 ### Before you code (auto-loaded by wu:brief)
 
-`wu:brief` auto-loads the read-side of the memory contract into the generated prompt under a `## Memory Context` section (WU-1240, WU-2607). It includes WU-scoped discoveries, summaries, project profile, and coordination signals from peer agents since `wu:claim`. Read that section before writing code — skipping it means working blind to what peer agents already found.
+`wu:brief` is the singular canonical handoff source of truth after `wu:claim`. It auto-loads the read-side of the memory contract into the generated prompt under a `## Memory Context` section (WU-1240, WU-2607). It includes WU-scoped discoveries, summaries, project profile, and coordination signals from peer agents since `wu:claim`. Read that section before writing code — skipping it means working blind to what peer agents already found.
 
 For ad-hoc lookups mid-WU (rarely needed; the brief is normally sufficient):
 
@@ -556,7 +556,7 @@ For the full worktree lifecycle (parallel execution, bootstrap, isolation guaran
 | `pnpm wu:unblock`       | Unblock WU (transitions to in_progress)                                         |
 | `pnpm wu:release`       | Release orphaned WU (in_progress to ready) AND reset lane branch (WU-2941)      |
 | `pnpm wu:status`        | Show WU status, location, and valid commands                                    |
-| `pnpm wu:brief`         | **MANDATORY after wu:claim.** Generate handoff prompt + record evidence         |
+| `pnpm wu:brief`         | **MANDATORY after wu:claim.** Generate canonical 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                                        |
@@ -968,7 +968,7 @@ is required for `pnpm db:reset` and similar workflows. Non-blocking informationa
 | `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 cost:summary`     | Summarize local cost telemetry; use `--brief` for local wu:brief token metrics |
 | `pnpm strict:progress`  | Report strict TypeScript backlog and guard regressions |
 
 ### State Management
@@ -1096,7 +1096,7 @@ Recommended framework roster (vendor-neutral aliases):
 Client-specific overlays may implement these aliases in different native surfaces such as
 `.claude/agents/`, `.codex/agents/`, or vendor rule/config directories.
 
-Generate handoff prompts (prompt-only, execution is a separate step): `pnpm wu:brief --id WU-XXX --client <client>`
+Generate the canonical handoff prompt and record evidence after claim: `pnpm wu:brief --id WU-XXX --client <client>`
 Record explicit delegation lineage when needed: `pnpm wu:delegate --id WU-XXX --parent-wu WU-YYY --client <client>`
 
 Supported clients: `claude-code`, `codex-cli`, `cursor`, `gemini-cli`, `windsurf`

package/templates/core/ai/onboarding/agent-invocation-guide.md.template

@@ -2,7 +2,7 @@
 
 **Last updated:** {{DATE}}
 
-This guide defines how to generate and hand off sub-agent delegation briefs, or record `wu:brief` evidence for self-implementation, so agents start with the right context, follow LumenFlow constraints, and leave durable artifacts for handoff.
+This guide defines how to generate and hand off sub-agent delegation briefs, or record canonical `wu:brief` evidence for self-implementation, so agents start with the right context, follow LumenFlow constraints, and leave durable artifacts for handoff.
 
 Use this document when:
 
@@ -38,7 +38,7 @@ Use Tier 1 after `/clear` to stay lean, then load more only if needed.
 ## 2) Session Management (Start Fresh)
 
 When approaching context limits, **start a fresh agent instead of compaction**.
-The handoff prompt is the bridge between sessions. `wu:brief` always generates the full WU context prompt and records evidence, whether you are delegating or self-implementing.
+The handoff prompt is the bridge between sessions. After `wu:claim`, `wu:brief` is the singular canonical handoff source of truth: it always generates the full WU context prompt and records evidence, whether you are delegating or self-implementing.
 
 **Mandatory triggers:**
 
@@ -129,13 +129,19 @@ pnpm wu:brief --id WU-XXX --client <client>
 # Then continue implementation directly in this session (no Task spawn).
 ```
 
-`wu:brief` always provides full context and records evidence in a single step. Use delegation flow (`wu:delegate`) only when you need auditable lineage tracking for initiative work.
+`wu:brief` is still required for self-implementation. It is the canonical handoff source after claim and always provides full context and records evidence in a single step. Use delegation flow (`wu:delegate`) only when you need auditable lineage tracking for initiative work.
+
+For local prompt accounting, add `--report-tokens`. The command prints total
+and section-level token counts, appends a schema-versioned
+`brief:token_reported` record to `.lumenflow/telemetry/brief-metrics.ndjson`,
+and keeps the data local unless a separate telemetry sync is configured. Review
+history with `pnpm cost:summary --brief`.
 
 ---
 
 ## 3) Canonical Handoff Surfaces
 
-Use the canonical handoff output verbatim when you have it:
+Use the canonical handoff output verbatim when you have it. For a claimed WU, `wu:brief` is the singular handoff source of truth; do not replace it with ad-hoc notes or a local summary.
 
 - `pnpm wu:brief --id WU-XXX --client <client>` for self-implementation
 - `pnpm wu:delegate --id WU-XXX --parent-wu <P> --client <client>` for auditable delegation

package/templates/core/ai/onboarding/existing-project-bootstrap.md.template

@@ -45,6 +45,23 @@ pnpm lumenflow --client <claude-code | cursor | windsurf>
 
 At this point `workspace.yaml` exists but is **untracked**. This is the trap.
 
+### Existing LumenFlow Projects: Upgrade First
+
+If the project already has LumenFlow files and package dependencies, do not reinstall or
+manually edit dependency versions. Run the managed upgrade command from the integration
+checkout:
+
+```bash
+pnpm lumenflow:upgrade --latest
+```
+
+After upgrade, `package.json` and `pnpm-lock.yaml` should contain the published
+`@lumenflow/*` packages managed by the command, with `@lumenflow/cli` as the CLI
+entrypoint. The old unscoped `lumenflow` wrapper is private/internal and should not
+remain in consumer dependencies or lockfile entries. If the command reports a
+non-fatal `NPM_TOKEN` config warning, set the token for private registry access or
+remove the stale placeholder from `.npmrc`; a successful install is still valid.
+
 ---
 
 ## Step 2: Commit the Baseline Before `lane:setup`

package/templates/core/ai/onboarding/quick-ref-commands.md.template

@@ -153,7 +153,8 @@ you want to refresh docs without upgrading packages (e.g., after manually editin
 | `pnpm wu:unblock --id WU-XXX`                                  | Unblock WU (ownership-guarded, v3.19.0)                                                                         |
 | `pnpm wu:release --id WU-XXX --reason "..."`                   | Release orphaned WU (ownership-guarded, v3.19.0)                                                                |
 | `pnpm wu:status --id WU-XXX`                                   | Show WU status, location, valid commands                                                                        |
-| `pnpm wu:brief --id WU-XXX --client <client>`                  | **MANDATORY after wu:claim.** Generate handoff prompt + record evidence. wu:done blocks without this (WU-2379)  |
+| `pnpm wu:brief --id WU-XXX --client <client>`                  | **MANDATORY after wu:claim.** Generate the canonical handoff prompt + record evidence. wu:done blocks without this (WU-2379) |
+| `pnpm wu:brief --id WU-XXX --client <client> --report-tokens`  | Print total/section token counts and append local `.lumenflow/telemetry/brief-metrics.ndjson` metrics           |
 | `pnpm wu:brief --id WU-XXX --no-context`                       | Generate prompt without memory context injection                                                                |
 | `pnpm wu:delegate --id WU-XXX --parent-wu <P>`                 | Generate prompt, record lineage, and store brief hash attestation                                               |
 | `pnpm wu:sandbox --id WU-XXX -- <cmd>`                         | Run command through hardened WU sandbox backend                                                                 |
@@ -478,6 +479,7 @@ Treat orchestration as a control plane: planning, handoff, execution, reconcilia
 | `pnpm flow:bottlenecks` | Identify flow bottlenecks                              |
 | `pnpm metrics:snapshot` | Capture metrics snapshot                               |
 | `pnpm cost:summary`     | Summarize local cost telemetry by model, agent, and WU |
+| `pnpm cost:summary --brief` | Summarize local wu:brief token metrics by WU, client, and date |
 | `pnpm metrics`          | View workflow metrics                                  |
 | `pnpm strict:progress`  | Report strict TypeScript backlog and guard regressions |
 
@@ -616,10 +618,11 @@ pnpm wu:create --lane "Framework: Core" --title "Add feature" \
 
 # 2. Claim (creates worktree) -- use the ID from wu:create output
 pnpm wu:claim --id WU-1990 --lane "Framework: Core"
+# 2b. Record canonical handoff evidence before coding
 pnpm wu:brief --id WU-1990 --client <client>
 cd worktrees/framework-core-wu-1990
 
-# 2b. Bootstrap (build CLI for dist-backed commands)
+# 2c. Bootstrap (build CLI for dist-backed commands)
 pnpm bootstrap
 
 # 3. Implement (TDD)
@@ -830,6 +833,7 @@ For cloud agents that cannot use local worktrees:
 # 1. Claim in cloud mode
 pnpm wu:claim --id WU-XXX --lane "<Lane>" --cloud
 # Or: LUMENFLOW_CLOUD=1 pnpm wu:claim --id WU-XXX --lane "<Lane>"
+# 1b. Record canonical handoff evidence before coding
 pnpm wu:brief --id WU-XXX --client <client>
 
 # 2. Work on lane branch, push commits

package/templates/core/ai/onboarding/wu-create-checklist.md.template

@@ -9,11 +9,16 @@ Use this checklist before running `pnpm wu:create`.
 ## Step 1: Confirm the Lane
 
 ```bash
+pnpm lane:setup --template react-vite   # or nextjs | node-cli | fastify
+pnpm lane:validate
+pnpm lane:lock
 pnpm lane:status
 pnpm wu:infer-lane --paths "packages/@lumenflow/cli/src/init.ts" --desc "Fix init docs drift"
 ```
 
-The lane should match the real implementation scope, not just the first file you noticed.
+Omit `--template` when you want LumenFlow to infer the stack from `package.json` and visible
+directories. The lane should match the real implementation scope, not just the first file you
+noticed.
 
 ---
 
@@ -33,17 +38,28 @@ The lane should match the real implementation scope, not just the first file you
 
 `--id` is optional. If omitted, `wu:create` allocates the next WU ID automatically.
 
+For `--exposure ui`, include concrete reachability evidence. User-flow features should use
+`navigation_path`, a page route in `code_paths`, or manual wording like
+`"Open /settings and verify ..."`. UI infrastructure/theme WUs can instead use manual wording like
+`"Run pnpm dev at http://localhost:3000 and confirm the component/theme state"`.
+
 ---
 
 ## Step 3: Decide Plan Storage
 
-If the work needs a plan, prefer repo-native or `lumenflow://plans/` references:
+If the work needs a plan, prefer repo-native `lumenflow://plans/` references:
 
 ```bash
 pnpm plan:create --id INIT-XXX --title "Plan title"
 pnpm wu:create --lane "Framework: CLI" --title "..." --plan
 ```
 
+Generated WU plans live in the repository plans directory
+(`software_delivery.directories.plansDir`, default `{{DOCS_OPERATIONS_PATH}}/plans`) so
+the same WU number can exist in separate projects without colliding. Older
+plans under `$LUMENFLOW_HOME/plans` still resolve as a compatibility fallback,
+but new WU work should use repo-local plans.
+
 Avoid pointing `--spec-refs` at random local filesystem notes that other agents cannot resolve.
 
 ---