feat: self-refreshing mcp/lsp code index

[markshust]

Problem

Two real agent sessions wasted steps because the MCP tooling lied. An agent created a correct app/ module (extra.marko.module: true, psr-4 autoload, a #[Get('/')] controller), but validate_module / list_routes returned "module not found" / "no routes" — until it ran indexer:rebuild. That trained two wrong, Magento-style reflexes: running composer dump-autoload and reaching for a reindex after scaffolding.

Root cause: IndexCache::ensureLoaded() short-circuited on $this->data !== null and never re-checked staleness after the first read. mcp:serve and lsp:serve are long-lived processes holding IndexCache as a singleton, so they froze their snapshot for the whole process lifetime. The runtime app was never affected (routing + autoloading are live per request) — only the AI tooling's symbol index lagged.

Fix

• IndexCache re-checks staleness on every read, so the long-lived servers reflect new code without indexer:rebuild or a restart.
• Scoped to app/ + modules/ (the dirs an agent edits); vendor/ is excluded from the on-read check but still fully indexed by build(). New/removed vendor packages surface on the next indexer:rebuild / devai:install cold-warm.
• Detects deletions, not just additions/edits, via a persisted tracked path-set compared against the current walk.
• No TTL/clock — the scoped walk is cheap, and a rebuild fires at most once per change (save() stamps the cache mtime). Re-checking every read is simpler and avoids any window where a fresh write is masked.

Also stops teaching the obsolete reflexes

• create-module skill Step 6: dropped composer dump-autoload and the "verify via list_modules" gate framing.
• Docs (codeindexer, modularity, troubleshooting, verification-checklist): rewritten to describe on-read self-refresh; indexer:rebuild reframed as forced/clean rebuild + cold-warm + vendor-change, not a routine step.
• devai-generated CLAUDE.md: added a "trust your own writes" directive — introspection tools are for discovering pre-existing code, not confirming scaffolding you just wrote.

Testing

• 10 new IndexCacheTest cases (singleton refresh, additions/edits/deletions, vendor-excluded, no rebuild storm, legacy-payload handling, first-load preserved) + 1 new ClaudeCodeAgentTest assertion.
• Full suite green: 6855 passed.

🤖 Generated with Claude Code