/harness-sync — 公開 repo への一方向エクスポート

ローカルの生きた harness (~/.claude) と公開 artifact repo は目的の違う別 repo として保ち、 remote 直結ではなく filter 付き一方向コピーで同期する。公開境界は script の origin filter 1 箇所で宣言的に管理される。

なぜ remote 直結にしないか

• ~/.claude は実行時状態 (settings, metrics, session 情報) を含む生きたディレクトリで、 gitignore の永久警戒を前提にした公開はミス耐性がゼロ
• origin filter は出自の記録であって再配布権の整理ではない (外部 origin はライセンス 整備が別途必要)
• 目的の違う repo 間は丸コピが調整コスト最小 (duplicate over coordination)

Workflow

1. Dry-run で差分を確認

bash <公開repo>/scripts/sync-from-local.sh --dry-run

差分の要約 (新規 / 変更 / 削除されるコンポーネント) をユーザーに提示する。

2. 公開スコープ確認

task request / approved plan に列挙された repo と component は追加確認なしで進める。 列挙外の repo・新規公開 component が見つかった場合だけ scope change として停止する。

3. 適用

bash <公開repo>/scripts/sync-from-local.sh

script は staging 収集 → runtime artifact と保守用 file の除去 (results.json, pycache, MAINTENANCE.md 等) → frontmatter YAML 検証 (GitHub 等の厳密パーサ基準。invalid なら abort) → secret scan (検出時 abort) → skills/ agents/ rules/ docs/decision-history/ docs/plans/ rfcs/ hooks/ scripts/hooks/ tests/ subtree の置換、まで行う。origin filter が効くのは skills/ agents/ rules/ だけで、 残りは別の規則で決まる (いずれも集約 repo のみ):

• docs/decision-history/ — 判断の経緯はハーネス自身の記録で定義上すべて自作のため、origin filter を 掛けずディレクトリ丸ごとが対象。以後の記録は公開される前提で書く。
• rfcs/ — 台帳エントリも自作の判断記録なので ADR と同じく丸ごと (ADR-0049)。起票は公開可能な書き方が既定 — 機微はリンク先へ (task-stocktake の公開規約)。
• docs/plans/ — 承認して commit した plan。ADR / RFC から相対リンクされる原本 (ADR-0085)。集めるのは git が追跡している plan だけで、untracked・未 commit の変更があれば abort する。公開可能な書き方が既定で、$HOME の実値を含む行があると script の home-directory path scan が abort する — ~/ に書き直す。
• hooks/ scripts/hooks/ tests/ — script 内の HOOK_ALLOWLIST に列挙したファイルだけ。 公開は provenance でなく curation の判断 (ADR-0038)。公開対象の hook を追加・rename したら allowlist を更新する — source に無い entry があると sync は abort する。scripts/claims.py (台帳 CLI、rfcs/ の消費側) も allowlist 経由 — subtree 外に置かれるため削除は伝播しない (delist したら公開 repo 側で手動削除)。install 手順の正本は 公開 repo の docs/hooks.md で、これは subtree の外にある (中に置くと sync で消える)。 script は commit しない。LLM 側で diff と secret scan の結果を確認してから次へ進む。

4. ドキュメント整合 (LLM 側の責務)

構成が変わったら、公開 repo の以下を確認する:

• docs/components.md / docs/components.ja.md の skill/agent/rule テーブルは GENERATED マーカー間で apply 時に script 自動再生成される（README は表を持たず、このページを指すだけ。表が README の約 16k 字を 占め、LLM の取得が初回で切れたため — ADR-0091）（skills-table / agents-table / rules-table。 membership は origin filter が正、Purpose 列は既存キュレーションを保持し新規のみ seed）。 手で直すのは Purpose 文面と周辺 prose のみ。集約カウント（"N skills" 等）はどこにも 書かない（No-volatile-state。churning count は焼き込むと drift する）
• repo の About（description）も同様に volatile-free に保つ — 数字を入れず、 価値提案（何を pick できるか）で記述する。gh repo edit --description で編集
• docs/hooks.md — script 生成ではない手書き doc。hook の発火条件・bypass 変数・ settings.json 断片・bats 被覆を持つので、公開 hook を足す / 挙動を変えたら手で追随する
• llms.txt / llms-full.txt — 退役した component の行を消すのは機械検査で確認する （下の 4b）。文面の質は llms-txt-writer に defer
• 集約 repo の docs/components.md の「Upstream components」節も script 生成（marker 間を apply 時に 自動再生成、外部 origin の名前のみ・ECC トップリンクのみ）— 手で編集しない

4b. 公開前リンク検査（機械、blocking、全モード）

apply の後・commit の前に、対象の公開 repo ごとに走らせる。集約・skill repo・rule repo・ plugin variant のどのモードでも同じ。どれかが非 0 なら直すまで commit しない:

python3 ~/.claude/skills/context-sync/scripts/context_evidence.py --root <公開repo> --gate --gate-readme
python3 ~/.claude/skills/harness-sync/scripts/public_links.py --root <公開repo> --owner shimo4228 --clones ~/MyAI_Lab
[ -f <公開repo>/.claude-plugin/marketplace.json ] && claude plugin validate <公開repo>

exit 3 = 違反（2 = 実行不能）。出力行がどの検査かを名指しするので、そこを読む。

この検査が要る理由は削除と変更の非対称にある。 subtree の丸ごと置換は退役した skill を 公開側から消すが、README・llms.txt・CHANGELOG は root files として不可侵で、手で保守する 文書のまま残る。repo 間リンクは相手の repo の変更で切れる。どちらも sync 自身は気づかない。

agent を経由しない sync はこの検査を通らない。 sync 自身が作る壊れ方（root files が payload に無い skills/ パスを指す）は vendored の scripts/sync-from-local.sh が apply 前に abort する。repo 間リンクは相手側の変更でも切れるので、public_links.py を全公開 repo に ときどき走らせる（repo-asset-stocktake の棚卸しのついでなど）。凍結済みで sync が abort する repo はこの経路を通らないので、その棚卸しが唯一の検査になる。

5. コミット

commit の前に find <公開repo> -name MAINTENANCE.md が空であることを確かめる — skill の MAINTENANCE.md は 保守者向けで公開しない（script の除去が漏れたら commit せず script を直す）。

claude-harness では、適用の出力の # commit body: 行が commit 本文の下書き（.git/SYNC_COMMIT_BODY）を指す。 下書きは source commit の trailer の写しで、末尾の Source: 行が次の同期の起点になる（RFC-0029）。script の scan が 止めるのは secret と $HOME/ の実値だけなので、commit の前に下書きを意味の検査に通す:

bash ~/.claude/scripts/verify-public-detail.sh --root <公開repo> --base origin/main \
  --target .git/SYNC_COMMIT_BODY --no-terms --llm

exit 1 の HIT（非公開 repo の名前・~/ 形式の私的パスなど）は下書きを直接編集して伏せ、exit 0 になるまで回す。 exit 2 は未検査なので commit しない。下書きには subject が無いので、先頭に subject・空行・主な増減を書き足す。 Source: 行は残す。

git -C <公開repo> add -A
git -C <公開repo> commit -F <公開repo>/.git/SYNC_COMMIT_BODY   # claude-harness。下書きの無い repo は commit だけ

メッセージ例: subject は chore: sync from local harness (origin: shimo4228)、body は主な増減と下書き。 default branch へ直接 commit するのは意図的（sync = mirror 更新であり branch-first 規約の対象外）。 task request が push まで含む場合は追加確認せず push する。

削除の伝播

claude-harness の script は subtree を丸ごと置換するため、ローカルで退役した skill や origin が変わったファイルは公開側からも消える。退役理由は ~/.claude 側の ADR にあるので、 公開側 commit message から参照する。

skill repo の script は逆に削除を伝播しない: 対象 skill を repo 自身の skills/ 配下から導出するため、harness 側に skill が無い・origin が一致しない場合は skip ではなく abort する(公開済み skill が静かに消えるのを防ぐ)。skill を退役させる場合は repo 側で明示的に削除する。

Skill repo sync モード

単独 skill repo (1 repo = 1 skill) も同じ workflow (dry-run → scope 確認 → apply → docs 整合 → 4b → commit) で同期する。違いは script だけ:

• 対象 skill は repo 自身の skills/ 配下ディレクトリ名から導出(これにより script は 全 skill repo で byte-identical に vendor できる)
• script の正本は templates/skill-repo-sync-from-local.sh（この skill の中）。直すときはそこを直し、 全 skill repo の scripts/sync-from-local.sh へ copy する。正本は apply 前に、root files が payload に 無い skills/ パスを指していないかを検査して abort する（4b の「sync 自身が作る壊れ方」）
• 置換対象は skills/<name>/ のみ。agents/ rules/ は扱わない
• root files (README / llms.txt / CHANGELOG / LICENSE) 不可侵、commit しない、は共通

対象は harness が正本の skill のみ。CA 等 project 運用版から汎用化 fork した curated skill repo (code-and-llm-collaboration, llm-agent-security-principles) には script を置かない — 丸ごと置換が汎用化リライトを上書きしてしまうため、手動 curation で 更新する。

Rule repo variant

単独 rule repo (1 repo = 1 rule file) も同じ workflow だが script が違う: 対象は skills/<name>/ ではなく固定の単一ファイル rules/common/<name>.md を publish する (source = ~/.claude/rules/common/<name>.md)。origin marker は rule ファイルの HTML コメント (<!-- origin: shimo4228 -->) を head -15 | grep で検出する。secret scan・ root files 不可侵・commit しない、は共通。

Rule + plugin repo variant (akc-cycle)

akc-cycle は rule + Claude Code plugin repo。rule は sync 対象外: repo が自己完結版 (self-contained edition) を所有し、harness 側はポインター版 — 別内容が意図 (ADR-0018 / ADR-0035 「圧縮版を配布 repo へ同期しない」)。script は固定 allowlist 方式: 対象 skills の正本は script の SKILLS= 配列（AKC cycle phase binding の skill 群。payload は skills のみで agent を持たない）。allowlist に harness 側で退役した component が残っていると sync は abort する — その場合は repo 側で allowlist から外し、payload の 増減として plugin.json の version と CHANGELOG を更新する。 staging → prune → YAML frontmatter 検証 → secret scan → subtree 置換 (skills/)。 allowlist の component が harness に無い / origin marker が無いと abort (silently drop しない)。.claude-plugin/plugin.json / marketplace.json と rules/common/akc-cycle.md は repo 側 root 資産 (README / LICENSE と同格) — sync は触らない。version 更新は plugin.json を repo 側で手動 bump する。plugin は rules を運べない (Claude Code plugin 仕様) ため、rule file は plugin payload 外の copy-install 経路のまま。

harness-stocktake も同型の skills-only plugin variant: 固定 allowlist は harness-stocktake と source 7 本 （skill-stocktake, rules-stocktake, agent-stocktake, hook-stocktake, rules-distill, context-sync, repo-asset-stocktake）と、 skill-stocktake が URL と参照の検査に使う skill-health と、Apply が skill 項目に使う skill-writer。 staging の後に移植性ゲートを持つ: 写す Markdown に ADR / RFC 番号、Herdr、Slack、launchd、triage-tick、 ~/.claude/<rules・agents・skills 以外の下位 path> があれば abort する（直すのは正本の SKILL.md。経緯は各 skill の MAINTENANCE.md へ）。tests/ は配らない。root の README・examples/・bench/ と .claude-plugin/ は repo 側の資産。

herdr-toolkit は同型の skills-only plugin variant: 固定 allowlist は 2 skills (spawn-session, agent-send) で rule / agent 収集ブロックを持たない。spawn.sh は兄弟 skill の agent-send を呼ぶので、2 つは一緒に publish する。 外部 origin の herdr skill 本体は Herdr 自身の integration が配るため対象外 (ADR-0036)。

Skill repo packaging（命名と subagent 同梱）

skill repo を GitHub 公開する際の規約（正本）:

• subagent 同梱: skill が呼ぶ subagent は repo に同梱する。同梱しないと installer が agent を別途探す羽目になり、canonical rules を agent が SKILL.md から参照する orchestrator skill は両方入れるまで壊れる。
• 命名の非対称: skill（SKILL.md）はオープンな cross-tool 標準（Agent Skills / agentskills.io — Codex / Gemini CLI / Cursor 等でも動く）、subagent（agents/*.md）は Claude Code 固有。→ agent を同梱する repo は claude-skill- prefix を維持し compatibility frontmatter に Claude Code 向けと明記。pure-skill repo は prefix を 外す（<owner>/<skill-name>）。awesome-list 掲載は owner/skill-name で並び repo prefix を見ないので、命名は意味の正確さで決める。
• レイアウト: install.sh（skills/* → ~/.claude/skills/、agents/*.md → ~/.claude/agents/）+ skills/<name>/SKILL.md + agents/<agent>.md（top-level フラット。 nest しない）。pure-skill repo は install.sh 省略可（citation-sync 等の先例）。
• install.sh は冪等: 同一なら skip（.venv とキャッシュは比較しない）、異なれば ~/.claude/backups/install-<ts>/ に退避してから上書き（skills/ の中に残すと旧版が同名の 2 つ目の skill として読まれる） （--force / --dry-run）。全 repo で byte-identical に保つ。README install 節は Option A（./install.sh）/ Option B（手動 cp）/ SkillsMP の 3 つを書く。
• SkillsMP caveat: /skills add <owner/repo> は skills/ のみ install し agents/ は入れない。agent 同梱 repo の README に必ず注記する（cp agents/*.md ~/.claude/agents/ または install.sh を実行）。
• 自分のファイルは skill ディレクトリの変数で指す: ~/.claude/skills/<name> を SKILL.md に書かない （install 先が違うと壊れる）。変数名・兄弟と他 skill の書き方・その場で読み替えを書く 1 行は skill-writer の references/portability.md が正本（SKILL.md 本文に変数名を書くと読み込み時に置換されるので、ここには書かない）。 dangling 検査は skill-health の scan_refs.py が変数を展開して行う。
• 単独 skill repo は .claude-plugin/ を持たない: plugin の経路は plugin repo（akc-cycle など）に寄せる。 単独 repo にも置くと同じ skill を別の名前空間で二重に配り、version を保守するファイルも増える。 置くなら claude plugin validate が通ること（4b）
• 公開用 packaging metadata は local 正本に持たせる: compatibility: 等の公開向け frontmatter を repo 側で足すと、丸ごと置換のたびに消える（= 恒常的な偽 drift 源）。 local SKILL.md の frontmatter に持たせる — Claude Code は未知キーを無視するので無害。

Repo mapping (project-specific)

共通 env: origin filter shimo4228 (HARNESS_SYNC_ORIGIN)、source (HARNESS_SYNC_SOURCE)。source の既定は ~/.claude だが、正本を移設した 3 repo（citation-sync / paper-ecosystem / writing-ecosystem）だけは script 側の既定が移設先を指す（RFC-0019 手段 A）。既定以外を使うときは env で上書きする。

手動 diff 確認が残る対象（script が置換しないもの）

skill 本体の drift は script が拾う。手動 diff の対象は script が置換しない同梱物だけ:

• agents/*.md（claude-skill-paper-ecosystem / claude-skill-writing-ecosystem / readme-writer の 同梱 subagent。正本は writing 系が ~/MyAI_Lab/zenn-content/.claude/agents/、 paper 系が ~/MyAI_Lab/paper-lab/.claude/agents/、readme-writer が ~/.claude/agents/readme-judge.md）
• rules/writing-principles.md（claude-skill-writing-ecosystem の同梱 rule。writing-ecosystem の 背骨で、同梱しないと公開版 skill は原理を失う。正本 ~/MyAI_Lab/zenn-content/.claude/rules/writing-principles.md）
• hook script（例: skill-stocktake の hooks/log-skill-usage.sh。正本 ~/.claude/hooks/）
• repo root の inspiration.md（repo 固有文書。harness に正本なし — diff 対象外だが、 skills/<name>/ 配下に置くと置換で消えるため root に置く）

script を置かない repo: 汎用化 fork の curated repo（code-and-llm-collaboration, llm-agent-security-principles — 意図的に乖離、diff 同期しない）と、harness に正本を 持たない repo 単独 skill（agent-adoption-triage 等）。新しい単独 skill repo を作ったら script を vendor するのが default — 例外にする場合はここに理由ごと追記する。