engineering-memory 1.11.28 → 1.11.30

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

@@ -2,7 +2,9 @@ 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 { backendRejectsField } from './api-client.js';
 import { BridgeRecoveryError } from './recovery-error.js';
+import { commentReviewSchema, dueComment, markComment } from './review-comment.js';
 export const reviewDeliverySchema = z.object({
     taskId: z.string(),
     externalTaskId: z.string().nullish(),
@@ -13,6 +15,11 @@ export const reviewDeliverySchema = z.object({
     pushed: z.boolean().nullish(),
     branch: z.string().nullish(),
     workItemKey: z.string().nullish(),
+    reviewState: z.string().nullish(),
+    reviewCommit: z.string().nullish(),
+    reviewCommentPostedAt: z.string().nullish(),
+    providerJob: z.string().nullish(),
+    providerFailedAt: z.string().nullish(),
     reviewRequest: z
         .object({
         provider: z.string(),
@@ -22,10 +29,19 @@ export const reviewDeliverySchema = z.object({
         url: z.string(),
         state: z.string(),
         source: z.string().optional(),
+        targetBranch: z.string().nullish(),
     })
         .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' &&
@@ -45,13 +61,16 @@ export class MergeRequests {
     tokens;
     gitlab;
     git;
+    language;
     passes = new Map();
     running = new Set();
-    constructor(client, tokens, gitlab, git) {
+    readingRefused = false;
+    constructor(client, tokens, gitlab, git, language) {
         this.client = client;
         this.tokens = tokens;
         this.gitlab = gitlab;
         this.git = git;
+        this.language = language;
     }
     async open(input) {
         const delivery = reviewDeliverySchema.parse((await this.client.request(endpoints.taskDelivery(input.projectId, input.taskId)))
@@ -67,7 +86,7 @@ export class MergeRequests {
         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 ?? delivery.choice === 'commit_push_draft_pr';
+        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');
@@ -125,6 +144,53 @@ export class MergeRequests {
             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 });
+        }
+    }
+    async comment(projectId, taskId, request, comment) {
+        const link = await this.tokens.forLink(request.host, request.repository);
+        const token = link ? await this.tokens.token(link.address) : null;
+        if (!link || !token)
+            return { posted: false };
+        try {
+            await this.post(projectId, taskId, { address: link.address, token, project: link.project, number: request.number }, comment);
+            return { posted: true };
+        }
+        catch (error) {
+            if (!(error instanceof GitLabError))
+                throw error;
+            return { posted: false, failure: error.failure };
+        }
+    }
     schedule(projectId, repoRoot, deliveries) {
         const now = Date.now();
         const last = this.passes.get(projectId);
@@ -151,8 +217,17 @@ export class MergeRequests {
         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)))
+                if (!found)
+                    continue;
+                let job = delivery.providerJob ?? null;
+                if (this.changed(delivery, found)) {
+                    const answer = await this.report(projectId, delivery.taskId, found);
+                    if (!answer)
+                        continue;
                     reported++;
+                    job = answer.providerJob;
+                }
+                await this.provide(projectId, delivery, found, job, pass).catch(() => undefined);
             }
         };
         await Promise.all([worker(), worker(), worker(), worker()]);
@@ -168,10 +243,9 @@ export class MergeRequests {
             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;
+            return request
+                ? { url: known.url, request, address: link.address, token, project: link.project }
+                : null;
         }
         if (!repoRoot || !delivery.branch)
             return null;
@@ -201,7 +275,78 @@ export class MergeRequests {
             .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;
+        return chosen ? { url: chosen.web_url, request: chosen, address, token, project: path } : null;
+    }
+    changed(delivery, found) {
+        const known = delivery.reviewRequest;
+        const head = found.request.sha;
+        return (!known ||
+            reviewState(found.request) !== known.state ||
+            known.source !== 'machine' ||
+            (known.targetBranch !== undefined && found.request.target_branch !== known.targetBranch) ||
+            (!this.readingRefused &&
+                delivery.reviewState === 'passed' &&
+                !!head &&
+                !!delivery.reviewCommit &&
+                head !== delivery.reviewCommit));
+    }
+    async provide(projectId, delivery, found, job, pass) {
+        const state = reviewState(found.request);
+        const failedAt = job === (delivery.providerJob ?? null) ? delivery.providerFailedAt : null;
+        if ((state !== 'draft' && state !== 'ready') ||
+            (failedAt && Date.now() - Date.parse(failedAt) < 30 * 60 * 1000) ||
+            pass.failed.has(found.address) ||
+            pass.calls < 3)
+            return;
+        if (delivery.reviewState === 'findings_open' ||
+            (concludedReview.includes(delivery.reviewState ?? '') &&
+                delivery.reviewCommentPostedAt === null)) {
+            const review = commentReviewSchema.safeParse((await this.client
+                .request(endpoints.review(projectId, delivery.taskId))
+                .catch(() => null))?.data);
+            const comment = review.success
+                ? dueComment(review.data, (await this.language()) ?? 'en')
+                : null;
+            if (comment)
+                await this.post(projectId, delivery.taskId, { ...found, number: found.request.iid }, comment, pass).catch(() => undefined);
+        }
+        const due = (job === 'make_ready' && state === 'draft') || (job === 'make_draft' && state === 'ready')
+            ? job
+            : null;
+        if (!due)
+            return;
+        try {
+            pass.calls--;
+            const title = found.request.title;
+            if (title === undefined)
+                throw new GitLabError('unexpected_answer', found.address, null, null);
+            const after = await this.gitlab.retitleMergeRequest(found.address, found.token, found.project, found.request.iid, due === 'make_ready'
+                ? title.replace(draftPrefix, '') || defaultTitle(found.request.source_branch, null)
+                : `Draft: ${title}`.slice(0, 255));
+            await this.report(projectId, delivery.taskId, { ...found, request: after });
+        }
+        catch (error) {
+            if (!(error instanceof GitLabError))
+                return;
+            pass.failed.add(found.address);
+            await this.client
+                .request(endpoints.reviewProviderFailure(projectId, delivery.taskId), {
+                method: 'POST',
+                body: { job: due, failure: error.failure },
+            })
+                .catch(() => undefined);
+        }
+    }
+    async post(projectId, taskId, target, comment, pass) {
+        if (pass)
+            pass.calls--;
+        const notes = await this.gitlab.notes(target.address, target.token, target.project, target.number);
+        if (!notes.some((note) => note.body.includes(comment.marker))) {
+            if (pass)
+                pass.calls--;
+            await this.gitlab.createNote(target.address, target.token, target.project, target.number, comment.body);
+        }
+        await markComment(this.client, projectId, taskId, comment);
     }
     async call(pass, address, request) {
         if (pass.failed.has(address) || pass.calls <= 0)
@@ -218,16 +363,28 @@ export class MergeRequests {
         }
     }
     async report(projectId, taskId, found) {
+        const body = { url: found.url, state: reviewState(found.request), source: 'machine' };
+        const reading = {
+            ...(found.request.sha ? { headCommit: found.request.sha } : {}),
+            targetBranch: found.request.target_branch,
+        };
+        const send = () => this.client.request(endpoints.taskReviewRequest(projectId, taskId), {
+            method: 'POST',
+            body: this.readingRefused ? body : { ...body, ...reading },
+            idempotencyKey: randomUUID(),
+        });
         try {
-            await this.client.request(endpoints.taskReviewRequest(projectId, taskId), {
-                method: 'POST',
-                body: { url: found.url, state: found.state, source: 'machine' },
-                idempotencyKey: randomUUID(),
+            const response = await send().catch(async (error) => {
+                if (this.readingRefused || !backendRejectsField(error, ['headCommit', 'targetBranch']))
+                    throw error;
+                this.readingRefused = true;
+                return send();
             });
-            return true;
+            const answer = z.object({ providerJob: z.string().nullish() }).safeParse(response.data);
+            return { providerJob: answer.success ? (answer.data.providerJob ?? null) : null };
         }
         catch {
-            return false;
+            return null;
         }
     }
 }

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

@@ -0,0 +1,135 @@
+import * as z from 'zod/v4';
+import { endpoints } from '../config.js';
+import { concludedReview } from './merge-request-sync.js';
+import { copies, format } from './texts.js';
+const text = z.string().min(1);
+const commentWording = z.strictObject({
+    round: text,
+    passed: text,
+    skipped: text,
+    exempted: text,
+    findingsOf: text,
+    rule: text,
+    open: text,
+    fixed: text,
+    rejected: text,
+});
+export const commentReviewSchema = z.object({
+    delivery: z.object({
+        id: z.string(),
+        taskId: z.string(),
+        externalTaskId: z.string(),
+        workItemKey: z.string().nullish(),
+        reviewState: z.string().nullish(),
+        reviewChangedAt: z.string().nullish(),
+        reviewExemptionReason: z.string().nullish(),
+        reviewCommentPostedAt: 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(),
+        })
+            .nullish(),
+    }),
+    rounds: z.array(z.object({
+        id: z.string(),
+        number: z.number().int(),
+        state: z.string(),
+        commentPostedAt: z.string().nullish(),
+    })),
+    totalRounds: z.number().int().optional(),
+    findings: z.array(z.object({
+        position: z.number().int(),
+        path: z.string(),
+        line: z.number().int().nullish(),
+        ruleKey: z.string().nullish(),
+        description: z.string(),
+        resolution: z.string(),
+        rejectionReason: z.string().nullish(),
+        fixedCommit: z.string().nullish(),
+    })),
+});
+export function dueComment(review, language) {
+    const { delivery, findings } = review;
+    const { copy, language: shown } = copies(commentWording, 'reviewComment', language)[0];
+    const task = delivery.workItemKey ?? delivery.externalTaskId;
+    const where = (finding) => '`' + (finding.path + (finding.line ? `:${finding.line}` : '')).replace(/`/g, '') + '`';
+    const latest = review.rounds.find((round) => round.state === 'submitted');
+    if (delivery.reviewState === 'findings_open' &&
+        latest?.commentPostedAt === null &&
+        findings.length) {
+        const marker = `<!-- engineering-memory review-round ${latest.id} -->`;
+        const lines = findings.map((finding) => `${finding.position}. ${where(finding)}` +
+            (finding.ruleKey
+                ? ` (${format(copy.rule, shown, { rule: oneLine(finding.ruleKey) })})`
+                : '') +
+            `: ${oneLine(finding.description)}`);
+        return {
+            kind: 'round',
+            roundId: latest.id,
+            marker,
+            body: [
+                marker,
+                `**${format(copy.round, shown, { task, round: latest.number, count: findings.length })}**`,
+                '',
+                ...lines,
+            ].join('\n'),
+        };
+    }
+    const outcome = delivery.reviewState;
+    if (!outcome ||
+        !concludedReview.includes(outcome) ||
+        !delivery.reviewChangedAt ||
+        delivery.reviewCommentPostedAt !== null ||
+        !['draft', 'ready'].includes(delivery.reviewRequest?.state ?? ''))
+        return null;
+    const marker = `<!-- engineering-memory review-conclusion ${delivery.id} ${delivery.reviewChangedAt} -->`;
+    const title = outcome === 'passed'
+        ? format(copy.passed, shown, { task, rounds: review.totalRounds ?? review.rounds.length })
+        : outcome === 'skipped'
+            ? format(copy.skipped, shown, { task })
+            : format(copy.exempted, shown, {
+                task,
+                reason: oneLine(delivery.reviewExemptionReason ?? ''),
+            });
+    const status = (finding) => finding.resolution === 'fixed'
+        ? format(copy.fixed, shown, { commit: (finding.fixedCommit ?? '').slice(0, 12) })
+        : finding.resolution === 'rejected'
+            ? format(copy.rejected, shown, { reason: oneLine(finding.rejectionReason ?? '') })
+            : copy.open;
+    return {
+        kind: 'conclusion',
+        concludedAt: delivery.reviewChangedAt,
+        marker,
+        body: [
+            marker,
+            `**${title}**`,
+            ...(findings.length && latest
+                ? [
+                    '',
+                    format(copy.findingsOf, shown, { round: latest.number }),
+                    ...findings.map((finding) => `${finding.position}. ${where(finding)}: ${status(finding)}`),
+                ]
+                : []),
+        ].join('\n'),
+    };
+}
+export async function markComment(client, projectId, taskId, comment) {
+    await client
+        .request(comment.kind === 'round'
+        ? endpoints.reviewRoundComment(projectId, comment.roundId)
+        : endpoints.reviewComment(projectId, taskId), {
+        method: 'POST',
+        ...(comment.kind === 'conclusion' ? { body: { concludedAt: comment.concludedAt } } : {}),
+    })
+        .catch(() => undefined);
+}
+function oneLine(value) {
+    const line = value.replace(/\s+/g, ' ').trim();
+    return (line.length > 1500 ? `${line.slice(0, 1499)}…` : line).replace(/@/g, '@​');
+}
+//# sourceMappingURL=review-comment.js.map

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

@@ -300,6 +300,18 @@ When the delivery chose a pull request and the branch is pushed to a GitLab, ope
 
 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; from the second round on it starts from `sinceLastRound`, what changed since the previous round. 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.
+
+The review is written on the pull request as comments: the findings of each round and the conclusion. On GitLab the bridge writes them with the user's saved token; when a result of `review.submit`, `review.reject_finding`, `review.conclude` or `review.make_ready` carries `comment.body`, post that body unchanged as a comment with your own tools (on GitHub, `gh pr comment` with the body in a file) — it is recorded as handed over and not handed over again. When you record a pull request with `task.review_request`, pass `headCommit` and `targetBranch` when you can read them (on GitHub, `gh pr view --json headRefOid,baseRefName`): a review that had passed waits again when its pull request gets a new commit or a new target branch, and the answer says so; tell the user in one line, and do not pass it again without a round — `review.start` runs the next one, and skipping or exempting still asks the user. An `awaitingReviews` entry shows `reopened`, `readyBeforeReview` and `pullRequestChange`: a make-ready or make-draft that a member computer with a GitLab token does in the background, with its last failure. Mention a failure in one line; on GitHub, when the answer asks for a draft again, make it a draft with your own tools (`gh pr ready --undo`) and record it with `task.review_request`.
+
 ## Code source and memory applicability
 
 The bridge sends the checkout's committed Git commit and tree at bootstrap. Task and session