project-tiny-context-harness 0.8.4 → 0.8.5

package/assets/context_templates/product-surface-contract.md

@@ -1,70 +1,70 @@
-# 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:
-- Design Rationale:
-- Empty / Loading / Stale / Unavailable:
-- Security / Redaction:
-- Verification:
-
-## Cross-Surface Rules
-
-- `<durable project-specific rule>`
-
-## Screen Contract Routing
-
-Keep this file at cross-surface responsibility depth. When one material screen needs durable entry/exit/shared-state, information hierarchy, semantic region order, fixed/scroll/overlay ownership, navigation, variants, material controls or design-target references, create an on-demand Screen Contract from `screen-contract.md` using an existing area/subdomain role (or `contract` only for a true cross-area interface).
-
-Link by stable surface/control/target keys. Do not duplicate the Screen Contract here, copy exact visual tokens from `DESIGN.md`, or embed authored target binaries and test evidence.
-
-## 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 durable main/drilldown/diagnostic ownership rationale, rejected alternative or tradeoff will guide future changes.
-- A repeated UI/product rule becomes reusable.
-- A platform-specific interaction rule becomes stable.
-- Cross-surface ownership changes which Screen Contract owns a detail.
-
-Do not update this Context for:
-
-- CSS-only fixes.
-- One-off screenshot observations.
-- Temporary audit notes.
-- Test logs.
-- Local implementation summaries.
-- PR notes, command output, screenshot review notes, debug history, agent reasoning or rationale inferred only from current code shape.
+# 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:
+- Design Rationale:
+- Empty / Loading / Stale / Unavailable:
+- Security / Redaction:
+- Verification:
+
+## Cross-Surface Rules
+
+- `<durable project-specific rule>`
+
+## Screen Contract Routing
+
+Keep this file at cross-surface responsibility depth. When one material screen needs durable entry/exit/shared-state, information hierarchy, semantic region order, fixed/scroll/overlay ownership, navigation, variants, material controls or design-target references, create an on-demand Screen Contract from `screen-contract.md` using an existing area/subdomain role (or `contract` only for a true cross-area interface).
+
+Link by stable surface/control/target keys. Do not duplicate the Screen Contract here, copy exact visual tokens from `DESIGN.md`, or embed authored target binaries and test evidence.
+
+## 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 durable main/drilldown/diagnostic ownership rationale, rejected alternative or tradeoff will guide future changes.
+- A repeated UI/product rule becomes reusable.
+- A platform-specific interaction rule becomes stable.
+- Cross-surface ownership changes which Screen Contract owns a detail.
+
+Do not update this Context for:
+
+- CSS-only fixes.
+- One-off screenshot observations.
+- Temporary audit notes.
+- Test logs.
+- Local implementation summaries.
+- PR notes, command output, screenshot review notes, debug history, agent reasoning or rationale inferred only from current code shape.

package/assets/context_templates/screen-contract.md

@@ -1,189 +1,189 @@
-# Screen Contract
-
-## Purpose
-
-This optional on-demand Context records durable responsibility, information hierarchy and interaction semantics for one user-facing screen/surface when a Product Surface Contract is too coarse for future implementation and verification.
-
-A screen may be a Web route, mobile screen, desktop window, game HUD/menu scene, CLI/TUI view, extension panel, kiosk or embedded-device interface. Use only the relevant sections. Do not create a Screen Contract for a semantics-preserving CSS/style fix, one-off UI bug or explicit throwaway prototype.
-
-Write project-specific facts only. Do not copy visual token values, binary targets, implementation screenshots, test logs, raw payloads, implementation summaries or secrets into this file.
-
-## Authority Boundary
-
-- Product Surface Contract owns cross-surface responsibility, main/drilldown placement and shared invariants.
-- This Screen Contract owns stable screen hierarchy, regions, state/navigation behavior, durable material-control semantics and canonical adoption records for one-screen/interaction-specific targets.
-- `DESIGN.md` owns visual-system semantics, the authored token source/generation direction and canonical adoption records for project/system/component-family targets.
-- Versioned authored design targets own their declared concrete composition for named viewport/mode/state/content conditions.
-- Verification Context owns repeatable proof paths. Code is current implementation evidence, not silent design authority.
-
-If these owners conflict, update the stale owner or retain a genuine decision. Do not resolve a conflict from file order, current code shape or an implementation-generated screenshot.
-
-## Screen Identity
-
-- Surface Key:
-- Surface / Route / Command:
-- Platform:
-- Owning Product Domain:
-- Primary User Question:
-- In-Scope User Tasks:
-- Explicit Non-Goals:
-
-## Entry, Exit And Shared State
-
-- Entry Context / Preconditions:
-- Entry Points / Deep Links:
-- Inherited Shared State:
-- Locally Editable State:
-- Committed State Changes:
-- Exit Outcomes / Destinations:
-- Back / Cancel / Interruption Behavior:
-- Focus / Selection Restoration:
-
-## Information Hierarchy
-
-Record semantic order and responsibility, not pixel coordinates.
-
-1. Primary judgment:
-2. Primary action:
-3. Supporting information:
-4. Secondary actions:
-5. Drilldown / evidence / diagnostics:
-6. Information forbidden from permanent main-surface placement:
-
-## Layout Contract
-
-### Regions
-
-| Region Key | Order | Responsibility | Fixed / Scroll / Overlay | Visibility Conditions |
-|---|---:|---|---|---|
-| `<region-key>` | 1 |  |  |  |
-
-### Spatial And Container Ownership
-
-- Safe-area / system-chrome ownership:
-- Fixed or sticky elements:
-- Scroll owner and restoration:
-- Overlay / modal / sheet owner:
-- Map / canvas / media visible-area contract:
-- Keyboard / input-method behavior:
-- Gesture competition / pointer ownership:
-
-## Control Inventory
-
-Each material control has a stable semantic key. Fill only applicable fields; do not add generic filler for non-applicable states.
-
-### `<control-key>`
-
-- Surface:
-- Region:
-- Location:
-- Control Type:
-- Label / Content:
-- User Task:
-- Visibility:
-- Availability:
-- Trigger:
-- Input:
-- Validation:
-- Default Value / Restored State:
-- Interaction / Commit / Cancel:
-- Navigation / Result:
-- Loading State:
-- Empty / No-Result State:
-- Success State:
-- Failure / Degraded State:
-- Recovery / Retry / Interruption:
-- Permission / Denial Path:
-- Feedback:
-- Accessibility / Keyboard / Focus / Motion Alternative:
-
-## Screen State Variants
-
-Describe composition or responsibility changes, not one-off screenshots.
-
-- Initial / loading:
-- Empty / no results:
-- Partial / stale / degraded:
-- Error / unavailable:
-- Permission denied:
-- Disabled / saving / mutating:
-- Success / confirmation:
-- Offline / recovery when applicable:
-
-## Responsive, Mode And Content Variants
-
-- Viewport / size-class boundaries:
-- Orientation / window-resize behavior:
-- Theme / product-mode differences:
-- Text scaling / localization / long-content behavior:
-- Reduced motion / contrast / input-mode differences:
-- Other explicitly unsupported combinations:
-
-## Navigation And Interaction Contract
-
-- Forward navigation and committed state:
-- Back / system-back / predictive-back behavior:
-- Deep-link behavior:
-- Modal / sheet / popover lifecycle:
-- Gesture ownership and accessible alternative:
-- Cancellation, interruption and recovery:
-- Cross-surface state/version consistency:
-
-## Design Target References
-
-Reference project-native targets; do not embed binary content. Every adopted target has exactly one canonical adoption record. Use this Screen Contract as the canonical owner only for a one-screen/interaction-specific target. For a project/system/component-family target owned by `DESIGN.md`, fill only its stable ID, `DESIGN.md` anchor and this screen's local applicability; do not repeat the full record.
-
-| Target ID | Canonical Owner / Anchor | Interpretation | Immutable Adopted Path / URI + Digest | Editable Upstream / Owner / Update Route | Declared Condition Coverage | Selection Basis | Local Applicability |
-|---|---|---|---|---|---|---|---|
-| `<stable-target-id>` | `this Screen Contract#...` / `DESIGN.md#...` | `exact-target` / `constraint` / `inspiration` |  |  |  |  |  |
-
-The canonical record owns interpretation, selection basis, immutable locator/digest, declared condition coverage and editable upstream/update route. Leave those fields pointer-only when this Screen Contract is not the canonical owner. An `exact-target` authorizes fidelity comparison only for its declared conditions. A `constraint` governs only its named rule. `inspiration` does not authorize reproduction. For an adopted exact target/constraint, the immutable locator must be readable and the editable upstream/update route must be verified or explicitly marked as a manual/external boundary. Relevant work opens the resource rather than treating this row as consumption. Update upstream and register a new immutable version/digest in the canonical record; never overwrite the adopted baseline. An implementation screenshot cannot register itself as its own target.
-
-### Selected Implementation Handoff
-
-- Handoff Source Path:
-- Handoff Scope Key:
-- Affected Subject / Target Keys:
-- Durable Owner / Update Boundary:
-
-Fill this pointer only when selected implementation resources use a validated `design-resource-handoff-v1`. The handoff remains ordinary Source and owns its strict subject-by-eight-dimension condition/evidence/verification index; do not duplicate that changing index into Context. This Screen Contract owns durable screen/control meaning and makes the handoff/targets reachable. Consumers must rerun shared preflight and open affected exact/constraint resources; neither this pointer nor a successful digest proves implementation conformance.
-
-## Verification
-
-- Semantic / information-hierarchy check:
-- Control behavior / state check:
-- Visual target / layout check:
-- Accessibility / focus / motion check:
-- Cross-surface shared-state check:
-- Target-runtime / native-device check:
-- Human or external confirmation boundary:
-- Known unproved combinations:
-
-## Stable Design Rationale
-
-- Decision:
-- Reason:
-- Rejected alternative when still decision-relevant:
-- Tradeoff that must guide future changes:
-
-Do not invent rationale from current implementation shape. Record a rejected alternative or tradeoff only when it is durable enough to constrain future screen decisions.
-
-## Registration Example
-
-Use an existing role. A screen owned by one domain normally uses `subdomain` (or the owning `area` file when small); use `contract` only when the screen itself is a cross-area interface.
-
-```toml
-[[context]]
-path = "project_context/areas/<area>/screens/<screen>.md"
-role = "subdomain"
-triggers = ["<surface-key>", "<route>", "<screen name>", "<material control key>"]
-read_policy = "on-demand"
-```
-
-Do not introduce `screen`, `design`, `surface-contract` or another custom role.
-
-## Maintenance Rules
-
-Update this Context when durable screen responsibility, hierarchy, region ownership, navigation/shared-state behavior, responsive/mode semantics or reusable material-control behavior changes.
-
-Do not update it for CSS-only fixes, one-off screenshot findings, generated diffs, temporary audit notes, test logs, command output, implementation summaries, PR notes or rationale inferred only from current code.
+# Screen Contract
+
+## Purpose
+
+This optional on-demand Context records durable responsibility, information hierarchy and interaction semantics for one user-facing screen/surface when a Product Surface Contract is too coarse for future implementation and verification.
+
+A screen may be a Web route, mobile screen, desktop window, game HUD/menu scene, CLI/TUI view, extension panel, kiosk or embedded-device interface. Use only the relevant sections. Do not create a Screen Contract for a semantics-preserving CSS/style fix, one-off UI bug or explicit throwaway prototype.
+
+Write project-specific facts only. Do not copy visual token values, binary targets, implementation screenshots, test logs, raw payloads, implementation summaries or secrets into this file.
+
+## Authority Boundary
+
+- Product Surface Contract owns cross-surface responsibility, main/drilldown placement and shared invariants.
+- This Screen Contract owns stable screen hierarchy, regions, state/navigation behavior, durable material-control semantics and canonical adoption records for one-screen/interaction-specific targets.
+- `DESIGN.md` owns visual-system semantics, the authored token source/generation direction and canonical adoption records for project/system/component-family targets.
+- Versioned authored design targets own their declared concrete composition for named viewport/mode/state/content conditions.
+- Verification Context owns repeatable proof paths. Code is current implementation evidence, not silent design authority.
+
+If these owners conflict, update the stale owner or retain a genuine decision. Do not resolve a conflict from file order, current code shape or an implementation-generated screenshot.
+
+## Screen Identity
+
+- Surface Key:
+- Surface / Route / Command:
+- Platform:
+- Owning Product Domain:
+- Primary User Question:
+- In-Scope User Tasks:
+- Explicit Non-Goals:
+
+## Entry, Exit And Shared State
+
+- Entry Context / Preconditions:
+- Entry Points / Deep Links:
+- Inherited Shared State:
+- Locally Editable State:
+- Committed State Changes:
+- Exit Outcomes / Destinations:
+- Back / Cancel / Interruption Behavior:
+- Focus / Selection Restoration:
+
+## Information Hierarchy
+
+Record semantic order and responsibility, not pixel coordinates.
+
+1. Primary judgment:
+2. Primary action:
+3. Supporting information:
+4. Secondary actions:
+5. Drilldown / evidence / diagnostics:
+6. Information forbidden from permanent main-surface placement:
+
+## Layout Contract
+
+### Regions
+
+| Region Key | Order | Responsibility | Fixed / Scroll / Overlay | Visibility Conditions |
+|---|---:|---|---|---|
+| `<region-key>` | 1 |  |  |  |
+
+### Spatial And Container Ownership
+
+- Safe-area / system-chrome ownership:
+- Fixed or sticky elements:
+- Scroll owner and restoration:
+- Overlay / modal / sheet owner:
+- Map / canvas / media visible-area contract:
+- Keyboard / input-method behavior:
+- Gesture competition / pointer ownership:
+
+## Control Inventory
+
+Each material control has a stable semantic key. Fill only applicable fields; do not add generic filler for non-applicable states.
+
+### `<control-key>`
+
+- Surface:
+- Region:
+- Location:
+- Control Type:
+- Label / Content:
+- User Task:
+- Visibility:
+- Availability:
+- Trigger:
+- Input:
+- Validation:
+- Default Value / Restored State:
+- Interaction / Commit / Cancel:
+- Navigation / Result:
+- Loading State:
+- Empty / No-Result State:
+- Success State:
+- Failure / Degraded State:
+- Recovery / Retry / Interruption:
+- Permission / Denial Path:
+- Feedback:
+- Accessibility / Keyboard / Focus / Motion Alternative:
+
+## Screen State Variants
+
+Describe composition or responsibility changes, not one-off screenshots.
+
+- Initial / loading:
+- Empty / no results:
+- Partial / stale / degraded:
+- Error / unavailable:
+- Permission denied:
+- Disabled / saving / mutating:
+- Success / confirmation:
+- Offline / recovery when applicable:
+
+## Responsive, Mode And Content Variants
+
+- Viewport / size-class boundaries:
+- Orientation / window-resize behavior:
+- Theme / product-mode differences:
+- Text scaling / localization / long-content behavior:
+- Reduced motion / contrast / input-mode differences:
+- Other explicitly unsupported combinations:
+
+## Navigation And Interaction Contract
+
+- Forward navigation and committed state:
+- Back / system-back / predictive-back behavior:
+- Deep-link behavior:
+- Modal / sheet / popover lifecycle:
+- Gesture ownership and accessible alternative:
+- Cancellation, interruption and recovery:
+- Cross-surface state/version consistency:
+
+## Design Target References
+
+Reference project-native targets; do not embed binary content. Every adopted target has exactly one canonical adoption record. Use this Screen Contract as the canonical owner only for a one-screen/interaction-specific target. For a project/system/component-family target owned by `DESIGN.md`, fill only its stable ID, `DESIGN.md` anchor and this screen's local applicability; do not repeat the full record.
+
+| Target ID | Canonical Owner / Anchor | Interpretation | Immutable Adopted Path / URI + Digest | Editable Upstream / Owner / Update Route | Declared Condition Coverage | Selection Basis | Local Applicability |
+|---|---|---|---|---|---|---|---|
+| `<stable-target-id>` | `this Screen Contract#...` / `DESIGN.md#...` | `exact-target` / `constraint` / `inspiration` |  |  |  |  |  |
+
+The canonical record owns interpretation, selection basis, immutable locator/digest, declared condition coverage and editable upstream/update route. Leave those fields pointer-only when this Screen Contract is not the canonical owner. An `exact-target` authorizes fidelity comparison only for its declared conditions. A `constraint` governs only its named rule. `inspiration` does not authorize reproduction. For an adopted exact target/constraint, the immutable locator must be readable and the editable upstream/update route must be verified or explicitly marked as a manual/external boundary. Relevant work opens the resource rather than treating this row as consumption. Update upstream and register a new immutable version/digest in the canonical record; never overwrite the adopted baseline. An implementation screenshot cannot register itself as its own target.
+
+### Selected Implementation Handoff
+
+- Handoff Source Path:
+- Handoff Scope Key:
+- Affected Subject / Target Keys:
+- Durable Owner / Update Boundary:
+
+Fill this pointer only when selected implementation resources use a validated `design-resource-handoff-v1`. The handoff remains ordinary Source and owns its strict subject-by-eight-dimension condition/evidence/verification index; do not duplicate that changing index into Context. This Screen Contract owns durable screen/control meaning and makes the handoff/targets reachable. Consumers must rerun shared preflight and open affected exact/constraint resources; neither this pointer nor a successful digest proves implementation conformance.
+
+## Verification
+
+- Semantic / information-hierarchy check:
+- Control behavior / state check:
+- Visual target / layout check:
+- Accessibility / focus / motion check:
+- Cross-surface shared-state check:
+- Target-runtime / native-device check:
+- Human or external confirmation boundary:
+- Known unproved combinations:
+
+## Stable Design Rationale
+
+- Decision:
+- Reason:
+- Rejected alternative when still decision-relevant:
+- Tradeoff that must guide future changes:
+
+Do not invent rationale from current implementation shape. Record a rejected alternative or tradeoff only when it is durable enough to constrain future screen decisions.
+
+## Registration Example
+
+Use an existing role. A screen owned by one domain normally uses `subdomain` (or the owning `area` file when small); use `contract` only when the screen itself is a cross-area interface.
+
+```toml
+[[context]]
+path = "project_context/areas/<area>/screens/<screen>.md"
+role = "subdomain"
+triggers = ["<surface-key>", "<route>", "<screen name>", "<material control key>"]
+read_policy = "on-demand"
+```
+
+Do not introduce `screen`, `design`, `surface-contract` or another custom role.
+
+## Maintenance Rules
+
+Update this Context when durable screen responsibility, hierarchy, region ownership, navigation/shared-state behavior, responsive/mode semantics or reusable material-control behavior changes.
+
+Do not update it for CSS-only fixes, one-off screenshot findings, generated diffs, temporary audit notes, test logs, command output, implementation summaries, PR notes or rationale inferred only from current code.

package/assets/context_templates/verification.md

@@ -1,32 +1,32 @@
-# Verification Context: main
-
-This role Context records critical repeat-execution paths for the owning area. Keep it minimal: enough for a future agent to rerun verification without rediscovering setup, not a test report.
-
-## Owner
-
-- Owning area: `main`.
-
-## Verification Paths
-
-- `npm test` or the shortest project-specific test, smoke, CI, probe or validation command.
-- Verification paths are reusable execution instances, not independent definitions of the verification target. For capability, metric or acceptance claims, first use the owning module's design Context to decide what claim should be proven, then choose the command or probe.
-
-## Required Preparation
-
-- List only durable setup such as services, env files, fixtures, local runtimes or external dependencies needed before rerun.
-
-## Expected Signals
-
-- Name the stage, health check, status, artifact shape or observable signal that means the path reached the intended point.
-
-## Acceptable Warnings
-
-- List warnings that are expected and should not trigger repeated investigation.
-
-## Excluded Dead Ends
-
-- List previously ruled-out commands, providers, endpoints or setup paths only when remembering them prevents repeated wasted work.
-
-## Forbidden Content
-
-- Do not record one-off logs, full command output, temporary JSON, CI artifacts, test reports, secrets, tokens, cookies, device ids, raw payloads or pass/fail claims.
+# Verification Context: main
+
+This role Context records critical repeat-execution paths for the owning area. Keep it minimal: enough for a future agent to rerun verification without rediscovering setup, not a test report.
+
+## Owner
+
+- Owning area: `main`.
+
+## Verification Paths
+
+- `npm test` or the shortest project-specific test, smoke, CI, probe or validation command.
+- Verification paths are reusable execution instances, not independent definitions of the verification target. For capability, metric or acceptance claims, first use the owning module's design Context to decide what claim should be proven, then choose the command or probe.
+
+## Required Preparation
+
+- List only durable setup such as services, env files, fixtures, local runtimes or external dependencies needed before rerun.
+
+## Expected Signals
+
+- Name the stage, health check, status, artifact shape or observable signal that means the path reached the intended point.
+
+## Acceptable Warnings
+
+- List warnings that are expected and should not trigger repeated investigation.
+
+## Excluded Dead Ends
+
+- List previously ruled-out commands, providers, endpoints or setup paths only when remembering them prevents repeated wasted work.
+
+## Forbidden Content
+
+- Do not record one-off logs, full command output, temporary JSON, CI artifacts, test reports, secrets, tokens, cookies, device ids, raw payloads or pass/fail claims.

package/assets/github/.gitkeep

@@ -1 +1 @@
-
+