workflow_tool_skill_evolution

道-方法 · 道层 skill 全文

本页是 <code>rules/skills/drafts/workflow_tool_skill_evolution.md</code> 的逐字投影（仅隐私清洗，零改写）。

name: workflow_tool_skill_evolution
type: 道（治理 / 演进）
status: draft (Beta) — 晋级前需 ≥1 个真实更新点经本 skill 的动态 workflow 端到端优化并过 landing_gate（FU-11 forcing_closure 三态为首个 dogfood）
created: 2026-06-15
description: 给一个已注册的工具、skill 或方法论文件加内容、改已有、或弃用时，怎么走才不破坏耦合、不丢旧需求、还保持模块化的方法论（道）。也判一次更新是否真 landed，以及怎么为一个具体更新点排一条任务专属的动态更新流程。触发场景：要改 tools/、rules/skills/ 或方法论文件（contexts/methodology/ 及各域 methodology/）下任一已注册资产、要为某更新点排更新流程、要判一次更新有没有破坏全系统、要让一次方法论修订真正传播到消费者、要用 trace 台账反推该优化什么。配套术 = 动态 workflow planner + 结构/行为/意图三家族检测器。设计真源在 adhoc_jobs/tool_skill_evolution_workflow_20260613/；方法论资产类与修订传播的机制真源在 adhoc_jobs/methodology_system_buildout_20260719/design/f_loop_design.md。

工具/skill 更新与演进（道）

一句话

一次更新不是"把文件改了"，是对一个运行系统的扰动。改动者从自己内部算不出"我有没有破坏耦合、丢了旧需求、还模块化吗"，这个判断和原任务同等代价、且从内部不可见。所以更新 workflow 的本质是闭环控制：harness 替改动者制造机械、可操作、独立调控者裁决的误差信号。一份让改动者自我打勾的清单，恰恰是那个失效本身。

何时用 / 不做什么

用：要改 tools/ 或 rules/skills/ 下任一已注册资产（加能力 / 加内容 / 改已有 / 弃用）；要改方法论文件（contexts/methodology/ 及各域 methodology/，见「方法论文件资产类」节）；要为某个更新点排一条更新流程；要判一次更新有没有破坏全系统或是否真 landed；要让一次方法论修订真正传播到消费者（见「修订传播义务」节）；要用 trace 台账反推该优化什么。

不做：不调度执行（那是术层 phase_runtime / 动态 planner）；不替代落地判级（workflow_landing_to_production）、需求入库（workflow_requirement_intake）、版本判定（workflow_version_evolution），本 skill 在更新场景里把它们串起来用；trivial 一行改动不必走全流程（按下面裁剪纪律）。

核心原理：三个正交误差信号源

误差信号有三个正交来源，对应改完可能破坏的三样东西。这是个跨域同构：把变更看成对运行系统的扰动，系统状态分三层，每层各有"对不对"的判据（接 [[project_open_loop_control_theory]] [[project_anti_performative_diligence_methodology]] [[project_verifiable_checkpoint_experiment]]）。

• 结构：引用、契约、schema。静态可查（"改 X 后引用 X 的 Y 还连得上吗"）。家族 A 供给。
• 行为：运行时台账 trace。运行可查（"改完后这个资产的真实使用和效果有没有漂移"）。家族 B 供给。
• 意图：提案对实现。做之前就锚住（"我说要改的和实际改的对得上吗，原需求还守着吗"）。家族 C 供给。

三层都闭，这次更新才真正受控。闭环的硬条件是有可测误差信号 + 调控者独立于被控对象，本 skill 的所有判断都为这两条服务。

方法论 A：如何更新（point 2a）

一次更新依次穿过 U0–U8 的可裁剪主干，括号标供给该步误差信号的家族。裁剪要显式记理由，不静默跳（沿用 workflow_phase_framework 的裁剪纪律）。

• U0 触发与分类：判更新类型（加工具能力 / 加 skill 内容 / 改已有 / 弃用），并给消费方一个 BREAKING / EXTENDED / DEPRECATED 信号。
• U1 提案（意图锚）[C]：写变更提案（为什么改 + 范围 + 上面的分类）。trivial 可省，但在 U7 记录里补一句因由。
• U2 影响分析（结构）[A]：reference_validator backlinks <target> 枚举下游 consumer，贴进提案。这一步同时处理耦合（看清谁依赖我）和结合旧需求（下游清单里就有承载旧需求的文件，改动决策必须照顾它们）。
• U3 改动 + delta 记录 [C]：做改动，同时记 delta（ADDED / MODIFIED / REMOVED），只记变化不重写全文。
• U4 结构门，改完即验 [A]：reference_validator validate + check-indexes + check-new-files（无死链 / 注册有效 / 新文件已登记）+ schema 守卫（契约文件版本）；目标是 skill 时另加 orthogonality.py（EW-5）判内容重叠（触发文本 Jaccard）与环境正交（是否共享同一条字面触发短语），不只是"链接通"还要"不跟别的 skill 抢触发场景"。机械 PASS / FLAG，不收自我声明。
• U5 行为验证 [C/B]：见方法论 B。文件改了不算完，行为变了才算。
• U6 版本判定 [C]：拿 U2 的下游清单喂 workflow_version_evolution 的"下游负担"判据，定打不打版本。把版本判断从凭记忆变成"工具出数据 + 判一个问题"。
• U7 归档 + 台账锚 [C/B]：delta 合并进主真源（INDEX / skill 文件 / 矩阵），变更记录进 contexts/evolution_changes/<date>-<target>/（审计轨迹非真源），改动锚 task_id 落 receipts 台账。
• U8 闭环回探 [B]：见方法论 C 的"发现"。台账反推出新漂移，生成下一条 U0。

不同更新类型走同一主干，差别在裁剪和门的松紧：加工具能力重 U2 + U4 + U5；加 skill 内容重 U1 + U5 + U6（分类/联动边变了回写矩阵）；改已有全程最重，U2 是命门，U5 验老行为没退化；弃用重 U1 的 DEPRECATED + U2 找全下游 + U3 的机械标记动作（deprecation.py mark：文件内插入 banner + 追加 maturity registry 行，只 append 不删改既有内容，提供迁移指针且不破坏兼容）。

方法论 B：如何验证效果（point 2b）

更新的"做对了"判据不是文件改了，是三层都给出非自报的信号：

1. 行为验证而非文件验证：给独立 sub-agent 一个 held-out 场景，不告诉它改了什么，看它是否自然命中新行为（对标 superpowers TDD skill 验证；接 [[workflow_real_task_test_case_design]]）。改 skill 尤其要这样验，改工具验它的真实调用效果。
2. 结构门机械过：U4 的 reference_validator 全绿 + schema 守卫不报。
3. landing_gate 四条件 + 独立调控者：运行证据 / 注册 / git-tracked / 下游引用，且第二 agent regulator 判引用是真消费边、claim 没偷换 frame。停机权不在改动者手里（接 [[workflow_landing_to_production]] 晋级门）。

粗粒度的"没过"救不了，误差信号必须可操作：指出哪条义务没覆盖、缺在哪、怎么复现（接 [[project_verifiable_checkpoint_experiment]]：1-bit ≈ 无信号）。

方法论 C：可能的方法（point 2c）= 三家族 + 动态选择

三个误差信号源各对应一个解法家族，扎在真实做法上（设计真源有完整扎根三齐）：

• 家族 A 防破坏门（结构）：影响分析接 commit 侧 + gate 一致性 + schema 守卫。对标 gstack 漂移扫描。
• 家族 B 遥测反推闭环（行为）：跨任务挖 receipts 台账找漂移（长期零调用 skill / 读了没生效 / rename 后老名残留）。对标可观测性驱动开发。这是"发现问题→优化"闭环的引擎。
• 家族 C 变更治理生命周期（意图）：提案 / delta / 归档 + 行为验证。对标 OpenSpec delta-archive。

发现问题到优化的闭环四拍：发现（B 挖台账出机械信号）→ 定位（信号带 task_id 沿台账回到具体文件，给可定位反例）→ 优化（定位出的问题本身是一次更新，进 U0 走全程）→ 回验（下一轮 B 确认信号消失）。回路不靠人记得，因为 B 持续产信号。

动态 workflow：检查→决定→任务专属流程（point 3）

本 skill 不是固定序列，是一个"为这个具体更新排流程"的判断引擎。拿到一个更新目标后：

1. 检查（point 3a，要考虑哪些点）：跑 U2 影响分析枚举下游；判更新类型（U0）；从本 skill 取适用的家族和门。检查是机械动作，先有数据再决定。
2. 决定（point 3b，做完检查后再决定）：据检查结果裁剪 U0–U8、选适用的家族/门，产出针对该任务的 plan。裁剪有据：每个省略的步写一句锚回目标特征的理由。决定基于真实情况（下游有多少、是不是 BREAKING、有没有 schema 契约），不套模板。
3. 形成任务专属 dynamic workflow（point 3c）：决定的产物是一份接 phase_runtime plan schema 的 dynamic 计划，由术层执行。同一个 skill 对不同目标产不同的流程。

道术结合（point 4）

术基于道（point 4a）：动态 planner（术）显式读本 skill 取方法论，机械可查它读了道的哪部分（receipt / canary）。不同优化需求产对应术（point 4b）：四种更新类型走不同 plan 路径，由 planner 据 U0 分类生成。能更新整套相关内容（point 4c）：U2 影响分析枚举下游 + 提案带出需联动更新的关联资产，使一次更新能机械地带出它牵动的全部。

区分判据（接 [[workflow_guidance_skill_matrix]] / [[workflow_landing_to_production]] Part 2）：输出 judgment（该怎么更新 / 何时算验证过）= 道，在本 skill；输出调度执行（planner / gate / runner）= 术，在 tools/。术替换后道仍成立。

验收（无上下文 agent 可自判）

一次更新算走完本 skill，当且仅当：U2 影响分析有机械产出（下游清单非空或确证无下游）；U4 结构门 PASS；U5 行为验证由独立 verifier 给非改动者自报；变更记录进 contexts/evolution_changes/；改动锚 task_id 进台账；最终过 landing_gate 四条件。任一缺 = 没走完，按 [[workflow_manage_unexpected]] 动作阶梯处理，不声称完成。

配套工具 / skill（按名引用）

• 术：动态 workflow planner（tools/evolution_workflow/，本程序 P3 建）、reference_validator（影响分析 backlinks / validate / check-indexes）、orthogonality.py（EW-5 skill 间内容/环境正交检查，U4 对 skill 目标自动注入）、deprecation.py（EW-11 过时标记：banner + maturity registry，U3 对 deprecate 目标自动注入）、landing_gate、forcing_closure（行为面三态）、phase_runtime（执行 plan）、session_dispatch（派 Codex 实现）。
• 道：workflow_phase_framework（排 phase 计划）、workflow_landing_to_production（判 landed + 晋级门）、workflow_version_evolution（版本判定）、workflow_requirement_intake（新需求入库）、workflow_guidance_skill_matrix（道术分类 + 联动边）、workflow_manage_unexpected（遇阻阶梯）、workflow_real_task_test_case_design（行为验证）。

已知陷阱（来自实证缺口，非臆测）

• 把"文件改了"当"改对了"：artifact ≠ behavior。修法 = U5 行为验证。
• 漏跑影响分析却不自知：reference_validator 有 backlinks 但漏跑零信号。修法 = U2 强制前置 + U4 commit 侧兜底。
• 静默 schema 破坏：契约文件无版本守卫，旧 plan 跑到 KeyError 才暴露。修法 = U4 schema 守卫。
• 分类 / 联动边延迟过期：被指向的术 skill 改了，联动边 verified 不自动失效。修法 = U6 回写矩阵 + U8 台账预警。
• 自报完成（表演式勤奋）：停机权落改动者手里。修法 = U5 独立调控者裁决。

claim ceiling

证据 observational（纸面设计 + 首个 dogfood FU-11 进行中）。晋级 production（rules/skills/ 顶层）需 ≥1 个真实更新点经本 skill 端到端 + 过 landing_gate + 人确认 + 走 workflow_version_evolution，不在纸上拍 solid。

S6 Dogfood Addendum（2026-07-02，Beta）

S1-S6 的术层 surface 已集中在 tools/evolution_workflow/：planner.py / record.py / maturity.py / reviews.py / trace_mining.py / refresh.py / todo_bridge.py，并由 tools/INDEX.md 的 evolution_workflow 行作为工具入口指针。S6 自指 dogfood 包为 contexts/evolution_changes/2026-07-02-evolution_workflow_refresh-add-capability/。

S6 只支持 bounded claim：refresh.py 对 importable runtime seam 做兼容 guard，当前工作区模式是 real-seam-present guarded，因为 tools/phase_state/reassess/ 存在但未作为 HEAD-landed runtime integration 处理。EW-29 adapter 为 python3 -m tools.evolution_workflow.reviews file_generation|implementation_effect；maturity 记录走 python3 -m tools.evolution_workflow.maturity update。本 DAO skill 保持 Beta；没有 human confirmation 时不得晋级 stable/production。

EW-5 / EW-11 Addendum（2026-07-07，Beta）

两个此前只有方法论描述、没有术层执行手段的缺口补上：

• EW-5 skill 间正交性：tools/evolution_workflow/orthogonality.py。给定目标 skill + 一组比较对象，抽取触发相关文本（frontmatter description + "何时用/触发"类标题段落）算内容重叠 Jaccard 分（无依赖确定性 bag-of-tokens：拉丁词+CJK bigram），并单独判环境正交（是否共享同一条字面触发短语，如相同 backtick 命令）。由 planning.py 的 U4 对 classify_target(target)=="skill" 的目标自动注入 shu_skills，不再只靠 agent 凭记忆判断"这个 skill 会不会跟别的撞"。真实一手扫描 rules/skills/*.md 时发现两个真限制：(a) 递归 rules/skills 会带出 drafts/ 下整本书蒸馏工作目录（7000+ 文件），scan 因此加 --max-files 门槛防止 O(n²) 挂起；(b) 没有 frontmatter description 也没有"何时用"标题的文件，回退文本过薄会让两个无关文件因结构巧合（都以类似标题+紧邻的空心小标题开头）判出 score=1.000 的假阳性——已加 confidence 字段（触发文本 token 数 < 12 标 low）区分这类巧合与真实重叠（如 gemini_image_generation.md vs generate_image.md 的 0.831 真阳性）。
• EW-11 统一标记过时：tools/evolution_workflow/deprecation.py。maturity.py 早就有 deprecated/obsolete 状态枚举，但没有把它写进被标记文件本身的机制——mark 子命令补上：frontmatter 后（或 .py shebang 后/文件顶部）插入标准 banner + 追加一条 maturity registry 行，只 append，从不删除或重写既有内容；已有的 status/superseded_by 字段只在缺失时补，status 已是 deprecated/superseded/obsolete 等终态时不覆盖（避免吞掉更具体的既有说明），否则允许从 live/draft 等活跃态迁移为 deprecated，避免 body banner 说过时、frontmatter 却仍读 live 的自相矛盾。check 做双向一致性核对，audit 只读扫描"已过时未规范化"候选，不自动改写。由 planning.py 的 U3 对 update_type=deprecate 自动注入；U3 因此从"弃用省略"改为"弃用保留"（此前设计假设弃用没有机械动作可执行，现在有了）。
• 两者均以 contexts/evolution/maturity_registry.jsonl、tools/reference_validator.py、既有 frontmatter 约定为基础复用，不建平行台账；测试见 tools/evolution_workflow/tests/test_orthogonality.py / test_deprecation.py，含真实仓库 skill 文件的健全性检查（非纯合成 fixture）。claim ceiling 仍为 bounded：两工具本身有真实单测 + 真实 planner 端到端 wiring 证据，但尚未有独立 sub-agent 的 held-out 行为验证（方法论 B 第 1 条），晋级前仍需走一次真实 dogfood + landing_gate + 人确认。

方法论文件资产类（2026-07-19，Beta）

本 skill 的资产清单从 tools/ + rules/skills/ 扩到第三类：方法论文件——contexts/methodology/ 正文与各域 program 内 methodology/（如 career），含其候选与修订区。承认理由：方法论文本同样是被读、被引用、约束行为的运行资产，改它同样是对运行系统的扰动，此前却没有演进框架接住它（更新即裸改）。方法论体系 campaign 的反馈回路把这类更新接进本 skill 的同一控制论框架；回路拓扑（源→候选队列→周裁决批→三着陆道→四谓词）的机制真源 = adhoc_jobs/methodology_system_buildout_20260719/design/f_loop_design.md §A-§E，本节只收资产类承认与判断面，不复制机制正文。

三家族对这类资产的具体化（信号形态与代码/skill 资产不同，按此取信号、不硬套原 gate）：

• 家族 A 结构面（裁薄）：reference_validator 全量 gate 对 markdown 方法论文件基本空转；活的结构信号只有两个——指针存活 grep（死引用）与 frontmatter 最小契约缺失（consumers: 等字段），由 patrol 面供给（fs_patrol 日巡 + patrol 断言）。
• 家族 B 行为面：读取台账（usage_hook 的 skill_read / receipts）供「谁在读」；零消费与 staleness 由 guardian 产出年龄检查供给（挂靠锚见「修订传播义务」节锚 3）。
• 家族 C 意图面：候选流 = contexts/methodology/candidates/queue.jsonl（append-only；trigger_kind 四类 recurrence / review_convergence / obs_cluster / corpus_synthesis；2026-07-19 已落地首批 4 条真实候选）。轻量变更单（E 条目 + 证据锚 + 版本指纹）替代完整 proposal/delta 五件套——家族 C 对这类资产的裁剪形态。

U0-U8 对这类资产的裁剪基线（裁剪仍显式记理由，不静默跳）：U1 提案 = 队列候选行（evidence_refs + target + sketch）；U2 影响分析 = 指针存活 grep + 消费边清单，非全量 backlinks；U4 结构门 = patrol 断言；U5 行为验证 = 「修订传播义务」节的拉取门强制重读（held-out sub-agent 验证对单条修订成本不成比例）；独立调控者 = 周裁决批（裁决是证据核验非模型意见）；U7 归档锚 = 版本指纹 + 队列状态转移（woven），非 evolution_changes 完整包。走候选队列 + 裁决批落地的方法论更新，视为已走本 skill 的裁剪化实例。

修订传播义务（2026-07-19，Beta）

一次修订 landed ≠ 消费者读到。push 型传播（修订落地时编排者向在跑 lane 注入重读指令）是口头义务，已实证失效——「一句话」节那条失效律（让执行者自我打勾的清单恰是失效本身）在传播环节的重演。义务 = 拉取门为主、push 为辅，对任何有 mid-run 消费者的方法论文件 / 道 skill 修订生效：

1. 版本指纹：每个方法论文件带指纹（SOP tag 或 行数 + 末行 hash）；织入落地时由确定层再生指纹索引（文件→指纹的单文件投影，GENERATED 区）。
2. 边界拉取门：长期 program 的开工卡 / 入口件记录「所读方法论指纹」；phase 边界 / run 起点由确定层比对所记指纹 vs 索引现值，不一致 = flag，须重读修订区才放行。传播从「广播义务」变成「过界检查」，不依赖任何人记得。
3. push 降为第二层 best-effort：修订 commit 落地时仍向在跑 lane 注入重读指令，但保证性来自拉取门。

三实例锚（真实证据，本次扩节时逐条 grep 核实在位）：

1. push 失效实证：career/methodology/METHODOLOGY_OPTIMIZATION_PHASE_v1.md:190（E15——E1-E13 落地后 2/3 lane 新条款零执行痕迹；传播义务写明了也没被执行）。
2. 拉取门已运行先例：adhoc_jobs/context_infra_migration_20260709/RUN_TEMPLATE.md:23（每张派发卡 must_read 必含 program 根 GLOSSARY.md；同文件 :6 起卡缺引用 = gate flag、:42 具名消费者 = 每张派发卡）——「过界检查」形态已在 migration program 实战。
3. 挂靠监测面：periodic_jobs/guardian_health/health_scan.py:46（L3Finding / severity 阈值框架已 live）——staleness 检查挂这里（含「指纹索引 mtime 落后于最新方法论文件 mtime = 织入了没登记」），不新造监控系统。

义务判据（何时必须更新指纹索引）：每次 accept-as-revision / accept-as-new 落地（织入正文或新生文件）即必须同批更新指纹索引 + 一行路由差量（接口裁定 D-SYN-3，同 campaign design/SYSTEM_DESIGN.md：随周裁决批由单 writer 同批 apply）；机械核验 = 指纹索引 mtime 不落后于全部方法论文件的最新 mtime，落后即 guardian finding。零 mid-run 消费者的静默窗内织入免 push（义务自动满足），拉取门在下一次开工时兜住。术层落地（指纹索引生成脚本 + 开工卡义务行）= campaign 队列 LOOP-4；工具未落地前本义务以手工比对执行，不因工具缺位而免除。