From b5e9d0e528a50aae2e916cc7202bacc2e8db67dd Mon Sep 17 00:00:00 2001 From: Jarvis Date: Mon, 13 Jul 2026 09:53:37 -0500 Subject: [PATCH] docs(tess): add migration evidence set --- docs/tess/M5-MIGRATION-CUTOVER.md | 12 ++++++++++++ docs/tess/M5-MIGRATION-INVENTORY.md | 11 +++++++++++ docs/tess/M5-MIGRATION-RETENTION-DEPRECATION.md | 14 ++++++++++++++ docs/tess/M5-MIGRATION-ROLLBACK.md | 10 ++++++++++ 4 files changed, 47 insertions(+) create mode 100644 docs/tess/M5-MIGRATION-CUTOVER.md create mode 100644 docs/tess/M5-MIGRATION-INVENTORY.md create mode 100644 docs/tess/M5-MIGRATION-RETENTION-DEPRECATION.md create mode 100644 docs/tess/M5-MIGRATION-ROLLBACK.md diff --git a/docs/tess/M5-MIGRATION-CUTOVER.md b/docs/tess/M5-MIGRATION-CUTOVER.md new file mode 100644 index 0000000..cd5a715 --- /dev/null +++ b/docs/tess/M5-MIGRATION-CUTOVER.md @@ -0,0 +1,12 @@ +# TESS-MIG-001 — Cutover Procedure + +This procedure is evidence-bound. It does not authorize a production cutover until the M5 qualification gate records the required validation. + +1. Confirm the gateway has the explicitly registered `runtime.hermes` adapter (`apps/gateway/src/agent/agent.module.ts`) and provider reachability evidence (`apps/gateway/src/agent/hermes-runtime-reachability.e2e.test.ts`). +2. Query the normalized runtime capability surface, not a Hermes API directly. Confirm the session capabilities required for the operation are advertised. +3. Query the transitional matrix through `RuntimeProviderService.transitionalCapabilityMatrix` (`apps/gateway/src/agent/runtime-provider-registry.service.ts`). Kanban, skills, memory, tools, and cron must remain `unsupported`; stop rather than route those operations through Hermes. +4. Route new memory activity through the Mosaic operator-memory plugin path; there is no landed Hermes memory import. +5. Use `MosCoordinationService` for orchestration handoff. Tess does not take Mos authority. +6. Record the qualification evidence and only then update an external deployment/channel binding through its separately authorized operational process. + +No claim here authorizes bulk transcript copying, data-schema migration, or enabling an unsupported transitional capability. diff --git a/docs/tess/M5-MIGRATION-INVENTORY.md b/docs/tess/M5-MIGRATION-INVENTORY.md new file mode 100644 index 0000000..05358aa --- /dev/null +++ b/docs/tess/M5-MIGRATION-INVENTORY.md @@ -0,0 +1,11 @@ +# TESS-MIG-001 — Hermes → Mosaic Evidence Inventory + +Hermes is a reference adapter, not a Mosaic core dependency. `packages/agent/src/hermes-runtime-provider.ts` contains the adapter-local `HermesLegacySession` and converts it to core `RuntimeSession`; `packages/types/src/agent/agent-runtime-provider.ts` contains only normalized contracts. `apps/gateway/src/agent/agent.module.ts` explicitly registers the adapter, while `apps/gateway/src/agent/runtime-provider-registry.service.ts` exposes it only through the runtime registry. + +| Reference concern | Landed Mosaic evidence | State | +| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | +| sessions, hierarchy, streaming, send/attach/terminate | `HermesRuntimeProvider` plus `hermes-runtime-provider.test.ts` | adapted | +| Kanban, skills, memory, tools, cron | normalized matrix in `HermesRuntimeProvider.transitionalCapabilityMatrix`; each is `unsupported` and `assertTransitionalCapability` denies before a transport call | deferred / fail-closed | +| operator memory | `packages/memory/src/operator-memory-plugin.ts`, constructed by `apps/gateway/src/memory/memory.module.ts` and session-scoped by `apps/gateway/src/agent/agent.service.ts` | native Mosaic path | +| orchestration handoff | `apps/gateway/src/coord/mos-coordination.service.ts` retains authenticated handoff/observe/result ownership checks | native Mosaic path | +| transcripts, profiles, preferences | no Hermes importer/schema mapping landed | no automatic migration | diff --git a/docs/tess/M5-MIGRATION-RETENTION-DEPRECATION.md b/docs/tess/M5-MIGRATION-RETENTION-DEPRECATION.md new file mode 100644 index 0000000..9f63dc8 --- /dev/null +++ b/docs/tess/M5-MIGRATION-RETENTION-DEPRECATION.md @@ -0,0 +1,14 @@ +# TESS-MIG-001 — Retention and Legacy Deprecation Policy + +## Retention + +- Hermes is not a Mosaic persistence authority. The adapter maps runtime behavior only; it does not import or persist Hermes legacy session shapes. +- Mosaic operator memory is scoped by tenant, owner, and session in `packages/memory/src/operator-memory-plugin.ts`; gateway session ownership is derived before that plugin is made available in `apps/gateway/src/agent/agent.service.ts`. +- Existing Hermes archives remain in their source system under its existing retention policy. This project has no landed automatic transcript, profile, or preference migration. +- Any future import requires an explicit, scoped design and redaction/provenance evidence; it must not extend `packages/types` with Hermes schema. + +## Deprecation + +- Session adapter use remains transitional until M5 qualification demonstrates the normalized provider path. +- Kanban, skills, memory, tools, and cron are not deprecated into a Hermes bridge: they remain explicitly unsupported until their Mosaic-owned contracts are implemented and qualified. +- A future deprecation change must remove the external binding first, retain rollback evidence, and then remove the adapter in a separately reviewed code change. It must not silently replace or widen a registered provider. diff --git a/docs/tess/M5-MIGRATION-ROLLBACK.md b/docs/tess/M5-MIGRATION-ROLLBACK.md new file mode 100644 index 0000000..34ec700 --- /dev/null +++ b/docs/tess/M5-MIGRATION-ROLLBACK.md @@ -0,0 +1,10 @@ +# TESS-MIG-001 — Rollback Procedure + +Rollback is configuration/binding reversal, not a database rollback: no Hermes schema migration or automatic data import is implemented by the landed adapter. + +1. Stop sending new traffic to the Mosaic Hermes adapter by reverting the external runtime/channel binding through its authorized deployment process. +2. Keep the gateway registration and core contracts unchanged unless a reviewed code rollback is required; `AgentRuntimeProviderRegistry` registration is explicit and non-replacing (`packages/agent/src/runtime-provider-registry.ts`). +3. Do not replay an unsupported Kanban, skills, memory, tools, or cron operation. The transitional matrix is intentionally fail-closed. +4. Preserve Mosaic audit, session, and operator-memory records under their normal scoped retention rules; do not copy them into Hermes as a rollback shortcut. +5. For an in-flight coordination request, use the owned handoff observation/result flow in `MosCoordinationService`; do not create a second orchestrator path. +6. Capture the binding reversal, affected scope, correlation IDs, and reason in the approved operational record before retrying a cutover.