Make the loop contract machine-checked and the contributor path obvious - #5
Merged
Conversation
…obvious The catalog grew to 21 loops with nothing checking that a loop file actually follows the contract it claims to. Frontmatter, section order, and README coverage were conventions held up by review attention alone, and a contributor had 18 lines of CONTRIBUTING.md and no way to know whether their file was correct before opening a PR. - tools/validate_loops.py: standard-library validator for the PROTOCOL.md section 14 contract. Checks frontmatter keys and values, filename/loop-id/name agreement, all eleven sections present and in order, a fenced RUN PROMPT, duplicate ids, non-portable paths, composed-of references, README catalog coverage, and every relative markdown link in the repo. No install, so what CI runs is exactly what a contributor runs. - CI workflow running that one command on every push and pull request. - Issue forms for the three real contribution shapes: a RUN PROMPT that broke, an improvement to an existing loop, and a new loop proposal. The bug form asks which agent and model, because "it did not work" is otherwise unreproducible; it also asks whether the loop exceeded its risk class, which jumps the queue. - Pull request template carrying the run notes and the safety boundary. - CONTRIBUTING.md rewritten into a path: pick a contribution, the contract in short, the five safety requirements and why each exists, how to test a prompt, and permission to say "not run, docs only" instead of ticking a box falsely. Stale claims fixed along the way: the loop-cards title said "The 15 Agentic Loops" while shipping 21, and the README catalog table listed only the base 15 with 16-21 reachable through prose alone. PROTOCOL.md section 14 now documents read-only→branch, which four shipped loops already use, plus the parenthetical scope-note and composed-of forms the catalog relies on. The DBarr3-to-AetherAI3 badge and footer links are deliberately left alone here; PR #6 owns that change, and duplicating it would only conflict. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
AetherAI3
force-pushed
the
lane3/contributor-funnel
branch
from
August 19, 2026 11:10
5945845 to
8f03153
Compare
Owner
Author
|
Rebased the branch to drop the Merge order does not matter now; the two PRs no longer touch the same lines. |
AetherAI3
pushed a commit
to dbarrante/agentic-loops
that referenced
this pull request
Aug 19, 2026
The contributor-funnel work (AetherAI3#5) landed after this branch was cut, so the README catalog area conflicted and the new validator did not exist here yet. Conflicts resolved by taking this branch's generalised section name — "Loops That Run the Catalog" is right now that the catalog is 22 and no longer 15 plus meta — over master's "Loops That Run the Other 15", while keeping master's meta-loop index table. Same for LOOP-20's lead sentence: "the applicable catalog loops" rather than a hard-coded 19. Stale claims the merge exposed, all fixed: - the catalog note still said "the 15 base loops" with LOOP-22 in the table; - the table-of-contents link pointed at the old heading anchor, which nothing caught because the validator only checked relative file links, not same-page anchors; - the loop-cards graphic is titled and alt-texted for the loops it actually draws, LOOP-01 to LOOP-15, rather than for "the base loops", which is now 16. Two validator additions, both prompted by this merge: - Same-page anchors are checked against the headings in the file. Renaming a heading silently breaks every table-of-contents entry pointing at it, and the link and the heading are usually far enough apart that no diff looks wrong. Proven by renaming the heading and watching it fail. - `coordinates-with`, which LOOP-22 introduces, is now documented in PROTOCOL.md section 14 and CONTRIBUTING.md alongside `composed-of`, and its references are resolved the same way. The two mean different things — one loop runs another, the other hands findings to it — and both are worth keeping honest. LOOP-22 itself needed no changes. It conforms to the section 14 contract, is free of project-specific paths and assumptions, and its approval gates are stricter than the protocol default rather than looser. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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.
What changes, and what failure made it necessary
The catalog reached 21 loops with nothing checking that a loop file follows the contract it claims to follow. Frontmatter shape, section order, and README coverage were conventions held up by review attention. A contributor had 18 lines of
CONTRIBUTING.md, no local check, and no way to know their file was correct before opening a PR.That gap had already produced drift: the loop-cards graphic was titled "The 15 Agentic Loops" while the repo shipped 21, the README catalog table listed only the base 15 (LOOP-16 through LOOP-21 were reachable through prose links alone), and the stars badge, made-by badge, and footer all still pointed at the pre-rename
DBarr3namespace.Landed
tools/validate_loops.py— standard-library validator for thePROTOCOL.md§14 contract. Checks frontmatter keys and values, filename/loop-id/nameagreement, all eleven sections present and in order, a fencedRUN PROMPT, duplicate ids, non-portable paths,composed-ofreferences, README catalog coverage, and every relative markdown link in the repo. No install step, so what CI runs is exactly what a contributor runs on a fresh clone..github/workflows/validate.yml— runs that single command on push and PR.RUN PROMPTthat broke, an improvement to an existing loop, a new-loop proposal. The bug form asks which agent and model (otherwise "it did not work" is unreproducible) and whether the loop exceeded its declared risk class, which jumps the queue.CONTRIBUTING.mdrewritten from 18 lines into an actual path: pick a contribution, the contract in short, the five safety requirements and why each exists, how to test a prompt, and explicit permission to write "not run, docs only" rather than tick a box falsely.PROTOCOL.md§14 now documentsread-only→branch(four shipped loops already use it), the parenthetical scope-note form (branch-mutating (loops only)), andcomposed-of.Validation
python tools/validate_loops.pypasses locally —21 loops conform to PROTOCOL.md section 14.RUN PROMPTagainst a real repo with a real agentNot run — no
RUN PROMPTor loop behavior changed in this PR. It is tooling, templates, and documentation only.The validator itself was tested in both directions rather than only written: against the clean catalog (exit 0, 21 loops), and against a deliberately broken probe file, which it rejected with the expected six violations — wrong
loop-idfor its filename, wrongnameslug, an inventedrisk-class, a missing# Adversarial Checksection, an absolute/Users/...path, and a duplicateloop-id. All five issue forms and the workflow parse as YAML.Safety boundary
risk-class— no loop behavior changedCONTRIBUTING.mdnow states the safety rules explicitly (least-invasive risk class, no default-branch merges inside a loop, checkpointed mutations, an adversary that can actually FAIL,FAIL-with-artifactover silent success) so that a contributor cannot weaken one without noticing.For a new loop only
Not applicable — no loop added.
🤖 Generated with Claude Code