同期が「更新しました」と嘘をつく — 配布が届かない2つの欠陥を潰す

1. この指示書が解決する問題

同期を動かすと「更新しました」と表示される。それでも配布先のルールやツールが古い。この指示書は、その症状を持つ配布処理を調査し、修正と到達確認まで行うためのものです。 対象読者は、複数端末へ設定・ルール・実行スクリプトを配る仕組みを自作している開発者です。AIに作業を任せる場合も、以下の証拠と完了条件を渡してください。

題材は orgiast-claude-rules という、AI向けルールと運用ツールを配布するリポジトリです。 tools/onboarding-sync.mjs は、そのリポジトリ更新とルール同期などを担うNode.jsスクリプトです。 updateRepositoryFiles は、Git更新を試し、必要なら配布アーカイブを展開する関数です。 origin/main は、この処理が配布正本として扱うリモート追跡ブランチです。 tools/ は実行ツール、rules-extracted/ は分割ルール、skills/ は作業手順の配布ディレクトリです。

扱う欠陥は次の2件に限定します。

欠陥	成功と誤認したもの	実際に届かない理由
①	現在ブランチへのpull成功	正本mainの変更を取り込んだか調べず終了する
②	保護対象を除いたzip展開の完了	過去の配布物を人の編集と誤認し、上書きしない

一次資料は、修正コミット d914321（PR #166）と 6262cb2（PR #168）です。 どちらも2026年8月30日の修正で、親コミットのコード、修正差分、追加テストを照合しました。 以下の引用行番号は指定コミット時点のものです。作業中ファイルの行番号ではありません。 当時の端末での件数はコミット本文の記録として紹介し、今回再計測した数値とは区別します。 今回の調査基準HEADは 4cf951d。関係する現行回帰テスト13件の成功も確認しました。 実端末全台への配布や、スケジュールからの起動成功まで確認したという意味ではありません。

調査の成果物には「実行入口、正本の版、書込先、未更新一覧、読み戻し結果」を残してください。 成功ログだけで完了にせず、配布先に期待する内容が存在することを完了条件にします。

2. 欠陥①：別ブランチへのpull成功を、正本の配布成功と取り違える

症状。 何度同期しても新しいツールが届かず、毎回成功メッセージだけが出ます。 d914321 の本文には、ある端末でmainより78コミット遅れ、39ファイルのドリフトがあったと記録されています。 ドリフトとは、配布正本と端末上のファイルが期待どおりに一致していない状態です。

再現条件。 共有作業ツリーをmain以外の作業ブランチに置きます。 そのブランチにはpull可能な上流を設定し、main側にだけ新しい配布変更を作ります。 作業ブランチの上流が最新なら、pullは正常に終わってもmainの変更は入りません。

修正前の実物：tools/onboarding-sync.mjs、d914321^、180–182行。^ は修正コミットの親を表します。

git(['-C', targetRepo, 'pull', '--ff-only'], { stdio: 'pipe', timeout: 60000 });
emit('[onboarding-sync] tools を更新しました (git pull)');
return { ok: true, method: 'pull', excluded: [] };

原因。 git pull --ff-only は引数で配布元を指定しておらず、現在ブランチの上流を扱います。 そのコマンドの正常終了だけでreturnするため、mainのzipを取る代替経路へ進めません。 --ff-only が制約するのは更新方法であり、「配布正本まで届いた」という業務上の条件ではありません。

直し方。 pull後に正本をfetchし、HEADに未収録のmainコミット数を調べます。 0以外、または確認不能なら成功扱いで終了せず、zipの代替経路へ進めます。 修正後の実物：tools/onboarding-sync.mjs、d914321、184–193行。

git(['-C', targetRepo, 'fetch', 'origin', 'main'], { stdio: 'pipe', timeout: 60000 });
const count = git(['-C', targetRepo, 'rev-list', '--count', 'HEAD..origin/main'], { encoding: 'utf8', timeout: 60000 });
behind = Number.parseInt(String(count).trim(), 10);
if (!Number.isFinite(behind)) throw new Error(`behind 件数が不正です: ${String(count).trim()}`);
if (behind === 0) {
  emit('[onboarding-sync] tools を更新しました (git pull / main 到達確認済み)');
  return { ok: true, method: 'pull', behind, excluded: [] };
}
pullReason = `git pull は通ったが main へ未到達(${behind}コミット遅れ)`;
emit(`[onboarding-sync] ${pullReason}。zip で更新します`);

同コミット194–196行には、確認に失敗した場合も理由を表示してzipへ進む処理があります。 fetch失敗時にzipを試すことは、オフラインでも必ず更新できるという保証ではありません。 zip取得も失敗すれば、配布できなかったことを結果に残す必要があります。

修正コミット本文では、同じ端末のドリフトが39件から2件へ減ったと報告されています。 残り2件は編集中として保護され、未更新であることがログに出たという記録です。 これを「修正すれば必ず全ファイルが一致する」という保証に読み替えないでください。

適用時の限界。 HEAD..origin/main が0でも、HEADとorigin/mainが同一とは限りません。 HEADがmainを含んで先行している場合や、作業ツリーに編集がある場合もあります。 この修正は正本への未到達を検知しますが、配布内容の完全一致は第6章の読み戻しで確かめます。 利用中のブランチを強制的に切り替える修正は避け、配布専用checkoutの分離も検討してください。

3. 欠陥②：自分が配った旧版を、人の編集として保護し続ける

症状。 zip更新へ進んでも、一部ファイルだけ古いまま残り続けます。 6262cb2 の本文には、保護86件について古いmainのコピーを人の作業と誤認した記録があります。 その結果、重複出品を防ぐガードが届かず、同じ題材が審査待ちに8件並んだと記載されています。 マキモノはAI指示書を出品するマーケットで、このガードは重複登録を防ぐ配布ツールです。

再現条件。 main以外のHEADを持つ作業ツリーへ、以前のmainのファイルをzipで配ります。 そのファイルはHEADと異なるため、git status では変更ありになります。 さらに、前回配布のハッシュ台帳に該当ファイルの一致記録がない状態を用意します。 台帳が有効なら自己出力として更新できる経路は、修正前から存在していました。

修正前の実物：tools/onboarding-sync.mjs、d914321、211–215行。ここで previous.files は、前回zip配布時に保存したファイルハッシュの台帳です。

for (const rel of changed) {
  const current = path.join(targetRepo, ...rel.split('/'));
  if (previous?.files?.[rel] && fs.existsSync(current) && sha256File(current) === previous.files[rel]) selfOutput.add(rel);
  else excluded.add(rel);
}

原因。 HEADとの差分は、変更の有無を示しても、誰が書いたかまでは示しません。 台帳で自己出力と証明できないファイルを一律除外すると、過去の配布物まで保護対象になります。 除外される限り内容は変わらず、次回も同じ理由で除外されるため、再実行では直りません。

直し方。 台帳との一致判定を残し、追跡済みファイルをmainの過去版とも照合します。 Git blobはファイル内容を表すオブジェクトで、そのハッシュを比較すれば内容の一致を判定できます。 履歴列挙と改行差の扱いの実物：tools/onboarding-sync.mjs、6262cb2、228–234行。

const commits = String(git(
  ['-C', targetRepo, 'rev-list', '-n', '50', 'origin/main', '--', rel],
  { encoding: 'utf8', timeout: 60000 },
)).trim().split(/\s+/).filter(Boolean);
const content = fs.readFileSync(current);
const localShas = new Set([gitBlobSha(content)]);
if (!content.includes(0)) localShas.add(gitBlobSha(Buffer.from(content.toString('binary').replaceAll('\r\n', '\n'), 'binary')));

続く235–243行では、各コミットの commit:path を rev-parse でblobハッシュに変換します。 ローカルの候補ハッシュと一致すれば matchesHistory をtrueにします。 分類の実物：同ファイル、同コミット、245–246行。

if (matchesHistory) oldDistribution.add(rel);
else excluded.add(rel);

一致したファイルを除外集合へ入れないことで、zip内の新版へ更新できるようになります。履歴に一致しない編集や、照合に失敗したファイルは保護を継続します。 未追跡ファイルは履歴照合しません。ただし前回配布台帳と一致する自己出力判定が先にあります。 従って、実装を「未追跡は例外なく全部保護」と説明すると不正確です。

適用時の限界。 探索は対象パスの変更履歴を最大50コミットに限っています。 古すぎる版、浅い履歴、Git失敗では一致を証明できず、保護が残る場合があります。 また、履歴との一致は内容の証拠であり、書き手が機械だったことの厳密な証明ではありません。 人が意図的に過去版へ戻す運用では、配布専用領域や明示的な所有権の管理を併用してください。

コミット本文の修正後記録は「保護86件から11件」「旧配布版24件を更新」です。 差の75件をすべて更新したと換算してはいけません。未追跡を表示件数から外す変更も含まれます。 実際の戻り値 excluded には全除外名が残ります（同ファイル276行）。 件数の見た目より、必要なファイルが除外に残っていないことを調べてください。

4. なぜ成功報告が出てしまうのか

2件とも、途中の操作が成功したことを、配布の目的を達成したことに読み替えています。 欠陥①ではpullの正常終了、欠陥②では除外付きコピーの完了が成功表示の条件でした。 どちらも、利用側が読むファイルの期待内容を条件にしていませんでした。

zip経路の戻り値の実物：tools/onboarding-sync.mjs、6262cb2、276行。

return { ok: true, method: 'zip', reason, behind, excluded: [...excluded].sort(), changed };

この ok: true は、excluded が空であることも、changed がtrueであることも要求しません。 必要なファイルが保護されていても、関数としては正常に処理を終えられます。 一方、もともと正本と一致しているno-opは正常です。「書いた件数0」だけでも失敗とは判定できません。

プロセスのexit code、関数の ok、配布物の一致は、それぞれ別の結果として扱います。 このスクリプトはhookを壊さないため失敗を握る設計も持っています。hookとは、AIセッションの開始などに連動して自動実行される処理です。 根拠は 6262cb2:tools/onboarding-sync.mjs の冒頭コメントと、末尾のmainのcatchです。 セッションを続行できたというexit 0を、配布完了の証拠にしないでください。

他環境へ適用する際は、次の結果区分を明示する設計を推奨します。既存実装の引用ではありません。

• updated：期待版と読み戻しが一致し、今回変更した。
• already-current：変更不要で、期待版との一致を確認した。
• partial：保護対象などが残り、必要な配布物の一部が未到達。
• failed／unverified：取得・書込に失敗した、または到達確認ができない。

書込後のハッシュ保存だけでも不足します。間違った内容を正しく記録することがあるためです。 修正版のコピー処理は宛先ハッシュを保存しますが、それは主に次回の自己出力判定用です。 根拠：6262cb2:tools/onboarding-sync.mjs、127–130行。 独立して決めた期待版との比較まで行って、初めて到達確認になります。

5. テストで固定すべきこと

まず既存テスト tools/onboarding-sync.test.mjs を読んでください。 修正①の追加テストは d914321 の118–139行、修正②の主要テストは 6262cb2 の185–228行です。 Git応答を差し替え、一時ディレクトリへ配布する構成なので、実端末を更新せず条件を作れます。 成功メッセージへのassertだけでなく、配布後にファイルを読み戻すassertを残してください。

入力・障害条件	固定する期待結果
pull成功、mainとの差0	pull経路で終了し、zip取得は0回
pull成功、mainに78コミット未到達	zip経路へ進み、理由を出す
pull成功、main確認のfetch失敗	確認済みとせずzipを試す
pull失敗、zip取得成功	古いファイルが新版になり、新規ファイルも届く
変更あり、内容がmainの過去版と一致	除外せず新版で更新する
変更あり、内容が履歴と不一致	人の編集を保護し、未更新名を出す
台帳にない未追跡ファイル	履歴照合せず保護する
履歴の取得失敗	推測で上書きせず保護する
テキストの差がCRLFとLFだけ	履歴一致と判定して更新する
status自体を取得できない	zip取得・書込をせず失敗を返す
自己出力をもう一度更新	保護で凍結せず、さらに新しい版が届く
自己出力に人が追記してから同期	追記した内容を保護する

読み戻しを含む既存テストの実物：tools/onboarding-sync.test.mjs、6262cb2、185–191行。

test('modified file matching a main history version is updated', async () => {
  const f = repositoryFixture();
  const result = await updateRepositoryFiles(f.repo, fallbackOptions(f, historyGit(' M tools/changed.mjs\0', { 'tools/changed.mjs': 'old' })));
  assert.deepEqual(result.excluded, []);
  assert.equal(fs.readFileSync(path.join(f.repo, 'tools', 'changed.mjs'), 'utf8'), 'new');
  assert.match(f.output.join('\n'), /旧配布版と一致したため更新 1件/);
});

今回の原稿作成時には、上記に対応する現行テスト13件を次の選択実行で確認しました。 コマンドはリポジトリのルートで実行します。テスト全体や全PCを検証したという意味ではありません。

node --test --test-name-pattern='successful pull|fetch failure after successful pull|failed pull falls|zip fallback preserves|modified file|untracked file skips|rev-list failure|CRLF-only|status failure writes|two fallback runs|human edit after fallback' tools/onboarding-sync.test.mjs

加えて、自分の環境では実Gitの一時bareリポジトリと作業cloneを使う統合テストを用意してください。 mainだけを進め、別ブランチのpull成功からzip配布へ進むことを、実コマンドでも確認します。 「mainを含むが配布ファイルを独自変更したHEAD」も、読み戻しで不一致になるべき追加ケースです。 これらの統合テストは本稿の追加提案であり、今回実行済みとはしていません。

6. 検証手順：直した後に、本当に届いたかを確かめる

手順1：本当に動く入口と宛先を確定する。 スケジューラの実行ファイル、引数、実行アカウント、HOME、作業ディレクトリを記録します。 .ps1 と .mjs が並ぶ環境では、実際に登録された方から呼出経路を追います。 今回の関数は targetRepo に書きますが、CLI側はHOMEからリポジトリを組み立てます。 調査HEADの tools/onboarding-sync.mjs、22・30行が根拠です。実行時のcwdと同じとは限りません。

手順2：配布正本を固定する。 管理側で配布予定コミットSHAを確定し、対象ファイル一覧を作ります。 検証中に動くmainの先端を期待値にすると、別の配布時点との比較になってしまいます。 下記のSHAには、配布処理が実際に取得した版を指定してください。 可変URLのzipで版が記録できない場合は、その不足を未検証理由として残します。

手順3：修正版を、既存端末と同じ入口で実行する。 まず隔離した検証用プロファイルで、2件の再現条件と人の編集保護を確認します。 実端末では保護対象を退避・確認し、承認された更新経路を実行してログと戻り値を保存します。 --force が外すのは間引きであって、人の編集保護を解除する指定ではありません。 新規インストールで動くだけでは不十分です。既存端末への修正版の到達も確認します。

手順4：配布先ファイルを独立に読み戻す。 以下は本稿用の検証例です。リポジトリ実装からの引用ではありません。Python 3とGitが必要です。既知の正本checkout、配布先、確定SHA、対象相対パスを引数にします。 tools/対象.mjs などの例示値を置換し、対象が複数なら末尾へ列挙してください。 正本checkoutには確定SHAのオブジェクトを事前に取得しておきます。

python3 - /path/to/source /path/to/destination EXPECTED_COMMIT tools/対象.mjs <<'PYCODE'
import hashlib, pathlib, subprocess, sys
source, destination, ref, *files = sys.argv[1:]
if not files:
    raise SystemExit('対象ファイル未指定')
failed = False
for rel in files:
    expected = subprocess.check_output(['git', '-C', source, 'show', f'{ref}:{rel}'])
    target = pathlib.Path(destination) / rel
    actual = target.read_bytes() if target.is_file() else None
    equal = actual == expected
    failed |= not equal
    digest = lambda b: hashlib.sha256(b).hexdigest() if b is not None else 'MISSING'
    print('OK' if equal else 'MISMATCH', rel, digest(expected), digest(actual))
raise SystemExit(1 if failed else 0)
PYCODE

この例はバイト単位の一致を要求します。正当な改行変換も不一致として出ます。変換が仕様なら、その仕様どおりの期待内容を別途生成して比較してください。 不一致を隠すために、すべての空白や改行を無条件に削ることは避けます。

手順5：利用先と全対象へ確認を伸ばす。 リポジトリから別ディレクトリへ再コピーするなら、アプリが読む最終配置先でも同じ確認をします。 対象端末・アカウントごとに、期待SHA、実行入口、最終配置先、ハッシュ、除外名を記録します。 未応答や未登録の端末は未確認として残します。応答した端末だけの成功を全台成功と呼びません。 最後に同じ版を再配布し、内容が変わらず、保護対象も消えず、一致確認が再び通ることを確認します。

7. 再発防止チェックリスト

• 成功条件を「期待版が最終配置先に存在する」と定義した。
• pullの上流と配布正本を区別し、正本への未到達を検知する。
• コミット到達だけでなく、実ファイルの内容も比較する。
• 差分ありという理由だけで、人の編集と決めつけない。
• 自己出力台帳を使い、台帳なしの既存端末からも移行できる。
• 履歴照合の上限と失敗時の保護方針を明示した。
• 未追跡、人の編集、削除されたファイルを無断で上書きしない。
• 未更新の必要ファイルを名前付きで報告し、部分成功を区別する。
• 表示件数の対象と、全除外一覧の対象を混同しない。
• 正常なno-opと、未到達によるno-opを読み戻しで区別する。
• 初回、2回目、新版への更新、人の編集後の再実行をテストした。
• 新規インストール経路と既存端末の自動更新経路の両方を検証した。
• スケジューラに登録された実ファイル・アカウントで検証した。
• 無応答端末を成功扱いせず、登録有無と入口から調べる。
• 読み戻し結果には版と配置先を残し、秘密や個人情報を含めない。

調査担当AIへの完了指示：欠陥ごとに修正前の分岐、再現条件、修正差分、テスト結果を提出すること。 配布完了の報告には最終配置先の読み戻し結果を添え、未更新・未確認の対象を明示すること。 「更新しました」という文字列を確認しただけでは、この指示書の作業を完了としないこと。