LaneResolutionKit.git · AGENTS.md

revision d17d1c98e91b4db8a754a121cc96cac1f3d1814b · complete file
# LaneResolutionKit — Agent Guide

Scope: a pure resolver answering "which lane serves this role, right now?" once, into a value that carries its own
client budget. Zero dependencies, Foundation only.

## Invariants

- **The resolver is pure.** Configuration, consent, credential state, health and a clock in; a resolution out. No
  I/O, no network, no credential store, no clock reads of its own. This package MUST NOT gain a dependency that
  could reach a secret — its inability to prompt is a structural guarantee, not a convention.
- **A lane is resolved ONCE, into a value.** For a given role at a given moment there is exactly one resolution,
  computed here and passed to everyone who needs it. No consumer re-derives it, and "ask again later" is
  re-deriving.
- **The budget is a property of the decision, not a lookup.** A decision carries the lane AND the context window,
  output reserve and payload budget that lane actually has. `LaneBudget` has no public initialiser taking a number;
  obtaining one without a decision is not an available operation.
- **A refusal is a value with a reason, never a nil.** No public function returns `Optional` to mean "unavailable".
  A refusal names the role, the lane, the gate that refused, why, and the one remedy that exists.
- **Gates are ordered and may only NARROW.** `configured → permitted → credentialed → constructible → healthy`. No
  stage may add a candidate a previous stage excluded. `preferredOrder` orders survivors and can widen nothing.
- **`permitted` precedes `credentialed`, always.** Reordering these two breaks the guarantee that without consent
  no credential data is read. This ordering is load-bearing, not stylistic.
- **A credential has four states, not two.** `absent`, `presentUnverified`, `authorised`, `refused`. Presence never
  elects a lane; the grant is what initialises a paid one. Any `Bool` treatment of this is wrong by construction.
- **Naming a lane must not read a secret.** `name(role:)` and `resolve(role:)` run the same gates in the same
  order; only `name` decides `credentialed` from attributes. Any change that makes naming read data is a defect.
- **A failure teaches only what it is evidence of.** Only `windowOverflow` — the model reporting input, window and
  payload — may narrow a size budget. A timeout is latency. Narrowing never widens.
- **The seam is generic.** No consumer's domain types, vocabulary, or product decisions enter this package. Lanes
  are declared by the caller and passed in; there is no enum of lanes here and there must never be one.

## Prohibitions

- Do not add a dependency without recording why an owned or zero-dependency alternative was not possible.
- Do not introduce a lane inventory, provider enum, or default lane table.
- Do not make a public API return `Optional` to signal unavailability.
- Do not add a public `LaneBudget` initialiser that accepts token counts.
- Do not narrow a budget from any evidence other than an explicit window overflow.

## Safety and review

- Public API changes are reviewed against the invariants above before release. Removing or narrowing public API
  requires a deprecating release first and a major version for the removal.
- Every behavioural change ships with a test in THIS package. A seam proved only in a consumer is untested here.
- The suite MUST NOT touch a real credential store and MUST NOT prompt. Tests use fakes that record whether a data
  read was attempted, not merely what it returned.

## Routing

- For multi-step or high-risk changes, create or update `PLANS.md` before editing code.
- Procedures live in skills: `.codex/skills/*/SKILL.md` (mirrored identically in `.claude/skills/`). This file
  carries law only — no steps, no tool configuration, no workflows.
- MCP is optional capability only; correctness must never depend on MCP availability.

## References

- `README.md` — what the kit is and how to use it.
- `docs/INCIDENTS.md` — the measured failures each invariant exists to prevent.
- `FCIS_COMPLIANCE.md` — which org standards bind this repository, and the evidence for each.