@lumenflow/cli 5.5.0 → 5.7.14

package/templates/core/AGENTS.md.template

@@ -2,7 +2,7 @@
 
 # Universal Agent Instructions
 
-**Last updated:** {{DATE}}
+**Last updated:** {{DATE}} (5.6.0 — INIT-069 vocabulary: `--estimated-files`, `--interrupt-class`, `test-over-deletion`, `monolithic-file-contention`, `prod-migration-drift`, `db:journal-recover`, file-overlap & lane-fit preflight)
 
 > **Works with any AI coding assistant.** This file provides instructions that work regardless of which AI tool you're using -- Claude Code, Cursor, Windsurf, Cline, Codex, Aider, or any other. Just read this file and follow the workflow.
 
@@ -81,10 +81,22 @@ Capture findings in shared memory so other agents (and other vendors) can see th
 
 ```bash
 pnpm mem:create --type discovery --wu WU-XXXX --tags <csv> --priority P? --title '<prose>'
+# Pre-Phase Audits (WU-2940): omit --wu to capture findings before any WU exists.
+pnpm mem:create --type discovery --tags pre-phase-audit --title 'orchestrator finding'
 pnpm mem:signal '<short status>' --wu WU-XXXX
+# WU-2940: --interrupt-class is canonical; --interrupt remains a back-compat alias.
+pnpm mem:signal 'urgent: build break on main' --wu WU-XXXX --interrupt-class urgent
 pnpm mem:checkpoint --wu WU-XXXX --note '<progress>' --next-steps '<what is next>'
 ```
 
+For mid-flight scope correction (WU-2940), `pnpm wu:edit` accepts sizing flags
+(`--estimated-files`, `--estimated-tool-calls`, `--sizing-strategy`,
+`--sizing-exception-type`, `--sizing-exception-reason`) and allows
+non-destructive edits (`--description`, `--notes`, sizing) on in-progress WUs
+**from the main checkout** without the wu:release/wu:recover dance. Structural
+edits (`--lane`, `--code-paths` replace, `--priority`, `--type`,
+`--initiative`) still require the dance.
+
 **Classification rule:** if the fact would help _another_ agent vendor working this repo, it belongs in shared memory (`mem:create`), not your vendor's personal memory folder. Examples of shared: bug discoveries, architecture decisions, CI/gates gotchas, initiative direction, cross-WU scope flags. Examples of vendor-personal: behavioural feedback, user preferences, tool-invocation mechanics.
 
 **Shell-quoting footgun:** always **single-quote** the `--title` value. Bash expands `$var`, `$0`, backticks, and `!hist` inside double-quoted strings, silently corrupting prose containing prices (`$49`), positional refs, or exclamation marks. See [Memory section in LUMENFLOW.md](LUMENFLOW.md#memory-shared-vs-vendor-personal) for the full mem:\* contract.
@@ -137,6 +149,17 @@ pnpm mem:triage --archive mem-XXXX --reason '<why>'             # drop non-actio
 
 `wu:done` does not auto-triage. Unreviewed discoveries rot — always check the list before completing.
 
+### Database Workflow Primitives (WU-2945)
+
+```bash
+pnpm db:journal-recover            # detect drizzle journal collisions (dry-run by default)
+pnpm db:journal-recover --confirm  # apply resequence + write audit log under .lumenflow/db-recovery/
+pnpm lumenflow:setup-prereqs       # show external prereqs (e.g. Supabase CLI) — runs at end of pnpm setup
+```
+
+- `db:journal-recover` is idempotent — re-running on a healthy chain is a no-op.
+- If your project uses Supabase, install the Supabase CLI before `pnpm db:reset`.
+
 ## Quick Start (Cloud / Branch-PR)
 
 Cloud agents (Codex, Claude web, CI bots) that cannot use local worktrees use the **branch-pr** mode. This is a first-class lifecycle, not a workaround.
@@ -186,6 +209,13 @@ The completion workflow is a two-step process. Run `wu:prep` from the worktree (
 
 For detailed troubleshooting, see [troubleshooting-wu-done.md]({{DOCS_ONBOARDING_PATH}}/troubleshooting-wu-done.md).
 
+**Plan-time preflight (WU-2942):** `pnpm orchestrate:initiative` emits two extra sections after the wave breakdown:
+
+- _File-overlap preflight_ — WU pairs sharing a `code_paths` entry inside the same wave (silently serial; resolve before claim).
+- _Lane-fit suggestions_ — WUs stacked on a WIP=1 lane with concrete re-lane recommendations from `wu:infer-lane`.
+
+Read these BEFORE claiming a wave. Default mode is advisory; configure via `software_delivery.orchestrate.preflight: 'advisory' | 'strict' | 'off'` or pass `--strict-preflight` to make warnings blocking for one run. See [LUMENFLOW.md "Plan-time preflight"](LUMENFLOW.md#plan-time-preflight-wu-2942).
+
 ---
 
 ## Core Principles
@@ -196,8 +226,10 @@ For detailed troubleshooting, see [troubleshooting-wu-done.md]({{DOCS_ONBOARDING
    (`--skip-gate <name>`, repeatable) is the preferred bypass surface as of
    WU-2925; legacy `--skip-gates` is deprecated for one minor cycle. Only gates
    marked `skippable: true` (allow-list: `migration-verify`, `lane-health`,
-   `tdd-diff-evidence`, plus the WU-2927 opt-in local-prep gates `build`,
-   `integration-test`, `e2e-smoke`) or overridden via
+   `tdd-diff-evidence`, the WU-2927 opt-in local-prep gates `build`,
+   `integration-test`, `e2e-smoke`, the WU-2943 advisory heuristic gates
+   `test-over-deletion`, `monolithic-file-contention`, and the WU-2944
+   opt-in `prod-migration-drift` gate) or overridden via
    `software_delivery.gates.overrides.<gate_id>.skippable=true` may be skipped.
    Both flags require `--reason` and `--fix-wu`.
 
@@ -231,6 +263,31 @@ For detailed troubleshooting, see [troubleshooting-wu-done.md]({{DOCS_ONBOARDING
    See [LUMENFLOW.md gates section](LUMENFLOW.md#extended-local-prep-profile-wu-2927)
    for the schema and latency budget.
 
+   **Heuristic guard gates (WU-2943).** Two advisory gates run on every
+   `wu:prep`, both `skippable: true` (allow-listed) with
+   `prereq_strategy: 'auto-skip'`:
+   - `test-over-deletion` — flags deleted `.test.ts(x)` whose `describe()` /
+     `describe.each()` strings reference symbols outside the current WU's
+     `code_paths` (scope-creep deletion).
+   - `monolithic-file-contention` — flags files appearing in 2+ active WUs'
+     `code_paths` (statuses `in_progress` + `ready`) when the current WU is
+     one of the claimants. Output names the file, the contending WUs, and
+     suggests splitting the module to enable parallelism.
+
+   Both auto-skip cleanly when the heuristic does not fire. Per-repo override
+   to BLOCK on trigger:
+   `pnpm config:set software_delivery.gates.overrides.<gate>.skippable=false`.
+
+   **Prod-migration-drift gate (WU-2944).** Optional CI-scheduled gate that
+   detects when the production database is N+ migrations behind the canonical
+   `migrations/` directory on main. Auto-skips `not-applicable` until the
+   repo opts in by setting
+   `software_delivery.gates.overrides.prod-migration-drift.connection_string_env_var`
+   (e.g. `PROD_DATABASE_URL`). Requires the configured env var to be set and
+   the prod DB to be reachable; otherwise auto-skips under
+   `prereq_strategy: 'auto-skip'`. Threshold is configurable
+   (`overrides.prod-migration-drift.threshold`, default 5).
+
 4. **Never Bypass Hooks**: No `--no-verify`
 5. **Vendor-Agnostic Dirty-Main Guard**: `wu:prep` and `wu:done` hard-block when main has non-allowlisted dirty files during worktree WUs (including MCP/tool-originated writes). `branch-pr` mode is exempt.
 6. **Docs Parity For Behavior Changes**: If you change LumenFlow behavior or workflow guidance, update internal docs, Starlight docs, or both as appropriate. Generated reference docs do not cover narrative behavior changes by themselves.
@@ -276,6 +333,13 @@ LumenFlow enforces safety at the repository level via git wrappers and hooks. Fo
 
 **Key rule:** Always use `wu:` commands for worktree and branch management -- never raw `git worktree` or `git branch -D` commands. Use `wu:recover` for state inconsistencies, `wu:release` for abandoned WUs, and `wu:prune` for stale worktrees.
 
+**WU-2941:** `wu:release` resets both the YAML status and the lane branch
+(default: delete branch locally + on `origin`). Pass `--keep-branch` to retain
+the branch for diagnostic recovery, or set
+`software_delivery.wu_release.branch_action: 'keep'` in `workspace.yaml` for
+air-gapped/offline repos. `wu:status` surfaces residual main↔worktree drift
+inline with a `Run pnpm wu:recover --id WU-X --action reset` hint.
+
 ---
 
 ## Vendor-Specific Overlays

package/templates/core/LUMENFLOW.md.template

@@ -1,6 +1,6 @@
 # LumenFlow Workflow Guide
 
-**Last updated:** {{DATE}}
+**Last updated:** {{DATE}} (5.6.0 — INIT-069: workflow ergonomics, smart guard gates, db primitives, prod drift CI gate)
 
 LumenFlow is a vendor-agnostic workflow framework for AI-native software development.
 
@@ -283,7 +283,8 @@ runtime metadata. When it is absent, receipt state falls back to the ephemeral
 
 A2A signal semantics are structured, not prose-only. `mem:signal` supports
 `--thread`, `--reply-to`, `--intent INFO|PROPOSE|COUNTER|AGREE|REJECT`,
-`--interrupt advisory|priority|urgent|soon|immediate`, and `--requires-ack`.
+`--interrupt-class advisory|priority|urgent|soon|immediate` (canonical name;
+`--interrupt` remains as a back-compat alias — WU-2940), and `--requires-ack`.
 Directed root signals default to `interrupt_class: priority` and get a generated
 `thread_id`; broadcasts default to `interrupt_class: advisory`. Replies inherit
 the parent thread unless `--thread` is explicit. When a recipient posts
@@ -543,28 +544,75 @@ For the full worktree lifecycle (parallel execution, bootstrap, isolation guaran
 
 ### 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                      |
+| 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 (sizing flags + non-destructive in-progress edits, WU-2940) |
+| `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) 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: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:edit ergonomics (WU-2940)
+
+`pnpm wu:edit` accepts the full sizing-estimate surface — `--estimated-files`,
+`--estimated-tool-calls`, `--sizing-strategy`, `--sizing-exception-type`,
+`--sizing-exception-reason` — for mid-flight scope correction without a
+wu:delete + wu:create dance. Each flag is independently editable; partial edits
+merge into the existing `sizing_estimate` sub-object.
+
+In-progress WUs accept non-destructive edits (`--description`, `--notes`, and
+the five sizing flags above) **from the main checkout** via the micro-worktree
+path. Other edits — `--lane`, `--code-paths` replace, `--priority`, `--type`,
+`--initiative` — still require the existing `wu:release`/`wu:recover` dance
+because they restructure scope.
+
+#### wu:release branch reset (WU-2941)
+
+`pnpm wu:release` now resets the **lane branch** alongside the WU YAML so
+subsequent `pnpm wu:status` reports no main↔worktree drift. Default behaviour
+is to delete the lane branch locally and on `origin`. Override with:
+
+- `--keep-branch` flag — retain the branch for diagnostic recovery.
+- `software_delivery.wu_release.branch_action` in `workspace.yaml` —
+  `'delete'` (default), `'rebase'` (hard-reset local ref to
+  `baseline_main_sha`, no remote push), or `'keep'` (no-op for
+  air-gapped/offline repos).
+
+Cloud `claimed_mode: branch-pr` releases are unaffected; the claimed branch
+is owned by the cloud lifecycle and never touched by `wu:release`.
+
+`pnpm wu:status` surfaces residual main↔worktree drift inline as a
+structured remediation hint (matching the `wu:done` preflight error format):
+`WU-X: main shows ready, branch shows in_progress. Run pnpm wu:recover --id
+WU-X --action reset to reconcile.`
+
+#### Pre-WU memory artifacts (WU-2940)
+
+`pnpm mem:create` accepts pre-WU artifacts: omit `--wu` to capture findings
+produced before any WU exists (Pre-Phase Audits per the wu-sizing-guide §1.5).
+The persisted record stores `wu_id` null/absent and remains discoverable via
+tag-only `mem:context --tags <csv>` queries.
+
+```bash
+# Capture an orchestrator finding before claiming the next WU
+pnpm mem:create --type discovery --tags pre-phase-audit \
+  --title 'INIT-XXX wave 1 needs review-audit exception in WU-YYY'
+```
 
 ### WU Maintenance
 
@@ -614,9 +662,12 @@ pnpm wu:prep --id WU-XXX \
 ```
 
 **Allow-list (skippable: true by default):** `migration-verify`,
-`lane-health`, `tdd-diff-evidence`, plus the WU-2927 opt-in local-prep gates
-`build`, `integration-test`, `e2e-smoke`. All other framework gates default to
-`skippable: false` and require a per-repo override at
+`lane-health`, `tdd-diff-evidence`, the WU-2927 opt-in local-prep gates
+`build`, `integration-test`, `e2e-smoke`, the WU-2943 advisory heuristic
+gates `test-over-deletion`, `monolithic-file-contention`, and the WU-2944
+opt-in `prod-migration-drift` gate (CI-scheduled; auto-skips not-applicable
+when `PROD_DATABASE_URL` is not configured). All other framework gates
+default to `skippable: false` and require a per-repo override at
 `software_delivery.gates.overrides.<gate_id>.skippable=true` to be skipped:
 
 ```bash
@@ -714,6 +765,71 @@ with `source: 'agent'`.
 Backward-compat: omitting `local_prep` (the default) preserves today's
 behaviour — none of the new gates is applicable, no new commands run.
 
+#### Heuristic guard gates (WU-2943)
+
+Two advisory gates ride the INIT-068 contract on every `wu:prep`. Both are
+`skippable_default: true` and `prereq_strategy: 'auto-skip'`, surface their
+findings via the `failed` `GateResult` state, and emit the standard six-state
+legend (`✅ / ❌ / ⏭ / ⊘ / 🚫`). Each gate is per-repo configurable via
+`software_delivery.gates.overrides.<gate_id>`.
+
+| Gate                         | Driver           | When applicable                                        | When it fails                                                                                                                                                                         |
+| ---------------------------- | ---------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `test-over-deletion`         | INIT-105 item 12 | wu:prep diff includes deleted `.test.ts` / `.test.tsx` | Any deleted test's `describe()` / `describe.each()` symbol is not present in the current WU's `code_paths`. Output lists each unrecognised symbol.                                    |
+| `monolithic-file-contention` | INIT-105 item 13 | Always (every `wu:prep`)                               | A file appears in 2+ active WUs' `code_paths` (statuses: `in_progress`, `ready`) and the current WU is one of the claimants. Output lists the file + claimant WUs + a re-laning hint. |
+
+Both gates are advisory (`skippable_default: true`); intentional triggers can
+be skipped with `--skip-gate test-over-deletion` / `--skip-gate
+monolithic-file-contention` (with `--reason` and `--fix-wu` per WU-2925).
+Repos that want either gate to BLOCK can flip the default:
+
+```bash
+pnpm config:set software_delivery.gates.overrides.test-over-deletion.skippable=false
+pnpm config:set software_delivery.gates.overrides.monolithic-file-contention.skippable=false
+```
+
+Backward-compat: when the heuristic does not fire, both gates auto-skip
+cleanly; existing `wu:prep` flows are unaffected.
+
+#### prod-migration-drift gate (WU-2944)
+
+Optional CI-scheduled gate (INIT-105 item 14). Compares the canonical
+`migrations/` directory on main against the production database's applied
+migrations and fails when drift exceeds a configurable threshold (default 5).
+Driver: cloud INIT-105 — prod silently accumulated 7+ migrations of drift
+before any human noticed; no automated detection caught it.
+
+| Property              | Value                                                                                            |
+| --------------------- | ------------------------------------------------------------------------------------------------ |
+| Gate name             | `prod-migration-drift`                                                                           |
+| Allow-list status     | `skippable: true` (advisory)                                                                     |
+| `prereq_strategy`     | `auto-skip`                                                                                      |
+| Default applicability | `not-applicable` until repo opts in via override (clean opt-out — most repos won't enable day 1) |
+| Default threshold     | `5` (drift > threshold ⇒ `failed`)                                                               |
+
+Per-repo opt-in (set both keys; without `connection_string_env_var` the gate
+auto-skips not-applicable):
+
+```bash
+pnpm config:set software_delivery.gates.overrides.prod-migration-drift.connection_string_env_var=PROD_DATABASE_URL
+pnpm config:set software_delivery.gates.overrides.prod-migration-drift.threshold=5
+# Optional: tighten to BLOCK on drift instead of advisory --skip-gate
+pnpm config:set software_delivery.gates.overrides.prod-migration-drift.skippable=false
+```
+
+Local `wu:prep` impact: zero by default. The gate is registered in the
+default registry alongside the WU-2943 heuristic gates, but
+`checkApplicability` returns `not-applicable` for repos that have not set
+`connection_string_env_var`, so it auto-skips cleanly. CI integration is
+scheduled (e.g. daily) — never on every PR — because it requires prod
+credentials and a reachable DB.
+
+`@lumenflow/cli` ships without a Postgres driver dependency to keep the CLI
+slim. The gate accepts a probe injection seam (`ctx.__prodDriftProbe`) used
+by the scheduled CI workflow to query the prod DB's applied-migrations list;
+when no probe is supplied (e.g. local `wu:prep`), the gate cleanly auto-skips
+under `prereq_strategy: 'auto-skip'`.
+
 ### Lane Management
 
 | Command              | Description                                       |
@@ -788,29 +904,62 @@ behaviour — none of the new gates is applicable, no new commands run.
 | `pnpm agent:log-issue`         | Log issue during agent session              |
 | `pnpm agent:issues-query`      | Query GitHub issues for agent work          |
 
-**ADR-010 control-plane rule:** planning, handoff, execution, reconciliation, finish, and status are separate concerns. Prompt emission is not launch. Worker return is not WU completion. Reconcile live initiative truth against WU status, worktree / branch state, `wu:prep` / `wu:done` or `wu:cleanup`, stamps, and integrity evidence. `mem:inbox` remains the signal channel, not the whole execution ledger.
+**ADR-010 control-plane rule:** planning, handoff, execution, reconciliation, finish, and status are separate concerns. Prompt emission is not launch. Worker return is not WU completion. Reconcile live initiative truth against WU status, worktree / branch state, `pnpm wu:prep` / `pnpm wu:done` or `pnpm wu:cleanup`, stamps, and integrity evidence. `mem:inbox` remains the signal channel, not the whole execution ledger.
+
+#### Plan-time preflight (WU-2942)
+
+`pnpm orchestrate:initiative` emits two preflight sections before agent dispatch so plan-time intelligence catches starvation that used to surface at claim time:
+
+- **File-overlap preflight** — flags WU pairs (or N-tuples) inside a parallel-claimable wave that share a `code_paths` entry. `wu:claim` rejects overlap by default, so a wave with shared paths is silently serial. Resolution: serialize the WUs, split file ownership, or `--force-overlap` knowingly.
+- **Lane-fit suggestions** — when N≥2 WUs in a wave share a lane whose `lock_policy` holds the lane lock (`all` or `active`), only one runs at a time. The advisor calls the same logic as `pnpm wu:infer-lane` and recommends a re-lane via `pnpm wu:edit --id <WU> --lane '<inferred>'` for the contended WUs.
+
+Modes (set via `software_delivery.orchestrate.preflight` in `workspace.yaml`, default `advisory`):
+
+- `advisory` — emit warnings and proceed.
+- `strict` — emit warnings and exit non-zero (also enabled per-run with `--strict-preflight`).
+- `off` — skip preflight scans entirely.
 
 ### 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 distribution:preflight`   | Audit consumer repos for npm-access flip readiness    |
-| `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 lumenflow:disable`        | Reversibly turn enforcement off (hooks become no-ops) |
-| `pnpm lumenflow:enable`         | Re-enable enforcement after `lumenflow:disable`       |
-| `pnpm lumenflow:uninstall`      | Remove LumenFlow files (dry-run by default)           |
-| `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                           |
+| 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 lumenflow:disable`        | Reversibly turn enforcement off (hooks become no-ops)   |
+| `pnpm lumenflow:enable`         | Re-enable enforcement after `lumenflow:disable`         |
+| `pnpm lumenflow:uninstall`      | Remove LumenFlow files (dry-run by default)             |
+| `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                             |
+| `pnpm db:journal-recover`       | Recover drizzle journal collisions (dry-run default)    |
+| `pnpm lumenflow:setup-prereqs`  | Surface external prereqs (e.g. Supabase CLI) post-setup |
+
+#### db:journal-recover (WU-2945)
+
+When two drizzle snapshots share the same `prevId` (chain fork) or journal entries share an `idx`,
+`pnpm db:journal-recover` detects the collision and offers a safe-resequence path. Default mode is
+dry-run; pass `--confirm` to apply. Every actual rewrite emits an audit log under
+`.lumenflow/db-recovery/<timestamp>.log`. Idempotent — re-running on a healthy chain is a no-op.
+
+```bash
+pnpm db:journal-recover                              # show plan
+pnpm db:journal-recover --drizzle-dir packages/db/drizzle
+pnpm db:journal-recover --confirm                    # apply, write audit log
+```
+
+#### Supabase CLI prerequisite (WU-2945)
+
+`pnpm setup` now runs `lumenflow:setup-prereqs` at the end. When the project uses Supabase
+(via `supabase/config.toml` or `@supabase/*` deps), it surfaces a reminder that the Supabase CLI
+is required for `pnpm db:reset` and similar workflows. Non-blocking informational only.
 
 ### Metrics & Flow
 

package/dist/distribution-preflight.js

@@ -1,230 +0,0 @@
-#!/usr/bin/env node
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-/**
- * distribution:preflight CLI Command (WU-2898)
- *
- * Audits every consumer repo that installs @lumenflow/* and reports whether
- * each one is ready for the npm-access flip from "public" to "restricted".
- *
- * For each consumer the preflight checks:
- *   - GitHub: NPM_TOKEN is registered as an Actions secret on the repo
- *     (`gh api repos/<repo>/actions/secrets`), and the repo has a `.npmrc`
- *     wired to the token.
- *   - Azure DevOps: prints a documented manual-check instruction. We cannot
- *     read pipeline secret variables programmatically without standing up an
- *     `az` PAT, so the report flags Azure rows as "needs manual check" so
- *     Tom can verify in the Azure DevOps web UI before the flip.
- *
- * Exits non-zero if any GitHub consumer is missing wiring, or if any Azure
- * DevOps row is unverified. Print a single table and a copy/paste remediation
- * footer so an operator can fix the gap and re-run.
- *
- * Usage:
- *   pnpm distribution:preflight
- *   pnpm distribution:preflight --json
- */
-import { execFileSync } from 'node:child_process';
-import { WU_STATUS } from '@lumenflow/core';
-import chalk from 'chalk';
-import Table from 'cli-table3';
-import { Command } from 'commander';
-export const DEFAULT_CONSUMERS = [
-    { kind: 'github', repo: 'hellmai/lumenflow-dev' },
-    { kind: 'github', repo: 'hellmai/lumenflow-cloud' },
-    { kind: 'github', repo: 'hellmai/patientpath.co.uk' },
-    { kind: 'azure-devops', project: 'skynexe', repo: 'skynexe-hub' },
-    { kind: 'azure-devops', project: 'skynexe', repo: 'skynexe-fund-analyser' },
-    { kind: 'azure-devops', project: 'skynexe', repo: 'skynexe-risk' },
-];
-/**
- * Production GitHub probe. Shells out to `gh` (already required by other
- * lifecycle commands), expecting the operator to be authenticated.
- */
-export const defaultRunGh = (args) => {
-    // sonarjs/no-os-command-from-path: this is a developer-machine CLI tool
-    // intentionally invoked by name so the operator's `gh` install (homebrew,
-    // apt, scoop, etc.) is picked up. Hard-coding an absolute path would
-    // break portability across the Mac/Linux/CI surfaces this script targets.
-    // eslint-disable-next-line sonarjs/no-os-command-from-path
-    return execFileSync('gh', args, {
-        encoding: 'utf8',
-        stdio: ['ignore', 'pipe', 'pipe'],
-    });
-};
-const NPM_TOKEN_NAME = 'NPM_TOKEN';
-/**
- * Probe a single GitHub consumer. Returns a ConsumerReport row.
- *
- * Failure semantics: if `gh` is unauthenticated or the repo is unreachable,
- * we return `npmTokenPresent: false` with a diagnostic note rather than
- * throwing — the preflight should report ALL consumer states in one pass,
- * not abort on the first error.
- */
-export function probeGitHubConsumer(consumer, deps) {
-    const repo = consumer.repo;
-    let npmTokenPresent = false;
-    let npmrcWired = false;
-    const notes = [];
-    // Check 1: repo Actions secrets contain NPM_TOKEN
-    try {
-        const stdout = deps.runGh(['api', `repos/${repo}/actions/secrets`]);
-        const parsed = JSON.parse(stdout);
-        const secrets = parsed.secrets ?? [];
-        npmTokenPresent = secrets.some((s) => s.name === NPM_TOKEN_NAME);
-        if (!npmTokenPresent) {
-            notes.push(`secret ${NPM_TOKEN_NAME} not found on ${repo}`);
-        }
-    }
-    catch (error) {
-        notes.push(`gh secrets probe failed: ${error instanceof Error ? error.message : String(error)}`);
-    }
-    // Check 2: repo root contains a .npmrc with NPM_TOKEN auth
-    try {
-        const stdout = deps.runGh(['api', `repos/${repo}/contents/.npmrc`]);
-        const parsed = JSON.parse(stdout);
-        if (parsed.content && parsed.encoding === 'base64') {
-            const decoded = Buffer.from(parsed.content, 'base64').toString('utf8');
-            npmrcWired = /_authToken=\$\{?NPM_TOKEN\}?/.test(decoded);
-            if (!npmrcWired) {
-                notes.push(`.npmrc found on ${repo} but does not reference NPM_TOKEN`);
-            }
-        }
-        else {
-            notes.push(`.npmrc payload on ${repo} not in expected base64 shape`);
-        }
-    }
-    catch (error) {
-        notes.push(`.npmrc probe failed (${repo}): ${error instanceof Error ? error.message : String(error)}`);
-    }
-    return {
-        repo,
-        platform: 'github',
-        npmTokenPresent,
-        npmrcWired,
-        readyToFlip: npmTokenPresent && npmrcWired,
-        note: notes.join('; ') || 'OK',
-    };
-}
-/**
- * Build the manual-check report row for an Azure DevOps consumer.
- *
- * We deliberately do NOT shell out to `az` here. Authenticating the Azure
- * DevOps CLI requires per-developer PAT setup that the LumenFlow CI surface
- * does not own. Treating the row as "needs manual check" is honest — a false
- * green here would directly cause the consumer pipelines to break on the
- * privatization flip.
- */
-export function buildAzureDevOpsRow(consumer) {
-    const repo = `${consumer.project}/${consumer.repo}`;
-    return {
-        repo,
-        platform: 'azure-devops',
-        npmTokenPresent: null,
-        npmrcWired: null,
-        readyToFlip: null,
-        note: 'manual check required — verify pipeline variable NPM_TOKEN is set as a secret ' +
-            'and that .npmrc is wired in the repo root',
-    };
-}
-/**
- * Run the full preflight against the supplied consumer list. Returns the
- * raw report rows — formatting/exit-code policy is applied by `main`.
- */
-export function runPreflight(consumers, deps = { runGh: defaultRunGh }) {
-    return consumers.map((c) => c.kind === 'github' ? probeGitHubConsumer(c, deps) : buildAzureDevOpsRow(c));
-}
-/**
- * Pretty-print the report as an aligned ASCII table.
- *
- * The status column uses three glyphs:
- *   ready  = both checks passed (GitHub) — safe to flip
- *   FAIL   = GitHub repo missing NPM_TOKEN or .npmrc — fix before flip
- *   manual = Azure DevOps row — operator must verify out-of-band
- */
-export function formatReport(rows) {
-    const table = new Table({
-        head: ['Consumer', 'Platform', 'NPM_TOKEN', '.npmrc', 'Ready', 'Note'],
-        style: { head: [] },
-    });
-    const triBool = (v) => {
-        if (v === null)
-            return chalk.yellow('manual');
-        return v ? chalk.green('yes') : chalk.red('no');
-    };
-    const status = (row) => {
-        if (row.readyToFlip === null)
-            return chalk.yellow('manual');
-        if (row.readyToFlip)
-            return chalk.green(WU_STATUS.READY);
-        return chalk.red('FAIL');
-    };
-    for (const row of rows) {
-        table.push([
-            row.repo,
-            row.platform,
-            triBool(row.npmTokenPresent),
-            triBool(row.npmrcWired),
-            status(row),
-            row.note,
-        ]);
-    }
-    return table.toString();
-}
-/**
- * Compute the exit code policy. Non-zero if any GitHub row failed or any
- * row needs manual verification (since the operator MUST acknowledge the
- * Azure rows before the flip is safe).
- */
-export function computeExitCode(rows) {
-    const anyFail = rows.some((r) => r.readyToFlip === false);
-    const anyManual = rows.some((r) => r.readyToFlip === null);
-    return anyFail || anyManual ? 1 : 0;
-}
-/**
- * CLI entry point. Returns the resolved exit code so tests can assert it
- * without spawning a subprocess.
- */
-export function main(argv = process.argv, deps = { runGh: defaultRunGh }, log = (m) => console.log(m)) {
-    const program = new Command()
-        .name('distribution-preflight')
-        .description('Audit consumer repos for @lumenflow/* privatization readiness (WU-2898)')
-        .option('--json', 'Emit raw JSON instead of an ASCII table', false)
-        .parse(argv);
-    const opts = program.opts();
-    const rows = runPreflight(DEFAULT_CONSUMERS, deps);
-    if (opts.json) {
-        log(JSON.stringify(rows, null, 2));
-    }
-    else {
-        log(formatReport(rows));
-        const failed = rows.filter((r) => r.readyToFlip === false);
-        const manual = rows.filter((r) => r.readyToFlip === null);
-        if (failed.length > 0) {
-            log('');
-            log(chalk.red(`✗ ${failed.length} GitHub consumer(s) not ready:`));
-            for (const r of failed)
-                log(`  - ${r.repo}: ${r.note}`);
-        }
-        if (manual.length > 0) {
-            log('');
-            log(chalk.yellow(`⚠ ${manual.length} Azure DevOps consumer(s) need manual verification:`));
-            for (const r of manual)
-                log(`  - ${r.repo}: ${r.note}`);
-        }
-        if (failed.length === 0 && manual.length === 0) {
-            log('');
-            log(chalk.green('✓ all consumers ready to flip'));
-        }
-    }
-    return computeExitCode(rows);
-}
-// Run when invoked directly (not when imported by tests).
-const isDirectInvocation = import.meta.url === `file://${process.argv[1]}` ||
-    // tsup bundles the CLI as ESM with the bin shim — argv[1] still ends with
-    // distribution-preflight.js so this guard remains correct after build.
-    process.argv[1]?.endsWith('distribution-preflight.js');
-if (isDirectInvocation) {
-    process.exit(main());
-}
-//# sourceMappingURL=distribution-preflight.js.map