@eir-labs/coltrane 0.7.5 → 0.8.1

package/institutions/quartet.json

@@ -4,11 +4,83 @@
     "name": "The Quartet",
     "kind": "institution",
     "laws": [
-      "Authority attaches to the chair, never to the incumbent. A named agent may act only within the capability grants of a chair it has been seated in; removing the agent from the chair removes the authority with it.",
-      "A capability grant names its objects exhaustively. A grant that names a standard, tool, or type the genome does not contain is a dead name and is refused at authoring time rather than resolved at dispatch.",
-      "Every chair states its mission and its obligations before an incumbent is seated. An office whose mission is inferred from its occupant's behaviour is not an office.",
-      "Lineage is cited or it is not claimed. An agent's name may be anchored in a forebear only where the record carries the forebear's identity and the primary or scholarly source the attributed disposition is documented in.",
-      "The institution exposes nothing to another institution except by contract."
+      {
+        "attributes": "any agent seated in an institutional chair",
+        "deontic": "forbidden",
+        "aim": "exercise a capability the seated chair grants do not contain",
+        "conditions": "while acting under an institutional seating",
+        "or_else": "the action is refused at dispatch, and the authority lapses the moment the agent is unseated",
+        "check": {
+          "predicate": "(subseteq exercised_caps chair_caps)",
+          "inputs": {
+            "exercised_caps": "CapGrant[]",
+            "chair_caps": "CapGrant[]"
+          }
+        },
+        "content_hash": "sha256:0d27ad56db185576590af99cd368e5826b7bc1589cf23b95bbbb890f8a863253"
+      },
+      {
+        "attributes": "any capability grant",
+        "deontic": "obliged",
+        "aim": "name only standards, tools, and types the genome contains",
+        "conditions": "at authoring time",
+        "or_else": "the grant is a dead name and is refused at authoring rather than resolved at dispatch",
+        "check": {
+          "predicate": "(forall o grant_objects (resolvable o genome))",
+          "inputs": {
+            "grant_objects": "string[]",
+            "genome": "Genome"
+          }
+        },
+        "content_hash": "sha256:faa936f438ae56f08a9f206f0c06603bb4e6c7012f4e2112f3a4557996ec5904"
+      },
+      {
+        "attributes": "every chair",
+        "deontic": "obliged",
+        "aim": "state its mission and its obligations before an incumbent is seated",
+        "conditions": "before any chair assignment for the chair is created",
+        "or_else": "the seating is refused; an office whose mission is inferred from its occupant is not an office",
+        "check": {
+          "predicate": "(and (nonempty chair_mission) (declared_before chair_obligations seat_created))",
+          "inputs": {
+            "chair_mission": "string",
+            "chair_obligations": "NormPair[]",
+            "seat_created": "timestamp"
+          }
+        },
+        "content_hash": "sha256:92d78f11e0b46bf31afe7b41c5037d0f238290589f2636b86118ab533249e2cc"
+      },
+      {
+        "attributes": "any agent name anchored in a forebear",
+        "deontic": "forbidden",
+        "aim": "claim descent from a forebear whose record lacks the forebear identity and a primary or scholarly source for the attributed disposition",
+        "conditions": "whenever a lineage attribution edge is authored",
+        "or_else": "the attribution is not claimed; an uncited lineage is a recollection, not a record",
+        "check": {
+          "predicate": "(and (has edge_source_figure) (or (has edge_source_primary_text) (has edge_source_scholarship)))",
+          "inputs": {
+            "edge_source_figure": "string",
+            "edge_source_primary_text": "string",
+            "edge_source_scholarship": "string"
+          }
+        },
+        "content_hash": "sha256:ee6c8db46e22e9b50a4862b140912634458438d96a6c1fda503e2b6782101e10"
+      },
+      {
+        "attributes": "the institution",
+        "deontic": "forbidden",
+        "aim": "expose any capability to another institution except through a witnessed exchange contract",
+        "conditions": "at all times",
+        "or_else": "the cross-institution access is refused; exposure exists only where an exchange contract carries the cap",
+        "check": {
+          "predicate": "(forall x cross_institution_access (backed_by_contract x exchange_contracts))",
+          "inputs": {
+            "cross_institution_access": "Access[]",
+            "exchange_contracts": "ExchangeContract[]"
+          }
+        },
+        "content_hash": "sha256:09c3ca9ff6c1da5921e1fc97a42602fc0896b4ac660ba8ae6ed51e4594070b60"
+      }
     ],
     "sovereign": false
   },
@@ -92,10 +164,30 @@
         }
       ],
       "obligations": [
-        "State the boundary of the read in the output; an unstated boundary makes an incomplete read indistinguishable from a complete one.",
-        "Record the source locator for every retrieved fact.",
-        "Emit no scope, ranking, or recommendation \u2014 those belong to the direction-setter.",
-        "Hold only a read-only tool grant, and only for the duration of the seating."
+        {
+          "attributes": "the field-reader",
+          "aim": "state the boundary of the read in the output",
+          "deontic": "obliged",
+          "tier": "declared"
+        },
+        {
+          "attributes": "the field-reader",
+          "aim": "record the source locator for every retrieved fact",
+          "deontic": "obliged",
+          "tier": "declared"
+        },
+        {
+          "attributes": "the field-reader",
+          "aim": "emit any scope, ranking, or recommendation, which belong to the direction-setter",
+          "deontic": "forbidden",
+          "tier": "declared"
+        },
+        {
+          "attributes": "the field-reader",
+          "aim": "hold any tool grant wider than read-only or outlasting the seating",
+          "deontic": "forbidden",
+          "tier": "declared"
+        }
       ]
     },
     {
@@ -123,11 +215,36 @@
         }
       ],
       "obligations": [
-        "State the criteria before applying them.",
-        "Record every alternative set aside, with its reason.",
-        "Do not re-decide the scope at verification time to make a failing result pass.",
-        "Separate what was checked from what was reasoned about, and return insufficient evidence where the evidence does not reach the question.",
-        "Do not perform the work this chair directs."
+        {
+          "attributes": "the direction-setter",
+          "aim": "state the criteria before applying them",
+          "deontic": "obliged",
+          "tier": "declared"
+        },
+        {
+          "attributes": "the direction-setter",
+          "aim": "record every alternative set aside, with its reason",
+          "deontic": "obliged",
+          "tier": "declared"
+        },
+        {
+          "attributes": "the direction-setter",
+          "aim": "re-decide the scope at verification time to make a failing result pass",
+          "deontic": "forbidden",
+          "tier": "declared"
+        },
+        {
+          "attributes": "the direction-setter",
+          "aim": "separate what was checked from what was reasoned about, and return insufficient evidence where the evidence does not reach the question",
+          "deontic": "obliged",
+          "tier": "declared"
+        },
+        {
+          "attributes": "the direction-setter",
+          "aim": "perform the work this chair directs",
+          "deontic": "forbidden",
+          "tier": "declared"
+        }
       ]
     },
     {
@@ -135,7 +252,7 @@
       "institution_slug": "quartet",
       "role": "structure-builder",
       "function": "CREATE",
-      "mission": "Settle the ordered structure a piece of work will be built through \u2014 checks before the changes they check \u2014 and then make the thing that structure implies, from the upstream record alone.",
+      "mission": "Settle the ordered structure a piece of work will be built through — checks before the changes they check — and then make the thing that structure implies, from the upstream record alone.",
       "required_skills": [],
       "preferred_skills": [
         "structure-conformance"
@@ -161,11 +278,36 @@
         }
       ],
       "obligations": [
-        "Settle the structure before producing the artefact.",
-        "Order the check before the change it checks.",
-        "Do not widen the scope the direction-setter fixed.",
-        "Record every departure from the settled structure, with its reason, rather than revising the structure after the fact.",
-        "Hold no tool grant: the artefact is emitted as reviewable content and is never applied."
+        {
+          "attributes": "the structure-builder",
+          "aim": "settle the structure before producing the artefact",
+          "deontic": "obliged",
+          "tier": "declared"
+        },
+        {
+          "attributes": "the structure-builder",
+          "aim": "order the check before the change it checks",
+          "deontic": "obliged",
+          "tier": "declared"
+        },
+        {
+          "attributes": "the structure-builder",
+          "aim": "widen the scope the direction-setter fixed",
+          "deontic": "forbidden",
+          "tier": "declared"
+        },
+        {
+          "attributes": "the structure-builder",
+          "aim": "record every departure from the settled structure, with its reason, rather than revising the structure after the fact",
+          "deontic": "obliged",
+          "tier": "declared"
+        },
+        {
+          "attributes": "the structure-builder",
+          "aim": "hold any tool grant or apply the artefact to a working tree; the artefact is emitted as reviewable content",
+          "deontic": "forbidden",
+          "tier": "declared"
+        }
       ]
     },
     {
@@ -194,9 +336,24 @@
         }
       ],
       "obligations": [
-        "Review the sealed outputs an approval presents before accepting them; an approval that does not cite what it reviewed is void.",
-        "Refuse rather than delegate the refusal: this office cannot be held by a model agent, and its verdict cannot be produced by one.",
-        "This chair ships UNASSIGNED. Seating it is the adopting organization's first governance act: the reader seats themselves."
+        {
+          "attributes": "the responsible-officer",
+          "aim": "review the sealed outputs an approval presents before accepting them; an approval that does not cite what it reviewed is void",
+          "deontic": "obliged",
+          "tier": "declared"
+        },
+        {
+          "attributes": "the responsible-officer",
+          "aim": "delegate the refusal, or let the office be held or its verdict produced by a model agent",
+          "deontic": "forbidden",
+          "tier": "declared"
+        },
+        {
+          "attributes": "the adopting organization",
+          "aim": "seat this chair as its first governance act, since it ships unassigned and the reader seats themselves",
+          "deontic": "obliged",
+          "tier": "declared"
+        }
       ]
     }
   ],
@@ -271,7 +428,7 @@
       "name": "Bill Evans",
       "domain": "modern jazz (piano)",
       "kind": "musician",
-      "what_taken": "Born 16 August 1929 in Plainfield, New Jersey; died 15 September 1980 in New York City. What the structure-builder chair takes is the documented practice of harmonic construction: rootless left-hand voicings built interval by interval, and the layered self-scrutiny of Conversations with Myself (Verve, 1963), on which Evans overdubbed three simultaneous piano parts and answered his own lines. Evans stated the underlying discipline himself in Improvisation in Jazz, his liner note to Miles Davis's Kind of Blue (Columbia, 1959), where he compared the improviser's position to that of the Japanese brush painter working on a surface that permits no erasure \u2014 structure settled before the stroke. Nothing of the man's biography beyond this working disposition is claimed or carried."
+      "what_taken": "Born 16 August 1929 in Plainfield, New Jersey; died 15 September 1980 in New York City. What the structure-builder chair takes is the documented practice of harmonic construction: rootless left-hand voicings built interval by interval, and the layered self-scrutiny of Conversations with Myself (Verve, 1963), on which Evans overdubbed three simultaneous piano parts and answered his own lines. Evans stated the underlying discipline himself in Improvisation in Jazz, his liner note to Miles Davis's Kind of Blue (Columbia, 1959), where he compared the improviser's position to that of the Japanese brush painter working on a surface that permits no erasure — structure settled before the stroke. Nothing of the man's biography beyond this working disposition is claimed or carried."
     },
     {
       "slug": "davis-miles",
@@ -279,7 +436,7 @@
       "name": "Miles Davis",
       "domain": "modern jazz (trumpet, bandleading)",
       "kind": "musician",
-      "what_taken": "Born 26 May 1926 in Alton, Illinois; died 28 September 1991 in Santa Monica, California. What the direction-setter chair takes is the documented practice of setting direction by subtraction. Bill Evans's liner note to Kind of Blue (Columbia, 1959) records that Davis conceived the settings only hours before the recording dates and arrived with sketches indicating to the group what was to be played \u2014 the direction fixed, the execution left to the players. The same disposition at longer range produced the serial abandonment of settled idioms across Birth of the Cool (Capitol, sessions 1949-1950), Kind of Blue (1959) and Bitches Brew (Columbia, 1970), documented in Ian Carr, Miles Davis: The Definitive Biography (revised edition, 1998). Nothing of the man's biography beyond this working disposition is claimed or carried."
+      "what_taken": "Born 26 May 1926 in Alton, Illinois; died 28 September 1991 in Santa Monica, California. What the direction-setter chair takes is the documented practice of setting direction by subtraction. Bill Evans's liner note to Kind of Blue (Columbia, 1959) records that Davis conceived the settings only hours before the recording dates and arrived with sketches indicating to the group what was to be played — the direction fixed, the execution left to the players. The same disposition at longer range produced the serial abandonment of settled idioms across Birth of the Cool (Capitol, sessions 1949-1950), Kind of Blue (1959) and Bitches Brew (Columbia, 1970), documented in Ian Carr, Miles Davis: The Definitive Biography (revised edition, 1998). Nothing of the man's biography beyond this working disposition is claimed or carried."
     }
   ],
   "lineage_edges": [
@@ -334,7 +491,7 @@
           "Kind of Blue (Columbia CL 1355, 1959)",
           "Bitches Brew (Columbia GP 26, 1970)"
         ],
-        "primary_text": "Bill Evans, 'Improvisation in Jazz', liner note to Kind of Blue (Columbia CL 1355, 1959) \u2014 records that Davis arrived at the sessions with sketches conceived only hours before",
+        "primary_text": "Bill Evans, 'Improvisation in Jazz', liner note to Kind of Blue (Columbia CL 1355, 1959) — records that Davis arrived at the sessions with sketches conceived only hours before",
         "scholarship": "Ian Carr, Miles Davis: The Definitive Biography (revised edition, 1998); Miles Davis with Quincy Troupe, Miles: The Autobiography (New York: Simon & Schuster, 1989)",
         "attributed_disposition": "direction fixed by subtraction; execution left to the players",
         "note": "A public historical figure. The attribution names a documented working disposition; it is not an endorsement, a likeness, or a claim on the person."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eir-labs/coltrane",
-  "version": "0.7.5",
+  "version": "0.8.1",
   "description": "A methodology engine — a typed substrate for defining agents, composing multi-phase standards, dispatching gigs, and sealing every output to a content-addressed ledger. Ships as an MCP server.",
   "type": "module",
   "license": "Apache-2.0",
@@ -95,6 +95,7 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "@vitest/coverage-v8": "^3.2.6",
+    "fast-check": "^3.23.2",
     "tsx": "^4.19.0",
     "typescript": "^5.6.0",
     "vitest": "^3.0.0"

package/standards/defect-investigation-v1.json

@@ -0,0 +1,156 @@
+{
+  "slug": "defect-investigation-v1",
+  "domain": "engineering",
+  "agent_slugs": [
+    "defect-investigator"
+  ],
+  "phases": [
+    {
+      "name": "reproduce",
+      "intent": "Reproduce the defect deterministically; no investigation proceeds on a guess.",
+      "chairs": [
+        {
+          "role": "reproduce",
+          "agent_slug": "defect-investigator",
+          "depends_on": [],
+          "input_contract": [
+            "defect-report"
+          ],
+          "output_contract": [
+            "reproduction"
+          ],
+          "required_skills": []
+        }
+      ]
+    },
+    {
+      "name": "locate",
+      "intent": "Trace the exact failing call-chain in read code, file:symbol.",
+      "chairs": [
+        {
+          "role": "locate",
+          "agent_slug": "defect-investigator",
+          "depends_on": [
+            "reproduce"
+          ],
+          "input_contract": [
+            "reproduction"
+          ],
+          "output_contract": [
+            "defect-location"
+          ],
+          "required_skills": []
+        }
+      ]
+    },
+    {
+      "name": "root-cause",
+      "intent": "Why-chain to the violated invariant, not the surface symptom.",
+      "chairs": [
+        {
+          "role": "root-cause",
+          "agent_slug": "defect-investigator",
+          "depends_on": [
+            "locate"
+          ],
+          "input_contract": [
+            "defect-location"
+          ],
+          "output_contract": [
+            "root-cause"
+          ],
+          "required_skills": []
+        }
+      ]
+    },
+    {
+      "name": "generalize",
+      "intent": "Abstract the root cause to its defect CLASS and the single invariant that kills the whole class.",
+      "chairs": [
+        {
+          "role": "generalize",
+          "agent_slug": "defect-investigator",
+          "depends_on": [
+            "root-cause"
+          ],
+          "input_contract": [
+            "root-cause"
+          ],
+          "output_contract": [
+            "defect-class"
+          ],
+          "required_skills": []
+        }
+      ]
+    },
+    {
+      "name": "sweep",
+      "intent": "Sweep the WHOLE codebase for every instance of the class — found and checked-clean. Deferring a sibling is illegal.",
+      "chairs": [
+        {
+          "role": "sweep",
+          "agent_slug": "defect-investigator",
+          "depends_on": [
+            "generalize"
+          ],
+          "input_contract": [
+            "defect-class"
+          ],
+          "output_contract": [
+            "class-sweep"
+          ],
+          "required_skills": []
+        }
+      ]
+    },
+    {
+      "name": "fix-spec",
+      "intent": "Plan a fix for EVERY swept instance, each RED-first, plus a class-guard test.",
+      "chairs": [
+        {
+          "role": "fix-spec",
+          "agent_slug": "defect-investigator",
+          "depends_on": [
+            "sweep",
+            "root-cause"
+          ],
+          "input_contract": [
+            "class-sweep"
+          ],
+          "output_contract": [
+            "fix-spec"
+          ],
+          "required_skills": []
+        }
+      ]
+    },
+    {
+      "name": "verify",
+      "intent": "Confirm RED→GREEN per instance, the class-guard passes, and the original reproduction passes.",
+      "chairs": [
+        {
+          "role": "verify",
+          "agent_slug": "defect-investigator",
+          "depends_on": [
+            "fix-spec"
+          ],
+          "input_contract": [
+            "fix-spec"
+          ],
+          "output_contract": [
+            "fix-verification"
+          ],
+          "required_skills": []
+        }
+      ]
+    }
+  ],
+  "input_types": [
+    "defect-report"
+  ],
+  "output_types": [
+    "fix-spec",
+    "fix-verification"
+  ],
+  "description": "A defect is investigated to a CLASS-COMPLETE fix, never an instance patch. Reproduce → locate → root-cause → GENERALIZE to the defect class → SWEEP the whole codebase for every instance → fix-spec covering all of them (each RED-first, plus a class-guard test) → verify. The generalize+sweep phases are load-bearing: no defect closes until its class is swept, so 'the same class of bug we already fixed' becomes structurally impossible. A human governor seals the completed investigation."
+}

package/standards/software-change-pr-v1.json

@@ -0,0 +1,151 @@
+{
+  "slug": "software-change-pr-v1",
+  "domain": "software-change",
+  "agent_slugs": [
+    "john",
+    "miles",
+    "bill",
+    "code-implementer",
+    "change-verifier",
+    "pr-publisher"
+  ],
+  "phases": [
+    {
+      "name": "sense-context",
+      "chairs": [
+        {
+          "role": "read-context",
+          "agent_slug": "john",
+          "depends_on": [],
+          "input_contract": [
+            "change-request"
+          ],
+          "output_contract": [
+            "change-context"
+          ],
+          "required_skills": []
+        }
+      ],
+      "intent": "Read the material the change lands in, to the declared boundary and no further: entry points, the files the change plausibly touches, the checks that already cover the region, the conventions it must hold to — and the unknowns, which are part of the reading, not a failure of it. No decision is taken here."
+    },
+    {
+      "name": "frame-change",
+      "chairs": [
+        {
+          "role": "frame-change",
+          "agent_slug": "miles",
+          "depends_on": [
+            "read-context"
+          ],
+          "input_contract": [
+            "change-context"
+          ],
+          "output_contract": [
+            "change-decision"
+          ],
+          "required_skills": []
+        }
+      ],
+      "intent": "Fix the direction from the reading: scope, non-goals, stop condition, and the alternatives set aside with their reasons. Stated before any structure exists, so the structure is answerable to it. Settled for the run — later phases append observations, never revisions."
+    },
+    {
+      "name": "plan-change",
+      "chairs": [
+        {
+          "role": "plan-change",
+          "agent_slug": "bill",
+          "depends_on": [
+            "read-context",
+            "frame-change"
+          ],
+          "input_contract": [
+            "change-context",
+            "change-decision"
+          ],
+          "output_contract": [
+            "change-plan"
+          ],
+          "required_skills": [],
+          "preferred_skills": [
+            "structure-conformance"
+          ]
+        }
+      ],
+      "intent": "Settle the structure the change will be built through: ordered steps with explicit dependencies, the checks that land FIRST together with what each reports while the change is absent, the paths the plan commits to touching, and the tradeoff at every step where more than one structure would have served."
+    },
+    {
+      "name": "create-change",
+      "chairs": [
+        {
+          "role": "write-change",
+          "agent_slug": "code-implementer",
+          "depends_on": [
+            "plan-change"
+          ],
+          "input_contract": [
+            "change-plan"
+          ],
+          "output_contract": [
+            "change-set"
+          ],
+          "required_skills": []
+        }
+      ],
+      "intent": "Make the change the plan implies by WRITING it directly into the isolated working tree — every file it requires, created new or edited in place, however many that takes. The change lands as real files and the change-set is the real diff captured from the tree; this seat does not emit a patch for another to apply, and it does not verify its own work. Where the build departs from the plan, the departure is recorded with its reason."
+    },
+    {
+      "name": "verify-change",
+      "chairs": [
+        {
+          "role": "verify-change",
+          "agent_slug": "change-verifier",
+          "depends_on": [
+            "plan-change",
+            "write-change"
+          ],
+          "input_contract": [
+            "change-plan",
+            "change-set"
+          ],
+          "output_contract": [
+            "change-verdict"
+          ],
+          "required_skills": []
+        }
+      ],
+      "intent": "RUN the checks the plan fixed against the working tree the implementer has already written — build and tests, nothing to apply — then measure the change against its commitments criterion by criterion from the actual run: which acceptance criteria the run confirms green, where scope drifted, and which checks could not be executed. A criterion passes only when a real test asserted it and that test went green in this run; a check that could not run is unverified, never a pass; a red run is reported verbatim. The seat that clears the change is the seat that ran it."
+    },
+    {
+      "name": "publish-pr",
+      "chairs": [
+        {
+          "role": "publish-pr",
+          "agent_slug": "pr-publisher",
+          "depends_on": [
+            "write-change",
+            "verify-change"
+          ],
+          "input_contract": [
+            "change-set",
+            "change-verdict"
+          ],
+          "output_contract": [
+            "pull-request"
+          ],
+          "required_skills": []
+        }
+      ],
+      "intent": "Turn the verified change into an open pull request the pipeline cannot merge. The change is already on disk and confirmed by the verifier; commit exactly what is in the working tree to a fresh non-main branch, push it, and open exactly one PR whose body carries the rationale and the verifier's verdict. A failed verdict is not published — it is surfaced as a caveat and the seat stops. Landing the PR on main is a human governor's act on green CI, external to this run."
+    }
+  ],
+  "input_types": [
+    "change-request"
+  ],
+  "output_types": [
+    "change-set",
+    "change-verdict",
+    "pull-request"
+  ],
+  "max_examine_rounds": 3,
+  "description": "The full governed dev-loop: read the material, fix the direction, settle the structure, WRITE the change into an isolated working tree, RUN it to say whether what was built is what was decided, and open it as a pull request the seat that built it cannot merge. The implementer HOLDS the tree — it writes the change directly with the real file-editing interface (any number of files) and seals the change-set as the real captured diff, so the change that gets reviewed is the change that exists; there is no hand-authored patch to apply. The verify seat then EXECUTES against that tree — build and tests — so a change is cleared by a real run, never by argument; and a failing run is not the end: max_examine_rounds budgets the examine⇄amend loop, so a red verdict re-runs the writer (the failing verdict fed back) and re-verifies, iterating to green or stopping honestly at the bound. The publish seat commits exactly what is on disk. The seams hold: the seat that reads does not decide, the seat that decides does not build, the seat that builds does not judge its own work, and the seat that publishes does not merge. The cage is the isolated tree, not a missing tool. Landing on the protected main line is a human governor's act on green CI, not the pipeline's."
+}