feat(memory): add V1 migration audit and deprecation guidance

cli/knowledge.md

@@ -16,14 +16,14 @@
 - The SQLite repository projects the latest `coverage.recorded` event per `(taskId, dimension)` into the `currentCoverage` retrieval category, filtered by exact workspace revision/snapshot freshness and optional `taskId` narrowing.
 - The `query_index` tool handler (`packages/agent-runtime/src/tools/handlers/tool/query-index.ts`) records its results into `agentState.discoveryCoverage` via `recordDiscoveryResult` with a bounded (4000-char) question string; recording is wrapped in try/catch so a coverage failure can never break the tool call.
 - When testing tool handlers that import a function to spy on, prefer `spyOn(namespaceImport, 'fn')` over `mock.module()` (repo convention in `docs/testing.md`/`CONTRIBUTING.md`); a relative `mock.module` specifier resolves from the test file's directory and silently misses the module the subject under test imports when the two live at different depths.
-- Memory V2 authority is selected by `OPENBUFF_MEMORY_AUTHORITY` via `getMemoryAuthoritySelection` (`cli/src/utils/env.ts`); the default is `sqlite-v2-opt-in` (fail-closed — no V1 fallback), with `json-v1` as an explicit opt-out escape hatch and `shadow-v2` as an explicit shadow mode. The provider (`cli/src/services/memory-v2/provider.ts`) keys its shadow-vs-fail-closed behavior off `authority.effective`, so flipping the default flips which degradation path default runs take.
+- Memory V2 authority is selected by `OPENBUFF_MEMORY_AUTHORITY` via `getMemoryAuthoritySelection` (`cli/src/utils/env.ts`); the default is `sqlite-v2-opt-in` (fail-closed — no V1 fallback), with `json-v1` as an explicit opt-out escape hatch and `shadow-v2` as an explicit shadow mode. Release N keeps `json-v1` and `shadow-v2` supported but deprecates both compatibility modes; `sqlite-v2-opt-in` is the default and replacement. Authority selection, degradation, and fallback behavior are unchanged in this release, no removal date/version is implied, and migration is not claimed complete. Follow the normative [Memory V1 removal readiness plan](../docs/memory-v1-removal-readiness.md) before any later removal decision.
 
 ## Slash Commands and Plan Mode
 
 - Durable planning is entered through `mode:plan`; the standalone `/plan` command is intentionally absent from `COMMAND_REGISTRY` and `SLASH_COMMANDS` so there is one plan-entry path.
 - Keep the durable-plan quartet registered: `/resume-plan` (`rp`), `/update-plan` (`up`), `/plan-status` (`ps`), and `/lessons` (`lesson`). These commands operate on `.agents/sessions/<slug>/` artifacts and fall back to the plan-session picker when no target is provided.
 - `/plans` (`plan-ls`) lists the artifact-bearing sessions returned by `listPlanSessions()` and never prompts the agent, while `/plan-use` (`plan-active`, `use-plan`) writes the `ACTIVE_SESSION` pointer file under `.agents/` and only accepts a bare slug or `.agents/sessions/<slug>` — the resolved directory must be exactly one segment under `.agents/sessions/` because the pointer stores bare slugs, so nested paths, non-session paths, missing directories, and artifact-less directories are all rejected before any write. Both share `formatPlanSessionListRow` / `PLAN_SESSIONS_DIR_PREFIX` from `cli/src/commands/plan-artifacts.ts` so the rendered box and the text report cannot drift.
-- `/memory` (alias `/mem`, `cli/src/commands/memory-command.ts`, registered in `command-registry.ts` and listed in `data/slash-commands.ts`) inspects the persisted cross-session task memory for the current project (`.openbuff/memory/task-memory.json`). `/memory status` (the default) reports the record's revision and age, its goal and per-list counts, and how much of its evidence still verifies against disk, listing up to five stale paths; `/memory prune` drops evidence that no longer verifies. Both subcommands are move-aware via `collectWorkspaceMoves` + `WorkspaceJournalService` so a renamed file's evidence rebinds rather than being reported stale and deleted.
+- `/memory` (alias `/mem`, `cli/src/commands/memory-command.ts`, registered in `command-registry.ts` and listed in `data/slash-commands.ts`) inspects the persisted cross-session task memory for the current project (`.openbuff/memory/task-memory.json`). `/memory status` (the default) reports the record's revision and age, its goal and per-list counts, and how much of its evidence still verifies against disk, listing up to five stale paths; `/memory prune` drops evidence that no longer verifies. Both subcommands are move-aware via `collectWorkspaceMoves` + `WorkspaceJournalService` so a renamed file's evidence rebinds rather than being reported stale and deleted. `/memory audit-migration` is dedicated and read-only: before acquiring V2 it calls `inspectPersistedTaskMemoryV1`, blocks absent/invalid/unreadable states with bounded distinct reports, and passes the exact checksum-verified memory to the SDK audit without a second read. An `exact` audit reconstructs and compares every deterministic source-derived task/observation header and payload plus marker metadata; it is lossless only when `omittedFields === 0`, `(truncatedFields ?? 0) === 0`, and `warnings.length === 0`. The legacy loader still collapses non-valid inspection states to `undefined` for compatibility. `not-migrated` means removal is not ready and is not a product defect; all outcomes are rendered distinctly with bounded reason text. The audit's exactness check is order-insensitive (canonicalized before comparison) because the SQLite backend persists payloads via key-sorted `stableJson` and re-parses them on export; this is covered end-to-end by `cli/src/services/memory-v2/__tests__/memory-v1-migration-sqlite-roundtrip.test.ts`.
 - Slash-command descriptions should stay model-agnostic under BYOK/local mode. Use wording such as "configured reviewer" rather than naming hosted models.
 
 ## Import Guidelines
@@ -919,7 +919,7 @@ Streaming markdown renders as plain text until the message or agent finishes. Th
 
 - _Knowledge refresh 2026-08-23: add `/memory` (alias `/mem`) slash command; staleness guard touch._
 
-- _Knowledge refresh 2026-09-12: Memory V2 implementation across `cli/src/services/memory-v2/` (SQLite kernel with WAL/append-only triggers/canonical projections/project binding, contained file I/O with O_NOFOLLOW/proc-fd anchoring, lease-based provider with opt-in fail-closed), `/memory` command expanded to 18 subcommands (authority/diagnose/query/inspect/consolidate/repair/revalidate/correct/forget/pin/export/import plus existing status/prune) with sanitized error boundaries and preview-by-default mutators, `cli/src/utils/codebuff-client.ts` gained `ManagedOpenbuffClient` with lease-based lifecycle and `memoryV2ClientConfigFromProvider` wiring, `cli/src/utils/env.ts` gained `getMemoryAuthoritySelection` for the `OPENBUFF_MEMORY_AUTHORITY` env var, `cli/src/types/chat.ts` gained `MemoryReportContentBlock` and `v2Lines` additive fields, and `cli/src/components/renderers/memory-box.tsx` gained the `report` state renderer with insert-command buttons._
+- _Knowledge refresh 2026-09-12: Memory V2 implementation across `cli/src/services/memory-v2/` (SQLite kernel with WAL/append-only triggers/canonical projections/project binding, contained file I/O with O_NOFOLLOW/proc-fd anchoring, lease-based provider with opt-in fail-closed), `/memory` expanded with authority/diagnose/query/inspect/consolidate/repair/revalidate/correct/forget/pin/export/import and the read-only SDK-backed `audit-migration` command plus existing status/prune, all with sanitized error boundaries and preview-by-default mutators; `cli/src/utils/codebuff-client.ts` gained `ManagedOpenbuffClient` with lease-based lifecycle and `memoryV2ClientConfigFromProvider` wiring, `cli/src/utils/env.ts` gained `getMemoryAuthoritySelection` for the `OPENBUFF_MEMORY_AUTHORITY` env var, `cli/src/types/chat.ts` gained `MemoryReportContentBlock` and `v2Lines` additive fields, and `cli/src/components/renderers/memory-box.tsx` gained the `report` state renderer with insert-command buttons._
 
 - _Knowledge refresh 2026-08-31: live compaction status rendering (`context_compaction_status` consumption, run-correlated pending/settled pairing, replayed-pending-as-interrupted) in `cli/src/utils/sdk-event-handlers.ts` and `cli/src/components/renderers/compaction-box.tsx`._