agent-history-hygiene

agent-history-hygiene

エージェントのトランスクリプトとプランファイルは、それらが生み出した機能を記録するコミットに含めます。秘密情報を漏らしたり、記録プロセスの実行中にファイルを変更したりしないでください。

目的別に分けた各項目：

項目	答える質問
run-specstory-session.sh	「最終処理の前に記録プロセスが終了したことを、どう証明できますか？」
queue-agent-commit.sh	「ライブの履歴に触れずに、許可されたこのコミットを正確にキューに登録するにはどうすればよいですか？」
finalize-agent-commit.sh	「セッション後の正確なスナップショットをサニタイズしてコミットするにはどうすればよいですか？」
find-session.sh	「現在のセッションのトランスクリプト／プランファイルはどれですか？」
stage-agent-artifacts.sh	「準備済みのインデックスに含める正確なエージェントファイルはどれですか？」
agent-commit-metadata.sh	「コミットに含める由来情報のトレーラーはどれですか？」
bootstrap-project.sh	「検証のみを行うフックをインストールするにはどうすればよいですか？」
scan-staged.sh	「実際にステージされているインデックスはクリーンですか？」
probe-specstory-redaction.py	「SpecStory は標準で何をマスキングしますか？」

基本的な不変条件

1. トランスクリプトとプランは、それらが生み出した機能と一緒にコミットします。 .specstory/history/ を無視したり、変更のあるエージェントの成果物をレビュー履歴から黙って除外したりしないでください。

2. SpecStory の状態はレビュー履歴ではありません。 無視するのは .specstory/.project.json と .specstory/statistics.json のみです。どちらもマシン固有で、再生成できます。

3. Git 履歴を変更する前に、プロセスが停止していることを確認します。 記録プロセスがアクティブな場合、コミット、pull --rebase、リベース／ベース更新、統合、ワークツリー／セッションの終了は禁止されます。必須の順序：

   recorder quiescence
     -> exact artifact + message finalization
     -> ordinary hook-enabled commit proven
     -> history/ref movement or retirement
   

4. 由来情報はステージされたスナップショットから取得します。 セッション、トランスクリプト、プランを正確に指定し、ステージされていない成果物をトレーラーで参照したり、不明なモデルを推測したりしないでください。

5. Git の書き換え前に、プロバイダー側で認証情報をローテーションします。 マスキングによって新たな到達可能性は防げますが、認証情報が無効になるわけでも、すべてのローカルコピーが消去されるわけでもありません。

6. 漏えいの対処に通常の git push --force を使わないでください。 チームメイトの作業を破壊するおそれがあり、既存のクローンやキャッシュからデータを削除することもできません。

7. 配布するファイルはスキャナーで安全と判定される必要があります。 npx skills add は、このディレクトリ全体を利用者のスキャン対象範囲にインストールします。秘密鍵のヘッダーをそのまま埋め込まないでください。テスト実行時に組み立てるか、合成プレースホルダーを使用してください。これは tests/test_shipped_file_hygiene.py で強制されます。

使用する場面

次の場合にこのスキルを使用してください。

• ユーザーが SpecStory のセッション、トランスクリプト、またはプランのコミット／保存を求めている場合。
• 変更のある .specstory/history/*.md、.claude/plans/*.md、.cursor/plans/*.md、または別途設定された成果物が機能に伴う場合。
• .specstory/.project.json または statistics.json が繰り返し変更される場合。
• ユーザーがエージェントの成果物に対する pre-commit／gitleaks のインストールを求めている場合。
• スキャナーがエージェントの成果物内の秘密情報を検出した場合。または
• 認証情報がコミットまたはプッシュされた場合。書き換えを行う前に references/remediation.md を読んでください。

ユーザーがエージェントの履歴を明示的に除外したい場合、またはエージェントの成果物が存在しない場合は使用しないでください。漏えいがすでに共有の main／release に含まれている場合、そのブランチの書き換えを提案しないでください。修復手順書を使用してください。

デフォルトのライフサイクル：今すぐキューに登録し、終了後に最終処理する

このライフサイクルを実行または復旧する前に、 references/post-session-finalization.md を読んでください。すべての状態、終了コード、復旧アクション、再試行禁止の境界が定義されています。

1. 同期ラッパーを起動する

目的のワークツリーから、Claude を起動する前に実行します。

bash skills/local/agent-history-hygiene/scripts/run-specstory-session.sh \
  --allow-commit claude

--allow-commit は、外側の親プロセスに1回限りの最終処理機能を与えます。子プロセスがユーザーの同意を推測できるようにするものではありません。エージェントは、キューに登録する前に明示的なコミット許可を待つ必要があります。

ラッパーを Stop フック、デタッチされたウォッチャー／デーモン、またはライブチェックポイントに置き換えないでください。Stop フックは、プロセス／記録プロセスが停止したことを確認する前に実行されます。デーモンを使うと、記録プロセスの寿命とセッションが切り離されます。ライブチェックポイントでは、ファイルがまだ変更される可能性がある間にコミットが行われます。

2. 通常どおり作業し、機能パスのみをステージングします

Claude /status から正規の小文字 UUID を取得します。正確な SpecStory パスとプランポリシーを特定します。1 つの UUID に複数の表示エイリアスがある場合は、曖昧さを解消するため、UUID とパスの両方を渡します。

SESSION_ID=01234567-89ab-4cde-8fab-0123456789ab
TRANSCRIPT='.specstory/history/2026-09-01_02-14-50Z.md'
PLAN='.claude/plans/exact-change.md'

git add -- path/to/feature-a path/to/feature-b

ライブトランスクリプトやプランはステージングしないでください。SpecStory の終了後、最終処理が正確な成果物のステージングとサニタイズを行います。

3. ユーザーから明示的なコミット許可を得た後、一度だけキューに登録します

ライフサイクル管理対象のトレーラーを含めずに、UTF-8 のベース件名と本文を作成し、正確なセレクターを指定してキューに登録します。

MESSAGE_FILE="${TMPDIR:-/tmp}/agent-commit-message.txt"
printf '%s\n' \
  'feat(scope): summarize the change' \
  '' \
  'Explain why the change is needed.' > "$MESSAGE_FILE"

bash skills/local/agent-history-hygiene/scripts/queue-agent-commit.sh \
  --commit \
  --session-id "$SESSION_ID" \
  --specstory-path "$TRANSCRIPT" \
  --plan "$PLAN" \
  --message-file "$MESSAGE_FILE"
# Use --no-plan instead of --plan only when no plan exists.

キューはベースメッセージのみを、ワークツリーごとの非公開状態にコピーします。ライブトランスクリプトの読み取り、ステージング、スキャン、編集、コミットは行いません。

status=queued になったら、**「最終処理をキューに登録しました」**と報告し、エージェントセッションを終了します。それ以降、リポジトリやインデックスに対する操作は一切行わないでください。git status、diff、メッセージ編集、同期、最終処理の呼び出しも行ってはいけません。

4. 外側のランナーに処理を完了させます

新しい実行ではプロトコル v2 を使用し、デフォルトでクラウド同期を行いません。明示的に選択した設定は、構成を変更せずにネイティブの実行フラグと同期フラグに反映されます。既存の v1 リクエストは、暗黙のアップグレードを行わず、元の厳格なスキーマとリカバリールールを維持します。子プロセスの終了コードが 0 で、プロセスグループが静止した後に限り、ランナーは次の処理を行います。

1. ライフサイクルの証明を記録します。
2. 選択したクラウド不使用ポリシーで、UUID を正確に指定した静かな同期を 1 回実行します。
3. 選択したエイリアスの完全なダイジェストを、制限付きの非公開ネイティブ sync --print --silent --no-cloud-sync --no-stats エクスポートと照合して検証します。前後で変更されていないネイティブ JSONL の世代と紐付けます。エクスポートがサポートされていない場合やエイリアスが古い場合は停止します。
4. 親が保持するトークンを使って最終処理を呼び出します。
5. ロックされた代替インデックスで、正確な成果物をステージングしてサニタイズします。
6. 正規のトレーラーを導出し、非公開の引き継ぎドラフトを書き込み、通常のフックを有効にした状態で、通常の git commit -F を 1 回実行します。
7. 生成されたコミットの親、ツリー、ブランチ、および Agent-History-Request トレーラーを検証します。

書き込み処理が進行中の通常の pre-commit 実行は安全ではありません。ステージングされていない変更がある場合、pre-commit はそれらを退避し、ステージング済みの内容をチェックアウトまたは変更した後、退避した変更を復元することがあります。このチェックアウトと復元のシーケンスは記録処理と競合し、バイト列を上書きしたり、競合を起こしたり、再導入したりする可能性があります。そのため、pre-commit チェッカーは検証のみを行います。静止状態で実行される最終処理だけが、認可された変更処理です。

最終処理の結果

• 成功（committed／終了コード 0）： 通常のフック有効化済みコミットが行われたことを確認済みです。 この場合に限り、リベース／ベース更新、統合、または廃止に進めます。
• サニタイズ（rotation_required／終了コード 10）： インデックスと実ファイルのアーティファクトが正確にサニタイズされ、非公開の完全な変更前データ／出現箇所の証拠と下書きが保持され、コミットは試行されていません。v2 の読み取り専用 --preview-review --json では、マスクされた検出結果が表示されます。非公開のバージョン管理された --review-file で、すべての検出結果が reviewed_noncredential、credential_rotation_required、または unresolved のいずれかとして説明されます。確認済みのフィクスチャをすべてそろえると、最新の --allow-commit によって、このサニタイズ済みスナップショットに限りローテーションゲートが解除されます。実際の認証情報には、ローテーションと --rotation-confirmed が引き続き必要です。また、未解決または不完全なレビューが混在している場合はブロックされます。生のバイト列が復元されること、ポリシーの許可リストが追加されること、またはフックがスキップされることはありません。レガシー v1 ではローテーションのみの復旧が維持され、v2 のレビュー証拠を取得することはできません。
• 部分的な公開（publication_unproven／終了コード 8）： 非公開の証拠は保持されていますが、インデックス／ソースの公開を完全には確認できませんでした。状況を調査してください。ロールバックされた、またはサニタイズが自動的に再実行されると決めつけないでください。
• フック／コミット失敗（commit_failed／終了コード 11）： HEAD は変更されておらず、準備済みの正確なツリーと下書きが残っています。そのスナップショットを変更せずにフックを修正し、最新の --allow-commit を指定して、明示的な復旧呼び出しを 1 回行ってください。自動再試行はありません。
• 結果が不確定（終了コード 8）： 調整のみ行ってください。別のコミットを自動的に実行しないでください。HEAD が正確であることを確認するか、調査のためにエスカレーションしてください。
• 手動引き継ぎ： LazyGit はワークツリーごとの LAZYGIT_PENDING_COMMIT を読み込みます。標準の Git はワークツリーごとの COMMIT_EDITMSG を使用します。下書きがあれば復旧は可能ですが、コミットが行われた証拠にはなりません。

実際のリベースは、古い REBASE_HEAD ファイルだけではなく、Git の状態ディレクトリ（rebase-merge または rebase-apply）で判定します。ほかのアクティブな操作マーカーと index.lock も、キュー処理／最終処理をブロックします。

リポジトリをブートストラップする

ブートストラップまたは移行の前に、 references/pre-commit-redaction-stack.md を読んでください。

現在のフックリリース： ahh-v2.0.1 は、チェックイン済みテンプレートとフック移行先で使用される、変更不可の公開済みピンです。新規のブートストラップでは、gitleaks v8.30.1 もピン留めし、Sourcegraph／Git-OID の誤検出を修正するスコープ付きの変更をインストールします。ahh タグだけを更新しても、既存のルート .gitleaks.toml は書き換えられません。既存リポジトリについては、リファレンスのロールアウト手順に従ってください。

bash skills/local/agent-history-hygiene/scripts/bootstrap-project.sh \
  --install-hook
pre-commit run --all-files

ブートストラップでは、次のものがインストールされます。

• 検証のみを行うステージ済みインデックスチェッカーと gitleaks。
• history/ を表示したままにする、SpecStory 状態用の正確なネストされた除外設定。
• すべてのエージェント／アーカイブ／インストールルート（.agents、.claude、.codex、.cursor、.opencode、.specify、.specstory）を変更対象から除外する、一般的な衛生管理フック。および
• オプションの、検証のみを行う prepare-commit-msg の完全一致セレクターゲート。

セキュリティチェッカーは、これらのルートも引き続き対象にします。空白／EOF／フォーマッターの対象から .specstory のみを除外するだけでは不十分です。.agents/skills/ にはインストールされたベンダーコードが含まれており、.claude/skills/ がそこへのシンボリックリンクになっている場合があります。

古い ahh-v1.1.0 または厳密なローカルレダクター構成の場合、リリース後の移行はトランザクション方式で、フェイルクローズです。

bash skills/local/agent-history-hygiene/scripts/bootstrap-project.sh --migrate

互換性のある兄弟フック／オプションを保持し、公開前に候補を検証します。また、曖昧なコマンドやカスタマイズされたレガシーコマンドがある場合は処理を拒否します。

漏えい後の修復

スキャンで実際の認証情報が見つかった場合、またはユーザーからコミット／プッシュ済みと伝えられた場合：

1. 反射的な強制プッシュをすべて停止します。
2. references/remediation.md を最初から最後まで読みます。
3. 影響範囲にかかわらず、プロバイダー側で認証情報をローテーションします。
4. その後に限り、ランブックから最も影響の少ない Git 操作を選択します。

注意点

• .gitignore は既存の状態を追跡対象から外しません。 bootstrap-project.sh --untrack-specstory-state を使用してください。 除外対象を .specstory/ に広げてはいけません。
• SpecStory >= 2.4.0 は書き込み時に機密情報をマスキングしますが、コンテキストやルールに漏れがあります。ネイティブのマスキングを有効にしたままにし、ファイナライザーによるチェックも維持してください。プレースホルダーや対象範囲を変更する前に、 references/specstory-native-redaction.md をお読みください。
• SpecStory 2.10 はブランチ単位ではなく、チェックアウトパス単位で動作します。先にワークツリーを作成し、変更ストリームごとにラッパー／セッションを 1 つずつ起動してください。EnterWorktree では既存のレコーダーは再バインドされません。
• 厳密な検出では、不完全な JSONL、エイリアス、シンボリックリンク、安全でないバイト列、ワークツリー間の ID の不一致が拒否されます。解決結果が空または曖昧な場合は、 references/transcript-session-discovery.md をお読みください。
• 一部の Claude Code バージョンでは、プロジェクトスコープで plansDirectory が無視される場合があります。プランの保存先を確認してください。ユーザーレベルの "plansDirectory": "./.claude/plans" が推奨されるデフォルトです。
• pre-commit install はクローンごとに実行する必要があります。CI は二度目の機会であり、最後のゲートではありません。
• --install-hook を使用するには、core.hooksPath が実際に未設定である必要があります。空、相対、グローバル、またはカスタムの値が設定されている場合は拒否されます。設定済みのフックディレクトリには、検証のみを行うゲートを自分で組み込んでください。
• gitleaks protect は非推奨です。gitleaks git --staged または gitleaks dir を使用してください。
• 2 MiB のトランスクリプト上限を引き上げるのではなく、サイズの大きいセッションはローテーションしてください。

利用可能なスクリプト

• run-specstory-session.sh [--allow-commit] claude [-- OPTIONS...] — フォアグラウンドのプロセスグループを管理し、子プロセスおよびシグナルの終了ステータスを保持し、終了後に正確な同期を1回実行して、必要に応じてファイナライザーを1回呼び出します。
• queue-agent-commit.sh --commit --session-id UUID --specstory-path PATH (--plan PATH|--no-plan) --message-file PATH — 厳密なメタデータのみのワークツリーごとのリクエストを1つ書き込みます。同一のリクエストを繰り返しても冪等です。
• finalize-agent-commit.sh --request ABSOLUTE_PATH (--allow-commit|--runner-token TOKEN) [--rotation-confirmed] [--review-file PATH] — ライフサイクルとスナップショットの証明を検証し、正確にサニタイズされた成果物と下書きを用意して、通常のコミットを1回実行し、不確実な状態を再試行せずに調整します。V2 の --preview-review --json は認可不要で、書き込みを一切行いません。--prepare-only、--expected-revision DIGEST、--reconcile-only は、2つ目のコミットエンジンを使わない軽量なネイティブアダプターに対応します。
• _post_session.py capabilities --json / inspect --request PATH --json — 副作用のない範囲限定のプロトコル検出とレシートの再証明を行います。inspect --context --json では、真正な実行中のラッパーの祖先も必要です。公開出力に含まれるのは識別情報とダイジェストのみで、生のトランスクリプトやメッセージの値は含まれません。V2 では凍結されたインデックス全体のテキスト網羅性が必須です。プロダクトに関する検出結果があれば変更せずに処理をブロックし、未対応のバイナリやサイズ超過の網羅性については明示的に失敗します。
• find-session.sh (--session-id UUID|--specstory-path PATH|--newest) [--format specstory|claude|both] [--json] — チェックアウトとセッションの正確な証明を行います。--newest は互換性のためのヒューリスティックにすぎません。
• stage-agent-artifacts.sh ... — 正確なステージング、または広範囲のアトミックなステージングを行います。 --sanitize-index はロックされた代替インデックスで選択された BLOB をサニタイズします。--materialize-sanitized は生成後に、世代チェックを行って、それらの正確にサニタイズされたバイト列を安全に書き戻します。--check-staged は変更を一切行いません。
• agent-commit-metadata.sh [--harness NAME --model NAME] [--format trailers|json] — ステージ済み BLOB から正規の来歴情報を導出します。
• scan-staged.sh [--redact|--no-redact] [--config PATH] [--verbose] — 有効なインデックスを検証します。範囲限定の機密情報を含まない JSON 検出結果のみを出力し、スキャナーの生出力は抑制します。
• probe-specstory-redaction.py [--json] [--keep] [--dry-run] — ネイティブな対応範囲を測定します。SpecStory が存在しない場合は終了コード 30 を返します。
• bootstrap-project.sh [--migrate] [--install-hook] [--untrack-specstory-state] [--force] [--dry-run] — 検証スタックをインストールまたは移行します。前述の未公開の v2.0.0 に関するブロッカーに注意してください。

同梱アセット

• assets/artifact-dirs.txt — 正規の成果物ディレクトリ一覧。
• assets/pre-commit-config.yaml.template — 検証専用チェッカー、gitleaks、およびアーカイブとインストールルートの変更ツールを完全に除外した汎用的な衛生チェック。
• assets/gitleaks.toml.template — カスタムルールとスコープを限定した許可リストの例。
• assets/redact_secrets.py — ステージ済みインデックスのチェッカー兼サニタイザー。--check-index は正規または一時的なコミットインデックスを受け入れます。--fix-index には、ユーザーが明示的に所有する非正規の GIT_INDEX_FILE と、正確に指定された --files が必要です。

リファレンスファイル

• references/post-session-finalization.md — キューへの登録、ファイナライズ、復旧、リベース、統合、または廃止の前に読み込んでください。
• references/transcript-session-discovery.md — セッションまたはパスを正確に解決できない、曖昧である、または一致しない場合に読み込んでください。
• references/pre-commit-redaction-stack.md — 初期設定、移行、ルールの調整、またはスキャナーやフックの動作のデバッグ時に読み込んでください。
• references/specstory-native-redaction.md — ネイティブのレダクションに関する前提、センチネル、または対応範囲を変更する前に読み込んでください。
• references/remediation.md — 漏えい後に履歴を書き換えたり強制プッシュしたりする前に読み込んでください。

テスト

リポジトリのルートから実行します。

make test-skill

このテストスイートでは、正確な検出とステージング、代替インデックスのサニタイズとマテリアライズ、検証のみの移行とフック、スキャナーで安全に処理できる出力、ランナー／ファイナライザーの認可と復旧、古い REBASE_HEAD、プライベート状態、配布ファイルの安全性を網羅します。全項目と直接実行するコマンドについては、tests/README.md をご覧ください。

関連スキル

• git-workflow — 正規の Conventional Commit とプロベナンスメッセージの検証。
• project-knowledge-harness — このスキルが Git で保持する計画用スクラッチパッドを備えた、プロジェクトのメモリ。