/spec-governance

name: spec-governance
description: 规范治理生命周期 — 意图驱动记录、RecordRouter 分流、SCV 规范变更验证；规范吸纳执行细节由 spec-absorption 承接

Spec Governance Skill

定位

本 Skill 是规范治理生命周期的集中规则源，负责把“记录规范问题”和“规范变更验证”收口为统一链路；规范吸纳的候选扫描、通用性证明、消费者证明和实施执行由 `spec-absorption` 承接：

发现 -> Intent Detection -> Ambiguity Guard -> RecordRouter -> Ledger Write -> Upgrade Check -> Verification

原则：

• AI 负责语义判断、上下文归因、多意图拆分和模糊表达澄清。
• 规则负责安全底线、CP 状态、台账格式、路径落点和 SCV 阶段要求。
• 工具负责文件存在、测试结果、部署同步、active-root 泄漏和 validate 探针。

记录意图识别

`PostAssessmentGovernanceIntakeGate`：每条非空用户消息都先登记一个**中性的待评估候选**，但候选不等于治理命中。AI 必须在完成合理性评估、项目现实扩展和上下文归因后，才判断是否存在治理记录意图；关键词、固定短语或正则只能帮助定位证据，不能作为候选分类、写台账或跳过评估的权威依据。普通问答也必须形成 `record.none` 的受控评估结果，而不是靠“未命中关键词”静默绕过。

| 规范化意图 | 触发含义 | 默认目标 | |------------|----------|----------| | `record.violation` | 已有明确规则，但 AI 未执行或执行错 | `data/violations.md` | | `record.spec-defect` | 规范缺失、冲突、过窄、外部假设失效或拦截滞后 | `data/pending-fixes.md` | | `record.process-improvement` | 用户提出更优执行策略，AI 验证后可泛化 | `data/process-improvements.md`（优化清单，PI） | | `record.pending-issue` | 已确认但不阻断当前任务，适合后续批次治理 | `data/pending-issues.md` | | `record.audit-gap` | 审计/validate/Hook 未发现本该发现的问题 | `data/gap-registry.md` | | `record.none` | 普通解释、需求整理、报告整理，不是治理记录 | 不写台账 | | `record.ambiguous` | 指代不清或可能误写台账 | 先澄清 |

置信度规则

| 置信度 | 条件 | 处理 | |--------|------|------| | 高 | 用户表达明确，且上下文证据支持唯一分类 | 直接分流并说明依据 | | 中 | 主意图明确，但存在副意图或升级可能 | 先处理主意图，列出副意图 | | 低 | “记录这个”等指代不清，或目标台账不唯一 | 不写台账，先澄清 |

每次候选评估必须输出结构化 `GovernanceIntakeDecision`：`候选锚点`、`评估结论`、`泛化范围`、`现有规范状态`、`规范化意图`、`置信度`、`依据`、`目标台账`、`写入要求`、`写入证据`、`skipEvidence`。未适用字段必须显式写 `N/A + reason`，不能省略后让 Hook 猜测。

ContextualCandidateSet

• 候选集合按消息锚点持久化，至少保存 `id/sourceDigest/phase/verificationState`；新一轮消息不得覆盖上一轮未终结候选。
• 主阶段必须保留 `detected → assessed → generalized → routed → write-observed → acknowledged` 的有序历史；`record.none` 可在 challenge 通过后由 routed 进入 acknowledged，`uncertain/record.ambiguous` 必须停在 assessed，缺写入证据的实质意图必须停在 routed。禁止省略中间语义/证据阶段直接终结。
• 每个实质 intent state 必须保存 `targetLedger/claimedIds/observationIds/status`；复合候选逐项验证，不能只在 candidate 顶层保留一个总状态。
• 同一未终结消息重复送达时按 digest 去重并增加 `seenCount`；已终结消息再次出现时允许创建新候选，避免历史结论覆盖新上下文。
• Hook 只向 AI 暴露候选 ID、阶段、次数和最小消息锚点，不回显完整 prompt；多个未终结候选并存时，决策必须引用精确候选 ID。
• 旧版单候选状态必须迁移为 v2 candidate set；reset、项目目标切换和压缩恢复都不得丢失未终结候选。

CompoundRecordRouterGate

同一候选可同时命中多个 `record.*` 意图，例如“更优策略 + 规范缺口 + 原有探针漏检”可形成 `record.process-improvement + record.spec-defect + record.audit-gap`。复合意图必须逐项给出目标台账、写入要求、证据 ID 与验证状态；全部必需意图都完成后候选才可终结。禁止只记录第一个命中项、用一个台账 ID 代替其余意图，或把 `record.none` / `record.ambiguous` 与实质写入意图混合。

LedgerWriteEvidenceGate

• `写入要求=required` 时，只有成功的 `PostToolUse` 对**当前 active-root 的精确目标台账路径**形成观察，且本次工具输入和工具完成后的真实文件都包含相同、前缀正确的 ledger ID，才算 `verified`。PreToolUse、失败结果、只在回复中声称编号、只写错误项目/root、只在 patch 内容提到路径、目标文件不存在或宿主未暴露结果，都保持 `unverified`。
• `写入要求=already-recorded` 只适用于当前候选复用已存在记录的情况；必须在当前 active-root 的正确台账文件中重新读取并找到精确 ID，不能引用历史报告、错误 root 或仅凭记忆通过。
• 意图—台账—前缀固定映射：violation→`violations.md/VL-`、spec-defect→`pending-fixes.md/PF-`、process-improvement→`process-improvements.md/PI-`、pending-issue→`pending-issues.md/ISSUE-`、audit-gap→`gap-registry.md/GR-`。复合意图对每一项执行 all-of；任何一项未验证，候选都不能进入 `acknowledged`。
• Hook 只观察和验证写入证据，不自动创建台账条目；无法观察时明确保留 `unverified`，由 instruction-fallback 的报告/会话产物记录人工复证证据。

RecordNoneChallengeGate

`record.none` 是需要证明的终结决策，不是默认兜底。它必须独占规范化意图，并同时提供 `评估结论=no-governance-impact`、合法泛化范围、`现有规范状态=exists-complete|not-applicable`、置信度、独立的具体依据、`写入要求=none` 与具体 `skipEvidence`；不得携带台账路径或 ID。范围为 `project-local|none` 时必须证明局部性/不可泛化；范围更广时只能由 `exists-complete` 及精确既有规则证据关闭。缺字段、可泛化改进仍未被完整规则覆盖、规范状态为 missing/partial/conflicting、与写入意图混合、依据和 skipEvidence 空泛或相互复制时，候选保持 `pending-none-challenge`。`record.ambiguous` 或 `评估结论=uncertain` 始终停在 assessed、保持未终结并先澄清。

Improvement Intake（优化清单）

在所有模式下，除了处理“记录一下”这类显式记录请求，每条用户消息在完成合理性评估后，还必须执行一次主动 Improvement Intake：

• 若用户建议经验证**更优且可泛化**，即使没有说“记录一下”，也应主动写 PI。
• 若用户建议同时暴露了**规范未定义、过窄或不完整**，应同步写 PF。
• 若只是这次执行没有遵守已存在规则，应写 VL，而不是误写 PI/PF。
• 若只是业务项目的一次性偏好、局部临时安排或不可泛化做法，应判为 `record.none`。

Intake 分流矩阵

| 场景 | 目标 | |------|------| | 更优策略，可泛化 | `PI` | | 规范缺口 / 规范不完整 | `PF` | | 更优策略 + 规范缺口同时成立 | `PI + PF` | | 已有规则未执行 | `VL` | | 一次性偏好 / 不可泛化 / 普通讨论 | `none` |

所有模式下，主动 Intake 完成后必须显式回执：`已记录 PI-xxx`、`已记录 PF-xxx` 或 `已记录 PI-xxx / PF-xxx`。

宿主 runtime 若标记 `governanceIntakeCandidate`，只能作为“可能需要 RecordRouter”的收尾提醒；AI 仍必须输出规范化意图、置信度、依据和目标台账，或明确 `record.none + skipReason`。禁止仅凭关键词由 Hook 自动写台账。

InFlightIssueRequirementBindingGate（在途缺陷绑定当前需求）

当 dev/fix 任务已有当前需求或问题真相源且尚未闭环，在 CP2 前、实施中或验证阶段新发现/复现缺陷时，必须先判断它是否与当前目标、验收标准、实现路径、控制面或验证路线相关。相关缺陷不得只登记 PI/PF/ISSUE 后留待未来处理。

| 分类 | 必须动作 | |------|----------| | `blocking-related` | 立即暂停原计划的后续 mutation；把现象、证据、根因边界、影响、修复目标和回归条件写入当前需求/问题确认；用户面提醒是否一并纳入。用户已明确要求“一并处理/必须先处理”或有效 Auto 已授权时，记录 authority 后直接修订并优先修复，不重复索要确认 | | `nonblocking-related` | 在继续实施前写入当前需求的纳入候选与验收影响；提醒用户决定 `include/defer`，确认 include 后同步技术方案、实施计划和 TestRoute | | `unrelated` | 保持当前需求范围不变，按 RecordRouter 写相应台账或独立需求，并记录不纳入依据 |

最低记录字段为：`issueId / discoveredAt / reproductionEvidence / relation / severity / includeDecision / decisionAuthority / requirementPatch / solutionImpact / testImpact / priority`。`includeDecision=pending` 时不得把相关缺陷从当前需求上下文中移除；确认 `include` 后，必须在源码修复前完成需求、技术方案、验收和测试映射同步。阻断项的优先级高于原需求后续阶段，修复并通过定向回归后方可恢复原计划。

以下均不构成完成：只写 PI/PF、只在报告提到、只在记忆留 TODO、只回复用户“已记录”、或等待任务结束后再补需求。若缺陷是在复审/验证中复现，复现证据本身即为绑定触发，不得以“此前未在需求中”为由排除。

LayeredAbsorptionGate（分层吸纳归属判定）

`LayeredAbsorptionGate` 是 Improvement Intake 之后、规范源实施之前的强制架构门禁。`SkillFirstAbsorptionGate` / `CapabilityToSkillPromotionGate` 保留为 Skill 层兼容子门禁。任何可泛化 PI / PF / GAP / ISSUE 或用户确认值得吸纳的策略，都不能默认追加到 `CrossProjectLearnedGuards`、`LatestAbsorptionGuards` 或通用 instructions 长列表，也不能只做“通用规范 / Skill”二选一；必须先判断归属并列出所有消费层。

> 执行归属：本节只定义治理层门禁与输出字段。候选来自 `.devcodex/*/data`、“最新可吸纳 / 仍需吸纳 / 开始吸纳”时，必须读取 `spec-absorption`，先执行 `CommonNormGeneralizationGate` 与 `AbsorptionCandidateConsumerProofGate`，证明通用价值和 DevCodex 当前消费者；项目独有规则只能作为 `project-local` 或 `case-evidence-only`，不得进入通用规范。

归属分类

| 分类 | 含义 | 处理 | |------|------|------| | `global-