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.
Files changed (42) hide show
  1. package/config/behavioral-sc-map.json +170 -0
  2. package/config/brief-policies.json +28 -0
  3. package/config/ceremony-profiles.json +207 -0
  4. package/config/check-registry.json +114 -0
  5. package/config/matcher-registry.json +142 -0
  6. package/config/prove-evidence.schema.json +65 -0
  7. package/config/spec-policies.json +36 -0
  8. package/config/universal-rules.yaml +15 -0
  9. package/config/workflow-schema.json +279 -0
  10. package/lib/cli-commands.ts +7 -1
  11. package/lib/conformity.ts +965 -30
  12. package/lib/github.ts +195 -0
  13. package/lib/js-top-level-code.ts +27 -2
  14. package/lib/package-closure.ts +278 -2
  15. package/lib/release-preflight.ts +196 -0
  16. package/lib/scaffold/defaults.ts +40 -0
  17. package/lib/scaffold/managed-workflow.ts +125 -27
  18. package/lib/scaffold/owned-files.ts +6 -0
  19. package/lib/scaffold/profiles.ts +94 -0
  20. package/lib/scaffold/rehearsal.ts +27 -2
  21. package/lib/scaffold/steps.ts +654 -84
  22. package/lib/scaffold/write-steps.ts +50 -9
  23. package/lib/source-anchor.ts +144 -0
  24. package/lib/success-doc.ts +779 -0
  25. package/lib/suite-run-reading.ts +194 -0
  26. package/lib/test-census.ts +199 -0
  27. package/lib/trajectory.ts +377 -0
  28. package/lib/validators/spec-validators.ts +32 -4
  29. package/lib/workflow-security.ts +101 -0
  30. package/lib/workflow-test-harness.ts +349 -0
  31. package/package.json +6 -1
  32. package/scripts/create-success.ts +162 -0
  33. package/scripts/scaffold-project.ts +27 -3
  34. package/specs/SPEC-TEMPLATE.md +200 -0
  35. package/templates/SUCCESS-TEMPLATE.md +72 -0
  36. package/templates/agent-briefs/_shared.md +9 -0
  37. package/templates/agent-briefs/aditi.md +46 -0
  38. package/templates/agent-briefs/discovery.md +37 -0
  39. package/templates/agent-briefs/marcus.md +39 -0
  40. package/templates/agent-briefs/quinn.md +67 -0
  41. package/templates/agent-briefs/rook.md +40 -0
  42. 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
- addFrontmatterToSpecs(join(projectPath, "specs"), actions);
106
- addFrontmatterToAdrs(join(projectPath, "docs", "adr"), actions);
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 for ALL project types
142
- generateOrAuditProjectHarness(projectPath, actions);
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(projectPath, actions);
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
- createCiWorkflows(projectPath, actions, { force });
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
+ }