engineering-memory 1.6.4 → 1.8.0

package/install/commands.mjs

@@ -6,16 +6,19 @@ import { delimiter, join } from 'node:path';
 const metaCharacters = /([()\][%!^"`<>&|;, *?])/g;
 const defaultPathExtensions = '.COM;.EXE;.BAT;.CMD';
 const shimExtension = /\.(?:cmd|bat)$/i;
+const npmShimPath = /node_modules[\\/]\.bin[\\/][^\\/]+\.cmd$/i;
 const pathSeparators = /[/\\]/;
 
 export async function runCommand(command, args, options = {}) {
   const environment = options.env ?? process.env;
   const invocation = await planInvocation(command, args, environment, options);
+  const captureOutput = options.captureOutput !== false;
   return await new Promise((resolve) => {
     const child = spawn(invocation.command, invocation.args, {
       cwd: options.cwd,
       env: environment,
       shell: false,
+      ...(captureOutput ? {} : { stdio: 'ignore' }),
       windowsHide: true,
       windowsVerbatimArguments: invocation.verbatim,
     });
@@ -38,6 +41,24 @@ export async function runCommand(command, args, options = {}) {
   });
 }
 
+export function prependEnvironmentPath(environment, directory) {
+  const pathKeys = Object.keys(environment).filter(
+    (key) => key.toLowerCase() === 'path',
+  );
+  const pathKey =
+    pathKeys.find((key) => Boolean(environment[key])) ?? pathKeys[0] ?? 'PATH';
+  const current = pathKeys
+    .map((key) => environment[key])
+    .filter(Boolean)
+    .join(delimiter);
+  environment[pathKey] = current
+    ? `${directory}${delimiter}${current}`
+    : directory;
+  for (const duplicate of pathKeys) {
+    if (duplicate !== pathKey) delete environment[duplicate];
+  }
+}
+
 export async function planInvocation(
   command,
   args,
@@ -58,9 +79,13 @@ export async function planInvocation(
     return { command: executable, args, verbatim: false };
   }
   const comSpec = environment.ComSpec ?? environment.COMSPEC ?? 'cmd.exe';
-  const line = [escapeCommand(executable), ...args.map(escapeArgument)].join(
-    ' ',
-  );
+  const doubleEscapeMetaCharacters = npmShimPath.test(executable);
+  const line = [
+    escapeCommand(executable),
+    ...args.map((argument) =>
+      escapeArgument(argument, doubleEscapeMetaCharacters),
+    ),
+  ].join(' ');
   return {
     command: comSpec,
     args: ['/d', '/s', '/c', `"${line}"`],
@@ -80,7 +105,10 @@ export async function resolveWindowsExecutable(command, environment) {
   if (pathSeparators.test(command)) {
     return await firstExistingFile(command, extensions, carriesExtension);
   }
-  const searchPath = environment.Path ?? environment.PATH ?? '';
+  const searchPath = Object.entries(environment)
+    .filter(([key, value]) => key.toLowerCase() === 'path' && Boolean(value))
+    .map(([, value]) => value)
+    .join(delimiter);
   for (const directory of searchPath.split(delimiter).filter(Boolean)) {
     const candidate = await firstExistingFile(
       join(unquote(directory), command),
@@ -122,13 +150,14 @@ function escapeCommand(value) {
   return String(value).replace(metaCharacters, '^$1');
 }
 
-function escapeArgument(value) {
+function escapeArgument(value, doubleEscapeMetaCharacters) {
   const escaped = String(value)
-    .replace(/(\\*)"/g, '$1$1\\"')
-    .replace(/(\\*)$/, '$1$1');
-  return `"${escaped}"`
-    .replace(metaCharacters, '^$1')
-    .replace(metaCharacters, '^$1');
+    .replace(/(?=(\\+?)?)\1"/g, '$1$1\\"')
+    .replace(/(?=(\\+?)?)\1$/, '$1$1');
+  const quoted = `"${escaped}"`.replace(metaCharacters, '^$1');
+  return doubleEscapeMetaCharacters
+    ? quoted.replace(metaCharacters, '^$1')
+    : quoted;
 }
 
 export function commandFailure(command, result) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "engineering-memory",
-  "version": "1.6.4",
+  "version": "1.8.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/config.js

@@ -14,7 +14,7 @@ export function loadBridgeConfig(env = process.env) {
         cacheMaxEntries: positiveInteger(env.ENGINEERING_MEMORY_CACHE_MAX_ENTRIES, 64),
         cacheMaxBytes: positiveInteger(env.ENGINEERING_MEMORY_CACHE_MAX_BYTES, 5 * 1024 * 1024),
         cacheMaxAgeMs: positiveInteger(env.ENGINEERING_MEMORY_CACHE_MAX_AGE_MS, 24 * 60 * 60 * 1000),
-        markerSchemaVersion: positiveInteger(env.ENGINEERING_MEMORY_MARKER_SCHEMA_VERSION, 1),
+        markerSchemaVersion: positiveInteger(env.ENGINEERING_MEMORY_MARKER_SCHEMA_VERSION, 2),
         credentialService: env.ENGINEERING_MEMORY_CREDENTIAL_SERVICE ?? 'engineering-memory',
         credentialAccount: env.ENGINEERING_MEMORY_CREDENTIAL_ACCOUNT ?? 'default',
     };
@@ -26,6 +26,7 @@ export function apiStateRoot(config) {
     return join(config.stateRoot, 'origins', apiNamespaceKey(config.apiBaseUrl));
 }
 export const endpoints = {
+    auditList: '/audit',
     authRefresh: '/auth/refresh',
     authLogout: '/auth/logout',
     authBrowserStart: '/auth/browser/start',
@@ -49,6 +50,8 @@ export const endpoints = {
     taskScaffoldApplication: '/tasks/scaffold-application',
     organizationList: '/organizations',
     organizationCreate: '/organizations',
+    organizationMemberList: (organizationId) => `/organizations/${organizationId}/members`,
+    organizationMemberUpsert: (organizationId) => `/organizations/${organizationId}/members`,
     taskVerify: '/runtime/task/verify',
     taskClose: '/runtime/task/close',
     taskAbandon: '/runtime/task/abandon',
@@ -57,7 +60,12 @@ export const endpoints = {
     projectList: '/projects',
     projectResolve: '/projects/resolve',
     projectBind: (projectId) => `/projects/${projectId}/bind`,
+    projectArchive: (projectId) => `/projects/${projectId}`,
+    projectRestore: (projectId) => `/projects/${projectId}/restore`,
     projectMemberAdd: (projectId) => `/projects/${projectId}/members`,
+    projectMemberList: (projectId) => `/projects/${projectId}/members`,
+    workItemList: (projectId) => `/projects/${projectId}/work-items`,
+    workItemGet: (projectId, workItemId) => `/projects/${projectId}/work-items/${workItemId}`,
     projectLink: '/projects/link',
     projectUnlink: '/projects/unlink',
     projectLinks: (projectId) => `/projects/${projectId}/links`,

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

@@ -19,37 +19,44 @@ export class GitInspector {
         }
         return await canonicalPath(result.stdout.trim());
     }
-    async fingerprint(repoRoot) {
-        const [remote, firstCommit] = await Promise.all([
-            this.gitValue(repoRoot, ['config', '--get', 'remote.origin.url']),
-            this.gitValue(repoRoot, ['rev-list', '--max-parents=0', 'HEAD']),
-        ]);
-        const canonicalRoot = await canonicalPath(repoRoot);
+    async fingerprint(repoRoot, identityVersion = 2) {
+        if (!Number.isSafeInteger(identityVersion) || identityVersion < 1) {
+            throw new Error('Repository identity version must be a positive integer');
+        }
+        const remote = await this.gitValue(repoRoot, ['config', '--get', 'remote.origin.url']);
         const identity = remote
-            ? `${canonicalRemoteIdentity(remote)}\n${firstCommit ?? ''}`
-            : `${canonicalRoot.toLowerCase()}\n${firstCommit ?? ''}`;
+            ? canonicalRemoteIdentity(remote)
+            : (await this.mainWorktree(repoRoot)).toLowerCase();
+        if (identityVersion === 1) {
+            const firstCommit = await this.gitValue(repoRoot, ['rev-list', '--max-parents=0', 'HEAD']);
+            return sha256(`${identity}\n${firstCommit ?? ''}`);
+        }
         return sha256(identity);
     }
+    async mainWorktree(repoRoot) {
+        const commonDirectory = await this.gitValue(repoRoot, [
+            'rev-parse',
+            '--path-format=absolute',
+            '--git-common-dir',
+        ]);
+        if (!commonDirectory) {
+            return await canonicalPath(repoRoot);
+        }
+        return await canonicalPath(resolve(commonDirectory, '..'));
+    }
     async manifest(repoRoot) {
         const root = await this.findRoot(repoRoot);
         const head = await this.gitValue(root, ['rev-parse', 'HEAD']);
         const changedPaths = head
             ? await this.changedPathsAgainstHead(root)
             : await this.unbornChangedPaths(root);
-        const normalizedManifest = changedPaths.map(({ path, originalPath, status, contentHash, size, mode }) => ({
-            path,
-            originalPath: originalPath ?? null,
-            status: semanticStatus(status),
-            contentHash,
-            size,
-            mode: mode ?? null,
-        }));
+        const hashManifest = canonicalHashManifest(changedPaths);
         return {
             repoRoot: root,
             head,
             changedPaths,
-            worktreeHash: sha256(`${stableStringify(normalizedManifest)}\n`),
-            diffHash: sha256(`${head ?? '<unborn>'}\n${stableStringify(normalizedManifest)}\n`),
+            worktreeHash: sha256(`${stableStringify(hashManifest)}\n`),
+            diffHash: sha256(`${head ?? '<unborn>'}\n${stableStringify(hashManifest)}\n`),
         };
     }
     async stagedManifest(repoRoot) {
@@ -354,6 +361,41 @@ function semanticStatus(status) {
     }
     return status.trim() || status;
 }
+function canonicalHashManifest(entries) {
+    const byPath = new Map();
+    const renamedSources = new Set();
+    for (const entry of entries) {
+        const status = semanticStatus(entry.status);
+        const deleted = status === 'D';
+        if (status === 'R') {
+            if (!entry.originalPath) {
+                throw new Error(`Git rename is missing its original path: ${entry.path}`);
+            }
+            renamedSources.add(entry.originalPath);
+        }
+        byPath.set(entry.path, {
+            path: entry.path,
+            originalPath: null,
+            status: status === 'C' || status === 'R' ? 'A' : status,
+            contentHash: deleted ? null : entry.contentHash,
+            size: deleted ? null : entry.size,
+            mode: deleted ? null : (entry.mode ?? null),
+        });
+    }
+    for (const path of renamedSources) {
+        if (!byPath.has(path)) {
+            byPath.set(path, {
+                path,
+                originalPath: null,
+                status: 'D',
+                contentHash: null,
+                size: null,
+                mode: null,
+            });
+        }
+    }
+    return [...byPath.values()].sort((left, right) => left.path.localeCompare(right.path));
+}
 function deduplicateChangedPaths(entries) {
     const byPath = new Map();
     for (const entry of entries) {

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

@@ -44,6 +44,7 @@ const checkpointBase = {
     idempotencyKey: z.string().uuid().optional(),
 };
 export const engineeringMemoryToolNames = [
+    'audit.list',
     'session.entry',
     'session.set_decision',
     'session.decline_update',
@@ -70,10 +71,17 @@ export const engineeringMemoryToolNames = [
     'architecture.record_application',
     'organization.list',
     'organization.create',
+    'organization.member_list',
+    'organization.member_upsert',
     'project.setup',
     'project.list',
     'project.resolve',
+    'project.archive',
+    'project.restore',
     'project.member_add',
+    'project.member_list',
+    'work_item.list',
+    'work_item.get',
     'project.clone',
     'project.link',
     'project.unlink',
@@ -97,6 +105,31 @@ const reconciliationEntry = z.object({
     reason: z.string().optional(),
 });
 export function registerEngineeringMemoryTools(server, service) {
+    server.registerTool('audit.list', {
+        description: 'List one authorized organization or project audit trail with an exact cursor. Choose exactly one scope and send both cursor fields together.',
+        inputSchema: z
+            .object({
+            organizationId: z.string().uuid().optional(),
+            projectId: z.string().uuid().optional(),
+            beforeCreatedAt: z.string().datetime({ offset: true }).optional(),
+            beforeId: z.string().uuid().optional(),
+            limit: z.number().int().min(1).max(100).optional(),
+        })
+            .superRefine((value, context) => {
+            if (Boolean(value.organizationId) === Boolean(value.projectId)) {
+                context.addIssue({
+                    code: 'custom',
+                    message: 'Choose exactly one organizationId or projectId.',
+                });
+            }
+            if (Boolean(value.beforeCreatedAt) !== Boolean(value.beforeId)) {
+                context.addIssue({
+                    code: 'custom',
+                    message: 'Send beforeCreatedAt and beforeId together.',
+                });
+            }
+        }),
+    }, async (input) => toolResult(await service.auditList(input)));
     server.registerTool('session.entry', {
         description: 'The first call of every session in a repository, before answering anything about the project. Reports whether the user is signed in, whether this repository is bound, what this user decided about it last time, and the one thing to do now. A repository the user switched Engineering Memory off in reports that, and is left alone.',
         inputSchema: z.object({ repoRoot: optionalRepoRoot }),
@@ -131,6 +164,7 @@ export function registerEngineeringMemoryTools(server, service) {
             objective: z.string().min(2),
             taskKind: z.string().min(2),
             workItemKey: z.string().min(1).optional(),
+            workItemId: z.string().uuid().optional(),
             mode: z.enum(['write', 'read_only', 'scaffold']).optional(),
             knownRevisions: z.record(z.string(), z.number().int().min(0)).optional(),
         }),
@@ -401,6 +435,19 @@ export function registerEngineeringMemoryTools(server, service) {
             slug: z.string().min(2).max(120),
         }),
     }, async (input) => toolResult(await service.organizationCreate(input)));
+    server.registerTool('organization.member_list', {
+        description: "List an organization's members and roles so a member who cannot perform an owner-only recovery can coordinate with an owner.",
+        inputSchema: z.object({ organizationId: z.string().uuid() }),
+    }, async (input) => toolResult(await service.organizationMemberList(input)));
+    server.registerTool('organization.member_upsert', {
+        description: 'Add or update an existing Engineering Memory account in an organization. Only an organization owner may call this; use it before adding that account to a child project.',
+        inputSchema: z.object({
+            organizationId: z.string().uuid(),
+            email: z.string().email(),
+            role: z.enum(['owner', 'member']),
+            discipline: z.enum(['backend', 'frontend', 'fullstack']),
+        }),
+    }, async (input) => toolResult(await service.organizationMemberUpsert(input)));
     server.registerTool('project.setup', {
         description: 'Create a policy-ready backend project from the native questionnaire and local repository audit, then write its secret-free marker.',
         inputSchema: z.object({
@@ -429,7 +476,7 @@ export function registerEngineeringMemoryTools(server, service) {
         }),
     }, async (input) => toolResult(await service.projectSetup(input)));
     server.registerTool('architecture.plan', {
-        description: 'List the organization architecture modules in apply order with their manifests, rename map, asset contract and tenant-specific points. Returns no file bodies.',
+        description: 'List only architecture modules compatible with the approved project runtime contract, in apply order with their manifests, rename map, asset contract and tenant-specific points. Returns no file bodies; an empty plan means continue without scaffolding.',
         inputSchema: z.object({
             projectId: z.string().uuid(),
             sessionId: z.string().uuid(),
@@ -465,9 +512,9 @@ export function registerEngineeringMemoryTools(server, service) {
         inputSchema: z.object({}),
     }, async () => toolResult(await service.organizationList()));
     server.registerTool('project.list', {
-        description: 'List projects available to the authenticated user so the agent can present them through the native questionnaire UI.',
-        inputSchema: z.object({}),
-    }, async () => toolResult(await service.projectList()));
+        description: 'List projects available to the authenticated user, optionally including archived projects that need restoration.',
+        inputSchema: z.object({ includeArchived: z.boolean().optional() }),
+    }, async (input) => toolResult(await service.projectList(input)));
     server.registerTool('project.resolve', {
         description: 'Resolve the current repository fingerprint or bind an explicitly selected project, then write the secret-free marker only after backend authorization succeeds.',
         inputSchema: z.object({
@@ -476,14 +523,52 @@ export function registerEngineeringMemoryTools(server, service) {
             projectId: z.string().uuid().optional(),
         }),
     }, async (input) => toolResult(await service.projectResolve(input)));
+    server.registerTool('project.archive', {
+        description: 'Archive a project at an explicit version while preserving its repository identity and history.',
+        inputSchema: z.object({
+            projectId: z.string().uuid(),
+            expectedVersion: z.number().int().min(1),
+        }),
+    }, async (input) => toolResult(await service.projectArchive(input)));
+    server.registerTool('project.restore', {
+        description: 'Restore an archived project at the version returned by project.list with includeArchived enabled.',
+        inputSchema: z.object({
+            projectId: z.string().uuid(),
+            expectedVersion: z.number().int().min(1),
+        }),
+    }, async (input) => toolResult(await service.projectRestore(input)));
     server.registerTool('project.member_add', {
-        description: 'Add an existing Engineering Memory account to a project with an explicit role.',
+        description: 'Add or update an existing Engineering Memory account with an explicit project role and optional discipline override.',
         inputSchema: z.object({
             projectId: z.string().min(1),
             email: z.string().email(),
             role: z.enum(['owner', 'maintainer', 'member', 'reader']),
+            discipline: z.enum(['backend', 'frontend', 'fullstack']).nullable().optional(),
         }),
     }, async (input) => toolResult(await service.projectMemberAdd(input)));
+    server.registerTool('project.member_list', {
+        description: 'List the members and roles of a project, including an archived project, so an action that requires an owner can be coordinated with the right person.',
+        inputSchema: z.object({ projectId: z.string().uuid() }),
+    }, async (input) => toolResult(await service.projectMemberList(input)));
+    server.registerTool('work_item.list', {
+        description: 'List selectable work items for a project before opening an engineering run in this chat.',
+        inputSchema: z.object({
+            projectId: z.string().uuid(),
+            status: z
+                .enum(['backlog', 'ready', 'in_progress', 'in_review', 'done', 'cancelled'])
+                .optional(),
+            priority: z.enum(['lowest', 'low', 'medium', 'high', 'highest']).optional(),
+            assigneeUserId: z.string().uuid().optional(),
+            includeArchived: z.boolean().optional(),
+        }),
+    }, async (input) => toolResult(await service.workItemList(input)));
+    server.registerTool('work_item.get', {
+        description: 'Load one project work item, including acceptance criteria and dependencies, before starting or resuming its engineering run.',
+        inputSchema: z.object({
+            projectId: z.string().uuid(),
+            workItemId: z.string().uuid(),
+        }),
+    }, async (input) => toolResult(await service.workItemGet(input)));
     server.registerTool('auth.logout', {
         description: 'Revoke the refresh session and delete local credentials; transient revoke failures preserve the session unless the user explicitly confirms local-only logout.',
         inputSchema: z.object({

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

@@ -18,7 +18,7 @@ export class RepositoryResolver {
             throw new Error('Explicit project does not match the repository marker');
         }
         const [repoFingerprint, git] = await Promise.all([
-            this.git.fingerprint(repoRoot),
+            this.git.fingerprint(repoRoot, marker?.schemaVersion ?? this.markerSchemaVersion),
             this.git.manifest(repoRoot),
         ]);
         return {

package/runtime/dist/src/runtime/active-context-store.js

@@ -43,6 +43,16 @@ export class ActiveContextStore {
         const pointers = await this.list(repoFingerprint);
         return pointers.find((pointer) => pointer.taskSlug === taskSlug) ?? null;
     }
+    async loadForSession(repoFingerprint, sessionId) {
+        if (!isUuid(sessionId)) {
+            throw new Error('Context session identifier is invalid');
+        }
+        const matches = (await this.list(repoFingerprint)).filter((pointer) => pointer.sessionId === sessionId);
+        if (matches.length > 1) {
+            throw new Error('Context session has more than one active task pointer');
+        }
+        return matches[0] ?? null;
+    }
     async list(repoFingerprint) {
         assertFingerprint(repoFingerprint);
         await this.adoptLegacyPointer(repoFingerprint);
@@ -112,7 +122,7 @@ export class ActiveContextStore {
     async setChangeBaseline(repoFingerprint, sessionId, manifest, leasePaths, taskSnapshot) {
         const pointer = taskSnapshot
             ? await this.loadForTask(repoFingerprint, taskSnapshot.taskId)
-            : await this.load(repoFingerprint);
+            : await this.loadForSession(repoFingerprint, sessionId);
         if (!pointer || pointer.sessionId !== sessionId) {
             throw new Error('Change baseline does not match the active repository session');
         }
@@ -163,9 +173,7 @@ export class ActiveContextStore {
     }
     async clearVerificationIntent(repoFingerprint, taskId) {
         await this.exclusive(repoFingerprint, async () => {
-            const pointer = taskId
-                ? await this.loadForTask(repoFingerprint, taskId)
-                : await this.load(repoFingerprint);
+            const pointer = await this.loadForTask(repoFingerprint, taskId);
             if (!pointer?.verificationIntent) {
                 return;
             }
@@ -199,9 +207,7 @@ export class ActiveContextStore {
     }
     async clearCloseIntent(repoFingerprint, taskId) {
         await this.exclusive(repoFingerprint, async () => {
-            const pointer = taskId
-                ? await this.loadForTask(repoFingerprint, taskId)
-                : await this.load(repoFingerprint);
+            const pointer = await this.loadForTask(repoFingerprint, taskId);
             if (!pointer?.closeIntent) {
                 return;
             }

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

@@ -1,4 +1,46 @@
 import { sha256, stableStringify } from '../utilities/hash.js';
+export const backendRecoveryOperationNames = [
+    'auth.signin_browser',
+    'auth.web_csrf',
+    'auth.web_signin',
+    'audit.list',
+    'organization.member_list',
+    'organization.member_upsert',
+    'project.setup',
+    'project.resolve',
+    'project.list',
+    'project.restore',
+    'project.member_list',
+    'organization.list',
+    'project.member_add',
+    'work_item.list',
+    'work_item.get',
+    'session.bootstrap',
+    'session.resume',
+    'context.refresh',
+    'context.prepare_change',
+    'memory.query',
+    'memory.history',
+    'memory.propose_revision',
+    'memory.list_proposals',
+    'memory.review_proposal',
+    'architecture.plan',
+    'architecture.record_application',
+    'task.checkpoint',
+    'task.reconcile',
+    'task.self_review',
+    'task.verify',
+    'task.close',
+    'task.abandon',
+    'task.resolve_pending_delivery',
+];
+const backendRecoveryOperations = new Set(backendRecoveryOperationNames);
+const browserSigninRecovery = 'auth.signin_browser';
+export function normalizeBackendRecovery(value) {
+    return typeof value === 'string' && backendRecoveryOperations.has(value)
+        ? value
+        : null;
+}
 export class BackendUnavailableError extends Error {
     causeValue;
     retryable = true;
@@ -14,14 +56,17 @@ export class ApiResponseError extends Error {
     retryable;
     envelope;
     recovery;
-    constructor(message, httpStatus, code, retryable, envelope, recovery = null) {
-        super(message);
+    constructor(message, httpStatus, code, retryable, envelope, recovery) {
+        const normalizedRecovery = normalizeBackendRecovery(recovery) ?? (httpStatus === 401 ? browserSigninRecovery : null);
+        super(normalizedRecovery && !message.includes('Recovery: call ')
+            ? `${message} Recovery: call ${normalizedRecovery}.`
+            : message);
         this.httpStatus = httpStatus;
         this.code = code;
         this.retryable = retryable;
         this.envelope = envelope;
-        this.recovery = recovery;
         this.name = 'ApiResponseError';
+        this.recovery = normalizedRecovery;
     }
 }
 export class ApiClient {
@@ -53,7 +98,7 @@ export class ApiClient {
         if (request.authenticated !== false) {
             const accessToken = await this.options.credentials.get('access-token');
             if (!accessToken) {
-                throw new ApiResponseError('Authentication is required', 401, null, false, null);
+                throw new ApiResponseError('Authentication is required. Recovery: call auth.signin_browser.', 401, null, false, null, browserSigninRecovery);
             }
             headers.Authorization = `Bearer ${accessToken}`;
         }
@@ -108,9 +153,9 @@ export class ApiClient {
                 this.responseSources.set(cached.value, 'stale_cache');
                 return cached.value;
             }
-            const recovery = envelope.errorModel?.recovery ?? null;
+            const recovery = envelope.errorModel?.recovery ?? (response.status === 401 ? browserSigninRecovery : null);
             const refusal = envelope.errorModel?.text ?? envelope.message ?? `Backend returned ${response.status}`;
-            throw new ApiResponseError(recovery ? `${refusal} Recovery: call ${recovery}.` : refusal, response.status, envelope.errorModel?.code ?? null, response.status === 408 || response.status === 429 || response.status >= 500, envelope, recovery);
+            throw new ApiResponseError(refusal, response.status, envelope.errorModel?.code ?? null, retryableResponse(response.status, envelope.errorModel?.retryable), envelope, recovery);
         }
         if (request.cacheKey) {
             await this.options.cache.set(cacheKey, response.headers.get('etag'), envelope);
@@ -146,7 +191,7 @@ export class ApiClient {
         const refreshToken = await this.options.credentials.get('refresh-token');
         if (!refreshToken) {
             await this.options.credentials.clear();
-            throw new ApiResponseError('Authentication has expired', 401, null, false, null);
+            throw new ApiResponseError('Authentication has expired. Recovery: call auth.signin_browser.', 401, null, false, null, browserSigninRecovery);
         }
         const controller = new AbortController();
         const timeout = setTimeout(() => controller.abort(), this.options.timeoutMs);
@@ -172,18 +217,19 @@ export class ApiClient {
         catch (error) {
             if (isDefinitiveRefreshRejection(response.status)) {
                 await this.options.credentials.clear();
+                throw new ApiResponseError('Authentication has expired. Recovery: call auth.signin_browser.', response.status, null, false, null, browserSigninRecovery);
             }
             throw error;
         }
         if (!response.ok || envelope.status === 'error') {
             if (isDefinitiveRefreshRejection(response.status)) {
                 await this.options.credentials.clear();
-                throw new ApiResponseError('Authentication has expired', response.status, null, false, envelope);
+                throw new ApiResponseError('Authentication has expired. Recovery: call auth.signin_browser.', response.status, null, false, envelope, browserSigninRecovery);
             }
-            throw new ApiResponseError(envelope.errorModel?.text ?? envelope.message ?? 'Token refresh failed', response.status, envelope.errorModel?.code ?? null, response.status === 408 || response.status === 429 || response.status >= 500, envelope);
+            throw new ApiResponseError(envelope.errorModel?.text ?? envelope.message ?? 'Token refresh failed', response.status, envelope.errorModel?.code ?? null, retryableResponse(response.status, envelope.errorModel?.retryable), envelope, null);
         }
         if (!isRefreshTokens(envelope.data)) {
-            throw new ApiResponseError('Token refresh response is missing credentials', response.status, null, false, envelope);
+            throw new ApiResponseError('Token refresh response is missing credentials. Recovery: call auth.signin_browser.', response.status, null, false, envelope, browserSigninRecovery);
         }
         await this.options.credentials.set('access-token', envelope.data.accessToken);
         if (envelope.data.refreshToken) {
@@ -196,10 +242,10 @@ export class ApiClient {
             value = await response.json();
         }
         catch {
-            throw new ApiResponseError(`Backend returned a non-JSON response with status ${response.status}`, response.status, null, response.status >= 500, null);
+            throw new ApiResponseError(`Backend returned a non-JSON response with status ${response.status}`, response.status, null, response.status >= 500, null, null);
         }
         if (!isEnvelope(value)) {
-            throw new ApiResponseError('Backend response does not match the Engineering Memory envelope', response.status, null, false, null);
+            throw new ApiResponseError('Backend response does not match the Engineering Memory envelope', response.status, null, false, null, null);
         }
         return value;
     }
@@ -223,6 +269,9 @@ function isEnvelope(value) {
         'message' in candidate &&
         'errorModel' in candidate);
 }
+function retryableResponse(status, declared) {
+    return declared ?? (status === 408 || status === 429 || status >= 500);
+}
 function isRefreshTokens(value) {
     return (value !== null &&
         !Array.isArray(value) &&

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

@@ -6,6 +6,7 @@ import { endpoints } from '../config.js';
 import { sha256, stableStringify } from '../utilities/hash.js';
 import { ApiResponseError, BackendUnavailableError, } from './api-client.js';
 import { assertSafeToPersist, normalizeRepositoryPaths } from './offline-outbox.js';
+import { BridgeRecoveryError } from './recovery-error.js';
 export const validationIds = [
     'format',
     'static_analysis',
@@ -54,6 +55,7 @@ export class BridgeService {
                 objective: input.objective,
                 taskKind: input.taskKind,
                 workItemKey: input.workItemKey,
+                workItemId: input.workItemId,
                 mode: input.mode,
                 knownRevisions: input.knownRevisions,
             }, repository.repoRoot);
@@ -71,14 +73,18 @@ export class BridgeService {
                     body: { repoFingerprint: repository.repoFingerprint },
                 });
                 const project = objectValue(resolved.data);
-                const projects = await this.dependencies.client.request(endpoints.projectList);
+                const restoreRequired = Boolean(project?.archivedAt);
+                const restoreGuidance = archivedProjectGuidance(project);
+                const projects = await this.dependencies.client.request(restoreRequired ? `${endpoints.projectList}?includeArchived=true` : endpoints.projectList);
                 return asJsonValue({
-                    projectBindingRequired: true,
+                    projectBindingRequired: !restoreRequired,
+                    restoreRequired,
                     candidate: project,
                     requestedProjectId: projectId,
                     repository: publicRepository(repository),
                     projects: projects.data,
                     outbox: { recoveredDeliveries, ...objectOrEmpty(outbox) },
+                    ...(restoreRequired ? restoreGuidance : {}),
                 });
             }
             if (!projectId) {
@@ -94,6 +100,7 @@ export class BridgeService {
                     objective: persistedBootstrap.objective,
                     taskKind: persistedBootstrap.taskKind,
                     workItemKey: persistedBootstrap.workItemKey,
+                    workItemId: persistedBootstrap.workItemId,
                     mode: persistedBootstrap.mode ?? 'write',
                     repoFingerprint: repository.repoFingerprint,
                     ...(input.mode === 'read_only'
@@ -256,7 +263,7 @@ export class BridgeService {
                 ? await this.retryVerificationRecovery(repository, pointer, backend)
                 : null;
             if (recoveredVerification) {
-                pointer = await this.dependencies.activeContexts.load(repository.repoFingerprint);
+                pointer = await this.dependencies.activeContexts.loadForTask(repository.repoFingerprint, pointer.taskId);
             }
             let hydratedFromBackend = false;
             let mergedFromBackend = false;
@@ -405,7 +412,7 @@ export class BridgeService {
             await this.recoverJournalOutbox();
             const outbox = await this.flushOutbox();
             const pendingOutbox = await this.dependencies.outbox.list();
-            const pointer = await this.dependencies.activeContexts.load(repository.repoFingerprint);
+            const pointer = await this.dependencies.activeContexts.loadForSession(repository.repoFingerprint, input.sessionId);
             if (pointer?.verificationIntent || pointer?.closeIntent) {
                 throw refuse('A verification or close intent from an earlier session is still unsettled, so a new lease would be taken against the wrong state.', 'session.resume');
             }
@@ -492,7 +499,7 @@ export class BridgeService {
                     lastSequence: numericSequence(preparedTask.lastSequence),
                 }
                 : undefined);
-            const preparedPointer = await this.dependencies.activeContexts.load(repository.repoFingerprint);
+            const preparedPointer = await this.dependencies.activeContexts.loadForSession(repository.repoFingerprint, input.sessionId);
             if (preparedPointer) {
                 const preparedData = objectValue(response.data);
                 await this.seedResumeSnapshot(preparedPointer, {
@@ -1224,11 +1231,59 @@ export class BridgeService {
         return await this.execute(async () => {
             const response = await this.dependencies.client.request(endpoints.projectMemberAdd(input.projectId), {
                 method: 'POST',
-                body: { email: input.email, role: input.role },
+                body: cleanJson({
+                    email: input.email,
+                    role: input.role,
+                    ...(input.discipline !== undefined ? { discipline: input.discipline } : {}),
+                }),
+            });
+            return asJsonValue({ membership: response.data });
+        });
+    }
+    async projectMemberList(input) {
+        return await this.execute(async () => {
+            const response = await this.dependencies.client.request(endpoints.projectMemberList(input.projectId));
+            return asJsonValue({ members: response.data });
+        });
+    }
+    async auditList(input) {
+        return await this.execute(async () => {
+            const query = new URLSearchParams();
+            if (input.organizationId) {
+                query.set('organizationId', input.organizationId);
+            }
+            if (input.projectId)
+                query.set('projectId', input.projectId);
+            if (input.beforeCreatedAt) {
+                query.set('beforeCreatedAt', input.beforeCreatedAt);
+            }
+            if (input.beforeId)
+                query.set('beforeId', input.beforeId);
+            if (input.limit !== undefined)
+                query.set('limit', String(input.limit));
+            const response = await this.dependencies.client.request(`${endpoints.auditList}?${query.toString()}`);
+            return asJsonValue({ page: response.data });
+        });
+    }
+    async organizationMemberUpsert(input) {
+        return await this.execute(async () => {
+            const response = await this.dependencies.client.request(endpoints.organizationMemberUpsert(input.organizationId), {
+                method: 'PUT',
+                body: cleanJson({
+                    email: input.email,
+                    role: input.role,
+                    discipline: input.discipline,
+                }),
             });
             return asJsonValue({ membership: response.data });
         });
     }
+    async organizationMemberList(input) {
+        return await this.execute(async () => {
+            const response = await this.dependencies.client.request(endpoints.organizationMemberList(input.organizationId));
+            return asJsonValue({ members: response.data });
+        });
+    }
     async organizationList() {
         return await this.execute(async () => {
             const authentication = await this.dependencies.browserAuth.ensureAuthenticated();
@@ -1243,6 +1298,33 @@ export class BridgeService {
             });
         });
     }
+    async workItemList(input) {
+        return await this.execute(async () => {
+            const query = new URLSearchParams();
+            if (input.status)
+                query.set('status', input.status);
+            if (input.priority)
+                query.set('priority', input.priority);
+            if (input.assigneeUserId) {
+                query.set('assigneeUserId', input.assigneeUserId);
+            }
+            if (input.includeArchived)
+                query.set('includeArchived', 'true');
+            const suffix = query.size > 0 ? `?${query.toString()}` : '';
+            const response = await this.dependencies.client.request(`${endpoints.workItemList(input.projectId)}${suffix}`);
+            return asJsonValue({
+                selectionRequired: true,
+                questionnaire: 'Select the project work item to run in this chat',
+                ...objectOrEmpty(response.data),
+            });
+        });
+    }
+    async workItemGet(input) {
+        return await this.execute(async () => {
+            const response = await this.dependencies.client.request(endpoints.workItemGet(input.projectId, input.workItemId));
+            return asJsonValue({ workItem: response.data });
+        });
+    }
     async architecturePlan(input) {
         return await this.execute(async () => {
             const body = cleanJson(input);
@@ -1297,18 +1379,46 @@ export class BridgeService {
             return asJsonValue({ organization: response.data });
         });
     }
-    async projectList() {
+    async projectList(input = {}) {
         return await this.execute(async () => {
             const authentication = await this.dependencies.browserAuth.ensureAuthenticated();
             if (authentication) {
                 return asJsonValue({ authentication });
             }
-            const response = await this.dependencies.client.request(endpoints.projectList);
+            const response = await this.dependencies.client.request(input.includeArchived
+                ? `${endpoints.projectList}?includeArchived=true`
+                : endpoints.projectList);
             return asJsonValue({
                 selectionRequired: true,
                 questionnaire: 'Select an existing project or choose new project setup',
                 projects: response.data,
+                ...(input.includeArchived
+                    ? {
+                        archivedProjectActions: (Array.isArray(response.data) ? response.data : [])
+                            .map((entry) => objectValue(entry))
+                            .filter((project) => Boolean(project?.archivedAt))
+                            .map((project) => archivedProjectGuidance(project)),
+                    }
+                    : {}),
+            });
+        });
+    }
+    async projectArchive(input) {
+        return await this.execute(async () => {
+            const response = await this.dependencies.client.request(endpoints.projectArchive(input.projectId), {
+                method: 'DELETE',
+                body: { expectedVersion: input.expectedVersion },
             });
+            return asJsonValue({ project: response.data, archived: true });
+        });
+    }
+    async projectRestore(input) {
+        return await this.execute(async () => {
+            const response = await this.dependencies.client.request(endpoints.projectRestore(input.projectId), {
+                method: 'POST',
+                body: { expectedVersion: input.expectedVersion },
+            });
+            return asJsonValue({ project: response.data, restored: true });
         });
     }
     async projectResolve(input) {
@@ -1355,12 +1465,16 @@ export class BridgeService {
                 body: { repoFingerprint: repository.repoFingerprint },
             });
             const project = objectValue(response.data);
+            const restoreRequired = Boolean(project?.archivedAt);
+            const restoreGuidance = archivedProjectGuidance(project);
             return asJsonValue({
-                resolved: project !== null,
+                resolved: project !== null && !restoreRequired,
                 project,
                 markerPath: null,
                 repository: publicRepository(repository),
                 selectionRequired: project === null,
+                restoreRequired,
+                ...(restoreRequired ? restoreGuidance : {}),
             });
         });
     }
@@ -1391,21 +1505,50 @@ export class BridgeService {
             const client = await this.clientUpdate(authenticated);
             const shipped = objectValue(objectValue(client)?.shippedKnowledge);
             const incomplete = shipped && (shipped.failure !== null || Number(shipped.live) < Number(shipped.expected));
+            const projectId = repository.projectId ?? decision?.projectId ?? null;
+            const liveTasks = authenticated && state === 'bound'
+                ? (await this.dependencies.activeContexts.list(repository.repoFingerprint)).map(describePointer)
+                : [];
+            const workItems = authenticated && state === 'bound' && projectId
+                ? await this.actionableWorkItems(projectId)
+                : [];
+            const taskSelectionRequired = liveTasks.length > 0 || workItems.length > 0;
             return asJsonValue({
                 authenticated,
                 repository: publicRepository(repository),
                 decision: state,
-                projectId: repository.projectId ?? decision?.projectId ?? null,
+                projectId,
+                liveTasks,
+                workItems,
+                taskSelectionRequired,
                 client,
-                ...(incomplete
+                ...(incomplete && state === 'bound'
                     ? {
                         shippedKnowledgeWarning: 'The backend is not serving all of the knowledge this release ships. Tell the user before relying on the rules: some are missing from the running server, so a review against them is incomplete. The counts and the reason are in client.shippedKnowledge.',
                     }
                     : {}),
-                nextAction: entryNextAction(authenticated, state),
+                nextAction: taskSelectionRequired
+                    ? 'Present the live runs and actionable project work items, then ask which one this chat should handle. Resume only the run they choose, or bootstrap a separate run with the chosen workItemId. Another live task never blocks opening this one.'
+                    : entryNextAction(authenticated, state),
             });
         });
     }
+    async actionableWorkItems(projectId) {
+        try {
+            const response = await this.dependencies.client.request(`${endpoints.workItemList(projectId)}?limit=100`);
+            const items = objectValue(response.data)?.items;
+            if (!Array.isArray(items))
+                return [];
+            const actionable = new Set(['backlog', 'ready', 'in_progress', 'in_review']);
+            return items.filter((entry) => {
+                const item = objectValue(entry);
+                return item ? actionable.has(String(item.status)) : false;
+            });
+        }
+        catch {
+            return [];
+        }
+    }
     async clientUpdate(authenticated) {
         const installed = this.dependencies.clientVersion;
         if (!authenticated) {
@@ -2107,7 +2250,7 @@ export class BridgeService {
                     kind: 'bridge_error',
                     message: error instanceof Error ? error.message : 'Bridge operation failed',
                     retryable: false,
-                    ...(error instanceof RefusalError ? { recovery: error.recovery } : {}),
+                    ...(error instanceof BridgeRecoveryError ? { recovery: error.recovery } : {}),
                 },
             };
         }
@@ -2300,6 +2443,26 @@ function objectValue(value) {
 function objectOrEmpty(value) {
     return objectValue(value ?? undefined) ?? {};
 }
+function archivedProjectGuidance(project) {
+    const projectId = typeof project?.id === 'string' ? project.id : null;
+    const expectedVersion = typeof project?.lockVersion === 'number' ? project.lockVersion : null;
+    if (project?.role === 'owner') {
+        return {
+            projectId,
+            expectedVersion,
+            requiredRole: 'owner',
+            recovery: 'project.restore',
+            nextAction: 'Call project.restore with this project id and lockVersion before continuing.',
+        };
+    }
+    return {
+        projectId,
+        expectedVersion,
+        requiredRole: 'owner',
+        recovery: 'project.member_list',
+        nextAction: 'Call project.member_list with this project id, identify an owner, and ask that owner to restore the archived project.',
+    };
+}
 function slugify(value) {
     return value
         .trim()
@@ -2404,15 +2567,8 @@ function isOfflineLeaseUsable(lease, sessionId, changedPaths, baselineDiffHash)
         return false;
     }
 }
-class RefusalError extends Error {
-    recovery;
-    constructor(message, recovery) {
-        super(message);
-        this.recovery = recovery;
-    }
-}
 function refuse(message, recovery) {
-    return new RefusalError(`${message} Recovery: call ${recovery}.`, recovery);
+    return new BridgeRecoveryError(message, recovery);
 }
 function short(value) {
     return typeof value === 'string' && value.length > 0 ? value.slice(0, 12) : 'none';

package/runtime/dist/src/runtime/principal-state.js

@@ -1,6 +1,7 @@
 import { join } from 'node:path';
 import { readJson, removeFile, writeJson } from '../utilities/files.js';
 import { sha256 } from '../utilities/hash.js';
+import { BridgeRecoveryError } from './recovery-error.js';
 export class PrincipalStateGuard {
     stateRoot;
     credentials;
@@ -31,7 +32,7 @@ export class PrincipalStateGuard {
                 return;
             }
             if ((await this.outbox.list()).length > 0) {
-                throw new Error('Pending offline work belongs to a different authenticated principal');
+                throw new BridgeRecoveryError('Pending offline work belongs to a different authenticated principal.', 'task.resolve_pending_delivery');
             }
             await this.clearPrincipalState();
             await writeJson(this.ownerPath, {
@@ -44,7 +45,7 @@ export class PrincipalStateGuard {
     async clearAfterLogout() {
         await this.exclusive(async () => {
             if ((await this.outbox.list()).length > 0) {
-                throw new Error('Pending offline work must be resolved before logout');
+                throw new BridgeRecoveryError('Pending offline work must be resolved before logout.', 'task.resolve_pending_delivery');
             }
             await this.clearPrincipalState();
             await this.credentials.clear();

package/runtime/dist/src/runtime/recovery-error.js

@@ -0,0 +1,9 @@
+export class BridgeRecoveryError extends Error {
+    recovery;
+    constructor(message, recovery) {
+        super(`${message} Recovery: call ${recovery}.`);
+        this.recovery = recovery;
+        this.name = 'BridgeRecoveryError';
+    }
+}
+//# sourceMappingURL=recovery-error.js.map

package/skill/references/lifecycle.md

@@ -4,12 +4,16 @@
 
 Sign-in decides nothing beyond who the user is. The organization and the project are chosen after it, through the questionnaires in `questionnaires.md`, and both listings end with an option to create a new one. Ask for both whenever this session has not already confirmed them, and ask again the moment the user says they want to change either — changing the organization always means choosing the project again.
 
-Treat `.engineering-memory/project.json` as the binding authority. The marker contains only `projectId` and `schemaVersion`. Never infer a binding from a directory name or Git remote when a marker exists.
+Treat `.engineering-memory/project.json` as the binding authority. The marker contains only `projectId` and `schemaVersion`. Never infer a binding from a directory name or Git remote when a marker exists. Schema 1 markers retain the legacy commit-aware repository identity so existing bindings keep working. Schema 2 markers use the canonical remote or main-worktree identity, which stays unchanged when an unborn repository receives its first commit. Never rewrite or upgrade a marker by hand.
+
+An archived project is recoverable state, not a missing or conflicting binding. When an owner receives `project.restore`, use the `projectId` and `expectedVersion` in its data and call that operation before retrying. A non-owner receives `project.member_list` instead: list the members, identify a project owner and explain that the owner must restore the exact project before this session can retry. Use `project.list` with `includeArchived: true` when an owner must first select the archived project. Never create or bind a replacement project to escape archive state.
 
 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.
 
+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.
+
 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.
 
 A task nobody is going to finish is abandoned rather than inherited. Ask the user first, then call `task.abandon` with the task ID and their reason: it records the task as abandoned, withdraws the proposals it left waiting for review, releases its lease and session, and removes its local pointer. It changes nothing about any other task. Never abandon a task on your own judgement, and never abandon one to get past an error in your own.
@@ -43,12 +47,14 @@ When the request covers both halves of a linked product — a flow that needs en
 as screens — and the user's discipline covers both, it is one work item and two tasks: one in
 each repository. Verification and the commit gate stay per repository because a commit is.
 
-Ask which side to start on, propose the work item key, and open the task in the repository
-being worked in. When the work moves to the other side, open its task with the same
-`workItemKey` and that repository's root — every tool takes `repoRoot`, and both stay open at
-once. `context.prepare_change` then returns `siblingTasks`: the other task's objective, status
-and recent checkpoints, so a decision taken on one side is visible on the other without anyone
-repeating it.
+Ask which side to start on and select the work item before opening the first task. When the work
+moves to the other side, open its task with the same `workItemId` and that repository's root —
+every tool takes `repoRoot`, and both stay open at once. The backend accepts that id only from the
+current project or a directly linked project the account can work in, and derives the display key
+from the work item. `context.prepare_change` then returns `siblingTasks`: the other task's
+objective, status and recent checkpoints, so a decision taken on one side is visible on the other
+without anyone repeating it. A legacy key is never an authorization boundary; key-only tasks can
+see siblings only inside directly linked projects where the account is already a member.
 
 Do not open the second task speculatively. Open it when the work actually reaches that side.
 

package/skill/references/memory-updates.md

@@ -4,12 +4,14 @@ Backend resources are immutable revisions. The local agent drafts structured con
 
 Use `memory.propose_revision` for project profiles, engineering rules, service contracts, localization contracts, navigation contracts, state contracts, screen logic, component mappings, Figma mappings, current deviations, quality gates, task history, and architecture templates.
 
-Knowledge is layered. `scope: product` proposes a change to the shared engineering core that every organization reads, `scope: organization` proposes one that only this organization reads and which hides the product text for that key, and `scope: project` proposes a record for this project alone. The nearest layer wins when context is delivered. A product-scope proposal is the way a developer improves the product itself from inside their own project, and it requires nothing but the skill.
+Knowledge is layered. `scope: product` proposes a change to the shared engineering core that every organization reads, `scope: organization` proposes one that only this organization reads and which hides the product text for that key, and `scope: project` proposes a record for this project alone. The nearest layer wins when context is delivered. A product-scope proposal is the way a developer improves the product itself from inside their own project, and it requires nothing but the skill. It remains inactive for the configured product release principal to review; waiting in that platform queue does not prevent the contributor's task from verifying or closing.
 
 An architecture template is organization-scoped source, not prose. When a task establishes or changes a shared architecture structure that the templates carry, the template is stale and needs its own revision. Its manifest and content must stay in step: one `files[]` entry per `## file:` block, same path, byte count, SHA-256 and order. See `scaffolding.md`.
 
 Every proposal must include the current `baseRevision`. A conflict means the resource changed after context pinning. Do not overwrite it. Refresh context, compare revisions, and ask the user when the merge changes intent.
 
+When a revision changes which stacks receive the resource, send the complete selector as `metadata.appliesToStacks`. An absent selector preserves the resource's current stack scope; `[]` deliberately makes it universal. A concrete source template keeps the family selector, such as `["spring-boot"]`, and declares its exact machine-readable `metadata.compatibility`: language and supported language versions, framework and supported framework release lines, build tools and namespaces. The backend compares that contract with the approved project profile `runtimeContract` before returning source. Version-neutral Spring engineering rules remain `["spring-boot"]` and carry no source compatibility gate. Never broaden or delete a compatibility contract merely so an older project can use Engineering Memory; deliver the compatible rules and leave incompatible scaffolding unselected.
+
 Permanent proposals remain inactive until an authorized user explicitly approves them. Call `memory.review_proposal` only after receiving that decision through the native questionnaire.
 
 A proposal created in an earlier session, or created by a bundle import, is found with `memory.list_proposals`. It reports every proposal still waiting for review that this project or its organization can reach, with the reason, the current and base revision numbers, and whether the proposal now needs a rebase. Pass a single `proposalId` to read that proposal's proposed text before putting the decision to the user. Never present a decision the user cannot see the content of, and never approve on the strength of the summary alone. Approval makes the current context lease stale. Call `context.refresh`, reread the changed rule, prepare a new change lease, and rerun affected validation.

package/skill/references/questionnaires.md

@@ -30,6 +30,8 @@ A new organization is not empty. It reads the product engineering core immediate
 
 Once the organization is chosen, call `project.list` and offer that organization's projects, with **create a new project** last. Ignore projects belonging to other organizations; a listing that mixes them is how work lands in the wrong place. Creating one follows the unbound-repository flow below.
 
+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, identify the project owners in its result and tell the user which owner must perform the versioned restore. 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.
+
 Ask both questions again whenever a chat starts in a repository whose binding you have not confirmed in this session.
 
 ## Switching Organization or Project
@@ -50,17 +52,17 @@ Ask whether the current repository belongs to an existing accessible project, sh
 
 For a repository the backend has not seen before, ask whether this is an existing codebase import or a greenfield project. Before a marker or backend task exists, an existing-codebase import may perform one bounded local read-only structural and Figma discovery pass. It must not edit code. Use the findings in a native questionnaire to confirm the initial project profile and the repository-relative patterns that identify new memory resources. Send them as `discoveryUnits`, one unit per kind the project actually has: a client project declares `screen_logic` and `component_mapping`, and a server-side project declares `module_logic`, `data_model` and `api_endpoint` against its own layout. Never ask a server-side project for screen patterns, and never invent a unit for a kind the repository does not contain. Then call `project.setup`; the backend creates the project, owner membership, active profile revision, and pinned discovery policy atomically. Write the returned marker only after that succeeds, then start the normal `session.bootstrap` lifecycle. Later discoveries are reviewable memory proposals.
 
-Greenfield setup asks for project name, framework, the response envelope, the exception model, authentication needs, localization languages, storage policy, and the initial discovery patterns. A client project is also asked for the Figma library and screen links if available, the design token sources, the page architecture and the navigation pattern; a server-side project is asked instead for the data layer, the migration tool and how configuration and secrets arrive. Ask what the project is before deciding which list applies. Never invent missing answers. Do not write a marker unless the setup response contains the active initial profile and discovery policy.
+Greenfield setup asks for project name, framework, the response envelope, the exception model, authentication needs, localization languages, storage policy, and the initial discovery patterns. A client project is also asked for the Figma library and screen links if available, the design token sources, the page architecture and the navigation pattern; a server-side project is asked instead for the data layer, the migration tool and how configuration and secrets arrive. A Spring project must also name Maven or Gradle, its Java release, its exact Spring Boot version and its `javax` or `jakarta` namespace before any architecture template is offered; `Spring Boot` alone is not enough information to select compatible source. Record those confirmed values in `initialProjectProfile.metadata.runtimeContract` as `language: "java"`, `languageVersion`, `framework: "spring-boot"`, `frameworkVersion`, `buildTool` and `namespace`. Never infer or invent this object. The backend compares it with each source module and returns no incompatible module; an absent contract means broad Spring rules still apply but no constrained source template is offered. Ask what the project is before deciding which list applies. Do not write a marker unless the setup response contains the active initial profile and discovery policy.
 
 After setup, ask whether to build the project from the organization architecture templates. If the user accepts, follow `scaffolding.md`: confirm the optional modules, then confirm the package name and the concrete class name behind every rename placeholder in one questionnaire, then ask for each required asset role and each tenant-specific value the templates deliberately leave open.
 
 ## Project Membership
 
-Ask for the registered email and intended role. Show owner, maintainer, member, and reader effects. Confirm before calling `project.member_add`.
+Ask for the registered email and intended role. Show owner, maintainer, member, and reader effects. Confirm before calling `project.member_add`. A project grant is valid only while the same account belongs to the parent organization. If the call reports `organization.member_upsert`, do not retry the project write: an organization owner must first confirm the organization role and discipline and call that recovery. When the current account is not an organization owner, explain that coordination requirement instead of pretending the project grant succeeded. Retry `project.member_add` only after the parent grant exists.
 
 ## 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.
+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.
 
 ## Flow Entry and Exit
 

package/skill/references/scaffolding.md

@@ -1,6 +1,6 @@
 # Greenfield Scaffolding
 
-Architecture templates are source modules stored as approved engineering memory. The product ships a starter for each stack it supports and an organization may hold its own, which takes precedence; a template never belongs to a single project. A greenfield project reproduces the team architecture from those modules instead of re-deriving it from prose rules. The backend stores, versions and authorizes them; it never generates code. The agent applies the rename map and writes every file itself.
+Architecture templates are source modules stored as approved engineering memory. The product may ship one or more explicitly compatible starter generations for a stack and an organization may hold its own, which takes precedence; a template never belongs to a single project. General support for a stack does not imply that every starter generation is available. A greenfield project reproduces the team architecture from compatible modules instead of re-deriving it from prose rules. The backend stores, versions and authorizes them; it never generates code. The agent applies the rename map and writes every file itself.
 
 ## Organization first
 
@@ -13,13 +13,14 @@ Call `organization.list` and ask the user which organization the project belongs
 1. Open the task in `scaffold` mode and complete the normal bootstrap, discovery and `context.prepare_change` steps. Prepare the full set of intended paths before the first write.
 2. Call `architecture.plan`. It returns each module's manifest in apply order with its dependencies, rename map, string replacements, pubspec dependencies, asset contract and tenant-specific points. It carries no file bodies.
 3. Present the optional modules through the native questionnaire. A package-shaped project usually skips the application modules; an application usually takes them.
-4. Confirm the naming decisions in one questionnaire: package name and the concrete class name behind every rename placeholder. Never invent a name the user did not choose.
-5. For each module in `applyOrder`, call `architecture.module`, apply the rename map and string replacements, write the files, then call `architecture.record_application` with the template path and the written path of every file. Respect `dependsOn`; do not reorder modules.
-6. Merge every module's `packageDependencies` into the project's dependency manifest — `pubspec.yaml`, `package.json`, whatever the stack uses. Keep the existing constraint when a dependency already exists and report the conflict.
-7. Satisfy the `assetContract`. Ask the user for each required asset role. Never invent an asset, never ship a placeholder binary, and never copy a licensed font from another project.
-8. Resolve every `tenantSpecific` point through the questionnaire: base URLs, backend header contracts, storage key prefixes, supported locales, bundle identifiers. These are deliberately absent from the template. Do not guess them.
-9. Run code generation and localization generation, then static analysis and tests. Record the validation checkpoints as usual.
-10. Reconcile each applied template resource with a `scaffold_applied` reconciliation carrying a short reason, then run `task.verify`.
+4. Treat the modules returned by the backend as the compatibility boundary: it compares each manifest's `compatibility` object with the approved project profile `runtimeContract` before returning it. Read both contracts back and confirm them in the questionnaire; never add a module the plan withheld or substitute a conversational guess. For Spring, the comparison covers Java release, exact Spring Boot release line, build tool and `javax` or `jakarta` namespace. If the plan is empty, say that no compatible starter exists and continue without scaffolding; never upgrade or downgrade the project to make a template fit.
+5. Confirm the naming decisions in one questionnaire: package name and the concrete class name behind every rename placeholder. Never invent a name the user did not choose.
+6. For each module in `applyOrder`, call `architecture.module`, apply the rename map and string replacements, write the files, then call `architecture.record_application` with the template path and the written path of every file. Respect `dependsOn`; do not reorder modules.
+7. Merge every module's `packageDependencies` into the project's dependency manifest — `pubspec.yaml`, `package.json`, whatever the stack uses. Keep the existing constraint when a dependency already exists and report the conflict.
+8. Satisfy the `assetContract`. Ask the user for each required asset role. Never invent an asset, never ship a placeholder binary, and never copy a licensed font from another project.
+9. Resolve every `tenantSpecific` point through the questionnaire: base URLs, backend header contracts, storage key prefixes, supported locales, bundle identifiers. These are deliberately absent from the template. Do not guess them.
+10. Run the stack's generator, compiler or type checker against every emitted source file before calling the scaffold complete. If the required local compiler is unavailable or below the selected template's declared release, stop with the exact tool and version needed rather than claiming the source is valid. This refusal applies only to applying that template, not to using Engineering Memory with an existing project. Then run code generation, localization generation, static analysis and tests that the project requires.
+11. Reconcile each applied template resource with a `scaffold_applied` reconciliation carrying a short reason, then run `task.verify`.
 
 ## What scaffold mode does and does not relax