@kingkyylian/handoffkit 0.1.1 → 0.3.0

package/dist/index.js

@@ -7,6 +7,64 @@ import { Command as Command6 } from "commander";
 import { Command } from "commander";
 import { z as z2 } from "zod";
 
+// src/core/cache.ts
+import { mkdir, writeFile } from "fs/promises";
+import { join } from "path";
+
+// src/core/redact.ts
+var REDACTION = "[REDACTED]";
+var SECRET_KEY_PATTERN = /(\b(?:[A-Z0-9]+[_.-])*(?:API[_-]?KEY|TOKEN|SECRET|PASSWORD|PASSWD|PRIVATE[_-]?KEY|CLIENT[_-]?SECRET|ACCESS[_-]?TOKEN|REFRESH[_-]?TOKEN|COOKIE|SESSION|JWT|AUTH_TOKEN)(?:[_.-][A-Z0-9]+)*\b\s*(?:=|:)\s*)(["']?)([^\s"',}]+)/gi;
+var TOKEN_PATTERNS = [
+  /\bBearer\s+[A-Za-z0-9._~+/=-]{12,}/gi,
+  /\bsk-[A-Za-z0-9_-]{16,}/g,
+  /\bgh[pousr]_[A-Za-z0-9_]{16,}/g,
+  /\bnpm_[A-Za-z0-9_-]{16,}/g,
+  /\bxox[baprs]-[A-Za-z0-9-]{16,}/g,
+  /\bAIza[0-9A-Za-z_-]{20,}/g,
+  /\bAKIA[0-9A-Z]{16}\b/g,
+  /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g,
+  /\/\/([^/\s:@]+):([^@\s/]+)@/g
+];
+function redactText(input) {
+  let output = input.replace(
+    /-----BEGIN ([A-Z ]*PRIVATE KEY)-----[\s\S]*?-----END \1-----/g,
+    (_match, keyType) => `-----BEGIN ${keyType}-----
+${REDACTION}
+-----END ${keyType}-----`
+  );
+  output = output.replace(SECRET_KEY_PATTERN, (_match, prefix, quote) => {
+    return `${prefix}${quote}${REDACTION}${quote}`;
+  });
+  output = output.replace(/\bBearer\s+[A-Za-z0-9._~+/=-]{12,}/gi, "Bearer [REDACTED]");
+  output = output.replace(/\/\/([^/\s:@]+):([^@\s/]+)@/g, "//[REDACTED]@");
+  for (const pattern of TOKEN_PATTERNS.slice(1, -1)) {
+    output = output.replace(pattern, REDACTION);
+  }
+  return output;
+}
+
+// src/core/cache.ts
+async function writeCacheArtifact(root, kind, data, options = {}) {
+  const createdAt = (options.now ?? /* @__PURE__ */ new Date()).toISOString();
+  const envelope = {
+    version: 1,
+    kind,
+    createdAt,
+    data
+  };
+  const cacheDir = join(root, ".handoffkit", kind);
+  const artifactPath = join(cacheDir, `${cacheTimestamp(createdAt)}.json`);
+  const latestPath = join(cacheDir, "latest.json");
+  const contents = `${redactText(JSON.stringify(envelope, null, 2))}
+`;
+  await mkdir(cacheDir, { recursive: true });
+  await Promise.all([writeFile(artifactPath, contents, "utf8"), writeFile(latestPath, contents, "utf8")]);
+  return { artifactPath, latestPath };
+}
+function cacheTimestamp(timestamp) {
+  return timestamp.replace(/[:.]/g, "-");
+}
+
 // src/core/git.ts
 import { readFile } from "fs/promises";
 import { basename } from "path";
@@ -26,7 +84,7 @@ function formatCliError(error) {
 
 // src/core/git.ts
 var UNTRACKED_PATCH_CHAR_LIMIT = 2e4;
-var IGNORED_CHANGED_PATH_PREFIXES = ["node_modules/", "dist/", "coverage/", ".git/"];
+var IGNORED_CHANGED_PATH_PREFIXES = ["node_modules/", "dist/", "coverage/", ".git/", ".handoffkit/"];
 async function findGitRoot(cwd) {
   const result = await execa("git", ["rev-parse", "--show-toplevel"], {
     cwd,
@@ -160,40 +218,6 @@ function isIgnoredChangedPath(file) {
 // src/core/instructions.ts
 import { readFile as readFile2, stat } from "fs/promises";
 import fg from "fast-glob";
-
-// src/core/redact.ts
-var REDACTION = "[REDACTED]";
-var SECRET_KEY_PATTERN = /(\b[A-Z0-9_.-]*(?:API[_-]?KEY|TOKEN|SECRET|PASSWORD|PASSWD|PRIVATE[_-]?KEY|CLIENT[_-]?SECRET|ACCESS[_-]?TOKEN|REFRESH[_-]?TOKEN|COOKIE|SESSION|JWT|AUTH_TOKEN)[A-Z0-9_.-]*\b\s*(?:=|:)\s*)(["']?)([^\s"',}]+)/gi;
-var TOKEN_PATTERNS = [
-  /\bBearer\s+[A-Za-z0-9._~+/=-]{12,}/gi,
-  /\bsk-[A-Za-z0-9_-]{16,}/g,
-  /\bgh[pousr]_[A-Za-z0-9_]{16,}/g,
-  /\bnpm_[A-Za-z0-9_-]{16,}/g,
-  /\bxox[baprs]-[A-Za-z0-9-]{16,}/g,
-  /\bAIza[0-9A-Za-z_-]{20,}/g,
-  /\bAKIA[0-9A-Z]{16}\b/g,
-  /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g,
-  /\/\/([^/\s:@]+):([^@\s/]+)@/g
-];
-function redactText(input) {
-  let output = input.replace(
-    /-----BEGIN ([A-Z ]*PRIVATE KEY)-----[\s\S]*?-----END \1-----/g,
-    (_match, keyType) => `-----BEGIN ${keyType}-----
-${REDACTION}
------END ${keyType}-----`
-  );
-  output = output.replace(SECRET_KEY_PATTERN, (_match, prefix, quote) => {
-    return `${prefix}${quote}${REDACTION}${quote}`;
-  });
-  output = output.replace(/\bBearer\s+[A-Za-z0-9._~+/=-]{12,}/gi, "Bearer [REDACTED]");
-  output = output.replace(/\/\/([^/\s:@]+):([^@\s/]+)@/g, "//[REDACTED]@");
-  for (const pattern of TOKEN_PATTERNS.slice(1, -1)) {
-    output = output.replace(pattern, REDACTION);
-  }
-  return output;
-}
-
-// src/core/instructions.ts
 var INSTRUCTION_PATTERNS = [
   "**/AGENTS.md",
   "**/CLAUDE.md",
@@ -253,7 +277,7 @@ function instructionKind(path) {
 
 // src/core/package-json.ts
 import { access, readFile as readFile3 } from "fs/promises";
-import { join } from "path";
+import { join as join2 } from "path";
 import { z } from "zod";
 var PackageJsonSchema = z.object({
   name: z.string().optional(),
@@ -263,7 +287,7 @@ var PackageJsonSchema = z.object({
 var VERIFY_SCRIPT_ORDER = ["build", "test", "typecheck", "lint", "check", "verify", "ci"];
 var VERIFY_SCRIPT_PREFIX = /^(build|test|typecheck|lint|check|verify|ci)(:|$)/;
 async function detectPackageInfo(root) {
-  const packageJsonPath = join(root, "package.json");
+  const packageJsonPath = join2(root, "package.json");
   if (!await pathExists(packageJsonPath)) {
     return void 0;
   }
@@ -289,7 +313,7 @@ async function detectPackageManager(root, packageManagerField) {
     ["bun.lockb", "bun"]
   ];
   for (const [lockfile, manager] of lockfiles) {
-    if (await pathExists(join(root, lockfile))) {
+    if (await pathExists(join2(root, lockfile))) {
       return manager;
     }
   }
@@ -320,29 +344,73 @@ function orderIndex(name) {
 }
 
 // src/core/risk.ts
+var RISK_RULES = [
+  {
+    severity: "high",
+    title: "Security-sensitive code changed",
+    detail: "Review redaction, auth, token, or secret-handling changes carefully before handoff.",
+    matches: (file) => /(^|\/)(redact|secret|auth|token|security)/i.test(file)
+  },
+  {
+    severity: "high",
+    title: "Release or package publishing path changed",
+    detail: "Release and package changes can break install, provenance, or publish flow; run pnpm pack:dry-run and pnpm smoke:release before tagging or publishing.",
+    matches: isReleaseOrPackageFile
+  },
+  {
+    severity: "medium",
+    title: "CI workflow changed",
+    detail: "Workflow changes can fail only after push; confirm GitHub Actions still passes on the target branch.",
+    matches: (file) => file.startsWith(".github/workflows/")
+  },
+  {
+    severity: "medium",
+    title: "Build tooling or TypeScript config changed",
+    detail: "Tooling changes can break typecheck, lint, build output, or package entrypoints; run the full local check command.",
+    matches: isBuildToolingFile
+  },
+  {
+    severity: "medium",
+    title: "CLI behavior changed",
+    detail: "CLI entrypoint or command changes can break user-facing flags and output contracts; cover the changed command with unit or integration tests.",
+    matches: (file) => file.startsWith("src/cli/")
+  },
+  {
+    severity: "medium",
+    title: "Resume parsing changed",
+    detail: "Resume parser changes can drop handoff context; verify completed work, next steps, failures, and open questions are still extracted.",
+    matches: (file) => file === "src/core/resume.ts" || file.includes("/resume")
+  },
+  {
+    severity: "medium",
+    title: "Handoff report rendering changed",
+    detail: "Report rendering changes can hide critical context; verify Markdown and JSON output still include repository, verification, risk, and next-step sections.",
+    matches: (file) => file.startsWith("src/report/")
+  },
+  {
+    severity: "medium",
+    title: "Generated artifact or ignore policy changed",
+    detail: "Ignore/cache policy changes can pollute changedFiles or published packages; verify generated directories remain ignored and excluded from reports.",
+    matches: isGeneratedOrIgnorePolicyFile
+  },
+  {
+    severity: "low",
+    title: "Documentation changed",
+    detail: "Documentation-only changes still need examples, command names, and release instructions checked against the current CLI behavior.",
+    matches: isDocumentationFile
+  }
+];
 function analyzeRisk(report) {
   const files = report.repository.changedFiles;
   const notes = [];
-  if (files.some((file) => /(^|\/)(redact|secret|auth|token|security)/i.test(file))) {
-    notes.push({
-      severity: "high",
-      title: "Security-sensitive code changed",
-      detail: "Review redaction, auth, token, or secret-handling changes carefully before handoff."
-    });
-  }
-  if (files.some((file) => file === "package.json" || file.endsWith("-lock.yaml") || file.endsWith("lock.json"))) {
-    notes.push({
-      severity: "medium",
-      title: "Dependency or package metadata changed",
-      detail: "Run install/build verification and check package publishing metadata."
-    });
-  }
-  if (files.some((file) => file.startsWith(".github/workflows/"))) {
-    notes.push({
-      severity: "medium",
-      title: "CI workflow changed",
-      detail: "Confirm GitHub Actions still passes after push."
-    });
+  for (const rule of RISK_RULES) {
+    if (files.some(rule.matches)) {
+      notes.push({
+        severity: rule.severity,
+        title: rule.title,
+        detail: rule.detail
+      });
+    }
   }
   const sourceFiles = files.filter((file) => file.startsWith("src/") && file.endsWith(".ts"));
   const testFiles = files.filter((file) => file.startsWith("tests/") && file.endsWith(".test.ts"));
@@ -362,21 +430,34 @@ function analyzeRisk(report) {
   }
   return { notes };
 }
+function isReleaseOrPackageFile(file) {
+  return file === "package.json" || file === "CHANGELOG.md" || file === "docs/RELEASE.md" || file === "scripts/release-smoke.mjs" || /^\.github\/workflows\/.*release.*\.ya?ml$/i.test(file) || /(^|\/)(pnpm-lock\.yaml|package-lock\.json|yarn\.lock|bun\.lockb?)$/i.test(file);
+}
+function isBuildToolingFile(file) {
+  return /(^|\/)(tsconfig(?:\.[^/]*)?\.json|tsup\.config\.ts|vitest\.config\.ts|eslint\.config\.[cm]?[jt]s|pnpm-workspace\.yaml)$/i.test(file) || file.startsWith("scripts/");
+}
+function isGeneratedOrIgnorePolicyFile(file) {
+  return file === ".gitignore" || file === ".npmignore" || file.startsWith(".handoffkit/") || file.startsWith("docs/checkpoints/") || /(^|\/)(dist|coverage|node_modules|\.tmp-tests)\//.test(file);
+}
+function isDocumentationFile(file) {
+  return file === "README.md" || file === "ROADMAP.md" || file === "CONTRIBUTING.md" || file === "SECURITY.md" || file.startsWith("docs/");
+}
 
 // src/core/scanners.ts
 import { mkdtemp, readFile as readFile4 } from "fs/promises";
 import { tmpdir } from "os";
-import { relative, join as join2 } from "path";
+import { relative, join as join3 } from "path";
 import { performance } from "perf_hooks";
 import { execa as execa2 } from "execa";
+import fg2 from "fast-glob";
 var MAX_FINDINGS = 20;
 var ERROR_LIMIT = 2e3;
-async function detectSecretScanners() {
-  const [gitleaks, secretlint] = await Promise.all([scannerStatus("gitleaks"), scannerStatus("secretlint")]);
+async function detectSecretScanners(root = process.cwd()) {
+  const [gitleaks, secretlint] = await Promise.all([scannerStatus("gitleaks", root), scannerStatus("secretlint", root)]);
   return { scanners: [gitleaks, secretlint] };
 }
 async function runSecretScanners(root) {
-  const report = await detectSecretScanners();
+  const report = await detectSecretScanners(root);
   const scans = await Promise.all(report.scanners.map((scanner) => runScanner(root, scanner)));
   return { ...report, scans };
 }
@@ -422,14 +503,18 @@ function normalizeSecretlintFindings(rawJson, limit = MAX_FINDINGS, root) {
   }
   return findings;
 }
-async function scannerStatus(name) {
+async function scannerStatus(name, root) {
   const result = await execa2(name, ["--version"], {
     reject: false
   }).catch(() => void 0);
+  const configFiles = await scannerConfigFiles(name, root);
   return {
     name,
     available: Boolean(result && result.exitCode === 0),
-    ...result?.stdout ? { version: result.stdout.trim() } : {}
+    ...result?.stdout ? { version: result.stdout.trim() } : {},
+    configFiles,
+    configHint: configHint(name, configFiles),
+    installHint: installHint(name)
   };
 }
 async function runScanner(root, scanner) {
@@ -447,8 +532,8 @@ async function runScanner(root, scanner) {
 }
 async function runGitleaks(root) {
   const started = performance.now();
-  const tempDir = await mkdtemp(join2(tmpdir(), "handoffkit-gitleaks-"));
-  const reportPath = join2(tempDir, "report.json");
+  const tempDir = await mkdtemp(join3(tmpdir(), "handoffkit-gitleaks-"));
+  const reportPath = join3(tempDir, "report.json");
   const result = await execa2(
     "gitleaks",
     ["dir", root, "--no-banner", "--no-color", "--redact=100", "--report-format", "json", "--report-path", reportPath, "--max-target-megabytes", "2"],
@@ -518,6 +603,25 @@ function trimError(output) {
   return trimmed.length > ERROR_LIMIT ? `${trimmed.slice(0, ERROR_LIMIT)}
 [truncated]` : trimmed;
 }
+async function scannerConfigFiles(name, root) {
+  const patterns = name === "gitleaks" ? ["gitleaks.toml", ".gitleaks.toml", ".gitleaksignore", ".config/gitleaks/*.toml"] : [".secretlintrc", ".secretlintrc.*", "secretlint.config.*"];
+  const matches = await fg2(patterns, {
+    cwd: root,
+    dot: true,
+    onlyFiles: true,
+    unique: true
+  });
+  return matches.sort();
+}
+function configHint(name, configFiles) {
+  if (configFiles.length > 0) {
+    return `config: ${configFiles.join(", ")}`;
+  }
+  return name === "gitleaks" ? "config: none detected; optional files include .gitleaks.toml, gitleaks.toml, or .config/gitleaks/*.toml" : "config: none detected; optional files include .secretlintrc.*, .secretlintrc, or secretlint.config.*";
+}
+function installHint(name) {
+  return name === "gitleaks" ? "Install gitleaks from https://github.com/gitleaks/gitleaks, then rerun with --scan-secrets." : "Install secretlint from https://github.com/secretlint/secretlint, then rerun with --scan-secrets.";
+}
 
 // src/core/verify.ts
 import { performance as performance2 } from "perf_hooks";
@@ -572,7 +676,7 @@ async function collectHandoffReport(options) {
     }),
     detectInstructionFiles(root),
     detectPackageInfo(root),
-    options.scanSecrets ? runSecretScanners(root) : detectSecretScanners()
+    options.scanSecrets ? runSecretScanners(root) : detectSecretScanners(root)
   ]);
   const report = {
     goal: options.goal,
@@ -594,7 +698,7 @@ async function collectHandoffReport(options) {
 }
 
 // src/cli/output.ts
-import { mkdir, writeFile } from "fs/promises";
+import { mkdir as mkdir2, writeFile as writeFile2 } from "fs/promises";
 import { dirname, resolve } from "path";
 
 // src/core/budget.ts
@@ -625,84 +729,176 @@ function renderJsonReport(report) {
 `;
 }
 
+// src/report/profiles.ts
+var genericOrder = [
+  "goal",
+  "repository",
+  "gitStatus",
+  "recentCommits",
+  "changedFiles",
+  "branchDelta",
+  "diffSummary",
+  "includedBranchDelta",
+  "includedDiff",
+  "instructionFiles",
+  "package",
+  "resume",
+  "verification",
+  "risk",
+  "secretScanning"
+];
+var profiles = {
+  generic: {
+    title: "Handoff Packet",
+    sectionOrder: genericOrder,
+    nextAgentNotes: [
+      "Use this packet as the starting context for the next coding session.",
+      "Verify commands locally before claiming completion."
+    ]
+  },
+  codex: {
+    title: "Codex Handoff Packet",
+    sectionOrder: [
+      "goal",
+      "repository",
+      "gitStatus",
+      "changedFiles",
+      "verification",
+      "risk",
+      "branchDelta",
+      "diffSummary",
+      "includedBranchDelta",
+      "includedDiff",
+      "instructionFiles",
+      "package",
+      "resume",
+      "secretScanning",
+      "recentCommits"
+    ],
+    nextAgentNotes: [
+      "Start by reading the goal, repository status, changed files, and verification state.",
+      "Use local tools to inspect files before editing; do not assume hidden context.",
+      "Keep edits scoped and rerun the relevant verification before reporting completion."
+    ]
+  },
+  claude: {
+    title: "Claude Code Handoff Packet",
+    sectionOrder: [
+      "goal",
+      "resume",
+      "repository",
+      "verification",
+      "risk",
+      "changedFiles",
+      "gitStatus",
+      "branchDelta",
+      "diffSummary",
+      "includedBranchDelta",
+      "includedDiff",
+      "instructionFiles",
+      "package",
+      "secretScanning",
+      "recentCommits"
+    ],
+    nextAgentNotes: [
+      "Treat this as concise project memory plus current branch state.",
+      "Use the resume state to separate completed work from remaining work.",
+      "Ask for clarification only when the packet leaves a blocking ambiguity."
+    ]
+  },
+  cursor: {
+    title: "Cursor Handoff Packet",
+    sectionOrder: [
+      "goal",
+      "repository",
+      "changedFiles",
+      "gitStatus",
+      "includedDiff",
+      "diffSummary",
+      "branchDelta",
+      "includedBranchDelta",
+      "instructionFiles",
+      "package",
+      "verification",
+      "risk",
+      "resume",
+      "secretScanning",
+      "recentCommits"
+    ],
+    nextAgentNotes: [
+      "Open the changed files first to build editor context.",
+      "Use instruction files and package scripts to keep edits aligned with the workspace.",
+      "Prefer small edits and rerun the detected verification scripts."
+    ]
+  }
+};
+function profileForTarget(target) {
+  return profiles[target] ?? profiles.generic;
+}
+
 // src/report/markdown.ts
 function renderMarkdownReport(report) {
+  const profile = profileForTarget(report.target);
   const lines = [
-    `# ${titleForTarget(report.target)}`,
-    "",
-    "## Goal",
-    report.goal,
-    "",
-    "## Repository",
-    `- Repository: \`${report.repository.name}\``,
-    `- Branch: \`${report.repository.branch}\``,
-    `- Changed files: ${report.repository.changedFiles.length}`,
-    "",
-    "## Git Status",
-    codeBlock(report.repository.status || "Clean working tree."),
-    "",
-    "## Recent Commits",
-    listOrNone(report.repository.recentCommits.map((commit) => `- ${commit}`)),
-    "",
-    "## Changed Files",
-    listOrNone(report.repository.changedFiles.map((file) => `- \`${file}\``)),
-    "",
-    ...renderBaseDiffSummary(report),
-    "## Diff Summary",
-    "### Staged",
-    codeBlock(report.repository.stagedDiffSummary || "No staged diff."),
-    "",
-    "### Unstaged",
-    codeBlock(report.repository.unstagedDiffSummary || "No unstaged diff."),
-    "",
-    "## Instruction Files",
-    renderInstructionFiles(report.instructionFiles),
+    `# ${profile.title}`,
     "",
-    "## Package",
-    renderPackage(report.packageInfo),
-    "",
-    ...renderResumeSource(report),
-    ...renderVerification(report),
-    ...renderRisk(report),
-    ...renderSecretScanning(report),
+    ...profile.sectionOrder.flatMap((section) => renderSection(section, report)),
     "## Next Agent Notes",
+    ...profile.nextAgentNotes.map((note) => `- ${note}`),
     "- This packet was generated from local git and filesystem state.",
     "- Likely secrets were redacted from generated output.",
     "- No LLM APIs were called."
   ];
-  if (report.repository.includeDiff && report.repository.diff) {
-    lines.splice(
-      lines.indexOf("## Instruction Files"),
-      0,
-      "## Included Diff",
-      "### Staged Patch",
-      codeBlock(report.repository.diff.staged || "No staged patch."),
-      "",
-      "### Unstaged Patch",
-      codeBlock(report.repository.diff.unstaged || "No unstaged patch."),
-      ""
-    );
-  }
-  if (report.repository.includeDiff && report.repository.baseDiff) {
-    lines.splice(
-      lines.indexOf("## Included Diff"),
-      0,
-      `## Included Branch Delta Since \`${report.repository.baseRef}\``,
-      codeBlock(report.repository.baseDiff),
-      ""
-    );
-  }
   return `${lines.join("\n")}
 `;
 }
-function titleForTarget(target = "generic") {
-  const labels = {
-    generic: "Handoff Packet",
-    codex: "Codex Handoff Packet",
-    claude: "Claude Handoff Packet",
-    cursor: "Cursor Handoff Packet"
-  };
-  return labels[target] ?? "Handoff Packet";
+function renderSection(section, report) {
+  switch (section) {
+    case "goal":
+      return ["## Goal", report.goal, ""];
+    case "repository":
+      return [
+        "## Repository",
+        `- Repository: \`${report.repository.name}\``,
+        `- Branch: \`${report.repository.branch}\``,
+        `- Changed files: ${report.repository.changedFiles.length}`,
+        ""
+      ];
+    case "gitStatus":
+      return ["## Git Status", codeBlock(report.repository.status || "Clean working tree."), ""];
+    case "recentCommits":
+      return ["## Recent Commits", listOrNone(report.repository.recentCommits.map((commit) => `- ${commit}`)), ""];
+    case "changedFiles":
+      return ["## Changed Files", listOrNone(report.repository.changedFiles.map((file) => `- \`${file}\``)), ""];
+    case "branchDelta":
+      return renderBaseDiffSummary(report);
+    case "diffSummary":
+      return [
+        "## Diff Summary",
+        "### Staged",
+        codeBlock(report.repository.stagedDiffSummary || "No staged diff."),
+        "",
+        "### Unstaged",
+        codeBlock(report.repository.unstagedDiffSummary || "No unstaged diff."),
+        ""
+      ];
+    case "includedBranchDelta":
+      return renderIncludedBranchDelta(report);
+    case "includedDiff":
+      return renderIncludedDiff(report);
+    case "instructionFiles":
+      return ["## Instruction Files", renderInstructionFiles(report.instructionFiles), ""];
+    case "package":
+      return ["## Package", renderPackage(report.packageInfo), ""];
+    case "resume":
+      return renderResumeSource(report);
+    case "verification":
+      return renderVerification(report);
+    case "risk":
+      return renderRisk(report);
+    case "secretScanning":
+      return renderSecretScanning(report);
+  }
 }
 function renderBaseDiffSummary(report) {
   if (!report.repository.baseRef) {
@@ -714,6 +910,30 @@ function renderBaseDiffSummary(report) {
     ""
   ];
 }
+function renderIncludedBranchDelta(report) {
+  if (!report.repository.includeDiff || !report.repository.baseDiff) {
+    return [];
+  }
+  return [
+    `## Included Branch Delta Since \`${report.repository.baseRef}\``,
+    codeBlock(report.repository.baseDiff),
+    ""
+  ];
+}
+function renderIncludedDiff(report) {
+  if (!report.repository.includeDiff || !report.repository.diff) {
+    return [];
+  }
+  return [
+    "## Included Diff",
+    "### Staged Patch",
+    codeBlock(report.repository.diff.staged || "No staged patch."),
+    "",
+    "### Unstaged Patch",
+    codeBlock(report.repository.diff.unstaged || "No unstaged patch."),
+    ""
+  ];
+}
 function renderPackage(packageInfo) {
   if (!packageInfo) {
     return "No package.json detected.";
@@ -801,12 +1021,16 @@ function renderSecretScanning(report) {
 }
 function renderSecretScannerReport(secretScanning) {
   if (!secretScanning.scans) {
-    return secretScanning.scanners.map((scanner) => `- ${scanner.name}: ${scanner.available ? "available" : "not found"}`).join("\n");
+    return secretScanning.scanners.map((scanner) => `- ${scannerStatusLine(scanner)}`).join("\n");
   }
   return secretScanning.scans.map((scan) => {
+    const status = secretScanning.scanners.find((scanner) => scanner.name === scan.name);
     const lines = [
       `- ${scan.name}: ${scan.ran ? `${scan.findings.length} finding(s), exit ${scan.exitCode}` : scan.error ?? "not run"}`
     ];
+    if (status) {
+      lines.push(...scannerGuidanceLines(status));
+    }
     for (const finding of scan.findings) {
       lines.push(`  - ${finding.ruleId ? `${finding.ruleId}: ` : ""}${finding.message}${finding.file ? ` (${finding.file}${finding.line ? `:${finding.line}` : ""})` : ""}`);
     }
@@ -816,6 +1040,23 @@ function renderSecretScannerReport(secretScanning) {
     return lines.join("\n");
   }).join("\n");
 }
+function scannerStatusLine(scanner) {
+  const config = scanner.configFiles.length > 0 ? `; config: ${scanner.configFiles.join(", ")}` : scanner.available ? "" : `; ${scanner.configHint}`;
+  const install = scanner.available ? "" : `; ${scanner.installHint}`;
+  return `${scanner.name}: ${scanner.available ? "available" : "not found"}${config}${install}`;
+}
+function scannerGuidanceLines(scanner) {
+  const lines = [];
+  if (scanner.configFiles.length > 0) {
+    lines.push(`  - config: ${scanner.configFiles.join(", ")}`);
+  } else if (!scanner.available) {
+    lines.push(`  - ${scanner.configHint}`);
+  }
+  if (!scanner.available) {
+    lines.push(`  - ${scanner.installHint}`);
+  }
+  return lines;
+}
 function codeBlock(text) {
   return ["```text", text, "```"].join("\n");
 }
@@ -828,8 +1069,8 @@ async function writeRenderedReport(report, format, budget, output) {
   const rendered = redactText(renderOutput(report, format, budget));
   if (output) {
     const outputPath = resolve(process.cwd(), output);
-    await mkdir(dirname(outputPath), { recursive: true });
-    await writeFile(outputPath, rendered, "utf8");
+    await mkdir2(dirname(outputPath), { recursive: true });
+    await writeFile2(outputPath, rendered, "utf8");
     process.stderr.write(`Wrote handoff packet to ${outputPath}
 `);
     return;
@@ -863,11 +1104,13 @@ var PackCliOptionsSchema = z2.object({
   diff: z2.boolean().default(true),
   since: z2.string().trim().min(1).optional(),
   verify: z2.boolean().default(false),
-  scanSecrets: z2.boolean().default(false)
+  scanSecrets: z2.boolean().default(false),
+  cache: z2.boolean().default(false)
 });
 function createPackCommand() {
-  return new Command("pack").description("Create a safe local handoff packet for another AI assistant.").summary("Create a Markdown or JSON packet from the current git state.").option("--goal <text>", "handoff goal", "Make your own goal").option("--output <path>", "write output to a file instead of stdout").option("--format <format>", "output format: markdown or json", "markdown").option("--for <agent>", "target output: generic, codex, claude, or cursor", "generic").option("--budget <tokens>", "rough output token budget", parseBudget, 4e3).option("--since <ref>", "focus committed branch delta on a base ref").option("--verify", "run safe verification scripts and include results").option("--scan-secrets", "run optional local secret scanners and include bounded results").option("--include-diff", "include full staged and unstaged patches", false).option("--no-diff", "omit diff summaries and full patches").action(async (rawOptions) => {
+  return new Command("pack").description("Create a safe local handoff packet for another AI assistant.").summary("Create a Markdown or JSON packet from the current git state.").option("--goal <text>", "handoff goal", "Make your own goal").option("--output <path>", "write output to a file instead of stdout").option("--format <format>", "output format: markdown or json", "markdown").option("--for <agent>", "target output: generic, codex, claude, or cursor", "generic").option("--budget <tokens>", "rough output token budget", parseBudget, 4e3).option("--since <ref>", "focus committed branch delta on a base ref").option("--verify", "run safe verification scripts and include results").option("--scan-secrets", "run optional local secret scanners and include bounded results").option("--cache", "write explicit local cache artifacts under .handoffkit when available").option("--include-diff", "include full staged and unstaged patches", false).option("--no-diff", "omit diff summaries and full patches").action(async (rawOptions) => {
     const options = parseOptions(rawOptions);
+    const root = options.cache ? await findGitRoot(process.cwd()) : void 0;
     const report = await collectHandoffReport({
       goal: options.goal,
       cwd: process.cwd(),
@@ -881,6 +1124,15 @@ function createPackCommand() {
       includeVerification: options.verify,
       scanSecrets: options.scanSecrets
     });
+    if (options.cache && root && report.verification) {
+      const cache = await writeCacheArtifact(root, "verification", {
+        goal: report.goal,
+        target: report.target,
+        verification: report.verification
+      });
+      process.stderr.write(`Wrote verification cache to ${cache.latestPath}
+`);
+    }
     await writeRenderedReport(report, options.format, options.budget, options.output);
   });
 }
@@ -909,11 +1161,20 @@ import { z as z3 } from "zod";
 // src/core/resume.ts
 var RESUME_PREVIEW_LIMIT = 3e3;
 var SECTION_ALIASES = {
-  completed: [/^completed$/i, /^done$/i, /^done this session$/i, /^what changed$/i, /^implemented$/i],
-  remaining: [/^remaining$/i, /^next steps$/i, /^todo$/i, /^to do$/i],
-  failedCommands: [/^failed commands$/i, /^failures$/i, /^errors$/i],
-  openQuestions: [/^open questions$/i, /^open questions \/ risks$/i, /^open questions and risks$/i, /^questions$/i, /^blockers$/i],
-  verification: [/^verification$/i, /^tests$/i, /^validation$/i]
+  completed: [/^completed$/i, /^completed work$/i, /^done$/i, /^done this session$/i, /^what changed$/i, /^what i changed$/i, /^implemented$/i],
+  remaining: [/^remaining$/i, /^remaining work$/i, /^next steps$/i, /^next action$/i, /^next safest action$/i, /^todo$/i, /^to do$/i],
+  failedCommands: [/^failed command$/i, /^failed commands$/i, /^command failed$/i, /^commands failed$/i, /^failure$/i, /^failures$/i, /^error$/i, /^errors$/i],
+  openQuestions: [
+    /^open question$/i,
+    /^open questions$/i,
+    /^open questions \/ risks$/i,
+    /^open questions and risks$/i,
+    /^question$/i,
+    /^questions$/i,
+    /^blocker$/i,
+    /^blockers$/i
+  ],
+  verification: [/^verification$/i, /^tests$/i, /^tests run$/i, /^validation$/i]
 };
 function createResumeSource(path, content) {
   const normalized = content.replace(/\r\n/g, "\n").trim();
@@ -948,12 +1209,22 @@ function parseResumeState(content) {
       section = sectionForHeading(heading);
       continue;
     }
+    const transcriptLine = stripTranscriptPrefix(line);
+    const labeled = parseLabeledTranscriptLine(transcriptLine);
+    if (labeled) {
+      heading = labeled.heading;
+      section = labeled.section;
+      if (labeled.item) {
+        appendResumeItem(state, section, labeled.item, heading);
+      }
+      continue;
+    }
     if (!section) {
       continue;
     }
-    const item = normalizeListItem(line);
+    const item = normalizeListItem(transcriptLine);
     if (item) {
-      state[section].push({ text: redactText(item), ...heading ? { sourceHeading: redactText(heading) } : {} });
+      appendResumeItem(state, section, item, heading);
     }
   }
   const next = state.remaining[0] ?? state.openQuestions[0] ?? state.failedCommands[0];
@@ -971,10 +1242,41 @@ function sectionForHeading(heading) {
   }
   return void 0;
 }
+function parseLabeledTranscriptLine(line) {
+  const match = line.match(/^([^:]{1,80}):(?:\s*(.*))?$/);
+  if (!match?.[1]) {
+    return void 0;
+  }
+  const heading = match[1].trim();
+  const section = sectionForHeading(heading);
+  if (!section) {
+    return void 0;
+  }
+  const item = match[2]?.trim();
+  return {
+    section,
+    heading,
+    ...item ? { item } : {}
+  };
+}
+function appendResumeItem(state, section, item, heading) {
+  state[section].push({ text: redactText(item), ...heading ? { sourceHeading: redactText(heading) } : {} });
+}
 function normalizeListItem(line) {
   const match = line.match(/^[-*]\s+(.+)$/) ?? line.match(/^\d+\.\s+(.+)$/);
   return match?.[1]?.trim();
 }
+function stripTranscriptPrefix(line) {
+  let current = line.trim();
+  for (let i = 0; i < 4; i += 1) {
+    const next = current.replace(/^\[[^\]\n]{1,60}\]\s*/, "").replace(/^(?:user|assistant|system|developer|tool|terminal|command|cmd|result|codex|claude|cursor|gemini)(?:\s*\([^)]*\))?\s*[:>]\s*/i, "").trim();
+    if (next === current) {
+      return current;
+    }
+    current = next;
+  }
+  return current;
+}
 function normalizeHeading(heading) {
   return heading.trim().replace(/:$/, "").replace(/\s*\/\s*/g, " / ").replace(/\s+/g, " ");
 }
@@ -988,12 +1290,14 @@ var ResumeOptionsSchema = z3.object({
   output: z3.string().optional(),
   format: z3.enum(["markdown", "json"]).default("markdown"),
   for: z3.enum(["generic", "codex", "claude", "cursor"]).default("generic"),
-  budget: z3.number().int().positive().default(4e3)
+  budget: z3.number().int().positive().default(4e3),
+  cache: z3.boolean().default(false)
 });
 function createResumeCommand() {
-  return new Command2("resume").description("Create a fresh handoff packet using a previous handoff as resume context.").summary("Merge a previous handoff or transcript with fresh repo state.").argument("<path>", "previous handoff or transcript file").option("--goal <text>", "new handoff goal", "Resume interrupted AI coding session").option("--output <path>", "write output to a file instead of stdout").option("--format <format>", "output format: markdown or json", "markdown").option("--for <agent>", "target output: generic, codex, claude, or cursor", "generic").option("--budget <tokens>", "rough output token budget", parseBudget2, 4e3).action(async (path, rawOptions) => {
+  return new Command2("resume").description("Create a fresh handoff packet using a previous handoff as resume context.").summary("Merge a previous handoff or transcript with fresh repo state.").argument("<path>", "previous handoff or transcript file").option("--goal <text>", "new handoff goal", "Resume interrupted AI coding session").option("--output <path>", "write output to a file instead of stdout").option("--format <format>", "output format: markdown or json", "markdown").option("--for <agent>", "target output: generic, codex, claude, or cursor", "generic").option("--budget <tokens>", "rough output token budget", parseBudget2, 4e3).option("--cache", "write a local resume artifact under .handoffkit/resume").action(async (path, rawOptions) => {
     const options = ResumeOptionsSchema.parse(rawOptions);
     const source = createResumeSource(path, await readFile5(path, "utf8"));
+    const root = options.cache ? await findGitRoot(process.cwd()) : void 0;
     const report = await collectHandoffReport({
       goal: options.goal,
       cwd: process.cwd(),
@@ -1007,6 +1311,15 @@ function createResumeCommand() {
       scanSecrets: false,
       resumeSource: source
     });
+    if (options.cache && root) {
+      const cache = await writeCacheArtifact(root, "resume", {
+        goal: report.goal,
+        target: report.target,
+        source
+      });
+      process.stderr.write(`Wrote resume cache to ${cache.latestPath}
+`);
+    }
     await writeRenderedReport(report, options.format, options.budget, options.output);
   });
 }
@@ -1072,7 +1385,11 @@ function createScanSecretsCommand() {
 function renderScanMarkdown(report) {
   const lines = ["# Secret Scan Results", ""];
   for (const scan of report.scans ?? []) {
+    const status = report.scanners.find((scanner) => scanner.name === scan.name);
     lines.push(`- ${scan.name}: ${scan.ran ? `${scan.findings.length} finding(s), exit ${scan.exitCode}` : scan.error ?? "not run"}`);
+    if (status) {
+      lines.push(...scannerGuidanceLines2(status));
+    }
     for (const finding of scan.findings) {
       lines.push(`  - ${finding.ruleId ? `${finding.ruleId}: ` : ""}${finding.message}${finding.file ? ` (${finding.file}${finding.line ? `:${finding.line}` : ""})` : ""}`);
     }
@@ -1080,18 +1397,36 @@ function renderScanMarkdown(report) {
   return `${lines.join("\n")}
 `;
 }
+function scannerGuidanceLines2(scanner) {
+  const lines = [];
+  if (scanner.configFiles.length > 0) {
+    lines.push(`  - config: ${scanner.configFiles.join(", ")}`);
+  } else if (!scanner.available) {
+    lines.push(`  - ${scanner.configHint}`);
+  }
+  if (!scanner.available) {
+    lines.push(`  - ${scanner.installHint}`);
+  }
+  return lines;
+}
 
 // src/cli/commands/verify.ts
 import { Command as Command5 } from "commander";
 import { z as z6 } from "zod";
 var VerifyOptionsSchema = z6.object({
-  format: z6.enum(["markdown", "json"]).default("markdown")
+  format: z6.enum(["markdown", "json"]).default("markdown"),
+  cache: z6.boolean().default(false)
 });
 function createVerifyCommand() {
-  return new Command5("verify").description("Run safe local verification scripts.").summary("Run safe detected verification scripts.").option("--format <format>", "output format: markdown or json", "markdown").action(async (rawOptions) => {
+  return new Command5("verify").description("Run safe local verification scripts.").summary("Run safe detected verification scripts.").option("--format <format>", "output format: markdown or json", "markdown").option("--cache", "write a local verification artifact under .handoffkit/verification").action(async (rawOptions) => {
     const options = VerifyOptionsSchema.parse(rawOptions);
     const root = await findGitRoot(process.cwd());
     const verification = await runVerification(root);
+    if (options.cache) {
+      const cache = await writeCacheArtifact(root, "verification", verification);
+      process.stderr.write(`Wrote verification cache to ${cache.latestPath}
+`);
+    }
     if (options.format === "json") {
       process.stdout.write(redactText(`${JSON.stringify(verification, null, 2)}
 `));
@@ -1114,7 +1449,7 @@ function renderVerificationMarkdown(commands) {
 }
 
 // src/cli/index.ts
-var program = new Command6().name("handoffkit").description("Create safe local handoff packets for AI-assisted coding sessions.").summary("Create local-first AI coding session handoff packets.").showHelpAfterError("(run with --help for usage)").version("0.1.1");
+var program = new Command6().name("handoffkit").description("Create safe local handoff packets for AI-assisted coding sessions.").summary("Create local-first AI coding session handoff packets.").showHelpAfterError("(run with --help for usage)").version("0.3.0");
 program.addCommand(createPackCommand());
 program.addCommand(createVerifyCommand());
 program.addCommand(createRiskCommand());