@intentius/chant 0.101.0 → 0.102.0

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

@@ -0,0 +1,95 @@
+{
+  "$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. 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." },
+    "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" },
+    "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." },
+    "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" } },
+    "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" }
+      },
+      "additionalProperties": false
+    }
+  }
+}

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

@@ -0,0 +1,132 @@
+{
+  "$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 }
+      ]
+    },
+    "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 }
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,48 @@
+// 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 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).
+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 decisions the verdicts name. Entries of their reviews list
+  // (the decision 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" },
+    openedRev: "opened_rev",
+    closedRev: "closed_rev",
+    closedOn: "closed",
+  },
+};

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

@@ -0,0 +1,108 @@
+{
+  "$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. 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,
+  "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.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "oneOf": [
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["record"],
+            "properties": { "record": { "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": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }
+        }
+      }
+    },
+    "opened": { "$ref": "#/definitions/dateTime" },
+    "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" }]
+    },
+    "verdicts": {
+      "description": "The verdicts the session produced, in the order they were given.",
+      "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}$"
+          }
+        }
+      }
+    },
+    "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}$" },
+    "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>" }.
+  },
+};