@ikon85/agent-workflow-kit 0.10.0

package/scripts/test_skill_publish_audit.py

@@ -0,0 +1,300 @@
+#!/usr/bin/env python3
+"""Fail-closed publish audit for dist-kit/ (Welle 26 / Slice 6 / #990, Step 13).
+
+The scrub (scripts/lib/scrub.mjs) removes project-private tokens at build time;
+THIS audit is the BACKSTOP — it scans the assembled dist-kit/ and DENIES the
+publish if anything private survived. Scrub may be imperfect; this fails loud so
+nothing private ever ships silently.
+
+Deny classes (each with a negative fixture below):
+  - private repo slug `iKon85/Testreporter` + the bare project name
+  - board node/field IDs (`PVT…`) + status/wave/cluster option hashes
+  - private deploy domains (`*.iverra.de`), Coolify
+  - email addresses
+  - absolute home paths (`/home/<user>`)
+  - residual issue refs (`#NNN`) / hard-rule refs (`HRn`)
+  - unresolvable provenance cross-refs (`ADR-####` / `Welle N` / `Slice N`),
+    with a documented fixture/example allowlist (PROVENANCE_FIXTURE_SUFFIXES)
+  - `../` cross-skill reaches (skills/scripts/docs — NOT the CLI src, which
+    legitimately imports `../lib/…`)
+  - bare owner/maintainer names OUTSIDE the generated credit files
+  - high-entropy secrets (after exempting the manifest's own sha256 file-hashes)
+
+Allowlisted: the PUBLIC repo slug `iKon85/agent-workflow-kit`.
+File-exempt (credits legitimately name people): LICENSE, README.md, PROVENANCE.md,
+THIRD-PARTY-NOTICES.md — but these still may NOT carry board IDs / domains /
+secrets / the private repo slug.
+
+Run: python3 scripts/test_skill_publish_audit.py
+"""
+import json
+import re
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent
+PUBLIC_SLUG = "iKon85/agent-workflow-kit"
+CREDIT_FILES = {"LICENSE", "README.md", "PROVENANCE.md", "THIRD-PARTY-NOTICES.md"}
+PRIVATE_SKILLS = {
+    "drizzle", "migrations", "forecast-logic", "bug-bucketing", "iverra-brand",
+    "ui-ux-pro-max",
+}
+# pin SHAs are legitimate attribution (full forms exempted from high-entropy)
+KNOWN_PIN_HASHES = {
+    "2bf70051928429983de3b5718d277150926f8c89",
+    "ba71f82e8469395d3f7c4ed824334b16676e87a0",
+}
+
+# (label, regex) — denied EVERYWHERE, even in credit files.
+HARD_DENY = [
+    ("private repo slug", re.compile(r"iKon85/Testreporter")),
+    ("board node/field id", re.compile(r"PVT(?:SSF|F)?_[A-Za-z0-9]")),
+    ("private deploy domain", re.compile(r"[A-Za-z0-9.-]*\.iverra\.de")),
+    ("Coolify reference", re.compile(r"\bCoolify\b")),
+    ("email address", re.compile(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}")),
+    ("absolute home path", re.compile(r"/home/[A-Za-z0-9._-]+")),
+    ("home-encoded project slug", re.compile(r"-home-[a-z0-9]+-projects")),
+    ("issue ref", re.compile(r"#\d{3,5}\b")),
+    ("hard-rule ref", re.compile(r"\bHR\d+\b")),
+    ("project name", re.compile(r"[Tt]estreporter")),
+    ("kit issue ref", re.compile(r"\bkit#\d+\b")),
+]
+# Provenance cross-refs a kit consumer cannot resolve (no docs/adr dir, no wave
+# history). Denied EVERYWHERE except the documented fixture/example files below,
+# where a Welle/Slice/ADR token is legitimate CONTENT — synthetic PRD scenarios,
+# a template placeholder, illustrative ADR names, or board-sync's wave-prefix
+# parser examples — not project provenance. Keep in sync with scrub.mjs's PROV
+# class (which strips citation-shaped provenance from every other body/script).
+PROVENANCE_DENY = [
+    ("ADR ref", re.compile(r"\bADR-\d{3,4}\b")),
+    ("Welle ref", re.compile(r"\bWelle \d+\b")),
+    ("Slice ref", re.compile(r"\bSlice \d+[a-z]?\b")),
+]
+# Matched by dest-path SUFFIX so both surfaces (.claude/skills, .agents/skills)
+# resolve with one entry each.
+PROVENANCE_FIXTURE_SUFFIXES = (
+    "spec-self-critique/scenarios.md",        # synthetic Program-PRD fixtures
+    "to-issues/SKILL.md",                     # `Welle $WAVE / Slice 1a` title example
+    "improve-codebase-architecture/SKILL.md",  # illustrative `ADR-0007` example
+    "setup-workflow/domain.md",               # illustrative `ADR-0007` example
+    "docs/agents/wave-anchor-template.md",     # `Slice 1` / `Welle <N>` placeholders
+    "scripts/board-sync.py",                  # `Welle 7 — X` wave-prefix parser examples
+)
+# denied only OUTSIDE credit files (scrub should have neutralized these)
+BARE_PRIVATE = [
+    ("bare owner iKon85", re.compile(r"iKon85")),
+    ("maintainer name", re.compile(r"\bNiko\b")),
+]
+PARENT_REF = re.compile(r"\.\./")
+LONG_HEX = re.compile(r"\b[0-9a-f]{40,}\b")
+GH_TOKEN = re.compile(r"\b(?:ghp|gho|ghu|ghs|github_pat)_[A-Za-z0-9_]{20,}")
+
+
+def _parent_ref_scan_text(rel: str, text: str) -> str:
+    if rel != "scripts/loc_offender_core.py":
+        return text
+    # This is the portable path-traversal guard itself, not a cross-skill reach.
+    return "\n".join(
+        line for line in text.splitlines()
+        if 'p.startswith("../")' not in line and '"/../" in p' not in line
+    )
+
+
+def _known_hashes(root: Path) -> set:
+    hashes = set(KNOWN_PIN_HASHES)
+    pkg = root / "agent-workflow-kit.package.json"
+    if pkg.exists():
+        data = json.loads(pkg.read_text(encoding="utf-8"))
+        for f in data.get("files", []):
+            if "sha256" in f:
+                hashes.add(f["sha256"])
+    return hashes
+
+
+def _scan_file(rel: str, text: str, known_hashes: set) -> list:
+    out = []
+    base = Path(rel).name
+    credit = base in CREDIT_FILES
+    scan = text.replace(PUBLIC_SLUG, "")  # allowlist the public slug
+    for label, pat in HARD_DENY:
+        if pat.search(scan):
+            out.append(f"{rel}: {label}")
+    if not rel.endswith(PROVENANCE_FIXTURE_SUFFIXES):
+        for label, pat in PROVENANCE_DENY:
+            if pat.search(scan):
+                out.append(f"{rel}: {label}")
+    if not credit:
+        for label, pat in BARE_PRIVATE:
+            if pat.search(scan):
+                out.append(f"{rel}: {label}")
+    if not rel.startswith("src/") and PARENT_REF.search(_parent_ref_scan_text(rel, text)):
+        out.append(f"{rel}: ../ parent reference")
+    for m in LONG_HEX.finditer(text):
+        if m.group(0) not in known_hashes:
+            out.append(f"{rel}: high-entropy hex (possible secret)")
+            break
+    if GH_TOKEN.search(text):
+        out.append(f"{rel}: GitHub-token-like string")
+    return out
+
+
+def audit_dir(root) -> list:
+    """Return a list of violation strings ([] = clean = publishable)."""
+    root = Path(root)
+    known = _known_hashes(root)
+    violations = []
+    for f in sorted(root.rglob("*")):
+        if not f.is_file():
+            continue
+        rel = f.relative_to(root).as_posix()
+        raw = f.read_bytes()
+        if b"\x00" in raw:  # binary — skip
+            continue
+        violations += _scan_file(rel, raw.decode("utf-8", errors="replace"), known)
+    # project-private skill dirs must never appear in the kit
+    for surface in (".claude/skills", ".agents/skills"):
+        d = root / surface
+        if d.is_dir():
+            for child in d.iterdir():
+                if child.is_dir() and child.name in PRIVATE_SKILLS:
+                    violations.append(f"{surface}/{child.name}: project-private skill shipped")
+    return violations
+
+
+# --------------------------------------------------------------------------- #
+class AuditCatchesEachClass(unittest.TestCase):
+    """Inject one violation per class into a clean fixture → it must be caught."""
+
+    def setUp(self):
+        self.dir = Path(tempfile.mkdtemp())
+        # a minimal CLEAN kit
+        (self.dir / "agent-workflow-kit.package.json").write_text(
+            json.dumps({"kitVersion": "0.1.0", "files": [
+                {"path": ".claude/skills/x/SKILL.md", "sha256": "a" * 64}]}),
+            encoding="utf-8")
+        self.skill = self.dir / ".claude/skills/x"
+        self.skill.mkdir(parents=True)
+        (self.skill / "SKILL.md").write_text("# clean skill\nuse `#<n>` and #0f172a\n",
+                                             encoding="utf-8")
+
+    def _body(self, content):
+        (self.skill / "SKILL.md").write_text(content, encoding="utf-8")
+        return audit_dir(self.dir)
+
+    def test_clean_passes(self):
+        self.assertEqual(audit_dir(self.dir), [])
+
+    def test_private_slug(self):
+        self.assertTrue(any("repo slug" in v for v in self._body("see iKon85/Testreporter")))
+
+    def test_board_id(self):
+        self.assertTrue(any("board" in v for v in self._body("id PVT_kwHOAuH31M4BVtcf")))
+
+    def test_domain(self):
+        self.assertTrue(any("domain" in v for v in self._body("curl testreporter.iverra.de")))
+
+    def test_email(self):
+        self.assertTrue(any("email" in v for v in self._body("ping a@b.com please")))
+
+    def test_home_path(self):
+        self.assertTrue(any("home path" in v for v in self._body("at /home/niko/x")))
+
+    def test_home_encoded_slug(self):
+        leak = '$HOME/.claude/projects/-home-niko-projects-x/memory'
+        self.assertTrue(any("home-encoded" in v for v in self._body(leak)))
+
+    def test_issue_ref(self):
+        self.assertTrue(any("issue ref" in v for v in self._body("fixed in #824 now")))
+
+    def test_hr_ref(self):
+        self.assertTrue(any("hard-rule" in v for v in self._body("per HR16 rule")))
+
+    def test_kit_issue_ref(self):
+        self.assertTrue(any("kit issue ref" in v for v in self._body("see kit#27 §2")))
+
+    def test_adr_ref(self):
+        self.assertTrue(any("ADR ref" in v for v in self._body("per ADR-0034 rule")))
+
+    def test_welle_ref(self):
+        self.assertTrue(any("Welle ref" in v for v in self._body("built in Welle 52")))
+
+    def test_slice_ref(self):
+        self.assertTrue(any("Slice ref" in v for v in self._body("done in Slice 1g")))
+
+    def test_parent_ref(self):
+        self.assertTrue(any("parent" in v for v in self._body("[x](../../other/SKILL.md)")))
+
+    def test_bare_owner_in_body(self):
+        self.assertTrue(any("iKon85" in v for v in self._body("authored by iKon85")))
+
+    def test_secret(self):
+        self.assertTrue(any("secret" in v for v in self._body("token " + "d" * 50)))
+
+    def test_gh_token(self):
+        self.assertTrue(any("token" in v for v in self._body("ghp_" + "A" * 30)))
+
+    def test_private_skill_dir_flagged(self):
+        (self.dir / ".claude/skills/drizzle").mkdir(parents=True)
+        self.assertTrue(any("project-private" in v for v in audit_dir(self.dir)))
+
+
+class Exemptions(unittest.TestCase):
+    """Public slug is allowlisted; credit files may legitimately name people."""
+
+    def setUp(self):
+        self.dir = Path(tempfile.mkdtemp())
+        (self.dir / "agent-workflow-kit.package.json").write_text(
+            '{"kitVersion":"0.1.0","files":[]}', encoding="utf-8")
+
+    def _write(self, name, content):
+        (self.dir / name).write_text(content, encoding="utf-8")
+
+    def test_public_slug_allowed(self):
+        self._write("README.md", "npx github:iKon85/agent-workflow-kit init")
+        self.assertEqual(audit_dir(self.dir), [])
+
+    def test_credit_file_may_name_maintainer(self):
+        self._write("LICENSE", "Copyright (c) 2026 Niko (iKon85)\nMatt Pocock\nChase AI")
+        self.assertEqual(audit_dir(self.dir), [])
+
+    def test_credit_file_still_denies_board_id(self):
+        self._write("LICENSE", "Niko (iKon85) PVT_leak")
+        self.assertTrue(any("board" in v for v in audit_dir(self.dir)))
+
+    def test_manifest_own_hashes_not_flagged_as_secret(self):
+        # the package manifest's 64-hex file hashes are exempt (they ARE the kit's hashes)
+        (self.dir / "agent-workflow-kit.package.json").write_text(
+            json.dumps({"kitVersion": "0.1.0", "files": [
+                {"path": "x", "sha256": "f" * 64}]}), encoding="utf-8")
+        self.assertEqual(audit_dir(self.dir), [])
+
+    def test_loc_offender_traversal_guard_allowed(self):
+        p = self.dir / "scripts"
+        p.mkdir()
+        (p / "loc_offender_core.py").write_text(
+            'if p == ".." or p.startswith("../") or "/../" in p or p.endswith("/.."):\n'
+            '    return None\n',
+            encoding="utf-8")
+        self.assertEqual(audit_dir(self.dir), [])
+
+
+class RealDistKitIsClean(unittest.TestCase):
+    """Build dist-kit/ from SSOT and assert the audit passes (the publish gate)."""
+
+    def test_built_dist_kit_passes_audit(self):
+        build = REPO / "scripts/build-kit.mjs"
+        try:
+            r = subprocess.run(["node", str(build)], cwd=REPO,
+                               capture_output=True, text=True, timeout=120)
+        except (FileNotFoundError, subprocess.TimeoutExpired) as e:
+            self.skipTest(f"node/build unavailable: {e}")
+        self.assertEqual(r.returncode, 0, r.stderr)
+        violations = audit_dir(REPO / "dist-kit")
+        self.assertEqual(violations, [], "\n".join(violations[:40]))
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

package/scripts/test_skill_selfcontainment_lint.py

@@ -0,0 +1,255 @@
+#!/usr/bin/env python3
+"""Self-containment lint (Welle 26 / Slice 2 / #986): generic & vendored skills
+must be portable.
+
+Why: a published skill (npx/git-clone into a foreign repo, or a plugin cache)
+cannot resolve `../../../docs/...` — the path does not exist there and `../`
+escapes the plugin root. Project-specific content is found by *runtime
+convention* (an inline project-root path like `docs/agents/board-sync.md` that
+the model resolves from the project root), never a hardcoded `../` link.
+project-private skills are exempt: they live in this repo forever and their
+`../` refs are correct and clickable.
+
+Scope: skills whose manifest class is `generic` or `vendored`. Every distributed
+`*.md` file in the skill dir is scanned (SKILL.md + support docs), in both the
+Claude source (`.claude/skills`) and the Codex mirror (`.agents/skills`).
+
+A line carrying `self-containment-lint: ok` is exempt — line-scoped, for
+deliberate "don't do this" doc examples.
+
+Run: python3 scripts/test_skill_selfcontainment_lint.py
+"""
+import json
+import re
+import unittest
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+MANIFEST = REPO_ROOT / ".claude/skills/skill-manifest.json"
+SKILL_DIRS = [".claude/skills", ".agents/skills"]
+ENFORCED_CLASSES = {"generic", "vendored"}
+PUBLISH_CLASSES = {"generic", "vendored", "adapter"}
+VALID_CLASSES = {"generic", "vendored", "adapter", "project-private"}
+VALID_SURFACES = {"claude", "codex"}
+
+PARENT_REF = re.compile(r"\.\./")
+EXEMPT = "self-containment-lint: ok"
+
+
+def load_manifest() -> dict:
+    return json.loads(MANIFEST.read_text(encoding="utf-8"))
+
+
+def find_parent_refs(text: str) -> list[tuple[int, str]]:
+    """Return (line_no, line) for every line with a `../` reach, minus exempt lines."""
+    out = []
+    for n, line in enumerate(text.splitlines(), 1):
+        if EXEMPT in line:
+            continue
+        if PARENT_REF.search(line):
+            out.append((n, line.strip()))
+    return out
+
+
+def skill_dirs_on_disk(tree: str) -> set[str]:
+    base = REPO_ROOT / tree
+    if not base.is_dir():
+        return set()
+    # dot-dirs are tool caches (e.g. .impeccable/hook.cache.json, gitignored), not skills
+    return {p.name for p in base.iterdir() if p.is_dir() and not p.name.startswith(".")}
+
+
+class Detector(unittest.TestCase):
+    """The `../` detector itself behaves."""
+
+    def test_flags_parent_link(self):
+        self.assertEqual(len(find_parent_refs("see [x](../../../docs/y.md)")), 1)
+
+    def test_flags_parent_in_code(self):
+        self.assertEqual(len(find_parent_refs("import x from '../lib/y'")), 1)
+
+    def test_ignores_same_dir_relative(self):
+        self.assertEqual(find_parent_refs("see [x](./sub/y.md)"), [])
+
+    def test_ignores_root_relative_convention(self):
+        # the portable form: an inline project-root path, no `../`
+        self.assertEqual(find_parent_refs("read `docs/agents/board-sync.md`"), [])
+
+    def test_exempt_marker_line_scoped(self):
+        self.assertEqual(
+            find_parent_refs("bad: [x](../y) <!-- self-containment-lint: ok -->"), [])
+
+    def test_exempt_is_line_scoped_not_file_wide(self):
+        text = "ok line <!-- self-containment-lint: ok -->\n[x](../../bad)"
+        self.assertEqual(len(find_parent_refs(text)), 1)
+
+
+class ManifestValid(unittest.TestCase):
+    def test_schema_and_classes(self):
+        m = load_manifest()
+        self.assertEqual(m.get("schema_version"), 1)
+        for name, entry in m["skills"].items():
+            self.assertIn(entry.get("class"), VALID_CLASSES, name)
+            self.assertTrue(entry.get("surfaces"), f"{name}: no surfaces")
+            for s in entry["surfaces"]:
+                self.assertIn(s, VALID_SURFACES, f"{name}:{s}")
+            # publish is a mandatory bool — build-kit + lints consume it, not class
+            # (Slice 6 / #990 / Codex R2#3+#5).
+            self.assertIsInstance(entry.get("publish"), bool,
+                                  f"{name}: `publish` must be present and boolean")
+
+
+class ManifestCompleteness(unittest.TestCase):
+    """Manifest <-> filesystem, both trees (Codex R1#4 / R2#1)."""
+
+    def test_every_disk_skill_classified(self):
+        m = load_manifest()["skills"]
+        problems = [f"{tree}/{d} on disk but missing from manifest"
+                    for tree in SKILL_DIRS
+                    for d in sorted(skill_dirs_on_disk(tree)) if d not in m]
+        self.assertEqual(problems, [], "\n".join(problems))
+
+    def test_every_entry_matches_its_surfaces(self):
+        m = load_manifest()["skills"]
+        claude = skill_dirs_on_disk(".claude/skills")
+        agents = skill_dirs_on_disk(".agents/skills")
+        problems = []
+        for name, entry in m.items():
+            surfaces = set(entry.get("surfaces", []))
+            if "claude" in surfaces and name not in claude:
+                problems.append(f"{name}: surfaces claude but no .claude/skills/{name}")
+            if "codex" in surfaces and name not in agents:
+                problems.append(f"{name}: surfaces codex but no .agents/skills/{name}")
+            if name in claude and "claude" not in surfaces:
+                problems.append(f"{name}: in .claude/skills but surfaces lacks claude")
+            if name in agents and "codex" not in surfaces:
+                problems.append(f"{name}: in .agents/skills but surfaces lacks codex")
+        self.assertEqual(problems, [], "\n".join(problems))
+
+
+class PublishExclusion(unittest.TestCase):
+    """`publish` is authoritative; project-private skills never ship.
+
+    Adapters MAY ship — `adapter` is in PUBLISH_CLASSES (above). A published
+    skill can reference an adapter as a real workflow step (to-issues:59 +
+    orchestrate-wave -> codex-adapter-sync mirror), in which case build-kit's
+    shipped-deps-must-ship check (build-kit.mjs) *requires* the adapter to
+    publish — that dependency check is the authoritative consistency guardrail.
+    An adapter only ships when something published references it (spark-coordinator
+    stays publish:false — nothing published references it). Narrowed from the
+    original project-private+adapter rule (#990 R1#10/R2#3/#5) once a published
+    skill was found to depend on codex-adapter-sync; the blanket adapter ban
+    contradicted both PUBLISH_CLASSES and that dependency."""
+
+    def test_project_private_not_published(self):
+        m = load_manifest()["skills"]
+        leaks = sorted(n for n, e in m.items()
+                       if e["class"] == "project-private" and e.get("publish"))
+        self.assertEqual(leaks, [], f"project-private marked publish:true: {leaks}")
+
+    def test_published_skill_dirs_exist_per_surface(self):
+        """every publish:true skill exists on disk in each surface it claims."""
+        m = load_manifest()["skills"]
+        claude = skill_dirs_on_disk(".claude/skills")
+        agents = skill_dirs_on_disk(".agents/skills")
+        problems = []
+        for name, entry in m.items():
+            if not entry.get("publish"):
+                continue
+            if "claude" in entry["surfaces"] and name not in claude:
+                problems.append(f"{name}: publish:true, surfaces claude, but missing on disk")
+            if "codex" in entry["surfaces"] and name not in agents:
+                problems.append(f"{name}: publish:true, surfaces codex, but missing on disk")
+        self.assertEqual(problems, [], "\n".join(problems))
+
+
+class EnforcedSkillsSelfContained(unittest.TestCase):
+    """generic & vendored skills carry no `../` reach, all .md files, both trees."""
+
+    def test_no_parent_refs(self):
+        m = load_manifest()["skills"]
+        enforced = {n for n, e in m.items() if e["class"] in ENFORCED_CLASSES}
+        problems = []
+        for tree in SKILL_DIRS:
+            for name in sorted(enforced):
+                d = REPO_ROOT / tree / name
+                if not d.is_dir():
+                    continue
+                for md in sorted(d.rglob("*.md")):
+                    for ln, src in find_parent_refs(md.read_text(encoding="utf-8")):
+                        problems.append(f"{md.relative_to(REPO_ROOT)}:{ln}: {src}")
+        self.assertEqual(
+            problems, [],
+            "`../` reach in a generic/vendored skill — replace with a project-root "
+            "convention path (e.g. `docs/agents/x.md`) + runtime fallback:\n"
+            + "\n".join(problems))
+
+
+class LookupContract(unittest.TestCase):
+    """Skills migrated this slice reference project config by a project-root
+    convention path (no `../`) AND state a runtime fallback (Codex R2#2)."""
+
+    def test_migrated_skills_have_convention_path_and_fallback(self):
+        for name in ("to-prd", "to-issues", "spec-self-critique"):
+            txt = (REPO_ROOT / ".claude/skills" / name / "SKILL.md").read_text(encoding="utf-8")
+            self.assertRegex(txt, r"docs/(agents|conventions)/",
+                             f"{name}: no project-root convention path")
+            self.assertIn("/setup-workflow", txt, f"{name}: no fallback")
+            # same scanner as the lint (honors the line-scoped exempt marker), not a
+            # raw substring — keeps LookupContract consistent with the real check (R2#4)
+            self.assertEqual(find_parent_refs(txt), [], f"{name}: still has a parent-dir reach")
+
+
+class MockRepoLookup(unittest.TestCase):
+    """Runtime-lookup contract against a mock consumer repo. The lookup itself is
+    a model convention (no resolver to unit-test), so we assert both branches:
+    project file present → resolves from the project root; absent → the skill's
+    stated fallback path applies."""
+
+    def test_present_resolves_absent_falls_back(self):
+        import tempfile
+        to_prd = (REPO_ROOT / ".claude/skills/to-prd/SKILL.md").read_text(encoding="utf-8")
+        with tempfile.TemporaryDirectory() as d:
+            target = Path(d) / "docs/agents/board-sync.md"
+            self.assertFalse(target.exists())            # absent → fallback branch
+            self.assertIn("/setup-workflow", to_prd)     # skill states the fallback
+            target.parent.mkdir(parents=True)
+            target.write_text("x", encoding="utf-8")
+            self.assertTrue(target.exists())             # present → resolves from root
+
+    def test_spec_self_critique_layer_present_absent(self):
+        """spec-self-critique runs with the project layer (full pass) and without
+        it (base pass + warning). Text/path contract — the skill names the layer
+        path + a fallback; behavior is verified manually in the mock-repo run."""
+        import tempfile
+        skill = (REPO_ROOT / ".claude/skills/spec-self-critique/SKILL.md").read_text(encoding="utf-8")
+        self.assertIn("docs/agents/skills/spec-self-critique.md", skill)  # names the layer
+        self.assertIn("/setup-workflow", skill)                            # states the fallback
+        with tempfile.TemporaryDirectory() as d:
+            target = Path(d) / "docs/agents/skills/spec-self-critique.md"
+            self.assertFalse(target.exists())            # absent → base pass + warning
+            target.parent.mkdir(parents=True)
+            target.write_text("x", encoding="utf-8")
+            self.assertTrue(target.exists())             # present → full pass
+
+
+class NegativeFixture(unittest.TestCase):
+    """A real `../` in a scanned .md file is caught end-to-end (regression guard)."""
+
+    def test_parent_ref_in_md_file_is_flagged(self):
+        import tempfile
+        with tempfile.TemporaryDirectory() as d:
+            f = Path(d) / "SKILL.md"
+            f.write_text("see [x](../../../docs/y.md)\n", encoding="utf-8")
+            self.assertEqual(len(find_parent_refs(f.read_text(encoding="utf-8"))), 1)
+
+    def test_exempt_line_in_md_file_is_not_flagged(self):
+        import tempfile
+        with tempfile.TemporaryDirectory() as d:
+            f = Path(d) / "SKILL.md"
+            f.write_text("anti: [x](../bad) <!-- self-containment-lint: ok -->\n", encoding="utf-8")
+            self.assertEqual(find_parent_refs(f.read_text(encoding="utf-8")), [])
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)