@namewta/speculo 1.0.2 → 1.0.4

package/template/commands/references/git-repository-audit-procedure.md

@@ -0,0 +1,608 @@
+# Git 审计完整采集与报告协议
+
+仅在 git-repository-audit 被选择且准备采集/计算/形成报告时完整读取；这不是新的 command。
+
+## 输入选择
+
+从用户自然语言解析：
+
+```yaml
+start_time: "YYYY-MM-DD HH:mm:ss"
+end_time: "YYYY-MM-DD HH:mm:ss"
+timezone: "Asia/Shanghai"
+
+repositories:
+  mode: all                 # all | selected
+  include: []               # project_root 相对路径
+  exclude: []
+
+branches:
+  mode: default             # default | selected | all-local | all-refs
+  include: []
+  primary_branch: ""
+
+authors:
+  mode: all                 # all | selected
+  include: []               # 作者名字
+  exclude: []
+  exclude_bots: true
+
+paths:
+  include: []
+  exclude:
+    - ".git/**"
+    - "<Path>{roots.state}/**</Path>"
+    - ".venv/**"
+    - "node_modules/**"
+    - "vendor/**"
+    - "dist/**"
+    - "build/**"
+    - "coverage/**"
+    - "*.min.js"
+    - "*.map"
+    - "*.lock"
+
+options:
+  include_merge_commits: true
+  include_commit_body: true
+  include_raw_commit_appendix: true
+  weekly_breakdown: true
+  monthly_breakdown: true
+  top_n: 20
+  topic: git-audit
+```
+
+默认与阻塞规则：
+
+1. 时区缺失时使用 `Asia/Shanghai`。
+2. 仓库缺失时选择全部发现仓库。
+3. refs 缺失时选择每个仓库主分支的可达历史。
+4. 作者缺失时选择全部作者名字并排除可识别机器人。
+5. 开始或结束时间缺失时：
+   - 只完成仓库发现；
+   - 展示各仓库最早、最新提交；
+   - 一次性询问缺失时间；
+   - 时间确认前不采集完整历史、不创建正式报告。
+6. 纯日期的开始边界为 `00:00:00`，结束边界为 `23:59:59`，两端包含。
+7. 指定仓库、ref 或作者名字未命中时停止并列出未命中项，不静默忽略。
+
+## 作者身份
+
+作者身份只使用 Git Author Name，即 `%an`。
+
+身份键为“Unicode NFC 后去除首尾空白的作者名字”。
+
+- 不读取、展示或使用邮箱；
+- 不使用 `.mailmap`；
+- 不调用 `git check-mailmap`；
+- 同名合并为同一作者；
+- 不同名字视为不同作者；
+- 保持大小写，不猜测别名。
+
+机器人只按名字识别，如 `[bot]`、`dependabot`、`renovate`、`github-actions`、`automation` 或明显的 `bot` 名称。
+
+报告必须注明：同名可能误合并，同一人的不同名字可能被拆分。
+
+## 执行
+
+### 1. 解析 Speculo 工作区
+
+1. 从当前目录向上寻找 `<Path>{roots.state}/workspace.json</Path>`。
+2. 第一个命中的目录为 `project_root`；多个候选或用户目录不一致时停止消歧。
+3. 验证 `workspace.json`：
+   - 非空且是有效 JSON；
+   - `path_base` 为 `project-root`；
+   - roots 是 POSIX 项目相对路径。
+4. 读取 `<Path>{roots.config}</Path>`。
+5. 任一初始化文件缺失、为空或不可解析时，停止并提示运行：
+
+```bash
+speculo init
+```
+
+完成标准：`project_root`、`roots.state` 和最终报告目录只有一个解析结果。
+
+### 2. 检查工具
+
+执行并记录：
+
+```bash
+git --version
+uv --version
+uv run --no-project python -V
+```
+
+报告声明：
+
+- 仅分析本地历史；
+- 未执行 fetch；
+- Git、uv、Python 版本；
+- 生成时间和时区。
+
+完成标准：Git 与 uv 可用，Python 由 uv 成功启动。
+
+### 3. 发现仓库
+
+用标准库脚本扫描 `project_root`，识别：
+
+- 根目录仓库；
+- `.git/` 目录；
+- worktree/submodule 的 `.git` 文件；
+- 嵌套仓库。
+
+遍历时默认剪枝：
+
+```text
+.git
+<Path>{roots.state}</Path>
+.venv
+node_modules
+vendor
+dist
+build
+coverage
+```
+
+对候选执行：
+
+```bash
+git -C "<candidate>" rev-parse --is-inside-work-tree
+git -C "<candidate>" rev-parse --show-toplevel
+git -C "<candidate>" rev-parse --is-bare-repository
+```
+
+按真实仓库根路径去重。每个仓库记录：
+
+- 名称和项目相对路径；
+- bare/worktree/submodule 信号；
+- 当前分支和主分支；
+- 本地分支、远端跟踪分支、标签数量；
+- 最早和最新提交；
+- `git status --short` 摘要；
+- remote 名称与脱敏地址；
+- 分析开始时 HEAD；
+- 选中 refs 的 tip 哈希。
+
+主分支按以下顺序识别：
+
+1. 用户指定；
+2. `refs/remotes/origin/HEAD`；
+3. `main`；
+4. `master`；
+5. `develop`；
+6. 当前分支；
+7. 最近提交最新的本地分支。
+
+无法可靠确定时阻塞该仓库，不猜测。
+
+完成标准：仓库列表去重，每个仓库有明确成功/失败状态和项目相对路径。
+
+### 4. 确定 revision scope
+
+- `default`：主分支可达历史；
+- `selected`：用户指定 refs；
+- `all-local`：全部本地分支；
+- `all-refs`：本地与远端跟踪 refs。
+
+多个 refs 含同一 commit 时，按“仓库 + 完整哈希”去重。
+
+默认使用 Committer Date 过滤和统计，同时保留 Author Date 用于异常分析。
+
+完成标准：每个纳入仓库都有明确 refs、tip 快照、时间范围和时区。
+
+### 5. 采集 Git 原始数据
+
+Commit 元数据：
+
+- 完整/短哈希；
+- 父提交与父数量；
+- Author Name；
+- Author Date；
+- Committer Date；
+- subject、body、refs；
+- merge、revert、机器人标记；
+- 是否位于主分支 first-parent。
+
+使用记录分隔符和字段分隔符解析 `git log`，不得解析终端对齐表格。
+
+文件变化：
+
+```bash
+git -C "<repo>" show --numstat --format= <commit>
+git -C "<repo>" show --name-status --find-renames --format= <commit>
+```
+
+记录：
+
+- changed files；
+- additions、deletions；
+- binary；
+- A/M/D/R/C/T；
+- rename/copy；
+- 一级/二级目录；
+- 扩展名和语言；
+- 业务代码、测试、文档、配置、CI、迁移、依赖、generated/vendor。
+
+Merge commit 只统计合并事件；普通 churn 默认只汇总非 merge commit。需要 merge diff 时使用 first-parent 并单独标注。
+
+路径排除只影响 LOC、热点和模块统计，不删除 commit。全部文件被排除的 commit 仍保留，`effective_churn` 为 0。
+
+完成标准：每个指标可回溯到 commit；binary、rename 和排除路径口径明确。
+
+### 6. 分类与主题聚合
+
+一级分类：
+
+```text
+feature
+bugfix
+refactor
+test
+docs
+build-ci
+performance
+security
+chore
+revert
+merge
+unknown
+```
+
+分类依据：
+
+1. Conventional Commits；
+2. subject/body；
+3. issue、PR、需求编号；
+4. 文件与模块；
+5. diff 规模和文件类型；
+6. 测试、文档、配置伴随变化。
+
+置信度：
+
+- `high`：message、路径、变化一致；
+- `medium`：message 明确，文件证据有限；
+- `low`：主要依赖推断；
+- `unknown`：证据不足。
+
+按编号、相似 message、模块、时间、依赖、follow-up fix 和 revert 链聚合功能/技术主题。每个主题记录：
+
+- 可观察目标；
+- 起止时间；
+- commit 数和关键哈希；
+- 主要作者名字；
+- 仓库/模块；
+- additions、deletions、churn；
+- 测试伴随；
+- 后续 fix/revert；
+- 置信度。
+
+证据不足时使用“疑似”或“待人工确认”，不杜撰业务背景。
+
+完成标准：分类总数闭合；主要 feature/bugfix 已归入主题或未聚类清单。
+
+### 7. 计算分析指标
+
+基础指标：
+
+```text
+total_commits
+non_merge_commits
+merge_commits
+first_parent_merges
+revert_commits
+feature/bugfix/refactor/test/docs/build_ci/performance/security/chore/unknown
+active_authors
+active_days
+changed_files
+additions
+deletions
+net_change
+churn
+binary_changes
+added/deleted/renamed_files
+```
+
+定义：
+
+```text
+net_change = additions - deletions
+churn = additions + deletions
+active_day = 至少一个纳入统计的非 merge commit 的自然日
+```
+
+提交强度：
+
+```text
+commit_density = non_merge_commits / active_days
+weekly_commit_rate = non_merge_commits / period_weeks
+churn_per_active_day = churn / active_days
+files_per_commit = changed_files / non_merge_commits
+churn_per_commit = churn / non_merge_commits
+```
+
+按全局、仓库、周、月、作者和模块计算，并分析：
+
+- 月/周趋势；
+- 星期和小时分布；
+- 工作日、周末、非标准时段占比；
+- 连续活跃和最长静默；
+- 高峰日/周；
+- 中位数、四分位数、P95；
+- 周期末集中提交；
+- 超大或跨模块 commit；
+- Author/Committer Date 差异。
+
+不得把提交时间解释为工时或勤奋度。
+
+功能迭代强度优先展示：
+
+- 每周 feature commit/churn；
+- feature 活跃天数和模块数；
+- 测试伴随率；
+- 后续 bugfix/revert 比例。
+
+有足够比较样本时可附加：
+
+```text
+FII =
+  30% × normalized(feature_commits_per_active_week)
++ 25% × normalized(feature_churn_per_active_week)
++ 20% × normalized(feature_modules_touched)
++ 15% × normalized(feature_active_day_ratio)
++ 10% × normalized(feature_test_companion_rate)
+```
+
+必须同时显示原始值、标准化范围和权重；样本不足时不计算。
+
+质量与风险信号：
+
+- bugfix 占比与高频修复模块；
+- feature 后快速 fix、连续 fix、revert 后重做；
+- 测试伴随缺口；
+- generated/vendor/lockfile 噪声；
+- 高频热点和高 churn；
+- Top1/Top2 作者 commit、churn 集中度；
+- message 模糊和 unknown 比例。
+
+这些只能作为 Git 证据信号，不得称为真实缺陷密度、实际 bus factor 或绩效事实。
+
+完成标准：所有百分比同时给分子/分母，排名注明口径，表格合计一致。
+
+### 8. 团队与个人评估
+
+团队结论统一使用：
+
+```text
+事实 → 解释 → 风险或价值 → 建议
+```
+
+每个优点、不足和风险至少引用一个数据、项目相对路径或 commit 短哈希。建议分：
+
+```text
+P0：立即复核
+P1：下一迭代改进
+P2：持续优化
+```
+
+每位作者按统一结构输出：
+
+- commit、merge、活跃天；
+- additions、deletions、churn、changed files；
+- 仓库和模块覆盖；
+- feature/bugfix/refactor/test/docs/build-ci/performance/security；
+- 测试伴随率；
+- 平均、中位、最大 commit；
+- 主要主题、模块和代表性 commit；
+- Git 可见的贡献重心；
+- 优势信号、风险和改进点；
+- 证据与限制。
+
+可使用“功能交付型、缺陷治理型、架构重构型、测试保障型、工程效率型、文档规范型、多模块支持型、核心模块深耕型”描述 Git 可见重心。
+
+禁止只按 commit/LOC 给出最好或最差排名，禁止推断职位、态度、能力或绩效。
+
+完成标准：每位纳入范围的非机器人作者都有多维画像和限制声明。
+
+### 9. 交叉校验
+
+写报告前验证：
+
+- 全局 commit 与仓库去重合计一致；
+- 非 merge 分类之和等于非 merge commit；
+- merge 未重复进入普通 churn；
+- 作者合计闭合；
+- 多 refs 已去重；
+- 时间边界和时区一致；
+- binary 未作为普通 LOC；
+- 排除路径一致应用；
+- 仓库、周、月、作者和分类表合计一致；
+- 关键哈希在对应仓库存在；
+- 最终报告路径未占用。
+
+无法修复的差异使报告 `status: partial`，并记录具体差异，禁止伪造平衡数字。
+
+完成标准：校验结果进入报告正文和 frontmatter。
+
+### 10. 原子持久化
+
+1. 在内存生成完整 Markdown。
+2. 在 command 专属目录创建同文件系统临时文件。
+3. 写入并 flush；可用时 fsync。
+4. 原子 rename 到最终未占用路径。
+5. 重新读取验证：
+   - frontmatter 完整；
+   - command、scope 与文件名一致；
+   - 仓库选择和 Git 快照完整；
+   - 必需章节存在；
+   - 文件非空；
+   - 无绝对路径、邮箱或未脱敏凭证。
+6. 清理临时脚本和数据。
+7. 不执行 `git add` 或 commit。
+
+完成标准：只有一个正式报告持久化，已有报告未覆盖，临时数据已清理。
+
+## 报告 frontmatter
+
+```yaml
+---
+command: git-repository-audit
+schema_version: 1
+status: complete
+scope: workspace
+topic: git-audit
+generated_at: "ISO-8601"
+project_root: "."
+timezone: "Asia/Shanghai"
+time_range:
+  start: "ISO-8601"
+  end: "ISO-8601"
+date_basis: committer-date
+author_identity: author-name-only
+exclude_bots: true
+repository_mode: all
+repositories:
+  - path: "."
+    primary_branch: main
+    refs: [main]
+    head_at_start: "<full-sha>"
+path_includes: []
+path_excludes: []
+include_merge_commits: true
+local_history_only: true
+fetch_performed: false
+tool_versions:
+  git: ""
+  uv: ""
+  python: ""
+validation:
+  status: passed
+  warnings: []
+---
+```
+
+- `status` 为 `complete` 或 `partial`。
+- `scope` 必须与文件名一致。
+- `repositories` 保存完整选择、refs 和 HEAD 快照。
+- 部分仓库失败时使用 `partial` 并列明。
+- 不记录邮箱。
+
+## 报告结构
+
+```markdown
+# Git 仓库代码迭代与团队贡献盘点报告
+
+## 0. 执行摘要
+## 1. 分析范围与统计口径
+## 2. 仓库发现与 Git 快照
+## 3. 全局核心指标
+## 4. 仓库间对比
+## 5. 提交时间与提交强度
+## 6. 合并与分支活动
+## 7. 功能迭代主题
+## 8. Bug 修复与质量活动
+## 9. 代码增减与变更结构
+## 10. 热点模块与知识集中
+## 11. 团队优点、不足与风险
+## 12. 个人贡献画像
+## 13. 优先行动项
+## 14. 数据质量、限制与复核
+## 15. 原始数据附录
+```
+
+执行摘要在一页内包含范围、仓库数、commit、merge、feature、bugfix、作者数、additions、deletions、churn、3 至 5 条关键发现、3 至 5 条建议和主要限制。
+
+核心表格：
+
+```markdown
+| 仓库 | 项目相对路径 | 主分支 | refs | 本地分支 | 远端分支 | 标签 | 最早提交 | 最新提交 | 工作区状态 |
+|---|---|---|---|---:|---:|---:|---|---|---|
+
+| 主题 | 时间 | commits | 主要作者 | 仓库/模块 | +行 | -行 | 测试伴随 | 后续修复 | 关键哈希 | 置信度 |
+|---|---|---:|---|---|---:|---:|---|---|---|---|
+
+| 作者 | commits | 活跃天 | feature | bugfix | test | refactor | 工程类 | churn | 主要模块 | 主要主题 |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---|---|
+
+| 优先级 | 发现 | 数据证据 | 影响 | 建议行动 | 建议负责人 |
+|---|---|---|---|---|---|
+```
+
+无法从 Git 判断负责人时写“团队共同确认”。
+
+## 原始数据附录
+
+默认在同一报告中保留全部所选 commit，不静默截断。每条至少包含：
+
+```markdown
+| 仓库 | 哈希 | Committer Date | 作者名字 | 类型 | 置信度 | Subject | 文件数 | +行 | -行 | 主要模块 | 主题 |
+|---|---|---|---|---|---|---|---:|---:|---:|---|---|
+```
+
+同时包含：
+
+- 仓库、周、月和作者原始汇总；
+- merge 事件；
+- 功能主题与 commit 对照；
+- 待人工确认 commit；
+- 排除文件和 binary 影响摘要。
+
+commit 很多时按仓库和月份拆表，可用 `<details>` 折叠，但仍保留每个 commit，不生成第二个持久化数据文件。
+
+## 数据限制
+
+报告必须明确：
+
+- 仅本地可见历史，未 fetch；
+- 删除分支名称通常不可恢复；
+- merge commit 数不等于历史分支数；
+- squash/rebase 可能隐藏合并和多人贡献；
+- 作者只按名字归一化；
+- Git 无法完整反映设计、Review、沟通、带教、pair programming 和未提交工作；
+- LOC 会受格式化、生成文件、lockfile 和文件移动影响；
+- 测试文件未变化不等于没有测试；
+- bugfix 占比不等于真实缺陷密度；
+- 报告不能直接替代绩效评估。
+
+## 复核命令
+
+报告末尾按实际范围填充只读命令：
+
+```bash
+git -C "<repo>" log "<ref>" --since="<start>" --until="<end>" --format="%H" | sort -u | wc -l
+git -C "<repo>" log "<ref>" --merges --first-parent --since="<start>" --until="<end>" --format="%H"
+git -C "<repo>" log "<ref>" --no-merges --since="<start>" --until="<end>" --numstat
+git -C "<repo>" shortlog -sn "<ref>" --since="<start>" --until="<end>"
+```
+
+作者复核不使用 `-e`，不输出邮箱。
+
+## 返回
+
+完成后只返回：
+
+1. 报告项目相对路径；
+2. 分析范围摘要；
+3. 3 至 5 条最重要发现；
+4. `complete` 或 `partial`；
+5. 待人工复核事项。
+
+完整报告不再次复制到对话；报告文件是唯一事实源。
+
+## 完成标准
+
+- Speculo 工作区和 state 根唯一解析；
+- Python 仅通过 `uv run --no-project python -` 执行；
+- 范围内仓库发现并去重；
+- 时间、时区、仓库、refs、作者、路径范围明确；
+- 作者只按名字区分，未读取或输出邮箱；
+- commit 按仓库和完整哈希去重；
+- merge 与普通 churn 分开；
+- 功能、bugfix、时间、强度、代码量、热点、团队和个人分析完整；
+- 所有评价有数据、路径或 commit 证据；
+- 报告 frontmatter 保存完整选择和 Git 快照；
+- 报告位于 command 专属规范路径且 scope 可见；
+- 已有报告未覆盖；
+- 未创建 state、sidecar 或第二份正式数据；
+- 临时数据已清理；
+- 未修改 Git 仓库、项目文件或 Python 项目环境；
+- 最终报告已重读并通过结构和敏感信息检查。

package/template/skills/archive-and-consolidate/SKILL.md

@@ -18,4 +18,4 @@ This file is the routing entry. Read [`references/entry-procedure.md`](reference
 
 ## Stop
 
-Stop before side effects when the required input, owner, reference, confirmation, schema, or recovery evidence is missing; report the exact blocker and preserve any dry-run evidence.
+Stop before side effects when the required input, owner, reference, confirmation, schema, or recovery evidence is missing, or when `commands_root` is not `{roots.state}/commands`; report the exact blocker and preserve any dry-run evidence.

package/template/skills/archive-and-consolidate/references/entry-procedure.md

@@ -37,7 +37,14 @@
    - 识别操作型路径：`status.json`、`changes/`、`archive/`。
    - 识别知识型 store：`adr/`、`context/` 及任何标注为"永久"的目录（其内容在 change 完成后提升至此）。
    - 每个路径解析为完整的项目相对路径。
-5. 派生固定路径：`changes_root = state_root/changes`、`archive_root = state_root/archive`；`commands_root` 从公共 `<Path>{roots.state}/commands</Path>` 解析，不放进 workflow 私有 state root。
+5. 派生固定路径：
+   - `changes_root = state_root/changes`
+   - `archive_root = state_root/archive`
+   - `commands_root` 必须解析为 `<Path>{roots.state}/commands</Path>`
+   - `{roots.commands}` 是命令定义根，记为 `commands_def_root`，不是报告根
+   - 「不放进 workflow 私有 state root」只禁止写入 `<Path>{roots.state}/{workflow}/</Path>`（含 `specdev` / `learning` / `ops` / `person`）。它不禁止写入 `{roots.state}` 本身，更不得把报告退回 `{roots.commands}`
+   - POSIX 规范化后，若 `commands_root` 等于 `{roots.commands}`，或任何报告路径落在 `{roots.commands}/archive-and-consolidate/` → **blocked，不写文件**
+   - 写入 `path_context` 前再次核对 `commands_root` 等于 `<Path>{roots.state}/commands</Path>`
 6. 读取 `<Path>{roots.config}</Path>`（若存在）；不存在时静默降级为默认值（`language: "en"`、`confirm_before_external_write: true`）。
 7. 对每个已解析路径执行真实路径包含检查；符号链接逃逸或不存在的静态引用阻塞。
 8. 读取 `status.json`；扫描 changes 时校验 change 名称格式 `^\d{4}-\d{2}-\d{2}-[a-z0-9]+(-[a-z0-9]+)*$`，无日期前缀的历史 change 标注遗留但不阻塞。
@@ -110,7 +117,7 @@
 3. 显式标注所有破坏性动作（移动、删除、改写）。
 4. 报告摘要：待归档 change 数、待合并知识项数、待清理候选数、需确认项数。
 5. 呈现给用户并显式声明：**"未修改任何文件。此为 dry-run 计划，请确认后执行。"**
-6. dry-run 到此完成；调用方负责将报告写入 `commands_root/archive-and-consolidate/<YYYY-MM-DD>-<scope>-<topic>[-NN].md`（`<scope>` 为目标 workflow 名，`<topic>` 为 change 名或 `batch`）。
+6. dry-run 到此完成；调用方负责将报告写入 `<Path>{roots.state}/commands/archive-and-consolidate/{date}-{scope}-{topic}[-NN].md</Path>`（`<scope>` 为目标 workflow 名，`<topic>` 为 change 名或 `batch`）。禁止写入 `{roots.commands}/archive-and-consolidate/`。
 
 ### Step 7：执行已确认动作
 
@@ -140,7 +147,7 @@
   mode: "dry-run" | "executed",
   scope: "archive-single" | "archive-batch",
   knowledge_policy: "generic" | "mechanical-only",
-  path_context: { project_root, workflow_root, state_root, changes_root, archive_root, commands_root },
+  path_context: { project_root, workflow_root, state_root, changes_root, archive_root, commands_root }, // commands_root === {roots.state}/commands, never {roots.commands}
   knowledge_stores: [{ name, path, exists }],
   archive_plan: [{ source, target, status: "ready" | "blocked" | "moved" | "failed", notes }],
   consolidation_plan: [{ source_change, target_store, action: "create" | "merge" | "append", content_summary, graduation_criterion, status }],
@@ -157,6 +164,7 @@
 - `generic` 的每次合并写入已解决或标记冲突，目标 store 在 state 根内；每个清理动作完成路径包含验证且无跨 workflow 修改。
 - 未确认或 mode=`dry-run` 时无文件系统修改。
 - 执行后重读验证通过或不一致已记录。
+- `path_context.commands_root` 等于 `<Path>{roots.state}/commands</Path>`，不等于 `{roots.commands}`。
 - 本 skill 未自行选择报告路径或自行持久化。
 
 ## 渐进披露

package/template/skills/git-history-squash/SKILL.md

@@ -13,6 +13,8 @@ This file is the routing entry. Read [`references/entry-procedure.md`](reference
 ## Scope
 
 - Trigger: Plan and execute a confirmed first-parent Git history squash with recoverable refs and exact remote leases; never auto-trigger.
+- Owning command: `<Path>{roots.commands}/git-history-squash.md</Path>` owns confirmation and the command audit report.
+- This skill owns `<Path>{roots.state}/skills/git-history-squash/</Path>` transactional state.
 - Output and write owner remain those declared by the entry procedure and the owning command/workflow.
 - Do not infer missing scope, credentials, target, or authorization.
 

package/template/skills/git-history-squash/references/entry-procedure.md

@@ -8,7 +8,7 @@
 
 1. 从当前目录向上寻找并读取 `<Path>{roots.state}/workspace.json</Path>`，验证 `path_base: project-root` 和全部 roots，再读取 `<Path>{roots.config}</Path>`；无法唯一确定项目根时停止。
 2. 读取项目 `AGENTS.md` 及目标仓库作用域内规则。
-3. 将本 Skill 的持久化根解析为 `<Path>{roots.state}/skills/git-history-squash/</Path>`。根 `state.json` 只保存当前可恢复运行的 locator；每次运行使用 `<Path>{roots.state}/skills/git-history-squash/{date}-{topic}[-NN]/</Path>`，已有目录永不覆盖。
+3. 将本 Skill 的持久化根解析为 `<Path>{roots.state}/skills/git-history-squash/</Path>`。根 `state.json` 只保存当前可恢复运行的 locator；每次运行使用 `<Path>{roots.state}/skills/git-history-squash/{date}-{topic}[-NN]/</Path>`，已有目录永不覆盖。由 `<Path>{roots.commands}/git-history-squash.md</Path>` 调用时，command 负责确认门和 `<Path>{roots.state}/commands/git-history-squash/</Path>` 审计报告；本 Skill 仍只写上述 skill namespace。
 4. 从 [request template](../assets/request-template.json) 生成临时 request JSON。用户必须逐仓库明确 repository、完整 local branch ref、start、end、`inclusive | exclusive`、commit message、签名选择和远端发布选择；不得猜测缺失值。
 5. 读取 [Rewrite contract](rewrite-contract.md)，用它验证区间语义、预检项、确认门和 Git 写入边界。涉及父仓库与 submodule 时同时读取 [Submodule contract](submodule-contract.md)。
 

package/template/skills/writing-great-skills/SKILL.md

@@ -16,6 +16,8 @@ This file is the routing entry. Read [`references/entry-procedure.md`](reference
 - Output and write owner remain those declared by the entry procedure and the owning command/workflow.
 - Do not infer missing scope, credentials, target, or authorization.
 
+For an authorized review or rewrite of a skill/document, read [`references/document-contract.md`](references/document-contract.md) before editing. Its fidelity checks apply to any document; this does not change this skill’s explicit-only activation policy.
+
 ## Stop
 
 Stop before side effects when the required input, owner, reference, confirmation, schema, or recovery evidence is missing; report the exact blocker and preserve any dry-run evidence.