Execution Contract Skill
职责
在任务进入执行前，为需要强边界的工作生成或校验 ExecutionContract。它不是新的工作流子类型，而是 dev/fix/auto/release 等流程可调用的支撑型 Skill。
触发条件
| 场景 | 是否触发 |
|---|---|
| Auto 执行模式 | 🔴 必须 |
| 控制面 / 规范源 / 模板 / validate / 部署副本变更 | 🔴 必须 |
| 预计修改 ≥10 文件或多批次执行 | 🔴 必须 |
| 涉及发布、tag、publish、registry 后验收 | 🔴 必须 |
| 普通单文件文档小修 | N/A |
Contract 字段
| 字段 | 必填 | 说明 |
|---|---|---|
scope | ✅ | 本次任务目标、排除范围和禁止事项 |
allowedFirstBatch | 条件 | dev/fix 执行前必填；本批允许立即修改的功能、文件、公开面和验证动作 |
blockedScope | 条件 | dev/fix 执行前必填；明确排除的后续阶段能力、非目标文件、禁止扩散面和 No-Go |
allowedPaths | ✅ | 允许修改的路径集合；Auto 不得仅依赖静态白名单 |
parallelLaunchCards | 条件 | 多需求/子 Agent/worktree 执行前必填；引用 requirement-parallel-orchestration 的 RequirementIndependenceDecisionV1、ParallelLaunchCardV1、SharedSurfaceLockMapV1 和 IntegrationMergeProtocolV1；实际派发还必须绑定 HostSubagentDispatchPlanV1、每项 AgentWorkLeaseV1、当前宿主 direct capability identity、取消围栏与同 work graph 串行回退，缺任一项时不得派发 |
requiredArtifacts | ✅ | 必须产出的需求、方案、计划、进度、报告、测试、changelog 等 |
consumerScope | 条件 | 控制面 / 模板-示例-校验链任务必填；列出 sourceOfTruth、currentConsumers、historicalMirrors、validateProbes、deployCopies |
backlogTruthReview | 条件 | 当任务/批次直接来源于 data/*.md open/partial 项时必填；列出 candidateIds、classification、evidence、scopeDelta |
validationRoute | ✅ | 引用 test-router、audit-release、release-verification 或当前 CP3 验证矩阵 |
regressionMatrix | 条件 | 高风险控制面 / 多批次修复必填；列出“历史能力 → 受影响批次 → 必跑验证 → 失败回滚点” |
verificationEvidence | 条件 | 宿主验证或控制面任务必填；记录 validate、targeted tests、fixture/direct replay、部署同步、VisibleEnvelope/UserFacingArtifactSet/LinkCapability、MCP fallback 等证据计划 |
ledgerWriteback | 条件 | 当本轮会改变 VL/PF/PI/ISSUE/GAP 的状态时必填；列出 targetLedgers、requiredFields、writebackEvidence、rescanResult |
deviationPolicy | ✅ | 绿色/黄色/红色偏离分级与处理方式 |
driftTriggers | 条件 | DevelopmentDriftGate 触发器：范围扩张、包/API/配置/文档消费者变化、新依赖、验证路线改变、dirty 污染或用户新确认 |
deviationLog | 条件 | 多批次或发生绿色/黄色偏离时，记录实际新增消费者、探针、同步副本与理由 |
rollbackPlan | ✅ | 失败恢复路径、回滚锚点或结构化意图重算条件 |
progressArtifact | 条件 | 多批次、预计 ≥10 文件、跨轮次或用户要求持续跟踪时必须写 05-实施进度.md |
safetyInterruptionRecovery | 条件 | 授权本地安全审查出现宿主安全提示/内容不可见时，引用 AuthorizedLocalSecurityAuditPresentationGate 的 SafetyInterruptionCard、last checkpoint 与 resume evidence |
publisherCredentialTopology | 条件 | 首次发布或发布身份/仓库/package/registry/auth topology 变化时，引用 PublisherCredentialTopologyGate；只记录身份、scope/access/permission/ownership/成功证据，不含 secret value |
currentBatchScopeDiff | 条件 | 多阶段/多批次 dev/fix 必填；比较 total phase scope、allowedFirstBatch、当前 batch、blockedScope 与本次 diff |
validationConsumerRebind | 条件 | 新增 root script、CI job、validator、deploy copy 或 consumer 时必填；把 allowedPaths、TestRoute、rollback 与 consumerScope 重新绑定 |
derivedArtifactFreshness | 条件 | 派生资产受 tracked/staged consumer、模板、索引或生成顺序影响时必填；绑定 Owner Gate、生成输入 identity、post-stage candidate check 与 post-commit replay |
turnLivenessContract | 条件 | 长任务、工具完成后无续接、宿主停滞或跨轮次恢复时必填；引用 ai-agent-system-architecture 的状态/lease/ACK/terminal/checkpoint、CheckpointValidation 与 LocalTaskTrace 契约及能力边界 |
executionBudget | 条件 | Auto、多批次、预计 ≥10 文件、C08 恢复、用户反馈「太慢/卡/文件太多」、或 resume 长任务时必填；见 ExecutionBudgetGate |
executionAttemptLedger | 条件 | formal command、失败重试、取消/中断或 restart 时必填；作为既有 TurnLiveness state 的 ExecutionAttemptLedgerV1 子状态，不得新建平行状态机 |
longTaskAuthorization | 条件 | 与 executionBudget 同触发；记录授权证据与 cycle 身份，见 LongTaskAuthorizationGate |
externalWaitAccounting | 条件 | 存在 CP 等待、CI/鉴权/人工审批/外部系统等待时必填；见 ExternalWaitAccountingGate |
instructionAuthority | 条件 | 命中 host-capability-routing、Auto、跨轮或多批次时，引用 instructionRefId / decisionId / authority / digestStrength / freshness / fallback；不复制原文 |
gitExecutionContext | 条件 | 任何 branch/worktree/commit/merge/cherry-pick/push 规划或执行前必填；引用 GitExecutionContextV1，逐项披露并分离授权 |
worktreeLifecycleReceipt | 条件 | DevCodex 引导创建 worktree 或诊断残留 worktree 时必填；引用 WorktreeLifecycleReceiptV1，外部对象保持只读 |
GitExecutionContextGate
Git 共享状态动作由 GitExecutionContextV1 约束；schema 位于 git-execution-context.v1.schema.json，纯读取/校验实现位于 scripts/lib/git-execution-context.js。该能力不是 Git bot，也不能把宿主 UI 或用户绕过 DevCodex 的原生动作宣称为已拦截。
默认决策：
| 场景 | integrationPolicy | 规则 |
|---|---|---|
| 当前分支开发并交付当前分支 | none | 不创建/切换功能分支，不 merge、不 cherry-pick；需要时只单独确认 commit |
| detached/worktree/dev → 目标分支的选择性提交 | ordered-cherry-pick | 先形成有序且去重的 sourceCommitIds，验证目标基线，再显式 switch 与按序 cherry-pick；目标 commit ID 会变化 |
| 完整线性历史且需要保留原 commit IDs | ff-only-explicit | 仅在用户明确选择后使用 merge --ff-only；merge commit 仍非默认 |
| 功能分支或 merge commit | 非默认例外 | 先说明 reason/impact/alternative/target/recovery 并获得该动作授权 |
collaborationMode 未被 Profile/项目事实证明时必须为 unverified，仍采用 no-auto-branch。solo 项目默认 keep-current。branch-create / switch / commit / cherry-pick / merge-ff-only / push 每项都必须有独立 disclosure、authorization、authorizationEvidenceRefs 与 executionEvidenceRefs；pending 禁止携带证据，明确确认必须有本动作授权证据，completed 还必须有本动作执行证据。一个动作的确认不能传递给另一个动作，push 始终独立确认。branch create 必须先于 switch，且 branch/switch/integration disclosure 的 target 必须与 targetBranch 完全一致。读取已保存 context 时必须重算 validation，不得信任序列化的 valid/executable；conflictStatus=unverified 只能先核实，不能执行 Git 写动作。
cherry-pick 前必须满足：repo/HEAD/目标基线已验证，工作树与 index 没有未保护变更，source IDs 有序且不重复；只读 dirty 探针必须同时计入 tracked、untracked 与 ignored 内容，dirtySummary.untracked 包含 Git !! 条目。不得自动 stash、pull、reset、continue 或 abort。冲突时 conflictStatus=detected、validation.executable=false，停止并报告冲突文件与可选恢复动作；post-action 必须记录 targetAfter 和 postIntegrationValidationRefs，不能只凭命令退出码宣称完成。
WorktreeLifecycleReceiptGate
DevCodex 引导创建的 worktree 必须记录 worktreePath / gitCommonDir / headRef / headCommit / owner / ownershipEvidenceRefs / dirtyState / lockState / activeJobState / createdByRunId / teardownPlan / cleanupAuthorization / cleanupAuthorizationEvidenceRefs。safeDirectoryMutationAllowed 永远为 false。单项 schema 为 worktree-lifecycle-receipt.v1.schema.json，聚合诊断 schema 为 worktree-diagnostics.v1.schema.json。
devcodex-guided只有完整 receipt 经字段、派生validation、gitCommonDir与当前 HEAD/ref 重新校验，且 owner、clean、unlocked、无 active job、teardown plan、本次显式清理授权及独立授权证据全部具备时才可能 cleanupEligible；clean 探针必须同时计入 tracked、untracked 与 ignored 内容，避免删除被.gitignore隐藏的本地数据。HEAD/ref 已变化时保留创建归属，但立即退休旧清理授权并把 active job 降为unverified。部分字段、冲突 receipt 或自报validation.valid=true一律不能取得清理资格。host-owned / external-unowned / unverified只读诊断；dirty/owner/lock 任一未知时保持 UNVERIFIED，绝不 prune/remove。status/doctor的WorktreeDiagnosticsV1同时受 1.5 秒单命令上限和 8 秒总预算约束；prunable 路径不进入，外部未归属路径默认不做 dirty 探测，当前 worktree 与有 DevCodex receipt 的对象才进入有界只读探测。发现 dirty、locked、prunable、external-unowned 或未核实状态时聚合为 WARN，并保留逐项 typed issue。- 清理、移动或删除 worktree 必须有明确任务范围与可回读 receipt；实际操作权限由宿主及其用户配置决定，DevCodex 不再签发第二套批准令牌。
ExecutionBudgetGate / ExternalWaitAccountingGate / LongTaskAuthorizationGate（PI-118 / PF-137）
长任务不得只依赖事后 SessionTimingCard 或 C08 轮次阈值。命中 Auto、多批次、预计 ≥10 文件、C08 恢复、用户反馈「太慢/卡/文件太多」、跨会话 resume 同一长任务时，必须冻结 墙钟预算 + 外部等待会计 + 长任务授权。
ExecutionBudgetGate（墙钟预算 / 事中熔断）
| 字段 | 要求 |
|---|---|
cycleId | 当前恢复周期唯一 ID；禁止与已关闭 cycle 复用 |
startedAt | ISO 墙钟起点 |
maxWallClock | 本 cycle 最大执行墙钟（不含 external wait） |
maxWorkUnits | 本 cycle 最大 WorkUnit 数 |
maxDirtyDelta | 允许新增的源码/配置 status 条目上限（或等价 diff 预算） |
maxMaterialFindings | 新增实质性 finding 上限 |
maxFullRuns / maxBuildRuns | full test / build 次数上限；默认只在里程碑 closure 执行 |
compactionBudget | 允许的 compact/resume 次数 |
stopActions | 预算触顶后允许的动作（handoff/report/memory only 等） |
resetPolicy | 仅允许 close-cycle-and-open-new；禁止静默清零同一 cycle |
任一预算先到：立即停止新 source mutation，写 StopSnapshot（elapsed、completed、remaining、dirty delta、findings、validation runs、blocker、nextAction），并进入用户确认/新 cycle 路径。
ExternalWaitAccountingGate（外部等待）
| 等待类型 | 计入 |
|---|---|
| AI 读/写/验证/构建 | executionMs（消耗 wallClock 预算） |
| 等用户 CP/确认/授权 | waitingUserMs（不消耗执行预算） |
| 等 CI / registry 鉴权 / 人工审批 / 外部系统 | waitingExternalMs（不消耗执行预算） |
报告与 TimingCard 必须分列 执行 / 等人 / 外部等待；禁止把隔夜等人或 CI 排队算成「AI 执行了一整夜」。maxWallClock 只约束 executionMs。
LongTaskAuthorizationGate（长任务授权）
| 规则 | 要求 |
|---|---|
| 进入长任务 | 必须有可审计 authorizationEvidence：用户明确继续、合法 Auto、或 CP 确认；不得伪造 |
| 预算未冻结 | 禁止无人值守 source mutation |
| 用户再次「继续」 | 不得静默清零同一 cycleId 的已消耗预算 |
| 续跑 | 关闭旧 cycle → 新 cycleId + 新预算 + 更新 allowedPaths + 新授权证据 |
| 第二次 compact/resume 且旧 cycle 未关 | 强制 StopSnapshot 并要求新 cycle |
permission-core 等业务任务级 baseline 只能作样板，不得替代 DevCodex 通用 Contract 字段。
InstructionAuthorityContract
命中 host-capability-routing 时，ExecutionContract 只绑定 compact identity，不保存完整用户原文或 catalog row。compat/none、conversation-visible、readback 未验证或 digest mismatch 不能单独支持跨轮 mutation；应优先回绑 digest-bound CP/task artifact，失败则进入 StopSnapshot 并返回结构化意图重算，仍无法唯一化才请求重述。portable decision 不改变 allowedPaths、CP、Auto 或安全确认，Phase 1 也不得新增 native/MCP/CLI/Hook recovery action。
OwnIntroducedRegressionSelfFixGate / SharedStateMutationGate（PI-119）
| 门禁 | 规则 |
|---|---|
OwnIntroducedRegressionSelfFixGate | 本会话/本批次自己改出的 CI 红、targeted 失败或 validate 回归：完成根因分析后必须主动修本地并复证，不得停在「是否要修」确认；用户面只汇报证据与残余风险 |
SharedStateMutationGate | git commit / git push / tag / publish / 远端共享态：默认禁止；仅当用户当前消息明确授权（如「提交并推送」「发布」）才可执行；「发版一次」≠ 后续补丁无限 push；一次审批不是空白支票 |
| 与 Auto 关系 | @rocky / Auto 可自动通过 CP，不豁免 SharedStateMutationGate；发布类自然语言（如「版本发布」）仅授权本轮收口发布动作，仍须 R6 清单与成功证据 |
偏离分级
| 级别 | 判定 | 处理 |
|---|---|---|
| 🟢 绿色 | 不改变目标、范围、接口、路径边界的局部实现微调 | 记录原因后继续 |
| 🟡 黄色 | 新增当前消费者、验证动作或部署副本，但不改变需求范围，且仍在 yellowDeviationBoundary 内 | 更新计划/进度/报告与 deviationLog 后继续 |
| 🔴 红色 | 新增依赖、改 Hook runtime 权限模型、改 CLI 语义、改发布动作、扩大需求边界、触达 blockedScope 或改变验证路线 | 停止执行，回 CP2 或 CP1 |
CurrentBatchScopeDiffProbe / NewValidationConsumerRebindProbe
进入每个实施批次前必须反向比较 phaseTotalScope / allowedFirstBatch / actualTargetSet / blockedScope / dirtyBoundary。allowedFirstBatch 只允许当前批次，不得因总路线图已确认而一次放开后续模块。
当计划或实现新增 root package script、CI job、validator、fixture runner、部署副本或外部 consumer 时，执行 ValidationConsumerRebindMatrix，同步 allowedPaths / consumerScope / TestRoute / regressionMatrix / rollbackAuthorization / deployCopies。合同禁止修改某消费者但验收又依赖该消费者时必须在编码前阻断；回滚包含未纳入当前任务与精确目标集的删除、清空或其他动作时不得通过，实际操作权限仍由宿主决定。
Auto 消费规则
- Auto 仍是 Agent/Hook 执行模式，不是普通 Skill。
execution-contract只提供可复审契约，不豁免 S01~S07、C01、C10、C18。- Auto 修改路径必须同时满足静态白名单和当前 Contract 的
allowedPaths。 - Contract 缺少
allowedPaths、requiredArtifacts或validationRoute时，不得进入无人值守执行。
Turn Liveness 条件契约
命中长任务或宿主停滞时，ExecutionContract 只引用 ai-agent-system-architecture#TurnLivenessRecoveryGate，并补充本任务的 allowedRecoveryActions / forbiddenRecoveryActions / checkpointOwner / idempotencyEvidence / hostCapability / sidecarLifecycle / recoveryValidation。默认允许状态观察、恢复卡和用户可见诊断；默认禁止自动重放 mutation、修改宿主私有 thread store、终止未知/用户进程或把 Hook-only 检测描述为无事件 watchdog。sidecar 若未积累前瞻证据必须保持 gray，并写 trial/rollback 条件。
CheckpointValidationResultV1 必须分别记录 response-time 与 post-execution 的 status/evidence/deadline/errorCode；缺失宿主终态证据不得写 pass。启用 LocalTaskTraceV1 时还必须冻结 traceOwner / eventTypes / terminalSource / replayBoundary / retentionScope：只允许当前 turn 的只读数据投影，禁止 payload 执行、operation replay、state mutation、host wakeup 与 process control。
ExecutionAttemptLedgerGate
ExecutionAttemptLedgerV1 直接嵌入现有 TurnLiveness state，记录 candidateId / phase / commandSignature / qualificationEvidence / attemptNo / failureSignature / sourceDelta / evidenceDelta / FirstPassYield / commandWallMs / externalWaitMs / waitingUserMs / modelReasoningMs / terminal。有可用 qualification probe 时，formal run 前必须先有同 candidate/phase/command 的 pass；否则返回 qualification-required。
相同 candidate + phase + command + failureSignature 的连续两次 formal failure，且两次 sourceDelta=0 / evidenceDelta=0 时，第二次即生成 StopSnapshotV1，第三次正式运行前返回 stop-before-third 并停止新 mutation。相同 eventId 的相同语义重复交付幂等忽略，语义冲突必须报错。用户取消/中断必须写 cancelled/aborted terminal、释放 AI-owned lease，并记录 cancel finalizer 与 ServiceLifecycleCleanup；restart 只恢复原 ledger，不得把旧 inProgress 自动提升 completed。
DualLayerRepairCollaborationContract
当 AI 根据问题锚点和预期行为判断任务目标是修复 Bug、缺陷、回归、安全问题、规范缺口、审查 finding 或其他已确认不正确行为时，必须建立双层修复协作契约。该触发与模型名称、是否切换模型/Agent、宿主 UI 或工作流标签无关；纯新增能力、纯分析/审计发现阶段或只讨论模型选择不触发。
公共字段与状态
| 字段 | 要求 |
|---|---|
repairClass | lightweight / full |
contractState | draft / approved / executing / verification-pending / accepted / rejected / blocked |
authorizationEvidence | CP、合法 Auto、验证预算、发布或其他可审计的工作流授权；Auto 使用 mode=auto，不得伪造人工确认。文件/命令的操作级 permission 由宿主决定，不得记录成 DevCodex 自有授权 |
roleAssignments | 显式记录决策/验收与执行/验证逻辑角色；允许同一主体，但高风险通过结论不能只有补丁产出者自证 |
允许状态转换为 draft→approved/blocked、approved→executing/blocked、executing→verification-pending/blocked、verification-pending→accepted/rejected/blocked、rejected→executing/blocked。禁止 executing→accepted；单个测试通过、代码写完或开始验证不能替代 accepted。
lightweight
适用于低风险、预计不超过 2 文件，且无公共 API/Schema/config、控制面、发布、多批次或角色交接的 repair task。允许在问题确认、报告或记忆中内联，不强制完整任务目录。
| 层 | 必填字段 |
|---|---|
| 决策/验收层 | problemAnchor、expectedBehavior、acceptanceEvidence、decisionAcceptanceOwner |
| 执行/验证层 | allowedPaths、validationRoute、rollbackTrigger、executionVerificationOwner |
full
P0/P1、安全、控制面、公共 API/Schema/config、预计 ≥5 文件、多批次、角色交接、发布或其他高风险场景必须升级完整契约。
| 层 | 必填字段 |
|---|---|
| 决策/验收层 | auditSnapshot、approvedFindingIds、evidencePacket、roleAssignments、acceptanceMatrix、authorizationEvidence、条件 humanApproval |
| 执行/验证层 | allowedPaths、blockedScope、batchPlan、findingToPatchMap、regressionMatrix、handoffIntegrity、independentReReview、rollbackPlan |
findingToPatchMap 必须形成 problemAnchor/findingId → patchPaths → verificationEvidence → acceptanceStatus；每个 finding 至少映射一个 patch 或 no-code-change + evidence，每个 patch 必须反向对应已批准问题。
handoffIntegrity 复用 ContextHandoffCard，并追加 status / missingFields / checkedBy / checkedAt。independentReReview 至少记录 owner / independenceMode / evidence / result / runId；independenceMode 可为 isolated-session / different-agent / different-model / human / black-box-evidence，不强制第二模型或第二 Agent。
accepted 条件
- authorization、allowed paths、acceptance matrix 与 required evidence 均有效；full 合同还必须具备完整 finding map、handoff 与 independent re-review。
- active
repair-prevention-assessment#RepairPreventionAssessmentGate已返回有效RepairPreventionAssessmentV1；当前修复证据与 prospective prevention evidence 分列，no-new-control具有标准 reason/evidence，高风险或 repeat escape 使用 full。 - 补丁产出者可以参与验证，但不能成为高风险任务唯一通过证据源；角色独立或黑盒证据独立均可。
- 证据失败进入 rejected；触达 blockedScope、缺真相源或需要重开 CP 时进入 blocked。
输出格式
markdown## ExecutionContract | 字段 | 内容 | |------|------| | scope | | | allowedFirstBatch | | | blockedScope | | | allowedPaths | | | requiredArtifacts | | | consumerScope | | | backlogTruthReview | | | validationRoute | | | ledgerWriteback | | | verificationEvidence | | | deviationPolicy | | | driftTriggers | | | deviationLog | | | rollbackPlan | | | progressArtifact | | | safetyInterruptionRecovery | | | publisherCredentialTopology | | | instructionAuthority | instructionRefId / decisionId / authority / digestStrength / freshness / fallback | | turnLivenessContract | state/lease/ACK/terminal + checkpointValidation + LocalTaskTrace/replayBoundary | | executionBudget | cycleId / maxWallClock / maxWorkUnits / maxDirtyDelta / maxFullRuns / stopActions / resetPolicy | | executionAttemptLedger | qualification / attemptNo / failureSignature / source+evidence delta / timing split / terminal / StopSnapshot | | externalWaitAccounting | executionMs vs waitingUserMs vs waitingExternalMs | | longTaskAuthorization | authorizationEvidence / cycle lifecycle / continue=new-cycle | | repairPreventionAssessment | RepairPreventionAssessmentV1 / immediateClosure / prospectiveStatus / rollbackOrSunset |
验证
- 执行前：CP2/CP3 或修复方案中存在 Contract 字段，并通过
DevelopmentDriftGate核对allowedFirstBatch / blockedScope / driftTriggers / validationRoute / consumerSync / dirty boundary。 - 长任务 / Auto / resume：存在
executionBudget+longTaskAuthorization；有等待面时存在externalWaitAccounting；缺预算或未授权不得进入无人值守 mutation。 - repair task：轻量契约字段完整；高风险 full 契约的 finding map、handoff、独立复证和状态转换完整；RepairPreventionAssessmentV1 有效且没有用 current-event rerun 冒充 prospective effectiveness；只出现模型名称不得误触发。
- 执行中：每个 Batch 对照
allowedPaths、requiredArtifacts、consumerScope、backlogTruthReview、regressionMatrix、ledgerWriteback与deviationLog；消耗逼近预算时提前提示，触顶写StopSnapshot。 - 执行后：ECR-2/ECR-3/ECR-7 引用 Contract、
verificationEvidence、历史能力回归结果、backlog 真相复核结果与最终偏离记录；命中派生资产时引用PostStageDerivedArtifactFreshnessGate的 staged candidate receipt 和 post-commit replay，不能用生成时的 working-tree check 代替；命中 turn liveness 时同时引用双阶段 checkpoint 与 trace zero-write/replay 证据；长任务 ECR 必须引用 budget 消耗与等待分列。
