release: prepare paperclip-aperture 0.2.2

Author: tomismeta

.gitignore

@@ -3,3 +3,4 @@ node_modules
 .paperclip-sdk
 *.tgz
 .DS_Store
+tmp/

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
 

docs/RELEASE-0.2.2.md

@@ -0,0 +1,40 @@
+# paperclip-aperture 0.2.2
+
+`0.2.2` keeps the `0.2.x` product surface intact while tightening the semantic bridge into Aperture Core and making review flows more document-aware.
+
+## Highlights
+
+- Added richer semantic continuity hints on mapped issue events
+- Added better semantic confidence shaping for plugin-authored issue semantics
+- Added document-aware review interpretation for memo/spec-backed issues
+- Added `issue.documents.read` support to the plugin worker
+
+## What Changed
+
+- issue events now project clearer core-shaped relation hints such as:
+  - `same_issue`
+  - `supersedes`
+  - `resolves`
+- the plugin no longer over-stamps confidence on approval and failure paths when core can infer it from the canonical event shape
+- reconciliation now checks issue documents for blocked and `in_review` issues
+- if a review-blocking memo/spec request has been satisfied by a later document attachment, Focus downgrades that item from interruptive review work into monitor-only follow-up
+
+## Why This Matters
+
+- better semantic relation hints improve continuity and episode-tracking behavior in Aperture Core without forcing the plugin to abandon its Paperclip-specific ontology
+- document-aware review handling makes Focus less stale in real Paperclip workflows where the critical artifact lives on the issue, not just in comments
+- the architectural line remains the same:
+  - Aperture Core owns bounded semantic substrate and attention judgment
+  - paperclip-aperture owns Paperclip-specific interpretation and operator language
+
+## Dependency Snapshot
+
+- `@tomismeta/aperture-core@^0.4.0`
+- `@paperclipai/plugin-sdk@2026.318.0`
+
+## Validation
+
+- `pnpm test`
+- `pnpm typecheck`
+- `pnpm build`
+- live smoke-tested against a running local Paperclip instance, including document attach -> ambient downgrade behavior

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.",

src/aperture/event-mapper.ts

@@ -18,6 +18,10 @@ import {
   linkedIssuesItem,
   requestedAmountItem,
 } from "./attention-context.js";
+import {
+  analyzeIssueTextSemantics,
+  issueRelationTarget,
+} from "./issue-intelligence.js";
 
 type ExtendedPluginEventType =
   | PluginEvent["eventType"]
@@ -160,10 +164,6 @@ function issueDisplayTitle(event: MappablePluginEvent, fallback: string): string
   return fallback;
 }
 
-function issueRelationTarget(issueId: string): string {
-  return `issue:${issueId}`;
-}
-
 function relationHintsForIssueTargets(issueIds: string[] | undefined): SourceEvent["semanticHints"] | undefined {
   if (!issueIds || issueIds.length === 0) return undefined;
 
@@ -175,18 +175,38 @@ function relationHintsForIssueTargets(issueIds: string[] | undefined): SourceEve
   };
 }
 
+function issueSemanticText(payload: unknown): string {
+  return [
+    readPayloadString(payload, "bodySnippet"),
+    readPayloadString(payload, "summary"),
+    readPayloadString(payload, "description"),
+    readPayloadString(payload, "title"),
+    readPayloadString(payload, "issueTitle"),
+  ]
+    .filter((value): value is string => !!value)
+    .join("\n");
+}
+
 function issueSemanticHints(event: MappablePluginEvent): SourceEvent["semanticHints"] | undefined {
-  return event.entityType === "issue" && event.entityId
-    ? relationHintsForIssueTargets([event.entityId])
-    : undefined;
+  if (event.entityType !== "issue" || !event.entityId) return undefined;
+
+  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: boolean,
   linkedIssueIds: string[] | undefined,
 ): SourceEvent["semanticHints"] {
   return {
-    confidence: "high",
     whyNow: approvalBlockingWhyNow(budgetOverride),
     factors: budgetOverride
       ? ["budget stop", "approval", "operator decision"]
@@ -197,7 +217,6 @@ function approvalSemanticHints(
 
 function pendingApprovalSemanticHints(): SourceEvent["semanticHints"] {
   return {
-    confidence: "high",
     whyNow: pendingApprovalEventWhyNow(),
     factors: ["pending approval"],
   };
@@ -206,7 +225,6 @@ function pendingApprovalSemanticHints(): SourceEvent["semanticHints"] {
 function runFailureSemanticHints(): SourceEvent["semanticHints"] {
   return {
     intentFrame: "failure",
-    confidence: "high",
     whyNow: runFailedWhyNow(),
     factors: ["run failed", "operator review"],
   };