Sparklend test authoring skill

[tobal-g]

SparkLend test-authoring skill and Claude workflow

What this adds

• A skill at .claude/skills/sparklend-testing/ for authoring, debugging, and reviewing SparkLend Foundry tests against the protocol revision pinned under lib/.
• Two independently authored test suites that exercise the guidance: focused WadRayMath boundary/fuzz coverage through a thin wrapper, and a tree-first BTT suite for recovery from a synthetic stale collateral flag at a non-identity liquidity index.
• A GitHub Actions workflow that accepts test-writing or review tasks through @claude comments, runs Claude Code with the skill, and reports results back to the triggering issue or PR.

No protocol source, dependency metadata, global Foundry configuration, or submodule pin changes relative to origin/master.

Tests included

• test/fuzz/WadRayMath.t.sol and test/fuzz/wrappers/WadRayMathWrapper.sol call the pinned core's rayMul and rayDiv, cover deterministic zero, identity, half-up rounding, denominator, and overflow boundaries, and compare bounded fuzz inputs with explicit half-up oracles.
• test/integration/btt/IndexedCollateralSafety.tree specifies independent failure and recovery leaves around the first mintable scaled amount.
• test/integration/btt/IndexedCollateralSafety.t.sol executes the live Pool proxy path from a deliberately constructed stale collateral configuration. It checks the exact named reverts below the boundary, successful resupply at the boundary, subsequent collateral disablement, and complete relevant reserve, token, account, treasury, debt, and cash state before and after each action.

Skill contents

• SKILL.md: entry point, required reading, core operating rules, and the prohibition on changing the protocol target to make a test pass.
• references/repository-principles.md: pinned-source hierarchy, suite taxonomy, BTT conventions, proxy/caller/accounting semantics, fixture units, assertion requirements, and non-vacuous fuzz/invariant criteria.
• references/authoring-workflow.md: the end-to-end procedure from target selection and tree design through literal source tracing, scenario construction, full-state assertions, arithmetic anchoring, inheritance audit, and narrow-to-broad verification.
• references/anti-patterns.md: concrete failure modes extracted from the SC-1569 history, including green known-bug oracles, gated or vacuous invariants, incomplete liabilities, unproven tolerances, missing deterministic boundaries, and incorrect provenance.
• references/review-rubric.md: severity-ordered adversarial review criteria, comment review rules, and the merge-readiness gate.

Local use

Run Claude Code from the repository root and ask it to use sparklend-testing for any task that writes, revises, debugs, or reviews tests. For example:

Use the sparklend-testing skill to add BTT coverage for <behavior>. Trace the pinned core, update the tree first, and run targeted tests before the broader suite.

Claude loads .claude/skills/sparklend-testing/SKILL.md; authoring requires the repository principles and workflow references, while review or revision also requires the anti-patterns and rubric. Initialize submodules, install Foundry, and set MAINNET_RPC_URL when fork coverage is required.

GitHub workflow use

The workflow must first exist on the default branch. It has no workflow_dispatch interface or structured inputs; create either an issue/PR conversation comment (issue_comment) or an inline PR review comment (pull_request_review_comment) whose body contains @claude. Put the test-authoring, revision, or review task in that same comment.

The job:

• Runs only for newly created comments that contain @claude; runs for the same issue/PR share a concurrency group and are not canceled in progress.
• Requests contents: write, pull-requests: write, issues: write, id-token: write, and actions: read.
• Exports MAINNET_RPC_URL and ETHERSCAN_API_KEY from repository secrets.
• Uses actions/checkout@v4 with recursive submodules, depth 1, and persisted credentials. No explicit checkout ref is configured.
• Installs Foundry, runs forge build, then invokes anthropics/claude-code-action@v1 with CLAUDE_CODE_OAUTH_TOKEN, model claude-fable-5, and the allowed tools Bash,Edit,Write,Read,Glob,Grep,Task.
• Instructs Claude to use this skill for all test work, run targeted tests followed by forge test, report exact commands and counts, and never weaken a failing safety property. Changes worth landing are committed on a new branch and opened as a PR only when the full suite passes; otherwise Claude reports the failures on the triggering issue/PR.
• Maintains a progress/summary comment, streams full output to the job log, and uploads the execution transcript for 30 days even if the Claude step fails.

Repository operators must configure CLAUDE_CODE_OAUTH_TOKEN and a usable MAINNET_RPC_URL for the configured full-suite requirement; ETHERSCAN_API_KEY is also passed through for fork setups that resolve it.

Methodology and verification

The skill was derived from the repository's existing BTT, fuzz, ACL, fork, fixture, and helper conventions; the pinned sparklend-v1-core execution paths; and an ancestry-aware review of the historical SC-1569 test chain. The two added suites were then derived independently from the pinned math and Pool behavior, implemented with deterministic boundary anchors and live-path state assertions, and reviewed adversarially against the rubric and anti-pattern catalog. Follow-up review tightened comment scope and added explicit comment-quality gates without changing the tested behavior.

Current targeted verification passes forge test --match-contract WadRayMathTests (9/9) and forge test --match-contract IndexedCollateralSafetyTests (4/4). A local forge test run passed 410 tests and failed only StableBorrowTests.setUp() because the available mainnet RPC endpoint returned HTTP 402; the workflow is configured to require a valid MAINNET_RPC_URL and must not open a completed PR on that result. git diff --check origin/master...HEAD is clean, and the core pin remains 8120e495061dc3315f0a86f682f4ca645a418bf7.