project-tiny-context-harness 0.8.11 → 0.8.13

package/assets/skills/context_surface_contract/SKILL.md

@@ -1,191 +1,194 @@
----
-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.
-
-Use two depths without creating new roles: Product Surface Contract for cross-surface/main-versus-drilldown ownership, and an optional on-demand Screen Contract when one screen needs stable entry/exit/shared-state, information hierarchy, layout regions, navigation, variants or material-control semantics. Start from managed `product-surface-contract.md` or `screen-contract.md`; do not require both for every task.
-
-## 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`.
-
-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`.
-
-Keep one meaning owner: Surface Context owns cross-surface responsibility, Screen/interaction Context owns durable screen/control behavior, `DESIGN.md` owns visual-system semantics and target interpretations, authored targets own concrete declared composition, and verification Context owns repeatable proof paths. Link them with stable surface/control/target keys instead of copying facts.
-
-## 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.
-- Internal source classification when an external product, architecture, technical or acceptance source changes durable surface responsibility; do not create a Markdown coverage table.
-- 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.
-- External-source constraint classification and implementation alignment status.
-- 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?
-- If this came from an external plan/source, which source constraints are covered by existing Context, require new Context, are task-local only, are explicitly out of scope, need user decision or remain under-scoped?
-
-When screen depth is material, also answer only the applicable questions:
-
-- What stable surface/route key, entry context, exit outcome, inherited state and committed state identify the screen?
-- What is the semantic information order and which regions are fixed, scrolling or overlay-owned?
-- Which navigation, back/cancel, focus restoration, interruption and responsive/mode/state variants are durable?
-- For each material stable control key, what are its region/location, type/label, user task, visibility/availability, trigger/input/validation/default, interaction/navigation, loading/empty/success/failure/recovery/permission/feedback and accessibility semantics?
-- Which exact-target/constraint/inspiration IDs govern which declared conditions, and which verification path proves each independent claim?
-
-Before applying material UI facts, perform UI Authority Closure: classify each item as Context-covered, Context update, task-local, out of scope or decision-required. Conflicting controlling owners fail closed; current code, timestamps and Contract YAML do not silently win.
-
-## 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.
-
-Conformance must internally confirm that every important external-source constraint is covered by Context, updated into Context, task-local, explicitly out of scope or awaiting a genuine user decision, and that controlling surface facts reached the correct implementation. Unresolved constraints or non-aligned surface implementation mean the work cannot be described as fully aligned; component, modal, viewmodel or unit evidence alone cannot prove main-surface ownership. Do not create a fixed `plan.md`, Task Contract file or Markdown mapping tables for this check.
-
-## 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 invent rationale; rejected alternatives or tradeoffs belong in Context only when they are stable enough to affect future surface decisions.
-- Do not add a surface-specific validator, edit-order gate, plan-contract validator or package-level mandatory Surface Contract gate.
-- Do not create a `design`/`screen` Context role, per-surface readiness state, UI/UX Contract lifecycle or required Screen Contract for local fixes.
-- Do not include business-domain examples in this package-managed Skill.
+---
+name: context_surface_contract
+description: Use when the user asks for Product Surface Contract, Surface Contract, Screen Contract, durable product-surface responsibility, information/action/feedback ownership, information architecture governance, main/drilldown ownership, UI product boundary, 产品界面职责治理, 产品接触面, 用户接触面, 页面职责契约, 界面责任契约, or 主层/下钻归属 in a Minimal Context Harness project. Do not trigger for ordinary CSS/UI fixes, product-goal planning, visual Design Authority, design-resource generation, or implementation-only work unless durable surface responsibility is explicitly being defined or repaired.
+---
+
+# 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 an optional `<harnessRoot>/skills/surface_contract/SKILL.md`. This is the sole package-managed owner for durable surface responsibility; 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.
+
+This Skill owns where user-facing information, actions and feedback belong, including main/drilldown/diagnostic/detail responsibility and cross-surface ownership. `context_product_plan` owns goals, users, business rules, flows and acceptance meaning; `context_uiux_design` owns Design Authority/tokens/rationale/adopted-target interpretation; `design-resource-authoring` owns resource generation. This Skill owns none of those, performs no implementation acceptance and creates no Gate.
+
+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.
+
+Use two depths without creating new roles: Product Surface Contract for cross-surface/main-versus-drilldown ownership, and an optional on-demand Screen Contract when one screen needs stable entry/exit/shared-state, information hierarchy, layout regions, navigation, variants or material-control semantics. Start from managed `product-surface-contract.md` or `screen-contract.md`; do not require both for every task.
+
+## 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`.
+
+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`.
+
+Keep one meaning owner: Surface Context owns cross-surface responsibility, Screen/interaction Context owns durable screen/control behavior, `DESIGN.md` owns visual-system semantics and target interpretations, authored targets own concrete declared composition, and verification Context owns repeatable proof paths. Link them with stable surface/control/target keys instead of copying facts.
+
+## 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.
+- Internal source classification when an external product, architecture, technical or acceptance source changes durable surface responsibility; do not create a Markdown coverage table.
+- 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.
+- External-source constraint classification and implementation alignment status.
+- 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?
+- If this came from an external plan/source, which source constraints are covered by existing Context, require new Context, are task-local only, are explicitly out of scope, need user decision or remain under-scoped?
+
+When screen depth is material, also answer only the applicable questions:
+
+- What stable surface/route key, entry context, exit outcome, inherited state and committed state identify the screen?
+- What is the semantic information order and which regions are fixed, scrolling or overlay-owned?
+- Which navigation, back/cancel, focus restoration, interruption and responsive/mode/state variants are durable?
+- For each material stable control key, what are its region/location, type/label, user task, visibility/availability, trigger/input/validation/default, interaction/navigation, loading/empty/success/failure/recovery/permission/feedback and accessibility semantics?
+- Which exact-target/constraint/inspiration IDs govern which declared conditions, and which verification path proves each independent claim?
+
+Before applying material UI facts, perform UI Authority Closure: classify each item as Context-covered, Context update, task-local, out of scope or decision-required. Conflicting controlling owners fail closed; current code, timestamps and Contract YAML do not silently win.
+
+## 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.
+
+Conformance must internally confirm that every important external-source constraint is covered by Context, updated into Context, task-local, explicitly out of scope or awaiting a genuine user decision, and that controlling surface facts reached the correct implementation. Unresolved constraints or non-aligned surface implementation mean the work cannot be described as fully aligned; component, modal, viewmodel or unit evidence alone cannot prove main-surface ownership. Do not create a fixed `plan.md`, Task Contract file or Markdown mapping tables for this check.
+
+## 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 invent rationale; rejected alternatives or tradeoffs belong in Context only when they are stable enough to affect future surface decisions.
+- Do not add a surface-specific validator, edit-order gate, plan-contract validator or package-level mandatory Surface Contract gate.
+- Do not create a `design`/`screen` Context role, per-surface readiness state, UI/UX Contract lifecycle or required Screen Contract for local fixes.
+- Do not include business-domain examples in this package-managed Skill.
+- Do not author visual values, `DESIGN.md`, design resources, product acceptance evidence, a verification verdict or a workflow Gate.