rungate 0.4.1 → 0.5.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/cli-commands.ts +7 -1
- package/lib/conformity.ts +965 -30
- package/lib/github.ts +195 -0
- package/lib/js-top-level-code.ts +27 -2
- package/lib/package-closure.ts +278 -2
- package/lib/release-preflight.ts +196 -0
- package/lib/scaffold/defaults.ts +40 -0
- package/lib/scaffold/managed-workflow.ts +125 -27
- package/lib/scaffold/owned-files.ts +6 -0
- package/lib/scaffold/profiles.ts +94 -0
- package/lib/scaffold/rehearsal.ts +27 -2
- package/lib/scaffold/steps.ts +654 -84
- package/lib/scaffold/write-steps.ts +50 -9
- package/lib/source-anchor.ts +144 -0
- package/lib/success-doc.ts +779 -0
- package/lib/suite-run-reading.ts +194 -0
- package/lib/test-census.ts +199 -0
- package/lib/trajectory.ts +377 -0
- package/lib/validators/spec-validators.ts +32 -4
- package/lib/workflow-security.ts +101 -0
- package/lib/workflow-test-harness.ts +349 -0
- package/package.json +6 -1
- package/scripts/create-success.ts +162 -0
- package/scripts/scaffold-project.ts +27 -3
- 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
|
@@ -35,6 +35,7 @@ import {
|
|
|
35
35
|
createTsconfig,
|
|
36
36
|
generateProjectState,
|
|
37
37
|
createClaudeMdBridge,
|
|
38
|
+
seedSuccessDoc,
|
|
38
39
|
createCiWorkflows,
|
|
39
40
|
createGitHooks,
|
|
40
41
|
deployHooksToConsumers,
|
|
@@ -48,6 +49,7 @@ import {
|
|
|
48
49
|
checkGovernsAlignment, detectMisplacedSpecs, detectUnconvertedSpecs,
|
|
49
50
|
} from "../validators/spec-validators";
|
|
50
51
|
import type { ProjectType } from "../generators/types";
|
|
52
|
+
import { DEFAULT_PROFILE, isStepIncluded, type ScaffoldProfile } from "./profiles";
|
|
51
53
|
|
|
52
54
|
export interface WriteStepOptions {
|
|
53
55
|
force?: boolean;
|
|
@@ -58,6 +60,28 @@ export interface WriteStepOptions {
|
|
|
58
60
|
* `./rehearsal.ts`, which carries the reason for each.
|
|
59
61
|
*/
|
|
60
62
|
rehearsing?: boolean;
|
|
63
|
+
/**
|
|
64
|
+
* How much of the harness this project opted into. Orthogonal to
|
|
65
|
+
* `projectType`, which selects WHICH generators run; this selects whether
|
|
66
|
+
* the harness-only ones run at all. See `STEPS_NOT_MINIMAL` in
|
|
67
|
+
* `./profiles.ts`, which carries the reason for each exclusion.
|
|
68
|
+
*/
|
|
69
|
+
profile?: ScaffoldProfile;
|
|
70
|
+
/**
|
|
71
|
+
* Opt OUT of the mechanical fixes (#42 SC-4). Default on, because a
|
|
72
|
+
* re-scaffold that reports a gap it could have closed is a worse onboarding
|
|
73
|
+
* than one that closes it.
|
|
74
|
+
*/
|
|
75
|
+
autoFix?: boolean;
|
|
76
|
+
/**
|
|
77
|
+
* Opt IN to removing consumers the source scan did not find (#42 SC-2).
|
|
78
|
+
*
|
|
79
|
+
* Deliberately NOT covered by `autoFix`'s opt-out default — see
|
|
80
|
+
* `pruneStaleConsumers`. Adding a frontmatter line and deleting a config
|
|
81
|
+
* entry are not in the same risk class, and one flag governing both would
|
|
82
|
+
* make the safe default impossible to express.
|
|
83
|
+
*/
|
|
84
|
+
pruneConsumers?: boolean;
|
|
61
85
|
}
|
|
62
86
|
|
|
63
87
|
export function runScaffoldWriteSteps(
|
|
@@ -66,7 +90,7 @@ export function runScaffoldWriteSteps(
|
|
|
66
90
|
actions: string[],
|
|
67
91
|
opts: WriteStepOptions = {},
|
|
68
92
|
): void {
|
|
69
|
-
const { force = false, commit = false, rehearsing = false } = opts;
|
|
93
|
+
const { force = false, commit = false, rehearsing = false, profile = DEFAULT_PROFILE, autoFix = true, pruneConsumers = false } = opts;
|
|
70
94
|
|
|
71
95
|
// Phase 0: Security and directory setup
|
|
72
96
|
createGitignore(projectPath, actions);
|
|
@@ -86,7 +110,7 @@ export function runScaffoldWriteSteps(
|
|
|
86
110
|
createTsconfig(projectPath, actions);
|
|
87
111
|
|
|
88
112
|
// Phase 0.5: Generate AGENTS.md
|
|
89
|
-
const agentsMd = generateAgentsMdContent(projectPath, projectType, actions);
|
|
113
|
+
const agentsMd = generateAgentsMdContent(projectPath, projectType, actions, profile);
|
|
90
114
|
writeFileSync(join(projectPath, "AGENTS.md"), agentsMd);
|
|
91
115
|
actions.push("REGENERATED: AGENTS.md");
|
|
92
116
|
refreshAgentsMd(projectPath, projectType, actions);
|
|
@@ -102,8 +126,14 @@ export function runScaffoldWriteSteps(
|
|
|
102
126
|
// Validators. These used to run outside the `if (fix)` block with a `{ fix }`
|
|
103
127
|
// flag, which is why `addFrontmatterToSpecs` is the one step audit ever
|
|
104
128
|
// reported anything from.
|
|
105
|
-
|
|
106
|
-
|
|
129
|
+
if (autoFix) {
|
|
130
|
+
addFrontmatterToSpecs(join(projectPath, "specs"), actions);
|
|
131
|
+
addFrontmatterToAdrs(join(projectPath, "docs", "adr"), actions);
|
|
132
|
+
} else {
|
|
133
|
+
// Named, not silent. A run that declined to fix and said nothing is
|
|
134
|
+
// indistinguishable from one that had nothing to fix (#208, SC-819).
|
|
135
|
+
actions.push("SKIP: auto-fix of spec and ADR frontmatter (--no-auto-fix)");
|
|
136
|
+
}
|
|
107
137
|
detectOversizedSpecs(join(projectPath, "specs"), actions);
|
|
108
138
|
checkGovernsAlignment(join(projectPath, "specs"), actions);
|
|
109
139
|
detectMisplacedSpecs(projectPath, actions);
|
|
@@ -138,18 +168,29 @@ What does this workflow produce?
|
|
|
138
168
|
safeWrite(join(projectPath, "specs", "WORKFLOW-DEFINITION.md"), workflowDef, "specs/WORKFLOW-DEFINITION.md", actions);
|
|
139
169
|
}
|
|
140
170
|
|
|
141
|
-
// Phase 1.5: Harness config + briefs
|
|
142
|
-
|
|
171
|
+
// Phase 1.5: Harness config + briefs. Harness-only under `minimal` — see
|
|
172
|
+
// STEPS_NOT_MINIMAL for why each is excluded.
|
|
173
|
+
if (isStepIncluded("generateOrAuditProjectHarness", profile)) {
|
|
174
|
+
generateOrAuditProjectHarness(projectPath, actions, { pruneConsumers });
|
|
175
|
+
}
|
|
143
176
|
injectEnvironmentSection(projectPath, actions);
|
|
144
|
-
generateAgentBriefsStep
|
|
177
|
+
if (isStepIncluded("generateAgentBriefsStep", profile)) {
|
|
178
|
+
generateAgentBriefsStep(projectPath, actions);
|
|
179
|
+
}
|
|
145
180
|
|
|
146
181
|
// Phase 3: Final setup
|
|
147
182
|
copySpecTemplateIfEmpty(join(projectPath, "specs"), actions);
|
|
148
183
|
generateProjectState(projectPath, actions);
|
|
184
|
+
// Both profiles. #485 is about the file existing at all, and `minimal` is
|
|
185
|
+
// the profile the consumer that found the gap was scaffolded with.
|
|
186
|
+
seedSuccessDoc(projectPath, actions);
|
|
149
187
|
runAuditSpecsFix(projectPath, actions);
|
|
150
188
|
addPaiHarnessDevDep(projectPath, actions);
|
|
151
189
|
createClaudeMdBridge(projectPath, actions);
|
|
152
|
-
|
|
190
|
+
// See STEPS_NOT_MINIMAL.
|
|
191
|
+
if (isStepIncluded("createCiWorkflows", profile)) {
|
|
192
|
+
createCiWorkflows(projectPath, actions, { force });
|
|
193
|
+
}
|
|
153
194
|
createGitHooks(projectPath, actions);
|
|
154
195
|
|
|
155
196
|
// Leaves the tree. See STEPS_NOT_REHEARSED.
|
|
@@ -157,7 +198,7 @@ What does this workflow produce?
|
|
|
157
198
|
|
|
158
199
|
// Phase 3.5: steps that DESCRIBE the project run last, so they describe the tree this run left (#123).
|
|
159
200
|
reportExternalAdoptionStep(projectPath, actions);
|
|
160
|
-
refreshScopedRulesStep(projectPath, projectType, actions);
|
|
201
|
+
refreshScopedRulesStep(projectPath, projectType, actions, profile);
|
|
161
202
|
if (projectType === "code") {
|
|
162
203
|
generateCodeMapStep(projectPath, actions);
|
|
163
204
|
}
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Cite a line of source by what it SAYS, not by where it sits (#514).
|
|
3
|
+
*
|
|
4
|
+
* A spec that writes `workflows/ship.js:5775` is making a claim that stops
|
|
5
|
+
* being true the next time anything is inserted above line 5775, and nothing
|
|
6
|
+
* about the spec changes when it does. `test/gate-env-expressibility.test.ts`
|
|
7
|
+
* SC-1719 is the one guard anybody wrote for one such citation, and keeping
|
|
8
|
+
* it green cost three hand edits of five numbers in two PRs.
|
|
9
|
+
*
|
|
10
|
+
* Measured on `specs/GATE-CONTRACTS-SPEC.md` while fixing this: of its seven
|
|
11
|
+
* line citations, the three under that guard were correct and **three of the
|
|
12
|
+
* four unguarded ones were already wrong** — `gate-executor.ts:1725` pointed
|
|
13
|
+
* at a `parseFloat`, `evidence-prevalidator.ts:208` at a comment, and
|
|
14
|
+
* `scaffold-rungate-config.ts:66` at an unrelated `existsSync`. Each pointed
|
|
15
|
+
* at a plausible-looking line. Nobody had noticed.
|
|
16
|
+
*
|
|
17
|
+
* So the citation carries the text and the resolver reports the position:
|
|
18
|
+
*
|
|
19
|
+
* `workflows/ship.js@"const containerConfig = projectConfig.container"`
|
|
20
|
+
*
|
|
21
|
+
* **Resolution is total.** Not found and found-twice are both refusals, and
|
|
22
|
+
* the second one matters more than it looks: an ambiguous anchor is how a
|
|
23
|
+
* citation lands somewhere plausible, which is precisely the failure the line
|
|
24
|
+
* numbers had. `0`, `null` and "the first match" are indistinguishable from a
|
|
25
|
+
* correct answer; a refusal naming the count is not.
|
|
26
|
+
*/
|
|
27
|
+
import { existsSync, readFileSync, realpathSync } from "fs";
|
|
28
|
+
import { join, resolve, sep } from "path";
|
|
29
|
+
|
|
30
|
+
/** `path@"anchor"` inside a single markdown code span. */
|
|
31
|
+
export const ANCHOR_CITATION = /`([A-Za-z0-9_./-]+)@"([^"`]*)"`/g;
|
|
32
|
+
|
|
33
|
+
/** The old form, kept so a document can be checked for having left it behind. */
|
|
34
|
+
export const LINE_CITATION = /`?\b([A-Za-z0-9_./-]+\.(?:ts|js|json)):(\d+)\b/g;
|
|
35
|
+
|
|
36
|
+
export interface Citation {
|
|
37
|
+
path: string;
|
|
38
|
+
anchor: string;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
export type Resolution =
|
|
42
|
+
| { ok: true; path: string; anchor: string; line: number; text: string }
|
|
43
|
+
| { ok: false; path: string; anchor: string; reason: string };
|
|
44
|
+
|
|
45
|
+
/** Every anchor citation in a document, in order, deduplicated by nothing. */
|
|
46
|
+
export function anchorCitations(doc: string): Citation[] {
|
|
47
|
+
const out: Citation[] = [];
|
|
48
|
+
for (const m of doc.matchAll(ANCHOR_CITATION)) out.push({ path: m[1], anchor: m[2] });
|
|
49
|
+
return out;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/**
|
|
53
|
+
* Where a citation points, or why it does not point anywhere.
|
|
54
|
+
*
|
|
55
|
+
* `root` is the repository root; a citation's path is repo-relative, because
|
|
56
|
+
* a bare filename is how `steps.ts:43` came to be ambiguous between three
|
|
57
|
+
* files in this repo's own ADRs.
|
|
58
|
+
*/
|
|
59
|
+
export function resolveCitation(root: string, cite: Citation): Resolution {
|
|
60
|
+
const { path, anchor } = cite;
|
|
61
|
+
const fail = (reason: string): Resolution => ({ ok: false, path, anchor, reason });
|
|
62
|
+
|
|
63
|
+
if (anchor.length === 0) return fail("the anchor is empty, so it matches nothing and everything");
|
|
64
|
+
// Short anchors are the ones that become ambiguous later, after an
|
|
65
|
+
// unrelated edit somewhere else in the file. Refusing them now is cheaper
|
|
66
|
+
// than refusing them on the day they break something.
|
|
67
|
+
if (anchor.trim().length < 12) {
|
|
68
|
+
return fail(`the anchor "${anchor}" is ${anchor.trim().length} characters — too short to stay unique`);
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
// The path comes out of a markdown document, and this function reads
|
|
72
|
+
// whatever it names. Flagged by the commit security review: `ANCHOR_CITATION`
|
|
73
|
+
// admits `.` and `/`, so `../../../../etc/passwd` is a well-formed citation
|
|
74
|
+
// and `join` resolves it happily out of the tree.
|
|
75
|
+
//
|
|
76
|
+
// No live document does that — every citation here is written by someone
|
|
77
|
+
// with commit access — but "the input happens to be trusted today" is not a
|
|
78
|
+
// property of a library, and a spec is exactly the sort of file a consumer
|
|
79
|
+
// generates. Refused rather than normalised: a citation that climbs out of
|
|
80
|
+
// the repository is not a citation with a fixable path, it is a citation to
|
|
81
|
+
// something this function has no business reading.
|
|
82
|
+
//
|
|
83
|
+
// Three checks, and each has an input only it reaches. The first draft had
|
|
84
|
+
// four, and the battery measured the fourth — a `..`-segment spelling rule
|
|
85
|
+
// — at **0 red**, because `resolve` normalises `..` and the containment
|
|
86
|
+
// check below already refuses it. Two deciders answering one question, the
|
|
87
|
+
// fourth shape in `.claude/rules/checks-must-be-able-to-fail.md`. Dropped.
|
|
88
|
+
//
|
|
89
|
+
// `/etc/passwd` only this rule. `join` CONCATENATES a leading
|
|
90
|
+
// slash rather than absorbing it, so the path stays
|
|
91
|
+
// inside the tree and containment has nothing to say
|
|
92
|
+
// `../../etc/passwd` only containment, below
|
|
93
|
+
// a symlink inside only `realpathSync`, below — `resolve` is purely
|
|
94
|
+
// lexical and cannot see a link at all
|
|
95
|
+
//
|
|
96
|
+
// The first of those is not an escape: `join(root, "/etc/passwd")` reads
|
|
97
|
+
// `<root>/etc/passwd`. It is refused because a citation written absolute
|
|
98
|
+
// means something other than what its author thinks it means, and a
|
|
99
|
+
// confident citation to the wrong file is this whole issue.
|
|
100
|
+
if (path.startsWith("/")) return fail("the path is absolute — citations are repository-relative");
|
|
101
|
+
|
|
102
|
+
const full = join(root, path);
|
|
103
|
+
const contained = resolve(root) + sep;
|
|
104
|
+
if (!resolve(full).startsWith(contained)) {
|
|
105
|
+
return fail("the path resolves outside the repository, so it is not a citation to this tree");
|
|
106
|
+
}
|
|
107
|
+
if (!existsSync(full)) return fail("no such file in the repository");
|
|
108
|
+
|
|
109
|
+
// The symlink question, which the lexical check genuinely cannot answer:
|
|
110
|
+
// a link INSIDE the tree whose target is outside it resolves to a
|
|
111
|
+
// contained path and reads an uncontained file. `realpathSync` is the only
|
|
112
|
+
// thing that follows it, and it needs the file to exist, which is why it
|
|
113
|
+
// sits here rather than beside its lexical sibling.
|
|
114
|
+
if (!realpathSync(full).startsWith(realpathSync(resolve(root)) + sep)) {
|
|
115
|
+
return fail("the path is a symlink whose target is outside the repository");
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
const source = readFileSync(full, "utf-8");
|
|
119
|
+
const count = source.split(anchor).length - 1;
|
|
120
|
+
if (count === 0) return fail("the file no longer contains this text");
|
|
121
|
+
if (count > 1) {
|
|
122
|
+
return fail(
|
|
123
|
+
`the text appears ${count} times, so the citation does not name a site — ` +
|
|
124
|
+
`an ambiguous anchor is how a citation lands somewhere plausible`,
|
|
125
|
+
);
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
const lines = source.split("\n");
|
|
129
|
+
const index = lines.findIndex(l => l.includes(anchor));
|
|
130
|
+
// A multi-line anchor has no single line, and silently reporting its first
|
|
131
|
+
// is the kind of "near enough" that put three wrong numbers in a spec.
|
|
132
|
+
if (index < 0) return fail("the text spans more than one line, so it does not name a line");
|
|
133
|
+
return { ok: true, path, anchor, line: index + 1, text: lines[index] };
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/** Every citation in a document that does not resolve, as sentences. */
|
|
137
|
+
export function citationFailures(root: string, doc: string): string[] {
|
|
138
|
+
const out: string[] = [];
|
|
139
|
+
for (const cite of anchorCitations(doc)) {
|
|
140
|
+
const r = resolveCitation(root, cite);
|
|
141
|
+
if (!r.ok) out.push(`${cite.path}@"${cite.anchor}" — ${r.reason}`);
|
|
142
|
+
}
|
|
143
|
+
return out;
|
|
144
|
+
}
|