@tomismeta/paperclip-aperture 0.2.1 → 0.2.2

package/README.md

@@ -68,6 +68,8 @@ and agents                             attention now?    actually sees     to th
 - 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
@@ -104,14 +106,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 +128,7 @@ 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
 
 ## Links
 

package/dist/manifest.js

@@ -1,7 +1,7 @@
 const manifest = {
   id: "tomismeta.paperclip-aperture",
   apiVersion: 1,
-  version: "0.2.1",
+  version: "0.2.2",
   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/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,12 @@ function issueWhyNow(issue, analysis) {
 
 // src/aperture/reconciliation.ts
 var COMMENT_LOOKUP_CONCURRENCY = 6;
-function toIsoString(value) {
+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 +12578,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,36 +12592,36 @@ 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;
   return {
     lane,
@@ -12558,7 +12639,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 +12653,7 @@ function issueFrame(issue, comment, directory) {
       responseSpec: acknowledgeResponseSpec(),
       provenance,
       timing: {
-        createdAt: toIsoString(issue.createdAt) ?? updatedAt,
+        createdAt: toIsoString2(issue.createdAt) ?? updatedAt,
         updatedAt
       },
       metadata: {
@@ -12601,7 +12682,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 +12711,7 @@ function agentFrame(agent) {
       responseSpec: acknowledgeResponseSpec(),
       provenance,
       timing: {
-        createdAt: toIsoString(agent.createdAt) ?? updatedAt,
+        createdAt: toIsoString2(agent.createdAt) ?? updatedAt,
         updatedAt
       },
       metadata: {
@@ -12655,6 +12736,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 +12768,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 +13556,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 +13565,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 +13595,6 @@ function approvalSemanticHints(budgetOverride, linkedIssueIds) {
 }
 function pendingApprovalSemanticHints() {
   return {
-    confidence: "high",
     whyNow: pendingApprovalEventWhyNow(),
     factors: ["pending approval"]
   };
@@ -13490,7 +13602,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.2.2",
   "type": "module",
   "private": false,
   "description": "The live attention layer for Paperclip, powered by Aperture's deterministic attention engine.",