chore: prepare 0.7.3 patch release

AGENTS.md

@@ -75,13 +75,19 @@ Prefer modern typing syntax:
 
 ## PR guidance
 - Never open or merge a PR targeting `main` from `main`; always use a feature branch.
+- Always use the repository PR template when creating or updating PR descriptions.
 - PR titles must use the same format as commits: `<type>: <summary>`.
 - PR descriptions should include:
   - what changed
   - why the change was needed
 - Do not include a dedicated "Validation" section in PR text.
 - Keep PR scope aligned to the requested task; if scope grows, ask for guidance before expanding.
 
+## Issue guidance
+- Always use the repository issue templates when creating or updating issues.
+- Use `bug_report` for defects and regressions.
+- Use `feature_request` for new capabilities or enhancements.
+
 ## CI
 Do not modify GitHub CI workflows unless explicitly asked.
 
@@ -105,6 +111,10 @@ Prefer plain, concrete wording when accurate. Examples:
 
 Avoid describing features only in architectural terms when a behavior-first explanation is possible.
 
+Prefer direct subjects and strong verbs.
+Avoid noun stacks and passive phrasing when a simpler active sentence is clearer.
+Use simpler wording unless technical precision requires formal terminology.
+
 Specification and contract documents are different:
 - preserve precise terminology
 - preserve unambiguous behavioral guarantees

README.md

@@ -4,11 +4,11 @@
 [![Python versions](https://img.shields.io/pypi/pyversions/context-compiler)](https://pypi.org/project/context-compiler/)
 [![License](https://img.shields.io/pypi/l/context-compiler)](https://pypi.org/project/context-compiler/)
 
-Some behaviors require explicit host-side state machinery.
+Some behaviors require explicit host-side state handling.
 
 Context Compiler is a deterministic host-side state layer for LLM applications.
-It handles explicit state transitions for premise and policies so that mutation
-rules are fixed and repeatable.
+It applies explicit premise and policy updates so state changes stay fixed and
+repeatable.
 
 ## What prompting and reinjection can do
 
@@ -23,17 +23,17 @@ pending confirmations from checkpoints.
 ## What prompting cannot do by itself
 
 Prompt text (including reinjected state text) helps, but it does not give your
-app controlled rules for when state can change. By itself, it does not provide:
+app clear rules for when state can change. By itself, it does not provide:
 
 - rules your app controls for state changes
 - replacement precondition checks (`use X instead of Y` when `Y` may be absent)
 - confirmation flows that must complete before anything else changes
-- clear decisions about when a change is blocked
+- clear rules for when to block a change
 - reliable checkpoint restore for both saved state and pending confirmation flow
 
 ## What Context Compiler provides
 
-Context Compiler provides fixed host-side state machinery:
+Context Compiler provides fixed host-side state handling:
 
 - deterministic directive handling for explicit user state changes
 - clarification instead of silent overwrite for blocked/ambiguous changes

docs/DescriptionAndMilestones.md

@@ -10,9 +10,9 @@ conversations, and state can conflict over time.
 This project adds a deterministic state layer that is independent of the model.
 The model handles interpretation and generation; the engine handles premise and
 policies. Only explicit user directives can change state.
-By separating reasoning from state ownership, the system improves reliability
-without requiring model retraining. The system never derives authoritative state
-from model responses.
+When the model reasons and the engine owns state, behavior stays reliable
+without retraining the model. The system never derives authoritative state from
+model responses.
 The goal is not to make the model smarter, but to make interactions
 predictable: once a statement is corrected or scoped, future responses
 must respect that change.
@@ -64,7 +64,7 @@ After correcting or constraining the assistant once, the behavior remains consis
 ### M3 — Cross-Session Recall (implemented, engine-level / host-enabled)
 
 **Goal**
-Extend app-level workflows around persisted exported state safely and intentionally.
+Help apps safely reuse saved exported state.
 
 **Core capability:**
 
@@ -77,8 +77,8 @@ Extend app-level workflows around persisted exported state safely and intentiona
 
 **Deliverables:**
 
-- App-side storage/recovery patterns built on the existing import/export API
-- App-side storage/recovery patterns for checkpoint object/checkpoint JSON continuation restore
+- App-side storage and recovery patterns built on the existing import/export API
+- App-side storage and recovery patterns for checkpoint object and checkpoint JSON restore
 
 **User-visible outcome:**
 

docs/DesignPhilosophy.md

@@ -2,7 +2,7 @@
 
 ## The Problem with Implicit State
 
-Modern LLM applications typically manage conversational state implicitly — the model reads the transcript, infers what constraints are active, and generates a response accordingly. This works well for short conversations and simple tasks.
+Modern LLM applications often manage conversational state implicitly: the model reads the transcript, infers active constraints, and generates a response. This works well for short conversations and simple tasks.
 
 It breaks down reliably in longer conversations, correction flows, and multi-turn constraint management. Constraints drift. Corrections get partially applied or treated as additive rather than authoritative replacements. Contradictions accumulate instead of resolving. The model interprets intent rather than enforcing it.
 
@@ -16,7 +16,7 @@ Explicit state management is not a new idea. Earlier AI systems maintained struc
 
 The core insight is simple: maintain an explicit active set of rules rather than inferring the relevant context from history each time. What is in the active set is known with certainty. What is not in it is not active.
 
-These approaches succeeded in narrow, well-defined domains precisely because explicit state gives you guarantees that implicit inference cannot. The limitation was not the state management approach — it was that handling natural language and ambiguity was extraordinarily difficult. Those problems consumed most of the design effort.
+These approaches succeeded in narrow, well-defined domains because explicit state gives guarantees that implicit inference cannot. The limitation was not state management itself. Handling natural language and ambiguity was the hard part, and that work consumed most of the design effort.
 
 Modern LLMs handle natural language interpretation and generation far more effectively than earlier systems. This changes the calculus: the language interface problem is largely addressed. As end-to-end neural approaches became dominant, many systems shifted toward transcript-driven implicit state management, assuming a capable model could handle state implicitly.
 
@@ -26,8 +26,8 @@ That assumption is incorrect in practice, for the structural reason described ab
 
 Context Compiler applies explicit state management to the modern LLM context, with a clear division of responsibilities:
 
-- The LLM handles what it is genuinely good at — language understanding, reasoning, generation, handling ambiguity in user intent
-- The deterministic engine handles what probabilistic systems handle poorly — maintaining explicit state across turns, enforcing constraints, guaranteeing that corrections replace rather than compete with prior state
+- The LLM handles what it does well: language understanding, reasoning, generation, and ambiguity in user intent
+- The deterministic engine handles what probabilistic systems handle poorly: keep explicit state across turns, enforce constraints, and make corrections replace prior state instead of competing with it
 
 The preprocessor layer bridges the two: it uses the LLM's language understanding to translate natural language directive intent into canonical form, which the deterministic engine can then process reliably. Fuzzy where it needs to be fuzzy, deterministic where determinism matters.
 

docs/llm-preprocessor.md

@@ -15,8 +15,7 @@ layer. Do not rely on repo-relative preprocessor paths.
 
 ## Architectural framing
 
-The preprocessor is a helper layer in your app, not the source of truth for
-state changes.
+The preprocessor helps your app, but it does not own state changes.
 
 Model/tool-description translation can help with simple direct cases, but
 integrations should not rely on model intent translation alone to decide when
@@ -25,18 +24,18 @@ state changes.
 In simpler hosts without an embedded model, this preprocessor provides a
 conservative translation path.
 
-In model-assisted hosts, the app still checks outputs before applying them.
+In model-assisted hosts, the app still validates outputs before applying them.
 
 Both paths send canonical directives to the same deterministic engine. The
-engine still controls state updates.
+engine controls state updates.
 
 In MCP/tool-calling environments, over-eager tool calling on conversational or
 ambiguous input is a known failure mode. Conservative preprocessing and
 validation help reduce unintended mutation.
 
 ## Required flow
 
-Recommended conceptual flow:
+Recommended flow:
 
 1. heuristic preprocessing
 2. validate candidate output

docs/multi-engine.md

@@ -73,13 +73,13 @@ Introduce multiple engines only when you need **independent lifecycle or isolati
 ## Combining Policies from Multiple Sources
 
 If you need to combine constraints from separate sources, do it explicitly in
-host code by replaying directives through `step(...)` into a target engine.
+host code: replay directives through `step(...)` into a target engine.
 
 Pattern:
 
 1. Select ordered source directives
 2. Replay each directive via `engine.step(...)`
 3. Handle any returned `clarify` decisions explicitly
 
-This keeps conflict handling in normal engine semantics and avoids adding merge
-semantics to core state APIs.
+This keeps conflict handling in normal engine behavior and avoids adding merge
+rules to core state APIs.

examples/integrations/README.md

@@ -29,7 +29,7 @@ See the LiteLLM examples README for setup and usage:
 - Context Compiler runs before each LLM call.
 - If result is `clarify`, show the question and do not call the LLM.
 - If result is `passthrough`, send normal user input.
-- If result is `update`, use updated state and call the model with saved state added to the prompt.
+- If result is `update`, use updated state and call the model with saved state in the prompt.
 
 ## LiteLLM Proxy
 

examples/integrations/litellm/README.md

@@ -105,7 +105,7 @@ Use `llama` only for LLM-only preprocessing with Llama-family models.
 
 ## Usage pattern
 
-These files are importable integration references for host applications.
+You can import these files as integration references in host applications.
 
 - Import `handle_turn(...)` from either `basic.py` or `with_preprocessor.py`.
 - Create and retain an engine instance in host/session state.

examples/integrations/litellm_proxy/README.md

@@ -1,7 +1,7 @@
 # LiteLLM Proxy (pre-call hook)
 
 This example shows how to run Context Compiler inside a LiteLLM proxy pre-call hook.
-The hook applies fixed state handling before any upstream model call.
+The hook applies fixed state rules before any upstream model call.
 
 Available hook files:
 

examples/integrations/openwebui/README.md

@@ -1,9 +1,9 @@
 # Open WebUI Pipe Integration
 
-Examples of Open WebUI Pipe Functions that run Context Compiler.
+Examples of Open WebUI Pipe Functions that use Context Compiler.
 
 Tested target: Open WebUI `v0.8.12` (latest at time of testing).
-Runtime-validated on stock Docker Open WebUI with a real backend model provider.
+Validated at runtime on stock Docker Open WebUI with a real backend model provider.
 
 Compatibility note: OpenWebUI `0.9.x` changed `Users.get_user_by_id` to async.
 These examples support both sync (`0.8.x`) and async (`0.9.x`) user lookup.
@@ -49,11 +49,11 @@ If using `open_webui_pipe_with_preprocessor.py`:
 - Optional: set `PREPROCESSOR_MODEL_ID` to route fallback precompilation through
   a separate model. If unset, fallback uses `BASE_MODEL_ID`.
 - Fallback routing is Open WebUI-native (no LiteLLM dependency for this pipe).
-- The heuristic preprocessor is intentionally conservative/high-precision and
+- The heuristic preprocessor is intentionally conservative and high-precision, and
   may abstain on mixed-prose natural language (for example, `i think we should
   use docker`). In those cases, behavior may remain passthrough unless fallback
   precompilation returns a validated canonical directive.
-- Invalid configured model ids return explicit runtime misconfiguration errors:
+- If you configure invalid model ids, the pipe returns explicit runtime errors:
   - `BASE_MODEL_ID` not found in Open WebUI models
   - `PREPROCESSOR_MODEL_ID` not found in Open WebUI models
 
@@ -80,7 +80,7 @@ Use the Open WebUI model picker/list to copy exact model ids for `BASE_MODEL_ID`
 - No Redis/DB/external storage.
 - No Filters or Pipelines.
 - No production hardening.
-- Version-coupled to Open WebUI internal helper/import paths.
+- Tied to Open WebUI internal helper/import paths by version.
 
 ## Manual Validation
 

experimental/preprocessor/README.md

@@ -1,12 +1,12 @@
 # Experimental Preprocessor Package
 
-This package provides optional app-layer preprocessing utilities for Context
-Compiler integrations.
+This package provides optional preprocessing helpers for app integrations with
+Context Compiler.
 
 It is experimental and separate from the deterministic core engine in `src/`.
 
-Model/tool-description translation can help with simple direct cases, but raw
-model output is not safe by itself for state changes. The app must validate
+Model or tool-description translation can help in simple direct cases, but raw
+model output is not safe for state changes on its own. The app must validate
 outputs before applying them.
 
 In MCP/tool-calling environments, over-eager tool calling on conversational or
@@ -65,7 +65,7 @@ Raw preprocessor/LLM outputs must not be passed directly to the compiler.
 Raw model output must never directly change state.
 
 The preprocessor does not expand directive grammar. It may emit only validated
-canonical directives accepted by the compiler.
+canonical directives that the compiler accepts.
 
 Conservative boundary policy:
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "context-compiler"
-version = "0.7.2"
+version = "0.7.3"
 description = "Deterministic conversational state engine for LLM applications."
 readme = "README.md"
 requires-python = ">=3.11"