gse-pause

name	gse-pause
description	Auto-commit work, save session checkpoint. Triggered by /gse:pause.

GSE-One Pause — Session Pause

Arguments: $ARGUMENTS

Options

Flag / Sub-command	Description
(no args)	Auto-commit all active worktrees and save checkpoint
--no-commit	Save checkpoint without auto-committing
--note "text"	Attach a note to the checkpoint (context for future resume)
--help	Show this command's usage summary

Prerequisites

Before executing, read:

1. .gse/status.yaml — current sprint and lifecycle state
2. .gse/config.yaml — git strategy
3. .gse/backlog.yaml — active tasks and their worktree assignments

Workflow

Step 1 — Auto-Commit Active Worktrees

Unless --no-commit was specified:

For each TASK in backlog.yaml with git.worktree_status: active:

1. Navigate to the worktree directory: .worktrees/{worktree_name}
2. Check for uncommitted changes: git status --porcelain
3. If changes exist:

   git add -A
   git commit -m "gse(pause): checkpoint — {task_title}
   
   Sprint: S{NN}
   Task: TASK-{ID}
   Reason: session pause
   "
   

4. Update TASK in backlog.yaml:
   • git.uncommitted_changes: 0
   • git.last_commit: {now ISO 8601}

If no worktrees are active (strategy is branch-only or none):

1. Check current branch for uncommitted changes
2. If changes exist, auto-commit with the same convention

Commit failure handling (applies to the worktree loop and the current-branch fallback alike): if a commit is blocked by a guardrail hook (exit 2 — e.g., the protect-main hook when the current branch is main under branch-only strategy) or fails for any other reason (user pre-commit hooks, git errors), do NOT proceed silently. Present the Pause Commit Gate:

Question: I could not commit your uncommitted changes on {branch} ({reason}). How should I secure them before pausing?

Options:

1. Rescue branch (recommended, default) — create gse/pause-rescue-{YYYY-MM-DD-HHMM} from the current branch and commit the changes there. Protects the work without touching main and without weakening any guardrail.
2. Sanctioned override — commit on the current branch after setting hooks.protect_main: false in .gse/config.yaml (the hook's own sanctioned exception). Only if you deliberately work directly on main.
3. Checkpoint without commit — save the checkpoint and leave the changes uncommitted in the working tree. An explicit WARNING is recorded (Step 4 report + checkpoint note) so /gse:resume surfaces it.
4. Discuss — explore the options.

A refused or failed commit is NEVER counted in the "Auto-committed {N}" figure.

Report: "Auto-committed {N} worktree(s) with changes." — if any location was left uncommitted (Gate option 3, or --no-commit with a dirty state), report instead: "Auto-committed {N}; ⚠ {M} location(s) left with uncommitted changes."

Step 2 — Save Checkpoint

Create a checkpoint file at .gse/checkpoints/checkpoint-{YYYY-MM-DD-HHMM}.yaml using the checkpoint.yaml template (plugin/templates/checkpoint.yaml — authoritative schema). Populate all fields from the current session state:

• timestamp: ISO 8601 current time (flat top-level field per checkpoint.yaml schema)
• user: from profile.yaml → user.name
• last_task: current TASK from session context (e.g., task the user was producing)
• note: from --note flag if provided, else empty
• status_snapshot: extract current_phase, current_sprint, last_activity, last_activity_timestamp, health.score from status.yaml
• backlog_sprint_snapshot.tasks: for each TASK in current sprint, record status, complexity, branch
• git_state.current_branch: from git branch --show-current
• git_state.head: from git rev-parse HEAD (verification anchor for /gse:resume when no worktrees exist)
• git_state.clean: from git status --porcelain on the current branch (false if uncommitted changes remain)
• git_state.worktrees[]: from git worktree list, for each: path, branch, task (from backlog), last_commit (HEAD hash), clean (from git status)

If Step 1 left uncommitted changes anywhere (Pause Commit Gate option 3, or --no-commit with a dirty state), append to note: WARNING: uncommitted changes left on {branch} (commit blocked/skipped at pause) — /gse:resume Step 4 displays checkpoint notes, so the warning resurfaces at resume time.

Step 3 — Update Status

1. Update status.yaml session state only:
   • session_paused: true
   • pause_checkpoint: checkpoint-{YYYY-MM-DD-HHMM}.yaml
   • (Cursor fields last_activity, last_activity_timestamp are maintained centrally by the orchestrator after the activity closes — see plugin/agents/gse-orchestrator.md — section "Sprint Plan Maintenance", and gse-one-implementation-design.md §10.1 — Sprint Plan Lifecycle (v0.53.0). PAUSE writes no cursor fields directly.)

Step 3.5 — Coach End-of-Session Check (sustainability + engagement)

After the checkpoint is saved and status updated, the orchestrator invokes the coach agent with moment: /gse:pause (per coach.md Invocation contract, design §5.17). The coach activates axes 2–8 (workflow axes) to surface end-of-session observations — particularly the sustainability axis (detecting long session durations, sprint point totals vs spec §8 guidance) and the engagement_pattern axis (accepting defaults without pushback over the session). Coach outputs (bounded by config.yaml → coach.max_advice_per_check, default 3) are included in the pause report (Step 4). If nothing meaningful surfaces, this step is silent.

Step 4 — Report

SESSION PAUSED
  Checkpoint: .gse/checkpoints/checkpoint-{YYYY-MM-DD-HHMM}.yaml
  Auto-committed: {N} worktree(s)
  {if uncommitted changes remain}:
  ⚠ WARNING: uncommitted changes remain on {branch} — NOT committed.
    They stay in your working tree and will be surfaced again by /gse:resume.
  Sprint: S{NN} ({current_phase})
  Active tasks: {count}
  
  Resume with: /gse:resume