@vpxa/aikit 0.1.274 → 0.1.275

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

@@ -1,732 +1,2 @@
-var e=[{file:`references/handoff-template.md`,content:`# Handoff Template
-Use this template.
-## Table of Contents
-Use headings
----
-# Handoff: [TASK_TITLE]
-## Session Metadata
-- Created: [TIMESTAMP]
-- Project: [PROJECT_PATH]
-- Branch: [GIT_BRANCH]
-- Session duration: [APPROX_DURATION]
-## Current State Summary
-[One paragraph: work, status, handoff point]
-## Codebase Understanding
-### Architecture Overview
-[Key architecture insights]
-### Critical Files
-| File | Purpose | Relevance |
-|------|---------|-----------|
-| path/to/file | Purpose | Why it matters now |
-### Key Patterns Discovered
-[Patterns next agent should follow]
-## Work Completed
-### Tasks Finished
-- [x] Task 1 - what was done
-- [x] Task 2 - brief description
-### Files Modified
-| File | Changes | Rationale |
-|------|---------|-----------|
-| path/to/file | Changes | Why |
-### Decisions Made
-| Decision | Options Considered | Rationale |
-|----------|-------------------|-----------|
-| Chose X over Y | X, Y, Z | Why |
-## Pending Work
-### Immediate Next Steps
-1. [First action]
-2. [Second action]
-3. [Third action]
-### Blockers/Open Questions
-- [ ] Blocker: [description] - Needs: [unblocker]
-- [ ] Question: [unclear aspect] - Suggested: [resolution]
-### Deferred Items
-- Item 1 (deferred: [reason])
-## Context for Resuming Agent
-### Important Context
-[Critical information next agent MUST know]
-### Assumptions Made
-- Assumption 1: [assumed true]
-- Assumption 2: [another assumption]
-### Potential Gotchas
-- [Things that might trip up next agent]
-## Environment State
-### Tools/Services Used
-- [Tool/Service]: [relevant state]
-### Active Processes
-- [Background processes, dev servers, watchers]
-### Environment Variables
-- [Env vars that matter - names only, no values]
-## Related Resources
-- [Relevant docs]
-- [Related file paths]
-- [External resources consulted]
----
-## Template Usage Notes
-Be specific. Use file refs when useful. Exclude secrets. Capture WHAT and WHY.
-`},{file:`references/resume-checklist.md`,content:`# Resume Checklist
-On resume.
-## Pre-Resume Verification
-- [ ] Read handoff before acting
-- [ ] Verify project directory
-- [ ] Confirm branch matches or note why it differs
-- [ ] Check handoff timestamp
-## Context Validation
-- [ ] Review important context
-- [ ] Check assumptions
-- [ ] Check resolved blockers
-- [ ] Review gotchas
-## State Verification
-- [ ] Run \`git status\`
-- [ ] Compare modified files vs current state
-- [ ] Check required env vars
-- [ ] Verify required services/processes
-## Resume Execution
-- [ ] Start with next step #1
-- [ ] Apply documented patterns
-## During Work
-- [ ] Update handoff if major context changes
-- [ ] Add new blockers/questions
-## Red Flags - Stop and Verify
-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
-\`\`\`bash
-git branch --show-current
-git status
-git log --oneline -10
-ps aux | grep [process-name]
-env | grep [relevant-var]
-\`\`\`
-## Handoff Quality Assessment
-Re-explore if weak.
-`},{file:`scripts/check_staleness.js`,content:`#!/usr/bin/env node
-const fs = require('node:fs');
-const path = require('node:path');
-const { execSync } = require('node:child_process');
-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 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 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) + "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)));
-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 / 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) 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(", "));
-}
-}
-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
-const fs = require('node:fs');
-const path = require('node:path');
-const { execSync } = require('node:child_process');
-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 };
-}
-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 --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 from = null; let flow = null;
-for (let i = 0; i < args.length; i++) {
-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
-const fs = require('node:fs');
-const path = require('node:path');
-function extractTitle(filepath) {
-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 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 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); }
-const projectPath = args[0] || process.cwd();
-const handoffs = listHandoffs(projectPath);
-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
-const fs = require('node:fs');
-const path = require('node:path');
-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 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'];
-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*' + 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*' + 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;
-}
-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 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 resolveProjectRootFromHandoff(filepath) {
-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: 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) 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); }
-}
-const args = process.argv.slice(2);
-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 handoff docs for session transfer. Trigger on save-context, high context pressure, milestones, session end, or resume requests."
-metadata:
-  category: cross-cutting
-  domain: general
-  applicability: always
-  inputs: [session-state, decisions]
-  outputs: [handoff-document, flow-knowledge-entry]
-  requires: [aikit]
-  relatedSkills: [lesson-learned]
----
-# Session Handoff
-Handoffs.
-## Mindset
-Keep only state, decisions + why, blockers, next step, gotchas.
-## Quick Reference
-- **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**
-- **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
-Cold-start test: can new agent resume correctly on first attempt?
-- [ ] **Actionable**
-- [ ] **Self-contained**
-- [ ] **Minimal**
-- [ ] **Verified**
-## CREATE Workflow
-### 1. Choose storage target
-- Flow-scoped: \`.aikit-state/handoffs/{flow-slug}/YYYY-MM-DD-HHMMSS-[slug].md\`
-- Standalone: \`.aikit-state/handoffs/_standalone/YYYY-MM-DD-HHMMSS-[slug].md\`
-### 2. Gather only critical-path facts
-- 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
-\`\`\`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) if needed.
-### 4. Save compact flow knowledge
-\`\`\`
-knowledge({
-  action: "remember",
-  scope: "flow",
-  category: "session",
-  title: "Session Handoff: <slug>",
-  content: "State: ...
-Decisions: ...
-Next: ...
-Blockers: ...
-Evidence: ..."
-})
-\`\`\`
-Target 1-2K chars.
-### 5. Self-review before finalizing
-- 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
-\`\`\`
-knowledge({ action: "withdraw", scope: "flow", profile: "implementer", budget: 6000 })
-\`\`\`
-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 markdown file in \`.aikit-state/handoffs/\` only if compact entry is not enough.
-### 3. Verify live state before coding
-- 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, update handoff or create successor handoff.
-## Chaining Rule
-Create successor handoff instead of overwriting history.
-## Output Expectations
-Return status, file path, decisions, blocker/next step.
-## Resources
-- [references/handoff-template.md](references/handoff-template.md)
-- [references/resume-checklist.md](references/resume-checklist.md)
-`}];export{e as default};
+const e=e=>e.join(`
+`),t=[`const path = require('node:path');`,`const os = require('node:os');`,`const { createHash } = require('node:crypto');`,``,`function computePartitionKey(cwd) {`,`  const absolutePath = path.resolve(cwd);`,`  const baseName = path.basename(absolutePath).replace(/[^a-zA-Z0-9-]/g, '-') || 'workspace';`,`  const hash = createHash('sha256').update(absolutePath).digest('hex').slice(0, 8);`,`  return baseName + '-' + hash;`,`}`,``,`function getHandoffDir(cwd) {`,`  return path.join(os.homedir(), '.aikit', 'workspaces', computePartitionKey(cwd), 'handoffs');`,`}`,``,`function isContainedPath(rootPath, targetPath) {`,`  const relativePath = path.relative(rootPath, targetPath);`,`  return !relativePath.startsWith('..') && !path.isAbsolute(relativePath);`,`}`];var n=[{file:`references/handoff-template.md`,content:e(`# Handoff Template((Runtime path: ~/.aikit/workspaces/<workspace-hash>/handoffs/YYYY-MM-DD-HHMMSS-[slug].md(.flows/ stays workspace-local for flow state only.((## Current State(- Status:(- Last completed step:(- Current blocker:((## Decisions(- Decision:(- Why:(- Evidence:((## Next Steps(1.(2.(3.((## Blockers(- Blocker:(- Tried:(- Not tried:((## Gotchas(- Constraints, caveats, or follow-up notes.((Keep it compact, self-contained, and free of secrets.`.split(`(`))},{file:`references/resume-checklist.md`,content:e([`# Resume Checklist`,``,`- Open the latest handoff from ~/.aikit/workspaces/<workspace-hash>/handoffs/.`,`- Confirm branch and working tree.`,`- Review decisions, blockers, and gotchas.`,`- Resume from the first unfinished next step.`])},{file:`scripts/create_handoff.js`,content:e([`#!/usr/bin/env node`,`const fs = require('node:fs');`,...t,``,`function formatTimestamp(date) {`,`  const iso = date.toISOString();`,`  return iso.slice(0, 10) + '-' + iso.slice(11, 13) + iso.slice(14, 16) + iso.slice(17, 19);`,`}`,``,`function slugify(value) {`,`  return String(value || 'handoff').toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '') || 'handoff';`,`}`,``,`const handoffDir = getHandoffDir(process.cwd());`,`fs.mkdirSync(handoffDir, { recursive: true });`,``,`const filePath = path.join(handoffDir, formatTimestamp(new Date()) + '-' + slugify(process.argv[2]) + '.md');`,`const content = [`,`  '# Handoff',`,`  '',`,`  '## Current State',`,`  '- Status: draft',`,`  '- Last completed step:',`,`  '- Current blocker:',`,`  '',`,`  '## Decisions',`,`  '- Decision:',`,`  '- Why:',`,`  '- Evidence:',`,`  '',`,`  '## Next Steps',`,`  '1.',`,`  '2.',`,`  '3.',`,`  '',`,`  '## Blockers',`,`  '- Blocker:',`,`  '- Tried:',`,`  '- Not tried:',`,`  '',`,`  '## Gotchas',`,`  '- Constraints, caveats, or follow-up notes.',`,`]).join('\\n');`,``,`fs.writeFileSync(filePath, content, 'utf8');`,`process.stdout.write(filePath + '\\n');`])},{file:`scripts/list_handoffs.js`,content:e([`#!/usr/bin/env node`,`const fs = require('node:fs');`,...t,``,`const handoffDir = getHandoffDir(process.cwd());`,``,`if (!fs.existsSync(handoffDir)) {`,`  process.exit(0);`,`}`,``,`for (const entry of fs.readdirSync(handoffDir).filter((name) => name.endsWith('.md')).sort()) {`,`  const filePath = path.join(handoffDir, entry);`,`  const stat = fs.statSync(filePath);`,`  process.stdout.write(entry + '\\t' + stat.size + '\\t' + stat.mtime.toISOString() + '\\n');`,`}`])},{file:`scripts/check_staleness.js`,content:e([`#!/usr/bin/env node`,`const fs = require('node:fs');`,...t,``,`const staleAfterDays = Number(process.argv[2] || 30);`,`const handoffDir = getHandoffDir(process.cwd());`,``,`if (!fs.existsSync(handoffDir)) {`,`  process.stderr.write('Missing handoff dir: ' + handoffDir + '\\n');`,`  process.exit(1);`,`}`,``,`const now = Date.now();`,``,`for (const entry of fs.readdirSync(handoffDir).filter((name) => name.endsWith('.md')).sort()) {`,`  const filePath = path.join(handoffDir, entry);`,`  const ageDays = (now - fs.statSync(filePath).mtimeMs) / 86400000;`,`  if (ageDays > staleAfterDays) {`,`    process.stdout.write(entry + '\\t' + ageDays.toFixed(1) + 'd\\n');`,`  }`,`}`])},{file:`scripts/validate_handoff.js`,content:e([`#!/usr/bin/env node`,`const fs = require('node:fs');`,...t,``,`const REQUIRED_SECTIONS = [`,`  '## Current State',`,`  '## Decisions',`,`  '## Next Steps',`,`  '## Blockers',`,`  '## Gotchas',`,`];`,``,`function isRuntimeHandoff(filePath) {`,`  const absolutePath = path.resolve(filePath);`,`  const runtimeRoot = path.join(os.homedir(), '.aikit', 'workspaces');`,``,`  if (!isContainedPath(runtimeRoot, absolutePath)) {`,`    return false;`,`  }`,``,`  const relativePath = path.relative(runtimeRoot, absolutePath);`,`  const parts = relativePath.split(path.sep);`,`  return parts.length >= 3 && parts[1] === 'handoffs';`,`}`,``,`function validate(filePath) {`,`  const absolutePath = path.resolve(filePath);`,``,`  if (!isRuntimeHandoff(absolutePath)) {`,`    throw new Error('Handoff must live under ~/.aikit/workspaces/<workspace-hash>/handoffs/');`,`  }`,``,`  const content = fs.readFileSync(absolutePath, 'utf8');`,``,`  for (const section of REQUIRED_SECTIONS) {`,`    if (!content.includes(section)) {`,`      throw new Error('Missing section: ' + section);`,`    }`,`  }`,`}`,``,`const filePath = process.argv[2];`,``,`if (!filePath) {`,`  process.stderr.write('Usage: validate_handoff.js <handoff-file>\\n');`,`  process.exit(1);`,`}`,``,`validate(filePath);`,`process.stdout.write('OK\\n');`])},{file:`SKILL.md`,content:e(`---(name: session-handoff(description: "Create and resume session handoff docs."(metadata:(  category: cross-cutting(  domain: general(  applicability: always(  inputs: [session-state, decisions](  outputs: [handoff-document, resume-checklist](  requires: [aikit](  relatedSkills: [lesson-learned](---(# Session Handoff((Use when work needs a durable pause point.((## Runtime Location(- Full handoff docs live at ~/.aikit/workspaces/<workspace-hash>/handoffs/YYYY-MM-DD-HHMMSS-[slug].md(- .flows/ stays workspace-local for flow state only.((## Create(- Capture state, decisions, next steps, blockers, and gotchas.(- Keep it compact, self-contained, and secret-free.(- Write the file to the runtime handoff directory.((## Resume(- Open the latest handoff for the current workspace.(- Verify branch and worktree.(- Continue from the first unfinished next step.`.split(`(`))}];export{n as default};