Enhance configuration management and synchronization across platforms

.githooks/README.md

@@ -0,0 +1,39 @@
+# .githooks
+
+Git 钩子目录，通过 `install-hooks.sh` 注册为仓库的 `core.hooksPath`。
+
+## 安装
+
+```bash
+bash install-hooks.sh
+```
+
+会将 `core.hooksPath` 指向此目录，启用以下守卫。
+
+## pre-commit — 规则变更必须绑定治理记录
+
+拦截对以下文件的未治理变更：
+- `skills-engineering/ios-engineer/SKILL.md`
+- `skills-engineering/ios-engineer/references/*.md`
+
+如果这些文件被 staged，同一个 commit 必须包含对应的 proposal 和 approval 记录。
+
+## pre-push — 推送前强制同步并校验
+
+推送前顺序执行：
+1. `sync-skills.sh` — 同步 skill 到各 Agent 目录
+2. `sync-agent-preamble.sh` — 重写 preamble 托管块
+3. `verify-sync.sh` — 校验同步结果
+4. `sync_all.sh` — 同步 MCP 配置到所有平台
+
+任一步骤失败则阻止推送。
+
+## 紧急绕过
+
+```bash
+SKILL_BYPASS=1 git commit -m "..."   # 跳过 skill 治理检查
+SKILL_BYPASS=1 git push              # 跳过 skill-sync 段
+git push --no-verify                 # 跳过所有 hooks
+```
+
+绕过仅限紧急修复，需在 commit message 中说明原因。

.githooks/pre-push

@@ -16,9 +16,8 @@
 #
 # MCP-sync:
 #   4. sync/sync_all.sh                                   — sync MCP server
-#      definitions to Cursor / Codex / Claude / Xcode, plus the CODEX SHARED
-#      block from env/codex/shared.toml, plus Claude Code env from
-#      env/claude/settings.shared.json.
+#      definitions from env/mcp/*.json plus platform configs from
+#      env/platforms/*.json to Cursor / Codex / Claude / Xcode.
 #
 # Any failure aborts the push.
 #

.github/CODEOWNERS

@@ -0,0 +1,13 @@
+# iOS Engineer Skill — 核心治理文件
+skills-engineering/ios-engineer/SKILL.md            @i-stack/core
+skills-engineering/ios-engineer/references/          @i-stack/core
+skills-engineering/ios-engineer/scripts/             @i-stack/core
+skills-engineering/ios-engineer/evolution/           @i-stack/core
+
+# 技能工程基础设施
+skills-engineering/scripts/                          @i-stack/core
+env/platforms/                                       @i-stack/core
+
+# CI / 治理自动化
+.github/workflows/                                   @i-stack/core
+.githooks/                                           @i-stack/core

.github/workflows/deploy-docs.yml

@@ -0,0 +1,53 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main, feature_3.0.0]
+    paths:
+      - 'docs/**'
+      - 'package.json'
+      - '.github/workflows/deploy-docs.yml'
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build VitePress
+        run: npm run docs:build
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/hardcoded-paths.yml

@@ -0,0 +1,42 @@
+name: Check Hardcoded Paths
+
+on:
+  pull_request:
+  push:
+    branches: [main, feature_*]
+
+concurrency:
+  group: hardcoded-paths-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  hardcoded-paths:
+    name: Check hardcoded paths
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Scan for hardcoded personal paths
+        run: |
+          echo "Scanning committed files for hardcoded personal paths..."
+          RESULT_FILE=$(mktemp)
+          trap 'rm -f "$RESULT_FILE"' EXIT
+
+          find . -type f \
+            -not -path './.git/*' \
+            -not -path './node_modules/*' \
+            -print0 | while IFS= read -r -d '' f; do
+              matches=$(grep -In '/Users/' "$f" 2>/dev/null | grep -v '/Users/you/' | grep -v '/Users/YourName/' || true)
+              if [ -n "$matches" ]; then
+                echo "::error file=$f::Hardcoded personal path found"
+                echo "$matches"
+                echo "VIOLATION" >> "$RESULT_FILE"
+              fi
+          done
+
+          if grep -q "VIOLATION" "$RESULT_FILE" 2>/dev/null; then
+            echo ""
+            echo "::error::Hardcoded personal paths detected. Replace with placeholders like '~/path/to/your/project' or '/Users/you/...'"
+            exit 1
+          fi
+          echo "No hardcoded personal paths found"

.github/workflows/validate.yml

@@ -0,0 +1,49 @@
+name: Validate Skills
+
+on:
+  pull_request:
+    paths:
+      - 'skills-engineering/ios-engineer/**'
+  push:
+    branches: [main, feature_*]
+    paths:
+      - 'skills-engineering/ios-engineer/**'
+
+concurrency:
+  group: validate-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    name: Validate ios-engineer
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: skills-engineering/ios-engineer
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update -qq
+          sudo apt-get install -y -qq ripgrep ruby > /dev/null
+
+      - name: Validate Rule IDs
+        run: bash scripts/validate_rule_ids.sh
+
+      - name: Validate Scenario Specs
+        run: bash scripts/validate_scenario_specs.sh
+
+      - name: Audit Reference Freshness
+        run: |
+          STALE_MONTHS=12 CRITICAL_MONTHS=18 bash scripts/audit_ref_freshness.sh
+
+      - name: Validate Usage Ledger
+        run: bash scripts/validate_usage_ledger.sh
+
+      - name: Run full skill evolution validation
+        run: |
+          SKIP_SNAPSHOT_CONSISTENCY=1 \
+          SKIP_BEHAVIOR_VALIDATION=1 \
+          bash scripts/validate_skill_evolution.sh

.gitignore

@@ -3,13 +3,17 @@
 # skills-engineering: local machine sync config (see scripts/config.local.sh.example)
 skills-engineering/scripts/config.local.sh
 
-# env/: local secrets and platform config. Copy env/config.json.example and fill in tokens.
-env/config.json
+# env/: only secrets.json is gitignored.
+# env/mcp/*.json and env/platforms/*.json are committed (use ${VAR} references, no real secrets).
+# User only needs to create env/secrets.json from env/secrets.json.example.
+env/secrets.json
 
 *__pycache__*/
+.analysis_output/
 
 .cursor/
 .codex/
 .claude/
-docs/
-skills-engineering/ios-engineer/evolution/usage
+node_modules/
+skills-engineering/ios-engineer/evolution/usage/*
+!skills-engineering/ios-engineer/evolution/usage/usage.jsonl

CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to ai-coding-kit will be documented in this file.
+
+---
+
+## [3.0.0] — 2026-07-05
+
+### Added
+- **i18n 分层**: SKILL.md 英文元指令 + en-US 治理层镜像（rule_index / cognitive_adversary_mode / self_evolution），IR-001 从"强制中文"改为"语言匹配用户输入"
+- **CI 自动验证**: `.github/workflows/validate.yml` 在每次 PR / push 时自动校验 Rule IDs、Scenario Specs、Ref 新鲜度、Usage Ledger、演进流水线，并扫查硬编码路径
+- **CODEOWNERS**: ios-engineer 核心文件自动指定 reviewer
+- **CONTRIBUTING.md**: 贡献指南（proposal 驱动演进、翻译贡献、平台支持新增）
+
+### Changed
+- **IR-001 语义变更**: 从"始终使用简体中文"→"输出语言与用户输入语言一致"
+
+---
+
+## [2.0.0] — 2026-02-15
+
+### Added
+- skills-engineering 模块：Agent Skill 多平台统一同步（Claude Code / Codex CLI / Cursor / Gemini CLI / CodeBuddy / Continue / Cline / Xcode）
+- ios-engineer skill：完整的 iOS 工程规则体系（Swift / SwiftUI / UIKit / 并发 / 测试 / 迁移），含 40+ 规则 ID 和自演进机制
+- 5 个全局工程技能：工程纪律、认知拓展、真值接地、论证纪律、问题分析
+- sync 模块：MCP 配置同步引擎，从单一数据源渲染到 8 个平台原生格式
+- env 模块：统一配置数据源（secrets + MCP + 平台）
+- rag-gateway：TypeScript / Fastify 通用 RAG 网关（OpenAI 兼容 API）
+- Git hooks：pre-commit 规则变更治理 + pre-push 同步校验
+
+---
+
+## [1.0.0] — 2025-10-01
+
+### Added
+- 初始版本：MCP 配置同步核心引擎
+- 基础平台支持（Cursor / Claude Code）
+- env/ 配置分层（secrets.json + mcp/ + platforms/）

CONTRIBUTING.md

@@ -0,0 +1,110 @@
+# 贡献指南
+
+感谢你对 ai-coding-kit 的关注！本文档说明如何参与贡献。
+
+---
+
+## 开发环境
+
+```bash
+git clone https://github.com/i-stack/ai-coding-kit.git
+cd ai-coding-kit
+cp env/secrets.json.example env/secrets.json
+# 编辑 env/secrets.json 填入你的 API keys
+```
+
+运行验证：
+
+```bash
+cd skills-engineering/ios-engineer
+bash scripts/validate.sh
+```
+
+---
+
+## 贡献 Reference（新增 / 修改知识条目）
+
+ios-engineer 采用**提案驱动**的演进流程，所有对 reference 或 SKILL.md 的变更必须先创建提案：
+
+```bash
+# 1. 创建提案骨架
+bash skills-engineering/ios-engineer/scripts/create_skill_proposal.sh \
+  "feat: 新增 CarPlay 适配参考"
+
+# 2. 编辑 evolution/proposals/<id>.md，填写动机、变更范围、影响分析
+
+# 3. 实现变更（修改 references/ 或 SKILL.md）
+
+# 4. 运行完整验证
+bash skills-engineering/ios-engineer/scripts/validate_skill_evolution.sh
+
+# 5. 提交 PR，proposal 和变更一起提交
+```
+
+### Reference 编写规范
+
+- 每个 reference 文件首行必须包含 `<!-- last-verified: YYYY-MM -->`
+- 所有规则 ID（如 `IR-001`、`ROUTE-005`）必须在 `rule_index.md` 中注册
+- 禁止跨文件重复定义核心概念（unique ownership 原则）
+- 退役术语不得在任何 reference 中重新出现（retired term regression 检查）
+
+---
+
+## 翻译贡献
+
+1. 在 `i18n/en-US/references/` 创建与 `references/` 同名的文件
+2. 保持结构一致，标题层级不变
+3. 规则 ID（如 `IR-001`）不翻译，保持原样
+4. 代码示例中的注释可以翻译
+
+---
+
+## 新增平台支持
+
+1. 在 `env/platforms/` 添加平台配置 JSON
+2. 更新 `skills-engineering/scripts/sync-skills.sh` 添加新的同步目标
+3. 更新 `skills-engineering/scripts/verify-sync.sh` 添加校验逻辑
+4. 更新根目录 `README.md` 列出新平台
+
+---
+
+## Commit 规范
+
+```
+<type>: <简短描述>
+
+type 取值：
+  feat:     新功能
+  fix:      修复
+  ref:      新增/修改 reference
+  evolve:   技能演进（proposal → implementation → promotion）
+  chore:    工程基础设施（CI / 脚本 / 配置）
+  docs:     文档
+```
+
+示例：
+```
+ref: 新增 CarPlay 场景适配 reference
+evolve: promote v74 — 修复 concurrency reference 中版本前提缺失
+chore: CI 加入 rule_id 双向一致性检查
+```
+
+---
+
+## PR 要求
+
+- 涉及 `SKILL.md` 或 `references/*.md` 的变更必须绑定 `evolution/proposals/` 中的 proposal
+- CI 必须全部通过（Rule IDs / Scenario Specs / Ref Freshness / Snapshot Consistency）
+- 至少 1 位 [CODEOWNERS](./.github/CODEOWNERS) 批准
+
+---
+
+## 治理体系速览
+
+| 组件 | 文件 | 用途 |
+|------|------|------|
+| 规则注册表 | `rule_index.md` | 所有规则 ID 的单一事实来源 |
+| 自进化 | `self_evolution.md` | 技能演进闭环流程 |
+| Usage Ledger | `usage_ledger.md` | 任务命中观测 |
+| 认知对手 | `cognitive_adversary_mode.md` | 反 AI 迎合机制 |
+| 验证场景 | `validation_scenarios.md` + `evolution/scenarios/` | 回归验证集 |