GITHUB-ISSUES-2026-03-22-session-end-fix.md

Created: 2026-03-22 Purpose: File new bug for broken session-end implementation and build the stopgap skill.

Context

#342 was closed by PR #345 but the fix is incomplete. The SessionEnd hook can only run shell commands with a 1.5-second timeout — it cannot generate prose content. PR #345 built only a git-commit safety net, not the actual session state writer.

The real fix ships with the documentation feature (Tasks 1-12) which decides where ai-sessions lives. Until then, a manual session-end skill is the stopgap.

Rules for Harley

Run operations one at a time in the order listed
Confirm each result before moving to the next
Do not modify operation content
Report any failures to operator immediately
Stop after all operations are complete — no other work

Operation 1 — File new bug

gh issue create --title "fix: session-end hook does not generate session state — only commits" --label "bug" --body "## Problem

PR #345 (closing #342) built a SessionEnd hook that only auto-commits existing changes to ai-sessions/. It does not generate any content. CURRENT-CODE.md is never written. No immutable log is created. The hook is a no-op if nothing else writes the files first.

## Root cause

The original spec for #342 (written by Joker) was wrong. It treated the SessionEnd hook as if it could generate prose content. It cannot:
- SessionEnd hooks have a 1.5-second default timeout
- They can only run shell commands
- They cannot invoke Claude to think and write summaries

The spec conflated two different jobs:
1. **Generating session state** (requires Claude to think — cannot be a hook)
2. **Committing session state** (mechanical — can be a hook)

PR #345 built job 2 correctly. Job 1 was never built.

## Stopgap fix (this issue)

Build a session-end skill at .claude/skills/session-end/SKILL.md that Harley runs manually before /exit. The skill tells Harley to:

1. Write ai-sessions/CURRENT-CODE.md with real session state:
   - Current branch and version
   - What was done this session
   - What is working / not working
   - Open PRs and top open issues
   - Decisions made
   - Next steps and watch-out-fors
2. Write an immutable log to ai-sessions/logs/ with filename format:
   v[X].[X].[X]-[YYYY]-[MM]-[DD]-[HHMM]-code-[operator].md
3. Commit both files

The existing SessionEnd hook stays as-is — it is the safety net that auto-commits if Harley forgets to commit after running the skill.

## Permanent fix

Blocked by documentation feature (Tasks 1-12). Once ai-sessions moves to its own repo or dedicated location, the session-end flow can be properly automated. The skill remains the content generator; the hook remains the commit safety net.

## Acceptance criteria

- [ ] .claude/skills/session-end/SKILL.md exists in the scaffolder project
- [ ] .claude/skills/session-end/SKILL.md also exists in templates/ so sc create generates it for new projects
- [ ] Skill writes CURRENT-CODE.md with all required fields
- [ ] Skill writes immutable log with correct filename format
- [ ] Skill commits both files
- [ ] Existing SessionEnd hook unchanged (safety net)
- [ ] session-start skill references the session-end skill so Harley knows it exists

## References

- #342 — original issue (closed by PR #345, fix incomplete)
- PR #345 — the hook-only fix
- Claude Code hooks docs: SessionEnd has 1.5s timeout, shell commands only
- .claude/skills/session-start/SKILL.md — model for how skills work in this project"

Operation 2 — Build the session-end skill

Branch: fix/session-end-skill

git checkout dev && git pull origin dev
git checkout -b fix/session-end-skill
Create .claude/skills/session-end/SKILL.md with this exact content:

---
name: session-end
description: "Run this skill before ending a session with /exit. Writes session state to CURRENT-CODE.md and creates an immutable session log. The SessionEnd hook will auto-commit these files as a safety net, but always commit manually after running this skill."
---

# Session End

Run this skill before ending your session. Do NOT rely on the SessionEnd hook to generate content — it can only commit files, not write them.

## Steps

1. Write `ai-sessions/CURRENT-CODE.md` with this structure:

CURRENT-CODE.md

Branch

[current branch name]

Version

[current version from package.json or last known]

Last session — [YYYY-MM-DD]

[Bullet list of what was actually done this session]

What is working

[List what’s confirmed working]

What is not working

[List what’s known broken or incomplete]

Open PRs

[List any open PRs, or “None”]

Open issues (top)

[Top 5 open issues from: gh issue list —state open —limit 5]

Decisions made

[Any decisions made during this session]

Next steps

[What should happen next session]

Watch out for

[Anything the next session needs to be careful about]

2. Write an immutable log to `ai-sessions/logs/` with filename:
   `v[VERSION]-[YYYY]-[MM]-[DD]-[HHMM]-code-purls.md`

   The log contains the same content as CURRENT-CODE.md plus a session summary header.

3. `git add ai-sessions/CURRENT-CODE.md ai-sessions/logs/`
4. `git commit -m "chore: update session state"`

## Important

- Run this BEFORE `/exit`, not after
- The SessionEnd hook in .claude/settings.json is a safety net only — it auto-commits if you forget
- If you're on a feature branch, that's fine — commit session files there. They're gitignored from PRs.

Copy the skill to templates so sc create generates it for new projects:
- Ensure templates/.claude/skills/session-end/SKILL.md exists with the same content
Update .claude/skills/session-start/SKILL.md — add to the end, before the Fallback section:

## Reminder
Before ending this session, run the **session-end** skill to persist your state.
The SessionEnd hook only commits — it does not generate content.

Commit: fix: add session-end skill for manual state persistence (see #[NEW_ISSUE_NUMBER])
Push and create PR to dev

Operation 3 — Delete stale branch

gh api -X DELETE repos/purlshq/scaffolder/git/refs/heads/hotfix/gitignore-operator-files