@intentius/chant 0.101.0 → 0.102.0

package/src/workspace/reason-codes.ts

@@ -92,6 +92,9 @@ export const REASONS = {
   "work-done-gap-open": "A work record is done, and the finding it came from still fires on its region. graph --intent raises it, and records does by walking that region.",
   "work-acceptance-unmet": "A work record is done, and one of its acceptance criteria has no passing evidence of the verification it expects. check fails on it (WSP117).",
   "work-acceptance-self-verified": "A passing manual verdict on a work record's criterion names the record's implementer, so it does not count: a manual verdict comes from someone else.",
+  "work-contract-unknown": "A work record names a contract that no record of its kind's contract kind has.",
+  "work-contract-undecided": "A work record names a contract whose state is not approved, such as a draft.",
+  "work-tier-unknown": "A work record names a builder tier that its kind's work.tier.tiers does not list.",
   // An answer to a decision point that is valid but warned about (records, points, ws-058, #2739).
   "answer-points-unreadable": "The points file the answer kind names can't be read, or is not valid.",
   "answer-point-unknown": "The answer's point is not declared in the points file the answer kind names.",
@@ -136,7 +139,10 @@ export const REASONS = {
   // Write scope (#2548): a records write that is refused, and a commit check --changes reports, outside the writer's scope.
   "write-scope-member": "The write is to a file, or to a record kind, of a member outside the writer's scope: an agent session writes only its own member, and writeScope.<class>.members leaves the member out.",
   "write-scope-kind": "The write is to a record kind writeScope.<class>.records does not list, with a verb it does not list for the kind, or deletes a record.",
+  "write-scope-protected": "The write is to a file writeScope.<class>.protected lists, or one under a directory it lists, outside any top-level keys the entry's except allows (#3146).",
+  "write-scope-class-unknown": "The declaration's writeScope at base names a principal class no pinned package supplies, and the writer is judged human, so it may be in that class; the write is refused until the package is installed at the pinned version or the entry removed (#3080).",
   "agent-unknown": "CHANT_AGENT, or a commit's Chant-Agent trailer, names an agent session the declaration at base does not declare.",
+  "principal-unidentified": "chant.workspace.json at base sets identity.attribution to identified, and the write names a person by a bare name: --by, an author field or a decision point's answerer must be a forge identity (github:<login>, gitlab:<login>, <forge>@<host>:<login>), a principal the signers file at base lists, or an agent, runner or service principal (#3163).",
   // A review given in a session (records review --session, #2693).
   "session-unknown": "--session names no session of a session kind whose subjects are the record's kind.",
   "session-not-open": "--session names a session in a closed state, which takes no more verdicts.",
@@ -156,12 +162,15 @@ export const REASONS = {
   // The intent graph (graph --intent, #2651): a read that fails.
   "intent-region-invalid": "The region's path, or its line range, does not exist in the tree read.",
   "intent-record-unknown": "graph --intent --record names an id that no record of a decision kind read has.",
+  "intent-symbol-unsupported": "The region names a symbol, path#symbol, in a file no symbol resolver reads; a line range still works.",
+  "intent-symbol-unknown": "The region names a symbol the file does not declare in the tree read.",
+  "intent-symbol-ambiguous": "The region names a symbol that matches more than one declaration in the file; its qualified name picks one.",
   // The intent graph: part of the walk that can't be read. The document is still printed.
   "intent-history-shallow": "The repository is a shallow clone, so the region's history stops at the clone's boundary.",
   "intent-plugin-failed": "A kind file's commitJoins, which joins commits to units, contracts and evidence, failed for a commit.",
   // The intent graph: findings, each a node in the graph.
   "intent-commit-undecided": "A commit changed the region when no decision constrained it at path granularity.",
-  "intent-commit-bare": "A commit names no unit, no pull request and no decision covering the region at its time.",
+  "intent-commit-bare": "A commit names no unit, carries no record through its Chant-Record or Chant-Lease trailer, and has no pull request and no decision covering the region at its time.",
   "intent-pin-drifted": "A decision's pinned artifact no longer hashes to the pin.",
   "intent-pin-missing": "A decision's pinned artifact does not exist in the tree read.",
   "intent-pin-stale": "A current decision pins an artifact at the hash a record it supersedes pinned, and the artifact has not changed since: the decision moved on and the artifact did not.",
@@ -177,6 +186,11 @@ export const REASONS = {
   "intent-decision-unimplemented": "A decided decision constrains the region, no work item that is not dropped implements it, and no commit falls in its window.",
   "intent-work-blocked": "A work item constraining the region has commits in its window while a work item it needs is not done.",
   "intent-work-open-decided-code": "Commits in the region are a decision's own work while the work item implementing that decision is still open.",
+  // The intent graph's answer to why the region is like this (#3034): what it can't account for.
+  "intent-why-no-decision": "No current decision governs the region at any granularity, and none is carried out by the commits or runs that made its current lines.",
+  "intent-why-no-run": "None of the region's current lines was made by a commit an agent run is joined to.",
+  "intent-why-uncommitted": "Some of the region's lines are not committed yet.",
+  "intent-why-run-ambiguous": "Some lines come from a commit several agent runs made, and no run's recorded hunks say which wrote them.",
   // The forward coverage check (check --changes, #2773): findings, one per changed path.
   "change-uncovered": "A path the diff changes is covered by no current decided record and no open work item, by path or by its member.",
   "change-out-of-scope": "A record in hand for the change, such as the work item it is for or a decision that item implements, lists a path the diff changes in its out_of_scope.",
@@ -205,6 +219,9 @@ export const REASONS = {
   // A box's intent, the decision record its box block names (check, #2850). Each is also a WSP finding.
   "box-intent-unknown": "A box block names an intent, and no record of a declared kind named decision has that id.",
   "box-intent-unconstrained": "The decision record a box names as its intent constrains no member or path of this workspace: no member: entry for a declared member and no path: entry at, above or inside one's directory.",
+  // Why a workspace isn't plantable (status and graph, #3146): not a finding, since a workspace need not be.
+  "box-none": "No member's box block declares services, so the workspace has no box for a host to plant.",
+  "box-several": "More than one member's box block declares services, and a planted workspace runs one box.",
   // The work lease (chant workspace work claim|renew|release, #2732): why the command could not run.
   "work-kind-missing": "No work kind to find the item in: --kind names a kind with no work block, or the declaration names no work kind.",
   "work-kind-ambiguous": "More than one declared work kind has a record with the id, so --kind must name one.",
@@ -218,6 +235,12 @@ export const REASONS = {
   "lease-token-mismatch": "The live lease on the work item carries another fencing token than the one given.",
   "lease-race": "Another writer changed the lease between this command's read and its write.",
   "lease-push-rejected": "The remote refused the lease push: another clone claimed the item first, or the remote could not be reached.",
+  // The agent run record (chant workspace runs, #3033): why a write was refused, and what a read could not see. Nothing is written on a refusal.
+  "run-exists": "runs start or runs record was given a run id the ledger already has.",
+  "run-unknown": "runs end names a run the ledger has no start for.",
+  "run-ended": "runs end names a run whose end is already recorded.",
+  "runs-no-ledger": "The checkout has no chant/lifecycle branch, so there are no agent runs to read.",
+  "runs-ledger-malformed": "Some lines of the agent run ledger aren't run events; the rest are read.",
   // A box whose isolation fails (check, #2727). Each is also a WSP finding.
   "box-isolation-collision": "Two boxes on one host resolve to the same port, state path or cookie name, or two ports in one box share an offset.",
   "box-isolation-literal": "A host's stateRoot or a box's state entry is a literal machine path instead of one derived from an environment reference and the box's name.",

package/src/workspace/records-amend.schema.json

@@ -178,7 +178,9 @@
                 "ratify-quorum-not-met",
                 "write-scope-member",
                 "write-scope-kind",
+                "write-scope-class-unknown",
                 "agent-unknown",
+                "principal-unidentified",
                 "record-unparseable",
                 "record-schema-invalid",
                 "record-id-duplicate",

package/src/workspace/records-checkout.ts

@@ -0,0 +1,106 @@
+/**
+ * The checkout a working-tree read is made in, and which records in it are
+ * uncommitted (#3160).
+ *
+ * Work in progress lives as uncommitted files in a work branch's working tree
+ * (#3158, #3145). A reader such as hud or studio shows "kept, not yet
+ * applied" from `records --json` alone: each record says whether it is
+ * committed, modified or new against `HEAD`, and the document names the
+ * branch, the commit `HEAD` names and the base that branch forked from. The
+ * reader never diffs git itself.
+ *
+ * Every git call here reads. None takes the index lock or refreshes the
+ * index (`--no-optional-locks`), so a read leaves the checkout as it was,
+ * `.git` included, which the reader conformance suite checks.
+ */
+
+import { execFileSync } from "node:child_process";
+import { resolveBase, type BaseSource } from "./trust/provenance";
+
+/** Where a record's file stands against `HEAD`. */
+export type WorktreeState = "committed" | "modified" | "new";
+
+/** The branch, head and base of a checkout (#3160). `records` and `status` both print it. */
+export interface CheckoutHead {
+  /** The checked-out branch's short name, such as `chant/work/w-12`, or null when `HEAD` is detached. */
+  branch: string | null;
+  /** The commit `HEAD` names, or null before the first commit. Each record's `worktree` is judged against it. */
+  head: string | null;
+  /** The merge base of `head` and the target branch tip: the commit the branch forked from. Null without a head, a target, or common history. */
+  base: string | null;
+  /** Where the target branch was found: `flag` for `--base`, else `origin/HEAD`, `main` or `master`. Null when there is none. */
+  baseFrom: BaseSource | null;
+}
+
+/** {@link CheckoutHead} for one record kind, with the record files `HEAD` has and the working tree does not. */
+export interface CheckoutView extends CheckoutHead {
+  /** Record files of the kind at `head` that the working tree no longer has, from the repository root, sorted. */
+  deleted: string[];
+}
+
+function git(top: string, args: string[]): string {
+  return execFileSync("git", ["--no-optional-locks", "--literal-pathspecs", ...args], {
+    cwd: top,
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "pipe"],
+    maxBuffer: 256 * 1024 * 1024,
+  });
+}
+
+function tryGit(top: string, args: string[]): string | undefined {
+  try {
+    return git(top, args);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The branch, head and base of the checkout at `top`. `explicitBase` is
+ * `--base`, as the trust policy takes it; otherwise the target branch is the
+ * one the policy is read at (`origin/HEAD`, then `main`, then `master`).
+ */
+export function readCheckoutHead(top: string, explicitBase?: string): CheckoutHead {
+  const branch = tryGit(top, ["symbolic-ref", "--quiet", "--short", "HEAD"])?.trim() || null;
+  const head = tryGit(top, ["rev-parse", "--verify", "--quiet", "HEAD^{commit}"])?.trim() || null;
+  const target = resolveBase(top, explicitBase);
+  const base = head && target.commit ? tryGit(top, ["merge-base", head, target.commit])?.trim() || null : null;
+  return { branch, head, base, baseFrom: target.from };
+}
+
+/** NUL-separated git output as a list. */
+function zList(out: string | undefined): string[] {
+  return (out ?? "").split("\0").filter(Boolean);
+}
+
+/**
+ * Each of `paths` (record files directly in `dir`, from the repository root)
+ * as committed, modified or new against `head`, and the files directly in
+ * `dir` at `head` whose names `match` and that `paths` leaves out: the
+ * records deleted in the working tree. With no head every path is new.
+ *
+ * Staged and unstaged changes count alike: anything `HEAD` does not hold is
+ * uncommitted. A rename is a new record and a deleted one.
+ */
+export function worktreeStates(
+  top: string,
+  head: string | null,
+  dir: string,
+  paths: readonly string[],
+  match: RegExp,
+): { states: Map<string, WorktreeState>; deleted: string[] } {
+  const states = new Map<string, WorktreeState>();
+  if (head === null) {
+    for (const p of paths) states.set(p, "new");
+    return { states, deleted: [] };
+  }
+  const prefix = dir === "." ? "" : `${dir}/`;
+  const direct = (p: string) => p.startsWith(prefix) && !p.slice(prefix.length).includes("/");
+  const spec = dir === "." ? "." : dir;
+  const atHead = new Set(zList(tryGit(top, ["ls-tree", "-r", "-z", "--name-only", head, "--", spec])).filter(direct));
+  const changed = new Set(zList(tryGit(top, ["diff", "--name-only", "-z", "--no-renames", head, "--", spec])));
+  for (const p of paths) states.set(p, !atHead.has(p) ? "new" : changed.has(p) ? "modified" : "committed");
+  const present = new Set(paths);
+  const deleted = [...atHead].filter((p) => !present.has(p) && match.test(p.slice(prefix.length))).sort();
+  return { states, deleted };
+}

package/src/workspace/records-cli.ts

@@ -15,6 +15,11 @@
  *
  * With `--since <rev>` it prints what changed between two revisions instead,
  * through `records-since.ts` (#2673).
+ *
+ * A working-tree read in git says, for each record, whether it is committed,
+ * modified or new against `HEAD`, and names the branch, head and base of the
+ * checkout; `--uncommitted` lists only the records `HEAD` doesn't hold
+ * (#3160, `records-checkout.ts`).
  */
 
 import { execFileSync } from "node:child_process";
@@ -48,8 +53,9 @@ import {
   type SealInput,
   type VerdictAttestation,
 } from "./records";
+import { readCheckoutHead, worktreeStates, type CheckoutView, type WorktreeState } from "./records-checkout";
 import { gitTree, workingTree, type WorkspaceTree } from "./tree";
-import type { DecisionWork } from "./work";
+import type { DecisionWork, WorkAnswer } from "./work";
 import { activeAttestors, type CommitAttestor, type ProvenanceLevel } from "./trust/attestor";
 import { policyAtBase, recordProvenance, resolveBase, type BaseSource, type RecordProvenance } from "./trust/provenance";
 import { returnedPolicy, type TrustPolicy } from "./trust/policy";
@@ -62,7 +68,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] [--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> | 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;
@@ -81,6 +87,8 @@ export interface RecordsQuery {
    * false; the intent graph passes false, since it raises the warning itself.
    */
   workGaps?: boolean;
+  /** List only the records that are modified or new against `HEAD` (#3160). Needs git and a working-tree read. */
+  uncommitted?: boolean;
 }
 
 /**
@@ -108,6 +116,20 @@ export type RecordView = RecordEntry & {
    * (`record-decided.ts`). The intent graph's windows open at this commit.
    */
   decidedIn?: DecidedIn | null;
+  /**
+   * For a read in the working tree of a git repository (#3160): whether the
+   * record's file is as `HEAD` holds it (`committed`), changed from it
+   * (`modified`), or not in it (`new`), staged or not. Absent under `--at`.
+   */
+  worktree?: WorktreeState;
+  /**
+   * For a work kind whose work block names an answer kind (#3147): the
+   * decision-point answers about the item, the answer records whose
+   * `constrains` names its id, joined by id and never copied onto the item.
+   * Read at the same revision; in the working tree, with the questions a
+   * steward keeps on the lifecycle ledger (#2786) laid over it.
+   */
+  answers?: WorkAnswer[];
 };
 
 /** The role in the trust policy whose holders' verdicts the quorum does not count (#2671). */
@@ -134,6 +156,10 @@ export type RecordsDocument =
       /** The directory pinned paths resolve in, from the repository root: the workspace holding the kind file, or the repository root (#2549). */
       workspaceRoot: string;
       current: boolean;
+      /** Whether only the records `HEAD` doesn't hold were listed (`--uncommitted`, #3160). */
+      uncommitted: boolean;
+      /** For a read in the working tree of a git repository (#3160): the branch, head and base it is on, and the records deleted from it. Absent under `--at`. */
+      checkout?: CheckoutView;
       trust: TrustView;
       records: RecordView[];
       summary: { total: number; valid: number; invalid: number; superseded: number };
@@ -227,7 +253,8 @@ export async function queryDeclaredRecords(kinds: { declared: RecordKindDeclarat
     const doc = await queryRecords({ ...query, kind: k.file });
     out.push({ ...doc, declared: { member: k.declared.member, path: k.declared.path, name: k.declared.name } });
   }
-  return { $schema: RECORDS_OUTPUT_SCHEMA_ID, contract: RECORDS_CONTRACT_VERSION, kinds: out, ...(query.current ? { spec: specOf(out) } : {}) };
+  // The spec is every current spec record; an --uncommitted read lists only some, so it has none.
+  return { $schema: RECORDS_OUTPUT_SCHEMA_ID, contract: RECORDS_CONTRACT_VERSION, kinds: out, ...(query.current && !query.uncommitted ? { spec: specOf(out) } : {}) };
 }
 
 /** A records read, before provenance. */
@@ -356,6 +383,8 @@ export async function readRecordsFor(
 
 /** Run the query and build the document `--json` prints. Never throws a {@link RecordReadError}. */
 export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument> {
+  // A revision has no working tree to hold anything uncommitted; the CLI and the MCP tool refuse the pair first.
+  if (query.uncommitted && query.at !== undefined) throw new Error("--uncommitted reads the working tree and takes no --at");
   try {
     const { loaded, root, top, at, workspaceRoot, tree, result } = await readRecordsFor(query);
     // Provenance, judged by the policy at base and never by the tree read (#2547).
@@ -395,6 +424,41 @@ export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument
       const leases = await activeWorkLeases(loaded.file);
       for (const r of records) if (r.id !== null) r.lease = leases.get(r.id) ?? null;
     }
+    if (loaded.kind.work?.answers) {
+      // The answers about each item, joined by id (#3147). An answer kind that can't be read leaves answers out rather than failing the work read.
+      const [{ workAnswers }, { readLedgerAnswers, withLedgerAnswers }] = await Promise.all([import("./work"), import("./answers-ledger")]);
+      const answersRead = await readRecordsFor({
+        kind: resolve(dirname(loaded.file), loaded.kind.work.answers),
+        cwd: query.cwd,
+        ...(query.at !== undefined ? { at: query.at } : {}),
+        overlay: async (base, { loaded: l, root: r }) =>
+          withLedgerAnswers(base, await readLedgerAnswers({ file: l.file, name: l.kind.name, dirRel: relative(r, l.dir).split(sep).join("/") || "." })),
+      }).catch((err: unknown) => {
+        if (err instanceof RecordReadError) return undefined;
+        throw err;
+      });
+      if (answersRead) {
+        const byItem = workAnswers(answersRead.result.records, records.flatMap((r) => (r.id !== null ? [r.id] : [])));
+        for (const r of records) if (r.id !== null) r.answers = byItem.get(r.id) ?? [];
+      }
+    }
+    // Which records the checkout holds uncommitted, judged after every record is read, so links still resolve across the whole set (#3160).
+    let checkout: CheckoutView | undefined;
+    let listed = records;
+    let summary = result.summary;
+    if (at === null && top) {
+      const { head, ...rest } = readCheckoutHead(top, query.base);
+      const dir = relative(root, loaded.dir).split(sep).join("/") || ".";
+      const { states, deleted } = worktreeStates(top, head, dir, records.map((r) => r.path), new RegExp(loaded.kind.location.match));
+      for (const r of records) r.worktree = states.get(r.path) ?? "new";
+      checkout = { branch: rest.branch, head, base: rest.base, baseFrom: rest.baseFrom, deleted };
+      if (query.uncommitted) {
+        listed = records.filter((r) => r.worktree !== "committed");
+        summary = { ...summary, total: listed.length, valid: listed.filter((r) => r.valid).length, invalid: listed.filter((r) => !r.valid).length };
+      }
+    } else if (query.uncommitted && !top) {
+      throw new RecordReadError("not-a-git-repository", "--uncommitted compares the working tree with HEAD, and this directory is not in a git repository");
+    }
     return {
       $schema: RECORDS_OUTPUT_SCHEMA_ID,
       contract: RECORDS_CONTRACT_VERSION,
@@ -408,9 +472,11 @@ export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument
       at,
       workspaceRoot,
       current: !!query.current,
+      uncommitted: !!query.uncommitted,
+      ...(checkout ? { checkout } : {}),
       trust: { base: base.commit, baseFrom: base.from, active: policy.active, signersPath: policy.signersPath, problems: policy.problems },
-      records,
-      summary: result.summary,
+      records: listed,
+      summary,
       ...(result.decisions ? { decisions: result.decisions } : {}),
     };
   } catch (err) {
@@ -561,6 +627,11 @@ export async function runWorkspaceRecords(ctx: CommandContext): Promise<number>
     console.error(formatError({ message: `chant workspace records takes no argument but pin, new, amend, review or close (got ${args.extraPositional})`, hint: USAGE }));
     return 1;
   }
+  const pairing = uncommittedPairing(args);
+  if (pairing) {
+    console.error(formatError({ message: pairing, hint: USAGE }));
+    return 1;
+  }
   if (!args.kind) return runDeclaredRecords(args);
   if (args.require !== undefined && args.require !== "attested") {
     console.error(formatError({ message: `--require takes one level, attested, not ${JSON.stringify(args.require)}`, hint: USAGE }));
@@ -579,13 +650,13 @@ export async function runWorkspaceRecords(ctx: CommandContext): Promise<number>
     else console.log(formatSince(since));
     return "error" in since ? 1 : 0;
   }
-  const doc = await queryRecords({ kind: args.kind, current: args.current, at: args.at, base: args.base, cwd: process.cwd() });
+  const doc = await queryRecords({ kind: args.kind, current: args.current, uncommitted: args.uncommitted, at: args.at, base: args.base, cwd: process.cwd() });
   if (args.json) {
     console.log(JSON.stringify(doc, null, 2));
   } else if ("error" in doc) {
     console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));
   } else {
-    console.log(formatRecords(doc.records, doc.summary, doc.at));
+    console.log(formatRecords(doc.records, doc.summary, doc.at, doc.checkout));
   }
   if ("error" in doc) return 1;
   if (args.require) {
@@ -643,7 +714,7 @@ async function runDeclaredRecords(args: CommandContext["args"]): Promise<number>
     return 1;
   }
   if (args.since !== undefined) return runDeclaredSince(declared, args);
-  const set = await queryDeclaredRecords(declared, { current: args.current, at: args.at, base: args.base, cwd: process.cwd() });
+  const set = await queryDeclaredRecords(declared, { current: args.current, uncommitted: args.uncommitted, at: args.at, base: args.base, cwd: process.cwd() });
   if (args.json) console.log(JSON.stringify(set, null, 2));
   for (const doc of args.json ? [] : set.kinds) {
     if ("error" in doc) {
@@ -651,7 +722,7 @@ async function runDeclaredRecords(args: CommandContext["args"]): Promise<number>
       continue;
     }
     console.log(`${doc.declared.name ?? doc.kind.name} (${doc.declared.path})`);
-    console.log(formatRecords(doc.records, doc.summary, doc.at));
+    console.log(formatRecords(doc.records, doc.summary, doc.at, doc.checkout));
   }
   if (set.kinds.some((d) => "error" in d)) return 1;
   if (args.require) {
@@ -717,7 +788,20 @@ export function belowRequired(records: RecordView[], required: ProvenanceLevel):
   return records.filter((r) => r.provenance.level !== required);
 }
 
-function formatRecords(records: RecordView[], summary: { total: number; valid: number; invalid: number; superseded: number }, at: string | null): string {
+/** Why `--uncommitted` can't be given with the other flags given, or undefined when it can (#3160). */
+function uncommittedPairing(args: CommandContext["args"]): string | undefined {
+  if (!args.uncommitted) return undefined;
+  if (args.at !== undefined) return "--uncommitted reads the working tree against HEAD, and takes no --at";
+  if (args.since !== undefined) return "--uncommitted takes no --since: --since compares two revisions";
+  return undefined;
+}
+
+function formatRecords(
+  records: RecordView[],
+  summary: { total: number; valid: number; invalid: number; superseded: number },
+  at: string | null,
+  checkout?: CheckoutView,
+): string {
   const lines: string[] = [];
   const idWidth = Math.max(2, ...records.map((r) => (r.id ?? "-").length));
   const stateWidth = Math.max(5, ...records.map((r) => (r.state ?? "-").length));
@@ -728,7 +812,8 @@ function formatRecords(records: RecordView[], summary: { total: number; valid: n
     const remediated = r.remediatedBy.length > 0 ? `  remediated by ${r.remediatedBy.join(", ")}` : "";
     const attested = r.provenance.level === "attested" ? `  attested by ${r.provenance.principal}` : "";
     const sealed = r.attested === true ? `  sealed by ${(r.data?.[RECORD_SEAL_FIELD] as { signer: string }).signer}` : "";
-    lines.push(`${(r.id ?? "-").padEnd(idWidth)}  ${(r.state ?? "-").padEnd(stateWidth)}  ${title}${superseded}${remediated}${attested}${sealed}${flag}`);
+    const uncommitted = r.worktree === "new" || r.worktree === "modified" ? `  (${r.worktree}, uncommitted)` : "";
+    lines.push(`${(r.id ?? "-").padEnd(idWidth)}  ${(r.state ?? "-").padEnd(stateWidth)}  ${title}${superseded}${remediated}${attested}${sealed}${uncommitted}${flag}`);
     if (r.ready !== undefined) {
       const blocked = (r.blockedBy ?? []).map((b) => `${b.id} (${b.state ?? "unknown"})`).join(", ");
       const implemented = (r.implements ?? []).map((d) => `${d.id} (${d.state ?? "unknown"})`).join(", ");
@@ -745,9 +830,16 @@ function formatRecords(records: RecordView[], summary: { total: number; valid: n
       lines.push(`${" ".repeat(idWidth + 2)}quorum ${q.agreed} of ${q.need} agreed, ${verdict}; ${q.notCounted.length} not counted${concerns}`);
     }
   }
+  for (const path of checkout?.deleted ?? []) lines.push(`${"-".padEnd(idWidth)}  ${"-".padEnd(stateWidth)}  ${path}  (deleted, uncommitted)`);
   lines.push(
     `${summary.total} records${at ? ` at ${at.slice(0, 8)}` : ""}: ${summary.valid} valid, ${summary.invalid} invalid, ${summary.superseded} superseded`,
   );
+  if (checkout) {
+    const branch = checkout.branch ?? "a detached HEAD";
+    const head = checkout.head ? ` at ${checkout.head.slice(0, 8)}` : " with no commits";
+    const base = checkout.base ? `, forked from ${checkout.base.slice(0, 8)} of ${checkout.baseFrom}` : "";
+    lines.push(`working tree on ${branch}${head}${base}`);
+  }
   return lines.join("\n");
 }
 

package/src/workspace/records-close.schema.json

@@ -173,6 +173,7 @@
                 "record-closed",
                 "write-scope-member",
                 "write-scope-kind",
+                "write-scope-class-unknown",
                 "agent-unknown",
                 "record-unparseable",
                 "record-schema-invalid",

package/src/workspace/records-new.schema.json

@@ -167,7 +167,9 @@
                 "ratify-quorum-not-met",
                 "write-scope-member",
                 "write-scope-kind",
+                "write-scope-class-unknown",
                 "agent-unknown",
+                "principal-unidentified",
                 "record-unparseable",
                 "record-schema-invalid",
                 "record-id-duplicate",

package/src/workspace/records-review.schema.json

@@ -261,7 +261,9 @@
                 "session-not-open",
                 "write-scope-member",
                 "write-scope-kind",
+                "write-scope-class-unknown",
                 "agent-unknown",
+                "principal-unidentified",
                 "record-unparseable",
                 "record-schema-invalid",
                 "record-id-duplicate",

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

@@ -0,0 +1,171 @@
+/**
+ * Uncommitted records in the read contract (#3160): each record of a
+ * working-tree read says whether HEAD holds it as it is, the document names
+ * the branch, head and base, and `--uncommitted` lists only what HEAD
+ * doesn't hold. The documents validate against records.schema.json.
+ */
+
+import { execFileSync } from "node:child_process";
+import { cpSync, mkdtempSync, readFileSync, realpathSync, rmSync, statSync, unlinkSync, 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 { CONFORMANCE_FIXTURE_DIR, UNCOMMITTED_DECISION } from "./conformance";
+import { queryRecords, type RecordsDocument } from "./records-cli";
+import schema from "./records.schema.json";
+
+const validate = new Ajv2020({ strict: true, allErrors: true }).compile(schema);
+const KIND = "decisions/decision.kind.mjs";
+
+type Result = Extract<RecordsDocument, { records: unknown }>;
+
+function result(doc: RecordsDocument): Result {
+  expect(validate(doc), JSON.stringify(validate.errors, null, 2)).toBe(true);
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+  return doc;
+}
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+
+const GIT_ENV = { ...process.env, GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_NOSYSTEM: "1" };
+function git(cwd: string, ...args: string[]): string {
+  return execFileSync("git", ["-c", "user.name=t", "-c", "user.email=t@localhost", "-c", "commit.gpgsign=false", ...args], { cwd, env: GIT_ENV, encoding: "utf-8" }).trim();
+}
+
+const DECIDED = readFileSync(join(CONFORMANCE_FIXTURE_DIR, "decisions", "fix-001-how-the-app-is-deployed.md"), "utf-8");
+/** A decided record with id `fix-<n>`. */
+const decided = (n: string) => DECIDED.replace('id: "fix-001"', `id: "fix-${n}"`);
+/** A proposed record with id `fix-<n>`. */
+const proposed = (n: string) => UNCOMMITTED_DECISION.text.replace('id: "fix-002"', `id: "fix-${n}"`);
+const file = (n: string) => `decisions/fix-${n}-a-record.md`;
+
+/** A directory with the decision kind and its schema, and no records. */
+function kindDir(): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-records-uncommitted-")));
+  scratch.push(root);
+  cpSync(join(CONFORMANCE_FIXTURE_DIR, "decisions"), join(root, "decisions"), { recursive: true, filter: (src) => !src.endsWith(".md") });
+  return root;
+}
+
+/** A repository whose main holds fix-001, fix-003 and fix-005, on a work branch one commit past main. */
+function repository(): { root: string; main: string } {
+  const root = kindDir();
+  for (const n of ["001", "003", "005"]) writeFileSync(join(root, file(n)), decided(n));
+  git(root, "init", "--quiet", "--initial-branch=main");
+  git(root, "add", "-A");
+  git(root, "commit", "--quiet", "-m", "records");
+  const main = git(root, "rev-parse", "HEAD");
+  git(root, "checkout", "--quiet", "-b", "chant/work/w-1");
+  writeFileSync(join(root, "notes.txt"), "work\n");
+  git(root, "add", "notes.txt");
+  git(root, "commit", "--quiet", "-m", "work");
+  return { root, main };
+}
+
+describe("records in the working tree (#3160)", () => {
+  test("each record is committed, modified or new against HEAD, and the checkout names its branch, head, base and deleted records", async () => {
+    const { root, main } = repository();
+    writeFileSync(join(root, file("001")), `${decided("001")}\nA line kept in the working tree.\n`);
+    writeFileSync(join(root, file("002")), proposed("002"));
+    writeFileSync(join(root, file("004")), proposed("004"));
+    git(root, "add", file("004"));
+    unlinkSync(join(root, file("003")));
+    const head = git(root, "rev-parse", "HEAD");
+
+    const doc = result(await queryRecords({ kind: KIND, cwd: root }));
+    expect(doc.uncommitted).toBe(false);
+    expect(doc.records.map((r) => [r.id, r.worktree])).toEqual([
+      ["fix-001", "modified"],
+      ["fix-002", "new"],
+      ["fix-004", "new"],
+      ["fix-005", "committed"],
+    ]);
+    expect(doc.checkout).toEqual({ branch: "chant/work/w-1", head, base: main, baseFrom: "main", deleted: [file("003")] });
+
+    const only = result(await queryRecords({ kind: KIND, cwd: root, uncommitted: true }));
+    expect(only.uncommitted).toBe(true);
+    expect(only.records.map((r) => [r.id, r.worktree])).toEqual([
+      ["fix-001", "modified"],
+      ["fix-002", "new"],
+      ["fix-004", "new"],
+    ]);
+    expect(only.checkout).toEqual(doc.checkout);
+    expect(only.summary).toEqual({ total: 3, valid: 3, invalid: 0, superseded: 0 });
+  });
+
+  test("a record changed back to what HEAD holds, or touched without a change, is committed, and the read leaves the index alone", async () => {
+    const { root } = repository();
+    const path = join(root, file("001"));
+    writeFileSync(path, decided("001"));
+    const index = join(root, ".git", "index");
+    const before = { bytes: readFileSync(index), mtime: statSync(index).mtimeMs };
+    const doc = result(await queryRecords({ kind: KIND, cwd: root, uncommitted: true }));
+    expect(doc.records).toEqual([]);
+    expect(doc.checkout?.deleted).toEqual([]);
+    expect(readFileSync(index).equals(before.bytes)).toBe(true);
+    expect(statSync(index).mtimeMs).toBe(before.mtime);
+  });
+
+  test("--base names the target the base is forked from", async () => {
+    const { root } = repository();
+    const head = git(root, "rev-parse", "HEAD");
+    const doc = result(await queryRecords({ kind: KIND, cwd: root, base: "HEAD" }));
+    expect(doc.checkout).toMatchObject({ head, base: head, baseFrom: "flag" });
+  });
+
+  test("a detached HEAD has no branch, and a repository with no commits has no head and only new records", async () => {
+    const { root } = repository();
+    git(root, "checkout", "--quiet", "--detach");
+    expect(result(await queryRecords({ kind: KIND, cwd: root })).checkout?.branch).toBeNull();
+
+    const empty = kindDir();
+    writeFileSync(join(empty, file("001")), decided("001"));
+    git(empty, "init", "--quiet", "--initial-branch=main");
+    const doc = result(await queryRecords({ kind: KIND, cwd: empty, uncommitted: true }));
+    expect(doc.checkout).toEqual({ branch: "main", head: null, base: null, baseFrom: null, deleted: [] });
+    expect(doc.records.map((r) => r.worktree)).toEqual(["new"]);
+  });
+
+  test("a read at a revision has no checkout and no worktree", async () => {
+    const { root } = repository();
+    writeFileSync(join(root, file("002")), proposed("002"));
+    const doc = result(await queryRecords({ kind: KIND, cwd: root, at: "HEAD" }));
+    expect(doc.checkout).toBeUndefined();
+    expect(doc.records.every((r) => r.worktree === undefined)).toBe(true);
+    await expect(queryRecords({ kind: KIND, cwd: root, at: "HEAD", uncommitted: true })).rejects.toThrow(/takes no --at/);
+  });
+
+  test("outside git a read has no checkout, and --uncommitted fails with not-a-git-repository", async () => {
+    const root = kindDir();
+    writeFileSync(join(root, file("001")), decided("001"));
+    const doc = result(await queryRecords({ kind: KIND, cwd: root }));
+    expect(doc.checkout).toBeUndefined();
+    expect(doc.records[0].worktree).toBeUndefined();
+    const failed = await queryRecords({ kind: KIND, cwd: root, uncommitted: true });
+    expect(validate(failed)).toBe(true);
+    expect(failed).toMatchObject({ error: { code: "not-a-git-repository" } });
+  });
+
+  test("the schema holds an --uncommitted document to its promise", () => {
+    const head = "a".repeat(40);
+    const doc = {
+      $schema: schema.$id,
+      contract: 1,
+      kind: { name: "decision", schema: "urn:x", file: KIND },
+      at: null,
+      current: false,
+      uncommitted: true,
+      checkout: { branch: "main", head, base: head, baseFrom: "main", deleted: [] },
+      records: [{ id: "fix-001", path: file("001"), state: "decided", valid: true, reasons: [], supersededBy: null, remediatedBy: [], data: {}, worktree: "new" }],
+      summary: { total: 1, valid: 1, invalid: 0, superseded: 0 },
+    };
+    expect(validate(doc)).toBe(true);
+    expect(validate({ ...doc, records: [{ ...doc.records[0], worktree: "committed" }] })).toBe(false);
+    const { checkout: _checkout, ...noCheckout } = doc;
+    expect(validate(noCheckout)).toBe(false);
+  });
+});