engineering-memory 1.11.10 → 1.11.12

package/runtime/dist/src/runtime/offline-outbox.js

@@ -151,10 +151,10 @@ export class OfflineOutbox {
         }
     }
 }
-export function assertSafeToPersist(value, key = '', path = key) {
+export function assertSafeToPersist(value, key = '', path = key, questionText = false) {
     if (typeof value === 'string' || typeof value === 'number') {
         const detector = typeof value === 'string'
-            ? restrictedValueKind(value, key)
+            ? restrictedValueKind(value, key, questionText)
             : restrictedNumberKind(value, key);
         if (detector) {
             throw new Error(`PII or credentials cannot be persisted: ${path || '(value)'} (${detector})`);
@@ -162,7 +162,7 @@ export function assertSafeToPersist(value, key = '', path = key) {
         return;
     }
     if (Array.isArray(value)) {
-        value.forEach((item, index) => assertSafeToPersist(item, key, `${path}[${index}]`));
+        value.forEach((item, index) => assertSafeToPersist(item, key, `${path}[${index}]`, questionText));
         return;
     }
     if (value !== null && typeof value === 'object') {
@@ -171,7 +171,7 @@ export function assertSafeToPersist(value, key = '', path = key) {
             if (field) {
                 throw new Error(`Sensitive field cannot be persisted: ${childPath(path, childKey)} (${field})`);
             }
-            assertSafeToPersist(item, childKey, childPath(path, childKey));
+            assertSafeToPersist(item, childKey, childPath(path, childKey), questionText);
         });
     }
 }

package/runtime/dist/src/runtime/privacy-detector.js

@@ -13,6 +13,14 @@ const repositoryPathFields = new Set([
     'pathChanges',
     'templatePath',
 ]);
+const questionTextFields = new Set([
+    'message',
+    'context',
+    'example',
+    'label',
+    'description',
+    'title',
+]);
 const topLevelDomains = new Set([
     'com',
     'net',
@@ -151,8 +159,9 @@ export function restrictedNumberKind(value, key) {
         ? 'phone number'
         : null;
 }
-export function restrictedValueKind(value, key) {
+export function restrictedValueKind(value, key, questionText = false) {
     const repositoryPath = repositoryPathFields.has(key);
+    const prose = questionText && questionTextFields.has(key);
     if (hasEmailAddress(value, repositoryPath))
         return 'email address';
     if (privateKeyPattern.test(value))
@@ -167,9 +176,9 @@ export function restrictedValueKind(value, key) {
         return 'personal home directory';
     if (hasBearerCredential(value))
         return 'bearer credential';
-    if (hasPhoneNumber(value))
+    if (hasPhoneNumber(value, prose))
         return 'phone number';
-    if (!repositoryPath && hasIpv4Address(value))
+    if (!repositoryPath && !prose && hasIpv4Address(value))
         return 'network address';
     if (hasSecretAssignment(value))
         return 'assigned secret';
@@ -234,11 +243,11 @@ function hasIpv4Address(value) {
     }
     return false;
 }
-function hasPhoneNumber(value) {
+function hasPhoneNumber(value, prose = false) {
     const trimmed = value.trim();
     if (uuidPattern.test(trimmed))
         return false;
-    if (/^\d{10,11}$/.test(trimmed))
+    if (!prose && /^\d{10,11}$/.test(trimmed))
         return true;
     if (/(?:^|[^A-Z0-9])0?5\d{2}[\s.-]?\d{3}[\s.-]?\d{2}[\s.-]?\d{2}(?![A-Z0-9])/i.test(value)) {
         return true;

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

@@ -7,12 +7,14 @@ import { sha256, stableStringify } from '../utilities/hash.js';
 import { assertSafeToPersist } from './offline-outbox.js';
 const identifier = z.string().regex(/^[A-Za-z0-9_-]{1,100}$/);
 const questionId = z.string().regex(/^[a-z][a-z0-9_]{0,39}$/);
+export const languageTag = z.string().regex(/^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/);
 const optionSchema = z.strictObject({
     id: z
         .string()
         .regex(/^[A-Za-z0-9_-]{1,80}$/)
-        .refine((value) => value !== '__other__'),
+        .refine((value) => value !== '__other__' && value !== '__explain__'),
     label: z.string().trim().min(1).max(240),
+    description: z.string().trim().min(1).max(400).optional(),
 });
 const textFieldSchema = z.strictObject({
     title: z.string().trim().min(1).max(120),
@@ -27,6 +29,8 @@ const subQuestionSchema = z
     .strictObject({
     id: questionId,
     message: z.string().trim().min(1).max(600),
+    context: z.string().trim().min(1).max(1200).optional(),
+    example: z.string().trim().min(1).max(600).optional(),
     options: z
         .array(optionSchema)
         .min(2)
@@ -73,10 +77,23 @@ function attachDefinitionChecks(schema) {
 const questionnaireDefinitionShape = z.strictObject({
     questionnaireId: identifier,
     message: z.string().trim().min(1).max(2000),
-    language: z
-        .enum(['tr', 'en'])
+    context: z
+        .string()
+        .trim()
+        .min(1)
+        .max(1200)
+        .optional()
+        .describe('Why this is being asked, in the language of the conversation.'),
+    example: z
+        .string()
+        .trim()
+        .min(1)
+        .max(600)
+        .optional()
+        .describe('One concrete example of what the decision changes.'),
+    language: languageTag
         .optional()
-        .describe('Language of the current conversation: tr for Turkish, en for English. Translate the message and option labels into that language too.'),
+        .describe('Language the user is writing in, as a BCP-47 tag such as tr, en or pt-BR. Write the message, context, example, option labels and descriptions in that language too.'),
     options: z
         .array(optionSchema)
         .min(2)
@@ -234,7 +251,7 @@ export class QuestionnaireStore {
         scopeSchema.parse(scope);
         if (owner)
             ownerSchema.parse(owner);
-        assertSafeToPersist(definition);
+        assertSafeToPersist(definition, '', '', true);
         const contentHash = sha256(stableStringify(definition));
         const question = {
             ...definition,
@@ -261,6 +278,8 @@ export class QuestionnaireStore {
         const definition = boundDefinitionSchema.parse({
             questionnaireId: question.questionnaireId,
             message: question.message,
+            context: question.context,
+            example: question.example,
             language: question.language,
             options: question.options,
             allowFreeText: question.allowFreeText,
@@ -274,7 +293,7 @@ export class QuestionnaireStore {
             question.contentHash !== sha256(stableStringify(definition))) {
             throw new Error('Questionnaire scope or content does not match its durable record.');
         }
-        assertSafeToPersist(question);
+        assertSafeToPersist(question, '', '', true);
         const rawAnswer = await readJson(this.pathFor(scope, questionnaireId, 'answer.json'), this.root);
         if (!rawAnswer)
             return { ...question, status: 'pending' };
@@ -427,7 +446,7 @@ export class QuestionnaireStore {
         return join(this.scopeRoot(scope), sha256(questionnaireId), filename);
     }
     async publish(path, value) {
-        assertSafeToPersist(value);
+        assertSafeToPersist(value, '', '', true);
         const temporaryPath = `${path}.${randomUUID()}.tmp`;
         await writeJson(temporaryPath, value, this.root);
         try {

package/runtime/dist/src/runtime/task-start.js

@@ -1,4 +1,44 @@
 import { sha256, stableStringify } from '../utilities/hash.js';
+const startCopy = {
+    en: {
+        start: (task) => `${task}: how should this task start?`,
+        context: 'A task works on its own branch so that unfinished work never mixes with what is already open in this folder. Nothing is created, checked out or reserved until you answer. Your answer is kept, so asking for the same task again does not ask you twice.',
+        example: 'Choosing a separate worktree creates the branch in a folder of its own and leaves this folder on the branch and the files you have open right now.',
+        keepContext: 'This task continues on the branch this folder is already on. Nothing is created, checked out or reserved until you answer. Your answer is kept, so asking for the same task again does not ask you twice.',
+        roles: { development: 'development', production: 'production', test: 'test' },
+        holder: (task, branch, when) => `${task} holds this folder (branch ${branch}, last activity ${when}). If it moves out it stays open, keeps its own branch and continues in a separate worktree when it is resumed.`,
+        unknown: 'unknown',
+        separate: 'A managed folder of its own is prepared and the new branch is created there. This folder is left on its branch and its files are not touched.',
+        inPlace: 'The new branch is created here and this folder is switched to it.',
+        moveOut: (task) => `${task} keeps its branch and its work and continues in a separate worktree later. The new branch is checked out here.`,
+        stay: (source) => `Nothing new is created. The work continues on ${source} in this folder, so every commit lands on that branch.`,
+        later: 'Nothing is created or reserved. The task waits until you ask to start it.',
+        fetched: (role, source) => `The project's ${role} branch ${source} is fetched from the remote and the new branch starts from that exact commit.`,
+        pinned: (source) => `The new branch starts where this folder is right now, ${source}. Nothing is fetched.`,
+        typedBranch: 'Write a branch name on origin below. It is fetched and the new branch starts from it.',
+        suggested: 'The branch is created with this name.',
+        typedName: 'Write the name below. A name that already exists is refused and the form is asked again.',
+    },
+    tr: {
+        start: (task) => `${task} nasıl başlasın?`,
+        context: 'Her görev kendi dalında çalışır; böylece yarım kalan iş, bu klasörde açık olan işe karışmaz. Sen cevaplayana kadar hiçbir klasör açılmaz, hiçbir dal oluşturulmaz, hiçbir yer ayrılmaz. Verdiğin cevap saklanır; aynı görev için ikinci kez sorulmaz.',
+        example: 'Ayrı worktree’yi seçersen yeni dal kendi klasöründe açılır; bu klasör şu anki dalında ve açık dosyalarıyla olduğu gibi kalır.',
+        keepContext: 'Bu görev, klasörün zaten üzerinde olduğu dalda devam eder. Sen cevaplayana kadar hiçbir şey oluşturulmaz, hiçbir yer ayrılmaz. Verdiğin cevap saklanır; aynı görev için yeniden sorulmaz.',
+        roles: { development: 'geliştirme', production: 'canlı', test: 'test' },
+        holder: (task, branch, when) => `${task} görevi bu klasörü tutuyor (dal ${branch}, son etkinlik ${when}). Buradan çıkarılırsa görev kapanmaz; kendi dalını ve işini korur, devam ettiğinde ayrı bir worktree’de açılır.`,
+        unknown: 'bilinmiyor',
+        separate: 'Görev için ayrı bir klasör hazırlanır ve yeni dal orada açılır. Bu klasör kendi dalında kalır, dosyalarına dokunulmaz.',
+        inPlace: 'Yeni dal burada açılır ve bu klasör o dala geçer.',
+        moveOut: (task) => `${task} dalını ve işini korur, sonra ayrı bir worktree’de devam eder. Yeni dal burada açılır.`,
+        stay: (source) => `Yeni bir şey oluşturulmaz. İş bu klasörde ${source} üzerinde sürer; her commit o dala gider.`,
+        later: 'Hiçbir şey oluşturulmaz, hiçbir yer ayrılmaz. Görev sen isteyene kadar beklemede kalır.',
+        fetched: (role, source) => `Projenin ${role} dalı ${source} uzak sunucudan çekilir ve yeni dal tam o commit’ten başlar.`,
+        pinned: (source) => `Yeni dal, bu klasörün şu an üzerinde olduğu ${source} noktasından başlar. Hiçbir şey çekilmez.`,
+        typedBranch: 'origin üzerindeki dal adını aşağıya yaz. O dal çekilir ve yeni dal ondan başlar.',
+        suggested: 'Dal bu adla açılır.',
+        typedName: 'Adı aşağıya yaz. Zaten var olan bir ad kabul edilmez, form yeniden sorulur.',
+    },
+};
 export function suggestedBranchNames(externalTaskId) {
     const slug = externalTaskId
         .replace(/[^A-Za-z0-9._-]+/g, '-')
@@ -34,6 +74,7 @@ export function configuredBase(preferences, role) {
 }
 export function taskStartDefinition(facts) {
     const tr = facts.language === 'tr';
+    const copy = startCopy[tr ? 'tr' : 'en'];
     const folder = facts.folder;
     const keepOnly = facts.keepCurrent === true || !facts.currentCommit;
     const here = !keepOnly && !folder.managed && !folder.heldBy && folder.clean;
@@ -46,14 +87,26 @@ export function taskStartDefinition(facts) {
         currentCommit: facts.currentCommit,
         holder,
     };
+    const heldNotice = here && folder.holder
+        ? copy.holder(folder.holder.externalTaskId, folder.holder.branch ?? 'detached HEAD', readableTime(folder.holder.lastCheckpointAt, tr) ?? copy.unknown)
+        : null;
+    const withheldNotice = withheld(folder, keepOnly, tr);
+    const locationContext = [heldNotice, withheldNotice].filter(Boolean).join(' ');
     const questions = [
         {
             id: 'location',
             message: tr ? 'Nerede başlasın?' : 'Where should it start?',
+            ...(locationContext ? { context: locationContext } : {}),
             options: [
                 ...(keepOnly
                     ? []
-                    : [{ id: 'worktree', label: tr ? 'Ayrı bir worktree’de' : 'In a separate worktree' }]),
+                    : [
+                        {
+                            id: 'worktree',
+                            label: tr ? 'Ayrı bir worktree’de' : 'In a separate worktree',
+                            description: copy.separate,
+                        },
+                    ]),
                 ...(here
                     ? [
                         {
@@ -65,6 +118,7 @@ export function taskStartDefinition(facts) {
                                 : tr
                                     ? 'Bu klasörde yeni branch olarak'
                                     : 'In this folder, as a new branch',
+                            description: holder ? copy.moveOut(holder.externalTaskId) : copy.inPlace,
                         },
                     ]
                     : []),
@@ -75,10 +129,11 @@ export function taskStartDefinition(facts) {
                             label: tr
                                 ? 'Burada, ' + currentLabel + ' üzerinde, yeni branch açmadan'
                                 : 'Here on ' + currentLabel + ', without a new branch',
+                            description: copy.stay(currentLabel),
                         },
                     ]
                     : []),
-                { id: 'defer', label: tr ? 'Şimdilik başlatma' : 'Not now' },
+                { id: 'defer', label: tr ? 'Şimdilik başlatma' : 'Not now', description: copy.later },
             ],
         },
     ];
@@ -92,6 +147,7 @@ export function taskStartDefinition(facts) {
         const roleOption = ({ role, base }) => ({
             id: role,
             label: base.remote + '/' + base.branch + ' (' + role + ')',
+            description: copy.fetched(copy.roles[role], base.remote + '/' + base.branch),
         });
         binding.bases = {
             current: {
@@ -108,9 +164,14 @@ export function taskStartDefinition(facts) {
                 {
                     id: 'current',
                     label: tr ? 'Bu klasörün dalı: ' + currentLabel : 'This folder’s branch: ' + currentLabel,
+                    description: copy.pinned(currentLabel),
                 },
                 ...roles.slice(1).map(roleOption),
-                { id: 'other', label: tr ? 'Başka bir uzak dal' : 'Another remote branch' },
+                {
+                    id: 'other',
+                    label: tr ? 'Başka bir uzak dal' : 'Another remote branch',
+                    description: copy.typedBranch,
+                },
             ],
             otherAsText: true,
             textField: {
@@ -128,8 +189,8 @@ export function taskStartDefinition(facts) {
             id: 'name',
             message: tr ? 'Yeni branch’in adı ne olsun?' : 'What should the new branch be called?',
             options: [
-                { id: 'suggested', label: facts.suggestedName },
-                { id: 'custom', label: tr ? 'Başka bir ad' : 'Another name' },
+                { id: 'suggested', label: facts.suggestedName, description: copy.suggested },
+                { id: 'custom', label: tr ? 'Başka bir ad' : 'Another name', description: copy.typedName },
             ],
             textField: {
                 title: tr ? 'Branch adı' : 'Branch name',
@@ -140,24 +201,7 @@ export function taskStartDefinition(facts) {
     }
     else if (!keepOnly)
         binding.name = facts.name;
-    const fixed = [
-        ...(here && folder.holder
-            ? [
-                tr
-                    ? folder.holder.externalTaskId +
-                        ' bu klasörü tutuyor (branch ' +
-                        (folder.holder.branch ?? 'detached HEAD') +
-                        ', son etkinlik ' +
-                        (folder.holder.lastCheckpointAt ?? 'bilinmiyor') +
-                        '). Çıkarılırsa görev açık kalır ve devam ederken ayrı bir worktree’de açılır.'
-                    : folder.holder.externalTaskId +
-                        ' holds this folder (branch ' +
-                        (folder.holder.branch ?? 'detached HEAD') +
-                        ', last activity ' +
-                        (folder.holder.lastCheckpointAt ?? 'unknown') +
-                        '). If it moves out, it stays open and continues in a separate worktree when resumed.',
-            ]
-            : []),
+    const chosen = [
         ...(binding.base
             ? [
                 tr
@@ -168,25 +212,57 @@ export function taskStartDefinition(facts) {
         ...(binding.name
             ? [tr ? 'Yeni branch: ' + binding.name + '.' : 'New branch: ' + binding.name + '.']
             : []),
-        ...(withheld(folder, keepOnly, tr) ? [withheld(folder, keepOnly, tr)] : []),
     ];
-    const content = {
+    const shared = {
+        language: facts.language,
+        terminalChoices: [
+            { questionId: 'location', choice: 'defer' },
+            ...(keep ? [{ questionId: 'location', choice: 'keep_current' }] : []),
+        ],
+        binding: JSON.parse(JSON.stringify(binding)),
+    };
+    const previous = {
         message: [
             tr
                 ? facts.externalTaskId + ' nasıl başlasın? Sen cevaplayana kadar hiçbir şey oluşturulmaz.'
                 : facts.externalTaskId +
                     ': how should this task start? Nothing is created until you answer.',
-            ...fixed,
+            ...(here && folder.holder
+                ? [
+                    tr
+                        ? folder.holder.externalTaskId +
+                            ' bu klasörü tutuyor (branch ' +
+                            (folder.holder.branch ?? 'detached HEAD') +
+                            ', son etkinlik ' +
+                            (folder.holder.lastCheckpointAt ?? 'bilinmiyor') +
+                            '). Çıkarılırsa görev açık kalır ve devam ederken ayrı bir worktree’de açılır.'
+                        : folder.holder.externalTaskId +
+                            ' holds this folder (branch ' +
+                            (folder.holder.branch ?? 'detached HEAD') +
+                            ', last activity ' +
+                            (folder.holder.lastCheckpointAt ?? 'unknown') +
+                            '). If it moves out, it stays open and continues in a separate worktree when resumed.',
+                ]
+                : []),
+            ...chosen,
+            ...(withheldNotice ? [withheldNotice] : []),
         ].join(' '),
-        language: facts.language,
+        ...shared,
+        questions: questions.map(({ context: _why, options, ...question }) => ({
+            ...question,
+            options: options.map(({ description: _next, ...option }) => option),
+        })),
+    };
+    const questionnaireId = 'task-start-' + sha256(stableStringify(previous));
+    return {
+        questionnaireId,
+        message: [copy.start(facts.externalTaskId), ...chosen].join(' '),
+        context: keepOnly ? copy.keepContext : copy.context,
+        example: keepOnly ? copy.stay(currentLabel) : copy.example,
+        ...shared,
         questions,
-        terminalChoices: [
-            { questionId: 'location', choice: 'defer' },
-            ...(keep ? [{ questionId: 'location', choice: 'keep_current' }] : []),
-        ],
-        binding: JSON.parse(JSON.stringify(binding)),
+        previous: { questionnaireId, ...previous },
     };
-    return { questionnaireId: 'task-start-' + sha256(stableStringify(content)), ...content };
 }
 export function taskStartChoice(record) {
     if (record.status !== 'answered' ||
@@ -264,6 +340,12 @@ function holderIdentity(holder) {
         generation: holder.generation,
     };
 }
+function readableTime(value, tr) {
+    const [, date, time] = /^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2})/.exec(value ?? '') ?? [];
+    if (!date || !time)
+        return null;
+    return (tr ? date.split('-').reverse().join('.') : date) + ' ' + time + ' UTC';
+}
 function withheld(folder, keepOnly, tr) {
     if (keepOnly || folder.managed || (!folder.heldBy && folder.clean))
         return null;

package/runtime/dist/src/runtime/worktree-pool.js

@@ -283,6 +283,10 @@ export class WorktreePool {
         return this.transaction(async (registry) => structuredClone(registry.projects[projectId]?.entries.find((e) => key(e.repoRoot) === key(repoRoot)) ??
             null));
     }
+    async forSlug(projectId, externalTaskId) {
+        return this.transaction(async (registry) => structuredClone(registry.projects[projectId]?.entries.find((e) => e.externalTaskId === externalTaskId) ??
+            null));
+    }
     async validateCommit(projectId, taskId, repoRoot, generation) {
         return this.transaction(async (registry) => {
             const entry = registry.projects[projectId]?.entries.find((e) => key(e.repoRoot) === key(repoRoot));
@@ -457,6 +461,34 @@ export class WorktreePool {
             await this.save(registry);
         });
     }
+    async forgetUnreadable(projectId, externalTaskId, generation) {
+        return this.transaction(async (registry) => {
+            const project = registry.projects[projectId];
+            const entry = project?.entries.find((e) => e.externalTaskId === externalTaskId && e.generation === generation);
+            if (!project || !entry)
+                throw refuse('This is no longer the same registry entry for that task. List the checkouts again with worktree.list before forgetting one.');
+            if (await this.ownedElsewhere(entry))
+                throw refuse('Another live client still owns this task. Stop or pause it there first; worktree.list shows the checkout meanwhile.');
+            if (!(await this.unreadable(entry)))
+                throw new BridgeRecoveryError('This checkout can still be read as a Git worktree, so it is not forgotten. Settle its delivery and free it with worktree.release.', 'worktree.release');
+            project.entries = project.entries.filter((e) => e !== entry);
+            await this.save(registry);
+            return structuredClone(entry);
+        });
+    }
+    async unreadable(entry) {
+        if (!(await pathExists(entry.repoRoot)))
+            return true;
+        try {
+            if (key(await this.git.findRoot(entry.repoRoot)) !== key(await canonicalPath(entry.repoRoot)))
+                return true;
+            await this.commonDirectory(entry.repoRoot);
+            return false;
+        }
+        catch {
+            return true;
+        }
+    }
     async releaseUnowned(projectId, repoRoot, generation, sourceCommit) {
         await this.transaction(async (registry) => {
             const entry = registry.projects[projectId]?.entries.find((e) => key(e.repoRoot) === key(repoRoot));
@@ -832,12 +864,12 @@ export class WorktreePool {
     }
     async fileProtection(entry, allowBranchChange = false) {
         if (!(await pathExists(entry.repoRoot)))
-            return ['worktree directory missing'];
+            return [missingDirectory];
         try {
             await this.assertIdentity(entry, allowBranchChange);
         }
         catch {
-            return ['Git identity or reservation changed or unreadable; reconcile this checkout'];
+            return [(await this.unreadable(entry)) ? unreadableGit : changedIdentity];
         }
         const status = await this.runner.run('git', ['status', '--porcelain=v1', '--untracked-files=all'], { cwd: entry.repoRoot });
         const reasons = [];
@@ -877,7 +909,7 @@ export class WorktreePool {
                 activity: 'retired',
                 reasons: [
                     'outside the managed root ' + managedBase(activeRoot, 2) + '; not reused',
-                    ...((await pathExists(entry.repoRoot)) ? [] : ['worktree directory missing']),
+                    ...((await pathExists(entry.repoRoot)) ? [] : [missingDirectory]),
                 ],
             };
         const reasons = await this.fileProtection(entry);
@@ -1314,6 +1346,12 @@ function processAlive(pid) {
 }
 const changedFiles = 'uncommitted, staged or untracked files';
 const pendingTaskWork = 'task delivery or intent pending';
+const missingDirectory = 'worktree directory missing';
+const changedIdentity = 'Git identity or reservation changed; reconcile this checkout';
+const unreadableGit = 'Git metadata missing or unreadable; this folder is no longer a checkout';
+export function unreadableWorktree(view) {
+    return view.reasons.includes(missingDirectory) || view.reasons.includes(unreadableGit);
+}
 function protectedRefusal(reasons, next) {
     if (reasons.every((reason) => reason === pendingTaskWork))
         return new BridgeRecoveryError('Engineering Memory still holds an undelivered record for this task: a checkpoint, correction or close waiting in its local outbox, or an unfinished verification or close. The folder was left as it is. Settle it with task.resolve_pending_delivery (session.resume finishes an interrupted verification or close), then call worktree.release again.', 'task.resolve_pending_delivery');

package/skill/references/lifecycle.md

@@ -6,6 +6,14 @@ Sign-in decides nothing beyond who the user is. The organization and the project
 
 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.
 
+A project is not tied to one repository forever. When its code moves — to another host, under a new remote, into a history that starts again from one commit — the project moves with it and keeps everything: tasks, memory, work items, open sessions, the local state of every checkout. The old repository stays in the project's history. Recognise the three shapes this takes and never answer any of them by creating a second project:
+
+- Binding the selected project is refused with recovery `project.move_repository`. The project lives in another repository and the user is one of its owners. Call `project.move_repository` with the project id; it opens one native form that names both repositories and what stays with the project, and on approval moves the project and binds this checkout. A declined form changes nothing.
+- The same refusal arrives with recovery `project.member_list`. Moving needs project-owner authority, which the organization owner also holds. Check the roles, say that an owner has to run the move from a checkout of the new repository, and continue only work that does not need the binding. Do not name a person.
+- `session.entry`, `project.resolve` or bootstrap reports `projectMoved`, or bootstrap refuses with "Project moved". This checkout still points at a repository the project has left; the message names where it lives now. Tasks already open here can be resumed and finished. New work starts from the new repository: the user points this checkout's origin at it, or clones it, and selects the project again. An owner calls `project.move_repository` from here only when the code truly lives in this repository again.
+
+After a move nothing else changes for the agent. The binding keeps reporting the identity the project has always had, so resume, verification, receipts and the commit gate behave as they did before.
+
 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: check the available roles and explain that project-owner authority is required to restore this exact project before retrying. Do not name a person or disclose contact details. 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.
 
 For a bound repository, call `session.bootstrap` before producing a plan or changing files. Supply the current repository root, project ID, task ID or stable local task slug, objective, task kind, task mode, and current Git diff hash. `externalTaskId`, `objective`, `taskKind` and `workItemKey` are each one line with a fixed maximum length (160/240/80/120 characters); the bridge refuses an over-length or multi-line value locally, in milliseconds, before any Git or backend work, and names the limit in the refusal — put detail that does not fit in checkpoints, not in the objective. Use `read_only` for review, diagnosis, planning, or reporting without write authority; use `scaffold` when the task applies organization architecture templates to a new project; use `write` when the request authorizes repository changes. The bridge records the read-only Git diff hash as the immutable task baseline, including a pre-existing dirty worktree. Use the returned task ID, task version, context session ID, project profile, engineering rules, prior task documents, quality gates, and current deviations; `deferredResources` names what did not fit, each with the `revisionId` to read it by.
@@ -295,6 +303,13 @@ ownership generation. Cancellation leaves it protected. Git reservation, dirty f
 Git operations and pending work are checked again before release. A changed source requires a new
 inspection and answer. This recovery never deletes files or branches or interrupts another agent.
 
+When a recorded checkout is gone or can no longer be read as a Git worktree — its `.git` was
+deleted, or the repository it was linked to was removed — `worktree.list` names `worktree.reconcile`
+with `forgetUnreadable` and that task's `externalTaskId`, called from a working checkout of the same
+project. After its own native approval Engineering Memory only stops tracking that entry, so it
+stops counting toward the limit; no file in the folder is moved or deleted, the branch and the task
+stay, and a readable checkout is still freed with `worktree.release`.
+
 If the running client predates the pool tools, inspect `git worktree list` and the existing task
 reservations before any explicit allocation. Do not treat an unavailable tool or an empty registry
 as an empty filesystem. Preserve uncertain checkouts and report the client limitation.

package/skill/references/questionnaires.md

@@ -6,7 +6,11 @@ Use the host's native questionnaire for every question to the user, including im
 
 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.
+Pass `repoRoot`, `questionnaireId`, `message` and two to twelve `options`, each with an `id` and `label`. Identifiers use letters, digits, underscores or hyphens.
+
+A question has to be answerable by someone who has not followed the work. Say in `context` why it is being asked, give in `example` one concrete thing the decision changes, and give every option a `description` of what happens next if it is chosen. Show a record, a branch or a project by its title or name; an identifier or a hash in the visible text is refused, and one that really has to be shown goes inside backticks. Write all of it in the language the user is writing in and pass that language as `language`, a BCP-47 tag such as `tr`, `en` or `pt-BR`. The tag is remembered for the account and the computer, so it is asked for once: `session.entry` and every tool that opens a form take the same argument, and `questionnaire.ask` is refused while no language is known.
+
+Every form carries one more choice, "I did not understand; explain in more detail first". It is never recorded as an answer. When a call returns `needs_explanation`, explain in chat why the question is asked, what each option leads to and one example, then show the same question again with `questionnaire.resume`. A free-text reply that says the question was not understood is handled the same way and is not passed on as the decision. 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.
 
@@ -119,6 +123,8 @@ Once the organization is chosen, call `project.list` and offer that organization
 
 The normal list omits archived projects. If repository entry, setup, binding or task open reports `project.restore`, use the project id and expected version returned with that refusal and restore it before continuing. If it reports `project.member_list`, the current member cannot restore the project: call that operation to check the available roles and explain that the versioned restore requires project-owner authority. Do not identify a person, reconstruct an identity from an account identifier or disclose contact details. If an owner does not yet have the project id and expected version, call `project.list` with `includeArchived: true` and let them select the archived project. Archive state never authorizes creating a duplicate project.
 
+When the user picks an existing project and binding it is refused because the project lives in another repository, do not offer to create a new project for the same code. An owner is asked once, through the form `project.move_repository` opens, whether the project moves to this repository; the form already says which repository it leaves, which one it joins and how many tasks, memory records and work items stay with it, so add no second question of your own. Anyone else is told that a project owner runs the move, and is not asked anything.
+
 Ask both questions again whenever a chat starts in a repository whose binding you have not confirmed in this session.
 
 ## Switching Organization or Project
@@ -322,8 +328,9 @@ Saving a profile does not authorize filesystem initialization.
 ## Inspection confirmation language
 
 For memory.sync_start, pass language: tr in a Turkish conversation and language: en in an English
-conversation. Use the conversation language, never the computer locale. Legacy calls without language
-use English. The form shows a short source reference, scope, the treatment of uncommitted changes and
+conversation. Use the conversation language, never the computer locale. A call without language uses
+the language remembered from an earlier call, and English when none is known. The bridge's own forms
+have Turkish and English text; any other language opens them in English. The form shows a short source reference, scope, the treatment of uncommitted changes and
 the separate approval needed for permanent memory. Full commit and request hashes stay in the durable
 approval binding, not in the visible question. Generic questionnaire.ask messages and option labels
 are written by the agent in the same language; pass language for the native help and field labels.
@@ -359,5 +366,12 @@ safety checks still decide whether reuse is possible. Cancellation or choosing t
 release it. Resume the same form via the same operation. A changed source/generation needs a fresh
 decision, and an old answer cannot release a newly owned task.
 
+A checkout that is gone, or that can no longer be read as a Git worktree, is left with
+`worktree.reconcile` and `forgetUnreadable: {"externalTaskId": "..."}` from a working checkout of the
+same project: its native question names the task and the folder name, says that Engineering Memory
+only stops tracking it and touches no file, and warns when that task closed with its delivery
+unsettled. Cancelling or keeping it leaves it tracked, and a readable checkout is refused there and
+freed with `worktree.release` instead.
+
 If the user later reconsiders a preserved legacy checkout, repeat `worktree.reconcile` with a new
 `decisionAttempt`; never reinterpret the previous preserve answer as approval.