chore: split runtime and development dependencies (#5985)

docs/rules/02-tech-stack.md

@@ -104,10 +104,11 @@
 
 | Item | Detail |
 |---|---|
-| Source file | `requirements.in` — edit this to add or upgrade dependencies |
-| Lock file | `requirements.txt` — generated by `pip-compile`; never edit manually |
-| Tool | `pip-tools` (`pip-compile`, `pip-sync`) |
-| Install | `pip install -r requirements.txt` |
+| Runtime source | `requirements.in` — production/runtime dependencies only |
+| Dev/test/lint/build source | `requirements-dev.in` — includes runtime plus pytest, coverage tooling, pylint, and build support |
+| Compatibility entry | `requirements.txt` — delegates to `requirements.in`; not a committed cross-platform lock |
+| Runtime install | `pip install -r requirements.txt` |
+| Dev/test/lint/build install | `pip install -r requirements-dev.in` |
 
 ---
 

docs/rules/03-commands.md

@@ -12,11 +12,11 @@ python3 -m venv venv
 source venv/bin/activate          # macOS / Linux
 .\venv\Scripts\activate           # Windows
 
-# Install pip-tools
-pip install pip-tools
-
-# Install project dependencies
+# Install runtime dependencies
 pip install -r requirements.txt
+
+# Install development/test/lint/build dependencies
+pip install -r requirements-dev.in
 ```
 
 ---
@@ -24,20 +24,17 @@ pip install -r requirements.txt
 ## Dependency Management
 
 ```bash
-# Compile requirements.txt from requirements.in (full recompile)
-pip-compile requirements.in
-
-# Upgrade a single package without touching others
-pip-compile --upgrade-package <package-name> requirements.in
-
-# Install from the generated lock file
+# Install runtime dependencies
 pip install -r requirements.txt
+
+# Install test/lint/build dependencies
+pip install -r requirements-dev.in
 ```
 
 **Rules:**
-- Always edit `requirements.in` to add or change dependencies.
-- Never edit `requirements.txt` manually — it is a generated lock file.
-- After any change to `requirements.in`, re-run `pip-compile requirements.in` and commit both files together.
+- Runtime dependencies belong in `requirements.in`.
+- Test, coverage, lint, and explicit build tooling belong in `requirements-dev.in`.
+- `requirements.txt` is a compatibility entry that delegates to `requirements.in`; do not replace it with a local cross-platform lock file.
 
 ---
 
@@ -83,7 +80,7 @@ pylint app/chain/download.py
 ## Security Scan
 
 ```bash
-# Run safety check against the lock file
+# Run safety check against the runtime compatibility entry
 safety check -r requirements.txt --policy-file=safety.policy.yml
 
 # Save report to file
@@ -91,7 +88,7 @@ safety check -r requirements.txt --policy-file=safety.policy.yml > safety_report
 ```
 
 **Rules:**
-- Run after every change to `requirements.txt`.
+- Run after runtime dependency changes; include `requirements-dev.in` when development/test/lint/build dependencies change.
 - No new high-severity vulnerabilities may be introduced.
 
 ---

docs/rules/06-code-styles.md

@@ -111,7 +111,7 @@ except:
 
 ## What Not To Do
 
-- Do not introduce new third-party libraries without updating `requirements.in` and running `pip-compile`.
+- Do not introduce new third-party libraries without placing them in the correct dependency entry: runtime packages in `requirements.in`, test/lint/build tooling in `requirements-dev.in`.
 - Do not use `requests` or `httpx` directly for external HTTP calls — use `RequestUtils` from `app/utils/http.py`.
 - Do not issue raw SQLAlchemy queries from chains, modules, or endpoints — use the `*_oper.py` classes.
 - Do not add TODO or FIXME without context. Only keep one if it is genuinely deferred and cannot be addressed in the current task.

docs/rules/11-quality-and-security.md

@@ -57,7 +57,7 @@ pylint app/
 safety check -r requirements.txt --policy-file=safety.policy.yml
 ```
 
-- Run after every change to `requirements.txt`.
+- Run after runtime dependency changes; scan the development dependency entry as well when `requirements-dev.in` changes.
 - No new high-severity vulnerabilities may be introduced.
 - If a vulnerability cannot be patched immediately, document it explicitly in the PR description.
 
@@ -129,7 +129,7 @@ Before marking any task as complete:
 
 - [ ] Related pytest tests pass
 - [ ] No new pylint error-level issues in `pylint app/`
-- [ ] If dependencies changed: `pip-compile requirements.in` was run and `safety check` passes
+- [ ] If dependencies changed: the package is in the correct runtime or dev dependency entry, and `safety check` passes for the affected entry
 - [ ] If CLI behavior changed: `docs/cli.md` and related tests are updated
 - [ ] If MCP/API behavior changed: `docs/mcp-api.md` and related skill files are updated
 - [ ] If database schema changed: a new Alembic migration exists under `database/versions/`

docs/rules/12-collaboration-and-distribution.md

@@ -100,11 +100,10 @@ ci: improve docker build cache
 
 When updating a dependency:
 
-1. Update `requirements.in` with the new version constraint.
-2. Run `pip-compile requirements.in` to regenerate `requirements.txt`.
-3. Run `safety check -r requirements.txt --policy-file=safety.policy.yml`.
+1. Decide the dependency layer: runtime packages go to `requirements.in`; test, coverage, lint, and explicit build tooling go to `requirements-dev.in`.
+2. Keep `requirements.txt` as the compatibility entry that delegates to `requirements.in`; do not commit a locally generated cross-platform lock file.
+3. Run `safety check -r requirements.txt --policy-file=safety.policy.yml`; include the dev dependency entry when `requirements-dev.in` changed.
 4. Run the full test suite: `pytest`.
-5. Commit both `requirements.in` and `requirements.txt` together.
 
 ---