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.
- package/bin/rungate.ts +70 -0
- package/lib/aes-calculator.ts +66 -0
- package/lib/agent-audit.ts +139 -0
- package/lib/agent-brief-validation.ts +359 -0
- package/lib/agents-md-refs.ts +90 -0
- package/lib/bash-file-read.ts +197 -0
- package/lib/behavioral-cache.ts +78 -0
- package/lib/branch-cleanup.ts +234 -0
- package/lib/brief-context-parser.ts +35 -0
- package/lib/canary.ts +117 -0
- package/lib/check-registry.ts +226 -0
- package/lib/ci-checkout.ts +400 -0
- package/lib/cli-commands.ts +137 -0
- package/lib/compliance-backfill.ts +220 -0
- package/lib/compliance-report.ts +504 -0
- package/lib/compliance.ts +361 -0
- package/lib/config-loader.ts +255 -0
- package/lib/conformity.ts +1818 -131
- package/lib/container-provenance.ts +230 -0
- package/lib/create-brief.ts +150 -0
- package/lib/create-sc.ts +272 -0
- package/lib/deep-merge.ts +69 -0
- package/lib/dev-liveness.ts +214 -0
- package/lib/directive-extractor.ts +210 -0
- package/lib/distribution-standing.ts +113 -0
- package/lib/doc-hygiene.ts +238 -0
- package/lib/eval-criteria.ts +6 -0
- package/lib/evidence-portability.ts +123 -0
- package/lib/evidence-prevalidator.ts +390 -0
- package/lib/evidence-required.ts +150 -0
- package/lib/evidence-satisfiability.ts +288 -0
- package/lib/frontmatter.ts +163 -0
- package/lib/gap-scanner.ts +348 -0
- package/lib/gate-enforcement.ts +366 -0
- package/lib/generators/agent-briefs.ts +136 -0
- package/lib/generators/agents-md.ts +506 -0
- package/lib/generators/code-map.ts +60 -0
- package/lib/generators/types.ts +184 -0
- package/lib/git-ref-normalizer.ts +107 -0
- package/lib/github.ts +539 -0
- package/lib/harness-identity.ts +63 -0
- package/lib/hill-climb.ts +164 -0
- package/lib/instruction-effectiveness.ts +131 -0
- package/lib/issue-closure-audit.ts +225 -0
- package/lib/issue-create-override.ts +343 -0
- package/lib/js-top-level-code.ts +250 -0
- package/lib/liveness-contradiction.ts +149 -0
- package/lib/organize.ts +505 -0
- package/lib/paths.ts +197 -6
- package/lib/post-fix-verify.ts +157 -0
- package/lib/prior-branch.ts +489 -0
- package/lib/project-state-shape.ts +166 -0
- package/lib/promote-outputs.ts +156 -0
- package/lib/prove-label-gate.ts +35 -0
- package/lib/reachability.ts +302 -0
- package/lib/release-preflight.ts +186 -0
- package/lib/rule-health-pipeline.ts +264 -0
- package/lib/rule-health-trend.ts +161 -0
- package/lib/rule-provenance.ts +149 -0
- package/lib/rule-registry.ts +128 -0
- package/lib/rungate-schema.ts +114 -4
- package/lib/sc-claim-forms.ts +179 -0
- package/lib/sc-cover.ts +150 -0
- package/lib/sc-guard.ts +157 -0
- package/lib/sc-ids.ts +344 -0
- package/lib/scaffold/defaults.ts +165 -0
- package/lib/scaffold/managed-workflow.ts +370 -0
- package/lib/scaffold/owned-files.ts +265 -0
- package/lib/scaffold/steps.ts +2680 -0
- package/lib/scanner.ts +701 -0
- package/lib/screenshot-upload.ts +73 -0
- package/lib/secret-patterns.ts +112 -0
- package/lib/security-verdict.ts +616 -0
- package/lib/signal-phrases.ts +1 -0
- package/lib/spec-change-conformity.ts +80 -0
- package/lib/spec-files.ts +62 -0
- package/lib/spec-registry.ts +133 -0
- package/lib/spec-updater.ts +96 -0
- package/lib/stale-cleanup.ts +224 -0
- package/lib/stale-issue-scanner.ts +36 -0
- package/lib/strip-js-comments.ts +269 -0
- package/lib/suite-measurement.ts +228 -0
- package/lib/task-completion-checks.ts +177 -0
- package/lib/test-suite-lock.ts +1136 -0
- package/lib/transcript-checker.ts +1140 -0
- package/lib/validators/spec-validators.ts +171 -0
- package/lib/verdict-capture.ts +73 -0
- package/lib/verified-push.ts +358 -0
- package/lib/workflow-security.ts +174 -0
- package/lib/worktree-cleanup.ts +250 -0
- package/lib/worktree-collect.ts +283 -0
- package/lib/worktree-isolation.ts +82 -0
- package/package.json +36 -3
- package/prompts/ac-adversary.md +14 -2
- package/prompts/aditi.md +5 -0
- package/prompts/blast-radius.md +5 -0
- package/prompts/container-verify.md +5 -0
- package/prompts/discovery.md +4 -0
- package/prompts/environment.md +5 -0
- package/prompts/evidence-hierarchy.md +5 -0
- package/prompts/evidence-validator.md +11 -0
- package/prompts/marcus.md +5 -0
- package/prompts/prevention.md +5 -0
- package/prompts/prove-reproducer.md +12 -0
- package/prompts/quinn-decision-tree.md +5 -0
- package/prompts/quinn-ui-brief.md +5 -0
- package/prompts/quinn.md +5 -0
- package/prompts/rca.md +5 -0
- package/prompts/read-before-write.md +4 -0
- package/prompts/regression.md +5 -0
- package/prompts/serena.md +5 -0
- package/scripts/audit-specs.ts +464 -0
- package/scripts/convert-spec.ts +293 -0
- package/scripts/create-sc.ts +92 -0
- package/scripts/create-spec.ts +166 -0
- package/scripts/extract-constraints.ts +4 -3
- package/scripts/generate-code-map.ts +1 -1
- package/scripts/scaffold-project.ts +138 -1426
- package/scripts/sync-spec-tests.ts +211 -126
- package/.claude/agents/aditi.md +0 -47
- package/.claude/agents/marcus.md +0 -50
- package/.claude/agents/quinn.md +0 -58
- package/.claude/agents/rook.md +0 -47
- package/.claude/agents/serena.md +0 -46
- package/.claude/rungate.json +0 -11
- package/.fallowrc.json +0 -28
- package/.github/copilot-instructions.md +0 -20
- package/.rungate/conformity-findings.json +0 -648
- package/AGENTS.md +0 -106
- package/CODE-MAP.md +0 -50
- package/HARNESS.md +0 -88
- package/bun.lock +0 -26
- package/bunfig.toml +0 -2
- package/config/brief-policies.json +0 -28
- package/config/ceremony-profiles.json +0 -212
- package/config/consumer-cascade-map.json +0 -24
- package/config/doc-cascade-map.json +0 -24
- package/config/eval.json +0 -84
- package/config/profiles/account-plan.yaml +0 -36
- package/config/profiles/campaign.yaml +0 -94
- package/config/prove-evidence.schema.json +0 -65
- package/config/spec-policies.json +0 -36
- package/config/workflow-schema.json +0 -281
- package/gates/SCHEMA-GUIDE.md +0 -121
- package/gates/ac-quality.test.ts +0 -106
- package/gates/adversarial.test.ts +0 -274
- package/gates/brief-assembler.test.ts +0 -429
- package/gates/brief-assembler.ts +0 -334
- package/gates/bunfig.toml +0 -2
- package/gates/chain.test.ts +0 -91
- package/gates/e2e-smoke.test.ts +0 -234
- package/gates/error-classifier.test.ts +0 -249
- package/gates/error-classifier.ts +0 -89
- package/gates/orchestrator.test.ts +0 -950
- package/gates/orchestrator.ts +0 -569
- package/gates/preload.ts +0 -77
- package/gates/prompts/ac-adversary.md +0 -20
- package/gates/prompts/evidence-validator.md +0 -22
- package/gates/prompts/prove-reproducer.md +0 -53
- package/gates/prove.test.ts +0 -164
- package/gates/run-gate.ts +0 -936
- package/gates/schema-parity.test.ts +0 -197
- package/gates/schema.ts +0 -362
- package/gates/self-heal.test.ts +0 -511
- package/gates/self-heal.ts +0 -121
- package/gates/ship-orchestrator.test.ts +0 -379
- package/gates/ship-orchestrator.ts +0 -363
- package/gates/test-fixtures/broken-no-environments.json +0 -60
- package/gates/test-fixtures/valid-standard.json +0 -54
- package/gates/test-utils.ts +0 -43
- package/gates/witness.ts +0 -220
- package/gates/workflow.test.ts +0 -1053
- package/hooks/AgentBriefGuard.hook.ts +0 -586
- package/hooks/AgentVerdictCapture.hook.ts +0 -134
- package/hooks/AutoVerifyGate.hook.ts +0 -76
- package/hooks/GateEnforcement.hook.ts +0 -273
- package/hooks/IssueCloseGuard.hook.ts +0 -116
- package/hooks/MergeGuard.hook.ts +0 -55
- package/hooks/StaleTTLCleanup.hook.ts +0 -133
- package/hooks/VerifyPhaseLock.hook.ts +0 -81
- package/hooks/WorkflowStateGuard.hook.ts +0 -37
- package/hooks/lib/agentDetection.ts +0 -70
- package/hooks/lib/findWorkflow.ts +0 -101
- package/hooks/lib/parseStdin.ts +0 -37
- package/hooks/lib/paths.ts +0 -111
- package/hooks/lib/utils.ts +0 -81
- package/reference/migration-manifest.json +0 -554
- package/reference/prompts/agent-aditi.md +0 -38
- package/reference/prompts/agent-marcus.md +0 -38
- package/reference/prompts/agent-quinn.md +0 -38
- package/reference/prompts/agent-rook.md +0 -37
- package/reference/prompts/agent-serena.md +0 -37
- package/reference/prompts/council-skill.md +0 -170
- package/reference/prompts/goal-skill.md +0 -235
- package/reference/prompts/prove-skill.md +0 -283
- package/reference/prompts/quinn-standard.md +0 -246
- package/reference/prompts/ship-convergence.md +0 -65
- package/reference/prompts/ship-escalation.md +0 -43
- package/reference/prompts/ship-iteration.md +0 -382
- package/reference/prompts/ship-pending-patches.md +0 -246
- package/reference/prompts/ship-reference.md +0 -250
- package/reference/prompts/ship-skill.md +0 -347
- package/reference/prompts/ship-templates.md +0 -215
- package/reference/scripts/batch-status.sh +0 -68
- package/reference/scripts/chain-compat-check.sh +0 -67
- package/reference/scripts/context-audit.sh +0 -314
- package/reference/scripts/dead-export-check.sh +0 -61
- package/reference/scripts/generate-qc-tables.sh +0 -92
- package/reference/scripts/harness-init.sh +0 -111
- package/reference/scripts/pai-054-baseline-check.sh +0 -40
- package/reference/scripts/prove-smoke-test.sh +0 -112
- package/reference/scripts/setup-keychain-salt.sh +0 -12
- package/reference/scripts/skill-optimizer-friday.sh +0 -88
- package/reference/scripts/skill-qc-test.sh +0 -351
- package/reference/scripts/skill-synthesize-tonight.sh +0 -66
- package/reference/specs/HARNESS-EXTRACTION-SPEC.md +0 -263
- package/reference/specs/harness-v3-bash-deletion-plan.md +0 -65
- package/reference/specs/harness-v3-migration-plan.md +0 -188
- package/scripts/decision-reconcile.sh +0 -74
- package/scripts/decision-reconcile.ts +0 -152
- package/scripts/git-hooks/pre-commit +0 -76
- package/scripts/git-hooks/pre-push +0 -271
- package/scripts/harness-skill-check.sh +0 -52
- package/scripts/lib/gap-emit.sh +0 -65
- package/scripts/lib/jq-update.sh +0 -30
- package/scripts/lib/resolve-slug.sh +0 -30
- package/scripts/lib/verify-spec-compliance.sh +0 -102
- package/scripts/prove-backfill.sh +0 -87
- package/scripts/scaffold-rungate-config.ts +0 -91
- package/scripts/self-containment-check.sh +0 -109
- package/scripts/skill-qc-validator.sh +0 -402
- package/scripts/slug-resolver.sh +0 -14
- package/specs/BOOTSTRAP-DATA-FLOW-SPEC.md +0 -2493
- package/specs/BOOTSTRAP-TEST-PLAN.md +0 -571
- package/specs/HARNESS-GATES.md +0 -256
- package/specs/HARNESS-SKILL-CHAIN.md +0 -286
- package/specs/HARNESS-SKILL-CONTRACT.md +0 -93
- package/specs/HARNESS-STANDARD.md +0 -488
- package/specs/SPEC-TEMPLATE.md +0 -53
- package/specs/bootstrap-data-flow.png +0 -0
- package/specs/harness-automation-matrix.md +0 -314
- package/specs/harness-automation-matrix.rules.json +0 -64
- package/test/anti.test.ts +0 -80
- package/test/contract-negative.test.ts +0 -86
- package/test/contract.test.ts +0 -158
- package/test/external-deps.test.ts +0 -48
- package/test/fixtures/golden-project/.env.example +0 -3
- package/test/fixtures/golden-project/Makefile +0 -7
- package/test/fixtures/golden-project/docs/adr/ADR-001-framework.md +0 -23
- package/test/fixtures/golden-project/docs/setup-guide.md +0 -10
- package/test/fixtures/golden-project/package.json +0 -10
- package/test/fixtures/golden-project/specs/api-spec.md +0 -20
- package/test/fixtures/golden-project/src/auth.ts +0 -8
- package/test/fixtures/golden-project/src/db.ts +0 -11
- package/test/fixtures/golden-project/src/index.ts +0 -19
- package/test/fixtures/golden-project/src/utils/format.ts +0 -3
- package/test/fixtures/golden-project/test/auth.test.ts +0 -15
- package/test/fixtures/golden-project/tsconfig.json +0 -12
- package/test/meta-sc-coverage.test.ts +0 -159
- package/test/phase-0.test.ts +0 -846
- package/test/phase-1.test.ts +0 -617
- package/test/phase-2.test.ts +0 -620
- package/test/phase-3.test.ts +0 -99
- package/test/scaffold-conformity.test.ts +0 -8
- package/test/schema-canary.test.ts +0 -51
- package/test/spec-compliance-auto.test.ts +0 -64
- package/test/spec-compliance.test.ts +0 -295
- package/test/spec-discovery.test.ts +0 -68
- package/test/spec-drift.test.ts +0 -5
- package/test/structure.test.ts +0 -165
- package/test/unit/agent-brief-guard-ship.test.ts +0 -293
- package/test/unit/extract-constraints.test.ts +0 -145
- package/test/unit/issue-close-guard.test.ts +0 -204
- package/test/unit/scaffold-project.test.ts +0 -417
- package/test/unit/skill-cooccurrence.test.ts +0 -177
- package/test/unit/skill-sequence-logger.test.ts +0 -244
- package/test/unit/workflow-state-guard.test.ts +0 -95
- package/workflows/batch-ship.js +0 -295
- package/workflows/council.js +0 -481
- package/workflows/prove.js +0 -560
- package/workflows/ship.js +0 -789
- 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,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
|
+
}
|