docs: ausgelieferte Doku zitiert keine Issue-Nummern mehr, docs verify prueft es (schliesst #77)

Files changed:
- .gitignore
- CHANGES.md
- EVALS.md
- INSTALL.md
- README.md
- VERSION
- docs/pipeline-rationale.md
- instructions/CONTRACT.md
- instructions/bootstrap.md
- instructions/dev/issue-tracking.md
- instructions/evolve-subtypes.md
- instructions/kb-profiles.md
- instructions/mcp-read-server.md
- instructions/wiki-ingest/SKILL.md
- kb/CONTRACT.md
- kb/concepts/COLLECTION.md
- kb/sources/COLLECTION.md
- raw/CONTRACT.md
- tools/.coveragerc
- tools/CONTRACT.md
- tools/README.md
- tools/chemenu/commands/docs_verify.py
- tools/chemenu/tests/test_docs_verify.py
- types/source.schema.yaml
- types/type-spec.md

tools/chemenu/tests/test_docs_verify.py

@@ -2,7 +2,7 @@ import pytest
 import typer
 
 from chemenu import config
-from chemenu.commands import docs_verify
+from chemenu.commands import dist_cmd, docs_verify
 
 
 def test_every_registered_command_is_documented():
@@ -348,3 +348,98 @@ def test_verify_raises_when_content_is_ignored(monkeypatch):
     monkeypatch.setattr(docs_verify, "check_ignored_content", lambda: ["swallowed"])
     with pytest.raises(typer.Exit):
         docs_verify.verify()
+
+
+# --- issue references in shipped documents -----------------------------------
+
+
+def test_no_shipped_document_cites_an_issue():
+    """Forward direction, against the real tree: a `#42` in a file `dist export`
+    ships points at a board only the origin repo has, and the reader of a
+    distributed instance can neither resolve it nor tell that it is
+    unresolvable."""
+    assert docs_verify.check_no_issue_references() == []
+
+
+def test_a_cited_issue_number_is_reported(monkeypatch):
+    monkeypatch.setattr(
+        docs_verify,
+        "shipped_prose",
+        lambda: {"instructions/example.md": "A rule.\nRemoved in Gitea #66.\n"},
+    )
+    issues = docs_verify.check_no_issue_references()
+    assert len(issues) == 1
+    assert "instructions/example.md:2" in issues[0]
+    assert "#66" in issues[0]
+
+
+def test_a_markdown_anchor_is_not_an_issue_reference(monkeypatch):
+    """The reason this check can be a bare pattern at all: a link anchor and a
+    heading are word characters, so neither collides with `#<digits>`."""
+    monkeypatch.setattr(
+        docs_verify,
+        "shipped_prose",
+        lambda: {
+            "AGENTS.md": (
+                "# Heading\n"
+                "See [Gates](#gates) and [Collections](kb/CONTRACT.md#collections).\n"
+                "Exit code 42 means a human must look.\n"
+            )
+        },
+    )
+    assert docs_verify.check_no_issue_references() == []
+
+
+def test_python_source_is_out_of_scope():
+    """The scope decision, pinned: `tools/` ships as runtime machinery, and a
+    code comment addresses whoever edits that line - which only ever happens in
+    the origin repo, because `dist export` prunes the `stack-dev` skill with the
+    rest of `instructions/dev/`. So a `.py` file is in the export plan and out
+    of the scanned set."""
+    plan = dist_cmd.build_plan()
+    scanned = docs_verify.shipped_prose()
+
+    assert "tools/chemenu/commands/raw_cmd.py" in plan
+    assert not [path for path in scanned if path.endswith(".py")]
+
+    # ...while the prose beside it is scanned, templates included.
+    assert "tools/CONTRACT.md" in scanned
+    assert "instructions/CONTRACT.md" in scanned
+    assert "types/source.schema.yaml.template" in scanned
+
+
+def test_a_strip_marked_pointer_never_reaches_the_check():
+    """The sanctioned way to keep a pointer that is worth having here and
+    meaningless anywhere else. `shipped_prose` reads the export plan, whose text
+    already has its marker regions removed, so a number inside a marker block is
+    present in the working tree and absent from what ships.
+
+    Asserted over whichever files carry a marker today rather than a named one,
+    so retiring any single passage does not fail this for an unrelated reason -
+    what is pinned is that the mechanism works, not where it is used.
+    """
+    shipped = docs_verify.shipped_prose()
+    # Destination paths only coincide with source paths where nothing was
+    # re-keyed (`types/*.md` ships as `.template`), so the ones that do not
+    # exist in the tree are simply not this test's subject.
+    sources = {
+        path: source.read_text(encoding="utf-8")
+        for path in shipped
+        if (source := config.ROOT / path).is_file()
+    }
+    hidden = {
+        path: source
+        for path, source in sources.items()
+        if "dist:strip-start" in source and docs_verify.ISSUE_REFERENCE_RE.search(source)
+    }
+
+    assert hidden, "no shipped document keeps an issue number behind a strip marker"
+    for path, source in hidden.items():
+        assert docs_verify.ISSUE_REFERENCE_RE.search(source)
+        assert not docs_verify.ISSUE_REFERENCE_RE.search(shipped[path]), path
+
+
+def test_verify_raises_when_a_shipped_document_cites_an_issue(monkeypatch):
+    monkeypatch.setattr(docs_verify, "check_no_issue_references", lambda: ["cited"])
+    with pytest.raises(typer.Exit):
+        docs_verify.verify()