javi-forge 1.13.0 → 1.15.0

package/dist/cli/dispatch/ci.js

@@ -103,6 +103,33 @@ export async function handleCi(cli, ctx) {
             : cli.flags.quick
                 ? "quick"
                 : "full";
+    // Headless gate-run JSON (slice 4): `--json` on the RUN path is a NEW branch,
+    // NOT flag reuse — the flag is otherwise consumed only by `ci validate`. It
+    // bypasses the Ink render, drives the gate phase collecting structured
+    // outcomes, prints `{ ok, gates }`, and sets the process exit code EXPLICITLY
+    // (CI.tsx's error boundary is unreachable without a render, so this branch
+    // owns its exit code). `ok` is false iff a BLOCKING gate errored.
+    //
+    // JDA-A-002 / JDB-101: `ok` is deliberately scoped to blocking GATES (spec
+    // contract), so a blocking RUNNER/phase failure makes runCI throw yet leaves
+    // `ok:true`. A consumer keying on the object alone would misread that as
+    // success. Surfacing the top-level `exitCode` (non-zero on ANY run failure,
+    // including a crash) closes that gap without reinterpreting `ok`.
+    if (cli.flags.json) {
+        const { collectGateOutcomes } = await import("../../commands/ci.js");
+        const result = await collectGateOutcomes({
+            projectDir: process.cwd(),
+            mode: ciMode,
+            noDocker: !cli.flags.docker,
+            noGhagga: !cli.flags.ciGhagga,
+            noSecurity: !cli.flags.security,
+            timeout: cli.flags.timeout,
+            config: cli.flags.config || undefined,
+            stack: cli.flags.stack || undefined,
+        });
+        console.log(JSON.stringify({ ok: result.ok, exitCode: result.exitCode, gates: result.gates }, null, 2));
+        process.exit(result.exitCode);
+    }
     render(React.createElement(CIContextProvider, { isCI: true },
         React.createElement(CI, { projectDir: process.cwd(), mode: ciMode, noDocker: !cli.flags.docker, noGhagga: !cli.flags.ciGhagga, noSecurity: !cli.flags.security, timeout: cli.flags.timeout, config: cli.flags.config || undefined, stack: cli.flags.stack || undefined })), { stdin: ctx.inkStdin });
 }

package/dist/commands/ci.d.ts

@@ -1,4 +1,4 @@
-import { type CIGateConfig } from "../lib/ci-config.js";
+import { type CIGateConfig, type GateMode, type GateScope } from "../lib/ci-config.js";
 import type { Stack } from "../types/index.js";
 export type CIMode = "full" | "quick" | "shell" | "detect";
 export interface CIOptions {
@@ -79,7 +79,7 @@ export interface ResolveRunnerOptions {
  *   3. otherwise → single auto-detected runner (zero-config default)
  */
 export declare function resolveCIRunners(projectDir: string, options?: ResolveRunnerOptions): Promise<ResolvedRunners>;
-export declare function runCI(options: CIOptions, onStep: CIStepCallback): Promise<void>;
+export declare function runCI(options: CIOptions, onStep: CIStepCallback, onGateOutcome?: (outcome: GateOutcome) => void): Promise<void>;
 /**
  * Execute a single gate command HOST-NATIVE via `bash -c`, at the repo root,
  * with the provided env MAP. Modeled on `runSemgrep`/`runGhagga` (a spawned
@@ -96,10 +96,67 @@ export declare function runCI(options: CIOptions, onStep: CIStepCallback): Promi
  * eliminate. A null code therefore resolves to a NON-ZERO code using the shell
  * convention `128 + <signal number>` when the signal is resolvable, else 1.
  *
+ * TIMEOUT (GATE-2): when `timeoutSec` is set, a command still running after that
+ * many wall-clock seconds is killed — SIGTERM first, escalated to SIGKILL after a
+ * short grace if it ignores SIGTERM. A `timedOut` flag is set BEFORE the SIGTERM
+ * lands, and on `close` it OVERRIDES the child's reported code with the timeout
+ * sentinel 124 — REGARDLESS of what the child reported. This closes the false-green
+ * where a child that TRAPS SIGTERM and exits 0 gracefully (dev servers, watchers,
+ * SIGTERM-handling CLIs) would otherwise resolve 0 and PASS a timed-out blocking
+ * gate. INVARIANT: `timedOut ⇒ non-zero, ALWAYS` (124, the GNU `timeout(1)`
+ * convention — distinct from a signal-death 143/137). Timers are cleared on
+ * `close`/`error` so no dangling handle keeps the process alive. Omitting
+ * `timeoutSec` preserves the pre-GATE-2 behavior exactly (no timer, runs to
+ * completion).
+ *
  * Env values arrive as discrete map entries — never string-spliced into the
  * `bash -c` command — so metacharacters in a value cannot break out of the shell.
  */
-export declare function runGateNative(cmd: string, cwd: string, env: Record<string, string>): Promise<number>;
+export declare function runGateNative(cmd: string, cwd: string, env: Record<string, string>, timeoutSec?: number): Promise<number>;
+/**
+ * A single gate's structured result, collected for the headless JSON run path.
+ * Mirrors the `{ id, mode, scope, status, blocking, changedFiles?, exitCode? }`
+ * JSON shape.
+ */
+export interface GateOutcome {
+    id: string;
+    mode: GateMode;
+    scope: GateScope;
+    status: CIStepStatus;
+    /** `true` when `mode === blocking` — an errored blocking gate drives `ok:false`. */
+    blocking: boolean;
+    /** The changed-file set a scope:changed gate saw (present only when resolved). */
+    changedFiles?: string[];
+    /** First non-zero command code for a failed gate. */
+    exitCode?: number;
+    /**
+     * Human-readable cause of a degrade/skip, surfaced so the headless JSON
+     * consumer sees the degrade LOUDLY — not just in the Ink stream. Populated for
+     * the scope:changed skip variants: base ref null, changed-file resolution
+     * failure (shallow clone / missing ref), and the empty changed-set skip.
+     */
+    reason?: string;
+}
+/** Structured result of a headless (`--json`) gate run. */
+export interface HeadlessGateResult {
+    /** `false` iff a BLOCKING gate errored; informative failures keep it `true`. */
+    ok: boolean;
+    gates: GateOutcome[];
+    /** The process exit code to set explicitly (1 on a blocking failure or crash). */
+    exitCode: number;
+}
+/**
+ * Drive `runCI` headlessly (no Ink render), collecting each gate's structured
+ * outcome for the `--json` run path. `runCI` throws on a blocking gate failure
+ * (and on any non-gate error); the outcomes are captured regardless via the
+ * `onOutcome` callback, so the JSON is always complete.
+ *
+ * `ok` is `false` iff a BLOCKING gate errored (spec contract); informative
+ * failures keep `ok:true`. `exitCode` is `1` when a blocking gate errored OR
+ * `runCI` threw for any other reason (a real crash still exits non-zero), else
+ * `0`. The caller (dispatch) prints `{ ok, gates }` and sets `process.exitCode`.
+ */
+export declare function collectGateOutcomes(options: CIOptions): Promise<HeadlessGateResult>;
 /**
  * Classification of an existing `.git/hooks/<name>` before anything is written
  * (design D6). Every state has exactly one write policy, so no hook is ever

package/dist/commands/ci.js

@@ -6,10 +6,11 @@ import os from "node:os";
 import path from "node:path";
 import fs from "fs-extra";
 import { HOOK_ASSETS_DIR } from "../constants.js";
-import { CI_STACKS, findCIConfig, GATE_MODE, loadCIConfig, } from "../lib/ci-config.js";
+import { CI_STACKS, findCIConfig, GATE_MODE, GATE_SCOPE, loadCIConfig, } from "../lib/ci-config.js";
 import { refreshContextDir } from "../lib/context.js";
 import { ensureImage, isDockerAvailable, openShell, runInContainer, } from "../lib/docker.js";
 import { execFileAsync } from "../lib/exec.js";
+import { changedFiles, resolveBaseRef } from "../lib/git-diff.js";
 // =============================================================================
 // Stack detection
 // =============================================================================
@@ -313,7 +314,7 @@ function describeRunners(resolved) {
         .join(", ");
     return `Config: ${resolved.runners.length} runner(s) — ${summary}`;
 }
-export async function runCI(options, onStep) {
+export async function runCI(options, onStep, onGateOutcome) {
     const { projectDir = process.cwd(), mode = "full", noDocker = false, noGhagga = false, noSecurity = false, timeout = 600, } = options;
     // ── Resolve runners (once — nothing downstream re-detects) ─────────────────
     const stepDetect = "detect";
@@ -342,7 +343,7 @@ export async function runCI(options, onStep) {
             report(onStep, mode, `${mode} mode`, "error", detail);
             throw new Error(`no runners resolved — ${mode} mode requires at least one runner`);
         }
-        await runGates(resolved.gates, projectDir, onStep);
+        await runGates(resolved.gates, projectDir, onStep, onGateOutcome);
         return;
     }
     // Legacy single-runner view for the zero-config auto path. Keeping this
@@ -514,7 +515,7 @@ export async function runCI(options, onStep) {
     // already `full` or `quick` here; the guard makes the contract explicit.
     // `runGates` no-ops on an empty gate list (a v1 repo carries none).
     if (mode === "full" || mode === "quick") {
-        await runGates(resolved.gates, projectDir, onStep);
+        await runGates(resolved.gates, projectDir, onStep, onGateOutcome);
     }
 }
 // =============================================================================
@@ -772,13 +773,59 @@ function filterDefinedEnv(env) {
  * eliminate. A null code therefore resolves to a NON-ZERO code using the shell
  * convention `128 + <signal number>` when the signal is resolvable, else 1.
  *
+ * TIMEOUT (GATE-2): when `timeoutSec` is set, a command still running after that
+ * many wall-clock seconds is killed — SIGTERM first, escalated to SIGKILL after a
+ * short grace if it ignores SIGTERM. A `timedOut` flag is set BEFORE the SIGTERM
+ * lands, and on `close` it OVERRIDES the child's reported code with the timeout
+ * sentinel 124 — REGARDLESS of what the child reported. This closes the false-green
+ * where a child that TRAPS SIGTERM and exits 0 gracefully (dev servers, watchers,
+ * SIGTERM-handling CLIs) would otherwise resolve 0 and PASS a timed-out blocking
+ * gate. INVARIANT: `timedOut ⇒ non-zero, ALWAYS` (124, the GNU `timeout(1)`
+ * convention — distinct from a signal-death 143/137). Timers are cleared on
+ * `close`/`error` so no dangling handle keeps the process alive. Omitting
+ * `timeoutSec` preserves the pre-GATE-2 behavior exactly (no timer, runs to
+ * completion).
+ *
  * Env values arrive as discrete map entries — never string-spliced into the
  * `bash -c` command — so metacharacters in a value cannot break out of the shell.
  */
-export async function runGateNative(cmd, cwd, env) {
+export async function runGateNative(cmd, cwd, env, timeoutSec) {
     return await new Promise((resolve, reject) => {
         const proc = spawn("bash", ["-c", cmd], { cwd, env, stdio: "inherit" });
+        let killTimer;
+        let graceTimer;
+        let timedOut = false;
+        const clearTimers = () => {
+            if (killTimer !== undefined)
+                clearTimeout(killTimer);
+            if (graceTimer !== undefined)
+                clearTimeout(graceTimer);
+        };
+        if (timeoutSec !== undefined) {
+            killTimer = setTimeout(() => {
+                // The wall-clock budget expired: mark the run as timed out BEFORE the
+                // SIGTERM lands. A child that traps SIGTERM and exits 0 gracefully would
+                // otherwise report code=0 → a false-green; the `timedOut` flag overrides
+                // that below so a timed-out gate is ALWAYS a FAILURE.
+                timedOut = true;
+                // Ask politely, then force: SIGKILL if the child is still alive after
+                // the grace window.
+                proc.kill("SIGTERM");
+                graceTimer = setTimeout(() => {
+                    proc.kill("SIGKILL");
+                }, GATE_TIMEOUT_GRACE_MS);
+            }, timeoutSec * 1000);
+        }
         proc.on("close", (code, signal) => {
+            clearTimers();
+            if (timedOut) {
+                // INVARIANT: timedOut ⇒ non-zero, ALWAYS. Even a child that trapped the
+                // SIGTERM and exited 0 before the SIGKILL escalation is a timeout, not a
+                // pass. Resolve the GNU `timeout(1)` sentinel 124 ("command timed out"),
+                // semantically distinct from a signal-death 143/137.
+                resolve(GATE_TIMEOUT_EXIT_CODE);
+                return;
+            }
             if (code !== null) {
                 resolve(code);
                 return;
@@ -789,9 +836,34 @@ export async function runGateNative(cmd, cwd, env) {
             const signum = signal ? os.constants.signals[signal] : undefined;
             resolve(signum !== undefined ? 128 + signum : 1);
         });
-        proc.on("error", reject);
+        proc.on("error", (e) => {
+            clearTimers();
+            reject(e);
+        });
     });
 }
+/** Grace between the timeout SIGTERM and the escalated SIGKILL. */
+const GATE_TIMEOUT_GRACE_MS = 2000;
+/**
+ * Exit code resolved for a timed-out gate, regardless of how the child died.
+ * 124 is the GNU `timeout(1)` convention for "command timed out" — semantically
+ * distinct from a signal-death 143 (SIGTERM) / 137 (SIGKILL), and it CANNOT be a
+ * false-green because it is non-zero. Enforces `timedOut ⇒ non-zero, always`.
+ */
+const GATE_TIMEOUT_EXIT_CODE = 124;
+/**
+ * Env var carrying a scope:changed gate's newline-joined, root-relative paths.
+ *
+ * KNOWN LIMITATION (JDB-103): the list is newline-joined, so a path that itself
+ * contains a literal `\n` (git can emit such a path when `core.quotePath` is off)
+ * would corrupt line-based parsing on the gate side. This is a low-likelihood
+ * edge — repo paths with embedded newlines are pathological — and is accepted as
+ * a documented caveat rather than switched to NUL-joining, which would force
+ * every gate consumer to change its parser.
+ */
+const CHANGED_FILES_ENV = "JAVI_FORGE_CHANGED_FILES";
+/** Env var carrying a gate's optional baseline artifact path. */
+const BASELINE_ENV = "JAVI_FORGE_BASELINE";
 /**
  * Repo-level gate phase. Each gate runs host-native via `runGateNative` at the
  * repo root. Outcome semantics:
@@ -806,31 +878,109 @@ export async function runGateNative(cmd, cwd, env) {
  * contribute to the accumulator, so the exit code stays 0.
  *
  * Multi-command gates run in order and STOP at the first non-zero exit
- * (fail-fast, matching the runner precedent); that first code is reported.
+ * (fail-fast, matching the runner precedent); that first code is reported. An
+ * optional per-gate `timeout` (seconds) is applied PER COMMAND: a command that
+ * exceeds it is killed and resolves non-zero, so the timed-out gate fails
+ * (blocking) or warns (informative) — never a false-green.
+ *
+ * `scope: changed` consumes the injectable `git-diff.ts` engine: the base ref is
+ * resolved and the changed set computed ONCE, then shared. A non-empty set runs
+ * the gate with `$JAVI_FORGE_CHANGED_FILES` (newline-joined, root-relative); an
+ * empty set skips the gate; a null base OR a `changedFiles` throw skips every
+ * scope:changed gate with a named warning (loud-degrade, never widens, never
+ * crashes). `baseline` is injected as `$JAVI_FORGE_BASELINE`. Gate `env` spreads
+ * LAST (documented last-wins over the engine-injected keys).
  *
- * Slice 3 wires `mode` and `scope: all` gates with the engine-injected env
- * (`CI=true`). `scope: changed` wiring, `baseline`, and gate `env` injection
- * land in slice 4.
+ * `onOutcome` (optional) receives each gate's structured result for the headless
+ * JSON run path.
  */
-async function runGates(gates, projectDir, onStep) {
+async function runGates(gates, projectDir, onStep, onOutcome) {
     if (gates.length === 0)
         return;
     const blockingFailures = [];
-    // Engine-injected keys only in slice 3; gate `env` + JAVI_FORGE_CHANGED_FILES
-    // are added in slice 4.
     const baseEnv = {
         ...filterDefinedEnv(process.env),
         CI: "true",
     };
+    // Lazily resolved and memoized — computed only when a scope:changed gate
+    // exists, and only once (shared across all scope:changed gates).
+    let changedScope = null;
+    const resolveChangedScope = async () => {
+        if (changedScope !== null)
+            return changedScope;
+        const base = await resolveBaseRef(process.env, projectDir);
+        if (base === null) {
+            changedScope = {
+                kind: "skip",
+                reason: "no base ref resolved — skipping scope:changed",
+            };
+            return changedScope;
+        }
+        try {
+            changedScope = {
+                kind: "files",
+                files: await changedFiles(base, projectDir),
+            };
+        }
+        catch {
+            // Shallow clone / base sha absent from local history: caught here so the
+            // throw never aborts the phase and the gate never widens to scope:all.
+            changedScope = {
+                kind: "skip",
+                reason: "changed-file diff failed (shallow clone / missing ref) — skipping scope:changed",
+            };
+        }
+        return changedScope;
+    };
     for (const gate of gates) {
         const stepId = `gate:${gate.id}`;
         const label = `Gate: ${gate.id}`;
+        const blocking = gate.mode === GATE_MODE.BLOCKING;
+        const emit = (status, extra) => onOutcome?.({
+            id: gate.id,
+            mode: gate.mode,
+            scope: gate.scope,
+            status,
+            blocking,
+            ...extra,
+        });
         report(onStep, stepId, label, "running");
+        // Per-gate env map: engine keys, then baseline, then gate.env LAST (last-wins).
+        const gateEnv = { ...baseEnv };
+        let gateChangedFiles;
+        if (gate.scope === GATE_SCOPE.CHANGED) {
+            const scope = await resolveChangedScope();
+            if (scope.kind === "skip") {
+                report(onStep, stepId, `${label} skipped`, "skipped", scope.reason);
+                // Loud-degrade: carry the named reason into the JSON outcome too, not
+                // only the Ink `onStep` stream (which is a no-op under --json).
+                emit("skipped", { reason: scope.reason });
+                continue;
+            }
+            if (scope.files.length === 0) {
+                const noChanges = "no changed files";
+                report(onStep, stepId, `${label} skipped`, "skipped", noChanges);
+                emit("skipped", { changedFiles: [], reason: noChanges });
+                continue;
+            }
+            gateChangedFiles = scope.files;
+            gateEnv[CHANGED_FILES_ENV] = scope.files.join("\n");
+        }
+        if (gate.baseline !== undefined) {
+            gateEnv[BASELINE_ENV] = gate.baseline;
+        }
+        if (gate.env !== undefined) {
+            // Gate env spreads LAST — a gate MAY override CI / CHANGED_FILES / BASELINE.
+            Object.assign(gateEnv, gate.env);
+        }
         let exitCode = 0;
         let spawnError;
         try {
             for (const cmd of gate.run) {
-                exitCode = await runGateNative(cmd, projectDir, baseEnv);
+                // timeout is per-command (matches the fail-fast model): each command
+                // gets its own wall-clock budget. A timed-out command is killed and
+                // resolves non-zero, so fail-fast stops the gate here.
+                exitCode = await runGateNative(cmd, projectDir, gateEnv, gate.timeout);
                 if (exitCode !== 0)
                     break; // fail-fast: skip the remaining commands
             }
@@ -840,21 +990,53 @@ async function runGates(gates, projectDir, onStep) {
         }
         if (spawnError === undefined && exitCode === 0) {
             report(onStep, stepId, `${label} passed`, "done");
+            emit("done", { changedFiles: gateChangedFiles });
             continue;
         }
         const detail = spawnError !== undefined ? String(spawnError) : `exit ${exitCode}`;
-        if (gate.mode === GATE_MODE.BLOCKING) {
+        if (blocking) {
             blockingFailures.push(gate.id);
             report(onStep, stepId, `${label} failed`, "error", detail);
+            emit("error", { changedFiles: gateChangedFiles, exitCode });
         }
         else {
             report(onStep, stepId, `${label} failed (informative)`, "warning", detail);
+            emit("warning", { changedFiles: gateChangedFiles, exitCode });
         }
     }
     if (blockingFailures.length > 0) {
         throw new Error(`blocking gate(s) failed: ${blockingFailures.join(", ")}`);
     }
 }
+/**
+ * Drive `runCI` headlessly (no Ink render), collecting each gate's structured
+ * outcome for the `--json` run path. `runCI` throws on a blocking gate failure
+ * (and on any non-gate error); the outcomes are captured regardless via the
+ * `onOutcome` callback, so the JSON is always complete.
+ *
+ * `ok` is `false` iff a BLOCKING gate errored (spec contract); informative
+ * failures keep `ok:true`. `exitCode` is `1` when a blocking gate errored OR
+ * `runCI` threw for any other reason (a real crash still exits non-zero), else
+ * `0`. The caller (dispatch) prints `{ ok, gates }` and sets `process.exitCode`.
+ */
+export async function collectGateOutcomes(options) {
+    const gates = [];
+    let threw = false;
+    try {
+        await runCI(options, () => { }, (outcome) => gates.push(outcome));
+    }
+    catch {
+        // Blocking failure (aggregate throw) or a non-gate error — outcomes are
+        // already captured; the headless path never propagates the throw.
+        threw = true;
+    }
+    const blockingErrored = gates.some((g) => g.blocking && g.status === "error");
+    return {
+        ok: !blockingErrored,
+        gates,
+        exitCode: blockingErrored || threw ? 1 : 0,
+    };
+}
 // =============================================================================
 // CI Hooks Installation
 // =============================================================================

package/dist/lib/ci-config.d.ts

@@ -60,6 +60,12 @@ export interface CIGateConfig {
     baseline?: string;
     /** Optional env injected via the child-process env map (slice 4). */
     env?: Record<string, string>;
+    /**
+     * Optional per-command wall-clock timeout in seconds (GATE-2). When set, a
+     * command exceeding it is killed and the gate FAILS (non-zero). Omitted →
+     * no timeout (unchanged behavior).
+     */
+    timeout?: number;
 }
 export interface CIConfig {
     version: number;

package/dist/lib/ci-config.js

@@ -214,7 +214,15 @@ function validateRunner(raw, index, errors) {
         requires,
     };
 }
-const GATE_FIELDS = new Set(["id", "run", "mode", "scope", "baseline", "env"]);
+const GATE_FIELDS = new Set([
+    "id",
+    "run",
+    "mode",
+    "scope",
+    "baseline",
+    "env",
+    "timeout",
+]);
 function validateGate(raw, index, errors) {
     const base = `gates[${index}]`;
     if (!isRecord(raw)) {
@@ -310,6 +318,20 @@ function validateGate(raw, index, errors) {
             env = raw.env;
         }
     }
+    let timeout;
+    if (raw.timeout !== undefined) {
+        if (typeof raw.timeout !== "number" ||
+            !Number.isFinite(raw.timeout) ||
+            raw.timeout <= 0) {
+            errors.push({
+                path: `${base}.timeout`,
+                message: `timeout must be a positive number of seconds (got "${String(raw.timeout)}")`,
+            });
+        }
+        else {
+            timeout = raw.timeout;
+        }
+    }
     return {
         id: typeof id === "string" ? id.trim() : "",
         run,
@@ -317,6 +339,7 @@ function validateGate(raw, index, errors) {
         scope,
         baseline,
         env,
+        timeout,
     };
 }
 /**

package/dist/lib/git-diff.d.ts

@@ -3,7 +3,10 @@
  * 1. `$CI_MERGE_REQUEST_DIFF_BASE_SHA` (GitLab MR) when non-empty.
  * 2. `$CI_COMMIT_BEFORE_SHA` (GitLab push) when non-empty AND not the
  *    all-zeros new-branch sentinel.
- * 3. `$GITHUB_BASE_REF` (GitHub Actions PR) → `git merge-base origin/<ref> HEAD`.
+ * 3. `$GITHUB_BASE_REF` (GitHub Actions PR) → `git merge-base origin/<ref> HEAD`;
+ *    else on a push, `$GITHUB_EVENT_BEFORE` (github.event.before — the real push
+ *    base, unless the all-zeros new-branch sentinel) before falling to
+ *    `$GITHUB_SHA` (which equals HEAD after actions/checkout → empty diff).
  * 4. Local fallback: `git merge-base <candidate> HEAD` over
  *    `origin/main`, `origin/master`, `main`, `master` — first that resolves.
  * 5. Nothing resolves → `null` (caller loud-degrades).

package/dist/lib/git-diff.js

@@ -52,7 +52,10 @@ async function tryMergeBase(ref, cwd) {
  * 1. `$CI_MERGE_REQUEST_DIFF_BASE_SHA` (GitLab MR) when non-empty.
  * 2. `$CI_COMMIT_BEFORE_SHA` (GitLab push) when non-empty AND not the
  *    all-zeros new-branch sentinel.
- * 3. `$GITHUB_BASE_REF` (GitHub Actions PR) → `git merge-base origin/<ref> HEAD`.
+ * 3. `$GITHUB_BASE_REF` (GitHub Actions PR) → `git merge-base origin/<ref> HEAD`;
+ *    else on a push, `$GITHUB_EVENT_BEFORE` (github.event.before — the real push
+ *    base, unless the all-zeros new-branch sentinel) before falling to
+ *    `$GITHUB_SHA` (which equals HEAD after actions/checkout → empty diff).
  * 4. Local fallback: `git merge-base <candidate> HEAD` over
  *    `origin/main`, `origin/master`, `main`, `master` — first that resolves.
  * 5. Nothing resolves → `null` (caller loud-degrades).
@@ -68,12 +71,21 @@ export async function resolveBaseRef(env, cwd) {
         return env.CI_COMMIT_BEFORE_SHA;
     }
     // 3. GitHub Actions — a PR sets GITHUB_BASE_REF (merge-base against the
-    //    target branch); a push has no base ref and falls back to GITHUB_SHA.
+    //    target branch). A push has no base ref: prefer github.event.before
+    //    (GITHUB_EVENT_BEFORE — the commit the branch pointed at before the push,
+    //    the real diff base), unless it is the all-zeros new-branch sentinel, and
+    //    only then fall back to GITHUB_SHA (which equals HEAD after
+    //    actions/checkout → an empty diff → scope:changed gates would silently
+    //    skip; a visible skip, not a false-green — the before-sha avoids it).
     if (isNonEmpty(env.GITHUB_BASE_REF)) {
         const base = await tryMergeBase(`origin/${env.GITHUB_BASE_REF}`, cwd);
         if (base !== null)
             return base;
     }
+    else if (isNonEmpty(env.GITHUB_EVENT_BEFORE) &&
+        env.GITHUB_EVENT_BEFORE !== NEW_BRANCH_SENTINEL) {
+        return env.GITHUB_EVENT_BEFORE;
+    }
     else if (isNonEmpty(env.GITHUB_SHA)) {
         return env.GITHUB_SHA;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "javi-forge",
-	"version": "1.13.0",
+	"version": "1.15.0",
 	"description": "Project scaffolding and AI-ready CI bootstrap",
 	"type": "module",
 	"bin": {