@intentius/chant 0.102.0 → 0.104.0

package/src/workspace/points-cli.ts

@@ -11,7 +11,8 @@
  * can see it. With `--open`, only open questions are listed. It never writes
  * and never calls a model.
  *
- * `points ask` and `points answer` are the writes, in `decide.ts`.
+ * `points ask`, `points answer` and `points retract` are the writes, in
+ * `decide.ts`.
  */
 
 import { readFileSync } from "node:fs";
@@ -20,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, POINTS_WRITE_CONTRACT_VERSION, POINTS_WRITE_SCHEMA_ID, type PointsWriteDocument, type QuestionView } from "./decide";
+import { answerPoint, askPoint, questionView, retractAnswer, 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";
@@ -71,8 +72,14 @@ export interface PointView {
   questionType: string;
   instructions: string;
   candidates: (string | boolean)[];
-  /** What each candidate means, as the points file declares it: an object of strings for noul and choice, an array for score. */
+  /**
+   * What each candidate means, as the points file declares it: an object of
+   * strings for noul and choice, an array for score. Empty for an ad-hoc point,
+   * whose candidates come with each ask (#3403).
+   */
   criteria: Record<string, string> | string[];
+  /** The question's text and candidates come with each ask (#3403): each question lists them as `asked`. */
+  adhoc: boolean;
   /** Each input: its name, the read-contract output it names, and its description. */
   inputs: { name: string; output: string; description: string }[];
   deciders: Decider[];
@@ -164,8 +171,9 @@ export async function workspacePoints(query: PointsQuery): Promise<PointsDocumen
           version: pointVersion(p),
           questionType: p.question.type,
           instructions: p.question.instructions,
-          candidates: candidates(p.question),
-          criteria: p.question.criteria,
+          candidates: p.adhoc ? [] : candidates(p.question),
+          criteria: p.question.criteria ?? (p.question.type === "score" ? [] : {}),
+          adhoc: !!p.adhoc,
           inputs: Object.entries(p.inputs).map(([n, description]) => ({ name: n, output: inputOutput(n), description })),
           deciders: p.deciders,
           quorum: quorumOf(p),
@@ -215,7 +223,7 @@ export async function readQuestionStates(cwd: string): Promise<Map<string, Quest
 export function formatPoints(doc: Extract<PointsDocument, { points: unknown }>): string {
   const lines: string[] = [];
   for (const s of doc.sources) if (s.reason) lines.push(`${s.kind}: ${s.reason.code}: ${s.reason.message}`);
-  for (const p of doc.points) lines.push(`${p.name}  ${p.questionType}  ${p.title}  (${p.deciders.map((d) => d.kind).join(", ")})`);
+  for (const p of doc.points) lines.push(`${p.name}  ${p.questionType}${p.adhoc ? ", ad hoc" : ""}  ${p.title}  (${p.deciders.map((d) => d.kind).join(", ")})`);
   if (doc.points.length === 0) lines.push("no decision points are declared");
   lines.push("");
   for (const q of doc.questions) {
@@ -241,18 +249,23 @@ export function responseAsk(response: unknown): ModelAsk {
 
 const USAGE = [
   "chant workspace points [--open] [--kind <kind file>] [--at <rev>] [--json]",
-  "chant workspace points ask <point> --inputs <file|-> [--response <file>] [--subject <id>] [--kind <kind file>] [--dry-run]",
-  "chant workspace points answer <id> --answer <value> --by <name> [--by <name>...] [--kind <kind file>] [--dry-run]",
+  "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>] [--dry-run]",
+  "chant workspace points retract <id> --by <name> [--by <name>...] [--note <text>] [--kind <kind file>] [--dry-run]",
 ].join("\n");
 
-function usage(verb: "ask" | "answer", message: string): PointsWriteDocument {
+function usage(verb: PointsWriteVerb, message: string): PointsWriteDocument {
   return { $schema: POINTS_WRITE_SCHEMA_ID, contract: POINTS_WRITE_CONTRACT_VERSION, verb, error: { code: "write-usage-invalid", message } };
 }
 
-function readJson(verb: "ask" | "answer", flag: string, value: string, cwd: string): { value: unknown } | PointsWriteDocument {
+/** Whether a flag's value is the JSON itself rather than a file: it starts with { or [ (#3403). */
+const inlineJson = (value: string): boolean => /^\s*[[{]/.test(value);
+
+/** A flag's JSON: from standard input (-), the value itself when it starts with { or [, or a file. */
+function readJson(verb: PointsWriteVerb, flag: string, value: string, cwd: string): { value: unknown } | PointsWriteDocument {
   let text: string;
   try {
-    text = readFileSync(value === "-" ? 0 : resolve(cwd, value), "utf-8");
+    text = inlineJson(value) ? value : readFileSync(value === "-" ? 0 : resolve(cwd, value), "utf-8");
   } catch (err) {
     return { $schema: POINTS_WRITE_SCHEMA_ID, contract: POINTS_WRITE_CONTRACT_VERSION, verb, error: { code: "write-input-invalid", message: `${flag} ${value} could not be read: ${err instanceof Error ? err.message : String(err)}` } };
   }
@@ -263,7 +276,7 @@ function readJson(verb: "ask" | "answer", flag: string, value: string, cwd: stri
   }
 }
 
-/** `chant workspace points`, and its `ask` and `answer` verbs. */
+/** `chant workspace points`, and its `ask`, `answer` and `retract` verbs. */
 export async function runWorkspacePoints(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
   const cwd = process.cwd();
@@ -275,26 +288,39 @@ export async function runWorkspacePoints(ctx: CommandContext): Promise<number> {
   if (verb === "ask") {
     const point = args.extraPositional2;
     if (!point) return print(usage("ask", "ask needs the point's name"));
-    if (args.inputs === undefined) return print(usage("ask", "--inputs <file|-> is required"));
+    if (args.inputs === undefined) return print(usage("ask", "--inputs <file|-|json> is required"));
+    if (args.inputs === "-" && args.candidates === "-") return print(usage("ask", "--inputs and --candidates can't both read standard input: give one as a file or as JSON"));
     const inputs = readJson("ask", "--inputs", args.inputs, cwd);
     if (!("value" in inputs)) return print(inputs);
+    let given: unknown;
+    if (args.candidates !== undefined) {
+      const read = readJson("ask", "--candidates", args.candidates, cwd);
+      if (!("value" in read)) return print(read);
+      given = read.value;
+    }
     let ask: ModelAsk | undefined;
     if (args.response !== undefined) {
       const response = readJson("ask", "--response", args.response, cwd);
       if (!("value" in response)) return print(response);
       ask = responseAsk(response.value);
     }
-    return print(await askPoint({ cwd, point, inputs: inputs.value, subject: args.subject, kind: args.kind, ask, dryRun: args.dryRun }));
+    return print(await askPoint({ cwd, point, inputs: inputs.value, candidates: given, subject: args.subject, kind: args.kind, ask, dryRun: args.dryRun }));
   }
   if (verb === "answer") {
     const id = args.extraPositional2;
     if (!id) return print(usage("answer", "answer needs the question's id"));
     if (args.answer === undefined) return print(usage("answer", "--answer <value> is required"));
     if (!args.bys || args.bys.length === 0) return print(usage("answer", "--by <name> is required, once for each person who answered"));
-    return print(await answerPoint({ cwd, id, answer: args.answer, by: args.bys, kind: args.kind, dryRun: args.dryRun }));
+    return print(await answerPoint({ cwd, id, answer: args.answer, by: args.bys, note: args.note, relayedBy: args.relayedBy, kind: args.kind, dryRun: args.dryRun }));
+  }
+  if (verb === "retract") {
+    const id = args.extraPositional2;
+    if (!id) return print(usage("retract", "retract needs the question's id"));
+    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 !== undefined) {
-    console.error(formatError({ message: `chant workspace points takes no argument but ask or answer (got ${verb})`, hint: USAGE }));
+    console.error(formatError({ message: `chant workspace points takes no argument but ask, answer or retract (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

@@ -1,8 +1,8 @@
 {
   "$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 and answer output",
-  "description": "What `chant workspace points ask` and `points answer` print (ws-058, #2739): 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. 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.",
+  "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.",
   "oneOf": [
     {
       "$ref": "#/$defs/result"
@@ -37,7 +37,8 @@
         "verb": {
           "enum": [
             "ask",
-            "answer"
+            "answer",
+            "retract"
           ]
         },
         "kind": {
@@ -235,6 +236,13 @@
             }
           ]
         },
+        "reason": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The model's own explanation of the recorded answer, a proposal or a confirmed proposal, when the backend gave one (#3345). null otherwise, and from a chant before it."
+        },
         "model": {
           "description": "Any model answer: the proposal (observed), or the last answer below a model decider's threshold (not observed). null when no model answered.",
           "oneOf": [
@@ -303,6 +311,13 @@
                 },
                 "observed": {
                   "type": "boolean"
+                },
+                "reason": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "The model's explanation of this answer, when the backend gave one (#3345)."
                 }
               }
             }
@@ -362,6 +377,10 @@
                 "type": "number",
                 "minimum": 0,
                 "maximum": 1
+              },
+              "model_reason": {
+                "type": "string",
+                "description": "A model decider's own explanation of the answer it gave, when the backend gave one (#3345). reason is why the decider did not answer."
               }
             }
           }
@@ -391,6 +410,139 @@
             "null"
           ]
         },
+        "note": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "What the people who answered wrote with their answer (points answer --note, #3351). null when they wrote nothing, and from a chant before it."
+        },
+        "relayedBy": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Who relayed the answer to chant for the people who gave it (points answer --relayed-by, #3402), such as a follower relaying a person's answer through hud. null when nobody did, and from a chant before it."
+        },
+        "retractions": {
+          "type": "array",
+          "description": "Answers people took back, oldest first (points retract, #3351): each answer as it was and who retracted it, when and why. A retracted question is escalated to people again. Empty when none was, and absent from a chant before it.",
+          "items": {
+            "type": "object",
+            "required": [
+              "answer",
+              "decider",
+              "answeredBy",
+              "answeredOn",
+              "answerNote",
+              "answerRelayedBy",
+              "by",
+              "on",
+              "note"
+            ],
+            "properties": {
+              "answer": {
+                "oneOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "boolean"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "decider": {
+                "type": "object",
+                "description": "Who gave the answer: the record's decider as it was."
+              },
+              "answeredBy": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "answeredOn": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "answerNote": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "The note the answer carried."
+              },
+              "answerRelayedBy": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "Who relayed the answer (#3402)."
+              },
+              "by": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Who retracted it."
+              },
+              "on": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "note": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "Why it was retracted (points retract --note)."
+              }
+            }
+          }
+        },
+        "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": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "question",
+                "criteria"
+              ],
+              "properties": {
+                "question": {
+                  "type": "string"
+                },
+                "criteria": {
+                  "oneOf": [
+                    {
+                      "type": "object",
+                      "additionalProperties": {
+                        "type": "string"
+                      }
+                    },
+                    {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          ]
+        },
         "valid": {
           "type": "boolean"
         },
@@ -445,7 +597,8 @@
         "verb": {
           "enum": [
             "ask",
-            "answer"
+            "answer",
+            "retract"
           ]
         },
         "error": {
@@ -474,6 +627,11 @@
                 "quorum-not-met",
                 "answer-in-steward-turn",
                 "principal-unidentified",
+                "answer-not-answered",
+                "answer-field-unsupported",
+                "point-candidates-invalid",
+                "write-lock-timeout",
+                "write-lock-not-held",
                 "record-not-found",
                 "record-closed",
                 "record-id-taken",

package/src/workspace/points.schema.json

@@ -238,7 +238,7 @@
           }
         },
         "criteria": {
-          "description": "What each candidate means, as the points file declares it: noul and choice give an object of strings keyed by candidate, score an array of ordered level descriptions.",
+          "description": "What each candidate means, as the points file declares it: noul and choice give an object of strings keyed by candidate, score an array of ordered level descriptions. Empty for an ad-hoc point (#3403).",
           "oneOf": [
             {
               "type": "object",
@@ -254,6 +254,10 @@
             }
           ]
         },
+        "adhoc": {
+          "type": "boolean",
+          "description": "An ad-hoc point (#3403): the question's text and candidates come with each ask, and each question lists them as asked. Its candidates are empty and its criteria an empty object, or an empty array for a score. Absent from a chant before it."
+        },
         "inputs": {
           "type": "array",
           "items": {
@@ -269,7 +273,7 @@
               },
               "output": {
                 "type": "string",
-                "description": "The read-contract output the input names: record, decision, work-item, finding, region, commit, member, gate, release, environment or component."
+                "description": "The read-contract output the input names: record, decision, work-item, finding, region, commit, node, member, gate, release, environment, component or ask."
               },
               "description": {
                 "type": "string"
@@ -464,6 +468,13 @@
             }
           ]
         },
+        "reason": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The model's own explanation of the recorded answer, a proposal or a confirmed proposal, when the backend gave one (#3345). null otherwise, and from a chant before it."
+        },
         "model": {
           "description": "Any model answer: the proposal (observed), or the last answer below a model decider's threshold (not observed). null when no model answered.",
           "oneOf": [
@@ -532,6 +543,13 @@
                 },
                 "observed": {
                   "type": "boolean"
+                },
+                "reason": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "The model's explanation of this answer, when the backend gave one (#3345)."
                 }
               }
             }
@@ -591,6 +609,10 @@
                 "type": "number",
                 "minimum": 0,
                 "maximum": 1
+              },
+              "model_reason": {
+                "type": "string",
+                "description": "A model decider's own explanation of the answer it gave, when the backend gave one (#3345). reason is why the decider did not answer."
               }
             }
           }
@@ -646,6 +668,139 @@
             "null"
           ]
         },
+        "note": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "What the people who answered wrote with their answer (points answer --note, #3351). null when they wrote nothing, and from a chant before it."
+        },
+        "relayedBy": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Who relayed the answer to chant for the people who gave it (points answer --relayed-by, #3402), such as a follower relaying a person's answer through hud. null when nobody did, and from a chant before it."
+        },
+        "retractions": {
+          "type": "array",
+          "description": "Answers people took back, oldest first (points retract, #3351): each answer as it was and who retracted it, when and why. A retracted question is escalated to people again. Empty when none was, and absent from a chant before it.",
+          "items": {
+            "type": "object",
+            "required": [
+              "answer",
+              "decider",
+              "answeredBy",
+              "answeredOn",
+              "answerNote",
+              "answerRelayedBy",
+              "by",
+              "on",
+              "note"
+            ],
+            "properties": {
+              "answer": {
+                "oneOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "boolean"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "decider": {
+                "type": "object",
+                "description": "Who gave the answer: the record's decider as it was."
+              },
+              "answeredBy": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "answeredOn": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "answerNote": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "The note the answer carried."
+              },
+              "answerRelayedBy": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "Who relayed the answer (#3402)."
+              },
+              "by": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Who retracted it."
+              },
+              "on": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "note": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "Why it was retracted (points retract --note)."
+              }
+            }
+          }
+        },
+        "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": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "question",
+                "criteria"
+              ],
+              "properties": {
+                "question": {
+                  "type": "string"
+                },
+                "criteria": {
+                  "oneOf": [
+                    {
+                      "type": "object",
+                      "additionalProperties": {
+                        "type": "string"
+                      }
+                    },
+                    {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          ]
+        },
         "valid": {
           "type": "boolean"
         },

package/src/workspace/points.test.ts

@@ -143,7 +143,7 @@ describe("the decision points schema (#2738)", () => {
 
   test("the reference workspace's points validate", () => {
     const points = parsePoints(readFileSync(join(REPO, "reference-workspace", "decisions", "points.json"), "utf-8"), "decisions/points.json");
-    expect(Object.keys(points)).toEqual(["slice-tier", "ship-skip", "finding-triage", "needs-a-decision"]);
+    expect(Object.keys(points)).toEqual(["slice-tier", "understand", "ship-skip", "finding-triage", "needs-a-decision", "intent-origin", "intent-judgment", "intent-disposition", "agent-question"]);
   });
 
   test("a point whose chain does not end in a quorum is refused", () => {
@@ -232,6 +232,18 @@ describe("the decider chain (#2739)", () => {
     expect(r.escalations[1]).toMatchObject({ kind: "model", answer: "medium", confidence: 0.25, threshold: 0.8, reason: "not observed: confidence 0.25 is below the threshold 0.8" });
   });
 
+  test("the model's reason is kept with a proposal, and in the escalation of an answer below the threshold (#3345)", async () => {
+    const proposed = await runChain("slice-tier", SLICE, big, stub({ type: "choice", choice: "large", probabilities: { large: 0.9 }, confidence: 0.9, reason: "  Nine criteria across three services.\n" }));
+    expect(proposed).toMatchObject({ status: "proposed", reason: "Nine criteria across three services." });
+    const low = await runChain("n", NOUL, {}, stub({ type: "noul", noul: 0.6, reason: "Probably, but the diff is small." }));
+    expect(low.escalations[0]).toMatchObject({ kind: "model", answer: true, reason: "not observed: confidence 0.6 is below the threshold 0.8", model_reason: "Probably, but the diff is small." });
+    // A blank or non-string reason is no reason.
+    const blank = await runChain("slice-tier", SLICE, big, stub({ type: "choice", choice: "large", confidence: 0.9, reason: "  " }));
+    expect(blank).not.toHaveProperty("reason");
+    const odd = await runChain("slice-tier", SLICE, big, stub({ type: "choice", choice: "large", confidence: 0.9, reason: 3 } as unknown as WireAnswer));
+    expect(odd).not.toHaveProperty("reason");
+  });
+
   test("without a backend, or with an unpinned model answering, the model is not asked or not observed", async () => {
     expect((await runChain("slice-tier", SLICE, big)).escalations[1].reason).toBe("not asked: no model backend was given to this ask");
     const r = await runChain("slice-tier", SLICE, big, stub({ type: "choice", choice: "large", confidence: 0.99 }, "bosun-latest"));