mirror of https://github.com/abhigyanpatwari/GitNexus.git synced 2026-09-26 01:11:16 +00:00

abhigyanpatwari dbad60c6b7 docs(incremental): update spec + AGENTS.md + GUARDRAILS.md for shipped design

- Rewrite docs/superpowers/specs/2026-05-10-incremental-indexing-design.md
  to describe the architecture that actually shipped (parse cache +
  incremental DB writeback + scope-resolution short-circuit), with the
  v1 hydrate-phase post-mortem preserved as historical context.
- AGENTS.md "Keeping the Index Fresh" section: note that incremental
  is the new default and --force is the explicit opt-out; mention
  the parse-cache file location and that it's safe to delete.
- GUARDRAILS.md Signs: add an "Index seems corrupt or incremental is
  misbehaving" entry pointing users to --force as the manual escape
  hatch (the dirty flag handles automatic recovery).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-10 17:16:14 +05:30

5.1 KiB

Raw Blame History

Guardrails — GitNexus

Rules for human contributors and AI agents. Complements AGENTS.md (workflows) and CONTRIBUTING.md (PR process).

Scope (least privilege)

Read: Source, tests, docs, public config as needed.
Write: Only files required for the fix or feature; no unrelated formatting or refactors.
Execute: Tests, typecheck, documented CLI commands. No destructive commands on user data without approval.
Off-limits: Other people's machines, production deployments you don't own, credentials you lack permission to use.

Maintainer may widen scope per task.

Non-negotiables

Never commit secrets — API keys, tokens, real .env values, private URLs, session cookies. Use .env.example with placeholders.
Never rename with find-and-replace in GitNexus-indexed projects — use rename MCP tool with dry_run: true first, review graph vs text_search edits. No separate gitnexus rename CLI exists.
Run impact analysis before editing shared symbols — impact (upstream) for functions/classes/methods others call. Do not ignore HIGH/CRITICAL without maintainer sign-off.
Run detect_changes before commit — confirm diffs map to expected symbols/processes when the graph is available.
Preserve embeddings — plain npx gitnexus analyze now preserves any embeddings recorded in .gitnexus/meta.json (the previous behavior wiped them). Use --embeddings to also generate vectors for new/changed nodes; use --drop-embeddings only when an explicit wipe is intended (e.g., model swap).

Signs (recurring failure patterns)

Format: Trigger → Instruction → Reason. Append new Signs when the same mistake repeats.

Stale graph after edits

Trigger: MCP warns index is behind HEAD, or search doesn't match latest commit.
Do: npx gitnexus analyze (plus --embeddings if used). Runs incrementally by default — only changed files are re-parsed and their LadybugDB rows rewritten.
Why: Tools query LadybugDB from last analyze; git changes are invisible until re-indexed.

Index seems corrupt or "incremental" is misbehaving

Trigger: analyze produces unexpected results, or meta.json.incrementalInProgress is set, or the index is in a half-state after a crash.
Do: npx gitnexus analyze --force to rebuild from scratch. The dirty-flag check forces this automatically when a previous incremental run didn't complete cleanly, but --force is the manual escape hatch. Safe to delete .gitnexus/parse-cache.json at any time — content-addressed, will be regenerated.
Why: Incremental writeback is selective DB row replacement; if the on-disk state is inconsistent for any reason, a full rebuild is the cheapest path back to a known-good index.

Embeddings vanished after analyze

Trigger: Semantic search quality drops; stats.embeddings in meta.json is 0 after refresh.
Do: Re-run npx gitnexus analyze --embeddings to regenerate. Check the analyze log for a Warning: could not load cached embeddings line — if present, the cache restore failed (corrupt DB / schema mismatch) and the rebuild had nothing to preserve. If you intentionally passed --drop-embeddings, this is expected.
Why: Plain analyze preserves prior vectors by re-inserting them after the rebuild; the only ways to end up at zero are an explicit --drop-embeddings, a cache-load failure (now logged), or a model/dimension change that invalidates the cache.

MCP lists no repos

Trigger: MCP stderr says no indexed repos.
Do: npx gitnexus analyze in the target repo; verify npx gitnexus list shows it.
Why: MCP discovers repos via ~/.gitnexus/registry.json, populated by analyze.

Wrong repo in multi-repo setups

Trigger: Query/impact results belong to another project.
Do: Call list_repos, then pass repo on subsequent tools.
Why: Default target is ambiguous when multiple repos are registered.

LadybugDB lock / "database busy"

Trigger: Errors opening .gitnexus/lbug while MCP and analyze both run.
Do: Stop overlapping processes (one writer at a time). Retry analyze or restart MCP.
Why: Embedded DB expects single-process ownership.

Publishing & supply chain

npm: Do not publish from unreviewed automation. Bump version intentionally; tag releases to match package.json.
Dependencies: Minimal, auditable package.json changes; run tests and CI after lockfile updates.
License: PolyForm Noncommercial 1.0.0 — do not relicense without maintainer approval.

Escalation

Stop and ask a human maintainer when:

Impact analysis shows HIGH/CRITICAL risk and the task still requires the change.
You need to alter CI, release, or security-sensitive config.
Requirements conflict (e.g. "speed up analyze" vs "must keep all embeddings on huge repo").
You are unsure whether data loss is acceptable (clean, forced migrations, schema changes).

ARCHITECTURE.md — components and data flow
RUNBOOK.md — commands for recovery
CONTRIBUTING.md — PR and commit expectations

5.1 KiB Raw Blame History