🎙️ task - feat\(boot\): budget.tokens per boot.yml, held like a stop hook when exceeded

[uladkasach]

🦫🎙️ dispatch to foreman

💧 task enqueued
   ├─ priority = ?
   ├─ yieldage = ?
   └─ leverage = ?

title
feat(boot): budget.tokens per boot.yml, held like a stop hook when exceeded
description

.what

add a budget: block to boot.yml that declares the maximum token cost the boot's resident payload may consume:

budget:
  tokens: 5_000
always:
  briefs:
    say:            # resident in context every session
      - briefs/core.md
    ref:            # path-only, fetched on demand
      - briefs/reference.md

.why

a boot.yml's say set grows silently. every say brief is injected into context at session start, on every session, forever. today no mechanism caps it — so boots bloat unnoticed until a human sees /context is ~46% consumed by startup payload alone (real case: a bound-behavior boot + role briefs dominated a session's context).

a declared per-boot budget makes that cost a first-class, enforced contract instead of an invisible tax.

.behavior

when a boot renders and its resident (say) payload exceeds budget.tokens, the boot acts like a stop hook: it halts and forces the author to fix the boot.yml before the session proceeds.

remedies the halt should name:

• move briefs from say -> ref (path-only, fetched on demand)
• create .min variants of oversized briefs and point say at those
• raise the declared budget deliberately (an explicit, reviewable choice)

the key property: over-budget is a loud, hard stop, not a silent pass. the author must make the trim (or the raise) a conscious, reviewed decision.

.acceptance

• boot.yml parser accepts budget.tokens (underscore-numeric ok, e.g. 5_000)
• boot renderer computes the token cost of the resident say payload
• cost <= budget -> boot proceeds normally
• cost > budget -> boot emits a stop-hook-style halt that names the overage (actual vs budget) and the remedies above
• snapshot both stdouts: the clean pass and the over-budget halt

.notes

• scope is the core boot mechanism in rhachet (boot.yml parse + rhachet roles boot render), not any single role package.
• composes with the companion task for a --manifest <path> flag: a custom manifest (e.g. a behavior boot from rhachet-roles-bhuild) declares its own budget and is held to it the same way.
• supersedes two rougher ideas floated earlier (self-diagnostic boots; auto .min onStop) — the token budget is the cleaner, self-held mechanism that subsumes both.