engineering-memory 0.2.2 → 0.2.5

package/install/installer.mjs

@@ -107,8 +107,29 @@ export async function installEngineeringMemory(options = {}) {
       dispatcherSection: dispatcherSections.claude,
     },
   };
+  const mcpPlans = await planMcpRegistrations({
+    selectedClients,
+    bridgeEntry,
+    nodePath,
+    apiUrl,
+    clientVersion,
+    state: existingState,
+    commandRunner,
+    clientsWereRequested: options.selectedClients !== undefined,
+  });
+  const absentClients = mcpPlans
+    .filter((plan) => plan.action === 'absent')
+    .map((plan) => plan.clientName);
+  const installedClients = selectedClients.filter(
+    (clientName) => !absentClients.includes(clientName),
+  );
+  if (installedClients.length === 0) {
+    throw new Error(
+      `None of the supported agent CLIs are on PATH: ${selectedClients.join(', ')}. Install one, then rerun the installer.`,
+    );
+  }
   const clientPlans = await Promise.all(
-    selectedClients.map(async (clientName) => {
+    installedClients.map(async (clientName) => {
       const target = clientTargets[clientName];
       return {
         clientName,
@@ -120,15 +141,6 @@ export async function installEngineeringMemory(options = {}) {
       };
     }),
   );
-  const mcpPlans = await planMcpRegistrations({
-    selectedClients,
-    bridgeEntry,
-    nodePath,
-    apiUrl,
-    clientVersion,
-    state: existingState,
-    commandRunner,
-  });
   const hookPlan = await planGitHook({
     repoRoot: options.repoRoot ? resolve(options.repoRoot) : null,
     mode: options.hookMode ?? 'cancel',
@@ -189,7 +201,8 @@ export async function installEngineeringMemory(options = {}) {
       statePath,
       skillPaths: clientPlans.map((plan) => plan.skillPath),
       dispatcherPaths: clientPlans.map((plan) => plan.dispatcherPath),
-      selectedClients,
+      selectedClients: installedClients,
+      absentClients,
       apiUrl,
       clientVersion,
       runtimePath,

package/install/mcp-registration.mjs

@@ -48,6 +48,7 @@ export async function planMcpRegistrations({
   clientVersion,
   state,
   commandRunner,
+  clientsWereRequested = true,
 }) {
   const plans = [];
   for (const clientName of selectedClients) {
@@ -55,6 +56,10 @@ export async function planMcpRegistrations({
     if (!client) throw new Error(`Unsupported client: ${clientName}`);
     const version = await commandRunner(client.executable, ['--version']);
     if (version.code !== 0) {
+      if (!clientsWereRequested && !state?.mcp?.[clientName]) {
+        plans.push({ clientName, client, action: 'absent' });
+        continue;
+      }
       throw new Error(
         `${clientName} CLI is unavailable. Install its native CLI, ensure it is on PATH, then rerun the installer. ${commandFailure(client.executable, version)}`,
       );
@@ -121,6 +126,7 @@ export async function planMcpRegistrations({
 export async function applyMcpRegistrations(plans, commandRunner, transaction) {
   const result = {};
   for (const plan of plans) {
+    if (plan.action === 'absent') continue;
     if (plan.action === 'add') {
       await addRegistration(plan, plan.registration, commandRunner);
       transaction.add(() => removeRegistration(plan, commandRunner));
@@ -211,6 +217,19 @@ function registrationFingerprint(clientName, registration) {
     .digest('hex');
 }
 
+function fingerprintBeforeClientVersion(clientName, registration) {
+  return createHash('sha256')
+    .update(
+      JSON.stringify({
+        clientName,
+        nodePath: registration.nodePath,
+        bridgeEntry: registration.bridgeEntry,
+        apiUrl: registration.apiUrl ?? null,
+      }),
+    )
+    .digest('hex');
+}
+
 function sameRegistration(left, right) {
   return (
     left?.nodePath === right.nodePath &&
@@ -462,9 +481,13 @@ function isOwnedRegistration(clientName, managed) {
       typeof managed.bridgeEntry === 'string'
     );
   }
+  if (typeof managed.apiUrl !== 'string') return false;
+  if (managed.fingerprint === registrationFingerprint(clientName, managed)) {
+    return true;
+  }
   return (
-    typeof managed.apiUrl === 'string' &&
-    managed.fingerprint === registrationFingerprint(clientName, managed)
+    managed.clientVersion === undefined &&
+    managed.fingerprint === fingerprintBeforeClientVersion(clientName, managed)
   );
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "engineering-memory",
-  "version": "0.2.2",
+  "version": "0.2.5",
   "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

@@ -439,6 +439,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 +447,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 +661,31 @@ 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 repoRoot = input.repoRoot ?? process.cwd();
+            const entries = (input.entries ?? [
+                {
+                    resourceId: input.resourceId,
+                    type: input.type,
+                    proposalId: input.proposalId,
+                    revisionId: input.revisionId,
+                    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 response = await this.dependencies.client.request(endpoints.taskReconcile, {
                 method: 'POST',
                 body: cleanJson({
                     taskId: input.taskId,
-                    resourceId: input.resourceId,
-                    type: input.type,
-                    proposalId: input.proposalId,
-                    revisionId: input.revisionId,
-                    reason,
+                    entries,
                     expectedTaskVersion: snapshot.taskVersion,
                 }),
             });
             await this.dependencies.gate.invalidateTask(input.taskId);
-            return asJsonValue({ reconciliation: response.data });
+            return asJsonValue({ reconciliations: response.data });
         });
     }
     async taskResolvePendingDelivery(input) {
@@ -784,6 +820,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, {

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,22 @@ 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. Keep in order only what moves the task version, and what genuinely waits on another answer.
+
+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