Skip to content

bootstrap AGENTS.md and CONTRIBUTING.md - #26

Merged
lucasbalieiro merged 2 commits into
stratum-mining:mainfrom
plebhash:2026-11-06-agents-md
Nov 13, 2026
Merged

lucasbalieiro merged 2 commits into
stratum-mining:mainfrom
plebhash:2026-11-06-agents-md

Conversation

@plebhash

@plebhash plebhash commented Nov 6, 2026 •

Copy link
Copy Markdown
Member

Closes #9

Follows 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. Since AGENTS.md points agents at CONTRIBUTING.md for commits and this repo had none, the first commit bootstraps one.

CONTRIBUTING.md

Adapted from the sv2-apps/stratum one. 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 nightly rustfmt). Dropped: Monitoring API Schema, Versioning and public dependencies, Project Structure. "Your First Code Contribution" points at the ❌ rows of the Suite Coverage table instead of good first issue labels.

AGENTS.md

The sections shared by sv2-apps and stratum (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 the sv2-spec project overview.

The rest targets the mistakes an agent makes on this repo specifically:

  • The spec is the oracle. Sv2 claims come from spec text read during the work, not from recall and not from how SRI behaves; cargo test passing 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.md and the scenario registry. The catalog, the Suite Coverage table and the entries() 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 in COVERAGE.md: append, never renumber or reuse.
  • Scenarios. Reuse TestClient primitives, not exercised is never a pass, every wait on the endpoint is bounded.
  • Reporting a failure on an ecosystem project. One issue per bug under the project's [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: SetupConnection accepted with a version range that excludes 2 (C-SC-8) #15 and Braiins Pool: SetupConnection with protocol=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.md comes first, skills can follow once there is something to put in them.

For reviewers

  • The commit guidelines are copied verbatim, so they ask for conventional-commit structure, which this repo's history so far does not follow. Fine to keep, fine to drop.
  • sv2-apps has a "Code comments and attributes" section (comment and attribute blocks binding to the item below them) that stratum does not. Left out; say so if you want it in.

Comment thread AGENTS.md

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.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

stratum-mining/sv2-spec#246 might add new rules to COVERAGE.md

@plebhash
plebhash marked this pull request as ready for review November 12, 2026 21:32
Comment thread CONTRIBUTING.md Resolved
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
plebhash force-pushed the 2026-11-06-agents-md branch from 4b8775a to 785dd12 Compare November 13, 2026 20:00

@lucasbalieiro lucasbalieiro left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ACK

@lucasbalieiro
lucasbalieiro merged commit e31780a into stratum-mining:main Nov 13, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

bootstrap AGENTS.md

2 participants