@intentset/cli 0.3.0 → 0.5.0

package/src/agents.ts

@@ -0,0 +1,185 @@
+/**
+ * The agent guide `intentset init` writes to `.intentset/agents.md`: what a
+ * coding agent does, before and after it changes code, to keep the model
+ * current (Core §10: load the owning slice first, update affected semantics
+ * and checks in the same review, never self-approve). A repository points its
+ * agents at it from AGENTS.md or CLAUDE.md.
+ *
+ * Generated rather than copied, so the commands, the required sections and
+ * the trailer can never disagree with the toolchain that wrote it.
+ */
+import { ARTIFACT_TYPES, REQUIRED_SECTIONS } from "@intentset/core";
+import { UNCHANGED_TRAILER } from "./git.ts";
+import { TOOL } from "./output.ts";
+
+export const AGENT_GUIDE_PATH = ".intentset/agents.md";
+
+/** The lines a repository adds so its agents read the guide, by the file that takes each. */
+export const AGENT_POINTERS: Array<[string, string]> = [
+  ["CLAUDE.md", `@${AGENT_GUIDE_PATH}`],
+  ["AGENTS.md", `Before changing code, read ${AGENT_GUIDE_PATH} and follow it.`],
+];
+
+/** How the guide runs the CLI: through the package manager the repository uses. */
+export type PackageManager = "npm" | "pnpm";
+
+/** pnpm when the repository says so (its lockfile, workspace file or packageManager field), npm otherwise. */
+export function detectPackageManager(files: {
+  has(path: string): boolean;
+  packageJson: string | null;
+}): PackageManager {
+  if (files.has("pnpm-lock.yaml") || files.has("pnpm-workspace.yaml")) return "pnpm";
+  try {
+    const manager = (JSON.parse(files.packageJson ?? "{}") as { packageManager?: unknown }).packageManager;
+    if (typeof manager === "string" && manager.startsWith("pnpm@")) return "pnpm";
+  } catch {
+    // An unreadable package.json says nothing about the package manager.
+  }
+  return "npm";
+}
+
+export function agentGuide(scope: readonly string[], manager: PackageManager = "npm"): string {
+  const run = manager === "pnpm" ? "pnpm exec intentset" : "npx intentset";
+  const isolated =
+    manager === "pnpm"
+      ? "pnpm dlx --package=@intentset/cli --package=typescript@7 intentset ..."
+      : "npx -p @intentset/cli -p typescript@7 intentset ...";
+  const where = scope.map((pattern) => `\`${pattern}\``).join(", ");
+  const sections = ARTIFACT_TYPES.map(
+    (type) => `| ${type} | ${REQUIRED_SECTIONS[type].map((section) => `## ${section}`).join(", ")} |`,
+  );
+  return `# Keeping the product model current
+
+This repository keeps an Intentset product model: one Markdown file per product behavior, rule, scenario, slice,
+contract, decision, verification and knowledge article, under ${where}. The records say what the product promises,
+which code delivers it and how it is checked. You keep them true as part of every change, in the same commit as the
+code, so that people can review what the product does without reading every line of what changed.
+
+Written by \`intentset init\` (${TOOL.name} ${TOOL.version}). To refresh it, delete it and run
+\`${run} init --agents\`.
+
+## Before you change code
+
+Load what the code you are about to change promises:
+
+\`\`\`sh
+${run} context <a file you will edit>
+${run} context <an ID, such as BEH-...>
+\`\`\`
+
+The result is the owning slice, its behaviors, rules, scenarios, contracts, decisions and checks, with their paths.
+Keep the change inside that slice, and reach other slices only through the contracts it consumes.
+
+## When behavior changes
+
+Update the records in the same change as the code.
+
+- A changed promise: edit the behavior's Behavior, Preconditions and Outcomes, and the rules and scenarios it
+  touches.
+- A new promise: add a behavior record with \`status: draft\`, and add its ID to \`implements\` on the slice that
+  delivers it. New rules, scenarios and verifications start as drafts too.
+- New code that no slice claims: add a slice record with \`status: draft\`, its claims and its entrypoints. While a
+  slice is a draft, the paths it plans may not exist yet.
+- A changed check: a verification record names the test that checks a claim. Change the test and its record
+  together, and add one for a behavior or rule that has none.
+
+Write each link once, on the record that points: a behavior is \`governedBy\` its rules, a scenario \`illustrates\`
+a behavior, a slice \`implements\` behaviors, a verification \`verifies\` what it checks. Never write the reverse.
+
+## When behavior does not change
+
+A refactor changes code and no behavior. Say so in the commit message with a trailer naming each slice:
+
+\`\`\`text
+${UNCHANGED_TRAILER}: SLICE-...
+\`\`\`
+
+\`intentset review\` lists every slice whose code changed while its records did not, and this trailer is how a
+commit answers it. Use it only when no behavior changed: a reviewer reads it as your claim.
+
+## Never
+
+- Set a status to approved, implemented or released, or publish knowledge. People approve, and validation passing
+  is not approval.
+- Change an ID or reuse a retired one. Moving or renaming a file keeps its ID; splitting a behavior retires the old
+  one with \`replacedBy\`.
+- Name an owner, audience, release, role, edition or flag that is not in \`.intentset/registries.yaml\`. Ask
+  instead.
+- Commit run evidence (\`.intentset/evidence/\`) or an export. They describe one commit and are stale once it lands.
+- Edit generated output: an export, the Atlas, published pages.
+
+## Before you finish
+
+\`\`\`sh
+${run} validate
+${run} architecture check     # when .intentset/architecture.yaml exists
+${run} review --base main
+\`\`\`
+
+Fix every error. Resolve each slice \`review\` lists under "Code changed, records unchanged", by updating its records
+or with the trailer. The architecture check needs TypeScript 7; on an earlier TypeScript, run the toolchain as
+\`${isolated}\`.
+
+## Record format
+
+A record is Markdown with YAML frontmatter under \`intentset:\`, and its level-one heading repeats its title. An
+existing record of the same type in this repository is the best template; a new behavior looks like this, one
+recognizable promise including how it fails:
+
+\`\`\`markdown
+---
+markset: 0
+intentset:
+  spec: '0.1'
+  profile: intentset/behavior/0.1
+  id: BEH-AREA-NAME
+  type: behavior
+  title: The promise in a few words, such as Schedule an assessment
+  status: draft
+  owner: <an owner from the registry>
+  visibility: internal
+  audiences: [engineering, product]
+  parent: CAP-...
+  links:
+    governedBy: [RULE-...]
+  availability:
+    products: [PRD-...]
+    releases: [<a release from the registry>]
+    roles: [<a role>]
+    editions: [<an edition>]
+    flags: []
+---
+
+# The promise in a few words, such as Schedule an assessment
+
+## Behavior
+Who acts, and what the system does.
+
+## Preconditions
+What must be true first.
+
+## Outcomes
+Success: what happens. Failure: what is rejected, and what is left unchanged.
+\`\`\`
+
+A knowledge record explains behaviors, rules or capabilities to one audience, in that audience's words rather than
+the behavior's. It may carry \`tips\`: one plain sentence per explained ID, at most 160 characters, which the
+product shows beside the control that delivers that behavior once the knowledge is reviewed and published.
+
+\`\`\`yaml
+  links:
+    explains: [BEH-AREA-NAME, RULE-AREA-LIMIT]
+  tips:
+    BEH-AREA-NAME: What this control does, in one sentence.
+    RULE-AREA-LIMIT: The limit, and what happens at it.
+\`\`\`
+
+Each type requires these level-two sections:
+
+| Type | Required sections |
+|---|---|
+${sections.join("\n")}
+
+The specifications are at https://intentset.org/specifications/.
+`;
+}

package/src/commands/context.ts

@@ -9,7 +9,12 @@
  *
  * `restricted` artifacts are withheld unless asked for, and the report says
  * how many, so a short context never reads as a complete one. Never writes.
+ *
+ * Given a file rather than an ID, it reads the context of the slice whose
+ * claims include the file, since an agent about to edit code knows the file
+ * and not the ID of what it promises.
  */
+import { isAbsolute, relative, resolve, sep } from "node:path";
 import {
   type Artifact,
   type ContextArtifact,
@@ -21,8 +26,29 @@ import {
 } from "@intentset/core";
 import { count, formatDiagnostic, type Io, json, snapshotLine, TOOL } from "../output.ts";
 import type { Session } from "../session.ts";
+import { claimingSlices } from "../slices.ts";
 import { unresolved, validationLine, validationSummary } from "./shared.ts";
 
+/**
+ * The artifact a `context` argument names: itself when it is an ID, else the
+ * one slice whose claims include it as a file path, relative to the working
+ * directory. Several claiming slices are an overlap VSA reports; the caller
+ * is asked to choose.
+ */
+export function resolveTarget(
+  session: Session,
+  argument: string,
+  cwd: string,
+): { id: string; path: string | null } | { path: string; slices: string[] } {
+  const graph = session.result.graph;
+  if (graph.artifacts.has(argument)) return { id: argument, path: null };
+  const absolute = isAbsolute(argument) ? argument : resolve(cwd, argument);
+  const path = relative(session.repo.root, absolute).split(sep).join("/");
+  const slices = claimingSlices(graph, path).map((slice) => slice.meta.id);
+  if (slices.length === 1) return { id: slices[0], path };
+  return { path, slices };
+}
+
 const HEADINGS: Record<ContextRole, string> = {
   start: "Start",
   owner: "Owning slice",
@@ -39,12 +65,22 @@ const HEADINGS: Record<ContextRole, string> = {
 
 export function contextCommand(
   session: Session,
-  id: string,
+  argument: string,
   includeRestricted: boolean,
   asJson: boolean,
   io: Io,
 ): number {
   const { graph } = session.result;
+  const target = resolveTarget(session, argument, io.cwd);
+  if ("slices" in target && target.slices.length > 1) {
+    io.stderr(
+      `intentset context: ${target.path} is claimed by ${target.slices.join(" and ")}, an overlap VSA reports; ` +
+        "name one of them.\n",
+    );
+    return 2;
+  }
+  const via = "id" in target ? target.path : null;
+  const id = "id" in target ? target.id : argument;
   const bundle = contextFor(graph, id, { includeRestricted });
   if (bundle === null) {
     const diagnostic = unresolved(id, session);
@@ -73,6 +109,7 @@ export function contextCommand(
         snapshot: session.snapshot,
         validation: validationSummary(session, session.level),
         start: id,
+        ...(via === null ? {} : { resolvedFrom: via }),
         included: bundle.artifacts.length,
         withheld: bundle.withheld,
         restrictedIncluded: includeRestricted,
@@ -93,6 +130,7 @@ export function contextCommand(
     `# Context for ${id}`,
     "",
     `Bounded engineering context (Core §10) for ${start.meta.type} ${id}, "${start.meta.title}".`,
+    ...(via === null ? [] : ["", `${via} is claimed by ${id}, so this is that slice's context.`]),
     "",
     `- ${snapshotLine(session.snapshot)}`,
     `- ${validationLine(session, session.level)}`,

package/src/commands/init.ts

@@ -1,16 +1,20 @@
 /**
  * `intentset init`: the one command that writes, and it only creates. It
- * writes `.intentset/config.yaml` and an empty-but-valid
- * `.intentset/registries.yaml`, and with `--example` the scheduling example's
- * records under `product/scheduling/` and its registries in place of the
- * empty ones. Every target is checked before anything is written, and each
- * file is opened with exclusive create, so an existing file is never
+ * writes `.intentset/config.yaml`, an empty-but-valid
+ * `.intentset/registries.yaml` and `.intentset/agents.md`, the guide coding
+ * agents follow to keep the model current, and with `--example` the
+ * scheduling example's records under `product/scheduling/` and its
+ * registries in place of the empty ones. `--agents` writes the guide alone,
+ * for a repository initialized before there was one, with the scope its
+ * config already names. Every target is checked before anything is written,
+ * and each file is opened with exclusive create, so an existing file is never
  * overwritten, not even by a race.
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { compareStrings, DEFAULT_IGNORE, readConfig, readRegistries } from "@intentset/core";
+import { AGENT_GUIDE_PATH, AGENT_POINTERS, agentGuide, detectPackageManager } from "../agents.ts";
 import type { Io } from "../output.ts";
 import { CONFIG_PATH } from "../repository.ts";
 
@@ -22,6 +26,8 @@ export interface InitOptions {
   root?: string;
   repository?: string;
   example: boolean;
+  /** Write only the agent guide. */
+  agentsOnly?: boolean;
 }
 
 /** YAML double-quoted scalar; the strict reader takes JSON's escapes. */
@@ -82,6 +88,8 @@ export async function initCommand(options: InitOptions, io: Io): Promise<number>
     return 2;
   }
 
+  if (options.agentsOnly === true) return writeGuideOnly(root, io);
+
   // Everything to write, decided before anything is written.
   const files = new Map<string, string>([[CONFIG_PATH, configText(repository)]]);
   let registries = EMPTY_REGISTRIES_TEXT;
@@ -103,6 +111,7 @@ export async function initCommand(options: InitOptions, io: Io): Promise<number>
     }
   }
   files.set(REGISTRIES_PATH, registries);
+  files.set(AGENT_GUIDE_PATH, agentGuide([DEFAULT_INIT_SCOPE], managerAt(root)));
 
   // What init writes must read back clean, or it has handed the user a broken repository.
   const config = readConfig(files.get(CONFIG_PATH) as string, CONFIG_PATH);
@@ -112,6 +121,37 @@ export async function initCommand(options: InitOptions, io: Io): Promise<number>
     return 2;
   }
 
+  if (!create(root, files, io)) return 2;
+  const scope = options.example ? `${files.size - 3} example records in scope` : "an empty scope";
+  io.stdout(`Initialized ${quote(repository)} with ${scope}. Next: intentset validate\n`);
+  pointers(io);
+  return 0;
+}
+
+/** `init --agents`: the guide alone, for the scope the repository's config names, or the default with no config. */
+function writeGuideOnly(root: string, io: Io): number {
+  let scope = [DEFAULT_INIT_SCOPE];
+  const configFile = join(root, CONFIG_PATH);
+  if (existsSync(configFile)) {
+    const { config, diagnostics } = readConfig(readFileSync(configFile, "utf8"), CONFIG_PATH);
+    if (diagnostics.length === 0 && config.scope.length > 0) scope = config.scope;
+  }
+  if (!create(root, new Map([[AGENT_GUIDE_PATH, agentGuide(scope, managerAt(root))]]), io)) return 2;
+  pointers(io);
+  return 0;
+}
+
+/** The package manager the repository at root uses, so the guide's commands are ones it can run. */
+function managerAt(root: string) {
+  const packageJson = join(root, "package.json");
+  return detectPackageManager({
+    has: (path) => existsSync(join(root, path)),
+    packageJson: existsSync(packageJson) ? readFileSync(packageJson, "utf8") : null,
+  });
+}
+
+/** Create every file or none: refuse if any exists, then write each with exclusive create. */
+function create(root: string, files: Map<string, string>, io: Io): boolean {
   const ordered = [...files.keys()].sort(compareStrings);
   const existing = ordered.filter((path) => existsSync(join(root, path)));
   if (existing.length > 0) {
@@ -119,7 +159,7 @@ export async function initCommand(options: InitOptions, io: Io): Promise<number>
       `intentset init: refusing to overwrite ${existing.join(", ")}; init only creates files.\n` +
         "Remove them first if a fresh start is what you want.\n",
     );
-    return 2;
+    return false;
   }
   for (const path of ordered) {
     const target = join(root, path);
@@ -128,11 +168,15 @@ export async function initCommand(options: InitOptions, io: Io): Promise<number>
       writeFileSync(target, files.get(path) as string, { flag: "wx" });
     } catch (error) {
       io.stderr(`intentset init: could not create ${path}: ${(error as Error).message}\n`);
-      return 2;
+      return false;
     }
     io.stdout(`created ${path}\n`);
   }
-  const scope = options.example ? `${files.size - 2} example records in scope` : "an empty scope";
-  io.stdout(`Initialized ${quote(repository)} with ${scope}. Next: intentset validate\n`);
-  return 0;
+  return true;
+}
+
+/** How to point a repository's agents at the guide. init never edits a file it did not create, so it says rather than does. */
+function pointers(io: Io): void {
+  io.stdout(`\nPoint your coding agents at ${AGENT_GUIDE_PATH} with one line in the file they read:\n`);
+  for (const [file, line] of AGENT_POINTERS) io.stdout(`  ${file}: ${line}\n`);
 }

package/src/commands/publish.ts

@@ -1,8 +1,9 @@
 /**
  * `intentset publish` (Core §9): the deny-by-default projection of reviewed
  * knowledge for one audience, release and entitlement, as generated Markset
- * with provenance, optional HTML, the index a customer tool may read, and
- * retrieval chunks that carry the same filters. Refuses outright when the
+ * with provenance, optional HTML, the index a customer tool may read, the
+ * help file a product's runtime reads, and retrieval chunks that carry the
+ * same filters. Refuses outright when the
  * graph does not validate. Review pins are read as written: a real pin is a
  * literal hash, and the fixtures' `@current` is never bound here, so an
  * unbound one reads as changed. Writes only into the --out directory, which
@@ -11,7 +12,7 @@
 import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { type Visibility, sortDiagnostics } from "@intentset/core";
-import { type PublicationRequest, publish, toChunks } from "@intentset/publisher";
+import { HELP_FILE, type PublicationRequest, publish, toChunks } from "@intentset/publisher";
 import { count, formatDiagnostic, type Io } from "../output.ts";
 import { outputDirProblem, outputProblem } from "../outputs.ts";
 import type { Session } from "../session.ts";
@@ -86,6 +87,7 @@ export function publishCommand(session: Session, options: PublishCliOptions, io:
       if (document.html !== undefined) outputs.set(`${document.id}.html`, document.html);
     }
     outputs.set("index.json", `${JSON.stringify(published.index, null, 2)}\n`);
+    outputs.set(HELP_FILE, `${JSON.stringify(published.help, null, 2)}\n`);
     const chunks = toChunks(published.documents);
     outputs.set("chunks.jsonl", chunks.map((chunk) => `${JSON.stringify(chunk)}\n`).join(""));
   }

package/src/commands/review.ts

@@ -7,13 +7,19 @@
  * touches, a changed record to its own artifact and a changed source file
  * through the claiming slice to that slice's behaviors, each start's direct
  * dependents shown apart from its candidates. Markdown by default. Read-only.
+ *
+ * It also lists every slice whose code changed while none of the records that
+ * describe it did (Core §10: an agent updates affected semantics in the same
+ * review). A refactor changes code and no behavior, so the list is a prompt,
+ * not an error: a commit says so with an Intentset-Unchanged trailer, and
+ * `--fail-on-drift` fails only on slices no commit has spoken for.
  */
 import { type Graph, impact, compareStrings } from "@intentset/core";
-import { type Changes, changedFiles, chooseBase } from "../git.ts";
-import { matchGlob } from "../glob.ts";
+import { acknowledgedSlices, type Changes, changedFiles, chooseBase, UNCHANGED_TRAILER } from "../git.ts";
 import { count, formatDiagnostic, type Io, json, snapshotLine, TOOL } from "../output.ts";
 import { levelJson, levelSections } from "../reports.ts";
 import type { Session } from "../session.ts";
+import { activeSlices, claimingSlices, describingRecords, isSliceCode } from "../slices.ts";
 import { pathText, REACHABILITY_NOTE } from "./impact.ts";
 
 export interface Attribution {
@@ -27,9 +33,6 @@ export interface Attribution {
 export function attribute(graph: Graph, changed: readonly string[]): { starts: Attribution[]; unattributed: string[] } {
   const byPath = new Map<string, string>();
   for (const [id, artifact] of graph.artifacts) byPath.set(artifact.path, id);
-  const slices = [...graph.artifacts.values()]
-    .filter((a) => a.meta.type === "slice" && a.meta.status !== "retired" && a.meta.slice !== undefined)
-    .sort((a, b) => compareStrings(a.meta.id, b.meta.id));
   const starts = new Map<string, Set<string>>();
   const add = (id: string, reason: string) => {
     const set = starts.get(id) ?? new Set<string>();
@@ -43,7 +46,7 @@ export function attribute(graph: Graph, changed: readonly string[]): { starts: A
       add(id, `${path} is its record`);
       continue;
     }
-    const owners = slices.filter((slice) => slice.meta.slice?.claims.some((claim) => matchGlob(claim.path, path)));
+    const owners = claimingSlices(graph, path);
     let attributed = false;
     for (const slice of owners) {
       for (const behavior of slice.meta.links.implements ?? []) {
@@ -62,9 +65,46 @@ export function attribute(graph: Graph, changed: readonly string[]): { starts: A
   };
 }
 
+export interface Drift {
+  slice: string;
+  title: string;
+  /** The slice's changed code: files its source, backend or contract claims match. */
+  code: string[];
+  /** The records that describe the slice, none of which changed. */
+  records: string[];
+  /** True when a commit after the base names the slice in an Intentset-Unchanged trailer. */
+  acknowledged: boolean;
+}
+
+export const DRIFT_NOTE =
+  "Slices whose code changed while none of the records that describe them did: the slice, its behaviors, their " +
+  "rules, scenarios and verifications, its contracts and their decisions. If behavior changed, update those records " +
+  `in this change. If it did not, say so in a commit with the trailer \`${UNCHANGED_TRAILER}: <slice ID>\`.`;
+
+/** Each slice whose code is among the changed files while none of its describing records is, sorted by slice ID. */
+export function drift(graph: Graph, changed: readonly string[], acknowledged: ReadonlySet<string>): Drift[] {
+  const records = new Set([...graph.artifacts.values()].map((artifact) => artifact.path));
+  const touched = new Set(changed);
+  const out: Drift[] = [];
+  for (const slice of activeSlices(graph)) {
+    const code = changed.filter((path) => !records.has(path) && isSliceCode(slice, path));
+    if (code.length === 0) continue;
+    const describing = describingRecords(graph, slice);
+    if (describing.some((id) => touched.has(graph.artifacts.get(id)?.path ?? ""))) continue;
+    out.push({
+      slice: slice.meta.id,
+      title: slice.meta.title,
+      code,
+      records: describing,
+      acknowledged: acknowledged.has(slice.meta.id),
+    });
+  }
+  return out;
+}
+
 export function reviewCommand(
   session: Session,
-  options: { base?: string; levelReason: string },
+  options: { base?: string; levelReason: string; failOnDrift?: boolean },
   asJson: boolean,
   io: Io,
 ): number {
@@ -80,6 +120,9 @@ export function reviewCommand(
   if ("unavailable" in chosen) changes.baseUnavailable = chosen.unavailable;
   const changed = [...new Set([...changes.committed, ...changes.uncommitted])].sort(compareStrings);
   const { starts, unattributed } = attribute(graph, changed);
+  const drifted = drift(graph, changed, new Set(acknowledgedSlices(repo.root, base)));
+  const failing = options.failOnDrift === true && drifted.some((item) => !item.acknowledged);
+  const exit = session.errors > 0 || failing ? 1 : 0;
   const impacts = starts.map(({ start, because }) => {
     const artifact = graph.artifacts.get(start);
     const report = impact(graph, start);
@@ -108,10 +151,11 @@ export function reviewCommand(
         ...levelJson(session),
         note: REACHABILITY_NOTE,
         impact: impacts,
+        drift: drifted,
         unattributed,
       }),
     );
-    return session.errors > 0 ? 1 : 0;
+    return exit;
   }
 
   const baseLine =
@@ -147,9 +191,22 @@ export function reviewCommand(
     if (item.candidates.length === 0) out.push("- none");
     for (const hit of item.candidates) out.push(`- ${hit.id} (${hit.type}): \`${pathText(item.start, hit)}\``);
   }
+  const open = drifted.filter((item) => !item.acknowledged).length;
+  out.push("", `## Code changed, records unchanged (${drifted.length}, ${open} not acknowledged)`, "", DRIFT_NOTE);
+  if (drifted.length === 0) out.push("", "None.");
+  for (const item of drifted) {
+    out.push("", `### ${item.slice}: ${item.title}`, "");
+    out.push(
+      item.acknowledged
+        ? `- Acknowledged: a commit since the base says this changes no behavior (${UNCHANGED_TRAILER}).`
+        : "- Not acknowledged: update the records below, or say in a commit that no behavior changed.",
+    );
+    out.push(...item.code.map((path) => `- Code changed: ${path}`));
+    out.push(`- Records describing it, none changed: ${item.records.join(", ")}`);
+  }
   out.push("", `## Changed files no artifact accounts for (${unattributed.length})`, "");
   if (unattributed.length === 0) out.push("None.");
   else out.push(...unattributed.map((path) => `- ${path}`));
   io.stdout(`${out.join("\n")}\n`);
-  return session.errors > 0 ? 1 : 0;
+  return exit;
 }

package/src/git.ts

@@ -79,3 +79,18 @@ export function changedFiles(root: string, base: Base | null): Omit<Changes, "ba
     uncommitted: [...new Set(uncommitted)].sort(compareStrings),
   };
 }
+
+/**
+ * The trailer a commit carries to say it changes a slice's code without
+ * changing its behavior: `Intentset-Unchanged: SLICE-A, SLICE-B`. A reviewer
+ * reads it in the commit, so the claim is made where it can be questioned.
+ */
+export const UNCHANGED_TRAILER = "Intentset-Unchanged";
+
+/** The slice IDs named in an Intentset-Unchanged trailer of any commit after the base, sorted. */
+export function acknowledgedSlices(root: string, base: Base | null): string[] {
+  if (base === null) return [];
+  const out = git(root, ["log", `--format=%(trailers:key=${UNCHANGED_TRAILER},valueonly)`, `${base.commit}..HEAD`]);
+  if (out === null) return [];
+  return [...new Set(out.split(/[\s,]+/).filter((id) => id !== ""))].sort(compareStrings);
+}