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

== Goal

Adopt session-management standards without duplicating authoritative protocol
text into each repository.

== Maintenance Model

* Protocol definitions: central in `standards/session-management-standards/`
* Policy and hooks: local to each repository
* Session state artifacts: generated per working repository/session

== Canonical Command Model

Use these commands consistently in docs and local bindings:

* `intake repo <path>`
* `checkpoint change <path>`
* `verify maintenance <path>`
* `verify substantial <path>`
* `verify release <path>`
* `close planned <path>`
* `close urgent <path>`
* `recover repo <path>`
* `handover full <path>`
* `handover split <path>`
* `handover model <path>`
* `handover human <path>`

== Mapping Table

[cols="2,2,3",options="header"]
|===
| Family | Protocol | Standards Path

| verify
| maintenance-sweep
| `verify/maintenance-sweep/`

| verify
| substantial-completion
| `verify/substantial-completion/`

| verify
| release-audit
| `verify/release-audit/`

| continuity
| repo-intake
| `continuity/repo-intake/`

| continuity
| checkpoint-before-major-change
| `continuity/checkpoint-before-major-change/`

| continuity
| planned-session-close
| `continuity/planned-session-close/`

| continuity
| emergency-termination
| `continuity/emergency-termination/`

| continuity
| recovery-operation
| `continuity/recovery-operation/`

| handover
| full-transfer
| `handover/full-transfer/`

| handover
| collaborative-transfer
| `handover/collaborative-transfer/`

| handover
| model-transfer
| `handover/model-transfer/`

| handover
| human-transfer
| `handover/human-transfer/`
|===

== Downstream Repository Pattern

Downstream repositories should keep only thin bindings such as:

* `Justfile` aliases/recipes
* `coordination.k9` integration
* `session/README.md`
* `session/custom-checks.k9`
* `session/local-hooks.sh`

Do not copy full protocol content into each repository unless there is a
repository-specific exception that cannot live centrally.

== Runtime Artifacts

Runtime outputs are generated in the active repository and should usually not
be committed as authoritative standards text.

Use templates from `../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`

== Minimal Local Binding Strategy

1. Implement a local command dispatcher that accepts canonical commands.
2. Map friendly aliases in `Justfile` to canonical commands.
3. Add repo-local policy checks in `custom-checks.k9`.
4. Keep local hooks small and deterministic.
5. Store session state in working repo artifacts; do not fork standards text.

== Anti-Drift Rules

* Do not maintain two authoritative copies of the same protocol.
* If local wording diverges from central wording, central wins.
* Rename local references when canonical names change.
* Mark stubs as stubs.
