project-tiny-context-harness 0.2.59 → 0.2.60

package/README.md

@@ -115,7 +115,7 @@ npm ci
 npm run smoke:quickstart
 npm run preview:pack
 cd /path/to/your/test-repo
-npm install -D /path/to/project-tiny-context-harness/tmp/ty-context/source-preview/package/project-tiny-context-harness-0.2.59.tgz
+npm install -D /path/to/project-tiny-context-harness/tmp/ty-context/source-preview/package/project-tiny-context-harness-0.2.60.tgz
 npx --no-install ty-context init --adopt
 make validate-context
 ```
@@ -244,7 +244,9 @@ Use `npx --no-install ty-context ...` only when you explicitly want the already
 | Diagnostics | `make ty-context-doctor` or `npx --yes --package project-tiny-context-harness@latest ty-context doctor` | Reports Harness root, package version, schema version and required Minimal Context paths. |
 | Package source checks | `ty-context package sync-source`, `ty-context package check-source` | Maintainer-only commands for keeping package canonical assets aligned with the source workspace. |
 
-For product, UI/UX and engineering tasks that touch design intent, API/Schema, state/runtime behavior, architecture boundaries or verification design, the default Skills compile a short current-task contract before implementation. The contract starts with `Context Delta: none|required`; `required` preserves context-first behavior, while `none` means the task can proceed against existing Context. For engineering, RFC and implementation work, the existing Task Contract also includes `Modularity Check: none|required|exception` so oversized touched files trigger split-or-exception reasoning. For module design work, the development engineer Skill also compiles `Applicable Module Design`: the relevant principles, minimal design logic and durable rationale that control the current implementation or verification choice. The task contract and Contract Conformance are handoff evidence, not new PRD, tech-plan, validator or gate surfaces.
+For high-risk product, UI/UX and engineering tasks that affect durable architecture or module ownership, API/Schema/data contracts, state/runtime behavior, dependency direction, verification/deployment semantics or design-rationale tradeoffs, the default Skills compile a short current-task contract before implementation. The contract starts with `Context Delta: none|required`; `required` preserves context-first behavior, while `none` means the task can proceed against existing Context. It can name `Architecture Context Hit` and `Decision Rationale Hit: existing|required|none` so agents explicitly check the controlling Context and rationale state. When module design principles are relevant, the same contract still uses `Applicable Module Design` for the principles, design logic and rationale controlling the current choice. For engineering, RFC and implementation work, the existing Task Contract still includes `Modularity Check: none|required|exception` so oversized touched files trigger split-or-exception reasoning without becoming an architecture gate. Ordinary bug fixes, local styling, small refactors, package/release chores, test repairs and spikes are not forced into architecture/rationale ceremony unless they produce durable facts. The task contract and Contract Conformance are handoff evidence, not new PRD, tech-plan, ADR, implementation-document, validator or gate surfaces.
+
+Technical architecture support is a Minimal Context capability: use restrained `architecture.md`, area Module Design Capsules and existing `contract` / `decision-rationale` roles when durable architecture or rationale matters. Do not invent rationale; store stable reasons, rejected alternatives or tradeoffs only in the smallest durable Context surface when they will affect future implementation or verification choices.
 
 For long-running plans, RFCs or implementation proposals, the plan acceptance checklist Skill can turn a plan plus relevant Context into a falsifiable acceptance checklist and a paste-ready goal/target-mode prompt. It is one pre-execution acceptance pass, not a task planner or workflow engine: it stores temporary inputs under `tmp/ty-context/plan-acceptance/**`, asks for confirmation when durable assumptions are unclear, and leaves execution evidence to the future executor, tests, CI, review or human acceptance. The generated prompt may require a local audit under the same temporary directory so future sessions can recover acceptance progress; that audit is not Context, not a quality proof and not a replacement for the project's Tiny Context workflow contract.
 
@@ -310,7 +312,7 @@ Managed `AGENTS.md` guidance is intentionally a startup router, not a full manua
 - project goal
 - non-goals / boundaries
 - background
-- design rationale
+- project-wide design rationale, including rejected alternatives and tradeoffs that still matter
 - architecture context link
 - product / delivery brief
 - UX / screen brief
@@ -324,7 +326,7 @@ Managed `AGENTS.md` guidance is intentionally a startup router, not a full manua
 - system boundary
 - component map
 - data / control flow
-- design rationale
+- architecture-level design rationale, rejected alternatives and tradeoffs
 - constraints and tradeoffs
 - verification implications
 - open risks
@@ -342,7 +344,9 @@ Managed `AGENTS.md` guidance is intentionally a startup router, not a full manua
 - related role context pointers
 - open risks
 
-A module design capsule should stay small and decision-shaped: `Principles` are stable execution constraints, `Design Logic` is the minimum choose/reject/degrade/compose logic, and `Design Rationale` keeps only reasons that change later implementation or verification decisions. Current thresholds, commands and probe parameters belong in the relevant contract or verification Context as execution instances, not as permanent principles.
+A module design capsule should stay small and decision-shaped: `Principles` are stable execution constraints, `Design Logic` is the minimum choose/reject/degrade/compose logic, and `Design Rationale` keeps only reasons, rejected alternatives and tradeoffs that change later implementation or verification decisions. Current thresholds, commands and probe parameters belong in the relevant contract or verification Context as execution instances, not as permanent principles.
+
+Use the smallest durable rationale surface: project-wide tradeoffs in `global.md#Design Rationale`, architecture choices in `architecture.md#Design Rationale`, module reasons in an area Module Design Capsule, cross-domain interface rationale in `contract` role Context, larger cross-cutting reasons in `decision-rationale`, and visual identity or token rationale in `DESIGN.md`. Do not record implementation summaries, PR notes, command output, test-passed claims, screenshot review notes, debug history, agent reasoning or rationale inferred only from current code shape.
 
 Other context files under `project_context/**` can declare `context_role` in front matter or receive a role from `context.toml`. Roles are semantic labels for agent reading and authoring behavior; `validate-context` checks graph structure, paths and field shapes instead of enforcing a writing template for every role. Supported roles are `global`, `architecture`, `area`, `domain`, `subdomain`, `contract`, `foundation`, `verification`, `deployment`, `archive`, `implementation-index` and `decision-rationale`.
 

package/assets/README.md

@@ -94,7 +94,7 @@ That smoke packs the local workspace, installs it into a disposable repo, runs `
 ```sh
 npm run preview:pack
 cd /path/to/your/test-repo
-npm install -D /path/to/project-tiny-context-harness/tmp/ty-context/source-preview/package/project-tiny-context-harness-0.2.59.tgz
+npm install -D /path/to/project-tiny-context-harness/tmp/ty-context/source-preview/package/project-tiny-context-harness-0.2.60.tgz
 npx --no-install ty-context init --adopt
 make validate-context
 ```
@@ -270,7 +270,9 @@ The default Skills are Minimal Context helpers for explicit product-planning, UI
 
 Multilingual trigger phrases are compatibility details. Public README, npm and launch copy stay English-first, and public/package-managed surfaces must remain English-complete; literal non-English examples are documented only where they explain generated Skill matching and must not be the sole activation path.
 
-For product, UI/UX and engineering tasks that touch design intent, API/Schema, state/runtime behavior, architecture boundaries or verification design, the default Skills compile a short current-task contract before implementation. The contract starts with `Context Delta: none|required`; `required` preserves context-first behavior, while `none` means the task can proceed against existing Context. For engineering, RFC and implementation work, the existing Task Contract also includes `Modularity Check: none|required|exception` so oversized touched files trigger split-or-exception reasoning. For module design work, the development engineer Skill also compiles `Applicable Module Design`: the relevant principles, minimal design logic and durable rationale that control the current implementation or verification choice. The task contract and Contract Conformance are handoff evidence, not new PRD, tech-plan, validator or gate surfaces.
+For high-risk product, UI/UX and engineering tasks that affect durable architecture or module ownership, API/Schema/data contracts, state/runtime behavior, dependency direction, verification/deployment semantics or design-rationale tradeoffs, the default Skills compile a short current-task contract before implementation. The contract starts with `Context Delta: none|required`; `required` preserves context-first behavior, while `none` means the task can proceed against existing Context. It can name `Architecture Context Hit` and `Decision Rationale Hit: existing|required|none` so agents explicitly check the controlling Context and rationale state. When module design principles are relevant, the same contract still uses `Applicable Module Design` for the principles, design logic and rationale controlling the current choice. For engineering, RFC and implementation work, the existing Task Contract still includes `Modularity Check: none|required|exception` so oversized touched files trigger split-or-exception reasoning without becoming an architecture gate. Ordinary bug fixes, local styling, small refactors, package/release chores, test repairs and spikes are not forced into architecture/rationale ceremony unless they produce durable facts. The task contract and Contract Conformance are handoff evidence, not new PRD, tech-plan, ADR, implementation-document, validator or gate surfaces.
+
+Technical architecture support is a Minimal Context capability: use restrained `architecture.md`, area Module Design Capsules and existing `contract` / `decision-rationale` roles when durable architecture or rationale matters. Do not invent rationale; store stable reasons, rejected alternatives or tradeoffs only in the smallest durable Context surface when they will affect future implementation or verification choices.
 
 For long-running plans, RFCs or implementation proposals, the plan acceptance checklist compiler can turn a plan plus relevant Context into a falsifiable acceptance checklist and a paste-ready goal/target-mode prompt. This is one pre-execution acceptance pass, not a task planner or workflow engine: it stores temporary inputs under `tmp/ty-context/plan-acceptance/**`, asks for confirmation when durable assumptions are unclear, and leaves execution evidence to the future executor, tests, CI, review or human acceptance. The generated prompt may require a local audit under the same temporary directory so future sessions can recover acceptance progress; that audit is not Context, not a quality proof and not a replacement for the project's Tiny Context workflow contract.
 
@@ -402,7 +404,7 @@ Examples:
 - project goal
 - non-goals / boundaries
 - background
-- design rationale, including former ADR-level decisions that still matter
+- project-wide design rationale, including former ADR-level decisions, rejected alternatives and tradeoffs that still matter
 - architecture context link
 - product / delivery brief for durable product goals, users, flows and acceptance signals
 - UX / screen brief for durable screen, interaction, responsive and accessibility facts
@@ -416,7 +418,7 @@ Examples:
 - system boundary
 - component map
 - data / control flow
-- architecture-level design rationale
+- architecture-level design rationale, rejected alternatives and tradeoffs
 - constraints and tradeoffs
 - verification implications
 - open risks
@@ -434,7 +436,9 @@ Examples:
 - related role context pointers
 - open risks
 
-A module design capsule should stay small and decision-shaped: `Principles` are stable execution constraints, `Design Logic` is the minimum choose/reject/degrade/compose logic, and `Design Rationale` keeps only reasons that change later implementation or verification decisions. Current thresholds, commands and probe parameters belong in the relevant contract or verification Context as execution instances, not as permanent principles.
+A module design capsule should stay small and decision-shaped: `Principles` are stable execution constraints, `Design Logic` is the minimum choose/reject/degrade/compose logic, and `Design Rationale` keeps only reasons, rejected alternatives and tradeoffs that change later implementation or verification decisions. Current thresholds, commands and probe parameters belong in the relevant contract or verification Context as execution instances, not as permanent principles.
+
+Use the smallest durable rationale surface: project-wide tradeoffs in `global.md#Design Rationale`, architecture choices in `architecture.md#Design Rationale`, module reasons in an area Module Design Capsule, cross-domain interface rationale in `contract` role Context, larger cross-cutting reasons in `decision-rationale`, and visual identity or token rationale in `DESIGN.md`. Do not record implementation summaries, PR notes, command output, test-passed claims, screenshot review notes, debug history, agent reasoning or rationale inferred only from current code shape.
 
 Additional Markdown context files under `project_context/**` can declare `context_role` in front matter or receive a role from `context.toml`. Roles are semantic labels that help agents choose when and how to read context; `validate-context` checks graph structure, paths and field shapes rather than enforcing a writing template for each role:
 

package/assets/agents/AGENTS_CORE.md

@@ -13,7 +13,7 @@
 1. 先读 `project_context/global.md`、`project_context/architecture.md` 和 `project_context/context.toml`，再按 graph 读取相关 area / context unit。
 2. 若任务涉及 Product Surface work（Web UI、移动/桌面屏幕、游戏 UI/HUD/菜单、CLI/TUI 输出、扩展或设备界面）、前端布局、UI/UX、产品模块边界或信息放置，先做产品/页面定位检查；若改变 durable surface responsibility、主层/下钻归属、长任务状态或信息架构，使用 `context_surface_contract` Skill 应用 Surface Contract workflow：`project_context/**` 是 durable surface truth，repo-local Skills 可强制项目 task block，`DESIGN.md` 只放视觉 token/rationale，代码/截图只是实现证据；不新增 surface-specific context role，跨 surface 用现有 `contract` role。
 3. 若任务新增、迁移或整理 Context 文件，先做 role placement scan：area 只代表产品域归属；contract / foundation / subdomain / verification / deployment / implementation-index / decision-rationale 等按读取目的拆成 role Context。
-4. 对产品方案、UI/UX、系统设计、架构边界、API / Schema、模块设计原则、状态或运行语义、验证设计等任务，先把相关模块设计上下文编译进当前任务契约；契约第一段用 `Context Delta: none|required` 声明是否改变长期事实，再写本次 Task Contract；工程 / RFC / 实现类 Task Contract 同时包含 `Modularity Check: none|required|exception`。
+4. 对影响架构边界、模块 ownership、API / Schema / 数据契约、状态或运行语义、依赖方向、验证 / 部署语义或 durable rationale / tradeoff 的高风险产品、UI/UX、系统设计和工程任务，先把相关 Context 编译进当前任务契约；契约第一段用 `Context Delta: none|required` 作为唯一长期事实判断点，并包含 `Architecture Context Hit`、`Decision Rationale Hit: existing|required|none`；工程 / RFC / 实现类 Task Contract 同时包含 `Modularity Check: none|required|exception`。
 5. `Context Delta: required` 则 context-first；普通 bug fix、局部样式、局部漂移修复、测试修复或 spike 默认 code-first，但一旦产生长期结论必须回写 Context。
 6. 收尾做 Contract Conformance 和 Context drift check，只报告 `Context: 已更新 ...` 或 `Context: 本次无长期事实变化`；不要把一次性证据、任务契约或实现摘要写入 Context。
 
@@ -29,7 +29,7 @@
 
 1. 新会话或继续工作时，先读取 `project_context/global.md`、`project_context/architecture.md` 和 `project_context/context.toml`；按其中 default area 和触发条件读取相关 context。
 2. 第一处代码编辑前先做轻量变更分类，不按固定时长计时。若任务涉及 Product Surface work（Web UI、移动/桌面屏幕、游戏 UI/HUD/菜单、CLI/TUI 输出、扩展或设备界面）、前端布局、UI/UX、产品模块边界或信息应该放在哪个 surface / 页面 / 模块，先做产品/页面定位检查，再完成变更分类：用户在这个 surface 要完成什么判断，产品必须提供哪些信息 / 动作 / 反馈，哪些信息不应常驻，哪些属于主层、下钻、运维、诊断、详情或其他页面，当前布局和信息密度是否匹配 surface 任务。若 UI 改动涉及输入、选择、搜索、筛选、表单/配置、调度/时间窗口、预算/配额/限流或加载/空态/错误态，按产品/UIUX Skill 的控件任务框架做轻量检查，识别既有 Context 或 Product Surface Contract 是否适用以及是否缺少长期 surface/控件契约；职责不清或需要治理时使用 `context_surface_contract`。多 surface、多页面或多模块归属不清时，先审查相关信息架构，再收窄到代码模块实现。该检查是判断是否需要 context-first 的输入，不等于必须更新 Context，也不要求独立文档、新角色或新的 gate。
-3. 对产品方案、UI/UX、系统设计、架构边界、API / Schema、模块设计原则、状态机或运行语义、验证设计等任务，第一处代码编辑前先编译当前任务契约：用 `Context Delta: none|required` 作为唯一正式长期事实判断点，再写本次 Task Contract，并把命中的模块设计上下文、它控制的当前选择、首选路径和 fallback / degraded path 条件写入任务契约；工程 / RFC / 实现类 Task Contract 还应包含 `Modularity Check: none|required|exception`。普通 bug fix、局部样式、小重构、局部漂移修复、测试修复或 spike 不强制编译任务契约。
+3. 对产品方案、UI/UX、系统设计、架构边界、模块 ownership、API / Schema / 数据契约、状态机或运行语义、依赖方向、验证 / 部署语义或 durable rationale / tradeoff 等高风险任务，第一处代码编辑前先编译当前任务契约：用 `Context Delta: none|required` 作为唯一正式长期事实判断点，再写本次 Task Contract，并把 `Architecture Context Hit`、`Decision Rationale Hit: existing|required|none`、命中的模块设计上下文、它控制的当前选择、首选路径和 fallback / degraded path 条件写入任务契约；工程 / RFC / 实现类 Task Contract 还应包含 `Modularity Check: none|required|exception`。普通 bug fix、局部样式、小重构、局部漂移修复、package/release 处理、测试修复或 spike 不强制编译任务契约。
 4. 当新增、迁移或整理 `project_context/areas/**` 时，做 role placement scan（软约束，不做 gate）：`area` / `domain` 保留产品域归属，`subdomain` 用于产品域内较小 ownership，`contract` 用于 API / schema / event / 跨域接口语义，`foundation` 用于稳定理论 / 词汇 / 背景材料，`verification` / `deployment` 用于可复用执行路径，`implementation-index` 只做代码导航索引，`decision-rationale` 记录稳定设计原因，`archive` 用于非默认读取的历史或外部材料。
 5. 若任务契约声明 `Context Delta: required`，默认走 context-first：第一处代码编辑前先更新相关 `project_context/**`，写入必要且足以指导实现的长期结论，再按 Context 和 Task Contract 对齐实现、验证和收尾。
 6. 普通 bug fix、局部样式、局部实现漂移修复、测试修复或探索性 spike 不更新 Context，可先改代码；一旦形成长期结论，继续对齐或交付前必须回写 `project_context/**`。

package/assets/context_templates/architecture.md

@@ -14,9 +14,11 @@ This is the restrained architecture context. Keep only facts that help a fresh a
 
 - Summarize only the durable request, event, state or data flow that is hard to infer from code alone.
 
-## Design Rationale
-
-- Record architecture-level choices that still constrain future work; architecture boundary changes should be captured here before implementation alignment.
+## Design Rationale
+
+- Record architecture-level choices, rejected alternatives and tradeoffs that still constrain future work; leave this empty when no stable architecture reason exists.
+- Do not invent rationale or store implementation summaries, PR notes, command output, test result claims, debug history, agent reasoning or reasons inferred only from current code shape.
+- Architecture boundary changes should be captured here before implementation alignment.
 
 ## Constraints And Tradeoffs
 

package/assets/context_templates/area.md

@@ -15,10 +15,11 @@
 
 ## Module Design Capsule
 
-- Principles: stable execution constraints that should affect future module work.
-- Design Logic: the minimum logic for choosing, rejecting, degrading or composing module behavior.
-- Design Rationale: only durable reasons that change later implementation or verification decisions.
-- Current standards, thresholds and commands belong in the relevant contract or verification Context, not as permanent principles.
+- Principles: stable execution constraints that should affect future module work.
+- Design Logic: the minimum logic for choosing, rejecting, degrading or composing module behavior.
+- Design Rationale: only durable reasons, rejected alternatives and tradeoffs that change later implementation or verification decisions; leave it empty when no stable reason exists.
+- Do not invent rationale or store implementation summaries, PR notes, command output, test result claims, screenshot review notes, debug history, agent reasoning or reasons inferred only from current code shape.
+- Current standards, thresholds and commands belong in the relevant contract or verification Context, not as permanent principles.
 
 ## Key Constraints
 

package/assets/context_templates/global.md

@@ -12,9 +12,11 @@
 
 - Capture the minimum background a fresh agent needs before changing code.
 
-## Design Rationale
-
-- Record durable choices that are hard to infer from code or tests. Classify changes before implementation; if a change alters product ownership/plans, module responsibilities, information architecture, API/Schema, state/scheduler semantics, cross-area boundaries, verification role paths or deployment role paths, update Context before code with enough durable context to guide implementation.
+## Design Rationale
+
+- Record only project-wide durable choices, rejected alternatives and tradeoffs that are hard to infer from code or tests and likely to affect future work. Leave this sparse when no stable reason exists.
+- Do not invent rationale or store implementation summaries, PR notes, command output, test result claims, screenshot review notes, debug history, agent reasoning or reasons inferred only from current code shape.
+- Classify changes before implementation; if a change alters product ownership/plans, module responsibilities, information architecture, API/Schema, state/scheduler semantics, cross-area boundaries, verification role paths or deployment role paths, update Context before code with enough durable context to guide implementation.
 
 ## Architecture Context
 

package/assets/context_templates/product-surface-contract.md

@@ -18,8 +18,9 @@ Write only project-specific facts that should guide future implementation. Do no
 - Main Surface Allows:
 - Main Surface Forbids:
 - Drilldown Ownership:
-- Long Task State Requirement:
-- Empty / Loading / Stale / Unavailable:
+- Long Task State Requirement:
+- Design Rationale:
+- Empty / Loading / Stale / Unavailable:
 - Security / Redaction:
 - Verification:
 
@@ -47,14 +48,16 @@ Update this Context when:
 
 - A surface responsibility changes.
 - Main/drilldown ownership changes.
-- A durable long-task state contract is introduced.
-- A repeated UI/product rule becomes reusable.
-- A platform-specific interaction rule becomes stable.
+- A durable long-task state contract is introduced.
+- A durable main/drilldown/diagnostic ownership rationale, rejected alternative or tradeoff will guide future changes.
+- A repeated UI/product rule becomes reusable.
+- A platform-specific interaction rule becomes stable.
 
 Do not update this Context for:
 
 - CSS-only fixes.
 - One-off screenshot observations.
-- Temporary audit notes.
-- Test logs.
-- Local implementation summaries.
+- Temporary audit notes.
+- Test logs.
+- Local implementation summaries.
+- PR notes, command output, screenshot review notes, debug history, agent reasoning or rationale inferred only from current code shape.

package/assets/skills/context_development_engineer/SKILL.md

@@ -20,15 +20,15 @@ Project-specific engineering rules belong in a separate project-local Skill unde
 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 机械补成代码改动摘要。
+4. 第一处代码编辑前，若任务影响 durable architecture boundary、module ownership、API / Schema / data contract、state / runtime semantics、dependency direction、verification / deployment semantics 或 durable rationale / tradeoff，先编译当前任务契约；契约第一段用 `Context Delta: none|required` 完成唯一正式长期事实判断，再写本次 `Task Contract`，并显式写 `Architecture Context Hit` 和 `Decision Rationale Hit: existing|required|none`。
+5. 普通 bug fix、局部样式、局部实现漂移修复、小重构、package/release 处理、测试修复或探索性 spike 不强制编译架构 / rationale 任务契约，也不更新 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 和当前实现形态是执行实例，不能反推或覆盖模块设计目标。
+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 职责，再继续实现。
@@ -64,29 +64,32 @@ Project-specific engineering rules belong in a separate project-local Skill unde
 ## 任务契约编译
 
 - 任务契约是当前工程任务的编译产物，不是事实源、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。
+- `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。
+- 高风险工程任务只新增这两个显性 Task Contract 字段，不新增长模板或第二套 durable-fact gate：
+  - `Architecture Context Hit: <architecture.md | area/subdomain Context | contract Context | Module Design Capsule | none>`：命名控制本次技术判断的 Context。若命中 `none` 且本任务创建 durable architecture meaning，`Context Delta` 必须是 `required`。
+  - `Decision Rationale Hit: <existing | required | none>`：`existing` 表示现有 Context 已解释 durable reason；`required` 表示本任务创建或改变 durable rationale、rejected alternative、tradeoff 或 future-change constraint，必须走 `Context Delta: required`；`none` 表示没有稳定 rationale 或变化局部且自明。
+- 触及 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。
+- `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 强制编译任务契约。
+- 不为普通代码修改、bug fix、小重构、package/release 处理、测试修复、探索性 spike 或仅因 touched file 过大强制编译架构 / rationale 任务契约；大文件只走 `Modularity Check` 的拆分 / exception 判断。
 
 ## 模块设计上下文写法
 
 - 模块设计上下文应是 Minimal Context，不是设计论文；只保留短、准、稳定、会影响后续实现或验证选择的内容。
-- `Principles` 写稳定执行约束；`Design Logic` 写模块如何判断、选择、降级或组合能力；`Design Rationale` 只写会改变后续判断的原因。
-- `Current Standard`、`Verification Paths`、阈值、命令和 probe 参数是当前执行实例，不是永久原则；规则变化时更新对应 Context，而不是让旧命令继续定义目标。
-- 一次性证据、历史过程、完整日志、临时 JSON、raw payload、测试报告和任务契约不进入高频模块原则段。
+- `Principles` 写稳定执行约束；`Design Logic` 写模块如何判断、选择、降级或组合能力；`Design Rationale` 只写会改变后续判断的原因、rejected alternative 或 tradeoff。
+- `Current Standard`、`Verification Paths`、阈值、命令和 probe 参数是当前执行实例，不是永久原则；规则变化时更新对应 Context，而不是让旧命令继续定义目标。
+- 不编造 rationale；仅由当前代码形态反推的理由、一次性证据、实现摘要、PR notes、命令输出、截图审查、debug 过程、agent reasoning、完整日志、临时 JSON、raw payload、测试报告和任务契约不进入高频模块原则段。
 
 ## 输出边界
 
@@ -97,12 +100,17 @@ Project-specific engineering rules belong in a separate project-local Skill unde
 
 ## 建议沉淀位置
 
-- `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、触发词、按需读取策略和可选边界规则。
+- `global.md#Design Rationale`：跨模块工程取舍。
+- `architecture.md#Design Rationale`：架构级选择、rejected alternatives 和 tradeoffs。
+- `global.md#Current State`：影响后续恢复的实现状态。
+- `areas/*.md#User / System Contract`：模块可见行为、API、CLI、UI 或数据契约。
+- `areas/*.md#Module Design Capsule`：模块级 principles、design logic 和会影响后续判断的 rationale。
+- `areas/*.md#Core Data / API / State`：关键数据结构、接口、状态流或规则。
+- `areas/*.md#Key Constraints`：性能、安全、兼容、集成或维护约束。
+- role=`contract` Context：跨域 API / schema / event / interface 语义及其 durable rationale。
+- role=`decision-rationale` Context：更大或跨切面的稳定设计原因。
+- `areas/*.md#Code Entry Points`：未来 agent 需要快速定位的代码入口。
+- `areas/*/verification.md` 或 role=`verification` Context：关键测试、smoke、CI、probe 或验证重复执行路径。
+- `areas/*/deployment.md` 或 role=`deployment` Context：关键部署、云端初始化、运行拓扑、健康检查或回滚重复执行路径。
+- `DESIGN.md`：视觉 identity、design token 和视觉 rationale。
+- `project_context/context.toml`：复杂项目的产品域 area/context_unit、role、触发词、按需读取策略和可选边界规则。

package/assets/skills/context_product_plan/SKILL.md

@@ -80,10 +80,12 @@ Project-specific product planning rules belong in a separate project-local Skill
 
 ## 建议沉淀位置
 
-- `global.md#Product / Delivery Brief`：项目级产品目标、用户、核心流程和非目标。
-- `global.md#Design Rationale`：长期产品取舍。
-- `areas/*.md#User / System Contract`：产品域可见行为、API、CLI、UI 或数据契约。
-- `areas/*.md#Key Constraints`：业务规则、边界、风险和不易从代码看出的约束。
-- `areas/*/verification.md` 或 role=`verification` Context：关键测试、smoke、CI、probe 或验证重复执行路径。
-- `areas/*/deployment.md` 或 role=`deployment` Context：关键部署、云端初始化、运行拓扑、健康检查或回滚重复执行路径。
-- `project_context/context.toml`：复杂项目的产品域 area/context_unit、role、触发词、按需读取策略和可选边界规则。
+- `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、触发词、按需读取策略和可选边界规则。

package/assets/skills/context_surface_contract/SKILL.md

@@ -26,10 +26,12 @@ Use existing roles:
 - `contract` for cross-surface, cross-area or project-level Product Surface Contracts.
 - `area` or `subdomain` for owning product-domain Screen Contracts.
 - `verification` for repeatable UI, CLI, app or product-surface validation paths.
-- `decision-rationale` for stable product-surface tradeoff reasons.
-- `implementation-index` for code navigation only.
-
-Forbidden roles include `surface-contract`, `product-surface`, `web-contract`, `app-contract` and `game-surface`.
+- `decision-rationale` for stable product-surface tradeoff reasons.
+- `implementation-index` for code navigation only.
+
+Forbidden roles include `surface-contract`, `product-surface`, `web-contract`, `app-contract` and `game-surface`.
+
+Use `DESIGN.md` only for visual identity, visual tokens and visual rationale. Do not put surface responsibility, main/drilldown ownership or diagnostic placement into `DESIGN.md`.
 
 ## Mode Selection
 
@@ -108,7 +110,7 @@ Output:
 - Implementation Drift.
 - Verification run / not_run / failed.
 
-Do not store one-off evidence, screenshots, logs, raw outputs or implementation summaries in Context.
+Do not store one-off evidence, screenshots, logs, raw outputs or implementation summaries in Context.
 
 ## Compiler Questions
 
@@ -162,7 +164,8 @@ Final handoff should include concise `Surface Contract Conformance`: contract so
 ## Output Boundaries
 
 - Do not create PRDs, UI/UX handoff docs, ADRs, stage artifacts, lifecycle state or phase gates.
-- Do not update Context for ordinary CSS tweaks, copy edits or one-off UI bug fixes unless durable surface responsibility changes.
-- Do not treat current backend fields, enums, JSON, screenshots or terminal output as product intent.
-- Do not add a validator, edit-order gate or package-level mandatory Surface Contract gate.
-- Do not include business-domain examples in this package-managed Skill.
+- Do not update Context for ordinary CSS tweaks, copy edits or one-off UI bug fixes unless durable surface responsibility changes.
+- Do not treat current backend fields, enums, JSON, screenshots or terminal output as product intent.
+- Do not invent rationale; rejected alternatives or tradeoffs belong in Context only when they are stable enough to affect future surface decisions.
+- Do not add a validator, edit-order gate or package-level mandatory Surface Contract gate.
+- Do not include business-domain examples in this package-managed Skill.

package/assets/skills/context_uiux_design/SKILL.md

@@ -104,10 +104,14 @@ Project-specific UI/UX and visual design rules belong in a separate project-loca
 
 ## 建议沉淀位置
 
-- `global.md#UX / Screen Brief`：全局体验原则、主要屏幕、跨模块流程。
-- `areas/*.md#User / System Contract`：页面、组件、状态、交互和数据展示契约。
-- `areas/*.md#Key Constraints`：responsive、a11y、品牌/视觉边界、加载/空态/错误态约束。
-- `areas/*/verification.md` 或 role=`verification` Context：UI smoke、截图验收、可访问性检查或项目自己的关键验证重复执行路径。
-- `areas/*/deployment.md` 或 role=`deployment` Context：前端部署、预览环境、运行拓扑或健康检查重复执行路径。
-- `project_context/context.toml`：复杂项目的产品域 area/context_unit、role、触发词、按需读取策略和可选边界规则。
-- `DESIGN.md`：视觉 identity、design tokens、组件视觉规则和 do/don't。
+- `global.md#UX / Screen Brief`：全局体验原则、主要屏幕、跨模块流程。
+- `areas/*.md#User / System Contract`：页面、组件、状态、交互和数据展示契约。
+- `areas/*.md#Key Constraints`：responsive、a11y、品牌/视觉边界、加载/空态/错误态约束。
+- role=`contract` Context：跨页面 / 跨域界面契约及其 durable rationale。
+- role=`decision-rationale` Context：更大或跨切面的稳定交互、信息架构或 surface ownership 取舍原因。
+- `areas/*/verification.md` 或 role=`verification` Context：UI smoke、截图验收、可访问性检查或项目自己的关键验证重复执行路径。
+- `areas/*/deployment.md` 或 role=`deployment` Context：前端部署、预览环境、运行拓扑或健康检查重复执行路径。
+- `project_context/context.toml`：复杂项目的产品域 area/context_unit、role、触发词、按需读取策略和可选边界规则。
+- `DESIGN.md`：视觉 identity、design tokens、组件视觉规则、do/don't 和视觉 rationale。
+
+不要编造 rationale；仅由当前代码或截图形态反推的理由、实现摘要、PR notes、命令输出、测试通过声明、截图审查、debug 过程和 agent reasoning 不进入 Context 或 `DESIGN.md`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-tiny-context-harness",
-  "version": "0.2.59",
+  "version": "0.2.60",
   "description": "Minimal project memory and validation harness for AI coding agents.",
   "license": "MIT",
   "author": "Seven128",