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.
- package/lib/ac-quality.ts +119 -0
- package/lib/brief-precedence.ts +114 -0
- package/lib/ci-checkout.ts +27 -1
- package/lib/compliance-backfill.ts +16 -4
- package/lib/compliance-report.ts +109 -8
- package/lib/config-loader.ts +129 -5
- package/lib/config-readers.ts +86 -0
- package/lib/conformity.ts +520 -27
- package/lib/context-docs.ts +182 -0
- package/lib/create-brief.ts +22 -17
- package/lib/create-sc.ts +55 -33
- package/lib/decomposition-waves.ts +197 -0
- package/lib/doc-scan-targets.ts +435 -0
- package/lib/gate-check-audit.ts +190 -0
- package/lib/generators/agents-md.ts +10 -5
- package/lib/issue-extraction.ts +368 -0
- package/lib/organize.ts +129 -40
- package/lib/package-closure.ts +111 -0
- package/lib/phase2-decomposition.ts +270 -0
- package/lib/prior-branch.ts +24 -1
- package/lib/project-aliases.ts +100 -0
- package/lib/prove-label-gate.ts +93 -0
- package/lib/release-preflight.ts +225 -15
- package/lib/rungate-schema.ts +36 -2
- package/lib/sc-cover.ts +92 -1
- package/lib/sc-ids.ts +151 -0
- package/lib/scaffold/pre-push-hook.ts +165 -0
- package/lib/scaffold/rehearsal.ts +330 -0
- package/lib/scaffold/steps.ts +175 -122
- package/lib/scaffold/write-steps.ts +167 -0
- package/lib/scope-denylist.ts +258 -0
- package/lib/scratch-cleanup.ts +198 -0
- package/lib/scratch-roots.ts +94 -0
- package/lib/task-completion-checks.ts +50 -3
- package/lib/typescript-project.ts +233 -0
- package/lib/validators/spec-validators.ts +23 -34
- package/lib/verified-push.ts +179 -2
- package/lib/workflow-security.ts +51 -7
- package/lib/worktree-cleanup.ts +318 -20
- package/lib/worktree-repo.ts +465 -0
- package/package.json +8 -2
- package/scripts/audit-specs.ts +134 -37
- package/scripts/audit-transcript.ts +259 -0
- package/scripts/create-sc.ts +15 -1
- package/scripts/detect-sc-drift.ts +200 -0
- package/scripts/extract-constraints.ts +16 -36
- package/scripts/scaffold-project.ts +26 -136
- package/scripts/split-spec.ts +315 -0
- 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
|
+
}
|
package/lib/ci-checkout.ts
CHANGED
|
@@ -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
|
|
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
|
-
|
|
186
|
-
|
|
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),
|
package/lib/compliance-report.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
|
93
|
-
for (const id of Object.keys(entry
|
|
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 =
|
|
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:
|
|
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:
|
|
226
|
+
rule: ruleTextFor(compId),
|
|
126
227
|
lastN: verdicts,
|
|
127
228
|
passRate,
|
|
128
229
|
direction,
|
package/lib/config-loader.ts
CHANGED
|
@@ -1,11 +1,20 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* config-loader.ts —
|
|
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
|
-
| {
|
|
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 {
|
|
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 {
|
|
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)) {
|