feat(ci-carry): path-skipped jobs count only under an unchanged gate; find --policy-from head --simulate (GST-1190)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

bin/gstack-ci-carry

@@ -3,6 +3,7 @@
  * gstack-ci-carry — CI as the one full test run (GSTA-258; docs/pregate.md#ci-carry).
  *
  *   gstack-ci-carry find [--base <branch>] [--profile <name>]... [--command <exact lane command> --allow-repo-commands] [--json]
+ *                        [--policy-from head --simulate]
  *   gstack-ci-carry wait [--base <branch>] [--profile <name>] [--timeout <s>] [--interval <s>]
  *
  * find: the newest verified run of each profile (default: every profile the base branch's
@@ -15,7 +16,7 @@
  */
 import { spawnSync } from 'node:child_process';
 import { findCarry, laneMapping, mappingCoverage, waitForRun } from '../lib/ci-carry';
-import { isConfigUnavailable, loadConfigFromBase } from '../lib/pregate/config';
+import { isConfigUnavailable, loadConfigFromBase, loadConfigFromHead } from '../lib/pregate/config';
 import { buildRunCheck } from '../lib/pregate/run-check';
 import { wtreeFingerprint } from '../lib/script-invocation';
 import { resolveBaseBranch } from '../lib/ship-policy';
@@ -24,11 +25,13 @@ const HELP = `gstack-ci-carry — use a verified CI run at HEAD's exact tree ins
 
   find [--base <branch>] [--profile <name>]... [--command <exact lane command> --allow-repo-commands] [--json]
       CI_CARRY: accepted <receipt> (exit 0) or CI_CARRY: none (<reason>) (exit 1)
+      --policy-from head --simulate: the same check under the branch's own map and profiles, every line starting
+      SIMULATION:; a dry run that proves a new mapping before it lands (find never writes evidence; nothing clears)
   wait [--base <branch>] [--profile <name>] [--timeout <s>] [--interval <s>]
       poll the newest run at HEAD (default 1800 s, every 20 s): CI_WAIT: green|red|running|none, then find on green;
       exit 0 carried, 1 red or not carried, 3 still running or no run
 
-Profiles and ship_lanes_from come from origin/<base>'s .gstack/pregate.json only. Only a clean, committed tree
+Profiles and ship_lanes_from come from origin/<base>'s .gstack/pregate.json only (a simulation reads the branch's). Only a clean, committed tree
 carries; fork runs, stale runs, a newer red or running run on HEAD and a tree.json that misses an inventory
 file never do. Exit 2 is usage.`;
 
@@ -36,23 +39,28 @@ const argv = process.argv.slice(2);
 const cmd = argv[0];
 const all = (n: string) => argv.flatMap((a, i) => (a === n && argv[i + 1] !== undefined ? [argv[i + 1]!] : []));
 const flag = (n: string) => all(n).at(-1);
-const out = (s: string) => process.stdout.write(`${s}\n`);
+const simulate = argv.includes('--simulate');
+const out = (s: string) => process.stdout.write(`${simulate ? 'SIMULATION: ' : ''}${s}\n`);
 const usage = (m: string) => { process.stderr.write(`gstack-ci-carry: ${m}\n`); process.exit(2); };
 if (!cmd || argv.includes('--help') || argv.includes('-h')) { out(HELP); process.exit(cmd ? 0 : 2); }
 if (cmd !== 'find' && cmd !== 'wait') usage(`unknown command ${cmd}; run gstack-ci-carry --help`);
+const policyFrom = flag('--policy-from') ?? 'base';
+if (policyFrom !== 'base' && policyFrom !== 'head') usage('--policy-from needs base or head');
+if (simulate !== (policyFrom === 'head') || (simulate && cmd !== 'find')) usage('find --policy-from head --simulate go together: a branch\'s own map is only ever simulated, never carried');
 const git = (args: string[]) => { const r = spawnSync('git', args, { encoding: 'utf8', timeout: 30_000 }); return r.status === 0 ? r.stdout.trim() : ''; };
 const root = git(['rev-parse', '--show-toplevel']);
 if (!root) usage('not inside a git repository');
 const base = resolveBaseBranch(root, flag('--base'));
-const loaded = loadConfigFromBase(root, base);
-if (isConfigUnavailable(loaded) || loaded.errors.length) { out(`CI_CARRY: none (profiles_unavailable: origin/${base}'s .gstack/pregate.json is unreadable or invalid)`); process.exit(1); }
+const loaded = simulate ? loadConfigFromHead(root) : loadConfigFromBase(root, base);
+if (simulate) out(`policy ${isConfigUnavailable(loaded) ? 'unavailable' : loaded.label}; a dry run: nothing is written and nothing clears (a carry reads origin/${base}'s map only)`);
+if (isConfigUnavailable(loaded) || loaded.errors.length) { out(`CI_CARRY: none (profiles_unavailable: ${simulate ? 'the branch\'s' : `origin/${base}'s`} .gstack/pregate.json is unreadable or invalid)`); process.exit(1); }
 const command = flag('--command');
 const mapping = command !== undefined ? laneMapping(loaded.config.ship_lanes_from, command) : undefined;
 if (command !== undefined && !mapping) { out(`CI_CARRY: none (not_mapped: ${JSON.stringify(command)} is neither a key nor a declared alias in origin/${base}'s ship_lanes_from)`); process.exit(1); }
 if (mapping && !argv.includes('--allow-repo-commands')) usage('--command runs the mapping\'s inventory, a pin-file command: pass --allow-repo-commands');
 const profiles = all('--profile').length ? all('--profile') : mapping ? mapping.profiles : [...new Set(Object.values(loaded.config.ship_lanes_from).flatMap(m => m.profiles))];
 if (!profiles.length) { out(`CI_CARRY: none (no_profile: origin/${base} maps no lane in ship_lanes_from; pass --profile <name>)`); process.exit(1); }
-const check = buildRunCheck(root, null, argv.includes('--allow-repo-commands'), base);
+const check = buildRunCheck(root, null, argv.includes('--allow-repo-commands'), base, simulate ? 'head' : 'base');
 if ('error' in check) { out(`CI_CARRY: none (profiles_unavailable: ${check.error})`); process.exit(1); }
 const head = git(['rev-parse', 'HEAD']);
 const tree = git(['rev-parse', 'HEAD^{tree}']);

bin/gstack-evidence

@@ -133,6 +133,8 @@ interface EvidenceRecord {
   tests_ran?: number | "unknown" | "n/a";
   /** "files" when a carried narrow lane's tests_ran counts its inventory files the run covered (record-ci), not tests. */
   tests_unit?: "files";
+  /** Why a carried lane was not owed at all: every job it names was path-skipped by an unchanged gate (record-ci, GST-1190). */
+  not_owed?: string;
 }
 
 /** Bytes of streamed output kept for the tests_ran parse (the 2MB log would truncate the summary). */
@@ -705,10 +707,11 @@ function cmdRecordCi(argv: string[]): number {
   const runs = v.runs.map((r) => `${r.run_id}/${r.run_attempt}`);
   const rec: EvidenceRecord = {
     ts: new Date(v.runs.map((r) => r.finished_at).sort()[0]!).toISOString(), label, command, cmd_sha256: sha256(command), exit: 0, duration_s: 0,
-    commit: head, tree, dirty: false, wtree: tree, tests_ran: v.tests, source: "ci", runs, profiles: m.profiles, policy: loaded.label, ...(m.jobs ? { jobs: m.jobs } : {}), ...(v.unit ? { tests_unit: v.unit } : {}),
+    commit: head, tree, dirty: false, wtree: tree, tests_ran: v.tests, source: "ci", runs, profiles: m.profiles, policy: loaded.label, ...(m.jobs ? { jobs: m.jobs } : {}), ...(v.unit ? { tests_unit: v.unit } : {}), ...(v.notOwed ? { not_owed: v.notOwed } : {}),
   };
   appendJsonl(paths.file, rec, { mode: 0o600 });
   console.error(`gstack-evidence: recorded label=${label} exit=0 tests_ran=${v.tests}${v.unit ? ` unit=${v.unit}` : ""} log=- source=ci runs=${runs.join(",")} policy=${loaded.label}`);
+  if (v.notOwed) console.error(`gstack-evidence: not owed: ${v.notOwed}`);
   return 0;
 }
 

changelog.d/gsta258-l6-guard-carry.md

@@ -11,8 +11,12 @@
 
 - A test file whose every test skipped on the CI runner no longer counts as carried (GST-1190, harness-evals: 75 tests). `tree.json` now lists such files in `skipped_files`, written by gstack's own Free Tests from the per-file JUnit counts; the pregate tests stage runs them here, and a /ship lane or guard whose inventory names one runs here. A partly skipped file still counts. An older `tree.json` without the list is read as before.
 
+- A run profile can declare `skippable: { jobs, gate, scripts? }` for jobs a path filter skips (GST-1190, truther #1169). A skipped job counts only when the gate job succeeded and the workflow plus every repo file the gate runs match `origin/<base>` byte for byte; the lane then prints `not owed: CI skipped at this tree (gate job <name>, workflow unchanged)`. If the branch changed any of them, it controlled the skip, so the lane runs here.
+- `gstack-ci-carry find --policy-from head --simulate` is the same dry run for one lane command, every line starting `SIMULATION:`.
+
 ### Tests
 - `test/ship-ci-carry.test.ts`: in founderstar's shape (guards only, no lanes), `check-quick` carries from CI, `play-through` reuses a same-tree ledger pass, `assets` runs, and a dirty tree carries nothing. It fails without the guard carry.
 - `test/ship-ci-carry.test.ts`: a lane mapped by `jobs` carries when every named job passed at the same tree with no test files, and refuses for a missing job, a skipped job, a rerun whose newest attempt skipped the job, and another tree's run. Those five fail without the change.
 - `test/ship-ci-carry.test.ts` (GST-1190): an alias carries and an undeclared env prefix does not; a narrow lane reports its covered file count, not 9677; a jobs-mapped `bunx tsc --noEmit` guard carries with `n/a`; the newer-gstack message; `--simulate` writes and clears nothing and the branch's own map never carries; `carried` drops a row another base mapped. Six of these fail without the change.
 - `test/ci-tree-reuse.test.ts` and `test/ship-ci-carry.test.ts` (GST-1190 skipped files): the writer lists only fully skipped files and leaves the list out without complete counts; a fully skipped inventory file stops the lane carry, an empty list or older `tree.json` carries, and the tests stage runs only the skipped selected file. All three fail without the change.
+- `test/ship-ci-carry.test.ts` (path-skipped jobs and `find --simulate`): a skip under an unchanged, green gate is not owed; a changed workflow, a changed gate script or a failed gate job runs the lane here; `find --policy-from head --simulate` prints only SIMULATION lines and writes nothing. All five fail without the change.

docs/pregate.md

@@ -88,7 +88,7 @@ the byte-pinned `/ship` renders in `test/fixtures/golden/`).
 | `stall_timeout_s` | seconds a test command may print nothing while using under a tenth of one CPU before its process group is killed and the check is `incomplete` (`PREGATE_STALLED`); default 300, `0` disables; `--stall-timeout` overrides; the `--remote` gate is exempt (see [supervision](#supervision)) |
 | `timeout_s` | seconds each runner process may take (the unit-file group, each serial file, each guard without its own `timeout_s`, and the remote gate's deadline) when `--timeout` is not passed; 1 to 3600, default 600. `gstack-ship-preflight` and the `finish` fallback run pregate without `--timeout`, so this is how a repo with long lanes sets theirs |
 | `remote_gate` | the repo's remote test gate command; under 8 cores the local test tier becomes a `requires-remote` obligation naming it, and `--remote` runs it (see [remote gate](#remote-gate)) |
-| `run_profiles` | name → `{ workflow, events, jobs, artifact, max_age_hours?, os? }`: the GitHub Actions runs `clear --run` verifies as evidence on the identical tree; a profile named after a lane (`free-tests.yml/macos-named-regressions`) clears that lane (see [run evidence](#run-evidence)). `--from-run` and the main-push reuse job verify runs against them too ([from-run](#from-run), [CI reuse](#ci-reuse)) |
+| `run_profiles` | name → `{ workflow, events, jobs, artifact, max_age_hours?, os?, skippable? }`: the GitHub Actions runs `clear --run` verifies as evidence on the identical tree; a profile named after a lane (`free-tests.yml/macos-named-regressions`) clears that lane (see [run evidence](#run-evidence)). `--from-run` and the main-push reuse job verify runs against them too ([from-run](#from-run), [CI reuse](#ci-reuse)) |
 | `remote_gate_runs` | `{ profiles, inventory, skipped? }`: the run profiles that together clear `pregate.json/remote_gate`, the command that prints the remote gate's test files, one per line, which their runs must cover, and an optional command that prints which selected files the gate itself never runs (see [run evidence](#run-evidence)) |
 | `ship_lanes_from` | maps each exact /ship lane command to `{ profiles, inventory }` or `{ profiles, jobs }`, with optional `aliases`: the run profiles whose verified runs at HEAD's clean tree carry that lane instead of running it, and either the command listing its test files, which their runs must cover, or the CI jobs that must have succeeded (see [CI carry](#ci-carry)); read from the base branch only |
 | `allowlist` | `[{ finding, paths?, pattern?, reason }]`: benign findings the `secrets` check accepts and names as allowlisted, by gstack-redact finding id or non-secret category, path globs and a pattern anchored at the finding; never `env.value` (see [allowlist](#allowlist)) |
@@ -710,7 +710,16 @@ other gate change. Each profile names the workflow file, the events it
 accepts, every job that must have passed (each exactly once), and the artifact
 holding the run's `tree.json`. `max_age_hours` (1–168, default 24) bounds how
 old the run may be, and `os` (`Linux`, `macOS`, `Windows`) requires
-`tree.json` to record that runner OS. Each workflow uploads `tree.json` from
+`tree.json` to record that runner OS. <a id="skippable"></a>`skippable`
+(`{ jobs, gate, scripts? }`, GST-1190) lets named jobs be skipped by a path
+filter: a skipped job counts only when the `gate` job (the one whose output
+decides the skip) succeeded in the same attempt, and the workflow file plus
+every repo file the gate job runs are byte-identical to `origin/<base>`. Those
+files are the declared `scripts` and every path the gate job's steps name in the
+base copy of the workflow. Otherwise the pull request controlled the skip
+decision, so the job refuses as `job_skipped` and the lane runs here. A lane
+whose every named job was skipped this way prints `LANE: <label> not owed: CI
+skipped at this tree (gate job <name>, workflow unchanged) run=…`. Each workflow uploads `tree.json` from
 its own job: `run_id`, `run_attempt`, `event`, `sha` (or `head_sha`),
 `tree` (`git rev-parse HEAD^{tree}` as tested), `files` (every test file the
 run executed), `tests` (the count) and, with `os`, the runner OS or a list of
@@ -1057,18 +1066,23 @@ twice. harness-evals #240's `scripts/ci-tree-json.ts` does it right.
 <a id="prove-a-mapping"></a>**Proving a new mapping.** `ship_lanes_from` is read from `origin/<base>`
 only, so a branch that adds a mapping cannot carry from it, and running
 against `--base <PR branch>` fails (`BASE_CONTAINS_HEAD`). Prove it with the dry
-run instead:
+run instead, once per lane command:
 
 ```bash
-gstack-ship-preflight --tests-only --base main --policy-from head --simulate --lane 'verify=bun run verify'
+gstack-ci-carry find --base main --policy-from head --simulate --command 'bun run verify' --allow-repo-commands
 ```
 
-It reads the branch's own `ship_lanes_from` and `run_profiles`, checks each lane
+It reads the branch's own `ship_lanes_from` and `run_profiles`, checks the lane
 against the verified CI run at this tree exactly as a carry would, and prints
-`SIMULATION:` at the start of every line: `LANE: <label> would carry run=…`,
-`CI_CARRY: none label=<label> (<reason>)` or `not mapped`. It runs no lane and
-no pregate, writes no evidence or ledger row, and clears no obligation. It
-exits 0 when every mapped lane would carry. A branch's own map never carries,
+`SIMULATION:` at the start of every line (`SIMULATION: CI_CARRY: accepted …` or
+`SIMULATION: CI_CARRY: none (<reason>)`). It writes no evidence or ledger row
+and clears no obligation. To check every /ship lane at once, the same dry run
+takes lane flags: `gstack-ship-preflight --tests-only --base main --policy-from
+head --simulate --lane 'verify=bun run verify' …` prints `SIMULATION: LANE:
+<label> would carry run=…`, `SIMULATION: CI_CARRY: none label=<label> (<reason>)`
+or `not mapped` per lane, runs no lane and no pregate, and exits 0 when every
+mapped lane would carry. truther's adoption proved its map this way by hand
+before the dry run existed: run 41585332512 accepted 7 of 7 lanes. A branch's own map never carries,
 even when the base has no policy at all, because the pull request controls both
 the map and the CI that would satisfy it. So the first pull request that adopts
 a mapping pays its full lanes; the carry starts on the pull requests after it

lib/ci-carry.ts

@@ -37,7 +37,7 @@ export type CarryRefused = { ok: false; reason: CarryRefusal; detail: string };
  * the runs' tree.json covers (`unit: 'files'`; tree.json has no per-file test counts yet), with named jobs `n/a`, and only
  * without either (the whole run carried) the runs' test count.
  */
-export type CarryVerdict = { ok: true; runs: RunEvidence[]; tests: number | 'n/a'; unit?: 'files'; receipt: string } | CarryRefused;
+export type CarryVerdict = { ok: true; runs: RunEvidence[]; tests: number | 'n/a'; unit?: 'files'; notOwed?: string; receipt: string } | CarryRefused;
 
 /** How many of HEAD's runs per workflow are tried, newest first. */
 const CANDIDATES = 10;
@@ -51,7 +51,7 @@ function newestVerified(src: RunSource, name: string, profile: RunProfile, head:
   if (!listed.length) return no('no_run', `no ${profile.workflow} run (${profile.events.join(', ')}) on ${head.slice(0, 12)} yet`);
   const refusals: string[] = [];
   for (const run of listed) {
-    const v = verifyRun(src.deps, { repo: src.repo, runRef: String(run.id), profileName: name, profile, vetoHeads: [head], now: src.now });
+    const v = verifyRun(src.deps, { repo: src.repo, runRef: String(run.id), profileName: name, profile, vetoHeads: [head], now: src.now, unchanged: src.unchanged });
     if (v.ok) return v;
     refusals.push(`run ${run.id}: ${v.reason}`);
   }
@@ -100,7 +100,12 @@ export function findCarry(src: RunSource, o: { profiles: string[]; head: string;
   }
   const after = o.wtree();
   if (after !== o.tree) return no('tree_changed', `the working tree changed while the runs were verified (now ${after ? after.slice(0, 12) : 'unreadable'})`);
-  if (jobs.length) return { ok: true, runs, tests: 'n/a', receipt: `ci-carry tree=${o.tree.slice(0, 12)} jobs=${jobs.join(',')} ${runReceiptFields(runs, src.now)}` };
+  if (jobs.length) {
+    const gates = [...new Set(o.profiles.map(n => src.profiles[n]?.skippable?.gate).filter(Boolean))];
+    const allSkipped = runs.every(e => jobs.every(j => e.skipped_jobs?.includes(j)));
+    const notOwed = allSkipped ? `CI skipped at this tree (gate job ${gates.join(', ')}, workflow unchanged)` : undefined;
+    return { ok: true, runs, tests: 'n/a', ...(notOwed ? { notOwed } : {}), receipt: `ci-carry tree=${o.tree.slice(0, 12)} jobs=${jobs.join(',')}${notOwed ? ` not_owed=${gates.join(',')}` : ''} ${runReceiptFields(runs, src.now)}` };
+  }
   if (covered !== undefined) return { ok: true, runs, tests: covered, unit: 'files', receipt: `ci-carry tree=${o.tree.slice(0, 12)} files=${covered} ${runReceiptFields(runs, src.now)}` };
   const tests = runs.reduce((n, e) => n + (e.tests ?? e.files.length), 0);
   return { ok: true, runs, tests, receipt: `ci-carry tree=${o.tree.slice(0, 12)} tests=${tests} ${runReceiptFields(runs, src.now)}` };

lib/pregate/index.ts

@@ -261,7 +261,7 @@ function userPolicyChange(file: PregateFile): string | null {
 
 export interface ClearInput { runUrl?: string; bundleLane?: string; receiptPath?: string; runs?: string[]; evidence?: RunCheck }
 /** What a run clear needs: the base branch's run profiles, the verifier's dependencies, the clock, and the remote gate's inventory. */
-export interface RunCheck { repo: string; deps: RunDeps; profiles: Record<string, RunProfile>; gateRuns: RemoteGateRuns | null; now: Date; inventory: (command: string, tree: string, selected?: string[]) => string[] | { error: string } }
+export interface RunCheck { repo: string; deps: RunDeps; profiles: Record<string, RunProfile>; gateRuns: RemoteGateRuns | null; now: Date; unchanged?: (p: RunProfile) => string | null; inventory: (command: string, tree: string, selected?: string[]) => string[] | { error: string } }
 export type ClearDecision = { receipt: string; attested: boolean; substitution?: PregateReceiptSubstitution } | { refused: 'usage' | 'PREGATE_RECEIPT_INVALID'; message: string; fix?: string };
 
 /**

lib/pregate/run-check.ts

@@ -11,7 +11,7 @@ import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import { ghRunDeps, runInventory } from '../run-evidence';
+import { ghRunDeps, runInventory, type RunProfile } from '../run-evidence';
 import { wtreeFingerprint } from '../script-invocation';
 import { resolveBaseBranch } from '../ship-policy';
 import { normalizeRemoteUrl } from '../ship-queue-train-record';
@@ -19,6 +19,38 @@ import { REMOTE_GATE_LANE } from './checks/lanes';
 import { PREGATE_CONFIG_PATH, isConfigUnavailable, loadConfigFromBase, loadConfigFromHead } from './config';
 import type { RunCheck } from './index';
 
+/**
+ * Null when a skippable profile's workflow and every repo file its gate job runs are byte-identical at HEAD and
+ * origin/<base> (GST-1190); else the first that differs. The files are the profile's declared `scripts` plus every path the
+ * gate job's block in the base workflow names that exists on either side, so a branch cannot move the skip decision.
+ */
+export function gateInputsChanged(root: string, base: string, p: RunProfile): string | null {
+  const ref = `origin/${base.replace(/^origin\//, '')}`;
+  const wf = `.github/workflows/${p.workflow}`;
+  const gate = p.skippable?.gate;
+  if (!gate) return 'the profile names no gate job';
+  const blob = (rev: string, f: string) => { const r = spawnSync('git', ['rev-parse', '--verify', '--quiet', `${rev}:${f}`], { cwd: root, encoding: 'utf8', timeout: 30_000 }); return r.status === 0 ? r.stdout.trim() : null; };
+  const show = spawnSync('git', ['show', `${ref}:${wf}`], { cwd: root, encoding: 'utf8', timeout: 30_000, maxBuffer: 8 * 1024 * 1024 });
+  if (show.status !== 0) return `${wf} is not on ${ref}`;
+  const lines = show.stdout.split('\n');
+  const jobsAt = lines.findIndex(l => /^jobs:\s*$/.test(l));
+  const blocks: string[][] = [];
+  for (let i = jobsAt + 1; jobsAt >= 0 && i < lines.length && !/^\S/.test(lines[i]!); i++) {
+    if (/^  [\w-]+:\s*$/.test(lines[i]!)) blocks.push([lines[i]!]);
+    else blocks.at(-1)?.push(lines[i]!);
+  }
+  const block = blocks.find(b => b[0]!.trim() === `${gate}:` || b.some(l => l.trim() === `name: ${gate}`));
+  if (!block) return `${wf} on ${ref} has no job ${gate}`;
+  const named = [...new Set([...block.join('\n').matchAll(/[\w.\/-]+/g)].map(m => m[0].replace(/^\.\//, '')).filter(t => t.includes('/') || /\.(sh|ts|js|mjs|cjs|py|rb)$/.test(t)))];
+  for (const f of [wf, ...(p.skippable!.scripts ?? []), ...named]) {
+    const a = blob(ref, f);
+    const b = blob('HEAD', f);
+    if (a === null && b === null && f !== wf && !p.skippable!.scripts?.includes(f)) continue;
+    if (a === null || a !== b) return `${f} differs from ${ref}`;
+  }
+  return null;
+}
+
 /**
  * `profiled` says whether `lane` may have a run profile: an unreadable base counts as profiled, so a lane is
  * recorded unverified only once the base shows it has none. `policy: 'head'` reads the branch's profiles instead, only
@@ -33,6 +65,7 @@ export function buildRunCheck(root: string, lane: string | null, allowRepoComman
   if (!repo) return { error: 'origin is not a github.com repository; run evidence is read from GitHub Actions', profiled: lane === null ? false : lane === REMOTE_GATE_LANE ? !!loaded.config.remote_gate_runs : !!loaded.config.run_profiles[lane] };
   return {
     repo, deps: ghRunDeps(repo, root), profiles: loaded.config.run_profiles, gateRuns: loaded.config.remote_gate_runs, now: new Date(),
+    unchanged: p => gateInputsChanged(root, base, p),
     inventory: (command, tree, selected) => {
       if (!allowRepoCommands) return { error: 'the inventory command is a pin-file command; pass --allow-repo-commands' };
       const at = () => { const fp = wtreeFingerprint({ cwd: root }); return 'tree' in fp ? fp.tree : null; };

lib/run-evidence.ts

@@ -42,7 +42,11 @@ import * as path from 'node:path';
 import { sha256Hex, writeReceipt } from './egress-receipt';
 import { runBashSync } from './script-invocation';
 
-export interface RunProfile { workflow: string; events: string[]; jobs: string[]; artifact: string; max_age_hours?: number; os?: string }
+/**
+ * `skippable` (GST-1190): named jobs the workflow may skip by path; a skip counts only when the `gate` job succeeded and the
+ * workflow plus every repo file the gate job runs (`scripts` and any path its steps name) match origin/<base> byte for byte.
+ */
+export interface RunProfile { workflow: string; events: string[]; jobs: string[]; artifact: string; max_age_hours?: number; os?: string; skippable?: { jobs: string[]; gate: string; scripts?: string[] } }
 export interface RemoteGateRuns { profiles: string[]; inventory: string; skipped?: string }
 export interface ApiRun {
   id: number; run_attempt: number; status: string; conclusion: string | null; event: string; head_sha: string;
@@ -65,12 +69,12 @@ export type RunRefusal = 'run_ref_invalid' | 'other_repository' | 'fork_run' | '
   | 'run_not_success' | 'job_missing' | 'job_ambiguous' | 'job_skipped' | 'job_not_success' | 'artifact_missing' | 'artifact_mismatch'
   | 'artifact_reused' | 'tree_mismatch' | 'newer_run_vetoes' | 'run_changed' | 'run_stale' | 'os_mismatch' | 'api_error';
 /** `skipped`: the files whose every test skipped on the runner (tree.json `skipped_files`, GST-1190); undefined when an older tree.json does not say. */
-export interface RunEvidence { run_id: number; run_attempt: number; head_sha: string; tree: string; profile: string; event: string; finished_at: string; files: string[]; tests: number | null; skipped?: string[] }
+export interface RunEvidence { run_id: number; run_attempt: number; head_sha: string; tree: string; profile: string; event: string; finished_at: string; files: string[]; tests: number | null; skipped?: string[]; skipped_jobs?: string[] }
 export type RunVerdict = { ok: true; evidence: RunEvidence } | { ok: false; reason: RunRefusal; detail: string };
 
 const SHA = /^[0-9a-f]{40}$/;
 const RUN_EVENTS = ['push', 'workflow_dispatch', 'pull_request'];
-const PROFILE_KEYS = ['workflow', 'events', 'jobs', 'artifact', 'max_age_hours', 'os'];
+const PROFILE_KEYS = ['workflow', 'events', 'jobs', 'artifact', 'max_age_hours', 'os', 'skippable'];
 const WORKFLOW_FILE = /^[A-Za-z0-9_.-]+\.ya?ml$/;
 const NAME = /^[A-Za-z0-9_.\/-]{1,128}$/;
 export const DEFAULT_MAX_AGE_HOURS = 24;
@@ -105,6 +109,14 @@ export function runProfileErrors(profiles: unknown, gateRuns: unknown): Array<{
       if (typeof p.artifact !== 'string' || !NAME.test(p.artifact)) errors.push({ path: `${at}.artifact`, message: 'must be the artifact name holding tree.json' });
       if ('max_age_hours' in p && (!Number.isInteger(p.max_age_hours) || (p.max_age_hours as number) < 1 || (p.max_age_hours as number) > 168)) errors.push({ path: `${at}.max_age_hours`, message: 'must be an integer from 1 to 168' });
       if ('os' in p && (typeof p.os !== 'string' || !/^(Linux|macOS|Windows)$/.test(p.os))) errors.push({ path: `${at}.os`, message: 'must be Linux, macOS or Windows' });
+      if ('skippable' in p) {
+        const s = p.skippable as Record<string, unknown> | null;
+        const names = (v: unknown) => Array.isArray(v) && v.length > 0 && v.length <= 32 && v.every(x => typeof x === 'string' && !!x.trim() && x.length <= 128);
+        const repoPath = (x: unknown) => typeof x === 'string' && !!x && !x.startsWith('/') && !x.split('/').includes('..') && !/[\0\r\n]/.test(x);
+        if (!s || typeof s !== 'object' || Array.isArray(s) || Object.keys(s).some(k => !['jobs', 'gate', 'scripts'].includes(k)) || !names(s.jobs) || typeof s.gate !== 'string' || !s.gate.trim()
+          || (s.jobs as string[]).includes(s.gate as string) || ('scripts' in s && (!Array.isArray(s.scripts) || !s.scripts.every(repoPath))))
+          errors.push({ path: `${at}.skippable`, message: 'must be { jobs: [job names], gate: <the job that decides the skip>, scripts?: [repo paths the gate runs] }, the gate not among the jobs' });
+      }
     }
   }
   if (gateRuns !== undefined && gateRuns !== null) {
@@ -133,7 +145,7 @@ export const normalPath = (f: string): string => f.replace(/^(\.\/)+/, '');
  * The verdict for run `runRef` under `profile`. `vetoHeads` are further heads
  * whose newer runs of the same workflow can veto (the consumer's own head).
  */
-export function verifyRun(deps: RunDeps, o: { repo: string; runRef: string; profileName: string; profile: RunProfile; vetoHeads?: string[]; now: Date }): RunVerdict {
+export function verifyRun(deps: RunDeps, o: { repo: string; runRef: string; profileName: string; profile: RunProfile; vetoHeads?: string[]; now: Date; unchanged?: (p: RunProfile) => string | null }): RunVerdict {
   const id = parseRunRef(o.runRef, o.repo);
   if (id === null) return fail('run_ref_invalid', `${JSON.stringify(o.runRef)} is not a run id or a run URL on ${o.repo}`);
   const p = o.profile;
@@ -154,11 +166,21 @@ export function verifyRun(deps: RunDeps, o: { repo: string; runRef: string; prof
     const maxAge = p.max_age_hours ?? DEFAULT_MAX_AGE_HOURS;
     if (!Number.isFinite(finished)) return fail('api_error', `${at} has no completion time`);
     if (o.now.getTime() - finished > maxAge * 3600_000) return fail('run_stale', `${at} finished ${finishedAt}, more than ${maxAge} h before now`);
+    const skippedJobs: string[] = [];
     for (const name of p.jobs) {
       const hits = jobs.filter(j => j.name === name);
       if (hits.length === 0) return fail('job_missing', `${at} has no job named ${name}`);
       if (hits.length > 1) return fail('job_ambiguous', `${at} has ${hits.length} jobs named ${name}`);
-      if (hits[0]!.conclusion === 'skipped') return fail('job_skipped', `${at}'s ${name} job was skipped`);
+      if (hits[0]!.conclusion === 'skipped') {
+        const skip = p.skippable;
+        if (!skip?.jobs.includes(name)) return fail('job_skipped', `${at}'s ${name} job was skipped`);
+        const gate = jobs.filter(j => j.name === skip.gate);
+        if (gate.length !== 1 || gate[0]!.conclusion !== 'success') return fail('job_skipped', `${at}'s ${name} job was skipped and its gate job ${skip.gate} ${gate.length === 1 ? `concluded ${gate[0]!.conclusion}` : gate.length ? 'is ambiguous' : 'is missing'}`);
+        const changed = o.unchanged ? o.unchanged(p) : 'no base copy of the workflow was compared';
+        if (changed) return fail('job_skipped', `${at}'s ${name} job was skipped, but ${changed}, so this branch decided the skip`);
+        skippedJobs.push(name);
+        continue;
+      }
       if (hits[0]!.conclusion !== 'success') return fail('job_not_success', `${at}'s ${name} job concluded ${hits[0]!.conclusion}`);
     }
     const heads = [...new Set([run.head_sha, ...(o.vetoHeads ?? []).filter(h => SHA.test(h))])];
@@ -194,7 +216,7 @@ export function verifyRun(deps: RunDeps, o: { repo: string; runRef: string; prof
     const changed = runChanged(deps, id, run.run_attempt);
     if (changed) return fail('run_changed', changed);
     const skipped = rec.skipped_files === undefined ? {} : { skipped: (rec.skipped_files as string[]).map(normalPath) };
-    return { ok: true, evidence: { run_id: id, run_attempt: run.run_attempt, head_sha: run.head_sha, tree: headTree, profile: o.profileName, event: run.event, finished_at: finishedAt!, files, tests, ...skipped } };
+    return { ok: true, evidence: { run_id: id, run_attempt: run.run_attempt, head_sha: run.head_sha, tree: headTree, profile: o.profileName, event: run.event, finished_at: finishedAt!, files, tests, ...skipped, ...(skippedJobs.length ? { skipped_jobs: skippedJobs } : {}) } };
   } catch (e: any) {
     return fail('api_error', `reading run ${id} failed: ${String(e?.message ?? e).slice(0, 300)}`);
   }
@@ -227,7 +249,8 @@ export function uncoveredFiles(inventory: string[], evidence: RunEvidence[], ski
 }
 
 /** What a run check reads: the repository, the verifier's dependencies, the base branch's profiles and the clock. */
-export interface RunSource { repo: string; deps: RunDeps; profiles: Record<string, RunProfile>; now: Date }
+/** `unchanged` (findCarry only): null when a profile's workflow and gate inputs match the base, else which file differs. */
+export interface RunSource { repo: string; deps: RunDeps; profiles: Record<string, RunProfile>; now: Date; unchanged?: (p: RunProfile) => string | null }
 export type FromRunVerdict = { ok: true; evidence: RunEvidence; receipt: string } | { ok: false; reason: string; detail: string };
 
 /**

lib/ship-bin-common.ts

@@ -172,7 +172,7 @@ export function laneConcurrency(mode: string | undefined, cpus = os.availablePar
   return cpus <= 4 ? 1 : Infinity;
 }
 
-export interface LaneResult { label: string; exit: number | null; testsRan: string; log: string; carried?: string; reused?: string; carryNone?: string }
+export interface LaneResult { label: string; exit: number | null; testsRan: string; log: string; carried?: string; reused?: string; carryNone?: string; notOwed?: string }
 
 /** The base branch's `ship_lanes_from` entry for each lane whose command is a key or a declared alias, byte for byte (the ledger binds its sha256). */
 export function mappedLanes(cwd: string, base: string, list: { label: string; command: string }[]): Map<string, ShipLaneMapping> {
@@ -191,7 +191,8 @@ export function mappedLanes(cwd: string, base: string, list: { label: string; co
 export function carryLane(cwd: string, base: string, l: { label: string; command: string }): LaneResult {
   const rec = bin(cwd, 'gstack-evidence', ['record-ci', '--label', l.label, '--base', base, '--', l.command], 600_000);
   const got = / tests_ran=(\d+|n\/a)( unit=files)? log=- source=ci runs=(\S+)/.exec(rec.stderr);
-  if (rec.status === 0 && got) return { label: l.label, exit: 0, testsRan: got[2] ? `${got[1]} (files)` : got[1]!, log: '-', carried: got[3]! };
+  const notOwed = /^gstack-evidence: not owed: (.+)$/m.exec(rec.stderr)?.[1];
+  if (rec.status === 0 && got) return { label: l.label, exit: 0, testsRan: got[2] ? `${got[1]} (files)` : got[1]!, log: '-', carried: got[3]!, ...(notOwed ? { notOwed } : {}) };
   return { label: l.label, exit: null, testsRan: 'unknown', log: '-', carryNone: /^CARRY_NONE: (.+)$/m.exec(rec.stderr)?.[1] ?? `record_failed: ${firstLine(rec.stderr)}` };
 }
 
@@ -223,6 +224,7 @@ export async function runLanes(cwd: string, list: { label: string; command: stri
 
 /** Step 5's lane verdict: a lane passes on its runner count, never exit 0 alone; a carried lane names its CI runs. */
 export function laneLine(l: LaneResult): { line: string; ok: boolean } {
+  if (l.notOwed) return { line: `LANE: ${l.label} not owed: ${l.notOwed} run=${l.carried}`, ok: true };
   if (l.carried) return { line: `LANE: ${l.label} carried run=${l.carried} tests_ran=${l.testsRan}`, ok: true };
   const zero = l.exit === 0 && l.testsRan === '0';
   const state = l.exit !== 0 ? 'FAIL' : zero ? 'ZERO-RUN' : l.testsRan === 'unknown' ? 'pass (count unavailable)' : 'pass';

test/ship-ci-carry.test.ts

@@ -411,3 +411,63 @@ describe('GST-1190: a file whose every test skipped on CI is not carried', () =>
     expect(stage().stdout + stage().stderr).toMatch(/REUSE: accepted 2 of 2 selected local test file\(s\) from run .*; 0 still run/);
   });
 });
+
+describe('GST-1190: a path-skipped CI job counts only under an unchanged gate', () => {
+  // Value: protects=a lane whose CI job the workflow skipped by path is not owed only when the gate job that decided the skip succeeded and the
+  //   workflow and the gate's scripts are byte-identical to origin/<base>; otherwise the branch controlled the skip and the lane runs here;
+  //   fails_when=a branch edits the workflow or the gate script to skip its own typecheck and the lane still passes; why_new=TRUT-7 (truther #1169); seam=fake gh
+  const TSC = 'bunx tsc --noEmit';
+  const SKIP_PROFILE = { ...PROFILE, jobs: ['suite'], skippable: { jobs: ['typecheck'], gate: 'changes' } };
+  const WORKFLOW = 'name: Free\non: [pull_request, workflow_dispatch]\njobs:\n  changes:\n    runs-on: ubuntu-latest\n    steps:\n      - run: bash scripts/changes.sh\n  suite:\n    runs-on: ubuntu-latest\n    steps:\n      - run: bun test\n  typecheck:\n    needs: changes\n    runs-on: ubuntu-latest\n    steps:\n      - run: bunx tsc --noEmit\n';
+  const SKIP_BASE = {
+    '.gstack/pregate.json': JSON.stringify({ run_profiles: { 'ci/free': SKIP_PROFILE }, ship_lanes_from: { [TSC]: { profiles: ['ci/free'], jobs: ['typecheck'] } } }) + '\n',
+    '.github/workflows/free.yml': WORKFLOW,
+    'scripts/changes.sh': 'echo "typecheck=false" >> "$GITHUB_OUTPUT"\n',
+  };
+  const JOBS = (gate: string) => [{ name: 'changes', conclusion: gate }, { name: 'suite', conclusion: 'success' }, { name: 'typecheck', conclusion: 'skipped' }];
+  const setup = (feat: Record<string, string> = { 'src/b.ts': 'export const b = 2;\n' }, gate = 'success') => {
+    const f = shipFixture(SKIP_BASE, feat); fixtures.push(f);
+    world(f, { jobs: JOBS(gate), tree: { files: [], tests: 0 } });
+    return f;
+  };
+  const lane = (f: ShipFx) => preflight(f, [`tsc=${TSC}`]);
+
+  test('a skip the unchanged gate decided is not owed', () => {
+    const f = setup();
+    const out = lane(f);
+    expect(out.stdout).toContain('LANE: tsc not owed: CI skipped at this tree (gate job changes, workflow unchanged) run=7/1');
+    const row = JSON.parse(fs.readFileSync(findFilesBySuffix(path.join(f.state, 'projects'), '-evidence.jsonl')[0]!, 'utf8').trim().split('\n').at(-1)!);
+    expect([row.tests_ran, row.not_owed]).toEqual(['n/a', 'CI skipped at this tree (gate job changes, workflow unchanged)']);
+  });
+
+  test('a branch that changed the workflow decided its own skip: the lane runs here', () => {
+    const f = setup({ '.github/workflows/free.yml': WORKFLOW + '# skip more\n' });
+    expect(lane(f).stdout).toContain('CI_CARRY: none label=tsc (no_verified_run: ci/free: run 7: job_skipped)');
+  });
+
+  test('a branch that changed the gate script decided its own skip: the lane runs here', () => {
+    const f = setup({ 'scripts/changes.sh': 'echo "typecheck=false" >> "$GITHUB_OUTPUT" # always\n' });
+    expect(lane(f).stdout).toContain('CI_CARRY: none label=tsc (no_verified_run: ci/free: run 7: job_skipped)');
+  });
+
+  test('a gate job that failed decided nothing: the lane runs here', () => {
+    const f = setup(undefined, 'failure');
+    expect(lane(f).stdout).toContain('CI_CARRY: none label=tsc (no_verified_run: ci/free: run 7: job_skipped)');
+  });
+
+  test('gstack-ci-carry find --policy-from head --simulate checks the branch map, says SIMULATION on every line and writes nothing', () => {
+    const VERIFY = 'bun run verify';
+    const head = JSON.stringify({ run_profiles: { 'ci/free': PROFILE }, ship_lanes_from: { [VERIFY]: { profiles: ['ci/free'], jobs: ['suite'] } } }) + '\n';
+    const f = shipFixture({ '.github/workflows/free.yml': BASE['.github/workflows/free.yml'] }, { '.gstack/pregate.json': head }); fixtures.push(f);
+    world(f, { tree: { files: [], tests: 0 } });
+    const cli = (args: string[]) => f.run(path.join(BIN, 'gstack-ci-carry'), args);
+    const sim = cli(['find', '--base', 'main', '--policy-from', 'head', '--simulate', '--command', VERIFY, '--allow-repo-commands']);
+    expect(sim.status).toBe(0);
+    expect(sim.stdout.trim().split('\n').every(l => l.startsWith('SIMULATION: '))).toBe(true);
+    expect(sim.stdout).toMatch(/^SIMULATION: CI_CARRY: accepted ci-carry tree=[0-9a-f]{12} jobs=suite /m);
+    expect(fs.existsSync(path.join(f.state, 'projects')) ? findFilesBySuffix(path.join(f.state, 'projects'), '-evidence.jsonl') : []).toEqual([]);
+    expect(cli(['find', '--base', 'main', '--command', VERIFY, '--allow-repo-commands']).stdout).toContain('CI_CARRY: none (not_mapped');
+    expect(cli(['find', '--base', 'main', '--simulate']).status).toBe(2);
+    expect(cli(['wait', '--base', 'main', '--policy-from', 'head', '--simulate']).status).toBe(2);
+  });
+});