@vaultcompass/conductor 0.16.0 → 0.17.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
@@ -76,7 +76,7 @@ jobs:
76
76
  echo "ca69b3d3cd08f889a49dc0a383122f71cc528b83803671df5fd874d97485b108 $bin/osv-scanner" | sha256sum -c -
77
77
  chmod +x "$bin/osv-scanner"
78
78
  echo "$bin" >> "$GITHUB_PATH"
79
- - uses: vaultcompasshq/conductor@257830bd4b94a81419189b641508f1dda0950d00 # v0.15.0
79
+ - uses: vaultcompasshq/conductor@be3f33defcca091c403af6d2dc6e377ef5b94af7 # v0.16.0
80
80
  - uses: github/codeql-action/upload-sarif@v4
81
81
  if: always()
82
82
  with:
@@ -229,7 +229,7 @@ required.
229
229
 
230
230
  Your terminal also shows one status line per gate, written to stderr so a
231
231
  CI job log has a per-gate record even when the report goes to a file,
232
- such as `conductor: gate dependencies (dep-guard 0.18.0): ok, exit 0` or
232
+ such as `conductor: gate dependencies (dep-guard 0.18.1): ok, exit 0` or
233
233
  a `skipped (deferred to stage ci)` line for a deferred gate. They carry
234
234
  nothing the summary does not; to see only the summary, redirect stderr
235
235
  (`conductor run --staged --stage commit 2>/dev/null` in the hook).
@@ -237,15 +237,15 @@ required.
237
237
  A commit with a staged credential in it prints the full report and exits 1:
238
238
 
239
239
  ```
240
- conductor 0.16.0
240
+ conductor 0.17.0
241
241
  verdict-token: blocked (1)
242
242
  conductor run: 2 gate(s), 1 finding(s)
243
243
 
244
- dependencies dep-guard 0.18.0 exit 0 153ms via dep-guard on path
244
+ dependencies dep-guard 0.18.1 exit 0 153ms via dep-guard on path
245
245
  threshold medium suppressed 0 ignored 0
246
246
  mode staged corpusBuiltAt 2026-09-20T06:16:40.340Z lockfileFormat npm online false lookups 0 skipped-by-deadline 0
247
247
 
248
- secrets vault-guard 1.13.0 exit 1 105ms via vault-guard on path
248
+ secrets vault-guard 1.13.1 exit 1 105ms via vault-guard on path
249
249
  BLOCKING critical vault-guard/anthropic jest.config.mjs:14:12
250
250
  Possible secret of type 'anthropic'
251
251
  threshold medium suppressed 0 ignored not reported
@@ -532,8 +532,8 @@ request being judged, and the version-pin protection described above
532
532
  "protects nothing" against a tree that controls its own judge (the
533
533
  validate step's own comment in `action.yml` says so in those words). A tag
534
534
  moves when someone pushes it. Name this action by owner and the full commit
535
- SHA instead. The recipes in this README name v0.15.0 that way, as
536
- `vaultcompasshq/conductor@257830bd4b94a81419189b641508f1dda0950d00 # v0.15.0`.
535
+ SHA instead. The recipes in this README name v0.16.0 that way, as
536
+ `vaultcompasshq/conductor@be3f33defcca091c403af6d2dc6e377ef5b94af7 # v0.16.0`.
537
537
 
538
538
  ```yaml
539
539
  name: guardrails
@@ -555,10 +555,10 @@ jobs:
555
555
  with:
556
556
  node-version: '22.23.4'
557
557
  - id: conductor
558
- uses: vaultcompasshq/conductor@257830bd4b94a81419189b641508f1dda0950d00 # v0.15.0
558
+ uses: vaultcompasshq/conductor@be3f33defcca091c403af6d2dc6e377ef5b94af7 # v0.16.0
559
559
  with:
560
560
  output: conductor.sarif
561
- - uses: github/codeql-action/upload-sarif@v3
561
+ - uses: github/codeql-action/upload-sarif@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
562
562
  if: always()
563
563
  continue-on-error: true
564
564
  with:
@@ -654,7 +654,7 @@ jobs:
654
654
  # installs those itself, globally. Leave conductor-version unset so the
655
655
  # umbrella is the default in the pinned action.yml.
656
656
  - id: conductor
657
- uses: vaultcompasshq/conductor@257830bd4b94a81419189b641508f1dda0950d00 # v0.15.0
657
+ uses: vaultcompasshq/conductor@be3f33defcca091c403af6d2dc6e377ef5b94af7 # v0.16.0
658
658
  with:
659
659
  output: conductor.sarif
660
660
  # Exact versions, never a range and never "latest". These three
@@ -665,10 +665,10 @@ jobs:
665
665
  # request of their own. On a pull request the action refuses a pin
666
666
  # below what the pinned action.yml ships, and the three lines can
667
667
  # be left out entirely to take that action's own versions.
668
- dep-guard-version: 0.18.0
669
- vault-guard-version: 1.13.0
670
- intent-guard-version: 1.10.3
671
- - uses: github/codeql-action/upload-sarif@v3
668
+ dep-guard-version: 0.18.1
669
+ vault-guard-version: 1.13.1
670
+ intent-guard-version: 1.10.4
671
+ - uses: github/codeql-action/upload-sarif@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
672
672
  # Always: the log is most worth having on the run that failed.
673
673
  if: always()
674
674
  # The sarif path is published BEFORE the gates run, so on the exit 2
@@ -876,7 +876,7 @@ jobs:
876
876
  # seconds) plus 300 seconds for the preview, rounded up. A step
877
877
  # timeout below that can kill a full gitleaks scan and leave no verdict.
878
878
  timeout-minutes: 30
879
- uses: vaultcompasshq/conductor@257830bd4b94a81419189b641508f1dda0950d00 # v0.15.0
879
+ uses: vaultcompasshq/conductor@be3f33defcca091c403af6d2dc6e377ef5b94af7 # v0.16.0
880
880
  with:
881
881
  pr-comment: true
882
882
  advisory: true
@@ -1012,7 +1012,7 @@ step and add `pull-requests: write` to the job's `permissions`:
1012
1012
  # the pull request runs before the action in this job: no install, build
1013
1013
  # or test step here; those belong in a separate job. ...
1014
1014
  - id: conductor
1015
- uses: vaultcompasshq/conductor@257830bd4b94a81419189b641508f1dda0950d00 # v0.15.0
1015
+ uses: vaultcompasshq/conductor@be3f33defcca091c403af6d2dc6e377ef5b94af7 # v0.16.0
1016
1016
  with:
1017
1017
  output: conductor.sarif
1018
1018
  pr-comment: true
@@ -1091,12 +1091,12 @@ per pull request.
1091
1091
 
1092
1092
  ```yaml
1093
1093
  - id: conductor-package-a
1094
- uses: vaultcompasshq/conductor@257830bd4b94a81419189b641508f1dda0950d00 # v0.15.0
1094
+ uses: vaultcompasshq/conductor@be3f33defcca091c403af6d2dc6e377ef5b94af7 # v0.16.0
1095
1095
  with:
1096
1096
  pr-comment: true
1097
1097
  pr-comment-marker: 'package-a'
1098
1098
  - id: conductor-package-b
1099
- uses: vaultcompasshq/conductor@257830bd4b94a81419189b641508f1dda0950d00 # v0.15.0
1099
+ uses: vaultcompasshq/conductor@be3f33defcca091c403af6d2dc6e377ef5b94af7 # v0.16.0
1100
1100
  with:
1101
1101
  pr-comment: true
1102
1102
  pr-comment-marker: 'package-b'
@@ -31,7 +31,7 @@ import { ExternalConfigError, materializeExternalConfig, nestedConfigProposals,
31
31
  import { osvLockfileKind, profileFor } from './products.js';
32
32
  import { unreadManifestsNote } from './unread-manifests.js';
33
33
  import { escapeNonAscii } from './policy-diff.js';
34
- import { atLeastVersion, refuseHeadControlledArgument, refuseHeadControlledData, refuseHeadControlledProgram, } from './trust-base.js';
34
+ import { atLeastVersion, refuseHeadControlledArgument, refuseHeadControlledData, refuseHeadControlledProgram, writtenInsideWorkingTree, } from './trust-base.js';
35
35
  import { ResolveError, argumentCandidates, candidateNames, codeArguments, nodeModulesCandidate, resolveGateBinary, } from './resolve.js';
36
36
  /** The longest excerpt of a gate's own reason that is carried. */
37
37
  export const GATE_SAID_MAX_CHARS = 160;
@@ -675,8 +675,9 @@ export function refuseHeadControlledBinary(repoRoot, trustBase, binary) {
675
675
  return refusal;
676
676
  }
677
677
  }
678
+ const fromOptions = new Set(binary.optionArgumentPaths ?? []);
678
679
  for (const argument of binary.argumentPaths) {
679
- const refusal = refuseHeadControlledArgument(repoRoot, trustBase, argument);
680
+ const refusal = refuseHeadControlledArgument(repoRoot, trustBase, argument, fromOptions.has(argument) ? "the gate's options:" : "the gate's args:");
680
681
  if (refusal !== null) {
681
682
  return refusal;
682
683
  }
@@ -770,7 +771,7 @@ changeBase,
770
771
  * after its enables, so the appended flag wins.
771
772
  */
772
773
  preview = false) {
773
- const passthrough = renderOptionFlags(gate.options);
774
+ const passthrough = renderOptionFlags(gate.options, gate.product);
774
775
  const trust = trustBase === undefined ? [] : ['--trust-base', trustBase];
775
776
  const config = external.configPath === undefined ? [] : ['--config', external.configPath];
776
777
  switch (gate.product) {
@@ -946,7 +947,7 @@ preview = false) {
946
947
  ...lockfiles,
947
948
  ...(noResolve ? ['--no-resolve'] : []),
948
949
  ...callAnalysis,
949
- ...renderOptionFlags(options),
950
+ ...renderOptionFlags(options, gate.product),
950
951
  ...(preview ? ['--no-call-analysis=all'] : []),
951
952
  ];
952
953
  }
@@ -1304,7 +1305,11 @@ function previewRefusal(gate, repoRoot) {
1304
1305
  detail: "the preview does not run call analysis, because it would build the head's code",
1305
1306
  };
1306
1307
  }
1307
- if (gate.command !== undefined && realPathInside(repoRoot, gate.command)) {
1308
+ // Inside by its real path OR as written: a directory on the written path
1309
+ // that is a link out of the tree is the head's choice too (audit
1310
+ // 2026-11-01, MB2), and the primary rule judges every path as written.
1311
+ if (gate.command !== undefined &&
1312
+ (realPathInside(repoRoot, gate.command) || writtenInsideWorkingTree(repoRoot, gate.command))) {
1308
1313
  return {
1309
1314
  reason: 'gate-program-refused',
1310
1315
  detail: `preview under the proposed rules: the base command ${gate.command} is inside the working tree, so this gate was not run`,
@@ -1327,7 +1332,9 @@ function previewRefusal(gate, repoRoot) {
1327
1332
  // on every preview spawn, an option-value directory included (review B1).
1328
1333
  for (const arg of codeArguments(gate)) {
1329
1334
  const candidates = argumentCandidates(arg, repoRoot);
1330
- if (candidates.some((named) => realPathInside(repoRoot, named) || realPathInside(repoRoot, path.dirname(named)))) {
1335
+ if (candidates.some((named) => realPathInside(repoRoot, named) ||
1336
+ realPathInside(repoRoot, path.dirname(named)) ||
1337
+ writtenInsideWorkingTree(repoRoot, named))) {
1331
1338
  return {
1332
1339
  reason: 'gate-program-refused',
1333
1340
  detail: `preview under the proposed rules: the base args entry ${arg} names a path inside the working tree, so this gate was not run`,
package/dist/normalize.js CHANGED
@@ -533,8 +533,15 @@ function readTrustBase(raw, product) {
533
533
  export function normalizeIntentGuard(raw, version) {
534
534
  const product = 'intent-guard';
535
535
  const root = needRecord(raw, product, 'the output');
536
- if (root.status !== 'blocked' && root.status !== 'ok') {
537
- fail(product, 'status', 'either "ok" or "blocked"');
536
+ // "skipped" is accepted ahead of the gate using it (issue 103): intent-guard
537
+ // 1.10.4 says "nothing was checked" as status ok plus skipReason, because
538
+ // anything else would have been unparseable to every conductor up to this
539
+ // one, and a later release can move to a status of its own once its pin
540
+ // floor is above this version. It is the one value added; every other
541
+ // status is still refused, and readSkipReason refuses a skipped status
542
+ // that names no reason or that carries a finding.
543
+ if (root.status !== 'blocked' && root.status !== 'ok' && root.status !== 'skipped') {
544
+ fail(product, 'status', 'one of "ok", "blocked" or "skipped"');
538
545
  }
539
546
  const trustBase = readTrustBase(root.trustBase, product);
540
547
  const warnings = readIntentWarnings(root.warnings);
@@ -678,6 +685,7 @@ export function normalizeIntentGuard(raw, version) {
678
685
  : 'The intent gate blocked without stating a reason.', 'unattributed'));
679
686
  }
680
687
  }
688
+ const skipReason = readSkipReason(root, findings, product);
681
689
  return {
682
690
  findings,
683
691
  ...(trustBase === undefined ? {} : { trustBase }),
@@ -700,11 +708,43 @@ export function normalizeIntentGuard(raw, version) {
700
708
  driftCategories: drift?.categories ?? null,
701
709
  budgetAction: budget?.action ?? null,
702
710
  reasons,
711
+ // Present only when the gate said it checked nothing. The report
712
+ // surfaces read it through intentCheckedNothing in output-text.ts.
713
+ ...(skipReason === null ? {} : { skipReason }),
703
714
  },
704
715
  },
705
716
  diagnostics: [],
706
717
  };
707
718
  }
719
+ /**
720
+ * The gate's own statement that it checked nothing, or null (issue 103).
721
+ *
722
+ * intent-guard 1.10.4 puts a top-level `skipReason` string on a result whose
723
+ * status is still "ok" when require-frozen is off and there is no contract;
724
+ * a future status "skipped" means the same. Read only on those two
725
+ * statuses: a blocked result stays blocked whatever else it says, which is
726
+ * the fail-closed reading of a contradiction. An empty string is no reason.
727
+ *
728
+ * Refused as unparseable, never guessed at: a skipReason that is not a
729
+ * string, a status "skipped" that names no reason, and a skip that carries
730
+ * any finding. "Nothing was checked" beside a finding is a contradiction,
731
+ * and reading it as a skip would hide the finding, so the gate is reported
732
+ * as one whose output could not be read.
733
+ */
734
+ function readSkipReason(root, findings, product) {
735
+ if (root.status === 'blocked') {
736
+ return null;
737
+ }
738
+ const said = optionalString(root.skipReason ?? undefined, product, 'skipReason');
739
+ const reason = said === undefined || said === '' ? null : said;
740
+ if (root.status === 'skipped' && reason === null) {
741
+ fail(product, 'skipReason', 'a non-empty string when status is "skipped"');
742
+ }
743
+ if (reason !== null && findings.length > 0) {
744
+ fail(product, 'findings', 'empty when the gate says it checked nothing (skipReason)');
745
+ }
746
+ return reason;
747
+ }
708
748
  // -- gitleaks (external, git history mode) -------------------------------
709
749
  //
710
750
  // The report is a JSON array written to a file, one entry per leak, with
@@ -121,7 +121,7 @@ import { gateExitBlocks } from './exit-codes.js';
121
121
  import { cleanPreviewLine } from './gate-runner.js';
122
122
  import { NATIVE_CONTRACT_PATH, isLegacyContractPath } from './intent-prepare.js';
123
123
  import { INTENT_WARNING } from './normalize.js';
124
- import { gateOutcomeWords, skewFound, skewPlace } from './output-text.js';
124
+ import { gateOutcomeWords, intentCheckedNothing, intentSkipReason, skewFound, skewPlace, } from './output-text.js';
125
125
  import { POLICY_FILE_NAME } from './policy.js';
126
126
  import { policyChangeLine } from './policy-diff.js';
127
127
  import { guardPreview } from './run.js';
@@ -587,6 +587,27 @@ function treeUnchangedNotifications(result) {
587
587
  * keep answering it the same way.
588
588
  */
589
589
  function skippedNotifications(result) {
590
+ return [...preparedSkipNotifications(result), ...ranAndCheckedNothingNotifications(result)];
591
+ }
592
+ /**
593
+ * An intent gate that RAN and checked nothing (issue 103): intent-guard
594
+ * 1.10.4's skipReason on a directly spawned run, or, before it, no contract
595
+ * found with require-frozen off. Filed under the same id as the
596
+ * pull-request path's no-contract skip, with the same message shape and the
597
+ * gate's own sentence as the detail, because it is the same state and a
598
+ * consumer filtering on intent-guard/no-contract should see both. The same
599
+ * predicate the text report reads (intentCheckedNothing), so the two agree.
600
+ * The gate's own run is still in the log, since it did run.
601
+ */
602
+ function ranAndCheckedNothingNotifications(result) {
603
+ return result.gates.filter(intentCheckedNothing).map((gate) => ({
604
+ id: `${gate.product}/no-contract`,
605
+ message: `The ${gate.role} gate (${gate.product}) checked nothing on this branch. ` +
606
+ (intentSkipReason(gate) ?? 'It found no contract to check against.'),
607
+ details: { role: gate.role, product: gate.product, reason: 'no-contract' },
608
+ }));
609
+ }
610
+ function preparedSkipNotifications(result) {
590
611
  return result.skipped.map((gate) => ({
591
612
  // The reason IS the second half of the id, which keeps
592
613
  // intent-guard/no-contract exactly where consumers already have it and
@@ -177,6 +177,21 @@ export declare function versionSkewSummaryLines(result: RunResult): string[];
177
177
  * not a pass.
178
178
  */
179
179
  export declare function verdictToken(result: RunResult, advisory: boolean): string;
180
+ /**
181
+ * The gate's own skipReason (intent-guard 1.10.4, issue 103), or null. Put
182
+ * in the run details by normalizeIntentGuard only when non-empty.
183
+ */
184
+ export declare function intentSkipReason(gate: GateOutcome): string | null;
185
+ /**
186
+ * An intent gate that RAN and checked nothing: it said so with skipReason,
187
+ * or (before 1.10.4) it reported no contract found. The one predicate the
188
+ * text report, its one-line summary and the SARIF notification all read, so
189
+ * a directly spawned run reports this state on the same surfaces as the
190
+ * pull-request path's no-contract skip (issue 103). Never for a gate that
191
+ * could not run or that blocked: a missing contract under require-frozen is
192
+ * a block, not a skip.
193
+ */
194
+ export declare function intentCheckedNothing(gate: GateOutcome): boolean;
180
195
  export interface TextOptions {
181
196
  /**
182
197
  * Print the full report even when the run is fully clean.
@@ -404,14 +404,23 @@ function gateSection(gate, verbose, refusedOnTerminal = false) {
404
404
  const facts = Object.entries(gate.run.details)
405
405
  .filter(([key, value]) =>
406
406
  // ignoredReported drives the line above rather than being a fact
407
- // about the run, so it is not printed twice.
407
+ // about the run, so it is not printed twice. skipReason gets its
408
+ // own line, below.
408
409
  key !== 'ignoredReported' &&
410
+ key !== 'skipReason' &&
409
411
  (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') &&
410
412
  value !== '')
411
413
  .map(([key, value]) => `${key} ${String(value)}`);
412
414
  if (facts.length > 0) {
413
415
  lines.push(` ${facts.join(' ')}`);
414
416
  }
417
+ // The gate's own sentence for having checked nothing (issue 103), in the
418
+ // words the pull-request path's skipped line uses for the same state.
419
+ // The gate wrote it, so it is cleaned like any other gate text.
420
+ const skipReason = intentSkipReason(gate);
421
+ if (skipReason !== null && intentCheckedNothing(gate)) {
422
+ lines.push(` ${skipWording('no-contract').line}: ${cleanOutputLine(skipReason)}`);
423
+ }
415
424
  for (const diagnostic of gate.run.diagnostics) {
416
425
  lines.push(` note ${diagnostic.code}: ${diagnostic.message}`);
417
426
  }
@@ -1030,7 +1039,30 @@ function gateCheckedNothing(gate) {
1030
1039
  }
1031
1040
  return (gate.diagnostics.some((d) => d.code === 'conductor/nothing-to-scan') ||
1032
1041
  readNoPackages(gate) ||
1033
- (gate.role === 'intent' && gate.run.details.contractFound === false));
1042
+ intentCheckedNothing(gate));
1043
+ }
1044
+ /**
1045
+ * The gate's own skipReason (intent-guard 1.10.4, issue 103), or null. Put
1046
+ * in the run details by normalizeIntentGuard only when non-empty.
1047
+ */
1048
+ export function intentSkipReason(gate) {
1049
+ const said = gate.run.details.skipReason;
1050
+ return typeof said === 'string' && said !== '' ? said : null;
1051
+ }
1052
+ /**
1053
+ * An intent gate that RAN and checked nothing: it said so with skipReason,
1054
+ * or (before 1.10.4) it reported no contract found. The one predicate the
1055
+ * text report, its one-line summary and the SARIF notification all read, so
1056
+ * a directly spawned run reports this state on the same surfaces as the
1057
+ * pull-request path's no-contract skip (issue 103). Never for a gate that
1058
+ * could not run or that blocked: a missing contract under require-frozen is
1059
+ * a block, not a skip.
1060
+ */
1061
+ export function intentCheckedNothing(gate) {
1062
+ return (gate.role === 'intent' &&
1063
+ gate.couldNotRun === null &&
1064
+ !gate.findings.some((finding) => finding.blocking) &&
1065
+ (intentSkipReason(gate) !== null || gate.run.details.contractFound === false));
1034
1066
  }
1035
1067
  /** How the verdict sentence names a gate that ran and checked nothing. */
1036
1068
  function checkedNothingWording(gate) {
@@ -1364,7 +1396,16 @@ function summaryLine(result) {
1364
1396
  // decided there is none exactly where most readers stop reading. Grouped in
1365
1397
  // first-seen order so the sentence does not reorder itself between runs.
1366
1398
  const skippedByWording = new Map();
1367
- for (const gate of result.skipped) {
1399
+ // An intent gate that ran and checked nothing (issue 103) is named in the
1400
+ // same clause as the pull-request path's no-contract skip: it is the same
1401
+ // state, and this line is all a hook or a pull request comment prints.
1402
+ const checkedNothing = [
1403
+ ...result.skipped,
1404
+ ...result.gates
1405
+ .filter(intentCheckedNothing)
1406
+ .map((gate) => ({ role: gate.role, product: gate.product, reason: 'no-contract' })),
1407
+ ];
1408
+ for (const gate of checkedNothing) {
1368
1409
  const lead = skipWording(gate.reason).summary;
1369
1410
  skippedByWording.set(lead, [
1370
1411
  ...(skippedByWording.get(lead) ?? []),
package/dist/policy.d.ts CHANGED
@@ -140,11 +140,31 @@ export interface CliOverrides {
140
140
  export declare function applyCliOverrides(policy: Policy, overrides: CliOverrides): Policy;
141
141
  /** Enabled gates in role order, so a report's section order never depends on file order. */
142
142
  export declare function enabledGates(policy: Policy): GatePolicy[];
143
+ /**
144
+ * Flags that take NO value, per product, read from each gate's own `--help`
145
+ * (osv-scanner 2.4.0 `scan source`, gitleaks 8.30.1 `git`, dep-guard 0.17.0
146
+ * and vault-guard 1.12.1 `scan`, intent-guard 1.10.2 `check`, and 1.10.3
147
+ * `check` again for issue 161, which lists the same flags). Two readers:
148
+ *
149
+ * - gateArgEntries in resolve.ts: the word after one of these is NOT its
150
+ * value, so `osv-scanner scan source -r .` keeps `.` as a positional scan
151
+ * target (re-review 2026-10-28, R1). Any flag not listed stays
152
+ * fail-closed there: the word after it is read as its value. A wrong
153
+ * entry would let a value be read as a positional, which leaves a
154
+ * directory unvetted, so entries come only from a gate's own help text.
155
+ * - renderOptionFlags below: a `true` option whose gate lists `--no-<key>`
156
+ * and not `--<key>` is not rendered (issue 161).
157
+ */
158
+ export declare const NO_VALUE_FLAGS: Record<Product, readonly string[]>;
143
159
  /**
144
160
  * Renders a passthrough option bag as child-process arguments.
145
161
  *
146
162
  * Keys are sorted so two policy files that differ only in key order produce
147
163
  * the same command line, which is what makes a run reproducible and a
148
164
  * report diffable.
165
+ *
166
+ * `product` is required so every caller renders what that gate accepts:
167
+ * `true` is `--key`, except where the gate's own help has only `--no-key`
168
+ * (onlyNegatedSpelling), where it is nothing.
149
169
  */
150
- export declare function renderOptionFlags(options: Record<string, OptionValue>): string[];
170
+ export declare function renderOptionFlags(options: Record<string, OptionValue>, product: Product): string[];
package/dist/policy.js CHANGED
@@ -443,19 +443,75 @@ export function applyCliOverrides(policy, overrides) {
443
443
  export function enabledGates(policy) {
444
444
  return GATE_ROLES.map((role) => policy.gates[role]).filter((gate) => gate !== undefined && gate.enabled);
445
445
  }
446
+ /**
447
+ * Flags that take NO value, per product, read from each gate's own `--help`
448
+ * (osv-scanner 2.4.0 `scan source`, gitleaks 8.30.1 `git`, dep-guard 0.17.0
449
+ * and vault-guard 1.12.1 `scan`, intent-guard 1.10.2 `check`, and 1.10.3
450
+ * `check` again for issue 161, which lists the same flags). Two readers:
451
+ *
452
+ * - gateArgEntries in resolve.ts: the word after one of these is NOT its
453
+ * value, so `osv-scanner scan source -r .` keeps `.` as a positional scan
454
+ * target (re-review 2026-10-28, R1). Any flag not listed stays
455
+ * fail-closed there: the word after it is read as its value. A wrong
456
+ * entry would let a value be read as a positional, which leaves a
457
+ * directory unvetted, so entries come only from a gate's own help text.
458
+ * - renderOptionFlags below: a `true` option whose gate lists `--no-<key>`
459
+ * and not `--<key>` is not rendered (issue 161).
460
+ */
461
+ export const NO_VALUE_FLAGS = {
462
+ 'osv-scanner': [
463
+ '-r', '--recursive', '--no-ignore', '--include-git-root', '--serve', '--offline',
464
+ '--offline-vulnerabilities', '--download-offline-databases', '--no-resolve',
465
+ '--allow-no-lockfiles', '--all-packages', '--all-vulns',
466
+ '--experimental-flag-deprecated-packages', '--experimental-no-default-plugins', '-h', '--help',
467
+ ],
468
+ gitleaks: [
469
+ '-v', '--verbose', '--pre-commit', '--staged', '--ignore-gitleaks-allow', '--no-banner',
470
+ '--no-color', '--redact', '-h', '--help',
471
+ ],
472
+ 'dep-guard': ['--staged', '--online', '--no-online', '-h', '--help'],
473
+ 'vault-guard': ['--staged', '-h', '--help'],
474
+ 'intent-guard': ['--staged', '--no-require-frozen', '--log', '--json', '-h', '--help', '-v', '--version'],
475
+ };
476
+ /**
477
+ * Whether `--<key>` is a spelling the gate does not have while `--no-<key>`
478
+ * is: its own help lists only the negation. The gate's default for such a
479
+ * flag is then on (a `--no-` flag exists to turn a default off), so a policy
480
+ * value `true` asks for exactly the default, and rendering it would hand the
481
+ * gate an option it refuses (issue 161: intent-guard 1.10.3 `check
482
+ * --require-frozen` exits 1 with "unknown option", which every directly
483
+ * spawned run reported as unparseable output).
484
+ *
485
+ * General across gates, not an intent-guard case: gitleaks `banner` and
486
+ * `color` and osv-scanner `ignore` and `resolve` take the same path. The
487
+ * premise is the table's: NO_VALUE_FLAGS lists only value-less flags, so
488
+ * this reads "the gate has a value-less --no-<key> and no value-less
489
+ * --<key>". A gate with a VALUED --<key> beside a value-less --no-<key>
490
+ * would wrongly lose `true`; no gate has that shape today.
491
+ */
492
+ function onlyNegatedSpelling(key, product) {
493
+ const known = NO_VALUE_FLAGS[product];
494
+ return known.includes(`--no-${key}`) && !known.includes(`--${key}`);
495
+ }
446
496
  /**
447
497
  * Renders a passthrough option bag as child-process arguments.
448
498
  *
449
499
  * Keys are sorted so two policy files that differ only in key order produce
450
500
  * the same command line, which is what makes a run reproducible and a
451
501
  * report diffable.
502
+ *
503
+ * `product` is required so every caller renders what that gate accepts:
504
+ * `true` is `--key`, except where the gate's own help has only `--no-key`
505
+ * (onlyNegatedSpelling), where it is nothing.
452
506
  */
453
- export function renderOptionFlags(options) {
507
+ export function renderOptionFlags(options, product) {
454
508
  const args = [];
455
509
  for (const key of Object.keys(options).sort()) {
456
510
  const value = options[key];
457
511
  if (value === true) {
458
- args.push(`--${key}`);
512
+ if (!onlyNegatedSpelling(key, product)) {
513
+ args.push(`--${key}`);
514
+ }
459
515
  }
460
516
  else if (value === false) {
461
517
  // Both dep-guard and intent-guard spell a negated boolean this way,
package/dist/resolve.d.ts CHANGED
@@ -26,6 +26,8 @@ export interface DataArgument {
26
26
  positional: boolean;
27
27
  /** The args entry as written, for the refusal message. */
28
28
  entry: string;
29
+ /** 'options' when the value came from the policy's `options:`, so the refusal names that list; absent for `args:`. */
30
+ from?: 'options';
29
31
  }
30
32
  export interface ResolvedBinary {
31
33
  /** What to spawn. */
@@ -59,14 +61,23 @@ export interface ResolvedBinary {
59
61
  * When `command:` is the gate itself (commandIsGateProgram) only the args
60
62
  * entries with a code extension are listed here (`codeArguments`); the
61
63
  * rest of its args are its own argv, read as data, and land in
62
- * `dataArguments` instead.
64
+ * `dataArguments` instead. The code-extension `options:` values are listed
65
+ * here too, for every command and for a gate resolution found (audit
66
+ * 2026-11-01, MB1).
63
67
  */
64
68
  argumentPaths: string[];
69
+ /**
70
+ * The entries of `argumentPaths` that came from `options:`, so a refusal
71
+ * names the list the value was written in (review of the 2026-11-01 fix,
72
+ * item 3). Absent is the same as empty: every entry came from `args:`.
73
+ */
74
+ optionArgumentPaths?: string[];
65
75
  /**
66
76
  * Every args entry that could name a path, when `command:` is the gate
67
77
  * itself (`dataArgumentPaths`), in args order, by POSITION and never by
68
- * what the head's disk holds. Empty for every other command, and when
69
- * resolution found the gate.
78
+ * what the head's disk holds; then every non-code `options:` value as
79
+ * rendered, for every command and for a gate resolution found (audit
80
+ * 2026-11-01, MB1).
70
81
  *
71
82
  * The pull-request check (refuseHeadControlledData) decides from the BASE
72
83
  * tree what each one is: a file must be the base's blob, a directory given
@@ -195,7 +206,8 @@ export declare function argumentCandidates(arg: string, repoRoot: string): strin
195
206
  /**
196
207
  * The args entries vetted as CODE: every entry when the command is not the
197
208
  * gate itself, and only the code-extension values (`hasCodeExtension`) when
198
- * it is. Each goes through `argumentCandidates`, here and in the preview.
209
+ * it is, then the code-extension `options:` values (optionCodeArguments).
210
+ * Each goes through `argumentCandidates`, here and in the preview.
199
211
  */
200
212
  export declare function codeArguments(gate: GatePolicy): string[];
201
213
  /**
@@ -218,5 +230,12 @@ export declare function codeArguments(gate: GatePolicy): string[];
218
230
  * wrapper given a gate's name that hands an extension-less entry to an
219
231
  * interpreter is a wrapper, vetted no further than this (README,
220
232
  * pull-request trust boundary).
233
+ *
234
+ * Then every non-code `options:` value (optionEntries), WHATEVER the command
235
+ * is and with no command at all: they are rendered into the argv of every
236
+ * spawn, after the args, so they are the gate's own data (or a script's)
237
+ * whoever runs them, and a rules directory written there is as much the
238
+ * rules as one written in args (audit 2026-11-01, MB1). Marked `from:
239
+ * 'options'` only so a refusal names the list the value came from.
221
240
  */
222
241
  export declare function dataArgumentPaths(gate: GatePolicy, repoRoot: string): DataArgument[];
package/dist/resolve.js CHANGED
@@ -61,6 +61,7 @@
61
61
  // reported missing.
62
62
  import { accessSync, constants, lstatSync, statSync } from 'node:fs';
63
63
  import path from 'node:path';
64
+ import { NO_VALUE_FLAGS, renderOptionFlags } from './policy.js';
64
65
  import { profileFor } from './products.js';
65
66
  export const CANDIDATES = {
66
67
  'dep-guard': [{ name: 'dep-guard', prefix: ['scan'], versionSafe: true }],
@@ -221,6 +222,7 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
221
222
  const candidateName = inferred?.name ?? baseName(gate.command);
222
223
  const candidate = inferred ?? table[0];
223
224
  const argumentPaths = argumentPathsOf(gate, repoRoot);
225
+ const optionArgumentPaths = optionArgumentPathsOf(gate, repoRoot);
224
226
  const dataArguments = dataArgumentPaths(gate, repoRoot);
225
227
  // A build directory holds plain .js files with a shebang but no
226
228
  // executable bit surprisingly often (a fresh tsc output, a file copied
@@ -234,6 +236,7 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
234
236
  program: gate.command,
235
237
  argvPrefix: [gate.command, ...prefix],
236
238
  argumentPaths,
239
+ optionArgumentPaths,
237
240
  dataArguments,
238
241
  source: 'policy',
239
242
  candidate: candidateName,
@@ -255,6 +258,7 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
255
258
  program: gate.command,
256
259
  argvPrefix: prefix,
257
260
  argumentPaths,
261
+ optionArgumentPaths,
258
262
  dataArguments,
259
263
  source: 'policy',
260
264
  candidate: candidateName,
@@ -271,8 +275,11 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
271
275
  command: found.command,
272
276
  program: found.command,
273
277
  argvPrefix: [...candidate.prefix],
274
- argumentPaths: [],
275
- dataArguments: [],
278
+ // No args: here (they go with a command:), but the options: are handed
279
+ // to this gate all the same (audit 2026-11-01, MB1).
280
+ argumentPaths: optionArgumentPathsOf(gate, repoRoot),
281
+ optionArgumentPaths: optionArgumentPathsOf(gate, repoRoot),
282
+ dataArguments: dataArgumentPaths(gate, repoRoot),
276
283
  source: found.source,
277
284
  candidate: candidate.name,
278
285
  versionProbe: versionProbeFor(gate.product, candidate, found.command, repoRoot, pathValue, skipNodeModules),
@@ -412,35 +419,10 @@ function hasCodeExtension(value) {
412
419
  * - a bare word that is one of the product's subcommands: nothing;
413
420
  * - any other word: a positional.
414
421
  */
415
- /**
416
- * Flags that take NO value, per product, read from each gate's own `--help`
417
- * (osv-scanner 2.4.0 `scan source`, gitleaks 8.30.1 `git`, dep-guard 0.17.0
418
- * and vault-guard 1.12.1 `scan`, intent-guard 1.10.2 `check`). The word after
419
- * one of these is NOT its value, so `osv-scanner scan source -r .` keeps `.`
420
- * as a positional scan target (re-review 2026-10-28, R1). Any flag not listed
421
- * stays fail-closed: the word after it is read as its value. A wrong entry
422
- * would let a value be read as a positional, which leaves a directory
423
- * unvetted, so entries come only from a gate's own help text.
424
- */
425
- const NO_VALUE_FLAGS = {
426
- 'osv-scanner': [
427
- '-r', '--recursive', '--no-ignore', '--include-git-root', '--serve', '--offline',
428
- '--offline-vulnerabilities', '--download-offline-databases', '--no-resolve',
429
- '--allow-no-lockfiles', '--all-packages', '--all-vulns',
430
- '--experimental-flag-deprecated-packages', '--experimental-no-default-plugins', '-h', '--help',
431
- ],
432
- gitleaks: [
433
- '-v', '--verbose', '--pre-commit', '--staged', '--ignore-gitleaks-allow', '--no-banner',
434
- '--no-color', '--redact', '-h', '--help',
435
- ],
436
- 'dep-guard': ['--staged', '--online', '--no-online', '-h', '--help'],
437
- 'vault-guard': ['--staged', '-h', '--help'],
438
- 'intent-guard': ['--staged', '--no-require-frozen', '--log', '--json', '-h', '--help', '-v', '--version'],
439
- };
440
- function gateArgEntries(gate) {
422
+ function gateArgEntries(product, words) {
441
423
  const entries = [];
442
424
  let pendingOption = false;
443
- for (const arg of gate.args ?? []) {
425
+ for (const arg of words) {
444
426
  if (arg.startsWith('-') && arg !== '-') {
445
427
  pendingOption = false;
446
428
  const equals = arg.indexOf('=');
@@ -453,7 +435,7 @@ function gateArgEntries(gate) {
453
435
  else {
454
436
  // A flag the gate's own help says takes no value leaves the next word
455
437
  // a positional (NO_VALUE_FLAGS); any other flag claims it.
456
- pendingOption = !NO_VALUE_FLAGS[gate.product].includes(arg);
438
+ pendingOption = !NO_VALUE_FLAGS[product].includes(arg);
457
439
  }
458
440
  continue;
459
441
  }
@@ -462,30 +444,54 @@ function gateArgEntries(gate) {
462
444
  entries.push({ value: arg, positional: false, entry: arg });
463
445
  continue;
464
446
  }
465
- if (CANDIDATES[gate.product].some((candidate) => candidate.prefix.includes(arg))) {
447
+ if (CANDIDATES[product].some((candidate) => candidate.prefix.includes(arg))) {
466
448
  continue;
467
449
  }
468
450
  entries.push({ value: arg, positional: true, entry: arg });
469
451
  }
470
452
  return entries.filter((each) => each.value !== '');
471
453
  }
454
+ /**
455
+ * The policy's `options:` as the gate receives them: rendered to flags
456
+ * (renderOptionFlags, the same rendering gateArgs appends to every spawn) and
457
+ * read by position like a gate-named command's args (audit 2026-11-01, MB1).
458
+ *
459
+ * Whatever the command is: the rendered flags always come after the args, so
460
+ * they are the gate's own argv, or a script's argv when the command is an
461
+ * interpreter, and never an interpreter's. Option keys cannot hold `=` (the
462
+ * schema's key pattern), so `--name value` is the only rendering there is.
463
+ */
464
+ function optionEntries(gate) {
465
+ return gateArgEntries(gate.product, renderOptionFlags(gate.options, gate.product));
466
+ }
467
+ /** The `options:` values vetted as CODE: those with a code extension, as for a gate-named command's args. */
468
+ function optionCodeArguments(gate) {
469
+ return optionEntries(gate)
470
+ .filter((each) => hasCodeExtension(each.value))
471
+ .map((each) => each.value);
472
+ }
472
473
  /**
473
474
  * The args entries vetted as CODE: every entry when the command is not the
474
475
  * gate itself, and only the code-extension values (`hasCodeExtension`) when
475
- * it is. Each goes through `argumentCandidates`, here and in the preview.
476
+ * it is, then the code-extension `options:` values (optionCodeArguments).
477
+ * Each goes through `argumentCandidates`, here and in the preview.
476
478
  */
477
479
  export function codeArguments(gate) {
478
- if (!commandIsGateProgram(gate)) {
479
- return gate.args ?? [];
480
- }
481
- return gateArgEntries(gate)
482
- .filter((each) => hasCodeExtension(each.value))
483
- .map((each) => each.value);
480
+ const fromArgs = !commandIsGateProgram(gate)
481
+ ? gate.args ?? []
482
+ : gateArgEntries(gate.product, gate.args ?? [])
483
+ .filter((each) => hasCodeExtension(each.value))
484
+ .map((each) => each.value);
485
+ return [...fromArgs, ...optionCodeArguments(gate)];
484
486
  }
485
487
  /** `argumentCandidates` for every code argument (`codeArguments`), flattened. */
486
488
  function argumentPathsOf(gate, repoRoot) {
487
489
  return codeArguments(gate).flatMap((arg) => argumentCandidates(arg, repoRoot));
488
490
  }
491
+ /** `argumentCandidates` for the code-extension `options:` values alone (optionCodeArguments). */
492
+ function optionArgumentPathsOf(gate, repoRoot) {
493
+ return optionCodeArguments(gate).flatMap((arg) => argumentCandidates(arg, repoRoot));
494
+ }
489
495
  /**
490
496
  * The args entries of a gate-named command that are its own DATA, when
491
497
  * `command:` is the gate itself (commandIsGateProgram), in args order; empty
@@ -506,14 +512,29 @@ function argumentPathsOf(gate, repoRoot) {
506
512
  * wrapper given a gate's name that hands an extension-less entry to an
507
513
  * interpreter is a wrapper, vetted no further than this (README,
508
514
  * pull-request trust boundary).
515
+ *
516
+ * Then every non-code `options:` value (optionEntries), WHATEVER the command
517
+ * is and with no command at all: they are rendered into the argv of every
518
+ * spawn, after the args, so they are the gate's own data (or a script's)
519
+ * whoever runs them, and a rules directory written there is as much the
520
+ * rules as one written in args (audit 2026-11-01, MB1). Marked `from:
521
+ * 'options'` only so a refusal names the list the value came from.
509
522
  */
510
523
  export function dataArgumentPaths(gate, repoRoot) {
511
- if (gate.command === undefined || !commandIsGateProgram(gate)) {
512
- return [];
513
- }
514
- return gateArgEntries(gate)
524
+ const fromArgs = gate.command === undefined || !commandIsGateProgram(gate)
525
+ ? []
526
+ : gateArgEntries(gate.product, gate.args ?? [])
527
+ .filter((each) => !hasCodeExtension(each.value))
528
+ .map((each) => ({ path: path.resolve(repoRoot, each.value), positional: each.positional, entry: each.entry }));
529
+ const fromOptions = optionEntries(gate)
515
530
  .filter((each) => !hasCodeExtension(each.value))
516
- .map((each) => ({ path: path.resolve(repoRoot, each.value), positional: each.positional, entry: each.entry }));
531
+ .map((each) => ({
532
+ path: path.resolve(repoRoot, each.value),
533
+ positional: each.positional,
534
+ entry: each.entry,
535
+ from: 'options',
536
+ }));
537
+ return [...fromArgs, ...fromOptions];
517
538
  }
518
539
  /**
519
540
  * The version probe for a policy `command:` that is not itself a gate name,
@@ -253,6 +253,12 @@ export type TreeEntry = {
253
253
  * decided outside the tree, so it is an error, never absent.
254
254
  */
255
255
  export declare function treeEntryAt(repoRoot: string, ref: string, relativePath: string): TreeEntry;
256
+ /**
257
+ * Whether `candidate`, as written, names the working tree or something in it
258
+ * (writtenRelative). For the preview's outright refusals, so a base path
259
+ * written inside the tree is refused there even when a link on it points out.
260
+ */
261
+ export declare function writtenInsideWorkingTree(repoRoot: string, candidate: string): boolean;
256
262
  /**
257
263
  * Why this gate's PROGRAM cannot be trusted on a pull-request run, or null.
258
264
  *
@@ -322,10 +328,23 @@ export declare function treeEntryAt(repoRoot: string, ref: string, relativePath:
322
328
  * or its tree entry is a link rather than a regular file, and either refuses.
323
329
  * Vetting the target is what catches a link whose own path is outside the
324
330
  * tree pointing into it; it never decides the in-repo case.
331
+ *
332
+ * AND THE PATH AS WRITTEN, for this rule and for both args rules below
333
+ * (audit 2026-11-01, MB2). Both spellings above resolve the directories on
334
+ * the path through the head's disk, so a head that replaced `tools/` with a
335
+ * link to a base-tracked `stub/` had `tools/vault-guard` judged as
336
+ * `stub/vault-guard`, which the base approved. So the path is also judged
337
+ * exactly as written inside the tree (writtenRelative): refused when HEAD's
338
+ * tree holds any directory on it as a link (linkOnWrittenPathAtHead), and
339
+ * the written path is one more candidate, judged by its own entries at both
340
+ * refs like the others. A link the base already had there is refused too:
341
+ * what the gate is handed through it is still decided by the head tree.
325
342
  */
326
343
  export declare function refuseHeadControlledProgram(repoRoot: string, trustBase: string, programPath: string,
327
344
  /** True when asked for an interpreter's `args:` entry, which words the root refusal for an argument. */
328
- fromArgs?: boolean): string | null;
345
+ fromArgs?: boolean,
346
+ /** Which policy list an argument came from, for its refusals: `args:`, or `options:` for a code-extension option value. */
347
+ list?: string): string | null;
329
348
  /**
330
349
  * Whether a gate's reported version is at least `minimum`.
331
350
  *
@@ -371,13 +390,16 @@ export declare function atLeastVersion(version: string | null, minimum: string):
371
390
  * read from disk, and a link is never followed for that, so a link is always
372
391
  * vetted as a link.
373
392
  */
374
- export declare function refuseHeadControlledArgument(repoRoot: string, trustBase: string, argumentPath: string): string | null;
393
+ export declare function refuseHeadControlledArgument(repoRoot: string, trustBase: string, argumentPath: string,
394
+ /** Which policy list the path came from, for the refusals: `args:`, or `options:` for a code-extension option value. */
395
+ list?: string): string | null;
375
396
  /**
376
397
  * Why a path a gate's own `args:` name cannot be trusted on a pull-request
377
398
  * run, or null (audit 2026-10-28, N1, and its review, B1 and N-a).
378
399
  *
379
- * Asked only when `command:` is the gate itself (dataArgumentPaths in
380
- * src/resolve.ts), whose args are its own argv: a rules file such as
400
+ * Asked for the args of a `command:` that is the gate itself, and for the
401
+ * `options:` values of every gate (dataArgumentPaths in src/resolve.ts),
402
+ * since both are the gate's own argv: a rules file such as
381
403
  * `--config=.gitleaks.toml`, or a rules directory such as dep-guard's
382
404
  * `--corpus-dir`, is read as data, not loaded as code. Its contents still
383
405
  * decide what the gate reports, so a pull request that rewrote them would
@@ -406,6 +428,14 @@ export declare function refuseHeadControlledArgument(repoRoot: string, trustBase
406
428
  * - Absent at the base: accepted only if the head has nothing there either,
407
429
  * tracked or on disk (a word that is not a path, `--format=json`);
408
430
  * otherwise it is a path this pull request chose, and refused.
431
+ * - AS WRITTEN as well as resolved (audit 2026-11-01, MB2): a directory on
432
+ * the written path that HEAD's tree holds as a link is refused, the
433
+ * written path is judged by the rules above like the resolved ones, and a
434
+ * positional scan target the base tracks as a directory is refused when
435
+ * HEAD holds it as a link, since that one is otherwise not compared.
436
+ * - The same for an `options:` value (audit 2026-11-01, MB1): it is
437
+ * rendered into the gate's argv and read the same way (dataArgumentPaths),
438
+ * and `from: 'options'` only changes which list the refusal names.
409
439
  *
410
440
  * Only whether something exists on disk at a path the base does not track is
411
441
  * read from the working tree; every other answer is a `git ls-tree` listing.
@@ -414,4 +444,5 @@ export declare function refuseHeadControlledData(repoRoot: string, trustBase: st
414
444
  path: string;
415
445
  positional: boolean;
416
446
  entry?: string;
447
+ from?: 'options';
417
448
  }): string | null;
@@ -708,6 +708,132 @@ function withResolvedParent(candidate) {
708
708
  const parent = path.dirname(candidate);
709
709
  return path.join(realOrNull(parent) ?? parent, path.basename(candidate));
710
710
  }
711
+ /**
712
+ * A vetted path AS WRITTEN, relative to the repository root with `/`
713
+ * separators: '' for the root itself, null when the path is not in the
714
+ * working tree (audit 2026-11-01, MB2).
715
+ *
716
+ * The resolved spellings above follow every link on the path, and a link
717
+ * inside the tree is the head's to choose: a head that replaces `data/` with
718
+ * a link to a base-approved `alt/` makes `data/corpus` resolve to
719
+ * `alt/corpus`, whose tree is the base's, while the policy named
720
+ * `data/corpus`. So the components INSIDE the tree are kept exactly as
721
+ * written. Only the leading components that reach the tree are resolved: the
722
+ * shortest prefix whose real path is the root or under it, which is how a
723
+ * root spelled through a symlinked mount (a macOS temporary directory) or an
724
+ * outside link into the tree still lands inside. Components above the tree
725
+ * are the machine's, which a pull request cannot write.
726
+ */
727
+ function writtenRelative(repoReal, candidate) {
728
+ const absolute = path.resolve(candidate);
729
+ const root = path.parse(absolute).root;
730
+ const segments = absolute.slice(root.length).split(path.sep).filter((segment) => segment !== '');
731
+ for (let depth = 0; depth <= segments.length; depth += 1) {
732
+ const real = realOrNull(path.join(root, ...segments.slice(0, depth)));
733
+ if (real === null) {
734
+ // Nothing below a missing component exists either.
735
+ return null;
736
+ }
737
+ if (real === repoReal || insideWorkingTree(repoReal, real)) {
738
+ const reached = path.relative(repoReal, real).split(path.sep).filter((segment) => segment !== '');
739
+ return [...reached, ...segments.slice(depth)].join('/');
740
+ }
741
+ }
742
+ return null;
743
+ }
744
+ /**
745
+ * Whether `candidate`, as written, names the working tree or something in it
746
+ * (writtenRelative). For the preview's outright refusals, so a base path
747
+ * written inside the tree is refused there even when a link on it points out.
748
+ */
749
+ export function writtenInsideWorkingTree(repoRoot, candidate) {
750
+ const repoReal = realOrNull(repoRoot);
751
+ return repoReal !== null && writtenRelative(repoReal, candidate) !== null;
752
+ }
753
+ /**
754
+ * The first DIRECTORY component above the last one of `relative` that HEAD's
755
+ * tree holds as a symbolic link, or null (audit 2026-11-01, MB2). Read from
756
+ * `git ls-tree`, one component at a time, never from the disk. Stops,
757
+ * answering null, at a component HEAD does not have, cannot list, or holds as
758
+ * a file: what is below it is then absent or unreadable, which the rule
759
+ * asking decides. The last component is each rule's own entry, which every
760
+ * rule already refuses as a link in its own words (a positional scan target
761
+ * included, in refuseHeadControlledData).
762
+ */
763
+ function linkOnWrittenPathAtHead(repoRoot, relative) {
764
+ const segments = relative.split('/').filter((segment) => segment !== '' && segment !== '.');
765
+ for (let depth = 1; depth < segments.length; depth += 1) {
766
+ const prefix = segments.slice(0, depth).join('/');
767
+ const listed = listOne(repoRoot, 'HEAD', prefix);
768
+ if (listed.kind !== 'entry') {
769
+ return null;
770
+ }
771
+ if (listed.mode === '120000') {
772
+ return prefix;
773
+ }
774
+ if (listed.type !== 'tree') {
775
+ return null;
776
+ }
777
+ }
778
+ return null;
779
+ }
780
+ /**
781
+ * The refusal for a vetted path a link at HEAD redirects, naming the link.
782
+ * `subject` is how the rule asking names the path: "the gate program at X",
783
+ * "in the gate's args:, the path X", "the path X named in the gate's args:".
784
+ */
785
+ function linkOnWrittenPathRefusal(subject, link, baseName) {
786
+ return (`${subject} goes through ${link}, which is a symbolic link at the head commit, so this pull ` +
787
+ 'request changed the path it is judged by: the gate would be handed whatever that link points ' +
788
+ `at, not the path ${baseName} approved. conductor judges every path as written and follows no ` +
789
+ 'link inside the repository. Name the directory the link points at, or commit a real directory ' +
790
+ 'there on the base branch. Nothing was checked by this gate.');
791
+ }
792
+ /**
793
+ * The first component of `relative`, the last one included, that is a
794
+ * symbolic link ON DISK while HEAD's tree holds no link at that exact
795
+ * spelling, or null (review of the 2026-11-01 fix, item 1).
796
+ *
797
+ * `git ls-tree` matches names exactly, and a case-insensitive disk does not:
798
+ * a head that adds a link entry `data` beside the base's tree `Data` leaves
799
+ * only `data -> alt` on disk after a checkout, so `Data/corpus` reads the
800
+ * link's target while the tree still says `Data` is the base's directory.
801
+ * The disk is therefore asked too, and a link there that the tree does not
802
+ * declare at that spelling refuses: what the gate is handed is decided by
803
+ * something other than the tree conductor judged. A link the tree DOES
804
+ * declare is left to the checks that already refuse it. Stops at the first
805
+ * component that is missing or not a directory. Each rule asks this LAST, so
806
+ * a path its own checks refuse keeps its wording; the exception is the data
807
+ * rule's positional root, which returns early and asks this first (R1).
808
+ */
809
+ function undeclaredLinkOnDisk(repoRoot, repoReal, relative) {
810
+ const segments = relative.split('/').filter((segment) => segment !== '' && segment !== '.');
811
+ for (let depth = 1; depth <= segments.length; depth += 1) {
812
+ const prefix = segments.slice(0, depth).join('/');
813
+ let stats;
814
+ try {
815
+ stats = lstatSync(path.join(repoReal, prefix));
816
+ }
817
+ catch {
818
+ return null;
819
+ }
820
+ if (stats.isSymbolicLink()) {
821
+ const listed = listOne(repoRoot, 'HEAD', prefix);
822
+ return listed.kind === 'entry' && listed.mode === '120000' ? null : prefix;
823
+ }
824
+ if (!stats.isDirectory()) {
825
+ return null;
826
+ }
827
+ }
828
+ return null;
829
+ }
830
+ /** The refusal for a link on disk the head tree does not declare, naming it. */
831
+ function undeclaredLinkRefusal(subject, link) {
832
+ return (`${subject} goes through ${link}, which is a symbolic link on disk that the pull request's tree does not declare ` +
833
+ 'there, so what the gate would be handed is decided by something other than the tree conductor ' +
834
+ 'judged. On a case-insensitive filesystem a tree entry spelled with different case is the same ' +
835
+ 'path. Nothing was checked by this gate.');
836
+ }
711
837
  /**
712
838
  * The tree object id of one directory at a ref, or null.
713
839
  *
@@ -792,16 +918,44 @@ function treeShaAt(repoRoot, ref, relativeDir) {
792
918
  * or its tree entry is a link rather than a regular file, and either refuses.
793
919
  * Vetting the target is what catches a link whose own path is outside the
794
920
  * tree pointing into it; it never decides the in-repo case.
921
+ *
922
+ * AND THE PATH AS WRITTEN, for this rule and for both args rules below
923
+ * (audit 2026-11-01, MB2). Both spellings above resolve the directories on
924
+ * the path through the head's disk, so a head that replaced `tools/` with a
925
+ * link to a base-tracked `stub/` had `tools/vault-guard` judged as
926
+ * `stub/vault-guard`, which the base approved. So the path is also judged
927
+ * exactly as written inside the tree (writtenRelative): refused when HEAD's
928
+ * tree holds any directory on it as a link (linkOnWrittenPathAtHead), and
929
+ * the written path is one more candidate, judged by its own entries at both
930
+ * refs like the others. A link the base already had there is refused too:
931
+ * what the gate is handed through it is still decided by the head tree.
795
932
  */
796
933
  export function refuseHeadControlledProgram(repoRoot, trustBase, programPath,
797
934
  /** True when asked for an interpreter's `args:` entry, which words the root refusal for an argument. */
798
- fromArgs = false) {
935
+ fromArgs = false,
936
+ /** Which policy list an argument came from, for its refusals: `args:`, or `options:` for a code-extension option value. */
937
+ list = "the gate's args:") {
799
938
  const repoReal = realOrNull(repoRoot);
800
939
  if (repoReal === null) {
801
940
  return `the repository root ${repoRoot} could not be resolved, so the gate program could not be checked against "${trustBase}". Nothing was checked by this gate.`;
802
941
  }
942
+ // AS WRITTEN, before either resolved spelling (audit 2026-11-01, MB2): a
943
+ // directory on the written path that HEAD holds as a link redirects the
944
+ // program to wherever the head points it, and the written path is also a
945
+ // candidate below, judged by its own entries at both refs.
946
+ const written = writtenRelative(repoReal, programPath);
947
+ if (written !== null && written !== '') {
948
+ const link = linkOnWrittenPathAtHead(repoRoot, written);
949
+ if (link !== null) {
950
+ return linkOnWrittenPathRefusal(fromArgs ? `in ${list}, the path ${written}` : `the gate program at ${written}`, link, trustBase === '' ? 'the base' : `"${trustBase}"`);
951
+ }
952
+ }
803
953
  const candidates = new Set();
804
- for (const candidate of [withResolvedParent(programPath), realOrNull(programPath)]) {
954
+ for (const candidate of [
955
+ withResolvedParent(programPath),
956
+ realOrNull(programPath),
957
+ written === null ? null : path.join(repoReal, written),
958
+ ]) {
805
959
  if (candidate !== null && insideWorkingTree(repoReal, candidate)) {
806
960
  candidates.add(candidate);
807
961
  }
@@ -827,18 +981,18 @@ fromArgs = false) {
827
981
  // gate program": it may be a script or a file a script reads (review
828
982
  // 2026-10-28, N-f, which the first N1 round fixed for the root only).
829
983
  if (fromArgs && (base === null || head === null)) {
830
- return (`in the gate's args:, the ${trustBase === '' ? 'base' : `"${trustBase}"`} ref does not ` +
984
+ return (`in ${list}, the ${trustBase === '' ? 'base' : `"${trustBase}"`} ref does not ` +
831
985
  `track ${relative}, a file named there or one an interpreter could load for it, so it is ` +
832
986
  'a file this pull request controls, vetted as code. Land it on the base branch first, or ' +
833
987
  'name a script outside the repository. Nothing was checked by this gate.');
834
988
  }
835
989
  if (fromArgs && (!isRegularFileMode(base.mode) || !isRegularFileMode(head.mode))) {
836
- return (`in the gate's args:, the file ${relative} is not a regular file at both "${trustBase}" ` +
990
+ return (`in ${list}, the file ${relative} is not a regular file at both "${trustBase}" ` +
837
991
  'and the head commit, so what an interpreter would load is decided by something other ' +
838
992
  'than the approved bytes. Nothing was checked by this gate.');
839
993
  }
840
994
  if (fromArgs && base.sha !== head.sha) {
841
- return (`in the gate's args:, the file ${relative} is not the one "${trustBase}" approved: this ` +
995
+ return (`in ${list}, the file ${relative} is not the one "${trustBase}" approved: this ` +
842
996
  'pull request changes it, and it is vetted as code an interpreter could load. Land the ' +
843
997
  'change on the base branch first. Nothing was checked by this gate.');
844
998
  }
@@ -882,7 +1036,7 @@ fromArgs = false) {
882
1036
  // the file may be a script or something the script reads, so it is
883
1037
  // not called "the gate program", and the remedy is about the
884
1038
  // command, not about vendoring (audit 2026-10-28, N1).
885
- return (`the file ${relative} named in the gate's args: is at the repository root, and it is ` +
1039
+ return (`the file ${relative} named in ${list} is at the repository root, and it is ` +
886
1040
  'vetted as code an interpreter could load (the command is not the gate itself, or ' +
887
1041
  'the entry has a code extension): ' +
888
1042
  'the directory that would have to be unchanged is the whole repository, and this pull ' +
@@ -897,7 +1051,7 @@ fromArgs = false) {
897
1051
  'its own directory, or install it on PATH. Nothing was checked by this gate.');
898
1052
  }
899
1053
  if (fromArgs) {
900
- return (`in the gate's args:, a file beside ${relative} in ${directory} is not what ` +
1054
+ return (`in ${list}, a file beside ${relative} in ${directory} is not what ` +
901
1055
  `"${trustBase}" approved: ${relative} is unchanged, but the directory around it is not, ` +
902
1056
  'and code an interpreter loads can load its neighbours. Land the change on the base ' +
903
1057
  'branch first, or name a script outside the repository. Nothing was checked by this gate.');
@@ -909,6 +1063,13 @@ fromArgs = false) {
909
1063
  'PATH. Nothing was checked by this gate.');
910
1064
  }
911
1065
  }
1066
+ // LAST, the disk against the tree (review of the 2026-11-01 fix, item 1).
1067
+ if (written !== null && written !== '') {
1068
+ const undeclared = undeclaredLinkOnDisk(repoRoot, repoReal, written);
1069
+ if (undeclared !== null) {
1070
+ return undeclaredLinkRefusal(fromArgs ? `in ${list}, the path ${written}` : `the gate program at ${written}`, undeclared);
1071
+ }
1072
+ }
912
1073
  return null;
913
1074
  }
914
1075
  /**
@@ -975,18 +1136,32 @@ export function atLeastVersion(version, minimum) {
975
1136
  * read from disk, and a link is never followed for that, so a link is always
976
1137
  * vetted as a link.
977
1138
  */
978
- export function refuseHeadControlledArgument(repoRoot, trustBase, argumentPath) {
1139
+ export function refuseHeadControlledArgument(repoRoot, trustBase, argumentPath,
1140
+ /** Which policy list the path came from, for the refusals: `args:`, or `options:` for a code-extension option value. */
1141
+ list = "the gate's args:") {
979
1142
  const repoReal = realOrNull(repoRoot);
980
1143
  if (repoReal === null) {
981
1144
  return `the repository root ${repoRoot} could not be resolved, so the gate arguments could not be checked against "${trustBase}". Nothing was checked by this gate.`;
982
1145
  }
983
- const spellings = [withResolvedParent(argumentPath), realOrNull(argumentPath)].filter((spelling) => spelling !== null);
1146
+ // The written spelling beside the resolved ones (audit 2026-11-01, MB2).
1147
+ const written = writtenRelative(repoReal, argumentPath);
1148
+ const spellings = [
1149
+ withResolvedParent(argumentPath),
1150
+ realOrNull(argumentPath),
1151
+ written === null ? null : path.join(repoReal, written),
1152
+ ].filter((spelling) => spelling !== null);
984
1153
  if (spellings.some((spelling) => path.relative(repoReal, spelling) === '')) {
985
- return (`the gate's args: name the repository root (${argumentPath}), so what would run is decided by ` +
1154
+ return (`${list} name the repository root (${argumentPath}), so what would run is decided by ` +
986
1155
  `the whole working tree, and this pull request differs from "${trustBase}" somewhere in it. ` +
987
1156
  'conductor already hands each gate the repository it scans; name a script in its own ' +
988
1157
  'directory instead. Nothing was checked by this gate.');
989
1158
  }
1159
+ if (written !== null) {
1160
+ const link = linkOnWrittenPathAtHead(repoRoot, written);
1161
+ if (link !== null) {
1162
+ return linkOnWrittenPathRefusal(`in ${list}, the path ${written}`, link, trustBase === '' ? 'the base' : `"${trustBase}"`);
1163
+ }
1164
+ }
990
1165
  let isDirectory;
991
1166
  try {
992
1167
  isDirectory = lstatSync(argumentPath).isDirectory();
@@ -998,7 +1173,7 @@ export function refuseHeadControlledArgument(repoRoot, trustBase, argumentPath)
998
1173
  isDirectory = false;
999
1174
  }
1000
1175
  if (!isDirectory) {
1001
- return refuseHeadControlledProgram(repoRoot, trustBase, argumentPath, true);
1176
+ return refuseHeadControlledProgram(repoRoot, trustBase, argumentPath, true, list);
1002
1177
  }
1003
1178
  for (const spelling of new Set(spellings)) {
1004
1179
  if (!insideWorkingTree(repoReal, spelling)) {
@@ -1009,27 +1184,35 @@ export function refuseHeadControlledArgument(repoRoot, trustBase, argumentPath)
1009
1184
  const headEntry = treeEntryAt(repoRoot, 'HEAD', relative);
1010
1185
  for (const listed of [baseEntry, headEntry]) {
1011
1186
  if (listed.kind === 'error') {
1012
- return (`the directory ${relative} named in the gate's args: could not be checked against ` +
1187
+ return (`the directory ${relative} named in ${list} could not be checked against ` +
1013
1188
  `"${trustBase}": ${listed.detail}. Nothing was checked by this gate.`);
1014
1189
  }
1015
1190
  }
1016
1191
  const base = baseEntry.kind === 'entry' ? baseEntry : null;
1017
1192
  const head = headEntry.kind === 'entry' ? headEntry : null;
1018
1193
  if (base === null || head === null || base.type !== 'tree' || head.type !== 'tree' || base.sha !== head.sha) {
1019
- return (`the directory ${relative} named in the gate's args: is not what "${trustBase}" approved: ` +
1194
+ return (`the directory ${relative} named in ${list} is not what "${trustBase}" approved: ` +
1020
1195
  'this pull request adds, removes or changes something in it, and an interpreter handed a ' +
1021
1196
  'directory runs what is inside. Land the change on the base branch first, or name a ' +
1022
1197
  'script outside the repository. Nothing was checked by this gate.');
1023
1198
  }
1024
1199
  }
1200
+ // LAST, the disk against the tree (review of the 2026-11-01 fix, item 1).
1201
+ if (written !== null) {
1202
+ const undeclared = undeclaredLinkOnDisk(repoRoot, repoReal, written);
1203
+ if (undeclared !== null) {
1204
+ return undeclaredLinkRefusal(`in ${list}, the path ${written}`, undeclared);
1205
+ }
1206
+ }
1025
1207
  return null;
1026
1208
  }
1027
1209
  /**
1028
1210
  * Why a path a gate's own `args:` name cannot be trusted on a pull-request
1029
1211
  * run, or null (audit 2026-10-28, N1, and its review, B1 and N-a).
1030
1212
  *
1031
- * Asked only when `command:` is the gate itself (dataArgumentPaths in
1032
- * src/resolve.ts), whose args are its own argv: a rules file such as
1213
+ * Asked for the args of a `command:` that is the gate itself, and for the
1214
+ * `options:` values of every gate (dataArgumentPaths in src/resolve.ts),
1215
+ * since both are the gate's own argv: a rules file such as
1033
1216
  * `--config=.gitleaks.toml`, or a rules directory such as dep-guard's
1034
1217
  * `--corpus-dir`, is read as data, not loaded as code. Its contents still
1035
1218
  * decide what the gate reports, so a pull request that rewrote them would
@@ -1058,26 +1241,67 @@ export function refuseHeadControlledArgument(repoRoot, trustBase, argumentPath)
1058
1241
  * - Absent at the base: accepted only if the head has nothing there either,
1059
1242
  * tracked or on disk (a word that is not a path, `--format=json`);
1060
1243
  * otherwise it is a path this pull request chose, and refused.
1244
+ * - AS WRITTEN as well as resolved (audit 2026-11-01, MB2): a directory on
1245
+ * the written path that HEAD's tree holds as a link is refused, the
1246
+ * written path is judged by the rules above like the resolved ones, and a
1247
+ * positional scan target the base tracks as a directory is refused when
1248
+ * HEAD holds it as a link, since that one is otherwise not compared.
1249
+ * - The same for an `options:` value (audit 2026-11-01, MB1): it is
1250
+ * rendered into the gate's argv and read the same way (dataArgumentPaths),
1251
+ * and `from: 'options'` only changes which list the refusal names.
1061
1252
  *
1062
1253
  * Only whether something exists on disk at a path the base does not track is
1063
1254
  * read from the working tree; every other answer is a `git ls-tree` listing.
1064
1255
  */
1065
1256
  export function refuseHeadControlledData(repoRoot, trustBase, data) {
1257
+ // Which list of the policy the value came from, for every message below:
1258
+ // an `options:` value is rendered into the same argv and vetted the same
1259
+ // way (audit 2026-11-01, MB1).
1260
+ const list = data.from === 'options' ? "the gate's options:" : "the gate's args:";
1066
1261
  const repoReal = realOrNull(repoRoot);
1067
1262
  if (repoReal === null) {
1068
- return `the repository root ${repoRoot} could not be resolved, so the files named in the gate's args: could not be checked against "${trustBase}". Nothing was checked by this gate.`;
1263
+ return `the repository root ${repoRoot} could not be resolved, so the files named in ${list} could not be checked against "${trustBase}". Nothing was checked by this gate.`;
1069
1264
  }
1070
1265
  const dataPath = data.path;
1071
- const spellings = [withResolvedParent(dataPath), realOrNull(dataPath)].filter((spelling) => spelling !== null);
1266
+ // The written spelling beside the resolved ones (audit 2026-11-01, MB2).
1267
+ const written = writtenRelative(repoReal, dataPath);
1268
+ const spellings = [
1269
+ withResolvedParent(dataPath),
1270
+ realOrNull(dataPath),
1271
+ written === null ? null : path.join(repoReal, written),
1272
+ ].filter((spelling) => spelling !== null);
1072
1273
  const baseName = trustBase === '' ? 'the base' : `"${trustBase}"`;
1274
+ if (written !== null && written !== '') {
1275
+ const subject = `the path ${written} named in ${list}`;
1276
+ const link = linkOnWrittenPathAtHead(repoRoot, written);
1277
+ if (link !== null) {
1278
+ return linkOnWrittenPathRefusal(subject, link, baseName);
1279
+ }
1280
+ // A positional directory the base tracks is a scan target and is not
1281
+ // compared below, so its own entry is asked here: a link there hands the
1282
+ // gate wherever the head points it, possibly the root, instead of the
1283
+ // target the base named. Every other own-entry link (a file, an option
1284
+ // value) is refused below, in the words of its kind.
1285
+ if (data.positional) {
1286
+ const own = listOne(repoRoot, 'HEAD', written);
1287
+ const approved = treeEntryAt(repoRoot, trustBase, written);
1288
+ if (own.kind === 'entry' && own.mode === '120000' && approved.kind === 'entry' && approved.type === 'tree') {
1289
+ return linkOnWrittenPathRefusal(subject, written, baseName);
1290
+ }
1291
+ }
1292
+ }
1073
1293
  if (spellings.some((spelling) => path.relative(repoReal, spelling) === '')) {
1074
1294
  if (data.positional) {
1075
- return null;
1295
+ // A scan target that IS the root is accepted, so the disk check that
1296
+ // otherwise runs last runs here first: a link on disk the head tree
1297
+ // does not declare can fold a positional onto the root (review R1).
1298
+ const undeclared = written === null || written === '' ? null : undeclaredLinkOnDisk(repoRoot, repoReal, written);
1299
+ return undeclared === null ? null : undeclaredLinkRefusal(`the path ${written} named in ${list}`, undeclared);
1076
1300
  }
1077
1301
  // The entry as written, never the absolute checkout path, which would
1078
1302
  // reach the pull-request comment and SARIF; and the remedy for the common
1079
1303
  // case, a scan target written after a flag, first (re-review R1).
1080
- return (`the gate's args: give the repository root (${data.entry ?? '.'}) as an option's value, so ` +
1304
+ return (`${list} give the repository root (${data.entry ?? '.'}) as an option's value, so ` +
1081
1305
  `the whole working tree would be data the gate reads, and this pull request differs from ` +
1082
1306
  `${baseName} somewhere in it. If it is the scan target written after a flag, move it before ` +
1083
1307
  'the flags, where it reads as a positional; otherwise give that option a directory of its ' +
@@ -1095,7 +1319,7 @@ export function refuseHeadControlledData(repoRoot, trustBase, data) {
1095
1319
  const headEntry = treeEntryAt(repoRoot, 'HEAD', relative);
1096
1320
  for (const listed of [baseEntry, headEntry]) {
1097
1321
  if (listed.kind === 'error') {
1098
- return (`the file ${relative} named in the gate's args: could not be checked against ${baseName}: ` +
1322
+ return (`the file ${relative} named in ${list} could not be checked against ${baseName}: ` +
1099
1323
  `${listed.detail}. Nothing was checked by this gate.`);
1100
1324
  }
1101
1325
  }
@@ -1106,7 +1330,7 @@ export function refuseHeadControlledData(repoRoot, trustBase, data) {
1106
1330
  // Names nothing at either side: a word, not a path.
1107
1331
  continue;
1108
1332
  }
1109
- return (`the file ${relative} named in the gate's args: is not tracked at ${baseName} and the head ` +
1333
+ return (`the file ${relative} named in ${list} is not tracked at ${baseName} and the head ` +
1110
1334
  'commit both, so the gate would read a path this pull request chose. Commit it on the base ' +
1111
1335
  'branch first, or name a file outside the repository. Nothing was checked by this gate.');
1112
1336
  }
@@ -1116,7 +1340,7 @@ export function refuseHeadControlledData(repoRoot, trustBase, data) {
1116
1340
  continue;
1117
1341
  }
1118
1342
  if (head === null || head.type !== 'tree' || head.sha !== base.sha) {
1119
- return (`the directory ${relative} named in the gate's args: is not what ${baseName} approved: ` +
1343
+ return (`the directory ${relative} named in ${list} is not what ${baseName} approved: ` +
1120
1344
  'this pull request adds, removes or changes something in it, and it is given as an ' +
1121
1345
  "option's value, so the gate reads it as data, such as a rules directory " +
1122
1346
  '(dep-guard --corpus-dir). Land the change on the base branch first. If it is a scan ' +
@@ -1126,16 +1350,23 @@ export function refuseHeadControlledData(repoRoot, trustBase, data) {
1126
1350
  continue;
1127
1351
  }
1128
1352
  if (head === null || !isRegularFileMode(base.mode) || !isRegularFileMode(head.mode)) {
1129
- return (`the file ${relative} named in the gate's args: is not a regular file at both ${baseName} ` +
1353
+ return (`the file ${relative} named in ${list} is not a regular file at both ${baseName} ` +
1130
1354
  'and the head commit, so what the gate would read is decided by something other than the ' +
1131
1355
  'approved bytes. Name the file itself. Nothing was checked by this gate.');
1132
1356
  }
1133
1357
  if (base.sha !== head.sha) {
1134
- return (`the file ${relative} named in the gate's args: is not the one ${baseName} approved: this ` +
1358
+ return (`the file ${relative} named in ${list} is not the one ${baseName} approved: this ` +
1135
1359
  'pull request changes it, and the gate reads it, so running the gate would let the pull ' +
1136
1360
  'request choose the rules that judge it. Land the change on the base branch first. ' +
1137
1361
  'Nothing was checked by this gate.');
1138
1362
  }
1139
1363
  }
1364
+ // LAST, the disk against the tree (review of the 2026-11-01 fix, item 1).
1365
+ if (written !== null && written !== '') {
1366
+ const undeclared = undeclaredLinkOnDisk(repoRoot, repoReal, written);
1367
+ if (undeclared !== null) {
1368
+ return undeclaredLinkRefusal(`the path ${written} named in ${list}`, undeclared);
1369
+ }
1370
+ }
1140
1371
  return null;
1141
1372
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vaultcompass/conductor",
3
- "version": "0.16.0",
3
+ "version": "0.17.0",
4
4
  "type": "module",
5
5
  "description": "Umbrella installer and combined report over the independently installable guardrail gates.",
6
6
  "keywords": [