infra(symlinks): #357 sub-task 4 — Windows symlink materialization gate

[silongtan]

Summary

Implements #357 sub-task 4 (the last sub-task on this tracking issue). PR #307 replaced .claude/skills/bicameral-* duplicates with symlinks but shipped no enforcement that Windows clones materialize them correctly. This PR closes that loop.

Stacks logically alongside the rest of the #357 cluster (#359 merged, #360, #361) but branches independently from dev — can merge in any order.

Why

Git stores the 22 .claude/skills/bicameral-* entries as mode-120000 symlinks. Windows defaults to core.symlinks=false and silently materializes them as plain text files containing the target path string ("../../skills/bicameral-preflight"). The MCP test surface still passes because nothing tries to follow the symlinks; the breakage surfaces only when Claude Code's slash-command resolver tries to resolve /bicameral-preflight. PR #307's body noted this in passing but added no gate, so it remained the "verified in-vivo" claim Devin's #357 critique correctly flagged.

Three defense-in-depth layers

1. tests/test_skills_symlink_integrity.py (NEW)

Two assertions, both with actionable failure messages:

• test_skills_symlinks_tracked_as_mode_120000 — git ls-files -s shows ≥ 22 mode-120000 entries under .claude/skills/. Catches the regression where a symlink got re-committed as a plain file (whether by Windows-clone misconfiguration or by a misguided IDE auto-fix).

• test_skills_symlinks_materialize_on_this_clone — on-disk .claude/skills/bicameral-preflight must resolve as a real symlink. If it's a plain file containing "../../skills/...", surfaces the specific fix commands inline:

  git config --global core.symlinks true
  git rm --cached .claude/skills/bicameral-*
  git checkout -- .claude/skills/
  

  Contributors never have to grep for "how do I fix this" when CI tells them outright.

2. .github/workflows/test-mcp-regression.yml

Two new steps run BEFORE the regular test suite on both ubuntu-latest and windows-latest:

• Asserts the mode-120000 count via git ls-files
• Asserts on-disk materialization via a Python probe with ::error:: annotations

The windows-latest matrix slot is where this actually matters — ubuntu-latest always materializes symlinks correctly. Now the matrix isn't just running tests on Windows; it's gating the symlink contract there too.

3. CLAUDE.md

Upgraded the Windows note from "recommended" framing to "required", with the specific fix-in-place commands AND a pointer to the test + workflow gate that enforces the contract.

Why NOT in setup_wizard.py

The wizard's _install_skills path is for wheel installs — bundled skills/ content is copied into the target repo's .claude/skills/. There are no symlinks at that layer; nothing to check. The Windows symlink issue only affects developer clones of this repo itself, where the test + CI gates are the right surface.

Verification

$ pytest tests/test_skills_symlink_integrity.py -v
tests/test_skills_symlink_integrity.py::test_skills_symlinks_tracked_as_mode_120000 PASSED
tests/test_skills_symlink_integrity.py::test_skills_symlinks_materialize_on_this_clone PASSED
============================== 2 passed in 0.16s ==============================

Negative-case verification (manually edited test to assert count > 1000): fails with the actionable error message listing the fix command.

Test plan

• CI green on ubuntu-latest (the new steps pass cleanly)
• CI green on windows-latest — the more interesting check, since this is where the gate actually trips on misconfigured clones
• After merge, intentionally check out the repo with core.symlinks=false on a Windows VM, run pytest, confirm the gate fires with the documented fix

What's left on #357

With this PR, all four acceptance criteria of #357 have a delivered PR:

• ✅ Sub-task 1 (test(infra): #357 sub-task 1 — sociable test audit + de-mock eval harness + regression gate #359, merged) — sociable test audit + de-mock + regression gate
• 🟡 Sub-task 2 (ci(perf): #357 sub-task 2 — file-backed SurrealKV perf gate #360, rebased on post-fix(e2e): #362 — reclassify Flow 3 'no cc rows + no verdicts' as advisory #363 dev) — file-backed SurrealKV perf gate
• 🟡 Sub-task 3 (infra(pre-commit): #357 sub-task 3 — local ruff enforcement at commit time #361, rebased on post-fix(e2e): #362 — reclassify Flow 3 'no cc rows + no verdicts' as advisory #363 dev) — pre-commit local enforcement
• 🟢 Sub-task 4 (this PR) — Windows symlink check

The remaining work on #357 itself is the 8 trap-row backfill PRs that the sub-task 1 audit identified — sequenced after sub-tasks 2/3/4 land.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1947dab6-f0e1-4ca9-ac7f-c848b05acd4c

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch infra/357-subtask-4-windows-symlink

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}