@vaultcompass/conductor 0.2.3 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -248,6 +248,12 @@ proceeds normally without mentioning them.
248
248
  - `--base <ref>` measures the intent gate against what this branch changed
249
249
  since `<ref>`, rather than against the index. See "Intent at a pull
250
250
  request" below.
251
+ - `--trust-base <ref>` reads the **rules** from `<ref>` instead of from the
252
+ tree being judged: this repository's own `.guardrails.yaml`, and every
253
+ control input of the gates that support it. See "The pull-request trust
254
+ boundary" below. `--base` and `--trust-base` are independent and a
255
+ pull-request run passes both: `--base` decides which paths are judged,
256
+ `--trust-base` decides what they are judged by.
251
257
  - `--spec <path>` names the spec the intent gate imports its contract from.
252
258
  - `--output <path>` writes the report to a file instead of to stdout, for a
253
259
  CI step that uploads it. One line still goes to stdout, because a job whose
@@ -270,6 +276,127 @@ proceeds normally without mentioning them.
270
276
  stdout, which is what a rejected config file looks like from two of the
271
277
  three.
272
278
 
279
+ ## The pull-request trust boundary
280
+
281
+ Every gate reads its own rules out of the repository it is judging. On a pull
282
+ request the author controls that repository, so without this a pull request
283
+ could turn a gate off in the same commit that carries the thing the gate
284
+ exists to catch, and the report would say the run was clean. For the umbrella
285
+ the sharpest version is `command:`, which names a program to run: a pull
286
+ request could point a gate at a script it added in the same commit.
287
+
288
+ **On a pull-request run the rules come from the base branch.** With
289
+ `--trust-base <ref>` the umbrella reads `.guardrails.yaml` from that ref with
290
+ `git show` and judges the head tree against it. A `.guardrails.yaml` in the
291
+ pull request never takes effect for that run, `command:` and `args:`
292
+ included, so **a pull request cannot change the rules it is judged by, and
293
+ cannot choose the program that judges it, as long as that program is
294
+ self-contained** (see the directory rule below). The same ref is passed
295
+ down to every gate that supports it, so their contracts, configs and
296
+ baselines come from the base branch too.
297
+
298
+ **The program is checked as well as the rules.** Reading the rules from the
299
+ base ref is worth nothing if the pull request supplies the binary that
300
+ applies them, and without this it could, two ways that both look ordinary in
301
+ a diff: a base `command:` pointing at a path inside the repository, where the
302
+ head replaces the file behind the approved path; and no `command:` at all,
303
+ where a head-committed `node_modules/.bin/<gate>` shadows the real gate,
304
+ because resolution prefers the repository's own copy over PATH so that a
305
+ project pin beats a global install.
306
+
307
+ So on a pull-request run a gate's program must be **outside the working tree**
308
+ (on PATH, or an absolute `command:` elsewhere on the machine), or else meet
309
+ **both** of these:
310
+
311
+ - it is a **tracked regular file whose contents are identical** at the base
312
+ ref and at the head commit; and
313
+ - **the tree object id of its containing directory is identical** at those
314
+ two refs, which is to say the pull request changed nothing anywhere in that
315
+ directory's subtree.
316
+
317
+ Both are compared with `git ls-tree` on both refs and never read from the
318
+ working tree. The second is not belt and braces. A vendored gate is rarely
319
+ one file: `vendor/vault-guard` execs `vendor/impl.sh`, and a pull request
320
+ that leaves the wrapper byte for byte alone and rewrites the helper beside it
321
+ passes a per-file check while running its own code. Comparing the directory
322
+ covers every file under it at once, without this tool having to know what a
323
+ wrapper calls.
324
+
325
+ **What is and is not vetted**, exactly: the program file and everything in
326
+ its directory subtree. Anything the program reaches **outside** that
327
+ directory is not vetted at all, so an in-repo gate must be **self-contained
328
+ within its own directory**. A program at the repository ROOT is refused, and
329
+ the message says to give it a directory: at the root the containing directory
330
+ is the whole repository, so the rule would mean "no pull request may change
331
+ anything".
332
+
333
+ A symlink inside the repository is refused on **its own entry**, before its
334
+ target is considered: it is either untracked, or its tree entry is a link
335
+ rather than a regular file, and either refuses. (A symlink whose own path is
336
+ outside the tree but which points into it has its target vetted; that is the
337
+ case following the link exists for.)
338
+
339
+ Anything else is could-not-run for that gate, naming the path, and it reaches
340
+ the exit code even where the policy sets `enforce: false`, because the gate
341
+ produced no findings to un-enforce: the umbrella declined to run a program
342
+ the pull request chose.
343
+
344
+ Nothing under `node_modules` is ever base-approved, and that is the right
345
+ answer rather than a limitation: what is there is chosen by the head's own
346
+ manifest and lockfile and installed by a step that runs before the gates, so
347
+ git has no record of those bytes at either ref. A pull request that edits its
348
+ lockfile to pull a different build of a gate has chosen its own judge just as
349
+ surely as one that commits a stub. **Vendoring a gate still works**, on those
350
+ terms: put it in its own directory, keep everything it needs inside that
351
+ directory, and leave the whole directory alone in a pull request the gate is
352
+ meant to judge. Changing it is not forbidden, it just has to land on the base
353
+ branch first, like any other rule change.
354
+
355
+ **A change to the rules is not refused, it is proposed.** Rules legitimately
356
+ change, and a gate that blocked every such pull request would train people to
357
+ bypass it. So a policy file that differs from the base ref's is reported as
358
+ one line, `policy changed in this pull request`, the run continues under the
359
+ base ref's rules, and the change takes effect **after merge**, on the first
360
+ run whose base branch carries it. The gates' own proposals are summed with it
361
+ into one sentence, `N control change(s) proposed in this pull request`, on the
362
+ one-line summary and on the verdict, with a line each under `--verbose` and a
363
+ `conductor/control-change-proposed` notification each in the SARIF log. A
364
+ reflow, a re-quote or an edited comment is not a proposal: the two files are
365
+ compared as parsed documents.
366
+
367
+ **It fails closed.** A `--trust-base` that does not resolve is not a reason to
368
+ fall back to the pull request's own file, because that fallback is the hole:
369
+ the run exits 2 and the report **leads with the refusal**, naming the ref and
370
+ the remedy, whether or not it can name any gate. That last part matters: with
371
+ no base ref there is no base policy, so the only list of gates available is
372
+ the head's, and a head that switches every gate off leaves it empty. So is a
373
+ base ref that resolves to the head commit, or to a different commit carrying
374
+ the head's tree, both of which would put the rules back inside the tree being
375
+ judged while still reporting pull-request mode as on. Pass the base
376
+ **branch**, never a SHA: on a `pull_request` event `github.sha` is the merge
377
+ commit, which is HEAD. If the base branch has no `.guardrails.yaml` at all,
378
+ the run has no rules and exits 2 rather than using the pull request's; the
379
+ file the pull request adds decides what runs once it is on the base branch.
380
+
381
+ **Which gates are covered.** All three: dep-guard from **0.6.0**,
382
+ intent-guard from **1.4.0**, vault-guard from **1.7.0**.
383
+
384
+ The umbrella asks each gate its version and passes the flag only to a build
385
+ that understands it, so an older gate is not handed a flag it would reject. A
386
+ gate that was not put into pull-request mode read its own rules out of the
387
+ tree being judged, which is the thing this exists to prevent, so it is never
388
+ silent: it gets a line in the report, a clause on the clean one-line summary,
389
+ and a `conductor/trust-base-not-passed` notification in the SARIF log. For a
390
+ gate that IS in the table, a version that cannot be read at all is
391
+ could-not-run rather than a quiet downgrade: the umbrella cannot establish
392
+ that the gate would take its rules from the base ref, and running it anyway
393
+ would put it outside the boundary on exactly the runs where something is
394
+ already wrong.
395
+
396
+ Outside pull-request mode nothing changes. A pre-commit hook and a direct run
397
+ on your own checkout are already inside the trust boundary, and neither passes
398
+ the flag.
399
+
273
400
  ## Intent at a pull request
274
401
 
275
402
  The intent gate is the only one of the three with any ceremony: its native
@@ -371,6 +498,21 @@ with a sentence saying to add it as a devDependency. `--base` is passed only whe
371
498
  itself and treats an empty value as "not a pull request", which is what a
372
499
  push build wants.
373
500
 
501
+ On a `pull_request` event the action passes
502
+ **`--trust-base origin/$GITHUB_BASE_REF`** of its own accord, so the run takes
503
+ its configuration from the base branch and the pull request cannot change the
504
+ rules it is judged by; a change to the rules shows as a proposal line and
505
+ takes effect after merge. See "The pull-request trust boundary" above. On any
506
+ other event it passes nothing and behaviour is unchanged. The `trust-base`
507
+ input names the ref explicitly, for a platform where `GITHUB_BASE_REF` is not
508
+ set.
509
+
510
+ There is deliberately **no input that turns pull-request mode off**.
511
+ Base-ref judging is the floor rather than a knob, and on a `pull_request`
512
+ event the workflow file itself runs from the pull request's own ref, so an
513
+ opt-out here would be settable by the very pull request the mode exists to
514
+ judge: the knob and the thing it protects against would be the same file.
515
+
374
516
  ```yaml
375
517
  name: guardrails
376
518
  on: pull_request
@@ -384,8 +526,11 @@ jobs:
384
526
  steps:
385
527
  - uses: actions/checkout@v4
386
528
  with:
387
- # Required. Without it there is no merge base to diff against, and
388
- # the intent gate fails closed rather than checking an empty set.
529
+ # Required, for two reasons now. Without it there is no merge base
530
+ # to diff against, and the intent gate fails closed rather than
531
+ # checking an empty set. And the base ref itself has to be in the
532
+ # clone, because on a pull request the rules are read from it: a
533
+ # base ref that will not resolve is exit 2 for every enabled gate.
389
534
  fetch-depth: 0
390
535
  - uses: pnpm/action-setup@v4
391
536
  - uses: actions/setup-node@v4
package/dist/cli.js CHANGED
@@ -14,8 +14,9 @@ import { EXIT_COULD_NOT_RUN } from './exit-codes.js';
14
14
  import { applyInit, planInit, renderInitHuman, renderRevertHuman, revertInit, } from './init.js';
15
15
  import { renderSarif } from './output-sarif.js';
16
16
  import { renderText } from './output-text.js';
17
- import { GATE_ROLES, GATE_STAGES, PolicyError, applyCliOverrides, loadPolicy } from './policy.js';
18
- import { runAll } from './run.js';
17
+ import { GATE_ROLES, GATE_STAGES, POLICY_FILE_NAME, PolicyError, applyCliOverrides, loadPolicy, parsePolicy, } from './policy.js';
18
+ import { refusedTrustBase, runAll } from './run.js';
19
+ import { policyDiffers, readPolicyAtRef, refuseTrustBaseRef } from './trust-base.js';
19
20
  const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
20
21
  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
21
22
  /**
@@ -64,6 +65,74 @@ function repoRoot(cwd) {
64
65
  throw new Error(`git could not be run to find the repository root: ${err.message}`);
65
66
  }
66
67
  }
68
+ /**
69
+ * Reads the policy for one run, from the base ref in pull-request mode.
70
+ *
71
+ * THE HEAD'S POLICY FILE IS NEVER PARSED INTO A RUN IN PULL-REQUEST MODE, and
72
+ * that is the whole of the fix. A pull request that rewrites `.guardrails.yaml`
73
+ * to point a gate's `command:` at a script it added, or to switch off the gate
74
+ * that would have caught what else is in the commit, gets the base ref's
75
+ * policy and a line saying its own was proposed.
76
+ *
77
+ * The head's file is read for exactly two things, neither of which can change
78
+ * what runs: it is compared with the base's so the difference can be
79
+ * reported, and, when the trust base itself cannot be used, it names the
80
+ * gates the report says did not run.
81
+ */
82
+ function policyForRun(root, trustBase, overrides) {
83
+ if (trustBase === undefined) {
84
+ return { kind: 'policy', policy: applyCliOverrides(loadPolicy(root), overrides) };
85
+ }
86
+ const refusal = refuseTrustBaseRef(root, trustBase);
87
+ if (refusal !== null) {
88
+ // An inventory, and only an inventory: a list of gate NAMES for the
89
+ // report, taken from the one file available when the base ref cannot be
90
+ // read. It is head-controlled, so it can be SHORTER as well as longer
91
+ // than the base's -- every gate `enabled: false`, or a file that will not
92
+ // parse at all, leaves it empty -- and an earlier comment here claimed
93
+ // only the longer direction, which is how the empty case went unnoticed.
94
+ //
95
+ // Neither direction can weaken the verdict, and that is the property this
96
+ // rests on rather than on the inventory being right. refusedTrustBase
97
+ // enforces every gate it names and writes exit 2 itself, and the refusal
98
+ // is carried on the result so both renderers lead with it whether the
99
+ // inventory names three gates or none. A longer list makes the report
100
+ // longer; a shorter one makes it shorter; the verdict is the same
101
+ // sentence either way.
102
+ //
103
+ // An unreadable head file leaves the list empty rather than replacing the
104
+ // refusal with a policy error: the ref is what went wrong, and reporting
105
+ // the head's malformed file would send the reader to the wrong fix on a
106
+ // run that would have ignored that file anyway.
107
+ let inventory = { version: 1, gates: {}, report: { format: 'text' } };
108
+ try {
109
+ inventory = applyCliOverrides(loadPolicy(root), overrides);
110
+ }
111
+ catch {
112
+ inventory = { version: 1, gates: {}, report: { format: 'text' } };
113
+ }
114
+ return { kind: 'refused', ref: trustBase, detail: refusal, inventory };
115
+ }
116
+ const baseText = readPolicyAtRef(root, trustBase);
117
+ const headText = readPolicyAtRef(root, 'HEAD');
118
+ if (baseText === null) {
119
+ throw new PolicyError(`No ${POLICY_FILE_NAME} on "${trustBase}". On a pull-request run every rule comes from the ` +
120
+ 'base ref, so this run has no policy at all and nothing was checked. ' +
121
+ (headText === null
122
+ ? `Run "conductor init" on the base branch.`
123
+ : `The ${POLICY_FILE_NAME} in this pull request is a proposal: it decides what runs ` +
124
+ 'once it is on the base branch, and never on the pull request that adds it.'));
125
+ }
126
+ return {
127
+ kind: 'policy',
128
+ policy: applyCliOverrides(parsePolicy(baseText, `${trustBase}:${POLICY_FILE_NAME}`), overrides),
129
+ trustBase: {
130
+ ref: trustBase,
131
+ policyChanged: policyDiffers(baseText, headText),
132
+ refusal: null,
133
+ },
134
+ };
135
+ }
67
136
  function parseFormat(value) {
68
137
  if (value !== 'text' && value !== 'sarif') {
69
138
  throw new PolicyError(`--format must be "text" or "sarif", got "${value}".`);
@@ -125,7 +194,11 @@ export function buildProgram() {
125
194
  const cwd = process.cwd();
126
195
  const shared = { cwd, pathValue: process.env.PATH ?? '' };
127
196
  if (options.revert) {
128
- const result = revertInit({ ...shared, force: Boolean(options.force) });
197
+ const result = revertInit({
198
+ ...shared,
199
+ force: Boolean(options.force),
200
+ dryRun: Boolean(options.dryRun),
201
+ });
129
202
  const rendered = `${renderRevertHuman(result)}\n`;
130
203
  if (options.json) {
131
204
  process.stdout.write(`${JSON.stringify(result)}\n`);
@@ -167,6 +240,7 @@ export function buildProgram() {
167
240
  .option('--format <format>', 'output format: text or sarif')
168
241
  .option('--stage <stage>', `which stopping point this run is: ${GATE_STAGES.join(', ')}. Stages are cumulative, so a gate runs at its own stage and every later one. Omit it to run every enabled gate.`)
169
242
  .option('--base <ref>', 'measure the intent gate against what this branch changed since <ref>, rather than against the index. In Actions this defaults to origin/<GITHUB_BASE_REF> when it is set.')
243
+ .option('--trust-base <ref>', 'pull-request mode: read .guardrails.yaml from this ref instead of from the tree being judged, and pass the same ref to every gate that supports it. A policy change in the pull request is reported as a proposal and never takes effect for the run, so a pull request cannot change the rules it is judged by. In Actions the composite action passes origin/<GITHUB_BASE_REF> on a pull_request event.')
170
244
  .option('--output <path>', 'write the report to this file instead of to stdout, for a CI step that uploads it')
171
245
  .option('--spec <path>', 'the spec the intent gate imports its contract from, outranking a Spec: line in the pull request body and the branch-name convention')
172
246
  .option('--verbose', 'print the full per-gate report even when the run is clean. A clean run prints one summary line by default, because a pre-commit hook that prints a screenful on every commit is a hook a team switches off. Text output only; SARIF is unaffected.')
@@ -179,22 +253,29 @@ export function buildProgram() {
179
253
  // and the catch below is what turns any of its three sentences into
180
254
  // one line on stderr and the could-not-run exit code.
181
255
  const root = repoRoot(cwd);
182
- const policy = applyCliOverrides(loadPolicy(root), {
256
+ const overrides = {
183
257
  ...(parseRoles(options.gate) === undefined
184
258
  ? {}
185
259
  : { gates: parseRoles(options.gate) }),
186
- });
187
- const format = parseFormat(options.format ?? policy.report.format);
260
+ };
188
261
  const stage = parseStage(options.stage);
189
- const result = runAll(policy, {
190
- repoRoot: root,
191
- staged: Boolean(options.staged),
192
- pathValue: process.env.PATH ?? '',
193
- env: process.env,
194
- ...(stage === undefined ? {} : { stage }),
195
- ...(options.base === undefined ? {} : { base: options.base }),
196
- ...(options.spec === undefined ? {} : { spec: options.spec }),
197
- });
262
+ const source = policyForRun(root, options.trustBase, overrides);
263
+ const policy = source.kind === 'policy' ? source.policy : source.inventory;
264
+ const format = parseFormat(options.format ?? policy.report.format);
265
+ const result = source.kind === 'refused'
266
+ ? refusedTrustBase(source.inventory, source.ref, source.detail, {
267
+ ...(stage === undefined ? {} : { stage }),
268
+ })
269
+ : runAll(source.policy, {
270
+ repoRoot: root,
271
+ staged: Boolean(options.staged),
272
+ pathValue: process.env.PATH ?? '',
273
+ env: process.env,
274
+ ...(stage === undefined ? {} : { stage }),
275
+ ...(options.base === undefined ? {} : { base: options.base }),
276
+ ...(options.spec === undefined ? {} : { spec: options.spec }),
277
+ ...(source.trustBase === undefined ? {} : { trustBase: source.trustBase }),
278
+ });
198
279
  const rendered = format === 'sarif'
199
280
  ? `${renderSarif(result, pkg.version)}\n`
200
281
  : renderText(result, { verbose: Boolean(options.verbose) });
@@ -95,6 +95,22 @@ export interface NormalizedGateOutput {
95
95
  run: RunSummary;
96
96
  /** Problems with the normalization itself, not with the scanned code. */
97
97
  diagnostics: Diagnostic[];
98
+ /**
99
+ * What the gate said about pull-request mode, when it was in it.
100
+ *
101
+ * NOT findings, and deliberately not folded into `run.details`. A proposed
102
+ * control change is a statement about the configuration this pull request
103
+ * would like to have, so it must never reach a severity, a fingerprint, a
104
+ * blocking count or an exit code; it is summed by the umbrella and printed
105
+ * as one sentence. `run.details` is rendered as loose scalars in the text
106
+ * report, which would scatter these across a line instead.
107
+ */
108
+ trustBase?: {
109
+ /** The ref that gate took its control inputs from, as it reported it. */
110
+ ref: string;
111
+ /** One line per control input the head proposes to change. */
112
+ proposals: string[];
113
+ };
98
114
  }
99
115
  export declare class NormalizeError extends Error {
100
116
  constructor(message: string);
@@ -8,11 +8,100 @@ export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing'
8
8
  * an unresolvable base ref, or a spec that would not import. Distinct from
9
9
  * gate-error on purpose, since the gate itself said nothing at all.
10
10
  */
11
- | 'preparation-failed';
11
+ | 'preparation-failed'
12
+ /**
13
+ * On a pull-request run, the umbrella could not establish that this gate
14
+ * would take its rules from the base ref, so it was not spawned. Raised for
15
+ * a gate in `TRUST_BASE_MIN_VERSION` whose version could not be read.
16
+ * Distinct from `preparation-failed`, which is about the run rather than
17
+ * about this gate, and from `binary-missing`, since the binary was found.
18
+ */
19
+ | 'trust-base-unverified'
20
+ /**
21
+ * On a pull-request run, the gate's PROGRAM is a file the head controls, so
22
+ * it was not run. Its own reason rather than a shape of
23
+ * `trust-base-unverified`, because the two send a reader to different
24
+ * places: one is a packaging problem with the installed gate, and this one
25
+ * is a pull request choosing the program that judges it.
26
+ */
27
+ | 'gate-program-refused';
12
28
  export interface CouldNotRun {
13
29
  reason: CouldNotRunReason;
14
30
  detail: string;
15
31
  }
32
+ /**
33
+ * The first version of each gate that understands `--trust-base`.
34
+ *
35
+ * A TABLE rather than a boolean, because the three gates get pull-request
36
+ * mode in three separate releases and the umbrella has to keep working
37
+ * against every combination in the meantime. A product missing from this
38
+ * table has no pull-request mode yet and is never handed the flag; a product
39
+ * in it is handed the flag only when the installed build says it is at least
40
+ * this version. Both directions matter: handing an older build a flag it does
41
+ * not parse makes it exit non-zero with no JSON, which the umbrella correctly
42
+ * reports as could-not-run, so a wrong guess here turns a working repository's
43
+ * pull requests red rather than merely leaving a gate un-hardened.
44
+ *
45
+ * The umbrella is deliberately NOT the place a version pin lives otherwise
46
+ * (nothing here imports any gate's package), and this is the one exception:
47
+ * it is a statement about a command-line flag, which is the only interface
48
+ * this package has to those tools.
49
+ */
50
+ export declare const TRUST_BASE_MIN_VERSION: Partial<Record<Product, string>>;
51
+ /**
52
+ * Pull-request mode as it applied to ONE gate.
53
+ *
54
+ * Carried on the outcome rather than worked out again by each reporter,
55
+ * because two different things have to be visible and neither is derivable
56
+ * from the other: whether this gate was actually put into pull-request mode,
57
+ * and what it said about the control inputs the head proposes to change.
58
+ *
59
+ * `withheld` is the half that must never be silent. A gate the umbrella could
60
+ * not put into pull-request mode read its own control inputs out of the tree
61
+ * under judgment, which is the whole hole this release exists to close, and a
62
+ * run where that happened must not look like a run where it did not.
63
+ */
64
+ export interface GateTrustBase {
65
+ /** The ref the umbrella took its own policy from, and offered to this gate. */
66
+ ref: string;
67
+ /**
68
+ * Null when the flag was passed; otherwise the reason it was not, for a
69
+ * gate that was never going to be inside the boundary in the first place.
70
+ * The run continues: that gate read its own control inputs from the tree
71
+ * being judged, and the report says so.
72
+ */
73
+ withheld: string | null;
74
+ /**
75
+ * Set when the umbrella could not ESTABLISH that this gate would be in
76
+ * pull-request mode, which is could-not-run rather than a downgrade.
77
+ *
78
+ * The distinction is the whole point and it is not symmetry with
79
+ * `withheld`. A gate outside the table was never going to get the flag, so
80
+ * nothing is unknown about it. A gate INSIDE the table is one this
81
+ * repository expects to be inside the boundary, and a version probe that
82
+ * fails leaves that unestablished for an unexplained reason. Falling back
83
+ * to running it anyway would put it quietly outside the boundary on the
84
+ * exact runs where something is already wrong.
85
+ */
86
+ refused: string | null;
87
+ /** The control-input changes this gate reported as proposed. */
88
+ proposals: string[];
89
+ }
90
+ /**
91
+ * Whether this gate can be handed `--trust-base`, and why not when it cannot.
92
+ *
93
+ * Exported so the decision can be tested directly rather than only through a
94
+ * spawned child, and so there is exactly one copy of it.
95
+ *
96
+ * THE PROJECT DIRECTORY IS THE FIRST TEST, not the version. The flag names a
97
+ * git ref, and intent-guard resolves it against its own `--project`. On a
98
+ * run with an imported contract that directory is a temporary one the
99
+ * umbrella made, holding a contract and nothing else, with no repository in
100
+ * it: the child would exit 2 on a ref it could not resolve, and the gate that
101
+ * was working a moment ago would report could-not-run. So the flag goes only
102
+ * where `--project` is the repository itself.
103
+ */
104
+ export declare function decideTrustBase(gate: GatePolicy, intent: IntentPreparation | undefined, trustBase: string | undefined, productVersion: string | null): GateTrustBase | undefined;
16
105
  export interface GateOutcome {
17
106
  role: GateRole;
18
107
  product: Product;
@@ -47,6 +136,11 @@ export interface GateOutcome {
47
136
  contractSource: ContractSource;
48
137
  baseRef: string | null;
49
138
  };
139
+ /**
140
+ * Present only on a pull-request run. Whether this gate was put into
141
+ * pull-request mode, and what it said was proposed.
142
+ */
143
+ trustBase?: GateTrustBase;
50
144
  }
51
145
  export interface RunGateOptions {
52
146
  repoRoot: string;
@@ -57,6 +151,22 @@ export interface RunGateOptions {
57
151
  timeoutMs?: number;
58
152
  /** The contract and change set prepared for the intent gate, when there is one. */
59
153
  intent?: IntentPreparation;
154
+ /**
155
+ * The repository's own frozen contract, for a run with NO preparation.
156
+ *
157
+ * A plain `conductor run` never prepares anything, but the intent gate
158
+ * still judges against the contract in the repository, resolved by the
159
+ * child from `--project .`. Recording it makes that visible: the report
160
+ * says which contract, and the SARIF fallback files the gate's own results
161
+ * against the contract they are about rather than against the policy file.
162
+ * Ignored when `intent` is set, which already carries the same fact.
163
+ */
164
+ intentContract?: string;
165
+ /**
166
+ * The ref the umbrella took its own policy from, on a pull-request run.
167
+ * Offered to every child; `decideTrustBase` says which ones can take it.
168
+ */
169
+ trustBase?: string;
60
170
  }
61
171
  /**
62
172
  * A gate that never got as far as being spawned.
@@ -83,7 +193,13 @@ export declare function preparationFailed(gate: GatePolicy, detail: string): Gat
83
193
  * decided by that gate's own argument parser rather than by anything the
84
194
  * user could read in their own policy file.
85
195
  */
86
- export declare function gateArgs(gate: GatePolicy, staged: boolean, intent: IntentPreparation | undefined): string[];
196
+ export declare function gateArgs(gate: GatePolicy, staged: boolean, intent: IntentPreparation | undefined,
197
+ /**
198
+ * The trust base to hand THIS gate, or undefined. Already decided by
199
+ * `decideTrustBase`; nothing here re-decides it, so a gate that cannot take
200
+ * the flag is never handed one by a second opinion written in this switch.
201
+ */
202
+ trustBase?: string): string[];
87
203
  /**
88
204
  * Runs one gate. TOTAL: this never throws.
89
205
  *