docs(#2705): single-source the legacy ADR range; classify 0174/0656 as mis-padded modern (#2836)

* test(#2705): failing-first regression for single-sourced ADR legacy range

* docs(#2705): single-source the legacy ADR range; classify 0174/0656 as mis-padded modern

* fix(#2705): align README prose with test vocabulary (mis-padded modern; backtick-tolerant range regex) (review)

* docs(changeset): #2705 single-source legacy ADR range

* docs(changeset): backfill #2705 PR number to 2836

* chore: trigger clean CI run (prior run cancelled by rapid backfill push)

tests/adr-index-gate.test.cjs

@@ -9,7 +9,7 @@
  * runtime behavior is the contract.
  */
 
-const { test } = require('node:test');
+const { test, describe } = require('node:test');
 const assert = require('node:assert/strict');
 const fs = require('node:fs');
 const path = require('node:path');
@@ -530,3 +530,86 @@ test('the ADR naming worked example names an ADR file that exists', () => {
     }
   }
 });
+
+// ─── #2705: legacy ADR range is single-sourced and matches disk ─────────────
+//
+// The legacy zero-padded ADR range used to be stated two different ways
+// (contributor-standards.md vs adr/README.md), both wrong. Now adr/README.md is
+// the single authoritative statement and contributor-standards.md references it.
+// The legacy set is the zero-padded ADRs whose numbers do NOT correspond to a
+// same-numbered repository issue; 0174 and 0656 are modern mis-padded files.
+
+describe('#2705: legacy ADR range single-sourced and accurate', () => {
+  const STANDARDS = path.join(REPO_ROOT, 'docs', 'contributor-standards.md');
+  const README = path.join(REPO_ROOT, 'docs', 'adr', 'README.md');
+
+  // Zero-padded ADR files on disk (4-digit prefix).
+  function zeroPaddedAdrFiles() {
+    return fs.readdirSync(ADR_DIR)
+      .filter((f) => /^\d{4}-.*\.md$/.test(f))
+      .map((f) => ({ file: f, num: Number(f.slice(0, 4)) }));
+  }
+
+  // A zero-padded number is "legacy sequential" iff no same-numbered issue-shaped
+  // ADR exists (i.e. the 4-digit number is NOT an issue number reused). 0001–0012
+  // are sequential (collisions on disk corroborate); 0174/0656 match issues.
+  function legacyNumbers() {
+    const all = zeroPaddedAdrFiles();
+    const nums = new Set(all.map((a) => a.num));
+    const legacy = new Set();
+    for (const n of nums) {
+      // Sequential legacy range: numbers 1..12 have intra-range duplicates on disk
+      // (0010 x2, 0011 x3) and do not correspond to same-numbered modern files.
+      if (n >= 1 && n <= 12) legacy.add(n);
+    }
+    return legacy;
+  }
+
+  test('exactly one doc restates the legacy range; the other references it', () => {
+    const readme = fs.readFileSync(README, 'utf8');
+    const standards = fs.readFileSync(STANDARDS, 'utf8');
+    // The authoritative "0001-* through 0012-*" statement lives in README. The
+    // range tokens are backtick-delimited in the prose (`0001-*` through `0012-*`),
+    // so match the digits+through+digits ignoring the backtick/asterisk escapes.
+    assert.match(readme, /0001-\*[^A-Za-z0-9]*through[^A-Za-z0-9]*0012-\*/, 'README must carry the authoritative legacy-range statement');
+    // contributor-standards must NOT restate the range — it must cross-reference README.
+    assert.doesNotMatch(
+      standards,
+      /0001-\*[^A-Za-z0-9]*through[^A-Za-z0-9]*001[12]-\*/,
+      'contributor-standards.md must not restate the legacy range (single-sourced in README); it should reference it',
+    );
+    assert.match(
+      standards,
+      /adr\/README\.md/,
+      'contributor-standards.md must reference docs/adr/README.md for the legacy range',
+    );
+  });
+
+  test('README legacy range matches the on-disk legacy set and excludes mis-padded modern 0174/0656', () => {
+    const readme = fs.readFileSync(README, 'utf8');
+    // The legacy clause must NOT include 0174 (the prior wrong "(and 0174-*)" clause).
+    assert.doesNotMatch(
+      readme,
+      /through 0012-\* \(and 0174-\*\)/,
+      'README must not classify 0174 as legacy residue (it is a modern mis-padded ADR)',
+    );
+    // The legacy set on disk (0001–0012) all exist as zero-padded files.
+    const legacy = legacyNumbers();
+    for (const n of legacy) {
+      const pad = String(n).padStart(4, '0');
+      const matches = fs.readdirSync(ADR_DIR).filter((f) => f.startsWith(`${pad}-`));
+      assert.ok(matches.length > 0, `legacy ADR ${pad}-* must exist on disk`);
+    }
+  });
+
+  test('README identifies 0174 and 0656 as mis-padded modern ADRs', () => {
+    const readme = fs.readFileSync(README, 'utf8');
+    assert.match(readme, /0174/, 'README must mention 0174');
+    assert.match(readme, /0656/, 'README must mention 0656');
+    assert.match(
+      readme,
+      /modern.*mis-padded|mis-padded.*modern/i,
+      'README must identify the zero-padded modern ADRs as mis-padded modern files, not legacy residue',
+    );
+  });
+});