Custos docs

Reference

Hedera Harness

The .harness/ folder is a Hedera Harness recipe: it hands an AI coding agent one realistic task on this template, then checks the result in tiers, from file checks up to a live action on Hedera testnet.

The recipe#

The task: add an ETH-USD market by following the "Add a market" recipe in AGENTS.md. In Custos a market is configuration, not code: an entry in packages/foundry/markets.json, an ETH-specific test, and a row in the README's markets table. The contracts must not change. The full brief is .harness/prd.md; the spec is .harness/spec.yaml (hedera-harness(opens in a new tab) 1.2.2, schema v2).

The same steps by hand are in Add a market.

Tiers#

TierFileChecks
0validators/static.jsonmarkets.json has ETH-USD with Chainlink ETH/USD and Supra pair 19, HBAR-USD is untouched, test/markets/EthUsdMarket.t.sol exists, the README lists ETH-USD, AGENTS.md documents markets.json and check-market, and no root or app .env file exists (packages/foundry/.env is allowed: the template's postinstall copies it from .env.example)
1validators/yarn.jsoncheck-markets ETH-USD (offline config check), the ETH test, all contract tests and invariants, foundry:lint, the app's type check, lint and production build. No keys, no network
2validators/playwright-smoke.yaml/, /keeper, /trade, /pool and /debug load with no error overlay
3acceptance-contract.jsonAn adversarial agent grades the running app with no wallet: the keeper, trade and pool pages still read the live HBAR-USD deployment (adding a market must not break anything)
3.5spec.yaml → chainValidationDeploys a PriceGuard with the new ETH-USD config from the harness's throwaway testnet account and reads both live feeds; fails if either doesn't answer

Run it#

bash
# check the recipe itself
yarn harness:doctor --recipe-only

# tiers 0–2 against the current workspace, no agent
yarn harness:validate

# the full loop: the agent implements the PRD, every tier runs,
# failures go back to the agent (up to 3 attempts)
export HEDERA_OPERATOR_ID=0.0.xxxx HEDERA_OPERATOR_KEY=0x...   # an ECDSA testnet account with ~15 ℏ; shell only, never a file
yarn harness:run

The chain tier needs Foundry (forge, cast) on the PATH. The harness creates one EVM-aliased account per run, funds it with 10 ℏ from your operator, passes it to the deploy command as DEPLOYER_PRIVATE_KEY (environment only), and sweeps what's left back afterwards. A PriceGuard deploy costs about 1 ℏ. Run artifacts go to .harness/runs/, which is gitignored.

hedera-harness and playwright must both be root devDependencies (they are, in package.json). Under npx hedera-harness, the tool can't import playwright from npm's cache, and the Tier 2 gate fails before any route with no visible reason.

How it was verified#

Fails without the feature, passes with it

Before handing the task to an agent, the PRD was solved by hand in three files (the markets.json entry, the ETH test, the README row), kept as .harness/reference/eth-usd.patch and not applied: the template ships without ETH-USD on purpose, so the recipe has something to do. hedera-harness validate .harness/spec.yaml on 2026-10-03, on two fresh clones:

WorkspaceResult
main as shipped (no ETH-USD)passed=false, 8 findings, every one about the missing feature, no false alarms. Tier 2 is skipped because Tier 1 failed
main + the reference implementation (3 files)passed=true, findings=0, playwrightGate=true routes=5
the passing run
command yarn install exit=0
command yarn workspace @sh/foundry check-markets ETH-USD exit=0
command node -e "require('fs').statSync('packages/foundry/test/markets/EthUsdMarket.t.sol')" && yarn workspace @sh/foundry test --match-path test/markets/EthUsdMarket.t.sol exit=0
command yarn foundry:test exit=0
command yarn foundry:lint exit=0
command yarn next:check-types exit=0
command yarn next:lint --max-warnings=0 exit=0
command yarn next:build exit=0
Playwright gate: / /keeper /trade /pool /debug → 200, rendered, 0 console errors, no forbidden text
Validation finished  passed=true  findings=0  playwrightGate=true routes=5

CI proves it both ways

.github/workflows/harness.yaml runs on Ubuntu with no secrets, on every push to main and on pull requests. It checks the recipe with yarn harness:doctor --recipe-only, then yarn harness:validate on main as shipped must fail, and fail for the missing ETH-USD market; then it applies .harness/reference/eth-usd.patch and yarn harness:validate must pass, Playwright tier included. The chain tier and the agent tiers need an operator account and an agent, so they run only under yarn harness:run.

A recorded agent run

hedera-harness run .harness/spec.yaml on 2026-10-03, on a fresh clone of main with no ETH-USD, agent preset claude (Claude Opus), operator an ECDSA testnet account passed through environment variables only.

StageOutcome
ResultPASSED, attempt 1 of 3, no findings (passed=true, openFindingIds=[])
Duration15 min 39 s (01:39:05 → 01:54:43 UTC), 17 min wall clock including setup
1/4 GenerateThe agent read AGENTS.md and the PRD and changed 4 files, no contracts: the ETH-USD entry in markets.json, a new test/markets/EthUsdMarket.t.sol (5 tests, reading the entry from markets.json), a README row noting ~3,600 s on mainnet, and its own GENERATION_NOTES.md
2/4 AssertTier 0 static: 0 findings. Tier 1: check-markets ETH-USD, the ETH test, all contract tests, foundry:lint, type check, app lint and production build all exit 0
Chain (Tier 3.5)The harness created and funded throwaway account 0.0.10834938(opens in a new tab), ran yarn custos:check-market:testnet --market ETH-USD (a PriceGuard deployed with the agent's config reading both live feeds), then swept the account back to 0 ℏ
3/4 SmokePlaywright gate: /, /keeper, /trade, /pool, /debug
4/4 EvaluateThe adversarial validator's verdict, quoted below

The harness committed the agent's work to a throwaway run branch, which isn't kept in the repo: the recipe's job is to produce it, so main stays without ETH-USD.

Windows#