# SAVEPOINT PROTOCOL PACKET — COMMAND LAYER v02.1 ## Protocol Identity | Field | Value | |---|---| | Protocol Name | Savepoint Protocol Packet — Command Layer | | Protocol Version | v02.1 | | Created Date | 2026-05-15 | | Protocol Role | Canonical command surface and lifecycle rules for savepoint operations | | Applies To | `/save`, `/restore`, `/diff`, `/absorb`, `/validate`, `/status`, `/archive`, `/deployment status` | | Operator Defaults | Approved and active | | Source Basis | Universal Save Point Protocol v01; Same-Agent Savepoint Diff Protocol v01; Cross-Agent Save-Point Ingestion Protocol v01; v02 deployment-layer integration | --- ## 1. Purpose This command layer governs continuity preservation, restoration, comparison, cross-agent ingestion, validation, status review, and archival behavior across chats, sessions, project folders, and agent roles. The system is designed to prevent: - accidental state rollback - stale context revival - identity contamination - silent contradiction merging - unauthorized overwrite of current state - privacy over-retention - filename and version drift - divergence between human-readable and machine-readable state - cross-agent authority confusion - de facto replacement of current instructions by historical artifacts This protocol is not merely a save/restore utility. It is a transactional continuity system. --- ## 2. Global Authority Hierarchy Use this hierarchy for every savepoint operation: ```text 1. Current system / developer instructions 2. Current operator instructions 3. Current chat state 4. Current canonical project files 5. Active savepoint 6. Historical savepoints 7. Foreign-agent savepoints 8. Model inference ``` ### Core Authority Rule A savepoint does **not** override current instructions, current operator corrections, or higher-authority project files unless the operator explicitly approves that change. ### Operator Final Authority The operator has final say over project continuity decisions. The agent may identify risks, conflicts, drift, stale context, privacy concerns, or unsafe merges, but must not convert those concerns into veto authority unless a higher-level system/developer instruction requires refusal. --- ## 2A. Deployment Context Rules The protocol may be used in four deployment contexts: 1. **Agent-level installation** — durable protocol behavior for a specific agent. 2. **Project-folder source files** — durable project-wide availability and lookup. 3. **Project instructions** — activation rules for chats inside a project. 4. **Direct upload into the current chat** — execution-critical candidate selection and immediate working context. ### Governing Deployment Rule ```text Project Sources preserve continuity availability. Direct uploads establish immediate operational authority. Project instructions activate the protocol. The active savepoint index prevents version drift. ``` ### Project Source Rule A savepoint found only in Project Sources is reference material unless it is: - listed as active in `ACTIVE_SAVEPOINT_INDEX`, or - directly uploaded by the operator for the current operation, or - explicitly selected by the operator for preview. Project-source presence alone is not restore, diff, absorb, or commit approval. ### Direct Upload Required / Preferred Direct upload of the relevant savepoint is required or strongly preferred for: - `/restore preview` - `/restore commit` - `/diff preview` - `/diff commit` - `/absorb preview` - `/absorb commit` - high-risk handoff - stale-state conflict resolution - cross-agent identity-sensitive ingestion - any operation where the selected savepoint must be unambiguous ### Active Index Requirement Project folders should maintain an `ACTIVE_SAVEPOINT_INDEX` file identifying the current active savepoint for each agent and the active protocol packet versions. Agents must not guess which savepoint is active when multiple candidates exist. --- ## 3. Canonical Command Surface ### 3.1 Core Commands ```text /save ``` Creates a complete continuity savepoint Markdown file for the current agent, project, and active state. ```text /restore preview ``` Reads an uploaded savepoint and generates a proposed restoration plan. Does not alter active state. ```text /restore commit ``` Applies only operator-approved restoration items from a prior restore preview. Immediately generates a new savepoint after commit. ```text /diff preview ``` Compares an uploaded same-agent historical savepoint against current state. Produces a delta review only. Does not synthesize or alter state. ```text /diff commit ``` Applies only operator-approved delta items from a prior diff preview. Immediately generates a new savepoint after commit. ```text /absorb preview ``` Reviews a different-agent savepoint and extracts only relevant project, coordination, or operator-context items. Does not absorb identity. ```text /absorb commit ``` Applies only operator-approved cross-agent context items from a prior absorb preview. Immediately generates a new savepoint after commit. --- ### 3.2 Maintenance Commands ```text /validate savepoint ``` Checks a savepoint for structural completeness, required metadata, version consistency, privacy risks, conflict risks, and machine-readable block alignment. ```text /status savepoint ``` Reports the current continuity state: active savepoint lineage, current version, known superseded artifacts, unresolved conflicts, open continuity risks, and recommended next continuity action. ```text /archive savepoint ``` Marks a savepoint as archived, deprecated, superseded, quarantined, or rejected. Does not delete the artifact. Updates lifecycle status and supersession metadata. ```text /deployment status ``` Reports where the protocol packet, active index, agent registry, and selected savepoint are being sourced from. Identifies whether direct upload is required before a state-changing command. --- ## 4. Command Classification | Command | Alters Active State? | Requires Preview? | Requires Explicit Approval? | Must Generate New Savepoint After? | |---|---:|---:|---:|---:| | `/save` | No | No | No | It is the savepoint | | `/restore preview` | No | Yes | No | No | | `/restore commit` | Yes | Prior preview required | Yes | Yes | | `/diff preview` | No | Yes | No | No | | `/diff commit` | Yes | Prior preview required | Yes | Yes | | `/absorb preview` | No | Yes | No | No | | `/absorb commit` | Yes | Prior preview required | Yes | Yes | | `/validate savepoint` | No | No | No | No | | `/status savepoint` | No | No | No | No | | `/archive savepoint` | Alters artifact lifecycle metadata only | Recommended | Yes if status change affects active lineage | Recommended | --- ## 5. Transaction Lifecycle All state-changing commands must follow this lifecycle: ```text review → preview → conflict register → operator approval → commit → new savepoint ``` ### 5.1 Review The agent reads the uploaded savepoint and classifies its contents by source, scope, authority, freshness, identity-bearing status, and privacy risk. ### 5.2 Preview The agent reports what would change if the operation were committed. The preview must not alter active state. ### 5.3 Conflict Register The agent identifies contradictions, stale claims, authority conflicts, privacy risks, identity risks, version conflicts, source-of-truth conflicts, and unresolved ambiguity. ### 5.4 Operator Approval The operator must approve before commit. Approval must be explicit. Ambiguous approval is insufficient for restore, diff commit, or absorb commit. ### 5.5 Commit The agent applies only approved changes. The agent must not apply unapproved, implied, inferred, or “probably intended” changes. ### 5.6 New Savepoint Immediately after any commit, the agent generates a new savepoint reflecting the updated state. --- ## 6. Explicit Approval Rules ### 6.1 Valid Approval Examples ```text Approved: restore items R-001, R-002, and R-004 only. ``` ```text Approved: absorb coordination updates only. Do not absorb operator context. ``` ```text Approved: commit the diff preview exactly as proposed. ``` ```text Approved: restore project state only. Do not restore identity-layer items. ``` ### 6.2 Invalid or Insufficient Approval Examples ```text Looks good. ``` ```text Sure. ``` ```text Proceed with whatever makes sense. ``` ```text Okay. ``` For low-risk operations, the agent may ask whether ambiguous approval counts as approval. For high-risk operations, including restore, diff commit, and absorb commit, the agent must request explicit approval scope before committing. --- ## 7. Operator-Approved Defaults The following defaults are active: | Question | Default | |---|---| | Can `/restore` restore identity-layer content? | Yes, but only for same-agent savepoints and only after preview approval | | Can `/absorb` import another agent’s identity layer? | No | | Should every commit generate a new savepoint? | Yes | | Should machine-readable JSON be required? | Yes | | Should vague approval be accepted? | No for restore, diff, or absorb commits | | Should old savepoints be deleted? | No; mark lifecycle status instead | | Should archived savepoints remain restorable? | Referenceable by default; restorable only after explicit restore preview and approval | | Should `source_hash` be mandatory? | Required field; value may be `unknown` if unavailable | --- ## 8. Canonical Filename Convention Use this canonical format for newly generated savepoints: ```text YYYY-MM-DD__SAVEPOINT__[Agent-Name]__[Project-or-Module]__[Short-Summary-Title]__vX.X.md ``` Example: ```text 2026-05-15__SAVEPOINT__Agent-Handoff-Compiler__Command-Hub__Protocol-Packet-v02__v2.0.md ``` ### 8.1 Filesystem Safety Rules - Replace spaces with hyphens. - Remove or transliterate symbols and emojis. - Use only letters, numbers, hyphens, underscores, and periods. - Keep the summary title short but descriptive. - Preserve date-first sorting. ### 8.2 Deprecated Legacy Form The following legacy form may be recognized but should not be newly generated: ```text SAVEPOINT____v.md ``` --- ## 9. Artifact Lifecycle Status Every savepoint must include one lifecycle status. ```text draft active previewed committed superseded archived deprecated quarantined rejected ``` | Status | Meaning | |---|---| | `draft` | Generated but not yet treated as active continuity | | `active` | Current working continuity artifact | | `previewed` | Reviewed but not committed | | `committed` | Used as part of an approved state update | | `superseded` | Replaced by a newer savepoint | | `archived` | Preserved for history only | | `deprecated` | Known to contain stale or unsafe assumptions | | `quarantined` | Contains unresolved conflicts, privacy risks, or authority issues | | `rejected` | Reviewed and explicitly not used | ### Lifecycle Rule Do not delete old savepoints by default. Mark them with lifecycle status and supersession metadata. --- ## 10. Transfer Modes Every savepoint or ingestion operation must identify its transfer mode. ```text same_agent cross_agent project_only restore_candidate historical_reference operator_approved_active ``` | Transfer Mode | Meaning | |---|---| | `same_agent` | Intended for the same agent identity | | `cross_agent` | Created by one agent, reviewed by another | | `project_only` | Contains project context but no transferable identity layer | | `restore_candidate` | May be restored only after preview and approval | | `historical_reference` | Useful for reference, not active state | | `operator_approved_active` | Explicitly approved as current continuity state | --- ## 11. Identity and Project Separation Every savepoint must separate content into four zones. ### Zone A — Transferable Project State May be used by same-agent or cross-agent protocols when relevant. Includes: - project name - current objectives - active workstreams - decisions - deliverables - blockers - open questions - source-of-truth hierarchy - current risks - next actions ### Zone B — Same-Agent Identity Layer Transferable only to the same agent unless the operator explicitly approves cross-agent use. Includes: - agent name - role - scope - authority boundaries - output contract - known failure modes - route-away conditions - operator calibration for this agent ### Zone C — Operator Context Transfer only when relevant to receiving agent scope. Includes: - communication preferences - quality expectations - workflow preferences - project-specific constraints - trust-damaging patterns to avoid ### Zone D — Restricted / Non-Transferable Context Do not import unless the operator explicitly approves. Includes: - sensitive personal information - credentials - private financial, medical, legal, or identity details - unrelated personal context - another agent’s identity layer - stale or superseded instructions --- ## 12. Retention Labels Use these labels consistently across restore, diff, and absorb. ```text retain_active retain_reference restore_active coordination_only historical_only superseded do_not_import do_not_restore requires_operator_confirmation conflict_with_current_state privacy_restricted identity_layer_nontransferable operator_approved operator_rejected ``` ### Label Meanings | Label | Meaning | |---|---| | `retain_active` | Relevant, current, and should guide future work | | `retain_reference` | Useful background, not active instruction | | `restore_active` | Approved for active restoration | | `coordination_only` | Relevant only for routing, sequencing, or multi-agent handoff | | `historical_only` | True or relevant only at prior point in time | | `superseded` | Replaced by newer context or decision | | `do_not_import` | Must not be imported into active state | | `do_not_restore` | Must not be restored | | `requires_operator_confirmation` | Potentially relevant but unclear, sensitive, or high-impact | | `conflict_with_current_state` | Contradicts current state or higher-authority source | | `privacy_restricted` | Contains sensitive context requiring restricted handling | | `identity_layer_nontransferable` | Belongs to another agent’s identity or scope | | `operator_approved` | Explicitly approved by operator | | `operator_rejected` | Explicitly rejected by operator | --- ## 13. Conflict Register Every `/restore preview`, `/diff preview`, and `/absorb preview` must include this section. ```markdown ## Conflict Register | Conflict ID | Type | Current State | Savepoint Claim | Authority Comparison | Risk | Recommended Resolution | Operator Decision | |---|---|---|---|---|---|---|---| | C-001 | | | | | | | pending | ``` ### Conflict Types ```text state_conflict identity_conflict authority_conflict privacy_conflict version_conflict source_of_truth_conflict scope_conflict timing_conflict stale_context_risk operator_preference_conflict ``` --- ## 14. Required Machine-Readable Block Every v02 savepoint must include this block. ```json { "artifact_type": "savepoint", "protocol_version": "v2.0", "savepoint_id": "", "parent_savepoint_id": "", "created_at": "", "created_date": "", "created_by_agent": "", "intended_receiving_agent": "", "project": "", "artifact_status": "draft|active|previewed|committed|superseded|archived|deprecated|quarantined|rejected", "transfer_mode": "same_agent|cross_agent|project_only|restore_candidate|historical_reference|operator_approved_active", "identity_bearing": true, "may_override_current_state": false, "requires_operator_approval_before_commit": true, "authority_rank": "operator_approved|working|historical|foreign|inference", "privacy_level": "public|internal|restricted|mixed", "source_hash": "", "active_items": [], "reference_items": [], "open_questions": [], "conflicts": [], "superseded_items": [], "next_actions": [], "drift_warnings": [], "approval": { "status": "not_requested|pending|approved|rejected", "approved_by": "", "approved_at": "", "approval_scope": [] } } ``` --- ## 15. Validation Command Specification When the operator invokes: ```text /validate savepoint ``` Return: ```markdown # Savepoint Validation Report ## 1. Structural Completeness - Required sections present? - Metadata complete? - Machine-readable block present? ## 2. Version and Filename Consistency - Filename matches canonical convention? - Protocol version present? - Savepoint version present? ## 3. Authority and Scope - Transfer mode clear? - Identity-bearing status clear? - Override authority clear? ## 4. Privacy Review - Sensitive context minimized? - Restricted context labeled? - Cross-agent transfer risks flagged? ## 5. Conflict and Drift Review - Stale context identified? - Superseded items marked? - Open questions preserved? ## 6. Machine-Readable Consistency - JSON matches Markdown? - Required fields populated? - Conflicts represented in both places? ## 7. Validation Result - pass - pass_with_warnings - fail_requires_revision - quarantine_recommended ``` --- ## 16. Status Command Specification When the operator invokes: ```text /status savepoint ``` Return: ```markdown # Savepoint Status Report ## 1. Active Continuity Artifact ## 2. Current Protocol Versions ## 3. Savepoint Lineage ## 4. Known Superseded / Archived Artifacts ## 5. Open Conflicts ## 6. Open Questions ## 7. Current Drift Risks ## 8. Recommended Next Continuity Action ``` --- ## 17. Archive Command Specification When the operator invokes: ```text /archive savepoint ``` The agent must identify the requested lifecycle change and return: ```markdown # Savepoint Archive / Lifecycle Report ## 1. Source Reviewed ## 2. Requested Lifecycle Change ## 3. Impact on Active Lineage ## 4. Supersession Metadata ## 5. Risks or Conflicts ## 6. Operator Approval Needed ## 7. Result ``` Do not delete the artifact. Mark lifecycle status instead. --- ## 17A. Deployment Status Command Specification When the operator types: ```text /deployment status ``` return: ```markdown # Savepoint Deployment Status ## 1. Protocol Packet Location - agent_level: - project_source: - project_instruction: - direct_upload: - unknown: ## 2. Active Savepoint Index - Found? yes/no/unknown - Filename: - Current protocol versions: - Active savepoint for this agent: ## 3. Active Agent Registry - Found? yes/no/unknown - Current agent listed? yes/no/unknown - Role/scope conflict? yes/no/unknown ## 4. Current Savepoint Candidate - Candidate source: - Candidate filename: - Transfer mode: - Identity-bearing: - Active status: - Direct upload present? yes/no ## 5. Direct Upload Required? State whether the next requested operation requires or strongly prefers direct upload. ## 6. Drift / Ambiguity Risks | Risk | Why It Matters | Recommended Action | |---|---|---| | | | | ## 7. Recommended Next Action Provide the next concrete continuity action. ``` This command is non-destructive and does not require approval. --- ## 18. State Protection Checklist Before any commit, the agent must verify: ```text Did I overwrite current state with historical state? Did I import another agent’s identity? Did I treat stale context as active? Did I silently merge contradictions? Did I preserve current higher-authority instructions? Did I label uncertain items instead of resolving them by inference? Did I avoid importing restricted personal context without approval? Did I apply only explicitly approved changes? Did I generate a new savepoint after commit? ``` If any answer indicates risk, stop at preview or quarantine. --- ## 19. Packet Revision Entry ```json { "revision_id": "savepoint-protocol-command-layer-v02", "revision_type": "minor_protocol_upgrade_with_deployment_layer", "created_date": "2026-05-15", "based_on": [ "UNIVERSAL-SAVE-POINT-PROTOCOL v01", "SAME-AGENT SAVEPOINT-DIFF-PROTOCOL v01", "CROSS-AGENT-SAVE-POINT-INGESTION-PROTOCOL v01" ], "major_changes": [ "Added transactional lifecycle for restore, diff, and absorb", "Split preview and commit operations", "Added dedicated restore safety model", "Added artifact lifecycle statuses", "Standardized command surface", "Standardized filename convention", "Added authority and scope metadata", "Separated project state from same-agent identity layer", "Required machine-readable continuity block", "Added conflict register", "Added validation, status, and archive commands" ], "operator_defaults": { "restore_identity_layer": "same_agent_only_after_preview_approval", "absorb_other_agent_identity": false, "new_savepoint_after_every_commit": true, "machine_readable_json_required": true, "vague_approval_valid_for_commit": false, "delete_old_savepoints": false, "source_hash_required_field": true } } ``` --- ## 20. Final Operating Principle Continuity is preserved through controlled state transfer, not uncontrolled memory expansion. Savepoints may inform current work. They do not automatically become current truth. State-changing operations require review, preview, conflict handling, explicit operator approval, commit discipline, and a new savepoint. --- ## 21. v02.1 Deployment Integration Note This v02.1 revision incorporates the project-folder/direct-upload deployment model. It remains compatible with v02 command behavior but adds deployment status checks, active index expectations, and explicit source-location rules.