@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,184 @@
1
+ // #443. Step 7's push was documented unconditionally with `--force-with-lease`,
2
+ // on a path whose common case is a first push where the lease buys nothing —
3
+ // and it is the exact string #149 documents as intermittently denied by the
4
+ // auto-mode classifier, before the push is attempted — so a denial is not a
5
+ // lease race. It is judged per invocation and intermittently, never once for
6
+ // the command, so a retry is a coin flip rather than a fix
7
+ // (`run-merge-bot.md`: "judged and intermittently denied per invocation").
8
+ //
9
+ // Two stronger claims were measured and REFUTED — this file must never pin
10
+ // either back in:
11
+ // - the lease does NOT fail on a fresh branch. `git push --force-with-lease
12
+ // -u origin HEAD` on a never-pushed branch succeeds cleanly at rc 0
13
+ // (measured, git 2.50.1, bare origin + clone).
14
+ // - the flag is NOT unconditionally useless. Step 7 rebases immediately
15
+ // before pushing, so a member re-entering step 7 after an earlier push
16
+ // genuinely needs the force — removing the flag would be wrong.
17
+ //
18
+ // Ruling: keep the push command exactly as written, add one sentence saying
19
+ // WHY the lease is there — a member who knows it protects a re-push can
20
+ // reason about a denial; one told only "use a plain push if denied" uses a
21
+ // plain push on the re-push too, where the force is load-bearing.
22
+ import { test } from "node:test";
23
+ import assert from "node:assert/strict";
24
+ import { readFileSync } from "node:fs";
25
+ import { join } from "node:path";
26
+ import { between, phrase } from "./prose-pin.mjs";
27
+
28
+ const REPO = join(import.meta.dirname, "..");
29
+ const NEXT_TICKET = readFileSync(join(REPO, "skills", "next-ticket", "SKILL.md"), "utf8");
30
+
31
+ const step7 = () =>
32
+ between(NEXT_TICKET, "## 7. When the superpowers path reports done", "## Red flags", "next-ticket/SKILL.md step 7");
33
+
34
+ // Narrow to the note itself before pinning anything, the way
35
+ // candidates-exit3-prose.test.mjs narrows to one table row. A positive
36
+ // `assert.match` over the whole step-7 slice is presence-only: it reddens when
37
+ // a pinned phrase is DELETED and stays green when a contradicting clause is
38
+ // spliced in beside it, phrases intact. Both halves below were measured passing
39
+ // 3/3 against a section-wide slice while asserting the opposite of the truth.
40
+ const note = () =>
41
+ between(step7(), "`--force-with-lease` matters only on a re-push", "`Closes #N` closes issue on merge", "step 7's lease note");
42
+
43
+ // The note's own `;` splits it into the two claims that must not leak into each
44
+ // other: the force is required on a re-push, the plain push is safe only on a
45
+ // first one. Slicing at the LAST `;` keeps every appended clause inside the
46
+ // fallback half rather than letting a new one escape both pins.
47
+ const semi = () => {
48
+ const at = note().lastIndexOf(";");
49
+ assert.notEqual(at, -1, "step 7's lease note no longer joins its two halves with `;` — update this test");
50
+ return at;
51
+ };
52
+ const reasonHalf = () => note().slice(0, semi());
53
+ const fallbackHalf = () => note().slice(semi());
54
+
55
+ test("step 7 still pushes with the lease, unconditionally — the command itself is untouched", () => {
56
+ assert.match(
57
+ step7(),
58
+ /git push --force-with-lease -u origin HEAD/,
59
+ "step 7's push command changed — the ruling was to add a sentence beside it, not to touch the command",
60
+ );
61
+ });
62
+
63
+ test("step 7 says the lease matters only on a re-push, and why", () => {
64
+ const s = reasonHalf();
65
+ assert.match(
66
+ s,
67
+ phrase("rebases immediately before pushing"),
68
+ "step 7 lost the mechanism the reason rests on — without it a reader can't tell why a re-push needs the force",
69
+ );
70
+ assert.match(
71
+ s,
72
+ phrase("re-entering step 7 after an earlier push"),
73
+ "step 7 no longer ties the force to the re-push case — the reason is now floating, unattached to when it applies",
74
+ );
75
+ // Both pins above are subject-side, so a reversal that rewrites only the
76
+ // PREDICATE leaves them verbatim. Pin the predicate too, and ban its
77
+ // negation, or the note can carry the refuted "the flag is unconditionally
78
+ // useless" claim with every pinned phrase still in place.
79
+ assert.match(
80
+ s,
81
+ phrase("needs the force to land the rebased commits"),
82
+ "step 7 no longer says what the force is FOR on a re-push — the claim's predicate is what a reversal rewrites first",
83
+ );
84
+ assert.doesNotMatch(
85
+ s,
86
+ /\b(?:not|never)\b[\s\S]{0,40}\bneeds?\b/i,
87
+ "step 7 now denies that a re-push needs the force — measured false, and #443's Brief refuted it: step 7 rebases immediately before pushing, so the force is load-bearing there",
88
+ );
89
+ });
90
+
91
+ test("step 7 scopes the plain-push fallback to a branch that has never been pushed", () => {
92
+ const s = fallbackHalf();
93
+ // The wrongly-ACCEPT half (AC-4): a reader must not come away licensed to
94
+ // plain-push on a re-push, where a denial means the force is load-bearing.
95
+ assert.match(
96
+ s,
97
+ phrase("a branch that has never been pushed"),
98
+ "step 7 no longer scopes the plain-push fallback to a first push — a reader could now use it on a denied re-push, where the force is load-bearing",
99
+ );
100
+ assert.match(
101
+ s,
102
+ phrase("git push -u origin HEAD"),
103
+ "step 7 no longer names the plain-push fallback command itself",
104
+ );
105
+ // Scoping the fallback IN to the first push does not scope it OUT of the
106
+ // re-push: both pins above survive a clause that widens it, appended right
107
+ // beside them. This half is the one that hands out the plain push, so the
108
+ // re-push must not be named in it at all.
109
+ assert.doesNotMatch(
110
+ s,
111
+ /\bre-?push\b/i,
112
+ "step 7's plain-push fallback now reaches the re-push case — that is the AC-4 defect: on a re-push the force is load-bearing and a denial there is not routed around",
113
+ );
114
+ });
115
+
116
+ // #1049. The ruling above settled WHY the lease is documented; it left open
117
+ // what a member does when the force is DENIED on a re-push. There is no route
118
+ // around that one — the force is load-bearing there — so the page states the
119
+ // only correct move: stop and report the denial. The failure it closes is a
120
+ // member reading a denial as "use more force" and retrying with a plain
121
+ // `--force`, which drops the lease the step exists to keep.
122
+ //
123
+ // NOT a route, measured (#1049) and banned here so a later author does not add
124
+ // it back: `gh pr update-branch` is server-side and pulls changes FROM the base
125
+ // branch, so it cannot upload locally-rebased commits — which is exactly what a
126
+ // step-7 re-push has to do. The merge bot's own denial-recovery route runs that
127
+ // command for a different purpose; the analogy does not carry to step 7.
128
+ test("step 7 routes a denied re-push to stop-and-report, never to a plain force", () => {
129
+ // In the REASON half, never the fallback one: that half bans the term
130
+ // `re-push` outright (the test above), so the same clause moved after the
131
+ // note's last `;` reds both this pin and that ban — measured, two reds — and
132
+ // correctly, since the fallback half is the one that hands out a plain push.
133
+ const s = reasonHalf();
134
+ assert.match(
135
+ s,
136
+ phrase("stop and report the denial"),
137
+ "step 7 no longer says what to do when the force is denied on a re-push — the gap #1049 was filed for",
138
+ );
139
+ assert.match(
140
+ s,
141
+ phrase("never retry with a plain `--force`"),
142
+ "step 7 no longer bans the plain-force retry — the move a member makes when a denial reads as 'use more force', and the one that drops the lease",
143
+ );
144
+ // Both pins above are deletion-only: they red when the clause goes, and on a
145
+ // reversal to "retry with a plain `--force` until it lands" (both measured).
146
+ // They stay green when a clause licensing the retry is spliced in BESIDE
147
+ // them, phrases intact — measured with "— if the classifier still denies it,
148
+ // `git push --force` lands the rebase" appended inside the reason half: the
149
+ // file goes 3/4 and the ONLY assertion that reds is the ban below. What such
150
+ // a clause has to name is the bare command, so that is what is banned — over
151
+ // the whole note, not one half, since either half could carry it. The
152
+ // lookahead is load-bearing rather than cautious: `\b` sits between `force`
153
+ // and `-with`, so the step's own documented command matches without it.
154
+ //
155
+ // #1446. `--force` is not the only spelling of "more force": `git push -f`
156
+ // (or `-f` bundled into another short option, e.g. `-uf`) and a raw
157
+ // force-push refspec (`git push origin +HEAD`) retry with exactly the same
158
+ // effect and neither named `--force` at all — measured 4/4 green against
159
+ // the un-widened regex above, i.e. the ban did not cover the class of retry
160
+ // the prose exists to forbid, only one spelling of it. Widened to three
161
+ // alternatives sharing one `git push` anchor, skipping up to three
162
+ // intervening tokens (remote/refspec/other flags) before the one that must
163
+ // carry the force: `--force` (long, as before), a short option whose letters
164
+ // include `f` and are not preceded by a hyphen or word character (excludes
165
+ // matching inside `--force[-with-lease]`, where the second `f` is preceded
166
+ // by the first dash, and inside a hyphenated English word, where it is
167
+ // preceded by a letter), or a bare `+<ref>` force-push refspec. Measured
168
+ // against the real note: still 4/4 green (baseline unchanged); against
169
+ // "`git push -f`" and "`git push origin +HEAD`" appended the same way as the
170
+ // `--force` mutation above: both now red on this assertion alone, matching
171
+ // the `--force` case exactly.
172
+ //
173
+ // Deliberately still uncaught: prose that licenses "more force" without
174
+ // naming a `git push` command at all (e.g. "retry with more force" or "force
175
+ // it through"). That is a semantic ban, not a lexical one — no regex over
176
+ // command text can catch prose that never spells the command — and is out
177
+ // of scope for this pin the same way the un-widened version never attempted
178
+ // it either.
179
+ assert.doesNotMatch(
180
+ note(),
181
+ /git push(?:\s+[\w./:-]+){0,3}\s+(?:--force(?!-with-lease)\b|(?<![-\w])-\w*f\w*\b|\+[\w./:-]+)/,
182
+ "step 7's lease note now names a bare `git push --force`, a short `-f` retry, or a `+<ref>` force-push refspec — a denial has no forcing route around it, and these are the commands a member reaches for when the page implies there is",
183
+ );
184
+ });
@@ -0,0 +1,64 @@
1
+ {
2
+ "_comment": "The allow-list data (#1314, #1347, ADR 0014). One allow-list per artefact kind (agents, skills, commands) for omp's documented keys (`omp://task-agent-discovery.md`, `omp://skills.md`). Enforced by frontmatter-check.mjs: unknown keys are rejected, required keys are enforced, and `forbidden` catches a key that reads as configuration but silently reroutes a member's tier, tree, or dispatch.",
3
+
4
+ "agents": {
5
+ "required": ["name", "description", "model"],
6
+ "allowed": [
7
+ "tools", "disallowedTools", "skills", "maxTurns", "background", "color", "memory",
8
+ "spawns", "output", "read-summarize", "blocking", "autoloadSkills"
9
+ ],
10
+ "forbidden": {
11
+ "thinking-level": "the level rides on model's `@<role>:<level>` suffix — one spelling only",
12
+ "thinking": "the level rides on model's `@<role>:<level>` suffix — one spelling only",
13
+ "effort": "retired Claude Code key — silently ignored by omp",
14
+ "prewalk": "silent mid-run model hand-off — the tier degradation ADR 0005 forbids",
15
+ "advisor": "silent mid-run model hand-off — the tier degradation ADR 0005 forbids",
16
+ "isolation": "members never use harness isolation (#1315): omp builds the workspace outside the claimed worktree and patch-applies into the controller's checkout"
17
+ },
18
+ "values": {
19
+ "model": {
20
+ "pattern": "^@(slow|task|smol):(minimal|low|medium|high|xhigh|max)$",
21
+ "message": "must be a fleet tier route `@slow|@task|@smol` with an explicit `:<level>` suffix (ADR 0014)"
22
+ },
23
+ "name": {
24
+ "pattern": "^fleet-[^:]*$",
25
+ "message": "must be fleet--prefixed with no ':' — omp's agent registry is bare-name/unnamespaced, so the prefix is the only collision guard (#1303)"
26
+ }
27
+ }
28
+ },
29
+
30
+ "skills": {
31
+ "required": ["name", "description"],
32
+ "allowed": [
33
+ "argument-hint", "arguments", "disable-model-invocation", "user-invocable",
34
+ "allowed-tools", "disallowed-tools", "when_to_use", "paths", "metadata", "license", "compatibility",
35
+ "globs", "hide"
36
+ ],
37
+ "forbidden": {
38
+ "hooks": "no documented meaning for fleet skill frontmatter",
39
+ "shell": "no documented meaning for fleet skill frontmatter",
40
+ "alwaysApply": "omp auto-injection — fleet skills are invoked, never injected"
41
+ },
42
+ "values": {
43
+ "disable-model-invocation": ["true", "false"]
44
+ }
45
+ },
46
+
47
+ "commands": {
48
+ "required": ["description"],
49
+ "allowed": [
50
+ "name", "argument-hint", "arguments", "disable-model-invocation", "user-invocable",
51
+ "allowed-tools", "disallowed-tools"
52
+ ],
53
+ "forbidden": {
54
+ "hooks": "no documented meaning for fleet skill frontmatter",
55
+ "shell": "no documented meaning for fleet skill frontmatter",
56
+ "alwaysApply": "omp auto-injection — fleet skills are invoked, never injected",
57
+ "globs": "skills-only (omp file-scoping) — no defined meaning for a flat command file",
58
+ "paths": "skills-only — no defined meaning for a flat command file"
59
+ },
60
+ "values": {
61
+ "disable-model-invocation": ["true", "false"]
62
+ }
63
+ }
64
+ }
@@ -0,0 +1,256 @@
1
+ #!/usr/bin/env node
2
+ // The allow-list checker (#1314, #1347). Layer 1 of two (#1298/ADR 0005):
3
+ // this is a STATIC audit of an agent/skill/command file's frontmatter SHAPE,
4
+ // before any run exists. Layer 2 (tier-check.mjs, #1345) compares a live
5
+ // dispatch's RESOLVED tier against the declaration; this file never reads a
6
+ // transcript and never runs anything.
7
+ //
8
+ // Contract, fixed on #1314 and recorded with the key sets on its closing
9
+ // comment: three key sets (agents, skills, commands), enforced in BOTH
10
+ // directions — an unknown key is a violation (half a contract leaves an
11
+ // undocumented addition silent) and a missing REQUIRED key is a
12
+ // violation — plus a third class, FORBIDDEN: a key that IS documented but
13
+ // silently re-routes a member's tier, tree, or dispatch rather than merely
14
+ // doing nothing. `frontmatter-allowlist.json` carries the data;
15
+ // this file carries no key names of its own.
16
+ //
17
+ // Failure contract: exit 1 per violation, each printed as
18
+ // `file:line: key — reason` (one line per violation, all files' violations
19
+ // printed before exiting). Exit 2 for CANNOT-RUN — the allow-list is
20
+ // missing or unreadable, or a file's frontmatter cannot be parsed at all.
21
+ // The distinction matters: a missing allow-list must fail LOUDLY rather
22
+ // than silently pass with an empty key set (#1314's own wording), which a
23
+ // bare exit-1-on-no-violations would do by accident if a missing file
24
+ // happened to yield an empty ruleset instead of an error.
25
+ //
26
+ // Kind classification is PATH-based, never content-sniffed: an ancestor
27
+ // segment named `agents`, a `<name>/SKILL.md` under `skills`, or a
28
+ // `commands/<name>.md` — the same convention install-root-audit.test.mjs's
29
+ // own tree walk and repo-root.mjs's own layout assumptions already use.
30
+ // Works whether invoked with a repo-relative path (`plugin/agents/x.md`,
31
+ // after #1336's re-nest) or a bare one under a kind directory (check-tracked.sh
32
+ // hands this xargs-expanded `git ls-files` paths, always repo-relative from
33
+ // the repo root check-tracked.sh itself runs in).
34
+ //
35
+ // Frontmatter is read as flat `key: value` scalar lines between a `---`
36
+ // fence pair — not a YAML parser, because every fleet frontmatter block in
37
+ // this tree is exactly that shape (tier-check.mjs's own `parseFrontmatter`
38
+ // makes the identical simplification, for the identical files). A block
39
+ // this reader cannot make sense of (no closing fence, a line that is
40
+ // neither blank nor `key: value`) is CANNOT-RUN, not a violation — a parser
41
+ // that quietly skipped what it couldn't read would silently pass exactly
42
+ // the "frontmatter unparseable" case #1314 named as a hard exit-2.
43
+
44
+ import { readFileSync } from "node:fs";
45
+ import { dirname, join } from "node:path";
46
+ import { fileURLToPath, pathToFileURL } from "node:url";
47
+
48
+ const NAME = "frontmatter-check";
49
+ const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
50
+ const DEFAULT_ALLOWLIST_PATH = join(SCRIPT_DIR, "frontmatter-allowlist.json");
51
+
52
+ // ---------------------------------------------------------------------------
53
+ // pure core — unit- and mutation-tested directly (frontmatter-check.test.mjs),
54
+ // no filesystem or process access below this line until main()
55
+ // ---------------------------------------------------------------------------
56
+
57
+ /** Parses and shape-validates the allow-list JSON. `{ allowlist }` or `{ error }`. */
58
+ export function parseAllowlist(raw) {
59
+ let json;
60
+ try {
61
+ json = JSON.parse(raw);
62
+ } catch (e) {
63
+ return { error: `not valid JSON (${e.message})` };
64
+ }
65
+ for (const kind of ["agents", "skills", "commands"]) {
66
+ const section = json[kind];
67
+ if (!section || typeof section !== "object" || Array.isArray(section)) {
68
+ return { error: `missing or malformed "${kind}" section` };
69
+ }
70
+ for (const field of ["required", "allowed", "forbidden"]) {
71
+ if (field === "forbidden") {
72
+ if (!section.forbidden || typeof section.forbidden !== "object" || Array.isArray(section.forbidden)) {
73
+ return { error: `"${kind}.forbidden" must be an object of key -> reason` };
74
+ }
75
+ } else if (!Array.isArray(section[field])) {
76
+ return { error: `"${kind}.${field}" must be an array` };
77
+ }
78
+ }
79
+ }
80
+ return { allowlist: json };
81
+ }
82
+
83
+ /**
84
+ * Which kind (`agents`/`skills`/`commands`) a given path belongs to, or
85
+ * `null` if it matches none of the three shapes. Scans every path segment
86
+ * rather than assuming a fixed depth, so both `plugin/agents/x.md` and a
87
+ * bare `agents/x.md` classify identically.
88
+ */
89
+ export function kindForPath(anyPath) {
90
+ const parts = String(anyPath).split("/").filter(Boolean);
91
+ for (let i = 0; i < parts.length; i++) {
92
+ if (parts[i] === "agents" && i + 2 === parts.length && parts[i + 1].endsWith(".md")) return "agents";
93
+ if (parts[i] === "skills" && i + 3 === parts.length && parts[i + 2] === "SKILL.md") return "skills";
94
+ if (parts[i] === "commands" && i + 2 === parts.length && parts[i + 1].endsWith(".md")) return "commands";
95
+ }
96
+ return null;
97
+ }
98
+
99
+ /**
100
+ * Reads the flat `key: value` fields out of a `---`-fenced frontmatter
101
+ * block. `{ fields: [{ key, value, line }] }` or `{ error }`. `line` is the
102
+ * 1-based source line the field's `key:` token sits on, so callers can print
103
+ * `file:line:` without re-deriving it. A value wrapped in a single matching
104
+ * pair of double or single quotes has them stripped (YAML's own scalar
105
+ * quoting) — `model: "@slow:xhigh"` and `model: @slow:xhigh` parse to the
106
+ * same value.
107
+ */
108
+ export function parseFrontmatter(text) {
109
+ const src = String(text ?? "");
110
+ if (!src.startsWith("---\n") && src !== "---" && !src.startsWith("---\r\n")) {
111
+ return { error: "no opening --- fence at the start of the file" };
112
+ }
113
+ const firstNewline = src.indexOf("\n");
114
+ const rest = src.slice(firstNewline + 1);
115
+ const closeMatch = /\n---\s*(?:\r?\n|$)/.exec(rest);
116
+ if (!closeMatch) return { error: "no closing --- fence" };
117
+ const body = rest.slice(0, closeMatch.index);
118
+ const lines = body.split(/\r?\n/);
119
+ const fields = [];
120
+ for (let i = 0; i < lines.length; i++) {
121
+ const line = lines[i];
122
+ const sourceLine = i + 2; // +1 for the opening fence line, +1 for 1-based
123
+ if (line.trim() === "") continue;
124
+ const m = /^([A-Za-z][\w-]*):\s?(.*)$/.exec(line);
125
+ if (!m) return { error: `unparseable frontmatter at line ${sourceLine}: ${JSON.stringify(line)}` };
126
+ let value = m[2].trim();
127
+ const quoted = /^"(.*)"$/.exec(value) || /^'(.*)'$/.exec(value);
128
+ if (quoted) value = quoted[1];
129
+ fields.push({ key: m[1], value, line: sourceLine });
130
+ }
131
+ return { fields };
132
+ }
133
+
134
+ /**
135
+ * A value-rule violation message for `key`/`value` under `kindRules.values`,
136
+ * or `null` if the value is fine (or the key carries no value rule at all).
137
+ * A rule is either an enum (array of legal literal strings) or a
138
+ * `{ pattern, message }` regex rule (agents' `name`).
139
+ */
140
+ function valueViolation(kindRules, key, value) {
141
+ const rule = kindRules.values && kindRules.values[key];
142
+ if (rule === undefined) return null;
143
+ if (Array.isArray(rule)) {
144
+ if (rule.includes(value)) return null;
145
+ return `value ${JSON.stringify(value)} is not one of {${rule.join(", ")}}`;
146
+ }
147
+ if (rule && typeof rule === "object" && typeof rule.pattern === "string") {
148
+ if (new RegExp(rule.pattern).test(value)) return null;
149
+ return rule.message || `value ${JSON.stringify(value)} does not match ${rule.pattern}`;
150
+ }
151
+ return null;
152
+ }
153
+
154
+ /**
155
+ * Every allow-list violation for one file's already-parsed fields, against
156
+ * one kind's rules. `[{ line, key, reason }]`, in file order, with missing
157
+ * required keys appended last (they have no field/line of their own —
158
+ * reported at line 1, the frontmatter's own opening fence, which is where a
159
+ * reader would add them).
160
+ */
161
+ export function checkFields(kind, allowlist, fields) {
162
+ const rules = allowlist[kind];
163
+ const violations = [];
164
+ const seen = new Set();
165
+ for (const { key, value, line } of fields) {
166
+ seen.add(key);
167
+ if (Object.prototype.hasOwnProperty.call(rules.forbidden, key)) {
168
+ violations.push({ line, key, reason: rules.forbidden[key] });
169
+ continue;
170
+ }
171
+ if (!rules.required.includes(key) && !rules.allowed.includes(key)) {
172
+ violations.push({ line, key, reason: `unrecognised key for ${kind} frontmatter — not required, allowed, or forbidden` });
173
+ continue;
174
+ }
175
+ const vv = valueViolation(rules, key, value);
176
+ if (vv) violations.push({ line, key, reason: vv });
177
+ }
178
+ for (const req of rules.required) {
179
+ if (!seen.has(req)) violations.push({ line: 1, key: req, reason: "required key missing" });
180
+ }
181
+ return violations;
182
+ }
183
+
184
+ /** `file:line: key — reason`, the ticket's exact violation-line shape. */
185
+ export function formatViolation(file, v) {
186
+ return `${file}:${v.line}: ${v.key} — ${v.reason}`;
187
+ }
188
+
189
+ // ---------------------------------------------------------------------------
190
+ // CLI
191
+ // ---------------------------------------------------------------------------
192
+
193
+ function dieCannotRun(message) {
194
+ process.stderr.write(`${NAME}: ${message}\n`);
195
+ process.exit(2);
196
+ }
197
+
198
+ function usage() {
199
+ process.stderr.write(`usage: ${NAME} [--allowlist <path>] <frontmatter-file...>\n`);
200
+ process.exit(2);
201
+ }
202
+
203
+ function main() {
204
+ const argv = process.argv.slice(2);
205
+ let allowlistPath = DEFAULT_ALLOWLIST_PATH;
206
+ const files = [];
207
+ for (let i = 0; i < argv.length; i++) {
208
+ if (argv[i] === "--allowlist") {
209
+ allowlistPath = argv[i + 1];
210
+ i += 1;
211
+ if (allowlistPath === undefined) usage();
212
+ } else {
213
+ files.push(argv[i]);
214
+ }
215
+ }
216
+ if (files.length === 0) usage();
217
+
218
+ let raw;
219
+ try {
220
+ raw = readFileSync(allowlistPath, "utf8");
221
+ } catch (e) {
222
+ dieCannotRun(`allow-list unreadable at ${allowlistPath} (${e.code || e.message})`);
223
+ }
224
+ const { allowlist, error: allowlistError } = parseAllowlist(raw);
225
+ if (allowlistError) dieCannotRun(`allow-list at ${allowlistPath} ${allowlistError}`);
226
+
227
+ let anyViolation = false;
228
+ for (const file of files) {
229
+ let text;
230
+ try {
231
+ text = readFileSync(file, "utf8");
232
+ } catch (e) {
233
+ dieCannotRun(`cannot read ${file} (${e.code || e.message})`);
234
+ }
235
+
236
+ const kind = kindForPath(file);
237
+ if (!kind) {
238
+ dieCannotRun(
239
+ `cannot classify ${file} as agents/skills/commands frontmatter — expected `
240
+ + '".../agents/<name>.md", ".../skills/<name>/SKILL.md", or ".../commands/<name>.md"',
241
+ );
242
+ }
243
+
244
+ const parsed = parseFrontmatter(text);
245
+ if (parsed.error) dieCannotRun(`${file}: ${parsed.error}`);
246
+
247
+ for (const v of checkFields(kind, allowlist, parsed.fields)) {
248
+ anyViolation = true;
249
+ process.stdout.write(formatViolation(file, v) + "\n");
250
+ }
251
+ }
252
+
253
+ process.exit(anyViolation ? 1 : 0);
254
+ }
255
+
256
+ if (import.meta.url === pathToFileURL(process.argv[1] || "").href) main();