Tensor Grep Add Language

tensor-grep: adding a language to the symbol graph

The registration checklist for extending tensor-grep's tree-sitter symbol graph (defs/refs/callers/blast-radius/tg source/tg imports) to a new language. Ground-truthed directly against src/tensor_grep/cli/lang_registry.py (full file), lang_go.py, lang_php.py, and lang_csharp.py (the three shipped module-shaped languages), and src/tensor_grep/cli/repo_map.py's real dispatch sites — not from memory or the session ledger alone. Sibling of tensor-grep-architecture-contract, scoped to one subsystem (the symbol-graph tier), not the front door / routing / backend contract.

When to use this skill vs. a sibling

Current status (verified against tg v1.110.14, origin/main @ a6242bb)

repo_map.py currently carries 10 lang_registry.register_language(...) call sites (grep -n "register_language(" src/tensor_grep/cli/repo_map.py): python, javascript, typescript, rust (the original four, inline in repo_map.py), plus go, java, php, csharp, c, and cpp — confirmed via language_id= greps and tests/unit/test_lang_registry.py::test_language_registry_has_exactly_the_stage2_languages's literal set-pin (which now includes "c" and "cpp"). All top-10 languages are now registered — the "C/C++ deferred" framing below this line in earlier passes of this skill is STALE; C landed via PR #731 (v1.97.0) and C++ via PR #732 (v1.98.0), each a self-contained module (lang_c.py/lang_cpp.py, mirroring lang_go.py's shape), both at the same foundational tier as Java/PHP/C# (defs/imports only, no references_and_calls). A follow-up C fix (#736, v1.98.2) corrected a file-scope function-pointer-variable mis-kind - see B5's declarator-shape addendum below before writing similar C/C++ declarator-walking logic. SUPERSEDED 2026-08-04 by Task 10E (C++, the final wave of the top-10 language-support campaign): the "foundational tier" claim in the paragraph above is now STALE for every language named in it. Java (10A), C# (10B), PHP (10C), C (10D), and now C++ (10E) all carry a real references_and_calls extractor; repo_map._symbol_navigation_descriptor() reports 10 parser-backed / 0 foundational — the foundational tier is EMPTY. lang_cpp.py's new cpp_references_and_calls extends C's bare-identifier-call confirmation with three C++-only shapes (qualified calls Foo::bar(), explicit this->method(), and new Widget() as a ref_kind="constructor" reference) but DELIBERATELY does not attempt Java/C#/PHP-style general receiver-type confirmation (w.method(), p->method()) — C++'s real inheritance and auto make that walk unsound for the common case; see lang_cpp.py's own "TASK 10E CALL/ ACCESS NODE SHAPES" / "RESOLUTION CONFIDENCE" docstring block for the full reasoning. Re-run the one-liner rather than trust this paragraph either.

SUPERSEDED (append-only, do not edit the paragraph above) - 2026-08-11, Task 10E final wave: C and C++ are now PARSER-BACKED too; _symbol_navigation_descriptor() returns 10 parser-backed (c, cpp, csharp, go, java, javascript, php, python, rust, typescript) and the foundational tier is EMPTY. The "same foundational tier as Java/PHP/C#" claim above is accurate-as-dated (v1.98.x) history; the tier split has since moved to 10/0 and is pinned by tests/unit/test_lang_registry.py. Re-run the grep above before trusting any "N of top-10" count - it is a snapshot, not a promise; this count has changed on every pass of this skill so far.

(2026-08-12 maintenance note: the two SUPERSEDED blocks above were reordered on this date to restore append-only chronology — the 2026-08-11 entry had been placed ABOVE the 2026-08-04 entry despite the append-only (newest-last) instruction. Both blocks describe the same 10/0 terminal state; all dated content was preserved verbatim, only the order changed: oldest first, newest last.)

The tiered language model (unchanged shape, re-verify the coverage numbers):

Positioning: tg = rg (text) + ast-grep (structural) + this symbol/retrieval/capsule layer — "not faster grep" (mirrors tensor-grep-architecture-contract's moat framing). Top-10 ranking (TIOBE Jul-2026 + Stack Overflow 2025 + GitHub Octoverse 2025 consensus): Python, JavaScript, TypeScript, Java, C#, C++, C, Go, Rust, PHP.

B1 — the pattern: register_language + a lang_<x>.py module

The current, correct pattern for a NEW language is a self-contained src/tensor_grep/cli/lang_<x>.py module (clone lang_go.py) that ends in a lang_registry.register_language(LanguageSpec(...)) call from repo_map.py. This is not the inline _rust_* / _parser_for_source_suffix machinery still visible in repo_map.py for Rust and Python — that style predates the registry (Stage 0's pure-parity refactor wrapped it, it did not replace it). Java is the one exception that used inline-in-repo_map.py (_java_imports_and_symbols etc. — grep -n "^def _java_imports_and_symbols" src/tensor_grep/cli/repo_map.py, was :4782, now :4783) and still registers through lang_registry — both shapes are contract-consistent, but the module shape is what Go, PHP, and C# (the three most recent additions) all converged on, and is what lang_go.py's own docstring recommends: it keeps repo_map.py from growing further.

One-directional import rule (stated in both lang_registry.py's module docstring — grep -n "never the reverse" src/tensor_grep/cli/lang_registry.py, was :10-12, now :10-11 — and lang_go.py:9-15): repo_map.py → lang_<x>.py, never the reverse. A helper the new module needs that repo_map.py already has must be duplicated locally (see lang_go.py:44-87's (was cited :37-87, re-grep grep -n "Duplicated tiny helpers" to relocate the block if this drifts again) byte-identical-to-repo_map.py tiny helpers), not imported — importing back creates a cycle.

LanguageSpec (grep -n "class LanguageSpec" src/tensor_grep/cli/lang_registry.py — was :67-111, now :72-119; frozen dataclass) is the single contract. Fields worth knowing before writing one:

register_language() is idempotent (grep -n "def register_language" src/tensor_grep/cli/lang_registry.py — was :118-128, now :126-136) — re-registering the same language_id replaces the entry and re-derives every suffix pointer, so a stale mapping never survives a reload. LANGUAGE_REGISTRY starts empty (grep -n "^LANGUAGE_REGISTRY" src/tensor_grep/cli/lang_registry.py — was :114, now :122) until whatever module calls register_language(...) is imported — a bare import lang_registry with no import repo_map gets an empty dict (see "Fast self-check" below).

B2 — the critical seams (miss silent half-integration)

Enumerate every seam lang_go.py touches and hit all of them. These are re-verified repo_map.py locations on v1.96.1-pending (re-grepped fresh after PR #728 inserted a 16-line go/php/csharp dispatch block inside _imports_with_lines_for_path, shifting every seam below it by +16 — except build_file_imports, which shifted +41, because a 12-line frozenset addition and a 13-line _resolve_raw_import_entry branch both land between it and seam 6; see B2's worked example below) — re-grep the symbol before trusting the line number on a later version (main.py/repo_map.py churn every release):

Seam 5b is easy to miss precisely because seam 5a's own code comments never mention it — unlike every other seam in this table, nothing in _target_language_for_path points you at _provider_language_for_path. The two functions serve different callers (5a feeds the agent capsule's confidence gate; 5b feeds the LSP-provider dispatch, e.g. clangd-via-LSP for a language whose symbol-graph tier is only foundational or absent) but both must return the SAME language_id for every suffix a LanguageSpec registers, or the dynamic parity test below fails. _provider_language_for_path sometimes ALREADY recognizes a suffix before its LanguageSpec is registered (a latent pre-wiring, not a bug) — e.g. it independently maps .c/.cc/.cpp/.cxx/.h/.hh/.hpp/.hxx to "c"/"cpp" for the LSP provider even before a C or C++ LanguageSpec exists — which means the CHOICE of language_id for a new language is not always free: check _provider_language_for_path for an existing mapping BEFORE naming your new LanguageSpec.language_id, or the two functions will disagree the moment you register it.

Seam 5a is not a hypothesis — the live code says so in its own comments. Reading _target_language_for_path on main today:

if suffix == ".go":
    # MOST-FORGOTTEN seam (PATH A Stage 1 design note): without this, the capsule's
    # query-language-vs-target-language 0.55 confidence cap (agent_capsule.py) never even
    # sees "go" as a candidate target language...
    return "go"
...
if suffix in _JAVA_SUFFIXES:
    # Same MOST-FORGOTTEN seam, Stage 2: without this, `tg agent`'s capsule never reports
    # primary_target_language == "java" for a Java target.
    return "java"
if suffix == ".php":
    # MOST-FORGOTTEN seam (see the ".go" branch above) -- same fix, same reason...
    return "php"

Seam 5b has NO equivalent per-branch comment on main today — it is a plain suffix dispatch (repo_map.py:14711-14739) with no "MOST-FORGOTTEN"-style warning attached to any of its branches, which is exactly why it is the one this skill itself omitted until this pass: nothing in the code nudges you toward it the way seam 5a's comments do.

Worked example, from PR #728, SUPERSEDED by the top-10 C/C++ campaign — seam 6 was closed for go/php/csharp at the FOUNDATIONAL tier first, then C/C++ joined the same frozenset later; re-read this before assuming "in the frozenset" means "fully working," and re-derive the member count rather than trusting either number below. _SUPPORTED_FILE_DEPENDENCY_LANGUAGES (grep -n '_SUPPORTED_FILE_DEPENDENCY_LANGUAGES\s*=' src/tensor_grep/cli/repo_map.py — was :17131, now :17148) on main today is frozenset({"python", "javascript", "typescript", "rust", "java", "go", "php", "csharp", "c", "cpp"}) — all 10 registered languages are now members (this table used to say "all 8" right after #728 landed C/C++ hadn't joined yet; a later "Top-10 language campaign" commit added "c"/"cpp" to the same frozenset with its own inline comment — re-count with the grep above, don't carry either "8" or "10" forward without checking). PR #728 shipped three new per-language extractors — lang_go.go_imports_with_lines, lang_php.php_imports_with_lines, lang_csharp.csharp_imports_with_lines — dispatched from _imports_with_lines_for_path (grep -n "^def _imports_with_lines_for_path" src/tensor_grep/cli/repo_map.py — was :6831, now :6832); each walks the same node kind its *_imports_and_symbols sibling already walks (import_spec / namespace_use_clause / using_directive respectively) and emits one {"module": ..., "line": ...} row per statement. tg imports on a .go/.php/.cs file no longer reports result_incomplete with an empty list the way it did before this PR — it returns real, line-numbered rows.

But resolution — WHICH file/module each row's module string actually points to — is still deferred for all five (go/php/csharp/c/cpp), and it is honestly deferred, never silently faked. _resolve_raw_import_entry (grep -n "^def _resolve_raw_import_entry" src/tensor_grep/cli/repo_map.py — was :17160, now :17177) carries an elif language_id in ("go", "php", "csharp", "c", "cpp") branch (re-grep elif language_id in ( in repo_map.py; currently :17246, mirroring the elif language_id == "java" branch immediately above it, currently :17237-17245 — both numbers already superseded twice across this skill's re-verify passes, re-grep rather than trusting either) that always returns resolved, external, provenance, confidence = None, False, [], 0.0 — every row comes back resolved=None, external=False rather than a fabricated file path or a fabricated external=True. Each language is missing different resolver machinery: Go's own _go_import_path_to_dir (lang_go.py) already resolves an import path to a package directory, not a single file — a Go import names a package that can span many .go files with no 1:1 import-to-file mapping, so picking "the" file needs new design, not just wiring existing code; PHP has no PSR-4/composer.json autoload-map reader; C# has no .csproj/ assembly-reference map; C/C++ have no standardized manifest at all (no go.mod/composer.json/.csproj equivalent). None of that resolver machinery is built yet — see docs/BACKLOG.md for the exact per-language scope still open. The fail-closed contract (B3) still fires exactly as before for any language genuinely outside this frozenset: build_file_imports (grep -n "^def build_file_imports" src/tensor_grep/cli/repo_map.py — was :17271, now :17288) sets result_incomplete=True with incomplete_reason=f"'{language_id}' has no import-resolution support in \tg imports` yet"for any registered-but-unsupported language, and_imports_with_lines_for_path's own docstring (inside the function body, grep -n "unsupported language (e.g. Kotlin)" src/tensor_grep/cli/repo_map.py— was cited:6440, now :6835`) names Kotlin as its worked example of one — go/php/csharp/c/cpp just are not examples of it anymore.

A second, separate gate stays narrower still, and closing seam 6 does not close it too. _confirm_import_edges (grep -n "^def _confirm_import_edges" src/tensor_grep/cli/repo_map.py — was :17350, now :17367; the tg importers reverse-confirm step that turns a prefiltered "maybe imports it" into a confirmed edge) has its own independent language allow-list — if language_id not in ("javascript", "typescript", "rust", "python"): return [] (re-verified unchanged this pass) — which still excludes java, go, php, csharp, c, AND cpp alike. Membership in _SUPPORTED_FILE_DEPENDENCY_LANGUAGES does not imply membership in this second, stricter gate; a future PR that builds true forward resolution for go/php/csharp/c/cpp still would not make tg importers's reverse-confirm step cover them without touching this allow-list too. This is the same "forgot a seam but the honesty floor caught it" lesson as before, one tier deeper: even a foundational landing must decide, per emitted row, whether to fabricate confidence it doesn't have — every landing so far has chosen not to, matching Java's (#725) precedent exactly. True forward resolution for go/php/csharp/c/cpp (and then extending _confirm_import_edges's allow-list) remains a good next PR for whoever reads this skill next.

Two more seams exist beyond this table, found by reading lang_go.py itself rather than the ledger (not independently re-grepped against repo_map.py's call sites this pass — verify before citing a line number): (7) the per-language dispatch arms that call references_and_calls / file_imports_symbol_from_definition directly, which feed tg callers/tg blast-radius; (8) clear_<lang>_repo_context_cache (lang_go.py:449) wired into the daemon-refresh sweep, so tg session refresh doesn't serve stale import-resolution context after a repo change.

B3 — fail-closed contract, extended per-language

• Override provenance_when_missing. The registry default is "regex-heuristic" (grep -n "provenance_when_missing: str" src/tensor_grep/cli/lang_registry.py — was :89, now :94) — true for the original JS/TS/Rust languages, which have a real regex fallback. Every language shipped since (Go, PHP) has no regex fallback and explicitly sets provenance_when_missing="grammar-missing" in its LanguageSpec(...) call. Skipping this override makes a grammar-absent file for the new language read as "zero symbols found" instead of a genuine resolution_gaps entry — a silent lie by omission (lang_go.py:17-24).
• A None callable field is an honest deferral, not a bug — PHP is the shipped precedent. lang_php.py's own docstring states its Stage 1 landing is "deliberately narrower than Go's": it implements extract_imports_and_symbols + parser_symbol_sources only, and registers references_and_calls, file_imports_symbol_from_definition, import_update_target, and prime_repo_context all as None. repo_map.py's _language_coverage_gaps_for_universe already treats import_update_target is None as a resolution_gaps entry — so tg callers/ tg blast-radius stay honest about PHP's current lack of reverse-import resolution instead of reading as a proven zero. You do not have to land every seam in one PR — land a real, honestly-labeled subset, exactly like PHP did.
• Every extractor function returns the empty shape ([] / ([], [])), never raises, when the grammar is missing (every public function in lang_go.py starts with parser = _go_parser(); if parser is None: return <empty>).
• Symbol-kind vocabulary — emit the language's own, do not pre-collapse. Each module emits its native kind strings (Go: "function"/"method"/"struct"/"interface"/ "const"/"var"/"type"). The FULL def-node vocabulary for Go is _GO_DEF_NODE_KINDS (grep -n "_GO_DEF_NODE_KINDS" src/tensor_grep/cli/lang_go.py — this spot was cited as lang_go.py:110-113, which is only _GO_TYPE_SPEC_KIND_BY_TYPE_FIELD, the struct/interface sub-mapping applied INSIDE a type_spec; the full set now lives at :117-123, with the kind emission sites at :290 (const/var), :397 (function), :400 (method), and the type_spec branch defaulting to "type"). A later normalization layer (not independently re-verified this pass — presumably in repo_map.py) is what the ledger records as the cross-language collapse: class/interface/struct/enum/record/trait → "class"; method/constructor/function → "function". Emit the real vocabulary in the new module; re-verify where the collapse actually happens before assuming its exact shape.
• resolution_confidence banding is the same fail-closed principle per-match. go_references_and_calls (lang_go.py:711) bands 0.95 for a confirmed resolution (resolution_provenance=["go-import-resolution"]) vs. 0.7 "receiver-heuristic" for a textually-plausible-but-statically-unconfirmed one (lang_go.py:820) — an unconfirmed match is demoted, never dropped. This is the per-match instance of the Backend Fail-Closed Contract: never fabricate certainty.

B4 — verify the plan against current code before dispatch

A real onboarding brief this session said "mirror inline _rust_*" — stale, because the repo had already grown lang_registry.py and the module pattern since that mental model formed. All three build agents that received the brief independently caught it via the verify-plan-against-code discipline before writing code, and corrected to the module shape. Rule: before dispatching an add-a-language plan — to a subagent, codex, cursor, or your own future self — re-read lang_registry.py plus the most recently added lang_<x>.py sibling fresh. Do not trust a memory, an old skill snapshot (including this one — see the "Fast self-check" below), or a prior session's summary about which shape is current.

B5 — live-verify grammar node shapes before writing extraction logic

Do not guess a node shape from documentation, another language's grammar, or intuition — dump the real parse tree. lang_go.py shipped with at least three node-shape surprises found exactly this way, each pinned by an inline F<n> fix comment — worked, re-verified proof this step cannot be skipped:

• Generic receiver type nesting (lang_go.py:126-159, F8 fix): func (r *MyType[T]) M() parses the receiver's type as a generic_type node whose raw text is "MyType[T]" — never matching the plain "MyType" a type_spec declares, unless you descend into generic_type's own type field.
• Grammar-version-dependent content node (lang_go.py:162-189, F11 fix): a recent tree_sitter_go exposes interpreted_string_literal_content as a child of an import path; an older/differently-built grammar can omit it — silently zeroing out every import in the file with no error and no resolution_gaps entry (the parser loaded fine, so nothing marks a gap). Fix: fall back to quote-stripping the raw node text.
• Row-counting divergence (lang_go.py:766, the row-counting fix -- cite this by LINE, not by F-tag: F26 is reused across at least 5 sites in lang_go.py, so an F-tag grep lands on a different fix): tree-sitter's row index advances only on "\n"; naive Python line-splitting also splits on other separators — one stray separator shifts every later line lookup out of alignment with tree-sitter's own rows unless you count rows the same way tree-sitter does.

None of these were guessable from a grammar README. Parse real (or minimal handwritten) source covering every construct you plan to extract through the target tree_sitter_<lang> package directly, and print node.type/node.children recursively, before writing extraction logic.

A fourth, independently-verified example (PR #726 merged mid-authoring-pass — re-checked against the real file rather than left as a secondhand ledger note): C#'s aliased using directive. using MyAlias = System.Text.StringBuilder; parses with the alias identifier emitted first (leftmost child) and the actual target namespace last (rightmost child) — the reverse of what you might guess. _csharp_using_directive_target (lang_csharp.py:138-150) handles all four using forms (plain, dotted, aliased, static/global-qualified) with one rule: take the last matching identifier/qualified_name child, never the first — verified against the installed tree_sitter_c_sharp 0.23.x grammar for all four forms (lang_csharp.py:113-124's own comment table). Getting this backwards would record every aliased import as its local alias name instead of the namespace actually being imported.

A fifth example, and the most important one for C-family declarator walkers (PR #736, v1.98.2): a "seems obviously right" tell was FALSIFIED by the live AST, not confirmed by it. lang_c.py's _c_declarator_name_node walks a declarator chain to decide seen_function: bool — "did the chain pass through a function_declarator?" A banked note from an earlier session proposed the fix as "require function_declarator to be OUTERMOST" to exclude a file-scope function-pointer VARIABLE (void (*handler)(int);, which this module deliberately must NOT report as a function). Dumping the real tree_sitter_c 0.24.2 AST before writing any code showed that hypothesis was simply wrong: a function-pointer variable's declarator chain ALSO has function_declarator outermost — identical in that one respect to a real prototype void f(int);. "Outermost" is not the discriminator at all. The real tell lives one level deeper, in what that function_declarator node's OWN declarator field WRAPS:

A parenthesized_declarator hop alone is not the signal — a real function can be wrapped in meaningless redundant parens too (row 4); what matters is whether the parens wrap a bare name (real function) or a pointer declarator (variable). lang_cpp.py had its OWN, independently-written declarator walker (_cpp_declarator_name_node) with the same latent bug shape — this WAS fixed by PR #737 (confirmed landed: git log --oneline -- src/tensor_grep/cli/lang_cpp.py shows 3c68a34 fix(lang-cpp): exclude function-pointer variables (were mis-kinded "function") (#737) on top of the #732 landing) — do not assume this skill's own older passes describing it as "not yet landed" are still current, re-run the git log. The fix ports lang_c.py's _c_parenthesized_declarator_wraps_bare_name tell via a new _cpp_parenthesized_declarator_wraps_bare_name (lang_cpp.py:381) and confirms the member-function-pointer wrinkle (void (C::*mp)(int);, which wraps a qualified_identifier instead of a pointer_declarator) is SCOPE-DEPENDENT: file/namespace-scope excludes via the bare-name type check, while in-class scope excludes via a different path entirely (tree-sitter-cpp can't resolve C:: inside a class body and emits an ERROR node, giving the parenthesized_declarator two named children instead of one). Rule for this skill's audience specifically: a banked "the fix is obviously X" note — even one written in a prior session about this exact bug class — is a hypothesis about a declarator SHAPE, and declarator shapes are exactly the thing B5 already tells you not to guess. Dump the real parse tree for every shape you plan to include/exclude before trusting a one-line fix description, including your own.

B6 — tiered model recap (see "Current status" above for the live table)

text search (any language, rg passthrough) → structural scan/rewrite (~26 langs via the ast-grep wrapper tg wraps) → deep symbol graph (this skill's tier, the tree-sitter grammars in lang_registry). Adding a language to the symbol graph does not change the other two tiers — a language with no LanguageSpec still gets full-text search and (if ast-grep supports it) structural scan/rewrite; it just has no defs/refs/callers/ tg source support until it clears this checklist.

E1 — priority and what's next

Top-10 by TIOBE Jul-2026 + Stack Overflow 2025 + GitHub Octoverse 2025 consensus: Python, JavaScript, TypeScript, Java, C#, C++, C, Go, Rust, PHP. All 10 are now registered on main — C landed via PR #731 (v1.97.0), C++ via PR #732 (v1.98.0), both scoped exactly per items 1-5 below (a Stage-1, per-file, foundational-tier landing, not the full #include-graph resolution items 1-2 warn against blocking on). The five scoping notes below are kept as a worked EXAMPLE of "scope before starting, not while coding" for the next language beyond the top-10, not as an open task:

1. No module system. Go has go.mod/go.work; C/C++ has no compiler-enforced namespace-to-directory mapping. The honest floor for a first landing is per-file symbol extraction (filename-as-scope), not a full compile_commands.json/CMake include-graph. SUPERSEDED 2026-08-12 — the "#include resolution ... tracked but not started" claim this item used to end with is STALE: PR #957 (commit 9f854d4, verified via git log --oneline -1 9f854d4) shipped a fail-closed #include resolution engine — src/tensor_grep/cli/lang_c_cpp_include.py (quoted includes search the importer's directory first then repo-rooted include roots; angle includes only the repo-rooted roots; macro/call-form includes stay unresolved; never fabricates an on-disk path) — wired into lang_c.c_file_imports_symbol_from_definition and lang_cpp.cpp_file_imports_symbol_from_definition (grep those symbols in src/tensor_grep/cli/lang_c.py / lang_cpp.py), and tested by tests/unit/test_c_cpp_cross_file_callers.py. What REMAINS honestly deferred: forward tg imports resolution for c/cpp — _resolve_raw_import_entry's elif language_id in ("go", "php", "csharp", "c", "cpp") branch still returns the deferred tuple (resolved=None, external=False) — and a clangd-grade compile_commands.json/CMake include-graph resolver, which is not started.
2. #include is textual, not semantic. tree-sitter has no preprocessor; a #define-wrapped declaration (export/visibility macros are common in real C/C++ headers) can hide or reshape the node the extractor expects — B5's live-verify discipline is mandatory here, not optional, on a much larger surface than Go's. Confirmed as shipped: class MACRO Name (a macro-decorated class declaration) misparses on the installed C++ grammar — an INHERENT tree-sitter ceiling, not a bug in this codebase's extractor, and disclosed as accepted in PR #732.
3. Declaration/definition split. A C/C++ function typically appears twice (a header prototype, a body-bearing definition) — which one is canonical for tg source/tg defs is a design decision to make explicitly, not an assumption carried over from Go's one-declaration model.
4. C and C++ are two separate grammar packages (tree-sitter-c vs. tree-sitter-cpp) — decide upfront whether they are one LanguageSpec or two (recommend two, mirroring how JS/TS already get two specs rather than one with a mode flag). Confirmed as shipped: they landed as two separate modules (lang_c.py/lang_cpp.py), each its own LanguageSpec, exactly as recommended here.
5. A first Stage 1 landing can reasonably scope to per-file extraction + declaration/definition dedup by name, in the same 0.7 "receiver-heuristic"-equivalent confidence band Go uses for anything short of confirmed resolution — a real, honestly-labeled feature now, rather than blocking on #include-graph resolution.

Known post-ship correction (PR #736, v1.98.2 — see B5's declarator-shape addendum above for the full worked example): C's file-scope function-pointer VARIABLE (void (*handler)(int);) was initially mis-kinded "function" — fixed by distinguishing what a function_declarator's own declarator field wraps, not whether it's outermost. The sibling fix for lang_cpp.py's independently-written declarator walker (same bug shape, plus a C++-only member-function-pointer wrinkle) HAS SINCE LANDED as PR #737 (3c68a34 fix(lang-cpp): exclude function-pointer variables (were mis-kinded "function") (#737), confirmed via git log --oneline -- src/tensor_grep/cli/lang_cpp.py — two earlier passes of this skill said "not yet landed"; that was accurate when written and is now stale, which is exactly why this section says "re-verify with git log" instead of asserting a fixed date).

Parallel-drain hygiene (cross-ref: AGENTS.md Campaign Orchestration A22)

A new grammar touches three files that several in-flight language PRs are likely to touch at once: tests/unit/test_lang_registry.py (the LANGUAGE_REGISTRY.keys() set-pin test, test_language_registry_has_exactly_the_stage2_languages), the pyproject ast extra (grep -n '^ast = ' pyproject.toml — was :600, now :614, now :621, plus the mirrored dev/bench extras), and uv.lock (a new tree-sitter-<lang> [[package]] block). When more than one language PR is in flight:

• Drain ONE at a time and rebase each onto the prior, UNIONing the assertions — e.g. the set-pin test must assert the full accumulated language set, never take-one-side.
• A CLEAN rebase (no conflict marker) is not proof of correctness — a silent auto-merge can drop a lang_* import. Always re-run pytest tests/unit/test_lang_registry.py after every rebase, not just after the final one.
• uv lock regenerated from scratch churns ~280 unrelated lines (local-vs-CI uv-version marker-expr reformatting) — hand-splice only the new dependency's [[package]] block (alphabetical) plus its requires-dist/optional-dependency refs, and verify with uv export --format requirements.txt --all-extras --no-emit-project --locked (must exit 0 — the exact audit.yml "Dependency & License Audit" gate).
• If you edit uv.lock/ci.yml (CRLF-committed files) with a Python text-mode write (open(path, newline="\n")), it flips every line ending in the file, turning an 11-line change into a 1000+ line diff. Read/write in binary mode (rb/wb) and byte-replace, preserving \r\n.

See AGENTS.md's Campaign Orchestration Disciplines (A22) for the general form of this rule, not specific to language PRs.

Validation

• Extend tests/unit/test_lang_registry.py, not just a new bespoke test file — it already carries the pattern a new language must fit: test_spec_for_path_resolves_every_ registered_suffix, test_language_registry_has_exactly_the_stage2_languages (the union-pin set — add your language_id here), test_target_and_provider_language_agree_ with_registry (this ONE dynamic test pins BOTH seam 5a _target_language_for_path AND seam 5b _provider_language_for_path at once — it iterates every registered LanguageSpec and asserts both functions return that spec's own language_id for each of its suffixes, so it fails loudly if you wire only one of the pair), and the test_*_provenance_is_tree_sitter_when_grammar_present / test_grammar_absent_monkeypatch_*_provenance_flips_to_grammar_missing pair (21 tests as of 2026-07-27 -- re-run the grep rather than trusting this number; it grows with every language total as of this writing — grep -c "def test_" tests/unit/test_lang_registry.py).
• Fixture/parity dogfood: write a minimal real-world-shaped fixture file in the new language exercising every construct you extract (functions, types/generics if the language has them, qualified access, imports) and run tg defs/tg refs/tg callers/ tg source/tg imports against it through the real installed binary, not CliRunner (AGENTS.md's "Dogfood the Real Binary, Not CliRunner").
• Confirm _target_language_for_path (seam 5) with a live tg agent capsule run on a fixture in the new language and check primary_target_language in the JSON — this is the seam a unit test on lang_registry alone will not catch, because it lives in repo_map.py, not the registry module.
• Never trust a subagent's "I added the language and it works" as a self-report — confirm against external state: the registry dict, a real symbol-command run, and (if _target_language_for_path was touched) a capsule run.

Fast self-check before trusting a claim about this design

# Import side effect: LANGUAGE_REGISTRY is empty until the registering module (repo_map) is imported
uv run python -c "from tensor_grep.cli import lang_registry; print(sorted(lang_registry.LANGUAGE_REGISTRY.keys()))"
uv run python -c "from tensor_grep.cli import lang_registry, repo_map; print(sorted(lang_registry.LANGUAGE_REGISTRY.keys()))"

# Does a suffix resolve, and what does provenance_when_missing say?
uv run python -c "from tensor_grep.cli import lang_registry, repo_map; s = lang_registry.spec_for_path('x.go'); print(s.

…(truncated)