Gating split: env-gate recency scan, ship doc-aware analysis unconditionally (refines hl-78b)
Date: 2026-06-08 Status: Accepted Decision: hl-fk0 Deciders: Sean Brandt
Context
Section titled “Context”The recency scan introduces a git clone per index run (network cost). The doc-aware analysis changes (structured chunk selection, prompt framing, Documentation Accuracy section) are behavior-changing by design and intended as upstream PRs. ADR hl-78b establishes the fork’s env-gated default-unchanged convention for patches but does not define how to classify features that are quality fixes vs infrastructure additions. This decision refines (does not supersede) hl-78b.
Decision
Section titled “Decision”Branch 1 (feat/file-recency-metadata) is gated behind INDEX_FILE_RECENCY (default off — byte-identical behavior when unset). Branches 2 (feat/doc-aware-analysis) and 3 (feat/recency-aware-review-context) ship ungated as unconditional quality fixes that degrade gracefully when lastModifiedAt is absent. Classification rule: cost-incurring infrastructure → env-gated; behavior-improving prompt/selection changes → unconditional upstream-PR candidates.
Rationale
Section titled “Rationale”- Env-gating a prompt quality fix would be awkward in an upstream PR — a maintainer would want the improvement unconditionally.
- Branches 2–3 improve analysis quality even without age data (structured selection, doc cap, path diversity, code-is-truth framing); gating them would withhold a strict improvement from operators who do not enable the scan.
- The split aligns with hl-78b’s upstream-PR sizing convention: each branch is independently mergeable and the gating boundary corresponds to what upstream would accept unconditionally.
Alternatives Considered
Section titled “Alternatives Considered”- Gate scan only; ship branches 2–3 unconditionally (chosen): follows upstream conventions; full benefit still requires enabling
INDEX_FILE_RECENCY. - Gate all three behind one env var: simplest rollout, but makes an unconditional quality improvement opt-in and is inconsistent with upstream-PR framing.
- Ship all three unconditionally: simplest code, but forces a git clone on every index run without operator opt-in — violates the fork’s default-unchanged convention for cost-incurring changes.
Consequences
Section titled “Consequences”- Positive: operators get immediate analysis-quality improvements on deploy; the scan stays opt-in; each branch remains upstream-PR-sized.
- Negative: without
INDEX_FILE_RECENCY=true, age annotations and stale-doc demotion are silent no-ops; full benefit needs deploy + env + re-index. - Neutral: branch 2 depends on branch 1’s type exports but not its runtime behavior.