@intentius/chant 0.84.0 → 0.85.0

package/src/workspace/intent.ts

@@ -22,24 +22,28 @@
  *   the graph pins it.
  *
  * Every gap the walk finds is a `finding` node with a closed code, never
- * prose, so a reader can draw it and a test can assert it. chant emits the
+ * prose, so a reader can draw it and a test can assert it. A commit made
+ * inside a decision's window is not taken as that decision's work: unless
+ * the decision's own unit made it, it is `decided-by-window`, shown for the
+ * person to judge (#2656). A plugin's `commitJoins` may add findings of its
+ * own, in its own code namespace. chant emits the
  * graph and hud renders it (#2524 D8, D15). Git is read through a local
  * `git` subprocess only: no fetch, no network.
  */
 
 import { execFileSync } from "node:child_process";
 import { realpathSync } from "node:fs";
-import { relative, resolve, sep } from "node:path";
+import { basename, relative, resolve, sep } from "node:path";
 import { readDeclaration, readerVersion, resolveGroups, WORKSPACE_ERROR_CODES, WorkspaceReadError, type Declaration } from "./declaration";
 import { classifyFile, declaredFilesUnder } from "./generated-files";
-import { hasTrailer, readCommitJoins, runCommitJoins, type CommitJoins, type IntentCommit, type JoinedEntity } from "./intent-joins";
+import { entityDecisions, hasTrailer, readCommitJoins, runCommitJoins, type CommitJoins, type IntentCommit, type JoinedEntity, type PluginFinding } from "./intent-joins";
 import { loadKindRegistry } from "./kinds";
 import { resolveLinks, type LinkTableRow } from "./links";
 import { sourceMemberHandles } from "./member-handles";
 import { constraintCovers, isWorkspacePath, memberHolding } from "./record-assets";
 import { importKindModule, loadRecordKind, RecordReadError, type LoadedRecordKind } from "./records";
 import { queryRecords, type RecordView } from "./records-cli";
-import type { ReasonCode } from "./reason-codes";
+import type { PluginCode, ReasonCode } from "./reason-codes";
 import { joinPath, skippedDir, type WorkspaceTree } from "./tree";
 import { activeAttestors, type ProvenanceLevel } from "./trust/attestor";
 import { commitProvenance, policyAtBase, resolveBase } from "./trust/provenance";
@@ -167,8 +171,18 @@ export interface CommitNode {
   signature: { level: ProvenanceLevel; reason: string; principal?: string };
   /** The line ranges the commit changed in the region, in the commit's own version of the file; null for a file or directory region. */
   lines: LineRange[] | null;
+  /**
+   * How the decisions constraining the region by path relate to the commit
+   * (#2656): `decided` when it falls inside a decision's window and that
+   * decision's own unit made it, `decided-by-window` when it only falls
+   * inside a window, `undecided` when it falls outside every window, and
+   * null when no record kind was read.
+   */
+  state: CommitState | null;
 }
 
+export type CommitState = "decided" | "decided-by-window" | "undecided";
+
 export interface JoinedNode {
   id: string;
   kind: "unit" | "contract" | "evidence";
@@ -237,9 +251,14 @@ export interface LinkNode {
 export interface FindingNode {
   id: string;
   kind: "finding";
-  code: IntentFindingCode;
+  /** A closed code, or a plugin's own `plugin:<name>:<code>` (#2656). */
+  code: IntentFindingCode | PluginCode;
   message: string;
   concerns: string[];
+  /** For a plugin's finding: the kind file that returned it. */
+  plugin?: string;
+  /** For a plugin's finding: the refs as the plugin gave them. The ones that name a node in the graph are in concerns. */
+  refs?: string[];
 }
 
 export type IntentNode = RegionNode | FileNode | MemberNode | CommitNode | JoinedNode | EvidenceEntryNode | DecisionNode | ArtifactNode | LinkNode | FindingNode;
@@ -250,6 +269,7 @@ export type IntentEdge =
   | { kind: "constrains"; from: string; to: string; granularity: Granularity; entry: string }
   | { kind: "pins"; from: string; to: string; pinnedSha256: string | null; pinState: PinState }
   | { kind: "touched-by"; from: string; to: string; lines: LineRange[] | null }
+  | { kind: "within"; from: string; to: string; state: "decided" | "decided-by-window" }
   | { kind: "produced-by" | "serves" | "cites-evidence" | "supersedes" | "links"; from: string; to: string };
 
 export interface IntentReason {
@@ -269,7 +289,7 @@ export type IntentDocument =
       workspace: { name: string; root: string };
       region: string;
       history: { rev: string | null; follows: "line-range" | "file" | "directory"; shallow: boolean };
-      kinds: { file: string; records: string | null; joins: "function" | "data" | null }[];
+      kinds: { file: string; name: string; records: string | null; joins: "function" | "data" | null }[];
       nodes: IntentNode[];
       edges: IntentEdge[];
       reasons: IntentReason[];
@@ -486,6 +506,8 @@ interface LoadedKind {
   file: string;
   /** Relative to the repository root, for the document. */
   display: string;
+  /** The record kind's name, or the file's name without `.kind.mjs`: the namespace of its plugin findings. */
+  name: string;
   records?: { loaded: LoadedRecordKind; views: RecordView[]; workspaceRoot: string };
   joins?: CommitJoins;
 }
@@ -503,12 +525,13 @@ async function loadKinds(query: IntentQuery, top: string): Promise<LoadedKind[]>
     }
     const joins = readCommitJoins(mod);
     if (typeof joins === "string") throw new IntentError("kind-invalid", `kind file ${k} has a commitJoins export that can't be read: ${joins}`);
-    const kind: LoadedKind = { file, display, ...(joins ? { joins } : {}) };
+    const kind: LoadedKind = { file, display, name: basename(file).replace(/(?:\.kind)?\.[cm]?[jt]s$/, ""), ...(joins ? { joins } : {}) };
     if (mod.recordKind !== undefined) {
       const doc = await queryRecords({ kind: file, at: query.at, cwd: query.cwd });
       if ("error" in doc) throw new IntentError(doc.error.code, doc.error.message);
       try {
         kind.records = { loaded: await loadRecordKind(file), views: doc.records, workspaceRoot: doc.workspaceRoot };
+        kind.name = kind.records.loaded.kind.name;
       } catch (err) {
         if (err instanceof RecordReadError) throw new IntentError(err.code as IntentErrorCode, err.message);
         throw err;
@@ -611,7 +634,15 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
     if (!isWorkspacePath(path) || located.tree.stat(path) !== "file") return undefined;
     return located.tree.read(path);
   };
-  const joined = new Map<string, { unit?: string; contracts: string[]; authorship: string[] }>();
+  interface Joined {
+    unit?: string;
+    contracts: string[];
+    authorship: string[];
+    /** The record ids the commit's units and contracts say they carry out. */
+    decisions: string[];
+  }
+  const joined = new Map<string, Joined>();
+  const pluginFindings: { commit: string; plugin: string; finding: PluginFinding }[] = [];
   const failedPlugins = new Set<string>();
   for (const t of touched) {
     const c = details.get(t.sha);
@@ -624,17 +655,17 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
       : { level: "unattested" as const, reason: policy.problems.length ? policy.problems.join("; ") : `no signers file (${policy.signersPath}) at base; attestation is off` };
     const pr = c.subject.match(/\(#([0-9]+)\)\s*$/);
     const cid = `commit:${c.sha}`;
-    add<CommitNode>({ id: cid, kind: "commit", sha: c.sha, subject: c.subject, author: c.author, date: c.date, trailers: c.trailers, pullRequest: pr ? Number(pr[1]) : null, signature, lines: t.lines });
+    add<CommitNode>({ id: cid, kind: "commit", sha: c.sha, subject: c.subject, author: c.author, date: c.date, trailers: c.trailers, pullRequest: pr ? Number(pr[1]) : null, signature, lines: t.lines, state: null });
     edges.push({ kind: "touched-by", from: rid, to: cid, lines: t.lines });
 
     // 2. Each commit's origin, from the plugins.
-    const entry = { contracts: [] as string[], authorship: [] as string[] } as { unit?: string; contracts: string[]; authorship: string[] };
+    const entry: Joined = { contracts: [], authorship: [], decisions: [] };
     joined.set(c.sha, entry);
     for (const k of kinds) {
       if (!k.joins) continue;
       let result;
       try {
-        result = await runCommitJoins(k.joins, c, { read: readAt, at: located.at });
+        result = await runCommitJoins(k.joins, c, { read: readAt, at: located.at }, k.name);
       } catch (err) {
         const message = `${k.display}: commitJoins failed for ${c.sha.slice(0, 8)}: ${err instanceof Error ? err.message : String(err)}`;
         if (!failedPlugins.has(message)) reasons.push({ code: "intent-plugin-failed", message });
@@ -653,6 +684,8 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
         if (contractId) edges.push({ kind: "serves", from: unitId, to: contractId });
       }
       if (contractId) entry.contracts.push(result.contract!.id);
+      if (unitId) entry.decisions.push(...entityDecisions(result.unit), ...entityDecisions(result.contract));
+      for (const f of result.findings ?? []) pluginFindings.push({ commit: cid, plugin: k.display, finding: f });
       const evidence = result.evidence === undefined ? [] : Array.isArray(result.evidence) ? result.evidence : [result.evidence];
       for (const e of evidence) edges.push({ kind: "cites-evidence", from: unitId ?? contractId ?? cid, to: joinedNode("evidence", e) });
       entry.authorship.push(...(result.authorship ?? []));
@@ -859,11 +892,20 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
       return !!w && w.from.has(sha) && !w.until?.has(sha);
     });
   const readsRecords = kinds.some((k) => k.records);
+  // A decision's own work: a commit whose unit, or that unit's contract, names
+  // the decision, or whose unit serves a contract the decision constrains.
+  const ownWork = (j: Joined, d: DecisionNode) =>
+    !!j.unit && (j.decisions.some((x) => x === d.record || x === `${d.recordKind}/${d.record}`) || d.constrains.some((x) => x.granularity === "contract" && j.contracts.includes(x.entry)));
   for (const t of touched) {
     const c = nodes.get(`commit:${t.sha}`) as CommitNode | undefined;
     if (!c) continue;
     const j = joined.get(t.sha)!;
-    if (readsRecords && coveredAt(t.sha, ["path"]).length === 0) {
+    if (readsRecords) {
+      const inWindow = coveredAt(t.sha, ["path"]);
+      for (const w of inWindow) edges.push({ kind: "within", from: c.id, to: w.node.id, state: ownWork(j, w.node) ? "decided" : "decided-by-window" });
+      c.state = inWindow.length === 0 ? "undecided" : inWindow.some((w) => ownWork(j, w.node)) ? "decided" : "decided-by-window";
+    }
+    if (readsRecords && c.state === "undecided") {
       find("intent-commit-undecided", `${t.sha.slice(0, 8)} changed the region when no decision constrained ${region.path} by path`, [c.id, rid]);
     }
     if (readsRecords && !j.unit && c.pullRequest === null && coveredAt(t.sha, ["path", "member", "contract", "issue"]).length === 0) {
@@ -915,7 +957,23 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
   }
 
   // Findings last, in the order of the code list, so the same walk always prints the same way.
-  findings.sort((x, y) => INTENT_FINDING_CODES.indexOf(x.code) - INTENT_FINDING_CODES.indexOf(y.code));
+  findings.sort((x, y) => INTENT_FINDING_CODES.indexOf(x.code as IntentFindingCode) - INTENT_FINDING_CODES.indexOf(y.code as IntentFindingCode));
+  // Then the plugins' findings, in commit order, each about its commit and the nodes its refs name.
+  const resolveRef = (ref: string): string | undefined => {
+    if (nodes.has(ref)) return ref;
+    for (const prefix of ["commit", "unit", "contract", "evidence", "artifact", "file", "member"]) if (nodes.has(`${prefix}:${ref}`)) return `${prefix}:${ref}`;
+    for (const n of nodes.values()) {
+      if (n.kind === "decision" && (ref === n.record || ref === `${n.recordKind}/${n.record}`)) return n.id;
+      if (n.kind === "commit" && /^[0-9a-f]{7,}$/.test(ref) && n.sha.startsWith(ref)) return n.id;
+    }
+    return undefined;
+  };
+  for (const { commit, plugin, finding } of pluginFindings) {
+    const code = finding.code as PluginCode;
+    const refs = finding.refs ?? [];
+    const concerns = [...new Set([commit, ...refs.map(resolveRef).filter((x): x is string => x !== undefined)])];
+    findings.push({ id: `finding:${code}:${findings.filter((f) => f.code === code).length + 1}`, kind: "finding", code, message: finding.message, concerns, plugin, refs });
+  }
   for (const f of findings) nodes.set(f.id, f);
   const all = [...nodes.values()];
   return {
@@ -925,7 +983,7 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
       workspace: { name: declaration.name, root: located.root },
       region: rid,
       history: { rev, follows: region.lines ? "line-range" : type === "file" ? "file" : "directory", shallow },
-      kinds: kinds.map((k) => ({ file: k.display, records: k.records?.loaded.kind.name ?? null, joins: k.joins?.form ?? null })),
+      kinds: kinds.map((k) => ({ file: k.display, name: k.name, records: k.records?.loaded.kind.name ?? null, joins: k.joins?.form ?? null })),
       nodes: all,
       edges,
       reasons,

package/src/workspace/member-commands.ts

@@ -333,9 +333,12 @@ export function parseMemberRunOutput(stdout: string): { chant: string; results:
   return header ? { chant: header.chant, results, stray: stray.join("\n") } : undefined;
 }
 
-async function runGroup(verb: WorkspaceVerb, group: ToolchainGroup, root: string, args: ParsedArgs): Promise<UnitResult[]> {
+/** A command line to run in each member instead of the verb's own, such as `graph --components` (#2662). */
+export type MemberArgv = (unit: RunUnit) => string[];
+
+async function runGroup(verb: WorkspaceVerb, group: ToolchainGroup, root: string, args: ParsedArgs, argvFor?: MemberArgv): Promise<UnitResult[]> {
   const { toolchain, units } = group;
-  const argvs = new Map(units.map((u) => [u.id, memberArgv(verb, u, args)]));
+  const argvs = new Map(units.map((u) => [u.id, argvFor ? argvFor(u) : memberArgv(verb, u, args)]));
   for (const u of units) {
     const o = argvs.get(u.id)!;
     const i = o.indexOf("--output");
@@ -365,9 +368,12 @@ async function runGroup(verb: WorkspaceVerb, group: ToolchainGroup, root: string
   return out;
 }
 
-/** Run every group of the plan, one process per toolchain at a time each, and return the results in plan order. */
-export async function executePlan(plan: MemberPlan, args: ParsedArgs): Promise<UnitResult[]> {
-  const perGroup = await Promise.all(plan.groups.map((g) => runGroup(plan.verb, g, plan.workspace.root, args)));
+/**
+ * Run every group of the plan, one process per toolchain at a time each, and
+ * return the results in plan order. `argvFor` replaces the verb's command line.
+ */
+export async function executePlan(plan: MemberPlan, args: ParsedArgs, argvFor?: MemberArgv): Promise<UnitResult[]> {
+  const perGroup = await Promise.all(plan.groups.map((g) => runGroup(plan.verb, g, plan.workspace.root, args, argvFor)));
   const byId = new Map(perGroup.flat().map((r) => [r.id, r]));
   const order = plan.groups.flatMap((g) => g.units);
   return order.map((u) => byId.get(u.id)!);

package/src/workspace/read-contract.test.ts

@@ -6,8 +6,9 @@
  * `chant` member (`delivery`), three `other` members and decision records.
  * Each read-contract command reads it here, and its output must validate
  * against the command's schema: `ls`, `graph` (running delivery's real
- * `chant graph`), `check`, `status` and `records`, in the working tree and,
- * for `ls`, `graph` and `check`, at `HEAD` through `--at`.
+ * `chant graph`), `graph --composites`, `check`, `status` and `records`, in
+ * the working tree and, for `ls`, `graph` and `check`, at `HEAD` through
+ * `--at`.
  *
  * The schemas themselves are checked here too: each is a draft 2020-12
  * document under `https://intentius.io/chant/schemas/workspace/<command>/v1/`,
@@ -20,6 +21,8 @@ import { pathToFileURL } from "node:url";
 import { describe, expect, test } from "vitest";
 import { contract, git, REPO, validSchema } from "./__fixtures__/contract-repo";
 import checkSchema from "./check.schema.json";
+import { workspaceComposites } from "./composites";
+import compositesSchema from "./composites.schema.json";
 import { workspaceGraph } from "./graph-cli";
 import graphSchema from "./graph.schema.json";
 import { intentGraph } from "./intent";
@@ -37,7 +40,7 @@ import statusSchema from "./status.schema.json";
 const FIXTURE = join(REPO, "reference-workspace");
 const TIMEOUT = 240_000;
 
-const SCHEMAS = { ls: lsSchema, graph: graphSchema, check: checkSchema, status: statusSchema, records: recordsSchema, intent: intentSchema };
+const SCHEMAS = { ls: lsSchema, graph: graphSchema, check: checkSchema, status: statusSchema, records: recordsSchema, intent: intentSchema, composites: compositesSchema };
 
 /** This checkout's chant, started the way the CLI starts it, for members with no toolchain of their own. */
 const reader: Toolchain = {
@@ -131,6 +134,31 @@ describe("every schema against the reference workspace (#2543)", () => {
     }
   });
 
+  test(
+    "graph --composites runs delivery's own component graph, and says why the list is empty (#2662)",
+    async () => {
+      const { expectValid } = contract(compositesSchema);
+      for (const at of [undefined, "HEAD"]) {
+        const { doc, failed } = await workspaceComposites({ cwd: FIXTURE, at, reader });
+        expectValid(doc);
+        if ("error" in doc) throw new Error(doc.error.message);
+        expect(failed, JSON.stringify(doc.members)).toBe(false);
+        expect(doc.at).toBe(at ? head : null);
+        expect(doc.members.map((m) => [m.name, m.status])).toEqual([
+          ["app", "skipped"],
+          ["delivery", "read"],
+          ["design-client", "skipped"],
+          ["design", "skipped"],
+        ]);
+        // delivery has a docker Service and no composite or component.
+        expect(doc.composites).toEqual([]);
+        expect(doc.components).toEqual([]);
+        expect(doc.reasons.map((r) => r.code)).toEqual(["composites-none-declared", "composites-no-component"]);
+      }
+    },
+    TIMEOUT,
+  );
+
   test("records, in the working tree and at HEAD", async () => {
     const { expectValid } = contract(recordsSchema);
     for (const at of [undefined, "HEAD"]) {

package/src/workspace/reason-codes.test.ts

@@ -10,12 +10,15 @@ import { join } from "node:path";
 import { describe, expect, test } from "vitest";
 import { REPO } from "./__fixtures__/contract-repo";
 import { MEMBER_RUN_REASON_CODES } from "./compose-graph";
+import { COMPOSITES_ERROR_CODES, COMPOSITES_REASON_CODES } from "./composites";
 import { WORKSPACE_ERROR_CODES } from "./declaration";
 import { GRAPH_ERROR_CODES } from "./graph-cli";
 import { INTENT_ERROR_CODES, INTENT_FINDING_CODES, INTENT_REASON_CODES } from "./intent";
 import { CHECK_CODES, CHECK_ERROR_CODES } from "./lineage-check";
 import { GROUP_REASON_CODES, MEMBER_REASON_CODES } from "./ls";
-import { isReasonCode, REASON_CODES, REASONS } from "./reason-codes";
+import intentSchema from "./intent.schema.json";
+import { isPluginCode, isReasonCode, REASON_CODES, REASONS } from "./reason-codes";
+import { contract } from "./__fixtures__/contract-repo";
 import { READ_ERROR_CODES, RECORD_REASON_CODES, RECORD_WARNING_CODES } from "./records";
 import { STATUS_ERROR_CODES, STATUS_REASON_CODES } from "./status";
 
@@ -37,6 +40,8 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   INTENT_ERROR_CODES,
   INTENT_FINDING_CODES,
   INTENT_REASON_CODES,
+  COMPOSITES_ERROR_CODES,
+  COMPOSITES_REASON_CODES,
 };
 
 /** Every string in an `enum` under a property named `code`, anywhere in a schema. */
@@ -111,6 +116,34 @@ describe("the closed list of reason codes", () => {
     expect(seen).toBeGreaterThan(30);
   });
 
+  test("a plugin's finding codes are in its own namespace, outside the list, and the intent schema accepts them (#2656)", () => {
+    expect(isPluginCode("plugin:chud:contract-criteria-changed")).toBe(true);
+    expect(isPluginCode("plugin:chud:contract-criteria-changed", "chud")).toBe(true);
+    expect(isPluginCode("plugin:chud:contract-criteria-changed", "units")).toBe(false);
+    for (const bad of ["plugin:chud", "plugin::x", "plugin:chud:Upper", "plugin:chud:a:b", "intent-commit-bare", 7]) expect(isPluginCode(bad), String(bad)).toBe(false);
+    expect(isReasonCode("plugin:chud:contract-criteria-changed")).toBe(false);
+    const { validate } = contract(intentSchema);
+    const finding = (code: string) => ({ id: `finding:${code}:1`, kind: "finding", code, message: "m", concerns: [] });
+    const doc = (code: string) => ({
+      $schema: intentSchema.$id,
+      contract: 1,
+      chant: "0.0.0",
+      at: null,
+      workspace: { name: "w", root: "." },
+      region: "region:.",
+      history: { rev: null, follows: "directory", shallow: false },
+      kinds: [],
+      nodes: [finding(code)],
+      edges: [],
+      reasons: [],
+      summary: { commits: 0, decisions: 0, artifacts: 0, findings: 1 },
+    });
+    expect(validate(doc("plugin:chud:contract-criteria-changed"))).toBe(true);
+    expect(validate(doc("intent-commit-bare"))).toBe(true);
+    expect(validate(doc("plugin:chud:Nope"))).toBe(false);
+    expect(validate(doc("made-up-code"))).toBe(false);
+  });
+
   test("the read-contract page documents every code", () => {
     const page = readFileSync(join(REPO, "docs", "src", "content", "docs", "reference", "workspace-read-contract.mdx"), "utf-8");
     for (const c of REASON_CODES) expect(page, c).toContain(`| \`${c}\` |`);

package/src/workspace/reason-codes.ts

@@ -64,6 +64,7 @@ export const REASONS = {
   "asset-missing": "A file the record pins by hash does not exist in the tree read.",
   "asset-stale": "A file the record pins is unchanged at the hash a record it supersedes pinned: the decision changed and the artifact did not follow.",
   "record-supersedes-pending": "A supersedes link from a record whose state is weaker than the record it names, so the link has no effect yet.",
+  "record-no-evidence": "The record's evidence list is empty: it cites nothing and pins no file. Information for a reviewer, never an error.",
   // 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.",
@@ -89,6 +90,10 @@ export const REASONS = {
   "intent-evidence-unpinned": "A decision's evidence has no hash: a URL, or a path with no sha256.",
   "intent-trailer-unverified": "A commit carries a trailer a plugin says claims authorship, and the commit is not attested.",
   "intent-region-unconstrained": "No decision constrains the region at any granularity.",
+  // Composite instances joined to components (graph --composites, #2662): why the list is empty or has no component.
+  "composites-no-chant-member": "No member of kind chant was read, so nothing declares a composite instance or a component.",
+  "composites-none-declared": "The members read declare no composite instance.",
+  "composites-no-component": "The members read declare no component, so no composite instance has one.",
   // The lineage lock (check).
   "lock-invalid": "The lineage lock can't be read.",
   "manual-step-open": "A scope in the lineage lock has an open manual step.",
@@ -102,3 +107,20 @@ export const REASON_CODES = Object.keys(REASONS) as ReasonCode[];
 export function isReasonCode(value: unknown): value is ReasonCode {
   return typeof value === "string" && Object.prototype.hasOwnProperty.call(REASONS, value);
 }
+
+/**
+ * A finding code a plugin contributes to the intent graph through its
+ * `commitJoins` (#2656): `plugin:<name>:<code>`, where `<name>` is the kind's
+ * name and `<code>` is lower case words joined by dashes. These are outside the
+ * closed list: the plugin owns its namespace, and core only carries them.
+ */
+export type PluginCode = `plugin:${string}:${string}`;
+
+export const PLUGIN_CODE = /^plugin:([^:\s]+):([a-z0-9]+(?:-[a-z0-9]+)*)$/;
+
+/** Whether `value` is a plugin code, and, given `name`, one in that kind's namespace. */
+export function isPluginCode(value: unknown, name?: string): value is PluginCode {
+  if (typeof value !== "string") return false;
+  const m = value.match(PLUGIN_CODE);
+  return !!m && (name === undefined || m[1] === name);
+}

package/src/workspace/records-contract.test.ts

@@ -5,13 +5,13 @@
  * doesn't exist yet, so the chant repo's own decision files stand in for it.
  */
 
-import { cpSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import Ajv2020 from "ajv/dist/2020";
 import { afterAll, describe, expect, test } from "vitest";
 import { queryRecords, RECORDS_CONTRACT_VERSION, RECORDS_OUTPUT_SCHEMA_ID, type RecordsDocument } from "./records-cli";
-import { READ_ERROR_CODES, RECORD_REASON_CODES } from "./records";
+import { READ_ERROR_CODES, RECORD_REASON_CODES, RECORD_WARNING_CODES } from "./records";
 import schema from "./records.schema.json";
 import { PROVENANCE_LEVELS } from "./trust/attestor";
 
@@ -77,6 +77,26 @@ describe("records output schema", () => {
     expect(doc.summary.invalid).toBe(2);
   });
 
+  test("a workspace-sourced decision with no evidence validates, with its warning (#2654)", async () => {
+    const root = copyDecisions();
+    const dir = join(root, "docs", "design", "decisions");
+    const text = readFileSync(join(dir, "ws-003-seal-scope.md"), "utf-8")
+      .replace(/^id: .*$/m, 'id: "ws-900"')
+      .replace(/^source:\n(?:  .*\n)*/m, 'source:\n  kind: "workspace"\n  member: "app"\n')
+      .replace(/^evidence:\n(?:  .*\n)*/m, "evidence: []\n");
+    writeFileSync(join(dir, "ws-900-extra.md"), text);
+    const doc = await queryRecords({ kind: KIND, current: true, cwd: root });
+    expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    const r = doc.records.find((x) => x.id === "ws-900");
+    expect(r?.valid).toBe(true);
+    expect(r?.warnings?.map((w) => w.code)).toEqual(["record-no-evidence"]);
+  });
+
+  test("lists exactly the warning codes the code can return", () => {
+    expect(schema.$defs.warning.properties.code.enum).toEqual([...RECORD_WARNING_CODES]);
+  });
+
   test("every failure validates with its code", async () => {
     const root = copyDecisions();
     const docs = [

package/src/workspace/records.schema.json

@@ -74,7 +74,7 @@
           "items": { "$ref": "#/$defs/asset" }
         },
         "warnings": {
-          "description": "Added in contract 1 by #2549. Findings that leave the record valid: a pinned file that changed, went missing or did not follow a superseding decision, or a supersedes link that has no effect yet. valid and --current do not look at them.",
+          "description": "Added in contract 1 by #2549. Findings that leave the record valid: a pinned file that changed, went missing or did not follow a superseding decision, a supersedes link that has no effect yet, or (added by #2654) an evidence list that is empty. valid and --current do not look at them.",
           "type": "array",
           "items": { "$ref": "#/$defs/warning" }
         }
@@ -101,7 +101,7 @@
       "type": "object",
       "required": ["code", "message"],
       "properties": {
-        "code": { "enum": ["asset-drift", "asset-missing", "asset-stale", "record-supersedes-pending"] },
+        "code": { "enum": ["asset-drift", "asset-missing", "asset-stale", "record-supersedes-pending", "record-no-evidence"] },
         "message": { "type": "string" }
       }
     },

package/src/workspace/records.test.ts

@@ -93,6 +93,49 @@ describe("readRecords", () => {
     expect(r.data).not.toBeNull();
   });
 
+  describe("a dissent needs a reason (#2652)", () => {
+    const withReviews = (reviews: string) => decision("ws-001").replace(/^reviews: \[\]$/m, `reviews:\n${reviews}`);
+    const review = (verdict: string, extra = "") => `  - reviewer: "ana"\n    verdict: "${verdict}"\n    on: "2026-09-24"\n${extra}`;
+
+    for (const [label, note] of [
+      ["null", "    note: null\n"],
+      ["empty", '    note: ""\n'],
+      ["blank", '    note: "  "\n'],
+      ["missing", ""],
+    ] as const) {
+      test(`a dissent with a ${label} note is record-schema-invalid, naming the reviewer`, async () => {
+        write("ws-001-a.md", withReviews(review("dissent", note)));
+        const [r] = (await read()).records;
+        expect(r.valid).toBe(false);
+        expect(codes(r)).toEqual(["record-schema-invalid"]);
+        expect(r.reasons[0].message).toBe("/reviews/0 A dissent needs a reason: the dissent by ana has no note.");
+      });
+    }
+
+    test("a dissent with a note is valid, and so are agree and abstain without one", async () => {
+      write(
+        "ws-001-a.md",
+        withReviews(
+          review("dissent", '    note: "the seal should cover the lockfile too"\n') +
+            review("agree") +
+            review("abstain", "    note: null\n"),
+        ),
+      );
+      const [r] = (await read()).records;
+      expect(r.reasons).toEqual([]);
+      expect(r.valid).toBe(true);
+    });
+
+    test("a dissent carries its concern's lifecycle; another verdict cannot", async () => {
+      write("ws-001-a.md", withReviews(review("dissent", '    note: "why"\n    addressed_by: "INTENTIUS/chant#2652"\n    withdrawn_on: "2026-09-25"\n')));
+      expect((await read()).records[0].valid).toBe(true);
+      write("ws-001-a.md", withReviews(review("agree", '    addressed_by: "ws-002"\n')));
+      const [r] = (await read()).records;
+      expect(codes(r)).toEqual(["record-schema-invalid"]);
+      expect(r.reasons[0].message).toBe("/reviews/0 Only a dissent is a concern: the agree by ana cannot carry addressed_by or withdrawn_on.");
+    });
+  });
+
   test("a supersedes link to a missing id is record-supersedes-unknown", async () => {
     write("ws-002-b.md", decision("ws-002", "decided", ["ws-404"]));
     const [r] = (await read()).records;
@@ -199,6 +242,56 @@ describe("readRecords", () => {
   });
 });
 
+/**
+ * A decision made in the workspace (#2654): the workspace source form with no
+ * issue, and no evidence. `constrains` replaces ws-003's.
+ */
+function workspaceDecision(id: string, constrains: string[] = ["member:app"]): string {
+  const list = constrains.length === 0 ? "constrains: []\n" : `constrains:\n${constrains.map((c) => `  - "${c}"\n`).join("")}`;
+  return decision(id)
+    .replace(/^source:\n(?:  .*\n)*/m, 'source:\n  kind: "workspace"\n  member: "app"\n')
+    .replace(/^evidence:\n(?:  .*\n)*/m, "evidence: []\n")
+    .replace(/^constrains:\n(?:  .*\n)*/m, list);
+}
+
+describe("a decision that originates in the workspace (#2654)", () => {
+  test("validates with no issue and no evidence, is current, and carries record-no-evidence", async () => {
+    write("ws-001-a.md", workspaceDecision("ws-001"));
+    const current = await read({ current: true });
+    expect(current.records.map((r) => [r.id, r.valid, r.reasons, r.warnings.map((w) => w.code)])).toEqual([
+      ["ws-001", true, [], ["record-no-evidence"]],
+    ]);
+    expect(current.records[0].data?.source).toEqual({ kind: "workspace", member: "app" });
+  });
+
+  test("takes a session and an issue, and nothing else", async () => {
+    const base = workspaceDecision("ws-001");
+    write("ws-001-a.md", base.replace('  member: "app"\n', '  member: "app"\n  session: "S-0001"\n  issue: "jhgaylor/chud#77"\n'));
+    write("ws-002-b.md", base.replace('id: "ws-001"', 'id: "ws-002"').replace('  member: "app"\n', '  member: "app"\n  session: null\n'));
+    write("ws-003-c.md", base.replace('id: "ws-001"', 'id: "ws-003"').replace('  member: "app"\n', '  member: "app"\n  row: "Sort order"\n'));
+    write("ws-004-d.md", base.replace('id: "ws-001"', 'id: "ws-004"').replace('  member: "app"\n', ""));
+    const records = (await read()).records;
+    expect(records.map((r) => [r.id, codes(r)])).toEqual([
+      ["ws-001", []],
+      ["ws-002", []],
+      ["ws-003", ["record-schema-invalid"]],
+      ["ws-004", ["record-schema-invalid"]],
+    ]);
+  });
+
+  test("a record with evidence carries no record-no-evidence warning", async () => {
+    write("ws-001-a.md", decision("ws-001"));
+    expect((await read()).records[0].warnings).toEqual([]);
+  });
+
+  test("a record that constrains nothing is refused", async () => {
+    write("ws-001-a.md", workspaceDecision("ws-001", []));
+    const [r] = (await read()).records;
+    expect(codes(r)).toEqual(["record-schema-invalid"]);
+    expect(r.reasons[0].message).toMatch(/constrains/);
+  });
+});
+
 describe("loadRecordKind", () => {
   const load = () => loadRecordKind(join(dir, "decisions", "decision.kind.mjs"));