@lumenflow/cli 5.4.0 → 5.7.12

package/templates/core/ai/onboarding/agent-safety-card.md.template

@@ -40,28 +40,12 @@ Quick reference for AI agents working in LumenFlow projects.
 | Read WU spec first                   | Understand scope                  |
 | cd to worktree after claim           | Isolation                         |
 | Write tests before code              | TDD                               |
-| Treat unread inbox signals as decisions | Prevent missed redirects       |
 | Run wu:prep in the claimed workspace | Quality and lifecycle correctness |
 | Run wu:done from main                | Complete WU                       |
 | Stay within code_paths               | Scope discipline                  |
 
 ---
 
-## Coordination Signals
-
-`wu:brief` includes an Inbox Snapshot when memory is available. Also check `mem:inbox`
-after checkpoints and before `wu:prep`.
-
-An unread signal is a decision point:
-
-1. Read it.
-2. Decide whether it changes, blocks, or does not affect the WU.
-3. Reply, acknowledge, or dismiss it before continuing.
-
-Do not leave directed signals for `wu:done`; by then the coordination window has already passed.
-
----
-
 ## Universal Safety Mechanisms
 
 ### Git Safety Wrapper
@@ -114,7 +98,69 @@ not guess-and-retry.
 1. Read the error message
 2. Fix the underlying issue
 3. Re-run gates
-4. Never use `--skip-gates` for new failures
+4. Never use `--skip-gate` (or legacy `--skip-gates`) for new failures
+5. WU-2925: prefer `--skip-gate <name>` (repeatable, per-gate) over
+   `--skip-gates` (legacy binary, 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 per-repo at
+   `software_delivery.gates.overrides.<gate_id>.skippable=true` may be skipped.
+   Both flags require `--reason` and `--fix-wu`.
+
+### Skip-vs-Block decision matrix (WU-2926)
+
+The runtime distinguishes six discriminated `GateResult` states with stable
+glyphs. The decision matrix encodes when a gate runs, auto-skips, or BLOCKS:
+
+| Applicability  | Preconditions | Skippable | `prereq_strategy` | Result                           | Glyph |
+| -------------- | ------------- | --------- | ----------------- | -------------------------------- | ----- |
+| 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`                         | ❌    |
+
+Key invariant: `applicable + missing + skippable=false` ALWAYS blocks. This is
+the silent-bypass guard. `--skip-gate <name>` cannot bypass it. The only
+escape hatch is a deliberate per-repo override at
+`software_delivery.gates.overrides.<gate_id>.skippable=true`, used only when
+the missing prerequisite is genuinely environmental (not a missing
+implementation).
+
+Audit NDJSON `source` field discriminates all four non-running outcomes:
+`agent` | `auto-skip-not-applicable` | `auto-skip-missing-prereq` | `blocked`.
+CFR/DORA only counts `source: 'agent'` so auto-skips and blocks never inflate
+change-failure-rate.
+
+### Override syntax (copy-pasteable, WU-2925/2926)
+
+```bash
+# Per-gate skip at wu:prep or wu:done (--skip-gate is repeatable)
+pnpm wu:prep --id WU-XXX --skip-gate lane-health \
+  --reason "no DB infra in agent worktree" --fix-wu WU-YYY
+
+# Make a non-allow-listed gate skippable per repo
+pnpm config:set software_delivery.gates.overrides.<gate_id>.skippable=true
+
+# Narrow a safety-critical gate's reach via applicability_paths
+# (preferred over flipping skippable for safety-critical gates)
+pnpm config:set software_delivery.gates.overrides.safety-critical-test.applicability_paths \
+  --json-value '["app/security/**","lib/auth/**"]'
+```
+
+### Latency-budget guidance (`local_prep` profile, WU-2927)
+
+The opt-in `software_delivery.gates.local_prep` profile extends `wu:prep` with
+`build`, `integration-test`, and `e2e-smoke` gates. All three are
+`skippable: true` and accept `--skip-gate <name>`. Latency budget defaults:
+
+- **`latency_budget_warn_ms: 180000`** (3 min): default soft warn, never blocks.
+- **60–90s**: tight, suits greenfield repos; expect false-positive warnings as
+  suites grow.
+- **5–10 min**: loose, suits monorepos with full Playwright; consider
+  `--skip-gate e2e-smoke` per-WU for cosmetic-only changes.
+
+Public reference: <https://lumenflow.dev/reference/gates#local_prep-profile-550>.
 
 ---
 

package/templates/core/ai/onboarding/initiative-orchestration.md.template

@@ -87,6 +87,10 @@ pnpm wu:brief --id WU-100 --client claude-code
 pnpm wu:delegate --id WU-100 --parent-wu WU-050 --client claude-code
 ```
 
+When the work is initiative decomposition or execution design rather than direct implementation, the
+default framework role to brief or delegate is `initiative-architect`. That role now replaces the
+retired docs-planning vocabulary in the default agent roster.
+
 **Use `wu:delegate` (not `wu:brief`) when:**
 
 - You are the orchestrator agent managing the initiative

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

@@ -39,14 +39,14 @@ pnpm release --release-version 1.3.0 --skip-publish
 
 ### Options
 
-| Flag                        | Description                             |
-| --------------------------- | --------------------------------------- |
-| `--release-version <X.Y.Z>` | **Required.** Semver version to release |
-| `--dry-run`                 | Preview changes without making them     |
+| Flag                        | Description                                  |
+| --------------------------- | -------------------------------------------- |
+| `--release-version <X.Y.Z>` | **Required.** Semver version to release      |
+| `--dry-run`                 | Preview changes without making them          |
 | `--skip-publish`            | Skip npm publish only; validation still runs |
-| `--skip-build`              | Skip build step (use existing dist)     |
-| `--version`, `-V`           | Show CLI version                        |
-| `--help`, `-h`              | Show help                               |
+| `--skip-build`              | Skip build step (use existing dist)          |
+| `--version`, `-V`           | Show CLI version                             |
+| `--help`, `-h`              | Show help                                    |
 
 ### Examples
 

package/templates/core/ai/onboarding/vendor-support.md.template

@@ -31,15 +31,73 @@ lumenflow init
 
 For popular AI coding assistants, LumenFlow provides **optional enhanced integrations** with deeper features like auto-detection, skills, and vendor-specific configurations.
 
-| Assistant   | Config File                    | Auto-detected | Enhanced Features                                                |
-| ----------- | ------------------------------ | ------------- | ---------------------------------------------------------------- |
-| Claude Code | `CLAUDE.md`, `.claude/`        | Yes           | Skills, agents, hooks, settings, A2A `signal:received` delivery |
-| Cursor      | `.cursor/rules/lumenflow.md`   | Yes           | Rules integration; A2A push deferred to `mem:watch`              |
-| Windsurf    | `.windsurf/rules/lumenflow.md` | Yes           | Rules integration; A2A push deferred to `mem:watch`              |
-| Cline       | `.clinerules`                  | No            | Rules file; poll `mem:inbox` for A2A signals                     |
-| Codex       | `AGENTS.md` (native)           | No            | Universal files directly; A2A push deferred to `mem:watch`       |
-| Aider       | `.aider.conf.yml`              | No            | Config file; poll `mem:inbox` for A2A signals                    |
-| Antigravity | `AGENTS.md` (native)           | Unknown       | Research phase                                                   |
+| Assistant   | Config File                                        | Auto-detected | Enhanced Features                                                |
+| ----------- | -------------------------------------------------- | ------------- | ---------------------------------------------------------------- |
+| Claude Code | `CLAUDE.md`, `.claude/`                            | Yes           | Skills, agents, hooks, settings, A2A `signal:received` delivery  |
+| Cursor      | `AGENTS.md`, `.cursor/rules/`                      | Yes           | Rules integration; foreground `mem:watch` A2A delivery           |
+| Windsurf    | `AGENTS.md`, `.agents/skills/`, `.windsurf/rules/` | Yes           | Rules integration plus shared skills; foreground `mem:watch` A2A |
+| Cline       | `.clinerules`                                      | No            | Rules file; foreground `mem:watch` or `mem:inbox` for A2A        |
+| Codex       | `AGENTS.md`, `.agents/skills/`, `.codex/agents/`   | No            | Universal files plus overlays; foreground `mem:watch` A2A        |
+| Aider       | `.aider.conf.yml`                                  | No            | Config file; foreground `mem:watch` or `mem:inbox` for A2A       |
+| Antigravity | `AGENTS.md` (native)                               | Unknown       | Research phase                                                   |
+
+### Shared Cross-Vendor Surfaces
+
+LumenFlow stays vendor-agnostic by anchoring on shared repo surfaces first, then layering
+vendor-specific overlays where a client has extra capabilities.
+
+- `AGENTS.md` is the shared instruction baseline. Codex reads it natively, Cursor and Windsurf
+  both support it as a repo instruction surface, and other vendors can usually consume it as plain
+  project guidance.
+- `.agents/skills/` is the shared skills projection surface. Codex and Windsurf can both consume
+  it today, while Claude Code still uses its own `.claude/skills/` overlay.
+- Vendor overlays stay additive: `.claude/agents/`, `.codex/agents/`, `.cursor/rules/`,
+  `.windsurf/rules/`, and similar files add client-specific behavior on top of the shared
+  instruction and skills layers.
+
+### Agent Plugin Distribution
+
+ADR-018 adds plugin distribution as a discoverability on-ramp for Claude Code and Codex. It does
+not replace the repo-level integration surfaces above and it does not replace the Software Delivery
+Pack runtime.
+
+**Current source identity:**
+
+- Canonical bundle: `plugins/lumenflow/`
+- Claude manifest: `plugins/lumenflow/.claude-plugin/plugin.json`
+- Codex manifest: `plugins/lumenflow/.codex-plugin/plugin.json`
+- Claude repo marketplace catalog: `.claude-plugin/marketplace.json`
+- Codex repo marketplace catalog: `.agents/plugins/marketplace.json`
+
+The `lumenflow-dev` repository is the first release train's marketplace source repository. Do not
+create a separate `lumenflow-marketplace` repository unless ADR-018 is amended.
+
+**Namespace and coexistence rules:**
+
+- Canonical skill authoring remains `.lumenflow/skills/<name>/SKILL.md`.
+- Standalone projections keep local names such as `design-first` and `tdd-workflow`.
+- Claude plugin skills are plugin-qualified, for example `/lumenflow:design-first`.
+- Codex plugin prompts should name the installed `lumenflow` plugin or bundled skill through
+  Codex's `@` plugin selection surface; do not invent a Codex slash namespace.
+- Plugin installation must not delete `.claude/skills/`, `.agents/skills/`, or other standalone
+  projections. A future `--plugin-only` cleanup path must be explicit and dry-run-first.
+
+**First-run handoff:**
+
+The plugin can provide skills, hooks, MCP configuration, and first-run guidance. It cannot install
+`.husky/`, GitHub Actions, WU state, conditional gates, co-change gates, or package aliases inside a
+consumer repository. First-run plugin text must direct users to run `npx lumenflow init` for a new
+repo or `pnpm lumenflow:integrate --sync` in an already initialized repo when they want governed
+workflow state, enforcement, gates, and evidence.
+
+**Marketplace preflight:**
+
+- Anthropic official marketplace submission exists today, so a maintainer must confirm or reserve
+  the `lumenflow` plugin name through the Anthropic submission path before marketplace packaging
+  relies on `/lumenflow:*` names.
+- Codex official self-serve publishing is documented as coming later. Until then, Codex readiness
+  targets repo/personal marketplace install with the `lumenflow` id and an official-directory
+  checklist that does not claim undocumented vendor gates.
 
 ---
 
@@ -70,6 +128,7 @@ Cursor is an AI-first code editor built on VS Code.
 
 **Config Files:**
 
+- `AGENTS.md` - Shared repo instructions
 - `.cursor/rules/lumenflow.md` - LumenFlow rules
 
 **Auto-detection:** Environment variables starting with `CURSOR_`
@@ -86,6 +145,8 @@ Windsurf (Codeium) is an AI IDE with agentic capabilities.
 
 **Config Files:**
 
+- `AGENTS.md` - Shared repo instructions
+- `.agents/skills/` - Shared skills discovered by Windsurf
 - `.windsurf/rules/lumenflow.md` - LumenFlow rules
 
 **Auto-detection:** Environment variables starting with `WINDSURF_`
@@ -114,11 +175,14 @@ lumenflow init --client cline
 
 ### OpenAI Codex
 
-Codex reads the AGENTS.md file directly for universal instructions.
+Codex reads shared repo instructions from `AGENTS.md`, shared skills from `.agents/skills/`, and
+vendor-specific subagent overlays from `.codex/agents/`.
 
 **Config Files:**
 
 - `AGENTS.md` - Universal agent instructions (always created)
+- `.agents/skills/` - Shared skills surface
+- `.codex/agents/` - Codex subagent overlays (explicit invocation only)
 
 **Initialize:**
 

package/templates/vendors/claude/.claude/skills/frontend-design/SKILL.md.template

@@ -2,7 +2,7 @@
 name: frontend-design
 description: Create distinctive, production-grade frontend interfaces. Use when building React components, pages, UI features, or when user requests visual/design work.
 version: 1.0.0
-source: docs/operations/_frameworks/lumenflow/lumenflow-agent-capsule.md
+source: {{DOCS_OPERATIONS_PATH}}/_frameworks/lumenflow/lumenflow-agent-capsule.md
 last_updated: {{DATE}}
 allowed-tools: Read, Write, Edit, Bash
 ---

package/templates/vendors/claude/.claude/skills/wu-lifecycle/SKILL.md.template

@@ -65,6 +65,34 @@ pnpm wu:prune --execute     # Clean stale worktrees
 pnpm wu:cleanup --id WU-XXX # After PR merge
 ```
 
+## Coordination Signal Checkpoints
+
+`wu:brief` includes an Inbox Snapshot for the current WU/session when memory is enabled.
+Treat every unread signal surfaced there, at any `mem:checkpoint`, or before `wu:prep`
+as a decision point, not background noise.
+
+Before continuing after an unread signal:
+
+1. Read the signal context.
+2. Decide whether it changes the work, blocks progress, or is not actionable.
+3. Reply, acknowledge, or dismiss it through `mem:signal` / shared memory before moving on.
+
+Do not wait until `wu:done` to inspect coordination traffic. Mid-flight redirects, peer review,
+and orchestrator-worker handoffs depend on agents consuming signals during the WU.
+
+## A2A Signal Hook Delivery
+
+Claude Code sessions with generated LumenFlow hooks receive directed A2A
+`signal:received` events at the next `PostToolUse` boundary. Treat the hook
+payload the same way as an unread `mem:inbox` result:
+
+1. Read the signal message, `intent`, `interrupt_class`, and WU/thread scope.
+2. If `requires_ack: true`, reply on the same thread with `pnpm mem:signal ... --reply-to <signal_id> --intent AGREE` or `--intent REJECT`.
+3. Continue only after the decision is recorded, unless an explicit `wu:prep --allow-unread-signals --reason '<audit reason>'` override is justified.
+
+Non-hook clients still rely on `wu:brief`, `mem:checkpoint`, and explicit
+`mem:inbox` polling until the daemon fallback lands.
+
 ## wu:prep + wu:done Workflow (WU-1223)
 
 **Two-step completion:**

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);
-  }
-}