project-tiny-context-harness 0.2.53 → 0.2.55

package/assets/github/harness.yml

@@ -1,4 +1,4 @@
-# pjsdlc:sdlc-harness:github-workflow:begin
+# ty-context:github-workflow:begin
 name: Harness Gates
 
 on:
@@ -14,24 +14,28 @@ on:
         default: "validate-context"
         type: choice
         options:
-          - validate-context
-          - validate-harness
-
-jobs:
-  harness:
-    runs-on: ubuntu-latest
-    steps:
+          - validate-context
+          - validate-code-modularity
+          - validate-harness
+
+jobs:
+  harness:
+    runs-on: ubuntu-latest
+    steps:
       - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
       - uses: actions/setup-node@v6
         with:
           node-version: "24"
       - name: Prepare source workspace CLI
-        if: ${{ hashFiles('packages/sdlc-harness/package.json') != '' }}
+        if: ${{ hashFiles('packages/ty-context/package.json') != '' }}
         run: |
           npm ci
           npm run build --workspace project-tiny-context-harness
       - name: Run harness gate
         run: make "${HARNESS_GATE}"
         env:
-          HARNESS_GATE: ${{ github.event.inputs.gate || 'validate-context' }}
-# pjsdlc:sdlc-harness:github-workflow:end
+          HARNESS_GATE: ${{ github.event.inputs.gate || 'validate-harness' }}
+          TY_CONTEXT_MODULARITY_BASE: ${{ github.event_name == 'pull_request' && format('origin/{0}', github.base_ref) || github.event.before || '' }}
+# ty-context:github-workflow:end

package/assets/make/ty-context.mk

@@ -0,0 +1,48 @@
+PYTHON ?= python3
+TY_CONTEXT ?= $(if $(wildcard packages/ty-context/dist/cli.js),node packages/ty-context/dist/cli.js,npx --yes --package project-tiny-context-harness@latest ty-context)
+TY_CONTEXT_MODULARITY_SCOPE = $(if $(TY_CONTEXT_MODULARITY_BASE),--base $(TY_CONTEXT_MODULARITY_BASE),--touched)
+
+.PHONY: help ty-context-doctor ty-context-sync ty-context-upgrade ty-context-check-modularity validate-context validate-code-modularity validate-harness lint test-current-domain test-all build
+
+help:
+	@echo "Minimal Context Harness commands"
+	@echo "  make ty-context-doctor         Diagnose Harness root, core package and schema version"
+	@echo "  make ty-context-sync           Refresh managed assets; refuses when upgrade migrations are pending"
+	@echo "  make ty-context-upgrade        Run safe upgrade migrations, sync managed assets and doctor"
+	@echo "  make ty-context-check-modularity  Warn on oversized touched handwritten source files"
+	@echo "  make validate-context    Check whether project_context/** supports context recovery"
+	@echo "  make validate-code-modularity  Fail on oversized touched handwritten source files"
+	@echo "  make validate-harness    Run validate-context and validate-code-modularity"
+	@echo "  make test-all            Run the project regression suite after replacing this placeholder"
+
+ty-context-doctor:
+	$(TY_CONTEXT) doctor
+
+ty-context-sync:
+	$(TY_CONTEXT) sync
+
+ty-context-upgrade:
+	$(TY_CONTEXT) upgrade
+
+ty-context-check-modularity:
+	$(TY_CONTEXT) check-modularity $(TY_CONTEXT_MODULARITY_SCOPE)
+
+validate-context:
+	$(TY_CONTEXT) validate-context
+
+validate-code-modularity:
+	$(TY_CONTEXT) check-modularity $(TY_CONTEXT_MODULARITY_SCOPE) --fail-on-warning
+
+validate-harness: validate-context validate-code-modularity
+
+lint:
+	@echo "No project lint command configured yet. Replace this target with your stack-specific lint command."
+
+test-current-domain:
+	@echo "No domain test command configured yet. Replace this target with focused tests for the current change."
+
+test-all:
+	@echo "No full test command configured yet. Replace this target with the project regression suite."
+
+build:
+	@echo "No build command configured yet. Replace this target with the project build/package command."

package/assets/skills/context_development_engineer/SKILL.md

@@ -7,9 +7,9 @@ description: Use when the user explicitly asks for 开发工程师, 软件工程
 
 ## Package-Managed Boundary
 
-This Skill is generated by `sdlc-harness sync` and owned by the Harness package. Do not edit the generated `context_development_engineer` Skill directly.
+This Skill is generated by `ty-context sync` and owned by the Harness package. Do not edit the generated `context_development_engineer` Skill directly.
 
-Project-specific engineering rules belong in a separate project-local Skill under `<harnessRoot>/skills/development_engineer/SKILL.md`. When a project-local Skill and this package-managed Skill both apply, use the more specific project-local Skill as the primary instruction source while keeping durable conclusions in `project_context/**`. Keep the project-local Skill front matter `description` trigger keywords aligned with this package-managed Skill and the project `AGENTS.md` role-trigger rule; if the project adds or narrows trigger terms, update both places together so agent activation and SDLC guidance do not drift apart.
+Project-specific engineering rules belong in a separate project-local Skill under `<harnessRoot>/skills/development_engineer/SKILL.md`. When a project-local Skill and this package-managed Skill both apply, use the more specific project-local Skill as the primary instruction source while keeping durable conclusions in `project_context/**`. Keep the project-local Skill front matter `description` trigger keywords aligned with this package-managed Skill and the project `AGENTS.md` role-trigger rule; if the project adds or narrows trigger terms, update both places together so agent activation and Tiny Context guidance do not drift apart.
 
 ## 目标
 
@@ -29,13 +29,15 @@ Project-specific engineering rules belong in a separate project-local Skill unde
    - Gap
    - Proposed change
 8. 涉及模块原则、模块逻辑、设计原因、API / Schema、状态语义、验证设计或 capability / metric / acceptance claim 时，先做 Module Principle / Design Gate：列出命中的模块设计上下文来源，说明这些原则 / 逻辑控制本次哪些实现或验证选择，再选择实现路径、验证 claim、probe 参数或 fallback。命令、probe 和当前实现形态是执行实例，不能反推或覆盖模块设计目标。
-9. 涉及 UI surface、表单/配置、输入、选择、搜索、筛选、调度/时间、预算/配额/限流或状态反馈的实现方案时，检查当前代码是否只是暴露字段，还是满足了已有 Context、页面职责和控件任务框架；实现收尾要能给出简短 Context Conformance 证据。
+9. 涉及 Product Surface（Web 页面、移动/桌面屏幕、游戏 UI/HUD/菜单、CLI/TUI 输出、扩展或设备界面）、表单/配置、输入、选择、搜索、筛选、调度/时间、预算/配额/限流或状态反馈的实现方案时，检查当前代码是否只是暴露字段，还是满足了已有 Context、Surface Contract、页面职责和控件任务框架；实现收尾要能给出简短 Surface/Context Conformance 证据。
+   - 若存在 Product Surface Contract，Task Contract 必须包含 Surface Contract Hit、main allows/forbids、drilldown ownership、long-task state requirement、implementation drift 和 verification。
+   - 若缺失且本任务创建 durable surface responsibility，设置 `Context Delta: required`，先用 `context_surface_contract` 或项目 Context 写入具体 surface 职责，再继续实现。
 10. 实现时保持精准修改，优先遵循仓库现有框架、接口、测试和代码风格。
 11. 当用户明确要求 / 允许“多开agent”或使用 subagent，且当前会话存在可用 subagent 工具时，积极把可并行的探索、审查或实现拆分交给 subagent；使用前先复用已有相关 agent，没有合适 agent 或并行度不足时再新开。`wait_agent` 只表示取得结果，不释放资源；subagent 完成、空闲或不再需要时必须调用 `close_agent`，收尾前清理已完成 / 空闲 / 不再需要的 subagent，避免占满后续资源。
 12. 当任务涉及新实现、重构、重复逻辑、模块边界或影响面控制时，先做轻量 abstraction / decomposition scan：
-   - 工程 / RFC / 实现类 Task Contract 包含 `Modularity Check: none|required|exception`；可用 `sdlc-harness check-modularity --file <path> --limit 300` 审计计划编辑文件，用 `sdlc-harness check-modularity --touched --limit 300` 做交付前审计。若项目本地 Skill 定义了不同 limit，使用项目本地值。
+   - 工程 / RFC / 实现类 Task Contract 包含 `Modularity Check: none|required|exception`；可用 `ty-context check-modularity --file <path> --limit 300` 审计计划编辑文件，用 `make validate-code-modularity` 或 `ty-context check-modularity --touched --limit 300 --fail-on-warning` 做交付前硬审计。若项目本地 Skill 定义了不同 limit，使用项目本地值。
    - 发现超限 touched file 后，不只记录行数；判断本次是否在该文件加入新职责，并回到本节拆分原则选择产品面、hook、model、adapter、component、service / facade 或 verification helper 等边界。避免只按行数机械拆分、但耦合和职责仍留在原处。
-   - 如果本次不拆，`Modularity Check` 取 `exception`，交付说明写 `Modularity: exception documented` 并列出文件、暂不拆原因和后续拆分边界。
+   - 如果本次不拆，`Modularity Check` 取 `exception`，必须有 `<harnessRoot>/config.yaml` 的 `modularity.waivers` 记录（`path`、收窄 `category`、`reason`、`future_split_boundary`）；交付说明只能补充说明，不是机器豁免。若项目设置 `modularity.policy: strict_except_generated`，legacy waiver 不可用，超限手写源码必须拆分或停止触碰。已豁免历史债也不得继续塞新职责，除非本次任务就是拆分 / 迁移。
    - 查找相似实现、重复逻辑、紧耦合模块或影响面异常扩散点。
    - 当一个业务对象、能力或接口的变更需要跨多个 Context、产品域或实现层同步调整时，将该影响范围视为模块边界复核信号；优先评估是否应通过独立模块、服务、facade 或稳定接口收敛依赖，避免通过手工 manifest 长期复制实现暴露面。
    - 将候选项分为局部重构与长期边界变化，后者按既有 Context-first 规则处理。
@@ -66,10 +68,11 @@ Project-specific engineering rules belong in a separate project-local Skill unde
   - `none`：本次只是按既有 Context / 架构原则落地，不新增长期事实。
   - `required`：说明长期事实类型、应写入的 Context / role、需要沉淀的事实，以及明确不写入 Context 的一次性内容。
 - `Task Contract` 用短列表说明 capability、owner、upstream / downstream、allowed / forbidden dependency、input / output / state / persistence、failure / retry / timeout / degraded / recovery、observability、performance、security、non-goals 和 verification path。
+- 触及 Product Surface 时，`Task Contract` 同时说明 surface platform、primary user question、main allows/forbids、drilldown ownership、long-task state requirement、implementation drift 和 conformance verification。
 - 工程 / RFC / 实现类任务的 `Task Contract` 必须包含 `Modularity Check: none|required|exception`：
   - `none`：没有超限计划 / touched 手写源码文件，或本次没有向超限文件增加新职责。
   - `required`：拆分是本次验收条件，应按 abstraction / decomposition scan 的职责边界完成。
-  - `exception`：本次触碰超限文件但暂不拆；交付说明必须记录文件、原因和后续拆分边界。
+  - `exception`：本次触碰超限文件但暂不拆；只有默认 `modularity.policy: scoped_waivers` 允许此路径，且必须已有或同步新增 `<harnessRoot>/config.yaml` `modularity.waivers` 记录文件、收窄分类、原因和后续拆分边界。若项目设置 `modularity.policy: strict_except_generated`，不得用 legacy waiver 绕过超限手写源码，交付说明只记录本次是否新增职责以及为什么没有拆。
 - `Applicable Module Design` 是高风险任务的前置字段：列出命中的 Context / Skill 来源、适用的 Principles、Design Logic 和 Design Rationale，以及它们控制的当前实现或验证选择。
 - `Principle Decision Gate` 要写明首选执行路径、fallback / degraded path 的进入条件，以及什么证据不能证明本次目标。涉及 capability、metric 或 acceptance claim 时，先声明要证明的 claim，再选择命令或 probe。
 - 对长任务、多模块、多 agent、容易发生 `Context Delta` 调头或多轮验证的任务，可以用 `plan.md` 或等价临时计划面暂存 `Context Delta`、`Task Contract`、`Implementation Steps` 和 `Contract Conformance`；它只是临时执行缓存。

package/assets/skills/context_full_project_export/SKILL.md

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

package/assets/skills/context_harness_upgrade/SKILL.md

@@ -1,13 +1,13 @@
 ---
 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 sdlc-harness upgrade, run make sdlc-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.
+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 `sdlc-harness sync` and owned by the Harness package. Do not edit the generated `context_harness_upgrade` Skill directly.
+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.
 
@@ -24,20 +24,20 @@ When the user asks to upgrade Tiny Context / Project Tiny Context Harness in an
    - `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 sdlc-upgrade`
-   - `make sdlc-doctor`
+   - `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 sdlc-harness upgrade --check`
-   - `npx --yes --package project-tiny-context-harness@latest sdlc-harness upgrade`
-   - `npx --yes --package project-tiny-context-harness@latest sdlc-harness doctor`
+   - `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. Do not run standalone `sync` before `upgrade`. `upgrade` is the default path after an npm package update because it plans migrations, applies safe migrations, refreshes managed assets and runs diagnostics.
 6. Do not run standalone `sync` after a successful `upgrade` unless release notes say the update is `sync-only`, the project wrapper did not run sync, or the user explicitly asks for a managed-asset refresh.
 7. If `upgrade --check` or `upgrade` reports only `safe_pending` items and the command succeeds, do not invent additional manual cleanup.
 8. 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.
 9. 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.
 10. Run diagnostics after migration-scoped follow-up:
-   - `make sdlc-doctor` or the CLI `doctor`
+   - `make ty-context-doctor` or the CLI `doctor`
    - `make validate-context`
 11. 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.
 
@@ -45,7 +45,7 @@ When the user asks to upgrade Tiny Context / Project Tiny Context Harness in an
 
 - `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 `pjsdlc_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.
+- 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.
 

package/assets/skills/context_product_plan/SKILL.md

@@ -7,9 +7,9 @@ description: Use when the user explicitly asks for 产品方案, 产品经理,
 
 ## Package-Managed Boundary
 
-This Skill is generated by `sdlc-harness sync` and owned by the Harness package. Do not edit the generated `context_product_plan` Skill directly.
+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 SDLC guidance do not drift apart.
+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.
 
 ## 目标
 
@@ -19,7 +19,9 @@ Project-specific product planning rules belong in a separate project-local Skill
 
 1. 先读取 `project_context/global.md` 和 `project_context/context.toml`，按 default area、triggers、read_when 选择相关 context。
 2. 和用户澄清或整理：目标用户、产品/页面定位、核心问题、用户需要什么、产品需要提供的内容/能力/反馈、主要流程、验收信号、非目标、约束、风险和受影响模块。
-3. 涉及 Web 页面、前端布局、UI/UX、产品模块边界或信息放置时，把页面产品定位检查作为前置动作：用户在页面要完成的判断、产品必须提供的信息/动作/反馈、不应常驻的信息、下游消费层/运维层/详情层/其他页面归属、布局和信息密度是否匹配页面任务。多页面或多模块归属不清时，先读取相关 Context 并搜索页面入口，做全站或相关页面的信息架构 sweep，再收窄到具体实现。该检查是下一步变更分类的输入；只有形成长期产品归属、页面职责、信息架构或模块边界结论时才更新 Context。
+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。
+   - 若缺失且本任务改变 durable surface responsibility，输出 `Surface Contract Delta: required`，把具体答案写入 `project_context/**`，跨 surface 或跨 area 使用现有 `contract` role，不新增 surface-specific role。
 4. 涉及输入、选择、搜索、筛选、表单/配置、调度/时间窗口、预算/配额/限流或加载/空态/错误态等 UI 控件时，用“控件任务框架”重新理解用户任务和产品反馈；这只是通用判断框架，不是业务处方库。
 5. 当一个产品对象、能力或接口的增删改需要跨多个页面、模块、Context 或产品域同步调整时，将该影响范围视为产品边界复核信号；先判断它是否应沉淀为独立能力、subdomain 或 area，并明确对外契约、所有权和消费方边界，避免通过手工清单长期维护各消费面的重复映射。
 6. 产品意图、模块职责、边界和验收口径以 `project_context/**` 为准；代码和搜索结果只说明当前实现状态。Context 决定“应该是什么”，代码揭示“现在是什么”，代码不能静默重定义 Context。
@@ -43,7 +45,8 @@ Project-specific product planning rules belong in a separate project-local Skill
 - `Context Delta` 必须先出现，取值为 `none` 或 `required`：
   - `none`：本次只是按既有 Context / 原则落地，不新增长期事实。
   - `required`：说明长期事实类型、应写入的 Context / role、需要沉淀的事实，以及明确不写入 Context 的一次性内容。
-- `Task Contract` 用短列表说明本次产品实现必须满足的目标、用户任务、信息 / 动作 / 状态 / 反馈、边界、非目标和验收信号。
+- `Task Contract` 用短列表说明本次产品实现必须满足的目标、用户任务、信息 / 动作 / 状态 / 反馈、边界、非目标和验收信号。
+- 触及 Product Surface 时，`Task Contract` 同时说明 surface platform、primary user question、main allows/forbids、drilldown ownership、long-task state requirement 和 verification；业务特定答案进入项目 Context 或项目本地 Skill，不写进 package-managed Skill。
 - 对长任务、多模块、多 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 实现。

package/assets/skills/context_surface_contract/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: context_surface_contract
+description: Use when the user asks for Product Surface Contract, Surface Contract, Screen Contract, product surface responsibility, surface responsibility audit, information architecture governance, main/drilldown ownership, UI product boundary, product surface compiler, 产品界面职责治理, 产品接触面, 用户接触面, 页面职责契约, 界面责任契约, 主层/下钻归属, or asks to turn broad UI/product principles into project Context in a Minimal Context Harness project. Do not trigger for ordinary CSS tweaks, one-off UI bug fixes, copy edits, or implementation-only tasks unless the user explicitly asks to define or repair durable product-surface responsibility or information architecture contracts.
+---
+
+# Context Surface Contract
+
+## Package-Managed Boundary
+
+This Skill is generated by `ty-context sync` and owned by the Harness package. Do not edit the generated `context_surface_contract` Skill directly.
+
+Project-specific Product Surface responsibilities belong in `project_context/**` and optional project-local Skills such as `<harnessRoot>/skills/product_plan/SKILL.md`, `<harnessRoot>/skills/uiux_design/SKILL.md`, `<harnessRoot>/skills/development_engineer/SKILL.md` or `<harnessRoot>/skills/surface_contract/SKILL.md`. The package-managed Skill teaches the compiler workflow only; it must not contain business-specific page duties, provider facts, project names, raw payload schemas or product examples.
+
+## Purpose
+
+Help agents turn broad product/UI principles into concrete, project-owned Product Surface Contracts while keeping Minimal Context small.
+
+A Product Surface is any user-facing interface where users make judgments, take actions and receive feedback. Covered platforms include Web apps, dashboards, admin or operations UI, mobile screens, desktop windows, game UI/HUD/menu scenes, CLI/TUI output, browser extension or plugin UI, and embedded, kiosk or device UI.
+
+## Context Roles
+
+Do not add a new `context_role`.
+
+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`.
+
+## Mode Selection
+
+Use the narrowest mode that matches the request:
+
+- Audit Mode: inspect whether existing surfaces have clear responsibility.
+- Compile Mode: turn audit findings or user decisions into Context candidates.
+- Apply Mode: write durable Context only when the user explicitly allows durable writes.
+- Conformance Mode: check implementation against an existing Product Surface Contract.
+
+Do not run implementation, long validation, browser smoke, app smoke or CLI smoke unless the user explicitly asks for execution.
+
+## Audit Mode
+
+Use when the user asks to inspect, review or audit surface responsibility.
+
+Output only:
+
+- Surface list.
+- Surface platform.
+- Code, screenshot, CLI or app evidence inspected.
+- Existing Context expectation.
+- Drift, missing contract or backend complexity exposure.
+- Candidate `Context Delta`.
+- Suggested durable placement.
+- Optional temporary audit path under `tmp/**` when useful.
+
+Do not edit durable Context by default. Code, screenshots and CLI output are evidence of current implementation, not authority for product responsibility.
+
+## Compile Mode
+
+Use when turning audit findings or user decisions into Context candidates.
+
+Output:
+
+- Project-level Product Surface Contract candidate when responsibilities cross surfaces or areas.
+- Area-level Screen Contract candidate when ownership belongs inside one domain.
+- `context.toml` candidate registration with `role = "contract"` when durable registration is needed.
+- `global.md#Context Index` candidate entry when a new Context file is added.
+- Verification candidate for repeatable surface checks.
+- Repo-local Skill task-block candidate when the user wants project-specific enforcement.
+
+Do not assume business responsibilities from current code shape alone. Ask for confirmation if the candidate would silently choose between competing product or information-architecture meanings.
+
+## Apply Mode
+
+Use only when the user explicitly allows durable writes.
+
+Allowed writes:
+
+- `project_context/**`.
+- `project_context/context.toml`.
+- `project_context/global.md#Context Index`.
+- Optional `verification` role Context.
+- Optional separate project-local Skill files when the user explicitly wants project-local enforcement.
+
+Forbidden writes:
+
+- Package-managed generated Skills in a consumer project.
+- `<harnessRoot>/ty-context-managed/**` in a consumer project.
+- Business code unless the user also requested implementation.
+- Generated files.
+- `DESIGN.md`, except visual tokens or visual rationale that do not belong in a Product Surface Contract.
+
+If `Surface Contract Hit` is `none` and the task creates durable surface responsibility, set `Context Delta: required` and update project Context before implementation alignment.
+
+## Conformance Mode
+
+Use after implementation or during review.
+
+Output:
+
+- Surface Contract Conformance.
+- Remaining Drift.
+- Missing Context.
+- Implementation Drift.
+- Verification run / not_run / failed.
+
+Do not store one-off evidence, screenshots, logs, raw outputs or implementation summaries in Context.
+
+## Compiler Questions
+
+For each touched surface, answer only what is relevant:
+
+- What surface is being touched?
+- What platform shape does it have?
+- What primary user question does it answer?
+- What belongs on the main surface?
+- What must move to drilldown, diagnostics, operations, evidence or technical detail?
+- Which long-running or mutating actions require task id, progress, retry, import, recovery or history?
+- Which empty, loading, stale, unavailable, fixture or fallback states matter?
+- What validation path can prove conformance?
+
+## Repo-Local Task Block Candidate
+
+When the user wants project-local enforcement, propose a separate project-local Skill block like this and tailor only the project-specific answers:
+
+```markdown
+## Surface Contract Task Block
+
+For any task touching user-facing surfaces, information placement, forms, filters, search, long-running UI actions, diagnostics, evidence, CLI/TUI output or main/drilldown ownership, answer before implementation:
+
+- Surface Contract Hit: `<context file / none>`
+- Surface: `<route / screen / window / panel / command / HUD / menu>`
+- Surface Platform: `<web | mobile | desktop | game | cli-tui | extension | embedded | mixed>`
+- Owning Product Domain: `<area / subdomain>`
+- Primary User Question: `<one concrete user judgment>`
+- Main Surface Allows: `<durable visible information and actions>`
+- Main Surface Forbids: `<backend fields, raw payloads, diagnostics, debug ids, fake states, etc.>`
+- Drilldown Ownership: `<details / evidence / operations / diagnostics / technical details>`
+- Long Task State Requirement: `<run id, progress, retry, recovery, import, history, or none>`
+- Context Delta: `<none | required>`
+- Verification: `<view-model test / component test / browser smoke / CLI smoke / manual check>`
+```
+
+Do not add this task block to package-managed default Skills as a universal gate. Projects opt in through separate project-local Skills.
+
+## Implementation Alignment
+
+When implementation is also requested, align code with the Product Surface Contract:
+
+- View-models or presenters should expose user-facing states instead of raw backend payloads when that contract exists.
+- Components or commands should render main-surface facts and move technical details to the owning drilldown.
+- Long-running actions should persist or recover the required operation state.
+- Tests should assert user-facing state semantics, not only backend field plumbing.
+- Browser, app, CLI or game smoke checks should validate actual surface behavior when feasible.
+
+Final handoff should include concise `Surface Contract Conformance`: contract source, implementation alignment, remaining drift and verification status.
+
+## 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.

package/assets/skills/context_uiux_design/SKILL.md

@@ -7,9 +7,9 @@ description: Use when the user explicitly asks for 设计稿, 重做设计, UI/U
 
 ## Package-Managed Boundary
 
-This Skill is generated by `sdlc-harness sync` and owned by the Harness package. Do not edit the generated `context_uiux_design` Skill directly.
+This Skill is generated by `ty-context sync` and owned by the Harness package. Do not edit the generated `context_uiux_design` Skill directly.
 
-Project-specific UI/UX and visual design rules belong in a separate project-local Skill under `<harnessRoot>/skills/uiux_design/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/**` and `DESIGN.md`. 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 SDLC guidance do not drift apart.
+Project-specific UI/UX and visual design rules belong in a separate project-local Skill under `<harnessRoot>/skills/uiux_design/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/**` and `DESIGN.md`. 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.
 
 ## 目标
 
@@ -20,7 +20,9 @@ Project-specific UI/UX and visual design rules belong in a separate project-loca
 1. 先读取 `project_context/global.md` 和 `project_context/context.toml`，按 default area、triggers、read_when 选择相关 context。
 2. 如果项目存在 `DESIGN.md`，先读取它；如果用户要求视觉体系、设计稿或界面风格，按 Google `@google/design.md` 的 DESIGN.md 格式创建或更新根目录 `DESIGN.md`。
 3. 整理或生成：用户流程、页面/组件清单、关键状态、交互反馈、响应式边界、a11y 要求、视觉约束和设计 token。
-4. 涉及 Web 页面、前端布局、UI/UX、产品模块边界或信息放置时，把页面产品定位检查作为前置动作：用户在页面要完成的判断、产品必须提供的信息/动作/反馈、不应常驻的信息、下游消费层/运维层/详情层/其他页面归属、布局和信息密度是否匹配页面任务。多页面或多模块归属不清时，先读取相关 Context、搜索页面入口并结合已有 UI 代码/截图做全站或相关页面的信息架构 sweep，再收窄到具体视觉或交互实现。该检查是下一步变更分类的输入；只有形成长期页面职责、信息架构、交互契约或模块边界结论时才更新 Context 或 `DESIGN.md`。
+4. 涉及 Product Surface（Web 页面、移动/桌面屏幕、游戏 UI/HUD/菜单、CLI/TUI 输出、扩展或设备界面）、前端布局、UI/UX、产品模块边界或信息放置时，把产品/页面定位检查作为前置动作：用户在这个 surface 要完成的判断、产品必须提供的信息/动作/反馈、不应常驻的信息、主层/下钻/运维/诊断/详情归属、布局和信息密度是否匹配任务。多 surface、多平台或多模块归属不清时，先读取相关 Context、搜索入口并结合已有 UI 代码/截图做信息架构 sweep，必要时使用 `context_surface_contract` 做 Surface Contract Check，再收窄到具体视觉或交互实现。该检查是下一步变更分类的输入；只有形成长期 surface 职责、信息架构、交互契约或模块边界结论时才更新 Context 或 `DESIGN.md`。
+   - 若存在 Product Surface Contract，读取并对齐 primary user question、main allows/forbids、drilldown ownership、long-task state 和 verification。
+   - 若缺失且本任务改变 durable surface responsibility，输出 `Surface Contract Delta: required`，把界面职责写入 `project_context/**`；视觉 token、颜色、字体、间距、圆角和视觉 rationale 仍写入 `DESIGN.md`。
 5. 涉及输入、选择、搜索、筛选、表单/配置、调度/时间窗口、预算/配额/限流或加载/空态/错误态等 UI 控件时，用“控件交互框架”检查控件语义、反馈状态、校验、错误预防、可供性和信息密度；这只是通用判断框架，不是固定控件处方。
 6. 界面职责、流程归属和长期交互契约以 `project_context/**` 为准；`DESIGN.md` 负责视觉 token 和视觉 rationale；代码、截图和搜索结果只说明当前实现状态。Context 决定“应该是什么”，代码和截图揭示“现在是什么”，代码不能静默重定义 Context。
 7. 设计判断或第一处实现编辑前，若任务涉及页面职责、流程边界、信息架构、交互契约、状态或调度语义、可访问性约束、设计验证关键路径或部署关键路径，先编译当前任务契约；契约第一段用 `Context Delta: none|required` 完成唯一正式长期事实判断，再写本次 `Task Contract`。
@@ -44,7 +46,8 @@ Project-specific UI/UX and visual design rules belong in a separate project-loca
 - `Context Delta` 必须先出现，取值为 `none` 或 `required`：
   - `none`：本次只是按既有 Context / `DESIGN.md` / 设计原则落地，不新增长期事实。
   - `required`：说明长期事实类型、应写入的 Context / role 或 `DESIGN.md` 位置、需要沉淀的事实，以及明确不写入 Context 的一次性内容。
-- `Task Contract` 用短列表说明页面 / 组件任务、用户判断、主信息和辅助信息归属、动作层级、输入语义、loading / empty / no results / stale / error / degraded / success 状态、布局稳定性、非目标和验收入口。
+- `Task Contract` 用短列表说明页面 / 组件任务、用户判断、主信息和辅助信息归属、动作层级、输入语义、loading / empty / no results / stale / error / degraded / success 状态、布局稳定性、非目标和验收入口。
+- 触及 Product Surface 时，`Task Contract` 同时说明 surface platform、primary user question、main allows/forbids、drilldown ownership、long-task state requirement 和 verification；代码字段、枚举、JSON 或截图只是实现证据，不是产品职责来源。
 - 对长任务、多页面/组件、多 agent、容易发生 `Context Delta` 调头或多轮截图 / 手动验证的任务，可以用 `plan.md` 或等价临时计划面暂存 `Context Delta`、`Task Contract`、`Implementation Steps` 和 `Contract Conformance`；它只是临时执行缓存。
 - `plan.md` 中出现的长期界面、交互或视觉事实必须提炼回 `project_context/**` 或 `DESIGN.md`；否则不要把临时计划当作事实源、交付产物或后续引用依据。
 - `Context Delta: required` 时先更新 `project_context/**` 或 `DESIGN.md`，再继续实现；`none` 时直接按 Task Contract 实现。