agent-history-hygiene

agent-history-hygiene

将 Agent 会话记录和计划文件与其所产出的功能一同提交，避免泄露机密，也避免在记录器运行时修改文件。

各界面按用途划分：

界面	回答的问题
run-specstory-session.sh	“如何确认记录器已退出后再进行最终处理？”
queue-agent-commit.sh	“如何将这个确切获授权的提交加入队列，而不触碰实时历史记录？”
finalize-agent-commit.sh	“如何清理并提交会话结束后的确切快照？”
find-session.sh	“当前会话对应哪个会话记录 / 计划文件？”
stage-agent-artifacts.sh	“哪些确切的 Agent 文件应加入准备好的索引？”
agent-commit-metadata.sh	“提交中应包含哪些来源信息尾注？”
bootstrap-project.sh	“如何安装仅用于验证的钩子？”
scan-staged.sh	“有效的暂存索引是否干净？”
probe-specstory-redaction.py	“SpecStory 原生会对哪些内容进行脱敏？”

核心不变量

1. 将会话记录和计划与其产出的功能一同提交。 绝不要忽略 .specstory/history/，也不要悄悄将有改动的 Agent 产物从审查记录中移除。

2. SpecStory 状态不属于审查历史。 仅忽略 .specstory/.project.json 和 .specstory/statistics.json；它们均为 机器本地文件，可重新生成。

3. Git 历史变更前必须确认已静止。 记录器运行时，禁止提交、 pull --rebase、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 持续发生变化；
• 用户要求为 Agent 产物安装 pre-commit/gitleaks；
• 扫描器在 Agent 产物中发现机密；或
• 凭据已被提交或推送——在进行任何重写前，请阅读 references/remediation.md。

如果用户明确要求排除 Agent 历史记录，或不存在 Agent 产物，则不要使用此技能。 如果泄露已出现在共享的 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 为外层父进程提供一次运行的最终处理能力。 它不会让子进程推断用户已同意。Agent 仍须等待用户明确授权提交后才能将其加入队列。

不要用 Stop 钩子、分离运行的监视器 / 守护进程或实时检查点替代此封装脚本。Stop 钩子会在尚未确认进程 / 记录器已静止时运行；守护进程会使记录器的生命周期与会话脱离；实时检查点则会在文件仍可能变化时提交。

2. 正常工作；仅暂存功能路径

从 Claude /status 获取规范的小写 UUID。解析准确的 SpecStory 路径和计划策略；如果一个 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 时，报告 “最终处理已排队”，并退出 Agent 会话。 不要再执行任何仓库/索引操作——甚至不要运行 git status、查看差异、编辑消息、同步或调用最终处理器。

4. 由外层运行器完成后续工作

新运行使用协议 v2，默认不进行云同步；显式选择会传递给原生运行和同步标志，而不会更改配置。现有 v1 请求保留其严格的原始架构和恢复规则，绝不隐式升级。只有在子进程以 0 退出且进程组已静止后，运行器才会：

1. 记录生命周期证明；
2. 按选定的不进行云同步策略，执行一次精确的静默 UUID 同步；
3. 将所选别名的完整摘要与有界的私有原生 sync --print --silent --no-cloud-sync --no-stats 导出进行验证，并绑定前后未变的原生 JSONL 生成版本（不支持导出或别名过期时停止）；
4. 使用其持有的父级令牌调用最终处理器；
5. 在锁定的备用索引中暂存并清理准确的工件；
6. 推导规范尾注，写入私有交接草稿，并调用一次普通的 git commit -F，启用常规钩子；以及
7. 证明生成结果的父提交、树、分支和 Agent-History-Request 尾注。

写入器仍在活动时，常规的提交前执行并不安全：存在未暂存的更改时，提交前钩子可能会将其暂存起来、检出/修改已暂存的内容，然后恢复暂存内容。此检出/恢复序列可能与记录器发生竞争，导致字节被覆盖、产生冲突或重新引入。因此，提交前检查器仅用于验证；静止状态下的最终处理器是唯一获准执行修改的组件。

完成结果

• 成功（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 显式调用一次进行恢复。 不会自动重试。
• 结果不确定（退出码 8）： 只能进行核对。绝不自动发起另一笔提交；确认精确的 HEAD， 或升级处理以供检查。
• 手动交接： LazyGit 读取每个工作树的 LAZYGIT_PENDING_COMMIT；标准 Git 使用每个工作树的 COMMIT_EDITMSG。 草稿可以用于恢复，但不能证明提交已发生。

实际变基由 Git 的状态目录（rebase-merge 或 rebase-apply）判定，不能仅凭过时的 REBASE_HEAD 文件判断。其他进行中的操作 标记和 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；
• 精确的嵌套 SpecStory 状态忽略规则，同时保留 history/ 可见；
• 通用卫生钩子，其修改器会排除所有 Agent/归档/安装根目录： .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 的作用范围是检出路径，而非分支。请先创建工作树，然后为每个变更流启动一个包装器/会话。EnterWorktree 不会重新绑定现有记录器。
• 精确发现会拒绝不完整的 JSONL、别名、符号链接、不安全字节和跨工作树标识。当解析结果为空或有歧义时，请阅读 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...] — 管理前台进程组，保留子进程和信号状态，退出后执行一次精确同步，并可选择调用一个最终处理器。
• queue-agent-commit.sh --commit --session-id UUID --specstory-path PATH (--plan PATH|--no-plan) --message-file PATH — 写入一个严格的、仅含元数据的单工作树请求；重复提交相同请求具有幂等性。
• finalize-agent-commit.sh --request ABSOLUTE_PATH (--allow-commit|--runner-token TOKEN) [--rotation-confirmed] [--review-file PATH] — 验证生命周期／快照证明，准备精确的净化制品和草稿，执行一次常规提交，并在状态不确定时进行协调，不重试。V2 --preview-review --json 无需授权且不会写入；--prepare-only、--expected-revision DIGEST 和 --reconcile-only 支持轻量原生适配器，无需第二套提交引擎。
• _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 会在锁定的备用索引中净化选定内容；--materialize-sanitized 会在生成检查后安全地将这些精确净化后的字节写回；--check-staged 不会修改内容。
• agent-commit-metadata.sh [--harness NAME --model NAME] [--format trailers|json] — 根据已暂存内容生成规范来源信息。
• 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] — 安装／迁移验证栈；请记住上文提到的 unpublished-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 中保留其计划草稿。