ci: make local plugin release notes resilient to large releases

[MLittleprince]

Summary

• aggregate local-plugin commits into deterministic user-facing release topics while preserving every source ref
• align standalone and weekly release-note item limits with the Doc Agent dynamic 12-18 policy
• handle net-zero reverts and numeric hexadecimal commit refs correctly
• make the read-only offline preview compact large evidence sets without truncating required refs
• add v2.0.18 and future high-commit regression coverage

Why

The v2.0.18 release had 29 important local-plugin commits. The old drafting path produced 12 items that referenced only 12 of those commits, so strict evidence validation stopped the workflow before npm, tag, and GitHub Release side effects.

The Doc Agent already supports a dynamic item budget, but these caller-side MemOS changes had not been committed or submitted. This PR makes both sides use the same rule and groups related commits before drafting, so concise notes can still retain complete evidence coverage.

Policy

• item budget: min(18, max(12, ceil(required_count / 2)))
• 29 required commits therefore allow up to 15 items
• related commits may share one release item, but all of their source_refs are preserved
• missing or invented refs, uncovered important commits, mixed-language copy, duplicate copy, and invalid release binding still fail closed

Safety

• no workflow permissions, secrets, npm publish behavior, tag behavior, or GitHub Release ordering changed
• no package runtime source changed
• both the weekly MemOS release path and standalone local-plugin path use the same evidence policy
• small releases retain the existing 12-item limit
• the PR dry-run fallback remains side-effect-free and now preserves complete evidence instead of slicing to 10 items

Verification

• node --check passed for both changed scripts
• git diff --check passed
• full local-plugin release automation suite: 162/162 tests passed
• GitHub MemOS Release — Pre-Merge Dry Run passed in run 33365598362
• real inspection result: 28 effective important commits, 14 items, 28/28 covered refs, 0 validation issues

[Memtensor-AI]

🤖 Open Code Review

Target: PR #2311
Task: ce0ab48705cec8a0
Base: main
Head: fix/local-plugin-v218-evidence

🔍 OpenCodeReview found 17 issue(s) in this PR.

⚠️ 1 warning(s) occurred during review.

---

1. .github/scripts/draft-local-plugin-release-notes.test.mjs (L319-L322)

The <= 15 bound is inconsistent with what the implementation actually guarantees. releaseTopicsForCommits calls compactReleaseTopics with releaseTopicLimitForRequiredCount(commits.length) where commits.length is 31 (not 29), yielding a real limit of min(18, max(12, ceil(31/2))) = 16. The test-only commits are excluded from hints but still counted in commits.length, so the effective compact limit is 16, not 15. This test could spuriously fail if the actual topics land at 16. The assertion should use releaseTopicLimitForRequiredCount(commits.length) to stay in sync with the implementation.

💡 Suggested Change

Before:

  const topics = releaseTopicsForCommits(commits);
  assert.ok(topics.length > 1);
  assert.ok(topics.length <= 15);
  assert.equal(releaseTopicLimitForRequiredCount(29), 15);

After:

  const topics = releaseTopicsForCommits(commits);
  assert.ok(topics.length > 1);
  assert.ok(topics.length <= releaseTopicLimitForRequiredCount(commits.length));
  assert.equal(releaseTopicLimitForRequiredCount(29), 15);

---

2. .github/scripts/draft-local-plugin-release-notes.test.mjs (L406-L407)

The key-uniqueness check passes trivially because compactReleaseTopics always assigns a fresh consolidated-* key to every merged topic. This means the Set size will always equal compacted.length regardless of whether distinct source topics were incorrectly collapsed. The check does not verify that a topic's original key is preserved when it is not merged — only that the output keys are mutually distinct. Consider also asserting that topics below the compaction threshold retain their original key values.

💡 Suggested Change

Before:

  assert.equal(compacted.length, 18);
  assert.equal(new Set(compacted.map((topic) => topic.key)).size, compacted.length);

After:

  assert.equal(compacted.length, 18);
  assert.equal(new Set(compacted.map((topic) => topic.key)).size, compacted.length);
  // Topics whose keys are not consolidated should be unchanged
  const unconsolidatedKeys = compacted
    .filter((topic) => !topic.key.startsWith("consolidated-"))
    .map((topic) => topic.key);
  assert.ok(unconsolidatedKeys.every((key) => topics.some((t) => t.key === key)));

---

3. .github/scripts/draft-local-plugin-release-notes.test.mjs (L403-L405)

These expected values (12, 15, 18) are hardcoded magic numbers that duplicate the formula min(MAX_RELEASE_TOPICS, max(MIN_RELEASE_TOPICS, ceil(n/2))) without referencing the named constants. If MIN_RELEASE_TOPICS or MAX_RELEASE_TOPICS changes in the production code, the test values silently become wrong with no hint of the correct values. Consider deriving the expected values from the exported constants or at least adding an inline comment with the formula.

💡 Suggested Change

Before:

  assert.equal(releaseTopicLimitForRequiredCount(2), 12);
  assert.equal(releaseTopicLimitForRequiredCount(29), 15);
  assert.equal(releaseTopicLimitForRequiredCount(40), 18);

After:

  // Formula: min(MAX_RELEASE_TOPICS=18, max(MIN_RELEASE_TOPICS=12, ceil(n/2)))
  assert.equal(releaseTopicLimitForRequiredCount(2), 12);   // max(12, ceil(1))=12
  assert.equal(releaseTopicLimitForRequiredCount(29), 15);  // max(12, ceil(14.5))=15
  assert.equal(releaseTopicLimitForRequiredCount(40), 18);  // min(18, ceil(20))=18

---

4. .github/scripts/prepare-memos-release.mjs (L1503-L1506)

The previous implementation explicitly filtered out revert commits before building sourceItems:

.filter((item) => !/^revert\b/i.test(item.text))
.filter((item) => !revertedKeys.has(...))

This new code removes both filters, so revert commits will pass through fallbackTopicForText and may appear as release note entries. Consider re-adding the revert-commit guard:

const revertedKeys = new Set((evidence.reverted_change_keys || []).map((k) => String(k).toLowerCase()));
const sourceItems = evidence.important_commits
  .filter((commit) => !/^revert\b/i.test(commit.subject))
  .filter((commit) => !revertedKeys.has(commit.subject.toLowerCase()))
  .map((commit) => ({ text: commit.subject, source_refs: [commit.short_sha] }));

---

5. .github/scripts/prepare-memos-release.mjs (L31)

MIN_RELEASE_ITEMS reads as "the minimum number of items required", but it is actually the floor for the dynamic cap computed in releaseItemLimitForRequiredCount. A name like RELEASE_ITEMS_LIMIT_FLOOR or MIN_RELEASE_ITEM_LIMIT would express the intent more clearly.

---

6. .github/scripts/prepare-memos-release.mjs (L1465)

An unrecognised category value silently falls back to "Improved" copy, producing quietly incorrect release notes with no diagnostic. Consider logging a warning:

if (!copy[category]) {
  warn(`combinedFallbackCopy: unknown category "${category}", falling back to Improved`);
}
return copy[category] || copy.Improved;

---

7. .github/scripts/prepare-memos-release.mjs (L1480-L1481)

The scoring formula is non-obvious: a lower score wins, so pairs with fewer combined source refs are merged first, keeping high-evidence items intact. Without a comment this reads like an arbitrary magic number and will mislead future maintainers. Consider adding:

// Prefer merging low-evidence pairs first (fewest combined source_refs) to preserve
// high-evidence items as independent entries.

---

8. .github/scripts/draft-local-plugin-release-notes.mjs (L757-L770)

In the new topic-mode branch, refs are added to refToGroup but are no longer added to knownRefs. The old code (hint-mode) called knownRefs.add(ref) inside this loop. knownRefs is used downstream in coverageFromReleaseItems to determine which refs are "known" when computing coverage. With this omission, topic-mode refs won't appear in knownRefs, which could cause coverage checks to treat them as unknown and produce false coverage failures. Consider restoring knownRefs.add(ref) inside the topic-mode loop.

💡 Suggested Change

Before:

  const topics = evidence?.release_note_guidance?.release_topics || [];
  const sourceGroups = topics.length > 0
    ? topics
    : evidence?.release_note_guidance?.source_ref_category_hints || [];
  for (const [position, hint] of sourceGroups.entries()) {
    const refs = normalizeSourceRefs(hint.source_refs);
    const category = normalizeReleaseCategory(hint.category);
    if (refs.length === 0 || !category) continue;
    const groupKey = topics.length > 0
      ? `topic:${String(hint.key || position)}`
      : refs[0];
    for (const ref of refs) {
      refToGroup.set(ref, groupKey);
    }

After:

    for (const ref of refs) {
      knownRefs.add(ref);
      refToGroup.set(ref, groupKey);
    }

---

9. .github/scripts/draft-local-plugin-release-notes.mjs (L705)

The removal of if (/^\d{2,}$/.test(text)) return \#${text}`;silently drops bare numeric PR refs (e.g."2311") — they now return ""instead of being normalized to"#2311"`. If any existing draft payloads or external callers emit bare numeric strings as source_refs, those refs will be lost without any warning. This is a silent data-loss breaking change. Verify that no upstream producer emits bare numeric refs, or add an explicit rejection path.

---

10. .github/scripts/draft-local-plugin-release-notes.mjs (L58-L61)

The count / 2 divisor (half the commit count, clamped to 12–18) has no explanation. It is non-obvious why halving the commit count is the right ratio, and a future maintainer who changes MIN_RELEASE_TOPICS or MAX_RELEASE_TOPICS may not realize the relationship. A short comment explaining the intent (e.g. "roughly one release topic per two commits") would help.

---

11. .github/scripts/draft-local-plugin-release-notes.mjs (L965-L969)

This backfill unconditionally appends all refs from owned groups onto the winning item, even refs that the item never originally referenced. While this preserves topic evidence coverage, it means a release item's source_refs in the output can contain refs it never had in the input. Downstream consumers that assume source_refs only includes refs the AI explicitly cited may be surprised. Consider documenting this behavior or validating that downstream processing handles the expanded ref list correctly.

---

12. .github/scripts/draft-local-plugin-release-notes.mjs (L245-L248)

The inner spread-and-reverse [...seen].reverse().find(...) creates a new reversed array on every revert commit, making the overall loop O(n²) in the number of commits. For typical release ranges this is fine, but if the commit range ever grows large (hundreds of commits with many reverts), this will become noticeable. A Map from SHA to commit would make lookups O(1).

---

13. .github/scripts/draft-local-plugin-release-notes.mjs (L399-L402)

The fallback in categoryHintForSubject changed from returning null ("let the AI decide") to returning a concrete "Improved" hint. This means every previously unrecognized commit now gets an opinionated nudge toward "Improved" rather than being freely classified. This is a deliberate policy shift that affects AI output quality. The change itself may be intentional, but a comment documenting why "Improved" is the right default would prevent future maintainers from reverting it without understanding the rationale.

---

14. .github/scripts/prepare-memos-release.test.mjs (L1397-L1399)

These three assertions for releaseItemLimitForRequiredCount are embedded inside a test that is primarily about draft validation. If any of these assertions fail, the test aborts before the validation logic runs, producing a misleading failure message with no context. They should be extracted into their own dedicated unit test.

---

15. .github/scripts/prepare-memos-release.test.mjs (L1440)

This exact-count assertion couples the test to the current output of releaseItemLimitForRequiredCount(29). If the scaling formula changes intentionally, this test breaks without a clear explanation. Consider using releaseItemLimitForRequiredCount(29) as the expected value to make the intent explicit:

assert.equal(draft.release_items.length, releaseItemLimitForRequiredCount(29));

---

16. .github/scripts/prepare-memos-release.test.mjs (L1433-L1435)

Mutating process.env directly inside the test is not safe under parallel test runners. Another concurrent test could observe the modified environment between the mutation and the finally restore. If the test runner ever enables concurrency, this will cause non-deterministic failures. Consider running this test explicitly serially, or passing overrides as arguments to requestDocAgentDraft if the API allows it.

---

17. .github/scripts/prepare-memos-release.test.mjs (L1470)

The test name says "keeps categories separate", but this assertion only verifies that no unexpected category values appear — it passes even if compaction silently drops all "Fixed" items. Add an explicit check that both categories are present in the output:

const categories = new Set(compacted.map((item) => item.category));
assert.ok(categories.has("Improved") && categories.has("Fixed"));

---

🧹 Filtered 2 low-confidence OCR finding(s) before posting/fix-loop (existing_code_mismatch: 2).

Generated by cloud-assistant via Open Code Review.

[Memtensor-AI]

✅ Automated Test Results: PASSED

All tests passed (1/1 executed). memos_github_open_source/smoke: 1/1. Duration: 1s

Branch: fix/local-plugin-v218-evidence