@eir-labs/coltrane 0.8.0 → 0.9.0

package/standards/spec-drafting-v1.json

@@ -0,0 +1,125 @@
+{
+  "slug": "spec-drafting-v1",
+  "domain": "spec-drafting",
+  "agent_slugs": [
+    "grounder",
+    "contract-definer",
+    "red-spec-drafter",
+    "spec-reviewer",
+    "spec-publisher"
+  ],
+  "phases": [
+    {
+      "name": "ground",
+      "chairs": [
+        {
+          "role": "ground",
+          "agent_slug": "grounder",
+          "depends_on": [],
+          "input_contract": [],
+          "output_contract": [
+            "grounding-dossier"
+          ],
+          "required_skills": []
+        }
+      ],
+      "intent": "A lineage pass before anyone fixes a contract: our own codebase, tests, records and backlog designs (the callsites, what is declared-but-unenforced), plus internet prior art on how comparable systems build this subsystem AND, separately, how to verify a contract formally (property-based, deterministic algebra, model-based). Everything cited; nothing recalled. The synthesis is what makes the spec buildable rather than invented."
+    },
+    {
+      "name": "define-contract",
+      "chairs": [
+        {
+          "role": "define-contract",
+          "agent_slug": "contract-definer",
+          "depends_on": [
+            "ground"
+          ],
+          "input_contract": [
+            "grounding-dossier"
+          ],
+          "output_contract": [
+            "subsystem-contract"
+          ],
+          "required_skills": []
+        }
+      ],
+      "intent": "Fix what the subsystem MUST be: the complete set of obligations, the machine-statable invariants that must hold (each naming how it is checked), and the failure modes that must fail closed. Exhaustive, not sampled — an omitted invariant is a hole the tests cannot cover, and a hole is how a system does B while claiming A through Z."
+    },
+    {
+      "name": "draft-red-spec",
+      "chairs": [
+        {
+          "role": "draft-red-spec",
+          "agent_slug": "red-spec-drafter",
+          "depends_on": [
+            "ground",
+            "define-contract"
+          ],
+          "input_contract": [
+            "grounding-dossier",
+            "subsystem-contract"
+          ],
+          "output_contract": [
+            "red-spec"
+          ],
+          "required_skills": []
+        }
+      ],
+      "intent": "Write the spec AS red tests, directly into the working tree: for every contract invariant, a real running assertion against the real callsite, failing today because the enforcement is absent, using the verification method the grounding chose (property-based/axiomatic where universal). The files land on disk and the red-spec is the real captured diff; the coverage_map binds every invariant to its test; uncovered must be empty. Each test must be genuinely RED — it must FAIL on the missing enforcement, never pass regardless (a subset law that already holds on the un-wired path is a tautology, not a red test; assert the strict effect so it is green only once the enforcement exists). No implementation ships — only the falsifiable contract."
+    },
+    {
+      "name": "review",
+      "chairs": [
+        {
+          "role": "review",
+          "agent_slug": "spec-reviewer",
+          "depends_on": [
+            "define-contract",
+            "draft-red-spec"
+          ],
+          "input_contract": [
+            "subsystem-contract",
+            "red-spec"
+          ],
+          "output_contract": [
+            "change-verdict"
+          ],
+          "required_skills": []
+        }
+      ],
+      "intent": "The gate that stops a spec from lying: read the tests, not the coverage_map's word. Refuse on a single uncovered invariant, one tautological test that passes regardless of the implementation, or one pending placeholder. A passing review means every claim in the contract has a failing test that proves it. On a failing review the red-spec-drafter amends and is re-reviewed — the spec is not published until it genuinely holds."
+    },
+    {
+      "name": "publish-red-spec",
+      "chairs": [
+        {
+          "role": "publish-red-spec",
+          "agent_slug": "spec-publisher",
+          "depends_on": [
+            "draft-red-spec",
+            "review"
+          ],
+          "input_contract": [
+            "red-spec",
+            "change-verdict"
+          ],
+          "output_contract": [
+            "pull-request"
+          ],
+          "required_skills": []
+        }
+      ],
+      "intent": "Open the RED spec as one pull request for a human to approve. The red-spec-drafter has already written the failing tests into the working tree and the reviewer has judged the spec good; commit exactly what is on disk to a fresh non-main branch, push it, and open exactly one PR whose body states plainly that CI is red by design — the failing tests ARE the contract, and the implementation pipeline turns this same branch green. The gate is the spec-review verdict (the spec's quality), never the test run. A failed review is not published — it is surfaced as a caveat and the seat stops. The human approves the contract on GitHub before anyone builds against it."
+    }
+  ],
+  "input_types": [],
+  "output_types": [
+    "grounding-dossier",
+    "subsystem-contract",
+    "red-spec",
+    "change-verdict",
+    "pull-request"
+  ],
+  "max_examine_rounds": 3,
+  "description": "Draft a buildable spec for a subsystem/contract AND publish it as a RED pull request for human approval. A buildable spec is not prose — it is comprehensive RED tests: real running assertions, one or more per contract invariant, failing because the enforcement does not exist yet, with a coverage map that leaves nothing uncovered. Five seats, seam-separated so a spec cannot certify itself: the grounder runs a lineage pass; the contract-definer fixes the exhaustive contract; the red-spec-drafter WRITES a real red test for every invariant directly into the working tree; the reviewer refuses on a single uncovered invariant, one tautological test, or one pending placeholder; and the spec-publisher opens exactly one PR whose CI is red by design. max_examine_rounds wires the review→redraft loop: a failing review re-runs the red-spec-drafter with the review fed back — so a tautological or not-actually-red test is amended and re-reviewed, iterating until the spec genuinely holds or the rounds are spent, before anything is published. This is the deliberate human-approval handoff: a person approves the contract on GitHub, then the implementation pipeline (a separate standard) takes this same branch and turns it green."
+}