project-tiny-context-harness 0.2.57 → 0.2.59

package/assets/skills/context_development_engineer/SKILL.md

@@ -1,108 +1,108 @@
----
-name: context_development_engineer
-description: Use when the user explicitly asks for 开发工程师, 软件工程师, 研发工程师, 开发专家, 工程专家, 技术专家, 开发方案, 研发方案, 工程方案, 技术方案, 实现, 实现方案, 实施计划, 多开agent, subagent, software engineer, senior engineer, engineering expert, development plan, engineering plan, or technical implementation plan in a Minimal Context Harness project. Do not trigger for routine coding, bug fixes, small refactors, package/release work, or generic mentions of code, development, or engineering.
----
-
-# Context Development Engineer
-
-## Package-Managed Boundary
-
-This Skill is generated by `ty-context sync` and owned by the Harness package. Do not edit the generated `context_development_engineer` Skill directly.
-
-Project-specific engineering rules belong in a separate project-local Skill under `<harnessRoot>/skills/development_engineer/SKILL.md`. When a project-local Skill and this package-managed Skill both apply, use the more specific project-local Skill as the primary instruction source while keeping durable conclusions in `project_context/**`. Keep the project-local Skill front matter `description` trigger keywords aligned with this package-managed Skill and the project `AGENTS.md` role-trigger rule; if the project adds or narrows trigger terms, update both places together so agent activation and Tiny Context guidance do not drift apart.
-
-## 目标
-
-帮助 agent 以开发工程师 / 技术专家视角完成实现判断，并把长期工程事实压缩进可恢复的 Minimal Context。
-
-## 工作方式
-
-1. 先读取 `project_context/global.md`、`project_context/architecture.md` 和 `project_context/context.toml`，按 default area、triggers、read_when 选择相关 context。
-2. 先确认用户目标、约束、成功标准、影响产品域、现有验证 / 部署关键路径和风险；能从代码或 Context 发现的事实不要反复询问用户。
-3. `project_context/**` 决定“应该是什么”：模块职责、归属、架构边界、接口方向、契约语义和禁止依赖；代码决定“现在实现到了哪里”。代码不能静默重定义 Context。
-4. 第一处代码编辑前，若任务涉及系统设计、技术方案、架构边界、产品域职责、跨域依赖、API / Schema、模块设计原则、数据契约、状态机或运行语义、验证关键路径或部署关键路径，先编译当前任务契约；契约第一段用 `Context Delta: none|required` 完成唯一正式长期事实判断，再写本次 `Task Contract`。
-5. 普通 bug fix、局部样式、局部实现漂移修复、测试修复或探索性 spike 不更新 Context，可先改代码；一旦形成长期工程结论，继续对齐或交付前必须回写 Context。不要把 Context 机械补成代码改动摘要。
-6. 如果代码、搜索结果或相邻实现与 Context 冲突，显式标记为实现漂移、缺失工作或 Context 过期，不要用当前代码形态反推模块归属。
-7. 涉及已有 Context 的实现判断，先做轻量对齐：
-   - Context expectation
-   - Current code evidence
-   - Gap
-   - Proposed change
-8. 涉及模块原则、模块逻辑、设计原因、API / Schema、状态语义、验证设计或 capability / metric / acceptance claim 时，先做 Module Principle / Design Gate：列出命中的模块设计上下文来源，说明这些原则 / 逻辑控制本次哪些实现或验证选择，再选择实现路径、验证 claim、probe 参数或 fallback。命令、probe 和当前实现形态是执行实例，不能反推或覆盖模块设计目标。
-9. 涉及 Product Surface（Web 页面、移动/桌面屏幕、游戏 UI/HUD/菜单、CLI/TUI 输出、扩展或设备界面）、表单/配置、输入、选择、搜索、筛选、调度/时间、预算/配额/限流或状态反馈的实现方案时，检查当前代码是否只是暴露字段，还是满足了已有 Context、Surface Contract、页面职责和控件任务框架；实现收尾要能给出简短 Surface/Context Conformance 证据。
-   - 若存在 Product Surface Contract，Task Contract 必须包含 Surface Contract Hit、main allows/forbids、drilldown ownership、long-task state requirement、implementation drift 和 verification。
-   - 若缺失且本任务创建 durable surface responsibility，设置 `Context Delta: required`，先用 `context_surface_contract` 或项目 Context 写入具体 surface 职责，再继续实现。
-10. 实现时保持精准修改，优先遵循仓库现有框架、接口、测试和代码风格。
-11. 当用户明确要求 / 允许“多开agent”或使用 subagent，且当前会话存在可用 subagent 工具时，积极把可并行的探索、审查或实现拆分交给 subagent；使用前先复用已有相关 agent，没有合适 agent 或并行度不足时再新开。`wait_agent` 只表示取得结果，不释放资源；subagent 完成、空闲或不再需要时必须调用 `close_agent`，收尾前清理已完成 / 空闲 / 不再需要的 subagent，避免占满后续资源。
-12. 当任务涉及新实现、重构、重复逻辑、模块边界或影响面控制时，先做轻量 abstraction / decomposition scan：
-   - 工程 / RFC / 实现类 Task Contract 包含 `Modularity Check: none|required|exception`；可用 `ty-context check-modularity --file <path> --limit 300` 审计计划编辑文件，用 `make validate-code-modularity` 或 `ty-context check-modularity --touched --limit 300 --fail-on-warning` 做交付前硬审计。若项目本地 Skill 定义了不同 limit，使用项目本地值。
-   - 发现超限 touched file 后，不只记录行数；判断本次是否在该文件加入新职责，并回到本节拆分原则选择产品面、hook、model、adapter、component、service / facade 或 verification helper 等边界。避免只按行数机械拆分、但耦合和职责仍留在原处。
-   - 如果本次不拆，`Modularity Check` 取 `exception`，必须有 `<harnessRoot>/config.yaml` 的 `modularity.waivers` 记录（`path`、收窄 `category`、`reason`、`future_split_boundary`）；交付说明只能补充说明，不是机器豁免。若项目设置 `modularity.policy: strict_except_generated`，legacy waiver 不可用，超限手写源码必须拆分或停止触碰。已豁免历史债也不得继续塞新职责，除非本次任务就是拆分 / 迁移。
-   - 查找相似实现、重复逻辑、紧耦合模块或影响面异常扩散点。
-   - 当一个业务对象、能力或接口的变更需要跨多个 Context、产品域或实现层同步调整时，将该影响范围视为模块边界复核信号；优先评估是否应通过独立模块、服务、facade 或稳定接口收敛依赖，避免通过手工 manifest 长期复制实现暴露面。
-   - 将候选项分为局部重构与长期边界变化，后者按既有 Context-first 规则处理。
-   - 对候选点说明当前重复 / 耦合证据、抽象后的边界、收益、风险和是否值得现在做。
-   - 默认只实施高收益、低风险、语义稳定的候选项。
-   - 不为一次性代码、不稳定语义或纯粹好看的架构做抽象。
-13. 当人工流程呈现重复、确定性、容易漏步骤或顺序影响正确性时，主动评估是否应沉淀为 repo-local tool/script。脚本应放在 owning module 的工具目录并配测试；可恢复的执行入口、参数约束和适用边界写入对应 verification / deployment Context。Skill 只记录这类脚本化机会识别原则，不承载具体模块命令、provider id、artifact 路径或一次性运行结果。
-14. 需要沉淀长期事实时，只更新 `project_context/**`：
-   - 全局工程取舍、跨产品域索引或当前状态写入 `global.md`。
-   - 产品域 API、数据契约、关键约束、入口和风险写入对应 area / subdomain Context。
-   - 跨域接口语义写入 `context_role: contract` 或 manifest role 为 `contract` 的 Context；关键重复验证路径写入 `verification`；关键部署、运行拓扑或云端初始化路径写入 `deployment`；代码入口索引用 `implementation-index`；底层理论源用 `foundation`；历史归档索引用 `archive`。
-   - 新 context unit 可新增 `project_context/areas/<unit>.md`，并更新 `global.md#Context Index`；复杂项目同时更新 `project_context/context.toml`。
-   - 如果 `upgrade` 自动把深层 `.md` 注册成 area，但语义上更像 foundation / contract / archive，后续应显式调整 manifest role；不要依赖自动迁移判断语义。
-15. 实现收尾时做 `Contract Conformance` 和 Context drift check：确认代码没有引入未沉淀的长期事实，且 Context 没有退化成普通实现摘要；交付说明只报告轻量状态：`Context: 已更新 ...` 或 `Context: 本次无长期事实变化`。Conformance 说明本次契约满足情况、未满足或延期项和验证入口；一次性证据、截图结果、测试日志、任务契约和实现摘要不写入 Context。
-16. Context 只能声明验证 / 部署关键路径或验收信号，不能伪造“测试已通过”或“部署已成功”。
-17. Verification / Deployment Role Context 只记录长期可复用的重复执行路径事实：特殊准备、最短命令或路径、预期阶段 / 信号、可接受 warning、已排除的重复探索点。不要记录一次性测试日志、完整输出、临时 JSON、CI artifact、测试报告、release ledger、secret、token、cookie、device id 或 raw payload。
-
-## UI 实现对齐
-
-- UI 实现方案不只检查字段是否接上，还要检查控件是否支持用户任务、输入语义、反馈状态、错误恢复和已有页面/控件契约。
-- 当 current code evidence 显示后端字段、枚举或自由输入直接暴露给用户时，不默认把它当作产品意图；先对照 Context、产品/UIUX Skill 的控件任务框架和项目组件体系判断是否是实现漂移或缺失契约。
-- Contract Conformance 证据应短而具体：命中的已有 Context / 页面契约或 Task Contract、实现如何满足、未满足或延期项、验证入口或手动检查。它属于交付说明，不属于 `project_context/**`。
-
-## 任务契约编译
-
-- 任务契约是当前工程任务的编译产物，不是事实源、tech plan、ADR、implementation doc 或长期 Context；默认留在方案、交付说明或 PR 文本中。
-- `Context Delta` 必须先出现，取值为 `none` 或 `required`：
-  - `none`：本次只是按既有 Context / 架构原则落地，不新增长期事实。
-  - `required`：说明长期事实类型、应写入的 Context / role、需要沉淀的事实，以及明确不写入 Context 的一次性内容。
-- `Task Contract` 用短列表说明 capability、owner、upstream / downstream、allowed / forbidden dependency、input / output / state / persistence、failure / retry / timeout / degraded / recovery、observability、performance、security、non-goals 和 verification path。
-- 触及 Product Surface 时，`Task Contract` 同时说明 surface platform、primary user question、main allows/forbids、drilldown ownership、long-task state requirement、implementation drift 和 conformance verification。
-- 工程 / RFC / 实现类任务的 `Task Contract` 必须包含 `Modularity Check: none|required|exception`：
-  - `none`：没有超限计划 / touched 手写源码文件，或本次没有向超限文件增加新职责。
-  - `required`：拆分是本次验收条件，应按 abstraction / decomposition scan 的职责边界完成。
-  - `exception`：本次触碰超限文件但暂不拆；只有默认 `modularity.policy: scoped_waivers` 允许此路径，且必须已有或同步新增 `<harnessRoot>/config.yaml` `modularity.waivers` 记录文件、收窄分类、原因和后续拆分边界。若项目设置 `modularity.policy: strict_except_generated`，不得用 legacy waiver 绕过超限手写源码，交付说明只记录本次是否新增职责以及为什么没有拆。
-- `Applicable Module Design` 是高风险任务的前置字段：列出命中的 Context / Skill 来源、适用的 Principles、Design Logic 和 Design Rationale，以及它们控制的当前实现或验证选择。
-- `Principle Decision Gate` 要写明首选执行路径、fallback / degraded path 的进入条件，以及什么证据不能证明本次目标。涉及 capability、metric 或 acceptance claim 时，先声明要证明的 claim，再选择命令或 probe。
-- 对长任务、多模块、多 agent、容易发生 `Context Delta` 调头或多轮验证的任务，可以用 `plan.md` 或等价临时计划面暂存 `Context Delta`、`Task Contract`、`Implementation Steps` 和 `Contract Conformance`；它只是临时执行缓存。
-- `plan.md` 中出现的长期工程事实必须提炼回 `project_context/**`；否则不要把临时计划当作事实源、交付产物或后续引用依据。
-- `Context Delta: required` 时先更新 `project_context/**`，再继续实现；`none` 时直接按 Task Contract 实现。
-- `Contract Conformance` 是交付前的软检查：实现偏差修实现，契约遗漏回 Task Contract，长期事实缺失回 `Context Delta` 并先更新 Context。
-- 不为普通代码修改、bug fix、小重构、package/release 处理、测试修复或探索性 spike 强制编译任务契约。
-
-## 模块设计上下文写法
-
-- 模块设计上下文应是 Minimal Context，不是设计论文；只保留短、准、稳定、会影响后续实现或验证选择的内容。
-- `Principles` 写稳定执行约束；`Design Logic` 写模块如何判断、选择、降级或组合能力；`Design Rationale` 只写会改变后续判断的原因。
-- `Current Standard`、`Verification Paths`、阈值、命令和 probe 参数是当前执行实例，不是永久原则；规则变化时更新对应 Context，而不是让旧命令继续定义目标。
-- 一次性证据、历史过程、完整日志、临时 JSON、raw payload、测试报告和任务契约不进入高频模块原则段。
-
-## 输出边界
-
-- 不默认创建 `.work_products/**`、tech plan、ADR、implementation doc、review/test/release 文档。
-- 不要求 lifecycle phase、plan task、phase gate 或阶段 Skill。
-- 如果用户明确要求独立开发方案、技术方案或实现说明，可以临时生成；长期事实仍要提炼回 `project_context/**`。
-- 如果用户只是要求普通代码修改、修 bug、小重构、package/release 处理，或只是泛泛提到“代码 / 开发 / engineering”，不需要触发本 Skill；只有明确角色名或强相关产物名指向工程方案、实现方案、实施计划、技术判断或长期工程事实沉淀时才使用。
-
-## 建议沉淀位置
-
-- `global.md#Design Rationale`：跨模块工程取舍。
-- `global.md#Current State`：影响后续恢复的实现状态。
-- `areas/*.md#User / System Contract`：模块可见行为、API、CLI、UI 或数据契约。
-- `areas/*.md#Core Data / API / State`：关键数据结构、接口、状态流或规则。
-- `areas/*.md#Key Constraints`：性能、安全、兼容、集成或维护约束。
-- `areas/*.md#Code Entry Points`：未来 agent 需要快速定位的代码入口。
-- `areas/*/verification.md` 或 role=`verification` Context：关键测试、smoke、CI、probe 或验证重复执行路径。
-- `areas/*/deployment.md` 或 role=`deployment` Context：关键部署、云端初始化、运行拓扑、健康检查或回滚重复执行路径。
-- `project_context/context.toml`：复杂项目的产品域 area/context_unit、role、触发词、按需读取策略和可选边界规则。
+---
+name: context_development_engineer
+description: Use when the user explicitly asks for 开发工程师, 软件工程师, 研发工程师, 开发专家, 工程专家, 技术专家, 开发方案, 研发方案, 工程方案, 技术方案, 实现, 实现方案, 实施计划, 多开agent, subagent, software engineer, senior engineer, engineering expert, development plan, engineering plan, or technical implementation plan in a Minimal Context Harness project. Do not trigger for routine coding, bug fixes, small refactors, package/release work, or generic mentions of code, development, or engineering.
+---
+
+# Context Development Engineer
+
+## Package-Managed Boundary
+
+This Skill is generated by `ty-context sync` and owned by the Harness package. Do not edit the generated `context_development_engineer` Skill directly.
+
+Project-specific engineering rules belong in a separate project-local Skill under `<harnessRoot>/skills/development_engineer/SKILL.md`. When a project-local Skill and this package-managed Skill both apply, use the more specific project-local Skill as the primary instruction source while keeping durable conclusions in `project_context/**`. Keep the project-local Skill front matter `description` trigger keywords aligned with this package-managed Skill and the project `AGENTS.md` role-trigger rule; if the project adds or narrows trigger terms, update both places together so agent activation and Tiny Context guidance do not drift apart.
+
+## 目标
+
+帮助 agent 以开发工程师 / 技术专家视角完成实现判断，并把长期工程事实压缩进可恢复的 Minimal Context。
+
+## 工作方式
+
+1. 先读取 `project_context/global.md`、`project_context/architecture.md` 和 `project_context/context.toml`，按 default area、triggers、read_when 选择相关 context。
+2. 先确认用户目标、约束、成功标准、影响产品域、现有验证 / 部署关键路径和风险；能从代码或 Context 发现的事实不要反复询问用户。
+3. `project_context/**` 决定“应该是什么”：模块职责、归属、架构边界、接口方向、契约语义和禁止依赖；代码决定“现在实现到了哪里”。代码不能静默重定义 Context。
+4. 第一处代码编辑前，若任务涉及系统设计、技术方案、架构边界、产品域职责、跨域依赖、API / Schema、模块设计原则、数据契约、状态机或运行语义、验证关键路径或部署关键路径，先编译当前任务契约；契约第一段用 `Context Delta: none|required` 完成唯一正式长期事实判断，再写本次 `Task Contract`。
+5. 普通 bug fix、局部样式、局部实现漂移修复、测试修复或探索性 spike 不更新 Context，可先改代码；一旦形成长期工程结论，继续对齐或交付前必须回写 Context。不要把 Context 机械补成代码改动摘要。
+6. 如果代码、搜索结果或相邻实现与 Context 冲突，显式标记为实现漂移、缺失工作或 Context 过期，不要用当前代码形态反推模块归属。
+7. 涉及已有 Context 的实现判断，先做轻量对齐：
+   - Context expectation
+   - Current code evidence
+   - Gap
+   - Proposed change
+8. 涉及模块原则、模块逻辑、设计原因、API / Schema、状态语义、验证设计或 capability / metric / acceptance claim 时，先做 Module Principle / Design Gate：列出命中的模块设计上下文来源，说明这些原则 / 逻辑控制本次哪些实现或验证选择，再选择实现路径、验证 claim、probe 参数或 fallback。命令、probe 和当前实现形态是执行实例，不能反推或覆盖模块设计目标。
+9. 涉及 Product Surface（Web 页面、移动/桌面屏幕、游戏 UI/HUD/菜单、CLI/TUI 输出、扩展或设备界面）、表单/配置、输入、选择、搜索、筛选、调度/时间、预算/配额/限流或状态反馈的实现方案时，检查当前代码是否只是暴露字段，还是满足了已有 Context、Surface Contract、页面职责和控件任务框架；实现收尾要能给出简短 Surface/Context Conformance 证据。
+   - 若存在 Product Surface Contract，Task Contract 必须包含 Surface Contract Hit、main allows/forbids、drilldown ownership、long-task state requirement、implementation drift 和 verification。
+   - 若缺失且本任务创建 durable surface responsibility，设置 `Context Delta: required`，先用 `context_surface_contract` 或项目 Context 写入具体 surface 职责，再继续实现。
+10. 实现时保持精准修改，优先遵循仓库现有框架、接口、测试和代码风格。
+11. 当用户明确要求 / 允许“多开agent”或使用 subagent，且当前会话存在可用 subagent 工具时，积极把可并行的探索、审查或实现拆分交给 subagent；使用前先复用已有相关 agent，没有合适 agent 或并行度不足时再新开。`wait_agent` 只表示取得结果，不释放资源；subagent 完成、空闲或不再需要时必须调用 `close_agent`，收尾前清理已完成 / 空闲 / 不再需要的 subagent，避免占满后续资源。
+12. 当任务涉及新实现、重构、重复逻辑、模块边界或影响面控制时，先做轻量 abstraction / decomposition scan：
+   - 工程 / RFC / 实现类 Task Contract 包含 `Modularity Check: none|required|exception`；可用 `ty-context check-modularity --file <path> --limit 300` 审计计划编辑文件，用 `make validate-code-modularity` 或 `ty-context check-modularity --touched --limit 300 --fail-on-warning` 做交付前硬审计。若项目本地 Skill 定义了不同 limit，使用项目本地值。
+   - 发现超限 touched file 后，不只记录行数；判断本次是否在该文件加入新职责，并回到本节拆分原则选择产品面、hook、model、adapter、component、service / facade 或 verification helper 等边界。避免只按行数机械拆分、但耦合和职责仍留在原处。
+   - 如果本次不拆，`Modularity Check` 取 `exception`，必须有 `<harnessRoot>/config.yaml` 的 `modularity.waivers` 记录（`path`、收窄 `category`、`reason`、`future_split_boundary`）；交付说明只能补充说明，不是机器豁免。若项目设置 `modularity.policy: strict_except_generated`，legacy waiver 不可用，超限手写源码必须拆分或停止触碰。已豁免历史债也不得继续塞新职责，除非本次任务就是拆分 / 迁移。
+   - 查找相似实现、重复逻辑、紧耦合模块或影响面异常扩散点。
+   - 当一个业务对象、能力或接口的变更需要跨多个 Context、产品域或实现层同步调整时，将该影响范围视为模块边界复核信号；优先评估是否应通过独立模块、服务、facade 或稳定接口收敛依赖，避免通过手工 manifest 长期复制实现暴露面。
+   - 将候选项分为局部重构与长期边界变化，后者按既有 Context-first 规则处理。
+   - 对候选点说明当前重复 / 耦合证据、抽象后的边界、收益、风险和是否值得现在做。
+   - 默认只实施高收益、低风险、语义稳定的候选项。
+   - 不为一次性代码、不稳定语义或纯粹好看的架构做抽象。
+13. 当人工流程呈现重复、确定性、容易漏步骤或顺序影响正确性时，主动评估是否应沉淀为 repo-local tool/script。脚本应放在 owning module 的工具目录并配测试；可恢复的执行入口、参数约束和适用边界写入对应 verification / deployment Context。Skill 只记录这类脚本化机会识别原则，不承载具体模块命令、provider id、artifact 路径或一次性运行结果。
+14. 需要沉淀长期事实时，只更新 `project_context/**`：
+   - 全局工程取舍、跨产品域索引或当前状态写入 `global.md`。
+   - 产品域 API、数据契约、关键约束、入口和风险写入对应 area / subdomain Context。
+   - 跨域接口语义写入 `context_role: contract` 或 manifest role 为 `contract` 的 Context；关键重复验证路径写入 `verification`；关键部署、运行拓扑或云端初始化路径写入 `deployment`；代码入口索引用 `implementation-index`；底层理论源用 `foundation`；历史归档索引用 `archive`。
+   - 新 context unit 可新增 `project_context/areas/<unit>.md`，并更新 `global.md#Context Index`；复杂项目同时更新 `project_context/context.toml`。
+   - 如果 `upgrade` 自动把深层 `.md` 注册成 area，但语义上更像 foundation / contract / archive，后续应显式调整 manifest role；不要依赖自动迁移判断语义。
+15. 实现收尾时做 `Contract Conformance` 和 Context drift check：确认代码没有引入未沉淀的长期事实，且 Context 没有退化成普通实现摘要；交付说明只报告轻量状态：`Context: 已更新 ...` 或 `Context: 本次无长期事实变化`。Conformance 说明本次契约满足情况、未满足或延期项和验证入口；一次性证据、截图结果、测试日志、任务契约和实现摘要不写入 Context。
+16. Context 只能声明验证 / 部署关键路径或验收信号，不能伪造“测试已通过”或“部署已成功”。
+17. Verification / Deployment Role Context 只记录长期可复用的重复执行路径事实：特殊准备、最短命令或路径、预期阶段 / 信号、可接受 warning、已排除的重复探索点。不要记录一次性测试日志、完整输出、临时 JSON、CI artifact、测试报告、release ledger、secret、token、cookie、device id 或 raw payload。
+
+## UI 实现对齐
+
+- UI 实现方案不只检查字段是否接上，还要检查控件是否支持用户任务、输入语义、反馈状态、错误恢复和已有页面/控件契约。
+- 当 current code evidence 显示后端字段、枚举或自由输入直接暴露给用户时，不默认把它当作产品意图；先对照 Context、产品/UIUX Skill 的控件任务框架和项目组件体系判断是否是实现漂移或缺失契约。
+- Contract Conformance 证据应短而具体：命中的已有 Context / 页面契约或 Task Contract、实现如何满足、未满足或延期项、验证入口或手动检查。它属于交付说明，不属于 `project_context/**`。
+
+## 任务契约编译
+
+- 任务契约是当前工程任务的编译产物，不是事实源、tech plan、ADR、implementation doc 或长期 Context；默认留在方案、交付说明或 PR 文本中。
+- `Context Delta` 必须先出现，取值为 `none` 或 `required`：
+  - `none`：本次只是按既有 Context / 架构原则落地，不新增长期事实。
+  - `required`：说明长期事实类型、应写入的 Context / role、需要沉淀的事实，以及明确不写入 Context 的一次性内容。
+- `Task Contract` 用短列表说明 capability、owner、upstream / downstream、allowed / forbidden dependency、input / output / state / persistence、failure / retry / timeout / degraded / recovery、observability、performance、security、non-goals 和 verification path。
+- 触及 Product Surface 时，`Task Contract` 同时说明 surface platform、primary user question、main allows/forbids、drilldown ownership、long-task state requirement、implementation drift 和 conformance verification。
+- 工程 / RFC / 实现类任务的 `Task Contract` 必须包含 `Modularity Check: none|required|exception`：
+  - `none`：没有超限计划 / touched 手写源码文件，或本次没有向超限文件增加新职责。
+  - `required`：拆分是本次验收条件，应按 abstraction / decomposition scan 的职责边界完成。
+  - `exception`：本次触碰超限文件但暂不拆；只有默认 `modularity.policy: scoped_waivers` 允许此路径，且必须已有或同步新增 `<harnessRoot>/config.yaml` `modularity.waivers` 记录文件、收窄分类、原因和后续拆分边界。若项目设置 `modularity.policy: strict_except_generated`，不得用 legacy waiver 绕过超限手写源码，交付说明只记录本次是否新增职责以及为什么没有拆。
+- `Applicable Module Design` 是高风险任务的前置字段：列出命中的 Context / Skill 来源、适用的 Principles、Design Logic 和 Design Rationale，以及它们控制的当前实现或验证选择。
+- `Principle Decision Gate` 要写明首选执行路径、fallback / degraded path 的进入条件，以及什么证据不能证明本次目标。涉及 capability、metric 或 acceptance claim 时，先声明要证明的 claim，再选择命令或 probe。
+- 对长任务、多模块、多 agent、容易发生 `Context Delta` 调头或多轮验证的任务，可以用 `plan.md` 或等价临时计划面暂存 `Context Delta`、`Task Contract`、`Implementation Steps` 和 `Contract Conformance`；它只是临时执行缓存。
+- `plan.md` 中出现的长期工程事实必须提炼回 `project_context/**`；否则不要把临时计划当作事实源、交付产物或后续引用依据。
+- `Context Delta: required` 时先更新 `project_context/**`，再继续实现；`none` 时直接按 Task Contract 实现。
+- `Contract Conformance` 是交付前的软检查：实现偏差修实现，契约遗漏回 Task Contract，长期事实缺失回 `Context Delta` 并先更新 Context。
+- 不为普通代码修改、bug fix、小重构、package/release 处理、测试修复或探索性 spike 强制编译任务契约。
+
+## 模块设计上下文写法
+
+- 模块设计上下文应是 Minimal Context，不是设计论文；只保留短、准、稳定、会影响后续实现或验证选择的内容。
+- `Principles` 写稳定执行约束；`Design Logic` 写模块如何判断、选择、降级或组合能力；`Design Rationale` 只写会改变后续判断的原因。
+- `Current Standard`、`Verification Paths`、阈值、命令和 probe 参数是当前执行实例，不是永久原则；规则变化时更新对应 Context，而不是让旧命令继续定义目标。
+- 一次性证据、历史过程、完整日志、临时 JSON、raw payload、测试报告和任务契约不进入高频模块原则段。
+
+## 输出边界
+
+- 不默认创建 `.work_products/**`、tech plan、ADR、implementation doc、review/test/release 文档。
+- 不要求 lifecycle phase、plan task、phase gate 或阶段 Skill。
+- 如果用户明确要求独立开发方案、技术方案或实现说明，可以临时生成；长期事实仍要提炼回 `project_context/**`。
+- 如果用户只是要求普通代码修改、修 bug、小重构、package/release 处理，或只是泛泛提到“代码 / 开发 / engineering”，不需要触发本 Skill；只有明确角色名或强相关产物名指向工程方案、实现方案、实施计划、技术判断或长期工程事实沉淀时才使用。
+
+## 建议沉淀位置
+
+- `global.md#Design Rationale`：跨模块工程取舍。
+- `global.md#Current State`：影响后续恢复的实现状态。
+- `areas/*.md#User / System Contract`：模块可见行为、API、CLI、UI 或数据契约。
+- `areas/*.md#Core Data / API / State`：关键数据结构、接口、状态流或规则。
+- `areas/*.md#Key Constraints`：性能、安全、兼容、集成或维护约束。
+- `areas/*.md#Code Entry Points`：未来 agent 需要快速定位的代码入口。
+- `areas/*/verification.md` 或 role=`verification` Context：关键测试、smoke、CI、probe 或验证重复执行路径。
+- `areas/*/deployment.md` 或 role=`deployment` Context：关键部署、云端初始化、运行拓扑、健康检查或回滚重复执行路径。
+- `project_context/context.toml`：复杂项目的产品域 area/context_unit、role、触发词、按需读取策略和可选边界规则。

package/assets/skills/context_full_project_export/SKILL.md

@@ -1,55 +1,55 @@
----
-name: context_full_project_export
-description: Use when the user explicitly asks to 导出尽可能详细的项目全量上下文, 全量上下文导出, 项目上下文全量导出, full project context export, export full project context, project context export, 当前项目代码实现, 代码级实现导出, or code-level implementation export in a Minimal Context Harness project.
----
-
-# Context Full Project Export
-
-## Package-Managed Boundary
-
-This Skill is generated by `ty-context sync` and owned by the Harness package. Do not edit the generated `context_full_project_export` Skill directly.
-
-This Skill creates a temporary export artifact only. It does not author durable Context and does not change `project_context/context.toml`.
-
-## Purpose
-
-When the user needs a full project context export, create a temporary Markdown bundle that collects project Context, key agent guidance, architecture/module facts and useful entry points for copying into an external tool or one-off discussion.
-
-When the user needs a code-level implementation export, create one temporary Markdown snapshot of current source and engineering configuration files for upload to Web GPT or another external model.
-
-## Workflow
-
-1. Prefer the package CLI to generate both temporary artifacts in one command. Do not hand-write tracked export documents:
-   - `npx --yes --package project-tiny-context-harness@latest ty-context export-context --all`
-2. Use `--full` when only the project Context bundle is needed:
-   - `npx --yes --package project-tiny-context-harness@latest ty-context export-context --full`
-3. Use `--code` when only the code-level implementation snapshot is needed. It generates one Markdown file by default:
-   - `npx --yes --package project-tiny-context-harness@latest ty-context export-context --code`
-4. Custom output paths are allowed only for single-artifact modes and must stay under the temporary export directory. `--all` does not accept `--output`:
-   - `npx --yes --package project-tiny-context-harness@latest ty-context export-context --full --output tmp/ty-context/context-exports/my-export.md`
-   - `npx --yes --package project-tiny-context-harness@latest ty-context export-context --code --output tmp/ty-context/context-exports/my-code-export.md`
-5. Use dry-run mode to inspect planned sources before writing:
-   - `npx --yes --package project-tiny-context-harness@latest ty-context export-context --all --check`
-   - `npx --yes --package project-tiny-context-harness@latest ty-context export-context --full --check`
-   - `npx --yes --package project-tiny-context-harness@latest ty-context export-context --code --check`
-6. After exporting, report artifact paths, source counts and warnings to the user. Do not summarize export contents back into Context.
-
-## Output Boundaries
-
-- Export artifacts must remain temporary export artifacts, not Context.
-- `--full` defaults to `tmp/ty-context/context-exports/full-project-context-<timestamp>.md`.
-- `--code` defaults to `tmp/ty-context/context-exports/code-level-implementation-<timestamp>/code-level-implementation.md`.
-- `--all` generates both default artifacts with the same timestamp.
-- `--all` does not accept `--output`; custom filenames are supported only for `--full` or `--code`.
-- `--code` creates one Markdown file, not shards or `all.md`.
-- Do not output to `project_context/**`.
-- Do not modify `project_context/context.toml`.
-- Do not register export artifacts as `[[context]]`, `implementation-index` or any Context graph node.
-- Do not write tracked docs; if the user asks for an ordinary docs path, redirect to `tmp/ty-context/context-exports/**`.
-- Export contents may include redaction warnings; do not bypass secret/token/cookie/password/api_key filtering.
-
-## Handoff
-
-- Report `Export: generated <path>` or `Export: check completed; no files written`.
-- If the CLI rejects an output path, explain that this prevents temporary exports from polluting durable fact sources and suggest `tmp/ty-context/context-exports/<name>.md`.
-- Context drift check should be `Context: no durable project facts changed` unless the task also changes Harness rules.
+---
+name: context_full_project_export
+description: Use when the user explicitly asks to 导出尽可能详细的项目全量上下文, 全量上下文导出, 项目上下文全量导出, full project context export, export full project context, project context export, 当前项目代码实现, 代码级实现导出, or code-level implementation export in a Minimal Context Harness project.
+---
+
+# Context Full Project Export
+
+## Package-Managed Boundary
+
+This Skill is generated by `ty-context sync` and owned by the Harness package. Do not edit the generated `context_full_project_export` Skill directly.
+
+This Skill creates a temporary export artifact only. It does not author durable Context and does not change `project_context/context.toml`.
+
+## Purpose
+
+When the user needs a full project context export, create a temporary Markdown bundle that collects project Context, key agent guidance, architecture/module facts and useful entry points for copying into an external tool or one-off discussion.
+
+When the user needs a code-level implementation export, create one temporary Markdown snapshot of current source and engineering configuration files for upload to Web GPT or another external model.
+
+## Workflow
+
+1. Prefer the package CLI to generate both temporary artifacts in one command. Do not hand-write tracked export documents:
+   - `npx --yes --package project-tiny-context-harness@latest ty-context export-context --all`
+2. Use `--full` when only the project Context bundle is needed:
+   - `npx --yes --package project-tiny-context-harness@latest ty-context export-context --full`
+3. Use `--code` when only the code-level implementation snapshot is needed. It generates one Markdown file by default:
+   - `npx --yes --package project-tiny-context-harness@latest ty-context export-context --code`
+4. Custom output paths are allowed only for single-artifact modes and must stay under the temporary export directory. `--all` does not accept `--output`:
+   - `npx --yes --package project-tiny-context-harness@latest ty-context export-context --full --output tmp/ty-context/context-exports/my-export.md`
+   - `npx --yes --package project-tiny-context-harness@latest ty-context export-context --code --output tmp/ty-context/context-exports/my-code-export.md`
+5. Use dry-run mode to inspect planned sources before writing:
+   - `npx --yes --package project-tiny-context-harness@latest ty-context export-context --all --check`
+   - `npx --yes --package project-tiny-context-harness@latest ty-context export-context --full --check`
+   - `npx --yes --package project-tiny-context-harness@latest ty-context export-context --code --check`
+6. After exporting, report artifact paths, source counts and warnings to the user. Do not summarize export contents back into Context.
+
+## Output Boundaries
+
+- Export artifacts must remain temporary export artifacts, not Context.
+- `--full` defaults to `tmp/ty-context/context-exports/full-project-context-<timestamp>.md`.
+- `--code` defaults to `tmp/ty-context/context-exports/code-level-implementation-<timestamp>/code-level-implementation.md`.
+- `--all` generates both default artifacts with the same timestamp.
+- `--all` does not accept `--output`; custom filenames are supported only for `--full` or `--code`.
+- `--code` creates one Markdown file, not shards or `all.md`.
+- Do not output to `project_context/**`.
+- Do not modify `project_context/context.toml`.
+- Do not register export artifacts as `[[context]]`, `implementation-index` or any Context graph node.
+- Do not write tracked docs; if the user asks for an ordinary docs path, redirect to `tmp/ty-context/context-exports/**`.
+- Export contents may include redaction warnings; do not bypass secret/token/cookie/password/api_key filtering.
+
+## Handoff
+
+- Report `Export: generated <path>` or `Export: check completed; no files written`.
+- If the CLI rejects an output path, explain that this prevents temporary exports from polluting durable fact sources and suggest `tmp/ty-context/context-exports/<name>.md`.
+- Context drift check should be `Context: no durable project facts changed` unless the task also changes Harness rules.

package/assets/skills/context_harness_upgrade/SKILL.md

@@ -1,60 +1,60 @@
----
-name: context_harness_upgrade
-description: Use when the user asks to upgrade Tiny Context, update Tiny Context, use the Tiny Context upgrade skill to upgrade this project, upgrade project-tiny-context-harness, run ty-context upgrade, run make ty-context-upgrade, Project Tiny Context Harness upgrade, 用 Tiny Context upgrade skill 升级这个项目, 升级 tiny context, 升级tiny context, or 更新 project-tiny-context-harness in a Minimal Context Harness project.
----
-
-# Context Harness Upgrade
-
-## Package-Managed Boundary
-
-This Skill is generated by `ty-context sync` and owned by the Harness package. Do not edit the generated `context_harness_upgrade` Skill directly.
-
-This Skill handles Harness package upgrade and migration orchestration only. It does not author product facts, refactor business code, replace project tests or prove application quality.
-
-## Purpose
-
-When the user asks to upgrade Tiny Context / Project Tiny Context Harness in an existing project, run the canonical `upgrade` path, handle only migration-scoped follow-up, and leave durable project semantics to the project Context and user-owned code. A `sync-only` release means no new migration is expected; it does not change the default upgrade entry for explicit upgrade requests.
-
-## Workflow
-
-1. Read the project routing and Context entry points before changing files:
-   - `AGENTS.md`
-   - `project_context/global.md`
-   - `project_context/architecture.md`
-   - `project_context/context.toml`
-2. Inspect the working tree with `git status --short`. Do not revert unrelated user changes.
-3. Prefer project wrappers when present:
-   - `make ty-context-sync`
-   - `make ty-context-upgrade`
-   - `make ty-context-doctor`
-   - `make validate-context`
-4. If no wrapper exists, use the package CLI explicitly:
-   - `npx --yes --package project-tiny-context-harness@latest ty-context sync`
-   - `npx --yes --package project-tiny-context-harness@latest ty-context upgrade --check`
-   - `npx --yes --package project-tiny-context-harness@latest ty-context upgrade`
-   - `npx --yes --package project-tiny-context-harness@latest ty-context doctor`
-5. Run `upgrade --check` when useful, then run `upgrade`. This remains the default after package updates and for explicit upgrade requests because it plans migrations, applies safe migrations, refreshes managed assets and runs diagnostics.
-6. Do not run standalone `sync` before `upgrade` for explicit upgrade requests. A direct `sync` is only a shortcut for releases explicitly marked `sync-only` when the user asks for managed-asset refresh instead of upgrade diagnostics.
-7. Do not run standalone `sync` after a successful `upgrade` unless the project wrapper did not run sync or the user explicitly asks for another managed-asset refresh.
-8. If `upgrade --check` or `upgrade` reports only `safe_pending` items and the command succeeds, do not invent additional manual cleanup.
-9. If the report includes `manual_required` or `blocked`, handle only the listed migration scope. Use `project_context/context.toml`, role placement scan and the existing area graph to decide placement. Do not guess product or business semantics.
-10. If the report includes `blocked`, treat it as a write preflight failure: resolve the blocked migration scope and rerun `upgrade` before expecting safe migrations or managed asset sync to have been applied.
-11. Run diagnostics after migration-scoped follow-up:
-   - `make ty-context-doctor` or the CLI `doctor`
-   - `make validate-context`
-12. Report commands run, migration status, diagnostics, files changed and any remaining manual items. Use `Context: no durable project facts changed` unless the upgrade exposed or required a real long-term project fact change.
-
-## Manual Handling Rules
-
-- `manual_required` means the Harness detected a migration-scoped item but cannot safely choose the project meaning. Fix it only when the existing Context or file structure proves the intended placement.
-- `blocked` means the safe target already exists or another conflict prevents a mechanical write. Do not overwrite. Compare source and target, preserve user content and ask for direction if the conflict cannot be resolved from project facts.
-- Deprecated override Skills under `ty-context-managed/override_skills/**` should be migrated to standalone project-local Skills only when their content is still relevant. Do not merge them into package-managed default Skills.
-- Ambiguous Context roles should not be guessed from filenames like `api.md`, `notes.md` or `main.md` alone. Register a role only when the manifest, path convention or durable content makes it clear.
-- If `upgrade` creates default `project_context/areas/main.md` or `project_context/areas/main/verification.md` but `project_context/context.toml` already declares real project areas and does not register `main`, remove those generated defaults instead of preserving them as durable project facts. If `main` is registered or contains user-authored facts, do not delete it automatically.
-
-## Boundaries
-
-- Do not restore legacy stage workflow, sprint documents or phase gates.
-- Do not modify application code, product behavior, deployment settings or tests unless the user explicitly asks or a migration report points to a Harness-owned file in that scope.
-- Do not write one-off command output, release logs, diagnostics or temporary migration notes into `project_context/**`.
-- Do not edit package-managed generated surfaces directly in a consumer project unless the change is part of a migration conflict that cannot be resolved another way. Prefer rerunning `upgrade` / `sync` from the package source.
+---
+name: context_harness_upgrade
+description: Use when the user asks to upgrade Tiny Context, update Tiny Context, use the Tiny Context upgrade skill to upgrade this project, upgrade project-tiny-context-harness, run ty-context upgrade, run make ty-context-upgrade, Project Tiny Context Harness upgrade, 用 Tiny Context upgrade skill 升级这个项目, 升级 tiny context, 升级tiny context, or 更新 project-tiny-context-harness in a Minimal Context Harness project.
+---
+
+# Context Harness Upgrade
+
+## Package-Managed Boundary
+
+This Skill is generated by `ty-context sync` and owned by the Harness package. Do not edit the generated `context_harness_upgrade` Skill directly.
+
+This Skill handles Harness package upgrade and migration orchestration only. It does not author product facts, refactor business code, replace project tests or prove application quality.
+
+## Purpose
+
+When the user asks to upgrade Tiny Context / Project Tiny Context Harness in an existing project, run the canonical `upgrade` path, handle only migration-scoped follow-up, and leave durable project semantics to the project Context and user-owned code. A `sync-only` release means no new migration is expected; it does not change the default upgrade entry for explicit upgrade requests.
+
+## Workflow
+
+1. Read the project routing and Context entry points before changing files:
+   - `AGENTS.md`
+   - `project_context/global.md`
+   - `project_context/architecture.md`
+   - `project_context/context.toml`
+2. Inspect the working tree with `git status --short`. Do not revert unrelated user changes.
+3. Prefer project wrappers when present:
+   - `make ty-context-sync`
+   - `make ty-context-upgrade`
+   - `make ty-context-doctor`
+   - `make validate-context`
+4. If no wrapper exists, use the package CLI explicitly:
+   - `npx --yes --package project-tiny-context-harness@latest ty-context sync`
+   - `npx --yes --package project-tiny-context-harness@latest ty-context upgrade --check`
+   - `npx --yes --package project-tiny-context-harness@latest ty-context upgrade`
+   - `npx --yes --package project-tiny-context-harness@latest ty-context doctor`
+5. Run `upgrade --check` when useful, then run `upgrade`. This remains the default after package updates and for explicit upgrade requests because it plans migrations, applies safe migrations, refreshes managed assets and runs diagnostics.
+6. Do not run standalone `sync` before `upgrade` for explicit upgrade requests. A direct `sync` is only a shortcut for releases explicitly marked `sync-only` when the user asks for managed-asset refresh instead of upgrade diagnostics.
+7. Do not run standalone `sync` after a successful `upgrade` unless the project wrapper did not run sync or the user explicitly asks for another managed-asset refresh.
+8. If `upgrade --check` or `upgrade` reports only `safe_pending` items and the command succeeds, do not invent additional manual cleanup.
+9. If the report includes `manual_required` or `blocked`, handle only the listed migration scope. Use `project_context/context.toml`, role placement scan and the existing area graph to decide placement. Do not guess product or business semantics.
+10. If the report includes `blocked`, treat it as a write preflight failure: resolve the blocked migration scope and rerun `upgrade` before expecting safe migrations or managed asset sync to have been applied.
+11. Run diagnostics after migration-scoped follow-up:
+   - `make ty-context-doctor` or the CLI `doctor`
+   - `make validate-context`
+12. Report commands run, migration status, diagnostics, files changed and any remaining manual items. Use `Context: no durable project facts changed` unless the upgrade exposed or required a real long-term project fact change.
+
+## Manual Handling Rules
+
+- `manual_required` means the Harness detected a migration-scoped item but cannot safely choose the project meaning. Fix it only when the existing Context or file structure proves the intended placement.
+- `blocked` means the safe target already exists or another conflict prevents a mechanical write. Do not overwrite. Compare source and target, preserve user content and ask for direction if the conflict cannot be resolved from project facts.
+- Deprecated override Skills under `ty-context-managed/override_skills/**` should be migrated to standalone project-local Skills only when their content is still relevant. Do not merge them into package-managed default Skills.
+- Ambiguous Context roles should not be guessed from filenames like `api.md`, `notes.md` or `main.md` alone. Register a role only when the manifest, path convention or durable content makes it clear.
+- If `upgrade` creates default `project_context/areas/main.md` or `project_context/areas/main/verification.md` but `project_context/context.toml` already declares real project areas and does not register `main`, remove those generated defaults instead of preserving them as durable project facts. If `main` is registered or contains user-authored facts, do not delete it automatically.
+
+## Boundaries
+
+- Do not restore legacy stage workflow, sprint documents or phase gates.
+- Do not modify application code, product behavior, deployment settings or tests unless the user explicitly asks or a migration report points to a Harness-owned file in that scope.
+- Do not write one-off command output, release logs, diagnostics or temporary migration notes into `project_context/**`.
+- Do not edit package-managed generated surfaces directly in a consumer project unless the change is part of a migration conflict that cannot be resolved another way. Prefer rerunning `upgrade` / `sync` from the package source.