@namewta/speculo 0.8.10 → 0.8.13

package/template/skills/engineering-standards-builder/templates/project-skill/generated-skill-set.json.template

@@ -0,0 +1,7 @@
+{
+  "schema_version": 1,
+  "generator": "engineering-standards-builder",
+  "skills": [
+{{SKILL_ENTRIES}}
+  ]
+}

package/template/skills/engineering-standards-builder/templates/project-skill/references/project/00-project-profile.md.template

@@ -11,11 +11,13 @@
 
 {{EVIDENCE_SUMMARY}}
 
+证据使用项目根相对路径。扫描结果只作基线，重要结论必须由源码、配置、CI、测试、消费者或已声明模板复核。
+
 ## 工具链与质量门禁
 
 {{QUALITY_GATES}}
 
-每个命令必须包含 scope、working directory、来源和当前状态（active/planned）。
+每个命令必须包含 scope、working directory、来源和当前状态（active/planned）。`planned` 不能作为已通过门禁。
 
 ## 排除与冻结区域
 

package/template/skills/engineering-standards-builder/templates/project-skill/references/project/01-module-map.md.template

@@ -18,6 +18,8 @@ quality gates
 evidence/confidence
 ```
 
+不要因根目录 manifest 或单个扩展名把语言/框架规则扩散到其他模块。
+
 ## 依赖方向
 
 {{DEPENDENCY_DIRECTIONS}}
@@ -25,3 +27,5 @@ evidence/confidence
 ## 路由
 
 {{MODULE_RULE_ROUTES}}
+
+领域 Skill 的独立触发和 owner 统一记录在 [Skill 地图](03-skill-map.md)。

package/template/skills/engineering-standards-builder/templates/project-skill/references/project/02-decisions-and-exceptions.md.template

@@ -10,7 +10,7 @@
 Decision ID:
 Scope:
 Decision:
-Source: user-decision | repository-fact | official-guidance | builder-baseline
+Source: user-decision | repository-fact | project-template | official-guidance | builder-baseline
 Rationale:
 Migration:
 Verification:

package/template/skills/engineering-standards-builder/templates/project-skill/references/project/03-skill-map.md.template

@@ -0,0 +1,19 @@
+# Skill 地图
+
+`engineering-standards` 是规范权威。只有当前任务命中下表中的独立触发条件时，才读取对应领域 Skill。
+
+{{SKILL_MAP}}
+
+每个领域 Skill 记录：
+
+```text
+Name
+Role
+Triggers
+Scope
+Canonical evidence
+Exclusions
+Relationship to engineering-standards
+```
+
+清单外的项目 Skill 不归 Engineering Standards Builder 所有，不得因 refresh 被修改或删除。

package/template/skills/engineering-standards-builder/templates/project-skill/references/project/04-source-and-template-map.md.template

@@ -0,0 +1,22 @@
+# 源码与模板地图
+
+这里导航到项目中的唯一事实源，不复制源码、FM 模板或脚手架正文。每个记录必须含至少一个可解析的项目内 Markdown 链接。
+
+{{SOURCE_AND_TEMPLATE_RECORDS}}
+
+推荐格式：
+
+```text
+## <Capability>
+- Read when:
+- Canonical source/template: project-relative Markdown link
+- Role:
+- Applies when:
+- Produces:
+- Manual integration:
+- Consumers/tests:
+- Verification:
+- Legacy/counterexamples:
+```
+
+模板只负责骨架时必须明确列出生成后仍需完成的业务逻辑、注册、import、配置和测试。

package/template/skills/engineering-standards-builder/templates/project-skill/references/project/review-checklist.md.template

@@ -3,12 +3,14 @@
 只检查与当前 scope 和风险相关的条目。
 
 - [ ] 变更映射到模块地图中的明确 scope。
+- [ ] 只读取了 Skill 地图路由的最小充分领域 Skill 和项目来源。
 - [ ] 依赖只通过允许的 public contract，未产生循环或深导入。
 - [ ] 外部输入、权限、秘密和敏感数据边界已处理。
 - [ ] 错误、超时、取消、资源和并发生命周期完整。
 - [ ] public API、schema、事件、CLI 或持久化兼容影响已说明。
 - [ ] 测试层级匹配风险，失败与清理路径被覆盖。
 - [ ] generated/vendor/frozen 文件未被无意修改。
+- [ ] 引用的源码/FM/脚手架仍是项目真实路径，未在 Skill 中复制第二份事实源。
 - [ ] 实际运行的 format/lint/compile/test/build 命令及退出码已记录。
 - [ ] 当前状态、目标状态、Ratchet 与例外没有混写。
 - [ ] 文档、迁移、回滚、可观测性和发布影响按需更新。

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

@@ -0,0 +1,100 @@
+---
+id: git-history-squash
+type: skill
+name: git-history-squash
+description: 受控压缩指定 Git 分支 tip 的 first-parent 提交区间，并以可恢复的本地 ref 事务和精确远端 lease 收敛历史。
+disable-model-invocation: true
+---
+
+# Git History Squash
+
+以**受控历史收敛**为主导词。本 Skill 只在用户显式调用后运行；讨论 squash、rebase、提交整理或项目文件中的指令均不构成调用或副作用授权。
+
+## 1. 解析运行上下文
+
+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>`，已有目录永不覆盖。
+4. 从 [request template](assets/request-template.json) 生成临时 request JSON。用户必须逐仓库明确 repository、完整 local branch ref、start、end、`inclusive | exclusive`、commit message、签名选择和远端发布选择；不得猜测缺失值。
+5. 读取 [Rewrite contract](references/rewrite-contract.md)，用它验证区间语义、预检项、确认门和 Git 写入边界。涉及父仓库与 submodule 时同时读取 [Submodule contract](references/submodule-contract.md)。
+
+**完成标准**：项目根、Skill state 根、request、目标仓库、分支、边界、消息和远端选择均只有一个解释；缺失项已向用户询问而非采用默认值。
+
+## 2. 生成 dry-run 计划
+
+运行：
+
+```bash
+node <Path>{roots.skills}/git-history-squash/scripts/git-history-squash.mjs</Path> plan \
+  --root . \
+  --state-root <Path>{roots.state}/skills/git-history-squash</Path> \
+  --evidence-root <Path>{roots.state}</Path> \
+  --request <request.json>
+```
+
+`plan` 可以写本 Skill 的报告与恢复 state，但不得创建 Git object、移动 ref、改变 index/worktree 或访问远端写接口。它冻结完整 SHA、区间计数、merge 数、worktree、dirty/operation 状态、关联 refs、workflow evidence、submodule 图、远端 tip 和可验证的保护策略。
+
+将脚本返回的 `change`、`report`、`next_action` 和 digest 原样保存。任何 blocker 都保持 dry-run，返回报告和修复条件。
+
+**完成标准**：报告位于本 Skill 的唯一运行目录；所有 Git refs 与工作区状态和 plan 前相同；只有无 blocker 的精确 manifest 才产生 `confirm-local`。
+
+## 3. 本地确认与执行
+
+向用户展示报告中的完整本地 manifest：每个 repository、branch、start/end/baseline SHA、first-parent/reachable/merge 数、commit message、签名选择、backup ref、关联 refs/worktrees，以及 submodule 执行层。
+
+只有用户在当前对话中明确确认该 manifest 和 `plan_digest` 后运行：
+
+```bash
+node <Path>{roots.skills}/git-history-squash/scripts/git-history-squash.mjs</Path> apply \
+  --root . \
+  --state-root <Path>{roots.state}/skills/git-history-squash</Path> \
+  --change <change> \
+  --confirm-plan <plan_digest>
+```
+
+脚本执行前重验完整计划。每个仓库使用终点 tree 与唯一 baseline parent 创建新 commit，再以 compare-and-swap ref transaction 同时创建 backup ref、移动目标 branch。任一漂移停止当前层；不删除或改写其他 branch、tag、worktree、stash、reflog 或 workflow evidence。
+
+多层 submodule 图只执行当前 eligible 层；下层要求发布时，父层必须等下层远端验证后重新产生新的 `plan_digest` 并再次确认。
+
+**完成标准**：脚本重读证明每个已处理仓库的新 tree、parent、提交数、backup ref 和工作区状态满足合同；失败时 state/report 明确区分已完成与未完成仓库。
+
+## 4. 远端确认与发布
+
+当脚本返回 `confirm-publish` 时，向用户展示完整远端 manifest：repository、remote、remote branch、冻结的 old SHA、local new SHA、保护策略和发布顺序。
+
+只有用户在当前对话中明确确认该 manifest 和 `publish_digest` 后运行：
+
+```bash
+node <Path>{roots.skills}/git-history-squash/scripts/git-history-squash.mjs</Path> publish \
+  --root . \
+  --state-root <Path>{roots.state}/skills/git-history-squash</Path> \
+  --change <change> \
+  --confirm-publish <publish_digest>
+```
+
+发布只使用精确 `--force-with-lease=<ref>:<old-sha>` 和单一显式 refspec。远端 tip 漂移、保护策略不允许、push 失败或回读不等于 new SHA 时立即停止；不回滚已经发布的其他仓库。
+
+**完成标准**：每个成功远端 branch 回读精确等于 new SHA；父仓库 gitlink 指向的 child SHA 已先从对应远端 branch 到达；未发布仓库及恢复步骤已进入报告。
+
+## 5. 恢复或结束
+
+读取 [Recovery contract](references/recovery-contract.md)。中断或重入时先运行：
+
+```bash
+node <Path>{roots.skills}/git-history-squash/scripts/git-history-squash.mjs</Path> status \
+  --root . \
+  --state-root <Path>{roots.state}/skills/git-history-squash</Path> \
+  --change <change>
+```
+
+实际 refs/remotes 与 state 一致时，使用脚本返回的下一 digest 回到步骤 3 或 4。漂移时保持 blocked，按报告生成新的精确恢复计划并重新取得授权；本 Skill 不自动执行恢复或清理。
+
+**完成标准**：运行状态为 `completed-local | completed-published | blocked-partial` 之一；报告包含全部确认、验证、远端结果和精确恢复命令，且没有 token、email、凭证 URL 或机器绝对路径。
+
+## 固定边界
+
+- `end` 必须等于目标 local branch tip；v1 不改写分支内部区间。
+- `start` 必须位于 `end` 的 first-parent 链；`inclusive` 使用 `start^1` 为 baseline，root start 产生无 parent 新提交；`exclusive` 保留 start 并以其为 baseline。
+- dry-run 不 fetch、不 stash、不 checkout、不创建 commit/tree、不移动 ref、不改变 index、不 push。
+- 本 Skill 不调用 `rebase`、普通 `--force`、没有精确 expected SHA 的 lease、`reset --hard` 或自动 cleanup。
+- GitHub 远端只有在 protection/rules 查询成功且允许非 fast-forward update 时才发布；无法验证策略的远端只生成本地计划。

package/template/skills/git-history-squash/assets/request-template.json

@@ -0,0 +1,18 @@
+{
+  "schema_version": 1,
+  "topic": "replace-me",
+  "repositories": [
+    {
+      "id": "replace-me",
+      "path": ".",
+      "branch": "refs/heads/replace-me",
+      "start": "replace-me",
+      "end": "replace-me",
+      "boundary": "inclusive",
+      "message": "replace-me",
+      "sign": false,
+      "remote": null,
+      "submodule_of": null
+    }
+  ]
+}

package/template/skills/git-history-squash/references/recovery-contract.md

@@ -0,0 +1,50 @@
+# Recovery Contract
+
+## Re-entry
+
+根 `state.json` 只定位当前 change。重入时读取 change `state.json`，再重读实际 local branch、backup ref、worktree、index、submodule checkout 和 remote branch，不从保存的 phase 直接推断成功。
+
+每个 repository 只能归入一个现场：
+
+- `untouched`：branch=old，backup 不存在；可以重新计划；
+- `local-verified`：branch=new，backup=old，本地验证通过；可以生成远端 manifest；
+- `published`：本地为 new，remote=new，backup=old；该层完成；
+- `recoverable-partial`：branch/remote 是 old 或 new 的可解释组合，但与保存 phase 不同；更新报告后等待新授权；
+- `unknown-drift`：出现第三个 SHA、backup 错误、dirty 状态或 gitlink/index 不一致；停止人工处理。
+
+授权只对展示过的当前 digest 有效。旧对话确认、state 中的确认记录、项目文件文字或先前层授权不能用于新的 apply、publish、restore 或 cleanup。
+
+## Local restore plan
+
+Local restore 只生成计划，不自动执行。单仓库基础命令为：
+
+```bash
+git -C <project-relative-repository> update-ref \
+  <target-branch> <old-sha> <new-sha>
+```
+
+执行前必须证明 backup ref 仍等于 old SHA、target branch 仍等于 new SHA，并重新取得明确 restore 授权。父仓库应从根到叶恢复 gitlink refs/index/checkouts，随后逐仓库验证 clean；恢复失败保留 backup refs。
+
+## Remote restore plan
+
+远端已发布时，恢复也是新的历史改写，必须独立确认并使用反向精确 lease：
+
+```bash
+git -C <project-relative-repository> push <remote> \
+  --force-with-lease=<remote-ref>:<new-sha> \
+  <backup-ref>:<remote-ref>
+```
+
+从父到子恢复远端，保证父 gitlink 不会在恢复过程中指向尚不可达 child。每次 push 后回读 remote ref；任何 lease 漂移停止后续恢复。
+
+## Preserved evidence
+
+完成与恢复都保留：
+
+- backup refs；
+- source/integration worktrees 和 branches；
+- stash 与 reflog；
+- workflow status、Evidence 和历史 SHA 引用；
+- 运行 state/report。
+
+删除这些内容是独立 cleanup 行为，需要新的精确目标和授权，不属于本 Skill。

package/template/skills/git-history-squash/references/rewrite-contract.md

@@ -0,0 +1,123 @@
+# Rewrite Contract
+
+## Request schema
+
+Request 使用 schema v1：
+
+```json
+{
+  "schema_version": 1,
+  "topic": "account-profile",
+  "repositories": [
+    {
+      "id": "backend",
+      "path": "services/backend",
+      "branch": "refs/heads/feature/account-profile",
+      "start": "<commit-ish>",
+      "end": "<commit-ish>",
+      "boundary": "inclusive",
+      "message": "feat: complete account profile",
+      "sign": false,
+      "remote": {
+        "name": "origin",
+        "branch": "refs/heads/feature/account-profile",
+        "publish": true
+      },
+      "submodule_of": null
+    }
+  ]
+}
+```
+
+- `topic` 和 repository `id` 使用小写 ASCII kebab-case。
+- `path` 是项目根 POSIX 相对路径，`.` 表示项目根；不得绝对、包含 `..` 或穿越符号链接。
+- `branch` 与 remote branch 必须是通过 `git check-ref-format` 的完整 `refs/heads/...`。
+- `start`、`end` 在 plan 时各解析一次并冻结为完整 commit SHA；空值和歧义值失败。
+- `message` 非空且不含 NUL；完整消息进入私有运行 state，报告只保留 subject 与 SHA-256。
+- `sign` 必须是 boolean；为 true 时使用当前仓库签名配置执行 `git commit-tree -S` 并在移动 ref 前验证新 commit。
+- `remote` 为 `null` 表示 local-only；非 null 时三个字段均必填。`publish: false` 不访问远端写接口。
+
+## Range semantics
+
+目标范围始终结束于选中 local branch 的 tip：
+
+```text
+exclusive: baseline = start,    replace start..end
+inclusive: baseline = start^1,  replace start^1..end
+```
+
+`inclusive` start 没有 parent 时 baseline 为 null，新提交成为 root commit。Start 必须出现在 `git rev-list --first-parent end` 中；只通过普通 ancestry 到达不够。End 不等于 branch tip、范围为空或范围不能减少节点时失败。
+
+普通 repository 的新 commit 使用 `end^{tree}`，并且只有 baseline 一个 parent。该策略不重放被替换的 merge，不执行内容合并，也不读取真实 index 来构造 tree。
+
+## Read-only preflight
+
+逐仓库穷尽检查：
+
+- Git feature probe、worktree/bare/shallow 状态、replace refs 和 grafts；
+- branch/start/end/baseline 的 object 类型、first-parent ancestry 和范围计数；
+- 全部 linked worktrees 的 branch、HEAD、locked/prunable、staged、unstaged、untracked 状态；
+- merge、rebase、cherry-pick、revert、bisect、sequencer 与 index/ref lock；
+- stash tip、范围内 local branch/remote/tag refs 和从旧 SHA 定位到的 workflow evidence；
+- submodule mode `160000`、`.gitmodules` 映射和 request dependency 图；
+- remote push URL 数量、remote branch tip、local ancestry 和 provider protection policy。
+
+Plan 命令统一设置 `GIT_OPTIONAL_LOCKS=0`。已有 stash、其他 refs 和 completed/archived workflow evidence 只记录；active workflow evidence、dirty/prunable worktree、进行中操作、浅克隆、replace/graft、多个 push URL 或未知远端保护策略阻塞执行。
+
+## Local transaction
+
+执行层开始前，把 `phase=local-applying` 和精确 manifest 原子写入运行 state/report。创建 commit object 后先验证 tree、parent、message digest 和签名，再通过 `git update-ref --stdin` 事务完成：
+
+```text
+start
+create <backup-ref> <old-head>
+update <target-branch> <new-head> <old-head>
+prepare
+commit
+```
+
+Backup ref 格式为：
+
+```text
+refs/speculo/backups/git-history-squash/<run-id>/<repository-id>
+```
+
+事务必须要求 backup ref 不存在且 target branch 仍等于 old head。每仓库事务原子；多个仓库之间不宣称原子。脚本在每个仓库成功后立刻原子更新运行 state/report。
+
+## Local verification
+
+普通 repository 同时满足：
+
+- `new^{tree} == old_end^{tree}`；
+- new 的 parent list 精确等于 baseline，或 root-inclusive 时为空；
+- `git rev-list --count baseline..new == 1`，root-inclusive 使用 `git rev-list --count new == 1`；
+- target branch 等于 new，backup ref 等于 old；
+- target branch 所在 worktree 仍 clean。
+
+Submodule parent 使用 submodule contract 的 planned tree，不套用普通 tree 等价规则。
+
+## Remote lease
+
+远端 old SHA 来自 push URL 对应 branch 的 `git ls-remote --exit-code`，不从 remote-tracking ref 推断。发布前再次回读，随后只运行等价于：
+
+```bash
+git push <remote> \
+  --force-with-lease=<remote-ref>:<remote-old-sha> \
+  <local-ref>:<remote-ref>
+```
+
+Remote ref 不存在、old SHA 在本地未知、old SHA 不是 old local head 的祖先、lease 漂移或回读失败均停止。普通 `--force`、省略 expected SHA 的 lease、matching refspec 和多个 push destinations 不进入执行路径。
+
+本地 path/file remote 的 protection 为 `not-applicable`。`github.com` remote 使用 `gh api` 读取 branch、classic protection 和适用 rules；`non_fast_forward`、锁定、禁止 force push、需要 PR 或无法判定时阻塞发布。其他 provider 在 v1 标记 `unknown` 并阻塞发布。
+
+## Report and state
+
+根 state：
+
+```json
+{"schema_version":1,"current_change":"YYYY-MM-DD-topic"}
+```
+
+运行 state 保存 schema version、run id、phase、request、冻结 repository manifest、per-repository result、当前 local/publish digest、确认摘要、错误和更新时间。写入使用同目录临时文件、flush/fsync 和 atomic rename；state symlink、未知 schema 或现有 active run 漂移时停止。
+
+`report.md` 从运行 state 整体重建，只允许原子替换同一 run 的报告；其他运行目录和报告永不覆盖。报告路径使用项目相对 POSIX 路径，外部 worktree 使用稳定占位 locator；URL、token、email 和机器绝对路径不得持久化。

package/template/skills/git-history-squash/references/submodule-contract.md

@@ -0,0 +1,54 @@
+# Submodule Contract
+
+## Dependency graph
+
+每个 child repository 用 `submodule_of` 声明直接父级：
+
+```json
+{
+  "repository": "workspace",
+  "gitlink_path": "services/backend"
+}
+```
+
+- Parent id 必须属于同一 request；图必须无环。
+- Child `path` 必须解析为 parent path 下 `gitlink_path` 的真实 repository。
+- Parent end tree 在该路径必须是 mode `160000`，old gitlink 必须等于 child old end。
+- Parent `.gitmodules` 必须唯一声明该 path；嵌套 submodule 逐层处理。
+- 有 parent 的 child 必须配置 `remote.publish: true`；父级 local ref 只能在 child new SHA 已从声明的远端 branch 回读后推进。
+
+## Planned parent tree
+
+父仓库的 old/new tree 不可能完全相等，因为 child squash 会改变 commit SHA。父级验证目标定义为：
+
+```text
+planned parent tree = parent old end tree
+                      + 每个直接 child gitlink old SHA -> child published new SHA
+```
+
+脚本使用临时 `GIT_INDEX_FILE` 读取 parent old end tree，只对已声明 mode `160000` 路径执行 cacheinfo 替换，再 `write-tree`。临时 index 不得指向真实 repository index。
+
+父级新 tree 与 old tree 的差异必须精确等于声明的 gitlink 路径；路径 mode 必须保持 `160000`，new object id 必须等于已发布 child SHA。普通文件、目录、symlink 或未声明 gitlink 有任何差异都停止。
+
+## Execution order
+
+1. 叶子 repository 生成 dry-run manifest并取得本地确认；
+2. 叶子完成 local transaction 和 tree 验证；
+3. 叶子生成 remote manifest并取得远端确认；
+4. 叶子远端 branch 回读精确等于 new SHA；
+5. 父级使用这些已发布 SHA 生成新的本地 manifest，再次取得确认；
+6. 父级创建 planned tree/new commit、推进 local ref并验证；
+7. 从叶到根重复，最上层最后发布。
+
+用户拒绝或延迟某层远端确认时，已完成 child 保持 `local-verified`，parent 保持 `planned`。后续调用从 state 恢复，但重新读取所有 refs/remotes 并重新取得当前层授权。
+
+## Checked-out aggregate worktree
+
+父目标 branch 未在任何 worktree checkout 时，只更新 branch ref。父目标 branch 已 checkout 时：
+
+- 预检要求 parent 和直接 child worktree 均 clean；
+- child checkout 为目标 branch 时必须已随 branch ref 到达 new SHA；为 detached HEAD 时只能从精确 old SHA CAS 到 child new SHA；其他状态阻塞；
+- 父真实 index 只更新声明的 gitlink cache entries，使其与 planned tree 一致；
+- 完成后父与 child worktree 必须 clean。
+
+Index、detached HEAD 或 branch ref 任一步失败时停止并保留 backup ref；跨 repository/index 操作不宣称原子，报告列出现场与恢复顺序。