engineering-memory 1.11.29 → 1.11.31

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/skill/references/lifecycle.md

@@ -304,12 +304,14 @@ When the user later says a pull request became ready, was merged or was closed,
 
 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.
+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
@@ -454,3 +456,24 @@ roles stay as they are; change an aimed role separately with work_item.setup_wor
 bound to the counts it showed: when they change, the question is asked again, and a change at the
 moment of writing moves nothing. It is critical under the task mode. An empty source needs no
 question. Keep the same requestKey to resume and honor deferral as in the flows above.
+
+## Jira connection
+
+When the user asks to connect Jira, to link the project to a Jira project or to match people, start
+with `jira.status`: it reads the bound project's link and the organization's connections and names
+the next step. `jira.connect` returns a one-time link: give it to the user as it is and never open it
+yourself; they open it on this computer and approve access in Atlassian. Call `jira.connect` again
+without `restart` to learn how it ended, and while it still waits, wait for the user; `restart: true`
+only discards a link the user no longer wants. When Jira is not configured on the server, say that
+the person who runs the server must add its settings, and do not retry. A connection that needs
+reconnecting is renewed with `jira.connect`.
+
+`jira.link_project`, `jira.unlink_project`, `jira.disconnect` and `jira.map_people` take a
+`requestKey`: reuse it to retry or continue the same request, and use a new one when the user asks
+again later. Every choice here (the site, the Jira project, replacing or pausing a link,
+disconnecting, who each person is) is asked of the user natively in every task mode; never answer it
+yourself. Pass a Jira project key the user names as `jiraProjectKey`. Match a person only from the
+user's answer and never guess a handle; a typed e-mail address is refused, so ask for the part before
+`@`. The access only reads Jira and Jira issues are not brought in yet, so do not promise writing to
+Jira or importing issues. After a disconnect the user can also remove the app on Atlassian's side, at
+id.atlassian.com → Connected apps, as the tool says.