Skip to content

Guidance-hook delivery cannot be declared #1251

Description

@williamthorsen

Problem

A rulebook reached only through a guidance-hook binding has no way to declare that. delivery: accepts ambient and skill; its array branch carries no minimum, so delivery: [] parses, deploys the rulebook nowhere, and still fills its bound hook, because the fill reads the body from the resolved closure independently of delivery. Hook-only delivery therefore works by accident and reads as an omission rather than a choice.

The gap also costs three checks. Nothing reports a rulebook a declaration binds while its delivery never claims the route, which is the state williamthorsen-code-layout-preferences and williamthorsen-typescript-preferences are in today. Nothing reports a rulebook that declares itself hook-reached but that no declaration binds. And nothing reports one that is both bound and ambient, which delivers the same text into a session twice.

Context

williamthorsen-code-layout-preferences and williamthorsen-typescript-preferences are bound to implementation-preferences and carry delivery: skill. That is inherited from before #1163, whose problem statement is that the consult- hop does not fire on its own; it is not a considered shape for a hook-bound rulebook. The consult- route still earns its place, because a hook reaches only the bodies that declare it and code is written in sessions that invoke none of them.

Proposed solution

Add hook to the delivery enum and reject an empty list. hook declares intent rather than instructing: unlike ambient and skill, a rulebook cannot cause its own transclusion, since the binding lives in codeassembly.yaml. That asymmetry is what makes the three checks above expressible.

Each check reports without failing the run. A rulebook's delivery is written by its author and a binding by its consumer, so a mismatch between the two is not always the consumer's to fix and must not take down their sync.

Acceptance criteria

Must have

  • delivery: hook is accepted, alone and combined with the other modes.
  • An empty delivery list is rejected.
  • A bound rulebook whose delivery omits hook is reported.
  • A rulebook that declares hook and that no declaration binds is reported.
  • No new check fails a sync run.
  • williamthorsen-code-layout-preferences and williamthorsen-typescript-preferences declare hook alongside skill.
  • The hook mode is documented where ambient and skill are specified.
  • New and modified behavior is covered by tests.

Should have

  • A rulebook that is both bound and ambient is reported.

Metadata

Metadata

Assignees

No one assigned

    Labels

    featureAdded or improved external functionalityscope:agents

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions