Add repo map, MCP baseline verification, and repo-specific agent skills

.github/dependabot.yml

@@ -1,29 +1,14 @@
-groupthinking-patch-3
- # To get started with Dependabot version updates, you'll need to specify which
- master
-# package ecosystems to update and where the package manifests are located.
-# Please see the documentation for all configuration options:
-# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
-
 version: 2
 updates:
-groupthinking-patch-3
-  - package-ecosystem: "" # See documentation for possible values
-
- groupthinking-patch-2
-  - package-ecosystem: "" # See documentation for possible values
-
   - package-ecosystem: "pip"
-    directory: "/" # Location of package manifests
+    directory: "/"
     schedule:
       interval: "weekly"
   - package-ecosystem: "npm"
-    directory: "/frontend" # Location of package manifests
+    directory: "/frontend"
     schedule:
       interval: "weekly"
   - package-ecosystem: "docker"
-master
-master
-    directory: "/" # Location of package manifests
+    directory: "/"
     schedule:
       interval: "weekly"

.github/skills/mcp-protocol-debugging/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: mcp-protocol-debugging
+description: Guide for exercising and debugging this repo's MCP JSON-RPC server (mcp_server/main.py), including capability negotiation (initialize/tools/list), tool calls, and error handling. Use when asked to verify, debug, or extend MCP support in self-correcting-executor.
+---
+
+This repo ships a canonical JSON-RPC MCP server at `mcp_server/main.py`
+(`MCPServer` class), independent from the FastAPI-based
+`mcp_server/real_mcp_server.py`. Use this process to verify or debug MCP
+behavior. Direct handler calls do not prove transport compatibility or MCP
+specification compliance:
+
+1. **Confirm the baseline capability negotiation works** by driving the
+   server directly in Python (no transport needed for debugging):
+
+   ```python
+   import asyncio
+   import json
+   from mcp_server.main import MCPServer
+
+   async def main():
+       server = MCPServer()
+       # 1. initialize — must return serverInfo + capabilities.tools/resources
+       init = await server.handle_request({
+           "jsonrpc": "2.0", "id": 1, "method": "initialize",
+           "params": {"clientInfo": {"name": "debug-client", "version": "1.0"}},
+       })
+       assert "error" not in init
+       advertised = {tool["name"] for tool in init["result"]["capabilities"]["tools"]}
+       assert "code_analyzer" in advertised
+
+       # 2. tools/list — must match the tools advertised in `initialize`
+       listed = await server.handle_request(
+           {"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}
+       )
+       assert "error" not in listed
+       assert {tool["name"] for tool in listed["result"]["tools"]} == advertised
+
+       # 3. tools/call — must execute real logic (code_analyzer, protocol_validator,
+       #    self_corrector), never mocked/simulated results
+       called = await server.handle_request({
+           "jsonrpc": "2.0", "id": 3, "method": "tools/call",
+           "params": {"name": "code_analyzer", "arguments": {"code": "x = 1"}},
+       })
+       assert "error" not in called
+       assert called["result"]["tool"] == "code_analyzer"
+       analysis = json.loads(called["result"]["result"]["content"][0]["text"])
+       assert analysis == {"lines_of_code": 1, "functions": 0, "complexity": 1, "imports": []}
+
+   asyncio.run(main())
+   ```
+
+2. **Run the automated baseline test** that pins this behavior down:
+
+   ```bash
+   python -m pytest tests/test_mcp_baseline.py -v
+   ```
+
+3. **When adding a new MCP tool or resource**, update all three of:
+   - `MCPServer._setup_tools` / `_setup_resources` (declares the capability)
+   - the corresponding `_execute_<tool_name>` method (real implementation,
+     never a stub/mock; inspect production behavior directly because
+     `TestMCPCompliance.test_no_placeholder_code_in_production` reports
+     placeholder patterns but does not fail the test)
+   - `tests/test_mcp_baseline.py` and/or `tests/test_mcp_compliance.py` to
+     cover the new capability.
+
+4. **Unknown or malformed methods must degrade gracefully**: `handle_request`
+   should always return a well-formed JSON-RPC response with an
+   `{"error": {"code": ..., "message": ...}}` field rather than raising
+   an unhandled exception — verify this whenever you touch `_get_handler`.
+
+5. For the FastAPI-based server (`mcp_server/real_mcp_server.py`) or the
+   quantum-specific server (`quantum_mcp_server/quantum_mcp.py`), apply the
+   same principle: prove `initialize`/capability discovery works live before
+   relying on more advanced features (subscriptions, resource reads, etc.).

.github/skills/quantum-connector-testing/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: quantum-connector-testing
+description: Guide for testing connectors/dwave_quantum_connector.py and other quantum MCP tools in self-correcting-executor without requiring a live D-Wave QPU token, while respecting this repo's "no simulation/mocks in production" convention. Use when asked to test, debug, or extend quantum computing integration.
+---
+
+This repo's D-Wave integration (`connectors/dwave_quantum_connector.py`,
+`mcp_server/quantum_tools.py`, `quantum_mcp_server/quantum_mcp.py`) is
+intentionally built against the **real** D-Wave Ocean SDK and Leap cloud
+service — it must never silently fall back to a local simulator/annealer in
+production code paths (see the removed `SimulatedAnnealingSampler` import
+and `tests/test_mcp_compliance.py::test_quantum_requires_real_qpu`).
+
+When testing or extending this code:
+
+1. **Check for `DWAVE_AVAILABLE` / `DWAVE_API_TOKEN` before assuming a QPU is
+   reachable.** Tests and scripts should `pytest.skip(...)` (not fabricate
+   results) when the token isn't set, mirroring the existing pattern in
+   `tests/test_mcp_compliance.py::test_quantum_requires_real_qpu`:
+
+   ```python
+   import os
+   import pytest
+
+   if not os.getenv("DWAVE_API_TOKEN"):
+       pytest.skip("DWAVE_API_TOKEN not set - skipping quantum test")
+   ```
+
+2. **Test the non-quantum-hardware parts directly and deterministically:**
+   - Input validation / `QuantumResult` dataclass construction
+   - Problem formulation (`BinaryQuadraticModel` / `ConstrainedQuadraticModel`
+     building) using `dimod`, which runs locally without QPU access
+   - Error handling paths that should raise/propagate a `RuntimeError`
+     (e.g. `"No D-Wave QPU available"`) instead of silently simulating
+
+3. **Never add a mock/simulated sampler as a fallback** in
+   `connectors/dwave_quantum_connector.py` or related production files —
+   inspect production fallbacks directly. In `tests/test_mcp_compliance.py`,
+   `TestMCPCompliance.test_no_placeholder_code_in_production` reports
+   TODO/FIXME/XXX/HACK markers, `placeholder`, and `NotImplementedError`
+   in `agents`, `connectors`, `mcp_server`, and `protocols`; it does not
+   fail the test or scan for mock samplers.
+   `TestMCPCompliance.test_data_processor_no_simulation` checks the runtime
+   data-processing result for a real directory or an explicit missing-data
+   error; it does not inspect quantum samplers.
+
+4. **Run the relevant test files** after any change:
+
+   ```bash
+   python -m pytest tests/test_mcp_compliance.py -k quantum -v
+   python -m pytest test_real_dwave_quantum.py -v   # requires DWAVE_API_TOKEN
+   ```
+
+5. If you need to demonstrate quantum problem formulation without hardware
+   access, use `simple_quantum_example.py` as a reference for building a
+   `BinaryQuadraticModel` locally, then document clearly that solving it on
+   real hardware requires a valid `DWAVE_API_TOKEN`.

.github/workflows/python-ci.yml

@@ -31,8 +31,7 @@ jobs:
         run: flake8 . || echo "Flake8 found issues but continuing CI"
         continue-on-error: true
       - name: Run tests with coverage
-        run: pytest --cov=. || echo "Tests failed but continuing CI"
-        continue-on-error: true
+        run: pytest --cov=.
 
   actions:
     runs-on: ubuntu-latest

docs/REPO_MAP.md

@@ -0,0 +1,145 @@
+# Repo Map, Architecture & Agentic Workflow Checklist
+
+This document maps `self-correcting-executor` for AI coding agents (Copilot
+cloud agent, Copilot CLI, etc.) so an agent run can quickly orient itself
+before making changes: what the repo does, how its pieces relate, what
+already exists for MCP/agents/tools, and what to check before commit/merge.
+
+## Repo tree (top level)
+
+```
+self-correcting-executor/
+├── agents/            # A2A agent framework + MCP-enabled agents
+├── analyzers/         # Static analysis helpers (pattern_detector, ...)
+├── auth/              # Basic auth helpers
+├── config/            # MCPConfig, component type definitions
+├── connectors/        # MCP base + concrete connectors (D-Wave, GitHub, LLM, xAI)
+├── docs/              # Architecture, planning & task docs (this file lives here)
+├── fabric/            # Integrated MCP "fabric" / state continuity core
+├── frontend/          # Vite/React UI
+├── llm/               # Continuous learning system
+├── mcp_runtime_template_hg/  # SDK/API/CLI template for MCP runtimes
+├── mcp_server/         # Canonical JSON-RPC MCP server (main.py) + quantum tools
+├── middleware/         # Security middleware
+├── orchestrator.py, orchestrator_mapreduce.py  # Task orchestration entrypoints
+├── protocols/          # Pluggable "protocol" tasks executed by the orchestrator
+├── quantum_mcp_server/ # Quantum-specific MCP server variant
+├── scripts/            # Compliance/setup/cleanup scripts
+├── tests/ + test_*.py  # Pytest suites (see pytest.ini: testpaths = tests)
+├── ui/                 # Additional UI assets/guide
+└── utils/              # Shared logger/tracker/registry utilities
+```
+
+## Mermaid diagram: high-level architecture
+
+```mermaid
+flowchart TD
+    subgraph Host["Host: AI Agent / Copilot"]
+        A[Agent orchestrator.py / orchestrator_mapreduce.py]
+    end
+
+    subgraph MCPServers["MCP Servers (this repo)"]
+        M1[mcp_server/main.py<br/>JSON-RPC MCP server]
+        M2[mcp_server/real_mcp_server.py]
+        M3[quantum_mcp_server/quantum_mcp.py]
+    end
+
+    subgraph Tools["Tools exposed via MCP"]
+        T1[code_analyzer]
+        T2[protocol_validator]
+        T3[self_corrector]
+    end
+
+    subgraph Connectors["Connectors"]
+        C1[dwave_quantum_connector.py]
+        C2[github_mcp_connector.py]
+        C3[llm_connector.py]
+        C4[xai_connector.py]
+    end
+
+    subgraph Protocols["protocols/*.py tasks"]
+        P1[data_processor]
+        P2[system_monitor]
+        P3[file_validator]
+        P4[...]
+    end
+
+    M1 --> T1
+    M1 --> T2
+    M1 --> T3
+    M2 --> C1
+    M2 --> P1
+    A --> Protocols
+    Protocols --> P1
+    Protocols --> P2
+    Protocols --> P3
+    Protocols --> P4
+```
+
+The MCP servers are separate entrypoints. This diagram does not imply that
+the task orchestrators call them or that an external client connection has
+been verified. `real_mcp_server.py` imports the D-Wave connector and the
+data processor; the other connectors are listed as repository components.
+
+## Checklist for an agent run in this repo
+
+Use this before proving/implementing anything live in this repo:
+
+- [x] **Agents** — `agents/a2a_framework.py`, `agents/a2a_mcp_integration.py`
+      implement agent-to-agent (A2A) communication over MCP.
+- [x] **Tools** — MCP tools are declared in `mcp_server/main.py`
+      (`code_analyzer`, `protocol_validator`, `self_corrector`).
+- [x] **MCP** — Baseline JSON-RPC server exists (`mcp_server/main.py`) and is
+      exercised in-process in `tests/test_mcp_baseline.py` (`initialize`,
+      `tools/list`, `tools/call`, and error handling for unknown methods).
+- [ ] **Pull / Push / Commit / Merge** — Use the repository's branch, commit
+      and pull-request workflow with the tools available in the current
+      environment. Follow `CONTRIBUTING.md` and the user's authorization
+      before publishing changes or merging.
+- [ ] **Issues** — Track work items and link PRs with `Closes #<issue>`.
+- [ ] **Code** — Run `python -m pytest tests/` (see `pytest.ini`) and the
+      lint config in `.flake8` before committing.
+- [ ] **Deps** — `requirements.txt` (runtime), `requirements-ci.txt` /
+      `requirements-test.txt` (CI/tests), `frontend/package.json` (UI).
+      Dependabot is configured in `.github/dependabot.yml`.
+- [ ] **Database** — `protocols/database_health_check.py`,
+      `utils/db_tracker.py` for DB-backed protocol tasks.
+- [ ] **Actions** — `.github/workflows/python-ci.yml` and
+      `.github/workflows/frontend-ci.yml` run CI on push/PR.
+- [ ] **Role assignment** — `middleware/security_middleware.py`,
+      `auth/basic_auth.py` for auth/authorization concerns.
+
+## MCP capability negotiation baseline
+
+The custom handler in `mcp_server/main.py` exposes the following JSON-RPC
+methods. The tests below call that handler directly: they verify its current
+behavior, not MCP specification compliance or a host/client transport
+handshake.
+
+| Method | Purpose |
+| --- | --- |
+| `initialize` | Returns `serverInfo` + `capabilities.tools` + `capabilities.resources` |
+| `tools/list` | Lists available tools independently of `initialize` |
+| `tools/call` | Executes a tool and returns real (non-mocked) results |
+| `resources/list` / `resources/read` | Lists/reads MCP resources |
+| `notifications/list` / `notifications/subscribe` | Baseline notification support |
+
+`tests/test_mcp_baseline.py` asserts `initialize`, `tools/list`, the
+`code_analyzer` tool result, and unknown-method errors. Resource and
+notification methods are listed above as implemented surface area; this
+test file does not exercise them. Run the in-process checks with:
+
+```bash
+python -m pytest tests/test_mcp_baseline.py -v
+```
+
+## Related repo-specific skills
+
+Two agent skills tailored to this repo live under `.github/skills/`:
+
+- `mcp-protocol-debugging` — how to exercise and debug the `mcp_server/main.py`
+  JSON-RPC server directly (capability negotiation, tool calls, error cases).
+- `quantum-connector-testing` — how to safely test `dwave_quantum_connector.py`
+  without requiring a live D-Wave QPU token, consistent with this repo's
+  "no mocks in production, real APIs only" convention (see
+  `tests/test_mcp_compliance.py`).