project-tiny-context-harness 0.8.4 → 0.8.5

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.

package/assets/skills/context_product_plan/SKILL.md

@@ -1,88 +1,108 @@
----
-name: context_product_plan
-description: Use when the user explicitly asks for 产品方案, 产品经理, 产品专家, 需求方案, 功能方案, 业务规则方案, 用户故事方案, 验收标准方案, 产品规划方案, product plan, product manager, product expert, product spec, or PM spec in a Minimal Context Harness project. Do not trigger for ordinary coding, debugging, package work, or generic mentions of 产品, product, or requirements.
----
-
-# Context Product Plan
-
-## Package-Managed Boundary
-
-This Skill is generated by `ty-context sync` and owned by the Harness package. Do not edit the generated `context_product_plan` Skill directly.
-
-Project-specific product planning rules belong in a separate project-local Skill under `<harnessRoot>/skills/product_plan/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/context.toml`，按 default area、triggers、read_when 选择相关 context。
-2. 和用户澄清或整理：目标用户、产品/页面定位、核心问题、用户需要什么、产品需要提供的内容/能力/反馈、主要流程、验收信号、非目标、约束、风险和受影响模块。
-3. 涉及 Product Surface（Web 页面、移动/桌面屏幕、游戏 UI/HUD/菜单、CLI/TUI 输出、扩展或设备界面）、前端布局、UI/UX、产品模块边界或信息放置时，把产品/页面定位检查作为前置动作：用户在这个 surface 要完成的判断、产品必须提供的信息/动作/反馈、不应常驻的信息、主层/下钻/运维/诊断/详情归属、布局和信息密度是否匹配任务。多 surface、多平台或多模块归属不清时，先读取相关 Context 并搜索入口，必要时使用 `context_surface_contract` 做 Surface Contract Audit，再收窄到具体实现。该检查是下一步变更分类的输入；只有形成长期产品归属、surface 职责、信息架构或模块边界结论时才更新 Context。
-   - 若存在 Product Surface Contract，读取并对齐 primary user question、main allows/forbids、drilldown ownership、long-task state 和 verification。
-   - 若产品方案只到 surface/流程粒度而 material screen 的实现、验收需要更深事实，不要宣称已有控件级权威。使用稳定 surface/control key 将缺口分类为已有 Screen/interaction Context 覆盖、需要 Context 更新、task-local、out-of-scope 或 decision required；按需从 `screen-contract.md` 提炼 durable hierarchy/regions/navigation/variants/control semantics，视觉系统和 target 仍由 `DESIGN.md`/authored target 所有。
-   - 若本次产品判断会受已采用的 `exact-target` 或 `constraint` 影响，必须沿 owning Context → stable target key → `DESIGN.md` 登记主动打开资源，而不是只读取登记文字。核对不可变 adopted locator/digest、覆盖条件以及 editable upstream owner/locator/update route。缺失、不可读、过期或冲突时将受影响判断保留为 decision required；只有 editable upstream 不可用时仍可读取 immutable target，但“修改设计资源”必须明确为人工/外部更新边界。更新后采用新 immutable version 并更新 owning reference，不覆盖旧基线。
-   - 若缺失且本任务改变 durable surface responsibility，将唯一 `Context Delta` 设为 `required`，把具体答案写入 `project_context/**`，跨 surface 或跨 area 使用现有 `contract` role，不新增 surface-specific role。
-4. 涉及输入、选择、搜索、筛选、表单/配置、调度/时间窗口、预算/配额/限流或加载/空态/错误态等 UI 控件时，用“控件任务框架”重新理解用户任务和产品反馈；这只是通用判断框架，不是业务处方库。
-5. 当一个产品对象、能力或接口的增删改需要跨多个页面、模块、Context 或产品域同步调整时，将该影响范围视为产品边界复核信号；先判断它是否应沉淀为独立能力、subdomain 或 area，并明确对外契约、所有权和消费方边界，避免通过手工清单长期维护各消费面的重复映射。
-6. 产品意图、模块职责、边界和验收口径以 `project_context/**` 为准；代码和搜索结果只说明当前实现状态。Context 决定“应该是什么”，代码揭示“现在是什么”，代码不能静默重定义 Context。
-7. 输出产品判断或第一处实现编辑前，先给出唯一长期事实判断 `Context Delta: none|required`。若输入包含产品、架构、技术或验收来源，在 agent 内部逐项判断 delivery-significant constraint 已被 Context 覆盖、需要先更新 Context、仅属 task-local、显式 out-of-scope 或需要真实用户决策；不要创建 `plan.md`、Task Contract 文件或 Markdown 映射表。
-8. 普通 bug fix、局部样式、局部实现漂移、测试修复或探索性 spike 不更新 Context；如果过程中形成长期产品结论，应在继续对齐或交付前回写 Context。不要把 Context 机械补成代码改动摘要。
-9. 如果代码与 Context 冲突，显式标记为实现漂移、缺失工作或 Context 过期。
-10. 输出产品判断时保持短而具体，避免长篇 PRD 模板。
-11. 需要沉淀长期事实时，只更新 `project_context/**`：
-   - 全局产品目标、边界、背景写入 `global.md`。
-   - 产品域用户/系统契约、规则、风险写入对应 area / subdomain Context。
-   - 跨域契约写入 `context_role: contract` 或 manifest role 为 `contract` 的 Context；底层理论源写入 `foundation`，关键重复验证路径写入 `verification`，关键部署/运行初始化路径写入 `deployment`，历史索引写入 `archive`，不要伪装成 area。
-   - 新 context unit 可新增 `project_context/areas/<unit>.md`，并更新 `global.md#Context Index`；复杂项目同时更新 `project_context/context.toml`。
-   - 如果 `upgrade` 自动把深层 `.md` 注册成 area，但语义上更像 foundation / contract / archive，后续应显式调整 manifest role；不要依赖自动迁移判断语义。
-12. Context 只能声明验证 / 部署关键路径或验收信号，不能伪造“测试已通过”或“部署已成功”。
+---
+name: context_product_plan
+description: Use when the user explicitly asks for 产品方案, 产品经理, 产品专家, 需求方案, 功能方案, 业务规则方案, 用户故事方案, 验收标准方案, 产品规划方案, product plan, product manager, product expert, product spec, or PM spec in a Minimal Context Harness project. Do not trigger for ordinary coding, debugging, package work, or generic mentions of 产品, product, or requirements.
+---
+
+# Context Product Plan
+
+## Package-Managed Boundary
+
+This Skill is generated by `ty-context sync` and owned by the Harness package. Do not edit the generated `context_product_plan` Skill directly.
+
+Project-specific product planning rules belong in a separate project-local Skill under `<harnessRoot>/skills/product_plan/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/context.toml`，按 default area、triggers、read_when 选择相关 context。
+2. 和用户澄清或整理：目标用户、产品/页面定位、核心问题、用户需要什么、产品需要提供的内容/能力/反馈、主要流程、验收信号、非目标、约束、风险和受影响模块。
+3. 涉及 Product Surface（Web 页面、移动/桌面屏幕、游戏 UI/HUD/菜单、CLI/TUI 输出、扩展或设备界面）、前端布局、UI/UX、产品模块边界或信息放置时，把产品/页面定位检查作为前置动作：用户在这个 surface 要完成的判断、产品必须提供的信息/动作/反馈、不应常驻的信息、主层/下钻/运维/诊断/详情归属、布局和信息密度是否匹配任务。多 surface、多平台或多模块归属不清时，先读取相关 Context 并搜索入口，必要时使用 `context_surface_contract` 做 Surface Contract Audit，再收窄到具体实现。该检查是下一步变更分类的输入；只有形成长期产品归属、surface 职责、信息架构或模块边界结论时才更新 Context。
+   - 若存在 Product Surface Contract，读取并对齐 primary user question、main allows/forbids、drilldown ownership、long-task state 和 verification。
+   - 若产品方案只到 surface/流程粒度而 material screen 的实现、验收需要更深事实，不要宣称已有控件级权威。使用稳定 surface/control key 将缺口分类为已有 Screen/interaction Context 覆盖、需要 Context 更新、task-local、out-of-scope 或 decision required；按需从 `screen-contract.md` 提炼 durable hierarchy/regions/navigation/variants/control semantics，视觉系统和 target 仍由 `DESIGN.md`/authored target 所有。
+   - 若本次产品判断会受已采用的 `exact-target` 或 `constraint` 影响，必须沿 owning Context → stable target key → `DESIGN.md` 登记主动打开资源，而不是只读取登记文字。核对不可变 adopted locator/digest、覆盖条件以及 editable upstream owner/locator/update route。缺失、不可读、过期或冲突时将受影响判断保留为 decision required；只有 editable upstream 不可用时仍可读取 immutable target，但“修改设计资源”必须明确为人工/外部更新边界。更新后采用新 immutable version 并更新 owning reference，不覆盖旧基线。
+   - 若缺失且本任务改变 durable surface responsibility，将唯一 `Context Delta` 设为 `required`，把具体答案写入 `project_context/**`，跨 surface 或跨 area 使用现有 `contract` role，不新增 surface-specific role。
+4. 涉及输入、选择、搜索、筛选、表单/配置、调度/时间窗口、预算/配额/限流或加载/空态/错误态等 UI 控件时，用“控件任务框架”重新理解用户任务和产品反馈；这只是通用判断框架，不是业务处方库。
+5. 当一个产品对象、能力或接口的增删改需要跨多个页面、模块、Context 或产品域同步调整时，将该影响范围视为产品边界复核信号；先判断它是否应沉淀为独立能力、subdomain 或 area，并明确对外契约、所有权和消费方边界，避免通过手工清单长期维护各消费面的重复映射。
+6. 产品意图、模块职责、边界和验收口径以 `project_context/**` 为准；代码和搜索结果只说明当前实现状态。Context 决定“应该是什么”，代码揭示“现在是什么”，代码不能静默重定义 Context。
+7. 输出产品判断或第一处实现编辑前，先给出唯一长期事实判断 `Context Delta: none|required`。若输入包含产品、架构、技术或验收来源，在 agent 内部逐项判断 delivery-significant constraint 已被 Context 覆盖、需要先更新 Context、仅属 task-local、显式 out-of-scope 或需要真实用户决策；不要创建 `plan.md`、Task Contract 文件或 Markdown 映射表。
+8. 普通 bug fix、局部样式、局部实现漂移、测试修复或探索性 spike 不更新 Context；如果过程中形成长期产品结论，应在继续对齐或交付前回写 Context。不要把 Context 机械补成代码改动摘要。
+9. 如果代码与 Context 冲突，显式标记为实现漂移、缺失工作或 Context 过期。
+10. 输出产品判断时保持短而具体，避免长篇 PRD 模板。
+11. 需要沉淀长期事实时，只更新 `project_context/**`：
+   - 全局产品目标、边界、背景写入 `global.md`。
+   - 产品域用户/系统契约、规则、风险写入对应 area / subdomain Context。
+   - 跨域契约写入 `context_role: contract` 或 manifest role 为 `contract` 的 Context；底层理论源写入 `foundation`，关键重复验证路径写入 `verification`，关键部署/运行初始化路径写入 `deployment`，历史索引写入 `archive`，不要伪装成 area。
+   - 新 context unit 可新增 `project_context/areas/<unit>.md`，并更新 `global.md#Context Index`；复杂项目同时更新 `project_context/context.toml`。
+   - 如果 `upgrade` 自动把深层 `.md` 注册成 area，但语义上更像 foundation / contract / archive，后续应显式调整 manifest role；不要依赖自动迁移判断语义。
+12. Context 只能声明验证 / 部署关键路径或验收信号，不能伪造“测试已通过”或“部署已成功”。
 13. Verification / Deployment Role Context 只记录长期可复用的重复执行路径事实：特殊准备、最短命令或路径、预期阶段 / 信号、可接受 warning、已排除的重复探索点。不要记录一次性测试日志、完整输出、临时 JSON、CI artifact、测试报告、release ledger、secret、token、cookie、device id 或 raw payload。
 14. 收尾时做 `Contract Conformance` 和 Context drift check，只报告轻量状态：`Context: 已更新 ...` 或 `Context: 本次无长期事实变化`。Conformance 说明本次契约满足情况、未满足或延期项和验证入口；一次性证据、测试日志、截图结果、任务契约和实现摘要不写入 Context。
 
-## 内部执行约束与 Conformance
-
-- `Context Delta` 只能是 `none` 或 `required`。`required` 先把足以指导实现的长期事实写入 owning Context；`none` 直接按现有 Context 工作，不制造 Context 噪音。
-- Agent 内部计划应保持目标、用户任务、信息 / 动作 / 状态 / 反馈、边界、非目标、验收信号和验证入口清晰。触及 Product Surface 时，同时保持 surface platform、primary user question、main allows/forbids、drilldown ownership 和 long-task state requirement 清晰；material controls 还应覆盖 applicable 的 region/location、type/label、task、visibility/availability、trigger/input/validation/default、interaction/navigation、states/recovery/permission/feedback/accessibility，而不是由开发时临时猜测。
-- 外部来源的每项重要约束都在内部分类为 Context 已覆盖、Context 已更新、task-local、显式 out-of-scope 或需要用户决策；存在未处理项时不能声称全量完成。
-- 默认流程不要求或验证固定 `plan.md`、Task Contract 文件、Source-to-Context 表、Context-to-Implementation 表、matrix、verdict 或 evidence ledger；可选 scratch 没有固定名称或权威。
-- `Contract Conformance` 直接检查 controlling Context 是否到达正确产品域、surface、API、状态与验证路径并避开 forbidden shortcut。实现偏差修实现；缺少长期事实则返回 `Context Delta: required`，先更新 Context 再重新对齐。
-- small code task、普通 bug fix、局部样式、小重构、测试修复或探索性 spike 不创建额外流程 artifact。
+## 非 UI 产品语义的默认粒度
 
-## 产品体验校准
+产品方案的默认完成单位是范围内最细、可独立判断的语义 Fact，不是段落、用户故事、Requirement、页面、Product Control、宽泛状态列表或“开发再定”。先完整索引用户文字、附件、Context、既有规范、外部约束和需要保留的仓库事实，再把每个新增/补全事实标为直接表达、逻辑必然推导、用户明确委托、证据支持的现状保留或 `decision_required`。不能从实现代码反推并静默升级为产品意图，也不能用一个 `all-states`、默认路径或代表样例代替若干原子条件。
 
-- 做页面、模块或入口规划时，先回答产品或页面定位是什么、要解决什么问题、需要提供什么给用户；再回答放什么、放哪里、为什么。这是页面变更前置判断，不是实现后的视觉润色。优先保留能帮助目标用户判断状态、采取行动、定位下一步或理解风险的信息。
-- 信息归属按使用场景决定：高频且跨页面的动作优先考虑系统级区域；模块动作放模块内部；运维、连接、缓存、后台任务等内部状态只有在影响用户判断或行动时才进入主界面，否则放运维/详情区域；低频解释放 Context、文档、帮助或详情，不默认占据主界面。
-- 首页、总览或入口页应服务产品定位下的核心使用路径和核心判断，不要为了证明系统层级完整而重复导航、堆叠入口、保留空指标槽或展示实现来源说明。
-- 产品文案面向真实用户，直白、行动优先；除产品名、协议、字段名、ID、调试 JSON 等必要专有名词外，普通按钮、筛选、状态、空态、警告和说明优先使用用户熟悉的语言。
-- 空态和数据要求真实：没有数据就显示真正空态，筛选无结果与系统无数据要区分，API/连接失败用用户能理解的状态表达，技术细节放到运维或详情里。
+对每个适用产品域显式闭合：
 
-## 控件任务框架
+- 目标、范围、非目标、术语、单位、不变量、假设、优先级和验收含义；
+- actor、role、tenant、organization、plan/entitlement、所有权、权限、隔离、审批与升级；
+- 业务谓词、完整决策表分支、优先级、例外、公式、版本、单位、精度、舍入、阈值和生效期；
+- entity、identifier、field、relation 的类型、空值/缺失/默认、枚举、唯一性、基数、生命周期、来源、敏感性、保留与序列化；
+- command/query/workflow 的触发、前置、输入、guard、顺序、状态转换、同步/异步副作用、输出、部分成功、取消/替换/补偿、禁止效果；
+- 每个 state/transition/illegal path，以及 timeout、stale、conflict、interruption、re-entry、recovery、archive/delete；
+- 时间、时区/DST、边界包含性、调度/递归、grace/debounce/throttle/lease/retry；
+- 输入校验、输出/错误分类、API/protocol/event/job、分页/排序、版本/兼容、幂等、重试、回放、死信和背压；
+- 数据一致性/并发/事务、故障/降级/恢复、配置/flag、迁移/回滚、性能/容量/可靠性、隐私/安全/审计、部署/运维/可观测性、外部集成，以及适用的商业、硬件、AI/ML 与自定义域语义。
 
-- 当产品界面涉及输入、选择、搜索、筛选、表单/配置、调度/时间窗口、预算/配额/限流或状态反馈时，先把控件还原成用户任务：用户要判断什么、选择什么、提交什么或规避什么风险。
-- 先判断数据语义，再选交互：自由文本、枚举、实体选择、时间/区间、数量/预算、规则配置和内部开关对应不同的理解成本、错误成本和验证需求。
-- 明确用户确认自己“选对了/填对了/可以继续”的反馈：加载中、无结果、无数据、连接失败、校验失败、保存成功和风险提示要能被用户区分。
-- 对数量、预算、配额、限流、调度和时间类字段，判断是否需要单位、范围、默认值、示例、推荐值、成本/风险/影响说明；只记录稳定业务结论，不把一次性解释写进 Context。
-- 检查用户可见语言是否面向任务，而不是后端字段名、数据库列或内部枚举直出；必要技术细节放到详情、帮助、运维或调试视图。
-- 如果选择自由输入，必须判断错误成本、校验反馈和恢复路径是否可接受；如果不可接受，应形成更明确的输入约束或控件契约。
-- 这些问题是通用产品判断，不是固定控件处方。业务特定答案进入项目 Context 或项目本地 Skill；本次实现如何满足既有约束只写在交付说明。
+每个 Fact 都应能按 `Outcome × subject/relation/population × 精确条件组合 × 原子属性 × typed expected predicate` 独立定位，并有 owner、来源/basis、适用性和验收方法。actor/role/tenant/version/environment/state/input/boundary/locale/time/concurrency/failure/migration/rollout 等适用条件必须是一等原子值或有依据的精确排除；N/A 不是省略的同义词。持续区间用边界/分段/公式表达，动态集合用可枚举 universe/partition 表达。
 
-## 输出边界
+普通默认 Workflow 在内部保持一次性的精确 Fact 与验收闭包，不创建方案矩阵或新状态；显式 Long-Task 则把同一全集写入其 Source `semantic-fact-manifest-v1` 并由现有 Contract/Final Gate 承载。两者都要求任何适用 Fact 未声明、未决、不可读、未映射或无可信验收边界时不得声称方案已完整。真正的产品、法律、安全、商业或外部决策应向用户/owner 阻断，不以“补全细节”为名发明。
 
-- 不默认创建 `.work_products/**`、PRD、tech plan、ADR、implementation doc、review/test/release 文档。
-- 不要求 lifecycle phase、plan task、phase gate 或阶段 Skill。
-- 如果用户明确要求独立方案文档，可以临时生成；长期事实仍要提炼回 `project_context/**`。
-- 如果用户只是要求实现功能、修 bug、调整代码、处理 package/release，或只是泛泛提到“产品 / product / requirements”，不需要触发本 Skill；只有明确角色名或强相关产物名指向产品判断、需求整理、验收口径或长期产品事实沉淀时才使用。
-
-## 建议沉淀位置
-
-- `global.md#Product / Delivery Brief`：项目级产品目标、用户、核心流程和非目标。
-- `global.md#Design Rationale`：项目级长期产品取舍、rejected alternatives 和 tradeoffs；不要编造 rationale，也不要写实现摘要、PR notes、命令输出、测试通过声明、截图审查、debug 过程、agent reasoning 或仅由当前代码形态反推的理由。
-- `areas/*.md#User / System Contract`：产品域可见行为、API、CLI、UI 或数据契约。
-- `areas/*.md#Key Constraints`：业务规则、边界、风险和不易从代码看出的约束。
-- role=`contract` Context：跨域 API / schema / event / interface 语义及其 durable rationale。
-- role=`decision-rationale` Context：更大或跨切面的稳定产品设计原因。
-- `areas/*/verification.md` 或 role=`verification` Context：关键测试、smoke、CI、probe 或验证重复执行路径。
-- `areas/*/deployment.md` 或 role=`deployment` Context：关键部署、云端初始化、运行拓扑、健康检查或回滚重复执行路径。
-- `project_context/context.toml`：复杂项目的产品域 area/context_unit、role、触发词、按需读取策略和可选边界规则。
+## 内部执行约束与 Conformance
+
+- `Context Delta` 只能是 `none` 或 `required`。`required` 先把足以指导实现的长期事实写入 owning Context；`none` 直接按现有 Context 工作，不制造 Context 噪音。
+- Agent 内部计划应保持目标、用户任务、信息 / 动作 / 状态 / 反馈、边界、非目标、验收信号和验证入口清晰。触及 Product Surface 时，同时保持 surface platform、primary user question、main allows/forbids、drilldown ownership 和 long-task state requirement 清晰；material controls 还应覆盖 applicable 的 region/location、type/label、task、visibility/availability、trigger/input/validation/default、interaction/navigation、states/recovery/permission/feedback/accessibility，而不是由开发时临时猜测。
+- 外部来源的每项重要约束都在内部分类为 Context 已覆盖、Context 已更新、task-local、显式 out-of-scope 或需要用户决策；存在未处理项时不能声称全量完成。
+- 默认流程不要求或验证固定 `plan.md`、Task Contract 文件、Source-to-Context 表、Context-to-Implementation 表、matrix、verdict 或 evidence ledger；可选 scratch 没有固定名称或权威。
+- `Contract Conformance` 直接检查 controlling Context 是否到达正确产品域、surface、API、状态与验证路径并避开 forbidden shortcut。实现偏差修实现；缺少长期事实则返回 `Context Delta: required`，先更新 Context 再重新对齐。
+- small code task、普通 bug fix、局部样式、小重构、测试修复或探索性 spike 不创建额外流程 artifact。
+
+## 产品体验校准
+
+- 做页面、模块或入口规划时，先回答产品或页面定位是什么、要解决什么问题、需要提供什么给用户；再回答放什么、放哪里、为什么。这是页面变更前置判断，不是实现后的视觉润色。优先保留能帮助目标用户判断状态、采取行动、定位下一步或理解风险的信息。
+- 信息归属按使用场景决定：高频且跨页面的动作优先考虑系统级区域；模块动作放模块内部；运维、连接、缓存、后台任务等内部状态只有在影响用户判断或行动时才进入主界面，否则放运维/详情区域；低频解释放 Context、文档、帮助或详情，不默认占据主界面。
+- 首页、总览或入口页应服务产品定位下的核心使用路径和核心判断，不要为了证明系统层级完整而重复导航、堆叠入口、保留空指标槽或展示实现来源说明。
+- 产品文案面向真实用户，直白、行动优先；除产品名、协议、字段名、ID、调试 JSON 等必要专有名词外，普通按钮、筛选、状态、空态、警告和说明优先使用用户熟悉的语言。
+- 空态和数据要求真实：没有数据就显示真正空态，筛选无结果与系统无数据要区分，API/连接失败用用户能理解的状态表达，技术细节放到运维或详情里。
+
+## 控件任务框架
+
+- 当产品界面涉及输入、选择、搜索、筛选、表单/配置、调度/时间窗口、预算/配额/限流或状态反馈时，先把控件还原成用户任务：用户要判断什么、选择什么、提交什么或规避什么风险。
+- 先判断数据语义，再选交互：自由文本、枚举、实体选择、时间/区间、数量/预算、规则配置和内部开关对应不同的理解成本、错误成本和验证需求。
+- 明确用户确认自己“选对了/填对了/可以继续”的反馈：加载中、无结果、无数据、连接失败、校验失败、保存成功和风险提示要能被用户区分。
+- 对数量、预算、配额、限流、调度和时间类字段，判断是否需要单位、范围、默认值、示例、推荐值、成本/风险/影响说明；只记录稳定业务结论，不把一次性解释写进 Context。
+- 检查用户可见语言是否面向任务，而不是后端字段名、数据库列或内部枚举直出；必要技术细节放到详情、帮助、运维或调试视图。
+- 如果选择自由输入，必须判断错误成本、校验反馈和恢复路径是否可接受；如果不可接受，应形成更明确的输入约束或控件契约。
+- 这些问题是通用产品判断，不是固定控件处方。业务特定答案进入项目 Context 或项目本地 Skill；本次实现如何满足既有约束只写在交付说明。
+
+## 输出边界
+
+- 不默认创建 `.work_products/**`、PRD、tech plan、ADR、implementation doc、review/test/release 文档。
+- 不要求 lifecycle phase、plan task、phase gate 或阶段 Skill。
+- 如果用户明确要求独立方案文档，可以临时生成；长期事实仍要提炼回 `project_context/**`。
+- 如果用户只是要求实现功能、修 bug、调整代码、处理 package/release，或只是泛泛提到“产品 / product / requirements”，不需要触发本 Skill；只有明确角色名或强相关产物名指向产品判断、需求整理、验收口径或长期产品事实沉淀时才使用。
+
+## 建议沉淀位置
+
+- `global.md#Product / Delivery Brief`：项目级产品目标、用户、核心流程和非目标。
+- `global.md#Design Rationale`：项目级长期产品取舍、rejected alternatives 和 tradeoffs；不要编造 rationale，也不要写实现摘要、PR notes、命令输出、测试通过声明、截图审查、debug 过程、agent reasoning 或仅由当前代码形态反推的理由。
+- `areas/*.md#User / System Contract`：产品域可见行为、API、CLI、UI 或数据契约。
+- `areas/*.md#Key Constraints`：业务规则、边界、风险和不易从代码看出的约束。
+- role=`contract` Context：跨域 API / schema / event / interface 语义及其 durable rationale。
+- role=`decision-rationale` Context：更大或跨切面的稳定产品设计原因。
+- `areas/*/verification.md` 或 role=`verification` Context：关键测试、smoke、CI、probe 或验证重复执行路径。
+- `areas/*/deployment.md` 或 role=`deployment` Context：关键部署、云端初始化、运行拓扑、健康检查或回滚重复执行路径。
+- `project_context/context.toml`：复杂项目的产品域 area/context_unit、role、触发词、按需读取策略和可选边界规则。