engineering-memory 1.8.0 → 1.9.0

package/dispatcher/sections.mjs

@@ -21,6 +21,8 @@ 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.
+
 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.`;
 
 export const dispatcherSections = Object.freeze({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "engineering-memory",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Installs the Engineering Memory skill and its local MCP bridge. Sign in after installing; your organization and project are resolved from your account.",
   "license": "UNLICENSED",
   "type": "module",

package/runtime/dist/src/git/git-inspector.js

@@ -3,6 +3,7 @@ import { isAbsolute, relative, resolve, sep } from 'node:path';
 import { assertManagedPath, canonicalPath } from '../utilities/files.js';
 import { sha256, stableStringify } from '../utilities/hash.js';
 import { NativeCommandRunner } from '../utilities/process.js';
+import { TaskBranchStore } from '../runtime/task-branch-store.js';
 export const temporaryScaffoldingMarker = 'ENGINEERING-MEMORY-TEMPORARY';
 export const temporaryScaffoldingPattern = `${temporaryScaffoldingMarker}:`;
 export class GitInspector {
@@ -33,6 +34,96 @@ export class GitInspector {
         }
         return sha256(identity);
     }
+    branchStore(repoRoot) {
+        return new TaskBranchStore(repoRoot, this.runner);
+    }
+    async validateBranch(repoRoot, name) {
+        const result = await this.runner.run('git', ['check-ref-format', '--branch', name], {
+            cwd: repoRoot,
+        });
+        if (name.length > 255 || result.exitCode !== 0 || result.stdout.trim() !== name)
+            throw new Error('Choose a valid literal Git branch name of at most 255 characters');
+    }
+    async createWorktree(repoRoot, name, target) {
+        await this.validateBranch(repoRoot, name);
+        const path = resolve(repoRoot, target);
+        const present = await lstat(path).then(() => true, (error) => {
+            if (error.code === 'ENOENT')
+                return false;
+            throw error;
+        });
+        if (present) {
+            const root = await this.findRoot(path);
+            const common = await this.gitValue(root, [
+                'rev-parse',
+                '--path-format=absolute',
+                '--git-common-dir',
+            ]);
+            const sourceCommon = await this.gitValue(repoRoot, [
+                'rev-parse',
+                '--path-format=absolute',
+                '--git-common-dir',
+            ]);
+            if (root === (await canonicalPath(path)) &&
+                common === sourceCommon &&
+                (await this.currentBranch(root)) === name)
+                return root;
+            throw new Error('The worktree directory already belongs to another repository or branch. Choose a different directory');
+        }
+        const exists = await this.branchExists(repoRoot, name);
+        const args = exists
+            ? ['worktree', 'add', '--', path, name]
+            : ['worktree', 'add', '-b', name, '--', path];
+        const result = await this.runner.run('git', args, { cwd: repoRoot });
+        if (result.exitCode !== 0)
+            throw new Error(`Git could not create the worktree: ${result.stderr.trim()}`);
+        return await this.findRoot(path);
+    }
+    async currentBranch(repoRoot) {
+        return await this.gitValue(repoRoot, ['symbolic-ref', '--short', '-q', 'HEAD']);
+    }
+    async defaultBranch(repoRoot) {
+        const ref = await this.gitValue(repoRoot, [
+            'symbolic-ref',
+            '--short',
+            '-q',
+            'refs/remotes/origin/HEAD',
+        ]);
+        return ref ? ref.replace(/^origin\//, '') : null;
+    }
+    async protectedBranchNames(repoRoot) {
+        const names = new Set(['main', 'master', 'develop', 'prod']);
+        const fallback = await this.defaultBranch(repoRoot);
+        if (fallback)
+            names.add(fallback);
+        return names;
+    }
+    async createBranch(repoRoot, name) {
+        await this.validateBranch(repoRoot, name);
+        const result = await this.runner.run('git', ['switch', '-c', name], { cwd: repoRoot });
+        if (result.exitCode !== 0) {
+            throw new Error(`Git could not create the branch ${name}: ${result.stderr.trim() || 'unknown error'}`);
+        }
+        const branch = await this.currentBranch(repoRoot);
+        if (branch !== name) {
+            throw new Error(`Git created ${name} but HEAD is on ${branch ?? 'no branch'}`);
+        }
+        return branch;
+    }
+    async branchExists(repoRoot, name) {
+        const result = await this.runner.run('git', ['rev-parse', '--verify', '--quiet', `refs/heads/${name}`], {
+            cwd: repoRoot,
+        });
+        return result.exitCode === 0;
+    }
+    async switchBranch(repoRoot, name) {
+        await this.validateBranch(repoRoot, name);
+        const result = await this.runner.run('git', ['switch', '--', name], { cwd: repoRoot });
+        if (result.exitCode !== 0) {
+            throw new Error(`Git could not switch to the branch ${name}: ${result.stderr.trim() || 'unknown error'}`);
+        }
+        return name;
+    }
     async mainWorktree(repoRoot) {
         const commonDirectory = await this.gitValue(repoRoot, [
             'rev-parse',

package/runtime/dist/src/git/pre-commit.js

@@ -35,8 +35,24 @@ async function run() {
     })).data);
     const result = await gate.verify(repoRoot);
     process.stderr.write(`${JSON.stringify(result)}\n`);
+    const advice = describe(result);
+    if (advice)
+        process.stderr.write(`${advice}\n`);
     process.exitCode = result.allowed ? 0 : 1;
 }
+function describe(result) {
+    const [expected, actual] = result.details ?? [];
+    switch (result.reason) {
+        case 'branch_mismatch':
+            return `The task selected ${expected} but HEAD is on ${actual}. Run: git switch ${expected}`;
+        case 'branch_detached':
+            return `The task selected ${expected} but HEAD is detached. Run: git switch ${expected}`;
+        case 'online_commit_gate_rejected':
+            return `The backend refused the commit: ${expected ?? 'no reason given'}`;
+        default:
+            return null;
+    }
+}
 void run().catch(() => {
     process.stderr.write('Engineering Memory Git gate failed\n');
     process.exitCode = 1;

package/runtime/dist/src/git/verification-gate.js

@@ -32,6 +32,7 @@ export class VerificationGate {
             taskClosed: input.taskClosed ?? false,
             taskVersion: input.taskVersion ?? null,
             taskChanges,
+            branch: input.branch ?? null,
         }, this.root);
     }
     async verify(repoRoot) {
@@ -79,6 +80,16 @@ export class VerificationGate {
                 taskId: receipt.taskId,
             };
         }
+        const branch = await this.git.currentBranch(repoRoot);
+        if (receipt.branch && branch !== receipt.branch) {
+            return {
+                allowed: false,
+                reason: branch ? 'branch_mismatch' : 'branch_detached',
+                diffHash: manifest.diffHash,
+                taskId: receipt.taskId,
+                details: [receipt.branch, branch ?? 'HEAD'],
+            };
+        }
         if (receipt.diffHash !== manifest.diffHash) {
             return {
                 allowed: false,
@@ -118,6 +129,7 @@ export class VerificationGate {
                 repoFingerprint: receipt.repoFingerprint,
                 diffHash: manifest.diffHash,
                 expectedTaskVersion: receipt.taskVersion,
+                branch: branch ?? undefined,
             });
             const result = asObject(attestation);
             if (result?.allowed !== true ||
@@ -132,12 +144,13 @@ export class VerificationGate {
                 };
             }
         }
-        catch {
+        catch (error) {
             return {
                 allowed: false,
                 reason: 'online_commit_gate_rejected',
                 diffHash: manifest.diffHash,
                 taskId: receipt.taskId,
+                details: [error instanceof Error ? error.message : String(error)],
             };
         }
         return {

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

@@ -66,6 +66,7 @@ export const engineeringMemoryToolNames = [
     'task.verify',
     'task.close',
     'task.abandon',
+    'task.branch',
     'architecture.plan',
     'architecture.module',
     'architecture.record_application',
@@ -428,6 +429,16 @@ export function registerEngineeringMemoryTools(server, service) {
             reason: z.string().min(1).max(2000),
         }),
     }, async (input) => toolResult(await service.taskAbandon(input)));
+    server.registerTool('task.branch', {
+        description: 'Record the native questionnaire answer for the exact externalTaskId before any new write/scaffold task or read-only-to-write transition. Choose name or keepCurrent. For another task in a busy checkout supply worktreePath and name; use the returned repoRoot for all subsequent commands. Existing branches may be selected without resetting them. Decisions persist across retries and restarts.',
+        inputSchema: z.object({
+            repoRoot: optionalRepoRoot,
+            externalTaskId: z.string().min(2).max(160),
+            worktreePath: z.string().min(1).optional(),
+            name: z.string().min(1).max(255).optional(),
+            keepCurrent: z.boolean().optional(),
+        }),
+    }, async (input) => toolResult(await service.taskBranch(input)));
     server.registerTool('organization.create', {
         description: 'Create an organization the user named, with the short identifier they typed. Offer this underneath the organizations they already belong to; never invent the identifier from the name.',
         inputSchema: z.object({

package/runtime/dist/src/runtime/api-client.js

@@ -32,6 +32,7 @@ export const backendRecoveryOperationNames = [
     'task.verify',
     'task.close',
     'task.abandon',
+    'task.branch',
     'task.resolve_pending_delivery',
 ];
 const backendRecoveryOperations = new Set(backendRecoveryOperationNames);

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

@@ -3,6 +3,7 @@ import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { minimatch } from 'minimatch';
 import { endpoints } from '../config.js';
+import { RepositoryResolver } from '../project/repository.js';
 import { sha256, stableStringify } from '../utilities/hash.js';
 import { ApiResponseError, BackendUnavailableError, } from './api-client.js';
 import { assertSafeToPersist, normalizeRepositoryPaths } from './offline-outbox.js';
@@ -90,6 +91,11 @@ export class BridgeService {
             if (!projectId) {
                 throw refuse('This repository has a marker that names no project, so there is nothing to bootstrap against.', 'project.resolve');
             }
+            const bootstrapMode = persistedBootstrap.mode ?? 'write';
+            const decision = bootstrapMode === 'read_only'
+                ? null
+                : await this.requireBranchDecision(repository, input.externalTaskId);
+            const branch = decision?.branch;
             const checkpointId = deterministicUuid('session.bootstrap', projectId, repository.repoFingerprint, input.externalTaskId);
             const response = await this.dependencies.client.request(endpoints.sessionBootstrap, {
                 method: 'POST',
@@ -106,6 +112,7 @@ export class BridgeService {
                     ...(input.mode === 'read_only'
                         ? { baselineDiffHash: repository.git.worktreeHash }
                         : {}),
+                    ...(decision ? { branch } : {}),
                     checkpointIdempotencyKey: checkpointId,
                     knownRevisions: persistedBootstrap.knownRevisions,
                 }),
@@ -127,11 +134,20 @@ export class BridgeService {
                 !isIsoTimestamp(checkpointPayload.createdAt)) {
                 throw refuse('The backend opened the session without the checkpoint the task is anchored to.', 'session.bootstrap');
             }
+            if (decision)
+                await this.dependencies.repositories.git
+                    .branchStore(repository.repoRoot)
+                    .bind(projectId, input.externalTaskId, task.id);
             const pointer = {
                 repoFingerprint: repository.repoFingerprint,
                 projectId,
                 taskId: task.id,
                 taskSlug: input.externalTaskId,
+                worktreeId: sha256(repository.repoRoot),
+                ...(decision
+                    ? { branch: typeof task.branch === 'string' ? task.branch : decision.branch }
+                    : {}),
+                mode: normalizeTaskMode(task.mode),
                 sessionId: session.id,
                 lastSequence: numericSequence(task.lastSequence),
                 taskVersion: numericTaskVersion(task.lockVersion),
@@ -256,6 +272,12 @@ export class BridgeService {
                 backendSession.id !== sessionId) {
                 throw refuse('The backend resumed the session without the task it belongs to.', 'session.resume');
             }
+            await this.assertTaskWorktree(repository, backendTask, pointer);
+            if (backendTask.status === 'closed' || backendTask.status === 'abandoned') {
+                await this.dependencies.repositories.git
+                    .branchStore(repository.repoRoot)
+                    .release(backendTask.id);
+            }
             let localJournal = await this.dependencies.journal.load(projectId, taskSlug);
             let pendingOutbox = await this.dependencies.outbox.list();
             const responseSource = this.dependencies.client.getResponseSource(response);
@@ -365,6 +387,13 @@ export class BridgeService {
                     projectId,
                     taskId: backendTask.id,
                     taskSlug,
+                    worktreeId: pointer?.worktreeId ?? sha256(repository.repoRoot),
+                    ...(typeof backendTask.branch === 'string'
+                        ? { branch: backendTask.branch }
+                        : pointer?.branch !== undefined
+                            ? { branch: pointer.branch }
+                            : {}),
+                    mode: normalizeTaskMode(backendTask.mode),
                     sessionId,
                     lastSequence: resumedLastSequence,
                     taskVersion: resumedTaskVersion,
@@ -443,6 +472,10 @@ export class BridgeService {
                 ...input.changedPaths,
             ]);
             const baselineDiffHash = activeBaseline?.diffHash ?? repository.git.diffHash;
+            const decision = pointer &&
+                (input.transitionToWrite || (pointer.branch !== undefined && pointer.mode !== 'read_only'))
+                ? await this.requireBranchDecision(repository, pointer.taskSlug)
+                : null;
             let transitionTaskVersion;
             if (input.transitionToWrite) {
                 if (!pointer || pointer.sessionId !== input.sessionId) {
@@ -455,6 +488,7 @@ export class BridgeService {
                 sessionId: input.sessionId,
                 changedPaths,
                 baselineDiffHash,
+                ...(decision ? { branch: decision.branch } : {}),
                 ...(input.transitionToWrite
                     ? { transitionToWrite: true, expectedTaskVersion: transitionTaskVersion }
                     : {}),
@@ -501,6 +535,17 @@ export class BridgeService {
                 : undefined);
             const preparedPointer = await this.dependencies.activeContexts.loadForSession(repository.repoFingerprint, input.sessionId);
             if (preparedPointer) {
+                if (decision) {
+                    await this.dependencies.repositories.git
+                        .branchStore(repository.repoRoot)
+                        .bind(preparedPointer.projectId, preparedPointer.taskSlug, preparedPointer.taskId);
+                    await this.dependencies.activeContexts.save({
+                        ...preparedPointer,
+                        worktreeId: sha256(repository.repoRoot),
+                        branch: typeof preparedTask?.branch === 'string' ? preparedTask.branch : decision.branch,
+                        mode: 'write',
+                    });
+                }
                 const preparedData = objectValue(response.data);
                 await this.seedResumeSnapshot(preparedPointer, {
                     ...objectOrEmpty(response.data),
@@ -1010,6 +1055,7 @@ export class BridgeService {
                     });
                 }
                 const taskMode = normalizeTaskMode(snapshotTask.mode);
+                await this.assertTaskWorktree(repository, snapshotTask, pointer);
                 const resourceDiscoveryPolicy = readResourceDiscoveryPolicy(snapshot, activeLease);
                 const validations = normalizePersistentInput(input.validations, repository.repoRoot);
                 if (taskMode === 'read_only') {
@@ -1072,6 +1118,11 @@ export class BridgeService {
                     changedPaths: taskMode === 'read_only' ? [] : taskChangedPaths,
                     pathChanges: pathChangeManifest,
                     diffHash: repository.git.diffHash,
+                    ...(taskMode !== 'read_only'
+                        ? {
+                            branch: await this.dependencies.repositories.git.currentBranch(repository.repoRoot),
+                        }
+                        : {}),
                     ...(taskMode === 'read_only' ? { worktreeHash: repository.git.worktreeHash } : {}),
                     validations,
                     pendingOutboxCount,
@@ -1105,6 +1156,9 @@ export class BridgeService {
                         repoFingerprint: repository.repoFingerprint,
                         repoRoot: repository.repoRoot,
                         diffHash: repository.git.diffHash,
+                        branch: typeof snapshotTask.branch === 'string'
+                            ? snapshotTask.branch
+                            : (pointer.branch ?? null),
                         taskVersion,
                         taskChanges,
                     });
@@ -1148,11 +1202,17 @@ export class BridgeService {
                 const taskChanges = pointer.changeBaseline
                     ? manifestDelta(pointer.changeBaseline.changedPaths, repository.git.changedPaths)
                     : [];
+                await this.assertTaskWorktree(repository, task, pointer);
                 const closeBody = {
                     taskId: input.taskId,
                     sessionId: pointer.sessionId,
                     expectedTaskVersion: numericTaskVersion(task.lockVersion),
                     diffHash: repository.git.diffHash,
+                    ...(normalizeTaskMode(task.mode) !== 'read_only'
+                        ? {
+                            branch: await this.dependencies.repositories.git.currentBranch(repository.repoRoot),
+                        }
+                        : {}),
                 };
                 await this.dependencies.activeContexts.setCloseIntent(repository.repoFingerprint, {
                     body: closeBody,
@@ -1162,6 +1222,111 @@ export class BridgeService {
             });
         });
     }
+    async taskBranch(input) {
+        return await this.execute(async () => {
+            const repository = await this.dependencies.repositories.resolve(input.repoRoot ?? process.cwd());
+            const authentication = await this.dependencies.browserAuth.ensureAuthenticated();
+            if (authentication)
+                return asJsonValue({ authentication });
+            if (!repository.projectId)
+                throw refuse('Resolve the project before choosing its task branch.', 'project.resolve');
+            if (!input.externalTaskId ||
+                input.externalTaskId.length > 160 ||
+                /[\r\n]/.test(input.externalTaskId))
+                throw refuse('Pass the exact externalTaskId of the task whose branch question was answered.', 'task.branch');
+            if (Boolean(input.name) === (input.keepCurrent === true) ||
+                (input.worktreePath && !input.name))
+                throw refuse('Choose exactly one branch name or keepCurrent. A separate worktree also needs a branch name.', 'task.branch');
+            assertSafeToPersist(cleanJson({ externalTaskId: input.externalTaskId, name: input.name }));
+            const git = this.dependencies.repositories.git;
+            let target = repository;
+            try {
+                if (input.name)
+                    await git.validateBranch(repository.repoRoot, input.name);
+                if (input.worktreePath && input.name) {
+                    const targetRoot = await git.createWorktree(repository.repoRoot, input.name, input.worktreePath);
+                    target = await this.dependencies.repositories.resolve(targetRoot);
+                    if (target.projectId && target.projectId !== repository.projectId)
+                        throw refuse('The target worktree belongs to a different Engineering Memory project. Choose another worktreePath.', 'task.branch');
+                    if (!target.markerPath) {
+                        await new RepositoryResolver(git, repository.schemaVersion ?? 2).writeMarker(targetRoot, repository.projectId);
+                        target = await this.dependencies.repositories.resolve(targetRoot);
+                    }
+                }
+                const branch = input.name ?? (await git.currentBranch(target.repoRoot));
+                const store = git.branchStore(target.repoRoot);
+                await store.reserve({
+                    projectId: repository.projectId,
+                    externalTaskId: input.externalTaskId,
+                    branch,
+                });
+                if (input.name && (await git.currentBranch(target.repoRoot)) !== input.name) {
+                    try {
+                        if (await git.branchExists(target.repoRoot, input.name))
+                            await git.switchBranch(target.repoRoot, input.name);
+                        else
+                            await git.createBranch(target.repoRoot, input.name);
+                    }
+                    catch (error) {
+                        if ((await git.currentBranch(target.repoRoot)) !== input.name) {
+                            await store.cancelUnopened(repository.projectId, input.externalTaskId);
+                            throw error;
+                        }
+                    }
+                }
+                return asJsonValue({
+                    branch,
+                    kept: input.keepCurrent === true,
+                    repoRoot: target.repoRoot,
+                    externalTaskId: input.externalTaskId,
+                    nextAction: 'Use this repoRoot for session.bootstrap and every subsequent command for this task. The decision survives retries and restarts.',
+                });
+            }
+            catch (error) {
+                if (error instanceof BridgeRecoveryError)
+                    throw error;
+                throw refuse(`${error instanceof Error ? error.message : String(error)} Retry task.branch for the selected task; use worktreePath to leave a busy or dirty checkout intact.`, 'task.branch');
+            }
+        });
+    }
+    async requireBranchDecision(repository, externalTaskId) {
+        const git = this.dependencies.repositories.git;
+        const store = git.branchStore(repository.repoRoot);
+        let record = await store.read();
+        if (!record) {
+            const pointer = await this.dependencies.activeContexts.loadForSlug(repository.repoFingerprint, externalTaskId);
+            if (pointer?.worktreeId === sha256(repository.repoRoot) &&
+                pointer.mode !== 'read_only' &&
+                pointer.branch !== undefined) {
+                await store.reserve({
+                    projectId: pointer.projectId,
+                    externalTaskId,
+                    branch: pointer.branch,
+                    taskId: pointer.taskId,
+                });
+                record = await store.read();
+            }
+        }
+        if (!record)
+            throw refuse(`Ask the branch question through the native questionnaire for task ${externalTaskId}, then call task.branch with that externalTaskId and a name or keepCurrent. For parallel work choose a separate worktreePath.`, 'task.branch');
+        if (record.decision.projectId !== repository.projectId ||
+            record.decision.externalTaskId !== externalTaskId)
+            throw refuse(`This worktree belongs to task ${record.decision.externalTaskId}. Use task.branch with worktreePath for ${externalTaskId}, then bootstrap in the returned directory.`, 'task.branch');
+        const branch = await git.currentBranch(repository.repoRoot);
+        if (branch !== record.decision.branch)
+            throw refuse(`Task ${externalTaskId} selected ${record.decision.branch ?? 'detached HEAD'}, but this worktree is on ${branch ?? 'detached HEAD'}. Return to the selected branch with task.branch.`, 'task.branch');
+        return record.decision;
+    }
+    async assertTaskWorktree(repository, task, pointer) {
+        if (normalizeTaskMode(task.mode) === 'read_only')
+            return;
+        if (pointer?.worktreeId && pointer.worktreeId !== sha256(repository.repoRoot))
+            throw refuse('This task belongs to a different worktree. Resume and run its commands in the worktree selected for this task.', 'session.resume');
+        const recorded = typeof task.branch === 'string' ? task.branch : pointer?.branch;
+        const current = await this.dependencies.repositories.git.currentBranch(repository.repoRoot);
+        if (recorded && current !== recorded)
+            throw refuse(`This task selected ${recorded}. Call task.branch with externalTaskId ${pointer?.taskSlug ?? String(task.externalTaskId)} and name ${recorded} before continuing.`, 'task.branch');
+    }
     async taskAbandon(input) {
         return await this.execute(async () => {
             return await this.taskExclusive(input.taskId, async () => {
@@ -1174,6 +1339,9 @@ export class BridgeService {
                 if (!abandoned || abandoned.abandoned !== true) {
                     throw refuse('The backend did not record the abandonment, so the task is still open.', 'session.resume');
                 }
+                await this.dependencies.repositories.git
+                    .branchStore(repository.repoRoot)
+                    .release(input.taskId);
                 const forgotten = await this.dependencies.activeContexts.forget(repository.repoFingerprint, input.taskId);
                 await this.dependencies.gate.invalidateTask(input.taskId);
                 return asJsonValue({
@@ -2072,6 +2240,7 @@ export class BridgeService {
             repoFingerprint: pointer.repoFingerprint,
             repoRoot: repository.repoRoot,
             diffHash: repository.git.diffHash,
+            branch: typeof backendTask?.branch === 'string' ? backendTask.branch : (pointer.branch ?? null),
             taskVersion,
             taskChanges: intent.taskChanges,
         });
@@ -2100,6 +2269,9 @@ export class BridgeService {
     }
     async deliverCloseIntent(repository, body, taskChanges, recoveredAfterResponseLoss) {
         const touchedContract = taskChanges.some((change) => /\.controller\.[tj]s$/.test(change.path));
+        const currentBranch = await this.dependencies.repositories.git.currentBranch(repository.repoRoot);
+        if (typeof body.branch === 'string' && body.branch !== currentBranch)
+            throw refuse(`Return to the branch ${body.branch} recorded in this close request before retrying.`, 'task.branch');
         let response;
         try {
             response = await this.dependencies.client.request(endpoints.taskClose, {
@@ -2125,11 +2297,19 @@ export class BridgeService {
             repoFingerprint: repository.repoFingerprint,
             repoRoot: repository.repoRoot,
             diffHash: String(body.diffHash),
+            branch: typeof closedTask.branch === 'string'
+                ? closedTask.branch
+                : typeof body.branch === 'string'
+                    ? body.branch
+                    : null,
             taskClosed: true,
             taskVersion: closedTaskVersion,
             taskChanges,
         });
         await this.dependencies.activeContexts.clearCloseIntent(repository.repoFingerprint, String(body.taskId));
+        await this.dependencies.repositories.git
+            .branchStore(repository.repoRoot)
+            .release(String(body.taskId));
         return asJsonValue({
             ...closedTask,
             repository: publicRepository(repository),

package/runtime/dist/src/runtime/task-branch-store.js

@@ -0,0 +1,111 @@
+import { NativeCommandRunner } from '../utilities/process.js';
+import { assertSafeToPersist } from './offline-outbox.js';
+import { BridgeRecoveryError } from './recovery-error.js';
+const decisionRef = 'refs/worktree/engineering-memory-task';
+export class TaskBranchStore {
+    repoRoot;
+    runner;
+    constructor(repoRoot, runner = new NativeCommandRunner()) {
+        this.repoRoot = repoRoot;
+        this.runner = runner;
+    }
+    async read() {
+        const reference = await this.runner.run('git', ['rev-parse', '--verify', '--quiet', decisionRef], { cwd: this.repoRoot });
+        if (reference.exitCode === 1)
+            return null;
+        if (reference.exitCode !== 0)
+            throw new BridgeRecoveryError('Git could not read the worktree task reservation. Retry the branch operation.', 'task.branch');
+        const oid = reference.stdout.trim();
+        const blob = await this.runner.run('git', ['cat-file', 'blob', oid], { cwd: this.repoRoot });
+        if (blob.exitCode !== 0)
+            throw new BridgeRecoveryError('Git could not read the recorded branch decision. Retry the branch operation.', 'task.branch');
+        let decision;
+        try {
+            decision = JSON.parse(blob.stdout);
+        }
+        catch {
+            throw new BridgeRecoveryError('The worktree branch record is invalid. Use a separate worktree to continue this task.', 'task.branch');
+        }
+        if (!decision)
+            throw new BridgeRecoveryError('The worktree branch record is invalid. Use a separate worktree to continue this task.', 'task.branch');
+        if (typeof decision.projectId !== 'string' ||
+            typeof decision.externalTaskId !== 'string' ||
+            !(decision.branch === null || typeof decision.branch === 'string')) {
+            throw new BridgeRecoveryError('The worktree branch record is invalid. Use a separate worktree to continue this task.', 'task.branch');
+        }
+        return { oid, decision };
+    }
+    async reserve(decision) {
+        assertSafeToPersist({ ...decision });
+        const existing = await this.read();
+        if (existing) {
+            this.assertSame(existing.decision, decision);
+            return;
+        }
+        const oid = await this.hash(decision);
+        const written = await this.runner.run('git', ['update-ref', '--no-deref', decisionRef, oid, '0'.repeat(oid.length)], { cwd: this.repoRoot });
+        if (written.exitCode !== 0) {
+            const winner = await this.read();
+            if (winner) {
+                this.assertSame(winner.decision, decision);
+                return;
+            }
+            throw new BridgeRecoveryError('Another branch operation is in progress. Retry the same task.branch operation.', 'task.branch');
+        }
+    }
+    async bind(projectId, externalTaskId, taskId) {
+        const current = await this.read();
+        if (!current ||
+            current.decision.projectId !== projectId ||
+            current.decision.externalTaskId !== externalTaskId)
+            throw new BridgeRecoveryError('The worktree reservation changed while opening the task. Resume it before editing.', 'session.resume');
+        if (current.decision.taskId === taskId)
+            return;
+        const oid = await this.hash({ ...current.decision, taskId });
+        const result = await this.runner.run('git', ['update-ref', '--no-deref', decisionRef, oid, current.oid], { cwd: this.repoRoot });
+        if (result.exitCode !== 0) {
+            const latest = await this.read();
+            if (latest?.decision.taskId !== taskId)
+                throw new BridgeRecoveryError('The worktree reservation changed while opening the task. Resume it before editing.', 'session.resume');
+        }
+    }
+    async cancelUnopened(projectId, externalTaskId) {
+        const current = await this.read();
+        if (!current ||
+            current.decision.taskId ||
+            current.decision.projectId !== projectId ||
+            current.decision.externalTaskId !== externalTaskId)
+            return;
+        const result = await this.runner.run('git', ['update-ref', '--no-deref', '-d', decisionRef, current.oid], { cwd: this.repoRoot });
+        if (result.exitCode !== 0 && (await this.read())?.oid === current.oid)
+            throw new BridgeRecoveryError('The failed branch operation could not release its reservation. Retry task.branch with the same task identifier.', 'task.branch');
+    }
+    async release(taskId) {
+        const current = await this.read();
+        if (!current || current.decision.taskId !== taskId)
+            return;
+        const result = await this.runner.run('git', ['update-ref', '--no-deref', '-d', decisionRef, current.oid], { cwd: this.repoRoot });
+        if (result.exitCode !== 0 && (await this.read())?.decision.taskId === taskId) {
+            throw new BridgeRecoveryError('The task has finished but its worktree reservation could not be released. Resume the task to retry cleanup.', 'session.resume');
+        }
+    }
+    assertSame(current, requested) {
+        if (current.projectId !== requested.projectId ||
+            current.externalTaskId !== requested.externalTaskId) {
+            throw new BridgeRecoveryError(`This worktree belongs to task ${current.externalTaskId}. Resume that task, or call task.branch with worktreePath and a branch name for the new task.`, 'task.branch');
+        }
+        if (current.branch !== requested.branch) {
+            throw new BridgeRecoveryError(`This task selected ${current.branch ?? 'detached HEAD'}. Return to that branch before continuing.`, 'task.branch');
+        }
+    }
+    async hash(decision) {
+        const result = await this.runner.run('git', ['hash-object', '-w', '--stdin'], {
+            cwd: this.repoRoot,
+            input: JSON.stringify(decision),
+        });
+        if (result.exitCode !== 0)
+            throw new BridgeRecoveryError('Git could not save the branch decision. Retry the same branch operation.', 'task.branch');
+        return result.stdout.trim();
+    }
+}
+//# sourceMappingURL=task-branch-store.js.map

package/skill/SKILL.md

@@ -11,6 +11,8 @@ 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.
+
 1. Locate `.engineering-memory/project.json` from the working directory toward the repository root. When it exists, the project's knowledge is in the backend and not in the working tree, so answer nothing about the project before bootstrapping — a file search that finds no design link, no screen record and no rule is reporting what the repository lacks, not what the project knows.
 2. Call `session.entry` before answering anything in a repository, and act on what it reports before the message itself: sign in when it says so, ask for organization and project when nothing has been decided, and stay completely silent about Engineering Memory in a repository where the user switched it off. Record every one of those answers with `session.set_decision`, and only ever from something the user actually said.
 3. Before planning or editing, call `session.bootstrap`. After compaction, a new chat, interruption, or handoff, call `session.resume` first.

package/skill/references/lifecycle.md

@@ -10,9 +10,11 @@ An archived project is recoverable state, not a missing or conflicting binding.
 
 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. 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, pinned revisions, project profile, engineering rules, prior task documents, quality gates, and current deviations.
 
-Before the first edit of a write task, settle the branch. Ask the user through the native questionnaire whether to open a branch for this task and which name to use, offering the convention the returned rules carry. Do this once, at the start, not at commit time — the commit gate runs long after the work is written, and by then the wrong branch has already cost something. A read-only task never creates a branch.
+Every new write or scaffold task settles its branch through the native questionnaire before it opens, including when HEAD is already on a feature branch. Offer a task branch or an explicit choice to stay on the current branch. Call `task.branch` with the exact `externalTaskId` and either `name` or `keepCurrent`, then call `session.bootstrap` in its returned `repoRoot`. An existing branch name checks it out. Creating a branch remains optional; recording the user's choice does not. A read-only task needs no branch decision, but `context.prepare_change` with `transitionToWrite` requires one before editing.
 
-Two tasks in one repository need two branches, and one working tree can only have one checked out. A second checkout is what `git worktree` is for: `git worktree add ../<repo>-<task> -b <branch>` gives the task its own directory and its own branch against the same repository, and the chat for that task runs there. Engineering Memory treats them as one project — the fingerprint comes from the repository, not the directory — while each task measures only what changed in its own tree. Offer this when a task starts in a repository that already has a live task, and never ask somebody to switch branches in a tree another task is using.
+The choice belongs to that task and worktree, survives retry and client restart, and cannot be consumed by a different task. Reuse an existing answer rather than asking again. A named branch stays fixed through prepare, verify, close and commit; closing never replaces it. Return with `task.branch` using the same task slug and recorded branch when a gate reports a mismatch. Legacy tasks without a recorded branch and tasks explicitly kept on detached HEAD remain compatible; they are not restricted to a named branch. Older clients remain supported during the minimum-version compatibility window.
+
+Parallel development needs separate working directories. If another task owns the current worktree, offer a separate worktree through the questionnaire. Call `task.branch` with `externalTaskId`, `name`, and `worktreePath`; run bootstrap and all subsequent file, test and Git commands in its returned `repoRoot`. This creates or reuses an appropriate Git worktree and preserves the repository's project marker schema. Never switch another task's working directory. Reservations are shared by clients using the same worktree; close or abandon releases that task's reservation. An interrupted close can release it through resume.
 
 A repository holds as many tasks as the people working in it. Never treat somebody else's unfinished task as a reason this one cannot proceed: no task waits on another task's review, reconciliation, verification or close, and nothing that is already verified or closed is undone by what happens elsewhere. When `session.resume` reports more than one live task for this repository, it lists them and the right move is to ask the user which one this is, never to guess and never to adopt the one that happens to be most recent.
 

package/skill/references/questionnaires.md

@@ -1,6 +1,6 @@
 # Native Questionnaires
 
-Use Codex or Claude native question controls. Do not open a custom survey web page. 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. 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.
 
 ## Authentication
 
@@ -62,7 +62,7 @@ Ask for the registered email and intended role. Show owner, maintainer, member,
 
 ## Branch
 
-At the start of a write task, before the first edit, ask whether to open a branch for it and confirm the name. Offer the convention the returned engineering rules state, the current branch as the alternative, and let the user name something else. Never create a branch during read-only analysis, and never create one without asking. When the repository already has another live task, add a third option — a separate worktree for this one — and say what it means: its own directory, its own branch, the same project, and the other task's tree left alone.
+Ask once for every new write or scaffold task, on any branch, and before a read-only task transitions to writing. Offer a new or existing task branch, or explicitly continuing on the current branch; use the naming convention from the returned rules. When another task owns the worktree, offer a separate directory and branch for parallel work. Pass the exact `externalTaskId` and either `name` or `keepCurrent` to `task.branch`; for a separate worktree also supply `worktreePath`. Continue in the returned `repoRoot`. Retries and handoffs reuse the stored choice. Read-only analysis does not create a branch or consume another task's answer.
 
 ## Flow Entry and Exit
 

package/bin/entry-point.test.mjs

@@ -1,29 +0,0 @@
-import assert from 'node:assert/strict';
-import { readFile } from 'node:fs/promises';
-import test from 'node:test';
-
-const entryPoint = new URL('./engineering-memory.mjs', import.meta.url);
-const manifest = new URL('../package.json', import.meta.url);
-
-test('the published entry point tells the installer which version it is', async () => {
-  const source = await readFile(entryPoint, 'utf8');
-
-  assert.match(
-    source,
-    /'--client-version',\s*await publishedVersion\(\)/,
-    'The installer is never told the version, so every install reports itself as unknown and no update is ever offered',
-  );
-});
-
-test('the published entry point tells the installer which backend it was built for', async () => {
-  const source = await readFile(entryPoint, 'utf8');
-
-  assert.match(source, /'--api-url',\s*await publishedApiUrl\(\)/);
-});
-
-test('the manifest carries a version the entry point can stamp', async () => {
-  const declared = JSON.parse(await readFile(manifest, 'utf8'));
-
-  assert.match(String(declared.version), /^\d+\.\d+\.\d+$/);
-  assert.equal(declared.name, 'engineering-memory');
-});