@tomismeta/paperclip-aperture 0.4.1 → 0.4.3

package/README.md

@@ -2,7 +2,7 @@
 
 # Paperclip Aperture
 
-**The live attention layer for Paperclip, powered by Aperture's deterministic attention engine.**
+**The live attention layer for Paperclip, combining Aperture Core continuity with Paperclip-native operator policy.**
 
 [![paperclip-aperture npm](https://img.shields.io/npm/v/%40tomismeta%2Fpaperclip-aperture?label=paperclip-aperture&color=2563eb)](https://www.npmjs.com/package/@tomismeta/paperclip-aperture)
 [![aperture github](https://img.shields.io/badge/aperture-tomismeta%2Faperture-18181b)](https://github.com/tomismeta/aperture)
@@ -13,7 +13,7 @@
 <p></p>
 </div>
 
-Paperclip Aperture adds a Focus surface to Paperclip that deterministically ranks approvals, issue activity, and other human-facing events into `now`, `next`, and `ambient`.
+Paperclip Aperture adds a Focus surface to Paperclip that turns approvals, issue activity, and other human-facing signals into `now`, `next`, and `ambient`.
 
 It is designed as a live attention layer, not an inbox clone:
 
@@ -66,22 +66,35 @@ 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
+- bounded focus hold while the operator is actively working the current `now` item, so `Show context` and inline commenting do not immediately lose the thread beneath them
 - 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
+- a plugin-local semantic mapping and policy layer that interprets Paperclip issue, approval, and agent signals before composing the final Focus view
 - 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
+- worker-owned display composition that merges live Paperclip approvals into the final Focus snapshot before the UI sees it
+- bounded Core trace export and sparse Focus action telemetry/activity writes for replay and debugging
+- live Core diagnostics export, including signal summaries, memory profile snapshots, and current-session attention state for offline analysis
+- worker-bridged operator signals for Focus page presence, active-item viewing, and context expansion so Aperture Core sees real interaction evidence instead of the plugin faking a second attention model
+- overlay diagnostics export that compares `core -> reconciled -> display` so the plugin's host-policy contribution is inspectable without confusing it for Core judgment
 - a sidebar entry, page, and dashboard widget
+- worker-side host read caching for issue/comment/document/agent reconciliation, with fresh summary/export reads when you need the latest host truth
+- bounded per-company Core sessions with health reporting so the worker does not grow without limit during normal multi-company use
+- replayable operator signal entries and overlay-response ledger entries so Focus actions remain auditable even when a frame came from the display adapter rather than Core
+- decision-owner metadata on reconciled/display frames so exports can distinguish Core judgment, Paperclip reconciliation, approval overlays, and final display promotion
+- a corpus-backed `issue-intelligence` regression check in CI so heuristic edits stay inspectable
+- rollback-safe local mutations that restore the last durable attention state if persistence fails
+- versioned persisted attention envelopes with an explicit migration path for older schemas
 
 ## Explainability
 
 Focus is meant to be more legible than a smart inbox.
 
-The current `0.3.x` explainability slice keeps reasoning attached to the cards you are already acting on:
+The current `0.4.x` 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
@@ -99,33 +112,40 @@ The intent is not to expose every internal scoring detail. It is to help an oper
 
 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.
+It is an SDK-first integration with explicit plugin-side host policy. Aperture Core handles continuity, replay, and global attention mechanics; the plugin adds Paperclip-specific candidate generation, approval overlays, and operator language where the host can know more than Core alone.
 
-For `0.3.x`, the boundary works like this:
+For `0.4.x`, the boundary works like this:
 
-- the plugin worker owns Aperture ingestion, replay, review state, and display composition
+- the plugin worker owns Aperture ingestion, replay, review state, display composition, reconciliation caching, and Paperclip-native policy overlays
+- the final Focus view is therefore Core-backed but not Core-only today: the plugin still owns some Paperclip-specific candidate and lane policy where the host has facts Core cannot infer by itself
 - Paperclip remains the system of record for issue and approval writes
-- approval transport still goes through same-origin Paperclip HTTP APIs from the plugin UI because the current plugin SDK does not expose approval read/write clients
-- the plugin intentionally publishes `ApertureEvent`s today, using a Paperclip-specific semantic mapping layer and ontology, rather than switching fully to `SourceEvent`
-- that semantic layer includes reusable intent detectors, actor resolution against real company agents, downstream blocker extraction, and shared operator-language generation inside the plugin
+- approval transport now goes through a worker-side Paperclip adapter using the plugin SDK HTTP client, so the browser UI no longer talks to host approval APIs directly
+- the plugin preserves Paperclip source facts as `SourceEvent`s where the Core contract supports them, while still exporting the normalized `ApertureEvent` used for replay/debug
+- that semantic layer includes reusable intent detectors, actor resolution against real company agents, downstream blocker extraction, explicit rule ids for matched issue heuristics, and shared operator-language generation inside the plugin
+- typed Paperclip issue blocker relations are preserved as Focus context/provenance/metadata so Aperture has better dependency facts without the plugin inventing dependency routing
+- `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.4.0`](https://www.npmjs.com/package/@tomismeta/aperture-core).
+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).
+
+If your Paperclip host is not running at the default local address, set the plugin config field `paperclipApiBase` so the worker-side approval adapter can reach the correct host API.
 
 ## Development
 
 ```bash
 pnpm install
-pnpm typecheck
-pnpm test
-pnpm build
+pnpm verify
 ```
 
 Before releasing, run:
 
 ```bash
+pnpm clean
 pnpm release:check
 ```
 
+`pnpm verify` runs typecheck, tests, the issue-intelligence eval corpus, a production build, and bundle-size checks.
+
 For a live local Paperclip smoke test, start Paperclip first:
 
 ```bash
@@ -156,6 +176,9 @@ Then open `http://127.0.0.1:3100/APE/aperture` and verify:
 
 - Plugin on npm: [`@tomismeta/paperclip-aperture`](https://www.npmjs.com/package/@tomismeta/paperclip-aperture)
 - Roadmap and releasing: [docs/ROADMAP.md](./docs/ROADMAP.md)
+- Architecture remediation note: [docs/AUDIT-REMEDIATION-2026-04.md](./docs/AUDIT-REMEDIATION-2026-04.md)
+- May 2026 audit remediation note: [docs/AUDIT-REMEDIATION-2026-05.md](./docs/AUDIT-REMEDIATION-2026-05.md)
+- Contribution guide: [CONTRIBUTING.md](./CONTRIBUTING.md)
 - Aperture GitHub repo: [tomismeta/aperture](https://github.com/tomismeta/aperture)
 - Aperture Core on npm: [`@tomismeta/aperture-core`](https://www.npmjs.com/package/@tomismeta/aperture-core)
 - Paperclip GitHub repo: [paperclipai/paperclip](https://github.com/paperclipai/paperclip)

package/dist/manifest.js

@@ -1,73 +1 @@
-const manifest = {
-  id: "tomismeta.paperclip-aperture",
-  apiVersion: 1,
-  version: "0.4.1",
-  displayName: "Paperclip Aperture",
-  description: "The live attention layer for Paperclip, powered by Aperture's deterministic attention engine.",
-  author: "@tomismeta",
-  categories: ["automation", "ui"],
-  capabilities: [
-    "events.subscribe",
-    "agents.read",
-    "issues.read",
-    "issue.comments.read",
-    "issue.comments.create",
-    "issue.documents.read",
-    "activity.log.write",
-    "plugin.state.read",
-    "plugin.state.write",
-    "telemetry.track",
-    "ui.dashboardWidget.register",
-    "ui.page.register",
-    "ui.sidebar.register"
-  ],
-  entrypoints: {
-    worker: "./dist/worker.js",
-    ui: "./dist/ui"
-  },
-  instanceConfigSchema: {
-    type: "object",
-    properties: {
-      captureIssueLifecycle: {
-        type: "boolean",
-        title: "Capture Issue Lifecycle",
-        default: true,
-        description: "Turn issue creation and update events into Aperture status signals."
-      },
-      captureRunFailures: {
-        type: "boolean",
-        title: "Capture Run Failures",
-        default: true,
-        description: "Turn failed agent runs into high-salience attention events."
-      }
-    }
-  },
-  ui: {
-    slots: [
-      {
-        type: "page",
-        id: "attention-page",
-        displayName: "Focus",
-        exportName: "AttentionPage",
-        routePath: "aperture"
-      },
-      {
-        type: "sidebar",
-        id: "attention-sidebar-link",
-        displayName: "Focus",
-        exportName: "AttentionSidebarLink"
-      },
-      {
-        type: "dashboardWidget",
-        id: "attention-widget",
-        displayName: "Focus",
-        exportName: "DashboardWidget"
-      }
-    ]
-  }
-};
-var manifest_default = manifest;
-export {
-  manifest_default as default
-};
-//# sourceMappingURL=manifest.js.map
+const e={id:"tomismeta.paperclip-aperture",apiVersion:1,version:"0.4.3",displayName:"Paperclip Aperture",description:"The live attention layer for Paperclip, combining Aperture Core continuity with Paperclip-native operator policy.",author:"@tomismeta",categories:["automation","ui"],capabilities:["events.subscribe","http.outbound","agents.read","issues.read","issue.relations.read","issue.comments.read","issue.comments.create","issue.documents.read","activity.log.write","plugin.state.read","plugin.state.write","telemetry.track","ui.dashboardWidget.register","ui.page.register","ui.sidebar.register"],entrypoints:{worker:"./dist/worker.js",ui:"./dist/ui"},instanceConfigSchema:{type:"object",properties:{captureIssueLifecycle:{type:"boolean",title:"Capture Issue Lifecycle",default:!0,description:"Turn issue creation and update events into Aperture status signals."},captureRunFailures:{type:"boolean",title:"Capture Run Failures",default:!0,description:"Turn failed agent runs into high-salience attention events."},paperclipApiBase:{type:"string",title:"Paperclip API Base",default:"http://127.0.0.1:3100",description:"Base URL the worker should use for Paperclip approval reads and writes when the plugin SDK lacks a first-class approval client."}}},ui:{slots:[{type:"page",id:"attention-page",displayName:"Focus",exportName:"AttentionPage",routePath:"aperture"},{type:"sidebar",id:"attention-sidebar-link",displayName:"Focus",exportName:"AttentionSidebarLink"},{type:"dashboardWidget",id:"attention-widget",displayName:"Focus",exportName:"DashboardWidget"}]}};var t=e;export{t as default};