Merge pull request #65 from StepenkoAnatoli/fix/single-witness-footgun

A reviewer note is not a citation

Author: StepenkoAnatoli

docs/ARCHITECTURE.md

@@ -423,6 +423,7 @@ each line — is in the ADR named beside it and in
 | The collector's spend gate is a **protected environment whose existence is proven**, because GitHub silently creates an *unprotected* one when a workflow names a missing environment; a missing credential **refuses** rather than falling back to a keyless route | ADR-0033 |
 | A claim's **support is weighed, not just checked**: `corroboration` reports whether a closed unknown rests on one reading, several readings of one source, a **republished copy of one document across hosts** (`mirror`, via `lib/similarity.mjs`), or genuinely distinct documents — it never fails a corpus on its own, because single-sourcing is often the right answer. Rows are **deduped by id first**: `citedIds` returns every `E-##` mention, so prose naming one row twice used to produce it twice, and once grouping folded the duplicate it reported a "republished copy" about a row that was merely mentioned twice | [ADR-0036](adr/0036-the-gate-can-see-single-sourcing.md) |
 | `corroboration` **reports the closest pair it measured** on an `independent` verdict, and does not act on it. The threshold has two measured blind spots, and containment - the obvious repair for the second - ranks a genuinely different pair (0.506) ABOVE a real mirror (0.380) over 2404 pairs, so trying harder would report second sources as copies. The number informs a reviewer; the grade does not move | ADR-0036 |
+| A reviewer note is **not a citation**: `stripReviewNotes` in lib/corpus.mjs removes `[single-witness: ...]` and `[render-reviewed: ...]` before `citedIds` runs. Those notes are prose written INSIDE the same cell the citations are read from, so explaining why no second witness exists - by pointing at a row that demonstrates it - turned that row into a citation, and the unknown read as corroborated while its own note denied it. It caught its author three times in two days across three projects; the guard was right every time and the mechanism was the problem. The raw cell is untouched, because the check that reads the reason needs it | ADR-0038 |
 | A finding a reviewer has **considered and overruled** is recorded, not repeated forever: `[single-witness: …]` in an unknown's Evidence cell and `[render-reviewed: …]` in an evidence row's Finding cell turn a true-but-permanent warning into a pass **that prints the reason**. A reason under 30 characters is named (`single-witness-unreasoned`) rather than obeyed, and a note left on an unknown that has since been corroborated is reported (`single-witness-stale`) so the acknowledgement cannot rot. The render note lives on the ROW because `verifyLedger` hashes the whole capture file — a capture is evidence and stays byte-immutable, a judgement about it is corpus prose | [ADR-0038](adr/0038-a-judgement-the-gate-can-read.md) |
 | The collector lock is exclusive **on a local filesystem, and not promised on a network one**: Node states "the exclusive flag might not work with network file systems", a condition ADR-0020 never carried. Measured 2026-09-22 - 24 racers, 1 winner, 23 EEXIST on win32 - so the guarantee holds where it was tested and nothing detects where it is standing. Evidence: `docs/decisions/2026-09-22-wx-lock/` | ADR-0020 |
 | The SEARCH side is **selectable at dispatch**: collect.yml takes a search_transport input (auto | serpapi | firecrawl-cli) and collect-remote.mjs a matching --search-transport, passed as RESEARCH_KIT_SEARCH_TRANSPORT. ADR-0027 built the ladder and the collector never exposed it, so a dispatched run always took whatever auto-detect picked and two providers could not be compared on one topic through the kit at all. auto becomes the EMPTY STRING, falsy in the ladder, so the default is the previous behaviour exactly | ADR-0027 |

research-kit/README.md

@@ -395,7 +395,7 @@ node research-kit/bin/selftest.mjs            # all of it
 node research-kit/bin/selftest.mjs gate hook  # just these files
 ```
 
-864 tests, offline, no key and no network. The runner **awaits** every test, so `ok` means
+867 tests, offline, no key and no network. The runner **awaits** every test, so `ok` means
 the assertions settled (ADR-0021), and each test is raced against a watchdog
 (`RESEARCH_KIT_TEST_TIMEOUT`, default 60s).
 

research-kit/lib/corpus.mjs

@@ -331,7 +331,7 @@ export function readCorpus(root) {
     .map((r) => ({
       id: r.ID, text: r.Unknown ?? '', why: r[HEADERS.unknowns[2]] ?? '',
       status: (r.Status ?? '').trim().toUpperCase(), evidence: r.Evidence ?? '', line: r.line,
-      cites: citedIds(r.Evidence ?? ''),
+      cites: citedIds(stripReviewNotes(r.Evidence ?? '')),
     }));
 
   const evidence = evidenceTable.rows
@@ -346,7 +346,7 @@ export function readCorpus(root) {
     .map((r) => ({
       id: r.ID, text: r.Subtopic ?? '', why: r[HEADERS.subtopics[2]] ?? '',
       status: (r.Status ?? '').trim().toUpperCase(), coveredBy: r['Covered by'] ?? '', line: r.line,
-      cites: citedIds(r['Covered by'] ?? ''),
+      cites: citedIds(stripReviewNotes(r['Covered by'] ?? '')),
     }));
 
   const sources = sourcesTable.rows.map((r) => ({
@@ -399,6 +399,28 @@ function normalizeRawCell(cell) {
   return value.split(path.sep).join('/');
 }
 
+/**
+ * A reviewer's recorded judgement, removed before citations are counted.
+ *
+ * WHY. `citedIds` returns every `E-##` mention in a cell, and a `[single-witness: ...]`
+ * reason is prose a reviewer writes INSIDE that cell. So explaining why no second witness
+ * exists - by referring to a row that demonstrates it - silently turned that row into a
+ * citation. The unknown then read as corroborated while its own note denied it, and
+ * `single-witness-stale` fired on a corpus that was correct.
+ *
+ * It caught its author three times in two days, across three different projects. The guard
+ * was right every time and the MECHANISM was the problem: a note about evidence is not a
+ * citation of it.
+ *
+ * The raw cell is untouched - `unknown.evidence` still carries the note, because the check
+ * that reads the reason needs it. Only the citation extraction sees the stripped text.
+ */
+const REVIEW_NOTE = /\[(?:single-witness|render-reviewed):[^\]]*\]/gi;
+
+export function stripReviewNotes(text) {
+  return String(text ?? '').replace(REVIEW_NOTE, ' ');
+}
+
 /** Every `E-##` / `U-##` / `D-##` id mentioned in a free-text cell. */
 export function citedIds(text) {
   return [...String(text ?? '').matchAll(/\b([A-Z]+-\d+)\b/g)].map((m) => m[1]);

research-kit/test/checks.test.mjs

@@ -566,3 +566,34 @@ test('capture-completeness: the render review is read from the ROW, never the ca
   assert.ok(findings.some((f) => f.rule === 'partial-render'),
     'a note in the capture front-matter must NOT satisfy the review - the ledger hashes it');
 });
+
+test('a row named INSIDE a single-witness note is not thereby cited', () => {
+  // The footgun this removes. `citedIds` returns every E-## mention in the cell, and the
+  // reason a reviewer writes lives in that same cell - so explaining why no second witness
+  // exists, by pointing at a row that demonstrates it, turned that row into a citation.
+  // The unknown read as corroborated while its own note denied it, and
+  // `single-witness-stale` fired on a corpus that was correct. It caught its author three
+  // times in two days before the mechanism was changed rather than the prose.
+  const dir = withEvidence(makePassingProject(), [
+    '| E-01 | 2026-09-14 | P | https://example.invalid/docs/limits | ten a minute | research/raw/x.md |',
+    '| E-02 | 2026-09-14 | P | https://other.invalid/blog | a blog agreeing | research/raw/y.md |',
+  ], 'E-01 [single-witness: the vendor is the authority on its own limits, and E-02 shows what a third party repeating it is worth]');
+
+  const findings = runCheck('corroboration', snapshot(dir));
+  assert.equal(findings[0].severity, 'pass');
+  assert.equal(findings[0].rule, 'single-witness',
+    'the note mentioned E-02; mentioning is not citing');
+  assert.doesNotMatch(findings[0].detail, /stale/);
+});
+
+test('a row cited OUTSIDE the note still counts', () => {
+  // The other half: stripping must not swallow real citations that happen to sit near one.
+  const dir = withEvidence(makePassingProject(), [
+    '| E-01 | 2026-09-14 | P | https://example.invalid/a | x | research/raw/x.md |',
+    '| E-02 | 2026-09-14 | P | https://other.invalid/b | x | research/raw/y.md |',
+  ], 'E-01 and E-02 both say so');
+
+  const findings = runCheck('corroboration', snapshot(dir));
+  assert.equal(findings[0].severity, 'pass');
+  assert.equal(findings[0].rule, 'independent', 'two genuine citations are still two');
+});

research-kit/test/corpus.test.mjs

@@ -5,7 +5,7 @@ import { PATHS, HEADERS, resolve, writeText, readText } from '../lib/core.mjs';
 import {
   readCorpus, readCaptures, parseTable, parseCapture, splitRow, escapeCell, tableRow,
   repairRowArity, captureEntry, rememberCapture, cacheDecision, traceOf, captureOf,
-  claimOf, sectionOf, appendRow, upsertRow, nextId, citedIds,
+  claimOf, sectionOf, appendRow, upsertRow, nextId, citedIds, stripReviewNotes,
 } from '../lib/corpus.mjs';
 
 describe('corpus');
@@ -162,3 +162,10 @@ test('nextId continues the sequence it is shown', () => {
   assert.equal(nextId('E', [{ id: 'E-01' }, { id: 'E-09' }]), 'E-10');
   assert.equal(nextId('U', [{ id: 'U-3' }]), 'U-04');
 });
+
+test('stripReviewNotes removes the note and nothing else', () => {
+  assert.equal(stripReviewNotes('E-01 [single-witness: see E-02]').includes('E-02'), false);
+  assert.equal(citedIds(stripReviewNotes('E-01 [single-witness: see E-02]')).join(), 'E-01');
+  assert.equal(citedIds(stripReviewNotes('E-01 and E-02')).join(), 'E-01,E-02');
+  assert.equal(stripReviewNotes('a [markdown](http://x) link'), 'a [markdown](http://x) link');
+});