Add self-correcting Builder–Judge–Manager contract (v0.1.4) - #1
Merged
Conversation
…oops. Separate produce from judge with structured handoffs, ground truth, and a hard max_revisions stop so agents escalate instead of looping forever. Co-authored-by: Cursor <cursoragent@cursor.com>
There was a problem hiding this comment.
Pull request overview
Adds a shared “self-correcting” quality contract (Builder → Judge → Manager) and wires producing loops to adopt it, including schema + docs + emitted adapters, with tests to keep adoption consistent.
Changes:
- Introduces
contracts/self-correcting.md(handoffs/verdict/action templates, ground-truth requirements, hard revision ceiling) pluscontracts/README.md. - Updates producing loops (
plan-and-implement,tdd,reproduce-and-fix,sar,adversarial-gate,de-ai-ify,migrate) and meta loops (swarm,use-the-loop) to reference and honor the contract. - Adds schema fields + tests and updates README/install docs + changelog/versioning for v0.1.4.
Reviewed changes
Copilot reviewed 63 out of 63 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| test/self-correcting-contract.test.js | Adds coverage to ensure self-correcting adopters reference the contract and declare a revision ceiling. |
| test/persona-coverage.test.js | Includes de-ai-ify in persona-coverage expectations. |
| schema/loop.schema.json | Adds optional self_correcting + self_correcting_max_revisions fields. |
| README.md | Documents self-correcting QC and bumps displayed version to v0.1.4. |
| personas/README.md | Documents persona usage for additional loops and notes contract-read requirement for self-correcting loops. |
| package.json | Bumps package version to 0.1.4. |
| loops/use-the-loop/loop.yaml | Bumps loop version. |
| loops/use-the-loop/loop.md | Requires honoring nested self-correcting stops and preferring Judge-ending compositions. |
| loops/tdd/loop.yaml | Marks self-correcting, adds revision ceiling, introduces prove/revise phases, updates outputs/personas. |
| loops/tdd/loop.md | Adds contract section and detailed Builder/Judge/Manager workflow for TDD. |
| loops/swarm/loop.yaml | Bumps loop version. |
| loops/swarm/loop.md | Adds de-ai-ify to allowable composition and honors nested self-correcting stops. |
| loops/sar/loop.yaml | Marks self-correcting and adds revision ceiling; updates description. |
| loops/sar/loop.md | Adds contract section and aligns phases to Builder/Judge/Manager with capped repair cycles. |
| loops/reproduce-and-fix/loop.yaml | Marks self-correcting, adds revision ceiling, introduces prove/revise phases, updates outputs/personas. |
| loops/reproduce-and-fix/loop.md | Adds contract section and detailed Prove/Judge path with capped revisions. |
| loops/plan-and-implement/loop.yaml | Marks self-correcting, adds revision ceiling, introduces judge/revise phases, updates outputs/personas. |
| loops/plan-and-implement/loop.md | Adds contract section, acceptance checks, and explicit Judge/Manager routing. |
| loops/migrate/loop.yaml | Marks self-correcting, adds revision ceiling, updates description. |
| loops/migrate/loop.md | Adds contract section and defines capped “thrash attempts” behavior. |
| loops/explain-codebase/loop.yaml | Bumps loop version. |
| loops/explain-codebase/loop.md | Clarifies it does not adopt the full contract; encourages path citations as light ground truth. |
| loops/de-ai-ify/loop.yaml | Marks self-correcting, adds revision ceiling, updates description. |
| loops/de-ai-ify/loop.md | Adds contract section and formalizes verify→re-spec→apply revise ceiling + verdict. |
| loops/adversarial-gate/loop.yaml | Marks self-correcting, adds revision ceiling, updates description. |
| loops/adversarial-gate/loop.md | Adds contract section; maps persona rounds and gate verdicts to Judge/Manager semantics. |
| INSTALL.mdc | Adds install guidance for self-correcting loops reading the contract. |
| INSTALL-GLOBAL.mdc | Adds global install guidance for self-correcting loops reading the contract. |
| INSTALL-CLAUDE.md | Notes self-correcting contract path for producing loops. |
| evals/adversarial-eval-loops.md | Adds follow-up eval prompts targeting the new contract behavior. |
| contracts/self-correcting.md | Adds the core Builder/Judge/Manager contract and adoption table. |
| contracts/README.md | Documents contracts directory and canonical contract paths. |
| CHANGELOG.md | Adds 0.1.4 release notes describing contract + adoption changes. |
| .cursor/rules/loops-use-the-loop.mdc | Re-emits Cursor rules content reflecting nested-stop / Judge-ending guidance. |
| .cursor/rules/loops-tdd.mdc | Re-emits Cursor rules content reflecting self-correcting TDD flow. |
| .cursor/rules/loops-swarm.mdc | Re-emits Cursor rules content reflecting nested-stop / Judge-ending guidance. |
| .cursor/rules/loops-sar.mdc | Re-emits Cursor rules content reflecting self-correcting SAR flow. |
| .cursor/rules/loops-reproduce-and-fix.mdc | Re-emits Cursor rules content reflecting self-correcting reproduce-and-fix flow. |
| .cursor/rules/loops-plan-and-implement.mdc | Re-emits Cursor rules content reflecting self-correcting plan-and-implement flow. |
| .cursor/rules/loops-migrate.mdc | Re-emits Cursor rules content reflecting self-correcting migrate guidance. |
| .cursor/rules/loops-explain-codebase.mdc | Re-emits Cursor rules content clarifying “light ground truth” only. |
| .cursor/rules/loops-de-ai-ify.mdc | Re-emits Cursor rules content reflecting self-correcting de-ai-ify flow. |
| .cursor/rules/loops-adversarial-gate.mdc | Re-emits Cursor rules content reflecting self-correcting adversarial-gate mapping. |
| .claude/skills/loops-use-the-loop/SKILL.md | Re-emits Claude skill doc with nested-stop / Judge-ending guidance. |
| .claude/skills/loops-use-the-loop/loop.yaml | Syncs emitted Claude skill YAML version. |
| .claude/skills/loops-tdd/SKILL.md | Re-emits Claude skill doc reflecting self-correcting TDD flow. |
| .claude/skills/loops-tdd/loop.yaml | Syncs emitted Claude skill YAML with self-correcting fields. |
| .claude/skills/loops-swarm/SKILL.md | Re-emits Claude skill doc reflecting nested-stop / Judge-ending guidance. |
| .claude/skills/loops-swarm/loop.yaml | Syncs emitted Claude skill YAML version. |
| .claude/skills/loops-sar/SKILL.md | Re-emits Claude skill doc reflecting self-correcting SAR flow. |
| .claude/skills/loops-sar/loop.yaml | Syncs emitted Claude skill YAML with self-correcting fields. |
| .claude/skills/loops-reproduce-and-fix/SKILL.md | Re-emits Claude skill doc reflecting self-correcting reproduce-and-fix flow. |
| .claude/skills/loops-reproduce-and-fix/loop.yaml | Syncs emitted Claude skill YAML with self-correcting fields. |
| .claude/skills/loops-plan-and-implement/SKILL.md | Re-emits Claude skill doc reflecting self-correcting plan-and-implement flow. |
| .claude/skills/loops-plan-and-implement/loop.yaml | Syncs emitted Claude skill YAML with self-correcting fields. |
| .claude/skills/loops-migrate/SKILL.md | Re-emits Claude skill doc reflecting self-correcting migrate guidance. |
| .claude/skills/loops-migrate/loop.yaml | Syncs emitted Claude skill YAML with self-correcting fields. |
| .claude/skills/loops-explain-codebase/SKILL.md | Re-emits Claude skill doc clarifying “light ground truth” only. |
| .claude/skills/loops-explain-codebase/loop.yaml | Syncs emitted Claude skill YAML version. |
| .claude/skills/loops-de-ai-ify/SKILL.md | Re-emits Claude skill doc reflecting self-correcting de-ai-ify flow. |
| .claude/skills/loops-de-ai-ify/loop.yaml | Syncs emitted Claude skill YAML with self-correcting fields. |
| .claude/skills/loops-adversarial-gate/SKILL.md | Re-emits Claude skill doc reflecting self-correcting adversarial-gate mapping. |
| .claude/skills/loops-adversarial-gate/loop.yaml | Syncs emitted Claude skill YAML with self-correcting fields. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+70
to
+73
| ## Stop conditions (Manager — hard logic) | ||
|
|
||
| Defaults for loops that adopt this contract (override in `loop.yaml` under `self_correcting:`): | ||
|
|
Owner
Author
There was a problem hiding this comment.
Fixed: contract now documents the flat keys (self_correcting / self_correcting_max_revisions) instead of a nested self_correcting: block.
Comment on lines
+8
to
+9
| * 2. Every loop.yaml with self_correcting: true references the contract | ||
| * path in its loop.md and declares a max_revisions. |
Owner
Author
There was a problem hiding this comment.
Fixed: header comment now names self_correcting_max_revisions and states the test covers canonical dirs only (emitted copies stay under emit --check).
Clarify flat loop.yaml keys (self_correcting + self_correcting_max_revisions) and that the coverage test only checks canonical loop dirs. Co-authored-by: Cursor <cursoragent@cursor.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.
Summary
contracts/self-correcting.mdwith Builder → Judge → Manager roles, handoff formats, ground truth rules,max_revisions: 3, and stress-test checklist.plan-and-implement,tdd,reproduce-and-fix,sar,adversarial-gate,de-ai-ify,migrate) to adopt the contract; meta loops honor nested ESCALATE and prefer ending on a Judge stage.Test plan
npm test(149 pass, includingself-correcting-contract.test.js)node adapters/emit.js --check(no drift)contracts/self-correcting.mdMade with Cursor