@kingkyylian/handoffkit 0.2.0 → 0.4.0

package/dist/index.js

@@ -1,15 +1,154 @@
 #!/usr/bin/env node
 
 // src/cli/index.ts
-import { Command as Command6 } from "commander";
+import { Command as Command7 } from "commander";
 
-// src/cli/commands/pack.ts
+// src/cli/commands/cache.ts
 import { Command } from "commander";
-import { z as z2 } from "zod";
+import { z } from "zod";
+
+// src/core/cache.ts
+import { mkdir, readdir, readFile, writeFile } from "fs/promises";
+import { basename, 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
+var CACHE_KINDS = ["resume", "verification"];
+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 };
+}
+async function listCacheArtifacts(root) {
+  const summaries = await Promise.all(CACHE_KINDS.map((kind) => listCacheKind(root, kind)));
+  return summaries.flat().sort((a, b) => b.createdAt.localeCompare(a.createdAt) || a.kind.localeCompare(b.kind) || a.name.localeCompare(b.name));
+}
+async function readCacheArtifact(root, kind, name = "latest") {
+  const normalizedName = normalizeArtifactName(name);
+  const artifactPath = join(root, ".handoffkit", kind, `${normalizedName}.json`);
+  const envelope = JSON.parse(await readFile(artifactPath, "utf8"));
+  if (envelope.version !== 1 || envelope.kind !== kind || typeof envelope.createdAt !== "string") {
+    throw new Error(`Invalid cache artifact: .handoffkit/${kind}/${normalizedName}.json`);
+  }
+  return envelope;
+}
+async function readResumeSourceFromCache(root, ref) {
+  const { kind, name } = parseCacheRef(ref, "resume");
+  if (kind !== "resume") {
+    throw new Error("resume --from-cache only supports resume cache artifacts.");
+  }
+  const artifact = await readCacheArtifact(root, kind, name);
+  const source = resumeSourceFromArtifact(artifact);
+  if (!source) {
+    throw new Error(`Cache artifact does not contain a resume source: .handoffkit/${kind}/${name}.json`);
+  }
+  return source;
+}
+function parseCacheRef(ref, defaultKind) {
+  const normalized = ref.trim();
+  const parts = normalized.split("/");
+  if (parts.length === 1 && defaultKind) {
+    return { kind: defaultKind, name: normalizeArtifactName(parts[0] || "latest") };
+  }
+  const [kind, name] = parts;
+  if (parts.length === 2 && kind && isCacheArtifactKind(kind)) {
+    return { kind, name: normalizeArtifactName(name || "latest") };
+  }
+  throw new Error(`Invalid cache ref: ${ref}`);
+}
+function resumeSourceFromArtifact(artifact) {
+  const data = artifact.data;
+  return data.source;
+}
+async function listCacheKind(root, kind) {
+  const cacheDir = join(root, ".handoffkit", kind);
+  let entries;
+  try {
+    entries = await readdir(cacheDir);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+  const artifacts = await Promise.all(
+    entries.filter((entry) => entry.endsWith(".json")).map(async (entry) => {
+      const name = basename(entry, ".json");
+      try {
+        const artifact = await readCacheArtifact(root, kind, name);
+        return {
+          kind,
+          name,
+          createdAt: artifact.createdAt,
+          path: `.handoffkit/${kind}/${entry}`
+        };
+      } catch {
+        return void 0;
+      }
+    })
+  );
+  return artifacts.filter((artifact) => Boolean(artifact));
+}
+function isCacheArtifactKind(value) {
+  return CACHE_KINDS.includes(value);
+}
+function normalizeArtifactName(name) {
+  const withoutExtension = name.replace(/\.json$/i, "");
+  if (!/^[A-Za-z0-9_.-]+$/.test(withoutExtension)) {
+    throw new Error(`Invalid cache artifact name: ${name}`);
+  }
+  return withoutExtension;
+}
+function cacheTimestamp(timestamp) {
+  return timestamp.replace(/[:.]/g, "-");
+}
 
 // src/core/git.ts
-import { readFile } from "fs/promises";
-import { basename } from "path";
+import { readFile as readFile2 } from "fs/promises";
+import { basename as basename2 } from "path";
 import { execa } from "execa";
 
 // src/cli/errors.ts
@@ -26,7 +165,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,
@@ -55,7 +194,7 @@ async function collectGitInfo(root, options) {
   const unstagedDiffSummary = options.includeDiffSummary ? joinSections([trackedUnstagedDiffSummary, renderUntrackedSummary(untrackedFiles)]) : "";
   const diff = options.includeDiff ? await collectDiff(root, untrackedFiles) : void 0;
   return {
-    name: basename(root),
+    name: basename2(root),
     branch,
     ...options.since ? { baseRef: options.since } : {},
     status,
@@ -139,7 +278,7 @@ function renderUntrackedSummary(files) {
 async function untrackedPatch(root, files) {
   const patches = await Promise.all(
     files.map(async (file) => {
-      const content = await readFile(`${root}/${file}`, "utf8");
+      const content = await readFile2(`${root}/${file}`, "utf8");
       const trimmedContent = content.length > UNTRACKED_PATCH_CHAR_LIMIT ? `${content.slice(0, UNTRACKED_PATCH_CHAR_LIMIT).trimEnd()}
 [truncated]` : content.trimEnd();
       return [`Untracked file: ${file}`, "```text", trimmedContent, "```"].join("\n");
@@ -157,43 +296,74 @@ function isIgnoredChangedPath(file) {
   return IGNORED_CHANGED_PATH_PREFIXES.some((prefix) => file === prefix.slice(0, -1) || file.startsWith(prefix));
 }
 
-// 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}`;
+// src/cli/commands/cache.ts
+var CacheFormatOptionsSchema = z.object({
+  format: z.enum(["markdown", "json"]).default("markdown")
+});
+var CacheKindSchema = z.enum(["verification", "resume"]);
+function createCacheCommand() {
+  return new Command("cache").description("Inspect local .handoffkit cache artifacts.").summary("List and show explicit local cache artifacts.").addCommand(createCacheListCommand()).addCommand(createCacheShowCommand());
+}
+function createCacheListCommand() {
+  return new Command("list").description("List local cache artifacts.").option("--format <format>", "output format: markdown or json", "markdown").action(async (rawOptions) => {
+    const options = CacheFormatOptionsSchema.parse(rawOptions);
+    const root = await findGitRoot(process.cwd());
+    const artifacts = await listCacheArtifacts(root);
+    if (options.format === "json") {
+      process.stdout.write(`${JSON.stringify({ artifacts }, null, 2)}
+`);
+      return;
+    }
+    process.stdout.write(renderCacheListMarkdown(artifacts));
   });
-  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);
+}
+function createCacheShowCommand() {
+  return new Command("show").description("Show one local cache artifact.").argument("<kind>", "cache kind: verification or resume").argument("[name]", "artifact name, defaults to latest", "latest").option("--format <format>", "output format: markdown or json", "markdown").action(async (kindInput, name, rawOptions) => {
+    const options = CacheFormatOptionsSchema.parse(rawOptions);
+    const kind = CacheKindSchema.parse(kindInput);
+    const root = await findGitRoot(process.cwd());
+    const artifact = await readCacheArtifact(root, kind, name);
+    if (options.format === "json") {
+      process.stdout.write(`${JSON.stringify(artifact, null, 2)}
+`);
+      return;
+    }
+    process.stdout.write(renderCacheArtifactMarkdown(artifact, kind, name));
+  });
+}
+function renderCacheListMarkdown(artifacts) {
+  const lines = ["# Cache Artifacts", ""];
+  if (artifacts.length === 0) {
+    lines.push("No cache artifacts found.");
+  } else {
+    for (const artifact of artifacts) {
+      lines.push(`- ${artifact.kind}/${artifact.name} (${artifact.createdAt}) - \`${artifact.path}\``);
+    }
   }
-  return output;
+  return `${lines.join("\n")}
+`;
 }
+function renderCacheArtifactMarkdown(artifact, kind, name) {
+  return [
+    "# Cache Artifact",
+    "",
+    `- Artifact: ${kind}/${name}`,
+    `- Created: ${artifact.createdAt}`,
+    "",
+    "```json",
+    JSON.stringify(artifact, null, 2),
+    "```",
+    ""
+  ].join("\n");
+}
+
+// src/cli/commands/pack.ts
+import { Command as Command2 } from "commander";
+import { z as z3 } from "zod";
 
 // src/core/instructions.ts
+import { readFile as readFile3, stat } from "fs/promises";
+import fg from "fast-glob";
 var INSTRUCTION_PATTERNS = [
   "**/AGENTS.md",
   "**/CLAUDE.md",
@@ -226,7 +396,7 @@ async function readPreview(root, path) {
   if (!metadata.isFile()) {
     return "Directory rule set detected.";
   }
-  const content = await readFile2(fullPath, "utf8");
+  const content = await readFile3(fullPath, "utf8");
   const normalized = content.replace(/\r\n/g, "\n").trim();
   const preview = normalized.length > PREVIEW_CHAR_LIMIT ? `${normalized.slice(0, PREVIEW_CHAR_LIMIT).trimEnd()}
 [truncated]` : normalized;
@@ -252,22 +422,22 @@ function instructionKind(path) {
 }
 
 // src/core/package-json.ts
-import { access, readFile as readFile3 } from "fs/promises";
-import { join } from "path";
-import { z } from "zod";
-var PackageJsonSchema = z.object({
-  name: z.string().optional(),
-  packageManager: z.string().optional(),
-  scripts: z.record(z.string(), z.string()).optional()
+import { access, readFile as readFile4 } from "fs/promises";
+import { join as join2 } from "path";
+import { z as z2 } from "zod";
+var PackageJsonSchema = z2.object({
+  name: z2.string().optional(),
+  packageManager: z2.string().optional(),
+  scripts: z2.record(z2.string(), z2.string()).optional()
 });
 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;
   }
-  const rawPackageJson = await readFile3(packageJsonPath, "utf8");
+  const rawPackageJson = await readFile4(packageJsonPath, "utf8");
   const packageJson = PackageJsonSchema.parse(JSON.parse(rawPackageJson));
   const packageManager = await detectPackageManager(root, packageJson.packageManager);
   const verificationScripts = detectVerificationScripts(packageJson.scripts ?? {});
@@ -289,7 +459,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 +490,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,11 +576,23 @@ 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 { mkdtemp, readFile as readFile5 } 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";
@@ -452,14 +678,14 @@ 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"],
     { reject: false, all: true }
   );
-  const rawReport = await readFile4(reportPath, "utf8").catch(() => "[]");
+  const rawReport = await readFile5(reportPath, "utf8").catch(() => "[]");
   const findings = normalizeGitleaksFindings(rawReport);
   return {
     name: "gitleaks",
@@ -606,6 +832,7 @@ async function collectHandoffReport(options) {
     ...packageInfo ? { packageInfo } : {},
     ...options.resumeSource ? { resumeSource: options.resumeSource } : {},
     ...options.includeVerification ? { verification: await runVerification(root) } : {},
+    ...options.includeCache ? { cache: { artifacts: await listCacheArtifacts(root) } } : {},
     secretScanning,
     budget: {
       requestedTokens: options.budget,
@@ -618,7 +845,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
@@ -664,6 +891,7 @@ var genericOrder = [
   "package",
   "resume",
   "verification",
+  "cache",
   "risk",
   "secretScanning"
 ];
@@ -684,6 +912,7 @@ var profiles = {
       "gitStatus",
       "changedFiles",
       "verification",
+      "cache",
       "risk",
       "branchDelta",
       "diffSummary",
@@ -708,6 +937,7 @@ var profiles = {
       "resume",
       "repository",
       "verification",
+      "cache",
       "risk",
       "changedFiles",
       "gitStatus",
@@ -740,6 +970,7 @@ var profiles = {
       "instructionFiles",
       "package",
       "verification",
+      "cache",
       "risk",
       "resume",
       "secretScanning",
@@ -814,6 +1045,8 @@ function renderSection(section, report) {
       return renderResumeSource(report);
     case "verification":
       return renderVerification(report);
+    case "cache":
+      return renderCache(report);
     case "risk":
       return renderRisk(report);
     case "secretScanning":
@@ -919,6 +1152,18 @@ function renderVerification(report) {
     ""
   ];
 }
+function renderCache(report) {
+  if (!report.cache) {
+    return [];
+  }
+  return ["## Cache Artifacts", renderCacheArtifacts(report.cache.artifacts), ""];
+}
+function renderCacheArtifacts(artifacts) {
+  if (artifacts.length === 0) {
+    return "No cache artifacts found.";
+  }
+  return artifacts.map((artifact) => `- ${artifact.kind}/${artifact.name} (${artifact.createdAt}) - \`${artifact.path}\``).join("\n");
+}
 function renderRisk(report) {
   if (!report.risk) {
     return [];
@@ -989,8 +1234,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;
@@ -1014,21 +1259,24 @@ function renderOutput(report, format, budget) {
 }
 
 // src/cli/commands/pack.ts
-var PackCliOptionsSchema = z2.object({
-  goal: z2.string().trim().min(1).default("Make your own goal"),
-  output: z2.string().optional(),
-  format: z2.enum(["markdown", "json"]).default("markdown"),
-  for: z2.enum(["generic", "codex", "claude", "cursor"]).default("generic"),
-  budget: z2.number().int().positive().default(4e3),
-  includeDiff: z2.boolean().default(false),
-  diff: z2.boolean().default(true),
-  since: z2.string().trim().min(1).optional(),
-  verify: z2.boolean().default(false),
-  scanSecrets: z2.boolean().default(false)
+var PackCliOptionsSchema = z3.object({
+  goal: z3.string().trim().min(1).default("Make your own goal"),
+  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),
+  includeDiff: z3.boolean().default(false),
+  diff: z3.boolean().default(true),
+  since: z3.string().trim().min(1).optional(),
+  verify: z3.boolean().default(false),
+  scanSecrets: z3.boolean().default(false),
+  cache: z3.boolean().default(false),
+  includeCache: z3.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 Command2("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-cache", "include recent .handoffkit artifact summaries").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(),
@@ -1040,8 +1288,18 @@ function createPackCommand() {
       includeDiffSummary: options.diff,
       ...options.since ? { since: options.since } : {},
       includeVerification: options.verify,
-      scanSecrets: options.scanSecrets
+      scanSecrets: options.scanSecrets,
+      includeCache: options.includeCache
     });
+    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);
   });
 }
@@ -1063,18 +1321,27 @@ function parseBudget(value) {
 }
 
 // src/cli/commands/resume.ts
-import { readFile as readFile5 } from "fs/promises";
-import { Command as Command2 } from "commander";
-import { z as z3 } from "zod";
+import { readFile as readFile6 } from "fs/promises";
+import { Command as Command3 } from "commander";
+import { z as z4 } 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();
@@ -1109,12 +1376,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];
@@ -1132,10 +1409,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, " ");
 }
@@ -1144,17 +1452,20 @@ function hasResumeState(state) {
 }
 
 // src/cli/commands/resume.ts
-var ResumeOptionsSchema = z3.object({
-  goal: z3.string().trim().min(1).default("Resume interrupted AI coding session"),
-  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)
+var ResumeOptionsSchema = z4.object({
+  goal: z4.string().trim().min(1).default("Resume interrupted AI coding session"),
+  output: z4.string().optional(),
+  format: z4.enum(["markdown", "json"]).default("markdown"),
+  for: z4.enum(["generic", "codex", "claude", "cursor"]).default("generic"),
+  budget: z4.number().int().positive().default(4e3),
+  cache: z4.boolean().default(false),
+  fromCache: z4.string().trim().min(1).optional()
 });
 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 Command3("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").option("--from-cache <ref>", "load resume source from .handoffkit/resume, for example latest or resume/latest").action(async (path, rawOptions) => {
     const options = ResumeOptionsSchema.parse(rawOptions);
-    const source = createResumeSource(path, await readFile5(path, "utf8"));
+    const root = options.cache || options.fromCache ? await findGitRoot(process.cwd()) : void 0;
+    const source = await resolveResumeSource(path, options.fromCache, root);
     const report = await collectHandoffReport({
       goal: options.goal,
       cwd: process.cwd(),
@@ -1166,11 +1477,36 @@ function createResumeCommand() {
       includeDiffSummary: true,
       includeVerification: false,
       scanSecrets: false,
+      includeCache: 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);
   });
 }
+async function resolveResumeSource(path, fromCache, root) {
+  if (path && fromCache) {
+    throw new Error("Pass either <path> or --from-cache, not both.");
+  }
+  if (fromCache) {
+    if (!root) {
+      throw new Error("--from-cache requires a git repository.");
+    }
+    return readResumeSourceFromCache(root, fromCache);
+  }
+  if (!path) {
+    throw new Error("resume requires <path> or --from-cache <ref>.");
+  }
+  return createResumeSource(path, await readFile6(path, "utf8"));
+}
 function parseBudget2(value) {
   const parsed = Number.parseInt(value, 10);
   if (!Number.isFinite(parsed) || parsed <= 0) {
@@ -1180,13 +1516,13 @@ function parseBudget2(value) {
 }
 
 // src/cli/commands/risk.ts
-import { Command as Command3 } from "commander";
-import { z as z4 } from "zod";
-var RiskOptionsSchema = z4.object({
-  format: z4.enum(["markdown", "json"]).default("markdown")
+import { Command as Command4 } from "commander";
+import { z as z5 } from "zod";
+var RiskOptionsSchema = z5.object({
+  format: z5.enum(["markdown", "json"]).default("markdown")
 });
 function createRiskCommand() {
-  return new Command3("risk").description("Show deterministic risk notes for the current handoff.").summary("Show deterministic risk notes from changed files.").option("--format <format>", "output format: markdown or json", "markdown").action(async (rawOptions) => {
+  return new Command4("risk").description("Show deterministic risk notes for the current handoff.").summary("Show deterministic risk notes from changed files.").option("--format <format>", "output format: markdown or json", "markdown").action(async (rawOptions) => {
     const options = RiskOptionsSchema.parse(rawOptions);
     const report = await collectHandoffReport({
       goal: "Review local risk",
@@ -1197,7 +1533,8 @@ function createRiskCommand() {
       includeDiff: false,
       includeDiffSummary: false,
       includeVerification: false,
-      scanSecrets: false
+      scanSecrets: false,
+      includeCache: false
     });
     if (options.format === "json") {
       process.stdout.write(`${JSON.stringify(report.risk, null, 2)}
@@ -1212,13 +1549,13 @@ ${report.risk?.notes.map((note) => `- **${note.severity}**: ${note.title} - ${no
 }
 
 // src/cli/commands/scan-secrets.ts
-import { Command as Command4 } from "commander";
-import { z as z5 } from "zod";
-var ScanSecretsOptionsSchema = z5.object({
-  format: z5.enum(["markdown", "json"]).default("markdown")
+import { Command as Command5 } from "commander";
+import { z as z6 } from "zod";
+var ScanSecretsOptionsSchema = z6.object({
+  format: z6.enum(["markdown", "json"]).default("markdown")
 });
 function createScanSecretsCommand() {
-  return new Command4("scan-secrets").description("Run optional local secret scanners and print bounded redacted results.").summary("Run optional local secret scanners.").option("--format <format>", "output format: markdown or json", "markdown").action(async (rawOptions) => {
+  return new Command5("scan-secrets").description("Run optional local secret scanners and print bounded redacted results.").summary("Run optional local secret scanners.").option("--format <format>", "output format: markdown or json", "markdown").action(async (rawOptions) => {
     const options = ScanSecretsOptionsSchema.parse(rawOptions);
     const root = await findGitRoot(process.cwd());
     const report = await runSecretScanners(root);
@@ -1259,16 +1596,22 @@ function scannerGuidanceLines2(scanner) {
 }
 
 // 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")
+import { Command as Command6 } from "commander";
+import { z as z7 } from "zod";
+var VerifyOptionsSchema = z7.object({
+  format: z7.enum(["markdown", "json"]).default("markdown"),
+  cache: z7.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 Command6("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)}
 `));
@@ -1291,12 +1634,13 @@ 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.2.0");
+var program = new Command7().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.4.0");
 program.addCommand(createPackCommand());
 program.addCommand(createVerifyCommand());
 program.addCommand(createRiskCommand());
 program.addCommand(createScanSecretsCommand());
 program.addCommand(createResumeCommand());
+program.addCommand(createCacheCommand());
 try {
   await program.parseAsync(process.argv);
 } catch (error) {