@teamix-evo/skills 0.12.0 → 0.13.0

package/src/teamix-evo-design-opentrek/rules/sidebar-spec.md

@@ -1,217 +0,0 @@
-# Sidebar 完整规格
-
-> 适用于所有 L1/L2 页面的侧边栏框架组件。Sidebar 是全局框架组件（`page-frame.json` → `frameComponents.sidebar`），所有含 Sidebar 的页面自动继承此规范。
->
-> **真相源**：
-> - 宽度/Token → [`design-tokens.json`](./design-tokens.json) → `sidebarRules`
-> - 框架继承 → [`page-frame.json`](./page-frame.json) → `frameComponents.sidebar`
-> - 品牌 Logo SVG → [`_assets/`](./_assets/)
-
----
-
-## 1. 整体容器
-
-| 属性 | 值 | 说明 |
-|------|------|------|
-| position | `fixed` | 固定定位，不随内容滚动 |
-| width | `var(--layout-sidebar-width)` (240px) | 展开态宽度 |
-| background | `hsl(var(--sidebar))` | 即 `--gray-muted` |
-| z-index | `100` | 高于内容层 |
-| display | `flex` / `flex-direction: column` | 垂直排列 header + content + footer |
-| transition | `width 0.2s ease` | 展开/收起动画 |
-
----
-
-## 2. sidebar-header 容器
-
-| 属性 | 值 | 说明 |
-|------|------|------|
-| height | 不固定（由内容撑开） | 禁止硬编码 56px 等固定高度 |
-| padding | `16px 16px 0` | 顶部 16px 保证 Logo 距页面顶边距 |
-| display | `flex` | 水平排列 Logo + 折叠按钮 |
-| align-items | `center` | 垂直居中 |
-| gap | `var(--gap-xs)` (4px) | Logo 与折叠按钮间距 |
-
----
-
-## 3. sidebar-logo 容器
-
-| 属性 | 值 | 说明 |
-|------|------|------|
-| height | `32px` | Logo 可视区域高度 |
-| display | `flex` | 内部元素水平排列 |
-| align-items | `center` | 垂直居中 |
-| overflow | `hidden` | 防止内容溢出 |
-| flex-shrink | `0` | 禁止压缩 |
-
----
-
-## 4. 品牌 SVG Logo
-
-| 属性 | 值 | 说明 |
-|------|------|------|
-| width | `154px` | 保持宽高比 404:84 |
-| height | `32px` | 与容器高度一致 |
-| viewBox | `0 0 404 84` | 原始设计稿尺寸 |
-| 来源文件 | `OP_DEV-2.svg` | 完整品牌矢量图（默认产品） |
-
----
-
-## 5. sidebar-content 区域
-
-| 属性 | 值 | 说明 |
-|------|------|------|
-| flex | `1` | 占满剩余空间 |
-| padding-top | `24px` | 导航菜单与 header 的间距 |
-| padding-bottom | `12px` | 底部留白 |
-| overflow-y | `auto` | 内容超出时可滚动 |
-
----
-
-## 6. 收起态（Collapsed）
-
-> 点击收起按钮后，侧栏从 240px 收窄至 68px，Logo 切换为纯图标，展开按钮置于 Logo 下方。
-
-### 6.1 整体布局
-
-| 属性 | 展开态 | 收起态 | 说明 |
-|------|--------|--------|------|
-| sidebar width | `240px` | `68px` | CSS 变量 `--layout-sidebar-width` 仅控制展开态 |
-| transition | — | `width 0.2s ease` | 展开/收起动画 |
-| overflow | `hidden` | `visible` | 收起态允许 flyout 溢出 |
-
-### 6.2 sidebar-header 收起态
-
-| 属性 | 值 | 说明 |
-|------|------|------|
-| padding | `16px 0 0` | 仅保留顶部间距，水平归零 |
-| flex-direction | `column` | 垂直排列 Logo + 展开按钮 |
-| align-items | `center` | 水平居中 |
-
-### 6.3 收起态 Logo
-
-| 属性 | 值 | 说明 |
-|------|------|------|
-| 来源文件 | `OP_LOGO.svg` | 仅图标（黑色圆角矩形 + 白色钻石图案），无产品文字 |
-| width × height | `30px × 30px` | 适配 68px 侧栏宽度 |
-| viewBox | `0 0 84 84` | 原始正方形画布 |
-| 切换逻辑 | 完整 Logo 隐藏 → 收起 Logo 显示 | CSS class `.collapsed-logo` 控制 |
-
-### 6.4 展开按钮
-
-| 属性 | 值 | 说明 |
-|------|------|------|
-| 位置 | Logo 正下方 | `margin-top: 8px` |
-| 尺寸 | `18px × 18px` | 与收起按钮一致 |
-| 图标 | Lucide `PanelLeftOpen` | `<path d="m14 9 3 3-3 3"/>` 方向朝右 |
-| 颜色 | `hsl(var(--muted-foreground))` | hover → `hsl(var(--gray-primary))` |
-| 展开态可见性 | `display: none` | 仅收起态显示 |
-
-### 6.5 收起/展开按钮对照
-
-| 按钮 | 图标 | 可见条件 | 位置 |
-|------|------|----------|------|
-| 收起按钮 `.sidebar-collapse-btn` | Lucide `PanelLeftClose`（箭头朝左） | 展开态 | sidebar-header 右侧（`margin-left: auto`） |
-| 展开按钮 `.sidebar-expand-btn` | Lucide `PanelLeftOpen`（箭头朝右） | 收起态 | Logo 下方居中 |
-
----
-
-## 7. 品牌 Logo 资源清单
-
-| 文件名 | 用途 | 存放路径 |
-|--------|------|----------|
-| `OP_DEV-2.svg` | 展开态完整 Logo（含 OPENTREK DEV 文字） | `rules/_assets/` |
-| `OP_LOGO.svg` | 收起态纯图标 Logo | `rules/_assets/` |
-| `OP_AI STUDIO.svg` | AI Studio 产品变体 | `rules/_assets/` |
-| `OP_AGENT RUNTIME.svg` | Agent Runtime 产品变体 | `rules/_assets/` |
-| `OP_OPS.svg` | OPS 产品变体 | `rules/_assets/` |
-| `OP_AI GATEWAY.svg` | AI Gateway 产品变体 | `rules/_assets/` |
-
-### 7.1 Logo 资源引用规则
-
-品牌 Logo **必须使用** `_assets/` 目录中的 SVG 文件，禁止使用文字占位或外部图片链接。
-
-**资源映射表**：
-
-| 产品线 | SVG 文件 | 使用场景 |
-|---|---|---|
-| AI Gateway | `_assets/OP_AI GATEWAY.svg` | AI 网关相关页面 |
-| AI Studio | `_assets/OP_AI STUDIO.svg` | AI 开发平台相关页面 |
-| Agent Runtime | `_assets/OP_AGENT RUNTIME.svg` | Agent 运行时相关页面 |
-| DEV | `_assets/OP_DEV-2.svg` | 开发者工具相关页面 |
-| OPS | `_assets/OP_OPS.svg` | 运维相关页面 |
-| 通用 Logo | `_assets/OP_LOGO.svg` | 产品线未明确时使用 |
-
-**引用方式**：
-- 生成页面时，根据当前产品线从上表选择对应 SVG
-- Logo 放置在 Sidebar 品牌区域（顶部），与产品名文字并排
-- **必须以 inline SVG 方式嵌入**（直接将 SVG path 写入 JSX/HTML），禁止用 `<img src>` 或外部引用
-- 仅截取 SVG 的**图标部分**（viewBox `0 0 84 84`），文字（OPENTREK / AI GATEWAY）由 Sidebar 右侧 `<span>` 双行渲染
-
-**inline SVG 实现要求**：
-- 外层 `<rect>` 使用 `fill="currentColor"`，内层图案使用 `fill="white"` — 容器通过 `text-foreground` 类控色，自动适配主题
-- `<clipPath>` 的 `id` 必须全局唯一（按页面命名，如 `opai-logo-clip-{page-name}`），避免同 DOM 多个 SVG id 冲突
-- Logo 组件尺寸：`size-8`（32×32px），与 §3 sidebar-logo 容器 `height: 32px` 对齐
-- path 数据必须来自 `_assets/` 中对应 SVG 文件的真实内容，禁止简化或自绘近似图形
-
-**禁止项**：
-- ❌ 使用纯文字模拟 Logo（如用 div + font-weight:bold 模拟品牌标识）
-- ❌ 使用 Lucide/其他图标库图标占位（如 Layers、Diamond 等）
-- ❌ 使用外部 URL 引用 Logo
-- ❌ 使用非 `_assets/` 目录的图片资源
-- ❌ 自绘简化 SVG path 代替真实 Logo（即使视觉近似也不允许）
-- ❌ 多个页面使用相同的 clipPath id（会导致渲染冲突）
-
----
-
-## 8. Sidebar Footer 用户信息区域
-
-> 侧边栏底部固定的用户身份展示区域。
-
-| 属性 | 值 | 说明 |
-|------|------|------|
-| padding | `12px 12px 16px 24px` | 展开态内边距 |
-| display | `flex` | 水平排列 |
-| align-items | `center` | 垂直居中 |
-| gap | `var(--button-gap)` (8px) | 元素间距 |
-
-### 8.1 头像（sidebar-avatar）
-
-| 属性 | 值 | 说明 |
-|------|------|------|
-| 尺寸 | `28px × 28px` | 固定圆形 |
-| border-radius | `50%` | 圆形 |
-| background | `hsl(var(--sidebar-active))` | 与菜单激活态背景一致 |
-| font-size | `var(--font-size-base)` (12px) | 头像内文字 |
-| font-weight | `600` | 半粗体 |
-| 内容 | 用户姓名**最后一个字** | 如「小王」→ 显示「王」 |
-
-### 8.2 用户名（sidebar-username）
-
-| 属性 | 值 | 说明 |
-|------|------|------|
-| font-size | `var(--font-size-lg)` (14px) | 用户名字号 |
-| font-weight | `var(--font-weight-medium)` (500) | 中等字重 |
-| color | `hsl(var(--sidebar-item))` | 与菜单项文字颜色一致 |
-| overflow | `hidden` + `text-overflow: ellipsis` | 超长截断 |
-| white-space | `nowrap` | 禁止换行 |
-| 默认值 | `小王` | 占位用户名 |
-
-### 8.3 更多按钮（sidebar-more）
-
-| 属性 | 值 | 说明 |
-|------|------|------|
-| 尺寸 | `28px × 28px` | 正方形点击区域 |
-| border-radius | `var(--radius-sm)` (4px) | 微圆角 |
-| 图标 | 三点竖排（MoreVertical） | `<circle cx="12" cy="5/12/19" r="2"/>` |
-| color | `hsl(var(--muted-foreground))` | hover → `hsl(var(--gray-primary))` |
-| hover background | `hsl(var(--sidebar-hover))` | 悬停底色 |
-
-### 8.4 收起态 Footer
-
-| 属性 | 值 | 说明 |
-|------|------|------|
-| padding | `12px 10px 16px` | 收窄内边距 |
-| justify-content | `center` | 居中显示头像 |
-| 用户名 | `display: none` | 隐藏 |
-| 更多按钮 | `display: none` | 隐藏 |

package/src/teamix-evo-upgrade/SKILL.md

@@ -1,431 +0,0 @@
----
-name: teamix-evo-upgrade
-description: |
-  Help the user adopt token renames in `.teamix-evo/.upgrade-hints/tokens-<ts>.json` AND component source upgrades in `.teamix-evo/.upgrade-staging/{ui,biz-ui}-<ts>/` after `teamix-evo update` / `teamix-evo tokens update` / `teamix-evo switch` / `teamix-evo ui upgrade` / `teamix-evo biz-ui upgrade`. Read each hint or staging manifest, scan the project for usages or compare current vs incoming source, propose codemod / file-replace diffs, apply only after explicit user approval, then archive processed inputs.
-  TRIGGER when: user references `.teamix-evo/.upgrade-hints/`、`.teamix-evo/.upgrade-staging/`、`tokens-*.json` hint files、`ui-*` or `biz-ui-*` staging directories、phrases like "处理 token 改名"、"应用 codemod"、"扫一下 legacy token"、"升级 token 引用"、"更新 token 名"、"组件升级"、"ui-staging"、"biz-ui staging"、"apply ui staging"、"apply biz-ui staging"、"应用组件升级"、"apply token rename codemod"、"adopt token rename hints"、"scan for legacy tokens"、"token rename upgrade"、"component source upgrade"、"review ui staging diff"、"token 治理"、"tokens diagnose"、"tokens treat"、"治理计划"、".treatment-plan.md"、"baseline 锁定"、"token 反哺"、"清理 token 违规"、"token cleanup"、"lint baseline"、"降违规"、"全部治理"; AI sees output of `teamix-evo update` / `teamix-evo tokens update` / `teamix-evo switch --apply` / `teamix-evo ui upgrade` / `teamix-evo biz-ui upgrade` mentioning `💡 token rename hint:` or `staging at .teamix-evo/.upgrade-staging/...` and the user wants to follow up; AI sees output of `teamix-evo init` showing token-discipline ESLint warnings and the user wants to clean up; user opens any `.teamix-evo/.upgrade-hints/tokens-*.json` or any file under `.teamix-evo/.upgrade-staging/{ui,biz-ui}-*/` or `.teamix-evo/.treatment-plan.md`.
-  SKIP: any other lifecycle work — `init` / `update` orchestration / variant switch itself / install / uninstall / generating staging (defer to teamix-evo-manage); pure visual or design changes (defer to teamix-evo-design-<variant>); any code authoring unrelated to the rename / staging window (defer to teamix-evo-code-<variant>); refuse to auto-apply — never write source code without explicit per-file user confirmation.
-  Coordinates with: teamix-evo-manage (manage drives the upgrade flow that emits hints + staging; this skill consumes the resulting files).
----
-
-# teamix-evo-upgrade
-
-## 安装方式
-
-本 skill 是 **lifecycle 工具型 skill**（消费 `.upgrade-hints/` + `.upgrade-staging/` 的通用工作流，跨 variant 共用，不携带任何业务内容），manifest 里声明 `scope: "global"`。**推荐全局安装一次**：
-
-```bash
-npx teamix-evo skills add teamix-evo-upgrade --scope global
-```
-
-`skills init`（项目级自举）与 `npm create teamix-evo` **不会**自动装本 skill —— bulk 模式按 scope 自动跳过（ADR 0033）。如果用户在项目级显式 `skills add teamix-evo-upgrade --scope project`，CLI 给出「推荐 global」warning 但仍装入（用户自负责），代价是后续 IDE 会同时识别全局与项目两份副本。
-
-与 [`teamix-evo-manage`](../teamix-evo-manage/SKILL.md) 同属 lifecycle 工具，分工：manage 负责 orchestration（init / update / switch / 触发 staging 生成），本 skill 负责 staging / hints 的逐文件 hard-gate apply。
-
-This skill consumes two complementary upgrade artefacts the CLI produces during upgrades and the consumer must adopt by hand under the ADR 0019 (project-upgrade-flow) **frozen-on-add boundary** (after first-time install via `npm create teamix-evo` / `teamix-evo init` / `ui add`, the CLI never overwrites existing files under `src/components/{ui,business}/**`; upgrades go through staging instead of in-place rewrites):
-
-1. **Token rename hints** — `.teamix-evo/.upgrade-hints/tokens-<ts>.json` (variable-level rewrites under `src/**` + `tokens/tokens.overrides.css`).
-2. **Component source staging** — `.teamix-evo/.upgrade-staging/{ui,biz-ui}-<ts>/` (per-component file replacements under `src/components/{ui,business}/**`, see ADR 0040 component-source-layer-upgrade-flow).
-
-Both flows share the same shape (discover → read → propose → hard-gate confirm → archive); they only differ in the artefact they consume. Token-rename details are in part A, component-source details are in part B.
-
-# Part A — Token rename adoption
-
-## What is a hint file
-
-When `teamix-evo tokens update` bumps a variant version that ships a `renames` log, or `teamix-evo switch --apply` lands on a new variant whose history contains renames, the CLI writes a single JSON file:
-
-```
-.teamix-evo/
-└── .upgrade-hints/
-    └── tokens-2026-06-12T03-15-00-000Z.json
-```
-
-Schema v1 payload (every field is required except `description` per rename):
-
-```json
-{
-  "schemaVersion": 1,
-  "ts": "2026-06-12T03:15:00.000Z",
-  "package": "tokens",
-  "trigger": "update",
-  "fromVariant": "opentrek",
-  "toVariant": "opentrek",
-  "fromVersion": "0.5.0",
-  "toVersion": "0.6.5",
-  "renames": [
-    {
-      "sinceVersion": "0.6.0",
-      "from": "--color-old",
-      "to": "--color-new"
-    },
-    {
-      "sinceVersion": "0.6.5",
-      "from": "--space-x",
-      "to": "--space-h",
-      "description": "horizontal axis rename"
-    }
-  ]
-}
-```
-
-> `trigger` is `"update"` for version-bump hints and `"switch"` for variant-switch hints. Both consume the same way — only the framing line differs.
-
-## Workflow (5 steps, never skip step 4)
-
-### 1 · Discover
-
-List every hint file under `.teamix-evo/.upgrade-hints/`. Sort newest-first by filename (the `tokens-<fs-ts>.json` ts is filesystem-safe and lexically chronological).
-
-```bash
-ls -1 .teamix-evo/.upgrade-hints/tokens-*.json 2>/dev/null
-```
-
-If the directory is missing or empty, tell the user:
-
-> 当前没有待处理的 token rename hint。这通常意味着最近一次 `tokens update` / `switch` 没有跨过 rename 节点；你可以继续做你原本的事。
-
-### 2 · Aggregate
-
-Read each hint and aggregate the `renames` arrays into a single `from → to` map. When two hints rename the same token (rare — usually means a token was renamed twice across versions), the **newest hint wins** and the older mapping is discarded (treat the chain as resolved).
-
-Surface a one-line summary per hint to the user:
-
-> `tokens-…06-12T03-15-00-000Z.json` · update · opentrek 0.5.0 → 0.6.5 · 2 renames
-
-### 3 · Scan
-
-For each `from` token, run a project-wide search across the consumer-owned surface (never read `node_modules/` or `dist/`). The exact glob set depends on which token shape the rename targets:
-
-| `from` shape                                  | Where to search                                                            | Tooling          |
-| --------------------------------------------- | -------------------------------------------------------------------------- | ---------------- |
-| CSS variable (`--color-old`)                  | `src/**/*.{ts,tsx,js,jsx,css,scss,md,mdx}` + `tokens/tokens.overrides.css` | grep / Grep tool |
-| Tailwind class fragment (e.g. `bg-color-old`) | `src/**/*.{ts,tsx,jsx}` + `index.html`                                     | grep             |
-| Token JSON path (`color.old`)                 | `tokens/**/*.json` if any                                                  | grep             |
-
-Explicitly exclude:
-
-- `node_modules/**`、`dist/**`、`build/**`、`.next/**`
-- Anything under `.teamix-evo/snapshots/**` (those are restore points, not live code)
-- The hint file itself
-
-For each occurrence collect: file path, 1-based line number, the matched line.
-
-### 4 · Propose & ask (HARD GATE)
-
-For every `from → to` rename, show a diff hunk and **ask the user per file** before touching it. Use this template:
-
-```
-─── tokens/tokens.overrides.css (1 occurrence) ───
-- 12 |   color: var(--color-old);
-+ 12 |   color: var(--color-new);
-
-─── src/components/Banner.tsx (3 occurrences) ───
-- 18 |   className="text-[var(--color-old)]"
-+ 18 |   className="text-[var(--color-new)]"
-…
-
-应用这些修改？(y / n / per-file)
-```
-
-`per-file` lets the user pick file-by-file. Default to **no** if the user is silent. **Never auto-apply.** This is the entire reason the rename pipeline exists — ADR 0019 frozen boundary.
-
-If the user declines a particular file, record it in your reply (`保留：src/legacy/old-page.tsx — 用户选择不替换`) so they can come back to it later.
-
-### 5 · Archive processed hints
-
-After (and only after) the user has either accepted or explicitly skipped every rename in a hint file, **move the hint into the archive subdirectory** so subsequent runs don't re-prompt:
-
-```bash
-mkdir -p .teamix-evo/.upgrade-hints/.processed
-mv .teamix-evo/.upgrade-hints/tokens-<ts>.json .teamix-evo/.upgrade-hints/.processed/
-```
-
-Tell the user the file moved and that they can `git diff` to review the rewrites + the hint move in one shot.
-
-> If the user wants to **defer** an entire hint (not just per-file skip), leave it in place and tell them they can re-run this skill later.
-
-## Edge cases
-
-| Situation                                                       | Response                                                                                                                  |
-| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| Hint file fails JSON parse / wrong schemaVersion                | Print the file path + the parse error; **do not** delete it. Suggest the user inspect or run `teamix-evo restore --list`. |
-| `from` token literally not found in `src/**`                    | Tell the user the rename is "已经无影响" and ask whether to archive the hint anyway.                                      |
-| Multiple hint files pending                                     | Process newest-first one hint at a time — never batch across hints (keeps the diff small and the user in control).        |
-| User says "全部接受" / "apply all"                              | Still show every diff before applying. Bulk-confirm is fine, **silent apply is not**.                                     |
-| Project has no `src/` (library / monorepo root)                 | Ask the user which directory to scan; default to `packages/*/src` if a `pnpm-workspace.yaml` is present.                  |
-| User asks to handle an old hint that's already in `.processed/` | Read it from `.processed/`, re-run scan, and let the user decide whether to apply again or remove it permanently.         |
-
-## What this skill is NOT
-
-- **Not** a CLI command — there is no `teamix-evo upgrade`. The CLI emits hints + staging; this skill consumes them.
-- **Not** a token authority — only consumes the rename log declared by the upstream tokens pack (registry `TokensVariantEntry.renames`).
-- **Not** a refactor robot — diff-then-confirm is mandatory, the user owns every byte under `src/**`.
-- **Not** the place to discuss new token names or design decisions — those flow through the design skill.
-
-# Part B — Component source upgrade
-
-When `teamix-evo update` (auto-staging step), `teamix-evo ui upgrade [id]`, or `teamix-evo biz-ui upgrade [id]` runs, the CLI compares the consumer's installed component source against the latest upstream package contents and writes a **staging directory**:
-
-```
-.teamix-evo/.upgrade-staging/
-└── ui-2026-06-12T12-00-00-000Z/
-    ├── meta.json                       # UpgradeStagingManifest
-    ├── button/
-    │   ├── current.tsx                  # what is on disk now
-    │   └── incoming.tsx                 # alias-rewritten upstream source
-    └── …
-```
-
-> **v1 note** — CLI does **not** pre-render `diff.unified.patch`. The schema's `diffRelPath` field is reserved for a future v2 emitter; today this skill diffs `current.tsx` against `incoming.tsx` on the fly (B4).
-
-The CLI **never writes** into `src/components/{ui,business}/**` — frozen boundary, ADR 0019 (project-upgrade-flow) + ADR 0040 (component-source-layer-upgrade-flow). This skill is the only path to land staged changes.
-
-## Staging manifest payload (schema v1)
-
-```json
-{
-  "schemaVersion": 1,
-  "ts": "2026-06-12T12:00:00.000Z",
-  "package": "ui",
-  "trigger": "ui-upgrade",
-  "fromVersion": "0.7.0",
-  "toVersion": "0.8.0",
-  "lineage": "teamix-evo",
-  "summary": {
-    "total": 4,
-    "byRisk": { "unchanged": 1, "upgradable-medium": 2, "risky": 1 }
-  },
-  "entries": [
-    {
-      "id": "button",
-      "category": "ui",
-      "current": {
-        "target": "src/components/ui/button.tsx",
-        "hash": "sha256:…",
-        "sourceLineage": "teamix-evo"
-      },
-      "incoming": {
-        "sourceVersion": "0.8.0",
-        "hash": "sha256:…",
-        "relPath": "button/incoming.tsx"
-      },
-      "diff": {
-        "riskLevel": "upgradable-medium",
-        "hints": ["new export: ButtonGroup"],
-        "filesChangedCount": 1
-      }
-    }
-  ]
-}
-```
-
-`riskLevel` values (from ADR 0040 §D3 component-source-layer-upgrade-flow):
-
-| level               | meaning                                                              | suggested handling                  |
-| ------------------- | -------------------------------------------------------------------- | ----------------------------------- |
-| `unchanged`         | hash identical — nothing to do                                       | skip silently                       |
-| `upgradable-low`    | single file, no new/removed exports or cva variants                  | batch confirm                       |
-| `upgradable-medium` | new exports / new cva variants / multi-file                          | per-file confirm                    |
-| `risky`             | removed exports / removed cva variants / props rename                | discuss each, surface hints         |
-| `breaking`          | upstream removed the entry entirely                                  | flag explicitly, never auto-replace |
-| `foreign`           | file exists in `src/` but no upstream / no installed manifest record | leave untouched, ask for intent     |
-
-## Workflow (5 steps, never skip step 4)
-
-### B1 · Discover
-
-```bash
-ls -1d .teamix-evo/.upgrade-staging/{ui,biz-ui}-*/ 2>/dev/null | sort -r
-```
-
-If the directory is missing or empty:
-
-> 当前没有待应用的组件升级 staging。请先跑 `teamix-evo update` / `teamix-evo ui upgrade [id]` / `teamix-evo biz-ui upgrade [id]` 生成。
-
-### B2 · Read manifest & frame the opening line
-
-Parse `meta.json`. Pick the opening message based on `lineage`:
-
-| lineage         | opening line template                                                                                                                                                                                                             |
-| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `teamix-evo`    | `检测到 X 个组件，其中 Y 个有变化（unchanged=A, upgradable-low=B, medium=C, risky=D, breaking=E）。准备逐个 review。`                                                                                                             |
-| `mixed`         | `检测到 Z 个 teamix-evo 组件 + W 个未登记组件（foreign=F）。先处理可升级项，最后与你商量 foreign 组件去留。`                                                                                                                      |
-| `shadcn-native` | `你当前是 shadcn 原生安装（未使用 teamix-evo 的资产）。升级前建议先迁移到 teamix-evo 谱系（run 「teamix-evo ui init」重新安装），或者手动对齐调谐表。是否继续详细对比？` (CLI 这种情况不会生成 staging，但用户可能手工走到这一步) |
-| `custom-only`   | (CLI skip 了，不会出现在 staging 中 — 若出现是异常，请提示用户检查)                                                                                                                                                               |
-
-### B3 · Group by risk
-
-Iterate `entries` and bucket by `riskLevel`:
-
-- **`unchanged`** — just announce "以下组件未变，跳过" (list ids on one line).
-- **`upgradable-low`** — ⤵️ HARD GATE：仍然逐个展示 diff + y/n，禁止合并为一次性批量确认。速度优先时可缩短 diff 显示（只展示 hints 摘要），但每个组件必须独立确认。
-- **`upgradable-medium`** — walk one-by-one with a short hint summary, ask y/n/per-file (see B4).
-- **`risky`** — force per-component review; spell out every `hints[]` entry verbatim before showing the diff.
-- **`breaking`** — do **not** offer auto-replace. Tell the user upstream removed the entry, ask if they want to delete the local file or keep it as a custom component (likely a re-naming — cross-check `removedExports`).
-- **`foreign`** — list separately ("以下组件不在 manifest 中，可能是你手工添加的"), ask whether to register, delete, or leave alone.
-
-> **分级原则（B0）**：每个 risk level 必须独立分组展示，不得将不同 risk level 的组件混在同一批次提问。即使用户要求「全部应用」，也必须按 risk level 分组逐个展示。
-
-### B4 · Propose & ask (HARD GATE)
-
-For each non-unchanged entry the user has agreed to consider, render the diff with **the same template as Part A step 4** but use file replacement instead of inline rewrite. Read `current.tsx` + `incoming.tsx` and compute the diff on the fly (v1 does not pre-render `diff.unified.patch` — if the entry's `diff.diffRelPath` is set in a future schema version, prefer that file as the source of truth).
-
-```
-─── src/components/ui/button.tsx · risk=upgradable-medium · hints: new export: ButtonGroup ───
-@@ -1,3 +1,5 @@
- export const Button = (props: any) => null;
-+
-+export const ButtonGroup = (props: any) => null;
-
-应用？(y / n / per-file)
-```
-
-Application = **copy `incoming.tsx` over the file at `current.target`**, atomically. Do not partial-merge — the staging is whole-file.
-
-**Never auto-apply.** If the user is silent, default to no.
-
-⚠️ HARD GATE：即使用户说 "全部接受" / "apply all"，**仍然必须逐文件展示 diff**（每个组件一屏），用户看完后才写入。禁止将多个组件的 diff 合并展示或静默批量应用。
-
-If a file's `riskLevel` is `breaking` and the user opts to delete the file, do that explicitly with a confirmed `rm` command — not silently.
-
-### B5 · Archive staging
-
-After every entry has either been applied or explicitly skipped:
-
-```bash
-mkdir -p .teamix-evo/.upgrade-staging/.processed
-mv .teamix-evo/.upgrade-staging/<dir> .teamix-evo/.upgrade-staging/.processed/
-```
-
-Tell the user the directory was archived and that `git diff` will show every accepted file replacement plus the staging move in one shot.
-
-If the user wants to **defer** the entire staging (not per-entry skip), leave it in place — they can re-run this skill later.
-
-## Edge cases (component source)
-
-| Situation                                                              | Response                                                                                                                                                           |
-| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `meta.json` parse error / wrong schemaVersion                          | Print the path + parse error; **do not** delete it. Suggest `teamix-evo ui upgrade` re-run or `teamix-evo restore --list`.                                         |
-| `current.tsx` differs from `entry.current.target` on disk              | The user edited locally since CLI generated staging. Show both diffs (your edits vs incoming), let them merge by hand; do not silently overwrite.                  |
-| User passes `--apply` to a CLI upgrade command                         | The CLI itself rejects with frozen-boundary guidance. Re-route them here.                                                                                          |
-| Multiple staging directories pending                                   | Process newest-first one staging at a time — never batch across staging dirs (different `fromVersion/toVersion`, different baseline).                              |
-| User says “全部接受” / “apply all”                                     | Still show every diff before applying. Bulk-confirm is fine, **silent apply is not**.                                                                              |
-| `lineage=mixed` with `foreign` entries                                 | After upgradable-\* are processed, walk foreign entries one-by-one and ask: register (out of scope here — redirect to `teamix-evo ui add <id>`), delete, or leave. |
-| User asks to handle an old staging dir that's already in `.processed/` | Read the manifest from `.processed/`, re-render diffs, decide whether to re-apply or remove permanently.                                                           |
-
-# Part C — Token treatment pipeline
-
-After `teamix-evo init` lands tokens + ESLint rules, the project often has pre-existing token violations (hardcoded colors, raw Tailwind scales, etc.). The CLI provides a **diagnose → treat → reflect → baseline-lock** pipeline to systematically clean them up. This skill guides the user through it.
-
-> **Coordinates with**: Part A (token rename adoption) handles _rename_ hints from upstream version bumps; Part C handles _project-internal_ violations detected by ESLint rules.
-
-## When to trigger
-
-TRIGGER when: user references "token 治理"、"tokens diagnose"、"tokens treat"、"治理计划"、".treatment-plan.md"、"baseline 锁定"、"token 反哺"、"清理 token 违规"、"token cleanup"、"lint baseline"、"降违规"、AI sees output of `teamix-evo init` showing token-discipline ESLint warnings and the user wants to follow up.
-
-SKIP: rename hints (Part A), component source upgrades (Part B), design decisions (defer to design skill).
-
-## C1 · Diagnose
-
-Run the diagnosis to understand the current violation landscape:
-
-```bash
-npx teamix-evo tokens diagnose
-```
-
-This produces `.teamix-evo/.treatment-plan.md` — a tiered treatment plan classifying violations into:
-
-| Phase            | Description                                                    | Automation |
-| ---------------- | -------------------------------------------------------------- | ---------- |
-| L1-structure     | Token file structure issues (via `tokens audit`)               | audit      |
-| L2-format        | Color format normalisation (`hsl()` → CSS v4)                  | full-auto  |
-| L3-semantic-auto | Tailwind scale → semantic tokens                               | full-auto  |
-| L3-semantic-semi | Arbitrary values → tokens (AI-guided)                          | semi-auto  |
-| L3-manual        | Requires human judgment (radius, border, dark mode)            | manual     |
-| reflect          | High-frequency color literals → project-level token candidates | analysis   |
-
-Present the plan overview to the user and ask which phases they want to tackle now.
-
-## C2 · Treat (automated codemods)
-
-For full-auto phases (L2 + L3-auto), run the treatment pipeline:
-
-```bash
-# Dry-run first (recommended)
-npx teamix-evo tokens treat
-
-# Apply changes
-npx teamix-evo tokens treat --apply
-
-# Apply + lock baseline
-npx teamix-evo tokens treat --apply --lock-baseline
-```
-
-The pipeline executes 4 codemods in order:
-
-1. `hsl-to-v4` — HSL function → CSS v4 color syntax
-2. `hex-to-token` — hardcoded hex → semantic token reference
-3. `tw-scale-to-semantic` — raw Tailwind color scale → semantic class
-4. `space-to-gap` — space utility → gap utility
-
-After execution, a treatment report is generated at `.teamix-evo/.treatment-reports/<timestamp>.md` showing per-rule before/after deltas.
-
-### Workflow
-
-1. **Always dry-run first** — show the user the match counts and ask for confirmation
-2. Show the delta table from the report
-3. If the user approves, re-run with `--apply`
-4. Ask whether to lock the baseline (`--lock-baseline`)
-
-## C3 · Semi-auto treatment (AI-guided)
-
-For `L3-semantic-semi` violations (`no-arbitrary-tw-value`):
-
-1. Read the treatment plan's L3-semi section for the list of violations
-2. For each violation, read the file context and suggest the closest semantic token
-3. Present a diff hunk per file (same template as Part A step 4)
-4. **HARD GATE** — never auto-apply; get per-file confirmation
-
-## C4 · Reflect (token 反哺)
-
-After automated treatment, remaining `no-color-literal` violations often reveal project-specific colors not covered by the design system. Suggest the user run reflect analysis:
-
-1. Scan remaining violations and cluster by color value + frequency
-2. Present a table of candidates (color → suggested token name → occurrence count → files)
-3. Colors appearing ≥ 3 times are candidates for project-level tokens
-4. Guide the user to add chosen tokens to `tokens/tokens.overrides.css`
-5. After adding tokens, re-run `tokens treat` to pick up the new mappings
-
-## C5 · Baseline lock
-
-Once the user is satisfied with the treatment level:
-
-```bash
-npx teamix-evo tokens treat --apply --lock-baseline
-```
-
-This writes `.teamix-evo/tokens-baseline.json` — a snapshot of current violation counts. Future `tokens treat` runs will compare against this baseline.
-
-**CI integration**: add to `package.json` scripts:
-
-```json
-{
-  "scripts": {
-    "lint:baseline": "teamix-evo tokens treat --lock-baseline && git diff --exit-code .teamix-evo/tokens-baseline.json"
-  }
-}
-```
-
-If violations exceed the locked baseline, CI fails — preventing regression.
-
-## C6 · Edge cases
-
-| Situation                                         | Response                                                                   |
-| ------------------------------------------------- | -------------------------------------------------------------------------- |
-| No ESLint config / teamix-evo rules not installed | Tell the user to run `teamix-evo init` first to set up the lint rules.     |
-| No `src/` directory                               | Ask which directory to scan; default to `packages/*/src` in monorepo.      |
-| Codemod not found                                 | Skip gracefully; the pipeline only runs available codemods.                |
-| User wants to skip a phase                        | Respect the choice; only run requested phases.                             |
-| Baseline already exists                           | Show current vs baseline comparison before re-locking.                     |
-| Treatment report shows 0 delta                    | All violations are either semi-auto or manual; guide user to C3/C4.        |
-| User says "全部治理"                              | Run diagnose → treat --apply → reflect in sequence, but confirm each step. |