tensor-grep-prepare

name	tensor-grep-prepare
description	Use when an agent needs one-call edit readiness before changing code — tg prepare returns primary target, confidence, callers/blast-radius floor, validation commands, and claim/evidence coordination hooks. Prefer over the multi-step orient→search→agent→route-test→callers→evidence→ledger loop for routine edits. Pair with tg install-dense once for semantic find quality.

tensor-grep prepare (one-call edit readiness)

Verified against tg 1.110.14 — honesty note (2026-08-13): this stamp was bumped from 1.110.13 by the 2026-08-11 drift sweep (docs/audits/2026-08-11-skill-audit-findings.md item 6), but the dogfood table below records no dated 1.110.14 row — its newest rows are 1.110.13, and the ~5s saddle / ~22s --out/--claim numbers this header previously presented as a LIVE 1.110.14 run are byte-for-byte the 1.110.13 receipts. The 1.110.14 stamp therefore currently rests on the 1.110.13 receipt (prior 1.110.12 CUJ still representative); a future pass must either add a dated 1.110.14 dogfood row or keep citing 1.110.13, as this header now does.

Note: anonymous --claim agent_id_hint remains strong (“NOT attributable…” until TG_LEDGER_AGENT_ID / TG_EVIDENCE_AGENT_ID is set).

When to use

Need	Command
Single call before editing	tg prepare REPO/src "task" --json
Also submit advisory ledger claim	tg prepare REPO/src "task" --claim --json
Persist the capsule for evidence emit	tg prepare REPO/src "task" --out capsule.json --json
Whole-repo / large root	tg prepare REPO "task" --deadline 20 --json (expect partial)

Prefer REPO/src. Default deadline is 60s (like agent cold path); pass --no-deadline only when intentional.

What you get

• primary_target + confidence + ask_user_before_editing
• validation_commands
• blast_radius_floor (callers_count, top_callers, trust summary)
• coordination.claim — args ready; submitted=true only with --claim; an anonymous claim (neither TG_LEDGER_AGENT_ID nor TG_EVIDENCE_AGENT_ID set) additionally stamps coordination.claim.agent_id_hint with the STRONG hint — "this claim is filed as 'anonymous' and is NOT attributable to you. Set TG_LEDGER_AGENT_ID (or TG_EVIDENCE_AGENT_ID) to a stable per-agent value so other agents can see WHO holds it." — plus the machine-branchable agent_id_is_anonymous=true sibling, so the caller knows why agent_id reads anonymous. (The earlier weak hint "set TG_LEDGER_AGENT_ID for a stable identity" is RETIRED — superseded per the "Strengthened from" comment in src/tensor_grep/cli/prepare_service.py; grep "Strengthened from" to re-verify. Do not re-quote the weak form.)
• coordination.evidence — argv/note to emit a receipt without guessing flags

Dogfood:

Case	Result
prepare … saddle (1.110.13)	PASS ~5s
prepare … --out/--claim tg src (1.110.13)	PASS ~22s
prepare … saddle (1.110.12)	PASS ~6.5s
prepare … --out/--claim tg src (1.110.12)	PASS ~20s
prepare … saddle (1.110.10)	PASS ~6s
prepare … --out/--claim tg src (1.110.10)	PASS ~14s
prepare … --out (1.101.31)	PASS ~8s — overall 0.9, callers_count=1, file ~8KB
prepare … --claim (1.101.31)	PASS ~13s — anonymous + strong hint; env id clears hint
prepare … --out (1.101.22)	PASS ~7s — overall 0.9, callers_count=1, file ~8KB
prepare … --claim (1.101.22)	PASS ~9s — stronger anonymous agent_id_hint; env id clears hint
prepare … --out (1.101.19)	PASS ~7s — overall 0.9, callers_count=1, file ~8KB
prepare … --claim (1.101.19)	PASS ~8s — anonymous + hint; env id clears hint
prepare … --out (1.101.17)	PASS ~7s — overall 0.9, callers_count=1, file ~8KB
prepare … --claim (1.101.17)	PASS ~8s — anonymous + hint; TG_LEDGER_AGENT_ID clears hint
prepare … --out (1.101.9)	PASS ~6s — overall 0.9, callers_count=1, file ~8KB
prepare … --claim (1.101.9)	PASS ~8s — submitted=true + when anonymous

--out FILE (v1.93.0, A12(d)) replaces the old manual-redirect workflow. Chain straight into evidence emit, no separate save step:

tg prepare REPO/src "task" --out capsule.json --json
tg evidence emit REPO --capsule capsule.json --query "task" --json --agent-id "$AGENT_ID" --out receipt.json

Without --out, prepare still does not write the capsule file on its own — save stdout instead (tg prepare ... --json > capsule.json), or use coordination.evidence.argv.

Ledger cross-ref: --claim's behavior is affected by the #706 PATH-canonicalization fix (see tensor-grep-ledger) — a claim submitted here is now visible from tg ledger list at any subtree PATH under the same repo, not just the exact PATH prepare was run against.

Hard stops

1. ask_user_before_editing.required
2. partial / partial_reason, scan_limit.possibly_truncated, blast_radius_floor.possibly_incomplete, exit 2 — do not claim full coverage. (These are prepare's REAL incompleteness signals — partial_reason="deadline" folds into the top-level exit-2 honesty gate; a plain max_callers output cap stays exit 0. Note prepare emits NO result_incomplete field: grep -c result_incomplete src/tensor_grep/cli/prepare_service.py is 0, verified 2026-08-13 — an earlier revision of this hard stop listed it in error.)
3. Empty blast_radius_floor with source=no_primary_symbol — narrow PATH or raise budget

Dense semantic companion

tg install-dense --json   # once per machine; never auto-runs
tg find "intent" REPO/src --deadline 20 --json   # dense leg after install

Dogfood: install-dense PASS ~4s (uv-tool + potion-code-16M); post-install tg find no longer reports BM25-only rank_fallback_reason.

Related

• tensor-grep, tensor-grep-ledger, tensor-grep-find-and-route, tensor-grep-enterprise-agent