gitnexus 1.6.9 → 1.6.10-aptos.0

package/scripts/sync-plugin-manifests.mjs

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+/**
+ * Fail-closed version sync for the plugin manifest surfaces (#2445).
+ *
+ * `publish.yml` bumps only `gitnexus/package.json` when it cuts an RC, so
+ * every RC tag through v1.6.10-rc.28 shipped manifests frozen at the last
+ * stable version and failed its own unit suite (the cli-commands version
+ * contract). This script pins every version-bearing plugin surface to the
+ * package version:
+ *
+ *   - gitnexus-claude-plugin/.claude-plugin/plugin.json   (top-level version)
+ *   - .claude-plugin/marketplace.json                     (plugins[gitnexus])
+ *   - gitnexus-claude-plugin/.codex-plugin/plugin.json    (top-level version)
+ *   - .agents/plugins/marketplace.json                    (plugins[gitnexus])
+ *   - gitnexus-claude-plugin/skills/<skill>/mcp.json      (gitnexus@<version> launch arg, x10)
+ *
+ * Modes:
+ *   node scripts/sync-plugin-manifests.mjs           rewrite stale surfaces
+ *   node scripts/sync-plugin-manifests.mjs --check   verify only, exit 1 on drift
+ *
+ * Fail-closed: a missing file, unparseable JSON, an absent version field, or
+ * anything other than exactly one `gitnexus` marketplace entry aborts with a
+ * non-zero exit rather than letting a release ship a partial sync.
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Plugin skill mcp.json are executable MCP definitions (they launch
+// `npx -y gitnexus@<version> mcp` when a skill starts), not quickstart docs, so
+// they must ship pinned to the released version and be auto-stamped here like
+// the other surfaces — otherwise every skill invocation pulls whatever owns
+// `gitnexus@latest`, independent of the reviewed plugin version. All ten are
+// kept byte-identical (the shipped-skills-sync drift guard enforces it).
+const PLUGIN_SKILL_MCP_DIRS = [
+  'gitnexus-plan',
+  'gitnexus-work',
+  'gitnexus-review',
+  'gitnexus-lfg',
+  'gitnexus-guide',
+  'gitnexus-cli',
+  'gitnexus-debugging',
+  'gitnexus-exploring',
+  'gitnexus-impact-analysis',
+  'gitnexus-refactoring',
+];
+
+const MANIFEST_SURFACES = [
+  { file: 'gitnexus-claude-plugin/.claude-plugin/plugin.json', kind: 'plugin' },
+  { file: '.claude-plugin/marketplace.json', kind: 'marketplace' },
+  { file: 'gitnexus-claude-plugin/.codex-plugin/plugin.json', kind: 'plugin' },
+  { file: '.agents/plugins/marketplace.json', kind: 'marketplace' },
+  ...PLUGIN_SKILL_MCP_DIRS.map((name) => ({
+    file: `gitnexus-claude-plugin/skills/${name}/mcp.json`,
+    kind: 'mcp',
+  })),
+];
+
+const PLUGIN_NAME = 'gitnexus';
+
+function readJson(filePath) {
+  let raw;
+  try {
+    raw = readFileSync(filePath, 'utf8');
+  } catch (err) {
+    throw new Error(`Cannot read manifest surface ${filePath}: ${err.message}`);
+  }
+  try {
+    return { raw, parsed: JSON.parse(raw) };
+  } catch (err) {
+    throw new Error(`Manifest surface ${filePath} is not valid JSON: ${err.message}`);
+  }
+}
+
+function versionTarget(manifest, kind, filePath) {
+  if (kind === 'plugin') {
+    if (typeof manifest.version !== 'string' || manifest.version.length === 0) {
+      throw new Error(`Manifest surface ${filePath} has no version field to sync`);
+    }
+    return manifest;
+  }
+  const entries = (Array.isArray(manifest.plugins) ? manifest.plugins : []).filter(
+    (plugin) => plugin?.name === PLUGIN_NAME,
+  );
+  if (entries.length !== 1) {
+    throw new Error(
+      `Manifest surface ${filePath} must contain exactly one "${PLUGIN_NAME}" plugin entry, found ${entries.length}`,
+    );
+  }
+  if (typeof entries[0].version !== 'string' || entries[0].version.length === 0) {
+    throw new Error(`Manifest surface ${filePath} has no version field to sync`);
+  }
+  return entries[0];
+}
+
+/**
+ * Resolve the current pinned version and the textual needle for one surface.
+ * `plugin`/`marketplace` pin a JSON `"version"` field; `mcp` pins the version
+ * inside the `gitnexus@<version>` launch arg. Returns `{ from, needle }` where
+ * `needle(v)` renders the exact substring to match/replace for version `v`.
+ * Fail-closed on a missing/ambiguous target.
+ */
+function versionInfo(manifest, kind, filePath) {
+  if (kind === 'mcp') {
+    const server = manifest?.mcpServers?.[PLUGIN_NAME];
+    const args = Array.isArray(server?.args) ? server.args : [];
+    const pins = args.filter((arg) => typeof arg === 'string' && arg.startsWith(`${PLUGIN_NAME}@`));
+    if (pins.length !== 1) {
+      throw new Error(
+        `Manifest surface ${filePath} must contain exactly one "${PLUGIN_NAME}@<version>" launch arg, found ${pins.length}`,
+      );
+    }
+    const from = pins[0].slice(`${PLUGIN_NAME}@`.length);
+    if (from.length === 0) {
+      throw new Error(`Manifest surface ${filePath} has an empty ${PLUGIN_NAME}@ version`);
+    }
+    return { from, needle: (value) => `${PLUGIN_NAME}@${value}` };
+  }
+  const target = versionTarget(manifest, kind, filePath);
+  return { from: target.version, needle: (value) => `"version": "${value}"` };
+}
+
+/**
+ * Sync (or with `check: true`, only inspect) every manifest surface under
+ * `rootDir`. Returns `{ version, synced, stale }` where `stale` lists the
+ * surfaces that did not match the package version when the run started.
+ */
+export function syncPluginManifests(rootDir, { check = false } = {}) {
+  const pkgPath = path.join(rootDir, 'gitnexus', 'package.json');
+  const version = readJson(pkgPath).parsed.version;
+  if (typeof version !== 'string' || version.length === 0) {
+    throw new Error(`No version found in ${pkgPath}`);
+  }
+
+  const synced = [];
+  const stale = [];
+  for (const { file, kind } of MANIFEST_SURFACES) {
+    const manifestPath = path.join(rootDir, file);
+    const { raw, parsed } = readJson(manifestPath);
+    const { from, needle } = versionInfo(parsed, kind, manifestPath);
+    if (from === version) continue;
+
+    stale.push({ file, from });
+    if (check) continue;
+
+    // Textual surgery instead of re-serializing: JSON.stringify would refold
+    // arrays and fight prettier, turning a one-line version bump into
+    // formatting churn inside the release commit. The needle is built from
+    // the current pinned value, and anything other than exactly one
+    // occurrence aborts rather than guessing.
+    const currentNeedle = needle(from);
+    const occurrences = raw.split(currentNeedle).length - 1;
+    if (occurrences !== 1) {
+      throw new Error(
+        `Manifest surface ${manifestPath} has ${occurrences} occurrences of ${currentNeedle}; ` +
+          'expected exactly one, refusing to sync',
+      );
+    }
+    writeFileSync(manifestPath, raw.replace(currentNeedle, needle(version)));
+    synced.push(file);
+  }
+
+  return { version, synced, stale };
+}
+
+const invokedDirectly =
+  process.argv[1] !== undefined && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (invokedDirectly) {
+  const check = process.argv.includes('--check');
+  const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+  const result = syncPluginManifests(rootDir, { check });
+
+  if (check && result.stale.length > 0) {
+    for (const { file, from } of result.stale) {
+      console.error(
+        `::error::${file} is at ${from} but gitnexus/package.json is at ${result.version}. ` +
+          'Run `node gitnexus/scripts/sync-plugin-manifests.mjs` and commit the result.',
+      );
+    }
+    process.exit(1);
+  }
+
+  for (const file of result.synced) {
+    console.log(`synced ${file} -> ${result.version}`);
+  }
+  console.log(
+    result.stale.length === 0 && result.synced.length === 0
+      ? `all plugin manifests already at ${result.version}`
+      : `plugin manifests now at ${result.version}`,
+  );
+}

package/skills/gitnexus-lfg/README.md

@@ -0,0 +1,55 @@
+# gitnexus-lfg — plan → gate → work → review
+
+Thin pipeline orchestrator over three existing skills: `gitnexus-plan`
+produces the plan (asking up front how deep to go), the user chooses at a
+blocking gate to proceed or stop (an explicit deepen request is still
+honored), `gitnexus-work` executes it as verified atomic commits, and
+`gitnexus-review` reviews the result (the open PR if one exists, else the
+branch diff against the default branch). One bounded fix cycle for review
+findings, then a final report. It never pushes or opens a PR on its own.
+
+## Invocation
+
+| CLI | How to invoke |
+|-----|---------------|
+| **Claude Code** | `/gitnexus-lfg <task description>` or `/gitnexus-lfg docs/plans/<plan>.md` |
+| **Codex CLI** | Ask: "run the gitnexus pipeline on <task>" (Codex reads `AGENTS.md`), or install the skill user-level (below) |
+
+### Codex (user-level install)
+
+```
+cp -r .claude/skills/gitnexus-lfg ~/.agents/skills/gitnexus-lfg
+```
+
+Optionally, for an explicit slash command, create
+`~/.codex/prompts/gitnexus-lfg.md`:
+
+```markdown
+---
+description: GitNexus pipeline — plan (depth asked up front), user gate, work, PR review
+argument-hint: <task description or plan path>
+---
+Use the gitnexus-lfg skill for: $ARGUMENTS
+
+Read `~/.agents/skills/gitnexus-lfg/SKILL.md` (prefer the repo copy at
+`.claude/skills/gitnexus-lfg/SKILL.md` when present) and follow its lanes in
+order, invoking the real gitnexus-plan / gitnexus-work / gitnexus-review
+skills for each lane. Stop at the plan gate for the user's choice.
+```
+
+## The three lanes
+
+| Lane | Skill | Gate |
+|------|-------|------|
+| Plan | `gitnexus-plan` (`.claude/skills/gitnexus-plan/`) | Depth asked up front; blocking gate: proceed / stop |
+| Work | `gitnexus-work` (`.claude/skills/gitnexus-work/`) | Structural drift routes back to the plan gate |
+| Review | `gitnexus-review` (`.claude/skills/gitnexus-review/`) | One fix cycle max, then report |
+
+## Threshold governance (maintainers)
+
+The Lane 1 planning boundary (~35 turns) is a promoted benchmark policy from
+the GitNexus repository's `eval/workflow_bench/` paired candidate loop.
+Re-evaluate it offline whenever the named model or tool harness changes, and
+at least every 90 days; update the SKILL.md threshold only after the
+deterministic promotion gate shows no quality regression. Reading agents
+never self-edit it from a live task.

package/skills/gitnexus-lfg/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: gitnexus-lfg
+description: "Use when the user wants the GitNexus engineering pipeline run end-to-end on a task: gitnexus-plan (plan depth chosen up front), a blocking gate to execute with gitnexus-work or stop, finishing with a gitnexus-review of the result. Examples: \"/gitnexus-lfg Add retry support to the ingestion pipeline\", \"run the gitnexus pipeline on this\", \"plan, build and review this feature\"."
+---
+
+# gitnexus-lfg — plan → gate → work → review
+
+Thin orchestrator over three existing skills. It adds no engineering logic of
+its own — it sequences `gitnexus-plan`, `gitnexus-work`, and
+`gitnexus-review`, with the user deciding at the plan gate. Run every lane
+by actually invoking the named skill (read its SKILL.md and follow it);
+never inline a summary of what the skill would have done.
+
+```
+/gitnexus-lfg <task description>
+/gitnexus-lfg docs/plans/<existing-plan>.md    # skip lane 1, start at the gate
+```
+
+## Lane 1 — Plan
+
+**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;
+measured in the GitNexus repository's `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.
+
+The threshold is a promoted benchmark policy measured offline, not a
+timeless heuristic — never self-edit it from a live task. Its re-evaluation
+governance lives in this skill's README.
+
+Otherwise invoke `gitnexus-plan` with the task (knob overrides pass through
+verbatim; `gitnexus-plan` owns the up-front depth question — never ask it
+again here). 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)
+
+Present the plan's chat summary (objective, proposed changes, sequence, top
+risks, open questions, plan path), then ask the user — as a blocking
+question (`AskUserQuestion` in Claude Code; a numbered list in chat on CLIs
+without a blocking tool):
+
+1. **Proceed to work** — continue to Lane 3.
+2. **Stop here** — the plan file is the deliverable; end the pipeline.
+
+Depth was the user's up-front choice in Lane 1, so deepening is not offered
+by default — but honor an explicit request for it at the gate: run
+`gitnexus-plan` Deepen mode on the plan file and return here with the
+strengthened plan, as many times as the user asks. Do not proceed past the
+gate without an explicit choice — the gate is the pipeline's only checkpoint
+and exists precisely because execution is expensive to unwind.
+
+**Headless / non-interactive runs:** no one can answer the gate, so end the
+pipeline after Lane 1 — the plan file is the deliverable (gate option 2) —
+and say so in the final report. Never auto-proceed to execution.
+
+## Lane 3 — Work
+
+Invoke `gitnexus-work` with the plan path. It re-anchors the plan at HEAD,
+executes the Implementation Sequence as verified atomic commits, refreshes
+the knowledge graph when done (its Phase 4), and reports deviations. If it routes back for re-planning (structural drift), run the
+Deepen pass and return to the Lane 2 gate rather than pushing through.
+
+## Lane 4 — Review
+
+Invoke `gitnexus-review` on the completed work. Pass an open PR URL/number
+when one exists; otherwise pass the current branch. The review skill owns
+target resolution, exact-SHA checkout/index alignment, and merge-base
+selection. Do not duplicate that logic here. If work left local changes,
+pass `local` as a second, separately labeled review surface.
+
+Surface the review verdict and findings to the user. Findings the user
+wants fixed: those within `gitnexus-work`'s direct-mode bounds (1–2 files,
+no architectural decisions) → hand to `gitnexus-work` direct mode; anything
+larger → offer the plan gate instead (Deepen the plan with the findings, or
+stop). Then re-run this lane's review once. On that re-run, do not start
+another fix cycle even if findings remain — report them and point the user
+at `/gitnexus-work` (or the plan gate) to continue deliberately.
+
+## Final report
+
+One message: plan path, deepen cycles run, commits produced, verification
+status, review verdict with unresolved findings, and what (if anything) was
+explicitly left undone. The pipeline does not push or open a PR on its own —
+offer both as next steps.

package/skills/gitnexus-plan/README.md

@@ -0,0 +1,142 @@
+# gitnexus-plan — implementation-ready engineering plans
+
+Generates deep, implementation-ready engineering plans by combining GitNexus
+repository intelligence, statement-level Program Dependence Graph analysis,
+and the agent's native targeted source verification.
+
+## Invocation
+
+| CLI                           | How to invoke                                                                                          | Adapter file                                   |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------- |
+| **Claude Code**               | `/gitnexus-plan <task>`                                                                                | `.claude/skills/gitnexus-plan/SKILL.md`        |
+| **Codex CLI**                 | Ask: "run gitnexus-plan for <task>" (Codex reads `AGENTS.md`) — or install the user-level prompt below | `AGENTS.md` § Engineering planning & execution |
+| **Any AGENTS.md-aware agent** | Ask it to "read `.claude/skills/gitnexus-plan/SKILL.md` and follow it for <task>"                      | `AGENTS.md` § Engineering planning & execution |
+
+```
+/gitnexus-plan Add retry support to the ingestion pipeline
+/gitnexus-plan Fix the stale warm-cache invalidation bug in exportedTypeMap
+/gitnexus-plan depth:deep impact_depth:3 Migrate the emit phase to streaming COPY
+```
+
+Output: `docs/plans/YYYY-MM-DD-gitnexus-plan-<slug>.md` — a 13-section plan whose
+section 11 is a machine-readable **implementation context pack** that a
+follow-up agent can consume without re-investigating the repository. Compact
+and full packs both include versioned evidence provenance: a canonical global
+dirty digest and a sorted, per-layer cited-path manifest. An npm-dependency-free,
+versioned Node helper shared byte-for-byte with `gitnexus-work` is the only
+supported serializer, so planner and executor hash identical bytes. The same
+helper is the only supported existing-plan reader and plan writer. Its
+descriptor-anchored `read-plan` receipt binds the canonical path, exact base64
+bytes, and SHA-256 digest before Deepen or execution. The writer accepts a repo-relative
+`docs/plans/<date>-gitnexus-plan-<slug>.md` destination, rejects symlink
+traversal and accidental replacement, and publishes the verified UTF-8
+document through a descriptor-anchored atomic no-replace move. Deepen first
+requires the exact canonical path and digest from one read receipt, preserves
+the prior plan in a verified Git-admin backup, and also publishes without replacement. A safe read/write
+failure blocks the operation; there is no
+external-output or read-only-checkout fallback.
+
+### Codex (user-level install)
+
+Codex discovers SKILL.md skills from `~/.agents/skills/` (the same path the
+other `gitnexus-*` skills install to). To make this skill auto-discoverable in
+every Codex session:
+
+```
+cp -r .claude/skills/gitnexus-plan ~/.agents/skills/gitnexus-plan
+```
+
+Codex prompts are user-level only (not repo-shareable). Optionally, for an
+explicit `/gitnexus-plan` slash command, also create
+`~/.codex/prompts/gitnexus-plan.md`:
+
+```markdown
+---
+description: Implementation-ready engineering plan via GitNexus + PDG + source verification
+argument-hint: <task description>
+---
+
+Use the gitnexus-plan skill for: $ARGUMENTS
+
+Read `~/.agents/skills/gitnexus-plan/SKILL.md` (if this repo has its own copy at
+`.claude/skills/gitnexus-plan/SKILL.md`, prefer that one) and follow its phases in
+order, loading its `references/` files at the phases that call for them. Planning
+only — never edit code; the only repo file you write is the plan document.
+```
+
+## Architecture note: how GitNexus and the agent interact
+
+Three layers, strictly ordered:
+
+1. **GitNexus navigates** (`query` → `context` → `impact`/`trace` →
+   `cypher` last-resort). The graph answers _where to look_ and _what is
+   connected_: execution flows, callers/callees, blast radius, related tests.
+   Every call must answer a named planning question.
+2. **PDG constrains** (`pdg_query` controls/flows, `impact {mode:"pdg",
+direction, line}` statement slices, `explain` for taint). The
+   statement-level layers
+   answer _what gates and feeds the behavior_ inside the few functions the
+   change centers on. Results are filtered into a bounded slice
+   (`references/pdg-slice.md`), never dumped.
+3. **The agent verifies** (targeted line-range reads). Current source is
+   authoritative; graph results are navigation hints until verified. On
+   disagreement: trust source, record the discrepancy, recommend re-indexing.
+
+Token efficiency comes from the **context ledger**
+(`references/context-ledger.md`): every query and read is recorded with the
+question it answered, and nothing is re-fetched unless the source changed, a
+contradiction surfaced, or one of the ledger's defined escalations applies
+(summary→detail drill-down, ambiguity narrowing, a changed parameter answering
+a new question). The ledger also enforces symbol budgets (5 primary /
+20 related by default), pins dirty working-tree evidence as well as HEAD, and
+uses progressive disclosure to keep the big schemas out of context until the
+phase that needs them.
+
+## Files
+
+| File                                | Purpose                                                                               |
+| ----------------------------------- | ------------------------------------------------------------------------------------- |
+| `SKILL.md`                          | The skill: phases 0–5, hard rules, config, fallback                                   |
+| `references/pdg-slice.md`           | PDG slice construction: tools, inclusion criteria, schema, security/performance modes |
+| `references/context-ledger.md`      | Ledger schema + anti-reread rules                                                     |
+| `references/plan-template.md`       | The 13-section plan document template                                                 |
+| `references/context-pack.md`        | Implementation context pack schema + stability contract                               |
+| `references/evidence-provenance.md` | Versioned byte contract for dirty-tree evidence                                       |
+| `scripts/evidence-provenance.mjs`   | Snapshot serializer plus descriptor-anchored plan reader/writer                       |
+
+## Requirements and graceful degradation
+
+- Requires a GitNexus index; statement-level sections additionally require the
+  `--pdg` layers.
+- 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, but only when that runner's provenance is known-current.
+  Compact-plan categories default to `accept` (source-weighted, refresh only
+  if a graph claim becomes load-bearing). `--index-only` touches only the
+  `.gitnexus` store, never repo files. Stale analyzer provenance is a
+  disclosed **source-weighted limitation**: planning does not rebuild analyzer
+  output, and it does not use that graph for load-bearing claims.
+- PDG layer still unavailable after that → the plan says so and skips
+  statement-level claims (never reconstructs fake edges).
+- No GitNexus at all → fallback mode: targeted grep/read exploration, findings
+  labelled **source-derived**, with a recommendation to index.
+- Reading or publishing a plan requires Linux `/proc/self/fd`, `O_DIRECTORY`,
+  and `O_NOFOLLOW`; publication also requires a validated absolute Python 3
+  PATH candidate with libc `renameat2(RENAME_NOREPLACE)` support, a
+  writable target repository, and a shared filesystem for the plan and
+  Git-admin vault. The writer fails closed when those guarantees are
+  unavailable; it never redirects the plan elsewhere.
+
+## Limitations
+
+- `pdg_query` is intra-procedural; cross-function flow comes from `explain`
+  (taint) or `impact {mode:"pdg"}` inter-procedural reach.
+- The skill is planning-only by contract: the only repository file it writes
+  is the plan document, and the only other state it may touch is the
+  `.gitnexus` index store for a freshness refresh. It must not build
+  analyzer `dist/` output or mutate source, tests, configuration, benchmark,
+  or evaluation files. Instruction feedback is chat-only.