engineering-memory 1.10.3 → 1.10.5

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

@@ -1,6 +1,9 @@
 import { randomUUID } from 'node:crypto';
-import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { lstat, readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { SourceSnapshot } from '../git/source-snapshot.js';
+import { ProjectIntake } from '../project/project-intake.js';
+import { canonicalPath } from '../utilities/files.js';
 import { minimatch } from 'minimatch';
 import { endpoints } from '../config.js';
 import { sha256, stableStringify } from '../utilities/hash.js';
@@ -33,32 +36,64 @@ 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 questionnaireAsk(input, previousDefinitions = []) {
+        const scope = await this.questionnaireScope(input.repoRoot, input.preparation);
+        const { repoRoot: _repoRoot, preparation: _preparation, ...definition } = input;
+        return await this.dependencies.questionnaires.ask(scope, definition, previousDefinitions);
     }
     async questionnaireResume(input) {
-        const scope = await this.questionnaireScope(input.repoRoot);
+        const scope = await this.questionnaireScope(input.repoRoot, input.preparation);
         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 questionnaireWithdraw(input) {
+        const scope = await this.questionnaireScope(input.repoRoot, input.preparation);
+        return this.dependencies.questionnaires.withdraw(scope, input.questionnaireId);
+    }
     async questionnaireAccept(input) {
-        const scope = await this.questionnaireScope(input.repoRoot);
+        const scope = await this.questionnaireScope(input.repoRoot, input.preparation);
         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) {
+    async questionnaireScope(repoRoot, preparation = false) {
         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);
+        const target = await canonicalPath(repoRoot ?? process.cwd());
+        let lookup = target;
+        if (preparation) {
+            for (;;) {
+                try {
+                    await lstat(lookup);
+                    break;
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT' || dirname(lookup) === lookup)
+                        throw error;
+                    lookup = dirname(lookup);
+                }
+            }
+        }
+        let repository;
+        try {
+            repository = await this.dependencies.repositories.resolve(lookup);
+        }
+        catch (error) {
+            if (!preparation ||
+                !(error instanceof Error) ||
+                !error.message.startsWith('Not a Git repository:'))
+                throw error;
+        }
+        const decision = repository
+            ? await this.dependencies.repositoryDecisions.load(repository.repoFingerprint)
+            : null;
         if (decision?.state === 'disabled')
             throw refuse('Engineering Memory is disabled in this repository.', 'session.entry');
+        if (preparation && repository?.projectId)
+            throw refuse('This target is already inside a bound project. Use its normal questionnaire scope.', 'session.entry');
         const principalHash = accessToken ? principalFingerprint(accessToken) : sha256('anonymous');
         const currentCredential = await this.dependencies.credentials.get('access-token');
         if (principalHash !==
@@ -67,8 +102,10 @@ export class BridgeService {
         }
         return {
             principalHash,
-            repoFingerprint: repository.repoFingerprint,
-            projectId: repository.projectId,
+            repoFingerprint: preparation
+                ? sha256('preparation:' + (process.platform === 'win32' ? target.toLowerCase() : target))
+                : repository.repoFingerprint,
+            projectId: preparation ? null : repository.projectId,
         };
     }
     async pendingQuestionnaires(repoRoot) {
@@ -78,9 +115,10 @@ export class BridgeService {
             message: record.message,
             options: record.options,
             allowFreeText: record.allowFreeText,
+            ...(record.textField ? { textField: record.textField } : {}),
             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.',
+            nextAction: 'Call questionnaire.resume with this questionnaireId. No answer, elapsed time, dismissal or interruption is consent. If the user explicitly cancels this decision, call questionnaire.withdraw. Unrelated pending decisions never block independently authorized work.',
         }));
     }
     deliverInBackground() {
@@ -819,6 +857,264 @@ export class BridgeService {
             return await this.mutateWithOutbox('memory.propose_revision', endpoints.memoryProposeRevision, body);
         });
     }
+    async projectInspect(input) {
+        return this.execute(async () => asJsonValue(await new ProjectIntake().inspect(input.repoRoot)));
+    }
+    async onboardingChoice(input) {
+        return this.execute(async () => {
+            const scope = await this.questionnaireScope(input.repoRoot, input.preparation);
+            if (!this.dependencies.onboarding)
+                throw refuse('Update the client to persist onboarding choices.', 'session.entry');
+            if (input.choice) {
+                if (input.choice.requestKey !== input.requestKey)
+                    throw refuse('Keep the onboarding request identity unchanged.', 'session.entry');
+                const question = input.questionnaireId
+                    ? await this.dependencies.questionnaires.get(scope, input.questionnaireId)
+                    : null;
+                const digest = sha256(stableStringify(input.choice));
+                if (question?.answer?.choice !== 'approve' || !question.message.includes(digest))
+                    throw refuse('Approve the exact mode and profile through project.onboard before continuing.', 'session.entry');
+                return asJsonValue(await this.dependencies.onboarding.save(scope, input.choice));
+            }
+            return asJsonValue(await this.dependencies.onboarding.get(scope, input.requestKey));
+        });
+    }
+    async projectInitialize(input) {
+        if (input.questionnaireId !==
+            'onboard-profile-' + sha256(stableStringify(input.choice)) + '-initialize')
+            return this.execute(async () => {
+                throw refuse('Confirm Git preparation through project.initialize; a saved profile does not authorize initialization.', 'session.entry');
+            });
+        const stored = await this.onboardingChoice(input);
+        if (!stored.ok)
+            return stored;
+        return this.execute(async () => {
+            if (input.choice.mode !== 'greenfield')
+                throw refuse('Only the greenfield choice initializes Git. Use project.onboard for adoption or rework.', 'session.entry');
+            return asJsonValue({
+                ...(await new ProjectIntake().initialize(input.repoRoot)),
+                onboarding: stored.data,
+            });
+        });
+    }
+    async memorySource(input) {
+        return this.execute(async () => {
+            const repository = await this.dependencies.repositories.resolve(input.repoRoot);
+            const snapshot = new SourceSnapshot();
+            if (input.previousCommit) {
+                const history = await snapshot.history(repository.repoRoot, input.previousCommit, input.commit ?? input.ref ?? 'HEAD');
+                const paths = history.changes.changedPaths.filter((path) => !input.afterPath || Buffer.compare(Buffer.from(path), Buffer.from(input.afterPath)) > 0);
+                const limit = input.limit ?? 100;
+                const page = new Set(paths.slice(0, limit));
+                return asJsonValue({
+                    previousCommit: history.previousCommit,
+                    currentCommit: history.currentCommit,
+                    fallback: history.fallback ?? null,
+                    recentRelevantCommitIds: history.recentRelevantCommitIds,
+                    historyTruncated: history.historyTruncated,
+                    changedPaths: [...page],
+                    renamed: history.changes.renamed.filter((change) => page.has(change.from) || page.has(change.to)),
+                    added: history.changes.added.filter((path) => page.has(path)),
+                    deleted: history.changes.deleted.filter((path) => page.has(path)),
+                    nextCursor: paths.length > limit ? paths[limit - 1] : null,
+                    ...(history.fallback
+                        ? {
+                            nextAction: 'Use memory.sync_delta against the persisted previous inventory for content comparison. Missing history cannot prove no change.',
+                        }
+                        : {}),
+                });
+            }
+            if (input.path) {
+                if (!input.commit)
+                    throw refuse('Read source only at the inspection commit.', 'memory.sync_status');
+                const content = await snapshot.read(repository.repoRoot, input.commit, input.path, input.maxBytes ?? 1048576);
+                const offset = input.offset ?? 0, size = input.maxCharacters ?? 20000;
+                return asJsonValue({
+                    commit: input.commit,
+                    path: input.path,
+                    content: content.slice(offset, offset + size),
+                    offset,
+                    totalCharacters: content.length,
+                    nextOffset: offset + size < content.length ? offset + size : null,
+                });
+            }
+            const result = await snapshot.snapshot(repository.repoRoot, input.ref ?? 'HEAD');
+            const files = result.files.filter((file) => !input.afterPath ||
+                Buffer.compare(Buffer.from(file.path), Buffer.from(input.afterPath)) > 0);
+            const limit = input.limit ?? 100;
+            return asJsonValue({
+                ...result,
+                files: files.slice(0, limit),
+                totalFiles: result.files.length,
+                nextCursor: files.length > limit ? files[limit - 1].path : null,
+            });
+        });
+    }
+    async memorySyncStart(input) {
+        return this.execute(async () => {
+            const repository = await this.dependencies.repositories.resolve(input.repoRoot, input.projectId);
+            const snapshot = await new SourceSnapshot().snapshot(repository.repoRoot, input.ref ?? 'HEAD');
+            const { questionnaireId, ...confirmedInput } = input;
+            const digest = sha256(stableStringify(confirmedInput));
+            const scope = await this.questionnaireScope(input.repoRoot);
+            const question = await this.dependencies.questionnaires.get(scope, questionnaireId);
+            if (questionnaireId !== 'sync-start-' + digest ||
+                question?.answer?.choice !== 'approve' ||
+                input.ref !== snapshot.commit)
+                throw refuse('Confirm this exact mode and committed source through memory.sync_start before starting the inspection.', 'memory.sync_status');
+            const selected = await this.dependencies.client.request('/memory/onboarding/choose', {
+                method: 'POST',
+                body: cleanJson({
+                    projectId: input.projectId,
+                    requestKey: input.requestKey,
+                    mode: input.mode,
+                    profile: {},
+                    sourceCommit: snapshot.commit,
+                    reworkBehavior: input.reworkBehavior,
+                }),
+            });
+            const body = cleanJson({
+                projectId: input.projectId,
+                requestKey: input.requestKey,
+                mode: input.mode,
+                previousRunId: input.previousRunId,
+                reworkBehavior: input.reworkBehavior,
+                sourceCommit: snapshot.commit,
+                treeHash: snapshot.treeHash,
+                manifestHash: snapshot.manifestHash,
+                expectedFiles: snapshot.files.length,
+            });
+            assertSafeToPersist(body);
+            const response = await this.dependencies.client.request('/memory/sync/start', {
+                method: 'POST',
+                body,
+            });
+            const run = objectValue(response.data);
+            if (!run || typeof run.id !== 'string')
+                throw refuse('The inspection response has no run identity.', 'memory.sync_status');
+            if (run.state === 'inventory' || run.state === 'planning') {
+                for (let offset = 0; offset < snapshot.files.length; offset += 1000) {
+                    const page = cleanJson({
+                        projectId: input.projectId,
+                        runId: run.id,
+                        files: snapshot.files.slice(offset, offset + 1000),
+                    });
+                    assertSafeToPersist(page);
+                    await this.dependencies.client.request('/memory/sync/inventory', {
+                        method: 'POST',
+                        body: page,
+                    });
+                }
+                await this.dependencies.client.request('/memory/sync/inventory', {
+                    method: 'POST',
+                    body: cleanJson({ projectId: input.projectId, runId: run.id, files: [], seal: true }),
+                });
+            }
+            return asJsonValue({
+                runId: run.id,
+                onboarding: selected.data,
+                sourceCommit: snapshot.commit,
+                sourceRef: input.ref ?? 'HEAD',
+                checkedOutBranch: await this.dependencies.repositories.git.currentBranch(repository.repoRoot),
+                manifestHash: snapshot.manifestHash,
+                files: snapshot.files.length,
+                workingTreeExcluded: true,
+                nextAction: 'Read memory.source at this commit, plan semantic units across architecture, state, services, network, data, screens and flows; then seal the coverage plan.',
+            });
+        });
+    }
+    async memorySyncStatus(input) {
+        const { repoRoot, ...request } = input;
+        const result = await this.onboardingRequest('status', cleanJson(request));
+        if (!result.ok || !repoRoot || !input.runId)
+            return result;
+        return this.execute(async () => {
+            const repository = await this.dependencies.repositories.resolve(repoRoot, input.projectId);
+            const data = objectValue(result.data), run = objectValue(data?.run);
+            return asJsonValue({
+                ...data,
+                checkedOutHead: repository.git.head,
+                sourceMatchesCheckout: run?.sourceCommit === repository.git.head,
+                ...(run?.sourceCommit !== repository.git.head
+                    ? {
+                        sourceNotice: 'The checkout differs from the pinned inspection. Keep analyzing the pinned source; record a follow-up refresh for newer desired changes, and never report this source as the current checkout.',
+                    }
+                    : {}),
+            });
+        });
+    }
+    async memorySyncDelta(input) {
+        const { repoRoot, ...request } = input;
+        const delta = await this.onboardingRequest('delta', cleanJson(request));
+        if (!delta.ok || !repoRoot || input.afterId)
+            return delta;
+        const current = await this.onboardingRequest('status', cleanJson({ projectId: input.projectId, runId: input.runId, limit: 1 }));
+        if (!current.ok)
+            return current;
+        const run = objectValue(objectValue(current.data)?.run);
+        if (typeof run?.previousRunId !== 'string' || typeof run.sourceCommit !== 'string')
+            return delta;
+        const previous = await this.onboardingRequest('status', cleanJson({ projectId: input.projectId, runId: run.previousRunId, limit: 1 }));
+        if (!previous.ok)
+            return previous;
+        const prior = objectValue(objectValue(previous.data)?.run);
+        if (typeof prior?.sourceCommit !== 'string')
+            return delta;
+        const history = await this.memorySource({
+            repoRoot,
+            commit: run.sourceCommit,
+            previousCommit: prior.sourceCommit,
+            limit: 100,
+        });
+        return {
+            ok: true,
+            data: asJsonValue({
+                ...objectValue(delta.data),
+                sourceHistory: history.ok
+                    ? history.data
+                    : { unavailable: true, contentComparisonAuthoritative: true },
+            }),
+        };
+    }
+    async onboardingRequest(operation, body) {
+        return this.execute(async () => {
+            assertSafeToPersist(body);
+            const routes = {
+                status: '/memory/sync/status',
+                inventory: '/memory/sync/inventory',
+                plan: '/memory/sync/plan',
+                next: '/memory/sync/next',
+                submit: '/memory/sync/submit',
+                verify: '/memory/sync/verify',
+                reopen: '/memory/sync/reopen',
+                delta: '/memory/sync/delta',
+                catalog: '/memory/catalog',
+                read_revisions: '/memory/revisions/read',
+                review_batch: '/memory/proposals/review-batch',
+                onboarding_choose: '/memory/onboarding/choose',
+                onboarding_status: '/memory/onboarding/status',
+                rework: '/memory/onboarding/rework',
+            };
+            const response = await this.dependencies.client.request(routes[operation], {
+                method: 'POST',
+                body,
+            });
+            if (operation === 'review_batch' && Array.isArray(response.data)) {
+                const invalidatedTaskIds = [
+                    ...new Set(response.data.flatMap((item) => {
+                        const value = objectValue(item)?.invalidatedTaskIds;
+                        return Array.isArray(value)
+                            ? value.filter((id) => typeof id === 'string')
+                            : [];
+                    })),
+                ];
+                for (const id of invalidatedTaskIds)
+                    await this.dependencies.gate.invalidateTask(id);
+                await this.dependencies.activeContexts.markTasksConflict(invalidatedTaskIds, 'approved_memory_revision_requires_refresh');
+            }
+            return response.data;
+        });
+    }
     async memoryListProposals(input) {
         return await this.execute(async () => {
             const response = await this.dependencies.client.request(endpoints.memoryListProposals, { method: 'POST', body: cleanJson(input) });
@@ -1825,6 +2121,10 @@ export class BridgeService {
                 repository = await this.dependencies.repositories.resolve(input.repoRoot ?? process.cwd());
             }
             catch (error) {
+                const missingTarget = error.code === 'ENOENT';
+                const outsideGit = error instanceof Error && error.message.startsWith('Not a Git repository:');
+                if (!missingTarget && !outsideGit)
+                    throw error;
                 const authenticated = authentication.authenticated === true;
                 const clonable = authenticated ? await this.clonableProjects() : [];
                 return asJsonValue({
@@ -1832,9 +2132,10 @@ export class BridgeService {
                     repository: null,
                     decision: 'none',
                     clonableProjects: clonable,
-                    nextAction: clonable.length > 0
-                        ? 'This directory is not a Git repository. Offer the listed projects and clone the one the user chooses with project.clone. Do not mention Engineering Memory otherwise.'
-                        : 'This directory is not a Git repository, so Engineering Memory has nothing to bind. Work normally and say nothing about it.',
+                    preparationAvailable: true,
+                    nextAction: !authenticated
+                        ? 'Sign in through auth.signin_browser before binding a project. Native questionnaires may use preparation:true for this target before Git exists.'
+                        : 'No Git repository is bound here. For requested project creation, inspect the selected target with project.inspect, ask greenfield/adopt/rework through questionnaire.ask with preparation:true, then project.initialize if needed and organization/project selection. Existing projects may be cloned from clonableProjects. Never create a folder, choose a mode or bind a project silently.',
                     reason: error instanceof Error ? error.message : String(error),
                 });
             }

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

@@ -0,0 +1,47 @@
+import { randomUUID } from 'node:crypto';
+import { link } from 'node:fs/promises';
+import { join } from 'node:path';
+import { assertManagedPath, readJson, removeFile, writeJson } from '../utilities/files.js';
+import { sha256, stableStringify } from '../utilities/hash.js';
+import { assertSafeToPersist } from './offline-outbox.js';
+export class OnboardingStore {
+    root;
+    constructor(stateRoot) {
+        this.root = join(stateRoot, 'onboarding-choices');
+    }
+    async get(scope, requestKey) {
+        const value = await readJson(this.path(scope, requestKey), this.root);
+        if (value && value.requestKey !== requestKey)
+            throw new Error('Invalid onboarding choice identity');
+        return value;
+    }
+    async save(scope, choice) {
+        assertSafeToPersist(choice);
+        const path = this.path(scope, choice.requestKey);
+        const temporary = `${path}.${randomUUID()}.tmp`;
+        await writeJson(temporary, choice, this.root);
+        try {
+            const target = await assertManagedPath(this.root, path, true);
+            try {
+                await link(temporary, target);
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+            }
+        }
+        finally {
+            await removeFile(temporary, this.root);
+        }
+        const saved = await this.get(scope, choice.requestKey);
+        if (!saved || stableStringify(saved) !== stableStringify(choice))
+            throw new Error('This request already has a different onboarding choice. Use a new request key.');
+        return saved;
+    }
+    path(scope, requestKey) {
+        if (!/^[A-Za-z0-9_-]{1,120}$/.test(requestKey))
+            throw new Error('Invalid onboarding request key');
+        return join(this.root, sha256(stableStringify(scope)), sha256(requestKey) + '.json');
+    }
+}
+//# sourceMappingURL=onboarding-store.js.map

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

@@ -9,6 +9,10 @@ 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),
+    language: z
+        .enum(['tr', 'en'])
+        .optional()
+        .describe('Language of the current conversation: tr for Turkish, en for English. Translate the message and option labels into that language too.'),
     options: z
         .array(z.strictObject({
         id: z
@@ -21,6 +25,17 @@ export const questionnaireDefinitionSchema = z.strictObject({
         .max(12)
         .refine((values) => new Set(values.map((value) => value.id)).size === values.length),
     allowFreeText: z.boolean().default(false),
+    textField: z
+        .strictObject({
+        title: z.string().trim().min(1).max(120),
+        maxLength: z.number().int().min(1).max(2000),
+        requiredForChoice: z
+            .string()
+            .regex(/^[A-Za-z0-9_-]{1,80}$/)
+            .optional(),
+        valueType: z.enum(['text', 'uuid_list']).optional(),
+    })
+        .optional(),
 });
 const scopeSchema = z.strictObject({
     principalHash: z.string().regex(/^[0-9a-f]{64}$/),
@@ -38,26 +53,62 @@ 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(),
+    withdrawn: z.literal(true).optional(),
+    answer: z.strictObject({ choice: z.string(), text: z.string().optional() }).optional(),
 });
 export function questionnaireAnswerSchema(record) {
+    const textSchema = record.textField
+        ? record.textField.valueType === 'uuid_list'
+            ? z
+                .string()
+                .trim()
+                .min(2)
+                .max(record.textField.maxLength)
+                .refine((value) => {
+                try {
+                    const parsed = JSON.parse(value);
+                    if (!Array.isArray(parsed) || new Set(parsed).size !== parsed.length)
+                        return false;
+                    return z.array(z.string().uuid()).max(10).safeParse(parsed).success;
+                }
+                catch {
+                    return false;
+                }
+            }, 'Enter a JSON array containing valid project IDs.')
+                .optional()
+            : z.string().trim().min(1).max(record.textField.maxLength).optional()
+        : record.allowFreeText
+            ? z.string().trim().min(1).max(2000).optional()
+            : z.never().optional();
     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()),
+        text: z.preprocess((value) => (typeof value === 'string' && value.trim() === '' ? undefined : value), textSchema),
     })
-        .refine((answer) => answer.choice === '__other__' ? typeof answer.text === 'string' : answer.text === undefined);
+        .refine((answer) => {
+        if (record.textField?.requiredForChoice === answer.choice)
+            return typeof answer.text === 'string';
+        if (answer.choice === '__other__')
+            return typeof answer.text === 'string';
+        return answer.text === undefined;
+    });
 }
 export class QuestionnaireStore {
     root;
     constructor(stateRoot) {
         this.root = join(stateRoot, 'questionnaires');
     }
-    async ask(scope, input) {
+    async ask(scope, input, previousDefinitions = []) {
         const definition = questionnaireDefinitionSchema.parse(input);
+        const previousHashes = previousDefinitions.map((previous) => {
+            const parsed = questionnaireDefinitionSchema.parse(previous);
+            if (parsed.questionnaireId !== definition.questionnaireId)
+                throw new Error('Previous questionnaire content must belong to the same decision.');
+            return sha256(stableStringify(parsed));
+        });
         scopeSchema.parse(scope);
         assertSafeToPersist(definition);
         const contentHash = sha256(stableStringify(definition));
@@ -71,7 +122,8 @@ export class QuestionnaireStore {
         };
         await this.publish(this.pathFor(scope, definition.questionnaireId, 'pending.json'), question);
         const record = await this.get(scope, definition.questionnaireId);
-        if (!record || record.contentHash !== contentHash) {
+        if (!record ||
+            (record.contentHash !== contentHash && !previousHashes.includes(record.contentHash))) {
             throw new Error('Questionnaire id was reused with different content. Resume the original question or use a new id.');
         }
         return record;
@@ -84,8 +136,10 @@ export class QuestionnaireStore {
         const definition = questionnaireDefinitionSchema.parse({
             questionnaireId: question.questionnaireId,
             message: question.message,
+            language: question.language,
             options: question.options,
             allowFreeText: question.allowFreeText,
+            textField: question.textField,
         });
         if (stableStringify(question.scope) !== stableStringify(scope) ||
             question.questionnaireId !== questionnaireId ||
@@ -97,12 +151,23 @@ export class QuestionnaireStore {
         if (!rawAnswer)
             return { ...question, status: 'pending' };
         const answer = storedAnswerSchema.parse(rawAnswer);
+        if (answer.withdrawn) {
+            if (answer.requestKey !== question.requestKey || answer.answerAvailable || answer.answer)
+                throw new Error('Invalid questionnaire withdrawal receipt.');
+            return { ...question, ...answer, status: 'withdrawn' };
+        }
         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.');
         }
+        if (answer.answer?.text !== undefined && !question.textField)
+            throw new Error('Questionnaire text answer does not match its durable question.');
+        if (question.textField?.requiredForChoice &&
+            question.textField.requiredForChoice === answer.answer?.choice &&
+            typeof answer.answer?.text !== 'string')
+            throw new Error('Questionnaire text answer is required for this choice.');
         assertSafeToPersist(answer);
         return { ...question, ...answer, status: 'answered' };
     }
@@ -133,7 +198,10 @@ export class QuestionnaireStore {
         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.');
+        if (record.status === 'withdrawn')
+            throw new Error('Questionnaire was explicitly withdrawn. Start a new decision if the user resumes the work.');
         const answer = questionnaireAnswerSchema(record).parse(input);
+        assertSafeToPersist(answer);
         if (record.status === 'answered') {
             if (record.answer && stableStringify(record.answer) !== stableStringify(answer))
                 throw new Error('Questionnaire was already answered differently.');
@@ -143,16 +211,34 @@ export class QuestionnaireStore {
             requestKey,
             answeredAt: new Date().toISOString(),
             answerAvailable: answer.choice !== '__other__',
-            ...(answer.choice !== '__other__' ? { answer: { choice: answer.choice } } : {}),
+            ...(answer.choice !== '__other__'
+                ? { answer: { choice: answer.choice, ...(answer.text ? { text: answer.text } : {}) } }
+                : {}),
         };
         const published = await this.publish(this.pathFor(scope, questionnaireId, 'answer.json'), receipt);
         const resolved = (await this.get(scope, questionnaireId));
+        if (resolved.status === 'withdrawn')
+            throw new Error('Questionnaire was explicitly withdrawn before this response.');
         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 };
     }
+    async withdraw(scope, questionnaireId) {
+        const record = await this.get(scope, questionnaireId);
+        if (!record)
+            throw new Error('No questionnaire exists in this scope.');
+        if (record.status !== 'pending')
+            return record;
+        await this.publish(this.pathFor(scope, questionnaireId, 'answer.json'), {
+            requestKey: record.requestKey,
+            answeredAt: new Date().toISOString(),
+            answerAvailable: false,
+            withdrawn: true,
+        });
+        return (await this.get(scope, questionnaireId));
+    }
     scopeRoot(scope) {
         scopeSchema.parse(scope);
         return join(this.root, scope.principalHash, sha256(`${scope.repoFingerprint}\n${scope.projectId ?? ''}`));

package/skill/SKILL.md

@@ -7,7 +7,7 @@ description: Enforces the Engineering Memory lifecycle for Codex and Claude in r
 
 This skill is a thin runtime protocol. It contains no proprietary engineering rules. The task-specific rules, project profile, screen logic, component mappings, service contracts, decisions, and quality gates must come from the Engineering Memory MCP server.
 
-Read [lifecycle.md](references/lifecycle.md) before acting in a bound repository. Read [questionnaires.md](references/questionnaires.md) when authentication, project binding, project creation, membership, correction scope, proposal review, or Git-hook choices require user input. Read [memory-updates.md](references/memory-updates.md) before changing screen, component, service, project, or organization memory. Read [scaffolding.md](references/scaffolding.md) before creating a project from the organization architecture templates or changing a template.
+Read [lifecycle.md](references/lifecycle.md) before acting in a bound repository. Read [project-onboarding.md](references/project-onboarding.md) for greenfield, adopt, rework and refresh flows. Read [questionnaires.md](references/questionnaires.md) when authentication, project binding, project creation, membership, correction scope, proposal review, or Git-hook choices require user input. Read [memory-updates.md](references/memory-updates.md) before changing screen, component, service, project, or organization memory. Read [scaffolding.md](references/scaffolding.md) before creating a project from the organization architecture templates or changing a template.
 
 Mandatory behavior: