@intentius/chant 0.124.23 → 0.124.25

package/src/workspace/nested-graph.ts

@@ -22,7 +22,7 @@
 
 import { spawn } from "node:child_process";
 import type { ParsedArgs } from "../cli/registry";
-import type { ComposedMember, ComposedNode, WorkspaceGraph } from "./compose-graph";
+import { danglingKey, SCOPED_GROUPS, type ComposedMember, type ComposedNode, type WorkspaceGraph } from "./compose-graph";
 
 export type { NestedWorkspace } from "./compose-graph";
 import { readerToolchain, type Toolchain } from "./member-commands";
@@ -148,12 +148,17 @@ export function foldNested(graph: WorkspaceGraph, member: ComposedMember, inner:
       into[k] = [...(into[k] ?? []), ...v.map((id) => prefixed(outer, id))].sort();
     }
   }
-  for (const key of ["byStack", "byContainer", "byWave"] as const) {
+  for (const key of SCOPED_GROUPS) {
     for (const [k, v] of Object.entries(innerGroups[key] ?? {})) {
       const into = (groups[key] ??= {});
       into[prefixed(outer, k)] = v.map((id) => prefixed(outer, id)).sort();
     }
   }
+  if (inner.dangling?.length) {
+    graph.dangling = [...(graph.dangling ?? []), ...inner.dangling.map((d) => ({ ...d, from: prefixed(outer, d.from), member: outer, nested: d.member }))].sort((a, b) =>
+      danglingKey(a).localeCompare(danglingKey(b)),
+    );
+  }
   for (const c of inner.collectors ?? []) graph.collectors.push({ ...c, member: prefixed(outer, c.member) });
   for (const [kind, attrs] of Object.entries(inner.derivedAttrs ?? {})) {
     const all = new Set([...(graph.derivedAttrs?.[kind] ?? []), ...attrs]);

package/src/workspace/point-answer.schema.json

@@ -2,7 +2,7 @@
   "$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-.",
+  "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 open question that no longer applies is `withdrawn` (`points withdraw`, #2888), and asking it again opens it again. 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-": {} },
@@ -65,6 +65,17 @@
       "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" }
     },
+    "withdrawn": {
+      "type": "object",
+      "description": "An open question that no longer applies, such as one about a work item its author changed, which a run asks about anew (`points withdraw`, #2888): who withdrew it, when and why. A withdrawn question is not open, and nobody answers it; asking it again opens it again.",
+      "required": ["by", "on"],
+      "properties": {
+        "by": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 }, "description": "Who withdrew it." },
+        "on": { "$ref": "#/definitions/date" },
+        "note": { "type": "string", "minLength": 1, "description": "Why it was withdrawn (`points withdraw --note`)." }
+      },
+      "additionalProperties": false
+    },
     "asked_on": { "$ref": "#/definitions/date" },
     "answered_on": { "$ref": "#/definitions/date" },
     "source": {
@@ -85,6 +96,10 @@
       "if": { "properties": { "state": { "const": "escalated" } }, "required": ["state"] },
       "then": { "not": { "required": ["answer"] }, "properties": { "decider": { "properties": { "kind": { "const": "quorum" } } } } }
     },
+    {
+      "if": { "required": ["withdrawn"] },
+      "then": { "properties": { "state": { "enum": ["escalated", "proposed"] } } }
+    },
     {
       "if": { "properties": { "decider": { "properties": { "kind": { "const": "model" } }, "required": ["kind"] } }, "required": ["decider"] },
       "then": { "required": ["probabilities", "confidence", "threshold"], "properties": { "decider": { "required": ["backend", "model"] } } }

package/src/workspace/points-cli.ts

@@ -6,12 +6,12 @@
  * The points come from each record kind the declaration names with an
  * `answers` block, or from `--kind`, and the questions are that kind's
  * records. A question is open while it is escalated to people or proposed by a
- * model and not yet confirmed, and it lists any model's answer with its
+ * model and not yet confirmed, and not withdrawn (#2888), and it lists any model's answer with its
  * confidence, so a reader such as hud can prompt a person and an MCP client
  * can see it. With `--open`, only open questions are listed. It never writes
  * and never calls a model.
  *
- * `points ask`, `points answer` and `points retract` are the writes, in
+ * `points ask`, `points answer`, `points retract` and `points withdraw` are the writes, in
  * `decide.ts`.
  */
 
@@ -21,7 +21,7 @@ import { formatError } from "../cli/format";
 import type { CommandContext } from "../cli/registry";
 import { declaredRecordKinds, readDeclaration, readerVersion, WorkspaceReadError, type ErrorLocation, type WorkspaceErrorCode } from "./declaration";
 import { declaredKindFile } from "./declared-kinds";
-import { answerPoint, askPoint, questionView, retractAnswer, POINTS_WRITE_CONTRACT_VERSION, POINTS_WRITE_SCHEMA_ID, type PointsWriteDocument, type PointsWriteVerb, type QuestionView } from "./decide";
+import { answerPoint, askPoint, questionView, retractAnswer, withdrawQuestion, POINTS_WRITE_CONTRACT_VERSION, POINTS_WRITE_SCHEMA_ID, type PointsWriteDocument, type PointsWriteVerb, type QuestionView } from "./decide";
 import { candidates, inputOutput, pointsFileOf, pointVersion, quorumOf, readPointsThrough, type Decider, type ModelAsk, type WireAnswer } from "./points";
 import type { ReasonCode } from "./reason-codes";
 import { gitRevisionSource, workingTreeSource } from "./record-source";
@@ -107,7 +107,8 @@ export type PointsDocument =
       sources: SourceView[];
       points: PointView[];
       questions: QuestionView[];
-      summary: { points: number; questions: number; open: number; escalated: number; proposed: number; answered: number };
+      /** escalated, proposed and answered count by state, withdrawn ones included; withdrawn counts the questions withdrawn (#2888). */
+      summary: { points: number; questions: number; open: number; escalated: number; proposed: number; answered: number; withdrawn: number };
     }
   | { $schema: string; contract: number; chant: string; error: { code: WorkspaceErrorCode; message: string; location: ErrorLocation | null } };
 
@@ -197,7 +198,7 @@ export async function workspacePoints(query: PointsQuery): Promise<PointsDocumen
     sources,
     points,
     questions,
-    summary: { points: points.length, questions: questions.length, open: questions.filter((q) => q.open).length, escalated: count("escalated"), proposed: count("proposed"), answered: count("answered") },
+    summary: { points: points.length, questions: questions.length, open: questions.filter((q) => q.open).length, escalated: count("escalated"), proposed: count("proposed"), answered: count("answered"), withdrawn: questions.filter((q) => q.withdrawn !== null).length },
   };
 }
 
@@ -228,7 +229,7 @@ export function formatPoints(doc: Extract<PointsDocument, { points: unknown }>):
   lines.push("");
   for (const q of doc.questions) {
     const model = q.model && q.state !== "answered" ? `  model ${JSON.stringify(q.model.answer)} at ${q.model.confidence ?? "?"}${q.model.observed ? "" : `, below ${q.model.threshold ?? "?"}`}` : "";
-    lines.push(`${q.id}  ${q.state}  ${q.title}${model}`);
+    lines.push(`${q.id}  ${q.withdrawn ? "withdrawn" : q.state}  ${q.title}${model}`);
   }
   const n = doc.summary.questions;
   lines.push(doc.open ? `${n} open ${n === 1 ? "question" : "questions"}` : `${n} ${n === 1 ? "question" : "questions"}, ${doc.summary.open} open`);
@@ -252,6 +253,7 @@ const USAGE = [
   "chant workspace points ask <point> --inputs <file|-|json> [--candidates <file|-|json>] [--response <file>] [--subject <id>] [--kind <kind file>] [--dry-run]",
   "chant workspace points answer <id> --answer <value> --by <name> [--by <name>...] [--note <text>] [--relayed-by <principal>] [--kind <kind file>] [--resume] [--dry-run]",
   "chant workspace points retract <id> --by <name> [--by <name>...] [--note <text>] [--kind <kind file>] [--dry-run]",
+  "chant workspace points withdraw <id> --by <name> [--by <name>...] [--note <text>] [--kind <kind file>] [--dry-run]",
 ].join("\n");
 
 function usage(verb: PointsWriteVerb, message: string): PointsWriteDocument {
@@ -276,7 +278,7 @@ function readJson(verb: PointsWriteVerb, flag: string, value: string, cwd: strin
   }
 }
 
-/** `chant workspace points`, and its `ask`, `answer` and `retract` verbs. */
+/** `chant workspace points`, and its `ask`, `answer`, `retract` and `withdraw` verbs. */
 export async function runWorkspacePoints(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
   const cwd = process.cwd();
@@ -324,8 +326,14 @@ export async function runWorkspacePoints(ctx: CommandContext): Promise<number> {
     if (!args.bys || args.bys.length === 0) return print(usage("retract", "--by <name> is required, once for each person who takes the answer back"));
     return print(await retractAnswer({ cwd, id, by: args.bys, note: args.note, kind: args.kind, dryRun: args.dryRun }));
   }
+  if (verb === "withdraw") {
+    const id = args.extraPositional2;
+    if (!id) return print(usage("withdraw", "withdraw needs the question's id"));
+    if (!args.bys || args.bys.length === 0) return print(usage("withdraw", "--by <name> is required: who withdraws the question"));
+    return print(await withdrawQuestion({ cwd, id, by: args.bys, note: args.note, kind: args.kind, dryRun: args.dryRun }));
+  }
   if (verb !== undefined) {
-    console.error(formatError({ message: `chant workspace points takes no argument but ask, answer or retract (got ${verb})`, hint: USAGE }));
+    console.error(formatError({ message: `chant workspace points takes no argument but ask, answer, retract or withdraw (got ${verb})`, hint: USAGE }));
     return 1;
   }
   const doc = await workspacePoints({ cwd, at: args.at, open: args.open, kind: args.kind });

package/src/workspace/points-write.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://intentius.io/chant/schemas/workspace/points-write/v1/points-write.schema.json",
   "title": "chant workspace points ask, answer and retract output",
-  "description": "What `chant workspace points ask`, `points answer` and `points retract` print (ws-058, #2739, #3351): the answer record asked for or written, as `points --json` lists a question. ask returns the record that is there when the same point, declaration and inputs were answered or proposed before (reused), and otherwise writes one: answered from a table, proposed from a model at or above its threshold, escalated to people below it. answer records people's answer to an open question once the point's quorum is met, with their note. retract takes an answer back once the quorum is met: the question is escalated to people again and the answer moves into its retractions (ws-084). Nothing is committed to the working branch, and nothing is written on a refusal or with --dry-run. In a steward's turn a new record goes on the lifecycle ledger instead of the working tree (#2786), as a commit on chant/lifecycle, and a record already held there is rewritten there. The error codes are a closed list, each in the one closed list of `reason-codes.ts`. Written at contract version 1 of the write documents.",
+  "description": "What `chant workspace points ask`, `points answer`, `points retract` and `points withdraw` print (ws-058, #2739, #3351, #2888): the answer record asked for or written, as `points --json` lists a question. ask returns the record that is there when the same point, declaration and inputs were answered or proposed before (reused), and otherwise writes one: answered from a table, proposed from a model at or above its threshold, escalated to people below it. answer records people's answer to an open question once the point's quorum is met, with their note. retract takes an answer back once the quorum is met: the question is escalated to people again and the answer moves into its retractions (ws-084). withdraw closes an open question that no longer applies, with who withdrew it, when and why; asking it again opens it again (#2888). Nothing is committed to the working branch, and nothing is written on a refusal or with --dry-run. In a steward's turn a new record goes on the lifecycle ledger instead of the working tree (#2786), as a commit on chant/lifecycle, and a record already held there is rewritten there. The error codes are a closed list, each in the one closed list of `reason-codes.ts`. Written at contract version 1 of the write documents.",
   "oneOf": [
     {
       "$ref": "#/$defs/result"
@@ -38,7 +38,8 @@
           "enum": [
             "ask",
             "answer",
-            "retract"
+            "retract",
+            "withdraw"
           ]
         },
         "kind": {
@@ -507,6 +508,38 @@
             }
           }
         },
+        "withdrawn": {
+          "type": [
+            "object",
+            "null"
+          ],
+          "description": "Who withdrew the question, when and why (points withdraw, #2888): an open question that no longer applies, such as one about a work item its author changed. A withdrawn question keeps its state and is not open. null when it was not withdrawn, and absent from a chant before it.",
+          "required": [
+            "by",
+            "on",
+            "note"
+          ],
+          "properties": {
+            "by": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "on": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "note": {
+              "type": [
+                "string",
+                "null"
+              ]
+            }
+          }
+        },
         "asked": {
           "description": "An ad-hoc point's question as its ask gave it (points ask --candidates, #3403): the question's text, and its criteria, what each candidate means, in the point's question type's shape. People's answer is one of the candidates. null for a declared point's question, and absent from a chant before it.",
           "oneOf": [
@@ -567,7 +600,8 @@
                   "answer-points-unreadable",
                   "answer-point-unknown",
                   "answer-point-changed",
-                  "record-unattested"
+                  "record-unattested",
+                  "record-ratified-below-quorum"
                 ]
               },
               "message": {
@@ -598,7 +632,8 @@
           "enum": [
             "ask",
             "answer",
-            "retract"
+            "retract",
+            "withdraw"
           ]
         },
         "error": {

package/src/workspace/points.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://intentius.io/chant/schemas/workspace/points/v1/points.schema.json",
   "title": "chant workspace points output",
-  "description": "What `chant workspace points --json` prints (ws-058, #2739): the decision points each declared answer kind's points file declares, and the questions asked of them, each an answer record. A question is open while it is escalated to people, or proposed by a model and not yet confirmed; it carries any model's answer with its confidence and threshold, so a reader can prompt a person. With --open only open questions are listed. chant never calls a model to print this. Readers ignore fields they do not know; a field is only ever added within a version. The reason and error codes are closed lists, each in the one closed list of `reason-codes.ts`. Contract version 1 is written by chant 0.81.0 and newer, and this document was added to it by #2739; a chant without it refuses the command.",
+  "description": "What `chant workspace points --json` prints (ws-058, #2739): the decision points each declared answer kind's points file declares, and the questions asked of them, each an answer record. A question is open while it is escalated to people, or proposed by a model and not yet confirmed, and not withdrawn (#2888); it carries any model's answer with its confidence and threshold, so a reader can prompt a person. With --open only open questions are listed. chant never calls a model to print this. Readers ignore fields they do not know; a field is only ever added within a version. The reason and error codes are closed lists, each in the one closed list of `reason-codes.ts`. Contract version 1 is written by chant 0.81.0 and newer, and this document was added to it by #2739; a chant without it refuses the command.",
   "oneOf": [
     {
       "$ref": "#/$defs/result"
@@ -95,7 +95,8 @@
             "open",
             "escalated",
             "proposed",
-            "answered"
+            "answered",
+            "withdrawn"
           ],
           "properties": {
             "points": {
@@ -121,6 +122,11 @@
             "answered": {
               "type": "integer",
               "minimum": 0
+            },
+            "withdrawn": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Questions withdrawn because they no longer apply (#2888), whatever their state; none of them is open."
             }
           }
         }
@@ -765,6 +771,38 @@
             }
           }
         },
+        "withdrawn": {
+          "type": [
+            "object",
+            "null"
+          ],
+          "description": "Who withdrew the question, when and why (points withdraw, #2888): an open question that no longer applies, such as one about a work item its author changed. A withdrawn question keeps its state and is not open. null when it was not withdrawn, and absent from a chant before it.",
+          "required": [
+            "by",
+            "on",
+            "note"
+          ],
+          "properties": {
+            "by": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "on": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "note": {
+              "type": [
+                "string",
+                "null"
+              ]
+            }
+          }
+        },
         "asked": {
           "description": "An ad-hoc point's question as its ask gave it (points ask --candidates, #3403): the question's text, and its criteria, what each candidate means, in the point's question type's shape. People's answer is one of the candidates. null for a declared point's question, and absent from a chant before it.",
           "oneOf": [
@@ -825,7 +863,8 @@
                   "answer-points-unreadable",
                   "answer-point-unknown",
                   "answer-point-changed",
-                  "record-unattested"
+                  "record-unattested",
+                  "record-ratified-below-quorum"
                 ]
               },
               "message": {

package/src/workspace/reason-codes.ts

@@ -112,6 +112,7 @@ export const REASONS = {
   "seal-unverifiable": "Nothing here can say whose seal it is: there is no signers file at base, ssh-keygen is not installed, or the record came back in a return sealed by a signer no admission lists yet.",
   // A record whose author seal is not attested under a signers file at base (records, #2688). A warning: the record is still read.
   "record-unattested": "A signers file is active at base, and the record names an author whose seal does not verify: it has none, the author has no key in the file, or the signature fails.",
+  "record-ratified-below-quorum": "The record is in its kind's ratified state (reviews.ratified), and its quorum is not met: it was written to that state by hand, past the check of records new and amend. It is still read, and stays valid.",
   // A records read that fails (records).
   "kind-unreadable": "The record kind file is missing or could not be imported.",
   "kind-invalid": "The record kind file exports no recordKind, or its shape is wrong.",
@@ -161,7 +162,7 @@ export const REASONS = {
   "answer-in-steward-turn": "The answer was given during a steward's turn, or by a process it started: a steward never answers a decision point, and a person answers it through hud or at a shell.",
   "answer-never-over-mcp": "The answer or retraction came over MCP or ACP, or from a process a session on one started, and the question constrains a gate that is never resolved there: a person answers it at a shell or through hud (#3817).",
   "answer-not-answered": "points retract names a question that has no answer to retract: it is escalated or proposed, and people answer it instead (#3351).",
-  "answer-field-unsupported": "The answer kind's copy of point-answer.schema.json predates a field the write needs, a note, a relay, a retraction or an ad-hoc question's asked: copy the schema anew to turn it on (#3351, #3402, #3403).",
+  "answer-field-unsupported": "The answer kind's copy of point-answer.schema.json predates a field the write needs, a note, a relay, a retraction, an ad-hoc question's asked or a withdrawal: copy the schema anew to turn it on (#3351, #3402, #3403, #2888).",
   "point-candidates-invalid": "points ask names an ad-hoc point without --candidates, a declared point with them, or candidates that are not a question and criteria of the point's question type (#3403).",
   // records --since that fails (#2673).
   "since-rev-unknown": "--since names no commit, or a session with no opening revision and no commit that added it.",

package/src/workspace/record-assets.test.ts

@@ -181,6 +181,20 @@ describe("chant workspace records checks each pin", () => {
     expect(pinFile("ws/design/screens/home.png", root)).toEqual({ path: "design/screens/home.png", sha256: sha(PNG) });
     expect(pinFile("design", join(root, "ws"))).toEqual({ error: "design is not a file" });
   });
+
+  test("records pin takes the workspace above the current directory or the kind file, not the nested one above the file (#3038)", () => {
+    const root = repo({
+      "chant.workspace.json": declaration([{ name: "template", dir: "template", kind: "other", because: "a template" }]),
+      "template/chant.workspace.json": declaration([{ name: "box", dir: "box", kind: "other", because: "the box" }]),
+      "template/box/builder.mjs": "export {};\n",
+      "decisions/decision.kind.mjs": KIND,
+    });
+    const hash = sha("export {};\n");
+    expect(pinFile("template/box/builder.mjs", root)).toEqual({ path: "template/box/builder.mjs", sha256: hash });
+    expect(pinFile("box/builder.mjs", join(root, "template"))).toEqual({ path: "box/builder.mjs", sha256: hash });
+    expect(pinFile("box/builder.mjs", join(root, "template"), "../decisions/decision.kind.mjs")).toEqual({ path: "template/box/builder.mjs", sha256: hash });
+    expect(pinFile("chant.workspace.json", root, "template/box/builder.mjs")).toMatchObject({ error: expect.stringContaining("not a file path inside the workspace") });
+  });
 });
 
 describe("chant workspace graph --kind", () => {

package/src/workspace/records-cli.ts

@@ -78,7 +78,7 @@ export const RECORDS_CONTRACT_VERSION = 1;
 export const RECORDS_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/records/v1/records.schema.json";
 
 const USAGE =
-  "chant workspace records [--kind <kind file>] [--current] [--uncommitted | --at <rev>] [--base <rev>] [--require attested] [--json] | chant workspace records [--kind <kind file>] --since <rev|session id> [--at <rev>] [--json] | chant workspace records pin <path> | chant workspace records new|amend|review|close (#2670, #2693)";
+  "chant workspace records [--kind <kind file>] [--current] [--uncommitted | --at <rev>] [--base <rev>] [--require attested] [--json] | chant workspace records [--kind <kind file>] --since <rev|session id> [--at <rev>] [--json] | chant workspace records pin <path> [--kind <kind file>] | chant workspace records new|amend|review|close (#2670, #2693)";
 
 /** Exit code when the read worked and a record falls below `--require`. */
 export const EXIT_BELOW_REQUIRED = 2;
@@ -336,6 +336,16 @@ export async function quorumOptionsFor(loaded: LoadedRecordKind, tree: Workspace
   };
 }
 
+/**
+ * What a quorum that is not met lacks, for `ratify-quorum-not-met` and
+ * `record-ratified-below-quorum` (#2873, #2878): the need, the agreeing
+ * verdicts that count, and each verdict that does not count, with why.
+ */
+export function quorumShortfall(q: Quorum): string {
+  const notCounted = q.notCounted.length > 0 ? ` (not counted: ${q.notCounted.map((v) => `${v.reviewer}, ${v.reason!.code}`).join("; ")})` : "";
+  return `its quorum needs ${q.need} agreeing verdicts that count, and it has ${q.agreed}${notCounted}`;
+}
+
 /**
  * Where a kind's pinned paths resolve: the workspace whose declaration sits
  * nearest above the kind file, when it is inside the repository, or else the
@@ -446,10 +456,16 @@ export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument
       // Returned work (#2552): its seals verify against the signers admitted for its return too.
       const recordPolicy = p.returned ? returnedPolicy(policy, p.returned.id) : policy;
       const options = p.returned ? await quorumOptionsFor(loaded, tree, recordPolicy) : quorumOptions;
+      const quorum = options ? computeQuorum(loaded.kind, r, options) : null;
+      const ratified = loaded.kind.reviews?.ratified;
+      if (quorum && !quorum.met && ratified !== undefined && r.state === ratified) {
+        // Written to the ratified state by hand, past the check of records new and amend (#2878).
+        r.warnings.push({ code: "record-ratified-below-quorum", message: `${r.id ?? r.path} is ${ratified}, and ${quorumShortfall(quorum)}` });
+      }
       records.push({
         ...r,
         provenance: p,
-        ...(options ? { quorum: computeQuorum(loaded.kind, r, options) } : {}),
+        ...(options ? { quorum } : {}),
         ...(seals ? authorSeal(loaded.kind, r, recordPolicy, seals.checkRecordSeal) : {}),
       });
     }
@@ -635,12 +651,17 @@ async function raiseWorkGaps(loaded: LoadedRecordKind, records: RecordView[], op
 /**
  * `chant workspace records pin <path>`: the `{path, sha256}` a decision's
  * evidence entry holds for a file, with the path from the workspace root
- * (the nearest declaration above the file, or the repository root).
+ * records resolve pins in. With `kind`, that is the declaration nearest above
+ * the kind file, or the repository root, as {@link pinRoot} has it. Without,
+ * it is the declaration nearest above `cwd`, and only when there is none the
+ * one nearest above the file, so a workspace nested inside the current one is
+ * never taken for it (#3038).
  */
-export function pinFile(file: string, cwd: string): { path: string; sha256: string } | { error: string } {
+export function pinFile(file: string, cwd: string, kind?: string): { path: string; sha256: string } | { error: string } {
   const abs = realpathOr(resolve(cwd, file));
-  const top = gitRoot(dirname(abs));
-  const ws = findWorkspaceRoot(dirname(abs));
+  const from = kind === undefined ? dirname(abs) : dirname(resolve(cwd, kind));
+  const ws = kind === undefined ? (findWorkspaceRoot(cwd) ?? findWorkspaceRoot(from)) : findWorkspaceRoot(from);
+  const top = gitRoot(from);
   const base = ws ? realpathOr(ws.dir) : top ? realpathOr(top) : realpathOr(cwd);
   const path = relative(base, abs).split(sep).join("/");
   if (path.startsWith("..") || !isWorkspacePath(path)) return { error: `${file} is not a file path inside the workspace at ${base}` };
@@ -659,7 +680,7 @@ export async function runWorkspaceRecords(ctx: CommandContext): Promise<number>
       console.error(formatError({ message: "pin needs the path of a file", hint: USAGE }));
       return 1;
     }
-    const pin = pinFile(args.extraPositional2, process.cwd());
+    const pin = pinFile(args.extraPositional2, process.cwd(), args.kind);
     if ("error" in pin) {
       console.error(formatError({ message: pin.error, hint: USAGE }));
       return 1;

package/src/workspace/records-write-commands.e2e.test.ts

@@ -419,6 +419,38 @@ describe("ratifying against the quorum (#2873)", () => {
     expect(code(doc)).toBe("ratify-quorum-not-met");
   });
 
+  test("a record edited by hand to ratified below its quorum reads with record-ratified-below-quorum, and stays valid (#2878)", async () => {
+    const read = async (id: string, kind = KIND) => {
+      const doc = await queryRecords({ kind, cwd: dir });
+      if ("error" in doc) throw new Error(doc.error.message);
+      return doc.records.find((r) => r.id === id)!;
+    };
+    const warned = (r: { warnings: { code: string }[] }) => r.warnings.some((w) => w.code === "record-ratified-below-quorum");
+    // A decided record below its quorum is not warned about.
+    await agree("alice");
+    await agree("lex00");
+    expect(warned(await read("ws-001"))).toBe(false);
+    writeFileSync(join(dir, "decisions", "ws-001-one.md"), text("ws-001-one.md").replace('state: "decided"', 'state: "ratified"'));
+    const r = await read("ws-001");
+    expect(r).toMatchObject({ state: "ratified", valid: true, reasons: [] });
+    expect(r.quorum).toMatchObject({ need: 2, agreed: 1, met: false });
+    expect(r.warnings.find((w) => w.code === "record-ratified-below-quorum")!.message).toBe(
+      "ws-001 is ratified, and its quorum needs 2 agreeing verdicts that count, and it has 1 (not counted: lex00, review-decider)",
+    );
+    // A record ratified through amend at its quorum carries no such warning.
+    put("ws-006-six.md", decision({ id: "ws-006", title: "Six" }));
+    await agree("alice", "ws-006");
+    await agree("bob", "ws-006");
+    expect(await ratify("ws-006")).toMatchObject({ changed: ["state", "closed_digest"] });
+    expect(warned(await read("ws-006"))).toBe(false);
+    // A kind without reviews.ratified never warns: ws-003 opened ratified with no verdicts.
+    expect(warned(await read("ws-003"))).toBe(true);
+    // A kind module is cached by its path, so the kind without it is a second file.
+    const kindFile = join(dir, "decisions", "decision.kind.mjs");
+    writeFileSync(join(dir, "decisions", "plain.kind.mjs"), readFileSync(kindFile, "utf-8").replace(', ratified: "ratified" }', " }"));
+    expect(warned(await read("ws-003", "decisions/plain.kind.mjs"))).toBe(false);
+  });
+
   test("records new refuses a record that opens ratified below its quorum", async () => {
     const fresh = decision({ title: "Straight in", state: "ratified" });
     delete fresh.id;

package/src/workspace/records-write.ts

@@ -61,7 +61,7 @@ import {
   type RecordEntry,
   type RecordWarning,
 } from "./records";
-import { declaredKindFiles, pinRoot, quorumOptionsFor, realpathOr } from "./records-cli";
+import { declaredKindFiles, pinRoot, quorumOptionsFor, quorumShortfall, realpathOr } from "./records-cli";
 import { policyAtBase, resolveBase } from "./trust/provenance";
 import { WorkspaceReadError } from "./declaration";
 import { findSessionKinds, headCommit, sessionKindsFor } from "./session-kinds";
@@ -516,10 +516,9 @@ async function refuseRatifyBelowQuorum(o: Opened, written: RecordEntry, id: stri
   const options = await quorumOptionsFor(o.loaded, tree, policy);
   const q = options ? computeQuorum(o.loaded.kind, written, options) : null;
   if (q === null || q.met) return;
-  const notCounted = q.notCounted.length > 0 ? ` (not counted: ${q.notCounted.map((v) => `${v.reviewer}, ${v.reason!.code}`).join("; ")})` : "";
   throw new RecordWriteError(
     "ratify-quorum-not-met",
-    `${id} can't be ${ratified} yet: its quorum needs ${q.need} agreeing verdicts that count, and it has ${q.agreed}${notCounted}. Add verdicts with chant workspace records review ${id} --verdict agree --by <reviewer>, then set ${o.loaded.kind.stateField} to ${ratified} again`,
+    `${id} can't be ${ratified} yet: ${quorumShortfall(q)}. Add verdicts with chant workspace records review ${id} --verdict agree --by <reviewer>, then set ${o.loaded.kind.stateField} to ${ratified} again`,
   );
 }
 

package/src/workspace/records.schema.json

@@ -413,7 +413,8 @@
             "answer-points-unreadable",
             "answer-point-unknown",
             "answer-point-changed",
-            "record-unattested"
+            "record-unattested",
+            "record-ratified-below-quorum"
           ]
         },
         "message": { "type": "string" }

package/src/workspace/records.ts

@@ -147,8 +147,9 @@ export const SEAL_REASON_CODES = [
 export type SealCode = (typeof SEAL_REASON_CODES)[number];
 
 /**
- * A warning about a record's own seal (#2688), raised by `records` with the
- * policy at base, never by a write. Closed, like the reason codes.
+ * A warning `records` raises with the policy at base, never by a write: about
+ * a record's own seal (#2688), or a ratified record's quorum (#2878). Closed,
+ * like the reason codes.
  */
 export const SEAL_WARNING_CODES = [
   /**
@@ -158,6 +159,13 @@ export const SEAL_WARNING_CODES = [
    * fails. The record is still read, and still valid.
    */
   "record-unattested",
+  /**
+   * The record is in its kind's ratified state (`reviews.ratified`, #2873),
+   * and its quorum, computed as `records` computes it, is not met: it was
+   * written to that state by hand, past the check of `records new` and
+   * `amend`. The record is still read, and still valid (#2878).
+   */
+  "record-ratified-below-quorum",
 ] as const satisfies readonly ReasonCode[];
 export type SealWarningCode = (typeof SEAL_WARNING_CODES)[number];
 
@@ -201,7 +209,7 @@ export interface VerdictAttestation {
 }
 
 export interface RecordWarning {
-  /** A work kind's records also carry the codes of `WORK_WARNING_CODES` (#2683), an answer kind's those of `ANSWER_WARNING_CODES` (#2739), and `records` adds `SEAL_WARNING_CODES` (#2688). */
+  /** A work kind's records also carry the codes of `WORK_WARNING_CODES` (#2683), an answer kind's those of `ANSWER_WARNING_CODES` (#2739), and `records` adds `SEAL_WARNING_CODES` (#2688, #2878). */
   code: RecordWarningCode | WorkWarningCode | SealWarningCode | AnswerWarningCode;
   message: string;
 }
@@ -618,12 +626,17 @@ export interface LoadedRecordKind {
  * Import the kind file at `path` through the path loader lexicons use (#2520).
  * The kind is registered under a name no lexicon package can have (npm names
  * hold no `:`), imported and unregistered again, so no lexicon lookup sees it.
+ *
+ * A kind file is a data-only ES module, so a `.mjs`, `.cjs` or `.js` one loads
+ * with plain node and only a TypeScript one registers tsx (#3276). That keeps
+ * `workspace ls`, `status` and `records` from paying for tsx's loader thread
+ * on every read.
  */
 export async function importKindModule(path: string): Promise<Record<string, unknown>> {
   const name = `record-kind:${path}`;
   registerLexiconDeclarations([{ name, module: path }], dirname(path));
   try {
-    const mod = await importLexiconModule(name);
+    const mod = await importLexiconModule(name, { typeScript: !/\.[cm]?js$/.test(path) });
     if (!mod) throw new Error(`${path} was not registered`);
     return mod;
   } finally {

package/src/workspace/runs.ts

@@ -55,7 +55,7 @@ import { createHash, randomBytes } from "node:crypto";
 import { readFileSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 import { z } from "zod";
-import { describeLifecyclePush, fetchLifecycleStatus, type LifecyclePushStatus, pushLifecycleStatus, readBlobBySha, RefCASConflictError, writeLedgerFiles } from "../lifecycle/git";
+import { describeLifecyclePush, fetchLifecycleStatus, ledgerRevision, type LifecyclePushStatus, pushLifecycleStatus, readBlobBySha, RefCASConflictError, writeLedgerFiles } from "../lifecycle/git";
 import { resolveMemberLedger } from "../lifecycle/member-ledger";
 import { sortedJsonReplacer } from "../utils";
 import { followSquashes, type SquashFollow } from "./squash";
@@ -509,7 +509,9 @@ async function appendRun(top: string, rootOnDisk: string, id: string, make: (exi
   let written: RunLine[] = [];
   let lastErr: unknown;
   for (let attempt = 1; attempt <= APPEND_RETRY_ATTEMPTS && commit === undefined; attempt++) {
-    const prior = git(top, ["rev-parse", "--verify", "--quiet", `refs/heads/${LEDGER_BRANCH}:${path}`])?.trim() || null;
+    // #3955: in a run that records nothing, the run's own unrecorded tip.
+    const rev = await ledgerRevision(top);
+    const prior = git(top, ["rev-parse", "--verify", "--quiet", `${rev === LEDGER_BRANCH ? `refs/heads/${LEDGER_BRANCH}` : rev}:${path}`])?.trim() || null;
     const text = prior ? ((await readBlobBySha(prior, { cwd: top })) ?? "") : "";
     const existing = parseRunFile(text, id).lines;
     const lines = make(existing);