engineering-memory 1.11.28 → 1.11.29

package/runtime/dist/src/mcp/review-tools.js

@@ -0,0 +1,369 @@
+import * as z from 'zod/v4';
+import { waitingReview } from '../runtime/merge-request-sync.js';
+import { languageTag } from '../runtime/questionnaire-store.js';
+import { copies, format } from '../runtime/texts.js';
+import { sha256, stableStringify } from '../utilities/hash.js';
+import { answerChoice, answerData, askQuestionnaire } from './questionnaire-tools.js';
+const text = z.string().min(1);
+const option = z.strictObject({ label: text, description: text });
+const policyWording = z.strictObject({
+    message: text,
+    context: text,
+    example: text,
+    current: text,
+    none: option,
+    optional: option,
+    required: option,
+    keep: option,
+});
+const rejectWording = z.strictObject({
+    message: text,
+    context: text,
+    example: text,
+    reasonTitle: text,
+    reject: option,
+    keep: option,
+});
+const managers = ['owner', 'maintainer'];
+const conclusion = z.strictObject({ message: text, context: text });
+const concludeWording = z.strictObject({
+    passed: conclusion,
+    skipped: conclusion,
+    exempted: conclusion,
+    example: text,
+    reasonTitle: text,
+    confirm: option,
+    defer: option,
+});
+const reviewRead = z.object({
+    delivery: z.object({
+        externalTaskId: z.string(),
+        reviewState: z.string().nullish(),
+        reviewPolicy: z.string().optional(),
+    }),
+    rounds: z.array(z.object({ id: z.string(), state: z.string() })),
+    findings: z.array(z.object({
+        id: z.string(),
+        position: z.number().int(),
+        path: z.string(),
+        line: z.number().int().nullish(),
+        description: z.string(),
+        resolution: z.string(),
+    })),
+});
+const form = {
+    repoRoot: z.string().min(1).optional(),
+    language: languageTag.optional(),
+    decisionAttempt: z.number().int().min(1).max(10000).optional(),
+    presentation: z.literal('host_native').optional(),
+};
+export function registerReviewTools(server, service) {
+    server.registerTool('project.review_policy', {
+        description: 'Read whether this project reviews code before a PR/MR is ready: none, optional or required. With change true it asks the user in one native form and records their choice; only an owner or maintainer can change it. The setting applies from then on: work already delivered keeps its review state. On GitHub the setting is recorded, but GitHub does not enforce it.',
+        inputSchema: z.strictObject({
+            projectId: z.string().uuid(),
+            change: z.boolean().optional(),
+            ...form,
+        }),
+    }, async (input, context) => {
+        const found = await service.projectReviewPolicy({ projectId: input.projectId });
+        if (!found.ok || !input.change)
+            return output(found);
+        const project = found.data;
+        if (project.role && !managers.includes(project.role))
+            return refusal(`Only a project owner or maintainer can change the code review setting of ${project.name}; it is ${project.reviewPolicy}. project.member_list shows who can.`, 'project.member_list');
+        const questionnaireId = 'review-policy-' +
+            sha256(stableStringify({
+                projectId: input.projectId,
+                lockVersion: project.lockVersion,
+                reviewPolicy: project.reviewPolicy,
+                decisionAttempt: input.decisionAttempt ?? 0,
+            }));
+        const definitions = copies(policyWording, 'reviewPolicy', await service.language(input.language)).map(({ language, copy }) => ({
+            questionnaireId,
+            language,
+            impact: 'critical',
+            message: copy.message,
+            context: copy.context + '\n' + copy.current + ': ' + copy[project.reviewPolicy].label,
+            example: copy.example,
+            options: ['none', 'optional', 'required', 'keep'].map((id) => ({
+                id,
+                ...copy[id],
+            })),
+        }));
+        const asked = await askQuestionnaire(server, service, { ...definitions[0], repoRoot: input.repoRoot, presentation: input.presentation }, context, definitions);
+        const choice = answerChoice(asked);
+        if (!choice)
+            return asked;
+        if (choice === 'keep' || choice === project.reviewPolicy)
+            return output({
+                ok: true,
+                data: {
+                    reviewPolicy: project.reviewPolicy,
+                    changed: false,
+                    nextAction: 'Nothing was changed.',
+                },
+            });
+        const updated = await service.projectUpdate({
+            projectId: input.projectId,
+            data: { expectedVersion: project.lockVersion, reviewPolicy: choice },
+        });
+        if (!updated.ok)
+            return output(updated);
+        return output({
+            ok: true,
+            data: {
+                project: updated.data ?? null,
+                changed: true,
+                nextAction: `The code review setting of ${project.name} is now ${choice}. Tell the user; work already delivered keeps its review state.`,
+            },
+        });
+    });
+    server.registerTool('review.queue', {
+        description: 'List the deliveries of this project that wait for code review, oldest first: reviews not started or not finished, and reviews that ended while their PR/MR is still a draft. Each shows its open round and how many findings are open. Page with offset and limit (defaults 0 and 20, at most 100).',
+        inputSchema: z.strictObject({
+            projectId: z.string().uuid(),
+            offset: z.number().int().min(0).optional(),
+            limit: z.number().int().min(1).max(100).optional(),
+        }),
+    }, async (input) => output(await service.reviewQueue(input)));
+    server.registerTool('review.get', {
+        description: "Read the code review of a delivered task: its state, the project's setting, its rounds (newest first) and the findings of the latest submitted round with how each was resolved.",
+        inputSchema: z.strictObject({ projectId: z.string().uuid(), taskId: z.string().uuid() }),
+    }, async (input) => output(await service.reviewGet(input)));
+    server.registerTool('review.start', {
+        description: "Start the next code review round of a delivered task, or return the round already open at the same commit, from a clone of the task's project on this computer. It fetches the pushed branch and its target from origin without checking anything out and returns the review packet: the commits to compare, the changed files, the records that governed the change, earlier findings and the read-only Git commands the reviewer may use. Pass targetBranch only when the delivery names no target branch.",
+        inputSchema: z.strictObject({
+            projectId: z.string().uuid(),
+            taskId: z.string().uuid(),
+            repoRoot: z.string().min(1).optional(),
+            targetBranch: z.string().trim().min(1).max(240).optional(),
+        }),
+    }, async (input) => output(await service.reviewStart(input)));
+    server.registerTool('review.rules', {
+        description: 'Read the records a review round judges the change against, with their content, in pages (defaults offset 0 and limit 5, at most 20). Records the reader cannot open are counted, not shown.',
+        inputSchema: z.strictObject({
+            projectId: z.string().uuid(),
+            roundId: z.string().uuid(),
+            offset: z.number().int().min(0).optional(),
+            limit: z.number().int().min(1).max(20).optional(),
+        }),
+    }, async (input) => output(await service.reviewRules(input)));
+    server.registerTool('review.submit', {
+        description: 'Record the result of a review round: its findings, or an empty list when there are none. E-mail addresses, IP addresses and user folders in descriptions are masked first; a description that still holds a secret or personal data is refused so it can be rephrased. Sending the same result again changes nothing.',
+        inputSchema: z.strictObject({
+            projectId: z.string().uuid(),
+            roundId: z.string().uuid(),
+            findings: z
+                .array(z.strictObject({
+                path: z.string().trim().min(1).max(500),
+                line: z.number().int().min(1).optional(),
+                ruleKey: z.string().trim().min(1).max(160).optional(),
+                description: z.string().trim().min(1).max(4000),
+            }))
+                .max(100),
+        }),
+    }, async (input) => {
+        const result = await service.reviewSubmit(input);
+        if (!result.ok)
+            return output(result);
+        const data = result.data;
+        const task = data.review.delivery.externalTaskId;
+        const decided = data.review.rounds.some((round) => round.id === input.roundId && round.state === 'submitted');
+        return output({
+            ok: true,
+            data: {
+                ...data,
+                nextAction: [
+                    data.masked.length
+                        ? `These were masked in the descriptions before they were stored: ${data.masked.join(', ')}.`
+                        : '',
+                    !decided
+                        ? `The result is stored with this round, but the round no longer decides the review of ${task}: a newer round or a conclusion replaced it. Read the review with review.get and show the user where it stands.`
+                        : input.findings.length
+                            ? `Show the user the findings of ${task} and ask whether to fix them. A fix is a write task started with task.branch with reviewFixOf set to the reviewed taskId; a finding the user disagrees with is rejected with a reason through review.reject_finding.`
+                            : `No findings: the review of ${task} passed. Tell the user and call review.make_ready to make its PR/MR ready.`,
+                ]
+                    .filter(Boolean)
+                    .join(' '),
+            },
+        });
+    });
+    server.registerTool('review.reject_finding', {
+        description: 'Reject an open finding of a code review with a written reason, after asking the user in a native form where they write the reason. When it was the last open finding, the review passes.',
+        inputSchema: z.strictObject({
+            projectId: z.string().uuid(),
+            taskId: z.string().uuid(),
+            findingId: z.string().uuid(),
+            ...form,
+        }),
+    }, async (input, context) => {
+        const read = await service.reviewGet(input);
+        if (!read.ok)
+            return output(read);
+        const review = reviewRead.parse(read.data);
+        const finding = review.findings.find((candidate) => candidate.id === input.findingId);
+        if (!finding || finding.resolution !== 'open')
+            return refusal(finding
+                ? `Finding ${finding.position} is already ${finding.resolution}.`
+                : 'This finding is not among the findings of the latest round of this review. Read it again with review.get.', 'review.get');
+        const questionnaireId = 'review-reject-' +
+            sha256(stableStringify({
+                findingId: input.findingId,
+                decisionAttempt: input.decisionAttempt ?? 0,
+            }));
+        const where = finding.path + (finding.line ? ':' + finding.line : '');
+        const definitions = copies(rejectWording, 'reviewReject', await service.language(input.language)).map(({ language, copy }) => ({
+            questionnaireId,
+            language,
+            impact: 'critical',
+            message: copy.message,
+            context: copy.context +
+                '\n' +
+                `${review.delivery.externalTaskId} #${finding.position}, ${where}: ` +
+                (finding.description.length > 500
+                    ? finding.description.slice(0, 500) + '…'
+                    : finding.description),
+            example: copy.example,
+            options: [
+                { id: 'reject', ...copy.reject },
+                { id: 'keep', ...copy.keep },
+            ],
+            textField: { title: copy.reasonTitle, maxLength: 2000, requiredForChoice: 'reject' },
+        }));
+        const asked = await askQuestionnaire(server, service, { ...definitions[0], repoRoot: input.repoRoot, presentation: input.presentation }, context, definitions);
+        const answer = answerData(asked);
+        if (!answer?.choice)
+            return asked;
+        if (answer.choice !== 'reject' || !answer.text)
+            return output({
+                ok: true,
+                data: { rejected: false, nextAction: 'Nothing was recorded; the finding stays open.' },
+            });
+        const rejected = await service.reviewRejectFinding({
+            projectId: input.projectId,
+            findingId: input.findingId,
+            reason: answer.text,
+        });
+        if (!rejected.ok)
+            return output(rejected);
+        const after = reviewRead.parse(rejected.data);
+        const open = after.findings.filter((candidate) => candidate.resolution === 'open').length;
+        return output({
+            ok: true,
+            data: {
+                review: rejected.data ?? null,
+                rejected: true,
+                nextAction: after.delivery.reviewState === 'passed'
+                    ? `No finding is open any more, so the review of ${after.delivery.externalTaskId} passed. Tell the user and call review.make_ready to make its PR/MR ready.`
+                    : `The finding is rejected with the user's reason; ${open} finding${open === 1 ? ' is' : 's are'} still open.`,
+            },
+        });
+    });
+    server.registerTool('review.conclude', {
+        description: 'End a code review after asking the user in a native form. passed ends a review whose fix was pushed without another round (no finding may be open); skipped ends it where review is not required; exempted ends a required review and needs an owner or maintainer and a written reason. Every member except readers may pass or skip. Nothing changes in Git.',
+        inputSchema: z.strictObject({
+            projectId: z.string().uuid(),
+            taskId: z.string().uuid(),
+            outcome: z.enum(['passed', 'skipped', 'exempted']),
+            ...form,
+        }),
+    }, async (input, context) => {
+        const read = await service.reviewGet(input);
+        if (!read.ok)
+            return output(read);
+        const review = reviewRead.parse(read.data);
+        const task = review.delivery.externalTaskId;
+        const state = review.delivery.reviewState ?? null;
+        if (state === input.outcome)
+            return output({
+                ok: true,
+                data: {
+                    concluded: true,
+                    nextAction: `The review of ${task} already ended as ${state}. Call review.make_ready to make its PR/MR ready.`,
+                },
+            });
+        if (!waitingReview.includes(state ?? ''))
+            return refusal(`The review of ${task} is ${state ?? 'not tracked'}, so there is nothing to end. review.get shows where it stands.`, 'review.get');
+        if (input.outcome === 'passed' &&
+            (state !== 'pending' ||
+                !review.rounds.some((round) => round.state === 'submitted') ||
+                review.findings.some((finding) => finding.resolution === 'open')))
+            return refusal(`The review of ${task} is ${state}: it passes without another round only after a round was submitted, a fix was pushed and no finding is open. Start a round with review.start, or ask the user whether to skip or exempt it.`, 'review.start');
+        if (input.outcome === 'skipped' && review.delivery.reviewPolicy === 'required')
+            return refusal(`This project requires code review, so the review of ${task} cannot be skipped; a project owner or maintainer can exempt it with a written reason (outcome exempted).`, 'review.conclude');
+        if (input.outcome === 'exempted') {
+            const project = await service.projectReviewPolicy({ projectId: input.projectId });
+            const role = project.ok ? project.data.role : undefined;
+            if (role && !managers.includes(role))
+                return refusal(`Only a project owner or maintainer can exempt the review of ${task}. project.member_list shows who can.`, 'project.member_list');
+        }
+        const questionnaireId = 'review-conclude-' +
+            sha256(stableStringify({
+                taskId: input.taskId,
+                outcome: input.outcome,
+                reviewState: review.delivery.reviewState ?? null,
+                decisionAttempt: input.decisionAttempt ?? 0,
+            }));
+        const definitions = copies(concludeWording, 'reviewConclude', await service.language(input.language)).map(({ language, copy }) => ({
+            questionnaireId,
+            language,
+            impact: 'critical',
+            message: format(copy[input.outcome].message, language, { task }),
+            context: copy[input.outcome].context,
+            example: copy.example,
+            options: [
+                { id: 'confirm', ...copy.confirm },
+                { id: 'defer', ...copy.defer },
+            ],
+            ...(input.outcome === 'exempted'
+                ? {
+                    textField: {
+                        title: copy.reasonTitle,
+                        maxLength: 2000,
+                        requiredForChoice: 'confirm',
+                    },
+                }
+                : {}),
+        }));
+        const asked = await askQuestionnaire(server, service, { ...definitions[0], repoRoot: input.repoRoot, presentation: input.presentation }, context, definitions);
+        const answer = answerData(asked);
+        if (!answer?.choice)
+            return asked;
+        if (answer.choice !== 'confirm')
+            return output({
+                ok: true,
+                data: { concluded: false, nextAction: 'Nothing was recorded; the review stays open.' },
+            });
+        const concluded = await service.reviewConclude({
+            projectId: input.projectId,
+            taskId: input.taskId,
+            outcome: input.outcome,
+            ...(answer.text ? { reason: answer.text } : {}),
+        });
+        if (!concluded.ok)
+            return output(concluded);
+        return output({
+            ok: true,
+            data: {
+                review: concluded.data ?? null,
+                concluded: true,
+                nextAction: `The review of ${task} ended as ${input.outcome}. Call review.make_ready to make its PR/MR ready.`,
+            },
+        });
+    });
+    server.registerTool('review.make_ready', {
+        description: "Make the PR/MR of a delivered task ready for the team once its code review ended, or, when the user asks, one that has no code review; while a review runs it refuses. On GitLab with the user's own token saved on this computer, it removes Draft from the merge request and records it; anywhere else it says exactly what to do, since the draft is marked ready with the provider's own tools or by the user.",
+        inputSchema: z.strictObject({ projectId: z.string().uuid(), taskId: z.string().uuid() }),
+    }, async (input) => output(await service.reviewMakeReady(input)));
+}
+function output(result) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(result) }],
+        isError: !result.ok,
+    };
+}
+function refusal(message, recovery) {
+    return output({ ok: false, error: { kind: 'review', message, recovery, retryable: false } });
+}
+//# sourceMappingURL=review-tools.js.map

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

@@ -81,6 +81,15 @@ export const toolAnnotations = {
     'task.review_request': repeatableWrite,
     'task.open_review_request': { ...outward, idempotentHint: true },
     'gitlab.token': outward,
+    'project.review_policy': write,
+    'review.queue': read,
+    'review.get': read,
+    'review.start': { ...outward, idempotentHint: true },
+    'review.rules': read,
+    'review.submit': repeatableWrite,
+    'review.reject_finding': write,
+    'review.conclude': write,
+    'review.make_ready': { ...outward, idempotentHint: true },
     'task.abandon': destructive,
     'task.branch': outward, // fetches the chosen base from the Git remote
     'architecture.plan': read,

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

@@ -1,4 +1,5 @@
 import { registerDeliveryTools } from './delivery-tools.js';
+import { registerReviewTools } from './review-tools.js';
 import { registerLiveStatusTools } from './live-status-tools.js';
 import { registerStatusMeaningTools } from './status-meaning-tools.js';
 import { registerStatusRemapTools } from './status-remap-tools.js';
@@ -120,6 +121,15 @@ export const engineeringMemoryToolNames = [
     'task.review_request',
     'task.open_review_request',
     'gitlab.token',
+    'project.review_policy',
+    'review.queue',
+    'review.get',
+    'review.start',
+    'review.rules',
+    'review.submit',
+    'review.reject_finding',
+    'review.conclude',
+    'review.make_ready',
     'task.abandon',
     'task.branch',
     'architecture.plan',
@@ -376,6 +386,11 @@ export function registerEngineeringMemoryTools(server, service) {
                 .regex(/^[^\r\n]+$/, 'workItemKey must be a single line of at most 120 characters.')
                 .optional(),
             workItemId: z.string().uuid().optional(),
+            reviewFixOf: z
+                .string()
+                .uuid()
+                .optional()
+                .describe("The reviewed task's taskId when this write task fixes the findings of its code review, as given to task.branch. The task belongs to that task's work item and delivers onto its pull request branch."),
             mode: z.enum(['write', 'read_only', 'scaffold']).optional(),
             linkedSources: z
                 .array(z.object({
@@ -759,6 +774,7 @@ export function registerEngineeringMemoryTools(server, service) {
         return toolResult(await service.taskVerify(request));
     });
     registerDeliveryTools(server, service);
+    registerReviewTools(server, service);
     server.registerTool('task.abandon', {
         description: "Abandon a task the user has said they are giving up on, so it stops holding its proposals and its local pointer. It has no effect on any other task: nobody else's work waits on this, and nothing already verified or closed is undone. Ask the user first; never abandon a task on your own judgement.",
         inputSchema: z.object({

package/runtime/dist/src/mcp/worktree-tools.js

@@ -287,7 +287,7 @@ export function registerWorktreeTools(server, service) {
         inputSchema: z.strictObject(policy),
     }, async (input) => output(await service.worktreePolicy(json(input))));
     server.registerTool('task.branch', {
-        description: 'Start a write task by selecting its decision mode in one short native form, then resolve two short questions for the starting branch (unless base is given) and the folder. A unique branch name is generated automatically unless name is supplied. Pass workItemId (and workItemProjectId when the item lives in a linked project) for work on a work item: the branch question then also offers continuing the branch of its plan or of its earlier rounds, fetched from origin when this clone lacks it, and a planned item that has no branch yet gets its plan branch as the new name. Folder options: a separate managed worktree, this folder as a new branch when it is clean (moving out an unfinished task that holds it, named in the option), this folder on its current branch, or not now. Nothing is created until a valid native or mode-delegated start answer is recorded; the next call with the same arguments allocates. A remote base is fetched and its exact commit pinned. Retry/resume preserves the allocation. Not now returns status deferred with the exact reconsider call; retries keep the same decisionAttempt. Use the returned repoRoot for ALL commands. A read-only task allocates only when transitioning to write.',
+        description: "Start a write task by selecting its decision mode in one short native form, then resolve two short questions for the starting branch (unless base is given) and the folder. A unique branch name is generated automatically unless name is supplied. Pass workItemId (and workItemProjectId when the item lives in a linked project) for work on a work item: the branch question then also offers continuing the branch of its plan or of its earlier rounds, fetched from origin when this clone lacks it, and a planned item that has no branch yet gets its plan branch as the new name. To fix the findings of a code review, pass reviewFixOf with the reviewed task's taskId: the task continues on the branch of its pull request, and session.bootstrap then takes the same reviewFixOf. Folder options: a separate managed worktree, this folder as a new branch when it is clean (moving out an unfinished task that holds it, named in the option), this folder on its current branch, or not now. Nothing is created until a valid native or mode-delegated start answer is recorded; the next call with the same arguments allocates. A remote base is fetched and its exact commit pinned. Retry/resume preserves the allocation. Not now returns status deferred with the exact reconsider call; retries keep the same decisionAttempt. Use the returned repoRoot for ALL commands. A read-only task allocates only when transitioning to write.",
         inputSchema: z.strictObject({
             repoRoot: repo,
             externalTaskId: z.string().min(2).max(160),
@@ -297,6 +297,7 @@ export function registerWorktreeTools(server, service) {
             keepCurrent: z.boolean().optional(),
             workItemId: z.string().uuid().optional(),
             workItemProjectId: z.string().uuid().optional(),
+            reviewFixOf: z.string().uuid().optional(),
             language: languageTag.optional(),
             presentation,
         }),
@@ -324,6 +325,7 @@ export function registerWorktreeTools(server, service) {
                 },
             });
         const plan = flight.planBranch;
+        const fix = flight.reviewFix;
         const { previous, ...definition } = taskStartDefinition({
             ...input,
             ...flight,
@@ -331,6 +333,14 @@ export function registerWorktreeTools(server, service) {
             ...(plan && flight.continueBranches.includes(plan)
                 ? { base: { kind: 'existing', branch: plan } }
                 : {}),
+            ...(fix
+                ? {
+                    name: fix.branch,
+                    base: { kind: 'existing', branch: fix.branch },
+                    keepCurrent: false,
+                    reviewedTask: fix.externalTaskId,
+                }
+                : {}),
             language: told ?? 'en',
         });
         const owner = {
@@ -344,6 +354,7 @@ export function registerWorktreeTools(server, service) {
                 keepCurrent: input.keepCurrent,
                 workItemId: input.workItemId,
                 workItemProjectId: input.workItemProjectId,
+                reviewFixOf: input.reviewFixOf,
             }),
         };
         const form = await askQuestionnaire(server, service, { ...definition, repoRoot: input.repoRoot, presentation: input.presentation }, context, previous, owner);

package/runtime/dist/src/providers/gitlab.js

@@ -146,6 +146,7 @@ export const mergeRequestSchema = z.object({
     draft: z.boolean().optional(),
     work_in_progress: z.boolean().optional(),
     sha: z.string().nullish(),
+    title: z.string().optional(),
     source_branch: z.string(),
     target_branch: z.string(),
     project_id: z.number().optional(),
@@ -226,6 +227,9 @@ export class GitLabClient {
             ...(request.description ? { description: request.description } : {}),
         }));
     }
+    async retitleMergeRequest(address, token, project, number, title) {
+        return this.shape(address, mergeRequestSchema, await this.call(address, token, 'PUT', `/projects/${encodeURIComponent(project)}/merge_requests/${number}`, { title }));
+    }
     async found(read) {
         try {
             return await read();

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

@@ -52,6 +52,13 @@ export const backendRecoveryOperationNames = [
     'task.resolve_pending_delivery',
     'task.delivery',
     'task.review_request',
+    'project.review_policy',
+    'review.queue',
+    'review.get',
+    'review.start',
+    'review.submit',
+    'review.reject_finding',
+    'review.conclude',
 ];
 const backendRecoveryOperations = new Set(backendRecoveryOperationNames);
 const browserSigninRecovery = 'auth.signin_browser';