chore: move internal docs into docs/ (#62)

Author: johnsoncodehk

.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
 

.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:

COMPLETENESS.md docs/COMPLETENESS.mdCOMPLETENESS.md renamed to docs/COMPLETENESS.md

@@ -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

HIGHLIGHT-ISSUES-SURVEY.md docs/HIGHLIGHT-ISSUES-SURVEY.mdHIGHLIGHT-ISSUES-SURVEY.md renamed to docs/HIGHLIGHT-ISSUES-SURVEY.md

@@ -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)');