Metadata-Version: 2.5
Name: docsweep
Version: 0.5.0
Summary: Sweep, triage and archive AI coding agents' plan/bugfix/pending Markdown across projects.
Project-URL: Homepage, https://github.com/ishizakahiroshi/docsweep
Project-URL: Repository, https://github.com/ishizakahiroshi/docsweep
Author-email: ishizakahiroshi <ishizakahiroshi.dev@gmail.com>
License-Expression: MIT
License-File: LICENSE
License-File: NOTICES.md
Keywords: ai-agents,archive,claude-code,cli,codex,markdown,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: pyyaml>=6.0
Provides-Extra: all
Requires-Dist: fastapi>=0.110; extra == 'all'
Requires-Dist: jinja2>=3.1.6; extra == 'all'
Requires-Dist: markdown>=3.6; extra == 'all'
Requires-Dist: mcp<2,>=1.28.1; extra == 'all'
Requires-Dist: nh3>=0.2; extra == 'all'
Requires-Dist: python-multipart>=0.0.30; extra == 'all'
Requires-Dist: questionary>=2.0; extra == 'all'
Requires-Dist: sentence-transformers>=2.0; extra == 'all'
Requires-Dist: starlette>=1.3.1; extra == 'all'
Requires-Dist: uvicorn>=0.29; extra == 'all'
Requires-Dist: watchdog>=4.0; extra == 'all'
Provides-Extra: all-lite
Requires-Dist: fastapi>=0.110; extra == 'all-lite'
Requires-Dist: jinja2>=3.1.6; extra == 'all-lite'
Requires-Dist: markdown>=3.6; extra == 'all-lite'
Requires-Dist: mcp<2,>=1.28.1; extra == 'all-lite'
Requires-Dist: nh3>=0.2; extra == 'all-lite'
Requires-Dist: python-multipart>=0.0.30; extra == 'all-lite'
Requires-Dist: questionary>=2.0; extra == 'all-lite'
Requires-Dist: starlette>=1.3.1; extra == 'all-lite'
Requires-Dist: uvicorn>=0.29; extra == 'all-lite'
Requires-Dist: watchdog>=4.0; extra == 'all-lite'
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.28.1; extra == 'mcp'
Provides-Extra: resurrect
Requires-Dist: sentence-transformers>=2.0; extra == 'resurrect'
Provides-Extra: review
Requires-Dist: questionary>=2.0; extra == 'review'
Provides-Extra: watch
Requires-Dist: watchdog>=4.0; extra == 'watch'
Provides-Extra: web
Requires-Dist: fastapi>=0.110; extra == 'web'
Requires-Dist: jinja2>=3.1.6; extra == 'web'
Requires-Dist: markdown>=3.6; extra == 'web'
Requires-Dist: nh3>=0.2; extra == 'web'
Requires-Dist: python-multipart>=0.0.30; extra == 'web'
Requires-Dist: starlette>=1.3.1; extra == 'web'
Requires-Dist: uvicorn>=0.29; extra == 'web'
Description-Content-Type: text/markdown

# docsweep

> English version: [README.en.md](README.en.md)

AI コーディングツール（Claude Code / Codex 等）が生成する `plan_*.md` / `bugfix_*.md` /
`pending_*.md` の **蓄積・陳腐化問題を解決する** クロスプラットフォーム CLI + Web UI ツール。

H1 ステータスラベル（`[完了]` / `[計画]` / `[廃止]` 等）を機械的に読み取り、完了を各プロジェクトの
`archive/` へ自動移送し、陳腐化を「要判断」フラグで可視化し、複数プロジェクトを横断 INDEX で一望できます。

## OKF（Open Knowledge Format）v0.2 対応

docsweep は [OKF v0.2 の公式仕様](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
に合わせ、Markdown frontmatter の `type` / `status` を機械可読に扱います。
OKF の `status` は文書ライフサイクル（`draft` / `stable` / `deprecated`）なので、
docsweep の作業状態（`planned` / `in-progress` / `watching` / `done` / `discarded` /
`pending`）は拡張フィールド `docsweep_state` に分離しています。

`type` と追加フィールドは OKF の方針どおり閉じた登録簿にせず、docsweep が標準管理する
`plan` / `bugfix` / `pending` 以外も壊さず保持します。`manual` / `reference` / `setup` は
静的な知識文書として扱い、H1 ラベルは
人間向け表示として併用し、旧形式の `status: planned` なども読み取り互換を維持します。
既存ファイルを移行するときは `migrate-frontmatter --dry-run` で差分を確認してから
`--apply` を実行してください。

詳細な対応表は [docs/okf-mapping.md](docs/okf-mapping.md)、Bundle の構造は
[docs/okf-export-format.md](docs/okf-export-format.md) を参照してください。

## インストール

```bash
pip install docsweep                  # コア + CLI（wings の主要コマンド・SQLite 索引込み）
pip install 'docsweep[all]'           # Web UI / 対話レビュー / MCP / watch / resurrect も含む
pip install 'docsweep[watch]'         # index-watch のみ追加（watchdog）
pip install 'docsweep[resurrect]'     # resurrect の embedding 経路（sentence-transformers）
```

docsweep は **PATH に `docsweep` コマンドを通さない運用を標準**にしています。
CLI / Web UI / MCP は、Python 実行ファイルから module として起動できます。

```bash
python -m docsweep triage
python -m docsweep mcp
python -m docsweep serve --root ~/dev
```

MCP クライアントへ登録する場合も、`docsweep mcp` ではなく `python -m docsweep mcp`
を推奨します。より再現性を上げるなら、`command` には Python 実行ファイルの絶対パスを指定します。

```json
{
  "mcpServers": {
    "docsweep": {
      "command": "C:\\Users\\you\\AppData\\Local\\Programs\\Python\\Python312\\python.exe",
      "args": ["-m", "docsweep", "mcp"]
    }
  }
}
```

> 上記の `Python312` は **インストールされている Python のバージョンに置き換えてください**。
> 確認方法: Windows は `where python`、macOS / Linux は `which python3`。
> もしくは `python -c "import sys; print(sys.executable)"` でフルパスが取れます。

`docsweep ...` は Python の Scripts/bin ディレクトリが PATH に入っている環境向けの短縮形です。

## インストール後どこに置かれて、どう使えるか（OS 別）

`pip install docsweep` は **Python の site-packages にライブラリを配置**します。
別バイナリは生成されず、`python -m docsweep ...` で起動するのが標準動線です。

### 共通の挙動

- **`docsweep/` パッケージ本体**: 起動中の Python が解決する site-packages に展開される
- **設定・状態**: `~/.docsweep/`（全 OS 共通の論理パス）
- **MCP 設定**: AI クライアント（Claude Code 等）の設定ファイルに `python -m docsweep mcp` を 1 行登録するだけ
- **PATH 設定不要**: `docsweep` を PATH に通さなくても、`python -m docsweep ...` ですべての機能にアクセス可能

### Windows

| 項目 | 場所 |
|---|---|
| Python 実体（per-user 標準インストール） | `C:\Users\<you>\AppData\Local\Programs\Python\Python3XX\python.exe` |
| docsweep 本体（pip install 後） | `C:\Users\<you>\AppData\Local\Programs\Python\Python3XX\Lib\site-packages\docsweep\` |
| docsweep 設定・状態 | `C:\Users\<you>\.docsweep\`（= `%USERPROFILE%\.docsweep\` = `~/.docsweep`） |
| `docsweep` ショートカット | `...\Python3XX\Scripts\docsweep.exe`（PATH 通っていれば `docsweep` 直で起動可） |

> **Windows ストア版 Python は避けることを推奨**。`%LOCALAPPDATA%\Microsoft\WindowsApps\python.exe`
> 経由のストア版は仮想ストア配置の制約で **`Scripts/` ディレクトリへの書き込みが弾かれる**ことがあり、
> `pip install` 自体は通っても `docsweep.exe` ランチャーが正しく作られない／PATH に乗らないトラブルが
> 起きます。python.org 配布のインストーラ（per-user）か pyenv-win を使うのが安全です。

```powershell
# インストール
pip install 'docsweep[all]'

# 起動（PATH を気にせず常に動く形）
python -m docsweep triage
python -m docsweep serve --root D:\dev
python -m docsweep mcp

# MCP 登録例（~\.claude\mcp.json）— 絶対パスにすると Python 切替時も安定
# {
#   "mcpServers": {
#     "docsweep": {
#       "command": "C:\\Users\\you\\AppData\\Local\\Programs\\Python\\Python312\\python.exe",
#       "args": ["-m", "docsweep", "mcp"]
#     }
#   }
# }
# Python312 は実環境のバージョンに置換。確認: `where python` または `python -c "import sys; print(sys.executable)"`
```

### macOS

| 項目 | 場所 |
|---|---|
| Python 実体（Homebrew 例） | `/opt/homebrew/bin/python3` (Apple Silicon) / `/usr/local/bin/python3` (Intel) |
| docsweep 本体 | `/opt/homebrew/lib/python3.XX/site-packages/docsweep/` 等（`python3 -m site` で確認） |
| docsweep 設定・状態 | `~/.docsweep/`（＝ `/Users/<you>/.docsweep/`） |
| `docsweep` ショートカット | `/opt/homebrew/bin/docsweep` 等（PATH に既に入っていることが多い） |

```bash
# インストール（PEP 668 で system Python 保護がかかっていれば --user か venv 経由を選ぶ）
pip3 install 'docsweep[all]'

# 起動
python3 -m docsweep triage
python3 -m docsweep serve --root ~/dev
python3 -m docsweep mcp

# MCP 登録例（~/.claude/mcp.json）
# {
#   "mcpServers": {
#     "docsweep": {
#       "command": "/opt/homebrew/bin/python3",
#       "args": ["-m", "docsweep", "mcp"]
#     }
#   }
# }
# 自環境の Python パスは `which python3` で確認
```

### Linux

> **PEP 668 注意（Ubuntu 23.04+ / Debian 12+ / Fedora 38+ など）**: 近年の distro は system Python を保護しており、
> 素の `pip install` は `error: externally-managed-environment` で拒否されます。
> 解決策は **venv** か **`--user`** か **pipx** のいずれか（下記コマンド例の通り）。
> `--break-system-packages` フラグでの強行は OS 管理パッケージとコンフリクトする原因になるので推奨しません。

| 項目 | 場所 |
|---|---|
| Python 実体（distro pkg / pyenv 等） | `/usr/bin/python3` / `~/.pyenv/versions/3.XX.X/bin/python` 等 |
| docsweep 本体 | `/usr/lib/python3.XX/site-packages/docsweep/` か `~/.local/lib/python3.XX/site-packages/docsweep/`（`--user` 利用時） |
| docsweep 設定・状態 | `~/.docsweep/` |
| `docsweep` ショートカット | `/usr/local/bin/docsweep` / `~/.local/bin/docsweep`（PATH に `~/.local/bin` が無い distro では PATH 設定要） |

```bash
# 多くの distro は system Python を pip で汚せない。venv か --user か pipx を推奨
python3 -m venv ~/.venvs/docsweep && source ~/.venvs/docsweep/bin/activate
pip install 'docsweep[all]'

# または
pip install --user 'docsweep[all]'

# 起動
python3 -m docsweep triage
python3 -m docsweep serve --root ~/dev
python3 -m docsweep mcp

# MCP 登録例（~/.claude/mcp.json）— venv 内 Python の絶対パスを指定する
# {
#   "mcpServers": {
#     "docsweep": {
#       "command": "/home/you/.venvs/docsweep/bin/python",
#       "args": ["-m", "docsweep", "mcp"]
#     }
#   }
# }
# 自環境の Python パスは `which python3` で確認
```

### インストール形態を選ぶ

| 方式 | 向き不向き |
|---|---|
| **直接 `pip install`**（ユーザー Python に入れる） | 個人ツールとして気軽に使いたい時。最短手数 |
| **venv 隔離**（`python -m venv ...` で専用環境） | 依存をユーザー Python に混ぜたくない時。MCP 設定は venv 内 Python の絶対パスを書く |
| **pipx**（CLI として隔離 install） | docsweep CLI だけ使う時。MCP からは pipx の内部 venv Python を絶対パス指定 |
| **`pip install -e .`**（リポを clone して editable install） | 自分で docsweep を開発・拡張する時。src 編集が即反映 |

### アンインストール

```bash
pip uninstall docsweep
# 設定を消したい場合は別途
rm -rf ~/.docsweep                # macOS / Linux
Remove-Item -Recurse ~/.docsweep  # Windows PowerShell
```

## 使い方

> **朝の入口は `brief`**: 何も思い出せなくても `python -m docsweep brief` で「今日の 1 個」が断定的に出ます。
> プロジェクト横断は `python -m docsweep cross`。詳細: [docs/ai-agent-integration.md](docs/ai-agent-integration.md)。

```bash
# === wings（v0.2 系）の主要新コマンド ===

# 朝の入口 — 今日 1 個だけやろうを断定する（cwd プロジェクト）
python -m docsweep brief
python -m docsweep brief --all              # 全プロジェクト横並び要約
python -m docsweep brief --continue         # 末尾の対話を出さず context を即クリップボードへ

# 全プロジェクト束ねた俯瞰 — top_pick + 凍結予備軍 + project_summaries
python -m docsweep cross
python -m docsweep cross --project alpha,beta
python -m docsweep cross --explain plan_x.md   # スコア内訳

# 会話履歴から plan/bugfix/pending の草案を抽出（heuristic / LLM mock）
python -m docsweep capture --from clipboard
python -m docsweep capture --from file ./conv.md --save-all

# plan の「変更予定ファイル」と実装実態の整合チェック
python -m docsweep linkcheck --json

# 親 plan と child plan の closeout 検査（read-only。状態変更・archive はしない）
python -m docsweep closeout-check --path docs/local/plan_<parent>.md --to watching --json

# 状態遷移を提案（ruleset / 将来 LLM 委譲）+ 一括適用
python -m docsweep auto-triage --suggest > decisions.json
python -m docsweep auto-triage --apply decisions.json --dry-run

# 関係性ネットワーク（plan/bugfix/pending と frontmatter related のグラフ）
python -m docsweep graph --json

# archive と現役の類似ペアを抽出（embedding opt-in / 既定は Jaccard）
python -m docsweep resurrect --threshold 0.5

# SQLite 索引 ~/.docsweep/index.db
python -m docsweep index-sync               # 差分のみ取り込み（高速）
python -m docsweep index-rebuild            # 全件再構築
python -m docsweep index-watch              # ファイル監視で自動同期（watchdog 必要）

# === 従来コマンド（既存・後方互換） ===

# スキャン（既定は要判断＋保留のみ表示）
python -m docsweep --root ~/dev
python -m docsweep ./thisproject            # config 不要の単発スキャン
python -m docsweep scan --all --json        # 全件を機械可読 JSON で

# 自動移送（cron / CI / AI 委譲向け・非対話）。done/discarded のみ・様子見は守る
python -m docsweep sweep --dry-run
python -m docsweep sweep

# 横断 INDEX を再生成（.docsweep/INDEX.md と INDEX.json）
python -m docsweep index
python -m docsweep pending                  # 全プロジェクトの [保留] だけ一発表示
python -m docsweep report                   # 人間向け週次レポート
python -m docsweep summary                  # AI に渡す圧縮 JSON

# リリース整理（様子見をまとめて完了へ昇格し archive へ）
python -m docsweep promote --state watching --to done
# 卒業期限が来た様子見だけを下見／昇格（due 当日を含む）
python -m docsweep promote --due-expired --dry-run
python -m docsweep promote --due-expired

# 今回だけ卒業期限を今日 + 5 日に上書き（設定ファイルは変更しない）
python -m docsweep apply --path <plan-or-bugfix.md> --action relabel --to watching --watching-days 5

# 対話チェックリスト（人間専用）
python -m docsweep review

# テンプレ即生成
python -m docsweep new plan my-topic
python -m docsweep new bugfix crash-on-start
python -m docsweep new plan my-topic --split 3  # child に docsweep_parent を付ける

# OKF 互換 zip でエクスポート（docsweep を抜けても md が腐らないことを実演する材料）
python -m docsweep export --okf                          # ./docsweep-okf-<date>.zip
python -m docsweep export --okf --out /tmp/snapshot.zip  # 出力先を明示
python -m docsweep export --okf --include-archive        # archive/ 配下も含める

# 任意 Bundle を read-only 検査（未知 type / 追加キー / 壊れた link は警告扱い）
python -m docsweep okf-check ./bundle --json
python -m docsweep okf-profiles

# profile は既定では同梱 JSON。外部 profile は明示したときだけ取得する
python -m docsweep export --okf --okf-profile ./okf-profile.json
python -m docsweep okf-check ./bundle --okf-profile https://raw.githubusercontent.com/<org>/<repo>/<sha>/okf.json --okf-profile-sha256 <sha256>

# 運用ルールを各プロジェクトへ注入／取り消し（CLAUDE.md=正本・AGENTS.md はそこを指すポインタ）
python -m docsweep inject --project ./foo --preset claude-jp
python -m docsweep inject --project ./foo --no-guidance   # 導線を省きラベル節だけ（導線をグローバルに寄せる場合）
python -m docsweep eject  --project ./foo                  # 管理ブロックだけ剥がす（手書きは温存。--purge で .docsweep.yaml も）

# 個人グローバルへ「セッション開始時に triage を読む」導線＋due ルールを一度だけ注入（全プロジェクトで有効）
python -m docsweep inject --global                         # 既定 agent=claude（~/.claude/CLAUDE.md に @import 1 行）
python -m docsweep inject --global --agent codex           # ~/.codex/AGENTS.md にインライン（CODEX_HOME 尊重）
python -m docsweep inject --global --lang en               # 注入文言を英語で生成（プロジェクト注入でも --lang 可）
python -m docsweep eject  --global

python -m docsweep list                                    # 注入済み（プロジェクト＋グローバル）一覧

# Web UI（UX 主役・127.0.0.1・初回だけ ?token= 付き URL、以降は Cookie で /board を直接開ける）。注入/解除もダッシュボードから（プレビュー必須）
python -m docsweep serve --root ~/dev

# MCP サーバー（AI エージェント面・stdio）
python -m docsweep mcp
```

Web UI（看板）はこんな見た目です。

![やり忘れ列](assets/screenshots/webui-todo.png)

「完了」「廃止」になったカードは archive 候補列にまとまり、まとめて archive へ送れます。

![archive 候補列](assets/screenshots/webui-archive.png)

## 状態モデル（一直線・単一正本）

```
plan:    [保留] → [計画] → [実行中] → [様子見] → [完了]
bugfix:           [実行中] → [様子見] → [完了]
         （どちらも、どの状態からでも [廃止] へ分岐できる）
```

- **`[様子見]`** = 直したが寝かせ中。**自動移送されません**（再発確認の待機列として守る）。
- **`[完了]` / `[廃止]`** だけが archive 対象。`[廃止]` は削除ではなく archive へ隔離（復元可能）。
- 移送先は `archive_dir` を明示しなければ **work queue に連動**します。`work_policy: private`
  （既定）なら `<work_dir>/archive`（既定 `docs/local/archive`）、`shared` なら repo 直下
  `archive/`。private な作業文書を git 追跡され得る場所へ黙って出さないための既定です。
  移送先と選択根拠は `python -m docsweep sweep --dry-run --json` の `archive_routes` で
  確認できます。
- ラベル語彙・archive 可否・自動移送可否は `states:` 設定が **唯一の正本**で、検出・Web 表示・
  注入テンプレを全部そこから導出します。

## 設定の層

優先順位 **① CLI フラグ > ② プロジェクト `.docsweep.yaml` > ③ グローバル `~/.docsweep/config.yaml`**。
グローバルだけ書けば体感 1 層。`.docsweep.yaml` は置いた時だけ部分上書きで効きます。

### よくある 3 パターン（グローバル `~/.docsweep/config.yaml`）

プロジェクト境界は `.git` / `package.json` / `pyproject.toml` 等の実体マーカーで自動判定するので、
**root の中で各プロジェクトがどの深さにあっても OK**（フォルダ階層を決め打ちしない）。

**A. 1 つの親ディレクトリ以下を丸ごと管理**

```yaml
roots:
  - ~/dev
```

**B. 飛び飛びの複数ディレクトリを管理**

```yaml
roots:
  - ~/dev/github/public
  - ~/dev/works/clientA
  - ~/dev/works/clientB
  - /d/sandbox/experiments
```

**C. 用途別に切り替えたい（profiles）**

```yaml
roots:
  - ~/dev/github/public        # 既定（無引数）で見る範囲
profiles:
  work:                         # python -m docsweep triage --profile work
    - ~/dev/works/clientA
    - ~/dev/works/clientB
  all:                          # python -m docsweep triage --profile all
    - ~/dev/github/public
    - ~/dev/works
```

**一回きりの単発スキャン**は config を書かずに位置引数で指定もできます:

```bash
python -m docsweep triage ~/dev/foo ~/projects/bar
```

### 作業 queue と private ドキュメント

`new` / `capture --save-all` / MCP `capture_save` は、同じプロジェクト相対 `work_dir` に保存します。
未設定時の既定は `docs/local` で、プロジェクトに `docs/` があるかどうかで保存先は変わりません。

```yaml
work_dir: docs/local       # プロジェクト相対。例: docs/ai
work_policy: private       # private は Git ignore / tracked 状態を保存前に検査
secret_policy: block       # high-confidence secret は拒否。warn / off も選択可
```

解決順は CLI の `--work-dir` / `--work-policy` / `--secret-policy`、プロジェクト設定、
グローバル設定の順です。private queue は `export` の既定対象から除外され、`brief` / `triage` は
Git ignore されていても設定済み queue を確認できます。秘密情報の警告や JSON / UI の表示には本文・値の一部を含めません。
必要な場合だけ `--allow-sensitive` を明示してください。

初回は `python -m docsweep init` で既定設定を作り、各プロジェクトでは
`python -m docsweep inject` の導線と `python -m docsweep new plan <topic>` を使います。

### 作成AIとC単位の実行AI（opt-in）

個人の `~/.docsweep/config.yaml` で provenance を有効にすると、新規work MDへ
`work_id`、固定の `ai_author_*`、`ai_execution_refs` を追加し、実行本体はリポ外の
個人台帳へ1実行1行で保存できます。

作成したセッションのtranscript（AI CLI 自身が残す生ログ）のフルパスを `ai_session_logs` に
記録します。md の記述だけでは追えない判断の経緯へ、後から会話ログで戻れるようにするためです。
記録するのはパスだけで中身は読みません。`work_policy: private` のqueueに限り、かつ実在する
ときだけ書きます。

plan は複数セッションにまたがるため、`provenance start` でC実行を開始したときにも
そのセッションのパスを**追記**します（同じパスは重複しません）。作成時の1本だけでは
C2以降を誰がどの会話で実装したのか追えないためです。解決できないセッションでは
キー自体を書きません（`unknown` のような偽の値を置きません）。

対応は Claude Code / Codex / Grok / Copilot / Cursor Agent です。Claude Code はセッションIDを
環境変数に出すため確実に一致します。それ以外は「作業ディレクトリが一致し、直近まで書かれ続けて
いるセッションが1つだけ」のときに限って記録し、**2つ以上に絞れなければ何も書きません**
（別セッションのログを指すくらいなら残さない）。opencode は全セッションが単一のSQLiteに集約され
1セッションを特定できないため対象外です。自動解決できないときは `--ai-session-log <path>` で
明示するか、`DOCSWEEP_AI_SESSION_LOG` を設定します。

```yaml
provenance:
  enabled: true
  manager: docsweep
  ledger: provenance/ai-executions.csv
  actor_key: your-key
```

新規作成時は現在AIの取得可能なmetadataを明示します。exact model IDを取得できない場合は
推測せず `unknown`、取得元は `unavailable` または実際の取得経路を指定します。

```bash
python -m docsweep new plan auth-refactor \
  --ai-agent codex --ai-runtime codex-cli --ai-provider openai \
  --ai-model-id unknown --ai-model-source unavailable
```

C単位の実装・レビュー・検証は作業前に開始し、返されたIDを終了時に閉じます。
`context配分` 表には `AI実行` 列が追加され、詳細metadataは台帳だけに保持されます。

```bash
python -m docsweep provenance start --path docs/local/plan_auth-refactor.md \
  --context C1 --role implementation --agent codex --runtime codex-cli \
  --provider openai --model-id unknown --model-source unavailable --json
python -m docsweep provenance finish --execution <AIX-ID> --result completed --json
python -m docsweep provenance check --path docs/local/plan_auth-refactor.md --json
```

provenance が有効なのに `--ai-*` / `--agent` を渡さなかった場合は、作成AIが `unknown` で
記録される前にstderrへ1行警告します（作成自体は成功します）。あとから実値へ直すときは
`provenance init --update` を使います。台帳のauthoring行とfrontmatterの `ai_author_*` を
まとめて更新し、`execution_id` / `work_id` / `started_at` は変えません。

```bash
python -m docsweep provenance init --update --path docs/local/plan_auth-refactor.md   --agent claude --runtime claude-code --provider anthropic   --model-id claude-opus-5 --model-display "Claude Opus 5" --model-source runtime --json
```

独自台帳を正典にするリポは `.docsweep.yaml` で `manager: repo` と `delegate_skill` を宣言します。
この場合、汎用コマンドは委譲を返し、個人の汎用台帳へ二重記録しません。

## AI エージェント連携

> **方針**: 「全 AI 対応」を最優先し、MCP を使わない AI でも **CLI 直叩き**（`--json`）で同じことが
> できるようにしています。自然言語起動の主役は **朝の入口**（`brief` / `cross` / `capture_extract`+`capture_save`）
> ですが、MCP サーバーが露出する tool は v0.5.0 時点で 24 個あり、md を書き換える `apply` / `update_status` /
> `archive_done` や、グローバル設定を書き換える `inject_global` / `eject_global` も含みます。
> 一覧と権限の目安・自然言語マッピング表は [docs/ai-agent-integration.md](docs/ai-agent-integration.md)。

### 推奨運用: MCP 登録せず CLI 一本化

各 AI ツール（Claude Code / Codex / Cursor …）に MCP サーバーを個別登録するより、
**CLI 経由（`python -m docsweep ...`）を AI に直接叩かせる運用**が最もシンプルです。

- インストール 1 回で全 AI ツールから使える（MCP 登録は AI ツールごとに別ファイル）
- 戻り値・triage の中身は MCP と同じ — AI から見た体験はほぼ変わらない
- 唯一の手間は **AI 側で `python -m docsweep` を allowlist に追加** すること

Claude Code の場合、`~/.claude/settings.json` の `permissions.allow` に 1 行追記:

```json
{
  "permissions": {
    "allow": [
      "Bash(python -m docsweep:*)"
    ]
  }
}
```

> docsweep からは **この JSON を自動で書き換えません**（権限境界の操作になるため）。
> ユーザーが意図的に貼り付ける運用に倒しています。MCP として使いたい場合は
> 上の「MCP 登録例」を使ってください（こちらも自動登録はしません）。

### triage の中身

`python -m docsweep triage`（または MCP の `triage` ツール）は、**要判断＋保留を古い順に絞った残作業**を
`counts` ＋ `items[]` ＋ `needs_fix[]` で返します。各 item は `rel`（相対パス）・`title`（H1）・
`state`（ラベル）・`type`・`age_days`・`summary`・`actions`（`discard`/`keep`/`resume`/`relabel`/`promote`
の閉じた集合）を持ち、エージェントは「次にどのファイルの何を続けるか」を判断 → `python -m docsweep apply` で
機械実行します。横断 INDEX 全体の俯瞰は `python -m docsweep summary`。docsweep 自身は AI API を叩きません（ベンダー非依存）。

セッション開始時に AI へ自動でこの残作業を渡すには `python -m docsweep inject --global`（Claude は `@import`、
Codex はインラインで「作業前に triage を読む」導線を個人グローバル設定へ一度だけ注入）。

### 特定プロジェクトだけ調べたい時（`--project`）

複数 root を横断管理していると、AI からの自然言語クエリは「全体」より
「`<このリポ>` だけ」になりがちです。`sweep` / `promote` / `triage` / `scan` / `summary` は
共通の `--project <name>` フラグでプロジェクト名（境界フォルダ名）に絞り込めます。

```bash
# 「many-ai-cli の archive 移送対象いくつ?」
python -m docsweep sweep --dry-run --project many-ai-cli

# 「docsweep プロジェクトの様子見昇格候補は?」
python -m docsweep promote --due-expired --dry-run --project docsweep

# 「many-ai-cli の残作業ある?」
python -m docsweep triage --project many-ai-cli

# 「docsweep プロジェクトの全件だけ JSON で吐いて」
python -m docsweep scan --all --project docsweep --json

# 「docsweep プロジェクトの俯瞰を圧縮 JSON で」
python -m docsweep summary --project docsweep
```

> 絞り込みは **スキャンルートを動かさず後段でフィルタ** します。各プロジェクトの `.gitignore`
> が `docs/local/` を除外していても、グローバル config の `roots:` から見えていれば対象になります
> （位置引数 `.` で当該プロジェクトを単発スキャンすると `.gitignore` で除外されて 0 件になる
> 落とし穴を回避するための設計）。
>
> `triage` / `summary` の `counts` も per-project スコープに揃えて返します（フィルタ後の
> `items` 数と一致するので、AI/人間どちらが見ても齟齬がありません）。

MCP 経由でも同じく引数で絞れます。例: `triage(project="many-ai-cli")` / `summary(project="docsweep")` /
`sweep(project="many-ai-cli", dry_run=True)`。CLI と MCP で引数名・挙動を完全に揃えています。

### プロジェクトを一覧・除外する（`docsweep project`）

`roots:` の下に 20〜30 個のリポジトリが並ぶと、看板にも `scan` にも関係ないプロジェクトが
混ざります。`docsweep project` で一覧の確認と除外の切り替えができます。

```bash
# 一覧（ON / OFF と未処理件数）
python -m docsweep project list

# 除外リストへ入れて board / scan から外す
python -m docsweep project disable D:/dev/github/public/foo

# 除外を解除
python -m docsweep project enable D:/dev/github/public/foo
```

除外は `~/.docsweep/excluded.json` に root の絶対パスとして記録され、**ファイルは一切動かしません**
（表示から外れるだけで archive も削除もしません）。Web UI ではプロジェクト行のトグルから、
MCP では `list_projects` / `set_project_enabled` から同じ操作ができます。

### 中身の入った状態で試す（`docsweep demo`）

自分のプロジェクトへ入れる前に触ってみたいときは、使い捨てのサンプルを作れます。

```bash
# 一時ディレクトリにサンプル project を作る（既存のプロジェクトには触りません）
python -m docsweep demo

# 出力された root を指定して見る
python -m docsweep triage --root <生成先>
python -m docsweep serve   --root <生成先>
```

overdue / 今日 / 未来 / 期日なし / 保留 / 完了 がそろった md が 8 本できるので、
看板も `triage` も空になりません。グローバル設定の `roots` には登録しないので、
使い終わったらフォルダごと消せます。`--dir` で生成先を指定できます。

### まとめて動かすときの確認（`bulk_confirm_threshold`）

一括 archive・一括ラベル変更・`promote` は 1 手で数十件を動かせます。対象件数が
しきい値以上のときだけ確認の段が 1 つ増えます（既定 20 件。しきい値未満は従来どおり）。

```yaml
# .docsweep.yaml または ~/.docsweep/config.yaml
bulk_confirm_threshold: 20   # 0 にすると常に確認する
metrics: true                # 連続日数・今週の片付け件数の表示（false で記録ごと停止）
```

Web はフレーズ（`ARCHIVE` / `RELABEL`）の打ち込みを求め、CLI の `promote` は `--yes` を
要求します。非対話を崩さないため、CLI は端末でもプロンプトを出しません。

詳細は [docs/conventions.md](docs/conventions.md) と
[templates/AGENT_GUIDE.md](templates/AGENT_GUIDE.md) を参照してください。

## ライセンス

MIT
