// SPDX-License-Identifier: CC-BY-SA-4.0
// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath)
= Session Management Standards
Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
v2.0, 2026-04-07
:toc:
:toclevels: 3

== Purpose

This directory is the authoritative source for session-management protocols
shared across Hyperpolymath repositories.

Downstream repositories should keep only thin local bindings and integration
logic. Protocol definitions live here.

== Canonical Protocol Families

=== verify

* `maintenance-sweep` (`verify maintenance <path>`)
* `substantial-completion` (`verify substantial <path>`)
* `release-audit` (`verify release <path>`)

=== continuity

* `repo-intake` (`intake repo <path>`)
* `checkpoint-before-major-change` (`checkpoint change <path>`)
* `planned-session-close` (`close planned <path>`)
* `emergency-termination` (`close urgent <path>`)
* `recovery-operation` (`recover repo <path>`)

=== handover

* `full-transfer` (`handover full <path>`)
* `collaborative-transfer` (`handover split <path>`)
* `model-transfer` (`handover model <path>`)
* `human-transfer` (`handover human <path>`)

=== cross-cutting

Protocols that apply across every family above:

* `concurrent-write-collision` — companion-file pattern for handover
  documents under parallel-session write contention. See
  link:CONCURRENT-WRITE-COLLISION-PROTOCOL.adoc[CONCURRENT-WRITE-COLLISION-PROTOCOL.adoc].
  Adopted 2026-04-13.

== Shared Continuity Core

Every protocol and runtime artifact aligns to the same continuity core, defined
in link:SHARED-CONTINUITY-CORE.adoc[SHARED-CONTINUITY-CORE.adoc].

The core captures 25 essential fields across meta-attributes, core content,
tables, and lists, ensuring full context transfer between sessions.

== Directory Map

[source,text]
----
session-management-standards/
  README.adoc
  SHARED-CONTINUITY-CORE.adoc                # cross-cutting
  CONCURRENT-WRITE-COLLISION-PROTOCOL.adoc   # cross-cutting
  adoption-and-integration-guide/
    GUIDE.adoc
  verify/
    maintenance-sweep/
    substantial-completion/
    release-audit/
  continuity/
    repo-intake/
    checkpoint-before-major-change/
    planned-session-close/
    emergency-termination/
    recovery-operation/
  handover/
    collaborative-transfer/
    full-transfer/
    human-transfer/
    model-transfer/
  templates/
    SESSION_STATE.adoc
    NEXT_STEPS.md
    SESSION_SUMMARY.md
    EMERGENCY-CHECKPOINT.md
    SUBSTANTIAL_COMPLETION_REPORT.md
    HANDOVER-REPORT.md
    RECOVERY-PLAN.md
    RELEASE_AUDIT.md
    MAINTENANCE_REPORT.md
----

== Protocol File Contract

Each protocol directory (e.g., `continuity/planned-session-close/`) should
contain:

1. CHECKLIST.adoc (e.g., `continuity/planned-session-close/CHECKLIST.adoc`)
2. PROTOCOL.k9 (e.g., `continuity/planned-session-close/PROTOCOL.k9`)
3. STATE-template.a2ml (e.g., `continuity/planned-session-close/STATE-template.a2ml`)
4. EXAMPLE-FILLED-IN.adoc (e.g., `continuity/planned-session-close/EXAMPLE-FILLED-IN.adoc`)
5. optional local helper scripts (e.g., `run.sh`, `verify.sh`, `recover.sh`)

== Current Status

* `continuity/planned-session-close/` is fully expanded and active.
* `continuity/emergency-termination/CHECKLIST.adoc` contains detailed content.
* `verify/substantial-completion/CHECKLIST.adoc` contains detailed content.
* Remaining protocol files are present as explicit stubs and should be expanded
  incrementally.

== Adoption

See link:adoption-and-integration-guide/GUIDE.adoc[adoption-and-integration-guide/GUIDE.adoc]
for repository-local integration patterns.

== Renamed Protocols

The following previous names are retired and replaced:

* `maintenance-check` -> `verify/maintenance-sweep`
* `planned-termination` -> `continuity/planned-session-close`
* `handover-preparation` -> `handover/*-transfer`
