johnsoncodehk · johnsoncodehk · Jul 11, 2026 · Jul 11, 2026 · Jul 11, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -45,9 +45,9 @@ jobs:
 
       # Every correctness GATE through ONE runner — sanity / agnostic / conformance /
       # highlighter / vue / yaml / the generative scope≡role check / the gap-ledger selftest
-      # + --check (stale KNOWN-GAPS.md fails). One ✓/✗ summary, one exit code. The comparative
+      # + --check (stale docs/KNOWN-GAPS.md fails). One ✓/✗ summary, one exit code. The comparative
       # METRICS (scope-gap / src-coverage) and BENCH tools need the external TS corpus / VS Code
-      # grammars and run in the readme-bench workflow, not here. See TESTING.md for the taxonomy.
+      # grammars and run in the readme-bench workflow, not here. See docs/TESTING.md for the taxonomy.
       - name: Test
         run: npm run check
 

diff --git a/.github/workflows/gap-issues.yml b/.github/workflows/gap-issues.yml
@@ -1,4 +1,4 @@
-# Reconcile GitHub issues from the gap ledger (KNOWN-GAPS.md → issues), idempotently.
+# Reconcile GitHub issues from the gap ledger (docs/KNOWN-GAPS.md → issues), idempotently.
 # Runs when the ledger CHANGES on master (a gap appeared or was fixed) and on manual dispatch.
 # The deterministic ledger is the source of truth; this only PROJECTS it: opens an issue for a new
 # gap, auto-closes the issue when its fingerprint leaves the ledger. See test/gap-issues.ts.
@@ -7,7 +7,7 @@ name: gap-ledger-issues
 on:
   push:
     branches: [master]
-    paths: ['KNOWN-GAPS.md']
+    paths: ['docs/KNOWN-GAPS.md']
   workflow_dispatch: {}
 
 permissions:

diff --git a/COMPLETENESS.md → docs/COMPLETENESS.md b/COMPLETENESS.md → docs/COMPLETENESS.md
diff --git a/HIGHLIGHT-ISSUES-SURVEY.md → docs/HIGHLIGHT-ISSUES-SURVEY.md b/HIGHLIGHT-ISSUES-SURVEY.md → docs/HIGHLIGHT-ISSUES-SURVEY.md
diff --git a/KNOWN-GAPS.md → docs/KNOWN-GAPS.md b/KNOWN-GAPS.md → docs/KNOWN-GAPS.md
diff --git a/ROADMAP.md → docs/ROADMAP.md b/ROADMAP.md → docs/ROADMAP.md
diff --git a/TESTING.md → docs/TESTING.md b/TESTING.md → docs/TESTING.md
diff --git a/TOTAL-PARSING.md → docs/TOTAL-PARSING.md b/TOTAL-PARSING.md → docs/TOTAL-PARSING.md
diff --git a/test/check.ts b/test/check.ts
@@ -2,10 +2,10 @@
 //  check.ts — the SINGLE gate runner. Runs every correctness GATE as a subprocess and
 //  prints ONE ✓/✗ summary, exiting non-zero if any fails. `npm run check` answers
 //  "is the repo healthy?" in one command + one output — instead of running a dozen
-//  scripts with a dozen output formats. See TESTING.md for the report taxonomy
+//  scripts with a dozen output formats. See docs/TESTING.md for the report taxonomy
 //  (gate / metric / ledger / bench); this runs the GATE tier (the CI-blocking pass/fail
 //  checks that need no external corpus). Metrics live in the README coverage table
-//  (`npm run coverage:table`), findings in the gap ledger (`KNOWN-GAPS.md`).
+//  (`npm run coverage:table`), findings in the gap ledger (`docs/KNOWN-GAPS.md`).
 //
 //  Assumes the generated grammars are current (`npm run gen`), as CI does before this.
 //  Run:  node test/check.ts            # all gates

diff --git a/test/gap-issues.ts b/test/gap-issues.ts
@@ -1,5 +1,5 @@
 // ─────────────────────────────────────────────────────────────────────────────
-//  gap-issues.ts — RECONCILE GitHub issues from the gap ledger (KNOWN-GAPS.md).
+//  gap-issues.ts — RECONCILE GitHub issues from the gap ledger (docs/KNOWN-GAPS.md).
 //
 //  The deterministic ledger (test/gap-ledger.ts) is the SOURCE OF TRUTH — a committed,
 //  fingerprinted list of valid-input flat-highlighter divergences the generative
@@ -14,7 +14,7 @@
 //  Because the fingerprint is content-derived and the ledger is deterministic, this is a
 //  pure function of (ledger, open issues) → it never spams and auto-closes on fix — the
 //  OSS-Fuzz model. The CI workflow (.github/workflows/gap-issues.yml) runs it on a push
-//  that changes KNOWN-GAPS.md (and on manual dispatch).
+//  that changes docs/KNOWN-GAPS.md (and on manual dispatch).
 //
 //  Run:  node test/gap-issues.ts            # reconcile live (needs `gh` auth / GH_TOKEN)
 //        node test/gap-issues.ts --dry-run  # print the plan, touch nothing
@@ -23,7 +23,7 @@ import { readFileSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 
 const DRY = process.argv.includes('--dry-run');
-const LEDGER = 'KNOWN-GAPS.md';
+const LEDGER = 'docs/KNOWN-GAPS.md';
 const LABEL = 'gap-ledger';
 const marker = (id: string) => `<!-- gap-ledger:${id} -->`;
 const MARKER_RE = /<!-- gap-ledger:([0-9a-f]+) -->/;
@@ -63,7 +63,7 @@ function openIssues(): Map<string, number> {
 function title(g: Gap): string { return `[gap-ledger] ${g.language}: ${g.repro.replace(/\n/g, '\\n').slice(0, 50)}`; }
 function body(g: Gap): string {
   return [
-    'Auto-filed by the **gap ledger** (`test/gap-ledger.ts` → `KNOWN-GAPS.md`). The generative scope≡role',
+    'Auto-filed by the **gap ledger** (`test/gap-ledger.ts` → `docs/KNOWN-GAPS.md`). The generative scope≡role',
     'check found a flat-highlighter divergence from the Monogram parser on **valid input** — the floor-blind',
     'class the corpus-bound scope-gap metric is blind to. **This issue auto-CLOSES when the gap leaves the',
     'ledger** (i.e. when the highlighter is fixed and the next ledger regen drops it).',
@@ -102,6 +102,6 @@ for (const g of toOpen) {
 }
 for (const [id, num] of toClose) {
   console.log(`  - CLOSE #${num}  (gap ${id} no longer in the ledger — resolved)`);
-  if (!DRY) gh(['issue', 'close', String(num), '--comment', `Resolved — gap \`${id}\` is no longer in the ledger (\`KNOWN-GAPS.md\`); the highlighter no longer diverges here. Auto-closed by \`test/gap-issues.ts\`.`]);
+  if (!DRY) gh(['issue', 'close', String(num), '--comment', `Resolved — gap \`${id}\` is no longer in the ledger (\`docs/KNOWN-GAPS.md\`); the highlighter no longer diverges here. Auto-closed by \`test/gap-issues.ts\`.`]);
 }
 if (!toOpen.length && !toClose.length) console.log('  (in sync — nothing to do)');
diff --git a/test/gap-ledger.ts b/test/gap-ledger.ts
@@ -23,19 +23,19 @@
 //       it is DROPPED from the gap list (its count is reported, not listed).
 //    4. FINGERPRINT — a stable id = hash(language, normalized repro, role, bucket),
 //       so the same gap keeps the same id across commits.
-//    5. EMIT — a sorted KNOWN-GAPS.md (committed artifact): per gap, the language,
+//    5. EMIT — a sorted docs/KNOWN-GAPS.md (committed artifact): per gap, the language,
 //       escaped minimal repro, role-vs-scope (want vs got), fingerprint, and a
 //       machine-readable JSON block.
 //
 //  DETERMINISM is the whole point (a commit-trackable ledger): two runs produce a
-//  BYTE-IDENTICAL KNOWN-GAPS.md. The generator is a pure function of the grammar
+//  BYTE-IDENTICAL docs/KNOWN-GAPS.md. The generator is a pure function of the grammar
 //  (no seed), ddmin is deterministic, the oracle is deterministic, and the hash is
 //  content-only — so nothing varies run-to-run.
 //
 //  Run (bare node):
 //    node test/gap-ledger.ts            # print the ledger to stdout (don't write)
-//    node test/gap-ledger.ts --write    # (re)write KNOWN-GAPS.md
-//    node test/gap-ledger.ts --check    # fail if KNOWN-GAPS.md is stale (CI guard)
+//    node test/gap-ledger.ts --write    # (re)write docs/KNOWN-GAPS.md
+//    node test/gap-ledger.ts --check    # fail if docs/KNOWN-GAPS.md is stale (CI guard)
 //    node test/gap-ledger.ts yaml       # one language
 // ─────────────────────────────────────────────────────────────────────────────
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';
@@ -346,7 +346,7 @@ async function main(): Promise<void> {
   for (const r of results) console.error(`    ${r.name}: ${r.kept.length} kept · ${r.droppedOverAccept} dropped (over-accept) · ${r.discovered} distinct divergence(s)`);
   console.error(`  TOTAL: ${allGaps.length} gaps · ${droppedTotal} dropped over-accepts`);
 
-  const OUT = 'KNOWN-GAPS.md';
+  const OUT = 'docs/KNOWN-GAPS.md';
   if (CHECK) {
     const existing = existsSync(OUT) ? readFileSync(OUT, 'utf8') : '';
     if (existing !== md) { console.error(`\n${OUT} is STALE — run \`node test/gap-ledger.ts --write\`.`); process.exit(1); }

diff --git a/test/tm-completeness.ts b/test/tm-completeness.ts
@@ -34,7 +34,7 @@
 //  Run (bare node):
 //    node test/tm-completeness.ts            # print the report
 //    node test/tm-completeness.ts --check    # CI gate: fail on any open gap or stale ledger
-//    node test/tm-completeness.ts --write     # (re)write COMPLETENESS.md ledger table
+//    node test/tm-completeness.ts --write     # (re)write docs/COMPLETENESS.md ledger table
 // ─────────────────────────────────────────────────────────────────────────────
 import {
   token, rule, defineGrammar, sep, opt, many, many1, alt, exclude, not, reservableNot,
@@ -767,7 +767,7 @@ function ledgerRow(name: string, g: CstGrammar, r: ReachResult, tc: TokenCensus,
   };
 }
 
-// the auto-generated ledger block (a region in COMPLETENESS.md, like KNOWN-GAPS.md / the README issue table)
+// the auto-generated ledger block (a region in docs/COMPLETENESS.md, like docs/KNOWN-GAPS.md / the README issue table)
 function renderLedger(rows: LedgerRow[]): string {
   const L: string[] = [];
   L.push('<!-- COMPLETENESS-LEDGER:START — auto-generated by `node test/tm-completeness.ts --write`; do not edit by hand. -->');
@@ -795,7 +795,7 @@ function renderLedger(rows: LedgerRow[]): string {
   return L.join('\n');
 }
 
-const LEDGER_FILE = 'COMPLETENESS.md';
+const LEDGER_FILE = 'docs/COMPLETENESS.md';
 function spliceRegion(file: string, block: string): { changed: boolean; full: string } {
   const start = '<!-- COMPLETENESS-LEDGER:START', end = '<!-- COMPLETENESS-LEDGER:END -->';
   const cur = existsSync(file) ? readFileSync(file, 'utf8') : '';

diff --git a/test/tm-mutation.ts b/test/tm-mutation.ts
@@ -20,7 +20,7 @@
 //      reordered) are EXPECTED to slip past the structural detectors — they are caught,
 //      if at all, only by a differential WITNESS (a paint change on a targeted input).
 //      Survivors here are the detector's MEASURED blind spots, reported not failed: they
-//      are the honest boundary COMPLETENESS.md draws, made empirical.
+//      are the honest boundary docs/COMPLETENESS.md draws, made empirical.
 //
 //  Run:  node test/tm-mutation.ts
 // ─────────────────────────────────────────────────────────────────────────────
@@ -202,7 +202,7 @@ async function main(): Promise<void> {
   const failures = [...presenceSurvivors.map(r => `presence SURVIVED: ${r.grammar} — ${r.label}`),
     ...falseAlarms.map(r => `FALSE ALARM on equivalent mutant: ${r.grammar} — ${r.label}`)];
   if (failures.length) { console.log('\n✗ detector defect(s):'); for (const f of failures) console.log(`    - ${f}`); process.exit(1); }
-  console.log(`\n✓ every presence gap killed, no false alarms; correctness/ordering blind spots measured = ${corrOrderSurvivors.length} (the boundary COMPLETENESS.md states).`);
+  console.log(`\n✓ every presence gap killed, no false alarms; correctness/ordering blind spots measured = ${corrOrderSurvivors.length} (the boundary docs/COMPLETENESS.md states).`);
   void createParser; void buildRoleMap; void leafRoles; void generateInputs;
 }