90083f886a
The project is still greenfield (no production deployment) so this is the last safe moment to flatten the migration archaeology before the checksum history starts mattering for real. Schema changes - 18 migration files (531 lines) → one V1__init.sql (~380 lines) declaring the final end-state: RBAC + claim mappings + runtime management + config + audit + outbound + alerting, plus seed data (system roles, Admins group, default environment). - Drops the data-repair statements from V14 (firemode backfill), V16 (subjectFingerprint migration), V17 (ACKNOWLEDGED → FIRING coercion) — they were no-ops on any DB that starts at V1. - Declares condition_kind_enum with AGENT_LIFECYCLE from the start (was added retroactively by V18). - Declares alert_state_enum with three values only (was five, then swapped in V17) and alert_instances with read_at / deleted_at columns from day one (was added by V17). - alert_reads table never created (V12 created, V17 dropped). - alert_instances_open_rule_uq built with the V17 predicate from the start. Test changes - Replace V12MigrationIT / V17MigrationIT / V18MigrationIT with one SchemaBootstrapIT that asserts the combined invariants: tables present, alert_reads absent, enum value sets, alert_instances has read_at + deleted_at, open_rule_uq exists and is unique, env-delete cascade fires. Verification - pg_dump of the new V1 matches the pg_dump of V1..V18 applied in sequence (bytewise modulo column order and Postgres-auto FK names). - Full alerting IT suite (53 tests across 6 classes) green against the new schema. - The 47 pre-existing test failures on main (AgentRegistrationIT, SearchControllerIT, ClickHouseStatsStoreIT, …) are unrelated and fail identically without this change. Developer impact - Existing local DBs will fail checksum validation on boot. Wipe: docker compose down -v (or drop the tenant_default schema). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
102 lines
5.4 KiB
Markdown
102 lines
5.4 KiB
Markdown
<!-- gitnexus:start -->
|
|
# GitNexus — Code Intelligence
|
|
|
|
This project is indexed by GitNexus as **cameleer-server** (8801 symbols, 22808 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
|
|
|
|
> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
|
|
|
|
## Always Do
|
|
|
|
- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
|
|
- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
|
|
- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
|
|
- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
|
|
- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
|
|
|
|
## When Debugging
|
|
|
|
1. `gitnexus_query({query: "<error or symptom>"})` — find execution flows related to the issue
|
|
2. `gitnexus_context({name: "<suspect function>"})` — see all callers, callees, and process participation
|
|
3. `READ gitnexus://repo/cameleer-server/process/{processName}` — trace the full execution flow step by step
|
|
4. For regressions: `gitnexus_detect_changes({scope: "compare", base_ref: "main"})` — see what your branch changed
|
|
|
|
## When Refactoring
|
|
|
|
- **Renaming**: MUST use `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` first. Review the preview — graph edits are safe, text_search edits need manual review. Then run with `dry_run: false`.
|
|
- **Extracting/Splitting**: MUST run `gitnexus_context({name: "target"})` to see all incoming/outgoing refs, then `gitnexus_impact({target: "target", direction: "upstream"})` to find all external callers before moving code.
|
|
- After any refactor: run `gitnexus_detect_changes({scope: "all"})` to verify only expected files changed.
|
|
|
|
## Never Do
|
|
|
|
- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
|
|
- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
|
|
- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
|
|
- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
|
|
|
|
## Tools Quick Reference
|
|
|
|
| Tool | When to use | Command |
|
|
|------|-------------|---------|
|
|
| `query` | Find code by concept | `gitnexus_query({query: "auth validation"})` |
|
|
| `context` | 360-degree view of one symbol | `gitnexus_context({name: "validateUser"})` |
|
|
| `impact` | Blast radius before editing | `gitnexus_impact({target: "X", direction: "upstream"})` |
|
|
| `detect_changes` | Pre-commit scope check | `gitnexus_detect_changes({scope: "staged"})` |
|
|
| `rename` | Safe multi-file rename | `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` |
|
|
| `cypher` | Custom graph queries | `gitnexus_cypher({query: "MATCH ..."})` |
|
|
|
|
## Impact Risk Levels
|
|
|
|
| Depth | Meaning | Action |
|
|
|-------|---------|--------|
|
|
| d=1 | WILL BREAK — direct callers/importers | MUST update these |
|
|
| d=2 | LIKELY AFFECTED — indirect deps | Should test |
|
|
| d=3 | MAY NEED TESTING — transitive | Test if critical path |
|
|
|
|
## Resources
|
|
|
|
| Resource | Use for |
|
|
|----------|---------|
|
|
| `gitnexus://repo/cameleer-server/context` | Codebase overview, check index freshness |
|
|
| `gitnexus://repo/cameleer-server/clusters` | All functional areas |
|
|
| `gitnexus://repo/cameleer-server/processes` | All execution flows |
|
|
| `gitnexus://repo/cameleer-server/process/{name}` | Step-by-step execution trace |
|
|
|
|
## Self-Check Before Finishing
|
|
|
|
Before completing any code modification task, verify:
|
|
1. `gitnexus_impact` was run for all modified symbols
|
|
2. No HIGH/CRITICAL risk warnings were ignored
|
|
3. `gitnexus_detect_changes()` confirms changes match expected scope
|
|
4. All d=1 (WILL BREAK) dependents were updated
|
|
|
|
## Keeping the Index Fresh
|
|
|
|
After committing code changes, the GitNexus index becomes stale. Re-run analyze to update it:
|
|
|
|
```bash
|
|
npx gitnexus analyze
|
|
```
|
|
|
|
If the index previously included embeddings, preserve them by adding `--embeddings`:
|
|
|
|
```bash
|
|
npx gitnexus analyze --embeddings
|
|
```
|
|
|
|
To check whether embeddings exist, inspect `.gitnexus/meta.json` — the `stats.embeddings` field shows the count (0 means no embeddings). **Running analyze without `--embeddings` will delete any previously generated embeddings.**
|
|
|
|
> Claude Code users: A PostToolUse hook handles this automatically after `git commit` and `git merge`.
|
|
|
|
## CLI
|
|
|
|
| Task | Read this skill file |
|
|
|------|---------------------|
|
|
| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
|
|
| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
|
|
| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
|
|
| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
|
|
| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
|
|
| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
|
|
|
|
<!-- gitnexus:end -->
|