@intentius/chant 0.101.0 → 0.104.0

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

@@ -0,0 +1,54 @@
+// The review-session record kind (#2673, #2650 C10), data only: no imports,
+// no code.
+//
+// chant workspace records --kind design/sessions/session.kind.mjs --json
+// chant workspace records --kind design/sessions/session.kind.mjs --since <open commit> --at <close commit> --json
+// chant workspace records --since S-0002 --json
+// chant workspace records close S-0002
+//
+// 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 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$" },
+  format: "markdown-front-matter",
+  schema: { id: "urn:intentius:chant:session:1", path: "session.schema.json" },
+  idField: "id",
+  stateField: "state",
+  states: ["open", "closed"],
+  // A closed session never changes: records checks its seal on every read.
+  closedStates: ["closed"],
+  // The kind contract requires a supersedes declaration (#2664 proposes making
+  // it optional). The session schema has no supersedes field, so a session
+  // never supersedes another.
+  supersedes: { field: "supersedes", key: "session" },
+  // verdicts: the verdicts the session produced, each naming a decision.
+  // seal: the whole-file seal, sha256: and the hex SHA-256 of the JCS form
+  // 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 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: { kinds: ["../decisions/decision.kind.mjs", "../contracts/contract.kind.mjs", "../drivers/driver.kind.mjs"] },
+    openedRev: "opened_rev",
+    closedRev: "closed_rev",
+    closedOn: "closed",
+  },
+};

package/src/workspace/conformance/__writer_fixture__/sessions/session.schema.json

@@ -0,0 +1,289 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "urn:intentius:chant:session:1",
+  "title": "Review session",
+  "description": "The front matter of a review-session file (#2673, #2650 C10): a group walking an agenda of records together, who attended, and the verdicts the session produced. Its verdicts judge decisions, contracts and drivers, the kinds the session kind names as subjects (#3148, ws-082). A comment-mode review of the app's UI is a session too, one per review batch, with its comments, the agent's answers and the rounds of replies (#3350, ws-083). Each verdict is also an entry in the judged record's reviews list, whose session field names this session. A closed session is sealed: closed_digest is sha256: and the lowercase hex SHA-256 of the JCS form of the whole session without closed_digest (its front matter as core and the text below it as body, line endings LF, #2546), and chant workspace records checks it on every read (session-seal-mismatch).",
+  "type": "object",
+  "additionalProperties": false,
+  "patternProperties": {
+    "^x-": {}
+  },
+  "required": ["schema", "id", "title", "state", "agenda", "attendance", "opened", "closed", "verdicts"],
+  "properties": {
+    "schema": { "const": 1 },
+    "id": {
+      "description": "S- and at least four digits, as chud numbers its sessions.",
+      "type": "string",
+      "pattern": "^S-[0-9]{4,}$"
+    },
+    "title": { "type": "string", "minLength": 1 },
+    "state": { "enum": ["open", "closed"] },
+    "agenda": {
+      "description": "What the session walks, in order: a record by its id, or an item of free text. A record may say what it was when it was put up (digest), the evidence records reviewed with it and any screenshot or recording (#3148).",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "oneOf": [
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["record"],
+            "properties": {
+              "record": { "type": "string", "minLength": 1 },
+              "digest": {
+                "description": "The record's digest when it was put up for review, as chant workspace records --json prints it.",
+                "type": "string",
+                "pattern": "^[0-9a-f]{64}$"
+              },
+              "evidence": {
+                "description": "The evidence records reviewed with it, by id: the SHA-256 each evidence file is named for.",
+                "type": "array",
+                "uniqueItems": true,
+                "items": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+              },
+              "media": {
+                "description": "Screenshots and recordings shown with it, each a workspace path or an https link.",
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["kind", "ref"],
+                  "properties": {
+                    "kind": { "enum": ["screenshot", "recording"] },
+                    "ref": { "type": "string", "minLength": 1 }
+                  }
+                }
+              }
+            }
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["text"],
+            "properties": { "text": { "type": "string", "pattern": "\\S" } }
+          }
+        ]
+      }
+    },
+    "attendance": {
+      "description": "Who joined, with the class of each principal. An agent may attend to prepare and lay out; it never gives a verdict (#2650).",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["principal", "class"],
+        "properties": {
+          "principal": { "type": "string", "minLength": 1 },
+          "class": { "enum": ["person", "agent"] },
+          "roles": {
+            "description": "The roles the principal holds in the session, such as reviewer or facilitator. A quorum that names roles counts only verdicts by principals holding one.",
+            "type": "array",
+            "uniqueItems": true,
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "joined": { "description": "When the principal joined. Optional.", "$ref": "#/definitions/dateTime" }
+        }
+      }
+    },
+    "opened": { "$ref": "#/definitions/dateTime" },
+    "opened_by": {
+      "description": "Who opened the session. Optional.",
+      "type": "string",
+      "minLength": 1
+    },
+    "opened_rev": {
+      "description": "The commit HEAD named when chant workspace records new wrote the session (#2693), or null when the repository had no commit yet; the next records amend, review --session or close fills it. chant writes it, and records --since <session id> reads it. Optional, so a session written before #2693 stays valid.",
+      "oneOf": [{ "type": "null" }, { "$ref": "#/definitions/rev" }]
+    },
+    "closed": {
+      "description": "When the session closed, or null while it is open.",
+      "oneOf": [{ "type": "null" }, { "$ref": "#/definitions/dateTime" }]
+    },
+    "closed_rev": {
+      "description": "The commit HEAD named when chant workspace records close closed the session (#2693), or null when the repository had no commit. Only a closed session has it. Optional, so a session closed before #2693 stays valid.",
+      "oneOf": [{ "type": "null" }, { "$ref": "#/definitions/rev" }]
+    },
+    "closed_by": {
+      "description": "Who closes or closed the session, set by an amendment before chant workspace records close seals it. Optional.",
+      "type": "string",
+      "minLength": 1
+    },
+    "verdicts": {
+      "description": "The verdicts the session produced, in the order they were given. Each names a record of one of the session kind's subject kinds: a decision, a contract or a driver.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["record", "principal", "verdict"],
+        "properties": {
+          "record": { "description": "The id of the record judged.", "type": "string", "minLength": 1 },
+          "principal": { "type": "string", "minLength": 1 },
+          "verdict": { "enum": ["agree", "dissent", "abstain"] },
+          "digest": {
+            "description": "The digest of the record text the verdict judged, as the review entry carries it.",
+            "type": "string",
+            "pattern": "^[0-9a-f]{64}$"
+          },
+          "roles": {
+            "description": "The roles the principal gave the verdict in, which a quorum that names roles counts. Optional.",
+            "type": "array",
+            "uniqueItems": true,
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "at": { "description": "When the verdict was given. Optional.", "$ref": "#/definitions/dateTime" },
+          "note": { "description": "Why, in the principal's words. Optional.", "type": "string" }
+        }
+      }
+    },
+    "follow_ups": {
+      "description": "Records the session started for later, as <kind>:<id> with kind the record kind's name, the form a Chant-Record trailer uses (ws-075): contracts drafted, work items proposed, decisions opened. Optional.",
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "$ref": "#/definitions/recordRef" }
+    },
+    "comments": {
+      "description": "What people said in the session, in order (#3350, ws-083). A comment-mode review of the app's UI is one session per review batch: each comment is anchored to the page and elements it was made on, the agent that worked the batch answers each one, and a person may reply in later rounds. The comments are numbered from 1 by their position, as hud numbers them. Optional.",
+      "type": "array",
+      "items": { "$ref": "#/definitions/comment" }
+    },
+    "rounds": {
+      "description": "The rounds of a review batch (#3350, ws-083): round 0 is the batch as it was sent, with its note; each later round is a person's replies, which send the batch back for another turn. ended is when the agent's turn for the round ended, null while it is working. Optional.",
+      "type": "array",
+      "items": { "$ref": "#/definitions/round" }
+    },
+    "closed_digest": {
+      "description": "The seal, written when the session closes.",
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    }
+  },
+  "definitions": {
+    "rev": { "type": "string", "pattern": "^[0-9a-f]{40,64}$" },
+    "comment": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["text"],
+      "properties": {
+        "text": {
+          "description": "What the person wrote. Empty when the comment only marks its elements for the round's note.",
+          "type": "string"
+        },
+        "by": { "description": "Who wrote it. Optional; a review batch's reviewer is in attendance.", "type": "string", "minLength": 1 },
+        "at": { "description": "When it was written. Optional.", "$ref": "#/definitions/dateTime" },
+        "anchor": {
+          "description": "Where in the app the comment was made: the page's route and the elements it points at.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["route", "elements"],
+          "properties": {
+            "route": {
+              "description": "The page, as its path with any query and hash.",
+              "type": "string",
+              "minLength": 1
+            },
+            "elements": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["selector", "state"],
+                "properties": {
+                  "selector": { "description": "A CSS selector for the element.", "type": "string", "minLength": 1 },
+                  "tag": { "description": "The element's tag name.", "type": "string", "minLength": 1 },
+                  "text": { "description": "The element's text when the comment was made, cut short.", "type": "string" },
+                  "state": {
+                    "description": "anchored: the selector found exactly the element. ambiguous: it found more than one. lost: it found none.",
+                    "enum": ["anchored", "ambiguous", "lost"]
+                  },
+                  "basis": {
+                    "description": "What the selector was built from: an authored anchor (data-hud-id), the element's id, a test id, or its path in the page. Optional.",
+                    "enum": ["authored", "id", "testid", "path"]
+                  }
+                }
+              }
+            }
+          }
+        },
+        "answers": {
+          "description": "The agent's answers to the comment, one per round it answered in, oldest first; the last is the current one. handled: it changed something, and note says what. skipped: it did not, and note says why. needs-discussion: note is the question a person has to settle, by replying in a later round.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["round", "disposition", "note"],
+            "properties": {
+              "round": { "type": "integer", "minimum": 0 },
+              "disposition": { "enum": ["handled", "skipped", "needs-discussion"] },
+              "note": { "type": "string", "pattern": "\\S" },
+              "by": { "description": "The agent that answered. Optional.", "type": "string", "minLength": 1 },
+              "at": { "$ref": "#/definitions/dateTime" }
+            }
+          }
+        },
+        "replies": {
+          "description": "A person's replies to the comment, one per round from round 1.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["round", "text"],
+            "properties": {
+              "round": { "type": "integer", "minimum": 1 },
+              "text": { "type": "string", "pattern": "\\S" },
+              "by": { "type": "string", "minLength": 1 },
+              "at": { "$ref": "#/definitions/dateTime" }
+            }
+          }
+        },
+        "exit": {
+          "description": "How the comment left the box, once a person decided (hud#703, studio-039): kept, its record stays in the repository as the source of the work its changes are; sent, it went out with Send; dismissed, it was let go. Absent until then.",
+          "enum": ["kept", "sent", "dismissed"]
+        },
+        "follow_ups": {
+          "description": "Records the comment led to, as <kind>:<id>, such as the work item that carries its change. Optional.",
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "$ref": "#/definitions/recordRef" }
+        }
+      }
+    },
+    "round": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["round", "note", "at"],
+      "properties": {
+        "round": { "type": "integer", "minimum": 0 },
+        "note": {
+          "description": "The note sent with the round, or null when there was none. A reply round needs a reply or a note.",
+          "type": ["string", "null"]
+        },
+        "by": { "description": "Who sent the round. Optional.", "type": "string", "minLength": 1 },
+        "at": { "description": "When the round was sent.", "$ref": "#/definitions/dateTime" },
+        "ended": {
+          "description": "When the agent's turn for the round ended, or null while it is working. Optional.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/definitions/dateTime" }]
+        }
+      }
+    },
+    "recordRef": {
+      "description": "A record as <kind>:<id>, such as contract:C-002 or work:W-004.",
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*:[A-Za-z0-9][A-Za-z0-9._-]*$"
+    },
+    "dateTime": {
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2}(\\.[0-9]+)?)?(Z|[+-][0-9]{2}:[0-9]{2})$"
+    }
+  },
+  "if": { "required": ["state"], "properties": { "state": { "const": "closed" } } },
+  "then": {
+    "description": "A closed session needs its closed time and its seal.",
+    "required": ["closed_digest"],
+    "properties": { "closed": { "$ref": "#/definitions/dateTime" } }
+  },
+  "else": {
+    "description": "An open session has no closed time, no closing revision and no seal.",
+    "properties": { "closed": { "type": "null" }, "closed_rev": false, "closed_digest": false }
+  }
+}

package/src/workspace/conformance/__writer_fixture__/work/W-001-the-writer-suite-works-this-item.md

@@ -0,0 +1,25 @@
+---
+schema: 1
+id: "W-001"
+title: "The writer suite works this item"
+state: "open"
+implements: []
+needs: []
+constrains:
+  - "member:delivery"
+evidence: []
+acceptance:
+  - id: "AC-1"
+    text: "A run under the item's lease attaches evidence for this criterion through chant"
+    verification: "unit"
+owner: "conformance"
+opened_on: "2026-01-01"
+source:
+  kind: "workspace"
+  member: "delivery"
+supersedes: []
+---
+
+# The writer suite works this item
+
+The writer conformance suite (INTENTIUS/chant#3159) claims this item's lease, renews it, attaches evidence for AC-1 and releases it, each through the writer under test.

package/src/workspace/conformance/__writer_fixture__/work/work.kind.mjs

@@ -0,0 +1,60 @@
+// The work item record kind (#2683), data only: no imports, no code.
+//
+// chant workspace records --kind work/work.kind.mjs --json
+// chant workspace graph --intent <region> --kind decisions/decision.kind.mjs --kind work/work.kind.mjs
+//
+// A work item is a record in the workspace, with its dependencies written
+// inside it, that people and agents share as one queue with no server. Most
+// come from a gap the intent graph reports, named in `source.finding`.
+// Records are Markdown with front matter: an item keeps its id while its
+// state changes, so it is not content-addressed. ws-053 (#2664) lets a kind
+// read `format: "json"`, but `records new` and `records amend` write Markdown
+// only, so work items stay Markdown until the write commands write JSON.
+export const recordKind = {
+  name: "work",
+  location: { dir: ".", match: "^W-[0-9]{3,}-.+\\.md$" },
+  format: "markdown-front-matter",
+  schema: { id: "urn:intentius:chant:work:1", path: "work.schema.json" },
+  idField: "id",
+  stateField: "state",
+  // A proposal opens proposed: an item an agent or a decision point's model
+  // suggested (ws-058, #2741). A person keeps it by moving it to open, or drops it.
+  states: ["proposed", "open", "in-progress", "done", "dropped"],
+  closedStates: ["done", "dropped"],
+  // Takes effect from a done or dropped item, the closed states.
+  supersedes: { field: "supersedes", key: "work" },
+  // records new --by and the MCP records-new tool's by name a proposal's
+  // proposer here (#2756).
+  proposedBy: { field: "proposed_by" },
+  // Evidence is the proof of done: links, or workspace files pinned by hash.
+  pins: { field: "evidence" },
+  // The same grammar as a decision's: member:, path:, issues and decision ids.
+  constrains: { field: "constrains" },
+  // Workspace paths the change doing the work must not touch (#2773):
+  // chant workspace check --changes --work <id> reports change-out-of-scope.
+  outOfScope: { field: "out_of_scope" },
+  // needs and implements, the decisions they name, and when an item is ready.
+  work: {
+    needs: "needs",
+    implements: "implements",
+    decisions: "../decisions/decision.kind.mjs",
+    open: "open",
+    done: "done",
+    closedOn: "closed_on",
+    // What done means, stated on the record (#2772): each criterion expects
+    // a verification, and a manual verdict never comes from the owner.
+    acceptance: { field: "acceptance", implementer: "owner" },
+    // The builder tiers an item may name in tier, declared once here (#3147).
+    // The same three the slice-tier decision point answers with.
+    tier: { field: "tier", tiers: ["small", "medium", "large"] },
+    // An item is left to people after this many failed attempts, counted
+    // from its lease history (chant workspace work history). An item's own
+    // max_attempts overrides it (#3147).
+    attempts: { field: "max_attempts", max: 3 },
+    // Decision points' answers about an item are joined from the answer
+    // kind by the item's id, never copied onto the item (#3147).
+    answers: "../answers/answer.kind.mjs",
+    // A workspace with a contract kind links items to contracts with
+    // contract: { field: "contract", kind: "<contract kind file>" }.
+  },
+};