Repository navigation
bootstrap AGENTS.md and CONTRIBUTING.md - #26
Merged
lucasbalieiro merged 2 commits intoNov 13, 2026
Merged
Conversation
plebhash
commented
Nov 12, 2026
|
|
||
| A scenario has three outcomes, and *not exercised* is never a pass. When the assertion depends on something the test client cannot provoke (see Testability Tiers in `COVERAGE.md`) and it did not happen, return `ScenarioError::NotExercised` with the reason. Do not report a pass because nothing contradicted the assertion, and do not report a failure because the server made a choice the spec allows. | ||
|
|
||
| The suite runs against remote endpoints that may be slow, silent or gone. Every wait on the endpoint is bounded and ends in a `ScenarioResult`: a scenario never blocks without a timeout and never panics on what the endpoint sent or failed to send. |
Member
Author
There was a problem hiding this comment.
stratum-mining/sv2-spec#246 might add new rules to COVERAGE.md
plebhash
marked this pull request as ready for review
November 12, 2026 21:32
Bootstrap the contribution guide following the one on sv2-apps and stratum, with the sections that apply here: how to ask questions, where communication happens, the contribution workflow and the commit guidelines. Step 3 of the workflow states what is specific to this repository: a scenario gets its Scenario Catalog row before it is implemented, its Suite Coverage row flips to ✅ in the same PR, and the checks CI runs (formatting on nightly rustfmt).
Follow the pattern established on sv2-apps, stratum and sv2-spec: a committed AGENTS.md that every contributor's agent reads, a CLAUDE.md symlink to it, and a gitignored AGENTS_CUSTOM.md for personal guidance. The sections shared with sv2-apps and stratum (bug patching, PR reviews, drafting issues, Ponytail) are copied as they are. The rest is specific to this repository and targets the mistakes an agent makes here: Sv2 claims taken from recall or from SRI behaviour instead of spec text, scenarios that fail endpoints the spec allows, the Scenario Catalog, the Suite Coverage table and the registry drifting apart, and failures against ecosystem projects reported without what their maintainer needs to check the claim. Closes stratum-mining#9
plebhash
force-pushed
the
2026-11-06-agents-md
branch
from
November 13, 2026 20:00
4b8775a to
785dd12
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #9
Follows the pattern established on
sv2-apps,stratumandsv2-spec: a committedAGENTS.mdthat every contributor's agent reads, aCLAUDE.mdsymlink to it, and a gitignoredAGENTS_CUSTOM.mdfor personal guidance. SinceAGENTS.mdpoints agents atCONTRIBUTING.mdfor commits and this repo had none, the first commit bootstraps one.CONTRIBUTING.mdAdapted from the
sv2-apps/stratumone. Kept: questions, project communications, the contribution workflow and the commit guidelines. Specific to this repo, in step 3 of the workflow: a scenario gets its Scenario Catalog row before it is implemented, its Suite Coverage row flips to ✅ in the same PR, and the three CI checks (formatting runs on nightlyrustfmt). Dropped: Monitoring API Schema, Versioning and public dependencies, Project Structure. "Your First Code Contribution" points at the ❌ rows of the Suite Coverage table instead ofgood first issuelabels.AGENTS.mdThe sections shared by
sv2-appsandstratum(Bug patching, PR reviews, Drafting issues, Ponytail) are copied verbatim. Left out as not applying here: the companion-PR cross-repo flow, Loupe audit triage, pre-mined shares, and thesv2-specproject overview.The rest targets the mistakes an agent makes on this repo specifically:
cargo testpassing against SRI Pool shows the scenario runs, not that its reading of the spec is right. Before a scenario fails an endpoint, look for a compliant implementation that would trip it (the C-SC-7 false positive is the example, without naming the issue).COVERAGE.mdand the scenario registry. The catalog, the Suite Coverage table and theentries()registry are checked against each other in the same change; a row is ✅ exactly when a scenario registered under its ID exists. This is the drift consider adding a CI check to verify COVERAGE.md drift #8 wants CI to catch, so agents stop causing it in the meantime. IDs follow the rule already inCOVERAGE.md: append, never renumber or reuse.TestClientprimitives, not exercised is never a pass, every wait on the endpoint is bounded.[Tracker]issue, with the target, the scenario ID, the spec text pinned to a commit, and the suite's output, following the shape of PyBLØCK:SetupConnectionaccepted with a version range that excludes 2 (C-SC-8) #15 and Braiins Pool:SetupConnectionwithprotocol=1(Job Declaration) accepted on the mining endpoint, then no Job Declaration service (C-SC-7) #19. Rule out the scenario itself before drafting.No
.skills/folder yet (ref the comment on #9):AGENTS.mdcomes first, skills can follow once there is something to put in them.For reviewers
sv2-appshas a "Code comments and attributes" section (comment and attribute blocks binding to the item below them) thatstratumdoes not. Left out; say so if you want it in.