flagrm 0.4.0 → 0.5.0

package/dist/cli.js

@@ -13,14 +13,17 @@ import { blobIds, gitState } from "./core/git.js";
 import { hookRoot, parseHookInput, stopDecision } from "./core/hook.js";
 import { initProject, installRoot, updateProject } from "./core/install.js";
 import { buildInventory } from "./core/inventory.js";
-import { verifyMarkdown } from "./core/markdown.js";
+import { staleMarkdown, verifyMarkdown } from "./core/markdown.js";
 import { assertOwnNames } from "./core/name-owner.js";
 import { packageVersion } from "./core/package.js";
 import { resolveProjects } from "./core/registry.js";
-import { printBaseline, printDoctor, printInventory, printScope, printSteps, printVerifyReport, } from "./core/report.js";
+import { printBaseline, printDoctor, printInventory, printScope, printStale, printSteps, printVerifyReport, } from "./core/report.js";
 import { baselineRuns } from "./core/run-cache.js";
 import { setupReport, writeScope } from "./core/scope.js";
 import { withScopeFiles } from "./core/scope-files.js";
+import { LaunchDarklySource } from "./core/sources/launchdarkly.js";
+import { SourceError } from "./core/sources/types.js";
+import { evaluateStale, needsHistory } from "./core/stale.js";
 import { askTools, detectTools, savedTools, TOOL_LABELS } from "./core/tools.js";
 import { CHECK_IDS } from "./core/types.js";
 import { onPath, relativePath } from "./core/util.js";
@@ -29,7 +32,8 @@ const program = new Command();
 program
     .name("flagrm")
     .description("Guardrails for removing feature flags with an AI coding agent: set up the skills and hook (init, update, " +
-    "doctor), find flags (list), record the state before a removal (baseline) and gate the result (verify).")
+    "doctor), find flags (list) and those LaunchDarkly says are ready to remove (stale), record the state before a " +
+    "removal (baseline) and gate the result (verify).")
     .version(packageVersion());
 /** Accumulate repeatable options (`--exclude a --exclude b`) into an array. */
 function collect(value, previous) {
@@ -206,6 +210,57 @@ addCommonOptions(program
         printInventory(report);
     }
 });
+// --- stale -------------------------------------------------------------------
+addCommonOptions(program
+    .command("stale [flags...]")
+    .description("ask LaunchDarkly (the config's launchdarkly: section, read-only) which flags are ready to remove from code: " +
+    "remove (meets the conditions, in this repository's code), unreferenced (not in this repository) or keep " +
+    "(with reasons); flags are LaunchDarkly keys or code names, default all; " +
+    "exit 0 evaluated, 2 usage error, 3 LaunchDarkly unreachable or refused the request (token, access, project key)"))
+    .option("--md", "print a markdown summary (for a pull request or pipeline summary) instead of text")
+    .action(async (flags, opts) => {
+    if (opts.md && opts.json)
+        fail(new Error("--md and --json can't be combined."));
+    let config;
+    let projects;
+    try {
+        config = loadConfig(opts);
+        projects = resolveProjects(config);
+    }
+    catch (err) {
+        fail(err);
+    }
+    const ld = config.launchdarkly;
+    if (!ld) {
+        fail(new Error(`No launchdarkly: section in ${config.file ?? "the config"}. Add one with your LaunchDarkly project key:\n` +
+            "  launchdarkly:\n    project: <project key>\n" +
+            "and set LD_API_TOKEN to an API token (reader role is enough). See the README's LaunchDarkly section."));
+    }
+    // Checked before any request: nothing goes out without a token.
+    const token = process.env[ld.tokenEnv]?.trim();
+    if (!token)
+        fail(new Error(`${ld.tokenEnv} is not set: set it to a LaunchDarkly API token (reader role is enough).`));
+    const codeNames = (await buildInventory(projects)).flags.map((f) => f.flag);
+    let report;
+    try {
+        const read = await new LaunchDarklySource(ld, { token }).read((f) => needsHistory(f, ld, codeNames));
+        report = evaluateStale({ project: ld.project, read, codeNames, config: ld, now: new Date(), only: flags });
+    }
+    catch (err) {
+        if (!(err instanceof SourceError))
+            fail(err);
+        console.error(pc.red(err.message));
+        process.exitCode = 3;
+        return;
+    }
+    if (opts.json)
+        console.log(JSON.stringify(report, null, 2));
+    else if (opts.md)
+        process.stdout.write(`${staleMarkdown(report)}\n`);
+    else
+        printStale(report);
+    process.exitCode = 0;
+});
 // --- hook --------------------------------------------------------------------
 const hook = program.command("hook").description("entry points for agent hooks (installed by flagrm init)");
 hook

package/dist/core/baseline.js

@@ -2,12 +2,12 @@ import { spawn, spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import fg from "fast-glob";
 import { changeFilter } from "./change-filter.js";
 import { configSnapshot, projectCommands } from "./config-snapshot.js";
 import { environmentProblem } from "./environment.js";
 import { changedFilesSince } from "./git.js";
 import { buildInventory } from "./inventory.js";
+import { globAbsolute } from "./scan.js";
 import { withScopeFiles } from "./scope-files.js";
 import { JSON_SCHEMA_VERSION, READABLE_BASELINE_VERSIONS, } from "./types.js";
 import { readJson, relativePath } from "./util.js";
@@ -80,8 +80,15 @@ export function readBaseline(root, flag) {
         throw new UsageError(`${file} was written by schema version ${baseline.schemaVersion}; this flagrm expects ${JSON_SCHEMA_VERSION}. ` +
             `Re-run \`flagrm baseline ${flag} --force\` on the code as it was before the removal.`);
     }
+    const sha = baseline.git?.sha;
+    if (sha != null && !COMMIT_ID.test(sha)) {
+        throw new UsageError(`${file} has git.sha "${sha}", which is not a git commit id. ` +
+            `Re-run \`flagrm baseline ${flag} --force\` on the code as it was before the removal.`);
+    }
     return { baseline, file };
 }
+/** A full SHA-1 or SHA-256 commit id, as `git rev-parse HEAD` prints it. */
+const COMMIT_ID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
 /**
  * Run one shell command inside a project, streaming its output to `logFile`
  * (no buffer limit, stdout and stderr interleaved as printed). A command that
@@ -312,9 +319,7 @@ export function editsSince(root, sha, testResults = [], ignore = changeFilter())
 }
 /** The files (relative to `root`) matching absolute paths or globs, such as `testResults` patterns. */
 export function matchingFiles(root, patterns) {
-    return new Set(patterns.flatMap((pattern) => fg
-        .sync(path.sep === "\\" ? pattern.replace(/\\/g, "/") : pattern, { absolute: true, dot: true })
-        .map((file) => relativePath(root, file))));
+    return new Set(patterns.flatMap((pattern) => globAbsolute(pattern).map((file) => relativePath(root, file))));
 }
 /**
  * `baseline --force` starts over only before the removal began: the working

package/dist/core/change-filter.js

@@ -7,14 +7,17 @@
  */
 import picomatch from "picomatch";
 import { CONFIG_FILENAMES, loadConfig } from "./config.js";
-import { AGENT_SKILL_DIRS, SKILLS } from "./install.js";
+import { AGENT_SKILL_DIRS, LEGACY_SKILLS, SKILLS } from "./install.js";
 import { relativePath } from "./util.js";
-/** The files `flagrm init`, `update` and `scope --write` write, relative to the config root. */
+/**
+ * The files `flagrm init`, `update` and `scope --write` write, relative to the
+ * config root. Renamed skills count too: `update` deletes them, possibly mid-removal.
+ */
 export const SETUP_PATTERNS = [
     ...CONFIG_FILENAMES,
     ".gitignore",
     ".claude/settings.json",
-    ...AGENT_SKILL_DIRS.flatMap((dir) => SKILLS.map((skill) => `${dir}/${skill}/**`)),
+    ...AGENT_SKILL_DIRS.flatMap((dir) => [...SKILLS, ...Object.keys(LEGACY_SKILLS)].map((skill) => `${dir}/${skill}/**`)),
     ".github/prompts/flagrm-*.prompt.md",
     "AGENTS.md",
     "**/flagrm.slnf",
@@ -42,7 +45,7 @@ export function changeFilter(config) {
     };
 }
 /**
- * Matches `exclude` the way scanning's fast-glob `ignore` does: a pattern
+ * Matches `exclude` the way scanning's tinyglobby `ignore` does: a pattern
  * that matches a directory (`graphify-out`, `graphify-out/`) excludes
  * everything under it, so test the path and each of its parent directories.
  * `covers` reads the same way.

package/dist/core/config-snapshot.js

@@ -142,6 +142,23 @@ export function configChanges(before, now) {
     }
     return changes;
 }
+/**
+ * Whether the config file under `root` changed since `before` in what is
+ * scanned or ignored (`exclude`, globs, paths), not just in its commands.
+ * False when `before` recorded no config file.
+ */
+export function scanConfigChanged(before, root) {
+    if (!before?.file)
+        return false;
+    let text;
+    try {
+        text = fs.readFileSync(path.join(root, before.file.path), "utf8");
+    }
+    catch {
+        return true;
+    }
+    return withoutCommands(before.file.text) !== withoutCommands(text);
+}
 const quote = (text) => (text === undefined ? "(none)" : `\`${text}\``);
 function changedFiles(a, b) {
     const hashes = new Map(a.map((f) => [f.path, f.sha256]));

package/dist/core/config.js

@@ -19,6 +19,8 @@ export function parseTools(value, where = "tools") {
     }
     return TOOL_IDS.filter((t) => tools.includes(t));
 }
+export const DEFAULT_LAUNCHDARKLY_BASE_URL = "https://app.launchdarkly.com";
+export const DEFAULT_LAUNCHDARKLY_TOKEN_ENV = "LD_API_TOKEN";
 export const DEFAULT_FRONTEND_METHODS = ["isEnabled", "isFeatureEnabled", "hasFeature", "getFlag", "isOn"];
 export const DEFAULT_BACKEND_METHODS = [
     "IsEnabledAsync",
@@ -41,6 +43,17 @@ const KNOWN_CONFIG_KEYS = [
     "backendAttributes",
     "exclude",
     "include",
+    "launchdarkly",
+];
+const KNOWN_LAUNCHDARKLY_KEYS = [
+    "project",
+    "baseUrl",
+    "tokenEnv",
+    "environments",
+    "minDaysOn",
+    "temporaryOnly",
+    "tags",
+    "map",
 ];
 const KNOWN_PROJECT_KEYS = [
     "name",
@@ -155,6 +168,32 @@ function optionalPositiveNumber(value, where) {
     }
     return value;
 }
+function optionalBoolean(value, where) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "boolean")
+        throw new Error(`${where} must be true or false.`);
+    return value;
+}
+function optionalPositiveDays(value, where) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+        throw new Error(`${where} must be a positive whole number of days.`);
+    }
+    return value;
+}
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function optionalStringMap(value, where) {
+    if (value === undefined)
+        return undefined;
+    if (!isObject(value) || !Object.values(value).every((v) => typeof v === "string" && v.trim())) {
+        throw new Error(`${where} must map LaunchDarkly keys to code names (strings).`);
+    }
+    return value;
+}
 function optionalStringList(value, where) {
     if (value === undefined)
         return undefined;
@@ -163,6 +202,59 @@ function optionalStringList(value, where) {
     }
     return value;
 }
+const LOOPBACK_HOSTS = ["localhost", "127.0.0.1", "[::1]"];
+/** The `launchdarkly:` section with defaults applied; undefined when absent. */
+function parseLaunchDarkly(raw, quiet = false) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    const where = "launchdarkly";
+    if (!isObject(raw))
+        throw new Error(`${where} must be an object with at least a "project".`);
+    for (const key of ["token", "apiKey"]) {
+        if (key in raw) {
+            throw new Error(`${where}.${key}: never put the API token in the config file. Remove it and set the environment ` +
+                `variable named by ${where}.tokenEnv (default ${DEFAULT_LAUNCHDARKLY_TOKEN_ENV}) instead.`);
+        }
+    }
+    if (!quiet)
+        warnOnUnknownKeys(raw, KNOWN_LAUNCHDARKLY_KEYS, `"${where}"`);
+    const project = optionalString(raw.project, `${where}.project`);
+    if (!project)
+        throw new Error(`${where}.project is required: the LaunchDarkly project key.`);
+    const baseUrl = (optionalString(raw.baseUrl, `${where}.baseUrl`) ?? DEFAULT_LAUNCHDARKLY_BASE_URL).replace(/\/+$/, "");
+    let url;
+    try {
+        url = new URL(baseUrl);
+    }
+    catch {
+        throw new Error(`${where}.baseUrl is not a URL: ${baseUrl}`);
+    }
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && LOOPBACK_HOSTS.includes(url.hostname))) {
+        throw new Error(`${where}.baseUrl must use https: the API token is sent to it.`);
+    }
+    if (raw.tags !== undefined && !isObject(raw.tags)) {
+        throw new Error(`${where}.tags must be an object with "include" and/or "exclude" lists.`);
+    }
+    const tags = (raw.tags ?? {});
+    if (!quiet)
+        warnOnUnknownKeys(tags, ["include", "exclude"], `"${where}.tags"`);
+    const environments = optionalStringList(raw.environments, `${where}.environments`);
+    if (environments?.length === 0)
+        throw new Error(`${where}.environments must name at least one environment.`);
+    return {
+        project,
+        baseUrl,
+        tokenEnv: optionalString(raw.tokenEnv, `${where}.tokenEnv`) ?? DEFAULT_LAUNCHDARKLY_TOKEN_ENV,
+        ...(environments ? { environments } : {}),
+        minDaysOn: optionalPositiveDays(raw.minDaysOn, `${where}.minDaysOn`) ?? 30,
+        temporaryOnly: optionalBoolean(raw.temporaryOnly, `${where}.temporaryOnly`) ?? true,
+        tags: {
+            include: optionalStringList(tags.include, `${where}.tags.include`) ?? [],
+            exclude: optionalStringList(tags.exclude, `${where}.tags.exclude`) ?? [],
+        },
+        map: optionalStringMap(raw.map, `${where}.map`) ?? {},
+    };
+}
 /** Per-adapter defaults for `methods`/`attributes`; the legacy top-level keys override the built-ins. */
 function adapterDefaults(adapter, file) {
     const frontend = file.frontendMethods?.length ? file.frontendMethods : DEFAULT_FRONTEND_METHODS;
@@ -280,6 +372,7 @@ export function loadConfig(cli, cwd = process.cwd()) {
         throw new Error("No projects configured. Add a `projects:` list to flagrm.config.yaml, or pass --frontend and/or --backend.");
     }
     const tools = parseTools(file.tools);
+    const launchdarkly = parseLaunchDarkly(file.launchdarkly, cli.quiet);
     return {
         root: fileDir,
         file: configPath && fs.existsSync(configPath) ? configPath : undefined,
@@ -287,5 +380,6 @@ export function loadConfig(cli, cwd = process.cwd()) {
         projects,
         exclude: [...(file.exclude ?? []), ...(cli.exclude ?? [])],
         include: [...(file.include ?? []), ...(cli.include ?? [])],
+        ...(launchdarkly ? { launchdarkly } : {}),
     };
 }

package/dist/core/detect.js

@@ -5,7 +5,7 @@
  * saves the user from editing a template, and they check the result.
  */
 import path from "node:path";
-import fg from "fast-glob";
+import { globSync } from "tinyglobby";
 import { detectTestRunner } from "./test-runner.js";
 const IGNORE = ["**/node_modules/**", "**/.git/**", "**/bin/**", "**/obj/**", "**/dist/**"];
 const depth = (file) => file.split("/").length;
@@ -32,7 +32,7 @@ function commonDir(files) {
     return common.join("/") || ".";
 }
 export function detectProjects(cwd) {
-    const find = (pattern) => fg.sync(pattern, { cwd, deep: 4, ignore: IGNORE });
+    const find = (pattern) => globSync(pattern, { expandDirectories: false, cwd, deep: 3, ignore: IGNORE });
     const found = [];
     for (const marker of topmost(find("**/angular.json"))) {
         const dir = path.posix.dirname(marker);

package/dist/core/doctor.js

@@ -11,7 +11,7 @@ import { changeFilter, changeFilterAt } from "./change-filter.js";
 import { findConfigFile, loadConfig, TOOL_IDS } from "./config.js";
 import { projectCommands } from "./config-snapshot.js";
 import { gitState, isAncestor } from "./git.js";
-import { installedSkillVersion, SKILLS, stopHookState, TOOL_SKILL_DIRS } from "./install.js";
+import { installedSkillVersion, LEGACY_SKILLS, SKILLS, stopHookState, TOOL_SKILL_DIRS } from "./install.js";
 import { packageVersion } from "./package.js";
 import { resolveProjects } from "./registry.js";
 import { setupReport } from "./scope.js";
@@ -73,6 +73,11 @@ export async function runDoctor(cwd, options = {}) {
         }
         else
             add("ok", `${dir}: skills ${version}`);
+        for (const [legacy, skill] of Object.entries(LEGACY_SKILLS)) {
+            if (fs.existsSync(path.join(root, dir, legacy))) {
+                add("warn", `${dir}/${legacy}: replaced by ${skill} (run flagrm update)`);
+            }
+        }
     }
     const hook = tools.includes("claude-code") ? stopHookState(root) : undefined;
     if (hook === "current")
@@ -97,6 +102,14 @@ async function configChecks(cwd, configFile, options, add) {
         const config = loadConfig({ config: configFile }, cwd);
         root = config.root;
         projects = resolveProjects(config);
+        // Only `flagrm stale` needs the token, so a missing one warns: removals without LaunchDarkly still work.
+        // No request is made: doctor stays offline.
+        const ld = config.launchdarkly;
+        if (ld && !(options.env ?? process.env)[ld.tokenEnv]?.trim()) {
+            add("warn", `launchdarkly: ${ld.tokenEnv} is not set — flagrm stale can't read project "${ld.project}"`);
+        }
+        else if (ld)
+            add("ok", `launchdarkly: project "${ld.project}", token from ${ld.tokenEnv}`);
     }
     catch (err) {
         add("fail", `config: ${err instanceof Error ? err.message : String(err)}`);

package/dist/core/git.js

@@ -13,6 +13,8 @@ function git(cwd, ...args) {
     const result = spawnSync("git", args, { cwd, encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
     return { ok: result.status === 0, stdout: result.stdout ?? "" };
 }
+/** Whether git reads `rev` as a revision: one starting with `-` (`--output=<file>`) would be an option. */
+const isRevision = (rev) => rev !== "" && !rev.startsWith("-");
 /** NUL-separated paths (`-z`), which git never quotes or escapes, whatever the file name. */
 const paths = (text) => text.split("\0").filter(Boolean);
 /** Untracked (and not ignored) files under `cwd`. */
@@ -60,6 +62,8 @@ export function blobIds(cwd, files) {
  * diff plus untracked files), without the ones `ignore` names.
  */
 export function changedFilesSince(cwd, sha, ignore) {
+    if (!isRevision(sha))
+        return undefined;
     const diff = git(cwd, "diff", "-z", "--name-only", "--no-renames", "--relative", sha, ...PATHSPEC);
     if (!diff.ok)
         return undefined;
@@ -72,6 +76,8 @@ export function changedFilesSince(cwd, sha, ignore) {
  * Undefined when git can't tell.
  */
 export function trackedChangesSince(cwd, sha, ignore) {
+    if (!isRevision(sha))
+        return undefined;
     const diff = git(cwd, "diff", "-z", "--name-only", "--no-renames", "--relative", sha, ...PATHSPEC);
     if (!diff.ok)
         return undefined;
@@ -80,6 +86,8 @@ export function trackedChangesSince(cwd, sha, ignore) {
 }
 /** A file's content at `sha`, or undefined when it did not exist there. */
 export function fileAt(cwd, sha, relativePath) {
+    if (!isRevision(sha))
+        return undefined;
     const result = git(cwd, "show", `${sha}:./${relativePath.split(path.sep).join("/")}`);
     return result.ok ? result.stdout : undefined;
 }
@@ -156,6 +164,8 @@ function dropIgnored(cwd, index, ignore) {
 }
 /** The tree id of `cwd` at commit `sha`. */
 export function treeAt(cwd, sha) {
+    if (!isRevision(sha))
+        return undefined;
     const prefix = repoPrefix(cwd);
     if (prefix === undefined)
         return undefined;
@@ -169,5 +179,5 @@ export function headSha(cwd) {
 }
 /** Whether `sha` is HEAD or one of its ancestors. */
 export function isAncestor(cwd, sha) {
-    return git(cwd, "merge-base", "--is-ancestor", sha, "HEAD").ok;
+    return isRevision(sha) && git(cwd, "merge-base", "--is-ancestor", sha, "HEAD").ok;
 }

package/dist/core/hook.js

@@ -8,6 +8,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { changeFilterAt } from "./change-filter.js";
 import { findConfigRoot } from "./config.js";
+import { scanConfigChanged } from "./config-snapshot.js";
 import { headSha, trackedChangesSince, treeFingerprint } from "./git.js";
 import { readJson } from "./util.js";
 /** The hook's stdin: only a JSON object counts, and only fields of the expected type are kept. */
@@ -38,7 +39,8 @@ export function hookRoot(cwd) {
  * matches the current tree. In progress means HEAD is still the baseline
  * commit and a file git tracks changed, other than flagrm's setup files and
  * paths matching `exclude` (a removal paused on a question to the user, or a
- * stray test result file, doesn't count), or the last verify skipped checks.
+ * stray test result file, doesn't count), the config changed in what it
+ * scans or ignores, or the last verify skipped checks.
  * The fingerprint leaves out the same paths, as verify's does. Once HEAD moves (a
  * commit, a branch switch, a merge), that removal is no longer guarded.
  */
@@ -61,7 +63,7 @@ export function stopDecision(root, input) {
             return { block: false };
         const ignore = changeFilterAt(root);
         const edited = (trackedChangesSince(root, head, ignore) ?? []).length > 0;
-        const started = active.filter((flagDir) => edited || lastVerifySkipped(flagDir));
+        const started = active.filter((flagDir) => edited || lastVerifySkipped(flagDir) || configChanged(flagDir, root));
         if (started.length === 0)
             return { block: false };
         const current = treeFingerprint(root, ignore);
@@ -74,6 +76,15 @@ export function stopDecision(root, input) {
         return { block: false };
     }
 }
+/**
+ * Whether the config changed since the baseline (or `--accept config`) in what
+ * is scanned or ignored: widening `exclude` would otherwise hide the removal's
+ * edits from the hook. A verify passing on this tree shows the change and allows.
+ */
+function configChanged(flagDir, root) {
+    const baseline = readJson(path.join(flagDir, "baseline.json"));
+    return scanConfigChanged(baseline?.acceptedConfig ?? baseline?.config, root);
+}
 function lastVerifySkipped(flagDir) {
     const skipped = readJson(path.join(flagDir, "verify.json"))?.skipped;
     return Array.isArray(skipped) && skipped.length > 0;

package/dist/core/install.js

@@ -4,7 +4,8 @@
  * files: for Claude Code the skills and the Stop hook, for GitHub Copilot the
  * skills and `/flagrm-*` prompt files, for Codex the skills and the AGENTS.md
  * pointer. Every step reports what it did; nothing the user wrote is
- * overwritten, and nothing is deleted.
+ * overwritten. The only deletion: `update` replaces a renamed skill that flagrm
+ * installed (see {@link LEGACY_SKILLS}).
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -14,7 +15,13 @@ 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"];
+export const SKILLS = ["flagrm-remove", "flagrm-review"];
+/**
+ * Skills an earlier flagrm installed under another name, and the skill that
+ * replaces each. `update` deletes the old one (only when flagrm's stamp shows
+ * flagrm wrote it) and installs its replacement; `init` deletes nothing.
+ */
+export const LEGACY_SKILLS = { "flagrm-verify": "flagrm-review" };
 /** Where each supported tool discovers repository skills. */
 export const TOOL_SKILL_DIRS = {
     "claude-code": ".claude/skills",
@@ -23,7 +30,7 @@ export const TOOL_SKILL_DIRS = {
 };
 /** Every tool's skills directory: Claude Code, GitHub Copilot, Codex. */
 export const AGENT_SKILL_DIRS = TOOL_IDS.map((t) => TOOL_SKILL_DIRS[t]);
-/** GitHub Copilot prompt files: `/flagrm-remove` and `/flagrm-verify` in Copilot Chat, each pointing at its skill. */
+/** GitHub Copilot prompt files: `/flagrm-remove` and `/flagrm-review` in Copilot Chat, each pointing at its skill. */
 export const PROMPT_FILES = {
     "flagrm-remove": [
         "---",
@@ -35,21 +42,21 @@ export const PROMPT_FILES = {
         "Follow `.github/skills/flagrm-remove/SKILL.md` to remove the feature flags named after this command.",
         "",
     ].join("\n"),
-    "flagrm-verify": [
+    "flagrm-review": [
         "---",
-        "description: Check a feature flag removal with flagrm and propose its commit message",
+        "description: Review a feature flag removal in a fresh session (flagrm verify, then the ON path and deleted tests)",
         "argument-hint: <flag>",
         "agent: agent",
         "---",
         "",
-        "Follow `.github/skills/flagrm-verify/SKILL.md` for the feature flag named after this command.",
+        "Follow `.github/skills/flagrm-review/SKILL.md` for the feature flag named after this command.",
         "",
     ].join("\n"),
 };
 /**
  * The Stop hook command. npx runs the project's own flagrm (a dev dependency)
- * and falls back to a global install. `--no-install` matters: the `flagrm` name
- * on npm belongs to an unrelated package, and a hook must never download code.
+ * and falls back to a global install. `--no-install` matters: a hook must never
+ * download code, so without a local or global flagrm it does nothing.
  * No redirects or `||`: Claude Code runs hooks in PowerShell on Windows
  * without Git Bash, so the command must parse in both shells.
  */
@@ -62,8 +69,8 @@ export const AGENTS_BLOCK = [
     AGENTS_START,
     "## Feature flag removal (flagrm)",
     "",
-    "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`.",
+    "To remove one or more feature flags, follow `.agents/skills/flagrm-remove/SKILL.md`. To review a removal",
+    "in a new session, follow `.agents/skills/flagrm-review/SKILL.md`.",
     AGENTS_END,
 ].join("\n");
 const CONFIG_HEADER = [
@@ -144,6 +151,28 @@ export function writeConfigTemplate(cwd, tools) {
 export function installSkills(cwd, mode, version = packageVersion(), source = path.join(packageRoot(), "skills"), tools = TOOL_IDS) {
     const results = [];
     for (const dir of tools.map((t) => TOOL_SKILL_DIRS[t])) {
+        const replaced = new Set();
+        for (const [legacy, skill] of Object.entries(LEGACY_SKILLS)) {
+            const target = path.join(cwd, dir, legacy);
+            if (!fs.existsSync(target))
+                continue;
+            const step = relativePath(cwd, target);
+            if (mode === "init") {
+                results.push({ path: step, status: "skipped", note: `replaced by ${skill}: run flagrm update to delete it` });
+            }
+            else if (installedSkillVersion(target) === undefined) {
+                results.push({
+                    path: step,
+                    status: "skipped",
+                    note: "no flagrm-version stamp, so not deleted: delete it by hand",
+                });
+            }
+            else {
+                fs.rmSync(target, { recursive: true, force: true });
+                results.push({ path: step, status: "deleted", note: `replaced by ${skill}` });
+                replaced.add(skill);
+            }
+        }
         for (const skill of SKILLS) {
             const target = path.join(cwd, dir, skill);
             const exists = fs.existsSync(target);
@@ -151,7 +180,7 @@ export function installSkills(cwd, mode, version = packageVersion(), source = pa
                 results.push({ path: relativePath(cwd, target), status: "skipped" });
                 continue;
             }
-            if (mode === "update" && !exists)
+            if (mode === "update" && !exists && !replaced.has(skill))
                 continue;
             const before = exists ? snapshot(target) : undefined;
             fs.rmSync(target, { recursive: true, force: true });
@@ -193,18 +222,41 @@ export function installedSkillVersion(skillDir) {
         return undefined;
     }
 }
-/** GitHub Copilot's `/flagrm-remove` and `/flagrm-verify` prompt files in `.github/prompts/`. */
+/** GitHub Copilot's `/flagrm-remove` and `/flagrm-review` prompt files in `.github/prompts/`. */
 export function installPrompts(cwd, mode) {
     const results = [];
+    const prompt = (skill) => path.join(cwd, ".github", "prompts", `${skill}.prompt.md`);
+    const replaced = new Set();
+    for (const [legacy, skill] of Object.entries(LEGACY_SKILLS)) {
+        const file = prompt(legacy);
+        if (!fs.existsSync(file))
+            continue;
+        const step = relativePath(cwd, file);
+        if (mode === "init") {
+            results.push({ path: step, status: "skipped", note: `replaced by ${skill}: run flagrm update to delete it` });
+        }
+        else if (!fs.readFileSync(file, "utf8").includes(`.github/skills/${legacy}/SKILL.md`)) {
+            results.push({
+                path: step,
+                status: "skipped",
+                note: `doesn't point at flagrm's ${legacy} skill, so not deleted`,
+            });
+        }
+        else {
+            fs.rmSync(file);
+            results.push({ path: step, status: "deleted", note: `replaced by ${skill}` });
+            replaced.add(skill);
+        }
+    }
     for (const skill of SKILLS) {
-        const file = path.join(cwd, ".github", "prompts", `${skill}.prompt.md`);
+        const file = prompt(skill);
         const step = relativePath(cwd, file);
         const exists = fs.existsSync(file);
         if (mode === "init" && exists) {
             results.push({ path: step, status: "skipped" });
             continue;
         }
-        if (mode === "update" && !exists)
+        if (mode === "update" && !exists && !replaced.has(skill))
             continue;
         const before = exists ? fs.readFileSync(file, "utf8") : undefined;
         if (before === PROMPT_FILES[skill]) {
@@ -372,7 +424,10 @@ export function initProject(root, tools = TOOL_IDS) {
         ...deselectedSteps(root, tools),
     ];
 }
-/** `flagrm update`: refresh what `init` installed in `root` for `tools` from this flagrm version; adds nothing new. */
+/**
+ * `flagrm update`: refresh what `init` installed in `root` for `tools` from this
+ * flagrm version. Adds nothing new, except the replacement of a renamed skill it deletes.
+ */
 export function updateProject(root, tools = TOOL_IDS) {
     return [...tools.flatMap((t) => toolSteps(root, t, "update")), ...deselectedSteps(root, tools)];
 }