@intentius/chant 0.101.0 → 0.104.0

package/src/workspace/conformance/__writer_fixture__/answers/answer.schema.json

@@ -0,0 +1,135 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "urn:intentius:chant:point-answer:1",
+  "title": "Decision point answer front matter",
+  "description": "The front matter of one answer to a decision point (ws-058, #2739), as `chant workspace points ask` and `points answer` write it into the records directory of a record kind with an `answers` block. One record per point, declaration and inputs: its id is the point's name and the first 12 hex digits of the inputs hash, so the same question is answered once. A table's answer is `answered`; a model's answer at or above its threshold is `proposed` until a person confirms it; a question no decider before the quorum answered is `escalated`, open for people. An answer never changes in place: `points retract` escalates the question to people again and moves the answer into `retractions` (#3351, ws-084). An ad-hoc point's answer keeps the question and candidates its ask gave as `asked`, and they are part of the inputs hash (#3403). A workspace copies this file next to its answer kind, as reference-workspace/answers/ does. Values stay within what YAML and JSON share. Fields other than these must start with x-.",
+  "type": "object",
+  "additionalProperties": false,
+  "patternProperties": { "^x-": {} },
+  "required": ["id", "title", "point", "point_version", "question_type", "candidates", "inputs", "inputs_hash", "state", "decider", "asked_on"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*-[0-9a-f]{12}$", "description": "The point's name, a hyphen, and the first 12 hex digits of inputs_hash." },
+    "title": { "type": "string", "minLength": 1 },
+    "point": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$", "description": "The point in the points file this answers." },
+    "point_version": { "$ref": "#/definitions/sha256", "description": "sha256 of the point's declaration when it was asked. Editing the question or any decider changes it." },
+    "question_type": { "enum": ["noul", "choice", "score"] },
+    "candidates": { "type": "array", "minItems": 2, "items": { "type": ["string", "boolean"] }, "description": "The answers the question allowed: true and false, a choice's options, or a score's levels." },
+    "asked": {
+      "type": "object",
+      "description": "An ad-hoc point's question as its ask gave it (`points ask --candidates`, #3403): its text, and its criteria in the point's question type's shape, from which candidates come. People's answer is one of them.",
+      "required": ["question", "criteria"],
+      "properties": {
+        "question": { "type": "string", "minLength": 1 },
+        "criteria": {
+          "oneOf": [
+            { "type": "object", "minProperties": 2, "maxProperties": 255, "additionalProperties": { "type": "string" } },
+            { "type": "array", "minItems": 2, "maxItems": 10, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "inputs": { "type": "object", "description": "The state the deciders saw, input name to value." },
+    "inputs_hash": { "$ref": "#/definitions/sha256", "description": "sha256 of the point, its version and its inputs. The same hash is answered once." },
+    "constrains": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "What the question is about, such as a work item's id." },
+    "state": { "enum": ["escalated", "proposed", "answered"] },
+    "answer": { "type": ["string", "boolean"] },
+    "decider": {
+      "type": "object",
+      "required": ["kind"],
+      "properties": {
+        "kind": { "enum": ["table", "model", "quorum"] },
+        "row": { "type": "integer", "minimum": 0, "description": "table: the row that matched." },
+        "backend": { "type": "string", "minLength": 1 },
+        "model": { "type": "string", "minLength": 1, "description": "model: the model id that answered, as the backend reported it." },
+        "count": { "type": "integer", "minimum": 1 },
+        "roles": { "type": "array", "items": { "type": "string" } },
+        "by": { "type": "array", "items": { "type": "string" }, "description": "quorum: who answered." }
+      },
+      "additionalProperties": false
+    },
+    "probabilities": { "$ref": "#/definitions/probabilities" },
+    "confidence": { "$ref": "#/definitions/unit" },
+    "threshold": { "$ref": "#/definitions/unit" },
+    "reason": { "type": "string", "minLength": 1, "description": "model: the model's own explanation of its answer, when the backend gave one (#3345). Kept when a person confirms the proposal; moved into the escalations as model_reason when people answer otherwise." },
+    "escalations": {
+      "type": "array",
+      "description": "The deciders asked before the one that answered, or before the quorum, and why each did not answer.",
+      "items": { "$ref": "#/definitions/escalation" }
+    },
+    "answered_by": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 }, "description": "The people who answered or confirmed it." },
+    "note": { "type": "string", "minLength": 1, "description": "What the people who answered wrote with their answer (`points answer --note`, #3351). Moved into the retraction when the answer is retracted." },
+    "relayed_by": { "type": "string", "minLength": 1, "description": "Who carried the answer to chant for the people in answered_by (`points answer --relayed-by`, #3402), such as a follower relaying a person's answer through hud. It does not count toward the quorum. Moved into the retraction as answer_relayed_by when the answer is retracted." },
+    "retractions": {
+      "type": "array",
+      "description": "Answers people took back, oldest first (`points retract`, #3351): each answer as it was, and who retracted it, when and why. A retracted question is escalated to people again.",
+      "items": { "$ref": "#/definitions/retraction" }
+    },
+    "asked_on": { "$ref": "#/definitions/date" },
+    "answered_on": { "$ref": "#/definitions/date" },
+    "source": {
+      "type": "object",
+      "description": "Where the answer came from (#2708): via, client and model, the model id that answered when a model decider did."
+    }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "state": { "const": "proposed" } }, "required": ["state"] },
+      "then": { "required": ["answer"], "properties": { "decider": { "properties": { "kind": { "const": "model" } } } } }
+    },
+    {
+      "if": { "properties": { "state": { "const": "answered" } }, "required": ["state"] },
+      "then": { "required": ["answer", "answered_on"] }
+    },
+    {
+      "if": { "properties": { "state": { "const": "escalated" } }, "required": ["state"] },
+      "then": { "not": { "required": ["answer"] }, "properties": { "decider": { "properties": { "kind": { "const": "quorum" } } } } }
+    },
+    {
+      "if": { "properties": { "decider": { "properties": { "kind": { "const": "model" } }, "required": ["kind"] } }, "required": ["decider"] },
+      "then": { "required": ["probabilities", "confidence", "threshold"], "properties": { "decider": { "required": ["backend", "model"] } } }
+    },
+    {
+      "if": { "properties": { "state": { "const": "answered" }, "decider": { "properties": { "kind": { "const": "quorum" } }, "required": ["kind"] } }, "required": ["state", "decider"] },
+      "then": { "required": ["answered_by"], "properties": { "decider": { "required": ["by"] } } }
+    }
+  ],
+  "definitions": {
+    "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+    "unit": { "type": "number", "minimum": 0, "maximum": 1 },
+    "date": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" },
+    "probabilities": { "type": "object", "additionalProperties": { "$ref": "#/definitions/unit" } },
+    "retraction": {
+      "type": "object",
+      "required": ["answer", "decider", "by", "on"],
+      "properties": {
+        "answer": { "type": ["string", "boolean"], "description": "The answer retracted." },
+        "decider": { "type": "object", "required": ["kind"], "properties": { "kind": { "enum": ["table", "model", "quorum"] } }, "description": "Who gave it: the record's decider as it was." },
+        "answered_by": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "answered_on": { "$ref": "#/definitions/date" },
+        "answer_note": { "type": "string", "minLength": 1, "description": "The note the answer carried." },
+        "answer_relayed_by": { "type": "string", "minLength": 1, "description": "Who relayed the answer (#3402)." },
+        "by": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 }, "description": "Who retracted it." },
+        "on": { "$ref": "#/definitions/date" },
+        "note": { "type": "string", "minLength": 1, "description": "Why it was retracted (`points retract --note`)." }
+      },
+      "additionalProperties": false
+    },
+    "escalation": {
+      "type": "object",
+      "required": ["kind", "reason"],
+      "properties": {
+        "kind": { "enum": ["table", "model"] },
+        "reason": { "type": "string", "minLength": 1 },
+        "backend": { "type": "string" },
+        "model": { "type": "string" },
+        "answer": { "type": ["string", "boolean", "null"] },
+        "probabilities": { "$ref": "#/definitions/probabilities" },
+        "confidence": { "$ref": "#/definitions/unit" },
+        "threshold": { "$ref": "#/definitions/unit" },
+        "model_reason": { "type": "string", "minLength": 1, "description": "model: the model's own explanation of the answer it gave, when the backend gave one (#3345). reason is why the decider did not answer." }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/src/workspace/conformance/__writer_fixture__/contracts/contract.kind.mjs

@@ -0,0 +1,37 @@
+// The contract record kind (#3148, ws-082), data only: no imports, no code.
+//
+// chant workspace records --kind design/contracts/contract.kind.mjs --current --json
+//
+// A contract is an acceptance criterion made formal: what a person can do,
+// the criteria a check proves, and the check itself, a file pinned by hash.
+// It is drafted, approved once its reviewers agree, and retired when nothing
+// should be built against it any more. Studio's factory builds work items
+// against approved contracts; a work kind links an item to its contract with
+// work.contract (#3147). Each check run's result is an evidence record
+// (../evidence/evidence.kind.mjs) that names the contract and its criteria.
+export const recordKind = {
+  name: "contract",
+  location: { dir: ".", match: "^C-[0-9]{3,}-.+\\.md$" },
+  format: "markdown-front-matter",
+  schema: { id: "urn:intentius:chant:contract:1", path: "contract.schema.json" },
+  idField: "id",
+  stateField: "state",
+  states: ["draft", "approved", "retired"],
+  // An approved contract changes only in its state, its check pins and its
+  // reviews: anything else is a new contract that supersedes it. A retired
+  // contract is final and sealed.
+  closedStates: ["retired"],
+  approval: { draft: 0, approved: 1, retired: 1 },
+  seal: { field: "closed_digest" },
+  // A bare id or a list of ids, as studio's contracts write it. A link takes
+  // effect from an approved or retired contract.
+  supersedes: { field: "supersedes" },
+  // The contract's checks, each a workspace file pinned by the hash of its
+  // bytes (#2549): records reports a check edited after it was pinned.
+  pins: { field: "checks" },
+  // Verdicts on the contract, given in a review session (whose subjects
+  // include this kind) or with records review, and who approved it.
+  reviews: { field: "reviews", decider: "approved_by" },
+  // records new --by names a draft's proposer here (#2756).
+  proposedBy: { field: "proposed_by" },
+};

package/src/workspace/conformance/__writer_fixture__/contracts/contract.schema.json

@@ -0,0 +1,213 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "urn:intentius:chant:contract:1",
+  "title": "Contract file front matter",
+  "description": "The front matter of one contract file in design/contracts/ (#3148, ws-082): an acceptance criterion made formal, with the criteria a check proves and the check pinned by hash. The Markdown body after the front matter is the story and any detail; the criteria are listed here, so a reader never parses the body. Values stay within what YAML and JSON share.",
+  "type": "object",
+  "additionalProperties": false,
+  "patternProperties": {
+    "^x-": {}
+  },
+  "required": ["schema", "id", "title", "state", "criteria", "checks", "reviews", "approved_by"],
+  "properties": {
+    "schema": {
+      "description": "Format version of this file. Bumped only by a change to this schema.",
+      "const": 1
+    },
+    "id": {
+      "description": "Stable id: C, a dash and three or more digits, as studio numbers its contracts. Never reused, never renumbered.",
+      "$ref": "#/definitions/contractId"
+    },
+    "title": {
+      "description": "What a person can do once the contract holds, in a few words.",
+      "type": "string",
+      "minLength": 1
+    },
+    "state": {
+      "description": "draft: being written. approved: ready to build; only its state, checks and reviews change from here, and a changed contract is a new one that supersedes it. retired: nothing is built against it any more. Sealed once retired.",
+      "enum": ["draft", "approved", "retired"]
+    },
+    "tier": {
+      "description": "The builder tier the contract is built at, when it is fixed rather than asked of the slice-tier decision point: one of the tiers the work kind declares (#3147). Null or absent to leave it to the point.",
+      "type": ["string", "null"],
+      "pattern": "^[a-z][a-z0-9-]{0,31}$"
+    },
+    "criteria": {
+      "description": "The acceptance criteria, each with an id the check's tests are named after (a test named \"a1: ...\" checks a1) and the text it states. A work item that builds the contract lists criteria with the same ids in its acceptance, and an evidence record of a check run reports each by id. An approved contract states at least one.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "text"],
+        "properties": {
+          "id": { "$ref": "#/definitions/criterionId" },
+          "text": { "type": "string", "pattern": "\\S" }
+        }
+      }
+    },
+    "checks": {
+      "description": "The contract's checks: test files a runner runs against the app (studio runs them with node --test and APP_URL), each pinned by the hash of its bytes, so chant workspace records reports a check edited after it was pinned. Usually one. Empty while none is written; records then warns record-no-evidence, and a factory leaves the contract unchecked.",
+      "type": "array",
+      "items": { "$ref": "#/definitions/checkPin" }
+    },
+    "references": {
+      "description": "Design assets a criterion is checked against besides its tests, such as a section of a driver's design document (design/drivers/D-001/design.html#notes-page). Optional.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["criterion", "asset"],
+        "properties": {
+          "criterion": { "$ref": "#/definitions/criterionId" },
+          "asset": {
+            "description": "A workspace path, from the workspace root, with an optional #fragment naming a section in it.",
+            "type": "string",
+            "pattern": "^(?!/)(?!(?:[^/#]*/)*\\.{1,2}(?:[/#]|$))(?!.*//)[^\\\\\\u0000-\\u001f#]*[^/\\\\\\u0000-\\u001f#](#[A-Za-z][A-Za-z0-9:._-]*)?$"
+          }
+        }
+      }
+    },
+    "supersedes": {
+      "description": "The contract or contracts this one replaces, by id: a bare id, as studio's contracts write it, or a list. Takes effect once this contract is approved or retired. Optional.",
+      "oneOf": [
+        { "$ref": "#/definitions/contractId" },
+        { "type": "array", "items": { "$ref": "#/definitions/contractId" }, "uniqueItems": true }
+      ]
+    },
+    "proposed_by": {
+      "description": "Who drafted the contract: the name chant workspace records new --by wrote (#2756). Null or absent when nobody named one.",
+      "type": ["string", "null"]
+    },
+    "approved_by": {
+      "description": "Who approved the contract: a forge login. A contract approved in a review session also carries the verdicts that approved it in reviews. Null while it is a draft.",
+      "type": ["string", "null"]
+    },
+    "approved_on": {
+      "description": "When it was approved, as YYYY-MM-DD. Quoted, so YAML reads it as a string. Null or absent while it is a draft.",
+      "type": ["string", "null"],
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
+    },
+    "reviews": {
+      "description": "Each reviewer's verdict on the contract, in the decision kind's shape: reviewer, verdict, on, and the digest of the text judged. A verdict given in a review session names it in session (chant workspace records review --session). Empty until a review happens.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["reviewer", "verdict", "on"],
+        "properties": {
+          "reviewer": { "type": "string", "minLength": 1 },
+          "verdict": { "enum": ["agree", "dissent", "abstain"] },
+          "note": { "type": ["string", "null"] },
+          "on": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" },
+          "digest": {
+            "description": "The digest of the contract text the verdict judged: the lowercase hex SHA-256 of the file with LF line endings and without its reviews block (#2672).",
+            "type": "string",
+            "pattern": "^[0-9a-f]{64}$"
+          },
+          "session": {
+            "description": "The id of the review session the verdict was given in.",
+            "type": "string",
+            "minLength": 1
+          },
+          "seal": {
+            "description": "The reviewer's ssh signature over the verdict (#2687), as chant workspace records review --sign writes it.",
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["signer", "key", "signature"],
+            "properties": {
+              "signer": { "type": "string", "minLength": 1 },
+              "key": { "type": "string", "pattern": "^SHA256:[A-Za-z0-9+/]+=*$" },
+              "signature": { "type": "string", "pattern": "^-----BEGIN SSH SIGNATURE-----\\n" }
+            }
+          }
+        },
+        "dependencies": { "seal": ["digest"] },
+        "if": {
+          "required": ["verdict"],
+          "properties": { "verdict": { "const": "dissent" } }
+        },
+        "then": {
+          "description": "A dissent needs a reason: the dissent by {reviewer} has no note.",
+          "required": ["note"],
+          "properties": { "note": { "type": "string", "pattern": "\\S" } }
+        }
+      }
+    },
+    "seal": {
+      "description": "The author's ssh signature over the contract (#2688), as chant workspace records new --sign and amend --sign write it. Optional.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["signer", "key", "signature"],
+      "properties": {
+        "signer": { "type": "string", "minLength": 1 },
+        "key": { "type": "string", "pattern": "^SHA256:[A-Za-z0-9+/]+=*$" },
+        "signature": { "type": "string", "pattern": "^-----BEGIN SSH SIGNATURE-----\\n" }
+      }
+    },
+    "closed_digest": {
+      "description": "The contract's whole-file seal (#2546, ws-063), written when it is retired: sha256: and the lowercase hex SHA-256 of the JCS form of {body, core}, line endings LF. chant workspace records reports record-seal-mismatch if the file changes afterwards.",
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "required": ["state"],
+        "properties": { "state": { "enum": ["approved", "retired"] } }
+      },
+      "then": {
+        "description": "An approved or retired contract names who approved it.",
+        "properties": { "approved_by": { "type": "string", "minLength": 1 } }
+      }
+    },
+    {
+      "if": {
+        "required": ["state"],
+        "properties": { "state": { "const": "approved" } }
+      },
+      "then": {
+        "description": "An approved contract states at least one criterion.",
+        "properties": { "criteria": { "minItems": 1 } }
+      }
+    }
+  ],
+  "definitions": {
+    "contractId": {
+      "type": "string",
+      "pattern": "^C-[0-9]{3,}$"
+    },
+    "criterionId": {
+      "description": "A criterion's id, such as a1, unique in its contract.",
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$"
+    },
+    "workspacePath": {
+      "description": "A path from the workspace root, with / separators: no leading /, no . or .. segment, no empty segment, no backslash and no trailing /.",
+      "type": "string",
+      "pattern": "^(?!/)(?!(?:[^/]*/)*\\.{1,2}(?:/|$))(?!.*//)[^\\\\\\u0000-\\u001f]*[^/\\\\\\u0000-\\u001f]$"
+    },
+    "checkPin": {
+      "description": "A check file in the workspace, pinned by the hash of its bytes (#2549).",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["title", "path", "sha256"],
+      "properties": {
+        "title": { "type": "string", "minLength": 1 },
+        "path": {
+          "description": "The check, from the workspace root, such as design/contracts/checks/C-001.test.mjs.",
+          "$ref": "#/definitions/workspacePath"
+        },
+        "sha256": {
+          "description": "Hex SHA-256 of the check's bytes when it was pinned. chant workspace records pin <path> prints it.",
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$"
+        },
+        "as_of": {
+          "description": "When the check was pinned, as an ISO 8601 timestamp.",
+          "type": ["string", "null"]
+        }
+      }
+    }
+  }
+}

package/src/workspace/conformance/__writer_fixture__/decisions/points.json

@@ -0,0 +1,228 @@
+{
+  "$schema": "https://intentius.io/chant/schemas/workspace/decision-points/v1/decision-points.schema.json",
+  "points": {
+    "slice-tier": {
+      "title": "Which builder tier builds this work item",
+      "question": {
+        "type": "choice",
+        "instructions": "Pick the smallest builder tier that can build this work item. The state is how much the work item holds and whether that fits each tier's sizing limits.",
+        "criteria": {
+          "small": "A haiku-class builder. The work item fits the small limits.",
+          "medium": "A mid-size builder. The work item fits the medium limits.",
+          "large": "The largest builder. The work item is bigger than the medium limits."
+        }
+      },
+      "inputs": {
+        "work-item.criteria": "acceptance criteria in the work item",
+        "work-item.files": "distinct paths the work item names",
+        "work-item.words": "words in the body outside headings",
+        "work-item.fits_small": "whether it is within the small tier's limits",
+        "work-item.fits_medium": "whether it is within the medium tier's limits"
+      },
+      "deciders": [
+        {
+          "kind": "table",
+          "rows": [
+            { "when": { "work-item.fits_small": true }, "answer": "small" },
+            { "when": { "work-item.fits_medium": true }, "answer": "medium" }
+          ]
+        },
+        { "kind": "model", "backend": "systemone", "model": "bosun-v3.1-1.7b", "threshold": 0.8 },
+        { "kind": "quorum", "count": 1 }
+      ]
+    },
+    "understand": {
+      "title": "Is this ask understood well enough to build",
+      "question": {
+        "type": "choice",
+        "instructions": "A person asked for a change, and the ask is a work item whose source names what they said and who said it. The factory asks this before it builds the item. The state is the work item: its title and state, the person's words, who asked and where, and any acceptance criteria it has so far. Pick what happens next.",
+        "criteria": {
+          "proceed": "The ask is clear enough to build. The work item opens, and the factory builds it under its lease, writing its plan as acceptance criteria first.",
+          "redraft": "What the person wants is clear, but the work item does not say it well. Someone rewrites the item, which asks this point again, before anything is built.",
+          "ask": "The ask is unclear. Someone asks the person who made it what they mean before anything is built.",
+          "refuse": "The ask will not be built. The work item is dropped, with the reason."
+        }
+      },
+      "inputs": {
+        "work-item.state": "the work item's state: proposed for an ask nobody has kept yet",
+        "work-item.title": "the work item's title",
+        "work-item.source.ask.said": "what the person said, verbatim",
+        "work-item.source.ask.by": "who asked",
+        "work-item.source.ask.via": "where the ask came in, such as hud, shell or mcp",
+        "work-item.acceptance": "the acceptance criteria the item has so far"
+      },
+      "deciders": [
+        {
+          "kind": "table",
+          "rows": [
+            { "when": { "work-item.state": "open" }, "answer": "proceed", "note": "A person opened the item already, or it did not start as a proposal." }
+          ]
+        },
+        { "kind": "quorum", "count": 1 }
+      ]
+    },
+    "ship-skip": {
+      "title": "May this release skip the human gate",
+      "question": {
+        "type": "noul",
+        "instructions": "May this release pass the ship gate without a person approving it? The state is what the release would change. No model decider answers this point, since a model's answer may route or report and never authorizes a release.",
+        "criteria": {
+          "true": "An agent may pass the gate for this release.",
+          "false": "A person approves the release at the gate."
+        }
+      },
+      "inputs": {
+        "release.first_release": "nothing has shipped yet",
+        "release.new_migrations": "migrations that would fire",
+        "release.files_changed": "files changed since the serving release",
+        "release.app_changed": "whether any file under the app directory changed",
+        "release.work_changed": "whether any work item changed",
+        "release.units": "work items the release ships"
+      },
+      "deciders": [
+        {
+          "kind": "table",
+          "rows": [{ "when": {}, "answer": false, "note": "Never, until someone adds a row above this one that says when." }]
+        },
+        { "kind": "quorum", "count": 1, "note": "The ship gate's quorum: a gate that asks this point takes its approver count from here." }
+      ]
+    },
+    "finding-triage": {
+      "title": "What to do about this finding",
+      "question": {
+        "type": "choice",
+        "instructions": "A finding from chant workspace graph --intent, or from chant workspace check --changes, is a gap between what the workspace decided and what it holds. Pick what happens to it. The state is the finding and the region it fired on.",
+        "criteria": {
+          "work-item": "Someone closes the gap. It becomes a work item whose source names the finding and its region.",
+          "needs-a-decision": "The gap is a choice nobody has made. Someone writes a decision before any work starts.",
+          "leave": "Nothing happens. The finding is known, accepted or already taken."
+        }
+      },
+      "inputs": {
+        "finding.code": "the finding's code",
+        "finding.message": "what the finding says",
+        "finding.addressed": "whether a work item already addresses it",
+        "region.path": "the path the finding fired on",
+        "region.member": "the member the region is in",
+        "region.generated": "whether the region is a generated file"
+      },
+      "deciders": [
+        {
+          "kind": "table",
+          "rows": [
+            { "when": { "finding.addressed": true }, "answer": "leave", "note": "A work item already addresses it." },
+            { "when": { "finding.code": "intent-decision-unimplemented" }, "answer": "work-item", "note": "A decided decision that nobody is carrying out is work." },
+            {
+              "when": { "finding.code": { "in": ["intent-region-unconstrained", "intent-decision-contested", "intent-decision-superseded-live"] } },
+              "answer": "needs-a-decision",
+              "note": "No current decision that everyone agrees with covers the region."
+            },
+            {
+              "when": { "finding.code": "change-out-of-scope" },
+              "answer": "needs-a-decision",
+              "note": "A change crossed a boundary a record draws. Someone decides whether the boundary moves or the change goes, and no model answers leave for it. change-uncovered has no row: whether an uncovered change is work, a decision or nothing depends on what the path is, which the model reads."
+            }
+          ]
+        },
+        { "kind": "model", "backend": "systemone", "model": "jev-1.13.0", "threshold": 0.8 },
+        { "kind": "quorum", "count": 1 }
+      ]
+    },
+    "needs-a-decision": {
+      "title": "Does this change need a decision",
+      "question": {
+        "type": "noul",
+        "instructions": "Does the change need a decision written before it lands? The state is the commits in the change's window that changed its region, as chant workspace graph --intent reads them, and the decisions the change's work item implements.",
+        "criteria": {
+          "true": "Someone writes a decision that covers the change, or amends one, before it lands.",
+          "false": "The decisions already in the workspace cover the change."
+        }
+      },
+      "inputs": {
+        "commit.count": "commits in the window that changed the region",
+        "commit.undecided": "of those, the commits no decision's path window holds",
+        "commit.decided_by_window": "of those, the commits in a decision's window that are not that decision's own work",
+        "region.path": "the path the change touches",
+        "region.generated": "whether the region is a generated file",
+        "work-item.implements": "the decisions the change's work item implements"
+      },
+      "deciders": [
+        {
+          "kind": "table",
+          "rows": [
+            { "when": { "commit.count": 0 }, "answer": false, "note": "Nothing changed in the window." },
+            { "when": { "commit.undecided": 0, "commit.decided_by_window": 0 }, "answer": false, "note": "Every commit in the window is a decision's own work." }
+          ]
+        },
+        { "kind": "model", "backend": "systemone", "model": "jev-1.13.0", "threshold": 0.8 },
+        { "kind": "quorum", "count": 1 }
+      ]
+    },
+    "intent-origin": {
+      "title": "Where this change came from",
+      "question": {
+        "type": "choice",
+        "instructions": "An intent walk (chant workspace graph --intent) asks this at a commit no decision's window holds: was the change meant to carry out a decision? The state is the region walked and the commit's node.",
+        "criteria": {
+          "carried-out-decision": "The change carried out a decision, written down or not.",
+          "incidental": "The change was incidental: a fix, a rename or upkeep that no decision is about.",
+          "unknown": "The person walking the region does not know."
+        }
+      },
+      "inputs": {
+        "region.id": "the region walked, as graph --intent names it: region:<path>, with :<start>-<end> or #<symbol>",
+        "node.id": "the node of the walk the question is asked at, as graph --intent names it"
+      },
+      "deciders": [{ "kind": "quorum", "count": 1, "note": "The person walking the region answers. No table or model answers for them." }]
+    },
+    "intent-judgment": {
+      "title": "What the gap between this decision and the code is",
+      "question": {
+        "type": "choice",
+        "instructions": "An intent walk asks this at a decision, or at a commit made inside a decision's window that is not the decision's own work: does the code do what the decision says, and if not, why? The state is the region walked and the node.",
+        "criteria": {
+          "drift": "Drift: the code moved away from a decision that still holds.",
+          "unwritten-supersession": "A decision nobody wrote down superseded it.",
+          "decision-wrong": "The decision was wrong, and is reopened.",
+          "no-gap": "There is no gap: the code does what the decision says.",
+          "not-decidable": "It can't be decided from this walk."
+        }
+      },
+      "inputs": {
+        "region.id": "the region walked, as graph --intent names it: region:<path>, with :<start>-<end> or #<symbol>",
+        "node.id": "the node of the walk the question is asked at, as graph --intent names it"
+      },
+      "deciders": [{ "kind": "quorum", "count": 1, "note": "The person walking the region answers. No table or model answers for them." }]
+    },
+    "intent-disposition": {
+      "title": "What happens about this node",
+      "question": {
+        "type": "choice",
+        "instructions": "An intent walk asks this at any other node, such as a unit, contract, evidence, artifact or the region itself: what was done about the question the walk asks there? The state is the region walked and the node.",
+        "criteria": {
+          "handled": "Handled: it is done, or nothing needed doing.",
+          "skipped": "Skipped, and the note says why.",
+          "needs-discussion": "It needs a discussion or a decision first."
+        }
+      },
+      "inputs": {
+        "region.id": "the region walked, as graph --intent names it: region:<path>, with :<start>-<end> or #<symbol>",
+        "node.id": "the node of the walk the question is asked at, as graph --intent names it"
+      },
+      "deciders": [{ "kind": "quorum", "count": 1, "note": "The person walking the region answers. No table or model answers for them." }]
+    },
+    "agent-question": {
+      "title": "A question an agent asked the people working with it",
+      "adhoc": true,
+      "question": {
+        "type": "choice",
+        "instructions": "An agent asked the people working with it this question, with options of its own, and acts on the one they pick. The question and its options come with each ask, as hud's hud_ask and AskUserQuestion give them."
+      },
+      "inputs": {
+        "ask.id": "the asker's own id for this ask, such as hud's request id for the question, so each ask is a question of its own",
+        "ask.by": "who asked: the agent, or the session it asked in"
+      },
+      "deciders": [{ "kind": "quorum", "count": 1, "note": "A person in the room answers. No table or model answers an agent's question for them." }]
+    }
+  }
+}

package/src/workspace/conformance/__writer_fixture__/drivers/driver.kind.mjs

@@ -0,0 +1,15 @@
+// The driver record kind (#3148, ws-082), data only: no imports, no code.
+//
+// chant workspace records --kind design/drivers/driver.kind.mjs --json
+//
+// A driver groups contracts under one intent: what its member contracts add
+// up to once all of them hold. Its body is the design notes. A driver has no
+// lifecycle of its own; its contracts carry theirs. A review session may
+// judge a driver beside decisions and contracts, as a sign-off on the group.
+export const recordKind = {
+  name: "driver",
+  location: { dir: ".", match: "^D-[0-9]{3,}-.+\\.md$" },
+  format: "markdown-front-matter",
+  schema: { id: "urn:intentius:chant:driver:1", path: "driver.schema.json" },
+  idField: "id",
+};