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

package/SKILL.md

@@ -81,11 +81,56 @@ 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
+npx --yes @primitive.ai/prim hooks install                       # auto-detects Husky and prompts
+npx --yes @primitive.ai/prim hooks install --yes                 # confirm Husky (non-interactive)
+npx --yes @primitive.ai/prim hooks install --target=git-hooks    # force .git/hooks (skip Husky detection)
 npx --yes @primitive.ai/prim hooks uninstall
 ```
+Under `CI=1` (or with `--non-interactive`), `hooks install` fails fast in a Husky repo unless `--yes` or `--target` is set. The error message names both escapes.
+
 **Note:** `hooks uninstall` only removes `.git/hooks/pre-commit`. If the hook was installed into `.husky/pre-commit`, you must remove the prim block from that file manually.
 
 ## How the pre-commit hook behaves
@@ -102,21 +147,32 @@ 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
 
-| Command | Output | Where the ID is |
+Every data-returning command accepts `--json`. With `--json` set, stdout is a single JSON document — pipe to `jq` instead of parsing text:
+
+- `id=$(npx --yes @primitive.ai/prim context create -s global -n foo --text "x" --json | jq -r ._id)` — capture an ID
+- `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 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")`
+
+| Command | Without `--json` | With `--json` |
 |---|---|---|
-| `npx --yes @primitive.ai/prim context create` | `Created context: <id>` | Match `^Created context: (\S+)` |
-| `npx --yes @primitive.ai/prim project create` | `Created project: <id>` | Match `^Created project: (\S+)` |
-| `npx --yes @primitive.ai/prim spec update` | `Updated spec: <id>` | Match `^Updated spec: (\S+)` |
-| `npx --yes @primitive.ai/prim spec sync` | `Triggered sync for spec: <id>` | Match `^Triggered sync for spec: (\S+)` |
-| `npx --yes @primitive.ai/prim context list`, `npx --yes @primitive.ai/prim spec list` | Table with trailing count line | First token of each row (skip the final `N spec(s)` / `N context(s)` summary line) |
-| `npx --yes @primitive.ai/prim spec list --project-id <pid>` | Single-spec block (key:value) | `ID:` line |
-| `npx --yes @primitive.ai/prim context get <id>` | Pretty-printed JSON | `._id` field |
-| `npx --yes @primitive.ai/prim spec get <id>` | Human-readable key:value block | `ID:` line |
-| `npx --yes @primitive.ai/prim spec get <id> --text-only` | Raw spec markdown, nothing else | n/a |
+| Mutators above | stdout: bare `_id`; stderr: `Created/Updated/...` prefix (plus secondary lines: `Root project:`, `Linked spec:`, pattern lists) | stdout: `{ "_id": "<id>", … }` with extras where applicable (`spec sync` adds `specRootTaskId`; `context link/unlink` add `project`; `project create --spec` adds `spec`; `spec map/unmap` add `filePatterns`) |
+| `context list`, `spec list` (non-empty) | stdout: rows (first token = `_id`); stderr: `N context(s)` / `N spec(s)` summary | stdout: JSON array |
+| `context list`, `spec list` (empty) | stdout: (empty); stderr: `No contexts found.` / `No spec documents found.` | stdout: `[]` |
+| `spec list --project-id <pid>` | stdout: key:value block (or stdout empty + stderr `No spec document found for this project.` if none) | stdout: single object or `null` |
+| `context get <id>` | stdout: pretty-printed JSON (always JSON; `--json` accepted for symmetry) | stdout: pretty-printed JSON |
+| `spec get <id>` | stdout: human-readable key:value block (`ID:` line first) | stdout: JSON object |
+| `spec get <id> --text-only` | stdout: raw spec markdown, nothing else | stdout: JSON object (`--json` wins over `--text-only`) |
+| `auth status` | stdout: human readout; **exit code is the authoritative signal** (0 = authed) | stdout: JSON; exit code unchanged |
 
 ## Pitfalls
 
@@ -126,6 +182,7 @@ What that means:
 - **`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";
@@ -24,6 +25,13 @@ import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
 import { createServer } from "http";
 import { platform } from "os";
 import { dirname } from "path";
+
+// src/output.ts
+function printJson(data) {
+  console.log(JSON.stringify(data, null, 2));
+}
+
+// src/commands/auth.ts
 var FILE_MODE = 384;
 var LOCALHOST = "127.0.0.1";
 var CALLBACK_PORT = 19876;
@@ -174,8 +182,22 @@ ${authUrl.toString()}
       console.log("No saved tokens found.");
     }
   });
-  auth.command("status").description("Check authentication status and token expiry").action(() => {
+  auth.command("status").description("Check authentication status and token expiry").option("--json", "Output as JSON").action((opts) => {
     const token = getAuthToken();
+    if (opts.json) {
+      const expiresAt2 = getTokenExpiresAt();
+      const expiresInMs = expiresAt2 ? expiresAt2 - Date.now() : null;
+      const refreshPresent = existsSync(REFRESH_TOKEN_PATH);
+      printJson({
+        authenticated: !!token,
+        tokenFile: token ? TOKEN_FILE_PATH : null,
+        accessTokenExpiresInMs: expiresInMs,
+        accessTokenExpired: expiresInMs !== null && expiresInMs <= 0,
+        refreshTokenPresent: refreshPresent,
+        warnings: !token || refreshPresent ? [] : ["no refresh token"]
+      });
+      process.exit(token ? 0 : 1);
+    }
     if (!token) {
       console.log("Not authenticated. Run `prim auth login` to authenticate.");
       process.exit(1);
@@ -238,7 +260,7 @@ async function exchangeCode(siteUrl, code, codeVerifier, redirectUri) {
 import { readFileSync as readFileSync2 } from "fs";
 function registerContextCommands(program2) {
   const context = program2.command("context").description("Manage contexts");
-  context.command("list").description("List contexts").option("-s, --scope <scope>", "Filter by scope: project, global, external").option("-t, --project-id <projectId>", "List contexts linked to a specific project").action(async (opts) => {
+  context.command("list").description("List contexts").option("-s, --scope <scope>", "Filter by scope: project, global, external").option("-t, --project-id <projectId>", "List contexts linked to a specific project").option("--json", "Output as JSON").action(async (opts) => {
     const client = getClient();
     const params = new URLSearchParams();
     if (opts.projectId) {
@@ -248,14 +270,18 @@ function registerContextCommands(program2) {
       params.set("scope", opts.scope === "project" ? "task" : opts.scope);
     }
     const contexts = await client.get(`/api/cli/contexts?${params.toString()}`);
+    if (opts.json) {
+      printJson(contexts);
+      return;
+    }
     printContextList(contexts);
   });
-  context.command("get <contextId>").description("Get a context by ID").action(async (contextId) => {
+  context.command("get <contextId>").description("Get a context by ID").option("--json", "Output as JSON (default behavior; accepted for symmetry)").action(async (contextId) => {
     const client = getClient();
     const ctx = await client.get(`/api/cli/contexts/${contextId}`);
-    console.log(JSON.stringify(ctx, null, 2));
+    printJson(ctx);
   });
-  context.command("create").description("Create a new context").requiredOption("-s, --scope <scope>", "Scope: project, global, external").requiredOption("-n, --name <name>", "Context name").option("-t, --text <text>", "Context text content").option("-f, --file <path>", "Read text content from file").option("--project-id <projectId>", "Link to project(s), comma-separated").option("--spec", "Mark as a spec document").action(
+  context.command("create").description("Create a new context").requiredOption("-s, --scope <scope>", "Scope: project, global, external").requiredOption("-n, --name <name>", "Context name").option("-t, --text <text>", "Context text content").option("-f, --file <path>", "Read text content from file").option("--project-id <projectId>", "Link to project(s), comma-separated").option("--spec", "Mark as a spec document").option("--json", "Output as JSON").action(
     async (opts) => {
       const client = getClient();
       let text = opts.text;
@@ -270,44 +296,71 @@ function registerContextCommands(program2) {
         taskIds,
         isSpecDocument: opts.spec ?? false
       });
-      console.log(`Created context: ${result._id}`);
+      if (opts.json) {
+        printJson({ _id: result._id });
+        return;
+      }
+      console.error(`Created context: ${result._id}`);
+      console.log(result._id);
     }
   );
-  context.command("update <contextId>").description("Update a context").option("-n, --name <name>", "New name").option("-t, --text <text>", "New text content").option("-f, --file <path>", "Read text content from file").action(async (contextId, opts) => {
-    const client = getClient();
-    let text = opts.text;
-    if (opts.file) {
-      text = readFileSync2(opts.file, "utf-8");
+  context.command("update <contextId>").description("Update a context").option("-n, --name <name>", "New name").option("-t, --text <text>", "New text content").option("-f, --file <path>", "Read text content from file").option("--json", "Output as JSON").action(
+    async (contextId, opts) => {
+      const client = getClient();
+      let text = opts.text;
+      if (opts.file) {
+        text = readFileSync2(opts.file, "utf-8");
+      }
+      await client.patch(`/api/cli/contexts/${contextId}`, {
+        name: opts.name,
+        text
+      });
+      if (opts.json) {
+        printJson({ _id: contextId });
+        return;
+      }
+      console.error(`Updated context: ${contextId}`);
+      console.log(contextId);
     }
-    await client.patch(`/api/cli/contexts/${contextId}`, {
-      name: opts.name,
-      text
-    });
-    console.log(`Updated context: ${contextId}`);
-  });
-  context.command("delete <contextId>").description("Delete a context").action(async (contextId) => {
+  );
+  context.command("delete <contextId>").description("Delete a context").option("--json", "Output as JSON").action(async (contextId, opts) => {
     const client = getClient();
     await client.delete(`/api/cli/contexts/${contextId}`);
-    console.log(`Deleted context: ${contextId}`);
+    if (opts.json) {
+      printJson({ _id: contextId });
+      return;
+    }
+    console.error(`Deleted context: ${contextId}`);
+    console.log(contextId);
   });
-  context.command("link <contextId>").description("Link a context to a project").requiredOption("--project <projectId>", "Project ID to link to").action(async (contextId, opts) => {
+  context.command("link <contextId>").description("Link a context to a project").requiredOption("--project <projectId>", "Project ID to link to").option("--json", "Output as JSON").action(async (contextId, opts) => {
     const client = getClient();
     await client.post(`/api/cli/contexts/${contextId}/link`, {
       taskId: opts.project
     });
-    console.log(`Linked context ${contextId} to project ${opts.project}`);
+    if (opts.json) {
+      printJson({ _id: contextId, project: opts.project });
+      return;
+    }
+    console.error(`Linked context ${contextId} to project ${opts.project}`);
+    console.log(contextId);
   });
-  context.command("unlink <contextId>").description("Unlink a context from a project").requiredOption("--project <projectId>", "Project ID to unlink from").action(async (contextId, opts) => {
+  context.command("unlink <contextId>").description("Unlink a context from a project").requiredOption("--project <projectId>", "Project ID to unlink from").option("--json", "Output as JSON").action(async (contextId, opts) => {
     const client = getClient();
     await client.post(`/api/cli/contexts/${contextId}/unlink`, {
       taskId: opts.project
     });
-    console.log(`Unlinked context ${contextId} from project ${opts.project}`);
+    if (opts.json) {
+      printJson({ _id: contextId, project: opts.project });
+      return;
+    }
+    console.error(`Unlinked context ${contextId} from project ${opts.project}`);
+    console.log(contextId);
   });
 }
 function printContextList(contexts) {
   if (contexts.length === 0) {
-    console.log("No contexts found.");
+    console.error("No contexts found.");
     return;
   }
   for (const ctx of contexts) {
@@ -316,7 +369,7 @@ function printContextList(contexts) {
     const name = ctx.name ?? ctx.title ?? "(unnamed)";
     console.log(`${ctx._id}  ${scope.padEnd(8)} ${name}${spec}`);
   }
-  console.log(`
+  console.error(`
 ${contexts.length} context(s)`);
 }
 
@@ -324,6 +377,7 @@ ${contexts.length} context(s)`);
 import { execSync } from "child_process";
 import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync3, unlinkSync, writeFileSync as writeFileSync2 } 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
@@ -431,17 +485,37 @@ function installToDotGit(gitRoot) {
 }
 function registerHooksCommands(program2) {
   const hooks = program2.command("hooks").description("Manage git hooks");
-  hooks.command("install").description("Install the prim pre-commit hook").action(async () => {
+  hooks.command("install").description("Install the prim pre-commit hook (auto-detects Husky; use --target to override)").addOption(
+    new Option("--target <where>", "install destination; bypasses Husky detection").choices([
+      "husky",
+      "git-hooks"
+    ])
+  ).action(async (opts, command) => {
+    const globals = command.optsWithGlobals();
+    const nonInteractive = Boolean(
+      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 (detectHusky(gitRoot)) {
-      const confirmed = await askConfirmation(
+      if (globals.yes) return installToHusky(gitRoot);
+      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."
+        );
+      }
+      if (!process.stdin.isTTY) {
+        console.error(
+          "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?"
-      );
-      if (confirmed) {
-        installToHusky(gitRoot);
-        return;
+      )) {
+        return installToHusky(gitRoot);
+      } else {
+        console.log("Falling back to .git/hooks/pre-commit install.");
       }
-      console.log("Falling back to .git/hooks/pre-commit install.");
     }
     installToDotGit(gitRoot);
   });
@@ -460,17 +534,22 @@ function registerHooksCommands(program2) {
 // src/commands/project.ts
 function registerProjectCommands(program2) {
   const project = program2.command("project").description("Manage projects");
-  project.command("create").description("Create a new project").requiredOption("-n, --name <name>", "Project name").option("-d, --description <description>", "Project description").option("--spec <contextId>", "Link an existing spec as this project's spec").action(async (opts) => {
+  project.command("create").description("Create a new project").requiredOption("-n, --name <name>", "Project name").option("-d, --description <description>", "Project description").option("--spec <contextId>", "Link an existing spec as this project's spec").option("--json", "Output as JSON").action(async (opts) => {
     const client = getClient();
     const result = await client.post("/api/cli/tasks", {
       name: opts.name,
       description: opts.description,
       specContextId: opts.spec
     });
-    console.log(`Created project: ${result._id}`);
+    if (opts.json) {
+      printJson(opts.spec ? { _id: result._id, spec: opts.spec } : { _id: result._id });
+      return;
+    }
+    console.error(`Created project: ${result._id}`);
     if (opts.spec) {
-      console.log(`Linked spec: ${opts.spec}`);
+      console.error(`Linked spec: ${opts.spec}`);
     }
+    console.log(result._id);
   });
 }
 
@@ -592,12 +671,21 @@ function runUninstall(cwd, opts) {
 function runStatus(cwd, opts) {
   const target = resolveTarget(cwd, opts.target);
   if (target === null) return 1;
-  if (!existsSync3(target)) {
+  const fileExists = existsSync3(target);
+  let installed = false;
+  if (fileExists) {
+    const content = readFileSync4(target, "utf-8");
+    installed = content.includes(SKILL_BEGIN) && content.includes(SKILL_END);
+  }
+  if (opts.json) {
+    printJson({ installed, target });
+    return installed ? 0 : 1;
+  }
+  if (!fileExists) {
     console.log(`No rules file at ${target}`);
     return 1;
   }
-  const content = readFileSync4(target, "utf-8");
-  if (content.includes(SKILL_BEGIN) && content.includes(SKILL_END)) {
+  if (installed) {
     console.log(`PRIM SKILL v1 installed at ${target}`);
     return 0;
   }
@@ -617,7 +705,7 @@ function registerSkillCommands(program2) {
   skill.command("uninstall").description("Remove the prim skill block from your project rules file").option("--target <path>", "Path to the rules file (overrides auto-detection)").action((opts) => {
     process.exit(runUninstall(process.cwd(), opts));
   });
-  skill.command("status").description("Report whether the prim skill block is installed").option("--target <path>", "Path to the rules file (overrides auto-detection)").action((opts) => {
+  skill.command("status").description("Report whether the prim skill block is installed").option("--target <path>", "Path to the rules file (overrides auto-detection)").option("--json", "Output as JSON").action((opts) => {
     process.exit(runStatus(process.cwd(), opts));
   });
 }
@@ -626,20 +714,28 @@ function registerSkillCommands(program2) {
 import { readFileSync as readFileSync5 } from "fs";
 function registerSpecCommands(program2) {
   const spec = program2.command("spec").description("Manage spec documents");
-  spec.command("list").description("List spec documents").option("-t, --project-id <projectId>", "List spec for a specific root project").action(async (opts) => {
+  spec.command("list").description("List spec documents").option("-t, --project-id <projectId>", "List spec for a specific root project").option("--json", "Output as JSON").action(async (opts) => {
     const client = getClient();
     if (opts.projectId) {
       const specs = await client.get(`/api/cli/specs?rootTaskId=${opts.projectId}`);
+      if (opts.json) {
+        printJson(specs[0] ?? null);
+        return;
+      }
       if (specs.length === 0) {
-        console.log("No spec document found for this project.");
+        console.error("No spec document found for this project.");
         return;
       }
       printSpec(specs[0]);
       return;
     }
     const contexts = await client.get("/api/cli/specs");
+    if (opts.json) {
+      printJson(contexts);
+      return;
+    }
     if (contexts.length === 0) {
-      console.log("No spec documents found.");
+      console.error("No spec documents found.");
       return;
     }
     for (const ctx of contexts) {
@@ -648,39 +744,91 @@ function registerSpecCommands(program2) {
       const name = ctx.name ?? "(unnamed)";
       console.log(`${ctx._id}  ${scope.padEnd(8)} ${String(review).padEnd(10)} ${name}`);
     }
-    console.log(`
+    console.error(`
 ${contexts.length} spec(s)`);
   });
-  spec.command("get <contextId>").description("Get a spec document by ID").option("--text-only", "Print only the text content (no metadata)").action(async (contextId, opts) => {
+  spec.command("get <contextId>").description("Get a spec document by ID").option("--text-only", "Print only the text content (no metadata)").option("--json", "Output as JSON (overrides --text-only)").action(async (contextId, opts) => {
     const client = getClient();
     const ctx = await client.get(`/api/cli/contexts/${contextId}`);
+    if (opts.json) {
+      printJson(ctx);
+      return;
+    }
     if (opts.textOnly) {
       console.log(ctx.text ?? "");
       return;
     }
     printSpec(ctx);
   });
-  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").action(async (contextId, opts) => {
-    const client = getClient();
-    let text = opts.text;
-    if (opts.file) {
-      text = readFileSync5(opts.file, "utf-8");
-    }
-    if (!(text || opts.name)) {
-      console.error("Provide --text, --file, or --name to update.");
-      process.exit(1);
+  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);
     }
-    await client.patch(`/api/cli/contexts/${contextId}`, {
-      name: opts.name,
-      text,
-      skipTiptapLifecycle: !!text
-    });
-    if (text) {
-      await client.post(`/api/cli/contexts/${contextId}/inject`);
+  );
+  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();
+      let text = opts.text;
+      if (opts.file) {
+        text = readFileSync5(opts.file, "utf-8");
+      }
+      if (!(text || opts.name)) {
+        console.error("Provide --text, --file, or --name to update.");
+        process.exit(1);
+      }
+      await client.patch(`/api/cli/contexts/${contextId}`, {
+        name: opts.name,
+        text,
+        skipTiptapLifecycle: !!text
+      });
+      if (text) {
+        await client.post(`/api/cli/contexts/${contextId}/inject`);
+      }
+      if (opts.json) {
+        printJson({ _id: contextId });
+        return;
+      }
+      console.error(`Updated spec: ${contextId}`);
+      console.log(contextId);
     }
-    console.log(`Updated spec: ${contextId}`);
-  });
-  spec.command("sync <contextId>").description("Trigger spec \u2194 project DAG synchronization").action(async (contextId) => {
+  );
+  spec.command("sync <contextId>").description("Trigger spec \u2194 project DAG synchronization").option("--json", "Output as JSON").action(async (contextId, opts) => {
     const client = getClient();
     const ctx = await client.get(`/api/cli/contexts/${contextId}`);
     if (!ctx.isSpecDocument) {
@@ -688,42 +836,123 @@ ${contexts.length} spec(s)`);
       process.exit(1);
     }
     await client.post(`/api/cli/contexts/${contextId}/sync`);
-    console.log(`Triggered sync for spec: ${contextId}`);
+    if (opts.json) {
+      printJson(
+        ctx.specRootTaskId ? { _id: contextId, specRootTaskId: ctx.specRootTaskId } : { _id: contextId }
+      );
+      return;
+    }
+    console.error(`Triggered sync for spec: ${contextId}`);
     if (ctx.specRootTaskId) {
-      console.log(`Root project: ${ctx.specRootTaskId}`);
+      console.error(`Root project: ${ctx.specRootTaskId}`);
+    }
+    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/**"'
-  ).action(async (contextId, opts) => {
+  ).option("--json", "Output as JSON").action(async (contextId, opts) => {
     const client = getClient();
     const result = await client.post(`/api/cli/contexts/${contextId}/map`, {
       patterns: opts.pattern
     });
-    console.log(`Mapped patterns to spec ${contextId}:`);
+    if (opts.json) {
+      printJson({ _id: contextId, filePatterns: result.filePatterns });
+      return;
+    }
+    console.error(`Mapped patterns to spec ${contextId}:`);
     for (const p of result.filePatterns) {
-      console.log(`  ${p}`);
+      console.error(`  ${p}`);
     }
+    console.log(contextId);
   });
-  spec.command("unmap <contextId>").description("Remove file pattern mappings from a spec (omit --pattern to clear all)").option("-p, --pattern <patterns...>", "Specific pattern(s) to remove (omit to clear all)").action(async (contextId, opts) => {
+  spec.command("unmap <contextId>").description("Remove file pattern mappings from a spec (omit --pattern to clear all)").option("-p, --pattern <patterns...>", "Specific pattern(s) to remove (omit to clear all)").option("--json", "Output as JSON").action(async (contextId, opts) => {
     const client = getClient();
     const result = await client.post(`/api/cli/contexts/${contextId}/unmap`, {
       patterns: opts.pattern
     });
+    if (opts.json) {
+      printJson({ _id: contextId, filePatterns: result.filePatterns });
+      return;
+    }
     if (result.filePatterns.length === 0) {
-      console.log(`Cleared all file patterns from spec ${contextId}`);
+      console.error(`Cleared all file patterns from spec ${contextId}`);
     } else {
-      console.log(`Updated patterns for spec ${contextId}:`);
+      console.error(`Updated patterns for spec ${contextId}:`);
       for (const p of result.filePatterns) {
-        console.log(`  ${p}`);
+        console.error(`  ${p}`);
       }
     }
+    console.log(contextId);
   });
-  spec.command("auto-map <contextId>").description("Trigger auto-mapping of file patterns for a spec").action(async (contextId) => {
+  spec.command("auto-map <contextId>").description("Trigger auto-mapping of file patterns for a spec").option("--json", "Output as JSON").action(async (contextId, opts) => {
     const client = getClient();
     await client.post(`/api/cli/contexts/${contextId}/auto-map`);
-    console.log(`Auto-mapping triggered for spec: ${contextId}`);
+    if (opts.json) {
+      printJson({ _id: contextId });
+      return;
+    }
+    console.error(`Auto-mapping triggered for spec: ${contextId}`);
+    console.log(contextId);
   });
 }
 function printSpec(ctx) {
@@ -752,7 +981,10 @@ var __dirname2 = dirname3(fileURLToPath2(import.meta.url));
 var pkg = JSON.parse(readFileSync6(resolve3(__dirname2, "../package.json"), "utf-8"));
 updateNotifier({ pkg }).notify();
 var program = new Command();
-program.name("prim").description("CLI for managing Primitive specs and contexts").version(pkg.version);
+program.name("prim").description("CLI for managing Primitive specs and contexts").version(pkg.version).option("-y, --yes", "auto-confirm prompts").option(
+  "--non-interactive",
+  "fail fast instead of prompting (also: CI=1, PRIM_NON_INTERACTIVE=1)"
+);
 registerAuthCommands(program);
 registerContextCommands(program);
 registerSpecCommands(program);

package/package.json

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