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
27 changed files with 2498 additions and 56 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決定。
@@ -7,6 +7,7 @@ argument-hint: [ファイル...]
 # ドキュメントのルール違反を検査する

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

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

@@ -46,6 +50,11 @@ backlogでは `### PHY-P-14 題名` のように区分付きIDを使い、関連
 backlogは短い候補・制約を保持できるため、メインドキュメント向けの散文ヒューリスティックは適用しない。

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

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

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

 ## 3. 報告する

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

 ## 注意
@@ -17,6 +17,11 @@ 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")
@@ -36,13 +41,20 @@ def add(sev, path, line, msg):
 def load(path):
    """コードフェンス内を空行に潰した (行番号, 本文) の列を返す。"""
    raw = Path(path).read_text(encoding="utf-8").splitlines()
-    out, fence = [], False
+    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):
@@ -71,6 +83,108 @@ def local_target(path, target):
    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
@@ -138,12 +252,7 @@ def check_backlog_section(path, rel, lines):
        if not linked.is_file():
            add("ERROR", rel, n, "保留課題の参照先ファイルがない: %s" % target)
            continue
-        headings = set()
-        for _, linked_line in load(linked):
-            heading = re.match(r"^#{1,6}\s+(.+?)\s*#*\s*$", linked_line)
-            if heading:
-                slug = re.sub(r"[^\w\s-]", "", heading.group(1)).lower().replace(" ", "-")
-                headings.add(slug)
+        headings = heading_index(load(linked))
        if anchor not in headings:
            add("ERROR", rel, n, "保留課題の参照先見出しがない: %s" % target)

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

    # --- journal 固有 ---
    if is_journal:
@@ -5,6 +5,7 @@ import io
 import tempfile
 import unittest
 from pathlib import Path
+from urllib.parse import quote
 from unittest.mock import patch


@@ -24,6 +25,14 @@ def backlog_item(pid="PHY-P-14"):
    )


+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()
@@ -145,6 +154,147 @@ class DocLintTests(unittest.TestCase):
        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()
@@ -1,7 +1,7 @@
 # Beyond KLE

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

 - 応答・ドキュメントは日本語。
 - 現状はコード未着手、設計ドキュメントのみ。
@@ -14,10 +14,13 @@ 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` |

 既存ドキュメントには下記ルールを段階的に適用する。PHY・ELC・IDXの保留課題はbacklogへ分離済み。
 全体の再編は別タスクとして行い、指示なく他の内容を移動・分割・書き直ししない。
@@ -39,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. 履歴と根拠

@@ -68,6 +72,9 @@ PHY(物理配置) / ELC(電気配線) / IDX(キー識別) / MAP(キーマップ)
 - **現在の仕様・実装が答えに依存する未確認事項**は、仕様書の末尾に残す。2種類ある:
  - 本文が前提にしている推測 → 本文に `[推測:P-n]` を付け、末尾の `## 未確認事項` に対応項目を置く
  - 実装前に判断が必要な未解決の問い → 本文タグなしで `## 未確認事項` に直接置く
+- 本文が未決の問いに触れるときは、「未決」と書いて終わらせず該当項目へリンクする。
+  同一ファイル内は `[P-3](#p-3-...)`、他ファイルからは `[MAPのP-3](MAPレイヤー.md#p-3-...)` の形とする。
+  問いの内容は `## 未確認事項` にだけ書き、本文へ写さない(二重管理を避ける)。
 - 未確認の推測には、**何を確認できれば事実に格上げできるか**を「格上げ条件」として書く。
  設計判断には、**何を決めれば解決するか**を「完了条件」として書く。意思決定を事実確認と混同しない。
 - 答えに依存せず進められる課題は `backlog/` に置く(ルール5)。保留中の対応範囲・暫定仕様は仕様書に残す。
@@ -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のレイヤーとの対応付けの有無をユーザーが決める。
@@ -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レイヤー)を含ませることができるが、必須ではない。

 ## 構造

@@ -98,3 +98,67 @@
 - 再開条件: 既存コミュニティレイアウトとの互換出力を検証するとき。
 - 完了条件: 実データのキーを共通キーとバリアント別の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,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「概要」)が、申告方式ならモデルを増やさずに扱える。
@@ -50,17 +50,21 @@ ELCはIDXを参照せず、IDXもELCを参照しない。MAPもIDXを参照し

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

- **役割**: キーとキーコードの対応
+- **役割**: キーマップレイヤーごとのキーへの割り当て
 - **入力**: PHYのキーID
- **対応ツール**: ファームウェア、VIA、Remap
- **出力**: レイヤー別キーコード
+- **対応ツール**: 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)

 ## ツール設計方針

@@ -85,19 +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)
@@ -107,6 +114,9 @@ ELCはIDXを参照せず、IDXもELCを参照しない。MAPもIDXを参照し
 - **バージョン管理統合**: テキストベース定義でgit管理
 - **ワークフローサポート**: ガイド付きウィザード、テンプレート

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

 ### レイヤー間インターフェース
@@ -122,7 +132,7 @@ PHY → IDX

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

 All → Firmware
  Input: 各レイヤーのデータ + バリアント選択
@@ -158,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のターゲット

 ## 配慮事項
@@ -646,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": {
@@ -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