rungate 0.2.1 → 0.4.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.
Files changed (129) hide show
  1. package/bin/rungate.ts +70 -0
  2. package/lib/aes-calculator.ts +66 -0
  3. package/lib/agent-audit.ts +139 -0
  4. package/lib/agent-brief-validation.ts +359 -0
  5. package/lib/agents-md-refs.ts +90 -0
  6. package/lib/bash-file-read.ts +197 -0
  7. package/lib/behavioral-cache.ts +78 -0
  8. package/lib/branch-cleanup.ts +234 -0
  9. package/lib/brief-context-parser.ts +35 -0
  10. package/lib/brief-precedence.ts +114 -0
  11. package/lib/canary.ts +117 -0
  12. package/lib/check-registry.ts +226 -0
  13. package/lib/ci-checkout.ts +426 -0
  14. package/lib/cli-commands.ts +137 -0
  15. package/lib/compliance-backfill.ts +232 -0
  16. package/lib/compliance-report.ts +605 -0
  17. package/lib/compliance.ts +361 -0
  18. package/lib/config-loader.ts +255 -0
  19. package/lib/config-readers.ts +86 -0
  20. package/lib/conformity.ts +2161 -137
  21. package/lib/container-provenance.ts +230 -0
  22. package/lib/create-brief.ts +150 -0
  23. package/lib/create-sc.ts +267 -0
  24. package/lib/decomposition-waves.ts +197 -0
  25. package/lib/deep-merge.ts +69 -0
  26. package/lib/dev-liveness.ts +214 -0
  27. package/lib/directive-extractor.ts +210 -0
  28. package/lib/distribution-standing.ts +113 -0
  29. package/lib/doc-hygiene.ts +238 -0
  30. package/lib/eval-criteria.ts +6 -0
  31. package/lib/evidence-portability.ts +123 -0
  32. package/lib/evidence-prevalidator.ts +390 -0
  33. package/lib/evidence-required.ts +150 -0
  34. package/lib/evidence-satisfiability.ts +288 -0
  35. package/lib/frontmatter.ts +163 -0
  36. package/lib/gap-scanner.ts +348 -0
  37. package/lib/gate-check-audit.ts +190 -0
  38. package/lib/gate-enforcement.ts +366 -0
  39. package/lib/generators/agent-briefs.ts +136 -0
  40. package/lib/generators/agents-md.ts +511 -0
  41. package/lib/generators/code-map.ts +60 -0
  42. package/lib/generators/types.ts +184 -0
  43. package/lib/git-ref-normalizer.ts +107 -0
  44. package/lib/github.ts +539 -0
  45. package/lib/harness-identity.ts +63 -0
  46. package/lib/hill-climb.ts +164 -0
  47. package/lib/instruction-effectiveness.ts +131 -0
  48. package/lib/issue-closure-audit.ts +225 -0
  49. package/lib/issue-create-override.ts +343 -0
  50. package/lib/issue-extraction.ts +368 -0
  51. package/lib/js-top-level-code.ts +250 -0
  52. package/lib/liveness-contradiction.ts +149 -0
  53. package/lib/organize.ts +505 -0
  54. package/lib/paths.ts +197 -6
  55. package/lib/phase2-decomposition.ts +270 -0
  56. package/lib/post-fix-verify.ts +157 -0
  57. package/lib/prior-branch.ts +512 -0
  58. package/lib/project-state-shape.ts +166 -0
  59. package/lib/promote-outputs.ts +156 -0
  60. package/lib/prove-label-gate.ts +128 -0
  61. package/lib/reachability.ts +302 -0
  62. package/lib/release-preflight.ts +288 -0
  63. package/lib/rule-health-pipeline.ts +264 -0
  64. package/lib/rule-health-trend.ts +161 -0
  65. package/lib/rule-provenance.ts +149 -0
  66. package/lib/rule-registry.ts +128 -0
  67. package/lib/rungate-schema.ts +127 -5
  68. package/lib/sc-claim-forms.ts +179 -0
  69. package/lib/sc-cover.ts +150 -0
  70. package/lib/sc-guard.ts +157 -0
  71. package/lib/sc-ids.ts +344 -0
  72. package/lib/scaffold/defaults.ts +165 -0
  73. package/lib/scaffold/managed-workflow.ts +370 -0
  74. package/lib/scaffold/owned-files.ts +265 -0
  75. package/lib/scaffold/pre-push-hook.ts +165 -0
  76. package/lib/scaffold/steps.ts +2621 -0
  77. package/lib/scanner.ts +701 -0
  78. package/lib/scope-denylist.ts +258 -0
  79. package/lib/screenshot-upload.ts +73 -0
  80. package/lib/secret-patterns.ts +112 -0
  81. package/lib/security-verdict.ts +616 -0
  82. package/lib/signal-phrases.ts +1 -0
  83. package/lib/spec-change-conformity.ts +80 -0
  84. package/lib/spec-files.ts +62 -0
  85. package/lib/spec-registry.ts +133 -0
  86. package/lib/spec-updater.ts +96 -0
  87. package/lib/stale-cleanup.ts +224 -0
  88. package/lib/stale-issue-scanner.ts +36 -0
  89. package/lib/strip-js-comments.ts +269 -0
  90. package/lib/suite-measurement.ts +228 -0
  91. package/lib/task-completion-checks.ts +224 -0
  92. package/lib/test-suite-lock.ts +1136 -0
  93. package/lib/transcript-checker.ts +1140 -0
  94. package/lib/typescript-project.ts +233 -0
  95. package/lib/validators/spec-validators.ts +171 -0
  96. package/lib/verdict-capture.ts +73 -0
  97. package/lib/verified-push.ts +535 -0
  98. package/lib/workflow-security.ts +174 -0
  99. package/lib/worktree-cleanup.ts +432 -0
  100. package/lib/worktree-collect.ts +283 -0
  101. package/lib/worktree-isolation.ts +82 -0
  102. package/lib/worktree-repo.ts +300 -0
  103. package/package.json +27 -3
  104. package/prompts/ac-adversary.md +14 -2
  105. package/prompts/aditi.md +5 -0
  106. package/prompts/blast-radius.md +5 -0
  107. package/prompts/container-verify.md +5 -0
  108. package/prompts/discovery.md +4 -0
  109. package/prompts/environment.md +5 -0
  110. package/prompts/evidence-hierarchy.md +5 -0
  111. package/prompts/evidence-validator.md +11 -0
  112. package/prompts/marcus.md +5 -0
  113. package/prompts/prevention.md +5 -0
  114. package/prompts/prove-reproducer.md +12 -0
  115. package/prompts/quinn-decision-tree.md +5 -0
  116. package/prompts/quinn-ui-brief.md +5 -0
  117. package/prompts/quinn.md +5 -0
  118. package/prompts/rca.md +5 -0
  119. package/prompts/read-before-write.md +4 -0
  120. package/prompts/regression.md +5 -0
  121. package/prompts/serena.md +5 -0
  122. package/scripts/audit-specs.ts +464 -0
  123. package/scripts/convert-spec.ts +293 -0
  124. package/scripts/create-sc.ts +92 -0
  125. package/scripts/create-spec.ts +166 -0
  126. package/scripts/extract-constraints.ts +4 -3
  127. package/scripts/generate-code-map.ts +1 -1
  128. package/scripts/scaffold-project.ts +138 -1426
  129. package/scripts/sync-spec-tests.ts +211 -126
@@ -0,0 +1,113 @@
1
+ /**
2
+ * What `SUCCESS.md` claims about the distributed artifact, and whether it is
3
+ * still true (#366).
4
+ *
5
+ * Every mutation count, gate measurement and standing verdict in `SUCCESS.md`
6
+ * was taken against the working tree at `main`. The published artifact is
7
+ * `rungate@0.2.1`, and `main` is several hundred commits past it. **The
8
+ * evidence base and the installable artifact are different software**, and
9
+ * nothing in the file said so.
10
+ *
11
+ * It matters most where the file is weakest. `SUCCESS.md`'s consumer survey
12
+ * of 2026-10-08 returned a verdict of *not ready* — against code no consumer
13
+ * can obtain. That is the one deliberate attempt to assess claim 5, and it
14
+ * is unattributable to any shippable version. The claim-5 row argues, of the
15
+ * distribution path among others, that *"a path nothing has executed is not
16
+ * a path anyone understands."*
17
+ *
18
+ * `SUCCESS.md` is also the measure for filing issues, reviewing PRs and
19
+ * running audits, so a standing table that silently describes unpublished
20
+ * code hands that gap to every decision routed through it.
21
+ *
22
+ * ## Why two numbers and not one
23
+ *
24
+ * The issue named the vacuous form by name: *"An assertion that merely finds
25
+ * **a** version string in the file is the vacuous form and passes over this
26
+ * defect today."* It also named the mutation that has to turn it red —
27
+ * *"bumping `package.json` without publishing must turn it red"* — and that
28
+ * one is only catchable if the file records BOTH versions. Checking the
29
+ * recorded published version against the registry alone stays green through
30
+ * a version bump, because the bump does not move either of those two values.
31
+ */
32
+ export interface DistributionStanding {
33
+ /** The version the standing measurements were taken against. */
34
+ tree: string;
35
+ /** The version a consumer can actually install. */
36
+ published: string;
37
+ /** The date the line was written, `YYYY-MM-DD`. */
38
+ measured: string;
39
+ }
40
+
41
+ /**
42
+ * The one line in `SUCCESS.md` that records it, in the form the file writes.
43
+ *
44
+ * Anchored to a list item so prose discussing a version cannot be mistaken
45
+ * for the record — the same reason `.claude/rules/claiming-sc-coverage.md`
46
+ * asks for a declaring position. A file is allowed to talk about 0.2.1 in a
47
+ * sentence without that becoming the standing.
48
+ */
49
+ const STANDING_LINE =
50
+ /^-\s+\*\*Distribution standing\s*\((\d{4}-\d{2}-\d{2})\)\*\*\s*—\s*tree `([^`]+)`, published `rungate@([^`]+)`/m;
51
+
52
+ export function parseDistributionStanding(successMd: string): DistributionStanding | null {
53
+ const m = STANDING_LINE.exec(successMd);
54
+ return m ? { measured: m[1], tree: m[2], published: m[3] } : null;
55
+ }
56
+
57
+ /**
58
+ * What the registry says is installable right now.
59
+ *
60
+ * Deliberately not `npm view`: the registry's own JSON endpoint needs no npm
61
+ * CLI on the path and no lockfile, so the check measures the same thing on a
62
+ * laptop and on CI. A failure here THROWS rather than returning a fallback —
63
+ * an unreachable registry is an unmeasured check, and a check that reports
64
+ * "no problems found" when it could not look is the fail-open shape
65
+ * `.claude/rules/checks-must-be-able-to-fail.md` opens with.
66
+ */
67
+ export async function publishedVersion(
68
+ pkg: string,
69
+ fetchImpl: typeof fetch = fetch,
70
+ ): Promise<string> {
71
+ const res = await fetchImpl(`https://registry.npmjs.org/${pkg}/latest`);
72
+ if (!res.ok) throw new Error(`registry returned ${res.status} for ${pkg}`);
73
+ const body = (await res.json()) as { version?: unknown };
74
+ if (typeof body.version !== "string") {
75
+ throw new Error(`registry returned no version for ${pkg}`);
76
+ }
77
+ return body.version;
78
+ }
79
+
80
+ /**
81
+ * The single place that turns the three readings into a list of violations.
82
+ *
83
+ * One exported function on purpose, so there is one binding to mutate. A
84
+ * second comparison of the same facts elsewhere would survive any mutation
85
+ * of this one and the guard would go green for a reason unrelated to it
86
+ * working.
87
+ */
88
+ export function distributionViolations(
89
+ standing: DistributionStanding | null,
90
+ treeVersion: string,
91
+ publishedNow: string,
92
+ ): string[] {
93
+ if (standing === null) {
94
+ return [
95
+ "SUCCESS.md records no distribution standing — every number in it describes " +
96
+ "a tree, and nothing says which tree a consumer can install",
97
+ ];
98
+ }
99
+ const out: string[] = [];
100
+ if (standing.tree !== treeVersion) {
101
+ out.push(
102
+ `SUCCESS.md says its measurements were taken against ${standing.tree}, ` +
103
+ `package.json says the tree is ${treeVersion} — the standing describes code that moved`,
104
+ );
105
+ }
106
+ if (standing.published !== publishedNow) {
107
+ out.push(
108
+ `SUCCESS.md says rungate@${standing.published} is published, the registry says ` +
109
+ `${publishedNow} — the file's account of what a consumer can install is stale`,
110
+ );
111
+ }
112
+ return out;
113
+ }
@@ -0,0 +1,238 @@
1
+ /**
2
+ * Doc Hygiene — content alignment and drift detection.
3
+ *
4
+ * SC-509: exports [runContentAlignment, checkDocHygiene]
5
+ * SC-510: CONTENT-1 dead-reference lint — governs targets resolve to real files
6
+ * SC-511: CONTENT-2 hash-based drift detection — drift-hashes.json manifest
7
+ *
8
+ * Phase 0: infrastructure only — validates specs have governs fields.
9
+ * Phase 1: CONTENT-1 dead-reference lint, CONTENT-2 hash drift.
10
+ *
11
+ * All new checks start as WARN, not FAIL (DEC-005, spec-policies.json Decision #9).
12
+ * No LLM-based detection (DEC-006) — all checks are deterministic.
13
+ *
14
+ * Issue: #24, #35
15
+ */
16
+
17
+ import { existsSync, readFileSync, readdirSync } from 'fs';
18
+ import { join, resolve } from 'path';
19
+ import { createHash } from 'crypto';
20
+ import { getGoverningSpecs, getUngoverned } from './spec-registry';
21
+
22
+ export interface DocHygieneFinding {
23
+ /** Check identifier for signal tracking (e.g. 'GOVERNS-MISSING') */
24
+ checkId: string;
25
+ /** Severity — all new checks start as WARN per DEC-005 */
26
+ level: 'WARN' | 'FAIL';
27
+ /** Affected file path relative to specs/ */
28
+ file: string;
29
+ /** Human-readable description */
30
+ message: string;
31
+ }
32
+
33
+ export interface DocHygieneResult {
34
+ /** True when zero findings */
35
+ pass: boolean;
36
+ /** All findings from content alignment checks */
37
+ findings: DocHygieneFinding[];
38
+ }
39
+
40
+ /**
41
+ * Run content alignment checks against specs in the given root directory.
42
+ *
43
+ * Phase 0 checks:
44
+ * - GOVERNS-MISSING: spec has no governs field or governs is TODO
45
+ *
46
+ * Returns findings as WARN (not FAIL) per DEC-005 promotion policy.
47
+ */
48
+ export function runContentAlignment(root: string): DocHygieneFinding[] {
49
+ const findings: DocHygieneFinding[] = [];
50
+
51
+ // Check for specs without governs field
52
+ const ungoverned = getUngoverned(root);
53
+ for (const file of ungoverned) {
54
+ findings.push({
55
+ checkId: 'GOVERNS-MISSING',
56
+ level: 'WARN',
57
+ file,
58
+ message: `Spec ${file} has no governs field or governs is TODO`,
59
+ });
60
+ }
61
+
62
+ // CONTENT-1: Dead-reference lint — governs targets resolve to real files
63
+ findings.push(...checkDeadReferences(root));
64
+
65
+ return findings;
66
+ }
67
+
68
+ /**
69
+ * Determine if a governs value looks like a file/directory path.
70
+ *
71
+ * Path-like values contain a forward slash (e.g. "lib/scanner.ts", "gates/").
72
+ * Prose descriptions like "Session lifecycle management" are not paths.
73
+ */
74
+ function isPathLike(governs: string): boolean {
75
+ return governs.includes('/');
76
+ }
77
+
78
+ /**
79
+ * CONTENT-1: Dead-reference lint — verify governs targets resolve to real files.
80
+ *
81
+ * For each spec with a governs field containing a path-like value,
82
+ * check that the target exists relative to the project root using
83
+ * resolve and existsSync. Reports WARN per DEC-005.
84
+ */
85
+ export function checkDeadReferences(root: string): DocHygieneFinding[] {
86
+ const findings: DocHygieneFinding[] = [];
87
+ const specs = getGoverningSpecs(root);
88
+
89
+ for (const spec of specs) {
90
+ const governs = spec.governs.trim();
91
+
92
+ // Only validate path-like governs targets
93
+ if (!isPathLike(governs)) continue;
94
+
95
+ const targetPath = resolve(root, governs);
96
+
97
+ if (!existsSync(targetPath)) {
98
+ findings.push({
99
+ checkId: 'CONTENT-1',
100
+ level: 'WARN',
101
+ file: spec.file,
102
+ message: `Spec ${spec.file} governs "${governs}" but target does not resolve to a real file`,
103
+ });
104
+ }
105
+ }
106
+
107
+ return findings;
108
+ }
109
+
110
+ /**
111
+ * Generate a drift-hashes.json manifest for all governed specs.
112
+ *
113
+ * CONTENT-2: Creates a hash manifest mapping spec filenames to their
114
+ * SHA-256 content hashes. Used for drift detection across sessions.
115
+ */
116
+ export function generateDriftHashes(root: string): Record<string, string> {
117
+ const manifest: Record<string, string> = {};
118
+ const specs = getGoverningSpecs(root);
119
+
120
+ for (const spec of specs) {
121
+ const content = readFileSync(spec.path, 'utf-8');
122
+ const hash = createHash('sha256').update(content).digest('hex');
123
+ manifest[spec.file] = hash;
124
+ }
125
+
126
+ return manifest;
127
+ }
128
+
129
+ /**
130
+ * CONTENT-2: Check for hash drift between current specs and a stored manifest.
131
+ *
132
+ * Compares current spec hashes against a previously-generated drift-hashes.json
133
+ * manifest. Reports WARN findings for:
134
+ * - Hash mismatches (spec content changed since manifest was generated)
135
+ * - New specs not present in the manifest
136
+ * - Specs in manifest that no longer exist on disk
137
+ *
138
+ * All findings are WARN per DEC-005 promotion policy.
139
+ */
140
+ export function checkDriftHashes(
141
+ root: string,
142
+ manifest: Record<string, string>,
143
+ ): DocHygieneFinding[] {
144
+ const findings: DocHygieneFinding[] = [];
145
+ const currentHashes = generateDriftHashes(root);
146
+
147
+ // Check current specs against manifest
148
+ for (const [file, hash] of Object.entries(currentHashes)) {
149
+ if (!(file in manifest)) {
150
+ findings.push({
151
+ checkId: 'CONTENT-2',
152
+ level: 'WARN',
153
+ file,
154
+ message: `Spec ${file} is not in the drift-hashes.json manifest — new or untracked`,
155
+ });
156
+ } else if (manifest[file] !== hash) {
157
+ findings.push({
158
+ checkId: 'CONTENT-2',
159
+ level: 'WARN',
160
+ file,
161
+ message: `Spec ${file} has drift — hash mismatch against manifest`,
162
+ });
163
+ }
164
+ }
165
+
166
+ // Check for specs in manifest that no longer exist
167
+ for (const file of Object.keys(manifest)) {
168
+ if (!(file in currentHashes)) {
169
+ findings.push({
170
+ checkId: 'CONTENT-2',
171
+ level: 'WARN',
172
+ file,
173
+ message: `Spec ${file} in drift-hashes.json manifest but no longer exists — drift detected`,
174
+ });
175
+ }
176
+ }
177
+
178
+ return findings;
179
+ }
180
+
181
+ /**
182
+ * SC-514: Get governed specs whose targets overlap with changed files from git diff.
183
+ *
184
+ * Used for fast-exit scoping — if no governed files changed since the last
185
+ * signal, skip the full content alignment check. Accepts a list of changed
186
+ * file paths (from git diff --name-only) and returns only the SpecEntry
187
+ * objects whose governs targets intersect with the changed set.
188
+ *
189
+ * Directory governs targets (e.g. "lib/") match any changed file under
190
+ * that prefix. Prose-style governs are excluded from path matching.
191
+ */
192
+ export function getChangedGoverned(
193
+ root: string,
194
+ changedFiles: string[],
195
+ ): import('./spec-registry').SpecEntry[] {
196
+ const specs = getGoverningSpecs(root);
197
+ const matched: import('./spec-registry').SpecEntry[] = [];
198
+
199
+ for (const spec of specs) {
200
+ const governs = spec.governs.trim();
201
+
202
+ // Skip prose-style governs — only match path-like targets
203
+ if (!isPathLike(governs)) continue;
204
+
205
+ // Check if any changed file matches this governs target
206
+ const isDir = governs.endsWith('/');
207
+ const hit = changedFiles.some(changed => {
208
+ if (isDir) {
209
+ // Directory target: any diff under that prefix counts
210
+ return changed.startsWith(governs);
211
+ }
212
+ // Exact file match
213
+ return changed === governs;
214
+ });
215
+
216
+ if (hit) {
217
+ matched.push(spec);
218
+ }
219
+ }
220
+
221
+ return matched;
222
+ }
223
+
224
+ /**
225
+ * Run the full doc-hygiene check suite and return a pass/fail result.
226
+ *
227
+ * Wraps runContentAlignment with a structured result for gate enforcement.
228
+ * Signal logging metadata (check-id, file, finding-type) is included
229
+ * in each finding for promotion tracking per DEC-012.
230
+ */
231
+ export function checkDocHygiene(root: string): DocHygieneResult {
232
+ const findings = runContentAlignment(root);
233
+
234
+ return {
235
+ pass: findings.length === 0,
236
+ findings,
237
+ };
238
+ }
@@ -0,0 +1,6 @@
1
+ /**
2
+ * Re-export of transcript-checker.ts for backwards compatibility.
3
+ * All role-based evaluation criteria have been merged into transcript-checker.ts
4
+ */
5
+
6
+ export * from "./transcript-checker.js";
@@ -0,0 +1,123 @@
1
+ /**
2
+ * Can this AC's evidence be reproduced anywhere but the machine that wrote it?
3
+ * (#338)
4
+ *
5
+ * `evidence-target-valid` was a gate check that asserted nothing:
6
+ *
7
+ * const paths = harness?.codeCommittedPaths || [];
8
+ * if (paths.length === 0) return; // nothing authors this key
9
+ * const outside = fileRefs.filter(…); // computed and DISCARDED
10
+ * // Informational — outside refs are common (test fixtures, config)
11
+ *
12
+ * Two independent reasons it could not fail, and #315 removed it rather than
13
+ * leave a name in `config/ceremony-profiles.json` reporting coverage it did
14
+ * not provide. #338 is the rebuild, and it required a measurement first.
15
+ *
16
+ * ## The measurement, and what it killed
17
+ *
18
+ * Over the 82 completed runs in `~/.rungate` — 456 ACs, 452 with an evidence
19
+ * command, 593 file references between them:
20
+ *
21
+ * test 309 52.1%
22
+ * source 156 26.3%
23
+ * other 74 12.5%
24
+ * spec / config 34 5.8%
25
+ * docs / artifacts 20 3.4%
26
+ *
27
+ * Checked against each AC's own declared `contextFiles`: **264 inside, 278
28
+ * outside**, 51 with no context declared. The largest outside category is
29
+ * `test`, 158 of the 278 — which is not a defect but the normal shape of an
30
+ * AC: the evidence command runs the test that proves it, and the test file is
31
+ * not among the source files the AC is *about*.
32
+ *
33
+ * So "evidence commands target files within scope" is not a property real
34
+ * runs have. Any threshold near zero would be red on every run and switched
35
+ * off within a week, which is exactly what #338 said would happen if the rule
36
+ * were invented rather than measured. **The check cannot be rebuilt under its
37
+ * original name, and this says so rather than shipping a weaker version of
38
+ * it.**
39
+ *
40
+ * ## What the measurement did find
41
+ *
42
+ * 50 of 452 evidence commands — **11.1%, across 11 of 82 runs** — contain an
43
+ * absolute path into a developer's home directory. 55 of the 56 references
44
+ * point at the harness checkout itself and 1 at a consumer's; the per-root
45
+ * breakdown is in `specs/GATE-CONTRACTS-SPEC.md`, because SC-A1 of
46
+ * `specs/bootstrap-data-flow/success-criteria.md` says the harness must not
47
+ * name one of its consumers in its own source.
48
+ *
49
+ * Those commands cannot run in CI or on anyone else's machine. Evidence that
50
+ * only reproduces where it was written is not evidence, and this is the gate
51
+ * whose job is to say so.
52
+ *
53
+ * The rate is the reason this is the right threshold: ~1 run in 7. A check
54
+ * that fires on everything gets disabled; a check that fires on nothing is
55
+ * the one being replaced.
56
+ *
57
+ * ## Why zero tolerance here is not the mistake above
58
+ *
59
+ * Because the correct form already exists and costs one token. Evidence
60
+ * commands run with `cwd: projectRoot` (`lib/evidence-prevalidator.ts:208`),
61
+ * so the project's own files need no prefix at all, and the harness root has
62
+ * had `$HARNESS_ROOT` since `gates/run-gate.ts` — which is what all 55 of
63
+ * those references spell out longhand.
64
+ */
65
+
66
+ export interface EvidenceAc {
67
+ id?: unknown;
68
+ evidenceMethod?: { type?: unknown; command?: unknown } | null;
69
+ }
70
+
71
+ /**
72
+ * A path rooted in somebody's home directory.
73
+ *
74
+ * `/Users/<name>/…` and `/home/<name>/…` only. Not every absolute path:
75
+ * `/tmp` is reproducible by construction and 9 commands use it legitimately,
76
+ * and `/usr/bin/env` is not a machine-specific reference. Narrow on purpose
77
+ * — a detector that also flagged those would be arguing with correct
78
+ * commands, and arguing checks get switched off.
79
+ */
80
+ export const MACHINE_PATH = /\/(?:Users|home)\/[A-Za-z0-9_.-]+\/[^\s"'`)]*/g;
81
+
82
+ /** What to write instead, in the order a command should prefer them. */
83
+ export const PORTABLE_FORMS = [
84
+ "a path relative to the project root — evidence commands already run with cwd set to it",
85
+ "$HARNESS_ROOT for a file in the harness, which gates/run-gate.ts resolves",
86
+ ] as const;
87
+
88
+ export function machinePathsIn(command: string): string[] {
89
+ return [...new Set(command.match(MACHINE_PATH) ?? [])];
90
+ }
91
+
92
+ /**
93
+ * The gate's refusal. One exported function, so the mutation is a
94
+ * measurement rather than a claim in a PR (#338 SC-3).
95
+ *
96
+ * Returns [] when nothing was measured — an AC with no command, or a state
97
+ * with no ACs. That is not a fail-open: `all-acs-have-evidence` is the check
98
+ * that refuses a missing command, and duplicating its judgement here would
99
+ * mean two checks disagreeing about one fact.
100
+ */
101
+ export function evidencePortabilityViolations(acs: unknown): string[] {
102
+ if (!Array.isArray(acs)) return [];
103
+ const out: string[] = [];
104
+ for (const raw of acs) {
105
+ const ac = raw as EvidenceAc;
106
+ const command = ac?.evidenceMethod?.command;
107
+ // No `command.trim() === ""` branch: a mutation removing it scored 0 red,
108
+ // because an empty command yields no paths anyway. A branch no input can
109
+ // distinguish is a branch no test can cover, and keeping it would mean
110
+ // one line of this function was permanently unverifiable.
111
+ if (typeof command !== "string") continue;
112
+ const found = machinePathsIn(command);
113
+ if (found.length === 0) continue;
114
+ const id = typeof ac?.id === "string" ? ac.id : "an AC";
115
+ out.push(
116
+ `${id}: the evidence command hardcodes ${found.length === 1 ? "a path" : "paths"} into ` +
117
+ `a developer's home directory — ${found.join(", ")}. It cannot run in CI or on ` +
118
+ `another machine, so the evidence reproduces nowhere but here. Use ` +
119
+ `${PORTABLE_FORMS.join(", or ")}.`,
120
+ );
121
+ }
122
+ return out;
123
+ }