rungate 0.2.1 → 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 +24 -2
- 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
|
@@ -0,0 +1,264 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Rule health pipeline — merges agnix findings with auditor verdicts,
|
|
3
|
+
* generates improvement plans, and rescores after rewrites.
|
|
4
|
+
*
|
|
5
|
+
* Deep module: 3 exports (mergeFindings, generateImprovementPlan, rescoreAfterRewrite),
|
|
6
|
+
* simple interface hiding join logic, factor analysis, and rescore mechanics.
|
|
7
|
+
*
|
|
8
|
+
* AC-2: mergeFindings export
|
|
9
|
+
* AC-3: generateImprovementPlan export
|
|
10
|
+
* AC-4: rescoreAfterRewrite export
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
import { basename } from "path";
|
|
14
|
+
import type { InstructionFinding } from "./compliance.js";
|
|
15
|
+
import type { AgentAuditResult } from "./agent-audit.js";
|
|
16
|
+
import { COMPLIANCE_FACTORS, type ComplianceFactor } from "./hill-climb.js";
|
|
17
|
+
|
|
18
|
+
// ── Types ───────────────────────────────────────────────
|
|
19
|
+
|
|
20
|
+
export interface RuleHealthEntry {
|
|
21
|
+
ruleId: string;
|
|
22
|
+
file: string;
|
|
23
|
+
line: number;
|
|
24
|
+
agnixSeverity: "HIGH" | "MEDIUM" | "LOW" | null;
|
|
25
|
+
agnixMessage: string | null;
|
|
26
|
+
agnixSuggestion: string | null;
|
|
27
|
+
auditVerdict: "FOLLOWED" | "IGNORED" | null;
|
|
28
|
+
auditEvidence: string | null;
|
|
29
|
+
auditWeight: number | null;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
export interface ImprovementRecommendation {
|
|
33
|
+
ruleId: string;
|
|
34
|
+
file: string;
|
|
35
|
+
line: number;
|
|
36
|
+
factors: ComplianceFactor[];
|
|
37
|
+
recommendations: string[];
|
|
38
|
+
priority: "HIGH" | "MEDIUM" | "LOW";
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
export interface ImprovementPlan {
|
|
42
|
+
timestamp: string;
|
|
43
|
+
recommendations: ImprovementRecommendation[];
|
|
44
|
+
totalEntries: number;
|
|
45
|
+
actionableCount: number;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
export interface FileScoreDelta {
|
|
49
|
+
before: number;
|
|
50
|
+
after: number;
|
|
51
|
+
delta: number;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
export interface RescoreDelta {
|
|
55
|
+
timestamp: string;
|
|
56
|
+
files: Record<string, FileScoreDelta>;
|
|
57
|
+
totalDelta: number;
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
// ── AC-2: mergeFindings ─────────────────────────────────
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* Join agnix InstructionFinding array with auditor rule verdicts
|
|
64
|
+
* on matching rule ID, producing unified RuleHealthEntry records.
|
|
65
|
+
*
|
|
66
|
+
* Unmatched agnix findings get null audit fields.
|
|
67
|
+
* Unmatched audit rules get null agnix fields.
|
|
68
|
+
*/
|
|
69
|
+
export function mergeFindings(
|
|
70
|
+
agnixFindings: InstructionFinding[],
|
|
71
|
+
auditRules: AgentAuditResult["rules"],
|
|
72
|
+
): RuleHealthEntry[] {
|
|
73
|
+
const entries: RuleHealthEntry[] = [];
|
|
74
|
+
const matchedAuditIds = new Set<string>();
|
|
75
|
+
|
|
76
|
+
// Match agnix findings to audit rules by rule ID
|
|
77
|
+
for (const finding of agnixFindings) {
|
|
78
|
+
const matchingRule = auditRules.find((r) => r.id === finding.rule);
|
|
79
|
+
if (matchingRule) {
|
|
80
|
+
matchedAuditIds.add(matchingRule.id);
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
entries.push({
|
|
84
|
+
ruleId: finding.rule,
|
|
85
|
+
file: finding.file,
|
|
86
|
+
line: finding.line,
|
|
87
|
+
agnixSeverity: finding.severity,
|
|
88
|
+
agnixMessage: finding.message,
|
|
89
|
+
agnixSuggestion: finding.suggestion,
|
|
90
|
+
auditVerdict: matchingRule?.verdict ?? null,
|
|
91
|
+
auditEvidence: matchingRule?.evidence ?? null,
|
|
92
|
+
auditWeight: matchingRule?.weight ?? null,
|
|
93
|
+
});
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
// Add unmatched audit rules
|
|
97
|
+
for (const rule of auditRules) {
|
|
98
|
+
if (!matchedAuditIds.has(rule.id)) {
|
|
99
|
+
entries.push({
|
|
100
|
+
ruleId: rule.id,
|
|
101
|
+
file: "",
|
|
102
|
+
line: 0,
|
|
103
|
+
agnixSeverity: null,
|
|
104
|
+
agnixMessage: null,
|
|
105
|
+
agnixSuggestion: null,
|
|
106
|
+
auditVerdict: rule.verdict,
|
|
107
|
+
auditEvidence: rule.evidence,
|
|
108
|
+
auditWeight: rule.weight,
|
|
109
|
+
});
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
return entries;
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
// ── AC-3: generateImprovementPlan ───────────────────────
|
|
117
|
+
|
|
118
|
+
/**
|
|
119
|
+
* Read merged findings and produce an improvement plan with per-rule
|
|
120
|
+
* rewrite recommendations using the 7 compliance factors.
|
|
121
|
+
*
|
|
122
|
+
* Only generates recommendations for rules with IGNORED audit verdict
|
|
123
|
+
* or HIGH agnix severity.
|
|
124
|
+
*/
|
|
125
|
+
export function generateImprovementPlan(
|
|
126
|
+
entries: RuleHealthEntry[],
|
|
127
|
+
): ImprovementPlan {
|
|
128
|
+
const recommendations: ImprovementRecommendation[] = [];
|
|
129
|
+
|
|
130
|
+
for (const entry of entries) {
|
|
131
|
+
// Skip rules that are already followed and have no agnix issues
|
|
132
|
+
if (entry.auditVerdict === "FOLLOWED" && entry.agnixSeverity !== "HIGH") {
|
|
133
|
+
continue;
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
const factors: ComplianceFactor[] = [];
|
|
137
|
+
const recs: string[] = [];
|
|
138
|
+
|
|
139
|
+
// Position: rule is too far down in the file
|
|
140
|
+
if (entry.line > 30) {
|
|
141
|
+
factors.push("position");
|
|
142
|
+
recs.push(`Move rule ${entry.ruleId} from L${entry.line} to top section`);
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
// Language: if agnix flagged weak language
|
|
146
|
+
if (entry.agnixMessage?.toLowerCase().includes("vague") ||
|
|
147
|
+
entry.agnixMessage?.toLowerCase().includes("weak") ||
|
|
148
|
+
entry.agnixMessage?.toLowerCase().includes("ambiguous")) {
|
|
149
|
+
factors.push("language");
|
|
150
|
+
recs.push(`Strengthen language: ${entry.agnixSuggestion || "add MUST/MANDATORY"}`);
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
// Specificity: missing specific target
|
|
154
|
+
if (entry.agnixMessage?.toLowerCase().includes("specific") ||
|
|
155
|
+
entry.agnixSuggestion?.toLowerCase().includes("specific")) {
|
|
156
|
+
factors.push("specificity");
|
|
157
|
+
recs.push("Make target more specific with exact file paths");
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
// Section: rule not in a strong section
|
|
161
|
+
if (entry.auditVerdict === "IGNORED") {
|
|
162
|
+
factors.push("section");
|
|
163
|
+
recs.push("Move to Context or Always Do section for higher compliance");
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
// Evidence: no verification command associated
|
|
167
|
+
if (entry.auditVerdict === "IGNORED" && entry.auditWeight && entry.auditWeight >= 10) {
|
|
168
|
+
factors.push("evidence");
|
|
169
|
+
recs.push("Add verification command to make compliance mechanically checkable");
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
// If we still have no factors but the rule is IGNORED, add language as default
|
|
173
|
+
if (factors.length === 0 && entry.auditVerdict === "IGNORED") {
|
|
174
|
+
factors.push("language");
|
|
175
|
+
recs.push("Strengthen language to improve compliance");
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
// Only add HIGH agnix entries that are already FOLLOWED
|
|
179
|
+
if (factors.length === 0 && entry.agnixSeverity === "HIGH") {
|
|
180
|
+
factors.push("language");
|
|
181
|
+
recs.push(`Address HIGH severity finding: ${entry.agnixMessage}`);
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
if (factors.length > 0) {
|
|
185
|
+
const priority = entry.agnixSeverity === "HIGH" || entry.auditVerdict === "IGNORED"
|
|
186
|
+
? (entry.auditWeight && entry.auditWeight >= 15 ? "HIGH" : "MEDIUM")
|
|
187
|
+
: "LOW";
|
|
188
|
+
|
|
189
|
+
recommendations.push({
|
|
190
|
+
ruleId: entry.ruleId,
|
|
191
|
+
file: entry.file,
|
|
192
|
+
line: entry.line,
|
|
193
|
+
factors,
|
|
194
|
+
recommendations: recs,
|
|
195
|
+
priority,
|
|
196
|
+
});
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
return {
|
|
201
|
+
timestamp: new Date().toISOString(),
|
|
202
|
+
recommendations,
|
|
203
|
+
totalEntries: entries.length,
|
|
204
|
+
actionableCount: recommendations.length,
|
|
205
|
+
};
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
// ── AC-4: rescoreAfterRewrite ───────────────────────────
|
|
209
|
+
|
|
210
|
+
/**
|
|
211
|
+
* Re-run agnix on modified files and return a before-after delta object
|
|
212
|
+
* with per-file score changes.
|
|
213
|
+
*
|
|
214
|
+
* Uses simple word-count heuristic when agnix is not available,
|
|
215
|
+
* counting directive keywords (MUST, NEVER, ALWAYS, MANDATORY).
|
|
216
|
+
*/
|
|
217
|
+
export function rescoreAfterRewrite(
|
|
218
|
+
modifiedFiles: string[],
|
|
219
|
+
beforeScores: Record<string, number>,
|
|
220
|
+
): RescoreDelta {
|
|
221
|
+
const files: Record<string, FileScoreDelta> = {};
|
|
222
|
+
let totalDelta = 0;
|
|
223
|
+
|
|
224
|
+
for (const filePath of modifiedFiles) {
|
|
225
|
+
const fileName = basename(filePath);
|
|
226
|
+
const before = beforeScores[fileName] ?? 0;
|
|
227
|
+
|
|
228
|
+
// Try agnix, fall back to heuristic word count
|
|
229
|
+
let after = 0;
|
|
230
|
+
try {
|
|
231
|
+
const result = Bun.spawnSync(["agnix", filePath, "--format", "json"], {
|
|
232
|
+
timeout: 10_000,
|
|
233
|
+
});
|
|
234
|
+
const stdout = result.stdout.toString().trim();
|
|
235
|
+
if (stdout) {
|
|
236
|
+
const parsed = JSON.parse(stdout);
|
|
237
|
+
after = (parsed.diagnostics || []).length;
|
|
238
|
+
}
|
|
239
|
+
} catch {
|
|
240
|
+
// Heuristic fallback: count directive keywords in file
|
|
241
|
+
try {
|
|
242
|
+
const { readFileSync } = require("fs");
|
|
243
|
+
const content = readFileSync(filePath, "utf-8");
|
|
244
|
+
const keywords = ["MUST", "NEVER", "ALWAYS", "MANDATORY", "BEFORE"];
|
|
245
|
+
after = keywords.reduce((count, kw) => {
|
|
246
|
+
const regex = new RegExp(`\\b${kw}\\b`, "gi");
|
|
247
|
+
return count + (content.match(regex) || []).length;
|
|
248
|
+
}, 0);
|
|
249
|
+
} catch {
|
|
250
|
+
after = 0;
|
|
251
|
+
}
|
|
252
|
+
}
|
|
253
|
+
|
|
254
|
+
const delta = after - before;
|
|
255
|
+
files[fileName] = { before, after, delta };
|
|
256
|
+
totalDelta += delta;
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
return {
|
|
260
|
+
timestamp: new Date().toISOString(),
|
|
261
|
+
files,
|
|
262
|
+
totalDelta,
|
|
263
|
+
};
|
|
264
|
+
}
|
|
@@ -0,0 +1,161 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Rule health trend aggregation — reads daily rule-health JSON files
|
|
3
|
+
* and produces trend data with per-rule score trajectories.
|
|
4
|
+
*
|
|
5
|
+
* Deep module: 1 export (aggregateTrend), simple interface hiding
|
|
6
|
+
* file discovery, parsing, and trend classification.
|
|
7
|
+
*
|
|
8
|
+
* AC-6: aggregateTrend export
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
import { existsSync, readdirSync, readFileSync } from "fs";
|
|
12
|
+
import { join } from "path";
|
|
13
|
+
|
|
14
|
+
// ── Types ───────────────────────────────────────────────
|
|
15
|
+
|
|
16
|
+
export type TrendDirection = "improving" | "declining" | "stable";
|
|
17
|
+
|
|
18
|
+
export interface RuleTrajectory {
|
|
19
|
+
scores: number[];
|
|
20
|
+
verdicts: string[];
|
|
21
|
+
trend: TrendDirection;
|
|
22
|
+
latestScore: number;
|
|
23
|
+
delta: number;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
export interface TrendData {
|
|
27
|
+
dates: string[];
|
|
28
|
+
trajectories: Record<string, RuleTrajectory>;
|
|
29
|
+
overallTrend: TrendDirection;
|
|
30
|
+
timestamp: string;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
interface DailyRuleEntry {
|
|
34
|
+
score: number;
|
|
35
|
+
verdict: string;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
interface DailyFile {
|
|
39
|
+
date: string;
|
|
40
|
+
rules: Record<string, DailyRuleEntry>;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
// ── Trend classification ────────────────────────────────
|
|
44
|
+
|
|
45
|
+
const STABLE_THRESHOLD = 5; // Score change <= 5 is considered stable
|
|
46
|
+
|
|
47
|
+
function classifyTrend(scores: number[]): TrendDirection {
|
|
48
|
+
if (scores.length < 2) return "stable";
|
|
49
|
+
|
|
50
|
+
const first = scores[0];
|
|
51
|
+
const last = scores[scores.length - 1];
|
|
52
|
+
const delta = last - first;
|
|
53
|
+
|
|
54
|
+
if (Math.abs(delta) <= STABLE_THRESHOLD) return "stable";
|
|
55
|
+
return delta > 0 ? "improving" : "declining";
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
// ── Public API ──────────────────────────────────────────
|
|
59
|
+
|
|
60
|
+
/**
|
|
61
|
+
* Read daily rule-health JSON files from .rungate/rule-health-history
|
|
62
|
+
* and produce trend data with per-rule score trajectories.
|
|
63
|
+
*
|
|
64
|
+
* Files are named YYYY-MM-DD.json and contain:
|
|
65
|
+
* { date, rules: { ruleId: { score, verdict } } }
|
|
66
|
+
*
|
|
67
|
+
* Returns sorted chronological data with trend classification.
|
|
68
|
+
*/
|
|
69
|
+
export function aggregateTrend(projectRoot: string): TrendData {
|
|
70
|
+
const historyDir = join(projectRoot, ".rungate", "rule-health-history");
|
|
71
|
+
|
|
72
|
+
if (!existsSync(historyDir)) {
|
|
73
|
+
return {
|
|
74
|
+
dates: [],
|
|
75
|
+
trajectories: {},
|
|
76
|
+
overallTrend: "stable",
|
|
77
|
+
timestamp: new Date().toISOString(),
|
|
78
|
+
};
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
// Discover and sort daily files
|
|
82
|
+
const files = readdirSync(historyDir)
|
|
83
|
+
.filter((f) => f.endsWith(".json"))
|
|
84
|
+
.sort(); // YYYY-MM-DD sorts chronologically
|
|
85
|
+
|
|
86
|
+
if (files.length === 0) {
|
|
87
|
+
return {
|
|
88
|
+
dates: [],
|
|
89
|
+
trajectories: {},
|
|
90
|
+
overallTrend: "stable",
|
|
91
|
+
timestamp: new Date().toISOString(),
|
|
92
|
+
};
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
// Parse all daily files
|
|
96
|
+
const dailyData: DailyFile[] = [];
|
|
97
|
+
for (const file of files) {
|
|
98
|
+
try {
|
|
99
|
+
const content = readFileSync(join(historyDir, file), "utf-8");
|
|
100
|
+
const parsed: DailyFile = JSON.parse(content);
|
|
101
|
+
dailyData.push(parsed);
|
|
102
|
+
} catch {
|
|
103
|
+
// Skip malformed files
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
const dates = dailyData.map((d) => d.date);
|
|
108
|
+
|
|
109
|
+
// Build per-rule trajectories
|
|
110
|
+
const ruleIds = new Set<string>();
|
|
111
|
+
for (const daily of dailyData) {
|
|
112
|
+
for (const ruleId of Object.keys(daily.rules)) {
|
|
113
|
+
ruleIds.add(ruleId);
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
const trajectories: Record<string, RuleTrajectory> = {};
|
|
118
|
+
const allDeltas: number[] = [];
|
|
119
|
+
|
|
120
|
+
for (const ruleId of ruleIds) {
|
|
121
|
+
const scores: number[] = [];
|
|
122
|
+
const verdicts: string[] = [];
|
|
123
|
+
|
|
124
|
+
for (const daily of dailyData) {
|
|
125
|
+
const entry = daily.rules[ruleId];
|
|
126
|
+
if (entry) {
|
|
127
|
+
scores.push(entry.score);
|
|
128
|
+
verdicts.push(entry.verdict);
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
const trend = classifyTrend(scores);
|
|
133
|
+
const latestScore = scores[scores.length - 1] ?? 0;
|
|
134
|
+
const delta = scores.length >= 2 ? scores[scores.length - 1] - scores[0] : 0;
|
|
135
|
+
allDeltas.push(delta);
|
|
136
|
+
|
|
137
|
+
trajectories[ruleId] = {
|
|
138
|
+
scores,
|
|
139
|
+
verdicts,
|
|
140
|
+
trend,
|
|
141
|
+
latestScore,
|
|
142
|
+
delta,
|
|
143
|
+
};
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
// Overall trend from average delta
|
|
147
|
+
const avgDelta = allDeltas.length > 0
|
|
148
|
+
? allDeltas.reduce((a, b) => a + b, 0) / allDeltas.length
|
|
149
|
+
: 0;
|
|
150
|
+
|
|
151
|
+
const overallTrend: TrendDirection =
|
|
152
|
+
Math.abs(avgDelta) <= STABLE_THRESHOLD ? "stable" :
|
|
153
|
+
avgDelta > 0 ? "improving" : "declining";
|
|
154
|
+
|
|
155
|
+
return {
|
|
156
|
+
dates,
|
|
157
|
+
trajectories,
|
|
158
|
+
overallTrend,
|
|
159
|
+
timestamp: new Date().toISOString(),
|
|
160
|
+
};
|
|
161
|
+
}
|
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Who owns a `.claude/rules/*.md` file after a human has edited it (#370).
|
|
3
|
+
*
|
|
4
|
+
* `bun bin/rungate.ts scaffold . --fix` on a clean checkout of this repo
|
|
5
|
+
* rewrote eight rule files unconditionally — `writeFileSync` in a loop, no
|
|
6
|
+
* existence check, no comparison — and reported `GENERATED:` for each. On
|
|
7
|
+
* 2026-10-13 that truncated `.claude/rules/checks-must-be-able-to-fail.md`
|
|
8
|
+
* from 262 lines to 65, discarding every worked example and every mutation
|
|
9
|
+
* table in the file the rest of the repo cites more than any other. The run
|
|
10
|
+
* exited 0. `git status` said `M`, not `D`, so the loss did not even look
|
|
11
|
+
* like a deletion.
|
|
12
|
+
*
|
|
13
|
+
* It also reverted `key-files.md`'s `#296` annotation — "DA-owned, never
|
|
14
|
+
* written from an agent worktree" — which exists because run
|
|
15
|
+
* `wf_0b15a933-b2b` lost four worktrees and 2,565 lines of validated work
|
|
16
|
+
* when an agent wrote a DA-owned file.
|
|
17
|
+
*
|
|
18
|
+
* ## Why neither obvious answer works
|
|
19
|
+
*
|
|
20
|
+
* This is the other half of the question #208 asks from the opposite side:
|
|
21
|
+
*
|
|
22
|
+
* - **Never overwrite** (`safeWrite`, the plain `scaffold .` mode) writes
|
|
23
|
+
* nothing, so a generator fix never reaches a tree that already has the
|
|
24
|
+
* file. #363's AGENTS.md fix could not be adopted at all without `--fix`.
|
|
25
|
+
* - **Always overwrite** (`--fix`) is the defect above.
|
|
26
|
+
*
|
|
27
|
+
* Neither can be right, because `key-files.md` is genuinely generated — its
|
|
28
|
+
* table comes from a scan — *and* genuinely hand-annotated.
|
|
29
|
+
*
|
|
30
|
+
* ## The mechanism
|
|
31
|
+
*
|
|
32
|
+
* The generator stamps the sha of the body it wrote into the file's own
|
|
33
|
+
* frontmatter. On the next run the file answers the only question that
|
|
34
|
+
* matters — *has anyone touched this since the harness wrote it?* — without
|
|
35
|
+
* a manifest that can desync from the tree it describes.
|
|
36
|
+
*
|
|
37
|
+
* | existing file | action |
|
|
38
|
+
* |--------------------------------------------|------------|
|
|
39
|
+
* | absent | `create` |
|
|
40
|
+
* | body identical to what would be generated | `update` |
|
|
41
|
+
* | carries a marker matching its own body | `update` |
|
|
42
|
+
* | anything else | `preserve` |
|
|
43
|
+
*
|
|
44
|
+
* The second row is what makes adoption possible without a migration: a file
|
|
45
|
+
* the harness wrote before provenance existed is byte-identical to the
|
|
46
|
+
* generator's output, so the first run recognises it and stamps it. Nothing
|
|
47
|
+
* has to be hand-listed as owned.
|
|
48
|
+
*
|
|
49
|
+
* The last row is deliberately the fallback rather than an enumerated case.
|
|
50
|
+
* An unrecognised file is preserved and REPORTED, never resolved — the
|
|
51
|
+
* direction this is allowed to be wrong in is toward keeping a file the
|
|
52
|
+
* harness could have regenerated, which costs a line in a report. The other
|
|
53
|
+
* direction costs 197 lines of a rule nobody noticed was gone.
|
|
54
|
+
*/
|
|
55
|
+
import { createHash } from "crypto";
|
|
56
|
+
|
|
57
|
+
export type RuleAction = "create" | "update" | "preserve";
|
|
58
|
+
|
|
59
|
+
export interface RuleDecision {
|
|
60
|
+
action: RuleAction;
|
|
61
|
+
/** Why, in the words the scaffold report prints. */
|
|
62
|
+
reason: string;
|
|
63
|
+
/** What to write. Absent exactly when `action` is `preserve`. */
|
|
64
|
+
content?: string;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/** The frontmatter key carrying the sha of the body the harness last wrote. */
|
|
68
|
+
export const PROVENANCE_KEY = "generated-sha";
|
|
69
|
+
|
|
70
|
+
const FRONTMATTER = /^---\n([\s\S]*?)\n---\n/;
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* Everything after the frontmatter block.
|
|
74
|
+
*
|
|
75
|
+
* The sha covers the body alone, and that is load-bearing twice over: the
|
|
76
|
+
* stamp lives in the frontmatter, so hashing the whole file would change the
|
|
77
|
+
* thing being hashed, and `updated:`-style keys move on their own without
|
|
78
|
+
* anybody editing the rule.
|
|
79
|
+
*/
|
|
80
|
+
export function ruleBody(text: string): string {
|
|
81
|
+
// Leading blank lines go too. Without that the sha depends on whether the
|
|
82
|
+
// block was followed by one newline or two — which differs between a file
|
|
83
|
+
// that had frontmatter already and one the stamp just gave some, so the
|
|
84
|
+
// very first stamped file would read as hand-edited on the next run.
|
|
85
|
+
return text.replace(FRONTMATTER, "").replace(/^\n+/, "");
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
export function bodySha(text: string): string {
|
|
89
|
+
return createHash("sha256").update(ruleBody(text)).digest("hex").slice(0, 16);
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/** The sha the file claims the harness wrote, or null if it claims nothing. */
|
|
93
|
+
export function declaredSha(text: string): string | null {
|
|
94
|
+
const fm = FRONTMATTER.exec(text);
|
|
95
|
+
if (!fm) return null;
|
|
96
|
+
const line = new RegExp(`^${PROVENANCE_KEY}:\\s*([0-9a-f]{16})\\s*$`, "m").exec(fm[1]);
|
|
97
|
+
return line ? line[1] : null;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* Put the generated content's own body-sha into its frontmatter.
|
|
102
|
+
*
|
|
103
|
+
* Replaces an existing stamp rather than appending a second one — two
|
|
104
|
+
* `generated-sha` lines would make `declaredSha` read whichever came first
|
|
105
|
+
* and silently stop matching.
|
|
106
|
+
*/
|
|
107
|
+
export function stampProvenance(generated: string): string {
|
|
108
|
+
const sha = bodySha(generated);
|
|
109
|
+
const fm = FRONTMATTER.exec(generated);
|
|
110
|
+
if (!fm) return `---\n${PROVENANCE_KEY}: ${sha}\n---\n\n${generated}`;
|
|
111
|
+
const keys = fm[1]
|
|
112
|
+
.split("\n")
|
|
113
|
+
.filter(l => !new RegExp(`^${PROVENANCE_KEY}:`).test(l));
|
|
114
|
+
const block = `---\n${[...keys, `${PROVENANCE_KEY}: ${sha}`].join("\n")}\n---\n`;
|
|
115
|
+
return generated.replace(FRONTMATTER, block);
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
/**
|
|
119
|
+
* The single place that decides whether a generated rule file may be written.
|
|
120
|
+
*
|
|
121
|
+
* One exported predicate on purpose. A second site deciding the same thing
|
|
122
|
+
* would survive any mutation of this one, and the guard would go green for a
|
|
123
|
+
* reason that has nothing to do with it working —
|
|
124
|
+
* `.claude/rules/checks-must-be-able-to-fail.md`.
|
|
125
|
+
*/
|
|
126
|
+
export function decideRuleWrite(existing: string | null, generated: string): RuleDecision {
|
|
127
|
+
const content = stampProvenance(generated);
|
|
128
|
+
if (existing === null) return { action: "create", reason: "no such file", content };
|
|
129
|
+
|
|
130
|
+
if (bodySha(existing) === bodySha(generated)) {
|
|
131
|
+
// Unchanged from what the generator would write. Writing is a no-op on
|
|
132
|
+
// the body and stamps the marker, which is how a pre-provenance tree
|
|
133
|
+
// adopts the mechanism without anyone listing files by hand.
|
|
134
|
+
return { action: "update", reason: "identical to generator output", content };
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
const declared = declaredSha(existing);
|
|
138
|
+
if (declared !== null && declared === bodySha(existing)) {
|
|
139
|
+
return { action: "update", reason: "harness-written and untouched since", content };
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
return {
|
|
143
|
+
action: "preserve",
|
|
144
|
+
reason:
|
|
145
|
+
declared === null
|
|
146
|
+
? "hand-authored — no harness provenance marker"
|
|
147
|
+
: "hand-edited since the harness wrote it",
|
|
148
|
+
};
|
|
149
|
+
}
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
import { readFileSync } from "fs";
|
|
2
|
+
import { basename, join } from "path";
|
|
3
|
+
|
|
4
|
+
export type RuleTier = "identity" | "reinforcement" | "mechanical";
|
|
5
|
+
type RuleType = "never" | "always" | "read" | "run";
|
|
6
|
+
|
|
7
|
+
export interface Rule {
|
|
8
|
+
id: string;
|
|
9
|
+
text: string;
|
|
10
|
+
type: RuleType;
|
|
11
|
+
tier: RuleTier;
|
|
12
|
+
section: string;
|
|
13
|
+
source: string;
|
|
14
|
+
line: number;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
interface TierMap {
|
|
18
|
+
reinforcement?: string[];
|
|
19
|
+
mechanical?: string[];
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
function parseTierMap(content: string): TierMap {
|
|
23
|
+
const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
|
|
24
|
+
if (!fmMatch) return {};
|
|
25
|
+
const fm = fmMatch[1];
|
|
26
|
+
const tiersMatch = fm.match(/tiers:\n((?:\s+\w+:.*\n?)*)/);
|
|
27
|
+
if (!tiersMatch) return {};
|
|
28
|
+
const result: TierMap = {};
|
|
29
|
+
for (const line of tiersMatch[1].split("\n")) {
|
|
30
|
+
const m = line.match(/^\s+(reinforcement|mechanical):\s*\[([^\]]*)\]/);
|
|
31
|
+
if (m) {
|
|
32
|
+
const key = m[1] as keyof TierMap;
|
|
33
|
+
result[key] = m[2].split(",").map((s) => s.trim().replace(/^['"]|['"]$/g, ""));
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
return result;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
function classifyTier(section: string, tierMap: TierMap): RuleTier {
|
|
40
|
+
const s = section.toLowerCase();
|
|
41
|
+
for (const name of tierMap.reinforcement || []) {
|
|
42
|
+
if (s.startsWith(name.toLowerCase())) return "reinforcement";
|
|
43
|
+
}
|
|
44
|
+
for (const name of tierMap.mechanical || []) {
|
|
45
|
+
if (s.startsWith(name.toLowerCase())) return "mechanical";
|
|
46
|
+
}
|
|
47
|
+
return "identity";
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
export function loadRules(briefPath: string): Rule[] {
|
|
51
|
+
const content = readFileSync(briefPath, "utf-8");
|
|
52
|
+
const tierMap = parseTierMap(content);
|
|
53
|
+
const lines = content.split("\n");
|
|
54
|
+
const rules: Rule[] = [];
|
|
55
|
+
const sourceFile = basename(briefPath);
|
|
56
|
+
let currentSection = "top";
|
|
57
|
+
let ruleCounter = 0;
|
|
58
|
+
|
|
59
|
+
for (let i = 0; i < lines.length; i++) {
|
|
60
|
+
const line = lines[i];
|
|
61
|
+
const lineNum = i + 1;
|
|
62
|
+
|
|
63
|
+
if (line.startsWith("## ")) {
|
|
64
|
+
currentSection = line.replace("## ", "").trim();
|
|
65
|
+
continue;
|
|
66
|
+
}
|
|
67
|
+
if (line.startsWith("//") || line.startsWith("#") || !line.trim()) continue;
|
|
68
|
+
|
|
69
|
+
const sectionLower = currentSection.toLowerCase();
|
|
70
|
+
const trimmedLine = line.trim().replace(/^[-\d.]+\s*/, "");
|
|
71
|
+
let ruleType: RuleType | null = null;
|
|
72
|
+
|
|
73
|
+
if (/^(?:\*{0,2})(?:never|do not|don't)\b/i.test(trimmedLine)) {
|
|
74
|
+
ruleType = "never";
|
|
75
|
+
} else if (
|
|
76
|
+
(sectionLower.includes("never") || sectionLower.includes("additional never")) &&
|
|
77
|
+
line.trim().startsWith("- ")
|
|
78
|
+
) {
|
|
79
|
+
ruleType = "never";
|
|
80
|
+
} else if (sectionLower.includes("always") && line.trim().startsWith("- ")) {
|
|
81
|
+
ruleType = "always";
|
|
82
|
+
} else if (sectionLower.includes("core principles") && line.trim().startsWith("- ")) {
|
|
83
|
+
ruleType = "always";
|
|
84
|
+
} else if (sectionLower === "rules" && line.trim().startsWith("- ")) {
|
|
85
|
+
ruleType = "always";
|
|
86
|
+
} else if (
|
|
87
|
+
/(?:Read|read|Check|check)\s+[`"*]*([^\s`"*]+(?:\.(?:md|ts|json|yml|yaml|js|toml|sh)))[`"*]*/i.test(
|
|
88
|
+
line
|
|
89
|
+
)
|
|
90
|
+
) {
|
|
91
|
+
ruleType = "read";
|
|
92
|
+
} else if (sectionLower.includes("context") && /^\d+\./.test(line.trim())) {
|
|
93
|
+
ruleType = "read";
|
|
94
|
+
} else if (/(?:Run|run)\s+[`]([^`]+)[`]/.test(line)) {
|
|
95
|
+
ruleType = "run";
|
|
96
|
+
} else if (/`(bun test[^`]*)`/.test(line)) {
|
|
97
|
+
ruleType = "run";
|
|
98
|
+
} else if (/`(bunx? tsc[^`]*)`/.test(line)) {
|
|
99
|
+
ruleType = "run";
|
|
100
|
+
} else if (tierMap.mechanical?.includes(currentSection) && /^\d+\./.test(line.trim())) {
|
|
101
|
+
ruleType = "always";
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
if (ruleType) {
|
|
105
|
+
ruleCounter++;
|
|
106
|
+
rules.push({
|
|
107
|
+
id: `${sourceFile.replace(".md", "")}-rule-${ruleCounter}`,
|
|
108
|
+
text: trimmedLine,
|
|
109
|
+
type: ruleType,
|
|
110
|
+
tier: classifyTier(currentSection, tierMap),
|
|
111
|
+
section: currentSection,
|
|
112
|
+
source: sourceFile,
|
|
113
|
+
line: lineNum,
|
|
114
|
+
});
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
return rules;
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
export function getRulesForRole(role: string): Rule[] {
|
|
121
|
+
const projectRoot = join(import.meta.dir, "..");
|
|
122
|
+
const briefPath = join(projectRoot, ".claude/agents", `${role}.md`);
|
|
123
|
+
return loadRules(briefPath);
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
export function getRulesForTier(role: string, tier: RuleTier): Rule[] {
|
|
127
|
+
return getRulesForRole(role).filter((r) => r.tier === tier);
|
|
128
|
+
}
|