fix(guidance): stop pointing at a Ruflo reference file nothing deploys

[pacphi]

Card: #307 (A61-01) on the v4.0.0 board, milestone 4.0.0-alpha.61, epic #294. It is prerequisite A, it blocks #320, and the plan is docs/plans/2026-10-01-prereq-ruflo-reference-pointer.md.

Summary

The managed ruflo-reference block is rendered from claude/ruflo-reference.md into ~/.claude/CLAUDE.md for every Claude session. It told the agent to read ~/.config/ruflo/ruflo-reference-full.md, a file nothing deploys any more. Every machine set up with the npm kit had a dangling pointer, so the agent either wasted a tool call on a missing file or concluded the reference was unavailable.

• claude/ruflo-reference.md:
  • Line 2, an HTML comment that only misled maintainers, now reads "Compact Ruflo guidance; use ruflo --help for commands and flags".
  • Line 31, the prose the agent acts on, now reads "Run ruflo <cmd> --help for commands and flags. Reconcile upgrades with ak sync; inspect effective health with ak status."
  • Both sentinel lines are unchanged.
• claude/ruflo-reference-full.md: its header claimed a "Deployed copy" at that path. It now says the file is not deployed and ships as the source for a future on-demand skill. It names no repository-only path, because docs-layout.test.mjs rejects shipped guidance that does.
• Left in place: the legacy cleanup in uninstall.mjs that deletes a shell-kit copy where one exists, and the retired dependency-constraint record that names the file.
• Not done, as the card says: restoring or deploying the full reference file. That would add a user-level write, and the project-scope design turns this content into the reference file of the ak-ruflo project skill.

The guard

tests/kit/shipped-guidance-paths.test.mjs reads every claude/*.md template and fails if one names the retired ~/.config/ruflo/ folder (or its %APPDATA% twin). A first test checks that the guard actually scans the templates and recognises the path it exists to catch, so it cannot pass by scanning nothing. I confirmed the second test fails on the old templates, naming exactly ruflo-reference-full.md and ruflo-reference.md.

The card's wording, "a path that nothing deploys", is wider than this. The guard catches the one retired folder this bug came from, not every undeployed path in general. A general check would need a list of everything the kit deploys, which doesn't exist yet and arrives with the project-scope write gate.

Effect on existing machines

ak status reports 1 CLAUDE.md block(s) drifted: ruflo-reference→upserted until the next ak sync, the same path as any template change. ak sync replaces the sentinel span in place and leaves text outside it untouched. The block gets slightly smaller, so it stays within its byte budget.

Tests

• Focused: the guard, blocks-drift-parity, docs-layout, opencode, uninstall and status suites pass (184 of 184). lint:md and eslint report nothing.
• Full pnpm test: 6,494 passed, 2 failed, 17 skipped. The two failures (process-tree, setup-memory-probe) fail identically on unmodified main in a container that runs as root, and pass in CI.

Closes #307

🤖 Generated with Claude Code

https://claude.ai/code/session_01WAbqdRJ4kk8UsjrKxYeUCd

---

Generated by Claude Code