docs(contributing): align test and development instructions

.github/PULL_REQUEST_TEMPLATE/bugfix.md

@@ -8,7 +8,7 @@
 - Fixes: #
 
 ## Verification Steps
-1. Run the following command: `uv run pytest tests/integration`
+1. Run the following command: `uv run pytest src/ -k "not integration"`
 2. Describe any manual verification performed:
 
 ## Checklist

.github/PULL_REQUEST_TEMPLATE/feature.md

@@ -10,7 +10,7 @@
 - Refs: #
 
 ## Testing & Validation
-- [ ] **Unit Tests**: `uv run pytest tests/unit` passed.
+- [ ] **Unit Tests**: `uv run pytest src/ -k "not integration"` passed.
 - [ ] **Scenario Validation**: Verified that the agent can execute the trajectory.
 - [ ] **Data Integrity**: Checked that no PII or sensitive industrial data is included.
 

CONTRIBUTING.md

@@ -70,14 +70,18 @@ source .venv/bin/activate
 
 ### 2. Code Quality & Formatting
 
-We use `ruff` for both linting and formatting. Run these before every commit:
+We use `ruff` for both linting and formatting. Ruff is not included in the development dependencies, so use `uvx` to run it in an isolated environment:
 
 ```bash
-uv run ruff format .
-uv run ruff check --fix .
+uvx ruff check .
+uvx ruff format --check .
 
 ```
 
+Full-repository checks can report pre-existing lint and formatting violations.
+Focus fixes on the Python files you changed, and report unrelated failures
+separately rather than reformatting the whole repository in your PR.
+
 ### 3. Security Scanning
 
 This repo blocks secrets (API keys, tokens, credentials) at three layers:
@@ -121,25 +125,19 @@ detected, rotate/revoke it at its source first, then remove it from the code.
 Validate core logic for metrics and data parsing:
 
 ```bash
-uv run pytest tests/unit
+uv run pytest src/ -k "not integration"
 
 ```
 
-### Integration & Benchmark Validation
+### Full Suite / Integration Tests
 
-Verify that agent trajectories and environment simulations run correctly:
+Run the full suite (integration tests may require external services):
 
 ```bash
-chmod +x ./scripts/run_tests.sh
-./scripts/run_tests.sh
-
+uv run pytest src/
 ```
 
-This script validates:
-
-* **Linting**: Ruff validation.
-* **Agentic Logic**: Verification of ReAct and Plan-Execute orchestration.
-* **Asset Consistency**: Ensuring industrial asset IDs (e.g., FailureSensorIQ) match registry definitions.
+See [INSTRUCTIONS.md](INSTRUCTIONS.md#running-tests) for integration prerequisites and narrower test commands. The unit test command above does not require CouchDB or WatsonX.
 
 ---