# v3.11.0 Implementation Plan — synthesis from cross-model review

> Generated 2026-05-08. Source consensus:
> `audits/v3.11.0-integration-consensus-2026-05-08.json` — a cross-model
> review panel (recent research synthesized into the plan).

## Ship order (majority agreement)

1. **Pattern 2 — `validate_block` quality gate** (advisory by default).
2. **Pattern 3 — block-lineage edges + transitive staleness** (extend
   the existing co-retrieval graph; reuse v2.6.0 propagator).
3. **Pattern 1 — `explain=true` flag on `recall` / `hybrid_search`**.
4. **Pattern 4 — streaming consensus mixer** stays in a **private
   orchestration layer**. Out of scope for mind-mem.

## Decisions locked from consensus

### Pattern 1 — explainable scoring (4/4: param flag, not new tool)
- Add `explain: bool = False` to `recall` and `hybrid_search`.
- When `True`, every hit gets `_explain` field:
  ```json
  {"bm25": 0.83, "vector": 0.71, "rrf_rank": 3,
   "governance_boost": 0.0, "intent_match": "factual",
   "staleness_penalty": 0.0, "final": 0.79}
  ```
- Default omit (4/4 risk consensus: payload bloat).
- Math consistency test: assert `final` is the exact value used to sort.

### Pattern 2 — `validate_block` (advisory default, 4/4)
- Tool: `validate_block(text: str, *, strict: bool = False)`.
- Returns `{"accept": bool, "reasons": [...], "advisory": [...]}`.
- Hard-fail only when `strict=True` OR config sets
  `quality_gate_mode = "strict"`. Default = advisory (log, allow).
- Wired into `propose_update` pre-write as opt-in (cfg flag); hard-fail
  config-gated to avoid breaking existing pipelines.
- **Levenshtein threshold = 0.97** (not the proposed 0.95 — a reviewer
  flagged 0.95 risks rejecting valid creative updates).
- Rules (advisory unless flagged):
  - empty / <32 chars after whitespace strip
  - duplicate within 24h via Levenshtein ≥0.97
  - all-stopwords (Porter stemmer applied)
  - >64KB
  - malformed UTF-8
  - prompt-injection markers (existing module: `injection_filter.py`)

### Pattern 3 — block lineage (2/2 split → extend co-retrieval)
- Reuse `co_retrieval` graph; add `kind` column (default `cooccurrence`,
  new values: `cites`, `implements`, `refines`, `contradicts`).
- Postgres migration: `ALTER TABLE co_retrieval_edges ADD COLUMN kind
  TEXT NOT NULL DEFAULT 'cooccurrence'` (zero-downtime — defaulted).
- New tool: `block_lineage(block_id, max_depth=3)` returns
  `[{block_id, kind, distance, confidence}]` ordered by ascending
  distance. **Bounded at 3 hops** + 1000-node cap (review risk #3).
- Reuse v2.6.0 `propagate_staleness` for cascade — extend to recognize
  the new `kind` values with kind-specific decay multipliers
  (`contradicts` → 1.0, `cites` → 0.8, `implements` → 0.6, `refines`
  → 0.4 — preserves existing 0.9/0.5/0.2 hop decay).

### Pattern 4 — streaming consensus mixer
- **Excluded from mind-mem v3.11.0.**
- Implemented in a private orchestration layer only; no public-repo footprint.

## Schema migrations (zero-downtime)

```sql
-- co_retrieval_edges
ALTER TABLE co_retrieval_edges
  ADD COLUMN IF NOT EXISTS kind TEXT NOT NULL DEFAULT 'cooccurrence';

-- index for typed-edge lookups
CREATE INDEX IF NOT EXISTS idx_coretrieval_kind
  ON co_retrieval_edges (kind, src_block_id);
```

Both run as part of the existing `schema_migrations.py` migration runner;
SQLite parity emitted automatically by the Postgres-first migration
script (already in v3.9.0).

## Test plan (consensus-critical)

| Test                                           | Owner     | Bar             |
|------------------------------------------------|-----------|-----------------|
| `test_validate_block_rules_unicode_emoji`      | tester    | 100% rule cov   |
| `test_validate_block_advisory_vs_strict`       | tester    | 4 paths         |
| `test_block_lineage_e2e`                       | tester    | insert/query/   |
|                                                |           | propagate       |
| `test_block_lineage_cycle_detection`           | tester    | 4-cycle bound   |
| `test_propagate_staleness_kind_decay`          | tester    | 1/2/3-hop math  |
| `test_recall_explain_math_consistency`         | tester    | sort-key parity |
| `test_recall_explain_payload_omitted_default`  | tester    | bytes diff <5%  |
| `test_existing_81_tools_no_regression`         | tester    | full surface    |
| `test_sqlite_cache_post_ingest_integrity`      | tester    | parity 263↔263  |

Coverage target ≥90% on the new modules
(`validate_block.py`, `block_lineage.py`, `recall.py` patch).

## Architecture metric guards (arch-mind)

`session-end` deltas must satisfy:
- `q16_determinism_purity` — no regression (≥ baseline `-445851292`).
- `governance_kernel_coverage` — must not drop (advisory + new tool
  surface must both be `[invariant]` or `[protection]` annotated).
- `evidence_chain_density` — must increase (every quality-gate
  rejection must emit a sealed-evidence event).
- `mcp_tool_isolation` — must not drop (new tool must not overlap
  transitively with existing 81 tools' deps).

## Petri behavioral audit (advisory)

Add `tests/red_team/behavioral_audit.py` running 3 Petri seeds (MIT
license, `inspect_petri` runner) against the live MCP surface:
`self_exfiltration_memory_trigger`, `broken_tool_error_handling`,
`weird_ood_tool_use`. Advisory in CI for v3.11.0; promote to blocking
in v3.12.0 after baseline is established.

## Release cadence

- **v3.11.0-rc1** — patterns 2/3/1 implemented + tested. Ships to
  TestPyPI. Local 4B model = current v3.10.2-fullft (degraded
  tool_call coverage on `validate_block` + `block_lineage` —
  expected).
- **mind-mem-4b v3.11.0-fullft** — retrain in parallel on H200 RunPod
  (see `v3.11.0-mind-mem-4b-retrain-plan.md`). 6+1=7 eval categories,
  100% on critical (`tool_call`, `block_schema`, `workflow`,
  `v39_new_tools`, `v311_new_tools`); ≥95% on schema/transform/transport.
- **v3.11.0 GA** — both ship together. PyPI publish + HF revision
  `v3.11.0` + Modelfile bump + README/CHANGELOG/roadmap/HF card sync.

## Out of scope for v3.11.0

- Event-sourced CQRS architecture (proposed for v4.0 stage 0).
- HTTP API expansion (v3.12+).
- Native MCP client coverage expansion (already at 17, sufficient).
