/execution-contract

name: execution-contract
description: 执行契约规范 — 为长流程、多文件、Auto 或控制面任务生成/校验 ExecutionContract，约束范围、路径、产物、验证路线、偏离分级与恢复策略

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。单项 s