@vpxa/aikit 0.1.214 → 0.1.216

package/scaffold/dist/definitions/skills/session-handoff.mjs

@@ -1,1304 +1,616 @@
 var e=[{file:`references/handoff-template.md`,content:`# 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.
-
+Use this template.
 ## 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)
-
+Use headings
 ---
-
 # 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]
-
+[One paragraph: work, status, handoff point]
 ## Codebase Understanding
-
 ### Architecture Overview
-
-[Key architectural insights discovered during this session - how the system is structured, main components, data flow]
-
+[Key architecture insights]
 ### Critical Files
-
 | File | Purpose | Relevance |
 |------|---------|-----------|
-| path/to/file | What this file does | Why it matters for this task |
-
+| path/to/file | Purpose | Why it matters now |
 ### Key Patterns Discovered
-
-[Important patterns, conventions, or idioms found in this codebase that the next agent should follow]
-
+[Patterns next agent should follow]
 ## Work Completed
-
 ### Tasks Finished
-
-- [x] Task 1 - brief description of what was done
+- [x] Task 1 - what was done
 - [x] Task 2 - brief description
-
 ### Files Modified
-
 | File | Changes | Rationale |
 |------|---------|-----------|
-| path/to/file | Description of changes | Why this change was made |
-
+| path/to/file | Changes | Why |
 ### Decisions Made
-
 | Decision | Options Considered | Rationale |
 |----------|-------------------|-----------|
-| Chose X over Y | X, Y, Z | Why X was chosen |
-
+| Chose X over Y | X, Y, Z | Why |
 ## Pending Work
-
 ### Immediate Next Steps
-
-1. [Most critical next action - what to do first]
-2. [Second priority]
-3. [Third priority]
-
+1. [First action]
+2. [Second action]
+3. [Third action]
 ### Blockers/Open Questions
-
-- [ ] Blocker: [description] - Needs: [what's required to unblock]
-- [ ] Question: [unclear aspect] - Suggested: [potential resolution]
-
+- [ ] Blocker: [description] - Needs: [unblocker]
+- [ ] Question: [unclear aspect] - Suggested: [resolution]
 ### Deferred Items
-
-- Item 1 (deferred because: [reason, e.g., out of scope, needs user input])
-
+- Item 1 (deferred: [reason])
 ## Context for Resuming Agent
-
 ### Important Context
-
-[Critical information the next agent MUST know to continue effectively - this is the most important section for handoff]
-
+[Critical information next agent MUST know]
 ### Assumptions Made
-
-- Assumption 1: [what was assumed to be true]
+- Assumption 1: [assumed true]
 - Assumption 2: [another assumption]
-
 ### Potential Gotchas
-
-- [Things that might trip up a new agent - edge cases, quirks, non-obvious behavior]
-
+- [Things that might trip up next agent]
 ## Environment State
-
 ### Tools/Services Used
-
-- [Tool/Service]: [relevant configuration or state]
-
+- [Tool/Service]: [relevant state]
 ### Active Processes
-
-- [Any background processes, dev servers, watchers that may be running]
-
+- [Background processes, dev servers, watchers]
 ### Environment Variables
-
-- [Key env vars that matter for this work - DO NOT include secrets/values, just names]
-
+- [Env vars that matter - names only, no values]
 ## Related Resources
-
-- [Link to relevant documentation]
+- [Relevant docs]
 - [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
+Be specific. Use file refs when useful. Exclude secrets. Capture WHAT and WHY.
 `},{file:`references/resume-checklist.md`,content:`# Resume Checklist
-
-Follow this checklist when resuming work from a handoff document to ensure zero-ambiguity continuation.
-
+On resume.
 ## 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?
-
+- [ ] Read handoff before acting
+- [ ] Verify project directory
+- [ ] Confirm branch matches or note why it differs
+- [ ] Check handoff timestamp
 ## 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
-
+- [ ] Review important context
+- [ ] Check assumptions
+- [ ] Check resolved blockers
+- [ ] Review gotchas
 ## 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
-
+- [ ] Run \`git status\`
+- [ ] Compare modified files vs current state
+- [ ] Check required env vars
+- [ ] Verify required services/processes
 ## 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"
-
+- [ ] Start with next step #1
+- [ ] Apply documented patterns
 ## 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
-
+- [ ] Update handoff if major context changes
+- [ ] Add new blockers/questions
 ## 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
-
+1. **Files mentioned in handoff don't exist** - codebase may have changed
+2. **Branch has diverged substantially** - check git log
+3. **Assumptions are clearly invalid** - reassess
+4. **Unresolved blockers are still blocking you** - escalate
+5. **Architecture has changed** - re-explore
 ## 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.
+Re-explore if weak.
 `},{file:`scripts/check_staleness.js`,content:`#!/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 .aikit-state/handoffs/add-auth/2024-01-15-143022-auth.md
- *   node check_staleness.js .aikit-state/handoffs/_standalone/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: '' };
-  }
-}
-
+const runCmd = (cmd, cwd) => {
+try { return { ok: true, out: execSync(cmd, { cwd, timeout: 10000, 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 [];
+const content = fs.readFileSync(filepath, "utf-8");
+const meta = { created: null, branch: null, projectPath: null, modifiedFiles: [] };
+const created = content.match(/Created:\\s*(\\d{4}-\\d{2}-\\d{2}\\s+\\d{2}:\\d{2}:\\d{2})/);
+if (created) meta.created = new Date(created[1].replace(" ", "T"));
+const branch = content.match(/Branch:\\s*(\\S+)/);
+if (branch && !branch[1].startsWith("[")) meta.branch = branch[1];
+const proj = content.match(/Project:\\s*(.+?)(?:\\n|$)/);
+if (proj) meta.projectPath = proj[1].trim();
+for (const match of content.matchAll(/\\|\\s*([a-zA-Z0-9_\\-./]+\\.[a-zA-Z]+)\\s*\\|/g)) {
+if (match[1].includes("/") && !match[1].startsWith("[")) meta.modifiedFiles.push(match[1]);
+}
+return meta;
+}
+const getCommitsSince = (ts, cwd) => !ts ? [] : ((r) => r.ok && r.out ? r.out.split("\\n") : [])(runCmd("git log --since=\\"" + ts.toISOString() + "\\" --oneline --no-decorate", cwd));
+function getChangedFilesSince(ts, cwd) {
+if (!ts) return [];
+const result = runCmd("git log --since=\\"" + ts.toISOString() + "\\" --name-only --pretty=format:", cwd);
+return result.ok && result.out ? [...new Set(result.out.split("\\n").map((f) => f.trim()).filter(Boolean))] : [];
 }
-
 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 };
+const existing = []; const missing = [];
+for (const file of files) (fs.existsSync(path.join(cwd, file)) ? existing : missing).push(file);
+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 };
+const issues = []; let score = 0;
+if (daysOld > 30) { score += 3; issues.push("Handoff is " + Math.floor(daysOld) + "d old"); }
+else if (daysOld > 7) { score += 2; issues.push("Handoff is " + Math.floor(daysOld) + "d 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;
+if (score === 0) return { level: "FRESH", recommendation: "Safe to resume - minimal change", issues };
+if (score <= 2) return { level: "SLIGHTLY_STALE", recommendation: "Generally safe - review changes", issues };
+if (score <= 4) return { level: "STALE", recommendation: "Proceed with caution - changes may affect context", issues };
+return { level: "VERY_STALE", recommendation: "Consider new handoff - too many changes", issues };
 }
-
 function resolveProjectRootFromHandoff(handoffPath) {
-  const handoffsDir = path.dirname(handoffPath);
-  const handoffMarkerDir = path.basename(path.dirname(handoffsDir));
-  const stateMarkerDir = path.basename(path.dirname(path.dirname(handoffsDir)));
-  const isFlowScoped = handoffMarkerDir === 'handoffs' && stateMarkerDir === '.aikit-state';
-
-  return isFlowScoped ? path.resolve(handoffsDir, '..', '..', '..') : path.resolve(handoffsDir, '..');
+const handoffsDir = path.dirname(handoffPath);
+const handoffMarkerDir = path.basename(path.dirname(handoffsDir));
+const stateMarkerDir = path.basename(path.dirname(path.dirname(handoffsDir)));
+return handoffMarkerDir === "handoffs" && stateMarkerDir === ".aikit-state" ? path.resolve(handoffsDir, "..", "..", "..") : path.resolve(handoffsDir, "..");
 }
-
 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
-      : resolveProjectRootFromHandoff(handoffPath);
-
-  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;
+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 : resolveProjectRootFromHandoff(handoffPath);
+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 / 86400000; result.hoursOld = age / 3600000; }
+if (!isGitRepo) { result.stalenessLevel = "UNKNOWN"; result.recommendation = "Not a git repo - unable to detect changes"; result.issues = ["Project is not a git repository"]; return result; }
+const currentBranch = runCmd("git branch --show-current", projectPath).out;
+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 refs = checkFilesExist(meta.modifiedFiles, projectPath);
+result.referencedFilesExist = refs.existing.length; result.referencedFilesMissing = refs.missing;
+const stale = calculateStaleness(result.daysOld || 0, result.commitsSince, result.filesChangedCount, result.branchMatches, refs.missing.length);
+result.stalenessLevel = stale.level; result.recommendation = stale.recommendation; result.issues = stale.issues;
+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(', ')}\`);
-    }
-  }
+if (result.error) return void console.log("Error: " + result.error);
+console.log("\\n" + "=".repeat(60));
+console.log("Handoff Staleness");
+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) + "h") : ("Age: " + result.daysOld.toFixed(1) + "d"));
+}
+console.log("\\nStaleness: " + result.stalenessLevel);
+console.log("Next: " + result.recommendation);
+if (result.issues && result.issues.length) { 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) 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 .aikit-state/handoffs/<flow-slug>/2024-01-15-143022-auth.md');
-  console.log('       node check_staleness.js .aikit-state/handoffs/_standalone/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);
 }
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h") || !args.length) {
+console.log("Usage: node check_staleness.js <handoff-file>");
+console.log("       node check_staleness.js .aikit-state/handoffs/<flow-slug>/file.md");
+process.exit(!args.length ? 1 : 0);
+}
+const result = checkStaleness(args.find((arg) => !arg.startsWith("-")));
+if (args.includes("--json")) console.log(JSON.stringify(result, null, 2));
+else printReport(result);
 `},{file:`scripts/create_handoff.js`,content:`#!/usr/bin/env node
-/**
- * Smart scaffold generator for handoff documents.
- *
- * Creates a new handoff document with auto-detected metadata:
- * - Current timestamp
- * - Project path
- * - Git branch (if available)
- * - Recent git log
- * - Modified/staged files
- * - Handoff chain linking
- *
- * Usage:
- *   node create_handoff.js [task-slug]
- *   node create_handoff.js "implementing-auth"
- *   node create_handoff.js "auth-part-2" --continues-from 2024-01-15-auth.md
- *   node create_handoff.js "auth-part-2" --flow add-auth
- *   node create_handoff.js  # auto-generates slug from timestamp
- */
-
 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 getGitInfo(projectPath) {
-  const info = {
-    isGitRepo: false,
-    branch: null,
-    recentCommits: [],
-    modifiedFiles: [],
-    stagedFiles: [],
-  };
-
-  if (!runCmd('git rev-parse --git-dir', projectPath).ok) return info;
-  info.isGitRepo = true;
-
-  const { ok: bOk, out: branch } = runCmd('git branch --show-current', projectPath);
-  if (bOk && branch) info.branch = branch;
-
-  const { ok: lOk, out: log } = runCmd('git log --oneline -5 --no-decorate', projectPath);
-  if (lOk && log) info.recentCommits = log.split('\\n');
-
-  const { ok: mOk, out: modified } = runCmd('git diff --name-only', projectPath);
-  if (mOk && modified) info.modifiedFiles = modified.split('\\n');
-
-  const { ok: sOk, out: staged } = runCmd('git diff --name-only --cached', projectPath);
-  if (sOk && staged) info.stagedFiles = staged.split('\\n');
-
-  return info;
-}
-
-function getFlowDirectories(projectPath) {
-  const flowsDir = path.join(projectPath, '.flows');
-  if (!fs.existsSync(flowsDir)) return [];
-
-  return fs
-    .readdirSync(flowsDir)
-    .map((name) => ({ name, path: path.join(flowsDir, name) }))
-    .filter(({ name, path: flowPath }) => {
-      try {
-        return !name.startsWith('.') && fs.statSync(flowPath).isDirectory();
-      } catch {
-        return false;
-      }
-    })
-    .sort((a, b) => {
-      try {
-        return fs.statSync(b.path).mtimeMs - fs.statSync(a.path).mtimeMs;
-      } catch {
-        return 0;
-      }
-    });
-}
-
-function getActiveFlowSlug(projectPath) {
-  const flowDirs = getFlowDirectories(projectPath);
-  if (flowDirs.length === 0) return null;
-
-  const activeFlow = flowDirs.find(({ path: flowPath }) => {
-    const metaPath = path.join(flowPath, 'meta.json');
-    if (!fs.existsSync(metaPath)) return false;
-
-    try {
-      const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
-      return meta.status === 'active';
-    } catch {
-      return false;
-    }
-  });
-
-  return activeFlow ? activeFlow.name : null;
-}
-
-function getHandoffsDir(projectPath, flowSlug) {
-  if (flowSlug) return path.join(projectPath, '.aikit-state', 'handoffs', flowSlug);
-
-  const activeFlowSlug = getActiveFlowSlug(projectPath);
-  if (activeFlowSlug) return path.join(projectPath, '.aikit-state', 'handoffs', activeFlowSlug);
-
-  return path.join(projectPath, '.aikit-state', 'handoffs', '_standalone');
-}
-
-function findPreviousHandoffs(projectPath, flowSlug) {
-  const handoffs = [];
-  const baseDir = path.join(projectPath, '.aikit-state', 'handoffs');
-
-  function collectFromDir(dir, flow) {
-    if (!fs.existsSync(dir)) return;
-
-    for (const name of fs.readdirSync(dir)) {
-      if (!name.endsWith('.md')) continue;
-      const fp = path.join(dir, name);
-
-      let title = name;
-      try {
-        const content = fs.readFileSync(fp, 'utf-8');
-        const m = content.match(/^#\\s+(?:Handoff:\\s*)?(.+)$/m);
-        if (m) title = m[1].trim();
-      } catch {
-        /* ignore */
-      }
-
-      let date = null;
-      const dm = name.match(/^(\\d{4}-\\d{2}-\\d{2})-(\\d{6})/);
-      if (dm) {
-        try {
-          date = new Date(\`\${dm[1]}T\${dm[2].slice(0, 2)}:\${dm[2].slice(2, 4)}:\${dm[2].slice(4, 6)}\`);
-        } catch {
-          /* ignore */
-        }
-      }
-
-      handoffs.push({ filename: name, path: fp, title, date, flow });
-    }
-  }
-
-  if (!fs.existsSync(baseDir)) return handoffs;
-
-  const flowDirs = flowSlug
-    ? [flowSlug]
-    : fs.readdirSync(baseDir).filter((name) => {
-        try {
-          return fs.statSync(path.join(baseDir, name)).isDirectory();
-        } catch {
-          return false;
-        }
-      });
-
-  for (const fd of flowDirs) {
-    collectFromDir(path.join(baseDir, fd), fd === '_standalone' ? null : fd);
-  }
-
-  handoffs.sort((a, b) => (b.date || 0) - (a.date || 0));
-  return handoffs;
-}
-
-function getPreviousHandoffInfo(projectPath, continuesFrom, flowSlug) {
-  const handoffs = findPreviousHandoffs(projectPath, flowSlug);
-
-  if (continuesFrom) {
-    const found = handoffs.find((h) => h.filename.includes(continuesFrom));
-    return found
-      ? { exists: true, filename: found.filename, title: found.title, flow: found.flow }
-      : { exists: false, filename: continuesFrom, title: 'Not found' };
-  }
-
-  if (handoffs.length > 0) {
-    return {
-      exists: true,
-      filename: handoffs[0].filename,
-      title: handoffs[0].title,
-      flow: handoffs[0].flow,
-      suggested: true,
-    };
-  }
-
-  return { exists: false };
-}
-
-function sanitizeSlug(slug) {
-  return slug
-    .toLowerCase()
-    .replace(/[\\s_]/g, '-')
-    .replace(/[^a-z0-9-]/g, '');
-}
-
-function generateHandoff(projectPath, slug, continuesFrom, flowSlug) {
-  const now = new Date();
-  const timestamp = now.toISOString().replace('T', ' ').slice(0, 19);
-  const fileTs = \`\${now.toISOString().slice(0, 10)}-\${String(now.getHours()).padStart(2, '0')}\${String(now.getMinutes()).padStart(2, '0')}\${String(now.getSeconds()).padStart(2, '0')}\`;
-
-  if (!slug) slug = 'handoff';
-  slug = sanitizeSlug(slug);
-  const filename = \`\${fileTs}-\${slug}.md\`;
-
-  const resolvedFlowSlug = flowSlug || getActiveFlowSlug(projectPath);
-  const handoffsDir = getHandoffsDir(projectPath, flowSlug);
-  fs.mkdirSync(handoffsDir, { recursive: true });
-  const filepath = path.join(handoffsDir, filename);
-
-  const git = getGitInfo(projectPath);
-  const prev = getPreviousHandoffInfo(projectPath, continuesFrom, resolvedFlowSlug);
-
-  const branchLine = git.branch || '[not a git repo or detached HEAD]';
-
-  const commitsSection =
-    git.recentCommits.length > 0
-      ? git.recentCommits.map((c) => \`  - \${c}\`).join('\\n')
-      : '  - [no recent commits or not a git repo]';
-
-  const allModified = [...new Set([...git.modifiedFiles, ...git.stagedFiles])];
-  let modifiedSection;
-  if (allModified.length > 0) {
-    modifiedSection = allModified
-      .slice(0, 10)
-      .map((f) => \`| \${f} | [describe changes] | [why changed] |\`)
-      .join('\\n');
-    if (allModified.length > 10)
-      modifiedSection += \`\\n| ... and \${allModified.length - 10} more files | | |\`;
-  } else {
-    modifiedSection = '| [no modified files detected] | | |';
-  }
-
-  let chainSection;
-  if (prev.exists) {
-    const currentFlowDir = resolvedFlowSlug || '_standalone';
-    const prevFlowDir = prev.flow || '_standalone';
-    const prevPath =
-      prevFlowDir === currentFlowDir ? \`./\${prev.filename}\` : \`../\${prevFlowDir}/\${prev.filename}\`;
-    chainSection = \`## Handoff Chain
-
-- **Continues from**: [\${prev.filename}](\${prevPath})
-  - Previous title: \${prev.title || 'Unknown'}
-- **Supersedes**: [list any older handoffs this replaces, or "None"]
-
-> Review the previous handoff for full context before filling this one.\`;
-  } else {
-    chainSection = \`## Handoff Chain
-
-- **Continues from**: None (fresh start)
-- **Supersedes**: None
-
-> This is the first handoff for this task.\`;
-  }
-
-  const content = \`# Handoff: [TASK_TITLE - replace this]
-
-## Session Metadata
-- Created: \${timestamp}
-- Project: \${projectPath}
-- Branch: \${branchLine}
-- Session duration: [estimate how long you worked]
-
-### Recent Commits (for context)
-\${commitsSection}
-
-\${chainSection}
-
-## Current State Summary
-
-[TODO: Write one paragraph describing what was being worked on, current status, and where things left off]
-
-## Codebase Understanding
-
-### Architecture Overview
-
-[TODO: Document key architectural insights discovered during this session]
-
-### Critical Files
-
-| File | Purpose | Relevance |
-|------|---------|-----------|
-| [TODO: Add critical files] | | |
-
-### Key Patterns Discovered
-
-[TODO: Document important patterns, conventions, or idioms found in this codebase]
-
-## Work Completed
-
-### Tasks Finished
-
-- [ ] [TODO: List completed tasks]
-
-### Files Modified
-
-| File | Changes | Rationale |
-|------|---------|-----------|
-\${modifiedSection}
-
-### Decisions Made
-
-| Decision | Options Considered | Rationale |
-|----------|-------------------|-----------|
-| [TODO: Document key decisions] | | |
-
-## Pending Work
-
-### Immediate Next Steps
-
-1. [TODO: Most critical next action]
-2. [TODO: Second priority]
-3. [TODO: Third priority]
-
-### Blockers/Open Questions
-
-- [ ] [TODO: List blockers or open questions]
-
-### Deferred Items
-
-- [TODO: Items deferred and why]
-
-## Context for Resuming Agent
-
-### Important Context
-
-[TODO: Critical information the next agent MUST know]
-
-### Assumptions Made
-
-[TODO: List assumptions that might not be obvious]
-
-### Potential Gotchas
-
-[TODO: Things that could trip up the next agent]
-
-## Environment State
-
-[TODO: Required env vars, running processes, DB state]
-
-## Related Resources
-
-[TODO: Links to docs, PRs, issues, Slack threads]
-\`;
-
-  fs.writeFileSync(filepath, content, 'utf-8');
-
-  const compactContent = \`## Handoff: \${slug}
-Branch: \${branchLine} | Created: \${timestamp}
-
-### State
-[TODO: 1-2 sentences — what's happening, where we left off]
-
-### Decisions
-- [TODO: key decisions with rationale]
-
-### Next Steps
-1. [TODO: most critical action]
-2. [TODO: second priority]
-
-### Blockers
-- [TODO: what's blocking progress]
-
-### Assumptions
-- [TODO: assumptions that if wrong, change the approach]\`;
-
-  return { filepath, filename, compactContent };
+const runCmd = (cmd, cwd) => {
+try { return { ok: true, out: execSync(cmd, { cwd, timeout: 10000, encoding: "utf-8" }).trim() }; }
+catch { return { ok: false, out: "" }; }
+};
+function getGitInfo(root) {
+const info = { isGitRepo: false, branch: null, recentCommits: [], modifiedFiles: [], stagedFiles: [] };
+if (!runCmd("git rev-parse --git-dir", root).ok) return info;
+info.isGitRepo = true;
+const branch = runCmd("git branch --show-current", root); if (branch.ok && branch.out) info.branch = branch.out;
+const log = runCmd("git log --oneline -5 --no-decorate", root); if (log.ok && log.out) info.recentCommits = log.out.split("\\n");
+const modified = runCmd("git diff --name-only", root); if (modified.ok && modified.out) info.modifiedFiles = modified.out.split("\\n");
+const staged = runCmd("git diff --name-only --cached", root); if (staged.ok && staged.out) info.stagedFiles = staged.out.split("\\n");
+return info;
+}
+function getActiveFlowSlug(root) {
+const flowsDir = path.join(root, ".flows");
+if (!fs.existsSync(flowsDir)) return null;
+for (const name of fs.readdirSync(flowsDir)) {
+const flowPath = path.join(flowsDir, name);
+const metaPath = path.join(flowPath, "meta.json");
+try {
+if (!name.startsWith(".") && fs.statSync(flowPath).isDirectory() && fs.existsSync(metaPath)) {
+const meta = JSON.parse(fs.readFileSync(metaPath, "utf-8"));
+if (meta.status === "active") return name;
+}
+} catch {}
+}
+return null;
+}
+function getHandoffsDir(root, flow) {
+const active = flow || getActiveFlowSlug(root);
+return path.join(root, ".aikit-state", "handoffs", active || "_standalone");
+}
+function listPrevious(root, flow) {
+const baseDir = path.join(root, ".aikit-state", "handoffs");
+const handoffs = [];
+const collect = (dir, flowName) => {
+if (!fs.existsSync(dir)) return;
+for (const name of fs.readdirSync(dir)) {
+if (!name.endsWith(".md")) continue;
+const file = path.join(dir, name);
+let title = name; let date = null;
+try { const content = fs.readFileSync(file, "utf-8"); const match = content.match(/^#\\s+(?:Handoff:\\s*)?(.+)$/m); if (match) title = match[1].trim(); } catch {}
+const dm = name.match(/^(\\d{4}-\\d{2}-\\d{2})-(\\d{6})/);
+if (dm) { try { date = new Date(dm[1] + "T" + dm[2].slice(0,2) + ":" + dm[2].slice(2,4) + ":" + dm[2].slice(4,6)); } catch {} }
+handoffs.push({ filename: name, path: file, title, date, flow: flowName });
+}
+};
+if (!fs.existsSync(baseDir)) return handoffs;
+const dirs = flow ? [flow] : fs.readdirSync(baseDir).filter((name) => { try { return fs.statSync(path.join(baseDir, name)).isDirectory(); } catch { return false; } });
+for (const dir of dirs) collect(path.join(baseDir, dir), dir === "_standalone" ? null : dir);
+handoffs.sort((a, b) => (b.date || 0) - (a.date || 0));
+return handoffs;
+}
+const sanitizeSlug = (slug) => slug.toLowerCase().replace(/[\\s_]/g, "-").replace(/[^a-z0-9-]/g, "");
+function getPrevious(root, from, flow) {
+const handoffs = listPrevious(root, flow);
+if (from) {
+const found = handoffs.find((item) => item.filename.includes(from));
+return found ? { exists: true, filename: found.filename, title: found.title, flow: found.flow } : { exists: false };
+}
+return handoffs[0] ? { exists: true, filename: handoffs[0].filename, title: handoffs[0].title, flow: handoffs[0].flow } : { exists: false };
+}
+function generateHandoff(root, slug, from, flow) {
+const now = new Date();
+const stamp = now.toISOString().replace("T", " ").slice(0, 19);
+const fileTs = now.toISOString().slice(0,10) + "-" + String(now.getHours()).padStart(2,"0") + String(now.getMinutes()).padStart(2,"0") + String(now.getSeconds()).padStart(2,"0");
+const safeSlug = sanitizeSlug(slug || "handoff");
+const filename = fileTs + "-" + safeSlug + ".md";
+const activeFlow = flow || getActiveFlowSlug(root);
+const dir = getHandoffsDir(root, flow);
+fs.mkdirSync(dir, { recursive: true });
+const filepath = path.join(dir, filename);
+const git = getGitInfo(root);
+const prev = getPrevious(root, from, activeFlow);
+const branch = git.branch || "[not a git repo or detached HEAD]";
+const commits = git.recentCommits.length ? git.recentCommits.map((c) => "  - " + c).join("\\n") : "  - [none]";
+const files = [...new Set([...git.modifiedFiles, ...git.stagedFiles])];
+let modified = files.length ? files.slice(0, 10).map((f) => "| " + f + " | [changes] | [why] |").join("\\n") : "| [no modified files detected] | | |";
+if (files.length > 10) modified += "\\n| ... and " + (files.length - 10) + " more files | | |";
+let chain;
+if (prev.exists) {
+const currentFlow = activeFlow || "_standalone";
+const prevFlow = prev.flow || "_standalone";
+const prevPath = prevFlow === currentFlow ? "./" + prev.filename : "../" + prevFlow + "/" + prev.filename;
+chain = ["## Handoff Chain", "", "- **Continues from**: [" + prev.filename + "](" + prevPath + ")", "  - Previous title: " + (prev.title || "Unknown"), "- **Supersedes**: [list older handoffs replaced, or \\"None\\"]", "", "> Review previous handoff before filling this one."].join("\\n");
+} else chain = ["## Handoff Chain", "", "- **Continues from**: None (fresh start)", "- **Supersedes**: None", "", "> First handoff for this task."].join("\\n");
+const content = [
+"# Handoff: [TASK_TITLE - replace this]",
+"",
+"## Session Metadata",
+"- Created: " + stamp,
+"- Project: " + root,
+"- Branch: " + branch,
+"- Session duration: [estimate]",
+"",
+"### Recent Commits",
+commits,
+"",
+chain,
+"",
+"## Current State Summary",
+"",
+"[TODO: Summarize work, status, handoff point]",
+"",
+"## Codebase Understanding",
+"",
+"### Architecture Overview",
+"",
+"[TODO: Note key architecture insights]",
+"",
+"### Critical Files",
+"",
+"| File | Purpose | Relevance |",
+"|------|---------|-----------|",
+"| [TODO: Add critical files] | | |",
+"",
+"### Key Patterns Discovered",
+"",
+"[TODO: Note key patterns and conventions]",
+"",
+"## Work Completed",
+"",
+"### Tasks Finished",
+"",
+"- [ ] [TODO: List completed tasks]",
+"",
+"### Files Modified",
+"",
+"| File | Changes | Rationale |",
+"|------|---------|-----------|",
+modified,
+"",
+"### Decisions Made",
+"",
+"| Decision | Options Considered | Rationale |",
+"|----------|-------------------|-----------|",
+"| [TODO: Key decisions] | | |",
+"",
+"## Pending Work",
+"",
+"### Immediate Next Steps",
+"",
+"1. [TODO: First action]",
+"2. [TODO: Second action]",
+"3. [TODO: Third action]",
+"",
+"### Blockers/Open Questions",
+"",
+"- [ ] [TODO: Blockers or open questions]",
+"",
+"### Deferred Items",
+"",
+"- [TODO: Deferred items + why]",
+"",
+"## Context for Resuming Agent",
+"",
+"### Important Context",
+"",
+"[TODO: Critical context next agent MUST know]",
+"",
+"### Assumptions Made",
+"",
+"[TODO: Assumptions]",
+"",
+"### Potential Gotchas",
+"",
+"[TODO: Gotchas]",
+"",
+"## Environment State",
+"",
+"[TODO: Env vars, processes, DB state]",
+"",
+"## Related Resources",
+"",
+"[TODO: Docs, PRs, issues, threads]"
+].join("\\n");
+fs.writeFileSync(filepath, content, "utf-8");
+const compact = [
+"## Handoff: " + safeSlug,
+"Branch: " + branch + " | Created: " + stamp,
+"",
+"### State",
+"[TODO: 1-2 sentences — state + handoff point]",
+"",
+"### Decisions",
+"- [TODO: key decisions + rationale]",
+"",
+"### Next Steps",
+"1. [TODO: first action]",
+"2. [TODO: second action]",
+"",
+"### Blockers",
+"- [TODO: blockers]",
+"",
+"### Assumptions",
+"- [TODO: assumptions that could change approach]"
+].join("\\n");
+return { filepath, compact };
 }
-
-// --- Main ---
 const args = process.argv.slice(2);
-if (args.includes('--help') || args.includes('-h')) {
-  console.log('Usage: node create_handoff.js [task-slug] [--continues-from <previous>] [--flow <flow-slug>]');
-  console.log('       node create_handoff.js "implementing-auth"');
-  console.log('       node create_handoff.js "auth-part-2" --continues-from 2024-01-15-auth.md');
-  console.log('       node create_handoff.js "auth-part-2" --flow add-auth');
-  process.exit(0);
+if (args.includes("--help") || args.includes("-h")) {
+console.log("Usage: node create_handoff.js [task-slug] [--continues-from <previous>] [--flow <flow-slug>]");
+console.log("       node create_handoff.js --continues-from 2024-01-15-auth.md");
+console.log("       node create_handoff.js \\"auth-part-2\\" --flow add-auth");
+process.exit(0);
 }
-
-let slug = null;
-let continuesFrom = null;
-let flowSlug = null;
+let slug = null; let from = null; let flow = null;
 for (let i = 0; i < args.length; i++) {
-  if (args[i] === '--continues-from' && i + 1 < args.length) {
-    continuesFrom = args[++i];
-  } else if (args[i] === '--flow' && i + 1 < args.length) {
-    flowSlug = sanitizeSlug(args[++i]);
-  } else if (!args[i].startsWith('-')) {
-    slug = args[i];
-  }
-}
-
-const cwd = process.cwd();
-const { filepath, compactContent } = generateHandoff(cwd, slug, continuesFrom, flowSlug);
-console.log(\`Created handoff: \${filepath}\`);
-console.log('\\nCompact flow knowledge entry:');
-console.log('---');
-console.log(compactContent);
-console.log('---');
-console.log(\`\\nNext: Open the file and fill in all [TODO: ...] sections.\`);
-console.log(\`Then validate: node scripts/validate_handoff.js \${filepath}\`);
+if (args[i] === "--continues-from" && i + 1 < args.length) from = args[++i];
+else if (args[i] === "--flow" && i + 1 < args.length) flow = sanitizeSlug(args[++i]);
+else if (!args[i].startsWith("-")) slug = args[i];
+}
+const result = generateHandoff(process.cwd(), slug, from, flow);
+console.log("Created handoff: " + result.filepath);
+console.log("\\nCompact flow knowledge entry:");
+console.log("---");
+console.log(result.compact);
+console.log("---");
+console.log("\\nNext: Open file and fill all [TODO: ...] sections.");
+console.log("Then validate: node scripts/validate_handoff.js " + result.filepath);
 `},{file:`scripts/list_handoffs.js`,content:`#!/usr/bin/env node
-/**
- * List available handoff documents in the current project.
- *
- * Searches for handoff documents in .aikit-state/handoffs/<flow-slug>/ and .aikit-state/handoffs/_standalone/ and displays:
- * - Filename with date
- * - Flow scope
- * - Title extracted from document
- * - Status (complete / in progress / needs work)
- *
- * Usage:
- *   node list_handoffs.js           # List handoffs in current project
- *   node list_handoffs.js /path     # List handoffs in specified path
- */
-
 const fs = require('node:fs');
 const path = require('node:path');
-
 function extractTitle(filepath) {
-  try {
-    const content = fs.readFileSync(filepath, 'utf-8');
-    const m = content.match(/^#\\s+(?:Handoff:\\s*)?(.+)$/m);
-    if (m) {
-      const title = m[1].trim();
-      if (title.startsWith('[') && title.endsWith(']')) return '[Untitled - needs completion]';
-      return title.length > 50 ? \`\${title.slice(0, 50)}...\` : title;
-    }
-  } catch {
-    /* ignore */
-  }
-  return '[Unable to read title]';
+try {
+const content = fs.readFileSync(filepath, "utf-8");
+const match = content.match(/^#\\s+(?:Handoff:\\s*)?(.+)$/m);
+if (match) { const title = match[1].trim(); return title.startsWith("[") && title.endsWith("]") ? "[Untitled - needs completion]" : (title.length > 50 ? title.slice(0, 50) + "..." : title); }
+} catch {}
+return "[Unable to read title]";
 }
-
 function checkCompletion(filepath) {
-  try {
-    const content = fs.readFileSync(filepath, 'utf-8');
-    const count = (content.match(/\\[TODO:/g) || []).length;
-    if (count === 0) return 'Complete';
-    if (count <= 3) return \`In Progress (\${count} TODOs)\`;
-    return \`Needs Work (\${count} TODOs)\`;
-  } catch {
-    return 'Unknown';
-  }
+try {
+const count = (fs.readFileSync(filepath, "utf-8").match(/\\[TODO:/g) || []).length;
+if (count === 0) return "Complete";
+if (count <= 3) return "In Progress (" + count + " TODOs)";
+return "Needs Work (" + count + " TODOs)";
+} catch { return "Unknown"; }
 }
-
 function parseDateFromFilename(filename) {
-  const m = filename.match(/^(\\d{4}-\\d{2}-\\d{2})-(\\d{6})/);
-  if (m) {
-    try {
-      return new Date(\`\${m[1]}T\${m[2].slice(0, 2)}:\${m[2].slice(2, 4)}:\${m[2].slice(4, 6)}\`);
-    } catch {
-      /* ignore */
-    }
-  }
-  return null;
-}
-
-function listHandoffs(projectPath) {
-  const handoffs = [];
-  const baseDir = path.join(projectPath, '.aikit-state', 'handoffs');
-
-  function collectFromDir(dir, flow) {
-    if (!fs.existsSync(dir)) return;
-
-    for (const name of fs.readdirSync(dir)) {
-      if (!name.endsWith('.md')) continue;
-      const fp = path.join(dir, name);
-      const stat = fs.statSync(fp);
-
-      handoffs.push({
-        path: fp,
-        filename: name,
-        flow,
-        title: extractTitle(fp),
-        status: checkCompletion(fp),
-        date: parseDateFromFilename(name),
-        size: stat.size,
-      });
-    }
-  }
-
-  if (fs.existsSync(baseDir)) {
-    const flowDirs = fs
-      .readdirSync(baseDir)
-      .filter((name) => {
-        try {
-          return fs.statSync(path.join(baseDir, name)).isDirectory();
-        } catch {
-          return false;
-        }
-      })
-      .sort((a, b) => {
-        try {
-          return fs.statSync(path.join(baseDir, b)).mtimeMs - fs.statSync(path.join(baseDir, a)).mtimeMs;
-        } catch {
-          return 0;
-        }
-      });
-
-    for (const flow of flowDirs) {
-      collectFromDir(path.join(baseDir, flow), flow === '_standalone' ? null : flow);
-    }
-  }
-
-  handoffs.sort((a, b) => (b.date || 0) - (a.date || 0));
-  return handoffs;
-}
-
-function formatDate(dt) {
-  if (!dt) return 'Unknown date';
-  return dt.toISOString().replace('T', ' ').slice(0, 16);
-}
-
-// --- Main ---
+const match = filename.match(/^(\\d{4}-\\d{2}-\\d{2})-(\\d{6})/);
+if (!match) return null;
+try { return new Date(match[1] + "T" + match[2].slice(0,2) + ":" + match[2].slice(2,4) + ":" + match[2].slice(4,6)); } catch { return null; }
+}
+function listHandoffs(root) {
+const handoffs = [];
+const baseDir = path.join(root, ".aikit-state", "handoffs");
+const collect = (dir, flow) => {
+if (!fs.existsSync(dir)) return;
+for (const name of fs.readdirSync(dir)) {
+if (!name.endsWith(".md")) continue;
+const fp = path.join(dir, name); const stat = fs.statSync(fp);
+handoffs.push({ path: fp, filename: name, flow, title: extractTitle(fp), status: checkCompletion(fp), date: parseDateFromFilename(name), size: stat.size });
+}
+};
+if (fs.existsSync(baseDir)) {
+const flowDirs = fs.readdirSync(baseDir).filter((name) => { try { return fs.statSync(path.join(baseDir, name)).isDirectory(); } catch { return false; } }).sort((a, b) => { try { return fs.statSync(path.join(baseDir, b)).mtimeMs - fs.statSync(path.join(baseDir, a)).mtimeMs; } catch { return 0; } });
+for (const flow of flowDirs) collect(path.join(baseDir, flow), flow === "_standalone" ? null : flow);
+}
+handoffs.sort((a, b) => (b.date || 0) - (a.date || 0));
+return handoffs;
+}
+const formatDate = (dt) => dt ? dt.toISOString().replace("T", " ").slice(0, 16) : "Unknown date";
 const args = process.argv.slice(2);
-if (args.includes('--help') || args.includes('-h')) {
-  console.log('Usage: node list_handoffs.js [project-path]');
-  process.exit(0);
-}
-
+if (args.includes("--help") || args.includes("-h")) { console.log("Usage: node list_handoffs.js [project-path]"); process.exit(0); }
 const projectPath = args[0] || process.cwd();
 const handoffs = listHandoffs(projectPath);
-
-if (handoffs.length === 0) {
-  console.log('No handoff documents found.');
-  console.log(\`Looked in: \${path.join(projectPath, '.aikit-state', 'handoffs', '*')}\`);
-  console.log(\`           \${path.join(projectPath, '.aikit-state', 'handoffs', '_standalone')}\`);
-  console.log('\\nCreate one with: node scripts/create_handoff.js [task-slug]');
-  process.exit(0);
-}
-
-console.log(\`\\nFound \${handoffs.length} handoff(s) in \${projectPath}:\\n\`);
-console.log(\`\${'Date'.padEnd(18)} \${'Flow'.padEnd(18)} \${'Status'.padEnd(25)} Title\`);
-console.log(\`\${'-'.repeat(18)} \${'-'.repeat(18)} \${'-'.repeat(25)} \${'-'.repeat(40)}\`);
-
-for (const h of handoffs) {
-  const flowLabel = h.flow || '[standalone]';
-  console.log(\`\${formatDate(h.date).padEnd(18)} \${flowLabel.padEnd(18)} \${h.status.padEnd(25)} \${h.title}\`);
-}
-
-if (args.includes('--json')) {
-  console.log(\`\\n\${JSON.stringify(handoffs, null, 2)}\`);
-}
+if (!handoffs.length) {
+console.log("No handoff documents found.");
+console.log("Looked in: " + path.join(projectPath, ".aikit-state", "handoffs", "*"));
+console.log("           " + path.join(projectPath, ".aikit-state", "handoffs", "_standalone"));
+console.log("\\nCreate one with: node scripts/create_handoff.js [task-slug]");
+process.exit(0);
+}
+console.log("\\nFound " + handoffs.length + " handoff(s) in " + projectPath + ":\\n");
+console.log(String("Date").padEnd(18) + " " + String("Flow").padEnd(18) + " " + String("Status").padEnd(25) + " Title");
+console.log("-".repeat(18) + " " + "-".repeat(18) + " " + "-".repeat(25) + " " + "-".repeat(40));
+for (const handoff of handoffs) console.log(formatDate(handoff.date).padEnd(18) + " " + String(handoff.flow || "[standalone]").padEnd(18) + " " + handoff.status.padEnd(25) + " " + handoff.title);
+if (args.includes("--json")) console.log("\\n" + JSON.stringify(handoffs, null, 2));
 `},{file:`scripts/validate_handoff.js`,content:`#!/usr/bin/env node
-/**
- * Validate a handoff document for completeness and quality.
- *
- * Checks:
- * - No TODO placeholders remaining
- * - Required sections present and populated
- * - No potential secrets detected
- * - Referenced files exist
- * - Quality scoring (0-100)
- *
- * Usage:
- *   node validate_handoff.js <handoff-file>
- *   node validate_handoff.js .aikit-state/handoffs/add-auth/2024-01-15-143022-auth.md
- *   node validate_handoff.js .aikit-state/handoffs/_standalone/2024-01-15-143022-auth.md
- */
-
 const fs = require('node:fs');
 const path = require('node:path');
-
-// Secret detection patterns
 const SECRET_PATTERNS = [
-  [/["']?[a-zA-Z_]*api[_-]?key["']?\\s*[:=]\\s*["'][^"']{10,}["']/gi, 'API key'],
-  [/["']?[a-zA-Z_]*password["']?\\s*[:=]\\s*["'][^"']+["']/gi, 'Password'],
-  [/["']?[a-zA-Z_]*secret["']?\\s*[:=]\\s*["'][^"']{10,}["']/gi, 'Secret'],
-  [/["']?[a-zA-Z_]*token["']?\\s*[:=]\\s*["'][^"']{20,}["']/gi, 'Token'],
-  [/["']?[a-zA-Z_]*private[_-]?key["']?\\s*[:=]/gi, 'Private key'],
-  [/-----BEGIN [A-Z]+ PRIVATE KEY-----/g, 'PEM private key'],
-  [/mongodb(\\+srv)?:\\/\\/[^/\\s]+:[^@\\s]+@/gi, 'MongoDB connection string with password'],
-  [/postgres:\\/\\/[^/\\s]+:[^@\\s]+@/gi, 'PostgreSQL connection string with password'],
-  [/mysql:\\/\\/[^/\\s]+:[^@\\s]+@/gi, 'MySQL connection string with password'],
-  [/Bearer\\s+[a-zA-Z0-9_\\-.]+/g, 'Bearer token'],
-  [/ghp_[a-zA-Z0-9]{36}/g, 'GitHub personal access token'],
-  [/sk-[a-zA-Z0-9]{48}/g, 'OpenAI API key'],
-  [/xox[baprs]-[a-zA-Z0-9-]+/g, 'Slack token'],
+[/[\\"']?[a-zA-Z_]*api[_-]?key[\\"']?\\\\s*[:=]\\\\s*[\\"'][^\\"']{10,}[\\"']/gi, 'API key'],
+[/[\\"']?[a-zA-Z_]*password[\\"']?\\\\s*[:=]\\\\s*[\\"'][^\\"']+[\\"']/gi, 'Password'],
+[/[\\"']?[a-zA-Z_]*secret[\\"']?\\\\s*[:=]\\\\s*[\\"'][^\\"']{10,}[\\"']/gi, 'Secret'],
+[/[\\"']?[a-zA-Z_]*token[\\"']?\\\\s*[:=]\\\\s*[\\"'][^\\"']{20,}[\\"']/gi, 'Token'],
+[/[\\"']?[a-zA-Z_]*private[_-]?key[\\"']?\\\\s*[:=]/gi, 'Private key'],
+[/-----BEGIN [A-Z]+ PRIVATE KEY-----/g, 'PEM key'],
+[/Bearer\\\\s+[A-Za-z0-9_.-]+/g, 'Bearer token'],
+[/ghp_[a-zA-Z0-9]{36}/g, 'GitHub PAT'],
+[/sk-[a-zA-Z0-9]{48}/g, 'OpenAI key'],
+[/xox[baprs]-[a-zA-Z0-9-]+/g, 'Slack token'],
 ];
-
 const REQUIRED_SECTIONS = ['Current State Summary', 'Important Context', 'Immediate Next Steps'];
-const RECOMMENDED_SECTIONS = [
-  'Architecture Overview',
-  'Critical Files',
-  'Files Modified',
-  'Decisions Made',
-  'Assumptions Made',
-  'Potential Gotchas',
-];
-
-function checkTodos(content) {
-  const todos = content.match(/\\[TODO:[^\\]]*\\]/g) || [];
-  return { clear: todos.length === 0, todos };
-}
-
+const RECOMMENDED_SECTIONS = ['Architecture Overview', 'Critical Files', 'Files Modified', 'Decisions Made', 'Assumptions Made', 'Potential Gotchas'];
+const escapeRe = (value) => value.replace(/[.*+?^\${}()|[\\\\]\\\\]/g, '\\\\$&');
+function checkTodos(content) { const todos = content.match(/\\\\[TODO:[^\\\\]]*\\\\]/g) || []; return { clear: todos.length === 0, todos }; }
 function checkRequiredSections(content) {
-  const missing = [];
-  for (const section of REQUIRED_SECTIONS) {
-    const pattern = new RegExp(
-      \`(?:^|\\\\n)##?\\\\s*\${section.replace(/[.*+?^\${}()|[\\]\\\\]/g, '\\\\$&')}\`,
-      'i',
-    );
-    const match = pattern.exec(content);
-    if (!match) {
-      missing.push(\`\${section} (missing)\`);
-    } else {
-      const start = match.index + match[0].length;
-      const nextSection = content.slice(start).search(/\\n##?\\s+/);
-      const end = nextSection >= 0 ? start + nextSection : content.length;
-      const sectionContent = content.slice(start, end).trim();
-      if (sectionContent.length < 50 || sectionContent.includes('[TODO')) {
-        missing.push(\`\${section} (incomplete)\`);
-      }
-    }
-  }
-  return { complete: missing.length === 0, missing };
+const missing = [];
+for (const section of REQUIRED_SECTIONS) {
+const pattern = new RegExp('(?:^|\\\\n)##?\\\\s*' + escapeRe(section), 'i');
+const match = pattern.exec(content);
+if (!match) { missing.push(section + ' (missing)'); continue; }
+const start = match.index + match[0].length;
+const nextSection = content.slice(start).search(/\\\\n##?\\\\s+/);
+const end = nextSection >= 0 ? start + nextSection : content.length;
+const sectionContent = content.slice(start, end).trim();
+if (sectionContent.length < 50 || sectionContent.includes('[TODO')) missing.push(section + ' (incomplete)');
+}
+return { complete: missing.length === 0, missing };
 }
-
 function checkRecommendedSections(content) {
-  const missing = [];
-  for (const section of RECOMMENDED_SECTIONS) {
-    const pattern = new RegExp(
-      \`(?:^|\\\\n)##?\\\\s*\${section.replace(/[.*+?^\${}()|[\\]\\\\]/g, '\\\\$&')}\`,
-      'i',
-    );
-    if (!pattern.test(content)) missing.push(section);
-  }
-  return missing;
+const missing = [];
+for (const section of RECOMMENDED_SECTIONS) {
+const pattern = new RegExp('(?:^|\\\\n)##?\\\\s*' + escapeRe(section), 'i');
+if (!pattern.test(content)) missing.push(section);
+}
+return missing;
 }
-
 function scanForSecrets(content) {
-  const findings = [];
-  for (const [pattern, description] of SECRET_PATTERNS) {
-    const matches = content.match(pattern);
-    if (matches) findings.push({ description, count: matches.length });
-  }
-  return findings;
+const findings = [];
+for (const [pattern, description] of SECRET_PATTERNS) { const matches = content.match(pattern); if (matches) findings.push({ description, count: matches.length }); }
+return findings;
 }
-
 function checkFileReferences(content, basePath) {
-  const patterns = [
-    /\\|\\s*([a-zA-Z0-9_\\-./]+\\.[a-zA-Z]+)\\s*\\|/g,
-    /\`([a-zA-Z0-9_\\-./]+\\.[a-zA-Z]+(?::\\d+)?)\`/g,
-    /(?:^|\\s)([a-zA-Z0-9_\\-./]+\\.[a-zA-Z]+:\\d+)/gm,
-  ];
-
-  const foundFiles = new Set();
-  for (const pattern of patterns) {
-    for (const m of content.matchAll(pattern)) {
-      const filepath = m[1].split(':')[0];
-      if (filepath && !filepath.startsWith('http') && filepath.includes('/')) {
-        foundFiles.add(filepath);
-      }
-    }
-  }
-
-  const existing = [];
-  const missing = [];
-  for (const f of foundFiles) {
-    if (fs.existsSync(path.join(basePath, f))) existing.push(f);
-    else missing.push(f);
-  }
-  return { existing, missing };
+const patterns = [/\\\\|\\\\s*([A-Za-z0-9_./-]+\\\\.[a-zA-Z]+)\\\\s*\\\\|/g, /\`([A-Za-z0-9_./-]+\\\\.[a-zA-Z]+(?::\\\\d+)?)\`/g, /(?:^|\\\\s)([A-Za-z0-9_./-]+\\\\.[a-zA-Z]+:\\\\d+)/gm];
+const foundFiles = new Set();
+for (const pattern of patterns) {
+for (const match of content.matchAll(pattern)) {
+const filepath = match[1].split(':')[0];
+if (filepath && !filepath.startsWith('http') && filepath.includes('/')) foundFiles.add(filepath);
+}
+}
+const existing = []; const missing = [];
+for (const file of foundFiles) (fs.existsSync(path.join(basePath, file)) ? existing : missing).push(file);
+return { existing, missing };
+}
+function calculateScore(todosClear, requiredComplete, missingRequired, missingRecommended, secretsFound, filesMissing) {
+let score = 100;
+if (!todosClear) score -= 30;
+if (!requiredComplete) score -= 10 * missingRequired.length;
+if (secretsFound.length) score -= 20;
+if (filesMissing.length) score -= 5 * Math.min(filesMissing.length, 4);
+score -= 2 * missingRecommended.length;
+score = Math.max(0, score);
+return { score, rating: score >= 90 ? 'Excellent' : score >= 70 ? 'Good' : score >= 50 ? 'Fair' : 'Poor' };
 }
-
-function calculateScore(todosClear, reqComplete, missingReq, missingRec, secrets, filesMissing) {
-  let score = 100;
-
-  if (!todosClear) score -= 30;
-  if (!reqComplete) score -= 10 * missingReq.length;
-  if (secrets.length > 0) score -= 20;
-  if (filesMissing.length > 0) score -= 5 * Math.min(filesMissing.length, 4);
-  score -= 2 * missingRec.length;
-
-  score = Math.max(0, score);
-
-  let rating;
-  if (score >= 90) rating = 'Excellent - Ready for handoff';
-  else if (score >= 70) rating = 'Good - Minor improvements suggested';
-  else if (score >= 50) rating = 'Fair - Needs attention before handoff';
-  else rating = 'Poor - Significant work needed';
-
-  return { score, rating };
-}
-
 function resolveProjectRootFromHandoff(filepath) {
-  const handoffsDir = path.dirname(filepath);
-  const handoffMarkerDir = path.basename(path.dirname(handoffsDir));
-  const stateMarkerDir = path.basename(path.dirname(path.dirname(handoffsDir)));
-  const isFlowScoped = handoffMarkerDir === 'handoffs' && stateMarkerDir === '.aikit-state';
-
-  return isFlowScoped ? path.resolve(handoffsDir, '..', '..', '..') : path.resolve(handoffsDir, '..');
+const handoffsDir = path.dirname(filepath);
+const handoffMarkerDir = path.basename(path.dirname(handoffsDir));
+const stateMarkerDir = path.basename(path.dirname(path.dirname(handoffsDir)));
+return handoffMarkerDir === 'handoffs' && stateMarkerDir === '.aikit-state' ? path.resolve(handoffsDir, '..', '..', '..') : path.resolve(handoffsDir, '..');
 }
-
 function validateHandoff(filepath) {
-  if (!fs.existsSync(filepath)) return { error: \`File not found: \${filepath}\` };
-
-  const content = fs.readFileSync(filepath, 'utf-8');
-  const basePath = resolveProjectRootFromHandoff(filepath);
-
-  const { clear: todosClear, todos } = checkTodos(content);
-  const { complete: reqComplete, missing: missingReq } = checkRequiredSections(content);
-  const missingRec = checkRecommendedSections(content);
-  const secrets = scanForSecrets(content);
-  const { existing: existingFiles, missing: missingFiles } = checkFileReferences(content, basePath);
-
-  const { score, rating } = calculateScore(
-    todosClear,
-    reqComplete,
-    missingReq,
-    missingRec,
-    secrets,
-    missingFiles,
-  );
-
-  return {
-    filepath,
-    score,
-    rating,
-    todosClear,
-    remainingTodos: todos.slice(0, 5),
-    todoCount: todos.length,
-    requiredComplete: reqComplete,
-    missingRequired: missingReq,
-    missingRecommended: missingRec,
-    secretsFound: secrets,
-    filesVerified: existingFiles.length,
-    filesMissing: missingFiles.slice(0, 5),
-  };
+if (!fs.existsSync(filepath)) return { error: 'File not found: ' + filepath };
+const content = fs.readFileSync(filepath, 'utf-8');
+const basePath = resolveProjectRootFromHandoff(filepath);
+const { clear: todosClear, todos } = checkTodos(content);
+const { complete: requiredComplete, missing: missingRequired } = checkRequiredSections(content);
+const missingRecommended = checkRecommendedSections(content);
+const secretsFound = scanForSecrets(content);
+const refs = checkFileReferences(content, basePath);
+const { score, rating } = calculateScore(todosClear, requiredComplete, missingRequired, missingRecommended, secretsFound, refs.missing);
+return { filepath, score, rating, todosClear, remainingTodos: todos.slice(0, 5), todoCount: todos.length, requiredComplete, missingRequired, missingRecommended, secretsFound, filesVerified: refs.existing.length, filesMissing: refs.missing.slice(0, 5) };
 }
-
 function printReport(result) {
-  if (result.error) {
-    console.log(\`Error: \${result.error}\`);
-    return;
-  }
-
-  console.log(\`\\n\${'='.repeat(60)}\`);
-  console.log('Handoff Validation Report');
-  console.log('='.repeat(60));
-  console.log(\`File: \${result.filepath}\`);
-  console.log(\`\\nQuality Score: \${result.score}/100 - \${result.rating}\`);
-  console.log('='.repeat(60));
-
-  if (result.todosClear) {
-    console.log('\\n[PASS] No TODO placeholders remaining');
-  } else {
-    console.log(\`\\n[FAIL] \${result.todoCount} TODO placeholders found:\`);
-    for (const t of result.remainingTodos) console.log(\`       - \${t.slice(0, 50)}...\`);
-  }
-
-  if (result.requiredComplete) {
-    console.log('\\n[PASS] All required sections complete');
-  } else {
-    console.log('\\n[FAIL] Missing/incomplete required sections:');
-    for (const s of result.missingRequired) console.log(\`       - \${s}\`);
-  }
-
-  if (result.secretsFound.length === 0) {
-    console.log('\\n[PASS] No potential secrets detected');
-  } else {
-    console.log('\\n[WARN] Potential secrets detected:');
-    for (const s of result.secretsFound)
-      console.log(\`       - \${s.description} (\${s.count} match(es))\`);
-  }
-
-  console.log(
-    \`\\n[INFO] File references: \${result.filesVerified} verified, \${result.filesMissing.length} missing\`,
-  );
-  if (result.filesMissing.length > 0) {
-    for (const f of result.filesMissing) console.log(\`       - \${f}\`);
-  }
-
-  if (result.missingRecommended.length > 0) {
-    console.log('\\n[INFO] Missing recommended sections:');
-    for (const s of result.missingRecommended) console.log(\`       - \${s}\`);
-  }
+if (result.error) return void console.log('Error: ' + result.error);
+console.log('\\n' + '='.repeat(60));
+console.log('Handoff Validation');
+console.log('='.repeat(60));
+console.log('File: ' + result.filepath);
+console.log('\\nScore: ' + result.score + '/100 - ' + result.rating);
+console.log('='.repeat(60));
+if (result.todosClear) console.log('\\n[PASS] No TODO placeholders remaining');
+else { console.log('\\n[FAIL] ' + result.todoCount + ' TODO placeholders found:'); for (const todo of result.remainingTodos) console.log('       - ' + todo.slice(0, 50) + '...'); }
+if (result.requiredComplete) console.log('\\n[PASS] All required sections complete');
+else { console.log('\\n[FAIL] Missing/incomplete required sections:'); for (const section of result.missingRequired) console.log('       - ' + section); }
+if (!result.secretsFound.length) console.log('\\n[PASS] No potential secrets detected');
+else { console.log('\\n[WARN] Potential secrets detected:'); for (const finding of result.secretsFound) console.log('       - ' + finding.description + ' (' + finding.count + ' match(es))'); }
+console.log('\\n[INFO] File refs: ' + result.filesVerified + ' verified, ' + result.filesMissing.length + ' missing');
+for (const missingFile of result.filesMissing) console.log('       - ' + missingFile);
+if (result.missingRecommended.length) { console.log('\\n[INFO] Missing recommended sections:'); for (const section of result.missingRecommended) console.log('       - ' + section); }
 }
-
-// --- Main ---
 const args = process.argv.slice(2);
-if (args.includes('--help') || args.includes('-h') || args.length === 0) {
-  console.log('Usage: node validate_handoff.js <handoff-file>');
-  console.log('       node validate_handoff.js .aikit-state/handoffs/<flow-slug>/2024-01-15-143022-auth.md');
-  console.log('       node validate_handoff.js .aikit-state/handoffs/_standalone/2024-01-15-143022-auth.md');
-  process.exit(args.length === 0 ? 1 : 0);
-}
-
-if (args.includes('--json')) {
-  const result = validateHandoff(args.find((a) => !a.startsWith('-')));
-  console.log(JSON.stringify(result, null, 2));
-} else {
-  const result = validateHandoff(args[0]);
-  printReport(result);
-}
+if (args.includes('--help') || args.includes('-h') || !args.length) {
+console.log('Usage: node validate_handoff.js <handoff-file>');
+console.log('       node validate_handoff.js .aikit-state/handoffs/<flow-slug>/file.md');
+process.exit(!args.length ? 1 : 0);
+}
+const result = validateHandoff(args.find((arg) => !arg.startsWith('-')) || args[0]);
+if (args.includes('--json')) console.log(JSON.stringify(result, null, 2));
+else printReport(result);
 `},{file:`SKILL.md`,content:`---
 name: session-handoff
-description: "Creates comprehensive handoff documents for seamless AI agent session transfers. Triggered when: (1) user requests handoff/memory/context save, (2) context window approaches capacity (>70% pressure), (3) major task milestone completed, (4) work session ending, (5) user says 'save state', 'create handoff', 'I need to pause', 'context is getting full', (6) resuming work with 'load handoff', 'resume from', 'continue where we left off'. Proactively suggests handoffs after substantial work (multiple file edits, complex debugging, architecture decisions). Solves long-running agent context exhaustion by enabling fresh agents to continue with zero ambiguity."
+description: "Creates handoff docs for session transfer. Trigger on save-context, high context pressure, milestones, session end, or resume requests."
 metadata:
   category: cross-cutting
   domain: general
@@ -1308,121 +620,68 @@ metadata:
   requires: [aikit]
   relatedSkills: [lesson-learned]
 ---
-
 # Session Handoff
-
-Creates compact, high-signal handoffs so a fresh agent can resume work without rereading the full conversation.
-
+Handoffs.
 ## Mindset
-
-Session handoffs solve the "context amnesia" problem — you have 200K tokens of accumulated understanding that will vanish. Your job is compression with zero information loss on the critical path.
-
-Think of it as writing a briefing for a colleague who will take over your shift:
-- What's the current state? (not how we got here)
-- What decisions were made and WHY? (not what was considered)
-- What's blocked and needs action? (not what's going fine)
-- What will surprise them? (gotchas, non-obvious constraints)
-
-The 80/20 rule applies brutally: 80% of context is irrelevant to the next step. Identify the 20% that matters and make it crystal clear.
-
+Keep only state, decisions + why, blockers, next step, gotchas.
 ## Quick Reference
-
-Use this skill in two modes:
-- **CREATE** — when user asks to save context, context pressure exceeds ~70%, a milestone lands, or the session is ending
-- **RESUME** — when user asks to continue prior work, load saved context, or pick up from an existing handoff
-
-Every good handoff stores context in two forms:
-1. **Full markdown file** at \`.aikit-state/handoffs/{flow-slug}/YYYY-MM-DD-HHMMSS-[slug].md\`
-2. **Compact flow knowledge entry** via \`knowledge({ action: "remember", scope: "flow", category: "session", title: "Session Handoff: <slug>", content })\`
-
-On resume, start with \`knowledge({ action: "withdraw", scope: "flow", profile: "implementer", budget: 6000 })\`. Only open the full handoff file if the compact entry is insufficient.
-
+- **CREATE** — save context near milestone, pause, session end, or high context pressure
+- **RESUME** — continue prior work from handoff
+- Full file: \`.aikit-state/handoffs/{flow-slug}/YYYY-MM-DD-HHMMSS-[slug].md\`
+- Compact entry: \`knowledge({ action: "remember", scope: "flow", category: "session", title: "Session Handoff: <slug>", content })\`
+- Fast-path: \`knowledge({ action: "withdraw", scope: "flow", profile: "implementer", budget: 6000 })\`
 ## NEVER
-
-- **NEVER include full file contents in handoffs** — reference file paths + what changed, not entire files. Handoffs that paste 1000 lines of code are useless because the next agent will need to re-read them anyway.
-- **NEVER omit the "why" behind decisions** — "chose JWT" is worthless without "chose JWT because: stateless, API consumers, no session store." The next agent WILL re-examine your decisions without the rationale.
-- **NEVER create a handoff without blockers/next-steps** — these are the single most important sections. Everything else provides context; these drive action.
-- **NEVER hand off mid-failure** without capturing: error message, what was tried, what was NOT tried yet. Incomplete failure context causes the next agent to repeat failed approaches.
-- **NEVER include conversation history** — handoffs summarize OUTCOMES not PROCESS. "We discussed 3 options and chose X" not "I said... user said... I said..."
-- **NEVER create handoffs larger than 500 words** — if it's longer, you're pasting instead of summarizing. Compress ruthlessly.
-- **NEVER skip the architecture context** — the next agent doesn't know the codebase. Include: key files, patterns used, critical constraints.
-
+- **NEVER include full file contents in handoffs**
+- **NEVER omit the "why" behind decisions**
+- **NEVER create a handoff without blockers/next-steps**
+- **NEVER hand off mid-failure** without error text and tried/untried paths
+- **NEVER include conversation history**
+- **NEVER create handoffs larger than 500 words**
+- **NEVER skip architecture context**
 ## Handoff Quality Gate
-
-A good handoff passes the "cold start" test: could a brand-new agent, with NO prior context, pick up where you left off and produce correct output on the FIRST attempt?
-
-Score your handoff (must be 4/4):
-- [ ] **Actionable** — next steps are specific enough to execute without interpretation
-- [ ] **Self-contained** — doesn't require reading the conversation to understand
-- [ ] **Minimal** — no content that doesn't directly serve the next agent's work
-- [ ] **Verified** — decisions cite evidence (file:line, test output, tool result)
-
-If any criterion fails, compress further or add the missing context.
-
+Cold-start test: can new agent resume correctly on first attempt?
+- [ ] **Actionable**
+- [ ] **Self-contained**
+- [ ] **Minimal**
+- [ ] **Verified**
 ## CREATE Workflow
-
 ### 1. Choose storage target
-
-Save the full handoff at one of these locations:
 - Flow-scoped: \`.aikit-state/handoffs/{flow-slug}/YYYY-MM-DD-HHMMSS-[slug].md\`
 - Standalone: \`.aikit-state/handoffs/_standalone/YYYY-MM-DD-HHMMSS-[slug].md\`
-
-Use a slug that describes the active task, not the conversation.
-
 ### 2. Gather only critical-path facts
-
-Before writing, capture the minimum context needed for a cold start:
-- Current state: what is done, in progress, failing, or pending
-- Key files: exact paths and why they matter
-- Decisions: what was chosen and why
-- Verification: tests, checks, tool results, or specific evidence
-- Blockers: error text, attempted fixes, untried options
-- Next steps: ordered, concrete actions
-
-Use AI Kit tools inline instead of external scripts:
-- \`stash({ action: "set", key: "handoff:<slug>:notes", value })\` for temporary compression while drafting
-- \`checkpoint({ action: "save", label: "handoff-<slug>", notes })\` when session state itself matters
-- \`knowledge({ action: "list", category: "decisions" })\` and \`search({ query })\` to pull prior decisions into the handoff when relevant
-
+- Current state
+- Key files + why they matter
+- Decisions + why
+- Verification evidence
+- Blockers + tried/untried paths
+- Ordered next steps
+- \`stash({ action: "set", key: "handoff:<slug>:notes", value })\`
+- \`knowledge({ action: "list", category: "decisions" })\` + \`search({ query })\`
 ### 3. Write the full handoff
-
-Use this structure:
-
 \`\`\`md
 # Handoff: <task>
-
 ## Current State
 - Status:
 - Last completed step:
 - Current failure or pending task:
-
 ## Critical Files
 - path/to/file - purpose + why it matters now
-
 ## Decisions
 - Decision: why
 - Evidence: file:line | test output | tool result
-
 ## Next Steps
 1. First action
 2. Second action
 3. Third action
-
 ## Blockers
 - Blocker:
 - Tried:
 - Not tried yet:
-
 ## Gotchas
 - Non-obvious constraint or pattern
 \`\`\`
-
-Use [references/handoff-template.md](references/handoff-template.md) when you need a fuller structure, but delete sections that add no value.
-
+Use [references/handoff-template.md](references/handoff-template.md) if needed.
 ### 4. Save compact flow knowledge
-
-Store a compressed version for automatic resume:
-
 \`\`\`
 knowledge({
   action: "remember",
@@ -1436,70 +695,38 @@ Blockers: ...
 Evidence: ..."
 })
 \`\`\`
-
-Target 1-2K characters. This is the resume fast-path.
-
+Target 1-2K chars.
 ### 5. Self-review before finalizing
-
-Confirm all of the following:
-- No secrets, tokens, or raw credentials
-- No pasted file dumps
-- Every decision includes rationale
-- Every blocker includes attempted and untried paths
-- Next step #1 is immediately executable
-- Quality Gate score is 4/4
-
+- No secrets or file dumps
+- Decisions include rationale
+- Blockers include tried + untried paths
+- Next step #1 is executable
+- Quality Gate is 4/4
 ## RESUME Workflow
-
 ### 1. Pull compact context first
-
-Start with:
-
 \`\`\`
 knowledge({ action: "withdraw", scope: "flow", profile: "implementer", budget: 6000 })
 \`\`\`
-
-If the entry is truncated or multiple handoffs exist, use:
-
+If entry is truncated or multiple handoffs exist, use:
 \`\`\`
 knowledge({ action: "list", category: "session", scope: "flow" })
 knowledge({ action: "read", path: "<handoff-entry>" })
 \`\`\`
-
 ### 2. Load the full handoff only when needed
-
-Open the markdown file in \`.aikit-state/handoffs/\` if the compact entry lacks enough detail to act safely.
-
+Open markdown file in \`.aikit-state/handoffs/\` only if compact entry is not enough.
 ### 3. Verify live state before coding
-
-Do a fast reality check:
-- Does current branch still match the handoff assumptions?
-- Do referenced files still exist?
-- Have blockers already been resolved?
-- Do stated next steps still make sense against current diff and tests?
-
-Use the checklist in [references/resume-checklist.md](references/resume-checklist.md) for the verification pass.
-
+- Branch still matches assumptions?
+- Referenced files still exist?
+- Blockers already resolved?
+- Next steps still fit current diff and tests?
+Use [references/resume-checklist.md](references/resume-checklist.md).
 ### 4. Resume from the first actionable step
-
-Begin with Next Step #1. If reality differs from the handoff, update the handoff or create a successor handoff instead of silently continuing on stale assumptions.
-
+Begin with Next Step #1. If reality differs, update handoff or create successor handoff.
 ## Chaining Rule
-
-For long-running work, create a successor handoff instead of overwriting history. Each new handoff should state what it supersedes and what changed since the previous handoff.
-
+Create successor handoff instead of overwriting history.
 ## Output Expectations
-
-When asked to create a handoff, return:
-- Handoff status
-- File path written
-- Key decisions captured
-- Top blocker or next step
-
-Do not return conversation transcripts or visual dashboards.
-
+Return status, file path, decisions, blocker/next step.
 ## Resources
-
-- [references/handoff-template.md](references/handoff-template.md) - full markdown template when a simple structure is insufficient
-- [references/resume-checklist.md](references/resume-checklist.md) - verification checklist before resuming from saved context
+- [references/handoff-template.md](references/handoff-template.md)
+- [references/resume-checklist.md](references/resume-checklist.md)
 `}];export{e as default};