project-tiny-context-harness 0.2.57 → 0.2.59

package/assets/README.zh-CN.md

@@ -1,133 +1,133 @@
-# Project Tiny Context Harness 中文快速说明
-
-[English README](README.md)
-
-Project Tiny Context Harness 是给 AI coding agents 用的轻量项目记忆层。
-
-它不是新的全流程 Tiny Context 框架，也不是任务管理器。它做一件小事：把新会话 agent 最容易丢掉、但又必须长期稳定保留的项目事实放进仓库里，让下一次聊天、交接、调试或换工具时不用从头重新发现。
-
-一句话：
-
-```text
-Keep the memory. Drop the ceremony.
-保留项目记忆，丢掉流程仪式感。
-```
-
-## 它解决什么问题
-
-很多 agent 在一个对话里表现很好，但换到新对话后会重新问、重新猜或重新扫描：
-
-- 项目到底要解决什么问题
-- 哪些事情明确不做
-- 架构边界在哪里
-- 哪些文件是事实源
-- 改完以后应该跑什么验证
-- 上一次任务留下了哪些长期约束
-
-Project Tiny Context Harness 把这些内容压缩到几个 repo-native 文件里：
-
-- `AGENTS.md`
-- `project_context/context.toml`
-- `project_context/global.md`
-- `project_context/architecture.md`
-- `project_context/areas/**`
-
-Fresh agent 先读这些文件，再开始改代码。
-
-## 和传统 Tiny Context 流程的区别
-
-这个项目以前尝试过更重的阶段式 Tiny Context：阶段状态、任务流转、PRD / 技术方案 / 实现 / 评审 / 测试 / 发布产物和多个 gate。
-
-后来放弃这个方向，原因很直接：
-
-- 中小任务里，阶段流转和产物校验会显著拖慢执行。
-- 现代 coding agents 已经内化了很多普通软件工程循环：理解、设计、实现、测试、修复。
-- 真正值得保留下来的不是“每次任务都走完整流程”，而是“新 agent 能快速恢复项目长期事实”。
-
-所以当前默认方向是 Minimal Context Harness：只维护高密度、长期有效、能帮助恢复上下文的项目事实。
-
-对于长程任务，Harness 也提供一个轻量的计划验收清单 Skill：当用户明确给出或引用某份方案 / 计划 / RFC / implementation plan，并要求生成验收清单、完成定义或 goal/target 模式提示词时，它会把计划和验收清单临时放到 `tmp/ty-context/plan-acceptance/**`。这只是执行前的一次验收标准梳理，不执行计划、不证明完成，也不会把临时清单注册成 `project_context/**`。
-
-## 适合谁
-
-适合：
-
-- 经常用 Codex、Claude Code、Cursor、Gemini CLI、OpenCode 等 agent 改代码的项目。
-- 经常开新 chat，agent 反复重新理解项目的项目。
-- 想保留项目意图、边界和验证路径，但不想引入完整流程文档链的维护者。
-- 多 agent / 多工具协作时，需要一个工具无关的 repo 内事实源。
-
-不适合：
-
-- 替代测试、CI、review 或人工验收。
-- 自动执行完整 Tiny Context。
-- 做代码语义索引或外部文档检索。
-- 给每个任务强制生成 PRD、技术方案、测试报告和发布文档。
-
-## 快速试用
-
-npm 新包名还在等待发布。如果 `project-tiny-context-harness@latest` 尚未可用，可以先用源码 smoke 路径：
-
-```sh
-git clone https://github.com/Seven128/project-tiny-context-harness.git
-cd project-tiny-context-harness
-npm ci
-npm run smoke:quickstart
-```
-
-发布完成后，普通项目使用：
-
-```sh
-npm install -D project-tiny-context-harness@latest
-npx --yes --package project-tiny-context-harness@latest ty-context init
-make validate-context
-```
-
-生成的核心结构类似：
-
-```text
-AGENTS.md
-project_context/
-  context.toml
-  global.md
-  architecture.md
-  areas/main.md
-  areas/main/verification.md
-```
-
-## 一个简单的使用方式
-
-在新 agent 会话里先发：
-
-```text
-Read AGENTS.md and project_context/** first. Summarize the project goal, non-goals, architecture boundaries, validation entry points and next safe action before proposing code changes.
-```
-
-如果 agent 能快速说清楚项目目标、非目标、边界和验证入口，而不是重新扫描整个仓库猜测方向，这个 Harness 就发挥作用了。
-
-## Benchmark 说明
-
-不要把旧阶段式 Tiny Context 的 benchmark 数字当成当前 Minimal Context Harness 的性能证明。
-
-当前公开卖点是产品设计和 smoke 证据：它能安装一个小的项目记忆面，并用 `validate-context` 检查恢复事实是否存在。真正的效率结论需要重新设计 fresh baseline 和 Minimal Context Harness 的对照实验。
-
-## 反馈
-
-现在最有价值的反馈不是“能不能多加流程”，而是：
-
-- 你的 agent 经常忘掉什么项目事实？
-- 哪些事实应该长期留在仓库里？
-- `project_context/**` 是否太多、太少或不够好读？
-- 新 chat 是否更快恢复了项目意图？
-
-可以在 GitHub issue 里反馈：
-
-- [Adoption reports](https://github.com/Seven128/project-tiny-context-harness/issues/4)
-- [Demo starter issue](https://github.com/Seven128/project-tiny-context-harness/issues/5)
-- [Sample walkthrough starter issue](https://github.com/Seven128/project-tiny-context-harness/issues/6)
-
-## 语言策略
-
-本项目的默认 README、npm copy 和公开 launch 文案保持英文优先，方便 GitHub、Hacker News、Reddit、Product Hunt 和 curated lists 上的开发者快速判断项目价值。
-
-中文文档作为二级入口保留，用来服务中文用户和维护者，但不会替代英文主入口。
+# Project Tiny Context Harness 中文快速说明
+
+[English README](README.md)
+
+Project Tiny Context Harness 是给 AI coding agents 用的轻量项目记忆层。
+
+它不是新的全流程 Tiny Context 框架，也不是任务管理器。它做一件小事：把新会话 agent 最容易丢掉、但又必须长期稳定保留的项目事实放进仓库里，让下一次聊天、交接、调试或换工具时不用从头重新发现。
+
+一句话：
+
+```text
+Keep the memory. Drop the ceremony.
+保留项目记忆，丢掉流程仪式感。
+```
+
+## 它解决什么问题
+
+很多 agent 在一个对话里表现很好，但换到新对话后会重新问、重新猜或重新扫描：
+
+- 项目到底要解决什么问题
+- 哪些事情明确不做
+- 架构边界在哪里
+- 哪些文件是事实源
+- 改完以后应该跑什么验证
+- 上一次任务留下了哪些长期约束
+
+Project Tiny Context Harness 把这些内容压缩到几个 repo-native 文件里：
+
+- `AGENTS.md`
+- `project_context/context.toml`
+- `project_context/global.md`
+- `project_context/architecture.md`
+- `project_context/areas/**`
+
+Fresh agent 先读这些文件，再开始改代码。
+
+## 和传统 Tiny Context 流程的区别
+
+这个项目以前尝试过更重的阶段式 Tiny Context：阶段状态、任务流转、PRD / 技术方案 / 实现 / 评审 / 测试 / 发布产物和多个 gate。
+
+后来放弃这个方向，原因很直接：
+
+- 中小任务里，阶段流转和产物校验会显著拖慢执行。
+- 现代 coding agents 已经内化了很多普通软件工程循环：理解、设计、实现、测试、修复。
+- 真正值得保留下来的不是“每次任务都走完整流程”，而是“新 agent 能快速恢复项目长期事实”。
+
+所以当前默认方向是 Minimal Context Harness：只维护高密度、长期有效、能帮助恢复上下文的项目事实。
+
+对于长程任务，Harness 也提供一个轻量的计划验收清单 Skill：当用户明确给出或引用某份方案 / 计划 / RFC / implementation plan，并要求生成验收清单、完成定义或 goal/target 模式提示词时，它会把计划和验收清单临时放到 `tmp/ty-context/plan-acceptance/**`。这只是执行前的一次验收标准梳理，不执行计划、不证明完成，也不会把临时清单注册成 `project_context/**`。
+
+## 适合谁
+
+适合：
+
+- 经常用 Codex、Claude Code、Cursor、Gemini CLI、OpenCode 等 agent 改代码的项目。
+- 经常开新 chat，agent 反复重新理解项目的项目。
+- 想保留项目意图、边界和验证路径，但不想引入完整流程文档链的维护者。
+- 多 agent / 多工具协作时，需要一个工具无关的 repo 内事实源。
+
+不适合：
+
+- 替代测试、CI、review 或人工验收。
+- 自动执行完整 Tiny Context。
+- 做代码语义索引或外部文档检索。
+- 给每个任务强制生成 PRD、技术方案、测试报告和发布文档。
+
+## 快速试用
+
+npm 新包名还在等待发布。如果 `project-tiny-context-harness@latest` 尚未可用，可以先用源码 smoke 路径：
+
+```sh
+git clone https://github.com/Seven128/project-tiny-context-harness.git
+cd project-tiny-context-harness
+npm ci
+npm run smoke:quickstart
+```
+
+发布完成后，普通项目使用：
+
+```sh
+npm install -D project-tiny-context-harness@latest
+npx --yes --package project-tiny-context-harness@latest ty-context init
+make validate-context
+```
+
+生成的核心结构类似：
+
+```text
+AGENTS.md
+project_context/
+  context.toml
+  global.md
+  architecture.md
+  areas/main.md
+  areas/main/verification.md
+```
+
+## 一个简单的使用方式
+
+在新 agent 会话里先发：
+
+```text
+Read AGENTS.md and project_context/** first. Summarize the project goal, non-goals, architecture boundaries, validation entry points and next safe action before proposing code changes.
+```
+
+如果 agent 能快速说清楚项目目标、非目标、边界和验证入口，而不是重新扫描整个仓库猜测方向，这个 Harness 就发挥作用了。
+
+## Benchmark 说明
+
+不要把旧阶段式 Tiny Context 的 benchmark 数字当成当前 Minimal Context Harness 的性能证明。
+
+当前公开卖点是产品设计和 smoke 证据：它能安装一个小的项目记忆面，并用 `validate-context` 检查恢复事实是否存在。真正的效率结论需要重新设计 fresh baseline 和 Minimal Context Harness 的对照实验。
+
+## 反馈
+
+现在最有价值的反馈不是“能不能多加流程”，而是：
+
+- 你的 agent 经常忘掉什么项目事实？
+- 哪些事实应该长期留在仓库里？
+- `project_context/**` 是否太多、太少或不够好读？
+- 新 chat 是否更快恢复了项目意图？
+
+可以在 GitHub issue 里反馈：
+
+- [Adoption reports](https://github.com/Seven128/project-tiny-context-harness/issues/4)
+- [Demo starter issue](https://github.com/Seven128/project-tiny-context-harness/issues/5)
+- [Sample walkthrough starter issue](https://github.com/Seven128/project-tiny-context-harness/issues/6)
+
+## 语言策略
+
+本项目的默认 README、npm copy 和公开 launch 文案保持英文优先，方便 GitHub、Hacker News、Reddit、Product Hunt 和 curated lists 上的开发者快速判断项目价值。
+
+中文文档作为二级入口保留，用来服务中文用户和维护者，但不会替代英文主入口。

package/assets/agents/.gitkeep

@@ -1 +1 @@
-
+

package/assets/agents/AGENTS_CORE.md

@@ -1,59 +1,59 @@
-# Minimal Context Harness Protocol
-
-本项目使用 Minimal Context Harness。Harness 只维护上下文质量，不替项目证明产品质量。
-
-## AGENTS.md 定位
-
-- `AGENTS.md` 是 agent 启动路由器和硬边界，只放事实源入口、不可违反规则、关键触发器和最短验证入口。
-- 长设计理由默认压缩进 `project_context/**`；若项目已有明确的本地 spec / design 文档，可按项目约定使用。角色流程 / checklist 放 Skills，人类使用说明放 README；新增 AGENTS 规则前优先压缩或替换旧规则，不默认追加。
-- 建议把 AGENTS 主路径保持在约 40-70 行；这是软预算，不是 validator 或 CI gate。
-
-## Context 优先级阶梯
-
-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`。
-5. `Context Delta: required` 则 context-first；普通 bug fix、局部样式、局部漂移修复、测试修复或 spike 默认 code-first，但一旦产生长期结论必须回写 Context。
-6. 收尾做 Contract Conformance 和 Context drift check，只报告 `Context: 已更新 ...` 或 `Context: 本次无长期事实变化`；不要把一次性证据、任务契约或实现摘要写入 Context。
-
-## 事实源
-
-- 项目全局上下文：`project_context/global.md`
-- 架构上下文：`project_context/architecture.md`（克制、最小，只记录系统边界、组件关系和长期约束）
-- Context 图谱：`project_context/context.toml`（Schema v4 默认事实源；声明产品域 area/context_unit、role、触发条件和按需读取策略）
-- 产品域 / context unit 上下文：`project_context/areas/**/*.md`
-- 产品质量事实：项目自己的代码、测试、smoke、CI、hidden probe 或人工验收
-
-## 工作规则
-
-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 不强制编译任务契约。
-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/**`。
-7. `project_context/**` 是项目意图、产品域职责、架构边界、集成方向、允许/禁止依赖、验证关键路径和部署关键路径的权威事实源；代码是当前实现状态的权威事实源。
-8. 当代码形态、搜索结果或相邻实现与 Context 声明冲突时，把差异视为实现漂移、缺失工作或 Context 过期并显式说明；不要用当前代码形态或关键词搜索结果覆盖 Context 已声明的职责、归属或集成意图。
-9. 每个有意义的方案或实现变更收尾时做 Contract Conformance 和 Context drift check：对照 Task Contract 区分实现偏差、契约遗漏或长期事实缺失；实现偏差修实现，契约遗漏回 Task Contract，长期事实缺失回 `Context Delta` 并先更新 Context。交付说明只报告轻量状态：`Context: 已更新 ...` 或 `Context: 本次无长期事实变化`；Conformance 证据属于本次交付，不写入 `project_context/**`。
-10. 长期事实只写入 `project_context/**`；不要默认创建 PRD、tech plan、ADR、implementation doc、review/test/release 文档。
-11. 用户明确要求“产品方案 / 产品经理 / 产品专家 / product plan / product manager / product spec”、“设计稿 / UI/UX 设计方案 / 视觉专家 / UX designer / UI designer / visual polish / design system spec”或“开发工程师 / 技术方案 / 开发方案 / 实现 / 实现方案 / 实施计划 / 技术专家 / software engineer / development plan / technical implementation plan / 多开agent / subagent”这类角色或强产物名时，使用对应 Context authoring Skill，把长期结论写回 `project_context/**`。
-12. 用户明确要求“导出尽可能详细的项目全量上下文 / 全量上下文导出 / full project context export / export full project context / 当前项目代码实现 / 代码级实现导出 / code-level implementation export”时，使用 `context_full_project_export` Skill；默认优先运行 `ty-context export-context --all` 同时生成项目级 Context 汇总和代码级实现快照；只需要单份产物时再用 `--full` 或 `--code`；导出产物只放 `tmp/ty-context/context-exports/**`，不得放入或注册到 `project_context/**` / `project_context/context.toml`。用户明确要求“upgrade Tiny Context / update Tiny Context / Project Tiny Context Harness upgrade / 用 Tiny Context upgrade skill 升级这个项目 / 升级 tiny context”时，使用 `context_harness_upgrade` Skill，先走 `upgrade`，不要先单独运行 `sync`。
-13. 用户提供或引用某份方案 / 计划 / RFC / implementation plan / milestone plan，并明确要求生成验收清单、完成定义、goal-mode prompt 或 target-mode prompt 时，使用 `plan_acceptance_checklist_compiler` Skill；输出只放 `tmp/ty-context/plan-acceptance/**`，它只定义验收标准，不执行计划、不证明完成、不把结果注册到 `project_context/**` / `project_context/context.toml`。
-14. 当任务涉及设计稿、重做设计、视觉方案、设计系统、visual polish、frontend redesign 或 frontend styling，且存在可扫描的 UI 代码、页面文件、构建产物目录或本地/远程 URL 时，默认运行 `npx impeccable detect <target>` 做 Impeccable 视觉审查；没有可扫描目标、命令不可用或扫描失败时，说明原因并继续。Impeccable 不是 `validate-context` gate，也不替代截图检查、项目测试或人工判断。
-15. Tiny Context / Harness managed surfaces 是生成资产：`AGENTS.md` managed block、`.agent/ty-context-managed/**`、`.agent/skills/context_product_plan/**`、`.agent/skills/context_uiux_design/**`、`.agent/skills/context_development_engineer/**`、`.agent/skills/context_surface_contract/**`、`.agent/skills/context_full_project_export/**`、`.agent/skills/context_harness_upgrade/**` 和 `.agent/skills/plan_acceptance_checklist_compiler/**` 禁止承载项目特定规则；直接编辑会在 `sync` 时被覆盖或产生漂移。项目本地产品 / UIUX / 开发 / surface contract 规则必须新建独立 Skill，例如 `.agent/skills/product_plan/SKILL.md`、`.agent/skills/uiux_design/SKILL.md`、`.agent/skills/development_engineer/SKILL.md` 或 `.agent/skills/surface_contract/SKILL.md`；当项目本地 Skill 与默认 Skill 同时适用时，优先使用更具体的项目本地 Skill。项目本地 Skill 的 front matter `description` 触发词应与本文件中的角色触发规则和对应默认 `context_*` Skill 保持一致；新增或收窄关键词时，同步更新本地 Skill 描述和项目级 agent 指引，避免 Skill 触发条件与 Tiny Context 工作规则漂移。
-16. ADR 降级为 Context 中的 `Design Rationale`；实现说明优先写成代码注释、测试名或模块 Context 中的关键约束。
-17. Harness workflow gate 只运行 `validate-context`，用于检查上下文是否可恢复；不检查 context/code 修改顺序。自动化最多提示 context-first 风险，不做阻断。
-18. 产品质量由项目自己的验证入口证明；Context 只能声明验证 / 部署关键路径，不能伪造“测试已通过”或“部署已成功”。
-19. Verification / Deployment Role Context 规则：area 是产品域归属；`verification` 和 `deployment` 是 area-owned 的按需读取角色，用来提高关键测试、smoke、CI、部署、云端初始化或运行拓扑路径的重复执行效率。Context 不记录一次性测试日志、完整命令输出、临时 JSON、CI artifact、测试报告、release ledger、secret、token、cookie、device id 或 raw payload；只记录特殊准备、最短命令或路径、预期阶段 / 信号、可接受 warning、已排除的重复探索点。跨产品域路径可放 project-level role Context，普通产品域路径放 owning area 下的 role Context。
-20. `sync` 只刷新 managed guidance、默认 Skill 和工具；不会合并 Skill override，也不会覆盖用户新建的独立项目本地 Skill。
-21. 普通项目默认只有一个 `main` area 和一个 `areas/main/verification.md`；monorepo 或 product-family 项目可在 `context.toml` 中增加多个产品域 `area` / `context_unit`，并用 `context_role` 或 manifest role 区分 `area`、`subdomain`、`contract`、`foundation`、`verification`、`deployment`、`archive`、`implementation-index` 和 `decision-rationale` 等不同 Context 类型。
-
-## 常用命令
-
-- `make validate-context`：检查 `project_context/**` 是否足够支持 agent 恢复上下文。
-- `make ty-context-sync`：刷新 managed guidance、Context template、默认 Skill 和工具。
-- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --all`：同时导出临时项目级 Context 汇总和代码级实现 Markdown 到 `tmp/ty-context/context-exports/**`。
-- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --full`：导出临时项目级 Context 汇总 Markdown 到 `tmp/ty-context/context-exports/**`。
-- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --code`：导出临时代码级实现 Markdown 到 `tmp/ty-context/context-exports/**`。
-- `npx --yes --package project-tiny-context-harness@latest ty-context doctor`：临时诊断 canonical Tiny Context CLI；避免裸 `npx ty-context` 解析到旧包名或旧本地缓存。
+# Minimal Context Harness Protocol
+
+本项目使用 Minimal Context Harness。Harness 只维护上下文质量，不替项目证明产品质量。
+
+## AGENTS.md 定位
+
+- `AGENTS.md` 是 agent 启动路由器和硬边界，只放事实源入口、不可违反规则、关键触发器和最短验证入口。
+- 长设计理由默认压缩进 `project_context/**`；若项目已有明确的本地 spec / design 文档，可按项目约定使用。角色流程 / checklist 放 Skills，人类使用说明放 README；新增 AGENTS 规则前优先压缩或替换旧规则，不默认追加。
+- 建议把 AGENTS 主路径保持在约 40-70 行；这是软预算，不是 validator 或 CI gate。
+
+## Context 优先级阶梯
+
+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`。
+5. `Context Delta: required` 则 context-first；普通 bug fix、局部样式、局部漂移修复、测试修复或 spike 默认 code-first，但一旦产生长期结论必须回写 Context。
+6. 收尾做 Contract Conformance 和 Context drift check，只报告 `Context: 已更新 ...` 或 `Context: 本次无长期事实变化`；不要把一次性证据、任务契约或实现摘要写入 Context。
+
+## 事实源
+
+- 项目全局上下文：`project_context/global.md`
+- 架构上下文：`project_context/architecture.md`（克制、最小，只记录系统边界、组件关系和长期约束）
+- Context 图谱：`project_context/context.toml`（Schema v4 默认事实源；声明产品域 area/context_unit、role、触发条件和按需读取策略）
+- 产品域 / context unit 上下文：`project_context/areas/**/*.md`
+- 产品质量事实：项目自己的代码、测试、smoke、CI、hidden probe 或人工验收
+
+## 工作规则
+
+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 不强制编译任务契约。
+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/**`。
+7. `project_context/**` 是项目意图、产品域职责、架构边界、集成方向、允许/禁止依赖、验证关键路径和部署关键路径的权威事实源；代码是当前实现状态的权威事实源。
+8. 当代码形态、搜索结果或相邻实现与 Context 声明冲突时，把差异视为实现漂移、缺失工作或 Context 过期并显式说明；不要用当前代码形态或关键词搜索结果覆盖 Context 已声明的职责、归属或集成意图。
+9. 每个有意义的方案或实现变更收尾时做 Contract Conformance 和 Context drift check：对照 Task Contract 区分实现偏差、契约遗漏或长期事实缺失；实现偏差修实现，契约遗漏回 Task Contract，长期事实缺失回 `Context Delta` 并先更新 Context。交付说明只报告轻量状态：`Context: 已更新 ...` 或 `Context: 本次无长期事实变化`；Conformance 证据属于本次交付，不写入 `project_context/**`。
+10. 长期事实只写入 `project_context/**`；不要默认创建 PRD、tech plan、ADR、implementation doc、review/test/release 文档。
+11. 用户明确要求“产品方案 / 产品经理 / 产品专家 / product plan / product manager / product spec”、“设计稿 / UI/UX 设计方案 / 视觉专家 / UX designer / UI designer / visual polish / design system spec”或“开发工程师 / 技术方案 / 开发方案 / 实现 / 实现方案 / 实施计划 / 技术专家 / software engineer / development plan / technical implementation plan / 多开agent / subagent”这类角色或强产物名时，使用对应 Context authoring Skill，把长期结论写回 `project_context/**`。
+12. 用户明确要求“导出尽可能详细的项目全量上下文 / 全量上下文导出 / full project context export / export full project context / 当前项目代码实现 / 代码级实现导出 / code-level implementation export”时，使用 `context_full_project_export` Skill；默认优先运行 `ty-context export-context --all` 同时生成项目级 Context 汇总和代码级实现快照；只需要单份产物时再用 `--full` 或 `--code`；导出产物只放 `tmp/ty-context/context-exports/**`，不得放入或注册到 `project_context/**` / `project_context/context.toml`。用户明确要求“upgrade Tiny Context / update Tiny Context / Project Tiny Context Harness upgrade / 用 Tiny Context upgrade skill 升级这个项目 / 升级 tiny context”时，使用 `context_harness_upgrade` Skill，先走 `upgrade`，不要先单独运行 `sync`。
+13. 用户提供或引用某份方案 / 计划 / RFC / implementation plan / milestone plan，并明确要求生成验收清单、完成定义、goal-mode prompt 或 target-mode prompt 时，使用 `plan_acceptance_checklist_compiler` Skill；输出只放 `tmp/ty-context/plan-acceptance/**`，它只定义验收标准，不执行计划、不证明完成、不把结果注册到 `project_context/**` / `project_context/context.toml`。
+14. 当任务涉及设计稿、重做设计、视觉方案、设计系统、visual polish、frontend redesign 或 frontend styling，且存在可扫描的 UI 代码、页面文件、构建产物目录或本地/远程 URL 时，默认运行 `npx impeccable detect <target>` 做 Impeccable 视觉审查；没有可扫描目标、命令不可用或扫描失败时，说明原因并继续。Impeccable 不是 `validate-context` gate，也不替代截图检查、项目测试或人工判断。
+15. Tiny Context / Harness managed surfaces 是生成资产：`AGENTS.md` managed block、`.agent/ty-context-managed/**`、`.agent/skills/context_product_plan/**`、`.agent/skills/context_uiux_design/**`、`.agent/skills/context_development_engineer/**`、`.agent/skills/context_surface_contract/**`、`.agent/skills/context_full_project_export/**`、`.agent/skills/context_harness_upgrade/**` 和 `.agent/skills/plan_acceptance_checklist_compiler/**` 禁止承载项目特定规则；直接编辑会在 `sync` 时被覆盖或产生漂移。项目本地产品 / UIUX / 开发 / surface contract 规则必须新建独立 Skill，例如 `.agent/skills/product_plan/SKILL.md`、`.agent/skills/uiux_design/SKILL.md`、`.agent/skills/development_engineer/SKILL.md` 或 `.agent/skills/surface_contract/SKILL.md`；当项目本地 Skill 与默认 Skill 同时适用时，优先使用更具体的项目本地 Skill。项目本地 Skill 的 front matter `description` 触发词应与本文件中的角色触发规则和对应默认 `context_*` Skill 保持一致；新增或收窄关键词时，同步更新本地 Skill 描述和项目级 agent 指引，避免 Skill 触发条件与 Tiny Context 工作规则漂移。
+16. ADR 降级为 Context 中的 `Design Rationale`；实现说明优先写成代码注释、测试名或模块 Context 中的关键约束。
+17. Harness workflow gate 只运行 `validate-context`，用于检查上下文是否可恢复；不检查 context/code 修改顺序。自动化最多提示 context-first 风险，不做阻断。
+18. 产品质量由项目自己的验证入口证明；Context 只能声明验证 / 部署关键路径，不能伪造“测试已通过”或“部署已成功”。
+19. Verification / Deployment Role Context 规则：area 是产品域归属；`verification` 和 `deployment` 是 area-owned 的按需读取角色，用来提高关键测试、smoke、CI、部署、云端初始化或运行拓扑路径的重复执行效率。Context 不记录一次性测试日志、完整命令输出、临时 JSON、CI artifact、测试报告、release ledger、secret、token、cookie、device id 或 raw payload；只记录特殊准备、最短命令或路径、预期阶段 / 信号、可接受 warning、已排除的重复探索点。跨产品域路径可放 project-level role Context，普通产品域路径放 owning area 下的 role Context。
+20. `sync` 只刷新 managed guidance、默认 Skill 和工具；不会合并 Skill override，也不会覆盖用户新建的独立项目本地 Skill。
+21. 普通项目默认只有一个 `main` area 和一个 `areas/main/verification.md`；monorepo 或 product-family 项目可在 `context.toml` 中增加多个产品域 `area` / `context_unit`，并用 `context_role` 或 manifest role 区分 `area`、`subdomain`、`contract`、`foundation`、`verification`、`deployment`、`archive`、`implementation-index` 和 `decision-rationale` 等不同 Context 类型。
+
+## 常用命令
+
+- `make validate-context`：检查 `project_context/**` 是否足够支持 agent 恢复上下文。
+- `make ty-context-sync`：刷新 managed guidance、Context template、默认 Skill 和工具。
+- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --all`：同时导出临时项目级 Context 汇总和代码级实现 Markdown 到 `tmp/ty-context/context-exports/**`。
+- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --full`：导出临时项目级 Context 汇总 Markdown 到 `tmp/ty-context/context-exports/**`。
+- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --code`：导出临时代码级实现 Markdown 到 `tmp/ty-context/context-exports/**`。
+- `npx --yes --package project-tiny-context-harness@latest ty-context doctor`：临时诊断 canonical Tiny Context CLI；避免裸 `npx ty-context` 解析到旧包名或旧本地缓存。

package/assets/context_templates/architecture.md

@@ -1,31 +1,31 @@
-# Architecture Context
-
-This is the restrained architecture context. Keep only facts that help a fresh agent recover system shape, boundaries and durable constraints quickly.
-
-## System Boundary
-
-- Describe what is inside this project and what external systems, providers or runtime assumptions sit outside it.
-
-## Component Map
-
-- List the smallest useful set of components, areas or context units and how they relate.
-
-## Data / Control Flow
-
-- 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.
-
-## Constraints And Tradeoffs
-
-- Capture performance, safety, integration, deployment or maintainability constraints that matter for future changes.
-
-## Verification Implications
-
-- List project-specific verification entry points affected by architectural changes; do not claim tests already passed.
-
-## Open Risks
-
-- List unresolved architectural risks or unknowns.
+# Architecture Context
+
+This is the restrained architecture context. Keep only facts that help a fresh agent recover system shape, boundaries and durable constraints quickly.
+
+## System Boundary
+
+- Describe what is inside this project and what external systems, providers or runtime assumptions sit outside it.
+
+## Component Map
+
+- List the smallest useful set of components, areas or context units and how they relate.
+
+## Data / Control Flow
+
+- 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.
+
+## Constraints And Tradeoffs
+
+- Capture performance, safety, integration, deployment or maintainability constraints that matter for future changes.
+
+## Verification Implications
+
+- List project-specific verification entry points affected by architectural changes; do not claim tests already passed.
+
+## Open Risks
+
+- List unresolved architectural risks or unknowns.

package/assets/context_templates/area.md

@@ -1,38 +1,38 @@
-# Area Context: main
-
-## Responsibility
-
-- Describe this product/domain area or context unit's responsibility.
-
-## User / System Contract
-
-- Describe the external behavior, API, CLI, UI, screen state, interaction or data contract. Contract changes should be captured here before implementation alignment.
-- For UI/page areas, name the page responsibility, core user judgment, persistent information/actions/feedback, non-persistent information, and what belongs in downstream consumption, ops, detail or other surfaces when those facts are durable.
-
-## Core Data / API / State
-
-- Summarize important data structures, APIs, state transitions or rules.
-
-## 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.
-
-## Key Constraints
-
-- List constraints that are not obvious from code alone, including product rules, responsive/a11y needs or visual boundaries.
-
-## Code Entry Points
-
-- `src/` or the concrete file/function entry points.
-
-## Related Role Context
-
-- Verification paths live in this area's `verification` role Context, such as `project_context/areas/main/verification.md`.
-- Deployment/runtime/bootstrap paths live in this area's optional `deployment` role Context when those facts exist.
-
-## Open Risks
-
-- List unresolved risks or blockers.
+# Area Context: main
+
+## Responsibility
+
+- Describe this product/domain area or context unit's responsibility.
+
+## User / System Contract
+
+- Describe the external behavior, API, CLI, UI, screen state, interaction or data contract. Contract changes should be captured here before implementation alignment.
+- For UI/page areas, name the page responsibility, core user judgment, persistent information/actions/feedback, non-persistent information, and what belongs in downstream consumption, ops, detail or other surfaces when those facts are durable.
+
+## Core Data / API / State
+
+- Summarize important data structures, APIs, state transitions or rules.
+
+## 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.
+
+## Key Constraints
+
+- List constraints that are not obvious from code alone, including product rules, responsive/a11y needs or visual boundaries.
+
+## Code Entry Points
+
+- `src/` or the concrete file/function entry points.
+
+## Related Role Context
+
+- Verification paths live in this area's `verification` role Context, such as `project_context/areas/main/verification.md`.
+- Deployment/runtime/bootstrap paths live in this area's optional `deployment` role Context when those facts exist.
+
+## Open Risks
+
+- List unresolved risks or blockers.

package/assets/context_templates/context.toml

@@ -1,27 +1,27 @@
-# Schema v4 Minimal Context graph manifest.
-# Keep the default product/domain area for ordinary projects. Role context nodes
-# are read-purpose slices owned by an area or, only when cross-domain, by the project root.
-# When migrating deep files under project_context/areas/**, refine obvious
-# contract/foundation/subdomain/verification/deployment/implementation-index/
-# decision-rationale/archive files into [[context]] entries instead of keeping
-# every Markdown file as an [[areas]] product owner.
-
-[[areas]]
-id = "main"
-root = "."
-context = "project_context/areas/main.md"
-kind = "app"
-default = true
-
-[[context]]
-path = "project_context/areas/main/verification.md"
-role = "verification"
-read_policy = "default"
-triggers = ["test", "verify", "verification", "smoke", "ci"]
-
-# Example optional node:
-# [[context]]
-# path = "project_context/areas/main/deployment.md"
-# role = "deployment"
-# read_policy = "on-demand"
-# triggers = ["deploy", "deployment", "runtime", "cloud", "docker"]
+# Schema v4 Minimal Context graph manifest.
+# Keep the default product/domain area for ordinary projects. Role context nodes
+# are read-purpose slices owned by an area or, only when cross-domain, by the project root.
+# When migrating deep files under project_context/areas/**, refine obvious
+# contract/foundation/subdomain/verification/deployment/implementation-index/
+# decision-rationale/archive files into [[context]] entries instead of keeping
+# every Markdown file as an [[areas]] product owner.
+
+[[areas]]
+id = "main"
+root = "."
+context = "project_context/areas/main.md"
+kind = "app"
+default = true
+
+[[context]]
+path = "project_context/areas/main/verification.md"
+role = "verification"
+read_policy = "default"
+triggers = ["test", "verify", "verification", "smoke", "ci"]
+
+# Example optional node:
+# [[context]]
+# path = "project_context/areas/main/deployment.md"
+# role = "deployment"
+# read_policy = "on-demand"
+# triggers = ["deploy", "deployment", "runtime", "cloud", "docker"]