@primitive.ai/prim 0.1.0-alpha.14 → 0.1.0-alpha.15

package/SKILL.md

@@ -81,6 +81,47 @@ npx --yes @primitive.ai/prim project create -n "<name>" -d "<desc>"
 npx --yes @primitive.ai/prim project create -n "<name>" --spec <contextId>     # value is a context ID
 ```
 
+### Link a spec to a branch (and an optional PR)
+
+A branch-linked spec only auto-syncs from commits on its branch — so per-branch work doesn't mutate specs that aren't relevant. The link is the contract the pre-commit hook checks before every `sync-diff`.
+
+Two ways to bind a spec to a branch:
+
+```
+npx --yes @primitive.ai/prim spec create -s project -n "<name>" --file <path> --branch <branch> --pr <n>   # explicit at creation; --pr is optional
+```
+
+Or implicitly: the pre-commit hook **auto-links an unlinked spec to the current branch** the first time it sees a sync on that branch — no flag needed. The `[synced]` line on that first sync prints ` (auto-linking to <branch>)`; subsequent syncs print ` (linked to <branch> #<pr> <state>)` once the link sticks.
+
+Inspect a spec's bindings via `npx --yes @primitive.ai/prim context get <id>`. The `linkedBranches[]` field lists every `(branch, prNumber, prState, prReviewDecision)` the spec is bound to. The editor UI surfaces the same data as a status pill.
+
+- **`--branch` requires a GitHub origin.** With `--branch`, the CLI reads `repoFullName` from `git remote get-url origin`. If origin isn't GitHub, the link is silently dropped with a warning on stderr — the spec is still created, just unlinked — fix it later from the editor UI.
+- **There is no `prim spec link` subcommand in v1.** To re-link a spec to a different branch, edit it from the spec editor. The CLI only ever auto-links on first sync or accepts `--branch` at creation.
+
+### Trigger PR Intent Review or dispatch drift-fix against a linked PR
+
+```
+npx --yes @primitive.ai/prim spec review <id> --pr <n>             # head SHA defaults to `git rev-parse HEAD`
+npx --yes @primitive.ai/prim spec review <id> --pr <n> --sha <s>   # explicit SHA
+npx --yes @primitive.ai/prim spec drift  <id> --pr <n>             # dispatch the Claude Code drift-fix workflow against the PR
+```
+
+The review bot runs server-side, posts a PR comment with findings, and the outcome surfaces on the **next** pre-commit sync's `[synced]` line as ` (reviewed: <n> finding(s) → <prCommentUrl>)` or ` (review failed)` — don't poll the API yourself.
+
+`spec drift` requires the `primitive-drift-fix.yml` workflow file checked into the repo and the GitHub App's `actions:write` scope granted on the org. The CLI errors out otherwise with a one-liner naming the likely causes.
+
+Neither `spec review` nor `spec drift` accepts `--json` in v1 — they emit a single human-readable line on stdout. Capture it as text or branch on `$?`.
+
+### Inspect a task's auto-completion state
+
+```
+npx --yes @primitive.ai/prim spec status <taskId>
+```
+
+Reports the task's `status`, whether `auto-complete suppressed: yes/no`, and the timestamp + PR # of the most-recent auto-completion activity (with the bot's explanation). Use this after a merge to verify the auto-complete bot acted — or to see *why* it didn't (suppressed via the dashboard, last activity from a different PR, etc.).
+
+`spec status` operates on a **task ID**, not a context/spec ID. Discover task IDs from `prim project create` output or from the editor URL. No `--json` support in v1; output is a fixed `key: value` block on stdout.
+
 ### Install the pre-commit hook
 ```
 npx --yes @primitive.ai/prim hooks install                       # auto-detects Husky and prompts
@@ -106,6 +147,8 @@ What that means:
 - **The hook is not `npx --yes @primitive.ai/prim spec sync`.** `npx --yes @primitive.ai/prim spec sync` re-applies the *existing* spec to the project. The hook calls `sync-diff` -- an LLM updates the spec from the code change, then applies the new spec to the project. The casual "just commit and the hook will sync" is ambiguous; when explaining to the user, specify which operation you mean.
 - **The hook never blocks the commit.** Failures (auth, network, backend) print `[error]` to stderr but exit 0, so a successful `git commit` doesn't prove the spec changed. Check the hook's `[synced]` / `[error]` / `[skip]` output, or verify with `npx --yes @primitive.ai/prim spec get <id>`.
 - **Diffs over 256 KiB are truncated.** The hook logs `(truncated: X KiB -> Y KiB analyzed)`. The LLM only sees the first 256 KiB of the diff.
+- **The hook is branch-aware.** It sends `repoFullName`, `branch`, `sha`, and `prNumber` (the last detected from `gh pr view` when `gh` is on `PATH`, silently null otherwise). The server filters mappings to specs linked to the current branch *or* unlinked (auto-link candidates); specs bound to other branches are silently excluded from the affected list — they don't surface as `[skip]` lines, they just don't appear. If you push an explicit `sync-diff` for an other-branch spec via the API, the hook logs `[skip] <id> — <name> — not linked to <branch>` and continues.
+- **Link state and review results piggyback on the synced line.** `[synced]` lines carry ` (linked to <branch> #<pr> <state>)` or ` (auto-linking to <branch>)`, and once a PR Intent Review completes they grow ` (reviewed: <n> finding(s) → <prCommentUrl>)` or ` (review failed)`. PR `<state>` (`open` / `closed` / `merged`) tracks GitHub webhook deliveries — give it a few seconds to settle after a state change.
 - **To suppress the hook for one commit** (e.g., when intentionally desyncing code from spec, or when committing unrelated changes), use `git commit --no-verify`.
 
 ## Output formats
@@ -116,7 +159,7 @@ Every data-returning command accepts `--json`. With `--json` set, stdout is a si
 - `npx --yes @primitive.ai/prim spec list --json | jq -r '.[]._id'` — list every spec ID
 - `npx --yes @primitive.ai/prim auth status --json | jq -r .authenticated` — boolean; the exit code remains the authoritative signal
 
-Without `--json`, mutating commands (`context create/update/delete/link/unlink`, `spec update/sync/map/unmap/auto-map`, `project create`) emit the bare resource `_id` to **stdout** (one line, no prefix) and human-readable diagnostics to **stderr**. So this also works as a one-liner without `jq`:
+Without `--json`, mutating commands (`context create/update/delete/link/unlink`, `spec create/update/sync/map/unmap/auto-map`, `project create`) emit the bare resource `_id` to **stdout** (one line, no prefix) and human-readable diagnostics to **stderr**. So this also works as a one-liner without `jq`:
 
 - `id=$(npx --yes @primitive.ai/prim context create -s global -n foo --text "x")`
 
@@ -139,6 +182,7 @@ Without `--json`, mutating commands (`context create/update/delete/link/unlink`,
 - **`npx --yes @primitive.ai/prim spec sync` rejects non-spec contexts** with "Context is not a spec document. Use `prim context` instead." Use `npx --yes @primitive.ai/prim spec list` to find spec IDs.
 - **`npx --yes @primitive.ai/prim context delete` is permanent.** Confirm with the user before deleting.
 - **Scope is set at creation.** To change it, delete and recreate the context.
+- **The hook silently excludes specs bound to other branches.** If you don't see a spec you expected to sync, check its `linkedBranches[]` via `npx --yes @primitive.ai/prim context get <id>` — it may be bound to a different branch. To re-bind, use the spec editor (no CLI subcommand in v1).
 
 ## After each task
 

package/dist/{chunk-3APLWTLB.js → chunk-SHLF6OL2.js}

@@ -153,6 +153,34 @@ function getClient() {
   };
 }
 
+// src/utils/git.ts
+import { execSync } from "child_process";
+function safeExec(cmd) {
+  try {
+    return execSync(cmd, { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return null;
+  }
+}
+function parseRepoFullName(remoteUrl) {
+  const match = remoteUrl.match(/(?:github\.com[:/])([^/]+)\/([^/]+?)(?:\.git)?\/?$/);
+  return match ? `${match[1]}/${match[2]}` : null;
+}
+function getGitContext() {
+  const branchRaw = safeExec("git rev-parse --abbrev-ref HEAD");
+  const branch = branchRaw && branchRaw !== "HEAD" ? branchRaw : null;
+  const sha = safeExec("git rev-parse HEAD");
+  const remoteUrl = safeExec("git remote get-url origin");
+  const repoFullName = remoteUrl ? parseRepoFullName(remoteUrl) : null;
+  let prNumber = null;
+  if (safeExec("command -v gh")) {
+    const raw = safeExec("gh pr view --json number -q .number");
+    const n = raw ? Number.parseInt(raw, 10) : Number.NaN;
+    if (Number.isFinite(n)) prNumber = n;
+  }
+  return { branch, sha, repoFullName, prNumber };
+}
+
 export {
   TOKEN_FILE_PATH,
   REFRESH_TOKEN_PATH,
@@ -161,5 +189,6 @@ export {
   getTokenExpiresAt,
   getAuthToken,
   getSiteUrl,
-  getClient
+  getClient,
+  getGitContext
 };

package/dist/hooks/pre-commit.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import {
-  getClient
-} from "../chunk-3APLWTLB.js";
+  getClient,
+  getGitContext
+} from "../chunk-SHLF6OL2.js";
 
 // src/hooks/pre-commit.ts
 import { execSync } from "child_process";
@@ -47,7 +48,8 @@ var HOOK_TIMEOUT_MS = 1e4;
 var defaultDeps = {
   getClient,
   getStagedFiles,
-  getStagedDiff
+  getStagedDiff,
+  getGitContext
 };
 async function syncAffectedSpecs(deps = defaultDeps) {
   const stagedFiles = deps.getStagedFiles();
@@ -55,9 +57,18 @@ async function syncAffectedSpecs(deps = defaultDeps) {
     return [];
   }
   const client = deps.getClient();
+  const gitCtx = deps.getGitContext();
+  let mappingsUrl = "/api/cli/specs/mappings";
+  if (gitCtx.repoFullName && gitCtx.branch) {
+    const params = new URLSearchParams({
+      repoFullName: gitCtx.repoFullName,
+      branch: gitCtx.branch
+    });
+    mappingsUrl = `${mappingsUrl}?${params.toString()}`;
+  }
   let mappings = [];
   try {
-    mappings = await client.get("/api/cli/specs/mappings", {
+    mappings = await client.get(mappingsUrl, {
       signal: AbortSignal.timeout(HOOK_TIMEOUT_MS)
     });
   } catch {
@@ -66,6 +77,7 @@ async function syncAffectedSpecs(deps = defaultDeps) {
   if (mappings.length === 0) {
     return [];
   }
+  const specsById = new Map(mappings.map((s) => [s._id, s]));
   const affectedContexts = findAffectedContexts(stagedFiles, mappings);
   if (affectedContexts.size === 0) {
     return [];
@@ -90,20 +102,51 @@ async function syncAffectedSpecs(deps = defaultDeps) {
         console.log(`  [skip] ${contextId} \u2014 no diff content`);
         continue;
       }
-      const response = await client.post(
-        `/api/cli/contexts/${contextId}/sync-diff`,
-        { diffContent, affectedFiles: affected.matchedFiles },
-        { signal: AbortSignal.timeout(HOOK_TIMEOUT_MS) }
-      );
+      const body = {
+        diffContent,
+        affectedFiles: affected.matchedFiles
+      };
+      if (gitCtx.branch) body.branch = gitCtx.branch;
+      if (gitCtx.sha) body.sha = gitCtx.sha;
+      if (gitCtx.repoFullName) body.repoFullName = gitCtx.repoFullName;
+      if (gitCtx.prNumber !== null) body.prNumber = gitCtx.prNumber;
+      const response = await client.post(`/api/cli/contexts/${contextId}/sync-diff`, body, {
+        signal: AbortSignal.timeout(HOOK_TIMEOUT_MS)
+      });
       const name = ctx.name ?? "(unnamed)";
+      if (!response.analyzing && response.reason === "not_linked") {
+        console.log(
+          `  [skip] ${contextId} \u2014 ${name} \u2014 not linked to ${gitCtx.branch ?? "(no branch)"}`
+        );
+        continue;
+      }
+      const spec = specsById.get(contextId);
+      const link = spec?.linkedBranches?.find((l) => l.branch === gitCtx.branch);
+      let linkSuffix = "";
+      if (link) {
+        const prBits = link.prNumber ? ` #${String(link.prNumber)}${link.prState ? ` ${link.prState}` : ""}` : "";
+        linkSuffix = ` (linked to ${link.branch}${prBits})`;
+      } else if (gitCtx.branch && spec?.linkedBranches?.length === 0) {
+        linkSuffix = ` (auto-linking to ${gitCtx.branch})`;
+      }
+      const review = link?.latestReviewSummary;
+      let reviewSuffix = "";
+      if (review?.status === "completed") {
+        const n = review.findingsCount ?? 0;
+        const urlSuffix = review.prCommentUrl ? ` \u2192 ${review.prCommentUrl.replace(/^https?:\/\//, "")}` : "";
+        reviewSuffix = ` (reviewed: ${String(n)} finding${n === 1 ? "" : "s"}${urlSuffix})`;
+      } else if (review?.status === "failed") {
+        reviewSuffix = " (review failed)";
+      }
+      linkSuffix += reviewSuffix;
       if (response.truncated && response.sizeChars && response.limitChars) {
         const sizeKiB = Math.round(response.sizeChars / 1024);
         const limitKiB = Math.round(response.limitChars / 1024);
         console.log(
-          `  [synced] ${contextId} \u2014 ${name} (truncated: ${String(sizeKiB)} KiB \u2192 ${String(limitKiB)} KiB analyzed)`
+          `  [synced] ${contextId} \u2014 ${name} (truncated: ${String(sizeKiB)} KiB \u2192 ${String(limitKiB)} KiB analyzed)${linkSuffix}`
         );
       } else {
-        console.log(`  [synced] ${contextId} \u2014 ${name}`);
+        console.log(`  [synced] ${contextId} \u2014 ${name}${linkSuffix}`);
       }
       synced.push(contextId);
     } catch (error) {

package/dist/index.js

@@ -5,10 +5,11 @@ import {
   TOKEN_FILE_PATH,
   getAuthToken,
   getClient,
+  getGitContext,
   getSiteUrl,
   getTokenExpiresAt,
   saveTokenExpiry
-} from "./chunk-3APLWTLB.js";
+} from "./chunk-SHLF6OL2.js";
 
 // src/index.ts
 import { readFileSync as readFileSync6 } from "fs";
@@ -759,6 +760,47 @@ ${contexts.length} spec(s)`);
     }
     printSpec(ctx);
   });
+  spec.command("create").description("Create a new spec document").requiredOption("-s, --scope <scope>", "Scope: project, global, external").requiredOption("-n, --name <name>", "Spec name").option("-t, --text <text>", "Spec text content").option("-f, --file <path>", "Read text content from file").option("--project-id <projectId>", "Link to project(s), comma-separated").option("--branch <branch>", "Link spec to this branch on the current repo").option("--pr <prNumber>", "Optional PR number to attach to the link").option("--json", "Output as JSON").action(
+    async (opts) => {
+      const client = getClient();
+      let text = opts.text;
+      if (opts.file) {
+        text = readFileSync5(opts.file, "utf-8");
+      }
+      const taskIds = opts.projectId ? opts.projectId.split(",").map((id) => id.trim()) : void 0;
+      let linkedBranch;
+      if (opts.branch) {
+        const { repoFullName } = getGitContext();
+        if (!repoFullName) {
+          console.warn(
+            "[prim] --branch supplied but origin remote is not GitHub; skipping link."
+          );
+        } else {
+          linkedBranch = { repoFullName, branch: opts.branch };
+          if (opts.pr) {
+            const n = Number.parseInt(opts.pr, 10);
+            if (Number.isFinite(n)) linkedBranch.prNumber = n;
+          }
+        }
+      }
+      const result = await client.post("/api/cli/contexts", {
+        scope: opts.scope === "project" ? "task" : opts.scope,
+        name: opts.name,
+        text,
+        taskIds,
+        isSpecDocument: true,
+        linkedBranch
+      });
+      if (opts.json) {
+        printJson({ _id: result._id });
+        return;
+      }
+      console.error(
+        `Created spec: ${result._id}${linkedBranch ? ` (linked to ${linkedBranch.branch})` : ""}`
+      );
+      console.log(result._id);
+    }
+  );
   spec.command("update <contextId>").description("Update a spec document's text content").option("-t, --text <text>", "New text content").option("-f, --file <path>", "Read text content from file").option("-n, --name <name>", "New name").option("--json", "Output as JSON").action(
     async (contextId, opts) => {
       const client = getClient();
@@ -806,6 +848,65 @@ ${contexts.length} spec(s)`);
     }
     console.log(contextId);
   });
+  spec.command("review <contextId>").description("Manually trigger the PR Intent Review bot for a spec").requiredOption("--pr <prNumber>", "PR number to review against").option("--sha <headSha>", "Commit SHA the review runs against (defaults to current HEAD)").action(async (contextId, opts) => {
+    const prNumber = Number.parseInt(opts.pr, 10);
+    if (!Number.isFinite(prNumber)) {
+      console.error("--pr must be an integer.");
+      process.exit(1);
+    }
+    const headSha = opts.sha ?? getGitContext().sha;
+    if (!headSha) {
+      console.error("Could not determine head SHA \u2014 pass --sha or run inside a git checkout.");
+      process.exit(1);
+    }
+    const client = getClient();
+    await client.post(`/api/cli/contexts/${contextId}/review`, {
+      prNumber,
+      headSha
+    });
+    console.log(
+      `Scheduled review: ${contextId} against PR #${String(prNumber)} @ ${headSha.slice(0, 7)}`
+    );
+  });
+  spec.command("drift <contextId>").description("Dispatch the Claude Code drift-fix workflow against a PR").requiredOption("--pr <prNumber>", "PR number to dispatch the drift-fix workflow against").action(async (contextId, opts) => {
+    const prNumber = Number.parseInt(opts.pr, 10);
+    if (!Number.isFinite(prNumber)) {
+      console.error("--pr must be an integer.");
+      process.exit(1);
+    }
+    const client = getClient();
+    const result = await client.post(`/api/cli/contexts/${contextId}/drift`, {
+      prNumber
+    });
+    if (result.dispatched) {
+      const ref = result.runUrl ? `: ${result.runUrl}` : "";
+      console.log(`Dispatched drift-fix workflow${ref}`);
+    } else {
+      console.error(
+        "Drift-fix dispatch failed. Likely causes: actions:write App scope not granted, primitive-drift-fix.yml workflow file missing, or no findings on the latest review."
+      );
+      process.exit(1);
+    }
+  });
+  spec.command("status <taskId>").description(
+    "Show task status, auto-complete suppression flag, and the most-recent bot auto-completion"
+  ).action(async (taskId) => {
+    const client = getClient();
+    const result = await client.get(`/api/cli/tasks/${taskId}/status`);
+    console.log(`status: ${result.status}`);
+    console.log(`auto-complete suppressed: ${result.autoCompleteSuppressed ? "yes" : "no"}`);
+    const last = result.lastAutoCompleteActivity;
+    if (last) {
+      const when = last.createdAt ? new Date(last.createdAt).toISOString() : "\u2014";
+      const pr = last.prNumber ? `#${String(last.prNumber)}` : "\u2014";
+      console.log(`last auto-complete: ${when} (PR ${pr})`);
+      if (last.explanation) {
+        console.log(`  ${last.explanation}`);
+      }
+    } else {
+      console.log("last auto-complete: \u2014");
+    }
+  });
   spec.command("map <contextId>").description("Map file patterns to a spec (used by pre-commit hook to detect affected specs)").requiredOption(
     "-p, --pattern <patterns...>",
     'Glob pattern(s) to associate, e.g. "src/auth/**"'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitive.ai/prim",
-  "version": "0.1.0-alpha.14",
+  "version": "0.1.0-alpha.15",
   "description": "CLI for managing Primitive specs, contexts, and git hooks",
   "type": "module",
   "license": "MIT",