project-tiny-context-harness 0.2.70 → 0.2.71

package/README.md

@@ -65,9 +65,11 @@ Coding agents can move quickly inside one thread and still drift when a new chat
 
 Minimal Context Harness creates a small, explicit recovery path: project goal, boundaries, architecture context, validation entry points and durable task conclusions. It is designed to sit beside specs, tests, issues, docs and code intelligence tools instead of replacing them.
 
-The concrete failure mode is not only missing file search. In an ABCD module chain where A/B/C are upstream of downstream D, a D feature can expose a missing capability. Without Context, an agent may change upstream A/B to make D pass because current code permits it. Minimal Context adds a repo-owned intent layer: it records whether downstream D may change upstream A/B, whether the gap belongs in C's contract, or whether the task needs a `Context Delta` before implementation continues. Code shows what is possible; it cannot decide whether that is allowed project intent.
-
-The core bet is: **keep the memory, drop the ceremony**. Earlier stage-based workflows pushed ordinary software work through explicit phase artifacts and gates. Modern coding agents already internalize much of the understand, design, implement, test and repair loop, so Project Tiny Context Harness keeps the high-density repo context that survives fresh chats without making every task follow Tiny Context-stage choreography.
+The concrete failure mode is not only missing file search. In an ABCD module chain where A/B/C are upstream of downstream D, a D feature can expose a missing capability. Without Context, an agent may change upstream A/B to make D pass because current code permits it. Minimal Context adds a repo-owned intent layer: it records whether downstream D may change upstream A/B, whether the gap belongs in C's contract, or whether the task needs a `Context Delta` before implementation continues. Code shows what is possible; it cannot decide whether that is allowed project intent.
+
+Tiny Context has two core layers. Minimal Context is the durable fact layer: it says what project facts live in `project_context/**` or `DESIGN.md`. The workflow contract is the agent behavior layer: it says to read Context first, let foundation/contract/rationale/architecture Context interpret current-code convenience, decide `Context Delta`, compile a Task Contract, use `plan.md` when complex work needs a visible execution surface, implement against those constraints and finish with Contract Conformance plus Context drift check.
+
+The core bet is: **keep the memory, drop the ceremony**. Earlier stage-based workflows pushed ordinary software work through explicit phase artifacts and gates. Modern coding agents already internalize much of the understand, design, implement, test and repair loop, so Project Tiny Context Harness keeps the high-density repo context that survives fresh chats without making every task follow Tiny Context-stage choreography.
 
 ## Current Best Practice
 
@@ -94,9 +96,13 @@ The ordinary long-task path uses `/normal-long-task`. It is the non-Superpowers
 
 The Superpowers long-task path uses `/superpowers-long-task` when three inputs already exist: `Product / Architecture Source`, `Technical Realization Plan` and `Acceptance Checklist`. The product/architecture source preserves original intent and scope; the technical realization plan is the execution blueprint and plan-conformance source; the checklist is the acceptance authority. Two-document compatibility is allowed only when the first document clearly contains both product/architecture source and technical realization plan sections. If only a product/architecture source and checklist exist, the Skill stops for a missing `Technical Realization Plan` instead of generating one. The prompt is Tiny Context's adapter layer, not a Superpowers official schema. It requires `Product Context Delta` and `Technical Context Delta` checks before implementation, a `plan-conformance-matrix.*` process trace for implementation drift and a final AC-by-AC `final-acceptance-verdict.*` before completion.
 
-The recommended Superpowers layer is the specific [obra/Superpowers](https://github.com/obra/superpowers) plugin/workflow, not a generic planning substitute. Use `superpowers:writing-plans` when the target-mode prompt or source plan still needs bite-sized implementation tasks, then prefer `superpowers:subagent-driven-development` when subagents are available and `superpowers:executing-plans` otherwise. Behavior changes should use `superpowers:test-driven-development`, and completion claims should use `superpowers:verification-before-completion` against both the plan-conformance matrix and final acceptance verdict.
+The recommended Superpowers layer is the specific [obra/Superpowers](https://github.com/obra/superpowers) plugin/workflow, not a generic planning substitute. Use `superpowers:writing-plans` when the target-mode prompt or source plan still needs bite-sized implementation tasks, then prefer `superpowers:subagent-driven-development` when subagents are available and `superpowers:executing-plans` otherwise. Behavior changes should use `superpowers:test-driven-development`, and completion claims should use `superpowers:verification-before-completion` against both the plan-conformance matrix and final acceptance verdict, followed by `ty-context validate-plan-acceptance <dir>`.
 
 The reason is drift control. The workflow contract plus Context layer is intentionally a soft constraint. It works well for short tasks, and Context can still capture the expected facts for long tasks, but long execution makes the Context-to-code step drift as the context window grows, work is handed off, subagents split scope or validation loops multiply. A product/architecture source, technical realization plan, acceptance checklist, explicit long-task Skill invocation, target-mode prompt, plan-conformance matrix, final acceptance verdict and optional Superpowers execution layer make implementation conformance and completion evidence recoverable without restoring a phase-gated workflow.
+
+For high-risk product, architecture, technical-plan or acceptance-plan inputs, the workflow contract should be made visible in `plan.md` or an equivalent temporary plan surface before implementation. That plan surface separates Source-to-Context Coverage from Context-to-Implementation Binding. Source-to-Context maps each durable source constraint to an existing Context hit, a required Context update, a task-local-only decision, an explicit out-of-scope decision, a user decision or an under-scoped gap. Context-to-Implementation then maps Context facts to implementation obligations, expected surfaces, implemented paths, forbidden shortcuts and verification paths. `validate-plan-contract` can check the temporary plan for internal consistency, referenced path existence and declared binding consistency; it still does not prove product quality.
+
+Small code tasks should not use that full plan surface. A small code task is a local implementation task where existing Context is sufficient and the change does not alter durable product, architecture, API/schema/data, runtime/state/recovery, verification/deployment, security/redaction or surface-ownership facts. This is semantic, not line-count based: a one-line schema change can be high risk, while a broad mechanical cleanup can remain small.
 
 ## Positioning
 
@@ -147,7 +153,7 @@ npm ci
 npm run smoke:quickstart
 npm run preview:pack
 cd /path/to/your/test-repo
-npm install -D /path/to/project-tiny-context-harness/tmp/ty-context/source-preview/package/project-tiny-context-harness-0.2.70.tgz
+npm install -D /path/to/project-tiny-context-harness/tmp/ty-context/source-preview/package/project-tiny-context-harness-0.2.71.tgz
 npx --no-install ty-context init --adopt
 make validate-context
 ```
@@ -216,7 +222,7 @@ For existing projects:
 npx --yes --package project-tiny-context-harness@latest ty-context init --adopt
 ```
 
-`init` creates `project_context/context.toml`, `project_context/global.md`, `project_context/architecture.md`, `project_context/areas/main.md`, `project_context/areas/main/verification.md`, agent guidance, Context authoring Skills, a Product Surface Contract Skill, a full-project export Skill, a Harness upgrade Skill, the `/normal-long-task` and `/superpowers-long-task` Skills, managed templates/tools, a Makefile include and `.github/workflows/harness.yml`. 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. It does not create business Product Surface Contract files, stage work-product trees, lifecycle state or stage skills by default.
+`init` creates `project_context/context.toml`, `project_context/global.md`, `project_context/architecture.md`, `project_context/areas/main.md`, `project_context/areas/main/verification.md`, agent guidance, Context authoring Skills, a Product Surface Contract Skill, a full-project export Skill, a Harness upgrade Skill, the `/normal-long-task` and `/superpowers-long-task` Skills, managed templates/tools, a Makefile include and `.github/workflows/harness.yml`. The generated workflow runs only the selected Harness gate: `validate-context`, `validate-code-modularity` or the composite `validate-harness`; `validate-plan-contract` and `validate-plan-acceptance` are explicit commands for complex plan surfaces and long-task artifacts, not default workflow gates. Maintainer-only package tests and source-drift checks are intentionally kept out of consumer projects. It does not create business Product Surface Contract files, stage work-product trees, lifecycle state or stage skills by default.
 
 ## FAQ
 
@@ -274,13 +280,15 @@ Use `npx --no-install ty-context ...` only when you explicitly want the already
 | Project Context export | `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 Context summary artifact. It is not Context and must not be registered in `project_context/context.toml`. |
 | Code implementation export | `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 artifact. It is not Context and must not be registered in `project_context/context.toml`. |
 | Modularity check | `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. |
-| Code modularity validation | `make validate-code-modularity` | Hard gate for touched handwritten source modularity; CI can set `TY_CONTEXT_MODULARITY_BASE=<ref>` to audit PR/base changes. |
-| Harness validation | `make validate-harness` | Composite gate for `validate-context` and `validate-code-modularity`. |
-| Context validation | `npx --yes --package project-tiny-context-harness@latest ty-context validate-context`, `make validate-context` | Checks required project recovery fields, Context graph metadata, declared paths/roles and fake test-execution claims. |
-| Diagnostics | `make ty-context-doctor` or `npx --yes --package project-tiny-context-harness@latest ty-context doctor` | Reports Harness root, package version, schema version and required Minimal Context paths. |
+| Code modularity validation | `make validate-code-modularity` | Hard gate for touched handwritten source modularity; CI can set `TY_CONTEXT_MODULARITY_BASE=<ref>` to audit PR/base changes. |
+| Harness validation | `make validate-harness` | Composite gate for `validate-context` and `validate-code-modularity`. |
+| Context validation | `npx --yes --package project-tiny-context-harness@latest ty-context validate-context`, `make validate-context` | Checks required project recovery fields, Context graph metadata, declared paths/roles and fake test-execution claims. |
+| Plan contract validation | `npx --yes --package project-tiny-context-harness@latest ty-context validate-plan-contract <plan.md\|dir>` | Checks Source-to-Context Coverage and Context-to-Implementation Binding for structural consistency, referenced path existence and weak-proof complete/bound contradictions. |
+| Plan acceptance validation | `npx --yes --package project-tiny-context-harness@latest ty-context validate-plan-acceptance <dir>` | Checks long-task plan-conformance matrix and final verdict JSON for contradictory complete claims, dangling evidence references, weak-proof complete rows, missing plan/AC cross-references and declared surface/architecture binding gaps. |
+| Diagnostics | `make ty-context-doctor` or `npx --yes --package project-tiny-context-harness@latest ty-context doctor` | Reports Harness root, package version, schema version and required Minimal Context paths. |
 | Package source checks | `ty-context package sync-source`, `ty-context package check-source` | Maintainer-only commands for keeping package canonical assets aligned with the source workspace. |
 
-For high-risk product, UI/UX and engineering tasks that affect durable architecture or module ownership, API/Schema/data contracts, state/runtime behavior, dependency direction, verification/deployment semantics or design-rationale tradeoffs, 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. When an input is a product/architecture source or technical implementation plan, the same judgment is refined into `Product Context Delta: none|required` and `Technical Context Delta: none|required`; either `required` means overall `Context Delta: required`. Product Context Delta covers product logic, flows, surface responsibility, information architecture, status meaning, operation boundaries and acceptance semantics. Technical Context Delta covers API/schema/data/event contracts, module ownership, dependency direction, worker/runtime/state semantics, verification/deployment paths and durable technical tradeoffs. It can name `Architecture Context Hit` and `Decision Rationale Hit: existing|required|none` so agents explicitly check the controlling Context and rationale state. When module design principles are relevant, the same contract still uses `Applicable Module Design` for the principles, design logic and rationale controlling the current choice. For engineering, RFC and implementation work, the existing Task Contract still includes `Modularity Check: none|required|exception` so oversized touched files trigger split-or-exception reasoning without becoming an architecture gate. Ordinary bug fixes, local styling, small refactors, package/release chores, test repairs and spikes are not forced into architecture/rationale ceremony unless they produce durable facts. The task contract and Contract Conformance are handoff evidence, not new PRD, tech-plan, ADR, implementation-document, validator or gate surfaces.
+For high-risk product, UI/UX and engineering tasks that affect durable architecture or module ownership, API/Schema/data contracts, state/runtime behavior, dependency direction, verification/deployment semantics or design-rationale tradeoffs, 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. When an input is a product/architecture source or technical implementation plan, the same judgment is refined into `Product Context Delta: none|required` and `Technical Context Delta: none|required`; either `required` means overall `Context Delta: required`. Product Context Delta covers product logic, flows, surface responsibility, information architecture, status meaning, operation boundaries and acceptance semantics. Technical Context Delta covers API/schema/data/event contracts, module ownership, dependency direction, worker/runtime/state semantics, verification/deployment paths and durable technical tradeoffs. For external product/architecture/technical/acceptance sources, `plan.md` or an equivalent temporary plan surface should also include Source-to-Context Coverage with `covered`, `new_context_required`, `context_updated`, `task_local_only`, `out_of_scope_explicit`, `needs_user_decision` or `under_scoped` status. For high-risk implementation work, the same plan surface should include Context-to-Implementation Binding with `bound`, `partial`, `missing`, `blocked`, `out_of_scope_explicit`, `needs_user_decision` or `contradicted_by_current_state` status. It can name `Architecture Context Hit` and `Decision Rationale Hit: existing|required|none` so agents explicitly check the controlling Context and rationale state. When module design principles are relevant, the same contract still uses `Applicable Module Design` for the principles, design logic and rationale controlling the current choice. For engineering, RFC and implementation work, the existing Task Contract still includes `Modularity Check: none|required|exception` so oversized touched files trigger split-or-exception reasoning without becoming an architecture gate. Ordinary bug fixes, local styling, small refactors, package/release chores, test repairs and spikes are not forced into architecture/rationale ceremony unless they produce durable facts. The task contract, Source-to-Context Coverage, Context-to-Implementation Binding and Contract Conformance are handoff or temporary execution evidence, not new PRD, tech-plan, ADR or implementation-document surfaces.
 
 Technical architecture support is a Minimal Context capability: use restrained `architecture.md`, area Module Design Capsules and existing `contract` / `decision-rationale` roles when durable architecture or rationale matters. Do not invent rationale; store stable reasons, rejected alternatives or tradeoffs only in the smallest durable Context surface when they will affect future implementation or verification choices.
 
@@ -288,7 +296,7 @@ For long-running plans, RFCs or implementation proposals, invoke `/normal-long-t
 
 When the next step explicitly needs Superpowers, invoke `/superpowers-long-task` on the Product / Architecture Source, Technical Realization Plan and Acceptance Checklist. It emits the `Superpowers input packet` and execution binding so the future executor sees which inputs feed Context Delta assessment, `superpowers:writing-plans`, `superpowers:subagent-driven-development`, `superpowers:executing-plans`, TDD, `superpowers:verification-before-completion`, local audit, `plan-conformance-matrix.*` and `final-acceptance-verdict.*`. This is Tiny Context's adapter layer, not a Superpowers official schema. It cannot replace `/normal-long-task` for ordinary checklist preparation, and it does not derive a technical plan from a product plan; a two-document packet is accepted only when the first document explicitly contains both product/architecture source and technical realization plan sections.
 
-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.
+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 or create business surface contracts during `init` or `upgrade`. Product Surface Context authoring is not a default product-quality validator; plan validators only check declared temporary surface bindings for structural consistency. 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/**`:
 
@@ -335,7 +343,7 @@ Multilingual trigger phrases are compatibility details. Public README, npm and l
 
 The Harness upgrade Skill exists so consumer agents have a short, repeatable upgrade procedure for existing projects. It treats `upgrade` as the default after package updates and for explicit upgrade requests; `sync-only` only allows a direct managed-asset refresh shortcut when that is what the user asked for. Manual handling stays limited to the migration scope reported by the CLI instead of guessing project semantics.
 
-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 complex task-contract work, agents use `plan.md` or an equivalent temporary plan surface as scratch space for Source-to-Context Coverage, Context-to-Implementation Binding, `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. Small code tasks must not create `plan.md`, full trace tables, Source-to-Context Coverage or Context-to-Implementation Binding unless they discover durable Context changes, receive an external source packet or expand into high-risk/multi-surface work. If coverage still contains unresolved `new_context_required`, `needs_user_decision` or `under_scoped` rows, the implementation cannot be described as fully aligned to the source. If binding still contains `partial`, `missing`, `blocked`, `needs_user_decision` or `contradicted_by_current_state` rows, the implementation cannot be described as fully aligned to Context. Use `ty-context validate-plan-contract <plan.md|dir>` when that artifact should be machine-checked for self-consistency and referenced path existence.
 
 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.
 
@@ -547,10 +555,12 @@ make ty-context-check-modularity
 npx --yes --package project-tiny-context-harness@latest ty-context check-modularity --touched
 make ty-context-sync
 make ty-context-upgrade
-npx --yes --package project-tiny-context-harness@latest ty-context upgrade --check
-npx --yes --package project-tiny-context-harness@latest ty-context upgrade --check --json
-npx --yes --package project-tiny-context-harness@latest ty-context validate-context
-npx --yes --package project-tiny-context-harness@latest ty-context doctor
+npx --yes --package project-tiny-context-harness@latest ty-context upgrade --check
+npx --yes --package project-tiny-context-harness@latest ty-context upgrade --check --json
+npx --yes --package project-tiny-context-harness@latest ty-context validate-context
+npx --yes --package project-tiny-context-harness@latest ty-context validate-plan-contract plan.md
+npx --yes --package project-tiny-context-harness@latest ty-context validate-plan-acceptance tmp/ty-context/plan-acceptance/<slug>
+npx --yes --package project-tiny-context-harness@latest ty-context doctor
 make ty-context-doctor
 make validate-context
 make validate-code-modularity

package/assets/README.md

@@ -94,7 +94,7 @@ That smoke packs the local workspace, installs it into a disposable repo, runs `
 ```sh
 npm run preview:pack
 cd /path/to/your/test-repo
-npm install -D /path/to/project-tiny-context-harness/tmp/ty-context/source-preview/package/project-tiny-context-harness-0.2.70.tgz
+npm install -D /path/to/project-tiny-context-harness/tmp/ty-context/source-preview/package/project-tiny-context-harness-0.2.71.tgz
 npx --no-install ty-context init --adopt
 make validate-context
 ```
@@ -107,11 +107,13 @@ Use it when coding agents repeatedly lose project intent across new chats, hando
 
 Coding agents can move quickly inside one thread and still drift when a new chat, model, tool, reviewer or debugging session loses the project-specific facts that were never encoded anywhere stable.
 
-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 concrete failure mode is not only "the agent did not read enough files." In an ABCD module chain where A/B/C are upstream of downstream D, a D feature may reveal a missing capability. Without Context, the agent can satisfy D by changing upstream A/B because the current code makes that path available. What is missing is a repo-owned intent layer that says whether D may change upstream A/B, whether the gap belongs in C's contract, or whether the task must stop for a `Context Delta` before implementation continues. Current code can show what is possible; it cannot decide whether that is allowed project intent.
-
-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.
+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 concrete failure mode is not only "the agent did not read enough files." In an ABCD module chain where A/B/C are upstream of downstream D, a D feature may reveal a missing capability. Without Context, the agent can satisfy D by changing upstream A/B because the current code makes that path available. What is missing is a repo-owned intent layer that says whether D may change upstream A/B, whether the gap belongs in C's contract, or whether the task must stop for a `Context Delta` before implementation continues. Current code can show what is possible; it cannot decide whether that is allowed project intent.
+
+Tiny Context has two core layers. Minimal Context is the durable fact layer: it says what project facts live in `project_context/**` or `DESIGN.md`. The workflow contract is the agent behavior layer: it says to read Context first, let foundation/contract/rationale/architecture Context interpret current-code convenience, decide `Context Delta`, compile a Task Contract, use `plan.md` when complex work needs a visible execution surface, implement against those constraints and finish with Contract Conformance plus Context drift check.
+
+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.
 
 ## Current Best Practice
 
@@ -138,9 +140,13 @@ The ordinary long-task path uses `/normal-long-task`. It is the non-Superpowers
 
 The Superpowers long-task path uses `/superpowers-long-task` when three inputs already exist: `Product / Architecture Source`, `Technical Realization Plan` and `Acceptance Checklist`. The product/architecture source preserves original intent and scope; the technical realization plan is the execution blueprint and plan-conformance source; the checklist is the acceptance authority. Two-document compatibility is allowed only when the first document clearly contains both product/architecture source and technical realization plan sections. If only a product/architecture source and checklist exist, the Skill stops for a missing `Technical Realization Plan` instead of generating one. The prompt is Tiny Context's adapter layer, not a Superpowers official schema. It requires `Product Context Delta` and `Technical Context Delta` checks before implementation, a `plan-conformance-matrix.*` process trace for implementation drift and a final AC-by-AC `final-acceptance-verdict.*` before completion.
 
-The recommended Superpowers layer is the specific [obra/Superpowers](https://github.com/obra/superpowers) plugin/workflow, not a generic planning substitute. Use `superpowers:writing-plans` when the target-mode prompt or source plan still needs bite-sized implementation tasks, then prefer `superpowers:subagent-driven-development` when subagents are available and `superpowers:executing-plans` otherwise. Behavior changes should use `superpowers:test-driven-development`, and completion claims should use `superpowers:verification-before-completion` against both the plan-conformance matrix and final acceptance verdict.
+The recommended Superpowers layer is the specific [obra/Superpowers](https://github.com/obra/superpowers) plugin/workflow, not a generic planning substitute. Use `superpowers:writing-plans` when the target-mode prompt or source plan still needs bite-sized implementation tasks, then prefer `superpowers:subagent-driven-development` when subagents are available and `superpowers:executing-plans` otherwise. Behavior changes should use `superpowers:test-driven-development`, and completion claims should use `superpowers:verification-before-completion` against both the plan-conformance matrix and final acceptance verdict, followed by `ty-context validate-plan-acceptance <dir>`.
 
 The reason is drift control. The workflow contract plus Context layer is intentionally a soft constraint. It works well for short tasks, and Context can still capture the expected facts for long tasks, but long execution makes the Context-to-code step drift as the context window grows, work is handed off, subagents split scope or validation loops multiply. A product/architecture source, technical realization plan, acceptance checklist, explicit long-task Skill invocation, target-mode prompt, plan-conformance matrix, final acceptance verdict and optional Superpowers execution layer make implementation conformance and completion evidence recoverable without restoring a phase-gated workflow.
+
+For high-risk product, architecture, technical-plan or acceptance-plan inputs, the workflow contract should be made visible in `plan.md` or an equivalent temporary plan surface before implementation. That plan surface separates Source-to-Context Coverage from Context-to-Implementation Binding. Source-to-Context maps each durable source constraint to an existing Context hit, a required Context update, a task-local-only decision, an explicit out-of-scope decision, a user decision or an under-scoped gap. Context-to-Implementation then maps Context facts to implementation obligations, expected surfaces, implemented paths, forbidden shortcuts and verification paths. `validate-plan-contract` can check the temporary plan for internal consistency, referenced path existence and declared binding consistency; it still does not prove product quality.
+
+Small code tasks should not use that full plan surface. A small code task is a local implementation task where existing Context is sufficient and the change does not alter durable product, architecture, API/schema/data, runtime/state/recovery, verification/deployment, security/redaction or surface-ownership facts. This is semantic, not line-count based: a one-line schema change can be high risk, while a broad mechanical cleanup can remain small.
 
 ## Positioning
 
@@ -271,7 +277,7 @@ npx --yes --package project-tiny-context-harness@latest ty-context init --adopt
 - a root `Makefile` include block
 - `.github/workflows/harness.yml`
 
-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.
+The generated workflow runs only the selected Harness gate: `validate-context`, `validate-code-modularity` or the composite `validate-harness`. `validate-plan-contract` and `validate-plan-acceptance` are explicit commands for complex plan surfaces and long-task artifacts, not default workflow gates. Maintainer-only package tests and source-drift checks are intentionally kept out of consumer projects.
 
 `init` does not create business Product Surface Contract files, lifecycle state, plan state, stage skills or stage work-product trees by default.
 
@@ -303,7 +309,7 @@ The default Skills are Minimal Context helpers for explicit product-planning, UI
 
 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 high-risk product, UI/UX and engineering tasks that affect durable architecture or module ownership, API/Schema/data contracts, state/runtime behavior, dependency direction, verification/deployment semantics or design-rationale tradeoffs, 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. When an input is a product/architecture source or technical implementation plan, the same judgment is refined into `Product Context Delta: none|required` and `Technical Context Delta: none|required`; either `required` means overall `Context Delta: required`. Product Context Delta covers product logic, flows, surface responsibility, information architecture, status meaning, operation boundaries and acceptance semantics. Technical Context Delta covers API/schema/data/event contracts, module ownership, dependency direction, worker/runtime/state semantics, verification/deployment paths and durable technical tradeoffs. It can name `Architecture Context Hit` and `Decision Rationale Hit: existing|required|none` so agents explicitly check the controlling Context and rationale state. When module design principles are relevant, the same contract still uses `Applicable Module Design` for the principles, design logic and rationale controlling the current choice. For engineering, RFC and implementation work, the existing Task Contract still includes `Modularity Check: none|required|exception` so oversized touched files trigger split-or-exception reasoning without becoming an architecture gate. Ordinary bug fixes, local styling, small refactors, package/release chores, test repairs and spikes are not forced into architecture/rationale ceremony unless they produce durable facts. The task contract and Contract Conformance are handoff evidence, not new PRD, tech-plan, ADR, implementation-document, validator or gate surfaces.
+For high-risk product, UI/UX and engineering tasks that affect durable architecture or module ownership, API/Schema/data contracts, state/runtime behavior, dependency direction, verification/deployment semantics or design-rationale tradeoffs, 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. When an input is a product/architecture source or technical implementation plan, the same judgment is refined into `Product Context Delta: none|required` and `Technical Context Delta: none|required`; either `required` means overall `Context Delta: required`. Product Context Delta covers product logic, flows, surface responsibility, information architecture, status meaning, operation boundaries and acceptance semantics. Technical Context Delta covers API/schema/data/event contracts, module ownership, dependency direction, worker/runtime-state semantics, verification/deployment paths and durable technical tradeoffs. For external product/architecture/technical/acceptance sources, `plan.md` or an equivalent temporary plan surface should also include Source-to-Context Coverage with `covered`, `new_context_required`, `context_updated`, `task_local_only`, `out_of_scope_explicit`, `needs_user_decision` or `under_scoped` status. For high-risk implementation work, the same plan surface should include Context-to-Implementation Binding with `bound`, `partial`, `missing`, `blocked`, `out_of_scope_explicit`, `needs_user_decision` or `contradicted_by_current_state` status. It can name `Architecture Context Hit` and `Decision Rationale Hit: existing|required|none` so agents explicitly check the controlling Context and rationale state. When module design principles are relevant, the same contract still uses `Applicable Module Design` for the principles, design logic and rationale controlling the current choice. For engineering, RFC and implementation work, the existing Task Contract still includes `Modularity Check: none|required|exception` so oversized touched files trigger split-or-exception reasoning without becoming an architecture gate. Ordinary bug fixes, local styling, small refactors, package/release chores, test repairs and spikes are not forced into architecture/rationale ceremony unless they produce durable facts. The task contract, Source-to-Context Coverage, Context-to-Implementation Binding and Contract Conformance are handoff or temporary execution evidence, not new PRD, tech-plan, ADR or implementation-document surfaces.
 
 Technical architecture support is a Minimal Context capability: use restrained `architecture.md`, area Module Design Capsules and existing `contract` / `decision-rationale` roles when durable architecture or rationale matters. Do not invent rationale; store stable reasons, rejected alternatives or tradeoffs only in the smallest durable Context surface when they will affect future implementation or verification choices.
 
@@ -313,7 +319,7 @@ When the next step explicitly needs Superpowers, invoke `/superpowers-long-task`
 
 Important usage note: Minimal Context intentionally keeps Context read order, Context/code priority and drift checks as agent-level soft constraints rather than machine-enforced gates. That tradeoff works well for short tasks, but long tasks with large context windows, multiple handoffs or many verification loops are expected to drift unless product intent, technical implementation target and acceptance target are externalized. Use `/normal-long-task` before long-running execution when ordinary checklist preparation is needed; use `/superpowers-long-task` when the three upstream inputs already exist and Superpowers execution is desired. Treat the plan-conformance matrix as process trace, the final verdict as final AC-by-AC acceptance evidence, and the local audit only as temporary progress/recovery state.
 
-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.
+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 or create business surface contracts during `init` or `upgrade`. Product Surface Context authoring is not a default product-quality validator; plan validators only check declared temporary surface bindings for structural consistency. 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/**`:
 
@@ -356,7 +362,7 @@ modularity:
 
 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 complex task-contract work, agents use `plan.md` or an equivalent temporary plan surface as scratch space for Source-to-Context Coverage, Context-to-Implementation Binding, `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. Small code tasks must not create `plan.md`, full trace tables, Source-to-Context Coverage or Context-to-Implementation Binding unless they discover durable Context changes, receive an external source packet or expand into high-risk/multi-surface work. If coverage still contains unresolved `new_context_required`, `needs_user_decision` or `under_scoped` rows, the implementation cannot be described as fully aligned to the source. If binding still contains `partial`, `missing`, `blocked`, `needs_user_decision` or `contradicted_by_current_state` rows, the implementation cannot be described as fully aligned to Context. Use `ty-context validate-plan-contract <plan.md|dir>` when that artifact should be machine-checked for self-consistency and referenced path existence.
 
 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.
 
@@ -387,8 +393,10 @@ Use `npx --no-install ty-context ...` only when you explicitly want the already
 | `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`. |
+| `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. |
+| `npx --yes --package project-tiny-context-harness@latest ty-context validate-plan-contract <plan.md\|dir>` | Checks Source-to-Context Coverage and Context-to-Implementation Binding for structural consistency, referenced path existence and weak-proof complete/bound contradictions. |
+| `npx --yes --package project-tiny-context-harness@latest ty-context validate-plan-acceptance <dir>` | Checks long-task plan-conformance matrix and final verdict JSON for contradictory complete claims, dangling evidence references, weak-proof complete rows, missing plan/AC cross-references and declared surface/architecture binding gaps. |
+| `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/**`. |

package/assets/README.zh-CN.md

@@ -50,11 +50,13 @@ Fresh agent 先读这些文件，再开始改代码。
 
 一个典型失败场景是 ABCD 模块链：A/B/C 是上游，D 是下游。现在做 D 的需求时发现能力缺口；如果没有 Context 和优先级约束，agent 很容易为了让 D 完成而去改上游 A/B，因为当前代码让这条路可行。但真正需要判断的是：D 是否有权改 A/B？缺口是不是属于 C 的契约？是否必须先声明 `Context Delta`，让项目意图变化被确认后再实现？代码能说明“现在怎么改得动”，不能说明“项目意图是否允许这样改”。Tiny Context 要补的就是这一层 repo 内长期事实和优先级契约。
 
+Tiny Context 有两个核心层。Minimal Context 是长期事实源层：说明哪些项目事实写在 `project_context/**` 或 `DESIGN.md`。流程契约 / Workflow Contract 是 agent 行为层：规定先读 Context，让 foundation / contract / decision-rationale / architecture 等原则和契约类 Context 优先解释当前代码便利路径，再判断 `Context Delta`、编译 Task Contract、必要时用 `plan.md` 承载可见执行面、按契约实现，最后做 Contract Conformance 和 Context drift check。
+
 对于长程任务，Harness 提供两个显式调用的长程任务 Skill。普通长程任务用 `/normal-long-task`：它把方案和验收输入临时放到 `tmp/ty-context/plan-acceptance/**`，生成或复用完整验收清单，并可输出普通目标模式文本。如果外部规划模型参与，推荐仍然只给两份产物：`《开发方案》` 作为执行方向和 plan traceability source，`《验收清单和测试用例》` 作为 Codex target-mode acceptance input packet。第一份应包含可逐项追踪的 plan item、预期落点 surface、full scope 与 sampled/optional 边界；第二份应包含 AC、required evidence、测试命令、真实产品路径 / core path、证据分层、无效证据、状态机、local audit 和 blocker。Source Pack 只是临时上传材料，不是 durable Context。如果方案里已经有明确、具体的“验收清单”，`/normal-long-task` 会直接复用那份清单并单独写入完整验收清单文件；两份输入包走 strict mode，如果两份内容无法完整解析出 required fields，或第二份缺少 required evidence、verification method、fail condition、状态机、无效证据规则等必要字段，Skill 会停止并列出缺失项，不生成完整验收清单或目标模式文本。
 
 Superpowers 长程任务 Skill 用 `/superpowers-long-task`。如果下一步明确要 Superpowers 目标模式文本，推荐在三份输入都存在后调用：`Product / Architecture Source`（产品/架构原始意图源）、`Technical Realization Plan`（具体技术实现方案）和 `Acceptance Checklist`（验收清单）。它不要求先跑 `/normal-long-task`，但也不会把产品方案现场翻译成技术方案；如果只有产品/架构方案和验收清单，Skill 会停止并报告缺少 `Technical Realization Plan`。两份输入兼容只限第一份明确包含产品/架构源和技术实现方案两个章节。它显式输出 `Superpowers 输入包` 和执行绑定，让未来 executor 清楚哪些输入进入 Product Context Delta、Technical Context Delta、`superpowers:writing-plans`、subagent/inline execution、TDD、`superpowers:verification-before-completion`、local audit、`plan-conformance-matrix.*` 和 `final-acceptance-verdict.*`。这个 prompt 是 Tiny Context 的适配层，不是 Superpowers 官方 schema；它不生成技术方案或验收清单、不执行计划、不证明完成，也不会把临时清单、矩阵或 verdict 注册成 `project_context/**`。
 
-重要使用提示：Minimal Context 有意把 Context 读取顺序、Context / 代码优先级和漂移检查保持为 agent 级软约束，而不是机器强制 gate。这个取舍适合短任务，但长任务、大上下文、多次交接或多轮验证时预期会漂移。普通 checklist 准备需要 `/normal-long-task`；已有产品/架构原始意图源、具体技术实现方案和验收清单且需要 Superpowers 时，可直接用 `/superpowers-long-task`。`Product Context Delta` 判断产品逻辑、页面职责、信息架构和验收语义是否需要写入 Context；`Technical Context Delta` 判断 API/schema、模块边界、runtime/state、验证/部署路径和稳定技术取舍是否需要写入 Context。`plan-conformance-matrix.*` 是执行期“对图纸台账”，`final-acceptance-verdict.*` 是最后逐 AC 验收报告，local audit 只是临时进度/恢复状态，不能裁判完成。
+重要使用提示：Minimal Context 有意把 Context 读取顺序、Context / 代码优先级和漂移检查保持为 agent 级软约束，而不是机器强制 edit-order gate。这个取舍适合短任务，但长任务、大上下文、多次交接或多轮验证时预期会漂移。普通 checklist 准备需要 `/normal-long-task`；已有产品/架构原始意图源、具体技术实现方案和验收清单且需要 Superpowers 时，可直接用 `/superpowers-long-task`。`Product Context Delta` 判断产品逻辑、页面职责、信息架构和验收语义是否需要写入 Context；`Technical Context Delta` 判断 API/schema、模块边界、runtime/state、验证/部署路径和稳定技术取舍是否需要写入 Context。`plan-conformance-matrix.*` 是执行期“对图纸台账”，`final-acceptance-verdict.*` 是最后逐 AC 验收报告，local audit 只是临时进度/恢复状态，不能裁判完成。`validate-plan-contract` 和 `validate-plan-acceptance` 只检查临时 artifact 自洽、引用存在、弱证据 complete 行和已声明的 surface/architecture binding 一致性，不证明产品质量。
 
 ## 当前最佳实践
 
@@ -75,10 +77,14 @@ Web GPT 或其他外部规划模型产出长任务源输入
 -> 每个执行片段都回到流程契约 + project_context/**
 ```
 
-这里的 Superpowers 指具体的 [obra/Superpowers](https://github.com/obra/superpowers) 插件/开源工作流，不是泛化的执行规划替代品。如果目标模式文本或原方案还不够可执行，用 `superpowers:writing-plans` 转成 bite-sized implementation plan；有 subagent 支持时优先用 `superpowers:subagent-driven-development`，否则用 `superpowers:executing-plans`；涉及行为变更时用 `superpowers:test-driven-development`；完成声明前用 `superpowers:verification-before-completion` 同时检查 plan-conformance matrix 和 final acceptance verdict。
+这里的 Superpowers 指具体的 [obra/Superpowers](https://github.com/obra/superpowers) 插件/开源工作流，不是泛化的执行规划替代品。如果目标模式文本或原方案还不够可执行，用 `superpowers:writing-plans` 转成 bite-sized implementation plan；有 subagent 支持时优先用 `superpowers:subagent-driven-development`，否则用 `superpowers:executing-plans`；涉及行为变更时用 `superpowers:test-driven-development`；完成声明前用 `superpowers:verification-before-completion` 同时检查 plan-conformance matrix 和 final acceptance verdict，然后运行 `ty-context validate-plan-acceptance <dir>`。
 
 原因是漂移控制。流程契约 + Context 层是软约束，短任务里通常能让 agent 按预期执行；长程任务里，Context 仍然能记录符合预期的事实，但 Context 到代码 的实现步骤会随着上下文窗口变大、多次交接、subagent 拆分和多轮验证而漂移。产品/架构原始意图源、具体技术实现方案、验收清单、显式长程任务 Skill 调用、目标模式文本、plan-conformance matrix、final acceptance verdict 和可选 Superpowers 执行层，把“产品/技术 Context 有没有先对齐”“有没有按图纸实现”和“有没有按验收证据完成”都外化成可恢复、可审计的临时执行标准，同时不恢复阶段式 gate。
 
+对于高风险产品方案、架构方案、技术方案或验收方案输入，流程契约应先在 `plan.md` 或等价临时计划面里可见化，再进入实现。这个计划面把 Source-to-Context Coverage 和 Context-to-Implementation Binding 分开：前者把每条长期 source 约束映射到 existing Context hit、Context action、owning Context 和 coverage status；后者把 Context fact 映射到 implementation obligation、expected surfaces、implemented paths、forbidden shortcuts、verification path 和 binding status。Source coverage 仍有 `under_scoped` 或未处理的 `new_context_required` 时不能声称按方案完整实现；binding 仍有 `partial`、`missing`、`blocked`、`needs_user_decision` 或 `contradicted_by_current_state` 时不能声称按 Context 完整落地。
+
+small code task 不应该套完整 `plan.md` / trace 表。这里的 small 按语义风险判断，不按代码行数判断：现有 Context 已足够，且不改变 durable product、architecture、API/schema/data、runtime/state/recovery、verification/deployment、security/redaction 或 surface ownership 事实，才算 small。一个一行 schema 改动也可能不是 small；大范围机械样式清理反而可能仍是 small。
+
 ## 适合谁
 
 适合：

package/assets/agents/AGENTS_CORE.md

@@ -1,6 +1,8 @@
 # Minimal Context Harness Protocol
 
-本项目使用 Minimal Context Harness。Harness 只维护上下文质量，不替项目证明产品质量。
+本项目使用 Minimal Context Harness。Harness 只维护上下文质量，不替项目证明产品质量。
+
+流程契约 / Workflow Contract 是 Tiny Context 的第二核心：它指 Context Priority Ladder、Context Delta、Task Contract、Source-to-Context Coverage、Context-to-Implementation Binding、临时 `plan.md` / 等价计划面、Contract Conformance 和 Context drift check 这组读取、变更、实现和收尾优先级规则。Minimal Context 定义长期事实源是什么；流程契约定义 agent 如何诚实读取、更新、实现和验收这些事实。
 
 ## AGENTS.md 定位
 
@@ -12,42 +14,45 @@
 
 1. 先读 `project_context/global.md`、`project_context/architecture.md` 和 `project_context/context.toml`，再按 graph 读取相关 area / context unit。
 2. 若任务涉及 Product Surface work（Web UI、移动/桌面屏幕、游戏 UI/HUD/菜单、CLI/TUI 输出、扩展或设备界面）、前端布局、UI/UX、产品模块边界或信息放置，先做产品/页面定位检查；若改变 durable surface responsibility、主层/下钻归属、长任务状态或信息架构，使用 `context_surface_contract` Skill 应用 Surface Contract workflow：`project_context/**` 是 durable surface truth，repo-local Skills 可强制项目 task block，`DESIGN.md` 只放视觉 token/rationale，代码/截图只是实现证据；不新增 surface-specific context role，跨 surface 用现有 `contract` role。
-3. 若任务新增、迁移或整理 Context 文件，先做 role placement scan：area 只代表产品域归属；contract / foundation / subdomain / verification / deployment / implementation-index / decision-rationale 等按读取目的拆成 role Context。
-4. 对影响架构边界、模块 ownership、API / Schema / 数据契约、状态或运行语义、依赖方向、验证 / 部署语义或 durable rationale / tradeoff 的高风险产品、UI/UX、系统设计和工程任务，先把相关 Context 编译进当前任务契约；契约第一段用 `Context Delta: none|required` 作为唯一长期事实判断点，并包含 `Architecture Context Hit`、`Decision Rationale Hit: existing|required|none`；工程 / RFC / 实现类 Task Contract 同时包含 `Modularity Check: none|required|exception`。
-5. `Context Delta: required` 则 context-first；普通 bug fix、局部样式、局部漂移修复、测试修复或 spike 默认 code-first，但一旦产生长期结论必须回写 Context。
-6. 收尾做 Contract Conformance 和 Context drift check，只报告 `Context: 已更新 ...` 或 `Context: 本次无长期事实变化`；不要把一次性证据、任务契约或实现摘要写入 Context。
+3. 若任务新增、迁移或整理 Context 文件，先做 role placement scan：area 只代表产品域归属；contract / foundation / subdomain / verification / deployment / implementation-index / decision-rationale 等按读取目的拆成 role Context。
+4. 对影响架构边界、模块 ownership、API / Schema / 数据契约、状态或运行语义、依赖方向、验证 / 部署语义或 durable rationale / tradeoff 的高风险产品、UI/UX、系统设计和工程任务，先把相关 Context 编译进当前任务契约；契约第一段用 `Context Delta: none|required` 作为唯一长期事实判断点，并包含 `Architecture Context Hit`、`Decision Rationale Hit: existing|required|none`；工程 / RFC / 实现类 Task Contract 同时包含 `Modularity Check: none|required|exception`。
+5. 当输入包含产品方案、技术方案、架构迁移、页面职责、runtime/state/API/schema/verification 变更或验收方案时，先按流程契约在 Task Contract 或临时 `plan.md` / 等价计划面中做 Source-to-Context Coverage：逐项判断输入中的 durable constraints 是否已被 Context 覆盖、需要更新、仅属 task-local、显式 out-of-scope 或需要用户决策；不要在这张表里写实现路径。
+6. `Context Delta: required` 则 context-first；small code task 默认 code-first，但一旦产生长期结论必须回写 Context。small code task 指现有 Context 已足够、且不改变 durable product / architecture / API-schema / runtime-state / verification-deployment / security-redaction / surface ownership 事实的局部实现任务；它按语义风险判断，不按代码行数判断。Context 更新必须足以指导实现，不能只写状态摘要或把方案约束降级成实现备注。
+7. 收尾做 Contract Conformance 和 Context drift check；对照 Task Contract / `plan.md` 区分实现偏差、契约遗漏或长期事实缺失。高风险实现工作还要检查 Context-to-Implementation Binding：Context fact 是否绑定到 expected surfaces、implemented paths、forbidden shortcuts 和 verification path。交付只报告 `Context: 已更新 ...` 或 `Context: 本次无长期事实变化`；不要把一次性证据、任务契约或实现摘要写入 Context。
 
 ## 事实源
 
-- 项目全局上下文：`project_context/global.md`
-- 架构上下文：`project_context/architecture.md`（克制、最小，只记录系统边界、组件关系和长期约束）
-- Context 图谱：`project_context/context.toml`（Schema v4 默认事实源；声明产品域 area/context_unit、role、触发条件和按需读取策略）
-- 产品域 / context unit 上下文：`project_context/areas/**/*.md`
-- 产品质量事实：项目自己的代码、测试、smoke、CI、hidden probe 或人工验收
+- 项目全局上下文：`project_context/global.md`
+- 架构上下文：`project_context/architecture.md`（克制、最小，只记录系统边界、组件关系和长期约束）
+- Context 图谱：`project_context/context.toml`（Schema v4 默认事实源；声明产品域 area/context_unit、role、触发条件和按需读取策略）
+- 产品域 / context unit 上下文：`project_context/areas/**/*.md`
+- 原则、契约和基础概念类 Context（如 `foundation`、`contract`、`decision-rationale`、`architecture`、`verification` / `deployment`）优先解释当前代码便利路径；代码只能证明当前实现，不能静默改写项目意图。
+- 产品质量事实：项目自己的代码、测试、smoke、CI、hidden probe 或人工验收
 
 ## 工作规则
 
 1. 新会话或继续工作时，先读取 `project_context/global.md`、`project_context/architecture.md` 和 `project_context/context.toml`；按其中 default area 和触发条件读取相关 context。
 2. 第一处代码编辑前先做轻量变更分类，不按固定时长计时。若任务涉及 Product Surface work（Web UI、移动/桌面屏幕、游戏 UI/HUD/菜单、CLI/TUI 输出、扩展或设备界面）、前端布局、UI/UX、产品模块边界或信息应该放在哪个 surface / 页面 / 模块，先做产品/页面定位检查，再完成变更分类：用户在这个 surface 要完成什么判断，产品必须提供哪些信息 / 动作 / 反馈，哪些信息不应常驻，哪些属于主层、下钻、运维、诊断、详情或其他页面，当前布局和信息密度是否匹配 surface 任务。若 UI 改动涉及输入、选择、搜索、筛选、表单/配置、调度/时间窗口、预算/配额/限流或加载/空态/错误态，按产品/UIUX Skill 的控件任务框架做轻量检查，识别既有 Context 或 Product Surface Contract 是否适用以及是否缺少长期 surface/控件契约；职责不清或需要治理时使用 `context_surface_contract`。多 surface、多页面或多模块归属不清时，先审查相关信息架构，再收窄到代码模块实现。该检查是判断是否需要 context-first 的输入，不等于必须更新 Context，也不要求独立文档、新角色或新的 gate。
-3. 对产品方案、UI/UX、系统设计、架构边界、模块 ownership、API / Schema / 数据契约、状态机或运行语义、依赖方向、验证 / 部署语义或 durable rationale / tradeoff 等高风险任务，第一处代码编辑前先编译当前任务契约：用 `Context Delta: none|required` 作为唯一正式长期事实判断点，再写本次 Task Contract，并把 `Architecture Context Hit`、`Decision Rationale Hit: existing|required|none`、命中的模块设计上下文、它控制的当前选择、首选路径和 fallback / degraded path 条件写入任务契约；工程 / RFC / 实现类 Task Contract 还应包含 `Modularity Check: none|required|exception`。普通 bug fix、局部样式、小重构、局部漂移修复、package/release 处理、测试修复或 spike 不强制编译任务契约。
+3. 对产品方案、UI/UX、系统设计、架构边界、模块 ownership、API / Schema / 数据契约、状态机或运行语义、依赖方向、验证 / 部署语义或 durable rationale / tradeoff 等高风险任务，第一处代码编辑前先编译当前任务契约：用 `Context Delta: none|required` 作为唯一正式长期事实判断点，再写本次 Task Contract，并把 `Architecture Context Hit`、`Decision Rationale Hit: existing|required|none`、命中的模块设计上下文、它控制的当前选择、首选路径和 fallback / degraded path 条件写入任务契约；工程 / RFC / 实现类 Task Contract 还应包含 `Modularity Check: none|required|exception`。如果任务输入本身是产品/架构/技术/验收方案，Task Contract 或临时 `plan.md` 必须包含 Source-to-Context Coverage，列出 source item、durable constraint、existing Context hit、Context action、owning Context 和 coverage status；高风险实现工作还应包含 Context-to-Implementation Binding，列出 context fact、implementation obligation、expected surfaces、implemented paths、forbidden shortcuts、verification path 和 binding status。small code task 不强制编译任务契约。
 4. 当新增、迁移或整理 `project_context/areas/**` 时，做 role placement scan（软约束，不做 gate）：`area` / `domain` 保留产品域归属，`subdomain` 用于产品域内较小 ownership，`contract` 用于 API / schema / event / 跨域接口语义，`foundation` 用于稳定理论 / 词汇 / 背景材料，`verification` / `deployment` 用于可复用执行路径，`implementation-index` 只做代码导航索引，`decision-rationale` 记录稳定设计原因，`archive` 用于非默认读取的历史或外部材料。
-5. 若任务契约声明 `Context Delta: required`，默认走 context-first：第一处代码编辑前先更新相关 `project_context/**`，写入必要且足以指导实现的长期结论，再按 Context 和 Task Contract 对齐实现、验证和收尾。
-6. 普通 bug fix、局部样式、局部实现漂移修复、测试修复或探索性 spike 不更新 Context，可先改代码；一旦形成长期结论，继续对齐或交付前必须回写 `project_context/**`。
-7. `project_context/**` 是项目意图、产品域职责、架构边界、集成方向、允许/禁止依赖、验证关键路径和部署关键路径的权威事实源；代码是当前实现状态的权威事实源。
-8. 当代码形态、搜索结果或相邻实现与 Context 声明冲突时，把差异视为实现漂移、缺失工作或 Context 过期并显式说明；不要用当前代码形态或关键词搜索结果覆盖 Context 已声明的职责、归属或集成意图。
-9. 每个有意义的方案或实现变更收尾时做 Contract Conformance 和 Context drift check：对照 Task Contract 区分实现偏差、契约遗漏或长期事实缺失；实现偏差修实现，契约遗漏回 Task Contract，长期事实缺失回 `Context Delta` 并先更新 Context。交付说明只报告轻量状态：`Context: 已更新 ...` 或 `Context: 本次无长期事实变化`；Conformance 证据属于本次交付，不写入 `project_context/**`。
-10. 长期事实只写入 `project_context/**`；不要默认创建 PRD、tech plan、ADR、implementation doc、review/test/release 文档。
-11. 用户明确要求“产品方案 / 产品经理 / 产品专家 / product plan / product manager / product spec”、“设计稿 / UI/UX 设计方案 / 视觉专家 / UX designer / UI designer / visual polish / design system spec”或“开发工程师 / 技术方案 / 开发方案 / 实现 / 实现方案 / 实施计划 / 技术专家 / software engineer / development plan / technical implementation plan / 多开agent / subagent”这类角色或强产物名时，使用对应 Context authoring Skill，把长期结论写回 `project_context/**`。
-12. 用户明确要求“导出尽可能详细的项目全量上下文 / 全量上下文导出 / 项目整体上下文 / full project context export / export full project context / project context export / project overall context / 当前项目代码实现 / 代码级实现导出 / code-level implementation export / Source Pack export / source-pack export / task context export / code index export”时，使用 `context_full_project_export` Skill；默认优先运行 `ty-context export-context --source-pack` 生成最多 5 个临时上传文件到 `tmp/ty-context/context-exports/latest/`，且只保留 `latest/` 导出轮次；只需要导航索引用 `--code-index`，聚焦交接用 `--task-context <name>`，需要 legacy 单文件完整代码快照时再用 `--code`，需要 legacy Context+代码双导出时可用 `--all`；导出产物只放 `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. 长程任务不要靠宽泛关键词自动触发临时验收流程；需要普通长程任务包时，建议用户直接调用 `/normal-long-task`；已有 Product / Architecture Source、Technical Realization Plan 和 Acceptance Checklist 且需要 Superpowers 目标模式文本时，建议直接调用 `/superpowers-long-task`。输出只放 `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/normal-long-task/**` 和 `.agent/skills/superpowers-long-task/**` 禁止承载项目特定规则；直接编辑会在 `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 类型。
+5. 若任务契约声明 `Context Delta: required`，默认走 context-first：第一处代码编辑前先更新相关 `project_context/**`，写入必要且足以指导实现的长期结论，再按 Context 和 Task Contract / `plan.md` 对齐实现、验证和收尾。若 Source-to-Context Coverage 仍有 `new_context_required`、`needs_user_decision` 或 `under_scoped`，不得声称按方案完整实现；若 Context-to-Implementation Binding 仍有 `partial`、`missing`、`blocked`、`needs_user_decision` 或 `contradicted_by_current_state`，不得声称按 Context 完整落地。
+6. 普通 bug fix、局部样式、局部实现漂移修复、测试修复或探索性 spike 不更新 Context，可先改代码；一旦形成长期结论，继续对齐或交付前必须回写 `project_context/**`。
+7. small code task 不应创建 `plan.md`、完整 trace tables、Source-to-Context Coverage 或 Context-to-Implementation Binding，除非它发现 durable Context 变化、接收到外部 source packet，或扩展成高风险 / 多 surface 工作。
+8. `project_context/**` 是项目意图、产品域职责、架构边界、集成方向、允许/禁止依赖、验证关键路径和部署关键路径的权威事实源；代码是当前实现状态的权威事实源。
+9. 当代码形态、搜索结果或相邻实现与 Context 声明冲突时，把差异视为实现漂移、缺失工作或 Context 过期并显式说明；不要用当前代码形态或关键词搜索结果覆盖 Context 已声明的职责、归属或集成意图。
+10. 每个有意义的方案或实现变更收尾时做 Contract Conformance 和 Context drift check：对照 Task Contract / `plan.md` 区分实现偏差、契约遗漏或长期事实缺失；实现偏差修实现，契约遗漏回 Task Contract，长期事实缺失回 `Context Delta` 并先更新 Context。若存在 Source-to-Context Coverage，收尾必须确认没有未处理的 `under_scoped` / `new_context_required` 项；若存在 Context-to-Implementation Binding，收尾必须确认没有 non-bound 实现项。交付说明只报告轻量状态：`Context: 已更新 ...` 或 `Context: 本次无长期事实变化`；Conformance 证据属于本次交付，不写入 `project_context/**`。
+11. 长期事实只写入 `project_context/**`；不要默认创建 PRD、tech plan、ADR、implementation doc、review/test/release 文档。
+12. 用户明确要求“产品方案 / 产品经理 / 产品专家 / 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/**`。
+13. 用户明确要求“导出尽可能详细的项目全量上下文 / 全量上下文导出 / 项目整体上下文 / full project context export / export full project context / project context export / project overall context / 当前项目代码实现 / 代码级实现导出 / code-level implementation export / Source Pack export / source-pack export / task context export / code index export”时，使用 `context_full_project_export` Skill；默认优先运行 `ty-context export-context --source-pack` 生成最多 5 个临时上传文件到 `tmp/ty-context/context-exports/latest/`，且只保留 `latest/` 导出轮次；只需要导航索引用 `--code-index`，聚焦交接用 `--task-context <name>`，需要 legacy 单文件完整代码快照时再用 `--code`，需要 legacy Context+代码双导出时可用 `--all`；导出产物只放 `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`。
+14. 长程任务不要靠宽泛关键词自动触发临时验收流程；需要普通长程任务包时，建议用户直接调用 `/normal-long-task`；已有 Product / Architecture Source、Technical Realization Plan 和 Acceptance Checklist 且需要 Superpowers 目标模式文本时，建议直接调用 `/superpowers-long-task`。输出只放 `tmp/ty-context/plan-acceptance/**`，它们只定义验收标准、执行提示词或临时执行证据，不执行计划、不证明完成、不把结果注册到 `project_context/**` / `project_context/context.toml`。
+15. 当任务涉及设计稿、重做设计、视觉方案、设计系统、visual polish、frontend redesign 或 frontend styling，且存在可扫描的 UI 代码、页面文件、构建产物目录或本地/远程 URL 时，默认运行 `npx impeccable detect <target>` 做 Impeccable 视觉审查；没有可扫描目标、命令不可用或扫描失败时，说明原因并继续。Impeccable 不是 `validate-context` gate，也不替代截图检查、项目测试或人工判断。
+16. 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/normal-long-task/**` 和 `.agent/skills/superpowers-long-task/**` 禁止承载项目特定规则；直接编辑会在 `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 工作规则漂移。
+17. ADR 降级为 Context 中的 `Design Rationale`；实现说明优先写成代码注释、测试名或模块 Context 中的关键约束。
+18. Harness workflow gate 只运行 `validate-context`，用于检查上下文是否可恢复；不检查 context/code 修改顺序。`validate-plan-contract` 和 `validate-plan-acceptance` 是复杂 plan surface / 长程任务 artifact 的显式一致性检查，不默认进入 workflow gate。自动化最多提示 context-first 风险，不做阻断。
+19. 产品质量由项目自己的验证入口证明；Context 只能声明验证 / 部署关键路径，不能伪造“测试已通过”或“部署已成功”。
+20. 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。
+21. `sync` 只刷新 managed guidance、默认 Skill 和工具；不会合并 Skill override，也不会覆盖用户新建的独立项目本地 Skill。
+22. 普通项目默认只有一个 `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 类型。
 
 ## 常用命令
 
@@ -58,5 +63,7 @@
 - `npx --yes --package project-tiny-context-harness@latest ty-context export-context --task-context <name>`：导出最多 5 个临时聚焦任务交接文件。
 - `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` 解析到旧包名或旧本地缓存。
+- `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 validate-plan-contract <plan.md|dir>`：检查临时计划面的 Source-to-Context Coverage / Context-to-Implementation Binding 自洽、引用存在和弱证据矛盾；不证明产品质量。
+- `npx --yes --package project-tiny-context-harness@latest ty-context validate-plan-acceptance <dir>`：检查长程任务 matrix/verdict JSON 自洽、引用存在和 complete 声明矛盾；不替代测试、CI 或人工验收。
+- `npx --yes --package project-tiny-context-harness@latest ty-context doctor`：临时诊断 canonical Tiny Context CLI；避免裸 `npx ty-context` 解析到旧包名或旧本地缓存。

package/assets/skills/context_development_engineer/SKILL.md

@@ -20,7 +20,7 @@ Project-specific engineering rules belong in a separate project-local Skill unde
 1. 先读取 `project_context/global.md`、`project_context/architecture.md` 和 `project_context/context.toml`，按 default area、triggers、read_when 选择相关 context。
 2. 先确认用户目标、约束、成功标准、影响产品域、现有验证 / 部署关键路径和风险；能从代码或 Context 发现的事实不要反复询问用户。
 3. `project_context/**` 决定“应该是什么”：模块职责、归属、架构边界、接口方向、契约语义和禁止依赖；代码决定“现在实现到了哪里”。代码不能静默重定义 Context。
-4. 第一处代码编辑前，若任务影响 durable architecture boundary、module ownership、API / Schema / data contract、state / runtime semantics、dependency direction、verification / deployment semantics 或 durable rationale / tradeoff，先编译当前任务契约；契约第一段用 `Context Delta: none|required` 完成唯一正式长期事实判断，再写本次 `Task Contract`，并显式写 `Architecture Context Hit` 和 `Decision Rationale Hit: existing|required|none`。
+4. 第一处代码编辑前，若任务影响 durable architecture boundary、module ownership、API / Schema / data contract、state / runtime semantics、dependency direction、verification / deployment semantics 或 durable rationale / tradeoff，先编译当前任务契约；契约第一段用 `Context Delta: none|required` 完成唯一正式长期事实判断，再写本次 `Task Contract`，并显式写 `Architecture Context Hit` 和 `Decision Rationale Hit: existing|required|none`。如果输入包含产品方案、架构方案、技术方案、实现方案或验收方案，先在 `plan.md` 或等价临时计划面做 Source-to-Context Coverage，确认方案中的 durable architecture / ownership / API / runtime / verification constraints 已被现有 Context 覆盖、需要更新、仅属 task-local、显式 out-of-scope、需要用户决策或仍 under-scoped。
 5. 普通 bug fix、局部样式、局部实现漂移修复、小重构、package/release 处理、测试修复或探索性 spike 不强制编译架构 / rationale 任务契约，也不更新 Context；一旦形成长期工程结论，继续对齐或交付前必须回写 Context。不要把 Context 机械补成代码改动摘要。
 6. 如果代码、搜索结果或相邻实现与 Context 冲突，显式标记为实现漂移、缺失工作或 Context 过期，不要用当前代码形态反推模块归属。
 7. 涉及已有 Context 的实现判断，先做轻量对齐：
@@ -45,13 +45,13 @@ Project-specific engineering rules belong in a separate project-local Skill unde
    - 默认只实施高收益、低风险、语义稳定的候选项。
    - 不为一次性代码、不稳定语义或纯粹好看的架构做抽象。
 13. 当人工流程呈现重复、确定性、容易漏步骤或顺序影响正确性时，主动评估是否应沉淀为 repo-local tool/script。脚本应放在 owning module 的工具目录并配测试；可恢复的执行入口、参数约束和适用边界写入对应 verification / deployment Context。Skill 只记录这类脚本化机会识别原则，不承载具体模块命令、provider id、artifact 路径或一次性运行结果。
-14. 需要沉淀长期事实时，只更新 `project_context/**`：
+14. 需要沉淀长期事实时，只更新 `project_context/**`：
    - 全局工程取舍、跨产品域索引或当前状态写入 `global.md`。
    - 产品域 API、数据契约、关键约束、入口和风险写入对应 area / subdomain Context。
    - 跨域接口语义写入 `context_role: contract` 或 manifest role 为 `contract` 的 Context；关键重复验证路径写入 `verification`；关键部署、运行拓扑或云端初始化路径写入 `deployment`；代码入口索引用 `implementation-index`；底层理论源用 `foundation`；历史归档索引用 `archive`。
    - 新 context unit 可新增 `project_context/areas/<unit>.md`，并更新 `global.md#Context Index`；复杂项目同时更新 `project_context/context.toml`。
    - 如果 `upgrade` 自动把深层 `.md` 注册成 area，但语义上更像 foundation / contract / archive，后续应显式调整 manifest role；不要依赖自动迁移判断语义。
-15. 实现收尾时做 `Contract Conformance` 和 Context drift check：确认代码没有引入未沉淀的长期事实，且 Context 没有退化成普通实现摘要；交付说明只报告轻量状态：`Context: 已更新 ...` 或 `Context: 本次无长期事实变化`。Conformance 说明本次契约满足情况、未满足或延期项和验证入口；一次性证据、截图结果、测试日志、任务契约和实现摘要不写入 Context。
+15. 实现收尾时做 `Contract Conformance` 和 Context drift check：确认代码没有引入未沉淀的长期事实，且 Context 没有退化成普通实现摘要；若存在 `plan.md` / 等价临时计划面，必须反查 Source-to-Context Coverage、Context-to-Implementation Binding 和 Task Contract，确认没有未处理的 `under_scoped` / `new_context_required` / `needs_user_decision`，也没有 non-bound implementation rows。交付说明只报告轻量状态：`Context: 已更新 ...` 或 `Context: 本次无长期事实变化`。Conformance 说明本次契约满足情况、未满足或延期项和验证入口；一次性证据、截图结果、测试日志、任务契约和实现摘要不写入 Context。
 16. Context 只能声明验证 / 部署关键路径或验收信号，不能伪造“测试已通过”或“部署已成功”。
 17. Verification / Deployment Role Context 只记录长期可复用的重复执行路径事实：特殊准备、最短命令或路径、预期阶段 / 信号、可接受 warning、已排除的重复探索点。不要记录一次性测试日志、完整输出、临时 JSON、CI artifact、测试报告、release ledger、secret、token、cookie、device id 或 raw payload。
 
@@ -76,13 +76,18 @@ Project-specific engineering rules belong in a separate project-local Skill unde
   - `none`：没有超限计划 / touched 手写源码文件，或本次没有向超限文件增加新职责。
   - `required`：拆分是本次验收条件，应按 abstraction / decomposition scan 的职责边界完成。
   - `exception`：本次触碰超限文件但暂不拆；只有默认 `modularity.policy: scoped_waivers` 允许此路径，且必须已有或同步新增 `<harnessRoot>/config.yaml` `modularity.waivers` 记录文件、收窄分类、原因和后续拆分边界。若项目设置 `modularity.policy: strict_except_generated`，不得用 legacy waiver 绕过超限手写源码，交付说明只记录本次是否新增职责以及为什么没有拆。
-- `Applicable Module Design` 是高风险任务的前置字段：列出命中的 Context / Skill 来源、适用的 Principles、Design Logic 和 Design Rationale，以及它们控制的当前实现或验证选择。
+- `Applicable Module Design` 是高风险任务的前置字段：列出命中的 Context / Skill 来源、适用的 Principles、Design Logic 和 Design Rationale，以及它们控制的当前实现或验证选择。
 - `Principle Decision Gate` 要写明首选执行路径、fallback / degraded path 的进入条件，以及什么证据不能证明本次目标。涉及 capability、metric 或 acceptance claim 时，先声明要证明的 claim，再选择命令或 probe。
-- 对长任务、多模块、多 agent、容易发生 `Context Delta` 调头或多轮验证的任务，可以用 `plan.md` 或等价临时计划面暂存 `Context Delta`、`Task Contract`、`Implementation Steps` 和 `Contract Conformance`；它只是临时执行缓存。
-- `plan.md` 中出现的长期工程事实必须提炼回 `project_context/**`；否则不要把临时计划当作事实源、交付产物或后续引用依据。
-- `Context Delta: required` 时先更新 `project_context/**`，再继续实现；`none` 时直接按 Task Contract 实现。
-- `Contract Conformance` 是交付前的软检查：实现偏差修实现，契约遗漏回 Task Contract，长期事实缺失回 `Context Delta` 并先更新 Context。
-- 不为普通代码修改、bug fix、小重构、package/release 处理、测试修复、探索性 spike 或仅因 touched file 过大强制编译架构 / rationale 任务契约；大文件只走 `Modularity Check` 的拆分 / exception 判断。
+- 对长任务、多模块、多 agent、外部产品/架构/技术/实现/验收方案输入、容易发生 `Context Delta` 调头或多轮验证的任务，使用 `plan.md` 或等价临时计划面暂存 `Source-to-Context Coverage`、`Context-to-Implementation Binding`、`Context Delta`、`Task Contract`、`Implementation Steps` 和 `Contract Conformance`；它只是临时执行缓存。
+- small code task 指现有 Context 已足够、且不改变 durable product / architecture / API-schema / runtime-state / verification-deployment / security-redaction / surface ownership 事实的局部实现任务；它按语义风险判断，不按代码行数判断，不应创建 `plan.md`、完整 trace tables、Source-to-Context Coverage 或 Context-to-Implementation Binding，除非它发现长期事实变化或扩展成高风险工作。
+- `Source-to-Context Coverage` 表使用字段：`Source item | Durable constraint | Type | Existing Context Hit | Context action | Owning Context | Coverage status`。这张表只回答 source 约束是否进入或命中 Context，不写实现路径。
+- `Coverage status` 取值：`covered`、`new_context_required`、`context_updated`、`task_local_only`、`out_of_scope_explicit`、`needs_user_decision`、`under_scoped`。存在 `under_scoped` 或未处理的 `new_context_required` / `needs_user_decision` 时，不能声称已按方案完整实现。
+- `Context-to-Implementation Binding` 表使用字段：`Context fact | Implementation obligation | Expected surfaces | Implemented paths | Forbidden shortcuts | Verification path | Binding status`。
+- `Binding status` 取值：`bound`、`partial`、`missing`、`blocked`、`out_of_scope_explicit`、`needs_user_decision`、`contradicted_by_current_state`。runtime/API/worker 项不能只用测试名或 browser checked path 冒充 `bound`。
+- `plan.md` 中出现的长期工程事实必须提炼回 `project_context/**`；否则不要把临时计划当作事实源、交付产物或后续引用依据。
+- `Context Delta: required` 时先更新 `project_context/**`，再继续实现；`none` 时直接按 Task Contract 实现。
+- `Contract Conformance` 是交付前的软检查：实现偏差修实现，契约遗漏回 Task Contract，长期事实缺失或 source coverage under-scoped 回 `Context Delta` 并先更新 Context。
+- 不为 small code task、普通代码修改、bug fix、小重构、package/release 处理、测试修复、探索性 spike 或仅因 touched file 过大强制编译架构 / rationale 任务契约；大文件只走 `Modularity Check` 的拆分 / exception 判断。
 
 ## 模块设计上下文写法
 

package/assets/skills/context_product_plan/SKILL.md

@@ -25,7 +25,7 @@ Project-specific product planning rules belong in a separate project-local Skill
 4. 涉及输入、选择、搜索、筛选、表单/配置、调度/时间窗口、预算/配额/限流或加载/空态/错误态等 UI 控件时，用“控件任务框架”重新理解用户任务和产品反馈；这只是通用判断框架，不是业务处方库。
 5. 当一个产品对象、能力或接口的增删改需要跨多个页面、模块、Context 或产品域同步调整时，将该影响范围视为产品边界复核信号；先判断它是否应沉淀为独立能力、subdomain 或 area，并明确对外契约、所有权和消费方边界，避免通过手工清单长期维护各消费面的重复映射。
 6. 产品意图、模块职责、边界和验收口径以 `project_context/**` 为准；代码和搜索结果只说明当前实现状态。Context 决定“应该是什么”，代码揭示“现在是什么”，代码不能静默重定义 Context。
-7. 输出产品判断或第一处实现编辑前，若任务涉及产品方案、页面/模块边界、信息架构、API / Schema、验收口径、跨域契约、状态或调度语义，先编译当前任务契约；契约第一段用 `Context Delta: none|required` 完成唯一正式长期事实判断，再写本次 `Task Contract`。
+7. 输出产品判断或第一处实现编辑前，若任务涉及产品方案、页面/模块边界、信息架构、API / Schema、验收口径、跨域契约、状态或调度语义，先编译当前任务契约；契约第一段用 `Context Delta: none|required` 完成唯一正式长期事实判断，再写本次 `Task Contract`。如果输入包含产品方案、架构方案、技术方案或验收方案，先在 `plan.md` 或等价临时计划面做 Source-to-Context Coverage，确认方案中的 durable product / surface / IA / acceptance constraints 已被现有 Context 覆盖、需要更新、仅属 task-local、显式 out-of-scope、需要用户决策或仍 under-scoped。
 8. 普通 bug fix、局部样式、局部实现漂移、测试修复或探索性 spike 不更新 Context；如果过程中形成长期产品结论，应在继续对齐或交付前回写 Context。不要把 Context 机械补成代码改动摘要。
 9. 如果代码与 Context 冲突，显式标记为实现漂移、缺失工作或 Context 过期。
 10. 输出产品判断时保持短而具体，避免长篇 PRD 模板。
@@ -45,13 +45,18 @@ Project-specific product planning rules belong in a separate project-local Skill
 - `Context Delta` 必须先出现，取值为 `none` 或 `required`：
   - `none`：本次只是按既有 Context / 原则落地，不新增长期事实。
   - `required`：说明长期事实类型、应写入的 Context / role、需要沉淀的事实，以及明确不写入 Context 的一次性内容。
-- `Task Contract` 用短列表说明本次产品实现必须满足的目标、用户任务、信息 / 动作 / 状态 / 反馈、边界、非目标和验收信号。
-- 触及 Product Surface 时，`Task Contract` 同时说明 surface platform、primary user question、main allows/forbids、drilldown ownership、long-task state requirement 和 verification；业务特定答案进入项目 Context 或项目本地 Skill，不写进 package-managed Skill。
-- 对长任务、多模块、多 agent、容易发生 `Context Delta` 调头或多轮验证的任务，可以用 `plan.md` 或等价临时计划面暂存 `Context Delta`、`Task Contract`、`Implementation Steps` 和 `Contract Conformance`；它只是临时执行缓存。
-- `plan.md` 中出现的长期事实必须提炼回 `project_context/**`；否则不要把临时计划当作事实源、交付产物或后续引用依据。
-- `Context Delta: required` 时先更新 `project_context/**`，再继续实现；`none` 时直接按 Task Contract 实现。
-- `Contract Conformance` 是交付前的软检查：实现偏差修实现，契约遗漏回 Task Contract，长期事实缺失回 `Context Delta` 并先更新 Context。
-- 不为普通 bug fix、局部样式、小重构、局部实现漂移、测试修复或探索性 spike 强制编译任务契约。
+- `Task Contract` 用短列表说明本次产品实现必须满足的目标、用户任务、信息 / 动作 / 状态 / 反馈、边界、非目标和验收信号。
+- 触及 Product Surface 时，`Task Contract` 同时说明 surface platform、primary user question、main allows/forbids、drilldown ownership、long-task state requirement 和 verification；业务特定答案进入项目 Context 或项目本地 Skill，不写进 package-managed Skill。
+- 对长任务、多模块、多 agent、外部产品/架构/技术/验收方案输入、容易发生 `Context Delta` 调头或多轮验证的任务，使用 `plan.md` 或等价临时计划面暂存 `Source-to-Context Coverage`、`Context-to-Implementation Binding`、`Context Delta`、`Task Contract`、`Implementation Steps` 和 `Contract Conformance`；它只是临时执行缓存。
+- small code task 指现有 Context 已足够、且不改变 durable product / architecture / API-schema / runtime-state / verification-deployment / security-redaction / surface ownership 事实的局部实现任务；它按语义风险判断，不按代码行数判断，不应创建 `plan.md`、完整 trace tables、Source-to-Context Coverage 或 Context-to-Implementation Binding，除非它发现长期事实变化或扩展成高风险工作。
+- `Source-to-Context Coverage` 表使用字段：`Source item | Durable constraint | Type | Existing Context Hit | Context action | Owning Context | Coverage status`。这张表只回答 source 约束是否进入或命中 Context，不写实现路径。
+- `Coverage status` 取值：`covered`、`new_context_required`、`context_updated`、`task_local_only`、`out_of_scope_explicit`、`needs_user_decision`、`under_scoped`。存在 `under_scoped` 或未处理的 `new_context_required` / `needs_user_decision` 时，不能声称已按方案完整实现。
+- `Context-to-Implementation Binding` 表使用字段：`Context fact | Implementation obligation | Expected surfaces | Implemented paths | Forbidden shortcuts | Verification path | Binding status`。
+- `Binding status` 取值：`bound`、`partial`、`missing`、`blocked`、`out_of_scope_explicit`、`needs_user_decision`、`contradicted_by_current_state`。存在 non-bound 项时，不能声称已按 Context 完整落地。
+- `plan.md` 中出现的长期事实必须提炼回 `project_context/**`；否则不要把临时计划当作事实源、交付产物或后续引用依据。
+- `Context Delta: required` 时先更新 `project_context/**`，再继续实现；`none` 时直接按 Task Contract 实现。
+- `Contract Conformance` 是交付前的软检查：实现偏差修实现，契约遗漏回 Task Contract，长期事实缺失或 source coverage under-scoped 回 `Context Delta` 并先更新 Context。
+- 不为 small code task、普通 bug fix、局部样式、小重构、局部实现漂移、测试修复或探索性 spike 强制编译任务契约。
 
 ## 产品体验校准