feat(resume): the section index gets its first caller — at the moment a probe is about to be re-run

[ZacxDev]

Closes the last open item of the handoff-search-index effort
(claudedocs/handoff-handoff-search-index.md, ranked next-step 4): the index
shipped in #1209 and nothing called it. git grep handoff_search found the
module, its sibling writer, a scripts/README.md row and a shebang test — zero
real callers. An index with no reader is a cost with no benefit, and it fails
silently: every /resume went on re-deriving findings the corpus already held.

Where it is wired, and why this site

claude/skills/resume/SKILL.md step 3, immediately beside the existing
per-item pre-flight (git -C <repo> log --since=<doc-date> …).

The value proposition is the Ruled out: bullets inside ## Open investigations blocks — the content that stops the next session re-running a
probe someone already ran. Those only discriminate against a question:

• At orientation time (step 2/4) you have a topic slug, and a slug query
  mostly retrieves the doc you are already about to read. At step 3 you have
  the open item in hand, so the cross-doc hits are the ones that change what you
  do.
• Step 4 is a different corpus — the subsystem-index store, read through
  cairn recall. It is not this one.
• The adjacent command already carries exactly this rhetoric: "the cost is one
  command; the cost of skipping it is a whole session." The new block is that
  sentence's sibling, not a new section.

Sites considered and rejected

The /handoff "Run this first" template. Two reasons, either sufficient:
scripts/tests/test_handoff_skill_size.py leaves roughly 291 B under its
enforced floor, so a line there costs an eviction of an instruction in the
same commit — and that test's own playbook records that trimming imperative
prose for bytes is how an instruction gets lost. Second, a template only reaches
docs written after it, while this tool's entire value is retrieval over the
~379 docs that already exist.

A thin wrapper script. It adds indirection with no capability. The CLI is
already the right shape and already renders the recall banner, the
indexed_docs=N indexed_sections=M scope line and the five distinct
zero-causes. A wrapper would have to re-render or swallow them — and swallowing
is precisely the failure the tool was built to prevent.

--offline, deliberately

It answers from git refs with no database. The Postgres path has never been
executed by any test (the handoff doc says so in its own words), and the sync
unit ships disarmed (enableHandoffIndexSync = false). Wiring the consumer to
the DB path would have made the step a connection error on first use.

Honest degradation is in the block, not assumed

The block keeps every distinction the tool makes, because a consumer that drops
them reintroduces the silent zero:

• the recall banner posture — a hit is a POINTER TO VERIFY, never a current
  reading, and may describe a gotcha already fixed;
• the literal indexed_docs=N indexed_sections=M;
• all four non-answer exit codes with what each means (3 broken index · 4
  empty scope · 6 unmeasurable corpus · 7 repos resolved, zero docs derived),
  and that only NO MATCH at rc 0 means the corpus was asked and is silent;
• non-blocking: on any non-zero, print the stderr line, say retrieval was
  unavailable, and carry on with the item.

The guard (scripts/tests/test_resume_handoff_search_wiring.py)

Three claims, each derived from the tool rather than restated:

1. the prescribed command pinned as a whole normalised string — an edit
   dropping --offline goes red instead of silently starting to require a
   database;
2. the seam — every flag the skill prescribes is probed behaviourally
   against handoff_search.main(), so a rename in the tool breaks the test
   rather than leaving the skill prescribing a dead command (with a negative
   control asserting an unknown flag still SystemExits);
3. the silent-zero ledger — the non-answer codes are read out of
   EXIT_CODES / SCOPE_REASON_EXIT_CODES, so carving out a sixth zero goes
   red until /resume is taught about it.

Every contract assertion runs against a slice delimited by two pinned sentinels,
so a hit elsewhere in the 40 KB body cannot satisfy it — this file already
discusses "exit code 4" twice, for cairn and subsystem_recall.py, in a
completely different sense.

Red → green

Base d86b4e45: 3 failed / 3 passed before the skill edit, 6 passed
after. The three reds are the wiring and contract assertions; the three that
passed at base are the guard-the-guard, the seam probe (tool-only) and the
sentinel control.

Mutation sweep

Fresh minimal repo mirror per mutant, PYTHONDONTWRITEBYTECODE=1, narrowest
expression mutated. 7/7 killed, each by the specific guard whose claim it
violates:

mutant	killed by
M1 skill drops --offline	the shape pin
M2 skill drops exit code 7	the derived ledger
M3 skill drops POINTER TO VERIFY	the posture check
M4 whole block deleted	3 guards, incl. the sentinel
M5 tool renames --offline	the seam probe
M6 tool adds a 6th non-answer code	the derived ledger
M7 tool stops printing indexed_docs=	the posture check

Controls: an unmutated mirror and a whitespace-only skill edit are both
green, so the kills are facts about the mutations and not about "the file
changed".

⚠ The first build of that harness reported 8 kills off a RED no-op control —
the mirror omitted a transitive import (handoff_doc), so every "kill" was a
fact about the harness. Recorded because that is the entire reason the control
exists.

Bytes

claude/skills/resume/SKILL.md 40,581 → 41,852 (+1,271). That file has no
enforced ceiling (git grep -l MIN_HEADROOM_BYTES scripts/ — RULES.md,
browser-bridge, prune-skill and handoff have one; resume does not). ~40% of the
delta is the four-code non-answer ledger, which is the honesty half of the
wiring.

Not done here

The handoff doc's rank 4 is not struck through and rank 1 (arming the live
Postgres path) is untouched — that step cannot run in any sandbox and is
somebody's supervised operator act.

Gate — run on the MERGED tree a6fdcc87 (my commit 6af2ac49 + origin/main 5793c0e5)

Branch protection is off, so these are the only evidence there is. Both tiers,
named with the base sha, and the two nix derivations built one at a time.

Dev-host tier — nix develop … -c bash scripts/gate.sh --tier both (--set hermetic):

  FAIL  pytest  exit=1  verdict='RESULT: FAIL (exit=1)'
  PASS  node    exit=0  verdict='RESULT: PASS (exit=0)'
GATE: RESULT=FAIL exit=1

Exactly one failing test, and it is environmental — not this diff:

FAILED scripts/claude-hooks/tests/test_clawgate_task_interview_guard.py::
       test_a_body_file_written_by_a_heredoc_on_the_same_line_is_read

🔴 Discriminating control run, not asserted. /tmp/body.md exists on this
box — 21,181 B, mtime Sep 3 19:41, content about a mute-review queue, written by
a sibling agent. The guard reads the real file. Exporting pristine
origin/main 5793c0e5 (git archive | tar -x, none of my changes) and
running that one file reproduces the identical failure: 1 failed, 309 passed.
My diff touches claude/skills/resume/SKILL.md and one new file under
scripts/tests/; it cannot reach scripts/claude-hooks/.

Sandbox tier — the one Tekton runs, built from a cp -r ${./.} store copy,
one derivation at a time after waiting out three concurrent sibling nix builds:

devrc-pytests>   RESULT: PASS (exit=0)
devrc-nodetests> RESULT: PASS (exit=0)   TOTAL suites=5 files=41 tests=1449 pass=1449 fail=0

🔴 The sandbox is the cross-check that settles it: the clawgate guard test
passes there, because the build sandbox has its own /tmp and no sibling's
body.md in it. Same tree, same test, opposite result — that is the mechanism,
measured, rather than a plausible story about load.

⚠ origin/main has moved to 2b1d3552 since this was gated. strict is false
on this repo by design, so re-gate the merged tree if it has drifted materially
before merging.