National OS Japan Handbook

「読んだら全体像・現在地・動き方がわかる」 一冊本。
詳細は §8 の地図から各専門 doc へ。
N2 axiom (Natural Neutrality) に従い、自己評価・称賛表現を含まない。

§0 このドキュメントについて

役割: docs/ に散在する情報の統合入口。初回セッション / 引き継ぎ / 長期空白後の再開時に最初に読む 1 本。運用時の逐次参照は docs/handbook/ (完全取扱説明書、AI 単一入口 = docs/state/os_manifest.json) を使う。

canonical source: docs/HANDBOOK.md (shin-vps /root/national-os-japan/)

web 公開: https://national-os.jp/handbook

更新トリガー:

• §6 現在地: Phase 遷移時 + 月次 (最低 1 回)
• §7 教訓: 新 ADR の教訓が横断的に重要な場合のみ追記
• §8 地図: 新規 doc 追加・移動時
• §0 版番号: 毎回更新

注意: このドキュメントは snapshot。数値が古い可能性がある場合は (要確認) と記す。 canonical source (DB / git log / ADR) で実測してから判断すること。

このドキュメントと他 doc の棲み分け:

• docs/INDEX.md = 全 md ファイルの 1 行説明索引 (カタログ)
• docs/HANDBOOK.md = 通読書 (本 file)
• docs/LIVING_DESIGN.md = axiom + 不変的構造 (launch まで community vote 経由のみ更新)
• docs/RUNBOOK.md = 平時運用手順の詳細

§1 Mission

国の予算 123 兆円が、どこを通って、誰の手に渡って、何に使われたか。全部数字で追える。

3 原則 (VISION.md より転記)

1. 数字だけ。 文字（議事録等）に手を出さない
2. 出典付き。 全データに公式ソースへの 1 クリックアクセス
3. 判断しない。 「他と違う」を示す。「おかしい」とは言わない。判断は市民がする

追跡の範囲

国（123 兆円）
  → 主要経費別（社会保障 37 兆 / 国債費 27 兆 / 地方配分 17 兆 / 防衛 8.6 兆 / ...）
    → 都道府県別配分（突合チェック、透明度スコア）
      → 市区町村別配分（突合チェック）
        → 目的別歳出（財源構成比率付き）
          → 受注企業（法人番号で紐付け）

どの階層でもズームイン / アウト可能。企業側からの逆引きも可能。

意図的に捨てたもの

§2 全体像

何を: 政府公式統計 23 種を正規化・突合して、公金の流れを国から企業まで 5 階層で追跡するデータ基盤

誰のために: 「国民の税金がどこに使われているか知りたい」 全市民。 研究者・ジャーナリスト

どう作る: 完全オープンアルゴリズム (GitHub public)。 全計算ロジック公開。 全レコードに公式ソース URL 保持。 改ざん検知 (Merkle root + GitHub tag 週次外部アンカー)

現在地: 基盤完備 (旧 Phase 0-ε 全完了)。 v4.1 (synchronous-twilight) Phase 1-6 全完了 (2026-05-17)。

v4.1 実装フェーズ (synchronous-twilight)

旧基盤 (Phase 0-ε) KPI 達成状況

§3 アーキ quick ref

技術スタック

不可侵 axiom 12 個 (HANDOFF_PACK §1 より転記)

PR review で違反即 reject。 axiom 追加は launch 後 community vote 経由のみ。

構造的 (S1-S5):

様式的 (V1-V5):

中立性 (N1-N2):

ディレクトリ構造

/root/national-os-japan/
├── services/
│   ├── api/               # FastAPI 本体 (models.py が canonical)
│   ├── db/migrations/     # 229+ files、採番 = scripts/next_migration_number.sh
│   ├── evidence_manager/  # snapshot → canonical sha256 (S3 axiom)
│   └── scraper/collectors/  # データ収集 109 スクリプト
├── apps/
│   └── web/               # Next.js 16.2.6 (v4.1 移行先 / App Router)
│       └── src/app/       # pages (handbook/ 等)
├── docs/                  # 全 md 索引は docs/INDEX.md
│   ├── adr/               # 600+ ADR (active ~220 / archive ~138)
│   ├── design/            # VISION_FOUNDATION_v1 等
│   ├── deployment/        # PORT_REGISTRY / RUNNER_SETUP 等
│   ├── migration/         # history / collisions
│   ├── state/             # auto-generated state files (編集禁止)
│   ├── strategy/          # collision matrix 等
│   └── rule_audits/       # R-35/R-57/R-77/R-78 audit 群
├── scripts/               # 109 本 (migration 採番 / SRI 生成 / vendor copy)
├── tests/                 # pytest
└── deploy/systemd/        # timer 群 (Merkle / reconciliation / procurement-diff)

PORT / URL

§4 データ quick ref

規模 (要確認: 増加中)

追跡可能度 (2026-04-20 実測)

重要な概念

P-ID (パイプライン ID): 全レコードに付与する不変 ID。 階層を跨いで資金フローをトレース。 origin_pid + Lamport clock + immutability triggers で保護 (Phase 7-A 完了)。

透明度スコア: 「どこまで追えたか」 を 0-100 で数値化。 Unidentified (追跡不能) を定量管理。 5 終端タイプ分類 (N1 axiom)。

reconciliation rules: 異なるソース間の数値突合ルール。

• active: 41 rules (0 violations 維持)
• R-21 の 4 件は intentional policy monitoring signal として文書化済み (intent 的な 0 violations)
• skeleton: criteria populate 済み (active 化条件を明示)

Merkle root: 全データの改ざん検知。 weekly SHA256 + GitHub tag で外部アンカー。 確認: deploy/systemd/merkle.timer

canonical source 優先順位

§5 運用 quick ref

通常デプロイ (v4.1 Phase 1 以降)

# PR merge 後
ssh shin-vps
cd /root/national-os-japan
git pull origin main

# Python / FastAPI 再起動
source .venv/bin/activate
systemctl restart national-os-api

# Next.js rebuild + zero-downtime reload
cd apps/web
pnpm build
pm2 reload web

migration 実行

# 1. 番号採番 (全 origin/* scan で衝突回避)
scripts/next_migration_number.sh --check-vps

# 2. migration ファイル作成 (db/migrations/NNN_<description>.sql)

# 3. 実行
docker exec -it national_os_db psql -U nsjapan -d national_os -f /path/to/migration.sql

# 4. 動作確認
docker exec -it national_os_db psql -U nsjapan -d national_os \
  -c "SELECT rule_id, rule_name, tolerance FROM reconciliation_rules ORDER BY rule_id DESC LIMIT 5"

ADR 作成

# 番号採番 (衝突防止)
scripts/next_adr_number.sh

# 作成先: docs/adr/NNNN-<kebab-case-title>.md
# 必須セクション: Status / Context / Decision / Alternatives (「捨てたもの」) / Consequences
# Adversarial Self-Review: CLAUDE.md の 5 観点チェック必須

データ収集

# 個別 collector 実行
python scripts/collect_<name>.py

# e-Stat API: timeout 120s、 retry 3 回設定済み
# 全スクリプト一覧: ls scripts/collect_*.py | head -20

DB 直接確認

docker exec -it national_os_db psql -U nsjapan -d national_os

# よく使うクエリ
\dt                    -- テーブル一覧
\d table_name          -- テーブル構造
SELECT COUNT(*) FROM corp_master;  -- 企業マスタ件数

本番障害時

1. docs/ROLLBACK_PROCEDURE.md を最初に読む
2. 詳細手順は docs/RUNBOOK.md
3. DB backup: docker exec national_os_db pg_dump -U nsjapan national_os > backup.sql

並行 session 対策

• worktree 強制: .githooks/post-checkout が自動的に worktree 作業を強制
• migration 採番: scripts/next_migration_number.sh を 必ず 使う
• ADR 採番: scripts/next_adr_number.sh を 必ず 使う
• worktree は /root/national-os-japan-corp, /root/wt-* 等、repo root 外に作る
  • repo root 直下の wt-* に作ると docs/ が duplicate になり混乱 (教訓: wt-phase1-pr4/ が過去にその状態)

CI gates (push 前)

pnpm type-check        # TypeScript 0 errors (厳守)
pnpm lint              # ruff (Python) + ESLint
pytest                 # Python tests
pnpm build             # Next.js build success

INP threshold (launch envelope、 ADR-0005 確定):

• LCP < 4000ms / INP < 600ms / CLS < 0.1
• Phase 1-5 中は「launch envelope を割らない」 ことだけ守る

§6 現在地と次の一手

この section は最も drift しやすい。 git log --oneline -5 と task-tree DB を最初に確認すること。

今どこにいるか (2026-05-17 時点)

v4.1 (synchronous-twilight) 進行状況:

• Phase 1-6 全完了 (Phase 6: a0fa24a)
• 最新 main commit: #604 collect_kessan_obr α.2 refactor
• collector 追加継続中 (最新 migration 1579 factory_location_stat)
• worktree: main + corp (detached) + perf のみ (stale worktrees 整理済み 2026-05-17)

旧基盤 (Phase 0-ε) 状態:

• Master Plan 全完了 (Phase 0/α/β/γ/δ/ε + 7-M-θ)
• KPI: 一般会計 99.98% / exclude_keys 110 / tolerance_rationale 100% 達成
• reconciliation: 41 active rules + skeleton (0 violations 維持)

ADR 状況:

• 1600+ 本 (docs/adr/ 配下 281 files)
• 最新 ADR: ADR-1620 factory_location_stat (2026-05-17)

次の一手 (優先順)

1. collector 追加継続: migration 1589 以降 (next_migration_number.sh で採番)
2. α.2 collector refactor 継続: collect_fiscal_cards.py 等 (col-index 直書き廃止)
3. phase4/muni-choropleth: リモートブランチに市区町村コロプレス機能あり — cherry-pick/PR検討

マイルストーン

§7 教訓・禁則・ハマりどころ

絶対 NG (即 reject または事故になる操作)

よくハマる現象と対処

設計上の学び

§8 もっと知るための地図

最終更新ログ

Handbook は living document。 数値が古い可能性がある場合は先に canonical source (DB / git log / ADR) で確認する。