test(migrate): make "a migration owns the prose" enforceable

Follow-up to the N9 fix, turning the lesson into a check rather than a
thing to remember.

A migration that moves, renames or deletes anything under `.taskless/`
makes the files describing that directory wrong from that moment, and it
is the only commit that knows. Every other mechanism runs later than the
moment the fact changed, which is how `rule-tests/` stayed in the
installed README and skill description for two releases after `0005`
deleted it.

The rule is written at the migration registry, where the next person to
add one will be looking, with the three things that follow: update what
describes the directory, refresh this repository's own `.taskless/` and
commit it, and ask whether already-current projects need a version to
reach them at all.

The check is `installed-documentation.test.ts`, and it asks the question
nothing was asking: is the artifact installed in THIS repository the one
this build would write. Not whether a generated file matches its own
generator, which is vacuous — whether the copy on disk was refreshed
after the template changed, which is the step that was missed. It also
names `rule-tests/` and `sg/rules/` directly, so a reintroduction is
caught by what it says and not only by a whole-file comparison.

Verified by reintroducing the stale sentence and confirming both
assertions fail.

Author: theCodeDrift

packages/cli/src/filesystem/migrate.ts

@@ -265,6 +265,32 @@ export interface RunMigrationsOptions {
   allowVersionMismatches?: boolean;
 }
 
+/**
+ * A MIGRATION OWNS EVERYTHING UNDER `.taskless/`, INCLUDING THE PROSE.
+ *
+ * If a migration moves, renames or deletes anything in that directory, the
+ * files describing the directory are wrong from that moment, and the migration
+ * is the only commit that knows it. Every other mechanism — a reviewer, a
+ * linter, someone noticing — runs later than the moment the fact changed.
+ *
+ * That is not hypothetical here. `0004` and `0005` relocated every rule and
+ * deleted `rule-tests/`, and the installed `README.md` and skill description
+ * went on naming the old tree for two releases. `0001` rewrites the README on
+ * every run, which sounds like it covers this and does not: migrations only run
+ * ABOVE the recorded version, so a project that is already current never
+ * rewrites anything. Reaching those projects took `0006`.
+ *
+ * So when you write a migration that changes this directory's shape:
+ *
+ * 1. Update whatever describes it. `0001`'s README body derives its layout
+ *    section from the rule layout table, so a table change carries; anything
+ *    written as prose does not.
+ * 2. Refresh this repository's own `.taskless/` and commit it, since we install
+ *    Taskless on ourselves. `installed-documentation.test.ts` fails if you forget.
+ * 3. Ask whether already-current projects need the change. If they do, the only
+ *    thing that reaches them is a new version, because nothing below the
+ *    recorded one runs again.
+ */
 /**
  * The schema version a current CLI migrates a project to.
  *

packages/cli/test/installed-documentation.test.ts

@@ -0,0 +1,65 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import { buildReadmeContent } from "../src/filesystem/migrations/0001-init";
+import { pinnedSpecifier } from "../src/util/package-manager";
+
+/**
+ * This repository runs Taskless on itself, so its own `.taskless/` is an
+ * installed project like any other, and it went stale exactly the way a user's
+ * would: the README described `sg/rules/` and `rule-tests/` for two migrations
+ * after `0004` and `0005` dismantled that tree.
+ *
+ * WHAT LET IT SIT THERE was that nothing compared the file on disk to what the
+ * current build would write. Changing the template is a source edit; refreshing
+ * an already-migrated project is a separate act that nobody was reminded to
+ * perform, and `runMigrations` returns early on a current project so it never
+ * happened by itself.
+ *
+ * This is the reminder. It is deliberately about OUR copy rather than about the
+ * generator: asserting that a generated file matches its own generator would be
+ * vacuous. The question worth asking is whether the installed artifact in this
+ * repository is the one this build produces.
+ */
+
+const repositoryRoot = resolve(import.meta.dirname, "../../..");
+
+describe("this repository's own installed Taskless docs", () => {
+  it("carries the README this build would write", async () => {
+    const onDisk = await readFile(
+      resolve(repositoryRoot, ".taskless", "README.md"),
+      "utf8"
+    );
+
+    // If this fails, the template changed and this project was not migrated.
+    // Run `pnpm build && pnpm cli init --no-interactive` and commit the result;
+    // do not edit `.taskless/README.md` by hand, since the next migration
+    // overwrites it.
+    expect(onDisk).toBe(buildReadmeContent(pinnedSpecifier()));
+  });
+
+  it("describes no directory the layout migrations removed", async () => {
+    // The specific stale words, named so a reintroduction is caught by what it
+    // says rather than only by a whole-file comparison. `rule-tests/` is the
+    // directory `0005` deletes.
+    const onDisk = await readFile(
+      resolve(repositoryRoot, ".taskless", "README.md"),
+      "utf8"
+    );
+    expect(onDisk).not.toContain("rule-tests");
+    expect(onDisk).not.toContain("sg/rules/");
+  });
+
+  it("keeps the skill's trigger text off the old layout too", async () => {
+    // The skill description is what an agent reads before it opens anything, so
+    // a stale directory name here sends it looking in a place that no longer
+    // exists. Checked at the SOURCE, which is what `init` installs from.
+    const skill = await readFile(
+      resolve(repositoryRoot, "skills", "taskless", "SKILL.md"),
+      "utf8"
+    );
+    expect(skill).not.toContain("rule-tests");
+  });
+});