Document the dependencies cmdstanr does not track

Document the dependencies cmdstanr does not track

Part of the design described in #1254. I asked Claude to write the text below based on that.

The build record (#1238) tracks the Stan program, its includes, the user header, make/local and the CmdStan installation. What it leaves untracked is #1254 §6 ("Provenance we cannot complete" and "What no record can fix"): toolchain drift, compiler include-path environment variables, Make variables set in the environment, CmdStan or Stan Math modified in place, a make/local that includes another makefile, and headers the user header includes. force_recompile = TRUE is the remedy for every one of them, and nobody reaches for it without being told.

Checklist

Stage 3 (#1258)

• Both detectors: ^\s*(?:-?include|sinclude)\b on make/local, ^\s*#\s*include\s*" on the user header. They establish that a gap exists, never that none does, which is why the field is known_untracked_dependencies and not provenance_complete (#1254 §6, "Provenance we cannot complete")
• One line at compile time when a detector fires, naming the exposure and the remedy. Nothing on construction and nothing in pre-operation validation (#1254 §6)

Stage 4 (#1273)

• User-facing documentation of the untracked list and the remedy: the "What the build record does not track" section of the internals vignette, and the force_recompile roxygen on cmdstan_model()
• Angle-bracket includes named as the documented blind spot: a user-supplied -I is what makes #include <helpers.hpp> work, and the regex is not widened to [<"] because it would fire on <vector>

Compiler depfiles: the right mechanism, not in v1

Measured against CmdStan 2.39. CmdStan does not supply a depfile for models: make/program:106-108 sets up -include for one and :68 has a %.d: %.hpp rule, but the model's .hpp is an intermediate CmdStan deletes after linking, so make <model>.d gives No rule to make target.

cmdstanr could produce one itself:

c++ -std=c++17 <cmdstan -D flags> -MM -MG -MP -MF out.d user_header.hpp

About 150 ms warm. -MG makes it self-scoping: real paths are the user's files, <stan/math.hpp> and friends come back as bare names to discard. It would also close the angle-bracket blind spot. Costs: user -I flags must be forwarded or the closure is silently incomplete, an #ifdef on a macro defined inside stan/math evaluates differently during the scan, and .d parsing wants its own tests.

Not in v1 because it couples record validation to compiler flag construction, which can drift quietly, and puts a compiler invocation on a path that today only reads files and runs stanc. Records written before a release that adds it are handled by rules #1254 already states. A source-backed model rebuilds once (#1254 §6, "records written before it cannot answer the comparison that replaces it, so they are refused once"). An executable-only model cannot rebuild and keeps running: it "drops to the unprovenanced path above and stays there until whoever produced the executable rebuilds it" (#1254 §7), so a package that compiled at install time loses provenance reporting until the user reinstalls it, and nothing that fits.

Also worth documenting

Options that need CmdStan itself rebuilt are not an issue. CmdStan selects flag-specific main objects and precompiled headers by filename (makefile:97-118, :135, make/program:8), so flipping STAN_THREADS, STAN_MPI, STAN_OPENCL or STAN_NO_RANGE_CHECKS builds the right objects on demand.

Read the internals vignette section titled "What the build record does not track" and the force_recompile roxygen on cmdstan_model(). Confirm that the untracked dependencies, the angle-bracket include blind spot, and force_recompile as the remedy are documented consistently with the issue text; done means both user-facing documentation locations cover the listed limitations.