engineering-memory 1.10.1 → 1.10.3

package/dispatcher/sections.mjs

@@ -21,7 +21,7 @@ After compaction, a new chat, interruption, or handoff, call \`session.resume\`
 
 Do not edit until the skill lifecycle has completed discovery, its checkpoint, and \`context.prepare_change\`. Do not claim completion until \`task.verify\` succeeds.
 
-Use the host's native questionnaire for every question to the user, including implementation choices, names, clarification, branch/worktree decisions and delivery. In Codex use request_user_input when available; in Claude use AskUserQuestion. Never replace the questionnaire with a chat instruction such as 'type this', 'reply yes', or 'write X if you want Y'. Do not open a survey web page. If the required native control is unavailable or prohibited for that kind of question, follow the host's tool restrictions, explain the limitation, and continue only work already authorized; do not fabricate a survey or silently choose an answer. Existing answers remain valid through retries and handoffs.
+Use the host's native questionnaire for every question to the user, including implementation choices, names, clarification, branch/worktree decisions and delivery. For a required decision, use \`questionnaire.ask\` to open a durable native MCP form and \`questionnaire.resume\` to return to the same unanswered question. Read the skill's questionnaires reference first. Never use request_user_input_async for a required decision: it does not wait for an answer. When the durable form is unavailable, use a blocking native control only where the host permits it: request_user_input in Codex or AskUserQuestion in Claude. Never replace the questionnaire with a chat instruction such as 'type this', 'reply yes', or 'write X if you want Y'. Do not open a survey web page. If the required native control is unavailable or prohibited for that kind of question, follow the host's tool restrictions, explain the limitation, and continue only work already authorized; do not fabricate a survey or silently choose an answer. A timeout, dismissed form, empty response or ended turn is not an answer. Keep the decision pending and resume it; do not start dependent work or report it as resolved. Existing answers remain valid through retries and handoffs.
 
 When the repository is unbound, use the native questionnaire required by the skill. Do not silently create or bind a project. Do not open a survey web page.`;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "engineering-memory",
-  "version": "1.10.1",
+  "version": "1.10.3",
   "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/index.js

@@ -17,6 +17,7 @@ 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';
+import { QuestionnaireStore } from './runtime/questionnaire-store.js';
 export function createBridgeService() {
     const config = loadBridgeConfig();
     const apiNamespace = apiNamespaceKey(config.apiBaseUrl);
@@ -59,6 +60,7 @@ export function createBridgeService() {
         repositoryDecisions,
         updateChoices,
         shadowNotices,
+        questionnaires: new QuestionnaireStore(stateRoot),
         clientVersion: config.clientVersion,
         principalState,
     });

package/runtime/dist/src/mcp/questionnaire-tools.js

@@ -0,0 +1,131 @@
+import { acceptedContent, CLIENT_CAPABILITIES_META_KEY, inputRequired, inputResponse, } from '@modelcontextprotocol/server';
+import { questionnaireAnswerSchema, } from '../runtime/questionnaire-store.js';
+export async function askQuestionnaire(server, service, input, context) {
+    try {
+        return await present(server, service, await service.questionnaireAsk(input), input.repoRoot, context);
+    }
+    catch (error) {
+        return failure(error);
+    }
+}
+export async function resumeQuestionnaire(server, service, input, context) {
+    try {
+        return await present(server, service, await service.questionnaireResume(input), input.repoRoot, context);
+    }
+    catch (error) {
+        return failure(error);
+    }
+}
+async function present(server, service, record, repoRoot, context) {
+    if (record.status === 'answered')
+        return answered(record, record.answer, true);
+    if (context.mcpReq.signal.aborted)
+        return pending(record, 'interrupted');
+    const responses = context.mcpReq.inputResponses;
+    const response = inputResponse(responses, record.requestKey);
+    if (response.kind === 'elicit' && response.action === 'accept') {
+        const answer = acceptedContent(responses, record.requestKey, questionnaireAnswerSchema(record));
+        if (!answer)
+            return pending(record, 'invalid_response');
+        const resolved = await service.questionnaireAccept({
+            repoRoot,
+            questionnaireId: record.questionnaireId,
+            requestKey: record.requestKey,
+            scope: record.scope,
+            answer,
+        });
+        return answered(resolved.record, resolved.answer, resolved.replayed);
+    }
+    if (response.kind === 'elicit')
+        return pending(record, response.action);
+    if (responses !== undefined || context.mcpReq.droppedInputResponseKeys?.length)
+        return pending(record, 'missing_or_stale_response');
+    const envelope = context.mcpReq.envelope;
+    const capabilities = envelope?.[CLIENT_CAPABILITIES_META_KEY] ?? server.server.getClientCapabilities();
+    const elicitation = capabilities?.elicitation;
+    if (!elicitation || (!elicitation.form && elicitation.url !== undefined))
+        return pending(record, 'native_form_unavailable');
+    return inputRequired({
+        inputRequests: {
+            [record.requestKey]: inputRequired.elicit({
+                mode: 'form',
+                message: `${record.message}\n\nChoose an answer to resolve this decision. Closing or cancelling the form leaves it pending.${record.allowFreeText ? ' For another answer choose Other and fill in text. Free text is not stored and cannot be replayed.' : ''}`,
+                requestedSchema: {
+                    type: 'object',
+                    properties: {
+                        choice: {
+                            type: 'string',
+                            title: 'Answer',
+                            enum: [
+                                ...record.options.map((option) => option.id),
+                                ...(record.allowFreeText ? ['__other__'] : []),
+                            ],
+                            enumNames: [
+                                ...record.options.map((option) => option.label),
+                                ...(record.allowFreeText ? ['Other'] : []),
+                            ],
+                        },
+                        ...(record.allowFreeText
+                            ? {
+                                text: {
+                                    type: 'string',
+                                    title: 'Other answer',
+                                    minLength: 1,
+                                    maxLength: 2000,
+                                },
+                            }
+                            : {}),
+                    },
+                    required: ['choice'],
+                },
+            }),
+        },
+    });
+}
+function pending(record, reason) {
+    return result({
+        questionnaireId: record.questionnaireId,
+        status: 'pending',
+        reason,
+        answerAvailable: false,
+        nextAction: reason === 'native_form_unavailable'
+            ? 'This host does not advertise native MCP forms. The decision remains pending. Explain the limitation and continue only independently authorized work. Use a supported native host and questionnaire.resume to answer; do not silently substitute an asynchronous question.'
+            : 'The decision remains pending without expiry. Call questionnaire.resume with this questionnaireId to show the same question again. Do not infer an answer or continue dependent work.',
+    });
+}
+function answered(record, answer, replayed) {
+    return result({
+        questionnaireId: record.questionnaireId,
+        status: 'answered',
+        answerAvailable: answer !== undefined,
+        ...(answer ? { answer } : {}),
+        replayed,
+        ...(!answer
+            ? {
+                nextAction: 'The free-text answer was accepted earlier but was not stored for privacy. It cannot be recovered or inferred. Use the original answer if still present in this conversation; otherwise collect it again through a new questionnaire or supported native input before dependent work.',
+            }
+            : {}),
+    });
+}
+function result(data) {
+    return { content: [{ type: 'text', text: JSON.stringify({ ok: true, data }) }] };
+}
+function failure(error) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    ok: false,
+                    error: {
+                        kind: 'questionnaire_error',
+                        message: error instanceof Error ? error.message : 'Questionnaire operation failed.',
+                        recovery: 'session.entry',
+                    },
+                }),
+            },
+        ],
+        isError: true,
+    };
+}
+//# sourceMappingURL=questionnaire-tools.js.map

package/runtime/dist/src/mcp/server.js

@@ -1,11 +1,12 @@
 import { McpServer } from '@modelcontextprotocol/server';
-import { registerEngineeringMemoryTools } from './tool-definitions.js';
+import { registerEngineeringMemoryTools, registerQuestionnaireTools } from './tool-definitions.js';
 export function createEngineeringMemoryServer(service) {
     const server = new McpServer({
         name: 'engineering-memory',
         version: '0.1.0',
     });
     registerEngineeringMemoryTools(server, service);
+    registerQuestionnaireTools(server, service);
     return server;
 }
 //# sourceMappingURL=server.js.map

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

@@ -1,5 +1,7 @@
 import * as z from 'zod/v4';
 import { validationIds } from '../runtime/bridge-service.js';
+import { questionnaireDefinitionSchema } from '../runtime/questionnaire-store.js';
+import { askQuestionnaire, resumeQuestionnaire } from './questionnaire-tools.js';
 const optionalRepoRoot = z.string().min(1).optional();
 const stringList = z.array(z.string().min(1));
 const jsonValue = z.lazy(() => z.union([
@@ -45,6 +47,8 @@ const checkpointBase = {
 };
 export const engineeringMemoryToolNames = [
     'audit.list',
+    'questionnaire.ask',
+    'questionnaire.resume',
     'session.entry',
     'session.set_decision',
     'session.decline_update',
@@ -116,6 +120,19 @@ const reconciliationEntry = z.object({
     revisionId: z.string().optional(),
     reason: z.string().optional(),
 });
+export function registerQuestionnaireTools(server, service) {
+    server.registerTool('questionnaire.ask', {
+        description: 'Persist a required decision before displaying a native questionnaire. Use a questionnaireId unique to this decision occurrence or task, and reuse it only for identical retries. A later decision or changed wording/options requires a new id. Only a schema-validated native acceptance answers it. Dismissal, timeout and missing replies remain pending without expiry. Never supply answers in tool arguments. Do not put personal information or secrets in the question or options. Free text is returned once and never stored; use explicit options for replayable decisions.',
+        inputSchema: questionnaireDefinitionSchema.extend({ repoRoot: optionalRepoRoot }),
+    }, async (input, context) => await askQuestionnaire(server, service, input, context));
+    server.registerTool('questionnaire.resume', {
+        description: 'Display the original durable questionnaire after interruption or return its saved accepted choice. No timeout or dismissal resolves a pending question. A saved free-text receipt cannot replay the text and must never be treated as a recovered answer.',
+        inputSchema: z.strictObject({
+            repoRoot: optionalRepoRoot,
+            questionnaireId: z.string().regex(/^[A-Za-z0-9_-]{1,100}$/),
+        }),
+    }, async (input, context) => await resumeQuestionnaire(server, service, input, context));
+}
 export function registerEngineeringMemoryTools(server, service) {
     server.registerTool('audit.list', {
         description: 'List one authorized organization or project audit trail with an exact cursor. Choose exactly one scope and send both cursor fields together.',

package/runtime/dist/src/project/repository.js

@@ -59,19 +59,24 @@ export class RepositoryResolver {
             projectId: explicitProjectId ?? binding?.projectId ?? null,
             schemaVersion: binding?.schemaVersion ?? null,
             repoFingerprint,
+            legacyFingerprints: binding ? [] : [await this.git.fingerprint(repoRoot, 1)],
             git,
         };
     }
-    async writeBinding(repoRoot, projectId) {
+    async writeBinding(repoRoot, projectId, fingerprint) {
         assertProjectId(projectId);
         const repository = await this.resolve(repoRoot, projectId);
+        const older = repository.legacyFingerprints.includes(fingerprint);
+        if (fingerprint !== repository.repoFingerprint && !older) {
+            throw new Error('The confirmed project fingerprint does not identify this repository');
+        }
         const repositoryKey = await this.keyFor(repository.repoRoot);
         const bindingPath = this.pathFor(repositoryKey);
         await writeJson(bindingPath, {
             projectId,
-            schemaVersion: repository.schemaVersion ?? this.markerSchemaVersion,
+            schemaVersion: older ? 1 : (repository.schemaVersion ?? this.markerSchemaVersion),
             repositoryKey,
-            repoFingerprint: repository.repoFingerprint,
+            repoFingerprint: fingerprint,
         }, this.stateRoot);
         return bindingPath;
     }

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

@@ -6,6 +6,7 @@ import { endpoints } from '../config.js';
 import { sha256, stableStringify } from '../utilities/hash.js';
 import { ApiResponseError, BackendUnavailableError, } from './api-client.js';
 import { assertSafeToPersist, normalizeRepositoryPaths } from './offline-outbox.js';
+import { principalFingerprint } from './principal-state.js';
 import { BridgeRecoveryError } from './recovery-error.js';
 export const validationIds = [
     'format',
@@ -32,6 +33,56 @@ export class BridgeService {
         this.dependencies = dependencies;
         this.deferDeliveries = dependencies.deferDeliveries ?? true;
     }
+    async questionnaireAsk(input) {
+        const scope = await this.questionnaireScope(input.repoRoot);
+        const { repoRoot: _repoRoot, ...definition } = input;
+        return await this.dependencies.questionnaires.ask(scope, definition);
+    }
+    async questionnaireResume(input) {
+        const scope = await this.questionnaireScope(input.repoRoot);
+        const record = await this.dependencies.questionnaires.get(scope, input.questionnaireId);
+        if (!record)
+            throw refuse('No questionnaire exists for this account and repository binding.', 'session.entry');
+        return record;
+    }
+    async questionnaireAccept(input) {
+        const scope = await this.questionnaireScope(input.repoRoot);
+        if (stableStringify(scope) !== stableStringify(input.scope)) {
+            throw refuse('The account or repository binding changed while the questionnaire was open.', 'session.entry');
+        }
+        return await this.dependencies.questionnaires.accept(scope, input.questionnaireId, input.requestKey, input.answer);
+    }
+    async questionnaireScope(repoRoot) {
+        await this.dependencies.principalState?.ensure();
+        const accessToken = await this.dependencies.credentials.get('access-token');
+        const repository = await this.dependencies.repositories.resolve(repoRoot ?? process.cwd());
+        const decision = await this.dependencies.repositoryDecisions.load(repository.repoFingerprint);
+        if (decision?.state === 'disabled')
+            throw refuse('Engineering Memory is disabled in this repository.', 'session.entry');
+        const principalHash = accessToken ? principalFingerprint(accessToken) : sha256('anonymous');
+        const currentCredential = await this.dependencies.credentials.get('access-token');
+        if (principalHash !==
+            (currentCredential ? principalFingerprint(currentCredential) : sha256('anonymous'))) {
+            throw refuse('The account changed while the questionnaire scope was being resolved.', 'session.entry');
+        }
+        return {
+            principalHash,
+            repoFingerprint: repository.repoFingerprint,
+            projectId: repository.projectId,
+        };
+    }
+    async pendingQuestionnaires(repoRoot) {
+        const scope = await this.questionnaireScope(repoRoot);
+        return (await this.dependencies.questionnaires.pending(scope)).map((record) => ({
+            questionnaireId: record.questionnaireId,
+            message: record.message,
+            options: record.options,
+            allowFreeText: record.allowFreeText,
+            createdAt: record.createdAt,
+            status: record.status,
+            nextAction: 'Call questionnaire.resume with this questionnaireId. No answer, elapsed time, dismissal or interruption is consent. Continue only work that is independent of the pending decision.',
+        }));
+    }
     deliverInBackground() {
         if (!this.deferDeliveries)
             return;
@@ -70,7 +121,10 @@ export class BridgeService {
             if (!repository.bindingPath) {
                 const resolved = await this.dependencies.client.request(endpoints.projectResolve, {
                     method: 'POST',
-                    body: { repoFingerprint: repository.repoFingerprint },
+                    body: {
+                        repoFingerprint: repository.repoFingerprint,
+                        legacyFingerprints: repository.legacyFingerprints,
+                    },
                 });
                 const project = objectValue(resolved.data);
                 const restoreRequired = Boolean(project?.archivedAt);
@@ -182,6 +236,23 @@ export class BridgeService {
     async sessionResume(input) {
         return await this.execute(async () => {
             const repository = await this.dependencies.repositories.resolve(input.repoRoot ?? process.cwd(), input.projectId);
+            const decision = await this.dependencies.repositoryDecisions.load(repository.repoFingerprint);
+            if (decision?.state === 'disabled') {
+                return asJsonValue({
+                    decision: 'disabled',
+                    nextAction: entryNextAction(false, 'disabled'),
+                });
+            }
+            const pendingQuestionnaires = await this.pendingQuestionnaires(repository.repoRoot);
+            const signedIn = (await this.dependencies.browserAuth.status()).authenticated;
+            if (!signedIn && pendingQuestionnaires.length > 0) {
+                return asJsonValue({
+                    authenticated: false,
+                    pendingQuestionnaires,
+                    repository: publicRepository(repository),
+                    nextAction: 'Resume only the pending sign-in questionnaire for this work. Signing in is still required before accessing project memory.',
+                });
+            }
             const authentication = await this.dependencies.browserAuth.ensureAuthenticated();
             if (authentication) {
                 return asJsonValue({ authentication, repository: publicRepository(repository) });
@@ -201,6 +272,7 @@ export class BridgeService {
                 return asJsonValue({
                     taskChoiceRequired: true,
                     requestedTaskSlug: input.taskSlug,
+                    pendingQuestionnaires,
                     liveTasks: live.map(describePointer),
                     repository: publicRepository(repository),
                 });
@@ -209,6 +281,7 @@ export class BridgeService {
                 return asJsonValue({
                     taskChoiceRequired: true,
                     requestedSessionId: input.sessionId,
+                    pendingQuestionnaires,
                     liveTasks: live.map(describePointer),
                     repository: publicRepository(repository),
                 });
@@ -216,6 +289,7 @@ export class BridgeService {
             if (!pointer && live.length > 1) {
                 return asJsonValue({
                     taskChoiceRequired: true,
+                    pendingQuestionnaires,
                     liveTasks: live.map(describePointer),
                     repository: publicRepository(repository),
                 });
@@ -224,6 +298,13 @@ export class BridgeService {
             const taskSlug = input.taskSlug ?? pointer?.taskSlug;
             const sessionId = input.sessionId ?? pointer?.sessionId;
             if (!projectId || !taskSlug || !sessionId) {
+                if (pendingQuestionnaires.length > 0) {
+                    return asJsonValue({
+                        pendingQuestionnaires,
+                        repository: publicRepository(repository),
+                        nextAction: 'Resume only the pending questionnaire for this work. Unrelated pending questions never block a separate task; continue independently authorized work.',
+                    });
+                }
                 throw refuse('This repository has no live task to resume.', 'session.bootstrap');
             }
             if ((pointer &&
@@ -237,6 +318,7 @@ export class BridgeService {
                 const recoveredClose = await this.retryCloseIntent(repository, pointer);
                 return asJsonValue({
                     backend: { close: recoveredClose },
+                    pendingQuestionnaires,
                     repository: publicRepository(repository),
                     localJournal: await this.dependencies.journal.load(projectId, taskSlug),
                     synchronization: {
@@ -408,6 +490,7 @@ export class BridgeService {
                 backend,
                 repository: publicRepository(repository),
                 localJournal,
+                pendingQuestionnaires,
                 synchronization: {
                     backendSource: responseSource,
                     backendFresh: responseSource !== 'stale_cache',
@@ -1361,6 +1444,7 @@ export class BridgeService {
                 projectName: input.projectName,
                 projectSlug: input.projectSlug ?? slugify(input.projectName),
                 repoFingerprint: repository.repoFingerprint,
+                legacyFingerprints: repository.legacyFingerprints,
                 framework: input.framework,
                 developmentArea: input.developmentArea,
                 figmaConfig: input.figmaConfig,
@@ -1384,6 +1468,7 @@ export class BridgeService {
             const marker = objectValue(data?.marker);
             if (!project ||
                 typeof project.id !== 'string' ||
+                typeof project.repoFingerprint !== 'string' ||
                 !profileResource ||
                 !profileRevision ||
                 !policy ||
@@ -1392,7 +1477,7 @@ export class BridgeService {
                 readDiscoveryUnits(policy).length === 0) {
                 throw refuse('Project setup response is not policy-ready', 'project.setup');
             }
-            const bindingPath = await this.dependencies.repositories.writeBinding(repository.repoRoot, project.id);
+            const bindingPath = await this.dependencies.repositories.writeBinding(repository.repoRoot, project.id, project.repoFingerprint);
             return asJsonValue({ ...data, marker: null, markerPath: null, bindingPath });
         });
     }
@@ -1689,13 +1774,18 @@ export class BridgeService {
                 }
                 const response = await this.dependencies.client.request(endpoints.projectBind(input.projectId), {
                     method: 'POST',
-                    body: { repoFingerprint: repository.repoFingerprint },
+                    body: {
+                        repoFingerprint: repository.repoFingerprint,
+                        legacyFingerprints: repository.legacyFingerprints,
+                    },
                 });
                 const project = objectValue(response.data);
-                if (!project || project.id !== input.projectId) {
+                if (!project ||
+                    project.id !== input.projectId ||
+                    typeof project.repoFingerprint !== 'string') {
                     throw refuse('Project bind response does not match the selected project', 'project.resolve');
                 }
-                const bindingPath = await this.dependencies.repositories.writeBinding(repository.repoRoot, input.projectId);
+                const bindingPath = await this.dependencies.repositories.writeBinding(repository.repoRoot, input.projectId, project.repoFingerprint);
                 return asJsonValue({
                     resolved: true,
                     bound: true,
@@ -1708,7 +1798,10 @@ export class BridgeService {
             }
             const response = await this.dependencies.client.request(endpoints.projectResolve, {
                 method: 'POST',
-                body: { repoFingerprint: repository.repoFingerprint },
+                body: {
+                    repoFingerprint: repository.repoFingerprint,
+                    legacyFingerprints: repository.legacyFingerprints,
+                },
             });
             const project = objectValue(response.data);
             const restoreRequired = Boolean(project?.archivedAt);
@@ -1759,6 +1852,7 @@ export class BridgeService {
                 ? await this.actionableWorkItems(projectId)
                 : [];
             const taskSelectionRequired = liveTasks.length > 0 || workItems.length > 0;
+            const pendingQuestionnaires = state !== 'disabled' ? await this.pendingQuestionnaires(repository.repoRoot) : [];
             return asJsonValue({
                 authenticated,
                 repository: publicRepository(repository),
@@ -1767,15 +1861,18 @@ export class BridgeService {
                 liveTasks,
                 workItems,
                 taskSelectionRequired,
+                ...(state !== 'disabled' ? { pendingQuestionnaires } : {}),
                 client,
                 ...(incomplete && state === 'bound'
                     ? {
                         shippedKnowledgeWarning: 'The backend is not serving all of the knowledge this release ships. Tell the user before relying on the rules: some are missing from the running server, so a review against them is incomplete. The counts and the reason are in client.shippedKnowledge.',
                     }
                     : {}),
-                nextAction: taskSelectionRequired
-                    ? 'Present the live runs and actionable project work items, then ask which one this chat should handle. Resume only the run they choose, or bootstrap a separate run with the chosen workItemId. Another live task never blocks opening this one.'
-                    : entryNextAction(authenticated, state),
+                nextAction: pendingQuestionnaires.length > 0
+                    ? 'Resume only the pending questionnaire for this work with questionnaire.resume before taking action that depends on its answer. Unrelated pending questions never block opening a separate task. Never infer consent from a timeout, dismissal, interrupted turn or missing answer.'
+                    : taskSelectionRequired
+                        ? 'Present the live runs and actionable project work items, then ask which one this chat should handle. Resume only the run they choose, or bootstrap a separate run with the chosen workItemId. Another live task never blocks opening this one.'
+                        : entryNextAction(authenticated, state),
             });
         });
     }

package/runtime/dist/src/runtime/questionnaire-store.js

@@ -0,0 +1,185 @@
+import { randomUUID } from 'node:crypto';
+import { link, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import * as z from 'zod/v4';
+import { assertManagedPath, ensureManagedDirectory, isNodeError, readJson, removeFile, writeJson, } from '../utilities/files.js';
+import { sha256, stableStringify } from '../utilities/hash.js';
+import { assertSafeToPersist } from './offline-outbox.js';
+const identifier = z.string().regex(/^[A-Za-z0-9_-]{1,100}$/);
+export const questionnaireDefinitionSchema = z.strictObject({
+    questionnaireId: identifier,
+    message: z.string().trim().min(1).max(2000),
+    options: z
+        .array(z.strictObject({
+        id: z
+            .string()
+            .regex(/^[A-Za-z0-9_-]{1,80}$/)
+            .refine((value) => value !== '__other__'),
+        label: z.string().trim().min(1).max(240),
+    }))
+        .min(2)
+        .max(12)
+        .refine((values) => new Set(values.map((value) => value.id)).size === values.length),
+    allowFreeText: z.boolean().default(false),
+});
+const scopeSchema = z.strictObject({
+    principalHash: z.string().regex(/^[0-9a-f]{64}$/),
+    repoFingerprint: z.string().regex(/^[0-9a-f]{64}$/),
+    projectId: z.string().uuid().nullable(),
+});
+const storedQuestionSchema = questionnaireDefinitionSchema.extend({
+    schemaVersion: z.literal(1),
+    scope: scopeSchema,
+    contentHash: z.string().regex(/^[0-9a-f]{64}$/),
+    requestKey: z.string().regex(/^questionnaire_[0-9a-f]{64}$/),
+    createdAt: z.string().datetime(),
+});
+const storedAnswerSchema = z.strictObject({
+    requestKey: z.string().regex(/^questionnaire_[0-9a-f]{64}$/),
+    answeredAt: z.string().datetime(),
+    answerAvailable: z.boolean(),
+    answer: z.strictObject({ choice: z.string() }).optional(),
+});
+export function questionnaireAnswerSchema(record) {
+    return z
+        .strictObject({
+        choice: z.enum([
+            ...record.options.map((option) => option.id),
+            ...(record.allowFreeText ? ['__other__'] : []),
+        ]),
+        text: z.preprocess((value) => (typeof value === 'string' && value.trim() === '' ? undefined : value), record.allowFreeText ? z.string().trim().min(1).max(2000).optional() : z.never().optional()),
+    })
+        .refine((answer) => answer.choice === '__other__' ? typeof answer.text === 'string' : answer.text === undefined);
+}
+export class QuestionnaireStore {
+    root;
+    constructor(stateRoot) {
+        this.root = join(stateRoot, 'questionnaires');
+    }
+    async ask(scope, input) {
+        const definition = questionnaireDefinitionSchema.parse(input);
+        scopeSchema.parse(scope);
+        assertSafeToPersist(definition);
+        const contentHash = sha256(stableStringify(definition));
+        const question = {
+            ...definition,
+            schemaVersion: 1,
+            scope,
+            contentHash,
+            requestKey: `questionnaire_${sha256(`${stableStringify(scope)}\n${contentHash}\n${randomUUID()}`)}`,
+            createdAt: new Date().toISOString(),
+        };
+        await this.publish(this.pathFor(scope, definition.questionnaireId, 'pending.json'), question);
+        const record = await this.get(scope, definition.questionnaireId);
+        if (!record || record.contentHash !== contentHash) {
+            throw new Error('Questionnaire id was reused with different content. Resume the original question or use a new id.');
+        }
+        return record;
+    }
+    async get(scope, questionnaireId) {
+        const raw = await readJson(this.pathFor(scope, questionnaireId, 'pending.json'), this.root);
+        if (!raw)
+            return null;
+        const question = storedQuestionSchema.parse(raw);
+        const definition = questionnaireDefinitionSchema.parse({
+            questionnaireId: question.questionnaireId,
+            message: question.message,
+            options: question.options,
+            allowFreeText: question.allowFreeText,
+        });
+        if (stableStringify(question.scope) !== stableStringify(scope) ||
+            question.questionnaireId !== questionnaireId ||
+            question.contentHash !== sha256(stableStringify(definition))) {
+            throw new Error('Questionnaire scope or content does not match its durable record.');
+        }
+        assertSafeToPersist(question);
+        const rawAnswer = await readJson(this.pathFor(scope, questionnaireId, 'answer.json'), this.root);
+        if (!rawAnswer)
+            return { ...question, status: 'pending' };
+        const answer = storedAnswerSchema.parse(rawAnswer);
+        if (answer.requestKey !== question.requestKey ||
+            (answer.answerAvailable
+                ? !answer.answer || !question.options.some((option) => option.id === answer.answer.choice)
+                : !question.allowFreeText || answer.answer !== undefined)) {
+            throw new Error('Questionnaire answer does not match its durable question.');
+        }
+        assertSafeToPersist(answer);
+        return { ...question, ...answer, status: 'answered' };
+    }
+    async pending(scope) {
+        const directory = this.scopeRoot(scope);
+        await ensureManagedDirectory(this.root, directory);
+        const entries = await readdir(directory, { withFileTypes: true });
+        const records = [];
+        for (const entry of entries) {
+            if (!/^[0-9a-f]{64}$/.test(entry.name))
+                continue;
+            if (!entry.isDirectory() || entry.isSymbolicLink())
+                throw new Error('Unsafe questionnaire directory.');
+            const path = await assertManagedPath(this.root, join(directory, entry.name, 'pending.json'), true);
+            const raw = await readJson(path, this.root);
+            if (!raw)
+                continue;
+            const question = storedQuestionSchema.parse(raw);
+            if (sha256(question.questionnaireId) !== entry.name)
+                throw new Error('Questionnaire directory does not match its id.');
+            const record = await this.get(scope, question.questionnaireId);
+            if (record?.status === 'pending')
+                records.push(record);
+        }
+        return records.sort((left, right) => left.createdAt.localeCompare(right.createdAt));
+    }
+    async accept(scope, questionnaireId, requestKey, input) {
+        const record = await this.get(scope, questionnaireId);
+        if (!record || record.requestKey !== requestKey)
+            throw new Error('Questionnaire response is stale or belongs to a different scope.');
+        const answer = questionnaireAnswerSchema(record).parse(input);
+        if (record.status === 'answered') {
+            if (record.answer && stableStringify(record.answer) !== stableStringify(answer))
+                throw new Error('Questionnaire was already answered differently.');
+            return { record, answer: record.answer, replayed: true };
+        }
+        const receipt = {
+            requestKey,
+            answeredAt: new Date().toISOString(),
+            answerAvailable: answer.choice !== '__other__',
+            ...(answer.choice !== '__other__' ? { answer: { choice: answer.choice } } : {}),
+        };
+        const published = await this.publish(this.pathFor(scope, questionnaireId, 'answer.json'), receipt);
+        const resolved = (await this.get(scope, questionnaireId));
+        if (!published &&
+            resolved.answer &&
+            stableStringify(resolved.answer) !== stableStringify(answer))
+            throw new Error('Questionnaire was already answered differently.');
+        return { record: resolved, answer: published ? answer : resolved.answer, replayed: !published };
+    }
+    scopeRoot(scope) {
+        scopeSchema.parse(scope);
+        return join(this.root, scope.principalHash, sha256(`${scope.repoFingerprint}\n${scope.projectId ?? ''}`));
+    }
+    pathFor(scope, questionnaireId, filename) {
+        identifier.parse(questionnaireId);
+        return join(this.scopeRoot(scope), sha256(questionnaireId), filename);
+    }
+    async publish(path, value) {
+        assertSafeToPersist(value);
+        const temporaryPath = `${path}.${randomUUID()}.tmp`;
+        await writeJson(temporaryPath, value, this.root);
+        try {
+            const target = await assertManagedPath(this.root, path, true);
+            try {
+                await link(temporaryPath, target);
+                return true;
+            }
+            catch (error) {
+                if (isNodeError(error) && error.code === 'EEXIST')
+                    return false;
+                throw error;
+            }
+        }
+        finally {
+            await removeFile(temporaryPath, this.root);
+        }
+    }
+}
+//# sourceMappingURL=questionnaire-store.js.map

package/runtime/dist/src/utilities/files.js

@@ -136,7 +136,14 @@ export async function ensureManagedDirectory(root, directory) {
             if (!isNodeError(error) || error.code !== 'ENOENT') {
                 throw error;
             }
-            await mkdir(current, { mode: 0o700 });
+            try {
+                await mkdir(current, { mode: 0o700 });
+            }
+            catch (creationError) {
+                if (!isNodeError(creationError) || creationError.code !== 'EEXIST') {
+                    throw creationError;
+                }
+            }
             const created = await lstat(current);
             if (!created.isDirectory() || created.isSymbolicLink()) {
                 throw new Error(`Managed directory could not be created safely: ${current}`);

package/skill/SKILL.md

@@ -11,7 +11,7 @@ Read [lifecycle.md](references/lifecycle.md) before acting in a bound repository
 
 Mandatory behavior:
 
-Use the host's native questionnaire for every question to the user, including implementation choices, names, clarification, branch/worktree decisions and delivery. In Codex use request_user_input when available; in Claude use AskUserQuestion. Never replace the questionnaire with a chat instruction such as 'type this', 'reply yes', or 'write X if you want Y'. Do not open a survey web page. If the required native control is unavailable or prohibited for that kind of question, follow the host's tool restrictions, explain the limitation, and continue only work already authorized; do not fabricate a survey or silently choose an answer. Existing answers remain valid through retries and handoffs.
+Use the host's native questionnaire for every question to the user, including implementation choices, names, clarification, branch/worktree decisions and delivery. For a required decision, read [questionnaires.md](references/questionnaires.md), then use `questionnaire.ask` to open a durable native MCP form and `questionnaire.resume` to return to the same unanswered question. Never use request_user_input_async for a required decision: it does not wait for an answer. When the durable form is unavailable, use a blocking native control only where the host permits it: request_user_input in Codex or AskUserQuestion in Claude. Never replace the questionnaire with a chat instruction such as 'type this', 'reply yes', or 'write X if you want Y'. Do not open a survey web page. If the required native control is unavailable or prohibited for that kind of question, follow the host's tool restrictions, explain the limitation, and continue only work already authorized; do not fabricate a survey or silently choose an answer. A timeout, dismissed form, empty response or ended turn is not an answer. Keep the decision pending and resume it; do not start dependent work or report it as resolved. Existing answers remain valid through retries and handoffs.
 
 1. Discover the repository binding through `session.entry`. Bindings live in the user-level Engineering Memory state directory, outside the repository and installed runtime. No project settings file is required. For a bound repository, the project's knowledge is in the backend, so answer nothing about it before bootstrapping; the absence of local design files or records says nothing about its stored knowledge.
 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.

package/skill/references/lifecycle.md

@@ -4,7 +4,7 @@
 
 Sign-in decides nothing beyond who the user is. The organization and the project are chosen after it, through the questionnaires in `questionnaires.md`, and both listings end with an option to create a new one. Ask for both whenever this session has not already confirmed them, and ask again the moment the user says they want to change either — changing the organization always means choosing the project again.
 
-Use the binding returned by `session.entry` as the authority. The bridge stores the selected project and repository identity under `~/.engineering-memory/origins/<api-hash>/project-bindings/`, outside the installed runtime and working tree. It imports a legacy `.engineering-memory/project.json` once, preserving its schema and exact backend fingerprint for existing tasks and receipts. It leaves that file unchanged; after migration the file is optional and may be removed through the repository's normal Git workflow. New bindings never create it. Never infer a selection from a directory or remote, and never edit binding records by hand. Separate clones or a changed remote require a new explicit selection; worktrees of the same checkout share the local binding.
+Use the binding returned by `session.entry` as the authority. The bridge stores the selected project and repository identity under `~/.engineering-memory/origins/<api-hash>/project-bindings/`, outside the installed runtime and working tree. It imports a legacy `.engineering-memory/project.json` once, preserving its schema and exact backend fingerprint for existing tasks and receipts. It leaves that file unchanged; after migration the file is optional and may be removed through the repository's normal Git workflow. New bindings never create it. A checkout that never imported the marker still finds a project bound under the older identity: the bridge presents that identity alongside the current one and stores whichever the backend confirms. Never infer a selection from a directory or remote, and never edit binding records by hand. Separate clones or a changed remote require a new explicit selection; worktrees of the same checkout share the local binding.
 
 An archived project is recoverable state, not a missing or conflicting binding. When an owner receives `project.restore`, use the `projectId` and `expectedVersion` in its data and call that operation before retrying. A non-owner receives `project.member_list` instead: list the members, identify a project owner and explain that the owner must restore the exact project before this session can retry. Use `project.list` with `includeArchived: true` when an owner must first select the archived project. Never create or bind a replacement project to escape archive state.
 
@@ -22,6 +22,8 @@ A task nobody is going to finish is abandoned rather than inherited. Ask the use
 
 If an existing task is identified or execution resumes after compaction, call `session.resume`. Reconcile backend sequence, local outbox, Markdown projections, current Git diff, pinned revisions, and the active lease before any further action.
 
+Reconcile pending questions too. A required question remains unanswered across a timeout, dismissed form, interruption or restart. Use `questionnaire.resume` for its recorded identifier and wait for an explicit valid response before dependent work. Follow `questionnaires.md`; do not create a replacement async prompt or consume an unrelated task's answer.
+
 ## Discovery
 
 Perform only read operations until the relevant current code, tests, Figma evidence, Git diff, and returned memory have been inspected.

package/skill/references/questionnaires.md

@@ -1,6 +1,24 @@
 # Native Questionnaires
 
-Use the host's native questionnaire for every question to the user, including implementation choices, names, clarification, branch/worktree decisions and delivery. In Codex use request_user_input when available; in Claude use AskUserQuestion. Never replace the questionnaire with a chat instruction such as 'type this', 'reply yes', or 'write X if you want Y'. Do not open a survey web page. If the required native control is unavailable or prohibited for that kind of question, follow the host's tool restrictions, explain the limitation, and continue only work already authorized; do not fabricate a survey or silently choose an answer. Existing answers remain valid through retries and handoffs. Web pages are limited to sign in, sign up, initial password change, and email verification.
+Use the host's native questionnaire for every question to the user, including implementation choices, names, clarification, branch/worktree decisions and delivery. Existing answers remain valid through retries and handoffs. Web pages are limited to sign in, sign up, initial password change, and email verification.
+
+## Required decisions stay pending
+
+Use `questionnaire.ask` for a required decision. It records the question before opening a native MCP form. Use a stable question identifier belonging to the current task and decision, so a retry returns to the same question instead of creating another one. A new decision needs its own identifier; an answer to an earlier proposal, branch or delivery does not approve a later one.
+
+Pass `repoRoot`, `questionnaireId`, `message` and two to twelve `options`, each with an `id` and `label`. Identifiers use letters, digits, underscores or hyphens. Set `allowFreeText` only when the user needs to give an answer outside those options. `questionnaire.resume` takes the same `repoRoot` and `questionnaireId`. These tools collect decisions; they do not commit, publish, bind a project or perform the selected action. Apply the accepted answer through the relevant lifecycle tool, checking the current target and version first.
+
+Fixed-choice answers can be replayed from the local receipt. Free text is returned only in the accepting call and is never stored. If a later receipt says the answer is unavailable, recover it from the user's actual answer in the conversation; never reconstruct it from the options. If it cannot be recovered, explain that it must be requested again using a new question identifier.
+
+Read pending questions returned by `session.entry` and `session.resume`. Call `questionnaire.resume` for the question belonging to this work. Do not silently adopt a pending question from another task. Resuming uses the original question; do not rewrite its options under the same identifier.
+
+Only an explicit, valid accepted response answers a question. A timeout, dismissed form, empty response, invalid response, connection loss or ended turn is not an answer. These events leave the decision pending. Never substitute the recommended choice or treat silence as consent. The form's cancel or decline button dismisses the form; if abandoning the work is a meaningful decision, offer it as an explicit answer in the question.
+
+Never use request_user_input_async for a required decision: it does not wait for an answer. Do not end a turn while a required native form is still awaiting the user. Work that does not depend on the answer may continue. If the host removes the form or interrupts the tool call, retain the pending decision and resume that same question when the user returns. Do not automatically reopen dismissed forms in a loop, or use repeated sleeps to claim that a host timer has been disabled.
+
+The host owns the visible form and may impose a transport deadline or close it when the application exits. Engineering Memory preserves the decision without an expiry; it cannot promise that every host keeps a window visible indefinitely. If the host cannot display the form, report that limitation and the pending question identifier. Use a blocking native control only where the host permits it: request_user_input in Codex or AskUserQuestion in Claude. Follow the host's tool restrictions. Never fabricate an answer, silently fall back to an asynchronous question, or begin work that requires the missing decision.
+
+Never replace the questionnaire with a chat instruction such as 'type this', 'reply yes', or 'write X if you want Y'. Do not open a survey web page. Questions and saved answers must not contain credentials, personal data or production payloads. Authentication secrets belong in the existing browser authentication flow. Use an appropriate permitted native control for information that cannot be persisted; do not put it into a durable question's title, options or stored answer.
 
 ## Authentication