mirror of
https://github.com/abhigyanpatwari/GitNexus.git
synced 2026-09-23 00:41:36 +00:00
0a4b31b3c5
* 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
85 lines
3.8 KiB
Markdown
85 lines
3.8 KiB
Markdown
# 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
|
|
|
|
1. **Never commit secrets** — API keys, tokens, real `.env` values, private URLs, session cookies. Use `.env.example` with placeholders.
|
|
2. **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.
|
|
3. **Run impact analysis before editing shared symbols** — `impact` (upstream) for functions/classes/methods others call. Do not ignore HIGH/CRITICAL without maintainer sign-off.
|
|
4. **Run `detect_changes` before commit** — confirm diffs map to expected symbols/processes when the graph is available.
|
|
5. **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).
|
|
|
|
---
|
|
|
|
## Related docs
|
|
|
|
- [ARCHITECTURE.md](ARCHITECTURE.md) — components and data flow
|
|
- [RUNBOOK.md](RUNBOOK.md) — commands for recovery
|
|
- [CONTRIBUTING.md](CONTRIBUTING.md) — PR and commit expectations
|