@namewta/speculo 1.0.24 → 2.0.1

package/template/commands/git-repository-audit/COMMAND.md

@@ -0,0 +1,80 @@
+---
+id: git-repository-audit
+description: Produce a read-only reproducible audit for explicitly selected local Git repositories.
+---
+
+# Git Repository Audit 命令
+
+## 意图与边界
+
+执行一次性、只读、可复现的 Git 仓库盘点：
+
+- 发现 `project_root` 下的 Git 仓库；
+- 按用户选择的时间、仓库、refs、作者名字和路径范围采集本地 Git 历史；
+- 分析 commit、merge、功能迭代、bug 修复、提交节奏、代码增减、热点模块、团队协作和个人贡献；
+- 将完整选择、Git 快照、原始指标、关键证据、结论和复核命令写入唯一 Markdown 报告。
+
+本命令是单次短编排，不维护 workflow 状态机，不调用外部 API，不补抓远端数据。
+
+## 持久化契约
+
+唯一持久化产物：
+
+```text
+<Path>{roots.state}/commands/git-repository-audit/{date}-{scope}-{topic}[-NN].md</Path>
+```
+
+实际路径必须通过 `<Path>{roots.state}/workspace.json</Path>` 的 `roots.state` 解析：
+
+```text
+<Path>{roots.state}/commands/git-repository-audit/{date}-{scope}-{topic}[-NN].md</Path>
+```
+
+规则：
+
+- `<scope>`：
+  - `workspace`：全部发现仓库；
+  - `multi-repo`：多个但非全部仓库；
+  - `repo-<slug>`：单个仓库。
+- `<topic>`：用户主题转小写 kebab-case；缺失时为 `git-audit`。
+- 同日同 scope/topic 冲突时，从 `-01` 开始选择最小未占用编号。
+- 禁止覆盖已有报告。
+- 禁止把正式报告写入 `temp/`、系统临时目录或其他位置。
+- 本命令不创建 `state.json`、sidecar、CSV、JSON、数据库或长期缓存。
+- 临时数据只存在于内存或 `tempfile.TemporaryDirectory()`，结束时清理。
+- 报告内所有路径使用 POSIX 项目根相对路径；不持久化绝对路径。
+
+## 写操作边界
+
+只允许创建 command 专属目录并原子写入、重读本次报告。
+
+不得修改仓库、工作区、索引、refs、远端或 Python 项目环境。不得执行：
+
+```text
+git add/commit/checkout/switch/reset/restore/clean/merge/rebase/cherry-pick/revert
+git branch -d/-D
+git tag/stash/fetch/pull/push/gc
+uv sync/add/lock
+```
+
+不得修改项目源码、测试、文档、Git 配置、`.git/`、`pyproject.toml`、`uv.lock` 或项目内 `.venv`。
+
+## Python 运行契约
+
+所有 Python 采集和计算统一使用：
+
+```bash
+uv run --no-project python -
+```
+
+- 脚本从标准输入传入；
+- 仅使用 Python 标准库；
+- 不直接调用 `python`、`python3`、`pip` 或 `poetry`；
+- 不创建项目内虚拟环境；
+- `uv` 不可用时停止，不切换管理方式。
+
+## 按需执行
+
+本命令选中后，采集或生成报告前必须读取 `<Path>{roots.commands}/git-repository-audit/references/procedure.md</Path>`，按其输入选择、身份处理、固定点采集、计算、交叉校验、报告结构和原子持久化顺序执行。用户未明确的范围按原选择协议确认；不得先扩大分析范围。
+
+默认运行工具仍是 `uv run --no-project python -`；不可用即停止，不静默切换。仍只交付一个完整 Markdown 报告，包含原始指标、证据、限制和复核命令；不另建 CSV/JSON/sidecar。采集不可复现、交叉校验失败、来源不可读或报告路径冲突时停止受影响报告，不猜测数据、不覆盖已有结果。完成后回读报告，再按参考的返回合同交付。

package/template/commands/handoff/COMMAND.md

@@ -0,0 +1,61 @@
+---
+id: handoff
+description: Persist a compact handoff when the user asks another agent or session to continue the current work.
+---
+
+编写一份交接文档，总结当前对话，使新的 agent 可以继续此工作。
+
+## 归档路径
+
+报告文件必须写入以下规范路径：
+
+```
+<Path>{roots.state}/commands/handoff/{date}-{scope}-{topic}[-NN].md</Path>
+```
+
+- **<YYYY-MM-DD>** — 使用当前日期。
+- **<scope>** — 工作区、工作流或变更的 scope 标识，使用小写 kebab-case。
+- **<topic>** — 从交接范围或用户主题提取，使用小写 kebab-case；无法判断时使用 `speculo`。
+- **[-NN]** — 同日同 scope 同 topic 的多份报告，从 `-01` 开始递增；仅首份可省略后缀。
+
+- 禁止将命令报告写入 `temp/`、系统临时目录或工作区内其他非规范位置。
+
+## 内容要求
+
+在文档中包含一个"建议 skills"部分，列出建议 agent 调用的 skills。
+
+不要重复已被其他产物（规范、方案、ADR、issue、commit、diff）覆盖的内容，改用路径或 URL 引用它们。
+
+清除任何敏感信息，如 API 密钥、密码或个人身份信息。
+
+如果用户传入了参数，将其视为对下一个会话重点内容的描述，并据此定制文档。
+
+交接范围包含 SpecDev change 时，引用 README 的唯一 Outcome、接续点和当前 owning 工件，并按实际存在情况链接 `source.md`、`triage.md`、`publish.md`（若请求过），不复制正文、不创建业务状态镜像。旧归档只读引用原件；混合状态或未结束转换交原 owner 恢复。若 `external_action` 为 `pending-close` 或 `close-failed`，必须记录准确远程 locator、已完成步骤、授权状态和恢复入口 `T-triage`；不得把待关闭误报为本地未完成。若 `publish_action` 为 `pending` 或 `publish-failed`，必须记录账本路径、失败行和下一步，恢复入口仍是 T-triage publish。交接范围包含尚未成 Change 的 inbox 记事项时，引用 `<Path>{roots.state}/specdev/capture.md</Path>`（若存在）的失败行与恢复入口 T-triage capture，不创建 change。
+
+## 最小恢复包
+
+先回读当前真实源，再在同一交接报告内记录下列字段；不存在的信息明确缺失，不复制整套 Spec、知识库或完整推理过程。
+
+| 内容 | 必须能够恢复的事实 |
+|---|---|
+| 目标与边界 | 用户要求的 Outcome、交付数量、已接受决定、范围与不可放宽约束 |
+| 当前检查点 | change/Ticket/Run ID、当前 owner、worktree/branch、实际 HEAD 或来源摘要、验证时间 |
+| 权威指针 | 当前 owning 工件、直接依赖、Evidence、已命中 Skill 的真实 ID/入口/摘要与触发阶段 |
+| 未闭合动作 | 操作 ID、真实授权来源与范围、已知/未知副作用、锁/事务及回执位置；没有则明确无 |
+| 下一安全动作 | 一个具体动作、输入、进入条件、验证方式、失败停止点与原恢复入口 |
+
+接收方先核对 roots、owner、HEAD、关键输入摘要与未闭合动作，再继续既有流程。正常恢复只读上述最小集合；漂移、冲突或 unknown 时按领域原合同扩读并停止受影响写集。交接文档中的“已批准”不是新授权，不能据其释放他人锁、重放迁移或重新发布。
+
+OPS 交接引用原 Controller/Host/Project、task/Run/Release、immutable plan/approval/journal/目标 receipt 和 progress；不写凭据值或复制私密配置。started-only、终态失败、docs_pending 分别回到原恢复协议，不能包装成新 task 再试。只向接收方传递已授权范围内必要的 locator 与脱敏证据。
+
+## 路径引用规范
+
+文档中所有文件/文件夹引用必须使用**项目根目录**的相对路径。
+
+- ✅ `src/modules/auth/`
+- ✅ `scripts/migrate/2024-add-index.sql`
+- ✅ `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
+- ❌ `../../specdev/changes/...` — 相对于 handoff 文件，脱离目录后不可定位
+- ❌ `auth` — 裸名，无法判断是目录/文件/子模块
+
+例外：skills 名称属于逻辑标识而非文件路径，不适用此规则。

package/template/commands/manifest.json

@@ -0,0 +1,15 @@
+{
+  "schema_version": 1,
+  "commands": [
+    "archive-and-consolidate/COMMAND.md",
+    "docs-sync/COMMAND.md",
+    "engineering-standards-builder/COMMAND.md",
+    "git-history-squash/COMMAND.md",
+    "git-repository-audit/COMMAND.md",
+    "handoff/COMMAND.md",
+    "retro/COMMAND.md",
+    "source-code-zip/COMMAND.md",
+    "status/COMMAND.md",
+    "upstream-fork-sync/COMMAND.md"
+  ]
+}

package/template/commands/retro/COMMAND.md

@@ -0,0 +1,72 @@
+---
+id: retro
+description: Analyze confirmed Speculo usage friction and propose or create GitHub issues through the T-triage remote operation protocol.
+---
+
+# Retro 命令
+
+**外部写操作 + 目标仓库写死。** 本命令最后一步会通过 `gh` 向 `NAMEWTA/Speculo` 创建 issue——不论在哪个项目仓库中激活，目标仓库一律不可覆盖。确认前可执行只读检索和 dry-run，远程写入为零。
+
+## 归档路径模式
+
+报告文件：`<Path>{roots.state}/commands/retro/{date}-{scope}-{topic}[-NN].md</Path>`
+
+- `<YYYY-MM-DD>` 使用当前日期。
+- `<topic>` 从复盘范围或用户主题提取，使用小写 kebab-case；无法判断时使用 `speculo`。
+- 禁止把命令报告写入 `temp/`、系统临时目录或工作区内其他非规范位置。
+
+## 调用的能力
+
+- `<Path>{roots.references}/retrospective/retrospective-contract.md</Path>` — 复盘 Speculo 使用痛点、深度分析并产出去重/分级/根因化的 issue-ready 提案时读取。
+- `<Path>{roots.workflows}/specdev/specdev-t-triage/references/remote-operations.md</Path>` — 以 `issue-search` 去重、以 `issue-create` dry-run/confirmed 创建 Issue；该能力不成为任何 workflow 的 tracker。
+
+若当前安装没有 SpecDev/T-triage，报告缺失依赖，继续本地复盘与提案；远程步骤待用户安装该 workflow 后恢复，不静默初始化。
+
+## 执行步骤
+
+1. 从调用方 workspace 或项目入口定位 `<Path>.agents/speculo/.speculo/workspace.json</Path>` 并解析 roots；缺失或冲突时只做当前会话分析，不猜测持久化目录。读取 `<Path>{roots.references}/retrospective/retrospective-contract.md</Path>`，按明确 scope 定位相关报告、change 与知识条目，不扩大为全量历史采集。
+2. 用该 skill 产出规范化复盘结论：去重、分级、根因化的 issue-ready 提案清单，附丢弃/合并说明与每条处置建议。
+3. 创建 command 专属目录 `<Path>{roots.state}/commands/retro/</Path>`，把复盘结论写入带 scope 的 Markdown 报告。
+4. **去重**：调用 `T-triage 远程操作协议` 的 `operation=issue-search`，对每条 `disposition: file-issue` 检索；命中语义重复的默认跳过并记录 `dup_of`，仅当用户明确要求才补提。
+5. 本命令把分析类型映射为 bug→bug、friction/ergonomics→enhancement、missing-capability→feature-request、doc-gap→documentation；优先级映射 priority:<level>，可选 area:<area>。先只读确认远程标签，缺失时列为待处理，不擅自创建。展示精确标题、标签、正文、目标 `NAMEWTA/Speculo` 与去重结果，取得或沿用覆盖这些内容的明确授权；否则只保留报告。
+6. 按优先级调用 issue-create --apply，每项保存稳定 marker=retro:<报告文件名>:<序号>、正文摘要与授权。正文包含该 HTML marker 和 AI 协助说明；请求超时先查原 marker，不制造第二条。任一失败停止后续创建，在本报告记录已建/未建与恢复条件。此操作不激活 T、不创建 change、不改变原任务归属。
+7. 把每条提案的最终 issue 编号/URL 回写进本次报告的「提交结果」小节；返回报告路径、3-5 条复盘摘要和已创建 issue 链接清单。
+
+## 产物模板
+
+> **服务命令：** `retro.md`
+> **产物文件名：** `<YYYY-MM-DD>-<scope>-<topic>[-NN].md`
+
+```markdown
+---
+command: retro
+mode: issue-retro
+scope: [TODO: workspace | multi-workflow | <workflow> | <workflow>-<change>]
+workflows: [TODO: workflow ids]
+changes: [TODO: full change names]
+generated_at: [TODO: ISO-8601]
+---
+
+# Speculo Retro Report
+
+## 复盘范围
+[TODO: 本次复盘覆盖的 command / workflow 与时间/会话范围。]
+
+## 信号来源
+[TODO: 列出采集到的证据出处：对话节点、`<Path>{roots.state}/...</Path>` 产物路径、SpecDev README 与当前 owning 工件、其他领域仍有效的状态字段、LESSONS。]
+
+## 改进提案
+[TODO: 按优先级倒序列出每条提案：标题 / 类型 / 优先级 / 根因 / remediation_axis / 建议改动 / 正反回归样本 / 验收标准 / 受影响资产 / 去重结论。]
+
+## 丢弃与降级项
+[TODO: 列出被合并、丢弃或降级为「仅记教训」的项及原因。]
+
+## 目标仓库
+`NAMEWTA/Speculo`
+
+## 用户确认记录
+[TODO: 记录用户对 issue 清单的确认原文摘要。]
+
+## 提交结果
+[TODO: 列出每条提案对应的 issue 编号/URL，或未提交原因（重复/失败/用户撤回）。]
+```

package/template/commands/source-code-zip/COMMAND.md

@@ -0,0 +1,58 @@
+---
+id: source-code-zip
+description: Create a requested source ZIP using the bundled Node script and its ignore rules; do not install dependencies.
+---
+
+# Source Code ZIP
+
+先确认 node 可用，只有 node 不存在时才回退 nodejs。使用 scripts/zip_source_code.js；无第三方依赖，不安装 npm/Python/zip 工具。
+
+## 标准工作流
+
+1. 确认用户提供的是目录路径，不是单个文件；路径含空格时必须加引号。
+2. 先确认 `node --version` 能正常执行。
+3. 默认先运行一次 `--dry-run`；目录较大、规则刚修改或可能包含敏感信息时，同时添加 `--verbose`。
+4. 检查预览结果，确认 `.env`、YAML、依赖目录、构建产物、归档文件和密钥没有被纳入。
+5. 正式创建 ZIP。
+6. 报告 ZIP 的绝对路径、纳入文件数、输入总大小和生成结果。
+7. 除非用户明确理解风险并提出要求，不得使用 `--no-default-ignore`。
+
+推荐预览：
+
+```bash
+node scripts/zip_source_code.js "/path/to/project" --dry-run
+```
+
+查看每个项目被排除的原因：
+
+```bash
+node scripts/zip_source_code.js "/path/to/project" \
+  --dry-run \
+  --verbose
+```
+
+正式创建：
+
+```bash
+node scripts/zip_source_code.js "/path/to/project"
+```
+
+默认输出在源目录旁边：
+
+```text
+<目录名>.code.zip
+```
+
+例如：
+
+```text
+源目录：/work/my-app
+输出：  /work/my-app.code.zip
+```
+
+
+需要自定义过滤、额外文件、输出位置、覆盖、压缩或排障时读取 [参数与行为参考](references/cli-reference.md)。执行前核对目标目录和忽略策略，交付 ZIP 路径、清单/统计及未打包项。
+
+## 调用报告
+
+需要持久化本次报告时使用 <Path>{roots.state}/commands/source-code-zip/{date}-{scope}-{topic}[-NN].md</Path>。复用当前授权和产物合同，不为只读调用自动创建状态；不覆盖历史报告。

package/template/commands/status/COMMAND.md

@@ -0,0 +1,14 @@
+---
+id: status
+description: Summarize installed workflows, active changes, anomalies, and next routes without activating a workflow.
+---
+
+# Status 命令
+
+1. 读取 `<Path>{roots.state}/workspace.json</Path>`，解析 `<Path>{roots.config}</Path>`（不存在时以默认值静默降级），获取全部已安装 workflow/state 根。
+2. 从 `<Path>{roots.workflows}/{workflow}/manifest.json</Path>` 与领域 `<Path>{roots.workflows}/{workflow}/SKILL.md</Path>` 核对已安装 workflow ids；仅用于发现，不激活 Work。
+3. SpecDev 使用上面的工件分支；其他 id 读取 `<Path>{roots.state}/{workflow}/status.json</Path>`，按该 workflow 自己的当前 schema 解释，不把 SpecDev 字段套到其他 workflow。Learning schema v2 的 active/archived entry 携带 stable `change_id`、kind、parent/root、current locator、current_work、Homework 和 retention projection；递归 Change 位于 `changes/**` 或 `archive/**`，位置历史读取 `<Path>{roots.state}/learning/locations.json</Path>`。SpecDev 改走目录发现和 README 唯一 Outcome：changes 直接子目录为当前对象，changes/archive 为新归档，旧 archive/YYYY-MM 仅历史只读；未初始化且没有对象是合法空结果；Ops schema v3 使用 hosts/projects/deployments/allocations/bindings/releases 资源表，运行记录在 hosts/{host_id}/runs/{run_id} 或 releases/{run_id}。其他 schema 列为异常，停止解释该分支并保留原件，不转换或兼容读取。不得按 change 名跨 workflow 合并；按 (project, workflow, change-name) 去重，同身份多位置列异常，不重复合计或静默覆盖。
+4. 按各域模型报告 active 数量；以下调用镜像仅用于原模型仍定义的领域，报告各 Change 的 `current_work`、去重后的 `works_run`、生命周期、parent/root、最近更新时间和停滞 Change（`.status.json` 超过 14 天未更新）。SpecDev 报告 README 接续点、active/completed/cancelled 与已结束未归档对象；更新时间无可靠来源时为 unknown，不以 mtime 推断 14 天停滞；调查 Assignment 按实际票回读，另报triage `external_action` / `publish_action`，以及 active+archive `<Path>{roots.state}/specdev/changes/{change}/publish.md</Path>` 汇总的 `published_issues`（含 `origin:local` / `origin:intake`）、`publish_skipped`、`publish_failed`；并报告 workspace `<Path>{roots.state}/specdev/capture.md</Path>` 的 `inbox_open` / `inbox_intaken` / `inbox_waived`（缺失视为空 inbox，不计入 `published_issues`）。数字以本地账本为准，不扫 GitHub 当权威。可用 `<Path>{roots.workflows}/specdev/specdev-t-triage/scripts/publish-status.mjs</Path>` 与 `<Path>{roots.workflows}/specdev/specdev-t-triage/scripts/capture-status.mjs</Path>`。Learning 额外报告 domain/topic、Lesson/Homework、immediate/retention 和 synthesis 状态；Ops 按主机和 APP/公共服务分别展示 deployment_id、observed_version、路径、最后部署时间、共享绑定、plan/approval/run 状态与双边 docs-receipt。docs_pending/unknown 必须列异常；普通状态报告不读取或输出 private 明文账本，不把 OPS 资源套入 active/archived Change 统计。
+5. 报告 archived 数量和完整 scope/project/change locator；Learning 同时读取 `context/REVIEW.md` 汇总到期 Review、topic evidence status 和需要刷新内容。按各域协议检查预期归档目录/权威工件缺失、active/archived 重叠、parent cycle、位置登记不一致、未知 schema、断开链接和 malformed 目录均列为异常，不自动修复。
+6. 报告没有 workflow 资产的孤立状态根，以及按领域协议应存在而缺失的状态根；SpecDev 无业务对象不视为损坏，不自动修复。
+7. 用户要求持久化时写入 `<Path>{roots.state}/commands/status/{date}-workspace-{topic}[-NN].md</Path>`，并在报告中列出本次扫描的 workflow 选择。

package/template/commands/upstream-fork-sync/COMMAND.md

@@ -0,0 +1,85 @@
+---
+id: upstream-fork-sync
+description: Assess a requested fork/upstream checkpoint and produce reproducible diff, conflict, and customization-risk evidence.
+---
+
+# Upstream Fork Sync
+
+以**检查点**为主导词。每个仓库始终分开记录：本次观测到的 upstream tip、可选本地 mirror tip，以及已经由产品分支历史证明完成集成的 upstream checkpoint。Fetch 或 mirror 变化不能推进集成 checkpoint。
+
+## 1. 解析上下文
+
+1. 从当前目录向上寻找并读取 `<Path>{roots.state}/workspace.json</Path>`，验证 `path_base` 和所有 roots，再读取 `<Path>{roots.config}</Path>`；无法唯一确定项目根时停止。
+2. 读取项目 `AGENTS.md` 及其作用域内规则。项目存在工程规范时读取适用入口。
+3. 将本 command 的唯一持久化根解析为 `<Path>{roots.state}/commands/upstream-fork-sync/</Path>`。独立运行只写该根；不创建其他 workflow 的 change；本 command 的报告写在同一 command namespace。
+4. 读取 [Repository contract](references/repository-contract.md)，确定仓库、refs、网络刷新和副作用边界。
+
+完成标准：项目根、Skill state 根、目标仓库集合和本次是否允许 fetch 都只有一个解释。
+
+## 2. 建立稳定配置
+
+读取 `<Path>{roots.state}/commands/upstream-fork-sync/repository-map.json</Path>`。不存在时，只读发现 Git 仓库、remotes、默认产品分支和 upstream tracking refs，按 [Repository contract](references/repository-contract.md) 创建 schema v1 配置；无法从 Git 事实唯一判断的字段一次性询问用户。配置已存在时验证，不静默改写。
+
+读取 `<Path>{roots.state}/commands/upstream-fork-sync/customization-map.md</Path>`。不存在时创建最小稳定清单，记录 fork 必须长期保留的产品不变量和审查热点；无法从项目文档或代码证明的业务约束标记为待确认。该文件不接收运行 SHA、dirty paths、冲突或本次结论。
+
+完成标准：每个 repository id 唯一，所有项目路径和 refs 可解析，稳定配置与动态运行事实分离。
+
+## 3. 创建评估 change
+
+读取 [State schema](references/state-schema.md) 和 [Report contract](references/report-contract.md)，从用户主题生成小写 ASCII kebab-case topic，然后运行：
+
+```bash
+node <Path>{roots.commands}/upstream-fork-sync/scripts/upstream-sync.mjs</Path> assess \
+  --root . \
+  --state-root <Path>{roots.state}/commands/upstream-fork-sync</Path> \
+  --repository-map <Path>{roots.state}/commands/upstream-fork-sync/repository-map.json</Path> \
+  --topic <topic>
+```
+
+- 默认离线使用本地 refs；只有用户明确要求刷新网络 refs 时添加 `--fetch`。
+- 只需预览完整冻结快照时添加 `--dry-run`，此分支不写 state 或 change。
+- 正常运行创建 `<Path>{roots.state}/commands/upstream-fork-sync/{date}-{topic}[-NN]/</Path>`，已有目录永不覆盖。
+
+完成标准：脚本退出 0，change 的 state 与两份报告完整发布，根 `state.json` 只在 change 发布成功后更新。
+
+## 4. 深化风险结论
+
+逐仓库检查报告中的 Git 确认冲突、自动合并重叠和定制风险路径。对每条高风险路径使用报告冻结的 SHA 执行精确 `git diff <base>..<target> -- <path>`，再与 `customization-map.md` 的稳定不变量映射。
+
+只把路径级证据支持的语义结论补入本 change 的报告。保持 Git 冲突、自动合并重叠、定制合同风险和 dirty-worktree 重叠为四个类别；零文本冲突不得表述为集成安全。
+
+完成标准：所有冲突和定制热点都有结论或明确未验证项，报告中的命令可以从冻结 SHA 复现。
+
+## 5. 返回后续选择
+
+返回 change 路径、仓库 checkpoint、观测 upstream SHA、风险摘要和未验证项。列出适合继续处理的已安装 Work，但不自动创建 workflow change、不调用 Work、不 merge、不 commit、不 push；后续路线由用户选择。
+
+完成标准：本次 Skill 在评估 change 完整后停止，用户能用冻结产物自行选择下一 Work。
+
+## 6. 记录外部集成
+
+只有其他 Work 已完成集成且用户要求更新 checkpoint 时进入此分支。读取目标 change state，并运行：
+
+```bash
+node <Path>{roots.commands}/upstream-fork-sync/scripts/upstream-sync.mjs</Path> record-integration \
+  --root . \
+  --state-root <Path>{roots.state}/commands/upstream-fork-sync</Path> \
+  --repository-map <Path>{roots.state}/commands/upstream-fork-sync/repository-map.json</Path> \
+  --change <change> \
+  --repository <repository-id> \
+  --merge-commit <full-sha> \
+  --upstream-sha <full-sha> \
+  --verification '<command>: exit 0'
+```
+
+该入口只在 merge commit 可从产品 ref 到达、目标 upstream SHA 是其精确非第一父节点且匹配 change 冻结目标时更新状态；它不执行集成。
+
+完成标准：change state 和根 checkpoint 都已原子重读，实际 Git 历史与记录一致。
+
+## 停止条件
+
+目标 ref 缺失、保存的 checkpoint 不在产品历史、checkpoint 不在当前 upstream 历史、存在多个 merge-base、配置越界或状态 schema 非法时，停止且不移动 refs、不发布部分 change、不推进 checkpoint。返回准确 repository id、路径、refs 与 SHAs。
+
+## 调用报告
+
+需要持久化本次报告时使用 <Path>{roots.state}/commands/upstream-fork-sync/{date}-{scope}-{topic}[-NN].md</Path>。复用当前授权和产物合同，不为只读调用自动创建状态；不覆盖历史报告。

package/template/commands/upstream-fork-sync/references/report-contract.md

@@ -0,0 +1,40 @@
+# Report Contract
+
+## Output
+
+每次成功 assessment 创建：
+
+```text
+<Path>{roots.state}/commands/upstream-fork-sync/{change}/state.json</Path>
+<Path>{roots.state}/commands/upstream-fork-sync/{change}/diff-report.md</Path>
+<Path>{roots.state}/commands/upstream-fork-sync/{change}/conflict-report.md</Path>
+```
+
+首份无编号，冲突时从 `-01` 选择最小未占用编号。整个 change 先在同一 state 根暂存，再原子 rename；不得覆盖或留下半成品目录。
+
+## Diff report
+
+每个仓库包含：
+
+- checkpoint 来源、已集成 upstream SHA、观测 upstream SHA、product SHA、merge-base、mirror SHA 和 freshness；
+- `integrated_upstream_sha..observed_upstream_sha` 的有序提交；
+- 完整 name-status 与 numstat 文件清单；
+- product 自 checkpoint 后也修改的路径；
+- repository map 风险 glob 命中的路径；
+- 使用冻结 SHA 的复现命令；
+- commit/file/conflict/risk 计数和当前 disposition。
+
+Agent 使用 customization map 和路径级 diff 增补语义结论；报告不内嵌无界完整 patch。
+
+## Conflict report
+
+使用 `git merge-tree --write-tree --messages <product-sha> <upstream-sha>`，不修改 index、worktree 或 refs。该命令可能在对象数据库留下不可达 tree objects。
+
+始终分开：
+
+1. Git confirmed conflicts；
+2. Automatically mergeable overlaps；
+3. Customization contract risks；
+4. Dirty worktree overlaps。
+
+始终生成 conflict report。零文本冲突明确写为零，并注明 merge-tree 无法证明编译、运行时、API、数据迁移、权限或业务行为安全。

package/template/commands/upstream-fork-sync/references/repository-contract.md

@@ -0,0 +1,54 @@
+# Repository Contract
+
+## Repository map
+
+`<Path>{roots.state}/commands/upstream-fork-sync/repository-map.json</Path>` 是稳定、项目专属的 Git ref 配置：
+
+```json
+{
+  "schema_version": 1,
+  "repositories": [
+    {
+      "id": "app",
+      "path": ".",
+      "product_ref": "refs/heads/main",
+      "origin_ref": "refs/remotes/origin/main",
+      "origin_remote": "origin",
+      "upstream_ref": "refs/remotes/upstream/main",
+      "upstream_remote": "upstream",
+      "mirror_ref": null,
+      "baseline_ref": null,
+      "risk_paths": ["src/auth/**", "package.json"]
+    }
+  ]
+}
+```
+
+- `id` 使用唯一小写 kebab-case。
+- `path` 是项目根 POSIX 相对 Git worktree 路径，`.` 表示项目根；不得绝对、包含 `..` 或指向符号链接目录。
+- `product_ref` 与 `upstream_ref` 必填且使用完整 `refs/...`。
+- `origin_ref`、`origin_remote`、`mirror_ref`、`baseline_ref` 可以为 `null`；配置 remote 时对应 ref 必须存在。
+- `risk_paths` 是项目确认的 glob；它补充稳定 customization map，不取代 Agent 的语义复核。
+
+## Ref invariants
+
+- Product ref 包含二次开发；mirror 只表示本地上游镜像。
+- 配置 baseline 时，它必须同时是 product 与 observed upstream 的祖先；配置 mirror 时，它必须是 observed upstream 的祖先。任一关系不成立时停止评估。
+- Fetch 只更新 remote-tracking refs。Skill 不自动 stash、reset、clean、rebase、force-update、删除、commit、merge、push、tag 或更新 submodule pointer。
+- Dirty worktree 不影响基于 commit 的评估，但必须独立报告。
+- `--fetch` 逐仓库刷新配置的 upstream remote，并在配置时刷新 origin remote；失败仓库使用现存 refs 且标记 `stale`，不得称为最新。
+
+## Checkpoint discovery
+
+没有有效保存 checkpoint 时：
+
+1. 若配置 baseline，从 baseline 到 product ref 的 first-parent merges 逆序检查；否则检查 product ref 的 first-parent merges。
+2. 选择最新一个其非第一父节点属于当前 upstream 历史的 merge。
+3. 记录该 upstream 父节点及 merge commit。
+4. 没有合格 merge 时，仅在 product/upstream 有唯一 merge-base 时使用它，且 merge commit 为 `null`。
+
+Mirror tip 不能推导已集成 checkpoint；cherry-pick patch equivalence 也不能推进 graph checkpoint。
+
+## Stable customization map
+
+`<Path>{roots.state}/commands/upstream-fork-sync/customization-map.md</Path>` 只保存长期 fork 不变量、领域约束和审查热点。当前 SHAs、fetch 结果、changed files、conflicts、dirty paths 和一次运行结论属于 change 报告。

package/template/commands/upstream-fork-sync/references/state-schema.md

@@ -0,0 +1,55 @@
+# State Schema
+
+## Root state
+
+`<Path>{roots.state}/commands/upstream-fork-sync/state.json</Path>` 使用 schema v1：
+
+```json
+{
+  "schema_version": 1,
+  "updated_at": "RFC-3339 timestamp",
+  "current_change": "YYYY-MM-DD-ascii-kebab-topic",
+  "repositories": {
+    "app": {
+      "integrated_upstream_sha": "full SHA",
+      "main_merge_sha": "full SHA or null",
+      "observed_upstream_sha": "full SHA"
+    }
+  }
+}
+```
+
+根 state 只是当前同步索引。它不保存 ref 配置、run history、dirty paths、文件清单、conflicts、fetch details 或 verification logs。
+
+## Change state
+
+每个 `<Path>{roots.state}/commands/upstream-fork-sync/{change}/state.json</Path>` 包含：
+
+```json
+{
+  "schema_version": 1,
+  "created_at": "RFC-3339 timestamp",
+  "repository_map_sha256": "sha256",
+  "repositories": {
+    "app": {
+      "product_sha": "full SHA",
+      "upstream_sha": "full SHA",
+      "integrated_upstream_sha": "full SHA",
+      "main_merge_sha": null,
+      "recorded_at": null,
+      "verification": []
+    }
+  }
+}
+```
+
+只列出存在 upstream delta 的仓库。`record-integration` 填写 `main_merge_sha`、`recorded_at` 和 verification，并推进根 checkpoint；assessment、fetch、mirror observation 和报告生成都不能推进 `integrated_upstream_sha`。
+
+## Update rules
+
+- 发布 change 的全部文件后才替换根 state。
+- 未知 schema、额外字段、非法 repository id 和 SHA 类型全部拒绝。
+- 保存 checkpoint 必须仍在 product 与 upstream 历史中。
+- `record-integration` 要求精确匹配 change 的冻结 upstream target。
+- 旧 change 的冻结 target 不得回退或分叉当前根 checkpoint。
+- 状态写入使用同目录临时文件、fsync 和 rename；失败不得伪装为成功。