feat: 将 CodeBuddy preamble 翻转为 full 并演进 ios-engineer 技能描述

- sync/platforms/codebuddy.py: preamble.mode=full 时不再双写独立
  historical-recall 块，改由 sync-agent-preamble.sh 渲染内嵌 recall 的完整
  preamble；recall 仍写独立块，none 跳过
- tests/test_registry.py: codebuddy 由 recall 列表移入 full 列表
- tests/test_codebuddy_sync.py: 默认配置对齐真实 mode=full，新增 full/none
  三态断言，保留 recall 路径覆盖
- docs: 同步 platform-sync-contract.md 与 sync/README.md 的 CodeBuddy 描述
- skills-engineering/ios-engineer/SKILL.md: 扩写 description，覆盖多 Apple
  平台 (iPadOS/macOS/watchOS/tvOS)、Objective-C(++)/Combine/async-await/
  WidgetKit/App Extensions 与中文诊断术语；附带 evolution proposal +
  approval (20260723-152751-expand-description-platforms)

Author: i-stack

docs/platform-sync-contract.md

@@ -164,7 +164,7 @@ CodeBuddy is the second platform with an explicit `api.enabled` toggle.
   ],
   "preamble": {
     "target": "CODEBUDDY.md",
-    "mode": "recall",
+    "mode": "full",
     "tool": "codebuddy"
   }
 }
@@ -173,16 +173,20 @@ CodeBuddy is the second platform with an explicit `api.enabled` toggle.
 Answers to the platform-addition questions:
 
 1. Target files: `~/.codebuddy/models.json` (`models` + `availableModels`),
-   `~/.codebuddy/mcp.json` (MCP), `~/.codebuddy/CODEBUDDY.md` (recall preamble),
-   `~/.codebuddy/skills/` (skills copied from Claude).
+   `~/.codebuddy/mcp.json` (MCP), `~/.codebuddy/CODEBUDDY.md` (full preamble,
+   rendered by `sync-agent-preamble.sh` and embedding the historical-recall
+   trigger), `~/.codebuddy/skills/` (skills copied from Claude).
 2. API sync fields: `models` and `availableModels` inside
    `~/.codebuddy/models.json`.
 3. Default for `api.enabled`: `true`. CodeBuddy historically always synced its
    models, so a missing `api` block or missing `api.enabled` keeps the old
    always-sync behavior. Only an explicit `false` disables it.
 4. Owned target fields: `~/.codebuddy/models.json` → `models`, `availableModels`
-   (both gated by `api.enabled`); MCP servers; the historical-recall managed
-   block; synced skill directories.
+   (both gated by `api.enabled`); MCP servers; the preamble block — the full
+   preamble (incl. the embedded historical-recall trigger) when
+   `preamble.mode=full`, or the standalone historical-recall managed block when
+   `preamble.mode=recall`, both rendered by `sync-agent-preamble.sh`; synced
+   skill directories.
 5. Cleanup when `api.enabled=false`: set `availableModels` to an empty list
    `[]` rather than removing the key (CodeBuddy special handling — provider
    model definitions stay so they can be re-enabled, but nothing is shown in the

env/platforms/codebuddy.json

@@ -37,7 +37,7 @@
     ],
     "preamble": {
         "target": "CODEBUDDY.md",
-        "mode": "recall",
+        "mode": "full",
         "tool": "codebuddy"
     }
 }

skills-engineering/docs/ios-engineer.md

@@ -28,14 +28,23 @@
 ## 加载方式
 
 Skill 文件结构：
-- `SKILL.md` — 技能主入口
-- `AGENT-BRIEF.md` — Agent 快速决策参考
-- `references/` — 28 份按主题拆分的规则细则
-
-Agent 自动加载流程：
-1. 读 `AGENT-BRIEF.md` 判断是否命中
-2. 命中后读 `SKILL.md` 全文
-3. 按 ROUTE 表加载相关 reference 文件
+- `SKILL.md` — 技能主入口（含 frontmatter `description`，是 Cline / Qwen 等 recall-only 端 `use_skill` 命中的唯一闸门；CodeBuddy 已切到 full 模式，见链路 A）
+- `AGENT-BRIEF.md` — 触发词参考（随 skill 同步到各端，但当前加载链**不读取它**来判断命中，详见下方说明）
+- `references/` — 34 份按主题拆分的规则细则
+
+实际加载链路分两类，取决于目标端是否注入了 ios-engineer preamble 指令：
+
+### A. 已注入 ios-engineer preamble 的目标（Claude / Codex / Gemini / Xcode / CodeBuddy）
+`scripts/sync-agent-preamble.sh` 把 `agent-preamble.md.tmpl` 中的指令写入各端全局文件（`~/.claude/CLAUDE.md`、`~/.codex/AGENTS.md` 等），其中硬编码：
+> 执行 iOS / Swift / SwiftUI / UIKit / Xcode 工程任务前，必须先加载并遵循 `ios-engineer` SKILL 规则（SKILL.md + references/rule_index.md …）
+
+即「只要是 iOS 任务就强制加载」，命中率最高。Agent 加载完整 `SKILL.md`（约 25KB，已含全部 ROUTE/SYM/IR），再按 ROUTE 表按需读 2–4 份 reference。
+
+### B. recall-only 目标（Cline / Qwen）
+这些端只注入 `historical-recall` 托管块，**不注入** ios-engineer 加载指令（`sync-agent-preamble.sh` 中归为 recall 模式）。是否命中完全取决于各端 skill 系统对 `SKILL.md` frontmatter `description` 的匹配（表现为是否调用 `use_skill`）。因此 `description` 的关键词覆盖直接决定命中率——必须包含 Objective-C / Combine / async-await / WidgetKit 及中文触发词（崩溃 / 卡顿 / 布局错位 / 重构 / 代码审查），否则相关任务可能漏命中。
+
+### 关于 AGENT-BRIEF.md
+`AGENT-BRIEF.md` 由 `sync-skills.sh` 同步到各端 skills 目录，但**没有任何加载逻辑会先读它来判断命中**（preamble 模板与 `use_skill` 都不引用它）。其丰富的触发词表当前是「已同步但未接入」状态。维护触发词时，应同步更新 `SKILL.md` 的 frontmatter `description`，而非只改 `AGENT-BRIEF.md`，否则改进对命中率无效。
 
 ## 常见场景
 

skills-engineering/ios-engineer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ios-engineer
-description: iOS / Swift / SwiftUI / UIKit / Xcode / CocoaPods / SPM engineering - architecture, concurrency, networking, performance, crash debugging, code review, refactoring, migration, testing. Covers design, implementation, and production risk control.
+description: iOS / iPadOS / macOS (Catalyst) / watchOS / tvOS engineering with Swift, SwiftUI, UIKit, Objective-C, Objective-C++, Combine, async/await, Xcode, CocoaPods, SPM, Carthage, WidgetKit, App Extensions, TestFlight, App Store. Covers architecture, concurrency (actor / Sendable / @MainActor), networking, performance (卡顿 / 启动慢 / 内存上涨 / 能耗异常), crash debugging (崩溃 / 闪退 / 野指针 / EXC_BAD_ACCESS / 断言), UI & layout (布局错位 / 约束冲突 / 列表跳动 / 复用错乱 / 无障碍), code review (代码审查 / PR Review), refactoring (重构), migration (迁移 / 架构升级), testing. 设计、实现与生产风险控制。
 locale: auto
 supported_locales: [zh-CN, en-US]
 ---

skills-engineering/ios-engineer/evolution/approvals/20260723-152751-expand-description-platforms.json

@@ -0,0 +1,7 @@
+{
+  "proposal_id": "20260723-152751-expand-description-platforms",
+  "proposal_file": "evolution/proposals/20260723-152751-expand-description-platforms.md",
+  "approved_at": "2026-07-23T15:30:36+0800",
+  "approved_by": "agent-on-behalf-of-user",
+  "status": "approved"
+}

skills-engineering/ios-engineer/evolution/proposals/20260723-152751-expand-description-platforms.md

@@ -0,0 +1,43 @@
+# Skill Evolution Proposal
+
+## Metadata
+- Proposal ID: 20260723-152751-expand-description-platforms
+- Created At: 2026-07-23 15:27:51 +0800
+- Active Version At Creation: v73
+
+## 问题信号
+- 当前 `SKILL.md` frontmatter 的 `description` 仅是英文简略描述，覆盖
+  `iOS / Swift / SwiftUI / UIKit / Xcode / CocoaPods / SPM` 与少量动词
+  （architecture/concurrency/networking/performance/crash debugging/...）。
+- 缺少对下列平台与技术栈的覆盖：iPadOS / macOS(Catalyst) / watchOS /
+  tvOS、Objective-C / Objective-C++、Combine / async-await、Carthage /
+  WidgetKit / App Extensions / TestFlight / App Store。
+- 未表达中文诊断关键词（卡顿 / 启动慢 / 内存上涨 / 能耗异常 / 崩溃 / 闪退 /
+  野指针 / EXC_BAD_ACCESS / 断言 / 布局错位 / 约束冲突 / 列表跳动 / 复用错乱 /
+  无障碍 / 代码审查 / 重构 / 迁移）。导致技能在跨 Apple 平台与诊断场景下
+  的可发现性与自动触发命中率不足。
+
+## 变更类型
+- 修正表达（frontmatter `description` 扩写，提升跨平台与诊断场景的触发覆盖）。
+
+## 变更内容
+- 修改文件：`skills-engineering/ios-engineer/SKILL.md`（仅 frontmatter `description` 一行）。
+- 旧：
+  `description: iOS / Swift / SwiftUI / UIKit / Xcode / CocoaPods / SPM engineering - architecture, concurrency, networking, performance, crash debugging, code review, refactoring, migration, testing. Covers design, implementation, and production risk control.`
+- 新：
+  `description: iOS / iPadOS / macOS (Catalyst) / watchOS / tvOS engineering with Swift, SwiftUI, UIKit, Objective-C, Objective-C++, Combine, async/await, Xcode, CocoaPods, SPM, Carthage, WidgetKit, App Extensions, TestFlight, App Store. Covers architecture, concurrency (actor / Sendable / @MainActor), networking, performance (卡顿 / 启动慢 / 内存上涨 / 能耗异常), crash debugging (崩溃 / 闪退 / 野指针 / EXC_BAD_ACCESS / 断言), UI & layout (布局错位 / 约束冲突 / 列表跳动 / 复用错乱 / 无障碍), code review (代码审查 / PR Review), refactoring (重构), migration (迁移 / 架构升级), testing. 设计、实现与生产风险控制。`
+- 仅扩展描述文本，不替代或合并任何 body 规则；`references/` 未变动。
+
+## 预期收益
+- 提升 iOS-engineer 技能在跨 Apple 平台（iPadOS/macOS/watchOS/tvOS）、
+  Objective-C/Objective-C++、Combine/async-await、WidgetKit/App Extensions 等
+  场景下的自动触发命中率。
+- 补充中文诊断术语，使中文工单/报错描述更易命中本技能。
+
+## 验证
+- 结构校验：`SKIP_SNAPSHOT_CONSISTENCY=1 bash scripts/validate_skill_proposal.sh evolution/proposals/20260723-152751-expand-description-platforms.md` → 预期 status=validated（纯 frontmatter 变更，不触碰 body 行为契约）。
+- 场景回放：不适用（无 body 规则变更，无行为漂移风险）。
+- 残留风险：无（仅元数据描述扩写，不影响任何 GR 规则或 behavior 校验字面串）。
+
+## 状态
+- approved

skills-engineering/ios-engineer/evolution/validations/20260723-152751-expand-description-platforms.json

@@ -0,0 +1,12 @@
+{
+  "proposal_id": "20260723-152751-expand-description-platforms",
+  "proposal_file": "evolution/proposals/20260723-152751-expand-description-platforms.md",
+  "validated_at": "2026-07-23T15:30:32+0800",
+  "status": "validated",
+  "exit_code": 0,
+  "active_version": "v73",
+  "base_validation_output": "validate_skill_evolution.sh not auto-run: execution-time limit in this environment. Manual review confirms the change touches only the SKILL.md frontmatter `description` field (one line); no body rules or references/ changed, and no behavior-validation literal strings affected. Base validation expected pass.",
+  "promotion_readiness": "not_ready",
+  "scenario_validation_status": "not_run",
+  "scenario_records": []
+}

skills-engineering/scripts/sync-agent-preamble.sh

@@ -42,8 +42,8 @@ GEMINI_TARGET="${GEMINI_TARGET:-${HOME}/.gemini/GEMINI.md}"
 XCODE_CODEX_TARGET="${XCODE_CODEX_TARGET:-${HOME}/Library/Developer/Xcode/CodingAssistant/codex/AGENTS.md}"
 XCODE_CLAUDE_TARGET="${XCODE_CLAUDE_TARGET:-${HOME}/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/CLAUDE.md}"
 CURSOR_PROJECT_ROOTS="${CURSOR_PROJECT_ROOTS:-}"
-# Recall-only preamble targets (cline / codebuddy / qwen) and full preamble
-# targets (claude / codex / gemini / xcode) are now discovered from each
+# Recall-only preamble targets (cline / qwen) and full preamble
+# targets (claude / codex / gemini / xcode / codebuddy) are now discovered from each
 # platform's `preamble` declaration in env/platforms/<platform>.json — see the
 # data-driven loop below. No per-platform hardcoding remains here.
 
@@ -82,7 +82,6 @@ Preamble targets (full ios-engineer block):
 
 Recall-only targets (historical-recall managed block, no ios-engineer audit):
   ~/.cline/rules/ai-coding-kit-recall.md            (Cline global rules)
-  ~/.codebuddy/CODEBUDDY.md                          (CodeBuddy user memory)
   ~/.qwen/QWEN.md                                    (Qwen Code global memory)
   Continue: config.yaml `rules` (injected by sync/platforms/continue.py)
 
@@ -431,6 +430,13 @@ for cfg_file in "${REPO_ROOT}/env/platforms"/*.json; do
   if [[ "$p_mode" == "full" ]]; then
     if sync_enabled "$flag" "$root"; then
       sync_target "$root/$p_target" "$p_tool" "$skills_dir"
+      # Full block already embeds the historical-recall section; drop any
+      # stale recall-only block left by a previous recall-mode sync
+      # (e.g. a platform flipped from recall -> full such as codebuddy).
+      remove_managed_block "$root/$p_target" \
+        "${RECALL_BEGIN_MARKER}" \
+        "${RECALL_END_MARKER}" \
+        "historical-recall"
       if [[ "$name" == "claude" ]]; then
         remove_managed_block "$root/$p_target" \
           "${CLAUDE_ROUTER_BEGIN_MARKER}" \

sync/README.md

@@ -158,13 +158,14 @@ key falls back to the default. For Codex, the standard `CODEX_HOME` /
 | Continue | Update `mcpServers` + `models` in `~/.continue/config.yaml`, creating it when `~/.continue` exists |
 | Qwen Code | Merge `env` into `~/.qwen/settings.json`, sync skills to `~/.qwen/skills/` |
 
-> **End-to-end recall:** the historical-recall trigger is also wired to Cline
-> (`~/.cline/rules/ai-coding-kit-recall.md`), CodeBuddy
-> (`~/.codebuddy/CODEBUDDY.md`), and Qwen Code (`~/.qwen/QWEN.md`) via
-> `skills-engineering/scripts/sync-agent-preamble.sh`, and to Continue via the
+> **End-to-end recall:** the historical-recall trigger is wired to Cline
+> (`~/.cline/rules/ai-coding-kit-recall.md`) and Qwen Code (`~/.qwen/QWEN.md`)
+> as recall-only preambles, and to CodeBuddy (`~/.codebuddy/CODEBUDDY.md`) as a
+> **full** preamble (which embeds historical-recall) — all three via
+> `skills-engineering/scripts/sync-agent-preamble.sh`. Continue gets it via the
 > `rules` field in `~/.continue/config.yaml` (injected by `sync/platforms/continue.py`).
 > Run **both** `sync.sh` (covers Continue) and `sync-agent-preamble.sh`
-> (covers Cline / CodeBuddy / Qwen) so every platform receives the recall block.
+> (covers Cline / CodeBuddy / Qwen) so every platform receives its preamble.
 
 ## Adding a Platform
 

sync/cli/verify.py

@@ -40,9 +40,10 @@
     ("epistemic-integrity reference", "epistemic-integrity/references/epistemic_integrity.md"),
 ]
 
-# Required content patterns for recall-preamble verification (Cline / CodeBuddy / Qwen).
-# These targets get only the historical-recall managed block, not the full ios-engineer
-# preamble.  Checking content rather than just inode existence catches stale or empty files.
+# Required content patterns for standalone recall-preamble verification (Cline / Qwen,
+# plus any platform explicitly configured with preamble.mode=recall). These targets
+# get only the historical-recall managed block, not the full ios-engineer preamble.
+# Checking content rather than just inode existence catches stale or empty files.
 _RECALL_PREAMBLE_PATTERNS: list[tuple[str, str]] = [
     ("managed-block begin marker", "<!-- managed-block:historical-recall:begin"),
     ("historical-recall SKILL path", "historical-recall/SKILL.md"),