diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 9b6e319..b3877ae 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -9,7 +9,7 @@
     {
       "name": "ndf",
       "source": "./plugins/ndf-claude",
-      "description": "Claude Code plugin (v4.19.0): 8 specialized agents, focused NDF skills for PR/review workflows, implementation planning, plan-to-spec, browser smoke testing, statusline, Codex CLI delegation, transcript retention guard, default statusline setup, and optional Slack notifications."
+      "description": "Claude Code plugin (v4.20.0): 8 specialized agents, focused NDF skills for PR/review workflows, implementation planning, plan-to-spec, browser smoke testing, statusline, Codex CLI delegation, transcript retention guard, default statusline setup, and optional Slack notifications."
     },
     {
       "name": "mcp-playwright",
diff --git a/.serena/project.yml b/.serena/project.yml
index c583c4d..bdc1891 100644
--- a/.serena/project.yml
+++ b/.serena/project.yml
@@ -1,25 +1,28 @@
 
-
-# list of languages for which language servers are started; choose from:
-#   al                  angular             ansible             bash                clojure
-#   cpp                 cpp_ccls            crystal             csharp              csharp_omnisharp
-#   dart                elixir              elm                 erlang              fortran
-#   fsharp              go                  groovy              haskell             haxe
-#   hlsl                html                java                json                julia
-#   kotlin              lean4               lua                 luau                markdown
+# list of languages for which language servers are started (LSP backend only); choose from:
+#   ada                 al                  angular             ansible             bash
+#   bsl                 clojure             cpp                 cpp_ccls            crystal
+#   csharp              csharp_omnisharp    cue                 dart                elixir
+#   elm                 erlang              fortran             fsharp              gdscript
+#   go                  groovy              haskell             haxe                hlsl
+#   html                java                json                julia               kotlin
+#   latex               lean4               lua                 luau                markdown
 #   matlab              msl                 nix                 ocaml               pascal
-#   perl                php                 php_phpactor        powershell          python
-#   python_jedi         python_ty           r                   rego                ruby
-#   ruby_solargraph     rust                scala               scss                solidity
-#   swift               systemverilog       terraform           toml                typescript
-#   typescript_vts      vue                 yaml                zig
-#   (This list may be outdated. For the current list, see values of Language enum here:
-#   https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py
-#   For some languages, there are alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.)
+#   perl                php                 php_phpactor        php_phpantom        powershell
+#   python              python_jedi         python_pyrefly      python_ty           r
+#   rego                ruby                ruby_solargraph     rust                scala
+#   scss                solidity            svelte              swift               systemverilog
+#   terraform           toml                typescript          typescript_vts      vue
+#   yaml                zig
+#   (This list may be outdated; generated with scripts/print_language_list.py;
+#   For the current list, see values of Language enum here:
+#   https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py)
+# For some languages, there are alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.)
 # Note:
 #   - For C, use cpp
 #   - For JavaScript, use typescript
 #   - For Angular projects, use angular (subsumes typescript+html; requires `npm install` in the project root)
+#   - For Svelte projects, use svelte (subsumes typescript/javascript for .svelte projects; requires npm)
 #   - For SCSS / Sass / plain CSS, use scss (some-sass-language-server handles all three)
 #   - For Free Pascal/Lazarus, use pascal
 # Special requirements:
@@ -56,7 +59,7 @@ excluded_tools: []
 # initial prompt for the project. It will always be given to the LLM upon activating the project
 # (contrary to the memories, which are loaded on demand).
 initial_prompt: ""
-# the name by which the project can be referenced within Serena
+# the name by which the project can be referenced within Serena/when chatting with the LLM.
 project_name: "ai-plugins"
 
 # list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default).
@@ -119,8 +122,8 @@ ignored_memory_patterns: []
 
 # advanced configuration option allowing to configure language server-specific options.
 # Maps the language key to the options.
-# Have a look at the docstring of the constructors of the LS implementations within solidlsp (e.g., for C# or PHP) to see which options are available.
-# No documentation on options means no options are available.
+# The settings are considered only if the project is trusted (see global configuration to define trusted projects).
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#language-server-specific-settings
 ls_specific_settings: {}
 
 # list of mode names to be activated additionally for this project, e.g. ["query-projects"]
@@ -128,13 +131,38 @@ ls_specific_settings: {}
 # See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
 added_modes:
 
-# list of additional workspace folder paths for cross-package reference support (e.g. in monorepos).
+# list of additional workspace folder paths for cross-package reference support.
 # Paths can be absolute or relative to the project root.
 # Each folder is registered as an LSP workspace folder, enabling language servers to discover
-# symbols and references across package boundaries.
-# Currently supported for: TypeScript.
+# symbols and references across package boundaries, but these folders are not indexed by Serena,
+# i.e. the respective symbols will not be found using Serena's symbol search tools.
 # Example:
 #   additional_workspace_folders:
 #     - ../sibling-package
 #     - ../shared-lib
-additional_workspace_folders: []
+ls_additional_workspace_folders: []
+
+# list of workspace folder paths (LSP backend only).
+# These folders will be used to build up Serena's symbol index.
+# Paths must be within the project root and should thus be relative to the project root.
+# Furthermore, the paths should not be filtered by ignore settings.
+# Default setting: The entire project root folder (".") is considered.
+# In (large) monorepos, this can be used to index only subfolders of the project root, e.g.
+#   ls_workspace_folders:
+#     - "./subproject1"
+#     - "./subproject2"
+ls_workspace_folders:
+- .
+
+# optional shell command to run before the language backend (LSP or JetBrains) is initialised.
+# the command runs in the project root directory and is only executed if the project is trusted
+# (see trusted_project_path_patterns in the global configuration).
+# serena waits for the command to exit: a non-zero exit code is logged as an error but does not
+# abort activation. a per-project timeout (activation_command_timeout, default 180s) is the safety
+# backstop for non-terminating commands; on expiry the process is killed and activation continues.
+# example: activation_command: "npx nx run-many -t build"
+activation_command:
+
+# maximum time in seconds to wait for activation_command to complete before killing it (default 180s).
+# must be a positive number.
+activation_command_timeout: 180.0
diff --git a/.serena/serena_config.yml b/.serena/serena_config.yml
index 51c8bd3..3411fe6 100644
--- a/.serena/serena_config.yml
+++ b/.serena/serena_config.yml
@@ -34,16 +34,16 @@ web_dashboard: false
 # the address the web dashboard will listen on (bind address).
 web_dashboard_listen_address: 127.0.0.1
 
-# whether to open the Dashboard window/browser tab when Serena starts (provided that web_dashboard is enabled).
-# If set to false, you can still open the dashboard manually by clicking on the Serena icon in your system
-# tray on Windows and macOS. On Linux, there is no system tray support, so you can only open the dashboard by
-# a) telling the LLM to "open the dashboard" (provided that the open_dashboard tool is enabled) or by
-# b) manually navigating to http://localhost:24282/dashboard/ in your web browser (actual port
-#    may be higher if you have multiple instances running; try ports 24283, 24284, etc.)
-# See also: https://oraios.github.io/serena/02-usage/060_dashboard.html
+# whether to open the Dashboard window/browser tab when Serena starts (provided that `web_dashboard` is enabled).
+# If set to false, you can still open the dashboard manually:
+#  * When using an interface that supports a tray icon (see setting `web_dashboard_interface`),
+#    you can conveniently open the dashboard from the system tray.
+#  * When using the `browser` interface (no tray icon), so you can only open the dashboard by
+#    a) telling the LLM to "open the dashboard" (provided that the open_dashboard tool is enabled) or by
+#    b) manually navigating to http://localhost:24282/dashboard/ in your web browser (actual port
+#       may be higher if you have multiple instances running; try ports 24283, 24284, etc.)
+# Further information: https://oraios.github.io/serena/02-usage/060_dashboard.html
 web_dashboard_open_on_launch: true
-
-# address where JetBrains plugin servers are running (only relevant when using the JetBrains language backend)
 jetbrains_plugin_server_address: 127.0.0.1
 
 # the minimum log level for the GUI log window and the dashboard (10 = debug, 20 = info, 30 = warning, 40 = error)
@@ -72,25 +72,26 @@ included_optional_tools: []
 # This cannot be combined with non-empty excluded_tools or included_optional_tools.
 fixed_tools: []
 
-# list of mode names to that are always to be included in the set of active modes
-# The full set of modes to be activated is base_modes + default_modes.
-# If this is undefined, no base modes are included.
-# The project configuration (project.yml) may override this setting.
+# list of mode names to that are always to be included in the set of active modes.
+# The full set of modes to be activated is base_modes + default_modes + added_modes,
+# where added_modes can be defined by projects/CLI parameters.
+# If this is undefined/empty, no base modes are included.
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
 base_modes:
-
-# list of mode names that are to be activated by default.
-# The full set of modes to be activated is base_modes + default_modes.
-# These modes can be overridden by the project configuration (project.yml) or through the CLI (--mode).
 default_modes:
 - interactive
 - editing
+
+# Used as default for tools where the apply method has a default maximal answer length.
+# Even though the value of the max_answer_chars can be changed when calling the tool, it may make sense to adjust this default
+# through the global configuration.
 default_max_tool_answer_chars: 150000
 
 # the name of the token count estimator to use for tool usage statistics.
 # See the `RegisteredTokenCountEstimator` enum for available options.
 #
 # By default, a very naive character count estimator is used, which simply counts the number of characters.
-# You can configure this to TIKTOKEN_GPT4 to use a local tiktoken-based estimator for GPT-4 (will download tiktoken
+# You can configure this to TIKTOKEN_GPT4O to use a local tiktoken-based estimator for GPT-4o (will download tiktoken
 # data files on first run), or ANTHROPIC_CLAUDE_SONNET_4 which will use the (free of cost) Anthropic API to
 # estimate the token count using the Claude Sonnet 4 tokenizer.
 token_count_estimator: CHAR_COUNT
@@ -157,4 +158,40 @@ line_ending: native
 #      opening the dashboard in browser tabs when selected from the tray menu.
 #      This is EXPERIMENTAL. It is tested on Windows only. We will establish macOS support, but it is yet untested.
 #      On Linux, this cannot be universally supported, but it may work in some desktop environments.
+#      On NixOS, when using the package from flake.nix, both modern AppIndicator trays as well as
+#      older Xorg-/XEmbed-based trays should be supported.
+# See https://oraios.github.io/serena/02-usage/060_dashboard.html
 web_dashboard_interface:
+
+# trusted hosts used to access the web dashboard.
+# By default, only allow access via local addresses for security reasons.
+# If you want to allow access from remote machines, add the hostname used to access the dashboard to this list.
+# If the list is empty/undefined, all hosts are trusted.
+web_dashboard_trusted_hosts:
+- 127.0.0.1
+- localhost
+
+# command used to launch a JetBrains IDE on demand (only relevant when using the JetBrains language backend)
+# If this is non-empty and, at project activation, the Serena JetBrains Plugin server instance corresponding
+# to the project is not found, use this command to spawn a new instance.
+# Specifically, if this is <cmd>, then `<cmd> <projectDir>` is launched.
+# Provide the full path to the executable/script (e.g., "/usr/bin/idea" or "C:/Users/bob/AppData/Local/JetBrains/Toolbox/scripts/idea.cmd").
+jetbrains_launch_command:
+
+# list of glob patterns for project root directories that are considered trusted.
+# Some project settings will only be applied if the project is trusted.
+# A glob pattern can contain the following:
+#       *  matches any sequence of characters except path separators
+#      **  matches any sequence of characters including path separators
+#       ?  matches any single character except path separators
+#   [abc]  matches any single character in the set (here: a, b, or c)
+# Path separators are normalised internally, so on Windows, both / and \ can be used in the patterns.
+# Example:
+#   trusted_project_path_patterns:
+#     - /home/user/projects/**
+#     - C:\Users\Anna\Dev\work\**
+# The pattern "**" matches any project path, so it can be used to trust all projects.
+# NOTE: リポジトリにコミットする設定では信頼対象を空にしておく。
+# 任意の project.yml の trusted 限定設定（activation_command / ls_specific_settings 等）を
+# 無条件に受け入れないようにするため。信頼が必要な場合は各自のローカル設定で指定する。
+trusted_project_path_patterns: []
diff --git a/AGENTS.md b/AGENTS.md
index f56470f..d81e177 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -72,7 +72,7 @@ ai-plugins/
 
 ## NDFプラグインについて
 
-**NDFプラグイン**は、このマーケットプレイスの主要プラグインです（v4.19.0）。plugin 名は全ランタイムで `ndf` を維持し、配布物は `plugins/ndf-claude` / `plugins/ndf-codex` / `plugins/ndf-kiro` に分離しています。
+**NDFプラグイン**は、このマーケットプレイスの主要プラグインです（v4.20.0）。plugin 名は全ランタイムで `ndf` を維持し、配布物は `plugins/ndf-claude` / `plugins/ndf-codex` / `plugins/ndf-kiro` に分離しています。
 - 共通編集元は `plugins/ndf-shared/`
 - Claude Code版は 8個の専門サブエージェント、公開Skills、SessionStart/Stopフックを提供
 - Codex版は Codex向け公開Skillsと任意Slack通知hookを提供
diff --git a/README.md b/README.md
index 3a0d40c..2d254ea 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@ Claude Code / Codex / Kiro CLI向けのスキル・MCP設定を共有するた
 
 このマーケットプレイスは、チーム全体でAI開発ツール（Claude Code / Codex / Kiro CLI）の導入を加速するための事前設定されたプラグインを提供します。
 
-**NDFプラグイン v4.19.0** は、同じ `ndf@ai-plugins` という名前で Claude Code / Codex / Kiro CLI へ配布されるランタイム別プラグインです。共通ソースは `plugins/ndf-shared/` に集約し、利用者が install する配布物は `plugins/ndf-claude/` / `plugins/ndf-codex/` / `plugins/ndf-kiro/` に分かれています。
+**NDFプラグイン v4.20.0** は、同じ `ndf@ai-plugins` という名前で Claude Code / Codex / Kiro CLI へ配布されるランタイム別プラグインです。共通ソースは `plugins/ndf-shared/` に集約し、利用者が install する配布物は `plugins/ndf-claude/` / `plugins/ndf-codex/` / `plugins/ndf-kiro/` に分かれています。
 
 - **公開Skills**: Claude Code向け core 29個、Kiro向け core 28個、Codex向け core 30個に分離。
 - **元Skills（49個）**:
@@ -100,7 +100,14 @@ kiro-cli chat
 
 | プラグイン名 | バージョン | 説明 | 詳細 |
 |------------|----------|------|------|
-| **ndf** | 4.19.0 | Claude Code / Codex / Kiro CLI 向けに runtime 別配布物を提供する NDF プラグイン。8個の専門エージェント（Claude版）、公開Skills（Claude Code向け core 29個、Kiro向け core 28個、Codex向け core 30個）、Claude SessionStart/Stopフック、Codex/Kiro向け通知・実行補助を提供。v4.0.0 で Codex MCP サーバを廃止し、`/ndf:codex` skill + `corder` エージェント経由の CLI 直接実行に一本化。 | [Claude](./plugins/ndf-claude/README.md) / [Codex](./plugins/ndf-codex/README.md) / [Kiro](./plugins/ndf-kiro/README.md) |
+| **ndf** | 4.20.0 | Claude Code / Codex / Kiro CLI 向けに runtime 別配布物を提供する NDF プラグイン。8個の専門エージェント（Claude版）、公開Skills（Claude Code向け core 29個、Kiro向け core 28個、Codex向け core 30個）、Claude SessionStart/Stopフック、Codex/Kiro向け通知・実行補助を提供。v4.0.0 で Codex MCP サーバを廃止し、`/ndf:codex` skill + `corder` エージェント経由の CLI 直接実行に一本化。 | [Claude](./plugins/ndf-claude/README.md) / [Codex](./plugins/ndf-codex/README.md) / [Kiro](./plugins/ndf-kiro/README.md) |
+
+### NDF v4.20.0 の主な変更
+
+- `markdown-writing` skill を、体裁ルールから**第三者可読性のルール**へ拡張しました。適用対象に仕様書・PR 本文・調査レポート・レビューコメントを追加しています。
+- 説明文にテーブル名・カラム名などの内部識別子や、会話中に作ったローカル略語を持ち込まないルールを追加しました。「何のために」「何をやったか」の説明で識別子を使うと、書いた側は説明した気になり読み手には伝わらないためです。
+- 検討過程の痕跡（案A / Option A 等）と変更履歴（「以前は〜だったが変更した」）を本文に残さないルール、否定的な結論にエビデンスを必須とするルール、個人情報・認証情報を文書に含めないルールを追加しました。
+- 書き終えた後の grep セルフチェックとチェックリストを整備しました。
 
 ### NDF v4.19.0 の主な変更
 
diff --git a/issues/issue-33-cross-review-resume-open-threads.md b/issues/issue-33-cross-review-resume-open-threads.md
new file mode 100644
index 0000000..c5386bf
--- /dev/null
+++ b/issues/issue-33-cross-review-resume-open-threads.md
@@ -0,0 +1,88 @@
+# Issue 33: cross-review 再開時の未解決 thread 考慮
+
+## 関連リンク
+
+- GitHub Issue: https://github.com/devbasex/ai-plugins/issues/33
+- 関連 Skill: `plugins/ndf-shared/skills/cross-review/SKILL.md`
+
+## 概要
+
+`ndf:cross-review` の再開時に、前回中断ラウンドで残った未解決 review thread が `judge` の収束判定に考慮されない問題を修正する。
+
+最低限の対応として、再開時の既存 open thread と `comments_count` の意味をドキュメントに明記する。可能であれば `state.py` に open thread 検査を追加し、未解決 thread が残っている状態で即 approved に進まないガードを入れる。
+
+## 問題・背景
+
+再開ラウンドで codex / gemini が approve 相当を返すと、`state.py judge` は当該ラウンドの `result.json.intent` だけで `final=approved` にできる。前回中断前に投稿された未解決 thread はこの判定に含まれないため、Step 7.5 の最終スイープだけが取りこぼし防止になっている。
+
+また `result.json.comments_count` は「そのラウンドで新規投稿されたコメント数」であり、PR 上の実 open thread 総数ではない。fix / sweep の実行者がこの件数を実 open thread 数と誤解すると、再開・複数ラウンド累積時に取りこぼしが起きる。
+
+## 修正対象
+
+- `plugins/ndf-shared/skills/cross-review/SKILL.md`
+- `plugins/ndf-shared/skills/cross-review/docs/01-state-and-review.md`
+- `plugins/ndf-shared/skills/cross-review/docs/02-fix-and-rotation.md`
+- `plugins/ndf-shared/skills/cross-review/scripts/state.py`
+- `plugins/ndf-shared/skills/cross-review/tests/`
+- `plugins/ndf-claude/skills/cross-review/`
+- `plugins/ndf-codex/skills/cross-review/`
+- `plugins/ndf-kiro/skills/cross-review/`
+
+runtime 別配布物は `plugins/ndf-shared` を正とし、`scripts/build-runtime-plugins.sh` で同期する。
+
+## タスク分解
+
+### Task 1: 再開時 open thread の仕様を文書化
+
+- **対象ファイル:** `plugins/ndf-shared/skills/cross-review/docs/01-state-and-review.md`
+- **変更内容:** `state.py judge` は当該ラウンドの intent を見ること、再開前から存在する open thread は Step 7.5 sweep が回収責任を持つことを明記する。
+
+### Task 2: `comments_count` の意味を明記
+
+- **対象ファイル:** `plugins/ndf-shared/skills/cross-review/docs/01-state-and-review.md`, `plugins/ndf-shared/skills/cross-review/docs/02-fix-and-rotation.md`
+- **変更内容:** `comments_count` は投稿数であり、実 open thread 数ではないことを fix / sweep のプロンプト周辺に明記する。open thread は GraphQL の `reviewThreads` で洗い直す方針に統一する。
+
+### Task 3: 再開時 open thread ガードを検討・実装
+
+- **対象ファイル:** `plugins/ndf-shared/skills/cross-review/scripts/state.py`
+- **変更内容:** `init` 再開時または `judge` 前後で、PR 上の unresolved review thread 数を取得する helper を追加する。未解決 thread がある状態で即 approved になる場合は、次のどちらかを実装方針として選ぶ。
+  - `judge` は `open_thread_count > 0` の場合に continue を返し、fix / sweep 経由へ進める。
+  - `state.json` に `resumed_open_threads` を記録し、report / sweep に必須入力として渡す。
+
+実装範囲が過大になる場合は、Task 1 / Task 2 の docs 強化を先行し、script ガードは別 PR に分ける。
+
+### Task 4: テスト追加
+
+- **対象ファイル:** `plugins/ndf-shared/skills/cross-review/tests/`
+- **変更内容:** 再開 state と open thread count の扱いを unit test で固定する。GitHub API 呼び出し部分は subprocess / helper を mock し、ネットワーク不要で検証する。
+
+### Task 5: runtime 配布物同期
+
+- **対象ファイル:** `plugins/ndf-claude/`, `plugins/ndf-codex/`, `plugins/ndf-kiro/`
+- **変更内容:** `bash scripts/build-runtime-plugins.sh` を実行し、shared の変更を runtime 別配布物へ反映する。
+
+## PR 分割計画
+
+単一 PR で進める。主対象は cross-review skill 内の docs / state helper / tests であり、依存関係のある複数機能に分割するほどの変更ではない。
+
+| PR # | branch 名 | 概要 | 依存 | 並行可否 |
+|---|---|---|---|---|
+| 1 | `fix/issue-33-cross-review-resume-open-threads` | 再開時 open thread の仕様明記と必要な script guard / tests 追加 | なし | - |
+
+release branch: なし
+base branch: `main`
+
+## 影響範囲
+
+- `ndf:cross-review` の再開フロー
+- `state.py judge` の収束判定
+- Step 7.5 最終スイープの必須性に関する利用者理解
+- runtime 別 NDF plugin 配布物
+
+## テスト計画
+
+- [ ] `python3 plugins/ndf-shared/skills/cross-review/tests/...` または該当 pytest を実行する
+- [ ] `bash scripts/build-runtime-plugins.sh --check`
+- [ ] `bash scripts/validate-runtime-plugins.sh`
+- [ ] 再開 state の unit test で、open thread がある場合の期待挙動を確認する
+- [ ] Markdown link check が通ることを確認する
diff --git a/issues/issue-37-cross-review-reply-resolve-guard.md b/issues/issue-37-cross-review-reply-resolve-guard.md
new file mode 100644
index 0000000..27bc894
--- /dev/null
+++ b/issues/issue-37-cross-review-reply-resolve-guard.md
@@ -0,0 +1,99 @@
+# Issue 37: cross-review reply / resolve 漏れガード
+
+## 関連リンク
+
+- GitHub Issue: https://github.com/devbasex/ai-plugins/issues/37
+- 関連 Skill: `plugins/ndf-shared/skills/cross-review/SKILL.md`
+- 関連 Skill: `plugins/ndf-shared/skills/resolve-pr-comments/SKILL.md`
+- 関連 Skill: `plugins/ndf-shared/skills/fix/SKILL.md`
+
+## 概要
+
+`ndf:cross-review` の修正フェーズで、修正済み thread への reply 投稿、`resolveReviewThread`、PR レベル Summary コメント投稿が抜けたまま次 round や approve に進むことを防ぐ。
+
+あわせて `resolve-pr-comments` の返信 API 例を実行可能な形に修正し、reply 失敗が resolve 成功で隠れないようにする。
+
+## 問題・背景
+
+cross-review の Step 5 は `/ndf:fix` サブエージェントが reply + resolve + Summary コメントまで実行する契約になっている。しかしメインセッションが手動で修正・push して次 round に進めると、reply / resolve がスキップされても `state.py start-round` / `judge` / `merge-fix` 側で検知できず、未解決 inline thread が残る可能性がある。
+
+また `resolve-pr-comments/SKILL.md` の REST 返信例が `-f in_reply_to=<comment_id>` になっており、GitHub API では typed field の `-F in_reply_to=<comment_id>` を使う必要がある。reply 失敗後に GraphQL resolve だけ成功すると、thread は resolved でも「どの修正で対応したか」の inline reply が残らない。
+
+## 修正対象
+
+- `plugins/ndf-shared/skills/cross-review/SKILL.md`
+- `plugins/ndf-shared/skills/cross-review/docs/01-state-and-review.md`
+- `plugins/ndf-shared/skills/cross-review/docs/02-fix-and-rotation.md`
+- `plugins/ndf-shared/skills/cross-review/scripts/state.py`
+- `plugins/ndf-shared/skills/resolve-pr-comments/SKILL.md`
+- `plugins/ndf-shared/skills/fix/SKILL.md`
+- `plugins/ndf-shared/skills/cross-review/tests/`
+- `plugins/ndf-claude/`, `plugins/ndf-codex/`, `plugins/ndf-kiro/`
+
+runtime 別配布物は `plugins/ndf-shared` を正とし、`scripts/build-runtime-plugins.sh` で同期する。
+
+## タスク分解
+
+### Task 1: resolve-pr-comments の reply API 例を修正
+
+- **対象ファイル:** `plugins/ndf-shared/skills/resolve-pr-comments/SKILL.md`
+- **変更内容:** `gh api repos/:owner/:repo/pulls/$PR_NUMBER/comments -f body=... -f in_reply_to=...` を、`in_reply_to` が数値として送られる `-F in_reply_to=<comment_id>` へ修正する。必要なら GraphQL reply mutation の代替も併記する。
+
+### Task 2: reply + resolve + verify の小 script 方針を追加
+
+- **対象ファイル:** `plugins/ndf-shared/skills/resolve-pr-comments/SKILL.md`, 必要に応じて `plugins/ndf-shared/skills/resolve-pr-comments/scripts/`
+- **変更内容:** 対応済み thread に reply を投稿し、GraphQL `resolveReviewThread` を実行し、最後に unresolved count を確認する流れを標準化する。script を追加する場合は、reply 失敗時に resolve へ進まない `set -e` 相当の挙動にする。
+
+### Task 3: cross-review の次 round ガードを設計
+
+- **対象ファイル:** `plugins/ndf-shared/skills/cross-review/scripts/state.py`
+- **変更内容:** 前 round に `REQUEST_CHANGES` があり、対応する fix 結果または sweep 結果が無い状態で `start-round` / `judge` / `merge-fix` が進まないようにする。最低限、`merge-fix` で `resolved_threads`、`summary_comment_url`、fix result file の存在を検証する。
+
+### Task 4: final report 前の unresolved sweep 検証を必須化
+
+- **対象ファイル:** `plugins/ndf-shared/skills/cross-review/SKILL.md`, `plugins/ndf-shared/skills/cross-review/docs/02-fix-and-rotation.md`
+- **変更内容:** Step 7.5 の `sweep-pr<PR>-result.json` に `remaining_open=0` が必要であることを、report 前の必須検証として明記する。`remaining_open > 0` の場合は approved として完了報告しない。
+
+### Task 5: fix の戻り値契約を強化
+
+- **対象ファイル:** `plugins/ndf-shared/skills/fix/SKILL.md`, `plugins/ndf-shared/skills/cross-review/docs/02-fix-and-rotation.md`
+- **変更内容:** 修正済み thread は reply URL または comment id と resolve 結果を戻り値に含める契約にする。reply なし resolve を禁止し、deferred / rejected の扱いと区別する。
+
+### Task 6: テスト追加
+
+- **対象ファイル:** `plugins/ndf-shared/skills/cross-review/tests/`
+- **変更内容:** fix result が無い、`resolved_threads` が空、`summary_comment_url` が無い、unresolved count が残っている、などのケースで state guard が fail する unit test を追加する。
+
+### Task 7: runtime 配布物同期
+
+- **対象ファイル:** `plugins/ndf-claude/`, `plugins/ndf-codex/`, `plugins/ndf-kiro/`
+- **変更内容:** `bash scripts/build-runtime-plugins.sh` を実行し、shared の変更を runtime 別配布物へ反映する。
+
+## PR 分割計画
+
+原則は単一 PR で進める。ただし reply / resolve helper script を新設して state guard まで実装すると差分が大きくなるため、実装時に 2 PR へ分割してもよい。
+
+| PR # | branch 名 | 概要 | 依存 | 並行可否 |
+|---|---|---|---|---|
+| 1 | `fix/issue-37-resolve-pr-comments-reply-api` | reply API 例修正、resolve-pr-comments / fix 契約整理 | なし | ○ |
+| 2 | `fix/issue-37-cross-review-resolve-guard` | cross-review state guard、sweep 検証、tests 追加 | PR1 | × |
+
+release branch: 分割する場合のみ `release/issue-37-cross-review-reply-resolve-guard`
+base branch: `main`
+
+## 影響範囲
+
+- `ndf:cross-review` の round 進行条件
+- `/ndf:fix` の戻り値契約
+- `/ndf:resolve-pr-comments` の API 手順
+- PR 上の review thread 解決履歴
+- runtime 別 NDF plugin 配布物
+
+## テスト計画
+
+- [ ] `plugins/ndf-shared/skills/cross-review/tests/` の pytest を実行する
+- [ ] reply API 例が `-F in_reply_to=<comment_id>` になっていることを確認する
+- [ ] state guard の unit test で、reply / resolve / summary / unresolved count の不足を検出できることを確認する
+- [ ] `bash scripts/build-runtime-plugins.sh --check`
+- [ ] `bash scripts/validate-runtime-plugins.sh`
+- [ ] Markdown link check が通ることを確認する
diff --git a/plugins/ndf-claude/.claude-plugin/plugin.json b/plugins/ndf-claude/.claude-plugin/plugin.json
index 9cc4f39..435d514 100644
--- a/plugins/ndf-claude/.claude-plugin/plugin.json
+++ b/plugins/ndf-claude/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "ndf",
-  "version": "4.19.0",
+  "version": "4.20.0",
   "description": "Claude Code plugin with 8 specialized agents, focused NDF skills for PR/review workflows, implementation planning, debugging principles, statusline, browser smoke testing, Codex CLI delegation, transcript retention guard, default statusline setup, and optional Slack notifications.",
   "author": {
     "name": "takemi-ohama",
diff --git a/plugins/ndf-claude/skills/markdown-writing/01-diagram-guide.md b/plugins/ndf-claude/skills/markdown-writing/01-diagram-guide.md
index db40f52..ad9e8a4 100644
--- a/plugins/ndf-claude/skills/markdown-writing/01-diagram-guide.md
+++ b/plugins/ndf-claude/skills/markdown-writing/01-diagram-guide.md
@@ -2,6 +2,43 @@
 
 ## mermaid 記法
 
+### 横幅と文字サイズ
+
+mermaid は図の自然幅が本文幅を超えると、図全体を縮小して収める。文字も一緒に縮むため、横に長い図は文字が読めなくなる。縦に長い図は縮小されないので、文字サイズに影響しない。
+
+**横方向に並べる要素は3個まで。4個を超えないこと。**
+
+日本語ラベル（6文字程度）のノードは1個あたり約215px を消費する。本文幅と実効文字サイズの関係は以下（本文16px 基準の実測値）。
+
+| 横方向のノード数 | 図の自然幅 | GitHub（本文890px） | Notion（本文708px） |
+|---|---|---|---|
+| 3個 | 611px | 16px | 16px |
+| 4個 | 826px | 16px | 13.7px |
+| 5個 | 1041px | 13.7px | 10.9px |
+| 6個 | 1255px | 11.3px | 9.0px |
+| 7個 | 1470px | 9.7px | 7.7px |
+
+GitHub は5個から、Notion は4個から縮小が始まる。Notion に貼る前提の文書では**3個**を上限とする。
+
+縮小はノード数ではなく**幅**で決まるため、ラベルが長いほど早く限界が来る。`[Step1]` のような短いラベルなら1個あたり約152px で、GitHub なら6個まで等倍を保てる。
+
+超える場合の対処:
+
+| 対処 | 方法 |
+|------|------|
+| 向きを変える | `graph LR` をやめて `graph TD`（縦方向）にする。縦方向は何段あっても文字が縮まない |
+| ラベルを短くする | ノード幅はラベル文字数で決まる。`<br/>` で改行して幅を抑える |
+| 図を分割する | 1つの図に詰め込まず、関心事ごとに複数の図へ分ける |
+
+```mermaid
+graph TD
+    A[認証リクエスト<br/>受付] --> B{トークン<br/>有効?}
+    B -->|Yes| C[セッション作成]
+    B -->|No| D[401 を返す]
+```
+
+シーケンス図は participant 数が横幅を決め、1個あたり約200px を消費する。**GitHub で4個、Notion で3個**を上限とし、超えるならフェーズごとに図を分割する。
+
 ### フローチャート
 
 ```mermaid
@@ -49,39 +86,65 @@ erDiagram
     PRODUCT ||--o{ LINE_ITEM : "ordered in"
 ```
 
-## plantUML 記法
-
 ### コンポーネント図
 
-```plantuml
-@startuml
-package "Frontend" {
-    [React App]
-}
-package "Backend" {
-    [API Server]
-    [Database]
-}
-[React App] --> [API Server]
-[API Server] --> [Database]
-@enduml
+`subgraph` でグループを表現する。
+
+```mermaid
+graph LR
+    subgraph Frontend
+        R[React App]
+    end
+    subgraph Backend
+        A[API Server]
+        D[(Database)]
+    end
+    R --> A
+    A --> D
 ```
 
 ### アクティビティ図
 
-```plantuml
-@startuml
-start
-:ユーザー入力;
-if (有効?) then (yes)
-    :処理実行;
-else (no)
-    :エラー表示;
-endif
-stop
-@enduml
+```mermaid
+graph TD
+    S([開始]) --> I[ユーザー入力]
+    I --> V{有効?}
+    V -->|yes| P[処理実行]
+    V -->|no| E[エラー表示]
+    P --> G([終了])
+    E --> G
+```
+
+## その他の GitHub ネイティブ形式
+
+コードフェンスから直接レンダリングされる。図のソースが本文に残るのでレビューできる。
+
+### 数式（MathJax）
+
+ブロックは ` ```math ` または `$$…$$`、インラインは `$…$`。
+
+```math
+\sigma = \sqrt{\frac{1}{N}\sum_{i=1}^{N}(x_i - \mu)^2}
 ```
 
+### 地図
+
+` ```geojson ` / ` ```topojson ` でインタラクティブな地図になる。
+
+### 3Dモデル
+
+` ```stl ` に ASCII STL を書くと、回転・ズームできるビューアになる。
+
+## 使わないもの
+
+| | 理由 |
+|---|---|
+| plantUML | GitHub がレンダリングしない。外部レンダリングサーバの画像 URL に依存し、図のソースが差分に残らない |
+| HTML | GitHub 上ではソース表示になりレビューできない |
+| インライン `<svg>` | レンダラに除去され、図が消える |
+
+mermaid で表現しきれない自由レイアウトの図に限り、SVG をコミットして `<img src="./docs/diagram.svg">` で参照する。インラインでなくなるため、図と記述の乖離に気づけない点を承知の上で使う。
+
 ## ASCII 許可例（ツリーのみ）
 
 ディレクトリ構造はASCIIで表現可能:
@@ -138,7 +201,9 @@ docs/
 
 | DO | DON'T |
 |----|-------|
-| mermaid/plantUMLで図を描く | ASCII ARTで図を描く |
+| mermaid で図を描く | ASCII ARTで図を描く / plantUML を使う |
+| 横方向は3個まで（`graph TD` で縦に伸ばす） | 横に長い図にして文字を潰す |
+| 図はインラインで書く | 外部サービスの画像URLを貼る |
 | 300行以内に収める | 1000行超の巨大ファイル |
 | 順序prefixで分割 | prefixなしで分割 |
 | 2桁パディング（01-, 02-） | 1桁（1-, 2-） |
diff --git a/plugins/ndf-claude/skills/markdown-writing/SKILL.md b/plugins/ndf-claude/skills/markdown-writing/SKILL.md
index 56b3583..4b4d948 100644
--- a/plugins/ndf-claude/skills/markdown-writing/SKILL.md
+++ b/plugins/ndf-claude/skills/markdown-writing/SKILL.md
@@ -1,20 +1,113 @@
 ---
 name: markdown-writing
-description: "Write Markdown docs, diagrams, and split files."
-when_to_use: "Markdown 文書 / 図表を作成 / 編集するとき。Triggers: 'Markdown作成', 'ドキュメント作成', '文書作成', '図を描く', 'mermaid', 'create document', 'write docs'"
+description: "Write Markdown docs, PR bodies, and reports that read well to a third party."
+when_to_use: "Markdown 文書 / 仕様書 / 設計書 / PR 本文 / 調査レポート / 図表を作成・編集するとき。Triggers: 'Markdown作成', 'ドキュメント作成', '文書作成', '仕様書', '設計書', 'PR本文', 'PR説明', '調査レポート', '図を描く', 'mermaid', 'create document', 'write docs', 'write PR description'"
 allowed-tools:
   - Read
   - Write
   - Edit
+  - Grep
+  - Bash
 ---
 
 # Markdown Writing Skill
 
+読み手は**その場の会話・コードベース・検討過程を知らない第三者**（社外・レビュアー・将来の担当者）である、という前提で書く。
+
+適用対象: 仕様書 / 設計書 / README / OpenAPI 説明 / PR タイトル・本文 / コミットメッセージ / 調査レポート / 実装プラン / レビューコメント。
+
 ## 重要ルール
 
-### 1. 図表作成ルール
+### 1. 説明文に内部識別子・略語を持ち込まない
+
+**テーブル名・カラム名・クラス名などの内部識別子や、その場で作った略語を、説明文の主語・目的語に使わない。**
+
+「何のために」「何をやったか」を説明する文でこれらを使うと、読み手が識別子の意味を知っている前提になり、**書いた側は説明した気になり、読み手には何も伝わらない**。
+
+| | 例 |
+|---|---|
+| ❌ Bad | `user_subscriptions` の `plan_id` を更新し、us と sp を再生成する |
+| ✅ Good | 利用者の契約プランを変更し、請求明細を作り直す |
+| ❌ Bad | lcr がないと provisional に fallback する |
+| ✅ Good | 計算結果の控えが無い場合は、現在のマスタ値を参照する |
+
+**識別子を書いてよい場所**（むしろ書くべき）:
+
+- コードブロック・差分・スキーマ定義・SQL
+- 「どこを直したか」の指し示し（`app/Services/Foo.php:120` / 変更ファイル一覧）
+- 調査レポートのエビデンスブロック（クエリと実行結果）
+- 用語を導入する目的で、業務用語に括弧書きで添える場合
+
+**やること**:
+
+- 説明は業務用語・日本語で書き、識別子は必要なら括弧で添える（例: 「請求明細（`billing_details`）」）
+- 同じ文書で識別子を繰り返し使うなら、冒頭に**用語の対応表**を置き、本文は業務用語で通す
+- 略語は初出で正式名称を併記する。会話中に作ったローカル略称は文書に持ち込まない
+- プロジェクトに用語集（`terminology` skill、`docs/` の用語定義、UI ラベルの翻訳ファイル等）があれば、そこの表記に合わせる
+
+### 2. 検討過程の痕跡を残さない
+
+作成者とその場の相談相手（AI との対話含む）だけに通じるラベルや言い回しは、第三者には意味不明なので本文に書かない。
+
+- 検討時の選択肢ラベル（「案A / 案B」「Option A」「パターン1」などの符丁）
+- 「今回の相談で」「壁打ちの結果」「先ほど決めた」など会話由来の指示語
+- 不採用にした代替案との比較を、比較のためだけに残すこと
+
+**やること**: 決まった内容を、ラベルなしで断定形で書く。「なぜそうするか」は理由として本質的なものだけを一般的な言葉で残す。
+
+### 3. 変更履歴を本文に残さない
+
+指摘を受けて直した場合でも、**修正の経緯そのもの**を本文に含めない。
+
+- 「以前は X だったが、指摘を受けて Y に変更した」式の記述
+- 「〜という誤りがあったため修正」「レビュー対応で追加」などの由来説明
+- 却下された案の残骸
+
+**やること**: 現時点で正しい確定情報だけを書く。変更理由・経緯はコミットメッセージ / PR 説明 / レビュー返信に置く（git 履歴に残るので本文で二重に持たない）。
+
+- **stale 化防止**: 「以前は〜」式の履歴は、さらに変更が入ると二重に古くなる
+- **責務分離**: 「何が正か」は文書、「なぜ変えたか」は git / PR
+
+### 4. 否定的な結論にはエビデンスを添える
+
+「存在しない」「呼ばれていない」「データがない」「影響がない」といった**否定的な結論**は、読み手が最も検証しづらく、外れたときの被害が大きい。**必ず実行結果を根拠として添える。**
+
+| 主張 | 添えるエビデンス |
+|---|---|
+| カラム / テーブルが存在しない | スキーマ照会の実行結果 |
+| データが存在しない | 件数クエリの実行結果 |
+| どこからも呼ばれていない | 検索コマンドと結果（呼び出し元を辿った経路） |
+| 影響範囲がない | 洗い出した対象の一覧と、それぞれの判定 |
+
+やってはいけないこと:
+
+- コードを読んだだけで「無い」と断定する
+- エビデンスなしで残課題の優先度を下げる
+- 一部だけ見て「他にはない」と判断する
+
+確認しきれなかったことは、**「未確認・残リスク」として明示的に残す**。書かずに省くと「確認済み」と読まれる。
 
-**mermaid または plantUML を使用**（ASCII ART禁止、ツリー除く）
+### 5. 個人情報・機密情報を書かない
+
+文書・PR 本文・コミットメッセージ・添付ファイルに、実在の個人を特定できる情報や認証情報を含めない。コミットメッセージとマージ済み PR 本文は**後から消しにくく、履歴に残る**。
+
+- 氏名（フルネーム）/ 電話番号 / メールアドレス / 住所 / 生年月日
+- 個体を特定できる番号（車台番号、シリアル、口座番号など）
+- 認証情報・トークン・接続文字列
+- エクスポートしたままの実データ（CSV / XLSX / スクリーンショット）
+
+**やること**: 主キー・管理番号・記号（「対象A」「①」）で参照する。実データが必要なら社内アクセス制限のある場所に置き、文書には URL とサマリだけ書く。
+
+### 6. 図表作成ルール
+
+**図はインラインで書く。** GitHub がコードフェンスから直接レンダリングする形式だけを使う。図のソースが本文に残るため、差分でレビューでき、図と記述の乖離にも気づける。
+
+| 用途 | 書き方 |
+|---|---|
+| フロー / シーケンス / ER / 状態遷移 / クラス | ` ```mermaid ` |
+| 数式 | ` ```math ` または `$…$` / `$$…$$`（MathJax） |
+| 地図 | ` ```geojson ` / ` ```topojson ` |
+| 3Dモデル | ` ```stl `（ASCII STL） |
 
 ```mermaid
 graph TD
@@ -23,13 +116,40 @@ graph TD
     B -->|No| D[処理B]
 ```
 
-### 2. 文書の長さと分割ルール
+- 状態の対比（修正前 vs 後 / 期待 vs 実態 / 環境 A vs B）や定義の列挙は、図ではなく Markdown の**表**
+- **ディレクトリツリーは ASCII でよい**（`├──` / `└──` の罫線）。テキストのまま貼れて差分も追いやすく、図に置き換える利点がない
+- それ以外を ASCII ART で描かない
+
+```
+src/
+├── handlers/
+│   └── webhook.ts
+└── index.ts
+```
+
+**使わないもの**:
+
+- **HTML** — GitHub 上ではソース表示になりレビューできない
+- **plantUML** — GitHub はレンダリングしない。外部レンダリングサーバの画像 URL に依存することになり、図のソースが差分に残らない
+- **インライン `<svg>`** — レンダラに除去される
+
+mermaid で表現しきれない自由レイアウトの図がどうしても要る場合に限り、SVG をコミットして `<img src="./docs/diagram.svg">` で参照する。インラインではなくなるため、図と記述の乖離に気づけない点を承知の上で使う。
 
-| ページ数 | 対応 |
+### 7. 文書の長さと分割ルール
+
+| 行数 | 対応 |
 |---------|-----|
 | ~300行 | そのまま |
-| 301~600行 | 2ファイルに分割 |
-| 600行以上 | セクションごとに分割 |
+| 301~500行 | 内容によっては単一ファイルのままでよい（下記の判断基準） |
+| 501行以上 | セクションごとに分割 |
+
+300行を超えても、**分割すると読み手の理解が落ちる**場合は単一ファイルのままにする。
+
+- 通しで読んで初めて意味が通る一連の説明（手順書、設計の導出過程）
+- 分量の大半が表・コードブロックで、文章としての密度が低い
+- 相互参照が多く、分割すると行ったり来たりが増える
+
+逆に、独立して読める単位が明確にあるなら300行以下でも分割してよい。
 
 **分割時のファイル名**: 順序prefix（01-, 02-, ...）+ ケバブケース
 
@@ -40,19 +160,44 @@ docs/feature-guide/
 └── 03-usage.md
 ```
 
+## 書き終えたらセルフチェック
+
+**識別子と略語の混入**（説明文の中に裸で出ていないか。コードブロック内のヒットは無視してよい）:
+
+```bash
+grep -nE '[a-z]+_[a-z0-9_]{2,}' <対象ファイル>
+```
+
+**検討痕跡・変更履歴の混入**（プロジェクトやその場の符丁に応じて語を足す）:
+
+```bash
+grep -nE '案 ?[A-Z]|Option ?[A-Z]|パターン[0-9]|今回|壁打ち|以前は|当初は|に変更|指摘を受け|レビュー対応|誤りのため' <対象ファイル>
+```
+
+ヒットしたら、業務用語での説明・最終確定形の記述に置き換える。
+
 ## チェックリスト
 
-- [ ] 図表はmermaid/plantUML使用（ツリー除く）
-- [ ] ファイル長は300行以内（超える場合は分割）
+- [ ] 説明文がテーブル名 / カラム名 / ローカル略語ではなく業務用語で書かれている
+- [ ] 略語は初出で正式名称を併記している
+- [ ] 検討過程のラベル（案A / Option A 等）と会話由来の指示語が残っていない
+- [ ] 「以前は〜だったが変更した」式の経緯が本文に残っていない
+- [ ] 否定的な結論に実行結果のエビデンスが添えられている
+- [ ] 未確認事項が「残リスク」として明示されている
+- [ ] 個人情報・認証情報・実データが含まれていない
+- [ ] 図はインライン（mermaid / math / geojson / stl）で書いている（ディレクトリツリーはASCIIでよい）
+- [ ] plantUML / HTML / インライン`<svg>` を使っていない
+- [ ] ファイル長は300行以内（301~500行は内容次第で可、501行以上は分割）
 - [ ] 分割時は順序prefix使用（01-, 02-, ...）
 
 ## 詳細ガイド
 
 | ファイル | 内容 |
 |---------|------|
-| `01-diagram-guide.md` | mermaid/plantUML記法、よくある間違い |
+| `01-diagram-guide.md` | mermaid 記法、その他の GitHub ネイティブ形式、よくある間違い |
 
 ## 関連リソース
 
 - [Mermaid公式ドキュメント](https://mermaid.js.org/)
-- [PlantUML公式ドキュメント](https://plantuml.com/)
+- [GitHub: Creating diagrams](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams)
+- [GitHub: Writing mathematical expressions](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/writing-mathematical-expressions)
diff --git a/plugins/ndf-codex/.codex-plugin/plugin.json b/plugins/ndf-codex/.codex-plugin/plugin.json
index ddd954f..85c3e74 100644
--- a/plugins/ndf-codex/.codex-plugin/plugin.json
+++ b/plugins/ndf-codex/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "ndf",
-  "version": "4.19.0",
+  "version": "4.20.0",
   "description": "Codex plugin with focused NDF skills for PR/review workflows, cross-review, implementation planning, Playwright testing, Docker container access, GitHub operations, and optional Slack completion notifications.",
   "skills": "./skills/",
   "hooks": "./hooks/hooks.json"
diff --git a/plugins/ndf-codex/skills/markdown-writing/01-diagram-guide.md b/plugins/ndf-codex/skills/markdown-writing/01-diagram-guide.md
index db40f52..ad9e8a4 100644
--- a/plugins/ndf-codex/skills/markdown-writing/01-diagram-guide.md
+++ b/plugins/ndf-codex/skills/markdown-writing/01-diagram-guide.md
@@ -2,6 +2,43 @@
 
 ## mermaid 記法
 
+### 横幅と文字サイズ
+
+mermaid は図の自然幅が本文幅を超えると、図全体を縮小して収める。文字も一緒に縮むため、横に長い図は文字が読めなくなる。縦に長い図は縮小されないので、文字サイズに影響しない。
+
+**横方向に並べる要素は3個まで。4個を超えないこと。**
+
+日本語ラベル（6文字程度）のノードは1個あたり約215px を消費する。本文幅と実効文字サイズの関係は以下（本文16px 基準の実測値）。
+
+| 横方向のノード数 | 図の自然幅 | GitHub（本文890px） | Notion（本文708px） |
+|---|---|---|---|
+| 3個 | 611px | 16px | 16px |
+| 4個 | 826px | 16px | 13.7px |
+| 5個 | 1041px | 13.7px | 10.9px |
+| 6個 | 1255px | 11.3px | 9.0px |
+| 7個 | 1470px | 9.7px | 7.7px |
+
+GitHub は5個から、Notion は4個から縮小が始まる。Notion に貼る前提の文書では**3個**を上限とする。
+
+縮小はノード数ではなく**幅**で決まるため、ラベルが長いほど早く限界が来る。`[Step1]` のような短いラベルなら1個あたり約152px で、GitHub なら6個まで等倍を保てる。
+
+超える場合の対処:
+
+| 対処 | 方法 |
+|------|------|
+| 向きを変える | `graph LR` をやめて `graph TD`（縦方向）にする。縦方向は何段あっても文字が縮まない |
+| ラベルを短くする | ノード幅はラベル文字数で決まる。`<br/>` で改行して幅を抑える |
+| 図を分割する | 1つの図に詰め込まず、関心事ごとに複数の図へ分ける |
+
+```mermaid
+graph TD
+    A[認証リクエスト<br/>受付] --> B{トークン<br/>有効?}
+    B -->|Yes| C[セッション作成]
+    B -->|No| D[401 を返す]
+```
+
+シーケンス図は participant 数が横幅を決め、1個あたり約200px を消費する。**GitHub で4個、Notion で3個**を上限とし、超えるならフェーズごとに図を分割する。
+
 ### フローチャート
 
 ```mermaid
@@ -49,39 +86,65 @@ erDiagram
     PRODUCT ||--o{ LINE_ITEM : "ordered in"
 ```
 
-## plantUML 記法
-
 ### コンポーネント図
 
-```plantuml
-@startuml
-package "Frontend" {
-    [React App]
-}
-package "Backend" {
-    [API Server]
-    [Database]
-}
-[React App] --> [API Server]
-[API Server] --> [Database]
-@enduml
+`subgraph` でグループを表現する。
+
+```mermaid
+graph LR
+    subgraph Frontend
+        R[React App]
+    end
+    subgraph Backend
+        A[API Server]
+        D[(Database)]
+    end
+    R --> A
+    A --> D
 ```
 
 ### アクティビティ図
 
-```plantuml
-@startuml
-start
-:ユーザー入力;
-if (有効?) then (yes)
-    :処理実行;
-else (no)
-    :エラー表示;
-endif
-stop
-@enduml
+```mermaid
+graph TD
+    S([開始]) --> I[ユーザー入力]
+    I --> V{有効?}
+    V -->|yes| P[処理実行]
+    V -->|no| E[エラー表示]
+    P --> G([終了])
+    E --> G
+```
+
+## その他の GitHub ネイティブ形式
+
+コードフェンスから直接レンダリングされる。図のソースが本文に残るのでレビューできる。
+
+### 数式（MathJax）
+
+ブロックは ` ```math ` または `$$…$$`、インラインは `$…$`。
+
+```math
+\sigma = \sqrt{\frac{1}{N}\sum_{i=1}^{N}(x_i - \mu)^2}
 ```
 
+### 地図
+
+` ```geojson ` / ` ```topojson ` でインタラクティブな地図になる。
+
+### 3Dモデル
+
+` ```stl ` に ASCII STL を書くと、回転・ズームできるビューアになる。
+
+## 使わないもの
+
+| | 理由 |
+|---|---|
+| plantUML | GitHub がレンダリングしない。外部レンダリングサーバの画像 URL に依存し、図のソースが差分に残らない |
+| HTML | GitHub 上ではソース表示になりレビューできない |
+| インライン `<svg>` | レンダラに除去され、図が消える |
+
+mermaid で表現しきれない自由レイアウトの図に限り、SVG をコミットして `<img src="./docs/diagram.svg">` で参照する。インラインでなくなるため、図と記述の乖離に気づけない点を承知の上で使う。
+
 ## ASCII 許可例（ツリーのみ）
 
 ディレクトリ構造はASCIIで表現可能:
@@ -138,7 +201,9 @@ docs/
 
 | DO | DON'T |
 |----|-------|
-| mermaid/plantUMLで図を描く | ASCII ARTで図を描く |
+| mermaid で図を描く | ASCII ARTで図を描く / plantUML を使う |
+| 横方向は3個まで（`graph TD` で縦に伸ばす） | 横に長い図にして文字を潰す |
+| 図はインラインで書く | 外部サービスの画像URLを貼る |
 | 300行以内に収める | 1000行超の巨大ファイル |
 | 順序prefixで分割 | prefixなしで分割 |
 | 2桁パディング（01-, 02-） | 1桁（1-, 2-） |
diff --git a/plugins/ndf-codex/skills/markdown-writing/SKILL.md b/plugins/ndf-codex/skills/markdown-writing/SKILL.md
index 56b3583..4b4d948 100644
--- a/plugins/ndf-codex/skills/markdown-writing/SKILL.md
+++ b/plugins/ndf-codex/skills/markdown-writing/SKILL.md
@@ -1,20 +1,113 @@
 ---
 name: markdown-writing
-description: "Write Markdown docs, diagrams, and split files."
-when_to_use: "Markdown 文書 / 図表を作成 / 編集するとき。Triggers: 'Markdown作成', 'ドキュメント作成', '文書作成', '図を描く', 'mermaid', 'create document', 'write docs'"
+description: "Write Markdown docs, PR bodies, and reports that read well to a third party."
+when_to_use: "Markdown 文書 / 仕様書 / 設計書 / PR 本文 / 調査レポート / 図表を作成・編集するとき。Triggers: 'Markdown作成', 'ドキュメント作成', '文書作成', '仕様書', '設計書', 'PR本文', 'PR説明', '調査レポート', '図を描く', 'mermaid', 'create document', 'write docs', 'write PR description'"
 allowed-tools:
   - Read
   - Write
   - Edit
+  - Grep
+  - Bash
 ---
 
 # Markdown Writing Skill
 
+読み手は**その場の会話・コードベース・検討過程を知らない第三者**（社外・レビュアー・将来の担当者）である、という前提で書く。
+
+適用対象: 仕様書 / 設計書 / README / OpenAPI 説明 / PR タイトル・本文 / コミットメッセージ / 調査レポート / 実装プラン / レビューコメント。
+
 ## 重要ルール
 
-### 1. 図表作成ルール
+### 1. 説明文に内部識別子・略語を持ち込まない
+
+**テーブル名・カラム名・クラス名などの内部識別子や、その場で作った略語を、説明文の主語・目的語に使わない。**
+
+「何のために」「何をやったか」を説明する文でこれらを使うと、読み手が識別子の意味を知っている前提になり、**書いた側は説明した気になり、読み手には何も伝わらない**。
+
+| | 例 |
+|---|---|
+| ❌ Bad | `user_subscriptions` の `plan_id` を更新し、us と sp を再生成する |
+| ✅ Good | 利用者の契約プランを変更し、請求明細を作り直す |
+| ❌ Bad | lcr がないと provisional に fallback する |
+| ✅ Good | 計算結果の控えが無い場合は、現在のマスタ値を参照する |
+
+**識別子を書いてよい場所**（むしろ書くべき）:
+
+- コードブロック・差分・スキーマ定義・SQL
+- 「どこを直したか」の指し示し（`app/Services/Foo.php:120` / 変更ファイル一覧）
+- 調査レポートのエビデンスブロック（クエリと実行結果）
+- 用語を導入する目的で、業務用語に括弧書きで添える場合
+
+**やること**:
+
+- 説明は業務用語・日本語で書き、識別子は必要なら括弧で添える（例: 「請求明細（`billing_details`）」）
+- 同じ文書で識別子を繰り返し使うなら、冒頭に**用語の対応表**を置き、本文は業務用語で通す
+- 略語は初出で正式名称を併記する。会話中に作ったローカル略称は文書に持ち込まない
+- プロジェクトに用語集（`terminology` skill、`docs/` の用語定義、UI ラベルの翻訳ファイル等）があれば、そこの表記に合わせる
+
+### 2. 検討過程の痕跡を残さない
+
+作成者とその場の相談相手（AI との対話含む）だけに通じるラベルや言い回しは、第三者には意味不明なので本文に書かない。
+
+- 検討時の選択肢ラベル（「案A / 案B」「Option A」「パターン1」などの符丁）
+- 「今回の相談で」「壁打ちの結果」「先ほど決めた」など会話由来の指示語
+- 不採用にした代替案との比較を、比較のためだけに残すこと
+
+**やること**: 決まった内容を、ラベルなしで断定形で書く。「なぜそうするか」は理由として本質的なものだけを一般的な言葉で残す。
+
+### 3. 変更履歴を本文に残さない
+
+指摘を受けて直した場合でも、**修正の経緯そのもの**を本文に含めない。
+
+- 「以前は X だったが、指摘を受けて Y に変更した」式の記述
+- 「〜という誤りがあったため修正」「レビュー対応で追加」などの由来説明
+- 却下された案の残骸
+
+**やること**: 現時点で正しい確定情報だけを書く。変更理由・経緯はコミットメッセージ / PR 説明 / レビュー返信に置く（git 履歴に残るので本文で二重に持たない）。
+
+- **stale 化防止**: 「以前は〜」式の履歴は、さらに変更が入ると二重に古くなる
+- **責務分離**: 「何が正か」は文書、「なぜ変えたか」は git / PR
+
+### 4. 否定的な結論にはエビデンスを添える
+
+「存在しない」「呼ばれていない」「データがない」「影響がない」といった**否定的な結論**は、読み手が最も検証しづらく、外れたときの被害が大きい。**必ず実行結果を根拠として添える。**
+
+| 主張 | 添えるエビデンス |
+|---|---|
+| カラム / テーブルが存在しない | スキーマ照会の実行結果 |
+| データが存在しない | 件数クエリの実行結果 |
+| どこからも呼ばれていない | 検索コマンドと結果（呼び出し元を辿った経路） |
+| 影響範囲がない | 洗い出した対象の一覧と、それぞれの判定 |
+
+やってはいけないこと:
+
+- コードを読んだだけで「無い」と断定する
+- エビデンスなしで残課題の優先度を下げる
+- 一部だけ見て「他にはない」と判断する
+
+確認しきれなかったことは、**「未確認・残リスク」として明示的に残す**。書かずに省くと「確認済み」と読まれる。
 
-**mermaid または plantUML を使用**（ASCII ART禁止、ツリー除く）
+### 5. 個人情報・機密情報を書かない
+
+文書・PR 本文・コミットメッセージ・添付ファイルに、実在の個人を特定できる情報や認証情報を含めない。コミットメッセージとマージ済み PR 本文は**後から消しにくく、履歴に残る**。
+
+- 氏名（フルネーム）/ 電話番号 / メールアドレス / 住所 / 生年月日
+- 個体を特定できる番号（車台番号、シリアル、口座番号など）
+- 認証情報・トークン・接続文字列
+- エクスポートしたままの実データ（CSV / XLSX / スクリーンショット）
+
+**やること**: 主キー・管理番号・記号（「対象A」「①」）で参照する。実データが必要なら社内アクセス制限のある場所に置き、文書には URL とサマリだけ書く。
+
+### 6. 図表作成ルール
+
+**図はインラインで書く。** GitHub がコードフェンスから直接レンダリングする形式だけを使う。図のソースが本文に残るため、差分でレビューでき、図と記述の乖離にも気づける。
+
+| 用途 | 書き方 |
+|---|---|
+| フロー / シーケンス / ER / 状態遷移 / クラス | ` ```mermaid ` |
+| 数式 | ` ```math ` または `$…$` / `$$…$$`（MathJax） |
+| 地図 | ` ```geojson ` / ` ```topojson ` |
+| 3Dモデル | ` ```stl `（ASCII STL） |
 
 ```mermaid
 graph TD
@@ -23,13 +116,40 @@ graph TD
     B -->|No| D[処理B]
 ```
 
-### 2. 文書の長さと分割ルール
+- 状態の対比（修正前 vs 後 / 期待 vs 実態 / 環境 A vs B）や定義の列挙は、図ではなく Markdown の**表**
+- **ディレクトリツリーは ASCII でよい**（`├──` / `└──` の罫線）。テキストのまま貼れて差分も追いやすく、図に置き換える利点がない
+- それ以外を ASCII ART で描かない
+
+```
+src/
+├── handlers/
+│   └── webhook.ts
+└── index.ts
+```
+
+**使わないもの**:
+
+- **HTML** — GitHub 上ではソース表示になりレビューできない
+- **plantUML** — GitHub はレンダリングしない。外部レンダリングサーバの画像 URL に依存することになり、図のソースが差分に残らない
+- **インライン `<svg>`** — レンダラに除去される
+
+mermaid で表現しきれない自由レイアウトの図がどうしても要る場合に限り、SVG をコミットして `<img src="./docs/diagram.svg">` で参照する。インラインではなくなるため、図と記述の乖離に気づけない点を承知の上で使う。
 
-| ページ数 | 対応 |
+### 7. 文書の長さと分割ルール
+
+| 行数 | 対応 |
 |---------|-----|
 | ~300行 | そのまま |
-| 301~600行 | 2ファイルに分割 |
-| 600行以上 | セクションごとに分割 |
+| 301~500行 | 内容によっては単一ファイルのままでよい（下記の判断基準） |
+| 501行以上 | セクションごとに分割 |
+
+300行を超えても、**分割すると読み手の理解が落ちる**場合は単一ファイルのままにする。
+
+- 通しで読んで初めて意味が通る一連の説明（手順書、設計の導出過程）
+- 分量の大半が表・コードブロックで、文章としての密度が低い
+- 相互参照が多く、分割すると行ったり来たりが増える
+
+逆に、独立して読める単位が明確にあるなら300行以下でも分割してよい。
 
 **分割時のファイル名**: 順序prefix（01-, 02-, ...）+ ケバブケース
 
@@ -40,19 +160,44 @@ docs/feature-guide/
 └── 03-usage.md
 ```
 
+## 書き終えたらセルフチェック
+
+**識別子と略語の混入**（説明文の中に裸で出ていないか。コードブロック内のヒットは無視してよい）:
+
+```bash
+grep -nE '[a-z]+_[a-z0-9_]{2,}' <対象ファイル>
+```
+
+**検討痕跡・変更履歴の混入**（プロジェクトやその場の符丁に応じて語を足す）:
+
+```bash
+grep -nE '案 ?[A-Z]|Option ?[A-Z]|パターン[0-9]|今回|壁打ち|以前は|当初は|に変更|指摘を受け|レビュー対応|誤りのため' <対象ファイル>
+```
+
+ヒットしたら、業務用語での説明・最終確定形の記述に置き換える。
+
 ## チェックリスト
 
-- [ ] 図表はmermaid/plantUML使用（ツリー除く）
-- [ ] ファイル長は300行以内（超える場合は分割）
+- [ ] 説明文がテーブル名 / カラム名 / ローカル略語ではなく業務用語で書かれている
+- [ ] 略語は初出で正式名称を併記している
+- [ ] 検討過程のラベル（案A / Option A 等）と会話由来の指示語が残っていない
+- [ ] 「以前は〜だったが変更した」式の経緯が本文に残っていない
+- [ ] 否定的な結論に実行結果のエビデンスが添えられている
+- [ ] 未確認事項が「残リスク」として明示されている
+- [ ] 個人情報・認証情報・実データが含まれていない
+- [ ] 図はインライン（mermaid / math / geojson / stl）で書いている（ディレクトリツリーはASCIIでよい）
+- [ ] plantUML / HTML / インライン`<svg>` を使っていない
+- [ ] ファイル長は300行以内（301~500行は内容次第で可、501行以上は分割）
 - [ ] 分割時は順序prefix使用（01-, 02-, ...）
 
 ## 詳細ガイド
 
 | ファイル | 内容 |
 |---------|------|
-| `01-diagram-guide.md` | mermaid/plantUML記法、よくある間違い |
+| `01-diagram-guide.md` | mermaid 記法、その他の GitHub ネイティブ形式、よくある間違い |
 
 ## 関連リソース
 
 - [Mermaid公式ドキュメント](https://mermaid.js.org/)
-- [PlantUML公式ドキュメント](https://plantuml.com/)
+- [GitHub: Creating diagrams](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams)
+- [GitHub: Writing mathematical expressions](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/writing-mathematical-expressions)
diff --git a/plugins/ndf-kiro/skills/markdown-writing/01-diagram-guide.md b/plugins/ndf-kiro/skills/markdown-writing/01-diagram-guide.md
index db40f52..ad9e8a4 100644
--- a/plugins/ndf-kiro/skills/markdown-writing/01-diagram-guide.md
+++ b/plugins/ndf-kiro/skills/markdown-writing/01-diagram-guide.md
@@ -2,6 +2,43 @@
 
 ## mermaid 記法
 
+### 横幅と文字サイズ
+
+mermaid は図の自然幅が本文幅を超えると、図全体を縮小して収める。文字も一緒に縮むため、横に長い図は文字が読めなくなる。縦に長い図は縮小されないので、文字サイズに影響しない。
+
+**横方向に並べる要素は3個まで。4個を超えないこと。**
+
+日本語ラベル（6文字程度）のノードは1個あたり約215px を消費する。本文幅と実効文字サイズの関係は以下（本文16px 基準の実測値）。
+
+| 横方向のノード数 | 図の自然幅 | GitHub（本文890px） | Notion（本文708px） |
+|---|---|---|---|
+| 3個 | 611px | 16px | 16px |
+| 4個 | 826px | 16px | 13.7px |
+| 5個 | 1041px | 13.7px | 10.9px |
+| 6個 | 1255px | 11.3px | 9.0px |
+| 7個 | 1470px | 9.7px | 7.7px |
+
+GitHub は5個から、Notion は4個から縮小が始まる。Notion に貼る前提の文書では**3個**を上限とする。
+
+縮小はノード数ではなく**幅**で決まるため、ラベルが長いほど早く限界が来る。`[Step1]` のような短いラベルなら1個あたり約152px で、GitHub なら6個まで等倍を保てる。
+
+超える場合の対処:
+
+| 対処 | 方法 |
+|------|------|
+| 向きを変える | `graph LR` をやめて `graph TD`（縦方向）にする。縦方向は何段あっても文字が縮まない |
+| ラベルを短くする | ノード幅はラベル文字数で決まる。`<br/>` で改行して幅を抑える |
+| 図を分割する | 1つの図に詰め込まず、関心事ごとに複数の図へ分ける |
+
+```mermaid
+graph TD
+    A[認証リクエスト<br/>受付] --> B{トークン<br/>有効?}
+    B -->|Yes| C[セッション作成]
+    B -->|No| D[401 を返す]
+```
+
+シーケンス図は participant 数が横幅を決め、1個あたり約200px を消費する。**GitHub で4個、Notion で3個**を上限とし、超えるならフェーズごとに図を分割する。
+
 ### フローチャート
 
 ```mermaid
@@ -49,39 +86,65 @@ erDiagram
     PRODUCT ||--o{ LINE_ITEM : "ordered in"
 ```
 
-## plantUML 記法
-
 ### コンポーネント図
 
-```plantuml
-@startuml
-package "Frontend" {
-    [React App]
-}
-package "Backend" {
-    [API Server]
-    [Database]
-}
-[React App] --> [API Server]
-[API Server] --> [Database]
-@enduml
+`subgraph` でグループを表現する。
+
+```mermaid
+graph LR
+    subgraph Frontend
+        R[React App]
+    end
+    subgraph Backend
+        A[API Server]
+        D[(Database)]
+    end
+    R --> A
+    A --> D
 ```
 
 ### アクティビティ図
 
-```plantuml
-@startuml
-start
-:ユーザー入力;
-if (有効?) then (yes)
-    :処理実行;
-else (no)
-    :エラー表示;
-endif
-stop
-@enduml
+```mermaid
+graph TD
+    S([開始]) --> I[ユーザー入力]
+    I --> V{有効?}
+    V -->|yes| P[処理実行]
+    V -->|no| E[エラー表示]
+    P --> G([終了])
+    E --> G
+```
+
+## その他の GitHub ネイティブ形式
+
+コードフェンスから直接レンダリングされる。図のソースが本文に残るのでレビューできる。
+
+### 数式（MathJax）
+
+ブロックは ` ```math ` または `$$…$$`、インラインは `$…$`。
+
+```math
+\sigma = \sqrt{\frac{1}{N}\sum_{i=1}^{N}(x_i - \mu)^2}
 ```
 
+### 地図
+
+` ```geojson ` / ` ```topojson ` でインタラクティブな地図になる。
+
+### 3Dモデル
+
+` ```stl ` に ASCII STL を書くと、回転・ズームできるビューアになる。
+
+## 使わないもの
+
+| | 理由 |
+|---|---|
+| plantUML | GitHub がレンダリングしない。外部レンダリングサーバの画像 URL に依存し、図のソースが差分に残らない |
+| HTML | GitHub 上ではソース表示になりレビューできない |
+| インライン `<svg>` | レンダラに除去され、図が消える |
+
+mermaid で表現しきれない自由レイアウトの図に限り、SVG をコミットして `<img src="./docs/diagram.svg">` で参照する。インラインでなくなるため、図と記述の乖離に気づけない点を承知の上で使う。
+
 ## ASCII 許可例（ツリーのみ）
 
 ディレクトリ構造はASCIIで表現可能:
@@ -138,7 +201,9 @@ docs/
 
 | DO | DON'T |
 |----|-------|
-| mermaid/plantUMLで図を描く | ASCII ARTで図を描く |
+| mermaid で図を描く | ASCII ARTで図を描く / plantUML を使う |
+| 横方向は3個まで（`graph TD` で縦に伸ばす） | 横に長い図にして文字を潰す |
+| 図はインラインで書く | 外部サービスの画像URLを貼る |
 | 300行以内に収める | 1000行超の巨大ファイル |
 | 順序prefixで分割 | prefixなしで分割 |
 | 2桁パディング（01-, 02-） | 1桁（1-, 2-） |
diff --git a/plugins/ndf-kiro/skills/markdown-writing/SKILL.md b/plugins/ndf-kiro/skills/markdown-writing/SKILL.md
index 56b3583..4b4d948 100644
--- a/plugins/ndf-kiro/skills/markdown-writing/SKILL.md
+++ b/plugins/ndf-kiro/skills/markdown-writing/SKILL.md
@@ -1,20 +1,113 @@
 ---
 name: markdown-writing
-description: "Write Markdown docs, diagrams, and split files."
-when_to_use: "Markdown 文書 / 図表を作成 / 編集するとき。Triggers: 'Markdown作成', 'ドキュメント作成', '文書作成', '図を描く', 'mermaid', 'create document', 'write docs'"
+description: "Write Markdown docs, PR bodies, and reports that read well to a third party."
+when_to_use: "Markdown 文書 / 仕様書 / 設計書 / PR 本文 / 調査レポート / 図表を作成・編集するとき。Triggers: 'Markdown作成', 'ドキュメント作成', '文書作成', '仕様書', '設計書', 'PR本文', 'PR説明', '調査レポート', '図を描く', 'mermaid', 'create document', 'write docs', 'write PR description'"
 allowed-tools:
   - Read
   - Write
   - Edit
+  - Grep
+  - Bash
 ---
 
 # Markdown Writing Skill
 
+読み手は**その場の会話・コードベース・検討過程を知らない第三者**（社外・レビュアー・将来の担当者）である、という前提で書く。
+
+適用対象: 仕様書 / 設計書 / README / OpenAPI 説明 / PR タイトル・本文 / コミットメッセージ / 調査レポート / 実装プラン / レビューコメント。
+
 ## 重要ルール
 
-### 1. 図表作成ルール
+### 1. 説明文に内部識別子・略語を持ち込まない
+
+**テーブル名・カラム名・クラス名などの内部識別子や、その場で作った略語を、説明文の主語・目的語に使わない。**
+
+「何のために」「何をやったか」を説明する文でこれらを使うと、読み手が識別子の意味を知っている前提になり、**書いた側は説明した気になり、読み手には何も伝わらない**。
+
+| | 例 |
+|---|---|
+| ❌ Bad | `user_subscriptions` の `plan_id` を更新し、us と sp を再生成する |
+| ✅ Good | 利用者の契約プランを変更し、請求明細を作り直す |
+| ❌ Bad | lcr がないと provisional に fallback する |
+| ✅ Good | 計算結果の控えが無い場合は、現在のマスタ値を参照する |
+
+**識別子を書いてよい場所**（むしろ書くべき）:
+
+- コードブロック・差分・スキーマ定義・SQL
+- 「どこを直したか」の指し示し（`app/Services/Foo.php:120` / 変更ファイル一覧）
+- 調査レポートのエビデンスブロック（クエリと実行結果）
+- 用語を導入する目的で、業務用語に括弧書きで添える場合
+
+**やること**:
+
+- 説明は業務用語・日本語で書き、識別子は必要なら括弧で添える（例: 「請求明細（`billing_details`）」）
+- 同じ文書で識別子を繰り返し使うなら、冒頭に**用語の対応表**を置き、本文は業務用語で通す
+- 略語は初出で正式名称を併記する。会話中に作ったローカル略称は文書に持ち込まない
+- プロジェクトに用語集（`terminology` skill、`docs/` の用語定義、UI ラベルの翻訳ファイル等）があれば、そこの表記に合わせる
+
+### 2. 検討過程の痕跡を残さない
+
+作成者とその場の相談相手（AI との対話含む）だけに通じるラベルや言い回しは、第三者には意味不明なので本文に書かない。
+
+- 検討時の選択肢ラベル（「案A / 案B」「Option A」「パターン1」などの符丁）
+- 「今回の相談で」「壁打ちの結果」「先ほど決めた」など会話由来の指示語
+- 不採用にした代替案との比較を、比較のためだけに残すこと
+
+**やること**: 決まった内容を、ラベルなしで断定形で書く。「なぜそうするか」は理由として本質的なものだけを一般的な言葉で残す。
+
+### 3. 変更履歴を本文に残さない
+
+指摘を受けて直した場合でも、**修正の経緯そのもの**を本文に含めない。
+
+- 「以前は X だったが、指摘を受けて Y に変更した」式の記述
+- 「〜という誤りがあったため修正」「レビュー対応で追加」などの由来説明
+- 却下された案の残骸
+
+**やること**: 現時点で正しい確定情報だけを書く。変更理由・経緯はコミットメッセージ / PR 説明 / レビュー返信に置く（git 履歴に残るので本文で二重に持たない）。
+
+- **stale 化防止**: 「以前は〜」式の履歴は、さらに変更が入ると二重に古くなる
+- **責務分離**: 「何が正か」は文書、「なぜ変えたか」は git / PR
+
+### 4. 否定的な結論にはエビデンスを添える
+
+「存在しない」「呼ばれていない」「データがない」「影響がない」といった**否定的な結論**は、読み手が最も検証しづらく、外れたときの被害が大きい。**必ず実行結果を根拠として添える。**
+
+| 主張 | 添えるエビデンス |
+|---|---|
+| カラム / テーブルが存在しない | スキーマ照会の実行結果 |
+| データが存在しない | 件数クエリの実行結果 |
+| どこからも呼ばれていない | 検索コマンドと結果（呼び出し元を辿った経路） |
+| 影響範囲がない | 洗い出した対象の一覧と、それぞれの判定 |
+
+やってはいけないこと:
+
+- コードを読んだだけで「無い」と断定する
+- エビデンスなしで残課題の優先度を下げる
+- 一部だけ見て「他にはない」と判断する
+
+確認しきれなかったことは、**「未確認・残リスク」として明示的に残す**。書かずに省くと「確認済み」と読まれる。
 
-**mermaid または plantUML を使用**（ASCII ART禁止、ツリー除く）
+### 5. 個人情報・機密情報を書かない
+
+文書・PR 本文・コミットメッセージ・添付ファイルに、実在の個人を特定できる情報や認証情報を含めない。コミットメッセージとマージ済み PR 本文は**後から消しにくく、履歴に残る**。
+
+- 氏名（フルネーム）/ 電話番号 / メールアドレス / 住所 / 生年月日
+- 個体を特定できる番号（車台番号、シリアル、口座番号など）
+- 認証情報・トークン・接続文字列
+- エクスポートしたままの実データ（CSV / XLSX / スクリーンショット）
+
+**やること**: 主キー・管理番号・記号（「対象A」「①」）で参照する。実データが必要なら社内アクセス制限のある場所に置き、文書には URL とサマリだけ書く。
+
+### 6. 図表作成ルール
+
+**図はインラインで書く。** GitHub がコードフェンスから直接レンダリングする形式だけを使う。図のソースが本文に残るため、差分でレビューでき、図と記述の乖離にも気づける。
+
+| 用途 | 書き方 |
+|---|---|
+| フロー / シーケンス / ER / 状態遷移 / クラス | ` ```mermaid ` |
+| 数式 | ` ```math ` または `$…$` / `$$…$$`（MathJax） |
+| 地図 | ` ```geojson ` / ` ```topojson ` |
+| 3Dモデル | ` ```stl `（ASCII STL） |
 
 ```mermaid
 graph TD
@@ -23,13 +116,40 @@ graph TD
     B -->|No| D[処理B]
 ```
 
-### 2. 文書の長さと分割ルール
+- 状態の対比（修正前 vs 後 / 期待 vs 実態 / 環境 A vs B）や定義の列挙は、図ではなく Markdown の**表**
+- **ディレクトリツリーは ASCII でよい**（`├──` / `└──` の罫線）。テキストのまま貼れて差分も追いやすく、図に置き換える利点がない
+- それ以外を ASCII ART で描かない
+
+```
+src/
+├── handlers/
+│   └── webhook.ts
+└── index.ts
+```
+
+**使わないもの**:
+
+- **HTML** — GitHub 上ではソース表示になりレビューできない
+- **plantUML** — GitHub はレンダリングしない。外部レンダリングサーバの画像 URL に依存することになり、図のソースが差分に残らない
+- **インライン `<svg>`** — レンダラに除去される
+
+mermaid で表現しきれない自由レイアウトの図がどうしても要る場合に限り、SVG をコミットして `<img src="./docs/diagram.svg">` で参照する。インラインではなくなるため、図と記述の乖離に気づけない点を承知の上で使う。
 
-| ページ数 | 対応 |
+### 7. 文書の長さと分割ルール
+
+| 行数 | 対応 |
 |---------|-----|
 | ~300行 | そのまま |
-| 301~600行 | 2ファイルに分割 |
-| 600行以上 | セクションごとに分割 |
+| 301~500行 | 内容によっては単一ファイルのままでよい（下記の判断基準） |
+| 501行以上 | セクションごとに分割 |
+
+300行を超えても、**分割すると読み手の理解が落ちる**場合は単一ファイルのままにする。
+
+- 通しで読んで初めて意味が通る一連の説明（手順書、設計の導出過程）
+- 分量の大半が表・コードブロックで、文章としての密度が低い
+- 相互参照が多く、分割すると行ったり来たりが増える
+
+逆に、独立して読める単位が明確にあるなら300行以下でも分割してよい。
 
 **分割時のファイル名**: 順序prefix（01-, 02-, ...）+ ケバブケース
 
@@ -40,19 +160,44 @@ docs/feature-guide/
 └── 03-usage.md
 ```
 
+## 書き終えたらセルフチェック
+
+**識別子と略語の混入**（説明文の中に裸で出ていないか。コードブロック内のヒットは無視してよい）:
+
+```bash
+grep -nE '[a-z]+_[a-z0-9_]{2,}' <対象ファイル>
+```
+
+**検討痕跡・変更履歴の混入**（プロジェクトやその場の符丁に応じて語を足す）:
+
+```bash
+grep -nE '案 ?[A-Z]|Option ?[A-Z]|パターン[0-9]|今回|壁打ち|以前は|当初は|に変更|指摘を受け|レビュー対応|誤りのため' <対象ファイル>
+```
+
+ヒットしたら、業務用語での説明・最終確定形の記述に置き換える。
+
 ## チェックリスト
 
-- [ ] 図表はmermaid/plantUML使用（ツリー除く）
-- [ ] ファイル長は300行以内（超える場合は分割）
+- [ ] 説明文がテーブル名 / カラム名 / ローカル略語ではなく業務用語で書かれている
+- [ ] 略語は初出で正式名称を併記している
+- [ ] 検討過程のラベル（案A / Option A 等）と会話由来の指示語が残っていない
+- [ ] 「以前は〜だったが変更した」式の経緯が本文に残っていない
+- [ ] 否定的な結論に実行結果のエビデンスが添えられている
+- [ ] 未確認事項が「残リスク」として明示されている
+- [ ] 個人情報・認証情報・実データが含まれていない
+- [ ] 図はインライン（mermaid / math / geojson / stl）で書いている（ディレクトリツリーはASCIIでよい）
+- [ ] plantUML / HTML / インライン`<svg>` を使っていない
+- [ ] ファイル長は300行以内（301~500行は内容次第で可、501行以上は分割）
 - [ ] 分割時は順序prefix使用（01-, 02-, ...）
 
 ## 詳細ガイド
 
 | ファイル | 内容 |
 |---------|------|
-| `01-diagram-guide.md` | mermaid/plantUML記法、よくある間違い |
+| `01-diagram-guide.md` | mermaid 記法、その他の GitHub ネイティブ形式、よくある間違い |
 
 ## 関連リソース
 
 - [Mermaid公式ドキュメント](https://mermaid.js.org/)
-- [PlantUML公式ドキュメント](https://plantuml.com/)
+- [GitHub: Creating diagrams](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams)
+- [GitHub: Writing mathematical expressions](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/writing-mathematical-expressions)
diff --git a/plugins/ndf-shared/skills/markdown-writing/01-diagram-guide.md b/plugins/ndf-shared/skills/markdown-writing/01-diagram-guide.md
index db40f52..ad9e8a4 100644
--- a/plugins/ndf-shared/skills/markdown-writing/01-diagram-guide.md
+++ b/plugins/ndf-shared/skills/markdown-writing/01-diagram-guide.md
@@ -2,6 +2,43 @@
 
 ## mermaid 記法
 
+### 横幅と文字サイズ
+
+mermaid は図の自然幅が本文幅を超えると、図全体を縮小して収める。文字も一緒に縮むため、横に長い図は文字が読めなくなる。縦に長い図は縮小されないので、文字サイズに影響しない。
+
+**横方向に並べる要素は3個まで。4個を超えないこと。**
+
+日本語ラベル（6文字程度）のノードは1個あたり約215px を消費する。本文幅と実効文字サイズの関係は以下（本文16px 基準の実測値）。
+
+| 横方向のノード数 | 図の自然幅 | GitHub（本文890px） | Notion（本文708px） |
+|---|---|---|---|
+| 3個 | 611px | 16px | 16px |
+| 4個 | 826px | 16px | 13.7px |
+| 5個 | 1041px | 13.7px | 10.9px |
+| 6個 | 1255px | 11.3px | 9.0px |
+| 7個 | 1470px | 9.7px | 7.7px |
+
+GitHub は5個から、Notion は4個から縮小が始まる。Notion に貼る前提の文書では**3個**を上限とする。
+
+縮小はノード数ではなく**幅**で決まるため、ラベルが長いほど早く限界が来る。`[Step1]` のような短いラベルなら1個あたり約152px で、GitHub なら6個まで等倍を保てる。
+
+超える場合の対処:
+
+| 対処 | 方法 |
+|------|------|
+| 向きを変える | `graph LR` をやめて `graph TD`（縦方向）にする。縦方向は何段あっても文字が縮まない |
+| ラベルを短くする | ノード幅はラベル文字数で決まる。`<br/>` で改行して幅を抑える |
+| 図を分割する | 1つの図に詰め込まず、関心事ごとに複数の図へ分ける |
+
+```mermaid
+graph TD
+    A[認証リクエスト<br/>受付] --> B{トークン<br/>有効?}
+    B -->|Yes| C[セッション作成]
+    B -->|No| D[401 を返す]
+```
+
+シーケンス図は participant 数が横幅を決め、1個あたり約200px を消費する。**GitHub で4個、Notion で3個**を上限とし、超えるならフェーズごとに図を分割する。
+
 ### フローチャート
 
 ```mermaid
@@ -49,39 +86,65 @@ erDiagram
     PRODUCT ||--o{ LINE_ITEM : "ordered in"
 ```
 
-## plantUML 記法
-
 ### コンポーネント図
 
-```plantuml
-@startuml
-package "Frontend" {
-    [React App]
-}
-package "Backend" {
-    [API Server]
-    [Database]
-}
-[React App] --> [API Server]
-[API Server] --> [Database]
-@enduml
+`subgraph` でグループを表現する。
+
+```mermaid
+graph LR
+    subgraph Frontend
+        R[React App]
+    end
+    subgraph Backend
+        A[API Server]
+        D[(Database)]
+    end
+    R --> A
+    A --> D
 ```
 
 ### アクティビティ図
 
-```plantuml
-@startuml
-start
-:ユーザー入力;
-if (有効?) then (yes)
-    :処理実行;
-else (no)
-    :エラー表示;
-endif
-stop
-@enduml
+```mermaid
+graph TD
+    S([開始]) --> I[ユーザー入力]
+    I --> V{有効?}
+    V -->|yes| P[処理実行]
+    V -->|no| E[エラー表示]
+    P --> G([終了])
+    E --> G
+```
+
+## その他の GitHub ネイティブ形式
+
+コードフェンスから直接レンダリングされる。図のソースが本文に残るのでレビューできる。
+
+### 数式（MathJax）
+
+ブロックは ` ```math ` または `$$…$$`、インラインは `$…$`。
+
+```math
+\sigma = \sqrt{\frac{1}{N}\sum_{i=1}^{N}(x_i - \mu)^2}
 ```
 
+### 地図
+
+` ```geojson ` / ` ```topojson ` でインタラクティブな地図になる。
+
+### 3Dモデル
+
+` ```stl ` に ASCII STL を書くと、回転・ズームできるビューアになる。
+
+## 使わないもの
+
+| | 理由 |
+|---|---|
+| plantUML | GitHub がレンダリングしない。外部レンダリングサーバの画像 URL に依存し、図のソースが差分に残らない |
+| HTML | GitHub 上ではソース表示になりレビューできない |
+| インライン `<svg>` | レンダラに除去され、図が消える |
+
+mermaid で表現しきれない自由レイアウトの図に限り、SVG をコミットして `<img src="./docs/diagram.svg">` で参照する。インラインでなくなるため、図と記述の乖離に気づけない点を承知の上で使う。
+
 ## ASCII 許可例（ツリーのみ）
 
 ディレクトリ構造はASCIIで表現可能:
@@ -138,7 +201,9 @@ docs/
 
 | DO | DON'T |
 |----|-------|
-| mermaid/plantUMLで図を描く | ASCII ARTで図を描く |
+| mermaid で図を描く | ASCII ARTで図を描く / plantUML を使う |
+| 横方向は3個まで（`graph TD` で縦に伸ばす） | 横に長い図にして文字を潰す |
+| 図はインラインで書く | 外部サービスの画像URLを貼る |
 | 300行以内に収める | 1000行超の巨大ファイル |
 | 順序prefixで分割 | prefixなしで分割 |
 | 2桁パディング（01-, 02-） | 1桁（1-, 2-） |
diff --git a/plugins/ndf-shared/skills/markdown-writing/SKILL.md b/plugins/ndf-shared/skills/markdown-writing/SKILL.md
index 56b3583..4b4d948 100644
--- a/plugins/ndf-shared/skills/markdown-writing/SKILL.md
+++ b/plugins/ndf-shared/skills/markdown-writing/SKILL.md
@@ -1,20 +1,113 @@
 ---
 name: markdown-writing
-description: "Write Markdown docs, diagrams, and split files."
-when_to_use: "Markdown 文書 / 図表を作成 / 編集するとき。Triggers: 'Markdown作成', 'ドキュメント作成', '文書作成', '図を描く', 'mermaid', 'create document', 'write docs'"
+description: "Write Markdown docs, PR bodies, and reports that read well to a third party."
+when_to_use: "Markdown 文書 / 仕様書 / 設計書 / PR 本文 / 調査レポート / 図表を作成・編集するとき。Triggers: 'Markdown作成', 'ドキュメント作成', '文書作成', '仕様書', '設計書', 'PR本文', 'PR説明', '調査レポート', '図を描く', 'mermaid', 'create document', 'write docs', 'write PR description'"
 allowed-tools:
   - Read
   - Write
   - Edit
+  - Grep
+  - Bash
 ---
 
 # Markdown Writing Skill
 
+読み手は**その場の会話・コードベース・検討過程を知らない第三者**（社外・レビュアー・将来の担当者）である、という前提で書く。
+
+適用対象: 仕様書 / 設計書 / README / OpenAPI 説明 / PR タイトル・本文 / コミットメッセージ / 調査レポート / 実装プラン / レビューコメント。
+
 ## 重要ルール
 
-### 1. 図表作成ルール
+### 1. 説明文に内部識別子・略語を持ち込まない
+
+**テーブル名・カラム名・クラス名などの内部識別子や、その場で作った略語を、説明文の主語・目的語に使わない。**
+
+「何のために」「何をやったか」を説明する文でこれらを使うと、読み手が識別子の意味を知っている前提になり、**書いた側は説明した気になり、読み手には何も伝わらない**。
+
+| | 例 |
+|---|---|
+| ❌ Bad | `user_subscriptions` の `plan_id` を更新し、us と sp を再生成する |
+| ✅ Good | 利用者の契約プランを変更し、請求明細を作り直す |
+| ❌ Bad | lcr がないと provisional に fallback する |
+| ✅ Good | 計算結果の控えが無い場合は、現在のマスタ値を参照する |
+
+**識別子を書いてよい場所**（むしろ書くべき）:
+
+- コードブロック・差分・スキーマ定義・SQL
+- 「どこを直したか」の指し示し（`app/Services/Foo.php:120` / 変更ファイル一覧）
+- 調査レポートのエビデンスブロック（クエリと実行結果）
+- 用語を導入する目的で、業務用語に括弧書きで添える場合
+
+**やること**:
+
+- 説明は業務用語・日本語で書き、識別子は必要なら括弧で添える（例: 「請求明細（`billing_details`）」）
+- 同じ文書で識別子を繰り返し使うなら、冒頭に**用語の対応表**を置き、本文は業務用語で通す
+- 略語は初出で正式名称を併記する。会話中に作ったローカル略称は文書に持ち込まない
+- プロジェクトに用語集（`terminology` skill、`docs/` の用語定義、UI ラベルの翻訳ファイル等）があれば、そこの表記に合わせる
+
+### 2. 検討過程の痕跡を残さない
+
+作成者とその場の相談相手（AI との対話含む）だけに通じるラベルや言い回しは、第三者には意味不明なので本文に書かない。
+
+- 検討時の選択肢ラベル（「案A / 案B」「Option A」「パターン1」などの符丁）
+- 「今回の相談で」「壁打ちの結果」「先ほど決めた」など会話由来の指示語
+- 不採用にした代替案との比較を、比較のためだけに残すこと
+
+**やること**: 決まった内容を、ラベルなしで断定形で書く。「なぜそうするか」は理由として本質的なものだけを一般的な言葉で残す。
+
+### 3. 変更履歴を本文に残さない
+
+指摘を受けて直した場合でも、**修正の経緯そのもの**を本文に含めない。
+
+- 「以前は X だったが、指摘を受けて Y に変更した」式の記述
+- 「〜という誤りがあったため修正」「レビュー対応で追加」などの由来説明
+- 却下された案の残骸
+
+**やること**: 現時点で正しい確定情報だけを書く。変更理由・経緯はコミットメッセージ / PR 説明 / レビュー返信に置く（git 履歴に残るので本文で二重に持たない）。
+
+- **stale 化防止**: 「以前は〜」式の履歴は、さらに変更が入ると二重に古くなる
+- **責務分離**: 「何が正か」は文書、「なぜ変えたか」は git / PR
+
+### 4. 否定的な結論にはエビデンスを添える
+
+「存在しない」「呼ばれていない」「データがない」「影響がない」といった**否定的な結論**は、読み手が最も検証しづらく、外れたときの被害が大きい。**必ず実行結果を根拠として添える。**
+
+| 主張 | 添えるエビデンス |
+|---|---|
+| カラム / テーブルが存在しない | スキーマ照会の実行結果 |
+| データが存在しない | 件数クエリの実行結果 |
+| どこからも呼ばれていない | 検索コマンドと結果（呼び出し元を辿った経路） |
+| 影響範囲がない | 洗い出した対象の一覧と、それぞれの判定 |
+
+やってはいけないこと:
+
+- コードを読んだだけで「無い」と断定する
+- エビデンスなしで残課題の優先度を下げる
+- 一部だけ見て「他にはない」と判断する
+
+確認しきれなかったことは、**「未確認・残リスク」として明示的に残す**。書かずに省くと「確認済み」と読まれる。
 
-**mermaid または plantUML を使用**（ASCII ART禁止、ツリー除く）
+### 5. 個人情報・機密情報を書かない
+
+文書・PR 本文・コミットメッセージ・添付ファイルに、実在の個人を特定できる情報や認証情報を含めない。コミットメッセージとマージ済み PR 本文は**後から消しにくく、履歴に残る**。
+
+- 氏名（フルネーム）/ 電話番号 / メールアドレス / 住所 / 生年月日
+- 個体を特定できる番号（車台番号、シリアル、口座番号など）
+- 認証情報・トークン・接続文字列
+- エクスポートしたままの実データ（CSV / XLSX / スクリーンショット）
+
+**やること**: 主キー・管理番号・記号（「対象A」「①」）で参照する。実データが必要なら社内アクセス制限のある場所に置き、文書には URL とサマリだけ書く。
+
+### 6. 図表作成ルール
+
+**図はインラインで書く。** GitHub がコードフェンスから直接レンダリングする形式だけを使う。図のソースが本文に残るため、差分でレビューでき、図と記述の乖離にも気づける。
+
+| 用途 | 書き方 |
+|---|---|
+| フロー / シーケンス / ER / 状態遷移 / クラス | ` ```mermaid ` |
+| 数式 | ` ```math ` または `$…$` / `$$…$$`（MathJax） |
+| 地図 | ` ```geojson ` / ` ```topojson ` |
+| 3Dモデル | ` ```stl `（ASCII STL） |
 
 ```mermaid
 graph TD
@@ -23,13 +116,40 @@ graph TD
     B -->|No| D[処理B]
 ```
 
-### 2. 文書の長さと分割ルール
+- 状態の対比（修正前 vs 後 / 期待 vs 実態 / 環境 A vs B）や定義の列挙は、図ではなく Markdown の**表**
+- **ディレクトリツリーは ASCII でよい**（`├──` / `└──` の罫線）。テキストのまま貼れて差分も追いやすく、図に置き換える利点がない
+- それ以外を ASCII ART で描かない
+
+```
+src/
+├── handlers/
+│   └── webhook.ts
+└── index.ts
+```
+
+**使わないもの**:
+
+- **HTML** — GitHub 上ではソース表示になりレビューできない
+- **plantUML** — GitHub はレンダリングしない。外部レンダリングサーバの画像 URL に依存することになり、図のソースが差分に残らない
+- **インライン `<svg>`** — レンダラに除去される
+
+mermaid で表現しきれない自由レイアウトの図がどうしても要る場合に限り、SVG をコミットして `<img src="./docs/diagram.svg">` で参照する。インラインではなくなるため、図と記述の乖離に気づけない点を承知の上で使う。
 
-| ページ数 | 対応 |
+### 7. 文書の長さと分割ルール
+
+| 行数 | 対応 |
 |---------|-----|
 | ~300行 | そのまま |
-| 301~600行 | 2ファイルに分割 |
-| 600行以上 | セクションごとに分割 |
+| 301~500行 | 内容によっては単一ファイルのままでよい（下記の判断基準） |
+| 501行以上 | セクションごとに分割 |
+
+300行を超えても、**分割すると読み手の理解が落ちる**場合は単一ファイルのままにする。
+
+- 通しで読んで初めて意味が通る一連の説明（手順書、設計の導出過程）
+- 分量の大半が表・コードブロックで、文章としての密度が低い
+- 相互参照が多く、分割すると行ったり来たりが増える
+
+逆に、独立して読める単位が明確にあるなら300行以下でも分割してよい。
 
 **分割時のファイル名**: 順序prefix（01-, 02-, ...）+ ケバブケース
 
@@ -40,19 +160,44 @@ docs/feature-guide/
 └── 03-usage.md
 ```
 
+## 書き終えたらセルフチェック
+
+**識別子と略語の混入**（説明文の中に裸で出ていないか。コードブロック内のヒットは無視してよい）:
+
+```bash
+grep -nE '[a-z]+_[a-z0-9_]{2,}' <対象ファイル>
+```
+
+**検討痕跡・変更履歴の混入**（プロジェクトやその場の符丁に応じて語を足す）:
+
+```bash
+grep -nE '案 ?[A-Z]|Option ?[A-Z]|パターン[0-9]|今回|壁打ち|以前は|当初は|に変更|指摘を受け|レビュー対応|誤りのため' <対象ファイル>
+```
+
+ヒットしたら、業務用語での説明・最終確定形の記述に置き換える。
+
 ## チェックリスト
 
-- [ ] 図表はmermaid/plantUML使用（ツリー除く）
-- [ ] ファイル長は300行以内（超える場合は分割）
+- [ ] 説明文がテーブル名 / カラム名 / ローカル略語ではなく業務用語で書かれている
+- [ ] 略語は初出で正式名称を併記している
+- [ ] 検討過程のラベル（案A / Option A 等）と会話由来の指示語が残っていない
+- [ ] 「以前は〜だったが変更した」式の経緯が本文に残っていない
+- [ ] 否定的な結論に実行結果のエビデンスが添えられている
+- [ ] 未確認事項が「残リスク」として明示されている
+- [ ] 個人情報・認証情報・実データが含まれていない
+- [ ] 図はインライン（mermaid / math / geojson / stl）で書いている（ディレクトリツリーはASCIIでよい）
+- [ ] plantUML / HTML / インライン`<svg>` を使っていない
+- [ ] ファイル長は300行以内（301~500行は内容次第で可、501行以上は分割）
 - [ ] 分割時は順序prefix使用（01-, 02-, ...）
 
 ## 詳細ガイド
 
 | ファイル | 内容 |
 |---------|------|
-| `01-diagram-guide.md` | mermaid/plantUML記法、よくある間違い |
+| `01-diagram-guide.md` | mermaid 記法、その他の GitHub ネイティブ形式、よくある間違い |
 
 ## 関連リソース
 
 - [Mermaid公式ドキュメント](https://mermaid.js.org/)
-- [PlantUML公式ドキュメント](https://plantuml.com/)
+- [GitHub: Creating diagrams](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams)
+- [GitHub: Writing mathematical expressions](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/writing-mathematical-expressions)