@namewta/speculo 1.0.18 → 1.0.20

package/template/skills/engineering-standards-builder/SKILL.md

@@ -1,21 +1,161 @@
 ---
 name: engineering-standards-builder
 description: Generate or refresh project-specific engineering skills after the user explicitly invokes the builder.
+disable-model-invocation: true
 metadata: {"speculo-invocation": "user-only"}
 ---
 
-# engineering-standards-builder
+# Engineering Standards Builder
 
-Activation is explicit-only. Metadata is descriptive; enforce host permissions and obtain user authorization before effects.
+本 Skill 只在用户明确调用时运行。它不会在新项目中自动启动，也不把 Builder 自带的通用建议直接复制成项目规范。
 
-This file is the routing entry. Read [`references/entry-procedure.md`](references/entry-procedure.md) only after this skill is selected. Read a named reference there only for the active branch.
+目标是先理解当前项目真实的代码、目录、配置、测试、CI 与模板，再生成一组可长期复用的项目专属 Skill：一个稳定的工程规范路由入口，以及零个或多个有独立触发价值的领域 Skill。
 
-## Scope
+```text
+项目事实 + 用户指定的重点范围 + 已确认目标
+  -> 证据审计与冲突收敛
+  -> 最小充分 Skill Set
+  -> .agents/skills/
+```
 
-- Trigger: Generate or refresh project-specific engineering skills after the user explicitly invokes the builder.
-- 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.
+## 产物与所有权
 
-## 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.
+```text
+.agents/skills/
+├── engineering-standards/
+│   ├── SKILL.md
+│   ├── generated-skill-set.json
+│   └── references/project/
+│       ├── 00-project-profile.md
+│       ├── 01-module-map.md
+│       ├── 02-decisions-and-exceptions.md
+│       ├── 03-skill-map.md
+│       ├── 04-source-and-template-map.md
+│       └── review-checklist.md
+└── <optional-domain-skill>/
+    ├── SKILL.md
+    └── references/...
+```
+
+`engineering-standards` 是规范权威与路由器；领域 Skill 负责可独立触发的实现导航，不重复定义冲突规则。`generated-skill-set.json` 只登记 Builder 拥有的 `.agents/skills/*` 路径。刷新时不得改动或删除清单之外的 Skill。
+
+## 最小原则
+
+- 不按语言、目录或 Agent 数量机械拆 Skill。
+- 能由根路由和少量 references 清楚表达时，不新增领域 Skill。
+- 没有项目证据的规则不生成；Builder references 只提供审计维度与 fallback。
+- 不复制项目源码、FM 模板或脚手架正文；引用其真实路径并说明适用条件、集成步骤和验证方式。
+- 不新增配置文件、参数、时间戳、hash 或模型元数据来制造形式化负担。
+- 扫描深度、文件数和字节限制只是脚本内部资源保护，不是用户需要决策的项目规范。
+
+## 执行流程
+
+### 1. 确定项目根与学习范围
+
+从用户当前工作目录、Git/Workspace 边界和用户指定的代码或目录确定真实项目根。记录需要重点学习的模块、代码、目录、模板或脚手架；未指定时覆盖所有可编辑模块。
+
+读取现有 `AGENTS.md`、`CLAUDE.md`、贡献文档、架构文档和 `.agents/skills/`，但将它们视为待验证证据。识别 generated、vendor、build、cache、fixture 与冻结目录。发现已有 `generated-skill-set.json` 时进入 refresh；只有 legacy `engineering-standards` 时，在计划中声明接管该根 Skill，其他现有 Skill 一律视为非 Builder 所有。
+
+冲突优先级见 [治理与证据优先级](references/rules/00-governance-and-precedence.md)，路径和 scope 见 [证据、拓扑与作用域](references/rules/02-evidence-topology-and-scope.md)。本阶段只读。
+
+**完成标准**：项目根、重点范围、排除范围、现有规范和 Builder 写入边界明确。
+
+### 2. 建立确定性事实基线
+
+运行扫描器并捕获 stdout；默认不在项目中持久化 inventory：
+
+```bash
+node <skill-root>/scripts/discover-project.mjs --root <project-root> --pretty
+```
+
+扫描合同见 [项目发现合同](references/rules/01-project-discovery.md)。扫描器只提供拓扑基线，不能替代源码审计。继续读取真实 manifest/build 配置、CI 命令、公共入口、代表性实现、测试、消费者与项目模板。
+
+**完成标准**：每个可编辑模块有路径、技术栈、入口、质量门禁和证据；扫描限制、冲突与未知项已记录。
+
+存在可机械验证的边界/约束缺口时，读取 [工程约束](references/rules/09-mechanical-guardrails.md)，决定是否提出接入与验证方案。
+
+### 3. 用 Agent Team 分域取证
+
+当运行环境支持 Agent Team 且存在两个以上可独立审计的证据域时，默认由 leader 并行派发只读 scout。证据域按项目真实边界划分，例如架构与公共 API、后端、前端、公共复用、测试与 CI、FM/脚手架；不得套用固定角色表。
+
+leader 是唯一写入者。每个 scout 必须返回同一份精简证据合同：
+
+```text
+Scope
+Observed capability
+Canonical source paths
+Mature implementations
+Template paths
+Consumers and tests
+Applicable conditions
+Legacy/counterexamples
+Conflicts/unknowns
+Recommended skill boundary
+```
+
+leader 必须复读高影响路径，检查跨域冲突，并把同一事实的重复报告合并。Agent Team 不可用或任务不可合理拆分时，leader 按相同合同顺序审计；结果标准不变。
+
+**完成标准**：重要规范均有真实路径、消费者或测试支撑；反例、旧实现和未知项没有被“多数模式”掩盖。
+
+### 4. 收敛规范与 Skill 边界
+
+先识别项目已经声明的 canonical 模板或代码样板，例如 `docs/fm/**`、scaffold、generator assets。模板与成熟代码冲突时，判断它是目标模板、过期模板还是仅负责骨架，并记录 current、target 与 migration；不得静默任选一方。
+
+只有同时满足以下条件才创建领域 Skill：
+
+1. 有可独立描述的触发场景；
+2. 会在多次开发中复用；
+3. 有充分的项目源码、模板、测试或配置证据；
+4. 与根路由或其他领域 Skill 边界清晰；
+5. 独立后能明显减少无关上下文。
+
+否则内容留在 `engineering-standards`。领域 Skill 名称来自项目语义，不使用固定列表或固定数量。高影响未知项按 [决策收敛合同](references/rules/03-interview-and-decisions.md) 询问；用户已授权直接生成时，将无法安全推断的事项记为 `pending-decision`。
+
+只读取与项目事实匹配的 [通用规则索引](references/rules/README.md)、[TypeScript/JavaScript](references/typescript/README.md)、[Java](references/java/README.md)、[Go](references/go/README.md) 或 [Rust](references/rust/README.md) references。内置语言包和 [未内置语言 fallback](references/rules/16-language-adapter-contract.md) 是检查清单，不是高于项目代码的规范来源。
+
+**完成标准**：每个生成 Skill 都有独立价值和证据边界；没有为了覆盖目录或技术栈而过度拆分。
+
+### 5. 计划、生成与刷新
+
+先展示精简计划：模块与证据摘要、Skill Map、每个 Skill 的来源路径、保留/更新/新增/删除项、冲突决策和验证命令。用户已在当前请求中授权实施时，展示后直接执行。
+
+按 [Skill Set 生成合同](references/rules/14-generation-contract.md) 和 [模板索引](templates/README.md) 生成。所有项目引用使用项目根相对路径，并说明：何时读取、它负责什么、输出位置、需要哪些手工集成、运行什么验证。
+
+先准备完整候选内容并校验，再替换 Builder 拥有的文件。刷新规则：
+
+- 只更新或删除旧 `generated-skill-set.json` 登记的路径；
+- 名称与未登记 Skill 冲突时停止覆盖并重新命名或询问；
+- 保留仍有效的用户决策、例外和项目特有知识；
+- 删除或重命名必须在计划中显式列出；
+- 候选验证失败时保留旧 Skill Set；发布后验证失败时恢复旧内容；
+- 相同项目事实与决策重复运行应无无意义 diff。
+
+**完成标准**：根路由、领域 Skill、项目引用与所有权清单一致，清单外 Skill 未发生变化。
+
+### 6. 验证与报告
+
+运行：
+
+```bash
+node <skill-root>/scripts/validate-generated-skill.mjs --root <project-root> --strict
+```
+
+再按 [验证合同](references/rules/15-validation-contract.md) 执行项目已存在且本次允许的质量门禁。不得通过删除测试、放宽编译配置或扩大例外获取通过。
+
+最终报告生成/更新/保留/删除的 Skill，关键证据与模板路径，运行命令及退出码，未验证项、待确认决策和临时例外。
+
+**完成标准**：所有权、frontmatter、Skill 路由、项目内引用、选择性适配和规则字段通过；项目门禁通过或留下可复现阻塞证据。
+
+## Builder 自校验
+
+维护本 Skill 时读取 [fixture 合同](examples/README.md)，并运行：
+
+```bash
+node scripts/sync-manifest.mjs --root . --check
+node scripts/validate-builder.mjs --root .
+node scripts/self-test.mjs --root .
+```
+
+这些脚本无第三方依赖、接受显式根目录、拒绝路径越界，并提供 `--help`。

package/template/skills/engineering-standards-builder/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/template/skills/engineering-standards-builder/manifest.txt

@@ -1,3 +1,4 @@
+agents/openai.yaml
 examples/fallback/kotlin-gradle/build.gradle.kts
 examples/fallback/kotlin-gradle/expected.json
 examples/fallback/kotlin-gradle/src/main/kotlin/example/App.kt
@@ -44,7 +45,6 @@ examples/typescript/vue-vite/src/main.ts
 examples/typescript/vue-vite/tsconfig.json
 examples/typescript/vue-vite/vite.config.ts
 README.md
-references/entry-procedure.md
 references/go/00-detection-and-scope.md
 references/go/01-language-and-idioms.md
 references/go/02-modules-packages-and-layout.md
@@ -67,6 +67,7 @@ references/rules/05-files-directories-and-naming.md
 references/rules/06-apis-errors-resources-and-concurrency.md
 references/rules/07-documentation-and-comments.md
 references/rules/08-testing-strategy.md
+references/rules/09-mechanical-guardrails.md
 references/rules/09-security-configuration-and-data.md
 references/rules/10-performance-observability-and-i18n.md
 references/rules/11-tooling-quality-gates-and-ci.md

package/template/skills/engineering-standards-builder/references/rules/09-mechanical-guardrails.md

@@ -0,0 +1,9 @@
+# 可验证的工程约束
+
+仅在项目证据支持且用户所选范围需要时应用。先检查现有 lint、test、pre-commit、CI 是否已有规则且真正接入；已有检查失效优先修复接入，不复制禁令到更多文档。
+
+TypeScript 深模块可用项目现有 dependency-cruiser 或等价工具表达公开入口、私有实现、依赖方向与无环约束。先观察消费者和既有 exports/API；不能统一强制所有项目采用某种目录布局。测试可以通过公共入口验证行为，内部测试是否保留按实际维护收益决定。
+
+候选机械约束必须有通过→故意违规失败→恢复后通过的证据，并证明违规落地、检查命中了实际文件。pre-commit 只作为项目已有/明确选择的执行点，不默认安装 Husky、格式化器或依赖，不静默修改 CI。新增安装、脚本或配置属于独立实现写集，由调用方决定。
+
+生成的工程 Skill 只引用实际存在的命令和约束；尚未实现的建议单列，不伪装成已生效规则。

package/template/skills/engineering-standards-builder/scripts/validate-builder.mjs

@@ -128,8 +128,6 @@ async function main() {
     }
 
     const skillFile = fileByRel.get('SKILL.md');
-    const entryProcedure = fileByRel.get('references/entry-procedure.md');
-    if (!entryProcedure) errors.push('references/entry-procedure.md is missing');
     if (!skillFile) errors.push('SKILL.md is missing');
     else {
       const skillText = await readFile(skillFile.abs, 'utf8');
@@ -145,11 +143,11 @@ async function main() {
         try { metadata = JSON.parse(frontmatter.values.metadata ?? '{}'); }
         catch { errors.push('Builder metadata must use the emitted JSON-flow mapping'); }
         if (metadata['speculo-invocation'] !== 'user-only') errors.push('Builder must remain explicitly user-invoked with metadata.speculo-invocation=user-only');
-        if (!skillText.includes('Activation is explicit-only.')) errors.push('Builder must retain its visible explicit user selection boundary');
+        if (!skillText.includes('本 Skill 只在用户明确调用时运行。')) errors.push('Builder must retain its visible explicit user selection boundary');
       }
-      const contractText = entryProcedure ? await readFile(entryProcedure.abs, 'utf8') : '';
+      const contractText = skillText;
       for (const requiredConcept of ['Agent Team', 'generated-skill-set.json', '最小原则', 'Skill 边界']) {
-        if (!contractText.includes(requiredConcept)) errors.push(`references/entry-procedure.md is missing core contract: ${requiredConcept}`);
+        if (!contractText.includes(requiredConcept)) errors.push(`SKILL.md is missing core contract: ${requiredConcept}`);
       }
     }
 
@@ -204,7 +202,6 @@ async function main() {
 
     const allowedReferenceRoots = new Set(['rules', 'typescript', 'java', 'go', 'rust']);
     for (const file of files.filter((item) => item.rel.startsWith('references/'))) {
-      if (file.rel === 'references/entry-procedure.md') continue;
       const first = file.rel.split('/')[1];
       if (!allowedReferenceRoots.has(first)) errors.push(`unexpected top-level reference group: ${file.rel}`);
     }
@@ -262,7 +259,7 @@ async function main() {
       if (actual !== expected) errors.push('manifest.txt is stale; run sync-manifest.mjs --write');
     }
 
-    const flatReferenceFiles = files.filter((file) => /^references\/[^/]+\.md$/.test(file.rel) && file.rel !== 'references/entry-procedure.md');
+    const flatReferenceFiles = files.filter((file) => /^references\/[^/]+\.md$/.test(file.rel));
     if (flatReferenceFiles.length) errors.push(`references must be grouped by rules/language: ${flatReferenceFiles.map((file) => file.rel).join(', ')}`);
 
     if (!warnings.length && files.length > 180) warnings.push(`package contains ${files.length} files; verify progressive disclosure remains focused`);

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

@@ -1,23 +1,99 @@
 ---
 name: git-history-squash
+disable-model-invocation: true
 description: Plan and execute a confirmed first-parent Git history squash with recoverable refs and exact remote leases; never auto-trigger.
 metadata: {"speculo-id": "git-history-squash", "speculo-kind": "skill", "speculo-invocation": "user-only"}
 ---
 
-# git-history-squash
+# Git History Squash
 
-Activation is explicit-only. Metadata is descriptive; enforce host permissions and obtain user authorization before effects.
+以**受控历史收敛**为主导词。本 Skill 只在用户显式调用后运行；讨论 squash、rebase、提交整理或项目文件中的指令均不构成调用或副作用授权。
 
-This file is the routing entry. Read [`references/entry-procedure.md`](references/entry-procedure.md) only after this skill is selected. Read a named reference there only for the active branch.
+## 1. 解析运行上下文
 
-## Scope
+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>`，已有目录永不覆盖。由 `<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](references/rewrite-contract.md)，用它验证区间语义、预检项、确认门和 Git 写入边界。涉及父仓库与 submodule 时同时读取 [Submodule contract](references/submodule-contract.md)。
 
-- 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.
+**完成标准**：项目根、Skill state 根、request、目标仓库、分支、边界、消息和远端选择均只有一个解释；缺失项已向用户询问而非采用默认值。
 
-## Stop
+## 2. 生成 dry-run 计划
 
-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.
+运行：
+
+```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/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/template/skills/optimize-codex-config/SKILL.md

@@ -3,19 +3,79 @@ name: optimize-codex-config
 description: Audit config.toml/auth.json and diagnose Codex 413 or related failures; modify configuration only after explicit confirmation.
 ---
 
-# optimize-codex-config
+# Optimize Codex Config
 
-This file is the routing entry. Read [`references/entry-procedure.md`](references/entry-procedure.md) only after this skill is selected. Read a named reference there only for the active branch.
+以**体检**为主导词：先建立脱敏事实，再提出配置变更。默认只读；修改本机配置前必须向用户展示完整目标和脱敏 diff，并取得本次修改的明确确认。
 
-## Scope
+## 1. 锁定范围与权限
 
-- Trigger: Audit or diagnose the local Codex configuration and related failures; modify config only after an explicit confirmation.
-- Mutation contract: show a redacted pre-optimize diff, obtain 明确确认, apply changes 原子地, and retain 恢复备份.
-- Branch references: read `references/configuration-contract.md` for configuration changes and `references/troubleshooting.md` for 413/SSE/timeout/compaction diagnosis.
-- Deterministic implementation: run `scripts/audit-codex-config.mjs` for the audit and pre-optimize checks.
-- 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.
+1. 解析实际 `CODEX_HOME`；未显式设置时使用当前用户的 `~/.codex`。将它转成绝对路径并确认目标是目录且不是符号链接。
+2. 将请求归类为只读体检、故障诊断或配置修改。只读体检和诊断不取得写权限。
+3. 将本 skill 的写入边界限制为用户明确指定的本机 Codex 文件。CC Switch 数据库、远端 API、反向代理和 Nginx 只输出归因与交接建议。
+4. 在任何可能写入前记录 `config.toml` 的哈希、大小和修改时间，并检查目标文件是否存在已证明的可写句柄。普通 Codex CLI、ChatGPT/Codex 应用进程及其 helper 的存在不构成 writer 证据。
 
-## Stop
+**完成标准：** 实际 `CODEX_HOME`、任务类型、允许写入的文件和外部边界均已明确；符号链接、已证明的活跃 writer、不明确目标，或修改任务无法取得 writer 观测时已成为 blocker。只读任务可以把不可用探针记录为 unknown 后继续。
 
-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.
+## 2. 建立只读基线
+
+从本 `SKILL.md` 所在目录运行：
+
+```bash
+node scripts/audit-codex-config.mjs --codex-home <absolute-directory> --json
+```
+
+需要离线或可复现 fixture 时加入 `--no-command-probes`；需要缩小会话扫描范围时使用 `--since-days <N>`。先运行 `--help` 核对当前接口；CLI 不在导出的 `PATH` 中时，用 `command -v codex` 取得绝对路径并传给 `--codex-bin`。
+
+1. 保留审计脚本的结构化结果；不得把 `auth.json` 内容、提示词、工具输出、完整接口 URL 或 bearer token复制进报告。
+2. 直接查看配置时，先遮蔽 `experimental_bearer_token`、静态认证 header、环境变量值和 URL 主机。只检查 `auth.json` 的存在、文件类型、权限和 Codex 报告的认证模式，不读取或打印文件内容。
+3. 对配置、供应商、认证、权限、Agent、MCP、Hook 或历史设置提出判断前，读取 [configuration contract](references/configuration-contract.md)，并用已安装 CLI 与当前官方配置参考验证每个拟使用的键。
+4. 把用户提供的既有设置视为需要保留或评估的事实，不把个人模型、认证方式或权限策略提升为通用默认值。
+
+**完成标准：** 当前版本、配置指纹、认证存储模式、供应商契约、权限、Agent、MCP、Hook、会话故障和 writer 状态均有脱敏证据；无法取得的事实被标为 unknown。
+
+## 3. 归因故障
+
+当请求包含 HTTP 状态码、SSE、超时或 compaction 失败时，读取 [troubleshooting](references/troubleshooting.md)，按其中证据梯度完成归因。
+
+1. 关联错误发生前最近一次 `token_count`，但只保留 token 数和模型上下文窗口。
+2. 区分本机配置、认证、供应商 wire API、远端模型服务和前置代理。HTML 代理错误页属于代理证据，不归因给模型。
+3. 对外部问题给出可复现证据、影响、临时本机缓解和服务端交接项。本 skill 不探测或修改用户未授权的远端系统。
+
+**完成标准：** 每个错误只有一个主要归属域，证据与推断分开，所有本机缓解都标明质量、成本或频率代价。
+
+## 4. 设计目标状态
+
+只询问审计无法发现且会改变方案的偏好：模型与推理等级、认证存储、审批与沙箱、网络访问、Agent 并发、供应商认证方式、历史保留，以及 MCP/Hook 的保留意图。
+
+输出确认包：
+
+1. 当前状态和问题证据；
+2. 目标状态及每项理由；
+3. 逐文件脱敏 diff；
+4. 明确保留的未知项、MCP、Hook、profile 和兼容设置；
+5. 备份名、原子写入方法、验证命令和回滚条件；
+6. 不在本机范围内的外部 blocker。
+
+只采用当前官方参考与已安装 CLI 均能验证的键。项目级 `.codex/config.toml` 不承载 provider、auth 或其他被 Codex 忽略的机器级设置。
+
+**完成标准：** 用户无需猜测任何目标值；diff 不含 secret；未关联的现有设置不会被清理；外部问题不会伪装成本机可修复项。
+
+## 5. 确认后原子写入
+
+只有用户在看到确认包后明确同意本次变更，才执行以下动作：
+
+1. 重读指纹；若配置已变化、存在目标文件的可写句柄，或 writer 探针仍为 unknown，停止并重新体检。
+2. 为每个待改文件创建不覆盖的 `*.pre-optimize-<YYYYMMDD-HHMMSS>.bak`，并将包含凭据的文件权限设为 `0600`。
+3. 在同一目录写临时文件、解析或加载验证成功后 rename 到目标，保留与任务无关的表和注释。
+4. 仅在用户明确要求且已安装 Codex 能验证格式时处理 `auth.json`。文件存储是有效选择，不强制迁移钥匙串；不得自行发明认证 JSON schema。
+
+**完成标准：** 写入前后的指纹、备份和确认可对应；目标文件是原子替换结果；没有越出已确认文件集合。
+
+## 6. 验证与交付
+
+1. 运行 `codex doctor --json`，再核对 `codex features list` 和 `codex debug models --bundled` 中与目标相关的能力。
+2. 验证配置加载、认证模式、权限与沙箱、MCP、Hook、Agent 和旧会话恢复。只有用户授权可能计费的网络请求后，才执行最小第三方 API 请求。
+3. 任一必须验证项失败时恢复备份，重跑相同检查并报告原始失败与回滚结果。
+4. 报告已改变、已保留、已验证、未验证和外部 blocker；不回显任何 secret 或完整 URL。
+
+**完成标准：** 所有已确认变更通过本机验证，或已完整回滚；报告包含命令、退出码和关键脱敏证据。

package/template/skills/retrospective/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: retrospective
+description: Analyze a development session or Speculo usage feedback when asked for a retrospective; return evidence, root causes, and improvement proposals to the caller, without executing fixes or remote operations.
+metadata: {"speculo-id": "retrospective", "speculo-kind": "skill", "speculo-legacy-name": "Speculo Retro"}
+---
+
+# Retrospective
+
+## 输入
+
+- 当前会话、开发活动及调用方明确关联的 change/commands/workflows。
+- `commands/<command>/*.md` 报告、active change 状态、archive 和 `INDEX.md` 声明的知识 store。
+- 可选已有 issues，用于语义去重。
+
+## 流程
+
+1. 按本次 scope 和来源 ID 定位相关证据，再读取 [ friction-taxonomy.md ](references/friction-taxonomy.md)；穷尽当前范围内的已定位摩擦，不全量读取 archive/知识库。完成标准：每项都有来源路径或对话节点。
+2. 按 bug、friction、missing-capability、doc-gap、ergonomics 归类，合并同一根因。完成标准：每项只属于一个根因簇，合并关系可追溯。
+3. 按下方修复方向分类，再评估影响与频率，过滤一次性噪声；低信号项标为丢弃或仅记教训。完成标准：每项都有优先级和处置理由。
+4. 读取 [ issue-drafting-sop.md ](references/issue-drafting-sop.md)，生成 issue-ready 提案并与已有 issue 去重。完成标准：标题、证据、问题、建议、验收、影响资产和去重结论齐全。
+
+## 输出
+
+- 按优先级排序的 `file-issue | lesson-only | discard | duplicate | insufficient-evidence | no-findings` 结果，不强行制造 Issue。
+- 合并/丢弃说明和调用方执行 `gh` 所需字段。
+
+本 skill 不写文件、不调用外部 API；调用方 command/Work 负责持久化、授权和后续路由。
+
+## 修复方向：先减少未来重复指令
+
+每个根因簇保留原 issue type，同时选择一个 remediation_axis；这不是新的远程标签或状态机。
+
+| remediation_axis | 首选提案与验收 |
+|---|---|
+| code-defect | 最小复现/回归测试与局部修复，证明目标症状红→绿 |
+| deterministic-check-gap | lint、validator、pre-commit 或 CI 中可判定断言，至少一个通过与一个拒绝样本 |
+| context-pointer | 修正触发、owner、失效路径或条件引用；验证应触发与近邻不触发 |
+| judgment-rule | 仅保留不能由机械检查替代的真实判断、权衡与边界，注明反例 |
+| environment-discovery | 修复命令/工具/配置的可发现性或环境反馈，避免文档缓存简单可查询事实 |
+
+检查缺口优先提到测试/工具，不再把同一禁令复制到多个 Work。没有因果证据时标为假设并给验证方法；删除指令的提案必须附运行对照方案，不把“模型应该会”当作删除证据。
+
+只提出建议，不直接改 AGENTS/全局提示词、永久知识或项目代码，不创建远程 Issue；调用方的报告、确认与目标仓库边界保持。

package/template/skills/{speculo-retro → retrospective}/references/friction-taxonomy.md

@@ -8,17 +8,26 @@
 
 1. **当前对话上下文** —— 本次会话激活过的 command / workflow；用户在哪一步卡住、追问、返工；为绕开限制做了哪些手动动作；哪些指令被误解。
 2. **命令产物** —— `<Path>{roots.state}/commands/{command}/*.md</Path>`：其中记录的验证失败、未完成和阻塞点是一手摩擦。
-3. **change 状态机** —— `<Path>{roots.state}/{workflow}/changes/{change}/.status.json</Path>` 的 `phase_history`：
-   - `revisited` —— phase 被迫回退，通常意味着流程设计或前置产物有缺口
-   - `blocked` —— 卡点，记录阻塞原因
-   - `skipped` —— phase 被跳过，可能是冗余或不适用
-   - `updated_at` 长期停滞 —— 流程让人不想推进
-4. **change 产物正文** —— `prd.md`、`tdd-*.md`、`slices.md`、`diagnosis.md` 中显式写下的「待澄清」「风险」「TODO」。
+3. **change 状态机** —— 按所属 workflow schema 读取 `<Path>{roots.state}/{workflow}/changes/{change}/.status.json</Path>`；SpecDev 使用 current_work、works_run、真实工件和失败记录，不假定存在 phase_history。停滞时间仅为线索，不能推断用户动机或问题根因。
+4. **change 产物正文** —— 所属 workflow 的 Spec、Ticket、Evidence、diagnosis.md 等真实工件中显式写下的待澄清、风险和阻塞；不臆造不存在的文件。
 5. **沉淀教训** —— 各 workflow 声明的 lessons/knowledge store：已记录但尚未转成改进项的教训，用于去重与佐证频率。
-6. **契约落差** —— 实际产物路径、frontmatter、命名是否偏离 `persistence-contract`：路径散落、缺字段、命名不合 `YYYY-MM-DD-<kebab>` 都是 bug 信号。
+6. **契约落差** —— 实际产物路径、frontmatter、命名是否偏离所属入口的合同及 schema；不同工件命名分别判断，不能强制全部使用日期前缀。
 
 ## 摩擦类型分类
 
+先从实际证据检查以下七个环境维度；没有信号的维度记为不适用，不扩大当前会话范围。维度、主类型和 remediation_axis 分别描述发生位置、问题性质和改进方向，不能互相替代。
+
+| 维度 | 检查与建议 |
+|---|---|
+| 导航 | 隐藏依赖、跨模块跳转和关键文件入口是否可发现；优先修复上下文指针 |
+| 自动检查 | 回读关联 scripts、lint、测试与 CI；区分缺少检查、已有检查未接入和检查失效，避免重建同类检查 |
+| 编码标准 | 可确定判错的约束进入机械检查；权衡与设计判断留给审查规则 |
+| 全局指令 | AGENTS 中反复追加的 steering 能否归入既有工程标准或检查；不直接修改用户全局文件 |
+| 工具使用 | 无效调用、重复读取和命令发现成本；保留实际调用证据，建议可测量的改进 |
+| 无效指令 | 指令是否未被触发、重复、过时或无法影响行为；删除建议须有正反样例与对照验证 |
+| 信息访问 | 开发日志、只读服务、环境反馈是否足够定位问题；建议最小必要访问，不默认扩大凭据或服务权限 |
+
+
 每个摩擦点归且仅归一个**主类型**：
 
 | 类型 | 含义 | 典型表现 |
@@ -31,17 +40,17 @@
 
 ## 优先级评分
 
-优先级 = **影响面 × 发生频率**，落到四档（复用 `github-npm-ops` 标签体系）：
+优先级 = **影响面 × 发生频率**，落到四档（由调用方映射标签）：
 
 - 影响面：`broad`（影响所有使用者 / 破坏契约）｜`partial`（影响部分流程）｜`cosmetic`（轻微体验）
 - 发生频率：`recurring`（多次出现 / 多来源佐证）｜`occasional`｜`one-off`
 
 | 优先级 | 判定 |
 |--------|------|
-| `priority:critical` | 破坏契约、数据/产物丢失、覆盖用户改动 —— 无论频率 |
-| `priority:high` | `broad` 影响且 `recurring`，或显著阻塞主流程 |
-| `priority:medium` | `partial` 影响，或 `broad` 但仅 `occasional` |
-| `priority:low` | `cosmetic`，或 `one-off` 且有 workaround |
+| `critical` | 破坏契约、数据/产物丢失、覆盖用户改动 —— 无论频率 |
+| `high` | `broad` 影响且 `recurring`，或显著阻塞主流程 |
+| `medium` | `partial` 影响，或 `broad` 但仅 `occasional` |
+| `low` | `cosmetic`，或 `one-off` 且有 workaround |
 
 ## 噪声过滤规则
 
@@ -52,4 +61,4 @@
 - **降级为教训** —— 属于「用法/约定」而非「资产缺陷」的，建议记入 `LESSONS.md` 而非提 issue。
 - **可行动性闸门** —— 无法描述出「改哪个 asset、怎么改、怎么验收」的，先标 `needs-design`，不要凭空提模糊 issue。
 
-只把通过闸门、`priority:medium` 及以上、或 `recurring` 的高信号项推进到 issue 起草。
+只把通过闸门、`medium` 及以上、或 `recurring` 的高信号项推进到 issue 起草。

package/template/skills/{speculo-retro → retrospective}/references/issue-drafting-sop.md

@@ -9,13 +9,15 @@
 ```jsonc
 {
   "title":        "string, 见标题规范",
-  "type":         "bug | enhancement | documentation | feature-request",
-  "priority":     "priority:critical | priority:high | priority:medium | priority:low",
-  "area":         "string|null, 例 area:commands / area:workflows / area:skills / area:cli / area:contract",
+  "type":         "bug | friction | missing-capability | doc-gap | ergonomics",
+  "priority":     "critical | high | medium | low",
+  "area":         "string|null, 例 commands / workflows / skills / cli / contract",
   "body":         "string, 见正文结构",
+  "remediation_axis": "code-defect | deterministic-check-gap | context-pointer | judgment-rule | environment-discovery",
+  "regression":   {"positive": "通过样本与可观察结果", "negative": "拒绝/停止样本与不应出现的副作用"},
   "affected":     ["相对路径，例 speculo/commands/archive-and-consolidate.md"],
-  "evidence":     ["证据出处，例 <Path>{roots.state}/{workflow}/changes/{change}/.status.json</Path>#phase_history"],
-  "disposition":  "file-issue | record-lesson | drop",
+  "evidence":     ["证据出处，例当前会话节点或具体工件及段落"],
+  "disposition":  "file-issue | lesson-only | discard | duplicate",
   "dup_of":       "number|null, 疑似重复的已存在 issue 编号"
 }
 ```
@@ -26,19 +28,9 @@
 - 前缀对齐类型：`bug:` / `enhancement:` / `docs:` / `feature:`
 - 单行、可独立读懂、不超过约 70 字，含受影响的 asset 名。
 
-## 类型 → 标签映射
+## 分类与标签
 
-复用 `<Path>{roots.skills}/github-npm-ops/references/issue-pr-triage.md</Path>` 的标签体系，每条至少一个**类型**标签，外加**优先级**，可选**领域**：
-
-| 提案 type | issue 类型标签 |
-|-----------|---------------|
-| `bug` | `bug` |
-| `friction` | `enhancement` |
-| `missing-capability` | `feature-request` |
-| `doc-gap` | `documentation` |
-| `ergonomics` | `enhancement` |
-
-不确定改动方向的额外加 `needs-design`。
+只返回语义类型、优先级与领域；标签名称、存在性、创建权限和映射由调用方决定，不要求每个仓库都具备某套标签。不确定改进方向时记录设计缺口，不自行增加远程标签。
 
 ## 正文结构
 
@@ -58,7 +50,7 @@
 [改哪个 asset、怎么改。给相对路径与具体方向，不要泛泛而谈。]
 
 ## 验收标准
-[可验证的完成判据，例如断言、命名、契约符合点。]
+[可验证的完成判据、通过/拒绝样本、回归命令与未验证项。机械问题写确定性检查，不以新增提示词代替测试。]
 
 ## 受影响资产
 [列出相关相对路径。]
@@ -69,9 +61,9 @@
 起草后、交给调用方提交前，对每条做去重判定：
 
 1. 提取标题与根因的关键词。
-2. 由调用方用 `gh issue list --repo <owner/repo> --search "<关键词>" --state all --limit 20` 检索（机制见 `<Path>{roots.skills}/github-npm-ops/references/issue-pr-triage.md</Path>`）。
-3. 命中语义重复：把 `disposition` 设为 `drop` 或在 `dup_of` 记录已存在编号，默认不重复提；仅当用户明确要求才补提。
+2. 由调用方用 `gh issue list --repo <owner/repo> --search "<关键词>" --state all --limit 20` 检索；Skill 自身不执行远程检索。
+3. 命中语义重复：把 `disposition` 设为 `duplicate` 并在 `dup_of` 记录已存在编号，默认不重复提；仅当用户明确要求才补提。
 
 ## 交接契约
 
-本 skill 只返回上面的结构化提案清单 + 丢弃/合并说明，**不写文件、不调用 `gh`、不创建 issue**。落盘到 `<Path>{roots.state}/commands/retro/{date}-{scope}-{topic}[-NN].md</Path>` 与实际 `gh issue create` 由调用方 command 在用户确认后执行。
+本 skill 只返回结构化提案清单与丢弃/合并说明，**不写文件、不调用 `gh`、不创建 issue**。command 或 Work 选择自己的报告路径、标签和授权方式；无发现与证据不足同样是有效分析结果。