engineering-memory 1.11.28 → 1.11.30

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

@@ -7,6 +7,7 @@ const option = z.strictObject({
     label: z.string().trim().min(1).max(100),
     description: z.string().trim().min(1).max(240),
 });
+const reviewLine = z.string().trim().min(1).max(300);
 const copySchema = z.strictObject({
     message: z.string().trim().min(1).max(240),
     context: z.string().trim().min(1).max(500),
@@ -17,12 +18,26 @@ const copySchema = z.strictObject({
     commit_push_draft_pr: option,
     commit_push_pr: option,
     defer: option,
+    commit_push_review_pr: option.optional(),
+    commit_push_pr_unreviewed: option.optional(),
+    reviewRequired: reviewLine.optional(),
+    reviewOptional: reviewLine.optional(),
+    reviewFix: reviewLine.optional(),
     baseMessage: z.string().trim().min(1).max(240),
     baseContext: z.string().trim().min(1).max(500),
     baseTitle: z.string().trim().min(1).max(100),
     baseWrite: option,
     recorded: z.string().trim().min(1).max(100).optional(),
 });
+const deliveryChoices = [
+    'commit',
+    'commit_push',
+    'commit_push_review_pr',
+    'commit_push_draft_pr',
+    'commit_push_pr',
+    'defer',
+];
+const reviewPolicy = z.enum(['none', 'optional', 'required']);
 const closedSchema = z.object({
     closed: z.literal(true),
     taskVersion: z.number().int().positive(),
@@ -47,8 +62,11 @@ const closedSchema = z.object({
         taskId: z.string(),
         lockVersion: z.number().int(),
         choice: z.enum(['commit', 'commit_push', 'commit_push_draft_pr', 'commit_push_pr']).nullish(),
+        reviewState: z.string().nullish(),
     })
         .nullish(),
+    reviewPolicy: reviewPolicy.optional(),
+    reviewFixOf: z.object({ taskId: z.string(), externalTaskId: z.string() }).nullish(),
 });
 const recordWording = z.strictObject({
     message: z.string().trim().min(1).max(240),
@@ -63,7 +81,48 @@ const recordSchema = z.object({
     branch: z.string().nullable(),
     state: z.enum(['unanswered', 'answered', 'delivered', 'cancelled']),
     lockVersion: z.number().int(),
+    reviewPolicy: reviewPolicy.optional(),
+    reviewFixOfDeliveryId: z.string().nullish(),
 });
+function offered(policy, fix) {
+    if (fix)
+        return ['commit', 'commit_push'];
+    if (policy === 'required')
+        return ['commit', 'commit_push', 'commit_push_review_pr'];
+    if (policy === 'optional')
+        return ['commit', 'commit_push', 'commit_push_review_pr', 'commit_push_pr'];
+    return ['commit', 'commit_push', 'commit_push_draft_pr', 'commit_push_pr'];
+}
+function wording(copy, policy, choice) {
+    return choice === 'commit_push_pr' && policy === 'optional'
+        ? copy.commit_push_pr_unreviewed
+        : copy[choice];
+}
+function pullRequest(choice) {
+    return (choice === 'commit_push_review_pr' ||
+        choice === 'commit_push_draft_pr' ||
+        choice === 'commit_push_pr');
+}
+const incompleteCopy = {
+    ok: false,
+    error: {
+        kind: 'delivery',
+        message: "Supply complete delivery copy in the conversation language before closing, including the code review wording this project's question needs (commit_push_review_pr, commit_push_pr_unreviewed, reviewRequired, reviewOptional, reviewFix).",
+        recovery: 'task.close',
+        retryable: false,
+    },
+};
+function settingChanged(tool, now) {
+    return output({
+        ok: false,
+        error: {
+            kind: 'delivery',
+            message: `The project's code review setting changed to ${now} while the delivery question was open, so the answer was not recorded and no Git action was performed. Tell the user, then call ${tool} again: its question follows the new setting.`,
+            recovery: tool,
+            retryable: true,
+        },
+    });
+}
 export function registerDeliveryTools(server, service) {
     registerTaskDelivery(server, service);
     registerTaskReviewRequest(server, service);
@@ -79,13 +138,7 @@ export function registerDeliveryTools(server, service) {
             decisionAttempt: z.number().int().min(1).max(10000).optional(),
             deliveryInstruction: z
                 .strictObject({
-                choice: z.enum([
-                    'commit',
-                    'commit_push',
-                    'commit_push_draft_pr',
-                    'commit_push_pr',
-                    'defer',
-                ]),
+                choice: z.enum(deliveryChoices),
                 userRequestExcerpt: z.string().trim().min(1).max(1200),
                 baseBranch: z.string().trim().min(1).max(240).optional(),
             })
@@ -123,6 +176,8 @@ export function registerDeliveryTools(server, service) {
         const data = parsed.data;
         if (data.deliveryContext.mode === 'read_only')
             return output(closed);
+        const policy = data.reviewPolicy ?? 'none';
+        const fix = data.reviewFixOf ?? null;
         const delivered = data.delivery.alreadyDelivered;
         if (delivered)
             return output({
@@ -130,7 +185,12 @@ export function registerDeliveryTools(server, service) {
                 data: {
                     ...closed.data,
                     deliveryStatus: 'delivered',
-                    nextAction: `Everything this task changed was already committed and pushed by hand: ${delivered.ref.replace(/^refs\/remotes\//, '')} contains ${delivered.commit.slice(0, 12)}. There is nothing left to deliver, so no delivery question is asked, and the delivery is recorded for the project. Call worktree.release in this folder with deliveryOutcome delivered to settle the folder.`,
+                    nextAction: `Everything this task changed was already committed and pushed by hand: ${delivered.ref.replace(/^refs\/remotes\//, '')} contains ${delivered.commit.slice(0, 12)}. There is nothing left to deliver, so no delivery question is asked, and the delivery is recorded for the project. Call worktree.release in this folder with deliveryOutcome delivered to settle the folder.` +
+                        (fix
+                            ? ` This task fixes the review findings of ${fix.externalTaskId}: once the push is recorded, its open findings are marked fixed at this commit. Read review.get for ${fix.externalTaskId} and ask the user whether to review it again (review.start) or end its review as passed (review.conclude).`
+                            : policy === 'required'
+                                ? ' Code review is required in this project: if a PR/MR is opened for this branch, open it as a draft and record it (task.open_review_request on GitLab, task.review_request elsewhere). Recording it starts the review, which review.start runs.'
+                                : ''),
                 },
             });
         const destination = data.delivery.destination;
@@ -152,6 +212,8 @@ export function registerDeliveryTools(server, service) {
             language,
             copy,
             decisionAttempt: input.decisionAttempt ?? 0,
+            reviewPolicy: policy,
+            reviewFixOf: fix?.taskId ?? null,
         };
         const binding = { deliveryDigest: sha256(stableStringify(identity)) };
         const owner = {
@@ -163,20 +225,47 @@ export function registerDeliveryTools(server, service) {
         const questionnaireId = 'task-delivery-' + binding.deliveryDigest;
         const canPush = Boolean(destination.remote && destination.pushUrl);
         const ids = canPush
-            ? ['commit', 'commit_push', 'commit_push_draft_pr', 'commit_push_pr', 'defer']
+            ? [...offered(policy, Boolean(fix)), 'defer']
             : ['commit', 'defer'];
         const instruction = input.deliveryInstruction;
-        const recorded = data.deliveryRecord?.choice;
-        if (instruction && !ids.some((id) => id === instruction.choice))
+        const instructed = !instruction
+            ? null
+            : fix && pullRequest(instruction.choice)
+                ? 'commit_push'
+                : policy === 'required' && pullRequest(instruction.choice)
+                    ? 'commit_push_review_pr'
+                    : instruction.choice;
+        if (instructed && !ids.includes(instructed))
             return output({
                 ok: false,
                 error: {
                     kind: 'delivery',
-                    message: 'This delivery needs an available remote and push URL. No Git action was performed.',
+                    message: !canPush
+                        ? 'This delivery needs an available remote and push URL. No Git action was performed.'
+                        : policy === 'none'
+                            ? 'Code review is off in this project, so a reviewed PR/MR is not offered. No Git action was performed. Call task.close without deliveryInstruction to ask the user how to deliver.'
+                            : 'Code review is optional in this project, so a draft PR/MR is either reviewed first or opened without review, and the instruction does not say which. No Git action was performed. Call task.close without deliveryInstruction to ask the user.',
                     recovery: 'task.close',
                     retryable: false,
                 },
             });
+        const line = !canPush
+            ? ''
+            : fix
+                ? copy.reviewFix && format(copy.reviewFix, language ?? 'en', { task: fix.externalTaskId })
+                : policy === 'required'
+                    ? copy.reviewRequired
+                    : policy === 'optional'
+                        ? copy.reviewOptional
+                        : '';
+        if (!instruction && (line === undefined || ids.some((id) => !wording(copy, policy, id))))
+            return output(incompleteCopy);
+        const recorded = data.deliveryRecord?.choice;
+        const recordedLabel = !recorded
+            ? undefined
+            : data.deliveryRecord?.reviewState === 'pending'
+                ? (copy.commit_push_review_pr ?? copy[recorded]).label
+                : (wording(copy, policy, recorded) ?? copy[recorded]).label;
         const form = instruction
             ? null
             : await askQuestionnaire(server, service, {
@@ -192,18 +281,15 @@ export function registerDeliveryTools(server, service) {
                     ': ' +
                     destination.branch +
                     (canPush ? ' → ' + destination.remote + ' (' + destination.pushUrl + ')' : '') +
-                    (recorded && copy.recorded
-                        ? '\n' + copy.recorded + ': ' + copy[recorded].label
-                        : ''),
+                    (recordedLabel && copy.recorded
+                        ? '\n' + copy.recorded + ': ' + recordedLabel
+                        : '') +
+                    (line ? '\n' + line : ''),
                 example: copy.example,
-                options: ids.map((id) => ({
-                    id,
-                    label: copy[id].label,
-                    description: copy[id].description,
-                })),
+                options: ids.map((id) => ({ id, ...wording(copy, policy, id) })),
                 binding,
             }, context, [], owner);
-        const choice = instruction?.choice ?? (form ? answerChoice(form) : null);
+        const choice = instructed ?? (form ? answerChoice(form) : null);
         if (!choice)
             return form;
         const { deliveryInstruction: _instruction, ...formInput } = input;
@@ -227,11 +313,9 @@ export function registerDeliveryTools(server, service) {
             return deferred();
         service.live.deliveryStarted();
         try {
-            let baseBranch = choice === 'commit_push_draft_pr' || choice === 'commit_push_pr'
-                ? instruction?.baseBranch
-                : undefined;
+            let baseBranch = pullRequest(choice) ? instruction?.baseBranch : undefined;
             let baseQuestionnaireId;
-            if ((choice === 'commit_push_draft_pr' || choice === 'commit_push_pr') && !baseBranch) {
+            if (pullRequest(choice) && !baseBranch) {
                 baseQuestionnaireId = 'task-delivery-base-' + sha256(questionnaireId + choice);
                 const base = await askPullRequestBase(server, service, context, { ...input, questionnaireId: baseQuestionnaireId, binding: { ...binding, choice } }, language, copy, owner);
                 if (!answerChoice(base))
@@ -242,7 +326,7 @@ export function registerDeliveryTools(server, service) {
                 if (!baseBranch)
                     return base;
             }
-            if (choice === 'commit_push_draft_pr' || choice === 'commit_push_pr') {
+            if (pullRequest(choice)) {
                 const valid = await service.taskDeliveryBase({
                     repoRoot: input.repoRoot,
                     branch: baseBranch,
@@ -299,6 +383,9 @@ export function registerDeliveryTools(server, service) {
                         retryable: false,
                     },
                 });
+            const now = current.data.reviewPolicy ?? 'none';
+            if (pullRequest(choice) && now !== policy)
+                return settingChanged('task.close', now);
             const question = instruction
                 ? null
                 : await service.questionnaireResume({ repoRoot: input.repoRoot, questionnaireId });
@@ -313,14 +400,21 @@ export function registerDeliveryTools(server, service) {
                     projectId: record.projectId,
                     taskId: record.taskId,
                     expectedVersion: record.lockVersion,
-                    choice,
+                    choice: choice === 'commit_push_review_pr' ? 'commit_push_draft_pr' : choice,
                     ...(baseBranch ? { baseBranch } : {}),
+                    ...(pullRequest(choice) && data.reviewPolicy
+                        ? { expectedReviewPolicy: data.reviewPolicy }
+                        : {}),
                     answerSource: question ? answerSourceName(question.answerSource) : 'user_instruction',
                 })
                 : null;
             const answered = answer?.ok ? answer.data : null;
             const refused = answer && !answer.ok ? answer.error : null;
-            const other = refused?.details?.delivery;
+            const details = refused?.details;
+            if (details?.reviewPolicy)
+                return settingChanged('task.close', details.reviewPolicy);
+            const other = details?.delivery;
+            const told = instruction && instructed !== instruction.choice ? instruction.choice : null;
             return output({
                 ok: true,
                 data: {
@@ -352,7 +446,24 @@ export function registerDeliveryTools(server, service) {
                         ...(baseQuestionnaireId ? { baseQuestionnaireId } : {}),
                         destination,
                     },
-                    nextAction: 'Perform only the selected Git delivery under host permissions. No commit, push, PR/MR or merge was executed by task.close. Preserve this exact branch and destination.',
+                    nextAction: [
+                        'Perform only the selected Git delivery under host permissions. No commit, push, PR/MR or merge was executed by task.close. Preserve this exact branch and destination.',
+                        told && fix
+                            ? `The user asked for a PR/MR, but this task fixes the review findings of ${fix.externalTaskId}, whose PR/MR is already open: its changes are committed and pushed onto that branch and no new PR/MR is opened. Tell the user.`
+                            : told
+                                ? 'The user asked for a PR/MR without saying it is reviewed, and code review is required in this project, so it opens as a draft and becomes ready once the review ends. Tell the user.'
+                                : '',
+                        choice === 'commit_push_review_pr'
+                            ? `After the push and worktree.release, open the PR/MR into ${baseBranch} as a draft: on GitLab task.open_review_request opens it as a draft; elsewhere open it as a draft with your own tools and record it with task.review_request. Then start the code review with review.start for this task. The PR/MR becomes ready when the review ends.`
+                            : '',
+                        fix && choice === 'commit_push'
+                            ? `The push goes onto ${destination.branch}, the open PR/MR branch of ${fix.externalTaskId}; open no new PR/MR. Once the push is recorded by worktree.release, the open findings of ${fix.externalTaskId} are marked fixed at that commit: read review.get for ${fix.externalTaskId} and ask the user whether to review it again (review.start) or end its review as passed (review.conclude).`
+                            : fix
+                                ? `The findings of ${fix.externalTaskId} stay open until this commit is pushed onto its PR/MR branch.`
+                                : '',
+                    ]
+                        .filter(Boolean)
+                        .join(' '),
                 },
             });
         }
@@ -375,10 +486,10 @@ function registerTaskDelivery(server, service) {
     }, async (input, context) => {
         const language = await service.language(input.language);
         const copy = language ? copySchema.safeParse(texts('delivery', language)).data : undefined;
-        const wording = language
+        const recordCopy = language
             ? recordWording.safeParse(texts('taskDelivery', language)).data
             : undefined;
-        if (!language || !copy || !wording)
+        if (!language || !copy || !recordCopy)
             return output({
                 ok: false,
                 error: {
@@ -410,7 +521,14 @@ function registerTaskDelivery(server, service) {
                     nextAction: 'This delivery is already concluded. Tell the user what was recorded.',
                 },
             });
-        const binding = { taskId: record.taskId, lockVersion: record.lockVersion };
+        const policy = record.reviewPolicy ?? 'none';
+        const fix = Boolean(record.reviewFixOfDeliveryId);
+        const binding = {
+            taskId: record.taskId,
+            lockVersion: record.lockVersion,
+            reviewPolicy: policy,
+            reviewFix: fix,
+        };
         const questionnaireId = 'task-delivery-record-' +
             sha256(stableStringify({ ...binding, decisionAttempt: input.decisionAttempt ?? 0 }));
         const owner = {
@@ -423,28 +541,38 @@ function registerTaskDelivery(server, service) {
                 language: input.language,
             },
         };
-        const ids = [
-            'commit',
-            'commit_push',
-            'commit_push_draft_pr',
-            'commit_push_pr',
-            'abandon',
-            'defer',
-        ];
+        const ids = offered(policy, fix);
+        const line = fix || policy === 'none'
+            ? ''
+            : policy === 'required'
+                ? copy.reviewRequired
+                : copy.reviewOptional;
+        if (line === undefined || ids.some((id) => !wording(copy, policy, id)))
+            return output({
+                ok: false,
+                error: {
+                    kind: 'delivery',
+                    message: "The delivery question has no code review text in the conversation language, and this project's question needs it. Ask again in a language Engineering Memory offers.",
+                    recovery: 'task.delivery',
+                    retryable: false,
+                },
+            });
         const form = await askQuestionnaire(server, service, {
             repoRoot: input.repoRoot,
             presentation: input.presentation,
             questionnaireId,
             language,
             impact: 'critical',
-            message: format(wording.message, language, { task: record.externalTaskId }),
-            context: wording.context + (record.branch ? '\n' + copy.destination + ': ' + record.branch : ''),
-            example: wording.example,
-            options: ids.map((id) => ({
-                id,
-                label: id === 'abandon' ? wording.abandon.label : copy[id].label,
-                description: id === 'abandon' ? wording.abandon.description : copy[id].description,
-            })),
+            message: format(recordCopy.message, language, { task: record.externalTaskId }),
+            context: recordCopy.context +
+                (record.branch ? '\n' + copy.destination + ': ' + record.branch : '') +
+                (line ? '\n' + line : ''),
+            example: recordCopy.example,
+            options: [
+                ...ids.map((id) => ({ id, ...wording(copy, policy, id) })),
+                { id: 'abandon', ...recordCopy.abandon },
+                { id: 'defer', ...copy.defer },
+            ],
             binding,
         }, context, [], owner);
         const choice = answerChoice(form);
@@ -466,7 +594,7 @@ function registerTaskDelivery(server, service) {
                 reason: 'abandoned',
             }));
         let baseBranch;
-        if (choice === 'commit_push_draft_pr' || choice === 'commit_push_pr') {
+        if (pullRequest(choice)) {
             const base = await askPullRequestBase(server, service, context, {
                 ...input,
                 questionnaireId: 'task-delivery-base-' + sha256(questionnaireId + choice),
@@ -495,10 +623,17 @@ function registerTaskDelivery(server, service) {
             projectId: input.projectId,
             taskId: input.taskId,
             expectedVersion: record.lockVersion,
-            choice,
+            choice: choice === 'commit_push_review_pr' ? 'commit_push_draft_pr' : choice,
             ...(baseBranch ? { baseBranch } : {}),
+            ...(pullRequest(choice) && record.reviewPolicy
+                ? { expectedReviewPolicy: record.reviewPolicy }
+                : {}),
             answerSource: answerSourceName(question.answerSource),
         });
+        const changed = answer.error?.details
+            ?.reviewPolicy;
+        if (changed)
+            return settingChanged('task.delivery', changed);
         if (!answer.ok)
             return output(answer);
         return output({
@@ -512,28 +647,47 @@ function registerTaskDelivery(server, service) {
 }
 function registerTaskReviewRequest(server, service) {
     server.registerTool('task.review_request', {
-        description: "Record the pull request (GitHub) or merge request (GitLab) a closed task's changes went into, and its state: draft, ready, merged or closed. Call it with the link copied from the provider as soon as the pull request is opened, and again when the user says it became ready, was merged or was closed. Engineering Memory then moves the task's work item as the project's workflow rules say, for example to PR when every pull request of the work item is ready and to READY FOR QA when they are all merged. It works from any chat, also for a delivery session.entry lists. What is recorded is what was reported: Engineering Memory does not check it with the provider, and performs no Git or provider action.",
+        description: "Record the pull request (GitHub) or merge request (GitLab) a closed task's changes went into, and its state: draft, ready, merged or closed. Call it with the link copied from the provider as soon as the pull request is opened, and again when the user says it became ready, was merged or was closed. Pass headCommit and targetBranch when you can read them from the provider (on GitHub, gh pr view with --json headRefOid,baseRefName): a code review that had passed waits again when the pull request gets a new commit or a new target branch. Engineering Memory then moves the task's work item as the project's workflow rules say, for example to PR when every pull request of the work item is ready and to READY FOR QA when they are all merged. It works from any chat, also for a delivery session.entry lists. What is recorded is what was reported: Engineering Memory does not check it with the provider, and performs no Git or provider action.",
         inputSchema: z.strictObject({
             projectId: z.string().uuid(),
             taskId: z.string().uuid(),
             url: z.string().trim().min(1).max(500),
             state: z.enum(['draft', 'ready', 'merged', 'closed']),
+            headCommit: z
+                .string()
+                .regex(/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/)
+                .optional(),
+            targetBranch: z.string().trim().min(1).max(255).optional(),
         }),
     }, async (input) => {
         const result = await service.taskReviewRequest(input);
         if (!result.ok)
             return output(result);
         const recorded = result.data;
+        const reopened = recorded.data?.reviewReopened;
+        const job = recorded.data?.providerJob;
         return output({
             ok: true,
             data: {
                 ...result.data,
                 nextAction: recorded.queued
                     ? 'Engineering Memory is unreachable, so this report is queued. It is recorded, and the work item moves as the rules say, when Engineering Memory is reachable again.'
-                    : (recorded.data?.reviewEvent?.nextAction ??
-                        (recorded.data?.reviewEvent
-                            ? 'The pull request is recorded; the work item stays where it is.'
-                            : 'The pull request is recorded. The work item does not move yet: other work on it is still open or undelivered, or the task has no active work item.')),
+                    : [
+                        reopened
+                            ? `The code review of this delivery had passed, but the pull request has ${reopened === 'new_target' ? 'a new target branch' : 'a new commit'} now, so the review waits again. Tell the user in one line; review.start runs the next round.`
+                            : '',
+                        job === 'make_draft'
+                            ? 'This project requires code review, so turn the pull request back into a draft with your own tools (on GitHub, gh pr ready --undo) and record it with state draft.'
+                            : job === 'make_ready'
+                                ? 'Its code review has already ended: review.make_ready makes the pull request ready.'
+                                : '',
+                        recorded.data?.reviewEvent?.nextAction ??
+                            (recorded.data?.reviewEvent
+                                ? 'The pull request is recorded; the work item stays where it is.'
+                                : 'The pull request is recorded. The work item does not move yet: other work on it is still open or undelivered, or the task has no active work item.'),
+                    ]
+                        .filter(Boolean)
+                        .join(' '),
             },
         });
     });