git:20260713.2f8c42f to git:20260723.6e5370b

- description: Plan authority to settle a known invoice under a spend-bounded grant; this skill never moves money, and an approved downstream spend runner must execute payment.

- Settle one specific invoice that someone has already approved, without letting

- the amount drift past the grant that authorizes it.

-

- ## What this skill does

-

- `settle-invoice` produces a sealed `payment_plan` for one invoice. It binds the

- invoice reference, the amount, the currency, the payee identity by account

- digest, the rail, and the `requested_scope` authority ceiling that authorizes the

- settlement. It decides one of `ready`, `over_budget`, or `needs_review`, and it

- always requires human approval and a preflight check before the plan can be

- executed.

-

- The ceiling is the same typed `requested_scope` (an `AttenuationRequest`) the

- `spend` and `refund` accepting runners narrow from. The downstream spend lane

- reserves and mints the child grant against this exact ceiling, so the plan can

- never widen authority beyond it.

-

- The plan is the authority artifact, not the payment itself. Money moves only when

- a downstream spend lane consumes an approved plan, records rail evidence, and the

- runx receipt seals. This skill never holds funding material; it carries a payee

- account digest or last4, never a full account number.

-

- It settles a specific invoice where the counterparty, the invoice, and the

- amount are fixed inputs. `x402-pay` answers a machine 402 signal and `charge`

- authorizes a card; the difference here is that what is paid is already known, so

- the only open questions are whether the amount fits the grant and whether a

- person approves.

-

- ## When to use this skill

-

- - An agent reconciling accounts payable has a specific invoice to settle and a

- grant that bounds how much it may spend.

- - A workflow needs to prove that an invoice amount fit its authority ceiling

- before a person approved it.

- - An operator wants one artifact that ties an invoice reference to a payee, a

- rail, and an approval decision for audit.

- - A payable should be blocked, not paid, because its amount exceeds the bound it

- was granted under.

-

- ## When not to use this skill

-

- - A machine payment-required challenge belongs to `x402-pay` or the canonical

- `spend` family with the matching runtime path.

- - Authorizing a card or pricing an inbound paid call belongs to `charge`.

- - Reversing a prior settlement belongs to `refund`.

- - An unidentified payee, an unbounded amount, or an invoice you cannot reference

- stops the skill at `needs_agent`; it does not invent a counterparty.

- - A full bank account number, card PAN, routing-plus-account pair, API key, or

- any raw funding credential is never accepted or emitted. The plan carries

- digests and refs only.

-

- ## Procedure

-

- 1. Validate the four required facts: `invoice_ref`, `amount`, `currency`, and

- `payee`. Any missing fact stops the skill at `needs_agent`.

- 2. Validate `requested_scope`. Without an authority ceiling there is nothing to

- settle against, so a missing ceiling also stops at `needs_agent`.

- 3. Reduce the payee to a stable identity: keep the display name and an

- `account_digest` (a hash of the account reference, or a last4). If only a raw

- account number is supplied, digest it and discard the raw value.

- 4. Compare `amount` against the `requested_scope` ceiling. If the amount exceeds

- the ceiling, decide `over_budget` and record the overage as a blocker. Do not

- round, split, or partially settle to fit under the ceiling.

- 5. Select the rail. Use the supplied `rail` when present; otherwise leave it

- unresolved and record a blocker so a downstream lane or operator must choose.

- 6. Set the gates. Human approval is always required. Preflight is always

- required. Neither is optional and neither defaults to satisfied.

- 7. Emit the smallest `payment_plan` a spend lane can execute without widening

- authority beyond the invoice, the payee, and the `requested_scope` ceiling.

-

- ## Edge cases and stop conditions

-

- - **Missing invoice, amount, payee, or requested_scope ceiling:** return

- `needs_agent`. The skill does not guess a counterparty, an amount, or an

- authority ceiling.

- - **Amount over the bound:** decide `over_budget`; record the overage; do not

- emit a plan that a lane could execute as-is.

- - **Currency mismatch between amount and grant:** record a blocker and decide

- `needs_review`; this skill does not convert currency to force a fit.

- - **Raw account number supplied:** digest it, keep only the digest or last4, and

- proceed; never echo the raw number into the plan or the receipt.

- - **No rail resolvable:** decide `needs_review` with a rail blocker; a person or

- downstream lane must pick the rail.

- - **Approval absent or denied:** the plan is never `ready`; settlement does not

- proceed.

- Authority bounds the run. The `requested_scope` ceiling keeps the settlement

- inside the supplied authority and `ledger:append` records the settlement intent;

- no broader wallet scope is requested or implied. A `ready` decision means the

- plan is well-formed and within the ceiling, not that money may move; the approval

- and preflight gates still stand between the plan and any rail. The sealed receipt

- carries the invoice reference, amount, currency, payee name and account digest,

- rail, the requested authority ceiling, the decision, the gate state, and the

- blocker list as proof, and never a full account number, card PAN, funding

- credential, or raw secret.

- ## Output schema

- ```yaml

- payment_plan:

- decision: ready | over_budget | needs_review

- invoice_ref: string

- amount: number

- currency: string

- payee:

- name: string

- account_digest: string

- rail: string

- requested_scope: object

- gates:

- human_approval_required: boolean

- preflight_required: boolean

- blockers: array

- ```

- - `decision`: one of `ready`, `over_budget`, or `needs_review`.

- - `payee.account_digest`: a hash or last4, never a full account number.

- - `rail`: the selected settlement rail, or unresolved when none was supplied.

- - `gates.human_approval_required` and `gates.preflight_required`: both always

- true.

- - `blockers`: reasons the plan is not `ready`, for example an overage, an

- unresolved rail, or a currency mismatch.

- ## Worked example

- Input: invoice `INV-2026-0412` for 1840.00 USD to Acme Hosting at account

- `acct_3f9c1a7e`, under a `requested_scope` ceiling that authorizes up to 2500.00,

- on the `ach` rail.

- Output: `decision: ready`; the amount fits the ceiling, so no overage blocker; the

- payee is reduced to a name and `account_digest`; the rail is `ach`; both

- `human_approval_required` and `preflight_required` are true. The plan is

- well-formed and within bound, but money does not move until an operator approves

- and a downstream spend lane records rail evidence.

- ## Inputs

- - `invoice_ref` (required): reference for the invoice being settled.

- - `amount` (required): the settlement amount.

- - `currency` (required): the settlement currency.

- - `payee` (required): object naming the payee and its account by reference or

- digest, for example `{ "name": "Acme Hosting", "account_ref": "acct_..." }`.

- A raw account number is reduced to a digest and the raw value is dropped.

- - `requested_scope` (required): the typed authority ceiling

- (`AttenuationRequest`) the settlement is authorized against; the same ceiling

- the `spend`/`refund` accepting runners narrow from. An amount over this ceiling

- forces an `over_budget` decision.

- - `rail` (optional): the settlement rail to use, for example `ach`, `wire`, or a

- configured rail profile reference.