paperlint 14.1.0 → 14.3.0

package/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- vigiles:sha256:58c66e374c084cc5 compiled from CLAUDE.md.spec.ts -->
+<!-- vigiles:sha256:d595fb538eb0a81e compiled from CLAUDE.md.spec.ts -->
 
 # CLAUDE.md
 
@@ -106,6 +106,11 @@ Before writing machinery, **run the thing you are about to replace and paste its
 
 **Guidance only** — Before adding a CLI command or changing a delivery channel (skill links, hook wiring, the composite action, the npm package), read how comparable tools did it. "We need another command for X" has, in every tool examined, been the CONFIG not declaring something. [Details](docs/prior-art/README.md)
 
+### Browser Tests Find By Data Test
+
+**Enforced by:** `eslint/playwright/no-raw-locators`
+**Why:** A browser test finds an element only by `getByTestId` on `data-test`, and reads its values from the JSON in `data-test-meta`, never from CSS classes or visible text; content text is compared with the fixture's value. The older browser tests sit in `eslint-suppressions.json`, which may only shrink. [Details](docs/testing.md)
+
 ### New Code Is Functional
 
 **Enforced by:** `eslint/functional/no-let`

package/dist/skills/build-label-page/scripts/label-page-core.d.ts

@@ -83,20 +83,45 @@ interface CodeLine {
     readonly n: number;
     readonly text: string;
     readonly mark: boolean;
+    readonly gutter?: string;
+    readonly context?: boolean;
+}
+/** One entry of a term's note: a verbatim quote or snippet, and the link to where it is from. */
+interface NoteEntry {
+    readonly title?: string;
+    readonly says?: string;
+    readonly quote?: string;
+    readonly code?: string;
+    readonly example?: string;
+    readonly url: string;
+    readonly url_label: string;
+}
+interface Term {
+    readonly term: string;
+    readonly note: readonly NoteEntry[];
 }
 /** The content blocks (#380), each optional on any kind. */
 interface Blocks {
     readonly situation?: {
-        readonly summary: string;
+        readonly summary?: string;
         readonly question: string;
     };
     readonly excerpt?: {
         readonly file?: string;
+        readonly lang?: string;
         readonly url?: string;
+        readonly gutter_header?: string;
         readonly lines: readonly CodeLine[];
+        readonly annotation?: string;
         readonly caption?: string;
         readonly mark_label?: string;
     };
+    readonly quote?: {
+        readonly text: string;
+        readonly source?: string;
+    };
+    readonly terms?: readonly Term[];
+    readonly answer_notes?: Readonly<Record<string, Readonly<Record<string, string>>>>;
     readonly references?: {
         readonly summary: string;
         readonly entries: readonly {
@@ -135,7 +160,7 @@ interface Blocks {
 type Card = {
     readonly [F in (typeof PAGE_FIELDS)[number]]?: string;
 } & Blocks & {
-    readonly body: string;
+    readonly body?: string;
     readonly rules?: readonly RuleRef[];
     readonly unit?: Unit;
     readonly readings?: {
@@ -146,6 +171,7 @@ type Card = {
 type Item = Card & {
     readonly source_id: string;
     readonly group: string;
+    readonly answerers?: readonly string[];
 };
 type Practice = Card & {
     readonly expected: Readonly<Record<string, string>>;
@@ -159,6 +185,8 @@ interface Config {
     readonly seed: number;
     readonly groups: Readonly<Record<string, string>>;
     readonly labeller_knows?: readonly string[];
+    readonly answerers?: readonly string[];
+    readonly min_seconds?: number;
     readonly familiarity?: boolean;
     readonly familiarity_question?: string;
     readonly questions: readonly Question[];
@@ -171,6 +199,8 @@ interface KeyEntry {
     readonly source_id: string;
     readonly group: string;
     readonly on_page: boolean;
+    /** Who the item is shown to, when not every answerer of the page. */
+    readonly answerers?: readonly string[];
 }
 /** Rule → the linter's description (and a ruff rule's family), for every rule a card names. */
 type Described = ReadonlyMap<string, RuleText>;
@@ -183,21 +213,6 @@ declare function itemsOnPage(cfg: Config, keyPath: string): {
 };
 /** What a page shows: the questions, the practice and the items, blind, with their neutral ids. */
 declare function payloadOf(cfg: Config, page: ReturnType<typeof itemsOnPage>, described: Described): {
-    title: string;
-    intro: string;
-    labels: {
-        [x: string]: string;
-    };
-    groups: {
-        id: string;
-        label: string;
-    }[];
-    familiarity_question: string;
-    familiarity: {
-        value: string;
-        label: string;
-    }[];
-    allowed: JsonObject;
     questions: readonly Question[];
     practice: {
         round: number;
@@ -219,9 +234,11 @@ declare function payloadOf(cfg: Config, page: ReturnType<typeof itemsOnPage>, de
         })[];
     };
     items: ({
+        answerers?: readonly string[];
         rules?: never;
         id: string;
     } | {
+        answerers?: readonly string[];
         rules: {
             description?: string;
             family?: string;
@@ -230,6 +247,23 @@ declare function payloadOf(cfg: Config, page: ReturnType<typeof itemsOnPage>, de
         }[];
         id: string;
     })[];
+    answerers?: readonly string[];
+    min_seconds?: number;
+    title: string;
+    intro: string;
+    labels: {
+        [x: string]: string;
+    };
+    groups: {
+        id: string;
+        label: string;
+    }[];
+    familiarity_question: string;
+    familiarity: {
+        value: string;
+        label: string;
+    }[];
+    allowed: JsonObject;
 };
 export type Payload = ReturnType<typeof payloadOf>;
 /**
@@ -239,21 +273,6 @@ export type Payload = ReturnType<typeof payloadOf>;
  */
 export declare function prepareBuild(configPath: string, outDir: string): {
     payload: {
-        title: string;
-        intro: string;
-        labels: {
-            [x: string]: string;
-        };
-        groups: {
-            id: string;
-            label: string;
-        }[];
-        familiarity_question: string;
-        familiarity: {
-            value: string;
-            label: string;
-        }[];
-        allowed: JsonObject;
         questions: readonly Question[];
         practice: {
             round: number;
@@ -275,9 +294,11 @@ export declare function prepareBuild(configPath: string, outDir: string): {
             })[];
         };
         items: ({
+            answerers?: readonly string[];
             rules?: never;
             id: string;
         } | {
+            answerers?: readonly string[];
             rules: {
                 description?: string;
                 family?: string;
@@ -286,6 +307,23 @@ export declare function prepareBuild(configPath: string, outDir: string): {
             }[];
             id: string;
         })[];
+        answerers?: readonly string[];
+        min_seconds?: number;
+        title: string;
+        intro: string;
+        labels: {
+            [x: string]: string;
+        };
+        groups: {
+            id: string;
+            label: string;
+        }[];
+        familiarity_question: string;
+        familiarity: {
+            value: string;
+            label: string;
+        }[];
+        allowed: JsonObject;
     };
     dropped: number;
 };

package/docs/testing.md

@@ -149,3 +149,15 @@ file matches, and it transpiles without type-checking, so `npm run check` runs
    really occur stays, with the test that reaches it. `scripts/coverage-config.test.ts` fails on any
    coverage-ignore comment and pins `.c8rc.json`'s `exclude` list.
 7. **Say what an assertion guards** in a comment directly above it (`// Guards: …`).
+8. **A browser test finds an element by `data-test` and reads its values from `data-test-meta`.**
+   The page marks every element a test touches with `data-test="<kind>"` and puts the element's
+   values in `data-test-meta` as JSON (`{"line":279,"marked":true}`). The test sets
+   `selectors.setTestIdAttribute("data-test")`, locates only with `getByTestId`, parses the meta and
+   compares it with one `deepEqual`. CSS classes stay for styling and visible text stays for people,
+   so a restyle or a reworded label does not turn a test red. Text that IS the content (an
+   annotation, a quote) is compared with the fixture's value, never with a literal typed into the
+   test. Accessibility state (`aria-expanded`) may be asserted on purpose, but it never locates
+   anything. `playwright/no-raw-locators`, `playwright/prefer-locator`, `playwright/no-wait-for-selector`
+   and `playwright/no-eval` hold the locating half; the older browser tests sit in
+   `eslint-suppressions.json`, which may only shrink. Example: `annotatedFacts` and
+   `annotatedExpected` in `skills/build-label-page/scripts/label-page-browser.test.ts`.

package/eslint.config.mjs

@@ -19,6 +19,7 @@ import jsReasonRules from "#eslint-rules/js-needs-reason";
 
 import portRules from "#eslint-rules/install-path-literals";
 import n from "eslint-plugin-n";
+import playwright from "eslint-plugin-playwright";
 import tseslint from "typescript-eslint";
 import boundaries from "eslint-plugin-boundaries";
 import functional from "eslint-plugin-functional";
@@ -697,6 +698,22 @@ export default [
     files: TEST_FILES,
     rules: { "max-lines-per-function": ["error", MAX_LINES_TESTS] },
   },
+  // Browser tests find an element by its test id (`data-test`, set in the page and in
+  // `selectors.setTestIdAttribute`) and read its values from `data-test-meta`: a CSS selector or a
+  // visible text breaks when the look changes. The rules fire under vitest as well as under
+  // Playwright's own runner (measured on label-page-browser.test.ts and candidate_page.test.ts).
+  // The plugin's `testIdAttribute` option belongs to `prefer-native-locators`, which this block does
+  // not enable, so there is nothing to configure.
+  {
+    files: TEST_FILES,
+    plugins: { playwright },
+    rules: {
+      "playwright/no-raw-locators": "error",
+      "playwright/prefer-locator": "error",
+      "playwright/no-wait-for-selector": "error",
+      "playwright/no-eval": "error",
+    },
+  },
   // 🔴 DEBT, NOT A PERMISSION. The novelty-check scripts and their harnesses were moved from a consumer
   // repository AS THEY WERE (the 2026-11-02 decision): untyped JSON in, `any` throughout. Making them pass the
   // type-safety rules below means rewriting them, which is paperlint#339 (TypeScript rewrite of the Python

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperlint",
-  "version": "14.1.0",
+  "version": "14.3.0",
   "description": "A linter for scientific papers written in LaTeX: catches mistakes before you submit to a conference or journal.",
   "type": "module",
   "license": "MIT",
@@ -55,6 +55,7 @@
     "eslint-plugin-boundaries": "^7.2.0",
     "eslint-plugin-functional": "^10.0.1",
     "eslint-plugin-n": "^18.3.0",
+    "eslint-plugin-playwright": "^2.12.2",
     "eslint-plugin-project-structure": "^3.14.5",
     "eslint-plugin-sonarjs": "^4.2.1",
     "jsonc-parser": "^3.3.1",

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

@@ -4,7 +4,7 @@ description: Build a phone labelling page published as a claude.ai Artifact with
 allowed-tools: [Read, Write, Edit, Grep, Glob, Bash, Artifact, ArtifactData]
 ---
 
-<!-- vigiles:sha256:64e09e4a829be441 compiled from skills/build-label-page/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:9d7a2c35df4e6a10 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
 
@@ -106,8 +106,10 @@ building. In one line each:
    It 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). `kind` (`approval`, `witness`, `labels`) is required,
    and each kind requires its card fields on every item and practice card. Any card may also carry
-   the generic content blocks (a code excerpt with a marked line, references, a list, a table), every
-   word on them from `items.json`, with the question right under the excerpt. `"preset":
+   the generic content blocks (a code excerpt with a marked line, a note under it and an extra
+   gutter column; the words asked about as a quote; tap-to-see notes on its terms; a sub-line under
+   each answer; references, a list, a table, none of them folded), every word on them from
+   `items.json`, with the question right under the excerpt. `"preset":
    "linter-config-witness"` is a narrow preset for comparing linter configs; the blocks underneath
    are generic. Written by hand, the page meets the requirements above.
 4. **Read it as the labeller, then look at it.** Read the page text once as a person who knows
@@ -142,6 +144,20 @@ building. In one line each:
    same pass, and add the line "labels → `data/<study>-labels-<date>.json`" to the paper's
    `NOTES.md` for the numbers that use them.
 
+## Two answerers, and a time on screen
+
+Two optional top-level keys of `items.json`, both left out by default:
+
+- `"answerers": ["author", "second"]` — two or more people answer the same published page, each
+  under their own name (picked on the page) and without seeing the other's answers; an item's own
+  `answerers` shows it to that subset only. The store's ids become `<answerer>~<id>`, and the
+  labels file keeps each answerer's answers under `by_answerer`.
+- `"min_seconds": 30` — a card's answer saves only after the card has been on screen that long;
+  the seconds at its first save are stored and exported as `seconds`.
+
+Details and the export's shape: [`references/closed-choice-generator.md`](references/closed-choice-generator.md),
+"Two answerers, and a minimum time on screen".
+
 ## When the page misbehaves
 
 Look at what the store holds (`ArtifactData` `list`) before changing anything: the page may be fine

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

@@ -117,8 +117,10 @@ building. In one line each:
    It 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). \`kind\` (\`approval\`, \`witness\`, \`labels\`) is required,
    and each kind requires its card fields on every item and practice card. Any card may also carry
-   the generic content blocks (a code excerpt with a marked line, references, a list, a table), every
-   word on them from \`items.json\`, with the question right under the excerpt. \`"preset":
+   the generic content blocks (a code excerpt with a marked line, a note under it and an extra
+   gutter column; the words asked about as a quote; tap-to-see notes on its terms; a sub-line under
+   each answer; references, a list, a table, none of them folded), every word on them from
+   \`items.json\`, with the question right under the excerpt. \`"preset":
    "linter-config-witness"\` is a narrow preset for comparing linter configs; the blocks underneath
    are generic. Written by hand, the page meets the requirements above.
 4. **Read it as the labeller, then look at it.** Read the page text once as a person who knows
@@ -153,6 +155,20 @@ building. In one line each:
    same pass, and add the line "labels → \`data/<study>-labels-<date>.json\`" to the paper's
    \`NOTES.md\` for the numbers that use them.
 
+## Two answerers, and a time on screen
+
+Two optional top-level keys of \`items.json\`, both left out by default:
+
+- \`"answerers": ["author", "second"]\` — two or more people answer the same published page, each
+  under their own name (picked on the page) and without seeing the other's answers; an item's own
+  \`answerers\` shows it to that subset only. The store's ids become \`<answerer>~<id>\`, and the
+  labels file keeps each answerer's answers under \`by_answerer\`.
+- \`"min_seconds": 30\` — a card's answer saves only after the card has been on screen that long;
+  the seconds at its first save are stored and exported as \`seconds\`.
+
+Details and the export's shape: [\`references/closed-choice-generator.md\`](references/closed-choice-generator.md),
+"Two answerers, and a minimum time on screen".
+
 ## When the page misbehaves
 
 Look at what the store holds (\`ArtifactData\` \`list\`) before changing anything: the page may be fine

package/skills/build-label-page/references/closed-choice-generator.md

@@ -21,7 +21,7 @@ with the core's payload. Another page shape would be another template on the sam
 Rules 2 to 5, 7 and the page half of 8 of [`checklist.md`](checklist.md): a filter instead of
 scrolling, complete-item counting, neutral ids in a seeded order, the leak guard (an item field
 outside the allow-list stops the build), save on click with a time, the store-unavailable banner,
-the "How to answer" screen (folded into a toggle once the practice is done), the practice before
+the "How to answer" screen (folded into a toggle once the practice is done; it is page-level, not part of any card), the practice before
 the real items, one question per screen, each card's place (`labels.place`, by default
 "G007 · 7 of 20"), the card just
 answered kept under "Next unanswered" until the next answer (so a mis-tap can be changed), and a
@@ -111,7 +111,7 @@ Any card may carry these blocks, on any `kind`, and each one is optional. The pa
     "mark_label": "◀ the line in question", // optional; default «◀ this line»
   },
   "references": {
-    "summary": "What the guideline says", // the folded block's toggle
+    "summary": "What the guideline says", // the block's heading
     "entries": [
       {
         "label": "Guideline", // optional row label
@@ -162,17 +162,50 @@ Any card may carry these blocks, on any `kind`, and each one is optional. The pa
   4. the older fields (`code`, `unit`, `rules`, `readings`, `file`, `context`);
   5. the situation's summary;
   6. the excerpt;
-  7. **the question and its answers**;
-  8. `references`, `more` and `table`, each folded and closed.
+  7. **the question box**: the `quote` and its source, the question, and its answers with their `answer_notes`;
+  8. `references`, `more` and `table`, each in place under its heading. Nothing on a card is folded:
+     a labeller who has to open a block to answer reads half a card (#392).
 
   The question therefore sits right under the code it names.
 
-- **`situation`**: `{summary, question}`.
-  - `summary` is one sentence above the excerpt.
+- **`situation`**: `{summary?, question}`.
+  - `summary` is one sentence above the excerpt; optional.
   - `question` replaces the text of the page's first question on this card. Other questions keep their own text.
   - In either text, `{line}` stands for the excerpt's first marked line. The page writes «line N: », then the line's code as code, without its indent. A code line holding a backtick reads as it is.
   - `{line}` on a card without an `excerpt` is refused by path.
-- **`excerpt`**: at least one line is marked (`mark: true`). The marked line gets a `▶` in the gutter and `mark_label` after its code, and keeps its background, so it reads as marked even without its colour. A line's `text` may be empty, for a blank line.
+- **`excerpt`**: at least one line is marked (`mark: true`). The marked line gets a `▶` before its number and keeps its background, so it reads as marked even without its colour; after its code comes `mark_label`, unless the excerpt has an `annotation`. A line's `text` may be empty, for a blank line.
+  - `lang` follows the file name: «path · Python».
+  - Where two lines' numbers are not consecutive, a `⋮` row says what is left out (`labels.hidden`, `labels.hidden_one`). A line with `context: true` is drawn faint: one shown only to place the code, such as an enclosing block's opener.
+  - `gutter_header` and each line's `gutter` add a column between the number and the code: one word on top, one value per line («depth», `4`). The values are the consumer's, never computed by the page.
+  - `annotation` is one short fact in a box right under the first marked line, inside the code, with an arrow pointing at the line, as a code-review comment sits.
+
+### The approved card: a quote, notes on terms, answers that say what they mean
+
+`scripts/fixtures/v7-cards-items.json` is a page of three such cards (#392). The fields:
+
+```jsonc
+{
+  "quote": { "text": "Docstrings use Google-style format", "source": "`.github/copilot-instructions.md`, line 67" },
+  "situation": { "question": "Do these words forbid line 48?" },
+  "excerpt": { "file": "src/tables/merge.py", "lang": "Python", "annotation": "Ruff rule `D413` reports: …", "lines": [ … ] },
+  "terms": [
+    {
+      "term": "Google-style", // the card's own words that open the note
+      "note": [
+        // one or more entries; each has `quote` or `code` (verbatim), and its source link
+        { "title": "Google style", "quote": "Each section begins with a heading line, which ends with a colon.",
+          "example": "(e.g. `Args:`)", "url": "https://google.github.io/styleguide/pyguide.html", "url_label": "Google Python Style Guide" },
+      ],
+    },
+  ],
+  "answer_notes": { "forbid": { "forbid": "like a config with rule D413 on, which flags it" } }, // question → answer → sub-line
+}
+```
+
+- **`quote`** shows the words being asked about at the top of the question box, `source` as a small line under them. A card needs `body` or `quote`.
+- **`terms`**: each `term` must occur in the quote, its source or the annotation, inside one backtick span or outside all of them; the build refuses one it cannot find there, and a note entry with neither `quote` nor `code`. A term opens from its first occurrence in the quote, else the source, else the annotation. On the page it is a dotted button: a tap (or hover, where there is hover) opens one floating note anchored to it, at most 280 px wide (300 with a snippet), flipped above the term when there is no room below, kept inside the viewport. A tap outside closes it and does nothing else, so it never answers a card; so does Esc. Answer buttons carry no terms.
+- **`answer_notes`** puts a sub-line under an answer's label on this card: what the answer means here. A question or an answer the page does not have is refused.
+- Whether a note pushes the labeller toward one answer is not checked: the consumer lists each note for the study's author.
 - **`references.entries[].fields`**:
   - A field without `style` is a paragraph («label: text» when it has a label). A long one shows three lines and a «more».
   - `style: "code"` is a code block on a `label` row.
@@ -189,6 +222,9 @@ Any card may carry these blocks, on any `kind`, and each one is optional. The pa
   | `line_part`        | the `unit` row's label when the line holds several requirements | `{line} · part {part} of {of}` |
   | `repeat`           | the repeat sentence                                             | `Card {index} of {of}`         |
   | `practice_example` | text before each answer's example on a practice button          | empty                          |
+  | `hidden`           | a `⋮` row for lines left out                                    | `lines {from}–{to}`            |
+  | `hidden_one`       | a `⋮` row for one line left out                                 | `line {from}`                  |
+  | `wait`             | the bar under the answers while `min_seconds` runs              | `⏳ You can answer in {s} s`   |
 
 - The leak guard reads every string these blocks render, one string at a time.
 
@@ -199,7 +235,7 @@ A preset is opt-in. An items file names it with `"preset": "<name>"`. The preset
 - **`linter-config-witness`** is narrow: two linter configs of one requirement disagree on a line of code. The blocks underneath are generic.
   - **Input fields on a card:**
     - `example: {file, url?, lines, message, caught_by}`, which becomes the excerpt, with the caption «The linter says: …».
-    - `rules: [{linter, id, explanation}]`, whose explanation has `source` (`ruff rule`, `eslint docs`, `plugin docs`, `config message` or `none`), plus `what`, `why`, `example_bad`, `example_good` and `url`. These become the references, folded under «What the linter rule does (official docs)».
+    - `rules: [{linter, id, explanation}]`, whose explanation has `source` (`ruff rule`, `eslint docs`, `plugin docs`, `config message` or `none`), plus `what`, `why`, `example_bad`, `example_good` and `url`. These become the references, under «What the linter rule does (official docs)».
     - `more_like_this: {count, files}`, which becomes the list «N more file(s) with the same situation».
     - `details: {a, b}`: rows of `{key, raw, plain, matches_example}`. They become the table «Settings behind this card», with «A only / B only / A and B» rows.
   - **Its labels**: «Card {n} of {total}», «Requirement», «Card {index} of {of} for this requirement», and «Example of this answer, about other code: ».
@@ -246,6 +282,48 @@ author cannot read it is an exclusion made after the draw and goes unrecorded. T
 units whose fate is obvious. Each dropped unit carries its reason in the labels file. The author's words, with the date, then go into
 `author_check` of the plan; a dropped unit is replaced by the next one in the draw.
 
+## Two answerers, and a minimum time on screen
+
+Both keys are optional and top-level. Left out, the page, its store documents and the export are
+exactly as above.
+
+- **`answerers`**: two or more names (letters, digits, `-` and `_`), for a study where two people
+  answer the same published page, each under their own name and without seeing the other's
+  answers. The page first asks "Who is answering?"; the choice is kept in the browser's
+  localStorage when it has one (otherwise it asks again on every visit), and "Switch" beside
+  "Answering as …" asks again. Every document the page writes is named `<answerer>~<id>`
+  (`second~G004`, `second~r1-P2`, `second~python`): `~` is outside the name pattern, so no answerer,
+  item, group or practice id can hold it. The page reads only the current answerer's documents, so
+  their progress, done-state and practice are their own. An item may carry its own `answerers`, a
+  subset of the page's: it is shown only to those. A name an item lists that the page does not, a
+  name twice, or an item's list on a page without one stops the build.
+- **`min_seconds`**: an item's answer saves only after its card has been on screen that long. The
+  cards are a list, so "on screen" is measured by an `IntersectionObserver`: half the card in view,
+  or half the viewport filled by a card taller than that, while the tab is visible. A locked card
+  shows "You can answer in N s" under its disabled buttons. The answer document gains `seconds`:
+  how long the card had been on screen at its first save, kept on every later save. The practice
+  cards are not held.
+
+`key.json` carries `answerers`, each item's own subset (`ids.<id>.answerers`, only where it has one)
+and `min_seconds`. With `answerers`, `export` refuses a document id without `<answerer>~`, an
+answerer the key does not list, and an answer to an item not shown to its answerer, as it refuses
+an unknown item. The labels file keeps each answerer's answers apart:
+
+```text
+{ "answerers": ["author", "second"],
+  "items": [{ "id": "G001", "source_id": "case-1000", "group": "python",
+              "answerers": ["author", "second"],
+              "by_answerer": { "author": { "answers": { "label": "yes" }, "complete": true,
+                                           "seconds": 41, "…": "the fields of an item above" },
+                               "second": { "…": "…" } } }],
+  "by_answerer": { "author": { "groups": {}, "complete_items": 1, "total_items": 1, "…": "…" },
+                   "second": { "…": "…" } } }
+```
+
+An answerer with no document for an item is still listed, with every answer `null`. Each
+answerer's practice is scored into its own file, `<study>-practice-r<round>-<answerer>-<date>.json`.
+`seconds` appears only when the page was built with `min_seconds`.
+
 ## The export
 
 `export` reads the store's three collections (`answers`, `groups`, `practice`) from `dump.json`, in

package/skills/build-label-page/scripts/fixtures/v7-cards-items.json

@@ -0,0 +1,138 @@
+{
+  "study": "demo-words-forbid",
+  "kind": "labels",
+  "title": "Do the words forbid it",
+  "seed": 3,
+  "min_seconds": 10,
+  "groups": { "all": "Cards" },
+  "labels": { "place": "Card {n} of {total}", "wait": "Save · available after {s} seconds on this card" },
+  "questions": [
+    {
+      "id": "forbid",
+      "text": "Do these words forbid the marked line?",
+      "short": "do the words forbid it?",
+      "options": [
+        { "value": "forbid", "label": "Forbid", "icon": "⛔", "example": "«No print calls» and the line print(x)" },
+        { "value": "allow", "label": "Allow", "icon": "✅", "example": "«No print calls» and the line log.info(x)" },
+        { "value": "unsettled", "label": "The words don't settle it", "icon": "↔️", "example": "«Keep functions short» and a 30-line function" },
+        { "value": "elsewhere", "label": "The words are about something else", "icon": "🔀", "example": "«Use tabs» and a line about a database query" },
+        { "value": "cannot", "label": "I can't judge (say why)", "icon": "❔", "example": "a line in a language you do not read", "ask_why": "What stops you?" }
+      ]
+    }
+  ],
+  "practice": [
+    {
+      "quote": { "text": "No print calls in library code", "source": "`CONTRIBUTING.md`, line 4" },
+      "situation": { "question": "Do these words forbid line 3?" },
+      "excerpt": { "file": "lib/sum.py", "lang": "Python", "lines": [
+        { "n": 2, "text": "def total(xs):", "mark": false },
+        { "n": 3, "text": "    print(xs)", "mark": true }
+      ] },
+      "expected": { "forbid": "forbid" }, "why": "print is a print call, and lib/ is library code."
+    },
+    {
+      "quote": { "text": "No print calls in library code", "source": "`CONTRIBUTING.md`, line 4" },
+      "situation": { "question": "Do these words forbid line 3?" },
+      "excerpt": { "file": "lib/sum.py", "lang": "Python", "lines": [
+        { "n": 2, "text": "def total(xs):", "mark": false },
+        { "n": 3, "text": "    log.debug(xs)", "mark": true }
+      ] },
+      "expected": { "forbid": "allow" }, "why": "A log call is not a print call."
+    },
+    {
+      "quote": { "text": "Use tabs for indentation", "source": "`STYLE.md`, line 2" },
+      "situation": { "question": "Do these words forbid line 8?" },
+      "excerpt": { "file": "db/query.py", "lang": "Python", "lines": [
+        { "n": 8, "text": "rows = db.execute(sql)", "mark": true }
+      ] },
+      "expected": { "forbid": "elsewhere" }, "why": "The words are about indentation; the line is a query."
+    }
+  ],
+  "items": [
+    {
+      "source_id": "card-docstring", "group": "all",
+      "quote": { "text": "Docstrings use Google-style format", "source": "`.github/copilot-instructions.md`, line 67" },
+      "situation": { "question": "Do these words forbid line 48?" },
+      "excerpt": {
+        "file": "src/tables/merge.py", "lang": "Python",
+        "annotation": "Ruff rule `D413` reports: “Missing blank line after last section (\"Returns\")”",
+        "lines": [
+          { "n": 37, "text": "def merge_tables(", "mark": false, "context": true },
+          { "n": 40, "text": "    \"\"\"", "mark": false },
+          { "n": 41, "text": "    Merge the tables picked by the flags.", "mark": false },
+          { "n": 42, "text": "", "mark": false },
+          { "n": 43, "text": "    picks: For each table name, whether to keep its rows of each kind", "mark": false },
+          { "n": 44, "text": "        (kept, dropped), and which of the two to merge first.", "mark": false },
+          { "n": 45, "text": "    tables: Every table that can be merged.", "mark": false },
+          { "n": 46, "text": "        Columns needed: \"name\", \"kind\"", "mark": false },
+          { "n": 47, "text": "", "mark": false },
+          { "n": 48, "text": "    Returns:", "mark": true },
+          { "n": 49, "text": "        One table with the rows of every table picked.", "mark": false },
+          { "n": 50, "text": "    \"\"\"", "mark": false },
+          { "n": 51, "text": "    kinds_needed = {", "mark": false }
+        ]
+      },
+      "terms": [
+        { "term": "Ruff", "note": [{ "quote": "An extremely fast Python linter and code formatter, written in Rust.", "url": "https://docs.astral.sh/ruff/", "url_label": "Ruff docs" }] },
+        { "term": "D413", "note": [{ "title": "Ruff rule D413", "quote": "Checks for missing blank lines after the last section of a multiline docstring", "url": "https://docs.astral.sh/ruff/rules/missing-blank-line-after-last-section/", "url_label": "docs" }] },
+        { "term": "Google-style", "note": [
+          { "title": "Google style", "quote": "Each section begins with a heading line, which ends with a colon.", "example": "(e.g. `Args:`, `Returns:`, `Raises:`)", "url": "https://google.github.io/styleguide/pyguide.html#383-functions-and-methods", "url_label": "Google Python Style Guide, 3.8.3" },
+          { "title": "NumPy style, the other common one", "quote": "Each heading should be underlined in hyphens", "example": "(e.g. `Returns` with `-------` on the line under it)", "url": "https://numpydoc.readthedocs.io/en/latest/format.html#sections", "url_label": "numpydoc format guide" }
+        ] },
+        { "term": ".github/copilot-instructions.md", "note": [{ "quote": "Repository-wide custom instructions apply to all requests made in the context of a repository.", "url": "https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions", "url_label": "GitHub Docs" }] }
+      ],
+      "answer_notes": { "forbid": { "forbid": "like a config with rule D413 on, which flags it", "allow": "like a config without D413, which passes it" } }
+    },
+    {
+      "source_id": "card-call", "group": "all",
+      "quote": { "text": "Use cachedElement('elementId') instead of document.getElementById", "source": "`AGENTS.md`, line 7" },
+      "situation": { "question": "Do these words forbid line 22?" },
+      "excerpt": {
+        "file": "src/dom/cache.ts", "lang": "TypeScript",
+        "annotation": "calls `document.getElementById`",
+        "lines": [
+          { "n": 9, "text": "export const cachedElement = (id: string) => {", "mark": false, "context": true },
+          { "n": 19, "text": "    return hit", "mark": false },
+          { "n": 20, "text": "  }", "mark": false },
+          { "n": 21, "text": "", "mark": false },
+          { "n": 22, "text": "  const el = document.getElementById(id)", "mark": true },
+          { "n": 23, "text": "", "mark": false },
+          { "n": 24, "text": "  if (!el) {", "mark": false },
+          { "n": 25, "text": "    throw new TypeError(`No element with id \"${id}\"`)", "mark": false }
+        ]
+      },
+      "terms": [
+        { "term": "cachedElement", "note": [{ "says": "this project's own function, defined at line 9 of the file above; its comment reads", "quote": "A cache for DOM elements", "url": "https://example.com/src/dom/cache.ts#L3-L9", "url_label": "src/dom/cache.ts" }] },
+        { "term": "document.getElementById", "note": [{ "quote": "returns an Element object representing the element whose id property matches the specified string", "url": "https://developer.mozilla.org/en-US/docs/Web/API/Document/getElementById", "url_label": "MDN" }] },
+        { "term": "AGENTS.md", "note": [{ "quote": "a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project.", "url": "https://agents.md/", "url_label": "agents.md" }] }
+      ],
+      "answer_notes": { "forbid": { "forbid": "like a config that bans this call and checks this file", "allow": "like a config that bans this call but doesn't check this file" } }
+    },
+    {
+      "source_id": "card-depth", "group": "all",
+      "quote": { "text": "Avoid deep nesting (use early returns and guard clauses)", "source": "`CLAUDE.md`, line 85" },
+      "situation": { "question": "Do these words forbid line 279?" },
+      "excerpt": {
+        "file": "src/index/FileIndex.ts", "lang": "TypeScript", "gutter_header": "depth",
+        "annotation": "nested 4 blocks deep",
+        "lines": [
+          { "n": 22, "text": "export class FileIndex {", "mark": false, "context": true },
+          { "n": 257, "text": "  private onDeleted(uri: Uri): void {", "mark": false, "context": true },
+          { "n": 262, "text": "    try {", "mark": false, "context": true, "gutter": "1" },
+          { "n": 276, "text": "      if (entry.isDir) {", "mark": false, "gutter": "2" },
+          { "n": 277, "text": "        const prefix = `${rel}/`;", "mark": false },
+          { "n": 278, "text": "        for (const key of this.entries.keys()) {", "mark": false, "gutter": "3" },
+          { "n": 279, "text": "          if (key.startsWith(prefix)) {", "mark": true, "gutter": "4" },
+          { "n": 280, "text": "            this.entries.delete(key);", "mark": false },
+          { "n": 281, "text": "          }", "mark": false },
+          { "n": 282, "text": "        }", "mark": false }
+        ]
+      },
+      "terms": [
+        { "term": "guard clauses", "note": [{ "code": "function price(order) {\n  if (!order) return 0;\n  if (order.free) return 0;\n  if (order.staff) return staffPrice(order);\n  return listPrice(order);\n}", "url": "https://example.com/style-guide#guard-clauses", "url_label": "Style guide (example): guard clauses" }] },
+        { "term": "CLAUDE.md", "note": [{ "quote": "CLAUDE.md files are markdown files that give Claude persistent instructions for a project, your personal workflow, or your entire organization.", "url": "https://code.claude.com/docs/en/memory", "url_label": "Claude Code docs" }] }
+      ],
+      "answer_notes": { "forbid": { "forbid": "like a config with limit 3, which flags it", "allow": "like ESLint's default, limit 4, which passes it" } }
+    }
+  ]
+}