sachinshelke · sachinshelke · Jun 1, 2026 · May 28, 2026 · May 28, 2026 · May 28, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -30,6 +30,10 @@
 - **D00001D** 3.0.0 BUILD COMPLETE (this session). All enhancements are built, tested, committed to local main, and the full release …
 - **D00001E** fix: Python 3.10 CI failure — agents_md_generator._project_name() and cli_init used bare `import tomllib` (stdlib 3.11+…
 - **D00001F** RESOLVED the known release-smoke tooling bug: replaced `head -1` with `sed -n '1p'` in Makefile release-smoke + wheel-n…  ·  `Makefile`  ·  _makefile, release, tooling_
+- **D00001G** v3.0.x storage prereq IMPLEMENTATION COMPLETE on branch release/3.0.1 (commits 6253940 + c1352d7). Patches 1+2+3 done: …  ·  _memory, prereq, storage, v3.0.1_
+- **D00001H** M1 Phase A origin tagging IMPLEMENTATION COMPLETE on release/3.0.1 (commits 618710a storage + ff06b3d ide_inject). orig…  ·  _consensus, m1, memory, origin, v3.1.0_
+
+_+670 more decision(s) — full log in `.codevira/decisions.jsonl`._
 
 
 For the full decision log + outcomes + reverts, see `.codevira/decisions.jsonl` or run `codevira list-decisions`.

diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -27,7 +27,7 @@ Call these MCP tools at the moments the description matches your action — they
 
 - For commits that fix a bug, prefer commit messages starting with `fix:`, `bug:`, `hotfix:`, or `fixes #N`. Codevira scans these into a fix-history database used by the Anti-Regression hero to block silent re-introduction of fixed bugs.
 
-### Before you finish a meaningful unit of work — NON-NEGOTIABLE
+### Before you finish a meaningful unit of work — STRONG RECOMMENDATION
 
 Codevira's promise is "the project remembers what you did." That promise breaks if you don't write to it. Before you respond to the user with the final result of a meaningful change, **call ONE of these**:
 
@@ -36,7 +36,9 @@ Codevira's promise is "the project remembers what you did." That promise breaks
 - **`complete_changeset(changeset_id, decisions=[...])`** — if you closed a multi-file fix
 - **`write_session_log(...)`** — at minimum, at the end of any session that produced commits or non-trivial output
 
-A session that ships code WITHOUT a codevira write call leaves the project's memory stale for the next AI. That's the most common way the wedge breaks. Treat it as part of the definition-of-done, not optional.
+A session that ships code WITHOUT a codevira write call leaves the project's memory stale for the next AI. That's the most common way the wedge breaks. Treat it as part of the definition-of-done.
+
+**Engine enforcement (v3.2.0+):** The `session_log_enforcer` policy fires on `Stop` events. If the session shipped commits AND no `write_session_log` was called between `SESSION_START` and now, it emits a `warn` via Claude Code's `systemMessage` channel. Default mode is `warn` (non-blocking nudge); set `CODEVIRA_SESSION_LOG_ENFORCER_MODE=block` to force the AI to retry, or `off` to disable. v3.2.1 plans to default to `block` once warn-mode instrumentation confirms low noise. Logging is still your judgment call for what counts as "meaningful" — if you only answered a question with no commits, the policy stays silent.
 
 ### When you see "Roadmap drift detected" in your SessionStart context
 
@@ -51,6 +53,76 @@ That warning fires when codevira's claimed phase hasn't been updated for several
 
 - **`search_decisions(query="X")`** is the answer. Don't guess — surface the actual decision log.
 
+## Memory subsystems (v3.1.0)
+
+v3.1.0 added five memory subsystems on top of the existing decision log. Each has a specific moment to call it; together they cover the gap between "episodic" (decisions) and "the agent's day-to-day state."
+
+### Working memory — intra-session scratchpad
+
+`.codevira-cache/working.jsonl` (per-machine, ephemeral, gitignored). Capacity-bounded, decay-scored.
+
+- **`working_add(content, kind="observation"|"goal", importance=5, links=[])`** — record an observation (something you saw) or a goal (something you're trying). `Edit`/`Write`/`Bash` calls auto-populate this via the post_tool_use hook; explicit calls add narrative + intent the auto path can't see.
+- **`working_get(top_k=10, kind=?)`** — top-K live entries by decay score (importance × exp(-Δt/τ=6h) + 0.5 × access_count). Tombstoned entries excluded.
+- **`working_promote(entry_id, to="decision"|"skill"|"playbook", ...)`** — move an observation/goal into LTM. Calls `check_conflict` first; tombstones the source on success.
+- **`get_working_context(top_k=5)`** — compact markdown for ReAct-loop injection.
+
+Working memory persists into `get_session_context` (top-3 panel) so the next call sees your recent scratchpad.
+
+CLI escape hatch: `codevira working commit <session_id>` archives a session's live entries to `.codevira/working_archived/<session_id>.jsonl` (canonical, team-shareable).
+
+### Skill library — procedural memory
+
+`.codevira/skills.jsonl` (canonical, team-shareable). FTS5-backed retrieval with composite ranking (BM25 + tag-Jaccard + recency).
+
+- **`record_skill(name, procedure, summary, triggers, do_not_revert, force)`** — author a reusable procedure ("how we rebase in this repo", "the project's commit-message convention"). Conflict-checked against existing skills.
+- **`get_skill(query, top_k=5, file_path=?)`** — composite-ranked search. Returns `score_breakdown` so you can see WHY each skill surfaced.
+- **`apply_skill_outcome(skill_id, success)`** — manual reinforcement. The *canonical* signal comes from git via `outcomes_writer` fan-out (M5) — this tool is the override.
+- **`list_skills(status="active"|"archived"|"superseded"|"all", source, tags)`** — daily-driver `active` filter by default.
+- **`supersede_skill(old_id, name, procedure, ...)`** — version a skill; amendment chain preserves audit.
+- **`promote_skill_to_playbook(skill_id, task_type, name?, force)`** — write a skill's procedure as a playbook markdown so `get_playbook(task_type)` finds it.
+
+Auto-archive at 5 consecutive failures OR `unused_days ≥ 90` (configurable). Skills with `do_not_revert=true` are exempt.
+
+CLI: `codevira induce-skills [--apply] [--yes]` — cluster productive sessions (≥80% kept, tag-Jaccard ≥ 0.5) and propose induced skills. Without `--apply`: writes to `.codevira/induction_proposals.jsonl` for review.
+
+### Spatial memory — code-as-space
+
+Activity heatmap (`.codevira-cache/activity.jsonl`, per-machine) + folder-tree neighborhoods + affordances.
+
+- **`spatial_nearby(file_path, k=5)`** — files topologically near a file (BFS ≤ 2 hops over import/call edges + same-neighborhood), ranked by recent activity. Use when navigating unfamiliar code.
+- **`spatial_heat(top_k=20, since_days=?)`** — where attention has concentrated. Use for "what changed this week?".
+- **`spatial_neighborhood(file_path)`** — the folder-tree-derived (or yaml-overridden) neighborhood + members.
+- **`spatial_affordances(file_path)`** — what task_types apply here. E.g., a file under `mcp_server/tools/` typically affords `{add_tool, write_test}`. Combine with `get_playbook(task_type)` for relevant rules.
+
+Override files: `.codevira/neighborhoods.yaml` (re-label folder mapping); `.codevira/affordances.yaml` (project-specific affordances on top of `mcp_server/data/affordances.yaml`).
+
+### Consensus — cross-IDE awareness
+
+Tracks which IDE wrote each decision so contradictions across IDEs surface.
+
+- **`consensus_check()`** — run a scan (read-only) for cross-IDE conflicts since this IDE's last checkpoint. Materializes matches to `.codevira/pending_conflicts.jsonl`.
+- **`consensus_status(top_k=3)`** — count + top-K pending conflicts (`get_session_context` also surfaces a panel).
+- **`origin_of(decision_id)`** — provenance lookup (always available — provenance is M1).
+
+Phase C (opt-in handshake, default off) — gated by `memory.consensus.handshake_enabled` in `.codevira/config.yaml`:
+- **`consensus_propose_supersession(target_decision_id, new_decision, reason)`** — open a proposal against a foreign IDE's `do_not_revert` decision. Same-IDE fast-path bypasses the handshake.
+- **`consensus_resolve(proposal_id, action="approved"|"rejected"|"withdrawn", comment?)`** — record the response.
+- 14-day timeout default; expired proposals can be force-finalized via `expired_unilateral=True` (with audit row).
+
+CLI: `codevira consensus check`.
+
+### Reflections — episodic abstraction
+
+`.codevira/reflections.jsonl` (committed). LLM-generated abstractions over recent decisions + sessions.
+
+- **`reflect(period_days=7, dry_run=True)`** — build the source context + render the prompt. v3.1.0 returns `sampling_supported: False` + `rendered_prompt` (the MCP sampling/createMessage RPC ships in v3.2). Use the CLI to commit an LLM response.
+- **`get_reflections(top_k=5)`** — most recent reflections.
+- **`list_reflections(since?, tags?, limit=50)`** — filtered list.
+
+CLI: `codevira reflect [--period 7d] [--from-file PATH] [--apply] [--yes]`.
+
+Sanitization pass strips api keys / Bearer tokens / passwords / AWS AKIA / long hex / long base64 from the source context before the LLM sees it.
+
 ## Tool budget discipline
 
 Codevira is **token-efficient by design**:

diff --git a/Makefile b/Makefile
@@ -69,7 +69,7 @@ test-unit:
 	$(PYTHON) -m pytest tests/ -q --ignore=tests/e2e --ignore=tests/integration
 
 test-e2e:
-	$(PYTHON) -m pytest tests/e2e/test_first_contact.py tests/e2e/test_product_invariants.py -v
+	$(PYTHON) -m pytest tests/e2e/test_first_contact.py tests/e2e/test_product_invariants.py tests/e2e/test_cross_tool_universality.py -v
 
 # v2.1.2 hardening — integration suite (slower; runs in gauntlet):
 #   MCP round-trip, help-text linter, sandboxed-parent. Skipped from
@@ -252,7 +252,7 @@ release-verify-version:
 	@echo "  ✓ In sync with origin (or no upstream tracking)"
 	@# 4. Cross-check version in __init__.py if it declares __version__.
 	@if [ -f mcp_server/__init__.py ]; then \
-		INIT_VER=$$(grep -E "^__version__" mcp_server/__init__.py 2>/dev/null | sed -E 's/.*=\s*"([^"]+)".*/\1/'); \
+		INIT_VER=$$(grep -E "^__version__" mcp_server/__init__.py 2>/dev/null | sed -E 's/.*= *"([^"]+)".*/\1/'); \
 		if [ -n "$$INIT_VER" ] && [ "$$INIT_VER" != "$(VERSION)" ]; then \
 			echo "  ✗ Version drift: pyproject.toml=$(VERSION) but mcp_server/__init__.py=$$INIT_VER"; \
 			exit 1; \
@@ -268,6 +268,18 @@ release-verify-version:
 			echo "    Promote the [Unreleased] section to [$(VERSION)] before releasing."; \
 			exit 1; \
 		fi; \
+		\
+		NEWER=$$(find mcp_server indexer -type f \( -name "*.py" -o -name "*.html" \) -newer CHANGELOG.md 2>/dev/null | wc -l | tr -d ' '); \
+		if [ "$$NEWER" -gt "0" ]; then \
+			echo "  ✗ CHANGELOG.md is OLDER than $$NEWER source file(s) under mcp_server/ + indexer/."; \
+			echo "    The current $(VERSION) entry is probably stale relative to the wheel."; \
+			echo "    Either: (a) update the entry to cover the new commits, OR"; \
+			echo "    (b) bump the patch version + add a new entry."; \
+			echo "    First offenders:"; \
+			find mcp_server indexer -type f \( -name "*.py" -o -name "*.html" \) -newer CHANGELOG.md 2>/dev/null | head -5 | sed 's/^/      /'; \
+			exit 1; \
+		fi; \
+		echo "  ✓ CHANGELOG.md is fresh (newer than every tracked source file)"; \
 	fi
 	@# 6. Tag check: if tag exists, must point at HEAD.
 	@if git rev-parse "v$(VERSION)" >/dev/null 2>&1; then \

diff --git a/README.md b/README.md
@@ -92,6 +92,28 @@ every AI tool, on every project, on your local machine.**
 
 ---
 
+## What's new in v3.1.1 — hardening + interrogable memory
+
+> 3.1.1 supersedes the briefly-published 3.1.0 (which shipped
+> without this README/CHANGELOG entry). Same code shape; this
+> release is the documented one. Brings five memory subsystems
+> (M1–M9 from 3.1.0) plus the v3.1.1 hardening + viewer overhaul.
+
+| Area | What you get |
+|---|---|
+| **Five memory subsystems** | Origin tagging (M1), working memory (M2), skill library with FTS5 ranking (M3), spatial memory + activity heatmap (M4), skill induction wired to outcomes (M5), cross-IDE consensus check + handshake (M6/M7), reflections (M8). 22 new MCP tools. |
+| **Secret scrubbing everywhere** | Decisions, sessions, working memory, skills, reflections — every store scrubs api-key / Bearer / password / AWS AKIA / long hex / long base64 at the write boundary. One shared `mcp_server/storage/sanitize.py`. |
+| **Counter-decision discipline** | `record_decision` now accepts `alternatives_considered: list[str]` and `would_re_examine_if: str` — losing options + invalidation trigger surface in the viewer's rich-detail panel. Optional + back-compat. |
+| **Interrogable graph viewer** | `codevira graph` is no longer a passive force-layout. Free-text search → top-K ranked panel with score + outcome badge. Q&A intent detection ("what did we decide about X", "what got reverted", "what's protected"). Outcome lens (kept/modified/reverted). Lineage trace mode for supersession chains. |
+| **Auto outcome classification** | `codevira sync` now runs `observe-git` as a best-effort tail step — outcomes flow into the viewer's outcome lens automatically. |
+| **G3 real-IDE smoke** | The last permanently-skipped gauntlet gate now ships as a real check. Verifies codevira is registered in each detected IDE config + MCP `tools/list` round-trips in <1s. |
+| **AGENTS.md no more churn** | `regenerate()` is now idempotent — no rewrite when content unchanged, no perpetual uncommitted-drift loop. |
+| **4 silent bugs fixed** | `commit_session("../escape")` rejected; `triggers.tags="git"` rejected; `list_all(limit=0)` returns `[]`; spatial BFS catches query-time sqlite errors. |
+
+Full v3.1.1 release notes: [CHANGELOG.md](CHANGELOG.md#311--2026-05-30--hardening-viewer-overhaul-g3-sync-observe-git).
+
+---
+
 ## What's new in v3.0.0 — audited, lean, opinionated
 
 > Major version. v3.0.0 is the biggest API contraction since v2.0