@zq-silk/yui 0.2.0 → 0.4.2

package/dist/review/reviewConfig.js

@@ -0,0 +1,11 @@
+import { requireIdentity } from "../domain/validation.js";
+export const REVIEW_TRIGGERS = ["always", "leader", "final"];
+/** The Reviewer Role seeded in a new Home by `yui setup`. */
+export const DEFAULT_REVIEWER_ROLE = "reviewer";
+export function validateReviewConfig(config) {
+    requireIdentity(config.roleName, "Review Role");
+    if (!REVIEW_TRIGGERS.includes(config.trigger)) {
+        throw new Error(`Review trigger is invalid: ${String(config.trigger)}.`);
+    }
+    return config;
+}

package/dist/review/reviewRound.js

@@ -0,0 +1,399 @@
+import { requireIdentity, requireText, requireTimestamp } from "../domain/validation.js";
+import { validateTaskRecordReference } from "../task/taskRecordReference.js";
+import { validateTaskFinalReviewContract } from "./taskFinalReviewContract.js";
+import { validateManagedWorkspace } from "../worktree/managedWorkspace.js";
+import { assertExecutionGroupTransition, validateExecutionGroup } from "../execution/executionGroup.js";
+export function createReviewRound(id, taskId, workItemId, candidateId, reviewerRoleName, requestedBy, reviewBaseCommit, now, executionGroup) {
+    return validateReviewRound({
+        schemaVersion: 4,
+        id: requireIdentity(id, "ReviewRound id"),
+        taskId: requireIdentity(taskId, "Task id"),
+        workItemId: requireIdentity(workItemId, "Work Item id"),
+        candidateId: requireIdentity(candidateId, "Candidate id"),
+        reviewerRoleName: requireIdentity(reviewerRoleName, "Reviewer Role"),
+        reviewBaseCommit: requireCommit(reviewBaseCommit, "Review base commit"),
+        requestedBy: validateReviewRequestSource(requestedBy),
+        status: "pending",
+        ...(executionGroup === undefined ? {} : { executionGroup }),
+        createdAt: now.toISOString()
+    });
+}
+export function createTaskReviewRound(id, taskId, workItemId, candidateId, reviewerRoleName, requestedBy, taskCandidate, now, taskFinalReviewContract, executionGroup) {
+    const candidate = validateTaskReviewCandidate(taskCandidate);
+    return validateReviewRound({
+        schemaVersion: 4,
+        id: requireIdentity(id, "ReviewRound id"),
+        taskId: requireIdentity(taskId, "Task id"),
+        workItemId: requireIdentity(workItemId, "Work Item id"),
+        candidateId: requireIdentity(candidateId, "Candidate id"),
+        reviewerRoleName: requireIdentity(reviewerRoleName, "Reviewer Role"),
+        reviewBaseCommit: candidate.projects[0].commit,
+        scope: "task",
+        taskCandidate: candidate,
+        ...(taskFinalReviewContract === undefined
+            ? {}
+            : { taskFinalReviewContract }),
+        requestedBy: validateReviewRequestSource(requestedBy),
+        status: "pending",
+        ...(executionGroup === undefined ? {} : { executionGroup }),
+        createdAt: now.toISOString()
+    });
+}
+export function attachReviewRoundWorkspace(round, workspace) {
+    validateReviewRound(round);
+    validateReviewWorkspace(round, workspace);
+    if (round.status !== "pending") {
+        throw new Error(`ReviewRound workspace cannot attach from ${round.status}: ${round.id}.`);
+    }
+    if (round.workspace !== undefined) {
+        if (JSON.stringify(round.workspace) !== JSON.stringify(workspace)) {
+            throw new Error(`ReviewRound workspace is immutable: ${round.id}.`);
+        }
+        return round;
+    }
+    return validateReviewRound({ ...round, workspace });
+}
+export function startReviewRound(round, reviewerRunId) {
+    validateReviewRound(round);
+    if (round.status !== "pending") {
+        throw new Error(`ReviewRound cannot start from ${round.status}: ${round.id}.`);
+    }
+    if (round.workspace === undefined) {
+        throw new Error(`ReviewRound workspace is not ready: ${round.id}.`);
+    }
+    return validateReviewRound({
+        ...round,
+        reviewerRunId: requireIdentity(reviewerRunId, "Reviewer Run id"),
+        status: "running"
+    });
+}
+export function finishReviewRound(round, status, summary, now, result = {}) {
+    validateReviewRound(round);
+    if (round.status !== "pending" && round.status !== "running") {
+        throw new Error(`ReviewRound is already terminal: ${round.id}.`);
+    }
+    return validateReviewRound({
+        ...round,
+        status,
+        summary: requireText(summary, "Review summary"),
+        report: requireText(result.report ?? summary, "Review report"),
+        checks: validateChecks(result.checks ?? []),
+        ...(result.evidenceCommit === undefined
+            ? {}
+            : { evidenceCommit: requireCommit(result.evidenceCommit, "Review evidence commit") }),
+        endedAt: now.toISOString()
+    });
+}
+/** Accepts the Reviewer's complete report and extracts only optional known evidence. */
+export function parseReviewYieldReport(value) {
+    const report = requireText(value, "Review report");
+    let parsed;
+    try {
+        parsed = JSON.parse(report);
+    }
+    catch {
+        return { summary: report, report, checks: [] };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return { summary: report, report, checks: [] };
+    }
+    const record = parsed;
+    const summary = typeof record.summary === "string" && record.summary.trim().length > 0
+        ? requireText(record.summary, "Review summary")
+        : report;
+    const checks = extractChecks(record.checks);
+    const findings = extractFindings(record.findings);
+    const evidence = extractEvidence(record.evidence);
+    return {
+        summary,
+        report,
+        checks,
+        ...(findings.length === 0 ? {} : { findings }),
+        ...(evidence.length === 0 ? {} : { evidence }),
+        ...(typeof record.evidenceCommit !== "string"
+            ? {}
+            : {
+                evidenceCommit: requireCommit(record.evidenceCommit, "Review evidence commit")
+            })
+    };
+}
+function extractFindings(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((entry) => {
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+            return [];
+        }
+        const finding = entry;
+        if (typeof finding.id !== "string"
+            || (finding.severity !== "low" && finding.severity !== "medium"
+                && finding.severity !== "high" && finding.severity !== "critical"
+                && finding.severity !== "p1" && finding.severity !== "p2")
+            || (finding.status !== "open" && finding.status !== "resolved")
+            || typeof finding.summary !== "string") {
+            return [];
+        }
+        return [{
+                id: requireIdentity(finding.id, "Review finding id"),
+                // Reviewers may use the product-level P1/P2 vocabulary. Execution
+                // groups keep one canonical severity scale so resolution gates remain
+                // stable across Worker and Reviewer reports.
+                severity: finding.severity === "p1"
+                    ? "critical"
+                    : finding.severity === "p2"
+                        ? "high"
+                        : finding.severity,
+                status: finding.status,
+                summary: requireText(finding.summary, "Review finding summary")
+            }];
+    });
+}
+function extractEvidence(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((entry) => (typeof entry === "string" && entry.trim().length > 0 ? [entry.trim()] : []));
+}
+export function recordReviewWorkspaceDisposition(round, disposition, now) {
+    validateReviewRound(round);
+    if (round.status !== "completed" && round.status !== "failed") {
+        throw new Error(`ReviewRound must be terminal before workspace disposition: ${round.id}.`);
+    }
+    if (round.workspace === undefined) {
+        throw new Error(`ReviewRound has no managed workspace: ${round.id}.`);
+    }
+    if (disposition !== "preserved" && disposition !== "removed") {
+        throw new Error(`Review workspace disposition is invalid: ${String(disposition)}.`);
+    }
+    if (round.workspaceDisposition?.kind === disposition)
+        return round;
+    if (round.workspaceDisposition?.kind === "removed") {
+        throw new Error(`ReviewRound workspace is already removed: ${round.id}.`);
+    }
+    return validateReviewRound({
+        ...round,
+        workspaceDisposition: { kind: disposition, recordedAt: now.toISOString() }
+    });
+}
+/** Attach the common Reviewer panel Group while preserving the Round target. */
+export function attachReviewExecutionGroup(round, executionGroup) {
+    validateReviewRound(round);
+    validateReviewExecutionGroup(executionGroup, round);
+    if (round.status !== "pending") {
+        throw new Error(`ReviewRound ExecutionGroup cannot attach from ${round.status}: ${round.id}.`);
+    }
+    if (round.executionGroup !== undefined) {
+        if (JSON.stringify(round.executionGroup) !== JSON.stringify(executionGroup)) {
+            throw new Error(`ReviewRound ExecutionGroup is immutable: ${round.id}.`);
+        }
+        return round;
+    }
+    return validateReviewRound({ ...round, executionGroup });
+}
+/** Advance a Reviewer panel Group without changing the Round target. */
+export function updateReviewExecutionGroup(round, executionGroup) {
+    validateReviewRound(round);
+    validateReviewExecutionGroup(executionGroup, round);
+    if (round.executionGroup === undefined) {
+        if (round.status !== "pending") {
+            throw new Error(`ReviewRound ExecutionGroup cannot attach from ${round.status}: ${round.id}.`);
+        }
+        return validateReviewRound({ ...round, executionGroup });
+    }
+    if (round.executionGroup.id !== executionGroup.id
+        || JSON.stringify(round.executionGroup.target) !== JSON.stringify(executionGroup.target)) {
+        throw new Error(`ReviewRound ExecutionGroup target is immutable: ${round.id}.`);
+    }
+    if (JSON.stringify(round.executionGroup) === JSON.stringify(executionGroup))
+        return round;
+    assertExecutionGroupTransition(round.executionGroup, executionGroup);
+    return validateReviewRound({ ...round, executionGroup });
+}
+export function validateReviewRound(round) {
+    if (round.schemaVersion !== 4)
+        throw new Error("ReviewRound must use schemaVersion 4.");
+    validateTaskRecordReference({ taskId: round.taskId, localId: round.id }, "reviewRound");
+    validateTaskRecordReference({ taskId: round.taskId, localId: round.workItemId }, "workItem");
+    if (!/^candidate-[1-9]\d*$/.test(round.candidateId)) {
+        throw new Error(`Candidate local id is invalid: ${round.candidateId}.`);
+    }
+    requireIdentity(round.reviewerRoleName, "Reviewer Role");
+    requireCommit(round.reviewBaseCommit, "Review base commit");
+    const scope = round.scope ?? "work-item";
+    if (scope !== "work-item" && scope !== "task") {
+        throw new Error(`ReviewRound scope is invalid: ${String(round.scope)}.`);
+    }
+    if (scope === "task") {
+        if (round.taskCandidate === undefined) {
+            throw new Error(`Task ReviewRound requires a frozen Task candidate: ${round.id}.`);
+        }
+        const candidate = validateTaskReviewCandidate(round.taskCandidate);
+        if (candidate.projects[0].commit !== round.reviewBaseCommit) {
+            throw new Error(`Task ReviewRound base does not match its primary Project: ${round.id}.`);
+        }
+        if (round.taskFinalReviewContract !== undefined) {
+            const contract = validateTaskFinalReviewContract(round.taskFinalReviewContract);
+            if (contract.taskId !== round.taskId) {
+                throw new Error(`Task ReviewRound contract belongs to another Task: ${round.id}.`);
+            }
+            if (contract.reviewerRoleName !== round.reviewerRoleName) {
+                throw new Error(`Task ReviewRound contract uses another Reviewer Role: ${round.id}.`);
+            }
+        }
+    }
+    else if (round.taskCandidate !== undefined
+        || round.taskFinalReviewContract !== undefined) {
+        throw new Error(`WorkItem ReviewRound cannot carry a Task candidate or contract: ${round.id}.`);
+    }
+    if (round.executionGroup !== undefined)
+        validateReviewExecutionGroup(round.executionGroup, round);
+    validateReviewRequestSource(round.requestedBy);
+    if (!["pending", "running", "completed", "failed"].includes(round.status)) {
+        throw new Error(`ReviewRound status is invalid: ${String(round.status)}.`);
+    }
+    if (round.reviewerRunId !== undefined) {
+        validateTaskRecordReference({
+            taskId: round.taskId,
+            localId: round.reviewerRunId
+        }, "agentRun");
+    }
+    if (round.workspace !== undefined)
+        validateReviewWorkspace(round, round.workspace);
+    requireTimestamp(round.createdAt, "ReviewRound createdAt");
+    const terminal = round.status === "completed" || round.status === "failed";
+    if (terminal) {
+        requireText(round.summary ?? "", "Review summary");
+        requireText(round.report ?? "", "Review report");
+        validateChecks(round.checks ?? []);
+        if (round.evidenceCommit !== undefined) {
+            requireCommit(round.evidenceCommit, "Review evidence commit");
+            if (round.evidenceCommit === round.reviewBaseCommit) {
+                throw new Error("Review evidence commit must differ from its review base.");
+            }
+        }
+        requireTimestamp(round.endedAt ?? "", "ReviewRound endedAt");
+    }
+    else if (round.summary !== undefined
+        || round.report !== undefined
+        || round.checks !== undefined
+        || round.evidenceCommit !== undefined
+        || round.endedAt !== undefined) {
+        throw new Error("An active ReviewRound cannot have terminal metadata.");
+    }
+    if (round.status === "running"
+        && (round.reviewerRunId === undefined || round.workspace === undefined)) {
+        throw new Error("A running ReviewRound requires a Reviewer Run and workspace.");
+    }
+    if (round.workspaceDisposition !== undefined) {
+        if (!terminal || round.workspace === undefined) {
+            throw new Error("Only a terminal ReviewRound workspace can have a disposition.");
+        }
+        if (round.workspaceDisposition.kind !== "preserved"
+            && round.workspaceDisposition.kind !== "removed") {
+            throw new Error("Review workspace disposition is invalid.");
+        }
+        requireTimestamp(round.workspaceDisposition.recordedAt, "Review workspace disposition time");
+    }
+    return round;
+}
+function validateReviewExecutionGroup(group, round) {
+    validateExecutionGroup(group);
+    if (group.taskId !== round.taskId || group.purpose !== "review") {
+        throw new Error(`ReviewRound ExecutionGroup provenance is invalid: ${round.id}.`);
+    }
+    const expectedKind = (round.scope ?? "work-item") === "task"
+        ? "task-final-review"
+        : "work-item";
+    if (group.target.kind !== expectedKind
+        || group.target.taskId !== round.taskId
+        || group.target.candidateId !== round.candidateId) {
+        throw new Error(`ReviewRound ExecutionGroup target is invalid: ${round.id}.`);
+    }
+    if (expectedKind === "work-item" && group.target.workItemId !== round.workItemId) {
+        throw new Error(`ReviewRound ExecutionGroup WorkItem target is invalid: ${round.id}.`);
+    }
+    return group;
+}
+export function validateTaskReviewCandidate(candidate) {
+    if (candidate.schemaVersion !== 1) {
+        throw new Error("Task Review candidate must use schemaVersion 1.");
+    }
+    if (!Array.isArray(candidate.projects) || candidate.projects.length === 0) {
+        throw new Error("Task Review candidate requires at least one Project.");
+    }
+    const projects = candidate.projects.map(({ projectId, commit }) => ({
+        projectId: requireIdentity(projectId, "Task Review Project"),
+        commit: requireCommit(commit, "Task Review Project commit")
+    }));
+    if (new Set(projects.map(({ projectId }) => projectId)).size !== projects.length) {
+        throw new Error("Task Review candidate Projects must be unique.");
+    }
+    return { schemaVersion: 1, projects };
+}
+function extractChecks(value) {
+    if (!Array.isArray(value))
+        return [];
+    const extracted = value.flatMap((entry) => {
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry))
+            return [];
+        const check = entry;
+        if (typeof check.name !== "string"
+            || (check.outcome !== "passed"
+                && check.outcome !== "failed"
+                && check.outcome !== "skipped"))
+            return [];
+        return [{
+                name: check.name,
+                outcome: check.outcome,
+                ...(typeof check.details === "string" ? { details: check.details } : {})
+            }];
+    });
+    return validateChecks(extracted);
+}
+function validateReviewWorkspace(round, workspace) {
+    validateManagedWorkspace(workspace);
+    if (workspace.owner.taskId !== round.taskId) {
+        throw new Error(`ReviewRound workspace provenance is invalid: ${round.id}.`);
+    }
+    if (workspace.owner.type !== "review-round"
+        || workspace.owner.reviewRoundId !== round.id) {
+        throw new Error(`ReviewRound does not own its workspace: ${round.id}.`);
+    }
+    if (workspace.entries.length === 0
+        || workspace.entries.some(({ access }) => access !== "write")) {
+        throw new Error(`ReviewRound workspace must contain only writable isolated entries: ${round.id}.`);
+    }
+    if (!workspace.entries.some(({ baseCommit }) => baseCommit === round.reviewBaseCommit)) {
+        throw new Error(`ReviewRound workspace does not contain its review base: ${round.id}.`);
+    }
+}
+function validateChecks(checks) {
+    if (!Array.isArray(checks))
+        throw new Error("Review checks are invalid.");
+    return checks.map((check) => {
+        const name = requireText(check.name, "Review check name");
+        if (check.outcome !== "passed" && check.outcome !== "failed"
+            && check.outcome !== "skipped") {
+            throw new Error(`Review check outcome is invalid: ${String(check.outcome)}.`);
+        }
+        return {
+            name,
+            outcome: check.outcome,
+            ...(check.details === undefined
+                ? {}
+                : { details: requireText(check.details, "Review check details") })
+        };
+    });
+}
+function requireCommit(value, label) {
+    const commit = requireText(value, label).toLowerCase();
+    if (!/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/u.test(commit)) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return commit;
+}
+function validateReviewRequestSource(source) {
+    if (source !== "policy" && source !== "leader") {
+        throw new Error(`Review request source is invalid: ${String(source)}.`);
+    }
+    return source;
+}

package/dist/review/taskFinalReviewContract.js

@@ -0,0 +1,90 @@
+import { createHash } from "node:crypto";
+import { requireIdentity } from "../domain/validation.js";
+export const TASK_FINAL_REVIEW_ARGUMENT = "--yui-task-final-review";
+export function createTaskFinalReviewContract(input) {
+    const taskId = requireIdentity(input.taskId, "Task final-review contract Task id");
+    const reviewerRoleName = requireIdentity(input.reviewerRoleName, "Task final-review contract Reviewer Role");
+    const controlPlaneDigest = requireDigest(input.controlPlaneDigest, "Task final-review contract control-plane digest");
+    return Object.freeze({
+        schemaVersion: 1,
+        taskId,
+        reviewerRoleName,
+        controlPlaneDigest,
+        digest: contractDigest(taskId, reviewerRoleName, controlPlaneDigest)
+    });
+}
+export function validateTaskFinalReviewContract(value) {
+    if (typeof value !== "object" || value === null || value.schemaVersion !== 1) {
+        throw new Error("Task final-review contract must use schemaVersion 1.");
+    }
+    const expected = createTaskFinalReviewContract(value);
+    const digest = requireDigest(value.digest, "Task final-review contract digest");
+    if (digest !== expected.digest) {
+        throw new Error("Task final-review contract digest does not match its immutable fields.");
+    }
+    return value;
+}
+export function taskFinalReviewConfig(contract) {
+    const validated = validateTaskFinalReviewContract(contract);
+    return { roleName: validated.reviewerRoleName, trigger: "final" };
+}
+export function sameTaskFinalReviewContract(left, right) {
+    if (left === undefined || right === undefined)
+        return left === right;
+    return validateTaskFinalReviewContract(left).digest
+        === validateTaskFinalReviewContract(right).digest;
+}
+/**
+ * The contract switch is an exact CLI prefix, never an environment variable.
+ * It must immediately follow `--yui-control <digest>` so the preflight can
+ * bind it to the one verified Task runtime before opening mutable storage.
+ */
+export function extractTaskFinalReviewRequest(args) {
+    const index = args.indexOf(TASK_FINAL_REVIEW_ARGUMENT);
+    if (index < 0)
+        return { args: [...args] };
+    if (index !== 0) {
+        return {
+            args: [...args],
+            error: `${TASK_FINAL_REVIEW_ARGUMENT} must immediately follow the exact control prefix.`
+        };
+    }
+    const taskId = args[1];
+    const reviewerRoleName = args[2];
+    if (taskId === undefined || reviewerRoleName === undefined) {
+        return {
+            args: args.slice(3),
+            error: `${TASK_FINAL_REVIEW_ARGUMENT} requires <task-id> <reviewer-role>.`
+        };
+    }
+    try {
+        return {
+            request: {
+                taskId: requireIdentity(taskId, "Task final-review contract Task id"),
+                reviewerRoleName: requireIdentity(reviewerRoleName, "Task final-review contract Reviewer Role")
+            },
+            args: args.slice(3)
+        };
+    }
+    catch (error) {
+        return {
+            args: args.slice(3),
+            error: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
+function contractDigest(taskId, reviewerRoleName, controlPlaneDigest) {
+    return createHash("sha256").update(JSON.stringify([
+        "yui-task-final-review",
+        1,
+        taskId,
+        reviewerRoleName,
+        controlPlaneDigest
+    ])).digest("hex");
+}
+function requireDigest(value, label) {
+    if (typeof value !== "string" || !/^[a-f0-9]{64}$/u.test(value)) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return value;
+}