@intentius/chant 0.102.0 → 0.104.0

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

@@ -31,6 +31,36 @@
         { "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": {
@@ -127,6 +157,72 @@
         { "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",
+};

package/src/workspace/conformance/__writer_fixture__/drivers/driver.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "urn:intentius:chant:driver:1",
+  "title": "Driver file front matter",
+  "description": "The front matter of one driver file in design/drivers/ (#3148, ws-082): contracts grouped under one intent. The Markdown body after the front matter is the design notes. Values stay within what YAML and JSON share.",
+  "type": "object",
+  "additionalProperties": false,
+  "patternProperties": {
+    "^x-": {}
+  },
+  "required": ["schema", "id", "title", "intent", "members"],
+  "properties": {
+    "schema": {
+      "description": "Format version of this file. Bumped only by a change to this schema.",
+      "const": 1
+    },
+    "id": {
+      "description": "Stable id: D, a dash and three or more digits, as studio numbers its drivers. Never reused, never renumbered.",
+      "type": "string",
+      "pattern": "^D-[0-9]{3,}$"
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1
+    },
+    "intent": {
+      "description": "What the member contracts add up to once all of them hold, in a sentence or two.",
+      "type": "string",
+      "pattern": "\\S"
+    },
+    "members": {
+      "description": "The contracts the driver groups, by id. May be empty while the driver is being planned.",
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "type": "string", "pattern": "^C-[0-9]{3,}$" }
+    }
+  }
+}

package/src/workspace/conformance/__writer_fixture__/sessions/session.kind.mjs

@@ -8,11 +8,16 @@
 //
 // A session is a group walking an agenda of records together. It keeps who
 // attended and the verdicts it produced, and it is sealed when it closes.
-// Each verdict it produced is also an entry in the judged decision's reviews
-// list, whose session field names the session. chud's session files (such
-// as sessions/S-0001.json) are the starting shape; sessions are markdown
-// front matter here because that is the only record format chant reads
-// (#2664).
+// Each verdict it produced is also an entry in the judged record's reviews
+// list, whose session field names the session. Its verdicts judge decisions,
+// contracts and drivers (#3148, ws-082): studio's design sessions, which
+// approved contracts and signed off drivers, are this kind, and so is a
+// comment-mode review of the app's UI, one session per review batch, with
+// its anchored comments, the agent's answers and the rounds of replies
+// (#3350, ws-083). chud's session
+// files (such as sessions/S-0001.json) are the starting shape; sessions are
+// markdown front matter so that records new, amend, review and close write
+// them.
 export const recordKind = {
   name: "session",
   location: { dir: ".", match: "^S-[0-9]{4,}-.+\\.md$" },
@@ -32,15 +37,16 @@ export const recordKind = {
   // of the session without closed_digest (front matter as core, the text
   // below it as body, line endings LF), written when the session closes
   // (#2546).
-  // subjects: the decisions the verdicts name. Entries of their reviews list
-  // (the decision kind's reviews.field) name a session.
+  // subjects: the kinds of the records the verdicts name, decisions,
+  // contracts and drivers. Entries of their reviews lists (each kind's
+  // reviews.field) name a session.
   // openedRev, closedRev and closedOn (#2693): the fields records new and
   // records close write, the commits the session opened and closed at and
   // the time it closed. records --since <session id> reads the commits.
   session: {
     verdicts: "verdicts",
     seal: "closed_digest",
-    subjects: { kind: "../decisions/decision.kind.mjs" },
+    subjects: { kinds: ["../decisions/decision.kind.mjs", "../contracts/contract.kind.mjs", "../drivers/driver.kind.mjs"] },
     openedRev: "opened_rev",
     closedRev: "closed_rev",
     closedOn: "closed",