@vpxa/kb 0.1.15 → 0.1.17

package/skills/session-handoff/references/handoff-template.md

@@ -0,0 +1,139 @@
+# Handoff Template
+
+Use this template structure when creating handoff documents. The smart scaffold script will pre-fill metadata sections; complete the remaining sections based on session context.
+
+## Table of Contents
+
+- [Session Metadata](#session-metadata)
+- [Current State Summary](#current-state-summary)
+- [Codebase Understanding](#codebase-understanding)
+  - [Architecture Overview](#architecture-overview)
+  - [Critical Files](#critical-files)
+  - [Key Patterns Discovered](#key-patterns-discovered)
+- [Work Completed](#work-completed)
+  - [Tasks Finished](#tasks-finished)
+  - [Files Modified](#files-modified)
+  - [Decisions Made](#decisions-made)
+- [Pending Work](#pending-work)
+  - [Immediate Next Steps](#immediate-next-steps)
+  - [Blockers/Open Questions](#blockersopen-questions)
+  - [Deferred Items](#deferred-items)
+- [Context for Resuming Agent](#context-for-resuming-agent)
+  - [Important Context](#important-context)
+  - [Assumptions Made](#assumptions-made)
+  - [Potential Gotchas](#potential-gotchas)
+- [Environment State](#environment-state)
+- [Related Resources](#related-resources)
+- [Template Usage Notes](#template-usage-notes)
+
+---
+
+# Handoff: [TASK_TITLE]
+
+## Session Metadata
+- Created: [TIMESTAMP]
+- Project: [PROJECT_PATH]
+- Branch: [GIT_BRANCH]
+- Session duration: [APPROX_DURATION]
+
+## Current State Summary
+
+[One paragraph: What was being worked on, current status, and where things left off]
+
+## Codebase Understanding
+
+### Architecture Overview
+
+[Key architectural insights discovered during this session - how the system is structured, main components, data flow]
+
+### Critical Files
+
+| File | Purpose | Relevance |
+|------|---------|-----------|
+| path/to/file | What this file does | Why it matters for this task |
+
+### Key Patterns Discovered
+
+[Important patterns, conventions, or idioms found in this codebase that the next agent should follow]
+
+## Work Completed
+
+### Tasks Finished
+
+- [x] Task 1 - brief description of what was done
+- [x] Task 2 - brief description
+
+### Files Modified
+
+| File | Changes | Rationale |
+|------|---------|-----------|
+| path/to/file | Description of changes | Why this change was made |
+
+### Decisions Made
+
+| Decision | Options Considered | Rationale |
+|----------|-------------------|-----------|
+| Chose X over Y | X, Y, Z | Why X was chosen |
+
+## Pending Work
+
+### Immediate Next Steps
+
+1. [Most critical next action - what to do first]
+2. [Second priority]
+3. [Third priority]
+
+### Blockers/Open Questions
+
+- [ ] Blocker: [description] - Needs: [what's required to unblock]
+- [ ] Question: [unclear aspect] - Suggested: [potential resolution]
+
+### Deferred Items
+
+- Item 1 (deferred because: [reason, e.g., out of scope, needs user input])
+
+## Context for Resuming Agent
+
+### Important Context
+
+[Critical information the next agent MUST know to continue effectively - this is the most important section for handoff]
+
+### Assumptions Made
+
+- Assumption 1: [what was assumed to be true]
+- Assumption 2: [another assumption]
+
+### Potential Gotchas
+
+- [Things that might trip up a new agent - edge cases, quirks, non-obvious behavior]
+
+## Environment State
+
+### Tools/Services Used
+
+- [Tool/Service]: [relevant configuration or state]
+
+### Active Processes
+
+- [Any background processes, dev servers, watchers that may be running]
+
+### Environment Variables
+
+- [Key env vars that matter for this work - DO NOT include secrets/values, just names]
+
+## Related Resources
+
+- [Link to relevant documentation]
+- [Related file paths]
+- [External resources consulted]
+
+---
+
+## Template Usage Notes
+
+When filling this template:
+1. Be specific and concrete - vague descriptions don't help the next agent
+2. Include file paths with line numbers where relevant (e.g., `src/auth.ts:142`)
+3. Prioritize the "Important Context" and "Immediate Next Steps" sections
+4. Don't include sensitive data (API keys, passwords, tokens)
+5. Focus on WHAT and WHY, not just WHAT - rationale is crucial for handoffs

package/skills/session-handoff/references/resume-checklist.md

@@ -0,0 +1,80 @@
+# Resume Checklist
+
+Follow this checklist when resuming work from a handoff document to ensure zero-ambiguity continuation.
+
+## Pre-Resume Verification
+
+- [ ] Read the entire handoff document before taking any action
+- [ ] Verify you are in the correct project directory
+- [ ] Confirm the git branch matches (or understand why it might differ)
+- [ ] Check the handoff timestamp - how stale is this context?
+
+## Context Validation
+
+- [ ] Review "Important Context" section thoroughly
+- [ ] Understand all assumptions listed - are they still valid?
+- [ ] Check if any blockers have been resolved since handoff
+- [ ] Review "Potential Gotchas" to avoid known pitfalls
+
+## State Verification
+
+- [ ] Run `git status` to see current file state
+- [ ] Compare modified files list in handoff vs current state
+- [ ] Check if any environment variables need to be set
+- [ ] Verify any required services/processes are running
+
+## Resume Execution
+
+- [ ] Start with "Immediate Next Steps" item #1
+- [ ] Reference "Files Modified" table for context on recent changes
+- [ ] Apply patterns documented in "Key Patterns Discovered"
+- [ ] Follow architectural insights from "Architecture Overview"
+
+## During Work
+
+- [ ] Update handoff document if major new context is discovered
+- [ ] Mark completed items in "Pending Work" as you finish them
+- [ ] Add new blockers/questions as they arise
+- [ ] Consider creating a new handoff if session becomes long
+
+## Red Flags - Stop and Verify
+
+If you encounter any of these, pause and verify context before proceeding:
+
+1. **Files mentioned in handoff don't exist** - codebase may have changed significantly
+2. **Branch has diverged substantially** - check git log for recent commits
+3. **Assumptions are clearly invalid** - reassess the approach
+4. **Blockers marked as unresolved are now blocking you** - escalate to user
+5. **Architecture has changed** - re-explore before continuing
+
+## Quick Start Commands
+
+After reading the handoff, these commands help verify state:
+
+```bash
+# Check current branch and status
+git branch --show-current
+git status
+
+# See recent commits (compare with handoff)
+git log --oneline -10
+
+# Check for any running processes mentioned
+ps aux | grep [process-name]
+
+# Verify environment
+env | grep [relevant-var]
+```
+
+## Handoff Quality Assessment
+
+Rate the handoff quality to identify if more exploration is needed:
+
+| Aspect | Good | Needs Exploration |
+|--------|------|-------------------|
+| Next steps | Clear, actionable | Vague or missing |
+| File references | Specific paths/lines | General descriptions |
+| Decisions | Rationale included | Just outcomes |
+| Context | Complete picture | Gaps or assumptions |
+
+If multiple aspects "Need Exploration", spend time re-exploring the codebase before continuing implementation.

package/skills/session-handoff/scripts/check_staleness.js

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+/**
+ * Check staleness of a handoff document compared to current project state.
+ *
+ * Analyzes:
+ * - Time since handoff was created
+ * - Git commits since handoff
+ * - Files that changed since handoff
+ * - Branch divergence
+ * - Modified files status
+ *
+ * Usage:
+ *   node check_staleness.js <handoff-file>
+ *   node check_staleness.js .handoffs/2024-01-15-143022-auth.md
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execSync } = require('node:child_process');
+
+function _die(msg) {
+  process.stderr.write(`${msg}\n`);
+  process.exit(1);
+}
+
+function runCmd(cmd, cwd) {
+  try {
+    return { ok: true, out: execSync(cmd, { cwd, timeout: 10_000, encoding: 'utf-8' }).trim() };
+  } catch {
+    return { ok: false, out: '' };
+  }
+}
+
+function parseHandoffMetadata(filepath) {
+  const content = fs.readFileSync(filepath, 'utf-8');
+  const meta = { created: null, branch: null, projectPath: null, modifiedFiles: [] };
+
+  const createdMatch = content.match(/Created:\s*(\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2})/);
+  if (createdMatch) meta.created = new Date(createdMatch[1].replace(' ', 'T'));
+
+  const branchMatch = content.match(/Branch:\s*(\S+)/);
+  if (branchMatch && !branchMatch[1].startsWith('[')) meta.branch = branchMatch[1];
+
+  const projMatch = content.match(/Project:\s*(.+?)(?:\n|$)/);
+  if (projMatch) meta.projectPath = projMatch[1].trim();
+
+  const fileMatches = content.matchAll(/\|\s*([a-zA-Z0-9_\-./]+\.[a-zA-Z]+)\s*\|/g);
+  for (const m of fileMatches) {
+    if (m[1].includes('/') && !m[1].startsWith('[')) meta.modifiedFiles.push(m[1]);
+  }
+
+  return meta;
+}
+
+function getCommitsSince(timestamp, cwd) {
+  if (!timestamp) return [];
+  const iso = timestamp.toISOString();
+  const { ok, out } = runCmd(`git log --since="${iso}" --oneline --no-decorate`, cwd);
+  return ok && out ? out.split('\n') : [];
+}
+
+function getChangedFilesSince(timestamp, cwd) {
+  if (!timestamp) return [];
+  const iso = timestamp.toISOString();
+  const { ok, out } = runCmd(`git log --since="${iso}" --name-only --pretty=format:`, cwd);
+  if (ok && out) {
+    return [
+      ...new Set(
+        out
+          .split('\n')
+          .map((f) => f.trim())
+          .filter(Boolean),
+      ),
+    ];
+  }
+  return [];
+}
+
+function checkFilesExist(files, cwd) {
+  const existing = [];
+  const missing = [];
+  for (const f of files) {
+    if (fs.existsSync(path.join(cwd, f))) existing.push(f);
+    else missing.push(f);
+  }
+  return { existing, missing };
+}
+
+function calculateStaleness(daysOld, commitsSince, filesChanged, branchMatches, filesMissing) {
+  const issues = [];
+  let score = 0;
+
+  if (daysOld > 30) {
+    score += 3;
+    issues.push(`Handoff is ${Math.floor(daysOld)} days old`);
+  } else if (daysOld > 7) {
+    score += 2;
+    issues.push(`Handoff is ${Math.floor(daysOld)} days old`);
+  } else if (daysOld > 1) {
+    score += 1;
+  }
+
+  if (commitsSince > 50) {
+    score += 3;
+    issues.push(`${commitsSince} commits since handoff - significant changes`);
+  } else if (commitsSince > 20) {
+    score += 2;
+    issues.push(`${commitsSince} commits since handoff`);
+  } else if (commitsSince > 5) {
+    score += 1;
+  }
+
+  if (!branchMatches) {
+    score += 2;
+    issues.push('Current branch differs from handoff branch');
+  }
+
+  if (filesMissing > 5) {
+    score += 2;
+    issues.push(`${filesMissing} referenced files no longer exist`);
+  } else if (filesMissing > 0) {
+    score += 1;
+    issues.push(`${filesMissing} referenced file(s) missing`);
+  }
+
+  if (filesChanged > 20) {
+    score += 2;
+    issues.push(`${filesChanged} files changed since handoff`);
+  } else if (filesChanged > 5) {
+    score += 1;
+  }
+
+  let level, recommendation;
+  if (score === 0) {
+    level = 'FRESH';
+    recommendation = 'Safe to resume - minimal changes since handoff';
+  } else if (score <= 2) {
+    level = 'SLIGHTLY_STALE';
+    recommendation = 'Generally safe to resume - review changes before continuing';
+  } else if (score <= 4) {
+    level = 'STALE';
+    recommendation = 'Proceed with caution - significant changes may affect context';
+  } else {
+    level = 'VERY_STALE';
+    recommendation = 'Consider creating new handoff - too many changes since original';
+  }
+
+  return { level, recommendation, issues };
+}
+
+function checkStaleness(handoffPath) {
+  if (!fs.existsSync(handoffPath)) return { error: `Handoff file not found: ${handoffPath}` };
+
+  const meta = parseHandoffMetadata(handoffPath);
+  const projectPath =
+    meta.projectPath && fs.existsSync(meta.projectPath)
+      ? meta.projectPath
+      : path.resolve(path.dirname(handoffPath), '..'); // Up from .handoffs/
+
+  const isGitRepo = runCmd('git rev-parse --git-dir', projectPath).ok;
+
+  const result = {
+    handoffFile: handoffPath,
+    projectPath,
+    isGitRepo,
+    created: meta.created,
+    handoffBranch: meta.branch,
+  };
+
+  if (meta.created) {
+    const age = Date.now() - meta.created.getTime();
+    result.daysOld = age / 86_400_000;
+    result.hoursOld = age / 3_600_000;
+  }
+
+  if (isGitRepo) {
+    const { out: currentBranch } = runCmd('git branch --show-current', projectPath);
+    result.currentBranch = currentBranch;
+    result.branchMatches = meta.branch ? currentBranch === meta.branch : true;
+
+    const commits = getCommitsSince(meta.created, projectPath);
+    result.commitsSince = commits.length;
+    result.recentCommits = commits.slice(0, 5);
+
+    const changedFiles = getChangedFilesSince(meta.created, projectPath);
+    result.filesChangedCount = changedFiles.length;
+    result.filesChanged = changedFiles.slice(0, 10);
+
+    const { existing, missing } = checkFilesExist(meta.modifiedFiles, projectPath);
+    result.referencedFilesExist = existing.length;
+    result.referencedFilesMissing = missing;
+
+    const { level, recommendation, issues } = calculateStaleness(
+      result.daysOld || 0,
+      result.commitsSince,
+      result.filesChangedCount,
+      result.branchMatches,
+      missing.length,
+    );
+    result.stalenessLevel = level;
+    result.recommendation = recommendation;
+    result.issues = issues;
+  } else {
+    result.stalenessLevel = 'UNKNOWN';
+    result.recommendation = 'Not a git repo - unable to detect changes';
+    result.issues = ['Project is not a git repository'];
+  }
+
+  return result;
+}
+
+function printReport(result) {
+  if (result.error) {
+    console.log(`Error: ${result.error}`);
+    return;
+  }
+
+  console.log(`\n${'='.repeat(60)}`);
+  console.log('Handoff Staleness Report');
+  console.log('='.repeat(60));
+  console.log(`File: ${result.handoffFile}`);
+  console.log(`Project: ${result.projectPath}`);
+
+  if (result.created) {
+    console.log(`Created: ${result.created.toISOString().replace('T', ' ').slice(0, 19)}`);
+    if (result.daysOld != null) {
+      console.log(
+        result.daysOld < 1
+          ? `Age: ${result.hoursOld.toFixed(1)} hours`
+          : `Age: ${result.daysOld.toFixed(1)} days`,
+      );
+    }
+  }
+
+  console.log(`\nStaleness: ${result.stalenessLevel}`);
+  console.log(`Recommendation: ${result.recommendation}`);
+
+  if (result.issues && result.issues.length > 0) {
+    console.log('\nIssues:');
+    for (const issue of result.issues) console.log(`  - ${issue}`);
+  }
+
+  if (result.isGitRepo) {
+    console.log(
+      `\nBranch: ${result.currentBranch || 'detached'}${result.branchMatches ? ' (matches handoff)' : ` (handoff: ${result.handoffBranch})`}`,
+    );
+    console.log(`Commits since handoff: ${result.commitsSince}`);
+    console.log(`Files changed since handoff: ${result.filesChangedCount}`);
+    if (result.referencedFilesMissing.length > 0) {
+      console.log(`Missing referenced files: ${result.referencedFilesMissing.join(', ')}`);
+    }
+  }
+}
+
+// --- Main ---
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h') || args.length === 0) {
+  console.log('Usage: node check_staleness.js <handoff-file>');
+  console.log('       node check_staleness.js .handoffs/2024-01-15-143022-auth.md');
+  process.exit(args.length === 0 ? 1 : 0);
+}
+
+if (args.includes('--json')) {
+  const result = checkStaleness(args.find((a) => !a.startsWith('-')));
+  console.log(JSON.stringify(result, null, 2));
+} else {
+  const result = checkStaleness(args[0]);
+  printReport(result);
+}