@primitive.ai/prim 0.1.0-alpha.59 → 0.1.0-alpha.61

package/SKILL.md

@@ -80,13 +80,13 @@ Confirmations are author-targeted and rare by design; answering keeps the graph'
 
 Capture is automatic for low-level choices made while coding in an active repo. Use the deliberate CLI path for higher-order decisions that emerge in conversation: goals, priorities, principles, invariants, constraints, defaults, commitments, durable tradeoffs, and exceptions.
 
-A decision worth deliberately recording is a genuine **fork in the road**: the user or agent encountered multiple plausible paths, selected one, and that selection should inform future work. The litmus: does the selection govern future work, or did it merely happen once? A release-scoped choice — what is in or out of one release — reverses at the next release; it is ephemeral, not a decision. Record the chosen behavior, direction, constraint, or tradeoff—not routine implementation needed to finish the task or follow an existing convention. Small design choices made in-flight while implementing—such as edge-case handling, parameter defaults, retry or timeout values, log levels, naming, or the shape of an internal data structure—are implementation details even when you chose between alternatives: never deliberately record them or spend a rationale question on them; passive capture already covers coding activity. A teammate working elsewhere should benefit from knowing it — and that test is a gate, not a nicety. The graph is the team's shared memory: a decision that configures only your own working environment — editor, shell, or terminal tooling, a personal dev box or remote coding machine, which worktree manager, launcher, or TUI you run — is personal, not a team decision, however durable and well-reasoned, even when the setup touches repo-owned helper scripts. Never record a personal-environment decision on your own initiative; record only positions the team's shared work must preserve. An explicit request to record that specific decision still wins — note when honoring it that the record is visible to the whole team.
+A decision worth deliberately recording is a genuine **fork in the road**: the user or agent encountered multiple plausible paths, selected one, and that selection should inform future work. The litmus: does the selection govern future work, or did it merely happen once? A second litmus: was the rejected path one the product could actually have shipped — a defensible alternative a teammate could have argued for — rather than an obviously-wrong option the quality bar already excludes (leaving a surface broken or empty)? “Of course we did this” marks a forced choice, not a fork. A release-scoped choice — what is in or out of one release — reverses at the next release; it is ephemeral, not a decision. Record the chosen behavior, direction, constraint, or tradeoff—not routine implementation needed to finish the task or follow an existing convention. Small design choices made in-flight while implementing—such as edge-case handling, parameter defaults, retry or timeout values, log levels, naming, or the shape of an internal data structure—are implementation details even when you chose between alternatives: never deliberately record them or spend a rationale question on them; passive capture already covers coding activity. A teammate working elsewhere should benefit from knowing it — and that test is a gate, not a nicety. The graph is the team's shared memory: a decision that configures only your own working environment — editor, shell, or terminal tooling, a personal dev box or remote coding machine, which worktree manager, launcher, or TUI you run — is personal, not a team decision, however durable and well-reasoned, even when the setup touches repo-owned helper scripts. Never record a personal-environment decision on your own initiative; record only positions the team's shared work must preserve. An explicit request to record that specific decision still wins — note when honoring it that the record is visible to the whole team.
 
 ### Ground the rationale in real sources
 
 Before deliberately recording a decision, actively gather the real context behind **why this path was chosen** — aim to populate the decision with as much genuine, source-grounded rationale as you can find, never a plausible-sounding guess. Start with the current conversation — it is itself a primary source: when the why was stated or is visible in this session, capture it in `--rationale` at create time rather than omitting it. Then reach for every tool, connector, and MCP server available to you to pull from the actual sources the decision or task points to: Slack threads, Granola or other meeting notes, Linear issues, Zoom transcripts, email, and repository docs or skills. Don't limit yourself to that list — use whatever integrations you have. Read the source directly instead of inferring from memory, and target the specific thread, meeting, ticket, or document the user referenced rather than a broad, scattershot search.
 
-Record only rationale supported by those sources. Do not mistake the implementation method, the task request, or a restatement of the decision for its rationale. Write it as plain, impersonal engineering explanation — the reasons, evidence, and tradeoffs behind the choice, in a sentence or three. Rationale is explanatory, never normative: a constraint future work must obey belongs in `--decided` even when the rationale explains why, and reasoning belongs in `--rationale`, never inlined into the intent while `--rationale` sits empty. `--rationale` is not optional: never invent one, but never silently drop it either — when the why cannot be deduced from all available context, ask the user for it with the one focused question below and record their answer.
+Record only rationale supported by those sources. Do not mistake the implementation method, the task request, or a restatement of the decision for its rationale. Echoing the spec, PRD, or Linear ticket — the “what” — is not rationale either; the capture-worthy part is the approach reasoning: why this shape and why each recorded alternative loses. When you record an option in `--alternatives`, the rationale should say why it was rejected. Write it as plain, impersonal engineering explanation — the reasons, evidence, and tradeoffs behind the choice, in a sentence or three. Rationale is explanatory, never normative: a constraint future work must obey belongs in `--decided` even when the rationale explains why, and reasoning belongs in `--rationale`, never inlined into the intent while `--rationale` sits empty. `--rationale` is not optional: never invent one, but never silently drop it either — when the why cannot be deduced from all available context, ask the user for it with the one focused question below and record their answer.
 
 For proactively identified decisions in an active repo, let confidence in the rationale determine the interaction:
 

package/dist/{chunk-QY75BQMF.js → chunk-JQFN6LBO.js}

@@ -64,6 +64,13 @@ function stripControlChars(text) {
   }
   return out;
 }
+var MAX_HEALTH_ERROR_LENGTH = 240;
+function boundedHealthError(value) {
+  if (!value) return void 0;
+  const clean = stripControlChars(value).replace(/\s+/g, " ").trim();
+  if (!clean) return void 0;
+  return clean.length <= MAX_HEALTH_ERROR_LENGTH ? clean : `${clean.slice(0, MAX_HEALTH_ERROR_LENGTH - 1)}\u2026`;
+}
 function stripAnsi(text) {
   return text.replace(/\u001b\[[0-9;]*m/g, "");
 }
@@ -97,6 +104,7 @@ export {
   bold,
   colorForArea,
   stripControlChars,
+  boundedHealthError,
   stripAnsi,
   requireDurableIngestAcknowledgement
 };

package/dist/{chunk-UBEBEBLM.js → chunk-N4R7EXZT.js}

@@ -1,7 +1,10 @@
 import {
-  gitToplevel
+  gitToplevel,
+  githubRepositoryFullName,
+  setRepoSyncId
 } from "./chunk-LDQZASIF.js";
 import {
+  getClient,
   withFileLock
 } from "./chunk-I3HIPAIR.js";
 
@@ -53,6 +56,45 @@ import { homedir } from "os";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "path";
 import { fileURLToPath } from "url";
 import { parse as parseYaml } from "yaml";
+
+// src/lib/semver.ts
+function parseSemver(value) {
+  if (typeof value !== "string" || value.length > 256) return;
+  const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/u.exec(
+    value
+  );
+  if (!match) return;
+  const prerelease = match[4]?.split(".") ?? [];
+  if (prerelease.some((part) => /^\d+$/u.test(part) && part.length > 1 && part.startsWith("0"))) {
+    return;
+  }
+  return { core: [BigInt(match[1]), BigInt(match[2]), BigInt(match[3])], prerelease };
+}
+function compareSemver(left, right) {
+  const a = parseSemver(left);
+  const b = parseSemver(right);
+  if (!a || !b) return;
+  for (let i = 0; i < a.core.length; i += 1) {
+    if (a.core[i] !== b.core[i]) return a.core[i] < b.core[i] ? -1 : 1;
+  }
+  if (a.prerelease.length === 0 || b.prerelease.length === 0) {
+    return a.prerelease.length === b.prerelease.length ? 0 : a.prerelease.length === 0 ? 1 : -1;
+  }
+  for (let i = 0; i < Math.max(a.prerelease.length, b.prerelease.length); i += 1) {
+    const x = a.prerelease[i];
+    const y = b.prerelease[i];
+    if (x === void 0 || y === void 0) return x === void 0 ? -1 : 1;
+    if (x === y) continue;
+    const xNumeric = /^\d+$/u.test(x);
+    const yNumeric = /^\d+$/u.test(y);
+    if (xNumeric && yNumeric) return BigInt(x) < BigInt(y) ? -1 : 1;
+    if (xNumeric !== yNumeric) return xNumeric ? -1 : 1;
+    return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+// src/commands/claude-plugin.ts
 var __dirname = dirname(fileURLToPath(import.meta.url));
 var PLUGIN_DESCRIPTION = "Primitive decision-graph guidance for the prim CLI \u2014 a model-invoked skill installed by prim skill install.";
 var MAX_MANIFEST_BYTES = 64 * 1024;
@@ -97,42 +139,6 @@ function pluginPaths(dir) {
     skillPath: join(dir, "SKILL.md")
   };
 }
-function parseSemver(value) {
-  if (typeof value !== "string" || value.length > 256) return;
-  const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/u.exec(
-    value
-  );
-  if (!match) return;
-  const prerelease = match[4]?.split(".") ?? [];
-  if (prerelease.some((part) => /^\d+$/u.test(part) && part.length > 1 && part.startsWith("0"))) {
-    return;
-  }
-  return { core: [BigInt(match[1]), BigInt(match[2]), BigInt(match[3])], prerelease };
-}
-function compareSemver(left, right) {
-  const a = parseSemver(left);
-  const b = parseSemver(right);
-  if (!a || !b) return;
-  for (let i = 0; i < a.core.length; i += 1) {
-    if (a.core[i] !== b.core[i]) return a.core[i] < b.core[i] ? -1 : 1;
-  }
-  if (a.prerelease.length === 0 || b.prerelease.length === 0) {
-    return a.prerelease.length === b.prerelease.length ? 0 : a.prerelease.length === 0 ? 1 : -1;
-  }
-  const length = Math.max(a.prerelease.length, b.prerelease.length);
-  for (let i = 0; i < length; i += 1) {
-    const x = a.prerelease[i];
-    const y = b.prerelease[i];
-    if (x === void 0 || y === void 0) return x === void 0 ? -1 : 1;
-    if (x === y) continue;
-    const xNumeric = /^\d+$/u.test(x);
-    const yNumeric = /^\d+$/u.test(y);
-    if (xNumeric && yNumeric) return BigInt(x) < BigInt(y) ? -1 : 1;
-    if (xNumeric !== yNumeric) return xNumeric ? -1 : 1;
-    return x < y ? -1 : 1;
-  }
-  return 0;
-}
 function pathIsInside(root, path) {
   const rel = relative(root, path);
   return rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
@@ -586,8 +592,28 @@ function registerSkillCommands(program) {
   });
 }
 
+// src/lib/repository-binding.ts
+async function bindRepository(root, options) {
+  const repositoryFullName = githubRepositoryFullName(root);
+  if (!repositoryFullName) {
+    throw new Error("origin must be a GitHub HTTPS/SSH remote in owner/name form");
+  }
+  const response = await getClient().post(
+    "/api/cli/repositories/bind",
+    { repositoryFullName },
+    options
+  );
+  if (typeof response.repoSyncId !== "string" || response.repoSyncId.length === 0) {
+    throw new Error("server returned no repository binding");
+  }
+  setRepoSyncId(root, response.repoSyncId);
+  return { repoSyncId: response.repoSyncId, repositoryFullName };
+}
+
 export {
+  bindRepository,
   printJson,
+  compareSemver,
   refreshClaudePlugins,
   hasUsableCodexGuidance,
   registerSkillCommands

package/dist/daemon/server.js

@@ -1517,6 +1517,7 @@ function handleStatusSnapshot(params) {
     sessionId: activeSessionId,
     lastHeartbeatAt,
     version: runtimeVersion,
+    launchRevision: process.env.PRIM_LAUNCH_REVISION,
     healthy: daemonHealth.healthy,
     needsReauth: daemonHealth.needsReauth === true,
     heartbeat: { ...daemonHealth.heartbeat },

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

@@ -3,7 +3,7 @@ import {
   bold,
   color,
   requireDurableIngestAcknowledgement
-} from "../chunk-QY75BQMF.js";
+} from "../chunk-JQFN6LBO.js";
 import {
   resolvePreflightTargets
 } from "../chunk-B4SHJYIN.js";

package/dist/hooks/session-start.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 import {
+  bindRepository,
   hasUsableCodexGuidance,
   refreshClaudePlugins
-} from "../chunk-UBEBEBLM.js";
+} from "../chunk-N4R7EXZT.js";
 import {
   buildHookOutput,
   handoffHookOutput
@@ -22,7 +23,8 @@ import {
 } from "../chunk-YIMUIPMD.js";
 import {
   gitToplevel,
-  isRepoActiveForCapture
+  isRepoActiveForCapture,
+  repoSyncId
 } from "../chunk-LDQZASIF.js";
 import {
   getSiteUrl,
@@ -66,6 +68,7 @@ function reauthNoticeFields(agent) {
 
 // src/hooks/session-start-core.ts
 var DAEMON_TIMEOUT_MS = 250;
+var REPOSITORY_BIND_TIMEOUT_MS = 1e3;
 var PRIM_TRIGGER = "When this task chooses between plausible approaches or establishes or changes a lasting goal, priority, constraint, invariant, default, commitment, tradeoff, exception, or shared instruction";
 var PRIM_EXCLUSIONS = "Never invoke `prim` for routine implementation that merely follows an existing decision made before this task or for temporary tactics; they never qualify, including for evaluation.";
 function primReminder(action, rationaleAction) {
@@ -74,7 +77,25 @@ function primReminder(action, rationaleAction) {
 var PRIM_SKILL_REMINDER = primReminder("invoke the `prim` skill", "invoke the skill");
 var CODEX_PRIM_ACTION = "follow the installed Prim workflow and use the `prim` CLI";
 var CODEX_PRIM_REMINDER = primReminder(CODEX_PRIM_ACTION, CODEX_PRIM_ACTION);
-async function processSessionStart(raw, agent, feedbackSignal = AbortSignal.timeout(FEEDBACK_DEADLINE_MS)) {
+async function activeProjectRoot(cwd) {
+  try {
+    const root = gitToplevel(cwd);
+    if (!root || !isRepoActiveForCapture(cwd)) return null;
+    if (!repoSyncId(root)) {
+      try {
+        await bindRepository(root, {
+          signal: AbortSignal.timeout(REPOSITORY_BIND_TIMEOUT_MS),
+          quietRefresh: true
+        });
+      } catch {
+      }
+    }
+    return root;
+  } catch {
+    return null;
+  }
+}
+async function processSessionStart(raw, agent, feedbackSignal) {
   let envelope;
   try {
     const parsed = JSON.parse(raw);
@@ -98,12 +119,13 @@ async function processSessionStart(raw, agent, feedbackSignal = AbortSignal.time
     { timeoutMs: DAEMON_TIMEOUT_MS }
   );
   const cwd = envelope.cwd ?? process.cwd();
+  let projectRoot = null;
   let active = false;
   let skillState = { installed: 0, refreshed: 0 };
   if (agent === "claude_code") {
+    projectRoot = await activeProjectRoot(cwd);
+    active = projectRoot !== null;
     try {
-      const projectRoot = gitToplevel(cwd);
-      active = projectRoot !== null && isRepoActiveForCapture(cwd);
       skillState = await refreshClaudePlugins(
         cwd,
         active && projectRoot !== null ? { includeProject: true, projectRoot } : { includeProject: false }
@@ -128,10 +150,11 @@ async function processSessionStart(raw, agent, feedbackSignal = AbortSignal.time
       { timeoutMs: DAEMON_TIMEOUT_MS }
     );
     const presence = snapshot && !snapshot.presenceStale && typeof snapshot.onlineCount === "number" ? `[prim] team: ${snapshot.onlineCount} online` : void 0;
+    projectRoot = await activeProjectRoot(cwd);
+    active = projectRoot !== null;
     let proactive = false;
     try {
-      const projectRoot = gitToplevel(cwd);
-      proactive = projectRoot !== null && isRepoActiveForCapture(cwd) && hasUsableCodexGuidance(projectRoot);
+      proactive = projectRoot !== null && active && hasUsableCodexGuidance(projectRoot);
     } catch {
     }
     const additionalContext = [proactive ? CODEX_PRIM_REMINDER : void 0, presence].filter((value) => value !== void 0).join("\n\n");
@@ -143,10 +166,11 @@ async function processSessionStart(raw, agent, feedbackSignal = AbortSignal.time
     if (active) {
       const identity = getOrCreateWorkspaceId(cwd);
       if (identity.status === "ready") {
+        const signal = feedbackSignal ?? AbortSignal.timeout(FEEDBACK_DEADLINE_MS);
         const lease = await leaseDecisionFeedback({
           workspaceId: identity.workspaceId,
           currentSessionId: envelope.session_id,
-          signal: feedbackSignal
+          signal
         });
         const rendered = lease ? renderFeedback(lease) : void 0;
         return {
@@ -159,7 +183,7 @@ async function processSessionStart(raw, agent, feedbackSignal = AbortSignal.time
             await acknowledgeDecisionFeedback({
               workspaceId: identity.workspaceId,
               deliveries: rendered.deliveries,
-              signal: feedbackSignal
+              signal
             });
           } : void 0
         };
@@ -167,6 +191,7 @@ async function processSessionStart(raw, agent, feedbackSignal = AbortSignal.time
     }
     return { output: buildHookOutput({ additionalContext, reloadSkills }) };
   }
+  await activeProjectRoot(cwd);
   return { output: buildHookOutput({}) };
 }
 
@@ -195,7 +220,6 @@ function readStdin() {
   });
 }
 async function main() {
-  const feedbackSignal = AbortSignal.timeout(FEEDBACK_DEADLINE_MS);
   warmBinCache();
   const agent = parseAgent(process.argv);
   let raw;
@@ -205,7 +229,7 @@ async function main() {
     await emitOutput(buildHookOutput({}));
     return;
   }
-  const result = await processSessionStart(raw, agent, feedbackSignal);
+  const result = await processSessionStart(raw, agent);
   await emitOutput(result.output, result.acknowledge);
 }
 void main().catch(async () => {