@lumenflow/cli 2.12.0 → 2.14.0

package/README.md

@@ -51,130 +51,132 @@ This package provides CLI commands for the LumenFlow workflow framework, includi
 
 ### Work Unit Management
 
-| Command          | Description                                                                 |
-| ---------------- | --------------------------------------------------------------------------- |
-| `wu-block`       | Block a work unit and move it from in-progress to blocked status            |
-| `wu-claim`       | Claim a work unit by creating a worktree/branch and updating status         |
-| `wu-cleanup`     | Clean up worktree and branch after PR merge (PR-based completion workflow)  |
-| `wu-create`      | Create a new Work Unit with micro-worktree isolation (race-safe)            |
-| `wu-delete`      | Safely delete WU YAML files with micro-worktree isolation                   |
-| `wu-deps`        | Visualize WU dependency graph                                               |
-| `wu-done`        | WU Done Helper                                                              |
-| `wu-edit`        | Edit WU spec files with micro-worktree isolation                            |
-| `wu-infer-lane`  | WU Lane Inference CLI (WU-908)                                              |
-| `wu-preflight`   | Fast validation of code_paths and test paths before gates run.              |
-| `wu-prep`        | Prepare WU for completion (run gates in worktree)                           |
-| `wu-proto`       | Create and claim a prototype WU with relaxed validation (rapid prototyping) |
-| `wu-prune`       | WU Prune Utility                                                            |
-| `wu-recover`     | Analyze and fix WU state inconsistencies (WU-1090)                          |
-| `wu-release`     | Release an orphaned WU from in_progress back to ready state for reclaiming  |
-| `wu-repair`      | WU State Repair Tool (Unified - WU-1826, WU-2240)                           |
-| `wu-spawn`       | Generate Task tool invocation for sub-agent WU execution                    |
-| `wu-status`      | Show WU status, location, and valid commands (WU-1090)                      |
-| `wu-unblock`     | Unblock a work unit and move it from blocked to in-progress status          |
-| `wu-unlock-lane` | Safely unlock a lane lock with audit logging                                |
-| `wu-validate`    | Validate WU YAML files against schema (strict mode by default, WU-1329)     |
+| Command          | Description                                   |
+| ---------------- | --------------------------------------------- |
+| `wu-block`       | Block WU with reason                          |
+| `wu-claim`       | Claim WU and create worktree                  |
+| `wu-cleanup`     | Cleanup after PR merge                        |
+| `wu-create`      | Create new WU spec                            |
+| `wu-delete`      | Delete WU spec and cleanup                    |
+| `wu-deps`        | Show WU dependencies                          |
+| `wu-done`        | Complete WU (merge, stamp, cleanup) from main |
+| `wu-edit`        | Edit WU spec fields                           |
+| `wu-infer-lane`  | Infer lane from code paths/description        |
+| `wu-preflight`   | Pre-flight checks before wu:done              |
+| `wu-prep`        | Run gates in worktree, prep for wu:done       |
+| `wu-proto`       | Create WU prototype                           |
+| `wu-prune`       | Clean stale worktrees                         |
+| `wu-recover`     | Analyze and fix WU state inconsistencies      |
+| `wu-release`     | Release orphaned WU (in_progress to ready)    |
+| `wu-repair`      | Repair WU state issues                        |
+| `wu-spawn`       | Generate sub-agent spawn prompt               |
+| `wu-status`      | Show WU status, location, valid commands      |
+| `wu-unblock`     | Unblock WU                                    |
+| `wu-unlock-lane` | Unlock stuck lane                             |
+| `wu-validate`    | Validate WU spec                              |
 
 ### Memory & Session
 
-| Command              | Description                                                   |
-| -------------------- | ------------------------------------------------------------- |
-| `agent-issues-query` | Query logged issues from agent sessions                       |
-| `agent-log-issue`    | Log an issue encountered during agent work                    |
-| `agent-session`      | Start an agent session for a WU                               |
-| `agent-session-end`  | End an agent session                                          |
-| `mem-checkpoint`     | Create a checkpoint node for context snapshots                |
-| `mem-cleanup`        | Prune closed memory nodes based on lifecycle policy and TTL   |
-| `mem-context`        | Generate context injection block for wu:spawn prompts         |
-| `mem-create`         | Create a memory node with optional provenance tracking        |
-| `mem-delete`         | Delete memory nodes (soft delete via metadata.status=deleted) |
-| `mem-export`         | Export memory nodes as markdown or JSON                       |
-| `mem-inbox`          | Read coordination signals from other agents                   |
-| `mem-init`           | Initialize memory layer in repository                         |
-| `mem-ready`          | Query ready nodes for a WU (deterministic ordering)           |
-| `mem-signal`         | Send a coordination signal to other agents                    |
-| `mem-start`          | Create a session node linked to a WU                          |
-| `mem-summarize`      | Rollup older memory nodes into summary nodes for compaction   |
-| `mem-triage`         | Review discovery nodes and promote to WUs or archive          |
+| Command              | Description                                |
+| -------------------- | ------------------------------------------ |
+| `agent-issues-query` | Query GitHub issues for agent work         |
+| `agent-log-issue`    | Log issue during agent session             |
+| `agent-session`      | Start agent session                        |
+| `agent-session-end`  | End agent session                          |
+| `mem-checkpoint`     | Save progress checkpoint                   |
+| `mem-cleanup`        | Clean up stale memory data                 |
+| `mem-context`        | Get context for current lane/WU            |
+| `mem-create`         | Create memory node (bug discovery)         |
+| `mem-delete`         | Delete/archive a memory node               |
+| `mem-export`         | Export memory as markdown                  |
+| `mem-inbox`          | Check coordination signals                 |
+| `mem-init`           | Initialize memory for WU                   |
+| `mem-ready`          | Check pending memory nodes                 |
+| `mem-recover`        | Generate recovery context after compaction |
+| `mem-signal`         | Broadcast coordination signal              |
+| `mem-start`          | Start a memory session                     |
+| `mem-summarize`      | Summarize memory context                   |
+| `mem-triage`         | Triage discovered bugs                     |
 
 ### Initiative Orchestration
 
-| Command                      | Description                                                        |
-| ---------------------------- | ------------------------------------------------------------------ |
-| `initiative-add-wu`          | Link one or more WUs to an initiative bidirectionally              |
-| `initiative-bulk-assign-wus` | Bulk-assign orphaned WUs to initiatives based on lane prefix rules |
-| `initiative-create`          | Create a new Initiative with micro-worktree isolation (race-safe)  |
-| `initiative-edit`            | Edit Initiative YAML files with micro-worktree isolation           |
-| `initiative-list`            | List all initiatives with progress percentages                     |
-| `initiative-plan`            | Link a plan file to an initiative                                  |
-| `initiative-status`          | Show detailed initiative view with phases and WUs                  |
-| `orchestrate-init-status`    | Show initiative orchestration status                               |
-| `orchestrate-initiative`     | Orchestrate initiative execution with agents                       |
-| `orchestrate-monitor`        | Monitor spawned agent progress and signals                         |
-| `spawn-list`                 | Display spawn trees for WUs or initiatives                         |
+| Command                      | Description                      |
+| ---------------------------- | -------------------------------- |
+| `initiative-add-wu`          | Add WU to initiative             |
+| `initiative-bulk-assign-wus` | Bulk assign WUs to initiative    |
+| `initiative-create`          | Create new initiative            |
+| `initiative-edit`            | Edit initiative fields           |
+| `initiative-list`            | List all initiatives             |
+| `initiative-plan`            | Link plan to initiative          |
+| `initiative-status`          | Show initiative status           |
+| `orchestrate-init-status`    | Compact initiative progress view |
+| `orchestrate-initiative`     | Orchestrate initiative execution |
+| `orchestrate-monitor`        | Monitor spawn/agent activity     |
+| `spawn-list`                 | List active spawned agents       |
 
 ### Metrics & Analytics
 
-| Command            | Description                                     |
-| ------------------ | ----------------------------------------------- |
-| `flow-bottlenecks` | Identify workflow bottlenecks and critical path |
-| `flow-report`      | Generate DORA metrics flow report               |
-| `metrics`          | Unified Metrics CLI with subcommands (WU-1110)  |
-| `metrics-snapshot` | Capture current metrics snapshot for dashboards |
+| Command            | Description                  |
+| ------------------ | ---------------------------- |
+| `flow-bottlenecks` | Identify flow bottlenecks    |
+| `flow-report`      | Generate flow metrics report |
+| `metrics`          | View workflow metrics        |
+| `metrics-snapshot` | Capture metrics snapshot     |
 
 ### Lane Tooling
 
-| Command        | Description                                        |
-| -------------- | -------------------------------------------------- |
-| `lane-health`  | Check lane configuration health (WU-1188)          |
-| `lane-suggest` | Suggest lane definitions based on codebase context |
+| Command        | Description                 |
+| -------------- | --------------------------- |
+| `lane-health`  | Check lane config health    |
+| `lane-suggest` | Suggest lane for code paths |
 
 ### Verification & Gates
 
-| Command | Description                                                                                |
-| ------- | ------------------------------------------------------------------------------------------ |
-| `gates` | Run quality gates with support for docs-only mode, incremental linting, and tiered testing |
+| Command              | Description                   |
+| -------------------- | ----------------------------- |
+| `gates`              | Run all quality gates         |
+| `lumenflow-gates`    | Run all quality gates (alias) |
+| `lumenflow-validate` | Run validation checks (alias) |
+| `validate`           | Run validation checks         |
 
 ### System & Setup
 
-| Command                    | Description                                                                       |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| `backlog-prune`            | Backlog Prune Command                                                             |
-| `init-plan`                | Link a plan file to an initiative                                                 |
-| `lumenflow`                | Initialize LumenFlow in a project\n\n                                             |
-| `lumenflow-commands`       | List all available LumenFlow CLI commands                                         |
-| `lumenflow-docs-sync`      | Sync agent onboarding docs to existing projects (skips existing files by default) |
-| `lumenflow-doctor`         | Check LumenFlow safety components and configuration                               |
-| `lumenflow-init`           | Initialize LumenFlow in a project\n\n                                             |
-| `lumenflow-integrate`      | Integrate LumenFlow enforcement with AI client tools                              |
-| `lumenflow-metrics`        | Unified Metrics CLI with subcommands (WU-1110)                                    |
-| `lumenflow-release`        | Release Command                                                                   |
-| `lumenflow-sync-templates` | Sync internal docs to CLI templates for release-cycle maintenance                 |
-| `lumenflow-upgrade`        | LumenFlow Upgrade CLI Command                                                     |
-| `lumenflow-validate`       |                                                                                   |
-| `plan-create`              | Create a new plan file in repo plansDir                                           |
-| `plan-edit`                | Edit a section in a plan file                                                     |
-| `plan-link`                | Link a plan file to a WU or initiative                                            |
-| `plan-promote`             | Promote a plan to approved status                                                 |
-| `signal-cleanup`           | Prune old signals based on TTL policy to prevent unbounded growth                 |
-| `state-bootstrap`          | State Bootstrap Command                                                           |
-| `state-cleanup`            | Orchestrate all state cleanup: signals, memory, events                            |
-| `state-doctor`             | Check state integrity and optionally repair issues                                |
-| `sync-templates`           | Sync internal docs to CLI templates for release-cycle maintenance                 |
-| `validate`                 |                                                                                   |
+| Command                    | Description                               |
+| -------------------------- | ----------------------------------------- |
+| `backlog-prune`            | Clean stale backlog entries               |
+| `init-plan`                | Link plan to initiative (alias)           |
+| `lumenflow`                | Initialize LumenFlow in a project         |
+| `lumenflow-commands`       | List all available CLI commands           |
+| `lumenflow-docs-sync`      | Sync agent docs (for upgrades) (alias)    |
+| `lumenflow-doctor`         | Diagnose LumenFlow configuration          |
+| `lumenflow-init`           | Initialize LumenFlow in a project (alias) |
+| `lumenflow-integrate`      | Generate enforcement hooks for client     |
+| `lumenflow-metrics`        | View workflow metrics (alias)             |
+| `lumenflow-release`        | Run release workflow                      |
+| `lumenflow-sync-templates` | Sync templates to project                 |
+| `lumenflow-upgrade`        | Upgrade LumenFlow packages                |
+| `plan-create`              | Create a new plan                         |
+| `plan-edit`                | Edit plan content                         |
+| `plan-link`                | Link plan to WU or initiative             |
+| `plan-promote`             | Promote plan to WU                        |
+| `signal-cleanup`           | Clean up stale signals                    |
+| `state-bootstrap`          | Bootstrap state store                     |
+| `state-cleanup`            | Clean up stale state data                 |
+| `state-doctor`             | Diagnose state store issues               |
+| `sync-templates`           | Sync templates to project (alias)         |
 
 ### File & Git Operations
 
-| Command       | Description          |
-| ------------- | -------------------- |
-| `file-delete` | File Delete CLI Tool |
-| `file-edit`   | File Edit CLI Tool   |
-| `file-read`   | File Read CLI Tool   |
-| `file-write`  | File Write CLI Tool  |
-| `git-branch`  | Git Branch CLI Tool  |
-| `git-diff`    | Git Diff CLI Tool    |
-| `git-log`     | Git Log CLI Tool     |
-| `git-status`  | Git Status CLI Tool  |
+| Command       | Description                      |
+| ------------- | -------------------------------- |
+| `file-delete` | Delete file with audit trail     |
+| `file-edit`   | Edit file with audit trail       |
+| `file-read`   | Read file with audit trail       |
+| `file-write`  | Write file with audit trail      |
+| `git-branch`  | Show git branch with audit trail |
+| `git-diff`    | Show git diff with audit trail   |
+| `git-log`     | Show git log with audit trail    |
+| `git-status`  | Show git status with audit trail |
 
 <!-- END AUTO-GENERATED SECTION -->
 
@@ -279,5 +281,3 @@ For detailed upgrade instructions, migration guides, and troubleshooting, see [U
 ## License
 
 Apache-2.0
-
-<!-- MODIFIED -->

package/dist/gates-graceful-degradation.js

@@ -0,0 +1,151 @@
+/**
+ * Gates Graceful Degradation
+ *
+ * WU-1520: When gate scripts (format:check, lint, typecheck, spec:linter)
+ * are missing from package.json, emit a warning and skip instead of failing.
+ *
+ * Defense in depth: even if scaffold adds scripts, gates should degrade
+ * gracefully for any missing script.
+ *
+ * @module gates-graceful-degradation
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * Scripts that can be skipped when missing from package.json.
+ * These are optional tooling scripts that not every project configures.
+ */
+export const SKIPPABLE_GATE_SCRIPTS = [
+    'format:check',
+    'lint',
+    'typecheck',
+    'spec:linter',
+];
+/**
+ * Gates that are never skippable, regardless of configuration.
+ * These enforce critical invariants and must always run.
+ */
+export const NON_SKIPPABLE_GATES = ['invariants'];
+/**
+ * Check whether a script exists in a package.json scripts object.
+ *
+ * @param scriptName - The script name to check (e.g., 'lint', 'format:check')
+ * @param scripts - The scripts object from package.json, or undefined
+ * @returns true if the script exists
+ */
+export function checkScriptExists(scriptName, scripts) {
+    if (!scripts)
+        return false;
+    return Object.prototype.hasOwnProperty.call(scripts, scriptName);
+}
+/**
+ * Load the scripts object from a package.json file.
+ *
+ * @param projectRoot - Project root directory containing package.json
+ * @returns The scripts object, or undefined if package.json is missing or unreadable
+ */
+export function loadPackageJsonScripts(projectRoot) {
+    const packageJsonPath = path.join(projectRoot, 'package.json');
+    if (!existsSync(packageJsonPath))
+        return undefined;
+    try {
+        const content = readFileSync(packageJsonPath, 'utf8');
+        const pkg = JSON.parse(content);
+        return pkg.scripts;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Build a human-readable warning message for a missing gate script.
+ * Includes instructions on how to add the missing script.
+ *
+ * @param scriptName - The missing script name
+ * @returns Warning message string
+ */
+export function buildMissingScriptWarning(scriptName) {
+    const suggestions = {
+        'format:check': '"format:check": "prettier --check ."',
+        lint: '"lint": "eslint ."',
+        typecheck: '"typecheck": "tsc --noEmit"',
+        'spec:linter': '"spec:linter": "node tools/spec-linter.js"',
+    };
+    const suggestion = suggestions[scriptName] ?? `"${scriptName}": "<your-command>"`;
+    return [
+        `Warning: "${scriptName}" script not found in package.json - skipping gate.`,
+        `  To enable this gate, add to your package.json scripts:`,
+        `    ${suggestion}`,
+    ].join('\n');
+}
+/**
+ * Determine whether a gate should be skipped due to a missing script.
+ *
+ * @param gateName - The gate name (e.g., 'lint', 'invariants')
+ * @param scriptName - The underlying script name, or null for non-script gates
+ * @param scripts - The scripts object from package.json
+ * @param strict - When true, missing scripts cause a hard failure instead of skip
+ * @returns 'skip' if the gate should be skipped, 'run' if it should run, 'fail' if strict mode failure
+ */
+export function resolveGateAction(gateName, scriptName, scripts, strict) {
+    // Non-skippable gates always run
+    if (NON_SKIPPABLE_GATES.includes(gateName)) {
+        return 'run';
+    }
+    // If no script name is associated (e.g., custom run functions), always run
+    if (!scriptName) {
+        return 'run';
+    }
+    // If script exists, run it
+    if (checkScriptExists(scriptName, scripts)) {
+        return 'run';
+    }
+    // Script is missing
+    if (strict) {
+        return 'fail';
+    }
+    return 'skip';
+}
+/**
+ * Format a summary of gate results showing passed, skipped, and failed gates.
+ *
+ * @param results - Array of gate results
+ * @returns Formatted summary string
+ */
+export function formatGateSummary(results) {
+    if (results.length === 0) {
+        return 'No gates were executed.';
+    }
+    const passed = results.filter((r) => r.status === 'passed');
+    const skipped = results.filter((r) => r.status === 'skipped');
+    const failed = results.filter((r) => r.status === 'failed');
+    const warned = results.filter((r) => r.status === 'warned');
+    const lines = [];
+    lines.push('Gate Summary:');
+    lines.push('');
+    for (const result of results) {
+        const statusIcon = result.status === 'passed'
+            ? 'PASS'
+            : result.status === 'skipped'
+                ? 'SKIP'
+                : result.status === 'warned'
+                    ? 'WARN'
+                    : 'FAIL';
+        const duration = result.durationMs > 0 ? ` (${result.durationMs}ms)` : '';
+        const reason = result.reason ? ` - ${result.reason}` : '';
+        lines.push(`  [${statusIcon}] ${result.name}${duration}${reason}`);
+    }
+    lines.push('');
+    const parts = [];
+    if (passed.length > 0)
+        parts.push(`${passed.length} passed`);
+    if (skipped.length > 0)
+        parts.push(`${skipped.length} skipped`);
+    if (warned.length > 0)
+        parts.push(`${warned.length} warned`);
+    if (failed.length > 0)
+        parts.push(`${failed.length} failed`);
+    lines.push(parts.join(', '));
+    return lines.join('\n');
+}
+//# sourceMappingURL=gates-graceful-degradation.js.map

package/dist/gates-graceful-degradation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gates-graceful-degradation.js","sourceRoot":"","sources":["../src/gates-graceful-degradation.ts"],"names":[],"mappings":"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"}

package/dist/gates.js

@@ -71,6 +71,8 @@ import { runLaneHealthCheck } from './lane-health.js';
 // WU-1315: Onboarding smoke test
 import { runOnboardingSmokeTestGate } from './onboarding-smoke-test.js';
 import { BRANCHES, PACKAGES, PKG_MANAGER, ESLINT_FLAGS, ESLINT_COMMANDS, ESLINT_DEFAULTS, SCRIPTS, CACHE_STRATEGIES, DIRECTORIES, GATE_NAMES, GATE_COMMANDS, CLI_MODES, EXIT_CODES, FILE_SYSTEM, PRETTIER_ARGS, PRETTIER_FLAGS, } from '@lumenflow/core/dist/wu-constants.js';
+// WU-1520: Gates graceful degradation for missing optional scripts
+import { checkScriptExists, buildMissingScriptWarning, loadPackageJsonScripts, resolveGateAction, formatGateSummary, SKIPPABLE_GATE_SCRIPTS, } from './gates-graceful-degradation.js';
 /**
  * WU-1087: Gates-specific option definitions for createWUParser.
  * Exported for testing and consistency with other CLI commands.
@@ -107,6 +109,12 @@ export const GATES_OPTIONS = {
         flags: '--verbose',
         description: 'Stream output in agent mode instead of logging to file',
     },
+    // WU-1520: --strict flag makes missing scripts a hard failure for CI
+    strict: {
+        name: 'strict',
+        flags: '--strict',
+        description: 'Fail on missing gate scripts instead of skipping (for CI enforcement)',
+    },
 };
 /**
  * WU-1087: Parse gates options using createWUParser for consistency.
@@ -142,6 +150,7 @@ export function parseGatesOptions() {
             fullCoverage: opts.fullCoverage,
             coverageMode: opts.coverageMode ?? 'block',
             verbose: opts.verbose,
+            strict: opts.strict,
         };
     }
     finally {
@@ -1114,6 +1123,11 @@ async function executeGates(opts) {
     const laneHealthMode = loadLaneHealthConfig(process.cwd());
     // WU-1356: Resolve configured gates commands for test execution
     const configuredGatesCommands = resolveGatesCommands(process.cwd());
+    // WU-1520: Strict mode and script existence checking for graceful degradation
+    const isStrict = opts.strict || false;
+    const packageJsonScripts = loadPackageJsonScripts(process.cwd());
+    // WU-1520: Track gate results for summary
+    const gateResults = [];
     if (useAgentMode) {
         console.log(`🧾 gates (agent mode): output -> ${agentLog.logPath} (use --verbose for streaming)\n`);
     }
@@ -1153,12 +1167,17 @@ async function executeGates(opts) {
     }
     // Determine which gates to run
     // WU-2252: Invariants gate runs FIRST and is included in both docs-only and regular modes
+    // WU-1520: scriptName field maps gates to their package.json script for existence checking
     const gates = effectiveDocsOnly
         ? [
             // WU-2252: Invariants check runs first (non-bypassable)
             { name: GATE_NAMES.INVARIANTS, cmd: GATE_COMMANDS.INVARIANTS },
-            { name: GATE_NAMES.FORMAT_CHECK, run: runFormatCheckGate },
-            { name: GATE_NAMES.SPEC_LINTER, run: runSpecLinterGate },
+            {
+                name: GATE_NAMES.FORMAT_CHECK,
+                run: runFormatCheckGate,
+                scriptName: SCRIPTS.FORMAT_CHECK,
+            },
+            { name: GATE_NAMES.SPEC_LINTER, run: runSpecLinterGate, scriptName: SCRIPTS.SPEC_LINTER },
             // WU-1467: prompts:lint removed -- was a stub (exit 0), not an authoritative gate
             { name: GATE_NAMES.BACKLOG_SYNC, run: runBacklogSyncGate },
             // WU-2315: System map validation (warn-only until orphan docs are indexed)
@@ -1201,13 +1220,22 @@ async function executeGates(opts) {
         : [
             // WU-2252: Invariants check runs first (non-bypassable)
             { name: GATE_NAMES.INVARIANTS, cmd: GATE_COMMANDS.INVARIANTS },
-            { name: GATE_NAMES.FORMAT_CHECK, run: runFormatCheckGate },
+            {
+                name: GATE_NAMES.FORMAT_CHECK,
+                run: runFormatCheckGate,
+                scriptName: SCRIPTS.FORMAT_CHECK,
+            },
             {
                 name: GATE_NAMES.LINT,
                 cmd: isFullLint ? pnpmCmd(SCRIPTS.LINT) : GATE_COMMANDS.INCREMENTAL,
+                scriptName: SCRIPTS.LINT,
+            },
+            {
+                name: GATE_NAMES.TYPECHECK,
+                cmd: pnpmCmd(SCRIPTS.TYPECHECK),
+                scriptName: SCRIPTS.TYPECHECK,
             },
-            { name: GATE_NAMES.TYPECHECK, cmd: pnpmCmd(SCRIPTS.TYPECHECK) },
-            { name: GATE_NAMES.SPEC_LINTER, run: runSpecLinterGate },
+            { name: GATE_NAMES.SPEC_LINTER, run: runSpecLinterGate, scriptName: SCRIPTS.SPEC_LINTER },
             // WU-1467: prompts:lint removed -- was a stub (exit 0), not an authoritative gate
             { name: GATE_NAMES.BACKLOG_SYNC, run: runBacklogSyncGate },
             { name: GATE_NAMES.SUPABASE_DOCS_LINTER, run: runSupabaseDocsGate },
@@ -1278,6 +1306,32 @@ async function executeGates(opts) {
     let lastFormatCheckFiles = null;
     for (const gate of gates) {
         let result;
+        // WU-1520: Check if the gate's underlying script exists in package.json
+        const gateScriptName = gate.scriptName ?? null;
+        const gateAction = resolveGateAction(gate.name, gateScriptName, packageJsonScripts, isStrict);
+        if (gateAction === 'skip') {
+            const logLine = makeGateLogger({ agentLog, useAgentMode });
+            const warningMsg = buildMissingScriptWarning(gateScriptName);
+            logLine(`\n${warningMsg}\n`);
+            gateResults.push({
+                name: gate.name,
+                status: 'skipped',
+                durationMs: 0,
+                reason: 'script not found in package.json',
+            });
+            continue;
+        }
+        if (gateAction === 'fail') {
+            const logLine = makeGateLogger({ agentLog, useAgentMode });
+            logLine(`\n❌ "${gateScriptName}" script not found in package.json (--strict mode)\n`);
+            gateResults.push({
+                name: gate.name,
+                status: 'failed',
+                durationMs: 0,
+                reason: 'script not found in package.json (strict mode)',
+            });
+            die(`${gate.name} failed: missing script "${gateScriptName}" in package.json (--strict mode requires all gate scripts)`);
+        }
         if (gate.run) {
             result = await gate.run({ agentLog, useAgentMode });
             if (gate.name === GATE_NAMES.FORMAT_CHECK) {
@@ -1328,6 +1382,13 @@ async function executeGates(opts) {
                 else {
                     writeSync(agentLog.logFd, `\n${msg}\n\n`);
                 }
+                // WU-1520: Track skipped coverage gate in summary
+                gateResults.push({
+                    name: gate.name,
+                    status: 'skipped',
+                    durationMs: 0,
+                    reason: 'changed tests - coverage is partial',
+                });
                 continue;
             }
             // WU-1433: Special handling for coverage gate
@@ -1382,11 +1443,26 @@ async function executeGates(opts) {
                 else {
                     writeSync(agentLog.logFd, `\n${warnMsg}\n\n`);
                 }
+                // WU-1520: Track warned gates in summary
+                gateResults.push({
+                    name: gate.name,
+                    status: 'warned',
+                    durationMs: result.duration,
+                });
                 continue;
             }
             if (gate.name === GATE_NAMES.FORMAT_CHECK) {
                 emitFormatCheckGuidance({ agentLog, useAgentMode, files: lastFormatCheckFiles });
             }
+            // WU-1520: Track failed gate before dying
+            gateResults.push({
+                name: gate.name,
+                status: 'failed',
+                durationMs: result.duration,
+            });
+            // WU-1520: Print summary before failing
+            const logLine = makeGateLogger({ agentLog, useAgentMode });
+            logLine(`\n${formatGateSummary(gateResults)}\n`);
             if (useAgentMode) {
                 const tail = readLogTail(agentLog.logPath);
                 console.error(`\n❌ ${gate.name} failed (agent mode). Log: ${agentLog.logPath}\n`);
@@ -1396,11 +1472,20 @@ async function executeGates(opts) {
             }
             die(`${gate.name} failed`);
         }
+        // WU-1520: Track passed gate
+        gateResults.push({
+            name: gate.name,
+            status: 'passed',
+            durationMs: result.duration,
+        });
     }
     // WU-2064: Create/update gates-latest.log symlink for easy agent access
     if (agentLog) {
         updateGatesLatestSymlink({ logPath: agentLog.logPath, cwd: process.cwd(), env: process.env });
     }
+    // WU-1520: Print gate summary showing passed/skipped/failed/warned
+    const summaryLogLine = makeGateLogger({ agentLog, useAgentMode });
+    summaryLogLine(`\n${formatGateSummary(gateResults)}`);
     if (!useAgentMode) {
         console.log('\n✅ All gates passed!\n');
     }