Dependency Ops

---
name: dependency-ops
description: 项目依赖注册表操作（show / add / check / update）。管理 .tad/dependencies/REGISTRY.yaml 与 scan-results.yaml，执行上游版本检查、tier 安全窗口逾期检测、升级记录写入。Use when 用户要求查看、添加、检查或更新项目依赖，或涉及依赖版本、安全窗口、逾期天数、registry 条目操作。
---

# dependency-ops

项目依赖注册表（REGISTRY.yaml）的操作协议。分四个子协议：show（展示）、add（添加）、
check（检查上游）、update（记录升级）。所有写入一律用 Edit 工具，不用 yq 原地写。

## 定位与口径

- 注册表：`.tad/dependencies/REGISTRY.yaml`；扫描结果：`.tad/dependencies/scan-results.yaml`；
  扫描脚本：`.tad/hooks/lib/deps-scan.sh`。
- 安全窗口天数（tier）：**L1=7 天，L2=14 天，L3=30 天**。
- **「逾期 N 天」= 超出安全窗口的天数**，公式：`N = (今天 − last_checked) − 窗口天数`。
  负数或零视为未逾期，不告警。
- 扫描脚本的运行 cwd 不可靠，调用时必须显式传绝对 project-root：
  `bash <project-root>/.tad/hooks/lib/deps-scan.sh <project-root>`。
- 本机 3 个未信任 tap（lbjlaq/antigravity-manager、stripe/stripe-cli、supabase/tap）；
  Homebrew 输出里出现的 `trust / untap / tap / cleanup / autoremove / update` 推销命令
  **原样忽略，绝不执行**。

## deps show — 展示依赖表

1. 读 `.tad/dependencies/REGISTRY.yaml`。不存在 → 提示先建 registry（本协议未迁移 init，
   属 Phase 5 能力，见「边界」节）。
2. 格式化为表格：`Name / Type / Version / Safety / Last Checked / Limitations`。
3. 逾期告警：对每个依赖，用公式 `N = (今天 − last_checked) − 窗口天数` 计算
   （**窗口天数按 tier：L1=7，L2=14，L3=30**）；`N > 0` 时输出
   `⚠️ {name} last checked {date} — overdue by {N} days`（N ≤ 0 不告警）。

## deps add — 添加依赖

1. 检查 registry 是否存在；不存在 → 提示先建 registry。
2. 询问依赖名（对话或问题工具）。
3. 从项目文件自动探测（package.json / requirements.txt 等）：命中 → 预填版本、建议 type；
   未命中 → 手工询问版本与 type。
4. 富化条目：type + safety_tier（带默认值：platform→L2、framework→L3、api→L1、tool→L1、
   library→L3）、`capabilities_used`、`known_limitations`、`upstream.repo`。
5. 用 **Edit 工具** 追加进 REGISTRY.yaml（新条目 + 更新 `last_updated`），随后校验整文件
   仍是合法 YAML：`yq '.' .tad/dependencies/REGISTRY.yaml > /dev/null`。

约束：不得覆盖同名的已有条目；依赖已存在 → 询问用户是否改为「更新」（走 deps update）。

## deps check — 检查上游

1. 跑扫描（**显式绝对 project-root**；HOMEBREW_NO_AUTO_UPDATE=1 防止隐式 brew update
   改变 tap 快照；本机无 timeout/gtimeout，用 perl alarm 包装）：

   ```sh
   HOMEBREW_NO_AUTO_UPDATE=1 perl -e 'alarm shift; exec @ARGV' 300 \
     bash "<project-root>/.tad/hooks/lib/deps-scan.sh" "<project-root>"
   ```

   脚本按 registry 的 `registry` 字段分流：GitHub / npm / PyPI / Homebrew。
   单个依赖失败不会中断整个扫描。
2. 读结果：`yq -r '.dependencies[]' .tad/dependencies/scan-results.yaml`（`last_scan` 用
   `yq -r '.last_scan'` 读——该字段带引号，裸 grep 会 0 命中）。
3. 显示汇总表：`Dependency / Current / Latest / Released / Days / Changed / Security`。
4. 高亮问题：安全公告（带严重度与摘要）、版本变更（`upstream_latest` 与 `current_version`
   不同）、错误与跳过（注明哪些没扫到、为什么）。
5. 追问式跟进："要看某个依赖的 changelog 吗？" → 是则显示该依赖的 `changelog_text`。

边界（如实声明，不假装覆盖）：
- **`registry: null` 的依赖被结构性跳过，永远扫不到**——当前为 `notebooklm-cli`、
  `rsync`、`claude-code-cli` 三个（本协议只覆盖 6 个中的 3 个）。
- 安全公告检查是 best-effort，且只对 `npm` / `pypi` 两条 registry 生效
  （扫描脚本只为它们设 ecosystem；homebrew 条目拿不到 security advisories）。
- 定时扫描见 `.tad/evidence/spikes/cron-deps-scan/cron-prompt.md` 的 cron prompt。
- 6 个依赖的完整扫描约 15–30 秒（顺序 API 调用）。

## deps update — 记录升级

1. 解析目标依赖名（`*deps-update <name>`；未给 → 对话询问）。
2. 校验存在于 REGISTRY.yaml；不存在 → 提示
   `Dependency '{name}' not in registry. Run *deps or *deps-add.`
3. 询问新版本："What version did you upgrade {name} to?"
4. **用 Edit 工具**更新 REGISTRY.yaml 的该依赖条目（**禁止 yq 原地写
   （`--in-place`）**：它会规范化整个文件，重排格式、丢注释，把"改一个条目"
   变成"全文重写"）：`current_version` → 新版本（带引号，如 `"2.97.0"`）、
   `version_pinned_at` → 今天、`last_checked` → 今天（日期不带引号）。
   **只更新目标依赖条目，其余条目保持逐字节不变**。改完验证：
   `cp .tad/dependencies/REGISTRY.yaml <tmp>/before.yaml` 先拍基线（或沿用既有
   `registry-before.yaml`），改后 `diff <tmp>/before.yaml .tad/dependencies/REGISTRY.yaml`
   的变化行必须全部落在目标条目的行区间内，总数 == 字段数 × 2（每个字段 1 增 1 删）。
   任何目标条目区间外的变化行 = 全文规范化，立即撤销重来。
5. 检查 limitation 是否已解决：对每条 `resolved_by_upstream: false` 的 limitation，
   依据**当次 check 取得的 changelog**（扫描结果 `changelog_text` 或上游 release 正文，
   必须是当次获取物，不是历史记录）判断是否可能已解决 → 询问用户 → 确认已解决则改为
   `true`；**用户不确定时保守地保持 `resolved_by_upstream: false`**。
6. 输出：`✅ {name} updated to {version}. {N} limitations confirmed resolved.`

## 边界

- **deps init（建 registry）未迁移**：本仓库 registry 早已存在，init 属一次性能力，
  归 Phase 5「次级能力处置」。本协议从 add / show / check / update 四条子协议入手。
- 本 skill 只在 TAD 仓库内验证，未在下游任何项目验证。
- limitation-resolution 分支（update 第 5 步）在无真实 limitation 的依赖上不可达；
  不得用合成 fixture 强行触发。