almanac — リポジトリ内ナレッジWiki CLI

CodeAlmanac の「リポジトリ内 Wiki + search + ingest + garden」の思想を、macOS 依存（launchd/Codex）を除いた汎用ツールとして移植したもの。

プロジェクトが分岐・並行作業が増えても「今何が実装されているか」「過去に何を決めたか」を引ける単一の真実源を、各リポジトリの almanac/ に保ち、二重実装を防ぐ。

特徴

• 単一スクリプト（stdlib + pyyaml のみ、Python 3.8+）
• CWD から almanac/ を自動検出 → PATH に symlink してどのプロジェクトでも almanac search ... と叩ける
• 設定は各プロジェクトの almanac.yaml（取り込み源・ヒント・鮮度閾値を上書き可）
• ingest は「取り込み会計」: 本文合成は人間/エージェントが行い、CLI は「何が wiki に反映済みか」を追跡して知識の置き忘れ（_agent_out/ 等の墓場化）を防ぐ
• init --agents で各プロジェクトの AGENTS.md に運用ルールを追記（冪等）

インストール

# このリポジトリを clone して、スクリプトへ symlink
ln -s "$(pwd)/almanac.py" ~/.local/bin/almanac

--root <path> / 環境変数 ALMANAC_ROOT で明示指定も可能。省略時は CWD から上方向へ almanac/ を探す。

使い方

# プロジェクトに almanac/ を生成（運用ルール付き AGENTS.md も）
cd your-project
almanac init --agents

# 作業前: 実装済み・不採用を確認（二重実装防止）
almanac search "トレーリング"
almanac show inventory/002-signals

# 閲覧・健全性
almanac topics
almanac health && almanac validate && almanac garden

# 取り込み会計
almanac ingest --scan                      # 未取り込み候補を一覧
almanac ingest --record <ページ> <source...>  # 反映後に記録
almanac ingest --status                    # 状況確認

設定（各プロジェクト直下の almanac.yaml）

almanac_dir: almanac        # wiki ディレクトリ名（デフォルト: almanac）
stale_days: 90              # garden の未更新判定（日）
ingest:
  sources:                  # 取り込み対象ディレクトリ（root 相対）
    - docs
    - _agent_out
  git_commits: 60           # 対象コミット数（0 で無効）
  hints:                    # ファイル名サブストリング → 推奨ページ
    signal: inventory/002-signals
    executor: inventory/004-livetrade-venues

生成される almanac/ 構成

almanac/
├── README.md          # 索引・運用ルール
├── topics.yaml        # トピック別ページ整理
├── inventory/         # 実装済み一覧（二重実装防止の核心）
│   ├── README.md
│   └── 001-…〜008-…    # ドメイン別ページ（雛形）
├── decisions/         # 設計判断（ADR、1ページ=1判断、status: accepted/rejected 等）
├── architecture/      # フロー・不変条件・落とし穴
├── guides/            # 運用ランブック
└── .state/            # 取り込み会計（gitignore 推奨・コミットしない）

ページの先頭フロントマター（health が参照）:

<!-- status: active -->
<!-- updated: YYYY-MM-DD -->
<!-- sources: docs/xxx.md, git:hash など -->

テスト

python -m pytest tests/ -q        # 一時プロジェクトで自己完結（実リポジトリ非依存）

既知の制約・将来

• 検索は全文走査（索引なし）。ページが数百を超え遅くなったら SQLite 索引を後付け。
• 定期整理（garden）の自動化は systemd timer / cron で almanac garden を定期実行すればよい。
• 本家との互換性: 生成する almanac/ は本家 CodeAlmanac の自動検出条件（almanac/topics.yaml + almanac/README.md）に一致するため、Mac があれば本家を「お掃除役」として併用できる。