القائمة
当需要在 .servo/ artifact 中执行事务化写回时使用此技能。接收结构化写回指令，执行预校验→写入→后校验，替代 harness-skill 中分散的 ad-hoc 写回逻辑。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
当需要运行 Harness 分层闭环控制系统时，使用这个技能。它是 Codex 中顶层监督控制器的入口，负责状态估计、算子选择、技能绑定、子代理分派、证据收集、裁决与状态更新，而不是直接执行编码。
当 Harness 系统尚未初始化，或 `.servo/goal-charter.md` 不存在，需要初始化 repo 级 Goal Charter 与 Harness 控制面时，使用这个技能。
当 Harness 处于 WorktrackScope.closing，且需要一轮限定范围的收尾处理来处理合并请求、合并、清理与代码仓库刷新交接，同时不能悄悄越过审批边界时，使用这个技能。
当 Harness 处于 WorktrackScope.dispatching，且需要一轮不扩大范围的限定范围分派来选择专用技能或执行载体时，使用这个技能。
当 Harness 处于 WorktrackScope.judging，且需要基于现有证据完成一轮限定范围关卡判定，而不重新执行工作或刷新代码仓库状态时，使用这个技能。
当 Harness 处于工作追踪范围.验证中，且需要一轮限定范围的审查证据流程来收集并综合审查发现、但不输出最终关卡判定结果时，使用这个技能。
| name | repo-writeback-skill |
| description | 当需要在 .servo/ artifact 中执行事务化写回时使用此技能。接收结构化写回指令，执行预校验→写入→后校验，替代 harness-skill 中分散的 ad-hoc 写回逻辑。 |
本技能是通用 .servo artifact 写回算子，提供文件级事务保证：预校验字段合法性 → 一次性重写目标文件 → 提交后校验文件完整性。
它不承担业务逻辑（如 milestone completion 判定、pipeline advancement 计算），只执行经过验证的字段写入。业务逻辑仍由调用方（harness-skill、worktrack-close-skill 等）负责。
当需要在 .servo/ artifact 中执行结构化写回时使用：
文件级事务：预校验 → 重写 → 后校验。
writeback_instruction
↓
[预校验] 检查：文件存在、字段合法、值类型匹配
↓ (fail → return writeback_blocked)
[写入] 一次性重写目标文件（替换匹配的 YAML block）
↓
[后校验] 检查：文件可解析、字段值已更新、无意外修改
↓ (fail → return writeback_incomplete)
[完成] 返回 writeback_ok
.servo/ 文件在 worktrack 隔离 branch 上，无并发写writeback_instruction:
target_file: ".servo/milestone/MS-20260623-002.md"
operations:
- action: "set"
field_path: "progress_counter.completed"
value: 2
- action: "set"
field_path: "updated"
value: "2026-06-23T15:00:00+08:00"
pre_validate:
- check: "file_exists"
- check: "field_type_match"
- check: "no_destructive_operation"
post_validate:
- check: "file_parseable"
- check: "field_value_equals"
- check: "no_extra_fields_modified"
evidence_passthrough:
closeout_evidence_bundle_ref: string | N/A
closeout_bundle_status: complete | incomplete | contaminated | historical_gap | missing | N/A
dispatch_provenance:
status: captured | linked | incomplete | missing | historical_gap | contaminated | N/A
runtime_dispatch_record_ref: string | N/A
subagent_dispatch_record_refs: []
missing_dispatch_record_refs: []
dispatch_result_status: delegated | current_carrier_fallback | permission_blocked | runtime_gap | dispatch_package_unsafe | blocked | historical_gap | N/A
resolved_runtime_dispatch_status: delegated | current_carrier_fallback | permission_blocked | runtime_gap | dispatch_package_unsafe | blocked | historical_gap | incomplete | missing | contaminated | N/A
| action | 说明 | 适用场景 |
|---|---|---|
set | 设置单个字段值 | 更新 progress_counter、status 等 |
upsert_entry | 在 YAML list 中 upsert 条目（按 key 匹配） | 更新 milestone-backlog 条目 |
append_entry | 在 YAML list 末尾追加条目 | 新增 worktrack-backlog 条目、追加 latest_closed_worktrack_commit |
move_entry | 将条目从 source list 移动到 target list | milestone-backlog → milestone-history 迁移 |
set_section | 替换整个 YAML section | 更新 pipeline_summary 等聚合字段 |
writeback_instructionevidence_passthrough 必须携带 closeout handoff 中的 dispatch provenance 字段；缺失或不一致时返回 writeback_blocked: evidence_passthrough_incompletefile_exists: 目标文件必须存在（.servo/ 内路径）create_if_missing: true，创建空文件并填入 frontmatter + 基础结构writeback_blocked: file_not_foundfield_type_match: 值的类型必须匹配目标字段的预期类型progress_counter.*: integerstatus: string (planned/active/completed/superseded)updated: ISO8601 timestamp stringcompleted/blocked/deferred: integerpipeline_summary: string pattern planned=N / active=N / completed=N / superseded=Nlatest_closed_worktrack_commit: stringcloseout_evidence_bundle_ref: stringcloseout_bundle_status: string enum (complete / incomplete / contaminated / historical_gap / missing)dispatch_provenance.status: string enum (captured / linked / incomplete / missing / historical_gap / contaminated)runtime_dispatch_record_ref: stringsubagent_dispatch_record_refs: listmissing_dispatch_record_refs: listdispatch_result_status: string enum (delegated / current_carrier_fallback / permission_blocked / runtime_gap / dispatch_package_unsafe / blocked / historical_gap / N/A)resolved_runtime_dispatch_status: string enum (delegated / current_carrier_fallback / permission_blocked / runtime_gap / dispatch_package_unsafe / blocked / historical_gap / incomplete / missing / contaminated)milestone_id、title、created_by、created_atstatus: completed → status: planned（不可逆状态变更需 programmer 审批）closeout_evidence_bundle_ref、closeout_bundle_status、dispatch_provenance.status、runtime_dispatch_record_ref、subagent_dispatch_record_refs、missing_dispatch_record_refs、dispatch_result_status、resolved_runtime_dispatch_status。writeback_blocked: dispatch_provenance_missing 或保留上游明确的 historical_gap；不得合成 delegated、current_carrier_fallback、permission_blocked、runtime_gap、dispatch_package_unsafe 或 blocked。writeback_incomplete: file_corruptedwriteback_incomplete: field_value_mismatch，列出具体不匹配字段writeback_incomplete: unexpected_modificationharness-skill §10.7.6 定义的 acceptance writeback 事务最小写入集合：
| 写入目标 | 操作 | 说明 |
|---|---|---|
.servo/milestone/{id}.md | set progress_counter, status, updated | 核心 milestone 状态 |
.servo/repo/milestone-backlog.md | upsert_entry + move_entry | live backlog 条目更新 + 迁移到 history |
.servo/repo/milestone-history.md | append_entry | 已完成的 milestone 归档 |
.servo/control-state.md | set active_milestone, milestone_status, pipeline_summary | 控制面状态 |
.servo/repo/worktrack-backlog.md | set status (planned/active → done/deferred/blocked) | worktrack 状态归一化 |
事务执行顺序：先写入 milestone artifact → 更新 backlog → 迁移 history → 更新 control-state → 归一化 worktrack-backlog。
任一步骤 fail，标记 writeback_incomplete，不继续后续步骤。
| 维度 | .repo-writeback-skill | milestone-cleanup-skill |
|---|---|---|
| 操作对象 | .servo/ artifact 文件内容（字段值） | repo runtime cleanup report、dry-run 清理候选、本地 git 分支 + backlog 条目归档 + control-state 压缩 |
| 操作性质 | 字段级内容变更（写、改、迁移） | 默认 report/dry-run；显式批准后才执行文件系统/分支清理（删、归档、压缩） |
| 典型动作 | 更新 progress_counter、追加 commit hash、迁移 backlog 条目 | 生成 runtime maintenance sweep report、报告可清理分支、归档 history、压缩滚动日志 |
| 事务保证 | 文件级事务（预校验→重写→后校验） | 安全守卫（不碰 remote、不删未合并分支、不删 baseline；自动 closeout 只 report/dry-run） |
| 触发时机 | 每次 worktrack closeout / milestone acceptance / checkpoint 更新 | Milestone final acceptance / repo refresh 后、下一次 milestone activation 判定前 |
| 副作用 | 仅修改 .servo/ 文件内容 | 默认无清理副作用；apply 经批准后才删除本地分支、修改 backlog 条目归属或 compact control-state |
关键区分：writeback 改"文件里写了什么"，cleanup report 先说明"运行空间里有什么清理候选"。两者不同时执行，但可能在同一 closeout 链中先后调用；自动 closeout 链不得把 report finding 升级为 apply 授权。
.servo/ 目录的 git 跟踪策略因仓库而异：
| 模式 | 说明 | writeback 行为 |
|---|---|---|
| untracked（默认） | .servo/ 在 .gitignore 中，不进入 git 历史 | 仅文件级事务，不执行 git add |
| tracked | .servo/ 被 git 跟踪，作为 repo 正式 history 的一部分 | 文件级事务 + 写入后 git add 目标文件 |
跟踪模式从调用方的 control-state 或 repo 配置中读取（servo_tracking_mode: untracked | tracked）。本 skill 不决定跟踪策略，只根据模式调整写入后的 git 行为。
当前仓库默认
untracked。若切换到tracked，writeback 事务的第三步（后校验）需扩展到包含git diff --check。
本 skill 内置以下常见 .servo artifact 操作模式，调用方可直接使用模式名称，无需手写完整 instruction。
更新 milestone progress_counter 并追加 latest_closed_worktrack_commit。
writeback_instruction:
mode: "worktrack-closeout-progress"
params:
milestone_id: "MS-20260623-002"
worktrack_id: "WT-xxx"
commit_ref: "wt-xxx@abc1234"
merge_target: "ms/MS-20260623-002-worktrack-lifecycle-complete"
closeout_evidence_bundle_ref: ".servo/...#closeout-evidence-bundle"
closeout_bundle_status: "complete"
dispatch_provenance:
status: "linked"
runtime_dispatch_record_ref: ".servo/...#runtime-dispatch-WT-xxx"
subagent_dispatch_record_refs: []
missing_dispatch_record_refs: []
dispatch_result_status: "delegated"
resolved_runtime_dispatch_status: "delegated"
自动执行：
progress_counter.completed += 1, updated = nowlatest_closed_worktrack_commit, 更新 active_milestone_progressdone；若写入 evidence refs，同步保留 closeout_evidence_bundle_ref、closeout_bundle_status 与完整 dispatch_provenance passthrough 字段注册新 worktrack 到 control-state 和 worktrack-backlog。
writeback_instruction:
mode: "worktrack-init-register"
params:
worktrack_id: "WT-xxx"
milestone_id: "MS-xxx"
node_type: "docs"
branch: "wt-xxx"
status: "active"
Worktrack closeout 后清理 control-state 中的 active worktrack 指针。
writeback_instruction:
mode: "worktrack-closeout-clean"
params:
worktrack_id: "WT-xxx"
next_function: "RepoScope.Observe"
自动执行：
active_worktrack = none, worktrack_scope = closed, current_function = next_function更新或插入 milestone-backlog 条目。
writeback_instruction:
mode: "milestone-backlog-upsert"
params:
milestone_id: "MS-xxx"
updates:
status: "active"
priority: 42
激活 milestone（设置 active，更新 pipeline 上下文）。
writeback_instruction:
mode: "milestone-activation-switch"
params:
milestone_id: "MS-xxx"
previous_active: null # 或上一个 active milestone_id
自动执行：
active_milestone = milestone_id, milestone_status = activeactiveactivecompleted（goal-driven）或 superseded（work-collection）更新 control-state 的 Baseline Traceability checkpoint。
writeback_instruction:
mode: "baseline-checkpoint-update"
params:
checkpoint_type: "latest_observed_checkpoint" | "last_doc_catch_up_checkpoint" | "milestone_input_checkpoint"
hash: "abc1234"
verified_at: "2026-06-23T16:00:00+08:00"
重新计算并写入 milestone_pipeline_summary。
writeback_instruction:
mode: "pipeline-summary-recalc"
params:
planned: 3
active: 1
completed: 61
superseded: 0
将 milestone 条目从 live backlog 迁移到 history。
writeback_instruction:
mode: "milestone-history-archive"
params:
milestone_id: "MS-xxx"
final_status: "completed" | "superseded"
accepted_at: "2026-06-23T16:00:00+08:00"
accepted_by: "programmer"
自动执行：
更新 control-state 的路由和当前动作字段。
writeback_instruction:
mode: "control-state-route-update"
params:
current_function: "RepoScope.Observe"
recommended_next_route: "RepoScope.Decide"
current_next_action: "milestone 3/6; next WT: contract-checklist"
追加 handback 历史记录到 control-state。
writeback_instruction:
mode: "handback-history-append"
params:
status: "milestone-activated" | "worktrack-initialized" | "worktrack-closed" | "repo-scope-ready"
detail: "WT-xxx completed and merged"
当内置模式不覆盖时，使用原始 instruction 格式：
writeback_instruction:
target_file: ".servo/milestone/MS-20260623-002.md"
operations:
- action: "set"
field_path: "progress_counter.completed"
value: 2
- action: "set"
field_path: "updated"
value: "2026-06-23T15:00:00+08:00"
writeback_instruction:
target_file: ".servo/control-state.md"
operations:
- action: "append_entry"
list_path: "Active Worktrack.latest_closed_worktrack_commit"
value: "wt-xxx@abc1234 (merged to ms/MS-xxx)"
writeback_instruction:
transaction_id: "txn-MS-20260623-002-acceptance"
steps:
- target_file: ".servo/milestone/MS-20260623-002.md"
operations:
- action: "set"
field_path: "status"
value: "completed"
- target_file: ".servo/repo/milestone-backlog.md"
operations:
- action: "move_entry"
entry_key: "milestone_id"
entry_value: "MS-20260623-002"
from_list: "live_entries"
to_list: "completed_entries"
# ... more steps
writeback_result:
transaction_id: "txn-xxx"
status: "writeback_ok" | "writeback_blocked" | "writeback_incomplete"
steps_completed: 3
steps_total: 3
pre_validation:
passed: true | false
failures: []
post_validation:
passed: true | false
failures: []
affected_files:
- ".servo/milestone/MS-xxx.md"
- ".servo/repo/milestone-backlog.md"
proceed_blockers: []
recommendation: "continue" | "handback" | "retry"