@tomismeta/paperclip-aperture 0.2.1 → 0.3.0

package/README.md

@@ -64,22 +64,43 @@ 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
 - a plugin-local deterministic semantic mapping layer that interprets Paperclip issue, approval, and agent signals before publishing them into Aperture Core
+- richer semantic continuity hints on mapped issue events, including `supersedes` and `resolves` relationships where Paperclip-specific intent is clear
+- document-aware review interpretation for memo/spec-backed issues so Focus can tell the difference between `review is blocked on the artifact` and `the artifact is attached, monitor instead`
 - dynamic re-stacking so items can move between `now`, `next`, and `ambient` as new evidence arrives
 - inline issue commenting from the Focus surface when a Paperclip issue supports written response
 - 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
@@ -104,14 +125,19 @@ Before releasing, run:
 pnpm release:check
 ```
 
-For a live local Paperclip smoke test:
+For a live local Paperclip smoke test, start Paperclip first:
 
 ```bash
 pnpm build
+npx paperclipai run -i default
+```
+
+Then, in a second terminal:
+
+```bash
 npx paperclipai context set --api-base http://localhost:3100
 npx paperclipai plugin uninstall tomismeta.paperclip-aperture --force
 npx paperclipai plugin install --local .
-npx paperclipai run -i default
 ```
 
 Then open `http://127.0.0.1:3100/APE/aperture` and verify:
@@ -121,6 +147,9 @@ Then open `http://127.0.0.1:3100/APE/aperture` and verify:
 - issue comments post successfully from Focus
 - 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.1",
+  version: "0.3.0",
   displayName: "Paperclip Aperture",
   description: "The live attention layer for Paperclip, powered by Aperture's deterministic attention engine.",
   author: "@tomismeta",
@@ -12,6 +12,7 @@ const manifest = {
     "issues.read",
     "issue.comments.read",
     "issue.comments.create",
+    "issue.documents.read",
     "plugin.state.read",
     "plugin.state.write",
     "ui.dashboardWidget.register",

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

@@ -12330,12 +12330,78 @@ function truncate(value, max = 180) {
 function issueText(issue, comment) {
   return [comment?.body, issue.description].filter((value) => !!value).join("\n");
 }
+function toTimestamp(value) {
+  if (!value) return 0;
+  if (value instanceof Date) return value.getTime();
+  const timestamp = Date.parse(value);
+  return Number.isNaN(timestamp) ? 0 : timestamp;
+}
+function toIsoString(value) {
+  if (!value) return null;
+  if (typeof value === "string") return value;
+  return value.toISOString();
+}
 function normalizeActorKey(value) {
   return value.toLowerCase().replace(/[^a-z0-9]/g, "");
 }
 function escapeRegex(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+function issueRelationTarget(issueId) {
+  return `issue:${issueId}`;
+}
+function detectIssueIntents(text) {
+  const intents = /* @__PURE__ */ new Set();
+  for (const detector of ISSUE_INTENT_DETECTORS) {
+    if (detector.pattern.test(text)) intents.add(detector.key);
+  }
+  return intents;
+}
+function blockingTargetForText(text, identifier) {
+  const normalizedIdentifier = identifier?.toUpperCase();
+  const matches = text.match(/\b[A-Z]+-\d+\b/g) ?? [];
+  return matches.find((match) => match.toUpperCase() !== normalizedIdentifier) ?? null;
+}
+function explicitBoardInstructionForText(text) {
+  return text.replace(/\s+/g, " ").trim().match(/(board should either .*?)(?:[.!?]|$)/i)?.[1] ?? null;
+}
+function semanticConfidenceForIntents(intents) {
+  if (intents.has("resolution") || intents.has("share_with_board") || intents.has("confirmation") || intents.has("board_instruction")) {
+    return "high";
+  }
+  if (intents.has("clarification")) return "medium";
+  return null;
+}
+function relationHintsForIntents(intents, issueTarget) {
+  const hints = [];
+  const target = issueTarget ?? void 0;
+  if (target) {
+    hints.push({ kind: "same_issue", target });
+  }
+  if (intents.has("resolution")) {
+    hints.push(target ? { kind: "resolves", target } : { kind: "resolves" });
+    return hints;
+  }
+  if (intents.has("share_with_board") || intents.has("confirmation") || intents.has("board_instruction")) {
+    hints.push(target ? { kind: "supersedes", target } : { kind: "supersedes" });
+    return hints;
+  }
+  if (intents.has("clarification")) {
+    hints.push(target ? { kind: "repeats", target } : { kind: "repeats" });
+  }
+  return hints;
+}
+function analyzeIssueTextSemantics(input) {
+  const intents = detectIssueIntents(input.text);
+  return {
+    text: input.text,
+    blockingTarget: blockingTargetForText(input.text, input.identifier),
+    intents,
+    explicitBoardInstruction: explicitBoardInstructionForText(input.text),
+    semanticConfidence: semanticConfidenceForIntents(intents),
+    relationHints: relationHintsForIntents(intents, input.issueTarget)
+  };
+}
 function resolveAgentOwner(text, directory) {
   if (!directory || directory.agentNames.length === 0) return null;
   const mentionMatch = text.match(/needed from\s+@([a-z0-9_-]+)/i) ?? text.match(/@([a-z0-9_-]+)/i);
@@ -12348,25 +12414,19 @@ function resolveAgentOwner(text, directory) {
 }
 function analyzeIssueIntents(issue, comment, directory) {
   const text = issueText(issue, comment);
-  const intents = /* @__PURE__ */ new Set();
-  for (const detector of ISSUE_INTENT_DETECTORS) {
-    if (detector.pattern.test(text)) intents.add(detector.key);
-  }
+  const semanticAnalysis = analyzeIssueTextSemantics({
+    text,
+    identifier: issue.identifier,
+    issueTarget: issueRelationTarget(issue.id)
+  });
   const agentOwner = resolveAgentOwner(text, directory);
   const mentionMatch = text.match(/needed from\s+@([a-z0-9_-]+)/i) ?? text.match(/@([a-z0-9_-]+)/i);
   const owner = agentOwner ?? (mentionMatch?.[1] ? titleCase(mentionMatch[1]) : /board should|board can/i.test(text) ? "Board" : /ceo agent|@ceo|\bceo\b/i.test(text) ? "CEO" : /requires human|waiting on human|human review/i.test(text) ? "Human" : /operator intervention|operator review/i.test(text) ? "Operator" : null);
   const ownerKind = agentOwner ? "agent" : owner ? "human" : null;
-  const identifier = issue.identifier?.toUpperCase();
-  const matches = text.match(/\b[A-Z]+-\d+\b/g) ?? [];
-  const blockingTarget = matches.find((match) => match.toUpperCase() !== identifier) ?? null;
-  const explicitBoardInstruction = text.replace(/\s+/g, " ").trim().match(/(board should either .*?)(?:[.!?]|$)/i)?.[1] ?? null;
   return {
-    text,
+    ...semanticAnalysis,
     owner,
-    ownerKind,
-    blockingTarget,
-    intents,
-    explicitBoardInstruction
+    ownerKind
   };
 }
 function hasIntent(analysis, key) {
@@ -12376,8 +12436,28 @@ function ownerPhrase(value, ownerKind) {
   if (ownerKind === "agent") return value;
   return actorPhrase(value);
 }
-function issueRecommendedMove(issue, analysis) {
+function latestIssueDocument(documents) {
+  if (documents.length === 0) return null;
+  return [...documents].sort(
+    (left, right) => toTimestamp(right.updatedAt) - toTimestamp(left.updatedAt)
+  )[0] ?? null;
+}
+function analyzeIssueDocuments(documents, comment, analysis) {
+  const latest = latestIssueDocument(documents);
+  const latestUpdatedAt = toIsoString(latest?.updatedAt);
+  const commentUpdatedAt = comment?.updatedAt ?? null;
+  return {
+    hasDocuments: documents.length > 0,
+    latestDocumentTitle: latest?.title ?? null,
+    latestDocumentUpdatedAt: latestUpdatedAt,
+    resolvesArtifactRequest: hasIntent(analysis, "share_with_board") && !!latest && (!commentUpdatedAt || toTimestamp(latestUpdatedAt) >= toTimestamp(commentUpdatedAt))
+  };
+}
+function issueRecommendedMove(issue, analysis, documentSignal) {
   const normalized = analysis.text.replace(/\s+/g, " ").trim();
+  if (documentSignal?.resolvesArtifactRequest) {
+    return "Monitor the review now that the memo is attached.";
+  }
   if (hasIntent(analysis, "resolution")) {
     return "Monitor execution and confirm the team resumes work.";
   }
@@ -12402,7 +12482,10 @@ function issueRecommendedMove(issue, analysis) {
   }
   return null;
 }
-function issueHeadline(issue, analysis) {
+function issueHeadline(issue, analysis, documentSignal) {
+  if (documentSignal?.resolvesArtifactRequest) {
+    return "The requested memo appears attached, so review should be able to continue.";
+  }
   if (hasIntent(analysis, "resolution")) {
     return "Latest operator guidance appears to unblock this issue.";
   }
@@ -12426,7 +12509,13 @@ function issueHeadline(issue, analysis) {
   if (issue.description) return truncate(issue.description);
   return "This issue has new operator-relevant activity.";
 }
-function issueWhyNow(issue, analysis) {
+function issueWhyNow(issue, analysis, documentSignal) {
+  if (documentSignal?.resolvesArtifactRequest) {
+    return {
+      whyNow: documentSignal.latestDocumentTitle ? `${documentSignal.latestDocumentTitle} was attached after the request, so the missing artifact appears resolved.` : "A review document was attached after the request, so the missing artifact appears resolved.",
+      factors: ["document attached", "review can proceed"]
+    };
+  }
   if (hasIntent(analysis, "resolution")) {
     return {
       whyNow: "The latest comment appears to resolve the blocker; monitor execution rather than intervening.",
@@ -12467,12 +12556,19 @@ function issueWhyNow(issue, analysis) {
 
 // src/aperture/reconciliation.ts
 var COMMENT_LOOKUP_CONCURRENCY = 6;
-function toIsoString(value) {
+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;
   return value.toISOString();
 }
-function toTimestamp(value) {
+function toTimestamp2(value) {
   if (!value) return 0;
   if (value instanceof Date) return value.getTime();
   const timestamp = Date.parse(value);
@@ -12489,20 +12585,12 @@ function acknowledgeResponseSpec() {
 function issueTitle(issue) {
   return issue.identifier ? `${issue.identifier} ${issue.title}` : issue.title;
 }
-function recommendedMove(issue, comment, directory) {
-  const analysis = analyzeIssueIntents(issue, comment, directory);
-  return issueRecommendedMove(issue, analysis);
-}
-function issueHeadline2(issue, comment, directory) {
-  const analysis = analyzeIssueIntents(issue, comment, directory);
-  return issueHeadline(issue, analysis);
-}
 function latestComment(comments) {
   if (comments.length === 0) return null;
   const newest = [...comments].sort(
-    (left, right) => toTimestamp(right.updatedAt) - toTimestamp(left.updatedAt)
+    (left, right) => toTimestamp2(right.updatedAt) - toTimestamp2(left.updatedAt)
   )[0];
-  const updatedAt = toIsoString(newest.updatedAt) ?? toIsoString(newest.createdAt) ?? (/* @__PURE__ */ new Date(0)).toISOString();
+  const updatedAt = toIsoString2(newest.updatedAt) ?? toIsoString2(newest.createdAt) ?? (/* @__PURE__ */ new Date(0)).toISOString();
   return {
     body: truncate(newest.body),
     updatedAt
@@ -12511,37 +12599,38 @@ function latestComment(comments) {
 function priorityConsequence(issue) {
   return issue.priority === "critical" || issue.priority === "high" ? "high" : "medium";
 }
-function issueLane(issue, comment, directory) {
-  const analysis = analyzeIssueIntents(issue, comment, directory);
-  if (issue.status === "blocked" && hasIntent(analysis, "resolution")) {
-    return comment || issue.isUnreadForMe ? "ambient" : null;
+function issueLane(issue, comment, evidence) {
+  if ((issue.status === "blocked" || issue.status === "in_review") && (hasIntent(evidence.analysis, "resolution") || evidence.documentSignal.resolvesArtifactRequest)) {
+    return comment || issue.isUnreadForMe || evidence.documentSignal.hasDocuments ? "ambient" : null;
   }
   if (issue.status === "blocked") return issue.priority === "critical" ? "active" : "queued";
   if (issue.status === "in_review") return "queued";
   if (comment || issue.isUnreadForMe) return "ambient";
   return null;
 }
-function issueSummary(issue, comment, directory) {
-  return issueHeadline2(issue, comment, directory);
+function issueSummary(issue, evidence) {
+  return issueHeadline(issue, evidence.analysis, evidence.documentSignal);
 }
-function issueProvenance(issue, comment, directory) {
-  const analysis = analyzeIssueIntents(issue, comment, directory);
-  return issueWhyNow(issue, analysis);
+function issueProvenance(issue, evidence) {
+  return issueWhyNow(issue, evidence.analysis, evidence.documentSignal);
 }
-function issueAttentionTimestamp(issue, comment) {
-  const commentSignals = [comment?.updatedAt, toIsoString(issue.lastExternalCommentAt)].filter((value) => !!value).sort();
+function issueAttentionTimestamp(issue, comment, documentSignal) {
+  const commentSignals = [comment?.updatedAt, toIsoString2(issue.lastExternalCommentAt), documentSignal.latestDocumentUpdatedAt].filter((value) => !!value).sort();
   if (commentSignals.length > 0) return commentSignals.at(-1);
-  return toIsoString(issue.updatedAt) ?? toIsoString(issue.createdAt) ?? (/* @__PURE__ */ new Date(0)).toISOString();
+  return toIsoString2(issue.updatedAt) ?? toIsoString2(issue.createdAt) ?? (/* @__PURE__ */ new Date(0)).toISOString();
 }
-function issueFrame(issue, comment, directory) {
-  const lane = issueLane(issue, comment, directory);
-  if (!lane) return null;
-  const updatedAt = issueAttentionTimestamp(issue, comment);
-  const provenance = issueProvenance(issue, comment, directory);
+function issueFrame(issue, comment, documents, directory) {
   const analysis = analyzeIssueIntents(issue, comment, directory);
-  const owner = hasIntent(analysis, "resolution") ? null : analysis.owner;
-  const move = recommendedMove(issue, comment, directory);
+  const documentSignal = analyzeIssueDocuments(documents, comment, analysis);
+  const evidence = { analysis, documentSignal };
+  const lane = issueLane(issue, comment, evidence);
+  if (!lane) return null;
+  const updatedAt = issueAttentionTimestamp(issue, comment, documentSignal);
+  const provenance = issueProvenance(issue, evidence);
+  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: {
@@ -12558,7 +12647,7 @@ function issueFrame(issue, comment, directory) {
       tone: issue.status === "blocked" ? "focused" : lane === "ambient" ? "ambient" : "focused",
       consequence: issue.status === "blocked" ? priorityConsequence(issue) : lane === "ambient" ? "low" : "medium",
       title: issueTitle(issue),
-      summary: issueSummary(issue, comment, directory),
+      summary: issueSummary(issue, evidence),
       context: {
         items: [
           ...owner ? [needsActionFromItem(owner)] : [],
@@ -12572,7 +12661,7 @@ function issueFrame(issue, comment, directory) {
       responseSpec: acknowledgeResponseSpec(),
       provenance,
       timing: {
-        createdAt: toIsoString(issue.createdAt) ?? updatedAt,
+        createdAt: toIsoString2(issue.createdAt) ?? updatedAt,
         updatedAt
       },
       metadata: {
@@ -12580,7 +12669,11 @@ function issueFrame(issue, comment, 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 } : {}
       }
     }
   };
@@ -12601,7 +12694,7 @@ function agentSummary(agent) {
 function agentFrame(agent) {
   const lane = agentLane(agent);
   if (!lane) return null;
-  const updatedAt = toIsoString(agent.updatedAt) ?? toIsoString(agent.createdAt) ?? (/* @__PURE__ */ new Date(0)).toISOString();
+  const updatedAt = toIsoString2(agent.updatedAt) ?? toIsoString2(agent.createdAt) ?? (/* @__PURE__ */ new Date(0)).toISOString();
   const provenance = agentProvenance(agent);
   return {
     lane,
@@ -12630,7 +12723,7 @@ function agentFrame(agent) {
       responseSpec: acknowledgeResponseSpec(),
       provenance,
       timing: {
-        createdAt: toIsoString(agent.createdAt) ?? updatedAt,
+        createdAt: toIsoString2(agent.createdAt) ?? updatedAt,
         updatedAt
       },
       metadata: {
@@ -12638,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"
+        }
       }
     }
   };
@@ -12655,6 +12754,17 @@ async function safeListComments(ctx, issue) {
     return null;
   }
 }
+async function safeListDocuments(ctx, issue) {
+  try {
+    return await ctx.issues.documents.list(issue.id, issue.companyId);
+  } catch (error) {
+    ctx.logger.warn("Failed to load issue documents during Aperture reconciliation", {
+      issueId: issue.id,
+      error: error instanceof Error ? error.message : String(error)
+    });
+    return [];
+  }
+}
 async function mapWithConcurrency(items, limit, mapper) {
   if (items.length === 0) return [];
   const results = new Array(items.length);
@@ -12676,16 +12786,23 @@ async function loadIssueCandidates(ctx, companyId) {
     ctx.issues.list({ companyId, status: "in_review", limit: 25 })
   ]);
   const issues = [...blocked, ...inReview];
-  const comments = await mapWithConcurrency(
-    issues,
-    COMMENT_LOOKUP_CONCURRENCY,
-    (issue) => safeListComments(ctx, issue)
-  );
-  const allAgents = await ctx.agents.list({ companyId, limit: 100 });
+  const [comments, documents, allAgents] = await Promise.all([
+    mapWithConcurrency(
+      issues,
+      COMMENT_LOOKUP_CONCURRENCY,
+      (issue) => safeListComments(ctx, issue)
+    ),
+    mapWithConcurrency(
+      issues,
+      COMMENT_LOOKUP_CONCURRENCY,
+      (issue) => safeListDocuments(ctx, issue)
+    ),
+    ctx.agents.list({ companyId, limit: 100 })
+  ]);
   const directory = {
     agentNames: allAgents.map((agent) => agent.name).filter((name) => typeof name === "string" && name.trim().length > 0)
   };
-  return issues.map((issue, index) => issueFrame(issue, comments[index] ?? null, directory)).filter((candidate) => candidate !== null);
+  return issues.map((issue, index) => issueFrame(issue, comments[index] ?? null, documents[index] ?? [], directory)).filter((candidate) => candidate !== null);
 }
 async function loadAgentCandidates(ctx, companyId) {
   const [pendingApproval, errored, paused] = await Promise.all([
@@ -13457,9 +13574,6 @@ function issueDisplayTitle(event, fallback) {
   if (issueTitle2) return issueTitle2;
   return fallback;
 }
-function issueRelationTarget(issueId) {
-  return `issue:${issueId}`;
-}
 function relationHintsForIssueTargets(issueIds) {
   if (!issueIds || issueIds.length === 0) return void 0;
   return {
@@ -13469,12 +13583,29 @@ function relationHintsForIssueTargets(issueIds) {
     }))
   };
 }
+function issueSemanticText(payload) {
+  return [
+    readPayloadString(payload, "bodySnippet"),
+    readPayloadString(payload, "summary"),
+    readPayloadString(payload, "description"),
+    readPayloadString(payload, "title"),
+    readPayloadString(payload, "issueTitle")
+  ].filter((value) => !!value).join("\n");
+}
 function issueSemanticHints(event) {
-  return event.entityType === "issue" && event.entityId ? relationHintsForIssueTargets([event.entityId]) : void 0;
+  if (event.entityType !== "issue" || !event.entityId) return void 0;
+  const semanticAnalysis = analyzeIssueTextSemantics({
+    text: issueSemanticText(event.payload),
+    identifier: readPayloadString(event.payload, "identifier"),
+    issueTarget: issueRelationTarget(event.entityId)
+  });
+  return {
+    ...semanticAnalysis.semanticConfidence ? { confidence: semanticAnalysis.semanticConfidence } : {},
+    ...semanticAnalysis.relationHints.length > 0 ? { relationHints: semanticAnalysis.relationHints } : {}
+  };
 }
 function approvalSemanticHints(budgetOverride, linkedIssueIds) {
   return {
-    confidence: "high",
     whyNow: approvalBlockingWhyNow(budgetOverride),
     factors: budgetOverride ? ["budget stop", "approval", "operator decision"] : ["approval", "operator decision"],
     ...relationHintsForIssueTargets(linkedIssueIds) ?? {}
@@ -13482,7 +13613,6 @@ function approvalSemanticHints(budgetOverride, linkedIssueIds) {
 }
 function pendingApprovalSemanticHints() {
   return {
-    confidence: "high",
     whyNow: pendingApprovalEventWhyNow(),
     factors: ["pending approval"]
   };
@@ -13490,7 +13620,6 @@ function pendingApprovalSemanticHints() {
 function runFailureSemanticHints() {
   return {
     intentFrame: "failure",
-    confidence: "high",
     whyNow: runFailedWhyNow(),
     factors: ["run failed", "operator review"]
   };

package/package.json

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