@primitive.ai/prim 0.1.0-alpha.17 → 0.1.0-alpha.18

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: prim
-description: Use the prim CLI for managing Primitive specs, contexts, projects, and pre-commit hooks. TRIGGER when the user mentions Primitive, prim, "specs" (in the Primitive sense), or "contexts" (in the Primitive sense); when the repo's package.json depends on @primitive.ai/prim; when the user asks to sync, map, update, or auto-map a spec; when configuring Primitive pre-commit hooks. SKIP when "spec" means test specs (vitest, jest, rspec), when "context" means React context or LLM context window, or for unrelated CLIs.
+description: Use the prim CLI for Primitive specs, contexts, projects, pre-commit hooks, and the decision graph (passive decision capture, the conflict gate, reconcile, and team presence). TRIGGER when the user mentions Primitive, prim, "specs" or "contexts" (in the Primitive sense), or decisions / the decision graph / a conflict gate / reconcile; when the repo's package.json depends on @primitive.ai/prim; when the user asks to sync, map, update, or auto-map a spec; when an edit is denied or warned by a prior decision; when configuring Primitive hooks. SKIP when "spec" means test specs (vitest, jest, rspec), when "context" means React context or an LLM context window, or for unrelated CLIs.
 ---
 
 # Working with the prim CLI
@@ -35,6 +35,36 @@ The CLI auto-refreshes expired tokens. On unrecoverable expiry it throws `Authen
 2. Every command accepts `--help`. When unsure of flags, run `npx --yes @primitive.ai/prim <cmd> --help` rather than guessing.
 3. The CLI prints API errors as one-liners to stderr and exits non-zero. Treat any non-zero exit as actionable. If a command fails with an unrecognized error, re-run with `--help` to check your flags. If auth-related, re-check `auth status`.
 
+## Working with the decision graph
+
+Separate from specs, prim passively captures the decisions you make during a coding session -- which library, which pattern, which config value -- into a queryable decision graph, and actively **gates** edits that would conflict with a load-bearing prior decision. Capture and the gate run automatically through the session hooks installed by `npx --yes @primitive.ai/prim claude install` (Claude Code) or `npx --yes @primitive.ai/prim codex install` (Codex). You never invoke capture; you *respond* to the gate and *read* the graph.
+
+### Heed the conflict gate
+Before an edit (Claude Code: Edit/Write/MultiEdit; Codex: apply_patch) a PreToolUse hook scores the target file against the graph:
+
+- **deny** -- the edit is blocked: it conflicts with a load-bearing prior decision. Don't fight it. Read the reason line; it names the decision id. If you genuinely intend to override that decision, run `npx --yes @primitive.ai/prim reconcile dec_<shortId>`, then retry the edit once. Otherwise choose an approach that respects the decision.
+- **warn / additional context** -- the edit proceeds, but a relevant prior decision is surfaced. Read it. On Codex a would-be `ask` is delivered as allow-plus-context (Codex can't pause mid-tool), so that context is your only signal -- read it before continuing.
+- **"decision check skipped / not verified" or "... partial / truncated"** -- the check could not fully run. Treat constraints as UNKNOWN, not clear; never read silence as approval.
+
+The gate fail-opens on its *own* infrastructure errors (no daemon, network blip, org-unbound token) -- a setup problem never blocks your edit. That is exactly why an "unavailable" note matters: it is the honest signal that the check, not your edit, is what failed.
+
+### Read the graph before large or load-bearing edits
+- `npx --yes @primitive.ai/prim decisions check --files "src/a.ts,src/b.ts"` -- which active decisions reference the files you're about to touch (comma-separated paths, one `--files` value). Run it before a big change.
+- `npx --yes @primitive.ai/prim decisions recent` -- the team's recent decisions, each row badged by author and agent (`Your Claude Code` / `Your Codex`); `--limit <n>` and `--since <dur>` narrow it.
+- `npx --yes @primitive.ai/prim decisions show <idOrShortId>` and `npx --yes @primitive.ai/prim decisions cascade <idOrShortId>` -- full detail, and the downstream blast radius a change would disturb.
+
+### Reconcile and the verdict footer
+`npx --yes @primitive.ai/prim reconcile <idOrShortId>` mints a single-use bypass for the named decision -- it prints `[prim] reconcile bypass issued for dec_<short> (expires in ...)` to STDERR, with the bypass JSON on STDOUT. Your *next* edit to the governed file then goes through, and on that edit prim prints a verdict footer to STDERR -- confirmation the override was recorded, not silently dropped:
+
+```
+✓ Conflict caught before merge · N decisions saved · <author>'s intent preserved
+```
+
+`N` is the reconciled decision's downstream live-dependent count, shown as `N+` when the server caps it.
+
+### Presence
+With the daemon running (`npx --yes @primitive.ai/prim daemon start`), `npx --yes @primitive.ai/prim daemon status` includes the live online count in its STDOUT JSON (when presence is fresh); Claude Code surfaces it in the statusline as `team: N online`. Your captured decisions are attributed to your agent automatically -- no flag required.
+
 ## Common workflows
 
 ### Read a spec's current text (do this before any partial edit)

package/dist/{chunk-LCC66K45.js → chunk-6LAQVM26.js}

@@ -1,34 +1,3 @@
-// src/hooks/prim-hook-core.ts
-import { randomUUID } from "crypto";
-import { platform } from "os";
-
-// src/protocol/move.ts
-var ENVELOPE_VERSION = 1;
-
-// src/hooks/prim-hook-core.ts
-function toMove(parsed, cliVersion, agent = "claude_code") {
-  return {
-    moveId: randomUUID(),
-    capturedAt: Date.now(),
-    sessionId: parsed.session_id ?? "",
-    eventType: parsed.hook_event_name ?? "unknown",
-    payload: parsed,
-    env: {
-      cwd: parsed.cwd ?? process.cwd(),
-      cliVersion,
-      osPlatform: platform()
-    },
-    envelopeVersion: ENVELOPE_VERSION,
-    // Stamp the producer only for Codex; Claude Code moves omit it (the
-    // backend defaults an absent value to "claude_code"), keeping the
-    // Claude wire shape byte-identical.
-    ...agent === "codex" ? { producer: "codex" } : {}
-  };
-}
-function shouldFlushAfter(eventType) {
-  return eventType === "SessionEnd";
-}
-
 // src/hooks/redact.ts
 import { existsSync, readFileSync } from "fs";
 import { join } from "path";
@@ -109,7 +78,5 @@ function scrubFromCwd(value, cwd) {
 }
 
 export {
-  toMove,
-  shouldFlushAfter,
   scrubFromCwd
 };

package/dist/chunk-7GHOFNJ2.js

@@ -0,0 +1,57 @@
+// src/hooks/prim-hook-core.ts
+import { randomUUID } from "crypto";
+import { platform } from "os";
+
+// src/protocol/move.ts
+var ENVELOPE_VERSION = 1;
+
+// src/hooks/prim-hook-core.ts
+function toMove(parsed, cliVersion, agent = "claude_code") {
+  return {
+    moveId: randomUUID(),
+    capturedAt: Date.now(),
+    sessionId: parsed.session_id ?? "",
+    eventType: parsed.hook_event_name ?? "unknown",
+    payload: parsed,
+    env: {
+      cwd: parsed.cwd ?? process.cwd(),
+      cliVersion,
+      osPlatform: platform()
+    },
+    envelopeVersion: ENVELOPE_VERSION,
+    // Stamp the producer only for Codex; Claude Code moves omit it (the
+    // backend defaults an absent value to "claude_code"), keeping the
+    // Claude wire shape byte-identical.
+    ...agent === "codex" ? { producer: "codex" } : {}
+  };
+}
+function toCommitMove(commit, cliVersion, cwd) {
+  return {
+    moveId: `commit:${commit.sha}`,
+    capturedAt: Date.now(),
+    sessionId: "",
+    eventType: "git.commit",
+    payload: {
+      kind: "git.commit",
+      sha: commit.sha,
+      parentSha: commit.parentSha,
+      branch: commit.branch,
+      files: commit.files
+    },
+    env: {
+      cwd,
+      cliVersion,
+      osPlatform: platform()
+    },
+    envelopeVersion: ENVELOPE_VERSION
+  };
+}
+function shouldFlushAfter(eventType) {
+  return eventType === "SessionEnd";
+}
+
+export {
+  toMove,
+  toCommitMove,
+  shouldFlushAfter
+};

package/dist/hooks/post-commit.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+import {
+  appendMove,
+  resolveOrg
+} from "../chunk-JZGWQDM5.js";
+import {
+  toCommitMove
+} from "../chunk-7GHOFNJ2.js";
+
+// src/hooks/post-commit.ts
+import { execSync, spawn } from "child_process";
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+var here = dirname(fileURLToPath(import.meta.url));
+function git(args) {
+  try {
+    return execSync(`git ${args}`, {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+  } catch {
+    return;
+  }
+}
+function readCommit() {
+  const sha = git("rev-parse HEAD");
+  if (!sha) {
+    return null;
+  }
+  const branch = git("rev-parse --abbrev-ref HEAD");
+  const files = (git("diff-tree --no-commit-id --name-only -r -m --root HEAD") ?? "").split("\n").filter((f) => f.length > 0);
+  return {
+    sha,
+    parentSha: git("rev-parse --verify --quiet HEAD^") || void 0,
+    branch: branch && branch !== "HEAD" ? branch : void 0,
+    files
+  };
+}
+function resolveCliVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync(join(here, "..", "..", "package.json"), "utf-8"));
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+function spawnBackgroundFlush() {
+  const entry = join(here, "..", "index.js");
+  spawn(process.execPath, [entry, "moves", "flush"], {
+    detached: true,
+    stdio: "ignore"
+  }).unref();
+}
+try {
+  const commit = readCommit();
+  if (commit) {
+    const cwd = git("rev-parse --show-toplevel") ?? process.cwd();
+    const move = toCommitMove(commit, resolveCliVersion(), cwd);
+    const { orgId } = resolveOrg({ sessionId: "", cwd });
+    appendMove(move, orgId);
+    spawnBackgroundFlush();
+  }
+} catch (err) {
+  if (process.env.PRIM_HOOK_DEBUG) {
+    const detail = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[prim-post-commit] capture failed: ${detail}
+`);
+  }
+}
+process.exit(0);

package/dist/hooks/post-tool-use.js

@@ -7,9 +7,11 @@ import {
   getClient
 } from "../chunk-6SIEWWUL.js";
 import {
-  scrubFromCwd,
+  scrubFromCwd
+} from "../chunk-6LAQVM26.js";
+import {
   toMove
-} from "../chunk-LCC66K45.js";
+} from "../chunk-7GHOFNJ2.js";
 import {
   parseAgent
 } from "../chunk-7YRBACIE.js";

package/dist/hooks/prim-hook.js

@@ -4,10 +4,12 @@ import {
   resolveOrg
 } from "../chunk-JZGWQDM5.js";
 import {
-  scrubFromCwd,
+  scrubFromCwd
+} from "../chunk-6LAQVM26.js";
+import {
   shouldFlushAfter,
   toMove
-} from "../chunk-LCC66K45.js";
+} from "../chunk-7GHOFNJ2.js";
 import {
   parseAgent
 } from "../chunk-7YRBACIE.js";

package/dist/index.js

@@ -1577,30 +1577,39 @@ import { execSync } from "child_process";
 import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync5, unlinkSync as unlinkSync2, writeFileSync as writeFileSync3 } from "fs";
 import { resolve } from "path";
 import { Option } from "commander";
-var HOOK_SCRIPT = `#!/bin/sh
-# prim pre-commit hook \u2014 auto-syncs affected specs on commit
-# Installed by: prim hooks install
-
-# Find the nearest node_modules/.bin with prim, or use npx
-if command -v prim-pre-commit >/dev/null 2>&1; then
-  prim-pre-commit
-elif [ -f "./node_modules/.bin/prim-pre-commit" ]; then
-  ./node_modules/.bin/prim-pre-commit
+var PRE_COMMIT = { hookName: "pre-commit", binName: "prim-pre-commit" };
+var POST_COMMIT = { hookName: "post-commit", binName: "prim-post-commit" };
+var HOOKS = [PRE_COMMIT, POST_COMMIT];
+function blockMarkers(spec) {
+  return {
+    start: `# >>> prim ${spec.hookName} hook >>>`,
+    end: `# <<< prim ${spec.hookName} hook <<<`
+  };
+}
+var PRIM_BLOCK_START = blockMarkers(PRE_COMMIT).start;
+var PRIM_BLOCK_END = blockMarkers(PRE_COMMIT).end;
+function hookShim(binName) {
+  return `if command -v ${binName} >/dev/null 2>&1; then
+  ${binName}
+elif [ -f "./node_modules/.bin/${binName}" ]; then
+  ./node_modules/.bin/${binName}
 else
-  npx --yes -p @primitive.ai/prim prim-pre-commit 2>/dev/null || true
-fi
+  npx --yes -p @primitive.ai/prim ${binName} 2>/dev/null || true
+fi`;
+}
+function dotGitScript(spec) {
+  return `#!/bin/sh
+# prim ${spec.hookName} hook \u2014 installed by: prim hooks install
+
+${hookShim(spec.binName)}
 `;
-var PRIM_BLOCK_START = "# >>> prim pre-commit hook >>>";
-var PRIM_BLOCK_END = "# <<< prim pre-commit hook <<<";
-var PRIM_HUSKY_BLOCK = `${PRIM_BLOCK_START}
-if command -v prim-pre-commit >/dev/null 2>&1; then
-  prim-pre-commit
-elif [ -f "./node_modules/.bin/prim-pre-commit" ]; then
-  ./node_modules/.bin/prim-pre-commit
-else
-  npx --yes -p @primitive.ai/prim prim-pre-commit 2>/dev/null || true
-fi
-${PRIM_BLOCK_END}`;
+}
+function huskyBlock(spec) {
+  const { start, end } = blockMarkers(spec);
+  return `${start}
+${hookShim(spec.binName)}
+${end}`;
+}
 function getGitRoot() {
   return execSync("git rev-parse --show-toplevel", {
     encoding: "utf-8"
@@ -1624,8 +1633,8 @@ function detectHusky(gitRoot) {
   }
   return false;
 }
-function containsPrimHook(content) {
-  return content.includes("prim-pre-commit");
+function containsPrimHook(content, binName = PRE_COMMIT.binName) {
+  return content.includes(binName);
 }
 async function askConfirmation(question) {
   if (!process.stdin.isTTY) return false;
@@ -1639,52 +1648,63 @@ async function askConfirmation(question) {
     rl.close();
   }
 }
-function installToHusky(gitRoot) {
-  const hookPath = resolve(gitRoot, ".husky", "pre-commit");
+function installToHusky(gitRoot, spec = PRE_COMMIT) {
+  const hookPath = resolve(gitRoot, ".husky", spec.hookName);
   if (existsSync4(hookPath)) {
     const existing = readFileSync5(hookPath, "utf-8");
-    if (containsPrimHook(existing)) {
-      console.log("Prim pre-commit hook is already installed in .husky/pre-commit.");
+    if (containsPrimHook(existing, spec.binName)) {
+      console.log(`Prim ${spec.hookName} hook is already installed in .husky/${spec.hookName}.`);
       return;
     }
     const separator = existing.endsWith("\n") ? "\n" : "\n\n";
-    writeFileSync3(hookPath, `${existing}${separator}${PRIM_HUSKY_BLOCK}
+    writeFileSync3(hookPath, `${existing}${separator}${huskyBlock(spec)}
 `, {
       mode: 493
     });
-    console.log("Appended prim hook block to .husky/pre-commit.");
+    console.log(`Appended prim hook block to .husky/${spec.hookName}.`);
   } else {
     writeFileSync3(hookPath, `#!/bin/sh
 
-${PRIM_HUSKY_BLOCK}
+${huskyBlock(spec)}
 `, {
       mode: 493
     });
-    console.log("Created .husky/pre-commit with prim hook block.");
+    console.log(`Created .husky/${spec.hookName} with prim hook block.`);
   }
 }
-function installToDotGit(gitRoot) {
+function installToDotGit(gitRoot, spec = PRE_COMMIT) {
   const hooksDir = resolve(gitRoot, ".git", "hooks");
-  const hookPath = resolve(hooksDir, "pre-commit");
+  const hookPath = resolve(hooksDir, spec.hookName);
   if (!existsSync4(hooksDir)) {
     mkdirSync3(hooksDir, { recursive: true });
   }
   if (existsSync4(hookPath)) {
     const existing = readFileSync5(hookPath, "utf-8");
-    if (containsPrimHook(existing)) {
-      console.log("Prim pre-commit hook is already installed at .git/hooks/pre-commit.");
+    if (containsPrimHook(existing, spec.binName)) {
+      console.log(`Prim ${spec.hookName} hook is already installed at ${hookPath}.`);
       return;
     }
-    console.log(`A pre-commit hook already exists at ${hookPath}.`);
+    console.log(`A ${spec.hookName} hook already exists at ${hookPath}.`);
     console.log("To replace it, run: prim hooks uninstall && prim hooks install");
     return;
   }
-  writeFileSync3(hookPath, HOOK_SCRIPT, { mode: 493 });
-  console.log(`Installed pre-commit hook at ${hookPath}`);
+  writeFileSync3(hookPath, dotGitScript(spec), { mode: 493 });
+  console.log(`Installed ${spec.hookName} hook at ${hookPath}`);
+}
+function installHooks(gitRoot, target) {
+  for (const spec of HOOKS) {
+    if (target === "husky") {
+      installToHusky(gitRoot, spec);
+    } else {
+      installToDotGit(gitRoot, spec);
+    }
+  }
 }
 function registerHooksCommands(program2) {
   const hooks = program2.command("hooks").description("Manage git hooks");
-  hooks.command("install").description("Install the prim pre-commit hook (auto-detects Husky; use --target to override)").addOption(
+  hooks.command("install").description(
+    "Install the prim git hooks \u2014 pre-commit + post-commit (auto-detects Husky; use --target to override)"
+  ).addOption(
     new Option("--target <where>", "install destination; bypasses Husky detection").choices([
       "husky",
       "git-hooks"
@@ -1695,10 +1715,10 @@ function registerHooksCommands(program2) {
       globals.nonInteractive || process.env.CI || process.env.PRIM_NON_INTERACTIVE
     );
     const gitRoot = getGitRoot();
-    if (opts.target === "husky") return installToHusky(gitRoot);
-    if (opts.target === "git-hooks") return installToDotGit(gitRoot);
+    if (opts.target === "husky") return installHooks(gitRoot, "husky");
+    if (opts.target === "git-hooks") return installHooks(gitRoot, "git-hooks");
     if (detectHusky(gitRoot)) {
-      if (globals.yes) return installToHusky(gitRoot);
+      if (globals.yes) return installHooks(gitRoot, "husky");
       if (nonInteractive) {
         throw new Error(
           "--non-interactive set, refusing to prompt for Husky-hook installation. Pass --yes to confirm or --target=git-hooks to choose."
@@ -1709,24 +1729,30 @@ function registerHooksCommands(program2) {
           "Note: Husky detected but stdin is not a TTY \u2014 falling back to .git/hooks. Pass --yes for Husky or --non-interactive to fail fast."
         );
       } else if (await askConfirmation(
-        "Husky detected. Install prim hook into .husky/pre-commit instead of .git/hooks/pre-commit?"
+        "Husky detected. Install prim hooks into .husky/ instead of .git/hooks/?"
       )) {
-        return installToHusky(gitRoot);
+        return installHooks(gitRoot, "husky");
       } else {
-        console.log("Falling back to .git/hooks/pre-commit install.");
+        console.log("Falling back to .git/hooks install.");
       }
     }
-    installToDotGit(gitRoot);
+    installHooks(gitRoot, "git-hooks");
   });
-  hooks.command("uninstall").description("Remove the prim pre-commit hook").action(() => {
+  hooks.command("uninstall").description("Remove the prim git hooks (.git/hooks)").action(() => {
     const gitRoot = getGitRoot();
-    const hookPath = resolve(gitRoot, ".git", "hooks", "pre-commit");
-    if (!existsSync4(hookPath)) {
-      console.log("No pre-commit hook found.");
-      return;
+    for (const spec of HOOKS) {
+      const hookPath = resolve(gitRoot, ".git", "hooks", spec.hookName);
+      if (!existsSync4(hookPath)) {
+        console.log(`No ${spec.hookName} hook found.`);
+        continue;
+      }
+      if (containsPrimHook(readFileSync5(hookPath, "utf-8"), spec.binName)) {
+        unlinkSync2(hookPath);
+        console.log(`Removed ${spec.hookName} hook at ${hookPath}`);
+      } else {
+        console.log(`Left ${spec.hookName} hook at ${hookPath} untouched (not a prim hook).`);
+      }
     }
-    unlinkSync2(hookPath);
-    console.log(`Removed pre-commit hook at ${hookPath}`);
   });
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitive.ai/prim",
-  "version": "0.1.0-alpha.17",
+  "version": "0.1.0-alpha.18",
   "description": "CLI for managing Primitive specs, contexts, and git hooks",
   "type": "module",
   "license": "MIT",
@@ -30,6 +30,7 @@
   "bin": {
     "prim": "dist/index.js",
     "prim-pre-commit": "dist/hooks/pre-commit.js",
+    "prim-post-commit": "dist/hooks/post-commit.js",
     "prim-hook": "dist/hooks/prim-hook.js",
     "prim-pre-tool-use": "dist/hooks/pre-tool-use.js",
     "prim-post-tool-use": "dist/hooks/post-tool-use.js",
@@ -45,9 +46,9 @@
     "SKILL.md"
   ],
   "scripts": {
-    "build": "tsup src/index.ts src/hooks/pre-commit.ts src/hooks/prim-hook.ts src/hooks/pre-tool-use.ts src/hooks/post-tool-use.ts src/hooks/session-start.ts src/hooks/session-end.ts src/daemon/server.ts --format esm --clean",
-    "postbuild": "chmod +x ./dist/index.js ./dist/hooks/pre-commit.js ./dist/hooks/prim-hook.js ./dist/hooks/pre-tool-use.js ./dist/hooks/post-tool-use.js ./dist/hooks/session-start.js ./dist/hooks/session-end.js ./dist/daemon/server.js",
-    "dev": "tsup src/index.ts src/hooks/pre-commit.ts src/hooks/prim-hook.ts src/hooks/pre-tool-use.ts src/hooks/post-tool-use.ts src/hooks/session-start.ts src/hooks/session-end.ts src/daemon/server.ts --format esm --watch --clean",
+    "build": "tsup src/index.ts src/hooks/pre-commit.ts src/hooks/post-commit.ts src/hooks/prim-hook.ts src/hooks/pre-tool-use.ts src/hooks/post-tool-use.ts src/hooks/session-start.ts src/hooks/session-end.ts src/daemon/server.ts --format esm --clean",
+    "postbuild": "chmod +x ./dist/index.js ./dist/hooks/pre-commit.js ./dist/hooks/post-commit.js ./dist/hooks/prim-hook.js ./dist/hooks/pre-tool-use.js ./dist/hooks/post-tool-use.js ./dist/hooks/session-start.js ./dist/hooks/session-end.js ./dist/daemon/server.js",
+    "dev": "tsup src/index.ts src/hooks/pre-commit.ts src/hooks/post-commit.ts src/hooks/prim-hook.ts src/hooks/pre-tool-use.ts src/hooks/post-tool-use.ts src/hooks/session-start.ts src/hooks/session-end.ts src/daemon/server.ts --format esm --watch --clean",
     "clean": "rm -rf dist coverage",
     "lint": "biome check src/",
     "format": "biome check --fix src/",