# 上游能力正向匹配

在[必要前置](../SKILL.md#0-必要前置完成后才编写-spec)核实后、规格方案和执行计划定型前使用。先看上游能提供什么，再匹配本次场景，最后检查拟建实现。目标是形成可执行的采用决定，不建设第二套能力目录或自动调度平台。

## 1. 常见场景与候选提供方

从本次实际场景定位候选。下表提供常见检索方向；项目已有工具和已声明上游优先核对，新的共性处理再查询相关公共能力。具体支持范围、入口和成熟度以提供方当前选定版本为准。

| 候选提供方 | 主动寻找的使用场景 | 规格阶段应读的事实 |
| --- | --- | --- |
| 项目现有测试入口及 test-performance-optimizer | 多文件测试、重复安装、进程初始化、聚焦与全量分层、浏览器资源竞争、发布 Hook 再次验证 | package/build 配置、正式测试入口、已有日志、资源与失败传播合同 |
| release-skill | 发布准备及生成顺序、公开快照、泄漏检查、冻结与批准、Hook 执行及结果复用、宿主安装消费、部分失败恢复、发布后核验与收尾 | 对应版本能力说明、项目发布配置、选中单元、Hook 命令与输入、授权状态 |
| Foundation | 路径／原子写／临时空间／进程、合同校验、规范化与摘要、资源闭包、报告渲染与来源绑定、宿主投影、词元计量、身份／许可证等共享处理 | 精确版本公共能力目录及命中项合同、采用计划、消费者现有调用；不仅搜索 Harness 层 |
| artifact-graph 与 artifact-chain-assistant | 需求查重与承接、现行制品定位、实现上下文、影响关系、追溯与版本锁、制品校验、已有生成入口、本轮 SPEC 与相关制品双向覆盖 | 当前 CLI 帮助、项目类型／路径配置、相关制品与本轮基线、现有计划与维护入口 |
| skill-family-docs 与 skill-family-doc-render | 公开知识站首次生成、正文刷新、纯渲染、导航模板、来源覆盖、阅读与交互验收 | 已安装技能导览、精确渲染包版本、站点配置、页面清单、源正文和现有文档发布接线 |

只读能力目录和配置即可排除的类别，不运行工具。存在相关场景时，即使 SPEC 没有提到提供方名字，也要完成正向匹配。当前项目未安装不等于上游不存在。

## 2. 从供给匹配场景，再回查方案

1. **确定来源。** 区分项目锁定、当前安装、正式发布与工作树候选版本。优先读取来源可核验的公共包、目录或技能说明。需要最新能力时再核对发布源；不能导入相邻开发工作树来证明可采用。
2. **正向展开。** 从提供方公共能力的意图、输入输出与失败边界出发，定位本次使用场景。对无匹配的关键词再查相关能力分类与公共入口，不能把一次文本未命中当不存在。
3. **核对责任。** 把场景拆为共享处理、领域解释、平台限制和验收。Foundation 可以拥有报告格式、绑定、扫描或投影等通用处理，产品仍决定业务值与规则；不能一标“领域脚本”便整体排除。
4. **比较接线。** 阅读现有调用方与配置，判断直接采用还是薄适配。注明薄层具体负责哪些参数、策略或领域转换，不再包一层全功能接口。
5. **回查拟建项。** 将 SPEC 的脚本、验证器、生成器和编排步骤与命中能力对照，移除重复计划；需要替换既有路径时明确退出对象。不得借此清理未触及的存量。

Foundation 命中项使用 `foundation-adoption-review` 核对能力 ID、成熟度、失败语义、调用方责任和采用材料。release-skill 先读 help／对应阶段技能与项目配置；制品管理先从 where-am-i 或当前 CLI 查询定位，生成或优化 SPEC 时按第 6 节完成双向覆盖核对；文档生成先读 docs-help 并区分生成模式。区分入口的实际副作用：`prepare --offline`、Hook、渲染、投影及锁刷新会写入。

## 3. 把决定写进 SPEC

至少保留以下内容，可按场景合并相同项，不要求固定表格列数：

- **场景与位置**：对应用户结果或验收项，在哪个任务、哪个生成或验证步骤使用。
- **提供方与证据**：精确版本、能力 ID 或公开命令／函数、合同或配置出处。上游没有能力 ID 时不自造。
- **采用结论**：直接采用、薄适配、领域保留、已核实不适用、上游缺口或待确认；未采用的命中项说明原因。
- **调用与所有权**：输入输出、关键参数及路径策略、唯一调用责任、项目仍需实现的语义；已有接线可引用准确章节。
- **验证与副作用**：引用什么机制证据、补什么消费测试、何时执行、什么变化要求重跑；写入或外部系统调用的具体对象与副作用。

已发现但尚未核实的候选保持待确认，不能写成“已采用”。领域保留也须给出合同不覆盖的具体语义，不以“项目特殊”作理由。SPEC 记录本轮实际采用的能力、与方案有关但未采用的候选及理由，以及影响实施的待决项。没有相关场景的检索提示无需写入正文。

## 4. 相邻能力分工

以下分工用于本次场景已经命中的候选；采用其他提供方时核对其公共合同与实际职责。

- 测试性能技能在 SPEC 阶段提供分组、并行和复用的判断方法，实际测试使用项目已有权威入口。规格引用既有选择器和执行配置，明确批次顺序、初始化成本、串行资源、失败传播、超时／清理及重跑条件。沿用未改配置即可时不重复参数清单；拟改变策略而尚未验证时，只将实验写入相应任务，不把候选当成默认执行策略。
- 核对选择器的实际调用范围及输入限制，包括隐含的全量前置检查。没有可用窄入口时如实估算成本或保留该切片待决，不改称“聚焦”、不交给执行者临时拼 runner。跨阶段复用按测试性能技能的资格条件判断；发布 Hook 还须满足 release-skill 对应版本合同，不能手写缓存替代。
- release-skill 管发布动作的准备、冻结、执行及恢复；项目提供领域生成依赖和测试。正式宿主安装消费与产品真实业务语义分别验收，不能因为安装成功就删除领域检查。
- artifact-graph 管制品关系、上下文与锁；制品正文由对应制作能力承担。图关系不能证明业务通过，也不复制为第二套任务树。本轮 SPEC 与相关制品的双向覆盖按第 6 节处置。
- skill-family-docs 管公开知识站的内容工作流，doc-render 管确定性渲染；release-skill 管发布文档受管区域和发布流程。内部 SPEC 的写作与普通风格审校、产品自己的会议 HTML，不自动等同于知识站生成。
- 名为报告、索引或绑定的脚本先拆责任再匹配 Foundation。公共报告格式不能替代产品的知识事实、业务判断和交互状态。

## 5. 冻结与交付

SPEC 完成前检查：拟实施项的能力选择是否已有事实依据，调用与生成顺序是否完整，任务是否引用这些决定，相关验证是否已经安排，本轮相关制品与 SPEC 正文是否已按第 6 节完成双向核对。依赖关系复杂度没有降低时，不通过新增清单或控制器冒充收敛。

未决项影响哪一切片，就只将该切片标为不可开始。其余独立切片照常交付。执行者可以核对实际环境、解析已选入口及填入运行参数；不能把选择提供方、改版本、自建机制或重新安排测试留到实施时动态设计。发现新事实后先修订同一 SPEC 的受影响决定，再继续，不另建能力登记表。

## 6. 本轮 SPEC 与相关制品双向覆盖

正向匹配做一次，交付前再做一次，两处使用同一套处置。只读审阅同样核对，只报告不写。不为这项核对新增脚本、注册表、覆盖账本或控制器。

按本轮需求、基线与影响关系圈定相关制品。圈定依据包括需求条目的 `carried_into`、SPEC 中的相关引用，以及图上的影响关系。只核对本轮影响范围。

复用目标项目已明确选择、来源可核验的 `artifact-graph` 与 `artifact-chain-assistant` 精确版本及其已有类型、模板和制作入口。精确版本以目标项目的权威包清单、锁文件及正式发布来源核实；不把历史示例版本当作所有项目的固定约束，也不因本机发现新版自动升级。每份文档只承担一种制品角色。完整测试报告与执行记录只作引用，不写入设计或 SPEC 正文。不生成或复制清单，不自造类型，不定固定文件数量，不发明新接口。

先读当前 SPEC、本轮需求与基线声明，列出本轮声称需要的制品，以及本轮实际发生变化的制品。

项目存在 `artifact-graph.config.yaml` 时，先核实该项目已选的精确版本及其可用的只读入口，再用以下现有命令取得关系证据。显式冻结的版本不得自行更换：

- `artifact-graph query --from <type>:<id>`
- `artifact-graph context --target <type>:<id> --mode implementation`
- `artifact-graph impact --worktree`；变更集合已知时改用 `--staged` 或 `--paths`
- 需要图健康观察时：`artifact-graph validate --root <root> --warning-only`
- 覆盖边界观察：`artifact-graph coverage --format json`
- Node API：`loadConfig`、`scanArtifacts`、`queryGraph`。`scanArtifacts` 在内存中建图，不写项目

CLI `scan`、`init` 与 `version-lock refresh` 会写项目。只读请求不得调用这些写入命令。核对本身不授权升级、安装或刷新版本锁。

配置缺失或图入口不可用时，不得把未执行的查询写成已检查。`artifact-graph check-professional --root <root> --format json` 在缺少 `artifact-graph.config.yaml` 时给出 `GRAPH_CHECK_UNAVAILABLE` / not-performed。此时报告采用缺口，引导 `artifact-chain-where-am-i` 做只读盘点；需要建立配置时再走 `artifact-chain-bootstrap`。没有图配置时，`artifact-chain-requirements` 仍可保存和查询需求。

关系证据只用来圈定候选。圈定之后必须读取 SPEC 正文与相关制品正文，判断语义是否互相覆盖。图边、ID 相同、`validate` 通过、版本锁审计通过，都不能代替语义覆盖。

匹配阶段和交付核对使用同一张处置表。只读请求可以与其他判定同时成立；同时成立时只报告，不写文件。

| 情境 | 判定 | 处置 |
| --- | --- | --- |
| 双向一致 | SPEC 要求的制品正文存在，且语义覆盖本轮要求；本轮相关制品变更已被 SPEC 承接 | 正常继续 |
| SPEC单边 | SPEC 需要某制品，但正文缺失，或必要关系未建立 | 引导用已有制作入口补充正文与关系，再进入对应审阅入口。允许改稿时写入；只读请求只报告缺口 |
| 制品单边 | 本轮相关制品已变更，SPEC 未承接该变化 | 暂停该切片，等待用户决定：纳入本轮、延期，或认定基线未变。执行者不得代为裁决 |
| 历史未变 | 制品存在，相对本轮基线内容未变 | 保留基线，不强制纳入本轮 |
| 语义不符 | 图关系或 ID 能够对应，正文未覆盖要求 | 报告语义缺口。图检查通过不视为覆盖完成 |
| 无配置 | 缺少 `artifact-graph.config.yaml`，或公开图入口因无配置而不可用 | 明确采用缺口，引导已有盘点与 bootstrap 入口，不虚构已经检查 |
| 只读请求 | 用户只要审阅 | 只报告上述结论，不写文件 |

补充缺失制品时使用已有入口，不另建制作链：

- 需求保存、查询与承接到 SPEC：`artifact-chain-requirements`
- 功能制品：`prd-feature` 的 author 与 review
- 场景制品：`scenario-script` 的 author 与 review
- 其他已配置类型：`artifact-generate` 与 `artifact-review`
- 盘点与无配置：`artifact-chain-where-am-i`；项目配置决策：`artifact-chain-bootstrap`

审阅走各入口既有闭环和 Review Result 合同。本技能只引导进入对应入口，不汇总审阅结果，不自造审阅控制器。profile 或 worker 未就绪时，按该入口的 `NEEDS_INPUT` 或等价缺口报告，不假装已经评审。

未决事项只阻断真正依赖该差异的切片。无依赖切片照常交付。文档齐全但仍有覆盖未决时，报告“文档已整理，相关任务暂不可委派”，并写明等待补充评审还是等待用户裁决。交付前必须再做一次同一套核对。风格、链接、图关系或版本锁检查通过，不能代替这次语义覆盖结论。