diff --git a/.claude/skills/gitnexus-lfg/SKILL.md b/.claude/skills/gitnexus-lfg/SKILL.md index 97c81f371..4046907e2 100644 --- a/.claude/skills/gitnexus-lfg/SKILL.md +++ b/.claude/skills/gitnexus-lfg/SKILL.md @@ -18,9 +18,16 @@ never inline a summary of what the skill would have done. ## Lane 1 — Plan -Invoke `gitnexus-plan` with the task (knob overrides pass through verbatim). -If the input is already a plan file path, skip to Lane 2. The plan lands in -`docs/plans/` — record its path; every later lane consumes it. +**Boundary triage first.** If the task is plainly below the planning +boundary — trivial or small-bounded work an agent finishes in well under ~35 +turns (the measured regime where a planning pass costs more than it returns; +see `eval/workflow_bench/`) — say so and offer `gitnexus-work` direct mode as +an alternative to the full pipeline before spending the plan lane. Honor the +user's choice. + +Otherwise invoke `gitnexus-plan` with the task (knob overrides pass through +verbatim). If the input is already a plan file path, skip to Lane 2. The plan +lands in `docs/plans/` — record its path; every later lane consumes it. ## Lane 2 — The plan gate (user choice, blocking) diff --git a/.claude/skills/gitnexus-plan/README.md b/.claude/skills/gitnexus-plan/README.md index 902346439..f6ef9f0a6 100644 --- a/.claude/skills/gitnexus-plan/README.md +++ b/.claude/skills/gitnexus-plan/README.md @@ -90,11 +90,15 @@ of context until the phase that needs them. - 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 with +- Freshness is a gate, priced by category: full-plan categories (refactor, + security, performance, concurrency, architecture) default to `freshness: + strict` — a stale index (or missing PDG layer) is refreshed once with `analyze --index-only [--pdg]` — run via `node .gitnexus/run.cjs` when the project has one, else the installed `gitnexus` CLI (`npm install -g gitnexus`), else `npx gitnexus` — before the graph is relied on. + Compact-plan categories default to `accept` (source-weighted, refresh only + if a graph claim becomes load-bearing) because the refresh is the largest + fixed cost a planning session carries (measured: `eval/workflow_bench/`). `--index-only` touches only the `.gitnexus` store, never repo 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 diff --git a/.claude/skills/gitnexus-plan/SKILL.md b/.claude/skills/gitnexus-plan/SKILL.md index 647d06c61..de5d7cac4 100644 --- a/.claude/skills/gitnexus-plan/SKILL.md +++ b/.claude/skills/gitnexus-plan/SKILL.md @@ -50,22 +50,28 @@ never repo files) and the analyzer `dist/` rebuild that may precede it Read `references/context-ledger.md` and open the ledger with the task: original request, interpreted goal, acceptance criteria. Classify the task: -| Category | Depth posture | +| Category | Posture (depth · plan form · tool-call budget · freshness) | | --- | --- | -| Bug fix (local) | Narrow: 1–2 primary symbols, `impact_depth` 1 | -| Feature | Default knobs | -| Refactor / shared API change | Impact analysis mandatory, `impact_depth` 3 | -| Performance | Default + performance PDG mode (see `references/pdg-slice.md`) | -| Security | Default + security PDG mode + `explain` taint findings | -| Dependency upgrade / migration | Impact + compatibility focus; PDG usually unnecessary | -| Concurrency / transactional | Control-flow and state-mutation focus in the PDG slice | -| Test improvement / docs | Narrowest: usually no impact or PDG pass | -| Architecture change / spike | Widest: clusters + processes resources first | +| Bug fix (local) | Narrow, 1–2 primary symbols, `impact_depth` 1 · compact · ~15 · accept | +| Feature | Default knobs · compact · ~30 · accept | +| Refactor / shared API change | Impact mandatory, `impact_depth` 3 · full · ~45 · strict | +| Performance | Default + performance PDG mode (`references/pdg-slice.md`) · full · ~45 · strict | +| Security | Default + security PDG mode + `explain` taint findings · full · ~45 · strict | +| Dependency upgrade / migration | Impact + compatibility focus; PDG rarely needed · compact · ~20 · accept | +| Concurrency / transactional | Control-flow + state-mutation PDG focus · full · ~45 · strict | +| Test improvement / docs | Narrowest: usually no impact or PDG pass · compact · ~10 · accept | +| Architecture change / spike | Widest: clusters + processes first · full · no cap · strict | The category posture overrides the Configuration baseline; explicit `key:value` invocation knobs override both. A task matching several rows combines them: take the widest depth, union the focus areas. +**Turn economy is a deliverable.** The plan is judged on decision quality per +token, not thoroughness theater (measured: a 63-turn plan for a two-line +change — see `eval/workflow_bench/`). Stay within the category's tool-call +budget; when the budget runs out with questions still open, record them in +§12 instead of digging further — the executor re-verifies cheaply anyway. + ## Phase 1 — Anchor and freshness 1. Resolve the target repo: `list_repos` if in doubt, else the indexed repo @@ -80,8 +86,15 @@ take the widest depth, union the focus areas. `npx gitnexus analyze …`. 4. Read `gitnexus://repo/{name}/context` — codebase overview + staleness check. **Freshness gate.** Plans built on a stale graph make stale blast-radius - claims, so freshness is not advisory here. Under `freshness: strict` (the - default): + claims — but a refresh (analyzer rebuild + re-index) is the single + largest fixed cost a planning session carries (measured in + `eval/workflow_bench/`), so the gate is category-priced: + - Compact-plan categories default to `freshness: accept`: plan on the + current graph with source verification weighted higher — their plans + cite little graph evidence. Escalate to a refresh mid-plan only when a + graph claim becomes load-bearing (e.g. Proposed Changes rest on a d=1 + dependent list), and only then. + - Full-plan categories default to `freshness: strict`, and under it: - **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 @@ -150,7 +163,9 @@ GitNexus said where to look; now confirm what is there. Using ordinary file reads (exact line ranges, not whole files unless genuinely required): - Read every source range the plan will cite: signatures, branch conditions, - state mutations, error paths, nearby comments that change behavior. + state mutations, error paths, nearby comments that change behavior. Compact + plans cite less — verify what they cite, don't expand the citation set to + have more to verify. - Read the tests GitNexus associated with the primary symbols; never claim a test exists without having located it. - Verify the build/test commands the plan will name actually exist @@ -171,9 +186,11 @@ and executable behavior → compiler/build/lint output → GitNexus graph and PD ## Phase 5 — Compose the plan -1. Read `references/plan-template.md` and fill all 13 sections from the - ledger, tagging claims with the template's four classes — `[verified]`, - `[graph]`, `[inferred]`, `[assumed]` — and routing open questions to §12. +1. Read `references/plan-template.md` and fill the category's form — compact + (core sections, ≤80 lines excluding the pack) or full (all 13 sections) — + from the ledger, tagging claims with the template's four classes — + `[verified]`, `[graph]`, `[inferred]`, `[assumed]` — and routing open + questions to §12. 2. Build the implementation context pack per `references/context-pack.md` (this is section 11 of the plan). 3. Write the document to `docs/plans/YYYY-MM-DD-gitnexus-plan-.md` under the @@ -224,6 +241,7 @@ skill-config file mechanism; invocation args are the mechanism): | Knob | Default | Meaning | | --- | --- | --- | | `depth` | by category | `narrow` = `impact_depth` 1, PDG only if one function is clearly central; `default` = this table; `deep` = `impact_depth` 3 + clusters/processes read | +| `form` | by category | `compact` (core sections + mini-pack, ≤80 lines excl. pack — see `references/plan-template.md`) or `full` (all 13 sections) | | `impact_depth` | 2 | `maxDepth` for `impact` | | `pdg_data_depth` | 2 | Data-dependence hops in the PDG slice | | `pdg_control_depth` | 2 | Control-dependence hops in the PDG slice | @@ -231,7 +249,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 | +| `freshness` | by category | `strict` (full-plan categories) = refresh a stale index (and a missing PDG layer) with `analyze --index-only [--pdg]` before relying on the graph; `accept` (compact categories) = plan on the current graph, source-weighted and labelled, refreshing only if a graph claim becomes load-bearing | ## Fallback mode (GitNexus or PDG unavailable) diff --git a/.claude/skills/gitnexus-plan/references/context-pack.md b/.claude/skills/gitnexus-plan/references/context-pack.md index 46dd00385..394d4e50f 100644 --- a/.claude/skills/gitnexus-plan/references/context-pack.md +++ b/.claude/skills/gitnexus-plan/references/context-pack.md @@ -5,6 +5,12 @@ implementation agent (`gitnexus-work`, or any executor) consumes to start work **without repeating the investigation**. Distilled from the ledger; every entry traceable to verified evidence. +**Compact plans emit the mini-pack** — only: `task_summary`, +`files_to_modify`, `tests`, `verification_commands`, `pdg_constraints` (only +when a slice actually ran), `assumptions`, `open_questions`, `avoid`. Full +plans emit every field. Field semantics are identical in both; +`gitnexus-work` treats absent optional fields as empty, not as errors. + ## Schema ```yaml diff --git a/.claude/skills/gitnexus-plan/references/plan-template.md b/.claude/skills/gitnexus-plan/references/plan-template.md index 64eed916e..da21683e5 100644 --- a/.claude/skills/gitnexus-plan/references/plan-template.md +++ b/.claude/skills/gitnexus-plan/references/plan-template.md @@ -1,8 +1,41 @@ # Plan document template -Fill every section. If a section is genuinely empty for this task (e.g. no PDG -layer indexed), keep the heading and state why in one line — never silently -drop it. Repo-relative paths for all repo artifacts. +Two forms, chosen by the Phase 0 category (`form` knob overrides): **compact** +for narrow/default work, **full** for deep work. Repo-relative paths for all +repo artifacts in both. + +## Compact form + +Same evidence header, then only the load-bearing sections — keep the § +numbers in the headings so `gitnexus-work`'s § references resolve: + +```markdown +# GitNexus Engineering Plan + +> Task: +> Evidence verified at commit ; GitNexus index <...>. + +## Objective (§1) +## Current Behaviour (§2–3) — ≤10 lines, architecture folded in +## Findings (§4–5) — only load-bearing, each tagged + tool-named +## Proposed Changes (§6) +## Implementation Sequence (§7) — risks inline as step notes +## Test Strategy (§8) +## Implementation Context (§11) — the mini-pack (see context-pack.md) +## Assumptions and Open Questions (§12) +## Definition of Done (§13) +``` + +Hard cap: **80 lines excluding the §11 pack**. Anything cut that still +matters becomes one line in §12 — never padded prose. A compact plan that +outgrows the cap is a signal the task was misclassified: reclassify to full +rather than overflowing. + +## Full form + +Fill every section below. If a section is genuinely empty for this task +(e.g. no PDG layer indexed), keep the heading and state why in one line — +never silently drop it. **Claim tagging.** Tag every load-bearing claim with its evidence class: `[verified]` (source-read at the pinned commit), `[graph]` (GitNexus/PDG diff --git a/.claude/skills/gitnexus-work/SKILL.md b/.claude/skills/gitnexus-work/SKILL.md index 4f8d789f2..fb81fb53c 100644 --- a/.claude/skills/gitnexus-work/SKILL.md +++ b/.claude/skills/gitnexus-work/SKILL.md @@ -40,8 +40,12 @@ executor counterpart to the planning-only `gitnexus-plan`. `primary_symbols`, `related_symbols`, `files_to_modify`, `execution_path`, `pdg_constraints`, `architectural_patterns`, `tests`, `verification_commands`, `risks`, `assumptions`, `open_questions`, `avoid`. + Compact plans carry the mini-pack subset — absent optional fields are + empty, not errors. 3. **Drift check.** The plan header pins the commit its evidence was - verified at. If HEAD has moved since, diff the pinned commit against HEAD + verified at. **HEAD equals the pin → every citation is still verified: + skip all re-reading and go straight to work — that is the pin's entire + point.** If HEAD has moved since, diff the pinned commit against HEAD for **every file the pack cites** — `files_to_modify`, `primary_symbols`/`related_symbols` files, files named in `pdg_constraints.affected_statements`, `architectural_patterns[]` diff --git a/gitnexus-claude-plugin/skills/gitnexus-lfg/SKILL.md b/gitnexus-claude-plugin/skills/gitnexus-lfg/SKILL.md index 97c81f371..4046907e2 100644 --- a/gitnexus-claude-plugin/skills/gitnexus-lfg/SKILL.md +++ b/gitnexus-claude-plugin/skills/gitnexus-lfg/SKILL.md @@ -18,9 +18,16 @@ never inline a summary of what the skill would have done. ## Lane 1 — Plan -Invoke `gitnexus-plan` with the task (knob overrides pass through verbatim). -If the input is already a plan file path, skip to Lane 2. The plan lands in -`docs/plans/` — record its path; every later lane consumes it. +**Boundary triage first.** If the task is plainly below the planning +boundary — trivial or small-bounded work an agent finishes in well under ~35 +turns (the measured regime where a planning pass costs more than it returns; +see `eval/workflow_bench/`) — say so and offer `gitnexus-work` direct mode as +an alternative to the full pipeline before spending the plan lane. Honor the +user's choice. + +Otherwise invoke `gitnexus-plan` with the task (knob overrides pass through +verbatim). If the input is already a plan file path, skip to Lane 2. The plan +lands in `docs/plans/` — record its path; every later lane consumes it. ## Lane 2 — The plan gate (user choice, blocking) diff --git a/gitnexus-claude-plugin/skills/gitnexus-plan/README.md b/gitnexus-claude-plugin/skills/gitnexus-plan/README.md index 902346439..f6ef9f0a6 100644 --- a/gitnexus-claude-plugin/skills/gitnexus-plan/README.md +++ b/gitnexus-claude-plugin/skills/gitnexus-plan/README.md @@ -90,11 +90,15 @@ of context until the phase that needs them. - 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 with +- Freshness is a gate, priced by category: full-plan categories (refactor, + security, performance, concurrency, architecture) default to `freshness: + strict` — a stale index (or missing PDG layer) is refreshed once with `analyze --index-only [--pdg]` — run via `node .gitnexus/run.cjs` when the project has one, else the installed `gitnexus` CLI (`npm install -g gitnexus`), else `npx gitnexus` — before the graph is relied on. + Compact-plan categories default to `accept` (source-weighted, refresh only + if a graph claim becomes load-bearing) because the refresh is the largest + fixed cost a planning session carries (measured: `eval/workflow_bench/`). `--index-only` touches only the `.gitnexus` store, never repo 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 diff --git a/gitnexus-claude-plugin/skills/gitnexus-plan/SKILL.md b/gitnexus-claude-plugin/skills/gitnexus-plan/SKILL.md index 647d06c61..de5d7cac4 100644 --- a/gitnexus-claude-plugin/skills/gitnexus-plan/SKILL.md +++ b/gitnexus-claude-plugin/skills/gitnexus-plan/SKILL.md @@ -50,22 +50,28 @@ never repo files) and the analyzer `dist/` rebuild that may precede it Read `references/context-ledger.md` and open the ledger with the task: original request, interpreted goal, acceptance criteria. Classify the task: -| Category | Depth posture | +| Category | Posture (depth · plan form · tool-call budget · freshness) | | --- | --- | -| Bug fix (local) | Narrow: 1–2 primary symbols, `impact_depth` 1 | -| Feature | Default knobs | -| Refactor / shared API change | Impact analysis mandatory, `impact_depth` 3 | -| Performance | Default + performance PDG mode (see `references/pdg-slice.md`) | -| Security | Default + security PDG mode + `explain` taint findings | -| Dependency upgrade / migration | Impact + compatibility focus; PDG usually unnecessary | -| Concurrency / transactional | Control-flow and state-mutation focus in the PDG slice | -| Test improvement / docs | Narrowest: usually no impact or PDG pass | -| Architecture change / spike | Widest: clusters + processes resources first | +| Bug fix (local) | Narrow, 1–2 primary symbols, `impact_depth` 1 · compact · ~15 · accept | +| Feature | Default knobs · compact · ~30 · accept | +| Refactor / shared API change | Impact mandatory, `impact_depth` 3 · full · ~45 · strict | +| Performance | Default + performance PDG mode (`references/pdg-slice.md`) · full · ~45 · strict | +| Security | Default + security PDG mode + `explain` taint findings · full · ~45 · strict | +| Dependency upgrade / migration | Impact + compatibility focus; PDG rarely needed · compact · ~20 · accept | +| Concurrency / transactional | Control-flow + state-mutation PDG focus · full · ~45 · strict | +| Test improvement / docs | Narrowest: usually no impact or PDG pass · compact · ~10 · accept | +| Architecture change / spike | Widest: clusters + processes first · full · no cap · strict | The category posture overrides the Configuration baseline; explicit `key:value` invocation knobs override both. A task matching several rows combines them: take the widest depth, union the focus areas. +**Turn economy is a deliverable.** The plan is judged on decision quality per +token, not thoroughness theater (measured: a 63-turn plan for a two-line +change — see `eval/workflow_bench/`). Stay within the category's tool-call +budget; when the budget runs out with questions still open, record them in +§12 instead of digging further — the executor re-verifies cheaply anyway. + ## Phase 1 — Anchor and freshness 1. Resolve the target repo: `list_repos` if in doubt, else the indexed repo @@ -80,8 +86,15 @@ take the widest depth, union the focus areas. `npx gitnexus analyze …`. 4. Read `gitnexus://repo/{name}/context` — codebase overview + staleness check. **Freshness gate.** Plans built on a stale graph make stale blast-radius - claims, so freshness is not advisory here. Under `freshness: strict` (the - default): + claims — but a refresh (analyzer rebuild + re-index) is the single + largest fixed cost a planning session carries (measured in + `eval/workflow_bench/`), so the gate is category-priced: + - Compact-plan categories default to `freshness: accept`: plan on the + current graph with source verification weighted higher — their plans + cite little graph evidence. Escalate to a refresh mid-plan only when a + graph claim becomes load-bearing (e.g. Proposed Changes rest on a d=1 + dependent list), and only then. + - Full-plan categories default to `freshness: strict`, and under it: - **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 @@ -150,7 +163,9 @@ GitNexus said where to look; now confirm what is there. Using ordinary file reads (exact line ranges, not whole files unless genuinely required): - Read every source range the plan will cite: signatures, branch conditions, - state mutations, error paths, nearby comments that change behavior. + state mutations, error paths, nearby comments that change behavior. Compact + plans cite less — verify what they cite, don't expand the citation set to + have more to verify. - Read the tests GitNexus associated with the primary symbols; never claim a test exists without having located it. - Verify the build/test commands the plan will name actually exist @@ -171,9 +186,11 @@ and executable behavior → compiler/build/lint output → GitNexus graph and PD ## Phase 5 — Compose the plan -1. Read `references/plan-template.md` and fill all 13 sections from the - ledger, tagging claims with the template's four classes — `[verified]`, - `[graph]`, `[inferred]`, `[assumed]` — and routing open questions to §12. +1. Read `references/plan-template.md` and fill the category's form — compact + (core sections, ≤80 lines excluding the pack) or full (all 13 sections) — + from the ledger, tagging claims with the template's four classes — + `[verified]`, `[graph]`, `[inferred]`, `[assumed]` — and routing open + questions to §12. 2. Build the implementation context pack per `references/context-pack.md` (this is section 11 of the plan). 3. Write the document to `docs/plans/YYYY-MM-DD-gitnexus-plan-.md` under the @@ -224,6 +241,7 @@ skill-config file mechanism; invocation args are the mechanism): | Knob | Default | Meaning | | --- | --- | --- | | `depth` | by category | `narrow` = `impact_depth` 1, PDG only if one function is clearly central; `default` = this table; `deep` = `impact_depth` 3 + clusters/processes read | +| `form` | by category | `compact` (core sections + mini-pack, ≤80 lines excl. pack — see `references/plan-template.md`) or `full` (all 13 sections) | | `impact_depth` | 2 | `maxDepth` for `impact` | | `pdg_data_depth` | 2 | Data-dependence hops in the PDG slice | | `pdg_control_depth` | 2 | Control-dependence hops in the PDG slice | @@ -231,7 +249,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 | +| `freshness` | by category | `strict` (full-plan categories) = refresh a stale index (and a missing PDG layer) with `analyze --index-only [--pdg]` before relying on the graph; `accept` (compact categories) = plan on the current graph, source-weighted and labelled, refreshing only if a graph claim becomes load-bearing | ## Fallback mode (GitNexus or PDG unavailable) diff --git a/gitnexus-claude-plugin/skills/gitnexus-plan/references/context-pack.md b/gitnexus-claude-plugin/skills/gitnexus-plan/references/context-pack.md index 46dd00385..394d4e50f 100644 --- a/gitnexus-claude-plugin/skills/gitnexus-plan/references/context-pack.md +++ b/gitnexus-claude-plugin/skills/gitnexus-plan/references/context-pack.md @@ -5,6 +5,12 @@ implementation agent (`gitnexus-work`, or any executor) consumes to start work **without repeating the investigation**. Distilled from the ledger; every entry traceable to verified evidence. +**Compact plans emit the mini-pack** — only: `task_summary`, +`files_to_modify`, `tests`, `verification_commands`, `pdg_constraints` (only +when a slice actually ran), `assumptions`, `open_questions`, `avoid`. Full +plans emit every field. Field semantics are identical in both; +`gitnexus-work` treats absent optional fields as empty, not as errors. + ## Schema ```yaml diff --git a/gitnexus-claude-plugin/skills/gitnexus-plan/references/plan-template.md b/gitnexus-claude-plugin/skills/gitnexus-plan/references/plan-template.md index 64eed916e..da21683e5 100644 --- a/gitnexus-claude-plugin/skills/gitnexus-plan/references/plan-template.md +++ b/gitnexus-claude-plugin/skills/gitnexus-plan/references/plan-template.md @@ -1,8 +1,41 @@ # Plan document template -Fill every section. If a section is genuinely empty for this task (e.g. no PDG -layer indexed), keep the heading and state why in one line — never silently -drop it. Repo-relative paths for all repo artifacts. +Two forms, chosen by the Phase 0 category (`form` knob overrides): **compact** +for narrow/default work, **full** for deep work. Repo-relative paths for all +repo artifacts in both. + +## Compact form + +Same evidence header, then only the load-bearing sections — keep the § +numbers in the headings so `gitnexus-work`'s § references resolve: + +```markdown +# GitNexus Engineering Plan + +> Task: +> Evidence verified at commit ; GitNexus index <...>. + +## Objective (§1) +## Current Behaviour (§2–3) — ≤10 lines, architecture folded in +## Findings (§4–5) — only load-bearing, each tagged + tool-named +## Proposed Changes (§6) +## Implementation Sequence (§7) — risks inline as step notes +## Test Strategy (§8) +## Implementation Context (§11) — the mini-pack (see context-pack.md) +## Assumptions and Open Questions (§12) +## Definition of Done (§13) +``` + +Hard cap: **80 lines excluding the §11 pack**. Anything cut that still +matters becomes one line in §12 — never padded prose. A compact plan that +outgrows the cap is a signal the task was misclassified: reclassify to full +rather than overflowing. + +## Full form + +Fill every section below. If a section is genuinely empty for this task +(e.g. no PDG layer indexed), keep the heading and state why in one line — +never silently drop it. **Claim tagging.** Tag every load-bearing claim with its evidence class: `[verified]` (source-read at the pinned commit), `[graph]` (GitNexus/PDG diff --git a/gitnexus-claude-plugin/skills/gitnexus-work/SKILL.md b/gitnexus-claude-plugin/skills/gitnexus-work/SKILL.md index 4f8d789f2..fb81fb53c 100644 --- a/gitnexus-claude-plugin/skills/gitnexus-work/SKILL.md +++ b/gitnexus-claude-plugin/skills/gitnexus-work/SKILL.md @@ -40,8 +40,12 @@ executor counterpart to the planning-only `gitnexus-plan`. `primary_symbols`, `related_symbols`, `files_to_modify`, `execution_path`, `pdg_constraints`, `architectural_patterns`, `tests`, `verification_commands`, `risks`, `assumptions`, `open_questions`, `avoid`. + Compact plans carry the mini-pack subset — absent optional fields are + empty, not errors. 3. **Drift check.** The plan header pins the commit its evidence was - verified at. If HEAD has moved since, diff the pinned commit against HEAD + verified at. **HEAD equals the pin → every citation is still verified: + skip all re-reading and go straight to work — that is the pin's entire + point.** If HEAD has moved since, diff the pinned commit against HEAD for **every file the pack cites** — `files_to_modify`, `primary_symbols`/`related_symbols` files, files named in `pdg_constraints.affected_statements`, `architectural_patterns[]` diff --git a/gitnexus/skills/gitnexus-lfg/SKILL.md b/gitnexus/skills/gitnexus-lfg/SKILL.md index 97c81f371..4046907e2 100644 --- a/gitnexus/skills/gitnexus-lfg/SKILL.md +++ b/gitnexus/skills/gitnexus-lfg/SKILL.md @@ -18,9 +18,16 @@ never inline a summary of what the skill would have done. ## Lane 1 — Plan -Invoke `gitnexus-plan` with the task (knob overrides pass through verbatim). -If the input is already a plan file path, skip to Lane 2. The plan lands in -`docs/plans/` — record its path; every later lane consumes it. +**Boundary triage first.** If the task is plainly below the planning +boundary — trivial or small-bounded work an agent finishes in well under ~35 +turns (the measured regime where a planning pass costs more than it returns; +see `eval/workflow_bench/`) — say so and offer `gitnexus-work` direct mode as +an alternative to the full pipeline before spending the plan lane. Honor the +user's choice. + +Otherwise invoke `gitnexus-plan` with the task (knob overrides pass through +verbatim). If the input is already a plan file path, skip to Lane 2. The plan +lands in `docs/plans/` — record its path; every later lane consumes it. ## Lane 2 — The plan gate (user choice, blocking) diff --git a/gitnexus/skills/gitnexus-plan/README.md b/gitnexus/skills/gitnexus-plan/README.md index 902346439..f6ef9f0a6 100644 --- a/gitnexus/skills/gitnexus-plan/README.md +++ b/gitnexus/skills/gitnexus-plan/README.md @@ -90,11 +90,15 @@ of context until the phase that needs them. - 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 with +- Freshness is a gate, priced by category: full-plan categories (refactor, + security, performance, concurrency, architecture) default to `freshness: + strict` — a stale index (or missing PDG layer) is refreshed once with `analyze --index-only [--pdg]` — run via `node .gitnexus/run.cjs` when the project has one, else the installed `gitnexus` CLI (`npm install -g gitnexus`), else `npx gitnexus` — before the graph is relied on. + Compact-plan categories default to `accept` (source-weighted, refresh only + if a graph claim becomes load-bearing) because the refresh is the largest + fixed cost a planning session carries (measured: `eval/workflow_bench/`). `--index-only` touches only the `.gitnexus` store, never repo 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 diff --git a/gitnexus/skills/gitnexus-plan/SKILL.md b/gitnexus/skills/gitnexus-plan/SKILL.md index 647d06c61..de5d7cac4 100644 --- a/gitnexus/skills/gitnexus-plan/SKILL.md +++ b/gitnexus/skills/gitnexus-plan/SKILL.md @@ -50,22 +50,28 @@ never repo files) and the analyzer `dist/` rebuild that may precede it Read `references/context-ledger.md` and open the ledger with the task: original request, interpreted goal, acceptance criteria. Classify the task: -| Category | Depth posture | +| Category | Posture (depth · plan form · tool-call budget · freshness) | | --- | --- | -| Bug fix (local) | Narrow: 1–2 primary symbols, `impact_depth` 1 | -| Feature | Default knobs | -| Refactor / shared API change | Impact analysis mandatory, `impact_depth` 3 | -| Performance | Default + performance PDG mode (see `references/pdg-slice.md`) | -| Security | Default + security PDG mode + `explain` taint findings | -| Dependency upgrade / migration | Impact + compatibility focus; PDG usually unnecessary | -| Concurrency / transactional | Control-flow and state-mutation focus in the PDG slice | -| Test improvement / docs | Narrowest: usually no impact or PDG pass | -| Architecture change / spike | Widest: clusters + processes resources first | +| Bug fix (local) | Narrow, 1–2 primary symbols, `impact_depth` 1 · compact · ~15 · accept | +| Feature | Default knobs · compact · ~30 · accept | +| Refactor / shared API change | Impact mandatory, `impact_depth` 3 · full · ~45 · strict | +| Performance | Default + performance PDG mode (`references/pdg-slice.md`) · full · ~45 · strict | +| Security | Default + security PDG mode + `explain` taint findings · full · ~45 · strict | +| Dependency upgrade / migration | Impact + compatibility focus; PDG rarely needed · compact · ~20 · accept | +| Concurrency / transactional | Control-flow + state-mutation PDG focus · full · ~45 · strict | +| Test improvement / docs | Narrowest: usually no impact or PDG pass · compact · ~10 · accept | +| Architecture change / spike | Widest: clusters + processes first · full · no cap · strict | The category posture overrides the Configuration baseline; explicit `key:value` invocation knobs override both. A task matching several rows combines them: take the widest depth, union the focus areas. +**Turn economy is a deliverable.** The plan is judged on decision quality per +token, not thoroughness theater (measured: a 63-turn plan for a two-line +change — see `eval/workflow_bench/`). Stay within the category's tool-call +budget; when the budget runs out with questions still open, record them in +§12 instead of digging further — the executor re-verifies cheaply anyway. + ## Phase 1 — Anchor and freshness 1. Resolve the target repo: `list_repos` if in doubt, else the indexed repo @@ -80,8 +86,15 @@ take the widest depth, union the focus areas. `npx gitnexus analyze …`. 4. Read `gitnexus://repo/{name}/context` — codebase overview + staleness check. **Freshness gate.** Plans built on a stale graph make stale blast-radius - claims, so freshness is not advisory here. Under `freshness: strict` (the - default): + claims — but a refresh (analyzer rebuild + re-index) is the single + largest fixed cost a planning session carries (measured in + `eval/workflow_bench/`), so the gate is category-priced: + - Compact-plan categories default to `freshness: accept`: plan on the + current graph with source verification weighted higher — their plans + cite little graph evidence. Escalate to a refresh mid-plan only when a + graph claim becomes load-bearing (e.g. Proposed Changes rest on a d=1 + dependent list), and only then. + - Full-plan categories default to `freshness: strict`, and under it: - **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 @@ -150,7 +163,9 @@ GitNexus said where to look; now confirm what is there. Using ordinary file reads (exact line ranges, not whole files unless genuinely required): - Read every source range the plan will cite: signatures, branch conditions, - state mutations, error paths, nearby comments that change behavior. + state mutations, error paths, nearby comments that change behavior. Compact + plans cite less — verify what they cite, don't expand the citation set to + have more to verify. - Read the tests GitNexus associated with the primary symbols; never claim a test exists without having located it. - Verify the build/test commands the plan will name actually exist @@ -171,9 +186,11 @@ and executable behavior → compiler/build/lint output → GitNexus graph and PD ## Phase 5 — Compose the plan -1. Read `references/plan-template.md` and fill all 13 sections from the - ledger, tagging claims with the template's four classes — `[verified]`, - `[graph]`, `[inferred]`, `[assumed]` — and routing open questions to §12. +1. Read `references/plan-template.md` and fill the category's form — compact + (core sections, ≤80 lines excluding the pack) or full (all 13 sections) — + from the ledger, tagging claims with the template's four classes — + `[verified]`, `[graph]`, `[inferred]`, `[assumed]` — and routing open + questions to §12. 2. Build the implementation context pack per `references/context-pack.md` (this is section 11 of the plan). 3. Write the document to `docs/plans/YYYY-MM-DD-gitnexus-plan-.md` under the @@ -224,6 +241,7 @@ skill-config file mechanism; invocation args are the mechanism): | Knob | Default | Meaning | | --- | --- | --- | | `depth` | by category | `narrow` = `impact_depth` 1, PDG only if one function is clearly central; `default` = this table; `deep` = `impact_depth` 3 + clusters/processes read | +| `form` | by category | `compact` (core sections + mini-pack, ≤80 lines excl. pack — see `references/plan-template.md`) or `full` (all 13 sections) | | `impact_depth` | 2 | `maxDepth` for `impact` | | `pdg_data_depth` | 2 | Data-dependence hops in the PDG slice | | `pdg_control_depth` | 2 | Control-dependence hops in the PDG slice | @@ -231,7 +249,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 | +| `freshness` | by category | `strict` (full-plan categories) = refresh a stale index (and a missing PDG layer) with `analyze --index-only [--pdg]` before relying on the graph; `accept` (compact categories) = plan on the current graph, source-weighted and labelled, refreshing only if a graph claim becomes load-bearing | ## Fallback mode (GitNexus or PDG unavailable) diff --git a/gitnexus/skills/gitnexus-plan/references/context-pack.md b/gitnexus/skills/gitnexus-plan/references/context-pack.md index 46dd00385..394d4e50f 100644 --- a/gitnexus/skills/gitnexus-plan/references/context-pack.md +++ b/gitnexus/skills/gitnexus-plan/references/context-pack.md @@ -5,6 +5,12 @@ implementation agent (`gitnexus-work`, or any executor) consumes to start work **without repeating the investigation**. Distilled from the ledger; every entry traceable to verified evidence. +**Compact plans emit the mini-pack** — only: `task_summary`, +`files_to_modify`, `tests`, `verification_commands`, `pdg_constraints` (only +when a slice actually ran), `assumptions`, `open_questions`, `avoid`. Full +plans emit every field. Field semantics are identical in both; +`gitnexus-work` treats absent optional fields as empty, not as errors. + ## Schema ```yaml diff --git a/gitnexus/skills/gitnexus-plan/references/plan-template.md b/gitnexus/skills/gitnexus-plan/references/plan-template.md index 64eed916e..da21683e5 100644 --- a/gitnexus/skills/gitnexus-plan/references/plan-template.md +++ b/gitnexus/skills/gitnexus-plan/references/plan-template.md @@ -1,8 +1,41 @@ # Plan document template -Fill every section. If a section is genuinely empty for this task (e.g. no PDG -layer indexed), keep the heading and state why in one line — never silently -drop it. Repo-relative paths for all repo artifacts. +Two forms, chosen by the Phase 0 category (`form` knob overrides): **compact** +for narrow/default work, **full** for deep work. Repo-relative paths for all +repo artifacts in both. + +## Compact form + +Same evidence header, then only the load-bearing sections — keep the § +numbers in the headings so `gitnexus-work`'s § references resolve: + +```markdown +# GitNexus Engineering Plan + +> Task: +> Evidence verified at commit ; GitNexus index <...>. + +## Objective (§1) +## Current Behaviour (§2–3) — ≤10 lines, architecture folded in +## Findings (§4–5) — only load-bearing, each tagged + tool-named +## Proposed Changes (§6) +## Implementation Sequence (§7) — risks inline as step notes +## Test Strategy (§8) +## Implementation Context (§11) — the mini-pack (see context-pack.md) +## Assumptions and Open Questions (§12) +## Definition of Done (§13) +``` + +Hard cap: **80 lines excluding the §11 pack**. Anything cut that still +matters becomes one line in §12 — never padded prose. A compact plan that +outgrows the cap is a signal the task was misclassified: reclassify to full +rather than overflowing. + +## Full form + +Fill every section below. If a section is genuinely empty for this task +(e.g. no PDG layer indexed), keep the heading and state why in one line — +never silently drop it. **Claim tagging.** Tag every load-bearing claim with its evidence class: `[verified]` (source-read at the pinned commit), `[graph]` (GitNexus/PDG diff --git a/gitnexus/skills/gitnexus-work/SKILL.md b/gitnexus/skills/gitnexus-work/SKILL.md index 4f8d789f2..fb81fb53c 100644 --- a/gitnexus/skills/gitnexus-work/SKILL.md +++ b/gitnexus/skills/gitnexus-work/SKILL.md @@ -40,8 +40,12 @@ executor counterpart to the planning-only `gitnexus-plan`. `primary_symbols`, `related_symbols`, `files_to_modify`, `execution_path`, `pdg_constraints`, `architectural_patterns`, `tests`, `verification_commands`, `risks`, `assumptions`, `open_questions`, `avoid`. + Compact plans carry the mini-pack subset — absent optional fields are + empty, not errors. 3. **Drift check.** The plan header pins the commit its evidence was - verified at. If HEAD has moved since, diff the pinned commit against HEAD + verified at. **HEAD equals the pin → every citation is still verified: + skip all re-reading and go straight to work — that is the pin's entire + point.** If HEAD has moved since, diff the pinned commit against HEAD for **every file the pack cites** — `files_to_modify`, `primary_symbols`/`related_symbols` files, files named in `pdg_constraints.affected_statements`, `architectural_patterns[]`