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.
Files changed (119) 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 +24 -2
  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
@@ -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
+ }