/spec-absorption

name: spec-absorption
description: 规范吸纳执行 Skill — 用于检查 data 最新可吸纳项、证明通用规范价值、剔除项目独有规则、输出吸纳清单、分层决策、同步消费者和验证探针；当用户说“吸纳规范 / 最新可吸纳 / 仍需吸纳 / 检查 data 是否有规范 / 开始吸纳”时使用。

Spec Absorption Skill

定位

本 Skill 承接“规范吸纳”的执行面。`spec-governance` 负责 RecordRouter、台账分流、`GovernanceGateRegistry` 和 SCV；本 Skill 负责把 PI / PF / GAP / ISSUE / 用户确认项变成可审查、可验证、可同步的吸纳方案。

执行原则：

• **吸纳 ≠ 写进 Skill/台账关闭**。若吸纳后仍可「只写正文、不挂消费者、不按流程执行」，该吸纳 **无效**，不得标 absorbed/closed。
• **先 source-root 存在性验证，再谈可吸纳**；禁止把台账 `open / pending absorption / active` 字面状态直接写成「可吸纳清单」。
• **每条 absorb 必须绑定执行面**：Owner Skill/prompt/runtime + 验证路线；并完成 `ProbeNecessityDecision`（必须探针 / 结构门禁 / 清单即可 / 禁止探针）。
• 先证明是通用规范价值，再决定是否吸纳；不得把业务项目独有规则包装成 DevCodex 通用规范。
• 先证明 DevCodex 当前消费者存在，再进入规范源修改；不得只因为某个项目出现过一次就改通用规范。
• 先分层归属，再写实现；不得把成组能力默认追加到通用 instructions、`CrossProjectLearnedGuards` 或 prompts 长清单。
• 先输出最终待确认清单（含探针决策与执行影响）；用户确认后再实施、验证、回写台账和同步部署副本。

触发语义

| 用户语义 | 必做 | |----------|------| | “检查 data 是否有可以吸纳的” | 扫描 `.devcodex/*/data/` 全命名空间，**对每条候选先跑 `SourceExistenceVerificationGate`**，再输出候选、通用性判断、跳过理由与可关账项 | | “列出仍需吸纳清单” | 执行遗漏过滤，排除已吸纳、已关闭、**source 已覆盖（ledger-stale）**、重复和项目独有项，只列最终仍需吸纳 | | “开始吸纳 / 确认执行” | 执行分层决策、消费者同步、验证探针、台账回写、报告和记忆 | | “这个也要记录 / 以后要这样” | 先交给 `spec-governance` 做 RecordRouter，再由本 Skill 判断是否进入吸纳 | | “之前都吸纳到通用规范了，重新分层” | 叠加 `HistoricalCommonNormLayeringGate`，先建逐文件矩阵 |

执行流程

1. **输入归集**：读取用户消息、相关报告、运行态台账、最新记忆和源码现状。 2. **规模路由与全命名空间扫描**：先调用 `skill-gap-analysis` 的 `ProjectArtifactScaleRoutingGate` 形成 `ScaleDecisionRecord`，再执行 `WorkspaceDataAbsorptionScopeGate` 覆盖 `.devcodex/*/data/`；大语料必须分批/checkpoint，错误 glob、超时和派生产物污染结果标 invalid/discarded。 3. **SourceExistenceVerificationGate（硬前置）**：对每条表面 open 候选，在 **source-root**（通常 `devcodex`）检索同名 Gate / Skill / schema / 探针 / 测试入口；未完成存在性验证的候选不得进入「最终可吸纳清单」。 4. **Backlog Intake 真相复核**：结合存在性结果分类为 `pure-open / residual-tail / already-fixed / misclassified`，非 `pure-open` 不得原样进入吸纳范围；`already-fixed` / 等价覆盖写入 **可关账清单**。 5. **通用性证明**：对通过存在性验证且仍为缺口的项执行 `CommonNormGeneralizationGate`。 6. **消费者证明**：对通过通用性证明的项执行 `AbsorptionCandidateConsumerProofGate`。 7. **返工价值复核**：候选声称降低返工、补复审遗漏或提升首次通过率时，执行 `ReworkReductionValueGate`；文本出现次数不能替代可执行 owner 和效果证据。 8. **可执行吸纳与探针必要性**：对拟 absorb 项执行 `ExecutableAbsorptionEffectivenessGate` + `ProbeNecessityDecisionGate`；缺执行面或「该探针却无探针计划」→ 不得进入最终 absorb 清单。 9. **分层归属**：形成 `LayeredAbsorptionDecision`，判定 `global-invariant / existing-skill-subgate / new-skill-required / docs-only / case-evidence-only / project-local / already-covered`。 10. **阶段清单**：仅输出仍需吸纳项（含探针档位与影响）+ 并列 **可关账/已覆盖** 清单；confirm 等待用户，Auto 持久化当前决定后继续。 11. **实施同步**：确认后同步 commonInstruction、Skill、promptTemplate、executionConsumer、**validationProbe（按探针决策）**、publicDocs、deployCopy；禁止只改 Markdown 正文。 12. **验证回写**：执行 targeted test、`node scripts/validate.js`、必要的 `npm test` / website / release 验证；回写 PI / PF / GAP / VL / ISSUE 状态；**无探针/无消费者的不得写 absorbed**。 13. **报告记忆**：报告必须引用候选矩阵、SourceExistence、ProbeNecessity、LayeredAbsorptionDecision、验证证据、台账状态和部署副本同步。

SourceExistenceVerificationGate

> 🔴 **防复发（2026-07-26）**：仅扫台账状态输出「可吸纳」属于控制失效。最终确认清单中每条 `commonDecision=absorb` 必须有本门禁证据；`existenceStatus=present|equivalent-covered` 时只能 `already-covered` / `already-fixed` 并进可关账清单，**禁止**再标 absorb。

每个候选在进入通用性证明 / 最终确认清单前必须填写：

| 字段 | 说明 | |------|------| | `candidateId` | PI / PF / GAP / ISSUE 编号 | | `claimedCapability` | 候选声称要新增的能力名（Gate / Skill / 矩阵 / 探针） | | `searchAnchors` | 在 source-root 检索的关键词/路径（≥1；含同名与已知近邻等价名） | | `sourceRoot` | 规范源码根，例如 `E:/Worker/devcodex` 或仓库相对路径 | | `existenceStatus` | `absent` / `partial` / `present` / `equivalent-covered` / `unverified` | | `hitEvidence` | 命中文件路径与符号（可空数组，但 `present/partial/equivalent-covered` 时至少 1 条） | | `nearNeighborCoverage` | 近邻已有能力说明；无则 `none` | | `ledgerDisposition` | `absorb-candidate` / `residual-candidate` / `close-ledger` / `defer` | | `verifiedBy` | 检索方式 + 可选生产入口测试命令与 exitCode |

判定规则：

• `existenceStatus=unverified` 或缺少 `searchAnchors` / `sourceRoot` → **阻断**，不得输出为可吸纳。
• `present` 或 `equivalent-covered` → `backlogClass=already-fixed`（或 `commonDecision=already-covered`），进入 **可关账清单**，禁止 absorb。
• `partial` → 最多 `residual-tail`；最终 absorb 只能是「补洞切片」，必须写清已有近邻与仍缺字段。
• `absent` 且检索覆盖 claimedCapability 与主要近邻名 → 才可继续 `CommonNormGeneralizationGate` 并竞逐 `pure-open`。
• 台账写 `pending absorption` 但 source 已实现 → 记 **ledger-stale**，归可关账，不得重复实施。

负向样例

| 负向样例 | 处理 | |----------|------| | 只根据 `状态：open` / `pending absorption` 列入可吸纳 | invalid：`ledger-status-only` | | 未在 source-root 检索同名 Gate 即标 pure-open absorb | invalid：`existence-unverified` | | source 已有 `EvidenceFreshnessReceiptV1` + 测试绿，台账仍 residual open 又整包吸纳 | invalid：应 `close-ledger` | | 有近邻 TTFV 却把 ProgressReportFastPath 写成「已存在」而不写 partial/absent | invalid：须区分父门禁与特化缺口 |

CommonNormGeneralizationGate

每个候选吸纳前必须先填写：

| 字段 | 说明 | |------|------| | `candidateId` | PI / PF / GAP / ISSUE / 用户确认项编号或消息锚点 | | `sourceNamespace` | 来源命名空间，例如 `.devcodex/<project>/data` | | `candidateScope` | 原始问题影响范围：单项目 / 多项目 / DevCodex 控制面 / 宿主通用 | | `generalizationEvidence` | 可泛化证据：至少包含跨工作流复用、宿主无关性、DevCodex 当前消费者或同类问题重复证据之一 | | `projectSpecificResidue` | 项目私有路径、服务名、业务名词、数据库/接口/路由局部前提、私有组织流程 | | `negativeExamples` | 明确不吸纳的反例，防止下次误收 | | `commonTrigger` | 抽象后的通用触发语义 | | `targetConsumer` | DevCodex 中真实会执行该规范的 Skill / prompt / validate / report / docs | | `decision` | `absorb / case-evidence-only / project-local / docs-only / already-covered / reject` |

判定规则：

• 只有 `generalizationEvidence` 成立且 `targetConsumer` 存在，才可进入 `absorb`。
• 存在项目私有残留时，必须先抽象成宿主/流程/消费者无关表达；抽象失败则判 `project-local`。
• 只是某个项目的目录、服务、接口、业务角色或部署习惯，不得吸纳为 DevCodex 通用规范。
• 已有同等或更强规范、Skill、prompt 和探针覆盖时，判 `already-covered`，只回写台账，不重复新增。

负向样例

| 负向样例 | 处理 | |----------|------| | `ServiceSpecRead`、`docs/services/<name>/` 服务开发读取链 | 项目或框架私有，不吸纳为 DevCodex 通用规范；可作为“先证明通用价值”的反例 | | 单个业务项目的 service / route / model / schema 命名 | `project-local`，除非证明 DevCodex 多项目 Profile/服务规范消费者需要 | | 单个库的 `cacheControl`、adapter 配置或返回值习惯 | `case-evidence-only` 或并入对应库本地规范 | | 某个项目私有数据目录、导航层级、脚本名 | 不直接进入通用层；只能抽象为“消费者同步 / 产物边界 / 验证链”类规则 |

Absorption