rungate 0.2.0 → 0.3.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 (282) hide show
  1. package/bin/rungate.ts +70 -0
  2. package/lib/aes-calculator.ts +66 -0
  3. package/lib/agent-audit.ts +139 -0
  4. package/lib/agent-brief-validation.ts +359 -0
  5. package/lib/agents-md-refs.ts +90 -0
  6. package/lib/bash-file-read.ts +197 -0
  7. package/lib/behavioral-cache.ts +78 -0
  8. package/lib/branch-cleanup.ts +234 -0
  9. package/lib/brief-context-parser.ts +35 -0
  10. package/lib/canary.ts +117 -0
  11. package/lib/check-registry.ts +226 -0
  12. package/lib/ci-checkout.ts +400 -0
  13. package/lib/cli-commands.ts +137 -0
  14. package/lib/compliance-backfill.ts +220 -0
  15. package/lib/compliance-report.ts +504 -0
  16. package/lib/compliance.ts +361 -0
  17. package/lib/config-loader.ts +255 -0
  18. package/lib/conformity.ts +1818 -131
  19. package/lib/container-provenance.ts +230 -0
  20. package/lib/create-brief.ts +150 -0
  21. package/lib/create-sc.ts +272 -0
  22. package/lib/deep-merge.ts +69 -0
  23. package/lib/dev-liveness.ts +214 -0
  24. package/lib/directive-extractor.ts +210 -0
  25. package/lib/distribution-standing.ts +113 -0
  26. package/lib/doc-hygiene.ts +238 -0
  27. package/lib/eval-criteria.ts +6 -0
  28. package/lib/evidence-portability.ts +123 -0
  29. package/lib/evidence-prevalidator.ts +390 -0
  30. package/lib/evidence-required.ts +150 -0
  31. package/lib/evidence-satisfiability.ts +288 -0
  32. package/lib/frontmatter.ts +163 -0
  33. package/lib/gap-scanner.ts +348 -0
  34. package/lib/gate-enforcement.ts +366 -0
  35. package/lib/generators/agent-briefs.ts +136 -0
  36. package/lib/generators/agents-md.ts +506 -0
  37. package/lib/generators/code-map.ts +60 -0
  38. package/lib/generators/types.ts +184 -0
  39. package/lib/git-ref-normalizer.ts +107 -0
  40. package/lib/github.ts +539 -0
  41. package/lib/harness-identity.ts +63 -0
  42. package/lib/hill-climb.ts +164 -0
  43. package/lib/instruction-effectiveness.ts +131 -0
  44. package/lib/issue-closure-audit.ts +225 -0
  45. package/lib/issue-create-override.ts +343 -0
  46. package/lib/js-top-level-code.ts +250 -0
  47. package/lib/liveness-contradiction.ts +149 -0
  48. package/lib/organize.ts +505 -0
  49. package/lib/paths.ts +197 -6
  50. package/lib/post-fix-verify.ts +157 -0
  51. package/lib/prior-branch.ts +489 -0
  52. package/lib/project-state-shape.ts +166 -0
  53. package/lib/promote-outputs.ts +156 -0
  54. package/lib/prove-label-gate.ts +35 -0
  55. package/lib/reachability.ts +302 -0
  56. package/lib/release-preflight.ts +186 -0
  57. package/lib/rule-health-pipeline.ts +264 -0
  58. package/lib/rule-health-trend.ts +161 -0
  59. package/lib/rule-provenance.ts +149 -0
  60. package/lib/rule-registry.ts +128 -0
  61. package/lib/rungate-schema.ts +114 -4
  62. package/lib/sc-claim-forms.ts +179 -0
  63. package/lib/sc-cover.ts +150 -0
  64. package/lib/sc-guard.ts +157 -0
  65. package/lib/sc-ids.ts +344 -0
  66. package/lib/scaffold/defaults.ts +165 -0
  67. package/lib/scaffold/managed-workflow.ts +370 -0
  68. package/lib/scaffold/owned-files.ts +265 -0
  69. package/lib/scaffold/steps.ts +2680 -0
  70. package/lib/scanner.ts +701 -0
  71. package/lib/screenshot-upload.ts +73 -0
  72. package/lib/secret-patterns.ts +112 -0
  73. package/lib/security-verdict.ts +616 -0
  74. package/lib/signal-phrases.ts +1 -0
  75. package/lib/spec-change-conformity.ts +80 -0
  76. package/lib/spec-files.ts +62 -0
  77. package/lib/spec-registry.ts +133 -0
  78. package/lib/spec-updater.ts +96 -0
  79. package/lib/stale-cleanup.ts +224 -0
  80. package/lib/stale-issue-scanner.ts +36 -0
  81. package/lib/strip-js-comments.ts +269 -0
  82. package/lib/suite-measurement.ts +228 -0
  83. package/lib/task-completion-checks.ts +177 -0
  84. package/lib/test-suite-lock.ts +1136 -0
  85. package/lib/transcript-checker.ts +1140 -0
  86. package/lib/validators/spec-validators.ts +171 -0
  87. package/lib/verdict-capture.ts +73 -0
  88. package/lib/verified-push.ts +358 -0
  89. package/lib/workflow-security.ts +174 -0
  90. package/lib/worktree-cleanup.ts +250 -0
  91. package/lib/worktree-collect.ts +283 -0
  92. package/lib/worktree-isolation.ts +82 -0
  93. package/package.json +36 -3
  94. package/prompts/ac-adversary.md +14 -2
  95. package/prompts/aditi.md +5 -0
  96. package/prompts/blast-radius.md +5 -0
  97. package/prompts/container-verify.md +5 -0
  98. package/prompts/discovery.md +4 -0
  99. package/prompts/environment.md +5 -0
  100. package/prompts/evidence-hierarchy.md +5 -0
  101. package/prompts/evidence-validator.md +11 -0
  102. package/prompts/marcus.md +5 -0
  103. package/prompts/prevention.md +5 -0
  104. package/prompts/prove-reproducer.md +12 -0
  105. package/prompts/quinn-decision-tree.md +5 -0
  106. package/prompts/quinn-ui-brief.md +5 -0
  107. package/prompts/quinn.md +5 -0
  108. package/prompts/rca.md +5 -0
  109. package/prompts/read-before-write.md +4 -0
  110. package/prompts/regression.md +5 -0
  111. package/prompts/serena.md +5 -0
  112. package/scripts/audit-specs.ts +464 -0
  113. package/scripts/convert-spec.ts +293 -0
  114. package/scripts/create-sc.ts +92 -0
  115. package/scripts/create-spec.ts +166 -0
  116. package/scripts/extract-constraints.ts +4 -3
  117. package/scripts/generate-code-map.ts +1 -1
  118. package/scripts/scaffold-project.ts +138 -1426
  119. package/scripts/sync-spec-tests.ts +211 -126
  120. package/.claude/agents/aditi.md +0 -47
  121. package/.claude/agents/marcus.md +0 -50
  122. package/.claude/agents/quinn.md +0 -58
  123. package/.claude/agents/rook.md +0 -47
  124. package/.claude/agents/serena.md +0 -46
  125. package/.claude/rungate.json +0 -11
  126. package/.fallowrc.json +0 -28
  127. package/.github/copilot-instructions.md +0 -20
  128. package/.rungate/conformity-findings.json +0 -648
  129. package/AGENTS.md +0 -106
  130. package/CODE-MAP.md +0 -50
  131. package/HARNESS.md +0 -88
  132. package/bun.lock +0 -26
  133. package/bunfig.toml +0 -2
  134. package/config/brief-policies.json +0 -28
  135. package/config/ceremony-profiles.json +0 -212
  136. package/config/consumer-cascade-map.json +0 -24
  137. package/config/doc-cascade-map.json +0 -24
  138. package/config/eval.json +0 -84
  139. package/config/profiles/account-plan.yaml +0 -36
  140. package/config/profiles/campaign.yaml +0 -94
  141. package/config/prove-evidence.schema.json +0 -65
  142. package/config/spec-policies.json +0 -36
  143. package/config/workflow-schema.json +0 -281
  144. package/gates/SCHEMA-GUIDE.md +0 -121
  145. package/gates/ac-quality.test.ts +0 -106
  146. package/gates/adversarial.test.ts +0 -274
  147. package/gates/brief-assembler.test.ts +0 -429
  148. package/gates/brief-assembler.ts +0 -334
  149. package/gates/bunfig.toml +0 -2
  150. package/gates/chain.test.ts +0 -91
  151. package/gates/e2e-smoke.test.ts +0 -234
  152. package/gates/error-classifier.test.ts +0 -249
  153. package/gates/error-classifier.ts +0 -89
  154. package/gates/orchestrator.test.ts +0 -950
  155. package/gates/orchestrator.ts +0 -569
  156. package/gates/preload.ts +0 -77
  157. package/gates/prompts/ac-adversary.md +0 -20
  158. package/gates/prompts/evidence-validator.md +0 -22
  159. package/gates/prompts/prove-reproducer.md +0 -53
  160. package/gates/prove.test.ts +0 -164
  161. package/gates/run-gate.ts +0 -936
  162. package/gates/schema-parity.test.ts +0 -197
  163. package/gates/schema.ts +0 -362
  164. package/gates/self-heal.test.ts +0 -511
  165. package/gates/self-heal.ts +0 -121
  166. package/gates/ship-orchestrator.test.ts +0 -379
  167. package/gates/ship-orchestrator.ts +0 -363
  168. package/gates/test-fixtures/broken-no-environments.json +0 -60
  169. package/gates/test-fixtures/valid-standard.json +0 -54
  170. package/gates/test-utils.ts +0 -43
  171. package/gates/witness.ts +0 -220
  172. package/gates/workflow.test.ts +0 -1053
  173. package/hooks/AgentBriefGuard.hook.ts +0 -586
  174. package/hooks/AgentVerdictCapture.hook.ts +0 -134
  175. package/hooks/AutoVerifyGate.hook.ts +0 -76
  176. package/hooks/GateEnforcement.hook.ts +0 -273
  177. package/hooks/IssueCloseGuard.hook.ts +0 -116
  178. package/hooks/MergeGuard.hook.ts +0 -55
  179. package/hooks/StaleTTLCleanup.hook.ts +0 -133
  180. package/hooks/VerifyPhaseLock.hook.ts +0 -81
  181. package/hooks/WorkflowStateGuard.hook.ts +0 -37
  182. package/hooks/lib/agentDetection.ts +0 -70
  183. package/hooks/lib/findWorkflow.ts +0 -101
  184. package/hooks/lib/parseStdin.ts +0 -37
  185. package/hooks/lib/paths.ts +0 -111
  186. package/hooks/lib/utils.ts +0 -81
  187. package/reference/migration-manifest.json +0 -554
  188. package/reference/prompts/agent-aditi.md +0 -38
  189. package/reference/prompts/agent-marcus.md +0 -38
  190. package/reference/prompts/agent-quinn.md +0 -38
  191. package/reference/prompts/agent-rook.md +0 -37
  192. package/reference/prompts/agent-serena.md +0 -37
  193. package/reference/prompts/council-skill.md +0 -170
  194. package/reference/prompts/goal-skill.md +0 -235
  195. package/reference/prompts/prove-skill.md +0 -283
  196. package/reference/prompts/quinn-standard.md +0 -246
  197. package/reference/prompts/ship-convergence.md +0 -65
  198. package/reference/prompts/ship-escalation.md +0 -43
  199. package/reference/prompts/ship-iteration.md +0 -382
  200. package/reference/prompts/ship-pending-patches.md +0 -246
  201. package/reference/prompts/ship-reference.md +0 -250
  202. package/reference/prompts/ship-skill.md +0 -347
  203. package/reference/prompts/ship-templates.md +0 -215
  204. package/reference/scripts/batch-status.sh +0 -68
  205. package/reference/scripts/chain-compat-check.sh +0 -67
  206. package/reference/scripts/context-audit.sh +0 -314
  207. package/reference/scripts/dead-export-check.sh +0 -61
  208. package/reference/scripts/generate-qc-tables.sh +0 -92
  209. package/reference/scripts/harness-init.sh +0 -111
  210. package/reference/scripts/pai-054-baseline-check.sh +0 -40
  211. package/reference/scripts/prove-smoke-test.sh +0 -112
  212. package/reference/scripts/setup-keychain-salt.sh +0 -12
  213. package/reference/scripts/skill-optimizer-friday.sh +0 -88
  214. package/reference/scripts/skill-qc-test.sh +0 -351
  215. package/reference/scripts/skill-synthesize-tonight.sh +0 -66
  216. package/reference/specs/HARNESS-EXTRACTION-SPEC.md +0 -263
  217. package/reference/specs/harness-v3-bash-deletion-plan.md +0 -65
  218. package/reference/specs/harness-v3-migration-plan.md +0 -188
  219. package/scripts/decision-reconcile.sh +0 -74
  220. package/scripts/decision-reconcile.ts +0 -152
  221. package/scripts/git-hooks/pre-commit +0 -76
  222. package/scripts/git-hooks/pre-push +0 -271
  223. package/scripts/harness-skill-check.sh +0 -52
  224. package/scripts/lib/gap-emit.sh +0 -65
  225. package/scripts/lib/jq-update.sh +0 -30
  226. package/scripts/lib/resolve-slug.sh +0 -30
  227. package/scripts/lib/verify-spec-compliance.sh +0 -102
  228. package/scripts/prove-backfill.sh +0 -87
  229. package/scripts/scaffold-rungate-config.ts +0 -91
  230. package/scripts/self-containment-check.sh +0 -109
  231. package/scripts/skill-qc-validator.sh +0 -402
  232. package/scripts/slug-resolver.sh +0 -14
  233. package/specs/BOOTSTRAP-DATA-FLOW-SPEC.md +0 -2493
  234. package/specs/BOOTSTRAP-TEST-PLAN.md +0 -571
  235. package/specs/HARNESS-GATES.md +0 -256
  236. package/specs/HARNESS-SKILL-CHAIN.md +0 -286
  237. package/specs/HARNESS-SKILL-CONTRACT.md +0 -93
  238. package/specs/HARNESS-STANDARD.md +0 -488
  239. package/specs/SPEC-TEMPLATE.md +0 -53
  240. package/specs/bootstrap-data-flow.png +0 -0
  241. package/specs/harness-automation-matrix.md +0 -314
  242. package/specs/harness-automation-matrix.rules.json +0 -64
  243. package/test/anti.test.ts +0 -80
  244. package/test/contract-negative.test.ts +0 -86
  245. package/test/contract.test.ts +0 -158
  246. package/test/external-deps.test.ts +0 -48
  247. package/test/fixtures/golden-project/.env.example +0 -3
  248. package/test/fixtures/golden-project/Makefile +0 -7
  249. package/test/fixtures/golden-project/docs/adr/ADR-001-framework.md +0 -23
  250. package/test/fixtures/golden-project/docs/setup-guide.md +0 -10
  251. package/test/fixtures/golden-project/package.json +0 -10
  252. package/test/fixtures/golden-project/specs/api-spec.md +0 -20
  253. package/test/fixtures/golden-project/src/auth.ts +0 -8
  254. package/test/fixtures/golden-project/src/db.ts +0 -11
  255. package/test/fixtures/golden-project/src/index.ts +0 -19
  256. package/test/fixtures/golden-project/src/utils/format.ts +0 -3
  257. package/test/fixtures/golden-project/test/auth.test.ts +0 -15
  258. package/test/fixtures/golden-project/tsconfig.json +0 -12
  259. package/test/meta-sc-coverage.test.ts +0 -159
  260. package/test/phase-0.test.ts +0 -846
  261. package/test/phase-1.test.ts +0 -617
  262. package/test/phase-2.test.ts +0 -620
  263. package/test/phase-3.test.ts +0 -99
  264. package/test/scaffold-conformity.test.ts +0 -8
  265. package/test/schema-canary.test.ts +0 -51
  266. package/test/spec-compliance-auto.test.ts +0 -64
  267. package/test/spec-compliance.test.ts +0 -295
  268. package/test/spec-discovery.test.ts +0 -68
  269. package/test/spec-drift.test.ts +0 -5
  270. package/test/structure.test.ts +0 -165
  271. package/test/unit/agent-brief-guard-ship.test.ts +0 -293
  272. package/test/unit/extract-constraints.test.ts +0 -145
  273. package/test/unit/issue-close-guard.test.ts +0 -204
  274. package/test/unit/scaffold-project.test.ts +0 -417
  275. package/test/unit/skill-cooccurrence.test.ts +0 -177
  276. package/test/unit/skill-sequence-logger.test.ts +0 -244
  277. package/test/unit/workflow-state-guard.test.ts +0 -95
  278. package/workflows/batch-ship.js +0 -295
  279. package/workflows/council.js +0 -481
  280. package/workflows/prove.js +0 -560
  281. package/workflows/ship.js +0 -789
  282. package/workflows/verify.js +0 -236
@@ -0,0 +1,174 @@
1
+ import { createHash, timingSafeEqual } from "crypto";
2
+
3
+ const SHELL_METACHARACTERS = /[;&|$`\n\r"'\\(){}[\]<>!~*?#]/;
4
+ const PATH_TRAVERSAL = /\.\.($|[/\\])/;
5
+ const NULL_BYTE = /\x00/;
6
+
7
+ export function buildSafeGitAdd(filesChanged: string[]): string {
8
+ const validated = validateFilePaths(filesChanged);
9
+ if (validated.rejected.length > 0) {
10
+ throw new Error(
11
+ `Rejected unsafe file paths: ${validated.rejected.join(", ")}`,
12
+ );
13
+ }
14
+ if (validated.valid.length === 0) throw new Error("No valid files to stage");
15
+ return `git add ${validated.valid.map((f) => `'${f.replace(/'/g, "'\\''")}'`).join(" ")}`;
16
+ }
17
+
18
+ export function validateFilePaths(
19
+ paths: string[],
20
+ ): { valid: string[]; rejected: string[] } {
21
+ const valid: string[] = [];
22
+ const rejected: string[] = [];
23
+ for (const p of paths) {
24
+ if (
25
+ SHELL_METACHARACTERS.test(p) ||
26
+ PATH_TRAVERSAL.test(p) ||
27
+ NULL_BYTE.test(p) ||
28
+ p.startsWith("/") ||
29
+ p.length > 500
30
+ ) {
31
+ rejected.push(p);
32
+ } else {
33
+ valid.push(p);
34
+ }
35
+ }
36
+ return { valid, rejected };
37
+ }
38
+
39
+ /**
40
+ * Whether a string is safe to interpolate into a git or `gh` command as a
41
+ * branch name.
42
+ *
43
+ * #136 made branch names flow from the run into commands: the PR head is now
44
+ * `${shipBranch}` rather than something a checkout is asked for at the time.
45
+ * That is the right direction — an agent recovering from a failed push chose
46
+ * `HEAD:main` once — but the value still reaches a shell, and it originates
47
+ * from an agent's reply or from a PR listing, neither of which this process
48
+ * wrote.
49
+ *
50
+ * Git's own rules are looser than this (`git check-ref-format`). The extra
51
+ * strictness is deliberate: every character git allows but this rejects is
52
+ * one that means something to a shell, and no branch this harness creates
53
+ * needs any of them.
54
+ */
55
+ const SAFE_BRANCH = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/;
56
+
57
+ export function isSafeBranchName(name: unknown): name is string {
58
+ if (typeof name !== "string" || name.length === 0 || name.length > 255) return false;
59
+ if (!SAFE_BRANCH.test(name)) return false;
60
+ // Git's own refusals, and the ones that matter here: `..` would let a
61
+ // branch argument climb out of a refspec, and a leading `-` would be read
62
+ // as a flag by git and by gh alike.
63
+ if (name.includes("..") || name.includes("//") || name.endsWith("/") || name.endsWith(".lock")) return false;
64
+ return true;
65
+ }
66
+
67
+ export function resolveEvidencePath(
68
+ basePath: string,
69
+ evidencePath: string,
70
+ ): string {
71
+ if (NULL_BYTE.test(evidencePath)) {
72
+ throw new Error(`Evidence path contains null byte: ${evidencePath}`);
73
+ }
74
+ if (PATH_TRAVERSAL.test(evidencePath)) {
75
+ throw new Error(`Evidence path contains traversal: ${evidencePath}`);
76
+ }
77
+ if (evidencePath.startsWith("/")) {
78
+ throw new Error(`Evidence path is absolute: ${evidencePath}`);
79
+ }
80
+ const resolved = `${basePath}/${evidencePath}`;
81
+ if (!resolved.startsWith(basePath)) {
82
+ throw new Error(`Evidence path escapes base: ${resolved}`);
83
+ }
84
+ return resolved;
85
+ }
86
+
87
+ export function validateEvidenceCommand(command: string): {
88
+ safe: boolean;
89
+ reason?: string;
90
+ } {
91
+ if (NULL_BYTE.test(command)) {
92
+ return { safe: false, reason: "Command contains null byte" };
93
+ }
94
+ const dangerous = [
95
+ /rm\s+-rf/,
96
+ />\s*\/dev/,
97
+ /mkfs/,
98
+ /dd\s+if=/,
99
+ /chmod\s+777/,
100
+ /curl.*\|\s*(bash|sh)/,
101
+ ];
102
+ for (const pattern of dangerous) {
103
+ if (pattern.test(command)) {
104
+ return { safe: false, reason: `Dangerous pattern: ${pattern.source}` };
105
+ }
106
+ }
107
+ // Heuristic denylist — blocks known-dangerous patterns but not a security gate
108
+ // for arbitrary command execution. Evidence commands are controlled by Discovery,
109
+ // not external input, so denylist is defense-in-depth, not the primary control.
110
+ return { safe: true };
111
+ }
112
+
113
+ export function buildSafeSSHCommand(
114
+ host: string,
115
+ command: string,
116
+ ): string[] {
117
+ if (SHELL_METACHARACTERS.test(host)) {
118
+ throw new Error(`SSH host contains shell metacharacters: ${host}`);
119
+ }
120
+ if (host.startsWith("-")) {
121
+ throw new Error(`SSH host starts with dash (option injection): ${host}`);
122
+ }
123
+ return [
124
+ "ssh",
125
+ "-o",
126
+ "ConnectTimeout=5",
127
+ "-o",
128
+ "StrictHostKeyChecking=no",
129
+ "--",
130
+ host,
131
+ command,
132
+ ];
133
+ }
134
+
135
+ interface ACForHash {
136
+ id: string;
137
+ type: string;
138
+ statement: string;
139
+ specElement?: string;
140
+ threshold?: { op: string; value: unknown };
141
+ evidenceMethod?: { type: string; command?: string };
142
+ }
143
+
144
+ export function computeACHash(
145
+ acs: ACForHash[],
146
+ excludeFields: (keyof ACForHash)[] = [],
147
+ ): string {
148
+ const normalized = acs
149
+ .map((ac) => {
150
+ const filtered: Record<string, unknown> = {};
151
+ for (const [key, value] of Object.entries(ac)) {
152
+ if (!excludeFields.includes(key as keyof ACForHash)) {
153
+ filtered[key] = value;
154
+ }
155
+ }
156
+ return filtered;
157
+ })
158
+ .sort((a, b) =>
159
+ JSON.stringify(a).localeCompare(JSON.stringify(b)),
160
+ );
161
+ return createHash("sha256").update(JSON.stringify(normalized)).digest("hex");
162
+ }
163
+
164
+ export function verifyACHash(
165
+ acs: ACForHash[],
166
+ expectedHash: string,
167
+ excludeFields: (keyof ACForHash)[] = [],
168
+ ): boolean {
169
+ const computed = computeACHash(acs, excludeFields);
170
+ const computedBuf = Buffer.from(computed, "utf-8");
171
+ const expectedBuf = Buffer.from(expectedHash, "utf-8");
172
+ if (computedBuf.length !== expectedBuf.length) return false;
173
+ return timingSafeEqual(computedBuf, expectedBuf);
174
+ }
@@ -0,0 +1,250 @@
1
+ /**
2
+ * Worktree cleanup — removes stale git worktrees from .claude/worktrees/
3
+ *
4
+ * Safety-first design:
5
+ * - NEVER removes worktrees with uncommitted changes
6
+ * - NEVER removes worktrees with unmerged branches
7
+ * - Optionally filters by age (maxAgeMs)
8
+ *
9
+ * GitHub issue #564
10
+ */
11
+
12
+ import { readdirSync, statSync, existsSync } from "fs";
13
+ import { join } from "path";
14
+ import { spawnSync } from "child_process";
15
+
16
+ export interface CleanupResult {
17
+ removed: string[];
18
+ kept: string[];
19
+ errors: string[];
20
+ }
21
+
22
+ export interface CleanupOptions {
23
+ projectRoot: string;
24
+ maxAgeMs?: number;
25
+ }
26
+
27
+ /**
28
+ * How many commits on `branch` no `origin/*` ref contains (#232).
29
+ *
30
+ * `0` is the claim "every commit here is also on origin". `null` is the
31
+ * absence of a claim and the caller keeps the worktree — "I could not tell"
32
+ * is not grounds for `git worktree remove --force`.
33
+ *
34
+ * A repo with no `origin` remote returns `0` rather than the branch's whole
35
+ * length. There is nowhere for the work to have been pushed TO, so the
36
+ * question does not apply, and answering it literally would stop cleanup
37
+ * dead in every local-only checkout — which is the regression that gets a
38
+ * safety check reverted.
39
+ */
40
+ export function unpushedCommitCount(projectRoot: string, branch: string): number | null {
41
+ const remotes = spawnSync("git", ["remote"], {
42
+ cwd: projectRoot, encoding: "utf-8", timeout: 5000,
43
+ });
44
+ if (remotes.status !== 0) return null;
45
+ if (!remotes.stdout.split("\n").map(r => r.trim()).includes("origin")) return 0;
46
+
47
+ const count = spawnSync("git", ["rev-list", "--count", branch, "--not", "--remotes=origin"], {
48
+ cwd: projectRoot, encoding: "utf-8", timeout: 10_000,
49
+ });
50
+ if (count.status !== 0) return null;
51
+ const n = parseInt(count.stdout.trim(), 10);
52
+ return Number.isFinite(n) ? n : null;
53
+ }
54
+
55
+ /**
56
+ * Why this worktree must be kept, given what the origin check answered, or
57
+ * null to go ahead and remove it (#232).
58
+ *
59
+ * One exported binding rather than two branches inline, because the `null`
60
+ * arm is the one no fixture can reach: it needs git to fail between the
61
+ * branch read and the rev-list, which is real — a branch deleted in that
62
+ * window — and not something a test can stage. Inline, removing that arm
63
+ * scored ZERO red; here it is driven directly.
64
+ */
65
+ export function unpushedKeepReason(
66
+ entry: string,
67
+ branch: string,
68
+ unpushed: number | null,
69
+ ): string | null {
70
+ if (unpushed === null) return `${entry} (could not tell whether ${branch} is on origin)`;
71
+ if (unpushed > 0) return `${entry} (${unpushed} commit(s) on ${branch} not on origin)`;
72
+ return null;
73
+ }
74
+
75
+ /**
76
+ * Clean up stale git worktrees from .claude/worktrees/.
77
+ *
78
+ * @param opts - Cleanup options with projectRoot and optional maxAgeMs filter
79
+ * @returns CleanupResult with removed, kept, and errors arrays
80
+ */
81
+ export async function cleanupWorktrees(opts: CleanupOptions): Promise<CleanupResult> {
82
+ const { projectRoot, maxAgeMs } = opts;
83
+ const result: CleanupResult = {
84
+ removed: [],
85
+ kept: [],
86
+ errors: [],
87
+ };
88
+
89
+ const worktreesDir = join(projectRoot, ".claude", "worktrees");
90
+
91
+ // Early exit if directory doesn't exist
92
+ if (!existsSync(worktreesDir)) {
93
+ return result;
94
+ }
95
+
96
+ let entries: string[];
97
+ try {
98
+ entries = readdirSync(worktreesDir);
99
+ } catch (err) {
100
+ result.errors.push(`Failed to read worktrees directory: ${err}`);
101
+ return result;
102
+ }
103
+
104
+ const now = Date.now();
105
+
106
+ for (const entry of entries) {
107
+ const worktreePath = join(worktreesDir, entry);
108
+
109
+ // Skip if not a directory
110
+ try {
111
+ const stat = statSync(worktreePath);
112
+ if (!stat.isDirectory()) continue;
113
+
114
+ // Check age filter if provided
115
+ if (maxAgeMs !== undefined) {
116
+ const ageMs = now - stat.mtimeMs;
117
+ if (ageMs < maxAgeMs) {
118
+ // Too new, skip
119
+ continue;
120
+ }
121
+ }
122
+ } catch (err) {
123
+ result.errors.push(`Failed to stat ${entry}: ${err}`);
124
+ continue;
125
+ }
126
+
127
+ // Check for uncommitted changes
128
+ const statusCheck = spawnSync("git", ["status", "--porcelain"], {
129
+ cwd: worktreePath,
130
+ encoding: "utf-8",
131
+ timeout: 5000,
132
+ });
133
+
134
+ if (statusCheck.status !== 0) {
135
+ result.errors.push(`Failed to check git status for ${entry}: ${statusCheck.stderr}`);
136
+ continue;
137
+ }
138
+
139
+ if (statusCheck.stdout.trim() !== "") {
140
+ // Has uncommitted changes — keep it
141
+ result.kept.push(`${entry} (uncommitted changes)`);
142
+ continue;
143
+ }
144
+
145
+ // Get branch name
146
+ const branchCheck = spawnSync("git", ["-C", worktreePath, "branch", "--show-current"], {
147
+ cwd: projectRoot,
148
+ encoding: "utf-8",
149
+ timeout: 5000,
150
+ });
151
+
152
+ if (branchCheck.status !== 0) {
153
+ result.errors.push(`Failed to get branch name for ${entry}: ${branchCheck.stderr}`);
154
+ continue;
155
+ }
156
+
157
+ const branchName = branchCheck.stdout.trim();
158
+ if (!branchName) {
159
+ // Detached HEAD or no branch — keep it
160
+ result.kept.push(`${entry} (detached HEAD)`);
161
+ continue;
162
+ }
163
+
164
+ // Is the branch merged into main? (#68)
165
+ //
166
+ // This used to parse `git branch --merged main` display output, stripping
167
+ // a leading `*`. Git also prefixes `+ ` on any branch checked out in a
168
+ // LINKED WORKTREE — which is, by definition, every branch this function
169
+ // evaluates. So entries came out as "+ 24-doc-hygiene-infra", never
170
+ // matched the bare name, every candidate was classified unmerged, and the
171
+ // function removed nothing for its entire existence. 36 worktrees and
172
+ // 243 MB accumulated behind it.
173
+ //
174
+ // Ask git the question directly instead. `--is-ancestor` is a predicate
175
+ // with an exit status, so there is no display output to parse and no
176
+ // decoration to strip — the whole class of prefix bug goes away rather
177
+ // than this one instance of it.
178
+ //
179
+ // Argument order is load-bearing and inverting it is catastrophic: this
180
+ // asks whether BRANCH is an ancestor of main. Reversed, every branch cut
181
+ // from main would look merged and cleanup would delete unmerged work.
182
+ // test/unit/worktree-cleanup-merge.test.ts pins both directions.
183
+ const mergeCheck = spawnSync("git", ["merge-base", "--is-ancestor", branchName, "main"], {
184
+ cwd: projectRoot,
185
+ encoding: "utf-8",
186
+ timeout: 5000,
187
+ });
188
+
189
+ // Exit 0 = merged, 1 = not merged. Anything else (128: bad revision, no
190
+ // `main`, not a repo) is an error, NOT a verdict — treating it as "not
191
+ // merged" would be safe here, but treating it as merged would delete work,
192
+ // and silently swallowing it is how the original bug stayed invisible.
193
+ if (mergeCheck.status !== 0 && mergeCheck.status !== 1) {
194
+ result.errors.push(
195
+ `Failed to check merge status for ${entry}: git exited ${mergeCheck.status}: ${mergeCheck.stderr.trim()}`,
196
+ );
197
+ continue;
198
+ }
199
+
200
+ if (mergeCheck.status !== 0) {
201
+ // Branch not merged — keep it
202
+ result.kept.push(`${entry} (unmerged branch: ${branchName})`);
203
+ continue;
204
+ }
205
+
206
+ // Merged into LOCAL main is not the same as safe to delete (#232).
207
+ //
208
+ // A branch merged into a main that was never pushed exists in exactly one
209
+ // place on earth, and this function runs unattended from a SessionStart
210
+ // hook. #228 and #232 are both about work that was correct and became
211
+ // unreachable; removing a worktree whose commits are not on origin is the
212
+ // same loss with a tidier name.
213
+ const keepReason = unpushedKeepReason(
214
+ entry, branchName, unpushedCommitCount(projectRoot, branchName),
215
+ );
216
+ if (keepReason) {
217
+ result.kept.push(keepReason);
218
+ continue;
219
+ }
220
+
221
+ // All safety checks passed — remove the worktree
222
+ const removeResult = spawnSync("git", ["worktree", "remove", "--force", worktreePath], {
223
+ cwd: projectRoot,
224
+ encoding: "utf-8",
225
+ timeout: 15000,
226
+ });
227
+
228
+ if (removeResult.status !== 0) {
229
+ result.errors.push(`Failed to remove ${entry}: ${removeResult.stderr}`);
230
+ } else {
231
+ result.removed.push(entry);
232
+ }
233
+ }
234
+
235
+ // Prune worktree references
236
+ const pruneResult = spawnSync("git", ["worktree", "prune"], {
237
+ cwd: projectRoot,
238
+ encoding: "utf-8",
239
+ timeout: 5000,
240
+ });
241
+
242
+ if (pruneResult.status !== 0) {
243
+ result.errors.push(`Failed to prune worktree references: ${pruneResult.stderr}`);
244
+ }
245
+
246
+ // Log summary
247
+ console.log(`Worktree cleanup: ${result.removed.length} removed, ${result.kept.length} kept`);
248
+
249
+ return result;
250
+ }