Enhance hooks, improve TOML generation, and add new features

.githooks/post-commit

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# post-commit: 每次提交后顺带执行 ios-engineer 的 evolution 历史 GC，
+# 将 proposals/validations/approvals/history 收敛到最近 KEEP_RECENT（默认 10）份。
+# 可通过 SKIP_EVOLUTION_GC=1 跳过；GC 失败不影响已完成的提交。
+
+set -uo pipefail
+
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+GC_SCRIPT="$REPO_ROOT/skills-engineering/ios-engineer/scripts/gc_evolution_history.sh"
+
+# 脚本不存在则跳过（保持钩子健壮）
+[ -x "$GC_SCRIPT" ] || exit 0
+
+# 允许通过环境变量跳过
+[ "${SKIP_EVOLUTION_GC:-0}" = "1" ] && exit 0
+
+if bash "$GC_SCRIPT" >/dev/null 2>&1; then
+  :
+else
+  echo "post-commit: evolution 历史 GC 执行失败（不影响已完成的提交）。" >&2
+  echo "  可手动运行排查: bash $GC_SCRIPT --dry-run" >&2
+fi
+
+exit 0

.githooks/pre-commit

@@ -5,9 +5,11 @@
 # skills-engineering/ios-engineer/references/*.md is bound to a staged
 # evolution proposal whose approval record is staged or already committed.
 #
-# Bypass: SKILL_BYPASS=1 in the environment for emergencies. Bypass usage
-# should be documented in the commit message; reflog plus the SKILL_BYPASS
-# string in the parent shell history is the audit trail.
+# Bypass modes (in order of severity):
+#   MINOR_CHANGE=1  — Skip proposal/approval for trivial changes (typos,
+#                     comments, formatting). Logs and stages minor-changes.log.
+#   SKILL_BYPASS=1  — Full bypass for emergencies. Must be documented
+#                     in commit message.
 
 set -uo pipefail
 
@@ -25,6 +27,41 @@ if [ -z "$guarded" ]; then
   exit 0
 fi
 
+# --- Minor change path: log and skip proposal requirement ---------------------
+
+if [ "${MINOR_CHANGE:-0}" = "1" ]; then
+  MINOR_LOG="${PREFIX}/evolution/minor-changes.log"
+  if ! mkdir -p "$(dirname "${MINOR_LOG}")"; then
+    echo "skill-evolution pre-commit: failed to create minor-change log directory." >&2
+    exit 1
+  fi
+  timestamp="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  reason="${MINOR_CHANGE_REASON:-pre-commit: commit message unavailable; set MINOR_CHANGE_REASON for audit context}"
+
+  if ! {
+    echo "---"
+    echo "timestamp: ${timestamp}"
+    printf 'reason: "%s"\n' "${reason//\"/\\\"}"
+    echo "files:"
+    printf '%s\n' "$guarded" | sed 's/^/  - /'
+  } >> "${MINOR_LOG}"; then
+    echo "skill-evolution pre-commit: failed to write ${MINOR_LOG}." >&2
+    exit 1
+  fi
+
+  if ! git add "${MINOR_LOG}"; then
+    echo "skill-evolution pre-commit: failed to stage ${MINOR_LOG}." >&2
+    exit 1
+  fi
+
+  count=$(printf '%s\n' "$guarded" | grep -c .)
+  echo "skill-evolution pre-commit: MINOR_CHANGE=1 — logged ${count} file(s) to ${MINOR_LOG}"
+  echo "  (No proposal/approval required for trivial changes)"
+  exit 0
+fi
+
+# --- Standard path: require proposal + approval -------------------------------
+
 staged_proposals="$(printf '%s\n' "$changed_files" | grep -E "^${PREFIX}/evolution/proposals/[0-9]{8}-[0-9]{6}-[A-Za-z0-9_-]+\.md$" || true)"
 
 if [ -z "$staged_proposals" ]; then
@@ -33,7 +70,10 @@ if [ -z "$staged_proposals" ]; then
     echo "Guarded changes:"
     printf '%s\n' "$guarded" | sed 's/^/  - /'
     echo ""
-    echo "Stage an approved evolution proposal in the same commit, or set SKILL_BYPASS=1 to bypass (emergencies only)."
+    echo "Options:"
+    echo "  1. Stage an approved evolution proposal in the same commit"
+    echo "  2. Set MINOR_CHANGE=1 for trivial changes (typos, comments, formatting)"
+    echo "  3. Set SKILL_BYPASS=1 for emergencies only"
   } >&2
   exit 1
 fi

.githooks/pre-push

@@ -28,55 +28,116 @@ set -uo pipefail
 
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 
-# --- skill-sync chain ---------------------------------------------------------
+# --- Pre-flight validation: check all required scripts exist -----------------
 
-if [ "${SKILL_BYPASS:-0}" != "1" ]; then
-  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"
+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"
+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
     if [ ! -x "${s}" ]; then
-      echo "skill-sync pre-push: ${s} missing or not executable." >&2
-      echo "Set SKILL_BYPASS=1 to bypass (emergencies only)." >&2
-      exit 1
+      missing_scripts+=("${s}")
     fi
   done
+fi
+# MCP sync is optional — it is skipped gracefully below if missing or
+# non-executable, so it is intentionally NOT part of the missing-scripts
+# pre-flight check (unlike the required skill-sync scripts above).
+
+if [ ${#missing_scripts[@]} -gt 0 ]; then
+  echo "skill-sync pre-push: missing or non-executable scripts:" >&2
+  for s in "${missing_scripts[@]}"; do
+    echo "  - ${s}" >&2
+  done
+  echo "Set SKILL_BYPASS=1 to bypass (emergencies only)." >&2
+  exit 1
+fi
 
+# --- Pre-flight validation: check secrets.json exists for MCP sync -----------
+
+SECRETS_FILE="${ROOT}/env/secrets.json"
+if [ -x "${MCP_SYNC}" ] && [ ! -f "${SECRETS_FILE}" ]; then
+  echo "sync pre-push: ⚠ env/secrets.json not found — MCP sync will run but may fail." >&2
+  echo "sync pre-push: Copy env/secrets.json.example and fill in your keys." >&2
+fi
+
+# --- Track sync results (separate arrays for targeted fix advice) -------------
+
+skill_sync_failures=()
+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
-    echo "skill-sync pre-push: sync-skills.sh failed; push aborted." >&2
-    echo "Fix the sync error, or set SKILL_BYPASS=1 to bypass (emergencies only)." >&2
-    exit 1
-  fi
-
-  echo "skill-sync pre-push: rendering agent preamble blocks..."
-  if ! "${PREAMBLE_SCRIPT}"; then
-    echo "skill-sync pre-push: sync-agent-preamble.sh failed; push aborted." >&2
-    echo "Fix the preamble error, or set SKILL_BYPASS=1 to bypass (emergencies only)." >&2
-    exit 1
-  fi
+    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
-    echo "skill-sync pre-push: verify-sync.sh reported issues; push aborted." >&2
-    echo "Fix the sync state, or set SKILL_BYPASS=1 to bypass (emergencies only)." >&2
-    exit 1
+    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
 
 # --- sync (MCP + Codex shared) ------------------------------------------------
 
-MCP_SYNC="${ROOT}/sync/sync_all.sh"
 if [ -x "${MCP_SYNC}" ]; then
   echo "sync pre-push: syncing MCP + Codex shared config to local agent configs..."
   if ! "${MCP_SYNC}"; then
-    echo "sync pre-push: sync_all.sh failed; push aborted." >&2
-    echo "Fix the sync error, or use git push --no-verify to bypass (emergencies only)." >&2
-    exit 1
+    mcp_failures+=("sync_all.sh (MCP)")
+    echo "sync pre-push: ⚠ sync_all.sh failed." >&2
   fi
 else
   echo "sync pre-push: ${MCP_SYNC} missing or not executable; skipping." >&2
 fi
 
+# --- Summary ------------------------------------------------------------------
+
+if [ $((${#skill_sync_failures[@]} + ${#mcp_failures[@]})) -gt 0 ]; then
+  echo "" >&2
+  echo "═══════════════════════════════════════════════════════════" >&2
+  echo "pre-push: SYNC FAILURES DETECTED" >&2
+  echo "═══════════════════════════════════════════════════════════" >&2
+  echo "The following steps failed:" >&2
+  if [ ${#skill_sync_failures[@]} -gt 0 ]; then
+    for f in "${skill_sync_failures[@]}"; do echo "  ✗ ${f}" >&2; done
+  fi
+  if [ ${#mcp_failures[@]} -gt 0 ]; then
+    for f in "${mcp_failures[@]}"; do echo "  ✗ ${f}" >&2; done
+  fi
+  echo "" >&2
+  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
+  fi
+  if [ ${#mcp_failures[@]} -gt 0 ]; then
+    echo "" >&2
+    echo "To fix MCP-sync failures:" >&2
+    echo "  1. Resolve the errors above" >&2
+    echo "  2. Re-run: bash sync.sh" >&2
+    echo "  3. Then retry: git push" >&2
+    echo "  Or use git push --no-verify to skip all hooks (emergencies only)." >&2
+  fi
+  echo "═══════════════════════════════════════════════════════════" >&2
+  exit 1
+fi
+
 exit 0

.gitignore

@@ -24,3 +24,4 @@ docs/.vitepress/.temp/
 skills-engineering/ios-engineer/evolution/usage/*
 !skills-engineering/ios-engineer/evolution/usage/usage.jsonl
 templates/portability-ecosystem.md
+PRD/

Formula/ai-coding-kit.rb

@@ -1,8 +1,12 @@
 class AiCodingKit < Formula
-  desc "One kit for all AI coding tools — Agent Skills, MCP sync, iOS engineering rules, and RAG gateway"
+  desc "One kit for all AI coding tools — Agent Skills, MCP sync, iOS engineering rules"
   homepage "https://github.com/i-stack/ai-coding-kit"
   url "https://github.com/i-stack/ai-coding-kit/archive/refs/tags/v3.0.0.tar.gz"
-  sha256 "" # ← fill after `brew fetch` or `shasum -a 256 v3.0.0.tar.gz`
+  # RELEASE BLOCKER: fill sha256 before merging — brew install fails with an
+  # empty checksum. Compute it with:
+  #   curl -L https://github.com/i-stack/ai-coding-kit/archive/refs/tags/v3.0.0.tar.gz \
+  #     | shasum -a 256
+  sha256 "" # ← paste result here, then remove these comment lines
   license "MIT"
   version "3.0.0"
 

README.md

@@ -65,7 +65,7 @@ bash sync.sh
 bash install-hooks.sh
 ```
 
-启用 pre-commit（规则变更治理）和 pre-push（推送前强制同步校验）。详见 [.githooks/README.md](.githooks/README.md)。
+启用 pre-commit（规则变更治理）、post-commit（evolution 历史自动 GC）和 pre-push（推送前强制同步校验）。详见 [.githooks/README.md](.githooks/README.md)。
 
 ## What is MCP?
 

env/README.md

@@ -18,7 +18,8 @@ env/
 │   ├── xcodebuild.json
 │   ├── lanhu.json
 │   ├── moonvy.json
-│   └── gateway.json
+│   ├── postgres.json
+│   └── sqlite.json
 │
 ├── platforms/                ← 平台专属配置
 │   ├── claude.json

env/mcp/postgres.json

@@ -0,0 +1,18 @@
+{
+    "name": "postgres",
+    "type": "stdio",
+    "command": "npx",
+    "args": [
+        "-y",
+        "@modelcontextprotocol/server-postgres",
+        "${postgres.connection_string}"
+    ],
+    "platforms": [
+        "claude",
+        "codex",
+        "codebuddy",
+        "gemini",
+        "cline",
+        "continue"
+    ]
+}

env/mcp/sqlite.json

@@ -0,0 +1,19 @@
+{
+    "name": "sqlite",
+    "type": "stdio",
+    "command": "npx",
+    "args": [
+        "-y",
+        "sqlite-mcp-server",
+        "--db-path",
+        "${sqlite.db_path}"
+    ],
+    "platforms": [
+        "claude",
+        "codex",
+        "codebuddy",
+        "gemini",
+        "cline",
+        "continue"
+    ]
+}

env/review.json.example

@@ -0,0 +1,7 @@
+{
+  "_comment": "auto-code-review 执行参数。复制为 env/review.json 后填写；仅在用户显式启动 /auto-review 后加载。enabled=true 只表示功能可用，不构成当前请求授权。加载优先级：env/review.json → .auto-review-config.json → AUTO_REVIEW_* 环境变量。",
+  "enabled": true,
+  "reviewers": [],
+  "maxRounds": 3,
+  "allowSelfReview": false
+}

env/secrets.json.example

@@ -25,5 +25,11 @@
     "gemini": {
         "url": "https://your-gemini-proxy.example.com",
         "key": "sk-your-gemini-api-key"
+    },
+    "postgres": {
+        "connection_string": "postgresql://user:password@localhost:5432/your_database"
+    },
+    "sqlite": {
+        "db_path": "./data/your_database.sqlite"
     }
 }

install-hooks.sh

@@ -3,6 +3,7 @@
 #
 # Registers the root .githooks/ directory with this clone:
 #   - pre-commit:  SKILL evolution-proposal guard for skills-engineering/ios-engineer/
+#   - post-commit: evolution history GC (keep latest KEEP_RECENT snapshots)
 #   - pre-push:    skill-sync chain + sync/sync_all.sh (MCP + Codex shared)
 #
 # Run this once per clone:

skills-engineering/.agents/invocation.md

@@ -39,3 +39,6 @@
 | 根因 / 修复 / 安全 / 敏感信息 | engineering-discipline | P1 |
 | 第一性原理 / 深层需求 / 问题偏差 | problem-analysis | P1 |
 | 盲区 / 邻域 / 拓展 / 带走 | cognitive-expansion | P2（回答后追加） |
+| `/auto-review` / `使用 auto-code-review` / `启动跨模型代码审查` | auto-code-review | P1（仅用户显式触发） |
+
+`auto-code-review` 不因代码生成或修改完成自动加载。默认触发只授权只读审查；只有 `/auto-review --fix` 或明确“审查并修复”才授权主 agent 修改代码。

skills-engineering/README.md

@@ -18,6 +18,7 @@
 | `problem-analysis` | 全局技能 | 问题前置分析：逻辑检验、第一性原理拆解 |
 | `plan-grill` | 工作流技能 | 需求对齐/盘问锁定计划，产出 PLAN.md（基于 grill-me） |
 | `cross-model-review` | 工作流技能 | 跨模型对抗审查 PLAN.md，自动发现 CLI（基于 grill-me-codex） |
+| `auto-code-review` | 工作流技能 | 用户显式启动的跨模型代码审查；默认只读，可显式授权修复 |
 
 本仓库同时提供三类能力：
 
@@ -59,6 +60,9 @@
 ├── epistemic-integrity/       # 真值接地技能（同构）
 ├── logical-reasoning/         # 逻辑论证技能（同构）
 ├── problem-analysis/          # 问题分析技能（同构）
+├── plan-grill/                # 需求盘问锁定计划（Act 1）
+├── cross-model-review/        # 跨模型对抗审查 PLAN.md（Act 2）
+├── auto-code-review/          # 用户显式启动的代码审查（Act 3）
 ├── scripts/                   # 仓库级脚本
 │   ├── bootstrap.sh
 │   ├── sync-skills.sh
@@ -93,7 +97,7 @@
 
 - `Codex`：需要 `~/.codex/skills/ios-engineer` + `~/.codex/AGENTS.md`。前者提供 `SKILL.md + references/`，后者负责把技能路径接入 system prompt。
 - `Claude`：需要 `~/.claude/skills/ios-engineer` + `~/.claude/CLAUDE.md`。只同步 skill 目录不足以保证自动加载。
-- `Cursor`：每个 skill 需要 `~/.cursor/skills/<skill>` + 项目内 `.cursor/rules/<skill>.mdc`（`cognitive-expansion.mdc` 由 `sync-agent-preamble.sh` 从 skill 详规生成）。`alwaysApply: true` 的 `.mdc` 负责项目内自动加载。
+- `Cursor`：每个 skill 需要 `~/.cursor/skills/<skill>` + 项目内 `.cursor/rules/<skill>.mdc`。全局纪律使用 `alwaysApply: true`；需要用户授权的工作流可提供专用模板并设为 `alwaysApply: false`（如 `auto-code-review`）。
 - `Gemini`：需要 `~/.gemini/skills/ios-engineer` + `~/.gemini/GEMINI.md`。前者提供 `SKILL.md + references/`，后者负责作为全局上下文在对话中每次自动加载。
 - `Xcode Codex`：需要 `~/Library/Developer/Xcode/CodingAssistant/codex/skills/ios-engineer` + `~/Library/Developer/Xcode/CodingAssistant/codex/AGENTS.md`。
 - `Xcode Claude`：需要 `~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/skills/ios-engineer` + `~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/CLAUDE.md`。