@intentset/cli 0.3.0 → 0.4.0

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

package/src/main.ts

@@ -33,10 +33,12 @@ export type { Io } from "./output.ts";
 export const USAGE = `usage: intentset <command> [options]
 
 commands
-  init [--repository <name>] [--example]
-                            create .intentset/config.yaml and an empty .intentset/registries.yaml;
-                            --example adds the scheduling example under product/scheduling/.
-                            Never overwrites a file.
+  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
   graph [--format json] [--include-bodies] [--release <product>:<label>] [--out <file>]
         [--generated-at <time>] [--report evidence|knowledge|impact|ownership|all]...
@@ -52,9 +54,14 @@ commands
         [--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
-  context <ID> [--include-restricted]
-                            the bounded engineering context of an artifact, with paths and bodies
-  review [--base <ref>]     the local review report: checks, coverage, and the impact of what changed
+  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
+  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
   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>]
@@ -84,7 +91,8 @@ options
                             (for mcp, --mode names the server's mode instead)
   -h, --help                show this help
 
-exit codes: 0 no errors, 1 validation errors, 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",
@@ -103,7 +111,7 @@ const COMMANDS = [
 const GLOBAL = ["root", "json", "carrier", "level", "help"];
 const LEVEL_OPTIONS = ["evidence", "product", "release", "mode", "baseline"];
 const COMMAND_OPTIONS: Record<string, string[]> = {
-  init: ["repository", "example"],
+  init: ["repository", "example", "agents"],
   validate: LEVEL_OPTIONS,
   graph: [
     "format",
@@ -131,7 +139,7 @@ const COMMAND_OPTIONS: Record<string, string[]> = {
   ],
   impact: LEVEL_OPTIONS,
   context: ["include-restricted", ...LEVEL_OPTIONS],
-  review: ["base", ...LEVEL_OPTIONS],
+  review: ["base", "fail-on-drift", ...LEVEL_OPTIONS],
   serve: ["port", "host", "out", ...LEVEL_OPTIONS],
   mcp: [
     "mode",
@@ -168,7 +176,7 @@ const POSITIONALS: Record<string, { sub?: string; count: number; what?: string }
   architecture: { sub: "check", count: 0 },
   evidence: { sub: "import", count: 1, what: "a report file" },
   impact: { count: 1, what: "an artifact ID" },
-  context: { count: 1, what: "an artifact ID" },
+  context: { count: 1, what: "an artifact ID or a file path" },
 };
 
 export async function main(argv: string[], io: Io): Promise<number> {
@@ -228,7 +236,12 @@ export async function main(argv: string[], io: Io): Promise<number> {
     return usage(`--mode ${values.mode}: the modes are migration and strict`);
   }
   if (command === "init") {
-    return initCommand({ root: values.root, repository: values.repository, example: values.example }, io);
+    if (values.agents && values.example)
+      return usage("--agents writes only the guide; it does not combine with --example");
+    return initCommand(
+      { root: values.root, repository: values.repository, example: values.example, agentsOnly: values.agents },
+      io,
+    );
   }
 
   // Evidence scope: --product with --release, or graph's --release <product>:<label>.
@@ -321,7 +334,12 @@ export async function main(argv: string[], io: Io): Promise<number> {
       }
       const session = openSession(command, sessionOptions(level), io);
       if (typeof session === "number") return session;
-      return reviewCommand(session, { base: values.base, levelReason: reason }, values.json, io);
+      return reviewCommand(
+        session,
+        { base: values.base, levelReason: reason, failOnDrift: values["fail-on-drift"] },
+        values.json,
+        io,
+      );
     }
     case "serve": {
       const port = values.port === undefined ? 3000 : Number(values.port);
@@ -391,6 +409,8 @@ function parse(argv: string[]) {
       help: { type: "boolean", short: "h", default: false },
       repository: { type: "string" },
       example: { type: "boolean", default: false },
+      agents: { type: "boolean", default: false },
+      "fail-on-drift": { type: "boolean", default: false },
       format: { type: "string" },
       "include-bodies": { type: "boolean", default: false },
       release: { type: "string" },

package/src/slices.ts

@@ -0,0 +1,54 @@
+/**
+ * Slices, the code they claim and the records that describe them, for
+ * `review`'s list of slices whose code changed while their records did not
+ * (Core §10) and for `context <path>`.
+ *
+ * A slice's code is what its `source`, `backend` and `contract` claims match;
+ * its `verification` and `documentation` claims are checks and prose, not
+ * implementation. The records that describe a slice are the slice itself, the
+ * behaviors it implements, the rules that govern them, the scenarios that
+ * illustrate them, the verifications of any of those, the contracts it
+ * exposes, and the decisions that inform the slice, its behaviors or its
+ * contracts. Knowledge is left out: it explains the model to an audience, and
+ * review pins already mark it for review when the model changes.
+ */
+import { type Artifact, compareStrings, type Graph } from "@intentset/core";
+import { matchGlob } from "./glob.ts";
+
+const CODE_CLAIMS = new Set(["source", "backend", "contract"]);
+
+/** Every slice that is not retired and has slice metadata, sorted by ID. */
+export function activeSlices(graph: Graph): Artifact[] {
+  return [...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));
+}
+
+/** The slices with any claim matching `path`, sorted by ID. */
+export function claimingSlices(graph: Graph, path: string): Artifact[] {
+  return activeSlices(graph).filter((slice) => slice.meta.slice?.claims.some((claim) => matchGlob(claim.path, path)));
+}
+
+/** True when one of the slice's source, backend or contract claims matches `path`. */
+export function isSliceCode(slice: Artifact, path: string): boolean {
+  return slice.meta.slice?.claims.some((claim) => CODE_CLAIMS.has(claim.kind) && matchGlob(claim.path, path)) ?? false;
+}
+
+/** The IDs of the records that describe a slice, the slice included, sorted. Only IDs present in the graph. */
+export function describingRecords(graph: Graph, slice: Artifact): string[] {
+  const out = new Set<string>([slice.meta.id]);
+  const targets = (id: string, kind: string) =>
+    (graph.out.get(id) ?? []).filter((edge) => edge.kind === kind).map((edge) => edge.to);
+  const sources = (id: string, kind: string) =>
+    (graph.in.get(id) ?? []).filter((edge) => edge.kind === kind).map((edge) => edge.from);
+
+  const behaviors = targets(slice.meta.id, "implements");
+  const rules = behaviors.flatMap((id) => targets(id, "governedBy"));
+  const scenarios = behaviors.flatMap((id) => sources(id, "illustrates"));
+  const claims = [...behaviors, ...rules, ...scenarios];
+  const verifications = claims.flatMap((id) => sources(id, "verifies"));
+  const contracts = targets(slice.meta.id, "exposes");
+  const decisions = [slice.meta.id, ...behaviors, ...contracts].flatMap((id) => targets(id, "informedBy"));
+  for (const id of [...claims, ...verifications, ...contracts, ...decisions]) out.add(id);
+  return [...out].filter((id) => graph.artifacts.has(id)).sort(compareStrings);
+}