mirror of https://github.com/abhigyanpatwari/GitNexus.git synced 2026-08-28 05:25:25 +00:00

docs: optimize context files for LLM accuracy and token efficiency (#857 )

* docs: optimize context files for LLM accuracy and token efficiency

Fix factual errors across all five root context files and optimize
for LLM context window efficiency.

Corrections:
- Web UI: "runs entirely in WASM" -> thin client backed by HTTP API
- Pre-commit hook: "typecheck + tests" -> formatting + typecheck only
- MCP tools: 7 -> 16 (added api_impact, route_map, tool_map,
  shape_check, group_list/query/sync/contracts/status)
- Default serve port: 3741 -> 4747
- E2E tests: "5 tests" -> 7 spec files
- ESLint: "no config" -> eslint.config.mjs exists with TS/React rules
- npm test: "vitest run test/unit" -> "vitest run" (full suite)
- Removed nonexistent test:all script
- ci-quality.yml: added missing format + lint job descriptions
- Pipeline phase deps: added missing structure dep on mro/communities/processes
- Ingestion entry: added missing run-analyze.ts intermediate orchestrator
- Tools Quick Reference: added missing list_repos
- Group tool examples: fixed param name (group -> name)
- Removed stale vite-plugin-wasm gotcha
- Added gitnexus-shared to repository layout tables

New documentation:
- ARCHITECTURE.md: language-agnostic graph feeding (provider pattern,
  unified capture tags, import resolution tiers, chunked parse, MRO)
- ARCHITECTURE.md: full analysis flow (10 stages with progress %)
- ARCHITECTURE.md: storage layout, LadybugDB schema, embeddings, search
- ARCHITECTURE.md: DAG runner internals (Kahn's sort, dep isolation, error handling)

Token optimization:
- Removed filler prose, compressed descriptions into dense tables
- Front-loaded key facts in every section
- Eliminated redundancy between sections
- AGENTS.md: 219 -> 201 lines. ARCHITECTURE.md: 192 -> 298 lines
  (more info in fewer tokens via tables and structure)

* docs: optimize GUARDRAILS.md for LLM context efficiency

Tighten prose without losing information:
- Compressed intro, scope section, and Signs format labels
- Shortened Sign headers (removed "Sign:" prefix)
- Replaced verbose "Instruction/Reason" labels with "Do/Why"
- Removed trailing whitespace and redundant emphasis

2026-04-16 08:43:11 +01:00

3.8 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 — if .gitnexus/meta.json shows embeddings, use npx gitnexus analyze --embeddings; plain analyze drops them.

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).
Why: Tools query LadybugDB from last analyze; git changes are invisible until re-indexed.

Embeddings vanished after analyze

Trigger: Semantic search quality drops; stats.embeddings in meta.json is 0 after refresh.
Do: npx gitnexus analyze --embeddings, confirm meta.json reflects stored embeddings.
Why: Embedding generation is opt-in; analyze without the flag does not preserve prior vectors.

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

3.8 KiB Raw Blame History