rungate 0.2.1 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (129) hide show
  1. package/bin/rungate.ts +70 -0
  2. package/lib/aes-calculator.ts +66 -0
  3. package/lib/agent-audit.ts +139 -0
  4. package/lib/agent-brief-validation.ts +359 -0
  5. package/lib/agents-md-refs.ts +90 -0
  6. package/lib/bash-file-read.ts +197 -0
  7. package/lib/behavioral-cache.ts +78 -0
  8. package/lib/branch-cleanup.ts +234 -0
  9. package/lib/brief-context-parser.ts +35 -0
  10. package/lib/brief-precedence.ts +114 -0
  11. package/lib/canary.ts +117 -0
  12. package/lib/check-registry.ts +226 -0
  13. package/lib/ci-checkout.ts +426 -0
  14. package/lib/cli-commands.ts +137 -0
  15. package/lib/compliance-backfill.ts +232 -0
  16. package/lib/compliance-report.ts +605 -0
  17. package/lib/compliance.ts +361 -0
  18. package/lib/config-loader.ts +255 -0
  19. package/lib/config-readers.ts +86 -0
  20. package/lib/conformity.ts +2161 -137
  21. package/lib/container-provenance.ts +230 -0
  22. package/lib/create-brief.ts +150 -0
  23. package/lib/create-sc.ts +267 -0
  24. package/lib/decomposition-waves.ts +197 -0
  25. package/lib/deep-merge.ts +69 -0
  26. package/lib/dev-liveness.ts +214 -0
  27. package/lib/directive-extractor.ts +210 -0
  28. package/lib/distribution-standing.ts +113 -0
  29. package/lib/doc-hygiene.ts +238 -0
  30. package/lib/eval-criteria.ts +6 -0
  31. package/lib/evidence-portability.ts +123 -0
  32. package/lib/evidence-prevalidator.ts +390 -0
  33. package/lib/evidence-required.ts +150 -0
  34. package/lib/evidence-satisfiability.ts +288 -0
  35. package/lib/frontmatter.ts +163 -0
  36. package/lib/gap-scanner.ts +348 -0
  37. package/lib/gate-check-audit.ts +190 -0
  38. package/lib/gate-enforcement.ts +366 -0
  39. package/lib/generators/agent-briefs.ts +136 -0
  40. package/lib/generators/agents-md.ts +511 -0
  41. package/lib/generators/code-map.ts +60 -0
  42. package/lib/generators/types.ts +184 -0
  43. package/lib/git-ref-normalizer.ts +107 -0
  44. package/lib/github.ts +539 -0
  45. package/lib/harness-identity.ts +63 -0
  46. package/lib/hill-climb.ts +164 -0
  47. package/lib/instruction-effectiveness.ts +131 -0
  48. package/lib/issue-closure-audit.ts +225 -0
  49. package/lib/issue-create-override.ts +343 -0
  50. package/lib/issue-extraction.ts +368 -0
  51. package/lib/js-top-level-code.ts +250 -0
  52. package/lib/liveness-contradiction.ts +149 -0
  53. package/lib/organize.ts +505 -0
  54. package/lib/paths.ts +197 -6
  55. package/lib/phase2-decomposition.ts +270 -0
  56. package/lib/post-fix-verify.ts +157 -0
  57. package/lib/prior-branch.ts +512 -0
  58. package/lib/project-state-shape.ts +166 -0
  59. package/lib/promote-outputs.ts +156 -0
  60. package/lib/prove-label-gate.ts +128 -0
  61. package/lib/reachability.ts +302 -0
  62. package/lib/release-preflight.ts +288 -0
  63. package/lib/rule-health-pipeline.ts +264 -0
  64. package/lib/rule-health-trend.ts +161 -0
  65. package/lib/rule-provenance.ts +149 -0
  66. package/lib/rule-registry.ts +128 -0
  67. package/lib/rungate-schema.ts +127 -5
  68. package/lib/sc-claim-forms.ts +179 -0
  69. package/lib/sc-cover.ts +150 -0
  70. package/lib/sc-guard.ts +157 -0
  71. package/lib/sc-ids.ts +344 -0
  72. package/lib/scaffold/defaults.ts +165 -0
  73. package/lib/scaffold/managed-workflow.ts +370 -0
  74. package/lib/scaffold/owned-files.ts +265 -0
  75. package/lib/scaffold/pre-push-hook.ts +165 -0
  76. package/lib/scaffold/steps.ts +2621 -0
  77. package/lib/scanner.ts +701 -0
  78. package/lib/scope-denylist.ts +258 -0
  79. package/lib/screenshot-upload.ts +73 -0
  80. package/lib/secret-patterns.ts +112 -0
  81. package/lib/security-verdict.ts +616 -0
  82. package/lib/signal-phrases.ts +1 -0
  83. package/lib/spec-change-conformity.ts +80 -0
  84. package/lib/spec-files.ts +62 -0
  85. package/lib/spec-registry.ts +133 -0
  86. package/lib/spec-updater.ts +96 -0
  87. package/lib/stale-cleanup.ts +224 -0
  88. package/lib/stale-issue-scanner.ts +36 -0
  89. package/lib/strip-js-comments.ts +269 -0
  90. package/lib/suite-measurement.ts +228 -0
  91. package/lib/task-completion-checks.ts +224 -0
  92. package/lib/test-suite-lock.ts +1136 -0
  93. package/lib/transcript-checker.ts +1140 -0
  94. package/lib/typescript-project.ts +233 -0
  95. package/lib/validators/spec-validators.ts +171 -0
  96. package/lib/verdict-capture.ts +73 -0
  97. package/lib/verified-push.ts +535 -0
  98. package/lib/workflow-security.ts +174 -0
  99. package/lib/worktree-cleanup.ts +432 -0
  100. package/lib/worktree-collect.ts +283 -0
  101. package/lib/worktree-isolation.ts +82 -0
  102. package/lib/worktree-repo.ts +300 -0
  103. package/package.json +27 -3
  104. package/prompts/ac-adversary.md +14 -2
  105. package/prompts/aditi.md +5 -0
  106. package/prompts/blast-radius.md +5 -0
  107. package/prompts/container-verify.md +5 -0
  108. package/prompts/discovery.md +4 -0
  109. package/prompts/environment.md +5 -0
  110. package/prompts/evidence-hierarchy.md +5 -0
  111. package/prompts/evidence-validator.md +11 -0
  112. package/prompts/marcus.md +5 -0
  113. package/prompts/prevention.md +5 -0
  114. package/prompts/prove-reproducer.md +12 -0
  115. package/prompts/quinn-decision-tree.md +5 -0
  116. package/prompts/quinn-ui-brief.md +5 -0
  117. package/prompts/quinn.md +5 -0
  118. package/prompts/rca.md +5 -0
  119. package/prompts/read-before-write.md +4 -0
  120. package/prompts/regression.md +5 -0
  121. package/prompts/serena.md +5 -0
  122. package/scripts/audit-specs.ts +464 -0
  123. package/scripts/convert-spec.ts +293 -0
  124. package/scripts/create-sc.ts +92 -0
  125. package/scripts/create-spec.ts +166 -0
  126. package/scripts/extract-constraints.ts +4 -3
  127. package/scripts/generate-code-map.ts +1 -1
  128. package/scripts/scaffold-project.ts +138 -1426
  129. package/scripts/sync-spec-tests.ts +211 -126
@@ -0,0 +1,288 @@
1
+ /**
2
+ * Whether a release may be cut, and whether one actually was (#364).
3
+ *
4
+ * `rungate` has been published twice ever — `0.2.0` and `0.2.1`. `main` is
5
+ * 741 commits past the second. A consumer installing from npm receives a
6
+ * harness without any of the gate, collector or claim-audit work that
7
+ * `SUCCESS.md` cites as evidence, which is why #366 made the file say so and
8
+ * why this file exists to stop it drifting again.
9
+ *
10
+ * ## The failure this is built around
11
+ *
12
+ * The issue named it, and it is the shape `.claude/rules/checks-must-be-able-
13
+ * to-fail.md` opens with:
14
+ *
15
+ * > A publish job that exits 0 because npm rejected a duplicate version is
16
+ * > exactly the "could not measure reads as nothing wrong" shape, and it is
17
+ * > the most likely way this fix ships broken.
18
+ *
19
+ * A release pipeline has an unusually quiet way of doing nothing. The publish
20
+ * step can be skipped by an `if:` that stopped matching, swallowed by a
21
+ * `continue-on-error`, or rejected by the registry as a duplicate — and in
22
+ * every case the job is green and the tag exists. Nothing downstream can tell
23
+ * "we shipped 0.2.3" from "we tagged 0.2.3 and shipped nothing".
24
+ *
25
+ * ## Two readings, before and after
26
+ *
27
+ * So the guard is not one check but two, taken at different times, and
28
+ * neither is sufficient alone:
29
+ *
30
+ * - **Preflight** — the tree's version must NOT be on the registry yet. This
31
+ * is what makes a duplicate publish a red run rather than a no-op.
32
+ * - **Postflight** — after the publish step, the registry's `latest` must BE
33
+ * the tree's version. This is what makes a *skipped* publish a red run.
34
+ *
35
+ * Preflight alone passes a pipeline whose publish step never ran. Postflight
36
+ * alone passes a pipeline that republished nothing because the version was
37
+ * already there from last month. The pair is the same "two numbers, not one"
38
+ * argument `lib/distribution-standing.ts` makes about `SUCCESS.md`, applied
39
+ * to the act rather than to the record.
40
+ */
41
+
42
+ /** What the registry currently holds for a package. */
43
+ export interface RegistryState {
44
+ /** Every published version, in no particular order. */
45
+ versions: string[];
46
+ /** The `latest` dist-tag, or `null` for a package that has never shipped. */
47
+ latest: string | null;
48
+ }
49
+
50
+ /**
51
+ * Read the registry.
52
+ *
53
+ * The packument, not `/latest`: "has 0.2.2 ever been published" cannot be
54
+ * answered by a dist-tag, because `latest` moves on and leaves older versions
55
+ * installable behind it. `distributionViolations` asks a different question
56
+ * and is right to use `/latest`; this one needs the whole list.
57
+ *
58
+ * Deliberately not the `npm` CLI — the registry's JSON endpoint needs no npm
59
+ * on the path and no lockfile, so it measures the same thing on a laptop and
60
+ * on CI.
61
+ *
62
+ * A 404 is a real answer: the package has never been published, so every
63
+ * version is available. Any other failure THROWS rather than returning an
64
+ * empty state, because an unreachable registry would otherwise read as "no
65
+ * version conflicts" and wave a duplicate straight through.
66
+ */
67
+ export const NPM_REGISTRY = "https://registry.npmjs.org";
68
+
69
+ export async function registryState(
70
+ pkg: string,
71
+ fetchImpl: typeof fetch = fetch,
72
+ base: string = NPM_REGISTRY,
73
+ ): Promise<RegistryState> {
74
+ const res = await fetchImpl(`${base}/${pkg}`);
75
+ if (res.status === 404) return { versions: [], latest: null };
76
+ if (!res.ok) throw new Error(`registry returned ${res.status} for ${pkg}`);
77
+ const body = (await res.json()) as {
78
+ versions?: Record<string, unknown>;
79
+ "dist-tags"?: { latest?: unknown };
80
+ };
81
+ const versions = body.versions ? Object.keys(body.versions) : [];
82
+ const latest = body["dist-tags"]?.latest;
83
+ return { versions, latest: typeof latest === "string" ? latest : null };
84
+ }
85
+
86
+ /** `1.2.3`, `1.2.3-rc.1`, `1.2.3+build` — npm's shape, not a full semver parser. */
87
+ const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
88
+
89
+ /**
90
+ * Does `version` satisfy a `^x.y.z` range, by npm's rules? (#364)
91
+ *
92
+ * Exists because the scaffold pins consumers to a caret floored at the
93
+ * harness's own minor, and whether that range can ever resolve decided
94
+ * whether a release could be cut at all. A tree carrying an unpublished
95
+ * minor emits a range nothing satisfies — `0.3.0` emits `^0.3.0` while the
96
+ * registry's newest is `0.2.1` — and `release.yml` runs the suite before
97
+ * publishing, so a check wanting the tree's version already on npm cannot
98
+ * pass on the run that would put it there.
99
+ *
100
+ * The caret's 0.x behaviour is the whole point and is the part hand-rolled
101
+ * comparisons get wrong: below 1.0.0 a caret is pinned to the MINOR, not the
102
+ * major, so `^0.3.0` excludes `0.4.0`. Getting that backwards would make
103
+ * this answer `true` for every bump and the guard would certify nothing.
104
+ *
105
+ * Deliberately narrow: `harnessDevDepRange` only ever emits `^x.y.0`, so
106
+ * this handles carets and refuses anything else rather than pretending to be
107
+ * a semver range parser.
108
+ */
109
+ export function satisfiesCaret(version: string, range: string): boolean {
110
+ const r = /^\^(\d+)\.(\d+)\.(\d+)$/.exec(range);
111
+ const v = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(version);
112
+ if (!r || !v) return false;
113
+ const [rMaj, rMin, rPat] = r.slice(1, 4).map(Number);
114
+ const [vMaj, vMin, vPat] = v.slice(1, 4).map(Number);
115
+
116
+ // Lower bound: the version must be at or above the floor.
117
+ const atOrAbove =
118
+ vMaj > rMaj ||
119
+ (vMaj === rMaj && (vMin > rMin || (vMin === rMin && vPat >= rPat)));
120
+ if (!atOrAbove) return false;
121
+
122
+ // Upper bound, and the 0.x special case is the reason this function exists.
123
+ if (rMaj > 0) return vMaj === rMaj;
124
+ if (rMin > 0) return vMaj === 0 && vMin === rMin;
125
+ return vMaj === 0 && vMin === 0 && vPat === rPat;
126
+ }
127
+
128
+ /**
129
+ * The single place that decides whether a release may be cut. `null` allows.
130
+ *
131
+ * One exported function so there is one binding to mutate. `tag` is the git
132
+ * ref the workflow fired on, with any `refs/tags/` prefix already stripped;
133
+ * pass `null` for a run that is not tag-triggered.
134
+ *
135
+ * The tag comparison is here and not left to the workflow because a tag that
136
+ * disagrees with `package.json` publishes the version in `package.json` while
137
+ * every human reads the tag. That is not a release, it is two releases with
138
+ * one set of notes.
139
+ */
140
+ export function preflightRefusal(
141
+ treeVersion: string,
142
+ tag: string | null,
143
+ state: RegistryState,
144
+ ): string | null {
145
+ if (!SEMVER.test(treeVersion)) {
146
+ return `package.json version ${JSON.stringify(treeVersion)} is not a version npm will accept`;
147
+ }
148
+ if (tag !== null && tag !== `v${treeVersion}`) {
149
+ return (
150
+ `tag ${tag} does not name the version being published — package.json says ` +
151
+ `${treeVersion}, so the tag would describe a release that is not the one cut`
152
+ );
153
+ }
154
+ if (state.versions.includes(treeVersion)) {
155
+ return (
156
+ `rungate@${treeVersion} is already on the registry — publishing it again is ` +
157
+ `rejected by npm, and a job that treats that rejection as success reports a ` +
158
+ `release nobody can install. Bump package.json.`
159
+ );
160
+ }
161
+ return null;
162
+ }
163
+
164
+ /**
165
+ * The single place that decides whether a release actually happened. `null`
166
+ * allows.
167
+ *
168
+ * Run AFTER the publish step, against a freshly read registry. This is the
169
+ * half that cannot be satisfied by doing nothing: a skipped, swallowed or
170
+ * silently-failed publish leaves `latest` where it was.
171
+ */
172
+ export function postflightRefusal(treeVersion: string, latestAfter: string | null): string | null {
173
+ if (latestAfter === null) {
174
+ return (
175
+ `the registry has no latest version for rungate after the publish step — ` +
176
+ `the release did not happen, whatever the job's exit code says`
177
+ );
178
+ }
179
+ if (latestAfter !== treeVersion) {
180
+ return (
181
+ `the registry's latest is ${latestAfter}, not the ${treeVersion} this run was ` +
182
+ `cutting — the publish step did not take effect`
183
+ );
184
+ }
185
+ return null;
186
+ }
187
+
188
+ /** What a postflight poll saw, and how hard it had to look (#407). */
189
+ export interface PostflightReading {
190
+ /** The `latest` dist-tag on the final read. */
191
+ latest: string | null;
192
+ /** Reads performed. 1 means the registry had it immediately. */
193
+ attempts: number;
194
+ /** Time spent sleeping between reads, in ms. */
195
+ waitedMs: number;
196
+ /** The refusal, or `null` to allow. */
197
+ refusal: string | null;
198
+ }
199
+
200
+ /** Defaults sized for npm's observed read-after-write lag: up to ~30s. */
201
+ export const POSTFLIGHT_ATTEMPTS = 10;
202
+ export const POSTFLIGHT_DELAY_MS = 3_000;
203
+
204
+ /**
205
+ * Poll the registry until it serves `treeVersion`, or give up and refuse (#407).
206
+ *
207
+ * `v0.3.0` published cleanly and the release job still went red: the
208
+ * postflight read `registry.npmjs.org/rungate` about a second after `npm
209
+ * publish` returned, and that document is CDN-fronted and eventually
210
+ * consistent, so it was still serving `0.2.1`. The publish was fine. The check
211
+ * was wrong.
212
+ *
213
+ * `.claude/rules/checks-must-be-able-to-fail.md` is about checks that cannot
214
+ * fail. This is the inverse and it costs the same thing, because the message
215
+ * is wrong either way — and a red job over a green release is how a gate
216
+ * teaches people to stop reading it.
217
+ *
218
+ * ## The bound is the point
219
+ *
220
+ * Retrying until it goes green would turn this into the defect in the other
221
+ * direction. The loop is bounded, a publish that never lands still refuses,
222
+ * and the refusal says how long it waited — otherwise "it refused" and "it
223
+ * did not wait long enough" are indistinguishable to whoever reads the log.
224
+ *
225
+ * ## Why an intermediate throw retries and the last one does not
226
+ *
227
+ * A transient network error is exactly what polling is for, so a read that
228
+ * throws with attempts remaining is retried. The FINAL one rethrows, because
229
+ * `registryState` throws rather than returning an empty state precisely so
230
+ * that "could not measure" cannot read as "nothing wrong" — and swallowing
231
+ * the last throw here would put that fail-open back.
232
+ *
233
+ * `sleep` is injectable so the exhaustion case can be driven in a test without
234
+ * spending 30 seconds of wall clock on it.
235
+ */
236
+ export async function awaitRegistryServes(
237
+ pkg: string,
238
+ treeVersion: string,
239
+ opts: {
240
+ fetchImpl?: typeof fetch;
241
+ base?: string;
242
+ attempts?: number;
243
+ delayMs?: number;
244
+ sleep?: (ms: number) => Promise<void>;
245
+ } = {},
246
+ ): Promise<PostflightReading> {
247
+ const attempts = opts.attempts ?? POSTFLIGHT_ATTEMPTS;
248
+ const delayMs = opts.delayMs ?? POSTFLIGHT_DELAY_MS;
249
+ // A zero-attempt poll reads nothing and would fall out of the loop with no
250
+ // refusal — a check that never runs, reported as a check that passed.
251
+ if (!Number.isInteger(attempts) || attempts < 1) {
252
+ throw new Error(`postflight needs at least one attempt, got ${opts.attempts}`);
253
+ }
254
+ const sleep = opts.sleep ?? ((ms: number) => new Promise(r => setTimeout(r, ms)));
255
+
256
+ let waitedMs = 0;
257
+ let latest: string | null = null;
258
+ let refusal: string | null = null;
259
+
260
+ for (let attempt = 1; attempt <= attempts; attempt++) {
261
+ const last = attempt === attempts;
262
+ try {
263
+ const state = await registryState(pkg, opts.fetchImpl ?? fetch, opts.base);
264
+ latest = state.latest;
265
+ refusal = postflightRefusal(treeVersion, latest);
266
+ } catch (e) {
267
+ if (last) throw e;
268
+ refusal = `could not read the registry: ${(e as Error).message}`;
269
+ }
270
+
271
+ if (refusal === null) return { latest, attempts: attempt, waitedMs, refusal: null };
272
+ if (last) {
273
+ return {
274
+ latest,
275
+ attempts: attempt,
276
+ waitedMs,
277
+ refusal:
278
+ `${refusal} — read ${attempt} times over ${Math.round(waitedMs / 1000)}s, ` +
279
+ `which is long enough that this is not the registry catching up`,
280
+ };
281
+ }
282
+ await sleep(delayMs);
283
+ waitedMs += delayMs;
284
+ }
285
+
286
+ /* c8 ignore next */
287
+ throw new Error("unreachable: the loop returns on its last attempt");
288
+ }
@@ -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
+ }