Spec Governance

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 的受控评估结果，而不是靠“未命中关键词”静默绕过。

置信度规则

每次候选评估必须输出结构化 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 分流矩阵

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

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

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

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

最低记录字段为：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，不得进入通用规范。

归属分类

新 Skill 判定条件

满足任一条件应优先判为 new-skill-required：

1. 需要 3 条以上相关子门禁或一组稳定执行步骤。
2. 需要独立产物、状态文件、模板、清单或证据矩阵。
3. 跨 dev / fix / audit / release / report 多个工作流复用。
4. 用户会用自然语言直接点名该能力，例如“用户使用文档”“复审清单”“发布前审查”。
5. 只放在通用规范会导致触发条件模糊、提示词膨胀、职责边界不清或验证只能检查文本存在。

LayeredAbsorptionDecision 输出

每次吸纳实施前，CP2 / 技术方案 / 报告至少记录：

SkillAbsorptionDecision 是 LayeredAbsorptionDecision 的 Skill 层兼容字段，不能替代完整分层决策。若判定为 new-skill-required，不得只把规则追加到通用守门清单后宣告吸纳完成；必须在同批创建 Skill，或把未创建原因写入 PF / ISSUE，并在后续批次优先处理。任何层级判定为 N/A 都必须写 skipReason。

CapabilitySurfaceDecisionGate（能力载体中央决策）

新增或升级规则、Skill、Prompt、Resource、Tool、task-augmented Tool、CLI、Hook 或结构化 状态能力时，在 LayeredAbsorptionDecision 之后、创建/修改具体载体之前，必须执行 registry group capability-surface-decision。本 Gate 解决“直接写规则还是设计 MCP/CLI/Hook”， 不替代 platform/Agent architecture 的 primitive、宿主与权限证据。

唯一真相源与责任边界

中央 Gate 不是 MCP server，不持有领域 runtime state，也不改变宿主能力。被选中 surface 的 既有 owner 继续负责 runtime/state/transaction；新增 server 仍须独立比较 owner、事务、 信任/故障域、消费者、迁移和回滚。

决策路线

选择 tool 或 task-augmented-tool 后必须继续判断 read/write/execute、 control party、runtime/state/transaction owner、scope、confirmation、allowlist、 idempotency、timeout/cancel、receipt/audit。Tasks 未在 client/server 双侧协商时， 不得启用 task surface，必须回退同步 Tool 或 CLI。

CapabilitySurfaceDecisionV1

最低字段由 canonical schema 唯一定义，包含：

decisionRef / capabilityId / capabilityKind / semanticJudgement / contentDelivery / determinism / invocationFrequency / preferredSurface / controlParty / readWriteExecute / decisionOwner / runtimeOwner / stateOwner / transactionBoundary / hostMatrix / fallback / consumers / validationRoute / decisionEvidence / canonicalRecordPath / writer / readers / identity / invalidationTriggers / truthBoundary / status。

条件字段：

• write/execute → authority；
• Prompt/Resource/Tool/task surface → mcpContract；
• task surface → taskContract，且 negotiated capabilities 必含 tasks；
• Resource/Resource Template → resourceContract 的 payload/freshness/URI bound。

状态为 draft / validated / frozen / stale / blocked。validated/frozen 必须通过 schema、 surface-specific invariants、identity 与负向 fixture；stale/blocked 不得被 CP、报告或 生命周期消费者当作可实施证据。

Freshness 与失效

identity 绑定 schemaDigest/sourceHead/checkedAt/evidenceDigest。schema、source、 evidence、host、protocol、consumer 或 runtime owner 任一变化即重新验证；只更新时间不能 恢复 freshness。validator receipt 必须暴露 classification、issues、openBlockers、 decision/schema digest 与 freshness reasons。

必要负向探针

• 开放式语义判断被强制做成 Tool；
• 无界内容作为 MCP payload；
• write/execute 缺 authority/confirmation/allowlist/idempotency/cancel/receipt；
• Tasks 未协商仍启用或 fallback 递归；
• 新 server 无 owner/consumer/migration/rollback；
• 领域 Skill 复制中央字段或出现第二 writer；
• decisionRef/path 重复、identity stale、host/decision evidence 为 BLOCK；
• 只有 preferredSurface 字段但没有可重放的完整 decision record。

HistoricalCommonNormLayeringGate（历史通用规范分层迁移）

当用户要求“之前吸纳的规范重新分层”“全面逐个文件审查”“不要都堆在通用规范里”，或复审发现通用 instructions / prompt / report 模板持续承载大段执行正文时，必须执行 HistoricalCommonNormLayeringGate。

逐文件审查矩阵

迁移前先创建并冻结逐文件审查矩阵，至少包含：

迁移规则

• 通用 instructions 只保留安全底线、全局不变量、触发索引、跨 Skill 路由和历史兼容锚点；不得继续成为新 Gate 正文的默认容器。
• 具体执行步骤、证据字段、测试路线、发布门禁、用户文档写作、复审清单、Profile 同步和自我进化控制面必须进入对应 Skill、Prompt/Report 模板、执行消费者和 validate 探针。
• 已在通用层存在但尚未找到同等强度承接方的历史规则，不得直接删除；标记为 legacy-index-retained，保留 Gate 名 grep 锚点，并把补迁移项写入矩阵 / PF / ISSUE。
• Prompt 和 report 只能承载字段与输出结构，不复制完整 Gate 长清单；需要全量执行的内容由目标 Skill 读取。
• 历史 release / version / requirement 镜像默认按 historicalMirror 处理，不回写当前架构口径；当前 README、website guide、active version、changelog、Profile 和部署副本必须同步。
• 新增或补强该迁移能力时必须更新 V74 或后续 validate 探针，检查 HistoricalCommonNormLayeringGate、逐文件矩阵、目标 Skill、Prompt/Report、public docs 与 deploy copy。

PromptLongGateListDriftProbe

PromptLongGateListDriftProbe 是历史长清单迁移后的防回流探针。当前 README、website guide、拆分 instructions、technical-design / implementation-plan / report prompts 等消费者只能写 GovernanceGateRegistry、gateGroup、ownerSkill、validationRoute、skipReason 和少量代表锚点；不得重新复制 CrossProjectLearnedGuards、LatestAbsorptionGuards 或 ConfirmedAbsorptionCompletenessGates 的完整 Gate 长清单。

探针必须包含 SCV 负向样例：用旧版跨项目长清单、完整吸纳长清单和最新吸纳长清单构造样例，确认检测逻辑会失败；同时用分组 registry 摘要构造正向样例，确认不会误伤。若复审发现 prompt、report、README 或 website 又出现跨组大清单，应先记录逃逸原因，再补 GovernanceGateRegistry / gateGroup 引用和目标 Skill 承接方。

分层检查面