@eir-labs/coltrane 0.8.0 → 0.8.1

package/domain_types/defect-report.json

@@ -0,0 +1,28 @@
+{
+  "slug": "defect-report",
+  "version": 1,
+  "extends": "Signal",
+  "domain": "engineering",
+  "status": "active",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "symptom": {
+        "type": "string"
+      },
+      "trigger": {
+        "type": "string"
+      },
+      "error_text": {
+        "type": "string"
+      },
+      "observed_at": {
+        "type": "string"
+      }
+    }
+  },
+  "required_fields": [
+    "symptom",
+    "trigger"
+  ]
+}

package/domain_types/fix-spec.json

@@ -0,0 +1,28 @@
+{
+  "slug": "fix-spec",
+  "version": 1,
+  "extends": "Plan",
+  "domain": "engineering",
+  "status": "active",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "per_instance_fixes": {
+        "type": "array",
+        "items": {
+          "type": "object"
+        }
+      },
+      "class_guard_test": {
+        "type": "string"
+      },
+      "covers_all_swept_instances": {
+        "type": "boolean"
+      }
+    }
+  },
+  "required_fields": [
+    "per_instance_fixes",
+    "class_guard_test"
+  ]
+}

package/domain_types/fix-verification.json

@@ -0,0 +1,28 @@
+{
+  "slug": "fix-verification",
+  "version": 1,
+  "extends": "Verdict",
+  "domain": "engineering",
+  "status": "active",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "per_instance_results": {
+        "type": "array",
+        "items": {
+          "type": "object"
+        }
+      },
+      "class_guard_passes": {
+        "type": "boolean"
+      },
+      "repro_now_passes": {
+        "type": "boolean"
+      }
+    }
+  },
+  "required_fields": [
+    "per_instance_results",
+    "class_guard_passes"
+  ]
+}

package/domain_types/grounding-dossier.json

@@ -0,0 +1,95 @@
+{
+  "slug": "grounding-dossier",
+  "version": 1,
+  "extends": "Interpretation",
+  "domain": "spec-drafting",
+  "status": "active",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "internal_sources": {
+        "type": "array",
+        "description": "Our own lineage read: each {source, contribution}.",
+        "items": {
+          "type": "object",
+          "properties": {
+            "source": {
+              "type": "string"
+            },
+            "contribution": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "source",
+            "contribution"
+          ]
+        }
+      },
+      "external_sources": {
+        "type": "array",
+        "description": "Internet prior art on building the subsystem: each {citation, url, mechanism, applicability}.",
+        "items": {
+          "type": "object",
+          "properties": {
+            "citation": {
+              "type": "string"
+            },
+            "url": {
+              "type": "string"
+            },
+            "mechanism": {
+              "type": "string"
+            },
+            "applicability": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "citation",
+            "mechanism",
+            "applicability"
+          ]
+        }
+      },
+      "method_findings": {
+        "type": "array",
+        "description": "How to formally/axiomatically verify a contract (property-based testing, deterministic algebra, model-based, contract testing): each {approach, source, how_it_applies}.",
+        "items": {
+          "type": "object",
+          "properties": {
+            "approach": {
+              "type": "string"
+            },
+            "source": {
+              "type": "string"
+            },
+            "how_it_applies": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "approach",
+            "how_it_applies"
+          ]
+        }
+      },
+      "synthesis": {
+        "type": "string",
+        "description": "The high-resolution argument tying domain + method grounding into an implementation approach."
+      },
+      "open_questions": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      }
+    }
+  },
+  "required_fields": [
+    "internal_sources",
+    "external_sources",
+    "method_findings",
+    "synthesis"
+  ]
+}

package/domain_types/pull-request.json

@@ -0,0 +1,43 @@
+{
+  "slug": "pull-request",
+  "version": 1,
+  "extends": "Artifact",
+  "domain": "software-change",
+  "status": "active",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "base": {
+        "type": "string",
+        "description": "The target branch the PR merges into (the protected main line). The seat never merges it — a human governor does, on green CI."
+      },
+      "branch": {
+        "type": "string",
+        "description": "The non-main feature branch the change was applied and pushed to."
+      },
+      "commit_sha": {
+        "type": "string",
+        "description": "The HEAD commit pushed to the branch, taken from the actual push output in this run — never fabricated."
+      },
+      "pr_url": {
+        "type": "string",
+        "description": "The opened pull request URL, taken from the gh/API response in this run."
+      },
+      "pr_number": {
+        "type": "number",
+        "description": "The opened pull request number, from the same response."
+      },
+      "title": {
+        "type": "string",
+        "description": "The PR title, stating what changed."
+      }
+    }
+  },
+  "required_fields": [
+    "validation_criteria",
+    "input_refs",
+    "branch",
+    "commit_sha",
+    "pr_url"
+  ]
+}

package/domain_types/red-spec.json

@@ -0,0 +1,76 @@
+{
+  "slug": "red-spec",
+  "version": 1,
+  "extends": "Artifact",
+  "domain": "spec-drafting",
+  "status": "active",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "spec_doc": {
+        "type": "string",
+        "description": "The written spec (path added by the diffs)."
+      },
+      "diffs": {
+        "type": "array",
+        "description": "Per-path unified diffs: the RED test files (real assertions, failing because unimplemented) and the spec doc.",
+        "items": {
+          "type": "object",
+          "properties": {
+            "path": {
+              "type": "string"
+            },
+            "patch": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "path",
+            "patch"
+          ]
+        }
+      },
+      "coverage_map": {
+        "type": "array",
+        "description": "EVERY subsystem-contract invariant mapped to the red test that verifies it: each {invariant_id, test_name, test_file}.",
+        "items": {
+          "type": "object",
+          "properties": {
+            "invariant_id": {
+              "type": "string"
+            },
+            "test_name": {
+              "type": "string"
+            },
+            "test_file": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "invariant_id",
+            "test_name",
+            "test_file"
+          ]
+        }
+      },
+      "testing_method": {
+        "type": "string",
+        "description": "The axiomatic/property-based approach + engine used (e.g. fast-check property tests), grounded in method_findings."
+      },
+      "uncovered": {
+        "type": "array",
+        "description": "Contract invariants with no red test — MUST be empty.",
+        "items": {
+          "type": "string"
+        }
+      }
+    }
+  },
+  "required_fields": [
+    "validation_criteria",
+    "input_refs",
+    "diffs",
+    "coverage_map",
+    "testing_method"
+  ]
+}

package/domain_types/reproduction.json

@@ -0,0 +1,28 @@
+{
+  "slug": "reproduction",
+  "version": 1,
+  "extends": "Signal",
+  "domain": "engineering",
+  "status": "active",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "reproduced": {
+        "type": "boolean"
+      },
+      "minimal_case": {
+        "type": "string"
+      },
+      "steps": {
+        "type": "string"
+      },
+      "error_text": {
+        "type": "string"
+      }
+    }
+  },
+  "required_fields": [
+    "reproduced",
+    "minimal_case"
+  ]
+}

package/domain_types/root-cause.json

@@ -0,0 +1,28 @@
+{
+  "slug": "root-cause",
+  "version": 1,
+  "extends": "Judgment",
+  "domain": "engineering",
+  "status": "active",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "violated_invariant": {
+        "type": "string"
+      },
+      "why_chain": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      },
+      "is_root_not_symptom": {
+        "type": "boolean"
+      }
+    }
+  },
+  "required_fields": [
+    "violated_invariant",
+    "why_chain"
+  ]
+}

package/domain_types/subsystem-contract.json

@@ -0,0 +1,106 @@
+{
+  "slug": "subsystem-contract",
+  "version": 1,
+  "extends": "Judgment",
+  "domain": "spec-drafting",
+  "status": "active",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "obligations": {
+        "type": "array",
+        "description": "What the subsystem MUST do: each {id, statement}.",
+        "items": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "statement": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "id",
+            "statement"
+          ]
+        }
+      },
+      "invariants": {
+        "type": "array",
+        "description": "Machine-statable properties that must hold: each {id, statement, checkable} — checkable names how it can be verified (property/example/algebraic).",
+        "items": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "statement": {
+              "type": "string"
+            },
+            "checkable": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "id",
+            "statement",
+            "checkable"
+          ]
+        }
+      },
+      "failure_modes": {
+        "type": "array",
+        "description": "What must fail closed: each {id, condition, refusal}.",
+        "items": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "condition": {
+              "type": "string"
+            },
+            "refusal": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "id",
+            "condition",
+            "refusal"
+          ]
+        }
+      },
+      "inputs": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      },
+      "outputs": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      },
+      "scope_in": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      },
+      "scope_out": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      }
+    }
+  },
+  "required_fields": [
+    "obligations",
+    "invariants",
+    "failure_modes"
+  ]
+}

package/institutions/coltrane.json

@@ -0,0 +1,166 @@
+{
+  "institution": {
+    "slug": "coltrane",
+    "name": "Coltrane",
+    "kind": "institution",
+    "laws": [
+      {
+        "attributes": "any seated agent that is not a human governor",
+        "deontic": "forbidden",
+        "aim": "merge a change into the institution's protected main line",
+        "conditions": "at all times",
+        "or_else": "the merge is refused; a change lands only after its continuous-integration check is green on an open pull request and a human governor merges it",
+        "check": {
+          "predicate": "(=> (and (is-agent actor) (not (human-governor actor)) (= action \"merge-main\")) deny)",
+          "inputs": {
+            "actor": "principal",
+            "action": "action-kind"
+          }
+        },
+        "content_hash": "sha256:b6fc83599d08906b5a17c4df4fd62fc6613a8c6769de696e07f1822589c0edf4"
+      },
+      {
+        "attributes": "any seated agent proposing a change",
+        "deontic": "permitted",
+        "aim": "open a pull request proposing a change to the institution's main line",
+        "conditions": "the change is committed on a non-main branch and its local verify passed",
+        "or_else": "not applicable — a permission, not an obligation",
+        "check": {
+          "predicate": "(=> (and (is-agent actor) (= action \"open-pr\") (not (= source \"main\"))) allow)",
+          "inputs": {
+            "actor": "principal",
+            "action": "action-kind",
+            "source": "branch-name"
+          }
+        },
+        "content_hash": "sha256:16a421955526178557f84c668a5f7f78df76bb6b63ddc2941b5640bae6ee1131"
+      },
+      {
+        "attributes": "a pull request proposed for merge",
+        "deontic": "obliged",
+        "aim": "present a green continuous-integration result before it may be merged",
+        "conditions": "before any merge to the protected main line",
+        "or_else": "the merge is blocked until continuous integration is green",
+        "check": {
+          "predicate": "(=> (= action \"merge-main\") (require (= ci-status \"green\")))",
+          "inputs": {
+            "action": "action-kind",
+            "ci-status": "ci-status"
+          }
+        },
+        "content_hash": "sha256:c4c2b5fe59fdad6b299a43b60b4d61dfff9c848fe578d72ebf3d932fd5d15b13"
+      },
+      {
+        "attributes": "a change-set branch keyed by its originating gig, off the protected main line",
+        "deontic": "permitted",
+        "aim": "stand deliberately red between the spec merge and the implementation merge on a change-set branch, off the protected line",
+        "conditions": "while the target branch is a change-set branch and is not the protected main line",
+        "or_else": "not applicable — a permission, not an obligation",
+        "check": {
+          "predicate": "(=> (not (= target_branch \"main\")) allow)",
+          "inputs": {
+            "target_branch": "branch-name"
+          }
+        },
+        "content_hash": "sha256:f465a9f3e76a5288dd993ef1b8228993feea04a47af8f3c99462cc4edcb238a5"
+      }
+    ],
+    "sovereign": true,
+    "lineage": []
+  },
+  "organizations": [
+    {
+      "slug": "eir-labs",
+      "name": "Eir Labs",
+      "charter": "The organization that develops Coltrane through Coltrane's own governed pipeline. Its charter is to carry every change to the engine and its genome through a reviewed pull request a human governor merges on green continuous integration — never a direct write to the protected main line. It ships no capability it has not been granted and lands no change its checks have not passed.",
+      "parent_org": null
+    }
+  ],
+  "agent_records": [
+    {
+      "slug": "coltrane-proposer",
+      "name": "Coltrane Proposer",
+      "kind": "steve",
+      "is_institution": false,
+      "skill_slugs": [],
+      "status": "active",
+      "named_from_forebear": null,
+      "auth_user_id": null
+    }
+  ],
+  "org_members": [
+    {
+      "org_slug": "eir-labs",
+      "agent_slug": "coltrane-proposer"
+    }
+  ],
+  "chairs": [
+    {
+      "id": "coltrane.chair.change-author",
+      "institution_slug": "coltrane",
+      "role": "change-author",
+      "function": "CREATE",
+      "mission": "Propose changes to Coltrane as pull requests a human governor decides on. This chair reads, plans, builds and verifies a change, then opens it as a proposal on a non-main branch. It never merges its own work; landing the change on the protected main line is the governor's act, on green continuous integration.",
+      "required_skills": [],
+      "caps": [
+        {
+          "grant": "dispatch",
+          "standards": [
+            "software-change-v1"
+          ],
+          "expires": null
+        }
+      ],
+      "obligations": [
+        {
+          "attributes": "the change-author",
+          "aim": "open every change as a pull request on a non-main branch",
+          "deontic": "obliged",
+          "tier": "declared"
+        },
+        {
+          "attributes": "the change-author",
+          "aim": "merge its own pull request, or any change, into the protected main line",
+          "deontic": "forbidden",
+          "tier": "declared"
+        }
+      ]
+    },
+    {
+      "id": "coltrane.chair.human-governor",
+      "institution_slug": "coltrane",
+      "role": "human-governor",
+      "human": true,
+      "function": "JUDGE",
+      "mission": "Hold the merge authority for Coltrane's protected main line. This chair is held by a person, never a model agent: the governor reviews an open pull request and its continuous-integration result and merges it under their own name, or refuses it. Nothing lands on main without this office's yes. The office ships unassigned — the adopting organization seats a person here as its first governance act.",
+      "required_skills": [],
+      "caps": [],
+      "obligations": [
+        {
+          "attributes": "the human-governor",
+          "aim": "review the open pull request and confirm its continuous-integration result is green before merging",
+          "deontic": "obliged",
+          "tier": "declared"
+        },
+        {
+          "attributes": "the human-governor",
+          "aim": "delegate the merge decision to a model agent, or let the office be held by one",
+          "deontic": "forbidden",
+          "tier": "declared"
+        }
+      ]
+    }
+  ],
+  "assignments": [
+    {
+      "id": "coltrane.seat.change-author",
+      "chair_id": "coltrane.chair.change-author",
+      "agent_slug": "coltrane-proposer",
+      "org_slug": "eir-labs",
+      "contract_caps": [],
+      "witnessed_by": null
+    }
+  ],
+  "forebears": [],
+  "lineage_edges": []
+}