From 7cf943cf5fdff5e846d30e5510e2c73e89887f8c Mon Sep 17 00:00:00 2001
From: tzhouam <tzhouam@connect.ust.hk>
Date: Wed, 30 Sep 2026 17:01:41 +0800
Subject: [PATCH 1/4] Let L1 accept new-directory indexes in bootstrap mode,
 and check index links
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

kb init (design v3 §9.2/§9.3) must create repos/<repo>/_index.md and
components/<group>/_index.md, which check_changeset refuses outright
("index files are never created or deleted by a change set").

check_changeset gains a keyword `bootstrap` (default False, behaviour
unchanged). When set it relaxes exactly two rules:
- an _index.md may be created in a directory that had no files at base;
  it must link every page and child-directory index in its directory, and an
  existing parent index must link it. Creating an index in an existing
  directory and deleting any index stay refused.
- the shared knowledge/repos/_index.md may be modified (listing a new
  repository); adding or deleting it stays refused.

check_index_links(base, head) is the init-side check for index edits that L1
only classifies as prose (tables, cross-directory links): links a change adds
must resolve inside the knowledge tree, a changed index keeps its base links,
and every new page or child index is linked from its parent index.

A test pins that only kb_service/init_stages.py (kb init, a later PR) may pass
bootstrap=True.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 doc/architecture/SPEC/knowledge_service.md    |   5 +
 doc/architecture/SPEC/knowledge_service/l1.md |  32 +-
 .../knowledge_service/l1.py                   | 259 ++++++++++++++-
 test/test_kb_init_l1.py                       | 306 ++++++++++++++++++
 4 files changed, 594 insertions(+), 8 deletions(-)
 create mode 100644 test/test_kb_init_l1.py

diff --git a/doc/architecture/SPEC/knowledge_service.md b/doc/architecture/SPEC/knowledge_service.md
index bf4c3261..b0fd0262 100644
--- a/doc/architecture/SPEC/knowledge_service.md
+++ b/doc/architecture/SPEC/knowledge_service.md
@@ -48,6 +48,11 @@ library only.
 ## 2026-09-28 T1 索引修复
 L1 的索引检查允许为目录中已存在但未列入索引的页面补链接（巡检 T1 修复），新页面仍必须被链接。
 
+## 2026-09-30 kb init 的 L1 bootstrap 模式
+`l1.check_changeset(..., bootstrap=)` 只供 `kb init`（`kb_service/init_stages.py`）：允许在新目录新建
+`_index.md`、修改共享的 `repos/_index.md`；`l1.check_index_links(base, head)` 检查 init 改动的索引链接。
+细节见 [l1](knowledge_service/l1.md)。服务门禁与发布器从不传 `bootstrap`。
+
 ## 2026-09-28 知识验证器（v8：发布器本地门禁）
 `gate_verifier.verify_change(ctx, pr=, head_sha=, pre=, post=, final=, effective_base=, verdict=)` 是发布器本地门禁
 （`kb_service.local_gate`）在合并前与合并后运行的检查；v7 的仓库端 `kb-gate` 工作流、`.github/kb-gate/` 验证包、
diff --git a/doc/architecture/SPEC/knowledge_service/l1.md b/doc/architecture/SPEC/knowledge_service/l1.md
index 3fe1f133..ebc863fa 100644
--- a/doc/architecture/SPEC/knowledge_service/l1.md
+++ b/doc/architecture/SPEC/knowledge_service/l1.md
@@ -1,8 +1,8 @@
 # knowledge_service/l1.py —— 规范
 
-<!-- verified-against: 2026-09-29 -->
+<!-- verified-against: 2026-09-30 -->
 
-`LOC ~420 · 知识质量门的确定性一层（L1） · refactor-status: stable`
+`LOC ~600 · 知识质量门的确定性一层（L1） · refactor-status: stable`
 
 ## 职责
 - `check_tree(files)`：尾注合法、supersede 双向一致、tombstone ID 未被复用、
@@ -24,11 +24,39 @@
     同目录 `_index.md` 出现。
   - purge 时序：tombstone 的 `purged_at` 不得等于该规则的 `retired_at`；传入可信的
     `release` 时 `purged_at` 必须等于它。
+- `check_changeset(..., bootstrap=)`：仅供 `kb init`（唯一允许的调用方是
+  `kb_service/init_stages.py`，测试扫描源码钉住）。只放宽两条：
+  - 新目录（base 中该目录下没有任何文件）可以**新建** `_index.md`，产出一个 prose 块；新索引必须
+    链接本目录的每个页面和每个子目录的 `_index.md`，已存在的父目录索引必须链接它
+    （父索引也是本次新建时由父索引自己报告）。在已有目录新建索引、删除索引仍然拒绝。
+  - 共享的 `knowledge/repos/_index.md` 可以被**修改**（登记新仓库），新增/删除仍拒绝。
+  其余规则（尾注、frontmatter、`sources`、白名单其余部分、保护规则）不变；默认 `False`
+  时行为与原来逐字节一致。
+- `check_index_links(base, head)`：init 侧的索引链接检查（索引改成表格或跨目录链接时
+  L1 只把它当 prose 块）。对每个新增或改动的 `_index.md`：本次新增的相对链接必须解析到
+  head 中的文件或目录、不得逃出知识树（issue `index_link_broken` / `index_link_escapes`；
+  URL、纯锚点不算链接，base 已有的链接不重新判定——有些指向 `doc/`）；链接识别行内链接
+  （可带 `<尖括号>` 目标与 `"标题"`/`'标题'`/`(标题)`）和引用式链接（定义 `[r]: target` 只在被 `[文本][r]`、`[r][]`、`[r]` 实际使用时才算链接，
+  标签不区分大小写），其余无法解析
+  的 `](` 一律报 `index_link_unparsed`，不静默跳过；改动的索引不得丢掉
+  base 的链接（`index_link_dropped`）；head 中每个新页面、新子目录索引都必须被父索引链接
+  （`index_unlinked`，知识树根没有索引）。
+  - 代码处理按方向 fail-closed，不实现 Markdown 解析器：解析/逃逸/无法解析检查看**所有**像链接的
+    文本（藏在代码里的也查）；“是否链接了新页面”“是否保留了原链接”只认**确定可见**的链接——它之前
+    （含本行）没有任何类围栏行（容器前缀后的 ```` ``` ```` / `~~~`），且在所在块（段落、列表项、标题、
+    引用，或真表格——空行后开始、第二行是分隔行——正文行的单元格，代码段跨不过单元格）内它之前没有
+    反引号。引用式链接：解析检查查该标签的**每一个**定义（哪个生效取决于哪个在代码里）；导航只认只有
+    一个定义且该定义确定可见的标签。“保留”也 fail-closed：base 的链接只有在 head 中确定可见，或它所在的
+    每个块在 head 中原样存在、且该块之前的类围栏行也相同时，才算保留；否则报 `index_link_dropped`（把链接挪进代码 =
+    丢链接）。
+    在真实知识树的 142 个索引上逐一追加一行，无误报。
 
 ## 不变量
 纯函数；标准库 + PyYAML + `lifecycle`/`ops`，验证包原样携带。段比较忽略尾部空行
 （追加段落时前一段多出的分隔空行不算改动）。
 
 ## 测试
+`test_kb_init_l1.py`（bootstrap 新目录索引、父子链接、已有目录仍拒绝、删除拒绝、`repos/_index.md`
+只允许修改、链接检查各类 issue、仅 `init_stages.py` 可传 `bootstrap=True`）；
 `test_knowledge_ops_l1.py`（伪造的 sources/frontmatter/删除 active 规则/重复 ID、白名单与
 模式、prose 分块、外部引用、真实知识树上执行各类操作后两个既有校验器均通过）。
diff --git a/src/infermatrix_copilot/knowledge_service/l1.py b/src/infermatrix_copilot/knowledge_service/l1.py
index bb0bd49a..eaa5e068 100644
--- a/src/infermatrix_copilot/knowledge_service/l1.py
+++ b/src/infermatrix_copilot/knowledge_service/l1.py
@@ -18,6 +18,14 @@
                   pages, tombstones. Recomputed here; a mismatch is an issue,
                   never a block a verdict could cover.
 
+``check_changeset`` with ``bootstrap`` set is for ``kb init`` only (the one
+allowed caller is ``kb_service/init_stages.py``; a test pins that). It relaxes
+exactly two rules so a repository's knowledge can be created: an ``_index.md``
+may be created in a directory that had no files before, and the shared
+``repos/_index.md`` may be edited to list a new repository.
+``check_index_links(base, head)`` is the init-side link check for the index
+edits that bootstrap produces.
+
 Standard library + PyYAML + ``lifecycle``/``ops`` only.
 """
 
@@ -25,6 +33,7 @@
 
 import hashlib
 import json
+import posixpath
 import re
 from dataclasses import dataclass
 from pathlib import PurePosixPath
@@ -48,6 +57,87 @@
 _DENY = re.compile(r"knowledge/(?:skills|tools|\.claude)/|knowledge/[^/]+$")
 _REGULAR_MODE = "100644"
 _INDEX_LINE = re.compile(r"- \[[^\]\n]+\]\((?P<file>[^)/\s]+\.md)\)")
+# bootstrap only: the shared list of repositories, edited to link a new one
+_REPOS_INDEX = "knowledge/repos/_index.md"
+# inline links (optional <angle> target and "title" / 'title' / (title)) and
+# reference definitions; any other "](" is unparsed and refused by the link check
+_LINK_TITLE = r"""(?:\s+(?:"[^"\n]*"|'[^'\n]*'|\([^)\n]*\)))?"""
+_MD_LINK = re.compile(r"\]\(\s*(?:<(?P<angle>[^>\n]*)>|(?P<target>[^)\s]+))" + _LINK_TITLE + r"\s*\)")
+_MD_REF = re.compile(r"(?m)^ {0,3}\[(?P<label>[^\]\n]+)\]:[ \t]*(?:<(?P<angle>[^>\n]*)>|(?P<target>\S+))"
+                     + _LINK_TITLE + r"[ \t]*$")
+# a reference definition counts only where it is used: [text][label], [label][], [label]
+_REF_FULL = re.compile(r"\[(?P<text>[^\]\n]+)\]\[(?P<label>[^\]\n]*)\]")
+_REF_SHORT = re.compile(r"\[(?P<label>[^\]\n]+)\](?![(\[:])")
+# Link visibility, fail-closed. No Markdown parser is complete, so the checks
+# split by direction: every link-like text counts when checking that links
+# resolve (a link "hidden in code" is still checked), and only a CERTAINLY
+# visible link counts as navigation (for "is the page linked" and "was the link
+# kept"). Certainly visible: no fence-like line at or before it, and no
+# backtick before it in its block (paragraph, list item, heading, quote, or
+# table cell, which a code span cannot cross).
+_FENCE_LIKE = re.compile(r"^[\s>*+\-\d.)]*(?:`{3,}|~{3,})")
+_BLOCK_START = re.compile(r" {0,3}(?:#{1,6}(?:\s|$)|[-*+]\s|\d{1,9}[.)]\s|>)")
+_TABLE_ROW = re.compile(r" {0,3}\|")
+_TABLE_DELIM = re.compile(r" {0,3}\|?\s*:?-+:?\s*(?:\|\s*:?-+:?\s*)*\|?\s*")
+
+
+def _table_body_row(lines: list[str], k: int) -> bool:
+    """``lines[k]`` is a body row of a pipe table: a run of pipe lines that
+    starts after a blank line (a table does not interrupt a paragraph), whose
+    second line is a delimiter row, and ``lines[k]`` comes after it."""
+    if not _TABLE_ROW.match(lines[k]):
+        return False
+    first = k
+    while first > 0 and _TABLE_ROW.match(lines[first - 1]):
+        first -= 1
+    return (k >= first + 2 and (first == 0 or not lines[first - 1].strip())
+            and _TABLE_DELIM.fullmatch(lines[first + 1]) is not None)
+
+
+def _certainly_visible(text: str, pos: int) -> bool:
+    line_start = text.rfind("\n", 0, pos) + 1
+    line_end = text.find("\n", pos)
+    line_end = len(text) if line_end < 0 else line_end
+    lines = text[:line_end].split("\n")
+    if any(_FENCE_LIKE.match(line) for line in lines):
+        return False
+    line = lines[-1]
+    if _table_body_row(lines, len(lines) - 1):
+        cell_start = max((m.end() for m in re.finditer(r"(?<!\\)\|", line[:pos - line_start])), default=0)
+        return "`" not in line[cell_start:pos - line_start]
+    start = len(lines) - 1  # walk back to the first line of the block
+    while start > 0 and not _BLOCK_START.match(lines[start]) and lines[start - 1].strip():
+        start -= 1
+    block_start = sum(len(item) + 1 for item in lines[:start])
+    return "`" not in text[block_start:pos]
+
+
+def _block_span(text: str, pos: int) -> tuple[int, int]:
+    """Offsets of the whole block holding ``pos`` (a table body row is its
+    own block)."""
+    lines = text.split("\n")
+    k = text.count("\n", 0, pos)
+    start = end = k
+    if not _table_body_row(lines, k):
+        while start > 0 and not _BLOCK_START.match(lines[start]) and lines[start - 1].strip():
+            start -= 1
+        while end + 1 < len(lines) and lines[end + 1].strip() \
+                and not _BLOCK_START.match(lines[end + 1]) and not _table_body_row(lines, end + 1):
+            end += 1
+    offset = sum(len(line) + 1 for line in lines[:start])
+    return offset, offset + len("\n".join(lines[start:end + 1]))
+
+
+def _block_context(text: str, pos: int) -> tuple[str, tuple[str, ...]]:
+    """The block holding ``pos`` and the fence-like lines before it: the same
+    block after the same fences renders the same way."""
+    start, end = _block_span(text, pos)
+    return text[start:end], tuple(line for line in text[:start].split("\n") if _FENCE_LIKE.match(line))
+
+
+def _contexts(text: str) -> set[tuple[str, tuple[str, ...]]]:
+    starts = [0] + [m.end() for m in re.finditer("\n", text)]
+    return {_block_context(text, pos) for pos in starts}
 
 
 @dataclass(frozen=True)
@@ -188,11 +278,13 @@ def _check_routes(path: str, text: str, files: Mapping[str, str]) -> list[Issue]
 
 # -- change-set level ----------------------------------------------------------
 
-def _whitelist_issues(changes: Iterable[Change]) -> list[Issue]:
+def _whitelist_issues(changes: Iterable[Change], bootstrap: bool = False) -> list[Issue]:
     issues = []
     for change in changes:
         path = change.path
-        if not path.startswith(KNOWLEDGE_PREFIX) or _DENY.match(path) \
+        if bootstrap and path == _REPOS_INDEX and change.status == "M":
+            pass  # a new repository is listed in the shared index
+        elif not path.startswith(KNOWLEDGE_PREFIX) or _DENY.match(path) \
                 or not any(p.fullmatch(path) for p in _WHITELIST):
             issues.append(Issue("path_not_whitelisted", path, "only knowledge rule/guide pages, _routes.yaml and _tombstones.yaml auto-merge"))
             continue
@@ -327,7 +419,11 @@ def _classify_page(path: str, base_text: str | None, head_text: str | None,
 
 def _index_mechanical(path: str, base_text: str | None, head_text: str | None,
                       new_pages: set[str], issues: list[Issue], blocks: list[Block],
-                      head: Mapping[str, str] | None = None) -> None:
+                      head: Mapping[str, str] | None = None, *,
+                      base: Mapping[str, str] | None = None, bootstrap: bool = False) -> None:
+    if bootstrap and base_text is None and head_text is not None and head is not None:
+        _index_created(path, base or {}, head, issues, blocks)
+        return
     if base_text is None or head_text is None:
         issues.append(Issue("index_added_or_deleted", path, "index files are never created or deleted by a change set"))
         return
@@ -361,6 +457,155 @@ def _index_mechanical(path: str, base_text: str | None, head_text: str | None,
                             f"index lines must cover new pages {expected_new} and only link unlisted pages; got {files}"))
 
 
+def _link_occurrences(directory: str, text: str, *, certain: bool = False
+                      ) -> list[tuple[str, str, tuple[int, ...]]]:
+    """Relative links of an index as (written target without anchor, resolved
+    knowledge-relative path, positions of the link text and, for a reference,
+    its definition). URLs and anchor-only links are not targets; a link that
+    leaves the knowledge tree resolves to a path starting ``..``. ``certain``
+    keeps only links that are certainly visible (see above); a reference
+    counts only where it is used."""
+    def target_of(match) -> str:
+        return match.group("angle") if match.group("angle") is not None else match.group("target")
+
+    def keep(pos: int) -> bool:
+        return not certain or _certainly_visible(text, pos)
+
+    # every definition of a label: which one renders depends on which are in
+    # code, so resolution checks all of them, and navigation trusts a label
+    # only when it has exactly one definition and that one is visible
+    definitions: dict[str, list] = {}
+    for m in _MD_REF.finditer(text):
+        definitions.setdefault(m.group("label").strip().lower(), []).append(m)
+    used = [(m.group("label").strip().lower() or m.group("text").strip().lower(), m.start())
+            for m in _REF_FULL.finditer(text) if keep(m.start())]
+    used += [(m.group("label").strip().lower(), m.start())
+             for m in _REF_SHORT.finditer(text) if keep(m.start())]
+    found: list[tuple[str, tuple[int, ...]]] = [
+        (target_of(m), (m.start(),)) for m in _MD_LINK.finditer(text) if keep(m.start())]
+    for label, pos in used:
+        defs = definitions.get(label, [])
+        if not certain:
+            found += [(target_of(m), (pos, m.start())) for m in defs]
+        elif len(defs) == 1 and keep(defs[0].start()):
+            found.append((target_of(defs[0]), (pos, defs[0].start())))
+    out = []
+    for raw, positions in found:
+        target = raw.split("#", 1)[0]
+        if not target or "://" in target or target.startswith("mailto:"):
+            continue
+        resolved = ".." if target.startswith("/") else \
+            posixpath.normpath(posixpath.join(directory, target))  # absolute: never inside
+        out.append((target, resolved, positions))
+    return out
+
+
+def _link_targets(directory: str, text: str, *, certain: bool = False) -> dict[str, str]:
+    """{written target: resolved path} of ``_link_occurrences``."""
+    return {written: resolved for written, resolved, _ in _link_occurrences(directory, text, certain=certain)}
+
+
+def _dropped_links(directory: str, before: str, after: str) -> set[str]:
+    """Links ``before`` has that ``after`` may no longer show, fail-closed: a
+    link is kept only when it is certainly visible in ``after``, or every block
+    it sits in is unchanged in ``after`` after the same fence-like lines."""
+    raw_after = _link_targets(directory, after)
+    visible_after = _link_targets(directory, after, certain=True)
+    contexts_after = _contexts(after)
+    dropped = set()
+    for written, _resolved, positions in _link_occurrences(directory, before):
+        if written not in raw_after:
+            dropped.add(written)
+        elif written not in visible_after and not all(
+                _block_context(before, pos) in contexts_after for pos in positions):
+            dropped.add(written)
+    return dropped
+
+
+def _unparsed_links(text: str) -> set[str]:
+    """Each "](" no inline-link pattern accounts for, as its line: link syntax
+    the checker cannot read is refused rather than skipped."""
+    parsed = {m.start() for m in _MD_LINK.finditer(text)}
+    return {text[text.rfind("\n", 0, i) + 1:].split("\n", 1)[0].strip()
+            for i in (m.start() for m in re.finditer(r"\]\(", text)) if i not in parsed}
+
+
+def _dir_entries(head: Mapping[str, str], directory: str) -> list[str]:
+    """Pages directly in ``directory`` and the indexes of its child directories."""
+    prefix = f"{directory}/" if directory else ""
+    out = []
+    for p in sorted(head):
+        if not p.startswith(prefix) or not p.endswith(".md"):
+            continue
+        rest = p[len(prefix):].split("/")
+        if (len(rest) == 1 and rest[0] != INDEX_NAME) or (len(rest) == 2 and rest[1] == INDEX_NAME):
+            out.append(p)
+    return out
+
+
+def _index_created(path: str, base: Mapping[str, str], head: Mapping[str, str],
+                   issues: list[Issue], blocks: list[Block]) -> None:
+    """Bootstrap: an index created for a directory that is new in this change set."""
+    directory = posixpath.dirname(path)
+    if any(p.startswith(f"{directory}/") for p in base):
+        issues.append(Issue("index_added_or_deleted", path,
+                            "an index may be created only for a new directory"))
+        return
+    linked = set(_link_targets(directory, head[path], certain=True).values())
+    for entry in _dir_entries(head, directory):
+        if entry not in linked:
+            issues.append(Issue("index_missing", path, f"{entry} is not linked"))
+    if directory:
+        parent = posixpath.join(posixpath.dirname(directory), INDEX_NAME)
+        # a parent index created in the same change set reports its own children
+        if parent in base and parent in head and path not in set(
+                _link_targets(posixpath.dirname(parent), head[parent], certain=True).values()):
+            issues.append(Issue("index_missing", parent, f"the new {path} is not linked"))
+    blocks.append(Block("prose", path, "", "prose", _sha(head[path])))
+
+
+def check_index_links(base: Mapping[str, str], head: Mapping[str, str]) -> list[Issue]:
+    """Links of every index added or changed from ``base`` to ``head``: each
+    link the change adds resolves inside the knowledge tree to a file (or a
+    directory) of ``head``; a changed index keeps every link it had; every
+    page or child index new in ``head`` is linked from its parent index.
+    Links an index already had are not re-judged (some point into doc/)."""
+    issues: list[Issue] = []
+    head_dirs = {posixpath.dirname(p) for p in head}
+    for path in sorted(p for p in head if posixpath.basename(p) == INDEX_NAME):
+        if base.get(path) == head[path]:
+            continue
+        directory = posixpath.dirname(path)
+        before = _link_targets(directory, base.get(path) or "")
+        after = _link_targets(directory, head[path])
+        for line in sorted(_unparsed_links(head[path]) - _unparsed_links(base.get(path) or "")):
+            issues.append(Issue("index_link_unparsed", path, line[:120]))
+        for written in sorted(_dropped_links(directory, base.get(path) or "", head[path])):
+            issues.append(Issue("index_link_dropped", path, written))
+        for written, resolved in sorted(after.items()):
+            if written in before:
+                continue
+            if resolved == ".." or resolved.startswith("../"):
+                issues.append(Issue("index_link_escapes", path, written))
+            elif resolved not in head and not any(d == resolved or d.startswith(resolved + "/")
+                                                  for d in head_dirs):
+                issues.append(Issue("index_link_broken", path, written))
+    for page in sorted(p for p in head if p not in base and p.endswith(".md")):
+        directory = posixpath.dirname(page)
+        if posixpath.basename(page) == INDEX_NAME:
+            if not directory:
+                continue
+            directory = posixpath.dirname(directory)
+        parent = posixpath.join(directory, INDEX_NAME)
+        if parent not in head:
+            if directory:  # the knowledge root has no index
+                issues.append(Issue("index_unlinked", page, f"{parent} does not exist"))
+            continue
+        if page not in set(_link_targets(directory, head[parent], certain=True).values()):
+            issues.append(Issue("index_unlinked", page, f"{parent} does not link it"))
+    return issues
+
+
 def check_changeset(
     base: Mapping[str, str],
     head: Mapping[str, str],
@@ -368,6 +613,7 @@ def check_changeset(
     *,
     external_texts: Mapping[str, str] | None = None,
     release: str = "",
+    bootstrap: bool = False,
 ) -> ChangesetResult:
     """Gate one change set. ``base``/``head`` map knowledge-relative paths
     (``repos/...``) to text; ``changes`` are repository-relative git changes.
@@ -375,9 +621,9 @@ def check_changeset(
     for references to rules this change retires or purges. ``release`` is the
     trusted current release (from the signed verdict); when given, purges must
     carry it as ``purged_at``. A purge is always rejected in the release that
-    retired the rule."""
+    retired the rule. ``bootstrap`` is for ``kb init`` only (module docstring)."""
     changes = list(changes)
-    issues = _whitelist_issues(changes)
+    issues = _whitelist_issues(changes, bootstrap)
     blocks: list[Block] = []
     retired: list[str] = []
     purged: list[tuple[str, str]] = []  # (rule id, page)
@@ -400,7 +646,8 @@ def check_changeset(
     for path in sorted(knowledge_paths):
         name = PurePosixPath(path).name
         if name == INDEX_NAME:
-            _index_mechanical(path, base.get(path), head.get(path), new_pages, issues, blocks, head)
+            _index_mechanical(path, base.get(path), head.get(path), new_pages, issues, blocks, head,
+                              base=base, bootstrap=bootstrap)
         elif name == TOMBSTONES_NAME:
             tombstone_paths.append(path)
         elif name == ROUTES_NAME:
diff --git a/test/test_kb_init_l1.py b/test/test_kb_init_l1.py
new file mode 100644
index 00000000..4a444a66
--- /dev/null
+++ b/test/test_kb_init_l1.py
@@ -0,0 +1,306 @@
+"""L1 bootstrap mode (kb init creates a repository's indexes) and the init-side
+index link check (design kb init v3 §9.2, §9.3)."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from infermatrix_copilot.knowledge_service.l1 import (
+    Change, check_changeset, check_index_links,
+)
+
+PAGE = (
+    "---\n"
+    'title: "Demo rules"\n'
+    "created: 2026-09-30\n"
+    "updated: 2026-09-30\n"
+    "type: rule\n"
+    "tags: [demo]\n"
+    "sources: []\n"
+    "---\n\n"
+    "# Demo rules\n"
+)
+
+
+def _base() -> dict[str, str]:
+    return {
+        "repos/_index.md": "# repos\n\n| repo | where |\n|---|---|\n| old | [old](old/_index.md) |\n",
+        "repos/old/_index.md": "# old\n\n- [rules](rules.md)\n",
+        "repos/old/rules.md": PAGE,
+        "general/_index.md": "# general\n\n- [method](method.md)\n",
+        "general/method.md": "# method\n",
+    }
+
+
+def _new_repo(base: dict[str, str]) -> dict[str, str]:
+    head = dict(base)
+    head["repos/_index.md"] = base["repos/_index.md"] + "| new | [new](new/_index.md) |\n"
+    head["repos/new/_index.md"] = (
+        "# new\n\n| page | when |\n|---|---|\n| [rules](rules.md) | always |\n"
+        "| [core](core/_index.md) | core |\n\n- [method](../../general/method.md)\n"
+    )
+    head["repos/new/rules.md"] = PAGE
+    head["repos/new/core/_index.md"] = "# core\n\n- [cards](cards.md)\n"
+    head["repos/new/core/cards.md"] = "# cards\n"
+    return head
+
+
+def _changes(base: dict, head: dict) -> list[Change]:
+    out = []
+    for path in sorted(set(base) | set(head)):
+        if base.get(path) == head.get(path):
+            continue
+        status = "A" if path not in base else "D" if path not in head else "M"
+        out.append(Change(f"knowledge/{path}", status, "100644", "" if status == "D" else "100644"))
+    return out
+
+
+def _codes(result) -> set[str]:
+    return {i.code for i in result.issues}
+
+
+def test_new_directory_indexes_pass_only_in_bootstrap():
+    base = _base()
+    head = _new_repo(base)
+    boot = check_changeset(base, head, _changes(base, head), bootstrap=True)
+    assert boot.ok, boot.issues
+    created = {b.path for b in boot.blocks if b.kind == "prose"}
+    assert {"repos/new/_index.md", "repos/new/core/_index.md"} <= created
+    plain = check_changeset(base, head, _changes(base, head))
+    assert {"index_added_or_deleted", "path_not_whitelisted"} <= _codes(plain)
+
+
+def test_default_mode_is_unchanged_for_an_existing_index():
+    base = _base()
+    head = {**base, "repos/old/extra.md": PAGE,
+            "repos/old/_index.md": base["repos/old/_index.md"] + "- [extra](extra.md)\n"}
+    assert check_changeset(base, head, _changes(base, head)).ok
+    assert check_changeset(base, head, _changes(base, head), bootstrap=True).ok
+
+
+def test_index_in_an_existing_directory_is_still_refused():
+    base = _base()
+    base.pop("repos/old/_index.md")
+    head = {**base, "repos/old/_index.md": "# old\n\n- [rules](rules.md)\n"}
+    result = check_changeset(base, head, _changes(base, head), bootstrap=True)
+    assert "index_added_or_deleted" in _codes(result)
+
+
+def test_created_index_must_link_its_pages_and_child_indexes():
+    base = _base()
+    head = _new_repo(base)
+    head["repos/new/_index.md"] = "# new\n\n- [rules](rules.md)\n"
+    result = check_changeset(base, head, _changes(base, head), bootstrap=True)
+    missing = [i for i in result.issues if i.code == "index_missing"]
+    assert [i.detail for i in missing] == ["repos/new/core/_index.md is not linked"]
+
+
+def test_parent_index_must_link_the_created_index():
+    base = _base()
+    head = _new_repo(base)
+    head["repos/_index.md"] = base["repos/_index.md"]
+    result = check_changeset(base, head, _changes(base, head), bootstrap=True)
+    assert any(i.code == "index_missing" and i.path == "repos/_index.md" for i in result.issues)
+
+
+def test_deleting_an_index_is_refused_in_bootstrap():
+    base = _base()
+    head = dict(base)
+    head.pop("repos/old/_index.md")
+    result = check_changeset(base, head, _changes(base, head), bootstrap=True)
+    assert "index_added_or_deleted" in _codes(result)
+
+
+def test_repos_index_whitelist_is_edit_only():
+    base = _base()
+    head = _new_repo(base)
+    changes = [c if c.path != "knowledge/repos/_index.md" else Change(c.path, "A", "", "100644")
+               for c in _changes(base, head)]
+    result = check_changeset(base, head, changes, bootstrap=True)
+    assert "path_not_whitelisted" in _codes(result)
+
+
+def test_index_links_accept_a_valid_bootstrap():
+    base = _base()
+    assert check_index_links(base, _new_repo(base)) == []
+
+
+def test_index_links_report_broken_escaping_dropped_and_unlinked():
+    base = _base()
+    head = _new_repo(base)
+    head["repos/new/_index.md"] += "- [gone](missing.md)\n- [out](../../../README.md)\n- [abs](/etc/x.md)\n"
+    head["repos/old/_index.md"] = "# old\n"                      # dropped a link
+    head["repos/new/core/orphan.md"] = "# orphan\n"               # new page, not linked
+    issues = {(i.code, i.path, i.detail) for i in check_index_links(base, head)}
+    assert ("index_link_broken", "repos/new/_index.md", "missing.md") in issues
+    assert ("index_link_escapes", "repos/new/_index.md", "../../../README.md") in issues
+    assert ("index_link_escapes", "repos/new/_index.md", "/etc/x.md") in issues
+    assert ("index_link_dropped", "repos/old/_index.md", "rules.md") in issues
+    assert any(code == "index_unlinked" and path == "repos/new/core/orphan.md"
+               for code, path, _ in issues)
+
+
+def test_index_links_read_titles_angles_and_reference_definitions():
+    base = _base()
+    head = _new_repo(base)
+    head["repos/new/_index.md"] += (
+        '- [out](../../../README.md "title")\n'
+        "- [gone](<missing.md> 'title')\n"
+        "- [ref][r]\n\n[r]: ../../../ref.md \"t\"\n"
+        "[ok]: rules.md\n"
+    )
+    issues = {(i.code, i.detail) for i in check_index_links(base, head)}
+    assert issues == {("index_link_escapes", "../../../README.md"),
+                      ("index_link_broken", "missing.md"),
+                      ("index_link_escapes", "../../../ref.md")}
+
+
+def test_unused_reference_definitions_are_not_links():
+    base = _base()
+    head = _new_repo(base)
+    head["repos/new/core/_index.md"] = "# core\n\n[c]: cards.md\n"   # defined, never used
+    issues = {(i.code, i.path) for i in check_index_links(base, head)}
+    assert ("index_unlinked", "repos/new/core/cards.md") in issues
+    head["repos/new/core/_index.md"] = "# core\n\n- [Cards][c]\n\n[c]: cards.md\n"
+    assert check_index_links(base, head) == []
+    head["repos/new/core/_index.md"] = "# core\n\n- [c]\n\n[C]: cards.md\n"  # shortcut, case-folded
+    assert check_index_links(base, head) == []
+
+
+def test_code_never_hides_a_link_from_the_resolution_checks():
+    """Every link-like text is resolved, even one that may sit in code."""
+    base = _base()
+    head = _new_repo(base)
+    core = "repos/new/core/_index.md"
+    for tail in (
+        "```example```\n\n- [broken](missing.md)\n",           # inline code, not a fence
+        "`` literal [broken](missing.md) `\n",                   # unmatched backticks
+        "A literal ` here.\n\n[broken](missing.md)\n\nAnother literal ` here.\n",
+        "\\` [broken](missing.md) `\n",                          # escaped backtick
+        "- ```\n  example\n  ```\n\n[broken](missing.md)\n",     # fence inside a list
+        "~~~\n- [broken](missing.md)\n",                          # inside a real fence
+    ):
+        head[core] = "# core\n\n- [cards](cards.md)\n\n" + tail
+        assert {i.code for i in check_index_links(base, head)} == {"index_link_broken"}, tail
+
+
+def test_only_certainly_visible_links_count_as_navigation():
+    base = _base()
+    head = _new_repo(base)
+    core = "repos/new/core/_index.md"
+    for text in (
+        "# core\n\n`` a ```` [cards](cards.md) ``\n",          # unequal runs: inside code
+        "# core\n\nsee `code\n[cards](cards.md)` here\n",       # span across a line break
+        "# core\n\n```\n\n- [cards](cards.md)\n",                # after a fence-like line
+        "# core\n\n[cards]`example`(cards.md)\n",                # not a link at all
+    ):
+        head[core] = text
+        issues = {(i.code, i.path) for i in check_index_links(base, head)}
+        assert ("index_unlinked", "repos/new/core/cards.md") in issues, text
+    # a table cell is its own block: code in another cell does not matter
+    head[core] = "# core\n\n| page | note |\n|---|---|\n| `x/y` | [cards](cards.md) |\n"
+    assert check_index_links(base, head) == []
+
+
+def test_a_definition_in_code_cannot_shadow_the_real_one():
+    base = _base()
+    head = dict(base)
+    head["repos/old/_index.md"] = (base["repos/old/_index.md"]
+                                   + "[x][r]\n\n```\n[r]: rules.md\n```\n\n[r]: ../../../secret.md\n")
+    issues = {(i.code, i.detail) for i in check_index_links(base, head)}
+    assert ("index_link_escapes", "../../../secret.md") in issues
+
+
+def test_pipe_lines_without_a_table_header_are_not_table_cells():
+    base = _base()
+    head = _new_repo(base)
+    core = "repos/new/core/_index.md"
+    head[core] = "# core\n\n| `example | [cards](cards.md)` |\n"
+    issues = {(i.code, i.path) for i in check_index_links(base, head)}
+    assert ("index_unlinked", "repos/new/core/cards.md") in issues
+    # a table right after a paragraph line is not a table either (GFM)
+    head[core] = "# core\ntext `a\n| h | i |\n|---|---|\n| x | [cards](cards.md) |\n"
+    issues = {(i.code, i.path) for i in check_index_links(base, head)}
+    assert ("index_unlinked", "repos/new/core/cards.md") in issues
+
+
+def test_a_visible_link_after_code_that_becomes_code_is_dropped():
+    base = _base()
+    base["repos/old/_index.md"] = "# old\n\n- `rules` [rules](rules.md)\n"
+    head = dict(base)
+    head["repos/old/_index.md"] = "# old\n\n- `rules [rules](rules.md)\n"
+    assert {i.code for i in check_index_links(base, head)} == {"index_link_dropped"}
+    # unchanged block, unrelated edit elsewhere: kept
+    head["repos/old/_index.md"] = base["repos/old/_index.md"] + "\nmore words\n"
+    assert check_index_links(base, head) == []
+
+
+def test_a_link_after_a_closed_fence_that_reopens_is_dropped():
+    base = _base()
+    base["repos/old/_index.md"] = "# old\n\n```\nx\n```\n\n- [rules](rules.md)\n"
+    head = dict(base)
+    head["repos/old/_index.md"] = "# old\n\n```\nx\n\n- [rules](rules.md)\n"
+    assert {i.code for i in check_index_links(base, head)} == {"index_link_dropped"}
+    head["repos/old/_index.md"] = base["repos/old/_index.md"] + "\n- [more](rules.md#a)\n"
+    assert check_index_links(base, head) == []
+
+
+def test_moving_a_closing_fence_past_an_unchanged_link_drops_it():
+    base = _base()
+    base["repos/old/_index.md"] = "# old\n\n```\nx\n```\n\n- [rules](rules.md)\n"
+    head = dict(base)
+    head["repos/old/_index.md"] = "# old\n\n```\nx\n\n- [rules](rules.md)\n\n```\n"
+    assert {i.code for i in check_index_links(base, head)} == {"index_link_dropped"}
+
+
+def test_moving_a_link_into_code_drops_it():
+    base = _base()
+    head = dict(base)
+    head["repos/old/_index.md"] = "# old\n\n- `[rules](rules.md)`\n"
+    assert {i.code for i in check_index_links(base, head)} == {"index_link_dropped"}
+
+
+def test_duplicate_definitions_are_all_resolved_and_never_navigation():
+    base = _base()
+    head = _new_repo(base)
+    head["repos/new/core/_index.md"] = "# core\n\n- [Cards][c]\n\n[c]: missing.md\n[c]: cards.md\n"
+    issues = {(i.code, i.detail if i.code != "index_unlinked" else i.path)
+              for i in check_index_links(base, head)}
+    assert issues == {("index_link_broken", "missing.md"),
+                      ("index_unlinked", "repos/new/core/cards.md")}
+
+
+def test_removing_a_reference_usage_drops_the_link():
+    base = _base()
+    base["repos/old/_index.md"] = "# old\n\n- [Rules][r]\n\n[r]: rules.md\n"
+    head = dict(base)
+    head["repos/old/_index.md"] = "# old\n\n[r]: rules.md\n"
+    assert {i.code for i in check_index_links(base, head)} == {"index_link_dropped"}
+
+
+def test_index_links_detect_dropped_titled_links_and_refuse_unparsed_syntax():
+    base = _base()
+    base["repos/old/_index.md"] = '# old\n\n- [rules](rules.md "the rules")\n'
+    head = dict(base)
+    head["repos/old/_index.md"] = '# old\n\n- [x](rules.md "unterminated\n'
+    issues = {i.code for i in check_index_links(base, head)}
+    assert issues == {"index_link_dropped", "index_link_unparsed"}
+
+
+def test_index_links_ignore_urls_anchors_and_links_the_base_already_had():
+    base = _base()
+    base["general/_index.md"] += "- [schema](../../doc/knowledge/SCHEMA.md)\n"
+    head = dict(base)
+    head["general/_index.md"] += "- [site](https://example.com/x)\n- [top](#top)\n- [m](method.md#a)\n"
+    assert check_index_links(base, head) == []
+
+
+def test_only_kb_init_may_pass_bootstrap():
+    root = Path(__file__).resolve().parents[1] / "src" / "infermatrix_copilot"
+    allowed = {root / "kb_service" / "init_stages.py"}
+    offenders = [
+        str(path.relative_to(root)) for path in root.rglob("*.py")
+        if path not in allowed and re.search(r"bootstrap\s*=\s*True", path.read_text(encoding="utf-8"))
+    ]
+    assert offenders == []

From ba6ae171ebfc95ebb000cb309f241b3af3c63e69 Mon Sep 17 00:00:00 2001
From: tzhouam <tzhouam@connect.ust.hk>
Date: Wed, 30 Sep 2026 17:53:40 +0800
Subject: [PATCH 2/4] Count only whole, rendered links as index navigation

Two gaps in check_index_links' navigation side (coverage and preservation),
found by the integration gate:

- Indented code (4+ columns, tab included; an indented list item counts only
  inside a real list), HTML comments, HTML blocks and fences (any "hazard"
  line before a link: a fence, a line whose content after container
  prefixes starts with "<", a tag or comment left open) no longer count as
  visible. A page linked only from there is unlinked, and moving an existing
  link there is a drop.
- A navigation link must be whole: an unescaped, non-image "[" opening a
  non-blank label, then "(target)". "cards](x)", "\[cards](x)", "[](x)" and
  "![x](y)" no longer satisfy required links or preservation, nor does a
  link with a backtick or "<" in its text, or a tag or comment left open
  before it on its line (a code span, comment or attribute swallows it). Reference
  usages follow the same rule.

Resolution checks are unchanged (they still read every "](" form), so the
split stays fail-closed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 doc/architecture/SPEC/knowledge_service/l1.md |  10 +-
 .../knowledge_service/l1.py                   | 129 ++++++++++++++++--
 test/test_kb_init_l1.py                       |  89 ++++++++++++
 3 files changed, 215 insertions(+), 13 deletions(-)

diff --git a/doc/architecture/SPEC/knowledge_service/l1.md b/doc/architecture/SPEC/knowledge_service/l1.md
index ebc863fa..68185afa 100644
--- a/doc/architecture/SPEC/knowledge_service/l1.md
+++ b/doc/architecture/SPEC/knowledge_service/l1.md
@@ -43,11 +43,15 @@
   （`index_unlinked`，知识树根没有索引）。
   - 代码处理按方向 fail-closed，不实现 Markdown 解析器：解析/逃逸/无法解析检查看**所有**像链接的
     文本（藏在代码里的也查）；“是否链接了新页面”“是否保留了原链接”只认**确定可见**的链接——它之前
-    （含本行）没有任何类围栏行（容器前缀后的 ```` ``` ```` / `~~~`），且在所在块（段落、列表项、标题、
+    （含本行）没有任何“危险行”——类围栏行（容器前缀后的 ```` ``` ```` / `~~~`）、去掉容器前缀（`>`、列表标记）后
+    以 `<` 开头的 HTML 块行（单行闭合注释除外）、留下未闭合标签或 `<!--` 的行——且在所在块（段落、列表项、标题、
     引用，或真表格——空行后开始、第二行是分隔行——正文行的单元格，代码段跨不过单元格）内它之前没有
-    反引号。引用式链接：解析检查查该标签的**每一个**定义（哪个生效取决于哪个在代码里）；导航只认只有
+    反引号；且不在缩进代码（4 列以上缩进；只有同一块内上方有顶层列表项时，缩进的列表项才算嵌套列表）
+    或行内 HTML 注释里。导航只认完整链接：未转义、非图片的 `[` 开始的非空标签紧跟
+    `(目标)`，且整段链接文本里没有反引号和 `<`（`<目标>` 的尖括号除外）、同一行链接之前没有未闭合的标签
+    （引号内的 `>` 不闭合标签；链接/定义的 `<目标>` 与自动链接不是标签）或注释（缺开头 `[`、`[` 被转义、标签为空、图片、标签里带反引号的都不算）。引用式链接：解析检查查该标签的**每一个**定义（哪个生效取决于哪个在代码里）；导航只认只有
     一个定义且该定义确定可见的标签。“保留”也 fail-closed：base 的链接只有在 head 中确定可见，或它所在的
-    每个块在 head 中原样存在、且该块之前的类围栏行也相同时，才算保留；否则报 `index_link_dropped`（把链接挪进代码 =
+    每个块在 head 中原样存在、且该块之前的危险行也相同时，才算保留；否则报 `index_link_dropped`（把链接挪进代码 =
     丢链接）。
     在真实知识树的 142 个索引上逐一追加一行，无误报。
 
diff --git a/src/infermatrix_copilot/knowledge_service/l1.py b/src/infermatrix_copilot/knowledge_service/l1.py
index eaa5e068..9bda4dc2 100644
--- a/src/infermatrix_copilot/knowledge_service/l1.py
+++ b/src/infermatrix_copilot/knowledge_service/l1.py
@@ -68,6 +68,16 @@
 # a reference definition counts only where it is used: [text][label], [label][], [label]
 _REF_FULL = re.compile(r"\[(?P<text>[^\]\n]+)\]\[(?P<label>[^\]\n]*)\]")
 _REF_SHORT = re.compile(r"\[(?P<label>[^\]\n]+)\](?![(\[:])")
+# navigation needs the whole link: an unescaped "[" opening a non-blank label
+# (not an image "![", not "\["); anything less is not counted as a link
+_NAV_LABEL = r"(?<![\\!\]])\[(?P<text>(?:[^\[\]\\\n]|\\.)*[^\s\[\]\\](?:[^\[\]\\\n]|\\.)*)\]"
+_NAV_LINK = re.compile(_NAV_LABEL + r"\(\s*(?:<(?P<angle>[^>\n]*)>|(?P<target>[^)\s]+))"
+                       + _LINK_TITLE + r"\s*\)")
+_NAV_REF_FULL = re.compile(_NAV_LABEL + r"\[(?P<label>[^\]\n]*)\]")
+_NAV_REF_SHORT = re.compile(r"(?<![\\!\]])\[(?P<label>[^\[\]\n]*[^\s\[\]][^\[\]\n]*)\](?![(\[:])")
+# 4+ columns of indentation outside a nested list item: indented code
+_INDENTED = re.compile(r"(?: {4}| {0,3}\t)")
+_LIST_ITEM = re.compile(r"\s*(?:[-*+]|\d{1,9}[.)])\s")
 # Link visibility, fail-closed. No Markdown parser is complete, so the checks
 # split by direction: every link-like text counts when checking that links
 # resolve (a link "hidden in code" is still checked), and only a CERTAINLY
@@ -78,6 +88,61 @@
 _FENCE_LIKE = re.compile(r"^[\s>*+\-\d.)]*(?:`{3,}|~{3,})")
 _BLOCK_START = re.compile(r" {0,3}(?:#{1,6}(?:\s|$)|[-*+]\s|\d{1,9}[.)]\s|>)")
 _TABLE_ROW = re.compile(r" {0,3}\|")
+_TOP_LIST_ITEM = re.compile(r" {0,3}(?:[-*+]|\d{1,9}[.)])\s")
+_CONTAINER_PREFIX = re.compile(r"[ \t>]*(?:(?:[-*+]|\d{1,9}[.)])[ \t]+[ \t>]*)*")
+_CLOSED_COMMENT = re.compile(r"<!--.*?-->[ \t]*")
+
+
+_ANGLE_DEST_BEFORE = re.compile(r"(?:\]\(\s*|(?m:^) {0,3}\[[^\]\n]+\]:[ \t]*)$")
+_AUTOLINK = re.compile(r"<[A-Za-z][A-Za-z0-9+.-]{1,31}:[^<>\s]*>")
+
+
+def _open_tag(text: str) -> bool:
+    """``text`` ends inside an HTML comment or tag. A tag closes only at a ">"
+    outside its quoted attribute values. Markdown's own angle brackets (a
+    ``<destination>`` of a link or definition, an autolink) are not tags."""
+    state, quote, k = "", "", 0
+    while k < len(text):
+        if state == "comment":
+            end = text.find("-->", k)
+            if end < 0:
+                return True
+            state, k = "", end + 3
+            continue
+        ch = text[k]
+        if state == "tag":
+            if quote:
+                quote = "" if ch == quote else quote
+            elif ch in "\"'":
+                quote = ch
+            elif ch == ">":
+                state = ""
+        elif text.startswith("<!--", k):
+            state, k = "comment", k + 4
+            continue
+        elif ch == "<":
+            end = text.find(">", k)
+            if end > k and "\n" not in text[k:end] and (
+                    _ANGLE_DEST_BEFORE.search(text, 0, k) or _AUTOLINK.match(text, k)):
+                k = end + 1
+                continue
+            if k + 1 < len(text) and re.match(r"[A-Za-z/!?]", text[k + 1]):
+                state = "tag"
+        k += 1
+    return state != ""
+
+
+def _hazard(line: str) -> bool:
+    """A line that may change how the lines after it render: a fence, an HTML
+    block (content starting with "<" after any container prefix, except one
+    closed comment), or a tag or comment left open. Nothing after a hazard
+    counts as certainly visible."""
+    if _FENCE_LIKE.match(line):
+        return True
+    content = line[_CONTAINER_PREFIX.match(line).end():]
+    if content.startswith("<") and not _CLOSED_COMMENT.fullmatch(content):
+        return True
+    return _open_tag(line)
 _TABLE_DELIM = re.compile(r" {0,3}\|?\s*:?-+:?\s*(?:\|\s*:?-+:?\s*)*\|?\s*")
 
 
@@ -99,9 +164,11 @@ def _certainly_visible(text: str, pos: int) -> bool:
     line_end = text.find("\n", pos)
     line_end = len(text) if line_end < 0 else line_end
     lines = text[:line_end].split("\n")
-    if any(_FENCE_LIKE.match(line) for line in lines):
+    if any(_hazard(line) for line in lines):
         return False
     line = lines[-1]
+    if _in_html_comment(text, pos) or _indented_code(lines):
+        return False
     if _table_body_row(lines, len(lines) - 1):
         cell_start = max((m.end() for m in re.finditer(r"(?<!\\)\|", line[:pos - line_start])), default=0)
         return "`" not in line[cell_start:pos - line_start]
@@ -112,6 +179,32 @@ def _certainly_visible(text: str, pos: int) -> bool:
     return "`" not in text[block_start:pos]
 
 
+def _in_html_comment(text: str, pos: int) -> bool:
+    opened = text.rfind("<!--", 0, pos)
+    if opened < 0:
+        return False
+    closed = text.find("-->", opened + 4)
+    return closed < 0 or closed >= pos
+
+
+def _indented_code(lines: list[str]) -> bool:
+    """The last line may be indented code: 4+ columns of indentation, unless it
+    is a list item inside a real list, i.e. its block (no blank line between)
+    starts at a top-level list item (fail-closed)."""
+    if not _INDENTED.match(lines[-1]):
+        return False
+    if not _LIST_ITEM.match(lines[-1]):
+        return True
+    k = len(lines) - 2
+    while k >= 0 and lines[k].strip():
+        if _TOP_LIST_ITEM.match(lines[k]):
+            return False
+        if not (_INDENTED.match(lines[k]) and _LIST_ITEM.match(lines[k])):
+            return True
+        k -= 1
+    return True
+
+
 def _block_span(text: str, pos: int) -> tuple[int, int]:
     """Offsets of the whole block holding ``pos`` (a table body row is its
     own block)."""
@@ -129,10 +222,10 @@ def _block_span(text: str, pos: int) -> tuple[int, int]:
 
 
 def _block_context(text: str, pos: int) -> tuple[str, tuple[str, ...]]:
-    """The block holding ``pos`` and the fence-like lines before it: the same
-    block after the same fences renders the same way."""
+    """The block holding ``pos`` and the hazard lines before it: the same block
+    after the same hazards renders the same way."""
     start, end = _block_span(text, pos)
-    return text[start:end], tuple(line for line in text[:start].split("\n") if _FENCE_LIKE.match(line))
+    return text[start:end], tuple(line for line in text[:start].split("\n") if _hazard(line))
 
 
 def _contexts(text: str) -> set[tuple[str, tuple[str, ...]]]:
@@ -468,8 +561,21 @@ def _link_occurrences(directory: str, text: str, *, certain: bool = False
     def target_of(match) -> str:
         return match.group("angle") if match.group("angle") is not None else match.group("target")
 
-    def keep(pos: int) -> bool:
-        return not certain or _certainly_visible(text, pos)
+    def keep(match) -> bool:
+        # visible where it starts, and no backtick anywhere in the link text
+        # itself (one there opens a code span that swallows the link)
+        # and no markup in or open before it on its line (a comment or a tag
+        # attribute swallows what looks like a link)
+        if not certain:
+            return True
+        line_start = text.rfind("\n", 0, match.start()) + 1
+        body = match.group(0)
+        if "angle" in match.re.groupindex and match.group("angle") is not None:
+            # the <destination> delimiters are link syntax, not markup
+            lo, hi = match.start("angle") - 1 - match.start(), match.end("angle") + 1 - match.start()
+            body = body[:lo] + match.group("angle") + body[hi:]
+        return (_certainly_visible(text, match.start()) and "`" not in body and "<" not in body
+                and not _open_tag(text[line_start:match.start()]))
 
     # every definition of a label: which one renders depends on which are in
     # code, so resolution checks all of them, and navigation trusts a label
@@ -477,17 +583,20 @@ def keep(pos: int) -> bool:
     definitions: dict[str, list] = {}
     for m in _MD_REF.finditer(text):
         definitions.setdefault(m.group("label").strip().lower(), []).append(m)
+    # resolution reads every "](" and "[..]" form; navigation only whole links
+    link, full, short = (_NAV_LINK, _NAV_REF_FULL, _NAV_REF_SHORT) if certain \
+        else (_MD_LINK, _REF_FULL, _REF_SHORT)
     used = [(m.group("label").strip().lower() or m.group("text").strip().lower(), m.start())
-            for m in _REF_FULL.finditer(text) if keep(m.start())]
+            for m in full.finditer(text) if keep(m)]
     used += [(m.group("label").strip().lower(), m.start())
-             for m in _REF_SHORT.finditer(text) if keep(m.start())]
+             for m in short.finditer(text) if keep(m)]
     found: list[tuple[str, tuple[int, ...]]] = [
-        (target_of(m), (m.start(),)) for m in _MD_LINK.finditer(text) if keep(m.start())]
+        (target_of(m), (m.start(),)) for m in link.finditer(text) if keep(m)]
     for label, pos in used:
         defs = definitions.get(label, [])
         if not certain:
             found += [(target_of(m), (pos, m.start())) for m in defs]
-        elif len(defs) == 1 and keep(defs[0].start()):
+        elif len(defs) == 1 and keep(defs[0]):
             found.append((target_of(defs[0]), (pos, defs[0].start())))
     out = []
     for raw, positions in found:
diff --git a/test/test_kb_init_l1.py b/test/test_kb_init_l1.py
index 4a444a66..a8ea8cf1 100644
--- a/test/test_kb_init_l1.py
+++ b/test/test_kb_init_l1.py
@@ -254,6 +254,95 @@ def test_moving_a_closing_fence_past_an_unchanged_link_drops_it():
     assert {i.code for i in check_index_links(base, head)} == {"index_link_dropped"}
 
 
+def test_indented_code_html_comments_and_html_blocks_are_not_navigation():
+    base = _base()
+    head = _new_repo(base)
+    core = "repos/new/core/_index.md"
+    for text in (
+        "# core\n\n    [cards](cards.md)\n",                 # indented code
+        "# core\n\n\t[cards](cards.md)\n",                   # tab-indented code
+        "# core\n\n<!-- [cards](cards.md) -->\n",            # HTML comment
+        "# core\n\n<!--\n- [cards](cards.md)\n",             # unclosed comment
+        "# core\n\n<div>\n[cards](cards.md)\n</div>\n",      # HTML block
+    ):
+        head[core] = text
+        issues = {(i.code, i.path) for i in check_index_links(base, head)}
+        assert ("index_unlinked", "repos/new/core/cards.md") in issues, text
+    for text in (
+        "# core\n\n<div>\n- [cards](cards.md)\n</div>\n",   # HTML block across a list item
+        "# core\n\n    - group\n    - [cards](cards.md)\n",  # consecutive indented lines: code
+        "# core\n\ntext <!--\n\n- [cards](cards.md)\n",     # comment left open mid-line
+        "# core\n\n> <div>\n> [cards](cards.md)\n> </div>\n",  # HTML block inside a quote
+        "# core\n\n- [cards <!--](cards.md) -->\n",           # comment swallows the destination
+        '# core\n\n- <span title="[cards](cards.md)">x</span>\n',  # link text in an attribute
+        '# core\n\ntext <span title="\n[cards](cards.md)">x</span>\n',  # tag open across lines
+        '# core\n\ntext <span title=">[cards](cards.md)">x</span>\n',  # ">" inside a quoted value
+    ):
+        head[core] = text
+        issues = {(i.code, i.path) for i in check_index_links(base, head)}
+        assert ("index_unlinked", "repos/new/core/cards.md") in issues, text
+    # angle-bracket destinations are links, inline or in a definition
+    for text in ("# core\n\n- [cards](<cards.md>)\n", "# core\n\n- [Cards][c]\n\n[c]: <cards.md>\n",
+                 '# core\n\nsee <span title="a > b">x</span> and [cards](cards.md)\n'):
+        head[core] = text
+        assert check_index_links(base, head) == [], text
+    # a quote inside an angle destination or an autolink is not an HTML attribute
+    head["repos/new/core/it's.md"] = "# it's\n"
+    for text in ("# core\n\n- [it](<it's.md>)\n- [cards](cards.md)\n",
+                 "# core\n\n- [It][i]\n- [cards](cards.md)\n\n[i]: <it's.md>\n",
+                 "# core\n\nsee <https://example.com/a'b> and [cards](cards.md) and [it](<it's.md>)\n"):
+        head[core] = text
+        assert check_index_links(base, head) == [], text
+    head.pop("repos/new/core/it's.md")
+    # a nested list item indented 4 columns is still a list item
+    head[core] = "# core\n\n- group\n    - [cards](cards.md)\n"
+    assert check_index_links(base, head) == []
+    # a closed comment before the link does not hide it
+    head[core] = "# core\n\n<!-- note -->\n\n- [cards](cards.md)\n"
+    assert check_index_links(base, head) == []
+
+
+def test_moving_a_link_into_indented_code_or_a_comment_drops_it():
+    base = _base()
+    for moved in ("# old\n\n    - [rules](rules.md)\n", "# old\n\n<!-- - [rules](rules.md) -->\n",
+                  "# old\n\n<!--\n\n- [rules](rules.md)\n\n-->\n",
+                  "# old\n\n<div>\n\n- [rules](rules.md)\n\n</div>\n",
+                  '# old\n\ntext <span title=">- [rules](rules.md)">x</span>\n'):
+        head = {**base, "repos/old/_index.md": moved}
+        assert {i.code for i in check_index_links(base, head)} == {"index_link_dropped"}, moved
+
+
+def test_navigation_needs_a_whole_unescaped_link():
+    base = _base()
+    head = _new_repo(base)
+    core = "repos/new/core/_index.md"
+    for text in (
+        "# core\n\n- cards](cards.md)\n",       # no opening bracket
+        "# core\n\n- \\[cards](cards.md)\n",    # escaped bracket
+        "# core\n\n- [](cards.md)\n",           # empty label
+        "# core\n\n- ![cards](cards.md)\n",     # an image, not a link
+        "# core\n\n- [cards `](cards.md)`\n",   # a backtick in the label opens a code span
+        "# core\n\n- [Cards][c]\n\n[c]: `cards.md`\n",
+    ):
+        head[core] = text
+        issues = {(i.code, i.path) for i in check_index_links(base, head)}
+        assert ("index_unlinked", "repos/new/core/cards.md") in issues, text
+    head[core] = "# core\n\n- [cards \\] x](cards.md)\n"   # escaped bracket inside a label is fine
+    assert check_index_links(base, head) == []
+    # and a malformed replacement of an existing link drops it
+    for broken in ("# old\n\n- rules](rules.md)\n", "# old\n\n- [rules `](rules.md)`\n"):
+        head = {**base, "repos/old/_index.md": broken}
+        assert "index_link_dropped" in {i.code for i in check_index_links(base, head)}, broken
+
+
+def test_bootstrap_coverage_uses_the_same_navigation_rules():
+    base = _base()
+    head = _new_repo(base)
+    head["repos/new/core/_index.md"] = "# core\n\n    [cards](cards.md)\n"
+    result = check_changeset(base, head, _changes(base, head), bootstrap=True)
+    assert any(i.code == "index_missing" and "cards.md" in i.detail for i in result.issues)
+
+
 def test_moving_a_link_into_code_drops_it():
     base = _base()
     head = dict(base)

From 919585065ee6c182d7ec68a9f6abe71bb91a2943 Mon Sep 17 00:00:00 2001
From: tzhouam <tzhouam@connect.ust.hk>
Date: Wed, 30 Sep 2026 18:26:28 +0800
Subject: [PATCH 3/4] Take index links from a CommonMark parser instead of
 hand-written matchers

check_index_links hand-parsed Markdown to decide which links render, and
every review round found another construct it misread (reference definitions
inside a paragraph, escaped quotes in titles, HTML blocks, code spans...).
That loop does not converge, so the links now come from markdown-it-py's
CommonMark parser with GitHub pipe tables: every link_open href (not
images, nor anything in their alt text), split as a URL first and then only
the path percent-decoded (an encoded "#" or ":" stays part of the name). The parser settles reference definitions, titles, escapes,
code spans and blocks, HTML blocks and comments the way renderers do.

- resolution: links the change adds must resolve in head and stay inside the
  knowledge tree (base links are not re-judged; URLs/anchors are skipped)
- preservation: every base link (by resolved path) must still be a head link,
  so moving a link into code, a comment or an HTML block drops it
- coverage: new pages and child indexes must be among the parent index's
  links (bootstrap index creation uses the same links)
- index_link_unparsed is gone: the parser defines what is a link

markdown-it-py>=3 is declared in pyproject (it was only a transitive
dependency of rich) and imported lazily. The visibility heuristics, the
hazard/tag scanners and their regexes are deleted; behavioural regression
tests are ported to what CommonMark renders, including both new repros.
Real tree: appending a line to, and linking a new page from, each of the
142 indexes gives 0 issues and 0 missed links.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 doc/architecture/SPEC/knowledge_service/l1.md |  37 +--
 pyproject.toml                                |   1 +
 .../knowledge_service/l1.py                   | 313 +++---------------
 test/test_kb_init_l1.py                       | 257 +++++---------
 4 files changed, 151 insertions(+), 457 deletions(-)

diff --git a/doc/architecture/SPEC/knowledge_service/l1.md b/doc/architecture/SPEC/knowledge_service/l1.md
index 68185afa..e7648c11 100644
--- a/doc/architecture/SPEC/knowledge_service/l1.md
+++ b/doc/architecture/SPEC/knowledge_service/l1.md
@@ -33,30 +33,23 @@
   其余规则（尾注、frontmatter、`sources`、白名单其余部分、保护规则）不变；默认 `False`
   时行为与原来逐字节一致。
 - `check_index_links(base, head)`：init 侧的索引链接检查（索引改成表格或跨目录链接时
-  L1 只把它当 prose 块）。对每个新增或改动的 `_index.md`：本次新增的相对链接必须解析到
-  head 中的文件或目录、不得逃出知识树（issue `index_link_broken` / `index_link_escapes`；
-  URL、纯锚点不算链接，base 已有的链接不重新判定——有些指向 `doc/`）；链接识别行内链接
-  （可带 `<尖括号>` 目标与 `"标题"`/`'标题'`/`(标题)`）和引用式链接（定义 `[r]: target` 只在被 `[文本][r]`、`[r][]`、`[r]` 实际使用时才算链接，
-  标签不区分大小写），其余无法解析
-  的 `](` 一律报 `index_link_unparsed`，不静默跳过；改动的索引不得丢掉
-  base 的链接（`index_link_dropped`）；head 中每个新页面、新子目录索引都必须被父索引链接
-  （`index_unlinked`，知识树根没有索引）。
-  - 代码处理按方向 fail-closed，不实现 Markdown 解析器：解析/逃逸/无法解析检查看**所有**像链接的
-    文本（藏在代码里的也查）；“是否链接了新页面”“是否保留了原链接”只认**确定可见**的链接——它之前
-    （含本行）没有任何“危险行”——类围栏行（容器前缀后的 ```` ``` ```` / `~~~`）、去掉容器前缀（`>`、列表标记）后
-    以 `<` 开头的 HTML 块行（单行闭合注释除外）、留下未闭合标签或 `<!--` 的行——且在所在块（段落、列表项、标题、
-    引用，或真表格——空行后开始、第二行是分隔行——正文行的单元格，代码段跨不过单元格）内它之前没有
-    反引号；且不在缩进代码（4 列以上缩进；只有同一块内上方有顶层列表项时，缩进的列表项才算嵌套列表）
-    或行内 HTML 注释里。导航只认完整链接：未转义、非图片的 `[` 开始的非空标签紧跟
-    `(目标)`，且整段链接文本里没有反引号和 `<`（`<目标>` 的尖括号除外）、同一行链接之前没有未闭合的标签
-    （引号内的 `>` 不闭合标签；链接/定义的 `<目标>` 与自动链接不是标签）或注释（缺开头 `[`、`[` 被转义、标签为空、图片、标签里带反引号的都不算）。引用式链接：解析检查查该标签的**每一个**定义（哪个生效取决于哪个在代码里）；导航只认只有
-    一个定义且该定义确定可见的标签。“保留”也 fail-closed：base 的链接只有在 head 中确定可见，或它所在的
-    每个块在 head 中原样存在、且该块之前的危险行也相同时，才算保留；否则报 `index_link_dropped`（把链接挪进代码 =
-    丢链接）。
-    在真实知识树的 142 个索引上逐一追加一行，无误报。
+  L1 只把它当 prose 块）。**链接 = 渲染器实际生成的链接**：用 markdown-it-py 的 CommonMark 解析器
+  （开启 GitHub 管道表格）取所有 `link_open` 的 href（图片及其 alt 文本里的不算）；先按 URL 拆分（编码的 `#`、`:` 属于文件名），
+  再只对路径做百分号解码；引用定义、标题、转义、代码段/代码块、
+  HTML 块/注释都由解析器按渲染器的方式处理，不手写匹配。URL、纯锚点不算目标。
+  对每个新增或改动的 `_index.md`：
+  - 本次新增的链接必须解析到 head 中的文件或目录、不得逃出知识树（`index_link_broken` /
+    `index_link_escapes`，绝对路径保留各自的 `/…` 身份且一律算逃逸；base 已有的链接不重新判定——
+    有些指向 `doc/`）。
+  - 保留：base 的链接（按解析后的路径）必须仍在 head 的链接里，否则 `index_link_dropped`——把链接挪进
+    代码、注释或 HTML 块 = 丢链接。
+  - 覆盖：head 中每个新页面、新子目录索引都必须被父索引链接（`index_unlinked`，知识树根没有索引）；
+    bootstrap 新建索引的 `index_missing` 用同一套链接。
+  在真实知识树的 142 个索引上逐一追加一行、逐一新增一个被链接的页面：0 误报、0 漏判。
 
 ## 不变量
-纯函数；标准库 + PyYAML + `lifecycle`/`ops`，验证包原样携带。段比较忽略尾部空行
+纯函数；标准库 + PyYAML + `lifecycle`/`ops`（索引链接检查另用 markdown-it-py，延迟导入，
+`pyproject` 显式声明），验证包原样携带。段比较忽略尾部空行
 （追加段落时前一段多出的分隔空行不算改动）。
 
 ## 测试
diff --git a/pyproject.toml b/pyproject.toml
index 45f4e49f..c0d4a807 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -10,6 +10,7 @@ dependencies = [
     "anthropic>=0.34",
     "openai>=1.50",
     "rich>=13.0",
+    "markdown-it-py>=3",
 ]
 
 [project.optional-dependencies]
diff --git a/src/infermatrix_copilot/knowledge_service/l1.py b/src/infermatrix_copilot/knowledge_service/l1.py
index 9bda4dc2..d89ecf85 100644
--- a/src/infermatrix_copilot/knowledge_service/l1.py
+++ b/src/infermatrix_copilot/knowledge_service/l1.py
@@ -26,7 +26,8 @@
 ``check_index_links(base, head)`` is the init-side link check for the index
 edits that bootstrap produces.
 
-Standard library + PyYAML + ``lifecycle``/``ops`` only.
+Standard library + PyYAML + ``lifecycle``/``ops``; ``check_index_links`` (and the
+bootstrap index check) also uses markdown-it-py, imported lazily.
 """
 
 from __future__ import annotations
@@ -38,6 +39,7 @@
 from dataclasses import dataclass
 from pathlib import PurePosixPath
 from typing import Iterable, Mapping
+from urllib.parse import unquote, urlsplit
 
 import yaml
 
@@ -59,178 +61,6 @@
 _INDEX_LINE = re.compile(r"- \[[^\]\n]+\]\((?P<file>[^)/\s]+\.md)\)")
 # bootstrap only: the shared list of repositories, edited to link a new one
 _REPOS_INDEX = "knowledge/repos/_index.md"
-# inline links (optional <angle> target and "title" / 'title' / (title)) and
-# reference definitions; any other "](" is unparsed and refused by the link check
-_LINK_TITLE = r"""(?:\s+(?:"[^"\n]*"|'[^'\n]*'|\([^)\n]*\)))?"""
-_MD_LINK = re.compile(r"\]\(\s*(?:<(?P<angle>[^>\n]*)>|(?P<target>[^)\s]+))" + _LINK_TITLE + r"\s*\)")
-_MD_REF = re.compile(r"(?m)^ {0,3}\[(?P<label>[^\]\n]+)\]:[ \t]*(?:<(?P<angle>[^>\n]*)>|(?P<target>\S+))"
-                     + _LINK_TITLE + r"[ \t]*$")
-# a reference definition counts only where it is used: [text][label], [label][], [label]
-_REF_FULL = re.compile(r"\[(?P<text>[^\]\n]+)\]\[(?P<label>[^\]\n]*)\]")
-_REF_SHORT = re.compile(r"\[(?P<label>[^\]\n]+)\](?![(\[:])")
-# navigation needs the whole link: an unescaped "[" opening a non-blank label
-# (not an image "![", not "\["); anything less is not counted as a link
-_NAV_LABEL = r"(?<![\\!\]])\[(?P<text>(?:[^\[\]\\\n]|\\.)*[^\s\[\]\\](?:[^\[\]\\\n]|\\.)*)\]"
-_NAV_LINK = re.compile(_NAV_LABEL + r"\(\s*(?:<(?P<angle>[^>\n]*)>|(?P<target>[^)\s]+))"
-                       + _LINK_TITLE + r"\s*\)")
-_NAV_REF_FULL = re.compile(_NAV_LABEL + r"\[(?P<label>[^\]\n]*)\]")
-_NAV_REF_SHORT = re.compile(r"(?<![\\!\]])\[(?P<label>[^\[\]\n]*[^\s\[\]][^\[\]\n]*)\](?![(\[:])")
-# 4+ columns of indentation outside a nested list item: indented code
-_INDENTED = re.compile(r"(?: {4}| {0,3}\t)")
-_LIST_ITEM = re.compile(r"\s*(?:[-*+]|\d{1,9}[.)])\s")
-# Link visibility, fail-closed. No Markdown parser is complete, so the checks
-# split by direction: every link-like text counts when checking that links
-# resolve (a link "hidden in code" is still checked), and only a CERTAINLY
-# visible link counts as navigation (for "is the page linked" and "was the link
-# kept"). Certainly visible: no fence-like line at or before it, and no
-# backtick before it in its block (paragraph, list item, heading, quote, or
-# table cell, which a code span cannot cross).
-_FENCE_LIKE = re.compile(r"^[\s>*+\-\d.)]*(?:`{3,}|~{3,})")
-_BLOCK_START = re.compile(r" {0,3}(?:#{1,6}(?:\s|$)|[-*+]\s|\d{1,9}[.)]\s|>)")
-_TABLE_ROW = re.compile(r" {0,3}\|")
-_TOP_LIST_ITEM = re.compile(r" {0,3}(?:[-*+]|\d{1,9}[.)])\s")
-_CONTAINER_PREFIX = re.compile(r"[ \t>]*(?:(?:[-*+]|\d{1,9}[.)])[ \t]+[ \t>]*)*")
-_CLOSED_COMMENT = re.compile(r"<!--.*?-->[ \t]*")
-
-
-_ANGLE_DEST_BEFORE = re.compile(r"(?:\]\(\s*|(?m:^) {0,3}\[[^\]\n]+\]:[ \t]*)$")
-_AUTOLINK = re.compile(r"<[A-Za-z][A-Za-z0-9+.-]{1,31}:[^<>\s]*>")
-
-
-def _open_tag(text: str) -> bool:
-    """``text`` ends inside an HTML comment or tag. A tag closes only at a ">"
-    outside its quoted attribute values. Markdown's own angle brackets (a
-    ``<destination>`` of a link or definition, an autolink) are not tags."""
-    state, quote, k = "", "", 0
-    while k < len(text):
-        if state == "comment":
-            end = text.find("-->", k)
-            if end < 0:
-                return True
-            state, k = "", end + 3
-            continue
-        ch = text[k]
-        if state == "tag":
-            if quote:
-                quote = "" if ch == quote else quote
-            elif ch in "\"'":
-                quote = ch
-            elif ch == ">":
-                state = ""
-        elif text.startswith("<!--", k):
-            state, k = "comment", k + 4
-            continue
-        elif ch == "<":
-            end = text.find(">", k)
-            if end > k and "\n" not in text[k:end] and (
-                    _ANGLE_DEST_BEFORE.search(text, 0, k) or _AUTOLINK.match(text, k)):
-                k = end + 1
-                continue
-            if k + 1 < len(text) and re.match(r"[A-Za-z/!?]", text[k + 1]):
-                state = "tag"
-        k += 1
-    return state != ""
-
-
-def _hazard(line: str) -> bool:
-    """A line that may change how the lines after it render: a fence, an HTML
-    block (content starting with "<" after any container prefix, except one
-    closed comment), or a tag or comment left open. Nothing after a hazard
-    counts as certainly visible."""
-    if _FENCE_LIKE.match(line):
-        return True
-    content = line[_CONTAINER_PREFIX.match(line).end():]
-    if content.startswith("<") and not _CLOSED_COMMENT.fullmatch(content):
-        return True
-    return _open_tag(line)
-_TABLE_DELIM = re.compile(r" {0,3}\|?\s*:?-+:?\s*(?:\|\s*:?-+:?\s*)*\|?\s*")
-
-
-def _table_body_row(lines: list[str], k: int) -> bool:
-    """``lines[k]`` is a body row of a pipe table: a run of pipe lines that
-    starts after a blank line (a table does not interrupt a paragraph), whose
-    second line is a delimiter row, and ``lines[k]`` comes after it."""
-    if not _TABLE_ROW.match(lines[k]):
-        return False
-    first = k
-    while first > 0 and _TABLE_ROW.match(lines[first - 1]):
-        first -= 1
-    return (k >= first + 2 and (first == 0 or not lines[first - 1].strip())
-            and _TABLE_DELIM.fullmatch(lines[first + 1]) is not None)
-
-
-def _certainly_visible(text: str, pos: int) -> bool:
-    line_start = text.rfind("\n", 0, pos) + 1
-    line_end = text.find("\n", pos)
-    line_end = len(text) if line_end < 0 else line_end
-    lines = text[:line_end].split("\n")
-    if any(_hazard(line) for line in lines):
-        return False
-    line = lines[-1]
-    if _in_html_comment(text, pos) or _indented_code(lines):
-        return False
-    if _table_body_row(lines, len(lines) - 1):
-        cell_start = max((m.end() for m in re.finditer(r"(?<!\\)\|", line[:pos - line_start])), default=0)
-        return "`" not in line[cell_start:pos - line_start]
-    start = len(lines) - 1  # walk back to the first line of the block
-    while start > 0 and not _BLOCK_START.match(lines[start]) and lines[start - 1].strip():
-        start -= 1
-    block_start = sum(len(item) + 1 for item in lines[:start])
-    return "`" not in text[block_start:pos]
-
-
-def _in_html_comment(text: str, pos: int) -> bool:
-    opened = text.rfind("<!--", 0, pos)
-    if opened < 0:
-        return False
-    closed = text.find("-->", opened + 4)
-    return closed < 0 or closed >= pos
-
-
-def _indented_code(lines: list[str]) -> bool:
-    """The last line may be indented code: 4+ columns of indentation, unless it
-    is a list item inside a real list, i.e. its block (no blank line between)
-    starts at a top-level list item (fail-closed)."""
-    if not _INDENTED.match(lines[-1]):
-        return False
-    if not _LIST_ITEM.match(lines[-1]):
-        return True
-    k = len(lines) - 2
-    while k >= 0 and lines[k].strip():
-        if _TOP_LIST_ITEM.match(lines[k]):
-            return False
-        if not (_INDENTED.match(lines[k]) and _LIST_ITEM.match(lines[k])):
-            return True
-        k -= 1
-    return True
-
-
-def _block_span(text: str, pos: int) -> tuple[int, int]:
-    """Offsets of the whole block holding ``pos`` (a table body row is its
-    own block)."""
-    lines = text.split("\n")
-    k = text.count("\n", 0, pos)
-    start = end = k
-    if not _table_body_row(lines, k):
-        while start > 0 and not _BLOCK_START.match(lines[start]) and lines[start - 1].strip():
-            start -= 1
-        while end + 1 < len(lines) and lines[end + 1].strip() \
-                and not _BLOCK_START.match(lines[end + 1]) and not _table_body_row(lines, end + 1):
-            end += 1
-    offset = sum(len(line) + 1 for line in lines[:start])
-    return offset, offset + len("\n".join(lines[start:end + 1]))
-
-
-def _block_context(text: str, pos: int) -> tuple[str, tuple[str, ...]]:
-    """The block holding ``pos`` and the hazard lines before it: the same block
-    after the same hazards renders the same way."""
-    start, end = _block_span(text, pos)
-    return text[start:end], tuple(line for line in text[:start].split("\n") if _hazard(line))
-
-
-def _contexts(text: str) -> set[tuple[str, tuple[str, ...]]]:
-    starts = [0] + [m.end() for m in re.finditer("\n", text)]
-    return {_block_context(text, pos) for pos in starts}
 
 
 @dataclass(frozen=True)
@@ -550,93 +380,47 @@ def _index_mechanical(path: str, base_text: str | None, head_text: str | None,
                             f"index lines must cover new pages {expected_new} and only link unlisted pages; got {files}"))
 
 
-def _link_occurrences(directory: str, text: str, *, certain: bool = False
-                      ) -> list[tuple[str, str, tuple[int, ...]]]:
-    """Relative links of an index as (written target without anchor, resolved
-    knowledge-relative path, positions of the link text and, for a reference,
-    its definition). URLs and anchor-only links are not targets; a link that
-    leaves the knowledge tree resolves to a path starting ``..``. ``certain``
-    keeps only links that are certainly visible (see above); a reference
-    counts only where it is used."""
-    def target_of(match) -> str:
-        return match.group("angle") if match.group("angle") is not None else match.group("target")
-
-    def keep(match) -> bool:
-        # visible where it starts, and no backtick anywhere in the link text
-        # itself (one there opens a code span that swallows the link)
-        # and no markup in or open before it on its line (a comment or a tag
-        # attribute swallows what looks like a link)
-        if not certain:
-            return True
-        line_start = text.rfind("\n", 0, match.start()) + 1
-        body = match.group(0)
-        if "angle" in match.re.groupindex and match.group("angle") is not None:
-            # the <destination> delimiters are link syntax, not markup
-            lo, hi = match.start("angle") - 1 - match.start(), match.end("angle") + 1 - match.start()
-            body = body[:lo] + match.group("angle") + body[hi:]
-        return (_certainly_visible(text, match.start()) and "`" not in body and "<" not in body
-                and not _open_tag(text[line_start:match.start()]))
-
-    # every definition of a label: which one renders depends on which are in
-    # code, so resolution checks all of them, and navigation trusts a label
-    # only when it has exactly one definition and that one is visible
-    definitions: dict[str, list] = {}
-    for m in _MD_REF.finditer(text):
-        definitions.setdefault(m.group("label").strip().lower(), []).append(m)
-    # resolution reads every "](" and "[..]" form; navigation only whole links
-    link, full, short = (_NAV_LINK, _NAV_REF_FULL, _NAV_REF_SHORT) if certain \
-        else (_MD_LINK, _REF_FULL, _REF_SHORT)
-    used = [(m.group("label").strip().lower() or m.group("text").strip().lower(), m.start())
-            for m in full.finditer(text) if keep(m)]
-    used += [(m.group("label").strip().lower(), m.start())
-             for m in short.finditer(text) if keep(m)]
-    found: list[tuple[str, tuple[int, ...]]] = [
-        (target_of(m), (m.start(),)) for m in link.finditer(text) if keep(m)]
-    for label, pos in used:
-        defs = definitions.get(label, [])
-        if not certain:
-            found += [(target_of(m), (pos, m.start())) for m in defs]
-        elif len(defs) == 1 and keep(defs[0]):
-            found.append((target_of(defs[0]), (pos, defs[0].start())))
-    out = []
-    for raw, positions in found:
-        target = raw.split("#", 1)[0]
-        if not target or "://" in target or target.startswith("mailto:"):
-            continue
-        resolved = ".." if target.startswith("/") else \
-            posixpath.normpath(posixpath.join(directory, target))  # absolute: never inside
-        out.append((target, resolved, positions))
-    return out
+_MARKDOWN = None
+
 
+def _links(text: str) -> list[str]:
+    """The link destinations a CommonMark renderer (with GitHub's pipe tables)
+    makes of ``text``, as written (still percent-encoded). The parser settles
+    what a hand-written matcher cannot: reference definitions, titles, escapes,
+    code spans and blocks, HTML blocks and comments. Images are not links, and
+    neither is anything in an image's alt text."""
+    global _MARKDOWN
+    if _MARKDOWN is None:
+        from markdown_it import MarkdownIt  # lazy: only index checks need it
 
-def _link_targets(directory: str, text: str, *, certain: bool = False) -> dict[str, str]:
-    """{written target: resolved path} of ``_link_occurrences``."""
-    return {written: resolved for written, resolved, _ in _link_occurrences(directory, text, certain=certain)}
+        _MARKDOWN = MarkdownIt("commonmark").enable("table")
+    out: list[str] = []
 
+    def walk(tokens) -> None:
+        for token in tokens:
+            if token.type == "link_open":
+                out.append(str(token.attrGet("href") or ""))
+            if token.children and token.type != "image":
+                walk(token.children)
 
-def _dropped_links(directory: str, before: str, after: str) -> set[str]:
-    """Links ``before`` has that ``after`` may no longer show, fail-closed: a
-    link is kept only when it is certainly visible in ``after``, or every block
-    it sits in is unchanged in ``after`` after the same fence-like lines."""
-    raw_after = _link_targets(directory, after)
-    visible_after = _link_targets(directory, after, certain=True)
-    contexts_after = _contexts(after)
-    dropped = set()
-    for written, _resolved, positions in _link_occurrences(directory, before):
-        if written not in raw_after:
-            dropped.add(written)
-        elif written not in visible_after and not all(
-                _block_context(before, pos) in contexts_after for pos in positions):
-            dropped.add(written)
-    return dropped
+    walk(_MARKDOWN.parse(text))
+    return out
 
 
-def _unparsed_links(text: str) -> set[str]:
-    """Each "](" no inline-link pattern accounts for, as its line: link syntax
-    the checker cannot read is refused rather than skipped."""
-    parsed = {m.start() for m in _MD_LINK.finditer(text)}
-    return {text[text.rfind("\n", 0, i) + 1:].split("\n", 1)[0].strip()
-            for i in (m.start() for m in re.finditer(r"\]\(", text)) if i not in parsed}
+def _link_targets(directory: str, text: str) -> dict[str, str]:
+    """Relative links of an index: {destination without anchor: resolved
+    knowledge-relative path}. URLs and anchor-only links are not targets; a
+    link that leaves the knowledge tree resolves to a path starting ``..``,
+    and an absolute one keeps its own normalised ``/...`` path (both escape)."""
+    out: dict[str, str] = {}
+    for href in _links(text):
+        parts = urlsplit(href)  # split first: an encoded "#" or ":" is part of the name
+        if parts.scheme or parts.netloc or not parts.path:
+            continue
+        target = unquote(parts.path)
+        out[target] = posixpath.normpath(target) if target.startswith("/") else \
+            posixpath.normpath(posixpath.join(directory, target))
+    return out
 
 
 def _dir_entries(head: Mapping[str, str], directory: str) -> list[str]:
@@ -660,7 +444,7 @@ def _index_created(path: str, base: Mapping[str, str], head: Mapping[str, str],
         issues.append(Issue("index_added_or_deleted", path,
                             "an index may be created only for a new directory"))
         return
-    linked = set(_link_targets(directory, head[path], certain=True).values())
+    linked = set(_link_targets(directory, head[path]).values())
     for entry in _dir_entries(head, directory):
         if entry not in linked:
             issues.append(Issue("index_missing", path, f"{entry} is not linked"))
@@ -668,7 +452,7 @@ def _index_created(path: str, base: Mapping[str, str], head: Mapping[str, str],
         parent = posixpath.join(posixpath.dirname(directory), INDEX_NAME)
         # a parent index created in the same change set reports its own children
         if parent in base and parent in head and path not in set(
-                _link_targets(posixpath.dirname(parent), head[parent], certain=True).values()):
+                _link_targets(posixpath.dirname(parent), head[parent]).values()):
             issues.append(Issue("index_missing", parent, f"the new {path} is not linked"))
     blocks.append(Block("prose", path, "", "prose", _sha(head[path])))
 
@@ -678,6 +462,8 @@ def check_index_links(base: Mapping[str, str], head: Mapping[str, str]) -> list[
     link the change adds resolves inside the knowledge tree to a file (or a
     directory) of ``head``; a changed index keeps every link it had; every
     page or child index new in ``head`` is linked from its parent index.
+    Links are what a CommonMark renderer makes (``_links``): text in code, a
+    comment or an HTML block is not a link, so moving a link there drops it.
     Links an index already had are not re-judged (some point into doc/)."""
     issues: list[Issue] = []
     head_dirs = {posixpath.dirname(p) for p in head}
@@ -687,14 +473,15 @@ def check_index_links(base: Mapping[str, str], head: Mapping[str, str]) -> list[
         directory = posixpath.dirname(path)
         before = _link_targets(directory, base.get(path) or "")
         after = _link_targets(directory, head[path])
-        for line in sorted(_unparsed_links(head[path]) - _unparsed_links(base.get(path) or "")):
-            issues.append(Issue("index_link_unparsed", path, line[:120]))
-        for written in sorted(_dropped_links(directory, base.get(path) or "", head[path])):
-            issues.append(Issue("index_link_dropped", path, written))
+        kept = set(after.values())
+        for written, resolved in sorted(before.items()):
+            if resolved not in kept:
+                issues.append(Issue("index_link_dropped", path, written))
+        had = set(before.values())
         for written, resolved in sorted(after.items()):
-            if written in before:
+            if resolved in had:
                 continue
-            if resolved == ".." or resolved.startswith("../"):
+            if resolved == ".." or resolved.startswith(("../", "/")):
                 issues.append(Issue("index_link_escapes", path, written))
             elif resolved not in head and not any(d == resolved or d.startswith(resolved + "/")
                                                   for d in head_dirs):
@@ -710,7 +497,7 @@ def check_index_links(base: Mapping[str, str], head: Mapping[str, str]) -> list[
             if directory:  # the knowledge root has no index
                 issues.append(Issue("index_unlinked", page, f"{parent} does not exist"))
             continue
-        if page not in set(_link_targets(directory, head[parent], certain=True).values()):
+        if page not in set(_link_targets(directory, head[parent]).values()):
             issues.append(Issue("index_unlinked", page, f"{parent} does not link it"))
     return issues
 
diff --git a/test/test_kb_init_l1.py b/test/test_kb_init_l1.py
index a8ea8cf1..f99196ac 100644
--- a/test/test_kb_init_l1.py
+++ b/test/test_kb_init_l1.py
@@ -156,201 +156,106 @@ def test_index_links_read_titles_angles_and_reference_definitions():
                       ("index_link_escapes", "../../../ref.md")}
 
 
-def test_unused_reference_definitions_are_not_links():
-    base = _base()
-    head = _new_repo(base)
-    head["repos/new/core/_index.md"] = "# core\n\n[c]: cards.md\n"   # defined, never used
-    issues = {(i.code, i.path) for i in check_index_links(base, head)}
-    assert ("index_unlinked", "repos/new/core/cards.md") in issues
-    head["repos/new/core/_index.md"] = "# core\n\n- [Cards][c]\n\n[c]: cards.md\n"
-    assert check_index_links(base, head) == []
-    head["repos/new/core/_index.md"] = "# core\n\n- [c]\n\n[C]: cards.md\n"  # shortcut, case-folded
-    assert check_index_links(base, head) == []
+def _unlinked(base, head) -> bool:
+    return ("index_unlinked", "repos/new/core/cards.md") in {
+        (i.code, i.path) for i in check_index_links(base, head)}
 
 
-def test_code_never_hides_a_link_from_the_resolution_checks():
-    """Every link-like text is resolved, even one that may sit in code."""
-    base = _base()
-    head = _new_repo(base)
-    core = "repos/new/core/_index.md"
-    for tail in (
-        "```example```\n\n- [broken](missing.md)\n",           # inline code, not a fence
-        "`` literal [broken](missing.md) `\n",                   # unmatched backticks
-        "A literal ` here.\n\n[broken](missing.md)\n\nAnother literal ` here.\n",
-        "\\` [broken](missing.md) `\n",                          # escaped backtick
-        "- ```\n  example\n  ```\n\n[broken](missing.md)\n",     # fence inside a list
-        "~~~\n- [broken](missing.md)\n",                          # inside a real fence
-    ):
-        head[core] = "# core\n\n- [cards](cards.md)\n\n" + tail
-        assert {i.code for i in check_index_links(base, head)} == {"index_link_broken"}, tail
-
-
-def test_only_certainly_visible_links_count_as_navigation():
+def test_text_that_renders_no_link_does_not_link_a_page():
+    """Links are what a CommonMark renderer makes, not what looks like one."""
     base = _base()
     head = _new_repo(base)
     core = "repos/new/core/_index.md"
     for text in (
-        "# core\n\n`` a ```` [cards](cards.md) ``\n",          # unequal runs: inside code
-        "# core\n\nsee `code\n[cards](cards.md)` here\n",       # span across a line break
-        "# core\n\n```\n\n- [cards](cards.md)\n",                # after a fence-like line
-        "# core\n\n[cards]`example`(cards.md)\n",                # not a link at all
+        "# core\n\n    [cards](cards.md)\n",                   # indented code
+        "# core\n\n\t[cards](cards.md)\n",                     # tab-indented code
+        "# core\n\n```\n- [cards](cards.md)\n```\n",           # fenced code
+        "# core\n\n~~~\n- [cards](cards.md)\n",                  # unclosed fence runs to the end
+        "# core\n\n- `[cards](cards.md)`\n",                     # code span
+        "# core\n\n`` a ```` [cards](cards.md) ``\n",            # code span with unequal inner runs
+        "# core\n\nsee `code\n[cards](cards.md)` here\n",        # code span across a line break
+        "# core\n\n<!-- [cards](cards.md) -->\n",              # HTML comment
+        "# core\n\n<!--\n- [cards](cards.md)\n",               # unclosed comment block
+        "# core\n\n<div>\n[cards](cards.md)\n</div>\n",        # HTML block
+        "# core\n\n> <div>\n> [cards](cards.md)\n> </div>\n",  # HTML block inside a quote
+        "# core\n\n- [cards <!--](cards.md) -->\n",             # comment swallows the destination
+        '# core\n\n- <span title="[cards](cards.md)">x</span>\n',  # link text in an attribute
+        '# core\n\ntext <span title=">[cards](cards.md)">x</span>\n',
+        "# core\n\n- cards](cards.md)\n",                        # no opening bracket
+        "# core\n\n- \\[cards](cards.md)\n",                    # escaped bracket
+        "# core\n\n- ![cards](cards.md)\n",                      # an image, not a link
+        "# core\n\n- ![alt [cards](cards.md)](image.png)\n",      # a link inside alt text
+        "# core\n\n- [cards](cards.md%23missing)\n",             # an encoded "#" is in the name
+        "# core\n\n[cards]`example`(cards.md)\n",                # never a link
+        "# core\n\n[c]: cards.md\n",                             # a definition nobody uses
+        # a definition cannot interrupt a paragraph (gate repro)
+        "# core\n\nordinary paragraph\n[c]: cards.md\n\n- [cards][c]\n",
+        # an escaped quote does not close a title: no link (gate repro)
+        '# core\n\n- [cards](cards.md "bad\\")\n',
     ):
         head[core] = text
-        issues = {(i.code, i.path) for i in check_index_links(base, head)}
-        assert ("index_unlinked", "repos/new/core/cards.md") in issues, text
-    # a table cell is its own block: code in another cell does not matter
-    head[core] = "# core\n\n| page | note |\n|---|---|\n| `x/y` | [cards](cards.md) |\n"
-    assert check_index_links(base, head) == []
-
-
-def test_a_definition_in_code_cannot_shadow_the_real_one():
-    base = _base()
-    head = dict(base)
-    head["repos/old/_index.md"] = (base["repos/old/_index.md"]
-                                   + "[x][r]\n\n```\n[r]: rules.md\n```\n\n[r]: ../../../secret.md\n")
-    issues = {(i.code, i.detail) for i in check_index_links(base, head)}
-    assert ("index_link_escapes", "../../../secret.md") in issues
-
-
-def test_pipe_lines_without_a_table_header_are_not_table_cells():
-    base = _base()
-    head = _new_repo(base)
-    core = "repos/new/core/_index.md"
-    head[core] = "# core\n\n| `example | [cards](cards.md)` |\n"
-    issues = {(i.code, i.path) for i in check_index_links(base, head)}
-    assert ("index_unlinked", "repos/new/core/cards.md") in issues
-    # a table right after a paragraph line is not a table either (GFM)
-    head[core] = "# core\ntext `a\n| h | i |\n|---|---|\n| x | [cards](cards.md) |\n"
-    issues = {(i.code, i.path) for i in check_index_links(base, head)}
-    assert ("index_unlinked", "repos/new/core/cards.md") in issues
-
-
-def test_a_visible_link_after_code_that_becomes_code_is_dropped():
-    base = _base()
-    base["repos/old/_index.md"] = "# old\n\n- `rules` [rules](rules.md)\n"
-    head = dict(base)
-    head["repos/old/_index.md"] = "# old\n\n- `rules [rules](rules.md)\n"
-    assert {i.code for i in check_index_links(base, head)} == {"index_link_dropped"}
-    # unchanged block, unrelated edit elsewhere: kept
-    head["repos/old/_index.md"] = base["repos/old/_index.md"] + "\nmore words\n"
-    assert check_index_links(base, head) == []
-
-
-def test_a_link_after_a_closed_fence_that_reopens_is_dropped():
-    base = _base()
-    base["repos/old/_index.md"] = "# old\n\n```\nx\n```\n\n- [rules](rules.md)\n"
-    head = dict(base)
-    head["repos/old/_index.md"] = "# old\n\n```\nx\n\n- [rules](rules.md)\n"
-    assert {i.code for i in check_index_links(base, head)} == {"index_link_dropped"}
-    head["repos/old/_index.md"] = base["repos/old/_index.md"] + "\n- [more](rules.md#a)\n"
-    assert check_index_links(base, head) == []
-
-
-def test_moving_a_closing_fence_past_an_unchanged_link_drops_it():
-    base = _base()
-    base["repos/old/_index.md"] = "# old\n\n```\nx\n```\n\n- [rules](rules.md)\n"
-    head = dict(base)
-    head["repos/old/_index.md"] = "# old\n\n```\nx\n\n- [rules](rules.md)\n\n```\n"
-    assert {i.code for i in check_index_links(base, head)} == {"index_link_dropped"}
+        assert _unlinked(base, head), text
 
 
-def test_indented_code_html_comments_and_html_blocks_are_not_navigation():
+def test_text_that_renders_a_link_links_the_page():
     base = _base()
     head = _new_repo(base)
     core = "repos/new/core/_index.md"
+    head["repos/new/core/it's.md"] = "# it's\n"
+    head["repos/new/core/中文 页.md"] = "# 中文\n"
+    head["repos/new/core/a:b.md"] = "# a:b\n"
     for text in (
-        "# core\n\n    [cards](cards.md)\n",                 # indented code
-        "# core\n\n\t[cards](cards.md)\n",                   # tab-indented code
-        "# core\n\n<!-- [cards](cards.md) -->\n",            # HTML comment
-        "# core\n\n<!--\n- [cards](cards.md)\n",             # unclosed comment
-        "# core\n\n<div>\n[cards](cards.md)\n</div>\n",      # HTML block
-    ):
-        head[core] = text
-        issues = {(i.code, i.path) for i in check_index_links(base, head)}
-        assert ("index_unlinked", "repos/new/core/cards.md") in issues, text
-    for text in (
-        "# core\n\n<div>\n- [cards](cards.md)\n</div>\n",   # HTML block across a list item
-        "# core\n\n    - group\n    - [cards](cards.md)\n",  # consecutive indented lines: code
-        "# core\n\ntext <!--\n\n- [cards](cards.md)\n",     # comment left open mid-line
-        "# core\n\n> <div>\n> [cards](cards.md)\n> </div>\n",  # HTML block inside a quote
-        "# core\n\n- [cards <!--](cards.md) -->\n",           # comment swallows the destination
-        '# core\n\n- <span title="[cards](cards.md)">x</span>\n',  # link text in an attribute
-        '# core\n\ntext <span title="\n[cards](cards.md)">x</span>\n',  # tag open across lines
-        '# core\n\ntext <span title=">[cards](cards.md)">x</span>\n',  # ">" inside a quoted value
+        "# core\n\n- [cards](cards.md)\n",
+        "# core\n\n- [cards](cards.md \"title\")\n",
+        "# core\n\n- [cards](<cards.md>)\n",
+        "# core\n\n- [Cards][c]\n\n[c]: cards.md\n",
+        "# core\n\n- [c]\n\n[C]: <cards.md>\n",                  # shortcut, case-folded
+        "# core\n\n- `rules` [cards](cards.md)\n",               # code before the link
+        "# core\n\n- `open [cards](cards.md)\n",                 # unmatched backtick is literal
+        "# core\n\ntext <!--\n\n- [cards](cards.md)\n",           # an inline comment left open is text
+        "# core\n\n<div>\n\n- [cards](cards.md)\n\n</div>\n",     # an HTML block ends at a blank line
+        "# core\n\n```\nx\n```\n\n- [cards](cards.md)\n",          # after a closed fence
+        "# core\n\n- group\n    - [cards](cards.md)\n",            # nested list item
+        "# core\n\n| page | note |\n|---|---|\n| `x | [cards](cards.md)` |\n",  # a cell ends a span
+        'see <span title="a > b">x</span> and [cards](cards.md)\n',
     ):
-        head[core] = text
-        issues = {(i.code, i.path) for i in check_index_links(base, head)}
-        assert ("index_unlinked", "repos/new/core/cards.md") in issues, text
-    # angle-bracket destinations are links, inline or in a definition
-    for text in ("# core\n\n- [cards](<cards.md>)\n", "# core\n\n- [Cards][c]\n\n[c]: <cards.md>\n",
-                 '# core\n\nsee <span title="a > b">x</span> and [cards](cards.md)\n'):
-        head[core] = text
-        assert check_index_links(base, head) == [], text
-    # a quote inside an angle destination or an autolink is not an HTML attribute
-    head["repos/new/core/it's.md"] = "# it's\n"
-    for text in ("# core\n\n- [it](<it's.md>)\n- [cards](cards.md)\n",
-                 "# core\n\n- [It][i]\n- [cards](cards.md)\n\n[i]: <it's.md>\n",
-                 "# core\n\nsee <https://example.com/a'b> and [cards](cards.md) and [it](<it's.md>)\n"):
-        head[core] = text
+        head[core] = "- [it](<it's.md>)\n- [zh](<中文 页.md>)\n- [ab](a%3Ab.md)\n\n" + text
         assert check_index_links(base, head) == [], text
-    head.pop("repos/new/core/it's.md")
-    # a nested list item indented 4 columns is still a list item
-    head[core] = "# core\n\n- group\n    - [cards](cards.md)\n"
-    assert check_index_links(base, head) == []
-    # a closed comment before the link does not hide it
-    head[core] = "# core\n\n<!-- note -->\n\n- [cards](cards.md)\n"
-    assert check_index_links(base, head) == []
 
 
-def test_moving_a_link_into_indented_code_or_a_comment_drops_it():
+def test_moving_a_link_where_it_no_longer_renders_drops_it():
     base = _base()
-    for moved in ("# old\n\n    - [rules](rules.md)\n", "# old\n\n<!-- - [rules](rules.md) -->\n",
-                  "# old\n\n<!--\n\n- [rules](rules.md)\n\n-->\n",
-                  "# old\n\n<div>\n\n- [rules](rules.md)\n\n</div>\n",
-                  '# old\n\ntext <span title=">- [rules](rules.md)">x</span>\n'):
+    for moved in ("# old\n\n- `[rules](rules.md)`\n",
+                  "# old\n\n    - [rules](rules.md)\n",
+                  "# old\n\n<!-- - [rules](rules.md) -->\n",
+                  "# old\n\n```\nx\n\n- [rules](rules.md)\n\n```\n",
+                  "# old\n\n- rules](rules.md)\n",
+                  "# old\n\n- ![alt [rules](rules.md)](image.png)\n",
+                  "# old\n\n- [rules](rules.md%23x)\n",
+                  '# old\n\n- [rules](rules.md "bad\\")\n'):
         head = {**base, "repos/old/_index.md": moved}
-        assert {i.code for i in check_index_links(base, head)} == {"index_link_dropped"}, moved
+        assert "index_link_dropped" in {i.code for i in check_index_links(base, head)}, moved
 
 
-def test_navigation_needs_a_whole_unescaped_link():
+def test_absolute_links_keep_their_own_identity():
     base = _base()
-    head = _new_repo(base)
-    core = "repos/new/core/_index.md"
-    for text in (
-        "# core\n\n- cards](cards.md)\n",       # no opening bracket
-        "# core\n\n- \\[cards](cards.md)\n",    # escaped bracket
-        "# core\n\n- [](cards.md)\n",           # empty label
-        "# core\n\n- ![cards](cards.md)\n",     # an image, not a link
-        "# core\n\n- [cards `](cards.md)`\n",   # a backtick in the label opens a code span
-        "# core\n\n- [Cards][c]\n\n[c]: `cards.md`\n",
-    ):
-        head[core] = text
-        issues = {(i.code, i.path) for i in check_index_links(base, head)}
-        assert ("index_unlinked", "repos/new/core/cards.md") in issues, text
-    head[core] = "# core\n\n- [cards \\] x](cards.md)\n"   # escaped bracket inside a label is fine
-    assert check_index_links(base, head) == []
-    # and a malformed replacement of an existing link drops it
-    for broken in ("# old\n\n- rules](rules.md)\n", "# old\n\n- [rules `](rules.md)`\n"):
-        head = {**base, "repos/old/_index.md": broken}
-        assert "index_link_dropped" in {i.code for i in check_index_links(base, head)}, broken
+    base["repos/old/_index.md"] += "- [old](/docs/a.md)\n"
+    head = {**base, "repos/old/_index.md": base["repos/old/_index.md"] + "- [new](/outside/b.md)\n"}
+    issues = {(i.code, i.detail) for i in check_index_links(base, head)}
+    assert issues == {("index_link_escapes", "/outside/b.md")}
+    head["repos/old/_index.md"] = base["repos/old/_index.md"].replace("/docs/a.md", "/outside/b.md")
+    issues = {(i.code, i.detail) for i in check_index_links(base, head)}
+    assert issues == {("index_link_dropped", "/docs/a.md"), ("index_link_escapes", "/outside/b.md")}
 
 
-def test_bootstrap_coverage_uses_the_same_navigation_rules():
+def test_links_in_code_are_not_resolved_either():
     base = _base()
     head = _new_repo(base)
-    head["repos/new/core/_index.md"] = "# core\n\n    [cards](cards.md)\n"
-    result = check_changeset(base, head, _changes(base, head), bootstrap=True)
-    assert any(i.code == "index_missing" and "cards.md" in i.detail for i in result.issues)
-
-
-def test_moving_a_link_into_code_drops_it():
-    base = _base()
-    head = dict(base)
-    head["repos/old/_index.md"] = "# old\n\n- `[rules](rules.md)`\n"
-    assert {i.code for i in check_index_links(base, head)} == {"index_link_dropped"}
+    head["repos/new/core/_index.md"] = "# core\n\n- [cards](cards.md)\n\n```\n[x](missing.md)\n```\n"
+    assert check_index_links(base, head) == []
 
 
-def test_duplicate_definitions_are_all_resolved_and_never_navigation():
+def test_the_first_reference_definition_wins():
     base = _base()
     head = _new_repo(base)
     head["repos/new/core/_index.md"] = "# core\n\n- [Cards][c]\n\n[c]: missing.md\n[c]: cards.md\n"
@@ -360,6 +265,15 @@ def test_duplicate_definitions_are_all_resolved_and_never_navigation():
                       ("index_unlinked", "repos/new/core/cards.md")}
 
 
+def test_a_definition_in_code_cannot_shadow_the_real_one():
+    base = _base()
+    head = dict(base)
+    head["repos/old/_index.md"] = (base["repos/old/_index.md"]
+                                   + "[x][r]\n\n```\n[r]: rules.md\n```\n\n[r]: ../../../secret.md\n")
+    issues = {(i.code, i.detail) for i in check_index_links(base, head)}
+    assert ("index_link_escapes", "../../../secret.md") in issues
+
+
 def test_removing_a_reference_usage_drops_the_link():
     base = _base()
     base["repos/old/_index.md"] = "# old\n\n- [Rules][r]\n\n[r]: rules.md\n"
@@ -368,13 +282,12 @@ def test_removing_a_reference_usage_drops_the_link():
     assert {i.code for i in check_index_links(base, head)} == {"index_link_dropped"}
 
 
-def test_index_links_detect_dropped_titled_links_and_refuse_unparsed_syntax():
+def test_bootstrap_coverage_uses_rendered_links():
     base = _base()
-    base["repos/old/_index.md"] = '# old\n\n- [rules](rules.md "the rules")\n'
-    head = dict(base)
-    head["repos/old/_index.md"] = '# old\n\n- [x](rules.md "unterminated\n'
-    issues = {i.code for i in check_index_links(base, head)}
-    assert issues == {"index_link_dropped", "index_link_unparsed"}
+    head = _new_repo(base)
+    head["repos/new/core/_index.md"] = "# core\n\n    [cards](cards.md)\n"
+    result = check_changeset(base, head, _changes(base, head), bootstrap=True)
+    assert any(i.code == "index_missing" and "cards.md" in i.detail for i in result.issues)
 
 
 def test_index_links_ignore_urls_anchors_and_links_the_base_already_had():

From 6b070ccf14702dad2863e33d796e07b753fed3d0 Mon Sep 17 00:00:00 2001
From: tzhouam <tzhouam@connect.ust.hk>
Date: Wed, 30 Sep 2026 18:34:24 +0800
Subject: [PATCH 4/4] Accept index links to the knowledge root

A link such as [Knowledge](../..) from repos/<repo>/_index.md resolves
to the knowledge root, which check_index_links looked up among head's
directories and never found (top-level files have dirname "", the
link resolves to "."), so it reported index_link_broken for a valid
link. The root is now a directory every tree has; a link above it
still escapes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 doc/architecture/SPEC/knowledge_service/l1.md   | 2 +-
 src/infermatrix_copilot/knowledge_service/l1.py | 2 ++
 test/test_kb_init_l1.py                         | 9 +++++++++
 3 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/doc/architecture/SPEC/knowledge_service/l1.md b/doc/architecture/SPEC/knowledge_service/l1.md
index e7648c11..711a0617 100644
--- a/doc/architecture/SPEC/knowledge_service/l1.md
+++ b/doc/architecture/SPEC/knowledge_service/l1.md
@@ -38,7 +38,7 @@
   再只对路径做百分号解码；引用定义、标题、转义、代码段/代码块、
   HTML 块/注释都由解析器按渲染器的方式处理，不手写匹配。URL、纯锚点不算目标。
   对每个新增或改动的 `_index.md`：
-  - 本次新增的链接必须解析到 head 中的文件或目录、不得逃出知识树（`index_link_broken` /
+  - 本次新增的链接必须解析到 head 中的文件或目录（知识树根目录本身，如 `../..`，算已存在的目录）、不得逃出知识树（`index_link_broken` /
     `index_link_escapes`，绝对路径保留各自的 `/…` 身份且一律算逃逸；base 已有的链接不重新判定——
     有些指向 `doc/`）。
   - 保留：base 的链接（按解析后的路径）必须仍在 head 的链接里，否则 `index_link_dropped`——把链接挪进
diff --git a/src/infermatrix_copilot/knowledge_service/l1.py b/src/infermatrix_copilot/knowledge_service/l1.py
index d89ecf85..66d0d49c 100644
--- a/src/infermatrix_copilot/knowledge_service/l1.py
+++ b/src/infermatrix_copilot/knowledge_service/l1.py
@@ -483,6 +483,8 @@ def check_index_links(base: Mapping[str, str], head: Mapping[str, str]) -> list[
                 continue
             if resolved == ".." or resolved.startswith(("../", "/")):
                 issues.append(Issue("index_link_escapes", path, written))
+            elif resolved in (".", ""):
+                continue  # the knowledge root itself: a directory every tree has
             elif resolved not in head and not any(d == resolved or d.startswith(resolved + "/")
                                                   for d in head_dirs):
                 issues.append(Issue("index_link_broken", path, written))
diff --git a/test/test_kb_init_l1.py b/test/test_kb_init_l1.py
index f99196ac..3f6a0ae8 100644
--- a/test/test_kb_init_l1.py
+++ b/test/test_kb_init_l1.py
@@ -306,3 +306,12 @@ def test_only_kb_init_may_pass_bootstrap():
         if path not in allowed and re.search(r"bootstrap\s*=\s*True", path.read_text(encoding="utf-8"))
     ]
     assert offenders == []
+
+
+def test_index_links_accept_the_knowledge_root_and_its_directories():
+    base = _base()
+    head = dict(base)
+    head["repos/old/_index.md"] += "- [Knowledge](../..)\n- [Knowledge](../../)\n- [Repos](..)\n"
+    assert check_index_links(base, head) == []
+    head["repos/old/_index.md"] += "- [Above](../../..)\n"
+    assert [(i.code, i.detail) for i in check_index_links(base, head)] == [("index_link_escapes", "../../..")]