Project Operating & Agent Guidelines

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

Trivial edits (≤1 file, no exported symbols): Modify directly without querying either tool.
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.
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.
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.
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 <cmd> --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 <venv-python> -m pip and Django with <venv-python> 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.

6.4 KiB Raw Blame History