project-tiny-context-harness 0.2.53 → 0.2.55

package/assets/README.md

@@ -10,9 +10,9 @@ Translations: [Chinese (Simplified)](README.zh-CN.md)
 
 Project Tiny Context Harness is repo-native project memory for AI coding agents.
 
-`project-tiny-context-harness` ships Project Tiny Context Harness through the `sdlc-harness` CLI. It installs **Minimal Context Harness**: a compact `project_context/**` fact source, a short `AGENTS.md` startup router, role Skills and a `validate-context` gate so fresh agents can recover project intent, boundaries, verification entry points and next safe actions quickly.
+`project-tiny-context-harness` ships Project Tiny Context Harness through the `ty-context` CLI. It installs **Minimal Context Harness**: a compact `project_context/**` fact source, a short `AGENTS.md` startup router, role Skills and a `validate-context` gate so fresh agents can recover project intent, boundaries, verification entry points and next safe actions quickly.
 
-It is not another full SDLC ceremony. The Harness maintains context quality; project tests, reviews, CI and human acceptance still own product quality.
+It is not another full Tiny Context ceremony. The Harness maintains context quality; project tests, reviews, CI and human acceptance still own product quality.
 
 Think of it as durable project memory behind `AGENTS.md`, not another agent, process framework or task manager.
 
@@ -25,7 +25,7 @@ Best for:
 Not for:
 
 - replacing tests, review, CI or issue trackers
-- autonomous SDLC execution
+- autonomous Tiny Context execution
 - codebase semantic indexing or external docs retrieval
 
 Concrete shift:
@@ -55,7 +55,7 @@ Install:
 
 ```sh
 npm install -D project-tiny-context-harness@latest
-npx --yes --package project-tiny-context-harness@latest sdlc-harness init
+npx --yes --package project-tiny-context-harness@latest ty-context init
 ```
 
 No-install preview:
@@ -89,13 +89,13 @@ npm run smoke:quickstart
 npm run preview:pack
 ```
 
-That smoke packs the local workspace, installs it into a disposable repo, runs `sdlc-harness init` and validates the generated Minimal Context files. Use this path for package development, source-preview testing or private review.
+That smoke packs the local workspace, installs it into a disposable repo, runs `ty-context init` and validates the generated Minimal Context files. Use this path for package development, source-preview testing or private review.
 
 ```sh
 npm run preview:pack
 cd /path/to/your/test-repo
-npm install -D /path/to/project-tiny-context-harness/tmp/sdlc/source-preview/package/project-tiny-context-harness-0.2.53.tgz
-npx --no-install sdlc-harness init --adopt
+npm install -D /path/to/project-tiny-context-harness/tmp/ty-context/source-preview/package/project-tiny-context-harness-0.2.55.tgz
+npx --no-install ty-context init --adopt
 make validate-context
 ```
 
@@ -109,14 +109,14 @@ Coding agents can move quickly inside one thread and still drift when a new chat
 
 Most repositories already have README files, specs, tests and issue history, but fresh agents need a small, explicit recovery path: what the project is trying to do, what it must not do, where architecture boundaries live, how to validate changes and what durable facts changed after the last task. Minimal Context Harness makes that recovery path a first-class repo surface without adding a full planning ceremony.
 
-The product lesson is: **keep the memory, drop the ceremony**. Earlier stage-based workflows externalized requirements, design, implementation, review, test and release into explicit phase artifacts. Modern coding agents already internalize much of that ordinary software loop. Project Tiny Context Harness keeps the useful part: the smallest high-density repo context that survives fresh chats without forcing every task through phase transitions, work-product validation or SDLC-stage context splits.
+The product lesson is: **keep the memory, drop the ceremony**. Earlier stage-based workflows externalized requirements, design, implementation, review, test and release into explicit phase artifacts. Modern coding agents already internalize much of that ordinary software loop. Project Tiny Context Harness keeps the useful part: the smallest high-density repo context that survives fresh chats without forcing every task through phase transitions, work-product validation or Tiny Context-stage context splits.
 
 ## Positioning
 
 | Adjacent tool type | Use it for | Harness stance |
 |---|---|---|
 | Spec-first kits | Turning a feature idea into structured specs and implementation plans. | Complementary. Keep final durable project facts in `project_context/**`; do not require spec documents for every task. |
-| BMAD-style workflows and full SDLC processes | Coordinated role/process ceremonies on high-risk work. | Lighter default. Preserve context quality without shipping phase gates or work-product trees. |
+| BMAD-style workflows and full Tiny Context processes | Coordinated role/process ceremonies on high-risk work. | Lighter default. Preserve context quality without shipping phase gates or work-product trees. |
 | Task Master-style planners | Backlog decomposition and task execution state. | Complementary. Harness does not own task state; it owns durable project memory. |
 | Context7/Serena-style retrieval or code-intelligence tools | Pulling external docs, symbols or repository facts on demand. | Complementary. Harness keeps the local project truth that should travel with the repo. |
 | IDE or agent memory | Tool-specific continuity inside one product surface. | Portable fallback. Harness files are plain repo assets that any agent can read. |
@@ -129,7 +129,7 @@ cd project-tiny-context-harness-demo
 git init
 npm init -y
 npm install -D project-tiny-context-harness@latest
-npx --yes --package project-tiny-context-harness@latest sdlc-harness init
+npx --yes --package project-tiny-context-harness@latest ty-context init
 make validate-context
 ```
 
@@ -197,7 +197,7 @@ For common launch and adoption questions, see the [FAQ](docs/faq.md).
 
 This repository is both the source workspace and a reference workspace for `project-tiny-context-harness`. It contains three product areas:
 
-- Harness source code: `packages/sdlc-harness/src/**`, package assets, validators, migrations and source-sync logic.
+- Harness source code: `packages/ty-context/src/**`, package assets, validators, migrations and source-sync logic.
 - npm package release logic: package metadata, build/test scripts and source asset drift checks for `project-tiny-context-harness`.
 - Delivery benchmark logic: `examples/delivery-benchmark/**`, used to compare baseline coding against Harness-assisted delivery under the same quality bar.
 
@@ -207,13 +207,13 @@ Earlier stage-based workflow assets have been removed from the current source tr
 
 ```sh
 npm install -D project-tiny-context-harness@latest
-npx --yes --package project-tiny-context-harness@latest sdlc-harness init
+npx --yes --package project-tiny-context-harness@latest ty-context init
 ```
 
 For an existing project:
 
 ```sh
-npx --yes --package project-tiny-context-harness@latest sdlc-harness init --adopt
+npx --yes --package project-tiny-context-harness@latest ty-context init --adopt
 ```
 
 `init` creates:
@@ -228,17 +228,19 @@ npx --yes --package project-tiny-context-harness@latest sdlc-harness init --adop
 - `<harnessRoot>/skills/context_product_plan/SKILL.md`
 - `<harnessRoot>/skills/context_uiux_design/SKILL.md`
 - `<harnessRoot>/skills/context_development_engineer/SKILL.md`
+- `<harnessRoot>/skills/context_surface_contract/SKILL.md`
 - `<harnessRoot>/skills/context_full_project_export/SKILL.md`
 - `<harnessRoot>/skills/context_harness_upgrade/SKILL.md`
-- `<harnessRoot>/pjsdlc_managed/context_templates/**`
-- `<harnessRoot>/pjsdlc_managed/make/sdlc-harness.mk`
+- `<harnessRoot>/skills/plan_acceptance_checklist_compiler/SKILL.md`
+- `<harnessRoot>/ty-context-managed/context_templates/**`
+- `<harnessRoot>/ty-context-managed/make/ty-context.mk`
 - `tools/**`
 - a root `Makefile` include block
 - `.github/workflows/harness.yml`
 
-The generated workflow runs only the selected Harness gate, `validate-context` or `validate-harness`. Maintainer-only package tests and source-drift checks are intentionally kept out of consumer projects.
+The generated workflow runs only the selected Harness gate: `validate-context`, `validate-code-modularity` or the composite `validate-harness`. Maintainer-only package tests and source-drift checks are intentionally kept out of consumer projects.
 
-`init` does not create lifecycle state, plan state, stage skills or stage work-product trees by default.
+`init` does not create business Product Surface Contract files, lifecycle state, plan state, stage skills or stage work-product trees by default.
 
 ## FAQ
 
@@ -264,65 +266,109 @@ No. It checks that recovery facts exist and avoids fake test-result claims. Prod
 
 It should stay smaller than a full process. Ordinary bug fixes and local refactors do not update Context unless they produce durable product, architecture, API, state or validation facts.
 
-The default Skills are Minimal Context helpers for explicit product-planning, UI/UX-design, development-engineering, full-project-export and Tiny Context upgrade requests. Product, screen-flow and durable engineering conclusions go to `project_context/**`; visual identity and design tokens go to root `DESIGN.md`. Export artifacts are temporary files under `tmp/sdlc/context-exports/**`, not Context. The Harness upgrade Skill handles requests such as “upgrade Tiny Context” and “use the Tiny Context upgrade skill to upgrade this project” by running `upgrade` first, handling only migration-scoped follow-up, and avoiding standalone `sync` before the upgrade path.
+The default Skills are Minimal Context helpers for explicit product-planning, UI/UX-design, development-engineering, Product Surface Contract, full-project-export, Tiny Context upgrade and plan-acceptance-checklist requests. Product, screen-flow, surface responsibility and durable engineering conclusions go to `project_context/**`; visual identity and design tokens go to root `DESIGN.md`. Export artifacts are temporary files under `tmp/ty-context/context-exports/**`, not Context. Plan acceptance artifacts are temporary files under `tmp/ty-context/plan-acceptance/**`; they define completion criteria for a referenced plan but do not execute it or prove acceptance. The Harness upgrade Skill handles requests such as “upgrade Tiny Context” and “use the Tiny Context upgrade skill to upgrade this project” by running `upgrade` first, handling only migration-scoped follow-up, and avoiding standalone `sync` before the upgrade path.
 
 Multilingual trigger phrases are compatibility details. Public README, npm and launch copy stay English-first, and public/package-managed surfaces must remain English-complete; literal non-English examples are documented only where they explain generated Skill matching and must not be the sole activation path.
 
 For product, UI/UX and engineering tasks that touch design intent, API/Schema, state/runtime behavior, architecture boundaries or verification design, the default Skills compile a short current-task contract before implementation. The contract starts with `Context Delta: none|required`; `required` preserves context-first behavior, while `none` means the task can proceed against existing Context. For engineering, RFC and implementation work, the existing Task Contract also includes `Modularity Check: none|required|exception` so oversized touched files trigger split-or-exception reasoning. For module design work, the development engineer Skill also compiles `Applicable Module Design`: the relevant principles, minimal design logic and durable rationale that control the current implementation or verification choice. The task contract and Contract Conformance are handoff evidence, not new PRD, tech-plan, validator or gate surfaces.
 
-`sdlc-harness check-modularity` supports that field by auditing selected handwritten source files for physical line-count risk. It is warning-only by default and is not `validate-context`; teams that want CI enforcement can opt in with `--fail-on-warning`. The command provides file/line facts, while the agent still decides `none`, `required` or `exception` through the development engineer decomposition guidance.
-
-For complex task-contract work, agents may use `plan.md` or an equivalent temporary plan surface as scratch space for `Context Delta`, `Task Contract`, implementation steps and Conformance notes. It is execution cache only: durable facts must be extracted into `project_context/**` or `DESIGN.md`, and temporary plans are not Context, not registered in `context.toml` and not default project assets.
+For long-running plans, RFCs or implementation proposals, the plan acceptance checklist compiler can turn a plan plus relevant Context into a falsifiable acceptance checklist and a paste-ready goal/target-mode prompt. This is one pre-execution acceptance pass, not a task planner: it stores temporary inputs under `tmp/ty-context/plan-acceptance/**`, asks for confirmation when durable assumptions are unclear, and leaves execution evidence to the future executor, tests, CI, review or human acceptance.
+
+For Product Surface work, `context_surface_contract` turns broad product/page/UI principles into project-owned surface responsibilities. A Product Surface can be a Web page, mobile screen, desktop window, game UI/HUD/menu, CLI/TUI output, extension UI or embedded/device interface. Cross-surface contracts use the existing `contract` role; area-owned screen facts stay in `area` or `subdomain`; repeatable validation paths use `verification`. The Harness does not add a new surface-specific role, does not create business surface contracts during `init` or `upgrade`, and does not turn surface conformance into a validator gate. Projects that want mandatory task blocks should add a separate project-local Skill, while `product-surface-contract.md` is only a compact managed template for optional Context authoring.
+
+To create Product Surface Context in a user project, use the Skill through an agent because the package cannot safely infer business-specific screen duties from code alone. For a new project, `init` installs the Skill, template and routing guidance; as the project grows, ask the agent to run Product Surface Audit / Compile when a durable surface appears or when a product/UI/engineering task changes main/drilldown ownership. For an existing project, first run `ty-context upgrade`; then ask the agent to backfill the current surface responsibilities, review the proposed contract, and only then apply it to `project_context/**`:
+
+```text
+Use context_surface_contract in Audit + Compile mode for this repo. Inspect current user-facing routes, screens, panels, CLI/TUI outputs and relevant Context. Propose Product Surface Contract Context using existing roles only. Do not edit product code.
+```
+
+After review, apply the approved contract:
+
+```text
+Apply the approved Product Surface Contract to project_context/**, update project_context/context.toml if a new contract file is needed, keep roles to contract/area/subdomain/verification, and run make validate-context.
+```
+
+`ty-context check-modularity` supports that field by auditing selected handwritten source files for physical line-count risk. It is warning-only by default as a report command, while `validate-code-modularity` and `validate-harness` run it as a hard gate. The gate is not `validate-context`: `validate-context` remains pure Context recoverability. When `policy` is `scoped_waivers`, over-limit exceptions must be backed by `<harnessRoot>/config.yaml` `modularity.waivers` entries with `path`, narrow `category`, `reason` and `future_split_boundary`; handoff prose alone is not a machine waiver.
+
+### Modularity Policy
+
+Newly generated Harness configs default to `strict_except_generated`, which enforces the touched/PR handwritten source limit without legacy waivers:
+
+```yaml
+modularity:
+  limit: 300
+  policy: strict_except_generated
+```
+
+Generated and non-source files are still auto-skipped when they match existing lock/build/dist/path exclusions or generated-file headers such as `@generated` / `Code generated ... DO NOT EDIT`. `strict_except_generated` does not allow `modularity.waivers`; any configured waiver fails the modularity gate.
+
+Use `scoped_waivers` when a small number of legacy exceptions must be explicit and time-bounded:
+
+```yaml
+modularity:
+  limit: 300
+  policy: scoped_waivers
+  waivers:
+    - path: src/legacy/big-file.ts
+      category: legacy_migration
+      reason: "Existing legacy module exceeds the hard source size bound."
+      future_split_boundary: "Extract provider adapters and retry policy."
+```
+
+Omitting `policy` behaves the same as `scoped_waivers` for compatibility with existing projects. Allowed waiver categories are `generated`, `third_party_reference`, `legacy_migration`, `aggregate_styles` and `fixture_snapshot`.
+
+For complex task-contract work, agents may use `plan.md` or an equivalent temporary plan surface as scratch space for `Context Delta`, `Task Contract`, implementation steps and Conformance notes. It is execution cache only: durable facts must be extracted into `project_context/**` or `DESIGN.md`, and temporary plans are not Context, not registered in `context.toml` and not default project assets.
 
-For Web pages, frontend layout, UI/UX, product module boundaries or decisions about where information belongs, agents should run a lightweight page product-positioning check before deciding whether the change is context-first. The check asks what judgment the user needs to make on the page, what information/actions/feedback the product must provide, what should not be persistent, what belongs in downstream consumption, ops, detail or another page, and whether layout and information density match the page task. If ownership is unclear, inspect the relevant pages and Context first. The check is input to change classification: it does not by itself require a Context update, new document chain or validator gate.
+For Product Surface work, frontend layout, UI/UX, product module boundaries or decisions about where information belongs, agents should run a lightweight product/page positioning check before deciding whether the change is context-first. The check asks what judgment the user needs to make on the surface, what information/actions/feedback the product must provide, what should not be persistent, what belongs on the main surface versus drilldown, operations, diagnostics, evidence or detail, and whether layout and information density match the surface task. If ownership is unclear, inspect the relevant surfaces and Context first, and use `context_surface_contract` for a focused audit. The check is input to change classification: it does not by itself require a Context update, new role, new document chain or validator gate.
 
-The expected Context Priority Ladder is: read Context first, run the page product-positioning check when applicable, classify durable-fact impact or use `Context Delta` inside task-contract scenarios, choose context-first or code-first, then perform Contract Conformance when applicable and Context drift check before handoff. This is prompt-level guidance, not an edit-order validator.
+The expected Context Priority Ladder is: read Context first, run the product/page positioning or Surface Contract check when applicable, classify durable-fact impact or use `Context Delta` inside task-contract scenarios, choose context-first or code-first, then perform Contract Conformance when applicable and Context drift check before handoff. This is prompt-level guidance, not an edit-order validator.
 
 Managed `AGENTS.md` guidance is intentionally a startup router, not a full manual. It should contain fact-source entry points, hard boundaries, key triggers and shortest validation commands; package consumers default long design reasoning to Context unless they already have a local spec/design convention. In this source workspace, `PROJECT_SPEC.md` holds stable Harness workflow rationale. Role procedures belong in Skills and human usage guidance in README. The recommended 40-70 line range is a soft budget, not a validator gate.
 
-The default `context_*` Skills are package-managed generated files. `sync` overwrites them, so project-specific product/design/development rules should live in separate project-local Skills such as `.codex/skills/product_plan/SKILL.md`, `.codex/skills/uiux_design/SKILL.md` or `.codex/skills/development_engineer/SKILL.md`. When a project-local Skill and a default Skill both apply, agents should use the more specific project-local Skill first while keeping durable conclusions in `project_context/**` and `DESIGN.md`. Keep the project-local Skill front matter `description` triggers aligned with the matching default `context_*` Skill and the project `AGENTS.md` role-trigger rule; if a project adds or narrows product/design/development keywords, update both the local Skill and the agent guidance together. The Harness upgrade Skill is also package-managed; customize project semantics in Context, not by editing that generated Skill.
+The default `context_*` Skills and package-managed utility Skills are generated files. `sync` overwrites them, so project-specific product/design/development/surface-contract rules should live in separate project-local Skills such as `.codex/skills/product_plan/SKILL.md`, `.codex/skills/uiux_design/SKILL.md`, `.codex/skills/development_engineer/SKILL.md` or `.codex/skills/surface_contract/SKILL.md`. When a project-local Skill and a default Skill both apply, agents should use the more specific project-local Skill first while keeping durable conclusions in `project_context/**` and `DESIGN.md`. Keep the project-local Skill front matter `description` triggers aligned with the matching default `context_*` Skill and the project `AGENTS.md` role-trigger rule; if a project adds or narrows product/design/development/surface keywords, update both the local Skill and the agent guidance together. The Surface Contract, Harness upgrade and plan acceptance checklist Skills are also package-managed; customize project semantics in Context or separate project-local Skills, not by editing those generated Skills.
 
 ## CLI Entry Safety
 
-The canonical npm package is `project-tiny-context-harness`; `sdlc-harness` is the bin name. Prefer package-qualified `npx` commands for ad hoc use because bare `npx sdlc-harness` can resolve an older package name or a stale local install. After `init`, the managed Makefile wrapper uses the canonical latest CLI by default and can be overridden with `SDLC_HARNESS=...` when a project intentionally pins a local package.
+The canonical npm package is `project-tiny-context-harness`; `ty-context` is the bin name. Prefer package-qualified `npx` commands for ad hoc use because bare `npx ty-context` can resolve an older package name or a stale local install. After `init`, the managed Makefile wrapper uses the canonical latest CLI by default and can be overridden with `TY_CONTEXT=...` when a project intentionally pins a local package.
 
-Use `npx --no-install sdlc-harness ...` only when you explicitly want the already installed local package, such as release smoke tests against a packed tarball.
+Use `npx --no-install ty-context ...` only when you explicitly want the already installed local package, such as release smoke tests against a packed tarball.
 
 ## Core Commands
 
 | Command | Purpose |
 |---|---|
-| `npx --yes --package project-tiny-context-harness@latest sdlc-harness init` | Non-destructively installs Minimal Context Harness into the current project. |
-| `make sdlc-sync` or `npx --yes --package project-tiny-context-harness@latest sdlc-harness sync` | Refreshes managed guidance, default Skills, Makefile include, tools and templates. It does not run migrations or generate project semantics; when migration work is pending it refuses to write and tells you to run `upgrade`. |
-| `make sdlc-upgrade` or `npx --yes --package project-tiny-context-harness@latest sdlc-harness upgrade` | Default command after updating the npm package. Builds an upgrade plan, stops before writes when `blocked` items exist, otherwise applies `safe_pending` migrations, runs `sync` and `doctor`, and exits non-zero when manual follow-up or diagnostics remain. |
-| `npx --yes --package project-tiny-context-harness@latest sdlc-harness upgrade --check [--json]` | Checks the upgrade plan without writing files. Reports `safe_pending`, `manual_required` and `blocked`; exits non-zero when any work remains. |
-| `npx --yes --package project-tiny-context-harness@latest sdlc-harness export-context --all [--check]` | Creates both default temporary exports under `tmp/sdlc/context-exports/**`. |
-| `npx --yes --package project-tiny-context-harness@latest sdlc-harness export-context --full [--output tmp/sdlc/context-exports/name.md] [--check]` | Creates a temporary project Context summary Markdown artifact. |
-| `npx --yes --package project-tiny-context-harness@latest sdlc-harness export-context --code [--output tmp/sdlc/context-exports/name.md] [--check]` | Creates a temporary single-file code implementation Markdown artifact. |
-| `npx --yes --package project-tiny-context-harness@latest sdlc-harness check-modularity --touched [--limit 300] [--fail-on-warning]` | Warns when selected handwritten source files exceed a physical line-count limit; `--file <path>` and `--base <ref>` select explicit files or branch changes. |
-| `npx --yes --package project-tiny-context-harness@latest sdlc-harness validate-context` | Checks minimum project recovery fields, Context graph metadata, declared paths/roles and fake test-execution claims. |
-| `make validate-context` | Makefile wrapper for `validate-context`. |
-| `make validate-harness` | Compatibility alias for `validate-context` in vNext projects. |
-| `sdlc-harness package sync-source` | Maintainer-only command to sync source workspace assets into `packages/sdlc-harness/assets/**`. |
-| `sdlc-harness package check-source` | Maintainer-only drift check for package canonical assets. |
+| `npx --yes --package project-tiny-context-harness@latest ty-context init` | Non-destructively installs Minimal Context Harness into the current project. |
+| `make ty-context-sync` or `npx --yes --package project-tiny-context-harness@latest ty-context sync` | Refreshes managed guidance, default Skills, Makefile include, tools and templates. It does not run migrations or generate project semantics; when migration work is pending it refuses to write and tells you to run `upgrade`. |
+| `make ty-context-upgrade` or `npx --yes --package project-tiny-context-harness@latest ty-context upgrade` | Default command after updating the npm package. Builds an upgrade plan, stops before writes when `blocked` items exist, otherwise applies `safe_pending` migrations, runs `sync` and `doctor`, and exits non-zero when manual follow-up or diagnostics remain. |
+| `npx --yes --package project-tiny-context-harness@latest ty-context upgrade --check [--json]` | Checks the upgrade plan without writing files. Reports `safe_pending`, `manual_required` and `blocked`; exits non-zero when any work remains. |
+| `npx --yes --package project-tiny-context-harness@latest ty-context export-context --all [--check]` | Creates both default temporary exports under `tmp/ty-context/context-exports/**`. |
+| `npx --yes --package project-tiny-context-harness@latest ty-context export-context --full [--output tmp/ty-context/context-exports/name.md] [--check]` | Creates a temporary project Context summary Markdown artifact. |
+| `npx --yes --package project-tiny-context-harness@latest ty-context export-context --code [--output tmp/ty-context/context-exports/name.md] [--check]` | Creates a temporary single-file code implementation Markdown artifact. |
+| `npx --yes --package project-tiny-context-harness@latest ty-context check-modularity --touched [--limit 300] [--fail-on-warning]` | Reports selected handwritten source files over the physical line-count limit; `--file <path>` and `--base <ref>` select explicit files or branch changes, and config waivers are reported distinctly. |
+| `npx --yes --package project-tiny-context-harness@latest ty-context validate-context` | Checks minimum project recovery fields, Context graph metadata, declared paths/roles and fake test-execution claims. |
+| `make validate-context` | Makefile wrapper for `validate-context`. |
+| `make validate-code-modularity` | Hard gate for touched handwritten source modularity; CI can set `TY_CONTEXT_MODULARITY_BASE=<ref>` to audit PR/base changes. |
+| `make validate-harness` | Composite gate for `validate-context` and `validate-code-modularity`. |
+| `ty-context package sync-source` | Maintainer-only command to sync source workspace assets into `packages/ty-context/assets/**`. |
+| `ty-context package check-source` | Maintainer-only drift check for package canonical assets. |
 
 ## Updating Existing Projects
 
-After updating the package, run `sdlc-harness upgrade`. Use `sync` only when release notes say the update is `sync-only`; sync does not run migrations.
+After updating the package, run `ty-context upgrade`. Use `sync` only when release notes say the update is `sync-only`; sync does not run migrations.
 
 ```sh
 npm install -D project-tiny-context-harness@latest
-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 ty-context upgrade --check
+npx --yes --package project-tiny-context-harness@latest ty-context upgrade
 ```
 
 Release notes and release readiness use this update mode vocabulary:
 
 | Update mode | What to run | Meaning |
 |---|---|---|
-| `sync-only` | `sdlc-harness sync` | The release changes only package-managed assets. No migrations are required. |
-| `upgrade-required` | `sdlc-harness upgrade` | The release includes safe mechanical migrations and managed asset refresh. |
-| `manual-required` | `sdlc-harness upgrade`, then manual follow-up | The release includes items that cannot be mechanically changed without user intent. |
+| `sync-only` | `ty-context sync` | The release changes only package-managed assets. No migrations are required. |
+| `upgrade-required` | `ty-context upgrade` | The release includes safe mechanical migrations and managed asset refresh. |
+| `manual-required` | `ty-context upgrade`, then manual follow-up | The release includes items that cannot be mechanically changed without user intent. |
 
 `upgrade --check` prints the plan without writing files. The plan groups work as:
 
@@ -341,6 +387,7 @@ Examples:
 - `project_context/areas/main/verification.md` can be registered as a `verification` role by path convention.
 - `project_context/areas/payment/api.md` without a manifest role is reported as `manual_required`; the Harness does not guess whether it is an area, contract, foundation or implementation index.
 - If `project_context/areas/main.md` already exists while `project_context/modules/main.md` still exists, the migration is `blocked`; `upgrade` stops before migrations or `sync`, and no file is overwritten.
+- Projects installed before the rename from `sdlc-harness` may contain `package.json#sdlcHarness`, `sdlc-harness.config.json`, `<harnessRoot>/pjsdlc_managed/**`, `sdlc-harness.mk` or `pjsdlc:sdlc-harness` managed markers. `upgrade --check --json` reports these under `legacy-sdlc-harness-rename`; safe cases copy canonical `tyContext` / `ty-context.config.json` and refresh managed paths, while root conflicts, old override skills, unknown old managed content and target conflicts are `manual_required` or `blocked`.
 
 ## Minimal Context Files
 
@@ -395,10 +442,14 @@ Additional Markdown context files under `project_context/**` can declare `contex
 - `verification`: critical test, smoke, CI, probe or validation repeat-execution paths for an owning area or cross-domain project path.
 - `deployment`: critical deploy, CI/CD, cloud/bootstrap, runtime topology, service initialization, health-check or rollback/degradation repeat-execution paths.
 - `archive`: historical or external source index that should not be read by default.
-- `implementation-index`: code navigation map for owned paths, responsibilities and tests.
-- `decision-rationale`: stable reasons behind durable design choices.
-
-When authoring, migrating or cleaning up `project_context/areas/**`, run a soft role placement scan before registering every Markdown file as an `[[areas]]` entry. Keep `area` / `domain` for product ownership, use `subdomain` only for a smaller owned product context, move interface semantics into `contract`, stable theory or vocabulary into `foundation`, repeatable test/deploy execution paths into `verification` / `deployment`, code maps into `implementation-index`, design reasons into `decision-rationale`, and non-default historical or external material into `archive`. This is prompt-level guidance, not a validator gate.
+- `implementation-index`: code navigation map for owned paths, responsibilities and tests.
+- `decision-rationale`: stable reasons behind durable design choices.
+
+Product Surface Contracts use these existing roles. Use `contract` for cross-surface or cross-area files such as `project_context/areas/product-surface-contracts.md`; use `area` or `subdomain` for owned screen contracts inside one domain; use `verification` for repeatable UI/app/CLI surface checks. Do not add roles such as `surface-contract`, `product-surface`, `web-contract`, `app-contract` or `game-surface`.
+
+`init` gives new projects the Product Surface Contract capability, not a pre-filled business contract. The first durable contract is created when a user or agent explicitly audits/compiles a surface responsibility and writes the approved facts into `project_context/**`. Existing projects receive the same Skill and template after `upgrade`, but `upgrade` intentionally does not inspect current screens or guess their responsibilities; treat Product Surface Context backfill as an explicit follow-up task.
+
+When authoring, migrating or cleaning up `project_context/areas/**`, run a soft role placement scan before registering every Markdown file as an `[[areas]]` entry. Keep `area` / `domain` for product ownership, use `subdomain` only for a smaller owned product context, move interface semantics into `contract`, stable theory or vocabulary into `foundation`, repeatable test/deploy execution paths into `verification` / `deployment`, code maps into `implementation-index`, design reasons into `decision-rationale`, and non-default historical or external material into `archive`. This is prompt-level guidance, not a validator gate.
 
 Automatic migration moves legacy `project_context/modules/**/*.md` files into `project_context/areas/**/*.md`, creates a usable graph baseline and does not infer deep semantic roles. If an existing deep area file is really a foundation, contract, archive or implementation index, a later agent should update `context.toml` explicitly. Boundary rules are metadata only; Harness does not scan source imports or build a runtime dependency graph.
 
@@ -407,31 +458,31 @@ Automatic migration moves legacy `project_context/modules/**/*.md` files into `p
 Use `export-context --all` when you want both one-off project exports for copying into an external tool or discussion:
 
 ```sh
-npx --yes --package project-tiny-context-harness@latest sdlc-harness export-context --all
-npx --yes --package project-tiny-context-harness@latest sdlc-harness export-context --all --check
+npx --yes --package project-tiny-context-harness@latest ty-context export-context --all
+npx --yes --package project-tiny-context-harness@latest ty-context export-context --all --check
 ```
 
-This generates both default artifacts with the same timestamp: `tmp/sdlc/context-exports/full-project-context-<timestamp>.md` and `tmp/sdlc/context-exports/code-level-implementation-<timestamp>/code-level-implementation.md`. `--all` does not accept `--output`; use the single-artifact commands below for custom names.
+This generates both default artifacts with the same timestamp: `tmp/ty-context/context-exports/full-project-context-<timestamp>.md` and `tmp/ty-context/context-exports/code-level-implementation-<timestamp>/code-level-implementation.md`. `--all` does not accept `--output`; use the single-artifact commands below for custom names.
 
 Use `export-context --full` when you need only the project Context bundle:
 
 ```sh
-npx --yes --package project-tiny-context-harness@latest sdlc-harness export-context --full
-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 --full --check
+npx --yes --package project-tiny-context-harness@latest ty-context export-context --full
+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 --full --check
 ```
 
-The default artifact path is `tmp/sdlc/context-exports/full-project-context-<timestamp>.md`. The file title is `# Full Project Context Export`. The file header says `Export artifact. Do not reference from project_context/context.toml.` The export includes Context files, key README / AGENTS / DESIGN documents, managed Skill guidance, Makefile verification-entry summaries, a directory tree summary and Context code-entry indexes.
+The default artifact path is `tmp/ty-context/context-exports/full-project-context-<timestamp>.md`. The file title is `# Full Project Context Export`. The file header says `Export artifact. Do not reference from project_context/context.toml.` The export includes Context files, key README / AGENTS / DESIGN documents, managed Skill guidance, Makefile verification-entry summaries, a directory tree summary and Context code-entry indexes.
 
 Use `export-context --code` when an external model needs the current implementation state in one uploadable Markdown file:
 
 ```sh
-npx --yes --package project-tiny-context-harness@latest sdlc-harness export-context --code
-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 sdlc-harness export-context --code --check
+npx --yes --package project-tiny-context-harness@latest ty-context export-context --code
+npx --yes --package project-tiny-context-harness@latest ty-context export-context --code --output tmp/ty-context/context-exports/my-code-export.md
+npx --yes --package project-tiny-context-harness@latest ty-context export-context --code --check
 ```
 
-The default code artifact path is `tmp/sdlc/context-exports/code-level-implementation-<timestamp>/code-level-implementation.md`. The file title is `# Code-Level Implementation Export`. It scans main source and engineering configuration files, adds each file path, type, line count, character count, SHA256, a heuristic one-sentence summary and a fenced redacted code block. It does not split output into multiple Markdown files.
+The default code artifact path is `tmp/ty-context/context-exports/code-level-implementation-<timestamp>/code-level-implementation.md`. The file title is `# Code-Level Implementation Export`. It scans main source and engineering configuration files, adds each file path, type, line count, character count, SHA256, a heuristic one-sentence summary and a fenced redacted code block. It does not split output into multiple Markdown files.
 
 Both export modes exclude `.env*` except safe examples such as `.env.example`, secret/token/cookie-oriented files, raw captures, licensed payload dumps, `node_modules`, build output, caches, coverage, test reports, logs and existing export artifacts; obvious sensitive assignment values are redacted and reported as warnings.
 
@@ -466,7 +517,7 @@ mkdir -p .codex/skills/uiux_design
 $EDITOR .codex/skills/uiux_design/SKILL.md
 ```
 
-The project-local Skill should mention when it supersedes the package-managed default Skill and should either reuse the default Minimal Context workflow or state the narrower project workflow directly. Its front matter `description` should preserve the same role-trigger intent as `AGENTS.md` and the matching default `context_*` Skill, with any project-specific keyword additions reflected in both places. `sync` does not merge Skill overrides and does not overwrite these separate local Skills. Existing `.codex/pjsdlc_managed/override_skills/*.md` files should be migrated into standalone project-local Skills before running `sync`.
+The project-local Skill should mention when it supersedes the package-managed default Skill and should either reuse the default Minimal Context workflow or state the narrower project workflow directly. Its front matter `description` should preserve the same role-trigger intent as `AGENTS.md` and the matching default `context_*` Skill, with any project-specific keyword additions reflected in both places. `sync` does not merge Skill overrides and does not overwrite these separate local Skills. Existing `.codex/ty-context-managed/override_skills/*.md` files should be migrated into standalone project-local Skills before running `sync`.
 
 `init` creates root `DESIGN.md` beside Context as the design-system fact source, and `upgrade` creates it for existing Harness projects when missing. It starts as a neutral starter baseline with visual tokens, background/color logic, typography, spacing, component states and do/don't guidance; user-authored design rules take precedence once present. Use `npx @google/design.md lint DESIGN.md` to validate its structure when the file is changed.
 
@@ -482,7 +533,7 @@ Impeccable is a default design-review step when a scan target exists, but it is
 
 The former stage-based Harness is no longer shipped as a runnable default, compatibility layer or migration command. Existing users have completed migration, so the package keeps only the current Minimal Context surface.
 
-The design reason is evidence-driven: delivery benchmark pilots showed that full SDLC document chains and frequent workflow gates create real time/token friction on ordinary and medium-complexity tasks, while modern agents already handle much of single-stage product/test work internally. The vNext default keeps the part with the clearest expected return: a minimal durable context for recovery, iteration, debug and requirements changes.
+The design reason is evidence-driven: delivery benchmark pilots showed that full Tiny Context document chains and frequent workflow gates create real time/token friction on ordinary and medium-complexity tasks, while modern agents already handle much of single-stage product/test work internally. The vNext default keeps the part with the clearest expected return: a minimal durable context for recovery, iteration, debug and requirements changes.
 
 ## Delivery Benchmark
 

package/assets/README.zh-CN.md

@@ -4,7 +4,7 @@
 
 Project Tiny Context Harness 是给 AI coding agents 用的轻量项目记忆层。
 
-它不是新的全流程 SDLC 框架，也不是任务管理器。它做一件小事：把新会话 agent 最容易丢掉、但又必须长期稳定保留的项目事实放进仓库里，让下一次聊天、交接、调试或换工具时不用从头重新发现。
+它不是新的全流程 Tiny Context 框架，也不是任务管理器。它做一件小事：把新会话 agent 最容易丢掉、但又必须长期稳定保留的项目事实放进仓库里，让下一次聊天、交接、调试或换工具时不用从头重新发现。
 
 一句话：
 
@@ -34,9 +34,9 @@ Project Tiny Context Harness 把这些内容压缩到几个 repo-native 文件
 
 Fresh agent 先读这些文件，再开始改代码。
 
-## 和传统 SDLC 流程的区别
+## 和传统 Tiny Context 流程的区别
 
-这个项目以前尝试过更重的阶段式 SDLC：阶段状态、任务流转、PRD / 技术方案 / 实现 / 评审 / 测试 / 发布产物和多个 gate。
+这个项目以前尝试过更重的阶段式 Tiny Context：阶段状态、任务流转、PRD / 技术方案 / 实现 / 评审 / 测试 / 发布产物和多个 gate。
 
 后来放弃这个方向，原因很直接：
 
@@ -46,6 +46,8 @@ Fresh agent 先读这些文件，再开始改代码。
 
 所以当前默认方向是 Minimal Context Harness：只维护高密度、长期有效、能帮助恢复上下文的项目事实。
 
+对于长程任务，Harness 也提供一个轻量的计划验收清单 Skill：当用户明确给出或引用某份方案 / 计划 / RFC / implementation plan，并要求生成验收清单、完成定义或 goal/target 模式提示词时，它会把计划和验收清单临时放到 `tmp/ty-context/plan-acceptance/**`。这只是执行前的一次验收标准梳理，不执行计划、不证明完成，也不会把临时清单注册成 `project_context/**`。
+
 ## 适合谁
 
 适合：
@@ -58,7 +60,7 @@ Fresh agent 先读这些文件，再开始改代码。
 不适合：
 
 - 替代测试、CI、review 或人工验收。
-- 自动执行完整 SDLC。
+- 自动执行完整 Tiny Context。
 - 做代码语义索引或外部文档检索。
 - 给每个任务强制生成 PRD、技术方案、测试报告和发布文档。
 
@@ -77,7 +79,7 @@ npm run smoke:quickstart
 
 ```sh
 npm install -D project-tiny-context-harness@latest
-npx --yes --package project-tiny-context-harness@latest sdlc-harness init
+npx --yes --package project-tiny-context-harness@latest ty-context init
 make validate-context
 ```
 
@@ -105,7 +107,7 @@ Read AGENTS.md and project_context/** first. Summarize the project goal, non-goa
 
 ## Benchmark 说明
 
-不要把旧阶段式 SDLC 的 benchmark 数字当成当前 Minimal Context Harness 的性能证明。
+不要把旧阶段式 Tiny Context 的 benchmark 数字当成当前 Minimal Context Harness 的性能证明。
 
 当前公开卖点是产品设计和 smoke 证据：它能安装一个小的项目记忆面，并用 `validate-context` 检查恢复事实是否存在。真正的效率结论需要重新设计 fresh baseline 和 Minimal Context Harness 的对照实验。
 

package/assets/agents/AGENTS_CORE.md

@@ -11,7 +11,7 @@
 ## Context 优先级阶梯
 
 1. 先读 `project_context/global.md`、`project_context/architecture.md` 和 `project_context/context.toml`，再按 graph 读取相关 area / context unit。
-2. 若任务涉及 Web 页面、前端布局、UI/UX、产品模块边界或信息放置，先做页面产品定位检查，再完成变更分类；若 UI 改动涉及输入、选择、搜索、筛选、表单/配置、调度/时间窗口、预算/配额/限流或加载/空态/错误态，按产品/UIUX Skill 的控件任务框架做轻量检查。
+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。
@@ -28,7 +28,7 @@
 ## 工作规则
 
 1. 新会话或继续工作时，先读取 `project_context/global.md`、`project_context/architecture.md` 和 `project_context/context.toml`；按其中 default area 和触发条件读取相关 context。
-2. 第一处代码编辑前先做轻量变更分类，不按固定时长计时。若任务涉及 Web 页面、前端布局、UI/UX、产品模块边界或信息应该放在哪个页面 / 模块，先做页面产品定位检查，再完成变更分类：用户在这个页面要完成什么判断，产品必须提供哪些信息 / 动作 / 反馈，哪些信息不应常驻，哪些属于下游消费层 / 运维层 / 详情层 / 其他页面，当前布局和信息密度是否匹配页面任务。若 UI 改动涉及输入、选择、搜索、筛选、表单/配置、调度/时间窗口、预算/配额/限流或加载/空态/错误态，按产品/UIUX Skill 的控件任务框架做轻量检查，识别既有 Context 是否适用以及是否缺少长期页面/控件契约。多页面或多模块归属不清时，先审查全站或相关页面的信息架构，再收窄到代码模块实现。该检查是判断是否需要 context-first 的输入，不等于必须更新 Context，也不要求独立文档或新的 gate。
+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 对齐实现、验证和收尾。
@@ -38,21 +38,22 @@
 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；默认优先运行 `sdlc-harness export-context --all` 同时生成项目级 Context 汇总和代码级实现快照；只需要单份产物时再用 `--full` 或 `--code`；导出产物只放 `tmp/sdlc/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. 当任务涉及设计稿、重做设计、视觉方案、设计系统、visual polish、frontend redesign 或 frontend styling，且存在可扫描的 UI 代码、页面文件、构建产物目录或本地/远程 URL 时，默认运行 `npx impeccable detect <target>` 做 Impeccable 视觉审查；没有可扫描目标、命令不可用或扫描失败时，说明原因并继续。Impeccable 不是 `validate-context` gate，也不替代截图检查、项目测试或人工判断。
-14. SDLC / Harness managed surfaces 是生成资产：`AGENTS.md` managed block、`.agent/pjsdlc_managed/**`、`.agent/skills/context_product_plan/**`、`.agent/skills/context_uiux_design/**`、`.agent/skills/context_development_engineer/**`、`.agent/skills/context_full_project_export/**` 和 `.agent/skills/context_harness_upgrade/**` 禁止承载项目特定规则；直接编辑会在 `sync` 时被覆盖或产生漂移。项目本地产品 / UIUX / 开发规则必须新建独立 Skill，例如 `.agent/skills/product_plan/SKILL.md`、`.agent/skills/uiux_design/SKILL.md` 或 `.agent/skills/development_engineer/SKILL.md`；当项目本地 Skill 与默认 Skill 同时适用时，优先使用更具体的项目本地 Skill。项目本地 Skill 的 front matter `description` 触发词应与本文件中的角色触发规则和对应默认 `context_*` Skill 保持一致；新增或收窄关键词时，同步更新本地 Skill 描述和项目级 agent 指引，避免 Skill 触发条件与 SDLC 工作规则漂移。
-15. ADR 降级为 Context 中的 `Design Rationale`；实现说明优先写成代码注释、测试名或模块 Context 中的关键约束。
-16. Harness workflow gate 只运行 `validate-context`，用于检查上下文是否可恢复；不检查 context/code 修改顺序。自动化最多提示 context-first 风险，不做阻断。
-17. 产品质量由项目自己的验证入口证明；Context 只能声明验证 / 部署关键路径，不能伪造“测试已通过”或“部署已成功”。
-18. 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。
-19. `sync` 只刷新 managed guidance、默认 Skill 和工具；不会合并 Skill override，也不会覆盖用户新建的独立项目本地 Skill。
-20. 普通项目默认只有一个 `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 类型。
+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 sdlc-sync`：刷新 managed guidance、Context template、默认 Skill 和工具。
-- `npx --yes --package project-tiny-context-harness@latest sdlc-harness export-context --all`：同时导出临时项目级 Context 汇总和代码级实现 Markdown 到 `tmp/sdlc/context-exports/**`。
-- `npx --yes --package project-tiny-context-harness@latest sdlc-harness export-context --full`：导出临时项目级 Context 汇总 Markdown 到 `tmp/sdlc/context-exports/**`。
-- `npx --yes --package project-tiny-context-harness@latest sdlc-harness export-context --code`：导出临时代码级实现 Markdown 到 `tmp/sdlc/context-exports/**`。
-- `npx --yes --package project-tiny-context-harness@latest sdlc-harness doctor`：临时诊断 canonical SDLC CLI；避免裸 `npx sdlc-harness` 解析到旧包名或旧本地缓存。
+- `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/product-surface-contract.md

@@ -0,0 +1,60 @@
+# Product Surface Contract
+
+## Purpose
+
+This Context records durable responsibilities for user-facing Product Surfaces in this project or product domain.
+
+Write only project-specific facts that should guide future implementation. Do not copy generic platform rules, one-off audit notes, screenshots, test logs, implementation summaries, visual tokens or secrets into this file.
+
+## Surfaces
+
+### `<surface name>`
+
+- Surface:
+- Surface Platform:
+- Owning Product Domain:
+- Primary User Question:
+- Surface Type:
+- Main Surface Allows:
+- Main Surface Forbids:
+- Drilldown Ownership:
+- Long Task State Requirement:
+- Empty / Loading / Stale / Unavailable:
+- Security / Redaction:
+- Verification:
+
+## Cross-Surface Rules
+
+- `<durable project-specific rule>`
+
+## Registration Example
+
+Use the existing `contract` role for cross-surface or cross-area contracts:
+
+```toml
+[[context]]
+path = "project_context/areas/product-surface-contracts.md"
+role = "contract"
+triggers = ["surface", "screen", "ui", "ux", "web", "app", "mobile", "desktop", "game", "cli", "tui", "页面", "界面", "屏幕", "产品接触面", "信息架构", "页面职责", "界面职责", "product surface"]
+read_policy = "on-demand"
+```
+
+If using front matter in a Context Markdown file, use `context_role: contract`; do not use `role = "contract"` in Markdown front matter.
+
+## Maintenance Rules
+
+Update this Context when:
+
+- A surface responsibility changes.
+- Main/drilldown ownership changes.
+- A durable long-task state contract is introduced.
+- A repeated UI/product rule becomes reusable.
+- A platform-specific interaction rule becomes stable.
+
+Do not update this Context for:
+
+- CSS-only fixes.
+- One-off screenshot observations.
+- Temporary audit notes.
+- Test logs.
+- Local implementation summaries.