rungate 0.4.0 → 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 (65) 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/ac-quality.ts +119 -0
  11. package/lib/cli-commands.ts +7 -1
  12. package/lib/config-loader.ts +129 -5
  13. package/lib/conformity.ts +1122 -31
  14. package/lib/context-docs.ts +182 -0
  15. package/lib/create-brief.ts +22 -17
  16. package/lib/create-sc.ts +35 -8
  17. package/lib/doc-scan-targets.ts +435 -0
  18. package/lib/gate-check-audit.ts +9 -9
  19. package/lib/github.ts +195 -0
  20. package/lib/js-top-level-code.ts +27 -2
  21. package/lib/organize.ts +129 -40
  22. package/lib/package-closure.ts +387 -0
  23. package/lib/project-aliases.ts +100 -0
  24. package/lib/release-preflight.ts +352 -48
  25. package/lib/rungate-schema.ts +23 -1
  26. package/lib/sc-cover.ts +92 -1
  27. package/lib/sc-ids.ts +151 -0
  28. package/lib/scaffold/defaults.ts +40 -0
  29. package/lib/scaffold/managed-workflow.ts +125 -27
  30. package/lib/scaffold/owned-files.ts +6 -0
  31. package/lib/scaffold/profiles.ts +94 -0
  32. package/lib/scaffold/rehearsal.ts +355 -0
  33. package/lib/scaffold/steps.ts +787 -105
  34. package/lib/scaffold/write-steps.ts +208 -0
  35. package/lib/scratch-cleanup.ts +198 -0
  36. package/lib/scratch-roots.ts +94 -0
  37. package/lib/source-anchor.ts +144 -0
  38. package/lib/success-doc.ts +779 -0
  39. package/lib/suite-run-reading.ts +194 -0
  40. package/lib/test-census.ts +199 -0
  41. package/lib/trajectory.ts +377 -0
  42. package/lib/validators/spec-validators.ts +52 -35
  43. package/lib/workflow-security.ts +152 -7
  44. package/lib/workflow-test-harness.ts +349 -0
  45. package/lib/worktree-cleanup.ts +123 -7
  46. package/lib/worktree-repo.ts +165 -0
  47. package/package.json +10 -1
  48. package/scripts/audit-specs.ts +134 -37
  49. package/scripts/audit-transcript.ts +259 -0
  50. package/scripts/create-sc.ts +15 -1
  51. package/scripts/create-success.ts +162 -0
  52. package/scripts/detect-sc-drift.ts +200 -0
  53. package/scripts/extract-constraints.ts +16 -36
  54. package/scripts/scaffold-project.ts +51 -137
  55. package/scripts/split-spec.ts +315 -0
  56. package/scripts/sync-sc-status.ts +751 -0
  57. package/specs/SPEC-TEMPLATE.md +200 -0
  58. package/templates/SUCCESS-TEMPLATE.md +72 -0
  59. package/templates/agent-briefs/_shared.md +9 -0
  60. package/templates/agent-briefs/aditi.md +46 -0
  61. package/templates/agent-briefs/discovery.md +37 -0
  62. package/templates/agent-briefs/marcus.md +39 -0
  63. package/templates/agent-briefs/quinn.md +67 -0
  64. package/templates/agent-briefs/rook.md +40 -0
  65. package/templates/agent-briefs/serena.md +39 -0
@@ -1,11 +1,20 @@
1
1
  /**
2
- * config-loader.ts — Central config loader for rungate
2
+ * config-loader.ts — the one module that knows where rungate config LIVES
3
3
  *
4
4
  * Reads config from .claude/rungate/ directory (preferred) or
5
5
  * .claude/rungate.json (fallback). Merges directory files into
6
6
  * the same shape as the monolith for backward compatibility.
7
+ *
8
+ * It owns the WRITE side too (#415). ADR-002 D1 is usually quoted as "only
9
+ * this module may read the config", but the thing being centralised is the
10
+ * knowledge of which file a project's config is in, and a writer that answers
11
+ * that question for itself is a second answer to drift from. `create-brief`
12
+ * was the live instance: it built `.claude/rungate.json`, handed it to a
13
+ * writer, and on a project that had followed the documented migration printed
14
+ * "not found — role not registered", naming a file the project is documented
15
+ * not to have. The brief was written and the role was registered nowhere.
7
16
  */
8
- import { existsSync, readFileSync } from "fs";
17
+ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
9
18
  import { join } from "path";
10
19
  import { z } from "zod";
11
20
  import {
@@ -39,6 +48,14 @@ export interface ComplianceConfig {
39
48
  fileTypes: string[];
40
49
  artifactClassification: Record<string, string>;
41
50
  externalSources: OrganizeExternalSource[];
51
+ /**
52
+ * Names a cross-project document may call this project by (#442).
53
+ *
54
+ * Optional: the directory name and the GitHub slug are derived from the
55
+ * tree, so this is only for what a human knows — the abbreviation, the
56
+ * product name, the thing the team says out loud.
57
+ */
58
+ aliases?: string[];
42
59
  };
43
60
  }
44
61
 
@@ -98,7 +115,13 @@ export const DEFAULT_TEST_TIMEOUT = 120000;
98
115
  * Malformed JSON and orphaned fragments THROW, per ADR-001 D2. Unchanged.
99
116
  */
100
117
  export type ConfigResolution =
101
- | { status: "resolved"; config: ResolvedConfig; source: "directory" | "monolith" }
118
+ | {
119
+ status: "resolved";
120
+ config: ResolvedConfig;
121
+ source: "directory" | "monolith";
122
+ /** The directory or file the config was read from (#415). */
123
+ path: string;
124
+ }
102
125
  | { status: "absent" };
103
126
 
104
127
  const DIRECTORY_CONFIG_FILES = ["config.json", "roles.json", "hooks.json", "compliance.json"];
@@ -143,11 +166,21 @@ export function resolveConfig(projectRoot: string): ConfigResolution {
143
166
  // and silently drop issueRepo/ci/test — ADR-001 Step E keeps the monolith
144
167
  // in place during migration, so that state is on the normal upgrade path.
145
168
  if (existsSync(join(dirPath, "config.json"))) {
146
- return { status: "resolved", config: loadFromDirectory(dirPath), source: "directory" };
169
+ return {
170
+ status: "resolved",
171
+ config: loadFromDirectory(dirPath),
172
+ source: "directory",
173
+ path: dirPath,
174
+ };
147
175
  }
148
176
 
149
177
  if (existsSync(monolithPath)) {
150
- return { status: "resolved", config: loadFromMonolith(monolithPath), source: "monolith" };
178
+ return {
179
+ status: "resolved",
180
+ config: loadFromMonolith(monolithPath),
181
+ source: "monolith",
182
+ path: monolithPath,
183
+ };
151
184
  }
152
185
 
153
186
  // Fragments with no config.json and no monolith is a broken directory
@@ -209,6 +242,97 @@ function readJson(path: string): any {
209
242
  return JSON.parse(readFileSync(path, "utf-8"));
210
243
  }
211
244
 
245
+ /**
246
+ * Register a role in whichever layout the project is actually on (#415).
247
+ *
248
+ * The counterpart to `loadRoleConfig`, and deliberately in the same module:
249
+ * the writer has to make the same choice between the two layouts that the
250
+ * reader makes, and a second place making it is how `create-brief` came to
251
+ * write a monolith a migrated consumer does not have.
252
+ *
253
+ * Throws on an unscaffolded project. There is no third branch that invents a
254
+ * layout — a tool that creates `.claude/rungate.json` beside an existing
255
+ * `.claude/rungate/` gives the project two role sets and lets whichever the
256
+ * reader prefers decide what the project is, which is #70 one layer up.
257
+ *
258
+ * Returns the file written, so a caller can say where the role went rather
259
+ * than naming a path it guessed.
260
+ */
261
+ export function writeRoleConfig(
262
+ projectRoot: string,
263
+ roleName: string,
264
+ role: unknown,
265
+ ): string {
266
+ const resolution = resolveConfig(projectRoot);
267
+ if (resolution.status === "absent") {
268
+ throw new Error(
269
+ `No rungate config found under ${join(projectRoot, ".claude")} — ` +
270
+ `scaffold the project before registering a role`,
271
+ );
272
+ }
273
+
274
+ const target =
275
+ resolution.source === "directory"
276
+ ? join(resolution.path, "roles.json")
277
+ : resolution.path;
278
+
279
+ const existing = existsSync(target) ? readJson(target) : {};
280
+ const roles = resolution.source === "directory" ? existing : (existing.roles ??= {});
281
+
282
+ if (roles[roleName]) {
283
+ throw new Error(`Role '${roleName}' already exists in ${target}`);
284
+ }
285
+ roles[roleName] = role;
286
+
287
+ writeFileSync(target, JSON.stringify(existing, null, 2) + "\n");
288
+ return target;
289
+ }
290
+
291
+ /** Whether a scaffold wrote, or stepped aside because something was there. */
292
+ export type ScaffoldWriteResult =
293
+ | { status: "created"; path: string }
294
+ | { status: "exists"; path: string };
295
+
296
+ /**
297
+ * Create a project's config in the DIRECTORY layout (#415).
298
+ *
299
+ * `scripts/scaffold-rungate-config.ts` built these four paths itself, which
300
+ * put two modules in the business of knowing the layout — and left the
301
+ * scaffolder banked in the config-access ratchet at a number no migration
302
+ * could ever lower, because there was no read to migrate.
303
+ *
304
+ * **The "already there" decision lives here and only here.** The script used
305
+ * to make it as well, which made this one unreachable: a mutation that
306
+ * deleted it left the caller's copy still refusing, so the guard measured as
307
+ * load-bearing while nothing depended on it. Two deciders that agree are
308
+ * behaviourally one.
309
+ *
310
+ * Returns rather than throwing, so the caller reports the outcome without
311
+ * having to sniff an exception message for a prefix.
312
+ */
313
+ export function writeScaffoldedConfig(
314
+ projectRoot: string,
315
+ parts: { config: unknown; roles: unknown; hooks: unknown; compliance: unknown },
316
+ ): ScaffoldWriteResult {
317
+ const resolution = resolveConfig(projectRoot);
318
+ if (resolution.status === "resolved") {
319
+ return { status: "exists", path: resolution.path };
320
+ }
321
+
322
+ const dirPath = join(projectRoot, ".claude", "rungate");
323
+ mkdirSync(dirPath, { recursive: true });
324
+ const files: Array<[string, unknown]> = [
325
+ ["config.json", parts.config],
326
+ ["roles.json", parts.roles],
327
+ ["hooks.json", parts.hooks],
328
+ ["compliance.json", parts.compliance],
329
+ ];
330
+ for (const [name, body] of files) {
331
+ writeFileSync(join(dirPath, name), JSON.stringify(body, null, 2) + "\n");
332
+ }
333
+ return { status: "created", path: dirPath };
334
+ }
335
+
212
336
  export function loadComplianceConfig(projectRoot: string): ComplianceConfig | null {
213
337
  const dirPath = join(projectRoot, ".claude", "rungate", "compliance.json");
214
338
  if (existsSync(dirPath)) {