rungate 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (282) 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/canary.ts +117 -0
  11. package/lib/check-registry.ts +226 -0
  12. package/lib/ci-checkout.ts +400 -0
  13. package/lib/cli-commands.ts +137 -0
  14. package/lib/compliance-backfill.ts +220 -0
  15. package/lib/compliance-report.ts +504 -0
  16. package/lib/compliance.ts +361 -0
  17. package/lib/config-loader.ts +255 -0
  18. package/lib/conformity.ts +1818 -131
  19. package/lib/container-provenance.ts +230 -0
  20. package/lib/create-brief.ts +150 -0
  21. package/lib/create-sc.ts +272 -0
  22. package/lib/deep-merge.ts +69 -0
  23. package/lib/dev-liveness.ts +214 -0
  24. package/lib/directive-extractor.ts +210 -0
  25. package/lib/distribution-standing.ts +113 -0
  26. package/lib/doc-hygiene.ts +238 -0
  27. package/lib/eval-criteria.ts +6 -0
  28. package/lib/evidence-portability.ts +123 -0
  29. package/lib/evidence-prevalidator.ts +390 -0
  30. package/lib/evidence-required.ts +150 -0
  31. package/lib/evidence-satisfiability.ts +288 -0
  32. package/lib/frontmatter.ts +163 -0
  33. package/lib/gap-scanner.ts +348 -0
  34. package/lib/gate-enforcement.ts +366 -0
  35. package/lib/generators/agent-briefs.ts +136 -0
  36. package/lib/generators/agents-md.ts +506 -0
  37. package/lib/generators/code-map.ts +60 -0
  38. package/lib/generators/types.ts +184 -0
  39. package/lib/git-ref-normalizer.ts +107 -0
  40. package/lib/github.ts +539 -0
  41. package/lib/harness-identity.ts +63 -0
  42. package/lib/hill-climb.ts +164 -0
  43. package/lib/instruction-effectiveness.ts +131 -0
  44. package/lib/issue-closure-audit.ts +225 -0
  45. package/lib/issue-create-override.ts +343 -0
  46. package/lib/js-top-level-code.ts +250 -0
  47. package/lib/liveness-contradiction.ts +149 -0
  48. package/lib/organize.ts +505 -0
  49. package/lib/paths.ts +197 -6
  50. package/lib/post-fix-verify.ts +157 -0
  51. package/lib/prior-branch.ts +489 -0
  52. package/lib/project-state-shape.ts +166 -0
  53. package/lib/promote-outputs.ts +156 -0
  54. package/lib/prove-label-gate.ts +35 -0
  55. package/lib/reachability.ts +302 -0
  56. package/lib/release-preflight.ts +186 -0
  57. package/lib/rule-health-pipeline.ts +264 -0
  58. package/lib/rule-health-trend.ts +161 -0
  59. package/lib/rule-provenance.ts +149 -0
  60. package/lib/rule-registry.ts +128 -0
  61. package/lib/rungate-schema.ts +114 -4
  62. package/lib/sc-claim-forms.ts +179 -0
  63. package/lib/sc-cover.ts +150 -0
  64. package/lib/sc-guard.ts +157 -0
  65. package/lib/sc-ids.ts +344 -0
  66. package/lib/scaffold/defaults.ts +165 -0
  67. package/lib/scaffold/managed-workflow.ts +370 -0
  68. package/lib/scaffold/owned-files.ts +265 -0
  69. package/lib/scaffold/steps.ts +2680 -0
  70. package/lib/scanner.ts +701 -0
  71. package/lib/screenshot-upload.ts +73 -0
  72. package/lib/secret-patterns.ts +112 -0
  73. package/lib/security-verdict.ts +616 -0
  74. package/lib/signal-phrases.ts +1 -0
  75. package/lib/spec-change-conformity.ts +80 -0
  76. package/lib/spec-files.ts +62 -0
  77. package/lib/spec-registry.ts +133 -0
  78. package/lib/spec-updater.ts +96 -0
  79. package/lib/stale-cleanup.ts +224 -0
  80. package/lib/stale-issue-scanner.ts +36 -0
  81. package/lib/strip-js-comments.ts +269 -0
  82. package/lib/suite-measurement.ts +228 -0
  83. package/lib/task-completion-checks.ts +177 -0
  84. package/lib/test-suite-lock.ts +1136 -0
  85. package/lib/transcript-checker.ts +1140 -0
  86. package/lib/validators/spec-validators.ts +171 -0
  87. package/lib/verdict-capture.ts +73 -0
  88. package/lib/verified-push.ts +358 -0
  89. package/lib/workflow-security.ts +174 -0
  90. package/lib/worktree-cleanup.ts +250 -0
  91. package/lib/worktree-collect.ts +283 -0
  92. package/lib/worktree-isolation.ts +82 -0
  93. package/package.json +36 -3
  94. package/prompts/ac-adversary.md +14 -2
  95. package/prompts/aditi.md +5 -0
  96. package/prompts/blast-radius.md +5 -0
  97. package/prompts/container-verify.md +5 -0
  98. package/prompts/discovery.md +4 -0
  99. package/prompts/environment.md +5 -0
  100. package/prompts/evidence-hierarchy.md +5 -0
  101. package/prompts/evidence-validator.md +11 -0
  102. package/prompts/marcus.md +5 -0
  103. package/prompts/prevention.md +5 -0
  104. package/prompts/prove-reproducer.md +12 -0
  105. package/prompts/quinn-decision-tree.md +5 -0
  106. package/prompts/quinn-ui-brief.md +5 -0
  107. package/prompts/quinn.md +5 -0
  108. package/prompts/rca.md +5 -0
  109. package/prompts/read-before-write.md +4 -0
  110. package/prompts/regression.md +5 -0
  111. package/prompts/serena.md +5 -0
  112. package/scripts/audit-specs.ts +464 -0
  113. package/scripts/convert-spec.ts +293 -0
  114. package/scripts/create-sc.ts +92 -0
  115. package/scripts/create-spec.ts +166 -0
  116. package/scripts/extract-constraints.ts +4 -3
  117. package/scripts/generate-code-map.ts +1 -1
  118. package/scripts/scaffold-project.ts +138 -1426
  119. package/scripts/sync-spec-tests.ts +211 -126
  120. package/.claude/agents/aditi.md +0 -47
  121. package/.claude/agents/marcus.md +0 -50
  122. package/.claude/agents/quinn.md +0 -58
  123. package/.claude/agents/rook.md +0 -47
  124. package/.claude/agents/serena.md +0 -46
  125. package/.claude/rungate.json +0 -11
  126. package/.fallowrc.json +0 -28
  127. package/.github/copilot-instructions.md +0 -20
  128. package/.rungate/conformity-findings.json +0 -648
  129. package/AGENTS.md +0 -106
  130. package/CODE-MAP.md +0 -50
  131. package/HARNESS.md +0 -88
  132. package/bun.lock +0 -26
  133. package/bunfig.toml +0 -2
  134. package/config/brief-policies.json +0 -28
  135. package/config/ceremony-profiles.json +0 -212
  136. package/config/consumer-cascade-map.json +0 -24
  137. package/config/doc-cascade-map.json +0 -24
  138. package/config/eval.json +0 -84
  139. package/config/profiles/account-plan.yaml +0 -36
  140. package/config/profiles/campaign.yaml +0 -94
  141. package/config/prove-evidence.schema.json +0 -65
  142. package/config/spec-policies.json +0 -36
  143. package/config/workflow-schema.json +0 -281
  144. package/gates/SCHEMA-GUIDE.md +0 -121
  145. package/gates/ac-quality.test.ts +0 -106
  146. package/gates/adversarial.test.ts +0 -274
  147. package/gates/brief-assembler.test.ts +0 -429
  148. package/gates/brief-assembler.ts +0 -334
  149. package/gates/bunfig.toml +0 -2
  150. package/gates/chain.test.ts +0 -91
  151. package/gates/e2e-smoke.test.ts +0 -234
  152. package/gates/error-classifier.test.ts +0 -249
  153. package/gates/error-classifier.ts +0 -89
  154. package/gates/orchestrator.test.ts +0 -950
  155. package/gates/orchestrator.ts +0 -569
  156. package/gates/preload.ts +0 -77
  157. package/gates/prompts/ac-adversary.md +0 -20
  158. package/gates/prompts/evidence-validator.md +0 -22
  159. package/gates/prompts/prove-reproducer.md +0 -53
  160. package/gates/prove.test.ts +0 -164
  161. package/gates/run-gate.ts +0 -936
  162. package/gates/schema-parity.test.ts +0 -197
  163. package/gates/schema.ts +0 -362
  164. package/gates/self-heal.test.ts +0 -511
  165. package/gates/self-heal.ts +0 -121
  166. package/gates/ship-orchestrator.test.ts +0 -379
  167. package/gates/ship-orchestrator.ts +0 -363
  168. package/gates/test-fixtures/broken-no-environments.json +0 -60
  169. package/gates/test-fixtures/valid-standard.json +0 -54
  170. package/gates/test-utils.ts +0 -43
  171. package/gates/witness.ts +0 -220
  172. package/gates/workflow.test.ts +0 -1053
  173. package/hooks/AgentBriefGuard.hook.ts +0 -586
  174. package/hooks/AgentVerdictCapture.hook.ts +0 -134
  175. package/hooks/AutoVerifyGate.hook.ts +0 -76
  176. package/hooks/GateEnforcement.hook.ts +0 -273
  177. package/hooks/IssueCloseGuard.hook.ts +0 -116
  178. package/hooks/MergeGuard.hook.ts +0 -55
  179. package/hooks/StaleTTLCleanup.hook.ts +0 -133
  180. package/hooks/VerifyPhaseLock.hook.ts +0 -81
  181. package/hooks/WorkflowStateGuard.hook.ts +0 -37
  182. package/hooks/lib/agentDetection.ts +0 -70
  183. package/hooks/lib/findWorkflow.ts +0 -101
  184. package/hooks/lib/parseStdin.ts +0 -37
  185. package/hooks/lib/paths.ts +0 -111
  186. package/hooks/lib/utils.ts +0 -81
  187. package/reference/migration-manifest.json +0 -554
  188. package/reference/prompts/agent-aditi.md +0 -38
  189. package/reference/prompts/agent-marcus.md +0 -38
  190. package/reference/prompts/agent-quinn.md +0 -38
  191. package/reference/prompts/agent-rook.md +0 -37
  192. package/reference/prompts/agent-serena.md +0 -37
  193. package/reference/prompts/council-skill.md +0 -170
  194. package/reference/prompts/goal-skill.md +0 -235
  195. package/reference/prompts/prove-skill.md +0 -283
  196. package/reference/prompts/quinn-standard.md +0 -246
  197. package/reference/prompts/ship-convergence.md +0 -65
  198. package/reference/prompts/ship-escalation.md +0 -43
  199. package/reference/prompts/ship-iteration.md +0 -382
  200. package/reference/prompts/ship-pending-patches.md +0 -246
  201. package/reference/prompts/ship-reference.md +0 -250
  202. package/reference/prompts/ship-skill.md +0 -347
  203. package/reference/prompts/ship-templates.md +0 -215
  204. package/reference/scripts/batch-status.sh +0 -68
  205. package/reference/scripts/chain-compat-check.sh +0 -67
  206. package/reference/scripts/context-audit.sh +0 -314
  207. package/reference/scripts/dead-export-check.sh +0 -61
  208. package/reference/scripts/generate-qc-tables.sh +0 -92
  209. package/reference/scripts/harness-init.sh +0 -111
  210. package/reference/scripts/pai-054-baseline-check.sh +0 -40
  211. package/reference/scripts/prove-smoke-test.sh +0 -112
  212. package/reference/scripts/setup-keychain-salt.sh +0 -12
  213. package/reference/scripts/skill-optimizer-friday.sh +0 -88
  214. package/reference/scripts/skill-qc-test.sh +0 -351
  215. package/reference/scripts/skill-synthesize-tonight.sh +0 -66
  216. package/reference/specs/HARNESS-EXTRACTION-SPEC.md +0 -263
  217. package/reference/specs/harness-v3-bash-deletion-plan.md +0 -65
  218. package/reference/specs/harness-v3-migration-plan.md +0 -188
  219. package/scripts/decision-reconcile.sh +0 -74
  220. package/scripts/decision-reconcile.ts +0 -152
  221. package/scripts/git-hooks/pre-commit +0 -76
  222. package/scripts/git-hooks/pre-push +0 -271
  223. package/scripts/harness-skill-check.sh +0 -52
  224. package/scripts/lib/gap-emit.sh +0 -65
  225. package/scripts/lib/jq-update.sh +0 -30
  226. package/scripts/lib/resolve-slug.sh +0 -30
  227. package/scripts/lib/verify-spec-compliance.sh +0 -102
  228. package/scripts/prove-backfill.sh +0 -87
  229. package/scripts/scaffold-rungate-config.ts +0 -91
  230. package/scripts/self-containment-check.sh +0 -109
  231. package/scripts/skill-qc-validator.sh +0 -402
  232. package/scripts/slug-resolver.sh +0 -14
  233. package/specs/BOOTSTRAP-DATA-FLOW-SPEC.md +0 -2493
  234. package/specs/BOOTSTRAP-TEST-PLAN.md +0 -571
  235. package/specs/HARNESS-GATES.md +0 -256
  236. package/specs/HARNESS-SKILL-CHAIN.md +0 -286
  237. package/specs/HARNESS-SKILL-CONTRACT.md +0 -93
  238. package/specs/HARNESS-STANDARD.md +0 -488
  239. package/specs/SPEC-TEMPLATE.md +0 -53
  240. package/specs/bootstrap-data-flow.png +0 -0
  241. package/specs/harness-automation-matrix.md +0 -314
  242. package/specs/harness-automation-matrix.rules.json +0 -64
  243. package/test/anti.test.ts +0 -80
  244. package/test/contract-negative.test.ts +0 -86
  245. package/test/contract.test.ts +0 -158
  246. package/test/external-deps.test.ts +0 -48
  247. package/test/fixtures/golden-project/.env.example +0 -3
  248. package/test/fixtures/golden-project/Makefile +0 -7
  249. package/test/fixtures/golden-project/docs/adr/ADR-001-framework.md +0 -23
  250. package/test/fixtures/golden-project/docs/setup-guide.md +0 -10
  251. package/test/fixtures/golden-project/package.json +0 -10
  252. package/test/fixtures/golden-project/specs/api-spec.md +0 -20
  253. package/test/fixtures/golden-project/src/auth.ts +0 -8
  254. package/test/fixtures/golden-project/src/db.ts +0 -11
  255. package/test/fixtures/golden-project/src/index.ts +0 -19
  256. package/test/fixtures/golden-project/src/utils/format.ts +0 -3
  257. package/test/fixtures/golden-project/test/auth.test.ts +0 -15
  258. package/test/fixtures/golden-project/tsconfig.json +0 -12
  259. package/test/meta-sc-coverage.test.ts +0 -159
  260. package/test/phase-0.test.ts +0 -846
  261. package/test/phase-1.test.ts +0 -617
  262. package/test/phase-2.test.ts +0 -620
  263. package/test/phase-3.test.ts +0 -99
  264. package/test/scaffold-conformity.test.ts +0 -8
  265. package/test/schema-canary.test.ts +0 -51
  266. package/test/spec-compliance-auto.test.ts +0 -64
  267. package/test/spec-compliance.test.ts +0 -295
  268. package/test/spec-discovery.test.ts +0 -68
  269. package/test/spec-drift.test.ts +0 -5
  270. package/test/structure.test.ts +0 -165
  271. package/test/unit/agent-brief-guard-ship.test.ts +0 -293
  272. package/test/unit/extract-constraints.test.ts +0 -145
  273. package/test/unit/issue-close-guard.test.ts +0 -204
  274. package/test/unit/scaffold-project.test.ts +0 -417
  275. package/test/unit/skill-cooccurrence.test.ts +0 -177
  276. package/test/unit/skill-sequence-logger.test.ts +0 -244
  277. package/test/unit/workflow-state-guard.test.ts +0 -95
  278. package/workflows/batch-ship.js +0 -295
  279. package/workflows/council.js +0 -481
  280. package/workflows/prove.js +0 -560
  281. package/workflows/ship.js +0 -789
  282. package/workflows/verify.js +0 -236
@@ -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
+ }