docs(backlog): what the shipyard-cmake flag day surfaced and did not fix

[schmonz]

Summary

Records five findings from the 2026-09-13 shipyard-cmake cutover that were surfaced but deliberately not fixed as part of that flag day:

1. check-comments.sh cannot see inside heredocs — ~40 lines of prose in package-pkg.sh's rendered pre/postinstall never swept.
2. The comments gate ignores trailing comments entirely.
3. No consumer repo documents the developer path for obtaining shipyard outside CI.
4. 1password's cmake-10_9-gate job is broken independently of this flag day (pre-existing, spec D8 left it alone).
5. Check 18 (shell-recipe detection) has three blind spots — *.bats, tests/*.sh, extensionless executables, *.cmake/CMakeLists.txt, and bare ( — and real breakage hid in every one of them (porthole's bats test and generate-viewer recipe, five echo "(build it: ...)" recipes across four repos). Across fourteen repos the gate saw a minority of real call sites (e.g. magic-trackpad2: 4 visible vs 18 invisible).
6. Check 16 (cmake locator detection) has two blind spots — it only matches .cmake/package[s] (missing $HOME/.local/share/cmake/... locators in clang, golang, swift-runtime) and skips tests/ entirely (magic-trackpad2's tests/test_appcast_notes.sh matched the pattern exactly and was still never reported).

The last two (checks 18 and 16) were not anticipated by the original task brief — the cutover itself found them while auditing the other three.

This is documentation only: five new numbered entries appended to BACKLOG.md, matching its existing entry style (evidence-first, citing concrete repos/files/lines).

Test plan

• sh scripts/check-comments.sh exits 0
• sh scripts/check-family-conventions.sh exits 0
• Confirmed BACKLOG.md was 155 lines before, 204 after (49 new lines, no existing content altered)

🤖 Generated with Claude Code

https://claude.ai/code/session_01GTxFde2TJMmp5p64DhvDSK