Core adapter refactor: adapter architecture, Claude Code runtime, git-distributed skills#1
Merged
Merged
Conversation
Deletes the Zed verification script, settings merge utilities, and all associated GitNexus skills from the bundle.
Complete the enforcement core/adapter split: grep, read, edit, commit, and shell guards are now thin Cursor-protocol glue over a vendor-neutral classify.mjs (classifyGrep/Read/Edit/Commit/Shell -> Verdict) and a single cursor-emit.mjs adapter that maps Verdict -> Cursor hook JSON (+ guide mode, nudges, scorecard). Decision logic lives in one tested place; a new hook host only needs its own emit adapter. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
prompt-router now validates file tokens against the shared sourceExtRe instead of a third hard-coded extension list. Reconcile the api_impact guidance in gitnexus-first.mdc (was a blanket "NOT api_impact") with gitnexus.mdc: framework router -> api_impact, custom router -> dispatcher context. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The always-on Cursor rule (00-gitnexus-enforcement.mdc) and the Zed AGENTS.md block are now GENERATED from one canonical source (scripts/contract/enforcement-contract.md) via `npm run gen:contract`. A test fails if either drifts from the source, so they can never silently diverge again. Propagated trace/pdg_query/explain (+ impact mode:"pdg") into the contract and the gitnexus.mdc / gitnexus-first.mdc reference tables so the rules match the skills. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude Code is now fully supported, reusing the shared enforcement core: - lib/adapters/claude.mjs: wires .mcp.json (MCP), .claude/settings.json hooks (PreToolUse guards + SessionStart brief), .claude/skills symlinks, and a generated CLAUDE.md always-on contract. - bundle/.cursor/hooks/lib/claude-emit.mjs: maps the neutral classify Verdict to Claude Code's PreToolUse JSON (permissionDecision/reason) — the analog of cursor-emit.mjs. Same classify.mjs policy drives Cursor and Claude identically. - bundle/.claude/hooks/*: thin glue for Grep/Glob, Read, Edit/Write/MultiEdit, Bash (shell + commit gate), mcp__gitnexus__* (usage + stale gate), SessionStart. - Generalized runtime model: cursor|zed|claude|both|all + comma lists (e.g. "cursor,claude"); runtimeIds() drives the copy filter and adapter registry. - classify.mjs: tool-name-agnostic edit-rename detection + Read file_path so Claude's Edit/Read flow through unchanged. - gen-contract.mjs also generates CLAUDE.md from the one canonical contract. Tests: claude install (MCP/hooks/CLAUDE.md/skills) + live hook-protocol deny. 47/47. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The shared enforcement lib, policy config, and per-session state moved out of .cursor/ into a neutral .gnkit/ namespace, so a claude-only (or zed-only) repo no longer gets a stray .cursor/ directory. .gnkit/lib + .gnkit/gitnexus-hooks.json are tracked (like the Cursor hooks); only .gnkit/.gitnexus-* state is gitignored and removed on uninstall. Dropped dead graph-session.mjs. setup.sh + sync-cursor-gitnexus-teaching.sh are now runtime-aware via wants_cursor/ wants_zed/wants_claude (handle claude, all, and comma-lists) instead of binary "!= zed" gates; post-index skill sync links .cursor/.agents/.claude per runtime. installKit passes --runtime to setup explicitly. Verified: 47/47 tests; cursor + claude installs both wire correctly, hooks resolve from .gnkit/lib, grep hook denies symbols end-to-end, claude-only has no .cursor dir. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Old installs kept the shared hook lib, policy config, and session state under .cursor/; the relocation moved them to .gnkit/. migrateLegacyInstall now removes the obsolete .cursor/hooks/lib, .cursor/gitnexus-hooks.json, .cursor/gitnexus-api-profile.json, and .cursor/.gitnexus-* state so upgrades don't leave orphans. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The dead graph-session.mjs was still listed in the sync verify + pack manifests, so the kit health check reported 'Missing hook lib: .gnkit/lib/graph-session.mjs'. Removed it and added the new classify.mjs / cursor-emit.mjs / claude-emit.mjs so they are verified and packaged. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
(1) Pre-commit hook now runs gitnexus:full-pdg (force rebuild + PDG) instead of the incremental gitnexus:pdg, keeping control/data-dependence + taint accurate at commit boundaries. Aligned the docs/skills wording. (2) The always-on contract now names EVERY single-repo tool with when-to-use (added api_impact/route_map/shape_check/tool_map/check/list_repos alongside the core + PDG set); regenerated 00-enforcement.mdc + AGENTS.md + CLAUDE.md. Completed the gitnexus-guide skill tool table (was missing 5 tools), fixed its stale refresh command + graph schema, added check to gitnexus.mdc, marked cross-repo group_* out of scope per request. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…red-systems) Broadens scenario coverage beyond debugging/refactoring/impact/pr/security with five distinct multi-tool playbooks: - gitnexus-performance: structural cost (depth/fan-in/repeated work) → profiler - gitnexus-feature-dev: reuse existing patterns + wire into the right place - gitnexus-testing: blast radius → test target list + coverage gaps - gitnexus-architecture-review: judge coupling/cohesion/cycles/god objects (uses check + clusters) - gitnexus-layered-systems: trace/change across controller→service→repo→model layers safely Wired into every router (workspace, guide, gitnexus.mdc, agent-brief, docs/SKILLS, ZED count 14→19). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Mid-session agent-refresh ran analyze --embeddings --skills with no PDG, so the pdg_query/explain/impact(mode:pdg) tools we teach returned 'no PDG layer' until a commit. Switch it to gitnexus:pdg (incremental + embeddings + skills + PDG) — builds the layer without the --force full-rebuild stall on every staleness. Pre-commit hook keeps full-pdg. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…DG layer) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
query is hybrid BM25 + vectors; agents were phrasing search_query like grep keywords, underusing the embedding half. Sharpened the query teaching (contract + workspace 'Smart query habits') to phrase search_query as a natural-language concept, always pass task_context/goal, and use context for known symbols. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Each session's enforcement scorecard is archived to an append-only .gnkit/.gitnexus-telemetry.jsonl on session start (before the per-session scorecard is cleared), so aggregate trends survive across sessions. New gitnexus:stats command reports totals, per-session averages, session count/date-range, and a value summary. session-primer gains flushScorecardToTelemetry/readTelemetry/summarizeTelemetry. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
First cognitive routine of the intel-enhancement layer. Deep, opinionated, adversarially-verified multi-lens audit for milestone moments (feature done / big-task checkpoint / shared-code refactor / pre-ship). Distinct from cascade code-review: two KINDS of lenses — (A) correctness and (B) judgment/opinion (necessity, soundness, proportionality, conceptual integrity). Concrete lenses are spawned dynamically from the GitNexus map (clusters=layers, processes=flows) — one per slice/seam, not a fixed menu. Domain-expert persona is generalized/auto-inferred (optional .gnkit/domain.json pin). Fan out multi-agent when the runtime supports it, else sequential; adversarial verify → synthesize deduped/severity/file:line opinions+defects → iterate in waves. Scope-gated (impact blast-radius) so small tasks stay cheap — capability, not a gate. One-line always-on trigger in the contract; wired into all routers. Skills 19→20. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Fix a latent amnesia bug + add durable memory that survives context compaction: - Claude SessionStart is now source-aware: on compact/resume it PRESERVES the per-session gate flags (impact/detect) instead of clearing them — previously an auto-compaction mid-task silently re-armed the gates and re-blocked the agent — and injects a recovery brief (preserved gates + staleness + read/reconcile MEMORY.md). - New PreCompact hook: logs the compaction (gitnexus:stats 'compactions') + checkpoints state to .gnkit/MEMORY.md + steers 'preserve everything important'. - Always-on contract 'Durable memory' directive: maintain .gnkit/MEMORY.md running journal (works for every agent, not just Claude's weak native memory); nothing important may be lost across compaction. - session-primer: memoryPath/appendMemoryCheckpoint/shouldClearOnSource. MEMORY.md gitignored. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…ot gitignored) Point the durable memory at Claude Code's own per-project memory — ~/.claude/projects/<slug>/memory/MEMORY.md (slug = abs project path, / -> -) — so Claude refers to its own memory and other agents mirror the same file. It lives outside the repo, so nothing is gitignored (dropped the .gnkit/MEMORY.md ignore). Session/precompact hooks + contract now reference the resolved native path. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The Zed adapter resolved gitnexus to an absolute local binary path and baked it into the COMMITTED .zed/settings.json. Zed project settings win over user settings, so a teammate whose node/gitnexus lived elsewhere got a nonexistent binary → broken pipe → 'Context server request timeout' (MCP never started). Now writes 'npx -y gitnexus@latest mcp' like the Cursor + Claude adapters. Test asserts no absolute path leaks into context_servers. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Switching a repo away from the zed runtime (or an old zed install left behind) kept a committed .zed/settings.json pointing at a stale/absolute gitnexus binary, breaking Zed for teammates. migrateLegacyInstall now strips the orphaned gitnexus context_server + profile when Zed isn't active. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…evise gitignore
Teammates who cloned got 'Missing .gitnexus/agent-kit/skills' because the canonical
skill store lived under the gitignored .gitnexus/, so it wasn't distributed — the
committed .claude/skills symlinks dangled. Fix + unify the source of truth:
- Relocate the store .gitnexus/agent-kit/skills -> .gnkit/skills (tracked, like the
hook lib) so it ships via git. Symlink dirs (.cursor/.claude/.agents/skills) stay
ignored and are regenerated from the store by the sync script on setup/agent-refresh
(cross-platform; no committed symlinks).
- Revise the gitignore policy: POPULATE .gnkit/{lib,skills,gitnexus-hooks.json} +
all IDE configs/hooks/rules + AGENTS/CLAUDE + kit scripts/docs; IGNORE the
machine-specific index (.gitnexus/, regenerable), session state (.gnkit/.gitnexus-*),
derived api-profile, and the regenerable symlink dirs.
- migrate removes the legacy .gitnexus/agent-kit store on update.
Verified: store materializes as tracked real files (20), symlinks ignored+resolving,
.gitnexus/ + symlink dirs never staged. 50/50 tests.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…xt there) Claude Code allows hookSpecificOutput.additionalContext only on UserPromptSubmit/ PostToolUse/Stop/SubagentStop — NOT PreCompact — so the hook's emitContext output was invalid and errored every compaction. PreCompact now writes no stdout; it only checkpoints state to memory + logs the compaction. The 'preserve everything / lose nothing' steering already lands via the always-on contract + the SessionStart(compact) recovery brief (which validly supports additionalContext). Test asserts empty stdout. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…scipline
The compaction-aware SessionStart brief (Claude) replaced the graph-first tool
playbook with memory-recovery + "do NOT re-run the ✓ ones". Since gitnexus-session.mjs
is the ONLY re-priming channel on the Claude path (firstToolNudge is Cursor-only),
after the first compaction of a long session the agent lost its graph-first
reinforcement and was told to skip satisfied gates — so it drifted back to grep and
stopped self-refreshing ("respects GN less mid-session"). Hard gates (grep redirect,
shell-staleness, impact/detect) were never affected — this was soft reinforcement only.
Recovery brief now RE-STATES the graph-first playbook and keeps forward discipline
(run impact before NEW edits, detect_changes before commit) while still preserving
already-satisfied gates for work already analyzed. Test asserts the playbook is present
and the discouraging wording is gone.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The agent was doing symbol exploration via bash `grep`/`rg` and `a\|b` alternations — both sailed past graph-first enforcement (the "greps instead of using the graph" the user kept seeing): 1. classifyShell allowed ALL non-git/non-stale shell commands when fresh, so `grep signedRequest file.js` / `rg computeDryRunPnl src/` bypassed the Grep-tool gate entirely — the terminal was a wide-open escape hatch. Now a quote/escape-aware parser pulls (pattern, path) out of grep/egrep/rg/ag/ack/git-grep invocations and applies the SAME classifyGrep policy. Piped filters (`ps aux | grep`), non-source paths, and literal searches still pass; source symbol searches redirect to the graph. 2. classifyGrep treated `a\|b\|c` alternations as neither symbol nor literal → default ALLOW. Now any branch that names a symbol (bare/dotted id, or a decl/assignment like `const foo`, `foo =`, `function foo`) routes the whole grep to the graph. Also recognize `.log` files + `logs/` dirs as non-source (agents grep logs legitimately). Tests: 52/52. New test covers the screenshot's exact patterns + the legit-shell allowlist. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Graph-first enforcement had no sanctioned escape when the index is FRESH but GN returns wrong/suspicious/incomplete info — the agent was trapped (and the shell-grep fix just closed the informal valve). The contract even promised "GN wrong → classical OK", but evaluateStalePolicy returned `fresh` (enforcement on) before any fallback could apply. New: `npm run gitnexus:fallback -- "<why>"` (or `node scripts/gitnexus-agent.mjs fallback`) grants classical Grep/Read/shell for ~15 min EVEN ON A FRESH INDEX, via a new fallbackGrant flag honoured FIRST in evaluateStalePolicy → classical_fallback. Guard rails so it can't be a silent lazy bypass: - bounded: auto-expires after the TTL (self-cleaning); also clears on refresh / new session - reasoned: requires a one-line why - logged: bumps `classicalFallbackGranted` telemetry (repeated grants = a real GN problem) - surfaced: shown in `gitnexus:status` + the SessionStart brief (also fixes the staleLine that would otherwise mislabel an active fallback as "STALE — refresh") - reversible: `npm run gitnexus:fallback:off` Shared policy layer → works for Cursor, Zed, and Claude at once. Contract updated (single source + 3 generated files). Tests: 53/53. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Brings the kit's latest architecture from
core-adapter-refactorontomain(this was developed on the branch and never merged).mainis a strict ancestor, so this is a clean fast-forward — 25 commits ahead, 0 behind.Highlights
lib/adapters/{cursor,zed,claude}.mjsvia a shared contract +classifycore. Adding an IDE = one module + one registry line..mcp.json+ skills + native project memory path)..gnkit/skills; gitignore revised so teammates get skills ongit pullwith no re-install (only the derived graph index stays local).cursor | zed | claude | both | all, plus comma-lists (e.g.cursor,claude)..gnkit/layout for shared hook lib + state; runtime-aware setup; legacy.cursorstate cleaned on upgrade.gitnexus:stats,--json).gitnexus-microscopedeep-audit.agent-refreshnow builds full PDG (matches pre-commit).Merge notes
.agent-kit/skills; this uses the intended.gnkit/skills). That patch was discarded.mainshould be re-installed/updated from this to adopt the.gnkit/layout.🤖 Generated with Claude Code