Session Offload (/session-offload)

This skill defines the strict shutdown sequence for all AI agents finishing a session.

MANDATORY CHECKLIST RULE: Before executing the steps below, you MUST create a task.md artifact (or use the existing one) containing a checklist of all steps 1 to 5. You must physically update the checklist [x] as you complete each step. You are NOT allowed to skip any step.

1. Scratchpad Eviction

Scan and delete temporary files. Run these exact commands:

# Clean temporary diagnostic artifacts and stale backups cross-platform
python .agents/scripts/orion.py gc

1.5. Auto-Context Sync (Conversational Extraction)

If any new business rules, logic constraints, or architectural decisions were explicitly discussed with the user during this session, you MUST execute the /auto-context workflow now. This ensures conversational knowledge is persisted into the context/ structure before memory is wiped.

TERMINATION GATE: Execute /auto-context ONCE. Do not re-enter session-offload.md after /auto-context completes. After injection, proceed directly to Step 1.6.

1.6. Public Changelog Ledger & DNA SemVer Hook (Full Session & Unreleased Audit)

If CHANGELOG.md does not exist in the project root, copy .agents/templates/CHANGELOG.template.md to seed the initial Keep a Changelog structure with ## [Unreleased]. If CHANGELOG.md already exists, preserve its existing structure and historical entries completely—never overwrite or re-initialize it.

Once CHANGELOG.md is present, audit the entire unreleased delta since the last release tag (v<VERSION>..HEAD + uncommitted working tree) BEFORE committing:

1. Run DNA SemVer Radar: Execute python .agents/scripts/orion.py dna semver to inspect all Unreleased Commits and Modified Files since the baseline release tag (v<VERSION>), not just the single last task.
2. Outcome-Focused & Zero Internal Leaks: CHANGELOG.md MUST serve external users and developers, never an internal engineering diary.
   • Outcome Over Process: State the resulting capability or fix, never internal review stages, development workflows, or implementation steps.
   • Zero Internal Symbols or Paths: Never include internal source paths (core/..., commands/...), function/class/variable names, flags, comment markers, or test suite filenames.
   • Macro-Thematic Consolidation: Group deliverables into 5–8 high-signal thematic entries per release milestone. Macro capabilities receive 1 prominent list item with scope description; related minor enhancements and fixes are synthesized into 1 coherent summary paragraph per domain, avoiding fragmented 20+ item lists.
   • Zero AI Fingerprints: Ban metaphorical AI verbs (absorb, supercharge, empower, revolutionize, unleash, delve). Use plain verbs (add, fix, update, remove).
3. Episodic Triage (Strict Unreleased Invariant): Ensure every public deliverable across all commits and working-tree changes in this session (v<VERSION>..HEAD) is recorded under ## [Unreleased] across standard Keep a Changelog categories (Added, Changed, Deprecated, Removed, Fixed, Security).
4. Release Milestone Stamping (Explicit User Release Gate Only):
   • DO NOT execute dna bump on routine session offloads or in-development projects. Routine offloads MUST leave all deliverables in ## [Unreleased].
   • DO NOT stamp a fake 1.0.0 or bump version numbers on uninitiated greenfield projects (0.0.0) or active pre-release alpha/beta branches.
   • ONLY run python .agents/scripts/orion.py dna bump --auto (or --release) when the user has explicitly requested to conclude a tagged production release milestone.

2. Worktree Cleanup & Commit (Gated Auto-Commit)

If you have uncommitted changes (including updated CHANGELOG.md and context/ files) and the project is a git repository, you MUST pass 4 gates before committing them:

1. Logic Gate: Run the test suite (e.g. npm test or flutter test). You MUST NOT commit if Exit Code > 0.
2. Architecture Gate (DNA Hard Gate): Run python .agents/scripts/orion.py dna audit. Block commit if layer violations > 0, chimera files > 0, or score < 90.
3. Security Gate: Check for hardcoded API keys/secrets and run python .agents/scripts/orion.py verify_agents. Block commit if secrets found.
4. History Gate: DO NOT use generic commit messages. Use git diff to generate a strict Conventional Commit (<type>(<scope>): <description>).

(If the project is NOT a git repository, skip the History Gate and do not run git commands).

# 1. Logic Gate (Verify Exit Code == 0)
# (Run stack-specific test command here, e.g., 'npm test' or 'flutter test')

# 2. Architecture Gate (Verify 0 DNA violations & score >= 90)
python .agents/scripts/orion.py dna audit

# 3. Security Gate
python .agents/scripts/orion.py verify_agents

# 4. History Gate (Review exact diff and stage modified files surgically)
git diff
git add -u
git commit -m "<type>(<scope>): <precise description>"

2.5. Git Worktree & Branch Integration State Machine

When completing feature work on a branch or worktree:

1. Detect Workspace Isolation:

   # Check if inside linked worktree (not git submodule)
   git rev-parse --show-superproject-working-tree

2. Present Integration Menu to User:
   • Option 1: Merge to Base Branch Locally:

     git checkout <base_branch>
     git pull
     git merge <feature_branch>
     # Run tests on merged result
     <test_command>
     # Remove worktree if safe
     git worktree remove <worktree_path>

   • Option 2: Push & Create Pull Request: Push branch to origin and emit PR template.
   • Option 3: Keep Branch / Worktree As-Is: Preserve current checkout for manual developer inspection.

3. Atomic Memory Compression & Task Archival

Run the compression tool to prevent token bloat for the next session. The script automatically archives any tasks marked as DONE.

python .agents/scripts/orion.py compress

Verify that no obsolete task files remain in .orion/working/tasks/.

3.2. Sovereign Harness Drain & Skill Promotion

Drain the staging intent queue so any self-learned skills, umbrellas, or rule patches proposed during this session are validated against the 6 admission classes and atomically committed:

python .agents/scripts/orion.py harness promote

3.8. Self-Reflection

• Mandatory Action: Before ending the session, you MUST analyze any errors, failed executions, false assumptions, and cognitive biases that occurred during the session. Document these learnings in the session log so the system and user can evolve.

4. Generate Precise Handoff State (MANDATORY FORMAT)

You MUST explicitly use the write_file tool to save the exact markdown block below to .orion/working/handoff.md BEFORE running the offload and compression scripts. Do not just output it to the chat screen. Do not leave fields empty.

4.5. Orion Session Log & Synthesis (Awareness Push)

• Mandatory Action: The agent MUST append a 3-line session learning or architectural decision summary to .orion/episodic/session_history.md.
• High-Signal Episodic Observation Tags: You MUST categorize and tag the session's critical events into the log using these strict prefix tags:
  • [decision]: Architectural choices or tradeoffs made.
  • [bugfix]: Root causes and solutions for errors encountered.
  • [feature]: Completed capabilities or deliverables.
  • [refactor]: Structural code improvements or AST hardenings.
  • [discovery]: Non-obvious codebase quirks or dependencies found.
  • [security_alert]: Any boundary bypasses or sensitive data risks.
  • [sensitive]: Secrets or environment configurations modified.
  • [open_loop]: Unresolved issues or deferred tasks.
• Purpose: Closes the feedback loop to ensure project memory compounds over time via structured needle observations.
• Session Pulse: Execute python .agents/scripts/orion.py consolidate session to synthesize the session and trigger any pending Milestones.
• Archive .orion/working/handoff.md content as an episodic entry in .orion/log.md.

# SESSION HANDOFF

## 1. Resume Point
[Exactly what the next agent should do first. Provide exact file paths.]

## 2. Technical State
- **Active Files**: [List the 1-3 files actively being edited]
- **Current Blocker**: [Any unresolved errors or pending test results]
- **Pending Migrations**: [Any unapplied SQL changes?]

## 3. Context Offloading Entry
- **Git Commit Changes**: [MANDATORY: Execute `python .agents/scripts/orion.py dna semver` or `git log v<CURRENT_VERSION>..HEAD --oneline` to extract all commits and modified files across the session/release cycle, not just `HEAD~1`.]
- **Session Notes**: [Summary of technical decisions or business logic changes made during the session.]

## 4.6. Metrik Cost & Token Savings (MANDATORY)
You MUST execute the RTK built-in feature to report token savings specific to THIS SESSION:
1. Run `rtk gain --history` and filter/count only the execution rows that occurred during this session's timeframe.
2. Write a summary metric **Session Token Savings** in your farewell response (ignore historical data).

## 5. Anti-Goals (Do Not Do)
- [Any brittle architectural areas discovered during this session]

5. Formal Closure

Give a 1-sentence summary of the task completion and confirm that .orion/working/handoff.md is ready.

📚 Mandatory Knowledge Routing (JIT References)

If your current task intersects with these domains, you MUST execute view_file on the target BEFORE writing code: