[piyushmakhija28]

Closes item 2 of #296 — the last of the four.

This was supposed to be a one-line fix

The issue described item 2 as correcting ENABLE_CI's documented default. Auditing the rest of the flags table instead turned up a flag with no implementation at all.

FORCE_GRAPH_REBUILD is described in five files — CLAUDE.md, ADR-002, DEPLOYMENT_GUIDE.md, RUNBOOK_STALE_GRAPH.md, TROUBLESHOOTING_GUIDE.md — and read by no code anywhere since a43595b (2026-03-28, the "production readiness sprint").

RUNBOOK_STALE_GRAPH.md Option B tells an operator to run this while recovering from a stale-graph incident:

export FORCE_GRAPH_REBUILD=1
python scripts/3-level-flow.py --task "your task" --start-step 10

That did nothing. A wrong default confuses a reader; a recovery procedure that silently fails is consulted precisely when something has already gone wrong.

Implement, not delete

Deleting it from five documents would have meant asserting that ADR-002's stated mitigation never existed — a claim about the past rather than a correction to the present. Implementing makes the documents true.

refresh_call_graph_if_stale() now rebuilds unconditionally when the variable is "1", checked before the stale flag so it genuinely bypasses it. Only the literal "1" enables it, matching the ENABLE_* convention used across the engine.

Why an environment variable and not another state key

This covers exactly the case the stale flag cannot reach — the one ADR-002 names as its own risk. When call_graph_stale is never set, because the node that sets it crashed, the guard cannot fire and Step 5 reviews an outdated snapshot in silence. There is no in-state signal for an operator to correct, so the override has to come from outside the state.

Tests

Every test leaves call_graph_stale unset and supplies a usable cached snapshot, so without the override the cache is what the function returns.

The cases are paired on purpose: "forced rebuild returns fresh data" is satisfied by a function that always rebuilds, so unset, "0" and "true" each assert the cache is still honoured. A fifth test pins that FORCE_GRAPH_REBUILD=0 does not switch off ordinary stale-based rebuilding.

Proven by deleting the check: only the forced case went red; the other four stayed green. Then restored.

Documentation

RUNBOOK Option A was wrong in its own right and is corrected. It implied FORCE_GRAPH_REBUILD=0 disabled stale-based rebuilding and that unsetting it re-enabled it. Stale rebuilding is driven by the state flag and by no environment variable — the override only ever adds a rebuild. The fifth test pins that so the wording cannot drift back.

ADR-002, DEPLOYMENT_GUIDE.md and TROUBLESHOOTING_GUIDE.md needed no edits — implementing the variable made them true as written.

ENABLE_CI goes false → true, and the row now records that it is a GitHub repository variable, not a process environment variable: ci.yml reads vars.ENABLE_CI and falls back to true. That distinction is why it behaves unlike every other flag in that table, and its absence is probably how the default came to be recorded backwards.

The remaining flags were checked against their read sites and match. ENABLE_JENKINS and ENABLE_SONARQUBE resolve through core/config_loader.py rather than a direct getenv, which is why a first grep pass reported them missing — that pass was wrong, not the flags.

Verified

28 targeted tests, all six CI gates, counts caught by the doc-count enforcement test rather than by hand (third time since it landed), no line-ending flips. Pre-commit ran fully this time and ruff / black / isort all passed locally — the lint caveat carried in #298 and #299 does not apply here.

🤖 Generated with Claude Code