rungate 0.4.1 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/config/behavioral-sc-map.json +170 -0
- package/config/brief-policies.json +28 -0
- package/config/ceremony-profiles.json +207 -0
- package/config/check-registry.json +114 -0
- package/config/matcher-registry.json +142 -0
- package/config/prove-evidence.schema.json +65 -0
- package/config/spec-policies.json +36 -0
- package/config/universal-rules.yaml +15 -0
- package/config/workflow-schema.json +279 -0
- package/lib/agents-md-sections.ts +144 -0
- package/lib/branch-diff.ts +139 -0
- package/lib/bun-version.ts +268 -0
- package/lib/ci-checkout.ts +1 -1
- package/lib/cli-commands.ts +7 -1
- package/lib/compliance.ts +13 -11
- package/lib/config-loader.ts +12 -0
- package/lib/conformity.ts +1147 -116
- package/lib/context-docs.ts +143 -28
- package/lib/create-brief.ts +2 -1
- package/lib/create-sc.ts +90 -4
- package/lib/doc-scan-targets.ts +9 -0
- package/lib/evidence-command-transport.ts +160 -0
- package/lib/evidence-prevalidator.ts +22 -0
- package/lib/fallow-availability.ts +129 -0
- package/lib/gate-refusal-currency.ts +112 -0
- package/lib/gate-timeouts.ts +82 -0
- package/lib/generators/agent-briefs.ts +4 -1
- package/lib/generators/agents-md.ts +71 -23
- package/lib/generators/code-map.ts +2 -1
- package/lib/generators/types.ts +8 -0
- package/lib/git-dates.ts +55 -0
- package/lib/github.ts +195 -0
- package/lib/js-top-level-code.ts +27 -2
- package/lib/junit-checks.ts +484 -0
- package/lib/local-calendar-day.ts +78 -0
- package/lib/package-closure.ts +278 -2
- package/lib/project-state-shape.ts +59 -0
- package/lib/promote-outputs.ts +6 -2
- package/lib/release-preflight.ts +196 -0
- package/lib/report-provenance.ts +156 -0
- package/lib/sc-claim-forms.ts +75 -0
- package/lib/sc-id-cross-tree.ts +311 -0
- package/lib/scaffold/ai-review-step.ts +180 -0
- package/lib/scaffold/defaults.ts +40 -0
- package/lib/scaffold/managed-workflow.ts +125 -27
- package/lib/scaffold/owned-files.ts +48 -2
- package/lib/scaffold/profiles.ts +94 -0
- package/lib/scaffold/rehearsal.ts +232 -73
- package/lib/scaffold/steps.ts +777 -152
- package/lib/scaffold/write-steps.ts +56 -13
- package/lib/scanner.ts +38 -12
- package/lib/source-anchor.ts +144 -0
- package/lib/spec-listing.ts +148 -0
- package/lib/spec-requirements.ts +209 -0
- package/lib/success-doc.ts +779 -0
- package/lib/suite-run-reading.ts +364 -0
- package/lib/test-census.ts +199 -0
- package/lib/test-command.ts +133 -0
- package/lib/test-suite-lock.ts +166 -10
- package/lib/tool-probe.ts +120 -0
- package/lib/tracked-vs-ignored.ts +234 -0
- package/lib/trajectory.ts +377 -0
- package/lib/validators/spec-validators.ts +35 -6
- package/lib/workflow-security.ts +101 -0
- package/lib/workflow-test-harness.ts +349 -0
- package/package.json +6 -1
- package/scripts/audit-specs.ts +247 -12
- package/scripts/audit-transcript.ts +2 -1
- package/scripts/convert-spec.ts +2 -1
- package/scripts/create-sc.ts +17 -7
- package/scripts/create-spec.ts +2 -1
- package/scripts/create-success.ts +163 -0
- package/scripts/extract-constraints.ts +90 -19
- package/scripts/generate-code-map.ts +53 -12
- package/scripts/scaffold-project.ts +31 -4
- package/scripts/split-spec.ts +2 -1
- package/scripts/sync-sc-status.ts +57 -5
- package/scripts/sync-spec-tests.ts +2 -1
- package/specs/SPEC-TEMPLATE.md +200 -0
- package/templates/SUCCESS-TEMPLATE.md +72 -0
- package/templates/agent-briefs/_shared.md +9 -0
- package/templates/agent-briefs/aditi.md +46 -0
- package/templates/agent-briefs/discovery.md +37 -0
- package/templates/agent-briefs/marcus.md +39 -0
- package/templates/agent-briefs/quinn.md +67 -0
- package/templates/agent-briefs/rook.md +40 -0
- package/templates/agent-briefs/serena.md +39 -0
package/lib/context-docs.ts
CHANGED
|
@@ -18,27 +18,50 @@
|
|
|
18
18
|
*
|
|
19
19
|
* This module owns (1) and (3)'s successor; the loader owns (2).
|
|
20
20
|
*
|
|
21
|
-
* ## The decision about paths outside the project root
|
|
22
|
-
*
|
|
23
|
-
*
|
|
24
|
-
*
|
|
25
|
-
*
|
|
26
|
-
*
|
|
27
|
-
*
|
|
28
|
-
*
|
|
29
|
-
*
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
*
|
|
33
|
-
*
|
|
34
|
-
*
|
|
35
|
-
*
|
|
36
|
-
*
|
|
37
|
-
*
|
|
21
|
+
* ## The decision about paths outside the project root (#439, revised by #497)
|
|
22
|
+
*
|
|
23
|
+
* #439 allowed them, on two premises:
|
|
24
|
+
*
|
|
25
|
+
* > A brief NAMES files; it does not read them. The config is written by the
|
|
26
|
+
* > operator whose session the agent runs in, so a path they declared is not
|
|
27
|
+
* > an escalation of anything.
|
|
28
|
+
*
|
|
29
|
+
* The first is true of the brief and beside the point: the brief exists to be
|
|
30
|
+
* obeyed by an agent holding a Read tool, so "named" and "read" are one step
|
|
31
|
+
* apart and the step is the document's purpose. The second is true when the
|
|
32
|
+
* operator scaffolded the project. Rungate is a harness pointed at a
|
|
33
|
+
* `projectRoot`, and the config lives INSIDE that tree — so for any repo the
|
|
34
|
+
* operator cloned rather than authored, `contextDocs: ["/Users/<them>/.ssh/id_rsa"]`
|
|
35
|
+
* is a line in a checked-in file that puts an arbitrary host path into an
|
|
36
|
+
* agent instruction.
|
|
37
|
+
*
|
|
38
|
+
* That is a true sentence derived from the cases that were measured —
|
|
39
|
+
* operator-authored config — and then applied to a population it does not
|
|
40
|
+
* cover. `.claude/rules/checks-must-be-able-to-fail.md` has the shape under
|
|
41
|
+
* *"This cannot be checked" is a claim, and it is checkable*.
|
|
42
|
+
*
|
|
43
|
+
* So an external path is now REJECTED rather than included, unless its root
|
|
44
|
+
* is trusted — and the trust comes from `RUNGATE_TRUSTED_DOC_ROOTS` in the
|
|
45
|
+
* environment, never from the repository under test. **An allowlist inside
|
|
46
|
+
* the config it is allowing is not one**, which is the whole reason this is a
|
|
47
|
+
* revision rather than a revert.
|
|
48
|
+
*
|
|
49
|
+
* #439's real property is untouched and is still the thing this file is
|
|
50
|
+
* about: nothing declared disappears without a line saying what happened to
|
|
51
|
+
* it. A rejected external path is named in the notes with its reason, exactly
|
|
52
|
+
* as a missing or malformed one is. The old filter dropped it in silence; the
|
|
53
|
+
* difference between that and this is the only difference that matters.
|
|
54
|
+
*
|
|
55
|
+
* ## Symlinks
|
|
56
|
+
*
|
|
57
|
+
* The comparison is on the REAL path. `relative(resolve(root), resolved)` is
|
|
58
|
+
* symlink-blind: a link inside the repo pointing at `/Users/<them>/.ssh`
|
|
59
|
+
* resolves to a path under the root and reads as internal, which makes the
|
|
60
|
+
* control satisfiable by the cheapest possible bypass.
|
|
38
61
|
*/
|
|
39
62
|
|
|
40
|
-
import { existsSync } from "fs";
|
|
41
|
-
import { isAbsolute, relative, resolve } from "path";
|
|
63
|
+
import { existsSync, realpathSync } from "fs";
|
|
64
|
+
import { dirname, isAbsolute, join, relative, resolve } from "path";
|
|
42
65
|
|
|
43
66
|
/**
|
|
44
67
|
* Characters a path must not carry into a brief (BUG-439-A).
|
|
@@ -65,6 +88,61 @@ export function hasBriefUnsafeChars(value: string): boolean {
|
|
|
65
88
|
return BRIEF_UNSAFE.test(value);
|
|
66
89
|
}
|
|
67
90
|
|
|
91
|
+
/**
|
|
92
|
+
* The environment variable that names roots outside a project whose docs may
|
|
93
|
+
* still be reached.
|
|
94
|
+
*
|
|
95
|
+
* Deliberately NOT a config key. The threat is a `contextDocs` line in a
|
|
96
|
+
* repository the operator cloned rather than wrote; an allowlist read from
|
|
97
|
+
* that same repository would be authored by whoever authored the entry it is
|
|
98
|
+
* supposed to authorise. It is also deliberately not a rungate config read,
|
|
99
|
+
* so `.claude/rules/config-access.md` does not apply — this is not project
|
|
100
|
+
* config, and routing it through the loader would put it back inside the tree
|
|
101
|
+
* it exists to be outside of.
|
|
102
|
+
*/
|
|
103
|
+
export const TRUSTED_ROOTS_ENV = "RUNGATE_TRUSTED_DOC_ROOTS";
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* The trusted roots, absolute and real. `PATH`-style separator, because an
|
|
107
|
+
* operator setting this is already thinking in terms of a path list.
|
|
108
|
+
*/
|
|
109
|
+
export function trustedDocRoots(env: NodeJS.ProcessEnv = process.env): string[] {
|
|
110
|
+
const raw = env[TRUSTED_ROOTS_ENV];
|
|
111
|
+
if (typeof raw !== "string" || raw.trim() === "") return [];
|
|
112
|
+
return raw
|
|
113
|
+
.split(":")
|
|
114
|
+
.map(p => p.trim())
|
|
115
|
+
.filter(p => p !== "" && isAbsolute(p))
|
|
116
|
+
.map(p => realPathish(p));
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/**
|
|
120
|
+
* `realpathSync` where it can answer, and the real path of the nearest
|
|
121
|
+
* existing ancestor with the remainder appended where it cannot.
|
|
122
|
+
*
|
|
123
|
+
* A declared doc need not exist — `missing` is a first-class verdict here —
|
|
124
|
+
* and a plain `resolve()` fallback would make a path through a symlinked
|
|
125
|
+
* directory to a file that is not there yet read as internal. The ancestor
|
|
126
|
+
* walk is what keeps the missing case and the symlink case from being
|
|
127
|
+
* mutually exclusive.
|
|
128
|
+
*/
|
|
129
|
+
export function realPathish(p: string): string {
|
|
130
|
+
let head = resolve(p);
|
|
131
|
+
const tail: string[] = [];
|
|
132
|
+
for (;;) {
|
|
133
|
+
try {
|
|
134
|
+
return tail.length === 0 ? realpathSync(head) : join(realpathSync(head), ...tail);
|
|
135
|
+
} catch {
|
|
136
|
+
const parent = dirname(head);
|
|
137
|
+
// `/` is its own parent: nothing below it existed, so there is nothing
|
|
138
|
+
// to resolve and the lexical answer is the honest one.
|
|
139
|
+
if (parent === head) return resolve(p);
|
|
140
|
+
tail.unshift(head.slice(parent.length === 1 ? 1 : parent.length + 1));
|
|
141
|
+
head = parent;
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
|
|
68
146
|
export type ContextDocVerdict =
|
|
69
147
|
| {
|
|
70
148
|
kind: "included";
|
|
@@ -72,8 +150,10 @@ export type ContextDocVerdict =
|
|
|
72
150
|
declared: string;
|
|
73
151
|
/** Absolute, after resolving against the project root. */
|
|
74
152
|
resolved: string;
|
|
75
|
-
/** Outside the project root
|
|
153
|
+
/** Outside the project root. Only reachable here when a trusted root allows it. */
|
|
76
154
|
external: boolean;
|
|
155
|
+
/** The trusted root that allowed an external path, or null. */
|
|
156
|
+
trustedBy: string | null;
|
|
77
157
|
/** Declared but not on disk when the brief was assembled. */
|
|
78
158
|
missing: boolean;
|
|
79
159
|
}
|
|
@@ -83,7 +163,11 @@ export type ContextDocVerdict =
|
|
|
83
163
|
* Classify ONE declared entry. The single binding, so there is one thing to
|
|
84
164
|
* mutate and each arm is separately observable in the assembled brief.
|
|
85
165
|
*/
|
|
86
|
-
export function classifyContextDoc(
|
|
166
|
+
export function classifyContextDoc(
|
|
167
|
+
projectRoot: string,
|
|
168
|
+
declared: unknown,
|
|
169
|
+
env: NodeJS.ProcessEnv = process.env,
|
|
170
|
+
): ContextDocVerdict {
|
|
87
171
|
if (typeof declared !== "string") {
|
|
88
172
|
return { kind: "rejected", declared: JSON.stringify(declared) ?? String(declared), reason: "not a string" };
|
|
89
173
|
}
|
|
@@ -99,14 +183,39 @@ export function classifyContextDoc(projectRoot: string, declared: unknown): Cont
|
|
|
99
183
|
};
|
|
100
184
|
}
|
|
101
185
|
|
|
102
|
-
|
|
186
|
+
// The REAL path, on both sides. A link inside the repo pointing outside it
|
|
187
|
+
// resolves under the root lexically, and comparing the lexical answers is a
|
|
188
|
+
// control anyone can walk past with `ln -s`.
|
|
189
|
+
const resolved = realPathish(isAbsolute(trimmed) ? trimmed : join(projectRoot, trimmed));
|
|
103
190
|
// `relative` rather than `startsWith`: `/repo-backup` starts with `/repo`
|
|
104
191
|
// and is a different directory. One comparison, computed the way the
|
|
105
192
|
// filesystem means it.
|
|
106
|
-
const rel = relative(
|
|
193
|
+
const rel = relative(realPathish(projectRoot), resolved);
|
|
107
194
|
const external = rel === "" || rel.startsWith("..") || isAbsolute(rel);
|
|
108
195
|
|
|
109
|
-
|
|
196
|
+
const trustedBy = external ? (trustedDocRoots(env).find(root => isWithin(root, resolved)) ?? null) : null;
|
|
197
|
+
if (external && trustedBy === null) {
|
|
198
|
+
return {
|
|
199
|
+
kind: "rejected",
|
|
200
|
+
declared: trimmed,
|
|
201
|
+
reason: `resolves to ${resolved}, outside this project; add its root to ${TRUSTED_ROOTS_ENV} in the environment to allow it`,
|
|
202
|
+
};
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
return {
|
|
206
|
+
kind: "included",
|
|
207
|
+
declared: trimmed,
|
|
208
|
+
resolved,
|
|
209
|
+
external,
|
|
210
|
+
trustedBy,
|
|
211
|
+
missing: !existsSync(resolved),
|
|
212
|
+
};
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
/** Is `path` the root itself or under it? Same `relative` comparison, one place. */
|
|
216
|
+
function isWithin(root: string, path: string): boolean {
|
|
217
|
+
const rel = relative(root, path);
|
|
218
|
+
return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
|
|
110
219
|
}
|
|
111
220
|
|
|
112
221
|
/**
|
|
@@ -116,7 +225,11 @@ export function classifyContextDoc(projectRoot: string, declared: unknown): Cont
|
|
|
116
225
|
* rejection rather than silence, because a config that declares the key and
|
|
117
226
|
* gets nothing is exactly the case this issue is about.
|
|
118
227
|
*/
|
|
119
|
-
export function classifyContextDocs(
|
|
228
|
+
export function classifyContextDocs(
|
|
229
|
+
projectRoot: string,
|
|
230
|
+
raw: unknown,
|
|
231
|
+
env: NodeJS.ProcessEnv = process.env,
|
|
232
|
+
): ContextDocVerdict[] {
|
|
120
233
|
if (raw === undefined || raw === null) return [];
|
|
121
234
|
const entries: unknown[] = Array.isArray(raw)
|
|
122
235
|
? raw
|
|
@@ -130,7 +243,7 @@ export function classifyContextDocs(projectRoot: string, raw: unknown): ContextD
|
|
|
130
243
|
reason: `contextDocs must be an array or an object, got ${typeof raw}`,
|
|
131
244
|
}];
|
|
132
245
|
}
|
|
133
|
-
return entries.map(e => classifyContextDoc(projectRoot, e));
|
|
246
|
+
return entries.map(e => classifyContextDoc(projectRoot, e, env));
|
|
134
247
|
}
|
|
135
248
|
|
|
136
249
|
/** The numbered brief lines, one per included doc, labelled where it matters. */
|
|
@@ -140,7 +253,7 @@ export function contextDocLines(verdicts: ContextDocVerdict[], startIndex: numbe
|
|
|
140
253
|
for (const v of verdicts) {
|
|
141
254
|
if (v.kind !== "included") continue;
|
|
142
255
|
const notes = [
|
|
143
|
-
v.external ?
|
|
256
|
+
v.external ? `external to this project, allowed by ${TRUSTED_ROOTS_ENV}` : null,
|
|
144
257
|
v.missing ? "declared in contextDocs but not present at assembly time" : null,
|
|
145
258
|
].filter(Boolean);
|
|
146
259
|
lines.push(`${idx}. ${v.resolved}${notes.length ? ` (${notes.join("; ")})` : ""}`);
|
|
@@ -176,7 +289,9 @@ export function contextDocNotes(verdicts: ContextDocVerdict[]): string[] {
|
|
|
176
289
|
if (v.kind === "included") notes.push(`> - MISSING ${v.declared}: nothing at ${v.resolved}`);
|
|
177
290
|
}
|
|
178
291
|
for (const v of external) {
|
|
179
|
-
if (v.kind === "included")
|
|
292
|
+
if (v.kind === "included") {
|
|
293
|
+
notes.push(`> - EXTERNAL ${v.declared}: resolves to ${v.resolved}, outside this project, trusted via ${v.trustedBy}`);
|
|
294
|
+
}
|
|
180
295
|
}
|
|
181
296
|
return notes;
|
|
182
297
|
}
|
package/lib/create-brief.ts
CHANGED
|
@@ -6,6 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
import { readFileSync, writeFileSync, existsSync } from "fs";
|
|
8
8
|
import { writeRoleConfig } from "./config-loader";
|
|
9
|
+
import { localCalendarDay } from "./local-calendar-day";
|
|
9
10
|
import type { AgentMeta } from "./generators/types";
|
|
10
11
|
|
|
11
12
|
/**
|
|
@@ -16,7 +17,7 @@ export function generateBriefTemplate(
|
|
|
16
17
|
description: string,
|
|
17
18
|
forbiddenCommands?: string[],
|
|
18
19
|
): string {
|
|
19
|
-
const today =
|
|
20
|
+
const today = localCalendarDay();
|
|
20
21
|
const displayName = roleName.charAt(0).toUpperCase() + roleName.slice(1);
|
|
21
22
|
|
|
22
23
|
return `---
|
package/lib/create-sc.ts
CHANGED
|
@@ -9,7 +9,9 @@ import { join, dirname } from "path";
|
|
|
9
9
|
import { fileURLToPath } from "url";
|
|
10
10
|
|
|
11
11
|
import type { ScRegistry } from "./sc-ids";
|
|
12
|
-
import { isFixtureScId } from "./sc-ids";
|
|
12
|
+
import { isFixtureScId, scIdsSpelledInSource, SC_SOURCE_DIRS } from "./sc-ids";
|
|
13
|
+
import type { ScNamespaceReading, SourceReading } from "./sc-id-cross-tree";
|
|
14
|
+
import { readScNamespace } from "./sc-id-cross-tree";
|
|
13
15
|
import { tryLoadRungateConfig } from "./config-loader";
|
|
14
16
|
|
|
15
17
|
// ── Types ─────────────────────────────────────────────────────
|
|
@@ -267,6 +269,18 @@ export function listPatterns(): string {
|
|
|
267
269
|
* collision this function exists to prevent. The reservation is enforced
|
|
268
270
|
* against specs by SC-1524, not by making the allocator pretend.
|
|
269
271
|
*/
|
|
272
|
+
/**
|
|
273
|
+
* The ids a spec's own text spells, as one binding.
|
|
274
|
+
*
|
|
275
|
+
* The allocator counts them and the reading reports how many it counted; two
|
|
276
|
+
* scans of the same string would be two deciders that agree, and a reading
|
|
277
|
+
* whose numbers come from a different pattern than the allocation used is a
|
|
278
|
+
* reading of something else.
|
|
279
|
+
*/
|
|
280
|
+
function idsInSpecContent(specContent: string): string[] {
|
|
281
|
+
return [...specContent.matchAll(/SC-(\d+)/g)].map(m => m[0]);
|
|
282
|
+
}
|
|
283
|
+
|
|
270
284
|
export function nextSCNumber(
|
|
271
285
|
specContent: string,
|
|
272
286
|
reg?: ScRegistry,
|
|
@@ -277,15 +291,87 @@ export function nextSCNumber(
|
|
|
277
291
|
const n = Number(raw.replace(/^SC-[A-Z]?/, ""));
|
|
278
292
|
if (Number.isFinite(n)) ids.push(n);
|
|
279
293
|
};
|
|
280
|
-
const
|
|
281
|
-
let match;
|
|
282
|
-
while ((match = pattern.exec(specContent)) !== null) take(match[0]);
|
|
294
|
+
for (const raw of idsInSpecContent(specContent)) take(raw);
|
|
283
295
|
for (const id of reg?.declaredById.keys() ?? []) take(id);
|
|
284
296
|
for (const id of spelledInSource ?? []) if (!isFixtureScId(id)) take(id);
|
|
285
297
|
if (ids.length === 0) return 1;
|
|
286
298
|
return Math.max(...ids) + 1;
|
|
287
299
|
}
|
|
288
300
|
|
|
301
|
+
/**
|
|
302
|
+
* The next free SC number for a project, over every namespace this machine
|
|
303
|
+
* can see (#503).
|
|
304
|
+
*
|
|
305
|
+
* `nextSCNumber` answers the question for the arguments it is handed, and
|
|
306
|
+
* three widths of that question have each been wrong in turn: one spec's
|
|
307
|
+
* content (#392), the spec registry without test fixtures (#399), and the
|
|
308
|
+
* registry of whichever working tree the command ran in (#503). This is the
|
|
309
|
+
* composition, in one place, so a caller cannot assemble two of the three and
|
|
310
|
+
* believe it asked.
|
|
311
|
+
*
|
|
312
|
+
* It returns the reading alongside the number because the number is a FLOOR:
|
|
313
|
+
* a clone on another machine is outside anything this process can reach, and
|
|
314
|
+
* a caller that printed only the number would be claiming a guarantee the
|
|
315
|
+
* reading explicitly does not give.
|
|
316
|
+
*
|
|
317
|
+
* ## `reg` is REQUIRED, and was optional for two issues (#593)
|
|
318
|
+
*
|
|
319
|
+
* Omit it and `nextSCNumber` skips `reg.declaredById` entirely: the answer is
|
|
320
|
+
* assembled from the spec's own content, source-spelled fixtures and the
|
|
321
|
+
* cross-tree namespace, and the spec registry — the width #392 was filed
|
|
322
|
+
* over — is not consulted at all. The number comes back looking exactly like
|
|
323
|
+
* one that had asked everything, which is the composition failure the
|
|
324
|
+
* paragraph above says this function exists to make impossible. A caller
|
|
325
|
+
* with no registry to hand has `buildScRegistry([])`, which states "this
|
|
326
|
+
* tree declares nothing" instead of defaulting to it.
|
|
327
|
+
*
|
|
328
|
+
* The two readings agree whenever every spec-declared id is also spelled in
|
|
329
|
+
* a source file, which is most of the time and is why nothing noticed. They
|
|
330
|
+
* diverged the day a spec declared eight criteria no test mentioned yet.
|
|
331
|
+
*
|
|
332
|
+
* ## The reading names every leg, not just the cross-tree ones
|
|
333
|
+
*
|
|
334
|
+
* `readScNamespace` accounts for the worktrees and refs it read. The other
|
|
335
|
+
* three widths were invisible in the returned reading, so a CLI could print
|
|
336
|
+
* the number and a complete-looking account of where it came from while one
|
|
337
|
+
* of the legs behind it had never run. They are appended as sources of their
|
|
338
|
+
* own, with the count each contributed — `0` from a leg that was consulted
|
|
339
|
+
* and `0` from a leg that was skipped are the same number and opposite
|
|
340
|
+
* facts (`.claude/rules/config-access.md`).
|
|
341
|
+
*/
|
|
342
|
+
export function allocateScNumber(
|
|
343
|
+
root: string,
|
|
344
|
+
specContent: string,
|
|
345
|
+
reg: ScRegistry,
|
|
346
|
+
): { number: number; namespace: ScNamespaceReading } {
|
|
347
|
+
const namespace = readScNamespace(root);
|
|
348
|
+
const spelled = [...scIdsSpelledInSource(root).keys()];
|
|
349
|
+
const number = nextSCNumber(specContent, reg, [...spelled, ...namespace.ids.keys()]);
|
|
350
|
+
|
|
351
|
+
const legs: SourceReading[] = [
|
|
352
|
+
{
|
|
353
|
+
label: "the spec's own content",
|
|
354
|
+
kind: "spec-content",
|
|
355
|
+
status: "read",
|
|
356
|
+
found: new Set(idsInSpecContent(specContent)).size,
|
|
357
|
+
},
|
|
358
|
+
{
|
|
359
|
+
label: "spec registry (every declared id, checkbox and heading)",
|
|
360
|
+
kind: "registry",
|
|
361
|
+
status: "read",
|
|
362
|
+
found: reg.declaredById.size,
|
|
363
|
+
},
|
|
364
|
+
{
|
|
365
|
+
label: `SC ids spelled under ${SC_SOURCE_DIRS.join(", ")}`,
|
|
366
|
+
kind: "source-mentions",
|
|
367
|
+
status: "read",
|
|
368
|
+
found: new Set(spelled).size,
|
|
369
|
+
},
|
|
370
|
+
];
|
|
371
|
+
|
|
372
|
+
return { number, namespace: { ...namespace, sources: [...legs, ...namespace.sources] } };
|
|
373
|
+
}
|
|
374
|
+
|
|
289
375
|
/**
|
|
290
376
|
* Format an SC line for appending to a spec file.
|
|
291
377
|
*/
|
package/lib/doc-scan-targets.ts
CHANGED
|
@@ -393,6 +393,15 @@ export function planDocScan(projectPath: string): DocScanPlan {
|
|
|
393
393
|
if (real === null) { st.refused.push(path); continue; }
|
|
394
394
|
if (st.seen.has(real)) continue;
|
|
395
395
|
st.seen.add(real);
|
|
396
|
+
// A name is not a file type. `walkMarkdown` asks `statSync` before it
|
|
397
|
+
// decides; this loop asked only the suffix, so a DIRECTORY called
|
|
398
|
+
// `NOTES.md` at the project root was planned as a document and handed
|
|
399
|
+
// to `readFileSync`, which throws EISDIR — the plan claimed a file it
|
|
400
|
+
// could never read (#508). Nothing reports it either way: a directory
|
|
401
|
+
// with a markdown name carries no prose.
|
|
402
|
+
let isFile: boolean;
|
|
403
|
+
try { isFile = statSync(real).isFile(); } catch { continue; }
|
|
404
|
+
if (!isFile) continue;
|
|
396
405
|
if (st.files.length >= MAX_SCAN_FILES) { st.truncatedFiles++; continue; }
|
|
397
406
|
st.files.push(anchored(projectPath, st.rootReal, real));
|
|
398
407
|
}
|
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Moving an agent-authored evidence command from discovery to the state file,
|
|
3
|
+
* and recording every legitimate change made to one on the way (#614).
|
|
4
|
+
*
|
|
5
|
+
* ## The defect this module exists for
|
|
6
|
+
*
|
|
7
|
+
* `workflows/ship.js` persisted discovery's ACs by interpolating
|
|
8
|
+
* `JSON.stringify(discovery.acs…)` into a DOUBLE-QUOTED `bun -e "…"` shell
|
|
9
|
+
* string in the setup agent's prompt. Inside double quotes a shell expands
|
|
10
|
+
* `$1` to the empty string, `${VAR}` to the environment, and `$(cmd)` by
|
|
11
|
+
* RUNNING it. On run `wf_c92dd0a7-fe6` the command
|
|
12
|
+
*
|
|
13
|
+
* grep -rhcE '^export function localCalendarDay' lib | awk '{s+=$1} END {print s+0}'
|
|
14
|
+
*
|
|
15
|
+
* arrived in `workflow-state.json` as `awk '{s+=} END {print s+0}'` — an awk
|
|
16
|
+
* syntax error. The AC could never produce evidence, stayed PENDING, and took
|
|
17
|
+
* the verify gate down with four failures. The blast radius was every evidence
|
|
18
|
+
* command containing a `$`.
|
|
19
|
+
*
|
|
20
|
+
* The fix is to stop putting agent-authored text where a shell looks. The
|
|
21
|
+
* payload leaves the generator as a SINGLE-QUOTED argument — the one shell
|
|
22
|
+
* construct with no expansion inside it at all — and the `bun -e` program
|
|
23
|
+
* reads it out of `process.argv` instead of carrying it as program text.
|
|
24
|
+
*
|
|
25
|
+
* ## Why the provenance half is in the same module
|
|
26
|
+
*
|
|
27
|
+
* Three places legitimately rewrite an evidence command: discovery's path
|
|
28
|
+
* normaliser, discovery's evidence-type-ratio upgrade, and the git-ref
|
|
29
|
+
* qualification at the execution boundary (#118). Each used to overwrite
|
|
30
|
+
* `evidenceMethod.command` in place, so a reader of a broken command could not
|
|
31
|
+
* tell a repair from a corruption — which is exactly the question #614 took a
|
|
32
|
+
* run and a post-mortem to answer. `recordEvidenceRewrite` is the single site
|
|
33
|
+
* that changes a command, and it keeps the FIRST authored form.
|
|
34
|
+
*
|
|
35
|
+
* It belongs here because it is the same claim from the other side: the first
|
|
36
|
+
* half says nothing may change the command by accident, the second says
|
|
37
|
+
* everything that changes it on purpose must say so.
|
|
38
|
+
*
|
|
39
|
+
* `workflows/ship.js` cannot import (#69). It carries an inlined copy inside
|
|
40
|
+
* the `AC-PAYLOAD-TRANSPORT` markers, and `test/evidence-command-roundtrip.test.ts`
|
|
41
|
+
* runs both over one matrix so drift is red.
|
|
42
|
+
*/
|
|
43
|
+
import { shellSingleQuote } from "./phase2-decomposition";
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* Where the payload arrives inside the `bun -e` program.
|
|
47
|
+
*
|
|
48
|
+
* `bun -e '<program>' a b` gives the program `process.argv[1] === "a"`.
|
|
49
|
+
*/
|
|
50
|
+
export const AC_PAYLOAD_ARGV_INDEX = 1;
|
|
51
|
+
|
|
52
|
+
/** One recorded change to an evidence command. */
|
|
53
|
+
export interface EvidenceRewrite {
|
|
54
|
+
/** The site that made the change, named so a reader can go and read it. */
|
|
55
|
+
by: string;
|
|
56
|
+
/** The command as it stood before this change. */
|
|
57
|
+
from: string;
|
|
58
|
+
/** The command as it stands after it. */
|
|
59
|
+
to: string;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/** The AC fields the setup step persists into workflow-state.json. */
|
|
63
|
+
export interface AcPayloadRecord {
|
|
64
|
+
id: unknown;
|
|
65
|
+
type: unknown;
|
|
66
|
+
statement: unknown;
|
|
67
|
+
threshold: unknown;
|
|
68
|
+
evidenceMethod: unknown;
|
|
69
|
+
specElement: unknown;
|
|
70
|
+
coversCriteria: unknown[];
|
|
71
|
+
contextFiles: unknown[];
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* Project discovery's ACs onto the fields `writeACs` persists.
|
|
76
|
+
*
|
|
77
|
+
* Kept as a function rather than inlined at the two call sites because the
|
|
78
|
+
* two used to be two copies of the same object literal, and a field added to
|
|
79
|
+
* one of them would have been silently missing from the fix-acs fallback.
|
|
80
|
+
*/
|
|
81
|
+
export function acPayloadRecords(acs: unknown): AcPayloadRecord[] {
|
|
82
|
+
return (Array.isArray(acs) ? acs : []).map((ac: any) => ({
|
|
83
|
+
id: ac.id,
|
|
84
|
+
type: ac.type,
|
|
85
|
+
statement: ac.statement,
|
|
86
|
+
threshold: ac.threshold,
|
|
87
|
+
evidenceMethod: ac.evidenceMethod,
|
|
88
|
+
specElement: ac.specElement,
|
|
89
|
+
coversCriteria: ac.coversCriteria || [],
|
|
90
|
+
contextFiles: ac.contextFiles || [],
|
|
91
|
+
}));
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/** The payload exactly as it will be written to disk. */
|
|
95
|
+
export function acPayloadJson(acs: unknown): string {
|
|
96
|
+
return JSON.stringify(acPayloadRecords(acs));
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
/**
|
|
100
|
+
* The payload as a shell WORD, to sit after the closing quote of the
|
|
101
|
+
* `bun -e "…"` program.
|
|
102
|
+
*
|
|
103
|
+
* Single quotes are the one shell construct with no expansion inside them at
|
|
104
|
+
* all, so this is the only position in the command where agent-authored text
|
|
105
|
+
* is safe. `shellSingleQuote` closes, escapes and reopens on an apostrophe,
|
|
106
|
+
* which is the single character the construct cannot carry verbatim — and
|
|
107
|
+
* evidence commands are full of apostrophes, because that is how an awk or
|
|
108
|
+
* grep expression is quoted.
|
|
109
|
+
*
|
|
110
|
+
* ## Why an argument and not a file
|
|
111
|
+
*
|
|
112
|
+
* The obvious alternative — write the payload to `${WORK_DIR}/…json` and have
|
|
113
|
+
* the `bun -e` read it — was built first and does not work, for a reason
|
|
114
|
+
* worth recording rather than rediscovering. `initWorkflow` calls `beginRun`,
|
|
115
|
+
* whose whole job (#288) is to sweep the work directory into
|
|
116
|
+
* `previous-run-<id>/` so a dead run's artefacts cannot be read as this
|
|
117
|
+
* run's. A payload written before `initWorkflow` is archived by it, and the
|
|
118
|
+
* read that follows is an ENOENT; a payload written after it needs a third
|
|
119
|
+
* command in the agent's prompt. The argument has neither problem: one
|
|
120
|
+
* process, no new file in a swept directory, and no ordering to get wrong.
|
|
121
|
+
*/
|
|
122
|
+
export function acPayloadShellArgument(acs: unknown): string {
|
|
123
|
+
return shellSingleQuote(acPayloadJson(acs));
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/**
|
|
127
|
+
* The JavaScript expression that reads the payload back, for embedding in the
|
|
128
|
+
* `bun -e` program that calls `writeACs`.
|
|
129
|
+
*
|
|
130
|
+
* It contains no agent-authored text and no `$`, so it is safe inside the
|
|
131
|
+
* double-quoted shell string the setup step still is.
|
|
132
|
+
*/
|
|
133
|
+
export function acPayloadReadExpression(): string {
|
|
134
|
+
return `JSON.parse(process.argv[${AC_PAYLOAD_ARGV_INDEX}])`;
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
/**
|
|
138
|
+
* Change an evidence command, on the record.
|
|
139
|
+
*
|
|
140
|
+
* Returns true when the command actually changed. A no-op records nothing: a
|
|
141
|
+
* recorder that logged every call would leave `rewrites` non-empty on every
|
|
142
|
+
* AC and the field would stop meaning "this command was changed".
|
|
143
|
+
*
|
|
144
|
+
* `authoredCommand` is written once and never overwritten. A field holding
|
|
145
|
+
* "whatever it was one rewrite ago" cannot answer the question #614 asks,
|
|
146
|
+
* which is what the agent wrote.
|
|
147
|
+
*/
|
|
148
|
+
export function recordEvidenceRewrite(
|
|
149
|
+
evidenceMethod: { command?: string; authoredCommand?: string; rewrites?: EvidenceRewrite[] } | undefined | null,
|
|
150
|
+
by: string,
|
|
151
|
+
next: string,
|
|
152
|
+
): boolean {
|
|
153
|
+
if (!evidenceMethod || typeof evidenceMethod.command !== "string") return false;
|
|
154
|
+
const from = evidenceMethod.command;
|
|
155
|
+
if (from === next) return false;
|
|
156
|
+
if (evidenceMethod.authoredCommand === undefined) evidenceMethod.authoredCommand = from;
|
|
157
|
+
evidenceMethod.command = next;
|
|
158
|
+
evidenceMethod.rewrites = [...(evidenceMethod.rewrites || []), { by, from, to: next }];
|
|
159
|
+
return true;
|
|
160
|
+
}
|
|
@@ -57,6 +57,23 @@ export interface EvidencePrevalidationReading {
|
|
|
57
57
|
checkedAt: string;
|
|
58
58
|
/** Per-AC results. Empty — and only empty — when the verdict is UNMEASURED. */
|
|
59
59
|
acs: PrevalidationResult[];
|
|
60
|
+
/**
|
|
61
|
+
* The ids of the ACs classified `broken`, in the order they were measured.
|
|
62
|
+
*
|
|
63
|
+
* Derived from `acs`, never supplied — `EvidencePrevalidationSchema` refuses
|
|
64
|
+
* a reading whose `broken` disagrees with its own results, so this cannot
|
|
65
|
+
* drift into an independent claim.
|
|
66
|
+
*
|
|
67
|
+
* It exists because the gate's single refusal site,
|
|
68
|
+
* `prevalidationViolations` in gates/workflow.test.ts, names the ACs to fix
|
|
69
|
+
* out of exactly this key — and until #274 no writer produced it. Every
|
|
70
|
+
* genuine FAIL therefore refused with "no broken AC ids were recorded", which
|
|
71
|
+
* is true of the key and false of the reading: the per-AC results were right
|
|
72
|
+
* there under `acs`. Fail-closed, so nothing shipped that should not have,
|
|
73
|
+
* but a refusal the heal loop cannot act on costs a round and teaches
|
|
74
|
+
* nothing, which is part of how #261 cost two.
|
|
75
|
+
*/
|
|
76
|
+
broken: string[];
|
|
60
77
|
/** Why the reading is UNMEASURED. Null — and only null — when it is not. */
|
|
61
78
|
reason: string | null;
|
|
62
79
|
}
|
|
@@ -348,6 +365,7 @@ export async function measureEvidencePrevalidation(
|
|
|
348
365
|
verdict: "UNMEASURED",
|
|
349
366
|
checkedAt,
|
|
350
367
|
acs: [],
|
|
368
|
+
broken: [],
|
|
351
369
|
reason,
|
|
352
370
|
});
|
|
353
371
|
|
|
@@ -385,6 +403,10 @@ export async function measureEvidencePrevalidation(
|
|
|
385
403
|
verdict: broken.length > 0 ? "FAIL" : "PASS",
|
|
386
404
|
checkedAt,
|
|
387
405
|
acs: results,
|
|
406
|
+
// Mapped from the same filter the verdict is derived from, at the single
|
|
407
|
+
// site that derives it, so the verdict and the names it refuses under
|
|
408
|
+
// cannot disagree.
|
|
409
|
+
broken: broken.map((r) => r.id),
|
|
388
410
|
reason: null,
|
|
389
411
|
};
|
|
390
412
|
}
|