plan: Cr0wn60のVIA定義をcharlieplexingの検証用サンプルに加える

- samples/via/cr0wn60.json を追加し、テストケースにcharlieplexingを加える - ピンの割り当てとマスクの参照先としてファームウェアのコミット68d9249を記録する - CLAUDE.mdのドキュメント地図にsamples/を載せる Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017W6AsoJYTiN3bnxvSMS87f
plan: 検証用サンプルを実在のキーボードのKLE JSONで定める
2026-09-24 23:00:26 +09:00 · 2026-09-24 22:56:12 +09:00 · 2026-09-24 22:47:26 +09:00 · 2026-09-24 22:39:50 +09:00 · 2026-09-24 08:35:10 +09:00 · 2026-09-24 08:32:03 +09:00
34 changed files with 3184 additions and 214 deletions
@@ -0,0 +1,98 @@
+---
+name: decide
+description: 設計上の決定を記録する。メインドキュメントの更新・検討済み案の記録・journal作成・コミットを一度に行う。
+disable-model-invocation: true
+argument-hint: [決定の要旨]
+---
+
+# 決定を記録する
+
+共通の運用ルールは、AGENTS.mdの参照先であるCLAUDE.mdを正とする。
+現在の仕様はメインドキュメント、判断の経緯はjournal、変更の要旨はコミットに記録する。
+「検討済み・非採用」には、将来の再提案を防ぐために必要な案を選んで残す。
+
+## 手順
+
+### 0. 決定内容を確認する
+
+以下が揃っているか確認し、足りなければユーザーに聞く。推測で埋めない。
+
+- 採用した案は何か
+- それによって**今後効く制約**は何か(却下理由ではなく、現在の状態として書ける文)
+- 落とした案があるか
+- この決定が未確認の推測に依存していないか
+
+### 1. メインドキュメントを更新する
+
+該当する直下の `*.md` を更新する。
+
+- 採用した案・現在の設定を書く。「なぜAなのか」は1〜3行まで。
+- 「なぜBではないのか」は書かない。代わりに**制約文**として書く。
+  - ✗ `B案はKLEパーサーが壊れるので却下した`
+  - ○ `クラスター情報はKLE JSONに出力しない(KLE互換性の制約)`
+- 比較表・検討過程・ベンチマーク結果をここに書かない。
+- 他の担当の詳細を外へ移したあとも、この文書だけで担当範囲が分かるか確認する。
+  境界の理解に必要な一文と参照は残す。参照先の仕様は複製しない。
+
+### 2. 非採用一覧に残す案を選ぶ
+
+各案について、この記録が将来のどんな再提案を防ぐかを判断する。
+本文の制約だけで十分なら一覧へ重複記載しない。実際に検討した別方針で、
+再提案されうるものは、経緯への入口として末尾の `## 検討済み・非採用` に1案1行で残す。
+
+```
+- labels[9] へのID埋め込み (journal/2026-09-16-cluster-metadata.md)
+```
+
+- 理由は書かない。journalファイル名だけ。
+- 目安は5行まで。件数や古さだけで機械的に削除せず、再提案を防ぐ必要性で掲載を見直す。
+- 掲載する案がなければセクションを設けない。一覧から外しても経緯はjournalに残す。
+
+### 3. journal を書く
+
+`journal/YYYY-MM-DD-<topic>.md` を作る。トピックを詰め込まない(1決定1ファイル)。
+
+構成は上から順に:
+
+1. **結論** — 何を採用したか
+2. **案の比較** — 簡潔な表。メリット/デメリットを1行ずつ
+3. 検証ログ・根拠・捨てた案の詳細
+
+冒頭20行で結論と選択肢が分かること。整形は最低限でよい。
+他ファイルへのリンクも、他ファイルからのリンクも張らない。
+
+### 4. 推測と未決の問いを扱う
+
+この決定が未確認の推測に依存する場合:
+
+- メインドキュメント本文に `[推測:P-n]` を付ける
+- 末尾の `## 未確認事項` に項目を足し、**何を確認できれば事実に格上げできるか**を書く
+
+逆に、この決定で検証が済んだ推測があれば、タグを外して `## 未確認事項` から削除する。
+本文タグと末尾項目は必ず対で操作する(片方だけ残さない)。
+
+本文の未決記述は、読者が現在の対応範囲を理解するために必要かを判断する。
+対応する問いがあればCLAUDE.mdのルール4に従ってリンクし、問いの詳細は複製しない。
+必要な問いが未登録なら未確認事項を追加し、実装にも現在の説明にも不要な言及なら本文から外す。
+今は答えに依存せず進められる課題はルール5に従う。「未決」という単語だけで分類しない。
+
+### 5. コミットする
+
+メインドキュメントと journal を**同じコミット**に入れる。1コミット1決定。
+
+メッセージ:
+
+```
+<何を変えたか(1行)>
+
+<なぜそうしたか 数行>
+
+Journal: journal/2026-09-16-cluster-metadata.md
+```
+
+「なぜ」の詳細はコミットメッセージに書ききらない。journal 側にある。
+
+## 注意
+
+- 決定が固まっていない段階では使わない。調査中は journal だけ書けばよい。
+- 複数の決定をまとめてコミットしない。分ける。
@@ -0,0 +1,104 @@
+---
+name: doc-lint
+description: ドキュメントがAGENTS.mdの運用ルール1〜5に沿っているか検査する。推測タグと未確認事項の対応漏れ、保留課題の書式・参照・必須欄、journalへのリンク、比較表の混入などを検出する。
+argument-hint: [ファイル...]
+---
+
+# ドキュメントのルール違反を検査する
+
+機械的に判定できる項目はスクリプトで検出し、判断が要る項目だけ目視で見る。
+共通の運用ルールは、AGENTS.mdの参照先であるCLAUDE.mdを正とする。
+**検出して報告するだけで、勝手に直さない。** 修正は内容を確認してもらってから。
+
+## 1. スクリプトを走らせる
+
+```
+python .agents/skills/doc-lint/doc-lint.py [ファイル...]
+```
+
+Python 3.9以上で実行する。引数なしでリポジトリ直下の `*.md`、`journal/*.md`、`backlog/**/*.md` を全部見る。
+実行場所にかかわらずリポジトリを基準に分類し、明示したパスは実行ディレクトリから解決する。
+ERROR があれば終了コード 1。存在しない引数のファイルもERRORにする。
+
+検出する項目:
+
+| 種別 | 内容 |
+|---|---|
+| ERROR | 本文の `[推測:P-n]` に対応する `## 未確認事項` の項目がない |
+| ERROR | 本文の推測タグに対応する項目に `- 格上げ条件:` の内容がない |
+| ERROR | タグのない未確認事項に `- 格上げ条件:` または `- 完了条件:` の内容がない |
+| ERROR | `## 未確認事項` のIDが重複している |
+| ERROR | 未確認事項へのローカルリンクの参照先ファイル・見出しがない、または個別項目へのリンクが未確認事項の項目を指していない |
+| ERROR | リンクラベルの課題番号と参照先の課題番号が一致しない |
+| ERROR | 仕様書の `## 保留課題` がリンク箇条書き以外を含む、空である、参照先ファイル・見出しがない |
+| ERROR | 末尾の管理セクションが重複する、保留課題 → 検討済み・非採用 → 未確認事項の順でない |
+| ERROR | backlogの項目IDが不正・検査対象内で重複する、必須5欄がない・空である |
+| ERROR | backlogに推測タグがある、参照先ファイルが存在しない |
+| ERROR | journal へのリンク / journal から他ファイルへのリンク |
+| ERROR | `## 検討済み・非採用` の項目が journal ファイル名を参照していない |
+| ERROR | journal のファイル名が `YYYY-MM-DD-<topic>.md` 形式でない |
+| WARN | `## 検討済み・非採用` が5件を超えた |
+| WARN | 本文の段落・箇条書き項目に、リンクのない課題番号や、課題への参照を伴わない「未決」「未定」がある |
+| WARN | journal の冒頭20行に結論が見当たらない |
+| WARN | メインドキュメントに比較表・優先度評価・却下案の記述らしきもの |
+
+**本文タグのない `## 未確認事項` の項目はエラーにしない。** 実装前に判断が必要な未解決の問いとして正当。
+設計判断は「完了条件」でよい。タグなしの項目が事実確認なのか設計判断なのかは、目視で確認する。
+
+backlogでは `### PHY-P-14 題名` のように区分付きIDを使い、関連仕様・未決事項・保留できる理由・再開条件・完了条件を必須とする。
+仕様書側の書式は `- [PHYの保留課題](backlog/README.md#phy)`。
+backlogは短い候補・制約を保持できるため、メインドキュメント向けの散文ヒューリスティックは適用しない。
+
+WARN の散文検出は当たりが粗い。取りこぼしも誤検出もあるので、出た/出ないを結論にしない。
+未確認事項リンクの検査対象は `[P-3](#p-3-...)`・`[MAPのP-3](MAPレイヤー.md#p-3-...)` 等の
+インラインリンク。Markdown全般のリンク検査ではない。
+「未決」「未定」のWARNは、次行の参照も同じ段落として扱う。コード例、末尾の管理セクション、
+journal、backlog、ルールブック自体はこのWARNの対象外とする。
+WARNから課題の追加や本文の削除を自動決定しない。
+
+## 2. スクリプトで見られない項目を確認する
+
+こちらが本体。ファイルを読んで判断する。
+
+- **「なぜBではないのか」が理由として残っていないか。**
+  却下理由ではなく、現在効いている制約として書かれているか。
+  - ✗ `階層構造はKLEが非対応なので諦めた`
+  - ○ `階層クラスターはKLE JSONに出力しない(KLE互換性の制約)`
+- **本文が前提にする未確認の記述にタグが付いているか。** 検査項目の中で最も重要で、
+  機械では判定できない。「〜できるはず」「〜と考えられる」「実現可能」で実際に試していない
+  記述を探し、`[推測:P-n]` が付いているか確認する。
+- **同じ事実が複数ドキュメントに複製されていないか。** 片方だけ古くなる。
+- **他の担当の説明を移した結果、責務の境界まで消えていないか。**
+  この文書だけで担当範囲が分かるための一文と参照は残し、他の担当の詳細仕様は参照先で管理する。
+- **非採用一覧の各項目は、将来のどんな再提案を防ぐか。**
+  本文の制約で十分か、実際に検討した別方針として経緯への入口が必要かを判断する。
+  件数・古さ・重複だけで一律に追加・削除しない。
+- **本文の未決記述は、読者に何を伝えるためにあるか。**
+  現在の対応範囲は本文に残し、問いの詳細は未確認事項へ集約する。
+  対応項目へのリンク、必要な課題の追加、不要な言及の削除のいずれかを判断する。
+  リンクが存在しても、その問いが本文の内容に対応するかは目視で確認する。
+- **保留中の対応範囲が仕様本文にあるか。** 現在の実装が答えに依存する前提をbacklogへ隠していないか。
+- **再開条件・完了条件が具体的か。** 仕様書の保留課題リンクは該当区分に向き、解決済みの課題が残っていないか。
+- **journal の冒頭20行で、結論と選択肢が分かるか。** 見出しの有無ではなく中身を読む。
+- **コミット規約**(必要なら `git log --oneline` を見る)
+  - 1コミット1決定になっているか
+  - journal を伴う決定のメッセージに `Journal:` 行があるか
+
+## 3. 報告する
+
+機械検査のERROR / WARNと、目視で確認した内容・未確認の範囲を分けて報告する。
+機械検査が0件でも、内容の分類・責務の境界・記録の必要性が適切だった証明にはしない。
+目視確認を省いた場合はその旨を明記する。
+修正案は出してよいが、適用は確認を取ってから。事実関係の誤りを見つけた場合も、直さず指摘する。
+
+## 注意
+
+- 既存ドキュメントへのルール適用は段階的に進めている。
+  WARN が大量に出るのは想定内で、再編(`/restructure-doc`)のタイミングで解消する。
+  再編前のファイルの WARN を個別に直そうとしない。
+
+スクリプトを変更した場合の回帰検査:
+
+```
+python -B -m unittest discover -s .agents/skills/doc-lint -p test_doc_lint.py
+```
@@ -0,0 +1,382 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""CLAUDE.md の運用ルール1〜5のうち、機械的に判定できる項目を検査する。
+
+使い方:
+    python .agents/skills/doc-lint/doc-lint.py [ファイル...]
+引数なしならリポジトリ直下の *.md、journal/*.md、backlog/**/*.md が対象。
+明示したパスは実行ディレクトリから解決する。
+ERROR が1件でもあれば終了コード 1。
+"""
+import re
+import sys
+from pathlib import Path
+from urllib.parse import unquote, urlsplit
+
+TAG      = re.compile(r"\[推測:(P-\d+)\]")
+ENTRY    = re.compile(r"^###\s+(P-\d+)\b")
+H2       = re.compile(r"^##\s+(.*?)\s*$")
+MDLINK   = re.compile(r"\]\(([^)]+\.md[^)]*)\)")
+INLINE_LINK = re.compile(r"(?<!!)\[([^\]\n]+)\]\(\s*(<[^>\n]+>|[^\s)]+)\s*\)")
+INLINE_CODE = re.compile(r"(\x60+).*?\1", re.S)
+ISSUE_ID = re.compile(r"(?<![A-Za-z0-9_-])P-\d+(?![A-Za-z0-9_-])")
+ISSUE_ANCHOR = re.compile(r"^p-\d+(?:-|$)")
+HEADING = re.compile(r"^#{1,6}\s+(.+?)\s*#*\s*$")
+JOURNALFN= re.compile(r"^\d{4}-\d{2}-\d{2}-.+\.md$")
+PROMOTE  = re.compile(r"^\s*[-*]\s*格上げ条件\s*[:：]\s*\S")
+COMPLETE = re.compile(r"^\s*[-*]\s*完了条件\s*[:：]\s*\S")
+BACKLOG_ENTRY = re.compile(r"^###\s+([A-Za-z][A-Za-z0-9_-]*-P-\d+)\s+\S")
+BACKLOG_LINK = re.compile(r"^- \[[^\]]+の保留課題\]\(([^)]+)\)$")
+BACKLOG_FIELDS = ("関連仕様", "未決事項", "保留できる理由", "再開条件", "完了条件")
+MANAGEMENT_SECTIONS = ("保留課題", "検討済み・非採用", "未確認事項")
+ROOT = Path(__file__).resolve().parents[3]
+
+# ルールブック自身は、アンチパターンを例として引用するため散文ヒューリスティックの対象外
+PROSE_EXEMPT = {"CLAUDE.md"}
+
+issues = []
+def add(sev, path, line, msg):
+    issues.append((sev, path, line, msg))
+
+def load(path):
+    """コードフェンス内を空行に潰した (行番号, 本文) の列を返す。"""
+    raw = Path(path).read_text(encoding="utf-8").splitlines()
+    out, fence = [], None
+    for i, l in enumerate(raw, 1):
+        marker = re.match(r"^ {0,3}(\x60{3,}|~{3,})(.*)$", l)
+        if fence is not None:
+            out.append((i, ""))
+            if (marker and marker.group(1)[0] == fence[0]
+                    and len(marker.group(1)) >= fence[1] and not marker.group(2).strip()):
+                fence = None
+            continue
+        if marker:
+            fence = (marker.group(1)[0], len(marker.group(1)))
+            out.append((i, ""))
+            continue
+        out.append((i, l))
+    return out
+
+def section(lines, title):
+    """## <title> 配下の (行番号, 本文) を返す。無ければ None。"""
+    start = None
+    for idx, (n, l) in enumerate(lines):
+        m = H2.match(l)
+        if m and m.group(1) == title:
+            start = idx + 1
+            break
+    if start is None:
+        return None
+    body = []
+    for n, l in lines[start:]:
+        if H2.match(l):
+            break
+        body.append((n, l))
+    return body
+
+def local_target(path, target):
+    """相対リンクをリンク元基準で解決する。外部URLは対象外。"""
+    parsed = urlsplit(target)
+    if parsed.scheme or parsed.netloc:
+        return None, ""
+    linked = (path.parent / unquote(parsed.path)).resolve() if parsed.path else path
+    return linked, unquote(parsed.fragment)
+
+
+def heading_index(lines):
+    """ATX見出しのアンカーを作る。同じ見出しの連番も扱う。"""
+    headings = {}
+    for n, line in lines:
+        match = HEADING.match(line)
+        if not match:
+            continue
+        title = match.group(1)
+        slug = re.sub(r"[^\w\s-]", "", title).lower().replace(" ", "-")
+        anchor, suffix = slug, 0
+        while anchor in headings:
+            suffix += 1
+            anchor = f"{slug}-{suffix}"
+        headings[anchor] = (n, title)
+    return headings
+
+
+def body_paragraphs(lines):
+    """改行をまたぐ本文段落を返す。見出し・空行・次の箇条書きで区切る。"""
+    paragraph = []
+    in_management = False
+    for n, line in lines:
+        if HEADING.match(line):
+            if paragraph:
+                yield paragraph
+                paragraph = []
+            h2 = H2.match(line)
+            if h2:
+                in_management = h2.group(1) in MANAGEMENT_SECTIONS
+            elif line.startswith("# "):
+                in_management = False
+            continue
+        if in_management:
+            continue
+        if not line.strip() or re.match(r"^\s*(?:[-*+]|\d+[.)])\s+", line):
+            if paragraph:
+                yield paragraph
+                paragraph = []
+        if line.strip():
+            paragraph.append((n, line))
+    if paragraph:
+        yield paragraph
+
+
+def check_issue_references(path, rel, lines):
+    """課題リンクの構造はERROR、本文の参照漏れの候補はWARNにする。"""
+    targets = {}
+    valid_link_lines = set()
+    # インラインコードも位置を変えずにマスクする。
+    text = "\n".join(line for _, line in lines)
+    masked = INLINE_CODE.sub(lambda m: re.sub(r"[^\n]", " ", m.group()), text).split("\n")
+    prose_lines = [(n, line) for (n, _), line in zip(lines, masked)]
+    for n, line in prose_lines:
+        for match in INLINE_LINK.finditer(line):
+            label, target = match.groups()
+            target = target.strip("<>")
+            linked, anchor = local_target(path, target)
+            if linked is None:
+                continue
+            label_ids = ISSUE_ID.findall(label)
+            if not (label_ids or ISSUE_ANCHOR.match(anchor) or anchor == "未確認事項"):
+                continue
+            if not linked.is_file():
+                add("ERROR", rel, n, "未確認事項リンクの参照先ファイルがない: %s" % target)
+                continue
+            if linked not in targets:
+                target_lines = load(linked)
+                entries = {
+                    ln: ENTRY.match(value).group(1)
+                    for ln, value in (section(target_lines, "未確認事項") or [])
+                    if ENTRY.match(value)
+                }
+                targets[linked] = (heading_index(target_lines), entries)
+            headings, entries = targets[linked]
+            if not anchor or anchor not in headings:
+                add("ERROR", rel, n, "未確認事項リンクの参照先見出しがない: %s" % target)
+                continue
+            target_line, _ = headings[anchor]
+            if anchor == "未確認事項" and not label_ids:
+                continue
+            target_id = entries.get(target_line)
+            if target_id is None:
+                add("ERROR", rel, n, "課題リンクが未確認事項の個別項目を指していない: %s" % target)
+            elif any(pid != target_id for pid in label_ids):
+                add("ERROR", rel, n, "リンクラベルの課題番号と参照先が一致しない: %s → %s" % (label, target_id))
+            else:
+                valid_link_lines.add(n)
+
+    for paragraph in body_paragraphs(prose_lines):
+        n = paragraph[0][0]
+        text = "\n".join(line for _, line in paragraph)
+        # リンクと推測タグには別の構造検査がある。裸の課題番号だけを探す。
+        plain = TAG.sub("", INLINE_LINK.sub("", text))
+        bare_ids = sorted(set(ISSUE_ID.findall(plain)))
+        if bare_ids:
+            add("WARN", rel, n, "本文にリンクのない課題番号がある(要確認): %s" % ", ".join(bare_ids))
+        if (re.search(r"未決|未定", plain)
+                and not any(ln in valid_link_lines for ln, _ in paragraph)
+                and not TAG.search(text)):
+            add("WARN", rel, n, "本文の未決・未定に課題への参照がない(要確認)。リンク・課題追加・言及削除を判断する")
+
+
+def check_backlog(path, rel, lines, seen_ids):
+    blocks = []
+    current = None
+    for n, line in lines:
+        if H2.match(line):
+            current = None
+        elif re.match(r"^###\s", line):
+            match = BACKLOG_ENTRY.match(line)
+            current = None
+            if not match:
+                add("ERROR", rel, n, "保留課題の見出しは ### <区分>-P-<番号> <題名> とする")
+                continue
+            pid = match.group(1)
+            if pid in seen_ids:
+                add("ERROR", rel, n, "保留課題のID %s が重複している(初出: %s)" % (pid, seen_ids[pid]))
+            seen_ids[pid] = "%s:%d" % (rel, n)
+            current = (pid, n, [])
+            blocks.append(current)
+        elif current is not None:
+            current[2].append(line)
+
+    for pid, n, body in blocks:
+        for field in BACKLOG_FIELDS:
+            pattern = re.compile(r"^[-*]\s+" + re.escape(field) + r"\s*[:：]\s*\S")
+            if not any(pattern.match(line) for line in body):
+                add("ERROR", rel, n, "%s に「- %s:」の内容がない" % (pid, field))
+
+    for n, line in lines:
+        if TAG.search(line):
+            add("ERROR", rel, n, "本文の前提となる推測タグはbacklogではなく仕様書に置く")
+        for target in MDLINK.findall(line):
+            linked, _ = local_target(path, target)
+            if linked is not None and not linked.is_file():
+                add("ERROR", rel, n, "backlogの参照先ファイルがない: %s" % target)
+
+
+def check_backlog_section(path, rel, lines):
+    positions = []
+    for title in MANAGEMENT_SECTIONS:
+        headings = [n for n, line in lines if H2.match(line) and H2.match(line).group(1) == title]
+        if len(headings) > 1:
+            add("ERROR", rel, headings[1], "## %s が重複している" % title)
+        if headings:
+            positions.append(headings[0])
+    if positions != sorted(positions):
+        add("ERROR", rel, min(positions), "末尾の管理セクションは保留課題 → 検討済み・非採用 → 未確認事項の順に置く")
+
+    deferred = section(lines, "保留課題")
+    if deferred is None:
+        return
+    contents = [(n, line) for n, line in deferred if line.strip()]
+    if not contents:
+        add("ERROR", rel, 1, "空の ## 保留課題 はセクションごと削除する")
+    for n, line in contents:
+        match = BACKLOG_LINK.fullmatch(line)
+        if not match:
+            add("ERROR", rel, n, "保留課題には - [<区分>の保留課題](backlogのファイル#見出し) だけを書く")
+            continue
+        target = match.group(1)
+        linked, anchor = local_target(path, target)
+        if (linked is None or not linked.is_relative_to(ROOT / "backlog")
+                or linked.suffix != ".md" or not anchor):
+            add("ERROR", rel, n, "保留課題はbacklog内のMarkdownファイルの見出しへリンクする: %s" % target)
+            continue
+        if not linked.is_file():
+            add("ERROR", rel, n, "保留課題の参照先ファイルがない: %s" % target)
+            continue
+        headings = heading_index(load(linked))
+        if anchor not in headings:
+            add("ERROR", rel, n, "保留課題の参照先見出しがない: %s" % target)
+
+
+def check(path, seen_backlog_ids=None):
+    path = Path(path).resolve()
+    rel = path.relative_to(ROOT).as_posix() if path.is_relative_to(ROOT) else path.as_posix()
+    base = path.name
+    is_journal = path.is_relative_to(ROOT / "journal")
+    is_backlog = path.is_relative_to(ROOT / "backlog")
+    lines = load(path)
+
+    if is_backlog:
+        check_backlog(path, rel, lines, seen_backlog_ids if seen_backlog_ids is not None else {})
+    elif not is_journal:
+        check_backlog_section(path, rel, lines)
+        if base not in PROSE_EXEMPT:
+            check_issue_references(path, rel, lines)
+
+    unconf = section(lines, "未確認事項")
+    rejected = section(lines, "検討済み・非採用")
+    unconf_span = set(n for n, _ in unconf) if unconf else set()
+    tagged = {pid for n, line in lines if n not in unconf_span for pid in TAG.findall(line)}
+
+    # --- ルール4: 推測タグと未確認事項の対応 ---
+    entries = set()
+    if unconf is not None:
+        blocks = []          # [(pid, 行番号, [本文行])] 重複IDも個別に検査する
+        for n, l in unconf:
+            m = ENTRY.match(l)
+            if m:
+                pid = m.group(1)
+                if pid in entries:
+                    add("ERROR", rel, n, "未確認事項のID %s が重複している" % pid)
+                entries.add(pid)
+                blocks.append((pid, n, []))
+            elif blocks:
+                blocks[-1][2].append(l)
+        for pid, ln, body in blocks:
+            has_promote = any(PROMOTE.match(x) for x in body)
+            has_complete = any(COMPLETE.match(x) for x in body)
+            if pid in tagged and not has_promote:
+                add("ERROR", rel, ln,
+                    "%s に「- 格上げ条件:」の行がない(何を確認すれば事実に格上げできるか)" % pid)
+            elif not has_promote and not has_complete:
+                add("ERROR", rel, ln,
+                    "%s に「- 格上げ条件:」または「- 完了条件:」の内容がない" % pid)
+
+    for n, l in lines:
+        if n in unconf_span:
+            continue
+        for pid in TAG.findall(l):
+            if unconf is None or pid not in entries:
+                add("ERROR", rel, n,
+                    "本文の [推測:%s] に対応する項目が ## 未確認事項 にない" % pid)
+    # 逆向き(本文タグのない未確認事項)は「未解決の問い」として正当なのでエラーにしない
+
+    # --- ルール3: journal への/からのリンク禁止 ---
+    for n, l in lines:
+        for target in MDLINK.findall(l):
+            linked, _ = local_target(path, target)
+            if linked is not None and linked.is_relative_to(ROOT / "journal"):
+                add("ERROR", rel, n, "journal へのリンクが張られている: %s" % target)
+            elif is_journal and linked is not None:
+                add("ERROR", rel, n, "journal から他ファイルへのリンクが張られている: %s" % target)
+
+    # --- ルール1: 検討済み・非採用 ---
+    if rejected is not None:
+        items = [(n, l) for n, l in rejected if l.strip().startswith(("-", "*"))]
+        for n, l in items:
+            if not re.search(r"\(journal/[^)]+\.md\)", l):
+                add("ERROR", rel, n,
+                    "検討済み・非採用の項目が journal ファイル名を参照していない")
+        if len(items) > 5:
+            add("WARN", rel, items[5][0],
+                    "検討済み・非採用が %d 件(目安5件)。再提案を防ぐ必要性で掲載を見直す" % len(items))
+
+    # --- journal 固有 ---
+    if is_journal:
+        if not JOURNALFN.match(base):
+            add("ERROR", rel, 1, "journal のファイル名が YYYY-MM-DD-<topic>.md 形式でない")
+        head = " ".join(l for n, l in lines[:20])
+        if "結論" not in head:
+            add("WARN", rel, 1, "冒頭20行に結論が見当たらない(結論を先頭に置く)")
+
+    # --- ルール1: 調査・比較の混入(要目視確認) ---
+    if not is_journal and not is_backlog and base not in PROSE_EXEMPT:
+        # 検討済み・非採用 は却下案を列挙する場所なので対象外
+        skip = set(n for n, _ in rejected) if rejected else set()
+        for n, l in lines:
+            if n in skip:
+                continue
+            if "メリット" in l and "デメリット" in l:
+                add("WARN", rel, n, "比較表らしき記述(メリット/デメリット)。journal 行きでは?")
+            elif re.search(r"却下|不採用|見送っ|も検討したが|案[A-Z]|[A-Z]案", l):
+                add("WARN", rel, n, "却下案の検討過程らしき記述。制約文に書き換えるか journal へ")
+            elif re.search(r"優先度", l) and l.lstrip().startswith("#"):
+                add("WARN", rel, n, "優先度評価は journal 行きでは?")
+
+def main(argv):
+    issues.clear()
+    targets = [Path(arg).resolve() for arg in argv[1:]]
+    if not targets:
+        targets = (sorted(ROOT.glob("*.md")) + sorted((ROOT / "journal").glob("*.md"))
+                   + sorted((ROOT / "backlog").rglob("*.md")))
+    targets = list(dict.fromkeys(targets))
+    if not targets:
+        print("対象ファイルなし")
+        return 0
+    seen_backlog_ids = {}
+    for t in targets:
+        if t.is_file():
+            check(t, seen_backlog_ids)
+        else:
+            add("ERROR", t.as_posix(), 1, "対象ファイルが見つからない")
+
+    errs  = [i for i in issues if i[0] == "ERROR"]
+    warns = [i for i in issues if i[0] == "WARN"]
+    for sev, path, line, msg in errs + warns:
+        print("%-5s %s:%d  %s" % (sev, path, line, msg))
+    print("\n%d files / ERROR %d / WARN %d" % (len(targets), len(errs), len(warns)))
+    return 1 if errs else 0
+
+if __name__ == "__main__":
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")
+    sys.exit(main(sys.argv))
@@ -0,0 +1,300 @@
+"""文書の分類・参照・完了条件の回帰検査。標準ライブラリだけで実行する。"""
+import contextlib
+import importlib.util
+import io
+import tempfile
+import unittest
+from pathlib import Path
+from urllib.parse import quote
+from unittest.mock import patch
+
+
+spec = importlib.util.spec_from_file_location("doc_lint", Path(__file__).with_name("doc-lint.py"))
+lint = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(lint)
+
+
+def backlog_item(pid="PHY-P-14"):
+    return (
+        f"### {pid} 原点の吸着\n\n"
+        "- 関連仕様: [PHY](../PHY.md)\n"
+        "- 未決事項: 吸着が必要か\n"
+        "- 保留できる理由: 数値入力で編集できる\n"
+        "- 再開条件: 原点移動を試作するとき\n"
+        "- 完了条件: 吸着の要否を決める\n"
+    )
+
+
+def issue_section():
+    return (
+        "## 未確認事項\n\n"
+        "### P-1 動作の範囲\n\n- 完了条件: 範囲を決める\n\n"
+        "### P-3 対応・状態管理\n\n- 完了条件: 管理方法を決める\n"
+    )
+
+
+class DocLintTests(unittest.TestCase):
+    def setUp(self):
+        temporary = tempfile.TemporaryDirectory()
+        self.addCleanup(temporary.cleanup)
+        self.root = Path(temporary.name).resolve()
+        root_patch = patch.object(lint, "ROOT", self.root)
+        root_patch.start()
+        self.addCleanup(root_patch.stop)
+        self.write("PHY.md", "# PHY\n")
+
+    def write(self, relative, content):
+        path = self.root / relative
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding="utf-8")
+        return path
+
+    def run_lint(self, *paths):
+        output = io.StringIO()
+        with contextlib.redirect_stdout(output):
+            status = lint.main(["doc-lint.py", *(str(path) for path in paths)])
+        return status, output.getvalue()
+
+    def test_default_scan_includes_backlog_and_accepts_fixed_links(self):
+        self.write("PHY.md", "# PHY\n\n## 保留課題\n\n- [PHYの保留課題](backlog/README.md#phy)\n")
+        self.write("backlog/README.md", "# 保留課題\n\n## PHY\n\n" + backlog_item())
+        self.write("journal/2026-09-22-decision.md", "# 決定\n\n## 結論\n\n採用した。\n")
+        status, output = self.run_lint()
+        self.assertEqual(status, 0, output)
+        self.assertIn("3 files / ERROR 0", output)
+
+    def test_backlog_fields_must_have_values(self):
+        for field in lint.BACKLOG_FIELDS:
+            with self.subTest(field=field):
+                text = backlog_item()
+                text = "\n".join(f"- {field}: " if line.startswith(f"- {field}:") else line
+                                 for line in text.splitlines())
+                path = self.write("backlog/README.md", "## PHY\n" + text)
+                status, output = self.run_lint(path)
+                self.assertEqual(status, 1)
+                self.assertIn(f"- {field}:", output)
+
+    def test_duplicate_backlog_ids_across_nested_files(self):
+        self.write("backlog/one.md", "## PHY\n" + backlog_item())
+        self.write("backlog/sub/two.md", "## PHY\n" + backlog_item().replace("../PHY.md", "../../PHY.md"))
+        status, output = self.run_lint()
+        self.assertEqual(status, 1)
+        self.assertIn("保留課題のID PHY-P-14 が重複", output)
+
+    def test_incomplete_last_item_cannot_borrow_fields_from_next_section(self):
+        self.write("backlog/README.md", "## PHY\n### PHY-P-14 吸着\n\n## ELC\n" + backlog_item("ELC-P-1"))
+        status, output = self.run_lint()
+        self.assertEqual(status, 1)
+        self.assertIn("PHY-P-14 に「- 完了条件:」", output)
+
+    def test_invalid_backlog_heading_and_missing_reference(self):
+        path = self.write("backlog/README.md", "## PHY\n### P-14 吸着\n" + backlog_item().replace("../PHY.md", "../missing.md"))
+        status, output = self.run_lint(path)
+        self.assertEqual(status, 1)
+        self.assertIn("保留課題の見出し", output)
+        self.assertIn("参照先ファイルがない", output)
+
+    def test_spec_backlog_section_rejects_prose_empty_and_broken_targets(self):
+        self.write("backlog/README.md", "## PHY\n" + backlog_item())
+        cases = {
+            "内容をここにも要約する。": "だけを書く",
+            "": "空の ## 保留課題",
+            "- [PHYの保留課題](backlog/missing.md#phy)": "参照先ファイルがない",
+            "- [PHYの保留課題](backlog/README.md#missing)": "参照先見出しがない",
+            "- [PHYの保留課題](backlog/README.md)": "見出しへリンク",
+            "- [PHYの保留課題](PHY.md#phy)": "backlog内",
+        }
+        for content, expected in cases.items():
+            with self.subTest(content=content):
+                path = self.write("PHY.md", "# PHY\n\n## 保留課題\n\n" + content + "\n")
+                status, output = self.run_lint(path)
+                self.assertEqual(status, 1)
+                self.assertIn(expected, output)
+
+    def test_management_sections_have_one_order(self):
+        path = self.write("PHY.md", "## 未確認事項\n\n(なし)\n\n## 検討済み・非採用\n\n## 未確認事項\n")
+        status, output = self.run_lint(path)
+        self.assertEqual(status, 1)
+        self.assertIn("順に置く", output)
+        self.assertIn("## 未確認事項 が重複", output)
+
+    def test_decisions_accept_completion_but_tagged_assumptions_require_evidence(self):
+        text = "## 未確認事項\n\n### P-1 操作方式\n- 完了条件: 操作方式を決める\n"
+        path = self.write("PHY.md", text)
+        self.assertEqual(self.run_lint(path)[0], 0)
+        path.write_text("本文 [推測:P-1]\n\n" + text, encoding="utf-8")
+        status, output = self.run_lint(path)
+        self.assertEqual(status, 1)
+        self.assertIn("格上げ条件", output)
+        path.write_text("本文 [推測:P-1]\n\n" + text.replace("完了条件", "格上げ条件"), encoding="utf-8")
+        self.assertEqual(self.run_lint(path)[0], 0)
+
+    def test_absolute_journal_paths_keep_journal_checks(self):
+        path = self.write("journal/bad.md", "# 調査\n\n[仕様](../PHY.md)\n")
+        status, output = self.run_lint(path)
+        self.assertEqual(status, 1)
+        self.assertIn("journal のファイル名", output)
+        self.assertIn("journal から他ファイルへのリンク", output)
+
+    def test_backlog_is_not_prose_linted_but_cannot_link_to_journal(self):
+        self.write("journal/2026-09-22-decision.md", "## 結論\n")
+        path = self.write("backlog/README.md", "## PHY\n" + backlog_item() + "\n候補はA案。\n[履歴](../journal/2026-09-22-decision.md)\n")
+        status, output = self.run_lint(path)
+        self.assertEqual(status, 1)
+        self.assertIn("journal へのリンク", output)
+        self.assertIn("WARN 0", output)
+
+    def test_code_examples_do_not_create_real_sections_or_tags(self):
+        path = self.write("PHY.md", "```markdown\n## 保留課題\n[推測:P-9]\n```\n")
+        status, output = self.run_lint(path)
+        self.assertEqual(status, 0, output)
+
+    def test_missing_explicit_file_is_an_error(self):
+        status, output = self.run_lint(self.root / "missing.md")
+        self.assertEqual(status, 1)
+        self.assertIn("対象ファイルが見つからない", output)
+
+    def test_issue_links_accept_same_file_cross_file_and_encoded_anchors(self):
+        self.write("MAPレイヤー.md", "# MAP\n\n" + issue_section())
+        encoded = quote("MAPレイヤー.md") + "#" + quote("p-3-対応状態管理")
+        path = self.write(
+            "PHY.md",
+            "# PHY\n\n範囲は未決。\n[P-1](#p-1-動作の範囲)で扱う。\n\n"
+            "[MAPのP-3](MAPレイヤー.md#p-3-対応状態管理)へ。\n\n"
+            f"[MAPのP-3]({encoded})へ。\n\n" + issue_section(),
+        )
+        status, output = self.run_lint(path)
+        self.assertEqual(status, 0, output)
+        self.assertIn("ERROR 0 / WARN 0", output)
+
+    def test_issue_links_reject_missing_file_heading_and_fragment(self):
+        self.write("MAP.md", "# MAP\n\n" + issue_section())
+        for target, expected in (
+            ("missing.md#p-3-対応状態管理", "参照先ファイルがない"),
+            ("MAP.md#p-3-古い題名", "参照先見出しがない"),
+            ("MAP.md", "参照先見出しがない"),
+        ):
+            with self.subTest(target=target):
+                path = self.write("PHY.md", f"[P-3]({target})\n")
+                status, output = self.run_lint(path)
+                self.assertEqual(status, 1, output)
+                self.assertIn(expected, output)
+
+    def test_issue_label_must_match_real_entry_in_unconfirmed_section(self):
+        self.write("MAP.md", "# MAP\n\n### P-2 本文の見出し\n\n" + issue_section())
+        for link, expected in (
+            ("[P-3](MAP.md#p-1-動作の範囲)", "課題番号と参照先が一致しない"),
+            ("[MAPのP-3](MAP.md#p-1-動作の範囲)", "課題番号と参照先が一致しない"),
+            ("[P-2](MAP.md#p-2-本文の見出し)", "個別項目を指していない"),
+            ("[P-3](MAP.md#未確認事項)", "個別項目を指していない"),
+        ):
+            with self.subTest(link=link):
+                path = self.write("PHY.md", link + "\n")
+                status, output = self.run_lint(path)
+                self.assertEqual(status, 1, output)
+                self.assertIn(expected, output)
+
+    def test_duplicate_heading_slug_resolves_actual_target(self):
+        self.write("MAP.md", "# MAP\n\n### P-1 動作の範囲\n\n" + issue_section())
+        path = self.write("PHY.md", "[P-1](MAP.md#p-1-動作の範囲-1)\n")
+        self.assertEqual(self.run_lint(path)[0], 0)
+        path.write_text("[P-1](MAP.md#p-1-動作の範囲)\n", encoding="utf-8")
+        status, output = self.run_lint(path)
+        self.assertEqual(status, 1, output)
+        self.assertIn("個別項目を指していない", output)
+
+    def test_unresolved_prose_warns_without_failing_or_modifying_documents(self):
+        text = "# PHY\n\n方式は未定。P-3で検討する。\n\n" + issue_section()
+        path = self.write("PHY.md", text)
+        before = path.read_bytes()
+        status, output = self.run_lint(path)
+        self.assertEqual(status, 0, output)
+        self.assertIn("リンクのない課題番号", output)
+        self.assertIn("未決・未定に課題への参照がない", output)
+        self.assertEqual(path.read_bytes(), before)
+
+    def test_another_issue_link_does_not_hide_bare_id(self):
+        path = self.write(
+            "PHY.md", "P-3と[P-1](#p-1-動作の範囲)を参照。\n\n" + issue_section()
+        )
+        status, output = self.run_lint(path)
+        self.assertEqual(status, 0, output)
+        self.assertIn("リンクのない課題番号がある(要確認): P-3", output)
+
+    def test_unrelated_links_and_section_links_do_not_hide_unresolved_prose(self):
+        for link in ("[仕様](PHY.md)", "[一覧](#未確認事項)", "[外部](https://example.com/)"):
+            with self.subTest(link=link):
+                path = self.write("PHY.md", f"範囲は未決。{link}\n\n" + issue_section())
+                status, output = self.run_lint(path)
+                self.assertEqual(status, 0, output)
+                self.assertIn("未決・未定に課題への参照がない", output)
+
+    def test_broken_link_does_not_count_as_resolved_reference(self):
+        path = self.write("PHY.md", "範囲は未決。\n[P-1](#p-1-missing)\n")
+        status, output = self.run_lint(path)
+        self.assertEqual(status, 1, output)
+        self.assertIn("参照先見出しがない", output)
+        self.assertIn("未決・未定に課題への参照がない", output)
+
+    def test_paragraph_and_list_boundaries_do_not_borrow_links(self):
+        for body in (
+            "範囲は未決。\n\n[P-1](#p-1-動作の範囲)\n",
+            "- 範囲は未決。\n- [P-1](#p-1-動作の範囲)\n",
+            "1. 範囲は未決。\n2. [P-1](#p-1-動作の範囲)\n",
+            "範囲は未決。\n## 次の話\n[P-1](#p-1-動作の範囲)\n",
+        ):
+            with self.subTest(body=body):
+                path = self.write("PHY.md", body + "\n" + issue_section())
+                status, output = self.run_lint(path)
+                self.assertEqual(status, 0, output)
+                self.assertIn("未決・未定に課題への参照がない", output)
+        path = self.write(
+            "PHY.md", "- 範囲は未決。\n  [P-1](#p-1-動作の範囲)\n\n" + issue_section()
+        )
+        self.assertIn("ERROR 0 / WARN 0", self.run_lint(path)[1])
+
+    def test_code_examples_external_links_and_assumptions_are_not_prose_warnings(self):
+        path = self.write(
+            "PHY.md",
+            "\x60未決 P-8 [P-8](#missing)\x60\n\n"
+            "\x60\x60\x60markdown\n未定 P-8 [P-8](#missing)\n\x60\x60\x60\n\n"
+            "~~~markdown\n未定 P-8 [P-8](#missing)\n~~~\n\n"
+            "[P-99](https://example.com/#p-99)\n\n"
+            "範囲は未定 [推測:P-1]。\n\n"
+            "## 未確認事項\n\n### P-1 調査\n\n- 格上げ条件: 検証する\n",
+        )
+        status, output = self.run_lint(path)
+        self.assertEqual(status, 0, output)
+        self.assertIn("ERROR 0 / WARN 0", output)
+
+    def test_management_sections_and_non_spec_files_are_exempt_from_prose_warnings(self):
+        self.write("CLAUDE.md", "未決 P-8 [P-8](#missing)\n")
+        self.write("journal/2026-09-22-decision.md", "## 結論\n\n未定 P-8\n")
+        self.write("backlog/README.md", "## PHY\n\n" + backlog_item() + "\n未定 P-8\n")
+        self.write("PHY.md", "# PHY\n\n" + issue_section() + "\n未定 P-8\n")
+        status, output = self.run_lint()
+        self.assertEqual(status, 0, output)
+        self.assertIn("WARN 0", output)
+
+    def test_links_inside_unconfirmed_items_are_still_checked(self):
+        path = self.write("PHY.md", issue_section() + "\n[P-8](#missing)\n")
+        status, output = self.run_lint(path)
+        self.assertEqual(status, 1, output)
+        self.assertIn("参照先見出しがない", output)
+
+    def test_rejected_count_warning_does_not_select_entries_for_deletion(self):
+        path = self.write(
+            "PHY.md", "## 検討済み・非採用\n\n"
+            + "".join(f"- 案{i} (journal/2026-09-22-decision.md)\n" for i in range(6))
+        )
+        before = path.read_bytes()
+        status, output = self.run_lint(path)
+        self.assertEqual(status, 0, output)
+        self.assertIn("6 件(目安5件)", output)
+        self.assertIn("再提案を防ぐ必要性", output)
+        self.assertNotIn("古いものから落とす", output)
+        self.assertEqual(path.read_bytes(), before)
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,96 @@
+---
+name: restructure-doc
+description: 既存ドキュメント1ファイルをAGENTS.mdのルール1〜4に沿って仕分ける。事実・推測・採用案を残し、調査過程をjournalへ移す。
+disable-model-invocation: true
+argument-hint: <ファイル名>
+---
+
+# ドキュメントを再編する
+
+運用ルール策定前に書かれたドキュメントを、AGENTS.md のルール1〜4に沿った形に作り直す。
+**1回の実行で1ファイルだけ**扱う。
+
+## 最重要の制約
+
+**情報を失わせない。** この作業は「移動と再配置」であって、要約でも削除でもない。
+
+- 内容を短くしない。判断に迷った記述は、消さずに残してユーザーに聞く。
+- メインドキュメントから外す記述は、必ず journal に移す。捨てない。
+- 元の主張を勝手に言い換えない。特に断定度を上げ下げしない。
+
+## 手順
+
+### 1. 全体を読む
+
+対象ファイルを最初から最後まで読む。部分的に読んで判断しない。
+
+### 2. 4分類する
+
+各ブロック(見出し単位、または段落単位)を次のどれかに分ける。
+
+| 分類 | 行き先 |
+|---|---|
+| a. 採用した案 / 現在の設定 / 設計に影響する制約 | メインドキュメントに残す |
+| b. 裏取りの済んだ事実 | メインドキュメントに残す(文中のどこでもよい) |
+| c. 未確認の推測・未解決の問い | メインドキュメント末尾の `## 未確認事項` |
+| d. 調査過程 / 案の比較 / 却下案 / 優先度評価 | `journal/` へ移す |
+
+判定のヒント:
+
+- メリット/デメリット表、優先度リスト、「〜も検討したが」 → d
+- 「〜できるはず」「〜と考えられる」「実現可能」で、実際に試していない → c
+- 外部仕様の記述(KLEのプロパティ定義など)は、出典を確認できていれば b、していなければ c
+
+### 3. 分類結果を提示して承認を得る
+
+**ここで必ず止まる。** ファイルを書き換える前に、分類の一覧をユーザーに見せて確認する。
+特に b と c の境目(裏取りできているか)は自分で判断せず聞く。
+
+### 4. メインドキュメントを書き直す
+
+- a を中心に再構成する。b は文中に自然に置く。
+- 「なぜBではないのか」の記述が残っていたら、**制約文**に書き換える。
+  - ✗ `階層構造はKLEが非対応なので諦めた`
+  - ○ `階層クラスターはKLE JSONに出力しない(KLE互換性の制約)`
+- 落とした案があれば末尾 `## 検討済み・非採用` に1案1行(理由なし、journalファイル名を参照)。
+
+### 5. 未確認事項を立てる
+
+c に分類したものを末尾の `## 未確認事項` にまとめる。
+
+- 本文が前提にしている推測 → 本文に `[推測:P-n]` を付け、対応する項目を置く
+- まだ本文に書けない未解決の問い → 本文タグなしで項目だけ置く
+- 各項目に**格上げ条件**を必ず書く。思いつかないものはユーザーに聞く(空欄で残さない)
+
+```markdown
+### P-1 KLEはlabels[9]の内容を保存時に保持する
+- 位置づけ: 本文「クラスター管理」が前提にしている
+- 格上げ条件: KLE本家でインポート→エクスポートし、labels[9]が残ることを確認する
+```
+
+### 6. journal へ移す
+
+d を `journal/YYYY-MM-DD-<元ファイル名>.md` に移す。
+
+- 冒頭に**結論**(このファイルの再編で何が確定し、何を落としたか)
+- 次に案の比較(元ファイルの表をそのまま持ってきてよい)
+- 以下に元の調査記述
+- 整形は最低限でよい
+
+### 7. コミットする
+
+1ファイル1コミット。メインドキュメントと journal を同じコミットに入れる。
+
+```
+<ファイル名> を運用ルールに沿って再編
+
+<何を残し、何をjournalへ移したか 数行>
+
+Journal: journal/2026-09-16-<元ファイル名>.md
+```
+
+## 注意
+
+- 複数ファイルを一度に触らない。ファイル間で内容が重複していると気づいた場合は、
+  勝手に統合せず、指摘だけしてそのファイルの再編を終える。
+- 再編の途中で事実関係の誤りを見つけても、勝手に直さない。指摘する。
@@ -7,8 +7,9 @@ argument-hint: [決定の要旨]

 # 決定を記録する

-CLAUDE.md のルール1〜4に従い、決定を4箇所に分散して記録する。
-どれか1つでも欠けると後から追えなくなるので、全部やる。
+共通の運用ルールは CLAUDE.md を正とする。
+現在の仕様はメインドキュメント、判断の経緯はjournal、変更の要旨はコミットに記録する。
+「検討済み・非採用」には、将来の再提案を防ぐために必要な案を選んで残す。

 ## 手順

@@ -30,17 +31,22 @@ CLAUDE.md のルール1〜4に従い、決定を4箇所に分散して記録す
  - ✗ `B案はKLEパーサーが壊れるので却下した`
  - ○ `クラスター情報はKLE JSONに出力しない(KLE互換性の制約)`
 - 比較表・検討過程・ベンチマーク結果をここに書かない。
+- 他の担当の詳細を外へ移したあとも、この文書だけで担当範囲が分かるか確認する。
+  境界の理解に必要な一文と参照は残す。参照先の仕様は複製しない。

-### 2. 落とした案を1行残す
+### 2. 非採用一覧に残す案を選ぶ

-メインドキュメント末尾の `## 検討済み・非採用` に追記する。
+各案について、この記録が将来のどんな再提案を防ぐかを判断する。
+本文の制約だけで十分なら一覧へ重複記載しない。実際に検討した別方針で、
+再提案されうるものは、経緯への入口として末尾の `## 検討済み・非採用` に1案1行で残す。

 ```
 - labels[9] へのID埋め込み (journal/2026-09-16-cluster-metadata.md)
 ```

 - 理由は書かない。journalファイル名だけ。
- セクションが5行を超えたら、古いものから落とす。長くなるのは書きすぎのサイン。
+- 目安は5行まで。件数や古さだけで機械的に削除せず、再提案を防ぐ必要性で掲載を見直す。
+- 掲載する案がなければセクションを設けない。一覧から外しても経緯はjournalに残す。

 ### 3. journal を書く

@@ -55,7 +61,7 @@ CLAUDE.md のルール1〜4に従い、決定を4箇所に分散して記録す
 冒頭20行で結論と選択肢が分かること。整形は最低限でよい。
 他ファイルへのリンクも、他ファイルからのリンクも張らない。

-### 4. 推測を扱う
+### 4. 推測と未決の問いを扱う

 この決定が未確認の推測に依存する場合:

@@ -65,6 +71,11 @@ CLAUDE.md のルール1〜4に従い、決定を4箇所に分散して記録す
 逆に、この決定で検証が済んだ推測があれば、タグを外して `## 未確認事項` から削除する。
 本文タグと末尾項目は必ず対で操作する(片方だけ残さない)。

+本文の未決記述は、読者が現在の対応範囲を理解するために必要かを判断する。
+対応する問いがあればCLAUDE.mdのルール4に従ってリンクし、問いの詳細は複製しない。
+必要な問いが未登録なら未確認事項を追加し、実装にも現在の説明にも不要な言及なら本文から外す。
+今は答えに依存せず進められる課題はルール5に従う。「未決」という単語だけで分類しない。
+
 ### 5. コミットする

 メインドキュメントと journal を**同じコミット**に入れる。1コミット1決定。
@@ -1,12 +1,13 @@
 ---
 name: doc-lint
-description: ドキュメントがCLAUDE.mdの運用ルール1〜4に沿っているか検査する。推測タグと未確認事項の対応漏れ、journalへのリンク、比較表の混入などを検出する。
+description: ドキュメントがCLAUDE.mdの運用ルール1〜5に沿っているか検査する。推測タグと未確認事項の対応漏れ、保留課題の書式・参照・必須欄、journalへのリンク、比較表の混入などを検出する。
 argument-hint: [ファイル...]
 ---

 # ドキュメントのルール違反を検査する

 機械的に判定できる項目はスクリプトで検出し、判断が要る項目だけ目視で見る。
+共通の運用ルールは CLAUDE.md を正とする。
 **検出して報告するだけで、勝手に直さない。** 修正は内容を確認してもらってから。

 ## 1. スクリプトを走らせる
@@ -15,25 +16,45 @@ argument-hint: [ファイル...]
 python .claude/skills/doc-lint/doc-lint.py [ファイル...]
 ```

-引数なしで直下の `*.md` と `journal/*.md` を全部見る。ERROR があれば終了コード 1。
+Python 3.9以上で実行する。引数なしでリポジトリ直下の `*.md`、`journal/*.md`、`backlog/**/*.md` を全部見る。
+実行場所にかかわらずリポジトリを基準に分類し、明示したパスは実行ディレクトリから解決する。
+ERROR があれば終了コード 1。存在しない引数のファイルもERRORにする。

 検出する項目:

 | 種別 | 内容 |
 |---|---|
 | ERROR | 本文の `[推測:P-n]` に対応する `## 未確認事項` の項目がない |
-| ERROR | `## 未確認事項` の項目に `- 格上げ条件:` の行がない |
+| ERROR | 本文の推測タグに対応する項目に `- 格上げ条件:` の内容がない |
+| ERROR | タグのない未確認事項に `- 格上げ条件:` または `- 完了条件:` の内容がない |
 | ERROR | `## 未確認事項` のIDが重複している |
+| ERROR | 未確認事項へのローカルリンクの参照先ファイル・見出しがない、または個別項目へのリンクが未確認事項の項目を指していない |
+| ERROR | リンクラベルの課題番号と参照先の課題番号が一致しない |
+| ERROR | 仕様書の `## 保留課題` がリンク箇条書き以外を含む、空である、参照先ファイル・見出しがない |
+| ERROR | 末尾の管理セクションが重複する、保留課題 → 検討済み・非採用 → 未確認事項の順でない |
+| ERROR | backlogの項目IDが不正・検査対象内で重複する、必須5欄がない・空である |
+| ERROR | backlogに推測タグがある、参照先ファイルが存在しない |
 | ERROR | journal へのリンク / journal から他ファイルへのリンク |
 | ERROR | `## 検討済み・非採用` の項目が journal ファイル名を参照していない |
 | ERROR | journal のファイル名が `YYYY-MM-DD-<topic>.md` 形式でない |
 | WARN | `## 検討済み・非採用` が5件を超えた |
+| WARN | 本文の段落・箇条書き項目に、リンクのない課題番号や、課題への参照を伴わない「未決」「未定」がある |
 | WARN | journal の冒頭20行に結論が見当たらない |
 | WARN | メインドキュメントに比較表・優先度評価・却下案の記述らしきもの |

-**本文タグのない `## 未確認事項` の項目はエラーにしない。** 「まだ本文に書けない未解決の問い」として正当。
+**本文タグのない `## 未確認事項` の項目はエラーにしない。** 実装前に判断が必要な未解決の問いとして正当。
+設計判断は「完了条件」でよい。タグなしの項目が事実確認なのか設計判断なのかは、目視で確認する。
+
+backlogでは `### PHY-P-14 題名` のように区分付きIDを使い、関連仕様・未決事項・保留できる理由・再開条件・完了条件を必須とする。
+仕様書側の書式は `- [PHYの保留課題](backlog/README.md#phy)`。
+backlogは短い候補・制約を保持できるため、メインドキュメント向けの散文ヒューリスティックは適用しない。

 WARN の散文検出は当たりが粗い。取りこぼしも誤検出もあるので、出た/出ないを結論にしない。
+未確認事項リンクの検査対象は `[P-3](#p-3-...)`・`[MAPのP-3](MAPレイヤー.md#p-3-...)` 等の
+インラインリンク。Markdown全般のリンク検査ではない。
+「未決」「未定」のWARNは、次行の参照も同じ段落として扱う。コード例、末尾の管理セクション、
+journal、backlog、ルールブック自体はこのWARNの対象外とする。
+WARNから課題の追加や本文の削除を自動決定しない。

 ## 2. スクリプトで見られない項目を確認する

@@ -43,10 +64,21 @@ WARN の散文検出は当たりが粗い。取りこぼしも誤検出もある
  却下理由ではなく、現在効いている制約として書かれているか。
  - ✗ `階層構造はKLEが非対応なので諦めた`
  - ○ `階層クラスターはKLE JSONに出力しない(KLE互換性の制約)`
- **裏取りしていない記述にタグが付いていないか。** 検査項目の中で最も重要で、
+- **本文が前提にする未確認の記述にタグが付いているか。** 検査項目の中で最も重要で、
  機械では判定できない。「〜できるはず」「〜と考えられる」「実現可能」で実際に試していない
  記述を探し、`[推測:P-n]` が付いているか確認する。
 - **同じ事実が複数ドキュメントに複製されていないか。** 片方だけ古くなる。
+- **他の担当の説明を移した結果、責務の境界まで消えていないか。**
+  この文書だけで担当範囲が分かるための一文と参照は残し、他の担当の詳細仕様は参照先で管理する。
+- **非採用一覧の各項目は、将来のどんな再提案を防ぐか。**
+  本文の制約で十分か、実際に検討した別方針として経緯への入口が必要かを判断する。
+  件数・古さ・重複だけで一律に追加・削除しない。
+- **本文の未決記述は、読者に何を伝えるためにあるか。**
+  現在の対応範囲は本文に残し、問いの詳細は未確認事項へ集約する。
+  対応項目へのリンク、必要な課題の追加、不要な言及の削除のいずれかを判断する。
+  リンクが存在しても、その問いが本文の内容に対応するかは目視で確認する。
+- **保留中の対応範囲が仕様本文にあるか。** 現在の実装が答えに依存する前提をbacklogへ隠していないか。
+- **再開条件・完了条件が具体的か。** 仕様書の保留課題リンクは該当区分に向き、解決済みの課題が残っていないか。
 - **journal の冒頭20行で、結論と選択肢が分かるか。** 見出しの有無ではなく中身を読む。
 - **コミット規約**(必要なら `git log --oneline` を見る)
  - 1コミット1決定になっているか
@@ -54,11 +86,19 @@ WARN の散文検出は当たりが粗い。取りこぼしも誤検出もある

 ## 3. 報告する

-ERROR / WARN / 目視で見つけたもの を分けて出す。
+機械検査のERROR / WARNと、目視で確認した内容・未確認の範囲を分けて報告する。
+機械検査が0件でも、内容の分類・責務の境界・記録の必要性が適切だった証明にはしない。
+目視確認を省いた場合はその旨を明記する。
 修正案は出してよいが、適用は確認を取ってから。事実関係の誤りを見つけた場合も、直さず指摘する。

 ## 注意

- 運用ルール策定前に書かれた既存ドキュメントは、まだルール1〜4が適用されていない。
+- 既存ドキュメントへのルール適用は段階的に進めている。
  WARN が大量に出るのは想定内で、再編(`/restructure-doc`)のタイミングで解消する。
  再編前のファイルの WARN を個別に直そうとしない。
+
+スクリプトを変更した場合の回帰検査:
+
+```
+python -B -m unittest discover -s .claude/skills/doc-lint -p test_doc_lint.py
+```
@@ -1,23 +1,35 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
-"""CLAUDE.md の運用ルール1〜4のうち、機械的に判定できる項目を検査する。
+"""CLAUDE.md の運用ルール1〜5のうち、機械的に判定できる項目を検査する。

 使い方:
    python .claude/skills/doc-lint/doc-lint.py [ファイル...]
-引数なしなら リポジトリ直下の *.md と journal/*.md を対象にする。
+引数なしならリポジトリ直下の *.md、journal/*.md、backlog/**/*.md が対象。
+明示したパスは実行ディレクトリから解決する。
 ERROR が1件でもあれば終了コード 1。
 """
-import sys, re, os, io, glob
-
-if hasattr(sys.stdout, "reconfigure"):
-    sys.stdout.reconfigure(encoding="utf-8")
+import re
+import sys
+from pathlib import Path
+from urllib.parse import unquote, urlsplit

 TAG      = re.compile(r"\[推測:(P-\d+)\]")
 ENTRY    = re.compile(r"^###\s+(P-\d+)\b")
 H2       = re.compile(r"^##\s+(.*?)\s*$")
 MDLINK   = re.compile(r"\]\(([^)]+\.md[^)]*)\)")
+INLINE_LINK = re.compile(r"(?<!!)\[([^\]\n]+)\]\(\s*(<[^>\n]+>|[^\s)]+)\s*\)")
+INLINE_CODE = re.compile(r"(\x60+).*?\1", re.S)
+ISSUE_ID = re.compile(r"(?<![A-Za-z0-9_-])P-\d+(?![A-Za-z0-9_-])")
+ISSUE_ANCHOR = re.compile(r"^p-\d+(?:-|$)")
+HEADING = re.compile(r"^#{1,6}\s+(.+?)\s*#*\s*$")
 JOURNALFN= re.compile(r"^\d{4}-\d{2}-\d{2}-.+\.md$")
 PROMOTE  = re.compile(r"^\s*[-*]\s*格上げ条件\s*[:：]\s*\S")
+COMPLETE = re.compile(r"^\s*[-*]\s*完了条件\s*[:：]\s*\S")
+BACKLOG_ENTRY = re.compile(r"^###\s+([A-Za-z][A-Za-z0-9_-]*-P-\d+)\s+\S")
+BACKLOG_LINK = re.compile(r"^- \[[^\]]+の保留課題\]\(([^)]+)\)$")
+BACKLOG_FIELDS = ("関連仕様", "未決事項", "保留できる理由", "再開条件", "完了条件")
+MANAGEMENT_SECTIONS = ("保留課題", "検討済み・非採用", "未確認事項")
+ROOT = Path(__file__).resolve().parents[3]

 # ルールブック自身は、アンチパターンを例として引用するため散文ヒューリスティックの対象外
 PROSE_EXEMPT = {"CLAUDE.md"}
@@ -28,14 +40,21 @@ def add(sev, path, line, msg):

 def load(path):
    """コードフェンス内を空行に潰した (行番号, 本文) の列を返す。"""
-    raw = io.open(path, encoding="utf-8").read().splitlines()
-    out, fence = [], False
+    raw = Path(path).read_text(encoding="utf-8").splitlines()
+    out, fence = [], None
    for i, l in enumerate(raw, 1):
-        if l.lstrip().startswith("```"):
-            fence = not fence
+        marker = re.match(r"^ {0,3}(\x60{3,}|~{3,})(.*)$", l)
+        if fence is not None:
+            out.append((i, ""))
+            if (marker and marker.group(1)[0] == fence[0]
+                    and len(marker.group(1)) >= fence[1] and not marker.group(2).strip()):
+                fence = None
+            continue
+        if marker:
+            fence = (marker.group(1)[0], len(marker.group(1)))
            out.append((i, ""))
            continue
-        out.append((i, "" if fence else l))
+        out.append((i, l))
    return out

 def section(lines, title):
@@ -55,15 +74,208 @@ def section(lines, title):
        body.append((n, l))
    return body

-def check(path):
-    rel = path.replace(os.sep, "/")
-    base = os.path.basename(rel)
-    is_journal = rel.startswith("journal/")
+def local_target(path, target):
+    """相対リンクをリンク元基準で解決する。外部URLは対象外。"""
+    parsed = urlsplit(target)
+    if parsed.scheme or parsed.netloc:
+        return None, ""
+    linked = (path.parent / unquote(parsed.path)).resolve() if parsed.path else path
+    return linked, unquote(parsed.fragment)
+
+
+def heading_index(lines):
+    """ATX見出しのアンカーを作る。同じ見出しの連番も扱う。"""
+    headings = {}
+    for n, line in lines:
+        match = HEADING.match(line)
+        if not match:
+            continue
+        title = match.group(1)
+        slug = re.sub(r"[^\w\s-]", "", title).lower().replace(" ", "-")
+        anchor, suffix = slug, 0
+        while anchor in headings:
+            suffix += 1
+            anchor = f"{slug}-{suffix}"
+        headings[anchor] = (n, title)
+    return headings
+
+
+def body_paragraphs(lines):
+    """改行をまたぐ本文段落を返す。見出し・空行・次の箇条書きで区切る。"""
+    paragraph = []
+    in_management = False
+    for n, line in lines:
+        if HEADING.match(line):
+            if paragraph:
+                yield paragraph
+                paragraph = []
+            h2 = H2.match(line)
+            if h2:
+                in_management = h2.group(1) in MANAGEMENT_SECTIONS
+            elif line.startswith("# "):
+                in_management = False
+            continue
+        if in_management:
+            continue
+        if not line.strip() or re.match(r"^\s*(?:[-*+]|\d+[.)])\s+", line):
+            if paragraph:
+                yield paragraph
+                paragraph = []
+        if line.strip():
+            paragraph.append((n, line))
+    if paragraph:
+        yield paragraph
+
+
+def check_issue_references(path, rel, lines):
+    """課題リンクの構造はERROR、本文の参照漏れの候補はWARNにする。"""
+    targets = {}
+    valid_link_lines = set()
+    # インラインコードも位置を変えずにマスクする。
+    text = "\n".join(line for _, line in lines)
+    masked = INLINE_CODE.sub(lambda m: re.sub(r"[^\n]", " ", m.group()), text).split("\n")
+    prose_lines = [(n, line) for (n, _), line in zip(lines, masked)]
+    for n, line in prose_lines:
+        for match in INLINE_LINK.finditer(line):
+            label, target = match.groups()
+            target = target.strip("<>")
+            linked, anchor = local_target(path, target)
+            if linked is None:
+                continue
+            label_ids = ISSUE_ID.findall(label)
+            if not (label_ids or ISSUE_ANCHOR.match(anchor) or anchor == "未確認事項"):
+                continue
+            if not linked.is_file():
+                add("ERROR", rel, n, "未確認事項リンクの参照先ファイルがない: %s" % target)
+                continue
+            if linked not in targets:
+                target_lines = load(linked)
+                entries = {
+                    ln: ENTRY.match(value).group(1)
+                    for ln, value in (section(target_lines, "未確認事項") or [])
+                    if ENTRY.match(value)
+                }
+                targets[linked] = (heading_index(target_lines), entries)
+            headings, entries = targets[linked]
+            if not anchor or anchor not in headings:
+                add("ERROR", rel, n, "未確認事項リンクの参照先見出しがない: %s" % target)
+                continue
+            target_line, _ = headings[anchor]
+            if anchor == "未確認事項" and not label_ids:
+                continue
+            target_id = entries.get(target_line)
+            if target_id is None:
+                add("ERROR", rel, n, "課題リンクが未確認事項の個別項目を指していない: %s" % target)
+            elif any(pid != target_id for pid in label_ids):
+                add("ERROR", rel, n, "リンクラベルの課題番号と参照先が一致しない: %s → %s" % (label, target_id))
+            else:
+                valid_link_lines.add(n)
+
+    for paragraph in body_paragraphs(prose_lines):
+        n = paragraph[0][0]
+        text = "\n".join(line for _, line in paragraph)
+        # リンクと推測タグには別の構造検査がある。裸の課題番号だけを探す。
+        plain = TAG.sub("", INLINE_LINK.sub("", text))
+        bare_ids = sorted(set(ISSUE_ID.findall(plain)))
+        if bare_ids:
+            add("WARN", rel, n, "本文にリンクのない課題番号がある(要確認): %s" % ", ".join(bare_ids))
+        if (re.search(r"未決|未定", plain)
+                and not any(ln in valid_link_lines for ln, _ in paragraph)
+                and not TAG.search(text)):
+            add("WARN", rel, n, "本文の未決・未定に課題への参照がない(要確認)。リンク・課題追加・言及削除を判断する")
+
+
+def check_backlog(path, rel, lines, seen_ids):
+    blocks = []
+    current = None
+    for n, line in lines:
+        if H2.match(line):
+            current = None
+        elif re.match(r"^###\s", line):
+            match = BACKLOG_ENTRY.match(line)
+            current = None
+            if not match:
+                add("ERROR", rel, n, "保留課題の見出しは ### <区分>-P-<番号> <題名> とする")
+                continue
+            pid = match.group(1)
+            if pid in seen_ids:
+                add("ERROR", rel, n, "保留課題のID %s が重複している(初出: %s)" % (pid, seen_ids[pid]))
+            seen_ids[pid] = "%s:%d" % (rel, n)
+            current = (pid, n, [])
+            blocks.append(current)
+        elif current is not None:
+            current[2].append(line)
+
+    for pid, n, body in blocks:
+        for field in BACKLOG_FIELDS:
+            pattern = re.compile(r"^[-*]\s+" + re.escape(field) + r"\s*[:：]\s*\S")
+            if not any(pattern.match(line) for line in body):
+                add("ERROR", rel, n, "%s に「- %s:」の内容がない" % (pid, field))
+
+    for n, line in lines:
+        if TAG.search(line):
+            add("ERROR", rel, n, "本文の前提となる推測タグはbacklogではなく仕様書に置く")
+        for target in MDLINK.findall(line):
+            linked, _ = local_target(path, target)
+            if linked is not None and not linked.is_file():
+                add("ERROR", rel, n, "backlogの参照先ファイルがない: %s" % target)
+
+
+def check_backlog_section(path, rel, lines):
+    positions = []
+    for title in MANAGEMENT_SECTIONS:
+        headings = [n for n, line in lines if H2.match(line) and H2.match(line).group(1) == title]
+        if len(headings) > 1:
+            add("ERROR", rel, headings[1], "## %s が重複している" % title)
+        if headings:
+            positions.append(headings[0])
+    if positions != sorted(positions):
+        add("ERROR", rel, min(positions), "末尾の管理セクションは保留課題 → 検討済み・非採用 → 未確認事項の順に置く")
+
+    deferred = section(lines, "保留課題")
+    if deferred is None:
+        return
+    contents = [(n, line) for n, line in deferred if line.strip()]
+    if not contents:
+        add("ERROR", rel, 1, "空の ## 保留課題 はセクションごと削除する")
+    for n, line in contents:
+        match = BACKLOG_LINK.fullmatch(line)
+        if not match:
+            add("ERROR", rel, n, "保留課題には - [<区分>の保留課題](backlogのファイル#見出し) だけを書く")
+            continue
+        target = match.group(1)
+        linked, anchor = local_target(path, target)
+        if (linked is None or not linked.is_relative_to(ROOT / "backlog")
+                or linked.suffix != ".md" or not anchor):
+            add("ERROR", rel, n, "保留課題はbacklog内のMarkdownファイルの見出しへリンクする: %s" % target)
+            continue
+        if not linked.is_file():
+            add("ERROR", rel, n, "保留課題の参照先ファイルがない: %s" % target)
+            continue
+        headings = heading_index(load(linked))
+        if anchor not in headings:
+            add("ERROR", rel, n, "保留課題の参照先見出しがない: %s" % target)
+
+
+def check(path, seen_backlog_ids=None):
+    path = Path(path).resolve()
+    rel = path.relative_to(ROOT).as_posix() if path.is_relative_to(ROOT) else path.as_posix()
+    base = path.name
+    is_journal = path.is_relative_to(ROOT / "journal")
+    is_backlog = path.is_relative_to(ROOT / "backlog")
    lines = load(path)

+    if is_backlog:
+        check_backlog(path, rel, lines, seen_backlog_ids if seen_backlog_ids is not None else {})
+    elif not is_journal:
+        check_backlog_section(path, rel, lines)
+        if base not in PROSE_EXEMPT:
+            check_issue_references(path, rel, lines)
+
    unconf = section(lines, "未確認事項")
    rejected = section(lines, "検討済み・非採用")
    unconf_span = set(n for n, _ in unconf) if unconf else set()
+    tagged = {pid for n, line in lines if n not in unconf_span for pid in TAG.findall(line)}

    # --- ルール4: 推測タグと未確認事項の対応 ---
    entries = set()
@@ -80,9 +292,14 @@ def check(path):
            elif blocks:
                blocks[-1][2].append(l)
        for pid, ln, body in blocks:
-            if not any(PROMOTE.match(x) for x in body):
+            has_promote = any(PROMOTE.match(x) for x in body)
+            has_complete = any(COMPLETE.match(x) for x in body)
+            if pid in tagged and not has_promote:
                add("ERROR", rel, ln,
                    "%s に「- 格上げ条件:」の行がない(何を確認すれば事実に格上げできるか)" % pid)
+            elif not has_promote and not has_complete:
+                add("ERROR", rel, ln,
+                    "%s に「- 格上げ条件:」または「- 完了条件:」の内容がない" % pid)

    for n, l in lines:
        if n in unconf_span:
@@ -96,9 +313,10 @@ def check(path):
    # --- ルール3: journal への/からのリンク禁止 ---
    for n, l in lines:
        for target in MDLINK.findall(l):
-            if target.lstrip("./").startswith("journal/"):
+            linked, _ = local_target(path, target)
+            if linked is not None and linked.is_relative_to(ROOT / "journal"):
                add("ERROR", rel, n, "journal へのリンクが張られている: %s" % target)
-            elif is_journal:
+            elif is_journal and linked is not None:
                add("ERROR", rel, n, "journal から他ファイルへのリンクが張られている: %s" % target)

    # --- ルール1: 検討済み・非採用 ---
@@ -110,7 +328,7 @@ def check(path):
                    "検討済み・非採用の項目が journal ファイル名を参照していない")
        if len(items) > 5:
            add("WARN", rel, items[5][0],
-                "検討済み・非採用が %d 件(目安5件)。古いものから落とす" % len(items))
+                    "検討済み・非採用が %d 件(目安5件)。再提案を防ぐ必要性で掲載を見直す" % len(items))

    # --- journal 固有 ---
    if is_journal:
@@ -121,7 +339,7 @@ def check(path):
            add("WARN", rel, 1, "冒頭20行に結論が見当たらない(結論を先頭に置く)")

    # --- ルール1: 調査・比較の混入(要目視確認) ---
-    if not is_journal and base not in PROSE_EXEMPT:
+    if not is_journal and not is_backlog and base not in PROSE_EXEMPT:
        # 検討済み・非採用 は却下案を列挙する場所なので対象外
        skip = set(n for n, _ in rejected) if rejected else set()
        for n, l in lines:
@@ -135,16 +353,21 @@ def check(path):
                add("WARN", rel, n, "優先度評価は journal 行きでは?")

 def main(argv):
-    targets = argv[1:]
+    issues.clear()
+    targets = [Path(arg).resolve() for arg in argv[1:]]
    if not targets:
-        targets = sorted(glob.glob("*.md")) + sorted(glob.glob("journal/*.md"))
+        targets = (sorted(ROOT.glob("*.md")) + sorted((ROOT / "journal").glob("*.md"))
+                   + sorted((ROOT / "backlog").rglob("*.md")))
+    targets = list(dict.fromkeys(targets))
    if not targets:
-        print("対象ファイルなし"); return 0
+        print("対象ファイルなし")
+        return 0
+    seen_backlog_ids = {}
    for t in targets:
-        if os.path.isfile(t):
-            check(t)
+        if t.is_file():
+            check(t, seen_backlog_ids)
        else:
-            print("見つからない: %s" % t)
+            add("ERROR", t.as_posix(), 1, "対象ファイルが見つからない")

    errs  = [i for i in issues if i[0] == "ERROR"]
    warns = [i for i in issues if i[0] == "WARN"]
@@ -154,4 +377,6 @@ def main(argv):
    return 1 if errs else 0

 if __name__ == "__main__":
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")
    sys.exit(main(sys.argv))
@@ -0,0 +1,300 @@
+"""文書の分類・参照・完了条件の回帰検査。標準ライブラリだけで実行する。"""
+import contextlib
+import importlib.util
+import io
+import tempfile
+import unittest
+from pathlib import Path
+from urllib.parse import quote
+from unittest.mock import patch
+
+
+spec = importlib.util.spec_from_file_location("doc_lint", Path(__file__).with_name("doc-lint.py"))
+lint = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(lint)
+
+
+def backlog_item(pid="PHY-P-14"):
+    return (
+        f"### {pid} 原点の吸着\n\n"
+        "- 関連仕様: [PHY](../PHY.md)\n"
+        "- 未決事項: 吸着が必要か\n"
+        "- 保留できる理由: 数値入力で編集できる\n"
+        "- 再開条件: 原点移動を試作するとき\n"
+        "- 完了条件: 吸着の要否を決める\n"
+    )
+
+
+def issue_section():
+    return (
+        "## 未確認事項\n\n"
+        "### P-1 動作の範囲\n\n- 完了条件: 範囲を決める\n\n"
+        "### P-3 対応・状態管理\n\n- 完了条件: 管理方法を決める\n"
+    )
+
+
+class DocLintTests(unittest.TestCase):
+    def setUp(self):
+        temporary = tempfile.TemporaryDirectory()
+        self.addCleanup(temporary.cleanup)
+        self.root = Path(temporary.name).resolve()
+        root_patch = patch.object(lint, "ROOT", self.root)
+        root_patch.start()
+        self.addCleanup(root_patch.stop)
+        self.write("PHY.md", "# PHY\n")
+
+    def write(self, relative, content):
+        path = self.root / relative
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding="utf-8")
+        return path
+
+    def run_lint(self, *paths):
+        output = io.StringIO()
+        with contextlib.redirect_stdout(output):
+            status = lint.main(["doc-lint.py", *(str(path) for path in paths)])
+        return status, output.getvalue()
+
+    def test_default_scan_includes_backlog_and_accepts_fixed_links(self):
+        self.write("PHY.md", "# PHY\n\n## 保留課題\n\n- [PHYの保留課題](backlog/README.md#phy)\n")
+        self.write("backlog/README.md", "# 保留課題\n\n## PHY\n\n" + backlog_item())
+        self.write("journal/2026-09-22-decision.md", "# 決定\n\n## 結論\n\n採用した。\n")
+        status, output = self.run_lint()
+        self.assertEqual(status, 0, output)
+        self.assertIn("3 files / ERROR 0", output)
+
+    def test_backlog_fields_must_have_values(self):
+        for field in lint.BACKLOG_FIELDS:
+            with self.subTest(field=field):
+                text = backlog_item()
+                text = "\n".join(f"- {field}: " if line.startswith(f"- {field}:") else line
+                                 for line in text.splitlines())
+                path = self.write("backlog/README.md", "## PHY\n" + text)
+                status, output = self.run_lint(path)
+                self.assertEqual(status, 1)
+                self.assertIn(f"- {field}:", output)
+
+    def test_duplicate_backlog_ids_across_nested_files(self):
+        self.write("backlog/one.md", "## PHY\n" + backlog_item())
+        self.write("backlog/sub/two.md", "## PHY\n" + backlog_item().replace("../PHY.md", "../../PHY.md"))
+        status, output = self.run_lint()
+        self.assertEqual(status, 1)
+        self.assertIn("保留課題のID PHY-P-14 が重複", output)
+
+    def test_incomplete_last_item_cannot_borrow_fields_from_next_section(self):
+        self.write("backlog/README.md", "## PHY\n### PHY-P-14 吸着\n\n## ELC\n" + backlog_item("ELC-P-1"))
+        status, output = self.run_lint()
+        self.assertEqual(status, 1)
+        self.assertIn("PHY-P-14 に「- 完了条件:」", output)
+
+    def test_invalid_backlog_heading_and_missing_reference(self):
+        path = self.write("backlog/README.md", "## PHY\n### P-14 吸着\n" + backlog_item().replace("../PHY.md", "../missing.md"))
+        status, output = self.run_lint(path)
+        self.assertEqual(status, 1)
+        self.assertIn("保留課題の見出し", output)
+        self.assertIn("参照先ファイルがない", output)
+
+    def test_spec_backlog_section_rejects_prose_empty_and_broken_targets(self):
+        self.write("backlog/README.md", "## PHY\n" + backlog_item())
+        cases = {
+            "内容をここにも要約する。": "だけを書く",
+            "": "空の ## 保留課題",
+            "- [PHYの保留課題](backlog/missing.md#phy)": "参照先ファイルがない",
+            "- [PHYの保留課題](backlog/README.md#missing)": "参照先見出しがない",
+            "- [PHYの保留課題](backlog/README.md)": "見出しへリンク",
+            "- [PHYの保留課題](PHY.md#phy)": "backlog内",
+        }
+        for content, expected in cases.items():
+            with self.subTest(content=content):
+                path = self.write("PHY.md", "# PHY\n\n## 保留課題\n\n" + content + "\n")
+                status, output = self.run_lint(path)
+                self.assertEqual(status, 1)
+                self.assertIn(expected, output)
+
+    def test_management_sections_have_one_order(self):
+        path = self.write("PHY.md", "## 未確認事項\n\n(なし)\n\n## 検討済み・非採用\n\n## 未確認事項\n")
+        status, output = self.run_lint(path)
+        self.assertEqual(status, 1)
+        self.assertIn("順に置く", output)
+        self.assertIn("## 未確認事項 が重複", output)
+
+    def test_decisions_accept_completion_but_tagged_assumptions_require_evidence(self):
+        text = "## 未確認事項\n\n### P-1 操作方式\n- 完了条件: 操作方式を決める\n"
+        path = self.write("PHY.md", text)
+        self.assertEqual(self.run_lint(path)[0], 0)
+        path.write_text("本文 [推測:P-1]\n\n" + text, encoding="utf-8")
+        status, output = self.run_lint(path)
+        self.assertEqual(status, 1)
+        self.assertIn("格上げ条件", output)
+        path.write_text("本文 [推測:P-1]\n\n" + text.replace("完了条件", "格上げ条件"), encoding="utf-8")
+        self.assertEqual(self.run_lint(path)[0], 0)
+
+    def test_absolute_journal_paths_keep_journal_checks(self):
+        path = self.write("journal/bad.md", "# 調査\n\n[仕様](../PHY.md)\n")
+        status, output = self.run_lint(path)
+        self.assertEqual(status, 1)
+        self.assertIn("journal のファイル名", output)
+        self.assertIn("journal から他ファイルへのリンク", output)
+
+    def test_backlog_is_not_prose_linted_but_cannot_link_to_journal(self):
+        self.write("journal/2026-09-22-decision.md", "## 結論\n")
+        path = self.write("backlog/README.md", "## PHY\n" + backlog_item() + "\n候補はA案。\n[履歴](../journal/2026-09-22-decision.md)\n")
+        status, output = self.run_lint(path)
+        self.assertEqual(status, 1)
+        self.assertIn("journal へのリンク", output)
+        self.assertIn("WARN 0", output)
+
+    def test_code_examples_do_not_create_real_sections_or_tags(self):
+        path = self.write("PHY.md", "```markdown\n## 保留課題\n[推測:P-9]\n```\n")
+        status, output = self.run_lint(path)
+        self.assertEqual(status, 0, output)
+
+    def test_missing_explicit_file_is_an_error(self):
+        status, output = self.run_lint(self.root / "missing.md")
+        self.assertEqual(status, 1)
+        self.assertIn("対象ファイルが見つからない", output)
+
+    def test_issue_links_accept_same_file_cross_file_and_encoded_anchors(self):
+        self.write("MAPレイヤー.md", "# MAP\n\n" + issue_section())
+        encoded = quote("MAPレイヤー.md") + "#" + quote("p-3-対応状態管理")
+        path = self.write(
+            "PHY.md",
+            "# PHY\n\n範囲は未決。\n[P-1](#p-1-動作の範囲)で扱う。\n\n"
+            "[MAPのP-3](MAPレイヤー.md#p-3-対応状態管理)へ。\n\n"
+            f"[MAPのP-3]({encoded})へ。\n\n" + issue_section(),
+        )
+        status, output = self.run_lint(path)
+        self.assertEqual(status, 0, output)
+        self.assertIn("ERROR 0 / WARN 0", output)
+
+    def test_issue_links_reject_missing_file_heading_and_fragment(self):
+        self.write("MAP.md", "# MAP\n\n" + issue_section())
+        for target, expected in (
+            ("missing.md#p-3-対応状態管理", "参照先ファイルがない"),
+            ("MAP.md#p-3-古い題名", "参照先見出しがない"),
+            ("MAP.md", "参照先見出しがない"),
+        ):
+            with self.subTest(target=target):
+                path = self.write("PHY.md", f"[P-3]({target})\n")
+                status, output = self.run_lint(path)
+                self.assertEqual(status, 1, output)
+                self.assertIn(expected, output)
+
+    def test_issue_label_must_match_real_entry_in_unconfirmed_section(self):
+        self.write("MAP.md", "# MAP\n\n### P-2 本文の見出し\n\n" + issue_section())
+        for link, expected in (
+            ("[P-3](MAP.md#p-1-動作の範囲)", "課題番号と参照先が一致しない"),
+            ("[MAPのP-3](MAP.md#p-1-動作の範囲)", "課題番号と参照先が一致しない"),
+            ("[P-2](MAP.md#p-2-本文の見出し)", "個別項目を指していない"),
+            ("[P-3](MAP.md#未確認事項)", "個別項目を指していない"),
+        ):
+            with self.subTest(link=link):
+                path = self.write("PHY.md", link + "\n")
+                status, output = self.run_lint(path)
+                self.assertEqual(status, 1, output)
+                self.assertIn(expected, output)
+
+    def test_duplicate_heading_slug_resolves_actual_target(self):
+        self.write("MAP.md", "# MAP\n\n### P-1 動作の範囲\n\n" + issue_section())
+        path = self.write("PHY.md", "[P-1](MAP.md#p-1-動作の範囲-1)\n")
+        self.assertEqual(self.run_lint(path)[0], 0)
+        path.write_text("[P-1](MAP.md#p-1-動作の範囲)\n", encoding="utf-8")
+        status, output = self.run_lint(path)
+        self.assertEqual(status, 1, output)
+        self.assertIn("個別項目を指していない", output)
+
+    def test_unresolved_prose_warns_without_failing_or_modifying_documents(self):
+        text = "# PHY\n\n方式は未定。P-3で検討する。\n\n" + issue_section()
+        path = self.write("PHY.md", text)
+        before = path.read_bytes()
+        status, output = self.run_lint(path)
+        self.assertEqual(status, 0, output)
+        self.assertIn("リンクのない課題番号", output)
+        self.assertIn("未決・未定に課題への参照がない", output)
+        self.assertEqual(path.read_bytes(), before)
+
+    def test_another_issue_link_does_not_hide_bare_id(self):
+        path = self.write(
+            "PHY.md", "P-3と[P-1](#p-1-動作の範囲)を参照。\n\n" + issue_section()
+        )
+        status, output = self.run_lint(path)
+        self.assertEqual(status, 0, output)
+        self.assertIn("リンクのない課題番号がある(要確認): P-3", output)
+
+    def test_unrelated_links_and_section_links_do_not_hide_unresolved_prose(self):
+        for link in ("[仕様](PHY.md)", "[一覧](#未確認事項)", "[外部](https://example.com/)"):
+            with self.subTest(link=link):
+                path = self.write("PHY.md", f"範囲は未決。{link}\n\n" + issue_section())
+                status, output = self.run_lint(path)
+                self.assertEqual(status, 0, output)
+                self.assertIn("未決・未定に課題への参照がない", output)
+
+    def test_broken_link_does_not_count_as_resolved_reference(self):
+        path = self.write("PHY.md", "範囲は未決。\n[P-1](#p-1-missing)\n")
+        status, output = self.run_lint(path)
+        self.assertEqual(status, 1, output)
+        self.assertIn("参照先見出しがない", output)
+        self.assertIn("未決・未定に課題への参照がない", output)
+
+    def test_paragraph_and_list_boundaries_do_not_borrow_links(self):
+        for body in (
+            "範囲は未決。\n\n[P-1](#p-1-動作の範囲)\n",
+            "- 範囲は未決。\n- [P-1](#p-1-動作の範囲)\n",
+            "1. 範囲は未決。\n2. [P-1](#p-1-動作の範囲)\n",
+            "範囲は未決。\n## 次の話\n[P-1](#p-1-動作の範囲)\n",
+        ):
+            with self.subTest(body=body):
+                path = self.write("PHY.md", body + "\n" + issue_section())
+                status, output = self.run_lint(path)
+                self.assertEqual(status, 0, output)
+                self.assertIn("未決・未定に課題への参照がない", output)
+        path = self.write(
+            "PHY.md", "- 範囲は未決。\n  [P-1](#p-1-動作の範囲)\n\n" + issue_section()
+        )
+        self.assertIn("ERROR 0 / WARN 0", self.run_lint(path)[1])
+
+    def test_code_examples_external_links_and_assumptions_are_not_prose_warnings(self):
+        path = self.write(
+            "PHY.md",
+            "\x60未決 P-8 [P-8](#missing)\x60\n\n"
+            "\x60\x60\x60markdown\n未定 P-8 [P-8](#missing)\n\x60\x60\x60\n\n"
+            "~~~markdown\n未定 P-8 [P-8](#missing)\n~~~\n\n"
+            "[P-99](https://example.com/#p-99)\n\n"
+            "範囲は未定 [推測:P-1]。\n\n"
+            "## 未確認事項\n\n### P-1 調査\n\n- 格上げ条件: 検証する\n",
+        )
+        status, output = self.run_lint(path)
+        self.assertEqual(status, 0, output)
+        self.assertIn("ERROR 0 / WARN 0", output)
+
+    def test_management_sections_and_non_spec_files_are_exempt_from_prose_warnings(self):
+        self.write("CLAUDE.md", "未決 P-8 [P-8](#missing)\n")
+        self.write("journal/2026-09-22-decision.md", "## 結論\n\n未定 P-8\n")
+        self.write("backlog/README.md", "## PHY\n\n" + backlog_item() + "\n未定 P-8\n")
+        self.write("PHY.md", "# PHY\n\n" + issue_section() + "\n未定 P-8\n")
+        status, output = self.run_lint()
+        self.assertEqual(status, 0, output)
+        self.assertIn("WARN 0", output)
+
+    def test_links_inside_unconfirmed_items_are_still_checked(self):
+        path = self.write("PHY.md", issue_section() + "\n[P-8](#missing)\n")
+        status, output = self.run_lint(path)
+        self.assertEqual(status, 1, output)
+        self.assertIn("参照先見出しがない", output)
+
+    def test_rejected_count_warning_does_not_select_entries_for_deletion(self):
+        path = self.write(
+            "PHY.md", "## 検討済み・非採用\n\n"
+            + "".join(f"- 案{i} (journal/2026-09-22-decision.md)\n" for i in range(6))
+        )
+        before = path.read_bytes()
+        status, output = self.run_lint(path)
+        self.assertEqual(status, 0, output)
+        self.assertIn("6 件(目安5件)", output)
+        self.assertIn("再提案を防ぐ必要性", output)
+        self.assertNotIn("古いものから落とす", output)
+        self.assertEqual(path.read_bytes(), before)
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1 @@
+REDIRECT: CLAUDE.mdに準じる
@@ -1,7 +1,7 @@
 # Beyond KLE

 キーボード設計のデータモデルとワークフローを再設計するプロジェクト。
-PHY(物理配置) / ELC(電気配線) / IDX(キー識別) / MAP(キーマップ) / IME(入力変換) の5層に分離する。
+PHY(物理配置) / ELC(電気配線) / IDX(キー識別) / MAP(キーマップ) / HST(ホスト) の5層に分離する。

 - 応答・ドキュメントは日本語。
 - 現状はコード未着手、設計ドキュメントのみ。
@@ -14,19 +14,25 @@ PHY(物理配置) / ELC(電気配線) / IDX(キー識別) / MAP(キーマップ)
 | `PHYレイヤー.md` | PHY層の仕様 |
 | `ELCレイヤー.md` | ELC層の仕様 |
 | `IDXレイヤー.md` | IDX層の仕様 |
+| `MAPレイヤー.md` | MAP層とエディタの責務・実機との読み書き方針 |
+| `HSTレイヤー.md` | HST層(ホストによるキーコードの解釈)の仕様 |
 | `phase1-json-schema.md` | 各層のJSON Schema |
 | `keyboard-making-workflow.md` | 既存の自作キーボード制作フローとの対応 |
 | `implementation-plan.md` | 実装方針の決定事項・検証用サンプル |
+| [`backlog/README.md`](backlog/README.md) | 後回しにできる問い・検証・改善候補 |
+| `samples/` | 検証用サンプル(KLE JSON、VIA定義)。出典とテストケースは `implementation-plan.md` |

-**既存ドキュメントは下記ルールの策定前に書かれたもので、ルール1〜4は未適用。**
-全体の再編は別タスクとして行う。それまで各ファイルをメイン/journalのどちらに分類するかは未確定なので、
-指示なく移動・分割・書き直しをしない。
+既存ドキュメントには下記ルールを段階的に適用する。PHY・ELC・IDXの保留課題はbacklogへ分離済み。
+全体の再編は別タスクとして行い、指示なく他の内容を移動・分割・書き直ししない。

 初期コミット以前の経緯は追跡できない。現在のドキュメント群を「初期検討段階」のベースラインとして扱い、
 それ以前の決定理由を掘り起こそうとしない。

 ## ドキュメント運用ルール

+現在の仕様・将来取り組む課題・過去の検討を分け、仕様を読む際に判断状況が混ざらないようにする。
+未確認の前提は確定事項と区別し、保留課題は再開するまで見つけられる状態に保つ。
+
 ### 1. メインドキュメント(リポジトリ直下の `*.md`)

 書くもの: **採用した案 / 現在の設定 / 設計に影響する制約**。
@@ -36,10 +42,11 @@ PHY(物理配置) / ELC(電気配線) / IDX(キー識別) / MAP(キーマップ)
 - 却下案の再提案を防ぐ情報は、比較ではなく**制約文**として書く。
  - ✗ `B案はKLEパーサーが壊れるので却下した`
  - ○ `クラスター情報はKLE JSONに出力しない(KLE互換性の制約)`
- 末尾に `## 検討済み・非採用` を置き、落とした案を**1案1行**で残す。理由は書かず、journalファイル名を参照する。
+- 落とした案があれば、末尾に `## 検討済み・非採用` を置き、**1案1行**で残す。理由は書かず、journalファイル名を参照する。
  - 例: `- labels[9] へのID埋め込み (journal/2026-09-16-cluster-metadata.md)`
  - コミットは `git log --oneline -- journal/2026-09-16-cluster-metadata.md` で引ける(journal削除後も追跡可)
-  - 目安5行まで。増えたら古いものから落とす。ここが長くなるのは書きすぎのサイン。
+  - 載せるのは、実際に検討した別方針のうち再提案されうるものに限る。本文の制約文で足りるなら重複させない。
+  - 目安5行まで。増えたら、再提案を防ぐ必要性が低いものから落とす。長くなるのは書きすぎのサイン。

 ### 2. 履歴と根拠

@@ -62,10 +69,15 @@ PHY(物理配置) / ELC(電気配線) / IDX(キー識別) / MAP(キーマップ)

 - **裏取りの済んだ事実**は、ドキュメント内のどこに書いてもよい。文中に自然に混ぜてよい。
  ただし同じ事実を複数ドキュメントに複製しない。必要ならリンクする。
- **未確認の推測**だけを末尾に隔離する。2種類ある:
+- **現在の仕様・実装が答えに依存する未確認事項**は、仕様書の末尾に残す。2種類ある:
  - 本文が前提にしている推測 → 本文に `[推測:P-n]` を付け、末尾の `## 未確認事項` に対応項目を置く
-  - まだ本文に書けない未解決の問い → 本文タグなしで `## 未確認事項` に直接置く
- `## 未確認事項` の各項目には、**何を確認できれば事実に格上げできるか**を必ず書く。
+  - 実装前に判断が必要な未解決の問い → 本文タグなしで `## 未確認事項` に直接置く
+- 本文が未決の問いに触れるときは、「未決」と書いて終わらせず該当項目へリンクする。
+  同一ファイル内は `[P-3](#p-3-...)`、他ファイルからは `[MAPのP-3](MAPレイヤー.md#p-3-...)` の形とする。
+  問いの内容は `## 未確認事項` にだけ書き、本文へ写さない(二重管理を避ける)。
+- 未確認の推測には、**何を確認できれば事実に格上げできるか**を「格上げ条件」として書く。
+  設計判断には、**何を決めれば解決するか**を「完了条件」として書く。意思決定を事実確認と混同しない。
+- 答えに依存せず進められる課題は `backlog/` に置く(ルール5)。保留中の対応範囲・暫定仕様は仕様書に残す。
 - 検証できたらタグを外し、該当項目を削除する。
 - 「今回検討して捨てた仮説」は `## 未確認事項` に書かない。journal に残して消す。
 - 推測に基づいて実装しない。先に検証するか、ユーザーに確認する。
@@ -80,9 +92,39 @@ PHY(物理配置) / ELC(電気配線) / IDX(キー識別) / MAP(キーマップ)
 - 格上げ条件: KLE本家でインポート→エクスポートし、labels[9]が残ることを確認する
 ```

+### 5. 保留課題(`backlog/`)
+
+書くもの: **今は解決しなくても進められる問い・検証・改善候補**。
+
+- 当面は `backlog/README.md` にまとめる。増えて読みにくくなったらレイヤー別・トピック別に分ける。
+- 項目には、関連仕様・未決事項・保留できる理由・再開条件・完了条件を書く。
+  再開条件は「いつ考え直すか」、完了条件は「何を確認または決定すれば終わるか」を示す。
+- 仕様書から移す項目は、元の番号にレイヤー名などを付けて識別する(例: `PHY-P-14`)。
+  判断に必要な候補や制約は短く残す。長い比較・調査ログは `journal/` に置く。
+- 問いの本文は二重管理しない。仕様書には保留中の対応範囲・暫定仕様を残し、必要に応じてbacklogへリンクする。
+- 仕様書から保留課題を分離した場合、末尾の管理セクションを `## 保留課題` → `## 検討済み・非採用` →
+  `## 未確認事項` の順に置く(存在するものだけ)。`## 保留課題` には下記のリンク箇条書きだけを書く。
+  項目名の列挙・問いの要約・保留理由・対応範囲は書かない。対応範囲は仕様本文、問いの詳細はbacklogに置く。
+- リンクは `- [<区分>の保留課題](backlog/README.md#<区分の見出し>)` の形とする。
+  分割後は該当するbacklogファイルへ向ける。複数区分を参照する場合は1リンク1行とし、参照先の見出しまで指定する。
+  該当課題がなくなったらリンクを削除し、空になった `## 保留課題` はセクションごと削除する。
+- 現在の仕様が依存する未確認の前提は、backlogへ移して隠さない。仕様書の `## 未確認事項` に残す。
+- backlogへの移動は仮説の採用や実装の許可を意味しない。実装は採用済みの仕様・対応範囲に従う。
+- 解決したら必要な結論を仕様書へ反映し、項目と不要になった参照を削除する。取り下げた項目も削除し、完了一覧は蓄積しない。
+  調査・判断の経緯はルール2・3に従って履歴に残す。
+- 未解決の課題は作業ツリーに残す。結論反映後に削除できるjournalとは寿命が異なる。
+
+仕様書側の書式:
+
+```markdown
+## 保留課題
+
+- [PHYの保留課題](backlog/README.md#phy)
+```
+
 ## Claude への作業指示

- ドキュメントを更新するときは、上のルール1〜4のどこに属する情報かを判断してから書く。分類に迷うものは書く前に確認する。
+- ドキュメントを更新するときは、上のルール1〜5のどこに属する情報かを判断してから書く。分類に迷うものは書く前に確認する。
 - 調査タスクの結果は、結論だけをメインドキュメントに書き、調査過程は `journal/` に落とす。
 - 既存ドキュメントの記述と食い違う事実を見つけたら、勝手に上書きせず指摘する。

@@ -25,6 +25,9 @@ ELCが扱う「ピン」は物理的なマイコンピンに限らない。**ピ
 現時点で具体形を定めるのは、マイコンとアナログマルチプレクサの2種別。
 デジタル側でピンを増やす部品も提供者として扱うが、種別ごとの記述は必要になった時点で定める。

+同じ `PinRef` が複数の提供者の `select` に現れることは一律には禁止しない。
+複数mux構成の走査出力は、実配線と制御方法を確認した構成から対応する。
+
 ### キーの端子

 キーは検出方式(detect)を持ち、検出方式ごとに端子の構成が決まる。各端子は接続先の論理ピンを持つ。
@@ -32,7 +35,7 @@ ELCが扱う「ピン」は物理的なマイコンピンに限らない。**ピ
 - 接点(contact): a, b の2端子。端子は無極性で、a と b に順序の意味はない
 - アナログ(analog): out 1端子。加えて電源の vcc, gnd。ホールセンサがこれにあたる

-光学スイッチの端子構成は未定 [推測:P-1]。
+光学スイッチは当面未対応とする。端子構成を確認するまで、既存の検出方式に仮置きしない。

 ### 配線トポロジを区分として持たない

@@ -46,6 +49,12 @@ ELCが扱う「ピン」は物理的なマイコンピンに限らない。**ピ
 row / col はELCの正本に含めない。charlieplexing で便宜的に行と列の形で書くことはあるが、
 それは表記の都合であって配線の事実ではない。QMKなどが要求する row / col は、出力時に割り当てる派生情報とする。

+走査方向の決定と追加指定はFirmware Generatorが受け持ち、ELCには保存しない。
+接点マトリクスでは、どちら側のピン群を駆動し、どちら側から読み取るかを指す。
+配線・ダイオードの向きと整合する方向を出力器が選び、追加指定が必要な場合は出力設定で受け取る。
+配線だけから全方式の走査手順が一意に決まることは前提にしない。
+方式ごとの必要な設定は、その方式の出力に対応する際に確認し、未対応の構成は出力しない。
+
 ### ダイオード

 接点キーはダイオードの向きを持つ。向きは端子名で表す(`a-to-b` はアノードがa側)。省略時はダイオードなし。
@@ -70,9 +79,13 @@ PHYがレイアウトバリアントを持つ場合も、ELCは選択に関係
 設計エラーとする。接点マトリクスなら、どちらが押されたかを区別できないため。
 排他かどうかはPHYの木から判る。

+ファームウェア向けのキー番号と接続先の対応表は、バリアント選択後のIDXの並びから生成する。
+同じ接続先を共有する排他キーも、選択後に同時には残らない。ELCの保存データは選択によって書き換えない。
+
 LEDチェーンもバリアントごとに分けない。排他なキー位置の両方にLEDが載る基板も、
 バリアント固有のキーにLEDが載らない基板もあるが、どちらもチェーンは1本で、選択によって並びが変わらない。
 載らないキーは、PHYがキーごとに持つper-key LEDの有無でそのまま表せる。
+キー配列の出力で行うバリアントの取捨・番号の詰め直しは、LEDチェーンには適用しない。

 ### 他レイヤーへの参照

@@ -130,6 +143,10 @@ type ELC = {
 }
 ```

+## 保留課題
+
+- [ELCの保留課題](backlog/README.md#elc)
+
 ## 検討済み・非採用

 - `matrix.type` による配線方式の列挙 (journal/2026-09-20-elc-pin-provider.md)
@@ -138,22 +155,4 @@ type ELC = {

 ## 未確認事項

-### P-1 光学スイッチの端子構成
-
- 位置づけ: 本文「キーの端子」が扱えていない残り
- 現状の認識: 発光側と受光側が独立した端子を持つのか、接点と同じ2端子として扱えるのかが分からない
- 格上げ条件: 光学スイッチを使った実在のPCBの回路図を読み、端子数と配線の形を確認する
-
-### P-2 複数マルチプレクサ構成の作り
-
- 位置づけ: 本文「ピンとピン提供者」が前提にしている。`select` を提供者ごとに持たせてよいかに関わる
- 現状の認識: 選択ピンを複数のmuxで共有して共通ピンだけ分ける形と、イネーブルピンで切り替える形が考えられるが、
-  どちらが一般的か確認していない。前者なら同じ `PinRef` が複数の提供者の `select` に現れる
- 格上げ条件: 複数muxを使った実在のキーボードの配線を確認し、共有の形を確かめる
-
-### P-3 駆動側と検出側の役割をELCが明示的に持つ必要があるか
-
- 位置づけ: 本文「配線トポロジを区分として持たない」の残り
- 現状の認識: 接点マトリクスではダイオードの向きから、directでは電源レールの参照から、
-  どちらを駆動しどちらを検出するかが決まりそうに見えるが、全方式で導出できるか確かめていない
- 格上げ条件: 各方式について、端子の接続先とダイオードの向きだけから走査手順が一意に決まるかを確認する
+(なし)
@@ -0,0 +1,97 @@
+# HSTレイヤー
+
+## 概要
+
+HST(ホスト)レイヤーは、接続先のホストがキーボードから受け取ったキーコードをどう解釈するかを記述する。
+MAPが出力するのはHIDのキーコードであり、画面上の文字や動作は、ホストのOSとキーボード配列の設定で決まる。
+HSTはこの対応を持ち、MAPエディタとFirmware Generatorが参照する。入力がHSTを通過するわけではない。
+
+名前は、HIDでキーボード(device)の接続相手をhostと呼ぶことに合わせる。
+IMEのかな漢字変換はOSの仕事であり、HSTの対象外とする。
+
+## プロファイル
+
+HSTのデータは、ホスト環境ごとのプロファイルの集まりとする。
+プロファイルはキーボードに依存しないため、プロジェクトの外にある共有カタログとして版を管理する。
+プロジェクトは、参照するプロファイルのIDと、利用者ごとの差分(XKBのオプションなど)だけを持つ。
+
+### 識別
+
+プロファイルは、OSとホスト配列の組で識別する。必要な場合だけ、入力方式やその設定を加える。
+
+- ホスト配列は、OSがキーコードを解釈するための配列の設定である。キーキャップの刻印やOSの表示言語とは独立に決まる
+  (日本語のWindowsで英語配列を設定する、など)。
+- Linux(XKB)では、配列(layout)・変種(variant)・オプション(options)の組になる。
+- `win-jp` のような短い名前は、人が選ぶためのプリセット名として付ける。
+- 各OSの識別子(WindowsのKLID、XKBの名前、macOSの入力ソースID)と対応付けられるようにする。
+
+```json
+{ "os": "windows", "layout": "jp106" }
+{ "os": "macos",   "layout": "us" }
+{ "os": "linux",   "layout": "jp", "options": ["ctrl:nocaps"] }
+```
+
+「日本語入力を使う環境」のような設定は、プロファイルの識別に含める。
+IMEが今ONか、のような実行時の状態は識別に含めない(次節の引数として扱う)。
+
+### 記述する内容
+
+プロファイルは、順方向の対応だけを記述する。
+
+```txt
+(キーコード, 修飾キー, ホスト状態) → 文字 / 動作 / 未定義 / 不明
+```
+
+- ホスト状態: CapsLock、かなロック、IMEのON/OFFなど、同じキーコードの結果を変える状態。
+  HSTは状態の種類を引数として記述するだけで、実行時の状態を観測しない。
+- OS固有のキーの意味: `LANG1`/`LANG2`(Macのかな/英数)、変換/無変換、Cmd/Ctrlの役割など。
+- 成立の前提: 動作に必要なOS側の設定(Unicode入力の方式など)。HSTは設定を変更する機能を持たない。
+- 対応可否: 対応済み・未対応・不明の3値とする。カタログに載っていない動作を「使えない」と扱わない。
+
+## 使う側の責務
+
+HSTは逆引き(文字から、それを入力するキー操作を求めること)を持たない。
+逆引きは、使う側が順方向の表から求める[推測:P-1]。
+
+- 順方向の表から導けるので、両方を持つと二重管理になる。
+- 逆引きの候補には、ファームウェアの機能に依存するものがある。
+  例えば、US刻印のキーキャップをJIS配列のホストで使う場合、Shiftの有無で文字の組が合わないキーには、
+  Shift時に別のキーコードを送る機能(QMKのKey Override)が必要になる。
+  これはホストの知識ではないため、HSTに持たせない。
+
+使う側の担当は次のとおり。
+
+- MAPエディタ: キーコードの表示、逆引きによる入力補助、対象ホストで意味を持たないキーコードの警告
+- Firmware Generator: `send_string` が前提にする配列、Unicode入力の方式など、ホストに依存する生成設定
+
+## MAPとの境界
+
+- MAPは具体的なキーコードを保存する。逆引きは編集時の入力補助であり、選んだ候補のキーコードをMAPへ書く一方向の変換とする。
+  実機に残るのはキーコードだけなので、この形なら実機との往復を単純に保てる。
+- HSTは割り当てを所有・変更しない。PHYのキーIDも参照しない。
+
+## 対象外
+
+- 実行時の状態の観測・同期(今どのOSに接続しているか、IMEがONか)
+- OS設定の変更、IMEの変換処理
+- ホスト側での再割り当て(AutoHotkey、Karabiner、IMEのローマ字テーブルなど)
+- アプリごとのショートカット(「コピー」のような操作の汎用的な辞書)
+
+## 検討済み・非採用
+
+- 名前をSYSとする (journal/2026-09-24-hst-layer-scope.md)
+- 逆引きの候補をプロファイルが持つ (journal/2026-09-24-hst-layer-scope.md)
+
+## 未確認事項
+
+### P-1 使う側が逆引きの候補と実現可否を判断できる
+
+- 位置づけ: 本文「使う側の責務」が前提にしている。HSTにファームウェアの知識を持たせない線引きは、これが成り立つことに依存する。
+- 格上げ条件: US刻印のキーキャップをJIS配列のホストで使う構成で、Shiftの有無で文字の組が合わないキーについて、
+  HSTの順方向の表と、Generatorのビルド設定(有効な機能)だけから、MAPエディタがKey Overrideを含む候補を作れることを試作で確認する。
+
+### P-2 対象ホストを複数持つか
+
+- 位置づけ: 未解決の問い。Win/Mac両用のキーボードでは、表示と検証を複数のホストに対して行う必要がある。
+  OSの切り替えをMAPのレイヤーで表す既存の慣習と、どう対応付けるかも関わる。
+- 完了条件: プロジェクトが参照するプロファイルの数と、MAPのレイヤーとの対応付けの有無をユーザーが決める。
@@ -2,20 +2,24 @@

 ## 概要

-IDXレイヤーは、PHYのキーに「キー番号」を与える。キー番号は、キーマップがキーを指すための識別子である。
+IDXレイヤーは、全バリアントにわたるPHYのキーの並び順を持つ。
+番号を使う形式への出力時に、選択したバリアントで使うキーだけを残し、0から連続するキー番号を与える。
+保存した並びの位置と、選択後の出力でのキー番号は区別する。

-キー番号は他のどの情報からも導出できない。設計者が決める並び順そのものであり、
-そのためIDXが正本として持つ。ELCのrow/colが「配線から決まるので出力時に導出する」のと、
-理由が裏返しの関係にある。
+並び順は他のどの情報からも導出できない。設計者が決める情報なので、IDXが正本として持つ。
+ELCのrow/colが「配線から決まるので出力時に導出する」のと、理由が裏返しの関係にある。

-IDXが持つのは、番号を振る対象のキーと、その並び順だけとする。
+IDXが持つのは、番号を振る対象のキーと、その並び順だけとする。バリアントの選択は保存しない。

 ## キー番号は公開インターフェース

-基板を公開すると、他人が書いたキーマップがそのキー番号に依存する。
-番号を振り直すと、既存のキーマップが別のキーを指す。
+基板を公開すると、他人が書いたキーマップが、出力したレイアウトのキー番号に依存する。
+同じレイアウトで番号を振り直すと、既存のキーマップが別のキーを指す。

-そのためキー番号は、出力のたびに生成し直す派生情報として扱わず、固定した正本として保存する。
+そのため並び順は正本として保存し、出力のたびに幾何や配線から生成し直さない。
+同じ並びと同じバリアント選択からは、同じ出力番号を得る。
+番号の互換性は出力レイアウトごとに扱い、異なるバリアントの同じ番号が同じキーを指すとは限らない。
+並びへの挿入・削除・並べ替えでは、影響する出力レイアウトの番号が変わることを考慮する。

 ## 幾何から導出しない

@@ -51,35 +55,50 @@ row / col 自体がELCの正本ではなく出力時の派生情報である。

 ## レイアウトバリアント

-PHYがレイアウトバリアントを持つ場合も、キー番号の空間は1つとする。バリアントごとにIDXを分けない。
-キー番号は公開インターフェースであり、どの空間のものかを断らずに解釈できなければならない。
-特定のレイアウト向けの並びは、選んだバリアントに属さないキーを落として得る。
-ただしこれだけでは足りない場合がある。QMKのコミュニティレイアウトでは、同じマトリクス位置が
-レイアウトによって別の物理キーになり(ANSIのバックスラッシュとISOの `#~`)、残ったキーの読み順が変わる。
-ISO系で引数順が一致しない。
+IDXは、番号を振る対象のキーを全バリアントにわたって1つの `order` に持つ。
+各PHYキーIDを別々の要素として並べ、同じIDは重複させない。同じ接続先に配線された排他キーも
+別々の要素にする。物理キーごとに、出力先が要求する並びの中の位置を与えられるようにするため。

-排他なキー同士は、同じキー番号を共有できる。`order` の要素にキーIDの配列を書くと、
-その位置の番号を配列内のキーで共有する。
+出力時は、PHYのVariantGroupごとにバリアントを選び、次の手順で出力用の並びを得る。

-番号を共有できるのは、ELCで同じ接続先の組に配線されたキーに限る。
-3つの処理系が要求するのはいずれも「番号の位置 → マトリクス位置」の1対1の対応表であり、
-1つの番号に対応するマトリクス位置は1つしかないため。
-逆に、同じ接続先の組に配線された排他キーは番号を共有しなければならない。
-別々の番号を与えると、その対応表に同じマトリクス位置が2回現れ、1回のキー押下で両方の番号が反応する。
+1. 選択したバリアントの配下と、バリアントに属さない共通のキーを対象にする。
+   入れ子の場合は、祖先のバリアントも選択されているキーだけを対象にする
+2. `order` から対象外のキーを除く。残ったキー同士の順序は変えない
+3. 残った並びの位置を、0から連続する出力用のキー番号とする

-選択によって番号が詰まることはない。あるバリアントでしか実装されないキーの番号は、
-別のバリアントを選んだときには使われない番号として残る。
+保存した `order` は書き換えない。レイアウトごとに独立したIDXや並び順も保存しない。
+同じ接続先の排他キーは選択後に同時には残らないため、別々の要素でも出力の対応表に重複しない。
+番号を使う形式への出力は、バリアントを選択した構成を単位とする。
+
+例えば、ANSIのバックスラッシュとISOの `#` が同じ接続先を使う場合も、次のように並べられる。
+QとAは共通キー、バックスラッシュと `#` は排他キーとする。
+
+| キー | 保存したorderでの位置 | ANSI出力の番号 | ISO出力の番号 |
+| --- | --- | --- | --- |
+| Q | 0 | 0 | 0 |
+| バックスラッシュ | 1 | 1 | — |
+| A | 2 | 2 | 1 |
+| # | 3 | — | 2 |
+
+全体の並びは `Q → バックスラッシュ → A → #`、ANSI出力は `Q → バックスラッシュ → A`、
+ISO出力は `Q → A → #` になる。
+
+既存コミュニティレイアウトとの互換出力は、要求順を再現できることを確認したものを対象とする。
+単一の `order` で既存レイアウト全般を再現できることは、現行仕様の前提にしない。

 ## 他レイヤーとの関係

 IDXはPHYのキーIDだけを参照する。ELCを参照しない。

 MAPはIDXを参照しない。MAPもキーの参照にPHYのキーIDを使う。
-キーマップを配列として出力するとき、IDXの並び順で並べ替える。
-これにより、IDXにキーを挿入して番号がずれても、MAPは書き換えずに済む。
+キーマップを配列として出力するとき、バリアント選択後のIDXの並び順で並べ替える。
+ELCから作るキー番号と接続先の対応表にも、同じ選択後の並びを使う。
+これにより、IDXの編集やバリアント選択で出力番号が変わっても、MAP内のキーIDへの割り当ては書き換えずに済む。
+PHYのIDで参照するELC・MAPの保存データ自体には、番号を詰める処理はない。

 MAPが番号を持たないキーにキーコードを割り当てていた場合、そのキーは出力に現れない。
-IDXの `order` と突き合わせて検出できる。
+IDXの `order` と突き合わせて検出できる。`order` に含まれていても、選ばれなかったバリアントの
+キーへの割り当ては、その出力には含めない。

 ## 持たないもの

@@ -92,30 +111,28 @@ IDXの `order` と突き合わせて検出できる。

 ```ts
 type IDX = {
-    order: (string | string[])[] // PHYのキーID。並びの位置がキー番号。
-                                 // 配列は、その位置の番号を共有する排他バリアントのキー
+    order: string[] // 全バリアントの対象キーのPHY ID。各IDは1回だけ現れる。
+                    // 出力時に対象外のキーを除き、残った並びの位置をキー番号とする
 }
 ```

-並びの位置を番号とする形は、ELCの `LEDChain.order` と同じ形である。
-欠番・重複・番号の飛びが構造として起こらない。
+番号は個別のフィールドとして持たず、出力時の並びの位置で表すため、出力番号に欠番や飛びは生じない。
+キーIDの重複は許さない。

-`order` に挙げたキーだけが番号を持つ。PHYの部品ノードと `decal` のキーは対象にならない。
+出力番号の対象は `order` に挙げたキーに限る。PHYの部品ノードと `decal` のキーは対象にならない。
+
+## 保留課題
+
+- [IDXの保留課題](backlog/README.md#idx)

 ## 検討済み・非採用

 - PHYのツリー順をキー番号とする (journal/2026-09-21-idx-necessity.md)
 - ELCのマトリクス順からキー番号を導出する (journal/2026-09-21-idx-necessity.md)
- `keyId` と `index` の対を並べる形 (journal/2026-09-21-idx-necessity.md)
+- 排他キーで番号を共有し、選択後も番号を詰めない (journal/2026-09-22-idx-variant-output.md)
 - MAPがキー番号を参照する (journal/2026-09-21-idx-necessity.md)
 - レイアウトごとに別のIDXを持つ (journal/2026-09-21-multi-layout.md)

 ## 未確認事項

-### P-1 一致しないコミュニティレイアウトの並びをどう与えるか
-
- 位置づけ: 本文「レイアウトバリアント」の残余。一致しない場合があることは確認済み
- 現状の認識: QMKの実データで、コミュニティレイアウトとの173組のうち30組(すべてISO系)が
-  `order` からの取捨では得られない。並べ替えの規則を与えるか、レイアウトごとの並びを持つかが未定。
-  後者は「レイアウトごとに別のIDXを持つ」として一度落としている
- 格上げ条件: 埋め方をユーザーが決める
+(なし)
@@ -0,0 +1,161 @@
+# MAPレイヤー
+
+## 概要
+
+MAPレイヤーは、キーマップレイヤーごとのキーへの割り当てを持つ。
+MAPエディタは、その設計・編集と、実機との読み書きを提供する。
+ここでいうキーマップレイヤーは、PHY・ELC等の設計レイヤーとは区別する。
+
+主眼は、新しく作成するキーボードのワークフローにある。
+キーマップを設計し、実機へ反映し、使って調整した結果をプロジェクトへ戻せるようにする。
+既存キーボード全般への接続・取り込みを、初期対応の前提にはしない。
+
+## MAPデータと他レイヤーの関係
+
+キー参照と出力時の並べ替えは、[IDXレイヤー「他レイヤーとの関係」](IDXレイヤー.md#他レイヤーとの関係)に従う。
+MAPのキー参照にはPHYのキーIDを使い、実機との通信に使うアドレスを正本のキー参照にはしない。
+
+現行の保存形式は、[JSON SchemaのMAP節](phase1-json-schema.md#4-mapレイヤー-json-schema)にある
+レイヤー別のキーコード割り当てを出発点とする。
+キーコードはQMKの表記を基本とする。当面の対象ファームウェアがQMKであるため。
+レイヤーとStaticの動作定義への参照は、QMKの番号ではなく名前で書く([DynamicとStatic](#dynamicとstatic))。
+
+ファームウェアの設定値は、キーボード全体に効くものをFirmware Generatorの設定とし、
+キーごとに上書きする値(tapping termのper key設定等)をMAPが持つ。
+QMKの機能ごとにどちらに属するかを個別に判断しないで済むようにするため。
+
+動作定義とキーごとの設定の保存形式は、[P-1](#p-1-動作定義とキーごとの設定の保存形式)で扱う。
+
+新規作成したMAPは、すべてのキーが未割り当ての状態から始める。
+PHYのラベルからの自動適用は行わない([PHY「ラベル」](PHYレイヤー.md#ラベル))。
+
+## キーマップレイヤーの識別
+
+キーマップレイヤーは、並び順と独立した名前で識別する。名前はMAP内で一意とする。
+レイヤーを切り替える動作も名前でレイヤーを参照し、番号へは出力時に並び順から変換する。
+レイヤーの並べ替えや挿入で参照先がずれないようにするため。IDXがキー番号を正本にしないのと同じ理由による。
+
+## MAPエディタの責務
+
+- PHYの配置を参照し、キーマップレイヤーごとの割り当てを編集・保存する。
+- 対応する実機へ割り当てを書き込み、実機の現在の割り当てを読み出す。
+- 実機で使いながら調整し、その結果をMAPへ取り込むワークフローを提供する。
+
+読み書きは一組として対応する。読み出しには、現在値の確認に加え、Remap等で調整した結果を
+プロジェクトへ戻す用途も含む。保存と実機への反映の操作、差分表示、自動同期の有無は、
+[P-3](#p-3-プロジェクトと実機の対応状態管理)で扱う。
+
+## DynamicとStatic
+
+Dynamicは、対応ファームウェアが公開している通信プロトコルを使って、再ビルドせずに設定を読み書きする経路。
+Staticは、設定をファームウェアへ組み込むために出力する経路とする。
+Staticの出力は[全体方針のFirmware Generator](keyboard-design-layers.md#firmware-generator)が担い、MAPエディタは持たない。
+
+MAPエディタはDynamicの読み書きを提供する。Dynamicで変更できる範囲は、
+対象ファームウェアと既存プロトコルが公開する範囲に従う。
+
+当面の対象ファームウェアはQMKとし、対応範囲を次のように分ける。
+
+- Dynamic: QMK本家のVIAプロトコルが公開する項目に限る。
+- Static: QMK本家masterの公式機能のうちVIAで変更できないものは、Firmware Generatorで生成する対象とする。
+- 次のものには当面対応しない。
+    - Vial等のフォーク
+    - XAP、developブランチ等、master以外にある機能
+    - Community Modules(VIAモジュールを除く)
+- キーボード・キーマップ固有のコード(VIAのキーボード独自メニューを含む)には、原則として対応しない。
+
+QMKはVIAをCommunity Modulesの形式へ移し、従来の実装を将来のリリースで削除すると告知している(QMK 0.34.4のChangeLog「VIA Feature Migration」)。
+VIAがモジュールへ移っても、QMKとVIAの両方に追従する。そのため、移行がmasterに入る前に、VIAモジュールを有効にした出力と読み書きに対応する。
+
+Staticで定義する動作(タップダンス等)をキーへ割り当てるときは、定義を名前で参照し、出力時に番号へ変換する。
+割り当て自体はVIAで読み書きできても、参照先の定義はStaticにしかないため、
+[レイヤーの参照](#キーマップレイヤーの識別)と同じく並び順に依存させない。
+
+QMK本家のVIAには、VIAの管理外にある実機の保存設定(Magic設定、保存されたデフォルトレイヤー、Unicodeの入力モード等)を読み出す手段がない。
+これらを実機で変更しても、MAPエディタはプロジェクトへ取り込めない。
+
+プロジェクトのMAP、Staticで組み込んだ初期キーマップ、実機に保存された現在の割り当ては区別する。
+実機で調整してMAPへ取り込んだ割り当ては、Firmware Generatorへの入力としてStaticの初期キーマップへ反映できるようにする。
+実機の保存内容を初期化しても、調整後の割り当てに戻せるようにするため。
+
+## 対応プロトコル
+
+最初に対応する通信プロトコルはVIAとし、対応プロトコルを絞って段階的に増やす。
+ユーザーが好むRemapと同じ通信経路を使い、新規キーボードの設計から実機での調整へつなぐため。
+
+- QMKやVial側にBeyond KLE独自のプロトコルを追加しない。そのためのファームウェアのフォークも行わない。
+- VIA対応では、対象ファームウェアの既存のVIA機能を使って読み書きする。
+- VIAへの対応は、Remapというアプリ全体の機能を再現することを意味しない。
+- 初期の実装対象はVIAに限る。
+
+対応環境は、QMKのコミットと、使うモジュールの一覧(各モジュールの出所とコミット)で固定し、
+更新するタイミングはユーザーが個別に判断する。QMKに同梱されたモジュールは、QMKのコミットで決まる。
+VIAもモジュールの1つとして扱い、QMKリポジトリの外へ移った場合にも同じ形で指定できるようにするため。
+MAPエディタのUIには、対応しているVIAプロトコルとキーコード体系のバージョンを明示する。
+接続した実機とはこの2つのバージョンで照合し、一致しない実機には対応しない。
+実機から取得できるバージョン情報がこの2つに限られるため。
+
+最初に対応する環境は、QMK 0.34.4(commit `08c662f`)とする。このときキーコード体系は0.0.9、VIAプロトコルは0x000D。
+VIAは同梱の従来実装(`quantum/via.c`)で、追加のモジュールは使わない。
+
+## VIAで読み書きする項目
+
+VIAプロトコル0x000Dのコマンドのうち、MAPエディタが扱うものを次のように分ける[推測:P-2]。
+
+- 対応する:
+    - VIAプロトコルとキーコード体系のバージョンの読み出し(実機との照合に使う)
+    - レイヤー数の読み出し
+    - レイヤー別のキーコード割り当ての読み書き
+    - マクロの読み書き(個数・容量の読み出しとリセットを含む)
+- 別の課題で扱う:
+    - エンコーダの割り当て([MAP-P-4](backlog/README.md#map-p-4-onoff以外の入力への割り当て))
+    - layout option([P-3](#p-3-プロジェクトと実機の対応状態管理))
+- 当面対応しない: キーマップ・EEPROMのリセット、ブートローダへの移行、デバイスの識別表示、
+  マトリクス状態の読み出し(キーテスター)、custom channel(照明・オーディオ・キーボード独自メニュー)
+
+実機のファームウェアでどの機能が有効かは、VIAでは読み出せない。
+新規キーボードではFirmware Generatorのビルド設定を正とする。既存キーボードでは、利用者が同じ形式で申告した内容を信用する。
+レイヤー数、マクロの個数と容量は実機から読み出し、書き込む前にMAPの内容が収まるかを確認する。
+
+## 持たないもの
+
+物理配置、配線、キーの出力番号は、それぞれPHY・ELC・IDXで扱う。
+ホストによるキーコードの解釈は[HSTレイヤー](HSTレイヤー.md)、IMEの入力変換はOSの責務とし、外部ツールで編集できる照明等の設定も、
+VIAで通信できるという理由だけでMAPの所有データには含めない。
+MAPエディタは、キーコードを当面US配列の文字で表示する。
+
+アナログ入力の解釈の所属は、[全体方針のP-1](keyboard-design-layers.md#p-1-アナログ値の解釈をどの層が持つか)で扱う。
+
+## 保留課題
+
+- [MAPの保留課題](backlog/README.md#map)
+- [PHYの保留課題](backlog/README.md#phy)
+
+## 検討済み・非採用
+
+- MAPエディタをStaticに閉じる (journal/2026-09-22-map-via-workflow.md)
+
+## 未確認事項
+
+### P-1 動作定義とキーごとの設定の保存形式
+
+- 位置づけ: MAPのデータモデルを定めるための設計判断。
+- 未決事項:
+    - マクロ(VIAで読み書きするため内容をMAPが持つ)と、タップダンス・コンボ等のStaticで定義する動作を、MAPにどう保存するか。
+    - キーごとに上書きする設定を、PHYのキー、キーとレイヤーの組、キーコードのどれに付けるか。
+- 完了条件: 動作定義とキーごとの設定の保存形式をユーザーが決める。
+
+### P-2 VIAのコマンドはQMK 0.34.4のソースどおりに動作する
+
+- 位置づけ: 本文「VIAで読み書きする項目」が前提にしている。コマンドの内容はソース(`quantum/via.c`)と公式文書から確認したもので、実機では検証していない。
+- 格上げ条件: QMK 0.34.4でビルドした新規キーボードの構成で、対応するコマンドの読み書きと、レイヤー数・マクロの個数と容量の読み出しを実機で確認する。
+
+### P-3 プロジェクトと実機の対応・状態管理
+
+- 位置づけ: 実機への読み書きをMAPへ結び付けるための設計判断。
+- 未決事項:
+    - 出力した構成とPHYキーID・通信上のアドレスの対応をどこに保持し、接続した実機とどう照合するか。
+    - VIAの割り当ては接続先(row/col)単位で保存されるため、同じ接続先に配線された排他キーは、実機では1つの割り当て先を共有する。書き込み時に選択外のバリアントのキーの割り当てをどう扱うか、読み出した値をどのPHYキーへ戻すか(実機側のlayout optionの選択に従うか)。
+    - バリアントや配線の変更後の扱い。
+    - プロジェクトと実機、プロジェクトとStaticで組み込んだ初期キーマップの差分表示・保存・反映の操作。
+- 完了条件: 対応情報の生成・保存・照合方法と状態管理を定め、設計から実機へ反映し、Remap等での変更を元のPHYキーIDへの割り当てとして取り込む手順を確認する。排他キーを含む構成で、書き込みと読み出しがバリアントの選択に従って元のPHYキーへ対応することを確認する。
@@ -3,7 +3,7 @@
 ## 概要

 PHYレイヤーは、キースイッチやキーキャップ、その他周辺部品の物理的な配置に関する情報を提供する。  
-付加的な情報として、matrix情報(ELCレイヤー)や入力キー情報(MAP/IMEレイヤー)を含ませることができるが、必須ではない。
+付加的な情報として、matrix情報(ELCレイヤー)や入力キー情報(MAP/HSTレイヤー)を含ませることができるが、必須ではない。

 ## 構造

@@ -101,6 +101,8 @@ LED・OLED・ロータリーエンコーダ・ネジ穴のように、設計者
 フットプリントの選択には使わない。予約名以外および省略時は既定の形で描く。
 ユーザーが付ける名前は `@` で始めない限り予約と衝突しない。

+当面は表裏の描き分けを行わない。描画用の予約グループ名を、PCB上の実装面の指定としては使わない。
+
 部品ノードはクラスターの子になれる。クラスターを動かせば配下の部品も追随する。

 LEDの配線はPHYが持たない。LEDの識別番号もPHYは持たない。番号は配線で決まるため、ELCが持つ。
@@ -113,6 +115,7 @@ IDXはLEDの番号を持たない。RGB効果が必要とする位置と区分
 ### ラベル

 キーはラベルを参考情報として持つ。KLE JSONの取り込みでは照合に使う。
+当面はラベルからMAPへの自動適用は行わない。

 ### グルーピング

@@ -170,7 +173,8 @@ VariantGroupごとにバリアントを1つ選んでから階層を畳んで生
 Variantをまたぐノードの移動は、クラスター間の移動と同じreparentとして扱う。絶対配置は変わらない。
 組み替えの対象を同一の親に限る規則がそのまま効くため、複数のVariantにまたがる選択は組み替えできない。

-選択はPHYを畳むときにだけ使う。他レイヤーはPHYのノードIDを参照するだけで、選択を見ない。
+ELC・IDX・MAPの保存データは全バリアントのPHYノードIDを参照し、選択によって書き換えない。
+選択は、PHYを単一の配置に畳むときや、IDX・MAPから選択した構成のキー配列を生成するときに使う。

 ### クラスターの組み替え

@@ -197,6 +201,9 @@ Transform は回転と平行移動だけを持つ剛体変換であり、合成
  ただし選択したノード全部が同じ回転角度を持つ場合はその角度を基準角度に採り、境界矩形もその角度の座標系で取る
 - 組み替えで生じた非グリッド値はそのまま保持する。クラスターを解除して親に戻ったノードも同じ

+当面、reframeは通常の移動・回転と別の明示的な操作とし、原点の指定は数値入力で行う。
+原点の吸着やフォーカス状態・ハンドルに連動した操作は、試作後に検討する。
+
 ## 保存形式

 各ノードは親から見た変換を持つ。キー・クラスター・部品ノード・バリアントノードを混在させた木構造として保持する。
@@ -341,6 +348,10 @@ const kleData = (ConfigObject | KeyLabel)[][]

 ### KLE JSONの取り込み

+当面は新規PHYとしての読み込みを対象とする。既存PHYへの照合・更新は、照合規則を検証するまで未対応とする。
+以下は照合・更新に対応する際の制約であり、曖昧な対応を自動確定しない。
+誤照合で既存IDを別のキーに割り当てると、他レイヤーの参照にも影響するため。
+
 既存のPHYデータを畳んだ配置に対して、KLE JSONの各キーを形状(位置・サイズ・回転)とラベルで照合する。

 - 照合できたキーは元のノードとして扱う。KLE側で配置が変わっていれば、元の親から見た相対座標に戻して反映する
@@ -355,10 +366,17 @@ KLE本家はこの位置の r, rx, ry をエラーにするが、VIAとRemapは

 KLEの rx, ry, r はキーの絶対配置 (x, y, rotation) に変換して取り込む。元の rx, ry は保持しない。

-見た目の属性(c, t, p, a, f, f2, fa, l, n)は、KLE JSONへ書き戻せるように保持する。どの層で持つかは決まっていない。
+見た目の属性(c, t, p, a, f, f2, fa, l, n)は、KLE JSONへ書き戻せるように保持する。
+当面はキー単位の `kleCompatibility` に不透明なデータとして退避し、見た目の編集機能は持たない。

 KLEの sm, sb, st(ファイル単位では switchMount, switchBrand, switchType)も同様に、不透明なまま保持して書き戻す。
 Beyond KLEはスイッチの品種を持たないため、対応づける先がない。
+ファイル単位の属性(switchMount, switchBrand, switchType, backcolor, radii, background, css)は、
+ファイル単位の `kleCompatibility` に退避する。正式な所属層を決めるまでは、この退避先で保持する。
+
+## 保留課題
+
+- [PHYの保留課題](backlog/README.md#phy)

 ## 検討済み・非採用

@@ -370,39 +388,4 @@ Beyond KLEはスイッチの品種を持たないため、対応づける先が

 ## 未確認事項

-### P-2 KLE JSON取り込み時の照合基準
-
- 位置づけ: 本文「KLE JSONの取り込み」の具体化に必要な未解決の問い
- 現状の認識: 形状の許容誤差、ラベルの扱い、複数候補がある場合の決め方が未定
- 格上げ条件: 照合規則を決めたうえで、KLE本家でキーの移動・追加・削除をしたJSONを取り込み、意図どおりに対応づくことを確認する
-
-### P-6 キーキャップの見た目情報を持つ層
-
- 位置づけ: 本文「見た目の属性は保持する。どの層で持つかは決まっていない」の未解決部分
- 現状の認識: c, t, p, a, f系に加え、l, n もキーキャップの見た目属性であり、PHYとは別の層が要りそう。退避だけして書き戻す sm, sb, st も同じ置き場の問題を持つ。そもそもキーキャップは設計時に決める必要が薄く、カスタムキーボードの文脈に属するため、Beyond KLEの扱う範囲かどうかも未定。ファイル単位の backcolor, radii, background, css も同じ問いに含まれる
- 格上げ条件: キーキャップの情報をBeyond KLEの範囲に含めるかをユーザーが決め、保持する層を決める
-
-### P-8 ラベルをMAPに適用するか
-
- 位置づけ: 未解決の問い。本文ではラベルを参考情報として持つことだけを決めている
- 現状の認識: どのラベルがMAPに適用できるかは、おそらく機械的には判断できない。自動で適用してユーザーが不要なものを落とす方式も考えられる
- 格上げ条件: 適用するか、する場合は自動適用とユーザーによる取捨の流れをユーザーが決める
-
-### P-12 部品の表裏を描画でどう扱うか
-
- 位置づけ: 本文「部品ノードは表裏を持たない」の残余
- 現状の認識: どちらの面に載るかはPCB設計ツールが決める情報なのでPHYには持たない。ただしエディタ上で裏面の部品を描き分けたくなる可能性があり、`@` 始まりの予約グループ名だけで表現できるかは未検証
- 格上げ条件: 予約グループ名による描画を実装し、表裏の描き分けが必要になるか、必要なら予約名で足りるかを確認する
-
-### P-13 reframeと通常の移動・回転をエディタ上でどう区別するか
-
- 位置づけ: 本文「クラスターの組み替え」の残余。データモデル側は決まっており、操作系だけが未定
- 現状の認識: クラスターへのフォーカス状態に紐づけ(中に入っている間は配下の絶対配置が変わらない)、
-  そのうえで原点ハンドルと通常の移動・回転ハンドルを分ける案が有力。専用モードを設ける案もある
- 格上げ条件: 操作系をユーザーが決める
-
-### P-14 クラスター原点の吸着先
-
- 位置づけ: 未解決の問い。数値入力以外に、原点をどこへ吸着させるか
- 現状の認識: キーのローカル原点(左上角)・キー中心・境界矩形の角と中心が候補。相対グリッドとは別の機構になる
- 格上げ条件: 原点移動を実装し、吸着なしで足りるか、足りない場合どの候補が要るかを確認する
+(なし)
@@ -0,0 +1,164 @@
+# 保留課題
+
+現在の実装が答えに依存せず進められる問い・検証・改善候補をまとめる。
+保留中の対応範囲は各仕様書を正とし、運用は[ドキュメント運用ルール](../CLAUDE.md)に従う。
+項目の識別子は移動元のレイヤー名と番号を引き継ぐ。
+
+## PHY
+
+### PHY-P-2 KLE JSON取り込み時の照合基準
+
+- 関連仕様: [PHYレイヤー](../PHYレイヤー.md)「KLE JSONの取り込み」
+- 未決事項: 形状の許容誤差、ラベルの扱い、複数候補がある場合の決め方。
+- 保留できる理由: 新規PHYとしての読み込みは、既存ノードとの照合なしで実装できる。
+- 再開条件: 既存PHYへのKLE JSONの照合・更新に着手するとき。
+- 完了条件: 照合規則と曖昧な候補の扱いを決め、KLE本家でキーの移動・追加・削除をしたJSONを取り込み、
+  意図したIDに対応づき、他レイヤーの参照を誤って付け替えないことを確認する。
+
+### PHY-P-6 キーキャップの見た目情報を持つ層
+
+- 関連仕様: [PHYレイヤー](../PHYレイヤー.md)「KLE JSONの取り込み」、[JSON Schema](../phase1-json-schema.md)の `kleCompatibility`
+- 未決事項: キーキャップの見た目編集をBeyond KLEの範囲に含めるか、正式にはどの層で情報を持つか。
+  対象はキー単位の c, t, p, a, f系, l, n と、退避する sm, sb, st、ファイル単位の
+  switchMount, switchBrand, switchType, backcolor, radii, background, css。
+- 保留できる理由: 現行Schemaの `kleCompatibility` で、正式な所属層や編集機能を決めずに保持・書き戻しができる。
+- 再開条件: 見た目の編集機能、または退避先から正式な所属層への移行を検討するとき。
+- 完了条件: 扱う範囲と所属層をユーザーが決め、既存の退避情報を失わない保持・移行方法を定める。
+
+### PHY-P-8 ラベルをMAPに適用するか
+
+- 関連仕様: [PHYレイヤー](../PHYレイヤー.md)「ラベル」
+- 未決事項: ラベルをMAPへ適用するか。機械的に適用先を判断できるかは未確認で、候補を自動適用してユーザーが不要なものを落とす案もある。
+- 保留できる理由: ラベルは参考情報として保持でき、MAPへの自動適用なしで各レイヤーを扱える。
+- 再開条件: MAPのキーコード割り当てを補助する機能を検討するとき。
+- 完了条件: 適用の要否と、適用する場合の候補提示・ユーザーによる取捨の流れをユーザーが決める。
+
+### PHY-P-12 部品の表裏を描画でどう扱うか
+
+- 関連仕様: [PHYレイヤー](../PHYレイヤー.md)「部品ノード」
+- 未決事項: エディタ上で表裏の描き分けが必要か。必要なら `@` 始まりの予約グループ名だけで足りるか。
+- 保留できる理由: 表裏を描き分けなくても配置は編集でき、実装面はPCB設計ツール側で決められる。
+- 再開条件: 部品ノードと予約グループ名による描画を試作し、表示を評価するとき。
+- 完了条件: 描き分けの要否を確認し、必要なら実装面の指定と混同しない表示方法を決める。
+
+### PHY-P-13 reframeと通常の移動・回転をエディタ上でどう区別するか
+
+- 関連仕様: [PHYレイヤー](../PHYレイヤー.md)「クラスターの組み替え」
+- 未決事項: reframeの操作系。クラスターへのフォーカス状態に紐づけて原点ハンドルと通常のハンドルを分ける案と、専用モードを設ける案がある。
+- 保留できる理由: データ変換は定義済みで、通常の移動・回転とは別の明示的な操作として試作できる。
+- 再開条件: クラスター編集を試作し、操作の分かりやすさを評価するとき。
+- 完了条件: 配下が追随する操作と絶対配置を保つ操作を区別できる操作系をユーザーが決める。
+
+### PHY-P-14 クラスター原点の吸着先
+
+- 関連仕様: [PHYレイヤー](../PHYレイヤー.md)「クラスターの組み替え」
+- 未決事項: 吸着が必要か。候補はキーのローカル原点(左上角)・キー中心・境界矩形の角と中心で、相対グリッドとは別の機構になる。
+- 保留できる理由: 数値入力だけで原点移動は成立する。
+- 再開条件: 原点移動を試作し、操作性を評価するとき。
+- 完了条件: 吸着の要否と、必要な場合の候補を決める。
+
+## ELC
+
+### ELC-P-1 光学スイッチの端子構成
+
+- 関連仕様: [ELCレイヤー](../ELCレイヤー.md)「キーの端子」
+- 未決事項: 発光側と受光側が独立した端子を持つのか、接点と同じ2端子として扱えるのか。
+- 保留できる理由: 光学スイッチを対応範囲から外したまま、接点・アナログの配線を扱える。
+- 再開条件: 光学スイッチの配線に対応するとき。
+- 完了条件: 実在のPCBの回路図で端子数と配線の形を確認し、必要な端子構成を定める。
+
+### ELC-P-2 複数マルチプレクサ構成の作り
+
+- 関連仕様: [ELCレイヤー](../ELCレイヤー.md)「ピンとピン提供者」
+- 未決事項: 選択ピンを共有して共通ピンを分ける構成と、enableで切り替える構成の実配線・制御方法。
+  どちらが一般的かは未確認。前者は複数providerの `select` に同じ `PinRef` を書く形で表現できる。
+- 保留できる理由: providerごとの参照を保存する形は維持でき、複数muxの走査出力を検証済みの構成に限定できる。
+- 再開条件: 複数muxを使う構成のファームウェア出力に対応するとき。
+- 完了条件: 実在のキーボードの配線でピン共有とenableの使い方を確認し、現行モデルでの表現と必要な制御を確かめる。
+
+### ELC-P-3 方式ごとの走査設定の確認
+
+- 関連仕様: [ELCレイヤー](../ELCレイヤー.md)「配線トポロジを区分として持たない」
+- 未決事項: 各方式で出力器が決められる走査方法と、ユーザーの追加指定が必要になる範囲。
+  接点マトリクスではダイオードの向き、directでは電源レールの参照から役割を判断できる範囲を確認する。
+- 保留できる理由: 走査方向の決定・追加指定の責任は出力器側と決まり、ELCの配線保存はそのまま進められる。
+- 再開条件: 各方式のファームウェア出力に着手するとき。
+- 完了条件: 対象方式の配線と整合する走査方法を確認し、必要な出力設定と対応範囲を定める。
+  全方式で走査手順が一意に決まることの証明は求めない。
+
+## IDX
+
+### IDX-P-1 単一のorderから既存コミュニティレイアウトの並びを得られる範囲
+
+- 関連仕様: [IDXレイヤー](../IDXレイヤー.md)「レイアウトバリアント」
+- 未決事項: 採用済みの方式で既存コミュニティレイアウトの要求順を再現できる範囲の実測。
+  同じPHYキーIDを使う共通キー同士の要求順がレイアウト間で逆転する場合は、単一の `order` からの取捨では表せないが、その実例の有無は未確認。
+- 保留できる理由: 全バリアントのキーを別々の要素として並べ、選択後に番号を詰める仕様は決定済み。
+  既存レイアウト全般との互換性を前提にせず実装できる。
+- 再開条件: 既存コミュニティレイアウトとの互換出力を検証するとき。
+- 完了条件: 実データのキーを共通キーとバリアント別のPHYキーに対応づけ、全体の `order` から各レイアウトの要求順を取捨で再現できるか確認する。
+  再現できないものが残る場合は、対応範囲と扱いを決める。
+
+## MAP
+
+### MAP-P-4 ON/OFF以外の入力への割り当て
+
+- 関連仕様: [MAPレイヤー](../MAPレイヤー.md)「MAPデータと他レイヤーの関係」、[PHYレイヤー](../PHYレイヤー.md)「部品ノード」
+- 未決事項: ロータリーエンコーダの回転のように、ON/OFFのキーではない入力へ割り当てる方法。
+  MAPはPHYのキーIDを参照するが、エンコーダはPHYで部品ノードとして置かれる。
+  参照先の種類、入力ごとの割り当て先(回転方向など)、VIAでの読み書きの対象にするかが未定。
+  アナログ値の解釈の所属は[全体方針のP-1](../keyboard-design-layers.md#p-1-アナログ値の解釈をどの層が持つか)で扱い、この項目とは分ける。
+- 保留できる理由: キーへの割り当てと実機との読み書きは、キー以外の入力を扱わなくても実装できる。
+- 再開条件: エンコーダ等を載せたキーボードの割り当てをMAPで扱うとき。
+- 完了条件: 対象とする入力の種類と、MAPからの参照方法・保存形式をユーザーが決め、VIAで読み書きする場合は必要なコマンドを確認する。
+
+### MAP-P-5 キーコードを表示するOS配列
+
+- 関連仕様: [MAPレイヤー](../MAPレイヤー.md)「持たないもの」、[HSTレイヤー](../HSTレイヤー.md)
+- 未決事項: MAPエディタがキーコードをどのOS配列の文字で表示するか。HSTのどのプロファイルを使うか。
+  少なくともUS/JISの切り替えは欲しい。利用者が増えれば他言語への対応も求められる。
+- 保留できる理由: キーコードの割り当てと実機との読み書きは、表示に使うOS配列と独立して実装できる。
+- 再開条件: MAPエディタの表示を実装するとき、またはHSTの[P-2](../HSTレイヤー.md#p-2-対象ホストを複数持つか)を決めるとき。
+- 完了条件: 表示に使うHSTプロファイルの指定方法と置き場所をユーザーが決める。
+
+### MAP-P-6 QMKのdevelopブランチ・Community Modulesへの対応
+
+- 関連仕様: [MAPレイヤー](../MAPレイヤー.md)「DynamicとStatic」
+- 未決事項: 当面非対応としたdevelopブランチの機能とCommunity Modules(VIAモジュール以外)を、DynamicとStaticの対象に含めるか。
+  含める場合、developブランチのコミットの指定方法と、UIでの対応バージョンの示し方。
+- 保留できる理由: QMK本家masterの公式機能だけで、Dynamicの読み書きとStaticの生成を実装できる。
+- 再開条件: masterの機能だけでは足りない動作や設定が必要になったとき。
+  または、VIAのモジュール移行([qmk_firmware#26315](https://github.com/qmk/qmk_firmware/pull/26315))がdevelopに入ったとき。
+  VIAモジュールへの対応はmasterに入る前に済ませる([MAPレイヤー「DynamicとStatic」](../MAPレイヤー.md#dynamicとstatic))。
+- 完了条件: 対象に含める範囲と、対応バージョンの管理方法をユーザーが決める。
+
+### MAP-P-7 再ビルド時に実機の調整を失わないワークフロー
+
+- 関連仕様: [MAPレイヤー](../MAPレイヤー.md)「DynamicとStatic」、[MAPのP-3](../MAPレイヤー.md#p-3-プロジェクトと実機の対応状態管理)
+- 未決事項: QMK本家のVIAは、実機に保存したVIAのデータ(キーマップ・マクロ・layout option)を、ビルド日時をもとにした値で検証し、一致しなければ初期化する(`quantum/via.c` の `via_eeprom_is_valid()`。実機では未検証)。
+  再ビルドしたファームウェアを書き込む前に、実機の調整をプロジェクトへ読み出す手順を、ワークフローでどう保証するか。警告、読み出しの強制、Firmware Generatorとの連携などが候補。
+- 保留できる理由: 実機からの読み出しとStaticの初期キーマップへの反映はすでに仕様にある。手作業の手順で運用できる。
+- 再開条件: Firmware Generatorでの書き込みや、プロジェクトと実機の状態管理(P-3)を設計するとき。
+- 完了条件: 再ビルドの前に実機の調整を取り込めるワークフローをユーザーが決め、書き込み後にVIAのデータが初期化されることを実機で確認する。
+
+### MAP-P-8 QMK以外のファームウェアでのキーコード表記
+
+- 関連仕様: [MAPレイヤー](../MAPレイヤー.md)「MAPデータと他レイヤーの関係」、[全体方針のFirmware Generator](../keyboard-design-layers.md#firmware-generator)
+- 未決事項: MAPはQMKのキーコード表記を基本とする。KMK等のQMK以外のファームウェアへ出力するとき、QMK表記から変換するか、共通の表記を別に設けるか。
+- 保留できる理由: 当面の対象ファームウェアはQMKだけで、QMK表記のまま保存・読み書き・出力できる。
+- 再開条件: QMK以外のファームウェアへの出力や、実機との通信に着手するとき。
+- 完了条件: QMK以外のファームウェアで使うキーコードの表現と、QMK表記との対応方法をユーザーが決める。
+
+### MAP-P-9 Cコードの生成とユーザーのCの組み込み
+
+- 関連仕様: [MAPレイヤー](../MAPレイヤー.md)「MAPデータと他レイヤーの関係」「DynamicとStatic」、[全体方針のFirmware Generator](../keyboard-design-layers.md#firmware-generator)
+- 未決事項: QMKのkeymap.jsonでは、タップダンス・コンボ・キーオーバーライドや、キーごとの設定(`get_tapping_term` 等のコールバック)を表現できない。
+  JSONを正本にしたままこれらをCとして生成する方法と、ユーザーが用意したC/hで一部を上書きする方法。
+  QMKのコールバックは1つの関数として定義するため、生成したCとユーザーのCが同じ関数を定義するとビルドできない。候補:
+    - 生成した関数の先頭でユーザー用のフックを呼び、フックが処理しなかった場合はJSONの値を使う(有力)
+    - ユーザーが引き受ける関数をJSONまたはhのプロトタイプで宣言し、Generatorはその関数を出力しない
+  `ACTION_TAP_DANCE_FN*` やリーダーキーのように、本質的にCで書く動作をJSONから参照する方法も含む。
+  MAPの「キーマップ固有のコードには原則として対応しない」との関係も整理する。
+- 保留できる理由: レイヤー別の割り当てとVIAでの読み書きは、keymap.jsonで表現できる範囲だけで実装できる。
+- 再開条件: Firmware Generatorでタップダンス・コンボ・キーごとの設定等を出力するとき、またはP-1で動作定義とキーごとの設定の保存形式を決めるとき。
+- 完了条件: 生成するCの構成と、ユーザーのC/hを組み込む方法をユーザーが決め、両方を含む構成でQMKのビルドが通ることを確認する。
@@ -13,16 +13,41 @@ PHYの正本は相対座標の木だが、既存エディタ(KLE, kle-ng)の移

 ### テストケース

-1. **60% ANSI** - 標準的なレイアウト
-2. **Split keyboard** - 左右分離型
-3. **Ergonomic layout** - カラムスタッガード + 回転
-4. **Macro pad** - シンプルな4x4
+入力はKLE JSONとし、取り込みを通してPHYへ変換する。
+
+| ケース | サンプル | 主に確かめること |
+|---|---|---|
+| 60% | Cr0wn60 | 行スタッガード、幅の違うキー、左右対称配列の中央の隙間 |
+| 分割 | crkbd、jisplit89 | 左右の分離、カラムスタッガードと回転した親指キー(crkbd)、キー数の多いJIS配列の分割(jisplit89) |
+| 分割 + バリアント | Kyria、Iris Rev.7 | 回転したクラスター内のバリアント(Kyria)、部品(エンコーダ)を含む3択のバリアント(Iris Rev.7) |
+| マクロパッド | 4x4 | 最小構成 |
+| charlieplexing | Cr0wn60(VIA定義) | 行と列が同じピンを共有する配線を、ELCの接続先で表せるか |
+
+リポジトリに置くサンプルは `samples/` にある。
+
+- `kle/cr0wn60.json`: [EwdErna/Cr0wn60](https://github.com/EwdErna/Cr0wn60) の `keyboard-layout.json`(919cc9e、MIT)
+- `via/cr0wn60.json`: 同リポジトリの `cr0wn60-via.json`。ラベルにマトリクス位置を持つ
+- `kle/macropad-4x4.json`: このリポジトリで作成
+
+Cr0wn60はcharlieplexingで、行と列に同じ9本のピンを割り当て、使わない位置をマスクしている。
+ピンの割り当ては、ファームウェア [EwdErna/qmk_firmware](https://github.com/EwdErna/qmk_firmware) の
+`dev/ewderna_22` ブランチ(68d9249)の `keyboards/ewderna/cr0wn/cr0wn60/` にある
+(`info.json` の `matrix_pins`、`cr0wn60.c` の `matrix_mask`)。
+
+その他はコピーせず、[the-via/keyboards](https://github.com/the-via/keyboards)(GPL-3.0)から、コミット 9e3e9f4 の次のファイルの `layouts.keymap` を取得して使う。
+
+- crkbd: `src/crkbd/crkbd.json`
+- jisplit89: `src/jisplit89/jisplit89.json`
+- Kyria: `src/splitkb/kyria.json`
+- Iris Rev.7: `src/keebio/iris/iris-rev7.json`
+
+VIAの定義に含まれるKLE JSONは、ラベルにキー名ではなくマトリクス位置(`行,列`)を持つ。
+バリアントは、ラベルの別の欄に `選択肢の番号,候補の番号` の形で示す。
+キー名のラベルによる照合の検証には使えない。ELCの接続先とバリアントの検証に使う。

 ### データ例

-以下は旧形式(`keys` 配列、`position` / `size.width`)で書かれており、現行のPHYスキーマ(`phase1-json-schema.md`)に合わせた変換が必要。
-
-#### 60% ANSI PHY Layer
+#### 60% ANSI PHY Layer (抜粋)

 ```json
 {
@@ -38,20 +63,22 @@ PHYの正本は相対座標の木だが、既存エディタ(KLE, kle-ng)の移
      "unitSize": { "x": 19.05, "y": 19.05 }
    }
  ],
-  "keys": [
-    // Escape key
+  "root": [
    {
-      "id": "k00", "profile": "standard",
-      "position": { "x": 0, "y": 0 },
-      "size": { "width": 1, "height": 1 },
-      "metadata": { "label": "Esc" }
+      "type": "key",
+      "id": "k00",
+      "profile": "standard",
+      "transform": { "x": 0, "y": 0, "rotation": 0 },
+      "size": { "w": 1, "h": 1 },
+      "labels": ["Esc"]
    },
-    // Space bar
    {
-      "id": "k60", "profile": "standard", 
-      "position": { "x": 5, "y": 4 },
-      "size": { "width": 6.25, "height": 1 },
-      "metadata": { "label": "Space" }
+      "type": "key",
+      "id": "k60",
+      "profile": "standard",
+      "transform": { "x": 5, "y": 4, "rotation": 0 },
+      "size": { "w": 6.25, "h": 1 },
+      "labels": ["Space"]
    }
  ]
 }
@@ -0,0 +1,44 @@
+# 保留課題をbacklogへ分離する
+
+## 結論
+
+文書を、現行仕様・保留課題・検討履歴の3種類に分ける。
+後回しにできる問い・検証・改善候補はbacklog/README.mdにまとめる。
+現在の仕様が依存する未確認の前提は、引き続き仕様書の末尾に残す。
+
+## 案の比較
+
+| 置き場 | 判断 |
+| --- | --- |
+| 各仕様書の未確認事項にすべて残す | 現行実装の前提と、将来考えればよい課題が混ざる |
+| journalへ移す | 結論反映後に削除できる履歴と、再開まで残す課題では寿命が異なる |
+| 直下にbacklog.mdを置く | 直下へ追加したくないというユーザーの意向で採らない |
+| backlog/README.mdへまとめる | 採用。役割をフォルダで区別し、必要になれば分割できる |
+
+## 運用の意図
+
+既存ルールの狙いは、採用した仕様に過去の検討を混ぜず、未確認の前提を事実と誤認して実装しないこと。
+保留課題は現在の仕様でも解決済みの履歴でもないため、第3の文書種別として扱う。
+
+移動の基準は未確認かどうかではなく、現在の実装がその答えに依存するかどうか。
+保留中の対応範囲・暫定仕様は仕様書に明記し、その範囲で進められる問いだけを移す。
+backlogへの移動自体は、仮説の採用や実装の許可を意味しない。
+
+各項目は元の番号にレイヤー名を付け、関連仕様・未決事項・保留理由・再開条件・完了条件を持つ。
+再開条件で「いつ考え直すか」を、完了条件で「何を確認または決定すれば終わるか」を残す。
+事実確認と設計上の意思決定をともに「格上げ」と呼ぶことはやめる。
+解決または取り下げた項目は削除し、完了済み課題の一覧は作らない。
+
+仕様書側の「保留課題」は、対応するbacklogの区分へのリンク箇条書きだけに固定した。
+問いの要約や項目名の列挙を重ねると片方だけ古くなるため、詳細はbacklogで一元管理する。
+末尾は保留課題・検討済み非採用・未確認事項の順とし、空の保留課題セクションは残さない。
+
+## 適用範囲
+
+PHY・ELC・IDXの10件を整理した。ELC-P-3は責任分担の決定後に残る方式別の確認として扱い、
+IDX-P-1は別途決定済みの仕様を維持して既存レイアウトとの互換性の実測だけを残した。
+実機確認や既存コミュニティレイアウトの再調査は行っていない。
+他の既存文書の全体再編は、この変更には含めない。
+
+doc-lintもルール5に対応させる。backlogを検査対象に加え、項目の必須欄、
+仕様書側の固定書式と参照先、事実確認と設計判断の完了条件を検査する。
@@ -0,0 +1,29 @@
+# ELCの走査設定を出力器に置く
+
+## 結論
+
+ELCは配線を保存し、走査方向の決定と追加指定はFirmware Generatorの出力設定に置く。
+接点マトリクスでいう走査方向は、どちら側のピン群を駆動して、どちら側から読み取るか。
+全方式で走査手順が配線から一意に決まることは、ELCの成立条件にしない。
+
+## 案の比較
+
+| 案 | 判断 |
+| --- | --- |
+| 全方式で配線から走査手順を一意に導出できることを先に検証する | 配線保存の実装まで止める条件としては強すぎる |
+| ELCに走査方向の指定を持たせる | 配線と出力時の選択の責任が混ざるため採らない |
+| 出力器が走査方向を選び、必要なら出力設定で指定を受ける | 採用。ELCの責任を配線に保てる |
+
+## 判断の根拠と残件
+
+旧ELC P-3は「端子の接続先とダイオードの向きだけから走査手順が一意に決まるか」を格上げ条件にしていた。
+しかし、複数の適切な方法から出力器が選べるなら、一意性は必要ない。
+先に決める必要があったのは、配線だけでは決まらない場合の指定をどこが受け持つかである。
+
+この変更は責任分担の決定であり、各方式の実配線や走査方法を新たに検証した結果ではない。
+出力器は配線・ダイオードの向きと整合する方法を選び、必要な追加指定は出力設定から受け取る。
+未対応の構成は出力しない。
+
+方式ごとの導出可能な範囲と必要な追加設定は、その方式の出力に着手するときに確認する。
+残件はbacklogのELC-P-3「方式ごとの走査設定の確認」に引き継いだ。
+PHYの編集やELCの配線保存は、この確認に依存せず進められる。
@@ -0,0 +1,38 @@
+# IDXの全体の並びとバリアント選択後の出力番号
+
+## 結論
+
+IDXは全バリアントの対象キーを `order: string[]` に持つ。同じ配線を使う排他キーも別々に並べる。
+出力時に選択した構成のキーだけを残し、残った並びの位置を0から連続する出力番号とする。
+保存したorderは変更しない。公開番号の互換性は出力レイアウトごとに扱う。
+ユーザーがこの方針を採用した。
+
+## 案の比較
+
+| 案 | 扱い |
+| --- | --- |
+| 1つのorderに全キーを置き、出力時に取捨して詰める | 採用 |
+| 同じ配線の排他キーは番号を共有し、選択後も番号を詰めない | 今回置き換えた旧仕様 |
+| レイアウトごとに独立したIDXを保存する | 採用しない |
+
+## 決定理由と例
+
+ユーザーは、ANSIのバックスラッシュとISOの # が同じ配線を使っても、IDXでは別々の位置を持つことを希望した。
+QとAが共通キーなら、全体のorderを `Q, backslash, A, hash` と置くことで、
+ANSIでは `Q, backslash, A`、ISOでは `Q, A, hash` を取捨だけで得られる。
+ISO出力の番号は0, 1, 2であり、保存したorderでの位置0, 2, 3とは区別する。
+
+旧仕様は、全バリアントを含む番号と配線の対応表に同じ接続先が重複することを理由に、番号共有を必須としていた。
+今回の出力単位はバリアント選択済みの構成であり、排他キーは同時に残らないため、その理由は当てはまらない。
+全バリアントを一度に含むキー番号の対応表は、今回の出力方式には含めない。
+
+MAPはPHYキーIDへの割り当てを保持する。出力時に配線の対応表とMAPの配列へ同じ選択後の並びを適用する。
+ELCの保存データは全バリアントの配線を保持し、LEDチェーンも選択によって取捨・詰め直しをしない。
+
+## 未検証の範囲
+
+例での解消は、既存コミュニティレイアウト全般に対応できることの検証ではない。
+従来の実データ調査は、既存のLAYOUT_all等の並びから他の並びを取捨できるかを調べたものだった。
+今回の、別々のPHYキーIDを使って全体のorderを構成する方式については改めて確認が必要。
+共通キー同士の要求順がレイアウト間で逆転する場合には単一のorderで表せない。
+その実例の有無と互換出力の対応範囲を、IDX P-1の残余として残す。
@@ -0,0 +1,46 @@
+# MAPエディタの実機との往復とVIA対応
+
+## 結論
+
+新規作成するキーボードのワークフローを主眼とし、MAPエディタは実機の読み書きを一組で提供する。
+最初の通信プロトコルはVIA。対応プロトコルを絞り、段階的に増やす。
+独自プロトコルの追加や、そのためのQMK・Vial等のフォークは行わない。
+高度な動作定義、Staticの対応範囲、同期方式はまだ決めていない。
+
+## 案の比較
+
+| 案 | 扱い |
+| --- | --- |
+| 既存プロトコルで実機の読み書きを提供し、VIAから始める | 採用 |
+| MAPエディタをStaticに閉じる | 採用しない |
+| Dynamicの対応範囲を読み出しだけに限定する | ユーザーが読み書きの両対応を指定 |
+| 独自プロトコルのためにファームウェアをフォークする | ユーザーが意図しないと明示 |
+
+## 判断の根拠
+
+ユーザーは、既存キーボード全般への対応よりも、新しく作るキーボードのワークフローを重視している。
+VIAを話すなら読み書きの両方を提供し、利用者が好むRemapと同じ通信経路から始める方針となった。
+当初のアシスタントによる「互換性」の説明はファイル変換に寄りすぎており、実機との通信を中心に修正した。
+VIA向けのキーボード定義生成と、MAPの割り当ての読み書きは別の責務として整理した。
+
+## 調査で確認した範囲
+
+公式文書・実装を参照した。実機による読み書きの検証は行っていない。
+
+- RemapはWebHIDを使い、QMKのVIAクライアント向け機能へアクセスする。Workbenchにはソース編集・ビルド・書き込みもある。
+  参照: https://github.com/remap-keys/remap#references
+  参照: https://remap-keys.app/docs/workbench
+- VIAのキーボード定義には配置とmatrix座標の対応がある。QMKのVIA実装はキー単位の読み書きにlayer・row・colを使う。
+  参照: https://caniusevia.com/docs/specification/
+  参照: https://github.com/qmk/qmk_firmware/blob/master/quantum/via.c
+- Vialではタップダンスやコンボを実機へ保存できるが、枠数等にはビルド時の制約がある。
+  参照: https://get.vial.today/manual/tap-dance.html
+  参照: https://get.vial.today/manual/combos.html
+- ZMK Studioは既存behaviorの割り当てを変更できるが、新しいbehavior定義等は対象外。実機に保存した変更とソース側の設定の扱いにも注意が必要。
+  参照: https://zmk.dev/docs/features/studio
+
+## 未採用の提案との区別
+
+共通の動作モデル、ファームウェア固有表現の保持、Staticを先に実装する順序、差分を選んで反映するUIは、
+アシスタントの提案段階にとどまる。今回の合意として固定しない。
+Vial・ZMK Studioを次にどの順序で実装するかも決めていない。
@@ -0,0 +1,89 @@
+# QMKでのDynamic/Staticの対応範囲
+
+## 結論
+
+当面の対象ファームウェアはQMK。
+- Dynamic: QMK本家のVIAプロトコルが公開する項目のみ
+- Static: QMK本家の公式機能のうちVIAで変更できないものは、Firmware Generatorで生成する対象
+- 非公式機能(Vial等のフォーク、XAP等のmaster以外のブランチ)は当面非対応
+- developブランチ・Community Modulesは当面非対応(将来広げたい→backlog MAP-P-6)。キーボード・キーマップ固有コードは原則非対応
+- 対応QMKは特定コミットに固定し、更新タイミングはユーザーが個別に判断する
+- UIにはVIAプロトコルとキーコード体系のバージョンを表示し、実機とはこの2つで照合。不一致の実機は非対応
+  (当初はUIにコミットを出す案だったが、実機から取れるのがこの2つだけなのでユーザーがバージョン表記に変更)
+- Staticで定義する動作(タップダンス等)はキーから名前で参照し、出力時に番号へ変換する
+- VIA管理外のEEPROM設定は読み出せない旨を制約として明記
+
+どこまでを初期対応するか(P-1)、最初に対応するコミット(P-2)は未決。
+
+## 案の比較
+
+| 案 | 扱い |
+| --- | --- |
+| DynamicはQMK本家VIAのみ、他の公式機能はStatic | 採用(ユーザー指定) |
+| VialでDynamicの範囲を広げる(タップダンス・コンボ・QMK Settings等) | 当面非対応(フォークのため) |
+| XAP | 当面非対応(master外) |
+| QMKの最新へ自動追従 | 採用しない。ユーザーが恣意的に更新時期を決める |
+
+## 調査結果(2026-09-23時点のソース)
+
+実機での検証はしていない。
+
+### A. QMK本家 VIA
+参照: https://raw.githubusercontent.com/qmk/qmk_firmware/master/quantum/via.h
+VIA_PROTOCOL_VERSION = 0x000D
+
+command:
+- 0x01 get_protocol_version
+- 0x02/0x03 get/set_keyboard_value
+  - 0x01 uptime(get), 0x02 layout_options(get/set), 0x03 switch_matrix_state(get),
+    0x04 firmware_version(get), 0x05 device_indication(set), 0x06 keycodes_version(get)
+- 0x04/0x05 dynamic_keymap_get/set_keycode (layer,row,col)
+- 0x06 dynamic_keymap_reset
+- 0x07/0x08/0x09 custom_set/get_value, custom_save
+  - channel 0 custom(キーボード独自メニュー)
+  - 1 backlight: brightness, effect
+  - 2 rgblight: brightness, effect, effect_speed, color
+  - 3 rgb_matrix: brightness, effect, effect_speed, color
+  - 4 audio: enable, clicky_enable
+  - 5 led_matrix: brightness, effect, effect_speed
+- 0x0A eeprom_reset
+- 0x0B bootloader_jump
+- 0x0C..0x10 dynamic_keymap_macro_get_count / get_buffer_size / get_buffer / set_buffer / reset
+- 0x11 dynamic_keymap_get_layer_count
+- 0x12/0x13 dynamic_keymap_get/set_buffer
+- 0x14/0x15 dynamic_keymap_get/set_encoder
+
+MAPに関係するもの: キーコード、レイヤー数、エンコーダ、マクロ、layout_options。
+照明・オーディオはMAPの所有データ外(MAPレイヤー.md「持たないもの」)。
+
+### B. Vial(フォーク、今回非対応)
+参照: https://raw.githubusercontent.com/vial-kb/vial-qmk/vial/quantum/vial.h
+参照: https://raw.githubusercontent.com/vial-kb/vial-qmk/vial/quantum/qmk_settings.c
+VIAL_PROTOCOL_VERSION = 6
+
+- keyboard_id、圧縮キーボード定義JSONの取得(get_size/get_def)
+- unlock/lock(物理キー押下による解除)
+- dynamic entry: tap dance, combo, key override, alt repeat key
+- 拡張マクロ(EXT_TAP/DOWN/UP)
+- QMK Settings (QSID):
+  1 grave_esc_override, 2 combo_term, 3 auto_shift, 4 auto_shift_timeout,
+  5 osk_tap_toggle, 6 osk_timeout, 7 tapping_term, 9-17 mousekey各種(MK_3_SPEED以外),
+  18 tap_code_delay, 19 tap_hold_caps_delay, 20 tapping_toggle,
+  21 magic_settings(Ctrl/Caps, Alt/GUI, Ctrl/GUI, Grave/Esc, BSpc/BSlash入替, GUI無効, NKRO),
+  22 permissive_hold, 23 hold_on_other_key_press, 24 retro_tapping,
+  25 quick_tap_term, 26 chordal_hold, 27 flow_tap_term
+- VialRGB(RGB Matrixエフェクト列挙・設定)。ソース未確認
+
+### C. プロトコル外で実機上だけ変わるもの(Dynamicの定義外)
+当初「すべてEEPROMに保存される」と書いたが誤り。確認結果:
+- 保存されない(再起動で消える): ダイナミックマクロ(docs/features/dynamic_macros.md
+  "lost when the keyboard is unplugged or otherwise rebooted")、DT_UP/DT_DOWN(docs/tap_hold.md "*not* persistent")
+- EEPROMに保存される(quantum/eeconfig.h): keymap config(Magic)、default layer、unicode mode、audio、backlight、
+  rgblight/rgb_matrix/led_matrix、haptic、steno mode、handedness、connection、kb/user固有データ
+- QMK本家via.cにはこれらを読み出すコマンドがない。照明・オーディオはcustom channel 1〜5で読めるがMAPの所有外。
+  custom channel 0はweakの via_custom_value_command_kb() へ流れる(キーボード固有コード、原則非対応)。
+- 参考: via_eeprom_is_valid() はビルド日時由来のmagicで検証し、不一致ならVIAのデータ(キーマップ・マクロ・layout options)を
+  初期化する。再ビルドして書き込むとDynamicの変更は消える前提になる。
+
+### XAP
+QMK公式の次世代プロトコルとして開発されていたが、masterには入っていない認識。未確認。
@@ -0,0 +1,29 @@
+# GeneratorのC出力とユーザーのCによる上書き
+
+## 結論
+
+未決。backlog MAP-P-9 として保留(ユーザー指定)。フック方式が有力(ユーザー「フック方式いいかも」)。
+JSONを第一級にしてCを自動生成し、ユーザーのC/hで一部を上書きできるようにしたい、というのがユーザーの意向。
+
+## 案の比較
+
+| 案 | 内容 | 所見 |
+| --- | --- | --- |
+| (b) フック | 生成関数の先頭でユーザーのフックを呼び、未処理ならJSONの値 | キー単位の例外だけ書ける。JSONが正本のまま |
+| (a) 関数ごと置き換え(JSONで宣言) | 宣言された関数はGeneratorが出力しない | 単純。その関数の範囲ではJSONの値が無効になる |
+| (a') 関数ごと置き換え(hのプロトタイプで宣言) | ユーザーのhにあるプロトタイプの関数を出力しない(ユーザー案) | (a)と同じ性質。Generatorがhを解析する必要 |
+| weak属性で上書き | 生成側をweakにしてユーザーの定義で上書き | 使えない(下記) |
+| ユーザーのCを解析して自動判定 | — | 壊れやすい |
+
+## 根拠(QMK 0.34.4)
+
+- keymap.jsonで書けるもの: keyboard, keymap, layout, layers, encoders, dip_switches, macros, keycodes(名前宣言), config, modules,
+  host_language 等(data/schemas/keymap.jsonschema)。タップダンス・コンボ・キーオーバーライド・キーごとの設定はない。
+- キーごとの設定は `*_PER_KEY` を定義した上での `get_tapping_term(keycode, record)` 等のコールバック。keyrecordを受けるので
+  キーコード単位でも位置単位でも書ける。
+- keymap.jsonとkeymap.cを並べると、json2cで生成したkeymap.cがユーザーのkeymap.cを取り込む
+  (builddefs/build_keyboard.mk:148-157、OTHER_KEYMAP_C)。QMK自体がJSON + ユーザーCの共存に対応している。
+- 取り込みは同一翻訳単位なので、生成側weak + ユーザー側strongは再定義エラーになる。QMK本体のweak既定実装もあるため、
+  別ファイルにしても生成側をweakにする方式は選ばれる定義が不定。
+- プロトタイプの再宣言はCでは合法(同一シグネチャなら何度でも)。QMKが宣言済みの関数をユーザーのhに書いてもよい。
+  シグネチャ違いはコンパイルエラーになるので検出にも使える。
@@ -0,0 +1,35 @@
+# IMEレイヤーの再定義(HST)と線引き
+
+## 結論
+
+- IMEレイヤーをHST(ホスト)レイヤーに改める。役割は、ホストがキーコードをどう解釈するかの記述。IMEの変換はOSの仕事で対象外。
+- データは、ホスト環境ごとのプロファイルを集めた共有カタログ。キーボードに依存しない。プロジェクトはプロファイルのIDと差分だけを持つ。
+- 識別はOS×ホスト配列(+必要なら入力方式)。`win-jp` などはプリセット名。
+- プロファイルは順方向の表 f(キーコード, 修飾キー, ホスト状態) → 文字/動作/未定義/不明、成立の前提、対応可否(3値)だけを持つ。
+- 逆引き・候補の生成・ファームウェアでの実現はMAPエディタとGeneratorが行う。ユーザーは、これが実現できるかに不安がある → HSTのP-1。
+- MAPはキーコードを保存する。逆引きは入力補助で、一方向の変換。
+- 複数ホストの扱いは未決 → HSTのP-2。
+
+## 案の比較
+
+| 論点 | 当初の提案(人との議論) | Claude | Codex | 採用 |
+|---|---|---|---|---|
+| 名前 | SYS | HOST/HST | SYS → 最終的にHOST/HSTに同意 | HST |
+| 識別子 | WIN-JAP (OS×言語) | OS×配列の構造 | OS×配列×入力方式+プロファイル名 | OS×配列(+入力方式) |
+| 範囲 | OS・言語ごとのキーの振る舞い・表示 | ホストの解釈の記述 | 意図を環境ごとの出力に変換、まで候補 → 最終的に「対応関係を提供、変更はしない」 | 記述のみ |
+| 逆引き | - | 使う側で順方向の表から求める | 候補と成立条件をプロファイルが持つ | 使う側 |
+| ホスト状態 | - | 関数の引数として記述 | 設定と実行時の状態を分ける | 両方(矛盾しない) |
+
+## 根拠・経緯
+
+- SYSは、HIDのSystem Control用途ページ(電源・スリープ)や「システム設定全般」と紛らわしい。hostはHIDでキーボードの接続相手を指す用語で、QMKも「host keyboard layout」と呼ぶ。
+- 言語は軸として誤り: 日本語Windowsで英語配列を使える。MacではUS/JISが入力ソースとキーボード種別で決まる。XKBはlayout/variant/optionsの3要素。
+  「英語」にもUS・UKがある。`JAP` はISOコードでもない(ja/jpn)。
+- 逆引きをプロファイルに持たせない理由: (1) 順方向の表から導けるので二重管理になる。
+  (2) 候補がファームウェアの機能に依存する。例: US刻印+JISホストでShiftの組が合わないキーにはKey Overrideが要る。HSTにQMKの知識が混ざる。
+- Codexの指摘で採用したもの: 表示の切り替えと送信内容の変更を混ぜない。知らない動作を「使えない」と扱わない(対応可否を3値にする)。OS設定への依存は記述する。
+- MAPの正本をキーコードにする理由の修正: Claudeは当初「VIAでは実機にキーコードしか残らず、意図を復元できないので、キーコードでなければならない」とした。
+  Codexが、意図をプロジェクト側に残す設計も可能で、難しくなるのは実機で変更された値の取り込みだけだと反論し、これが正しい。
+  採用する理由は「実機との往復を単純に保てるから」とする。
+- 「コピー」のような操作の辞書は、アプリやユーザー設定まで相手が広がるので対象外。
+- 未採用のアイデア: キートップの刻印生成にHSTを使う(PHYのラベルへ流す)。検討していないので仕様には書かない。
@@ -0,0 +1,162 @@
+# QMK 0.34.4 の機能棚卸し(MAP P-2 の下調べ)
+
+## 結論
+
+- 対象: QMK `0.34.4`(tag, commit `08c662f286ddfd12a985f57b584b02eca5af0ae6`, 2026-09-05)。masterの最新リリース。
+  ユーザーが最初の対応環境として0.34.4を採用(2026-09-24)。
+  - キーコード体系 `QMK_KEYCODES_VERSION` = `0.0.9`(quantum/keycodes.h)
+  - `VIA_PROTOCOL_VERSION` = `0x000D`(quantum/via.h。9/23時点の調査と同じ)
+- MAPから見たQMKの機能は次の6種類に分かれる(下の表)。スキーマ・編集機能への落とし込みは未着手。
+- 既存ドキュメントに影響しうる事実が2つある:
+  1. **VIAのモジュール化**(20260830 ChangeLog「VIA Feature Migration」#26315)。VIA統合の保守をVIAチームへ移し、
+     旧来のfeature実装は将来のリリースで削除予定と告知済み。PR本体はdevelop向けのDraftで、0.34.4時点のVIAは従来の
+     `quantum/via.c`。MAPレイヤー.md は「Dynamic = QMK本家のVIA」「Community Modules は当面非対応」としているため、
+     VIAがモジュール側へ移った時点でこの2つが衝突する。
+  2. **VIAのマトリクス状態取得の無効化**(20250831 ChangeLog #25414)。`id_switch_matrix_state` は既定で全0を返す。
+     `VIA_INSECURE` 定義時、または `SECURE_ENABLE` でアンロック中のみ実値。Remap等のキーテスターは既定では動かない。
+- QMKのキーごとの設定(tapping term等)はデータテーブルではなく、keycode/keyrecordを受けるCのコールバック関数で表現される。
+  keymap.json(data-driven)で書けるのはレイヤー・エンコーダ・DIPスイッチ・マクロ・カスタムキーコード・config・modules まで。
+  タップダンス・コンボ・キーオーバーライド・キーごとの設定はCでしか書けない。
+
+## 分類の概要
+
+| 区分 | 主なもの | 実機への保存 | VIAで読み書き |
+| --- | --- | --- | --- |
+| A. キーコード(単体で完結) | 基本キー、修飾付き、MT/LT/OSM等、レイヤー操作、Magic、メディア、マウス等 | キーマップ | ○(16bit値として) |
+| B. 定義を参照するキーコード | TD(n)、QK_MACRO_n、UM/UP、QK_KB_n/QK_USER_n | 参照はキーマップ、定義はファームウェア | 参照のみ○。定義はマクロのみ○ |
+| C. キー以外の起動条件を持つ動作 | コンボ、キーオーバーライド、リーダー、オートコレクト、Tri Layer | ファームウェア | × |
+| D. タップ・ホールド等の挙動設定 | TAPPING_TERM等 + キーごとのコールバック | ファームウェア(DTTの変更は揮発) | × |
+| E. キー以外の入力への割り当て | エンコーダ、DIPスイッチ、ポインティング、ジョイスティック等 | エンコーダはキーマップ | エンコーダのみ○ |
+| F. 実機の永続状態 | Magic設定、保存されたデフォルトレイヤー、Unicodeモード等 | EEPROM | × |
+
+MAPの所有外(照明・オーディオ・ディスプレイ・ハードウェア構成)は末尾にまとめた。
+
+---
+
+## A. キーコード体系 0.0.9
+
+data/constants/keycodes/*.hjson を 0.0.1〜0.0.9 の順にマージして得た範囲。
+
+| 範囲 | 名前 | 内容 |
+| --- | --- | --- |
+| 0x0000–0x00FF | QK_BASIC | KC_NO/KC_TRNS、HID基本キー(basic 161件)、system 3、media 27、mouse 19(QK_MOUSE_*)、修飾8 |
+| 0x0100–0x1FFF | QK_MODS | `LCTL(kc)` 等。kcは基本キーのみ、修飾は5bit(左右混在不可) |
+| 0x2000–0x3FFF | QK_MOD_TAP | `MT(mod, kc)`。kcは基本キーのみ |
+| 0x4000–0x4FFF | QK_LAYER_TAP | `LT(layer, kc)`。layer 0–15、kcは基本キーのみ |
+| 0x5000–0x51FF | QK_LAYER_MOD | `LM(layer, mod)`。layer 0–15 |
+| 0x5200– | QK_TO / MOMENTARY / DEF_LAYER / TOGGLE_LAYER / ONE_SHOT_LAYER / ONE_SHOT_MOD / LAYER_TAP_TOGGLE / PERSISTENT_DEF_LAYER | TO/MO/DF/TG/OSL/OSM/TT/PDF。各32(layer 0–31) |
+| 0x5600–0x56FF | QK_SWAP_HANDS | SH_T(kc)、SH_TOGG等7件 |
+| 0x5700–0x57FF | QK_TAP_DANCE | TD(0–255) |
+| 0x7000–0x70FF | QK_MAGIC | Ctrl/Caps、Alt/GUI、Ctl/GUI、Grave/Esc、BSpc/BSlash、Esc/Caps入替、GUI無効、NKRO、EE_HANDS 等35件 |
+| 0x7100–0x71FF | QK_MIDI | ノート・オクターブ・移調・ベロシティ・チャンネル等 |
+| 0x7200–0x73FF | QK_SEQUENCER | 9件 |
+| 0x7400–0x743F | QK_JOYSTICK | ボタン0–31 |
+| 0x7440–0x747F | QK_PROGRAMMABLE_BUTTON | 1–32 |
+| 0x7480–0x74BF | QK_AUDIO | Audio/Clicky/Music 15件 |
+| 0x74C0–0x751F | QK_STENO | 0.0.9で拡張・改名(STN_* → QK_STENO_* / ST_*、旧名はエイリアス) |
+| 0x7700–0x777F | QK_MACRO | QK_MACRO_0–31(名前付き)。VIA/keymap.jsonのマクロ |
+| 0x7780–0x77BF | QK_CONNECTION | 出力先切替(USB/2.4GHz/BT)、BTプロファイル1–5等15件 |
+| 0x77C0–0x77FF | QK_COMMUNITY_MODULE | Community Modules用 |
+| 0x7800–0x78FF | QK_LIGHTING | Backlight 7、LED Matrix 11、RGBLight(underglow)11 + RGB_MODE_* 10、RGB Matrix 15 |
+| 0x7C00–0x7DFF | QK_QUANTUM | 下記 |
+| 0x7E00–0x7E3F | QK_KB | QK_KB_0–31(キーボード固有) |
+| 0x7E40–0x7FFF | QK_USER | QK_USER_0–31(キーマップ固有。SAFE_RANGE以降) |
+| 0x8000–0xFFFF | QK_UNICODE / UNICODEMAP / UNICODEMAP_PAIR | UC(cp≤0x7FFF)、UM(i)、UP(i,j) |
+
+QK_QUANTUM の内訳(73件): Bootloader/Reboot/Debug/EEPROMクリア/Make、Auto Shift操作6、Grave Escape、
+Velocikey、Space Cadet 7、Unicodeモード切替8、Haptic 13、Combo on/off/toggle、Dynamic Macro 5、Leader、
+Key Lock、One Shot on/off/toggle、Key Override on/off/toggle、Secure 4、Dynamic Tapping Term 3、Caps Word、
+Autocorrect 3、Tri Layer Lower/Upper、Repeat/Alt Repeat、Layer Lock。
+
+補足:
+- 20250831で旧RGB・マウスの非推奨キーコードを削除(#25444)。
+- VIAはキーマップを16bit値で読み書きするため、上のどの値もキーへ書ける。ファームウェアで無効な機能の値は何もしない。
+
+## B. 定義を参照するキーコード
+
+| 機能 | キーコード | 定義の中身 | 定義の置き場所 |
+| --- | --- | --- | --- |
+| Tap Dance | TD(n) | `ACTION_TAP_DANCE_DOUBLE(kc1,kc2)` / `_LAYER_MOVE(kc,layer)` / `_LAYER_TOGGLE(kc,layer)` / `_FN` / `_FN_ADVANCED` / `_FN_ADVANCED_WITH_RELEASE`。組み込みは前3つで、残りはC関数 | C(`tap_dance_actions[]`) |
+| マクロ | QK_MACRO_n | tap/down/up/delay(+keymap.jsonではbeep)と文字列。VIAの保存形式は SS_TAP/DOWN/UP/DELAY_CODE を含むバイト列 | keymap.json `macros` またはVIA(EEPROM)。VIA既定16個 |
+| Unicode Map | UM(i), UP(i,j) | コードポイント表 | C(`unicode_map[]`) |
+| 固有キーコード | QK_KB_n, QK_USER_n | 任意のC処理 | C(`process_record_*`)。keymap.json `keycodes` で名前宣言のみ可 |
+| Send String | (キーコードなし) | 文字列送信。マクロやC処理から呼ぶ | C |
+
+## C. キー以外の起動条件を持つ動作
+
+| 機能 | 定義 | 主な設定 |
+| --- | --- | --- |
+| Combos | キーコード列(最大8、EXTRA_LONGで16)→出力キーコード | COMBO_TERM、per-combo: term/must_hold/must_tap/must_press_in_order、COMBO_STRICT_TIMER、COMBO_ONLY_FROM_LAYER / COMBO_REF_DEFAULT(参照レイヤー)、Modifier Combos、キー解放・再押下の扱い |
+| Key Overrides | trigger, trigger_mods, layers(ビットマスク), negative_mod_mask, suppressed_mods, replacement, options(ko_option_t), custom_action, enabled | MODS_TO_NEUTRALIZE |
+| Leader Key | QK_LEADER の後のキー列(1〜5キー)→C処理 | LEADER_TIMEOUT、LEADER_PER_KEY_TIMING、LEADER_NO_TIMEOUT、STRICT_KEY_PROCESSING |
+| Autocorrect | 誤字→訂正の辞書(ビルド時にtrieへ変換) | 辞書ファイル、MIN/MAX_LENGTH |
+| Tri Layer | lower+upper → adjust レイヤー | 3レイヤーの番号 |
+| Caps Word / Repeat Key / Layer Lock / Key Lock / Swap Hands | 定義データはほぼなし。Swap Handsは `hand_swap_config`(マトリクス対応表)が必要 | Caps Wordの継続キー判定等はC |
+
+## D. タップ・ホールド等の挙動設定(docs/tap_hold.md 他)
+
+全体設定(config.h / keyboard.jsonのconfig)とキーごとのコールバックの組で提供される。
+
+| 設定 | 全体 | キーごと |
+| --- | --- | --- |
+| Tapping Term | TAPPING_TERM | TAPPING_TERM_PER_KEY → get_tapping_term(keycode, record) |
+| Dynamic Tapping Term | DYNAMIC_TAPPING_TERM_ENABLE(キーで増減、揮発) | — |
+| Permissive Hold | PERMISSIVE_HOLD | get_permissive_hold |
+| Hold On Other Key Press | HOLD_ON_OTHER_KEY_PRESS | get_hold_on_other_key_press |
+| Quick Tap Term | QUICK_TAP_TERM | get_quick_tap_term |
+| Flow Tap(2025-05追加) | FLOW_TAP_TERM | is_flow_tap_key、get_flow_tap_term(keycode, record, prev_keycode) |
+| Chordal Hold(2025-02追加) | CHORDAL_HOLD + 左右手の割り当て(chordal_hold_layout) | get_chordal_hold(tap_hold_keycode, …, other_keycode, …) |
+| Retro Tapping | RETRO_TAPPING | get_retro_tapping |
+| Speculative Hold(2025-11追加) | SPECULATIVE_HOLD | get_speculative_hold |
+| Tapping Force Hold | — | get_tapping_force_hold |
+| Tapping Toggle | TAPPING_TOGGLE(TTのタップ回数) | — |
+| Auto Shift | AUTO_SHIFT_TIMEOUT 等 | get_autoshift_timeout、get_auto_shifted_key、REPEAT/NO_AUTO_REPEAT_PER_KEY |
+| One Shot | ONESHOT_TAP_TOGGLE、ONESHOT_TIMEOUT | — |
+| Combo | COMBO_TERM | get_combo_term 等(コンボごと) |
+| その他 | TAP_CODE_DELAY、TAP_HOLD_CAPS_DELAY、DEBOUNCE | — |
+
+- キーごとのコールバックは keycode と keyrecord(押された位置・レイヤーを含む)を受ける。
+  つまり「キーコード単位」「物理位置単位」のどちらでも書ける(docs/tap_hold.md「Why do we include the key record」)。
+- Chordal Holdの手の割り当ては物理位置(マトリクス)単位のデータ。
+
+## E. キー以外の入力への割り当て
+
+| 機能 | MAP相当のデータ | 備考 |
+| --- | --- | --- |
+| Encoders | ENCODER_MAP: レイヤーごと・エンコーダごとの ccw/cw キーコード | keymap.json `encoders`。VIAで読み書き可(0x14/0x15) |
+| DIP Switch | DIP_SWITCH_MAP: スイッチごとの on/off キーコード | keymap.json `dip_switches`(2025-11追加)。VIA不可 |
+| Pointing Device | Auto Mouse Layer(レイヤー番号・タイムアウト)、ドラッグスクロール等はC | センサー設定はハードウェア寄り |
+| Joystick / Digitizer / MIDI / Steno / Programmable Button / Sequencer | キーコードでボタン・音等を割り当て。軸・プロトコル設定は全体 | Stenoは0.0.9でキーコード改名 |
+
+## F. 実機の永続状態(quantum/eeconfig.h)
+
+VIA管理外でEEPROMに保存されるもの: debug、keymap config(Magic: Ctrl/Caps入替、Caps→Ctrl、Alt/GUI入替、GUI無効、Grave/Esc、BSpc/BSlash、NKRO 他)、
+default layer(PDF)、Unicode入力モード、audio、backlight、rgblight/rgb_matrix/led_matrix、haptic、steno mode、
+handedness(EE_HANDS)、connection、kb/user固有データ、Community Modules の永続データ(1.1.3で追加)。
+QMK本家VIAにはこれらを読み出すコマンドがない(9/23調査の再確認)。
+
+## MAP所有外の機能(参考の一覧)
+
+- 照明: Backlight、RGBLight、RGB Matrix、LED Matrix、LED Indicators
+- 表示: OLED、Quantum Painter(LVGL含む)、ST7565、HD44780
+- 音・触覚: Audio、Haptic Feedback
+- ハードウェア構成: Split Keyboard、Custom Matrix、Debounce、Converters、PS/2 Mouse、Wireless、Battery、USBPD
+- ホスト連携: Raw HID、OS Detection、Secure、Command、Bootmagic、WPM、Deferred Exec、Virtser、Plover HID
+- 拡張: Community Modules(1.1.3。modules/qmk/ に hello_world, super_alt_tab, split_data_sync, nvm_test, flow_*_matrix_effect)
+
+## VIA 0x000D の読み書き範囲(0.34.4で再確認)
+
+9/23の journal(qmk-dynamic-scope)と同じコマンド構成。差分・補足:
+- `id_switch_matrix_state` は既定で0を返す(上記)。
+- `id_eeprom_reset` は `VIA_EEPROM_ALLOW_RESET` 定義時のみ有効。
+- エンコーダは `ENCODER_MAP_ENABLE` 時のみ。
+- 既定: DYNAMIC_KEYMAP_LAYER_COUNT 4、DYNAMIC_KEYMAP_MACRO_COUNT 16。上限はEEPROM容量に従う。
+
+## 調査方法
+
+- `git clone --depth 1 --branch 0.34.4 --filter=blob:none --sparse` で docs / quantum / data / builddefs を取得。
+- 機能一覧: docs/_sidebar.json、builddefs/generic_features.mk の GENERIC_FEATURES。
+- キーコード: data/constants/keycodes/keycodes_*.hjson をバージョン順にマージ。
+- 変更点: docs/ChangeLog/20250223〜20260830。
+- VIA移行PR: https://github.com/qmk/qmk_firmware/pull/26315(develop向けDraft。VIA_EEPROM_MAGIC_ADDR 以外は後方互換を維持する方針と記載)
+- 実機での検証はしていない。
@@ -0,0 +1,46 @@
+# VIAのモジュール化への追従
+
+## 結論
+
+- QMKはVIA統合をCommunity Modules形式へ移し、旧実装を将来削除すると告知(20260830 ChangeLog「VIA Feature Migration」#26315)。
+- 方針「QMKとVIAの両方に追従する」は変えない(ユーザー判断)。
+  → Community Modulesは当面非対応のままだが、VIAモジュールだけは例外として、移行がmasterに入る前に対応する。
+  最悪、Community Modulesへの対応はVIAだけでもよい(ユーザー発言)。
+- キーテスター(switch_matrix_state)が既定で動かない件は気にしない(ユーザー判断)。
+
+## 案の比較
+
+| 案 | 扱い |
+| --- | --- |
+| VIAモジュールだけCommunity Modules非対応の例外にする | 採用 |
+| Community Modules全般に対応を広げる | MAP-P-6のまま保留 |
+| 旧VIA実装が残るQMKに固定し続ける | 追従方針に反するので採用しない |
+
+## 根拠(2026-09-24時点)
+
+- docs/ChangeLog/20260830.md(QMK 0.34.4):
+  "upkeep of the VIA integration will transition to the VIA team" /
+  "in a future release, the old VIA feature-based implementation is expected to be removed."
+- PR https://github.com/qmk/qmk_firmware/pull/26315 : develop向けDraft。追加ファイルは
+  modules/qmk/via/{qmk_module.json, via.c, via.h, post_config.h, post_rules.mk}。
+  qmk_module.json にバージョン欄なし。VIA_EEPROM_MAGIC_ADDR 以外は後方互換を維持すると記載。
+- 0.34.4時点のVIAは従来どおり quantum/via.c、VIA_PROTOCOL_VERSION 0x000D。
+- 同梱モジュールの有効化は keymap.json の `"modules": ["qmk/via"]` の形(data/schemas/keymap.jsonschema の modules、
+  builddefs/build_keyboard.mk の generate-community-modules-*)。対応コストは小さい見込み。
+- 保守がVIAチームへ移るため、将来QMKリポジトリ外へ出る可能性はあるが未確認。
+
+## 追記: 対応環境の指定方法
+
+結論: 対応環境 = QMKのコミット + 使うモジュールの一覧(出所とコミット)。VIAは一覧の1項目。
+QMK同梱モジュールはQMKのコミットで決まる。実機との照合は従来どおりVIAプロトコル・キーコード体系のバージョン。
+
+| 案 | 扱い |
+| --- | --- |
+| QMKのコミット + モジュール一覧 | 採用。VIAが外部へ出てもMAP-P-6の他モジュールでも同じ形 |
+| QMKのコミット + VIAのバージョンだけ追加 | VIAの特別扱いになるため採用しない |
+| QMKのコミットだけ(現状) | VIAがリポジトリ外へ出ると実装が決まらない |
+
+- きっかけ: ユーザーが「QMKに加えてVIAのバージョンも明記したほうがよいか」と相談。
+- #26315の案ではVIAは modules/qmk/via(QMK同梱)で、qmk_module.json にバージョン欄がない。
+  この案のままならQMKのコミットだけで決まるが、保守移管後に外へ出る可能性に備える。
+- モジュールのバージョンは実機から取得できないため、照合には使わない。
@@ -0,0 +1,33 @@
+# VIAで読み書きする項目と機能・容量の確認方法
+
+## 結論
+
+- 対応: バージョン読み出し、レイヤー数、キーコード割り当て(まとめ読み書き含む)、マクロ
+- 別課題: エンコーダ(MAP-P-4)、layout option(P-3)
+- 当面非対応: リセット系・ブートローダ移行、デバイスの識別表示、キーテスター、custom channel
+- 有効な機能: 新規キーボードはGeneratorのビルド設定を正とする。既存キーボードは利用者の申告を信用する(ユーザー案)。
+  申告はGeneratorの設定と同じ形式にし、新規と既存を1つのモデルで扱う。
+- 容量(レイヤー数・マクロ個数・容量)は実機から読んで照合する。
+- P-2は判断が済んだので、実機で未検証という推測(P-2)に置き換えた。
+
+## 案の比較(VIA 0x000D, QMK 0.34.4 quantum/via.c)
+
+| 項目 | コマンド | 扱い | 理由 |
+| --- | --- | --- | --- |
+| プロトコル・キーコード体系バージョン | 0x01, 0x02 id 0x06 | 対応 | 実機照合に必須 |
+| レイヤー数 | 0x11 | 対応 | 容量確認 |
+| キーコード | 0x04/0x05, 0x12/0x13 | 対応 | MAPの本体 |
+| マクロ | 0x0C–0x10 | 対応 | P-1で内容をMAPが持つとした |
+| エンコーダ | 0x14/0x15 | 別課題 | MAP-P-4 |
+| layout options | 0x02/0x03 id 0x02 | 別課題 | P-3の排他キーの読み戻しと一体 |
+| リセット・ブートローダ | 0x06, 0x0A, 0x0B | 当面非対応 | 操作でありMAPのデータではない。0x0Aは VIA_EEPROM_ALLOW_RESET 時のみ |
+| デバイスの識別表示 | 0x03 id 0x05 | 当面非対応 | 任意の補助機能 |
+| キーテスター | 0x02 id 0x03 | 非対応 | 既定で全0(#25414)。ユーザーも不要と判断 |
+| custom channel | 0x07–0x09 | 非対応 | 照明・オーディオはMAP所有外、channel 0は固有コード |
+
+## 機能・容量の確認
+
+- VIAから読めるのは容量(レイヤー数、マクロ個数、マクロバッファサイズ)とバージョンだけ。
+  どの機能を有効にしてビルドしたか(タップダンス、コンボ等)は読めない。キーボード固有のVIA定義JSONにも含まれない。
+- 無効な機能のキーコードを書いてもエラーにならず、実機で何もしないだけ。申告の誤りは壊れる方向には働かない。
+- 既存キーボードは初期対応の前提ではない(MAPレイヤー.md「概要」)が、申告方式ならモデルを増やさずに扱える。
@@ -38,29 +38,33 @@ ELCはIDXを参照せず、IDXもELCを参照しない。MAPもIDXを参照し

 ### 3. IDXレイヤー (キー識別)

- **役割**: PHYのキーに"キー番号"を与える
+- **役割**: 全バリアントにわたるPHYのキーの並び順を保存し、選択した構成の出力用キー番号を決める
 - **入力**: PHYのキーID
 - **対応ツール**: QMKの `LAYOUT` マクロ、ZMKの matrix transform、KMKの `coord_mapping`
- **出力**: 番号を振るキーの並び。並びの位置がキー番号
+- **出力**: 全バリアントの対象キーIDを重複なく並べた `order`。出力時に対象外のキーを除き、0から連続する番号を与える
 - **備考**: キー番号はPHYの幾何からもELCの配線からも導出しない(導出すると、幾何の編集や再配線でキーマップがずれる)
- **備考**: キー番号は公開インターフェースであり、出力のたびに生成し直さず固定する
+- **備考**: 並び順を正本として保存する。出力番号は公開インターフェースであり、互換性は出力レイアウトごとに扱う
 - **備考**: マトリックス座標とLEDの識別番号はIDXが持たない(どちらも配線で決まるためELCが持つ)
- **備考**: レイアウトバリアントがあってもキー番号の空間は1つ。同じマトリクス位置に配線された排他キーは同じ番号を共有する
+- **備考**: 全バリアントで1つのIDXを持つ。同じ接続先に配線された排他キーも別々の要素とし、選択後の出力で番号を詰める。保存した `order` は変えない
 - **備考**: 既存のエコシステムでは、この並びが `LAYOUT` マクロの引数順などとして手書きされている。欠けている層ではなく、形式化されていない層

 ### 4. MAPレイヤー (キーマップ)

- **役割**: キーとキーコードの対応
+- **役割**: キーマップレイヤーごとのキーへの割り当て
 - **入力**: PHYのキーID
- **対応ツール**: ファームウェア、VIA、Remap
- **出力**: レイヤー別キーコード
- **備考**: キーの参照にキー番号を使わない。配列としての並べ替えは、出力時にIDXの並び順で行う
+- **対応ツール**: MAPエディタ (Keymap Designer)
+- **出力**: MAP JSON (現行形式はレイヤー別キーコード割り当て)
+- **備考**: キーの参照にPHYのキーIDを使う。配列としての並べ替えは、出力時にバリアント選択後のIDXの並び順で行う
+- **詳細**: [MAPレイヤー](MAPレイヤー.md)。動作定義とキーごとの設定の保存形式は、[MAPのP-1](MAPレイヤー.md#p-1-動作定義とキーごとの設定の保存形式)で扱う

-### 5. IMEレイヤー (入力変換)
+### 5. HSTレイヤー (ホスト)

- **役割**: キーコードと実際の入力文字の対応
- **対応ツール**: OS
- **備考**: MAPレイヤー設計時に考慮が必要
+- **役割**: 接続先のホスト(OSとキーボード配列の設定)が、キーコードをどう解釈するかの記述
+- **入力**: なし。どの層も参照せず、MAPエディタとFirmware Generatorから参照される
+- **対応ツール**: OSのキーボード配列、QMKの言語別キーコード(`keymap_japanese.h` など)
+- **出力**: ホスト環境ごとのプロファイル。キーボードに依存しない共有カタログとする
+- **備考**: IMEのかな漢字変換はOSの責務で、HSTの対象外
+- **詳細**: [HSTレイヤー](HSTレイヤー.md)

 ## ツール設計方針

@@ -75,7 +79,7 @@ ELCはIDXを参照せず、IDXもELCを参照しない。MAPもIDXを参照し
 #### Key Indexer

 - PHY JSONを入力
- キーにキー番号を割り当て
+- 全バリアントの対象キーを1つの並びに配置
 - 出力: IDX JSON

 #### Wiring Editor
@@ -85,18 +89,22 @@ ELCはIDXを参照せず、IDXもELCを参照しない。MAPもIDXを参照し
 - 視覚的に配線を確認
 - 出力: ELC JSON

-#### Keymap Designer
+#### Keymap Designer (MAPエディタ)

- PHY JSONを入力
- レイヤー別キーコード割り当て
- VIA/Remapとの互換性
+- PHYの配置を参照し、キーマップレイヤーごとの割り当てを編集・保存する
+- 新規キーボードの設計から実機での調整までを扱い、割り当ての読み書きを一組で提供する
+- 実機との通信は既存のVIAプロトコルから対応し、対象を段階的に増やす
 - 出力: MAP JSON

+具体的な責務と通信上の制約は、[MAPレイヤー](MAPレイヤー.md#mapエディタの責務)に従う。
+
 #### Firmware Generator

 - 全レイヤーの情報を統合
+- バリアントを選択し、IDXから対象外のキーを除いた並びで、キー番号の対応表とMAPの配列を生成
 - row / col など、ターゲットが要求する派生情報をここで割り当てる
 - QMK/VIA/KMK等へ変換
+- VIA向けキーボード定義は、配置と接続先の対応などを統合して生成する
 - 出力: ターゲット固有の設定ファイル

 ### 統合環境 (IDE)
@@ -106,6 +114,9 @@ ELCはIDXを参照せず、IDXもELCを参照しない。MAPもIDXを参照し
 - **バージョン管理統合**: テキストベース定義でgit管理
 - **ワークフローサポート**: ガイド付きウィザード、テンプレート

+ビルド・ファームウェアの書き込みは、MAP編集とは別の実行機能として扱う。
+同じ画面から各ツールを利用できることと、各レイヤーがそのデータや処理を所有することは区別する。
+
 ## プロトコル設計

 ### レイヤー間インターフェース
@@ -117,13 +128,14 @@ PHY → ELC

 PHY → IDX
  Input:  キーID + 配置
-  Output: 番号を振るキーIDの並び
+  Output: 全バリアントの対象キーIDの並び

 PHY → MAP
  Input:  キーID
-  Output: レイヤー別キーコード
+  Output: MAP JSON (現行形式はレイヤー別キーコード割り当て)

 All → Firmware
+  Input: 各レイヤーのデータ + バリアント選択
  Output: QMK keyboard.json / VIA JSON / KMK .py
 ```

@@ -156,7 +168,7 @@ All → Firmware
 ## 既存ツールとの関係

 - **KLE**: PHYデータを表示できる既存のビュワー。KLE JSONの読み書きで連携する
- **VIA/Remap**: MAP Layerクライアントとして連携
+- **VIA/Remap**: 同じVIA対応実機の割り当てを編集する外部クライアント。外部で調整した結果もMAPエディタで読み出してプロジェクトへ戻す。読み書きする項目は[MAP「VIAで読み書きする項目」](MAPレイヤー.md#viaで読み書きする項目)、実機との対応・状態管理は[MAPのP-3](MAPレイヤー.md#p-3-プロジェクトと実機の対応状態管理)で扱う
 - **QMK Configurator**: Firmware Generatorのターゲット

 ## 配慮事項
@@ -62,7 +62,8 @@
 - **現在の課題**: KLEとファームウェア設定の手動変換。並び順は手書きで、引数の数え間違いがそのまま
  キーのずれになる
 - **Beyond KLE対応**: **PHY** + **IDX** + **ELC** → ファームウェア自動生成。
-  ROW/COLはELCの配線から出力時に割り当てる。並び順は**IDXレイヤー**が正本として持つ
+  ROW/COLはELCの配線から出力時に割り当てる。並び順は**IDXレイヤー**が全バリアントにわたって正本として持ち、
+  出力時に選択したバリアントで使うキーだけを残して、キー番号を0から連続する番号に詰める

 #### b) キーマップ設定

@@ -71,7 +72,7 @@
  - 各キーへのキーコード割り当て
  - レイヤー設計
  - マクロ・特殊機能の設定
- **Beyond KLE対応**: **MAPレイヤー**。キーの参照にはPHYのキーIDを使い、配列への並べ替えは出力時にIDXの順で行う
+- **Beyond KLE対応**: **MAPレイヤー**。キーの参照にはPHYのキーIDを使い、配列への並べ替えは出力時にバリアント選択後のIDXの順で行う

 ### 4. 製造・組み立て段階

@@ -45,7 +45,7 @@ ELC・IDX・MAPはどれもPHYを参照する。ELCはIDXを参照せず、MAP
    },
    "kleCompatibility": {
      "type": "object",
-      "description": "File-level opaque KLE fields kept for round-trip output (switchMount, switchBrand, switchType, backcolor, radii, background, css). The owning layer is undecided; see P-6 in PHYレイヤー.md",
+      "description": "File-level opaque KLE fields kept for round-trip output (switchMount, switchBrand, switchType, backcolor, radii, background, css). Kept here for now; the eventual owning layer is deferred in backlog/README.md, PHY-P-6",
      "additionalProperties": true
    },
    "profiles": {
@@ -170,7 +170,7 @@ ELC・IDX・MAPはどれもPHYを参照する。ELCはIDXを参照せず、MAP
        },
        "kleCompatibility": {
          "type": "object",
-          "description": "Opaque KLE fields kept for round-trip output (c, t, p, a, f, f2, fa, l, n, sm, sb, st). The owning layer is undecided; see P-6 in PHYレイヤー.md",
+          "description": "Opaque KLE fields kept for round-trip output (c, t, p, a, f, f2, fa, l, n, sm, sb, st). Kept here for now; the eventual owning layer is deferred in backlog/README.md, PHY-P-6",
          "additionalProperties": true
        }
      }
@@ -424,8 +424,9 @@ ELC・IDX・MAPはどれもPHYを参照する。ELCはIDXを参照せず、MAP

 各フィールドの意味は `IDXレイヤー.md` を正とする。

-番号を振るキーの並びだけを持つ。並びの位置がキー番号になるため、欠番・重複・番号の飛びは
-構造として起こらない。
+全バリアントの対象キーIDを、重複なく1つの並びに持つ。同じ配線を使う排他キーも別々の要素とする。
+出力時は選択したバリアントで使わないキーを除き、残った並びの位置を0から連続するキー番号とする。
+保存した `order` は変更しない。

 ### 基本構造

@@ -434,7 +435,7 @@ ELC・IDX・MAPはどれもPHYを参照する。ELCはIDXを参照せず、MAP
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://beyond-kle.org/schemas/idx-layer.json",
  "title": "IDX Layer - Key Identification",
-  "description": "Ordered list of PHY keys; the position in the list is the key number",
+  "description": "Ordered PHY key IDs across all variants. Output key numbers are contiguous positions after filtering by variant selection",
  "type": "object",
  "required": ["version", "phyReference", "order"],
  "properties": {
@@ -450,20 +451,10 @@ ELC・IDX・MAPはどれもPHYを参照する。ELCはIDXを参照せず、MAP
    "order": {
      "type": "array",
      "uniqueItems": true,
+      "description": "Each PHY key has its own entry, including mutually exclusive keys wired to the same terminals. Variant selection does not modify this list",
      "items": {
-        "oneOf": [
-          {
-            "type": "string",
-            "description": "Reference to PHY layer key ID"
-          },
-          {
-            "type": "array",
-            "minItems": 2,
-            "uniqueItems": true,
-            "items": { "type": "string" },
-            "description": "Mutually exclusive variant keys sharing this key number. They must be wired to the same terminals in ELC"
-          }
-        ]
+        "type": "string",
+        "description": "Reference to PHY layer key ID"
      }
    }
  }
@@ -622,7 +613,8 @@ ELC・IDX・MAPはどれもPHYを参照する。ELCはIDXを参照せず、MAP
 ## 4. MAPレイヤー JSON Schema

 キーの参照にはPHYのキーIDを使う。キー番号は参照しない。
-配列としての並べ替えは、ファームウェア出力時にIDXの並び順で行う。
+配列としての並べ替えは、ファームウェア出力時にバリアント選択後のIDXの並び順で行う。
+キー番号と接続先の対応表も同じ並びで生成し、MAPの保存データは変更しない。

 ### 基本構造

@@ -654,10 +646,12 @@ ELC・IDX・MAPはどれもPHYを参照する。ELCはIDXを参照せず、MAP
  "$defs": {
    "layer": {
      "type": "object",
-      "required": ["id", "name", "keymap"],
+      "required": ["name", "keymap"],
      "properties": {
-        "id": { "type": "integer", "minimum": 0 },
-        "name": { "type": "string" },
+        "name": {
+          "type": "string",
+          "description": "Layer identifier, unique within the MAP. Layer order is the array order"
+        },
        "keymap": {
          "type": "array",
          "items": {
@@ -685,8 +679,8 @@ ELC・IDX・MAPはどれもPHYを参照する。ELCはIDXを参照せず、MAP

 ### PHY → IDX変換

-1. PHYレイヤーからキーのリストを取得
-2. 番号を振るキーを選び、並び順を決める
+1. PHYレイヤーから全バリアントのキーのリストを取得
+2. 番号を振る対象キーを1つの `order` に重複なく並べる。同じ配線の排他キーも別々の要素にする

 ### PHY → ELC変換

@@ -696,9 +690,12 @@ ELC・IDX・MAPはどれもPHYを参照する。ELCはIDXを参照せず、MAP

 ### IDX + ELC + MAP → ファームウェア出力

-1. ELCの配線から、ターゲットが要求する row / col を割り当て
-2. IDXの並び順に従って、MAPのキーコードを配列へ並べ替え
-3. VIA/QMK形式への出力
+1. PHYのVariantGroupごとにバリアントを選び、共通キーと、祖先を含めて選択されたバリアントのキーを特定
+2. IDXの `order` から対象外のキーを除き、残った順序のまま出力用のキー番号を0から連続して割り当て
+3. ELCの配線から、ターゲットが要求する row / col を割り当て、手順2の並びでキー番号との対応表を生成
+4. 同じ並びでMAPのキーコードを配列へ並べ替え、VIA/QMK形式へ出力
+
+保存したPHY・IDX・ELC・MAPは書き換えない。ELCのLEDチェーンの並び・番号は、このキーの取捨では変わらない。

 ## 次のステップ

@@ -0,0 +1,173 @@
+[
+  [
+    {
+      "p": "DCS R1"
+    },
+    "Esc",
+    {
+      "x": 0.25
+    },
+    "!\n1",
+    "@\n2",
+    "#\n3",
+    "$\n4",
+    "%\n5",
+    {
+      "x": 1
+    },
+    "^\n6",
+    "&\n7",
+    "*\n8",
+    "(\n9",
+    ")\n0",
+    "_\n-",
+    {
+      "x": 0.75
+    },
+    "+\n="
+  ],
+  [
+    {
+      "p": "DCS R2",
+      "a": 0,
+      "w": 1.5
+    },
+    "Tab\n\n\n\n\n1.5",
+    {
+      "a": 4
+    },
+    "Q",
+    "W",
+    "E",
+    "R",
+    "T",
+    {
+      "x": 0.5
+    },
+    "Y",
+    "U",
+    "I",
+    "O",
+    "P",
+    "{\n[",
+    {
+      "x": 0.5,
+      "a": 0,
+      "w": 1.5
+    },
+    "Backspace\n\n\n\n\n1.5"
+  ],
+  [
+    {
+      "p": "DCS R3",
+      "w": 1.75
+    },
+    "Ctrl\n\n\n\n\n1.75",
+    {
+      "a": 4
+    },
+    "A",
+    "S",
+    "D",
+    "F",
+    "G",
+    "H",
+    "J",
+    "K",
+    "L",
+    ":\n;",
+    "\"\n'",
+    {
+      "a": 0,
+      "w": 2.25
+    },
+    "Enter\n\n\n\n\n2.25"
+  ],
+  [
+    {
+      "p": "DCS R4",
+      "w": 1.25
+    },
+    "Shift\n\n\n\n\n1.25",
+    {
+      "x": 0.25,
+      "a": 4
+    },
+    "Z",
+    "X",
+    "C",
+    "V",
+    "B",
+    {
+      "x": 0.5
+    },
+    "N",
+    "M",
+    "<\n,",
+    ">\n.",
+    "?\n/",
+    "|\n\\",
+    {
+      "x": 0.25,
+      "a": 0,
+      "w": 1.75
+    },
+    "Shift\n\n\n\n\n1.75"
+  ],
+  [
+    {
+      "x": 1.25,
+      "w": 1.25
+    },
+    "Win\n\n\n\n\n1.25",
+    {
+      "w": 1.25
+    },
+    "Alt\n\n\n\n\n1.25",
+    {
+      "x": 6.5,
+      "w": 1.25
+    },
+    "Alt\n\n\n\n\n1.25",
+    {
+      "w": 1.25
+    },
+    "Ctrl\n\n\n\n\n1.25"
+  ],
+  [
+    {
+      "r": 180,
+      "rx": 4.5,
+      "ry": 4.5,
+      "y": -0.5,
+      "x": -0.25,
+      "a": 4
+    },
+    "\n\n\nFn"
+  ],
+  [
+    {
+      "rx": 6.75,
+      "y": -0.5,
+      "x": -2.5,
+      "p": "DCS SPACE",
+      "a": 3,
+      "w": 2.25
+    },
+    "\n\n\n\n\n2.25",
+    {
+      "w": 2.25
+    },
+    "\n\n\n\n\n2.25"
+  ],
+  [
+    {
+      "rx": 9.5,
+      "y": -0.5,
+      "x": -0.75,
+      "p": "DCS R4",
+      "a": 4
+    },
+    "\n\n\nCode"
+  ]
+]
@@ -0,0 +1,6 @@
+[
+  ["7", "8", "9", "/"],
+  ["4", "5", "6", "*"],
+  ["1", "2", "3", "-"],
+  ["0", ".", "Enter", "+"]
+]
@@ -0,0 +1,183 @@
+{
+    "name": "cr0wn60",
+    "vendorId": "0xADE1",
+    "productId": "0x0001",
+    "lighting": "qmk_rgblight",
+    "keycodes": [],
+    "matrix": { "rows": 9, "cols": 9 },
+    "layouts": {
+        "keymap": [
+            [
+                {
+                    "p": "DCS R1"
+                },
+                "1,0",
+                {
+                    "x": 0.25
+                },
+                "2,0",
+                "3,0",
+                "4,0",
+                "5,0",
+                "6,0",
+                {
+                    "x": 1
+                },
+                "0,1",
+                "2,1",
+                "3,1",
+                "4,1",
+                "5,1",
+                "6,1",
+                {
+                    "x": 0.75
+                },
+                "7,1"
+            ],
+            [
+                {
+                    "p": "DCS R2",
+                    "a": 0,
+                    "w": 1.5
+                },
+                "0,2",
+                {
+                    "a": 4
+                },
+                "1,2",
+                "3,2",
+                "4,2",
+                "5,2",
+                "6,2",
+                {
+                    "x": 0.5
+                },
+                "0,3",
+                "1,3",
+                "2,3",
+                "4,3",
+                "5,3",
+                "6,3",
+                {
+                    "x": 0.5,
+                    "a": 0,
+                    "w": 1.5
+                },
+                "7,3"
+            ],
+            [
+                {
+                    "p": "DCS R3",
+                    "w": 1.75
+                },
+                "0,4",
+                {
+                    "a": 4
+                },
+                "1,4",
+                "2,4",
+                "3,4",
+                "5,4",
+                "6,4",
+                "0,5",
+                "1,5",
+                "2,5",
+                "3,5",
+                "4,5",
+                "6,5",
+                {
+                    "a": 0,
+                    "w": 2.25
+                },
+                "7,5"
+            ],
+            [
+                {
+                    "p": "DCS R4",
+                    "w": 1.25
+                },
+                "0,6",
+                {
+                    "x": 0.25,
+                    "a": 4
+                },
+                "1,6",
+                "2,6",
+                "3,6",
+                "4,6",
+                "5,6",
+                {
+                    "x": 0.5
+                },
+                "0,7",
+                "1,7",
+                "2,7",
+                "3,7",
+                "4,7",
+                "5,7",
+                {
+                    "x": 0.25,
+                    "a": 0,
+                    "w": 1.75
+                },
+                "6,7"
+            ],
+            [
+                {
+                    "x": 1.25,
+                    "w": 1.25
+                },
+                "0,8",
+                {
+                    "w": 1.25
+                },
+                "1,8",
+                {
+                    "x": 6.5,
+                    "w": 1.25
+                },
+                "6,8",
+                {
+                    "w": 1.25
+                },
+                "7,8"
+            ],
+            [
+                {
+                    "r": 180,
+                    "rx": 4.5,
+                    "ry": 4.5,
+                    "y": -0.5,
+                    "x": -0.25,
+                    "a": 4
+                },
+                "2,8"
+            ],
+            [
+                {
+                    "rx": 6.75,
+                    "y": -0.5,
+                    "x": -2.5,
+                    "p": "DCS SPACE",
+                    "a": 3,
+                    "w": 2.25
+                },
+                "4,8",
+                {
+                    "w": 2.25
+                },
+                "3,8"
+            ],
+            [
+                {
+                    "rx": 9.5,
+                    "y": -0.5,
+                    "x": -0.75,
+                    "p": "DCS R4",
+                    "a": 4
+                },
+                "5,8"
+            ]
+        ]
+    }
+}
Author	SHA1	Message	Date
ewdernaandClaude Opus 5.5	af6ce99364	plan: Cr0wn60のVIA定義をcharlieplexingの検証用サンプルに加える - samples/via/cr0wn60.json を追加し、テストケースにcharlieplexingを加える - ピンの割り当てとマスクの参照先としてファームウェアのコミット68d9249を記録する - CLAUDE.mdのドキュメント地図にsamples/を載せる Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017W6AsoJYTiN3bnxvSMS87f	2026-09-24 23:00:26 +09:00
ewdernaandClaude Opus 5.5	1a443c562d	plan: 検証用サンプルを実在のキーボードのKLE JSONで定める - 60%はCr0wn60、分割はcrkbdとjisplit89、分割+バリアントはKyriaとIris Rev.7、マクロパッドは自作の4x4 - Cr0wn60(MIT、作者本人)と4x4は samples/kle/ に置く - the-via/keyboardsのもの(GPL-3.0)はコピーせず、コミット9e3e9f4とパスだけを記録する - 旧リストのErgonomic layoutはcrkbdとKyriaで扱う Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017W6AsoJYTiN3bnxvSMS87f	2026-09-24 22:56:12 +09:00
ewdernaandClaude Opus 5.5	73e913e776	plan: 60% ANSIのサンプルを現行のPHYスキーマの形式に書き換える - keys/position/size.width/metadata.label を root/type/transform/size.w/labels に置き換える - 値は変えない。PHYスキーマで検証済み - 旧形式である旨の注記を外し、見出しに抜粋と明記する Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017W6AsoJYTiN3bnxvSMS87f	2026-09-24 22:47:26 +09:00
ewdernaandClaude Opus 5.5	1c99f60719	hst: IMEレイヤーをHSTレイヤーとし、ホストによるキーコードの解釈の記述に範囲を絞る - 役割はホスト(OS×ホスト配列)がキーコードをどう解釈するかの記述。IMEの変換はOSの責務で対象外 - データはキーボードに依存しないプロファイルの共有カタログ。識別はOS×ホスト配列(+入力方式) - プロファイルは順方向の表・成立の前提・対応可否(3値)だけを持つ。逆引きと実現可否の判断は使う側(P-1で要確認) - MAPはキーコードを保存し、逆引きは一方向の入力補助とする - 複数ホストの扱いをP-2とし、MAP-P-5の参照をHSTへ向ける Journal: journal/2026-09-24-hst-layer-scope.md Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017W6AsoJYTiN3bnxvSMS87f	2026-09-24 22:39:50 +09:00
ewdernaandClaude Opus 5.5	7c927f5e12	map: 固有コード非対応の項目を対応範囲の一覧へ戻す 1414a7dでVIA移行の段落を一覧の途中に挿入し、固有コードの項目が一覧から離れていたのを直す。内容の変更なし。 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011zrYqwC8nXQX5Kg9Fur6Td	2026-09-24 08:35:10 +09:00
ewdernaandClaude Opus 5.5	a37fdd4abd	map: VIAで読み書きする項目と、機能はビルド設定を正とする確認方法を定める - バージョン、レイヤー数、キーコード割り当て、マクロに対応。エンコーダはMAP-P-4、layout optionはP-3 - リセット系、デバイスの識別表示、キーテスター、custom channelは当面非対応 - 有効な機能は新規キーボードではGeneratorのビルド設定、既存キーボードでは利用者の申告を正とし、容量は実機から読んで照合する - P-2を実機で未検証という推測に置き換える Journal: journal/2026-09-24-via-read-write-scope.md Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011zrYqwC8nXQX5Kg9Fur6Td	2026-09-24 08:32:03 +09:00
ewdernaandClaude Opus 5.5	333c651491	map: 最初の対応環境をQMK 0.34.4とする - QMK 0.34.4(08c662f)、キーコード体系0.0.9、VIAプロトコル0x000D。VIAは同梱の従来実装 - P-2の未決事項から対応コミットとキーコード体系を外す Journal: journal/2026-09-24-qmk-feature-inventory.md Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011zrYqwC8nXQX5Kg9Fur6Td	2026-09-24 08:25:08 +09:00
ewdernaandClaude Opus 5.5	0dc7933077	backlog: Cコードの生成とユーザーのCの組み込みをMAP-P-9として追加する keymap.jsonではタップダンス・コンボ・キーごとの設定等を表現できず、Cの生成が必要になる。 JSONを正本にしつつ、ユーザーのC/hで一部を上書きする方法を保留する。フック方式が有力。 Journal: journal/2026-09-24-generator-c-override.md Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011zrYqwC8nXQX5Kg9Fur6Td	2026-09-24 08:22:20 +09:00
ewdernaandClaude Opus 5.5	dccc5f095f	map: 対応環境をQMKのコミットと使うモジュールの一覧で固定する - 各モジュールは出所とコミットで指定し、QMK同梱のものはQMKのコミットで決まる - VIAもモジュールの1つとして扱い、QMKリポジトリ外へ移っても同じ形で指定できるようにする - MAP-P-6の未決事項からモジュールの指定方法を外す Journal: journal/2026-09-24-via-module-migration.md Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011zrYqwC8nXQX5Kg9Fur6Td	2026-09-24 08:21:59 +09:00
ewdernaandClaude Opus 5.5	1414a7d725	map: VIAがCommunity Modulesへ移ってもVIAモジュールで追従する - QMKはVIAをモジュールへ移し、旧実装を将来削除すると告知している(0.34.4 ChangeLog) - QMKとVIAの両方に追従する方針は変えず、Community Modules非対応の例外としてVIAモジュールに対応する - 移行がmasterに入る前に対応するため、MAP-P-6の再開条件に#26315のdevelop取り込みを加える Journal: journal/2026-09-24-via-module-migration.md Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011zrYqwC8nXQX5Kg9Fur6Td	2026-09-24 08:21:45 +09:00
ewdernaandClaude Opus 5.5	49b023ceaa	map: キーコードをQMK表記とし、キーごとの設定をMAP、全体設定をGeneratorに置く - キーコードはQMKの表記を基本とし、レイヤーとStatic定義は名前で参照する - キーボード全体の設定値はFirmware Generator、キーごとの上書きはMAPが持つ。QMKの機能ごとに所属を判断しないため - P-1を動作定義とキーごとの設定の保存形式に絞り、初期対応範囲の問いを削除する - QMK以外のファームウェアでのキーコード表記をMAP-P-8としてbacklogへ Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01P4UAjpgV7DLqJqF3sEf1bi	2026-09-23 21:18:59 +09:00
ewdernaandClaude Opus 5.5	e8fe11bfa1	backlog: 再ビルド時に実機の調整を失わないワークフローをMAP-P-7として追加する QMK本家のVIAは、実機に保存したVIAのデータをビルド日時をもとにした値で検証し、一致しなければ初期化する。再ビルドの前に実機の調整を読み出す手順が必要になる。 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01P4UAjpgV7DLqJqF3sEf1bi	2026-09-23 21:09:22 +09:00
ewdernaandClaude Opus 5.5	18e060d390	map: QMKはVIAのみDynamic対応とし、他の公式機能をStatic、非公式機能を当面非対応とする - DynamicはQMK本家masterのVIAプロトコルが公開する項目に限る - 公式機能のうちVIAで変更できないものはFirmware Generatorで生成する対象とする - フォーク・master以外のブランチ・Community Modulesは当面非対応(MAP-P-6)、固有コードは原則非対応 - 対応QMKはコミット固定とし、UIと実機照合はVIAプロトコル・キーコード体系のバージョンで行う - Static定義への参照は名前で持ち、VIA管理外のEEPROM設定は読み出せない制約を明記 - P-3のインデントを修正 Journal: journal/2026-09-23-qmk-dynamic-scope.md Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01P4UAjpgV7DLqJqF3sEf1bi	2026-09-23 20:33:43 +09:00
ewdernaandClaude Opus 5.5	cceb9a3e53	map: キーコードの表示を当面US配列とし、表示用OS配列をMAP-P-5で保留する US/JISの切り替えや他言語対応、IMEレイヤーとの関係は未定。割り当てと実機との読み書きは表示用の配列と独立に実装できるため保留とする。 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CBmwYrXocgCoFJfxVcKSGH	2026-09-23 14:52:17 +09:00
ewdernaandClaude Opus 5.5	cd502e260f	backlog: ON/OFF以外の入力への割り当てをMAP-P-4として追加するエンコーダはPHYで部品ノードとして置かれ、キーIDを参照するMAPからは割り当てられない。キーへの割り当てはこれを扱わずに実装できるため保留とし、 MAPのP-1(割り当てる動作の範囲)とは独立に扱う。 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CBmwYrXocgCoFJfxVcKSGH	2026-09-23 14:52:16 +09:00
ewdernaandClaude Opus 5.5	44035a7915	map: 新規作成したMAPは未割り当てから始める PHYのラベルからの自動適用は行わない。ラベルからの移植はPHY-P-8として保留中のため、保留課題にPHYへのリンクを置く。 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CBmwYrXocgCoFJfxVcKSGH	2026-09-23 14:51:21 +09:00
ewdernaandClaude Opus 5.5	76406e2f02	map: 実機で調整した割り当てをStaticの初期キーマップへ反映できるようにするプロジェクトのMAP、組み込んだ初期キーマップ、実機の現在値を区別する。実機の保存内容を初期化しても調整後の割り当てに戻せるようにするため。初期キーマップとの差分・反映の操作はP-3で扱う。 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CBmwYrXocgCoFJfxVcKSGH	2026-09-23 14:51:21 +09:00
ewdernaandClaude Opus 5.5	46905b1e79	map: P-3に排他キーが実機の割り当て先を共有する問題を追加する VIAの割り当てはrow/col単位で保存されるため、同じ接続先の排他キーは実機では1つの割り当て先を共有する。書き込み・読み出しでのPHYキーとの対応を未決事項と完了条件に加え、未決事項を箇条書きに分けた。 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CBmwYrXocgCoFJfxVcKSGH	2026-09-23 14:51:21 +09:00
ewdernaandClaude Opus 5.5	63da6e77d8	map: キーマップレイヤーを並び順と独立した名前で識別するレイヤーを切り替える動作も名前で参照し、番号へは出力時に並び順から変換する。並べ替えや挿入で参照先がずれないようにするため。スキーマのlayerからidを外し、MAP内で一意なnameを識別子とする。 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CBmwYrXocgCoFJfxVcKSGH	2026-09-23 14:51:21 +09:00
ewdernaandClaude Opus 5	54f292b08e	agent: decide/doc-lintを更新し、.agents と .claude を同期 codexが .agents 側で更新した内容を .claude へ取り込み、名前依存の箇所だけ置換した。両ツリーの差分はCLAUDE.md/AGENTS.mdとパスの表記のみ。 - 非採用一覧の掲載基準をルール1の変更に合わせる - 本文の「未決」はリンク・課題追加・言及削除のいずれかを判断する(ルール4) - 責務を外へ移したあと、担当範囲が分かる一文と参照が残っているか確認する - doc-lintに未確認事項リンクの参照先・ラベル整合の検査(ERROR)と、リンクのない課題番号・参照なしの「未決」「未定」の検出(WARN)を追加 - load() のコードフェンス処理が ~~~ や長さ違いを扱えていなかったのを修正 - .Codex という実在しないパスの参照を .agents に修正 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MtVk8W4yK6j3eCqQpEQBLS	2026-09-22 22:32:18 +09:00
ewdernaandClaude Opus 5	2fa910ed74	docs: 検討済み・非採用の掲載基準を再提案防止の必要性に変える件数と古さで機械的に落とすと、再提案を防ぐために必要な案が先に消える。掲載の可否を「実際に検討した別方針で再提案されうるか」で判断し、本文の制約文で足りるものは重複させない。落とした案がなければセクションを設けない。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MtVk8W4yK6j3eCqQpEQBLS	2026-09-22 22:32:08 +09:00
ewdernaandClaude Opus 5	bc2d33f856	docs: 本文から未確認事項へのリンク形式を運用ルール4に追加本文で「未決」とだけ書くと、末尾のどの項目に対応するか読む側が追えない。同一ファイル内・他ファイルからのリンク形式を定め、問いの内容は `## 未確認事項` にだけ置いて二重管理を避ける。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MtVk8W4yK6j3eCqQpEQBLS	2026-09-22 22:04:29 +09:00
ewdernaandClaude Opus 5	142357a440	map: MAPレイヤーを新設し、実機との読み書きとVIA対応を決める MAPエディタは割り当ての編集に加え、実機への書き込みと読み出しを一組で提供する。新規キーボードの設計から実機での調整までを主眼に置くため。最初の通信プロトコルはVIAとし、独自プロトコルの追加やそのためのファームウェアのフォークは行わない。 VIA向けキーボード定義の生成はFirmware Generator、ビルドと書き込みは IDEの責務として、MAP編集の外に置いた。VIAで通信できることと、MAPがそのデータを所有することは区別する。 Journal: journal/2026-09-22-map-via-workflow.md Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MtVk8W4yK6j3eCqQpEQBLS	2026-09-22 22:04:16 +09:00
ewderna	26df6edc06	agent: add skills for codex( simply copy)	2026-09-22 21:27:25 +09:00
ewderna	a80f5ea215	agent: add AGENTS.md for codex (simply redirect)	2026-09-22 19:57:13 +09:00
ewdernaandClaude Opus 5	5b671976d5	docs: 保留課題をbacklogへ分離し、運用ルール5を追加未確認事項が「現在の仕様が答えに依存するもの」と「答えが出なくても進められるもの」を混ぜて抱えていた。後者を backlog/README.md へ移し、仕様書の未確認事項を前者だけに絞る。移す際は保留中の対応範囲・暫定仕様を仕様書本文に明記し、 backlogへの移動が仮説の採用を意味しないようにする。 PHY・ELC・IDXの10件を移し、3ファイルとも未確認事項が空になった。ルール4では、事実確認の「格上げ条件」と意思決定の「完了条件」を区別する。仕様書側の保留課題はbacklogの区分へのリンク箇条書きだけに固定し、末尾は保留課題 → 検討済み・非採用 → 未確認事項の順に置く。 doc-lintをルール5に対応させ、backlogを検査対象に加えた。回帰テストを追加。 Journal: journal/2026-09-22-document-backlog.md Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DKW58HEg8zAQoLrkWByPfD	2026-09-22 19:52:39 +09:00
ewdernaandClaude Opus 5	66a594a378	elc: 走査方向の決定と追加指定をFirmware Generatorに置く ELCは配線を保存し、どちら側のピン群を駆動してどちら側から読み取るかは出力器が選ぶ。追加指定が必要な場合は出力設定で受け取る。複数の適切な方法から出力器が選べるなら一意性は要らないので、配線だけから全方式の走査手順が一意に決まることをELCの成立条件にしない。これは責任分担の決定であり、各方式の実配線を検証した結果ではない。 P-3は方式ごとの走査設定の確認として残す。 Journal: journal/2026-09-22-elc-scan-settings.md Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DKW58HEg8zAQoLrkWByPfD	2026-09-22 19:52:14 +09:00
ewdernaandClaude Opus 5	76c349fa0c	idx: 全バリアントを1つのorderに並べ、出力時に取捨して番号を詰める排他キーも別々の要素として並べる。出力はバリアントを選択した構成を単位とし、対象外のキーを除いた並びの位置をそのままキー番号にする。同じ配線の排他キーは選択後に同時には残らないため、番号を共有させる必要がない。保存したorderは選択で書き換えず、番号の互換性は出力レイアウトごとに扱う。 `6d0eba9` で「IDXは番号を共有できる」と書いたが、共有をやめる形に変える。コミュニティレイアウトの並びを取捨で得られるかは、この方式では未検証のため IDXのP-1として残す。 Journal: journal/2026-09-22-idx-variant-output.md Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DKW58HEg8zAQoLrkWByPfD	2026-09-22 18:36:09 +09:00