diff --git a/.claude/skills/gitnexus-plan/README.md b/.claude/skills/gitnexus-plan/README.md index acd189573..b1e6dd9c1 100644 --- a/.claude/skills/gitnexus-plan/README.md +++ b/.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. diff --git a/.claude/skills/gitnexus-plan/SKILL.md b/.claude/skills/gitnexus-plan/SKILL.md index 5a9c281cd..27fdd4865 100644 --- a/.claude/skills/gitnexus-plan/SKILL.md +++ b/.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. diff --git a/.claude/skills/gitnexus-plan/references/context-ledger.md b/.claude/skills/gitnexus-plan/references/context-ledger.md index caf5bdc9f..af22f341f 100644 --- a/.claude/skills/gitnexus-plan/references/context-ledger.md +++ b/.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: "); + # at most one per planning session + established_facts: [] # each with its evidence source symbols: # budgets count active (primary/related) only; diff --git a/.claude/skills/gitnexus-plan/references/pdg-slice.md b/.claude/skills/gitnexus-plan/references/pdg-slice.md index f8b98ad16..3ed142a8e 100644 --- a/.claude/skills/gitnexus-plan/references/pdg-slice.md +++ b/.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 diff --git a/.claude/skills/gitnexus-plan/references/plan-template.md b/.claude/skills/gitnexus-plan/references/plan-template.md index f17c0d920..64eed916e 100644 --- a/.claude/skills/gitnexus-plan/references/plan-template.md +++ b/.claude/skills/gitnexus-plan/references/plan-template.md @@ -14,7 +14,7 @@ narrative, not evidence. # GitNexus Engineering Plan > Task: -> Evidence verified at commit ; GitNexus index . +> Evidence verified at commit ; GitNexus index | not used>. ## 1. Objective