name: datalog-debug-skill description: freee API から同期したデータ、または任意の What-if データを DataLog (オンメモリ監査エンジン) に投入し、クエリ・監査・可視化で分析するためのスキル。会計税務・労務・社内統制の整合性監査、仮想シナリオ検証、グラフ探索を行う際に使う。

DataLog Skill

freee 会計・人事労務データを「事実 (Facts) と規則 (Rules) の集合」として取り込み、クエリ・監査・インタラクティブなグラフで分析するスキル。本番 freee データへの書き込みは発生せず (オンメモリ独立環境)、多様な入り口 (API 同期 / 自由 transact / LLM 試作) を同じグラフモデルに吸収する。

初期設定 (必須・非自動)

DataLog は MCP サーバー起動時に空の状態で立ち上がる。freee API データは 明示的に datalog_sync_* を呼ばない限り 1 件も投入されない (自動同期は無い)。クエリや監査を走らせる前に、対象ドメインに応じて以下を順に実行すること。

freee_auth_status で OAuth トークンが有効か確認 (期限切れなら freee_authenticate)
freee_set_current_company で対象事業所を選択
datalog_reset でクリーンな環境を確保 (再 sync 時は必須)
- ⚠️ 共有環境 (本番 / experimental など共通アカウント) では datalog_reset を呼ばない。エンジンは共有なので他利用者が投入済の datom / 検証データ (共有 30 件等) を破壊する。共有環境では reset せず、対象データを追加 sync するだけで足りる。手元の専有 sandbox でのみ reset 可。判断に迷うなら reset を省略する (= 非破壊側に倒す)
対象データを sync (会計監査なら deals/partners/account_items/tax_codes、社労士監査なら employees/work_record_summaries)
datalog_visualize で取り込み結果を確認

注意点:

各 datalog_sync_* は 差分同期ではなく全件取得。再実行で重複は発生しないが、削除されたエンティティを反映するには datalog_reset を挟む必要がある
datalog_sync_deals / datalog_sync_account_items は内部で概念ノード (取引/明細/勘定科目等) を最初の呼び出しでプリセットする。datalog_sync_partners は単独では概念ノードを作らないので、deals か account_items の sync を先に走らせること (順序逆だと "Nothing found for entity id ('node/name' '取引先')" でエラー)
datalog_sync_work_record_summaries は datalog_sync_employees の後でのみ動作 (emp ノードが無いと早期 return)
datalog_query / datalog_audit_run_all を sync 前に走らせると空結果が返るだけで失敗扱いにはならない。「データが無い」と「クエリが間違っている」の区別がつきにくいので、必ず初期設定 (上記 1-4) を済ませてから検証する

ツール早見表

ツール	役割
`datalog_schema`	現在のスキーマ情報 (固定 + 登録済み + 動的統計 + 推奨クエリ) を一括で返す
`datalog_query`	任意の datalog クエリを実行
`datalog_reset`	DataLog 環境を初期化
`datalog_transact`	任意 datom を投入 (persist=true で durable 永続化)
`datalog_retract`	durable に永続化した datom のうち指定したものだけを撤回 (= 検証フィクスチャの後始末。 reset 全消しと違い対象限定)
`datalog_sync_*`	freee API からデータ同期 (account_items / partners / tax_codes / deals / user_matchers / employees / work_record_summaries)
`datalog_visualize`	HTML 可視化 (自動更新)
`datalog_audit_list` / `datalog_audit_get` / `datalog_audit_create` / `datalog_audit_update` / `datalog_audit_delete` / `datalog_audit_run_all`	AuditQuery (監査クエリ) CRUD + 全件走行 (現行の正典モデル)。query は `[:find ?x :where ...]` selector。GUI と同じ store に書くのはこちら
`datalog_predicate_list` / `datalog_predicate_get` / `datalog_predicate_create` / `datalog_predicate_update` / `datalog_predicate_delete`	DomainPredicate (IDB / 派生述語) CRUD (現行の正典モデル)。query が rule body。is_detail_of 等のドメイン述語をここで作る
`datalog_testcase_list` / `datalog_testcase_get` / `datalog_testcase_create` / `datalog_testcase_update` / `datalog_testcase_delete` / `datalog_testcase_run`	TestCase (header: title / dataSource / kind / statuteDescription) CRUD + 配下 row 一括走行。parentKind=`audit_query` \| `domain_predicate` + parentId で親に紐付く
`datalog_testrow_list` / `datalog_testrow_get` / `datalog_testrow_create` / `datalog_testrow_update` / `datalog_testrow_delete`	TestRecordV2 row (nodeKey / expectedKind / businessExpectation / freeeReqBody) CRUD。TestCase 配下の test データ 1 行
`datalog_server_info`	サーバ build 情報 (commit / deploy 時刻) を返す。版数文字列が再デプロイ跨ぎで据え置きでも、どのビルドを叩いているか判別できる (= FB 切り分け用)

test の設計・作成は TestCase + testrow の親子モデル (datalog_testcase_* + datalog_testrow_*、上表) を使う。TestCase 1 件 = header (title / dataSource / kind / statuteDescription) で、その配下に複数 testrow (= nodeKey / expectedKind / businessExpectation / freeeReqBody)。走行は datalog_testcase_run。観点設計は audit-test-design-skill / freee-api-test-record-skill を参照。

基本ワークフロー

A. 実データ監査 (会計・税務)

freee_set_current_company → datalog_reset → datalog_sync_account_items
→ datalog_sync_partners → datalog_sync_tax_codes → datalog_sync_deals
→ datalog_sync_user_matchers (任意: 自動仕訳ロジック監査用)
→ datalog_visualize

datalog_sync_user_matchers は freee の自動登録ルール (UserMatcher) を取り込む。明細の自動仕訳ロジック (条件 / 適用 act / 適用先 account_item) を DataLog で照合できるようになり、「ルール適用結果と実 account_item の乖離」「無効化されたまま放置されたルール」等の監査が可能。

B. 人事労務データ (社労士観点)

freee_set_current_company → datalog_sync_employees
→ datalog_sync_work_record_summaries year=YYYY month=M → datalog_visualize

C. What-if 仮想データ

datalog_transact {...} → datalog_query → datalog_visualize

D. スキーマ発見 (LLM 向け)

datalog_schema (初回のみで全体像取得)
→ 興味のある概念名を特定
→ datalog_query (返された recommendedQueries を参考に)
→ 必要なら datalog_audit_create で監査化 / datalog_predicate_create でドメイン述語化

詳細リファレンス

idb-first-fewshot — ドメイン述語ファーストの good/bad 例、:in $ % 経路差、Pre-flight
statute-description — statuteDescription (法文風 Markdown) 書式規約 + few-shot + 強制ルール
core-predicates — 基本述語 6 種の意味と使い分け
datom-format — transact payload の書式、lookup-ref の使い方
query-syntax — Datalog :find :where :in の構文、rules 渡し
identifier-conventions — deal_/detail_/partner_/emp_/workrec_/... 命名規則

skill-only クライアント (= この skill を MCP 経由でしか読めない素の AI) は、上記 references を datalog_skill_list で一覧し datalog_skill_get（例 references/query-syntax.md）で本文取得できる。

よくある操作

schema-discovery — datalog_schema → 推奨クエリ → datalog_query の手順
what-if-analysis — 仮想データ投入とロールバック
visualization-guide — HTML モード切替 (簡単化/Raw)、アコーディオン、監査クリック
troubleshooting — FAQ (クエリ空返り、ルール追加失敗等)

運用鉄則 (厳守)

local (datalog-store/<base>.local.<breaking>.json) は絶対に手編集しない
- 必ず MCP 経由: datalog_audit_create / datalog_audit_update / datalog_audit_delete、ドメイン述語は datalog_predicate_create / datalog_predicate_update / datalog_predicate_delete (現行の正典モデル)
- 理由: Zod 検証、conn.onModified 連動 (HTML 自動更新)、テスト互換性を壊さないため
common (datalog-store/<base>.<breaking>.json) のみ手編集可
- git commit の diff で team レビューできるので、手編集の挙動変更は検出可能
監査クエリはドメイン述語 (DomainPredicate) を最大限活用
- [?e "is_a" ?c] [?c "node/name" "..."] のような型検査の繰り返しは対応する述語 (例 is_detail_of, is_partner_of, is_payment_instance_of) に畳む
- 監査の :where に :in $ % を書けば runner がドメイン述語集合を自動注入する
足りないドメイン述語は先に作る → その後監査クエリを書く
- 順序逆は技術負債になる (監査ごとに長い where が重複)
新規ドメイン述語 / 監査クエリは test 駆動 (現行モデル: TestCase + testrow)
- 親 (datalog_predicate_create / datalog_audit_create) を作ったら、datalog_testcase_create で TestCase を紐付け、datalog_testrow_create で期待付き test 行を足し、datalog_testcase_run で passing を確認
- test 0 件 (= linter TestCase) のままでも登録は可能だが UI に「未検証」相当が出る
- scope 別の必須要件 (enforce 済み):
  - scope='user': test 0 件可
  - scope='organization' (= org-admin caller のみ作成可): test 1 件以上必須
  - scope='common' (= app-admin caller のみ作成可): test 1 件以上必須
- test 期待値は testrow で表現: 各 testrow が expectedKind (truePositive / trueNegative / outOfScope) と businessExpectation (業務期待値 ordinal) を持つ。user の石入れ (確定 2 値) は GUI の test-cases-v2 画面で行う (= 共有範囲 writeGroups で編集可否)。
description は 3 系統で書く (audit query のみ statuteDescription 必須)
- userDescription: ドメインユーザー向け平易日本語 (集合論レベル / プログラミング用語禁止)
- engineerDescription: エンジニア / AI 向け技術疑似コード (旧 pseudocode の役割)
- statuteDescription: 税理士 / 会計士向け法文風 (= 条文風) Markdown 詳細。 audit query (= datalog_audit_create / datalog_audit_update) では 必ず埋める (= 詳細書式は statute-description)。ドメイン述語では不要。既存 query を update する際に空のまま上書きしない (= 既存値を必ず引き継ぐか、改訂版を出す)。
status 4 値ライフサイクル (= rule / query の稼働状況)
- active (本番) / not_active (停止) / updating (試作中、create 既定) / outdate (breaking ver up 後の未対応)
- (実装上は int ordinal: not_active=0 / outdate=10 / deprecated=20 / updating=30 / active=40)

runStatus 7 値 (= test / TestRecord の走行・段階)

test の走行結果 + 設計段階を 1 enum (int ordinal、末端 = 健全) で表す。 datalog_testcase_run が persist し、byRunStatus 集計でも使う:

ordinal	name	label	意味
`0`	`untested`	未走行	まだ走らせていない
`5`	`query_pending`	クエリ未完成	親 audit query が未完成 (= 走行不可)
`7`	`test_design_pending`	テスト設計中	header / 期待だけで datoms 未充足 (= 走行不可)
`10`	`error`	走行エラー	走行中に例外
`20`	`failing`	失敗	走行結果が期待と不一致
`30`	`passing`	成功	unit 走行 OK (= `datom_only` の terminal green)
`40`	`e2e_passing`	E2E 成功	freee 実投入 + 実走行まで通った最上位

runStatus ≠ rule の status (= 別 enum)。 runStatus は test 行の走行/段階、 status は rule/query の稼働状況。

AI は検証データを自発削除しない (厳守)
- audit query / IDB rule / TestCase / TestRecord などの 検証データの削除 (*_delete / datalog_reset) は user の明示指示が有る時だけ。
- 「片付け」「GUI で確認したいから一旦消す」等の AI 自身の判断による削除は禁止。作成物は残す。不要に見えても user が画面で確認・再利用する前提。
- 過去事故: user が消すよう指示していない fbtest* を AI が「片付け」と称して勝手 delete し、 user の GUI 確認を壊した。再発防止としてこの鉄則を置く。

breaking version とファイル名

datalog-store/ 配下の common / local 両方にバージョンタグ (<major>.<minor>、ゼロ詰め無し) が埋め込まれる:

common: <base>.<breaking>.json         例: query.0.0.json
local : <base>.local.<breaking>.json   例: query.0.0.local.json

<breaking> は package.json.version の major.minor 部分に追従する。

patch bump (0.0.1 → 0.0.2): 後方互換、データファイル変更不要
minor bump (0.0.x → 0.1.0): breaking、common と local 両方を新タグへ書き直す必要がある (datalog-migration-skill を参照)

旧 breaking 版の local ファイルは並列に残せる (= 現行版でないものは識別可能)。書き直し完了後に git rm で削除可。MCP CRUD ツールは現行 breaking 版にのみ書き込む。

ドメイン述語ファースト (要点)

クエリを書く前に必ず datalog_predicate_list で既存ドメイン述語 (DomainPredicate / IDB) を確認し、活用可能なら畳む。型検査の繰り返し ([?e "is_a" ?c]...) は対応する述語 (例 is_detail_of) に畳み、:find 直後の :in に $ % を必ず含める (忘れると Missing rules var '%' in :in で失敗、空返りではない)。試作は :in $ % 無しのアトミック述語で動作確認 → 安定後に datalog_predicate_create + datalog_audit_create で監査化。

good/bad の EDN 例、:in $ % 経路差 (audit 走行は自動注入 / ad-hoc datalog_query のみ inputs 明示)、Pre-flight チェックリストは idb-first-fewshot を参照。

注意事項

セッション内で state は保持される。クリーンな状態が必要なら datalog_reset
完全リセット (local.json 含む) は datalog_reset fullReset=true (破壊的)
可視化 HTML は /tmp/datalog_graph_latest.html に常時上書き
sync は差分同期ではない。取り直しは datalog_reset → sync を再実行
datalog_sync_* は freee API 認証前提。事前に freee_auth_status で確認

開発時の reconnect 最小化

原則: normal user 経路 (= MCP tool 連続呼び出し + 必要に応じた手編集) では reconnect 一切不要。reconnect が要るのは「コード変更で bin を入れ替える」開発作業時のみ。

reconnect 要否マトリクス:

変更内容	reconnect	理由
`datalog_*_create/update/delete` 等の MCP CRUD	不要	`notifyChanged()` → `refreshIdbRules()` で in-memory cache 自動更新
`datalog-store/*.json` の手編集	不要 (local) / 要 (common 反映)	`listQueries`/`listIdbRules` は file 毎回再読込。ただし IDB rule edn は CRUD 経由でのみ refresh されるので、手編集後は最初の CRUD or `datalog_reset` 等で発火する
`bun run build:ui` のみ (UI bundle 差分)	不要	`loadBundle()` は visualize 毎回 disk 読込 → 次の `datalog_visualize` で新 bundle 反映
`bun run build` 全体 (bin 再生成)	要	MCP host が新 bin を読み直すため
新 MCP tool 追加 / Zod schema 変更	要	bin 再生成必須 + tool 一覧は connect 時取得

機能完了の前に必ず: 想定 user 操作 (例: create → test → list / reset → re-sync → visualize) を vitest で e2e shape のテスト にし、reconnect 無しで pass することを確認する。

statuteDescription (要点)

audit query (= datalog_audit_create / datalog_audit_update) で 必ず埋める 3 つ目の description。税理士 / 会計士が税法・会計基準と同じ語彙・文体で読めるよう、条文風 + 箇条書きの Markdown を持つ (新規作成時は caller 未提供でも userDescription + engineerDescription から draft 生成、update 時は既存値を必ず引き継ぐ)。DomainPredicate (= datalog_predicate_create / datalog_predicate_update) では不要。

書式規約 (記号優先・主語明示・出典は確証時のみ)、3 系統 description の役割分担、few-shot 例 (収支区分矛盾 / 帳簿要件 / 36 協定)、強制ルールは statute-description を参照。