project-tiny-context-harness 0.7.5 → 0.7.7

package/assets/agents/.gitkeep

@@ -1 +1 @@
-
+

package/assets/agents/AGENTS_CORE.md

@@ -1,58 +1,58 @@
-# 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; Product Surface Contracts own cross-surface interfaces and optional on-demand Screen Contracts use existing area/subdomain/contract/verification roles for deeper screen/control facts. Before material production UI implementation, reconcile each affected stable surface/control/target key as Context-covered, requiring a Context update, task-local, out of scope or decision-required, then read `DESIGN.md`, its token source and referenced design targets. An unconfigured starter, candidate, style-only guidance or inspiration does not authorize invented production layout; only a selected exact/constraint target with adequate declared coverage authorizes fidelity. Dedicated external design tools may author resources upstream, but their output remains ordinary Source until this workflow uses `context_uiux_design` when needed to adopt or repair durable Design Authority. Local style fixes and explicit non-fidelity prototypes remain lightweight.
-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.
-
+# 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; Product Surface Contracts own cross-surface interfaces and optional on-demand Screen Contracts use existing area/subdomain/contract/verification roles for deeper screen/control facts. Before material production UI implementation, reconcile each affected stable surface/control/target key as Context-covered, requiring a Context update, task-local, out of scope or decision-required, then read `DESIGN.md`, its token source and referenced design targets. An unconfigured starter, candidate, style-only guidance or inspiration does not authorize invented production layout; only a selected exact/constraint target with adequate declared coverage authorizes fidelity. For an explicit standalone request to generate or iterate design resources, `design-resource-authoring` keeps the requested output/development content as the hard ceiling and may commission the smallest sufficient set from live Open Design capabilities; an implementation handoff covers material in-scope UI/UX meaning through relevant controls without requiring one artifact per control or changing Context, code or Contract. Its output and other externally authored resources remain ordinary Source until this workflow uses `context_uiux_design` when needed to adopt or repair durable Design Authority. Local style fixes and explicit non-fidelity prototypes remain lightweight.
+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.
 
 Externally authored design resources such as Figma frames, images, prototypes, token exports and component specifications are ordinary Source. Their authoring does not update `project_context/**` or `DESIGN.md`, edit production implementation, create a Delivery Contract or claim acceptance. The consuming workflow owns UI Authority Closure, `Context Delta`, durable adoption, implementation and project verification; candidates authorize no fidelity, while selected targets control only their declared surface/viewport/mode/state coverage.
-
-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.
-
+
+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 and externally authored design resources are ordinary upstream Source guidance, not a Contract Draft or required input protocol. Candidate design resources authorize no fidelity Claim; selected targets and acceptance-affecting resources enter real marked Source and existing verification inputs, and after Authority Lock use protected revision.
-
-The workflow uses one native Goal, one selected workspace, one Contract and one Final Gate. New authoring uses inline vertical Outcomes grouped by ordered Stages; existing `outcome_files` are physical compatibility only. Target profiles name required product targets and root runtimes; Checks declare Given/When journeys and all-of Evidence Capabilities. Stage/frontier state is derived from ordinary Progress and creates no second Gate, Receipt, scheduler or completion authority.
-
-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. Required targets cannot substitute for one another; presence cannot prove behavior; success and degradation remain distinct; typed boundary effects require an observer. Targeted verify is repair evidence only. Status, progress, Stage/frontier projections, receipts and compiled cache are audit/recovery surfaces only; prose, historical tests or Agent judgment never create acceptance. An adopted Authority Revision returns to rolling execution and is never delivery completion. External confirmations remain typed and explicit; machine acceptance reports target/stage qualification but cannot by itself authorize completing the platform-native Goal, CI, deployment or human acceptance.
-
+
+The workflow uses one native Goal, one selected workspace, one Contract and one Final Gate. New authoring uses inline vertical Outcomes grouped by ordered Stages; existing `outcome_files` are physical compatibility only. Target profiles name required product targets and root runtimes; Checks declare Given/When journeys and all-of Evidence Capabilities. Stage/frontier state is derived from ordinary Progress and creates no second Gate, Receipt, scheduler or completion authority.
+
+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. Required targets cannot substitute for one another; presence cannot prove behavior; success and degradation remain distinct; typed boundary effects require an observer. Targeted verify is repair evidence only. Status, progress, Stage/frontier projections, receipts and compiled cache are audit/recovery surfaces only; prose, historical tests or Agent judgment never create acceptance. An adopted Authority Revision returns to rolling execution and is never delivery completion. External confirmations remain typed and explicit; machine acceptance reports target/stage qualification but cannot by itself authorize completing the platform-native Goal, 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.
+
+## 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`; versioned authored design targets remain upstream project Source/verifier inputs until the consuming workflow adopts durable meaning, while generated implementation screenshots/diffs, logs, raw evidence, secrets, runtime state and receipts do not become Context.
-- 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 and Design Authority status.
-- `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.
+- 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 and Design Authority status.
+- `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,56 +1,56 @@
-# 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.
-
+# 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.
 - Reference durable versioned design targets at their project-native path or URI and classify them as `exact-target`, `constraint` or `inspiration`; do not paste generated implementation screenshots, diffs or review logs into Context.
-
-## 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)
+
+## 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)