feat(skills): gitnexus-plan runner build check before freshness refresh

When the target repo builds the analyzer from its own source (bin → dist/
mapping, as gitnexus/ does), the Phase 1 freshness gate now verifies dist/
is current before running the analyze refresh — rebuilding via the
package's build script when any analyzer source file is newer than the
built entrypoint — and prefers that freshly built CLI. Otherwise a stale
dist re-indexes with outdated extraction logic and the 'fresh' index lies.
Rebuilds are recorded in the ledger's index_refresh; the PDG-phase refresh
inherits the same check.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.claude/skills/gitnexus-plan/README.md

@@ -94,8 +94,12 @@ of context until the phase that needs them.
   a stale index (or a missing PDG layer) is refreshed once via
   `node .gitnexus/run.cjs analyze --index-only [--pdg]` before the graph is
   relied on — `--index-only` touches only the `.gitnexus` store, never repo
-  files. `freshness: accept` (or a failed/impractical refresh) plans on the
-  stale graph instead, source-weighted and labelled in the plan header.
+  files. When the repo builds the analyzer from source (like this one:
+  `gitnexus/dist`), the gate first ensures `dist/` is current (`npm run
+  build` when src is newer) so the refresh doesn't re-index with outdated
+  extraction logic. `freshness: accept` (or a failed/impractical refresh)
+  plans on the stale graph instead, source-weighted and labelled in the plan
+  header.
 - PDG layer still unavailable after that → the plan says so and skips
   statement-level claims (never reconstructs fake edges).
 - No GitNexus at all → fallback mode: targeted grep/read exploration, findings

.claude/skills/gitnexus-plan/SKILL.md

@@ -76,6 +76,15 @@ take the widest depth, union the focus areas.
    **Freshness gate.** Plans built on a stale graph make stale blast-radius
    claims, so freshness is not advisory here. Under `freshness: strict` (the
    default):
+   - **Runner build check — before any refresh.** If the target repo builds
+     the analyzer from its own source (a `bin` → `dist/` mapping, as in this
+     repo's `gitnexus/` package), the built output must be current, or the
+     refresh re-indexes with outdated extraction logic and defeats the gate.
+     Rebuild when any analyzer source file is newer than the built entrypoint
+     (e.g. `find gitnexus/src -newer gitnexus/dist/cli/index.js -print -quit`
+     prints anything — when in doubt, rebuild: `npm run build` in the
+     package) and prefer that freshly built CLI for the refresh. Note the
+     rebuild in `index_refresh`.
    - Stale index → run `node .gitnexus/run.cjs analyze --index-only` (append
      `--pdg` when the task category will reach Phase 3) and re-read the
      context resource. At most **one refresh per planning session**; record

.claude/skills/gitnexus-plan/references/context-ledger.md

@@ -21,8 +21,9 @@ context_ledger:
                                  # every line citation in the plan pins to it
 
   index_refresh: ""              # the one permitted analyze --index-only run:
-                                 # command + outcome (or "skipped: <reason>");
-                                 # at most one per planning session
+                                 # command + outcome (or "skipped: <reason>"),
+                                 # incl. any analyzer dist/ rebuild that
+                                 # preceded it; at most one per session
 
   established_facts: []          # each with its evidence source
 

.claude/skills/gitnexus-plan/references/pdg-slice.md

@@ -29,8 +29,8 @@ Contract caveats that shape interpretation:
   The note is repo-wide: one probe settles it — do not re-probe per function.
   Under `freshness: strict` (default), run
   `node .gitnexus/run.cjs analyze --index-only --pdg` — once per planning
-  session, and only if Phase 1's refresh didn't already carry `--pdg` — then
-  re-probe. If the refresh failed, is impractical, or `freshness: accept` was
+  session, only if Phase 1's refresh didn't already carry `--pdg`, and with
+  Phase 1's runner build check applied first — then re-probe. If the refresh failed, is impractical, or `freshness: accept` was
   passed: record "PDG unavailable" in the ledger, skip the slice, say so in
   plan §5, and recommend the command. Never reconstruct edges from source by
   hand.