feat(skills): gitnexus-plan freshness gate + active PDG-layer refresh

Freshness is now a Phase 1 gate, not advisory: under the default
freshness:strict, a stale index is refreshed once per planning session via
node .gitnexus/run.cjs analyze --index-only (appending --pdg when the task
will reach the PDG phase), then the context resource is re-read. A missing
PDG layer likewise triggers the one permitted --index-only --pdg refresh
and re-probe instead of a passive recommendation. freshness:accept (or a
failed/impractical refresh) preserves the old behavior: plan on the stale
graph, source-weighted, labelled in the plan header. --index-only is the
load-bearing flag choice — it suppresses all file generation, so the
planning-only contract holds (only the .gitnexus store changes). Ledger
gains an index_refresh record; plan header states fresh / refreshed /
refresh-skipped-with-reason.

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

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

@@ -88,10 +88,16 @@ of context until the phase that needs them.
 
 ## Requirements and graceful degradation
 
-- Requires a GitNexus index (`node .gitnexus/run.cjs analyze`); statement-level
-  sections additionally require `analyze --pdg`.
-- No PDG layer → the plan says so and skips statement-level claims (never
-  reconstructs fake edges).
+- Requires a GitNexus index; statement-level sections additionally require the
+  `--pdg` layers.
+- Freshness is a gate, not a footnote: under the default `freshness: strict`,
+  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.
+- 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
   labelled **source-derived**, with a recommendation to index.
 
@@ -100,4 +106,5 @@ of context until the phase that needs them.
 - `pdg_query` is intra-procedural; cross-function flow comes from `explain`
   (taint) or `impact {mode:"pdg"}` inter-procedural reach.
 - The skill is planning-only by contract: the only repository file it writes
-  is the plan document — it will not fix what it finds.
+  is the plan document, and the only other state it may touch is the
+  `.gitnexus` index store (freshness refresh) — it will not fix what it finds.

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

@@ -20,7 +20,10 @@ executor) can consume without repeating the investigation.
 
 **This skill plans. It never implements.** Do not modify production code,
 tests, or configuration while running it. The only repository file it writes
-is the plan document (a working ledger kept outside the repo is fine).
+is the plan document (a working ledger kept outside the repo is fine). The
+one permitted state change besides that is an index refresh via
+`analyze --index-only` — it writes only the `.gitnexus` index store, never
+repo files.
 
 ## Hard rules
 
@@ -70,9 +73,17 @@ take the widest depth, union the focus areas.
 2. Record the repo's current HEAD commit in the ledger — every line-number
    citation in the plan is pinned to it.
 3. Read `gitnexus://repo/{name}/context` — codebase overview + staleness check.
-   - Stale index → recommend `node .gitnexus/run.cjs analyze`, note the
-     staleness in the plan's Assumptions, and continue with source
-     verification weighted higher.
+   **Freshness gate.** Plans built on a stale graph make stale blast-radius
+   claims, so freshness is not advisory here. Under `freshness: strict` (the
+   default):
+   - 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
+     the command and outcome in the ledger's `index_refresh`.
+   - Refresh failed or impractical (no write access to the index, prohibitive
+     repo size), or `freshness: accept` was passed → proceed on the stale
+     graph, weight source verification higher, and state the staleness and
+     the skipped refresh in the plan header and Assumptions.
    - Resources unreadable but tools working → proceed on tools alone, treat
      freshness as unknown (weight source higher), and note it in the plan.
    - GitNexus unavailable entirely → switch to **Fallback mode** (below).
@@ -172,6 +183,7 @@ skill-config file mechanism; invocation args are the mechanism):
 | `max_related_symbols` | 20 | Ledger budget (active symbols; discards don't count) |
 | `max_snippet_lines` | 30 | Longest source excerpt quoted in the plan |
 | `out` | `docs/plans/` in target repo | Plan document destination |
+| `freshness` | `strict` | `strict` = refresh a stale index (and a missing PDG layer) with `analyze --index-only [--pdg]` before relying on the graph; `accept` = plan on the stale graph, source-weighted and labelled |
 
 ## Fallback mode (GitNexus or PDG unavailable)
 
@@ -180,5 +192,5 @@ skill-config file mechanism; invocation args are the mechanism):
    dependencies, execution flow, state changes, and related tests.
 3. Label every such finding **source-derived** in the plan — never present it
    as graph-derived, and never fabricate statement-level edges.
-4. Recommend `node .gitnexus/run.cjs analyze` (add `--pdg` for the PDG layers)
-   when it would materially raise confidence.
+4. Recommend `node .gitnexus/run.cjs analyze --index-only` (add `--pdg` for
+   the PDG layers) when it would materially raise confidence.

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

@@ -20,6 +20,10 @@ context_ledger:
   verified_at_commit: ""         # target repo HEAD, recorded once in Phase 1;
                                  # 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
+
   established_facts: []          # each with its evidence source
 
   symbols:                       # budgets count active (primary/related) only;

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

@@ -27,8 +27,13 @@ Contract caveats that shape interpretation:
 - Every `switch` case arm is `'T'` (per-case conditions not distinguished).
 - No `--pdg` layer → the tools return a "no PDG layer" note, not an error.
   The note is repo-wide: one probe settles it — do not re-probe per function.
-  Record it, skip the slice, recommend `analyze --pdg`. Do not reconstruct
-  edges from source by hand.
+  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
+  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.
 
 ## Inclusion criteria
 

.claude/skills/gitnexus-plan/references/plan-template.md

@@ -14,7 +14,7 @@ narrative, not evidence.
 # GitNexus Engineering Plan
 
 > Task: <one line>
-> Evidence verified at commit <HEAD sha>; GitNexus index <fresh | N commits behind | not used>.
+> Evidence verified at commit <HEAD sha>; GitNexus index <fresh | refreshed this session (--index-only [--pdg]) | N commits behind, refresh skipped: <reason> | not used>.
 
 ## 1. Objective