engineering-memory 0.1.0 → 0.2.0

package/bin/engineering-memory.mjs

@@ -1,14 +1,10 @@
 #!/usr/bin/env node
 import { createRequire } from 'node:module';
-import { cp, mkdir, mkdtemp, rm } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
+import { rm } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import {
-  exists,
-  readJson,
-  resolveProductionPackagePaths,
-} from '../install/files.mjs';
+import { exists, readJson } from '../install/files.mjs';
+import { stageBridgeRuntime } from '../lib/stage-runtime.mjs';
 import { runInstaller } from '../install/cli.mjs';
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
@@ -33,42 +29,6 @@ Choose the hook mode through the Codex or Claude native questionnaire before
 passing a repository. The installer never opens a questionnaire or an
 authentication web page.`;
 
-// The published package cannot carry node_modules, because npm excludes it from
-// every tarball. The bridge runtime is therefore assembled here from the
-// dependencies npm installed for this package, into the exact layout the
-// installer verifies against the bridge lockfile.
-async function stageBridgeRuntime() {
-  const source = join(packageRoot, 'runtime');
-  const packageJson = await readJson(join(source, 'package.json'));
-  const packageLock = await readJson(join(source, 'package-lock.json'));
-  if (!packageJson || !packageLock) {
-    throw new Error(`Bridge runtime metadata is missing in ${source}`);
-  }
-  const staged = await mkdtemp(join(tmpdir(), 'engineering-memory-runtime-'));
-  await cp(join(source, 'dist'), join(staged, 'dist'), { recursive: true });
-  await cp(join(source, 'package.json'), join(staged, 'package.json'));
-  await cp(
-    join(source, 'package-lock.json'),
-    join(staged, 'package-lock.json'),
-  );
-  for (const entry of resolveProductionPackagePaths(packageJson, packageLock)) {
-    const name = entry.path.slice('node_modules/'.length);
-    let installed;
-    try {
-      installed = dirname(require.resolve(`${name}/package.json`));
-    } catch {
-      if (entry.optional) continue;
-      throw new Error(
-        `Bridge dependency ${name} is not installed. Reinstall this package so npm resolves its dependencies.`,
-      );
-    }
-    const destination = join(staged, ...entry.path.split('/'));
-    await mkdir(dirname(destination), { recursive: true });
-    await cp(installed, destination, { recursive: true });
-  }
-  return staged;
-}
-
 // The backend this package was published for. An installation only names one
 // when it points at a different, self-hosted backend.
 async function publishedApiUrl() {
@@ -82,6 +42,11 @@ async function publishedApiUrl() {
   return apiUrl;
 }
 
+async function publishedVersion() {
+  const manifest = await readJson(join(packageRoot, 'package.json'));
+  return String(manifest?.version ?? '0.0.0');
+}
+
 async function main(argumentList) {
   const [command, ...rest] = argumentList;
   if (!command || command === '--help' || command === 'help') {
@@ -95,7 +60,7 @@ async function main(argumentList) {
   if (!(await exists(join(skillSource, 'SKILL.md')))) {
     throw new Error(`Skill source is missing in ${skillSource}`);
   }
-  const staged = await stageBridgeRuntime();
+  const staged = await stageBridgeRuntime(packageRoot, require);
   try {
     await runInstaller([
       ...rest,

package/dispatcher/sections.mjs

@@ -1,8 +1,23 @@
 const shared = `This section is managed by the Engineering Memory installer.
 
-For every task, search from the working directory toward the repository root for \`.engineering-memory/project.json\` before planning or editing.
+Search from the working directory toward the repository root for \`.engineering-memory/project.json\` before doing anything with this repository, including answering a question about it.
 
-When the marker exists, load the personal \`engineering-memory\` skill and use the \`engineering-memory\` MCP server. Call \`session.bootstrap\` before planning or editing. After compaction, a new chat, interruption, or handoff, call \`session.resume\` before continuing.
+Call \`session.entry\` before you answer anything in a repository, whatever the user asked for. It reports whether they are signed in, whether this repository is bound, what they decided about it last time, and the one thing to do now. Act on that before the message itself:
+
+- Not signed in: ask them to sign in and start the browser flow when they agree. Nothing about the project can be answered until that resolves.
+- No decision recorded: ask which organization and then which project, whatever the message was. The other answer is switching Engineering Memory off in this repository, and it is remembered with \`session.set_decision\`.
+- Switched off: say nothing about Engineering Memory, offer nothing, hint at nothing, however useful it would be for what was asked. They turned it off; raising it again is what this prevents. Record it back on only when they ask.
+- Bound: continue into the lifecycle.
+
+\`session.entry\` also reports this client's version. When it says an update is available, offer once to run \`npx engineering-memory@latest install\` and tell the user the client restarts afterwards. If they decline, record it with \`session.decline_update\` and never raise that version again. When it says an update is required, there is no choice to offer: say that this client is older than the backend supports, give the command, and do not carry on as though the lifecycle works.
+
+The user may say at any point that they want a different organization, a different project, Engineering Memory switched off, or switched back on. Recognise what they mean rather than matching words — the request arrives in whatever language and phrasing they happen to use — and act on it. Changing the organization always asks for the project again.
+
+When the marker exists, load the personal \`engineering-memory\` skill and use the \`engineering-memory\` MCP server before you answer. Call \`session.bootstrap\` after the entry check — not only before planning or editing, but before telling the user anything about this project: its design source, its screens, its rules, its history, what it does or does not have.
+
+Never answer a question about a bound repository from the working tree alone. What the repository holds is not what the project knows: the design file, the screen records, the engineering rules and the history of every earlier task live in Engineering Memory, and a file search will report them missing. If you are about to say that something is not recorded anywhere, that is the moment you have not asked yet.
+
+After compaction, a new chat, interruption, or handoff, call \`session.resume\` before continuing.
 
 Do not edit until the skill lifecycle has completed discovery, its checkpoint, and \`context.prepare_change\`. Do not claim completion until \`task.verify\` succeeds.
 

package/install/cli.mjs

@@ -8,6 +8,7 @@ const usage = `Usage:
 Options:
   --clients codex,claude
   --api-url <https-url>
+  --client-version <version>
   --development
   --repo <repository-root>
   --hook-mode chain|verify-only|cancel
@@ -39,6 +40,8 @@ export function parseInstallerArguments(arguments_) {
         .filter(Boolean);
     } else if (argument === '--api-url') {
       result.apiUrl = value;
+    } else if (argument === '--client-version') {
+      result.clientVersion = value;
     } else if (argument === '--repo') {
       result.repoRoot = resolve(value);
     } else if (argument === '--hook-mode') {

package/install/installer.mjs

@@ -70,6 +70,7 @@ export async function installEngineeringMemory(options = {}) {
   const nodePath = resolve(options.nodePath ?? process.execPath);
   const development = options.development === true;
   const apiUrl = normalizeApiUrl(options.apiUrl, { development });
+  const clientVersion = options.clientVersion ?? null;
   const selectedClients = normalizeClients(
     options.selectedClients ?? ['codex', 'claude'],
   );
@@ -124,6 +125,7 @@ export async function installEngineeringMemory(options = {}) {
     bridgeEntry,
     nodePath,
     apiUrl,
+    clientVersion,
     state: existingState,
     commandRunner,
   });
@@ -176,6 +178,7 @@ export async function installEngineeringMemory(options = {}) {
       bridgeEntry,
       nodePath,
       apiUrl,
+      clientVersion,
       development,
       mcp,
       hook,
@@ -188,6 +191,7 @@ export async function installEngineeringMemory(options = {}) {
       dispatcherPaths: clientPlans.map((plan) => plan.dispatcherPath),
       selectedClients,
       apiUrl,
+      clientVersion,
       runtimePath,
       bridgeEntry,
       gateEntry,

package/install/mcp-registration.mjs

@@ -3,6 +3,7 @@ import { commandFailure } from './commands.mjs';
 
 const SERVER_NAME = 'engineering-memory';
 const API_URL_ENV = 'ENGINEERING_MEMORY_API_URL';
+const CLIENT_VERSION_ENV = 'ENGINEERING_MEMORY_CLIENT_VERSION';
 const missingServerPattern =
   /not found|does not exist|unknown (?:mcp )?server|no (?:mcp )?server|is not configured/i;
 
@@ -44,6 +45,7 @@ export async function planMcpRegistrations({
   bridgeEntry,
   nodePath,
   apiUrl,
+  clientVersion,
   state,
   commandRunner,
 }) {
@@ -63,6 +65,7 @@ export async function planMcpRegistrations({
       nodePath,
       bridgeEntry,
       apiUrl,
+      clientVersion,
     });
     if (existing.code === 0) {
       if (!isOwnedRegistration(clientName, managed)) {
@@ -177,9 +180,14 @@ async function removeRegistration(plan, commandRunner) {
 }
 
 function environmentArgs(registration) {
-  return registration.apiUrl
-    ? ['--env', `${API_URL_ENV}=${registration.apiUrl}`]
-    : [];
+  const args = [];
+  if (registration.apiUrl) {
+    args.push('--env', `${API_URL_ENV}=${registration.apiUrl}`);
+  }
+  if (registration.clientVersion) {
+    args.push('--env', `${CLIENT_VERSION_ENV}=${registration.clientVersion}`);
+  }
+  return args;
 }
 
 function createRegistration(clientName, values) {
@@ -197,6 +205,7 @@ function registrationFingerprint(clientName, registration) {
         nodePath: registration.nodePath,
         bridgeEntry: registration.bridgeEntry,
         apiUrl: registration.apiUrl ?? null,
+        clientVersion: registration.clientVersion ?? null,
       }),
     )
     .digest('hex');
@@ -207,6 +216,7 @@ function sameRegistration(left, right) {
     left?.nodePath === right.nodePath &&
     left?.bridgeEntry === right.bridgeEntry &&
     left?.apiUrl === right.apiUrl &&
+    left?.clientVersion === right.clientVersion &&
     left?.fingerprint === right.fingerprint
   );
 }
@@ -355,10 +365,14 @@ function canonicalRegistration(registration) {
   return canonicalRegistrationFromValues({
     command: registration.nodePath,
     args: [registration.bridgeEntry],
-    env:
-      registration.apiUrl === undefined
+    env: {
+      ...(registration.apiUrl === undefined
         ? {}
-        : { [API_URL_ENV]: registration.apiUrl },
+        : { [API_URL_ENV]: registration.apiUrl }),
+      ...(registration.clientVersion
+        ? { [CLIENT_VERSION_ENV]: registration.clientVersion }
+        : {}),
+    },
   });
 }
 

package/lib/stage-runtime.mjs

@@ -0,0 +1,53 @@
+import { cp, mkdir, mkdtemp, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { readJson, resolveProductionPackagePaths } from '../install/files.mjs';
+
+// The published package cannot carry node_modules, because npm excludes it from
+// every tarball. The bridge runtime is assembled here from the dependencies npm
+// installed for this package, into the exact layout the installer verifies
+// against the bridge lockfile.
+export async function stageBridgeRuntime(packageRoot, resolver) {
+  const source = join(packageRoot, 'runtime');
+  const packageJson = await readJson(join(source, 'package.json'));
+  const packageLock = await readJson(join(source, 'package-lock.json'));
+  if (!packageJson || !packageLock) {
+    throw new Error(`Bridge runtime metadata is missing in ${source}`);
+  }
+  const staged = await mkdtemp(join(tmpdir(), 'engineering-memory-runtime-'));
+  await cp(join(source, 'dist'), join(staged, 'dist'), { recursive: true });
+  await cp(join(source, 'package.json'), join(staged, 'package.json'));
+  await cp(
+    join(source, 'package-lock.json'),
+    join(staged, 'package-lock.json'),
+  );
+  for (const entry of resolveProductionPackagePaths(packageJson, packageLock)) {
+    const name = entry.path.slice('node_modules/'.length);
+    const installed = await locate(name, resolver);
+    if (!installed) {
+      if (entry.optional) continue;
+      throw new Error(
+        `Bridge dependency ${name} is not installed. Reinstall this package so npm resolves its dependencies.`,
+      );
+    }
+    const destination = join(staged, ...entry.path.split('/'));
+    await mkdir(dirname(destination), { recursive: true });
+    await cp(installed, destination, { recursive: true });
+  }
+  return staged;
+}
+
+// A package is free to keep package.json out of its exports map, and several do,
+// so the directory is found on disk rather than through module resolution.
+async function locate(name, resolver) {
+  for (const directory of resolver.resolve.paths(name) ?? []) {
+    const candidate = join(directory, ...name.split('/'));
+    try {
+      await stat(join(candidate, 'package.json'));
+      return candidate;
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "engineering-memory",
-  "version": "0.1.0",
+  "version": "0.2.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",
@@ -13,6 +13,7 @@
   "files": [
     "bin",
     "dispatcher",
+    "lib",
     "install",
     "skill",
     "runtime"

package/runtime/dist/src/config.js

@@ -9,6 +9,7 @@ export function loadBridgeConfig(env = process.env) {
     return {
         apiBaseUrl: (env.ENGINEERING_MEMORY_API_URL ?? 'http://127.0.0.1:3000').replace(/\/$/, ''),
         stateRoot: resolve(env.ENGINEERING_MEMORY_STATE_DIR ?? join(homedir(), '.engineering-memory')),
+        clientVersion: env.ENGINEERING_MEMORY_CLIENT_VERSION ?? null,
         requestTimeoutMs: positiveInteger(env.ENGINEERING_MEMORY_TIMEOUT_MS, 15_000),
         cacheMaxEntries: positiveInteger(env.ENGINEERING_MEMORY_CACHE_MAX_ENTRIES, 64),
         cacheMaxBytes: positiveInteger(env.ENGINEERING_MEMORY_CACHE_MAX_BYTES, 5 * 1024 * 1024),
@@ -35,6 +36,7 @@ export const endpoints = {
     contextRefresh: '/runtime/context/refresh',
     memoryQuery: '/memory/query',
     memoryHistory: '/memory/history',
+    clientVersion: '/runtime/client-version',
     memoryScaffoldPlan: '/memory/scaffold-plan',
     memoryArchitectureModule: '/memory/architecture-module',
     memoryProposeRevision: '/memory/proposals',

package/runtime/dist/src/index.js

@@ -13,6 +13,8 @@ import { ApiClient } from './runtime/api-client.js';
 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 { UpdateChoiceStore } from './runtime/update-choice-store.js';
 import { PrincipalStateGuard } from './runtime/principal-state.js';
 export function createBridgeService() {
     const config = loadBridgeConfig();
@@ -39,6 +41,8 @@ export function createBridgeService() {
     const git = new GitInspector();
     const outbox = new OfflineOutbox(stateRoot);
     const activeContexts = new ActiveContextStore(stateRoot);
+    const repositoryDecisions = new RepositoryDecisionStore(stateRoot);
+    const updateChoices = new UpdateChoiceStore(stateRoot);
     const gate = new VerificationGate(stateRoot, git, outbox);
     const principalState = new PrincipalStateGuard(stateRoot, credentials, cache, outbox, activeContexts, gate);
     return new BridgeService({
@@ -50,6 +54,9 @@ export function createBridgeService() {
         outbox,
         gate,
         activeContexts,
+        repositoryDecisions,
+        updateChoices,
+        clientVersion: config.clientVersion,
         principalState,
     });
 }

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

@@ -44,6 +44,9 @@ const checkpointBase = {
     idempotencyKey: z.string().uuid().optional(),
 };
 export const engineeringMemoryToolNames = [
+    'session.entry',
+    'session.set_decision',
+    'session.decline_update',
     'session.bootstrap',
     'session.resume',
     'context.prepare_change',
@@ -74,6 +77,21 @@ export const engineeringMemoryToolNames = [
     'auth.logout',
 ];
 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.',
+        inputSchema: z.object({ repoRoot: optionalRepoRoot }),
+    }, async (input) => toolResult(await service.sessionEntry(input)));
+    server.registerTool('session.set_decision', {
+        description: 'Record what the user decided about Engineering Memory in this repository: bound once they have chosen a project, disabled when they ask for it off, or none to forget the decision when they ask for it back. Call it only from something the user actually said; it is the only thing that changes the entry state.',
+        inputSchema: z.object({
+            repoRoot: optionalRepoRoot,
+            decision: z.enum(['bound', 'disabled', 'none']),
+        }),
+    }, async (input) => toolResult(await service.sessionSetDecision(input)));
+    server.registerTool('session.decline_update', {
+        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.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({

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

@@ -1130,6 +1130,92 @@ export class BridgeService {
             });
         });
     }
+    async sessionEntry(input = {}) {
+        return await this.execute(async () => {
+            const authentication = await this.dependencies.browserAuth.status();
+            let repository;
+            try {
+                repository = await this.dependencies.repositories.resolve(input.repoRoot ?? process.cwd());
+            }
+            catch (error) {
+                return asJsonValue({
+                    authenticated: authentication.authenticated === true,
+                    repository: null,
+                    decision: 'none',
+                    nextAction: 'This directory is not a Git repository, so Engineering Memory has nothing to bind. Work normally and say nothing about it.',
+                    reason: error instanceof Error ? error.message : String(error),
+                });
+            }
+            const decision = await this.dependencies.repositoryDecisions.load(repository.repoFingerprint);
+            const authenticated = authentication.authenticated === true;
+            const state = decision?.state ?? (repository.projectId ? 'bound' : 'none');
+            const client = await this.clientUpdate(authenticated);
+            return asJsonValue({
+                authenticated,
+                repository: publicRepository(repository),
+                decision: state,
+                projectId: repository.projectId ?? decision?.projectId ?? null,
+                client,
+                nextAction: entryNextAction(authenticated, state),
+            });
+        });
+    }
+    // What the backend expects of this client, and whether the user has already
+    // been asked about it. A required update leaves no choice; an optional one is
+    // offered once per version and never raised again after a refusal.
+    async clientUpdate(authenticated) {
+        const installed = this.dependencies.clientVersion;
+        if (!authenticated) {
+            return asJsonValue({ installed, status: 'unknown' });
+        }
+        let report;
+        try {
+            const response = await this.dependencies.client.request(`${endpoints.clientVersion}?installed=${encodeURIComponent(installed ?? '')}`);
+            report = objectValue(response.data);
+        }
+        catch {
+            return asJsonValue({ installed, status: 'unknown' });
+        }
+        if (!report)
+            return asJsonValue({ installed, status: 'unknown' });
+        const status = String(report.status);
+        if (status === 'update_available') {
+            const declined = await this.dependencies.updateChoices.declinedVersion();
+            if (declined === String(report.latest)) {
+                return asJsonValue({ ...report, status: 'declined' });
+            }
+        }
+        return asJsonValue({ ...report, command: 'npx engineering-memory@latest install' });
+    }
+    async sessionDeclineUpdate() {
+        return await this.execute(async () => {
+            const response = await this.dependencies.client.request(`${endpoints.clientVersion}?installed=${encodeURIComponent(this.dependencies.clientVersion ?? '')}`);
+            const report = objectValue(response.data);
+            const latest = report ? String(report.latest) : 'unknown';
+            await this.dependencies.updateChoices.decline(latest);
+            return asJsonValue({
+                declinedVersion: latest,
+                nextAction: 'Do not offer this update again. Say nothing more about it unless the user asks, or until a newer version than this one is published.',
+            });
+        });
+    }
+    async sessionSetDecision(input) {
+        return await this.execute(async () => {
+            const repository = await this.dependencies.repositories.resolve(input.repoRoot ?? process.cwd());
+            if (input.decision === 'none') {
+                await this.dependencies.repositoryDecisions.clear(repository.repoFingerprint);
+                return asJsonValue({
+                    decision: 'none',
+                    nextAction: 'Ask which organization and then which project, listing what the user already has with the option to create a new one last.',
+                });
+            }
+            const decision = await this.dependencies.repositoryDecisions.save(repository.repoFingerprint, input.decision, repository.projectId ?? undefined);
+            return asJsonValue({
+                decision: decision.state,
+                nextAction: entryNextAction(true, decision.state),
+            });
+        });
+    }
     async authStatus() {
         return await this.execute(async () => {
             return asJsonValue(await this.dependencies.browserAuth.status());
@@ -1895,6 +1981,18 @@ export function parseCorrectionScopeLine(summary) {
     const match = /^Correction scope ([a-z_]+): (.+)$/.exec(summary);
     return match ? { scope: match[1], reference: match[2] } : null;
 }
+function entryNextAction(authenticated, decision) {
+    if (decision === 'disabled') {
+        return 'This user switched Engineering Memory off in this repository. Say nothing about it, offer nothing, and work as an ordinary agent until they ask for it back.';
+    }
+    if (!authenticated) {
+        return 'Ask the user to sign in before answering anything about this project, and start the browser flow when they agree.';
+    }
+    if (decision === 'bound') {
+        return 'Continue into the lifecycle with session.bootstrap or session.resume.';
+    }
+    return 'Ask which organization and then which project, whatever the user asked for, listing what they already have with the option to create a new one last. Switching Engineering Memory off in this repository is the other answer, and it is remembered.';
+}
 function deliveryQuestion() {
     return asJsonValue({
         required: true,

package/runtime/dist/src/runtime/repository-decision-store.js

@@ -0,0 +1,67 @@
+import { join } from 'node:path';
+import { readJson, removeFile, writeJson } from '../utilities/files.js';
+// What a user decided about Engineering Memory in one repository, on one
+// machine. It never lives in the repository: a developer switching it off must
+// not switch it off for everyone who clones after them.
+export class RepositoryDecisionStore {
+    root;
+    queues = new Map();
+    constructor(stateRoot) {
+        this.root = join(stateRoot, 'repository-decisions');
+    }
+    async load(repoFingerprint) {
+        assertFingerprint(repoFingerprint);
+        const decision = await readJson(this.pathFor(repoFingerprint), this.root);
+        if (!decision)
+            return null;
+        if (decision.repoFingerprint !== repoFingerprint ||
+            (decision.state !== 'bound' && decision.state !== 'disabled')) {
+            throw new Error('Repository decision record is invalid');
+        }
+        return decision;
+    }
+    async save(repoFingerprint, state, projectId) {
+        assertFingerprint(repoFingerprint);
+        return await this.exclusive(repoFingerprint, async () => {
+            const decision = {
+                schemaVersion: 1,
+                repoFingerprint,
+                state,
+                ...(projectId ? { projectId } : {}),
+                updatedAt: new Date().toISOString(),
+            };
+            await writeJson(this.pathFor(repoFingerprint), decision, this.root);
+            return decision;
+        });
+    }
+    async clear(repoFingerprint) {
+        assertFingerprint(repoFingerprint);
+        await this.exclusive(repoFingerprint, async () => {
+            await removeFile(this.pathFor(repoFingerprint), this.root);
+        });
+    }
+    pathFor(repoFingerprint) {
+        return join(this.root, `${repoFingerprint}.json`);
+    }
+    async exclusive(repoFingerprint, action) {
+        const previous = this.queues.get(repoFingerprint) ?? Promise.resolve();
+        let release = () => undefined;
+        const current = new Promise((resolvePromise) => {
+            release = resolvePromise;
+        });
+        this.queues.set(repoFingerprint, previous.then(() => current));
+        await previous;
+        try {
+            return await action();
+        }
+        finally {
+            release();
+        }
+    }
+}
+function assertFingerprint(value) {
+    if (!/^[0-9a-f]{64}$/.test(value)) {
+        throw new Error('Repository fingerprint is invalid');
+    }
+}
+//# sourceMappingURL=repository-decision-store.js.map

package/runtime/dist/src/runtime/update-choice-store.js

@@ -0,0 +1,26 @@
+import { join } from 'node:path';
+import { readJson, writeJson } from '../utilities/files.js';
+// Which client version the user was offered and turned down. Asking again for
+// the same version is nagging; asking when a newer one arrives is news.
+export class UpdateChoiceStore {
+    path;
+    root;
+    constructor(stateRoot) {
+        this.root = join(stateRoot, 'client');
+        this.path = join(this.root, 'update-choice.json');
+    }
+    async declinedVersion() {
+        const choice = await readJson(this.path, this.root);
+        return choice?.declinedVersion ?? null;
+    }
+    async decline(version) {
+        const choice = {
+            schemaVersion: 1,
+            declinedVersion: version,
+            updatedAt: new Date().toISOString(),
+        };
+        await writeJson(this.path, choice, this.root);
+        return choice;
+    }
+}
+//# sourceMappingURL=update-choice-store.js.map

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: engineering-memory
-description: Enforces the Engineering Memory lifecycle for Codex and Claude in repositories bound by .engineering-memory/project.json. Use for every planning, implementation, review, diagnosis, rework, Figma, component, screen, service, model, navigation, localization, storage, validation, or Git task in a bound repository.
+description: Enforces the Engineering Memory lifecycle for Codex and Claude in repositories bound by .engineering-memory/project.json. Use before answering anything about a bound repository, including a question about what it has or where its design lives, and for every planning, implementation, review, diagnosis, rework, Figma, component, screen, service, model, navigation, localization, storage, validation, or Git task in one.
 ---
 
 # Engineering Memory
@@ -11,18 +11,19 @@ Read [lifecycle.md](references/lifecycle.md) before acting in a bound repository
 
 Mandatory behavior:
 
-1. Locate `.engineering-memory/project.json` from the working directory toward the repository root.
-2. Before planning or editing, call `session.bootstrap`. After compaction, a new chat, interruption, or handoff, call `session.resume` first.
-3. Open the task in `read_only` mode for review, diagnosis, planning, or reporting that does not authorize writes; use `scaffold` mode only to apply organization architecture templates to a new project; otherwise use `write` mode. Do read-only discovery, then record the discovery checkpoint.
-4. For a write task, call `context.prepare_change` with the intended paths and record the pre-edit checkpoint before the first edit. Do not edit paths outside the active lease. A read-only task must not acquire a change lease unless the user expands the task to writing and the bridge performs the explicit mode transition.
-5. Use the returned context pack as the engineering authority for the task. Use `memory.query` only for targeted missing context, and `memory.history` to read why the records you are changing became what they are before you design against them.
-6. Record phase, correction, validation, and handoff checkpoints at the required moments. Declare the task's discretionary decisions on the validation-before checkpoint, and when a task repeats a shape, have the first unit reviewed before writing the rest.
-7. For a write task, reconcile every changed screen and component. Propose revisions when semantics changed; otherwise record an explicit no-semantic-memory-change reconciliation.
-8. Before validation, read the changed code back against the rules that govern it and record `task.self_review`. Verification refuses without a review of the current diff, and any later edit requires reviewing again.
-9. Run `task.verify` before claiming completion. Write tasks verify the exact Git diff, active lease, and structured command-bound validation evidence. Read-only tasks verify that the current Git diff hash still equals the baseline captured at bootstrap, plus the required discovery, validation, handoff, pinned-context, and synchronization evidence. Run `task.close` only after verification succeeds. The pre-commit gate must confirm the closed task online; a local verification receipt is insufficient.
-10. After closing a task, ask the delivery question every time — commit, commit and push, or either of those with a draft or ready pull request onto a base branch the user names — and do only what they choose. Once a pull request exists, check whether it merges cleanly and ask before resolving a conflict.
-11. Never commit, push, publish, deploy, approve a permanent memory revision, or overwrite an existing Git hook without explicit user authorization.
-12. Never store tokens, passwords, client secrets, raw headers, raw payloads, customer data, or PII in tool inputs, journals, memory, logs, or generated documentation.
+1. Locate `.engineering-memory/project.json` from the working directory toward the repository root. When it exists, the project's knowledge is in the backend and not in the working tree, so answer nothing about the project before bootstrapping — a file search that finds no design link, no screen record and no rule is reporting what the repository lacks, not what the project knows.
+2. Call `session.entry` before answering anything in a repository, and act on what it reports before the message itself: sign in when it says so, ask for organization and project when nothing has been decided, and stay completely silent about Engineering Memory in a repository where the user switched it off. Record every one of those answers with `session.set_decision`, and only ever from something the user actually said.
+3. Before planning or editing, call `session.bootstrap`. After compaction, a new chat, interruption, or handoff, call `session.resume` first.
+4. Open the task in `read_only` mode for review, diagnosis, planning, or reporting that does not authorize writes; use `scaffold` mode only to apply organization architecture templates to a new project; otherwise use `write` mode. Do read-only discovery, then record the discovery checkpoint.
+5. For a write task, call `context.prepare_change` with the intended paths and record the pre-edit checkpoint before the first edit. Do not edit paths outside the active lease. A read-only task must not acquire a change lease unless the user expands the task to writing and the bridge performs the explicit mode transition.
+6. Use the returned context pack as the engineering authority for the task. Use `memory.query` only for targeted missing context, and `memory.history` to read why the records you are changing became what they are before you design against them.
+7. Record phase, correction, validation, and handoff checkpoints at the required moments. Declare the task's discretionary decisions on the validation-before checkpoint, and when a task repeats a shape, have the first unit reviewed before writing the rest.
+8. For a write task, reconcile every changed screen and component. Propose revisions when semantics changed; otherwise record an explicit no-semantic-memory-change reconciliation.
+9. Before validation, read the changed code back against the rules that govern it and record `task.self_review`. Verification refuses without a review of the current diff, and any later edit requires reviewing again.
+10. Run `task.verify` before claiming completion. Write tasks verify the exact Git diff, active lease, and structured command-bound validation evidence. Read-only tasks verify that the current Git diff hash still equals the baseline captured at bootstrap, plus the required discovery, validation, handoff, pinned-context, and synchronization evidence. Run `task.close` only after verification succeeds. The pre-commit gate must confirm the closed task online; a local verification receipt is insufficient.
+11. After closing a task, ask the delivery question every time — commit, commit and push, or either of those with a draft or ready pull request onto a base branch the user names — and do only what they choose. Once a pull request exists, check whether it merges cleanly and ask before resolving a conflict.
+12. Never commit, push, publish, deploy, approve a permanent memory revision, or overwrite an existing Git hook without explicit user authorization.
+13. Never store tokens, passwords, client secrets, raw headers, raw payloads, customer data, or PII in tool inputs, journals, memory, logs, or generated documentation.
 
 If the repository is unbound, do not silently create or attach a project. Use the native questionnaire workflow. If the user selects task-only skip, do not create a marker or memory records.
 

package/skill/references/questionnaires.md

@@ -6,6 +6,18 @@ Use Codex or Claude native question controls. Do not open a custom survey web pa
 
 When no Engineering Memory session exists, ask whether to sign in, create an account, or skip Engineering Memory for this task. Explain that skip is permitted only for an unbound repository. After sign in or sign up is selected, let the bridge open the browser authentication flow. Never ask for a password in the native questionnaire or chat. If a browser link is expired, rejected, already used, or otherwise unusable, call `auth.signin_browser` with `restart: true` and present only the newly returned URL.
 
+## Entering a Repository
+
+`session.entry` decides what is asked, and it is asked whatever the user's first message is. A question about the project is not a reason to skip it; it is the reason it exists.
+
+When nothing has been decided about this repository, the choice put to the user is: work under an organization and project, or switch Engineering Memory off here. Both answers are recorded with `session.set_decision`, and the second one is final until they ask for it back — not asked again next session, not raised when a task would obviously benefit, not hinted at. A person who said no should never have to say it twice.
+
+## Client Updates
+
+`session.entry` reports whether this installation is behind the published client. An available update is offered once: say what it is, offer to run `npx engineering-memory@latest install`, and say the client has to be restarted afterwards for the new tools to load. A refusal is recorded with `session.decline_update` and that version is never mentioned again; a later, newer version is a new question rather than the same one repeated.
+
+A required update is not a question. The client is older than the backend supports, so say that, give the command, and do not offer to carry on without it — the tools the lifecycle depends on are not there.
+
 ## Organization
 
 Call `organization.list` and ask which organization to work under. List the ones the user already belongs to first, in the order the call returns them, and put **create a new organization** last. Never pick one on their behalf, not even when there is only one — the answer decides where everything the task produces is written.
@@ -22,7 +34,9 @@ Ask both questions again whenever a chat starts in a repository whose binding yo
 
 ## Switching Organization or Project
 
-The user may say mid-chat that they want to change organization or project, in those words or any others that mean it. Take it as an instruction rather than a remark, and act on it.
+The user may say mid-chat that they want to change organization or project, switch Engineering Memory off, or switch it back on. They will say it in their own words, in whatever language they are writing in, and there is no list of phrases to watch for — recognise what they mean and act on it. Take it as an instruction rather than a remark.
+
+Switching off records the decision and ends the subject. Switching back on clears it and runs the organization and project questions again.
 
 Changing the organization always means asking for the project again afterwards, because a project belongs to exactly one organization and the old answer cannot survive the change. Run the organization questionnaire, then the project one, then bind the repository to the chosen project with `project.resolve` so the marker matches what the user just said.