# Project Operating & Agent Guidelines ## 1. Codebase Navigation & Analysis (Ripwire vs. Graphify) > **Rule of Thumb:** Default to **Ripwire** for all hands-on coding, AST, edits, call graphs, and tests. Reserve **Graphify** strictly for high-level architectural understanding, cross-artifact relations, and non-code assets. CLI-only (never use MCP). Route strictly by question and artifact type. Never query both tools for the same sub-task; never execute in parallel. Always prefer `--expand` over reading entire files. | Metric / Dimension | **Ripwire** (Deterministic AST) | **Graphify** (Semantic KG) | |---|---|---| | **Primary Scope** | Local source code AST, symbol graphs, in-repo text | Cross-artifact: Code + Docs + PDFs + Media + SQL Schema | | **Best at** | Callers, callees, impact, tests, quality delta, `--arch`, `--doc-drift` | Conceptual "How A relates to B", ADR/RFC context, schemas | | **Primary CLI** | `ripwire . --for="…"`, `--callers=SYM`, `--impact=SYM`, `--test-gate` | `graphify query "…"`, `graphify path "A" "B"`, `graphify explain "node"` | | **Boundary** | Prose meaning, non-code files, cross-asset concepts | Exact symbol references, impact analysis, code test gates | ### Routing Gate & Pipeline 1. **Trivial edits (≤1 file, no exported symbols):** Modify directly without querying either tool. 2. **Execution routing:** - Hands-on coding, symbols, AST, usages, impact, and tests → **Ripwire**. - Architecture discovery, cross-artifact concepts (PDF, media, docs, ADR/RFC), and SQL schemas → **Graphify**. (Note: `.sql` symbols use Ripwire; schema semantics use Graphify). - Ambiguous/Mixed tasks → Run `ripwire . --help-task="task"` to classify, then route by artifact. 3. **Graphify query rules (when selected):** - Requires `graphify-out/graph.json`; if absent, route code questions to Ripwire. - **Bilingual alignment:** Match terms directly against `graphify-out/graph.json` vocabulary. Prioritize English code identifiers; include Persian terms only when verified in graph documentation/requirements. Never rely on internal translation or stemming. - **Traversal selection:** Use BFS for broad relationships, DFS for dependency traces, `path` for shortest linkage, and `explain` for node neighbors. - Always cross-verify critical graph findings against source code before editing. 4. **Pre-edit impact gate:** Before any non-trivial code change, inspect the target symbol with both `ripwire . --impact=SYM` and `ripwire . --uses=SYM`; if either query refuses or is ambiguous, resolve the symbol using the CLI guidance before editing. 5. **Post-edit pipeline:** Run `ripwire . --test-gate` followed by `ripwire . --quality-delta`. --- ## 2. Dynamic Help, Self-Correction & Staleness Never stall on tool errors or hallucinate flags. Dynamic CLI help always takes precedence over memorized parameters. - **Help Precedence:** Before using an unfamiliar or ambiguous capability, inspect `ripwire --help` or `ripwire --help=--FLAG`; if any instruction or remembered syntax conflicts with that output, the CLI help is authoritative. - **Dynamic Inspection (on error or flag confusion):** - Ripwire: `ripwire --help`, `ripwire --help=--FLAG`, `ripwire . --doctor`, `ripwire . --help-task="task"` - Graphify: `graphify --help`, `graphify --help` - **Fallback & Retries (Cap at 1):** - If a command fails or rejects flags: inspect its `--help` and retry once. - If a tool returns empty results or an explicit refusal: try the alternative tool once; if still unresolved, report to user. - If data is suspected to be stale: run `graphify update .` or `ripwire . --no-cache` and retry once. - If a tool binary is missing (`command -v` check fails): state missing dependency clearly; do not guess syntax. --- ## 3. Git Operations & Safety - **Read-only (Agent allowed):** `git status`, `git diff`, `git log`. - **Human-gated (User execution only):** `git add`, `commit`, `push`, `checkout`, `merge`, `rebase`, and branch management. If needed, request user action and pause. - **Exception:** `graphify hook install` is permitted (read-side only). --- ## 4. Development Server Lifecycle - **Binding:** Always bind Django to `0.0.0.0:8000` (LAN accessible). Never use `127.0.0.1` unless explicitly requested. - **Process Management:** Before launching, inspect port `8000`. Terminate previous project server instances and their child process trees cleanly. - **Health Verification:** Confirm exactly one process listens on `0.0.0.0:8000`, then fetch `127.0.0.1:8000` locally to verify health. - **Asset Confirmation:** When checking frontend changes, verify the served content on the live server before suggesting browser cache issues to the user. --- ## 5. Environment, Frontend & PWA Safety - **Python virtual environment:** Use the repository `.venv` for all Python and Django commands during development, tests, dependency management, and server startup. From WSL, run `.venv/Scripts/python.exe`; from Windows, run `.venv\Scripts\python.exe`. Run pip with ` -m pip` and Django with ` manage.py ...`. Do not use system Python or pip or create a second environment unless the user requests it. - **PyPI Mirror:** Use Liara's mirror: `https://package-mirror.liara.ir/repository/pypi/simple`. Use user-level pip configuration. Report downtime before falling back to public PyPI. - **Asset Versioning:** All locally served frontend assets must include `static_asset_version` in their URLs. - **PWA Lifecycle:** Keep the service worker registration URL versioned with `updateViaCache: 'none'`. - **Cache Regression Gate:** Changes to frontend caching or PWA code must pass assertions in `tests/test_views.py` and `tests/e2e/test_pwa_versioning.py`. --- ## 6. End-to-End Browser Tests (Playwright) - **Organization:** Place tests in `tests/e2e/`, mark with `e2e`, and run against Django's transactional `live_server`. - **Scope & Lifecycle:** Use managed Chromium and BrowserContext from `tests/e2e/conftest.py`. Keep Playwright function-scoped to prevent event loop deadlocks with Django's synchronous database setup. - **Page Objects:** Encapsulate interactions inside `tests/e2e/pages/`. Tests must assert user-visible outcomes only. - **Synchronization:** Never use hardcoded sleeps. Rely on Playwright locators, `expect`, navigation, and state-change assertions. - **Diagnostics:** Maintain automatic screenshot/trace capture on failure. PWA scenarios must enable service workers and use the `pwa` marker.