paperlint 9.0.1 → 10.1.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 (196) hide show
  1. package/CONTRIBUTING.md +16 -4
  2. package/README.md +68 -128
  3. package/dist/build.d.ts +1 -1
  4. package/dist/build.js +1 -1
  5. package/dist/cli.d.ts +5 -1
  6. package/dist/cli.d.ts.map +1 -1
  7. package/dist/cli.js +52 -6
  8. package/dist/cli.js.map +1 -1
  9. package/dist/domain/layout-tree.d.ts +19 -0
  10. package/dist/domain/layout-tree.d.ts.map +1 -0
  11. package/dist/domain/layout-tree.js +32 -0
  12. package/dist/domain/layout-tree.js.map +1 -0
  13. package/dist/domain/lookup-cache.d.ts +2 -2
  14. package/dist/domain/lookup-cache.js +2 -2
  15. package/dist/domain/paper-layout.d.ts +81 -0
  16. package/dist/domain/paper-layout.d.ts.map +1 -0
  17. package/dist/domain/paper-layout.js +259 -0
  18. package/dist/domain/paper-layout.js.map +1 -0
  19. package/dist/domain/repro-layout.d.ts +80 -0
  20. package/dist/domain/repro-layout.d.ts.map +1 -0
  21. package/dist/domain/repro-layout.js +247 -0
  22. package/dist/domain/repro-layout.js.map +1 -0
  23. package/dist/domain/scaffold-layout.d.ts +28 -0
  24. package/dist/domain/scaffold-layout.d.ts.map +1 -0
  25. package/dist/domain/scaffold-layout.js +81 -0
  26. package/dist/domain/scaffold-layout.js.map +1 -0
  27. package/dist/eslint-rules/js-needs-reason.d.ts +55 -0
  28. package/dist/eslint-rules/js-needs-reason.d.ts.map +1 -0
  29. package/dist/eslint-rules/js-needs-reason.js +35 -0
  30. package/dist/eslint-rules/js-needs-reason.js.map +1 -0
  31. package/dist/eslint-rules/prereg-coverage.d.ts +98 -0
  32. package/dist/eslint-rules/prereg-coverage.d.ts.map +1 -0
  33. package/dist/eslint-rules/prereg-coverage.js +274 -0
  34. package/dist/eslint-rules/prereg-coverage.js.map +1 -0
  35. package/dist/folder-layout-hook.d.ts +21 -0
  36. package/dist/folder-layout-hook.d.ts.map +1 -0
  37. package/dist/folder-layout-hook.js +117 -0
  38. package/dist/folder-layout-hook.js.map +1 -0
  39. package/dist/folder-layout-rule.d.ts +22 -0
  40. package/dist/folder-layout-rule.d.ts.map +1 -0
  41. package/dist/folder-layout-rule.js +107 -0
  42. package/dist/folder-layout-rule.js.map +1 -0
  43. package/dist/init.js +1 -1
  44. package/dist/init.js.map +1 -1
  45. package/dist/new-paper.d.ts +4 -1
  46. package/dist/new-paper.d.ts.map +1 -1
  47. package/dist/new-paper.js +40 -6
  48. package/dist/new-paper.js.map +1 -1
  49. package/dist/package-dirs.d.ts +6 -0
  50. package/dist/package-dirs.d.ts.map +1 -1
  51. package/dist/package-dirs.js +6 -0
  52. package/dist/package-dirs.js.map +1 -1
  53. package/dist/references.d.ts +1 -1
  54. package/dist/references.d.ts.map +1 -1
  55. package/dist/references.js +2 -2
  56. package/dist/references.js.map +1 -1
  57. package/dist/repro-layout-rule.d.ts +16 -0
  58. package/dist/repro-layout-rule.d.ts.map +1 -0
  59. package/dist/repro-layout-rule.js +81 -0
  60. package/dist/repro-layout-rule.js.map +1 -0
  61. package/dist/skills/label-agent-runs/scripts/labels-commands.d.ts +13 -0
  62. package/dist/skills/label-agent-runs/scripts/labels.d.ts +2 -0
  63. package/dist/skills/run-agent-grid/scripts/grid-guard-commands.d.ts +20 -0
  64. package/dist/skills/run-agent-grid/scripts/grid-guard.d.ts +2 -0
  65. package/docs/ci.md +60 -0
  66. package/docs/configuration.md +2 -0
  67. package/docs/e2e.md +2 -2
  68. package/docs/install.md +20 -16
  69. package/docs/layout.md +154 -0
  70. package/docs/optional-rules.md +5 -4
  71. package/docs/references.md +5 -2
  72. package/docs/rules/paper/allowed-files-only.md +192 -0
  73. package/docs/rules/repro/allowed-files-only.md +128 -0
  74. package/docs/rules/study/declare-sample.md +146 -0
  75. package/docs/rules.md +53 -50
  76. package/docs/skills.md +8 -3
  77. package/docs/testing.md +13 -0
  78. package/docs/venues.md +94 -0
  79. package/eslint-rules/js-needs-reason.test.ts +141 -0
  80. package/eslint-rules/js-needs-reason.ts +77 -0
  81. package/eslint-rules/prereg-coverage.test.ts +448 -0
  82. package/eslint-rules/prereg-coverage.ts +419 -0
  83. package/eslint.config.mjs +22 -2
  84. package/lib/skill-trigger-cases.harness.mjs +51 -5
  85. package/lib/skill-trigger-cases.mjs +53 -15
  86. package/lib/skill-trigger-cases.test.ts +211 -0
  87. package/package.json +8 -4
  88. package/plugin/hooks/hooks.json +9 -0
  89. package/scripts/coverage-config.test.ts +5 -3
  90. package/skills/analyze-sibling-paper/SKILL.md +2 -2
  91. package/skills/analyze-sibling-paper/SKILL.md.spec.ts +1 -1
  92. package/skills/build-benchmark/SKILL.md +17 -1
  93. package/skills/build-benchmark/SKILL.md.spec.ts +16 -0
  94. package/skills/build-label-page/SKILL.md +120 -0
  95. package/skills/build-label-page/SKILL.md.spec.ts +131 -0
  96. package/skills/build-label-page/build-label-page.eval.mjs +15 -0
  97. package/skills/build-label-page/build-label-page.test.ts +959 -0
  98. package/skills/build-label-page/references/checklist.md +148 -0
  99. package/skills/build-label-page/references/example-generator.py +803 -0
  100. package/skills/find-venue/SKILL.md +5 -3
  101. package/skills/find-venue/SKILL.md.spec.ts +4 -2
  102. package/skills/grade-paper-writing/SKILL.md +7 -7
  103. package/skills/grade-paper-writing/SKILL.md.spec.ts +6 -6
  104. package/skills/label-agent-runs/SKILL.md +103 -0
  105. package/skills/label-agent-runs/SKILL.md.spec.ts +106 -0
  106. package/skills/label-agent-runs/label-agent-runs.eval.ts +55 -0
  107. package/skills/label-agent-runs/label-agent-runs.harness.ts +123 -0
  108. package/skills/label-agent-runs/references/formats.md +64 -0
  109. package/skills/label-agent-runs/scripts/labels-commands.js +13 -0
  110. package/skills/label-agent-runs/scripts/labels-commands.ts +13 -0
  111. package/skills/label-agent-runs/scripts/labels.js +396 -0
  112. package/skills/label-agent-runs/scripts/labels.test.ts +538 -0
  113. package/skills/label-agent-runs/scripts/labels.ts +501 -0
  114. package/skills/map-prior-work/SKILL.md +2 -2
  115. package/skills/map-prior-work/SKILL.md.spec.ts +1 -1
  116. package/skills/paper-pipeline/SKILL.md +15 -6
  117. package/skills/paper-pipeline/SKILL.md.spec.ts +14 -5
  118. package/skills/paper-pipeline/grade-paper-writing-ablation.eval.mjs +19 -9
  119. package/skills/paper-pipeline/references/acceptance-gate.md +19 -19
  120. package/skills/paper-pipeline/references/artifact-checklist.md +5 -0
  121. package/skills/paper-pipeline/references/pipeline-status-template.md +30 -1
  122. package/skills/paper-pipeline/repro/2026-08-07-fork-check.log +1 -1
  123. package/skills/paper-pipeline/repro/2026-08-07-fork-check2.log +1 -1
  124. package/skills/paper-pipeline/repro/2026-08-07-language-eval-pilot.log +1 -1
  125. package/skills/paper-pipeline/repro/2026-08-07-language-eval-raw.log +1 -1
  126. package/skills/paper-pipeline/repro/2026-08-08-framing-vs-vocabulary-oracle.log +48 -48
  127. package/skills/paper-pipeline/repro/2026-08-08-grade-paper-writing-ablation-A6-oracle.log +8 -8
  128. package/skills/paper-pipeline/repro/2026-08-08-grade-paper-writing-ablation-oracle.log +48 -48
  129. package/skills/paper-pipeline/repro/2026-08-08-parent-replication-gpw.log +2 -2
  130. package/skills/paper-pipeline/repro/2026-08-08-parent-replication.mjs +3 -3
  131. package/skills/paper-pipeline/repro/2026-10-13-grade-paper-writing-ablation-preflight-after.log +81 -0
  132. package/skills/paper-pipeline/repro/2026-10-13-grade-paper-writing-ablation-preflight-before.log +81 -0
  133. package/skills/paper-pipeline/repro/2026-10-13-grade-paper-writing-ablation-setupdiff.log +59 -0
  134. package/skills/paper-pipeline/repro/2026-10-13-grade-paper-writing-trigger.jsonl +1 -0
  135. package/skills/paper-pipeline/repro/2026-10-13-grade-paper-writing-trigger.log +22 -0
  136. package/skills/paper-pipeline/repro/README.md +4 -0
  137. package/skills/paper-pipeline/scripts/extract-ref-facts.harness.mjs +2 -2
  138. package/skills/paper-pipeline/scripts/extract-ref-facts.mjs +2 -2
  139. package/skills/paper-pipeline/scripts/extract-ref-facts.test.mjs +4 -2
  140. package/skills/paper-pipeline/scripts/generated-code.harness.mjs +7 -2
  141. package/skills/paper-pipeline/scripts/generated-code.mjs +8 -4
  142. package/skills/paper-pipeline/scripts/generated-code.test.ts +15 -1
  143. package/skills/paper-status/SKILL.md +2 -2
  144. package/skills/paper-status/SKILL.md.spec.ts +1 -1
  145. package/skills/run-agent-grid/SKILL.md +181 -0
  146. package/skills/run-agent-grid/SKILL.md.spec.ts +184 -0
  147. package/skills/run-agent-grid/references/failure-catalog.md +36 -0
  148. package/skills/run-agent-grid/references/registry-and-ledger.md +142 -0
  149. package/skills/run-agent-grid/run-agent-grid.eval.ts +59 -0
  150. package/skills/run-agent-grid/run-agent-grid.harness.ts +115 -0
  151. package/skills/run-agent-grid/scripts/grid-guard-commands.js +18 -0
  152. package/skills/run-agent-grid/scripts/grid-guard-commands.ts +21 -0
  153. package/skills/run-agent-grid/scripts/grid-guard.js +700 -0
  154. package/skills/run-agent-grid/scripts/grid-guard.test.ts +1090 -0
  155. package/skills/run-agent-grid/scripts/grid-guard.ts +869 -0
  156. package/skills/study-accepted-papers/SKILL.md +163 -161
  157. package/skills/study-accepted-papers/SKILL.md.spec.ts +167 -165
  158. package/skills/study-accepted-papers/references/base-rates.md +69 -0
  159. package/skills/study-accepted-papers/references/mechanisms.md +181 -0
  160. package/skills/verify-citations/SKILL.md +2 -2
  161. package/skills/verify-citations/SKILL.md.spec.ts +1 -1
  162. package/src/build.ts +1 -1
  163. package/src/cli.harness.mjs +42 -0
  164. package/src/cli.test.ts +90 -6
  165. package/src/cli.ts +78 -5
  166. package/src/domain/layout-tree.test.ts +32 -0
  167. package/src/domain/layout-tree.ts +47 -0
  168. package/src/domain/lookup-cache.ts +2 -2
  169. package/src/domain/paper-layout.test.ts +264 -0
  170. package/src/domain/paper-layout.ts +336 -0
  171. package/src/domain/repro-layout.test.ts +222 -0
  172. package/src/domain/repro-layout.ts +311 -0
  173. package/src/domain/scaffold-layout.ts +104 -0
  174. package/src/folder-layout-hook.test.ts +214 -0
  175. package/src/folder-layout-hook.ts +141 -0
  176. package/src/folder-layout-rule.test.ts +235 -0
  177. package/src/folder-layout-rule.ts +151 -0
  178. package/src/hooks-settings.harness.ts +9 -8
  179. package/src/init.ts +1 -1
  180. package/src/layout-docs.test.ts +52 -0
  181. package/src/new-paper.harness.mjs +23 -1
  182. package/src/new-paper.test.ts +299 -6
  183. package/src/new-paper.ts +51 -5
  184. package/src/package-dirs.ts +8 -0
  185. package/src/paper-files.test.ts +9 -6
  186. package/src/references.test.ts +5 -5
  187. package/src/references.ts +2 -2
  188. package/src/repro-layout-rule.test.ts +114 -0
  189. package/src/repro-layout-rule.ts +121 -0
  190. package/src/rule-cases.test.ts +98 -0
  191. package/templates/paper/PIPELINE-STATUS.md +41 -7
  192. package/tsconfig.base.json +22 -0
  193. package/tsconfig.json +6 -24
  194. package/tsconfig.pkg.json +3 -1
  195. package/tsconfig.skills.json +14 -0
  196. package/tsconfig.src.json +12 -0
@@ -0,0 +1,142 @@
1
+ # The registry, the attempt ledger, and a driver that obeys the guard
2
+
3
+ `grid-guard` is `scripts/grid-guard.js` in this skill; every command below is run with
4
+ `node ${CLAUDE_SKILL_DIR}/scripts/grid-guard.js`. Exit codes: 0 allowed or clean, 1 refused or a
5
+ finding, 2 usage, 3 (`gate`) already counted.
6
+
7
+ ## The registry — `grid.json`, committed
8
+
9
+ ```json
10
+ {
11
+ "author": "the-author-handle",
12
+ "draw": {
13
+ "population": "every unit of the measured kind, and where the list came from",
14
+ "seed": 7349,
15
+ "script": "draw.py"
16
+ },
17
+ "arms": ["control", "treatment"],
18
+ "seeds": [1, 2, 3],
19
+ "budget": {
20
+ "cap": 300,
21
+ "currency": "USD",
22
+ "stopRule": "stop at the cap; report what ran"
23
+ },
24
+ "models": [
25
+ {
26
+ "id": "model-a",
27
+ "smoke": {
28
+ "timeoutSec": 2400,
29
+ "costPerRun": 1.8,
30
+ "readBy": "who read the smoke runs",
31
+ "at": "ISO time"
32
+ }
33
+ }
34
+ ],
35
+ "units": [
36
+ {
37
+ "id": "unit-017",
38
+ "role": "counted",
39
+ "stratum": "s2",
40
+ "requirement": "the author's requirement on this unit, verbatim",
41
+ "approval": {
42
+ "by": "the-author-handle",
43
+ "at": "ISO time",
44
+ "channel": "where the author said it"
45
+ },
46
+ "proof": {
47
+ "toolVisible": true,
48
+ "firesOnPinned": true,
49
+ "acceptsReference": true,
50
+ "at": "ISO time"
51
+ }
52
+ },
53
+ { "id": "unit-smoke", "role": "smoke" },
54
+ { "id": "unit-031", "role": "excluded", "reason": "why, in one line" }
55
+ ]
56
+ }
57
+ ```
58
+
59
+ What `gate` requires, field by field:
60
+
61
+ | field | for | refused when |
62
+ | -------------------------------------------- | ------------ | ------------------------------------------------------------------ |
63
+ | the file itself | every run | not in git, not committed, or the working copy differs from `HEAD` |
64
+ | `units[].id`, `arms`, `models[].id`, `seeds` | every run | the cell's unit, arm, model or seed is not declared |
65
+ | `units[].role` | every run | anything but `counted` or `smoke` |
66
+ | `units[].reason` | every run | an `excluded` unit has none |
67
+ | `budget.cap` | every run | missing, or ledger spend + next cost would pass it |
68
+ | `units[].approval` | counted runs | `by` ≠ `author`, or `at` / `channel` empty |
69
+ | `units[].proof` | counted runs | any of the three facts is not `true` |
70
+ | `draw.seed` | counted runs | missing |
71
+ | `models[].smoke` | counted runs | `timeoutSec` or `costPerRun` is not a number |
72
+
73
+ On success `gate` prints one JSON line: `{"allowed":true,"cell":{…},"attempt":"…","counted":…,"timeoutSec":…,"spent":…}`,
74
+ and has already appended a `reserved` record for that attempt to the ledger (read, check and append
75
+ under `<ledger>.lock`, so concurrent drivers cannot both take one cell or both fit under the cap).
76
+ The driver takes the run's timeout from `timeoutSec`.
77
+
78
+ ## The attempt ledger — `attempts.jsonl`, append-only
79
+
80
+ One JSON object per line. `gate` writes the first line of an attempt (a reservation); the driver
81
+ writes a line when the attempt **starts** and another when it **ends**, all with the same `attempt`
82
+ id; later lines add to earlier ones. A crashed attempt therefore stays on record with a start and
83
+ no end, and its reservation lapses at `expires`.
84
+
85
+ ```json
86
+ {"attempt":"a-0042","unit":"unit-017","arm":"control","model":"model-a","seed":"1","status":"reserved","cost":1.8,"start":"2026-01-01T09:59:58Z","expires":"2026-01-01T15:59:58Z"}
87
+ {"attempt":"a-0042","agent":"cli-a","model":"model-a","unit":"unit-017","arm":"control","seed":1,"root":"/scratch/w1","start":"2026-01-01T10:00:00Z"}
88
+ {"attempt":"a-0042","end":"2026-01-01T10:31:00Z","status":"complete","cost":1.62}
89
+ ```
90
+
91
+ | field | meaning |
92
+ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
93
+ | `status` | `reserved` — held by `gate` until the end record or `expires`; `complete` — counted, whatever the outcome; `harness-error` — kept on record, not counted, re-run |
94
+ | `root` | the working-copy root the attempt used: what `overlap` compares |
95
+ | `agent` | the agent CLI that ran; with `model` and `<unit>/<arm>/<seed>` it names the cell a label refers to |
96
+ | `cost` | what the attempt cost, counted toward the cap even for a harness error |
97
+
98
+ The outcome itself lives in the run folder (`runs/<attempt>/`), whose completion record
99
+ (`done.json` by default) is written **last**.
100
+
101
+ ## A driver loop
102
+
103
+ ```bash
104
+ #!/usr/bin/env bash
105
+ set -uo pipefail
106
+ G="node ${CLAUDE_SKILL_DIR}/scripts/grid-guard.js"
107
+ ROOT=/scratch/w1 # this driver's own working-copy root
108
+ $G lock "$ROOT" --owner "driver-w1" --pid $$ || exit 1
109
+ trap '$G release "$ROOT" --owner driver-w1' EXIT
110
+
111
+ while read -r unit arm model seed; do
112
+ id="a-$(date +%s%N)-$$-$unit-$arm-$model-$seed"
113
+ verdict=$($G gate --registry grid.json --ledger attempts.jsonl \
114
+ --unit "$unit" --arm "$arm" --model "$model" --seed "$seed" --attempt "$id")
115
+ rc=$?
116
+ [ $rc -eq 3 ] && continue # counted, or reserved by another driver: skip it
117
+ [ $rc -ne 0 ] && exit $rc # refused: stop the grid, read why
118
+ timeout_sec=$(node -e 'console.log(JSON.parse(process.argv[1]).timeoutSec ?? 3600)' "$verdict")
119
+ # 1. start record 2. fresh working copy of the unit in $ROOT 3. the agent CLI under
120
+ # `timeout $timeout_sec` 4. the scorer 5. runs/$id/done.json LAST 6. end record
121
+ # (status complete or harness-error, real cost) — it releases the reservation
122
+ done < cells.txt
123
+ ```
124
+
125
+ Start it detached so the agent session's limits cannot kill it, and let something else wake the
126
+ session:
127
+
128
+ ```bash
129
+ setsid nohup ./driver.sh > driver.log 2>&1 < /dev/null &
130
+ ```
131
+
132
+ ## The pre-commit hook
133
+
134
+ `.git/hooks/pre-commit` (or the hook manager the repository already uses):
135
+
136
+ ```bash
137
+ #!/usr/bin/env bash
138
+ exec node "<path to this skill>/scripts/grid-guard.js" precommit --runs runs --done done.json
139
+ ```
140
+
141
+ A hook in `.git/hooks/` is not versioned; record in the study's README that it is installed, and
142
+ run the same command in CI if the repository has CI.
@@ -0,0 +1,59 @@
1
+ /**
2
+ * run-agent-grid — the PAID tier: does this skill's description fire on its own requests, and
3
+ * stay quiet on a sibling's?
4
+ *
5
+ * Declared here, whole: the prompts it must fire on, the prompts it must not, and the
6
+ * measurement — no shared table, no kit. `vigiles eval` discovers this file by its name and runs
7
+ * it; nothing runs at import.
8
+ *
9
+ * The should-not-fire prompts are the neighbours' territory, written inline: `build-benchmark`
10
+ * (designing the study), `build-label-page` (a page a person labels on), `label-agent-runs`
11
+ * (labelling the outcomes) and `draft-paper`. They are inline rather than imported from
12
+ * `label-agent-runs.eval.ts` because that file imports this one's prompts, and two evals that
13
+ * import each other's constants deadlock at module load.
14
+ *
15
+ * The skills it competes with are every skill this package ships (the `skills/` directory this
16
+ * file sits in), the same set in a checkout and in `node_modules`.
17
+ *
18
+ * ⚠️ NEVER RUN. Written with the skill; its rates are UNKNOWN, not assumed good.
19
+ *
20
+ * Costs money; not CI.
21
+ * npx vigiles eval skills/run-agent-grid/run-agent-grid.eval.ts
22
+ */
23
+ import { dirname } from "node:path";
24
+ import { fileURLToPath } from "node:url";
25
+ import { defineEval, skillResolved } from "vigiles";
26
+
27
+ /** The namespace vigiles installs a loose skills directory under. */
28
+ const LOOSE_NS = "vigiles-loose-skills";
29
+
30
+ /** Requests this skill owns. Exported: `label-agent-runs.eval.ts` uses them as its should-not-fire set. */
31
+ export const TRIGGER_PROMPTS: readonly string[] = [
32
+ "запускаю платную сетку прогонов агента — что проверить до первого запуска",
33
+ "the grid driver died halfway, how do I resume without re-running the counted cells",
34
+ "два драйвера писали в одну рабочую папку, какие прогоны теперь испорчены",
35
+ "gate every agent run on the approved sample and a hard budget cap before we spend money",
36
+ ];
37
+
38
+ export default defineEval({
39
+ measureTriggerRate: {
40
+ name: "run-agent-grid-trigger",
41
+ skillsDir: dirname(dirname(fileURLToPath(import.meta.url))),
42
+ prompts: TRIGGER_PROMPTS,
43
+ irrelevantPrompts: [
44
+ "надо спроектировать сам замер, а не описывать его — как считать честно",
45
+ "build a gold-labelling page for these 40 items so I can answer on my phone",
46
+ "which of the finished runs does a person have to read, and which can the classifier label",
47
+ "числа есть, пора писать текст",
48
+ ],
49
+ fired: (trace) => skillResolved(trace, `${LOOSE_NS}:run-agent-grid`),
50
+ // Four named phrasings per side, deliberately, as for every skill of this package.
51
+ minPrompts: 4,
52
+ // A grid in progress, so "the driver died" and "the registry" have something to refer to.
53
+ fixture: {
54
+ "grid.json": '{ "arms": ["control", "treatment"], "seeds": [1, 2] }\n',
55
+ "attempts.jsonl":
56
+ '{"attempt":"a1","unit":"u1","arm":"control","seed":1,"start":"2026-01-01T00:00:00Z"}\n',
57
+ },
58
+ },
59
+ });
@@ -0,0 +1,115 @@
1
+ /**
2
+ * run-agent-grid — the agent-facing tier. Does an agent that loads this skill get a guard it can
3
+ * actually call, at the path the skill names, with the result the skill promises?
4
+ *
5
+ * Runs the REAL `claude` CLI against a SCRIPTED MOCK MODEL (`runHarnessTest`): $0, no API key.
6
+ * The script: activate the skill, then — through the Bash tool, as an agent following §5 would —
7
+ * take the lock on a working-copy root, have a second driver refused while the first holds it,
8
+ * and release it. The commands use the skill directory as `${CLAUDE_SKILL_DIR}` resolves for a
9
+ * consumer: the skill's link under `.claude/skills/`, and the COMPILED `grid-guard.js` there,
10
+ * which is what runs from `node_modules` (`npm run build` makes it; `npm run check` builds first).
11
+ *
12
+ * Also, without the CLI: the shared per-skill checks (`checkSkill`). Whether the skill names only
13
+ * subcommands the guard has is not tested here: the spec interpolates them from
14
+ * `scripts/grid-guard-commands.ts`, so a wrong one fails `tsc`.
15
+ *
16
+ * What it does NOT prove: that a real model follows the order of the gates. That is a
17
+ * probabilistic question for `run-agent-grid.eval.ts` and a real grid.
18
+ */
19
+ import { spawnSync } from "node:child_process";
20
+ import { join } from "node:path";
21
+ import { runHarnessTest, skip, type ToolCall } from "vigiles";
22
+ import { createChecker } from "../../lib/check.ts";
23
+ import { checkSkill } from "../../lib/skill-checks.mjs";
24
+ import { observeAgentCli } from "#lib/agent-cli-version";
25
+ import { claudeDir } from "#src/package-dirs";
26
+ import { COMMANDS } from "./scripts/grid-guard-commands.ts";
27
+
28
+ const check = createChecker();
29
+
30
+ await checkSkill("run-agent-grid");
31
+
32
+ // ── Through the real CLI: the lock, as the skill tells an agent to take it ────────────────
33
+ const SKILL_LINK = join(claudeDir(), "skills", "run-agent-grid");
34
+ const cli = observeAgentCli({ spawnSync });
35
+ if (!cli.present) skip(`run-agent-grid effects: ${cli.note}`);
36
+
37
+ const g = `node ${SKILL_LINK}/scripts/grid-guard.js`;
38
+ // The holder's pid is this harness: alive for the whole run, so the second driver must be refused.
39
+ // `--attached`: a Bash call of an agent session is not a detached driver, and this run is short —
40
+ // the detachment refusal itself is pinned in `scripts/grid-guard.test.ts`.
41
+ const LOCK = `${g} ${COMMANDS.lock} wc --owner driver-a --pid ${String(process.pid)} --attached`;
42
+ const r = await runHarnessTest({
43
+ pluginDir: claudeDir(),
44
+ // bubblewrap is absent here; the code loaded is this repository's own `.claude`.
45
+ sandbox: false,
46
+ transcript: true,
47
+ timeoutMs: 180_000,
48
+ prompt:
49
+ "we are about to start the paid grid — take the lock on the working copy",
50
+ allowedTools: ["Skill", "Bash"],
51
+ files: { "README.md": "grid working directory\n" },
52
+ model: [
53
+ { tool: "Skill", input: { skill: "run-agent-grid" } },
54
+ { tool: "Bash", input: { command: LOCK } },
55
+ {
56
+ tool: "Bash",
57
+ input: {
58
+ command: `${g} ${COMMANDS.lock} wc --owner driver-b --attached`,
59
+ },
60
+ },
61
+ {
62
+ tool: "Bash",
63
+ input: { command: `${g} ${COMMANDS.release} wc --owner driver-a` },
64
+ },
65
+ { text: "done" },
66
+ ],
67
+ });
68
+
69
+ /** Did this call run, with this error flag, and print what `re` matches? */
70
+ const ran = (c: ToolCall | undefined, isError: boolean, re: RegExp): boolean =>
71
+ c !== undefined && c.isError === isError && re.test(c.resultText);
72
+ const shown = (c: ToolCall | undefined): string =>
73
+ c ? c.resultText.slice(0, 300) : "never called";
74
+
75
+ try {
76
+ const activation = r.toolCalls.find((c) => c.name === "Skill");
77
+ check(
78
+ "the skill activated",
79
+ activation !== undefined && !activation.isError,
80
+ shown(activation),
81
+ );
82
+ const reached = r.modelRequests
83
+ .map((q) => [q.system, ...q.messages.map((m) => m.text)].join("\n"))
84
+ .join("\n");
85
+ check(
86
+ "the skill body reached the model",
87
+ reached.includes(
88
+ "The order — each gate is passed before the next phase starts",
89
+ ),
90
+ `${String(r.modelRequests.length)} requests`,
91
+ );
92
+ const bash = r.toolCalls.filter((c) => c.name === "Bash");
93
+ const [take, second, give] = bash;
94
+ check("three Bash calls ran", bash.length === 3, String(bash.length));
95
+ check(
96
+ "the first driver takes the lock",
97
+ ran(take, false, /locked \S+wc\.lock for driver-a/),
98
+ shown(take),
99
+ );
100
+ check(
101
+ "a second driver is refused while the first lives",
102
+ ran(second, true, /wc\.lock is held by driver-a/),
103
+ shown(second),
104
+ );
105
+ check(
106
+ "the owner releases it",
107
+ ran(give, false, /released \S+wc\.lock/),
108
+ shown(give),
109
+ );
110
+ console.log(
111
+ `✓ run-agent-grid [effects]: skill activated; lock taken, second driver refused, released.\n CLI: ${cli.note}`,
112
+ );
113
+ } finally {
114
+ r.cleanup();
115
+ }
@@ -0,0 +1,18 @@
1
+ /**
2
+ * The subcommands of `grid-guard`, by name. One table, read twice: the dispatcher in
3
+ * `grid-guard.ts` is keyed by these names (a missing or extra entry is a type error there), and
4
+ * `SKILL.md.spec.ts` interpolates them into every command it instructs (a name that is not here
5
+ * is a type error there). So the skill cannot instruct a subcommand the script does not have.
6
+ *
7
+ * A module of its own, with no side effects: the spec imports it at compile time, and importing
8
+ * `grid-guard.ts` itself would run the command line.
9
+ */
10
+ export const COMMANDS = {
11
+ lock: "lock",
12
+ release: "release",
13
+ gate: "gate",
14
+ overlap: "overlap",
15
+ envProbe: "env-probe",
16
+ scanKeys: "scan-keys",
17
+ precommit: "precommit",
18
+ };
@@ -0,0 +1,21 @@
1
+ /**
2
+ * The subcommands of `grid-guard`, by name. One table, read twice: the dispatcher in
3
+ * `grid-guard.ts` is keyed by these names (a missing or extra entry is a type error there), and
4
+ * `SKILL.md.spec.ts` interpolates them into every command it instructs (a name that is not here
5
+ * is a type error there). So the skill cannot instruct a subcommand the script does not have.
6
+ *
7
+ * A module of its own, with no side effects: the spec imports it at compile time, and importing
8
+ * `grid-guard.ts` itself would run the command line.
9
+ */
10
+ export const COMMANDS = {
11
+ lock: "lock",
12
+ release: "release",
13
+ gate: "gate",
14
+ overlap: "overlap",
15
+ envProbe: "env-probe",
16
+ scanKeys: "scan-keys",
17
+ precommit: "precommit",
18
+ } as const;
19
+
20
+ /** A subcommand's name as typed on the command line. */
21
+ export type CommandName = (typeof COMMANDS)[keyof typeof COMMANDS];