engineering-memory 0.2.5 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "engineering-memory",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "description": "Installs the Engineering Memory skill and its local MCP bridge. Sign in after installing; your organization and project are resolved from your account.",
   "license": "UNLICENSED",
   "type": "module",

package/runtime/dist/src/runtime/bridge-service.js

@@ -25,8 +25,26 @@ export const validationIds = [
 export class BridgeService {
     dependencies;
     taskQueues = new Map();
+    deferDeliveries;
+    backgroundDelivery = Promise.resolve();
     constructor(dependencies) {
         this.dependencies = dependencies;
+        this.deferDeliveries = dependencies.deferDeliveries ?? true;
+    }
+    deliverInBackground() {
+        if (!this.deferDeliveries)
+            return;
+        this.backgroundDelivery = this.backgroundDelivery.then(async () => {
+            try {
+                await this.flushOutbox();
+            }
+            catch {
+                return;
+            }
+        });
+    }
+    async settleDeliveries() {
+        await this.backgroundDelivery;
     }
     async sessionBootstrap(input) {
         return await this.execute(async () => {
@@ -676,15 +694,31 @@ export class BridgeService {
             }));
             assertSafeToPersist(cleanJson({ entries }));
             const snapshot = await this.activeTaskSnapshot(input.taskId, undefined, input.repoRoot);
+            const body = cleanJson({
+                taskId: input.taskId,
+                entries,
+                expectedTaskVersion: snapshot.taskVersion,
+            });
+            await this.dependencies.gate.invalidateTask(input.taskId);
+            if (this.deferDeliveries) {
+                const queued = await this.dependencies.outbox.enqueue({
+                    operation: 'task.reconcile',
+                    method: 'POST',
+                    path: endpoints.taskReconcile,
+                    body,
+                });
+                this.deliverInBackground();
+                return asJsonValue({
+                    reconciled: entries.map((entry) => entry.resourceId),
+                    queued: true,
+                    outboxId: queued.id,
+                    deliveryStatus: 'pending',
+                });
+            }
             const response = await this.dependencies.client.request(endpoints.taskReconcile, {
                 method: 'POST',
-                body: cleanJson({
-                    taskId: input.taskId,
-                    entries,
-                    expectedTaskVersion: snapshot.taskVersion,
-                }),
+                body,
             });
-            await this.dependencies.gate.invalidateTask(input.taskId);
             return asJsonValue({ reconciliations: response.data });
         });
     }
@@ -1363,7 +1397,10 @@ export class BridgeService {
             assertSafeToPersist(cleanJson(safeInput));
             return await this.taskExclusive(input.taskId, async () => {
                 await this.recoverJournalOutbox(input.projectId, input.taskSlug);
-                await this.flushOutbox();
+                if (this.deferDeliveries)
+                    this.deliverInBackground();
+                else
+                    await this.flushOutbox();
                 const journalInput = {
                     eventId: idempotencyKey,
                     taskId: input.taskId,
@@ -1426,7 +1463,8 @@ export class BridgeService {
                     await this.dependencies.activeContexts.updateTaskSnapshot(input.taskId, expectedTaskVersion + 1, pointer.lastSequence + 1);
                 }
                 const predecessorEntries = taskEntries.filter((entry) => entry.id !== queued.id);
-                if (predecessorEntries.length > 0) {
+                if (predecessorEntries.length > 0 || this.deferDeliveries) {
+                    this.deliverInBackground();
                     return asJsonValue({
                         local: { directory: staged.directory, applied: staged.applied },
                         queued: true,

package/skill/references/lifecycle.md

@@ -26,7 +26,7 @@ A request can be as short as "add the KYC flow from Figma". That is enough, and
 
 1. The Figma address arrives in the core pack as the `figma_reference` record. Never ask where the design lives; read it. If the user names a different file, that is a correction to that record — propose the revision and ask for approval in the same reply, so the next session already knows.
 2. Ask for existing flows with `memory.query` naming the `flow_logic` kind. If the flow is already recorded, read it and its history before touching anything.
-3. Read the flow in Figma: which frames belong to it, the order its prototype links imply, and the node id of every screen. A file-level link is orientation, not evidence.
+3. Read the flow in Figma, at orientation depth only: which frames belong to it, the order its prototype links imply, and the node id of every screen. A file-level link is orientation, not evidence. Stop there — geometry, fills, typography and tokens belong to the screen being built, read at the moment it is built, not gathered for the whole flow up front. Read this yourself rather than delegating it; nothing else can proceed until it is answered, so a second agent only adds the wait.
 4. Read what surrounds it — the screen records the flow starts from and returns to, the navigation contract, the trackers that already exist — and pull `memory.history` wherever the header shows earlier work or a run of corrections.
 5. Decide the entry point, the order, whether a tracker is needed and exactly what it carries, and where the flow ends.
 6. Ask the user what neither Figma nor memory can answer. Where a flow is entered from and what abandoning it halfway does are almost never in the design. Never invent them, and never invent the content of a document the flow displays.
@@ -45,7 +45,9 @@ answer in the design; do not spend the read there.
 
 Do not pull history for everything. Pull it for the records the task actually touches, and for anything the header shows a surprising number of corrections on. Record `task.checkpoint` with type `discovery` and update STATE, DECISIONS, DISCOVERY, and HANDOFF projections through the bridge.
 
-Send calls that do not feed each other in one batch rather than one at a time: reads of any kind, and proposals for different records. Reconcile every record the task touched in a single `task.reconcile` call with `entries`, not one call per record. Keep in order only what moves the task version, and what genuinely waits on another answer.
+Send calls that do not feed each other in one batch rather than one at a time: reads of any kind, and proposals for different records. Reconcile every record the task touched in a single `task.reconcile` call with `entries`, not one call per record.
+
+Checkpoints, recorded corrections and reconciliations return before the backend has them, reporting `deliveryStatus: 'pending'` with the task version they will occupy. That is a completed call, not a pending one: the journal is already durable, delivery is already under way, and `task.verify` refuses while anything remains undelivered. Do not wait for it, poll it, or send it again. Wait only for what the next step uses — a proposal's identifiers, an approval's revision, a prepared lease, and verification itself.
 
 Temporary code written to reach or force a path — a pinned state, a fixed service response, a jump straight to the screen — is allowed and expected, carries the marker `ENGINEERING-MEMORY-TEMPORARY` with its reason, and is removed before verification. `task.verify` refuses while any marker is in the tree and names every line, and the commit gate refuses while one is staged.
 

package/skill/references/memory-updates.md

@@ -22,4 +22,12 @@ Screen logic is canonical in the backend. A screen revision should cover purpose
 
 Component mappings should cover the Flutter symbol and path, public API, purpose, states, design tokens, responsive behavior, Figma file and exact node IDs, assets, usage guidance, tests, selectors, and evidence. Mark missing or partial Figma evidence instead of inventing node IDs.
 
+A backend project records three kinds instead of screens and components, and which kinds a project has is declared in its project profile rather than assumed.
+
+A `module_logic` record covers one resource: what it is for, the entities it owns, the endpoints it exposes, the guards that protect them, the background jobs and queues it runs, what it depends on and why that dependency exists.
+
+A `data_model` record covers one entity: its columns and their types, its relations, what it inherits from the base entity, and every index it declares **with the query that index exists to serve**. An index nobody can name a query for is reported as a finding rather than recorded as a fact.
+
+An `api_endpoint` record covers one route and is the surface a client binds to: method and path, the request DTO, the response DTO, the guards, the error codes it can return, the localization keys it uses, its pagination shape, and which client consumes it. When a linked project exists, these are the records that cross to it, so they are written for a reader on the other side of the wire rather than for the person who wrote the controller.
+
 Do not send full source trees, generated files, vendor assets, raw diffs, credentials, or user data as memory content. Prefer relative paths, symbols, hashes, contract summaries, exact approved Figma identifiers, and bounded task-specific evidence.