flagrm 0.3.0 → 0.4.0

package/dist/core/doctor.js

@@ -1,6 +1,6 @@
 /**
  * `flagrm doctor`: is this repository ready for an agent to remove a flag?
- * Config, build/test commands, git, .gitignore, the installed skills and
+ * Config, build/test/lint commands, git, .gitignore, the installed skills and
  * hook, and baselines left behind by abandoned removals.
  */
 import fs from "node:fs";
@@ -15,8 +15,20 @@ import { installedSkillVersion, SKILLS, stopHookState, TOOL_SKILL_DIRS } from ".
 import { packageVersion } from "./package.js";
 import { resolveProjects } from "./registry.js";
 import { setupReport } from "./scope.js";
+import { detectTestRunner, testResultsHint } from "./test-runner.js";
 import { savedTools } from "./tools.js";
 import { onPath, readJson, relativePath } from "./util.js";
+import { hasTestNames } from "./verify/test-results.js";
+/** How to get test results for a project without `testResults`: .NET writes TRX, JavaScript runners by detection. */
+function missingResultsFix(adapterId, ctx, root) {
+    const dir = path.join(root, ".flagrm", "test-results", ctx.name);
+    const fromProject = relativePath(ctx.root, dir) || ".";
+    const fromConfig = `./${relativePath(root, dir)}`;
+    if (adapterId === "dotnet") {
+        return `add \`--logger trx --results-directory "${fromProject}"\` to the test command and set testResults: ${fromConfig}/*.trx`;
+    }
+    return testResultsHint(detectTestRunner(ctx.root), fromProject, fromConfig, adapterId === "angular", root);
+}
 /** Check the setup in `cwd`: config and commands, git, .gitignore, skills, hook and abandoned baselines. */
 export async function runDoctor(cwd, options = {}) {
     const checks = [];
@@ -93,10 +105,13 @@ async function configChecks(cwd, configFile, options, add) {
     setupChecks(projects, root, options.probes ?? realProbes((exe) => onPath(exe, root)), add);
     for (const { adapter, ctx } of projects) {
         const commands = projectCommands(adapter, ctx);
-        for (const check of ["build", "test"]) {
+        for (const check of ["build", "test", "lint"]) {
             const command = commands[check];
             if (!command) {
-                add("warn", `${ctx.name}: no ${check} command — verify can't ${check === "build" ? "check the build" : "compare tests"}`);
+                // Lint is optional: verify skips it without a command, which is no problem.
+                if (check !== "lint") {
+                    add("warn", `${ctx.name}: no ${check} command — verify can't ${check === "build" ? "check the build" : "compare tests"}`);
+                }
                 continue;
             }
             const missing = simpleCommandProgram(command);
@@ -111,7 +126,7 @@ async function configChecks(cwd, configFile, options, add) {
                 }
             }
             if (check === "test" && !commands.testResults) {
-                add("warn", `${ctx.name}: test command has no testResults — verify can't compare tests by name, so a test that fails before the removal fails verify too`);
+                add("warn", `${ctx.name}: test command has no testResults — verify reads failing tests and counts from the log only and deleted tests from the diff, so it can't compare tests by name`, [`fix: ${missingResultsFix(adapter.id, ctx, root)}`]);
             }
             if (!options.run) {
                 const source = commands.defaults.includes(check) ? " (adapter default)" : "";
@@ -121,16 +136,21 @@ async function configChecks(cwd, configFile, options, add) {
             const log = path.join(root, ".flagrm", "doctor", `${ctx.name}.${check}.log`);
             const run = await runCheck(ctx, check, command, log, undefined, commands.testResults);
             // Proven here rather than halfway through a removal: without readable results, verify can't compare tests.
-            if (check === "test" && commands.testResults && !run.results) {
+            if (check === "test" && commands.testResults && !hasTestNames(run.results)) {
                 add("fail", `${ctx.name}: \`${command}\` wrote no test results matching ${relativePath(cwd, commands.testResults)}`, run.exitCode === 0 ? undefined : errorExcerpt(run.log, 3));
                 continue;
             }
             // A suite that is already red is no setup problem: the baseline records those tests as known failures.
-            if (run.exitCode !== 0 && run.results?.failed) {
+            if (run.exitCode !== 0 && run.results?.failed && run.results.failedNames.length >= run.results.failed) {
                 const failed = run.results.failed;
                 add("warn", `${ctx.name}: \`${command}\`: ${failed === 1 ? "1 test fails already — the baseline records it as a known failure" : `${failed} tests fail already — the baseline records them as known failures`}, which verify only warns about`);
                 continue;
             }
+            // Lint debt is no setup problem: verify only warns about a lint run that already failed at the baseline.
+            if (check === "lint" && run.exitCode !== 0 && !run.failure && !run.interrupted) {
+                add("warn", `${ctx.name}: \`${command}\` fails already (exit ${run.exitCode}) — verify only warns about lint errors the baseline had`, errorExcerpt(run.log, 3));
+                continue;
+            }
             if (run.exitCode === 0) {
                 add("ok", `${ctx.name}: \`${command}\` passed`);
                 continue;

package/dist/core/environment.js

@@ -1,8 +1,8 @@
 /**
  * Tell a machine setup problem apart from broken code in a failed build or
  * test log: a missing .NET SDK, a tool a build step calls that isn't
- * installed, Docker not running for Testcontainers. Each becomes one line
- * that says what to fix.
+ * installed, Docker not running for Testcontainers, a package script or
+ * ESLint config that doesn't exist. Each becomes one line that says what to fix.
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -12,7 +12,13 @@ import { relativePath } from "./util.js";
  * it shows none. `root` is the project root: paths are reported relative to it.
  */
 export function environmentProblem(log, root) {
-    const problems = [missingSdk(log, root), ...missingCommands(log, root), dockerUnavailable(log)].filter(Boolean);
+    const problems = [
+        missingSdk(log, root),
+        ...missingCommands(log, root),
+        dockerUnavailable(log),
+        missingScript(log),
+        eslintBroken(log),
+    ].filter(Boolean);
     return problems.length ? problems.join("; ") : undefined;
 }
 /**
@@ -77,3 +83,19 @@ function dockerUnavailable(log) {
         return undefined;
     return "Docker is not running (Testcontainers tests need it): start Docker or leave those tests out of `test`";
 }
+/** npm and pnpm print `Missing script: "lint"`, Yarn 1 `Command "lint" not found`, Yarn 2+ `Couldn't find a script named "lint"`. */
+function missingScript(log) {
+    const name = /\bMissing script: "?([^"\s]+)"?/.exec(log)?.[1] ??
+        /\berror Command "([^"]+)" not found/.exec(log)?.[1] ??
+        /Couldn't find a script named "([^"]+)"/.exec(log)?.[1];
+    if (!name)
+        return undefined;
+    return `package.json has no "${name}" script: add it or change the command in the config`;
+}
+/** ESLint that can't find its config or crashes exits 2 before it lints anything. */
+function eslintBroken(log) {
+    if (!/ESLint couldn't find (?:a configuration file|an eslint\.config)|Oops! Something went wrong! :\(/.test(log)) {
+        return undefined;
+    }
+    return "ESLint could not run (no config found, or it crashed): fix its setup or change the command in the config";
+}

package/dist/core/git.js

@@ -3,6 +3,7 @@
  * to the config root (`cwd`), and flagrm's own `.flagrm/` directory is ignored.
  */
 import { spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -26,6 +27,34 @@ export function gitState(cwd) {
     const dirtyFiles = changedFilesSince(cwd, "HEAD") ?? [];
     return { sha: head.stdout.trim(), dirty: dirtyFiles.length > 0, dirtyFiles };
 }
+function hashObjects(cwd, files) {
+    const result = spawnSync("git", ["hash-object", "--stdin-paths"], {
+        cwd,
+        encoding: "utf8",
+        input: `${files.join("\n")}\n`,
+    });
+    return result.status === 0 ? (result.stdout ?? "").split("\n") : undefined;
+}
+/**
+ * Each file's git blob id as it is in the working tree (null when it doesn't
+ * exist), so a later run can tell whether it changed since. A file git can't
+ * hash (a submodule directory) gets an id of its own each time, so it always
+ * counts as changed. Paths are relative to `cwd`.
+ */
+export function blobIds(cwd, files) {
+    const ids = {};
+    const existing = files.filter((rel) => fs.existsSync(path.join(cwd, rel)));
+    for (const rel of files)
+        ids[rel] = null;
+    if (existing.length === 0)
+        return ids;
+    // One git call for all files; when it fails, one per file, so a single unhashable path doesn't spoil the rest.
+    const out = hashObjects(cwd, existing);
+    existing.forEach((rel, i) => {
+        ids[rel] = (out ? out[i] : hashObjects(cwd, [rel])?.[0]) || `unhashable:${randomUUID()}`;
+    });
+    return ids;
+}
 /**
  * Files added, modified or deleted in the working tree since `sha` (tracked
  * diff plus untracked files), without the ones `ignore` names.
@@ -108,13 +137,21 @@ export function treeFingerprint(cwd, ignore) {
  * doesn't have it), so the fingerprint doesn't see changes to it.
  */
 function dropIgnored(cwd, index, ignore) {
-    const listed = paths(gitWithIndex(cwd, index, ["ls-files", "-z"]).stdout).filter(ignore);
+    const head = headSha(cwd);
+    // The paths that differ from HEAD, deleted ones included: `ls-files` no longer lists a deleted file.
+    // Before the first commit there is no HEAD to compare with, so every path in the index.
+    const listing = head
+        ? gitWithIndex(cwd, index, ["diff-index", "--cached", "--name-only", "--no-renames", "--relative", "-z", "HEAD"])
+        : gitWithIndex(cwd, index, ["ls-files", "-z"]);
+    if (!listing.ok)
+        return false;
+    const listed = paths(listing.stdout).filter(ignore);
     if (listed.length === 0)
         return true;
     const input = `${listed.join("\0")}\0`;
     const fromFile = ["--pathspec-from-file=-", "--pathspec-file-nul"];
     // `reset` also drops a path HEAD doesn't have; before the first commit there is no HEAD to reset to.
-    const args = headSha(cwd) ? ["reset", "-q", "HEAD", ...fromFile] : ["rm", "-q", "--cached", ...fromFile];
+    const args = head ? ["reset", "-q", "HEAD", ...fromFile] : ["rm", "-q", "--cached", ...fromFile];
     return gitWithIndex(cwd, index, args, input).ok;
 }
 /** The tree id of `cwd` at commit `sha`. */

package/dist/core/install.js

@@ -11,6 +11,7 @@ import path from "node:path";
 import { DEFAULT_BACKEND_ATTRIBUTES, DEFAULT_BACKEND_METHODS, DEFAULT_FRONTEND_METHODS, findConfigRoot, findDefaultConfigFile, repositoryRoot, TOOL_IDS, } from "./config.js";
 import { detectProjects } from "./detect.js";
 import { packageRoot, packageVersion } from "./package.js";
+import { runnerTestCommands, testResultsHint } from "./test-runner.js";
 import { saveTools } from "./tools.js";
 import { relativePath } from "./util.js";
 export const SKILLS = ["flagrm-remove", "flagrm-verify"];
@@ -27,11 +28,11 @@ export const PROMPT_FILES = {
     "flagrm-remove": [
         "---",
         "description: Remove a feature flag with flagrm's guardrails (keep the ON path, verify until it passes)",
-        "argument-hint: <flag>",
+        "argument-hint: <flag> [flag...]",
         "agent: agent",
         "---",
         "",
-        "Follow `.github/skills/flagrm-remove/SKILL.md` to remove the feature flag named after this command.",
+        "Follow `.github/skills/flagrm-remove/SKILL.md` to remove the feature flags named after this command.",
         "",
     ].join("\n"),
     "flagrm-verify": [
@@ -61,8 +62,8 @@ export const AGENTS_BLOCK = [
     AGENTS_START,
     "## Feature flag removal (flagrm)",
     "",
-    "To remove a feature flag, follow `.agents/skills/flagrm-remove/SKILL.md`. To check a removal and get its",
-    "commit message, follow `.agents/skills/flagrm-verify/SKILL.md`.",
+    "To remove one or more feature flags, follow `.agents/skills/flagrm-remove/SKILL.md`. To check a removal",
+    "later, follow `.agents/skills/flagrm-verify/SKILL.md`.",
     AGENTS_END,
 ].join("\n");
 const CONFIG_HEADER = [
@@ -89,14 +90,21 @@ const EXAMPLE_PROJECTS = [
     { name: "backend", adapter: "dotnet", path: "backend", marker: "backend/Backend.sln" },
 ];
 /** The config lines for one project, with commented-out commands that fit it. */
-function projectLines(p) {
+function projectLines(p, cwd) {
     const dir = p.path === "." ? "." : `./${p.path}`;
     const inDir = (rel) => (p.path === "." ? `./${rel}` : `${dir}/${rel}`);
     const lines = [`  - name: ${p.name}`, `    adapter: ${p.adapter}`, `    path: ${dir}`];
     if (p.adapter === "angular") {
-        lines.push("    # build: npx ng build", p.jest
-            ? "    # test: JEST_JUNIT_OUTPUT_DIR=test-results npx jest --ci --reporters=default --reporters=jest-junit"
-            : "    # test: npx ng test --watch=false", `    # testResults: ${inDir("test-results/junit.xml")}   # JUnit XML, so verify can count tests`, `    # methods: [${DEFAULT_FRONTEND_METHODS.join(", ")}]   # flag evaluation methods (defaults shown)`);
+        const results = path.join(cwd, ".flagrm", "test-results", p.name);
+        const runner = p.testRunner ?? { kind: "unknown" };
+        const tests = runnerTestCommands(runner, path.join(cwd, p.path), results);
+        lines.push("    # build: npx ng build", `    # test: ${tests?.test ?? "npx ng test --watch=false"}`, tests
+            ? `    # testResults: ./${relativePath(cwd, tests.testResults)}   # the default test command writes these`
+            : `    # testResults: ${inDir("test-results/junit.xml")}   # JUnit XML, TRX or Jest JSON, so verify can compare tests`, ...(tests
+            ? []
+            : [
+                `    # to get test results: ${testResultsHint(runner, relativePath(path.join(cwd, p.path), results) || ".", `./${relativePath(cwd, results)}`, true, cwd)}`,
+            ]), `    # methods: [${DEFAULT_FRONTEND_METHODS.join(", ")}]   # flag evaluation methods (defaults shown)`);
     }
     else {
         const solution = /\.slnx?$/.test(p.marker) ? ` ${path.posix.basename(p.marker)}` : "";
@@ -104,13 +112,20 @@ function projectLines(p) {
     }
     return lines;
 }
-export function configTemplate(projects, tools) {
+export function configTemplate(projects, tools, cwd = process.cwd()) {
     const listed = projects.length ? projects : EXAMPLE_PROJECTS;
     const [comment1, comment2, projectsKey] = CONFIG_HEADER;
     const toolLines = tools
         ? ["# The AI coding tools `flagrm init` and `flagrm update` set up.", `tools: [${tools.join(", ")}]`]
         : [];
-    return [comment1, comment2, ...toolLines, projectsKey, ...listed.flatMap(projectLines), ...CONFIG_FOOTER].join("\n");
+    return [
+        comment1,
+        comment2,
+        ...toolLines,
+        projectsKey,
+        ...listed.flatMap((p) => projectLines(p, cwd)),
+        ...CONFIG_FOOTER,
+    ].join("\n");
 }
 /** Write `flagrm.config.yaml` for the projects found in `cwd` (an example when none are) unless a config file exists. */
 export function writeConfigTemplate(cwd, tools) {
@@ -119,7 +134,7 @@ export function writeConfigTemplate(cwd, tools) {
         return { path: relativePath(cwd, existing), status: "skipped" };
     const file = path.join(cwd, "flagrm.config.yaml");
     const projects = detectProjects(cwd);
-    fs.writeFileSync(file, configTemplate(projects, tools), "utf8");
+    fs.writeFileSync(file, configTemplate(projects, tools, cwd), "utf8");
     const note = projects.length
         ? `detected ${projects.map((p) => `${p.adapter} (${p.marker})`).join(", ")}`
         : "no Angular or .NET project found: edit the example projects";

package/dist/core/inventory.js

@@ -138,7 +138,9 @@ function followFlow(projects, entries) {
                 continue;
             const words = flagWords([{ name: entry.flag }, ...entry.definitions]);
             const flagNames = [entry.flag, ...entry.definitions.map((d) => d.name.split(".").pop() ?? d.name)];
-            entry.flow.push({ ...name, record: !name.ambiguous && recordable(name, flagNames, words) });
+            // A renamed import of one of the flag's definitions is as specific as the definition.
+            const record = name.kind === "alias" || (!name.ambiguous && recordable(name, flagNames, words));
+            entry.flow.push({ ...name, record });
         }
         for (const test of tests)
             byFlag.get(test.flag)?.parameterizedTests.push(test);

package/dist/core/markdown.js

@@ -3,6 +3,7 @@
  * for the user or a PR. Every fact comes from the report; the agent adds
  * notes and the commit message around it.
  */
+import { reusedNote } from "./run-cache.js";
 import { relativePath } from "./util.js";
 import { shortTestName, shortTestNames } from "./verify/test-results.js";
 const ICON = { pass: "✅", fail: "❌", warn: "⚠️", skipped: "➖" };
@@ -30,6 +31,9 @@ export function verifyMarkdown(report, root) {
         "|---|---|---|",
         ...report.checks.map((c) => `| ${c.id} | ${ICON[c.status]} ${c.status} | ${c.summary.replace(/\|/g, "\\|")} |`),
     ];
+    const note = reusedNote(report.runs, report.createdAt);
+    if (note)
+        out.push("", `_${note}_`);
     const changed = report.changedFiles ?? [];
     if (changed.length)
         out.push("", `**Files changed since baseline (${changed.length}):** ${codeList(changed)}`);

package/dist/core/name-owner.js

@@ -0,0 +1,179 @@
+/**
+ * Which flags a name's code reads: where the name is declared or assigned
+ * (`name =`, `name:`, `name(...) {`, `Name =>`, `Name {`), and the flag
+ * literals and qualified names in what follows, up to the end of that
+ * statement or body. Lexical like the rest of discovery (comments and strings
+ * masked), so it works for TypeScript and C# alike and misses unusual shapes.
+ *
+ * `baseline --name` refuses a name that reads only other flags: once
+ * recorded, `leftovers` would make the agent delete another flag's code, and
+ * a recorded name can't be removed again.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { UsageError } from "./baseline.js";
+import { buildInventory } from "./inventory.js";
+import { commentSyntax, computeLexicalMask, escapeRegExp, LEX_CODE, LEX_STRING } from "./scan.js";
+import { SourceText } from "./source-text.js";
+import { toLf } from "./text-utils.js";
+import { relativePath } from "./util.js";
+const MAX_LINES = 20;
+const OPEN = "([{";
+const CLOSE = ")]}";
+/** Every declaration or assignment of `name` in `files` (absolute; every project file when undefined). */
+export function nameReads(projects, name, files, flags) {
+    const only = files && new Set(files);
+    const word = new RegExp(`(?<![\\w$])${escapeRegExp(name)}(?![\\w$])`, "g");
+    const out = [];
+    const seen = new Set();
+    for (const { ctx } of projects) {
+        for (const file of ctx.files) {
+            if (seen.has(file) || (only && !only.has(file)) || commentSyntax(file) !== "slash")
+                continue;
+            seen.add(file);
+            let text;
+            try {
+                text = toLf(fs.readFileSync(file, "utf8"));
+            }
+            catch {
+                continue;
+            }
+            if (!text.includes(name))
+                continue;
+            const mask = computeLexicalMask(text, "slash");
+            const source = new SourceText(file, text);
+            for (const m of text.matchAll(word)) {
+                if (mask[m.index] !== LEX_CODE)
+                    continue;
+                const after = m.index + name.length;
+                if (!isSite(text, mask, m.index, after))
+                    continue;
+                const body = text.slice(after, statementEnd(text, mask, after));
+                out.push({ file, line: source.position(m.index).line, flags: flagsIn(body, flags) });
+            }
+        }
+    }
+    return out;
+}
+/** A declaration or assignment of the name at `start..after`, not a read, a call, a ternary branch or a case label. */
+function isSite(text, mask, start, after) {
+    const before = text.slice(Math.max(0, start - 40), start);
+    if (/\?\s*$/.test(before) || /\bcase\s+$/.test(before))
+        return false;
+    let i = after;
+    while (i < text.length && /[ \t]/.test(text[i]))
+        i++;
+    // `x?:` / `x!:` (optional, definite) and `x ??= y` declare or assign; `x != y`, `x ? a : b` and `x!.y` don't.
+    if (text[i] === "?" || text[i] === "!") {
+        const op = text.slice(i, i + 3);
+        return op[1] === ":" || op === "??=";
+    }
+    const rest = text.slice(i, i + 3);
+    if (rest.startsWith("=>"))
+        return true;
+    if (rest.startsWith("="))
+        return !rest.startsWith("==");
+    if (rest.startsWith(":"))
+        return true;
+    if (rest.startsWith("{"))
+        return true;
+    if (!rest.startsWith("("))
+        return false;
+    // A parameter list, then (after an optional return type, which may hold `|`, `.` or `<>`) a body or
+    // `=>`: a method. Anything else is a call: `;`/`,`/`}` or a line break first, or a `)` closing an
+    // enclosing bracket (`if (isX()) {`). Arrows and braces inside the call's own brackets don't count.
+    let depth = 0;
+    for (let j = i; j < Math.min(text.length, i + 400); j++) {
+        if (mask[j] !== LEX_CODE)
+            continue;
+        const c = text[j];
+        if (c === "(")
+            depth++;
+        else if (c === ")") {
+            if (--depth < 0)
+                return false;
+        }
+        else if (depth > 0)
+            continue;
+        else if (c === "{")
+            return true;
+        else if (c === "=" && text[j + 1] === ">")
+            return true;
+        else if (c === ";" || c === "," || c === "}")
+            return false;
+        else if (c === "\n") {
+            const head = text.slice(j + 1).trimStart();
+            return head.startsWith("{") || head.startsWith("=>");
+        }
+    }
+    return false;
+}
+/** Where the statement or body starting at `from` ends: `;` or `,` at depth 0, a closing bracket below it, or a `{` body's `}`. */
+function statementEnd(text, mask, from) {
+    let depth = 0;
+    let lines = 0;
+    for (let i = from; i < text.length; i++) {
+        if (text[i] === "\n" && ++lines >= MAX_LINES)
+            return i;
+        if (mask[i] !== LEX_CODE)
+            continue;
+        const c = text[i];
+        if (OPEN.includes(c))
+            depth++;
+        else if (CLOSE.includes(c)) {
+            depth--;
+            if (depth < 0)
+                return i;
+            if (depth === 0 && c === "}")
+                return i + 1;
+        }
+        else if (depth === 0 && (c === ";" || c === ","))
+            return i;
+    }
+    return text.length;
+}
+/** The flags whose literal (quoted) or qualified name (in code) occurs in `body`. */
+function flagsIn(body, flags) {
+    const mask = computeLexicalMask(body, "slash");
+    return flags
+        .filter(({ flag, aliases }) => {
+        for (const m of body.matchAll(new RegExp(`(['"\`])${escapeRegExp(flag)}\\1`, "g"))) {
+            if (mask[m.index] === LEX_STRING)
+                return true;
+        }
+        return aliases.some((alias) => {
+            const pattern = alias.split(".").map(escapeRegExp).join("\\s*\\.\\s*");
+            for (const m of body.matchAll(new RegExp(`(?<![\\w$])${pattern}(?![\\w$])`, "g"))) {
+                if (mask[m.index] === LEX_CODE)
+                    return true;
+            }
+            return false;
+        });
+    })
+        .map((f) => f.flag);
+}
+/** Throw a {@link UsageError} for the first agent name whose code reads only flags other than `flag`. */
+export async function assertOwnNames(root, projects, flag, names) {
+    if (names.length === 0)
+        return;
+    const inventory = (await buildInventory(projects)).flags;
+    // A renamed import of the flag's registry (`AppFeatureFlags.X`) reads it as much as the definition does.
+    const refs = inventory.map((e) => ({
+        flag: e.flag,
+        aliases: [...e.definitions.map((d) => d.name), ...e.flow.filter((n) => n.kind === "alias").map((n) => n.name)],
+    }));
+    if (!refs.some((r) => r.flag === flag))
+        refs.push({ flag, aliases: [] });
+    for (const name of [...new Set(names.map((n) => n.name))]) {
+        const entries = names.filter((n) => n.name === name);
+        const files = entries.every((n) => n.file) ? entries.map((n) => path.resolve(root, n.file)) : undefined;
+        const sites = nameReads(projects, name, files, refs);
+        if (sites.some((s) => s.flags.includes(flag)))
+            continue;
+        const foreign = sites.find((s) => s.flags.length > 0);
+        if (!foreign)
+            continue;
+        throw new UsageError(`"${name}" reads ${foreign.flags.join(", ")}, not ${flag} (${relativePath(root, foreign.file)}:${foreign.line}); ` +
+            "not recorded. Record only names this flag's value goes through.");
+    }
+}

package/dist/core/report.js

@@ -1,4 +1,5 @@
 import pc from "picocolors";
+import { reusedNote } from "./run-cache.js";
 import { plural, relativePath } from "./util.js";
 /** A path relative to the working directory, with `/` separators on every platform. */
 function rel(file) {
@@ -70,6 +71,9 @@ export function printBaseline(baseline, file) {
         if (c.failure)
             console.log(`    ${pc.yellow("setup problem:")} ${c.failure.message}`);
     }
+    const note = reusedNote(checks ?? [], baseline.createdAt);
+    if (note)
+        console.log(`  ${pc.dim(note)}`);
     if (baseline.names.length) {
         const names = baseline.names.map((n) => n.kind === "literal" ? n.name : `${n.name} (${n.kind}${n.file ? ` in ${n.file}` : ""})`);
         console.log(`  names: ${pc.dim(names.join(", "))}`);
@@ -122,6 +126,9 @@ export function printVerifyReport(report, file) {
     }
     if (report.strict && warned)
         console.log(pc.dim("\n  --strict: warnings count as failures."));
+    const note = reusedNote(report.runs, report.createdAt);
+    if (note)
+        console.log(pc.dim(`\n  ${note}`));
     console.log(pc.dim(`\nResult written to ${rel(file)}.`));
 }
 const STEP_STYLE = {

package/dist/core/run-cache.js

@@ -0,0 +1,137 @@
+/**
+ * Build and test runs a passing full verify saves, so the next baseline or
+ * verify on the same tree with the same commands reuses them instead of
+ * running them again: in a sequential removal, the next flag's baseline
+ * starts on the commit the previous flag's verify passed on.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import fg from "fast-glob";
+import { flagDir, matchingFiles, runChecks } from "./baseline.js";
+import { changeFilter } from "./change-filter.js";
+import { configSnapshot, projectCommands } from "./config-snapshot.js";
+import { treeFingerprint } from "./git.js";
+import { packageVersion } from "./package.js";
+import { JSON_SCHEMA_VERSION, RUN_CHECK_ID } from "./types.js";
+import { readJson } from "./util.js";
+/** `.flagrm/<flag>/verify/runs.json`. */
+export function runsPath(root, flag) {
+    return path.join(flagDir(root, flag), "verify", "runs.json");
+}
+/**
+ * The tree the commands will run on: its fingerprint before they run, without
+ * flagrm's setup files and the test result files the runs themselves rewrite.
+ * Commands are compared on their own, so leaving out the config file is safe.
+ * Unlike the Stop hook's fingerprint, `exclude`d paths count: a build or test
+ * may read them (a lockfile, generated sources), so a change there must rerun.
+ */
+export function runsKey(root, projects) {
+    const ignore = changeFilter();
+    const patterns = projects.flatMap(({ adapter, ctx }) => projectCommands(adapter, ctx).testResults ?? []);
+    const results = matchingFiles(root, patterns);
+    return treeFingerprint(root, (rel) => ignore(rel) || results.has(rel));
+}
+/** The (project, check) pairs a run of `only` would run: those with a command. */
+export function plannedRuns(projects, only) {
+    return projects.flatMap(({ adapter, ctx }) => {
+        const commands = projectCommands(adapter, ctx);
+        return only.filter((check) => commands[check]).map((check) => ({ project: ctx.name, check }));
+    });
+}
+/**
+ * Save a passing full verify's runs; never a set with a setup problem, which would come back on every rerun,
+ * nor runs that were themselves reused: the set they came from keeps its own flag and time.
+ * The logs are copied next to `runs.json`, so a later verify overwriting its own logs leaves the saved set whole.
+ */
+export function saveRuns(root, flag, projects, key, runs, createdAt = new Date().toISOString()) {
+    if (runs.some((r) => r.failure || r.reused))
+        return;
+    const file = runsPath(root, flag);
+    const logDir = path.join(path.dirname(file), "saved");
+    fs.mkdirSync(logDir, { recursive: true });
+    const kept = runs.map(({ reused: _reused, ...run }) => {
+        if (!run.log)
+            return run;
+        const log = path.join(logDir, `${run.project}.${run.check}.log`);
+        fs.copyFileSync(run.log, log);
+        return { ...run, log };
+    });
+    const saved = {
+        schemaVersion: JSON_SCHEMA_VERSION,
+        flagrmVersion: packageVersion(),
+        flag,
+        createdAt,
+        key,
+        commands: configSnapshot(projects).projects,
+        runs: kept,
+    };
+    fs.writeFileSync(file, `${JSON.stringify(saved, null, 2)}\n`, "utf8");
+}
+/** Forget every saved set, of any flag, for this tree: a fresh run on it failed, so they may hide a flaky test or a changed machine. */
+export function dropRuns(root, key) {
+    for (const file of fg.sync(".flagrm/*/verify/runs.json", { cwd: root, absolute: true, dot: true })) {
+        if (readJson(file)?.key === key)
+            fs.rmSync(file, { force: true });
+    }
+}
+/** The newest saved set, of any flag, for this tree and these commands that has every `needed` run and its log. */
+export function findRuns(root, projects, key, needed) {
+    if (needed.length === 0)
+        return undefined;
+    const commands = JSON.stringify(configSnapshot(projects).projects);
+    const version = packageVersion();
+    let best;
+    for (const file of fg.sync(".flagrm/*/verify/runs.json", { cwd: root, absolute: true, dot: true })) {
+        const saved = readJson(file);
+        if (!saved || !Array.isArray(saved.runs) || typeof saved.createdAt !== "string")
+            continue;
+        if (saved.key !== key || saved.schemaVersion !== JSON_SCHEMA_VERSION)
+            continue;
+        if (saved.flagrmVersion !== version || JSON.stringify(saved.commands) !== commands)
+            continue;
+        const runs = needed.map((n) => saved.runs.find((r) => r.project === n.project && r.check === n.check));
+        if (runs.some((r) => !r || (r.log !== undefined && !fs.existsSync(r.log))))
+            continue;
+        if (!best || saved.createdAt > best.saved.createdAt)
+            best = { saved, runs: runs };
+    }
+    return best;
+}
+/** The found runs as this flag's own: logs copied into `logDir` under their usual names, marked `reused`. */
+export function reuseRuns(found, logDir) {
+    fs.mkdirSync(logDir, { recursive: true });
+    const reused = { flag: found.saved.flag, createdAt: found.saved.createdAt };
+    return found.runs.map((run) => {
+        if (!run.log)
+            return { ...run, reused };
+        const log = path.join(logDir, `${run.project}.${run.check}.log`);
+        if (path.resolve(run.log) !== path.resolve(log))
+            fs.copyFileSync(run.log, log);
+        return { ...run, log, reused };
+    });
+}
+/** A baseline's build, test and lint runs: reused from a passing verify on the same tree and commands, else run. */
+export async function baselineRuns(root, flag, projects, reuse = true) {
+    const logDir = flagDir(root, flag);
+    const key = reuse ? runsKey(root, projects) : undefined;
+    const found = key ? findRuns(root, projects, key, plannedRuns(projects, ["build", "test", "lint"])) : undefined;
+    return found ? reuseRuns(found, logDir) : runChecks(projects, logDir);
+}
+/** One line saying which runs were reused and from where, or undefined when none were. `at`: when they were reused. */
+export function reusedNote(runs, at) {
+    const reused = runs.find((r) => r.reused)?.reused;
+    if (!reused)
+        return undefined;
+    const checks = [...new Set(runs.filter((r) => r.reused).map((r) => RUN_CHECK_ID[r.check]))];
+    const what = checks.length > 1 ? `${checks.slice(0, -1).join(", ")} and ${checks.at(-1)}` : checks[0];
+    return `${what} reused from ${reused.flag}'s verify (same tree and commands, ${age(Date.parse(at) - Date.parse(reused.createdAt))} ago; --no-reuse to run them)`;
+}
+function age(ms) {
+    const min = Math.round(ms / 60_000);
+    if (min < 1)
+        return "under a minute";
+    if (min < 60)
+        return `${min} min`;
+    const hours = Math.round(min / 60);
+    return hours < 48 ? `${hours} h` : `${Math.round(hours / 24)} days`;
+}