@vaultcompass/conductor 0.4.6 → 0.5.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
@@ -1,8 +1,34 @@
1
1
  # conductor
2
2
 
3
- conductor is the optional layer over three guardrail gates that each work on
4
- their own. All it adds is one policy file, one init, one hook and one report.
5
- Delete it and every gate still runs, with exactly the configuration it had.
3
+ conductor is the one required check for a repository an AI agent edits. It
4
+ runs the scanners a maintainer already trusts, and adds the checks those
5
+ scanners cannot do on their own: a hallucinated package name, a credential
6
+ caught before the edit lands, a pull request that edits its own gate, a
7
+ change that reaches outside what was approved for it.
8
+
9
+ It does that by running five gates over one policy file, one init, one
10
+ hook and one report: three from this family, and two the adopter already
11
+ installs, gitleaks for secrets anywhere in git history and osv-scanner for
12
+ known vulnerabilities. conductor scans nothing itself and installs nothing
13
+ that is not its own. Delete conductor and every one of those five still
14
+ runs, with exactly the configuration it had.
15
+
16
+ The claim is checked in public. The
17
+ [conductor-proof](https://github.com/vaultcompasshq/conductor-proof)
18
+ repository runs an ordinary gitleaks and osv-scanner job beside conductor,
19
+ with four pull requests left open on purpose, one planted problem each.
20
+ Read the checks on each pull request rather than this table.
21
+
22
+ | Planted problem | Ordinary job | conductor |
23
+ | --- | --- | --- |
24
+ | [A dependency whose name does not exist on npm](https://github.com/vaultcompasshq/conductor-proof/pull/6) | pass | fail |
25
+ | [A pull request that turns off its own checks, then adds that dependency](https://github.com/vaultcompasshq/conductor-proof/pull/7) | skipped | fail |
26
+ | [A credential-shaped string in a test fixture](https://github.com/vaultcompasshq/conductor-proof/pull/8) | fail | fail |
27
+ | [An edit to a path the intent contract protects](https://github.com/vaultcompasshq/conductor-proof/pull/11) | pass | fail |
28
+
29
+ The third row is parity, not a catch: both jobs see a credential shape.
30
+ The other three are what a scanner that only knows about vulnerabilities
31
+ and secrets has no way to know.
6
32
 
7
33
  <!-- guardrails-family: shared block, keep it identical in dep-guard, vault-guard, intent-guard and conductor -->
8
34
  The Vault & Compass guardrails are three gates over an AI-assisted coding
@@ -20,17 +46,192 @@ optional umbrella that runs them from one policy file, one hook and one
20
46
  report.
21
47
  <!-- /guardrails-family -->
22
48
 
49
+ ## Adopting conductor
50
+
51
+ The first pull request under a policy conductor just added cannot be judged
52
+ by that policy, so plan for a short, ordered sequence rather than one
53
+ command: init, a first pull request in advisory mode, merge, then go
54
+ required.
55
+
56
+ 1. **Init.** Install the gates. Each of them is a working tool on its own,
57
+ and none of them needs this one:
58
+
59
+ ```
60
+ npm install -g @vaultcompass/dep-guard @vaultcompass/vault-guard @vaultcompass/intent-guard
61
+ ```
62
+
63
+ The umbrella is optional. Install it when running the three separately
64
+ has become the annoying part:
65
+
66
+ ```
67
+ npm install -g @vaultcompass/conductor
68
+ ```
69
+
70
+ The two external gates are installed by you, on your machine and in your
71
+ workflow, from their own releases: [gitleaks](https://github.com/gitleaks/gitleaks)
72
+ 8.19 or later and [osv-scanner](https://github.com/google/osv-scanner)
73
+ 2.x. conductor never downloads either one. It finds them on `PATH`, and
74
+ when one is enabled in the policy and missing, the run reports
75
+ could-not-run (exit 2) with the install step in the report. Two policy
76
+ lines switch them on:
77
+
78
+ ```yaml
79
+ gates:
80
+ secrets-history:
81
+ product: gitleaks
82
+ vulnerabilities:
83
+ product: osv-scanner
84
+ ```
85
+
86
+ **Globally, and that is the guidance for CI too.** A devDependency is
87
+ fine beside it for your own pre-commit hook, and nothing about a local
88
+ run changed. It is not what gates your pull requests: on a pull-request
89
+ run the umbrella never looks in `node_modules/.bin` at all, because what
90
+ is installed there is chosen by the head's own manifest and lockfile. The
91
+ Action installs all four packages itself, globally, at versions pinned in
92
+ your workflow file. See "The pull-request trust boundary" and "The
93
+ Action" below.
94
+
95
+ From the repository root, look before you write:
96
+
97
+ ```
98
+ conductor init --dry-run
99
+ ```
100
+
101
+ That prints every file it would write or change and writes nothing. Then:
102
+
103
+ ```
104
+ conductor init
105
+ ```
106
+
107
+ which writes `.guardrails.yaml` with every gate listed and only the ones
108
+ it found switched on, and `.guardrails/manifest.json`, the record init
109
+ reads back on a later `--revert`. The intent gate is written unenforced
110
+ unless a frozen contract already exists at `.intent-guard/intent-contract.yaml`,
111
+ in which case init enforces it from the start rather than leaving a
112
+ frozen contract's protected paths reporting without blocking. **It writes
113
+ no pre-commit hook unless you ask for one:**
114
+
115
+ ```
116
+ conductor init --hook
117
+ ```
118
+
119
+ adds one pre-commit hook on top of that, running every enabled gate whose
120
+ stage is `commit`. A CI-only adopter that never runs conductor locally can
121
+ stop at the first `conductor init`, with no hook at all.
122
+
123
+ **`.git/hooks` is never part of a clone**, so a hook one checkout has does
124
+ not follow a teammate's clone, or a fresh clone of your own: hooks are per
125
+ clone and per machine. Each clone that wants the hook runs
126
+ `conductor init --hook` once; a repository that already has
127
+ `.guardrails.yaml` gets only the hook from that run, since init never
128
+ rewrites a policy file that already exists.
129
+
130
+ Do not wire this into a `package.json` `prepare` script. A failing init
131
+ (no `.git` in a Docker build, a foreign hook already installed, husky's
132
+ own `prepare` key, or conductor not yet installed at install time) would
133
+ fail `npm install` itself for everyone who runs it, not only for the
134
+ person who wanted the hook.
135
+
136
+ **`.guardrails/manifest.json` records the absolute path on the machine
137
+ that ran `init`**, for the hook, when there is one, and for the policy
138
+ file alike, and
139
+ conductor does not add a `.gitignore` entry for it. That path is specific
140
+ to your checkout, so do not commit the file: add
141
+ `.guardrails/manifest.json` to your own `.gitignore` today. The file
142
+ lives inside your working tree so `--revert` can find it later, and
143
+ recording repo-relative paths there instead of absolute ones is a known
144
+ gap, not a design; it has not been fixed yet.
145
+
146
+ Commit something, now that `--hook` above has installed the pre-commit
147
+ hook (this walkthrough's output below only appears when the hook is
148
+ installed; a bare `conductor init` with no `--hook` runs no gate on
149
+ commit at all). A clean commit prints one line:
150
+
151
+ ```
152
+ conductor: clean, nothing blocked. 2 gate(s) ran: dependencies (dep-guard), secrets (vault-guard). Deferred to a later stage: intent (intent-guard) from stage ci. 1 note(s). Re-run with --verbose for the full report.
153
+ ```
154
+
155
+ A commit with a staged credential in it prints the full report and exits 1:
156
+
157
+ ```
158
+ conductor 0.5.0
159
+ conductor run: 2 gate(s), 1 finding(s)
160
+
161
+ dependencies dep-guard 0.2.1 exit 0 251ms via dep-guard on path
162
+ threshold medium suppressed 0 ignored 0
163
+
164
+ secrets vault-guard 1.4.6 exit 1 97ms via vault-guard on path
165
+ BLOCKING critical vault-guard/anthropic jest.config.mjs:27:32
166
+ Possible secret of type 'anthropic'
167
+ threshold medium suppressed 0 ignored not reported
168
+
169
+ deferred intent intent-guard did not run here; it runs from stage ci onwards
170
+
171
+ verdict: exit 1, 1 blocking finding(s) across 2 gate(s).
172
+ ```
173
+
174
+ Both gates there are the ones you installed a moment ago, running with
175
+ their own thresholds and their own baselines. The umbrella found nothing
176
+ of its own, because it looks for nothing of its own.
177
+
178
+ Before opening anything, run `conductor run --verbose` on this same
179
+ checkout. That is the full report your policy will produce for the
180
+ dependency and secrets gates, with no `--trust-base` involved: a direct
181
+ run on your own checkout is already inside the trust boundary, so it
182
+ reads the policy you just wrote. **It is not the full preview for the
183
+ intent gate.** Locally, with no `--base`, the intent gate runs the way it
184
+ runs at a commit: intent-guard's own native flow, which wants an approved
185
+ contract and reports `BLOCKING critical intent-guard/gate-blocked` when
186
+ there is none. On a pull request a base ref resolves (conductor reads
187
+ `GITHUB_BASE_REF`, which GitHub sets for the whole job on a
188
+ `pull_request` event), and the umbrella instead prepares a contract for the
189
+ intent gate itself; with no contract to import, that path reports the
190
+ gate `skipped ... no contract` and never reaches the exit code. So a
191
+ first pull request with no contract yet is not blocked by the intent gate
192
+ on the pull request, whatever the local preview showed a moment before.
193
+ See "Intent at a pull request" below for the full mechanism.
194
+
195
+ 2. **Open the first pull request in advisory mode.** Add `.guardrails.yaml`
196
+ and the workflow together, with `advisory: true` and `pr-comment: true`
197
+ on the conductor step -- the recipe under "Running the gates as an
198
+ advisory check" below is a complete copy-paste job -- and leave the check
199
+ out of branch protection for this one pull request. The step still exits
200
+ 2 on this pull request even with `advisory: true`: the base branch has no
201
+ policy yet, so the run has no rules, and `advisory` never touches that
202
+ exit code, only a blocking finding's. Leaving the check out of branch
203
+ protection is what keeps that expected exit 2 from blocking the merge;
204
+ the step posts a comment saying so with the remedy on it, which is the
205
+ honest report of an unfinished adoption, not a broken tool.
206
+
207
+ 3. **Merge.** Every pull request after that is judged by the policy on the
208
+ base branch, and a change to that policy shows up as a proposal line and
209
+ takes effect after its own merge.
210
+
211
+ 4. **Go required.** Once a few ordinary pull requests have shown the report
212
+ reads the way you expect, remove `advisory: true` from the conductor step
213
+ and require the job's own check context in branch protection -- `gates`
214
+ in the recipes below, the job name, never the context the SARIF-upload
215
+ step reports under. That is the whole of turning this from an advisory
216
+ job into the one required check.
217
+
218
+ There is deliberately no mode in which the pull request's own policy file
219
+ decides the run, not even as a preview: step 1's preview gives you the same
220
+ report without putting a file the pull request controls behind a verdict on
221
+ the pull request page.
222
+
23
223
  ## Why
24
224
 
25
- Run all three and you have three inits, three config files, three output
26
- shapes, and three pre-commit hooks fighting over one file. That is the
225
+ Run all three family gates and you have three inits, three config files,
226
+ three output shapes, and three pre-commit hooks fighting over one file, and
227
+ a separate job for the two external scanners. That is the
27
228
  friction this repository removes, and that is all it removes:
28
229
 
29
230
  - **one policy file**, `.guardrails.yaml`, keyed by the role each gate
30
231
  fills rather than by the product filling it;
31
- - **one init**, which writes that file and a single pre-commit hook running
32
- every enabled gate whose stage is `commit`, which by default is every gate
33
- but the intent one;
232
+ - **one init**, which writes that file, and with `--hook` a single
233
+ pre-commit hook running every enabled gate whose stage is `commit`, which
234
+ by default is every gate but the intent one;
34
235
  - **one report**, as text for a terminal or as a single SARIF 2.1.0 log
35
236
  with one run per gate.
36
237
 
@@ -40,79 +241,10 @@ with ceremony rather than runtime named as the cost. A screenful of per-gate
40
241
  detail on a commit that found nothing is that cost, paid on every commit, and
41
242
  it is what makes a team switch a hook off.
42
243
 
43
- ## Quickstart
44
-
45
- Install the gates. Each of them is a working tool on its own, and none of
46
- them needs this one:
47
-
48
- ```
49
- npm install -g @vaultcompass/dep-guard @vaultcompass/vault-guard @vaultcompass/intent-guard
50
- ```
51
-
52
- The umbrella is optional. Install it when running the three separately has
53
- become the annoying part:
54
-
55
- ```
56
- npm install -g @vaultcompass/conductor
57
- ```
58
-
59
- **Globally, and that is the guidance for CI too.** A devDependency is fine
60
- beside it for your own pre-commit hook, and nothing about a local run changed.
61
- It is not what gates your pull requests: on a pull-request run the umbrella
62
- never looks in `node_modules/.bin` at all, because what is installed there is
63
- chosen by the head's own manifest and lockfile. The Action installs all four
64
- packages itself, globally, at versions pinned in your workflow file. See "The
65
- pull-request trust boundary" and "The Action" below.
66
-
67
- From the repository root, look before you write:
68
-
69
- ```
70
- conductor init --dry-run
71
- ```
72
-
73
- That prints every file it would write or change and writes nothing. Then:
74
-
75
- ```
76
- conductor init
77
- ```
78
-
79
- which writes `.guardrails.yaml` with every gate listed and only the ones it
80
- found switched on, plus one pre-commit hook running every enabled gate whose
81
- stage is `commit`.
82
-
83
- Commit something. A clean commit prints one line:
84
-
85
- ```
86
- conductor: clean, nothing blocked. 2 gate(s) ran: dependencies (dep-guard), secrets (vault-guard). Deferred to a later stage: intent (intent-guard) from stage ci. 1 note(s). Re-run with --verbose for the full report.
87
- ```
88
-
89
- A commit with a staged credential in it prints the full report and exits 1:
90
-
91
- ```
92
- conductor 0.4.6
93
- conductor run: 2 gate(s), 1 finding(s)
94
-
95
- dependencies dep-guard 0.2.1 exit 0 251ms via dep-guard on path
96
- threshold medium suppressed 0 ignored 0
97
-
98
- secrets vault-guard 1.4.6 exit 1 97ms via vault-guard on path
99
- BLOCKING critical vault-guard/anthropic jest.config.mjs:27:32
100
- Possible secret of type 'anthropic'
101
- threshold medium suppressed 0 ignored not reported
102
-
103
- deferred intent intent-guard did not run here; it runs from stage ci onwards
104
-
105
- verdict: exit 1, 1 blocking finding(s) across 2 gate(s).
106
- ```
107
-
108
- Both gates there are the ones you installed a moment ago, running with their
109
- own thresholds and their own baselines. The umbrella found nothing of its
110
- own, because it looks for nothing of its own.
111
-
112
244
  ## What it deliberately is not
113
245
 
114
- It is not a fourth gate. It finds no bugs of its own and scans nothing.
115
- Every finding about your code came from one of the three gates and is
246
+ It is not a sixth gate. It finds no bugs of its own and scans nothing.
247
+ Every finding about your code came from one of the five gates and is
116
248
  labelled with which one. The only findings it adds are about the gates
117
249
  themselves, and they are labelled `conductor`: a gate that is switched on
118
250
  and could not run, and a gate whose output it could not read. Those exist
@@ -122,8 +254,8 @@ whole family exists to prevent.
122
254
  It is not something you adopt before the gates are useful. Each gate keeps
123
255
  its own config file, its own baseline, its own thresholds, and its own exit
124
256
  codes. The umbrella never writes into any of them: it passes a policy to
125
- each gate as command-line flags, which every one of the three already
126
- treats as higher precedence than its own config. Delete this tool and every
257
+ each gate as command-line flags, which every one of them already treats as
258
+ higher precedence than its own config. Delete this tool and every
127
259
  gate still runs, with exactly the configuration it had, because nothing
128
260
  here ever touched it.
129
261
 
@@ -161,13 +293,26 @@ gates:
161
293
  enforce: false
162
294
  options:
163
295
  require-frozen: false
296
+ secrets-history:
297
+ product: gitleaks
298
+ enabled: true
299
+ stage: ci
300
+ enforce: true
301
+ vulnerabilities:
302
+ product: osv-scanner
303
+ enabled: true
304
+ stage: ci
305
+ enforce: true
164
306
 
165
307
  report:
166
308
  format: text
167
309
  ```
168
310
 
169
- **Gates are keyed by role**, not by product. `dependencies`, `secrets`,
170
- `intent`. The `product` field says which binary fills that role today.
311
+ **Gates are keyed by role**, not by product. `dependencies` (dep-guard),
312
+ `secrets` (vault-guard), `intent` (intent-guard), `secrets-history`
313
+ (gitleaks, scanning git history) and `vulnerabilities` (osv-scanner, over
314
+ the resolved dependency tree). The `product` field says which binary fills
315
+ that role today. The last two are external tools you install yourself.
171
316
 
172
317
  **`enabled`** defaults to true. A gate that is enabled and whose binary
173
318
  cannot be found is a blocking finding of the umbrella's own
@@ -176,7 +321,9 @@ cannot be found is a blocking finding of the umbrella's own
176
321
  **`stage`** says when a gate runs: `commit`, `push`, or `ci`. Stages are
177
322
  **cumulative** in that order, so a gate runs at its own stage and at every
178
323
  later one, and a run at `ci` runs everything that is enabled. The defaults
179
- are `commit` for `dependencies` and `secrets` and `ci` for `intent`.
324
+ are `commit` for `dependencies` and `secrets`, and `ci` for `intent`,
325
+ `secrets-history` and `vulnerabilities`: a history scan and a registry
326
+ lookup are pull-request work, not commit-time work.
180
327
 
181
328
  A gate held back by the stage filter is never silent. It is one line in the
182
329
  text report naming the stage it is waiting for, and a `conductor/gate-deferred`
@@ -190,7 +337,14 @@ enforced gate's do. The only thing it cannot do is change the exit code: its
190
337
  blocking findings do not raise it, and its failing to run at all does not
191
338
  make the run exit 2. That is the adoption ramp, so a gate can be switched on
192
339
  and read for a few weeks before it is allowed to refuse anybody's commit.
193
- `init` writes it out for every gate, and starts the intent gate at `false`.
340
+ `init` writes it out for every gate. For the intent gate it writes `true`
341
+ when a frozen contract already exists at init time
342
+ (`.intent-guard/intent-contract.yaml`, or the pre-1.3.0
343
+ `.conductor/intent-contract.yaml`), since the ramp is already climbed by
344
+ then, and leaving it unenforced would silently let a frozen contract's
345
+ protected paths produce findings that never fail the check. It writes
346
+ `false`, with a comment explaining why, when there is no contract yet to
347
+ enforce against.
194
348
 
195
349
  **`options`** is handed to that gate unchanged. Each key is one of that
196
350
  gate's own long flags with the leading dashes stripped: `fail-on: high`
@@ -198,10 +352,18 @@ becomes `--fail-on high`, `online: true` becomes `--online`,
198
352
  `require-frozen: false` becomes `--no-require-frozen`, and a list becomes
199
353
  one flag per entry. The handful of flags the umbrella supplies itself (the
200
354
  JSON format flag, `--staged`, and the intent gate's `--project`) are
201
- rejected if you also set them, rather than being silently overridden.
355
+ rejected if you also set them, rather than being silently overridden. For
356
+ the external gates the umbrella writes `--report-format`, `--report-path`,
357
+ `--exit-code`, `--log-opts`, `--config`, `--gitleaks-ignore-path`,
358
+ `--ignore-gitleaks-allow`, `--log-level`, `--redact` and `--no-banner` to
359
+ gitleaks, and
360
+ `--format`, `--config` and `--lockfile` to osv-scanner, so those are
361
+ reserved too. Narrow what either
362
+ tool reports in its own config file (`.gitleaks.toml`, `osv-scanner.toml`)
363
+ instead.
202
364
 
203
365
  **There is no shared severity threshold, on purpose.** One top-level
204
- `failOn` would read as one decision and mean three different things, so
366
+ `failOn` would read as one decision and mean five different things, so
205
367
  setting one is an error rather than a knob that half works. Each gate keeps
206
368
  its own threshold in its own `options` block, spelled the way that gate
207
369
  spells it.
@@ -213,21 +375,41 @@ that gate, for pointing at a build that is not installed anywhere.
213
375
 
214
376
  ## Commands
215
377
 
216
- `conductor init` writes the policy file and one pre-commit hook.
217
-
378
+ `conductor init` writes the policy file and `.guardrails/manifest.json`, the
379
+ record `--revert` reads back later. The manifest currently records absolute
380
+ machine paths rather than repo-relative ones (see "Adopting conductor"
381
+ above); do not commit it.
382
+
383
+ - `--hook` also writes one pre-commit hook running every enabled gate whose
384
+ stage is `commit`. Without it, init writes only the policy file and the
385
+ manifest: no hook, and none of the hook-manager detection below runs
386
+ either. `.git/hooks` is never part of a clone, so a hook one checkout has
387
+ does not follow a teammate's clone, or a fresh clone of your own; each
388
+ needs its own `conductor init --hook`. `--revert` still removes a hook a
389
+ previous `--hook` run left behind, whether or not this invocation passes
390
+ `--hook` itself.
218
391
  - `--dry-run` prints every file it would write or change and writes nothing.
219
392
  - `--revert` removes exactly what a previous init wrote, and nothing else.
220
393
  A file changed since init is reported and left alone.
221
394
  - `--adopt` replaces one gate's own pre-commit hook with the umbrella hook.
222
395
  Without it, init reports the collision and stops rather than stacking a
223
396
  second invocation of a gate that is already hooked. A hook the umbrella
224
- does not recognise is never replaced, with or without `--adopt`.
397
+ does not recognise is never replaced, with or without `--adopt`. Only
398
+ meaningful together with `--hook`; without it, init errors rather than
399
+ silently ignoring the flag, because there is no hook for it to act on.
225
400
  - `--force` acts on a file **conductor itself wrote** and that has changed
226
401
  since: on its own it replaces a managed hook somebody has edited, and with
227
402
  `--revert` it removes one, restoring an adopted hook if there was one. It
228
403
  never overrides a foreign-hook or gate-hook refusal, with or without
229
404
  `--adopt`: those hooks were never conductor's, and no flag here turns
230
- somebody else's file into one this tool may overwrite.
405
+ somebody else's file into one this tool may overwrite. Like `--adopt`,
406
+ only meaningful together with `--hook` on an init (not on a `--revert`);
407
+ without it, init errors.
408
+
409
+ The rest of this section, on hook managers already wired into the
410
+ repository, applies only when `--hook` is given: none of it is consulted,
411
+ and none of it can block the policy file from being written, on a plain
412
+ `conductor init`.
231
413
 
232
414
  Init recognises the hook manager already wired into the repository. husky is
233
415
  redirected to the tracked hook it maintains rather than the generated
@@ -281,6 +463,15 @@ proceeds normally without mentioning them.
281
463
  leaves out is named as excluded, on one line in the text report and as a
282
464
  `conductor/gate-excluded` notification in the SARIF log's `conductor` run.
283
465
  It never reaches the exit code.
466
+ - `--advisory` maps exit 1 to exit 0: a run whose only failure is a blocking
467
+ finding no longer fails. A gate that could not run is unaffected and still
468
+ exits 2, so a crashed install or a missing policy still shows red rather
469
+ than a silent green: this flag changes what a **finding** does, never what
470
+ a **broken gate** does. The report is unchanged, a blocking finding still
471
+ prints with its `BLOCKING` marker, and only the process exit and the
472
+ verdict line's own wording (it says findings were advisory and did not
473
+ block) change. Text output only; the SARIF log has no verdict line to
474
+ change and its `properties.blocking` on each result is unaffected.
284
475
 
285
476
  ### Exit codes
286
477
 
@@ -289,7 +480,34 @@ proceeds normally without mentioning them.
289
480
  - **2** an enabled gate could not run: its binary is missing, it exited with
290
481
  its own could-not-run code, or it exited 1 with nothing parseable on
291
482
  stdout, which is what a rejected config file looks like from two of the
292
- three.
483
+ three family gates.
484
+
485
+ The external gates' exits are read per tool. gitleaks exits 1 for an error
486
+ as well as for a leak, so the umbrella hands it `--exit-code 3`: 3 is a leak
487
+ (blocked), 1 is could-not-run. gitleaks also exits 0 with an empty report
488
+ when git itself fails (a base ref the checkout never fetched), so a clean
489
+ exit that logged an `ERR` line is could-not-run too, never a pass. A
490
+ gitleaks exit with no report file behind it is could-not-run. osv-scanner is
491
+ handed every tracked lockfile by name (`package-lock.json`,
492
+ `npm-shrinkwrap.json`, `pnpm-lock.yaml`, `yarn.lock`, `bun.lock`, at any
493
+ depth, never under `node_modules`); when the repository tracks none, it is
494
+ not spawned at all and the gate is reported clean with a
495
+ `conductor/nothing-to-scan` note, so a docs-only repository is not red on
496
+ every pull request. Its 1 is blocked. Its own 128 ("no package sources
497
+ found") on lockfiles it WAS handed means they parsed to no packages; that is
498
+ clean too, with a distinct `conductor/lockfiles-empty` note naming the
499
+ files. Only those npm-family names are handed over today: a repository
500
+ whose only lockfile belongs to another ecosystem gets nothing-to-scan from
501
+ this gate. Lockfiles inside git submodules are never listed. In a sparse
502
+ checkout a tracked lockfile that is not on disk is still handed over and
503
+ osv-scanner exits 127 on it, a false could-not-run that fails closed. Any other osv-scanner exit
504
+ (127 is its error code) is could-not-run. A gitleaks older than 8.19 or an
505
+ osv-scanner older than 2.0 is could-not-run, naming the floor.
506
+
507
+ `run --advisory` maps exit 1 to exit 0. It never touches exit 2: a gate that
508
+ could not run is a different failure from a blocking finding, and advisory
509
+ mode exists to leave that one alone. See "Running the gates as an advisory
510
+ check" below.
293
511
 
294
512
  ## The pull-request trust boundary
295
513
 
@@ -438,8 +656,66 @@ choose its own judge on exactly the repositories that have no rules yet. See
438
656
  "Adopting conductor" below for the sequence and for how to see what your
439
657
  policy will do before you merge it.
440
658
 
441
- **Which gates are covered.** All three: dep-guard from **0.6.0**,
442
- intent-guard from **1.4.0**, vault-guard from **1.7.0**.
659
+ **Which gates are covered.** All five: dep-guard from **0.6.0**,
660
+ intent-guard from **1.4.0**, vault-guard from **1.7.0**, and the two
661
+ external gates at their command-line floors, gitleaks **8.19.0** and
662
+ osv-scanner **2.0.0**.
663
+
664
+ **The external gates get their pull-request mode from the umbrella.**
665
+ Neither tool has a `--trust-base`, and both auto-load a config from the tree
666
+ they scan, which on a pull request is the head: a pull request could add an
667
+ allowlist entry for exactly the secret or advisory it introduces. So on a
668
+ pull-request run the umbrella reads `.gitleaks.toml` and `osv-scanner.toml`
669
+ from the base ref with `git show` and passes each tool that copy with
670
+ `--config`. When the base has none, the tool gets a neutral one (gitleaks'
671
+ built-in rules, an empty osv-scanner config) rather than nothing, because
672
+ nothing would let it find the head's file on its own. gitleaks'
673
+ `.gitleaksignore` is handled the same way, and because gitleaks also loads
674
+ the ignore file at the root of whatever it scans, the umbrella scans the
675
+ repository's git directory instead of the working tree on a pull request:
676
+ the same history, without the head's ignore file. A head-side change to any
677
+ of these files is reported as a proposal line and takes effect after merge,
678
+ exactly like a change to `.guardrails.yaml`. History is scoped to
679
+ `<base>..HEAD` on a pull request and to `HEAD` locally, so a secret on
680
+ another branch never reddens this one. Merge commits are scanned by their
681
+ first-parent diff, so a secret added inside a merge (while resolving a
682
+ conflict, say) is found; the same leak seen in a pull request's commit and
683
+ again in its merge is reported once, with the other commit listed.
684
+
685
+ A base `.gitleaks.toml` can name another file with `[extend] path`, which
686
+ gitleaks resolves against its working directory. On a pull request
687
+ conductor copies every file in that chain from the base ref into a
688
+ directory of its own and runs gitleaks from there, so the head's copy of an
689
+ extended file is never read; a head-side edit to one is a proposal, and an
690
+ extended file the base does not have makes the gate could-not-run, naming
691
+ it. gitleaks' log level is pinned at `info` and `log-level` is reserved,
692
+ because conductor reads gitleaks' error lines to tell a failed scan from a
693
+ clean one. Write the extend as a plain relative path in an `[extend]` table:
694
+ a base `.gitleaks.toml` whose extend target is a symbolic link, or which
695
+ writes the extend as an inline table or a quoted key, fails closed on every
696
+ pull request until it is rewritten that way.
697
+
698
+ **Local runs and `.gitattributes`.** On a pull request gitleaks scans the
699
+ repository's git directory, where the head's `.gitattributes` is not read.
700
+ A local run scans the working tree, so a file your own `.gitattributes`
701
+ marks `binary` is skipped by gitleaks there. Pull requests are not affected.
702
+
703
+ On a pull request gitleaks is also passed `--ignore-gitleaks-allow`, so an
704
+ inline `gitleaks:allow` comment does not hide a secret: an inline allow
705
+ lives in the tree being judged, so the pull request controls it. A
706
+ legitimate allow belongs in the base branch's `.gitleaks.toml` allowlist or
707
+ `.gitleaksignore`, both of which conductor already reads from the base.
708
+ Local runs keep inline allows.
709
+
710
+ osv-scanner is never pointed at a directory to walk, because its own walk
711
+ skips anything `.gitignore` matches, tracked or not, so one ignore line in a
712
+ pull request could hide a committed lockfile. conductor lists the tracked
713
+ lockfiles with `git ls-files` and hands each one over with `--lockfile`. On
714
+ a pull request that list comes from the head's index, not the base ref: the
715
+ lockfiles are the tree being judged, and adding or removing one is visible
716
+ in the diff. Only the root `osv-scanner.toml` is read from the base and
717
+ passed with `--config`, which overrides any nested one for the run; a
718
+ nested one the pull request adds or edits is reported as a proposal.
443
719
 
444
720
  The umbrella asks each gate its version and passes the flag only to a build
445
721
  that understands it, so an older gate is not handed a flag it would reject. A
@@ -459,7 +735,7 @@ the flag.
459
735
 
460
736
  ## Intent at a pull request
461
737
 
462
- The intent gate is the only one of the three with any ceremony: its native
738
+ The intent gate is the only one of the five with any ceremony: its native
463
739
  flow wants a contract approved before the work starts, which is a per-task
464
740
  human step. That step is exactly what a pull request cannot carry, so at the
465
741
  `ci` stage the umbrella stands in for it.
@@ -472,6 +748,20 @@ With no `--base`, `GITHUB_BASE_REF` is used as `origin/<value>` when it is
472
748
  set, and the text report says so. With neither, the intent gate runs the way
473
749
  it does at a commit: against the staged index, or the paths you name.
474
750
 
751
+ **This is why a local preview and a pull-request run can disagree about a
752
+ missing contract.** The contract-discovery rules below (`--spec`, a frozen
753
+ native contract, a `Spec:` line, the `docs/superpowers/specs` convention)
754
+ only engage once `--base` resolves to something, or `--spec` is given.
755
+ Neither is true of a plain `conductor run` on your own checkout, so a
756
+ repository with no contract gets intent-guard's own native answer instead:
757
+ `BLOCKING critical intent-guard/gate-blocked`, because that flow wants an
758
+ approved contract and none exists. On a pull request `--base` is set, this
759
+ whole section's machinery engages, and a branch with nothing to import
760
+ lands in the no-contract state below instead: reported, and never reaching
761
+ the exit code. Read a local `BLOCKING` line on the intent gate as "there is
762
+ no contract for the umbrella to import here yet," not as "this pull request
763
+ will fail."
764
+
475
765
  A git failure here is **fail-closed**: could-not-run, so exit 2 for an
476
766
  enforced gate and a note for an unenforced one. There is deliberately no
477
767
  fallback to an empty path set, because an empty path set is what a passing
@@ -530,6 +820,22 @@ skipped line, in the verdict and on the one-line summary of a clean run, so a
530
820
  reader can tell "nobody has written one" from "somebody decided against one"
531
821
  wherever they meet it.
532
822
 
823
+ **A repository with no contract yet is not a repository this gate can act
824
+ on**, and the no-contract skip line names `docs/superpowers/specs`, which is
825
+ a convention from this family's own tooling and not one an outside adopter
826
+ has reason to recognise. The next step, if you want this gate to have an
827
+ opinion here, is the one intent-guard's own documentation describes: draft a
828
+ contract naming the paths worth protecting, then freeze it, and keep the
829
+ frozen file committed so rule 2 above finds it on every pull request from
830
+ then on. Until you do that, a project rule that lives only in `AGENTS.md`
831
+ never blocks anything through this gate. intent-guard does read prose rules
832
+ files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, cursor rules) as constraint
833
+ sources, but by its own design a constraint from that source is advisory
834
+ and leaves the exit code alone; only a user-stated constraint, or one
835
+ promoted with `intent-guard correct --promote`, can block. Conductor itself
836
+ never opens that file. What is enforced is the frozen contract or the
837
+ imported spec, never project convention documented in prose.
838
+
533
839
  **A waiver is a decision, recorded by whoever wrote the pull request body,
534
840
  and that includes a contributor from a fork.** On the ordinary path, where a
535
841
  repository has no frozen contract of its own, `Spec: none` means the intent
@@ -654,14 +960,14 @@ jobs:
654
960
  contents: read
655
961
  security-events: write
656
962
  steps:
657
- - uses: actions/checkout@v4
963
+ - uses: actions/checkout@v7
658
964
  with:
659
965
  fetch-depth: 0
660
- - uses: actions/setup-node@v4
966
+ - uses: actions/setup-node@v7
661
967
  with:
662
968
  node-version: '22.11.0'
663
969
  - id: conductor
664
- uses: vaultcompasshq/conductor@v0.4.6
970
+ uses: vaultcompasshq/conductor@v0.5.0
665
971
  with:
666
972
  output: conductor.sarif
667
973
  - uses: github/codeql-action/upload-sarif@v3
@@ -688,7 +994,7 @@ jobs:
688
994
  contents: read
689
995
  security-events: write
690
996
  steps:
691
- - uses: actions/checkout@v4
997
+ - uses: actions/checkout@v7
692
998
  with:
693
999
  # Required, for two reasons now. Without it there is no merge base
694
1000
  # to diff against, and the intent gate fails closed rather than
@@ -697,7 +1003,7 @@ jobs:
697
1003
  # base ref that will not resolve is exit 2 for every enabled gate.
698
1004
  fetch-depth: 0
699
1005
  - uses: pnpm/action-setup@v4
700
- - uses: actions/setup-node@v4
1006
+ - uses: actions/setup-node@v7
701
1007
  with:
702
1008
  # Not a bare major: Node 22.0.0 ships npm 10.5.1, which the action
703
1009
  # refuses because that client reports a clean install as tampered
@@ -710,7 +1016,7 @@ jobs:
710
1016
  # pinned below.
711
1017
  - run: pnpm install --frozen-lockfile
712
1018
  - id: conductor
713
- uses: vaultcompasshq/conductor@v0.4.6
1019
+ uses: vaultcompasshq/conductor@v0.5.0
714
1020
  with:
715
1021
  output: conductor.sarif
716
1022
  # Exact versions, never a range and never "latest". These four
@@ -721,7 +1027,7 @@ jobs:
721
1027
  # request of their own. Forward only on a pull request: the action
722
1028
  # refuses a pin below what its tag ships, and the four lines can be
723
1029
  # left out entirely to take that tag's own versions.
724
- conductor-version: 0.4.6
1030
+ conductor-version: 0.5.0
725
1031
  dep-guard-version: 0.7.0
726
1032
  vault-guard-version: 1.8.0
727
1033
  intent-guard-version: 1.5.2
@@ -740,6 +1046,37 @@ jobs:
740
1046
  sarif_file: ${{ steps.conductor.outputs.sarif }}
741
1047
  ```
742
1048
 
1049
+ **The two external gates are installed by your workflow, not by the
1050
+ Action.** The Action still installs exactly its four npm packages and has no
1051
+ input for gitleaks or osv-scanner; conductor downloads, pins and checksums
1052
+ no third-party binary. If the policy enables `secrets-history` or
1053
+ `vulnerabilities`, add a step before the conductor step that puts both tools
1054
+ on `PATH`, pinned by version and checked against the release's own
1055
+ checksum, the same way you would for a standalone security job:
1056
+
1057
+ ```yaml
1058
+ - name: Install gitleaks and osv-scanner
1059
+ run: |
1060
+ set -euo pipefail
1061
+ bin="$RUNNER_TEMP/external-gates"
1062
+ mkdir -p "$bin"
1063
+ cd "$RUNNER_TEMP"
1064
+ curl -sSLO https://github.com/gitleaks/gitleaks/releases/download/v8.30.1/gitleaks_8.30.1_linux_x64.tar.gz
1065
+ echo "551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb gitleaks_8.30.1_linux_x64.tar.gz" | sha256sum -c -
1066
+ tar -xzf gitleaks_8.30.1_linux_x64.tar.gz -C "$bin" gitleaks
1067
+ curl -sSL -o "$bin/osv-scanner" https://github.com/google/osv-scanner/releases/download/v2.6.0/osv-scanner_linux_amd64
1068
+ echo "ca69b3d3cd08f889a49dc0a383122f71cc528b83803671df5fd874d97485b108 $bin/osv-scanner" | sha256sum -c -
1069
+ chmod +x "$bin/osv-scanner"
1070
+ echo "$bin" >> "$GITHUB_PATH"
1071
+ ```
1072
+
1073
+ `fetch-depth: 0` on the checkout matters more with gitleaks enabled: on a
1074
+ pull request conductor scans `<base>..HEAD`, and a base that was never
1075
+ fetched is a git error gitleaks itself would report as a clean scan of
1076
+ nothing. conductor reads that error off gitleaks' log and reports the gate
1077
+ as could-not-run instead. A missing tool is could-not-run as well, with the
1078
+ install step named in the report.
1079
+
743
1080
  The `@v4` pins there are readable, not safe: a tag moves, so pinning by one
744
1081
  runs whatever its author pushes to it next. Pin every third-party action by
745
1082
  commit digest in a workflow you actually run, the way this repository's own
@@ -747,15 +1084,22 @@ workflows do.
747
1084
 
748
1085
  ### Running the gates as an advisory check
749
1086
 
750
- To run the gates without blocking a merge, set `continue-on-error: true` on the
751
- `conductor` step and leave the check not required in branch protection. Set a
752
- step `timeout-minutes` as well. `continue-on-error` swallows a failing exit
753
- code, but it does not bound a step that hangs: on a required job a stuck run
754
- still drags the job to its own job-level limit and blocks the very merge the
755
- advisory setting was meant to leave alone. The Action already caps each gate's
756
- own subprocess at 120 seconds and reports a gate that exceeds it as
757
- could-not-run, so a step `timeout-minutes` is an outer bound around the whole
758
- run rather than the primary control.
1087
+ To run the gates without blocking a merge, set `advisory: true` on the
1088
+ `conductor` step and leave the check not required in branch protection.
1089
+ `advisory: true` maps a blocking finding to exit 0, so it never fails this
1090
+ run; a gate that **could not run** is unaffected and still exits 2, so a
1091
+ crashed install or a missing policy on the base ref still shows red rather
1092
+ than a silent green. That distinction is why the recipe below carries no
1093
+ `continue-on-error` anywhere: an earlier version of this recipe put
1094
+ `continue-on-error: true` on every step, including the umbrella's own, and a
1095
+ transient `npm audit signatures` failure then read as nothing wrong for two
1096
+ days (issue #36) because the step's exit code was swallowed regardless of
1097
+ which of the two reasons produced it. `advisory` fixes the failure that
1098
+ caused that; `continue-on-error` is the thing that let it happen, so the two
1099
+ do not belong in the same recipe. Set a step `timeout-minutes` as well: the
1100
+ Action already caps each gate's own subprocess at 120 seconds and reports one
1101
+ that exceeds it as could-not-run, so the timeout is an outer bound around the
1102
+ whole run rather than the primary control.
759
1103
 
760
1104
  A complete copy-paste job, rather than the one step above in isolation:
761
1105
 
@@ -770,65 +1114,69 @@ jobs:
770
1114
  contents: read
771
1115
  pull-requests: write
772
1116
  steps:
773
- - uses: actions/checkout@v4
774
- continue-on-error: true
1117
+ - uses: actions/checkout@v7
775
1118
  with:
776
1119
  fetch-depth: 0
777
- - uses: actions/setup-node@v4
778
- continue-on-error: true
1120
+ - uses: actions/setup-node@v7
779
1121
  with:
780
1122
  node-version: '22.11.0'
781
- - name: Fetch the base ref
782
- continue-on-error: true
783
- run: git fetch origin "$GITHUB_BASE_REF:refs/remotes/origin/$GITHUB_BASE_REF"
784
- env:
785
- GITHUB_BASE_REF: ${{ github.base_ref }}
786
1123
  - id: conductor
787
- continue-on-error: true
788
1124
  timeout-minutes: 5
789
- uses: vaultcompasshq/conductor@v0.4.6
1125
+ uses: vaultcompasshq/conductor@v0.5.0
790
1126
  with:
791
1127
  pr-comment: true
1128
+ advisory: true
792
1129
  ```
793
1130
 
794
- Every fallible step above, the checkout, the node setup, the explicit fetch,
795
- and the conductor step itself, carries `continue-on-error: true`, because a
796
- required job must never go red over an advisory step that hung or failed.
797
1131
  `action.yml` already shallow-fetches the trust base itself as of 0.4.5 when
798
1132
  the checkout does not already carry it (see the changelog entry for that
799
- version), so the explicit "Fetch the base ref" step above is belt and
800
- braces, not a requirement; it is here so the recipe still resolves the base
801
- ref on an action version that predates that self-fetch. `pr-comment: true`
802
- is what makes the advisory finding visible at all: a `pull_request` check
803
- that is not required posts nothing anywhere else a developer would look, so
804
- without it the run's only trace is a green-looking step nobody opens. See
805
- "The report as a pull request comment" below for what that input needs and
806
- what it does on a fork.
1133
+ version), so this recipe needs no separate "fetch the base ref" step. None of
1134
+ the three steps above swallows its own exit code: a checkout or setup-node
1135
+ failure is an infrastructure problem this recipe should still surface, and
1136
+ the `conductor` step's own advisory behaviour comes from `advisory: true`
1137
+ rather than from hiding a failing step, for the reason above. `pr-comment:
1138
+ true` is what makes the advisory finding visible at all: a `pull_request`
1139
+ check that is not required posts nothing anywhere else a developer would
1140
+ look, so without it the run's only trace is a step that exited 0 and nobody
1141
+ opens. See "The report as a pull request comment" below for what that input
1142
+ needs and what it does on a fork.
1143
+
1144
+ `advisory` changes the umbrella's own process exit code only: it does not
1145
+ reach the SARIF log, so a GitHub Code Scanning tab shows the same results and
1146
+ the same alerts either way, and Code Scanning's own merge protection can
1147
+ still block on them regardless of what this step's exit code says. `advisory`
1148
+ is also an input on the `conductor` step, which means it is read from the
1149
+ pull request's own workflow file on a same-repo `pull_request` event, the
1150
+ same as every other input this Action takes; that gives a pull request
1151
+ author nothing they could not already do by editing the workflow to add
1152
+ `continue-on-error` themselves, and the control for that, as for any workflow
1153
+ edit, is branch protection requiring review on `.github/workflows`, not
1154
+ anything in `action.yml`.
807
1155
 
808
1156
  ### Adopting conductor
809
1157
 
810
- The first pull request cannot be judged by the policy it adds. Plan for two
811
- steps rather than being surprised by one:
812
-
813
- 1. On a branch, run `conductor init`, then run `conductor run --verbose` on
814
- your own checkout. That is the full report your policy will produce, with
815
- no `--trust-base` involved: a direct run on your own checkout is already
816
- inside the trust boundary, so it reads the policy you just wrote. This is
817
- where you tune thresholds, not on a pull request.
818
- 2. Open the pull request with `.guardrails.yaml` and the workflow together,
819
- and set `continue-on-error: true` on the conductor step for it. The step
820
- is inert on this pull request: the base branch has no policy yet, so the
821
- run has no rules, exits 2, and posts a comment saying so with the remedy
822
- on it. That is the honest report of an unfinished adoption, not a broken
823
- tool.
824
- 3. Merge. Every pull request after that is judged by the policy on the base
825
- branch, and a change to that policy shows up as a proposal line and takes
826
- effect after its own merge.
827
-
828
- There is deliberately no mode in which the pull request's own policy file
829
- decides the run, not even as a preview: the preview in step 1 gives you the
830
- same report without putting a file the pull request controls behind a
831
- verdict on the pull request page.
1158
+ See "Adopting conductor" near the top of this README for the ordered
1159
+ walkthrough: init, a first pull request in advisory mode, merge, then go
1160
+ required. This subsection is the mechanism behind two of those steps.
1161
+
1162
+ **Why the first pull request still exits 2 under `advisory: true`.**
1163
+ `advisory: true` maps a blocking **finding** to exit 0; it has no opinion
1164
+ about a run that never had a policy to be judged by. The pull request that
1165
+ first adds `.guardrails.yaml` is judged against the base branch, which has
1166
+ none yet, so the run is refused outright before any gate produces a finding
1167
+ for `advisory` to act on. Leaving the check out of branch protection for
1168
+ that one pull request is what keeps the expected exit 2 from blocking the
1169
+ merge; the step posts a comment naming the ref and the remedy.
1170
+
1171
+ **Why "go required" means the job's own context, never the SARIF-upload
1172
+ row.** The recipes above upload conductor's SARIF log with
1173
+ `github/codeql-action/upload-sarif`, which can add its own code-scanning
1174
+ check to a pull request's checks list alongside the workflow job's own
1175
+ check. Branch protection's required-checks picker can then show both. Only
1176
+ the job's own context (`gates` in the recipes above, the job key, not any
1177
+ step name) carries conductor's actual exit code; a code-scanning check can
1178
+ read green from an old scan, or from `continue-on-error` on the upload step
1179
+ itself, independent of whether the gates step passed. Require the job.
832
1180
 
833
1181
  ### The report as a pull request comment
834
1182
 
@@ -846,7 +1194,7 @@ step and add `pull-requests: write` to the job's `permissions`:
846
1194
  steps:
847
1195
  # ... checkout, pnpm, setup-node, install, as in the example above ...
848
1196
  - id: conductor
849
- uses: vaultcompasshq/conductor@v0.4.6
1197
+ uses: vaultcompasshq/conductor@v0.5.0
850
1198
  with:
851
1199
  output: conductor.sarif
852
1200
  pr-comment: true
@@ -898,12 +1246,12 @@ per pull request.
898
1246
 
899
1247
  ```yaml
900
1248
  - id: conductor-package-a
901
- uses: vaultcompasshq/conductor@v0.4.6
1249
+ uses: vaultcompasshq/conductor@v0.5.0
902
1250
  with:
903
1251
  pr-comment: true
904
1252
  pr-comment-marker: 'package-a'
905
1253
  - id: conductor-package-b
906
- uses: vaultcompasshq/conductor@v0.4.6
1254
+ uses: vaultcompasshq/conductor@v0.5.0
907
1255
  with:
908
1256
  pr-comment: true
909
1257
  pr-comment-marker: 'package-b'
@@ -976,13 +1324,17 @@ came from, so a pull request that plants one gets a clean comment beside a
976
1324
  SARIF log that refused it.
977
1325
 
978
1326
  **Mirror whatever you gave the Action**, or the two runs can report different
979
- contracts. The step above matches the example, which passes neither
980
- `base-ref`, `trust-base` nor `spec`, so both runs read `GITHUB_BASE_REF` and
981
- the `Spec:` line out of the job environment themselves and land on the same
982
- contract and the same ref. If you set any of those inputs on the gates step,
983
- pass the same values here as `--base`, `--trust-base` and `--spec`; if you do
984
- not, the comment is a report of a contract source, or of a boundary, the
985
- uploaded log never used.
1327
+ contracts, or different verdicts. The step above matches the example, which
1328
+ passes neither `base-ref`, `trust-base`, `spec` nor `advisory`, so both runs
1329
+ read `GITHUB_BASE_REF` and the `Spec:` line out of the job environment
1330
+ themselves and land on the same contract and the same ref, and neither one
1331
+ maps a blocking finding to exit 0. If you set any of those inputs on the
1332
+ gates step, pass the same values here: `--base`, `--trust-base` and `--spec`
1333
+ for the first three, and `--advisory` if you set `advisory: true`. Missing
1334
+ one of the first three means the comment is a report of a contract source,
1335
+ or of a boundary, the uploaded log never used; missing `--advisory` means the
1336
+ comment's own verdict line reads "exit 1" underneath a gates step that just
1337
+ exited 0, which is confusing in the opposite direction from silence.
986
1338
 
987
1339
  **On a pull request from a fork the token is read-only**, so `gh pr comment`
988
1340
  fails, `continue-on-error` swallows the failure, and no comment appears on
@@ -1002,12 +1354,16 @@ In: the policy file and its schema, `init` with dry-run, revert, and adopt,
1002
1354
  `run` producing the combined text report and a combined SARIF log, the
1003
1355
  composed exit code, per-gate `stage` and `enforce`, `run --stage`, the intent
1004
1356
  gate at a pull request (`--base`, `--spec`, the imported contract, the
1005
- no-contract advisory), and the composite Action.
1357
+ no-contract advisory), the two external gates (gitleaks over git history and
1358
+ osv-scanner over the dependency tree, run from `PATH`, their config read
1359
+ from the base ref on a pull request), and the composite Action.
1006
1360
 
1007
1361
  Out, deliberately: a unified baseline or ledger (each gate keeps its own, and
1008
1362
  their fingerprints are not equally durable, so one shared file would expire
1009
1363
  entries silently for one product and not another), an MCP registration,
1010
- running the gates concurrently, and any finding of the umbrella's own about
1364
+ running the gates concurrently, downloading or pinning any third-party
1365
+ binary (the adopter installs gitleaks and osv-scanner), and any finding of
1366
+ the umbrella's own about
1011
1367
  anybody's CODE. The findings it does raise are all about the gates
1012
1368
  themselves: `conductor/gate-missing`, `conductor/gate-output-unparseable`
1013
1369
  and `conductor/gate-failed`, plus the two diagnostics
@@ -1020,7 +1376,8 @@ runs inside an agent session or on save, which intent-guard's own optional
1020
1376
  session hooks already cover.
1021
1377
 
1022
1378
  This is a young tool rather than a finished one. The gates are still the
1023
- product; this is the convenience layer over them.
1379
+ product, two of them are not this family's, and this is the layer that
1380
+ makes them one required check.
1024
1381
 
1025
1382
  ## Design notes
1026
1383
 
@@ -1037,4 +1394,4 @@ Adopter feedback is a row in [FINDINGS.md](FINDINGS.md). How to change this repo
1037
1394
 
1038
1395
  ## License
1039
1396
 
1040
- MIT, [Vault & Compass](https://vaultcompass.io)
1397
+ MIT. Built by [Vault & Compass](https://vaultcompass.io).