uv-suite 0.26.2 → 0.26.3

package/hooks/checkpoint-helper.sh

@@ -0,0 +1,124 @@
+#!/bin/bash
+# UV Suite helper: locate per-session checkpoint paths and print metadata.
+# Used by the /checkpoint and /restore slash commands.
+#
+# Usage:
+#   checkpoint-helper.sh dir       # ensure + print the dir for current session
+#   checkpoint-helper.sh meta      # print session metadata as shell-eval'able lines
+#   checkpoint-helper.sh frontmatter  # YAML frontmatter to embed at the top of a checkpoint
+#   checkpoint-helper.sh latest    # cat the latest checkpoint for current session (with fallback)
+#   checkpoint-helper.sh list      # list all sessions that have checkpoints, newest first
+
+resolve_paths() {
+  PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+  STATE_DIR="$PROJECT_DIR/.uv-suite-state"
+  SID="${UVS_SESSION_ID:-}"
+  if [ -z "$SID" ] && [ -f "$STATE_DIR/current-session.txt" ]; then
+    SID=$(cat "$STATE_DIR/current-session.txt" 2>/dev/null)
+  fi
+  CHECKPOINTS_ROOT="$PROJECT_DIR/uv-out/checkpoints"
+  SESSION_CP_DIR=""
+  [ -n "$SID" ] && SESSION_CP_DIR="$CHECKPOINTS_ROOT/$SID"
+  META_FILE=""
+  [ -n "$SID" ] && META_FILE="$STATE_DIR/sessions/$SID.json"
+}
+
+print_meta_field() {
+  # $1 = field name; reads from $META_FILE; empty if missing
+  [ -z "$META_FILE" ] || [ ! -f "$META_FILE" ] && { echo ""; return; }
+  if command -v jq >/dev/null 2>&1; then
+    jq -r --arg k "$1" '.[$k] // ""' "$META_FILE" 2>/dev/null
+  else
+    grep -o "\"$1\"[[:space:]]*:[[:space:]]*\"[^\"]*\"" "$META_FILE" | head -1 | sed "s/.*\"$1\"[[:space:]]*:[[:space:]]*\"\(.*\)\"/\1/"
+  fi
+}
+
+resolve_paths
+
+case "$1" in
+  dir)
+    if [ -n "$SESSION_CP_DIR" ]; then
+      mkdir -p "$SESSION_CP_DIR"
+      echo "$SESSION_CP_DIR"
+    else
+      mkdir -p "$CHECKPOINTS_ROOT"
+      echo "$CHECKPOINTS_ROOT"
+    fi
+    ;;
+  meta)
+    echo "uvs_session_id=${SID:-}"
+    echo "session_name=$(print_meta_field name)"
+    echo "session_kind=$(print_meta_field kind)"
+    echo "session_purpose=$(print_meta_field purpose)"
+    echo "session_priority=$(print_meta_field priority)"
+    echo "persona=$(print_meta_field persona)"
+    ;;
+  frontmatter)
+    NAME=$(print_meta_field name)
+    KIND=$(print_meta_field kind)
+    PURPOSE=$(print_meta_field purpose)
+    PRIORITY=$(print_meta_field priority)
+    PERSONA=$(print_meta_field persona)
+    NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+    cat <<EOF
+---
+uvs_session_id: ${SID:-}
+session_name: ${NAME}
+session_kind: ${KIND}
+session_purpose: ${PURPOSE}
+session_priority: ${PRIORITY}
+persona: ${PERSONA}
+checkpoint_at: ${NOW}
+---
+EOF
+    ;;
+  latest)
+    if [ -n "$SESSION_CP_DIR" ] && [ -f "$SESSION_CP_DIR/latest.md" ]; then
+      cat "$SESSION_CP_DIR/latest.md"
+    elif [ -f "$CHECKPOINTS_ROOT/latest.md" ]; then
+      echo "(no per-session checkpoint for ${SID:-this session}; showing legacy global latest.md)"
+      echo
+      cat "$CHECKPOINTS_ROOT/latest.md"
+    else
+      echo "No checkpoint found at $CHECKPOINTS_ROOT. Run /checkpoint to create one."
+    fi
+    ;;
+  list)
+    [ ! -d "$CHECKPOINTS_ROOT" ] && { echo "No checkpoints directory at $CHECKPOINTS_ROOT"; exit 0; }
+    found=0
+    for d in "$CHECKPOINTS_ROOT"/*/; do
+      [ -d "$d" ] || continue
+      cp_sid=$(basename "$d")
+      cp_meta="$STATE_DIR/sessions/$cp_sid.json"
+      cp_name=""
+      cp_priority=""
+      if [ -f "$cp_meta" ]; then
+        if command -v jq >/dev/null 2>&1; then
+          cp_name=$(jq -r '.name // ""' "$cp_meta" 2>/dev/null)
+          cp_priority=$(jq -r '.priority // ""' "$cp_meta" 2>/dev/null)
+        else
+          cp_name=$(grep -o '"name"[[:space:]]*:[[:space:]]*"[^"]*"' "$cp_meta" | head -1 | sed 's/.*"name"[[:space:]]*:[[:space:]]*"\(.*\)"/\1/')
+        fi
+      fi
+      latest=$(ls -t "$d"*.md 2>/dev/null | head -1)
+      [ -z "$latest" ] && continue
+      ts=$(stat -f '%Sm' -t '%Y-%m-%d %H:%M' "$latest" 2>/dev/null || stat -c '%y' "$latest" 2>/dev/null | cut -c1-16)
+      label="${cp_name:-(unlabeled)}"
+      [ -n "$cp_priority" ] && label="$label [p:$cp_priority]"
+      mark=" "
+      [ "$cp_sid" = "$SID" ] && mark="*"
+      echo "$mark ${cp_sid:0:8}  $ts  $label"
+      found=1
+    done
+    [ "$found" -eq 0 ] && echo "No per-session checkpoints yet (current session: ${SID:-none})"
+    # Note legacy global checkpoint if present
+    if [ -f "$CHECKPOINTS_ROOT/latest.md" ]; then
+      ts=$(stat -f '%Sm' -t '%Y-%m-%d %H:%M' "$CHECKPOINTS_ROOT/latest.md" 2>/dev/null || stat -c '%y' "$CHECKPOINTS_ROOT/latest.md" 2>/dev/null | cut -c1-16)
+      echo "  legacy   $ts  (pre-metadata global latest.md)"
+    fi
+    ;;
+  *)
+    echo "Usage: checkpoint-helper.sh [dir|meta|frontmatter|latest|list]"
+    exit 1
+    ;;
+esac

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uv-suite",
-  "version": "0.26.2",
+  "version": "0.26.3",
   "description": "Portable framework for AI-assisted software development. 10 agents, 9 skills, 5 hooks, 4 personas. Works with Claude Code, Cursor, and Codex.",
   "author": "Utsav Anand",
   "license": "MIT",

package/skills/checkpoint/SKILL.md

@@ -3,7 +3,8 @@ name: checkpoint
 description: >
   Save a checkpoint of the current session — what was done, key decisions, current state,
   and what's next. Use before ending a session, before /compact, or at any natural breakpoint.
-  The next session auto-loads the latest checkpoint.
+  Checkpoints are stored per-session under uv-out/checkpoints/<session-id>/, so concurrent
+  terminals don't clobber each other. /restore picks up the latest for the current session.
 argument-hint: "[optional-label]"
 user-invocable: true
 allowed-tools:
@@ -12,39 +13,51 @@ allowed-tools:
   - Bash(git status *)
   - Bash(git diff *)
   - Bash(git log *)
+  - Bash(git branch *)
   - Bash(git rev-parse *)
   - Bash(date *)
   - Bash(ls *)
   - Bash(mkdir *)
+  - Bash(cat *)
   - Bash(echo *)
+  - Bash("$CLAUDE_PROJECT_DIR"/.claude/hooks/checkpoint-helper.sh *)
 ---
 
-## Resolve checkpoint directory
+## Resolve session and checkpoint directory
 
-Anchor checkpoints to `$CLAUDE_PROJECT_DIR` (or the git repo root, or the current
-working dir as a last resort) so `/checkpoint` and `/restore` always agree, no matter
-which subdirectory the session was launched from.
-
-!`DIR="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/uv-out/checkpoints"; mkdir -p "$DIR"; echo "$DIR"`
+!`"$CLAUDE_PROJECT_DIR"/.claude/hooks/checkpoint-helper.sh dir`
 
 Use the absolute path printed above as `<checkpoint-dir>` for every file path below.
+The directory is per-session — two `uv` launches in the same repo write to
+different folders, so checkpoints don't collide.
+
+## Session metadata
+
+!`"$CLAUDE_PROJECT_DIR"/.claude/hooks/checkpoint-helper.sh meta`
+
+## Frontmatter to embed at the top of the checkpoint
+
+!`"$CLAUDE_PROJECT_DIR"/.claude/hooks/checkpoint-helper.sh frontmatter`
 
 ## Write a checkpoint
 
-Write a file named `<checkpoint-dir>/YYYY-MM-DD-HHMM.md` using the current timestamp.
+Write a file named `<checkpoint-dir>/YYYY-MM-DD-HHMM.md` using the current
+timestamp. **Begin the file with the YAML frontmatter block printed above
+exactly as shown** — `/restore` parses these fields when picking which
+checkpoint to load.
 
-Also write/overwrite `<checkpoint-dir>/latest.md` with the same content, so the next
-session's `/restore` always finds the freshest state.
+Also write/overwrite `<checkpoint-dir>/latest.md` with the same content,
+so the next session's `/restore` always finds the freshest state for this
+session.
 
 ## Label
 
 $ARGUMENTS
 
-If a label was provided, include it in the filename: `<checkpoint-dir>/YYYY-MM-DD-HHMM-[label].md`
-
-## What to capture
+If a label was provided, include it in the filename:
+`<checkpoint-dir>/YYYY-MM-DD-HHMM-[label].md`
 
-Review the full conversation so far and write a structured checkpoint with these exact sections:
+## Body structure (after the frontmatter)
 
 ```markdown
 # Checkpoint: [date] [time] [label if provided]
@@ -88,5 +101,5 @@ Review the full conversation so far and write a structured checkpoint with these
 
 - Be specific. "Worked on auth" is useless. "Added JWT refresh token rotation with 7-day expiry" is useful.
 - Capture WHY decisions were made, not just what. The next session needs the rationale.
-- Keep it under 80 lines. This isn't a novel — it's a handoff.
-- Every checkpoint overwrites `latest.md` so the next session always finds the freshest state.
+- Keep the body under 80 lines. The frontmatter is required and not counted.
+- Always include the YAML frontmatter — `/restore` reads it to pick the right checkpoint and to display session context.

package/skills/restore/SKILL.md

@@ -1,25 +1,55 @@
 ---
 name: restore
 description: >
-  Restore the latest checkpoint from a previous session. Shows what was done,
-  key decisions, current state, and what's next. Use at the start of a new session.
+  Restore the latest checkpoint for the current session — shows what was done,
+  key decisions, current state, and what's next. With no arguments, picks the
+  current `UVS_SESSION_ID`'s most recent checkpoint. Pass a session id prefix
+  or name to restore from a different session.
+argument-hint: "[<session-id-prefix> | <session-name> | list]"
 user-invocable: true
 allowed-tools:
   - Read(*)
   - Bash(ls *)
   - Bash(cat *)
   - Bash(grep *)
+  - Bash(find *)
   - Bash(git rev-parse *)
+  - Bash("$CLAUDE_PROJECT_DIR"/.claude/hooks/checkpoint-helper.sh *)
 ---
 
-## Latest checkpoint
+## Available sessions with checkpoints
 
-!`DIR="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/uv-out/checkpoints"; if [ -f "$DIR/latest.md" ]; then cat "$DIR/latest.md"; else echo "No checkpoint found at $DIR. Run /checkpoint to create one."; fi`
+!`"$CLAUDE_PROJECT_DIR"/.claude/hooks/checkpoint-helper.sh list`
 
-## All checkpoints
+(`*` marks the current session.)
 
-!`DIR="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/uv-out/checkpoints"; if [ -d "$DIR" ]; then matches=$(ls -la "$DIR"/ 2>/dev/null | grep '\.md$' | tail -10); if [ -n "$matches" ]; then echo "$matches"; else echo "No checkpoints in $DIR"; fi; else echo "No checkpoints directory at $DIR"; fi`
+## Latest checkpoint for the current session
+
+!`"$CLAUDE_PROJECT_DIR"/.claude/hooks/checkpoint-helper.sh latest`
+
+## Argument
+
+$ARGUMENTS
 
 ## Instructions
 
-Read the checkpoint above. Summarize it to the user in 3-4 sentences: what was done, what's the current state, and what's next. Then ask: "Ready to pick up from here, or do you want to take a different direction?"
+1. **If `$ARGUMENTS` is empty or "latest"**: read the checkpoint shown above (the
+   current session's `latest.md`). Summarize it in 3-4 sentences: what was
+   done, current state, what's next. Then ask: "Ready to pick up from here, or
+   do you want to take a different direction?"
+
+2. **If `$ARGUMENTS` is "list"**: just show the user the available-sessions
+   list above and ask which one they want to restore.
+
+3. **If `$ARGUMENTS` looks like a session id prefix** (8-char hex / UUID-ish)
+   **or a session name**: match it against the list above. Read the
+   matching session's `latest.md` from
+   `<project>/uv-out/checkpoints/<full-session-id>/latest.md` using the Read
+   tool, then summarize as in (1).
+
+4. If no match is found, list the available sessions and ask the user to
+   pick one.
+
+When summarizing, include the session's name and purpose from the
+frontmatter at the top of the checkpoint — that's the context the next
+session needs to know what it's picking up.