paperlint 14.2.0 → 14.4.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?: {

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.2.0",
+  "version": "14.4.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:dce0979d7f187ae7 compiled from skills/build-label-page/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:ed201d81c5934675 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
 
@@ -57,7 +57,7 @@ building. In one line each:
    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
+3. **An item is done only when every question on it is answered.** The card asks 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
@@ -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

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

@@ -68,7 +68,7 @@ building. In one line each:
    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
+3. **An item is done only when every question on it is answered.** The card asks 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
@@ -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

package/skills/build-label-page/references/checklist.md

@@ -41,8 +41,8 @@ filter works in any frame, because the next thing to answer is simply the first
 
 ## 3. An item counts as done only when every question on it is answered
 
-**Do.** Done means all questions answered. The card shows which one is missing ("Still needs:
-boundary"). The progress counter counts complete items only, so "7 of 12" means 7 items with every
+**Do.** Done means all questions answered. The card asks the one still missing in its question
+box, and "Next unanswered" lists what each item still needs. The progress counter counts complete items only, so "7 of 12" means 7 items with every
 question answered. A group is finished when all its items are and its familiarity question (rule 5)
 is answered.
 
@@ -50,7 +50,7 @@ is answered.
 and surfaces weeks later as a gap in the data. A counter that counts partial items reports progress
 that the analysis cannot use.
 
-**Check.** Answer one question of a two-question item: the counter stays put and the card names the
+**Check.** Answer one question of a two-question item: the counter stays put and the card asks the
 other question.
 
 ## 4. Blind: the page tells the labeller nothing about the answer or the source

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
@@ -155,24 +155,61 @@ Any card may carry these blocks, on any `kind`, and each one is optional. The pa
 }
 ```
 
-- **Order on the card.** The card shows, in this order:
-  1. its place (`labels.place`);
-  2. the body, on a `labels.body` row when that label is set;
-  3. the repeat sentence;
-  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.
-
-  The question therefore sits right under the code it names.
-
-- **`situation`**: `{summary, question}`.
-  - `summary` is one sentence above the excerpt.
+- **Order on the card.** Each card is a bordered panel, with wide space before the next. It shows, in this order:
+  1. its place (`labels.place`), then its `title`;
+  2. the `quote` and its source;
+  3. the body, on a `labels.body` row when that label is set;
+  4. the repeat sentence;
+  5. the older fields (`code`, `unit`, `rules`, `readings`, `file`, `context`);
+  6. the situation's summary;
+  7. the excerpt;
+  8. **the question box**: the question, its answers with their `answer_notes`, and the wait bar of `min_seconds`;
+  9. the reason box of an answer with `ask_why`, then the status line. The status line never lists
+     what is missing (the question box asks it): it shows «Saved <time>», «Saving…», why a save did not happen, or nothing;
+  10. `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).
+
+  A card is read once, top to bottom: the words asked about, the code they are about, the question
+  right under that code, its answers. A card without a `quote` has the same order without step 2.
+
+- **`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 card, above its code, `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 +226,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 +239,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: ».

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" } }
+    }
+  ]
+}