@primitive.ai/prim 0.1.0-alpha.52 → 0.1.0-alpha.54

package/README.md

@@ -31,8 +31,8 @@ npx @primitive.ai/prim
 In commands such as `npx --yes @primitive.ai/prim@latest ...`, the first `--yes`
 belongs to **npm**: it skips npm's package-install confirmation. It does not approve a
 Primitive action. Prim's own global `--yes` comes after the package name, for example
-`npx --yes @primitive.ai/prim@latest --yes decisions create ...`, and applies only to
-that Prim invocation.
+`npx --yes @primitive.ai/prim@latest --yes decisions create ... --attribution user`,
+and applies only to that Prim invocation.
 
 ## Quick Start
 
@@ -215,7 +215,7 @@ prim decisions show <id>                 # Drill into one decision
 prim decisions cascade <id>              # Blast radius of a decision
 prim decisions check --files <…>         # Active decisions referencing files (warn-only)
 prim decisions confirm <id>              # Answer a rationale-confirmation prompt
-prim decisions create --intent <…>       # Author a decision directly (flags-only)
+prim decisions create --intent <…> --attribution <user|agent>  # Record with explicit origin
 prim decisions link <child> --on <parent>    # Relate: <child> depends on <parent>
 prim decisions unlink <child> --on <parent>  # Remove that dependency
 ```
@@ -226,12 +226,19 @@ JSON; human-readable status goes to STDERR.
 When passive capture is inactive in the current repo, an approved one-time create is:
 
 ```bash
-npx --yes @primitive.ai/prim@latest --yes decisions create --intent "…"
+npx --yes @primitive.ai/prim@latest --yes decisions create --intent "…" --attribution user
 ```
 
 Here npm's first `--yes` only permits package resolution; Prim's second `--yes`
 confirms this create. It does not enable the repo or authorize a later create.
 
+Every create requires `--attribution user|agent`. Use `user` only when the person
+directly stated, selected, or confirmed the exact recorded choice. Use `agent` when
+the agent introduced that exact choice while pursuing a broader request. A broad task
+prompt or permission to implement does not make the resulting agent choice a user
+Decision. If the origin is ambiguous, confirm the exact choice with the person before
+creating it; do not guess.
+
 `link` / `unlink` curate the dependency edges the automatic linker would otherwise
 own — `<child>` depends on `<parent>`. Both are idempotent and refuse any link that
 would create a cycle (exit 2); an unresolved id exits 4.

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: prim
-description: Use the prim CLI for Primitive’s decision graph. MUST INVOKE before finishing any coding, planning, specification, or review task where the user or agent chose between plausible approaches or established or changed a lasting goal, priority, constraint, invariant, default, commitment, tradeoff, exception, or shared instruction—even when Primitive was not mentioned. Also invoke for Primitive setup, reading decisions, conflict gates, reconcile, rationale confirmations, linking, and team presence. SKIP routine implementation that merely follows an existing decision, temporary tactics, and unrelated uses of “decision.”
+description: Use the prim CLI for Primitive’s decision graph. MUST INVOKE before finishing any coding, planning, specification, or review task where the user or agent chose between plausible approaches or established or changed a lasting goal, priority, constraint, invariant, default, commitment, tradeoff, exception, or shared instruction—even when Primitive was not mentioned. Also invoke for Primitive setup, reading decisions, conflict gates, reconcile, rationale confirmations, linking, and team presence. SKIP — do not invoke even to check — when the task shows no fork that should guide future work, for example temporary tactics (a change that is explicitly temporary or to-be-reverted); routine implementation that merely follows an existing decision or a convention already visible in the code or repo instructions; or the word “decision” merely naming code, data, or UI. Such signals need no graph lookup to rule out.
 ---
 
 # Working with the prim CLI
@@ -80,7 +80,7 @@ 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. Record the chosen behavior, direction, constraint, or tradeoff—not routine implementation needed to finish the task or follow an existing convention. A teammate working elsewhere should benefit from knowing it.
+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. 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.
 
 ### Ground the rationale in real sources
 
@@ -91,8 +91,10 @@ Record only rationale supported by those sources. Do not mistake the implementat
 For proactively identified decisions in an active repo, let confidence in the rationale determine the interaction:
 
 - **Clear and well-supported** — record the decision and rationale silently at the natural task boundary.
-- **Plausible but uncertain** — at the task boundary, state the proposed rationale and ask for lightweight confirmation: “I understand the reason for choosing X to be Y. Is that right?” Record after confirmation or correction.
-- **No supported rationale** — at the task boundary, ask one focused question: “What made you choose X over the other path?” Record after the answer.
+- **Plausible but uncertain** — at the task boundary, state the proposed rationale and ask for lightweight confirmation: “I understand the reason for choosing X to be Y. Is that right?” Record in the same turn with the rationale omitted; add it once confirmed or corrected.
+- **No supported rationale** — at the task boundary, ask one focused question: “What made you choose X over the other path?” Record in the same turn with the rationale omitted; add it when the answer arrives.
+
+In both cases the question is a courtesy, not a gate: never make the record wait on an answer, and never fabricate a rationale to fill the gap. An unanswered question with no record is the only wrong outcome.
 
 These questions share the interruption budget below; never ask separate questions for the decision and its rationale. If both are uncertain, combine them into one concise prompt. An explicit request to “add this decision to Primitive” still records immediately with the information supplied—do not delay it to demand rationale.
 
@@ -109,8 +111,10 @@ an explicit local `prim.active=false` is always inactive. Every
   rationale, then wait for approval before creating it. A previous approval never
   carries forward to another Decision.
 - After approval, pass Prim's global `--yes` for that invocation:
-  `npx --yes @primitive.ai/prim --yes decisions create ...`. The first `--yes` is
-  npm's package-install flag; the second is Prim's one-time confirmation.
+  `npx --yes @primitive.ai/prim --yes decisions create ... --attribution user`.
+  The person's approval of the exact proposed choice is user ratification. The
+  first `--yes` is npm's package-install flag; the second is Prim's one-time
+  confirmation.
 - Do not run `prim enable` merely to bypass this boundary or infer permission to
   activate the repo. Activation requires a separate user request (a requested
   `prim setup` counts because setup explicitly activates its current repo). A
@@ -124,7 +128,7 @@ When the user asks to record a decision—for example, “add this decision to P
 
 ### Clear decisions: record without interrupting
 
-When the user clearly makes a durable fork-in-the-road decision without explicitly asking to record it, record it at the next natural task boundary without asking a redundant confirmation question **when passive capture is active**. In an inactive repo, present it and obtain the per-create approval above. Preserve the user's meaning and stated rationale; do not strengthen, broaden, or embellish it. Prefer the governing position over the implementation activity that revealed it.
+When the user clearly makes a durable fork-in-the-road decision without explicitly asking to record it, record it at the next natural task boundary without asking a redundant confirmation question **when passive capture is active**. An explicit ratification of a direction—“agreed,” “ship it that way,” or any equivalent affirmation—is such a decision even when the ratified option was your own proposal: the ratification is the approval, so record it and do not ask whether to record. That rule is general: in an active repository, never ask permission to record — the only question the budget permits is the single rationale question, and only when no rationale was stated. In an inactive repo, present it and obtain the per-create approval above. Preserve the user's meaning and stated rationale; do not strengthen, broaden, or embellish it. Prefer the governing position over the implementation activity that revealed it.
 
 Examples that qualify:
 
@@ -166,16 +170,18 @@ npx --yes @primitive.ai/prim decisions recent --limit 20
 If an equivalent decision is already present, do not create or suggest it again. After this duplicate check—or after the user confirms an onboarding proposal—author the decision directly. If the repo is inactive, that confirmation authorizes Prim's `--yes` only for the approved create:
 
 ```
-npx --yes @primitive.ai/prim decisions create --intent "Adopt prosemirror-collab over Yjs" --area data --rationale "Server-authoritative ordering" --alternatives "Yjs,Automerge"
+npx --yes @primitive.ai/prim decisions create --intent "Adopt prosemirror-collab over Yjs" --attribution user --area data --rationale "Server-authoritative ordering" --alternatives "Yjs,Automerge"
 ```
 
 Inactive-repo form after approval:
 
 ```
-npx --yes @primitive.ai/prim --yes decisions create --intent "Adopt prosemirror-collab over Yjs" --area data --rationale "Server-authoritative ordering" --alternatives "Yjs,Automerge"
+npx --yes @primitive.ai/prim --yes decisions create --intent "Adopt prosemirror-collab over Yjs" --attribution user --area data --rationale "Server-authoritative ordering" --alternatives "Yjs,Automerge"
 ```
 
-Only `--intent` is required. Optional: `--kind` (change|exploration|task_execution|unclear, default change), `--rationale`, `--area`, `--decided`, `--alternatives` (comma-separated), `--confidence` (high|medium|low, default high), `--reversibility` (high|low, default high), and `--files` (comma-separated repo-relative paths the decision governs — these are the files Conflict Gates would check on later edits, same path form as `decisions check`; Conflict Gates are not currently enabled). Omit `--files` for broad directions that should not immediately participate in file-based Conflict Gates. STDOUT is the created identity `{ decisionId, shortId, createdAt }`; STDERR prints `[prim] created dec_<short>.` — pass that `dec_<short>` straight into `decisions show` / `cascade` / `confirm`.
+Both `--intent` and `--attribution` are required. Set `--attribution user` only when the person directly stated, selected, or confirmed the exact recorded choice. Set `--attribution agent` when you introduced that exact choice while pursuing a broader request. A broad task prompt, implementation permission, or assignment of responsibility does not turn your implementation choice into a user Decision. If the origin is ambiguous, ask the person to confirm the exact choice before creating it; after confirmation, use `user`. Never guess attribution.
+
+Optional: `--kind` (change|exploration|task_execution|unclear, default change), `--rationale`, `--area`, `--decided`, `--alternatives` (comma-separated), `--confidence` (high|medium|low, default high), `--reversibility` (high|low, default high), and `--files` (comma-separated repo-relative paths the decision governs — these are the files Conflict Gates would check on later edits, same path form as `decisions check`; Conflict Gates are not currently enabled). Omit `--files` for broad directions that should not immediately participate in file-based Conflict Gates. STDOUT is the created identity `{ decisionId, shortId, createdAt }`; STDERR prints `[prim] created dec_<short>.` — pass that `dec_<short>` straight into `decisions show` / `cascade` / `confirm`.
 
 ### Inferred decisions: finish first, then optionally ask once
 

package/dist/index.js

@@ -2309,6 +2309,9 @@ function registerDaemonCommands(program2) {
   });
 }
 
+// src/commands/decisions.ts
+import { Option } from "commander";
+
 // src/decisions/cascade-renderer.ts
 var DEPENDENTS_INLINE_LIMIT = 5;
 var KNOWLEDGE_INLINE_LIMIT = 4;
@@ -2764,6 +2767,7 @@ var defaultDeps4 = { getClient };
 function toRequestBody(request) {
   const candidate = {
     intent: request.intent,
+    attribution: request.attribution,
     kind: request.kind,
     rationale: request.rationale,
     area: request.area,
@@ -3103,7 +3107,12 @@ function registerDecisionsCommands(program2) {
       throw err;
     }
   });
-  decisions.command("create").description("Author a decision directly \u2014 the deliberate manual path around automatic capture").requiredOption("--intent <text>", "What was decided (required)").option("--kind <kind>", "change | exploration | task_execution | unclear (default change)").option("--rationale <text>", "Why the decision was made").option(
+  decisions.command("create").description("Record a decision directly with its explicit user or agent origin").requiredOption("--intent <text>", "What was decided (required)").addOption(
+    new Option(
+      "--attribution <origin>",
+      "Who originated the exact choice: user | agent (required)"
+    ).choices(["user", "agent"]).makeOptionMandatory()
+  ).option("--kind <kind>", "change | exploration | task_execution | unclear (default change)").option("--rationale <text>", "Why the decision was made").option(
     "--area <area>",
     "Functional area (auth, data, infra, ui, api, billing, mobile, docs, testing)"
   ).option("--decided <items>", "Comma-separated option(s) chosen").option("--alternatives <items>", "Comma-separated options considered but rejected").option("--confidence <level>", "high | medium | low (default high)").option("--reversibility <level>", "high | low (default high)").option(
@@ -3124,6 +3133,7 @@ function registerDecisionsCommands(program2) {
     }
     const request = {
       intent: opts.intent,
+      attribution: opts.attribution,
       kind: opts.kind,
       rationale: opts.rationale,
       area: opts.area,
@@ -3874,7 +3884,7 @@ import { execFileSync } from "child_process";
 import { existsSync as existsSync7, mkdirSync as mkdirSync5, readFileSync as readFileSync6, unlinkSync as unlinkSync2, writeFileSync as writeFileSync4 } from "fs";
 import { homedir as homedir6 } from "os";
 import { dirname as dirname4, join as join6, resolve as resolve2 } from "path";
-import { Option } from "commander";
+import { Option as Option2 } from "commander";
 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];
@@ -4167,12 +4177,12 @@ function registerHooksCommands(program2) {
   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([
+    new Option2("--target <where>", "install destination; bypasses Husky detection").choices([
       "husky",
       "git-hooks"
     ])
   ).addOption(
-    new Option(
+    new Option2(
       "--scope <scope>",
       "project (default, this repo) or user (a global core.hooksPath capturing every repo)"
     ).choices(["project", "user"])
@@ -4212,7 +4222,7 @@ function registerHooksCommands(program2) {
   hooks.command("uninstall").description(
     "Remove the prim git hooks (.git/hooks, or the global core.hooksPath with --scope user)"
   ).addOption(
-    new Option(
+    new Option2(
       "--scope <scope>",
       "project (default, this repo) or user (global core.hooksPath)"
     ).choices(["project", "user"])

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitive.ai/prim",
-  "version": "0.1.0-alpha.52",
+  "version": "0.1.0-alpha.54",
   "description": "CLI for Primitive's decision graph — passive decision capture, conflict gate, and team presence",
   "type": "module",
   "license": "MIT",