engineering-memory 1.11.27 → 1.11.29

package/runtime/dist/src/runtime/merge-request-sync.js

@@ -0,0 +1,322 @@
+import { randomUUID } from 'node:crypto';
+import * as z from 'zod/v4';
+import { endpoints } from '../config.js';
+import { GitLabError, gitLabRemote, projectPath, reviewState, } from '../providers/gitlab.js';
+import { BridgeRecoveryError } from './recovery-error.js';
+export const reviewDeliverySchema = z.object({
+    taskId: z.string(),
+    externalTaskId: z.string().nullish(),
+    state: z.string(),
+    choice: z.string().nullish(),
+    baseBranch: z.string().nullish(),
+    deliveredCommit: z.string().nullish(),
+    pushed: z.boolean().nullish(),
+    branch: z.string().nullish(),
+    workItemKey: z.string().nullish(),
+    reviewState: z.string().nullish(),
+    reviewRequest: z
+        .object({
+        provider: z.string(),
+        host: z.string(),
+        repository: z.string(),
+        number: z.number().int().positive(),
+        url: z.string(),
+        state: z.string(),
+        source: z.string().optional(),
+    })
+        .nullish(),
+});
+const pullRequestChoices = ['commit_push_draft_pr', 'commit_push_pr'];
+export const waitingReview = ['pending', 'in_review', 'findings_open'];
+export const concludedReview = ['passed', 'skipped', 'exempted'];
+const draftPrefix = /^\s*(?:(?:\[draft\]|\(draft\)|draft:|\[wip\]|wip:)\s*)+/i;
+export function opensAsDraft(delivery) {
+    const review = delivery.reviewState ?? '';
+    return (waitingReview.includes(review) ||
+        (delivery.choice === 'commit_push_draft_pr' && !concludedReview.includes(review)));
+}
+export function awaitsReviewRequest(delivery) {
+    return (!delivery.reviewRequest &&
+        delivery.state === 'delivered' &&
+        delivery.pushed === true &&
+        pullRequestChoices.includes(delivery.choice ?? ''));
+}
+export function reviewDeliveries(data) {
+    const items = z.object({ items: z.array(z.unknown()) }).safeParse(data);
+    return (items.success ? items.data.items : []).flatMap((item) => {
+        const delivery = reviewDeliverySchema.safeParse(item);
+        return delivery.success ? [delivery.data] : [];
+    });
+}
+const manualWay = 'Opening it in GitLab yourself always works: record it afterwards with task.review_request and its link.';
+export class MergeRequests {
+    client;
+    tokens;
+    gitlab;
+    git;
+    passes = new Map();
+    running = new Set();
+    constructor(client, tokens, gitlab, git) {
+        this.client = client;
+        this.tokens = tokens;
+        this.gitlab = gitlab;
+        this.git = git;
+    }
+    async open(input) {
+        const delivery = reviewDeliverySchema.parse((await this.client.request(endpoints.taskDelivery(input.projectId, input.taskId)))
+            .data);
+        if (delivery.reviewRequest)
+            return { recorded: { url: delivery.reviewRequest.url, state: delivery.reviewRequest.state } };
+        if (delivery.state === 'cancelled')
+            throw new BridgeRecoveryError('This delivery was concluded without delivering, so it gets no merge request.', 'task.delivery');
+        const branch = delivery.branch;
+        if (!branch)
+            throw new BridgeRecoveryError('This task has no branch, so there is nothing to open a merge request from.', 'task.review_request');
+        const chosen = pullRequestChoices.includes(delivery.choice ?? '');
+        const target = input.targetBranch ?? (chosen ? delivery.baseBranch : null);
+        if (!target)
+            throw new BridgeRecoveryError('The delivery answer did not choose a pull request, so it names no target branch. If the user wants a merge request, call again with the targetBranch they name.', 'task.open_review_request');
+        const draft = input.draft ?? opensAsDraft(delivery);
+        const pushUrl = await this.git.branchPushUrl(input.repoRoot, branch);
+        if (!pushUrl)
+            throw new BridgeRecoveryError(`This clone has no remote that ${branch} is pushed to. ${manualWay}`, 'task.review_request');
+        const remote = gitLabRemote(pushUrl);
+        if ('refusal' in remote)
+            throw new BridgeRecoveryError(remoteRefusal(remote.refusal, pushUrl), 'task.review_request');
+        const address = (await this.tokens.address(remote.host)) ?? remote.address;
+        const token = await this.tokens.token(address);
+        if (!token)
+            throw new BridgeRecoveryError(`No GitLab token is saved on this computer for ${address}. Call gitlab.token and give the user the link it returns; they save their own token there, and then this call works. ${manualWay}`, 'gitlab.token', { address });
+        const path = projectPath(address, remote.path);
+        try {
+            const project = await this.gitlab.project(address, token, path);
+            if (!project)
+                throw new BridgeRecoveryError(`GitLab at ${address} shows no project ${path} to this token. If GitLab runs under a path (like https://host/gitlab), save that address with gitlab.token; otherwise the token's user needs access to the project. ${manualWay}`, 'gitlab.token', { address, project: path });
+            const remoteHead = await this.gitlab.branch(address, token, path, branch);
+            if (!remoteHead)
+                throw new BridgeRecoveryError(`${branch} is not on GitLab yet. Push it, then call again.`, 'task.open_review_request');
+            const local = await this.git.branchCommit(input.repoRoot, branch).catch(() => null);
+            const delivered = local?.commit ?? delivery.deliveredCommit ?? null;
+            if (delivered &&
+                delivered !== remoteHead.commit &&
+                !(await this.gitlab.contains(address, token, path, branch, delivered)))
+                throw new BridgeRecoveryError(`${branch} on GitLab does not have ${delivered.slice(0, 12)} yet, so a merge request would lack it. Push the branch, then call again.`, 'task.open_review_request');
+            const source = { id: project.id, path };
+            const existing = (await this.gitlab.mergeRequests(address, token, source, branch, 'opened'))[0];
+            if (existing)
+                return opened(existing, true);
+            if (!(await this.gitlab.branch(address, token, path, target)))
+                throw new BridgeRecoveryError(`The target branch ${target} does not exist on GitLab. Ask the user which branch the merge request goes into and call again with targetBranch.`, 'task.open_review_request');
+            const title = ((draft ? 'Draft: ' : '') +
+                (input.title ??
+                    defaultTitle(local?.subject || remoteHead.title || branch, delivery.workItemKey))).slice(0, 255);
+            try {
+                return opened(await this.gitlab.createMergeRequest(address, token, path, {
+                    source: branch,
+                    target,
+                    title,
+                    ...(input.description ? { description: input.description } : {}),
+                }), false);
+            }
+            catch (error) {
+                if (!(error instanceof GitLabError) ||
+                    !['conflict', 'unknown_outcome', 'server_error'].includes(error.failure))
+                    throw error;
+                const found = (await this.gitlab.mergeRequests(address, token, source, branch, 'opened'))[0];
+                if (found)
+                    return opened(found, true);
+                throw error;
+            }
+        }
+        catch (error) {
+            if (error instanceof GitLabError)
+                throw gitLabRefusal(error);
+            throw error;
+        }
+    }
+    async markReady(request) {
+        const link = await this.tokens.forLink(request.host, request.repository);
+        const token = link ? await this.tokens.token(link.address) : null;
+        if (!link || !token)
+            throw new BridgeRecoveryError(`No GitLab token is saved on this computer for ${request.host}. Ask the user to mark ${request.url} ready in GitLab ("Mark as ready"); Engineering Memory follows it. Or call gitlab.token so they save their own token here, then call review.make_ready again.`, 'gitlab.token');
+        try {
+            const current = await this.gitlab.mergeRequest(link.address, token, link.project, request.number);
+            if (reviewState(current) !== 'draft')
+                return { url: current.web_url, state: reviewState(current) };
+            if (current.title === undefined)
+                throw new GitLabError('unexpected_answer', link.address, null, null);
+            const after = await this.gitlab.retitleMergeRequest(link.address, token, link.project, request.number, current.title.replace(draftPrefix, '') || defaultTitle(current.source_branch, null));
+            return { url: after.web_url, state: reviewState(after) };
+        }
+        catch (error) {
+            if (!(error instanceof GitLabError))
+                throw error;
+            const at = error.address;
+            const reason = error.failure === 'token_rejected'
+                ? `GitLab at ${at} no longer accepts the saved token (expired or revoked); gitlab.token saves a new one.`
+                : error.failure === 'not_allowed'
+                    ? `GitLab at ${at} refused this with the saved token: changing a merge request needs the api scope and Developer or higher.`
+                    : error.failure === 'unreachable'
+                        ? `This computer cannot reach ${at}; if GitLab is reachable only from the company network, connect and call review.make_ready again.`
+                        : error.failure === 'unknown_outcome'
+                            ? `The answer of GitLab at ${at} was lost after the change was sent, so it may already be ready; calling review.make_ready again is safe and reads where it stands.`
+                            : `GitLab at ${at} answered ${error.failure.replace(/_/g, ' ')}${error.status ? ` (${error.status})` : ''}.`;
+            throw new BridgeRecoveryError(`${reason} ${request.url} may still be a draft: the user can mark it ready in GitLab ("Mark as ready"); Engineering Memory follows it.`, error.failure === 'token_rejected' || error.failure === 'not_allowed'
+                ? 'gitlab.token'
+                : 'review.make_ready', { address: at, failure: error.failure, status: error.status });
+        }
+    }
+    schedule(projectId, repoRoot, deliveries) {
+        const now = Date.now();
+        const last = this.passes.get(projectId);
+        if (last !== undefined && now - last < 5 * 60 * 1000)
+            return;
+        this.passes.set(projectId, now);
+        const pass = this.read(projectId, repoRoot, deliveries).then(() => undefined, () => undefined);
+        this.running.add(pass);
+        void pass.finally(() => this.running.delete(pass));
+    }
+    async settle() {
+        while (this.running.size)
+            await Promise.all([...this.running]);
+    }
+    async read(projectId, root, given) {
+        if (!(await this.tokens.any()))
+            return { reported: 0 };
+        const repoRoot = typeof root === 'function' ? await root().catch(() => null) : root;
+        const deliveries = given ??
+            reviewDeliveries((await this.client.request(`${endpoints.projectDeliveries(projectId)}?state=review&limit=100`)).data);
+        const pass = { failed: new Set(), projects: new Map(), calls: 100 };
+        const queue = [...deliveries];
+        let reported = 0;
+        const worker = async () => {
+            for (let delivery = queue.shift(); delivery && pass.calls > 0; delivery = queue.shift()) {
+                const found = await this.follow(delivery, repoRoot, pass).catch(() => null);
+                if (found && (await this.report(projectId, delivery.taskId, found)))
+                    reported++;
+            }
+        };
+        await Promise.all([worker(), worker(), worker(), worker()]);
+        return { reported };
+    }
+    async follow(delivery, repoRoot, pass) {
+        const known = delivery.reviewRequest;
+        if (known) {
+            if (known.provider !== 'gitlab' || !['draft', 'ready'].includes(known.state))
+                return null;
+            const link = await this.tokens.forLink(known.host, known.repository);
+            const token = link && !pass.failed.has(link.address) ? await this.tokens.token(link.address) : null;
+            if (!link || !token)
+                return null;
+            const request = await this.call(pass, link.address, () => this.gitlab.mergeRequest(link.address, token, link.project, known.number));
+            if (!request)
+                return null;
+            const state = reviewState(request);
+            return state !== known.state || known.source !== 'machine' ? { url: known.url, state } : null;
+        }
+        if (!repoRoot || !delivery.branch)
+            return null;
+        const pushUrl = await this.git.branchPushUrl(repoRoot, delivery.branch).catch(() => null);
+        const remote = pushUrl ? gitLabRemote(pushUrl) : null;
+        if (!remote || 'refusal' in remote)
+            return null;
+        const address = (await this.tokens.address(remote.host)) ?? remote.address;
+        const token = pass.failed.has(address) ? null : await this.tokens.token(address);
+        if (!token)
+            return null;
+        const path = projectPath(address, remote.path);
+        const key = `${address}\n${path}`;
+        if (!pass.projects.has(key))
+            pass.projects.set(key, await this.call(pass, address, () => this.gitlab.project(address, token, path)));
+        const project = pass.projects.get(key);
+        if (!project)
+            return null;
+        const requests = await this.call(pass, address, () => this.gitlab.mergeRequests(address, token, { id: project.id, path }, delivery.branch));
+        const rank = (request) => request.state === 'opened' || request.state === 'locked'
+            ? 0
+            : request.state === 'merged'
+                ? 1
+                : 2;
+        const chosen = (requests ?? [])
+            .filter((request) => rank(request) < 2)
+            .sort((left, right) => rank(left) - rank(right) ||
+            Number(right.sha === delivery.deliveredCommit) -
+                Number(left.sha === delivery.deliveredCommit))[0];
+        return chosen ? { url: chosen.web_url, state: reviewState(chosen) } : null;
+    }
+    async call(pass, address, request) {
+        if (pass.failed.has(address) || pass.calls <= 0)
+            return null;
+        pass.calls--;
+        try {
+            return await request();
+        }
+        catch (error) {
+            if (!(error instanceof GitLabError))
+                throw error;
+            pass.failed.add(address);
+            return null;
+        }
+    }
+    async report(projectId, taskId, found) {
+        try {
+            await this.client.request(endpoints.taskReviewRequest(projectId, taskId), {
+                method: 'POST',
+                body: { url: found.url, state: found.state, source: 'machine' },
+                idempotencyKey: randomUUID(),
+            });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+function opened(request, reused) {
+    return {
+        url: request.web_url,
+        state: reviewState(request),
+        sourceBranch: request.source_branch,
+        targetBranch: request.target_branch,
+        reused,
+    };
+}
+export function defaultTitle(subject, workItemKey) {
+    const title = subject.trim().slice(0, 240) || 'Merge request';
+    return workItemKey && !title.toLowerCase().includes(workItemKey.toLowerCase())
+        ? `${workItemKey}: ${title}`
+        : title;
+}
+function remoteRefusal(refusal, pushUrl) {
+    switch (refusal) {
+        case 'github':
+            return `The branch is pushed to GitHub (${pushUrl}). Engineering Memory opens merge requests only on GitLab so far: open the pull request with the tools you have and record it with task.review_request.`;
+        case 'ip':
+            return `The remote is reached by an IP address (${pushUrl}), and Engineering Memory records no link with an IP address in it. Open the merge request in GitLab and move the work item with work_item.update.`;
+        case 'local':
+            return `The remote is a folder on disk (${pushUrl}), not a GitLab server. ${manualWay}`;
+        default:
+            return `The remote address ${pushUrl} is not one Engineering Memory can read as a GitLab project. ${manualWay}`;
+    }
+}
+function gitLabRefusal(error) {
+    const at = error.address;
+    const details = { address: at, failure: error.failure, status: error.status };
+    switch (error.failure) {
+        case 'token_rejected':
+            return new BridgeRecoveryError(`GitLab at ${at} no longer accepts the saved token (expired or revoked). Call gitlab.token so the user can save a new one. ${manualWay}`, 'gitlab.token', details);
+        case 'not_allowed':
+            return new BridgeRecoveryError(`GitLab at ${at} refused this with the saved token: it needs the api scope and a role that may open merge requests in the project (Developer or higher). Nothing was opened. ${manualWay}`, 'gitlab.token', details);
+        case 'unreachable':
+            return new BridgeRecoveryError(`This computer cannot reach ${at}. If GitLab is only reachable from the company network, the user connects (for example through the VPN) and you call again. Nothing was opened.`, 'task.open_review_request', details);
+        case 'untrusted_certificate':
+            return new BridgeRecoveryError(`This computer does not trust the certificate of ${at}. If the company uses its own certificate, the user sets NODE_EXTRA_CA_CERTS to its file and restarts the coding agent. Nothing was opened.`, 'task.open_review_request', details);
+        case 'unknown_outcome':
+            return new BridgeRecoveryError(`The answer from ${at} was lost after the merge request was sent, and it is not visible yet. Call again: an open merge request of the branch is reused, never opened twice.`, 'task.open_review_request', details);
+        case 'redirected':
+            return new BridgeRecoveryError(`${at} answered with a redirect, so the saved address is probably not GitLab's own. Call gitlab.token so the user can correct the address.`, 'gitlab.token', details);
+        default:
+            return new BridgeRecoveryError(`GitLab at ${at} answered ${error.failure.replace(/_/g, ' ')}${error.status ? ` (${error.status})` : ''}${error.detail ? `: ${error.detail}` : ''}. Nothing more was done. ${manualWay}`, 'task.open_review_request', details);
+    }
+}
+//# sourceMappingURL=merge-request-sync.js.map

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

@@ -9,15 +9,17 @@ export class PrincipalStateGuard {
     outbox;
     activeContexts;
     gate;
+    gitlabTokens;
     ownerPath;
     queue = Promise.resolve();
-    constructor(stateRoot, credentials, cache, outbox, activeContexts, gate) {
+    constructor(stateRoot, credentials, cache, outbox, activeContexts, gate, gitlabTokens) {
         this.stateRoot = stateRoot;
         this.credentials = credentials;
         this.cache = cache;
         this.outbox = outbox;
         this.activeContexts = activeContexts;
         this.gate = gate;
+        this.gitlabTokens = gitlabTokens;
         this.ownerPath = join(stateRoot, 'principal-owner.json');
     }
     async ensure() {
@@ -55,6 +57,7 @@ export class PrincipalStateGuard {
         await this.cache.clear();
         await this.activeContexts.clear();
         await this.gate.clear();
+        await this.gitlabTokens?.clear();
         await removeFile(this.ownerPath, this.stateRoot);
     }
     async exclusive(action) {

package/runtime/dist/src/runtime/review-masking.js

@@ -0,0 +1,31 @@
+import { restrictedValueKind } from './privacy-detector.js';
+const masks = [
+    [/[\p{L}\p{N}._%+-]{1,64}@[\p{L}\p{N}.-]+\.\p{L}{2,63}/gu, 'e-mail address', () => '[e-mail]'],
+    [
+        /(?<![\d.])(?:\d{1,3}\.){3}\d{1,3}(?![\d.])/g,
+        'IP address',
+        (match) => (match.split('.').every((part) => Number(part) <= 255) ? '[IP]' : match),
+    ],
+    [
+        /[A-Z]:[\\/](?:Users|Documents and Settings)[\\/][^\\/\s"'<>:|?*]+|\\\\[^\\\s]+\\Users\\[^\\/\s"'<>*]+|(?:\/mnt\/[a-z]|\/cygdrive\/[a-z]|\/System\/Volumes\/Data|\/Volumes\/[^/\s]+|\/export)\/(?:Users|home)\/[^\\/\s"'<>*]+/gi,
+        'user folder',
+        () => '~',
+    ],
+    [
+        /(^|[\s"'(<=])\/(?:[a-z]\/)?(?:Users|home)\/[^\\/\s"'<>*]+/gi,
+        'user folder',
+        (_, before) => before + '~',
+    ],
+];
+export function maskFinding(description) {
+    const masked = new Set();
+    let text = description;
+    for (const [pattern, kind, replace] of masks) {
+        const next = text.replace(pattern, replace);
+        if (next !== text)
+            masked.add(kind);
+        text = next;
+    }
+    return { text, masked: [...masked], left: restrictedValueKind(text, 'description') };
+}
+//# sourceMappingURL=review-masking.js.map

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

@@ -51,6 +51,7 @@ const startWording = z.strictObject({
     newBranch: text,
     newBranchOrContinue: text,
     continuePlan: text,
+    continueReview: text,
     example: text,
     stay: text,
     base: z.strictObject({
@@ -199,11 +200,16 @@ export function taskStartDefinition(facts) {
         message: copy.message,
         context: keepOnly
             ? copy.keepContext
-            : binding.base?.kind === 'existing'
-                ? format(copy.continuePlan, language, { branch: binding.base.branch })
-                : format(Object.values(binding.bases ?? {}).some((base) => base.kind === 'existing')
-                    ? copy.newBranchOrContinue
-                    : copy.newBranch, language, { name: binding.name }) + (binding.base ? ' · ' + sourceLabel(binding.base, facts.currentBranch) : ''),
+            : binding.base?.kind === 'existing' && facts.reviewedTask
+                ? format(copy.continueReview, language, {
+                    branch: binding.base.branch,
+                    task: facts.reviewedTask,
+                })
+                : binding.base?.kind === 'existing'
+                    ? format(copy.continuePlan, language, { branch: binding.base.branch })
+                    : format(Object.values(binding.bases ?? {}).some((base) => base.kind === 'existing')
+                        ? copy.newBranchOrContinue
+                        : copy.newBranch, language, { name: binding.name }) + (binding.base ? ' · ' + sourceLabel(binding.base, facts.currentBranch) : ''),
         example: keepOnly ? format(copy.stay, language, { source: current }) : copy.example,
         questions,
         binding: JSON.parse(JSON.stringify(binding)),
@@ -216,7 +222,7 @@ function legacyTaskStartDefinition(facts) {
     const folder = facts.folder;
     const keepOnly = facts.keepCurrent === true || !facts.currentCommit;
     const here = !keepOnly && !folder.managed && !folder.heldBy && folder.clean;
-    const keep = keepOnly || (!folder.managed && !folder.heldBy && !folder.holder);
+    const keep = !facts.reviewedTask && (keepOnly || (!folder.managed && !folder.heldBy && !folder.holder));
     const holder = here && folder.holder ? holderIdentity(folder.holder) : null;
     const currentLabel = sourceLabel({ kind: 'current', ...(facts.currentCommit ? { commit: facts.currentCommit } : {}) }, facts.currentBranch);
     const binding = {

package/skill/references/lifecycle.md

@@ -296,9 +296,19 @@ Call `task.close` only after verification and only when the current diff still m
 
 After memory approval, finish any required reconciliation and verification, then call `task.close` in the same turn; do not stop at publishing memory or at a successful verify result. Closing is not the end of the turn either. The MCP `task.close` call closes the verified task and opens its durable, mode-governed delivery selector itself: commit, commit and push, commit and push with a draft PR/MR, commit and push with a PR/MR, or keep it for now. Do not open a duplicate delivery questionnaire. Follow its pending/delegated/native result and retry the same call until a real decision is recorded. Cancellation and feedback preserve the closed worktree and pending delivery. PR/MR target selection is a second question when the target is not already explicitly supplied; merging is separate and never implied. An explicit Git delivery instruction already present in the user's own message can be passed as `deliveryInstruction` with its exact relevant `userRequestExcerpt`, choice and any explicit baseBranch. It is reported as an agent-reported user instruction, not a native answer; never use memory approval or an agent preference as that instruction. Read-only tasks have no Git delivery form. Perform only the selected and authorized Git action; the tool itself commits, pushes and merges nothing. When the host has to approve a push, follow the Delivery section of `questionnaires.md`; an Engineering Memory form is never the way past a host's denial.
 
-When a pull request has been opened, keep going: record it with `task.review_request` — its link as the provider shows it, and `draft` or `ready` as it was opened — then check whether it merges cleanly, report the result with the link, and if it conflicts, name the files and ask whether to resolve them. Never end the turn on a pull request whose mergeability was never checked, and never resolve a conflict without being told to.
+When the delivery chose a pull request and the branch is pushed to a GitLab, open it with `task.open_review_request` in the task's clone: it opens the merge request from this computer — a GitLab reachable only from the company network included — reuses one the branch already has, and records it in the same call. When it says no GitLab token is saved, call `gitlab.token` and give the user the link it returns: they type their own token on that page, on their own computer. Never open or fill in that page, never ask for the token, and never use a token pasted into the chat — ask the user to revoke it and use the page. For any other provider, or when the tool refuses, open the pull request with the tools you have and record it with `task.review_request` — its link as the provider shows it, and `draft` or `ready` as it was opened. Either way, keep going: check whether it merges cleanly, report the result with the link, and if it conflicts, name the files and ask whether to resolve them. Never end the turn on a pull request whose mergeability was never checked, and never resolve a conflict without being told to. `session.entry` lists as `awaitingReviewRequests` the delivered tasks still waiting for their pull request; mention them in one line.
 
-When the user later says a pull request became ready, was merged or was closed, record that state with `task.review_request` too; it works from any chat, also for a delivery `session.entry` lists. Engineering Memory then moves the task's work item as the project's workflow rules say: to the `pr_opened` target once every pull request of the work item is ready, to the `all_prs_merged` target (READY FOR QA by default) once they are all merged, and to the draft target when one is still a draft and the project names one. It waits while another task of the work item is still open, or closed with a delivery that has no pull request yet. Relay the returned `nextAction` in one line. The record is what was reported: Engineering Memory does not check it with the provider, so never report a merge the user has not confirmed. A merge is final, and a delivery keeps the first pull request recorded for it. GitHub pull request and GitLab merge request links are recorded; for another provider, move the work item with `work_item.update`.
+When the user later says a pull request became ready, was merged or was closed, record that state with `task.review_request` too; it works from any chat, also for a delivery `session.entry` lists. Engineering Memory then moves the task's work item as the project's workflow rules say: to the `pr_opened` target once every pull request of the work item is ready, to the `all_prs_merged` target (READY FOR QA by default) once they are all merged, and to the draft target when one is still a draft and the project names one. It waits while another task of the work item is still open, or closed with a delivery that has no pull request yet. Relay the returned `nextAction` in one line. A record is what was reported, unless a member's computer read it from GitLab: where someone has saved a GitLab token, the bridge reads the project's merge requests in the background when a chat opens or work items are listed, and records a merge, a close or a draft turning ready by itself, also for a merge request someone opened by hand. Never report a merge the user has not confirmed. A merge is final, and a delivery keeps the first pull request recorded for it. GitHub pull request and GitLab merge request links are recorded; for another provider, move the work item with `work_item.update`.
+
+## Code review
+
+A project can review code before a pull request is ready: `project.review_policy` reads its setting — none, optional or required — and, only when the user asks to change it, `change: true` asks them in one native form; only an owner or maintainer can change it. Under optional the delivery question offers a pull request reviewed first, which opens as a draft, and one without review; under required only the reviewed one. A user's own instruction for a ready pull request under required becomes the reviewed one, and the tool says so; relay it. When the tool says the setting changed while the question was open, tell the user and call it again.
+
+After a reviewed pull request is pushed and the worktree released, open it as a draft (`task.open_review_request`, or your own tools and `task.review_request` with `draft`), then call `review.start` in a clone of the project. It fetches the pushed branch without checking anything out and returns the review packet. Give the packet to a fresh subagent that did not write the change; only when your host cannot start one, review it yourself under the same rules. The reviewer reads the change only through the read-only Git commands the packet lists: it never checks out, switches branches, edits, commits, pushes or changes a file. It judges the change against the packet's records (more with `review.rules`) and says whether each earlier finding still holds. Each finding names the file by its path in the repository, the line in the reviewed commit when there is one, the key of the record it breaks when one applies, and what is wrong and why in plain words. Record the result with `review.submit`, an empty list when there are no findings. Describe a problem without the value itself: e-mail addresses, IP addresses and user folders are masked, and a description that still looks like it holds a secret or personal data is refused.
+
+Show the findings to the user and ask whether to fix them. A fix is a write task: `task.branch` with `reviewFixOf` set to the reviewed task's id, then `session.bootstrap` with the same `reviewFixOf`; it continues the pull request's branch, and its delivery offers commit or commit and push onto that branch — never a second pull request. After its push the open findings are marked fixed; ask whether to review again (`review.start`) or end the review (`review.conclude` with passed). A finding the user disagrees with is rejected with `review.reject_finding`, where the user writes the reason in the form; never write it for them. `review.conclude` also skips a review where the setting is not required, and exempts one under required, which only an owner or maintainer can do and only with the reason the user writes. Every one of these asks the user in a native form first.
+
+Once a review has ended, call `review.make_ready`: on GitLab, with the user's own token saved, it removes Draft and records the pull request ready; anywhere else follow its `nextAction` (for example `gh pr ready`) and record the state with `task.review_request`. It also makes ready, when the user asks, a pull request that has no code review. Never mark a draft ready while its review has not ended. `session.entry` lists as `awaitingReviews` the deliveries that wait for code review; mention them in one line and start nothing on your own. When the user asks, `review.queue` and `review.get` read them, and every member except readers can continue any review where it stopped.
 
 ## Code source and memory applicability