格式遵循 Keep a Changelog。

2.13.0 — 2026-05-07

新增

• pactkit interface-summary CLI — 基于 AST 的接口摘要提取，物理输出仅包含签名、类型和 docstring。为 Act Phase 1 分层加载实现 "Code Enforces, Prompt Instructs" 原则——AI 收到的内容在物理层面就是精简的。
• Act Phase 4 Journey Sync — 条件步骤，当 Story 修改了 journey 相关步骤时自动更新 docs/e2e/journey.md。补全了 create→consume→update 生命周期闭环。
• Plan Phase 3.2a Journey Segment — 条件性 Spec 标注，将 Story 与 journey 步骤关联，使 Act Phase 4 能自动检测是否需要同步。

2.12.0 — 2026-05-06

变更

• Rules 架构重构 — 将 6 个全局核心 rules 合并为单个 pactkit.md；按需规则重新编号为 01-06，移至 ~/.claude/skills/_rules/。每次对话减少约 60% 的 context window 消耗。
• 版本不匹配自动部署 — pipx upgrade pactkit 后，下一条 CLI 命令自动同步已部署文件，无需手动执行 pactkit init。

修复

• deployer 中的硬编码路径 — _build_command_rules_header() 现在使用 FormatProfile.rules_dir / skills_dir 替代硬编码的 ~/.claude/ 路径。
• 过期文件名引用 — 更新了 visualize.py、commands.py、lazy_visualize.py 和测试文件中的交叉引用，匹配新的规则文件名。

2.11.0 — 2026-04-25

新增

• Lateral Scan（横向扫描） — Plan Phase 1 在写 Spec 前扫描重复模式。若与已有实现重叠 > 30%，Spec 必须包含 R0: 提取共享抽象 或明确声明技术债务。
• DEFERRED 注释机制 — 跳过 SHOULD 要求时，代码中必须包含 # DEFERRED(SHOULD): R{N} — 原因 注释。Check 阶段新增覆盖率表格输出，追踪延迟项。

修复

• pactkit.yaml 残留版本操作 — 移除 board.py 中的 update_version() 函数和 CLI 子命令，清理 prompts、agents、skills 文档中的所有过期引用。版本现在仅由 pyproject.toml + __init__.py 管理，部署标记位于 ~/.claude/.pactkit-version。
• CI tree-sitter 依赖 — 在 CI workflow 中单独安装 tree-sitter 可选依赖。

2.10.6 — 2026-04-22

修复

• L3 SHOULD 语义调整 — Signal Strength Convention L3 Recommended 从"违反=警告，非阻塞"改为"默认必须执行——跳过需说明理由"（RFC 2119）。防止 AI 系统性地延迟 SHOULD 任务。

2.10.5 — 2026-04-21

新增

• Solution Design Protocol — 新增规则 12-solution-design.md，要求在实现前进行能力增量评估（框架原生 + 项目已有）。防止框架盲区、项目盲区和硬编码耦合。包含实现约束（禁止魔术值、开闭原则、单一职责、依赖方向）。集成到 Plan Phase 1 和 Act Phase 1。

变更

• 全局版本追踪 — 版本追踪从项目级 pactkit.yaml 迁移至全局 ~/.claude/.pactkit-version 标记文件。消除通过 pipx 升级 PactKit 后的跨项目版本不同步问题。pactkit update --if-needed 现在检查全局标记而非项目 yaml。

2.10.4 — 2026-04-20

新增

• Hotfix 影响检查 — /project-hotfix 新增 Phase 0.5，修复前读取已有的 .mmd 调用图文件。当目标函数有 3+ 调用者时发出警告。建议性（L3），非阻塞，无调用图时静默跳过。

2.10.3 — 2026-04-20

修复

• pactkit clean 保护父级目录 — rglob("dist") 会匹配 node_modules/*/dist，破坏 npm 依赖内部文件。新增 _inside_protected() 守卫，保护 node_modules/ 和 .git/；含路径的模式改用直接匹配。
• CI tree-sitter 测试 — CI workflow 现安装 [visualize] extras，Java/TS 分析器测试在 GitHub Actions 中通过。

2.10.2 — 2026-04-20

新增

• PDCA 推荐协议 — AI 在自由对话中分析出可执行结论时，主动推荐合适的 PDCA 命令。触发矩阵映射信号到命令；抑制规则防止噪音。
• 双维度 Harness 审计 — 审计现评分两个维度：Config（项目 + 全局配置，50 分）和 Code（测试、lint、复杂度、git 卫生，50 分）。JSON 输出包含 dimensions 拆分字段。
• 统一 HTML 报告仪表盘 — 单页 report.html，包含标签切换、D3 力导向图、harness 分数环、层级条和热点面板。

修复

• Shared Protocols Context.md 引用 — 补充 Context.md Canonical Format "Referenced by" 行中缺失的 Act Phase 4，确保 context.md 反映 Act 阶段进展。
• 语义版本比较 — 版本不匹配警告现使用元组比较替代字符串相等，正确给出升级/降级方向。
• Focus 调用图空输出 — 修复 focus 解析使用 LANG_PROFILES[stack].source_dirs 替代硬编码 src/ 前缀。

2.9.13 — 2026-04-15

修复

• 精简核心依赖 — 将适配器包（pactkit-opencode、pactkit-codex）和 tree-sitter 绑定移至 [project.optional-dependencies]。核心 pip install pactkit 现在仅需 pyyaml。按需安装：pactkit[all]、pactkit[visualize]、pactkit[opencode]、pactkit[codex]。
• Spec-lint CLI 回退 — Playbook 现包含 python3 -m pactkit spec-lint 回退路径，适用于 pactkit 不在 $PATH 的环境。
• Board add_story 签名 — Plan playbook Phase 3.3 现显示完整的 add_story 调用签名，包含所有必需参数。

2.9.12 — 2026-04-02

新增

• Copilot 部署适配器 — pactkit-copilot 适配器包通过 entry_points 注册。pactkit update --format copilot 部署 skills、commands、agents 和 copilot-instructions.md 到 .github/。
• OCP 规则头分发 — _build_command_rules_header() 基于 profile.rules_import_style 分发，不再硬编码 profile 名称。
• 多栈自动检测 — pactkit init 自动检测多栈并写入 stack: [python, typescript] 列表语法。
• 两层模块图 — visualize --mode module 生成维度子图。
• Prompt 模板同步 — 所有部署格式统一使用规范 prompt 模板渲染。

修复

• OpenCode rules_import_style — 从 "instructions" 改为 "inline"，匹配实际行为。

2.9.11 — 2026-04-01

修复

• Rules 模板变量 — _deploy_rules() 现通过 _render_prompt() 渲染 {PROJECT_CONFIG_DIR} 等模板变量。此前 Codex/OpenCode 部署的 rules 包含原始模板字符串。
• Copilot Agent YAML 损坏 — Agent tools: 字段被逐字符迭代（[R, e, a, d, ...] → [Read, Write, ...]）。
• Copilot 重复注解 — (terminal only) (terminal only) 修复为单次注解。
• Skill CLI 引用 — 所有 SKILL.md 文件现经过 _replace_slash_commands() 处理。

2.9.10 — 2026-04-01

修复

• Skill 脚本 __future__ 导入 — load_script() 现将 from __future__ import annotations 提升到 _SHARED_HEADER 之前，修复部署的 spec_linter.py SyntaxError。
• Lessons 表格自动修复 — append_lesson() 追加前调用 _repair_table_structure()，修复：缺失表头、错误表头格式、数据行在表头之前。

2.9.9 — 2026-04-01

新增

• GitHub Copilot 适配器支持 — 新增 copilot FormatProfile。pactkit init --format copilot 部署到项目 .github/ 目录。
• 动态 --format CLI 选项 — init、update、upgrade 命令从 VALID_FORMATS 动态派生选项，无需硬编码。

修复

• 排除命令引用清理 — strip_excluded_command_references() 清理所有渲染 prompt 中被排除格式的 /project-sprint 引用。

2.9.4 — 2026-03-31

修复

• Init playbook DIP 违规 — 消除 DETECTED_ENV 运行时 IDE 检测；所有硬编码路径替换为模板变量。
• 全量 DIP 审计 — 修复 doctor skill、core-protocol 规则和 done 命令中的硬编码 IDE 路径。
• tree-sitter 升级为核心依赖 — 不再可选；CI 安装已更新。
• --focus 扫描优化 — _scan_files 现仅扫描聚焦子目录，不再扫描整个项目根目录。
• SCAN_EXCLUDES 扩展 — 从 13 扩展到 30+ 条目，覆盖 Go、Java、Node、IDE 和 VCS 目录。

2.9.3 — 2026-03-31

新增

• 多语言调用链修复（STORY-slim-069）— dispatch hint 注释解析（pactkit-trace: dispatches_to）和继承边链接从 Python 扩展到 Go（struct embedding）、Java（extends/implements）、TypeScript（class extends）的 tree-sitter 分析器。
• CLI 可视化参数暴露（HOTFIX-slim-070）— --entry、--focus、--reverse、--depth、--max-nodes 现可通过 pactkit visualize CLI 访问。

修复

• 4 类调用链断链（STORY-slim-068）— dict.update 扫描冲突、动态分发提示、抽象方法孤立节点、跨包 stub 边。
• 嵌套子图 call graph（STORY-slim-067）— 支持 fan-in/fan-out 分析和子图分组。
• 边去重 + 环修复（HOTFIX-slim-069）— 重复边使用 ×N 标签，消除假阳性环检测。

2.9.2 — 2026-03-30

修复

• FormatProfile.excluded_commands — OpenCode/Codex 排除 project-sprint（需要子代理团队，仅 Claude Code 支持）。Doctor check_config_drift 现尊重格式级排除。
• 冗余 pactkit.yaml 组件列表 — 移除 .opencode/pactkit.yaml 中的显式 agents/commands/skills/rules 列表（缺省 = 部署全部）。
• 孤立 Spec 清理 — 移除 7 个已归档的旧前缀 Spec 文件。

2.9.1 — 2026-03-30

新增

• 拓扑感知追踪 — ApiCallParser（tree-sitter-typescript）和 AgentParser（LangGraph/YAML/MCP）实现多拓扑代码追踪。Plan/Act 阶段新增拓扑门禁。

修复

• Monorepo 子目录检测 — TopologyParser.detect() 现扫描直接子目录，修复 monorepo 布局的误判。
• Doctor 误报漂移警告 — check_config_drift() 现搜索全局部署目录，而非仅项目本地路径。
• 规范 lessons.md 表头 — Init 强制 | Date | Lesson | Context | 表头，防止 AI 自创列名。

2.9.0 — 2026-03-28

新增

• pactkit init 默认部署所有 IDE 配置 — CLI 默认 --format all，一次性部署 Claude Code + OpenCode + Codex 配置，无需逐个指定 --format。

修复

• 入口点部署器循环导入 — 延迟加载 entry_point 部署器，修复 pipx 环境下 pactkit init 的 ValueError。

2.8.0 — 2026-03-27

新增

• 3-IDE 默认安装 — pip install pactkit 现在自动安装所有三个 IDE 适配器（Claude Code + OpenCode + Codex）。

修复

• OpenCode 命令架构 — 将 OpenCode 从纯 skills 模式恢复为 commands/ + skills/ 双重架构。OpenCode 从 commands/*.md 自动发现命令，而 skills/ 中的嵌入式技能由 AI 代理按需加载。
• Spec 版本混淆 — /project-plan 不再从 pactkit.yaml（工具版本）读取版本号。现在明确从项目清单（pyproject.toml、package.json）读取。

变更

• 跨 IDE 命令架构：
  • Claude Code：纯 skills（skills/project-*/SKILL.md），前缀 /
  • OpenCode：commands + skills（commands/project-*.md + skills/pactkit-*/SKILL.md），前缀 /
  • Codex：纯 skills（skills/project-*/SKILL.md），前缀 $

2.7.0 — 2026-03-27

新增

• Commands → Skills 迁移（STORY-slim-063）— 11 个 PDCA 命令现以 skills/{name}/SKILL.md 子目录格式部署（Claude Code 格式）。VALID_SKILLS 从 10 扩展至 21 项。
• 旧版命令清理 — 升级时自动移除 commands/ 中的旧版 project-*.md 文件。
• Codex FormatProfile（STORY-slim-060）— 在核心中重新添加 codex profile 以支持薄适配器模式。pactkit-codex 首次发布至 PyPI。
• 3 包协调发布 — 首次同时发布 pactkit、pactkit-opencode 和 pactkit-codex。

修复

• board.py update_task（HOTFIX-slim-061）— 现可识别项目符号格式的 Done 区域条目。
• visualize --lazy focus（HOTFIX-slim-062）— 移除硬编码的 focus 刷新；新增文件名匹配。

变更

• 统一部署摘要显示 Skills (embedded + commands) 计数。
• 跨格式隔离：Skills 迁移不影响 OpenCode 和 Codex。

2.6.0 — 2026-03-26

新增

• DeployerProtocol & DeployerBase（STORY-slim-057）— 提取 deployer 接口和共享基类，采用注册表模式实现基于适配器的插件架构。
• pactkit-opencode 适配器包（STORY-slim-058）— 将所有 8 个 OpenCode 专属函数提取为独立包，通过 entry_points 自动注册。
• 入口点自动发现 — 导入时扫描 pactkit.deployers 入口点组，实现零配置适配器注册。

移除

• Codex Profile（STORY-slim-059）— 移除废弃的 codex FormatProfile 及所有引用。VALID_FORMATS 通过 FORMAT_PROFILES.keys() 自动收缩。
• 核心中的 OpenCode 函数 — 8 个函数（约 300 行）迁移至 pactkit-opencode 适配器。deployer.py 体积减少 17%。

变更

• deploy() 通过注册表分发，替代 if/elif 链。新格式只需调用 register_deployer()。

2.5.0 — 2026-03-26

新增

• E2E CLI 覆盖率 100% — 60 个基于子进程的 E2E 测试，覆盖全部 25 个 CLI 子命令
• python -m pactkit — 包支持模块调用方式作为替代入口

修复

• Mermaid 引号注入 — 文件/函数名包含 " 不再破坏 .mmd 图表渲染
• O(N×E) 被调用者解析 — _resolve_callee() 使用预建后缀索引实现 O(1) 查找
• 模块索引冲突 — 不同目录下同名文件不再导致节点静默丢失
• Focus 子串误匹配 — --focus auth.py 不再匹配 oauth.py
• BFS O(N²) Pop — 所有 BFS 位置改用 deque.popleft() 替代 list.pop(0)
• 非原子写入 — pactkit.yaml、.mmd 文件和 atomic_write() 均使用 tmp+rename 模式
• Deployer 编码 — 3 处裸 read_text() 调用指定 encoding='utf-8'
• 大文件 OOM — MAX_FILE_BYTES=1MB 防护避免自动生成的超大文件导致 OOM
• Sprint 冗余操作 — 消除重复的 visualize/clean/context 运行

2.4.1 — 2026-03-26

修复

• CI 模板覆盖 — pactkit update 不再覆盖 pactkit.yaml 中自定义的 ci.install_cmd
• Board ID 验证 — 现支持开发者前缀 ID（HOTFIX-slim-052、STORY-alice-001）

新增

• Board move_story 命令 — 通过 CLI 在看板分区间移动 Story
• PyPI 自动发布 — Tag 触发 CI 通过可信发布者（OIDC）自动发布到 PyPI

变更

• 闭源迁移 — 源码仓库转为私有；公共入口移至 pactkit-public

2.4.0 — 2026-03-25

新增

• 多架构拓扑分析 — pactkit visualize 现在理解代码结构之外的 3 种项目拓扑：
  • PDCA 拓扑 — 工作流图中的 Plan→Act→Check→Done 序列边
  • 服务拓扑 — 解析 docker-compose.yml、openapi.yaml、*.proto 生成服务依赖图
  • 前端拓扑 — 解析 Next.js（App/Pages Router）、Vue Router 生成 page→component→hook→store 链
  • 跨拓扑影响 — 回归分析横跨所有拓扑类型
  • 统一分层图 — 将代码 + 拓扑维度合并为一张可视化图

修复

• 拓扑自动检测可靠性提升
• CI 多语言测试覆盖的依赖配置
• Spec/PRD 交叉引用一致性（4 处问题）

2.3.0 — 2026-03-22

新增

• 25 个确定性 CLI 子命令 — 核心操作现在以 Python 代码运行，而非 prompt：clean、regression、context、lint、test-map、coverage-gate、doctor、spec-lint、spec-status 等
• 覆盖率门禁 — pactkit coverage-gate 执行三级阈值（≥80% 通过、50-79% 警告、<50% 阻止）
• 自动版本同步 — pactkit update --if-needed 版本匹配时跳过重部署
• E2E 测试框架 — pactkit.yaml 中的配置驱动 E2E 策略
• Spec Linter 增强 — W007 需求-AC 覆盖检查、W008 占位符检测、E007 按子节验证

修复

• Plan 阶段大型 Spec 生成卡顿（拆分为子步骤）
• Explore 子代理无界搜索（有界委托模式）
• 25+ 处 CLI 与 prompt 交叉引用完整性缺口

2.2.0 — 2026-03-20

新增

• 上下文感知规则加载 — 每个命令只加载所需规则，token 使用量减少 20-83%
• 栈感知 CI 流水线 — 支持 Python、Node.js、Go、Java，配置正确的 setup 和测试运行器
• GitHub Enterprise (GHE) 支持 — ci.github_host 和 ci.actions_ref 配置

2.1.0 — 2026-03-17

新增

• 多格式部署 — 新增 AI 工具格式只需一个注册表条目，所有下游代码自动适配
• 模板变量 — 48 个硬编码路径替换为部署时解析的命名占位符
• 文档 Schema 注册表 — pactkit schema [type] CLI 查看文档结构规则
• 懒加载规则 — 每轮系统 prompt 开销减少 62%

修复

• /project-init 环境检测改进
• 配置合并时保留用户条目（不再覆盖）

---

早期版本

• 1.5.0 — PDCA 质量门禁、基于影响的回归、Done/Release/PR 命令拆分、社区标准
• 1.4.0 — Spec Linter（14 条规则）、主动澄清门禁、Act 前一致性检查、自动 PR
• 1.3.0 — CI/CD 流水线生成、Issue 追踪集成、Hook 模板、Doctor 诊断
• 1.0.0 — 首次公开发布。9 个 Agent、13 个命令、3 个 Skill、6 条宪章规则