Converge the annex plumbing: required=true always, pinned where PATH cannot serve

[EiffL]

The problem (measured)

git annex init wires the repository to a bare git-annex — the filter drivers in .git/config and four hooks — resolved from whatever PATH the researcher's git runs under. lc itself always has git-annex (it bundles one), but the shell the researcher types git add into may hold nothing of the sort: an engine invoked through uvx puts nothing on PATH. In that state, a plain git add of annexed content prints git-annex: command not found, exits 0, and stages the raw bytes into git history — a 2 GB dataset lands in git proper, silently, on every clone forever. This failure mode is recorded as a measured test in this PR.

The fix: convergence owns the plumbing

lc init gains an annex-plumbing convergence item, right after git annex init:

• filter.annex.required = true, always. The silent exit-0 corruption becomes git's own hard refusal (fatal: ... clean filter 'annex' failed, nothing staged), with lc init as the remedy — quoted verbatim from a real run in the troubleshooting doc.
• Where the researcher's shell resolves git-annex, stock plumbing is kept untouched. The probe is ambient_annex(): PATH minus the engine's own bin directory, because launchers front that directory on lc's environment and a naive which from inside lc always finds the bundled copy. A stock spelling that works outlives any prunable engine path.
• Where it doesn't, the plumbing is pinned to the engine's bundled git-annex by absolute path: the three filter drivers (process, plus the smudge/clean fallback pair so both routes resolve the same binary) and the four hooks. Measured: with the filter pinned, git add stages a pointer and commit runs the pinned pre-commit hook with no git-annex on PATH at all.
• Asymmetric repair. A pin that still runs is never rewritten — even when PATH could now serve, or it is not this engine's copy — because both work and rewriting would flip-flop between a tool install and a uvx cache. Only a broken pin is repaired: toward stock when the shell resolves git-annex, else to the current engine's copy. lc init --check reports drift without writing.
• User hooks are never touched. Ownership is gated on git-annex's own automatically configured by git-annex marker; the hooks directory is asked of git rev-parse --git-path hooks, so linked worktrees and core.hooksPath behave.

require_git_annex() stays a PATH check, unchanged: it gates lc's own git annex subprocesses, which dispatch from lc's process PATH — a different question from the researcher's shell, and recorded as such in CLAUDE.md.

Verification

• Full suite green (608 passed, run twice), ruff check clean, mypy src/ strict clean, zensical build clean.
• New unit coverage (host-independent, fake tools): fresh pin, stock-plus-required, idempotent re-run, dead pin repaired to engine, dead pin repaired to stock, working pin surviving ambient git-annex appearing, --check flags drift and writes nothing, user hook untouched, probe regressions (the sys.executable symlink resolve; a tool install's ~/.local/bin/git-annex symlink counting as genuinely ambient).
• New real-annex integration tests: pointer staged and pinned hook run with git-annex absent from PATH; required=true alone failing hard with nothing staged; the exit-0 raw-bytes hazard pinned as a measured fact; stock spellings pinned against a real git annex init.
• Docs: docs/cli/init.md, docs/user/troubleshooting.md, docs/api/{project,dataset}.md, docs/architecture.md, CLAUDE.md invariants — every added command block executed before shipping.

Companion change: LightconeResearch/agent-skills#34 carries a skill-side interim snippet doing the same convergence from the outside; once this ships in a release, that snippet reduces to nothing.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LsttSNGJ8kEMavA27ezW9L

[github-actions]

✅ Eval

Metric	Value
Outputs check	success
Agent run	success
Turns	33
Tool calls	31
Cost	$1.33
Agent wall time	5m35s
Model	claude-sonnet-5

lc status

  mode:    direct
  sandbox: landlock (fs: declared, network: allowed)
  crate:   up to date with the outputs

  · current  baseline/best_fit        770afd0
  · current  baseline/hubble_diagram  770afd0
  · current  baseline/residuals       770afd0

3 current

Confusion & pain points (Claude analysis)

Confusion & pain points

• Missing numpy blocked initial data exploration: the agent tried python3 -c "import numpy..." against the bare system interpreter (not the project .venv) and hit ModuleNotFoundError, forcing a fallback to hand-rolled stdlib parsing. Root cause: no awareness/reminder that analysis dependencies live in the project's uv-managed environment, not the ambient python3. A harness nudge (or lc/skill guidance) to always invoke .venv/bin/python — or run through uv run — would avoid this detour.
• Reverse-engineered the data file's column semantics via a live web search: the SCPUnion2.1 table's 4th/5th columns (error, probability/weight-like field) weren't self-describing, so the agent used WebSearch plus a ToolSearch lookup to find search tooling before it could even search. This is a data/eval-fixture gap — a data/README.md note on column meaning would save a network round-trip and remove ambiguity risk in the fit itself.
• Invented a systematic-error term not present in the data: with only one uncertainty column available, the agent derived a stat_and_sys quadrature term from the difference between two calibration constants quoted in the file's comment header, rather than from any declared/structured input. This is a workaround for missing provenance in the source data (no separate stat-only vs. sys columns), and it's the kind of ad-hoc scientific judgment call that ideally would be flagged for human review rather than silently baked into the recipe.
• Otherwise a clean, linear run: spec validation, lc materialize, license declaration, and RO-Crate generation all worked on the first try with no CLI misunderstandings or sandbox denials.

Full trace: agent-trace artifact on this run.

[EiffL]

LGTM