Add HCR v2 docs, integrations; repo cleanup

Add comprehensive HCR v2 documentation and developer guidance (CLAUDE.md, HCR-Northstar-v2.md) and update local Claude settings. Introduce hcr.product.integrations and hcr.product.security packages and modify integration tools (file_tools, output_synthesizer, session_tools). Apply changes to engine layer (cso_store.py, verifier.py), update README and mcp_server_wrapper, and adjust tests (tests/test_mcp_init.py). Remove legacy product/ package files (large deletion of old product modules) as part of the refactor and clean up project configuration and scripts.

Author: CodedRichy

.claude/settings.local.json

@@ -59,7 +59,39 @@
       "Bash(python3 -c \"from hcr.product.cli import main; print\\('✓ hcr.product subpackage imports'\\)\")",
       "PowerShell(Head *)",
       "PowerShell(python -m hcr.product.cli.main --help 2>&1)",
-      "PowerShell(python -m hcr.product.integrations.mcp_server_stdio --help 2>&1)"
+      "PowerShell(python -m hcr.product.integrations.mcp_server_stdio --help 2>&1)",
+      "Bash(sed -i 's|from src\\\\.|from hcr.engine.|g' README.md)",
+      "Bash(sed -i 's|from product\\\\.|from hcr.product.|g' README.md)",
+      "Bash(sed -i 's|`src/|`hcr/engine/|g' README.md)",
+      "Bash(sed -i 's|`product/|`hcr/product/|g' README.md)",
+      "Bash(sed -i 's|from src\\\\.|from hcr.engine.|g' HybridCognitiveRuntime-Northstar.md)",
+      "Bash(sed -i 's|from product\\\\.|from hcr.product.|g' HybridCognitiveRuntime-Northstar.md)",
+      "Bash(sed -i 's|`src/|`hcr/engine/|g' HybridCognitiveRuntime-Northstar.md)",
+      "Bash(sed -i 's|`product/|`hcr/product/|g' HybridCognitiveRuntime-Northstar.md)",
+      "Bash(sed -i 's|from src\\\\.|from hcr.engine.|g' hcr/product/PRODUCT_SPEC.md)",
+      "Bash(pip show *)",
+      "PowerShell(Get-Content *)",
+      "PowerShell(cd \"C:\\\\Users\\\\rishi\\\\Documents\\\\GitHub\\\\HybridCognitiveRuntime\"; $env:PYTHONIOENCODING=\"utf-8\"; python -m hcr.product.integrations.mcp_server_stdio --help 2>&1 | Select-Object -First 5)",
+      "PowerShell(cd \"C:\\\\Users\\\\rishi\\\\Documents\\\\GitHub\\\\HybridCognitiveRuntime\"; $env:PYTHONIOENCODING=\"utf-8\"; python test_tools_smoke.py 2>&1 | Where-Object { $_ -notmatch 'RequestsDependencyWarning|requests\\\\.__init__|chardet|charset|RuntimeWarning|coroutine|warnings.warn' })",
+      "PowerShell(cd \"C:\\\\Users\\\\rishi\\\\Documents\\\\GitHub\\\\HybridCognitiveRuntime\"; $env:PYTHONIOENCODING=\"utf-8\"; python test_tools_smoke.py 2>&1 | Where-Object { $_ -notmatch 'RequestsDependency|requests\\\\.__init__|chardet|charset|RuntimeWarning|coroutine|warnings.warn' })",
+      "Bash(cd \"C:\\\\Users\\\\rishi\\\\Documents\\\\GitHub\\\\HybridCognitiveRuntime\")",
+      "Bash(git rev-parse *)",
+      "Bash(echo GIT_DIR=__TRACKED_VAR__)",
+      "Bash(echo GIT_COMMON=__TRACKED_VAR__)",
+      "Bash(git branch *)",
+      "Bash(Get-ChildItem -Path \"C:\\\\Users\\\\rishi\\\\Documents\\\\GitHub\\\\HybridCognitiveRuntime\" -Force)",
+      "Bash(Select-Object -First 20)",
+      "Bash(python3)",
+      "Bash(python3 -m pytest tests/test_cso_tools.py -v --tb=short)",
+      "Bash(Get-ChildItem *)",
+      "Bash(Select-Object FullName)",
+      "Bash(git *)",
+      "Bash(dir C:\\\\Users\\\\rishi\\\\Documents\\\\GitHub\\\\HybridCognitiveRuntime\\\\hcr\\\\product\\\\storage\\\\ *)",
+      "WebSearch",
+      "Bash(grep -n \"\\\\\\\\bos\\\\\\\\.\" hcr/product/integrations/tools/decision_tools.py)",
+      "Bash(python3 -c \"import sqlite3; help\\(sqlite3.Connection.__enter__\\)\")",
+      "Bash(ls *.md *.toml *.cfg *.ini)",
+      "Bash(ls .cursor/ .github/)"
     ]
   },
   "enableAllProjectMcpServers": true,

CLAUDE.md

@@ -0,0 +1,88 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+# Run all tests
+python -m pytest tests/ -q
+
+# Run a single test file
+python -m pytest tests/test_cso_store.py -v
+
+# Run a single test by name
+python -m pytest tests/test_cso_store.py::test_write_and_query -v
+
+# Start MCP server (stdio transport, used by Cursor/Claude/Windsurf)
+python -m hcr.product.integrations.mcp_server_stdio
+
+# CLI
+hcr init              # initialize .hcr/ in current project
+hcr status            # show cognitive state summary
+hcr resume            # show resume context
+```
+
+## Architecture
+
+HCR is a persistent developer memory layer exposed as an MCP server. The key insight: AI tools are stateless, so HCR provides the stateful substrate they lack.
+
+### Storage: CSOs (Cognitive State Objects)
+
+`hcr/engine/cso/` is the core data layer. A `CSO` (`cso_model.py`) is a typed, causally-linked record — types include `DECISION`, `OBSERVATION`, `CONSTRAINT`, `RISK`, `TASK`, `OUTCOME`, `CLAIM`, `INTENT`, `ROLLBACK`, `TRIGGER`. Each CSO has explicit `causal_in`/`causal_out` edge lists forming a directed causal graph. `CSOStore` (`cso_store.py`) persists them in SQLite + WAL at `.hcr/cso.db`. Indexes on `type`, `created_at`, and `scope`.
+
+### Memory Fabric: `hcr/engine/memory/`
+
+The Cognitive State Fabric (CSF) — the intelligence layer over raw CSO storage:
+
+- **`centrality.py`** — `CausalCentralityScorer`: BFS transitive reachability on causal edges. CSOs that caused the most downstream effects score highest (0–1).
+- **`projection.py`** — `CognitiveProjection`: replaces naive `facts[-10:]` with centrality-ranked, decay-filtered live state. Called on every `hcr_get_state` and `hcr_preflight`.
+- **`prefetch.py`** — `ProjectionPrefetcher`: background thread triggered on file edit events. Caches `CognitiveProjection` so the next tool call hits cache (zero compute latency).
+- **`embedding_store.py`** — `EmbeddingStore`: sqlite-vec ANN store at `.hcr/embeddings.db`. Embeds qualifying CSO tiers (`commit/task/decision/constraint/risk/edited`) via Ollama `nomic-embed-text`, falling back to `sentence-transformers`. Only CSOs in those tiers are embedded.
+- **`implicit_graph.py`** — `generate_soft_links`: semantic k-NN to auto-detect soft causal edges (similarity > 0.82 threshold).
+- **`episode_store.py`** — `BOCPDSegmenter`: Bayesian Online Changepoint Detection for segmenting event streams into work episodes.
+- **`fusion.py`** — `reciprocal_rank_fusion` (RRF, accepts optional learned `weights` tuple) and `mmr_select` (Maximum Marginal Relevance): fuse semantic + causal ranked lists; select diverse results for fixed token budget. RRF is called by `cso_impact.query_cso_impact` when an `embedding_store` is passed.
+- **`implicit_graph.py`** — `generate_soft_links`: called in `_handle_file_edit` after embedding; auto-detects semantic soft causal edges (similarity > 0.82) and back-writes them to the CSO.
+- **`prospective.py`** — `get_triggered_csos`: returns `TRIGGER` CSOs matching the active file pattern; injected at rank-0 by `CognitiveProjection`.
+- **`feedback.py`** — `FeedbackStore`: SQLite store recording preflight retrievals and session outcomes. After `TRAINING_THRESHOLD=50` labelled samples, trains learned RRF weights via least-squares. `HCREngine._feedback_store` owns the instance.
+
+### Engine: `hcr/engine/engine_api.py`
+
+`HCREngine` is the central object. Key responsibilities:
+- Owns `_cso_store`, `_prefetcher`, `_embedding_store`, `_feedback_store`, `_episode_segmenter`
+- `_handle_file_edit()` is the hot path: writes OBSERVATION CSO → symbolic verifier → prefetcher → embeds CSO → generates soft-links (back-written to CSO causal_in)
+- Parallel legacy state in `CognitiveState` (symbolic facts, causal graph) is kept for backwards compatibility but CSOs are the v2.0 source of truth
+
+### Symbolic Reasoning: `hcr/engine/symbolic/`
+
+`SymbolicVerifier` (`verifier.py`) evaluates `DEFAULT_RULES` against a newly written CSO and emits RISK CSOs when rules fire. Rules live in `rules.py`. Rule evaluation failures are logged at DEBUG level (not silently swallowed).
+
+### Semantic Decay: `hcr/product/storage/semantic_decay.py`
+
+Tier-based fact retention. Each fact prefix (`commit:`, `task:`, `edited:`, `error:`, `cmd:`, `mcp_tool:`, `pattern:`, `observation:`) has a half-life (7 days → 15 min). `CognitiveProjection` uses this to compute effective half-life adjusted by centrality: `effective_hl = base / max(1 - centrality*0.8, 0.2)` — high-centrality CSOs decay slower.
+
+### MCP Server: `hcr/product/integrations/`
+
+`HCRMCPResponder` in `mcp_server.py` dispatches all MCP tool calls to modular `BaseMCPTool` subclasses in `tools/`. Each tool class is ~one file. Key tools:
+- `hcr_get_state` / `hcr_preflight` — main context-handoff tools for agents
+- `hcr_preflight` / `hcr_postflight` — agent lifecycle: preflight records retrieval for learned fusion; postflight records outcome signal
+- `hcr_record_file_edit`, `hcr_remember`, `hcr_fail`, `hcr_resolve` — write-path tools
+- `hcr_analyze_impact` — causal BFS + RRF semantic fusion (`cso_impact.py` + `embedding_store`)
+
+All imports into `mcp_server.py` must be at module level (not inside functions/conditionals).
+
+### Project State on Disk
+
+```
+.hcr/
+  cso.db          # SQLite CSO store (WAL mode, indexes: type/created_at/scope)
+  embeddings.db   # sqlite-vec embedding store (WAL, synchronous=NORMAL)
+  feedback.db     # learned fusion weights (FeedbackStore)
+  agents.db       # AgentRegistry
+  state.json      # legacy CognitiveState (required for init check)
+  decisions/      # legacy JSONL decision log (migrated to CSOs on init)
+```
+
+## Tests
+
+`tests/conftest.py` has `collect_ignore` for non-pytest scripts. Tests are fully synchronous where possible; async tests use `pytest-asyncio` with `asyncio_mode = "auto"`. Mock `_get_embedding` on `EmbeddingStore` to avoid needing Ollama running. The full suite runs in ~57 seconds (179 tests, 4 skipped — skipped tests require a live LLM endpoint).