@jentrix/cli 0.5.9 → 0.5.11

package/claude-plugin/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "jentrix",
   "description": "Connect this Claude Code session to a Jentrix project: /jentrix-connect binds the current session (trusted lifecycle hooks supply the session id), /jentrix-align runs the MVP alignment wizard, /jentrix-status and /jentrix-end wrap the same session operations. Business logic lives in the Jentrix CLI — removing this plugin leaves `jentrix session attach` as the universal fallback.",
-  "version": "0.4.0"
+  "version": "0.5.0"
 }

package/claude-plugin/commands/jentrix-end.md

@@ -1,6 +1,6 @@
 ---
 description: End the connected Jentrix session (pushes the final artifacts, verifies capture, stores the RUN_SUMMARY)
-allowed-tools: Bash(jentrix session:*), Bash(jentrix push:*)
+allowed-tools: Bash(jentrix session:*), Bash(jentrix push:*), Bash(jentrix artifact:*), Bash(jentrix column:*), Bash(jentrix task:*), Bash(jentrix tool:*)
 ---
 
 End the connected Jentrix session honestly. For an ALIGNED session (the MVP
@@ -12,14 +12,30 @@ pipeline), the typed artifacts ARE the record — push them before closing:
      what changed, what's next) and run
      `jentrix push report --title "<short title>"` with the content on stdin.
    - Push any decisions made this session that were not already pushed:
-     `jentrix push decision …` (one per decision).
+     `jentrix push decision --basis <artifact-id|url> …` (one per decision;
+     `--basis` is repeatable and names what the decision rested on — file the
+     context first so the ref resolves).
+   - **Gap sweep**: every promised-but-undone item becomes a
+     `jentrix push gap` — one per gap, title stating the claim ("Windows hook
+     path untested"). A session with no output MUST have at least one gap
+     explaining why. Push `jentrix push issue` for anything found broken and
+     not yet recorded.
    - Push any durable lessons: `jentrix push learning …`.
    - If the session produced a diff/patch worth recording, push it:
      `git diff | jentrix push diff --title "<what it changes>"`.
    Ask the operator (native choice UI) before pushing anything they might
    not want recorded; never invent content — summarize what actually
    happened.
-2. Move the aligned task to the board's **"In review"** column when the work
+2. **Batched mint confirmations.** Collect this session's gap/issue/findings
+   artifacts that are not yet cards (each push printed its offer) and ask the
+   operator ONCE, as a single native choice list: which should become cards?
+   For each accepted one run
+   `jentrix artifact mint-issue --artifact <id> --from-task <taskId>`
+   (add `--blocks` when it blocks acceptance of the aligned task). Mints are
+   idempotent per artifact (`mint-<artifactId>`), so a retry converges on the
+   same card. A declined mint leaves the artifact exactly as pushed — never
+   nag again, never mint unasked.
+3. Move the aligned task to the board's **"In review"** column when the work
    is finished — not to a terminal one. Acceptance is a human's to record
    (Accept / Return on the task panel writes who decided, when, and on which
    artifacts), and an agent grading its own work as Done is the cheapest habit
@@ -32,7 +48,7 @@ pipeline), the typed artifacts ARE the record — push them before closing:
    terminal column the operator never got to judge. If it is unclear whether
    the task is done, ask the operator through the native choice UI. Pushing a
    `findings` or `report` artifact is not by itself proof the task is done.
-3. **Offer a one-line project outcome.** A project that never changes state
+4. **Offer a one-line project outcome.** A project that never changes state
    cannot answer the only question a goal exists to answer — are we closer.
    Ask the operator, through the native choice UI, for one sentence on what
    this session moved, and record it on the project's goal statement: read the
@@ -42,11 +58,11 @@ pipeline), the typed artifacts ARE the record — push them before closing:
    `jentrix tool update_project --args '{"projectId":"<id>","goalStatement":"<existing text>\n<YYYY-MM-DD>: <the operator's sentence>","expectedUpdatedAt":"<updatedAt from the read>"}'`.
    Offer it; never write a sentence they did not say, and never block the
    close on it — a declined nudge is a normal outcome.
-4. Run `jentrix session end <session-id>` with the Bash tool (ask the user or
+5. Run `jentrix session end <session-id>` with the Bash tool (ask the user or
    run `jentrix session status` first when the id is unknown) and relay the
    output. Telemetry is recorded by the session host's attested path — never
    report token numbers yourself.
-5. **Relay the closing telemetry line verbatim.** `session end` prints a
+6. **Relay the closing telemetry line verbatim.** `session end` prints a
    `Telemetry:` line, and on stderr it may print `NO TOKEN TELEMETRY: …`.
    Exit 0 does NOT mean telemetry was recorded — on 2026-08-11 a real session
    closed at exit 0 having recorded none, and nothing said so. If the warning
@@ -54,9 +70,9 @@ pipeline), the typed artifacts ARE the record — push them before closing:
    another session's transcript) and the repair for the next session
    (`jentrix align --provider-session <id> --transcript-path <file>`). Do not
    restate the numbers as your own claim — quote the line.
-6. The session is SEALED once ended: `jentrix push` refuses it
+7. The session is SEALED once ended: `jentrix push` refuses it
    (`SESSION_NOT_ACTIVE`), by design. Anything learned at the close —
    including the telemetry line above — belongs in the report you pushed in
    step 1, or in the next session. Do not try to reopen it.
-7. Ending the Jentrix session does NOT terminate this Claude Code session —
+8. Ending the Jentrix session does NOT terminate this Claude Code session —
    say so if the user seems to expect it.

package/claude-plugin/commands/jentrix-review.md

@@ -0,0 +1,42 @@
+---
+description: Review a Jentrix session's typed artifacts by category (input → plan → decision → output → issue → gap → learning → record), check the readiness contract, and post the verdict as a task comment
+allowed-tools: Bash(jentrix tool:*), Bash(jentrix artifact:*), Bash(jentrix session:*), Bash(jentrix comment:*)
+---
+
+Run the category walk over one session's record (docs: Reviewing a session).
+Read-only until the final comment; never modify the tree, the board, or the
+artifacts under review.
+
+1. Resolve the session: the argument if one was given, else the checkout's
+   aligned session (`jentrix session status`). Note its aligned task — the
+   verdict lands there.
+2. List the record:
+   `jentrix artifact list --workspace <id> --session-id <sessionId> --json`
+   (or `jentrix tool list_artifacts --args '{"workspaceId":"…","sessionId":"…"}'`).
+   Group the rows by review category — input (PROMPT/GOAL/PRD/SOURCE_DIGEST),
+   plan (PLAN), decision (DECISION_MEMO), output (DELIVERABLE/REPORT/DIFF/
+   PATCH/PR/BRANCH/COMMIT/SCREENSHOT/RECORDING/MOCKUP/CSV/PDF/DOC + anything
+   unmapped), issue (ISSUE/FINDINGS), gap (GAP), learning
+   (LEARNING/MEMORY_NOMINATION), record (TRACE/RUN_SUMMARY/LOG/EVAL_REPORT/
+   POLICY_REPORT) — and walk them in that order.
+3. Read what needs reading: `jentrix artifact get --artifact-id <id>` returns a
+   short-lived download URL; fetch the bodies of the RUN_SUMMARY, each
+   DECISION_MEMO, and every output you are judging.
+4. Check the readiness contract and verify it yourself — do not just quote
+   the summary's verdict:
+   - ≥ 1 input artifact;
+   - every DECISION_MEMO body carries a `Based on:` block, and each
+     artifact-id ref in it RESOLVES (`jentrix artifact get --artifact-id`) — a ref that
+     404s is a finding;
+   - ≥ 1 output artifact OR ≥ 1 gap explaining why there is none;
+   - the RUN_SUMMARY's Capture integrity section reports complete capture or
+     capture off by design.
+5. Post the verdict as ONE comment on the aligned task
+   (`jentrix comment create --task <id> --body …`): the per-category counts,
+   each contract check with its evidence, what you actually opened, and the
+   conclusion — review-ready or not, and what is missing. Verdicts are
+   task-scoped; never move the card and never mark anything accepted —
+   Accept/Return is the operator's control.
+6. If the walk surfaced something broken that is not yet on the record,
+   offer (never auto-run) `jentrix push issue` / `jentrix push gap` on the
+   session, and the mint command for a card.

package/codex-plugin/plugins/jentrix/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jentrix",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Connect Codex tasks to Jentrix projects with trusted lifecycle hooks, alignment, checkpoints, and honest session capture.",
   "author": {
     "name": "Jentrix",

package/codex-plugin/plugins/jentrix/skills/jentrix-end/SKILL.md

@@ -6,18 +6,25 @@ description: End a connected Jentrix session after preserving approved outputs,
 # End the connected session
 
 1. For an aligned session, offer to push a concise final `report`, any unrecorded
-   `decision` or `learning`, and a useful `diff`. Never invent content or record
-   material the operator declined.
-2. If work is genuinely complete, read the board's real columns and move the task to
+   `decision --basis <artifact-id|url>` or `learning`, and a useful `diff`. Run the
+   **gap sweep**: every promised-but-undone item becomes a `jentrix push gap` (title
+   states the claim), and anything found broken becomes `jentrix push issue`. Never
+   invent content or record material the operator declined.
+2. **Batched mint confirmations**: list this session's gap/issue/findings artifacts
+   not yet minted and ask the operator once which should become cards; for each
+   accepted one run `jentrix artifact mint-issue --artifact <id> --from-task <id>`
+   (`--blocks` when it blocks acceptance). Idempotent per artifact
+   (`mint-<artifactId>`); a declined mint leaves the artifact untouched.
+3. If work is genuinely complete, read the board's real columns and move the task to
    **In review**. Never self-accept it into Done.
-3. Offer the operator a one-line project outcome; append only wording they supplied.
+4. Offer the operator a one-line project outcome; append only wording they supplied.
    Declining never blocks closure.
-4. Run `jentrix session end <session-id>` and relay all output, including the exact
+5. Run `jentrix session end <session-id>` and relay all output, including the exact
    telemetry line and any capture gap.
-5. Explain that Codex lifecycle hooks do not report token receipts, so null token
+6. Explain that Codex lifecycle hooks do not report token receipts, so null token
    fields are expected on hook-watched sessions. Do not report estimates.
-6. A final-response artifact exists only when a prior `Stop` hook observed assistant
+7. A final-response artifact exists only when a prior `Stop` hook observed assistant
    text before closure. The assistant text produced by this closing turn occurs after
    the command and must not be claimed as captured.
-7. The Jentrix session is sealed after end; do not retry pushes against it. Ending it
+8. The Jentrix session is sealed after end; do not retry pushes against it. Ending it
    does not terminate the Codex task.

package/codex-plugin/plugins/jentrix/skills/jentrix-review/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: stacks-review
+description: Review a Jentrix session's typed artifacts by category, verify the readiness contract, and post the verdict as a comment on the aligned task.
+---
+
+# Review a session's record
+
+1. Resolve the target session (argument, else `jentrix session status`) and its
+   aligned task — the verdict lands there.
+2. `jentrix tool list_artifacts --args '{"workspaceId":"…","sessionId":"…"}'` and
+   group by review category, walking in order: input → plan → decision → output →
+   issue → gap → learning → record.
+3. Read the RUN_SUMMARY, every DECISION_MEMO, and the outputs under judgment via
+   `jentrix artifact get --artifact-id <id>` download URLs.
+4. Verify the readiness contract yourself (never just quote the verdict): ≥1 input;
+   every memo's `Based on:` refs resolve; ≥1 output or ≥1 gap; capture integrity
+   holds or capture was off by design.
+5. Post ONE task comment with per-category counts, each check with evidence, and
+   the conclusion. Never move cards, never self-accept — Accept/Return belongs to
+   the operator.
+6. Offer (never auto-run) `jentrix push issue|gap` and the mint command for
+   anything the walk surfaced that is not yet on the record.

package/dist/main.js

@@ -20962,7 +20962,7 @@ function refreshAccessToken(input) {
 
 // src/client.ts
 var CLI_NAME = "stacks-cli";
-var CLI_VERSION = "0.5.9";
+var CLI_VERSION = "0.5.11";
 var DEAD_TOKEN_MESSAGE = "authentication failed (HTTP 401): the token is dead or expired \u2014 mint a new PAT at /account/tokens on your Jentrix server and update STACKS_TOKEN (or --token / the config file).";
 var RELOGIN_MESSAGE = "OAuth session expired and could not be refreshed \u2014 run `jentrix login` to sign in again.";
 function originOf2(url2) {
@@ -21803,7 +21803,7 @@ async function inspectRepository(cwd, git = defaultGitRunner) {
 
 // src/commands/align.ts
 import { randomUUID as randomUUID2 } from "node:crypto";
-import { existsSync as existsSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "node:fs";
 import { join as join3 } from "node:path";
 
 // src/mcp-config.ts
@@ -24135,6 +24135,16 @@ ${JSON.stringify(session.alignment, null, 2)}`
     },
     detected.providerSessionId
   );
+  try {
+    const spoolDir = join3(deps2.spoolRoot, sessionId);
+    mkdirSync3(spoolDir, { recursive: true });
+    writeFileSync3(
+      join3(spoolDir, "prompt-request.json"),
+      JSON.stringify({ requestedAt: (/* @__PURE__ */ new Date()).toISOString() }),
+      { mode: 384 }
+    );
+  } catch {
+  }
   if (!liveHost && detected.provider === "claude" && detected.transcriptPath && detected.providerSessionId && transcriptBelongsTo(detected.transcriptPath, detected.providerSessionId) === false) {
     deps2.writeErr(
       [
@@ -24730,7 +24740,10 @@ var PUSH_KINDS = [
   "learning",
   "prompt",
   "goal",
-  "prd"
+  "prd",
+  "gap",
+  "issue",
+  "context"
 ];
 var ARTIFACT_TYPE_BY_PUSH_KIND = {
   plan: "PLAN",
@@ -24742,7 +24755,10 @@ var ARTIFACT_TYPE_BY_PUSH_KIND = {
   learning: "LEARNING",
   prompt: "PROMPT",
   goal: "GOAL",
-  prd: "PRD"
+  prd: "PRD",
+  gap: "GAP",
+  issue: "ISSUE",
+  context: "SOURCE_DIGEST"
 };
 function sessionTarget(sessionId) {
   return {
@@ -24767,7 +24783,17 @@ async function runPush(kind, file, flags, deps2) {
         `unknown kind "${kind}" \u2014 expected one of: ${PUSH_KINDS.join(", ")}`
       );
     }
+    if (flags.basis?.length && kind !== "decision") {
+      throw new UsageError(
+        "--basis records what a decision rested on \u2014 it only applies to `jentrix push decision`"
+      );
+    }
     if (flags.ref) {
+      if (flags.basis?.length) {
+        throw new UsageError(
+          "--ref references an existing artifact, so there is no body to carry a basis block \u2014 drop --basis"
+        );
+      }
       if (!flags.task) {
         throw new UsageError(
           "--ref needs --task <id>: a reference links an existing artifact TO a task"
@@ -24820,7 +24846,10 @@ async function runPush(kind, file, flags, deps2) {
         file ? `${file} is empty` : "stdin is empty \u2014 pipe the content or name a file"
       );
     }
-    const body = redactLocal(raw, deps2.env);
+    const withBasis = flags.basis?.length ? `${await basisBlock(flags.basis, deps2)}
+
+${raw}` : raw;
+    const body = redactLocal(withBasis, deps2.env);
     const credentials = deps2.resolveTarget();
     const post = (to) => (deps2.fetchImpl ?? fetch)(
       new URL(to.path, stacksBaseUrlOf(credentials.url)),
@@ -24887,8 +24916,8 @@ async function runPush(kind, file, flags, deps2) {
         `note: identical content is already stored on task ${payload.sameBytesOnTaskId}. One truth per artifact: \`jentrix push ${kind} --ref <artifactId> --task ${payload.taskId}\` references it instead of keeping two rows that will disagree once one is revised.`
       );
     }
-    if (kind === "findings" && payload.taskId) {
-      await offerIssueMint(payload, flags, deps2, correlatedSessionId);
+    if (isMintableKind(kind) && payload.taskId) {
+      await offerCardMint(kind, payload, flags, deps2, correlatedSessionId);
     }
     return 0;
   } catch (error2) {
@@ -24902,6 +24931,37 @@ async function runPush(kind, file, flags, deps2) {
     return 1;
   }
 }
+async function basisBlock(refs, deps2) {
+  const lines = [];
+  const ids = refs.filter((ref) => !/^https?:\/\//i.test(ref));
+  const titles = /* @__PURE__ */ new Map();
+  if (ids.length) {
+    await withCaller(deps2, async (caller) => {
+      for (const id of ids) {
+        try {
+          const result = await callStructured(caller, "get_artifact", {
+            artifactId: id
+          });
+          const record3 = result.artifact ?? result;
+          titles.set(id, String(record3.title ?? ""));
+        } catch {
+          throw new UsageError(
+            `--basis ${id} does not resolve to an artifact you can read \u2014 push the context first (\`jentrix push context\`), or pass a URL`,
+            EXIT_CODES.NOT_FOUND
+          );
+        }
+      }
+    });
+  }
+  for (const ref of refs) {
+    const title = titles.get(ref);
+    lines.push(
+      title !== void 0 ? `- artifact ${ref} \u2014 ${title}` : `- ${ref}`
+    );
+  }
+  return `Based on:
+${lines.join("\n")}`;
+}
 async function runRefPush(kind, artifactId, taskId, flags, deps2) {
   const credentials = deps2.resolveTarget();
   const response = await (deps2.fetchImpl ?? fetch)(
@@ -24929,54 +24989,72 @@ async function runRefPush(kind, artifactId, taskId, flags, deps2) {
   void kind;
   return 0;
 }
-async function offerIssueMint(payload, flags, deps2, sessionId = null) {
+var MINTABLE_PUSH_KINDS = ["findings", "gap", "issue"];
+function isMintableKind(kind) {
+  return MINTABLE_PUSH_KINDS.includes(kind);
+}
+var MINTABLE_ARTIFACT_TYPES = ["FINDINGS", "GAP", "ISSUE"];
+function mintNoun(type) {
+  return type === "GAP" ? "Gap" : type === "ISSUE" ? "Issue" : "Finding";
+}
+async function offerCardMint(kind, payload, flags, deps2, sessionId = null) {
   if (!payload.artifactId || !payload.taskId) return;
   try {
-    const board = await findIssuesBoard(deps2, payload.taskId);
+    const board = await findMintBoard(deps2, payload.taskId);
     if (!board) {
       deps2.writeErr(
-        "note: this workspace has no BUGS board, so there is nowhere to mint an issue. Create one (`jentrix board create --kind BUGS`) and re-push, or file the finding by hand."
+        "note: no board can take a card here (no BUGS board, and the task's own board has no column), so nothing was minted. File the card by hand."
       );
       return;
     }
     if (!flags.yes) {
+      const noun = kind === "findings" ? "issues" : "follow-up cards";
       deps2.writeErr(
-        `note: findings usually become issues. \`${mintIssueCommandHint(payload.artifactId, payload.taskId)}\` opens a card on ${board.name}, links this artifact to it, and relates it back to this task. Nothing was created.`
+        `note: ${kind} pushes usually become ${noun}. \`${mintIssueCommandHint(payload.artifactId, payload.taskId)}\` opens a card on ${board.name}, links this artifact to it, and relates it back to this task${flags.blocks ? "" : " (add --blocks when it blocks acceptance)"}. Nothing was created.`
       );
       return;
     }
-    const minted = await mintIssueCard(deps2, {
+    const minted = await mintCard(deps2, {
       board,
       artifactId: payload.artifactId,
       anchorTaskId: payload.taskId,
+      noun: mintNoun(ARTIFACT_TYPE_BY_PUSH_KIND[kind] ?? "FINDINGS"),
+      blocks: Boolean(flags.blocks),
       sessionId
     });
     deps2.writeOut(
-      `Minted issue ${minted.key ?? minted.id} on ${board.name} \xB7 artifact linked \xB7 RELATES_TO ${payload.taskId}`
+      `Minted ${minted.key ?? minted.id} on ${board.name} \xB7 artifact linked \xB7 ${flags.blocks ? "BLOCKS" : "RELATES_TO"} ${payload.taskId}`
     );
   } catch (error2) {
     deps2.writeErr(
-      `note: could not offer an issue card (${error2 instanceof Error ? error2.message : "unknown"}). The finding is stored; file the issue by hand.`
+      `note: could not offer a card (${error2 instanceof Error ? error2.message : "unknown"}). The artifact is stored; file the card by hand.`
     );
   }
 }
 function mintIssueCommandHint(artifactId, taskId) {
   return `jentrix artifact mint-issue --artifact ${artifactId} --from-task ${taskId}`;
 }
-async function findIssuesBoard(deps2, taskId) {
+async function findMintBoard(deps2, taskId) {
   return withCaller(deps2, async (caller) => {
     const task = await callStructured(caller, "get_task", { taskId });
     const workspaceId = String(task.workspaceId ?? "");
     if (!workspaceId) return null;
     const boards = (await callStructured(caller, "list_boards", { workspaceId })).boards.filter((b) => b.kind === "BUGS" && !b.archivedAt);
-    const board = boards[0];
-    if (!board) return null;
-    const columns = (await callStructured(caller, "list_columns", { boardId: board.id })).columns;
-    const first = columns[0];
-    return first ? { id: board.id, name: board.name, columnId: first.id } : null;
+    const candidates = [
+      ...boards,
+      ...task.boardId ? [{ id: String(task.boardId), name: String(task.boardName ?? "board") }] : []
+    ];
+    for (const board of candidates) {
+      const columns = (await callStructured(caller, "list_columns", { boardId: board.id })).columns;
+      const first = columns[0];
+      if (first) {
+        return { id: board.id, name: board.name, columnId: first.id };
+      }
+    }
+    return null;
   });
 }
-async function mintIssueCard(deps2, input) {
+async function mintCard(deps2, input) {
   return withCaller(
     deps2,
     async (caller, target) => {
@@ -24985,9 +25063,9 @@ async function mintIssueCard(deps2, input) {
       });
       const created = await callStructured(caller, "create_task", {
         columnId: input.board.columnId,
-        title: `Finding from ${String(anchor.key ?? input.anchorTaskId)}`,
-        description: `Minted from a findings artifact pushed on ${String(anchor.key ?? input.anchorTaskId)}. Origin session artifact: ${input.artifactId}.`,
-        idempotencyKey: `mint-issue-${input.artifactId}`
+        title: `${input.noun} from ${String(anchor.key ?? input.anchorTaskId)}`,
+        description: `Minted from a ${input.noun.toLowerCase()} artifact pushed on ${String(anchor.key ?? input.anchorTaskId)}. Origin session artifact: ${input.artifactId}.`,
+        idempotencyKey: `mint-${input.artifactId}`
       });
       const issueId = String(created.id);
       await (deps2.fetchImpl ?? fetch)(
@@ -25005,7 +25083,7 @@ async function mintIssueCard(deps2, input) {
       await callStructured(caller, "add_task_link", {
         fromTaskId: issueId,
         toTaskId: input.anchorTaskId,
-        kind: "RELATES_TO"
+        kind: input.blocks ? "BLOCKS" : "RELATES_TO"
       });
       return { id: issueId, key: created.key };
     },
@@ -25024,17 +25102,31 @@ async function runMintIssue(flags, deps2) {
       );
       sessionId = marker?.sessionId ?? null;
     }
-    const board = await findIssuesBoard(deps2, flags.fromTask);
+    const result = await withCaller(
+      deps2,
+      (caller) => callStructured(caller, "get_artifact", { artifactId: flags.artifact })
+    );
+    const record3 = result.artifact ?? result;
+    const type = String(record3.type ?? "");
+    if (!MINTABLE_ARTIFACT_TYPES.includes(type)) {
+      throw new UsageError(
+        `artifact ${flags.artifact} is ${type || "of unknown type"} \u2014 only FINDINGS, GAP, and ISSUE artifacts mint into cards`,
+        EXIT_CODES.CONFLICT
+      );
+    }
+    const board = await findMintBoard(deps2, flags.fromTask);
     if (!board) {
       throw new UsageError(
-        "this workspace has no BUGS board, so there is nowhere to mint an issue. Create one (`jentrix board create --kind BUGS`) and retry, or file the finding by hand.",
+        "no board can take a card here (no BUGS board, and the task's own board has no column). Create one and retry, or file the card by hand.",
         EXIT_CODES.NOT_FOUND
       );
     }
-    const minted = await mintIssueCard(deps2, {
+    const minted = await mintCard(deps2, {
       board,
       artifactId: flags.artifact,
       anchorTaskId: flags.fromTask,
+      noun: mintNoun(type),
+      blocks: Boolean(flags.blocks),
       sessionId
     });
     deps2.writeOut(
@@ -25043,8 +25135,9 @@ async function runMintIssue(flags, deps2) {
         issueKey: minted.key ?? null,
         boardId: board.id,
         artifactId: flags.artifact,
-        relatedTaskId: flags.fromTask
-      }) : `Minted issue ${minted.key ?? minted.id} on ${board.name} \xB7 artifact linked \xB7 RELATES_TO ${flags.fromTask}`
+        relatedTaskId: flags.fromTask,
+        linkKind: flags.blocks ? "BLOCKS" : "RELATES_TO"
+      }) : `Minted ${minted.key ?? minted.id} on ${board.name} \xB7 artifact linked \xB7 ${flags.blocks ? "BLOCKS" : "RELATES_TO"} ${flags.fromTask}`
     );
     return 0;
   } catch (error2) {
@@ -25060,10 +25153,13 @@ async function runMintIssue(flags, deps2) {
 }
 function registerMintIssueCommand(artifact, deps2, onExit2) {
   artifact.command("mint-issue").description(
-    "Mint an Issues card from a findings artifact: opens a card on the workspace's BUGS board, links the artifact to it, and relates it back to the source task."
-  ).requiredOption("--artifact <id>", "the findings artifact to link").requiredOption(
+    "Mint a card from a findings/gap/issue artifact: opens a card on the workspace's BUGS board (else the task's own board), links the artifact to it, and relates it back to the source task."
+  ).requiredOption("--artifact <id>", "the findings/gap/issue artifact to link").requiredOption(
     "--from-task <id>",
-    "the task the finding was pushed on (the card RELATES_TO it)"
+    "the task the artifact was pushed on (the card RELATES_TO it)"
+  ).option(
+    "--blocks",
+    "the card BLOCKS the source task (acceptance-blocking) instead of RELATES_TO"
   ).option("--json", "stable JSON output").action(
     async (flags) => onExit2(await runMintIssue(flags, deps2))
   );
@@ -25072,6 +25168,11 @@ function registerPushCommand(program3, deps2, onExit2) {
   program3.command("push <kind> [file]").description(
     `Push a typed artifact (${PUSH_KINDS.join("|")}) from a file or stdin to the ALIGNED session \u2014 redacted locally and server-side, linked to the aligned project/task.`
   ).option("--title <title>", "artifact title (defaults to kind + date)").option(
+    "--basis <ref>",
+    'decision pushes only, repeatable: an artifact id (must resolve) or URL the decision rested on \u2014 written as the structured "Based on:" block',
+    (ref, prior) => [...prior, ref],
+    []
+  ).option(
     "--session <id>",
     "explicit session id (default: this checkout's alignment)"
   ).option(
@@ -25085,7 +25186,10 @@ function registerPushCommand(program3, deps2, onExit2) {
     "reference an EXISTING artifact from --task instead of uploading (one artifact, N tasks)"
   ).option(
     "--yes",
-    "accept the offers this push makes (mint an issue from findings) without prompting"
+    "accept the offers this push makes (mint a card from findings/gap/issue) without prompting"
+  ).option(
+    "--blocks",
+    "with --yes on a findings/gap/issue push: the minted card BLOCKS the aligned task (acceptance-blocking) instead of RELATES_TO"
   ).option("--json", "stable JSON output").action(
     async (kind, file, flags) => onExit2(await runPush(kind, file, flags, deps2))
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jentrix/cli",
-  "version": "0.5.9",
+  "version": "0.5.11",
   "description": "Command-line client for the Jentrix MCP surface (jentrix tool <name>, generated noun-verb commands).",
   "keywords": [
     "jentrix",

package/surface.json

@@ -1018,7 +1018,9 @@
               "LEARNING",
               "PROMPT",
               "GOAL",
-              "PRD"
+              "PRD",
+              "GAP",
+              "ISSUE"
             ],
             "type": "string"
           },
@@ -10454,7 +10456,9 @@
               "LEARNING",
               "PROMPT",
               "GOAL",
-              "PRD"
+              "PRD",
+              "GAP",
+              "ISSUE"
             ],
             "type": "string"
           },