Field report: ran the skill's restructure on a 15-repo working workspace, found a blind spot in the audit

[ruben-aguirre]

Jake, field report from running this skill against a real production workspace (my fractional CMO consultancy's whole operating environment: ~15 git repos in one folder tree, clients, sales, finance, the lot).

What the skill did well. The restructure audit ran across every area and caught 26 real problems in one pass: dead pointers, map drift, duplicated catalogs, folders with no contract. All fixed and shipped. The walk test and the catalog-holds-no-books rule earned their keep repeatedly.

The blind spot. The workspace had 58 files named CLAUDE.md against 38 CONTEXT.md. Canon (your paper + this skill's own references) wants one map plus a per-folder CONTEXT.md, but the audit never flagged it: a folder with any CLAUDE.md reads as correct to it, so it doesn't check CLAUDE-vs-CONTEXT naming or the one-map rule. We found the divergence by hand, then migrated everything: one CLAUDE.md left (the root map), CONTEXT.md everywhere else, runnable code repos exempt (they leave the workspace via CI/deploys, so their CLAUDE.md is developer docs, not routing). Root map went from ~7,000 tokens to ~1,200 with a per-block relocation ledger so nothing was lost.

Two field notes worth the skill knowing:

1. Case-insensitive filesystems bite the rename. On Windows/macOS, CLAUDE.md -> CONTEXT.md collides with any existing lowercase context.md (we had one in every client folder). Those become merges, not renames, and a migration map built from a file inventory won't see it coming. Worth a warning in the restructure flow.
2. The one-level tree held up. Root map lists areas only, each line ending with its read pointer; every area's CONTEXT.md carries its own deeper structure. The old 120-line full-depth tree at root was the thing that kept drifting.

Happy to send a PR adding the naming/one-map check to the restructure audit if you'd take it. Say the word.

Ruben (8 SIGNAL, Clief Notes)

[krwhynot]

Your case-insensitivity note is the one I'd push hardest on, because it survives the fix that's currently queued for it — and that's easy to miss.

#2 rewrites the Migrate step into copy → verify parity → remove:

6. Migrate — copy, verify, then remove. Never move-and-hope. Copy to the new home, verify parity (file count and content hash) against the source, and only then remove the original.

Walk that through your scenario. CLAUDE.md is copied onto an existing context.md; on Windows/macOS the filesystem resolves those to one file, so the copy overwrites it. Parity then compares destination against source — and passes, byte for byte, because the destination is the source now. The check reports success, the original is removed, and the file you clobbered was already gone before the verification ran.

So it guards a partial or corrupted copy, not a destination collision. Different failure class, and the parity check structurally can't see this one. The guard has to fire before the write — a destination-exists test, case-folded — and the collision has to surface at the approval gate, because a migration map built from a file inventory won't show it (your point exactly).

Your 58-vs-38 CLAUDE.md/CONTEXT.md observation is the other half of it: the rename that triggers this is the skill's own canon (SKILL.md:62 mandates a root CONTEXT.md, core.md:68 makes CLAUDE.md the entry file), so restructure walks into it by design rather than by accident.

I hit the same thing from a different direction — auditing the skill rather than running it — and reached your finding independently, so consider this a second data point rather than a competing report. I deliberately haven't sent a PR for it: every viable site is inside one of #2's hunks, and filing it now would make a fifth conflicting PR that blocks the one change the maintainer has already approved. It's better as a clause on #2's step 6 once that lands. You offered a PR upstream first, so it's yours if you want it — happy to review or to stay out of the way.

[krwhynot]

Follow-up: the blocker I named above is gone. #2 was rebased onto b20fb45 a few minutes after I wrote that and is now MERGEABLE, which moves its hunks off the line I'd have needed. I re-tested it rather than assuming:

collision-guard branch × #2 (pre-rebase 88bde35)  → CONFLICT (content): SKILL.md
collision-guard branch × #2 (rebased)             → clean

So the reason I gave for holding back was true when I wrote it and isn't any more. Worth correcting rather than leaving to stand.

Which puts it back with you. You reported this first, you offered the PR, and it's still the only finding here with no upstream equivalent — nothing in #2, #3, #4 or #5 checks a destination before writing to it. I'm not going to file over the top of that. If you'd rather not, say so and I'll send it, but it should be yours.

One thing worth carrying into whatever lands: the guard has to be a pre-write destination test, case-folded — not a post-write verification. #2's verify parity (file count and content hash) against the source runs after the copy, and in this failure mode the destination legitimately matches the source by then, so it passes while the clobbered file is already gone.

[ruben-aguirre]

Filed it: #10.

Thanks for the correction on the rebase, and more for the parity walkthrough. I had #2's copy-verify-remove logged as covering this and it doesn't. The destination is the source by the time parity runs, so it passes clean while the file it ate is already gone. That moved the fix from "add a warning" to "the test has to happen before the write," which is what the PR does.

I kept it to one Guardrails bullet instead of putting it inline in the restructure steps, since #2 renumbers those and #9 changes the entry file name. Test merged clean against #2, #4, #7, #8 and #9. If Jake wants it inline once #2 lands, it's a one line move.

Review welcome if you want to take a pass at it.