purecontext-mcp 1.13.0 → 1.14.0

package/AGENT_REFERENCE.md

@@ -192,7 +192,7 @@ Directory tree with file counts. Use when you need to understand the project's f
 Find all usage sites for a symbol across the repo. Use before renaming or modifying a symbol.
 
 ### `get_task_context`
-Assemble a focused context bundle from a natural-language task description — the symbols and files most relevant to the work. The cold-start orientation front door. In the default `mode:"associative"` it discovers seed symbols, then **walks the real dependency + co-change graph** (imports, callers, historically co-changing files), so a structurally essential but lexically dissimilar symbol can be surfaced — not just keyword matches. Each item carries a `role` derived from the graph edge (`dependency`/`caller`/`historical`/`primary`) and `provenance`; the result adds `evidenceGaps` (`lowConfidenceSeeds`/`droppedByBudget`/`unselectedCoChange`) and `suggestedProbes[]` so you can decide whether to probe further. Works with zero embeddings (ranks by graph provenance). Pass `mode:"flat"` for legacy single-pass similarity. Fanout is governed by config `taskContext.*`.
+Assemble a focused context bundle from a natural-language task description — the symbols and files most relevant to the work. The cold-start orientation front door. In the default `mode:"associative"` it discovers seed symbols, then **walks the real dependency + co-change graph** (imports, callers, historically co-changing files), so a structurally essential but lexically dissimilar symbol can be surfaced — not just keyword matches. Each item carries a `role` derived from the graph edge (`dependency`/`caller`/`historical`/`primary`) and `provenance`; the result adds `evidenceGaps` (`lowConfidenceSeeds`/`droppedByBudget`/`unselectedCoChange`) and `suggestedProbes[]` so you can decide whether to probe further. Works with zero embeddings (ranks by graph provenance). Pass `mode:"flat"` for legacy single-pass similarity. Fanout is governed by config `taskContext.*`. **Note:** with no embeddings configured, seed discovery is FTS token-based — a pure natural-language task with no terms shared with indexed symbols returns no seeds (it says so in `suggestedProbes`); include a real symbol/term, configure embeddings, or fall back to `search_symbols`/`search_semantic`.
 
 ---
 

package/CHANGELOG.md

@@ -11,6 +11,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.14.0] - 2026-06-29
+
+### Changed
+
+**Agent instructions now teach the change-safety workflow.** The always-on rules that `install` writes into every IDE (Cursor, Windsurf, Cline, Copilot, Continue, Claude) previously covered only navigation. They now teach the full close-the-loop workflow introduced in 1.8.0–1.13.0:
+
+- **Orient** with `get_task_context`, then **before editing** run `prepare_change` (existing code) or `check_consistency` (new code), **edit**, **refresh** with `index_file`, **verify** with `verify_change`, and gate a merge with `merge_readiness`.
+- The gate-envelope contract (`{ gate: "pass" | "warn" | "block" }`) and the `index_file`-not-`index_folder` mid-task freshness rule are now explicit.
+
+This makes the tools shipped in 1.8.0–1.13.0 discoverable to agents — previously they existed but the installed guidance never mentioned them.
+
+**Agent rules are now single-sourced** from `assets/agent-rules.md` (shipped in the package). The `install` command reads it at runtime, so the rules can no longer drift from a hardcoded copy.
+
+### Documentation
+
+- Documented the full tool surface for 1.10.0–1.13.0 that was missing from the public docs: `index_file`, `check_index_staleness`, `check_consistency`, `merge_readiness`, the gate envelope, `get_task_context` associative mode, the `index-file` CLI subcommand, and the `consistency.*` / `taskContext.*` config blocks.
+- Noted `get_task_context`'s no-embeddings behavior: seed discovery falls back to FTS token matching, so a pure natural-language task that shares no tokens with indexed symbols returns no seeds (reported in `suggestedProbes`) — configure embeddings, phrase with real terms, or fall back to `search_symbols`.
+
+---
+
 ## [1.13.0] - 2026-06-28
 
 ### Added

package/assets/agent-rules.md

@@ -5,7 +5,7 @@ Use PureContext MCP tools to read and change code. Never read whole files to fin
 ### Mandatory workflow
 
 1. **Start every session**: `list_repos()` → get `repoId` (required for all tools). Not indexed? `index_folder({ path })`.
-2. **Orient on a task**: `get_task_context({ repoId, task })` → the symbols and files most relevant to the work, walked over the real dependency + co-change graph (not just keyword matches), plus `evidenceGaps` for what you haven't seen yet.
+2. **Orient on a task**: `get_task_context({ repoId, task })` → the symbols and files most relevant to the work, walked over the real dependency + co-change graph (not just keyword matches), plus `evidenceGaps` for what you haven't seen yet. If it returns nothing, your task text shares no terms with indexed symbols and no embeddings are configured — name a real symbol/term, or fall back to `search_symbols`/`search_semantic`.
 3. **Find code**: `search_symbols` (by name) → read `summary`/`signature` → `get_symbol_source` only for what you'll edit. `search_semantic` for concepts, `search_text` for literals.
 
 ### Changing code safely — close the loop

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "1.13.0";
+export declare const VERSION = "1.14.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,2 +1,2 @@
-export const VERSION = '1.13.0';
+export const VERSION = '1.14.0';
 //# sourceMappingURL=version.js.map

package/docs/06-tools-reference.md

@@ -796,6 +796,8 @@ Assemble a focused context bundle for a natural-language task description (the s
 
 Fanout is governed by config `taskContext.{seedCount, expansionDepth, maxPool, maxCoChangePartners, maxSymbolsPerPartner}`.
 
+**No-embeddings behavior:** seed discovery falls back to FTS token matching when no embedding provider is configured. A pure natural-language task that shares no tokens with indexed symbol names returns no seeds (reported in `suggestedProbes`). For best results either configure embeddings, phrase the task with real symbol/domain terms, or fall back to `search_symbols` / `search_semantic`.
+
 ---
 
 ## Distribution Tools

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "purecontext-mcp",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "Change-aware code intelligence for AI coding agents (MCP): blast radius, temporal co-change, and per-symbol risk before the edit — built on token-efficient code navigation",
   "type": "module",
   "license": "MIT",