codevira 3.0.0__tar.gz → 3.1.0__tar.gz

{codevira-3.0.0 → codevira-3.1.0}/CHANGELOG.md

@@ -9,6 +9,242 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ---
 
+## [3.1.0] — Five memory subsystems + cross-IDE consensus
+
+v3.1.0 adds five memory subsystems on top of the v3.0.x decision
+log, plus a cross-IDE consensus layer. Every addition is additive
+to the existing schemas; v3.0.x records continue to read without
+migration. The MCP surface gains 22 new tools across the new
+subsystems.
+
+### v3.0.x storage prereq (ships first)
+
+- **`refactor(jsonl_store)`** — extract `read_merged` / `compact` /
+  `read_recent` from `decisions_store._read_merged` /
+  `sessions_store.read_recent`. The five new memory subsystems
+  share this amendment-overlay primitive instead of duplicating
+  it. Tests cover amendment-chain-three-deep recursion semantics.
+  Zero behavior change for existing callers.
+
+- **`fix(session_id)`** — `decisions_store.record` and
+  `sessions_store.write` now default `session_id` to
+  `f"ad-hoc-{secrets.token_hex(3)}"` (e.g., `ad-hoc-a1b2c3`)
+  instead of the literal string `"ad-hoc"`. Every concurrent IDE
+  that didn't pass a slug previously collided into one bucket;
+  the unique-per-call default fixes cross-IDE attribution.
+
+### M1 — Origin tagging (provenance)
+
+Every decision and session write now carries an `origin` block:
+
+```json
+"origin": {"ide": "claude_code", "agent_model": "...",
+           "host_hash": "<12 hex chars>", "ts": "..."}
+```
+
+- `host_hash` = `sha1(uuid.getnode() bytes + username)[:12]` —
+  stable per machine (MAC-based, `platform.node()` fallback),
+  privacy-preserving (no plaintext hostname/username leaks).
+- `CODEVIRA_IDE` env var read at MCP server startup; default
+  `"unknown"`. `ide_inject.py` now writes `CODEVIRA_IDE=<ide_key>`
+  into the MCP config block for all 10 supported IDE configs
+  (Claude Code, Claude Desktop, Cursor, Windsurf, Antigravity —
+  per-project + global).
+- `check_conflict` response includes the candidate's `origin` so
+  agents can see "this conflicts with a decision Cursor wrote 3
+  days ago" instead of just an opaque decision_id.
+- Reads tolerate `origin` absent (legacy v3.0.x records treated
+  as `ide="unknown"`).
+
+### M2 — Working memory
+
+Bounded, decay-scored intra-session scratchpad.
+
+- `.codevira-cache/working.jsonl` (per-machine, ephemeral,
+  gitignored). Auto-populated by `post_tool_use` hook on Edit /
+  Write / MultiEdit / NotebookEdit / update_node (importance 4),
+  Bash (importance 3), tool errors (importance bumped to 7).
+- 4 MCP tools: `working_add`, `working_get`, `working_promote`
+  (to=decision|skill|playbook with check_conflict gate), and
+  `get_working_context` (compact markdown for ReAct loops).
+- Decay score: `importance × exp(-Δt_hours / 6) + 0.5 ×
+  access_count`. Top-3 surfaces in `get_session_context`.
+- Eviction = amendment tombstone; periodic compaction during
+  `codevira sync`.
+- CLI: `codevira working commit <session_id>` archives a
+  session's live entries to
+  `.codevira/working_archived/<session_id>.jsonl`.
+
+### M3 — Skill library (procedural memory)
+
+`.codevira/skills.jsonl` (canonical, team-shareable). FTS5
+retrieval + composite ranking.
+
+- `skill_fts` virtual table in the existing
+  `.codevira-cache/fts5.sqlite`. Independent staleness key
+  (`skill_source_mtime`) so the existing decisions tracking is
+  unaffected.
+- Composite ranking:
+  `score = 0.5 × BM25_norm + 0.3 × tag_jaccard + 0.2 ×
+  recency_decay(τ=30d)`. Never-used skills score 0 recency —
+  reinforcement, not existence, drives the recency signal.
+- 6 MCP tools: `record_skill`, `get_skill`, `apply_skill_outcome`,
+  `list_skills`, `supersede_skill`,
+  `promote_skill_to_playbook` (writes
+  `.codevira/playbooks/<task_type>/<slug>.md`).
+- Lifecycle states: `active` (default), `archived` (5 consec
+  failures OR `unused_days ≥ 90` — configurable; do_not_revert
+  exempt), `superseded` (final).
+- M5 wires git-derived outcomes_writer to skill reinforcement (see
+  below).
+
+### M4 — Spatial memory
+
+Activity heatmap + folder-tree neighborhoods + affordances.
+
+- `.codevira-cache/activity.jsonl` (per-machine). Auto-emitted on
+  Edit/Write via `memory_fanout` + on `decisions_store.record`
+  when `file_path` is set. Schema: `{id, ts, node_id, kind:
+  edit|decision_ref, session_id, origin, _schema_v: 1}`.
+- 4 MCP tools: `spatial_nearby` (BFS ≤ 2 hops over the indexer
+  graph + same-neighborhood union, ranked by `(1/(1+bfs_dist)) ×
+  log(1+visit_count_30d)`), `spatial_heat`,
+  `spatial_neighborhood`, `spatial_affordances`.
+- Folder-tree neighborhoods (top-2 dir components, e.g.,
+  `mcp_server/storage`). Project-overridable via
+  `.codevira/neighborhoods.yaml`.
+- Bundled `mcp_server/data/affordances.yaml` mapping file globs to
+  task_type affordances (e.g., `mcp_server/tools/*.py` →
+  `{add_tool, write_test}`). Project override:
+  `.codevira/affordances.yaml`; bundled + project union per match.
+
+### M5 — Skill induction wired to outcomes_writer
+
+Closes the reinforcement loop. Two pieces:
+
+- **Sessions schema additions**: `task_type` (`feature` | `bug` |
+  `refactor` | `release` | `docs` | `other`) and `skill_ids: []`
+  (skills used during the session). Additive; legacy sessions
+  tolerate absence.
+- **outcomes_writer fan-out**: when `observe_all()` classifies a
+  decision as `kept` or `reverted`, each skill referenced via
+  `skill_ids` on the same session gets `mark_used(success=…)`.
+  Pre-builds a `{session_id → set[skill_id]}` index so the
+  per-decision fan-out is O(1). Best-effort: skill errors log and
+  drop without blocking the decision-outcome write.
+- **CLI**: `codevira induce-skills [--apply] [--yes]` —
+  deterministic induction (no LLM in v3.1.0). Pipeline: filter
+  sessions with ≥80% kept; group by task_type; cluster by
+  tag-Jaccard ≥ 0.5; keep clusters ≥3 sessions; render candidate
+  skill with `name = "<task_type>: <top-3 tags>"`,
+  `procedure = bullet-summary of session.task +
+  decision.decision` (capped 30 lines).
+
+### M6 — Consensus Phase B (cross-IDE conflict check, read-only)
+
+- Per-IDE checkpoint files
+  `.codevira/checkpoints/<ide_key>.json` keyed on
+  `last_seen_decision_id` — zero-padded base-36 D-ids preserve
+  monotonic ordering without clock drift.
+- `consensus_store.scan_and_materialize()`: walks decisions with
+  `id > checkpoint`, partitions by `origin.ide` into
+  `current_corpus` + `foreign`, runs the reused `check_conflict`
+  tokenize/Jaccard/overlap math on every pair, records matches as
+  PC-prefixed rows in `.codevira/pending_conflicts.jsonl`.
+- 2 MCP tools: `consensus_check`, `consensus_status`.
+  `get_session_context` surfaces a top-3 panel sorted by
+  `(do_not_revert × recency)`.
+- CLI: `codevira consensus check`. Read-only — no amendment rows
+  written on decisions.
+
+### M7 — Consensus Phase C handshake (opt-in, default off)
+
+Opt-in belief-revision protocol gated behind
+`memory.consensus.handshake_enabled` in `.codevira/config.yaml`.
+
+- New `config.py` helper for dotted-key lookups against
+  `.codevira/config.yaml`.
+- `propose_supersession` (cross-IDE) appends a
+  `proposed_supersession` row with `expires_at = ts +
+  handshake_timeout_days` (default 14, configurable). Same-IDE
+  fast-path returns `{fast_path: True}` so the caller routes to
+  `decisions_store.supersede` directly.
+- `resolve_proposal(action: approved|rejected|withdrawn)`
+  appends a resolution row carrying `resolver_origin`.
+- `finalize_proposal(expired_unilateral=False)` — approved
+  proposals turn into a real `decisions_store.supersede` call.
+  Expired proposals require `expired_unilateral=True` (deadlock
+  safety); the audit row records the force-finalize.
+- 3 MCP tools: `consensus_propose_supersession`,
+  `consensus_resolve`, `origin_of` (provenance lookup; always
+  available).
+- Row kind taxonomy in pending_conflicts.jsonl: `conflict` (M6),
+  `proposed_supersession` (M7), `resolution` (M7).
+
+### M8 — Reflections (durable LLM abstractions)
+
+Generative-Agents-style abstractions over recent decisions +
+sessions.
+
+- `.codevira/reflections.jsonl` (canonical, committed) +
+  `.codevira/reflection_proposals.jsonl` (review staging).
+- `scrub_sensitive` strips api keys, Bearer tokens, passwords,
+  AWS-style AKIA, long hex/base64 from source records before the
+  LLM sees them.
+- `build_source_context` aggregates sessions + decisions in the
+  period window with plan caps (≤30 sessions, ≤100 decisions,
+  ≤6 KB envelope).
+- Bundled prompt template at
+  `mcp_server/data/prompts/reflection_v1.md`.
+- **MCP sampling integration scope**: v3.1.0 ships the storage +
+  sanitization + prompt rendering + the API surface. The
+  `sampling/createMessage` RPC that asks the host LLM for the
+  abstraction is the **v3.2** deliverable. v3.1.0 `reflect()`
+  returns `{sampling_supported: False, rendered_prompt,
+  source_context, deferred_to: "v3.2"}`; the CLI accepts an LLM
+  response via `--from-file`.
+- 3 MCP tools: `reflect`, `get_reflections`, `list_reflections`.
+- CLI: `codevira reflect [--period 7d] [--from-file PATH]
+  [--apply] [--yes]`. Render mode prints the prompt;
+  `--from-file` parses the LLM YAML response and writes a
+  proposal; `--apply --yes` commits to `reflections.jsonl`.
+
+### Schema versioning convention
+
+All NEW JSONL stores (`working`, `skills`, `activity`,
+`pending_conflicts`, `reflections`) carry `_schema_v: 1` on each
+record. Readers tolerate absence (treats as v1). Existing
+`decisions.jsonl` / `sessions.jsonl` are unchanged.
+
+### `get_session_context` panels
+
+Now carries five panels in addition to the existing roadmap /
+recent decisions:
+  - `working` — top-3 live entries (M2).
+  - `consensus` — top-3 pending conflicts (M6) sorted by
+    `(do_not_revert × recency)`.
+The plan reserves panels for working, skills, spatial,
+reflections in future ticks if value justifies the token cost.
+
+### Tests
+
+~450+ new tests across `tests/storage/`, `tests/test_tools_*`,
+`tests/test_cli_*`, `tests/test_reflections.py`,
+`tests/test_consensus_handshake.py`, etc. The full v3.1.0 suite
+runs in <20s; zero regressions from the v3.0.x baseline.
+
+### Locked decisions honored
+
+The v3.0.0 locks remain intact:
+- D000001 (atomic writes through `mcp_server/storage/atomic.py`)
+- D000012 (WRITE-path forbidden-root validation via
+  `ensure_dirs`)
+- The v2.2.0 "no embeddings; FTS5 + Jaccard only" decision —
+  M3's skill retrieval and M6's conflict check both use the
+  existing FTS5/Jaccard infrastructure; no new embedding deps.
+
+---
+
 ## [3.0.0] — 2026-05-27 — Lean, audited, opinionated
 
 ### Hardened (RC audit — rounds 2 + 3, pre-publish)

{codevira-3.0.0/codevira.egg-info → codevira-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: codevira
-Version: 3.0.0
+Version: 3.1.0
 Summary: Cross-IDE decision enforcement for AI coding agents. 1 MB per project, in your repo, no cloud, no vectors. Claude Code, Cursor, Windsurf, Antigravity, Codex all share the same in-repo memory; hooks block AI tool calls that violate prior decisions. MIT, local-first.
 Author-email: Sachin Shelke <sachin.worldnet@gmail.com>
 License: MIT

{codevira-3.0.0 → codevira-3.1.0/codevira.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: codevira
-Version: 3.0.0
+Version: 3.1.0
 Summary: Cross-IDE decision enforcement for AI coding agents. 1 MB per project, in your repo, no cloud, no vectors. Claude Code, Cursor, Windsurf, Antigravity, Codex all share the same in-repo memory; hooks block AI tool calls that violate prior decisions. MIT, local-first.
 Author-email: Sachin Shelke <sachin.worldnet@gmail.com>
 License: MIT

{codevira-3.0.0 → codevira-3.1.0}/codevira.egg-info/SOURCES.txt

@@ -90,14 +90,18 @@ mcp_server/_repair_init.py
 mcp_server/_safe_crash.py
 mcp_server/auto_init.py
 mcp_server/cli.py
+mcp_server/cli_consensus.py
 mcp_server/cli_export.py
 mcp_server/cli_graph.py
 mcp_server/cli_hooks_admin.py
+mcp_server/cli_induce.py
 mcp_server/cli_init.py
 mcp_server/cli_projects.py
+mcp_server/cli_reflect.py
 mcp_server/cli_replay.py
 mcp_server/cli_sync.py
 mcp_server/cli_uninstall.py
+mcp_server/cli_working.py
 mcp_server/crash_logger.py
 mcp_server/decision_replay.py
 mcp_server/detect.py
@@ -115,6 +119,7 @@ mcp_server/roadmap_drift.py
 mcp_server/server.py
 mcp_server/setup_wizard.py
 mcp_server/data/__init__.py
+mcp_server/data/affordances.yaml
 mcp_server/data/config.example.yaml
 mcp_server/data/agents/builder.md
 mcp_server/data/agents/developer.md
@@ -128,6 +133,7 @@ mcp_server/data/hooks/pre_tool_use.sh
 mcp_server/data/hooks/session_start.sh
 mcp_server/data/hooks/stop.sh
 mcp_server/data/hooks/user_prompt_submit.sh
+mcp_server/data/prompts/reflection_v1.md
 mcp_server/data/rules/coding-standards-generic.md
 mcp_server/data/rules/coding-standards-go.md
 mcp_server/data/rules/coding-standards-typescript.md
@@ -145,6 +151,7 @@ mcp_server/data/rules/testing-standards.md
 mcp_server/engine/__init__.py
 mcp_server/engine/demo_policy.py
 mcp_server/engine/events.py
+mcp_server/engine/memory_fanout.py
 mcp_server/engine/policy.py
 mcp_server/engine/runner.py
 mcp_server/engine/signals.py
@@ -160,27 +167,42 @@ mcp_server/engine/policies/token_budget.py
 mcp_server/engine/wiring/__init__.py
 mcp_server/engine/wiring/claude_code_hooks.py
 mcp_server/engine/wiring/mcp_dispatch.py
+mcp_server/graph/__init__.py
+mcp_server/graph/template.html
 mcp_server/storage/__init__.py
+mcp_server/storage/activity_store.py
 mcp_server/storage/agents_md_generator.py
 mcp_server/storage/atomic.py
+mcp_server/storage/config.py
+mcp_server/storage/consensus_store.py
 mcp_server/storage/decisions_store.py
 mcp_server/storage/digest.py
 mcp_server/storage/fts5_index.py
 mcp_server/storage/jsonl_store.py
 mcp_server/storage/manifest.py
+mcp_server/storage/origin.py
 mcp_server/storage/outcomes_writer.py
 mcp_server/storage/paths.py
+mcp_server/storage/reflections_store.py
+mcp_server/storage/sanitize.py
 mcp_server/storage/sessions_store.py
+mcp_server/storage/skills_store.py
 mcp_server/storage/token_estimator.py
+mcp_server/storage/working_store.py
 mcp_server/tools/__init__.py
 mcp_server/tools/changesets.py
 mcp_server/tools/check_conflict.py
 mcp_server/tools/code_reader.py
+mcp_server/tools/consensus.py
 mcp_server/tools/graph.py
 mcp_server/tools/learning.py
 mcp_server/tools/playbook.py
+mcp_server/tools/reflections.py
 mcp_server/tools/roadmap.py
 mcp_server/tools/search.py
+mcp_server/tools/skills.py
+mcp_server/tools/spatial.py
+mcp_server/tools/working.py
 rules/coding-standards.md
 rules/engineering-excellence.md
 rules/git-cicd-governance.md
@@ -196,11 +218,15 @@ tests/test_auto_init.py
 tests/test_call_edge_fk_safety.py
 tests/test_check_conflict.py
 tests/test_chunker.py
+tests/test_cli_consensus.py
 tests/test_cli_graph.py
+tests/test_cli_induce.py
 tests/test_cli_projects.py
 tests/test_cli_replay.py
 tests/test_cli_uninstall.py
 tests/test_cli_version.py
+tests/test_cli_working.py
+tests/test_consensus_handshake.py
 tests/test_crash_logger.py
 tests/test_dedupe_migration.py
 tests/test_detect.py
@@ -223,6 +249,7 @@ tests/test_outcome_tracker.py
 tests/test_paths.py
 tests/test_prompts.py
 tests/test_record_decision.py
+tests/test_reflections.py
 tests/test_repair_init.py
 tests/test_roadmap_drift.py
 tests/test_server.py
@@ -234,5 +261,8 @@ tests/test_tools_graph.py
 tests/test_tools_learning.py
 tests/test_tools_playbook.py
 tests/test_tools_roadmap.py
+tests/test_tools_skills.py
+tests/test_tools_spatial.py
+tests/test_tools_working.py
 tests/test_treesitter_parser.py
 tests/test_watcher_circuit.py

{codevira-3.0.0 → codevira-3.1.0}/mcp_server/__init__.py

@@ -14,4 +14,4 @@ internals — internal APIs may change between minor versions.
 from mcp_server.cli import main
 
 __all__ = ["main"]
-__version__ = "3.0.0"
+__version__ = "3.1.0"

{codevira-3.0.0 → codevira-3.1.0}/mcp_server/cli.py

@@ -1139,6 +1139,18 @@ def main() -> None:
         action="store_false",
         help="Decisions-only view (omit the code-file overlay)",
     )
+    graph_parser.add_argument(
+        "--no-skills",
+        dest="with_skills",
+        action="store_false",
+        help="Omit the skills overlay (procedural memory)",
+    )
+    graph_parser.add_argument(
+        "--no-reflections",
+        dest="with_reflections",
+        action="store_false",
+        help="Omit the reflections overlay (LLM abstractions)",
+    )
     graph_parser.add_argument(
         "--dry-run",
         action="store_true",
@@ -1239,6 +1251,106 @@ def main() -> None:
         ),
     )
 
+    # v3.1.0 M8: reflections — codevira reflect [--period 7d]
+    # [--from-file PATH] [--apply] [--yes]. Without --from-file the
+    # CLI prints the rendered prompt + source-context summary for the
+    # user to feed to their own LLM; with --from-file it parses the
+    # LLM response and writes a proposal (or commits with --apply).
+    reflect_parser = subparsers.add_parser(
+        "reflect",
+        help="Build a reflection over recent decisions + sessions "
+        "(v3.1.0 M8). MCP sampling/createMessage integration ships "
+        "in v3.2; meanwhile this CLI renders the prompt and accepts "
+        "an LLM response via --from-file.",
+    )
+    reflect_parser.add_argument(
+        "--period",
+        type=int,
+        default=7,
+        help="Look-back window in days (default 7).",
+    )
+    reflect_parser.add_argument(
+        "--from-file",
+        type=str,
+        default=None,
+        help="Read an LLM YAML response from this file (per the prompt "
+        "template) and persist it as a reflection proposal.",
+    )
+    reflect_parser.add_argument(
+        "--apply",
+        action="store_true",
+        help="Commit to .codevira/reflections.jsonl (otherwise the "
+        "result lands in reflection_proposals.jsonl for review).",
+    )
+    reflect_parser.add_argument(
+        "--yes",
+        action="store_true",
+        help="With --apply: skip the interactive confirm prompt.",
+    )
+
+    # v3.1.0 M6 Phase B: cross-IDE consensus check (read-only). The
+    # MCP surface (consensus_check / consensus_status) is also exposed.
+    consensus_parser = subparsers.add_parser(
+        "consensus",
+        help="Cross-IDE consensus operations (v3.1.0 M6). `check` "
+        "materializes conflicts between decisions written by this IDE "
+        "vs other IDEs into .codevira/pending_conflicts.jsonl for "
+        "human review. No automatic resolution; the handshake "
+        "protocol is M7 (opt-in).",
+    )
+    consensus_sub = consensus_parser.add_subparsers(dest="consensus_action")
+    consensus_sub.add_parser(
+        "check",
+        help="Scan for conflicts since the last checkpoint; advance "
+        "this IDE's checkpoint.",
+    )
+
+    # v3.1.0 M5: induced-skill candidate generation. CLI-only — the MCP
+    # surface for skills is record_skill / get_skill / list_skills.
+    induce_parser = subparsers.add_parser(
+        "induce-skills",
+        help="Cluster productive sessions and propose induced skills "
+        "(v3.1.0 M5). Without --apply: writes proposals to "
+        ".codevira/induction_proposals.jsonl for human review. With "
+        "--apply: interactively confirms each proposal (use --yes to "
+        "skip prompts in CI).",
+    )
+    induce_parser.add_argument(
+        "--apply",
+        action="store_true",
+        help="Commit the proposals as induced skills "
+        "(otherwise dry-run to induction_proposals.jsonl)",
+    )
+    induce_parser.add_argument(
+        "--yes",
+        action="store_true",
+        help="With --apply: skip the interactive confirm prompt "
+        "(non-interactive, CI-safe).",
+    )
+
+    # v3.1.0 M2 Phase 3: working-memory subcommands. The MCP tool
+    # surface (working_add / working_get / working_promote) is the
+    # everyday agent-facing API; this CLI tier is the escape hatch for
+    # a human user operating on the per-machine cache outside an IDE.
+    working_parser = subparsers.add_parser(
+        "working",
+        help="Operate on working memory (v3.1.0 M2). `commit <session_id>` "
+        "copies a session's live scratchpad entries from the per-machine "
+        "cache (.codevira-cache/working.jsonl) to the canonical archive "
+        "(.codevira/working_archived/<session_id>.jsonl).",
+    )
+    working_sub = working_parser.add_subparsers(dest="working_action")
+    working_commit_parser = working_sub.add_parser(
+        "commit",
+        help="Promote a session's live working entries to the canonical archive.",
+    )
+    working_commit_parser.add_argument(
+        "session_id",
+        help="Session slug to commit (the value the MCP tool reported as "
+        "session_id, typically `ad-hoc-XXXXXX` or an explicit slug you "
+        "passed to working_add).",
+    )
+
     engine_parser = subparsers.add_parser(
         "engine",
         help="Internal: lifecycle-hook engine entry (called by hook scripts)",
@@ -1270,7 +1382,7 @@ def main() -> None:
     )
     engine_sub.add_parser(
         "enable",
-        help="Re-enable hook engine policies (removes " "~/.codevira/engine.disabled).",
+        help="Re-enable hook engine policies (removes ~/.codevira/engine.disabled).",
     )
     engine_sub.add_parser(
         "status",
@@ -1469,6 +1581,8 @@ def main() -> None:
             out=getattr(args, "out", None),
             dry_run=getattr(args, "dry_run", False),
             with_files=getattr(args, "with_files", True),
+            with_skills=getattr(args, "with_skills", True),
+            with_reflections=getattr(args, "with_reflections", True),
         )
         sys.exit(rc)
     elif args.command == "sync":
@@ -1497,6 +1611,51 @@ def main() -> None:
             keep_data=getattr(args, "keep_data", False),
         )
         sys.exit(rc)
+    elif args.command == "reflect":
+        # v3.1.0 M8: reflections CLI.
+        from mcp_server.cli_reflect import cmd_reflect
+
+        sys.exit(
+            cmd_reflect(
+                period_days=getattr(args, "period", 7),
+                from_file=getattr(args, "from_file", None),
+                apply=getattr(args, "apply", False),
+                yes=getattr(args, "yes", False),
+            )
+        )
+    elif args.command == "consensus":
+        # v3.1.0 M6: cross-IDE consensus CLI.
+        consensus_action = getattr(args, "consensus_action", None)
+        if consensus_action == "check":
+            from mcp_server.cli_consensus import cmd_consensus_check
+
+            sys.exit(cmd_consensus_check())
+        sys.stderr.write(
+            "codevira consensus: missing subcommand. Try `codevira consensus check`.\n"
+        )
+        sys.exit(2)
+    elif args.command == "induce-skills":
+        # v3.1.0 M5: skill induction CLI.
+        from mcp_server.cli_induce import cmd_induce_skills
+
+        sys.exit(
+            cmd_induce_skills(
+                apply=getattr(args, "apply", False),
+                yes=getattr(args, "yes", False),
+            )
+        )
+    elif args.command == "working":
+        # v3.1.0 M2 Phase 3: working-memory subcommands.
+        working_action = getattr(args, "working_action", None)
+        if working_action == "commit":
+            from mcp_server.cli_working import cmd_working_commit
+
+            sys.exit(cmd_working_commit(getattr(args, "session_id", None)))
+        sys.stderr.write(
+            "codevira working: missing subcommand. Try `codevira working commit "
+            "<session_id>`.\n"
+        )
+        sys.exit(2)
     elif args.command == "engine":
         # Internal — Claude Code hook scripts call us with `engine handle <event>`.
         engine_action = getattr(args, "engine_action", None)

codevira-3.1.0/mcp_server/cli_consensus.py

@@ -0,0 +1,55 @@
+"""
+cli_consensus.py — v3.1.0 M6 Phase B: ``codevira consensus check`` CLI.
+
+Read-only scan that materializes cross-IDE conflicts to
+``.codevira/pending_conflicts.jsonl`` for human review. Calls into
+``consensus_store.scan_and_materialize`` so the same path also
+backs the ``consensus_check`` MCP tool.
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+def cmd_consensus_check(*, verbose: bool = False) -> int:
+    """Entry point for ``codevira consensus check``.
+
+    Returns 0 on success (including no conflicts found). Non-zero only
+    on storage / IO errors raised by the scan.
+    """
+    try:
+        from mcp_server.storage import consensus_store
+    except Exception as exc:  # noqa: BLE001
+        sys.stderr.write(
+            f"codevira consensus check: consensus_store import failed: {exc}\n"
+        )
+        return 1
+
+    try:
+        summary = consensus_store.scan_and_materialize()
+    except Exception as exc:  # noqa: BLE001
+        sys.stderr.write(f"codevira consensus check: scan failed: {exc}\n")
+        return 1
+
+    if summary.get("skipped_reason"):
+        sys.stdout.write(
+            f"codevira consensus check: skipped — {summary['skipped_reason']}.\n"
+            f"  Set CODEVIRA_IDE in your MCP config (ide_inject.py handles "
+            f"this for newly-injected IDE configs) and re-run.\n"
+        )
+        return 0
+
+    sys.stdout.write(
+        f"codevira consensus check: scanned {summary.get('scanned', 0)} "
+        f"decision(s) since last checkpoint "
+        f"(foreign-IDE: {summary.get('foreign', 0)}; "
+        f"conflicts recorded: {summary.get('conflicts_recorded', 0)}).\n"
+        f"  Checkpoint advanced to "
+        f"{summary.get('new_checkpoint') or '<none>'}.\n"
+    )
+    if summary.get("conflicts_recorded"):
+        from mcp_server.storage import paths
+
+        sys.stdout.write(f"  Review: {paths.pending_conflicts_path()}\n")
+    return 0