@intentset/cli 0.6.0 → 0.7.0

package/src/commands/migrate.ts

@@ -0,0 +1,136 @@
+/**
+ * `intentset migrate --to 0.2` (Core §1): moves the records the model reads from the specifications' `0.1` to `0.2`
+ * by rewriting two values in each record's frontmatter, `intentset.spec` and `intentset.profile`, which Core §4
+ * requires to agree with it. It reads the same records every other command reads (the files the configured scope
+ * matches), changes those two lines and nothing else, byte for byte, and keeps the quoting each line used. A tree
+ * with uncommitted changes to tracked files is refused unless `--allow-dirty` says otherwise, so the rewrite is a
+ * diff of its own that git can undo. Other files (`.intentset/agents.md`, which carries an example record) are not
+ * records and are left to their author.
+ */
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { sortDiagnostics } from "@intentset/core";
+import { trackedChanges } from "../git.ts";
+import { formatDiagnostic, type Io } from "../output.ts";
+import { type CarrierName, CONFIG_PATH, findRoot, loadRepository } from "../repository.ts";
+
+/** The specification versions this command moves between. */
+export const MIGRATE_FROM = "0.1";
+export const MIGRATE_TO = "0.2";
+
+export interface MigrateOptions {
+  root?: string;
+  to?: string;
+  allowDirty?: boolean;
+  carrier: CarrierName;
+}
+
+/** A message when the options cannot be run, before anything is read; null when they can. */
+export function migrateUsageProblem(options: Pick<MigrateOptions, "to">): string | null {
+  if (options.to === undefined) return `--to is required: the only target is ${MIGRATE_TO}, from ${MIGRATE_FROM}`;
+  if (options.to !== MIGRATE_TO) {
+    return `--to ${options.to}: the only target is ${MIGRATE_TO}, which moves records written for ${MIGRATE_FROM}`;
+  }
+  return null;
+}
+
+const SPEC_LINE = /^(\s+spec:\s*)(['"]?)(\d+\.\d+)\2(\s*(?:#.*)?)$/;
+const PROFILE_LINE = /^(\s+profile:\s*)(['"]?)intentset\/([a-z0-9-]+)\/(\d+\.\d+)\2(\s*(?:#.*)?)$/;
+
+/**
+ * The record's text moved from `from` to `to`, or null when it declares another value. Only lines inside the
+ * `intentset:` mapping of the frontmatter, and only `spec` and `profile`, are rewritten; line endings are kept.
+ */
+export function migrateText(
+  source: string,
+  frontmatter: { line: number; text: string },
+  from: string,
+  to: string,
+): string | null {
+  const lines = source.split("\n");
+  const first = frontmatter.line - 1;
+  const last = first + frontmatter.text.split("\n").length;
+  let inIntentset = false;
+  let childIndent: number | null = null;
+  let specSeen = false;
+  const edits = new Map<number, string>();
+  for (let i = first; i < last && i < lines.length; i++) {
+    const raw = lines[i];
+    const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+    const eol = raw.endsWith("\r") ? "\r" : "";
+    if (/^\S/.test(line)) {
+      inIntentset = /^intentset:\s*(#.*)?$/.test(line);
+      childIndent = null;
+      continue;
+    }
+    if (!inIntentset || line.trim() === "") continue;
+    const indent = line.length - line.trimStart().length;
+    childIndent ??= indent;
+    if (indent !== childIndent) continue;
+    const spec = SPEC_LINE.exec(line);
+    if (spec !== null) {
+      if (spec[3] !== from) return null;
+      specSeen = true;
+      edits.set(i, `${spec[1]}${spec[2]}${to}${spec[2]}${spec[4]}${eol}`);
+      continue;
+    }
+    const profile = PROFILE_LINE.exec(line);
+    if (profile !== null && profile[4] === from) {
+      edits.set(i, `${profile[1]}${profile[2]}intentset/${profile[3]}/${to}${profile[2]}${profile[5]}${eol}`);
+    }
+  }
+  if (!specSeen) return null;
+  for (const [i, text] of edits) lines[i] = text;
+  return lines.join("\n");
+}
+
+export function migrateCommand(options: MigrateOptions, io: Io): number {
+  const root = findRoot(io.cwd, options.root);
+  if (root === null) {
+    const where = options.root === undefined ? "this directory or any above it" : options.root;
+    io.stderr(`intentset migrate: no ${CONFIG_PATH} in ${where}.\n`);
+    return 2;
+  }
+  if (options.allowDirty !== true) {
+    const changes = trackedChanges(root);
+    if (changes === null) {
+      io.stderr(
+        "intentset migrate: this is not a git work tree, so the rewrite could not be undone; pass --allow-dirty to migrate anyway.\n",
+      );
+      return 2;
+    }
+    if (changes.length > 0) {
+      io.stderr(
+        `intentset migrate: ${changes.length} tracked file${changes.length === 1 ? " has" : "s have"} uncommitted changes. ` +
+          "Commit or stash them so the rewrite is a diff on its own, or pass --allow-dirty.\n",
+      );
+      return 2;
+    }
+  }
+  const repo = loadRepository(root, options.carrier);
+  if (!repo.configOk) {
+    io.stderr("intentset migrate: the configuration has errors, so the scope is unknown.\n");
+    for (const d of sortDiagnostics(repo.diagnostics)) io.stderr(formatDiagnostic(d));
+    return 2;
+  }
+  let moved = 0;
+  let current = 0;
+  let other = 0;
+  for (const input of repo.inputs) {
+    if (input.frontmatter === null) continue;
+    const text = migrateText(input.source, input.frontmatter, MIGRATE_FROM, MIGRATE_TO);
+    if (text === null) {
+      if (/^\s+spec:\s*['"]?0\.2['"]?\s*(#.*)?$/m.test(input.frontmatter.text)) current++;
+      else other++;
+      continue;
+    }
+    if (text === input.source) continue;
+    writeFileSync(join(root, input.path), text);
+    moved++;
+  }
+  io.stdout(
+    `intentset migrate: moved ${moved} record${moved === 1 ? "" : "s"} from ${MIGRATE_FROM} to ${MIGRATE_TO}` +
+      `${current > 0 ? `; ${current} already ${MIGRATE_TO}` : ""}${other > 0 ? `; ${other} declare neither (left as they are)` : ""}.\n`,
+  );
+  return 0;
+}

package/src/git.ts

@@ -94,3 +94,28 @@ export function acknowledgedSlices(root: string, base: Base | null): string[] {
   if (out === null) return [];
   return [...new Set(out.split(/[\s,]+/).filter((id) => id !== ""))].sort(compareStrings);
 }
+
+/**
+ * The files that differ between `commit` and the working tree (tracked changes, staged or not, and untracked files
+ * .gitignore does not exclude), sorted, as paths relative to the CLI's root; or null when `commit` is not an ancestor of
+ * HEAD or git cannot say. One `git diff --name-only`, so the evidence report can list what changed outside every
+ * subject (Core §8) without computing anything per file.
+ */
+export function changedSince(root: string, commit: string): string[] | null {
+  if (git(root, ["merge-base", "--is-ancestor", commit, "HEAD"]) === null) return null;
+  const diff = git(root, ["diff", "--relative", "--name-only", "-z", commit]);
+  if (diff === null) return null;
+  const untracked = paths(git(root, ["ls-files", "-z", "--others", "--exclude-standard"]));
+  return [...new Set([...paths(diff), ...untracked])].sort(compareStrings);
+}
+
+/**
+ * The tracked files that differ from HEAD, staged or not, as `git status` lists them; an empty list for a clean
+ * tree, and null when this is not a git work tree or git cannot say. Untracked files are not counted: a command that
+ * rewrites tracked files asks only that its rewrite be a diff on its own.
+ */
+export function trackedChanges(root: string): string[] | null {
+  const out = git(root, ["status", "--porcelain", "--untracked-files=no", "-z"]);
+  if (out === null) return null;
+  return out.split("\0").filter((entry) => entry !== "");
+}

package/src/index.ts

@@ -1,8 +1,10 @@
 /**
  * @intentset/cli as a library: `main` for running the command in-process,
- * and the repository loader and pattern matcher it is built on.
+ * the agent guide `init` writes (intentset.org serves it from the same
+ * generator), and the repository loader and pattern matcher it is built on.
  */
 export { main, USAGE } from "./main.ts";
+export { AGENT_GUIDE_PATH, AGENT_POINTERS, agentGuide, type PackageManager } from "./agents.ts";
 export type { Io } from "./output.ts";
 export { matchAny, matchGlob } from "./glob.ts";
 export { CONFIG_PATH, enumerate, findRoot, loadRepository, readCommit, type Repository } from "./repository.ts";

package/src/main.ts

@@ -5,26 +5,30 @@
  *
  * Exit codes (Core §11, ADR 0004): 0 no errors, 1 validation errors, 2
  * invocation or tool failure. validate, graph, architecture check, impact,
- * context, review, serve and mcp never write; graph --out, architecture
+ * context, review, evidence stale, serve, mcp and guide never write; graph --out, architecture
  * check --write-baseline, evidence import --out, publish --out and serve
- * --out write only what they name; init only creates.
+ * --out write only what they name; init only creates; migrate rewrites the
+ * two version values of each record's frontmatter and nothing else.
  */
 import { parseArgs } from "node:util";
 import type { Mode } from "@intentset/architecture";
-import { LEVELS, type Level } from "@intentset/core";
+import { EVIDENCE_BINDINGS, type EvidenceBinding, LEVELS, type Level } from "@intentset/core";
 import type { RunScope } from "@intentset/verification";
 import { architectureCommand } from "./commands/architecture.ts";
 import { contextCommand } from "./commands/context.ts";
 import { evidenceImportCommand, evidenceUsageProblem } from "./commands/evidence.ts";
+import { evidenceStaleCommand, evidenceStaleUsageProblem } from "./commands/evidence-stale.ts";
 import { graphCommand, graphUsageProblem, parseRelease } from "./commands/graph.ts";
+import { guideCommand } from "./commands/guide.ts";
 import { impactCommand } from "./commands/impact.ts";
 import { initCommand } from "./commands/init.ts";
+import { migrateCommand, migrateUsageProblem } from "./commands/migrate.ts";
 import { mcpCommand, mcpUsageProblem } from "./commands/mcp.ts";
 import { publishCommand, publishUsageProblem } from "./commands/publish.ts";
 import { reviewCommand } from "./commands/review.ts";
 import { serveCommand } from "./commands/serve.ts";
 import { validateCommand } from "./commands/validate.ts";
-import type { Io } from "./output.ts";
+import { type Io, TOOL } from "./output.ts";
 import { type CarrierName, CARRIERS, findRoot } from "./repository.ts";
 import { EVIDENCE_DIR, evidenceFiles, openSession, type SessionOptions } from "./session.ts";
 
@@ -34,68 +38,96 @@ export const USAGE = `usage: intentset <command> [options]
 
 commands
   init [--repository <name>] [--example] [--agents]
-                            create .intentset/config.yaml, an empty .intentset/registries.yaml and
-                            .intentset/agents.md, the guide that tells coding agents how to keep the
-                            model current; --example adds the scheduling example under
-                            product/scheduling/; --agents writes only the guide, for a repository
-                            already initialized. Never overwrites a file.
-  validate                  every check the level asks for; exit 1 when any diagnostic is an error
+                            create .intentset/config.yaml, an empty .intentset/registries.yaml
+                            and .intentset/agents.md, the guide that tells coding agents how to
+                            keep the model current; --example adds the scheduling example under
+                            product/scheduling/; --agents writes only the guide, for a
+                            repository already initialized. Never overwrites a file.
+  guide                     print that guide for this repository, for the scope its config
+                            names, without writing anything
+  validate                  every check the level asks for; exit 1 when any diagnostic is an
+                            error
   graph [--format json] [--include-bodies] [--release <product>:<label>] [--out <file>]
         [--generated-at <time>] [--report evidence|knowledge|impact|ownership|all]...
         [--include-restricted]
-                            print the intentset/export/0.3 envelope, or write it to --out;
+                            print the intentset/export/0.4 envelope, or write it to --out;
                             each --report adds a section (ownership needs L2, evidence L3; all
                             is every one the level reads). Restricted artifacts are withheld
                             and counted unless --include-restricted
   architecture check [--mode migration|strict] [--baseline <file>] [--write-baseline <file>]
                             ownership, claims, imports, layers and regions (default level L2)
-  evidence import --from vitest|node-tap <report> --out <file> --product <ID> --release <label>
+  evidence import --from vitest|playwright|node-tap <report> --out <file> --product <ID>
+        --release <label>
         [--environment <text>] [--started-at <time>] [--finished-at <time>] [--uri-base <uri>]
         [--tool-version <v>]
                             turn a test report into run records bound to this commit and graph
-  impact <ID>               what depends on an artifact: direct, candidates, review context, ancestors
+  evidence stale [--release <product>:<label>] [--check] [--binding <subject|commit>]
+        [--format list|json|playwright|vitest|node-test]
+                            what needs a run: the automated verifications whose evidence is
+                            not a current pass, as a table, as JSON, or as the arguments that
+                            make a test runner run only those tests; never writes; --check
+                            exits 1 when any needs a run
+  impact <ID>               what depends on an artifact: direct, candidates, review context,
+                            ancestors
   context <ID|path> [--include-restricted]
-                            the bounded engineering context of an artifact, with paths and bodies;
-                            given a file a slice claims, the context of that slice
+                            the bounded engineering context of an artifact, with paths and
+                            bodies; given a file a slice claims, the context of that slice
   review [--base <ref>] [--fail-on-drift]
-                            the local review report: checks, coverage, the impact of what changed,
-                            and each slice whose code changed while its records did not;
-                            --fail-on-drift exits 1 for any such slice no commit acknowledged with
-                            an Intentset-Unchanged trailer
+                            the local review report: checks, coverage, the impact of what
+                            changed, and each slice whose code changed while its records did
+                            not; --fail-on-drift exits 1 for any such slice no commit
+                            acknowledged with an Intentset-Unchanged trailer
   publish --visibility <v> --audience <a> --product <ID> --release <r> --role <r> --edition <e>
         [--flag <f>]... [--authorized-internal] [--authorized-restricted] --out <dir> [--html]
         [--published-at <time>]
-                            reviewed knowledge for one audience and release, as Markset with provenance
+                            reviewed knowledge for one audience and release, as Markset with
+                            provenance
   serve [--port <n>] [--host <address>] [--out <dir>]
-                            the Atlas, the internal review pages, on http://127.0.0.1:3000/ (rebuilt
-                            when a file changes), or written to --out; runs at L2, or L3 with run records
+                            the Atlas, the internal review pages, on http://127.0.0.1:3000/
+                            (rebuilt when a file changes), or written to --out; runs at L2, or
+                            L3 with run records
+  migrate --to 0.2 [--allow-dirty]
+                            move the records the model reads from specifications 0.1 to 0.2:
+                            rewrites intentset.spec and intentset.profile in each record's
+                            frontmatter and nothing else, and says how many. Refuses a tree
+                            with uncommitted changes to tracked files unless --allow-dirty
   mcp --mode engineering [--include-restricted]
-  mcp --mode customer --visibility <public|customer> --audience <a> --product <ID> --release <r>
-        --role <r> --edition <e> [--flag <f>]...
+  mcp --mode customer --visibility <public|customer> --audience <a> --product <ID>
+        --release <r> --role <r> --edition <e> [--flag <f>]...
                             the read-only MCP server on stdio: the engineering graph, or one
                             publication made in memory as publish makes it, and nothing else
 
 options
-  --root <dir>              repository root (default: the nearest directory at or above this one
-                            holding .intentset/config.yaml)
+  --root <dir>              repository root (default: the nearest directory at or above this
+                            one holding .intentset/config.yaml)
   --json                    machine-readable output, keys in canonical order
   --carrier <markset|plain> how documents are read (default markset)
   --level <L1..L4>          conformance level; each includes those below it (default L1):
                             L2 adds architecture, L3 evidence, L4 publication readiness
-  --evidence <file>         L3 and above: run records to read, repeatable (default: every *.json in
-                            ${EVIDENCE_DIR}/, which holds local output and is not committed)
+  --evidence <file>         L3 and above: run records to read, repeatable (default: every
+                            *.json in ${EVIDENCE_DIR}/, which holds local output and is not
+                            committed)
   --product <ID> --release <label>
-                            L3 and above: the exact scope evidence is assessed for (default: every scope)
+                            L3 and above: the exact scope evidence is assessed for (default:
+                            every scope)
+  --binding <subject|commit>
+                            L3 and above, and evidence import: how run evidence is judged
+                            current, overriding evidence.binding in the configuration (default:
+                            subject where slices claim files, else commit). Subject keeps a
+                            record current while what it checked is unchanged; commit only at
+                            the commit it ran at
   --mode <migration|strict> --baseline <file>
-                            L2 and above: whether a baseline of known violations applies, and which
-                            (for mcp, --mode names the server's mode instead)
+                            L2 and above: whether a baseline of known violations applies, and
+                            which (for mcp, --mode names the server's mode instead)
   -h, --help                show this help
+  --version                 print "intentset <version>", the checker version a report names
 
-exit codes: 0 no errors, 1 validation errors (or, with review --fail-on-drift, unacknowledged drift),
-            2 invocation or tool failure`;
+exit codes: 0 no errors, 1 validation errors (or, with review --fail-on-drift,
+            unacknowledged drift), 2 invocation or tool failure`;
 
 const COMMANDS = [
   "init",
+  "guide",
   "validate",
   "graph",
   "architecture",
@@ -105,13 +137,16 @@ const COMMANDS = [
   "review",
   "publish",
   "serve",
+  "migrate",
   "mcp",
 ];
 
-const GLOBAL = ["root", "json", "carrier", "level", "help"];
-const LEVEL_OPTIONS = ["evidence", "product", "release", "mode", "baseline"];
+const GLOBAL = ["root", "json", "carrier", "level", "help", "version"];
+const LEVEL_OPTIONS = ["evidence", "product", "release", "mode", "baseline", "binding"];
 const COMMAND_OPTIONS: Record<string, string[]> = {
   init: ["repository", "example", "agents"],
+  guide: [],
+  migrate: ["to", "allow-dirty"],
   validate: LEVEL_OPTIONS,
   graph: [
     "format",
@@ -124,9 +159,13 @@ const COMMAND_OPTIONS: Record<string, string[]> = {
     "evidence",
     "mode",
     "baseline",
+    "binding",
   ],
   architecture: ["mode", "baseline", "write-baseline"],
   evidence: [
+    "format",
+    "check",
+    "evidence",
     "from",
     "out",
     "product",
@@ -136,6 +175,7 @@ const COMMAND_OPTIONS: Record<string, string[]> = {
     "finished-at",
     "uri-base",
     "tool-version",
+    "binding",
   ],
   impact: LEVEL_OPTIONS,
   context: ["include-restricted", ...LEVEL_OPTIONS],
@@ -172,9 +212,9 @@ const COMMAND_OPTIONS: Record<string, string[]> = {
 };
 
 /** Positional arguments after the command: a fixed subcommand, then how many more. */
-const POSITIONALS: Record<string, { sub?: string; count: number; what?: string }> = {
-  architecture: { sub: "check", count: 0 },
-  evidence: { sub: "import", count: 1, what: "a report file" },
+const POSITIONALS: Record<string, { subs?: Record<string, number>; count: number; what?: string }> = {
+  architecture: { subs: { check: 0 }, count: 0 },
+  evidence: { subs: { import: 1, stale: 0 }, count: 0, what: "a report file" },
   impact: { count: 1, what: "an artifact ID" },
   context: { count: 1, what: "an artifact ID or a file path" },
 };
@@ -189,6 +229,10 @@ export async function main(argv: string[], io: Io): Promise<number> {
   }
   const { values, positionals, tokens } = parsed;
   const [command, ...rest] = positionals;
+  if (values.version && !values.help) {
+    io.stdout(`${TOOL.name} ${TOOL.version}\n`);
+    return 0;
+  }
   if (values.help || command === undefined) {
     io.stdout(`${USAGE}\n`);
     return values.help ? 0 : 2;
@@ -211,14 +255,48 @@ export async function main(argv: string[], io: Io): Promise<number> {
 
   const shape = POSITIONALS[command] ?? { count: 0 };
   let args = rest;
-  if (shape.sub !== undefined) {
-    if (args[0] !== shape.sub) return usage(`the only subcommand is "${command} ${shape.sub}"`);
+  let wanted = shape.count;
+  let sub: string | undefined;
+  if (shape.subs !== undefined) {
+    const names = Object.keys(shape.subs);
+    sub = args[0];
+    if (sub === undefined || !Object.hasOwn(shape.subs, sub)) {
+      return usage(
+        names.length === 1
+          ? `the only subcommand is "${command} ${names[0]}"`
+          : `the subcommands are ${names.map((name) => `"${command} ${name}"`).join(" and ")}`,
+      );
+    }
+    wanted = shape.subs[sub];
     args = args.slice(1);
   }
-  if (args.length < shape.count) return usage(`${shape.what} is required`);
-  if (args.length > shape.count) {
-    const hint = shape.count === 0 ? " (use --root <dir> to name the repository)" : "";
-    return usage(`unexpected argument "${args[shape.count]}"${hint}`);
+  if (args.length < wanted) return usage(`${shape.what} is required`);
+  if (args.length > wanted) {
+    const hint = wanted === 0 ? " (use --root <dir> to name the repository)" : "";
+    return usage(`unexpected argument "${args[wanted]}"${hint}`);
+  }
+  if (command === "evidence") {
+    // Each subcommand takes its own options, though one list allows them all.
+    const own =
+      sub === "stale"
+        ? ["format", "check", "evidence", "release", "binding"]
+        : [
+            "from",
+            "out",
+            "product",
+            "release",
+            "environment",
+            "started-at",
+            "finished-at",
+            "uri-base",
+            "tool-version",
+            "binding",
+          ];
+    for (const token of tokens) {
+      if (token.kind === "option" && COMMAND_OPTIONS.evidence.includes(token.name) && !own.includes(token.name)) {
+        return usage(`--${token.name} is not an option of evidence ${sub}`);
+      }
+    }
   }
 
   const carrier = values.carrier ?? "markset";
@@ -235,6 +313,15 @@ export async function main(argv: string[], io: Io): Promise<number> {
   if (command !== "mcp" && values.mode !== undefined && values.mode !== "migration" && values.mode !== "strict") {
     return usage(`--mode ${values.mode}: the modes are migration and strict`);
   }
+  if (command === "guide") return guideCommand({ root: values.root }, io);
+  if (command === "migrate") {
+    const problem = migrateUsageProblem({ to: values.to });
+    if (problem !== null) return usage(problem);
+    return migrateCommand(
+      { root: values.root, to: values.to, allowDirty: values["allow-dirty"], carrier: carrier as CarrierName },
+      io,
+    );
+  }
   if (command === "init") {
     if (values.agents && values.example)
       return usage("--agents writes only the guide; it does not combine with --example");
@@ -246,8 +333,8 @@ export async function main(argv: string[], io: Io): Promise<number> {
 
   // Evidence scope: --product with --release, or graph's --release <product>:<label>.
   let scope: RunScope | null = null;
-  if (command !== "evidence" && command !== "publish" && command !== "mcp") {
-    if (command === "graph") {
+  if ((command !== "evidence" || sub === "stale") && command !== "publish" && command !== "mcp") {
+    if (command === "graph" || command === "evidence") {
       const release = values.release === undefined ? null : parseRelease(values.release);
       scope = release === null ? null : { product: release.product, release: release.label };
     } else if ((values.product === undefined) !== (values.release === undefined)) {
@@ -257,6 +344,9 @@ export async function main(argv: string[], io: Io): Promise<number> {
     }
   }
 
+  if (values.binding !== undefined && !(EVIDENCE_BINDINGS as readonly string[]).includes(values.binding)) {
+    return usage(`--binding ${values.binding}: the bindings are ${EVIDENCE_BINDINGS.join(" and ")}`);
+  }
   const sessionOptions = (level: Level): SessionOptions => ({
     root: values.root,
     carrier: carrier as CarrierName,
@@ -265,6 +355,7 @@ export async function main(argv: string[], io: Io): Promise<number> {
     baseline: values.baseline,
     evidence: values.evidence,
     scope,
+    binding: values.binding as EvidenceBinding | undefined,
   });
 
   switch (command) {
@@ -294,6 +385,21 @@ export async function main(argv: string[], io: Io): Promise<number> {
       return architectureCommand(session, { writeBaseline: values["write-baseline"] }, values.json, io);
     }
     case "evidence": {
+      if (sub === "stale") {
+        if (levelGiven === "L1" || levelGiven === "L2") {
+          return usage("evidence is judged at L3 and above, where run records are read");
+        }
+        const staleOptions = {
+          release: values.release,
+          format: values.format,
+          check: values.check,
+          json: values.json,
+        };
+        const checked = evidenceStaleUsageProblem(staleOptions);
+        if ("problem" in checked) return usage(checked.problem);
+        const session = openSession("evidence stale", sessionOptions(levelGiven ?? "L3"), io);
+        return typeof session === "number" ? session : evidenceStaleCommand(session, checked.format, staleOptions, io);
+      }
       const options = {
         from: values.from,
         report: args[0],
@@ -305,6 +411,7 @@ export async function main(argv: string[], io: Io): Promise<number> {
         finishedAt: values["finished-at"],
         uriBase: values["uri-base"],
         toolVersion: values["tool-version"],
+        binding: values.binding as EvidenceBinding | undefined,
       };
       const problem = evidenceUsageProblem(options);
       if (problem !== null) return usage(problem);
@@ -407,6 +514,7 @@ function parse(argv: string[]) {
       carrier: { type: "string" },
       level: { type: "string" },
       help: { type: "boolean", short: "h", default: false },
+      version: { type: "boolean", default: false },
       repository: { type: "string" },
       example: { type: "boolean", default: false },
       agents: { type: "boolean", default: false },
@@ -422,7 +530,9 @@ function parse(argv: string[]) {
       product: { type: "string" },
       mode: { type: "string" },
       baseline: { type: "string" },
+      binding: { type: "string" },
       "write-baseline": { type: "string" },
+      check: { type: "boolean", default: false },
       from: { type: "string" },
       environment: { type: "string" },
       "started-at": { type: "string" },
@@ -441,6 +551,8 @@ function parse(argv: string[]) {
       "published-at": { type: "string" },
       port: { type: "string" },
       host: { type: "string" },
+      to: { type: "string" },
+      "allow-dirty": { type: "boolean", default: false },
     },
   });
 }

package/src/reports.ts

@@ -35,6 +35,17 @@ function ofCounts(part: ClaimCounts, whole: ClaimCounts): string {
   ].join(", ");
 }
 
+/** Which binding judged the evidence, and why (Core §8). */
+function bindingLine(run: EvidenceRun): string {
+  const { binding, reason } = run.binding;
+  if (binding === "subject") {
+    return `Binding: subject (${reason === "default" ? "the default, since slices claim files" : "as configured"}); a record is current while the subject it checked is unchanged`;
+  }
+  return reason === "no-slices"
+    ? "Binding: commit, because no slice claims files and there is no subject to bind to (EVID004); a record is current only at the assessed commit and graph hash"
+    : "Binding: commit, as configured; a record is current only at the assessed commit and graph hash";
+}
+
 export function evidenceLines(run: EvidenceRun): string[] {
   const { coverage, classification } = run.check;
   const snap = run.snapshot;
@@ -46,6 +57,7 @@ export function evidenceLines(run: EvidenceRun): string[] {
   const d = coverage.denominator;
   const lines = [
     `Evidence: ${count(run.records, "run record")} from ${from}; assessed at ${snap.commit === null ? "no commit" : `commit ${snap.commit}`}, graph ${snap.graphHash}, for ${scope}`,
+    bindingLine(run),
     `Coverage over ${count(d.behaviors, "behavior")}, ${count(d.rules, "rule")} and ${count(d.scenarios, "scenario")} that are not retired:`,
     `  linked:    ${ofCounts(coverage.linked, d)}  (${coverage.measures.linked})`,
     `  verified:  ${ofCounts(coverage.verified, d)}  (${coverage.measures.verified})`,
@@ -57,7 +69,7 @@ export function evidenceLines(run: EvidenceRun): string[] {
   if (ids.length === 0) lines.push("  none");
   for (const id of ids) {
     const v = classification.verifications[id];
-    lines.push(`  ${id}  ${v.method}  ${v.status}${v.note === undefined ? "" : `  (${v.note})`}`);
+    lines.push(`  ${id}  ${v.method}  ${v.status}  [${v.binding}]${v.note === undefined ? "" : `  (${v.note})`}`);
   }
   lines.push(
     `Not checked, so not a pass (${coverage.unresolved.length}):${coverage.unresolved.length === 0 ? " none" : ""}`,
@@ -94,9 +106,21 @@ export function levelJson(session: Session): Record<string, unknown> {
     const { files, records, snapshot, check } = session.evidence;
     const verifications: Record<string, unknown> = {};
     for (const [id, v] of Object.entries(check.classification.verifications)) {
-      verifications[id] = { method: v.method, status: v.status, ...(v.note === undefined ? {} : { note: v.note }) };
+      verifications[id] = {
+        method: v.method,
+        status: v.status,
+        binding: v.binding,
+        ...(v.note === undefined ? {} : { note: v.note }),
+      };
     }
-    out.evidence = { files, records, snapshot, coverage: check.coverage, verifications };
+    out.evidence = {
+      files,
+      records,
+      binding: session.evidence.binding,
+      snapshot: { commit: snapshot.commit, graphHash: snapshot.graphHash, scope: snapshot.scope ?? null },
+      coverage: check.coverage,
+      verifications,
+    };
   }
   if (session.publication !== undefined) out.publication = { checked: session.publication.checked };
   return out;