docs(adr): supersede ADR-2376 to leave the icon-mode removal release undecided

[kompiro]

Summary

Supersedes ADR-2376 with ADR-2906. Icon display mode stays deprecated, but we no longer commit to removing it in the next major. The release that removes it will be decided by a separate ADR when the scope of v2 and later is settled.

What changed: the contents of the next major (v2) are not decided. ADR-2376 used "the next major" as the removal slot, which fixed one breaking change in a release whose scope does not exist yet.

Changes

• docs/adr/2906-icon-mode-removal-release-undecided.md: new ADR. It carries over ADR-2376's Phase 1 record, the Phase 2 evaluation, step 1 (the deprecation notice already shipped with shape mode: an external shape: url() icon gets no card frame and is stretched off-aspect #2696) and step 3 (no investment in icon-mode-specific rendering bugs; Icon mode: the annotation badge is drawn over the title, and the title budget ignores it #2639 stays won't-fix). It replaces step 2 (removal in the next major) and drops README.md from the notice locations, because the README no longer lists features after docs: streamline README onboarding #2905.
• docs/adr/2376-...md: frontmatter status: superseded / superseded_by: ADR-2906 plus the body status line only. The body prose is unchanged.
• docs/tools/app.md / docs/tools/app.ja.md: the notice now says removal happens in a future major and the release is not decided yet.
• .changeset/icon-mode-removal-release-undecided.md: new correcting changeset (core + CLI patch; karasu-vscode follows via cascade). The original shape-mode-external-icon-card changeset was already consumed by the 0.7.0 / core 0.3.0 release (chore: release karasu 0.7.0, @karasu-tools/core 0.3.0, karasu-vscode 0.2.0 #2921) with the "next major" wording, so the published CHANGELOG entries stay as they are and the next release notes retract the promise.
• docs/adr/effective.md, graph.md, graph/renderer.md: regenerated.

Not eligible for the ADR-only auto-merge: the diff also touches docs/tools/ and adds a changeset.

Test plan

• pnpm adr:validate (no warnings for ADR-2906 / ADR-2376)
• pnpm adr:check-assumptions (0 failing)
• pnpm adr:regenerate output committed
• pnpm changeset status --since=main shows a patch for @karasu-tools/core and karasu (and karasu-vscode via cascade)
• No other "next major" promise for icon mode remains outside docs/adr/ (grep)

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Clarified that deprecated icon-card mode is planned for removal in a future major release, but the release has not yet been decided.
  • Updated the recommended migration guidance to use shape mode with a URL.
  • Clarified that existing icon-card behavior remains unchanged for now.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: kompiro/karasu/.coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: 492b9dca-ce30-4858-a587-c1c42a689d7e

📥 Commits

Reviewing files that changed from the base of the PR and between eb44043 and 0585558.

⛔ Files ignored due to path filters (3)

• docs/adr/effective.md is excluded by !docs/adr/effective.md
• docs/adr/graph.md is excluded by !docs/adr/graph.md
• docs/adr/graph/renderer.md is excluded by !docs/adr/graph/**

📒 Files selected for processing (5)

• .changeset/icon-mode-removal-release-undecided.md
• docs/adr/2376-icon-display-mode-de-emphasis-and-removal-path.md
• docs/adr/2906-icon-mode-removal-release-undecided.md
• docs/tools/app.ja.md
• docs/tools/app.md

Included review availability: This review used your included allowance. 0 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 8 reviews per hour.

---

📝 Walkthrough

Walkthrough

The change leaves icon display mode deprecated but removes the commitment to remove it in the next major release. ADR-2906 records the undecided release timing, and the related ADR, tool documentation, and changeset reflect that decision.

Changes

Icon mode removal timing

Layer / File(s)	Summary
Removal timing decision docs/adr/2906-icon-mode-removal-release-undecided.md, docs/adr/2376-icon-display-mode-de-emphasis-and-removal-path.md	ADR-2906 leaves the removal release for a future ADR. It keeps the deprecation and existing API and UI behavior. ADR-2376 now identifies ADR-2906 as superseding it.
Deprecation notices and release-note correction docs/tools/app.md, docs/tools/app.ja.md, .changeset/icon-mode-removal-release-undecided.md	The English and Japanese notices say removal will occur in a future major, with the specific release undecided. The changeset records this correction for the core and CLI packages.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~5 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to 05855

The notices now leave the removal release undecided, and the correction covers both packages without rewriting published release notes or changing icon-mode behavior. No remaining issue is indicated, so the change is ready for normal checks.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title uses the required docs(adr): subject format, uses the valid adr documentation scope, states the main change, uses imperative mood, and has no trailing period.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

_{Comment @coderabbitai help to get the list of available commands.}

[kompiro]

Code review

Found 1 issue:

1. ADR-2906 says the shape-mode-external-icon-card changeset "is not released yet", and its 理由 section leans on that ("the wording can be fixed before it reaches release notes"). That no longer holds. The release PR chore: release karasu 0.7.0, @karasu-tools/core 0.3.0, karasu-vscode 0.2.0 #2921 (commit 9e12cbc) consumed the changeset with the old "removed in the next major version" wording into packages/core/CHANGELOG.md (L526) and packages/cli/CHANGELOG.md, and deleted the file on main. This PR now has a modify/delete conflict on .changeset/shape-mode-external-icon-card.md (mergeable: CONFLICTING). Suggested fix: merge main, drop the edit to the consumed changeset, correct the ADR's background and reasons to say the old wording shipped in karasu 0.7.0 / @karasu-tools/core 0.3.0, and consider a new changeset so the next release notes retract the "next major" promise.

karasu/docs/adr/2906-icon-mode-removal-release-undecided.md

Lines 50 to 53 in 5ed851b

	ステップ 1 は #2696（PR #2797）で実施された。`docs/tools/app.md` / `app.ja.md` と
	changeset `shape-mode-external-icon-card` は「非推奨であり、次の major で削除する」と書いた。
	ただし changeset はまだ release されておらず、この文面は release notes には出ていない。

karasu/docs/adr/2906-icon-mode-removal-release-undecided.md

Lines 88 to 91 in 5ed851b

	よいという ADR-2376 の利点は、ステップ 3 を引き継ぐことで保たれる。
	- **文面を直すコストが今は小さい。** 「次の major」の文面は changeset としてまだ release
	されていないので、release notes に出る前に直せる。

karasu/.changeset/shape-mode-external-icon-card.md

Lines 16 to 19 in 5ed851b

	With that migration target shipped, **icon display mode is deprecated** and
	will be removed in a future major version (which release is not decided yet) —
	use shape mode with `shape: url(...)` instead (ADR-2376, ADR-2906).

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}