vericify 1.1.0 → 1.3.0

package/README.md

@@ -62,6 +62,7 @@ Node `18+` is required.
 
 ```bash
 cd /path/to/repo
+vericify context
 vericify adapters
 vericify hub
 ```
@@ -76,6 +77,7 @@ If your workspace already contains `agent-state/*`, Vericify reads it automatica
 
 ```bash
 cd /path/to/ace-workspace
+vericify context
 vericify adapters
 vericify hub
 ```
@@ -93,6 +95,30 @@ vericify adapters
 
 That creates or updates `.vericify/adapters.json` for the current repo and marks the adapter as attached.
 
+For Claude Code, `vericify attach --adapter claude-code` also writes compact-bootstrap guidance into `CLAUDE.md` and, when `.claude/` exists, installs the Vericify hook block into `.claude/settings.json`.
+
+## Compact Bootstrap And Resume
+
+Use the compact packet when you want session bootstrap or resume without rereading the full projected state:
+
+```bash
+vericify context
+vericify delta --since vcx_...
+vericify snapshot --format compact
+```
+
+`vericify context` returns one minified JSON packet with:
+
+- the selected run
+- status
+- current focus
+- blockers
+- a strict `live_signal` subset
+- the last meaningful events
+- a fresh opaque continuity id
+
+Use `--pretty` if you want the compact packet formatted for humans.
+
 ## Do I Need `--session-id`?
 
 No. `--session-id` is optional.
@@ -194,10 +220,11 @@ Best when you already have `agent-state/*` and want a cockpit, history, and comp
 ```bash
 vericify attach --adapter codex --label "Primary Codex"
 vericify attach --adapter claude-code --session-id claude-main --capture-mode attachment
+vericify context
 vericify hub
 ```
 
-Best when you want durable workspace metadata now, even before vendor-specific live capture bridges are added.
+Best when you want durable workspace metadata now. Claude Code attach also writes the startup guidance for `vericify context`, the `vericify delta --since=<id>` resume path, and the `PreCompact` reinjection hook when `.claude/` is available.
 
 ### Use case 3: Create a native run trail manually
 
@@ -319,11 +346,14 @@ Today the package is semantic-first. Git-backed provenance can be attached when
 
 ```bash
 vericify help
+vericify context
+vericify delta --since vcx_...
 vericify adapters
 vericify attach --adapter codex --label "Primary Codex session"
 vericify attach --adapter claude-code --session-id claude-main --capture-mode attachment --label "Claude main"
 vericify hub
 vericify snapshot
+vericify snapshot --format compact
 vericify compare --run-id handoff:run-a --compare-run-id workspace:current
 vericify publish --run-id handoff:run-a
 vericify sync --run-id handoff:run-a --endpoint https://sync.example.test
@@ -372,6 +402,8 @@ The package also exports:
 
 - `loadWorkspaceState`
 - `projectWorkspaceState`
+- `buildCompactPacket`
+- `buildCompactDelta`
 - `detectAdapters`
 - `attachAdapter`
 - `buildRunComparison`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vericify",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "private": false,
   "type": "module",
   "description": "Local-first run intelligence and operations hub for agent systems.",
@@ -20,6 +20,8 @@
   "scripts": {
     "adapters": "node src/index.js adapters",
     "attach": "node src/index.js attach",
+    "context": "node src/index.js context",
+    "delta": "node src/index.js delta",
     "hub": "node src/index.js hub",
     "compare": "node src/index.js compare",
     "publish:artifact": "node src/index.js publish",

package/src/adapters/claude-attach.js

@@ -0,0 +1 @@
+export { attachClaudeWorkspace } from "./handshake/claude-code.js";

package/src/adapters/handshake/antigravity.js

@@ -0,0 +1,81 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { readJson } from "../../core/fs.js";
+import { createHandshakeResult, emitHandshakeStartedEvent, mergeJsonFile, writeInstructionBlock } from "./common.js";
+
+function antigravityInstructionBlock() {
+  return `## Vericify Process Posts
+
+When working in this workspace, emit native Vericify process posts at these moments:
+
+- **Blocker:** \`vericify post --run-id workspace:current --agent-id antigravity --kind blocker --summary "<what is blocking>"\`
+- **Handoff:** \`vericify post --run-id workspace:current --agent-id antigravity --kind handoff_note --summary "<handoff context>"\`
+- **Completion:** \`vericify post --run-id workspace:current --agent-id antigravity --kind completion --summary "<what changed>"\`
+- **Intentional silence:** \`vericify post --run-id workspace:current --agent-id antigravity --kind stale_ack --summary "<reason>"\`
+
+You may also write structured state to \`.antigravity/vericify-state.json\` using the passthrough schema.`;
+}
+
+export function antigravityHandshake(workspaceRoot, options = {}) {
+  const result = createHandshakeResult();
+  const skippedReasons = [];
+  const antigravityDir = resolve(workspaceRoot, ".antigravity");
+  const statePath = resolve(antigravityDir, "vericify-state.json");
+  const instructionPath = resolve(antigravityDir, "vericify-instructions.md");
+  const configPath = resolve(workspaceRoot, "antigravity.config.json");
+
+  if (existsSync(antigravityDir)) {
+    try {
+      const stateResult = mergeJsonFile(statePath, (existing) => ({
+        ...(existing && typeof existing === "object" ? existing : {}),
+        _vericify_passthrough: true,
+        handoffs: existing?.handoffs && typeof existing.handoffs === "object" ? existing.handoffs : {},
+        nodes: existing?.nodes && typeof existing.nodes === "object" ? existing.nodes : {},
+        entries: Array.isArray(existing?.entries) ? existing.entries : [],
+        events: Array.isArray(existing?.events) ? existing.events : [],
+        posts: Array.isArray(existing?.posts) ? existing.posts : [],
+      }));
+      result.passthrough_written = Boolean(stateResult.written);
+      result.passthrough_path = statePath;
+      if (stateResult.skipped) skippedReasons.push(stateResult.reason);
+    } catch (error) {
+      skippedReasons.push(`.antigravity/vericify-state.json write failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+
+    try {
+      const instructionResult = writeInstructionBlock(instructionPath, "## Vericify Process Posts", antigravityInstructionBlock(), {
+        createIfAbsent: true,
+        createDirs: true,
+      });
+      result.instruction_written = Boolean(instructionResult.written);
+      result.instruction_path = instructionPath;
+      if (instructionResult.skipped) skippedReasons.push(instructionResult.reason);
+    } catch (error) {
+      skippedReasons.push(`antigravity instructions write failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+
+    if (existsSync(configPath)) {
+      const config = readJson(configPath, null);
+      const hasVericifyConfig = Boolean(config && typeof config === "object" && "vericify" in config);
+      if (hasVericifyConfig) {
+        skippedReasons.push("antigravity.config.json already contains vericify keys; left unchanged");
+      }
+    }
+  } else {
+    skippedReasons.push(".antigravity directory is missing; passthrough config and instructions skipped");
+  }
+
+  const eventResult = emitHandshakeStartedEvent(workspaceRoot, {
+    adapterId: "antigravity",
+    sessionId: options.sessionId ?? null,
+    hooksWritten: false,
+    instructionWritten: result.instruction_written,
+    passthroughWritten: result.passthrough_written,
+  });
+
+  return {
+    ...result,
+    event_emitted: eventResult.event_emitted,
+    skipped_reasons: [...skippedReasons, ...eventResult.skipped_reasons].filter(Boolean),
+  };
+}

package/src/adapters/handshake/claude-code.js

@@ -0,0 +1,150 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { readJson, readText } from "../../core/fs.js";
+import { createHandshakeResult, emitHandshakeStartedEvent } from "./common.js";
+
+const CLAUDE_DIR = ".claude";
+const CLAUDE_SETTINGS_FILE = "settings.json";
+const VERICIFY_MARKER = "<!-- vericify-instruction -->";
+const VERICIFY_END_MARKER = "<!-- /vericify-instruction -->";
+const VERICIFY_CONTEXT_COMMAND = "vericify context";
+const VERICIFY_CONTEXT_RESUME_COMMAND = "vericify delta --since=<id>";
+const VERICIFY_PRECOMPACT_COMMAND = "vericify context --run-id workspace:current";
+
+function markerBlock() {
+  return `${VERICIFY_MARKER}
+## Vericify Bootstrap
+
+At session start, run \`${VERICIFY_CONTEXT_COMMAND}\` and use that packet as the default bootstrap surface.
+
+Between sessions, prefer \`${VERICIFY_CONTEXT_RESUME_COMMAND}\` over rereading raw ACE files.
+
+When Claude compaction fires, re-inject \`${VERICIFY_PRECOMPACT_COMMAND}\`.
+
+## Vericify Process Posts
+
+When working in this workspace, emit native Vericify process posts at these moments:
+
+- **Blocker:** \`vericify post --run-id workspace:current --agent-id claude-code --kind blocker --summary "<what is blocking and what is needed>"\`
+- **Handoff initiated or acknowledged:** \`vericify post --run-id workspace:current --agent-id claude-code --kind handoff_note --summary "<what was handed off and what is expected next>"\`
+- **Meaningful work completed:** \`vericify post --run-id workspace:current --agent-id claude-code --kind completion --summary "<what changed and what is now true>"\`
+- **Extended silence is intentional:** \`vericify post --run-id workspace:current --agent-id claude-code --kind stale_ack --summary "<why silence is expected and when to re-check>"\`
+
+These posts are how Vericify tracks run narrative. Without them the hub cannot distinguish active silence from stale work.
+${VERICIFY_END_MARKER}`;
+}
+
+function upsertClaudeInstruction(workspaceRoot) {
+  const path = resolve(workspaceRoot, "CLAUDE.md");
+  const existing = readText(path, "");
+  const nextBlock = markerBlock();
+  const blockPattern = new RegExp(`${VERICIFY_MARKER}[\\s\\S]*?${VERICIFY_END_MARKER}`);
+  const prefix = existing.trimEnd();
+  const next = blockPattern.test(existing)
+    ? existing.replace(blockPattern, nextBlock)
+    : prefix
+      ? `${prefix}\n\n${nextBlock}\n`
+      : `${nextBlock}\n`;
+  if (next !== existing) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, next);
+    return { path, written: true };
+  }
+  return { path, written: false };
+}
+
+function upsertClaudeSettings(workspaceRoot, commands) {
+  const claudeDir = resolve(workspaceRoot, CLAUDE_DIR);
+  const settingsPath = join(claudeDir, CLAUDE_SETTINGS_FILE);
+  if (!existsSync(claudeDir)) {
+    return {
+      path: settingsPath,
+      written: false,
+      skipped_reason: `${CLAUDE_DIR} directory is missing; Claude hook installation skipped`,
+    };
+  }
+
+  const currentSettings = readJson(settingsPath, {});
+  const nextSettings = {
+    ...currentSettings,
+    hooks: {
+      ...(currentSettings.hooks && typeof currentSettings.hooks === "object" ? currentSettings.hooks : {}),
+    },
+  };
+  for (const [hookName, command] of Object.entries(commands)) {
+    const currentGroups = Array.isArray(nextSettings.hooks[hookName])
+      ? nextSettings.hooks[hookName].map((group) => ({
+          ...group,
+          hooks: Array.isArray(group.hooks) ? group.hooks.map((hook) => ({ ...hook })) : [],
+        }))
+      : [];
+    const nextGroups = currentGroups.map((group) => ({
+      ...group,
+      hooks: Array.isArray(group.hooks) ? group.hooks.filter((hook) => !hook?._vericify) : [],
+    }));
+    const targetIndex = nextGroups.findIndex((group) => String(group?.matcher ?? "") === "");
+    const targetGroup = targetIndex >= 0 ? nextGroups[targetIndex] : { matcher: "", hooks: [] };
+    targetGroup.hooks = Array.isArray(targetGroup.hooks) ? targetGroup.hooks : [];
+    targetGroup.hooks.push({
+      _vericify: true,
+      type: "command",
+      command,
+    });
+    if (targetIndex >= 0) {
+      nextGroups[targetIndex] = targetGroup;
+    } else {
+      nextGroups.push(targetGroup);
+    }
+    nextSettings.hooks[hookName] = nextGroups.filter((group) => Array.isArray(group.hooks) && group.hooks.length > 0);
+  }
+
+  const nextRaw = `${JSON.stringify(nextSettings, null, 2)}\n`;
+  const currentRaw = readText(settingsPath, "");
+  if (nextRaw !== currentRaw) {
+    mkdirSync(dirname(settingsPath), { recursive: true });
+    writeFileSync(settingsPath, nextRaw);
+    return { path: settingsPath, written: true, settings: nextSettings };
+  }
+  return { path: settingsPath, written: false, settings: nextSettings };
+}
+
+export function claudeCodeHandshake(workspaceRoot, options = {}) {
+  const result = createHandshakeResult();
+  const skippedReasons = [];
+
+  try {
+    const settingsResult = upsertClaudeSettings(workspaceRoot, {
+      PostToolUse: "vericify event --source-module claude-code --event-type TOOL_COMPLETED --status done",
+      Stop: "vericify event --source-module claude-code --event-type SESSION_STOPPED --status done",
+      PreCompact: VERICIFY_PRECOMPACT_COMMAND,
+    });
+    result.hooks_written = Boolean(settingsResult.written);
+    result.hooks_path = settingsResult.path;
+    if (settingsResult.skipped_reason) skippedReasons.push(settingsResult.skipped_reason);
+  } catch (error) {
+    skippedReasons.push(`Claude settings write failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  try {
+    const instructionResult = upsertClaudeInstruction(workspaceRoot);
+    result.instruction_written = Boolean(instructionResult.written);
+    result.instruction_path = instructionResult.path;
+  } catch (error) {
+    skippedReasons.push(`CLAUDE.md write failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  const eventResult = emitHandshakeStartedEvent(workspaceRoot, {
+    adapterId: "claude-code",
+    sessionId: options.sessionId ?? null,
+    hooksWritten: result.hooks_written,
+    instructionWritten: result.instruction_written,
+  });
+
+  return {
+    ...result,
+    event_emitted: eventResult.event_emitted,
+    skipped_reasons: [...skippedReasons, ...eventResult.skipped_reasons],
+  };
+}
+
+export { claudeCodeHandshake as attachClaudeWorkspace };

package/src/adapters/handshake/codex.js

@@ -0,0 +1,75 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { createHandshakeResult, emitHandshakeStartedEvent, mergeJsonFile, writeInstructionBlock } from "./common.js";
+
+const VERICIFY_MARKER = "<!-- vericify-instruction -->";
+
+function codexInstructionBlock() {
+  return `${VERICIFY_MARKER}
+## Vericify Process Posts
+
+When working in this workspace, emit native Vericify process posts at these moments:
+
+- **Blocker:** \`vericify post --run-id workspace:current --agent-id codex --kind blocker --summary "<what is blocking>"\`
+- **Handoff:** \`vericify post --run-id workspace:current --agent-id codex --kind handoff_note --summary "<handoff context>"\`
+- **Completion:** \`vericify post --run-id workspace:current --agent-id codex --kind completion --summary "<what changed>"\`
+- **Intentional silence:** \`vericify post --run-id workspace:current --agent-id codex --kind stale_ack --summary "<reason>"\`
+
+You may also write structured state directly to \`.codex/vericify-state.json\` using the passthrough schema (handoffs, nodes, entries, events, posts).
+<!-- /vericify-instruction -->`;
+}
+
+export function codexHandshake(workspaceRoot, options = {}) {
+  const result = createHandshakeResult();
+  const skippedReasons = [];
+  let instructionResult = { skipped: false, reason: "" };
+  const codexDir = resolve(workspaceRoot, ".codex");
+  const statePath = resolve(codexDir, "vericify-state.json");
+  const agentsPath = resolve(workspaceRoot, "AGENTS.md");
+
+  if (existsSync(codexDir)) {
+    try {
+      const mergeResult = mergeJsonFile(statePath, (existing) => ({
+        ...(existing && typeof existing === "object" ? existing : {}),
+        _vericify_passthrough: true,
+        handoffs: existing?.handoffs && typeof existing.handoffs === "object" ? existing.handoffs : {},
+        nodes: existing?.nodes && typeof existing.nodes === "object" ? existing.nodes : {},
+        entries: Array.isArray(existing?.entries) ? existing.entries : [],
+        events: Array.isArray(existing?.events) ? existing.events : [],
+        posts: Array.isArray(existing?.posts) ? existing.posts : [],
+      }));
+      result.passthrough_written = Boolean(mergeResult.written);
+      result.passthrough_path = statePath;
+    } catch (error) {
+      skippedReasons.push(`.codex/vericify-state.json write failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  } else {
+    skippedReasons.push(".codex directory is missing; passthrough config skipped");
+  }
+
+  try {
+    instructionResult = writeInstructionBlock(agentsPath, VERICIFY_MARKER, codexInstructionBlock(), {
+      createIfAbsent: true,
+      createDirs: true,
+    });
+    result.instruction_written = Boolean(instructionResult.written);
+    result.instruction_path = agentsPath;
+    if (instructionResult.skipped) skippedReasons.push(instructionResult.reason);
+  } catch (error) {
+    skippedReasons.push(`AGENTS.md write failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  const eventResult = emitHandshakeStartedEvent(workspaceRoot, {
+    adapterId: "codex",
+    sessionId: options.sessionId ?? null,
+    hooksWritten: false,
+    instructionWritten: result.instruction_written,
+    passthroughWritten: result.passthrough_written,
+  });
+
+  return {
+    ...result,
+    event_emitted: eventResult.event_emitted,
+    skipped_reasons: [...skippedReasons, ...(instructionResult.skipped ? [instructionResult.reason] : []), ...eventResult.skipped_reasons].filter(Boolean),
+  };
+}

package/src/adapters/handshake/common.js

@@ -0,0 +1,130 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { readJson, readText } from "../../core/fs.js";
+import { isoNow } from "../../core/util.js";
+import { appendStatusEvent } from "../../store/status-events.js";
+
+export function createHandshakeResult() {
+  return {
+    hooks_written: false,
+    hooks_path: null,
+    mcp_written: false,
+    mcp_path: null,
+    instruction_written: false,
+    instruction_path: null,
+    passthrough_written: false,
+    passthrough_path: null,
+    event_emitted: false,
+    skipped_reasons: [],
+  };
+}
+
+function ensureParentDir(filePath) {
+  mkdirSync(dirname(filePath), { recursive: true });
+}
+
+export function mergeJsonFile(filePath, mergeFn, { createIfAbsent = true } = {}) {
+  if (!existsSync(filePath) && !createIfAbsent) {
+    return {
+      written: false,
+      skipped: true,
+      reason: `${filePath} is missing; skipped.`,
+      value: null,
+    };
+  }
+
+  const currentRaw = readText(filePath, "");
+  const existing = currentRaw.trim() ? readJson(filePath, null) : null;
+  const next = mergeFn(existing);
+  const nextRaw = `${JSON.stringify(next, null, 2)}\n`;
+  if (nextRaw === currentRaw) {
+    return {
+      written: false,
+      skipped: false,
+      reason: "Already up to date.",
+      value: next,
+    };
+  }
+
+  ensureParentDir(filePath);
+  writeFileSync(filePath, nextRaw);
+  return {
+    written: true,
+    skipped: false,
+    reason: "",
+    value: next,
+  };
+}
+
+export function writeInstructionBlock(filePath, markerComment, block, { createIfAbsent = true, createDirs = true } = {}) {
+  const currentRaw = readText(filePath, "");
+  if (!currentRaw && !createIfAbsent) {
+    return {
+      written: false,
+      skipped: true,
+      reason: `${filePath} is missing; skipped.`,
+    };
+  }
+
+  if (currentRaw.includes(markerComment)) {
+    return {
+      written: false,
+      skipped: false,
+      reason: "Instruction block already present.",
+    };
+  }
+
+  if (createDirs) {
+    ensureParentDir(filePath);
+  }
+
+  const body = String(block ?? "").trimEnd();
+  const next = currentRaw.trimEnd()
+    ? `${currentRaw.trimEnd()}\n\n${body}\n`
+    : `${body}\n`;
+  if (next === currentRaw) {
+    return {
+      written: false,
+      skipped: false,
+      reason: "Already up to date.",
+    };
+  }
+
+  writeFileSync(filePath, next);
+  return {
+    written: true,
+    skipped: false,
+    reason: "",
+  };
+}
+
+export function emitHandshakeStartedEvent(workspaceRoot, { adapterId, sessionId, hooksWritten, instructionWritten, mcpWritten = false, passthroughWritten = false }) {
+  try {
+    appendStatusEvent(workspaceRoot, {
+      source_module: adapterId,
+      event_type: "SESSION_STARTED",
+      status: "started",
+      payload: {
+        summary: `${adapterId} adapter attached.`,
+        adapter_id: adapterId,
+        session_id: sessionId ?? null,
+        hooks_written: Boolean(hooksWritten),
+        instruction_written: Boolean(instructionWritten),
+        workspace_root: workspaceRoot,
+        mcp_written: Boolean(mcpWritten),
+        passthrough_written: Boolean(passthroughWritten),
+      },
+    });
+    return {
+      event_emitted: true,
+      skipped_reasons: [],
+      timestamp: isoNow(),
+    };
+  } catch (error) {
+    return {
+      event_emitted: false,
+      skipped_reasons: [`Failed to emit SESSION_STARTED: ${error instanceof Error ? error.message : String(error)}`],
+      timestamp: isoNow(),
+    };
+  }
+}

package/src/adapters/handshake/cursor.js

@@ -0,0 +1,100 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { createHandshakeResult, emitHandshakeStartedEvent, mergeJsonFile, writeInstructionBlock } from "./common.js";
+
+const VERICIFY_MARKER = "<!-- vericify-instruction -->";
+
+function cursorInstructionBlock() {
+  return `---
+description: Vericify process post instructions
+alwaysApply: true
+---
+
+## Vericify Process Posts
+
+When working in this workspace, emit native Vericify process posts at these moments:
+
+- **Blocker:** \`vericify post --run-id workspace:current --agent-id cursor --kind blocker --summary "<what is blocking>"\`
+- **Handoff:** \`vericify post --run-id workspace:current --agent-id cursor --kind handoff_note --summary "<handoff context>"\`
+- **Completion:** \`vericify post --run-id workspace:current --agent-id cursor --kind completion --summary "<what changed>"\`
+- **Intentional silence:** \`vericify post --run-id workspace:current --agent-id cursor --kind stale_ack --summary "<reason>"\``;
+}
+
+export function cursorHandshake(workspaceRoot, options = {}) {
+  const result = createHandshakeResult();
+  const skippedReasons = [];
+  const cursorDir = resolve(workspaceRoot, ".cursor");
+  const cursorMcpPath = resolve(cursorDir, "mcp.json");
+  const rulesDir = resolve(cursorDir, "rules");
+  const fallbackRulesPath = resolve(workspaceRoot, ".cursorrules");
+  const mcpPlaceholder = {
+    _vericify: true,
+    mcpServers: {
+      vericify: {
+        command: "vericify-mcp",
+        args: ["--workspace-root", "."],
+        _note: "vericify-mcp not yet installed. Run: npm install -g vericify-mcp",
+      },
+    },
+  };
+
+  if (existsSync(cursorDir)) {
+    try {
+      const mcpResult = mergeJsonFile(cursorMcpPath, (existing) => {
+        const current = existing && typeof existing === "object" ? existing : {};
+        return {
+          ...current,
+          _vericify: true,
+          mcpServers: {
+            ...(current.mcpServers && typeof current.mcpServers === "object" ? current.mcpServers : {}),
+            vericify: current.mcpServers?.vericify ?? mcpPlaceholder.mcpServers.vericify,
+          },
+        };
+      });
+      result.mcp_written = Boolean(mcpResult.written);
+      result.mcp_path = cursorMcpPath;
+      if (mcpResult.skipped) skippedReasons.push(mcpResult.reason);
+    } catch (error) {
+      skippedReasons.push(`.cursor/mcp.json write failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  } else {
+    skippedReasons.push(".cursor directory is missing; MCP placeholder skipped");
+  }
+
+  let instructionTarget = null;
+  if (existsSync(rulesDir)) {
+    instructionTarget = resolve(rulesDir, "vericify.mdc");
+  } else if (existsSync(fallbackRulesPath)) {
+    instructionTarget = fallbackRulesPath;
+  }
+
+  if (instructionTarget) {
+    try {
+      const instructionResult = writeInstructionBlock(instructionTarget, VERICIFY_MARKER, cursorInstructionBlock(), {
+        createIfAbsent: true,
+        createDirs: true,
+      });
+      result.instruction_written = Boolean(instructionResult.written);
+      result.instruction_path = instructionTarget;
+      if (instructionResult.skipped) skippedReasons.push(instructionResult.reason);
+    } catch (error) {
+      skippedReasons.push(`Cursor instruction write failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  } else {
+    skippedReasons.push("No .cursor/rules/ or .cursorrules file exists; instruction block skipped");
+  }
+
+  const eventResult = emitHandshakeStartedEvent(workspaceRoot, {
+    adapterId: "cursor",
+    sessionId: options.sessionId ?? null,
+    hooksWritten: false,
+    instructionWritten: result.instruction_written,
+    mcpWritten: result.mcp_written,
+  });
+
+  return {
+    ...result,
+    event_emitted: eventResult.event_emitted,
+    skipped_reasons: [...skippedReasons, ...eventResult.skipped_reasons].filter(Boolean),
+  };
+}

package/src/adapters/handshake/index.js

@@ -0,0 +1,35 @@
+import { createHandshakeResult } from "./common.js";
+import { antigravityHandshake } from "./antigravity.js";
+import { claudeCodeHandshake } from "./claude-code.js";
+import { codexHandshake } from "./codex.js";
+import { cursorHandshake } from "./cursor.js";
+import { vscodeCopilotHandshake } from "./vscode-copilot.js";
+
+const HANDSHAKE_FNS = {
+  "claude-code": claudeCodeHandshake,
+  codex: codexHandshake,
+  cursor: cursorHandshake,
+  "vscode-copilot-chat": vscodeCopilotHandshake,
+  antigravity: antigravityHandshake,
+};
+
+export function runHandshake(workspaceRoot, options = {}) {
+  const adapterId = String(options.adapterId ?? "").trim();
+  const fn = HANDSHAKE_FNS[adapterId];
+  if (!fn) {
+    return {
+      skipped: true,
+      reason: "No handshake defined for this adapter.",
+      ...createHandshakeResult(),
+    };
+  }
+
+  try {
+    return fn(workspaceRoot, options);
+  } catch (error) {
+    return {
+      ...createHandshakeResult(),
+      skipped_reasons: [`Handshake failed: ${error instanceof Error ? error.message : String(error)}`],
+    };
+  }
+}