@lumenflow/cli 5.4.0 → 5.7.12

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.
 
@@ -205,7 +205,7 @@ intentionally exempt and the workspace policy does not already exclude it.
 ## Core Principles
 
 1. **Design-First** (feature/refactor WUs): Load the `design-first` skill before implementation. Question requirements, delete unnecessary, simplify before optimizing. Invocation varies by vendor — see [Skills & Agents](#skills--agents) below.
-2. **Fit-For-Surface Verification**: Choose the least brittle verification that gives strong confidence. Prefer TDD for runtime logic when repository policy requires it; prefer behavior-focused integration, smoke, visual, or manual verification for UI, content, and presentation work. Never assert inline styles, CSS values, exact copy, or DOM shape in E2E/integration tests.
+2. **Fit-For-Surface Verification**: Choose the least brittle verification that gives strong confidence. Prefer TDD for runtime logic when repository policy requires it; prefer behavior-focused integration, smoke, visual, or manual verification for UI, content, and presentation work. Never assert inline styles, CSS values, exact copy, or DOM shape in E2E/integration tests. For the boundary between framework-owned gates, generated brief content, and consumer-authored local guidance, see [ADR-017](docs/09-architecture-decisions/ADR-017-lumenflow-configurability-principle.md).
 3. **Library-First**: Search existing libraries before custom code
 4. **DRY/SOLID/KISS/YAGNI**: No magic numbers, no hardcoded strings
 5. **Worktree Discipline**: After `wu:claim`, work ONLY in the worktree
@@ -252,17 +252,60 @@ pnpm mem:inbox                    # coordination signals (defaults to unread)
 The memory layer also supports live-session addressing for active agents:
 
 ```bash
-pnpm mem:roster                             # list active session_id/display_name/role rows
-pnpm mem:signal 'please review' --wu WU-XXXX --to Planck
-pnpm mem:inbox --for Planck                 # targeted + broadcast signals for that session
+pnpm mem:roster                             # list active session_id/display_name/agent_identity/role rows
+pnpm mem:signal 'please review' --wu WU-XXXX --to Planck,codex:implementer:host42 --intent PROPOSE --requires-ack
+pnpm mem:inbox --for Planck --thread thread-1234  # directed + broadcast signals for that identity
+pnpm mem:converged --thread thread-1234      # exit 0 when every root recipient replied AGREE
 pnpm mem:context --wu WU-XXXX --no-roster   # opt out when a test needs stable output
 ```
 
+The wire contract for agent-to-agent coordination is `A2A.V1`, exported from
+`@lumenflow/control-plane-sdk/a2a`. Local files under `.lumenflow/memory/`, the
+Claude `PostToolUse` hook, and `mem:watch` are adapters over that contract, not
+separate schemas. `workspace_id` is optional for local worktrees and required
+for hosted transports such as lumenflow.cloud, where it is the tenant/workspace
+routing key.
+
 `display_name` is an ephemeral live-session handle, not a stable role alias. It
 is assigned from `.lumenflow/agents/display-name-pool.yaml` when a session
 starts and released when the session ends. `mem:signal --to` / `mem:inbox --for`
-resolve either a `session_id` or a current `display_name` against the live
-roster before reading or writing `target_agent`.
+accept a `session_id`, current `display_name`, or explicit `agent_identity`.
+`mem:signal --to` also accepts comma-separated recipients. Directed signals are
+persisted as canonical A2A `recipients[]`; `target_agent` remains only as the
+single-recipient legacy alias.
+
+`agent_identity` is an explicit stable reader identity for A2A receipt
+coalescing across restarts or concurrent sessions. Set it with
+`pnpm agent:session --agent-identity <owner>:<role>:<purpose>` or
+`LUMENFLOW_AGENT_IDENTITY`; LumenFlow never derives it from PID, hostname, or
+runtime metadata. When it is absent, receipt state falls back to the ephemeral
+`session_id`.
+
+A2A signal semantics are structured, not prose-only. `mem:signal` supports
+`--thread`, `--reply-to`, `--intent INFO|PROPOSE|COUNTER|AGREE|REJECT`,
+`--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
+`--intent AGREE` or `--intent REJECT` on that thread, the root signal receipt is
+promoted to `acked` or `rejected`, and `mem:converged --thread <id>` reports
+whether every root recipient has agreed. Local JSONL remains only the dev
+adapter over `A2ASignalV1` / `A2AReceiptV1`; lumenflow.cloud should use the same
+contract over its hosted transport.
+
+Claude Code projects with generated LumenFlow hooks receive addressed
+`signal:received` events at the next `PostToolUse` boundary. The hook surfaces
+`intent`, `interrupt_class`, `requires_ack`, and same-thread ACK/REJECT commands
+without replacing the `wu:prep` unread-directed-signal gate. Other local clients
+can run `pnpm mem:watch --session <session_id|display_name|agent_identity>` in
+a side terminal for foreground `signal:received` delivery through the same event
+queue and receipt model.
+
+Before `wu:prep`, any unread directed signal addressed to the current reader on
+the WU or its initiative is a decision point. Read, ACK, or dismiss it before
+continuing. `pnpm wu:prep --allow-unread-signals --reason '<audit reason>'`
+exists for explicit audited overrides only.
 
 ### During the WU (capture, don't hoard)
 
@@ -501,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
 
@@ -552,6 +642,194 @@ For the full worktree lifecycle (parallel execution, bootstrap, isolation guaran
 | `pnpm typecheck`                  | Run TypeScript type checking                               |
 | `pnpm test`                       | Run all tests (Vitest)                                     |
 
+#### Per-gate skip (WU-2925)
+
+`pnpm wu:prep` and `pnpm wu:done` accept `--skip-gate <name>` (repeatable) to
+suppress a single named gate. The legacy `--skip-gates` (binary) is deprecated
+for one minor cycle and emits a deprecation warning pointing to the public
+[Gates Reference](https://lumenflow.dev/reference/gates#per-gate-skip); use
+`--skip-gate` per gate.
+
+```bash
+# Skip a single environmental gate (allow-list)
+pnpm wu:done --id WU-XXX --skip-gate lane-health \
+  --reason "pre-existing 50-file coverage gap" --fix-wu WU-YYY
+
+# Repeat the flag to skip multiple gates
+pnpm wu:prep --id WU-XXX \
+  --skip-gate lane-health --skip-gate migration-verify \
+  --reason "no DB infra in agent worktree" --fix-wu WU-YYY
+```
+
+**Allow-list (skippable: true by default):** `migration-verify`,
+`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
+pnpm config:set software_delivery.gates.overrides.db-dod-gate.skippable=true
+```
+
+Audit format gains a discriminated `source` field
+(`agent` | `auto-skip-not-applicable` | `auto-skip-missing-prereq` | `blocked`)
+and a `lifecycle` field (`prep` | `done`) so the trail spans both lifecycle
+commands. Legacy entries without `source` are read as `agent` for DORA/CFR
+back-compat. CFR (Change Failure Rate) only counts `source: 'agent'` rows;
+auto-skips and blocks are excluded.
+
+MCP exposes both `skip_gate` (array, preferred) and `skip_gates` (boolean,
+deprecated) for one minor cycle, symmetric with the CLI.
+
+#### Discriminated GateResult states (WU-2926)
+
+Each gate run produces one of six `GateResult` discriminated states. Stable
+glyphs/labels (also surfaced verbatim in the public
+[Gates Reference](https://lumenflow.dev/reference/gates#discriminated-gateresult-states)):
+
+| State                         | Glyph               | Meaning                                                                                               |
+| ----------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------- |
+| `passed`                      | ✅ PASSED           | Gate ran successfully.                                                                                |
+| `failed`                      | ❌ FAILED           | Gate ran and failed (or `applicable + missing + skippable + 'fail'`).                                 |
+| `skipped-by-agent`            | ⏭ SKIPPED-BY-AGENT | Explicit `--skip-gate <name>` (audit `source: 'agent'`).                                              |
+| `skipped-auto-not-applicable` | ⊘ AUTO-SKIPPED      | `checkApplicability` returned not-applicable (audit `source: 'auto-skip-not-applicable'`).            |
+| `skipped-auto-missing-prereq` | ⊘ AUTO-SKIPPED      | Applicable + missing prereq + skippable + `'auto-skip'` (audit `source: 'auto-skip-missing-prereq'`). |
+| `blocked-missing-prereq`      | 🚫 BLOCKED          | Applicable + missing prereq + `skippable: false` (audit `source: 'blocked'`, exits non-zero).         |
+
+Decision matrix:
+
+| Applicability  | Preconditions | Skippable | `prereq_strategy` | Result                           |
+| -------------- | ------------- | --------- | ----------------- | -------------------------------- |
+| not-applicable | —             | —         | —                 | `skipped-auto-not-applicable`    |
+| applicable     | satisfied     | —         | —                 | run → `passed` or `failed`       |
+| applicable     | missing       | false     | —                 | `blocked-missing-prereq` (BLOCK) |
+| applicable     | missing       | true      | `'auto-skip'`     | `skipped-auto-missing-prereq`    |
+| applicable     | missing       | true      | `'fail'`          | `failed`                         |
+
+Each `GateDefinition` may implement `checkApplicability` and
+`checkPreconditions`. Defaults return `'applicable'` and `'satisfied'` so
+existing simple gates inherit always-runs semantics with no per-gate code
+change. `safety-critical-test` ships with `skippable_default: false` and a
+default applicability of `'applicable'` for every change set — preserving
+today's runs-on-every-WU behaviour. Per-repo override:
+
+```bash
+# Narrow safety-critical-test applicability without flipping the default
+pnpm config:set software_delivery.gates.overrides.safety-critical-test.applicability_paths \
+  --json-value '["app/security/**","lib/auth/**"]'
+```
+
+Auto-skip + blocked states write audit NDJSON with the discriminated `source`
+field; CFR only counts `source: 'agent'` rows so auto-skips and blocks never
+inflate change-failure-rate.
+
+#### Extended local-prep profile (WU-2927)
+
+`software_delivery.gates.local_prep` is an opt-in profile that extends
+`wu:prep` with the build / integration-test / e2e-smoke gates that previously
+only ran in CI. Driven by lumenflow.cloud's three P0 hotfixes in 24h
+(WU-1497..WU-1499) — each slipped past local gates because `wu:prep` did not
+run `pnpm build`, `pnpm test:integration`, or `pnpm test:e2e --smoke`.
+
+```yaml
+software_delivery:
+  gates:
+    local_prep:
+      build:
+        enabled: false # opt-in: pnpm build on every wu:prep
+      integration_test:
+        enabled: false # opt-in: pnpm test:integration on every wu:prep
+      e2e_smoke:
+        enabled: false # opt-in: pnpm test:e2e --tag <tag>
+        tag: smoke
+      latency_budget_warn_ms: 180000 # 3 min soft warn, never blocks
+```
+
+| Field                       | Default           | Effect                                                                                                                                                                                                                                       |
+| --------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `build.enabled`             | `false`           | When `true`, registers a build gate that runs `pnpm build`. `prereq_strategy: 'fail'` — missing `build` script in `package.json` is a misconfig (`failed`), not an environmental gap.                                                        |
+| `integration_test.enabled`  | `false`           | When `true`, makes the (now unconditionally registered) `integration-test` gate applicable. Runs `RUN_INTEGRATION_TESTS=1 pnpm vitest run '**/*.integration.*' '**/golden-*.test.*'`. Missing script → `failed`.                             |
+| `e2e_smoke.enabled` + `tag` | `false` / `smoke` | When `true` AND `playwright.config.{ts,js,mjs}` exists at repo root, registers an `e2e-smoke` gate that runs `pnpm test:e2e --tag <tag>`. Repos without Playwright are auto `not-applicable` (clean opt-out — no explicit disable required). |
+| `latency_budget_warn_ms`    | `180000`          | `wu:prep` prints total elapsed seconds; if it exceeds the budget, emits a non-failing warning. Soft signal only.                                                                                                                             |
+
+All three gates are added to the `--skip-gate` allow-list (`skippable: true`),
+extending WU-2925's initial `{migration-verify, lane-health, tdd-diff-evidence}`
+set. Rationale: local-prep gates are opt-in environmental gates; agents need
+`--skip-gate <name>` for legitimate hotfix scenarios where the gate is broken
+or irrelevant for that WU. Skips are captured in audit per WU-2925 semantics
+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                                       |
@@ -578,7 +856,9 @@ For the full worktree lifecycle (parallel execution, bootstrap, isolation guaran
 | `pnpm mem:cleanup`    | Clean up stale memory data                 |
 | `pnpm mem:context`    | Get context for current lane/WU            |
 | `pnpm mem:create`     | Create memory node (bug discovery)         |
+| `pnpm mem:converged`  | Check A2A thread agreement                 |
 | `pnpm mem:inbox`      | Check coordination signals                 |
+| `pnpm mem:watch`      | Deliver A2A signal events without hooks    |
 | `pnpm mem:roster`     | List active sessions and display names     |
 | `pnpm mem:summarize`  | Summarize memory context                   |
 | `pnpm mem:triage`     | Triage discovered bugs                     |
@@ -624,28 +904,63 @@ For the full worktree lifecycle (parallel execution, bootstrap, isolation guaran
 | `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 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
 
@@ -678,19 +993,6 @@ For the full worktree lifecycle (parallel execution, bootstrap, isolation guaran
 | `pnpm pack:install`  | Install a domain pack into workspace       |
 | `pnpm pack:search`   | Search for domain packs in a registry      |
 
-### Audited Wrappers
-
-| Command            | Description                      |
-| ------------------ | -------------------------------- |
-| `pnpm file:read`   | Read file with audit trail       |
-| `pnpm file:write`  | Write file with audit trail      |
-| `pnpm file:edit`   | Edit file with audit trail       |
-| `pnpm file:delete` | Delete file with audit trail     |
-| `pnpm git:status`  | Show git status with audit trail |
-| `pnpm git:diff`    | Show git diff with audit trail   |
-| `pnpm git:log`     | Show git log with audit trail    |
-| `pnpm git:branch`  | Show git branch with audit trail |
-
 Commands include **context-aware validation** that checks location, WU status, and git state. When validation fails, commands provide copy-paste ready fix commands.
 
 ---
@@ -728,12 +1030,13 @@ If you're an AI agent, read the onboarding docs:
 Skills are reusable workflow/knowledge bundles that agents load on demand. The `SKILL.md` format pioneered by Claude Code has converged into a de-facto standard adopted by OpenAI Codex (Dec 2025), Cursor (v2.4), and Windsurf Cascade (Jan 2026). LumenFlow stores vendor-neutral skill sources in `.lumenflow/skills/` and projects them to each vendor surface via `pnpm lumenflow:integrate --client <x>`.
 
 Agent plugins are a distribution on-ramp, not a replacement for these repo-level
-projections or for the Software Delivery Pack runtime. Standalone projected
-skills keep local names such as `design-first`, while plugin-installed Claude
-skills use plugin-qualified names such as `/lumenflow:design-first`. If both
-surfaces exist, prompts and handoff text must say which one they mean.
-Installing a plugin gives the agent methodology and entrypoint guidance;
-repo-level enforcement still requires `npx lumenflow init`,
+projections or for the Software Delivery Pack runtime. Per
+[ADR-018](docs/09-architecture-decisions/ADR-018-agent-plugin-distribution-boundary.md),
+standalone projected skills keep local names such as `design-first`, while
+plugin-installed Claude skills use plugin-qualified names such as
+`/lumenflow:design-first`. If both surfaces exist, prompts and handoff text must
+say which one they mean. Installing a plugin gives the agent methodology and
+entrypoint guidance; repo-level enforcement still requires `npx lumenflow init`,
 `pnpm lumenflow:integrate`, or `pnpm lumenflow:integrate --sync`.
 
 ### Core skills (vendor-neutral)
@@ -765,9 +1068,10 @@ For plugin-distributed skills, prefer the vendor's plugin-qualified invocation
 surface instead of rewriting all canonical skill names. Claude Code plugin
 skills are namespaced as `/lumenflow:<skill>`. Codex plugin use should name the
 installed `lumenflow` plugin or one of its bundled skills through Codex's `@`
-plugin selection surface. Standalone projections remain valid until a future
-explicit cleanup command such as `--plugin-only` exists and is run
-intentionally.
+plugin selection surface. **Plugin packaging is scoped under INIT-065 and not
+yet shipped as of 5.4.0** — these invocations apply once the packaging WUs land.
+Standalone projections remain valid until a future explicit cleanup command such
+as `--plugin-only` exists and is run intentionally.
 
 For vendor-specific setup details and per-vendor quirks, see:
 
@@ -811,6 +1115,12 @@ Durable artifacts carry `requested_role` (from the orchestrator) and `actual_rol
 
 ---
 
+## Remote / MCP Dispatch
+
+LumenFlow ships `pnpm file:*` and `pnpm git:*` CLIs (`file:read`, `file:write`, `file:edit`, `file:delete`, `git:status`, `git:diff`, `git:log`, `git:branch`). These commands exist for non-native-tool agents (MCP remote dispatch, server-side sandbox). Local agents with native Read/Edit/Write should use those directly — they're faster and already audited via the client transcript. The wrappers are not part of the canonical local-development CLI surface.
+
+---
+
 ## References
 
 - [LumenFlow Agent Capsule]({{DOCS_OPERATIONS_PATH}}/_frameworks/lumenflow/lumenflow-agent-capsule.md) -- Full framework reference (lifecycle, lanes, gates, DoD)
@@ -819,5 +1129,6 @@ Durable artifacts carry `requested_role` (from the orchestrator) and `actual_rol
 - [.lumenflow/constraints.md](.lumenflow/constraints.md) -- Non-negotiable rules and forbidden commands
 - [WU Sizing Guide]({{DOCS_OPERATIONS_PATH}}/_frameworks/lumenflow/wu-sizing-guide.md) -- Scoping work without needless fragmentation
 - [ADR-014: Typed Agent-Role Contract](docs/09-architecture-decisions/ADR-014-typed-agent-role-contract.md) — Canonical orchestration role vocabulary
+- [ADR-017: LumenFlow Configurability Principle](docs/09-architecture-decisions/ADR-017-lumenflow-configurability-principle.md) — Defaults are allowed; framework prescription must be configurable or consumer-authored
 - [Skills Index](.lumenflow/skills/INDEX.md)
 - [Agents README](.claude/agents/README.md)

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

@@ -146,10 +146,6 @@ These surfaces already assemble the objective, scope, code paths, tests, recover
 constraints block, and evidence metadata. Do not prepend or append a second wrapper block around
 them.
 
-The role aliases referenced by these handoffs are vendor-neutral framework names (`general-purpose`,
-`lumenflow-pm`, `initiative-architect`, and so on). Client-specific overlays may implement those
-aliases differently, but the orchestration brief should keep the shared alias vocabulary intact.
-
 If you are building a fully custom or experimental prompt outside those canonical surfaces, use
 this structure:
 
@@ -218,7 +214,6 @@ Before spawning:
 
 - Confirm WU status and lane availability
 - Ensure worktree exists (or claim first)
-- Use the shared framework alias vocabulary in the brief, not vendor-specific display names
 - Provide explicit code_paths and tests
 - Require `mem:checkpoint` at 50+ tool calls
 - Require `mem:signal` for milestones