paper-harness-cli 0.5.0

CLI kernel for bootstrapping and maintaining paper-harness projects

paperops

paperops は、AI エージェントと論文を書くためのプロジェクトハーネスである。

人間が template/ を手でコピーして使う道具ではない。主導線は pops CLI で、Agent が安全に project state を初期化・診断・更新するための execution kernel として扱う。

最小セットアップ

新規論文プロジェクト:

uvx --from paper-harness-cli pops init paper-my-topic
cd paper-my-topic
uvx --from paper-harness-cli pops doctor

既存プロジェクトを CLI 管理へ寄せる:

cd paper-my-topic
uvx --from paper-harness-cli pops setup
uvx --from paper-harness-cli pops doctor

template/ はこのリポジトリ内の source of truth であり、paper-harness-cli パッケージに bundled scaffold として同梱される。 pops は uvx --from paper-harness-cli pops ... で実行する。.venv は CLI 用ではなく、論文プロジェクトの Python 実行環境が必要な場合に make venv で作成する。

AI 前提の作業ループ

日常運用の主役は、CLI そのものではなく Agent との会話である。

1. 人間が論文トピック、制約、投稿先候補、判断を伝える。
2. Agent が evidence/、claims/、review/、requests/ のカードを正本として整え、notes/views/ で俯瞰できるようにする。
3. uvx --from paper-harness-cli pops ... が init / setup / doctor / update-paperops のような決定的操作を担う。
4. 原稿は manuscript/ja を中心に進め、必要な block を manuscript/en へ同期する。
5. 関連研究や外部情報源を集める場合は /source-reach-scan で source channel と raw capture 方針を決め、/research-related-work で調査対象と field framework を作り、raw findings を refs/research/、採用文献を refs/summaries/ と .bib、議論を notes/related-work-map.md へ分ける。
6. 投稿前の模擬査読は /peer-review-manuscript、実査読コメントへの返答は /respond-to-peer-review で review/ のカードと notes/views/peer-review.md へ整理する。
7. 実験結果や外部ディレクトリが必要なら refs/links.toml と refs/local/locations.toml で link を解決し、runops project は MCP の read / inspect / plan tool から確認する。
8. 追加解析・図表・実験要望は requests/analysis/ に残し、notes/views/research-requests.md で俯瞰してから runops 側の research/paper_requests.toml へ handoff する。
9. 人間が原稿レビューやプロンプト指示を出した場合は /integrate-writing-feedback で feedback card にし、claim / gate / evidence / request / manuscript へ遡って反映する。
10. 構成やハーネスの違和感をまだ修正に固定したくない場合は /open-paper-scan で俯瞰し、採用する idea だけ後段の skill へ渡す。
11. 共有前に make ci、投稿前に make pre-submit でハーネスのゲートを通す。
12. 再利用可能な摩擦は /feedback-paper-harness で上流 paperops に戻す。

CLI の詳細は docs/cli.md を参照する。

コア設計思想

• template/ は個別論文リポジトリに展開される scaffold の source of truth。
• src/paperops/ は template/ を展開・診断・更新する薄い CLI。
• evidence/ は result / figure / source card の正本。raw result、figure data、analysis artifact を claim に昇格する前の証拠単位へ束ねる。
• claims/ は claim / scientific gate / argument card の正本。Abstract、Conclusion、主要図表へ出してよい主張だけを明示する。
• review/ と requests/ は、人間レビュー、査読コメント、追加解析、改稿依頼をカード化し、原稿への指摘を上流へ遡らせるための層。
• notes/ はセッション継続性、外部ソース到達、関連研究、読者モデル、AI 初稿 polish、AI 利用ログ、notes/views/ の俯瞰ビューを持つ共有 memory。作業用ドキュメントは日本語で書く。
• manuscript/ja と manuscript/en は block ID で対応するバイリンガル原稿。
• refs/ は raw PDF 置き場ではなく、キュレーション済みの参照知識層、関連研究の調査設計、source reach の一時領域、外部 project link 台帳。作業用ドキュメントは日本語で書く。
• refs/links.toml は共有可能な link intent を持ち、個人環境の絶対パスは ignored な refs/local/locations.toml に分離する。
• submission/<venue>/ は投稿先公式テンプレートと最終提出用 TeX の隔離スロット。
• pops update-paperops はハーネス管理ファイルだけを扱い、下流固有の manuscript/、notes/、refs/、submission/ を自動上書きしない。

runops / 外部 project link

論文を書きながら実験結果、図表ソース、外部ノート、データセットを参照する場合、共有ファイルには絶対パスを書かず、refs/links.toml に link の意味だけを記録する。実パスは refs/local/locations.toml に置き、pops links list --resolve-local と /resolve-local-paths で解決する。

kind = "runops_project" の link は runops MCP 連携の入口である。既存結果は runops.analysis.artifacts、runops.survey.summary、runops.publication.exports.list で確認し、追加要望は requests/analysis/ に記録してから runops.paper.request.draft で検証し、人間確認後に runops project の research/paper_requests.toml へ渡す。詳細は docs/cli.md と docs/skill-catalog.md を参照する。

リポジトリ構成

• src/paperops/: pops CLI
• template/: 論文プロジェクトに展開される scaffold
• .github/workflows/: 下流論文リポジトリから呼び出し可能な再利用可能 GitHub Actions workflow
• .github/ISSUE_TEMPLATE/: テンプレート改善、スキル要求、構造変更の Issue フォーム
• .claude/skills/, .agents/skills/: テンプレート保守用 skill
• docs/: アーキテクチャ、変更ポリシー、トリアージルール、CLI と配布方針
• tests/: pops CLI の最小 smoke tests

スキャフォールドが最適化するもの

• refs/: 生の PDF 置き場ではなく共有知識層として活用
• refs/source-reach/ と /source-reach-scan: 外部 Web、GitHub、動画、RSS、SNS などの source channel、到達経路、raw capture、credential risk を分ける
• refs/research/ と /research-related-work: 関連研究の outline / field framework / raw findings / 議論を分け、採用する文献だけ refs/summaries/ と .bib へ昇格
• /peer-review-manuscript と /respond-to-peer-review: 模擬査読、major/minor comment、response matrix、revision plan を review/ のカードへ整理
• /integrate-writing-feedback: 人間の原稿レビューや自然文指示を feedback card にし、claim / gate / evidence / request / manuscript へ遡って反映
• notes/views/: カード正本から見た result pattern、claim-evidence、scientific gate、peer-review、request の俯瞰ビュー
• 日本語・英語の原稿をブロックレベルのミラーとして追跡
• submission/<venue>/: 投稿先公式テンプレートと最終提出用 TeX の分離
• manuscript/publication-metadata.toml、notes/ai-use.md、notes/reproducibility.md: 公開メタデータ、AI 利用開示、計算環境、図表 provenance の投稿前確認
• make pre-submit: make ci に加えて引用サマリー、strict mirror freshness、submission slot、スタータープレースホルダー、workflow 参照、公開メタデータ不足を検出
• make argument-focus-check: AI 初稿が条件数列挙、防御的 caveat、ローカル実行ログに寄りすぎていないかを advisory に検出
• /map-result-patterns: simulation results や figure data を本文の主張へ直接流し込む前に、result pattern / evidence packet として中間層へ束ねる
• /scientific-gate: 中心主張、Abstract、Conclusion、主要図表の claim readiness と人間承認を確認
• /polish-ai-draft: AI 初稿の定型臭を、主張・証拠・AI 利用開示を保ったまま整える
• /open-paper-scan: 改善指示を局所修正へ閉じる前に、原稿・読者体験・執筆ハーネスを発散的に眺める
• make citation-check: TeX 本文中の citation key と .bib の不整合を早期検出
• make public-terms-check / make claim-evidence-check: 内部語の公開本文混入と supported claim の evidence 対応を早期検出
• make mirror-freshness-check / make mirror-strict-check / make submission-drift-check: 日英 block の同期鮮度と投稿版への科学的変更戻し忘れを点検
• make skill-mirror-check: .agents/skills/ の共通 skill 実体と .claude/skills/ の Claude Code wrapper が対応しているかを点検
• scripts/build-ja.sh / scripts/build-en.sh: \input / \include / \includegraphics / bibliography / style 参照の構造検証を行い、TeX 環境があれば PDF ビルドへ進む
• 下流論文リポジトリ用の Issue フォーム: 原稿レビュー、エビデンス不足、ハーネス摩擦を分けて収集
• テンプレート自体の再利用可能な保守ワークフロー
• プロジェクトローカルの Claude / Codex スキル、フック、運用ルール

CLI

uvx --from paper-harness-cli pops init paper-my-topic
uvx --from paper-harness-cli pops setup
uvx --from paper-harness-cli pops doctor
uvx --from paper-harness-cli pops update-paperops --dry-run
uvx --from paper-harness-cli pops update-paperops --plan
uvx --from paper-harness-cli pops links list --resolve-local
uvx --from paper-harness-cli pops links check
uvx --from paper-harness-cli pops migrate --apply
uvx --from paper-harness-cli pops feedback
uvx --from paper-harness-cli pops version

このコマンド面は uvx 経由に一本化する。実装は小さく保ち、既存 skill と Makefile の運用を壊さないことを優先する。 version を跨ぐ scaffold 更新では、update-paperops --plan で minor checkpoint ごとの upgrade chain を確認し、必要に応じて --apply-chain で exact version の pops を順に呼び替える。詳細は docs/upgrade-policy.md を参照する。

PyPI 公開

paper-harness-cli は release publish または手動 dispatch で PyPI に公開する。 GitHub Actions の PyPI 公開 workflow は distribution を build / check し、PyPI Trusted Publishing で paper-harness-cli にアップロードする。 PyPI 側では trusted publisher として、この repository、workflow .github/workflows/publish-pypi.yml、environment pypi を設定しておく。

開発と検証

テンプレートは完全な TeX 環境を前提とせず、軽量なローカルチェックを提供する。 scripts/build-ja.sh と scripts/build-en.sh は latexmk が利用可能な場合はコンパイルを行い、そうでなければ scripts/check-tex-structure.py による構造検証にフォールバックするため、クリーンなランナーでも CI が執筆ハーネスを実行できる。 開発時のローカルセットアップは、リポジトリローカルの .venv 内の Python 3.11 以上である。

make venv
make smoke
python -m pip wheel . --no-deps -w .codex-tmp/wheelhouse

上流リファレンス

フックと設定のレイアウトは Anthropic の Claude Code ドキュメントのプロジェクト設定とフックに準拠しており、GitHub 自動化ファイルは GitHub の再利用可能ワークフローと Issue フォームのドキュメントに準拠している:

• https://code.claude.com/docs/en/settings
• https://code.claude.com/docs/en/hooks
• https://docs.github.com/en/actions/reference/workflows-and-actions/reusing-workflow-configurations
• https://docs.github.com/en/enterprise-cloud@latest/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms