docs: document .venv fix so documented test commands work

[labgadget015-dotcom]

What

• Add a note to CLAUDE.md documenting the one-line fix for the broken .venv: set include-system-site-packages = true in .venv/pyvenv.cfg so the documented source .venv/bin/activate && pytest flow resolves pytest/ruff from the system install.
• Root cause: .venv/bin/python is a symlink to /usr/bin/python3 but the venv shipped with include-system-site-packages = false and zero installed packages, so pytest failed with No module named pytest.

Why

The test suite was never red — under the system python it's 1492 passed, 2 skipped at 77.65% coverage. The ".venv" trap was an environment/config issue, not a code bug. The note prevents the next session from re-tripping it.

Verification (already run on host)

• source .venv/bin/activate && python -m pytest --version -> pytest 9.0.3
• Full suite via venv: 1492 passed, 2 skipped; coverage 77.65% (gate met)
• python -m ruff check . -> All checks passed!

Note

.venv/pyvenv.cfg is gitignored, so the cfg flip itself is host-local (applied on m900). This PR only records the knowledge in CLAUDE.md. Do NOT rm -rf .venv.

(Note: this commit also carries a pre-existing staged .devcontainer/devcontainer-lock.json from the working tree; it is unrelated to this change and can be dropped on merge if undesired.)

[github-actions]

📊 Code Complexity Analysis

Summary:

• Total Functions Analyzed: 844
• Average Complexity: 3.59
• High Complexity Functions: 29
• Low Maintainability Files: 60

⚠️ High Complexity Functions

These functions exceed the complexity threshold and should be refactored:

File	Function	Complexity	Line
core/risk_scorer.py	score_pull_request	35	141
autopilot/autopilot.py	generate_summary	24	195
autopilot/staleness_engine.py	process_stale_prs	16	281
autopilot/ai_optimization/performance_monitor.py	get_benchmark_stats	15	184
.github/scripts/batch_scan_dependabot.py	main	15	64
.github/scripts/weekly_digest.py	build_blocks	15	38
autopilot/recommendation_contract.py	validate	14	54
.github/scripts/workflow_monitor.py	get_workflow_statistics	14	216
.github/scripts/metrics_collector.py	parse_workflow_metrics	14	148
.github/scripts/setup_branch_protection.py	main	14	240

... and 19 more

Recommendations:

• Break down large functions into smaller, focused units
• Extract complex conditional logic into separate functions
• Use early returns to reduce nesting

🔧 Low Maintainability Files

These files have low maintainability scores and may need refactoring:

File	Score	Status
.github/scripts/health_dashboard_generator.py	28.14	🔴
.github/scripts/workflow_monitor.py	33.73	🔴
.github/scripts/ai_code_suggestor.py	33.76	🔴
.github/scripts/ai_workflow_optimizer.py	35.51	🔴
.github/scripts/performance_benchmark.py	39.46	🔴
.github/scripts/self_healing_system.py	40.27	🔴
.github/scripts/threshold_monitor.py	41.13	🔴
.github/scripts/parallel_code_analyzer_optimized.py	41.16	🔴
autopilot/tests/test_recommendation_contract.py	42.05	🔴
autopilot/autopilot.py	42.45	🔴
autopilot/ai_optimization/anomaly_detector.py	42.56	🔴
.github/scripts/refactoring_assistant.py	43.03	🔴
autopilot/ai_optimization/intelligent_cache.py	43.28	🔴
autopilot/ai_optimization/commit_summarizer.py	44.05	🔴
.github/scripts/async_parallel_analyzer.py	44.47	🔴
autopilot/ai_optimization/performance_monitor.py	44.69	🔴
.github/scripts/badge_generator.py	45.28	🔴
.github/scripts/copilot_integration.py	45.37	🔴
.github/scripts/distributed_monitoring.py	45.53	🔴
autopilot/dependency_graph.py	45.65	🔴
.github/scripts/elite_copilot.py	45.69	🔴
.github/scripts/issue_auto_creator.py	46.39	🔴
.github/scripts/cost_calculator.py	46.4	🔴
.github/scripts/inline_pr_commenter.py	46.63	🔴
.github/scripts/complexity_reporter.py	46.78	🔴
.github/scripts/pr_triage.py	47.13	🔴
core/risk_scorer.py	48.15	🔴
autopilot/ai_optimization/nlp_relevance_filter.py	48.43	🔴
.github/scripts/pr_inline_commenter.py	48.47	🔴
.github/scripts/dependency_audit.py	48.7	🔴
autopilot/staleness_engine.py	48.73	🔴
.github/scripts/metrics_collector.py	48.91	🔴
.github/scripts/dependency_updater.py	48.91	🔴
autopilot/ai_optimization/ml_priority_scorer.py	49.53	🔴
.github/scripts/parallel_code_analyzer.py	49.96	🔴
autopilot/ai_optimization/api_optimizer.py	50.46	🟡
.github/scripts/workflow_optimizer.py	51.67	🟡
.github/scripts/cot_selector.py	51.73	🟡
.github/scripts/release_manager.py	51.92	🟡
.github/scripts/check_quality.py	52.33	🟡
.github/scripts/auto_pr.py	52.72	🟡
.github/scripts/changelog_generator.py	53.13	🟡
.github/scripts/notification_manager.py	53.58	🟡
.github/scripts/prometheus_exporter.py	54.96	🟡
.github/scripts/weekly_digest.py	55.02	🟡
.github/scripts/llm_router.py	55.19	🟡
core/audit_logger.py	55.6	🟡
.github/scripts/gather_context.py	56.0	🟡
.github/scripts/batch_scan_dependabot.py	56.3	🟡
core/llm_provider.py	56.32	🟡
.github/scripts/streaming_results.py	56.64	🟡
.github/scripts/setup_branch_protection.py	57.0	🟡
.github/scripts/optimized_github_client.py	58.27	🟡
agents/orchestrator_agent.py	59.02	🟡
core/incident_freeze.py	59.67	🟡
core/github_client.py	61.96	🟡
core/message_queue.py	63.22	🟡
core/agent_config.py	63.82	🟡
autopilot/decisions/ledger.py	63.92	🟡
core/idempotency.py	64.45	🟡

Maintainability Index Guide:

• 🟢 85-100: Excellent maintainability
• 🟡 65-84: Good maintainability
• 🟠 50-64: Moderate maintainability (consider refactoring)
• 🔴 0-49: Poor maintainability (needs refactoring)

[github-actions]

🟢 Risk Assessment: LOW (0.0/10)

Analysed 2 files, 21+ / 0− lines. Test coverage unchanged or improved.

Scoring breakdown

Factor	Score

✅ Eligible for auto-merge (subject to CI passing).

[github-actions]

🤖 Elite AI Copilot Analysis

Elite AI Copilot Analysis Report

Generated: 2026-08-27 06:27:03
Session ID: copilot_1787812023
Repository: .

🎯 Health Score: 100.0/100

🚀 Top Recommendations

1. ✅ Repository is in excellent shape - continue current practices

📊 Detailed Insights

Code Quality Baseline Established

• Category: code_quality
• Severity: info
• Description: Repository code quality metrics captured
• Suggested Action: Continue monitoring for regressions
• Confidence: 90%

Security Scan Initiated

• Category: security
• Severity: info
• Description: No critical vulnerabilities detected in initial scan
• Suggested Action: Enable continuous security monitoring
• Confidence: 85%

Repository Structure Analyzed

• Category: architecture
• Severity: info
• Description: Well-organized modular structure detected
• Suggested Action: Maintain separation of concerns
• Confidence: 80%

Performance Baseline Captured

• Category: performance
• Severity: info
• Description: Repository performance metrics recorded
• Suggested Action: Monitor for performance regressions
• Confidence: 75%

Documentation Structure Good

• Category: documentation
• Severity: info
• Description: Comprehensive documentation files present
• Suggested Action: Keep documentation in sync with code changes
• Confidence: 90%

---

Powered by Elite AI Copilot v1.0

[github-actions]

🔍 Pre-commit Checks

✅ All pre-commit checks passed!

Your code follows the project style guidelines.

---

Pre-commit hooks help maintain code quality and consistency.

[github-actions]

Code Quality Analysis ❌ FAILED

Duration: 0.03s
Total Issues: 10

Tool Results

• pylint: ❌
• flake8: ❌
• bandit: ❌
• radon_cc: ❌
• radon_mi: ❌

View detailed results

{
  "timestamp": "2026-08-27 06:27:11",
  "elapsed_seconds": 0.03,
  "summary": {
    "total_issues": 10,
    "critical": 0,
    "high": 0,
    "medium": 0,
    "low": 0
  },
  "tools": {
    "pylint": {
      "status": "failed",
      "output": "",
      "errors": "Pylint error: [Errno 2] No such file or directory: 'pylint'"
    },
    "flake8": {
      "status": "failed",
      "output": "",
      "errors": "Flake8 error: [Errno 2] No such file or directory: 'flake8'"
    },
    "bandit": {
      "status": "failed",
      "output": "",
      "errors": "Bandit error: [Errno 2] No such file or directory: 'bandit'"
    },
    "radon_cc": {
      "status": "failed",
      "output": "",
      "errors": "Radon error: [Errno 2] No such file or directory: 'radon'"
    },
    "radon_mi": {
      "status": "failed",
      "output": "",
      "errors": "Radon MI error: [Errno 2] No such file or directory: 'radon'"
    }
  },
  "passed": false
}

[github-actions]

🔒 Security Scan Results

🛡️ Bandit Security Scan

• 🔴 HIGH: 0
• 🟡 MEDIUM: 5
• 🟢 LOW: 107

📦 Dependency Vulnerabilities

• Total vulnerable dependencies: 61

Vulnerable Dependencies:

• pygithub 2.10.0
• aiohttp 3.14.3
• multidict 6.7.1
• yarl 1.24.5
• pyyaml 6.0.3
• ... and 56 more

---

Security scans run automatically on every PR. View detailed reports in the Actions tab.

[labgadget015-dotcom]

🤖 DRC Agent Analysis

Recommendation: 🟠 P1 IMPORTANT

Summary: REALIST recommended Solution 2 (CLAUDE.md + Automated venv Bootstrap Script) over DREAMER's top pick of Solution 4 (Devcontainer). This is the correct pragmatic call given solo operator bandwidth constraints and the immediate need to unblock the documented workflow.

Next steps:

1. Step 1: Verify repo structure - confirm scripts/ directory exists or create it with mkdir -p scripts/
2. Step 2: Create scripts/bootstrap_venv.sh with set -euo pipefail, venv creation using --system-site-packages, and explicit post-activation verification instructions
3. Step 3: chmod +x scripts/bootstrap_venv.sh and verify locally by running in a shell without active venv
4. Step 4: Add ## Environment Troubleshooting section to CLAUDE.md with Symptom/Root Cause/Fix A/Fix B/Warning/Note structure, ordering bootstrap script as the preferred fix
5. Step 5: Update CLAUDE.md Setup section to reference bootstrap script as canonical venv creation command

Strategic fit: Consulting: medium · Product: medium · Tech debt: reduces

---

Analysed by GadgetLab DRC Agent (Dreamer → Realist → Critic) · Run run_1787811996343

[Copilot]

🟡 Changes recommended

It includes an out-of-scope devcontainer lockfile change for a docs-focused PR and the new CLAUDE.md note should be clarified to avoid implying the repo “ships” a prebuilt .venv.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Documents a host-specific workaround for a broken local .venv so the repository’s documented pytest/ruff commands run successfully, and (incidentally) adds a devcontainer feature lockfile.

Changes:

• Add a CLAUDE.md note describing the one-line pyvenv.cfg change (include-system-site-packages = true) to make pytest/ruff available via system site-packages on the affected host.
• Add .devcontainer/devcontainer-lock.json locking the devcontainer feature SHAs/versions.

File summaries

File	Description
CLAUDE.md	Adds documentation about a host-local .venv misconfiguration and the workaround to restore the documented test flow.
.devcontainer/devcontainer-lock.json	Introduces a devcontainer lockfile pinning feature versions/digests (extra change beyond the docs scope).

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.