@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,235 @@
1
+ // #436. `instruments.sh` is executed by an AGENT reading run-team/SKILL.md, so
2
+ // the script being correct buys nothing on its own — the whole mechanism is
3
+ // three clauses of prose, and every one of them can rot without an error:
4
+ //
5
+ // - the RULE (both refusing exit codes, no re-read after a refusal, and the
6
+ // one condition under which re-pinning is legitimate),
7
+ // - the PIN at phase 0 step 0, which must sit after the fast-forward,
8
+ // - the RE-PIN in the mid-run tooling fix, the one legitimate writer to the
9
+ // set. Lose that clause and the first tooling fix of a run makes every
10
+ // later gate refuse, which is how a guard gets discarded rather than fixed.
11
+ //
12
+ // The refusal half is the one worth pinning hardest. "Exit 0 is the only code
13
+ // that lets a gate proceed" is the acceptance criterion; a later edit that
14
+ // softened exit 2 to "re-run and continue" would read as perfectly reasonable
15
+ // prose and would turn a fail-closed guard into a fail-open one, silently.
16
+ //
17
+ // THE CEILING, shared with every prose pin in this repo: these prove a clause is
18
+ // PRESENT in the smallest slice that can hold it. None can prove a sentence
19
+ // added beside it does not negate it, and none runs anything —
20
+ // instruments.test.mjs owns the script's behaviour. Read each assertion as "not
21
+ // vacuous to REWORDING", never as "this rule cannot be subverted".
22
+ //
23
+ // Zero deps: `node --test plugin/scripts/instrument-check-prose.test.mjs`.
24
+
25
+ import { test } from "node:test";
26
+ import assert from "node:assert/strict";
27
+ import { accessSync, constants, readFileSync } from "node:fs";
28
+ import { join } from "node:path";
29
+ import { between, paragraph, phrase, sentences } from "./prose-pin.mjs";
30
+
31
+ const REPO = join(import.meta.dirname, "..");
32
+ const RUN_TEAM = readFileSync(join(REPO, "skills", "run-team", "SKILL.md"), "utf8");
33
+
34
+ // Bounded at both ends, and the slices are small on purpose: the file names
35
+ // `instruments.sh` in three separate places, so a slice running to EOF is
36
+ // satisfied by whichever of the other two survived.
37
+ const RULE = () =>
38
+ between(
39
+ RUN_TEAM,
40
+ "**You read your instruments out of a tree every member can write to",
41
+ "\n## Phase 0 — shortlist",
42
+ "run-team instrument rule",
43
+ );
44
+
45
+ // The END bound is THIS paragraph's own blank line, via `paragraph()`. It was a
46
+ // literal `between()` end anchor on the heading of the NEXT, unrelated phase-0
47
+ // step, which made an unrelated rename of that neighbour red this pin with a
48
+ // bare "no longer contains" that reads as an instrument-check regression and is
49
+ // not one — reproduced at `fa65476` as a negative control the suite should NOT
50
+ // have caught, and fixed here (#1062 records the exact wording; naming it again
51
+ // here would only be a second copy free to drift). A blank line is the bound
52
+ // that belongs to the pinned content and the one a rewrap cannot move, and
53
+ // `anchorAt` additionally refuses a start anchor occurring more than once — so
54
+ // this slice is tighter than what it replaces, still bounded at BOTH ends (an
55
+ // unbounded end would let an unrelated later copy satisfy the assertions, the
56
+ // worse failure), and no prose was added to give it something to anchor on.
57
+ // `paragraph()` is this directory's single definition of that bound (#823,
58
+ // #1372): a hand-rolled end anchor on neighbouring text is the defect it
59
+ // removes, not a style choice.
60
+ const PIN_STEP = () => paragraph(RUN_TEAM, "**Pin the instruments,", "run-team phase 0 pin");
61
+
62
+ // The gate list is one bullet, and this slice is bounded to it. Read out of the
63
+ // whole RULE slice, `phrase("reap")` is satisfied by the unrelated `reap.sh`
64
+ // mention further down it, so the loop below stayed green with the gate name
65
+ // gone. Word boundaries would not have fixed it: `\breap\b` matches inside
66
+ // `reap.sh` too. Bounding the text the loop reads is what cannot regress.
67
+ const GATES = () =>
68
+ between(
69
+ RUN_TEAM,
70
+ "**Re-check before you act on any instrument reading**",
71
+ "**Exit 0 is the only code",
72
+ "run-team gate list",
73
+ );
74
+
75
+ const TOOLING_FIX = () =>
76
+ between(RUN_TEAM, "## Fix the tooling mid-run", "\n## Failure handling", "run-team tooling fix");
77
+
78
+ test("the rule states that BOTH non-zero codes refuse, not just the changed one", () => {
79
+ const rule = RULE();
80
+ // Exit 0 as the sole proceeding code, and exit 2 named as a refusal beside
81
+ // exit 1. Pinning only "exit 1 refuses" would stay green on the fail-open
82
+ // rewrite this exists to prevent, since exit 2 is the code that reads like a
83
+ // retry.
84
+ assert.match(rule, phrase("Exit 0 is the only code that lets a gate proceed"));
85
+ assert.match(rule, phrase("Exit 1 (the set changed) and exit 2 (the check could not answer) both refuse"));
86
+ });
87
+
88
+ test("the rule forbids re-reading the instrument after a refusal", () => {
89
+ // "Refuse and report, not silently re-read" is #436's stated behaviour on
90
+ // detection. Without this clause the rule reads as a warning rather than a
91
+ // gate, and re-running until it passes is the obvious wrong reflex.
92
+ assert.match(RULE(), phrase("report what it printed and do NOT re-read the instrument"));
93
+ });
94
+
95
+ test("the rule names the gates it runs before, not just 'a gate'", () => {
96
+ // The check is worthless if the controller cannot tell where it applies. Each
97
+ // of these is a decision the fleet takes off an instrument reading.
98
+ const gates = GATES();
99
+ for (const gate of ["SHA acceptance", "CI verdict", "reconcile", "reap", "label gate"]) {
100
+ assert.match(gates, phrase(gate), `the rule stopped naming the ${gate}`);
101
+ }
102
+ });
103
+
104
+ test("the rule limits re-pinning to a change the controller made deliberately", () => {
105
+ // The baseline IS the mechanism, and `--pin` overwrites it with whatever is in
106
+ // the tree, never comparing first. Nothing in the script can tell a re-pin
107
+ // after a deliberate fix from one used to clear a refusal under time pressure,
108
+ // so this clause is the only thing between the two — and losing it discards
109
+ // the guard while every other pin here stays green.
110
+ const rule = RULE();
111
+ assert.match(rule, phrase("Re-pin only after a change you made deliberately"));
112
+ assert.match(rule, phrase("Re-pinning to clear a refusal you cannot explain discards the check"));
113
+ });
114
+
115
+ test("the rule records that refs are out of the digest, and why", () => {
116
+ // Not decoration: the ticket's corroborating evidence is a stray branch, so
117
+ // the next reader will ask. Without the reason, "add refs to the digest" is
118
+ // an obvious-looking improvement that fires on ordinary work several times a
119
+ // fleet run — which is the noise #436's third acceptance criterion rules out.
120
+ const rule = RULE();
121
+ assert.match(rule, phrase("It does not cover refs, deliberately"));
122
+ assert.match(rule, phrase("a per-gate refusal on that is noise"));
123
+ });
124
+
125
+ test("phase 0 step 0 pins the set, and only after the fast-forward", () => {
126
+ const step = PIN_STEP();
127
+ assert.match(step, phrase("instruments.sh --pin"));
128
+ // The ordering is the load-bearing half. Phase 0 step 0 fast-forwards the
129
+ // checkout because the runbook is read out of it; pinning first certifies the
130
+ // superseded text for the whole run, and every later gate then passes.
131
+ assert.match(step, phrase("after that fast-forward and before anything reads them"));
132
+ // Both anchors present, in this order. The hand-rolled `indexOf(ff) <
133
+ // indexOf(pin)` this replaces was vacuous to the rewording it exists to catch:
134
+ // reword the fast-forward away and `indexOf` returns -1, which is less than
135
+ // anything. `between` throws by name on either anchor missing and on the
136
+ // reversed order, which is every case the comparison was meant to cover.
137
+ between(RUN_TEAM, "git merge --ff-only origin/main", "**Pin the instruments,", "run-team phase 0 ordering");
138
+ });
139
+
140
+ /**
141
+ * The counterfactual rule, as a function so the refuse and accept cases can be
142
+ * fed input this repo does not contain. Returns null when the step is sound,
143
+ * else the reason.
144
+ */
145
+ export function wrongOrderFault(step) {
146
+ // #1061. This sentence states what happens in the order the instruction
147
+ // above it forbids, so its MOOD is the whole content. Unmarked ("Pinning
148
+ // ahead of the fast-forward pins the superseded text and certifies it for
149
+ // the rest of the run.") it parses as a declarative describing what the
150
+ // instruction achieves, and the reader — usually an agent — is then told by
151
+ // the runbook to do the one thing the instruction exists to prevent.
152
+ //
153
+ // Scoped to the SENTENCE, never the step slice: over the paragraph the
154
+ // marker below is satisfied by a modal a later edit adds to any other
155
+ // clause in it. Anchored on the COST and not on the opening word, because
156
+ // the marker can be a modal ("Pinning before … WOULD instead pin") or a
157
+ // conditional ("IF you pin before …") and only the second keeps "Pinning"
158
+ // as the subject — a start anchor on that word makes every conditional
159
+ // rewording an anchor red.
160
+ //
161
+ // The sentence is `sentences()`'s, never a first-period `[^.]*` window
162
+ // (#1940). That window ran straight past a `?` or `!` — and so did a
163
+ // splitter that missed a bold sentence's `.**` — so a neighbour ending in
164
+ // one lent the declarative its `if` or `would` and the mutant below passed.
165
+ // It also began after any period inside the sentence (`instruments.sh`,
166
+ // "e.g."), which stripped the marker from a valid conditional rewording.
167
+ // Newlines are whitespace to the splitter, so a rewrap moves neither end;
168
+ // the count is `anchorAt`'s exactly-once guarantee, held inline because this
169
+ // bound is a sentence rather than an anchor.
170
+ const hits = sentences(step).filter((s) => /superseded\s+text/.test(s));
171
+ if (hits.length !== 1) {
172
+ return `the sentence naming what pinning in the wrong order costs occurs ${hits.length} times — re-anchor this test, never widen it to the paragraph`;
173
+ }
174
+ const [wrongOrder] = hits;
175
+ // The marker, and the mutant this check exists to kill: restore the
176
+ // declarative above, which keeps every token pinned anywhere in this file
177
+ // and flips only the mood — RED here and nowhere else. Deleting the
178
+ // sentence reds on the count above instead, which measures vocabulary
179
+ // removal and proves less.
180
+ if (!/\bwould\b|\bif\b/i.test(wrongOrder)) {
181
+ return "the wrong-order sentence lost its counterfactual marker — it now reads as a statement of what pinning DOES, which is the failure it is describing";
182
+ }
183
+ // And it still says whose order is wrong. A marked sentence that no longer
184
+ // names the fast-forward it is contrasting with pins mood over nothing.
185
+ if (!phrase("fast-forward").test(wrongOrder)) {
186
+ return "the wrong-order sentence stopped naming the fast-forward it is the counterfactual of";
187
+ }
188
+ return null;
189
+ }
190
+
191
+ test("phase 0 step 0 states the WRONG pin order as a counterfactual, not as a fact", () => {
192
+ assert.equal(wrongOrderFault(PIN_STEP()), null);
193
+ });
194
+
195
+ // #1940. The other half, fed shapes the step does not hold today. The
196
+ // first-period window accepted the declarative whenever the sentence beside it
197
+ // ended in `?` or `!` and carried a marker of its own — the one mutant this
198
+ // rule exists to kill — and refused a conditional with a filename or an
199
+ // abbreviation ahead of its `if`.
200
+ test("a neighbouring sentence cannot lend the declarative its marker, and a period inside the sentence cannot strip it (#1940)", () => {
201
+ const declarative = "Pinning ahead of the fast-forward pins the superseded text and certifies it for the rest of the run.";
202
+ for (const neighbour of [
203
+ `What if one refuses? ${declarative}`,
204
+ `It would be too late afterwards! ${declarative}`,
205
+ `**If in doubt, pin after the fast-forward.** ${declarative}`,
206
+ "Pinning ahead of the fast-forward pins the superseded text! If in doubt, re-pin.",
207
+ ]) {
208
+ assert.match(wrongOrderFault(neighbour), /counterfactual marker/, neighbour);
209
+ }
210
+
211
+ assert.equal(wrongOrderFault("If you run instruments.sh --pin before that fast-forward, it pins the superseded text."), null);
212
+ assert.equal(wrongOrderFault("Pinning before that fast-forward (e.g. from a stale tree) would instead pin the superseded text."), null);
213
+ });
214
+
215
+ test("the mid-run tooling fix re-pins — the one legitimate writer to the set", () => {
216
+ const fix = TOOLING_FIX();
217
+ assert.match(fix, phrase("Re-pin first"));
218
+ assert.match(fix, phrase("instruments.sh"));
219
+ // The consequence, spelled out, is what stops the step being dropped as
220
+ // ceremony: skipping it makes the controller's own fix look like tampering.
221
+ assert.match(fix, phrase("the next gate refuses on your own fix"));
222
+ });
223
+
224
+ test("the path the prose tells the controller to run is a real executable", () => {
225
+ // The cheapest guard against the whole mechanism being prose about nothing:
226
+ // a renamed or deleted script leaves all the assertions above green.
227
+ //
228
+ // Absence is all this can decide, and the collection it replaces could not
229
+ // decide more: the capture group was a fixed literal, so the Set it filled
230
+ // held one element or none and `size === 1` was "the name appears somewhere"
231
+ // wearing a cross-site consistency check's clothes.
232
+ const SH = "scripts/instruments.sh";
233
+ assert.match(RUN_TEAM, phrase("~/.fleet/bin/fleet-run instruments.sh"), "the prose stopped naming the instrument check through the Resolver");
234
+ accessSync(join(REPO, SH), constants.X_OK);
235
+ });
@@ -0,0 +1,394 @@
1
+ #!/bin/sh
2
+ # Did the controller's instrument set change under it? (#436)
3
+ #
4
+ # The controller reads the world through scripts and runbooks that live in the
5
+ # MAIN checkout, and every member can write to that checkout — except through a
6
+ # `write`/`edit`/`ast_edit` that member-write-guard.mjs refuses (ADR 0020); a
7
+ # `bash` or `eval` write still lands, the backstop #2210 tracks. Worktree isolation
8
+ # and `./agent-test` port derivation protect members from each other; neither
9
+ # protects the tree the controller measures from. Measured: a member edited two
10
+ # files in the main checkout instead of its worktree while the CI monitor was
11
+ # polling one of them and a finisher was using it to decide a label. It caught
12
+ # itself. Nothing in the fleet would have.
13
+ #
14
+ # The failure is silent in the direction that matters. A modified instrument
15
+ # still returns a verdict; it may just not be the right one, and there is no
16
+ # error, no diff in any PR and nothing in the ledger to say so. So this is a
17
+ # DETECTION, not a prevention: pin the set's state at run start, re-check before
18
+ # each gate decision, and refuse rather than read a changed instrument. It
19
+ # compares the tree as it stands against the pin, so a change still present when
20
+ # it runs is caught and one made and reverted between two runs of it is not.
21
+ #
22
+ # Exit 0 unchanged, 1 changed, 2 the question could not be answered.
23
+ #
24
+ # THREE codes, but only ONE of them lets a gate proceed. Every other fleet probe
25
+ # with this contract (inflight.sh, verify-sha.sh, staleness.mjs) hands exit 2
26
+ # back to a caller that then decides; here 1 and 2 both refuse, because a guard
27
+ # that fails open on "could not look" protects nothing — the whole point is to
28
+ # fail closed. The split survives only so the refusal can say WHICH it was: a
29
+ # changed instrument is a finding about the tree, an unanswerable check is a
30
+ # finding about this script. Both stop the gate.
31
+ #
32
+ # WHAT IS IN THE SET: every tracked file under the plugin's own component
33
+ # directories — `plugin/commands/ plugin/scripts/ plugin/skills/
34
+ # plugin/agents/ plugin/workflows/` — contents read from the AUDITED
35
+ # repository: the tree the baseline names (its recorded root, else the working
36
+ # directory's checkout), or for a pin the tree named by `--audit` (see below).
37
+ # Not a written list of instrument names — the
38
+ # ticket named six and the class is larger (the supply scan, the liveness
39
+ # probe, the shared `arg.mjs`/`json.sh`/`net.sh` libraries that a single edit
40
+ # mutates every node instrument through, and the runbooks, which the
41
+ # controller also reads from this same writable tree and which phase 0
42
+ # already knows can be stale). A list rots on the next commit that adds a
43
+ # script; a directory does not.
44
+ #
45
+ # NOT THE WHOLE REPO, deliberately: since #1336 the plugin's payload is
46
+ # nested under `plugin/`, and the repo root also carries `docs/`, `.github/`
47
+ # and `.out-of-scope/`. `docs/metrics/` is APPENDED BY THE CONTROLLER
48
+ # MID-RUN, so a whole-repo set would fire the gate on the run's own
49
+ # bookkeeping every single time — a guard the controller learns to ignore,
50
+ # which is the failure the paragraph below names.
51
+ #
52
+ # TRACKED, deliberately: an untracked file appearing under those dirs — a
53
+ # `.DS_Store`, an editor swap file, a member's scratch output — changes no
54
+ # reading the controller takes, and refusing on it would fire the guard on
55
+ # ordinary runs. A guard the controller learns to ignore is worse than none.
56
+ #
57
+ # CONTENT, not `git status`: status answers off the stat cache, so a content
58
+ # change that lands on the same size and mtime does not reach it, and a bare
59
+ # `touch` does. This hashes bytes, so it accepts a touch and refuses a rewrite.
60
+ #
61
+ # MODES ARE NOT IN THE DIGEST, and that one is a GAP rather than a trade: a
62
+ # mode-only change to a tracked instrument is ACCEPTED. Measured — `chmod +x`
63
+ # on a tracked `100644` instrument leaves `git status` printing ` M` for it,
64
+ # and `git update-index --chmod=+x` moves the index entry to `100755` with the
65
+ # blob untouched; both exit 0 here. A mode change that costs the hash its READ
66
+ # is caught instead: `chmod 000` on a tracked instrument refuses at exit 2
67
+ # through `could not hash every tracked file` — as root that never fires,
68
+ # since root reads a mode-000 file regardless (instruments.test.mjs skips
69
+ # this case there for the same reason). So the exposure is the bits that
70
+ # still permit reading, the exec bit above all — and that bit is not how a
71
+ # fleet probe runs: fleet-run hands `.sh` to `sh` and `.mjs` to `node`, so a
72
+ # stripped `+x` is invisible through the Resolver, while invoking one by path
73
+ # instead is EACCES at exec (126), loud rather than a wrong verdict. Folding
74
+ # modes in — digesting `git ls-files -s` alongside the contents, or a per-file
75
+ # `[ -x "$f" ]` — is a behaviour change to the gate on a channel with no
76
+ # silently wrong reading to its name, and whether a mode-only edit is worth
77
+ # refusing on is a decision rather than a fix, so #1059 names the gap and
78
+ # leaves the behaviour alone. instruments.test.mjs pins the accepted pair,
79
+ # so closing the gap later goes red there rather than leaving this
80
+ # paragraph stale.
81
+ #
82
+ # REFS ARE DELIBERATELY NOT IN THE DIGEST, and the reason is not that they do
83
+ # not matter. The corroborating evidence on #436 is a stray `fix/42-slug` branch
84
+ # left in the main checkout by something running this repo's own fixtures — a
85
+ # ref write, which no hash of files can see. But `claim-ticket.sh` creates a
86
+ # branch per ticket and `reap.sh` deletes them, in the ref store every worktree
87
+ # shares, so a ref digest changes several times per pass as ORDINARY WORK. Per
88
+ # gate that is noise, and noise is the one failure this check cannot afford.
89
+ # Sweeping for unexpected refs is a drain-cadence question, not a gate one, and
90
+ # it is not what #436's acceptance criteria ask for.
91
+ #
92
+ # COST: two `git ls-files` (the state home's own set, which decides whether a
93
+ # recorded root may be followed at all, and the audited tree's set) and one
94
+ # pass of `shasum` over those files. No network, no `gh`, no fetch, no
95
+ # subprocess per file. It is meant to be run
96
+ # before every gate decision and it has to be cheap enough that nobody is
97
+ # tempted to skip it.
98
+ set -eu
99
+
100
+ # Directly below `set -eu`, not below a locale pin: this script has none and is
101
+ # deliberately off locale-pin-prose.test.mjs's PINNED list. The five siblings
102
+ # that DO carry a pin put this line under it instead, because that file's
103
+ # PROLOGUE regex admits only comments, blanks and `set -[eux]+` above the pin.
104
+ # Here the only constraint left is the real one: above the first git call.
105
+ #
106
+ # GIT_WORK_TREE is #1337's defect reached through the environment. The
107
+ # contract that ticket established is that the audited tree is the WORKING
108
+ # DIRECTORY's checkout — and `git rev-parse --show-toplevel` answers with the
109
+ # ambient work tree instead the moment one is set, `--repo` or not. Measured
110
+ # (#1020): standing in a checkout whose instruments have been TAMPERED, with
111
+ # `GIT_WORK_TREE` naming a clean twin that carries its own pinned baseline,
112
+ # this script exits 0 and prints the twin's digest. The gate passes. That is
113
+ # the same wrong-tree write `--repo ""` produced before #1350 refused it, one
114
+ # door further out, and a gate that certifies a tree nobody looked at is
115
+ # worse than no gate.
116
+ #
117
+ # GIT_DIR is unset alongside it and is measured INERT here: `ls-files` names
118
+ # paths and the digest is taken over the FILES ON DISK under `$root`, so
119
+ # pointing the object database elsewhere changes nothing — measured against a
120
+ # clean twin holding the exact pre-tamper content, the tampered digest came
121
+ # back unchanged and the gate still refused. It stays on the line because the
122
+ # pair is one hazard with one remedy, and because "inert today" is a
123
+ # measurement of the current call set: a digest taken from `git show` or
124
+ # `cat-file` rather than from disk would reintroduce the half nothing here
125
+ # can see. ambient-git-vars-prose.test.mjs pins the line itself, which is
126
+ # what keeps that half from being quietly dropped.
127
+ unset GIT_DIR GIT_WORK_TREE
128
+
129
+ NAME=instruments
130
+ # `printf '%s'`, never `echo` (#484): `echo` expands backslash escapes in its
131
+ # operand, and the messages below carry paths that git will happily hand us with
132
+ # a backslash in them.
133
+ die() { printf '%s: %s\n' "$NAME" "$1" >&2; exit 2; }
134
+
135
+ pin=false
136
+ repo=""
137
+ # The tree `--pin` certifies when it is NOT the state home's own checkout —
138
+ # the cross-workspace case: a fleet running in a repo that does not track
139
+ # `plugin/…` pins the marketplace/clone checkout that does, and the check
140
+ # later follows THAT pointer, recorded beside the digest. Pin-only: a check
141
+ # that let its caller repoint the tree would turn the baseline into a
142
+ # suggestion.
143
+ audit=""
144
+ while [ $# -gt 0 ]; do
145
+ case "$1" in
146
+ --pin) pin=true; shift ;;
147
+ --audit)
148
+ [ $# -ge 2 ] || die "usage: instruments.sh [--pin] [--repo <path>] [--audit <path>]"
149
+ audit=$2
150
+ [ -n "$audit" ] || die "--audit requires a non-empty path"
151
+ shift 2
152
+ ;;
153
+ --repo)
154
+ [ $# -ge 2 ] || die "usage: instruments.sh [--pin] [--repo <path>] [--audit <path>]"
155
+ repo=$2
156
+ # An empty value falls through the `[ -n "$repo" ]` branch below and
157
+ # silently re-derives from cwd — measured (#1350 review): `--repo ""`
158
+ # pinned the CALLER's cwd repo instead of refusing, exactly the
159
+ # wrong-tree-write class this ticket exists to close. Refuse here,
160
+ # before that check ever runs.
161
+ [ -n "$repo" ] || die "--repo requires a non-empty path"
162
+ shift 2
163
+ ;;
164
+ *) die "usage: instruments.sh [--pin] [--repo <path>] [--audit <path>]" ;;
165
+ esac
166
+ done
167
+ [ -n "$audit" ] && [ "$pin" != true ] \
168
+ && die "--audit is only accepted with --pin — a check audits the tree its baseline names, never one its caller names"
169
+
170
+ # Two trees, named apart:
171
+ #
172
+ # `root` — the STATE HOME — is the WORKING DIRECTORY's checkout, never the
173
+ # checkout this script happens to ship from. Under the install-only dev loop
174
+ # (ADR 0003) this file runs out of a plugin cache — on a real install, under
175
+ # `~/.omp/plugins/cache/...` — and the OLD own-location contract (`git -C
176
+ # "$(dirname "$0")" …`) resolved it to whatever git checkout happens to
177
+ # CONTAIN that cache path. Measured (#1337), pre-cutover: on a real box that
178
+ # was the operator's unrelated personal dotfiles checkout, and `--pin` run
179
+ # that way writes `.fleet/instruments.sha` into it. `--repo <path>` is the
180
+ # explicit override for the one legitimate case that needs a home other than
181
+ # cwd's: auditing a named worktree from elsewhere. Resolution happens before
182
+ # anything is read or written, so a cwd outside any checkout refuses here,
183
+ # not partway through. The baseline lives here, so every reader that knows
184
+ # only the run's workspace finds it without configuration.
185
+ #
186
+ # `target` — the AUDITED TREE — is the checkout whose `plugin/…` files are
187
+ # hashed. `--pin --audit <path>` names it for the cross-workspace case: a
188
+ # fleet running in a repo that does not track `plugin/…` has no instrument
189
+ # set to certify of its own (that empty set is exactly the refusal below),
190
+ # so the pin certifies the plugin checkout that DOES and records its toplevel
191
+ # beside the digest. A plain check then follows the RECORDED root, not cwd:
192
+ # the pointer travels inside the baseline, from the same write as the digest,
193
+ # so no later caller can repoint it. Absent a recorded root, target == root:
194
+ # the shape every existing baseline was made over, byte-for-byte.
195
+ if [ -n "$repo" ]; then
196
+ root=$(git -C "$repo" rev-parse --show-toplevel) \
197
+ || die "$repo is not inside a git checkout — cannot identify the instrument set"
198
+ else
199
+ root=$(git rev-parse --show-toplevel) \
200
+ || die "the working directory is not inside a git checkout — cannot identify the instrument set (pass --repo <path> to audit a tree other than cwd's)"
201
+ fi
202
+
203
+ # `root` is the STATE HOME (the baseline's checkout, the run's own tree);
204
+ # `target` is the AUDITED TREE the digest covers. They are the same tree in
205
+ # every ordinary run.
206
+ set='plugin/commands plugin/scripts plugin/skills plugin/agents plugin/workflows'
207
+ base="$root/.fleet/instruments.sha"
208
+
209
+ # Whether the state home tracks an instrument set OF ITS OWN decides if a
210
+ # second tree may be named at all — and it is what closes the door a recorded
211
+ # root would otherwise open: measured, a member who can write `.fleet/`
212
+ # (member-write-guard does not stop `bash`, #2210) can keep the honest
213
+ # run-start digest on line 1 and move `root=` to a pristine clone of the
214
+ # workspace whose bytes match it — the old script hashed the tampered tree and
215
+ # refused; a check that trusted the pointer would certify the clone and pass.
216
+ # The pointer therefore rides on the SAME trust the digest has: honoured only
217
+ # where the state home tracks no set of its own (the cross-workspace shape,
218
+ # where the pointer is the only tree the check CAN audit), and `--audit` is
219
+ # refused at the pin on a checkout that does track the set — so a forged pair
220
+ # can only ever aim at a tree whose own audit stays intact.
221
+ # shellcheck disable=SC2086 # $set is a deliberate list of pathspecs, not one path
222
+ home=$(git -C "$root" ls-files -- $set) \
223
+ || die "git ls-files failed under $root for: $set"
224
+
225
+ target=$root
226
+ if [ -n "$audit" ]; then
227
+ [ -z "$home" ] || die "--audit names a tree outside this checkout only when this checkout tracks no instrument set; it tracks one — drop --audit and the pin audits its own tree"
228
+ target=$(git -C "$audit" rev-parse --show-toplevel) \
229
+ || die "$audit is not inside a git checkout — cannot identify the instrument set to pin"
230
+ elif [ "$pin" = true ] && [ -z "$home" ]; then
231
+ # #1058's refusals mirrored on this path: a baseline that EXISTS but cannot
232
+ # be read names the tree this re-pin is supposed to keep certifying, and
233
+ # overwriting it blind would discard the pointer with no record that it was
234
+ # ever there.
235
+ basedir="$(dirname "$base")"
236
+ [ -d "$basedir" ] && [ ! -x "$basedir" ] \
237
+ && die "$basedir exists but is unreadable — fix its permissions; do NOT --pin over it, --pin overwrites rather than compares"
238
+ { [ -e "$base" ] || [ -L "$base" ]; } && [ ! -r "$base" ] \
239
+ && die "$base exists but is unreadable — fix its permissions; do NOT --pin over it, --pin overwrites rather than compares"
240
+ if [ -r "$base" ]; then
241
+ prior=$(sed -n '/^root=/{s/^root=//;p;q;}' "$base") || die "cannot read $base"
242
+ [ -n "$prior" ] && target=$prior
243
+ fi
244
+ fi
245
+
246
+ if [ "$pin" != true ]; then
247
+ # A check reads its baseline BEFORE it hashes anything, because the baseline
248
+ # names the tree to hash. A run pinned with `--audit` certified a checkout
249
+ # other than this workspace's; standing here, the only honest comparison is
250
+ # against THAT tree, and there is no cwd, flag, or config that says
251
+ # otherwise — `--repo` moves the state home, never the audited tree.
252
+ #
253
+ # No baseline is not "nothing has changed" — it is a run that never pinned,
254
+ # and the check has nothing to compare against. Refusing is the whole
255
+ # contract.
256
+ #
257
+ # EXISTS-but-unreadable is a different state than ABSENT, and it needs a
258
+ # different message: `--pin` never compares against the existing baseline,
259
+ # it just overwrites it with whatever the tree looks like now. Labeling this
260
+ # case "no baseline" and prescribing `--pin` would walk a controller from
261
+ # "the check could not look" to "certified clean" in one step, discarding
262
+ # evidence it never read — the exact anti-pattern run-team/SKILL.md forbids.
263
+ # (#1058)
264
+ basedir="$(dirname "$base")"
265
+
266
+ # A directory that exists but cannot be searched (missing +x) hides
267
+ # everything under it from stat(2) — `[ -e "$base" ]` below reads FALSE for
268
+ # every file underneath, so without this check the run falls through to the
269
+ # "no baseline" message one level up: the exact mislabel this refusal exists
270
+ # to prevent, just moved from the file to its containing directory. (#1058)
271
+ [ -d "$basedir" ] && [ ! -x "$basedir" ] \
272
+ && die "$basedir exists but is unreadable — fix its permissions; do NOT --pin over it, --pin overwrites rather than compares"
273
+
274
+ # `-L` catches a dangling symlink: the link entry is present but its target
275
+ # is gone, so `-e` (which dereferences) reads FALSE and the run would
276
+ # otherwise fall through to the same "no baseline" message for a baseline
277
+ # that is very much present, just broken. (#1058)
278
+ { [ -e "$base" ] || [ -L "$base" ]; } && [ ! -r "$base" ] \
279
+ && die "$base exists but is unreadable — fix its permissions; do NOT --pin over it, --pin overwrites rather than compares"
280
+ [ -r "$base" ] || die "no baseline at $base — run instruments.sh --pin once at run start"
281
+ want=$(sed -n '1p' "$base") || die "cannot read $base"
282
+ [ -n "$want" ] || die "$base is empty — re-pin, do not guess"
283
+
284
+ # The recorded root, if this baseline carries one. Absent — every baseline
285
+ # pinned before the audited tree could live apart from the state home, and
286
+ # every pin that CERTIFIED the state home itself — the audited tree IS the
287
+ # state home, the shape that digest was made over.
288
+ #
289
+ # Honoured only where a foreign pointer is admissible at all: this
290
+ # checkout's own recorded root is the shape every ordinary pin writes beside
291
+ # its own digest and means nothing — hashing `rec` here is hashing `root`.
292
+ # A FOREIGN pointer while the state home tracks a set of its own is the
293
+ # alarm: a member who could rewrite `root=`, keeping the honest line-1
294
+ # digest, would move the gate to a pristine clone whose bytes match it and
295
+ # watch the check exit 0 over a tree nobody read. No legitimate pin of this
296
+ # script can write that pair — the pin refuses `--audit` on a checkout that
297
+ # tracks the set — so it is a baseline that does not belong to this home (a
298
+ # moved or copied `.fleet/`, a clone that arrived carrying another
299
+ # workspace's baseline) or a forgery. Both refuse; re-pin here fixes the
300
+ # first and the second is the finding.
301
+ rec=$(sed -n '/^root=/{s/^root=//;p;q;}' "$base")
302
+ if [ -n "$home" ] && [ -n "$rec" ] && [ "$rec" != "$root" ]; then
303
+ die "baseline in $base certifies a foreign audited tree ($rec) while $root tracks its own instrument set — the baseline does not belong to this checkout, or was tampered with; refuse, do not re-read"
304
+ fi
305
+ if [ -n "$rec" ] && [ "$rec" != "$root" ]; then
306
+ # Re-verified, not trusted. What this catches: the tree moved (the path
307
+ # is now inside a DIFFERENT checkout, so `--show-toplevel` answers another
308
+ # name), or stopped being one (deleted, de-repo'd) — both refuse, because
309
+ # comparing a digest made over one tree against the bytes of nothing (or
310
+ # of a parent repo's tree) is not an answer. What it cannot catch is a
311
+ # REPLACEMENT: a checkout placed at the recorded path is audited by
312
+ # content, and content matching line 1 is exactly as indistinguishable
313
+ # from the pinned tree as a forged digest line is — no new power, and the
314
+ # foreign-pointer guard above already refuses this whole channel for any
315
+ # home that tracks a set of its own.
316
+ again=$(git -C "$rec" rev-parse --show-toplevel 2>/dev/null) \
317
+ || die "audited tree $rec (pinned in $base) is not a git checkout — the tree moved; refuse, do not re-read"
318
+ [ "$again" = "$rec" ] \
319
+ || die "audited tree moved: $rec now resolves to $again — refusing to certify a tree other than the one pinned"
320
+ target=$rec
321
+ fi
322
+ fi
323
+
324
+ # Hash the AUDITED tree — `$target`, which a baseline's recorded root may have
325
+ # repointed above.
326
+ #
327
+ # shellcheck disable=SC2086 # $set is a deliberate list of pathspecs, not one path
328
+ files=$(mktemp) || die "cannot create a temp file"
329
+ # INT/HUP/TERM as well as EXIT: a controller that kills a stalled gate check
330
+ # should not leave the temp file behind on a shared machine.
331
+ trap 'rm -f "$files"' EXIT
332
+ trap 'rm -f "$files"; exit 2' INT HUP TERM
333
+
334
+ # shellcheck disable=SC2086 # $set is a deliberate list of pathspecs, not one path
335
+ git -C "$target" ls-files -z -- $set > "$files" \
336
+ || die "git ls-files failed under $target for: $set"
337
+ # An empty listing is the shape a wrong root produces — a symlinked skills dir
338
+ # resolving to a different repository, most plausibly, or a workspace that
339
+ # simply does not vendor the plugin. Certifying it would hand back "unchanged"
340
+ # for a set that was never read.
341
+ [ -s "$files" ] || die "no tracked file under $target for: $set — refusing to certify an empty instrument set"
342
+
343
+ # Two steps, each with its own status check, because a pipeline reports only its
344
+ # LAST command: with `xargs … | shasum` as one pipeline, a `shasum` that cannot
345
+ # run at all leaves the second one hashing empty input and exiting 0, and the
346
+ # empty-input digest then compares unequal and reads as CHANGED. That is exit 1
347
+ # — a verdict about the tree — off a failure to look. reap.sh shipped this exact
348
+ # bug against `git cherry` (#264) and it deleted branches.
349
+ #
350
+ # `xargs` exits 123 when `shasum` failed on any file, which is how a tracked
351
+ # file deleted from the worktree arrives: as exit 2 naming it, not as a digest
352
+ # quietly missing a line. Both refuse; only one of them is honest about why.
353
+ per_file=$(cd "$target" && xargs -0 shasum -a 256 < "$files") \
354
+ || die "could not hash every tracked file under $set — see the errors above"
355
+ digest=$(printf '%s\n' "$per_file" | shasum -a 256 | cut -d' ' -f1) \
356
+ || die "could not digest the instrument set"
357
+ [ -n "$digest" ] || die "empty digest for $target ($set)"
358
+
359
+ if [ "$pin" = true ]; then
360
+ mkdir -p "$root/.fleet" || die "cannot create $root/.fleet"
361
+ # Two lines, order fixed: the digest first, the audited tree's toplevel
362
+ # second. A reader that only knows the old one-line shape — merge-gate.mjs's
363
+ # `readInstruments`, which takes the FIRST stdout line as the digest — keeps
364
+ # working, and a check from this script reads both. The root rides in the
365
+ # same write as the digest because it is not a suggestion: a pointer an
366
+ # attacker with a writable `.fleet/` could repoint at will would move the
367
+ # gate to a tree they control, so the check trusts nothing else, re-verifies
368
+ # the tree at check time, and refuses if it moved.
369
+ {
370
+ printf '%s\n' "$digest"
371
+ printf 'root=%s\n' "$target"
372
+ } > "$base" || die "cannot write $base"
373
+ printf '%s\n' "$digest"
374
+ printf '%s: pinned %s over %s\n' "$NAME" "$digest" "$target ($set)" >&2
375
+ exit 0
376
+ fi
377
+
378
+ printf '%s\n' "$digest"
379
+ if [ "$digest" = "$want" ]; then
380
+ exit 0
381
+ fi
382
+
383
+ # Cold path only, so it costs the ordinary run nothing. The controller has to
384
+ # report WHAT changed, and neither digest says. `git status` names the
385
+ # uncommitted half, which is the shape the near-miss on #436 actually took; a
386
+ # checked-out branch that moved shows as nothing here and the HEAD line is what
387
+ # names it. Both are read from the AUDITED tree, which is the one the verdict
388
+ # is about — not the state home the baseline was found in.
389
+ printf '%s: instrument set CHANGED under this run — expected %s\n' "$NAME" "$want" >&2
390
+ printf '%s: refuse the gate and report. Do NOT re-read the instrument.\n' "$NAME" >&2
391
+ printf '%s: HEAD %s\n' "$NAME" "$(git -C "$target" rev-parse HEAD 2>/dev/null || printf '?')" >&2
392
+ # shellcheck disable=SC2086 # $set is a deliberate list of pathspecs, not one path
393
+ git -C "$target" status --porcelain -- $set >&2 || true
394
+ exit 1