panayiotism/claude-harness/checkpoint

Checkpoint - Save Session Progress

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

Arguments: $ARGUMENTS

Session ID: ${CLAUDE_SESSION_ID} — session state lives in .claude-harness/sessions/${CLAUDE_SESSION_ID}/.

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/${CLAUDE_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.6: Persist to Memory Layers (OKF bundle)

Memory layers are an OKF v0.1 bundle at ${MEMORY_DIR}: one markdown concept file per entry with YAML frontmatter (required type field), plus an index.md listing per directory. See schemas/okf-memory.md for the format.

1.6. Persist session decisions to ${MEMORY_DIR}/decisions/:

• For each key decision made during this session:
• Write a concept file dec-{NNN}-{slug}.md (next NNN from existing files; slug = lowercased decision, non-alphanumerics as hyphens, <=48 chars):

```markdown

type: Decision id: dec-{NNN} title: "{what was decided, <=80 chars}" timestamp: {ISO timestamp} feature: {feature-id}

# {full decision text}

## Rationale {why this decision was made}

## Alternatives

• {other options considered}

## Impact {files or areas affected} ```

• Append * [{id}: {title}](/decisions/{filename}) - {short description} to ${MEMORY_DIR}/decisions/index.md
• Rolling window: if more than 50 decision concepts exist, delete the oldest files and their index lines (FIFO)
• Report: "Recorded {N} decisions to episodic memory"

1.7. Update semantic memory with discovered patterns:

• Read ${MEMORY_DIR}/semantic/architecture.json
• 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
• For new concepts/entities discovered:
• Append entry with name, type, location, relationships
• Write updated file

1.9. Persist reusable patterns to ${MEMORY_DIR}/patterns/:

• Extract reusable patterns from this session:
• Code patterns that worked well
• Naming conventions used
• Project-specific rules learned
• For each NEW pattern (check ${MEMORY_DIR}/patterns/index.md to avoid duplicates):
• Write pat-{NNN}-{slug}.md with frontmatter (type: Pattern, id, title) and body # {pattern} + ## Source
• Append a matching * [...](...) line to ${MEMORY_DIR}/patterns/index.md
• Report: "Updated procedural patterns"

Phase 1.9.5: Compile Session Briefing

1.9.5. Write persistent session briefing to .claude-harness/session-briefing.md:

• The SessionStart hook points Claude at this file on every new session
• 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: {immediate actionable items} ```

• Keep under 120 lines (~1500 tokens) to avoid context bloat
• Source data: ${FEATURES_FILE} plus the OKF memory bundle (${MEMORY_DIR}/decisions/, ${MEMORY_DIR}/failures/, ${MEMORY_DIR}/rules/ concept files) -- or run python3 "${CLAUDE_PLUGIN_ROOT}/scripts/compile-briefing.py" .claude-harness --write to generate it
• 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 always enabled:

• 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 as a Rule concept: write ${MEMORY_DIR}/rules/rule-{NNN}-{slug}.md (frontmatter type: Rule, id, title, timestamp, active: true; body = # {title} + description) and add it to ${MEMORY_DIR}/rules/index.md
• 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

1. Run build/test commands appropriate for the project

• Check for errors and fix if possible
• Report any failures

Phase 3: Commit & Push

1. 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/${CLAUDE_SESSION_ID}/loop-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 with git push -u origin {branch}

Phase 4: PR Management

1. If on a feature/fix branch (gh CLI must be authenticated -- check gh auth status on failure):

• Get GitHub owner/repo: use the cached values from the session context (injected at SessionStart); only if absent, parse once from git remote get-url origin
• Check loop state type to determine if this is a feature or fix
• Check if a PR exists for this branch: gh pr list --head {branch} --json number,url
• If no PR exists, create one:

`` gh pr create --title "{title}" --body "{body}" --label "{labels}" ``

• Title follows conventional commits:
• For features: feat: <description>
• For fixes: fix: <description>
• refactor: <description> for refactoring
• docs: <description> for documentation
• Body should include:
• Link to issue: "Closes #XX" or "Fixes #XX"
• For fixes: Also reference original feature issue
• Summary of changes (bullet points)
• Testing instructions
• Breaking changes (if any)
• Labels:
• For features: Copy from linked issue + add status:ready-for-review
• For fixes: Add bugfix + linked-to:{feature-id} + status:ready-for-review
• If PR exists:
• Update PR description with latest progress: gh pr edit {number} --body "{updated body}"
• Add comment summarizing checkpoint changes: gh pr comment {number} --body "..."
• Update labels based on current status
• Check PR status: gh pr view {number} --json state,mergeable,reviewDecision,statusCheckRollup
• Update tracking:
• For features: Update ${FEATURES_FILE} features array with prNumber
• For fixes: Update ${FEATURES_FILE} fixes array with prNumber
• Report PR URL and status

PR Title Convention (Conventional Commits):

• feat: New feature (triggers MINOR version bump)
• fix: Bug fix (triggers PATCH version bump)
• refactor: Code refactoring
• docs: Documentation
• test: Tests
• chore: Maintenance

Phase 5: Report Status

1. Report final status:

• Build/test results
• Commit hash and push status
• PR URL, CI status, review status
• Remaining work

Phase 6: Clear Loop State and Tasks (if feature/fix completed)

1. If an agentic loop just completed successfully:

• Read session-scoped loop state: .claude-harness/sessions/${CLAUDE_SESSION_ID}/loop-state.json
• If status is "completed" and matches current feature/fix:
• Mark all tasks complete (if tasks.enabled in loop-state):
• Call TaskList to find the feature's tasks
• For any tasks not yet "completed", call TaskUpdate to mark as "completed"
• Report: "All 6 tasks completed"
• Reset loop state to idle (see schemas/loop-state.schema.json for canonical shape):

``json { "version": 9, "feature": null, "featureName": null, "type": "feature", "linkedTo": null, "status": "idle", "attempt": 0, "maxAttempts": 12, "startedAt": null, "lastAttemptAt": null, "verification": {}, "history": [], "tasks": { "enabled": false, "chain": [], "current": null, "completed": [] }, "lastCheckpoint": "{commit-hash}", "escalationRequested": false } ``

• Report: "Loop completed and reset"
• If loop is still in progress, preserve state for session continuity
• Optional session cleanup: If feature is archived and session is complete, the session directory can be removed (it's gitignored anyway; the SessionEnd hook also removes it on clean exit)

Phase 7: Archive Completed Features and Fixes

1. Archive completed features and fixes:

• Read ${FEATURES_FILE}

Archive features:

• Find all features with status="passing" or passes=true
• If any completed features exist:
• Read ${ARCHIVE_FILE} (create if missing with {"version":3,"archived":[],"archivedFixes":[]})
• Add archivedAt timestamp to each completed feature
• Append completed features to the archived[] array
• Remove completed features from features array
• Report: "Archived X completed features"

Archive fixes:

• Find all fixes with status="passing"
• If any completed fixes exist:
• Add archivedAt timestamp to each completed fix
• Append completed fixes to the archivedFixes[] array
• Remove completed fixes from fixes array
• Report: "Archived X completed fixes"

• Write updated ${FEATURES_FILE} and ${ARCHIVE_FILE}

Phase 8: Persist Orchestration Memory

1. Persist orchestration memory (if orchestration was active):

• Read .claude-harness/agents/context.json
• Skip if no currentSession or no agentResults