From 7c185993383b21e2570142fc3b755b02a0c3673a Mon Sep 17 00:00:00 2001 From: Gergo Magyar Date: Sat, 11 Jul 2026 07:43:56 +0000 Subject: [PATCH] feat(skills): gitnexus-plan runner build check before freshness refresh MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .claude/skills/gitnexus-plan/README.md | 8 ++++++-- .claude/skills/gitnexus-plan/SKILL.md | 9 +++++++++ .../skills/gitnexus-plan/references/context-ledger.md | 5 +++-- .claude/skills/gitnexus-plan/references/pdg-slice.md | 4 ++-- 4 files changed, 20 insertions(+), 6 deletions(-) diff --git a/.claude/skills/gitnexus-plan/README.md b/.claude/skills/gitnexus-plan/README.md index b1e6dd9c1..a55a5cb43 100644 --- a/.claude/skills/gitnexus-plan/README.md +++ b/.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 diff --git a/.claude/skills/gitnexus-plan/SKILL.md b/.claude/skills/gitnexus-plan/SKILL.md index 27fdd4865..b3a310b17 100644 --- a/.claude/skills/gitnexus-plan/SKILL.md +++ b/.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 diff --git a/.claude/skills/gitnexus-plan/references/context-ledger.md b/.claude/skills/gitnexus-plan/references/context-ledger.md index af22f341f..ee749e933 100644 --- a/.claude/skills/gitnexus-plan/references/context-ledger.md +++ b/.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: "); - # at most one per planning session + # command + outcome (or "skipped: "), + # incl. any analyzer dist/ rebuild that + # preceded it; at most one per session established_facts: [] # each with its evidence source diff --git a/.claude/skills/gitnexus-plan/references/pdg-slice.md b/.claude/skills/gitnexus-plan/references/pdg-slice.md index 3ed142a8e..eccb1bf14 100644 --- a/.claude/skills/gitnexus-plan/references/pdg-slice.md +++ b/.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.