Docs: decisions.md を per-file ADR 群へ移行（Phase 0-5 完了）

.claude/agents/doc-reviewer.md

@@ -36,15 +36,15 @@ The orchestrator gives you the scope — the changed-file list / diff, or explic
 
 ## What is NOT a finding (do not flag)
 
-- **Why / design intent / rationale** — docs *should* explain these (`docs/decisions.md`, design sections). Not a finding (this is the key difference from `comment-reviewer`).
+- **Why / design intent / rationale** — docs *should* explain these (`docs/adr/`, design sections). Not a finding (this is the key difference from `comment-reviewer`).
 - **How / usage / tutorials / runnable steps** — docs *should* explain these. Not a finding.
 - **Structural completeness vs disk** — that is `sync-readme`'s job. Note it in passing only if you happen to see it; do not make it your focus.
 - **Generated docs** — `docs/portal/**`, `docs/openapi/**`, `docs/coverage/**`, `docs/db-schema/**`, `docs/godoc/**`, and any `<!-- generated -->` output: these are regenerated from sources; review the source, not the output.
 
 ## How to review
 
 1. Read `docs/rules.md` "Documentation Rules". Then read the doc(s) in scope.
-2. For every factual claim a doc makes about the code (a named symbol, file, command, flag, signature, behavior), **verify it against the actual code** — open the file, `grep` the symbol, check the path exists. Accuracy findings are your highest-value output and must be evidenced, not guessed.
+2. For every factual claim a doc makes about the code (a named symbol, file, command, flag, signature, behavior), **verify it against the actual code** — open the file, `grep` the symbol, check the path exists. Accuracy findings are your highest-value output and must be evidenced, not guessed. When a claim points at a *directory* rather than a specific file, read that directory's `README.md` first for orientation, then load only the specific files you need — more stable than scanning the whole directory.
 3. Then judge substance / rot / redundancy.
 4. Report **only** what you can quote and (for accuracy) evidence against the code. Be conservative — do not turn style preferences into findings.
 

.claude/skills/adr-scan/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: adr-scan
+description: PROVISIONAL / one-off. Full-repository scan that discovers ADR-worthy architectural decisions across the whole repo (not just docs/decisions.md) so decisions.md can be migrated to a formal docs/adr/ set. Fans out read-only discovery over four surfaces — canonical docs (decisions/architecture/rules), subsystem design docs (docs/design/**), deliberate-exclusion docs (docs/project/**, out-of-scope), and latent decisions (per-package READMEs + code "why" comments) — classifying each candidate as decision (ADR-worthy) / rule (stays in rules.md) / inventory (stays in a living reference) / exclusion (ADR-worthy negative decision). Read-only: produces a candidate ADR inventory only, writes no docs/adr files. Delete after the migration format is locked.
+---
+
+# adr-scan (provisional)
+
+**Status: temporary.** Built to drive the one-off `decisions.md` → `docs/adr/` migration
+survey. Remove once the ADR skeleton/numbering is agreed. Read-only — never writes
+`docs/adr/**` or edits source; it only emits a candidate inventory.
+
+## Purpose
+
+`docs/decisions.md` holds 8 explicit decisions, but architectural decisions are also
+scattered across design docs, rules, deliberate exclusions, and code comments. Before
+migrating to a formal per-file ADR set, discover the full ADR-worthy surface so the
+numbering and split are done once.
+
+## Classification taxonomy (the core judgment)
+
+Each candidate is exactly one of:
+
+- **decision** — a choice among alternatives with lasting consequences (X over Y). ADR-worthy.
+- **exclusion** — a deliberate "we intentionally do NOT do X" with rationale. ADR-worthy (negative decision).
+- **rule** — a consequence/constraint enforced day-to-day (layer deps, DTO boundary). Stays in `docs/rules.md`; may *reference* an ADR but is not itself one.
+- **inventory** — a catalog that drifts with code (dependency table). Stays in a living reference doc, never an ADR.
+
+A candidate is ADR-worthy only if: it has (or implies) considered alternatives, it is
+cross-cutting or hard to reverse, and it is not merely restating a rule/inventory.
+
+## Scan surfaces (fan out one worker each)
+
+1. **Canonical** — `docs/decisions.md`, `docs/architecture.md`, `docs/rules.md`. Extract explicit decisions + rule-encoded decisions; separate decision vs rule.
+2. **Subsystem design** — `docs/design/*.md` (idempotency / job / observability / outbox / rest / worker). Each design doc's "why / alternatives / trade-off" content.
+3. **Deliberate exclusions** — `docs/project/*.md` (esp. `out-of-scope.md`), `policy.md`, `scope.md`. Negative decisions with rationale.
+4. **Latent** — per-package `README.md` (Design Intent / Notes) + code `// why` rationale comments. Decisions made in code but never elevated to a doc.
+
+## Output (per candidate)
+
+```text
+- title:        short decision title (imperative, ADR-style)
+  type:         decision | exclusion | rule | inventory
+  adr_worthy:   yes | no
+  source:       file:line (evidence)
+  alternatives: present | implied | none
+  proposed_adr: which ADR bucket it belongs to (or existing 0001..N)
+  note:         one line — why worthy / why not
+```
+
+Aggregate into: (A) ADR bucket list with proposed numbering, (B) rules-stay list,
+(C) inventory-stay list, (D) newly-discovered decisions not in decisions.md.

.makefiles/database/dml-merge.mk

@@ -4,14 +4,14 @@
 .PHONY: merge-dml-repo ## ドメイン用DMLのマージ
 .PHONY: merge-dml-qs ## クエリサービス用DMLのマージ
 .PHONY: merge-dml-cs ## コマンドサービス用DMLのマージ
-.PHONY: merge-dml-sysq ## システムクエリ用DMLのマージ
+.PHONY: merge-dml-sysq ## システムCQRS用DMLのマージ
 .PHONY: merge-dml-core ## 指定したタイプのDMLのマージを実行 (例: make merge-dml-core type="repository" work-dir=".")
 # -----CI用ターゲット-----
 .PHONY: merge-dml-ci ## DMLのマージを実行（CI用）
 .PHONY: merge-dml-ci-repo ## ドメイン用DMLのマージ（CI用）
 .PHONY: merge-dml-ci-qs ## クエリサービス用DMLのマージ（CI用）
 .PHONY: merge-dml-ci-cs ## コマンドサービス用DMLのマージ（CI用）
-.PHONY: merge-dml-ci-sysq ## システムクエリ用DMLのマージ（CI用）
+.PHONY: merge-dml-ci-sysq ## システムCQRS用DMLのマージ（CI用）
 .PHONY: merge-dml-ci-core ## 指定したタイプのDMLのマージを実行（CI用） (例: make merge-dml-ci-core type="repository" work-dir=".")
 
 # -----Dockerコンテナ内で実行するコマンド群-----
@@ -22,7 +22,7 @@ merge-dml-repo:
 merge-dml-qs:
 	$(MAKE) merge-dml-core type="query_service" work-dir="."
 merge-dml-sysq:
-	$(MAKE) merge-dml-core type="system_query" work-dir="."
+	$(MAKE) merge-dml-core type="system_cqrs" work-dir="."
 merge-dml-cs:
 	$(MAKE) merge-dml-core type="command_service" work-dir="."
 merge-dml-core:
@@ -41,7 +41,7 @@ merge-dml-ci-repo:
 merge-dml-ci-qs:
 	$(MAKE) merge-dml-ci-core type="query_service" work-dir=$(work-dir)
 merge-dml-ci-sysq:
-	$(MAKE) merge-dml-ci-core type="system_query" work-dir=$(work-dir)
+	$(MAKE) merge-dml-ci-core type="system_cqrs" work-dir=$(work-dir)
 merge-dml-ci-cs:
 	$(MAKE) merge-dml-ci-core type="command_service" work-dir=$(work-dir)
 merge-dml-ci-core:

AGENTS.md

@@ -29,7 +29,7 @@ The source of truth for design, rules, and flows is under `docs/` and the per-pa
 | Non-negotiable rules (layer deps, generated code, domain constraints, DTO boundary, tx, errors, comments) | `docs/rules.md` |
 | How to perform a change (API / DB / business-logic flows, finding related code) | `docs/development-flow.md` |
 | Testing conventions (structure, naming, `require`/`assert`, mocks, coverage exceptions) | `docs/testing-conventions.md` (DoD in `docs/rules.md`) |
-| Technology rationale (ADR: onion / OpenAPI-first / sqlc / echo / fx / worker / o11y) | `docs/decisions.md` |
+| Technology rationale (per-file ADR: onion / OpenAPI-first / sqlc / echo / fx / worker / o11y) | `docs/adr/` (log: `docs/adr/README.md`) |
 | Per-layer / per-package detail | `internal/**/README.md`, `pkg/**/README.md` |
 | Subsystem design references (rest / worker / job / outbox / idempotency / observability) | `docs/design/README.md` |
 

README.md

@@ -145,7 +145,7 @@ The source of truth lives close to the code. Start here and follow the link that
 - [docs/architecture.md](docs/architecture.md) — system structure & layer responsibilities
 - [docs/rules.md](docs/rules.md) — non-negotiable rules (layer deps, generated code, DTO, tx, errors)
 - [docs/development-flow.md](docs/development-flow.md) — how to perform a change (API / DB / logic)
-- [docs/decisions.md](docs/decisions.md) — technology rationale (ADR)
+- [docs/adr/](docs/adr/README.md) — architecture decision records (ADR); technology rationale
 - [docs/testing-conventions.md](docs/testing-conventions.md) — testing conventions
 - [docs/project/versioning.md](docs/project/versioning.md) — versioning policy
 

database/dml/README.ja.md

@@ -16,7 +16,7 @@ database/dml/
 ├── query_service/    # 検索専用 DML（読み取り最適化）
 │   └── user/
 ├── command_service/  # コマンド専用 DML（将来拡張用）
-└── system_query/     # システム運用クエリ（ヘルスチェック等）
+└── system_cqrs/     # システム運用クエリ（ヘルスチェック等）
     └── health_check/
 ```
 
@@ -27,7 +27,7 @@ database/dml/
 |`repository/`|`internal/infrastructure/rdb/repository/`|Domain 層|Aggregate の CRUD|
 |`query_service/`|`internal/infrastructure/rdb/query_service/`|Usecase 層|ユースケース固有の検索|
 |`command_service/`|（将来拡張）|Usecase 層|書き込み専用コマンド|
-|`system_query/`|`internal/infrastructure/rdb/system_query/`|Usecase 層|システム運用クエリ|
+|`system_cqrs/`|`internal/infrastructure/rdb/system_cqrs/`|Usecase 層|システム運用クエリ|
 
 ## SQL ファイルの配置ルール
 

database/dml/README.md

@@ -16,7 +16,7 @@ database/dml/
 ├── query_service/    # Search-specific DML (read optimization)
 │   └── user/
 ├── command_service/  # Command-specific DML (future extension)
-└── system_query/     # System operational queries (health check, etc.)
+└── system_cqrs/     # System operational queries (health check, etc.)
     └── health_check/
 ```
 
@@ -27,7 +27,7 @@ database/dml/
 |`repository/`|`internal/infrastructure/rdb/repository/`|Domain layer|Aggregate CRUD|
 |`query_service/`|`internal/infrastructure/rdb/query_service/`|Usecase layer|Usecase-specific search|
 |`command_service/`|(future extension)|Usecase layer|Write-only commands|
-|`system_query/`|`internal/infrastructure/rdb/system_query/`|Usecase layer|System operational queries|
+|`system_cqrs/`|`internal/infrastructure/rdb/system_cqrs/`|Usecase layer|System operational queries|
 
 ## SQL File Placement Rules
 

database/dml/system_query/README.ja.md → database/dml/system_cqrs/README.ja.md

@@ -12,12 +12,12 @@
 
 ## インフラストラクチャマッピング
 
-実装: `internal/infrastructure/rdb/system_query/`
+実装: `internal/infrastructure/rdb/system_cqrs/`
 
 ## ディレクトリ構成
 
 ```text
-system_query/
+system_cqrs/
 ├── health_check/
 │   ├── select_system_health.sql
 │   └── ...

database/dml/system_query/README.md → database/dml/system_cqrs/README.md

@@ -12,12 +12,12 @@ System operational queries for health checks, metrics collection, and infrastruc
 
 ## Infrastructure Mapping
 
-Implementation: `internal/infrastructure/rdb/system_query/`
+Implementation: `internal/infrastructure/rdb/system_cqrs/`
 
 ## Directory Structure
 
 ```text
-system_query/
+system_cqrs/
 ├── health_check/
 │   ├── select_system_health.sql
 │   └── ...

database/gen/health_check_system_cqrs.gen.sql

@@ -0,0 +1,4 @@
+
+-- === source: database/dml/system_cqrs/health_check/select_system_health.sql ===
+-- name: GetDBHealthCheck :one
+SELECT 1 AS health_check;

database/gen/idempotency_system_query.gen.sql → database/gen/idempotency_system_cqrs.gen.sql

@@ -1,5 +1,5 @@
 
--- === source: database/dml/system_query/idempotency/claim_idempotency_key.sql ===
+-- === source: database/dml/system_cqrs/idempotency/claim_idempotency_key.sql ===
 -- name: ClaimIdempotencyKey :one
 -- 業務 tx 内でキーを claim する。既存キーがある場合は 0 行を返す。
 INSERT INTO idempotency_keys (
@@ -16,7 +16,7 @@ INSERT INTO idempotency_keys (
 ON CONFLICT ON CONSTRAINT idempotency_keys_scope_key_unique DO NOTHING
 RETURNING id;
 
--- === source: database/dml/system_query/idempotency/complete_idempotency_key.sql ===
+-- === source: database/dml/system_cqrs/idempotency/complete_idempotency_key.sql ===
 -- name: CompleteIdempotencyKey :execrows
 -- 同一 tx 内で claimed → completed へ遷移し、結果 DTO(JSON) と HTTP ステータスを保存する。scope 必須（越境防止）。
 UPDATE idempotency_keys
@@ -29,7 +29,7 @@ WHERE scope = $1
     AND idempotency_key = $2
     AND status = 'claimed';
 
--- === source: database/dml/system_query/idempotency/delete_expired_idempotency_keys.sql ===
+-- === source: database/dml/system_cqrs/idempotency/delete_expired_idempotency_keys.sql ===
 -- name: DeleteExpiredIdempotencyKeys :execrows
 -- TTL 失効行を最大 $2 件削除し、削除件数を返す。
 DELETE FROM idempotency_keys
@@ -41,7 +41,7 @@ WHERE id IN (
         LIMIT $2
     );
 
--- === source: database/dml/system_query/idempotency/get_idempotency_key.sql ===
+-- === source: database/dml/system_cqrs/idempotency/get_idempotency_key.sql ===
 -- name: GetIdempotencyKey :one
 -- scope 必須（越境防止）。scope と idempotency_key で一致する行を返す。
 SELECT

database/gen/outbox_system_query.gen.sql → database/gen/outbox_system_cqrs.gen.sql

@@ -1,5 +1,5 @@
 
--- === source: database/dml/system_query/outbox/claim_pending_outbox.sql ===
+-- === source: database/dml/system_cqrs/outbox/claim_pending_outbox.sql ===
 -- name: ClaimPendingOutbox :many
 -- pending 行を最大 $1 件 claim する。SKIP LOCKED により多インスタンスでも同一行を二重取得しない。
 -- 順序保証は捨てているため id 昇順で十分。呼び出し側 tx の保持中だけロックされる。
@@ -18,7 +18,7 @@ ORDER BY id
 LIMIT $1
 FOR UPDATE SKIP LOCKED;
 
--- === source: database/dml/system_query/outbox/delete_published_outbox.sql ===
+-- === source: database/dml/system_cqrs/outbox/delete_published_outbox.sql ===
 -- name: DeletePublishedOutbox :execrows
 -- retention 用 GC。published_at が cutoff より古い行を最大 $2 件削除し、削除件数を返す。
 -- 長時間稼働で outbox が単調増加しないようにする。
@@ -32,7 +32,7 @@ WHERE id IN (
         LIMIT $2
     );
 
--- === source: database/dml/system_query/outbox/insert_outbox.sql ===
+-- === source: database/dml/system_cqrs/outbox/insert_outbox.sql ===
 -- name: InsertOutbox :one
 -- 業務 tx 内で outbox 行を 1 行 INSERT する（emit）。message_id は DB が採番し返す。
 INSERT INTO outbox (
@@ -46,15 +46,15 @@ INSERT INTO outbox (
 )
 RETURNING id, message_id;
 
--- === source: database/dml/system_query/outbox/mark_outbox_dead.sql ===
+-- === source: database/dml/system_cqrs/outbox/mark_outbox_dead.sql ===
 -- name: MarkOutboxDead :execrows
 -- attempts が max に達した恒久失敗行を dead へ遷移する。無限リトライを止め、手動 replay 対象として残置する。
 UPDATE outbox
 SET status = 'dead'
 WHERE id = $1
     AND status = 'pending';
 
--- === source: database/dml/system_query/outbox/mark_outbox_failed.sql ===
+-- === source: database/dml/system_cqrs/outbox/mark_outbox_failed.sql ===
 -- name: MarkOutboxFailed :one
 -- publish 失敗時に attempts を加算し last_error を記録する。加算後の attempts を返し、
 -- 呼び出し側が max 到達判定（dead 化）に用いる。次 poll で自然に再送される。
@@ -66,7 +66,7 @@ WHERE id = $1
     AND status = 'pending'
 RETURNING attempts;
 
--- === source: database/dml/system_query/outbox/mark_outbox_published.sql ===
+-- === source: database/dml/system_cqrs/outbox/mark_outbox_published.sql ===
 -- name: MarkOutboxPublished :execrows
 -- publish 成功行を published へ遷移する。published_at に遷移時刻を記録する。
 UPDATE outbox
@@ -76,7 +76,7 @@ SET
 WHERE id = $1
     AND status = 'pending';
 
--- === source: database/dml/system_query/outbox/oldest_pending_outbox.sql ===
+-- === source: database/dml/system_cqrs/outbox/oldest_pending_outbox.sql ===
 -- name: OldestPendingOutbox :one
 -- SLI(outbox lag) 算出用。最古 pending 行の created_at を返す。pending 行が無ければ 0 行を返す。
 SELECT created_at
@@ -85,7 +85,7 @@ WHERE status = 'pending'
 ORDER BY id
 LIMIT 1;
 
--- === source: database/dml/system_query/outbox/replay_dead_outbox.sql ===
+-- === source: database/dml/system_cqrs/outbox/replay_dead_outbox.sql ===
 -- name: ReplayDeadOutbox :execrows
 -- dead 行を pending へ戻し再 publish 対象に復帰させる（運用 replay）。attempts/last_error をリセットする。
 -- $1 が NULL の場合は全 dead 行、指定時は当該 message_id のみを対象とする。

docs/adr/0000-record-architecture-decisions.md

@@ -0,0 +1,72 @@
+---
+status: accepted
+date: 2026-07-04
+deciders: [maintainers]
+tags: [meta, documentation]
+---
+
+# ADR-0000: Record architecture decisions as ADRs
+
+## Status
+
+accepted
+
+## Context
+
+Collating a project's technology rationale into a single growing file has two problems:
+
+- **In-place editing loses history.** Rewriting a decision when reality changes discards
+  the record of *why the old design was once chosen*.
+- **Mixed content.** Blending immutable decisions with a living inventory (e.g. a dependency
+  table that must track `go.mod`) forces a drifting catalog into a "rationale" document,
+  where it silently goes stale.
+
+This is a **template** repository: downstream users fork it and need to understand *why*
+each choice was made, and to *supersede* individual choices with their own without editing
+a shared monolith.
+
+## Decision
+
+Record each architecture decision as its own immutable file under `docs/adr/`, in
+MADR-lite form (see [`template.md`](template.md)). Classify every candidate before it
+lands:
+
+- **decision** / **exclusion** → an ADR here (immutable; supersede by a new ADR).
+- **rule** (a day-to-day enforced consequence) → stays in `docs/rules.md`, may link its ADR.
+- **inventory** (a catalog that drifts with code, e.g. the dependency list) → a living
+  reference (`docs/reference/dependencies.md`), never an ADR.
+
+ADRs are numbered in dependency / foundational order (principles first), and superseding a
+decision means adding a new `accepted` ADR and flipping the old one to `superseded`, not
+editing its body.
+
+## Consequences
+
+### Positive Consequences
+
+- Decision history is preserved; supersession is auditable.
+- Forks can override one decision by adding one ADR.
+- Drifting catalogs (dependencies) live where drift is expected, not inside immutable records.
+
+### Negative Consequences
+
+- More files and cross-references to maintain (each ADR also needs a `docs/ja/adr/` mirror).
+- Contributors must classify (decision vs rule vs inventory) before writing — a small upfront judgment cost.
+
+## Alternatives Considered
+
+### Keep the single `docs/decisions.md`
+
+Rejected: in-place edits erase decision history, and the file already mixed immutable
+decisions with a drifting inventory.
+
+### One file, append-only decision log (no per-decision files)
+
+Rejected: forks cannot cleanly supersede an individual decision, and a single file grows
+unbounded and merge-conflicts.
+
+## Notes
+
+- Migration scope, the full ordered ADR list (~92), and per-ADR source references live in
+  [the ADR log](README.md).
+- The dependency inventory that lived in `docs/decisions.md` moves to `docs/reference/dependencies.md`.