office-review-pass

/office-review-pass — Word 成果物を壊さずにレビューして修正する

ひとつの作業です。.docx をレビューサイクルに通し、Ane の書式を保ったまま、すべての変更を書き出されたファイルで検証できる状態にします。

Office の編集はすべて ane_package.officeops にあります。このスキルが担うのは判断であり、仕組みではありません。モードに officeops が備えていない機能が必要なら、officeops に追加して、そこでテストしてください。これにより、このスキルを薄く保てます。また、それがモジュールを最初に切り出した理由です。コードを書く前に、正確な呼び出しシグネチャが記載された references/officeops-api.md を読んでください。

モードの選択

• read — 文書にコメントが含まれている、または専門家による読み込みが必要な場合に使います。読み取り専用です。
• annotate — 指摘事項を文書内に、Ane 名義の欄外コメントとして記載する場合に使います。作業用コピーに書き込み、バックアップを残します。
• track — ほかの人が編集内容を確認し、元に戻せるようにする必要がある場合に使います。変更履歴付きのコピーを作成します。
• revise — Ane が修正に同意し、文書に直接反映する場合に使います。ファイルを編集します。
• annex — 文書に用語集と出典付録を追加する必要がある場合に使います。

モードは連携して使えます。read で指摘事項をまとめ、annotate で欄外に記載し、track または revise で編集を適用します。モードが曖昧な場合は、作業を始める前に一行で質問してください。track と revise を分ける判断基準は、誰が決定するかです。相手方が編集を拒否できる必要がある場合は track、Ane がすでに決定している場合は revise です。annotate と track を分ける判断基準は、コメントか変更かです。コメントは問題点を示し、変更履歴付きの編集は修正後の内容を示します。

共通ルール — すべてのモードに適用

• Ane のファイルを基準にします。 対象ファイルが存在する場合は、mel_wiki/wiki/concepts/edit-preservation-protocol.md を適用してください。ディスク上の内容を読み、依頼された箇所だけを変更し、それ以外はすべてバイト単位で一致させます。文書を再生成してはいけません。また、チャットの内容をもとに文書を作り直してはいけません。チャットに表示されるのはシステムが生成した内容であり、ディスクにあるのはその後 Ane が変更した内容です。
• 呼び出しが戻ったかどうかではなく、書き出されたファイルを検証してください。 保存した .docx を再度開き、officeops.verify で検証します。save() が戻ったことは何の証明にもなりません。ロゴがなく配色だけが適用された ToR のバージョンが6つ納品され、その実行はいずれも正常終了しました。
• 事実を捏造してはいけません。 名前、日付、数値、条項番号、URL、MA 名は、文書または読み込んだコンテキストにない場合、質問してください。この原則が最も重要なのは annex モードです。もっともらしい URL も、誰かがクリックするまでは実在する URL と見分けがつかないためです。
• EDIT-PRESERVATION DELIVERY 形式で報告してください：変更した内容、変更せずに残した内容、範囲外の所見を列挙し、対応は行いません。

読み取りモード

目的は、文書を要約することではありません。Aneがすでに気づいた点を実際に踏まえたうえで、専門家としてのセカンドオピニオンを提供することです。

1. コメントを本文中の該当箇所に配置した状態で文書を表示します。 python scripts/review_pass.py read <path> --out review.md これは officeops.comments.render_review を呼び出します。この関数は文書本文を順にたどり、コメントの範囲が始まる位置に、対象となるアンカー語句、作成者、解決済みかどうか、およびその下にネストされた返信を添えて各コメントを表示します。生の .docx ではなく、そのファイルを読んでください。
2. まず文書全体を読み、その後でコメントを読みます。 彼女のコメントを十分に把握する前に自分の見解をまとめることが、相互レビューを有意義にします。彼女のコメントを先に読むモデルは、すべてに同意する傾向があります。
3. すべてのコメントを相互レビューし、それぞれを次の3つの分類のいずれかに分け、その分類を明示します。
   • 同意 — さらに、彼女が指摘していない点を加えます。つまり、影響、修正方法、または抵触する条項です。
   • 異議を唱える — その理由を示します。彼女のコメントは検討すべき同僚レビュアーの意見であり、実行すべき指示ではありません。すべてに同意するレビューでは、彼女が知らなかったことは何も伝わりません。これは、このモードが避けようとしている失敗パターンです。
   • 捉え直す — 実際の問題を指摘していますが、原因を浅く、または深く診断しすぎています。
4. 彼女が見落とした指摘を追加し、それぞれに該当箇所へ直接移動できるよう、レンダリング結果のブロック番号を付けます。
5. 結論を最初に示します。 まず文書に対する評価を一文で述べ、次にその根拠となる重要な理由、続いてコメントごとの相互レビュー、最後に独自の指摘を示します。文書の読者層に別途指定がない限り、Tier 1 の作業用ブリーフとします。
6. 文書の所有者に送る送付メールを提案します。ただし、求められるまでは作成しません。 Aneが希望した場合は、重要な点を2つか3つ挙げた短いメールにし、内容を繰り返すのではなく、文書を添付します。

変更履歴もレビューの対象です。render_review は挿入を承認済みとして表示し、削除を表示せず、該当するブロックに +ins / -del のマークを付けます。個々の変更について、作成者や日付を含めて検討する必要がある場合は、officeops.tracked.read_revisions(path) で確認できます。

文体について。 レビュー対象の文書には通常、Ane以外の作成者がいます。指摘の対象は文書の記述であり、人物ではありません。協働的な表現を維持します。「作成者が記載しなかった」ではなく、「承認基準が明記されていません」とします。

注釈モード

読み取りモードでの指摘を書き込むための方法です。各指摘は、Aneの作業用コピーにマージンコメントとして追加されます。これは、彼女のフィードバック用コピー（fbANE ファイル）にコメントを残した状態で文書の所有者に返すという、繰り返し行われている作業パターンです。Aneが評価レビューのラウンドでコメントを一つずつ手作業で追加した事例をもとに一般化したものです。

1. 所見の一覧と作成者名を確認します。 デフォルトの作成者は、装飾なしの「Ane Gasser」です。これは、コメントに AI のラベルが付いていると、取引先に提出する文書では機械出力のように見えるという、以前のレビューラウンドでの本人の明示的な指示によるものです。帰属の判断は本人に委ねられています。書き込む前に確認し、以下のスコープ境界に従って、IPPF の外に出る文書は AI 支援による出版物として扱います。
2. 各アンカーは、連続する5語以上で、該当する段落がちょうど1つでなければなりません。 コメントを JSON ファイルに書き込み、次を実行します。 python scripts/review_pass.py annotate <path> --comments comments.json --author "Ane Gasser" ファイルの形式は [{"match": "...", "text": "..."}] または {"anchor words": "comment text"} です。項目ごとの author と initials はデフォルト設定を上書きします。アンカーは書き込み前に本文と表の段落全体で事前チェックされます。ヒット数が0件または複数件の場合は、不正なアンカーをすべて示して処理全体が失敗します。また、ドライバーは5語未満のアンカーを無条件で拒否します。失敗したアンカーは選び直し、条件を緩めてはいけません。
3. コメント付きコピーの検証が完了した後にのみ、元のファイルを置き換えます。 officeops.add_comments_in_place は元のファイルと同じ場所にコピーを書き出して検証します。すべての新しいコメントが存在すること、既存のコメントがそれぞれの ID を維持していること、本文の語数が変わっていないことを確認してから、ソースと同じ場所にタイムスタンプ付きの _BACKUP_ ファイルを書き出し、置き換えます。処理に失敗した場合、作業用コピーはバイト単位で元のままです。本人のファイルが破損した状態になる時間はありません。
4. 依頼リストではなく、書き込み済みファイルの件数を報告します：コメント総数、保持された既存コメント数、新規追加数、語数に変更がないこと、バックアップファイル名。ドライバーはこれらを正確に表示するので、提出レポートにも同じ内容を記載します。
5. 後続のレビューラウンドで確認された落とし穴。 (a) ドライバーには Windows 形式のパス（C:/Users/...）を渡します。Git Bash 形式のパス（/c/Users/...）を渡すと、zipfile 内で FileNotFoundError が発生します。(b) read_comments はコメント内の段落を区切り文字なしで連結するため、 を含むコメントは読み戻し時に連結された状態になります。空白を除去して比較してください。そうしないと、正しく書き込まれたコメントも不一致と報告されます。(c) ドライバーでできるのはコメントの追加だけです。Ane の既存コメント文を書き換える機能はまだサポートされていません（バックログ：ENHANCE office-review-pass）。対応されるまでは、各コメントの最後の w:p を残してください。commentsExtended.xml と commentsIds.xml はその段落の w14:paraId をキーにしているためです。そのうえで、周囲のテキストを再構築します。comments.xml と people.xml の両方で w:author を変更し、作業用コピーで ID、作成者、日付、アンカー、本文の語数を検証してから、バックアップを作成して置き換えます。参考スクリプト：作業フォルダー内の agent-improvements/handoffs/hera-hub-round2-scripts/hera_apply_aar.py。(d) 2026-09-25 追加（Member Association のケーススタディ）： アンカーは文字単位で一致します。Word のテキストでは、曲線形のアポストロフィや引用符（’、“）が使われることがよくあります。照合文字列に直線形の ' を入力すると、何も見つかりません。アポストロフィや引用符を含まない5語の範囲を選ぶか、抽出したテキストから範囲をコピーし、打ち直さないようにします。ドライバーの事前チェックでは失敗したアンカーが示されますが、最初から問題のない範囲を選んでおけば再実行を避けられます。(d) 文言を変更する場合は、段落を再構築せず、既存の w:t ランの中で編集します：古い文字列がちょうど1回だけ含まれる w:t を見つけ、その中で置換します。ヒット数が0件または複数件なら、処理を中止します。これにより段落数、paraIds、ランの書式が維持され、変更していないコメントが comments.xml 内でバイト単位で同一であることも検証できます。参考：hera-hub-round2-scripts/hera_apply_align.py（2026-09-24、2回実行）。(e) Word で再保存すると、文字が1つも変わらなくても、コメントのテキストが複数のランに分割されることがあります：レビュー済みレポートを Ane が再保存した後、ある文が Table| 4) の位置で分割され、単一ランを対象とする一致検索では見つかりませんでした。処理を中止し、ランの構造を出力して、そのテキストを含むランを対象に編集し直します。照合条件を緩めたり、ランを結合したりしてはいけません。(f) 2026-10-14 追加（RBM ES レビュー、コメント書式の処理）： 落とし穴 (c) の制約が該当すると決めつける前に、パーツ一覧を確認してください。 ローカライズ用コメントドライバーでコメントを書き込んだパッケージには commentsExtended.xml、commentsIds.xml、people.xml がないため、w14:paraId をキーとするものがありません。既存のコメント文は自由に再構築できます。w:comment の子要素を書き換え、ID、作成者、日付を維持し、該当する1つのパーツだけを置き換えて、他のすべてのパーツがバイト単位で同一であることを検証します。最後の w:p を残す編集が必要なのは、Word で再保存されたパッケージだけです。また、メインのドキュメントパーツは常に word/document.xml とは限りません。_rels/.rels が指定するパーツを使ってください。Storyline／ベンダーのエクスポートでは word/document2.xml が使われており、名前をハードコードすると、破損を示しているかのような KeyError が発生します。参考スクリプト（スライド対応のコメント再構築、処理中止により安全を確保、パッケージをバイト単位で同一のまま置き換え）：1. Ane's PROJECTS/RBM II/RBM - transaltions SP/review-working/transform_comments_v2_20261014.py。 コメントの文面は読み取りモードの方針に従います。人ではなく文章について述べ、異議を唱えるだけでなく、それぞれのコメントに影響や修正案を添えます。「不明瞭です」とだけ書かれた欄外コメントでは、著者が推測するしかありません。

track モード

業務委託先の提案書、パートナー向け文書、翻訳レビューの場合、相手は Word でファイルを開き、各変更の作成者を確認して、一つずつ承認または却下できます。

1. 編集内容の一覧と、変更に表示する作成者名を確認します。変更の作成者を示すことがこのモードの要点です。作成者が示されていない変更履歴は、システムによる変更のように見えます。
2. 編集内容を JSON ファイルに書き込み、次のコマンドを実行します。 python scripts/review_pass.py track <path> --edits edits.json --author "Ane Gasser" --out marked-up.docx または、編集内容にロジックが必要な場合は officeops.tracked.TrackedEditor を直接操作します。いずれの場合も、コピーが作成され、元のファイルは変更されません。
3. 各編集の戻り値の件数を確認します。 .replace() は置換した件数を返します。0 は検索文字列が間違っていたことを意味し、文書がすでに正しかったという意味ではありません。成功メッセージではこの2つは見分けがつかず、正しいのはどちらか一方だけです。
4. 書き込み後のファイルは、必ず read_revisions で検証し、paragraph.text は使わないでください。 python-docx は w:ins 内のテキストを読み取らないため、変更履歴を記録した挿入の後でも、段落には新しい語句がないように表示されます。paragraph.text に対してアサーションを行うと、成功している編集が失敗したと判定されます。python scripts/review_pass.py revisions marked-up.docx を実行すると、実際に反映された内容が表示されます。
5. 各編集の件数を報告し、変更履歴付きファイルのパスと、受信者に表示される内容を一行で説明したメモを渡します。

コメントと変更履歴は併用できます。officeops.comments.add_comments はコピーに欄外コメントを追加するため、変更履歴付き文書に変更内容とその理由の両方を含められます。照合文字列は5語以上連続しており、段落がちょうど1つだけ一致する必要があります。一致が0件または複数件の場合、推測せずにエラーが発生します。間違った段落にコメントが付くと、ツールのエラーではなくレビューの誤りに見えてしまうためです。そのエラーを捕捉して文字列を選び直し、照合条件を緩めないでください。

revise mode

Ane がドキュメントを手作業で編集しています。書式は Ane が設定したものであり、python-docx で run を編集すると書式が崩れます。3 つの run に分かれたフレーズが、最初の run の書式を引き継いだ 1 つの run として戻ってきてしまい、気付かないまま書式が変わります。

1. 範囲を確認します。 合意したリストにある項目だけを対象にし、それ以外は変更しません。気付いたほかの点は、適用せずにレポートに記載します。
2. ファイルを Word で閉じておく必要があります。 COM は実行中の Word インスタンスを操作します。ファイルが開かれていると PackageNotFoundError が発生しますが、これは破損を意味するものではありません。
3. officeops.wordcom.find_replace をラップする python scripts/review_pass.py revise <path> --edits edits.json を実行します。COM はその場で編集し、取り消し機能もないため、最初の編集前にタイムスタンプ付きのバックアップが自動で作成されます。
4. 返された件数を読み、報告します。 関数は件数を推測せず、Word から読み取ります。0 を返すペアがあれば、検索文字列が間違っているため、黙って除外せず Ane に伝える必要があります。ヘッダーまたはフッターにも同じテキストがある場合は --headers を渡します。連絡先ブロックやドキュメントのタイトルは、そこに隠れていることがあります。2 回出現すると分かっている文字列の件数が 1 なら、丸め誤差ではなく、実際に見落としがあります。 あるレビューでは、ヘッダーが 2 つの表で繰り返されていたにもかかわらず、最初の表だけが変更されました。ファイルを再レンダリングすると、2 つ目は変更されていないことが分かり、2 回目の実行で修正できました。編集前のレンダリングと比較して、必ず再レンダリングして差分を確認します。件数だけを信用してはいけません。同じセルテキストが繰り返され、行ごとに異なる内容へ変更する必要がある場合（Yes → Yes (Table 1, EQ3)）、検索と置換では位置を指定できません。その場合は python-docx で表、行、列を指定してセルを編集し、保存方法については次の段落を参照してください。
5. 保存したファイルを検証します。 python scripts/review_pass.py verify <path> を実行すると、ブランディング、ヘッダー／フッター、孤立したハイパーリンク、単語数の各チェックが実行されます。孤立したハイパーリンクは、テキスト置換によって生じる特有の破損です。文字列は消えても関連付けは残り、リンク先のないリンクが付いたドキュメントが納品されます。

python-docx での編集を Ane のファイルに保存する方法。 Document.save() はヘッダー、フッター、スタイル、設定、core.xml を含むすべてのパーツを再シリアライズします。本文だけを編集した場合でも、元のファイルとのバイト単位の比較ではすべてのパーツが異なります。いったん一時ファイルに保存し、その word/document.xml だけを取り出して、ほかのすべてのパーツが元のファイルとバイト単位で同一のコピーに書き込みます。次に、word/document.xml 以外に差分がないことを確認してからバックアップを作成し、ファイルを差し替えます。参考：hera-hub-round2-scripts/hera_annex_final_ir.py。

PDF。 officeops.wordcom.export_pdf は既定で実行を拒否しますが、それが正しい動作です。Wine & Slate のキットドキュメントでは ExportAsFixedFormat が無期限にハングします。ページ数は返されますが、エクスポートは完了せず、Word プロセスがファイルを開いたまま終了しません。そのため、このモードでは PDF を作成しません。最後に、Word で「ファイル」→「名前を付けて保存」→「PDF」の順に操作して手動でエクスポートするよう、Ane に一行で伝えます。Ane がこの特定のドキュメントでは問題が起きないと確認した場合に限り allow_known_hang=True を渡し、その判断はあなたではなく Ane に委ねます。タイムアウトを延ばしてハングをごまかしても、時間を無駄にしたうえで失敗します。

付属資料モード

文書の起草チーム以外の読者が、誰にも尋ねずに文書を理解できるようにするための付属セクションが2つあります。

1. 用語集 — 文書で使われているすべての略語と専門用語を展開し、展開形だけでは意味が伝わらない場合は、6語程度の平易な説明を添えます。これを作るには文書を読みます。標準的な用語リストを使わないでください。標準的なリストには、この文書では使っていない用語が含まれ、文書内で作られた用語が抜けてしまうためです。
2. 出典付属資料 — 参照されているすべての文書、法律、規格、フレームワークを、クリックできるハイパーリンク付きで記載します。
   • 検証には、このセッションでの WebSearch または WebFetch が必要です。 トレーニングデータから思い出した URL は、リンクを装った推測にすぎず、このモードで出力されるものの中で最も大きな損害をもたらします。
   • まず正式な発行元を優先し、次にそのドメイン上の直接 PDF、続いて機関リポジトリまたは DOI を優先します。アグリゲーターは正式なリンクに加えてのみ使用します。
   • 検証できないものには ⚠️ URL unverified — confirm before publication と明記し、リンクを付けません。もっともらしい URL を推測してはいけません。
3. 新しい見出しスタイルを導入せず、文書の既存の見出しスタイルに合わせ、IPPF Visual Identity 2025 テンプレートを維持します。
4. 検証：verify.hyperlink_targets で各リンクが意図したアドレスに解決されることを確認し、verify.stranded_hyperlinks で孤立したリンクがないことを確認します。用語数、出典数、検証できなかった項目をすべて明示して報告します。

検証計画

各モードは作業前に確認内容を示し、書き込んだファイルを再度開いて確認します。

モード	検証する内容
read	読み取り専用 — 書き込みは行いません。レンダリング結果からブロック数とコメント数を報告します。
annotate	書き込んだファイルに対して read_comments を実行：既存コメントと新規コメントの合計数、既存 ID の維持、語数の不変、ソースと同じ場所にバックアップがあること。
track	書き込んだコピーに対して read_revisions を実行：置換ごとに挿入と削除が1件ずつあり、作成者と日付が設定されていること。
revise	Word から置換数を読み戻した後、verify を実行 — ブランディング、ヘッダー／フッター、孤立したハイパーリンクがないこと、語数。
annex	hyperlink_targets と stranded_hyperlinks を実行し、検証に失敗した出典の数を確認します。

python scripts/test_review_pass.py はドライバー自体をチェックします — 2種類の編集ファイル形式を読み込めること、マークアップされたコピーがソースを上書きしないこと、検索文字列に一致がない場合にゼロ以外で終了することを確認します。ドライバーを毎回手書きのスニペットではなく使う理由は、最後のチェックにあります。編集がひとつも適用されなかったレビューラウンドで作られたファイルは、すべて適用されたファイルとまったく同じように見えてしまうからです。Office の動作自体は、作業フォルダー内の tests/test_officeops.py で確認します。

対象範囲の境界

• ファイルを直接編集せず、英語の文章表現だけを扱う場合は ane-voice です。完成したブリーフの読み取り専用 QA 判定は check-deliverable です。対象言語への作業は localise です。ジェネレーターから ToR を作成する場合は tor-procurement です。コメント付き文書から決定事項を抽出して議事録にする場合は、meeting-notes の周辺情報モードを使います — コメントを読み取りますが、書き込みは行いません。コメントを書き込むのは、このスキルの annotate モードです。
• Excel の修復と古くなったジェネレーターの正規化は office-repair（Wave 3）の対象であり、このスキルの対象ではありません。
• COM モードには Windows と Word が必要で、ファイルを閉じておく必要があります。Web コンテナーでは、read と track の処理は引き続き動作します — 純粋な python-docx と lxml で実装されています — ただし revise は動作しません。
• AI の支援を受けた処理の後に IPPF の外部へ出る文書は、AI 支援出版物です。mel_wiki/wiki/concepts/ai-use-in-publications.md に従って奥付の掲載を提案してください。通常の文法のみの編集は対象外です。