GitNexus — Code Intelligence

This project is indexed by GitNexus as PuPu (41812 symbols, 140105 relationships, 1104 execution flows).

Index stale? Run node .gitnexus/run.cjs analyze --index-only from the project root — it auto-selects an available runner. No .gitnexus/run.cjs yet? Bootstrap with npx, bunx, or pnpm dlx — e.g. bunx gitnexus@latest analyze (npm 11 npx crash; #1939).

Always Do

• MUST run impact before editing. Use impact({target: "symbolName", direction: "upstream"}) or node .gitnexus/run.cjs impact "symbolName" --direction upstream --repo .; report callers, processes, and risk. Never substitute grep for graph analysis.
• MUST analyze graph changes before committing. Use detect_changes({scope: "all"}) (MCP) or node .gitnexus/run.cjs detect-changes --scope all --repo . (CLI fallback). partial: true or truncated: true is not a clean check — a zero means unseen, not unaffected; re-run it. For regression review: detect_changes({scope: "compare", base_ref: "main"}) or node .gitnexus/run.cjs detect-changes --scope compare --base-ref "main" --repo ..
• MUST warn on HIGH/CRITICAL risk pre-edit; never use riskSharedAxes to waive a HIGH/CRITICAL risk warning. Compare File/symbol: MCP File omits axes; Graph-RAG expands File.
• MUST treat risk: UNKNOWN as unresolved, not as low. An empty caller set is not evidence the symbol is unused — it can also mean the callers are not resolvable by the index (plain-object property access, dynamic dispatch, cross-language calls). impact pairs UNKNOWN with a riskNote saying so. Confirm with a text search before treating the symbol as safe to change or delete; do not proceed on the strength of a zero.
• MUST use query({search_query: "concept"}) for concepts/flows, context({name: "symbolName"}) for a named symbol, or impact for blast radius, on read-only callers, dependencies, imports, or execution flow. Graph first; text search only for empty/UNKNOWN/literals.
• For security review, explain({target: "fileOrSymbol"}) lists taint findings (source→sink flows; needs analyze --pdg).

Never Do

• NEVER edit a function, class, or method before MCP/CLI impact analysis.
• NEVER ignore HIGH or CRITICAL risk warnings from impact analysis, and never read UNKNOWN as an all-clear — it means the walk could not answer, which is the one verdict that requires confirming by other means.
• NEVER rename symbols with find-and-replace — use rename which understands the call graph.
• NEVER commit before MCP/CLI graph change analysis.

Resources

CLI

PuPu Conventions (for Codex and any agent writing code here)

These are load-bearing — violating them breaks the build or the architecture. Canonical source: CLAUDE.md and .claude/CLAUDE.md.

Frontend (src/, electron/):

• JavaScript only — no TypeScript, no PropTypes. Never create .ts / .tsx files.
• Inline styles only — no CSS modules, no styled-components. Theme via isDark from ConfigContext.
• All function components — no class components.
• Custom router BUILTIN_COMPONENTs/mini_react/mini_router.js for internal routing — not react-router-dom.
• React never touches ipcRenderer. System access goes through preload bridges (window.unchainAPI, ollamaAPI, themeAPI, etc.). IPC channel constants in electron/shared/ must match both ends.
• localStorage writes go only through helpers in src/SERVICEs/, never directly from components.
• Overlay zIndex comes from Z in BUILTIN_COMPONENTs/layer/z_layers.js — never a literal — for anything portalled to document.body or position: fixed. z_layers_guard enforces this, but only for literals ≥1000 (CONTENT_RAISED: 10 and SCROLL_OVERLAY: 500 are legitimately small), so sub-1000 literals and wrong-layer choices are review's job: Z.MODAL where Z.POPOVER belongs passes the guard and is still wrong.
• Electron tests have both .js and .cjs variants — keep them in sync.

Backend (unchain_runtime/server/):

• Python Flask sidecar. Key files: routes.py / route_chat.py, unchain_adapter.py, memory_factory.py, character_store.py. Tests in unchain_runtime/server/tests/.
• Run unchain tests with its own pytest (run_tests.sh) — do NOT use npx jest. Run PuPu/JS tests with react-scripts test.
• After changing unchain .py, the sidecar must be restarted to take effect — note this in your report.

General:

• Run GitNexus impact analysis before editing any symbol (see the GitNexus block above). Warn on HIGH / CRITICAL.
• Match the surrounding code's style and idiom. No unrelated refactoring.
• The agent currently implementing a direct Release child may refine that issue's GitHub body before or during implementation. [DRAFT] is initial intent, not a delivery gate; this body-only authority does not permit scope, title, label, Project-field, assignee, parent/child, release-membership, defer/cancel, or closure changes. GitHub assignee alone does not establish implementation responsibility.

Removed mechanisms: Quorum/court workflows, code-owner routing, role confirmations, case tooling, and their role definitions and records have been removed. Do not recreate them or use them as a delivery gate. Historical material is available through Git history only.

Release workflow: Prefer the smallest matching release skill: release-open-sprint, issue-draft-ticket, issue-refine-ticket, issue-feature-audit, or release-close-sprint. These skills plus the Release issue, a direct implementation plan when needed, and evidence-backed tests are the project workflow. If a skill is unavailable, proceed with the equivalent direct workflow; never fall back to a retired mechanism.

Cross-boundary work: Any change crossing a repository, process, provider, serialization, persistence, or durable-state boundary must follow .claude/rules/cross-boundary-contract-gate.md. Record BC-###, applicable SEQ-###, and AC-### directly in the Release issue or implementation plan, then test the exact deployed artifact pair before active rollout. No owner field, confirmation, proposal, ruling, or court record is permitted or required.

Shared project skills

All maintained PuPu skills live in .agents/skills/<name>/SKILL.md. Codex discovers this directory directly; .claude/skills/<name> is a relative symlink to the same directory for Claude Code. Edit the canonical files only, keep both entrypoints aligned, and resolve scripts/references relative to the loaded skill directory. Do not recreate personal copies or retired skill names. Release skills manage versions and the release pipeline; issue skills manage ticket intake, refinement, implementation and audit; dev-ui skills manage UI conventions; community skills manage growth, repository polling, tags and Store verification. GitNexus skills keep their upstream names.