fix(symlink-lint): enforce relay completeness and sync missing self-adoption symlinks

[onlyarnav]

Summary

• The self-adoption relay directories drifted out of sync with skills/ (71 skill directories):
  • .agents/skills/ (canonical), .claude/skills/, .github/skills/, and .kiro/skills/ were missing magpie-dependency-license-audit.
  • .kiro/skills/ was missing magpie-report-framework-issue.
• Added Rule 3 (Completeness) to symlink-lint: in the framework checkout (where skills/ lives), every skill directory under skills/ must have its canonical entry under .agents/skills/ and every wired agent directory (.claude/, .github/, .kiro/, etc.) must relay the full canonical set. Adopter checkouts (where root skills/ is absent) remain exempt.
• Added comprehensive unit test coverage for Rule 3 in tools/symlink-lint/tests/test_symlink_lint.py.
• Updated documentation in tools/symlink-lint/README.md, docs/labels-and-capabilities.md, and tools/spec-loop/specs/meta-and-quality-tooling.md.

Type of change

• Python package (tools/*/ with pyproject.toml)
• Documentation (docs/, README.md, CONTRIBUTING.md)
• CI / dev loop (prek, workflows, validators)

Test plan

• uv run --directory tools/symlink-lint --project . ruff check src tests passes
• uv run --directory tools/symlink-lint --project . mypy src tests passes
• uv run --project tools/symlink-lint pytest tools/symlink-lint/tests passes
• python tools/symlink-lint/src/symlink_lint/__init__.py --archive passes (exit code 0)
• Verified git index entries for all 5 missing symlinks (.agents, .claude, .github, .kiro) are staged as mode 120000

RFC-AI-0004 compliance

• Vendor neutrality — ensures all supported agent directories receive full relays for framework skills

possible fix for: #1137

Notes for reviewers (optional)

Generated-by: Antigravity (Gemini 3.7 Flash)

[dpol1]

Thanks for picking #1137 up so fast — the five links are right (mode 120000, canonical → ../../skills/…, relays → ../../.agents/skills/magpie-…), and rule 3 run against main reports exactly the five missing links and nothing else. Skill discovery mirrors the validator (is_dir() + no leading dot + PRUNE_DIR_NAMES), so skills/pyproject.toml and the cache dirs are ignored, and agent-dir discovery stays convention-based like rules 1–2. Locally on the PR head: symlink-lint and --archive exit 0, ruff check / mypy / pytest (27) green. Branch is clean against main (MERGEABLE); merge is BLOCKED only by the red prek check.

Two things need to land before this can merge, plus a few smaller ones.

CI is red — workspace-ruff-format (__init__.py:145-147)

Confirmed from run 33528122998, not guessed: ruff format (workspace)...Failed, 1 file would be reformatted. The three-line find_missing_relays(...) signature fits the tool's 110-column limit, so ruff collapses it to one line. uv run --directory tools/symlink-lint --project . --group dev ruff format src and recommit. (AGENTS.md § Local setup: "Before opening or updating a PR, run prek run --all-files … as a hard pre-flight gate.")

The hook never fires on the case rule 3 exists for (.pre-commit-config.yaml:234)

The symlink-lint hook is types: [symlink]. Rule 3's failure mode — a new skills/<x>/ committed with no links — stages no symlink, so locally the hook does not run on exactly that commit; only CI's --all-files catches it, which is how #1137's drift landed in the first place. The archive hook at :250-251 already has the right shape: add a files: pattern covering skills/.* and the agent skills/ trees with types_or: [symlink, file], and update the comment at :224-227 and README.md:106-107 ("fired on any staged symlink"). (AGENTS.md § Local setup: "fix the underlying issue or update the hook config in the same PR"; README.md:53-54 promises rule 3 "catches new skills that landed without their self-adoption symlinks".)

Smaller points

• Scoping heuristic (__init__.py:162-164). "Framework checkout" is inferred from root/skills being any directory. An adopter repo with its own top-level skills/ gets told to add .agents/skills/magpie-<subdir> for every subdirectory (reproduced on a scratch tree). Rule 2 makes a similar assumption already, so this is not new exposure — but the README/docstring now claim adopters are exempt, which overstates it. Either gate on a framework marker (e.g. skills/setup/SKILL.md), or reword the exemption.
• Trusted-source pointer dirs (__init__.py:166-170). A skills/<name>/source.md pointer dir (no SKILL.md) is treated as a skill, so rule 3 demands a canonical link → ../../skills/<name>. Per skills/setup/skill-sources.md:222-231 that link's real target is ../../.apache-magpie-sources/<id>/skills/<name>/ and it is gitignored — so a fresh clone with any pointer dir fails the lint (reproduced). None exist in-tree today, so this is latent; skip dirs without SKILL.md the way the validator's is_skill_source_pointer does, and add the test case.
• Tests (tests/test_symlink_lint.py:192-197). test_completeness_unwired_agent_dir_not_required builds the same tree as the clean test — no agent dir without a skills/ child is ever created, so the behaviour in its name is untested; (tmp_path / ".github").mkdir() before the assert fixes it. Missing cases: pointer dir (above), skills/pyproject.toml.
• Out-of-scope changes. os.path → posixpath (:53, :252-253), _rel returning str (:262-266), and the module-wide pytestmark = skipif(not _can_symlink()) (tests:53-55) are not in #1137 or the commit message. The skipif in particular silently skips the whole suite — archive and main() tests included — wherever os.symlink fails. Drop them here or split into their own PR with the rationale. (AGENTS.md § Before submitting: "Re-read the diff and check that every change is intentional.")
• Doc drift to three rules. README.md:78 ("Unlike rules 1–2"), docs/adapters/add-a-harness.md:76 ("enforces both rules"), .pre-commit-config.yaml:224-225 comment.
• Wording. README.md:54-55 / __init__.py:41-42 conflate the dangling-skip (applies everywhere) with rule 3's skills/-absent exemption. docs/labels-and-capabilities.md:305 and the spec edit at :43-44 now have "(canonical/relay target-correctness)" trailing "incomplete … sets" — it belongs after "misdirected skill relays".
• Nits. __init__.py:185-190: every target in skills/setup/agents.md is a dot-dir, so entry.name.startswith(".") tightens the wired-dir scan cheaply. PR body: Fixes #1137 (or Refs) instead of the ## possible fix for: heading, so the link is machine-readable. tools/spec-loop/.last-sync was not bumped alongside the spec edit — though it is already behind main for unrelated reasons, so that is a judgment call.

---

This review was drafted by an AI-assisted tool and posted by
a contributor who does not have confirmed Apache Magpie maintainer
access. The findings below are this tool's analysis only, not
a maintainer sign-off; an Apache Magpie maintainer will still need
to look at the PR before it moves forward. If you think a
finding is mis-applied, please reply on the PR.

More on how Apache Magpie handles maintainer review:
CONTRIBUTING.md § Opening a pull request.