vericify 0.1.0

package/README.md

@@ -0,0 +1,389 @@
+# Vericify
+
+```text
+__     _______ ____  ___ ____ ___ _______   __
+\ \   / / ____|  _ \|_ _/ ___|_ _|  ___\ \ / /
+ \ \ / /|  _| | |_) || | |    | || |_   \ V /
+  \ V / | |___|  _ < | | |___ | ||  _|   | |
+   \_/  |_____|_| \_\___\____|___|_|     |_|
+```
+
+Vericify is a local-first operations hub for agent work.
+
+It gives a workspace a durable run model instead of making you reconstruct intent from chat scrollback, shell history, and raw logs.
+
+It works on its own, and it also plugs neatly into [ACE / ace-swarm](https://www.npmjs.com/package/ace-swarm) workspaces that already emit `agent-state/*`.
+
+## Product Summary
+
+Vericify is for people building with agents who want to answer questions like:
+
+- What is moving right now?
+- What is blocked?
+- Which run diverged?
+- Which earlier run looks like a recovery path?
+- What should I publish or hand off?
+
+The package installs one CLI:
+
+```bash
+vericify
+```
+
+Default behavior is simple:
+
+- run it inside the repo you want to observe
+- store native state in `.vericify/`
+- read partner state from `agent-state/*` when present
+- open the terminal hub with `vericify` or `vericify hub`
+
+## What Vericify Does
+
+Vericify gives you:
+
+- a terminal cockpit for run inspection
+- a structured run model built from handoffs, posts, todos, events, and checkpoints
+- a compare engine that explains divergence and recovery
+- publishable run artifacts under `.vericify/published/`
+- a local-first sync outbox under `.vericify/sync-outbox/`
+- partner compatibility with [ACE / ace-swarm](https://www.npmjs.com/package/ace-swarm)
+
+## Install
+
+```bash
+npm install -g vericify
+```
+
+Node `18+` is required.
+
+## Five-Minute Start
+
+### 1) Start in any repo
+
+```bash
+cd /path/to/repo
+vericify adapters
+vericify hub
+```
+
+If Vericify already sees `.vericify/` or `agent-state/*`, the hub can immediately project runs from that workspace.
+
+### 2) If you already use [ACE / ace-swarm](https://www.npmjs.com/package/ace-swarm)
+
+This is the easiest path.
+
+If your workspace already contains `agent-state/*`, Vericify reads it automatically:
+
+```bash
+cd /path/to/ace-workspace
+vericify adapters
+vericify hub
+```
+
+No extra conversion step is required.
+
+### 3) If you are using another agent client and want to label it explicitly
+
+Attach the adapter to the current workspace:
+
+```bash
+vericify attach --adapter codex --label "Primary Codex session"
+vericify adapters
+```
+
+That creates or updates `.vericify/adapters.json` for the current repo and marks the adapter as attached.
+
+## Do I Need `--session-id`?
+
+No. `--session-id` is optional.
+
+Use no session ID when:
+
+- one active session per tool is enough
+- you only want to label the workspace relationship
+- you want the lightest setup
+
+Add a session ID when:
+
+- you run multiple sessions from the same tool
+- you want stable names in artifacts and dashboards
+- you want to distinguish roles like `claude-main` and `claude-review`
+
+Good session IDs look like:
+
+- `claude-main`
+- `codex-bugfix`
+- `cursor-review-01`
+
+## What Attachment Looks Like
+
+### A) Attach without a session ID
+
+This is valid:
+
+```bash
+vericify attach --adapter codex --label "Primary Codex session"
+```
+
+Simplified output:
+
+```json
+{
+  "path": ".vericify/adapters.json",
+  "attachment": {
+    "adapter_id": "codex",
+    "capture_mode": "manual",
+    "label": "Primary Codex session"
+  }
+}
+```
+
+Notes:
+
+- `capture_mode` defaults to `manual` if you do not set one
+- this is enough to tell Vericify "track this tool in this workspace"
+
+### B) Attach with a session ID
+
+Use this when you want a named session:
+
+```bash
+vericify attach --adapter claude-code --session-id claude-main --capture-mode attachment --label "Claude main"
+```
+
+Simplified output:
+
+```json
+{
+  "path": ".vericify/adapters.json",
+  "attachment": {
+    "adapter_id": "claude-code",
+    "capture_mode": "attachment",
+    "session_id": "claude-main",
+    "label": "Claude main"
+  }
+}
+```
+
+After that, verify status:
+
+```bash
+vericify adapters
+```
+
+Look for:
+
+- `detection_status: "attached"`
+- `session_id` when you supplied one
+- `label_override` with your human-friendly name
+
+## Easy Use Cases
+
+### Use case 1: Observe an existing [ACE / ace-swarm](https://www.npmjs.com/package/ace-swarm) workspace
+
+```bash
+cd /path/to/ace-workspace
+vericify adapters
+vericify hub
+```
+
+Best when you already have `agent-state/*` and want a cockpit, history, and compare surface.
+
+### Use case 2: Tag a Codex or Claude Code workspace before richer capture exists
+
+```bash
+vericify attach --adapter codex --label "Primary Codex"
+vericify attach --adapter claude-code --session-id claude-main --capture-mode attachment
+vericify hub
+```
+
+Best when you want durable workspace metadata now, even before vendor-specific live capture bridges are added.
+
+### Use case 3: Create a native run trail manually
+
+```bash
+vericify handoff --id h1 --from capability-ops --to capability-build --title "Implement compare engine" --status open
+vericify post --run-id handoff:h1 --agent-id capability-build --kind progress --summary "Builder started compare engine"
+vericify snapshot
+vericify hub
+```
+
+Best when you want to model agent work directly in Vericify.
+
+### Use case 4: Compare two runs
+
+```bash
+vericify compare --run-id handoff:run-a --compare-run-id workspace:current
+```
+
+The comparison report includes:
+
+- composite similarity
+- latest checkpoint similarity
+- actor overlap
+- node overlap
+- layer-level divergence cues
+- recovery explanations
+- recommended next actions
+
+### Use case 5: Publish or queue a run artifact
+
+```bash
+vericify publish --run-id handoff:run-a --compare-run-id workspace:current --title "Run A artifact"
+vericify sync --run-id handoff:run-a --compare-run-id workspace:current --endpoint https://sync.example.test
+```
+
+This writes:
+
+- `.vericify/published/<artifact-id>/run-artifact.json`
+- `.vericify/published/<artifact-id>/SUMMARY.md`
+- `.vericify/sync-outbox/<item>.json`
+
+## Product Spec
+
+### Core Objects
+
+- `Run`: one coordinated attempt to complete an objective
+- `Branch`: an alternate path inside a run
+- `Lane`: one concurrent execution stream
+- `Handoff`: transfer of responsibility
+- `Checkpoint`: durable snapshot at a meaningful transition
+- `Delta`: structural, semantic, or operational change between checkpoints
+
+### Storage Contract
+
+Vericify writes native state here:
+
+```text
+.vericify/
+|-- adapters.json
+|-- handoffs.json
+|-- todo-state.json
+|-- run-ledger.json
+|-- status-events.ndjson
+|-- process-posts.json
+|-- published/
+`-- sync-outbox/
+```
+
+Vericify also reads partner state here when available:
+
+```text
+agent-state/
+`-- ...
+```
+
+This is why it works naturally with [ACE / ace-swarm](https://www.npmjs.com/package/ace-swarm) workspaces.
+
+### Adapter Contract
+
+Current adapter registry:
+
+- `local-state`
+- `ace`
+- `codex`
+- `claude-code`
+- `cursor`
+- `vscode-copilot-chat`
+- `antigravity`
+
+Current truth:
+
+- `local-state` is fully implemented
+- `ace` is the partner path for [ACE / ace-swarm](https://www.npmjs.com/package/ace-swarm) style workspaces
+- peer adapters are currently attachment and detection contracts
+- auto-detection is heuristic for several tools, so explicit attachment is the reliable path
+
+### Checkpoint Policy
+
+Checkpoint triggers currently include:
+
+- `handoff`
+- `status_transition`
+- `process_milestone`
+- `ledger_update`
+- `operator_save`
+- `branch_fork`
+
+Capture modes currently include:
+
+- `semantic`
+- `git`
+- `hybrid`
+
+Today the package is semantic-first. Git-backed provenance can be attached when available.
+
+## CLI Reference
+
+### High-signal commands
+
+```bash
+vericify help
+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 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
+```
+
+### Native writer commands
+
+```bash
+vericify handoff --id h1 --from capability-ops --to capability-build --title "Review" --status open
+vericify todo --id todo-1 --title "Write store" --status in_progress
+vericify ledger --tool vericify --category major_update --message "Writer landed"
+vericify event --source-module capability-build --event-type STORE_WRITE --status started --payload-json '{"summary":"native write"}'
+vericify post --run-id handoff:h1 --agent-id capability-build --kind progress --summary "Checkpoint emitted"
+```
+
+### Helpful defaults
+
+- current working directory is the workspace unless you pass `--workspace-root`
+- `vericify` with no command opens `hub`
+- `--session-id` is optional
+- `--compare-run-id` is optional for `publish` and `sync`
+
+## Terminal Hub Controls
+
+Start the cockpit:
+
+```bash
+vericify hub
+```
+
+Keys:
+
+- `q` quit
+- `j` / `k` move between runs
+- `Enter` inspect selected run
+- `c` compare selected run
+- `y` history view
+- `h` back to hub
+- `r` refresh
+- `/` command palette
+- `Ctrl+R` command history search
+
+## Programmatic API
+
+The package also exports:
+
+- `loadWorkspaceState`
+- `projectWorkspaceState`
+- `detectAdapters`
+- `attachAdapter`
+- `buildRunComparison`
+- `publishRunArtifact`
+- `enqueueSyncOutboxItem`
+
+## Honest Status
+
+Vericify is intentionally honest about what is implemented now.
+
+- peer client adapters are not full live capture bridges yet
+- hosted sync is an outbox contract today, not a running SaaS backend
+- git-backed diffing exists as optional provenance, not the whole product
+
+That is deliberate: the package is meant to be useful now, without pretending unfinished infrastructure already exists.

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "vericify",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "Local-first run intelligence and operations hub for agent systems.",
+  "main": "./src/api.js",
+  "exports": {
+    ".": "./src/api.js",
+    "./api": "./src/api.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "vericify": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "adapters": "node src/index.js adapters",
+    "attach": "node src/index.js attach",
+    "hub": "node src/index.js hub",
+    "compare": "node src/index.js compare",
+    "publish": "node src/index.js publish",
+    "sync": "node src/index.js sync",
+    "handoff": "node src/index.js handoff",
+    "todo": "node src/index.js todo",
+    "ledger": "node src/index.js ledger",
+    "event": "node src/index.js event",
+    "post": "node src/index.js post",
+    "snapshot": "node src/index.js snapshot",
+    "help": "node src/index.js help",
+    "test": "node --test test/**/*.test.mjs"
+  },
+  "keywords": [
+    "agents",
+    "ai",
+    "observability",
+    "tui",
+    "runs",
+    "checkpoints",
+    "diff",
+    "codex",
+    "claude-code",
+    "cursor",
+    "copilot",
+    "ace-swarm"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/adapters/index.js

@@ -0,0 +1,37 @@
+import { listLocalStatePaths, loadLocalState } from "./local-state.js";
+import {
+  attachWorkspaceAdapter,
+  detectWorkspaceAdapters,
+  listAdapterDefinitions,
+  readWorkspaceAdapterAttachments,
+} from "./registry.js";
+
+export const DEFAULT_ADAPTER = "local-state";
+
+export function listDefaultWorkspacePaths(workspaceRoot) {
+  return listLocalStatePaths(workspaceRoot);
+}
+
+export function loadWorkspaceState(workspaceRoot) {
+  const state = loadLocalState(workspaceRoot);
+  return {
+    ...state,
+    adapterProfiles: detectWorkspaceAdapters(workspaceRoot, state.adapterAttachments),
+  };
+}
+
+export function listAvailableAdapters() {
+  return listAdapterDefinitions();
+}
+
+export function detectAdapters(workspaceRoot) {
+  return detectWorkspaceAdapters(workspaceRoot);
+}
+
+export function readAdapterAttachments(workspaceRoot) {
+  return readWorkspaceAdapterAttachments(workspaceRoot);
+}
+
+export function attachAdapter(workspaceRoot, input) {
+  return attachWorkspaceAdapter(workspaceRoot, input);
+}

package/src/adapters/local-state.js

@@ -0,0 +1,86 @@
+import { hashText, unique } from "../core/util.js";
+import { readJson, readNdjson } from "../core/fs.js";
+import { listStorePaths, resolveStoreLayout } from "../store/paths.js";
+import { readAdapterAttachments } from "../store/adapter-attachments.js";
+
+export function listLocalStatePaths(workspaceRoot) {
+  return listStorePaths(workspaceRoot);
+}
+
+function mergeByKey(preferredItems, partnerItems, getKey) {
+  const merged = new Map();
+  for (const item of partnerItems) merged.set(getKey(item), item);
+  for (const item of preferredItems) merged.set(getKey(item), item);
+  return [...merged.values()];
+}
+
+function mergeOrderedIds(preferred, partner) {
+  return unique([...preferred, ...partner]);
+}
+
+export function loadLocalState(workspaceRoot) {
+  const paths = resolveStoreLayout(workspaceRoot);
+  const adapterAttachmentState = readAdapterAttachments(workspaceRoot);
+  const vericifyState = {
+    handoffRegistry: readJson(paths.vericify.handoffRegistry, { handoffs: {} }),
+    todoState: readJson(paths.vericify.todoState, { nodes: {}, order: [] }),
+    runLedger: readJson(paths.vericify.runLedger, { entries: [] }),
+    processPosts: readJson(paths.vericify.processPosts, { posts: [] }),
+    statusEvents: readNdjson(paths.vericify.statusEvents),
+  };
+  const partnerState = {
+    handoffRegistry: readJson(paths.partner.handoffRegistry, { handoffs: {} }),
+    todoState: readJson(paths.partner.todoState, { nodes: {}, order: [] }),
+    runLedger: readJson(paths.partner.runLedger, { entries: [] }),
+    processPosts: readJson(paths.partner.processPosts, { posts: [] }),
+    statusEvents: readNdjson(paths.partner.statusEvents),
+  };
+
+  const handoffs = mergeByKey(
+    Object.values(vericifyState.handoffRegistry.handoffs ?? {}),
+    Object.values(partnerState.handoffRegistry.handoffs ?? {}),
+    (handoff) => handoff.handoff_id ?? hashText(JSON.stringify(handoff))
+  );
+  const todoNodes = mergeByKey(
+    Object.values(vericifyState.todoState.nodes ?? {}),
+    Object.values(partnerState.todoState.nodes ?? {}),
+    (node) => node.id ?? hashText(JSON.stringify(node))
+  );
+  const ledgerEntries = mergeByKey(
+    Array.isArray(vericifyState.runLedger.entries) ? vericifyState.runLedger.entries : [],
+    Array.isArray(partnerState.runLedger.entries) ? partnerState.runLedger.entries : [],
+    (entry) => entry.id ?? hashText(`${entry.timestamp_utc}:${entry.tool}:${entry.message}`)
+  );
+  const statusEvents = mergeByKey(
+    vericifyState.statusEvents,
+    partnerState.statusEvents,
+    (event) => event.event_id ?? hashText(`${event.timestamp}:${event.source_module}:${event.event_type}:${event.status}`)
+  ).sort((left, right) => String(left.timestamp).localeCompare(String(right.timestamp)));
+  const processPosts = mergeByKey(
+    Array.isArray(vericifyState.processPosts.posts) ? vericifyState.processPosts.posts : [],
+    Array.isArray(partnerState.processPosts.posts) ? partnerState.processPosts.posts : [],
+    (post) => post.process_post_id ?? hashText(`${post.timestamp}:${post.agent_id}:${post.summary}`)
+  ).sort((left, right) => String(left.timestamp).localeCompare(String(right.timestamp)));
+
+  return {
+    workspaceRoot,
+    handoffs,
+    todoNodes,
+    todoOrder: mergeOrderedIds(
+      Array.isArray(vericifyState.todoState.order) ? vericifyState.todoState.order : [],
+      Array.isArray(partnerState.todoState.order) ? partnerState.todoState.order : []
+    ),
+    ledgerEntries,
+    statusEvents,
+    processPosts,
+    adapterAttachments: Array.isArray(adapterAttachmentState.attachments) ? adapterAttachmentState.attachments : [],
+    sourceRefs: {
+      adapterAttachments: [paths.vericify.adapterAttachments],
+      handoffRegistry: [paths.vericify.handoffRegistry, paths.partner.handoffRegistry],
+      todoState: [paths.vericify.todoState, paths.partner.todoState],
+      runLedger: [paths.vericify.runLedger, paths.partner.runLedger],
+      statusEvents: [paths.vericify.statusEvents, paths.partner.statusEvents],
+      processPosts: [paths.vericify.processPosts, paths.partner.processPosts],
+    },
+  };
+}

package/src/adapters/registry.js

@@ -0,0 +1,126 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { readAdapterAttachments, upsertAdapterAttachment } from "../store/adapter-attachments.js";
+
+const ADAPTER_DEFINITIONS = [
+  {
+    adapter_id: "local-state",
+    label: "Local State",
+    category: "native",
+    description: "Reads Vericify-native .vericify/* storage plus partner agent-state/* when present.",
+    detection_paths: [".vericify", "agent-state"],
+    capture_modes: ["filesystem"],
+    notes: ["Always available as the baseline local-first adapter."],
+  },
+  {
+    adapter_id: "ace",
+    label: "ACE / ace-swarm",
+    category: "partner",
+    description: "Partner adapter for ace-swarm workspaces that already emit agent-state/* artifacts.",
+    detection_paths: ["agent-state", ".agents", "AGENTS.md"],
+    capture_modes: ["filesystem", "attachment"],
+    notes: ["Out-of-box partner path when an ace-swarm style workspace is present."],
+  },
+  {
+    adapter_id: "codex",
+    label: "Codex",
+    category: "peer",
+    description: "Peer adapter contract for Codex sessions and workspace-attached process traces.",
+    detection_paths: [".codex", "AGENTS.md"],
+    capture_modes: ["attachment", "filesystem"],
+    notes: ["Auto-detection is heuristic; explicit attachment is the reliable path."],
+  },
+  {
+    adapter_id: "claude-code",
+    label: "Claude Code",
+    category: "peer",
+    description: "Peer adapter contract for Claude Code sessions and workspace-attached traces.",
+    detection_paths: [".claude", "CLAUDE.md"],
+    capture_modes: ["attachment", "filesystem"],
+    notes: ["Use adapter attachment when workspace hints are absent."],
+  },
+  {
+    adapter_id: "cursor",
+    label: "Cursor",
+    category: "peer",
+    description: "Peer adapter contract for Cursor-driven agent sessions.",
+    detection_paths: [".cursor", ".cursor/rules", ".cursorrules"],
+    capture_modes: ["attachment", "filesystem"],
+    notes: ["Workspace rules are treated as detection hints, not proof of live capture."],
+  },
+  {
+    adapter_id: "vscode-copilot-chat",
+    label: "VS Code Copilot Chat",
+    category: "peer",
+    description: "Peer adapter contract for VS Code Copilot Chat sessions and workspace traces.",
+    detection_paths: [".vscode", ".github/copilot-instructions.md"],
+    capture_modes: ["attachment", "filesystem"],
+    notes: ["Detection relies on editor/workspace hints; attach explicitly for certainty."],
+  },
+  {
+    adapter_id: "antigravity",
+    label: "Antigravity",
+    category: "peer",
+    description: "Peer adapter contract for Antigravity sessions and workspace traces.",
+    detection_paths: [".antigravity", "antigravity.config.json"],
+    capture_modes: ["attachment", "filesystem"],
+    notes: ["Manual attachment is expected until a dedicated capture bridge ships."],
+  },
+];
+
+function detectPaths(workspaceRoot, relPaths) {
+  return relPaths
+    .map((relPath) => resolve(workspaceRoot, relPath))
+    .filter((path) => existsSync(path));
+}
+
+function profileStatus(definition, attached, detectedPaths) {
+  if (definition.adapter_id === "local-state") return "ready";
+  if (attached) return "attached";
+  if (detectedPaths.length) return "detected";
+  return "manual";
+}
+
+export function listAdapterDefinitions() {
+  return ADAPTER_DEFINITIONS.map((definition) => ({ ...definition }));
+}
+
+export function readWorkspaceAdapterAttachments(workspaceRoot) {
+  return readAdapterAttachments(workspaceRoot);
+}
+
+export function attachWorkspaceAdapter(workspaceRoot, input) {
+  return upsertAdapterAttachment(workspaceRoot, input);
+}
+
+export function detectWorkspaceAdapters(workspaceRoot, attachments = undefined) {
+  const attachmentList = attachments ?? readAdapterAttachments(workspaceRoot).attachments ?? [];
+  const byId = new Map(attachmentList.map((attachment) => [attachment.adapter_id, attachment]));
+  return ADAPTER_DEFINITIONS.map((definition) => {
+    const attached = byId.get(definition.adapter_id);
+    const detectedPaths = detectPaths(workspaceRoot, definition.detection_paths);
+    const status = profileStatus(definition, attached, detectedPaths);
+    return {
+      adapter_id: definition.adapter_id,
+      label: definition.label,
+      category: definition.category,
+      description: definition.description,
+      capture_modes: [...definition.capture_modes],
+      detection_status: status,
+      attached: Boolean(attached),
+      ready: status === "ready" || status === "attached" || status === "detected",
+      detection_paths: definition.detection_paths.map((relPath) => resolve(workspaceRoot, relPath)),
+      detected_paths: detectedPaths,
+      session_id: attached?.session_id,
+      source_refs: detectedPaths,
+      notes: [
+        ...definition.notes,
+        ...(attached?.notes ? [String(attached.notes)] : []),
+      ],
+      attached_at: attached?.attached_at,
+      updated_at: attached?.updated_at,
+      capture_mode: attached?.capture_mode,
+      label_override: attached?.label,
+    };
+  });
+}