@intentset/cli 0.2.0 → 0.4.0

package/src/agents.ts

@@ -0,0 +1,150 @@
+/**
+ * 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.`],
+];
+
+export function agentGuide(scope: readonly string[]): string {
+  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
+\`npx intentset init --agents\`.
+
+## Before you change code
+
+Load what the code you are about to change promises:
+
+\`\`\`sh
+npx intentset context <a file you will edit>
+npx intentset 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
+npx intentset validate
+npx intentset architecture check     # when .intentset/architecture.yaml exists
+npx intentset 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
+\`npx -p @intentset/cli -p typescript@7 intentset ...\`.
+
+## 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.
+\`\`\`
+
+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 } 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]));
 
   // 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,28 @@ 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)]]), io)) return 2;
+  pointers(io);
+  return 0;
+}
+
+/** 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 +150,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 +159,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/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/commands/serve.ts

@@ -65,9 +65,9 @@ export function atlasOf(session: Session): Map<string, string> {
 
 /**
  * Every file a build read as text, and the directories holding them, absolute:
- * a newer modification time on any of them means rebuild. A directory's time
- * changes when a file is added to it or removed, which is how a new record is
- * noticed.
+ * a different modification time or size on any of them means rebuild. A
+ * directory's time changes when a file is added to it or removed, which is how
+ * a new record is noticed.
  */
 function watched(session: Session, evidence: readonly string[]): string[] {
   const { repo } = session;
@@ -93,14 +93,31 @@ function watched(session: Session, evidence: readonly string[]): string[] {
   return [...files];
 }
 
-function changedSince(paths: readonly string[], since: number): string | null {
-  for (const path of paths) {
-    try {
-      if (statSync(path).mtimeMs > since) return path;
-    } catch {
-      // Absent now: a file the build read was removed, or an optional file never existed.
-    }
+/**
+ * Each path's modification time and size, or "absent". Compared with itself
+ * later rather than with a clock: a wall-clock start time in whole milliseconds
+ * is earlier than a file written in the same millisecond, and a file system's
+ * clock is coarser than the process's, so comparing the two calls a file
+ * written before the build "changed" (the 0.3.0 release run did, on Linux).
+ */
+function stamps(paths: readonly string[]): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const path of paths) out.set(path, stamp(path));
+  return out;
+}
+
+function stamp(path: string): string {
+  try {
+    const stat = statSync(path);
+    return `${stat.mtimeMs}:${stat.size}`;
+  } catch {
+    // Absent: a file the build read was removed, or an optional file never existed.
+    return "absent";
   }
+}
+
+function changedSince(recorded: ReadonlyMap<string, string>): string | null {
+  for (const [path, before] of recorded) if (stamp(path) !== before) return path;
   return null;
 }
 
@@ -118,7 +135,6 @@ export function requestPath(url: string | undefined): string | null {
 
 export async function serveCommand(options: ServeOptions, sessionOptions: SessionOptions, io: Io): Promise<number> {
   const given = sessionOptions.evidence;
-  let builtAt = Date.now();
   const first = openSession("serve", sessionOptions, io);
   if (typeof first === "number") return first;
   let session: Session = first;
@@ -131,6 +147,7 @@ export async function serveCommand(options: ServeOptions, sessionOptions: Sessio
   }
   const evidence = () => evidenceFiles(session.repo.root, io.cwd, given);
   let paths = watched(session, evidence());
+  let recorded = stamps(paths);
   const levelLine = `${count(session.result.graph.artifacts.size, "artifact")}, ${count(session.errors, "error")}, ${count(session.warnings, "warning")} at ${session.level}${
     session.evidence === undefined
       ? `; no run records were given or found in ${EVIDENCE_DIR}/, so L3 was not checked`
@@ -141,9 +158,10 @@ export async function serveCommand(options: ServeOptions, sessionOptions: Sessio
 
   /** Rebuild when a file the last build read has changed; keep serving the last good build if a rebuild fails. */
   const refresh = (): string | null => {
-    const changed = changedSince(paths, builtAt);
+    const changed = changedSince(recorded);
     if (changed === null) return null;
-    const started = Date.now();
+    // Stamped before the build reads anything, so an edit made while it runs shows as a change next time.
+    const before = stamps(paths);
     const next = openSession("serve", sessionOptions, io);
     if (typeof next === "number") return "the repository could not be read; the terminal says why";
     try {
@@ -152,8 +170,10 @@ export async function serveCommand(options: ServeOptions, sessionOptions: Sessio
       return `the Atlas could not be built: ${(error as Error).message}`;
     }
     session = next;
-    builtAt = started;
     paths = watched(session, evidence());
+    const after = stamps(paths);
+    for (const [path, value] of before) if (after.has(path)) after.set(path, value);
+    recorded = after;
     io.stdout(
       `rebuilt: ${changed.slice(session.repo.root.length + 1) || "."} changed. ${snapshotLine(session.snapshot)}\n`,
     );

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);
+}