rungate 0.5.0 → 0.7.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/lib/affected-tests.ts +398 -0
- package/lib/agent-audit.ts +2 -3
- package/lib/agent-worktree.ts +287 -0
- package/lib/agents-md-sections.ts +209 -0
- package/lib/behavioral-cache.ts +150 -2
- package/lib/branch-diff.ts +139 -0
- package/lib/branch-protection.ts +790 -0
- package/lib/brief-ac-alignment.ts +104 -0
- package/lib/brief-references.ts +205 -0
- package/lib/bun-version.ts +347 -0
- package/lib/check-remedy.ts +140 -0
- package/lib/ci-checkout.ts +18 -1
- package/lib/ci-history-depth.ts +159 -0
- package/lib/ci-setup-step.ts +96 -0
- package/lib/claude-code-action.ts +85 -0
- package/lib/claude-tool-vocabulary.ts +188 -0
- package/lib/cli-commands.ts +15 -0
- package/lib/commit-sha.ts +42 -0
- package/lib/commit-subject.ts +90 -0
- package/lib/compliance-report.ts +377 -45
- package/lib/compliance.ts +196 -20
- package/lib/config-loader.ts +51 -1
- package/lib/config-trackable.ts +391 -0
- package/lib/conformity.ts +1272 -189
- package/lib/containment.ts +238 -0
- package/lib/content-hash.ts +24 -0
- package/lib/context-docs.ts +143 -28
- package/lib/create-brief.ts +2 -1
- package/lib/create-sc.ts +323 -4
- package/lib/dev-liveness.ts +180 -0
- package/lib/discovery-branch-points.ts +432 -0
- package/lib/discovery-stability.ts +481 -0
- package/lib/distribution-currency.ts +186 -0
- package/lib/doc-routing.ts +157 -0
- package/lib/doc-scan-targets.ts +9 -0
- package/lib/evidence-command-transport.ts +160 -0
- package/lib/evidence-prevalidator.ts +246 -2
- package/lib/evidence-satisfiability.ts +534 -12
- package/lib/failure-intake.ts +317 -0
- package/lib/fallow-availability.ts +286 -0
- package/lib/fs-write-capabilities.ts +232 -0
- package/lib/gate-refusal-currency.ts +112 -0
- package/lib/gate-run-split.ts +147 -0
- package/lib/gate-timeouts.ts +82 -0
- package/lib/generators/agent-briefs.ts +4 -1
- package/lib/generators/agents-md.ts +204 -48
- package/lib/generators/code-map.ts +2 -1
- package/lib/generators/types.ts +8 -0
- package/lib/git-dates.ts +55 -0
- package/lib/git-isolation.ts +140 -0
- package/lib/github.ts +15 -0
- package/lib/google-auth-action.ts +93 -0
- package/lib/harness-project.ts +48 -0
- package/lib/harness-provenance.ts +255 -0
- package/lib/hook-evidence.ts +235 -0
- package/lib/hook-scopes.ts +386 -0
- package/lib/hook-target-tree.ts +398 -0
- package/lib/hook-trees.ts +447 -0
- package/lib/js-top-level-code.ts +78 -10
- package/lib/junit-checks.ts +536 -0
- package/lib/launch-base.ts +253 -0
- package/lib/line-citation.ts +372 -0
- package/lib/local-calendar-day.ts +78 -0
- package/lib/orphan-reaper.ts +468 -0
- package/lib/parity-binding.ts +205 -0
- package/lib/per-test-timeouts.ts +219 -0
- package/lib/plan-coverage.ts +151 -0
- package/lib/prior-branch.ts +201 -8
- package/lib/process-table.ts +146 -0
- package/lib/project-state-derivation.ts +219 -0
- package/lib/project-state-root.ts +258 -0
- package/lib/project-state-shape.ts +59 -0
- package/lib/promote-outputs.ts +6 -2
- package/lib/published-artifact.ts +525 -0
- package/lib/readdir-sorted.ts +45 -0
- package/lib/report-provenance.ts +156 -0
- package/lib/review-execution-reading.ts +206 -0
- package/lib/review-tool-agreement.ts +433 -0
- package/lib/rule-promotion.ts +234 -0
- package/lib/rule-retirement.ts +525 -0
- package/lib/run-branch.ts +612 -0
- package/lib/rungate-schema.ts +19 -0
- package/lib/runner-home.ts +274 -0
- package/lib/sc-claim-forms.ts +75 -0
- package/lib/sc-id-cross-tree.ts +323 -0
- package/lib/sc-ids.ts +121 -13
- package/lib/sc-reservations.ts +289 -0
- package/lib/scaffold/ai-review-findings.ts +403 -0
- package/lib/scaffold/ai-review-step.ts +4777 -0
- package/lib/scaffold/managed-workflow.ts +587 -192
- package/lib/scaffold/owned-files.ts +186 -39
- package/lib/scaffold/pre-push-hook.ts +49 -5
- package/lib/scaffold/rehearsal.ts +205 -71
- package/lib/scaffold/steps.ts +1517 -293
- package/lib/scaffold/workflow-census.ts +217 -0
- package/lib/scaffold/workflow-drift.ts +217 -0
- package/lib/scaffold/write-steps.ts +10 -4
- package/lib/scan-budget.ts +247 -0
- package/lib/scanner.ts +80 -62
- package/lib/scratch-roots.ts +50 -5
- package/lib/screenshot-discovery.ts +121 -0
- package/lib/screenshot-upload.ts +41 -1
- package/lib/secret-patterns.ts +511 -8
- package/lib/ship-mode.ts +219 -0
- package/lib/source-slice.ts +294 -0
- package/lib/spec-listing.ts +148 -0
- package/lib/spec-requirements.ts +209 -0
- package/lib/stale-cleanup.ts +37 -3
- package/lib/suite-flake.ts +278 -0
- package/lib/suite-measurement.ts +23 -4
- package/lib/suite-run-reading.ts +411 -1
- package/lib/suite-timeout-margin.ts +193 -0
- package/lib/test-case-bodies.ts +883 -0
- package/lib/test-case-deletion.ts +653 -0
- package/lib/test-census.ts +97 -29
- package/lib/test-command-positions.ts +274 -0
- package/lib/test-command.ts +133 -0
- package/lib/test-suite-lock.ts +325 -26
- package/lib/tool-probe.ts +142 -0
- package/lib/top-level-cd.ts +393 -0
- package/lib/tracked-vs-ignored.ts +234 -0
- package/lib/tree-entries.ts +89 -0
- package/lib/ts-ast.ts +200 -0
- package/lib/validators/spec-validators.ts +3 -2
- package/lib/walk-test-files.ts +97 -0
- package/lib/workflow-actions.ts +263 -0
- package/lib/worktree-collect.ts +177 -5
- package/lib/worktree-repo.ts +36 -1
- package/package.json +2 -1
- package/scripts/ai-review-findings.ts +45 -0
- 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 +37 -7
- package/scripts/create-spec.ts +2 -1
- package/scripts/create-success.ts +2 -1
- package/scripts/extract-constraints.ts +197 -26
- package/scripts/generate-code-map.ts +62 -28
- package/scripts/scaffold-project.ts +12 -2
- package/scripts/split-spec.ts +2 -1
- package/scripts/sync-sc-status.ts +127 -14
- package/scripts/sync-spec-tests.ts +2 -1
|
@@ -13,6 +13,8 @@ import type { ProjectScan } from "./types";
|
|
|
13
13
|
import { OWNED_FILES, ownedFilesTable } from "../scaffold/owned-files";
|
|
14
14
|
import { isHarnessItself } from "../harness-identity";
|
|
15
15
|
import { typecheckDecision } from "../typescript-project";
|
|
16
|
+
import { localCalendarDay } from "../local-calendar-day";
|
|
17
|
+
import { resolveShipPolicy, shipWorkflowRule } from "../ship-mode";
|
|
16
18
|
|
|
17
19
|
/**
|
|
18
20
|
* Build the AGENTS.md frontmatter block.
|
|
@@ -22,36 +24,83 @@ import { typecheckDecision } from "../typescript-project";
|
|
|
22
24
|
* drop a hand-set owner, and emitting nothing — the previous behavior —
|
|
23
25
|
* stripped the block entirely on every re-scaffold.
|
|
24
26
|
*/
|
|
25
|
-
function
|
|
26
|
-
const
|
|
27
|
+
export function existingFrontmatter(root: string): Record<string, string> {
|
|
28
|
+
const path = join(root, "AGENTS.md");
|
|
29
|
+
const existing: Record<string, string> = {};
|
|
30
|
+
if (!existsSync(path)) return existing;
|
|
31
|
+
const content = readFileSync(path, "utf-8");
|
|
32
|
+
const match = content.match(/^---\n([\s\S]*?)\n---\n/);
|
|
33
|
+
if (!match) return existing;
|
|
34
|
+
for (const line of match[1].split("\n")) {
|
|
35
|
+
const kv = line.match(/^([\w-]+):\s*(.*)$/);
|
|
36
|
+
if (!kv) continue;
|
|
37
|
+
const value = kv[2].trim();
|
|
38
|
+
// Carry forward only simple scalars. The block is re-emitted verbatim,
|
|
39
|
+
// so a value holding a delimiter or control character could terminate
|
|
40
|
+
// the frontmatter early and turn the rest of the file into a second
|
|
41
|
+
// document — or smuggle keys past this loop on the next round-trip.
|
|
42
|
+
if (value.includes("---") || /[\x00-\x1f]/.test(value)) continue;
|
|
43
|
+
if (value.length > 200) continue;
|
|
44
|
+
existing[kv[1]] = value;
|
|
45
|
+
}
|
|
46
|
+
return existing;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* The committed AGENTS.md with its frontmatter block removed (#827).
|
|
51
|
+
*
|
|
52
|
+
* `null` means there is nothing to compare against — no file, or a file with
|
|
53
|
+
* no frontmatter block, which is a shape this generator has never written.
|
|
54
|
+
* Null and `""` are different facts and the caller must not conflate them:
|
|
55
|
+
* an absent file has no `updated:` to carry forward, so it gets today's.
|
|
56
|
+
*/
|
|
57
|
+
export function existingBody(root: string): string | null {
|
|
58
|
+
const path = join(root, "AGENTS.md");
|
|
59
|
+
if (!existsSync(path)) return null;
|
|
60
|
+
const content = readFileSync(path, "utf-8");
|
|
61
|
+
const match = content.match(/^---\n[\s\S]*?\n---\n\n/);
|
|
62
|
+
if (!match) return null;
|
|
63
|
+
return content.slice(match[0].length);
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* Build the AGENTS.md frontmatter block.
|
|
68
|
+
*
|
|
69
|
+
* Preserves whatever the existing file declared (owner, status, custom keys)
|
|
70
|
+
* and refreshes `updated:` ONLY when the body it is about actually changed.
|
|
71
|
+
* Regenerating from scratch would silently drop a hand-set owner, and
|
|
72
|
+
* emitting nothing — the behavior before #552 — stripped the block entirely
|
|
73
|
+
* on every re-scaffold.
|
|
74
|
+
*
|
|
75
|
+
* #827: `updated` used to be forced to today AFTER the spread, so it could
|
|
76
|
+
* never be carried forward and AGENTS.md could never be a fixed point of its
|
|
77
|
+
* own generator — the file stopped being one the morning after it was
|
|
78
|
+
* written, with no code or spec change in between. Dropping the field
|
|
79
|
+
* instead would make the file a fixed point and lose the freshness signal
|
|
80
|
+
* doc-hygiene wants, so neither of those is the fix. What the field claims
|
|
81
|
+
* to mean is "the date this file's content last changed", and deriving it
|
|
82
|
+
* from the body is what makes it mean that; the fixed point then falls out
|
|
83
|
+
* rather than being exempted into existence.
|
|
84
|
+
*
|
|
85
|
+
* @param bodyUnchanged the generator's body for this scan equals the one on
|
|
86
|
+
* disk. The caller computes the body first and answers
|
|
87
|
+
* this; the frontmatter is not in a position to.
|
|
88
|
+
*/
|
|
89
|
+
function buildFrontmatter(root: string, today: string, bodyUnchanged: boolean): string {
|
|
27
90
|
const defaults: Record<string, string> = {
|
|
28
91
|
"doc-type": "reference",
|
|
29
92
|
status: "active",
|
|
30
93
|
updated: today,
|
|
31
94
|
};
|
|
32
95
|
|
|
33
|
-
const
|
|
34
|
-
const existing: Record<string, string> = {};
|
|
35
|
-
if (existsSync(path)) {
|
|
36
|
-
const content = readFileSync(path, "utf-8");
|
|
37
|
-
const match = content.match(/^---\n([\s\S]*?)\n---\n/);
|
|
38
|
-
if (match) {
|
|
39
|
-
for (const line of match[1].split("\n")) {
|
|
40
|
-
const kv = line.match(/^([\w-]+):\s*(.*)$/);
|
|
41
|
-
if (!kv) continue;
|
|
42
|
-
const value = kv[2].trim();
|
|
43
|
-
// Carry forward only simple scalars. The block is re-emitted verbatim,
|
|
44
|
-
// so a value holding a delimiter or control character could terminate
|
|
45
|
-
// the frontmatter early and turn the rest of the file into a second
|
|
46
|
-
// document — or smuggle keys past this loop on the next round-trip.
|
|
47
|
-
if (value.includes("---") || /[\x00-\x1f]/.test(value)) continue;
|
|
48
|
-
if (value.length > 200) continue;
|
|
49
|
-
existing[kv[1]] = value;
|
|
50
|
-
}
|
|
51
|
-
}
|
|
52
|
-
}
|
|
96
|
+
const existing = existingFrontmatter(root);
|
|
53
97
|
|
|
54
|
-
|
|
98
|
+
// An existing stamp survives only when the body it dates is unchanged. A
|
|
99
|
+
// file with no stamp at all gets today's either way — there is nothing to
|
|
100
|
+
// carry, and a missing `updated:` is not evidence of freshness.
|
|
101
|
+
const stamp = bodyUnchanged ? (existing.updated ?? today) : today;
|
|
102
|
+
|
|
103
|
+
const merged: Record<string, string> = { ...defaults, ...existing, updated: stamp };
|
|
55
104
|
const order = ["doc-type", "status", "owner", "updated"];
|
|
56
105
|
const keys = [...order.filter(k => k in merged), ...Object.keys(merged).filter(k => !order.includes(k))];
|
|
57
106
|
return `---\n${keys.map(k => `${k}: ${merged[k]}`).join("\n")}\n---\n\n`;
|
|
@@ -62,7 +111,14 @@ export interface GeneratedRule {
|
|
|
62
111
|
content: string;
|
|
63
112
|
}
|
|
64
113
|
|
|
65
|
-
|
|
114
|
+
/**
|
|
115
|
+
* @param today the calendar day a CHANGED body is stamped with. Injectable
|
|
116
|
+
* so a test can advance the clock without advancing anything
|
|
117
|
+
* else — the whole of #827 is a field that moves when nothing
|
|
118
|
+
* else did, and a case that cannot change the date cannot see
|
|
119
|
+
* it. Defaults to the real day, so every caller is unchanged.
|
|
120
|
+
*/
|
|
121
|
+
export function generateAgentsMd(scan: ProjectScan, today: string = localCalendarDay()): string {
|
|
66
122
|
const {
|
|
67
123
|
name,
|
|
68
124
|
identity,
|
|
@@ -76,17 +132,28 @@ export function generateAgentsMd(scan: ProjectScan): string {
|
|
|
76
132
|
} = scan;
|
|
77
133
|
|
|
78
134
|
const techLine = techStack.length > 0 ? `\n**Tech:** ${techStack.join(", ")}` : "";
|
|
79
|
-
|
|
135
|
+
|
|
136
|
+
// #552. `scan.repoUrl` is `git remote get-url origin`, and a project with
|
|
137
|
+
// no remote called `origin` gets `""` — which this line turned into
|
|
138
|
+
// `<!-- TODO: Add repo URL -->`, twice, on every single run, with NOWHERE
|
|
139
|
+
// for the consumer to put the answer. `--profile=minimal` writes no
|
|
140
|
+
// `.claude/rungate/`, so there was no config key either, and editing
|
|
141
|
+
// AGENTS.md is futile because the next run regenerates it.
|
|
142
|
+
//
|
|
143
|
+
// The frontmatter is the place, because it is the one part of this file
|
|
144
|
+
// that already survives regeneration: `buildFrontmatter` carries forward
|
|
145
|
+
// every simple scalar the existing block declared. So `repo:` written once
|
|
146
|
+
// by hand persists, and the git remote stays the default when there is one.
|
|
147
|
+
const declaredRepo = existingFrontmatter(scan.root).repo;
|
|
148
|
+
const effectiveRepoUrl = repoUrl || (declaredRepo ?? "");
|
|
149
|
+
const repoLine = effectiveRepoUrl
|
|
150
|
+
? `- **Repo:** ${effectiveRepoUrl}`
|
|
151
|
+
: "<!-- TODO: Add repo URL — set `repo:` in this file's frontmatter, which survives regeneration -->";
|
|
80
152
|
|
|
81
153
|
const consumerSection = consumers.length > 0
|
|
82
154
|
? `\n## Consumers (${consumers.length})\n\n${consumers.map(c => `- ${c}`).join("\n")}\n\nCheck cascade impact when modifying shared modules.`
|
|
83
155
|
: "";
|
|
84
156
|
|
|
85
|
-
// Re-scaffolding used to strip AGENTS.md's frontmatter, because the
|
|
86
|
-
// generator never emitted any. Carry the existing block forward with a
|
|
87
|
-
// refreshed `updated:` so doc-hygiene keeps working across re-scaffolds.
|
|
88
|
-
const frontmatter = buildFrontmatter(scan.root);
|
|
89
|
-
|
|
90
157
|
// convert-spec is only advertised where the script actually exists —
|
|
91
158
|
// rungate has it, a scaffolded consumer may not. It was being dropped on
|
|
92
159
|
// every re-scaffold because the table did not know about it at all.
|
|
@@ -159,7 +226,12 @@ bunx rungate --help
|
|
|
159
226
|
|
|
160
227
|
Pin the version: re-scaffolding on a newer rungate rewrites generated files.`;
|
|
161
228
|
|
|
162
|
-
|
|
229
|
+
// Re-scaffolding used to strip AGENTS.md's frontmatter, because the
|
|
230
|
+
// generator never emitted any. Carry the existing block forward so
|
|
231
|
+
// doc-hygiene keeps working across re-scaffolds — and build the BODY
|
|
232
|
+
// first, because `updated:` is a statement about the body and cannot be
|
|
233
|
+
// decided before it exists (#827).
|
|
234
|
+
const body = `# ${name}
|
|
163
235
|
|
|
164
236
|
## Project Identity
|
|
165
237
|
|
|
@@ -191,6 +263,8 @@ ${consumerSection}
|
|
|
191
263
|
${repoLine}${makeTargets}
|
|
192
264
|
- **Test:** \`${testCmd}\`
|
|
193
265
|
`;
|
|
266
|
+
|
|
267
|
+
return buildFrontmatter(scan.root, today, body === existingBody(scan.root)) + body;
|
|
194
268
|
}
|
|
195
269
|
|
|
196
270
|
/**
|
|
@@ -263,28 +337,27 @@ description: Shared behavioral principles for all agents working in this project
|
|
|
263
337
|
`,
|
|
264
338
|
});
|
|
265
339
|
|
|
340
|
+
// The TEXT is not a constant any more (#911). A project that has decided to
|
|
341
|
+
// bypass the harness declares `ship.mode: "direct"` in its config, and this
|
|
342
|
+
// rule says so — with the date and the reason — instead of telling every
|
|
343
|
+
// agent the opposite of its instructions. `lib/ship-mode.ts` is the single
|
|
344
|
+
// decider; an unrecognised mode throws out of here rather than defaulting.
|
|
266
345
|
rules.push({
|
|
267
346
|
filename: "ship-workflow.md",
|
|
268
|
-
content:
|
|
269
|
-
description: All implementation work must go through the ship workflow — never spawn agents directly
|
|
270
|
-
---
|
|
271
|
-
|
|
272
|
-
## Ship Workflow Required
|
|
273
|
-
|
|
274
|
-
When shipping an issue or implementing code changes, use the ship workflow:
|
|
275
|
-
|
|
276
|
-
\`\`\`
|
|
277
|
-
Skill("ship") → Workflow({ scriptPath: "workflows/ship.js" })
|
|
278
|
-
\`\`\`
|
|
279
|
-
|
|
280
|
-
**NEVER spawn Marcus, Quinn, or Rook directly with the Agent tool.** The ship workflow captures transcripts, runs compliance grading, and enforces gates. Spawning agents directly bypasses all measurement.
|
|
281
|
-
|
|
282
|
-
If Skill("harness") or Skill("goal") fails, fall back to Skill("ship") with the issue number.
|
|
283
|
-
`,
|
|
347
|
+
content: shipWorkflowRule(resolveShipPolicy(scan.harnessConfig)),
|
|
284
348
|
});
|
|
285
349
|
|
|
286
350
|
if (specs.length > 0) {
|
|
287
|
-
|
|
351
|
+
// A row that sends a reader to a document stating no requirements says so
|
|
352
|
+
// in the row (#579). `specs/PROJECT-STATE.md` sat here for two months as
|
|
353
|
+
// the governing spec for project state management while being a rendered
|
|
354
|
+
// status snapshot, and the table was the reason anyone went there.
|
|
355
|
+
const specsTable = specs
|
|
356
|
+
.map(s => {
|
|
357
|
+
const governs = s.criteriaNone ? `STATES NO CRITERIA — ${s.governs}` : s.governs;
|
|
358
|
+
return `| ${s.file} | ${governs} | ${s.testable} |`;
|
|
359
|
+
})
|
|
360
|
+
.join("\n");
|
|
288
361
|
rules.push({
|
|
289
362
|
filename: "specs-routing.md",
|
|
290
363
|
content: `---
|
|
@@ -357,8 +430,58 @@ ${ownedFilesTable()}
|
|
|
357
430
|
| regenerate | Rewrites it every run; reports CHANGED only when the bytes differ |
|
|
358
431
|
| provenance | Rewrites it unless you edited it, in which case it is preserved and reported (#370) |
|
|
359
432
|
| job-preserving | Owns named jobs inside a file you also write to; your jobs are carried forward |
|
|
433
|
+
| section-preserving | Rewrites the file every run except for named sections, which are carried forward verbatim |
|
|
360
434
|
| create-only | Seeds it once and never touches it again — the content is yours, not the harness's |
|
|
361
435
|
|
|
436
|
+
### AGENTS.md is section-owned (#568)
|
|
437
|
+
|
|
438
|
+
Everything in \`AGENTS.md\` is generated from the scan and your
|
|
439
|
+
\`.claude/rungate/\` config, with one exception: a \`## Hard Constraints\`
|
|
440
|
+
section is yours, and a re-scaffold carries it forward verbatim —
|
|
441
|
+
including the \`<!-- BEGIN AUTO-EXTRACTED -->\` block, and including any
|
|
442
|
+
lines you wrote outside it.
|
|
443
|
+
|
|
444
|
+
It was the only user-owned content in the tree that survived
|
|
445
|
+
regeneration until #655, which is a promise \`specs/bootstrap-data-flow/\`
|
|
446
|
+
makes and nothing kept until #568: one run on a consumer removed 37
|
|
447
|
+
constraint lines and reported \`REGENERATED: AGENTS.md\`, exit 0. Put
|
|
448
|
+
non-inferable project rules there — the ones an agent cannot read off the
|
|
449
|
+
code — and nowhere else in the file.
|
|
450
|
+
|
|
451
|
+
If a run cannot carry every one of those lines forward it **refuses the
|
|
452
|
+
write**, names the lines, and leaves your file untouched.
|
|
453
|
+
|
|
454
|
+
### An agent brief is section-owned too (#655)
|
|
455
|
+
|
|
456
|
+
A rule mined from THIS repository's compliance history — the output of the
|
|
457
|
+
hill-climb loop — is non-inferable by construction, and until #655 it had
|
|
458
|
+
nowhere in the project to live. Every brief surface was rebuilt from
|
|
459
|
+
harness-wide inputs on the next \`bunx rungate scaffold .\`:
|
|
460
|
+
\`templates/agent-briefs/_shared.md\` resolves under the harness's own
|
|
461
|
+
templates directory, so a project rule written there reaches every
|
|
462
|
+
consumer; \`roles.json\`'s \`tiers.reinforcement\` carries section NAMES, not
|
|
463
|
+
rule text; and the write itself was a bare \`writeFileSync\`.
|
|
464
|
+
|
|
465
|
+
So \`.claude/agents/*.md\` now works the way \`AGENTS.md\` does, through the
|
|
466
|
+
same merge in \`lib/agents-md-sections.ts\`:
|
|
467
|
+
|
|
468
|
+
- Add a \`## Project Constraints\` heading to a brief and everything under
|
|
469
|
+
it, up to the next \`##\`, is yours. A re-scaffold carries it forward
|
|
470
|
+
verbatim and rewrites the rest.
|
|
471
|
+
- The section is **opt-in**. No template emits it, because a generated
|
|
472
|
+
section would collide with yours and the merge would refuse every run.
|
|
473
|
+
A heading plus one line is a section; a heading alone is not.
|
|
474
|
+
- If a run cannot carry every one of those lines forward it **refuses the
|
|
475
|
+
write**, names the lines, and leaves the brief untouched — the same
|
|
476
|
+
refusal-rather-than-silent-loss property #568 gave AGENTS.md.
|
|
477
|
+
- A reinforcement the hill-climb applies goes there in preference to
|
|
478
|
+
\`## Efficiency Rules\`, \`## Testing Rules\` or \`## Never Do\`, so what the
|
|
479
|
+
loop writes is the content a re-scaffold preserves.
|
|
480
|
+
|
|
481
|
+
The \`## Hard Constraints\` spelling is AGENTS.md's and only AGENTS.md's. A
|
|
482
|
+
brief section is scoped to one role; using one heading for both would make
|
|
483
|
+
a rule written in the wrong file look like it was in the right one.
|
|
484
|
+
|
|
362
485
|
### The workflow files are job-owned, not file-owned (#216)
|
|
363
486
|
|
|
364
487
|
rungate owns the \`test\` job in \`ci.yml\` and the \`gates\` job in
|
|
@@ -371,6 +494,39 @@ cannot carry a job forward — a flow mapping (\`jobs: {deploy: {...}}\`), or a
|
|
|
371
494
|
file it cannot parse — it **refuses the write**, names the jobs at risk and
|
|
372
495
|
the line delta, and leaves your file untouched. Re-run with \`--force\` only
|
|
373
496
|
if you mean to discard them.
|
|
497
|
+
|
|
498
|
+
### Every workflow file is reported, owned or not (#722)
|
|
499
|
+
|
|
500
|
+
The table above is a list of files this generator **writes**. That is why a
|
|
501
|
+
workflow it did not write could not be added to it: the next scaffold would
|
|
502
|
+
either start generating the file or the row would describe behaviour the
|
|
503
|
+
code does not have, which is #208 exactly.
|
|
504
|
+
|
|
505
|
+
So ownership travels with the bytes instead. Each generated workflow carries
|
|
506
|
+
a \`# generated-sha:\` marker on its first line — a YAML comment, invisible
|
|
507
|
+
to anything that parses the file — and a re-scaffold reports **every** file
|
|
508
|
+
in \`.github/workflows/\`:
|
|
509
|
+
|
|
510
|
+
| Status | What it means |
|
|
511
|
+
|--------|---------------|
|
|
512
|
+
| generated-and-unchanged | rungate wrote it and nobody has touched it |
|
|
513
|
+
| generated-and-hand-edited | rungate wrote it and the bytes have moved; preserved, not rewritten |
|
|
514
|
+
| NOT-OWNED | no marker — rungate did not write this and does not manage it |
|
|
515
|
+
|
|
516
|
+
**A NOT-OWNED workflow is reported by name and otherwise left alone.** What
|
|
517
|
+
you do with it is yours; the harness only refuses to keep quiet about it.
|
|
518
|
+
Each name is printed individually, because "5 unowned workflows" is not
|
|
519
|
+
something anybody can act on.
|
|
520
|
+
|
|
521
|
+
The line also carries its own coverage — \`read N/M file(s)\` — and a
|
|
522
|
+
directory that could not be read reports \`UNMEASURED\` rather than an empty
|
|
523
|
+
list. A scan that read 2 of 7 files and a scan that read all 7 are otherwise
|
|
524
|
+
the same clean report, and no reader can tell them apart from the output.
|
|
525
|
+
|
|
526
|
+
This matters on a tree the harness was added to rather than one it created.
|
|
527
|
+
One consumer ran five \`engine: copilot\` workflows that cost money, failed on
|
|
528
|
+
quota and emailed its owner, and every scaffold run reported clean — not
|
|
529
|
+
because anything went wrong, but because nothing had ever looked.
|
|
374
530
|
`,
|
|
375
531
|
});
|
|
376
532
|
|
|
@@ -5,6 +5,7 @@
|
|
|
5
5
|
* Takes scan data in, produces file content out. No file I/O.
|
|
6
6
|
*/
|
|
7
7
|
import type { ProjectScan } from "./types";
|
|
8
|
+
import { localCalendarDay } from "../local-calendar-day";
|
|
8
9
|
|
|
9
10
|
/**
|
|
10
11
|
* Generate CODE-MAP.md content from project scan data.
|
|
@@ -12,7 +13,7 @@ import type { ProjectScan } from "./types";
|
|
|
12
13
|
* Returns the full markdown string. Does NOT write files.
|
|
13
14
|
*/
|
|
14
15
|
export function generateCodeMap(scan: ProjectScan): string {
|
|
15
|
-
const today =
|
|
16
|
+
const today = localCalendarDay();
|
|
16
17
|
const { name, dirs, deps, devDeps, modules, routes } = scan;
|
|
17
18
|
|
|
18
19
|
let md = `---
|
package/lib/generators/types.ts
CHANGED
|
@@ -17,6 +17,14 @@ export interface SpecEntry {
|
|
|
17
17
|
file: string;
|
|
18
18
|
governs: string;
|
|
19
19
|
testable: string;
|
|
20
|
+
/**
|
|
21
|
+
* The spec declares `criteria: none` in its frontmatter (#579).
|
|
22
|
+
*
|
|
23
|
+
* Carried into the routing table rather than left in the file, because the
|
|
24
|
+
* reader harmed by a criteria-free spec is the one the table SENDS there.
|
|
25
|
+
* Optional so a consumer's scanner predating this still typechecks.
|
|
26
|
+
*/
|
|
27
|
+
criteriaNone?: boolean;
|
|
20
28
|
}
|
|
21
29
|
|
|
22
30
|
export interface TestFile {
|
package/lib/git-dates.ts
ADDED
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Every path's most recent commit date, from ONE git subprocess (#323).
|
|
3
|
+
*
|
|
4
|
+
* A LEAF module (#508). The implementation and its history live below,
|
|
5
|
+
* unchanged, moved out of `lib/conformity.ts` so a CLI can use it:
|
|
6
|
+
* conformity imports `bun:test` at module scope, and
|
|
7
|
+
* `scripts/extract-constraints.ts` runs outside a test runner. It is
|
|
8
|
+
* re-exported from `lib/conformity.ts`, which is the name every existing
|
|
9
|
+
* caller and SC-842 knows — one binding, two names, the same arrangement
|
|
10
|
+
* `isHarnessItself` has with `lib/harness-identity.ts` (#380).
|
|
11
|
+
*
|
|
12
|
+
* The second caller is why this moved. `computeStaleness` in
|
|
13
|
+
* `scripts/extract-constraints.ts` was still spawning one `git log` per
|
|
14
|
+
* document — the exact code #323 replaced here, in a file #323 did not
|
|
15
|
+
* touch — and HYGIENE-6 was timing out at 5001ms because of it.
|
|
16
|
+
*/
|
|
17
|
+
import { spawnSync } from "child_process";
|
|
18
|
+
import { existsSync } from "fs";
|
|
19
|
+
import { join } from "path";
|
|
20
|
+
|
|
21
|
+
export function lastCommitDates(root: string, pathspecs: string[]): Map<string, string> {
|
|
22
|
+
const lastCommit = new Map<string, string>();
|
|
23
|
+
// Not a git repository: nothing is tracked, so no path has a commit date.
|
|
24
|
+
// That is a real answer, not a failure, and scaffolded projects hit it.
|
|
25
|
+
if (!existsSync(join(root, ".git"))) return lastCommit;
|
|
26
|
+
if (pathspecs.length === 0) return lastCommit;
|
|
27
|
+
{
|
|
28
|
+
const log = spawnSync(
|
|
29
|
+
"git",
|
|
30
|
+
["-C", root, "log", "--format=%H %ci", "--name-only", "--", ...pathspecs],
|
|
31
|
+
{ timeout: 60_000, maxBuffer: 64 * 1024 * 1024 },
|
|
32
|
+
);
|
|
33
|
+
if (log.error) {
|
|
34
|
+
throw new Error(`lastCommitDates: git log could not run in ${root}: ${log.error.message}`);
|
|
35
|
+
}
|
|
36
|
+
if (log.status !== 0) {
|
|
37
|
+
throw new Error(
|
|
38
|
+
`lastCommitDates: git log exited ${log.status} in ${root}: ` +
|
|
39
|
+
`${log.stderr?.toString().trim() || "(no stderr)"}`,
|
|
40
|
+
);
|
|
41
|
+
}
|
|
42
|
+
let currentDate = "";
|
|
43
|
+
for (const line of log.stdout.toString().split("\n")) {
|
|
44
|
+
const header = /^[0-9a-f]{7,40} (\d{4}-\d{2}-\d{2})/.exec(line);
|
|
45
|
+
if (header) {
|
|
46
|
+
currentDate = header[1];
|
|
47
|
+
continue;
|
|
48
|
+
}
|
|
49
|
+
const path = line.trim();
|
|
50
|
+
if (!path || !currentDate) continue;
|
|
51
|
+
if (!lastCommit.has(path)) lastCommit.set(path, currentDate);
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
return lastCommit;
|
|
55
|
+
}
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The git-config isolation set, declared ONCE as data (#1001).
|
|
3
|
+
*
|
|
4
|
+
* ## Why this file exists rather than a second copy of a string
|
|
5
|
+
*
|
|
6
|
+
* `git` executes code out of its own configuration. `core.fsmonitor` is a
|
|
7
|
+
* command git runs, `core.hooksPath` points at hooks git fires, and
|
|
8
|
+
* `core.excludesFile` can make a file invisible to the reading that is
|
|
9
|
+
* supposed to see it. So **running `git` in a directory someone else chose
|
|
10
|
+
* means running whatever that directory's `.git/config` says**, and
|
|
11
|
+
* converting a shell string to an argv does nothing about it.
|
|
12
|
+
*
|
|
13
|
+
* That was measured once, under #960/#965, in a scratch repository with one
|
|
14
|
+
* planted untracked file (git 2.50.1):
|
|
15
|
+
*
|
|
16
|
+
* | poisoned key | written where | unisolated | isolated |
|
|
17
|
+
* |---|---|---|---|
|
|
18
|
+
* | `core.excludesFile` → a file listing the plant | `~/.gitconfig` | **plant INVISIBLE** | `?? planted.txt` |
|
|
19
|
+
* | `core.excludesFile` → a file listing the plant | the checkout's `.git/config` | **plant INVISIBLE** | `?? planted.txt` |
|
|
20
|
+
* | `core.fsmonitor` → a script touching a marker | `~/.gitconfig` | **marker written — git ran it** | not run |
|
|
21
|
+
* | `core.hooksPath` → a dir with `post-index-change` | `~/.gitconfig` | **hook fired** | not fired |
|
|
22
|
+
*
|
|
23
|
+
* **The lesson was learned once and propagated nowhere.** It lived as a
|
|
24
|
+
* single shell-prefix string inside `lib/scaffold/ai-review-step.ts`, so
|
|
25
|
+
* `hooks/CommitEnforcement.hook.ts` — which runs `git -C <a path out of an
|
|
26
|
+
* agent's reply text>` — could not reuse it even in principle: its call sites
|
|
27
|
+
* are `execFileSync('git', […])` and a shell prefix is not an argv.
|
|
28
|
+
*
|
|
29
|
+
* One declaration, two projections. `gitIsolatedShellPrefix()` reproduces the
|
|
30
|
+
* existing string exactly, so `AI_REVIEW_GIT_ISOLATED` is now derived rather
|
|
31
|
+
* than spelled; `gitIsolatedArgs`/`gitIsolatedEnv` serve the `execFileSync`
|
|
32
|
+
* callers. A second declaration of either is refused by
|
|
33
|
+
* `test/git-isolation.test.ts`.
|
|
34
|
+
*
|
|
35
|
+
* ## Why env vars AND `-c`, which is not belt-and-braces
|
|
36
|
+
*
|
|
37
|
+
* `GIT_CONFIG_GLOBAL`/`GIT_CONFIG_SYSTEM`/`GIT_CONFIG_NOSYSTEM` neutralise
|
|
38
|
+
* whole FILES, so they cover keys nobody thought to enumerate — but they do
|
|
39
|
+
* not touch the checkout's own `.git/config`, which is inside the tree being
|
|
40
|
+
* read. The `-c` flags are the only thing covering row two of the table, and
|
|
41
|
+
* command scope outranks local scope. **Neither covers the other.**
|
|
42
|
+
*
|
|
43
|
+
* ## `safe.directory='*'` is load-bearing, not a loosening
|
|
44
|
+
*
|
|
45
|
+
* `actions/checkout` writes `safe.directory` for the workspace into the
|
|
46
|
+
* GLOBAL config on every job. Neutralise the global file and that exception
|
|
47
|
+
* goes with it, so wherever the working tree is owned by a different uid than
|
|
48
|
+
* the process — containers, rootless self-hosted pools — `git` exits 128 with
|
|
49
|
+
* *"detected dubious ownership"*. `safe.directory` is honoured only from
|
|
50
|
+
* protected scopes (system, global, command), so `-c` restores it from the
|
|
51
|
+
* one source the subject cannot write, and the checkout's `.git/config` still
|
|
52
|
+
* cannot set it. Without it, isolation would be stricter than what it
|
|
53
|
+
* replaces in a way that fails closed on **green** repositories.
|
|
54
|
+
*
|
|
55
|
+
* ## WHAT THIS DOES NOT COVER
|
|
56
|
+
*
|
|
57
|
+
* - **Config a caller passes deliberately.** These are defaults a caller
|
|
58
|
+
* prepends; anything added after them wins.
|
|
59
|
+
* - **`git` subcommands that reach the network.** `fetch` with these env vars
|
|
60
|
+
* also discards a proxy, a CA bundle, or an `insteadOf` rewrite a
|
|
61
|
+
* self-hosted runner legitimately keeps in `~/.gitconfig`. That is a
|
|
62
|
+
* different trade-off and is why `buildRestoreScript` was left out of #960.
|
|
63
|
+
* - **The repository's CONTENT.** Isolating config is not reviewing a tree.
|
|
64
|
+
*
|
|
65
|
+
* Issue: #1001. Refs #960, #965.
|
|
66
|
+
*/
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Env vars neutralising whole config FILES.
|
|
70
|
+
*
|
|
71
|
+
* `GIT_CONFIG_NOSYSTEM=1` is not redundant with `GIT_CONFIG_SYSTEM=/dev/null`
|
|
72
|
+
* on every git version, so both are set.
|
|
73
|
+
*/
|
|
74
|
+
export const GIT_ISOLATION_ENV: Readonly<Record<string, string>> = Object.freeze({
|
|
75
|
+
GIT_CONFIG_GLOBAL: "/dev/null",
|
|
76
|
+
GIT_CONFIG_SYSTEM: "/dev/null",
|
|
77
|
+
GIT_CONFIG_NOSYSTEM: "1",
|
|
78
|
+
});
|
|
79
|
+
|
|
80
|
+
/**
|
|
81
|
+
* Keys overridden at COMMAND scope, which outranks the checkout's own
|
|
82
|
+
* `.git/config` — the one scope the env vars above cannot reach.
|
|
83
|
+
*
|
|
84
|
+
* `core.fsmonitor` is set to the empty string rather than removed: an empty
|
|
85
|
+
* value is how git spells "no fsmonitor", and there is no `-c` form that
|
|
86
|
+
* unsets a key.
|
|
87
|
+
*/
|
|
88
|
+
export const GIT_ISOLATION_CONFIG: ReadonlyArray<readonly [string, string]> = Object.freeze([
|
|
89
|
+
["core.fsmonitor", ""],
|
|
90
|
+
["core.excludesFile", "/dev/null"],
|
|
91
|
+
["core.hooksPath", "/dev/null"],
|
|
92
|
+
["safe.directory", "*"],
|
|
93
|
+
] as const);
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* The shell-prefix projection: `VAR=… VAR=… git -c k=v …`, ready to be
|
|
97
|
+
* interpolated in front of a subcommand in a generated script.
|
|
98
|
+
*
|
|
99
|
+
* `safe.directory`'s value is single-quoted because `*` would otherwise be
|
|
100
|
+
* glob-expanded by the shell. That quoting is a property of THIS projection
|
|
101
|
+
* and must not leak into the argv one, where the value is passed literally —
|
|
102
|
+
* a `'*'` reaching git through `execFileSync` would be three characters that
|
|
103
|
+
* match no directory, i.e. isolation that silently does not apply.
|
|
104
|
+
*/
|
|
105
|
+
export function gitIsolatedShellPrefix(): string {
|
|
106
|
+
const env = Object.entries(GIT_ISOLATION_ENV).map(([k, v]) => `${k}=${v}`).join(" ");
|
|
107
|
+
const flags = GIT_ISOLATION_CONFIG.map(([k, v]) => `-c ${k}=${shellQuoteIfGlob(v)}`).join(" ");
|
|
108
|
+
return `${env} git ${flags}`;
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/** Single-quote a value a shell would otherwise expand. */
|
|
112
|
+
function shellQuoteIfGlob(v: string): string {
|
|
113
|
+
return /[*?[\]]/.test(v) ? `'${v}'` : v;
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/**
|
|
117
|
+
* The argv projection: the `-c` flags, followed by whatever the caller
|
|
118
|
+
* passes.
|
|
119
|
+
*
|
|
120
|
+
* Pre-command options only, so a caller's own `-C <dir>` may follow in any
|
|
121
|
+
* order. Pair with `gitIsolatedEnv`; the flags alone leave `~/.gitconfig`
|
|
122
|
+
* live, and the env alone leaves the checkout's `.git/config` live.
|
|
123
|
+
*/
|
|
124
|
+
export function gitIsolatedArgs(args: readonly string[] = []): string[] {
|
|
125
|
+
const flags: string[] = [];
|
|
126
|
+
for (const [k, v] of GIT_ISOLATION_CONFIG) flags.push("-c", `${k}=${v}`);
|
|
127
|
+
return [...flags, ...args];
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/**
|
|
131
|
+
* `base` with the isolation vars applied on top.
|
|
132
|
+
*
|
|
133
|
+
* Takes the base environment as a parameter rather than reading
|
|
134
|
+
* `process.env`, so a case can drive it without touching the machine's.
|
|
135
|
+
*/
|
|
136
|
+
export function gitIsolatedEnv(
|
|
137
|
+
base: NodeJS.ProcessEnv = process.env,
|
|
138
|
+
): NodeJS.ProcessEnv {
|
|
139
|
+
return { ...base, ...GIT_ISOLATION_ENV };
|
|
140
|
+
}
|
package/lib/github.ts
CHANGED
|
@@ -37,6 +37,21 @@ export interface GitHubClient {
|
|
|
37
37
|
update: (params: { owner: string; repo: string; pull_number: number; [key: string]: any }) => Promise<{ data: any }>;
|
|
38
38
|
list: (params: { owner: string; repo: string; [key: string]: any }) => Promise<{ data: any[] }>;
|
|
39
39
|
};
|
|
40
|
+
repos: {
|
|
41
|
+
/** Repository metadata. `owner.type` and `default_branch` are what PROTECT-1 reads (#909). */
|
|
42
|
+
get: (params: { owner: string; repo: string }) => Promise<{ data: any }>;
|
|
43
|
+
/**
|
|
44
|
+
* One branch. Carries `protected`, and needs only read access (#909).
|
|
45
|
+
*
|
|
46
|
+
* Asked BEFORE `getBranchProtection`, which needs admin: a 404 from the
|
|
47
|
+
* protection endpoint means "unprotected" or "you are not an admin"
|
|
48
|
+
* with no way to tell which, and conflating those would let a token
|
|
49
|
+
* without admin report every repo clean.
|
|
50
|
+
*/
|
|
51
|
+
getBranch: (params: { owner: string; repo: string; branch: string }) => Promise<{ data: any }>;
|
|
52
|
+
/** Branch protection. Requires admin on the repo; 403 for everyone else. */
|
|
53
|
+
getBranchProtection: (params: { owner: string; repo: string; branch: string }) => Promise<{ data: any }>;
|
|
54
|
+
};
|
|
40
55
|
checks: {
|
|
41
56
|
/**
|
|
42
57
|
* Check runs for one ref (#46).
|