@feigi/fleet-ctl 0.0.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 (245) hide show
  1. package/.claude-plugin/plugin.json +9 -0
  2. package/LICENSE +202 -0
  3. package/NOTICE +18 -0
  4. package/agents/fleet-finisher.agent.md +7 -0
  5. package/agents/fleet-implementer-alt.agent.md +210 -0
  6. package/agents/fleet-implementer.agent.md +210 -0
  7. package/agents/fleet-merge-bot.agent.md +7 -0
  8. package/agents/fleet-review-comments.agent.md +40 -0
  9. package/agents/fleet-review-correctness.agent.md +43 -0
  10. package/agents/fleet-review-runner.agent.md +73 -0
  11. package/agents/fleet-review-silent-failure.agent.md +49 -0
  12. package/agents/fleet-review-simplify.agent.md +46 -0
  13. package/agents/fleet-review-snapshot.agent.md +24 -0
  14. package/agents/fleet-review-tests.agent.md +46 -0
  15. package/agents/fleet-review-types.agent.md +41 -0
  16. package/agents/fleet-review-verifier.agent.md +29 -0
  17. package/commands/review-and-fix.md +98 -0
  18. package/commands/run-merge-bot.md +357 -0
  19. package/commands/run-team-help.md +17 -0
  20. package/package.json +23 -0
  21. package/scripts/agent-test-dir-prose.test.mjs +59 -0
  22. package/scripts/agent-test.test.mjs +1636 -0
  23. package/scripts/ambient-git-vars-mjs-prose.test.mjs +354 -0
  24. package/scripts/ambient-git-vars-prose.test.mjs +192 -0
  25. package/scripts/ancestry-check-position-prose.test.mjs +175 -0
  26. package/scripts/apply-ruleset.test.mjs +420 -0
  27. package/scripts/arg-header-probes-prose.test.mjs +393 -0
  28. package/scripts/arg.mjs +600 -0
  29. package/scripts/arg.test.mjs +1354 -0
  30. package/scripts/board-cli.test.mjs +694 -0
  31. package/scripts/board-identity.test.mjs +429 -0
  32. package/scripts/board-liveness-banner.test.mjs +119 -0
  33. package/scripts/board-prev-shape.test.mjs +229 -0
  34. package/scripts/board-tryparse-null.test.mjs +119 -0
  35. package/scripts/board.html +471 -0
  36. package/scripts/board.mjs +2037 -0
  37. package/scripts/board.test.mjs +3086 -0
  38. package/scripts/brief-after-cut-prose.test.mjs +53 -0
  39. package/scripts/candidates-exit3-prose.test.mjs +302 -0
  40. package/scripts/candidates.mjs +674 -0
  41. package/scripts/candidates.test.mjs +2101 -0
  42. package/scripts/caveat-unification-prose.test.mjs +98 -0
  43. package/scripts/ci-comment-rot-prose.test.mjs +2025 -0
  44. package/scripts/ci-completes-premise-prose.test.mjs +257 -0
  45. package/scripts/ci-state-prose.test.mjs +113 -0
  46. package/scripts/ci-state.mjs +761 -0
  47. package/scripts/ci-state.test.mjs +1640 -0
  48. package/scripts/ci-vacuous-green.test.mjs +368 -0
  49. package/scripts/citation-sweep-prose.test.mjs +1572 -0
  50. package/scripts/claim-lifecycle.test.mjs +185 -0
  51. package/scripts/claim-ticket.sh +417 -0
  52. package/scripts/claim-ticket.test.mjs +1121 -0
  53. package/scripts/closing-keyword-prose.test.mjs +193 -0
  54. package/scripts/cockpit-launch-idempotent-prose.test.mjs +165 -0
  55. package/scripts/cockpit-tick-nonblocking.test.mjs +210 -0
  56. package/scripts/compute-board.mjs +579 -0
  57. package/scripts/compute-board.test.mjs +1060 -0
  58. package/scripts/compute-spend.mjs +329 -0
  59. package/scripts/compute-spend.test.mjs +451 -0
  60. package/scripts/cross-repo-citation-prose.test.mjs +156 -0
  61. package/scripts/cwd-isolation-pins.mjs +83 -0
  62. package/scripts/dedupe-guard-prose.test.mjs +243 -0
  63. package/scripts/derive-testcmd.sh +239 -0
  64. package/scripts/derive-testcmd.test.mjs +380 -0
  65. package/scripts/diff-stats.mjs +231 -0
  66. package/scripts/diff-stats.test.mjs +408 -0
  67. package/scripts/dispatch-block-golden-prose.test.mjs +1024 -0
  68. package/scripts/dispatch-block-pins-prose.test.mjs +615 -0
  69. package/scripts/drop-merged-label.sh +173 -0
  70. package/scripts/drop-merged-label.test.mjs +480 -0
  71. package/scripts/expected-jobs-prose.test.mjs +80 -0
  72. package/scripts/filing-bar-seat-prose.test.mjs +242 -0
  73. package/scripts/filing-claim-bar-prose.test.mjs +166 -0
  74. package/scripts/finisher-dispatch-premise-prose.test.mjs +312 -0
  75. package/scripts/finisher-halt-prose.test.mjs +106 -0
  76. package/scripts/finisher-name-prose.test.mjs +134 -0
  77. package/scripts/finisher-own-tree-prose.test.mjs +285 -0
  78. package/scripts/finisher-pin-race-prose.test.mjs +339 -0
  79. package/scripts/fix-applier-correction-rules-prose.test.mjs +201 -0
  80. package/scripts/fix-applier-result-file-prose.test.mjs +100 -0
  81. package/scripts/fleet-bootstrap +155 -0
  82. package/scripts/fleet-heartbeat.mjs +272 -0
  83. package/scripts/fleet-heartbeat.test.mjs +450 -0
  84. package/scripts/fleet-provenance +207 -0
  85. package/scripts/fleet-provenance.test.mjs +64 -0
  86. package/scripts/fleet-run +148 -0
  87. package/scripts/fleet-run.test.mjs +90 -0
  88. package/scripts/fleet-state.mjs +400 -0
  89. package/scripts/fleet-state.test.mjs +373 -0
  90. package/scripts/fleet-tick-prose.test.mjs +299 -0
  91. package/scripts/fleet-tick.mjs +832 -0
  92. package/scripts/fleet-tick.test.mjs +1332 -0
  93. package/scripts/force-with-lease-reason-prose.test.mjs +184 -0
  94. package/scripts/frontmatter-allowlist.json +64 -0
  95. package/scripts/frontmatter-check.mjs +256 -0
  96. package/scripts/frontmatter-check.test.mjs +436 -0
  97. package/scripts/git-env.mjs +124 -0
  98. package/scripts/git-env.test.mjs +149 -0
  99. package/scripts/git-status-untracked-mode-sweep.test.mjs +216 -0
  100. package/scripts/gone-walk.test.mjs +213 -0
  101. package/scripts/gp-sep-invariant-prose.test.mjs +188 -0
  102. package/scripts/head-moved-after-label-prose.test.mjs +233 -0
  103. package/scripts/immutable-body-claim-prose.test.mjs +413 -0
  104. package/scripts/implementer-model-tier.test.mjs +643 -0
  105. package/scripts/inflight-citation-prose.test.mjs +144 -0
  106. package/scripts/inflight-exit2-prose.test.mjs +81 -0
  107. package/scripts/inflight-probe-guard-prose.test.mjs +109 -0
  108. package/scripts/inflight-scan-scope-prose.test.mjs +57 -0
  109. package/scripts/inflight.sh +1106 -0
  110. package/scripts/inflight.test.mjs +2984 -0
  111. package/scripts/injection-control-prose.test.mjs +404 -0
  112. package/scripts/install-root-audit.test.mjs +464 -0
  113. package/scripts/instrument-check-prose.test.mjs +235 -0
  114. package/scripts/instruments.sh +394 -0
  115. package/scripts/instruments.test.mjs +787 -0
  116. package/scripts/issue-tracker-prose.test.mjs +71 -0
  117. package/scripts/json.sh +248 -0
  118. package/scripts/json.test.mjs +364 -0
  119. package/scripts/ledger-dispatch.test.mjs +516 -0
  120. package/scripts/ledger-grammar.mjs +85 -0
  121. package/scripts/ledger-grammar.test.mjs +142 -0
  122. package/scripts/ledger-read-require-file.test.mjs +197 -0
  123. package/scripts/ledger.mjs +1753 -0
  124. package/scripts/ledger.test.mjs +3554 -0
  125. package/scripts/line-distance-prose.test.mjs +245 -0
  126. package/scripts/liveness-rationale-prose.test.mjs +83 -0
  127. package/scripts/locale-pin-prose.test.mjs +189 -0
  128. package/scripts/member-outcome-prose.test.mjs +167 -0
  129. package/scripts/member-outcomes-header.test.mjs +148 -0
  130. package/scripts/member-outcomes-prose.test.mjs +63 -0
  131. package/scripts/member-outcomes.mjs +231 -0
  132. package/scripts/member-outcomes.test.mjs +507 -0
  133. package/scripts/member-prompt-prose.test.mjs +161 -0
  134. package/scripts/member-record.mjs +605 -0
  135. package/scripts/member-record.test.mjs +516 -0
  136. package/scripts/member-write-guard.mjs +279 -0
  137. package/scripts/member-write-guard.test.mjs +211 -0
  138. package/scripts/merge-commit-probe-prose.test.mjs +122 -0
  139. package/scripts/merge-gate.mjs +262 -0
  140. package/scripts/merge-gate.test.mjs +613 -0
  141. package/scripts/muted-git-guard-sweep.test.mjs +493 -0
  142. package/scripts/net-ssh-precedence-prose.test.mjs +91 -0
  143. package/scripts/net-watchdog-prose.test.mjs +79 -0
  144. package/scripts/net.sh +409 -0
  145. package/scripts/net.test.mjs +211 -0
  146. package/scripts/no-ci-gate-prose.test.mjs +108 -0
  147. package/scripts/no-undo-audit.sh +1134 -0
  148. package/scripts/no-undo-audit.test.mjs +3965 -0
  149. package/scripts/no-wave.test.mjs +138 -0
  150. package/scripts/node-floor-sweep.test.mjs +611 -0
  151. package/scripts/pointer-target-prose.test.mjs +186 -0
  152. package/scripts/pr-overlap.mjs +417 -0
  153. package/scripts/pr-overlap.test.mjs +695 -0
  154. package/scripts/printf-die-sweep.test.mjs +384 -0
  155. package/scripts/prompt-renderer.mjs +39 -0
  156. package/scripts/prompt-renderer.test.mjs +68 -0
  157. package/scripts/prose-pin.mjs +808 -0
  158. package/scripts/prose-pin.test.mjs +1034 -0
  159. package/scripts/prove-merge.sh +228 -0
  160. package/scripts/prove-merge.test.mjs +995 -0
  161. package/scripts/pull-table-relabel-prose.test.mjs +60 -0
  162. package/scripts/quiet-payload-prose.test.mjs +222 -0
  163. package/scripts/reap.sh +1768 -0
  164. package/scripts/reap.test.mjs +4395 -0
  165. package/scripts/reaping-prose.test.mjs +159 -0
  166. package/scripts/refuter-scratch-prose.test.mjs +135 -0
  167. package/scripts/release-label-required-prose.test.mjs +71 -0
  168. package/scripts/release-label-split-prose.test.mjs +169 -0
  169. package/scripts/release-ticket.sh +1716 -0
  170. package/scripts/release-ticket.test.mjs +5106 -0
  171. package/scripts/renovate-release-contract.test.mjs +379 -0
  172. package/scripts/repo-root.mjs +544 -0
  173. package/scripts/repo-root.test.mjs +873 -0
  174. package/scripts/reporter-output-rule-prose.test.mjs +208 -0
  175. package/scripts/review-agent-report-only.test.mjs +49 -0
  176. package/scripts/review-core-cwd-isolation.test.mjs +374 -0
  177. package/scripts/review-core-reads.test.mjs +478 -0
  178. package/scripts/review-core-refuter-scratch.test.mjs +148 -0
  179. package/scripts/review-core-snapshot-path.test.mjs +777 -0
  180. package/scripts/review-core-specialist-scratch.test.mjs +189 -0
  181. package/scripts/review-core-testcmd.test.mjs +288 -0
  182. package/scripts/review-core-unrun.test.mjs +530 -0
  183. package/scripts/review-core-unverified-discriminant.test.mjs +208 -0
  184. package/scripts/review-core.mjs +1028 -0
  185. package/scripts/review-eval-resolver-path.test.mjs +55 -0
  186. package/scripts/review-eval.mjs +197 -0
  187. package/scripts/review-host-fixture.mjs +73 -0
  188. package/scripts/review-in-run-retry.test.mjs +187 -0
  189. package/scripts/review-no-vendor-dispatch.test.mjs +45 -0
  190. package/scripts/review-path-default.test.mjs +796 -0
  191. package/scripts/review-runner-spawns.test.mjs +93 -0
  192. package/scripts/review-runner.test.mjs +155 -0
  193. package/scripts/review-tier-audit.test.mjs +140 -0
  194. package/scripts/run-artifact-pr-prose.test.mjs +341 -0
  195. package/scripts/run-merge-bot-prose.test.mjs +1391 -0
  196. package/scripts/scratch-partition-invariant-prose.test.mjs +74 -0
  197. package/scripts/scripts-path-citation-sweep.test.mjs +73 -0
  198. package/scripts/section-between-guard-prose.test.mjs +378 -0
  199. package/scripts/select-dimensions.test.mjs +674 -0
  200. package/scripts/shared-refusal.test.mjs +388 -0
  201. package/scripts/shell-traps-prose.test.mjs +507 -0
  202. package/scripts/shortlist.mjs +355 -0
  203. package/scripts/shortlist.test.mjs +366 -0
  204. package/scripts/slow-transport.mjs +72 -0
  205. package/scripts/snapshot-repo.test.mjs +772 -0
  206. package/scripts/snapshot-runner-audience-prose.test.mjs +129 -0
  207. package/scripts/spend-view.test.mjs +312 -0
  208. package/scripts/staleness-qualifier-prose.test.mjs +251 -0
  209. package/scripts/staleness-verdict-prose.test.mjs +142 -0
  210. package/scripts/staleness.mjs +414 -0
  211. package/scripts/staleness.test.mjs +893 -0
  212. package/scripts/stalled-member-liveness-prose.test.mjs +219 -0
  213. package/scripts/stash-prohibition-prose.test.mjs +313 -0
  214. package/scripts/strip-comments.mjs +44 -0
  215. package/scripts/tier-check.mjs +468 -0
  216. package/scripts/tier-check.test.mjs +726 -0
  217. package/scripts/tier-guard-gate-prose.test.mjs +216 -0
  218. package/scripts/tier-outcomes-header.test.mjs +586 -0
  219. package/scripts/tier-outcomes.mjs +441 -0
  220. package/scripts/tier-outcomes.test.mjs +342 -0
  221. package/scripts/tier-roles.mjs +250 -0
  222. package/scripts/tier-roles.test.mjs +316 -0
  223. package/scripts/tracker-block-copy-prose.test.mjs +288 -0
  224. package/scripts/triage-labels-gloss-prose.test.mjs +97 -0
  225. package/scripts/unattended-git-sweep.test.mjs +142 -0
  226. package/scripts/verify-sha-exit2-prose.test.mjs +269 -0
  227. package/scripts/verify-sha.sh +117 -0
  228. package/scripts/verify-sha.test.mjs +693 -0
  229. package/scripts/watcher-degraded-block.test.mjs +372 -0
  230. package/scripts/watcher-key-prose.test.mjs +106 -0
  231. package/scripts/within-run-pair-prose.test.mjs +208 -0
  232. package/scripts/worktree-audit.sh +482 -0
  233. package/scripts/worktree-audit.test.mjs +1407 -0
  234. package/scripts/worktree-head-prose.test.mjs +276 -0
  235. package/scripts/worktree-listing-sweep.test.mjs +217 -0
  236. package/scripts/worktree-model-prose.test.mjs +216 -0
  237. package/scripts/worktree.sh +470 -0
  238. package/skills/next-ticket/SKILL.md +138 -0
  239. package/skills/run-team/SKILL.md +3603 -0
  240. package/skills/run-team/references/ci-and-staleness.md +75 -0
  241. package/skills/run-team/references/correction-tickets.md +37 -0
  242. package/skills/run-team/references/isolation.md +23 -0
  243. package/skills/run-team/references/member-lifecycle.md +73 -0
  244. package/skills/run-team/references/reaping.md +73 -0
  245. package/skills/sizing-a-ticket/SKILL.md +39 -0
@@ -0,0 +1,436 @@
1
+ // The allow-list checker's own tests (#1314, #1347). Two halves:
2
+ //
3
+ // (1) a pure-core unit/mutation suite over `parseAllowlist`, `kindForPath`,
4
+ // `parseFrontmatter`, `checkFields`, `formatViolation` — fixture-driven,
5
+ // independent of what happens to be checked into the tree right now.
6
+ // (2) a CLI/end-to-end suite driving the script as a child process, over
7
+ // fixture files on disk, proving the exit-code contract (0/1/2) and the
8
+ // exact `file:line: key — reason` line shape.
9
+ //
10
+ // The MUTATION PROOF #1314's own acceptance criterion asks for — "a
11
+ // disallowed key -> red, revert -> green; repeat for a missing required key"
12
+ // — is done directly against the CLI (not simulated): a fixture agent file is
13
+ // mutated in place, the checker is run, the run is asserted red, the mutation
14
+ // is reverted, the checker is run again, the run is asserted green. Three
15
+ // mutations covered: a forbidden key, a missing required key, an unknown key
16
+ // — plus the real-tree run at the bottom, which is the checker's own first
17
+ // real green (#1345 having landed `thinking-level` beside `effort` on both
18
+ // fleet agents; #1298/#1314/ADR 0005 name this as the gate's first real red
19
+ // until then, and green after).
20
+ import { test } from "node:test";
21
+ import assert from "node:assert/strict";
22
+ import { spawnSync } from "node:child_process";
23
+ import { mkdtempSync, writeFileSync, readFileSync, mkdirSync, existsSync } from "node:fs";
24
+ import { join } from "node:path";
25
+ import { tmpdir } from "node:os";
26
+ import { fileURLToPath } from "node:url";
27
+ import {
28
+ parseAllowlist, kindForPath, parseFrontmatter, checkFields, formatViolation,
29
+ } from "./frontmatter-check.mjs";
30
+
31
+ const SCRIPT = fileURLToPath(new URL("./frontmatter-check.mjs", import.meta.url));
32
+ const REAL_ALLOWLIST_PATH = fileURLToPath(new URL("./frontmatter-allowlist.json", import.meta.url));
33
+ const REPO = fileURLToPath(new URL("..", import.meta.url));
34
+
35
+ function dir() {
36
+ return mkdtempSync(join(tmpdir(), "frontmatter-check-"));
37
+ }
38
+
39
+ function runCli(argv, cwd) {
40
+ return spawnSync(process.execPath, [SCRIPT, ...argv], { cwd, encoding: "utf8" });
41
+ }
42
+
43
+ // A minimal but real three-kind allow-list, standing in for the real one so
44
+ // these fixtures are not coupled to #1314's exact recorded content.
45
+ const FIXTURE_ALLOWLIST = {
46
+ agents: {
47
+ required: ["name", "description", "model"],
48
+ allowed: ["tools"],
49
+ forbidden: { "thinking-level": "the level rides on model's `@<role>:<level>` suffix — one spelling only" },
50
+ values: {
51
+ model: {
52
+ pattern: "^@(slow|task|smol):(minimal|low|medium|high|xhigh|max)$",
53
+ message: "must be a fleet tier route @slow|@task|@smol with an explicit :<level> suffix",
54
+ },
55
+ },
56
+ },
57
+ skills: {
58
+ required: ["name", "description"],
59
+ allowed: ["argument-hint"],
60
+ forbidden: { model: "a per-skill tier override with no documented effect" },
61
+ },
62
+ commands: {
63
+ required: ["description"],
64
+ allowed: ["argument-hint"],
65
+ forbidden: { model: "a per-skill tier override with no documented effect" },
66
+ },
67
+ };
68
+
69
+ function writeFixtureAllowlist(d) {
70
+ const p = join(d, "allowlist.json");
71
+ writeFileSync(p, JSON.stringify(FIXTURE_ALLOWLIST));
72
+ return p;
73
+ }
74
+
75
+ // ---------------------------------------------------------------------------
76
+ // parseAllowlist
77
+ // ---------------------------------------------------------------------------
78
+
79
+ test("parseAllowlist: the real allow-list on disk is well-shaped", () => {
80
+ const raw = readFileSync(REAL_ALLOWLIST_PATH, "utf8");
81
+ const { allowlist, error } = parseAllowlist(raw);
82
+ assert.equal(error, undefined);
83
+ for (const kind of ["agents", "skills", "commands"]) {
84
+ assert.ok(Array.isArray(allowlist[kind].required), `${kind}.required is an array`);
85
+ assert.ok(Array.isArray(allowlist[kind].allowed), `${kind}.allowed is an array`);
86
+ assert.equal(typeof allowlist[kind].forbidden, "object", `${kind}.forbidden is an object`);
87
+ }
88
+ });
89
+
90
+ test("parseAllowlist: malformed JSON is an error, not a thrown exception", () => {
91
+ const { allowlist, error } = parseAllowlist("{not json");
92
+ assert.equal(allowlist, undefined);
93
+ assert.match(error, /not valid JSON/);
94
+ });
95
+
96
+ test("parseAllowlist: a JSON file missing a kind section is an error naming it", () => {
97
+ const { error } = parseAllowlist(JSON.stringify({ agents: FIXTURE_ALLOWLIST.agents, skills: FIXTURE_ALLOWLIST.skills }));
98
+ assert.match(error, /"commands"/);
99
+ });
100
+
101
+ test("parseAllowlist: a kind section with forbidden as an array (wrong shape) is an error", () => {
102
+ const bad = JSON.parse(JSON.stringify(FIXTURE_ALLOWLIST));
103
+ bad.agents.forbidden = ["hooks"];
104
+ const { error } = parseAllowlist(JSON.stringify(bad));
105
+ assert.match(error, /agents\.forbidden/);
106
+ });
107
+
108
+ // ---------------------------------------------------------------------------
109
+ // kindForPath
110
+ // ---------------------------------------------------------------------------
111
+
112
+ test("kindForPath: classifies agents, skills, commands under a plugin/ prefix", () => {
113
+ assert.equal(kindForPath("plugin/agents/fleet-implementer.agent.md"), "agents");
114
+ assert.equal(kindForPath("plugin/skills/run-team/SKILL.md"), "skills");
115
+ assert.equal(kindForPath("plugin/commands/review-and-fix.md"), "commands");
116
+ });
117
+
118
+ test("kindForPath: classifies the same shapes with no plugin/ prefix (bare repo-relative)", () => {
119
+ assert.equal(kindForPath("agents/x.md"), "agents");
120
+ assert.equal(kindForPath("skills/foo/SKILL.md"), "skills");
121
+ assert.equal(kindForPath("commands/y.md"), "commands");
122
+ });
123
+
124
+ test("kindForPath: a file one level too deep or too shallow does not classify", () => {
125
+ assert.equal(kindForPath("plugin/agents/nested/x.md"), null);
126
+ assert.equal(kindForPath("plugin/skills/SKILL.md"), null);
127
+ assert.equal(kindForPath("plugin/skills/foo/bar/SKILL.md"), null);
128
+ });
129
+
130
+ test("kindForPath: an unrelated path classifies as null", () => {
131
+ assert.equal(kindForPath("plugin/scripts/frontmatter-check.mjs"), null);
132
+ });
133
+
134
+ // ---------------------------------------------------------------------------
135
+ // parseFrontmatter
136
+ // ---------------------------------------------------------------------------
137
+
138
+ test("parseFrontmatter: reads flat key: value fields with 1-based source lines", () => {
139
+ const { fields, error } = parseFrontmatter("---\nname: fleet-x\ndescription: does a thing\n---\nbody\n");
140
+ assert.equal(error, undefined);
141
+ assert.deepEqual(fields, [
142
+ { key: "name", value: "fleet-x", line: 2 },
143
+ { key: "description", value: "does a thing", line: 3 },
144
+ ]);
145
+ });
146
+
147
+ test("parseFrontmatter: a blank line inside the block is skipped, not a parse error", () => {
148
+ const { fields, error } = parseFrontmatter("---\nname: x\n\ndescription: y\n---\n");
149
+ assert.equal(error, undefined);
150
+ assert.equal(fields.length, 2);
151
+ assert.equal(fields[1].line, 4);
152
+ });
153
+
154
+ test("parseFrontmatter: no opening fence is a parse error", () => {
155
+ const { error } = parseFrontmatter("name: x\ndescription: y\n");
156
+ assert.match(error, /opening --- fence/);
157
+ });
158
+
159
+ test("parseFrontmatter: no closing fence is a parse error", () => {
160
+ const { error } = parseFrontmatter("---\nname: x\ndescription: y\n");
161
+ assert.match(error, /closing --- fence/);
162
+ });
163
+
164
+ test("parseFrontmatter: a line that is neither blank nor key: value is a parse error naming the line", () => {
165
+ const { error } = parseFrontmatter("---\nname: x\nnot a field at all\n---\n");
166
+ assert.match(error, /unparseable frontmatter at line 3/);
167
+ });
168
+
169
+ test("parseFrontmatter: an empty value (key: with nothing after it) parses as an empty string, not an error", () => {
170
+ const { fields, error } = parseFrontmatter("---\nargument-hint:\n---\n");
171
+ assert.equal(error, undefined);
172
+ assert.equal(fields[0].value, "");
173
+ });
174
+
175
+ test("parseFrontmatter: a double-quoted value has its quotes stripped", () => {
176
+ const { fields, error } = parseFrontmatter('---\nmodel: "@slow:xhigh"\n---\n');
177
+ assert.equal(error, undefined);
178
+ assert.equal(fields[0].value, "@slow:xhigh");
179
+ });
180
+
181
+ test("parseFrontmatter: a single-quoted value has its quotes stripped", () => {
182
+ const { fields, error } = parseFrontmatter("---\nmodel: '@slow:xhigh'\n---\n");
183
+ assert.equal(error, undefined);
184
+ assert.equal(fields[0].value, "@slow:xhigh");
185
+ });
186
+
187
+ // A mismatched pair is not a quoted value: stripping must require the SAME
188
+ // quote character on both ends, so neither direction may be stripped.
189
+ test("parseFrontmatter: a mismatched pair (opening double, closing single) is left unstripped", () => {
190
+ const { fields, error } = parseFrontmatter("---\nmodel: \"@slow:xhigh'\n---\n");
191
+ assert.equal(error, undefined);
192
+ assert.equal(fields[0].value, "\"@slow:xhigh'");
193
+ });
194
+
195
+ test("parseFrontmatter: a mismatched pair (opening single, closing double) is left unstripped", () => {
196
+ const { fields, error } = parseFrontmatter("---\nmodel: '@slow:xhigh\"\n---\n");
197
+ assert.equal(error, undefined);
198
+ assert.equal(fields[0].value, "'@slow:xhigh\"");
199
+ });
200
+
201
+ // ---------------------------------------------------------------------------
202
+ // checkFields — the both-directions contract plus value rules
203
+ // ---------------------------------------------------------------------------
204
+
205
+ test("checkFields: a clean agent file (every required key, no forbidden/unknown) has zero violations", () => {
206
+ const fields = [
207
+ { key: "name", value: "fleet-x", line: 2 },
208
+ { key: "description", value: "d", line: 3 },
209
+ { key: "model", value: "@slow:xhigh", line: 4 },
210
+ ];
211
+ assert.deepEqual(checkFields("agents", FIXTURE_ALLOWLIST, fields), []);
212
+ });
213
+
214
+ test("checkFields: a forbidden key is a violation carrying the allow-list's own reason", () => {
215
+ const fields = [
216
+ { key: "name", value: "fleet-x", line: 2 },
217
+ { key: "description", value: "d", line: 3 },
218
+ { key: "model", value: "@slow:xhigh", line: 4 },
219
+ { key: "thinking-level", value: "low", line: 5 },
220
+ ];
221
+ const violations = checkFields("agents", FIXTURE_ALLOWLIST, fields);
222
+ assert.deepEqual(violations, [{ line: 5, key: "thinking-level", reason: FIXTURE_ALLOWLIST.agents.forbidden["thinking-level"] }]);
223
+ });
224
+
225
+ test("checkFields: an unrecognised key (neither required, allowed, nor forbidden) is its own violation class", () => {
226
+ const fields = [
227
+ { key: "name", value: "fleet-x", line: 2 },
228
+ { key: "description", value: "d", line: 3 },
229
+ { key: "model", value: "@slow:xhigh", line: 4 },
230
+ { key: "totallyUnknownKey", value: "1", line: 5 },
231
+ ];
232
+ const violations = checkFields("agents", FIXTURE_ALLOWLIST, fields);
233
+ assert.equal(violations.length, 1);
234
+ assert.equal(violations[0].key, "totallyUnknownKey");
235
+ assert.match(violations[0].reason, /unrecognised key/);
236
+ });
237
+
238
+ test("checkFields: a missing required key is a violation reported at line 1, not silently dropped", () => {
239
+ const fields = [
240
+ { key: "name", value: "fleet-x", line: 2 },
241
+ { key: "model", value: "@slow:xhigh", line: 3 },
242
+ ];
243
+ const violations = checkFields("agents", FIXTURE_ALLOWLIST, fields);
244
+ assert.deepEqual(violations, [{ line: 1, key: "description", reason: "required key missing" }]);
245
+ });
246
+
247
+ test("checkFields: an allowed key with no value rule at all never becomes a violation on its value", () => {
248
+ const fields = [
249
+ { key: "name", value: "fleet-x", line: 2 },
250
+ { key: "description", value: "d", line: 3 },
251
+ { key: "model", value: "@slow:xhigh", line: 4 },
252
+ { key: "tools", value: "Bash,Read,Write,AnythingGoes", line: 5 },
253
+ ];
254
+ assert.deepEqual(checkFields("agents", FIXTURE_ALLOWLIST, fields), []);
255
+ });
256
+
257
+ test("checkFields: a value that does not match its pattern is a violation carrying the pattern's own message", () => {
258
+ const fields = [
259
+ { key: "name", value: "fleet-x", line: 2 },
260
+ { key: "description", value: "d", line: 3 },
261
+ { key: "model", value: "claude-opus-5", line: 4 },
262
+ ];
263
+ const violations = checkFields("agents", FIXTURE_ALLOWLIST, fields);
264
+ assert.equal(violations.length, 1);
265
+ assert.equal(violations[0].key, "model");
266
+ assert.equal(violations[0].reason, FIXTURE_ALLOWLIST.agents.values.model.message);
267
+ });
268
+
269
+ test("checkFields: forbidden is checked before the required/allowed membership test — a forbidden required-looking key still reports its forbidden reason", () => {
270
+ const allowlist = {
271
+ agents: {
272
+ required: ["name"],
273
+ allowed: [],
274
+ forbidden: { name: "shadowed on purpose for this fixture" },
275
+ },
276
+ };
277
+ const violations = checkFields("agents", allowlist, [{ key: "name", value: "x", line: 2 }]);
278
+ assert.deepEqual(violations, [{ line: 2, key: "name", reason: "shadowed on purpose for this fixture" }]);
279
+ });
280
+
281
+ // ---------------------------------------------------------------------------
282
+ // formatViolation
283
+ // ---------------------------------------------------------------------------
284
+
285
+ test("formatViolation: the ticket's exact file:line: key — reason shape", () => {
286
+ assert.equal(
287
+ formatViolation("plugin/agents/x.agent.md", { line: 5, key: "hooks", reason: "ignored for plugin subagents" }),
288
+ "plugin/agents/x.agent.md:5: hooks — ignored for plugin subagents",
289
+ );
290
+ });
291
+
292
+ // ---------------------------------------------------------------------------
293
+ // CLI — exit codes, output shape, over real files on disk
294
+ // ---------------------------------------------------------------------------
295
+ // A fixture agent file lives under a real agents/ subdirectory, so
296
+ // kindForPath classifies it the same way it would a real repo-relative path.
297
+
298
+ // The fixture above needs a real agents/ subdirectory for kindForPath to
299
+ // classify it — build that directly rather than via the throwaway probe.
300
+ function agentFixtureDir() {
301
+ const d = dir();
302
+ const allowlistPath = writeFixtureAllowlist(d);
303
+ const agentsDir = join(d, "agents");
304
+ mkdirSync(agentsDir, { recursive: true });
305
+ return { d, allowlistPath, agentsDir, file: join(agentsDir, "x.agent.md") };
306
+ }
307
+
308
+ test("CLI: a clean agent file under agents/ exits 0 with no stdout", () => {
309
+ const { allowlistPath, agentsDir, file, d } = agentFixtureDir();
310
+ writeFileSync(file, "---\nname: fleet-x\ndescription: d\nmodel: \"@slow:xhigh\"\n---\nbody\n");
311
+ const r = runCli(["--allowlist", allowlistPath, "agents/x.agent.md"], d);
312
+ assert.equal(r.status, 0);
313
+ assert.equal(r.stdout, "");
314
+ void agentsDir;
315
+ });
316
+
317
+ test("CLI: a forbidden key exits 1 and prints file:line: key — reason", () => {
318
+ const { allowlistPath, file, d } = agentFixtureDir();
319
+ writeFileSync(file, "---\nname: fleet-x\ndescription: d\nmodel: \"@slow:xhigh\"\nthinking-level: low\n---\nbody\n");
320
+ const r = runCli(["--allowlist", allowlistPath, "agents/x.agent.md"], d);
321
+ assert.equal(r.status, 1);
322
+ assert.equal(r.stdout.trim(), `agents/x.agent.md:5: thinking-level — ${FIXTURE_ALLOWLIST.agents.forbidden["thinking-level"]}`);
323
+ });
324
+
325
+ test("CLI: a missing allow-list exits 2, never 0 or 1 — a missing list must fail loudly, not pass with an empty ruleset", () => {
326
+ const { file, d } = agentFixtureDir();
327
+ writeFileSync(file, "---\nname: fleet-x\ndescription: d\nmodel: \"@slow:xhigh\"\n---\n");
328
+ const r = runCli(["--allowlist", join(d, "does-not-exist.json"), "agents/x.agent.md"], d);
329
+ assert.equal(r.status, 2);
330
+ assert.match(r.stderr, /allow-list unreadable/);
331
+ });
332
+
333
+ test("CLI: unparseable frontmatter exits 2, distinct from a violation's exit 1", () => {
334
+ const { allowlistPath, file, d } = agentFixtureDir();
335
+ writeFileSync(file, "no fence at all\n");
336
+ const r = runCli(["--allowlist", allowlistPath, "agents/x.agent.md"], d);
337
+ assert.equal(r.status, 2);
338
+ assert.match(r.stderr, /opening --- fence/);
339
+ });
340
+
341
+ test("CLI: a file that classifies as none of agents/skills/commands exits 2 naming why", () => {
342
+ const { allowlistPath, d } = agentFixtureDir();
343
+ const stray = join(d, "stray.md");
344
+ writeFileSync(stray, "---\nname: x\n---\n");
345
+ const r = runCli(["--allowlist", allowlistPath, "stray.md"], d);
346
+ assert.equal(r.status, 2);
347
+ assert.match(r.stderr, /cannot classify/);
348
+ });
349
+
350
+ test("CLI: multiple files in one invocation report every violation across all of them before exiting", () => {
351
+ const { allowlistPath, agentsDir, d } = agentFixtureDir();
352
+ writeFileSync(join(agentsDir, "a.agent.md"), "---\nname: fleet-a\ndescription: d\nmodel: \"@slow:xhigh\"\nthinking-level: low\n---\n");
353
+ writeFileSync(join(agentsDir, "b.agent.md"), "---\nname: fleet-b\ndescription: d\nmodel: \"@task:medium\"\n---\n");
354
+ const r = runCli(["--allowlist", allowlistPath, "agents/a.agent.md", "agents/b.agent.md"], d);
355
+ assert.equal(r.status, 1);
356
+ assert.equal(r.stdout.trim(), "agents/a.agent.md:5: thinking-level — " + FIXTURE_ALLOWLIST.agents.forbidden["thinking-level"]);
357
+ });
358
+
359
+ // ---------------------------------------------------------------------------
360
+ // #1314's mutation proof, done literally: mutate a fixture in place, run the
361
+ // CLI, assert red; revert; run again; assert green. Three shapes: forbidden
362
+ // key, missing required key, unknown key.
363
+ // ---------------------------------------------------------------------------
364
+
365
+ test("MUTATION PROOF: a forbidden key introduced -> red; reverted -> green", () => {
366
+ const { allowlistPath, file, d } = agentFixtureDir();
367
+ const clean = "---\nname: fleet-x\ndescription: d\nmodel: \"@slow:xhigh\"\n---\nbody\n";
368
+ writeFileSync(file, clean);
369
+ const green1 = runCli(["--allowlist", allowlistPath, "agents/x.agent.md"], d);
370
+ assert.equal(green1.status, 0, "clean fixture starts green");
371
+
372
+ const mutated = "---\nname: fleet-x\ndescription: d\nmodel: \"@slow:xhigh\"\nthinking-level: low\n---\nbody\n";
373
+ writeFileSync(file, mutated);
374
+ const red = runCli(["--allowlist", allowlistPath, "agents/x.agent.md"], d);
375
+ assert.equal(red.status, 1, "forbidden key introduced -> red");
376
+ assert.match(red.stdout, /thinking-level — /);
377
+
378
+ writeFileSync(file, clean);
379
+ const green2 = runCli(["--allowlist", allowlistPath, "agents/x.agent.md"], d);
380
+ assert.equal(green2.status, 0, "reverted -> green again");
381
+ });
382
+
383
+ test("MUTATION PROOF: a required key removed -> red; reverted -> green", () => {
384
+ const { allowlistPath, file, d } = agentFixtureDir();
385
+ const clean = "---\nname: fleet-x\ndescription: d\nmodel: \"@slow:xhigh\"\n---\nbody\n";
386
+ writeFileSync(file, clean);
387
+ assert.equal(runCli(["--allowlist", allowlistPath, "agents/x.agent.md"], d).status, 0);
388
+
389
+ const mutated = "---\nname: fleet-x\nmodel: \"@slow:xhigh\"\n---\nbody\n"; // description removed
390
+ writeFileSync(file, mutated);
391
+ const red = runCli(["--allowlist", allowlistPath, "agents/x.agent.md"], d);
392
+ assert.equal(red.status, 1, "missing required key -> red");
393
+ assert.match(red.stdout, /description — required key missing/);
394
+
395
+ writeFileSync(file, clean);
396
+ const green = runCli(["--allowlist", allowlistPath, "agents/x.agent.md"], d);
397
+ assert.equal(green.status, 0, "reverted -> green again");
398
+ });
399
+
400
+ test("MUTATION PROOF: an unknown key introduced -> red; reverted -> green", () => {
401
+ const { allowlistPath, file, d } = agentFixtureDir();
402
+ const clean = "---\nname: fleet-x\ndescription: d\nmodel: \"@slow:xhigh\"\n---\nbody\n";
403
+ writeFileSync(file, clean);
404
+ assert.equal(runCli(["--allowlist", allowlistPath, "agents/x.agent.md"], d).status, 0);
405
+
406
+ const mutated = "---\nname: fleet-x\ndescription: d\nmodel: \"@slow:xhigh\"\nomp-only-experimental-flag: yes\n---\nbody\n";
407
+ writeFileSync(file, mutated);
408
+ const red = runCli(["--allowlist", allowlistPath, "agents/x.agent.md"], d);
409
+ assert.equal(red.status, 1, "unknown key -> red");
410
+ assert.match(red.stdout, /omp-only-experimental-flag — unrecognised key/);
411
+
412
+ writeFileSync(file, clean);
413
+ const green = runCli(["--allowlist", allowlistPath, "agents/x.agent.md"], d);
414
+ assert.equal(green.status, 0, "reverted -> green again");
415
+ });
416
+
417
+ // ---------------------------------------------------------------------------
418
+ // The real tree, with the real allow-list: today's own first real green
419
+ // (#1298/ADR 0005's own prediction — red on missing thinking-level until
420
+ // #1343, green after; #1343 is on main, so this is the gate's first real
421
+ // green, run here rather than merely asserted).
422
+ // ---------------------------------------------------------------------------
423
+
424
+ test("REAL TREE: every tracked agents/skills/commands frontmatter file in this checkout passes the real allow-list", () => {
425
+ const agentFiles = ["fleet-implementer.agent.md", "fleet-implementer-alt.agent.md"]
426
+ .map((f) => `agents/${f}`);
427
+ const skillFiles = ["next-ticket", "run-team", "sizing-a-ticket"].map((s) => `skills/${s}/SKILL.md`);
428
+ const commandFiles = ["review-and-fix.md", "run-merge-bot.md"].map((f) => `commands/${f}`);
429
+ const all = [...agentFiles, ...skillFiles, ...commandFiles];
430
+ for (const f of all) {
431
+ assert.ok(existsSync(join(REPO, f)), `${f} exists in the real tree`);
432
+ }
433
+ const r = runCli(["--allowlist", REAL_ALLOWLIST_PATH, ...all], REPO);
434
+ assert.equal(r.status, 0, `real tree is clean against the real allow-list:\n${r.stdout}${r.stderr}`);
435
+ assert.equal(r.stdout, "");
436
+ });
@@ -0,0 +1,124 @@
1
+ // Shared by every `.mjs` script under this directory that shells out to git —
2
+ // two exports, one per half of the same spawn. `gitEnv()` builds the env the
3
+ // git child is given; `workspaceDirFromGitCommonDir()` turns what the most
4
+ // common of those children answers with, `rev-parse --git-common-dir`, into
5
+ // the workspace directory a run's files live under. The first half is #1599's
6
+ // reasoning, below; the second is #1658's, beside its own function.
7
+ //
8
+ // GIT_DIR and GIT_WORK_TREE outrank both the child's cwd and an explicit `-C`
9
+ // argument — measured directly (#1599): a `git rev-parse`/`ls-files` call
10
+ // pointed at a repository via `cwd` or `-C` still answers for whichever
11
+ // repository an ambient GIT_DIR or GIT_WORK_TREE names, silently, often at
12
+ // exit 0. #1020 closed the identical class in every shell script under this
13
+ // directory with one line, `unset GIT_DIR GIT_WORK_TREE`; there is no shell
14
+ // to unset in here, so the child's env has to be built instead — and #1020's
15
+ // own EXEMPT reasons for net.sh/worktree.sh ("a library... unset there would
16
+ // reach back into the caller's environment") do not transfer: a spawned
17
+ // child's env object is already private to it, never the calling process's.
18
+ //
19
+ // `fleet-state.mjs`'s `statePath()` and `ledger.mjs`'s tracker-query probe
20
+ // each spell the same three lines inline — `{ ...process.env }` then two
21
+ // `delete`s — predating this module, and #1599's own body cites exactly that
22
+ // duplication as the reason a THIRD hand-spelled copy (its own measured
23
+ // hazard, `ledger.mjs`'s `defaultLedgerPath()`) should not become a fourth.
24
+ // A shared helper also turns "does this call scrub the ambient vars" back
25
+ // into a one-name grep, `gitEnv(`, the way `unset GIT_DIR GIT_WORK_TREE` is
26
+ // one for shell — see `ambient-git-vars-mjs-prose.test.mjs`.
27
+ //
28
+ // The two pre-existing inline sites are deliberately NOT migrated to call
29
+ // this. Neither is in #1599's scope — its own body excludes
30
+ // `fleet-state.mjs`'s `statePath()` by name (already fixed and covered, by
31
+ // PR #1598), and `ledger.mjs`'s tracker-query scrub is likewise already
32
+ // measured and covered (`ledger.test.mjs`, "an inherited GIT_DIR or GH_REPO
33
+ // cannot retarget the query…") — and touching either to satisfy a detector
34
+ // would be churn with no behavioural change. `ambient-git-vars-mjs-prose.test.mjs`
35
+ // carries both of them by name instead of by import.
36
+
37
+ import { realpathSync } from "node:fs";
38
+ import { dirname, resolve } from "node:path";
39
+
40
+ /**
41
+ * `base` (defaulting to `process.env`) with GIT_DIR and GIT_WORK_TREE
42
+ * removed, so a git child spawned with the result cannot be retargeted by
43
+ * whichever repository an ambient invocation — a git hook, `rebase --exec`,
44
+ * `bisect run` — happened to set either to.
45
+ *
46
+ * `overrides` are applied AFTER the copy of `base` and BEFORE the two
47
+ * deletes below, so a caller can add its own keys (`LC_ALL`, `GH_REPO`) in
48
+ * the same call without a second object spread, and an override that itself
49
+ * names GIT_DIR or GIT_WORK_TREE cannot smuggle either back in.
50
+ */
51
+ export function gitEnv(overrides = {}, base = process.env) {
52
+ const env = { ...base, ...overrides };
53
+ delete env.GIT_DIR;
54
+ delete env.GIT_WORK_TREE;
55
+ return env;
56
+ }
57
+
58
+ // Every fleet script that needs to know WHERE the run's files live asks git
59
+ // the same question — `rev-parse --git-common-dir` — and then resolves the
60
+ // answer the same way, because the answer is the same shape in all three:
61
+ // the common dir is shared by every worktree of one repository (git answers
62
+ // with the MAIN checkout's git dir from inside a linked worktree), so its
63
+ // PARENT is the one workspace a run has, whichever worktree asked. That is
64
+ // why a member running from `.worktrees/<n>-slug` and the controller running
65
+ // from the checkout root agree about the run's single ledger, its single
66
+ // heartbeat and its single board.
67
+ //
68
+ // Three callers hand-spelled that resolution, one apiece, before #1658:
69
+ // `ledger.mjs`'s `defaultLedgerPath()`, `fleet-state.mjs`'s `statePath()` and
70
+ // `board.mjs`'s `resolveCockpitInstance()` — and `fleet-state.mjs`'s own
71
+ // comment had already written down the trigger ("if a third file ever needs
72
+ // this, the resolution itself should move"), which #1656's addition tripped.
73
+ // What is NOT shared is the part each caller owns: the filename it joins on
74
+ // (`ledger.md`, `heartbeat.json`, `.fleet`), the wording of the warning it
75
+ // degrades with, and what its own degraded answer is. Hence the seam: this
76
+ // function answers the directory or `null`, and every caller composes the
77
+ // rest around it.
78
+
79
+ /**
80
+ * The workspace directory a `git rev-parse --git-common-dir` answer names —
81
+ * the directory HOLDING the common git dir — resolved against `cwd`, or
82
+ * `null` when the answer carries nothing usable.
83
+ *
84
+ * `null` is the signal every caller's degrade arm branches on, and the reason
85
+ * this returns it rather than a cwd-relative fallback of its own: what a
86
+ * degraded answer should be is the caller's to say (a cwd-relative filename
87
+ * for the ledger, an absolute cwd-anchored `.fleet` for the board), and so is
88
+ * the warning that must accompany it — a degrade nobody announces is the
89
+ * failure class all three of those warnings exist to close.
90
+ *
91
+ * `resolve(cwd, …)` rather than resolve()'s implicit `process.cwd()`: git
92
+ * answers this RELATIVE — a bare `.git` — when it runs from a checkout's top
93
+ * level, and the cwd that was relative to is an argument here, not ambient,
94
+ * so a caller that injects the answer (board.mjs, which takes it as a
95
+ * parameter so its worktree and resolution-failed cases stay plain test rows)
96
+ * can inject the cwd too. `cwd` defaults to `process.cwd()`, which is what
97
+ * the callers that spawn git themselves already resolved against.
98
+ *
99
+ * The `trim()` is what makes a newline-only answer the `null` case rather
100
+ * than a path; a trailing newline riding on a real answer would be discarded
101
+ * by `dirname()` anyway, together with the rest of the final segment.
102
+ *
103
+ * `canonicalise` is OPT-IN, and deliberately so (#1658). Only `board.mjs`
104
+ * takes it: a symlinked route to one workspace derives a SECOND port and a
105
+ * second state directory for a cockpit already being served (#1582), so the
106
+ * cockpit's key has to be the canonical form. `ledger.mjs` and
107
+ * `fleet-state.mjs` do not — both PRINT the path they resolve (the ledger in
108
+ * `check`'s JSON, both in their degrade warnings), and realpath would change
109
+ * that output without changing which file they reach, since the canonical and
110
+ * symlinked spellings of one path are one file. Left off, this function reads
111
+ * nothing: `canonicalise: true` is its only filesystem access.
112
+ *
113
+ * A path that does not resolve is not a failure when it is asked for: the
114
+ * caller gets a usable key back, just an uncanonicalised one. A workspace
115
+ * directory removed out from under a running cockpit must not turn resolution
116
+ * into a throw.
117
+ */
118
+ export function workspaceDirFromGitCommonDir(gitCommonDir, cwd = process.cwd(), { canonicalise = false } = {}) {
119
+ const common = String(gitCommonDir ?? "").trim();
120
+ if (!common) return null;
121
+ const workspace = dirname(resolve(cwd, common));
122
+ if (!canonicalise) return workspace;
123
+ try { return realpathSync(workspace); } catch { return workspace; }
124
+ }