@ikon85/agent-workflow-kit 0.10.0

package/scripts/test_skill_setup_workflow_seeds.py

@@ -0,0 +1,200 @@
+#!/usr/bin/env python3
+"""setup-workflow seed + idempotency-rule spec (Welle 26 / Slice 5 / #989).
+
+`/setup-workflow` is a prompt-driven skill, so its interactive run is verified
+live (mock fresh-fill + in-repo idempotent re-run). This file pins the two parts
+that ARE machine-checkable:
+
+1. The seed templates it ships are structurally valid for their consumers, so a
+   fresh fill cannot produce a project layer that makes a downstream skill warn.
+2. The sentinel-based idempotency rule, as a reference implementation + the
+   canonical example table the skill's prose must satisfy (Codex R1 #12 strict
+   `state=` header; R2 #2 terminal `not-applicable`; R3 legacy no-sentinel skip).
+
+It does NOT test Claude's execution of the prose — that is the live-verify.
+
+Run: python3 scripts/test_skill_setup_workflow_seeds.py
+"""
+import json
+import re
+import unittest
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent
+SKILL = REPO / ".claude/skills/setup-workflow"
+
+SENTINEL_RE = re.compile(
+    r"^<!--\s*setup-workflow:\s*state=(stub|filled|not-applicable)"
+    r"(?:;\s*mode=(github-projects-v2|none))?\s*-->\s*$"
+)
+
+
+# ---- Reference implementation of the documented idempotency rule -------------
+def classify(first_line, is_empty):
+    """Return the action the skill must take for one target file.
+
+    first_line: the file's first line, or None if the file does not exist.
+    is_empty:   True if the file is empty/whitespace-only.
+    """
+    if first_line is None:
+        return "create"
+    m = SENTINEL_RE.match(first_line.strip())
+    if m:
+        return "fill" if m.group(1) == "stub" else "skip"
+    # No sentinel: non-empty legacy file is left alone; empty is fillable.
+    return "create" if is_empty else "skip"
+
+
+class IdempotencyRule(unittest.TestCase):
+    CASES = [
+        # (first_line, is_empty, expected)
+        (None, False, "create"),                                      # missing
+        ("<!-- setup-workflow: state=stub -->", False, "fill"),       # stub
+        ("<!-- setup-workflow: state=filled -->", False, "skip"),     # filled
+        ("<!-- setup-workflow: state=stub; mode=github-projects-v2 -->", False, "fill"),
+        ("<!-- setup-workflow: state=filled; mode=github-projects-v2 -->", False, "skip"),
+        ("<!-- setup-workflow: state=not-applicable; mode=none -->", False, "skip"),
+        ("# Board sync — GitHub Projects field-IDs", False, "skip"),  # legacy non-empty
+        ("", True, "create"),                                         # empty no-sentinel
+    ]
+
+    def test_canonical_examples(self):
+        for first, empty, expected in self.CASES:
+            self.assertEqual(
+                classify(first, empty), expected, f"{first!r} empty={empty}"
+            )
+
+    def test_filled_file_mentioning_marker_in_body_is_not_refilled(self):
+        # Only the FIRST line decides; a body mention must not flip it (Codex R1 #12).
+        first = "<!-- setup-workflow: state=filled -->"
+        self.assertEqual(classify(first, False), "skip")
+
+
+class SeedTemplatesValid(unittest.TestCase):
+    def test_spec_completeness_seed_has_valid_self_critique_block(self):
+        """A convention without a valid Trigger/Check/Korrektur block makes
+        spec-self-critique point 8 warn — the seed must carry one (Codex R1 #14)."""
+        t = (SKILL / "spec-completeness-seed.md").read_text(encoding="utf-8")
+        self.assertIn("## Self-Critique-Check", t)
+        for kw in ("Trigger", "Check", "Korrektur"):
+            self.assertRegex(t, rf"\*\*{kw}", f"missing {kw} in Self-Critique-Check")
+
+    def test_spec_self_critique_seed_has_12_point_anchors(self):
+        """Stable retro-append anchors for points 1..12 (Codex R1 #15)."""
+        t = (SKILL / "spec-self-critique-seed.md").read_text(encoding="utf-8")
+        anchors = sorted(int(n) for n in re.findall(r"^## Point (\d+)\b", t, re.M))
+        self.assertEqual(anchors, list(range(1, 13)))
+
+    def test_orchestrate_wave_seed_has_section_contract(self):
+        """The orchestrate-wave project-layer seed carries the exact §-section
+        headings the skill's Phase-0 probe matches (#1958). If a heading is
+        renamed here without updating the skeleton (or vice versa) the probe
+        stops finding the section — this pins the contract on both sides."""
+        seed = (SKILL / "orchestrate-wave-seed.md").read_text(encoding="utf-8")
+        skeleton = (REPO / ".claude/skills/orchestrate-wave/SKILL.md").read_text(encoding="utf-8")
+        sections = [
+            "§Setup", "§Builder Commands", "§Builder Hard Rules",
+            "§Integration Suites", "§Verify Recipe", "§Headless Login", "§Landing",
+        ]
+        for sec in sections:
+            self.assertRegex(seed, rf"(?m)^#+ {re.escape(sec)}\b", f"seed missing heading {sec!r}")
+            self.assertIn(sec, skeleton, f"skeleton no longer refers to {sec!r}")
+
+    def test_board_sync_seed_documents_states_and_profile(self):
+        t = (SKILL / "board-sync.md").read_text(encoding="utf-8")
+        for token in ("state=filled", "state=stub", "state=not-applicable", "Status"):
+            self.assertIn(token, t)
+
+    def test_workflow_overview_seed_is_generic_and_linked_from_skill(self):
+        """Fresh repos should get an entry-point map without Testreporter-local lore.
+
+        The expected skill set is derived from the manifest's `entryPoint` flag
+        (publish:true skills only) rather than a hand-maintained token list —
+        it used to hardcode 5 names while the manifest already carried 13
+        publish:true entry-point-worthy skills, so the seed silently drifted
+        behind (#1890: `ask-matt`, the router, was missing entirely)."""
+        manifest = json.loads((REPO / ".claude/skills/skill-manifest.json").read_text(encoding="utf-8"))
+        expected = sorted(
+            name for name, meta in manifest["skills"].items()
+            if meta.get("publish") and meta.get("entryPoint")
+        )
+        self.assertGreaterEqual(len(expected), 10, "manifest entryPoint set looks too small")
+
+        seed = (SKILL / "workflow-overview.md").read_text(encoding="utf-8")
+        skill = (SKILL / "SKILL.md").read_text(encoding="utf-8")
+
+        self.assertIn("# Workflow", seed)
+        for name in expected:
+            self.assertIn(name, seed, f"entry-point skill {name!r} (manifest entryPoint:true) missing from seed")
+        self.assertIn("ask-matt", seed, "router entry must be named explicitly")
+        self.assertNotIn("Testreporter", seed)
+        self.assertIn("workflow-overview.md", skill)
+        self.assertIn("## Workflow", skill)
+
+    def test_triage_labels_seed_matches_two_label_reality(self):
+        """The seed presented at setup-workflow fill-time must not contradict
+        the triage skill's actual label vocabulary: it used to list five
+        canonical roles as if all were active labels, but the triage skill
+        only ever applies two — the rest live in board status. A fresh fill
+        from the old seed taught agents to assign three dead labels (#1879)."""
+        seed = (SKILL / "triage-labels.md").read_text(encoding="utf-8")
+        triage_skill = (REPO / ".claude/skills/triage/SKILL.md").read_text(encoding="utf-8")
+
+        for label in ("needs-info", "ready-for-agent"):
+            self.assertIn(f"`{label}`", seed)
+            self.assertIn(f"`{label}`", triage_skill)
+
+        # The retired roles must not appear in the table portion (before the
+        # board-status explainer) as if they were still active labels.
+        table, sep, explainer = seed.partition("Board status is authoritative")
+        self.assertTrue(sep, "seed must explain that board status is authoritative")
+        for retired in ("needs-triage", "ready-for-human", "wontfix"):
+            self.assertNotIn(f"`{retired}`", table)
+
+        self.assertIn("Board status is authoritative", seed)
+        self.assertIn("Board status is authoritative", triage_skill)
+
+
+class SentinelProtectsFilledProfile(unittest.TestCase):
+    """A consumer's filled board profile must never be rewritten on rerun."""
+
+    def test_filled_public_profile_is_left_unchanged_on_rerun(self):
+        real_profile = REPO / "docs/agents/board-sync.md"
+        text = real_profile.read_text(encoding="utf-8")
+        first_line = text.splitlines()[0]
+        self.assertEqual(
+            classify(first_line, False), "skip",
+            "a filled project profile must classify as skip, never re-fillable",
+        )
+        # Prove this is genuinely filled (not an accidental stub), otherwise
+        # the "skip" assertion above would be vacuous.
+        self.assertIn('"repo": "iKon85/agent-workflow-kit"', text)
+        self.assertIn('"vorBau": "Clarify Before Build"', text)
+
+    def test_unfilled_stub_gets_english_defaults(self):
+        stub_first_line = "<!-- setup-workflow: state=stub; mode=github-projects-v2 -->"
+        self.assertEqual(classify(stub_first_line, False), "fill")
+
+        seed = (SKILL / "board-sync.md").read_text(encoding="utf-8")
+        self.assertIn('"retroValues": ["ran", "skipped"]', seed)
+        self.assertIn('"vorBau": "Clarify Before Build"', seed)
+        self.assertNotIn("gefahren", seed)
+        self.assertNotIn("Vor Bau zu klären", seed)
+
+
+class FreshFillProducesValidSentinels(unittest.TestCase):
+    """Simulate the write step: prepend the documented sentinel to a template
+    body and assert the result is a well-formed project-layer file."""
+
+    def test_prepended_sentinel_parses(self):
+        body = (SKILL / "spec-self-critique-seed.md").read_text(encoding="utf-8")
+        for state, mode in (("stub", None), ("filled", "github-projects-v2"),
+                            ("not-applicable", "none")):
+            sentinel = f"<!-- setup-workflow: state={state}" + (
+                f"; mode={mode}" if mode else "") + " -->"
+            written = sentinel + "\n" + body
+            self.assertRegex(written.splitlines()[0], SENTINEL_RE)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

package/scripts/test_skill_stale_name_lint.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""Stale-skill-name lint (Welle 26 / Slice 5 / #989).
+
+When a skill is renamed (here: `setup-matt-pocock-skills` -> `setup-workflow`),
+every ACTIVE reference must move with it, or consumer skills point at a command
+that no longer exists (Codex R1 #1: `to-issues/SKILL.md:10` still invoked the
+deleted name). This lint fails on any active reference to a retired skill name.
+
+ACTIVE reference = a form that would actually misroute: a slash invocation
+(`/<name>`), a frontmatter `name:` value, a `.../skills/<name>` dir/path reference,
+or a manifest JSON key (`"<name>":`).
+
+EXPLICITLY NOT a violation (Codex R2 #1): legitimate *attribution prose* that names
+the upstream skill — the provenance upstream-path `engineering/<name>/`, a manifest
+`note`, or a SKILL.md description "adapted from <name>". Those credit the upstream,
+they don't route anywhere. The active-form patterns below match none of them. A
+per-line `stale-name-lint: ok` marker also exempts a single line.
+
+Run: python3 scripts/test_skill_stale_name_lint.py
+"""
+import re
+import unittest
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent
+
+# Retired skill names that must have zero active references anywhere we scan.
+RETIRED_NAMES = ["setup-matt-pocock-skills"]
+
+LINT_OK = "stale-name-lint: ok"
+
+
+def _active_patterns(name):
+    """Forms that would actually misroute to a non-existent skill.
+
+    Boundary-guarded so neither the provenance path `engineering/<name>/` nor
+    attribution prose (`adapted from <name>`, a manifest note) matches.
+    """
+    n = re.escape(name)
+    return [
+        re.compile(rf"(?<![\w/])/{n}(?![\w/-])"),  # slash invocation /<name>
+        re.compile(rf"name:\s*{n}\b"),             # frontmatter name:
+        re.compile(rf"skills/{n}\b"),              # .claude|.agents/skills/<name>
+        re.compile(rf'"{n}"\s*:'),                 # manifest JSON key
+    ]
+
+
+def _scan_files():
+    """Files where an active reference would actually mislead a consumer."""
+    files = []
+    for root in ("CLAUDE.md", "AGENTS.md"):
+        p = REPO / root
+        if p.is_file():
+            files.append(p)
+    for d in (".claude/skills", ".agents/skills", "docs"):
+        base = REPO / d
+        if base.is_dir():
+            files.extend(base.rglob("*.md"))
+    manifest = REPO / ".claude/skills/skill-manifest.json"
+    if manifest.is_file():
+        files.append(manifest)
+    return files
+
+
+def _violations_for(name):
+    """Return list of (file, lineno, line) with an active reference to `name`."""
+    patterns = _active_patterns(name)
+    out = []
+    for f in _scan_files():
+        try:
+            text = f.read_text(encoding="utf-8")
+        except (UnicodeDecodeError, OSError):
+            continue
+        for i, line in enumerate(text.splitlines(), start=1):
+            if name not in line or LINT_OK in line:
+                continue
+            if any(p.search(line) for p in patterns):
+                out.append((f.relative_to(REPO), i, line.strip()))
+    return out
+
+
+class StaleSkillName(unittest.TestCase):
+    def test_no_active_references_to_retired_skill_names(self):
+        all_v = []
+        for name in RETIRED_NAMES:
+            all_v.extend(_violations_for(name))
+        msg = "\n".join(f"  {f}:{n}: {ln}" for f, n, ln in all_v)
+        self.assertEqual(
+            all_v,
+            [],
+            f"\nActive references to retired skill name(s) found "
+            f"(rename them or add `{LINT_OK}`):\n{msg}",
+        )
+
+    def test_attribution_prose_is_not_flagged(self):
+        """Credit forms that name the upstream must NOT be treated as violations."""
+        for name in RETIRED_NAMES:
+            patterns = _active_patterns(name)
+            for benign in (
+                f"| `setup-workflow` | generic | `engineering/{name}/` |",
+                f"adapted from Matt Pocock's `{name}` (MIT)",
+                f'"note": "evolved from {name} (Welle 26)"',
+            ):
+                self.assertFalse(
+                    any(p.search(benign) for p in patterns),
+                    f"attribution prose should be exempt: {benign!r}",
+                )
+
+    def test_active_forms_are_flagged(self):
+        """The misrouting forms must be caught."""
+        for name in RETIRED_NAMES:
+            patterns = _active_patterns(name)
+            for active in (
+                f"run `/{name}` if not",
+                f"name: {name}",
+                f".claude/skills/{name}/SKILL.md",
+                f'"{name}": {{ "class": "vendored" }}',
+            ):
+                self.assertTrue(
+                    any(p.search(active) for p in patterns),
+                    f"active form should be flagged: {active!r}",
+                )
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

package/scripts/test_skill_surface_refs.py

@@ -0,0 +1,300 @@
+#!/usr/bin/env python3
+"""Skill surface-reference lint (Welle 49 / Slice 2 / #1873).
+
+Every `/skill-name` or backtick `` `skill-name` `` a SKILL.md names must
+resolve to a skill that exists as a directory on the SAME surface the
+referencing file lives on. `skill-manifest.json`'s `surfaces` array is the
+SSOT for which trees (`.claude/skills`, `.agents/skills`) host a skill.
+
+Two independent checks:
+
+  MISMATCH — an exact backtick reference to a REAL manifest skill NOT hosted
+  on the referencing file's surface (a Claude-only skill named from a
+  Codex-surface file, or vice-versa). This is the class behind the
+  Codex-escalation dangling-target finding and the `/code-review` dangling:
+  a PUBLISHED skill can pass the existing publish audit
+  (`auditSkillNameRefs` in `scripts/lib/audit-refs.mjs`, which only checks
+  *publish status*) while still dangling on ONE surface — that audit has no
+  concept of `surfaces` at all.
+
+  NONEXISTENT — a `/name` slash-token styled as a catalog entry (a list item
+  opening with an optionally-bold backtick slash-token, the convention every
+  genuine skill listing in this repo uses, e.g. `- **`/tdd`** — ...`) that
+  names NO manifest skill anywhere — a typo'd or dead name in a router list.
+
+`class: "adapter"` skills (e.g. `codex-adapter-sync`) are exempt from
+MISMATCH: their purpose is to be invoked FROM the opposite surface —
+Claude-side prose runs the Codex-mirror-sync tool that itself lives only
+under `.agents/skills` (manifest note: "published skills reference it as the
+Claude→Codex mirror step"). That's the intended direction, not a dangler.
+
+Deliberate exceptions: an inline marker on the line (`Claude Code only`, or
+the generic `skill-surface-lint: ok`), or `PROSE_ALLOWLIST` below for
+skill-system PROSE in files this slice doesn't touch (each entry carries its
+own reason — an explicit, auditable allowlist, not a blanket exemption).
+
+Run: python3 scripts/test_skill_surface_refs.py
+"""
+import json
+import re
+import unittest
+from pathlib import Path
+
+from test_skill_portability_lint import load_manifest, SKILL_DIRS
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+TREE_SURFACE = {".claude/skills": "claude", ".agents/skills": "codex"}
+
+EXEMPT = "skill-surface-lint: ok"
+CLAUDE_ONLY_MARKER = "Claude Code only"
+
+# Slash-tokens a catalog bullet can legitimately name without matching any
+# manifest skill: either a real command OUTSIDE this repo's manifest (a
+# Claude Code CLI built-in, or — like `handoff` — a skill living in the
+# user's global `~/.claude/skills`, never a repo skill directory; ask-matt
+# names both, formatted exactly like a real catalog entry, `/compact` even
+# self-annotates "(built-in)"), or a documented TEMPLATE PLACEHOLDER in
+# third-party (vendored, not ours to rewrite) skill prose — `impeccable`'s
+# recommended-actions template repeats `/command-name` as a fill-in-the-blank,
+# not a specific skill.
+EXTERNAL_COMMANDS = {"compact", "handoff", "command-name"}
+
+# Deliberate skill-system PROSE that NAMES a skill without inviting an
+# operator on THIS surface to invoke it — not a routing reference. Each is a
+# file this slice does not edit (see #1873 scope); (relpath, distinctive
+# line substring, reason).
+PROSE_ALLOWLIST = [
+    (".agents/skills/ask-matt/SKILL.md",
+     "Folder↔upstream-name note:",
+     "identity blockquote names its own upstream-name mapping (Matt "
+     "Pocock's write-a-skill == upstream writing-great-skills), not a "
+     "routing invocation"),
+    (".agents/skills/sync-upstream-skills/SKILL.md",
+     "write-a-skill` = upstream `writing-great-skills`",
+     "folder↔upstream naming-convention example, not an invocation"),
+    (".agents/skills/codex-adapter-sync/SKILL.md",
+     "grill-with-docs-codex`, `grill-me-codex`, Chase AI's cross-model",
+     "rule-doc prose naming the escalation-target-rewrite pattern by "
+     "example, describing the very class this lint catches"),
+]
+
+# A markdown list item that OPENS with an (optionally bold) backtick
+# slash-token — the sole convention every genuine skill-catalog entry in
+# this repo uses (`- **`/tdd`** — ...`). Deliberately excludes inline/prose
+# slash mentions (route examples, `/tmp`, upstream-repo slugs) which never
+# open a bullet this way.
+BULLET_ENTRY = re.compile(r"^\s*(?:[-*]|\d+\.)\s+\*{0,2}`([^`\n]+)`")
+NAME_SHAPE = re.compile(r"^(/?)([a-z][a-z0-9]*(?:-[a-z0-9]+)*)$")
+
+
+def escape_name(name: str) -> str:
+    return re.escape(name)
+
+
+def name_pattern(name: str) -> re.Pattern:
+    """A backtick-wrapped exact reference (`` `/name` `` or `` `name` ``) OR a
+    boundary-guarded bare slash-token — mirrors the proven construction in
+    `scripts/lib/audit-refs.mjs`'s `auditSkillNameRefs` (same repo, same
+    problem shape: a name match that ignores doc paths / repo slugs, since
+    `owner/name` and `skills/name` never satisfy either alternative — the
+    char immediately before the match is excluded by the boundary guard)."""
+    e = escape_name(name)
+    return re.compile(rf"`/?{e}`|(?<![\w/-])/{e}(?![\w-])")
+
+
+def is_allowlisted(relpath: str, line: str) -> bool:
+    return any(relpath == path and substr in line
+               for path, substr, _reason in PROSE_ALLOWLIST)
+
+
+def find_mismatches(surface: str, relpath: str, text: str, manifest: dict) -> list[str]:
+    """Lines on `surface` naming a real manifest skill not hosted there."""
+    problems = []
+    for lineno, line in enumerate(text.splitlines(), 1):
+        if EXEMPT in line or CLAUDE_ONLY_MARKER in line or is_allowlisted(relpath, line):
+            continue
+        for name, entry in manifest.items():
+            if entry.get("class") == "adapter":
+                continue
+            if surface in entry.get("surfaces", []):
+                continue
+            if name_pattern(name).search(line):
+                problems.append(
+                    f"{relpath}:{lineno}: `{name}` not hosted on '{surface}' "
+                    f"(hosted={entry.get('surfaces', [])}): {line.strip()}")
+    return problems
+
+
+def find_nonexistent(relpath: str, text: str, manifest: dict) -> list[str]:
+    """Catalog-style bullets naming a slash-token that matches NO manifest
+    skill anywhere and is not a known external command."""
+    problems = []
+    for lineno, line in enumerate(text.splitlines(), 1):
+        if EXEMPT in line:
+            continue
+        m = BULLET_ENTRY.match(line)
+        if not m:
+            continue
+        shape = NAME_SHAPE.match(m.group(1))
+        if not shape or not shape.group(1):
+            continue
+        name = shape.group(2)
+        if name in manifest or name in EXTERNAL_COMMANDS:
+            continue
+        problems.append(f"{relpath}:{lineno}: `/{name}` names no skill anywhere: {line.strip()}")
+    return problems
+
+
+def iter_skill_markdown():
+    """Yield (surface, relpath-as-posix-string, text) for every distributed
+    *.md under every skill directory on both trees."""
+    for tree in SKILL_DIRS:
+        surface = TREE_SURFACE[tree]
+        base = REPO_ROOT / tree
+        if not base.is_dir():
+            continue
+        for skill_dir in sorted(p for p in base.iterdir() if p.is_dir()):
+            for md in sorted(skill_dir.rglob("*.md")):
+                relpath = md.relative_to(REPO_ROOT).as_posix()
+                yield surface, relpath, md.read_text(encoding="utf-8")
+
+
+class PatternDetectorFixtures(unittest.TestCase):
+    """Fixture (a)+(c): a manufactured Codex-surface skill naming a
+    Claude-only manifest skill is red unmarked, green once marked."""
+
+    MANIFEST = {
+        "claude-only-skill": {"class": "vendored", "surfaces": ["claude"]},
+        "dual-skill": {"class": "generic", "surfaces": ["claude", "codex"]},
+        "the-adapter": {"class": "adapter", "surfaces": ["codex"]},
+    }
+
+    def test_unmarked_claude_only_ref_on_codex_surface_is_red(self):
+        text = "- **`/claude-only-skill`** — does a thing."
+        problems = find_mismatches("codex", "fixture/SKILL.md", text, self.MANIFEST)
+        self.assertEqual(len(problems), 1)
+        self.assertIn("claude-only-skill", problems[0])
+
+    def test_marked_claude_only_ref_is_green(self):
+        text = "- **`/claude-only-skill`** (Claude Code only) — does a thing."
+        self.assertEqual(find_mismatches("codex", "fixture/SKILL.md", text, self.MANIFEST), [])
+
+    def test_dual_surface_ref_is_always_green(self):
+        text = "- **`/dual-skill`** — does a thing."
+        self.assertEqual(find_mismatches("codex", "fixture/SKILL.md", text, self.MANIFEST), [])
+
+    def test_adapter_class_target_is_exempt_both_directions(self):
+        text = "run **`/the-adapter`** after editing a skill."
+        self.assertEqual(find_mismatches("claude", "fixture/SKILL.md", text, self.MANIFEST), [])
+
+    def test_doc_path_and_repo_slug_are_not_matched(self):
+        text = ("see `docs/agents/skills/claude-only-skill.md` or the upstream "
+                "repo `someorg/claude-only-skill`")
+        self.assertEqual(find_mismatches("codex", "fixture/SKILL.md", text, self.MANIFEST), [])
+
+    def test_generic_exempt_marker_is_line_scoped(self):
+        text = "- **`/claude-only-skill`** <!-- skill-surface-lint: ok -->"
+        self.assertEqual(find_mismatches("codex", "fixture/SKILL.md", text, self.MANIFEST), [])
+
+
+class NonexistentFixtures(unittest.TestCase):
+    """Fixture (b): a catalog bullet naming a skill that exists nowhere."""
+
+    MANIFEST = {"tdd": {"class": "vendored", "surfaces": ["claude", "codex"]}}
+
+    def test_wholly_nonexistent_skill_bullet_is_red(self):
+        text = "- **`/frobnicate-widget`** — does a thing that never existed."
+        problems = find_nonexistent("fixture/SKILL.md", text, self.MANIFEST)
+        self.assertEqual(len(problems), 1)
+        self.assertIn("frobnicate-widget", problems[0])
+
+    def test_known_skill_bullet_is_green(self):
+        text = "- **`/tdd`** — test-driven development."
+        self.assertEqual(find_nonexistent("fixture/SKILL.md", text, self.MANIFEST), [])
+
+    def test_external_builtin_bullet_is_green(self):
+        text = "- **`/handoff`** — compacts the conversation."
+        self.assertEqual(find_nonexistent("fixture/SKILL.md", text, self.MANIFEST), [])
+
+    def test_inline_prose_slash_mention_is_not_a_catalog_entry(self):
+        text = "falling back to `/tmp` when $TMPDIR is unset."
+        self.assertEqual(find_nonexistent("fixture/SKILL.md", text, self.MANIFEST), [])
+
+    def test_route_example_list_is_not_flagged(self):
+        text = "- Product signals: `/app/*`, `/dashboard`, `/settings`, forms."
+        self.assertEqual(find_nonexistent("fixture/SKILL.md", text, self.MANIFEST), [])
+
+    def test_exempt_marker_line_scoped(self):
+        text = "- **`/frobnicate-widget`** <!-- skill-surface-lint: ok -->"
+        self.assertEqual(find_nonexistent("fixture/SKILL.md", text, self.MANIFEST), [])
+
+
+class AllowlistFixtures(unittest.TestCase):
+    """Fixture (d): the deliberate skill-system-prose exceptions stay green."""
+
+    MANIFEST = {"write-a-skill": {"class": "vendored", "surfaces": ["claude"]}}
+
+    def test_ask_matt_identity_blockquote_is_allowlisted(self):
+        text = ("> Homage. Folder↔upstream-name note: `/diagnose` = upstream "
+                "`diagnosing-bugs`, `/write-a-skill` = upstream `writing-great-skills`.")
+        problems = find_mismatches(
+            "codex", ".agents/skills/ask-matt/SKILL.md", text, self.MANIFEST)
+        self.assertEqual(problems, [])
+
+    def test_sync_upstream_skills_naming_note_is_allowlisted(self):
+        text = ("e.g. `diagnose` = upstream `diagnosing-bugs`, "
+                "`write-a-skill` = upstream `writing-great-skills`")
+        problems = find_mismatches(
+            "codex", ".agents/skills/sync-upstream-skills/SKILL.md", text, self.MANIFEST)
+        self.assertEqual(problems, [])
+
+    def test_codex_adapter_sync_rule_doc_example_is_allowlisted(self):
+        text = ("has no `.agents` mirror. Any Codex-side reference to that skill "
+                "name is a dangling target (e.g. `grill-with-docs-codex`, "
+                "`grill-me-codex`, Chase AI's cross-model Act-2 variants).")
+        manifest = {"grill-with-docs-codex": {"class": "vendored", "surfaces": ["claude"]},
+                    "grill-me-codex": {"class": "vendored", "surfaces": ["claude"]}}
+        problems = find_mismatches(
+            "codex", ".agents/skills/codex-adapter-sync/SKILL.md", text, manifest)
+        self.assertEqual(problems, [])
+
+    def test_allowlist_does_not_leak_to_other_files(self):
+        """The allowlist is (path, substring)-scoped — the SAME prose in a
+        DIFFERENT file must still be caught (regression guard)."""
+        text = ("e.g. `diagnose` = upstream `diagnosing-bugs`, "
+                "`write-a-skill` = upstream `writing-great-skills`")
+        problems = find_mismatches("codex", "fixture/other-skill/SKILL.md", text, self.MANIFEST)
+        self.assertEqual(len(problems), 1)
+
+
+class RealRepoSurfaceRefs(unittest.TestCase):
+    """The actual repo, end to end: every skill-name reference in every
+    SKILL.md resolves on its own surface (AC: green on HEAD)."""
+
+    def test_no_cross_surface_dangling_references(self):
+        manifest = load_manifest()["skills"]
+        problems = []
+        for surface, relpath, text in iter_skill_markdown():
+            problems.extend(find_mismatches(surface, relpath, text, manifest))
+        self.assertEqual(
+            problems, [],
+            "skill reference dangles on its own surface — either the target "
+            "doesn't ship there (mark `(Claude Code only)` / port a Codex "
+            "mirror) or this is deliberate prose (add a PROSE_ALLOWLIST "
+            "entry with a reason):\n" + "\n".join(problems))
+
+    def test_no_wholly_nonexistent_catalog_entries(self):
+        manifest = load_manifest()["skills"]
+        problems = []
+        for _surface, relpath, text in iter_skill_markdown():
+            problems.extend(find_nonexistent(relpath, text, manifest))
+        self.assertEqual(
+            problems, [],
+            "catalog bullet names a skill that exists on no surface — fix "
+            "the name, remove the stale entry, or add it to "
+            "EXTERNAL_COMMANDS if it's a real command outside this repo's "
+            "manifest:\n" + "\n".join(problems))
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)