@cleocode/core 2026.10.27 → 2026.11.1-canary.10

package/dist/tasks/review-verdict.d.ts

@@ -0,0 +1,296 @@
+/**
+ * Independent per-AC review of a PR (T14122, council run
+ * 20261028T155822Z-293ed9f0, blocking amendment 2 of D11211).
+ *
+ * The author of a task cannot be the one who decides its criteria are met.
+ * A reviewer under its own CLEO session gets a {@link ReviewPacket}: the PR
+ * diff at its head and the task's criteria, never the PR title, body,
+ * comments, commit messages or changesets, so the author's `Closes:` lines
+ * and summary cannot steer it. It records one {@link ReviewVerdict} per
+ * criterion, bound to that head and to the packet it was given.
+ *
+ * Authorship is the task's work claim (T12502): the current claim holder,
+ * every holder a hand-off or take-over replaced, and the session that
+ * created the task. Git identity cannot serve, since every agent pushes under
+ * one GitHub account. A reviewer whose session or agent id is among them is
+ * refused, and a task with no recorded author refuses every verdict.
+ *
+ * Verdicts are task audit rows (`review.verdict`), written only by
+ * {@link recordReviewVerdict}; nothing parses PR text. The merge sweep
+ * (T14101) and `cleo review check` read them through
+ * {@link reviewVerdictsFor} and {@link judgeReviewVerdicts}.
+ *
+ * @task T14122
+ */
+import type { ReviewAnswer, ReviewAuthors, ReviewDispatch, ReviewJudgement, ReviewPacket, ReviewShadowComparison, ReviewVerdict, Task, TaskAuditLogRow } from '@cleocode/contracts';
+/** The audit action a verdict is recorded under. */
+export declare const REVIEW_VERDICT_ACTION = "review.verdict";
+/**
+ * The audit action a shadow verdict is recorded under (T14372): the same
+ * checks as a verdict, never read by {@link reviewVerdictsFor}, so it never
+ * counts toward a merge.
+ */
+export declare const REVIEW_SHADOW_VERDICT_ACTION = "review.shadow-verdict";
+/** The audit action a reviewer dispatch is recorded under (T14372). */
+export declare const REVIEW_DISPATCH_ACTION = "review.dispatch";
+/**
+ * The agent-id prefix of a dispatched reviewer worker (T14372). A verdict
+ * under such an id is accepted only from the session its dispatch created.
+ */
+export declare const REVIEWER_AGENT_PREFIX = "reviewer-";
+/**
+ * The environment variable a dispatched reviewer process carries its
+ * per-dispatch secret in (T14403). A verdict under a dispatch is accepted only
+ * when its SHA-256 matches the dispatch row's `reviewerSecretSha256`.
+ */
+export declare const REVIEW_SECRET_ENV = "CLEO_REVIEW_SECRET";
+/**
+ * The environment variable naming the file a dispatched reviewer reads its
+ * per-dispatch secret from (T14403): the path `cleo review dispatch` returns,
+ * so the secret itself never passes through a transcript or a command line.
+ */
+export declare const REVIEW_SECRET_FILE_ENV = "CLEO_REVIEW_SECRET_FILE";
+/**
+ * The reviewer dispatches recorded for one task on one PR (T14372), every head.
+ *
+ * @param projectRoot - Project root.
+ * @param taskId - The task.
+ * @param prNumber - The PR.
+ * @returns The dispatches, in no particular order.
+ * @task T14372
+ */
+export declare function reviewDispatchesFor(projectRoot: string, taskId: string, prNumber: number): Promise<ReviewDispatch[]>;
+/**
+ * Audit actions that name a task's claim holders (T14213): a fresh claim, a
+ * holder's own release, and every replacement or forced release. A holder
+ * stays an author after its claim is released or refocused.
+ */
+export declare const CLAIM_AUTHOR_ACTIONS: string[];
+/** How a packet reads a PR from GitHub. Injected by tests. */
+export interface ReviewDeps {
+    /** The PR's current head sha, or null when it cannot be read; may throw gh's own error (T14328). */
+    prHead(cwd: string, prNumber: number): Promise<string | null>;
+    /** The PR's diff at its current head, or null when it cannot be read; may throw gh's own error (T14328). */
+    prDiff(cwd: string, prNumber: number): Promise<string | null>;
+}
+/** Runs `gh` with arguments in a work tree and returns its stdout; throws on failure. */
+export type GhRunner = (args: string[], cwd: string) => string;
+/**
+ * {@link ReviewDeps} over a `gh` runner (T14328): `gh pr view` and
+ * `gh pr diff`, the diff verbatim (`--allow-escape-sequences`, no colour), so
+ * a diff carrying terminal escapes in its content is read, not refused.
+ *
+ * @param run - The `gh` runner (tests inject one).
+ * @returns The deps.
+ * @task T14328
+ */
+export declare function ghReviewDeps(run?: GhRunner): ReviewDeps;
+/** The default {@link ReviewDeps}: `gh pr view` and `gh pr diff`. */
+export declare const defaultReviewDeps: ReviewDeps;
+/**
+ * A diff with each raw ESC byte written as the visible text `\x1b` (T14328):
+ * a CI log or fixture in the diff can carry terminal escapes, and the packet
+ * is printed to a reviewer's terminal. The packet hashes this form, so one
+ * head still yields one packet.
+ *
+ * @param diff - The diff verbatim.
+ * @returns The same diff with no raw escape byte.
+ * @task T14328
+ */
+export declare function visibleEscapes(diff: string): string;
+/**
+ * A unified diff without the files whose path matches `withheld`, and the
+ * paths it left out.
+ *
+ * @param diff - A `git diff` / `gh pr diff` unified diff.
+ * @param withheld - Paths to leave out.
+ */
+export declare function withholdDiffPaths(diff: string, withheld?: RegExp): {
+    diff: string;
+    withheldPaths: string[];
+};
+/**
+ * A criterion's text as a packet shows it (T14259): whitespace runs collapsed
+ * and the ends trimmed, so a whitespace-only rewrite of the criteria changes
+ * neither the packet nor a verdict's {@link acTextSha256}.
+ *
+ * @param text - The criterion text as stored.
+ * @returns The normalised text.
+ * @task T14259
+ */
+export declare function normalizeAcText(text: string): string;
+/**
+ * The sha256 of a criterion's normalised text (T14259): a verdict binds the
+ * text it judged, so an edit after the verdict invalidates it.
+ *
+ * @param text - The criterion text, normalised or not.
+ * @returns The hex digest.
+ * @task T14259
+ */
+export declare function acTextSha256(text: string): string;
+/**
+ * The current normalised text of each of a task's criteria, by alias (T14259).
+ *
+ * @param projectRoot - Project root.
+ * @param taskId - The task.
+ * @returns Alias (`AC2`) to normalised text.
+ * @task T14259
+ */
+export declare function currentAcTexts(projectRoot: string, taskId: string): Promise<ReadonlyMap<string, string>>;
+/**
+ * A diff with the blob ids dropped from its `index <a>..<b>` lines (T14325):
+ * `gh pr diff` abbreviates them to a length that varies between calls, which
+ * made the packet sha flap for an unchanged head. The mode stays; the ids say
+ * nothing a reviewer judges.
+ *
+ * @param diff - A `git diff` / `gh pr diff` unified diff.
+ * @returns The same diff, deterministic for one head.
+ * @task T14325
+ */
+export declare function canonicalDiff(diff: string): string;
+/**
+ * Build the review packet for one PR and task: the diff at the PR head and
+ * the task's criteria, nothing the author wrote about the change.
+ *
+ * @param projectRoot - Project root (task store and `gh` working directory).
+ * @param prNumber - The PR.
+ * @param taskId - The task under review.
+ * @param deps - GitHub access.
+ * @throws CleoError when the task or the PR cannot be read, or the head moved while reading.
+ */
+export declare function buildReviewPacket(projectRoot: string, prNumber: number, taskId: string, deps?: ReviewDeps): Promise<ReviewPacket>;
+/**
+ * The identities that authored a task (T14122): its current claim holder,
+ * every session that ever claimed it, including a claim since released or
+ * refocused (T14213), every holder a hand-off or take-over replaced, and the
+ * session that created it.
+ *
+ * @param task - The task.
+ * @param claimRows - Its claim audit rows ({@link CLAIM_AUTHOR_ACTIONS}); a row's `action`, when given, keeps a forced release's releaser out (T14213).
+ */
+export declare function reviewAuthors(task: Pick<Task, 'claim' | 'provenance'>, claimRows: readonly (Pick<TaskAuditLogRow, 'beforeJson' | 'afterJson' | 'sessionId'> & Partial<Pick<TaskAuditLogRow, 'action'>>)[]): ReviewAuthors;
+/** What {@link recordReviewVerdict} records. */
+export interface ReviewVerdictInput {
+    /** The PR. */
+    prNumber: number;
+    /** The task. */
+    taskId: string;
+    /** The criterion alias (`AC2`). */
+    ac: string;
+    /** Whether the diff implements it. */
+    verdict: 'met' | 'unmet';
+    /** Why. */
+    reason: string;
+    /** The {@link ReviewPacket.packetSha256} the reviewer judged. */
+    packetSha256: string;
+    /** For a `met`: the id of the earlier non-author `unmet` verdict on this head it answers (T14128). */
+    answers?: string;
+    /** Record a shadow verdict (T14372): every check still applies; it never counts toward a merge. */
+    shadow?: boolean;
+}
+/**
+ * Record one reviewer's verdict on one criterion, bound to the PR head
+ * (T14122). The packet is rebuilt and must hash to `packetSha256`, so the
+ * verdict is about exactly the diff and criterion text the reviewer saw on
+ * the current head.
+ *
+ * @param projectRoot - Project root.
+ * @param input - The verdict.
+ * @param opts - The reviewer's environment (session binding, `CLEO_AGENT_ID`) and GitHub access.
+ * @returns The recorded verdict.
+ * @throws CleoError when the reviewer is unbound or an author, the task has no recorded author,
+ *   the criterion is unknown, the reason is empty, or the packet no longer matches.
+ */
+export declare function recordReviewVerdict(projectRoot: string, input: ReviewVerdictInput, opts?: {
+    env?: NodeJS.ProcessEnv;
+    deps?: ReviewDeps;
+}): Promise<ReviewVerdict>;
+/**
+ * The verdicts recorded for one task on one PR (T14122), oldest first. All of
+ * them, not only the latest: an earlier `unmet` a later `met` did not answer
+ * still counts (T14128).
+ *
+ * @param projectRoot - Project root.
+ * @param taskId - The task.
+ * @param prNumber - The PR.
+ */
+export declare function reviewVerdictsFor(projectRoot: string, taskId: string, prNumber: number): Promise<ReviewVerdict[]>;
+/**
+ * The shadow verdicts recorded for one task on one PR (T14372), oldest first.
+ *
+ * @param projectRoot - Project root.
+ * @param taskId - The task.
+ * @param prNumber - The PR.
+ * @task T14372
+ */
+export declare function shadowVerdictsFor(projectRoot: string, taskId: string, prNumber: number): Promise<ReviewVerdict[]>;
+/**
+ * Which criteria a task's verdicts prove met on a PR head, and why the rest
+ * are not (T14122). Only the latest verdict on `headSha` counts; a verdict on
+ * an older head is stale, and one whose reviewer is among its recorded
+ * authors counts for nothing. A `met` does not clear an earlier non-author
+ * `unmet` on the same head unless it answers it by id (T14128), so shopping
+ * for a friendlier reviewer leaves the criterion unmet and names the verdict
+ * that was not answered. The merge sweep and `cleo review check` share it,
+ * so both report the same reasons.
+ *
+ * A verdict binds the criterion text it judged (T14259): given the current
+ * texts, one whose {@link ReviewVerdict.acTextSha256} no longer matches is
+ * `edited`. A verdict recorded before that binding carries no hash and is
+ * judged as before.
+ *
+ * @param verdicts - The task's verdicts on the PR ({@link reviewVerdictsFor}).
+ * @param acs - The criteria to judge (`AC1`, …).
+ * @param headSha - The PR head (`headRefOid`).
+ * @param texts - Each criterion's current text by alias ({@link currentAcTexts}); omitted, no edit check.
+ */
+export declare function judgeReviewVerdicts(verdicts: readonly ReviewVerdict[], acs: readonly string[], headSha: string, texts?: ReadonlyMap<string, string>): ReviewJudgement;
+/**
+ * Each criterion's latest shadow verdict on a head next to the lead's latest
+ * counted one (T14372), so the lead can see whether a reviewer worker decides
+ * as it does before routine PRs are handed over. A counted verdict from a
+ * worker (a dispatched session or a `reviewer-*` agent id) is never the lead's,
+ * so a worker is never compared with itself.
+ *
+ * @param verdicts - Counted verdicts ({@link reviewVerdictsFor}).
+ * @param shadow - Shadow verdicts ({@link shadowVerdictsFor}).
+ * @param acs - The criteria.
+ * @param headSha - The PR head.
+ * @param workerSessions - Sessions created by dispatches ({@link reviewDispatchesFor}).
+ * @task T14372
+ */
+export declare function compareShadowVerdicts(verdicts: readonly ReviewVerdict[], shadow: readonly ReviewVerdict[], acs: readonly string[], headSha: string, workerSessions?: ReadonlySet<string>): ReviewShadowComparison[];
+/** One task's review state on a PR head ({@link checkPrReviews}). */
+export interface PrReviewCheck extends ReviewJudgement {
+    /** The task. */
+    taskId: string;
+    /** Each `unmet` on the head a later `met` answered, and by whom (T14137). */
+    answered: ReviewAnswer[];
+    /** Shadow verdicts next to counted ones, when any shadow verdict is on the head (T14372). */
+    shadow?: ReviewShadowComparison[];
+}
+/**
+ * The `unmet` verdicts on a head that a later `met` answered by id, with both
+ * reviewers (T14137): one reviewer answering every finding stands out.
+ *
+ * @param verdicts - A task's verdicts on the PR ({@link reviewVerdictsFor}).
+ * @param headSha - The PR head.
+ */
+export declare function reviewAnswers(verdicts: readonly ReviewVerdict[], headSha: string): ReviewAnswer[];
+/**
+ * The pre-merge review check for an open PR (T14122): for each task, which
+ * criteria a non-author verdict proves met on the PR's current head, and why
+ * the rest are not (missing, unmet, or reviewed on an older head). A push
+ * after review makes every verdict stale here, while the author can still
+ * fix it in the same PR.
+ *
+ * @param projectRoot - Project root.
+ * @param prNumber - The PR.
+ * @param taskIds - The tasks the PR delivers.
+ * @param opts - Narrow to these criteria (default: all of each task's), and GitHub access.
+ * @throws CleoError when the PR head cannot be read.
+ */
+export declare function checkPrReviews(projectRoot: string, prNumber: number, taskIds: readonly string[], opts?: {
+    acs?: readonly string[];
+    deps?: ReviewDeps;
+}): Promise<PrReviewCheck[]>;