N4darae/shrt

What an agent needs to compose an RPC chain and a contract. .claude/skills/shrt/SKILL.md routes here; shrt init installs these four files into .shrt/docs/:

A package path such as runner/runner.go is a file in the shrt module (github.com/N4darae/shrt). Every command prints its flags and exit codes with -h.

This is the path that finds regressions. Chains written by hand miss most of what the planner probes (boundaries, the last item of a list, other roles, missing tokens, read-backs after every write, repeats), so write contracts and let plan compose the chains.

export API_USER=... API_PASSWORD=...           # the login's credentials, and <ROLE>_USER/_PASSWORD
shrt init                                      # observes the envelope from one real login
shrt contract init -all                        # one overlay per domain under .shrt/contracts/
#   fill each overlay from the service's code: required, failures, effects, fields.<f>.value
shrt contract lint && shrt contract status -gaps
shrt contract plan -all -write                 # one chain per rpc; fix every fill:/gap: line, re-plan -force
shrt run <chain>                               # every chain; a red one on a correct backend is
#   a real defect: shrt chain pin <chain> keeps it red in a slice, the rest green
shrt confirm -all -note "..."                  # show the user the table; approve only on their yes
shrt gate                                      # later, against every new release

A contract states behaviour; effects: states what a write does to numbers (GRAMMAR.md §3). summary and note are prose for people.

cd "$(git rev-parse --show-toplevel)"
shrt init -agents=false -build=false # only if .shrt/docs/ is missing, as on a fresh clone
shrt catalog build                   # the descriptor; without it every catalog command fails
shrt doctor                          # is this installation sound?
shrt catalog ls -filter <word>

.shrt/docs/, the descriptor, .shrt/runs/, .shrt/tokens.json and .shrt/safespots/pending/ are gitignored build output, so a fresh clone has none of them, and a run id quoted in a document is no evidence it can check. Run shrt doctor before trusting a green. Rebuild the descriptor after any proto change and the binary after any change to shrt itself (go build -o shrt ./cmd/shrt): both go stale quietly.

shrt init guesses the auth: block from the descriptor and says so; check the login it picked (GRAMMAR.md §4). A second role on the same login gets a profile when <ROLE>_USER and <ROLE>_PASSWORD are exported at init and the repo's README names the role; export them and re-run shrt init to add one later. Export the env vars auth.body reads before a run (read their names from .shrt/config.yaml); without them shrt run refuses before sending anything.

Only run (not -dry-run), verify (not -run <id>), gate and chain slice -verify send traffic.

Any command exits 2 for an unknown command, 1 for a bad flag or a setup it cannot load, 0 for -h and otherwise as below; 3 is no verdict, neither red nor green: re-run.

shrt gate sends every chain in .shrt/chains once (by verify when it has a safe spot, by run otherwise, with a fresh -var tag as short as run's own), retries an exit 3 once, and holds shrt chain hollow to .shrt/hollow-baseline. One line per chain:

Each FAIL line ends with its suspect and also <suspect> for the first other one, or same fault as <chain> when an earlier line named it and every other suspect of this chain; a slice failing at its parent's first change, and not a kept-red slice failing not as pinned, has no line of its own, the parent's says (+N slice(s) fail the same: ...). Then one line per suspect rpc and changed path. -v adds the suspect's request, every changed path and the knock-on counts. How a suspect is chosen: PLAYBOOK.md §8.

A token refused early once makes the gate hold a fresh one (at most 30s) and re-send a read: refused twice is a FINDING that sessions end early (-no-session-check skips it). shrt gate <chain>... gates a subset, without the ratchet. With no overlay, or an rpc whose contract no chain calls, it ends with one coverage: line.

shrt init writes this wrapper to .shrt/ci-gate.sh (commit it; init -force refreshes it); it skips the contract checks while .shrt/contracts holds no overlay. Init also writes 0 into a missing .shrt/quality-baseline, never over one; a gate failing on it names the current score, to write in as a reviewed edit. The first gate outside CI writes .shrt/hollow-baseline with today's count and says so; commit it. With CI set, a missing baseline fails the gate.

set -euo pipefail
cd "$(git rev-parse --show-toplevel)"
[ -f .shrt/docs/GRAMMAR.md ] || shrt init -agents=false -build=false
shrt catalog build
shrt doctor -strict
if compgen -G '.shrt/contracts/*.y*ml' > /dev/null; then
  shrt contract lint
  shrt contract quality -gate -baseline .shrt/quality-baseline
fi
shrt chain lint -strict
exec shrt gate

Build the tag into other text (name: item-${vars.tag}): a field that is ${vars.tag} alone is input, so the fresh tag makes every verify of it drift. A slowdown fails the gate only with latency: {fail: true}, which shrt init writes into every new config.

      shrt catalog ls -filter <word>          what rpcs exist
   → shrt contract show <rpc>                 what the curated layer knows
   → shrt contract plan <rpc> -write          let the contract compose the chain
   → edit .shrt/chains/<name>.yaml            fill ONLY the test data
   → shrt chain lint <name>                   shape, refs, required fields
   → shrt run <name> -dry-run                 resolve everything, send nothing
   → shrt run <name>                          the receipt
   → shrt chain hollow                        did any read pass and find nothing?
   → shrt confirm <name> -note "..."          propose it; show the user the summary, ask
   → (user says yes) shrt confirm <name> -approve -by <their email>
   → shrt verify <name>                       replay and diff, later

Left of edit is derivation, and the tool does it. Right of it is evidence. Yours is the middle: the test data, and the assertions that say what correct means. The gate's shrt chain lint -strict fails the six assertion-quality warnings in the command table; other warnings exit 0. Authoring the contract itself is a different loop, fed by shrt contract quality (PLAYBOOK.md §7).

      shrt run <name>                         a receipt on today's binary
   → shrt verify <name> -run <run-id>         does it still match what a person approved?
   → (change the code)
   → shrt run <name> ; shrt verify ...        the same two lines

run asks whether your assertions hold; verify asks whether every response field still matches the approved run, including what nobody asserted. With no safe spot yet, shrt diff <name> compares the last two runs; it is a comparison, not a verdict (PLAYBOOK.md §9). shrt chain ls shows which chains have a safe spot; expect few at first, since only a person creates one.

1. Approve only on the user's yes. Propose with shrt confirm <c> -note "...", the note saying what you inspected in the responses and why it is right. Present the proposal in the conversation (PLAYBOOK.md §8) and ask. Run -approve -by <user email> only after the user answers yes to that proposal; silence or your own judgement is not a yes.
2. Never reorder, skip or parallelise steps. Order is the contract.
3. Never hand-write a body from memory. Field names and enum values come from the descriptor (shrt catalog describe).
4. Never leave a step asserting only that it did not crash. error.code == OK is the floor, not the assertion (PLAYBOOK.md §4). chain lint -strict fails such a step when its contract declares response facts.