Partial protocol override dirs read as breakage to builders: teach per-file resolution at the point of use + add a resolution-inspection command

[amrmelsayed]

Field incident

A freshly spawned SPIR builder on an adopter workspace (published 3.3.4, current Tower) ran a multi-core bfs / -name specify.md -path '*spir*' scan of the entire filesystem while orienting, burning ~3 CPU cores for minutes. It eventually found what it wanted in the installed package skeleton ($(npm root -g)/@cluesmith/codev/skeleton/...) and proceeded normally, leaving no error artifact anywhere.

Investigation showed the delivery machinery is healthy: run from inside that builder's worktree, the 3.3.4 resolver resolves protocols/spir/prompts/specify.md, templates/spec.md, and protocol.md to the skeleton, and resolveCodevIncludes inlines the spec template into the specify prompt in full.

Root cause

The workspace carries a deliberate partial protocol override: codev/protocols/spir/ exists but contains only protocol.json (a consult-lane policy customization; the stale full copies were pruned long ago). Per-file resolution handles this exactly as designed. But to an orienting agent, a present-yet-nearly-empty protocol dir reads as breakage:

• The CLAUDE.md/AGENTS.md guidance says only that the absence of codev/protocols/<name>/ is normal. Nothing says a partial dir is equally normal.
• Nothing agent-facing states where tier 4 lives on disk, so an agent that decides it must read a framework file has no address and improvises a search.
• The guidance sits ~500 lines into CLAUDE.md; builders demonstrably do not act on it under time pressure.

Because the hunt always eventually succeeds and the lane proceeds, the failure is invisible and every similarly-minded builder replays it. The user-visible symptom is "high CPU consumption on spawns".

Fix shape (hypothesis, for the builder to validate)

Two deliverables, both trees where applicable:

1. Knowledge at the point of use.

   • Builder-facing spawn prompt (builder-prompt.md per protocol, or the shared spawn-prompt assembly, whichever is the single source): one short paragraph — protocol dirs may be absent or partial; resolution is per-file across the four tiers; the installed skeleton is at $(npm root -g)/@cluesmith/codev/skeleton/; never search the filesystem for framework files.
   • Skeleton CLAUDE.md/AGENTS.md template, File Resolution section: extend "absence is normal" to cover partial dirs explicitly, and name the tier-4 disk location.

2. Transparency instead of prohibition. A resolution-inspection surface, e.g. codev resolve <codev-relative-path> (or a codev doctor section): print which tier each requested framework file resolves from and the absolute path, so "is this dir broken?" is a one-command answer for humans and agents. An agent that can ask the resolver never needs to scan /.

Explicit non-goal

codev doctor must NOT warn on or disallow partial protocol override dirs. Sparse per-file overrides are the intended customization mechanism; full local copies are the anti-pattern (they rot). A check that pressures projects toward full copies would recreate the drift problem the resolver exists to prevent.

Related latent footgun (note, not the trigger here)

resolveCodevIncludes() collapses an unresolvable {{> ...}} include to an empty string by design ("never an error"). For load-bearing includes (a phase prompt's template), a silent empty substitution would strand the builder with "use the template below" and nothing below. Verified NOT the cause of this incident, but worth hardening (visible [MISSING: <path>] marker plus a log line) while in the area — builder's judgment whether it fits this scope or deserves its own issue.