mirror of
https://github.com/abhigyanpatwari/GitNexus.git
synced 2026-08-28 05:25:25 +00:00
perf(skills): cost-optimize the workflow from measured ground base
Every optimization targets a measured fixed-cost component (eval/workflow_bench ground base: workflow arm −211% to −333% vs baseline, all tasks resolved): - Plan form is category-priced: compact form (core sections w/ § anchors preserved, ≤80 lines excl. pack, mini-pack subset of the context pack) for narrow/default categories; the full 13 sections only for deep work (refactor/security/performance/concurrency/architecture). A compact plan outgrowing its cap reclassifies to full rather than overflowing. - Freshness gate is category-priced: compact categories default to accept (source-weighted, refresh only when a graph claim becomes load-bearing); strict stays the default for full-plan categories — the rebuild+re-index was the largest single fixed cost. - Turn economy: per-category tool-call budgets (~10 to ~45; architecture uncapped); budget exhaustion routes open questions to §12 instead of more digging. - gitnexus-work fast path: HEAD == evidence pin → skip all citation re-reading (the pin's entire point); mini-pack fields tolerated. - lfg Lane 1 boundary triage: tasks below the measured ~35-turn boundary get offered gitnexus-work direct mode before the plan lane is spent. Copies re-synced (npm skills/, plugin, ~/.agents); steering + sync guards green. Re-measurement of the workflow arm follows to verify the numbers actually improve. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Gergo Magyar
parent
987fe9ed11
commit
830a045911
18 changed files with 294 additions and 78 deletions
|
|
@ -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)
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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-<slug>.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)
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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: <one line>
|
||||
> Evidence verified at commit <sha>; 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
|
||||
|
|
|
|||
|
|
@ -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[]`
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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-<slug>.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)
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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: <one line>
|
||||
> Evidence verified at commit <sha>; 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
|
||||
|
|
|
|||
|
|
@ -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[]`
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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-<slug>.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)
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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: <one line>
|
||||
> Evidence verified at commit <sha>; 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
|
||||
|
|
|
|||
|
|
@ -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[]`
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue