82 lines
6.4 KiB
Markdown
82 lines
6.4 KiB
Markdown
# 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 <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.
|