@lumenflow/cli 5.5.0 → 5.7.12

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,63 @@ 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 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                             |
+| `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/packs/agent-runtime/agent-heartbeat.ts

@@ -1,163 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-
-export interface HeartbeatHealth {
-  busy?: boolean;
-  stalled?: boolean;
-  last_progress_at?: string;
-}
-
-export interface HeartbeatAssignment {
-  wu_id: string;
-  action: 'claim' | 'continue' | 'abort';
-  hint?: string;
-}
-
-export interface AgentHeartbeatInput {
-  workspace_id: string;
-  session_id: string;
-  agent_id?: string;
-  wu_id?: string;
-  health?: HeartbeatHealth;
-}
-
-export interface AgentHeartbeatResult {
-  status: 'ok';
-  server_time: string;
-  next_heartbeat_ms?: number;
-  assignment?: HeartbeatAssignment;
-  budget_remaining_usd?: number;
-  coalesced_signals?: number;
-}
-
-export interface AgentHeartbeatPort {
-  heartbeat(input: AgentHeartbeatInput): Promise<AgentHeartbeatResult>;
-}
-
-export interface HeartbeatManagerOptions {
-  maxAttempts?: number;
-  baseBackoffMs?: number;
-  maxBackoffMs?: number;
-  sleepFn?: (delayMs: number) => Promise<void>;
-  logger?: Pick<Console, 'warn'>;
-}
-
-const DEFAULT_MAX_ATTEMPTS = 3;
-const DEFAULT_BASE_BACKOFF_MS = 500;
-const DEFAULT_MAX_BACKOFF_MS = 30_000;
-
-function defaultSleep(delayMs: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, delayMs));
-}
-
-/**
- * Enforces single-flight heartbeat execution and coalesces concurrent signals
- * into one follow-up heartbeat, with retry/backoff on transient failures.
- */
-export class HeartbeatManager {
-  private readonly maxAttempts: number;
-  private readonly baseBackoffMs: number;
-  private readonly maxBackoffMs: number;
-  private readonly sleepFn: (delayMs: number) => Promise<void>;
-  private readonly logger?: Pick<Console, 'warn'>;
-
-  private inFlight: Promise<AgentHeartbeatResult> | null = null;
-  private queuedInput: AgentHeartbeatInput | null = null;
-  private queuedSignals = 0;
-  private consecutiveFailures = 0;
-
-  public constructor(
-    private readonly port: AgentHeartbeatPort,
-    options: HeartbeatManagerOptions = {},
-  ) {
-    this.maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
-    this.baseBackoffMs = options.baseBackoffMs ?? DEFAULT_BASE_BACKOFF_MS;
-    this.maxBackoffMs = options.maxBackoffMs ?? DEFAULT_MAX_BACKOFF_MS;
-    this.sleepFn = options.sleepFn ?? defaultSleep;
-    this.logger = options.logger;
-  }
-
-  public async heartbeat(input: AgentHeartbeatInput): Promise<AgentHeartbeatResult> {
-    if (this.inFlight) {
-      this.queuedInput = input;
-      this.queuedSignals += 1;
-      return this.inFlight;
-    }
-
-    const request = this.drainQueue(input);
-    this.inFlight = request;
-    try {
-      return await request;
-    } finally {
-      this.inFlight = null;
-    }
-  }
-
-  public getState(): {
-    inFlight: boolean;
-    queuedSignals: number;
-    consecutiveFailures: number;
-  } {
-    return {
-      inFlight: this.inFlight !== null,
-      queuedSignals: this.queuedSignals,
-      consecutiveFailures: this.consecutiveFailures,
-    };
-  }
-
-  private async drainQueue(initialInput: AgentHeartbeatInput): Promise<AgentHeartbeatResult> {
-    let currentInput = initialInput;
-    let localCoalescedSignals = 0;
-
-    while (true) {
-      const result = await this.sendWithRetry(currentInput);
-      const queuedInput = this.queuedInput;
-      localCoalescedSignals += this.queuedSignals;
-      this.queuedInput = null;
-      this.queuedSignals = 0;
-
-      if (!queuedInput) {
-        const mergedCoalesced = (result.coalesced_signals ?? 0) + localCoalescedSignals;
-        if (mergedCoalesced > 0) {
-          return {
-            ...result,
-            coalesced_signals: mergedCoalesced,
-          };
-        }
-        return result;
-      }
-
-      currentInput = queuedInput;
-    }
-  }
-
-  private async sendWithRetry(input: AgentHeartbeatInput): Promise<AgentHeartbeatResult> {
-    let attempt = 0;
-
-    while (true) {
-      try {
-        const result = await this.port.heartbeat(input);
-        this.consecutiveFailures = 0;
-        return result;
-      } catch (error) {
-        this.consecutiveFailures += 1;
-        attempt += 1;
-
-        if (attempt >= this.maxAttempts) {
-          throw error;
-        }
-
-        const delayMs = this.getBackoffDelayMs();
-        this.logger?.warn?.(
-          `[agent:heartbeat] attempt ${attempt} failed; retrying in ${delayMs}ms`,
-        );
-        await this.sleepFn(delayMs);
-      }
-    }
-  }
-
-  private getBackoffDelayMs(): number {
-    const exponent = Math.max(0, this.consecutiveFailures - 1);
-    return Math.min(this.baseBackoffMs * 2 ** exponent, this.maxBackoffMs);
-  }
-}