release: v1.108.65 — surface assemble_task_context/plan_turn composition tools in agent-facing docs

assemble_task_context (single-call, intent-classified, token-budgeted
orchestrator) was absent from every agent-facing surface while plan_turn
was already prominent. Add it to the injected CLAUDE.md/Cursor/Windsurf
policy Opening-move, plus a README "One-call task orchestration"
subsection and a Why-agents-need-this bullet. Pin the new policy term in
test_claude_md_policy.py so the visibility can't silently regress. Docs +
one policy constant; no tool behavior change.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: jgravelle

CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to jcodemunch-mcp are documented here.
 
+## [1.108.65] - 2026-06-20 - Surface the composition tools in agent-facing docs
+
+### Changed
+
+- **`assemble_task_context` is now surfaced as the single-call task
+  orchestrator** across the agent-facing surfaces, alongside `plan_turn`. The
+  injected CLAUDE.md / Cursor / Windsurf policy (`_CLAUDE_MD_POLICY`) gains an
+  "Opening move" step describing `assemble_task_context` — natural-language task
+  in, intent-classified token-budgeted source-attributed capsule out, running the
+  intent-appropriate tool sequence end-to-end in one request rather than chaining
+  primitives by hand. The README's "What you get" adds a **One-call task
+  orchestration** subsection (`assemble_task_context` / `plan_turn` /
+  `get_ranked_context`) and a matching "Why agents need this" bullet. Docs +
+  policy-constant only; no tool behavior change. `test_claude_md_policy.py` pins
+  the new policy term so the visibility can't silently regress.
+
 ## [1.108.64] - 2026-06-20 - Logging honors the log_file / log_level config keys
 
 ### Changed

CLAUDE.md

@@ -1,6 +1,7 @@
 # jcodemunch-mcp — Project Brief
 
 ## Current State
+- **Version:** 1.108.65 — Surface the composition tools (`assemble_task_context` / `plan_turn`) in agent-facing docs. Answers the "these code-index tools work in isolation" critique (a competitor's launch claim, see memory `reference_competitor_atelier`): the suite already HAS an orchestration layer — `assemble_task_context` (one-call, intent-classified, single-budget capsule) and `plan_turn` (confidence-routed opening move) — it just wasn't legible. `assemble_task_context` was absent from every agent-facing surface; now added to `_CLAUDE_MD_POLICY` (init.py — the injected CLAUDE.md/Cursor/Windsurf policy) "Opening move" as the one-call shortcut, plus a new README "What you get → One-call task orchestration" subsection + "Why agents need this" bullet. `skills.py` SKILL.md already had a "Task orchestration" section (unchanged). Docs + one policy constant; **no tool behavior change**. `test_claude_md_policy.py` REQUIRED_POLICY_TERMS pins `assemble_task_context` so visibility can't regress (the line is full-tier only, so `_filter_policy_for_tools` drops it under core/standard exactly like `plan_turn` — existing filter tests unaffected, 22 pass). Legibility fix, not capability chase ([[feedback_clean_room_innovation]]).
 - **Version:** 1.108.64 — Logging honors the `log_file` / `log_level` config keys. `_setup_logging` read only `args.log_file`/`args.log_level` (argparse defaults baked from `JCODEMUNCH_LOG_FILE`/`JCODEMUNCH_LOG_LEVEL` env), so a path set via `config set log_file <path>` was **inert** — the `log_file` config key existed (DEFAULTS/CONFIG_TYPES/template, "=== Logging ===") but the server never read it. New pure helper `_resolve_log_config(args)` applies one precedence chain: **explicit CLI flag > env var > config key > hardcoded default** (WARNING / stderr); `_add_common_args` `--log-level`/`--log-file` defaults changed `None` so the chain (not argparse) owns env resolution. **Why:** lets the jMunch Console enable server file logging by writing the config key + restarting the server (the server is client-launched, so the Console can't inject an env var into it; and `_setup_logging` ignored config). Purely additive — nothing set anywhere → WARNING+stderr exactly as before; an explicit env/CLI from the launching client still wins over config. `_setup_logging` is the only reader of those args (verified). New `tests/test_v1_108_64.py` (6: default/config-file/config-level/env-overrides-config/cli-wins/uppercased). See [[project_jmunch_console]].
 - **Version:** 1.108.63 — Two composite/contract correctness fixes (both reported by @mmashwani, source-cited). **#338**: `check_edit_safe` + `check_delete_safe` called `check_references(identifier=...)` (singular → flat `import_references`/`content_references`, no `results` key) then iterated the batch-only `ref_out.get("results", [])`, so the identifier content-reference signal (Signal 2/3) was ALWAYS zero — a symbol still referenced by a duck-typed/string-dispatch call site (no import edge, so `find_importers`/Signal 1 misses it too) could return `safe_to_delete`. Fix = both call sites switch to the batch form `identifiers=[target_name]`, producing the grouped `results` shape the loops already expect (external preflight response shape unchanged). **#339**: `find_importers(file_paths=[...], cross_repo=true)` passed `""` into `_find_cross_repo_importers` for multi-file batches. That helper is **package-level** (it resolves the repo's package importers and ignores its `file_path` arg entirely), so a multi-file batch either dropped the evidence or implied per-file precision that doesn't exist; now **fails closed** with a clear error (`_meta.cross_repo_scope=package`, `file_count`) pointing at singular calls, while a single-element `file_paths` batch is still honored (== singular path). Docstring + `server.py` schema for `find_importers.cross_repo` document the constraint. New `tests/test_v1_108_63.py` (7): content-reference blocking on delete/edit + no-false-positive orphan guard + cross-repo batch contract (multi-file errors, single-file allowed, no-cross-repo + singular unaffected). 165 passed across the four affected suites + new file. Shipped to PyPI. See [[project_community_mmashwani]]. **#340 (bounded-source mode for `get_symbol_source`) accepted-in-principle, deferred to a follow-up — enhancement w/ API-surface design choices.**
 - **Version:** 1.108.62 — Index templating-language files over a supported underlying source language (#336, PR #337 by @horknfbr). Files of the form `name.<underlying-ext>.<engine-ext>` (Jinja2 template of TypeScript `foo.ts.j2`, Jinja of Python `service.py.jinja`, Twig of TS `widget.ts.twig`) were dropped at discovery as `wrong_extension` (`get_language_for_path` resolved the compound from the first dot → `.ts.j2` unregistered → `None`), so every real source symbol inside went unindexed. Now recognized: engine constructs are **masked offset-preserving** (each `{{ }}`/`{% %}`/`{# #}` hole → same-length `_` filler, newlines kept) and the body is re-parsed as its underlying language via recursive `parse_file()`, so symbols/signatures/imports/line+byte positions all resolve with **no block re-wrapping** (simpler than the Astro/Razor sub-block extractors). **Engines:** Jinja2 (`.j2`/`.jinja`/`.jinja2`) + Twig (`.twig`); pluggable `TemplateEngine` registry in new `parser/template_shared.py` (single-extension HTML-bodied engines can be added on demand). Underlying language inferred from the **middle extension** by stripping the engine suffix and resolving the remainder recursively — so every supported language works as the body with no per-language work. **Discovery guard:** the strip/recurse step in `get_language_for_path` sits *after* the compound + last-extension checks and fires only for registered engine extensions, so it can only ever turn `None` into a language, never re-resolve a `.d.ts`/`.test.ts`/`.blade.php` (non-collision tests included). `{% macro %}`/`{% block %}` definitions additionally surfaced as symbols, **reusing** `sql_preprocessor.extract_dbt_directives` (generalized to take a `directive_keywords` set; the default dbt set stays byte-identical) rather than a parallel regex. `repo` forwarded into the recursive body parse so the underlying language honors per-project `.jcodemunch.jsonc` gating. **Purely additive — previously-skipped files only add symbols, no `INDEX_VERSION` bump** (a re-index picks up the now-recognized files). New `parser/template_shared.py`; `extractor.py` `_parse_template_symbols`; `imports.py` template branch; `languages.py` `template_underlying_language` + `_TEMPLATE_LANG_SPEC`. New `tests/test_templates.py` (17 cases) + fixtures; `LANGUAGE_SUPPORT.md` updated. Verified pre-merge against the PR branch: 17/17 template tests + 607-case parser/sql/dbt/astro/razor/languages/importers sweep all green, dbt path byte-identical. Shipped to PyPI (first contributor template-language feature). See [[project_jcm_336_template_indexing]].

README.md

@@ -226,6 +226,7 @@ jCodeMunch fixes that by giving them a structured way to:
 * fall back to text search when structure alone is not enough
 * detect dead code, trace impact, rank by centrality, and map git diffs to symbols
 * plan the next turn with `plan_turn` — confidence-guided routing before the first read
+* assemble a whole task's context in one call with `assemble_task_context` — intent-classified, multi-tool, single token budget
 * track session state and avoid re-reading files the agent already explored
 
 Agents do not need bigger and bigger context windows.
@@ -248,6 +249,16 @@ Inspect repository structure and file outlines before asking for source.
 
 Send the model the code it needs, not 1,500 lines of collateral damage.
 
+### One-call task orchestration — the tools compose, they don't sit in isolation
+
+The retrieval primitives below are not a disconnected bag of tools the agent has to wire together by hand. Two composition tools drive the rest:
+
+- **`assemble_task_context`** takes a natural-language task and returns a single source-attributed context capsule under a token budget. It auto-classifies the task into one of six intents (explore / debug / refactor / extend / audit / review), auto-extracts the anchor symbols, and runs the intent-appropriate sequence of the tools below end-to-end — so the agent gets the whole context for a task in **one request** instead of chaining five. Every entry is tagged with its `stage` and `source_tool`, so the provenance is auditable.
+- **`plan_turn`** is the opening move: it analyzes the query against the index and returns a confidence-guided route — which tools to call, on which symbols, under a turn budget — *before* the first read. Low confidence means "this probably doesn't exist," so the agent stops instead of burning a budget hunting for a feature that isn't there.
+- **`get_ranked_context`** packs the most relevant symbols for a query into a fixed token budget (BM25 + PageRank), when you want a ranked context pack rather than a full intent sequence.
+
+The point: jCodeMunch is structured retrieval *with* an orchestration layer over it, not a pile of primitives. The composition tools run the right sub-tools, in the right order, under one budget, in one call.
+
 ### Structural queries native tools can't answer
 
 `find_importers` tells you what imports a file. `get_blast_radius` tells you what breaks if you change a symbol, with depth-weighted risk scores and optional source snippets. `get_class_hierarchy` traverses inheritance chains. `get_call_hierarchy` traces callers and callees N levels deep using AST-derived call graphs, with optional LSP-enriched dispatch resolution for interface/trait method calls. `find_dead_code` finds symbols and files unreachable from any entry point. `get_untested_symbols` finds functions with no evidence of test-file reachability — the intersection of import-graph analysis and test-file detection. `get_changed_symbols` maps a git diff to the exact symbols that were added, modified, or removed. `get_symbol_importance` ranks your codebase by architectural centrality using PageRank on the import graph. `get_hotspots` surfaces the riskiest code by combining complexity with git churn. `get_dependency_cycles` detects circular imports. `get_coupling_metrics` measures module coupling and instability. `get_tectonic_map` discovers the logical module topology by fusing three coupling signals (imports, shared references, git co-churn) — revealing hidden module boundaries, misplaced files, and god-module risk without any configuration. `get_signal_chains` traces how external signals (HTTP requests, CLI commands, scheduled tasks, events) propagate through the codebase via the call graph — discovery mode maps all entry-point-to-leaf pathways and reports orphan symbols, lookup mode tells you which user-facing chains a specific symbol participates in (e.g. "validate_email sits on POST /api/users and cli:import-users"). These are not "faster grep" — they are questions grep cannot answer at all.

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "jcodemunch-mcp"
-version = "1.108.64"
+version = "1.108.65"
 description = "Token-efficient MCP server for source code exploration via tree-sitter AST parsing"
 readme = "README.md"
 requires-python = ">=3.10"

src/jcodemunch_mcp/cli/init.py

@@ -60,6 +60,7 @@
    - `high` → go directly to recommended symbols, max 2 supplementary reads
    - `medium` → explore recommended files, max 5 supplementary reads
    - `low` → the feature likely doesn't exist. Report the gap to the user. Do NOT search further hoping to find it.
+3. **One-call shortcut for a concrete task** — `assemble_task_context { "repo": "...", "task": "..." }` returns a single token-budgeted, source-attributed context capsule. It auto-classifies the task (explore / debug / refactor / extend / audit / review), auto-extracts anchor symbols, and runs the intent-appropriate sequence of the tools below end-to-end — so you get the whole context in one request instead of chaining the primitives by hand. Prefer it over a manual chain when the task is well-defined; fall back to step 1's routing when you need to decide *whether* the feature exists first.
 
 **Interpreting search results:**
 - If `search_symbols` returns `negative_evidence` with `verdict: "no_implementation_found"`:

tests/test_claude_md_policy.py

@@ -5,6 +5,7 @@
 # All required terms that must be present in _CLAUDE_MD_POLICY
 REQUIRED_POLICY_TERMS = [
     ("plan_turn", "plan_turn tool for routing"),
+    ("assemble_task_context", "assemble_task_context single-call orchestrator"),
     ("negative_evidence", "negative_evidence for empty results"),
     ("high", "high confidence level"),
     ("medium", "medium confidence level"),