gitnexus 1.6.9 → 1.6.10-aptos.0

package/skills/gitnexus-plan/SKILL.md

@@ -0,0 +1,348 @@
+---
+name: gitnexus-plan
+description: 'Use when you need a deep, implementation-ready engineering plan for a code change — built from GitNexus graph intelligence, statement-level PDG analysis, and targeted source verification, compact enough that an implementation agent can start without re-investigating. Also strengthens existing plans via Deepen mode. Examples: "/gitnexus-plan Add retry support to the ingestion pipeline", "/gitnexus-plan deepen docs/plans/<plan>.md", "plan this change using the knowledge graph".'
+---
+
+# gitnexus-plan — implementation-ready engineering plans
+
+Produce an implementation-ready plan for an engineering task. GitNexus is the
+navigation layer (where to look), statement-level PDG is the constraint layer
+(what gates and feeds the behavior), and your native targeted source reads are
+the verification layer (what is actually true right now). The output is a plan
+document plus a compact, machine-readable **implementation context pack**
+that a follow-up implementation agent (`gitnexus-work`, or any executor) can
+consume without repeating the investigation.
+
+```
+/gitnexus-plan <task description>
+/gitnexus-plan impact_depth:3 depth:deep <task description>   # knob overrides, see Configuration
+```
+
+**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). The
+only other permitted state change is an index refresh via
+`analyze --index-only`, which writes only the `.gitnexus` index store. It
+must not build analyzer `dist/` output and must not mutate source, tests,
+configuration, or evaluation data. Stale analyzer provenance is disclosed as
+a source-weighted limitation, never repaired by a planning run.
+
+## Hard rules
+
+- **Ledger first.** Before every GitNexus call and every repo file read, check
+  the context ledger. Never repeat a query or reread an unchanged range that
+  already answered the same question (allowed repeats are defined in
+  `references/context-ledger.md`; this skill's own reference files are exempt
+  from ledger bookkeeping).
+- **Every graph query answers a named planning question.** Record the question
+  and the conclusion in the ledger. No exploratory dredging.
+- **Source beats graph.** The graph navigates; current source is authoritative.
+  Verify before asserting (see Phase 4). Comments are the weakest evidence —
+  never stronger than executable code.
+- **No fabrication.** Never invent symbols, filenames, test names, tool
+  results, or PDG edges. Unknowns go to _Assumptions and Open Questions_.
+- **No scope creep.** Adjacent refactors the task didn't ask for go to plan
+  §12 as explicitly-deferred follow-ups, not into Proposed Changes.
+- **Pin working-tree evidence, not only HEAD.** Every plan form carries the
+  versioned global dirty digest and sorted cited-path manifest defined in
+  `references/context-ledger.md`. Generate it only with the portable helper
+  and byte contract in `scripts/evidence-provenance.mjs` and
+  `references/evidence-provenance.md`; never reimplement the digest.
+- **Write the plan only through the helper.** The generated-plan path is a
+  normalized repo-relative
+  `docs/plans/YYYY-MM-DD-gitnexus-plan-<3-5-word-slug>.md` path. Compose the
+  complete UTF-8 document in memory or in a scratchpad outside the target
+  repo, then pass it on stdin to the helper's `write-plan` command. Never
+  write the destination directly or fall back to an external output path when
+  the safe writer fails.
+- **Read an existing plan only through the helper.** Deepen must invoke
+  `scripts/evidence-provenance.mjs read-plan`, parse the exact decoded
+  `plan_bytes_base64` from its descriptor-anchored receipt, and retain that
+  receipt's canonical `generated_plan_path` and `plan_digest` as one binding.
+  Never parse a direct lexical-path read or apply one plan's digest to another
+  path.
+- **Stop when you have enough.** Sufficient evidence ends exploration; plans
+  do not improve monotonically with tokens spent.
+
+## Phase 0 — Parse and classify
+
+Read `references/context-ledger.md` and open the ledger with the task:
+original request, interpreted goal, acceptance criteria. Classify the task:
+
+| Category                       | Posture (depth · plan form · tool-call budget · freshness)                       |
+| ------------------------------ | -------------------------------------------------------------------------------- |
+| 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.
+
+**Seeded evidence.** When a completed investigation already supplies
+verified findings — a finished review, a triage document with `path:line`
+anchors and named failing scenarios — open the ledger FROM it: cite the
+source document as the opening ledger entries and plan directly against
+them instead of re-running the graph ladder over ground it already covers.
+Re-deriving what the evidence proves is budget spent against the
+turn-economy rule. Phase 4 still source-verifies whatever Proposed Changes
+will cite, at the pinned commit — seeding replaces exploration, never
+verification.
+
+**Depth is the user's decision, asked once, up front.** In an interactive
+session, when the invocation carries no explicit depth signal (no `depth:`,
+`form:`, or `freshness:` knob, and not Deepen mode), ask one blocking
+question before Phase 1 — how deep should this plan go?
+
+1. **Quick** — `depth:narrow form:compact freshness:accept`. Fastest useful
+   plan: 1–2 primary symbols, minimal graph work, core sections only.
+2. **Standard** — the category posture above, unchanged. Recommend this
+   unless the classification argues otherwise.
+3. **Deep** — `depth:deep form:full freshness:strict`. All 13 sections,
+   `impact_depth` 3, clusters/processes read, PDG slices for the central
+   functions.
+
+The answer sets the knobs exactly as if they had been typed in the
+invocation; explicit knobs win and skip the question. Headless runs never
+ask — the category posture applies unchanged. Asking up front replaces
+offering to deepen a finished plan afterwards: Deepen mode (below) remains
+the mechanism for strengthening an existing plan document — a later session,
+review findings, an executor route-back — not a default follow-up question.
+
+**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 — the GitNexus repo's `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
+   covering the working directory. Pass `repo` explicitly on every call when
+   more than one repo is indexed.
+2. Record the repo's current HEAD commit in the ledger — every line-number
+   citation in the plan is pinned to it.
+3. **Resolve and record the analyzer runner** (used by every `analyze`
+   command in this skill): `node .gitnexus/run.cjs analyze …` when the
+   project has a runner (a previous analyze dropped it next to the index),
+   else `gitnexus analyze …` (installed CLI — `npm install -g gitnexus`),
+   else `npx gitnexus analyze …`. Record its path/version and any available
+   source/build identity; do not manufacture provenance from timestamps.
+4. Read `gitnexus://repo/{name}/context` — codebase overview + staleness check.
+   **Freshness gate.** Plans built on a stale graph make stale blast-radius
+   claims — but a re-index is the largest fixed cost a planning session
+   carries, 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:
+   - **Analyzer provenance check — before any refresh.** Compare the resolved
+     runner identity with the index metadata and, in an analyzer-source
+     checkout, with current analyzer source. If identity is stale or unknown,
+     do not build output and do not make that graph load-bearing. Record a
+     **stale analyzer provenance — source-weighted limitation** in
+     `index_refresh`, the plan header, and §12; rely on targeted source reads
+     or hand execution to `gitnexus-work`, which owns the build-current gate.
+   - Stale index → run `analyze --index-only` via the resolved runner
+     (append `--pdg` when the task category will reach Phase 3) and re-read
+     the context resource **only when runner provenance is known-current**.
+     Refresh budget, stated once here: at most one `--index-only` refresh in
+     Phase 1 **plus** at most one later `--pdg` upgrade in Phase 3 (only when
+     Phase 1's refresh lacked `--pdg`) per planning session — a Deepen run is
+     its own session. Record each command, runner identity, 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).
+5. For architecture-scale tasks only, also read
+   `gitnexus://repo/{name}/clusters` and `.../processes`.
+
+## Phase 2 — Graph navigation ladder
+
+Use the narrowest operation that answers the current ledger question, in this
+order. Budgets: at most `max_primary_symbols` (5) primary symbols and
+`max_related_symbols` (20) related symbols active in the ledger.
+
+1. `query {search_query, task_context}` — locate concepts, execution flows,
+   modules, and related tests for the task.
+2. `context {name}` — 360° view of each candidate primary symbol: callers,
+   callees, categorized refs, processes. Promote to primary or discard. An
+   `ambiguous` result (ranked candidates) is answered by one retry narrowed
+   with `kind` / `file_path` / uid — that retry is an allowed repeat.
+3. `impact {target, direction}` — upstream/downstream blast radius for shared
+   or high-connectivity symbols (`maxDepth` = `impact_depth`; `summaryOnly:
+true` first for hub symbols, then drill in — an allowed repeat). Record the
+   d=1 items — the **direct (depth-1) dependents** — the plan must account
+   for every one of them.
+4. `trace {from, to}` — when the task hinges on _how A reaches B_, one call
+   instead of chained context hops.
+5. Statement-level PDG — Phase 3, for the functions the change centers on.
+6. `cypher` — last resort, only for a precise graph question the tools above
+   cannot express. Read `gitnexus://repo/{name}/schema` first; anchor and
+   LIMIT every query.
+7. `detect_changes {scope}` — only when planning against existing uncommitted
+   or branch work.
+
+Do not run every tool by default. A local test fix may finish the ladder at
+step 2.
+
+## Phase 3 — Statement-level PDG slice
+
+For the 1–3 functions most central to the change, build a bounded **PDG
+context slice**. Read `references/pdg-slice.md` and follow it — it owns the
+tool calls, inclusion criteria, depth bounds, slice schema, the security and
+performance modes, and the no-PDG-layer fallback.
+
+## Phase 4 — Targeted source verification
+
+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. 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
+  (package.json scripts / CI workflows), and prefer the script form that
+  carries its prerequisites (pre-hooks) over invoking underlying binaries
+  directly.
+- Check repo conventions that constrain the change (AGENTS.md, GUARDRAILS.md,
+  lint/build config) — only the parts the change touches.
+- Mark each ledger symbol `source_verified: true` as you go. **A symbol that
+  is named in Proposed Changes must be source-verified.**
+- On graph/source disagreement: trust source, record the discrepancy in the
+  ledger and the plan, recommend re-indexing. Never present stale graph data
+  as fact.
+- Immediately before composition, recompute the versioned
+  `evidence_provenance` snapshot by invoking
+  `scripts/evidence-provenance.mjs` exactly as specified in
+  `references/evidence-provenance.md`: the
+  canonical global dirty digest over all dirty paths and the sorted manifest
+  of every cited path, including object kind and
+  HEAD/index/worktree/untracked layer digests. Re-read any citation that
+  changed during planning. Exclude only the generated plan path.
+
+Evidence hierarchy, strongest first: current source and config → current tests
+and executable behavior → compiler/build/lint output → GitNexus graph and PDG
+→ documentation and comments.
+
+## Phase 5 — Compose the plan
+
+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), including mandatory
+   `evidence_provenance` in compact and full forms.
+3. Set `generated_plan_path` to
+   `docs/plans/YYYY-MM-DD-gitnexus-plan-<slug>.md` under the root of the repo
+   being planned (the Phase 1 target repo, not necessarily the cwd); use a
+   3–5-word kebab-case slug and repo-relative paths inside the document.
+   Compose the complete document without creating that destination, then
+   pipe its exact UTF-8 bytes to `scripts/evidence-provenance.mjs write-plan`
+   as specified in `references/evidence-provenance.md`. The helper safely
+   creates missing parent directories. Initial planning must not pass
+   `--replace`. A safe-write failure blocks plan publication: report it and
+   do not write directly, choose an external destination, or weaken the
+   repo-relative provenance contract. The snapshot and writer commands apply
+   the same strict generated-plan filename/date validator; do not substitute a
+   source, `.git`, or arbitrary `docs/plans/` path in either invocation.
+4. Present in chat: objective, proposed-changes summary, implementation
+   sequence, top risks, open questions, and the plan file path. Do not paste
+   the whole document into chat.
+
+## Deepen mode
+
+`/gitnexus-plan deepen <plan-path>` strengthens an existing plan in place
+instead of creating a new one:
+
+1. Resolve the target repository and normalized repo-relative plan candidate,
+   then load it with `scripts/evidence-provenance.mjs read-plan --repo <root>
+--generated-plan <candidate>` exactly as specified in
+   `references/evidence-provenance.md`. Reject a missing, external, escaping,
+   symlinked, or differently scoped path. Decode and parse only the receipt's
+   exact `plan_bytes_base64`; retain its canonical `generated_plan_path` and
+   `plan_digest` unchanged for the entire Deepen session.
+2. Re-run Phase 1 in full — analyzer provenance check and freshness gate (a
+   Deepen run is its own session, with its own refresh budget).
+3. **Re-anchor before re-pinning.** Recompute the plan's global dirty digest
+   and cited-path manifest as well as comparing its old HEAD pin with current
+   HEAD. Changed, renamed, deleted, mixed, or newly absent cited paths get
+   their ranges re-read — or the claim downgraded — _before_ the pin and
+   provenance snapshot move. Moving only the commit pin silently launders
+   dirty or stale claims as verified.
+4. Escalate to `depth: deep` (impact_depth 3, clusters/processes read)
+   unless the invocation overrides knobs explicitly.
+5. Seed the ledger from the plan's §11 pack, then re-verify: every
+   `[graph]`/`[inferred]` claim gets a targeted pass toward `[verified]`;
+   every `[assumed]` claim is resolved or kept with its reason; direct
+   (d=1) dependent accounting is re-checked against the refreshed graph;
+   PDG slices are built or expanded for the central functions when the
+   layer is present.
+6. **Reconcile execution state.** If `gitnexus-work` already landed commits
+   for this plan (a mid-execution route-back), mark the §7 steps present at
+   HEAD as completed and re-sequence the remainder — the rewritten plan must
+   be executable from the top without redoing landed steps.
+7. Strengthen whatever the deeper pass showed thin — test scenarios, risks,
+   Definition of Done — and carry claim-tag upgrades through the prose.
+8. Rewrite the **same canonical file** through
+   `scripts/evidence-provenance.mjs write-plan --replace
+--expected-plan-path <retained-read-plan-path>
+--expected-plan-digest <retained-read-plan-digest>`: same 13 sections,
+   context pack kept in sync, evidence header updated. `--replace` is reserved
+   for Deepen mode, and both expected values must come from the same read-plan
+   receipt; any digest/path mismatch blocks publication. Retain the successful receipt's
+   `prior_plan_backup_git_path`; it names the verified Git-admin backup of the
+   displaced plan. Summarize the delta in chat: claims upgraded, claims that
+   failed re-verification, sections changed, and that backup path.
+
+## Configuration
+
+Baseline defaults — the Phase 0 category posture overrides them, and inline
+`key:value` tokens before the task text override both (the repo has no
+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                                                                                                                                                                                                                                                          |
+| `max_primary_symbols` | 5           | Ledger budget (active symbols; discards don't count)                                                                                                                                                                                                                                              |
+| `max_related_symbols` | 20          | Ledger budget (active symbols; discards don't count)                                                                                                                                                                                                                                              |
+| `max_snippet_lines`   | 30          | Longest source excerpt quoted in the plan                                                                                                                                                                                                                                                         |
+| `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)
+
+1. Say so, first thing, in chat and in the plan.
+2. Use targeted repo exploration (grep/glob/reads) to approximate callers,
+   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 `analyze --index-only` (add `--pdg` for the PDG layers) via
+   the resolved runner — `node .gitnexus/run.cjs`, installed `gitnexus`, or
+   `npx gitnexus` — when it would materially raise confidence.
+
+## Skill feedback
+
+If this run exposed friction in the instructions, include concise feedback in
+the final response. Feedback is chat-only: do not append evaluation learnings,
+edit benchmark data, or modify this skill during a live planning task.

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

@@ -0,0 +1,137 @@
+# Context ledger
+
+The ledger is gitnexus-plan's working memory. It exists to make repeated
+investigation impossible-by-discipline: **before every GitNexus call and
+every repo file read, check it.** Keep it as structured notes in your working
+context (or a scratchpad file _outside the repo_ for very long sessions); it
+is never published verbatim — the plan and context pack are distilled from
+it. This skill's own reference files are exempt from ledger bookkeeping.
+
+## Schema
+
+```yaml
+context_ledger:
+  task:
+    original_request: ''
+    interpreted_goal: ''
+    category: '' # Phase 0 classification
+    acceptance_criteria: []
+
+  verified_at_commit:
+    '' # target repo HEAD, recorded once in Phase 1;
+    # every line citation in the plan pins to it
+
+  evidence_provenance: {} # required immutable working snapshot; populate
+    # exactly from context-pack.md's normative schema
+
+  index_refresh:
+    '' # analyze --index-only runs: command + outcome
+    # (or "skipped: <reason>"). Budget is
+    # owned by SKILL.md Phase 1: one refresh plus
+    # at most one Phase 3 --pdg upgrade per session
+
+  established_facts: [] # each with its evidence source
+
+  symbols: # budgets count active (primary/related) only;
+    # discards are free — but on budget overflow,
+    # discard something before promoting
+    - name: ''
+      kind: ''
+      file: ''
+      relevance: 'primary | related | discarded'
+      source_verified: false # flipped in Phase 4; required before naming in Proposed Changes
+
+  files_read:
+    - file: ''
+      ranges: [] # e.g. ["120-188"]
+      purpose: ''
+
+  gitnexus_queries:
+    - query: '' # tool + args
+      purpose: '' # the planning question it answers
+      conclusion: '' # one line; details stay in working memory
+      key_output: '' # one-line raw quote when the plan leans on this result
+
+  pdg_slices:
+    - symbol: ''
+      purpose: ''
+      conclusion: ''
+
+  unresolved_questions: []
+  assumptions: [] # explicit, carried into plan §12
+  decisions: [] # with rationale, carried into plan §6/§7
+```
+
+## Evidence provenance
+
+`context-pack.md` is the sole normative emitted field schema, and
+`evidence-provenance.md` plus `../scripts/evidence-provenance.mjs` are the
+normative byte contract and implementation. Keep the helper's exact schema-2
+output in the ledger; do not redefine, abbreviate, or independently reproduce
+its canonicalization here.
+
+Build `evidence_provenance` immediately before composing the plan, after all
+source verification, by invoking the helper exactly as described in
+`evidence-provenance.md`. It is a versioned, canonical snapshot of both the
+whole working tree and every path that supports a plan citation:
+
+- `global_dirty_digest` is SHA-256 over the helper's versioned, NUL-framed
+  records for
+  **every dirty repo-relative path**, not only cited paths. Each record includes
+  path, state, object kind, every available layer digest, and both endpoints of
+  a rename. Overlapping porcelain facts for one path are merged; for example,
+  a staged deletion plus a recreated untracked file is `mixed` and retains
+  both its Git-backed and untracked layers. States are `staged`, `unstaged`,
+  `untracked`, `deleted`, `renamed`, or `mixed`. Exclude only this run's
+  normalized repo-relative generated plan path so writing the plan cannot
+  invalidate its own evidence; do not exclude the rest of `docs/plans/`.
+- `cited_path_manifest` is sorted by normalized repo-relative path and
+  includes every path cited by a `[verified]` claim or named as evidence in
+  the context pack. Record clean paths too. A path entry has this shape:
+
+```yaml
+- path: 'src/example.ts'
+  object_kind: # each layer: regular | symlink | gitlink | directory | absent
+    head: 'regular'
+    index: 'regular'
+    worktree: 'regular'
+    untracked: 'absent'
+  state: 'clean | staged | unstaged | untracked | deleted | renamed | mixed | absent'
+  rename_from: null
+  rename_to: null
+  head_digest: 'sha256:<hex> | absent'
+  index_digest: 'sha256:<hex> | absent'
+  worktree_digest: 'sha256:<hex> | absent'
+  untracked_digest: 'sha256:<hex> | absent'
+```
+
+Use Git object contents for HEAD and index digests and filesystem bytes for
+worktree/untracked digests; never confuse an absent layer with an empty file.
+Hash symlink targets as link text and gitlinks as object IDs. If a cited path
+cannot be classified or read, the plan must mark the evidence unavailable
+instead of emitting a digest it did not prove.
+
+## Reread rules
+
+Do **not** repeat a query or reread a source range unless one of:
+
+- the previous result was incomplete for the question at hand;
+- the source is known to have changed (an edit happened);
+- validation exposed a contradiction between graph and source.
+
+**Allowed repeats** (deliberate escalations, not violations):
+
+- `summaryOnly: true` → full drill-down on the same `impact` target;
+- an `ambiguous` result retried once with `kind` / `file_path` / uid narrowing;
+- the same tool re-run with a changed parameter that answers a _new_ planning
+  question (e.g. `pdg_query` `controls` then `flows` on one function).
+
+When a repeat is justified, note in the ledger _why_ the earlier entry was
+insufficient. A ledger full of near-duplicate queries is the failure signal —
+stop and plan with what is established.
+
+## Discarding
+
+Symbols and queries that turned out irrelevant stay in the ledger marked
+`discarded` with a one-line reason. That is what prevents re-walking dead
+ends later in the session.

package/skills/gitnexus-plan/references/context-pack.md

@@ -0,0 +1,126 @@
+# Implementation context pack
+
+Section 11 of the plan. The stable, machine-readable contract a follow-up
+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`,
+`evidence_provenance`, `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; `evidence_provenance` is
+mandatory in both forms. `gitnexus-work` treats absent optional fields as
+empty, not as errors.
+
+## Schema
+
+This is the sole normative emitted `evidence_provenance` field schema. The
+portable byte contract and executable serializer live in
+`evidence-provenance.md` and `../scripts/evidence-provenance.mjs`; sibling
+documents must reference them rather than reimplementing canonical bytes.
+
+```yaml
+implementation_context:
+  task_summary: ''
+  acceptance_criteria: []
+
+  evidence_provenance:
+    schema_version: 2
+    head_commit: '' # full commit SHA that source citations pin to
+    # normalized repo-relative docs/plans/<date>-gitnexus-plan-<3-5-word-slug>.md;
+    # safely written; exact path excluded from global_dirty_digest
+    generated_plan_path: ''
+    global_dirty_digest:
+      algorithm: 'sha256'
+      canonicalization: 'gitnexus-evidence-provenance-v2 NUL-framed UTF-8 records'
+      value: '' # digest only; do not embed the whole dirty-path manifest
+    cited_path_manifest: # sorted by normalized repo-relative path
+      - path: ''
+        object_kind: # per layer: regular | symlink | gitlink | directory | absent
+          head: ''
+          index: ''
+          worktree: ''
+          untracked: ''
+        state: 'clean | staged | unstaged | untracked | deleted | renamed | mixed | absent'
+        rename_from: null
+        rename_to: null
+        head_digest: 'sha256:<hex> | absent'
+        index_digest: 'sha256:<hex> | absent'
+        worktree_digest: 'sha256:<hex> | absent'
+        untracked_digest: 'sha256:<hex> | absent'
+
+  primary_symbols:
+    - symbol: ''
+      file: ''
+      lines: ''
+      role: ''
+
+  related_symbols:
+    - symbol: ''
+      relationship: '' # CALLS / IMPORTS / EXTENDS / test-of / ...
+      relevance: ''
+
+  execution_path: [] # ordered prose steps, from §2/§5
+
+  pdg_constraints: # from the PDG slice; empty + note if no layer
+    - description: ''
+      affected_statements: [] # "<file>:<line>" refs
+      implementation_consequence: ''
+
+  architectural_patterns:
+    - pattern: ''
+      example_location: '' # repo-relative file (+ symbol)
+      usage_guidance: ''
+
+  files_to_modify:
+    - file: ''
+      symbols: []
+      intended_change: ''
+
+  tests:
+    - file: '' # existing file to update, or new path to create
+      scenarios: [] # input → action → expected outcome
+
+  verification_commands: [] # real commands verified to exist AND be runnable —
+    # prefer npm/CI scripts that carry their pre-hooks
+
+  risks: []
+  assumptions: [] # faithful condensation of plan §12 assumptions;
+    # each entry names WHAT to check and HOW —
+    # gitnexus-work re-verifies them before executing
+  open_questions: [] # faithful condensation of plan §12 open questions
+
+  avoid:
+    - 'Do not repeat full repository discovery'
+    - 'Do not replace established patterns without evidence'
+    # + task-specific prohibitions discovered during planning
+```
+
+## Must not contain
+
+- full files;
+- the repository-wide raw dirty-path manifest (store only its canonical
+  `global_dirty_digest`; detailed entries are bounded to cited paths);
+- large raw GitNexus responses;
+- unfiltered PDG dumps;
+- duplicate code excerpts (cite `file:line`, don't re-quote);
+- speculative implementation details presented as facts.
+
+## Stability contract
+
+Field names above are the interface consumed by `gitnexus-work` (fields it
+does not act on directly travel as executor context). Add fields
+freely; do not rename or repurpose existing ones. `assumptions` and `avoid`
+are load-bearing: an executor treats `assumptions` as things to re-verify
+cheaply before relying on them, and `avoid` as hard constraints.
+`evidence_provenance` is also load-bearing: its version, global digest, and
+sorted cited-path manifest let the executor distinguish commit drift from
+staged, unstaged, untracked, deleted, renamed, mixed, or absent working-tree
+evidence. Legacy packs that lack it or use schema 1 require a conservative
+schema-2 re-anchor; they are not interpreted as a clean tree.
+`generated_plan_path` is always normalized, relative to the target repo, and
+scoped to the generated-plan filename shape under `docs/plans/`; schema 2 has
+no external-output representation. An executor must load the plan with the
+helper's descriptor-anchored `read-plan` command and require this field to
+equal the receipt's canonical target-repo-relative path byte-for-byte.