session-ecosystem-audit

name	session-ecosystem-audit
description	Comprehensive diagnostic of the Session Ecosystem — 17 categories across 5 domains with composite health scoring, trend tracking, patch suggestions, and interactive finding-by-finding walkthrough. Covers session lifecycle hooks, state persistence, compaction resilience layers, cross-session safety, and integration configuration.

Document Version: 1.0 Last Updated: 2026-02-23 Status: ACTIVE

Session Ecosystem Audit

Deep diagnostic of the entire Session Ecosystem — lifecycle skills (session-begin, session-end, checkpoint, alerts), hooks (session-start.js, commit-tracker.js, pre-compaction-save.js, compact-restore.js, compaction-handoff.js), state files (handoff.json, commit-log.jsonl, session-notes.json), and the 4-layer compaction resilience system. Produces per-category scores, a composite health grade (A-F), trend tracking across runs, and an interactive walkthrough with patch suggestions.

Invocation: /session-ecosystem-audit

When to use: When you want to understand the overall health of the session management system, identify gaps in lifecycle coverage, validate compaction resilience layers, check cross-session safety invariants, or verify hook registration alignment. Complementary with /hook-ecosystem-audit (that skill audits ALL hooks; this skill audits the SESSION SYSTEM specifically).

---

When to Use

• Tasks related to session-ecosystem-audit
• User explicitly invokes /session-ecosystem-audit

When NOT to Use

• When the task doesn't match this skill's scope -- check related skills
• When a more specialized skill exists for the specific task

CRITICAL RULES (Read First)

Read .claude/skills/_shared/ecosystem-audit/CRITICAL_RULES.md and follow all 8 rules. The rules below are summaries — the shared file is authoritative.

1. CHECK for saved progress first (MUST)
2. ALWAYS run the script first (MUST)
3. ALWAYS display the dashboard (MUST)
4. Use conversational Q&A for decisions (MUST) — NEVER use AskUserQuestion
5. SAVE progress after every decision (MUST)
6. Show patch suggestions inline (SHOULD)
7. Create TDMS entries (MUST) for deferred findings
8. Save decisions (MUST) to session log

---

Compaction Guard

Read .claude/skills/_shared/ecosystem-audit/COMPACTION_GUARD.md for the full compaction guard protocol (state file schema, resume, save, cleanup).

State file path: .claude/tmp/session-audit-progress.json

---

Phase 1: Run & Parse

1. Run the audit script:

node .claude/skills/session-ecosystem-audit/scripts/run-session-ecosystem-audit.js

2. Parse the v2 JSON output from stdout (progress goes to stderr).

3. Create a session decision log file:

   • Path: .claude/tmp/session-audit-session-{YYYY-MM-DD-HHMM}.jsonl
   • Create .claude/tmp/ directory if it doesn't exist

4. Save initial progress state to .claude/tmp/session-audit-progress.json with currentFindingIndex: 0, the full findings data, score, and grade.

---

Phase 2: Dashboard Overview (compact)

Present a compact header with composite grade and domain breakdown:

Session Ecosystem Health: {grade} ({score}/100)  |  Trend: {sparkline} ({delta})
{errors} errors · {warnings} warnings · {info} info  |  {patches} patch suggestions

┌──────────────────────────────────┬───────┬──────────┬──────────────┐
│ Category                         │ Score │ Rating   │ Trend        │
├──────────────────────────────────┼───────┼──────────┼──────────────┤
│ D1: Session Lifecycle Mgmt       │       │          │              │
│   Session Begin Completeness     │  {s}  │ {rating} │ {trend}      │
│   Session End Completeness       │  {s}  │ {rating} │ {trend}      │
│   Session Counter Accuracy       │  {s}  │ {rating} │ {trend}      │
│   Session Documentation Freshness│  {s}  │ {rating} │ {trend}      │
│   Passive Surfacing Compliance   │  {s}  │ {rating} │ {trend}      │
├──────────────────────────────────┼───────┼──────────┼──────────────┤
│ D2: State Persistence & Handoff  │       │          │              │
│   Handoff File Schema            │  {s}  │ {rating} │ {trend}      │
│   Commit Log Integrity           │  {s}  │ {rating} │ {trend}      │
│   Task State File Health         │  {s}  │ {rating} │ {trend}      │
│   Session Notes Quality          │  {s}  │ {rating} │ {trend}      │
├──────────────────────────────────┼───────┼──────────┼──────────────┤
│ D3: Compaction Resilience        │       │          │              │
│   Layer A: Commit Tracker        │  {s}  │ {rating} │ {trend}      │
│   Layer C: Pre-Compaction Save   │  {s}  │ {rating} │ {trend}      │
│   Layer D: Gap Detection         │  {s}  │ {rating} │ {trend}      │
│   Restore Output Quality         │  {s}  │ {rating} │ {trend}      │
├──────────────────────────────────┼───────┼──────────┼──────────────┤
│ D4: Cross-Session Safety         │       │          │              │
│   Begin/End Balance              │  {s}  │ {rating} │ {trend}      │
│   Multi-Session Validation       │  {s}  │ {rating} │ {trend}      │
├──────────────────────────────────┼───────┼──────────┼──────────────┤
│ D5: Integration & Configuration  │       │          │              │
│   Hook Registration Alignment    │  {s}  │ {rating} │ {trend}      │
│   State File Management          │  {s}  │ {rating} │ {trend}      │
└──────────────────────────────────┴───────┴──────────┴──────────────┘

Rating badges: good = "Good", average = "Avg", poor = "Poor"

Then say: "Found N findings to review. Walking through each one (impact-weighted)..."

---

Phase 3: Finding-by-Finding Walkthrough

Read .claude/skills/_shared/ecosystem-audit/FINDING_WALKTHROUGH.md for the full walkthrough protocol (finding card, decisions, patches, delegation, batching).

Sort findings by impactScore descending (highest impact first). DEBT entries use source_id: review:session-ecosystem-audit-{date}.

---

Phase 4: Summary & Actions

Read .claude/skills/_shared/ecosystem-audit/SUMMARY_AND_TRENDS.md for the summary template, trend report template, and verification re-run template.

Write report to .claude/tmp/session-audit-report-{YYYY-MM-DD}.md.

Process verification: Run __tests__/ suite:

node --test .claude/skills/session-ecosystem-audit/scripts/__tests__/*.test.js

---

Phase 5: Trend Report (if previous runs exist)

Uses trend report template from SUMMARY_AND_TRENDS.md.

History: .claude/state/session-ecosystem-audit-history.jsonl

---

Category Reference

Domain 1: Session Lifecycle Management (20% weight)

Category	What It Checks
Session Begin Completeness	All /session-begin sections backed by scripts/npm commands that exist
Session End Completeness	All /session-end sections backed by scripts/npm commands that exist
Session Counter Accuracy	SESSION_CONTEXT.md counter matches commit-log.jsonl session numbers
Session Documentation Freshness	SESSION_CONTEXT.md within limits: line count, staleness, section quality
Passive Surfacing Compliance	Warnings have action paths, HIGH→state flags, MEDIUM→JSONL, no wallpaper

Domain 2: State Persistence & Handoff (25% weight)

Category	What It Checks
Handoff File Schema	handoff.json has all 11 required fields + gitState sub-fields
Commit Log Integrity	commit-log.jsonl entries valid JSON, required fields, file size managed
Task State File Health	task-*.state.json files valid JSON, no orphaned completed tasks
Session Notes Quality	session-notes.json valid, entries have timestamps/text, no stale entries

Domain 3: Compaction Resilience (20% weight)

Category	What It Checks
Layer A: Commit Tracker	commit-tracker.js registered, Bash matcher, file exists, content OK
Layer C: Pre-Compaction Save	pre-compaction-save.js registered, captures key state fields
Layer D: Gap Detection	check-session-gaps.js exists, npm script, reads commit-log + context
Restore Output Quality	compact-restore.js registered with "compact" matcher, reads handoff

Domain 4: Cross-Session Safety (15% weight)

Category	What It Checks
Begin/End Balance	Session begin count matches end count in .session-state.json
Multi-Session Validation	session-start.js has validation logic, SESSION_CONTEXT.md current

Domain 5: Integration & Configuration (20% weight)

Category	What It Checks
Hook Registration Alignment	7 expected session hooks registered in settings.json + files exist
State File Management	.claude/state/ gitignored, no oversized files, tmp cleanup

---

Benchmarks & Checker Development

Read .claude/skills/_shared/ecosystem-audit/CLOSURE_AND_GUARDRAILS.md for scoring conventions and the checker development guide.

17 categories. Domain weights: D1=20%, D2=25%, D3=20%, D4=15%, D5=20%.

Data Sources

Source	Path	Content
Session skills	.claude/skills/session-*/SKILL.md	Session begin, end, checkpoint, alerts
Session hooks	.claude/hooks/session-start.js	SessionStart event handler
Commit tracker	.claude/hooks/commit-tracker.js	PostToolUse commit logger
Pre-compact save	.claude/hooks/pre-compaction-save.js	PreCompact state snapshot
Compact restore	.claude/hooks/compact-restore.js	SessionStart:compact recovery
Compaction handoff	.claude/hooks/compaction-handoff.js	PreCompact handoff writer
Handoff state	.claude/state/handoff.json	Last compaction state snapshot
Commit log	.claude/state/commit-log.jsonl	Historical commit records
Session state	.claude/hooks/.session-state.json	Begin/end counters and timestamps
Session notes	.claude/state/session-notes.json	AI-written session context notes
Task states	.claude/state/task-*.state.json	In-progress task snapshots
Gap detector	scripts/check-session-gaps.js	Layer D gap detection
Settings	.claude/settings.json	Hook registrations
SESSION_CONTEXT	SESSION_CONTEXT.md	Current session counter and status

Compaction Resilience Architecture

Layer A: commit-tracker.js (PostToolUse: Bash)
  → Logs every commit to .claude/state/commit-log.jsonl
  → Survives compaction (persistent file)

Layer C: pre-compaction-save.js (PreCompact)
  → Captures full state snapshot to .claude/state/handoff.json
  → Includes: git state, task states, commit log, agents, active plan

Layer D: check-session-gaps.js (session-begin script)
  → Detects undocumented sessions by comparing commit-log vs SESSION_CONTEXT.md
  → Runs at session start to catch missed session-ends

Restore: compact-restore.js (SessionStart: compact)
  → Reads handoff.json after compaction
  → Outputs recovery context to stdout for Claude to read

---

Version History

Version	Date	Description
1.2	2026-03-25	Extract shared patterns to _shared/ecosystem-audit/
1.1	2026-02-24	Add compaction guard for progress persistence
1.0	2026-02-23	Initial implementation