Fix and enhance skills-engineering rules and validation scripts

.githooks/pre-push

@@ -5,6 +5,9 @@
 # about to be published:
 #
 # Skill-sync chain (fail-fast):
+#   0. skills-engineering/scripts/validate-skill-structure.sh — validate every
+#      SKILL.md's machine-recognizable structure (frontmatter, size, reference
+#      links, orphan references) before publishing
 #   1. skills-engineering/scripts/sync-skills.sh         — rsync ios-engineer/
 #      into ~/.claude, ~/.codex, ~/.cursor skill caches (with excludes)
 #   2. skills-engineering/scripts/sync-agent-preamble.sh — rewrite managed
@@ -33,12 +36,14 @@ ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 SYNC_SCRIPT="${ROOT}/skills-engineering/scripts/sync-skills.sh"
 PREAMBLE_SCRIPT="${ROOT}/skills-engineering/scripts/sync-agent-preamble.sh"
 VERIFY_SCRIPT="${ROOT}/skills-engineering/scripts/verify-sync.sh"
+STRUCT_SCRIPT="${ROOT}/skills-engineering/scripts/validate-skill-structure.sh"
+BEHAVIOR_SCRIPT="${ROOT}/skills-engineering/scripts/validate-skill-behavior.sh"
 MCP_SYNC="${ROOT}/sync/sync_all.sh"
 
 # Collect missing scripts upfront so user sees all issues at once
 missing_scripts=()
 if [ "${SKILL_BYPASS:-0}" != "1" ]; then
-  for s in "${SYNC_SCRIPT}" "${PREAMBLE_SCRIPT}" "${VERIFY_SCRIPT}"; do
+  for s in "${STRUCT_SCRIPT}" "${BEHAVIOR_SCRIPT}" "${SYNC_SCRIPT}" "${PREAMBLE_SCRIPT}" "${VERIFY_SCRIPT}"; do
     if [ ! -x "${s}" ]; then
       missing_scripts+=("${s}")
     fi
@@ -73,24 +78,36 @@ mcp_failures=()
 # --- skill-sync chain (preamble and verify run only if sync-skills succeeds) --
 
 if [ "${SKILL_BYPASS:-0}" != "1" ]; then
-  echo "skill-sync pre-push: syncing skills-engineering/ to local agent caches..."
-  if ! "${SYNC_SCRIPT}"; then
-    skill_sync_failures+=("sync-skills.sh")
-    echo "skill-sync pre-push: ⚠ sync-skills.sh failed." >&2
+  echo "skill-sync pre-push: validating skill structure (frontmatter/size/links/orphans)..."
+  if ! "${STRUCT_SCRIPT}"; then
+    skill_sync_failures+=("validate-skill-structure.sh")
+    echo "skill-sync pre-push: ⚠ validate-skill-structure.sh reported issues." >&2
   else
-    echo "skill-sync pre-push: rendering agent preamble blocks..."
-    if ! "${PREAMBLE_SCRIPT}"; then
-      skill_sync_failures+=("sync-agent-preamble.sh")
-      echo "skill-sync pre-push: ⚠ sync-agent-preamble.sh failed." >&2
-    fi
-
-    echo "skill-sync pre-push: verifying cache layout..."
-    if ! "${VERIFY_SCRIPT}"; then
-      skill_sync_failures+=("verify-sync.sh")
-      echo "skill-sync pre-push: ⚠ verify-sync.sh reported issues." >&2
+    echo "skill-sync pre-push: validating skill behavior/consistency (cross-skill rules, matrix, i18n)..."
+    if ! "${BEHAVIOR_SCRIPT}"; then
+      skill_sync_failures+=("validate-skill-behavior.sh")
+      echo "skill-sync pre-push: ⚠ validate-skill-behavior.sh reported issues." >&2
+    else
+      echo "skill-sync pre-push: syncing skills-engineering/ to local agent caches..."
+    if ! "${SYNC_SCRIPT}"; then
+      skill_sync_failures+=("sync-skills.sh")
+      echo "skill-sync pre-push: ⚠ sync-skills.sh failed." >&2
+    else
+      echo "skill-sync pre-push: rendering agent preamble blocks..."
+      if ! "${PREAMBLE_SCRIPT}"; then
+        skill_sync_failures+=("sync-agent-preamble.sh")
+        echo "skill-sync pre-push: ⚠ sync-agent-preamble.sh failed." >&2
+      fi
+
+      echo "skill-sync pre-push: verifying cache layout..."
+      if ! "${VERIFY_SCRIPT}"; then
+        skill_sync_failures+=("verify-sync.sh")
+        echo "skill-sync pre-push: ⚠ verify-sync.sh reported issues." >&2
+      fi
     fi
   fi
 fi
+fi
 
 # --- sync (MCP + Codex shared) ------------------------------------------------
 
@@ -122,11 +139,21 @@ if [ $((${#skill_sync_failures[@]} + ${#mcp_failures[@]})) -gt 0 ]; then
   echo "Push aborted. Your local agent caches may be in an inconsistent state." >&2
   if [ ${#skill_sync_failures[@]} -gt 0 ]; then
     echo "" >&2
-    echo "To fix skill-sync failures:" >&2
-    echo "  1. Resolve the errors above" >&2
-    echo "  2. Re-run: bash skills-engineering/scripts/sync-skills.sh" >&2
-    echo "  3. Then retry: git push" >&2
-    echo "  Or set SKILL_BYPASS=1 to skip skill-sync (emergencies only)." >&2
+    if printf '%s\n' "${skill_sync_failures[@]}" | grep -qxE "validate-skill-structure\.sh|validate-skill-behavior\.sh"; then
+      echo "To fix skill-sync failures:" >&2
+      echo "  1. A SKILL STRUCTURE or BEHAVIOR check failed (pre-sync gate). Run and fix:" >&2
+      echo "       bash skills-engineering/scripts/validate-skill-structure.sh" >&2
+      echo "       bash skills-engineering/scripts/validate-skill-behavior.sh" >&2
+      echo "  2. Once every skill PASSES, retry: git push" >&2
+      echo "  (re-running sync-skills.sh will NOT fix structure issues.)" >&2
+      echo "  Or set SKILL_BYPASS=1 to skip skill-sync (emergencies only)." >&2
+    else
+      echo "To fix skill-sync failures:" >&2
+      echo "  1. Resolve the errors above" >&2
+      echo "  2. Re-run: bash skills-engineering/scripts/sync-skills.sh" >&2
+      echo "  3. Then retry: git push" >&2
+      echo "  Or set SKILL_BYPASS=1 to skip skill-sync (emergencies only)." >&2
+    fi
   fi
   if [ ${#mcp_failures[@]} -gt 0 ]; then
     echo "" >&2

skills-engineering/.agents/composition.md

@@ -0,0 +1,48 @@
+# 多技能协同规范（块发射顺序与冲突裁决）
+
+本文件定义：当 `.agents/invocation.md` 中多个 skill 在同一轮回复里**同时命中**时，结构化输出块（block）的发射顺序与冲突裁决规则。它解决"多个全局技能都要求输出自己的块"时的歧义，是对 invocation.md"正交约束层可同时生效"的落地补充。
+
+## 1. 技能分层与角色
+
+| 层 | 技能 | 角色 | 典型产出块 |
+|----|------|------|-----------|
+| L0 问题前 | `problem-analysis` | 先审问题本身是否合理/需求是否真实 | `问题分析` 块（仅在发现偏差时） |
+| L1 平台/领域 | `ios-engineer` 等平台 skill | 领域知识与具体修法 | 领域结构化输出 |
+| L2 论证 | `logical-reasoning` (GR-010) | 自身回复的论证质量 | `逻辑链` 块（高风险判断时） |
+| L3 求真 | `epistemic-integrity` (GR-011~013) | 与外部真实的接地 | `验证锚点` 块（高风险事实时） |
+| L4 结构 | `engineering-discipline` (GR-001~008) | 输出结构与工程纪律 | 四段式 / `前置确认` / `残留风险声明` 块 |
+| L5 回答后 | `cognitive-expansion` (Tier 0/3) | 打破茧房的可带走增量 | `认知尾注` 块（门控命中后） |
+| 校准 | `ios-engineer` 认知对手模式 (Tier 2) | 反迎合/挑战用户结论 | 完整认知校准结构（见 ios-engineer `cognitive_adversary_mode.md`） |
+
+## 2. 块发射顺序
+
+同一回复中出现多个块时，**按层级由内到外、由前到后**排列：
+
+```
+[问题分析]            (L0，仅偏差时)
+  └─ 主答案 / 领域输出 (L1)
+       ├─ 逻辑链       (L2，高风险判断时)
+       ├─ 验证锚点     (L3，高风险事实时)
+       └─ 四段式/前置确认/残留风险声明 (L4，工程任务时)
+认知尾注              (L5，Tier 0 门控命中后，附于主答末尾)
+```
+
+- `cognitive-expansion` 的 `认知尾注` **永远最后一个**，且独立于主答结构（属于"回答后"层）。
+- 认知对手模式（Tier 2）与 `认知尾注`（Tier 0）**互斥不叠加**：Tier 2 命中时输出完整校准结构，不再单独写 Tier 0（避免重复，见 `cognitive-expansion` 详规）。
+- 纯执行/纯机械任务：只输出主答案，不强制任何块（L0~L4 的门控未命中即静默）。
+
+## 3. 冲突裁决
+
+当不同层的规则就"同一处内容"给出冲突要求时，按以下优先级裁决：
+
+1. **真相 > 结构**：`epistemic-integrity` 的求真要求（如"不得把未验证说成已知""给可核验把手"）优先于 `engineering-discipline` 的格式/结构要求。即：宁可放慢结构输出，也要先满足证据与置信标注。
+2. **问题 > 方案**：`problem-analysis` 发现前提错误或需求偏差时，其余层（L1~L4）必须先等问题分析结论，不得在错误前提上推进。
+3. **安全 > 一切**：`engineering-discipline` GR-001（不读/不打印/不提交机密）与"高风险 shell 前安全自检"无条件优先于任何产出效率。
+4. **最小化噪音**：当多个块可合并时合并（如四段式的"验证"段可承载 `逻辑链` 的"可证伪/缺口"字段），但不得删除任一技能要求的**必填字段**（如 GR-008 的"已覆盖/未覆盖/残留风险"三字段、IR-006 的"版本前提"块）。
+5. **门控各自独立**：每个块的"是否输出"由其自身门控决定，不因其他块输出而被抑制（除 Tier 0/Tier 2 互斥外）。
+
+## 4. 与既有规范的边界
+
+- 本文件只规定**块的顺序与冲突**，不重复各 skill 的内部规则（见各自 `SKILL.md` + `references/`）。
+- 路由/加载判定见 `.agents/invocation.md`；本文件假定相关 skill 已按 invocation.md 正确加载。
+- 工作流技能（`plan-grill` → `cross-model-review` → `auto-code-review`）是**跨多轮/跨会话**的接力，不适用本文件的"单回复块排序"，其顺序由其各自 Act 序号（Act 1/2/3）决定。

skills-engineering/.agents/invocation.md

@@ -38,7 +38,11 @@
 | 逻辑 / 推断 / 因果 / 论证 | logical-reasoning | P1 |
 | 根因 / 修复 / 安全 / 敏感信息 | engineering-discipline | P1 |
 | 第一性原理 / 深层需求 / 问题偏差 | problem-analysis | P1 |
+| 锁定计划 / 盘问 / grill me / 先别写代码 | plan-grill | P1（条件自动 + 显式；产出 PLAN.md 供 cross-model-review 接力） |
+| 对抗审查 / cross review / stress-test PLAN.md | cross-model-review | P1（接力 plan-grill；需 PLAN.md 存在） |
 | 盲区 / 邻域 / 拓展 / 带走 | cognitive-expansion | P2（回答后追加） |
 | `/auto-review` / `使用 auto-code-review` / `启动跨模型代码审查` | auto-code-review | P1（仅用户显式触发） |
 
 `auto-code-review` 不因代码生成或修改完成自动加载。默认触发只授权只读审查；只有 `/auto-review --fix` 或明确“审查并修复”才授权主 agent 修改代码。
+
+多全局技能同时命中时的块发射顺序与冲突裁决，见 `.agents/composition.md`。

skills-engineering/README.md

@@ -84,7 +84,7 @@
 - `ios-engineer/evolution/`：技能演进数据，包括 `proposals/`、`validations/`、`approvals/`、`history/`、`scenarios/`、`usage/`。
 - `scripts/`：仓库级脚本，负责同步技能、同步 Agent preamble 与同步结果校验；本地机器专属配置放在 `scripts/config.local.sh`（模板为 `scripts/config.local.sh.example`），路径由仓库根 `.gitignore` 排除，会被 sync 脚本自动 source。
 - `docs/`：各 skill 的独立使用文档，供人类阅读，不参与 Agent 运行时加载。
-- `.agents/`：`invocation.md`（多 skill 并行加载规范）和 `writing-docs.md`（文档写作规范）。
+- `.agents/`：`invocation.md`（多 skill 并行加载规范）、`composition.md`（多技能同时命中时的块发射顺序与冲突裁决）和 `writing-docs.md`（文档写作规范）。
 - `.claude-plugin/plugin.json`：Claude Code 插件清单，支持一键安装为 Claude 插件。
 - `.out-of-scope/repository-scope.md`：仓库级范围外声明（安全合规等跨 skill 通用约束）。
 - 提交/推送守卫：合并入 `ai-coding-kit` 后由仓库根的 [../.githooks/](../.githooks/) 统一管理，详见外层根 README 的「Git 钩子」章节。
@@ -400,6 +400,8 @@ bash install-hooks.sh
 
 [`.githooks/pre-push`](../.githooks/pre-push) 在推送前顺序执行（默认任一失败即中止 push）：
 
+0. `skills-engineering/scripts/validate-skill-structure.sh` —— 推送前校验全部 `SKILL.md` 的机器可识别结构（frontmatter 必填键、行数上限、本地 `references/` 引用存在性、内部链接可解析、无孤儿 reference）；任一技能结构回归即中止 push。
+0b. `skills-engineering/scripts/validate-skill-behavior.sh` —— 推送前跨技能行为/一致性校验（companion 文件齐备、各技能自有规则 ID 在 `references/` 中有定义、`.agents/invocation.md` 触发矩阵覆盖全部技能、i18n 镜像覆盖与跨技能硬链提示）；任一 FAIL 即中止 push。独立运行：`bash skills-engineering/scripts/validate-skill-behavior.sh [<skill>]`。
 1. `skills-engineering/scripts/sync-skills.sh` —— 把 `ios-engineer/` 同步到 `~/.claude`、`~/.codex`、`~/.cursor`，以及可选的 `~/Library/Developer/Xcode/CodingAssistant/codex` 和 `~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig` skill 缓存（按 `SYNC_*` 门控与排除规则）。
 2. `skills-engineering/scripts/sync-agent-preamble.sh` —— 重写各端 preamble 托管块，并按 `sync-manifest` 的 `skill:*` 生成 `.cursor/rules/*.mdc`。
 3. `skills-engineering/scripts/verify-sync.sh` —— 断言各已启用缓存只有 `SKILL.md + references/`、preamble 托管块已 tilde 化。
@@ -442,3 +444,17 @@ git push --no-verify                 # 跳过整个 pre-push（含 sync/sync_all
 - 新增 `scripts/list-skills.sh`：列出所有已注册 skill 及描述
 - 新增 `scripts/templates/epistemic-integrity.mdc.tmpl`：补齐 Cursor `.mdc` 生成链路
 - 修复 `scripts/verify-sync.sh`：补齐 `epistemic-integrity` 和 `problem-analysis` 的 preamble 检查
+
+### 3.0.1 — 2026-07-10
+
+- 新增 `scripts/validate-skill-behavior.sh`：跨技能行为/一致性校验（companion 文件齐备、自有规则 ID 在 `references/` 有定义、`.agents/invocation.md` 触发矩阵覆盖全部技能、i18n 镜像覆盖与跨技能硬链提示）；接入 `pre-push` 作为结构校验后的硬闸门。
+  - 加固（后续 review 修复）：discovery 改以"含 SKILL.md 的顶层目录"为准，使缺 companion 的新 skill 也能被捕获；规则 ID 定义校验改为**仅在本 skill 的 `references/*.md` 内**用结构化锚点（标题 `## ID` / 括号 `[ID]` / 表格 `| ID |`）匹配，不再把 SKILL.md 或 ios-engineer 的 references 并入搜索空间（原本会让检查完全失效或误兜底）。
+  - `cognitive-expansion` 补 `CE-001~013` 自有规则 ID（`SKILL.md` 声明 + `references/rule_index.md` 表格定义 + `references/examples.md` before/after 形态样本与退化标本）；使其从"纯散文规范"升为可被 `validate-skill-behavior.sh` Check 2 校验的契约，对齐 ios-engineer 的 `rule_index.md` 模式。
+  - 复查修复：SKILL.md 入口链接 `examples.md`，消除结构门禁 `validate-skill-structure.sh` 的 orphan reference（原 examples.md 从入口不可达）；`validate-skill-behavior.sh` Check 2 增加反向校验（rule_index.md 中 active 表行须被 SKILL.md 声明），使"双向一致"契约成真，并排除 ios-engineer 的 retired / 镜像 ID 误报。
+  - 复查修复（续）：Check 2 前向定义集合此前经 `DEF_TABLE` 包含所有表行，使 `| ID | retired |` 这类退役行仍可作"有效定义"，与"退役 ID 不应再出现在 SKILL.md"的生命周期约定冲突，且注释自相矛盾。改为仅以 `DEF_ACTIVE`（active 表行）填充 `defined`，删除已无用的 `DEF_TABLE`；负向测试（把某 CE 行改 `retired`）现正确触发前向 FAIL。
+  - `cognitive-expansion` 收口（P1/P2 中的 C+B）：① Tier 3 `跨域类比` 加护栏（CE-008 细化）——须机制对齐、点名被映射机制，禁陈词/换词类比，附 1 good/1 bad 例（`cognitive_expansion.md` §Tier 3 + `examples.md` 示例 2 复用同一 good 例）；② `流程保障`（预测日志/双会话/每周深潜）由契约段移入`附录`并标注"可选习惯、非门控、不计入 `validate-skill-behavior.sh` 任何 Check"，避免稀释强制部分。三处 CE-008 措辞同步，`SKILL.md`/`rule_index.md`/`cognitive_expansion.md` 一致。
+- 新增 `scripts/verify-review-setup.sh`：审查链前置自检（plan-reviews 构建产物、auto-code-review 配置、reviewer CLI 可用性）。
+- 新增 `.agents/composition.md`：多全局技能同时命中时的块发射顺序与冲突裁决。
+- `.agents/invocation.md`：触发矩阵补齐缺失的 `plan-grill` 与 `cross-model-review`，并指向 `composition.md`。
+- `cognitive-expansion` / `logical-reasoning` 及 `cognitive_expansion.md`：对 ios-engineer 的跨技能链接加"条件性"说明，消除非 iOS 环境死链风险。
+- `ios-engineer/SKILL.md`：en-US 镜像声明改为诚实的部分镜像说明（符合 GR-011）。

skills-engineering/auto-code-review/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: auto-code-review
 description: 用户显式触发的跨模型代码审查工作流。仅当用户明确说 `/auto-review`、`使用 auto-code-review`、`启动跨模型代码审查`，或明确要求“审查并修复”时使用；普通代码生成、修改完成或含糊的“看看代码”不自动触发。默认只读审查，只有用户明确要求 `--fix` 或“审查并修复”才允许主 agent 修改代码。
-locale: zh-CN
-supported_locales: [zh-CN]
+locale: auto
+supported_locales: [zh-CN, en-US]
 ---
 
 # Auto Code Review

skills-engineering/auto-code-review/i18n/en-US/references/agent_brief.md

@@ -0,0 +1,53 @@
+# auto-code-review Agent Invocation Guide
+
+## One-Line Description
+
+User-explicitly-triggered cross-model code review; read-only by default; main agent may fix only when `--fix` is explicitly specified.
+
+## When to Invoke
+
+- Invoke: `/auto-review`, `use auto-code-review`, `start cross-model code review`.
+- Invoke with fix authorization: `/auto-review --fix`, `review and fix`.
+- Do NOT invoke: normal code generation/modification completed, pure Q&A, vague "take a look at the code".
+
+## Key Behaviors
+
+1. Read `SKILL.md` and `references/auto_code_review.md` in full.
+2. Confirm explicit trigger exists in the current session; distinguish `review-only` vs `review-and-fix`.
+3. Load `env/review.json`, `.auto-review-config.json`, `AUTO_REVIEW_*`; configuration does NOT substitute user authorization.
+4. Confirm review scope: precise changes from the current request; otherwise ask the user to choose staged or worktree.
+5. Recall historical reviews first, then invoke the reviewer in read-only mode.
+6. `review-only` only triages, reports, and archives — no code modifications.
+7. `review-and-fix` allows the main agent to fix and re-review, up to 3 rounds.
+8. After archiving, best-effort execute sync + merge.
+
+## When NOT to Invoke
+
+- Normal code generation or modification completed.
+- User has not explicitly requested the auto-code-review workflow.
+- `AUTO_REVIEW_ENABLED=false`.
+
+## Configuration Options
+
+Priority: `env/review.json` → `.auto-review-config.json` → `AUTO_REVIEW_*`.
+
+| Environment Variable | Default | Meaning |
+|---|---|---|
+| `AUTO_REVIEW_ENABLED` | `true` | Capability switch; does NOT mean current request is authorized |
+| `AUTO_REVIEW_REVIEWER` | auto-select | Single reviewer |
+| `AUTO_REVIEW_REVIEWERS` | auto-select | Reviewer list |
+| `AUTO_REVIEW_MAX_ROUNDS` | `3` | Maximum rounds for `review-and-fix` |
+| `AUTO_REVIEW_ALLOW_SELF_REVIEW` | `false` | Whether single-model fallback is allowed |
+
+Reference template: `env/review.json.example`.
+
+Archive contains `QUESTION.md`, `RESPONSE.md`, `REVIEW-LOG.md`, `diff.patch`, and `raw/`.
+
+## Permission Boundaries
+
+- Reviewer is ALWAYS read-only.
+- `/auto-review` does NOT authorize the main agent to write files.
+- `/auto-review --fix` authorizes the main agent to fix issues within the current review scope.
+- `AUTO_REVIEW_ENABLED=true` only means the capability is available; it is NOT persistent authorization.
+
+Plan review still uses `cross-model-review`.