fix(docs-check): require an actual markdown link for index coverage

scripts/check-docs.mjs

@@ -17,15 +17,26 @@ const failures = [];
 const rate = (pass, total) => (total === 0 ? 1 : pass / total);
 
 // ---- 1. Index coverage: every doc in the four categories is indexed. ----
-const indexText = readFileSync(join(root, "docs/README.md"), "utf8");
+const indexPath = join(root, "docs/README.md");
+// Strip fenced code blocks and HTML comments so example/commented-out links
+// aren't mistaken for real links.
+const indexText = readFileSync(indexPath, "utf8")
+  .replace(/```[\s\S]*?```/g, "")
+  .replace(/<!--[\s\S]*?-->/g, "");
+const indexedTargets = new Set();
+for (const m of indexText.matchAll(/\[[^\]]*\]\(([^)\s]+)\)/g)) {
+  const target = m[1];
+  if (/^[a-z][a-z+.-]*:/i.test(target) || target.startsWith("#")) continue;
+  indexedTargets.add(resolve(dirname(indexPath), target.split("#")[0]));
+}
 const categories = ["adr", "design", "specs", "plans"];
 let docsTotal = 0;
 let docsIndexed = 0;
 for (const cat of categories) {
   for (const name of readdirSync(join(root, "docs", cat))) {
     if (!name.endsWith(".md") || name === "TEMPLATE.md") continue;
     docsTotal++;
-    if (indexText.includes(`${cat}/${name}`)) docsIndexed++;
+    if (indexedTargets.has(join(root, "docs", cat, name))) docsIndexed++;
     else failures.push(`index: docs/${cat}/${name} has no line in docs/README.md`);
   }
 }

test/docs-integrity.test.mjs

@@ -59,6 +59,48 @@ test("docs gate accepts cross-skill links that stay in the synced skills tree",
   assert.match(stdout, /ok   link_integrity: 1\.000/);
 });
 
+test("docs gate rejects index coverage from a bare document path without a markdown link", async () => {
+  const root = await createFixture();
+  await writeFile(path.join(root, "docs/adr/example.md"), "# Example\n");
+  await writeFile(
+    path.join(root, "docs/README.md"),
+    "[Metric](specs/pr-acceptance-metric.md)\n\nSee adr/example.md for details.\n",
+  );
+
+  await assert.rejects(
+    runDocsGate(root),
+    (error) =>
+      error.stderr.includes("index: docs/adr/example.md has no line in docs/README.md"),
+  );
+});
+
+test("docs gate rejects index coverage from a link inside an HTML comment", async () => {
+  const root = await createFixture();
+  await writeFile(path.join(root, "docs/adr/example.md"), "# Example\n");
+  await writeFile(
+    path.join(root, "docs/README.md"),
+    "[Metric](specs/pr-acceptance-metric.md)\n\n<!-- [Example](adr/example.md) -->\n",
+  );
+
+  await assert.rejects(
+    runDocsGate(root),
+    (error) =>
+      error.stderr.includes("index: docs/adr/example.md has no line in docs/README.md"),
+  );
+});
+
+test("docs gate accepts index coverage from an actual relative markdown link", async () => {
+  const root = await createFixture();
+  await writeFile(path.join(root, "docs/adr/example.md"), "# Example\n");
+  await writeFile(
+    path.join(root, "docs/README.md"),
+    "[Metric](specs/pr-acceptance-metric.md)\n[Example](adr/example.md)\n",
+  );
+
+  const { stdout } = await runDocsGate(root);
+  assert.match(stdout, /ok   docs_index_coverage: 1\.000/);
+});
+
 async function createFixture() {
   const root = await mkdtemp(path.join(os.tmpdir(), "core-docs-gate-"));
   for (const dir of [