@namewta/speculo 0.8.3 → 0.8.5

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

@@ -0,0 +1,54 @@
+# Repository Contract
+
+## Repository map
+
+`<Path>{roots.state}/skills/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}/skills/upstream-fork-sync/customization-map.md</Path>` 只保存长期 fork 不变量、领域约束和审查热点。当前 SHAs、fetch 结果、changed files、conflicts、dirty paths 和一次运行结论属于 change 报告。

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

@@ -0,0 +1,55 @@
+# State Schema
+
+## Root state
+
+`<Path>{roots.state}/skills/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}/skills/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；失败不得伪装为成功。