change-publish

change-publish

此技能的作用

将已接受的 ChDR编入项目的记忆层 {REPO_ROOT}/docs/adlc/memory/chdr/：

• 验证已接受的 ChDR（状态，以及 Decision 声明的来源信息）
• 将每个已提升的 ChDR 写入 docs/adlc/memory/chdr/ChDR-{NNN}.md，并添加 OKF 风格的 frontmatter
• 重新生成 {REPO_ROOT}/docs/adlc/memory/chdr/chdr.md——这是面向启动的索引，team-boot 会将其注入会话启动上下文（位于类别目录中，遵循 adr/adr.md 和 pdr/pdr.md 的相同约定）
• 将源草稿标记为 ### Status: **Published**

与 /team-levelup（会针对 team-ai-directives 发起 PR）不同，change-publish 写入的是项目本地记忆——ChDR 描述的是此代码库的演进，无法通过团队级信号门槛。不会创建 PR；用户按常规流程提交即可。

只有通过 /change-clarify 接受 ChDR 后，此技能才会运行。

适用时机

• 运行 /change-clarify 后：需要将已接受的 ChDR 提升到记忆层
• 重新运行 /change-init 后：有新的已接受 ChDR 需要添加到记忆索引

不适用时机

• 没有已接受的 ChDR：先运行 /change-clarify
• 发现 ChDR：使用 /change-init
• 审查 ChDR：使用 /change-clarify

流程

用户输入

$ARGUMENTS

示例：

• "ChDR-001 ChDR-003" — 仅提升指定的 ChDR
• 输入为空：提升所有已接受的 ChDR

角色与上下文

你将担任记忆发布者——将已接受的 ChDR 从本地草稿移入持久化的项目记忆。你的职责：

• 再次验证来源信息（这是防止污染的断路器——未经来源验证的决策一经提升，就会通过 team-boot 污染每个后续会话）
• 使用 team-boot 可索引的 frontmatter 写入已提升的记录
• 重新生成 chdr.md 索引，让下次会话启动时能看到新决策

概要

1. 环境设置（阶段 0）：解析路径，列出已接受的 ChDR
2. 前置条件检查（阶段 1）：确保存在已接受的 ChDR
3. 来源验证（阶段 2）：重新验证每条 Decision 声明都包含 SHA/URL
4. 重复项检查（阶段 3）：跳过记忆中已存在且 issue key 相同的 ChDR
5. 记忆记录生成（阶段 4）：写入 docs/adlc/memory/chdr/ChDR-{NNN}.md
6. 索引重新生成（阶段 5）：重建 docs/adlc/memory/chdr/chdr.md（面向启动）
7. 草稿状态更新（阶段 6）：将已提升的草稿标记为 Published
8. 摘要（阶段 7）：报告结果

执行步骤

阶段 0：环境设置

运行：

scripts/bash/setup-change-publish.sh

解析 JSON 中的 REPO_ROOT、CHDR_DRAFTS_DIR、MEMORY_DIR、MEMORY_INDEX、ACCEPTED_CHDRS。

如果设置脚本不可用或运行失败，则手动解析：

1. REPO_ROOT — 向上查找 .adlc/，或运行 git rev-parse --show-toplevel。
2. CHDR_DRAFTS_DIR — REPO_ROOT/.adlc/drafts/chdr
3. MEMORY_DIR — REPO_ROOT/docs/adlc/memory/chdr
4. MEMORY_INDEX — REPO_ROOT/docs/adlc/memory/chdr/chdr.md（位于类别目录中，如 docs/adlc/memory/adr/adr.md 和 pdr/pdr.md）
5. ACCEPTED_CHDRS — grep -l '^### Status: \*\*Accepted\*\*' CHDR_DRAFTS_DIR/ChDR-*.md

阶段 1：前置条件检查

如果 ACCEPTED_CHDRS 为空：

No accepted ChDRs found.
Run /change-clarify to accept ChDRs first.

阶段 2：来源验证

对于每个已接受的 ChDR，重新验证：### Decision 中的每个非平凡句子都引用了 SHA（\b[0-9a-f]{7,40}\b）或 URL（https?://）。跳过未通过来源验证的 ChDR——它们不能被提升（存在污染风险）：

## Provenance Validation

**Passing**: N | **Skipped**: M

### Skipped ChDRs

| ChDR | Reason |
|---|---|
| ChDR-XXX | Decision claim lacks SHA/URL provenance |

被跳过的 ChDR 在草稿中仍保持 Accepted 状态，供用户修正。

阶段 3：重复项检查

对于每个通过验证的 ChDR，检查是否已存在具有相同 ### Issue Links key 的记忆记录。如果存在，则跳过（或提供合并选项）——不要创建重复项。

阶段 4：记忆记录生成

对于每个已接受的 ChDR，写入 {MEMORY_DIR}/ChDR-{NNN}.md：

---
type: ChDR
title: {title from heading}
description: {descriptor from draft}
resource: ./docs/adlc/memory/chdr/ChDR-{NNN}.md
tags: [chdr]
generated:
  by: agent:change-publish
  at: {today}T00:00:00Z
id: ChDR-{NNN}
created: {date from draft}
verified:
  - by: agent:change-publish
    at: {today}T00:00:00Z
status: stable
stale_after: 365d
sources:
  - id: {sha}
    resource: git:{sha}
    title: {commit subject}
  - id: {issue-key}
    resource: {issue-url}
    title: {issue title}
---

# {Title}

{Content from draft — Context, Decision, Consequences, Evidence verbatim}

## Source

Promoted from: .adlc/drafts/chdr/ChDR-{NNN}.md

阶段 5：重新生成索引（面向启动流程）

这是与 team-boot 的集成点。 通过列出 {MEMORY_DIR} 中的所有 ChDR-*.md 文件，并构建一个行首为 | ChDR- 的 Markdown 表格（team-boot 使用的 awk 筛选器），重新生成 {MEMORY_INDEX}（{REPO_ROOT}/docs/adlc/memory/chdr/chdr.md）：

# Change Decision Records (Memory)

## ChDR Index

| ID | Title | Status | Date | Issues | Commits | Descriptor |
|----|-------|--------|------|--------|---------|------------|
| ChDR-001 | Why payments retries are capped at 3 | stable | 2026-08-16 | PROJ-123 | abc1234 | Consult before changing retry config |

**Stats**: N entries | Last Updated: YYYY-MM-DD

team-boot 的 boot.sh/boot.ps1 会读取此文件，并将 ## ChDR Index 部分和 CHDR_COUNT 与 PDR/ADR 索引一并写入会话启动上下文。

阶段 6：更新草稿状态

对于每个已晋升的 ChDR，将草稿文件的状态更新为 ### Status: **Published**，并添加：

### Promotion

- **Date**: [YYYY-MM-DD]
- **Memory path**: docs/adlc/memory/chdr/ChDR-{NNN}.md

阶段 7：总结

## Change-Publish Summary

**ChDRs Promoted**: N
**ChDRs Skipped (provenance)**: M
**ChDRs Skipped (duplicate)**: K

### Artifacts

| Type | Count |
|---|---|
| Memory records (docs/adlc/memory/chdr/) | N |
| Boot index (docs/adlc/memory/chdr/chdr.md) | 1 (regenerated) |

### Next Steps

The next session start (`team-boot`) will inject the ChDR index into context.
Commit `docs/adlc/memory/chdr/` (records + `chdr.md`) via your normal flow.

关键规则

晋升前核实来源依据

• 晋升一个没有来源依据的 Decision 会污染所有后续会话（team-boot 会注入它）
• 在发布时重新核实来源依据，而不只是在澄清时核实

项目本地，而非团队范围

• ChDR 发布到 docs/adlc/memory/，而不是 team-ai-directives
• 不创建 PR——用户按常规流程提交
• 按设计，ChDR 无法通过 team-levelup 的“适用于整个团队”信号门槛

索引格式必须与 team-boot 一致

• 行首必须为 | ChDR-（boot.sh/boot.ps1 中的 awk/regex 筛选器）
• 文件必须位于 docs/adlc/memory/chdr/chdr.md（在类别目录内，与 adr/adr.md 和 pdr/pdr.md 类似）；双重读取回退路径为 docs/adlc/memory/chdr.md（较早的根目录级位置）和 .adlc/memory/chdr.md（旧版布局）

工作流指导与转换

执行 /change-publish 后

/change-init → /change-clarify → /change-publish
    ↓
[team-boot] → injects docs/adlc/memory/chdr/chdr.md index at next session start
    ↓
[Agent consults ChDRs on demand when touching affected code]

定期重新运行 /change-init，以挖掘新的历史记录；新的已接受 ChDR 会添加到记忆中，并重新生成索引。

后续步骤

提交记忆目录。下一个会话会通过 team-boot 自动获取 ChDR 索引。

验证

• 所有具有来源依据且已接受的 ChDR 均已晋升至 docs/adlc/memory/chdr/ChDR-*.md。
• 已重新生成 docs/adlc/memory/chdr/chdr.md 索引，且行首为 | ChDR-。
• 已晋升的草稿均标记为 ### Status: **Published**。
• 未晋升任何没有来源依据的 ChDR。
• 记忆中没有重复的 issue key。

上下文

$ARGUMENTS