#1251 Let a rulebook declare that a guidance hook is how it is reached

[williamthorsen]

What

Rulebooks can now name hook in their delivery, declaring that a guidance-hook binding is the route they take into an agent's context. sync now warns when a binding and a rulebook disagree: a bound rulebook that never claims the route, and one that is also delivered ambiently, so its text reaches the session twice. Neither fails the run.

An empty delivery list is now rejected. It previously parsed and named no route at all, so the rulebook deployed nowhere with nothing to say so; a rulebook carrying one must name at least one of ambient, hook, and skill before it will sync.

Why

Two rulebooks in the shipped library are reached only through a guidance-hook binding, and nothing in their declaration said so. The arrangement worked by accident and read as an omission rather than a choice.

That silence also left three misconfigurations unreported. A project could bind a rulebook never written for the splice, bind one that then delivers the same text into a session twice, or adopt a rulebook offering the route and never bind it, and get no signal in any of the three cases.

Details

🎉 Features

• delivery accepts hook, alone or beside ambient and skill. The mode records a route rather than requesting one: the binding that splices a rulebook into a host body lives in codeassembly.yaml, so a rulebook cannot route itself there. That asymmetry is what makes a disagreement between the two expressible at all.
• 🚨 Breaking: delivery: [] is rejected on parse, carrying the same message an unknown mode does. A project holding an empty list syncs today and fails outright after upgrading.
• sync and sync --dry-run report three disagreements between a binding and the delivery of the rulebook it names. Bound while never claiming the route, and bound while also delivering ambient, are warnings; claiming the route while nothing binds it is advice. None changes the run's exit status or the files written, because a rulebook's delivery is written by its author and a binding by whoever adopts it, so a mismatch is not always the adopter's to fix.
• The code-layout and TypeScript preference rulebooks declare hook alongside skill, stating the route a project already reaches them by. Both stay available as consult- skills, which is how they reach a session that invokes no hook-declaring skill or subagent.

🧪 Tests

• Coverage spans the parse (hook alone and combined, and the empty list), the advisory computation through a real sync (each kind, the case where two fire for one rulebook, and the agreeing case), both report paths, and the frontmatter of the two library rulebooks that carry the route.

📚 Documentation

• The README's declaration-format and guidance-hook sections and the content-specification rulebook cover the third mode, with the three reported conditions tabulated beside the two failures a binding can already cause.

Closes #1251

[github-actions]

Dependency audit

Production dependency audit passed.