Release 0.4.5 for Paperclip SDK 2026.517

Author: tomismeta

README.md

@@ -126,7 +126,7 @@ For `0.4.x`, the boundary works like this:
 - `activity.logged` document events invalidate stale reconciled state so document-backed review blockers refresh promptly without a full browser-side merge layer
 - Focus exports the live Core snapshot, the reconciled/plugin-composed display snapshot, and bounded Core traces so replay/debug flows can inspect both the engine substrate and the final operator view
 
-The plugin has been validated against [`@tomismeta/aperture-core@0.7.0`](https://www.npmjs.com/package/@tomismeta/aperture-core) and [`@paperclipai/plugin-sdk@2026.428.0`](https://www.npmjs.com/package/@paperclipai/plugin-sdk).
+The plugin requires Paperclip `2026.517.0` or newer and has been validated against [`@tomismeta/aperture-core@0.7.0`](https://www.npmjs.com/package/@tomismeta/aperture-core) and [`@paperclipai/plugin-sdk@2026.517.0`](https://www.npmjs.com/package/@paperclipai/plugin-sdk).
 
 Approval overlay transport is opt-in until the Paperclip plugin SDK exposes a first-class approval client. Set the plugin config field `paperclipApiBase` when the worker can reach the host approval API; leave it empty to run Focus without approval overlays in hosted or restricted-network environments.
 

docs/RELEASE-0.4.5.md

@@ -0,0 +1,27 @@
+# paperclip-aperture 0.4.5
+
+`0.4.5` aligns Paperclip Aperture with the current Paperclip plugin SDK and
+uses the newer host attention contracts where they improve Focus judgment.
+
+## Highlights
+
+- upgraded `@paperclipai/plugin-sdk` from `2026.428.0` to `2026.517.0`
+- declares Paperclip `2026.517.0` as the minimum host version
+- surfaces Paperclip Blocked Inbox attention as first-class Focus evidence
+- surfaces active Paperclip recovery actions directly in Focus
+- keeps planning-mode blockers calmer unless the host marks them urgent
+- preserves document lock metadata in review handoff copy and diagnostics
+- excludes plugin-operation issues from host reconciliation scans
+
+## Why This Matters
+
+- lets Focus defer to Paperclip's own blocked-work and recovery signals instead
+  of relying only on plugin-local heuristics
+- keeps Aperture current with the latest Paperclip issue, comment, and document
+  contracts
+- improves operator clarity around locked review artifacts and planning-mode
+  work without changing the plugin boundary
+
+## Validation
+
+- `pnpm verify`

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomismeta/paperclip-aperture",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "type": "module",
   "private": false,
   "description": "The live attention layer for Paperclip, combining Aperture Core continuity with Paperclip-native operator policy.",
@@ -54,7 +54,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@paperclipai/plugin-sdk": "2026.428.0",
+    "@paperclipai/plugin-sdk": "2026.517.0",
     "@tomismeta/aperture-core": "0.7.0"
   },
   "devDependencies": {

pnpm-lock.yaml

@@ -43,6 +43,7 @@ function createIssue(input: CorpusFixture["issue"]): Issue {
     title: input.title,
     description: input.description,
     status: input.status,
+    workMode: "standard",
     priority: "high",
     assigneeAgentId: null,
     assigneeUserId: null,

scripts/eval-issue-intelligence.ts

@@ -16,6 +16,11 @@ export const ATTENTION_CONTEXT_IDS = {
   recommendedMove: "recommended-move",
   issueStatus: "issue-status",
   issuePriority: "issue-priority",
+  issueWorkMode: "issue-work-mode",
+  blockedReason: "blocked-reason",
+  blockedSeverity: "blocked-severity",
+  recoveryAction: "recovery-action",
+  documentLock: "document-lock",
   latestComment: "latest-comment",
   agentStatus: "agent-status",
   pauseReason: "pause-reason",
@@ -78,6 +83,26 @@ export function issuePriorityItem(value: string): AttentionContextItem {
   return item(ATTENTION_CONTEXT_IDS.issuePriority, "Priority", value);
 }
 
+export function issueWorkModeItem(value: string): AttentionContextItem {
+  return item(ATTENTION_CONTEXT_IDS.issueWorkMode, "Mode", value);
+}
+
+export function blockedReasonItem(value: string): AttentionContextItem {
+  return item(ATTENTION_CONTEXT_IDS.blockedReason, "Blocked reason", value);
+}
+
+export function blockedSeverityItem(value: string): AttentionContextItem {
+  return item(ATTENTION_CONTEXT_IDS.blockedSeverity, "Severity", value);
+}
+
+export function recoveryActionItem(value: string): AttentionContextItem {
+  return item(ATTENTION_CONTEXT_IDS.recoveryAction, "Recovery", value);
+}
+
+export function documentLockItem(value: string): AttentionContextItem {
+  return item(ATTENTION_CONTEXT_IDS.documentLock, "Document lock", value);
+}
+
 export function latestCommentItem(value: string): AttentionContextItem {
   return item(ATTENTION_CONTEXT_IDS.latestComment, "Latest comment", value);
 }

src/aperture/attention-context.ts

@@ -51,8 +51,12 @@ export type IssueActorDirectory = {
 
 export type IssueDocumentSignal = {
   hasDocuments: boolean;
+  hasLockedDocuments: boolean;
   latestDocumentTitle: string | null;
   latestDocumentUpdatedAt: string | null;
+  latestDocumentLockedAt: string | null;
+  latestDocumentLockOwnerKind: "agent" | "user" | null;
+  latestDocumentLockOwnerId: string | null;
   resolvesArtifactRequest: boolean;
 };
 
@@ -273,12 +277,18 @@ export function analyzeIssueDocuments(
 ): IssueDocumentSignal {
   const latest = latestIssueDocument(documents);
   const latestUpdatedAt = toIsoString(latest?.updatedAt);
+  const latestLockedAt = toIsoString(latest?.lockedAt);
   const commentUpdatedAt = comment?.updatedAt ?? null;
+  const lockedDocuments = documents.filter((document) => !!document.lockedAt);
 
   return {
     hasDocuments: documents.length > 0,
+    hasLockedDocuments: lockedDocuments.length > 0,
     latestDocumentTitle: latest?.title ?? null,
     latestDocumentUpdatedAt: latestUpdatedAt,
+    latestDocumentLockedAt: latestLockedAt,
+    latestDocumentLockOwnerKind: latest?.lockedByAgentId ? "agent" : latest?.lockedByUserId ? "user" : null,
+    latestDocumentLockOwnerId: latest?.lockedByAgentId ?? latest?.lockedByUserId ?? null,
     resolvesArtifactRequest:
       hasIntent(analysis, "share_with_board")
       && !!latest
@@ -294,7 +304,9 @@ export function issueRecommendedMove(
   const normalized = analysis.text.replace(/\s+/g, " ").trim();
 
   if (documentSignal?.resolvesArtifactRequest) {
-    return "Monitor the review now that the memo is attached.";
+    return documentSignal.latestDocumentLockedAt
+      ? "Monitor the locked review snapshot now that the memo is attached."
+      : "Monitor the review now that the memo is attached.";
   }
 
   if (hasIntent(analysis, "resolution")) {
@@ -338,7 +350,9 @@ export function issueHeadline(
   documentSignal?: IssueDocumentSignal,
 ): string {
   if (documentSignal?.resolvesArtifactRequest) {
-    return "The requested memo appears attached, so review should be able to continue.";
+    return documentSignal.latestDocumentLockedAt
+      ? "The requested memo is attached and locked, so review should be able to continue from the preserved snapshot."
+      : "The requested memo appears attached, so review should be able to continue.";
   }
 
   if (hasIntent(analysis, "resolution")) {
@@ -386,9 +400,15 @@ export function issueWhyNow(
   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"],
+        ? documentSignal.latestDocumentLockedAt
+          ? `${documentSignal.latestDocumentTitle} was attached and locked after the request, so the missing artifact appears preserved for review.`
+          : `${documentSignal.latestDocumentTitle} was attached after the request, so the missing artifact appears resolved.`
+        : documentSignal.latestDocumentLockedAt
+          ? "A review document was attached and locked after the request, so the missing artifact appears preserved for review."
+          : "A review document was attached after the request, so the missing artifact appears resolved.",
+      factors: documentSignal.latestDocumentLockedAt
+        ? ["document attached", "document locked", "review can proceed"]
+        : ["document attached", "review can proceed"],
     };
   }