@@ -7,6 +7,19 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+### Fixed — `meta upgrade` printed one retirement's rationale once per OCCURRENCE
+
+An adopter estate carrying 24 `@forge*` attributes got ~96 lines of output for one
+retirement: every occurrence repeated the same `why`, the same two options and the same
+guide link. The instruction was buried in its own repetition — the exact failure
+`runGen`'s no-manifest refusal aggregates to avoid, in a command that had not learned it.
+
+Occurrences are per-line information and still print per line (file, line, subject, the
+value found). The rationale is per RULE and now prints once, after the listing, headed by
+the attributes it covers so a reader can connect the paragraph to the lines above it. Two
+rules that render identically collapse; two that differ anywhere do not.
+
+
 ### Fixed — a failed D1 introspection named a WARNING as its cause
 
 `meta verify --db` / `meta migrate` against a live D1 shell out to
 
@@ -126,6 +126,14 @@ export async function upgradeCommand(args: string[], cwd: string): Promise<numbe
     ...(flags.maxVersion !== undefined ? { maxVersion: flags.maxVersion } : {}),
   };
 
+  // One retirement RULE, however many occurrences it has. An estate hit this with 24
+  // `@forge*` attributes, and the per-occurrence rationale turned the output into ~96
+  // lines saying one thing four times over — the wall that buries the instruction it is
+  // made of, which is the exact failure `runGen`'s no-manifest refusal aggregates to
+  // avoid. Keyed by the rendered text, so two rules that happen to read identically
+  // collapse and two that differ anywhere do not.
+  const rules = new Map<string, { why: string; suggestions: string[]; subjects: Set<string> }>();
+
   for (const file of files) {
     const rel = relative(projectRoot, file);
     const before = await readFile(file, "utf8");
@@ -148,22 +156,24 @@ export async function upgradeCommand(args: string[], cwd: string): Promise<numbe
     log.info(`\n${rel}`);
     for (const c of r.changes) log.info(`  ${c.line}: @${c.from} → ${c.to}`);
     for (const f of r.refusals) {
-      // The WHY and the replacement both print, and the guide is not an alternative to
-      // them. This used to read `Retired in <since>. See <guide>` — dropping `why`
-      // whenever a guide existed, which is almost always, and dropping `replacedBy`
-      // unconditionally. For the `@forge*` entries that removed the only actionable
-      // sentence there is ("opt the provider in explicitly"), and for an authored
-      // `<type>.base` it announced a retirement of something that was never authorable —
-      // telling the reader they used to have a working feature. Hence "no longer accepted
-      // as of", which is true of both, with the carefully-written `why` beside it.
+      // The occurrence line is per-line information: file, line, subject, the value found.
+      // The RATIONALE that goes with it is per RULE and prints once, after the listing —
+      // see `rules` below.
       log.warn(
         `  ${f.line}: ${f.subject}${f.value !== undefined ? `: ${f.value}` : ""} — needs a decision ` +
           `(no longer accepted as of ${f.since}).`,
       );
-      log.warn(`      ${f.why}`);
-      // The same suggestion list every OTHER door prints for a retirement, rather than a
-      // second rendering of the same note that can drift from it.
-      for (const line of retirementSuggestions(f)) log.warn(`      ${line}`);
+      const key = `${f.why}\u0000${retirementSuggestions(f).join("\u0000")}`;
+      const rule = rules.get(key);
+      if (rule === undefined) {
+        rules.set(key, {
+          why: f.why,
+          suggestions: retirementSuggestions(f),
+          subjects: new Set([f.subject]),
+        });
+      } else {
+        rule.subjects.add(f.subject);
+      }
     }
 
     totalChanges += r.changes.length;
@@ -175,6 +185,21 @@ export async function upgradeCommand(args: string[], cwd: string): Promise<numbe
   }
 
   log.info("");
+
+  // The WHY and the options, once per rule. Both print, and the guide is not an
+  // alternative to them: this used to read `Retired in <since>. See <guide>`, dropping
+  // `why` whenever a guide existed — which is almost always — and dropping `replacedBy`
+  // unconditionally. For the `@forge*` entries that removed the only actionable sentence
+  // there is ("opt the provider in explicitly"). The subject list is what lets a reader
+  // connect the paragraph back to the lines above it now that it prints away from them.
+  for (const rule of rules.values()) {
+    const subjects = [...rule.subjects].sort().join(", ");
+    log.warn(`\n  ${subjects} — why, and what to do:`);
+    log.warn(`      ${rule.why}`);
+    for (const line of rule.suggestions) log.warn(`      ${line}`);
+  }
+  if (rules.size > 0) log.info("");
+
   if (notChecked.length > 0) {
     log.warn(
       `${notChecked.length} file(s) could not be parsed and were NOT checked — fix these ` +
 
@@ -86,3 +86,68 @@ describe("meta upgrade and the deregistered @forge* vocabulary", () => {
     expect(err).toContain("@forgeRationale");    // on field.long
   });
 });
+
+// ── the wall ──────────────────────────────────────────────────────────────────
+//
+// An adopter estate hit this with 24 `@forge*` occurrences. Every one printed the same
+// three lines — the `why`, the keep-them option, the delete-them option, the guide — so
+// the output was ~96 lines saying one thing four times over, and the instruction was
+// buried in its own repetition. That is exactly the failure `runGen`'s no-manifest
+// refusal aggregates to avoid, in a command that had not learned it.
+//
+// Occurrences are per-line information and stay per line. The RATIONALE is per RULE, and
+// prints once.
+describe("many occurrences of one retirement", () => {
+  const MANY = {
+    "metadata.root": {
+      package: "acme",
+      children: ["A", "B", "C", "D"].map((n) => ({
+        "object.entity": {
+          name: n, "@forgeConfidence": "high", "@forgeSource": "an interview",
+          children: [
+            { "source.rdb": { "@table": n.toLowerCase() } },
+            { "field.long": { name: "id" } },
+            { "identity.primary": { "@fields": ["id"], "@generation": "increment" } },
+          ],
+        },
+      })),
+    },
+  };
+
+  async function upgradeMany(): Promise<{ exit: number; err: string }> {
+    const dir = await mkdtemp(join(tmpdir(), "forge-wall-"));
+    dirs.push(dir);
+    await mkdir(join(dir, "metaobjects"), { recursive: true });
+    await writeFile(join(dir, "metaobjects", "meta.json"), JSON.stringify(MANY), "utf8");
+    const lines: string[] = [];
+    const oe = console.error, ol = console.log;
+    console.error = (...a: unknown[]) => { lines.push(a.map(String).join(" ")); };
+    console.log = (...a: unknown[]) => { lines.push(a.map(String).join(" ")); };
+    try { return { exit: await run(["upgrade", "--cwd", dir]), err: lines.join("\n") }; }
+    finally { console.error = oe; console.log = ol; }
+  }
+
+  test("every occurrence is still named", async () => {
+    const { exit, err } = await upgradeMany();
+    expect(exit).toBe(1);
+    // 4 entities × 2 attributes = 8 occurrence lines.
+    expect(err.split("\n").filter((l) => l.includes("needs a decision"))).toHaveLength(8);
+  });
+
+  test("the reason and the options print ONCE, not once per occurrence", async () => {
+    const { err } = await upgradeMany();
+    const count = (needle: string): number => err.split("\n").filter((l) => l.includes(needle)).length;
+    expect(count("expected-registry.json")).toBe(1);   // the why
+    expect(count("forgeTypesProvider")).toBe(1);       // keep them
+    expect(count("0.x-to-1.0.md")).toBe(1);            // the guide
+  });
+
+  test("the rationale names which attributes it is about", async () => {
+    // Printed away from the occurrence lines, it has to say what it applies to — or the
+    // reader has to guess which of the refusals the paragraph belongs to.
+    const { err } = await upgradeMany();
+    const idx = err.indexOf("expected-registry.json");
+    const paragraph = err.slice(Math.max(0, idx - 400), idx);
+    expect(paragraph).toContain("@forgeConfidence");
+  });
+});