engineering-memory 0.2.3 → 0.2.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "engineering-memory",
-  "version": "0.2.3",
+  "version": "0.2.6",
   "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/git/git-inspector.js

@@ -3,6 +3,7 @@ import { isAbsolute, relative, resolve, sep } from 'node:path';
 import { assertManagedPath, canonicalPath } from '../utilities/files.js';
 import { sha256, stableStringify } from '../utilities/hash.js';
 import { NativeCommandRunner } from '../utilities/process.js';
+export const temporaryScaffoldingMarker = 'ENGINEERING-MEMORY-TEMPORARY';
 export class GitInspector {
     runner;
     constructor(runner = new NativeCommandRunner()) {
@@ -273,6 +274,42 @@ export class GitInspector {
             .map((line) => line.trim())
             .filter(Boolean);
     }
+    async temporaryScaffolding(repoRoot) {
+        const root = await this.findRoot(repoRoot);
+        const [worktree, staged] = await Promise.all([
+            this.markerMatches(root, ['--untracked'], 'worktree'),
+            this.markerMatches(root, ['--cached'], 'staged'),
+        ]);
+        const found = new Map();
+        for (const match of [...worktree, ...staged]) {
+            const identity = `${match.path}:${match.line}`;
+            const existing = found.get(identity);
+            found.set(identity, existing ? { ...existing, staged: existing.staged || match.staged } : match);
+        }
+        return [...found.values()].sort((left, right) => left.path === right.path ? left.line - right.line : left.path.localeCompare(right.path));
+    }
+    async markerMatches(root, scope, origin) {
+        const result = await this.runner.run('git', ['grep', '--no-color', '-n', '-I', '-F', ...scope, '-e', temporaryScaffoldingMarker], { cwd: root });
+        if (result.exitCode !== 0)
+            return [];
+        return result.stdout
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .flatMap((line) => {
+            const match = /^(.+?):(\d+):(.*)$/.exec(line);
+            if (!match)
+                return [];
+            return [
+                {
+                    path: normalizeGitPath(match[1]),
+                    line: Number(match[2]),
+                    text: match[3].trim().slice(0, 200),
+                    staged: origin === 'staged',
+                },
+            ];
+        });
+    }
     async gitValue(repoRoot, args) {
         const result = await this.runner.run('git', args, { cwd: repoRoot });
         const value = result.stdout.trim().split(/\r?\n/)[0];

package/runtime/dist/src/git/verification-gate.js

@@ -35,15 +35,25 @@ export class VerificationGate {
         }, this.root);
     }
     async verify(repoRoot) {
-        const [fingerprint, manifest, stagedChanges, pending] = await Promise.all([
+        const [fingerprint, manifest, stagedChanges, pending, scaffolding] = await Promise.all([
             this.git.fingerprint(repoRoot),
             this.git.manifest(repoRoot),
             this.git.stagedManifest(repoRoot),
             this.outbox.list(),
+            this.git.temporaryScaffolding(repoRoot),
         ]);
         if (pending.length > 0) {
             return { allowed: false, reason: 'offline_outbox_pending', diffHash: manifest.diffHash };
         }
+        const staged = scaffolding.filter((match) => match.staged);
+        if (staged.length > 0) {
+            return {
+                allowed: false,
+                reason: 'temporary_scaffolding_staged',
+                diffHash: manifest.diffHash,
+                details: staged.map((match) => `${match.path}:${match.line}`),
+            };
+        }
         const receipt = await readJson(this.pathFor(fingerprint), this.root);
         if (!receipt) {
             return { allowed: false, reason: 'task_verify_required', diffHash: manifest.diffHash };

package/runtime/dist/src/index.js

@@ -14,6 +14,7 @@ import { BridgeService } from './runtime/bridge-service.js';
 import { OfflineOutbox } from './runtime/offline-outbox.js';
 import { ActiveContextStore } from './runtime/active-context-store.js';
 import { RepositoryDecisionStore } from './runtime/repository-decision-store.js';
+import { ShadowNoticeStore } from './runtime/shadow-notice-store.js';
 import { UpdateChoiceStore } from './runtime/update-choice-store.js';
 import { PrincipalStateGuard } from './runtime/principal-state.js';
 export function createBridgeService() {
@@ -43,6 +44,7 @@ export function createBridgeService() {
     const activeContexts = new ActiveContextStore(stateRoot);
     const repositoryDecisions = new RepositoryDecisionStore(stateRoot);
     const updateChoices = new UpdateChoiceStore(stateRoot);
+    const shadowNotices = new ShadowNoticeStore(stateRoot);
     const gate = new VerificationGate(stateRoot, git, outbox);
     const principalState = new PrincipalStateGuard(stateRoot, credentials, cache, outbox, activeContexts, gate);
     return new BridgeService({
@@ -56,6 +58,7 @@ export function createBridgeService() {
         activeContexts,
         repositoryDecisions,
         updateChoices,
+        shadowNotices,
         clientVersion: config.clientVersion,
         principalState,
     });

package/runtime/dist/src/mcp/tool-definitions.js

@@ -47,6 +47,7 @@ export const engineeringMemoryToolNames = [
     'session.entry',
     'session.set_decision',
     'session.decline_update',
+    'session.answer_shadow_notice',
     'session.bootstrap',
     'session.resume',
     'context.prepare_change',
@@ -76,6 +77,13 @@ export const engineeringMemoryToolNames = [
     'auth.signin_browser',
     'auth.logout',
 ];
+const reconciliationEntry = z.object({
+    resourceId: z.string().min(1),
+    type: z.enum(['approved_revision', 'no_semantic_memory_change']),
+    proposalId: z.string().optional(),
+    revisionId: z.string().optional(),
+    reason: z.string().optional(),
+});
 export function registerEngineeringMemoryTools(server, service) {
     server.registerTool('session.entry', {
         description: 'The first call of every session in a repository, before answering anything about the project. Reports whether the user is signed in, whether this repository is bound, what this user decided about it last time, and the one thing to do now. A repository the user switched Engineering Memory off in reports that, and is left alone.',
@@ -92,6 +100,16 @@ export function registerEngineeringMemoryTools(server, service) {
         description: 'Record that the user turned down the available client update. Call it only when they say no. The same version is never offered again; a newer one is a new question. A required update is not declinable and must not be recorded here.',
         inputSchema: z.object({}),
     }, async () => toolResult(await service.sessionDeclineUpdate()));
+    server.registerTool('session.answer_shadow_notice', {
+        description: 'Record that the user has answered a shadowed rule notice: the record in force overrides a wider rule that has since changed, and they chose whether to read the new text or keep the override. Call it only after they answer. The same revision of that wider rule is never raised again; a later revision is a new question.',
+        inputSchema: z.object({
+            resourceId: z.string().describe('The wider rule that is being hidden.'),
+            revisionNumber: z
+                .number()
+                .int()
+                .describe('The revision of that rule the user was told about.'),
+        }),
+    }, async (input) => toolResult(await service.sessionAnswerShadowNotice(input)));
     server.registerTool('session.bootstrap', {
         description: 'Authenticate, resolve the repository project, open or resume a write or read-only task, and load mandatory engineering context before planning.',
         inputSchema: z.object({
@@ -247,30 +265,52 @@ export function registerEngineeringMemoryTools(server, service) {
         }),
     }, async (input) => toolResult(await service.taskSelfReview(input)));
     server.registerTool('task.reconcile', {
-        description: 'Reconcile each changed screen or component with an approved revision or an explicit no-semantic-memory-change reason.',
+        description: 'Reconcile changed screens and components with an approved revision or an explicit no-semantic-memory-change reason. Pass every record the task touched as `entries` in one call rather than calling once per record; the whole set is applied together and rejected together.',
         inputSchema: z
             .object({
             repoRoot: optionalRepoRoot,
             taskId: z.string().min(1),
-            resourceId: z.string().min(1),
-            type: z.enum(['approved_revision', 'no_semantic_memory_change']),
+            entries: z.array(reconciliationEntry).min(1).max(50).optional(),
+            resourceId: z.string().min(1).optional(),
+            type: z.enum(['approved_revision', 'no_semantic_memory_change']).optional(),
             proposalId: z.string().optional(),
             revisionId: z.string().optional(),
             reason: z.string().optional(),
         })
             .superRefine((value, context) => {
-            if (value.type === 'approved_revision' && (!value.proposalId || !value.revisionId)) {
+            const entries = value.entries ??
+                (value.resourceId && value.type
+                    ? [
+                        {
+                            resourceId: value.resourceId,
+                            type: value.type,
+                            proposalId: value.proposalId,
+                            revisionId: value.revisionId,
+                            reason: value.reason,
+                        },
+                    ]
+                    : null);
+            if (!entries) {
                 context.addIssue({
                     code: 'custom',
-                    message: 'Approved reconciliation requires proposalId and revisionId',
+                    message: 'Reconciliation requires entries, or a single resourceId and type',
                 });
+                return;
             }
-            if (value.type === 'no_semantic_memory_change' &&
-                (!value.reason || value.reason.length < 8)) {
-                context.addIssue({
-                    code: 'custom',
-                    message: 'No-semantic-change reconciliation requires a reason of at least 8 characters',
-                });
+            for (const entry of entries) {
+                if (entry.type === 'approved_revision' && (!entry.proposalId || !entry.revisionId)) {
+                    context.addIssue({
+                        code: 'custom',
+                        message: 'Approved reconciliation requires proposalId and revisionId',
+                    });
+                }
+                if (entry.type === 'no_semantic_memory_change' &&
+                    (!entry.reason || entry.reason.length < 8)) {
+                    context.addIssue({
+                        code: 'custom',
+                        message: 'No-semantic-change reconciliation requires a reason of at least 8 characters',
+                    });
+                }
             }
         }),
     }, async (input) => toolResult(await service.taskReconcile(input)));

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 () => {
@@ -439,6 +457,7 @@ export class BridgeService {
                     ...(preparedData?.lease ? { activeLease: preparedData.lease } : {}),
                 });
             }
+            const shadowed = await this.unansweredShadowNotices(response.data);
             return asJsonValue({
                 ...objectOrEmpty(response.data),
                 editLeaseGranted: true,
@@ -446,9 +465,42 @@ export class BridgeService {
                 strictVerifyBlocked: false,
                 backendSource: responseSource,
                 repository: publicRepository(repository),
+                shadowedRuleNotices: shadowed,
+                ...(shadowed.length > 0
+                    ? {
+                        nextAction: 'A record this change relies on overrides a wider rule that has changed since the override was written. Say so in this reply, name the wider rule, and ask whether to read its new text or keep the override. Record the answer with session.answer_shadow_notice so it is not raised again until that rule moves.',
+                    }
+                    : {}),
             });
         });
     }
+    async sessionAnswerShadowNotice(input) {
+        return await this.execute(async () => {
+            await this.dependencies.shadowNotices.answer(input.resourceId, input.revisionNumber);
+            return asJsonValue({ resourceId: input.resourceId, answered: true });
+        });
+    }
+    async unansweredShadowNotices(data) {
+        const shadowed = objectValue(objectValue(data)?.shadowed);
+        if (!shadowed)
+            return [];
+        const notices = Object.values(shadowed)
+            .flatMap((entry) => (Array.isArray(entry) ? entry : []))
+            .flatMap((entry) => {
+            const hidden = objectValue(entry);
+            const resourceId = hidden?.resourceId;
+            const resourceKey = hidden?.resourceKey;
+            const revisionNumber = hidden?.currentRevisionNumber;
+            return typeof resourceId === 'string' &&
+                typeof resourceKey === 'string' &&
+                typeof revisionNumber === 'number'
+                ? [{ resourceId, resourceKey, revisionNumber }]
+                : [];
+        });
+        const unanswered = await this.dependencies.shadowNotices.unanswered(notices);
+        const wanted = new Set(unanswered.map((notice) => notice.resourceId));
+        return notices.filter((notice) => wanted.has(notice.resourceId));
+    }
     async contextRefresh(input) {
         return await this.execute(async () => {
             const response = await this.dependencies.client.request(endpoints.contextRefresh, {
@@ -627,29 +679,47 @@ export class BridgeService {
     }
     async taskReconcile(input) {
         return await this.execute(async () => {
-            const reason = normalizePersistentInput(input.reason, input.repoRoot ?? process.cwd());
-            assertSafeToPersist(cleanJson({
-                resourceId: input.resourceId,
-                type: input.type,
-                proposalId: input.proposalId,
-                revisionId: input.revisionId,
-                reason,
-            }));
-            const snapshot = await this.activeTaskSnapshot(input.taskId, undefined, input.repoRoot);
-            const response = await this.dependencies.client.request(endpoints.taskReconcile, {
-                method: 'POST',
-                body: cleanJson({
-                    taskId: input.taskId,
+            const repoRoot = input.repoRoot ?? process.cwd();
+            const entries = (input.entries ?? [
+                {
                     resourceId: input.resourceId,
                     type: input.type,
                     proposalId: input.proposalId,
                     revisionId: input.revisionId,
-                    reason,
-                    expectedTaskVersion: snapshot.taskVersion,
-                }),
+                    reason: input.reason,
+                },
+            ]).map((entry) => ({
+                ...entry,
+                reason: normalizePersistentInput(entry.reason, repoRoot),
+            }));
+            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);
-            return asJsonValue({ reconciliation: response.data });
+            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,
+            });
+            return asJsonValue({ reconciliations: response.data });
         });
     }
     async taskResolvePendingDelivery(input) {
@@ -784,6 +854,20 @@ export class BridgeService {
                         diffHash: repository.git.diffHash,
                     });
                 }
+                const scaffolding = await this.dependencies.repositories.git.temporaryScaffolding(repository.repoRoot);
+                if (scaffolding.length > 0) {
+                    return asJsonValue({
+                        verified: false,
+                        reason: 'temporary_scaffolding_present',
+                        temporaryScaffolding: scaffolding.map((match) => ({
+                            location: `${match.path}:${match.line}`,
+                            text: match.text,
+                            staged: match.staged,
+                        })),
+                        nextAction: 'Temporary code written to reach or force a path is still in the working tree. Remove every listed line and restore what it replaced, then verify again. A manipulation that ships is a defect, so this is checked in the tree rather than taken on trust.',
+                        diffHash: repository.git.diffHash,
+                    });
+                }
                 let taskChangedPaths = [];
                 let taskChanges = [];
                 const snapshotResponse = await this.dependencies.client.request(endpoints.sessionResume, {
@@ -1313,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,
@@ -1376,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/runtime/dist/src/runtime/shadow-notice-store.js

@@ -0,0 +1,26 @@
+import { join } from 'node:path';
+import { readJson, writeJson } from '../utilities/files.js';
+export class ShadowNoticeStore {
+    path;
+    root;
+    constructor(stateRoot) {
+        this.root = join(stateRoot, 'client');
+        this.path = join(this.root, 'shadow-notices.json');
+    }
+    async unanswered(pending) {
+        const record = await readJson(this.path, this.root);
+        const answered = record?.answered ?? {};
+        return pending.filter((notice) => (answered[notice.resourceId] ?? -1) < notice.revisionNumber);
+    }
+    async answer(resourceId, revisionNumber) {
+        const existing = await readJson(this.path, this.root);
+        const record = {
+            schemaVersion: 1,
+            answered: { ...(existing?.answered ?? {}), [resourceId]: revisionNumber },
+            updatedAt: new Date().toISOString(),
+        };
+        await writeJson(this.path, record, this.root);
+        return record;
+    }
+}
+//# sourceMappingURL=shadow-notice-store.js.map

package/skill/references/lifecycle.md

@@ -33,8 +33,24 @@ A request can be as short as "add the KYC flow from Figma". That is enough, and
 
 Then propose the `flow_logic` record and stop. The plan is not a message in the chat; it is the proposal, and the user approving it is the approval. Do not write the second screen before that approval exists — a flow's shape replicated across six screens costs six times as much to undo, and verification refuses a task that adds several screens without an approved flow record reconciled to it.
 
+### A task that reports a defect
+
+Settle first whether the report is about what the user sees or where they go. If it is, the
+design carries the intended behaviour and the code carries the actual one, so read both
+before naming a cause: open the frame the report starts from, follow its prototype link to
+the destination the design intends, and state the divergence. Never repoint navigation at a
+target inferred only from surrounding code. Carry both node ids into the discovery
+checkpoint as evidence. A defect in a calculation, a response shape or a service has no
+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.
+
+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.
+
 Do not write task Markdown files directly. The bridge owns event IDs, expected task versions, atomic projections, outbox state, and synchronization.
 
 ## Change Preparation

package/skill/references/questionnaires.md

@@ -70,9 +70,28 @@ When the user names a different Figma file or link, treat it as a correction to
 
 ## Running the Application
 
-When the change is something a person sees or interacts with and this environment can run the application, ask before launching it rather than starting on your own. A run occupies the user's machine, can take minutes, and they may be using it. Say what you would exercise and what you are looking for, so the answer is about the work rather than about the tooling.
+When the change is something a person sees or interacts with and this environment can run the application, ask before launching it rather than starting on your own. A run occupies the user's machine and their time, and the answer should be theirs.
 
-Ask again nothing when they decline. Verify what you can without it and state in the handoff that the flow was not exercised in a running application.
+Ask with the price attached. Say what would be exercised, what is being looked for, and roughly how long it takes, and carry a recommendation rather than leaving the choice bare. For a change confined to one screen with no service on the path, recommend against running and say what will be verified instead — a five-minute change should not cost an hour of driving the application. For a flow that spans several screens, or anything touching a service, recommend running, because that is exactly what reading cannot answer.
+
+When they decline, do not raise it again for this task. Verify what you can without it and state in the handoff that the flow was not exercised in a running application.
+
+## Design Reading
+
+Before proposing a flow record or naming a cause from the design, put the reading in front of
+the user: the frames found, their node ids, and the order the prototype links imply. Ask
+whether that is the flow and where it is entered from. A prototype link is evidence, not a
+decision, and the design cannot say which entry point the product intends. Never skip
+straight from what the design showed to a proposal.
+
+## Shadowed Product Rule
+
+When `context.prepare_change` returns `shadowedRuleNotices`, a record this change relies on
+overrides a wider rule that has changed since the override was written. Say so in the same
+reply, name the wider rule, and ask whether to read its new text or keep the override. The
+override still wins if that is the answer — it just stops being silent. Record the answer
+with `session.answer_shadow_notice`, which keeps the same revision from being raised again;
+a later revision of that rule is a new question.
 
 ## Correction Scope