rungate 0.3.0 → 0.4.1

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 (49) hide show
  1. package/lib/ac-quality.ts +119 -0
  2. package/lib/brief-precedence.ts +114 -0
  3. package/lib/ci-checkout.ts +27 -1
  4. package/lib/compliance-backfill.ts +16 -4
  5. package/lib/compliance-report.ts +109 -8
  6. package/lib/config-loader.ts +129 -5
  7. package/lib/config-readers.ts +86 -0
  8. package/lib/conformity.ts +520 -27
  9. package/lib/context-docs.ts +182 -0
  10. package/lib/create-brief.ts +22 -17
  11. package/lib/create-sc.ts +55 -33
  12. package/lib/decomposition-waves.ts +197 -0
  13. package/lib/doc-scan-targets.ts +435 -0
  14. package/lib/gate-check-audit.ts +190 -0
  15. package/lib/generators/agents-md.ts +10 -5
  16. package/lib/issue-extraction.ts +368 -0
  17. package/lib/organize.ts +129 -40
  18. package/lib/package-closure.ts +111 -0
  19. package/lib/phase2-decomposition.ts +270 -0
  20. package/lib/prior-branch.ts +24 -1
  21. package/lib/project-aliases.ts +100 -0
  22. package/lib/prove-label-gate.ts +93 -0
  23. package/lib/release-preflight.ts +225 -15
  24. package/lib/rungate-schema.ts +36 -2
  25. package/lib/sc-cover.ts +92 -1
  26. package/lib/sc-ids.ts +151 -0
  27. package/lib/scaffold/pre-push-hook.ts +165 -0
  28. package/lib/scaffold/rehearsal.ts +330 -0
  29. package/lib/scaffold/steps.ts +175 -122
  30. package/lib/scaffold/write-steps.ts +167 -0
  31. package/lib/scope-denylist.ts +258 -0
  32. package/lib/scratch-cleanup.ts +198 -0
  33. package/lib/scratch-roots.ts +94 -0
  34. package/lib/task-completion-checks.ts +50 -3
  35. package/lib/typescript-project.ts +233 -0
  36. package/lib/validators/spec-validators.ts +23 -34
  37. package/lib/verified-push.ts +179 -2
  38. package/lib/workflow-security.ts +51 -7
  39. package/lib/worktree-cleanup.ts +318 -20
  40. package/lib/worktree-repo.ts +465 -0
  41. package/package.json +8 -2
  42. package/scripts/audit-specs.ts +134 -37
  43. package/scripts/audit-transcript.ts +259 -0
  44. package/scripts/create-sc.ts +15 -1
  45. package/scripts/detect-sc-drift.ts +200 -0
  46. package/scripts/extract-constraints.ts +16 -36
  47. package/scripts/scaffold-project.ts +26 -136
  48. package/scripts/split-spec.ts +315 -0
  49. package/scripts/sync-sc-status.ts +751 -0
@@ -0,0 +1,119 @@
1
+ /**
2
+ * The two AC-quality readings `gates/workflow.test.ts` used to compute inline
3
+ * and then `console.warn` about (#423).
4
+ *
5
+ * #183 audited the ported check list and found four checks that warn without
6
+ * asserting. Two were documented decisions. These two were not: they were
7
+ * `tsc-pass`'s shape — a name promising a verdict over a body that cannot
8
+ * produce one — and they sat in `WARN_TIER_CHECKS` with a reason reading
9
+ * "reported, not fixed".
10
+ *
11
+ * #423 settles them in opposite directions, and the reason they go different
12
+ * ways is the whole point of separating the READING from the VERDICT:
13
+ *
14
+ * - `outcomeEvidenceViolations` now **refuses**. An OUTCOME AC records that a
15
+ * user-visible outcome was observed; a bare number cannot establish one, and
16
+ * `0`, `{}`, `null` and `SKIP` being indistinguishable from success is the
17
+ * *Silent Default Substitution* anti-pattern this repo already names in
18
+ * `.claude/rules/config-access.md`. Its sibling two tests above it,
19
+ * `outcome-acs-no-skip`, has always asserted.
20
+ *
21
+ * - `goalKeywordCoverage` stays a **warning**, and that is now a measured
22
+ * decision rather than a deferral. Measured over the 153 `workflow-state.json`
23
+ * files under `~/.rungate` carrying a goal: **71% of real runs** fall under
24
+ * the 50% threshold, median coverage 38%. Restricting to states whose ACs
25
+ * carry real statements (>80 chars) gives 66% of 131, median 41%; >300 chars
26
+ * gives 73% of 101. The number does not move. A check that would refuse two
27
+ * runs in three is not a gate, it is an outage, and a stopword-filtered
28
+ * substring match over prose is the same basis #409 Decision #9 already
29
+ * rejected for `spec-decision-compliance`.
30
+ *
31
+ * Both are here rather than inline in the gate suite for the reason
32
+ * `.claude/rules/checks-must-be-able-to-fail.md` gives: one exported binding
33
+ * per reading, so there is exactly one thing to mutate and the test can drive
34
+ * both sides of it without a workflow run.
35
+ */
36
+
37
+ /** An AC as the gate suite sees it — untyped on the wire, so read defensively. */
38
+ interface LooseAc {
39
+ id?: unknown;
40
+ type?: unknown;
41
+ verdict?: unknown;
42
+ statement?: unknown;
43
+ evidence?: { content?: unknown } | null;
44
+ }
45
+
46
+ function asAcs(acs: unknown): LooseAc[] {
47
+ return Array.isArray(acs) ? (acs as LooseAc[]) : [];
48
+ }
49
+
50
+ /**
51
+ * Evidence that is a bare measurement — a number and nothing a reader could
52
+ * check.
53
+ *
54
+ * Deliberately wider than the `/^\d+$/` the inline body used. That form read
55
+ * `3` as numeric-only and `3/3`, `12%`, `0.0` and `-1` as behavioural, which
56
+ * is the second shape in `.claude/rules/checks-must-be-able-to-fail.md`: a
57
+ * detector narrower than what it detects, where a reformat of the same
58
+ * non-answer walks straight through. The question is whether the evidence
59
+ * contains a WORD, so that is what is asked.
60
+ */
61
+ export function isBareMeasurement(content: unknown): boolean {
62
+ if (typeof content !== "string") return false;
63
+ const trimmed = content.trim();
64
+ if (trimmed === "") return false; // absence is a different check's question
65
+ return !/[a-z]/i.test(trimmed);
66
+ }
67
+
68
+ /**
69
+ * OUTCOME ACs marked PASS whose evidence is a bare measurement.
70
+ *
71
+ * **Absent evidence is deliberately out of scope.** `all-acs-have-evidence`
72
+ * exempts OUTCOME ACs from mechanical evidence at ship time by design — they
73
+ * are verified live at prove — so reporting absence here would duplicate a
74
+ * decision another check already owns, and two deciders answering one question
75
+ * are behaviourally one (the fourth shape, #420). This one answers: when there
76
+ * IS evidence, does it say anything.
77
+ */
78
+ export function outcomeEvidenceViolations(acs: unknown): string[] {
79
+ return asAcs(acs)
80
+ .filter(ac => ac.type === "OUTCOME" && ac.verdict === "PASS")
81
+ .filter(ac => isBareMeasurement(ac.evidence?.content))
82
+ .map(ac => `${String(ac.id ?? "?")}: evidence is ${JSON.stringify(String(ac.evidence?.content ?? "")).slice(0, 40)}`);
83
+ }
84
+
85
+ /** The words in a goal worth asking about: long enough to mean something. */
86
+ const STOPWORDS = new Set([
87
+ "the", "and", "for", "that", "this", "with", "from", "have", "been",
88
+ "will", "must", "when", "into", "also", "each", "than",
89
+ ]);
90
+
91
+ /** ADR-009 C4's threshold, warned under — never refused. See the file docblock. */
92
+ export const GOAL_COVERAGE_WARN_BELOW = 0.5;
93
+
94
+ export interface GoalCoverage {
95
+ keywords: string[];
96
+ covered: string[];
97
+ coverage: number;
98
+ }
99
+
100
+ /**
101
+ * How much of the issue goal's vocabulary the ACs repeat (ADR-009 C4).
102
+ *
103
+ * `null` when there is nothing to ask — no goal, or a goal of nothing but
104
+ * short words. A caller must not read that as full coverage; it is the
105
+ * difference between measuring zero and not measuring, which is the
106
+ * distinction `.claude/rules/config-access.md` calls out by name.
107
+ */
108
+ export function goalKeywordCoverage(goal: unknown, acs: unknown): GoalCoverage | null {
109
+ if (typeof goal !== "string" || goal.trim() === "") return null;
110
+ const keywords = goal
111
+ .toLowerCase()
112
+ .replace(/[^a-z0-9\s]/g, " ")
113
+ .split(/\s+/)
114
+ .filter(w => w.length > 4 && !STOPWORDS.has(w));
115
+ if (keywords.length === 0) return null;
116
+ const acText = asAcs(acs).map(ac => String(ac.statement ?? "").toLowerCase()).join(" ");
117
+ const covered = keywords.filter(kw => acText.includes(kw));
118
+ return { keywords, covered, coverage: covered.length / keywords.length };
119
+ }
@@ -0,0 +1,114 @@
1
+ /**
2
+ * Which instruction an agent worked from (#180).
3
+ *
4
+ * A ship run launched in the same turn as an unrelated user message gives
5
+ * every agent that message as its task, outranking the brief. The Workflow
6
+ * runtime prepends it — rungate does not write it and cannot remove it:
7
+ *
8
+ * > `[user request]` The harness relays, verbatim and indented below, the user
9
+ * > request that triggered this workflow run. This relayed request is the only
10
+ * > user voice in this task; …
11
+ *
12
+ * ## The run
13
+ *
14
+ * `wf_17267830-401` shipped #178. The relayed text was a status question typed
15
+ * in the parent session — *"What do we still need to do to get the pipeline to
16
+ * ship?"* — and Marcus returned:
17
+ *
18
+ * ```json
19
+ * {"success": true, "filesChanged": [], "testOutput":
20
+ * "No tests run — the relayed user request was a status/priority question, not
21
+ * an implementation task, and the harness framing states the user request
22
+ * wins over the computed task."}
23
+ * ```
24
+ *
25
+ * The agent was not confused. It followed the precedence the framing gave it,
26
+ * and the framing was wrong for this run. `marcus-brief.md` for the same run
27
+ * was correct and complete — 63 lines, five ACs, eight files, a canary. **The
28
+ * brief lost to text it never saw.**
29
+ *
30
+ * ## What changes, and what deliberately does not
31
+ *
32
+ * The relay is NOT removed (#180 AC-3). It is useful when the triggering
33
+ * message *is* about the run — "focus on the API half first" should still
34
+ * reach the agent. Two things change:
35
+ *
36
+ * - **Precedence.** Every briefed prompt now states that the brief's Task and
37
+ * Acceptance Criteria are authoritative and that a relayed request narrows
38
+ * or prioritises them but does not replace them.
39
+ * - **Reportability.** The implement reply carries `taskSource`, so a
40
+ * substitution is a value in the reply rather than a sentence in prose
41
+ * nobody parses. That is #166 applied to which instruction was obeyed:
42
+ * Marcus said what it did only because it chose to narrate it.
43
+ *
44
+ * The notice goes on every briefed role, not a list of implement roles. A
45
+ * hardcoded role name in harness code is the thing `.claude/rules` keeps
46
+ * filing issues about, and the claim is true of every computed brief anyway.
47
+ */
48
+
49
+ /** What an agent may say it worked from. */
50
+ export const TASK_SOURCES = ["brief", "relayed-request", "both"] as const;
51
+ export type TaskSource = (typeof TASK_SOURCES)[number];
52
+
53
+ /**
54
+ * The precedence paragraph appended to every briefed prompt.
55
+ *
56
+ * Written as one exported function so there is a single binding to mutate —
57
+ * a second copy of this wording somewhere else would survive the mutation and
58
+ * the test would go green for the wrong reason.
59
+ */
60
+ export function briefPrecedenceNotice(briefPath: string): string {
61
+ return (
62
+ `TASK PRECEDENCE — the brief is the task. The Task and Acceptance Criteria in ` +
63
+ `${briefPath} and in the prompt below are computed from the issue and are authoritative. ` +
64
+ `A relayed user request from the session that launched this run does NOT replace them: ` +
65
+ `it may narrow or prioritise the work, and if it is about something else entirely it is ` +
66
+ `not your task and you should say so rather than doing it. Run wf_17267830-401 did the ` +
67
+ `other thing — it answered a status question, changed no files and reported success.\n` +
68
+ `Report which you worked from in \`taskSource\`: "brief", "relayed-request", or "both".\n\n`
69
+ );
70
+ }
71
+
72
+ /** Minimal shape of an implement reply, as far as this check is concerned. */
73
+ export interface TaskSourceReading {
74
+ taskSource?: unknown;
75
+ }
76
+
77
+ /**
78
+ * Refuse a reply whose `taskSource` is missing or says the brief was replaced.
79
+ *
80
+ * **Absent is a refusal, not a pass** — the same decision `worktreeRepo` made
81
+ * in #218 and for the same reason: a field the run accepts as missing is a
82
+ * field that stops being written, and then the channel is gone without anyone
83
+ * deciding to remove it.
84
+ *
85
+ * `"both"` passes. The relay narrowing a brief is the case #180 AC-3 keeps
86
+ * working, and an agent that read both and says so is doing exactly what the
87
+ * notice asks.
88
+ */
89
+ export function taskSourceRefusal(result: TaskSourceReading | null | undefined, label: string): string | null {
90
+ const value = result?.taskSource;
91
+ if (value === undefined || value === null || value === "") {
92
+ return (
93
+ `${label} reported no taskSource, so which instruction it worked from is unknown. ` +
94
+ `The schema requires it (#180): an implement reply that cannot say whether it followed ` +
95
+ `the brief or a relayed message from the parent session is the state wf_17267830-401 ` +
96
+ `shipped in, where the substitution was visible only because the agent narrated it.`
97
+ );
98
+ }
99
+ if (typeof value !== "string" || !(TASK_SOURCES as readonly string[]).includes(value)) {
100
+ return (
101
+ `${label} reported taskSource ${JSON.stringify(value)}, which is not one of ` +
102
+ `${TASK_SOURCES.join(", ")}. An unrecognised value is not a verdict.`
103
+ );
104
+ }
105
+ if (value === "relayed-request") {
106
+ return (
107
+ `${label} worked from the relayed user request instead of its brief. The brief carries ` +
108
+ `this issue's acceptance criteria, governing spec, file list and verify commands; the ` +
109
+ `relayed text is whatever was typed in the session that launched the run and is not ` +
110
+ `guaranteed to be about this issue at all (#180).`
111
+ );
112
+ }
113
+ return null;
114
+ }
@@ -193,6 +193,21 @@ export function ciCheckoutPlan(opts: {
193
193
  source: string;
194
194
  dest: string;
195
195
  model: CheckoutModel;
196
+ /**
197
+ * The source repo's own `origin`, restored after the fetches (#183).
198
+ *
199
+ * `actions/checkout@v4` leaves `origin` pointing at the GitHub repository.
200
+ * This plan repoints it at `file://source` so the replayed fetches resolve
201
+ * offline, and before #183 it left it there — so a test asking "what
202
+ * repository is this checkout of" got a filesystem path under the model and
203
+ * `github.com/owner/name` in CI. `test/worktree-repo.test.ts`'s SC-1444
204
+ * positive control failed here for that reason and passed in CI, which is
205
+ * the inversion this whole module exists to prevent.
206
+ *
207
+ * Omit it and `origin` keeps the `file://` URL — a source with no origin
208
+ * has nothing to restore.
209
+ */
210
+ originUrl?: string | null;
196
211
  }): CheckoutCommand[] {
197
212
  const { source, dest, model } = opts;
198
213
  const cmds: CheckoutCommand[] = [];
@@ -227,6 +242,12 @@ export function ciCheckoutPlan(opts: {
227
242
  cmds.push({ kind: "exec", argv, inClone: true, tolerateFailure: true });
228
243
  }
229
244
 
245
+ // Last, and it has to be last: every fetch above needs `file://` to resolve
246
+ // without a network.
247
+ if (opts.originUrl) {
248
+ cmds.push({ kind: "exec", argv: ["git", "remote", "set-url", "origin", opts.originUrl], inClone: true });
249
+ }
250
+
230
251
  return cmds;
231
252
  }
232
253
 
@@ -363,8 +384,13 @@ export function prepareCiCheckout(opts: PrepareOptions): PrepareOutcome {
363
384
  }
364
385
 
365
386
  const dest = `${opts.tmpRoot}/repo`;
387
+ // What the runner's `origin` points at (#183). A source with no origin —
388
+ // a bare init, a consumer's unpushed scaffold — restores nothing, which is
389
+ // also what CI would have.
390
+ const srcOrigin = opts.run(["git", "remote", "get-url", "origin"], opts.source);
391
+ const originUrl = srcOrigin.status === 0 ? srcOrigin.stdout.trim() || null : null;
366
392
  const result = executeCheckoutPlan(
367
- ciCheckoutPlan({ source: opts.source, dest, model }),
393
+ ciCheckoutPlan({ source: opts.source, dest, model, originUrl }),
368
394
  dest,
369
395
  opts.tmpRoot,
370
396
  opts.run,
@@ -33,12 +33,17 @@
33
33
  import { existsSync, readFileSync, readdirSync, statSync } from "fs";
34
34
  import { basename, dirname, join, relative } from "path";
35
35
 
36
- import type { ComplianceEntry } from "./compliance-report";
36
+ import { COMPLIANCE_HISTORY_SCHEMA, type ComplianceEntry } from "./compliance-report";
37
37
 
38
38
  /** A grade file on disk, before it becomes history entries. */
39
39
  interface GradeRule {
40
40
  id?: string;
41
41
  verdict?: string;
42
+ // #116 — these three were on disk the whole time and the backfill dropped
43
+ // them, so a reconstructed entry was as unsourced as a live one.
44
+ rule?: string;
45
+ evidence?: string;
46
+ category?: string;
42
47
  }
43
48
 
44
49
  interface Grade {
@@ -182,9 +187,16 @@ export function planComplianceBackfill(root: string, existing: ComplianceEntry[]
182
187
  timestamp,
183
188
  issue,
184
189
  role: g.role,
185
- scores: Object.fromEntries(
186
- (g.rules ?? []).filter(r => r.id).map(r => [r.id as string, r.verdict || "N/A"]),
187
- ),
190
+ schema: COMPLIANCE_HISTORY_SCHEMA,
191
+ rules: (g.rules ?? [])
192
+ .filter(r => r.id)
193
+ .map(r => ({
194
+ id: r.id as string,
195
+ verdict: r.verdict || "N/A",
196
+ rule: r.rule,
197
+ evidence: r.evidence,
198
+ category: r.category,
199
+ })),
188
200
  total: g.total,
189
201
  followed: g.followed,
190
202
  pct: pct(g),
@@ -1,17 +1,111 @@
1
1
  import { appendFileSync, readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
2
2
  import { dirname, join } from "path";
3
3
 
4
+ /**
5
+ * The history's record shape (#116).
6
+ *
7
+ * **1** — `scores`, a flat `id → verdict` map, and nothing else.
8
+ * **2** — `rules`, the whole record the grader produced.
9
+ *
10
+ * A grade file carries `{ id, rule, verdict, evidence, category }` per rule.
11
+ * The history kept `id → verdict` and dropped the other three, so
12
+ *
13
+ * ```
14
+ * grade: { id: "DIR-L29", verdict: "VIOLATED",
15
+ * rule: "Run the full suite at most TWICE…",
16
+ * evidence: "5 bun test runs (expected 1-2)", category: "quality" }
17
+ * history: { "DIR-L29": "VIOLATED" }
18
+ * ```
19
+ *
20
+ * The second is an unsourced verdict. It cannot be re-checked, the rule text
21
+ * is unrecoverable once the rule is edited, and a trend built from it cannot
22
+ * explain itself — which is tier F by the standard this repo applies to ACs.
23
+ *
24
+ * The lossiness had not bitten only because the writer was never running
25
+ * (#69: the Grade-phase tail ran in a sandbox with no `require` and failed
26
+ * inside a `catch`). All four entries on disk when #116 was filed were
27
+ * synthetic fixtures, which is why the schema was changed then rather than
28
+ * migrated later.
29
+ */
30
+ export const COMPLIANCE_HISTORY_SCHEMA = 2;
31
+
32
+ /** One graded rule, as the grader produced it. */
33
+ export interface ComplianceRuleRecord {
34
+ id: string;
35
+ verdict: string;
36
+ /** The rule's text at grading time — not recoverable later if it is edited. */
37
+ rule?: string;
38
+ /** What the grader saw. Without it the verdict is unsourced. */
39
+ evidence?: string;
40
+ category?: string;
41
+ }
42
+
4
43
  export interface ComplianceEntry {
5
44
  timestamp: string;
6
45
  issue: string;
7
46
  role: string;
8
- scores: Record<string, string>;
47
+ /**
48
+ * Absent means 1. Stamped rather than inferred so a reader can tell "written
49
+ * before the change" from "written after it and carrying nothing".
50
+ */
51
+ schema?: number;
52
+ /** Schema 1 only. New entries do not write it — see `entryVerdicts`. */
53
+ scores?: Record<string, string>;
54
+ /** Schema 2. The full records. */
55
+ rules?: ComplianceRuleRecord[];
9
56
  total: number;
10
57
  followed: number;
11
58
  pct: number;
12
59
  flagged: string[];
13
60
  }
14
61
 
62
+ /** 1 for an unstamped entry, which is what every pre-#116 line is. */
63
+ export function historySchema(entry: ComplianceEntry): number {
64
+ return typeof entry.schema === "number" ? entry.schema : 1;
65
+ }
66
+
67
+ /**
68
+ * `id → verdict`, from whichever shape the entry is in.
69
+ *
70
+ * The single reader, so there is one place that knows both forms (SC-3). A
71
+ * v2 entry does NOT also carry `scores`: two copies of the same fact in one
72
+ * record can disagree, and nothing would notice which was right.
73
+ */
74
+ export function entryVerdicts(entry: ComplianceEntry): Record<string, string> {
75
+ if (Array.isArray(entry.rules)) {
76
+ const out: Record<string, string> = {};
77
+ for (const r of entry.rules) {
78
+ if (r && r.id) out[r.id] = r.verdict || "N/A";
79
+ }
80
+ return out;
81
+ }
82
+ return entry.scores ?? {};
83
+ }
84
+
85
+ /** The records, empty for a v1 entry — which is the point of the version. */
86
+ export function ruleRecords(entry: ComplianceEntry): ComplianceRuleRecord[] {
87
+ return Array.isArray(entry.rules) ? entry.rules : [];
88
+ }
89
+
90
+ /** The rule's recorded text for one id, newest entry first. Null if no entry kept it. */
91
+ export function recordedRuleText(entries: ComplianceEntry[], compId: string): string | null {
92
+ for (let i = entries.length - 1; i >= 0; i--) {
93
+ const hit = ruleRecords(entries[i]!).find(r => r.id === compId && r.rule);
94
+ if (hit?.rule) return hit.rule;
95
+ }
96
+ return null;
97
+ }
98
+
99
+ /** Everything recorded for one id, newest first, so a verdict can be re-checked. */
100
+ export function evidenceFor(entries: ComplianceEntry[], compId: string): ComplianceRuleRecord[] {
101
+ const out: ComplianceRuleRecord[] = [];
102
+ for (let i = entries.length - 1; i >= 0; i--) {
103
+ const hit = ruleRecords(entries[i]!).find(r => r.id === compId);
104
+ if (hit) out.push(hit);
105
+ }
106
+ return out;
107
+ }
108
+
15
109
  export interface TrendLine {
16
110
  compId: string;
17
111
  rule: string;
@@ -88,22 +182,29 @@ export function generateComplianceReport(
88
182
  const window = roleHistory.slice(-TREND_WINDOW);
89
183
  const allPcts = [...window.map((h) => h.pct), current.pct];
90
184
 
185
+ const considered = [...window, current];
186
+ const verdictMaps = new Map(considered.map(e => [e, entryVerdicts(e)]));
187
+
91
188
  const allCompIds = new Set<string>();
92
- for (const entry of [...window, current]) {
93
- for (const id of Object.keys(entry.scores)) allCompIds.add(id);
189
+ for (const entry of considered) {
190
+ for (const id of Object.keys(verdictMaps.get(entry)!)) allCompIds.add(id);
94
191
  }
95
192
 
193
+ // The rule text the grader recorded beats the hardcoded map (#116): the map
194
+ // goes stale the moment a rule is edited, and a v2 entry carries what the
195
+ // rule actually said when the verdict was reached.
196
+ const ruleTextFor = (compId: string) =>
197
+ recordedRuleText(considered, compId) || COMP_RULES[compId] || compId;
198
+
96
199
  const compTrends: TrendLine[] = [];
97
200
  for (const compId of [...allCompIds].sort()) {
98
- const verdicts = [...window, current].map(
99
- (e) => e.scores[compId] || "N/A"
100
- );
201
+ const verdicts = considered.map((e) => verdictMaps.get(e)![compId] || "N/A");
101
202
  const checkable = verdicts.filter((v) => v !== "N/A");
102
203
  const passed = checkable.filter((v) => v === "FOLLOWED").length;
103
204
  const passRate = checkable.length > 0 ? passed / checkable.length : 0;
104
205
 
105
206
  if (checkable.length < 2) {
106
- compTrends.push({ compId, rule: COMP_RULES[compId] || compId, lastN: verdicts, passRate, direction: "stable" });
207
+ compTrends.push({ compId, rule: ruleTextFor(compId), lastN: verdicts, passRate, direction: "stable" });
107
208
  continue;
108
209
  }
109
210
  const firstHalf = checkable.slice(0, Math.ceil(checkable.length / 2));
@@ -122,7 +223,7 @@ export function generateComplianceReport(
122
223
 
123
224
  compTrends.push({
124
225
  compId,
125
- rule: COMP_RULES[compId] || compId,
226
+ rule: ruleTextFor(compId),
126
227
  lastN: verdicts,
127
228
  passRate,
128
229
  direction,
@@ -1,11 +1,20 @@
1
1
  /**
2
- * config-loader.ts — Central config loader for rungate
2
+ * config-loader.ts — the one module that knows where rungate config LIVES
3
3
  *
4
4
  * Reads config from .claude/rungate/ directory (preferred) or
5
5
  * .claude/rungate.json (fallback). Merges directory files into
6
6
  * the same shape as the monolith for backward compatibility.
7
+ *
8
+ * It owns the WRITE side too (#415). ADR-002 D1 is usually quoted as "only
9
+ * this module may read the config", but the thing being centralised is the
10
+ * knowledge of which file a project's config is in, and a writer that answers
11
+ * that question for itself is a second answer to drift from. `create-brief`
12
+ * was the live instance: it built `.claude/rungate.json`, handed it to a
13
+ * writer, and on a project that had followed the documented migration printed
14
+ * "not found — role not registered", naming a file the project is documented
15
+ * not to have. The brief was written and the role was registered nowhere.
7
16
  */
8
- import { existsSync, readFileSync } from "fs";
17
+ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
9
18
  import { join } from "path";
10
19
  import { z } from "zod";
11
20
  import {
@@ -39,6 +48,14 @@ export interface ComplianceConfig {
39
48
  fileTypes: string[];
40
49
  artifactClassification: Record<string, string>;
41
50
  externalSources: OrganizeExternalSource[];
51
+ /**
52
+ * Names a cross-project document may call this project by (#442).
53
+ *
54
+ * Optional: the directory name and the GitHub slug are derived from the
55
+ * tree, so this is only for what a human knows — the abbreviation, the
56
+ * product name, the thing the team says out loud.
57
+ */
58
+ aliases?: string[];
42
59
  };
43
60
  }
44
61
 
@@ -98,7 +115,13 @@ export const DEFAULT_TEST_TIMEOUT = 120000;
98
115
  * Malformed JSON and orphaned fragments THROW, per ADR-001 D2. Unchanged.
99
116
  */
100
117
  export type ConfigResolution =
101
- | { status: "resolved"; config: ResolvedConfig; source: "directory" | "monolith" }
118
+ | {
119
+ status: "resolved";
120
+ config: ResolvedConfig;
121
+ source: "directory" | "monolith";
122
+ /** The directory or file the config was read from (#415). */
123
+ path: string;
124
+ }
102
125
  | { status: "absent" };
103
126
 
104
127
  const DIRECTORY_CONFIG_FILES = ["config.json", "roles.json", "hooks.json", "compliance.json"];
@@ -143,11 +166,21 @@ export function resolveConfig(projectRoot: string): ConfigResolution {
143
166
  // and silently drop issueRepo/ci/test — ADR-001 Step E keeps the monolith
144
167
  // in place during migration, so that state is on the normal upgrade path.
145
168
  if (existsSync(join(dirPath, "config.json"))) {
146
- return { status: "resolved", config: loadFromDirectory(dirPath), source: "directory" };
169
+ return {
170
+ status: "resolved",
171
+ config: loadFromDirectory(dirPath),
172
+ source: "directory",
173
+ path: dirPath,
174
+ };
147
175
  }
148
176
 
149
177
  if (existsSync(monolithPath)) {
150
- return { status: "resolved", config: loadFromMonolith(monolithPath), source: "monolith" };
178
+ return {
179
+ status: "resolved",
180
+ config: loadFromMonolith(monolithPath),
181
+ source: "monolith",
182
+ path: monolithPath,
183
+ };
151
184
  }
152
185
 
153
186
  // Fragments with no config.json and no monolith is a broken directory
@@ -209,6 +242,97 @@ function readJson(path: string): any {
209
242
  return JSON.parse(readFileSync(path, "utf-8"));
210
243
  }
211
244
 
245
+ /**
246
+ * Register a role in whichever layout the project is actually on (#415).
247
+ *
248
+ * The counterpart to `loadRoleConfig`, and deliberately in the same module:
249
+ * the writer has to make the same choice between the two layouts that the
250
+ * reader makes, and a second place making it is how `create-brief` came to
251
+ * write a monolith a migrated consumer does not have.
252
+ *
253
+ * Throws on an unscaffolded project. There is no third branch that invents a
254
+ * layout — a tool that creates `.claude/rungate.json` beside an existing
255
+ * `.claude/rungate/` gives the project two role sets and lets whichever the
256
+ * reader prefers decide what the project is, which is #70 one layer up.
257
+ *
258
+ * Returns the file written, so a caller can say where the role went rather
259
+ * than naming a path it guessed.
260
+ */
261
+ export function writeRoleConfig(
262
+ projectRoot: string,
263
+ roleName: string,
264
+ role: unknown,
265
+ ): string {
266
+ const resolution = resolveConfig(projectRoot);
267
+ if (resolution.status === "absent") {
268
+ throw new Error(
269
+ `No rungate config found under ${join(projectRoot, ".claude")} — ` +
270
+ `scaffold the project before registering a role`,
271
+ );
272
+ }
273
+
274
+ const target =
275
+ resolution.source === "directory"
276
+ ? join(resolution.path, "roles.json")
277
+ : resolution.path;
278
+
279
+ const existing = existsSync(target) ? readJson(target) : {};
280
+ const roles = resolution.source === "directory" ? existing : (existing.roles ??= {});
281
+
282
+ if (roles[roleName]) {
283
+ throw new Error(`Role '${roleName}' already exists in ${target}`);
284
+ }
285
+ roles[roleName] = role;
286
+
287
+ writeFileSync(target, JSON.stringify(existing, null, 2) + "\n");
288
+ return target;
289
+ }
290
+
291
+ /** Whether a scaffold wrote, or stepped aside because something was there. */
292
+ export type ScaffoldWriteResult =
293
+ | { status: "created"; path: string }
294
+ | { status: "exists"; path: string };
295
+
296
+ /**
297
+ * Create a project's config in the DIRECTORY layout (#415).
298
+ *
299
+ * `scripts/scaffold-rungate-config.ts` built these four paths itself, which
300
+ * put two modules in the business of knowing the layout — and left the
301
+ * scaffolder banked in the config-access ratchet at a number no migration
302
+ * could ever lower, because there was no read to migrate.
303
+ *
304
+ * **The "already there" decision lives here and only here.** The script used
305
+ * to make it as well, which made this one unreachable: a mutation that
306
+ * deleted it left the caller's copy still refusing, so the guard measured as
307
+ * load-bearing while nothing depended on it. Two deciders that agree are
308
+ * behaviourally one.
309
+ *
310
+ * Returns rather than throwing, so the caller reports the outcome without
311
+ * having to sniff an exception message for a prefix.
312
+ */
313
+ export function writeScaffoldedConfig(
314
+ projectRoot: string,
315
+ parts: { config: unknown; roles: unknown; hooks: unknown; compliance: unknown },
316
+ ): ScaffoldWriteResult {
317
+ const resolution = resolveConfig(projectRoot);
318
+ if (resolution.status === "resolved") {
319
+ return { status: "exists", path: resolution.path };
320
+ }
321
+
322
+ const dirPath = join(projectRoot, ".claude", "rungate");
323
+ mkdirSync(dirPath, { recursive: true });
324
+ const files: Array<[string, unknown]> = [
325
+ ["config.json", parts.config],
326
+ ["roles.json", parts.roles],
327
+ ["hooks.json", parts.hooks],
328
+ ["compliance.json", parts.compliance],
329
+ ];
330
+ for (const [name, body] of files) {
331
+ writeFileSync(join(dirPath, name), JSON.stringify(body, null, 2) + "\n");
332
+ }
333
+ return { status: "created", path: dirPath };
334
+ }
335
+
212
336
  export function loadComplianceConfig(projectRoot: string): ComplianceConfig | null {
213
337
  const dirPath = join(projectRoot, ".claude", "rungate", "compliance.json");
214
338
  if (existsSync(dirPath)) {