paperlint 9.0.0 → 10.0.0

package/lib/skill-trigger-cases.mjs

@@ -12,11 +12,11 @@
  *
  *   skill     the skill under test
  *   why       the territory it owns, in one line — the thing a sibling must NOT take
- *   prompts   should-fire. FOUR each, deliberately mixed (below)
+ *   prompts   should-fire. At least FOUR, deliberately mixed (below)
  *   collides  siblings whose own should-fire prompts become this case's
- *             irrelevantPrompts. That is how "the WRONG skill must not fire" is
- *             asserted, and it is symmetric: each side of a collision is measured
- *             from both directions.
+ *             irrelevantPrompts — at least one from EVERY collider. That is how
+ *             "the WRONG skill must not fire" is asserted, and it is symmetric:
+ *             each side of a collision is measured from both directions.
  *
  * 🔴 THE PROMPTS ARE MIXED ON PURPOSE, AND THE MIX DECIDES THE NUMBER.
  * `framing-vs-vocabulary.eval.mjs` measured the same skills two ways: prompts that
@@ -55,13 +55,36 @@ const PACKAGE_CASES = [
   {
     skill: "grade-paper-writing",
     why: "prose craft — the sentence is the unit, NOT the section",
+    // The first four are HARVESTED and measured; they stay first and unchanged, so the rate on
+    // them stays comparable with pipeline-firing.eval.mjs and the siblings that collide with this
+    // case keep receiving the same irrelevant prompts. The last four were added 2026-10-13 with
+    // the rewritten description and have never been run — rates UNKNOWN. Eight, not four, because
+    // this skill's firing was measured at 12%, then 50–54%, on the same prompts: four prompts
+    // cannot tell those apart.
     prompts: [
       "оцени как написано — читается как стена жаргона",
       "is the writing any good or does it read like shit",
       "abstract звучит криво хотя по смыслу всё на месте, дай оценку прозе",
       "grade the craft: title, abstract, sentence clarity, hedge stacking",
+      "прочитай черновик и скажи честно, нормально ли он читается",
+      "the reviewer says our paper reads like a blog post — is he right about the prose",
+      "каждое предложение по отдельности понятно, а абзацы всё равно сливаются в сплошную простыню",
+      "grade the prose in section 3 and give me the sentences to rewrite",
+    ],
+    // Every sibling the description sends a request to. Each is a different wrong answer to "is
+    // this paper any good?": cut it, re-read one edit, attack the science, predict the committee,
+    // gate the submission, study the venue. Of the five added 2026-10-13, only cold-read-diff
+    // already named this case; the other four do not name it back, because that would change the
+    // irrelevant sets their own rates are measured on.
+    collides: [
+      "tighten-paper",
+      "argument-arc",
+      "cold-read-diff",
+      "paper-adversarial-review",
+      "pc-panel-review",
+      "harden-paper",
+      "study-accepted-papers",
     ],
-    collides: ["tighten-paper", "argument-arc"],
   },
   {
     skill: "argument-arc",
@@ -153,6 +176,17 @@ const PACKAGE_CASES = [
     ],
     collides: ["research-ideate", "draft-paper"],
   },
+  {
+    skill: "build-label-page",
+    why: "a PERSON labels items on a phone page with a shared store, and the answers are exported into the study",
+    prompts: [
+      "сделай мне страницу, где я разметил бы эти примеры с телефона",
+      "build a gold-labelling page for these 40 items so I can answer on my phone",
+      "нужна слепая страница для ревью ответов модели, чтобы я не видел, какой из них чей",
+      "make me a page to label these, and put the answers back into the study folder",
+    ],
+    collides: ["build-benchmark", "draft-paper"],
+  },
   {
     skill: "camera-ready",
     why: "AFTER accept — de-anonymize, archive, disclose",
@@ -248,7 +282,7 @@ const PACKAGE_CASES = [
       "посмотри что принимали на этой площадке и чем те статьи сильны",
       "хочу дотянуть с accept до strong accept — что для этого нужно именно там",
       "read a dozen accepted papers from this venue and diff our draft against them",
-      "какие приёмы у них заходят — артефакты, threat model, запоминающееся название",
+      "before we design the study: what does this venue actually reward? look at its award winners",
     ],
     collides: ["find-venue", "harden-paper"],
   },
@@ -436,14 +470,18 @@ export function irrelevantFor(skill, want = 4) {
   // verify-citations — seven of twenty-one, exactly the set with `collides.length
   // === 1`. Two-collider cases are unaffected (ceil(4/2) === 2), so numbers
   // measured before the fix stay comparable.
+  //
+  // `want` is a FLOOR, not a cap (2026-10-13). The set used to be cut at `want`,
+  // so a case with more than four colliders silently dropped the rest: the table
+  // said "must not take X's requests" and no request of X's was ever sent. Cases
+  // with one or two colliders get exactly what they got before (4); a case with
+  // three gets 6, with seven gets 7 — one from each.
   const per = Math.ceil(want / c.collides.length);
-  return c.collides
-    .flatMap((sib, i) => {
-      const s = BY_SKILL.get(sib);
-      if (!s) throw new Error(`${skill} collides with unknown skill "${sib}"`);
-      // Rotate by the collider's index so two cases sharing a collider do not
-      // receive byte-identical irrelevant sets.
-      return [...s.prompts.slice(i), ...s.prompts.slice(0, i)].slice(0, per);
-    })
-    .slice(0, want);
+  return c.collides.flatMap((sib, i) => {
+    const s = BY_SKILL.get(sib);
+    if (!s) throw new Error(`${skill} collides with unknown skill "${sib}"`);
+    // Rotate by the collider's index so two cases sharing a collider do not
+    // receive byte-identical irrelevant sets.
+    return [...s.prompts.slice(i), ...s.prompts.slice(0, i)].slice(0, per);
+  });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperlint",
-  "version": "9.0.0",
+  "version": "10.0.0",
   "description": "A linter for scientific papers written in LaTeX: catches mistakes before you submit to a conference or journal.",
   "type": "module",
   "license": "MIT",
@@ -34,7 +34,7 @@
     "ts-essentials": "^10.2.1",
     "typescript": "^6.0.3",
     "unpdf": "^1.8.1",
-    "vigiles": "^32.1.0",
+    "vigiles": "^38.2.0",
     "zod": "^4.6.5"
   },
   "devDependencies": {

package/plugin/CLAUDE.md

@@ -0,0 +1,22 @@
+<!-- vigiles:sha256:6312a3b8f9804eba compiled from plugin/CLAUDE.md.spec.ts -->
+
+# CLAUDE.md
+
+## `plugin/`
+
+Not a plugin any more. `plugin/hooks/hooks.json` is the hook wiring that `paperlint init` merges
+into the consumer's `.claude/settings.json`, and it is the only source of that wiring.
+
+## Why there is no Claude Code plugin
+
+There is no Claude Code plugin or marketplace entry; it was removed in the release after 1.0.0
+(#82). Do not bring it back without answering each of these, measured (`docs/install.md`,
+"Why it is shaped this way"):
+
+- **A plugin cannot carry the code.** Claude Code installs a plugin's dependencies with a 60-second
+  timeout, and a failed install never blocks the plugin: the hooks load and fail with
+  `cannot find module vigiles`, silently.
+- **The skills need the npm package anyway.** 23 of 24 skills ran scripts that resolve only through
+  `node_modules/paperlint/`.
+- **Its manifests carried versions nothing updated**, and Claude Code decides plugin updates from
+  that number.

package/plugin/CLAUDE.md.spec.ts

@@ -0,0 +1,22 @@
+// Compiled to plugin/CLAUDE.md by `npx vigiles compile`. Edit THIS file, never the markdown.
+import { file, instructionFile, prose } from "vigiles/spec";
+
+export default instructionFile({
+  sections: {
+    "`plugin/`": prose`Not a plugin any more. ${file("plugin/hooks/hooks.json")} is the hook wiring that \`paperlint init\` merges
+into the consumer's \`.claude/settings.json\`, and it is the only source of that wiring.`,
+
+    "Why there is no Claude Code plugin": prose`There is no Claude Code plugin or marketplace entry; it was removed in the release after 1.0.0
+(#82). Do not bring it back without answering each of these, measured (${file("docs/install.md")},
+"Why it is shaped this way"):
+
+- **A plugin cannot carry the code.** Claude Code installs a plugin's dependencies with a 60-second
+  timeout, and a failed install never blocks the plugin: the hooks load and fail with
+  \`cannot find module vigiles\`, silently.
+- **The skills need the npm package anyway.** 23 of 24 skills ran scripts that resolve only through
+  \`node_modules/paperlint/\`.
+- **Its manifests carried versions nothing updated**, and Claude Code decides plugin updates from
+  that number.`,
+  },
+  rules: {},
+});

package/plugin/hooks/hooks.json

@@ -9,6 +9,15 @@
             "command": "node \"${CLAUDE_PROJECT_DIR}/node_modules/paperlint/bin/paperlint.mjs\" hook paper-edit-guard"
           }
         ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PROJECT_DIR}/node_modules/paperlint/bin/paperlint.mjs\" hook paper-folder-layout"
+          }
+        ]
       }
     ],
     "PostToolUse": [

package/scripts/coverage-config.test.ts

@@ -400,8 +400,9 @@ test("the exclude list is exactly the justified set", () => {
     "**/*.test.*",
     // PAID LLM evaluations, never run by `npm test`
     "**/*.eval.mjs",
-    // skill sources vigiles compiles into SKILL.md
+    // skill and CLAUDE.md sources vigiles compiles; a glob's `**` skips a dot directory
     "**/*.spec.ts",
+    ".github/*.spec.ts",
     // type declarations
     "**/*.d.ts",
     "**/*.d.mts",

package/skills/CLAUDE.md

@@ -0,0 +1,19 @@
+<!-- vigiles:sha256:e0aa2cec8926b04f compiled from skills/CLAUDE.md.spec.ts -->
+
+# CLAUDE.md
+
+## `skills/`
+
+The skills this package ships. Loaded when working under `skills/`. The consumer's root and the
+package's location come from `skills/paper-pipeline/scripts/consumer.mjs`; the links are made by
+`src/link-skills.ts`; install-specific paths are flagged by `eslint-rules/install-path-literals.ts`.
+
+## Rules
+
+### Skills Ship In Skills
+
+**Guidance only** — Skills ship in `skills/`, never `.claude/skills/`. `paperlint init` symlinks each one into the consumer's `.claude/skills/<name>`; the link's directory name is the skill's name. `skills/` is the npm layout: of 855 packages scanned, 336 shipped `skills/` against 15 `.claude/skills/`. Rejected: leaving the skills for Claude Code to find inside `node_modules` (`docs/install.md`); a symlink loads at startup, deterministically.
+
+### A Criterion That Judges Prose
+
+**Guidance only** — It follows the five principles in `eslint-rules/CLAUDE.md` ("A rule that judges prose"). A skill does not grep prose for what a rule can count.

package/skills/CLAUDE.md.spec.ts

@@ -0,0 +1,18 @@
+// Compiled to skills/CLAUDE.md by `npx vigiles compile`. Edit THIS file, never the markdown.
+import { file, guidance, instructionFile, prose } from "vigiles/spec";
+
+export default instructionFile({
+  sections: {
+    "`skills/`": prose`The skills this package ships. Loaded when working under \`skills/\`. The consumer's root and the
+package's location come from ${file("skills/paper-pipeline/scripts/consumer.mjs")}; the links are made by
+${file("src/link-skills.ts")}; install-specific paths are flagged by ${file("eslint-rules/install-path-literals.ts")}.`,
+  },
+  rules: {
+    "skills-ship-in-skills": guidance(
+      "Skills ship in `skills/`, never `.claude/skills/`. `paperlint init` symlinks each one into the consumer's `.claude/skills/<name>`; the link's directory name is the skill's name. `skills/` is the npm layout: of 855 packages scanned, 336 shipped `skills/` against 15 `.claude/skills/`. Rejected: leaving the skills for Claude Code to find inside `node_modules` (`docs/install.md`); a symlink loads at startup, deterministically.",
+    ),
+    "a-criterion-that-judges-prose": guidance(
+      'It follows the five principles in `eslint-rules/CLAUDE.md` ("A rule that judges prose"). A skill does not grep prose for what a rule can count.',
+    ),
+  },
+});

package/skills/analyze-sibling-paper/SKILL.md

@@ -5,7 +5,7 @@ context: fork
 allowed-tools: [WebSearch, WebFetch, Read, Write, Grep, Glob, Bash, Agent]
 ---
 
-<!-- vigiles:sha256:238796152df07749 compiled from skills/analyze-sibling-paper/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:834f128ace92288a compiled from skills/analyze-sibling-paper/SKILL.md.spec.ts -->
 
 # analyze-sibling-paper — settle "isn't this just X?" before a reviewer does
 
@@ -115,7 +115,7 @@ again at rebuttal. **A close sibling with no file in `<paper-dir>/siblings/` is
 ## Compose with
 - `verify-citations` — surfaces the nearest-neighbor works; hand each genuine sibling to this skill.
 - `harden-paper` — its nearest-neighbor-scoop axis (axis 3) calls this for each close competitor.
-- `study-accepted-papers` — venue-corpus levers (different axis: the venue's bar, not a specific rival).
+- `study-accepted-papers` — venue-corpus levers (different axis: what the venue rewards, not a specific rival).
 - `extend-paper` — a scooped angle, or the un-scooped remainder, can become the next paper's pivot.
 
 ## Provenance

package/skills/analyze-sibling-paper/SKILL.md.spec.ts

@@ -130,7 +130,7 @@ again at rebuttal. **A close sibling with no file in \`<paper-dir>/siblings/\` i
 ## Compose with
 - \`verify-citations\` — surfaces the nearest-neighbor works; hand each genuine sibling to this skill.
 - \`harden-paper\` — its nearest-neighbor-scoop axis (axis 3) calls this for each close competitor.
-- \`study-accepted-papers\` — venue-corpus levers (different axis: the venue's bar, not a specific rival).
+- \`study-accepted-papers\` — venue-corpus levers (different axis: what the venue rewards, not a specific rival).
 - \`extend-paper\` — a scooped angle, or the un-scooped remainder, can become the next paper's pivot.
 
 ## Provenance

package/skills/build-benchmark/SKILL.md

@@ -5,7 +5,7 @@ context: fork
 allowed-tools: [Read, Write, Edit, Grep, Glob, Bash, Agent]
 ---
 
-<!-- vigiles:sha256:0b91129ca6a6b2a3 compiled from skills/build-benchmark/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:5eb2ba9561e082d9 compiled from skills/build-benchmark/SKILL.md.spec.ts -->
 
 # build-benchmark — the study + the artifact reviewers can run
 
@@ -51,6 +51,17 @@ is the *inverse* of the flaw:
 
 Write the design as the answer to "what would make the critiqued pitfall impossible here?"
 
+**Declare the population, the screens and the coverage before freezing the sample.** Each screen
+between the population and the sample (fits one excerpt, one classifier lane, a model-picked item)
+changes what the sample can say, not only its size; screens that are reasonable one by one can leave a
+sample nobody meets in practice. So, before the draw is frozen, the study's `prereg.json` says what
+the claim is about, what each screen removed per stratum and what share the sample can represent; then
+show the author the drawn **units** (the rules or cases, not the items made from them) and ask: *is
+this what you meet in practice?* The fields are the experimental rule
+`study/declare-sample` (`docs/rules/study/declare-sample.md`), off by default: do this step either way,
+and turn the check on with `"rules": { "study/declare-sample": "error" }` in the paper's `paperlint.json`
+for `paperlint lint` to fail until they are there.
+
 ## 2. Honest statistics — the part reviewers attack first
 
 - **Paired where the design is paired; Welch where variances differ.** Use a **paired-t** when the same
@@ -156,6 +167,8 @@ Before submitting, verify the artifact you built with the reviewer-side reproduc
 - **argument-arc (frame mode)** — 🔴 **hard input.** Owns row `frame`, the stated claim. No `frame`, no study.
 - **research-ideate** (upstream) — supplies the contribution and the pitfall to invert; this skill turns
   it into evidence.
+- **build-label-page** — when the study needs a person to label items (gold labels, a blind review of
+  outputs): it builds the page, publishes it and exports the answers into the study's `data/`.
 - **draft-paper** — the study's stats, bound, and artifact-number table feed Methods/Results/Availability.
 - **pc-panel-review** — its artifact-runner reviewer `cd`s in and re-executes every harness; build so
   that pass is deterministic.

package/skills/build-benchmark/SKILL.md.spec.ts

@@ -57,6 +57,17 @@ is the *inverse* of the flaw:
 
 Write the design as the answer to "what would make the critiqued pitfall impossible here?"
 
+**Declare the population, the screens and the coverage before freezing the sample.** Each screen
+between the population and the sample (fits one excerpt, one classifier lane, a model-picked item)
+changes what the sample can say, not only its size; screens that are reasonable one by one can leave a
+sample nobody meets in practice. So, before the draw is frozen, the study's \`prereg.json\` says what
+the claim is about, what each screen removed per stratum and what share the sample can represent; then
+show the author the drawn **units** (the rules or cases, not the items made from them) and ask: *is
+this what you meet in practice?* The fields are the experimental rule
+\`study/declare-sample\` (\`docs/rules/study/declare-sample.md\`), off by default: do this step either way,
+and turn the check on with \`"rules": { "study/declare-sample": "error" }\` in the paper's \`paperlint.json\`
+for \`paperlint lint\` to fail until they are there.
+
 ## 2. Honest statistics — the part reviewers attack first
 
 - **Paired where the design is paired; Welch where variances differ.** Use a **paired-t** when the same
@@ -162,6 +173,8 @@ Before submitting, verify the artifact you built with the reviewer-side reproduc
 - **argument-arc (frame mode)** — 🔴 **hard input.** Owns row \`frame\`, the stated claim. No \`frame\`, no study.
 - **research-ideate** (upstream) — supplies the contribution and the pitfall to invert; this skill turns
   it into evidence.
+- **build-label-page** — when the study needs a person to label items (gold labels, a blind review of
+  outputs): it builds the page, publishes it and exports the answers into the study's \`data/\`.
 - **draft-paper** — the study's stats, bound, and artifact-number table feed Methods/Results/Availability.
 - **pc-panel-review** — its artifact-runner reviewer \`cd\`s in and re-executes every harness; build so
   that pass is deterministic.

package/skills/build-label-page/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: build-label-page
+description: Build a phone labelling page published as a claude.ai Artifact with a shared answer store, and export the answers into the paper's study folder. Use when a study needs a person to label items (gold labels, a blind review of model outputs, "is this a real boundary case"), or on "a page to label these", "a gold-labelling page", "a blind review page". Carries the seven rules that keep such a page honest. Composes with build-benchmark and draft-paper.
+allowed-tools: [Read, Write, Edit, Grep, Glob, Bash, Artifact, ArtifactData]
+---
+
+<!-- vigiles:sha256:894d8a2df3f5c319 compiled from skills/build-label-page/SKILL.md.spec.ts -->
+
+# build-label-page — a page the person labels on a phone, and the labels back in the repo
+
+When a study needs a person to decide something about each of many items, a chat thread is the wrong
+tool: it loses answers, shows the model's own output next to the question and gives no count of what
+is left. Build a page instead. The agent generates it from the items, publishes it as an Artifact with
+a shared answer store (the `db` capability), the person answers on a phone, and the agent exports the
+answers into the study's `data/` folder. The labels are data the paper's numbers trace to, so they are
+committed, not left in the store.
+
+**Not for** an LLM judge (no person answers), a questionnaire about the person, or a form that collects
+anything but labels.
+
+## The seven rules
+
+The full text, each with its reason and its check, is
+[`references/checklist.md`](references/checklist.md). Read it before building. In one line each:
+
+1. **Test it in the claude.ai phone viewer before sending the link.** The viewer can size the frame to
+   the page, so the page cannot scroll itself and a fixed toast may be off-screen. A plain browser
+   passing proves nothing about this.
+2. **Navigation never relies on in-page scrolling or toasts.** "Next unanswered" is a filter: it hides
+   every finished item and group, and a note at the top lists what is left and what each still needs.
+3. **An item is done only when every question on it is answered.** The card names the missing
+   question; the progress counter counts complete items only.
+4. **Blind.** Neutral ids (`G001`…), order shuffled with a fixed seed, no model answers, verdicts or
+   source labels on the page. The generator refuses to build when an item carries a field outside an
+   allow-list; new question wording is added to the allow-list on purpose.
+5. **Ask only what the labeller can answer.** Only the languages and tools they know; one "how well do
+   you know it" question per group, used later as an analysis filter; "clear-cut or real boundary"
+   is the labeller's judgement, not the designer's.
+6. **Export into the repository right away**, one JSON per page into the study's `data/` with the
+   export date, commit it, and record answers given in chat with `source: "chat"`. If the page fails,
+   take the last answers in chat; patch the page blind at most once.
+7. **Save on click**, no submit button; "Saved <time>" on every card; survive a reload; render
+   readable, with a banner, when the store is unavailable.
+
+## Procedure
+
+1. **Decide the labelling.** What exactly does the labeller decide per item (the questions, each with
+   a closed set of answers)? Which groups (languages, tools) does the labeller know? How many items
+   fit the time they have on a phone? Who is the labeller: a page with a store opens only for people
+   with access to the artifact, so the labeller is the owner or has been shared as a Contributor.
+   If the study design is not written yet, `build-benchmark` comes first.
+   If the items come from a drawn sample, the study's `prereg.json` declares the population, the
+   screens and the coverage before the sample is frozen (the experimental rule `study/declare-sample` checks it, off by default), and the
+   author has been shown the drawn **units** (the rules or cases, not the items) with "is this what
+   you meet in practice?". The labelling page is not that check: items made from easy units each look
+   fine on their own.
+2. **Copy the generator into the study and write the items.** The study folder is
+   `<paper-dir>/repro/<slug>-YYYY-MM-DD/` (`gold-labels-2026-10-12`; `repro/allowed-files-only` wants the
+   date, a `README.md` in it saying what the study asks, and a line in `repro/README.md`; where this
+   sits in stage 3, and what checks each place: `docs/layout.md` in the paperlint package).
+   `items.json` follows the header of the generator. Source ids in `items.json` are the study's own;
+   the page never shows them.
+
+   ```bash
+   cp ${CLAUDE_SKILL_DIR}/references/example-generator.py <study-dir>/make_label_page.py
+   ```
+
+   The generator is a template: change the questions and keep the guards (allow-list, neutral ids,
+   store-unavailable banner, filter instead of scrolling). Do not loosen the allow-list to make a
+   build pass; take the field out of the item.
+3. **Build and read it as the labeller.** From the study folder (`<study-dir>`):
+
+   ```bash
+   python3 make_label_page.py build items.json label-page
+   ```
+
+   This writes `label-page/page.html` and `label-page/key.json` (the only link from `G001` to the
+   source id; it never goes on the page). Rebuilding with the same seed keeps every id, and a new item
+   gets the next one. Read the page text once as a person who knows nothing about the source: if
+   anything on it tells the answer, take it out of the item.
+4. **Publish.** Load `artifact-design` and `artifact-capabilities`, then publish `page.html` with
+   `capabilities: {db: {}}`. Use a title of two to four words. Do not ask the page for `user` or
+   anything else it does not use.
+5. **Test in the viewer (rule 1)** and list the store once with `ArtifactData` (`list` of
+   `answers`) to confirm the test answer arrived. `ArtifactData` can be a deferred tool: load it with
+   `ToolSearch` first. Then delete the test answer's document, or tell the person which one it is
+   and keep it out of the export.
+6. **Send the link** with one line on how it works: tap an answer, it saves; "Next unanswered" shows
+   what is left. Say what you tested and what you could not.
+7. **Export when the person is done, or stops** (rule 6). Save the store's two collections, `answers`
+   and `groups`, as `dump.json` in the shape the generator's header gives (answers given in chat go
+   in with `"source": "chat"`), then:
+
+   ```bash
+   python3 make_label_page.py export dump.json label-page/key.json data
+   ```
+
+   It writes `data/<study>-labels-<date>.json` and prints every incomplete item, every answer or
+   familiarity value that is not one of the offered options (not counted, same rule as on the page;
+   correct it in the dump and export again) and every group with no familiarity answer. Commit the file in the same pass, and add the line "labels →
+   `data/<study>-labels-<date>.json`" to the paper's `NOTES.md` for the numbers that use them.
+
+## When the page misbehaves
+
+Look at what the store holds (`ArtifactData` `list`) before changing anything: the page may be fine
+and the person may have opened it without access. One fix to the page is allowed. If it fails again,
+ask for the remaining answers in chat, write them into the dump with `"source": "chat"`, and export.
+Do not iterate on a page you cannot see.
+
+## Compose with
+
+- **build-benchmark** — owns the study design and the inter-rater rule: agreement with the person who
+  wrote the codebook measures trainability, not reliability, so the labeller for gold labels is
+  someone who did not write the scheme.
+- **draft-paper** — the exported labels, the familiarity filter and the complete-item count feed the
+  Methods and the threats.
+- **submit-paper** — a published artifact page is not anonymous. Do not link it from an anonymized
+  submission; the exported JSON is what goes into the reproduction artifact.

package/skills/build-label-page/SKILL.md.spec.ts

@@ -0,0 +1,129 @@
+// Compiled to SKILL.md by `vigiles compile`. Edit THIS file, never the markdown.
+import { experimental_skill } from "vigiles/spec";
+
+export default experimental_skill({
+  name: "build-label-page",
+  description:
+    'Build a phone labelling page published as a claude.ai Artifact with a shared answer store, and export the answers into the paper\'s study folder. Use when a study needs a person to label items (gold labels, a blind review of model outputs, "is this a real boundary case"), or on "a page to label these", "a gold-labelling page", "a blind review page". Carries the seven rules that keep such a page honest. Composes with build-benchmark and draft-paper.',
+  tools: [
+    "Read",
+    "Write",
+    "Edit",
+    "Grep",
+    "Glob",
+    "Bash",
+    "Artifact",
+    "ArtifactData",
+  ],
+  body: `
+# build-label-page — a page the person labels on a phone, and the labels back in the repo
+
+When a study needs a person to decide something about each of many items, a chat thread is the wrong
+tool: it loses answers, shows the model's own output next to the question and gives no count of what
+is left. Build a page instead. The agent generates it from the items, publishes it as an Artifact with
+a shared answer store (the \`db\` capability), the person answers on a phone, and the agent exports the
+answers into the study's \`data/\` folder. The labels are data the paper's numbers trace to, so they are
+committed, not left in the store.
+
+**Not for** an LLM judge (no person answers), a questionnaire about the person, or a form that collects
+anything but labels.
+
+## The seven rules
+
+The full text, each with its reason and its check, is
+[\`references/checklist.md\`](references/checklist.md). Read it before building. In one line each:
+
+1. **Test it in the claude.ai phone viewer before sending the link.** The viewer can size the frame to
+   the page, so the page cannot scroll itself and a fixed toast may be off-screen. A plain browser
+   passing proves nothing about this.
+2. **Navigation never relies on in-page scrolling or toasts.** "Next unanswered" is a filter: it hides
+   every finished item and group, and a note at the top lists what is left and what each still needs.
+3. **An item is done only when every question on it is answered.** The card names the missing
+   question; the progress counter counts complete items only.
+4. **Blind.** Neutral ids (\`G001\`…), order shuffled with a fixed seed, no model answers, verdicts or
+   source labels on the page. The generator refuses to build when an item carries a field outside an
+   allow-list; new question wording is added to the allow-list on purpose.
+5. **Ask only what the labeller can answer.** Only the languages and tools they know; one "how well do
+   you know it" question per group, used later as an analysis filter; "clear-cut or real boundary"
+   is the labeller's judgement, not the designer's.
+6. **Export into the repository right away**, one JSON per page into the study's \`data/\` with the
+   export date, commit it, and record answers given in chat with \`source: "chat"\`. If the page fails,
+   take the last answers in chat; patch the page blind at most once.
+7. **Save on click**, no submit button; "Saved <time>" on every card; survive a reload; render
+   readable, with a banner, when the store is unavailable.
+
+## Procedure
+
+1. **Decide the labelling.** What exactly does the labeller decide per item (the questions, each with
+   a closed set of answers)? Which groups (languages, tools) does the labeller know? How many items
+   fit the time they have on a phone? Who is the labeller: a page with a store opens only for people
+   with access to the artifact, so the labeller is the owner or has been shared as a Contributor.
+   If the study design is not written yet, \`build-benchmark\` comes first.
+   If the items come from a drawn sample, the study's \`prereg.json\` declares the population, the
+   screens and the coverage before the sample is frozen (the experimental rule \`study/declare-sample\` checks it, off by default), and the
+   author has been shown the drawn **units** (the rules or cases, not the items) with "is this what
+   you meet in practice?". The labelling page is not that check: items made from easy units each look
+   fine on their own.
+2. **Copy the generator into the study and write the items.** The study folder is
+   \`<paper-dir>/repro/<slug>-YYYY-MM-DD/\` (\`gold-labels-2026-10-12\`; \`repro/allowed-files-only\` wants the
+   date, a \`README.md\` in it saying what the study asks, and a line in \`repro/README.md\`; where this
+   sits in stage 3, and what checks each place: \`docs/layout.md\` in the paperlint package).
+   \`items.json\` follows the header of the generator. Source ids in \`items.json\` are the study's own;
+   the page never shows them.
+
+   \`\`\`bash
+   cp \${CLAUDE_SKILL_DIR}/references/example-generator.py <study-dir>/make_label_page.py
+   \`\`\`
+
+   The generator is a template: change the questions and keep the guards (allow-list, neutral ids,
+   store-unavailable banner, filter instead of scrolling). Do not loosen the allow-list to make a
+   build pass; take the field out of the item.
+3. **Build and read it as the labeller.** From the study folder (\`<study-dir>\`):
+
+   \`\`\`bash
+   python3 make_label_page.py build items.json label-page
+   \`\`\`
+
+   This writes \`label-page/page.html\` and \`label-page/key.json\` (the only link from \`G001\` to the
+   source id; it never goes on the page). Rebuilding with the same seed keeps every id, and a new item
+   gets the next one. Read the page text once as a person who knows nothing about the source: if
+   anything on it tells the answer, take it out of the item.
+4. **Publish.** Load \`artifact-design\` and \`artifact-capabilities\`, then publish \`page.html\` with
+   \`capabilities: {db: {}}\`. Use a title of two to four words. Do not ask the page for \`user\` or
+   anything else it does not use.
+5. **Test in the viewer (rule 1)** and list the store once with \`ArtifactData\` (\`list\` of
+   \`answers\`) to confirm the test answer arrived. \`ArtifactData\` can be a deferred tool: load it with
+   \`ToolSearch\` first. Then delete the test answer's document, or tell the person which one it is
+   and keep it out of the export.
+6. **Send the link** with one line on how it works: tap an answer, it saves; "Next unanswered" shows
+   what is left. Say what you tested and what you could not.
+7. **Export when the person is done, or stops** (rule 6). Save the store's two collections, \`answers\`
+   and \`groups\`, as \`dump.json\` in the shape the generator's header gives (answers given in chat go
+   in with \`"source": "chat"\`), then:
+
+   \`\`\`bash
+   python3 make_label_page.py export dump.json label-page/key.json data
+   \`\`\`
+
+   It writes \`data/<study>-labels-<date>.json\` and prints every incomplete item, every answer or
+   familiarity value that is not one of the offered options (not counted, same rule as on the page;
+   correct it in the dump and export again) and every group with no familiarity answer. Commit the file in the same pass, and add the line "labels →
+   \`data/<study>-labels-<date>.json\`" to the paper's \`NOTES.md\` for the numbers that use them.
+
+## When the page misbehaves
+
+Look at what the store holds (\`ArtifactData\` \`list\`) before changing anything: the page may be fine
+and the person may have opened it without access. One fix to the page is allowed. If it fails again,
+ask for the remaining answers in chat, write them into the dump with \`"source": "chat"\`, and export.
+Do not iterate on a page you cannot see.
+
+## Compose with
+
+- **build-benchmark** — owns the study design and the inter-rater rule: agreement with the person who
+  wrote the codebook measures trainability, not reliability, so the labeller for gold labels is
+  someone who did not write the scheme.
+- **draft-paper** — the exported labels, the familiarity filter and the complete-item count feed the
+  Methods and the threats.
+- **submit-paper** — a published artifact page is not anonymous. Do not link it from an anonymized
+  submission; the exported JSON is what goes into the reproduction artifact.`,
+});

package/skills/build-label-page/build-label-page.eval.mjs

@@ -0,0 +1,15 @@
+/**
+ * build-label-page — the PAID tier: does this skill's description actually fire?
+ *
+ * The prompts live in `lib/skill-trigger-cases.mjs` beside every other skill's, so collisions with
+ * `build-benchmark` and `draft-paper` are visible in one table. Measures recall on its own
+ * territory and precision against those siblings, against the real harness.
+ *
+ * ⚠️ NEVER RUN. Written 2026-10-12 with the skill; its rate is UNKNOWN, not assumed good.
+ *
+ * Costs money; not CI.
+ *   node skills/build-label-page/build-label-page.eval.mjs [trials]
+ */
+import { runSkillTriggerEval } from "../../lib/skill-eval-kit.mjs";
+
+await runSkillTriggerEval("build-label-page");