Skip to content

Make the loop contract machine-checked and the contributor path obvious - #5

Merged
AetherAI3 merged 1 commit into
masterfrom
lane3/contributor-funnel
Aug 19, 2026
Merged

Make the loop contract machine-checked and the contributor path obvious#5
AetherAI3 merged 1 commit into
masterfrom
lane3/contributor-funnel

Conversation

@AetherAI3

Copy link
Copy Markdown
Owner

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 DBarr3 namespace.

Landed

  • tools/validate_loops.py — standard-library validator for the PROTOCOL.md §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 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.
  • Issue forms for the three real contribution shapes: a RUN PROMPT that 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.
  • PR template carrying run notes and the safety boundary.
  • CONTRIBUTING.md rewritten 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 documents read-only→branch (four shipped loops already use it), the parenthetical scope-note form (branch-mutating (loops only)), and composed-of.

Validation

  • python tools/validate_loops.py passes locally — 21 loops conform to PROTOCOL.md section 14.
  • I ran the changed RUN PROMPT against a real repo with a real agent

Not run — no RUN PROMPT or 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-id for its filename, wrong name slug, an invented risk-class, a missing # Adversarial Check section, an absolute /Users/... path, and a duplicate loop-id. All five issue forms and the workflow parse as YAML.

Safety boundary

  • The loop stays inside its declared risk-class — no loop behavior changed
  • Nothing merges to a default branch without operator approval
  • No project-specific paths, hostnames, tool names, or infrastructure assumptions were introduced

CONTRIBUTING.md now 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-artifact over 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

…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
AetherAI3 force-pushed the lane3/contributor-funnel branch from 5945845 to 8f03153 Compare August 19, 2026 11:10
@AetherAI3

Copy link
Copy Markdown
Owner Author

Rebased the branch to drop the DBarr3AetherAI3 badge and footer edits — #6 owns that change, and carrying it here would only produce a conflict for whichever merges second. New links added by this PR (the issue-template config, the good first issue pointer in the README) already use the canonical namespace, so no follow-up is needed once #6 lands.

Merge order does not matter now; the two PRs no longer touch the same lines.

@AetherAI3
AetherAI3 merged commit 893313f into master Aug 19, 2026
1 check passed
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>
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.

2 participants