project-tiny-context-harness 0.7.0 → 0.7.1

package/assets/agents/AGENTS_CORE.md

@@ -1,56 +1,56 @@
-# Minimal Context Harness Protocol
-
-This project uses Tiny Context. The Harness maintains durable Context and workflow authority; project tests, CI, runtime evidence and human acceptance prove product quality.
-
-Tiny Context has three capabilities: Minimal Context, the default Workflow Contract, and the explicitly enabled Single-Goal Long-Task Workflow.
-
-## Default Workflow Contract
-
-Unless an active Long-Task binding exists:
-
-1. Read `project_context/global.md`, `project_context/architecture.md`, `project_context/context.toml` and the default area root, then collect graph/trigger candidates.
-2. Before deciding `Context Delta`, run one bounded text search over `project_context/**` using a small set of high-signal task terms such as explicit area/module names and API/schema/state/security/verification/deployment terms. Merge matching Context with manifest candidates and read only relevant files; search supplements rather than replaces semantic judgment.
-3. For UI/product-surface work, confirm information/action/feedback ownership and use `context_surface_contract` when durable responsibility is unclear or changes; contract owns interfaces and existing area/subdomain/verification roles own the project facts.
-4. Decide exactly one `Context Delta: none|required`. Update owning Context before code when durable product ownership, architecture, API/schema/data, state/recovery, dependency, security, product-surface responsibility or repeatable verification/deployment changes. Local fixes preserving durable semantics are `none`.
-5. Use the agent/platform internal plan. For high-risk work keep `Architecture Context Hit`, `Decision Rationale Hit: existing|required|none` and `Modularity Check: none|required|exception` as internal routing and maintenance questions, not artifacts or extra deltas.
-6. Implement precisely, run project-owned verification, perform Contract Conformance and a Context drift check, then report implementation, verification, Context status and blockers.
-
-The default workflow never requires a plan artifact, matrix, verdict, evidence ledger or result document. Optional scratch is not Context or completion proof. The bounded Context search creates no index, cache, state or second authority.
-
-For external product, architecture, technical or acceptance sources, internally classify every material constraint as covered by Context, requiring a Context update, task-local, explicitly out of scope or requiring a genuine user decision. Conformance must confirm controlling Context reached the correct modules, surfaces, APIs, state machines and verification paths without forbidden shortcuts or duplicate authority.
-
-## Long-Task Routing
-
-Do not infer long-task mode from duration, complexity, file count or agent preference.
-
-1. A valid Git common-dir active record plus matching worktree Git-config marker resumes through `ty-context long-task resume <workdir>` and `/long-task-workflow` in the current native Goal.
-2. Explicit `/long-task-workflow` authors or resumes exactly one complete `long-task-delivery-v2` Contract for the selected delivery.
-3. `/normal-long-task` is a retirement pointer. Otherwise remain on the default Workflow Contract, even when work is long.
-
-Contract Draft authoring belongs inside `long-task-workflow`: continuously revise the same non-authoritative `delivery-contract.yaml` until the first successful formal Compile creates Authority Lock. An optional Source Plan is ordinary upstream Source guidance, not a Contract Draft or required input protocol.
-
-The workflow uses one native Goal, one selected workspace, one Contract and one Final Gate. New authoring uses inline Outcomes; existing `outcome_files` are physical compatibility only. Outcomes decompose dependency-ready execution, targeted repair and diagnosis, not completion authority, workers, branches or model sessions.
-
-After the first Authority Lock, stop once before implementation and ask the user to continue with the current model or switch models and then resume the active Long-Task. A model choice already stated explicitly for this task satisfies the checkpoint; later revisions do not repeat it. Harness records no model route or checkpoint state.
-
-Before authoring, proof design or authority lifecycle work, read the phase-specific references in the package-managed `long-task-workflow` Skill. Use `ty-context long-task help` for CLI syntax instead of treating this startup router as a command reference.
-
-Final Gate, Stop and close recompile the source Contract and rerun every declared Check on one clean current snapshot. Targeted verify is repair evidence only. Status, progress, receipts and compiled cache are audit/recovery surfaces only; prose, historical tests or Agent judgment never create acceptance. External confirmations remain explicit and machine acceptance never implies CI, deployment or human acceptance.
-
-Tiny Context does not create or restore platform Goals, invoke models, spawn agents, call an App Server, create branches/worktrees, merge, push, open PRs, deploy or manage process trees. `ty-context enable long-task` installs the Source Plan Authoring Skill, Long-Task Workflow Skill and package-owned completion Hook.
-
-## Durable Facts And Generated Surfaces
-
-- Context is intended ownership/boundary/contract truth; code is current implementation truth. Treat disagreement as drift, missing work or stale Context.
-- Long-term facts live only in `project_context/**` or `DESIGN.md`; logs, raw evidence, secrets, runtime state and receipts do not.
-- Managed `AGENTS.md` blocks, `<harnessRoot>/ty-context-managed/**` and package-managed Skills are generated and sync-overwritten.
-- Explicit upgrades use `context_harness_upgrade`; package sync never imports retired Campaign or development-period authority state.
-
-## Verification
-
-- `make validate-context`: Context recoverability.
-- `make validate-harness`: Context plus touched-source modularity.
-- `ty-context doctor`: installation health plus advisory default Context footprint.
-- `node packages/ty-context/dist/cli.js package check-source`: managed-source/package parity in this source workspace.
-
-Every handoff reports exactly one of `Context: updated ...` or `Context: no durable fact change`. Never claim tests, deployment or acceptance from Context alone.
+# Minimal Context Harness Protocol
+
+This project uses Tiny Context. The Harness maintains durable Context and workflow authority; project tests, CI, runtime evidence and human acceptance prove product quality.
+
+Tiny Context has three capabilities: Minimal Context, the default Workflow Contract, and the explicitly enabled Single-Goal Long-Task Workflow.
+
+## Default Workflow Contract
+
+Unless an active Long-Task binding exists:
+
+1. Read `project_context/global.md`, `project_context/architecture.md`, `project_context/context.toml` and the default area root, then collect graph/trigger candidates.
+2. Before deciding `Context Delta`, run one bounded text search over `project_context/**` using a small set of high-signal task terms such as explicit area/module names and API/schema/state/security/verification/deployment terms. Merge matching Context with manifest candidates and read only relevant files; search supplements rather than replaces semantic judgment.
+3. For UI/product-surface work, confirm information/action/feedback ownership and use `context_surface_contract` when durable responsibility is unclear or changes; contract owns interfaces and existing area/subdomain/verification roles own the project facts.
+4. Decide exactly one `Context Delta: none|required`. Update owning Context before code when durable product ownership, architecture, API/schema/data, state/recovery, dependency, security, product-surface responsibility or repeatable verification/deployment changes. Local fixes preserving durable semantics are `none`.
+5. Use the agent/platform internal plan. For high-risk work keep `Architecture Context Hit`, `Decision Rationale Hit: existing|required|none` and `Modularity Check: none|required|exception` as internal routing and maintenance questions, not artifacts or extra deltas.
+6. Implement precisely, run project-owned verification, perform Contract Conformance and a Context drift check, then report implementation, verification, Context status and blockers.
+
+The default workflow never requires a plan artifact, matrix, verdict, evidence ledger or result document. Optional scratch is not Context or completion proof. The bounded Context search creates no index, cache, state or second authority.
+
+For external product, architecture, technical or acceptance sources, internally classify every material constraint as covered by Context, requiring a Context update, task-local, explicitly out of scope or requiring a genuine user decision. Conformance must confirm controlling Context reached the correct modules, surfaces, APIs, state machines and verification paths without forbidden shortcuts or duplicate authority.
+
+## Long-Task Routing
+
+Do not infer long-task mode from duration, complexity, file count or agent preference.
+
+1. A valid Git common-dir active record plus matching worktree Git-config marker resumes through `ty-context long-task resume <workdir>` and `/long-task-workflow` in the current native Goal.
+2. Explicit `/long-task-workflow` authors or resumes exactly one complete `long-task-delivery-v2` Contract for the selected delivery.
+3. `/normal-long-task` is a retirement pointer. Otherwise remain on the default Workflow Contract, even when work is long.
+
+Contract Draft authoring belongs inside `long-task-workflow`: continuously revise the same non-authoritative `delivery-contract.yaml` until the first successful formal Compile creates Authority Lock. An optional Source Plan is ordinary upstream Source guidance, not a Contract Draft or required input protocol.
+
+The workflow uses one native Goal, one selected workspace, one Contract and one Final Gate. New authoring uses inline Outcomes; existing `outcome_files` are physical compatibility only. Outcomes decompose dependency-ready execution, targeted repair and diagnosis, not completion authority, workers, branches or model sessions.
+
+After the first Authority Lock, stop once before implementation and ask the user to continue with the current model or switch models and then resume the active Long-Task. A model choice already stated explicitly for this task satisfies the checkpoint; later revisions do not repeat it. Harness records no model route or checkpoint state.
+
+Before authoring, proof design or authority lifecycle work, read the phase-specific references in the package-managed `long-task-workflow` Skill. Use `ty-context long-task help` for CLI syntax instead of treating this startup router as a command reference.
+
+Final Gate, Stop and close recompile the source Contract and rerun every declared Check on one clean current snapshot. Targeted verify is repair evidence only. Status, progress, receipts and compiled cache are audit/recovery surfaces only; prose, historical tests or Agent judgment never create acceptance. External confirmations remain explicit and machine acceptance never implies CI, deployment or human acceptance.
+
+Tiny Context does not create or restore platform Goals, invoke models, spawn agents, call an App Server, create branches/worktrees, merge, push, open PRs, deploy or manage process trees. `ty-context enable long-task` installs the Source Plan Authoring Skill, Long-Task Workflow Skill and package-owned completion Hook.
+
+## Durable Facts And Generated Surfaces
+
+- Context is intended ownership/boundary/contract truth; code is current implementation truth. Treat disagreement as drift, missing work or stale Context.
+- Long-term facts live only in `project_context/**` or `DESIGN.md`; logs, raw evidence, secrets, runtime state and receipts do not.
+- Managed `AGENTS.md` blocks, `<harnessRoot>/ty-context-managed/**` and package-managed Skills are generated and sync-overwritten.
+- Explicit upgrades use `context_harness_upgrade`; package sync never imports retired Campaign or development-period authority state.
+
+## Verification
+
+- `make validate-context`: Context recoverability.
+- `make validate-harness`: Context plus touched-source modularity.
+- `ty-context doctor`: installation health plus advisory default Context footprint.
+- `node packages/ty-context/dist/cli.js package check-source`: managed-source/package parity in this source workspace.
+
+Every handoff reports exactly one of `Context: updated ...` or `Context: no durable fact change`. Never claim tests, deployment or acceptance from Context alone.

package/assets/context_templates/architecture.md

@@ -1,33 +1,33 @@
-# Architecture Context
-
-This is the restrained architecture context. Keep only facts that help a fresh agent recover system shape, boundaries and durable constraints quickly.
-
-## System Boundary
-
-- Describe what is inside this project and what external systems, providers or runtime assumptions sit outside it.
-
-## Component Map
-
-- List the smallest useful set of components, areas or context units and how they relate.
-
-## Data / Control Flow
-
-- Summarize only the durable request, event, state or data flow that is hard to infer from code alone.
-
-## Design Rationale
-
-- Record architecture-level choices, rejected alternatives and tradeoffs that still constrain future work; leave this empty when no stable architecture reason exists.
-- Do not invent rationale or store implementation summaries, PR notes, command output, test result claims, debug history, agent reasoning or reasons inferred only from current code shape.
-- Architecture boundary changes should be captured here before implementation alignment.
-
-## Constraints And Tradeoffs
-
-- Capture performance, safety, integration, deployment or maintainability constraints that matter for future changes.
-
-## Verification Implications
-
-- List project-specific verification entry points affected by architectural changes; do not claim tests already passed.
-
-## Open Risks
-
-- List unresolved architectural risks or unknowns.
+# Architecture Context
+
+This is the restrained architecture context. Keep only facts that help a fresh agent recover system shape, boundaries and durable constraints quickly.
+
+## System Boundary
+
+- Describe what is inside this project and what external systems, providers or runtime assumptions sit outside it.
+
+## Component Map
+
+- List the smallest useful set of components, areas or context units and how they relate.
+
+## Data / Control Flow
+
+- Summarize only the durable request, event, state or data flow that is hard to infer from code alone.
+
+## Design Rationale
+
+- Record architecture-level choices, rejected alternatives and tradeoffs that still constrain future work; leave this empty when no stable architecture reason exists.
+- Do not invent rationale or store implementation summaries, PR notes, command output, test result claims, debug history, agent reasoning or reasons inferred only from current code shape.
+- Architecture boundary changes should be captured here before implementation alignment.
+
+## Constraints And Tradeoffs
+
+- Capture performance, safety, integration, deployment or maintainability constraints that matter for future changes.
+
+## Verification Implications
+
+- List project-specific verification entry points affected by architectural changes; do not claim tests already passed.
+
+## Open Risks
+
+- List unresolved architectural risks or unknowns.

package/assets/context_templates/area.md

@@ -1,39 +1,39 @@
-# Area Context: main
-
-## Responsibility
-
-- Describe this product/domain area or context unit's responsibility.
-
-## User / System Contract
-
-- Describe the external behavior, API, CLI, UI, screen state, interaction or data contract. Contract changes should be captured here before implementation alignment.
-- For UI/page areas, name the page responsibility, core user judgment, persistent information/actions/feedback, non-persistent information, and what belongs in downstream consumption, ops, detail or other surfaces when those facts are durable.
-
-## Core Data / API / State
-
-- Summarize important data structures, APIs, state transitions or rules.
-
-## Module Design Capsule
-
-- Principles: stable execution constraints that should affect future module work.
-- Design Logic: the minimum logic for choosing, rejecting, degrading or composing module behavior.
-- Design Rationale: only durable reasons, rejected alternatives and tradeoffs that change later implementation or verification decisions; leave it empty when no stable reason exists.
-- Do not invent rationale or store implementation summaries, PR notes, command output, test result claims, screenshot review notes, debug history, agent reasoning or reasons inferred only from current code shape.
-- Current standards, thresholds and commands belong in the relevant contract or verification Context, not as permanent principles.
-
-## Key Constraints
-
-- List constraints that are not obvious from code alone, including product rules, responsive/a11y needs or visual boundaries.
-
-## Code Entry Points
-
-- `src/` or the concrete file/function entry points.
-
-## Related Role Context
-
-- Verification paths live in this area's `verification` role Context, such as `project_context/areas/main/verification.md`.
-- Deployment/runtime/bootstrap paths live in this area's optional `deployment` role Context when those facts exist.
-
-## Open Risks
-
-- List unresolved risks or blockers.
+# Area Context: main
+
+## Responsibility
+
+- Describe this product/domain area or context unit's responsibility.
+
+## User / System Contract
+
+- Describe the external behavior, API, CLI, UI, screen state, interaction or data contract. Contract changes should be captured here before implementation alignment.
+- For UI/page areas, name the page responsibility, core user judgment, persistent information/actions/feedback, non-persistent information, and what belongs in downstream consumption, ops, detail or other surfaces when those facts are durable.
+
+## Core Data / API / State
+
+- Summarize important data structures, APIs, state transitions or rules.
+
+## Module Design Capsule
+
+- Principles: stable execution constraints that should affect future module work.
+- Design Logic: the minimum logic for choosing, rejecting, degrading or composing module behavior.
+- Design Rationale: only durable reasons, rejected alternatives and tradeoffs that change later implementation or verification decisions; leave it empty when no stable reason exists.
+- Do not invent rationale or store implementation summaries, PR notes, command output, test result claims, screenshot review notes, debug history, agent reasoning or reasons inferred only from current code shape.
+- Current standards, thresholds and commands belong in the relevant contract or verification Context, not as permanent principles.
+
+## Key Constraints
+
+- List constraints that are not obvious from code alone, including product rules, responsive/a11y needs or visual boundaries.
+
+## Code Entry Points
+
+- `src/` or the concrete file/function entry points.
+
+## Related Role Context
+
+- Verification paths live in this area's `verification` role Context, such as `project_context/areas/main/verification.md`.
+- Deployment/runtime/bootstrap paths live in this area's optional `deployment` role Context when those facts exist.
+
+## Open Risks
+
+- List unresolved risks or blockers.

package/assets/context_templates/context.toml

@@ -1,30 +1,30 @@
-# Schema v4 Minimal Context graph manifest.
-# Keep the default product/domain area for ordinary projects. Role context nodes
-# are read-purpose slices owned by an area or, only when cross-domain, by the project root.
-# Use read_policy = "default" only for near-universal recovery facts; prefer
-# "on-demand" for specialized architecture, contract, deployment or history detail.
-# `ty-context doctor` reports the deterministic default read footprint and exact duplicates.
-# When migrating deep files under project_context/areas/**, refine obvious
-# contract/foundation/subdomain/verification/deployment/implementation-index/
-# decision-rationale/archive files into [[context]] entries instead of keeping
-# every Markdown file as an [[areas]] product owner.
-
-[[areas]]
-id = "main"
-root = "."
-context = "project_context/areas/main.md"
-kind = "app"
-default = true
-
-[[context]]
-path = "project_context/areas/main/verification.md"
-role = "verification"
-read_policy = "default"
-triggers = ["test", "verify", "verification", "smoke", "ci"]
-
-# Example optional node:
-# [[context]]
-# path = "project_context/areas/main/deployment.md"
-# role = "deployment"
-# read_policy = "on-demand"
-# triggers = ["deploy", "deployment", "runtime", "cloud", "docker"]
+# Schema v4 Minimal Context graph manifest.
+# Keep the default product/domain area for ordinary projects. Role context nodes
+# are read-purpose slices owned by an area or, only when cross-domain, by the project root.
+# Use read_policy = "default" only for near-universal recovery facts; prefer
+# "on-demand" for specialized architecture, contract, deployment or history detail.
+# `ty-context doctor` reports the deterministic default read footprint and exact duplicates.
+# When migrating deep files under project_context/areas/**, refine obvious
+# contract/foundation/subdomain/verification/deployment/implementation-index/
+# decision-rationale/archive files into [[context]] entries instead of keeping
+# every Markdown file as an [[areas]] product owner.
+
+[[areas]]
+id = "main"
+root = "."
+context = "project_context/areas/main.md"
+kind = "app"
+default = true
+
+[[context]]
+path = "project_context/areas/main/verification.md"
+role = "verification"
+read_policy = "default"
+triggers = ["test", "verify", "verification", "smoke", "ci"]
+
+# Example optional node:
+# [[context]]
+# path = "project_context/areas/main/deployment.md"
+# role = "deployment"
+# read_policy = "on-demand"
+# triggers = ["deploy", "deployment", "runtime", "cloud", "docker"]

package/assets/context_templates/deployment.md

@@ -1,35 +1,35 @@
-# Deployment Context: main
-
-This optional role Context records critical repeat-execution paths for deploy, runtime bootstrap, cloud initialization and operational recovery. Keep it minimal and durable.
-
-## Owner
-
-- Owning area: `main`.
-
-## Runtime Topology
-
-- List durable service distribution only when it matters for rerunning deploy or bootstrap, such as Web/API/worker/Redis/DB/Docker/cloud instance boundaries.
-
-## Deployment Paths
-
-- List the shortest deploy, CI/CD, bootstrap, migration, health-check or rollback/degradation command/path.
-
-## Required Preparation
-
-- List only durable setup such as cloud resources, env files, compose profiles, secret mounting names or database initialization steps. Do not store secret values.
-
-## Expected Signals
-
-- Name health checks, status transitions, URLs, queues, containers or logs-at-a-glance that show the path reached the intended stage.
-
-## Acceptable Warnings
-
-- List known benign warnings or slow-start states.
-
-## Excluded Dead Ends
-
-- List previously ruled-out deploy/bootstrap paths only when remembering them prevents repeated wasted work.
-
-## Forbidden Content
-
-- Do not record one-off logs, full command output, CI artifacts, release ledgers, secrets, tokens, cookies, device ids, raw payloads or claims that deployment already succeeded.
+# Deployment Context: main
+
+This optional role Context records critical repeat-execution paths for deploy, runtime bootstrap, cloud initialization and operational recovery. Keep it minimal and durable.
+
+## Owner
+
+- Owning area: `main`.
+
+## Runtime Topology
+
+- List durable service distribution only when it matters for rerunning deploy or bootstrap, such as Web/API/worker/Redis/DB/Docker/cloud instance boundaries.
+
+## Deployment Paths
+
+- List the shortest deploy, CI/CD, bootstrap, migration, health-check or rollback/degradation command/path.
+
+## Required Preparation
+
+- List only durable setup such as cloud resources, env files, compose profiles, secret mounting names or database initialization steps. Do not store secret values.
+
+## Expected Signals
+
+- Name health checks, status transitions, URLs, queues, containers or logs-at-a-glance that show the path reached the intended stage.
+
+## Acceptable Warnings
+
+- List known benign warnings or slow-start states.
+
+## Excluded Dead Ends
+
+- List previously ruled-out deploy/bootstrap paths only when remembering them prevents repeated wasted work.
+
+## Forbidden Content
+
+- Do not record one-off logs, full command output, CI artifacts, release ledgers, secrets, tokens, cookies, device ids, raw payloads or claims that deployment already succeeded.

package/assets/context_templates/global.md

@@ -1,55 +1,55 @@
-# Project / Delivery Context
-
-## Project Goal
-
-- Describe the user-visible goal this project is trying to achieve.
-
-## Non-goals / Boundaries
-
-- List what this project intentionally does not do.
-
-## Background
-
-- Capture only near-universal background a fresh agent needs before changing code. Route specialized facts through on-demand role Context instead of copying them here.
-
-## Design Rationale
-
-- Record only project-wide durable choices, rejected alternatives and tradeoffs that are hard to infer from code or tests and likely to affect future work. Leave this sparse when no stable reason exists.
-- Do not invent rationale or store implementation summaries, PR notes, command output, test result claims, screenshot review notes, debug history, agent reasoning or reasons inferred only from current code shape.
-- Classify changes before implementation; if a change alters product ownership/plans, module responsibilities, information architecture, API/Schema, state/scheduler semantics, cross-area boundaries, verification role paths or deployment role paths, update Context before code with enough durable context to guide implementation.
-
-## Architecture Context
-
-- Link to `project_context/architecture.md`; keep architecture notes minimal and focused on boundaries, components and constraints that are not obvious from code.
-
-## Context Graph
-
-- Link to `project_context/context.toml` and keep its default area, role, trigger, read policy and boundary metadata aligned with this Context.
-- When adding or reorganizing files under `project_context/areas/**`, run a soft role placement scan before registering every Markdown file as an area: product ownership stays in `area` / `domain` / `subdomain`; contracts, foundations, verification, deployment, implementation indexes, decision rationale and archives should use role Context when that better fits the reading purpose.
-
-## Product / Delivery Brief
-
-- Capture durable product goals, users, core flows, acceptance signals and non-goals.
-
-## UX / Screen Brief
-
-- Capture durable screen, flow, interaction, responsive and accessibility facts. Use `DESIGN.md` for visual identity and design tokens when needed.
-- For web/front-end surfaces, record durable page responsibilities, core user judgments, persistent information boundaries and cross-page or cross-layer ownership when they guide future changes.
-
-## Verification Entry Points
-
-- Point to the default verification context for repeatable test, smoke, CI or validation paths.
-- Project-level cross-domain verification may live here only as a short index; execution details belong in `verification` role Context.
-
-## Current State
-
-- Summarize what is implemented, blocked or risky right now.
-
-## Next Safe Action
-
-- State the safest next step for a fresh agent, including whether the next change should update Context before code.
-
-## Context Index
-
-- [main](areas/main.md)
-- [main verification](areas/main/verification.md)
+# Project / Delivery Context
+
+## Project Goal
+
+- Describe the user-visible goal this project is trying to achieve.
+
+## Non-goals / Boundaries
+
+- List what this project intentionally does not do.
+
+## Background
+
+- Capture only near-universal background a fresh agent needs before changing code. Route specialized facts through on-demand role Context instead of copying them here.
+
+## Design Rationale
+
+- Record only project-wide durable choices, rejected alternatives and tradeoffs that are hard to infer from code or tests and likely to affect future work. Leave this sparse when no stable reason exists.
+- Do not invent rationale or store implementation summaries, PR notes, command output, test result claims, screenshot review notes, debug history, agent reasoning or reasons inferred only from current code shape.
+- Classify changes before implementation; if a change alters product ownership/plans, module responsibilities, information architecture, API/Schema, state/scheduler semantics, cross-area boundaries, verification role paths or deployment role paths, update Context before code with enough durable context to guide implementation.
+
+## Architecture Context
+
+- Link to `project_context/architecture.md`; keep architecture notes minimal and focused on boundaries, components and constraints that are not obvious from code.
+
+## Context Graph
+
+- Link to `project_context/context.toml` and keep its default area, role, trigger, read policy and boundary metadata aligned with this Context.
+- When adding or reorganizing files under `project_context/areas/**`, run a soft role placement scan before registering every Markdown file as an area: product ownership stays in `area` / `domain` / `subdomain`; contracts, foundations, verification, deployment, implementation indexes, decision rationale and archives should use role Context when that better fits the reading purpose.
+
+## Product / Delivery Brief
+
+- Capture durable product goals, users, core flows, acceptance signals and non-goals.
+
+## UX / Screen Brief
+
+- Capture durable screen, flow, interaction, responsive and accessibility facts. Use `DESIGN.md` for visual identity and design tokens when needed.
+- For web/front-end surfaces, record durable page responsibilities, core user judgments, persistent information boundaries and cross-page or cross-layer ownership when they guide future changes.
+
+## Verification Entry Points
+
+- Point to the default verification context for repeatable test, smoke, CI or validation paths.
+- Project-level cross-domain verification may live here only as a short index; execution details belong in `verification` role Context.
+
+## Current State
+
+- Summarize what is implemented, blocked or risky right now.
+
+## Next Safe Action
+
+- State the safest next step for a fresh agent, including whether the next change should update Context before code.
+
+## Context Index
+
+- [main](areas/main.md)
+- [main verification](areas/main/verification.md)

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

@@ -1,63 +1,63 @@
-# 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>`
-
-## 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.
-
-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>`
+
+## 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.
+
+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.