@tomismeta/paperclip-aperture 0.2.2 → 0.3.0

package/README.md

@@ -64,6 +64,7 @@ and agents                             attention now?    actually sees     to th
 
 - a Focus surface inside Paperclip
 - ranked `now`, `next`, and `ambient` attention lanes
+- embedded explainability in the Focus UI, including `Why now`, `Why next`, confidence, signals, thread context, and related activity
 - approval handling, including budget-specific approval semantics
 - issue-aware operator language such as `review required`, `blocked`, and targeted recommended moves
 - agent-aware routing that distinguishes known company agents from human/operator roles when issue text references them
@@ -75,13 +76,31 @@ and agents                             attention now?    actually sees     to th
 - durable acknowledge/suppression behavior backed by plugin state and ledger replay
 - a sidebar entry, page, and dashboard widget
 
+## Explainability
+
+Focus is meant to be more legible than a smart inbox.
+
+The first `0.3.0` explainability slice keeps reasoning attached to the cards you are already acting on:
+
+- `Why now` on the active card explains why the current item outranks the rest of the queue
+- `Why next` on queued rows explains why something is staged behind the current top item
+- `Confidence` shows how strong the semantic signal is when the plugin has one
+- `Signals` surfaces the specific factors that pushed the item into attention
+- `Thread context` and `Related activity` help explain whether an item is part of a broader episode or continuation
+
+The intent is not to expose every internal scoring detail. It is to help an operator answer:
+
+- why did this surface?
+- why is it in this lane?
+- how much should I trust this judgment?
+
 ## Package Boundary
 
 This plugin treats Paperclip as the host runtime and UI shell, while embedding [Aperture Core](https://github.com/tomismeta/aperture/tree/main/packages/core) through the npm package [`@tomismeta/aperture-core`](https://www.npmjs.com/package/@tomismeta/aperture-core).
 
 It is a pure SDK integration: Aperture Core is used as-is inside a self-contained Paperclip plugin, with no changes to Aperture Core or Paperclip core.
 
-For `0.2.x`, the boundary works like this:
+For `0.3.x`, the boundary works like this:
 
 - the plugin worker owns Aperture ingestion, replay, review state, and display composition
 - Paperclip remains the system of record for issue and approval writes
@@ -129,6 +148,8 @@ Then open `http://127.0.0.1:3100/APE/aperture` and verify:
 - approval actions update Focus correctly
 - resolved blocker comments downgrade stale `Now` items
 - attached issue documents downgrade stale `share the memo/spec` review blockers into monitor-only follow-up
+- the active card exposes `Why now`
+- expanded queued rows expose `Why next`
 
 ## Links
 

package/dist/manifest.js

@@ -1,7 +1,7 @@
 const manifest = {
   id: "tomismeta.paperclip-aperture",
   apiVersion: 1,
-  version: "0.2.2",
+  version: "0.3.0",
   displayName: "Paperclip Aperture",
   description: "The live attention layer for Paperclip, powered by Aperture's deterministic attention engine.",
   author: "@tomismeta",

package/dist/ui/index.js

@@ -123,6 +123,82 @@ function mergeStoredFrames(snapshot, companyId, candidates, review, nowIso = (/*
   }, review);
 }
 
+// src/aperture/explainability.ts
+function asRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+}
+function readStringArray(value) {
+  if (!Array.isArray(value)) return [];
+  return value.filter((entry) => typeof entry === "string" && entry.trim().length > 0);
+}
+function readSemanticConfidence(frame) {
+  const semantic = asRecord(frame.metadata?.semantic);
+  const confidence = semantic?.confidence;
+  return confidence === "low" || confidence === "medium" || confidence === "high" ? confidence : null;
+}
+function readSemanticRelationHints(frame) {
+  const semantic = asRecord(frame.metadata?.semantic);
+  const relationHints = semantic?.relationHints;
+  if (!Array.isArray(relationHints)) return [];
+  return relationHints.filter((entry) => {
+    if (typeof entry !== "object" || entry === null) return false;
+    const hint = entry;
+    return hint.kind === "same_issue" || hint.kind === "resolves" || hint.kind === "supersedes" || hint.kind === "repeats" || hint.kind === "escalates";
+  });
+}
+function relationHintLabel(hint) {
+  switch (hint.kind) {
+    case "same_issue":
+      return "Part of the same thread";
+    case "resolves":
+      return "Resolves an earlier blocker";
+    case "supersedes":
+      return "Moves the request forward";
+    case "repeats":
+      return "Repeats an earlier ask";
+    case "escalates":
+      return "Raises the urgency";
+  }
+}
+function laneReason(lane) {
+  switch (lane) {
+    case "active":
+      return "This is the most urgent item in the queue right now.";
+    case "queued":
+      return "This is queued behind the current top item.";
+    case "ambient":
+      return "This is visible for awareness without needing action yet.";
+  }
+}
+function continuitySummary(frame) {
+  const episode = asRecord(frame.metadata?.episode);
+  const size = typeof episode?.size === "number" ? episode.size : null;
+  const state = typeof episode?.state === "string" ? episode.state.replace(/_/g, " ") : null;
+  if (!size || size <= 1) return null;
+  if (state) return `Part of a ${state} thread with ${size} related interactions.`;
+  return `Part of a thread with ${size} related interactions.`;
+}
+function frameSignals(frame) {
+  const attention = asRecord(frame.metadata?.attention);
+  const rationale = readStringArray(attention?.rationale);
+  const factors = readStringArray(frame.provenance?.factors);
+  return [.../* @__PURE__ */ new Set([...rationale.length > 0 ? rationale : factors, ...factors])];
+}
+function signalStrengthLabel(confidence) {
+  return `${confidence} confidence`;
+}
+function explainFrame(frame, lane) {
+  const relationLabels = [...new Set(readSemanticRelationHints(frame).map(relationHintLabel))];
+  return {
+    whyNow: frame.provenance?.whyNow ?? frame.summary ?? null,
+    laneReason: laneReason(lane),
+    signalStrength: readSemanticConfidence(frame),
+    signals: frameSignals(frame),
+    relationLabels,
+    continuity: continuitySummary(frame)
+  };
+}
+
 // src/aperture/attention-context.ts
 var ATTENTION_CONTEXT_IDS = {
   approvalType: "approval-type",
@@ -223,6 +299,10 @@ function approvalRecordToFrame(record) {
   const decisionContext = typeof payload.decisionContext === "string" ? payload.decisionContext : void 0;
   const summary = typeof payload.summary === "string" ? payload.summary : approvalBlockingSummary(budgetOverride);
   const updatedAt = record.updatedAt ?? record.createdAt;
+  const provenance = {
+    whyNow: approvalBlockingWhyNow(budgetOverride),
+    factors: budgetOverride ? ["budget stop", "approval", "operator decision"] : ["approval", "operator decision"]
+  };
   return {
     id: `approval-bootstrap:${record.id}`,
     taskId: `approval:${record.id}`,
@@ -256,17 +336,20 @@ function approvalRecordToFrame(record) {
         ...budgetOverride ? [{ id: "request-revision", label: "Request revision", kind: "cancel", emphasis: "secondary" }] : []
       ]
     },
-    provenance: {
-      whyNow: approvalBlockingWhyNow(budgetOverride),
-      factors: budgetOverride ? ["budget stop", "approval", "operator decision"] : ["approval", "operator decision"]
-    },
+    provenance,
     timing: {
       createdAt: record.createdAt,
       updatedAt
     },
     metadata: {
       approvalStatus: record.status,
-      approvalType: record.type
+      approvalType: record.type,
+      attention: {
+        rationale: provenance.factors
+      },
+      semantic: {
+        confidence: "high"
+      }
     }
   };
 }
@@ -933,6 +1016,52 @@ function ContextItems({ frame }) {
     item2.id
   )) });
 }
+function DetailCard(props) {
+  return /* @__PURE__ */ jsxs("div", { className: cn("border border-border bg-secondary/50 px-3 py-2", props.className), children: [
+    /* @__PURE__ */ jsx("div", { className: "text-xs font-medium text-muted-foreground", children: props.label }),
+    /* @__PURE__ */ jsx("div", { className: "mt-1", children: props.children })
+  ] });
+}
+function ExplainabilityBadges(props) {
+  if (props.values.length === 0) return null;
+  return /* @__PURE__ */ jsx("div", { className: "flex flex-wrap items-center gap-2", children: props.values.map((value) => /* @__PURE__ */ jsx(
+    Badge,
+    {
+      className: props.accent ? "border-transparent" : "border-border bg-background/70 text-foreground/80",
+      style: props.accent ? { color: ACCENT_COLOR, backgroundColor: `${ACCENT_COLOR}14`, borderColor: `${ACCENT_COLOR}33` } : void 0,
+      children: value
+    },
+    value
+  )) });
+}
+function ExplainabilityPanel(props) {
+  const explanation = explainFrame(props.frame, props.lane);
+  const strength = explanation.signalStrength ? signalStrengthLabel(explanation.signalStrength) : null;
+  return /* @__PURE__ */ jsxs("div", { className: "grid gap-3 lg:grid-cols-2", children: [
+    /* @__PURE__ */ jsxs(DetailCard, { label: "Why now", className: "lg:col-span-2", children: [
+      /* @__PURE__ */ jsx("p", { className: "text-sm leading-relaxed text-foreground/90", children: explanation.whyNow ?? judgmentLine(props.frame, props.lane) }),
+      /* @__PURE__ */ jsx("p", { className: "mt-2 text-xs leading-relaxed text-muted-foreground", children: explanation.laneReason })
+    ] }),
+    strength ? /* @__PURE__ */ jsx(DetailCard, { label: "Confidence", children: /* @__PURE__ */ jsx("p", { className: "text-sm text-foreground/90", children: strength }) }) : null,
+    explanation.continuity ? /* @__PURE__ */ jsx(DetailCard, { label: "Related activity", children: /* @__PURE__ */ jsx("p", { className: "text-sm leading-relaxed text-foreground/90", children: explanation.continuity }) }) : null,
+    explanation.signals.length > 0 ? /* @__PURE__ */ jsx(DetailCard, { label: "Signals", className: explanation.relationLabels.length > 0 ? "lg:col-span-1" : "lg:col-span-2", children: /* @__PURE__ */ jsx(ExplainabilityBadges, { values: explanation.signals }) }) : null,
+    explanation.relationLabels.length > 0 ? /* @__PURE__ */ jsx(DetailCard, { label: "Thread context", className: explanation.signals.length > 0 ? "lg:col-span-1" : "lg:col-span-2", children: /* @__PURE__ */ jsx(ExplainabilityBadges, { values: explanation.relationLabels, accent: true }) }) : null
+  ] });
+}
+function ExplainabilityStrip(props) {
+  const explanation = explainFrame(props.frame, props.lane);
+  const chips = [
+    ...explanation.signalStrength ? [signalStrengthLabel(explanation.signalStrength)] : [],
+    ...explanation.signals.slice(0, 2),
+    ...explanation.relationLabels.slice(0, 1)
+  ];
+  return /* @__PURE__ */ jsxs("div", { className: "space-y-2 rounded-md border border-border/70 bg-secondary/30 px-3 py-2", children: [
+    /* @__PURE__ */ jsx("div", { className: "text-xs font-medium text-muted-foreground", children: props.lane === "queued" ? "Why next" : props.lane === "ambient" ? "Why ambient" : "Why now" }),
+    /* @__PURE__ */ jsx("p", { className: "text-xs leading-relaxed text-muted-foreground", children: explanation.whyNow ?? judgmentLine(props.frame, props.lane) }),
+    /* @__PURE__ */ jsx("div", { className: "text-[11px] leading-relaxed text-muted-foreground", children: explanation.laneReason }),
+    chips.length > 0 ? /* @__PURE__ */ jsx(ExplainabilityBadges, { values: chips, accent: true }) : null
+  ] });
+}
 function isIssueFrame(frame) {
   return entityTypeFromFrame(frame) === "issue";
 }
@@ -1017,19 +1146,16 @@ function NowDetails(props) {
   const budgetHref = isBudgetOverride(frame) ? costsHref(props.companyPrefix) : null;
   const activityLink = activityHref(frame, props.companyPrefix);
   return /* @__PURE__ */ jsxs("div", { className: "space-y-3 border-t border-border pt-4", children: [
-    /* @__PURE__ */ jsxs("div", { className: "border border-border bg-secondary/50 px-3 py-2", children: [
-      /* @__PURE__ */ jsx("div", { className: "text-xs font-medium text-muted-foreground", children: "Judgment" }),
-      /* @__PURE__ */ jsx("p", { className: "mt-1 text-sm text-foreground/90", children: judgmentLine(frame, "active") }),
-      /* @__PURE__ */ jsxs("div", { className: "mt-2 flex flex-wrap items-center gap-x-3 gap-y-1 text-xs text-muted-foreground", children: [
-        /* @__PURE__ */ jsx("span", { children: requestDescriptor(frame) }),
-        /* @__PURE__ */ jsx("span", { children: impactLabel(frame) }),
-        /* @__PURE__ */ jsx("span", { children: formatRelativeTime(frameUpdatedAt(frame, snapshotUpdatedAt)) }),
-        requestedAmount(frame) ? /* @__PURE__ */ jsxs("span", { children: [
-          "Amount requested: ",
-          requestedAmount(frame)
-        ] }) : null,
-        budgetReason(frame) ? /* @__PURE__ */ jsx("span", { children: budgetReason(frame) }) : null
-      ] })
+    /* @__PURE__ */ jsx(ExplainabilityPanel, { frame, lane: "active" }),
+    /* @__PURE__ */ jsxs("div", { className: "flex flex-wrap items-center gap-x-3 gap-y-1 text-xs text-muted-foreground", children: [
+      /* @__PURE__ */ jsx("span", { children: requestDescriptor(frame) }),
+      /* @__PURE__ */ jsx("span", { children: impactLabel(frame) }),
+      /* @__PURE__ */ jsx("span", { children: formatRelativeTime(frameUpdatedAt(frame, snapshotUpdatedAt)) }),
+      requestedAmount(frame) ? /* @__PURE__ */ jsxs("span", { children: [
+        "Amount requested: ",
+        requestedAmount(frame)
+      ] }) : null,
+      budgetReason(frame) ? /* @__PURE__ */ jsx("span", { children: budgetReason(frame) }) : null
     ] }),
     /* @__PURE__ */ jsx(ContextItems, { frame }),
     /* @__PURE__ */ jsxs("div", { className: "flex flex-wrap items-center gap-3", children: [
@@ -1311,6 +1437,7 @@ function NextRow(props) {
     ),
     expanded ? /* @__PURE__ */ jsxs("div", { className: "space-y-3 px-4 pb-3 pl-12 sm:px-6 sm:pl-14", children: [
       showDetailText ? /* @__PURE__ */ jsx("p", { className: "text-sm leading-relaxed text-muted-foreground", children: detailText }) : null,
+      /* @__PURE__ */ jsx(ExplainabilityStrip, { frame, lane: "queued" }),
       /* @__PURE__ */ jsxs("div", { className: "flex flex-wrap items-center gap-x-4 gap-y-1 text-xs text-muted-foreground", children: [
         /* @__PURE__ */ jsx("span", { children: impactLabel(frame) }),
         driver ? /* @__PURE__ */ jsx(Accent, { children: driver }) : null,

package/dist/worker.js

@@ -12556,6 +12556,13 @@ function issueWhyNow(issue, analysis, documentSignal) {
 
 // src/aperture/reconciliation.ts
 var COMMENT_LOOKUP_CONCURRENCY = 6;
+function semanticMetadata(confidence, relationHints) {
+  const semantic = {
+    ...confidence ? { confidence } : {},
+    ...relationHints.length > 0 ? { relationHints } : {}
+  };
+  return Object.keys(semantic).length > 0 ? semantic : void 0;
+}
 function toIsoString2(value) {
   if (!value) return void 0;
   if (typeof value === "string") return value;
@@ -12623,6 +12630,7 @@ function issueFrame(issue, comment, documents, directory) {
   const owner = hasIntent(analysis, "resolution") || documentSignal.resolvesArtifactRequest ? null : analysis.owner;
   const move = issueRecommendedMove(issue, analysis, documentSignal);
   const target = analysis.blockingTarget;
+  const semantic = semanticMetadata(analysis.semanticConfidence, analysis.relationHints);
   return {
     lane,
     frame: {
@@ -12661,7 +12669,11 @@ function issueFrame(issue, comment, documents, directory) {
         issueStatus: issue.status,
         issuePriority: issue.priority,
         liveReconciled: true,
-        activityPath: comment ? "activity" : void 0
+        activityPath: comment ? "activity" : void 0,
+        attention: {
+          rationale: provenance.factors ?? []
+        },
+        ...semantic ? { semantic } : {}
       }
     }
   };
@@ -12719,7 +12731,13 @@ function agentFrame(agent) {
         agentStatus: agent.status,
         pauseReason: agent.pauseReason,
         liveReconciled: true,
-        activityPath: agent.status === "error" ? "activity" : void 0
+        activityPath: agent.status === "error" ? "activity" : void 0,
+        attention: {
+          rationale: provenance.factors ?? []
+        },
+        semantic: {
+          confidence: "high"
+        }
       }
     }
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomismeta/paperclip-aperture",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "type": "module",
   "private": false,
   "description": "The live attention layer for Paperclip, powered by Aperture's deterministic attention engine.",