checkpoint

What this skill does

# Checkpoint - Save Session Progress

Create a checkpoint of the current session: commit, push, PR, memory persistence, and feature archival.

Arguments: $ARGUMENTS

## Phase 0: Set Paths

1. **Set path variables**:
   - `FEATURES_FILE=".claude-harness/features/active.json"`
   - `ARCHIVE_FILE=".claude-harness/features/archive.json"`
   - `MEMORY_DIR=".claude-harness/memory/"`
   - `PROGRESS_FILE=".claude-harness/claude-progress.json"`
   - `SESSION_DIR=".claude-harness/sessions/{session-id}/"`

## Phase 1: Update Progress

1. Update `${PROGRESS_FILE}` with:
   - Summary of what was accomplished this session
   - Any blockers encountered
   - Recommended next steps
   - Update lastUpdated timestamp

## Phase 1.5: Capture Working Context

**Session Paths**: All session-specific state uses `.claude-harness/sessions/{session-id}/`. The session ID is provided by the SessionStart hook.

1.5. Update session-scoped working context `.claude-harness/sessions/{session-id}/working-context.json` with current working state:
   - Read `${FEATURES_FILE}` (from main repo in worktree mode) to identify active feature (first with passes=false)
   - Set `activeFeature` to the feature ID and `summary` to feature name
   - Populate `workingFiles` from:
     - Feature's `relatedFiles` array
     - Files shown in `git status` (modified/new)
     - For each file, add brief role description (one line)
   - Populate `decisions` with key architectural/implementation decisions made
   - Populate `codebaseUnderstanding` with insights about relevant code areas
   - Set `nextSteps` to immediate actionable items
   - Update `lastUpdated` timestamp

   **Keep concise**: ~25-40 lines total. This will be loaded on session resume.

   Example output:
   ```json
   {
     "version": 1,
     "lastUpdated": "2025-12-29T16:00:00.000Z",
     "activeFeature": "feature-003",
     "summary": "Add Google OAuth login",
     "workingFiles": {
       "src/auth/google.ts": "new - OAuth provider implementation",
       "src/auth/index.ts": "modified - added Google to provider registry",
       "prisma/schema.prisma": "modified - added Account model"
     },
     "decisions": [
       "Store tokens in DB, not cookies",
       "Separate Account model linked to User"
     ],
     "codebaseUnderstanding": {
       "authSystem": "Uses provider registry pattern, withAuth() middleware"
     },
     "nextSteps": [
       "Add error handling for token revocation",
       "Test OAuth callback flow"
     ]
   }
   ```

## Phase 1.6: Persist to Memory Layers

1.6. **Persist session decisions to episodic memory**:
   - Read `${MEMORY_DIR}/episodic/decisions.json` (from main repo in worktree mode)
   - For each key decision made during this session:
     - Append new entry:
       ```json
       {
         "id": "{uuid}",
         "timestamp": "{ISO timestamp}",
         "feature": "{feature-id}",
         "decision": "{what was decided}",
         "rationale": "{why this decision was made}",
         "alternatives": ["{other options considered}"],
         "impact": "{files or areas affected}"
       }
       ```
   - If entries exceed `maxEntries` (default 50), remove oldest entries (FIFO)
   - Write updated file
   - Report: "Recorded {N} decisions to episodic memory"

1.7. **Update semantic memory with discovered patterns**:
   - Read `${MEMORY_DIR}/semantic/architecture.json` (from main repo in worktree mode)
   - Update based on work done this session:
     - Add new file paths to `structure.entryPoints`, `structure.components`, etc.
     - Update `patterns.naming` with discovered naming conventions
     - Update `patterns.fileOrganization` with discovered structures
     - Update `patterns.codeStyle` with observed patterns
   - Set `lastUpdated` to current timestamp
   - Write updated file

1.8. **Update semantic entities (if new concepts discovered)**:
   - Read `${MEMORY_DIR}/semantic/entities.json` (from main repo in worktree mode)
   - For new concepts/entities discovered:
     - Append entry with name, type, location, relationships
   - Write updated file

1.9. **Update procedural patterns**:
   - Read `${MEMORY_DIR}/procedural/patterns.json` (from main repo in worktree mode)
   - Extract reusable patterns from this session:
     - Code patterns that worked well
     - Naming conventions used
     - Project-specific rules learned
   - Merge into existing patterns (don't duplicate)
   - Write updated file
   - Report: "Updated procedural patterns"

## Phase 1.9.5: Compile Session Briefing

1.9.5. **Write persistent session briefing** to `.claude-harness/session-briefing.md`:
   - This file is automatically injected into Claude's context at every SessionStart (via the hook)
   - It ensures Claude is immediately aware of project state on new sessions without manual `/start`
   - Compile from current state -- read features, decisions, failures, rules, and status:

   ```markdown
   # Session Briefing
   Last updated: {ISO timestamp}

   ## Active Features
   - {id}: {name} [{status}]
     {one-line description}
     Acceptance: {N} scenarios | Files: {relatedFiles summary}

   ## Recent Decisions (last 5)
   - {decision} ({feature}, {date})

   ## Approaches to AVOID
   - {approach} -> {rootCause} ({feature})

   ## Learned Rules
   - {title}: {description}

   ## Current Status
   Last checkpoint: {commit message summary}
   Branch: {current branch}
   Next steps: {from working-context nextSteps}
   ```

   - Keep under 120 lines (~1500 tokens) to avoid context bloat
   - Source data: `${FEATURES_FILE}`, `${MEMORY_DIR}/episodic/decisions.json`, `${MEMORY_DIR}/procedural/failures.json`, `${MEMORY_DIR}/learned/rules.json`
   - This file is git-tracked and persists across sessions, `/clear`, and machine reboots

## Phase 1.10: Auto-Reflect on User Corrections

1.10. **Auto-reflect is now always enabled** (part of UX simplification):
   - This phase always runs to capture learnings from the session
   - High-confidence rules are auto-saved; lower-confidence go to review queue

1.11. **Run reflection with auto mode**:
   - Execute the reflection logic (auto mode):
     - Scan conversation for user correction patterns
     - Filter for high-confidence corrections only
     - Skip interactive approval (auto mode)
   - For corrections with confidence >= `minConfidenceForAuto`:
     - Auto-approve and save to `${MEMORY_DIR}/learned/rules.json`
   - For lower confidence corrections:
     - Add to queue for manual review (don't save)

1.12. **Report auto-reflect results** (if rules extracted):
   ```
   AUTO-REFLECTION
   High-confidence rules auto-saved: {N}
   - {rule title}
   - {rule title}

   Lower-confidence (manual review needed): {N}
   (Low-confidence rules queued for next checkpoint review)
   ```

1.13. **If no corrections detected**:
   - Continue silently to Phase 2 (no noise if nothing found)

## Phase 2: Build & Test

2. Run build/test commands appropriate for the project
   - Check for errors and fix if possible
   - Report any failures

## Phase 3: Commit & Push

3. ALWAYS commit changes:
   - **Stage harness state files first**: `git add .claude-harness/` (sessions/ and working/ are gitignored, so only persistent state is staged)
   - Stage all other modified files: `git add -A` (except secrets/env files)
   - Check loop state to determine commit prefix:
     - Read session-scoped loop state: `.claude-harness/sessions/{session-id}/loop-state.json`
     - If session file doesn't exist, check legacy: `.claude-harness/loops/state.json`
     - If `type` is "fix": Use `fix({linkedTo.featureId}): <description>` prefix
     - If `type` is "feature" or undefined: Use `feat({feature-id}): <description>` prefix
   - Write descriptive commit message summarizing the work
   - For fixes, include: `Fixes #{fix-issue-number}` and `Related to #{original-issue-number}`
   - Push to remote

## Phase 4: PR Management (if GitHub MCP available)

4. If on a feature/fix branch and GitHub MCP is available:
   - **Get