---
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, or when already-authorized product/UI implementation independently yields `Context Delta: required` in the current Goal.
- 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, or when product/UI implementation is already authorized and the current Goal independently decides that durable Surface/Screen responsibility changed. Skill activation, analysis, audit, candidate comparison or resource generation alone never grants write authority.

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?
- Which authoritative target-user and usage-context reference applies?
- What primary user question does it answer?
- What primary task outcome, primary work object and shortest task loop does it support?
- Which critical context must remain visible while the user acts?
- How are each material operation, affected object and feedback related?
- Does the task force repeated scrolling, navigation or context switching to make one judgment?
- Which client/host, input-method and size-class constraints change the interaction topology?
- 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?
- Across supported size classes, which regions remain, reflow, collapse, become sheets/sidebars/modals or move to another surface, and how is the primary work object preserved?
- 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>`
- Primary Task Outcome / Work Object / Loop: `<outcome; object; orient-act-feedback-finish loop>`
- Critical Context Kept Visible: `<context required while acting>`
- Operation–Object–Feedback: `<material relationship>`
- Client / Size-Class Topology: `<host/input constraints and region changes>`
- 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.