@intentius/chant 0.101.0 → 0.104.0

package/src/workspace/decide.test.ts

@@ -10,12 +10,12 @@ import { join } from "node:path";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import { runDeclarationChecks } from "./checks";
 import { cleanScratch, commitAll, contract, REPO, repo } from "./__fixtures__/contract-repo";
-import { answerPoint, askPoint, type PointsWriteDocument } from "./decide";
+import { answerFields, answerPoint, askPoint, reasonFields, retractAnswer, type PointsWriteDocument } from "./decide";
 import pointAnswerSchema from "./point-answer.schema.json";
-import { workspacePoints } from "./points-cli";
+import { responseAsk, workspacePoints } from "./points-cli";
 import pointsSchema from "./points.schema.json";
 import pointsWriteSchema from "./points-write.schema.json";
-import type { ModelAsk, WireAnswer } from "./points";
+import { parsePoints, type ModelAsk, type WireAnswer } from "./points";
 import { queryRecords } from "./records-cli";
 
 const REF = join(REPO, "reference-workspace");
@@ -134,7 +134,7 @@ describe("points ask (#2739)", () => {
     expect(q).toMatchObject({ state: "escalated", open: true, current: true, model: { answer: "medium", confidence: 0.175, threshold: 0.8, model: "bosun-v3.1-1.7b", observed: false } });
     expect(q.escalations.map((e) => e.reason)).toEqual(["no row matches these inputs", "not observed: confidence 0.175 is below the threshold 0.8"]);
     expect(listed.questions.every((x) => x.open)).toBe(true);
-    expect(listed.points.map((p) => p.name)).toEqual(["slice-tier", "ship-skip", "finding-triage", "needs-a-decision", "needs-decision"]);
+    expect(listed.points.map((p) => p.name)).toEqual(["slice-tier", "understand", "ship-skip", "finding-triage", "needs-a-decision", "intent-origin", "intent-judgment", "intent-disposition", "agent-question", "needs-decision"]);
     expect(listed.points[0].inputs[0]).toEqual({ name: "work-item.criteria", output: "work-item", description: "acceptance criteria in the work item" });
 
     // A later ask still escalating keeps the standing record; one a model answers rewrites it, as proposed.
@@ -195,6 +195,210 @@ describe("points answer (#2739)", () => {
   });
 });
 
+describe("the model's reason (#3345)", () => {
+  const why = "Nine acceptance criteria across three services: more than a medium slice holds.";
+
+  test("a proposal keeps the model's reason, from --response too; points --json returns it, and confirming keeps it", async () => {
+    const response = { model: "bosun-v3.1-1.7b", answers: { "slice-tier": { ...confident, reason: why } } };
+    const asked = ok(await askPoint({ cwd: root, point: "slice-tier", inputs: { ...big, "work-item.criteria": 20 }, ask: responseAsk(response), on }));
+    expect(asked.question).toMatchObject({ state: "proposed", reason: why, model: { answer: "large", observed: true, reason: why } });
+    expect(fm(asked.path)).toContain(`reason: ${JSON.stringify(why)}`);
+    const listed = await workspacePoints({ cwd: root });
+    read.expectValid(listed);
+    if ("error" in listed) throw new Error(listed.error.message);
+    expect(listed.questions.find((q) => q.id === asked.id)).toMatchObject({ reason: why, model: { reason: why } });
+    const confirmed = ok(await answerPoint({ cwd: root, id: asked.id, answer: "large", by: ["alice"], on }));
+    expect(confirmed.question).toMatchObject({ state: "answered", decider: { kind: "model" }, reason: why });
+  });
+
+  test("people answering otherwise move the reason into the escalation, as model_reason", async () => {
+    const asked = ok(await askPoint({ cwd: root, point: "slice-tier", inputs: { ...big, "work-item.criteria": 21 }, ask: stub({ ...confident, reason: why }), on }));
+    const doc = ok(await answerPoint({ cwd: root, id: asked.id, answer: "medium", by: ["bob"], on }));
+    expect(doc.question).toMatchObject({ decider: { kind: "quorum" }, reason: null });
+    expect(doc.question.escalations.at(-1)).toMatchObject({ kind: "model", answer: "large", reason: "proposed large, and people answered medium", model_reason: why });
+    expect(fm(doc.path)).not.toMatch(/^reason:/m);
+  });
+
+  test("an answer below the threshold keeps its reason in the escalation, and points --json shows it on the model's answer", async () => {
+    const asked = ok(await askPoint({ cwd: root, point: "slice-tier", inputs: { ...big, "work-item.criteria": 22 }, ask: stub({ ...unsure, reason: "Could be either." }), on }));
+    expect(asked.question).toMatchObject({ state: "escalated", reason: null, model: { answer: "medium", observed: false, reason: "Could be either." } });
+    expect(asked.question.escalations[1]).toMatchObject({ kind: "model", model_reason: "Could be either." });
+    expect(ok(await askPoint({ cwd: root, point: "slice-tier", inputs: { ...big, "work-item.criteria": 23 }, ask: stub(unsure), on })).question.model).toMatchObject({ reason: null });
+  });
+
+  test("a workspace whose answer schema predates the reason keeps none, rather than failing the write", () => {
+    expect(reasonFields(pointAnswerSchema)).toEqual({ top: true, escalation: true });
+    const old = JSON.parse(JSON.stringify(pointAnswerSchema));
+    delete old.properties.reason;
+    delete old.definitions.escalation.properties.model_reason;
+    expect(reasonFields(old)).toEqual({ top: false, escalation: false });
+  });
+});
+
+describe("the intent walk's points, a note on an answer, and retracting it (#3351)", () => {
+  const walk = (node: string) => ({ "region.id": "region:app/server.mjs:1-1", "node.id": node });
+
+  test("the reference workspace declares the walk's three questions, each answered by the person walking", async () => {
+    const listed = await workspacePoints({ cwd: root });
+    read.expectValid(listed);
+    if ("error" in listed) throw new Error(listed.error.message);
+    const byName = Object.fromEntries(listed.points.map((p) => [p.name, p]));
+    expect(byName["intent-origin"]).toMatchObject({ candidates: ["carried-out-decision", "incidental", "unknown"], quorum: { count: 1 } });
+    expect(byName["intent-judgment"]).toMatchObject({ candidates: ["drift", "unwritten-supersession", "decision-wrong", "no-gap", "not-decidable"] });
+    expect(byName["intent-disposition"]).toMatchObject({ candidates: ["handled", "skipped", "needs-discussion"] });
+    for (const name of ["intent-origin", "intent-judgment", "intent-disposition"]) {
+      expect(byName[name].inputs.map((i: { name: string; output: string }) => [i.name, i.output])).toEqual([["region.id", "region"], ["node.id", "node"]]);
+      expect(byName[name].deciders.map((d: { kind: string }) => d.kind)).toEqual(["quorum"]);
+    }
+  });
+
+  test("an answer keeps its note; retracting it escalates the question again and keeps the answer, its note and why", async () => {
+    const asked = ok(await askPoint({ cwd: root, point: "intent-judgment", inputs: walk("decision:ref-001"), subject: "decision:ref-001", on }));
+    expect(asked.question).toMatchObject({ state: "escalated", open: true, note: null, retractions: [] });
+    expect(refused(await retractAnswer({ cwd: root, id: asked.id, by: ["alice"] }))).toBe("answer-not-answered");
+    const answered = ok(await answerPoint({ cwd: root, id: asked.id, answer: "drift", by: ["alice"], note: "  The port moved off 8080.  ", on }));
+    expect(answered.question).toMatchObject({ state: "answered", answer: "drift", note: "The port moved off 8080." });
+    expect(fm(answered.path)).toContain('note: "The port moved off 8080."');
+    expect(refused(await retractAnswer({ cwd: root, id: asked.id, by: ["bot"] }))).toBe("quorum-not-met");
+
+    const retracted = ok(await retractAnswer({ cwd: root, id: asked.id, by: ["alice"], note: "Wrong decision.", on: "2026-09-26" }));
+    expect(retracted.verb).toBe("retract");
+    expect(retracted.question).toMatchObject({ state: "escalated", open: true, answer: null, note: null, answeredBy: [], answeredOn: null, decider: { kind: "quorum", count: 1 } });
+    expect(retracted.question.retractions).toEqual([
+      { answer: "drift", decider: { kind: "quorum", count: 1, by: ["alice"] }, answeredBy: ["alice"], answeredOn: on, answerNote: "The port moved off 8080.", answerRelayedBy: null, by: ["alice"], on: "2026-09-26", note: "Wrong decision." },
+    ]);
+    expect(retracted.question.title).toMatch(/: open for people$/);
+    // Asking again leaves it with people.
+    expect(ok(await askPoint({ cwd: root, point: "intent-judgment", inputs: walk("decision:ref-001"), on }))).toMatchObject({ reused: true, question: { state: "escalated" } });
+
+    const again = ok(await answerPoint({ cwd: root, id: asked.id, answer: "no-gap", by: ["bob"], on: "2026-09-27" }));
+    expect(again.question).toMatchObject({ state: "answered", answer: "no-gap", note: null, answeredBy: ["bob"] });
+    expect(again.question.retractions).toHaveLength(1);
+    const listed = await workspacePoints({ cwd: root });
+    read.expectValid(listed);
+    if ("error" in listed) throw new Error(listed.error.message);
+    expect(listed.questions.find((q) => q.id === asked.id)).toMatchObject({ answer: "no-gap", retractions: [{ answer: "drift", note: "Wrong decision." }] });
+  });
+
+  test("retracting a confirmed proposal puts the model's answer back among the escalations", async () => {
+    const asked = ok(await askPoint({ cwd: root, point: "slice-tier", inputs: { ...big, "work-item.criteria": 30 }, ask: stub({ ...confident, reason: "Many criteria." }), on }));
+    ok(await answerPoint({ cwd: root, id: asked.id, answer: "large", by: ["alice"], on }));
+    const dry = ok(await retractAnswer({ cwd: root, id: asked.id, by: ["alice"], dryRun: true }));
+    expect(dry).toMatchObject({ dryRun: true, written: false, question: { state: "escalated" } });
+    expect(fm(asked.path)).toMatch(/^state: "answered"$/m);
+    const doc = ok(await retractAnswer({ cwd: root, id: asked.id, by: ["alice"], on }));
+    expect(doc.question).toMatchObject({ state: "escalated", decider: { kind: "quorum" }, probabilities: null, confidence: null, reason: null });
+    expect(doc.question.retractions[0]).toMatchObject({ answer: "large", decider: { kind: "model", model: "bosun-v3.1-1.7b" } });
+    expect(doc.question.escalations.at(-1)).toMatchObject({ kind: "model", answer: "large", reason: "proposed large, which people confirmed and then retracted", model_reason: "Many criteria." });
+  });
+
+  test("a workspace whose answer schema predates notes and retractions refuses them, rather than dropping them", () => {
+    expect(answerFields(pointAnswerSchema)).toEqual({ note: true, retractions: true, relayedBy: true, asked: true });
+    const old = JSON.parse(JSON.stringify(pointAnswerSchema));
+    delete old.properties.note;
+    delete old.properties.retractions;
+    delete old.properties.relayed_by;
+    delete old.properties.asked;
+    expect(answerFields(old)).toEqual({ note: false, retractions: false, relayedBy: false, asked: false });
+  });
+
+  test("an answer relayed for a person records who relayed it, and a retraction keeps it (#3402)", async () => {
+    const asked = ok(await askPoint({ cwd: root, point: "intent-origin", inputs: walk("decision:ref-002"), on }));
+    expect(asked.question).toMatchObject({ relayedBy: null });
+    const answered = ok(await answerPoint({ cwd: root, id: asked.id, answer: "incidental", by: ["alice"], relayedBy: " follower:hud-player-7 ", on }));
+    expect(answered.question).toMatchObject({ state: "answered", answeredBy: ["alice"], relayedBy: "follower:hud-player-7" });
+    expect(fm(answered.path)).toContain('relayed_by: "follower:hud-player-7"');
+    const retracted = ok(await retractAnswer({ cwd: root, id: asked.id, by: ["alice"], on: "2026-09-26" }));
+    expect(retracted.question).toMatchObject({ relayedBy: null, retractions: [{ answer: "incidental", answeredBy: ["alice"], answerRelayedBy: "follower:hud-player-7" }] });
+    expect(fm(asked.path)).toContain('answer_relayed_by: "follower:hud-player-7"');
+  });
+});
+
+describe("an ad-hoc question whose candidates come with the ask (#3403)", () => {
+  const room = {
+    question: "Which language should the importer be written in?",
+    criteria: { ts: "TypeScript: matches the rest of the repo.", py: "Python: the parser library is better." },
+  };
+
+  test("the reference workspace declares agent-question, ad hoc and decided by one person", async () => {
+    const listed = await workspacePoints({ cwd: root });
+    read.expectValid(listed);
+    if ("error" in listed) throw new Error(listed.error.message);
+    const p = listed.points.find((x) => x.name === "agent-question")!;
+    expect(p).toMatchObject({ adhoc: true, questionType: "choice", candidates: [], criteria: {}, quorum: { count: 1 } });
+    expect(p.inputs.map((i) => [i.name, i.output])).toEqual([["ask.id", "ask"], ["ask.by", "ask"]]);
+    expect(listed.points.find((x) => x.name === "slice-tier")).toMatchObject({ adhoc: false });
+  });
+
+  test("the ask keeps the question and candidates; the answer is checked against them, noted, retracted and answered again", async () => {
+    const inputs = { "ask.id": "req-1", "ask.by": "hud:session-7" };
+    const asked = ok(await askPoint({ cwd: root, point: "agent-question", inputs, candidates: room, subject: "hud:session-7", on }));
+    expect(asked.question).toMatchObject({
+      state: "escalated",
+      open: true,
+      point: "agent-question",
+      title: "Which language should the importer be written in? (hud:session-7): open for people",
+      candidates: ["ts", "py"],
+      asked: room,
+      decider: { kind: "quorum", count: 1 },
+    });
+    const text = fm(asked.path);
+    expect(text).toContain('asked:\n  question: "Which language should the importer be written in?"');
+    expect(text).toContain("- ts: TypeScript: matches the rest of the repo.");
+
+    // The same ask returns the same question; other options are another question.
+    expect(ok(await askPoint({ cwd: root, point: "agent-question", inputs, candidates: room, on }))).toMatchObject({ reused: true, id: asked.id });
+    const other = ok(await askPoint({ cwd: root, point: "agent-question", inputs, candidates: { ...room, criteria: { ...room.criteria, go: "Go." } }, on, dryRun: true }));
+    expect(other.id).not.toBe(asked.id);
+
+    expect(refused(await answerPoint({ cwd: root, id: asked.id, answer: "rust", by: ["alice"] }))).toBe("answer-not-candidate");
+    const answered = ok(await answerPoint({ cwd: root, id: asked.id, answer: "py", by: ["alice"], note: "The parser decides it.", on }));
+    expect(answered.question).toMatchObject({ state: "answered", answer: "py", answeredBy: ["alice"], note: "The parser decides it.", asked: room, title: "Which language should the importer be written in? (hud:session-7): py" });
+    const retracted = ok(await retractAnswer({ cwd: root, id: asked.id, by: ["alice"], note: "Asked too early.", on }));
+    expect(retracted.question).toMatchObject({ state: "escalated", asked: room, retractions: [{ answer: "py" }] });
+    ok(await answerPoint({ cwd: root, id: asked.id, answer: "ts", by: ["bob"], on }));
+
+    const listed = await workspacePoints({ cwd: root });
+    read.expectValid(listed);
+    if ("error" in listed) throw new Error(listed.error.message);
+    expect(listed.questions.find((q) => q.id === asked.id)).toMatchObject({ state: "answered", answer: "ts", answeredBy: ["bob"], asked: room, candidates: ["ts", "py"] });
+    expect(listed.questions.find((q) => q.point === "slice-tier")).toMatchObject({ asked: null });
+  });
+
+  test("refusals: no candidates for an ad-hoc point, candidates for a declared one, candidates that don't fit", async () => {
+    const inputs = { "ask.id": "req-2" };
+    expect(refused(await askPoint({ cwd: root, point: "agent-question", inputs }))).toBe("point-candidates-invalid");
+    expect(refused(await askPoint({ cwd: root, point: "slice-tier", inputs: { "work-item.fits_small": true }, candidates: room }))).toBe("point-candidates-invalid");
+    for (const bad of [[], { question: "Which?", criteria: { only: "One option." } }, { question: "", criteria: room.criteria }, { ...room, extra: 1 }, { question: "Which?", criteria: ["a", "b"] }]) {
+      const doc = await askPoint({ cwd: root, point: "agent-question", inputs, candidates: bad });
+      expect(refused(doc)).toBe("point-candidates-invalid");
+    }
+  });
+
+  test("an ad-hoc point leaves out criteria and is decided by one quorum", () => {
+    const base = { title: "Ad hoc", adhoc: true, question: { type: "choice", instructions: "Asked at runtime." }, inputs: { "ask.id": "the ask" } };
+    expect(() => parsePoints(JSON.stringify({ points: { a: { ...base, deciders: [{ kind: "quorum", count: 1 }] } } }), "points.json")).not.toThrow();
+    expect(() => parsePoints(JSON.stringify({ points: { a: { ...base, question: { ...base.question, criteria: { x: "X", y: "Y" } }, deciders: [{ kind: "quorum", count: 1 }] } } }), "points.json")).toThrow(/leave criteria out/);
+    expect(() =>
+      parsePoints(JSON.stringify({ points: { a: { ...base, deciders: [{ kind: "model", backend: "systemone", model: "jev-1.13.0", threshold: 0.8 }, { kind: "quorum", count: 1 }] } } }), "points.json"),
+    ).toThrow(/decided by people alone/);
+    expect(() => parsePoints(JSON.stringify({ points: { a: { ...base, adhoc: false, deciders: [{ kind: "quorum", count: 1 }] } } }), "points.json")).toThrow(/criteria/);
+  });
+
+  test("a workspace whose answer schema predates asked refuses an ad-hoc ask, rather than dropping the question", async () => {
+    const schemaFile = join(root, "answers", "answer.schema.json");
+    const original = readFileSync(schemaFile, "utf-8");
+    const old = JSON.parse(original);
+    delete old.properties.asked;
+    writeFileSync(schemaFile, JSON.stringify(old, null, 2));
+    try {
+      expect(refused(await askPoint({ cwd: root, point: "agent-question", inputs: { "ask.id": "req-3" }, candidates: room }))).toBe("answer-field-unsupported");
+    } finally {
+      writeFileSync(schemaFile, original);
+    }
+  });
+});
+
 describe("the points file in check and on read (#2738)", () => {
   test("a changed point warns on its answers, and an invalid points file is WSP116 and a points-invalid source", async () => {
     const file = join(root, "decisions", "points.json");