@juzser/blacksmith 0.4.0 → 0.5.0

package/factory/orchestrator/dist/judges.js

@@ -1,8 +1,14 @@
-import { readFileSync } from 'node:fs';
+import { readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
 import { JUDGE_REPORT_EVENT_TYPE } from './agents-registry.js';
+import { isAuditAxisTaskId } from './audit.js';
+import { sessionOwnerRole } from './delegation.js';
 import { SmithError } from './errors.js';
 import { appendEvent, eventTaskId, readLineageEvents, } from './events.js';
+import { JUDGE_TURN_ROLES } from './judgeRoles.js';
+import { compileSchemas, validateEachShape } from './schemas.js';
 import { isQualifiedTaskId, taskIdsMatch } from './taskId.js';
+import { loadTaxonomy } from './taxonomy.js';
 export class JudgeError extends SmithError {
 }
 /**
@@ -37,6 +43,25 @@ export class JudgeError extends SmithError {
  * refuses to score a task while it is non-empty.
  */
 export const JUDGE_DISPATCH_EVENT_TYPE = 'dispatch_decision';
+/**
+ * judgeRoles.ts's `JUDGE_TURN_ROLES` — the six `JUDGE_ROLES` (reviewer,
+ * verifier, grader, spec-reviewer, security-reviewer, auditor) plus `uiux` —
+ * imported rather than copied so this module and judgeRoles.ts can never
+ * drift apart on which roles a dispatch/report pair can open and close a
+ * turn for. A `dispatch_decision` from any other role is a coder or a
+ * merger, not a judge, even when its payload accidentally carries
+ * `declared_artifact` and `round` (a copy-pasted judge dispatch command, or a
+ * hand-written event) — folding it anyway would open a turn `judge-reported`
+ * can never close, and the gate would refuse the task forever.
+ *
+ * Deliberately the wider set, not the plain `JUDGE_ROLES` six: uiux's visual
+ * pass is bracketed by `smith judge dispatch`/`smith judge report` in
+ * practice (wave.md:242-253) exactly like the six, so a real uiux dispatch
+ * must open a turn here too, even though `dispatchLint.ts`'s narrower
+ * artifact-line check and `judgeStopHook.ts`'s Stop guard stay scoped to the
+ * six (see judgeRoles.ts for why).
+ */
+const JUDGE_TURN_ROLE_SET = new Set(JUDGE_TURN_ROLES);
 /**
  * Re-exported, not re-declared. The registry owns the terminal-event
  * vocabulary — this one next to `task-result-recorded` and `error-logged`,
@@ -61,6 +86,43 @@ const DEFAULT_PROVIDER = 'claude';
 const DEFAULT_MODEL_TIER = 'frontier';
 /** `--no-findings`: an operator attesting that a judge ran clean, recorded as an attestation and never as an artifact. */
 const ATTESTED_BY = 'operator';
+/**
+ * `uiux` is the only role that can open more than one turn per task — a
+ * pre-code spec turn and a post-test visual turn — because a spec judgment
+ * and a screenshot judgment answer different questions and must close
+ * independently (S2). Every other role opens exactly one turn per task, so
+ * `kind` has nothing to disambiguate for it.
+ */
+const UIUX_ROLE = 'uiux';
+/**
+ * Exported so a caller that only has a kind to check, with no role to pair
+ * it with (e.g. `judge outstanding`'s `--kind` filter), can validate it
+ * against the same closed list `assertKindAllowed` uses, rather than
+ * defining the list a second time.
+ */
+export function isJudgeKind(value) {
+    return value === 'spec' || value === 'visual';
+}
+/** Read `judge_kind` back off a stored payload; anything else (absent, legacy) is "no kind". */
+function kindField(payload) {
+    return isJudgeKind(payload.judge_kind) ? payload.judge_kind : null;
+}
+/**
+ * `kind` is uiux-only. Any other role naming one is almost certainly a
+ * copy-pasted uiux command, not a real second turn — allowing it would let a
+ * reviewer open two turns under two kinds that nothing ever disambiguates
+ * back (every reader keys on role alone for the other five judges).
+ */
+function assertKindAllowed(role, kind) {
+    if (kind === undefined)
+        return;
+    if (!isJudgeKind(kind)) {
+        throw new JudgeError('judges.invalid-kind', `"kind" must be "spec" or "visual"; got ${JSON.stringify(kind)}.`, { kind });
+    }
+    if (role !== UIUX_ROLE) {
+        throw new JudgeError('judges.kind-not-allowed', `"--kind" only applies to the "${UIUX_ROLE}" role, the only one that opens more than one turn per task; "${role}" opens one turn and takes no kind.`, { agent_role: role, kind });
+    }
+}
 /**
  * The turn a record belongs to, tolerating the two spellings of one task id.
  *
@@ -78,8 +140,8 @@ const ATTESTED_BY = 'operator';
  * exactly the same ambiguity. Leaving both outstanding blocks the gate, and
  * the operator's remedy is to qualify the id.
  */
-function findTurn(turns, taskId, role) {
-    const matching = turns.filter((t) => t.role === role && taskIdsMatch(t.taskId, taskId));
+function findTurn(turns, taskId, role, kind) {
+    const matching = turns.filter((t) => t.role === role && t.kind === kind && taskIdsMatch(t.taskId, taskId));
     return matching.length === 1 ? matching[0] : undefined;
 }
 function stringField(payload, field) {
@@ -123,10 +185,20 @@ export function foldJudgeTurns(events, taskId) {
         const round = numberField(record.payload, 'round');
         // No declared artifact, no report owed: this is a coder or a merger, not
         // a judge. `round` is required alongside it, so a half-formed payload is
-        // ignored rather than folded into a turn nobody can ever close.
+        // ignored rather than folded into a turn nobody can ever close. Nor does
+        // a role outside JUDGE_TURN_ROLE_SET open one — a non-judge dispatch that
+        // accidentally carries both fields is still not a judge (see the set's
+        // own comment).
         if (role === undefined || declaredArtifact === undefined || round === undefined)
             continue;
-        const existing = findTurn(turns, recordTaskId, role);
+        if (!JUDGE_TURN_ROLE_SET.has(role))
+            continue;
+        const kind = kindField(record.payload);
+        const dispatchedAt = record.ts;
+        const artifactMtimeAtDispatch = typeof record.payload.artifact_mtime_at_dispatch === 'number'
+            ? record.payload.artifact_mtime_at_dispatch
+            : null;
+        const existing = findTurn(turns, recordTaskId, role, kind);
         if (existing !== undefined) {
             if (existing.round > round)
                 continue;
@@ -138,16 +210,21 @@ export function foldJudgeTurns(events, taskId) {
             existing.reported = false;
             existing.reportedArtifact = null;
             existing.attested = false;
+            existing.dispatchedAt = dispatchedAt;
+            existing.artifactMtimeAtDispatch = artifactMtimeAtDispatch;
             continue;
         }
         turns.push({
             taskId: recordTaskId,
             role,
+            kind,
             round,
             declaredArtifact,
             reported: false,
             reportedArtifact: null,
             attested: false,
+            dispatchedAt,
+            artifactMtimeAtDispatch,
         });
     }
     for (const { record } of events) {
@@ -161,7 +238,8 @@ export function foldJudgeTurns(events, taskId) {
         const role = stringField(record.payload, 'agent_role');
         if (role === undefined)
             continue;
-        const turn = findTurn(turns, recordTaskId, role);
+        const kind = kindField(record.payload);
+        const turn = findTurn(turns, recordTaskId, role, kind);
         if (turn === undefined || turn.round !== numberField(record.payload, 'round'))
             continue;
         turn.reported = true;
@@ -204,6 +282,27 @@ async function emit(eventType, payload, taskId, ctx, opts) {
         payload,
     }, opts);
 }
+/**
+ * Who dispatched this session, read off the event graph -- the answer a
+ * `dispatch_decision` written with no explicit `--actor` wants before it
+ * falls back to `system` (issue #218).
+ *
+ * `smith judge dispatch` runs inside a wave-runner's own delegated session,
+ * and the CLI does not thread an `--actor` through that call. Defaulting to
+ * `system` was a placeholder, not a real writer, and `delegation.ts`'s rule 3
+ * reads every `dispatch_decision` in a delegated session as a second author
+ * unless its `actor` names the role that session belongs to. `sessionOwnerRole`
+ * is the same lookup rule 3 already does when it decides whose session this
+ * is, so a judge dispatch recorded through this default and a dispatch a
+ * wave-runner writes itself land under the same actor -- there is nothing
+ * left for rule 3 to flag. A session nothing dispatched (or a P9-7
+ * continuation, which is not delegation) still falls through to `system`
+ * unchanged, exactly as before.
+ */
+async function delegatedActor(sessionId, opts) {
+    const events = await readLineageEvents(sessionId, opts);
+    return sessionOwnerRole(events, sessionId) ?? undefined;
+}
 /**
  * Record that a judge was dispatched and what file it owes. Emitted by the
  * dispatcher BEFORE the agent runs — a dispatch recorded afterwards could only
@@ -211,18 +310,48 @@ async function emit(eventType, payload, taskId, ctx, opts) {
  * problem.
  */
 export async function recordJudgeDispatch(input, ctx, opts = {}) {
+    // Caught here, ahead of the taxonomy check `emit` runs below, so a role
+    // that IS a valid taxonomy agent but not a judge (a coder dispatch that
+    // copy-pasted a judge dispatch command, say) gets a message that names the
+    // real problem instead of passing taxonomy validation and opening a turn
+    // `judge report` can never close.
+    if (!JUDGE_TURN_ROLE_SET.has(input.role)) {
+        throw new JudgeError('judges.non-judge-role', `"${input.role}" is not a judge role; only ${JUDGE_TURN_ROLES.join(', ')} can open a judge turn.`, { task_id: input.taskId, agent_role: input.role });
+    }
+    assertKindAllowed(input.role, input.kind);
+    // A kindless uiux dispatch folds into a `kind: null` turn the uiux gate never
+    // reads, so a pass reported against it blocks forever. Reads of old logs
+    // still fold such turns; only a new write is refused.
+    if (input.role === UIUX_ROLE && input.kind === undefined) {
+        throw new JudgeError('judges.kind-required', `A "${UIUX_ROLE}" dispatch must name its turn: "--kind spec" for the pre-code spec, "--kind visual" for the post-test visual pass.`, { task_id: input.taskId, agent_role: input.role });
+    }
     if (!Number.isInteger(input.round) || input.round < 1) {
         throw new JudgeError('judges.invalid-round', `Judge rounds are 1-based integers; got ${JSON.stringify(input.round)}.`, { round: input.round, task_id: input.taskId, agent_role: input.role });
     }
     if (input.artifactPath.trim() === '') {
         throw new JudgeError('judges.no-declared-artifact', 'A judge dispatch must declare the artifact it will write — that path is the finish line.', { task_id: input.taskId, agent_role: input.role });
     }
+    // The dispatch guard and judge-stop both read an absolute path only; a
+    // relative one would be a finish line no hook can check.
+    if (!path.isAbsolute(input.artifactPath)) {
+        throw new JudgeError('judges.artifact-not-absolute', `The declared artifact "${input.artifactPath}" is not an absolute path; pass an absolute one.`, { task_id: input.taskId, agent_role: input.role });
+    }
+    // Both hooks parse the `Declared artifact:` line as one run of non-space
+    // characters, so a path with whitespace would print an expected_line the
+    // dispatch guard then refuses as missing.
+    if (/\s/.test(input.artifactPath)) {
+        throw new JudgeError('judges.artifact-has-whitespace', `The declared artifact "${input.artifactPath}" contains whitespace, which the "Declared artifact:" line cannot carry; pick a path without it.`, { task_id: input.taskId, agent_role: input.role });
+    }
     // appendEvent would reject this too, on taxonomy grounds. Caught here anyway,
     // so the message names the judge that was about to be dispatched instead of
     // the record type that failed validation.
     if (typeof input.model !== 'string' || input.model.trim() === '') {
         throw new JudgeError('judges.no-model', `A judge dispatch must name the model it runs on: "${input.role}" is checked against the finder it followed by model id, not by tier (P9-23).`, { task_id: input.taskId, agent_role: input.role });
     }
+    // Explicit `--actor` is authoritative and skips this lookup entirely; only
+    // an absent actor reaches for the delegated session's owner.
+    const actor = ctx.actor ?? (await delegatedActor(ctx.sessionId, opts));
+    const priorMtime = artifactMtime(input.artifactPath);
     return emit(JUDGE_DISPATCH_EVENT_TYPE, {
         agent_role: input.role,
         provider: input.provider ?? DEFAULT_PROVIDER,
@@ -230,7 +359,71 @@ export async function recordJudgeDispatch(input, ctx, opts = {}) {
         model: input.model,
         round: input.round,
         declared_artifact: input.artifactPath,
-    }, input.taskId, ctx, opts);
+        ...(priorMtime === null ? {} : { artifact_mtime_at_dispatch: priorMtime }),
+        ...(input.kind ? { judge_kind: input.kind } : {}),
+    }, input.taskId, { ...ctx, actor }, opts);
+}
+/** The file's mtime in epoch ms, or null when there is no file to date. */
+function artifactMtime(artifactPath) {
+    try {
+        return statSync(artifactPath).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * How far a fresh artifact's mtime may sit BEHIND its dispatch's `ts` and
+ * still count as written during the turn.
+ *
+ * Not zero, because the two stamps come from two clocks. `ts` is
+ * `Date.now()`; a file's mtime on Linux is taken from the kernel's coarse
+ * clock, which lags the real-time one by up to a scheduler tick (4 ms at the
+ * common HZ=250, 10 ms at HZ=100). A judge that answers inside one tick of
+ * its dispatch — a test, or a `[]` written back by a scripted run — would
+ * otherwise read as stale. Fifty milliseconds covers the tick with margin and
+ * reopens nothing the check exists for: the artifacts it refuses are an
+ * earlier round's, minutes to days old, and a file that existed at dispatch
+ * is refused by `artifactMtimeAtDispatch` regardless of this window.
+ */
+const ARTIFACT_CLOCK_TOLERANCE_MS = 50;
+/**
+ * Refuse an artifact that was not written during this turn (issue #249).
+ *
+ * Two ways to be stale, one code, because the remedy is the same — the judge
+ * did not report this round; re-run it:
+ *
+ *   - its mtime is not later than the dispatch that opened the round, so the
+ *     file is an earlier round's, or a placeholder left behind;
+ *   - it is the declared file, it was already there at dispatch, and its mtime
+ *     has not moved since — nothing rewrote it, whatever the clock says.
+ *     This is what catches a file dated in the future.
+ *
+ * Only the declared path is compared against the at-dispatch mtime: that is
+ * the only file whose mtime the dispatch recorded. An explicit `--artifact`
+ * (or `gate run --evidence`) elsewhere still has to postdate the dispatch.
+ */
+function assertArtifactFresh(artifactPath, turn) {
+    const mtime = artifactMtime(artifactPath);
+    // Missing is `readJudgeArtifact`'s refusal to make, with its own code.
+    if (mtime === null)
+        return;
+    const dispatchedMs = Date.parse(turn.dispatchedAt);
+    const context = {
+        artifact_path: artifactPath,
+        artifact_mtime: new Date(mtime).toISOString(),
+        dispatched_at: turn.dispatchedAt,
+        agent_role: turn.role,
+        round: turn.round,
+    };
+    if (mtime <= dispatchedMs - ARTIFACT_CLOCK_TOLERANCE_MS) {
+        throw new JudgeError('judges.artifact-stale', `Judge artifact "${artifactPath}" was last written at ${context.artifact_mtime}, before round ${turn.round} of "${turn.role}" was dispatched at ${turn.dispatchedAt}. It is an earlier round's file or a placeholder, not this turn's report; re-run the judge.`, context);
+    }
+    if (turn.artifactMtimeAtDispatch !== null &&
+        mtime === turn.artifactMtimeAtDispatch &&
+        path.resolve(artifactPath) === path.resolve(turn.declaredArtifact)) {
+        throw new JudgeError('judges.artifact-stale', `Judge artifact "${artifactPath}" already existed when round ${turn.round} of "${turn.role}" was dispatched, and nothing has rewritten it since. The judge did not report this round; re-run it.`, { ...context, artifact_mtime_at_dispatch: turn.artifactMtimeAtDispatch });
+    }
 }
 /** The one judge whose artifact is a verdict document rather than a findings list. */
 const GRADER_ROLE = 'grader';
@@ -262,6 +455,143 @@ function graderFindingCount(parsed) {
         return undefined;
     return criteria.filter((c) => !(typeof c === 'object' && c !== null && c.status === 'pass')).length;
 }
+/**
+ * Count what a uiux result document holds, for the turn `kind` it closes.
+ *
+ * uiux's declared artifact is always the Result object `{run_status,
+ * structured_output, artifacts}` (bs-uiux.md), never a findings-evidence array —
+ * the bug this slice fixes is exactly that `readJudgeArtifact` used to throw
+ * on this real shape. A pre-code spec names no findings of its own (its
+ * `structured_output.deviations` are design-token departures the spec itself
+ * chose, not something to count against the task), so a `spec` turn is
+ * always 0. A post-test visual pass's `structured_output.deviations` IS the
+ * findings list — one entry per screenshot departure from the spec — so a
+ * `visual` turn counts them. `kind === null` is a legacy uiux turn dispatched
+ * before this slice; it has no way to say which shape it is, so it is read
+ * the lenient way — a real `deviations` array still counts, anything else is
+ * the pre-existing 0.
+ */
+function uiuxFindingCount(parsed, kind) {
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return undefined;
+    // A spec turn's own `structured_output.deviations` are design-token
+    // departures the spec itself chose, never findings against the task, so a
+    // spec turn is always 0 regardless of what that array holds.
+    if (kind === 'spec')
+        return 0;
+    const document = parsed;
+    const structured = document.structured_output;
+    const deviations = typeof structured === 'object' && structured !== null
+        ? structured.deviations
+        : undefined;
+    if (Array.isArray(deviations))
+        return deviations.length;
+    if (kind === 'visual')
+        return undefined;
+    return 0;
+}
+/**
+ * Map a uiux visual pass's deviations onto the findings-evidence shape `gate
+ * run --evidence` already feeds `mintFindings` (`FindingEvidence`,
+ * findings.ts:454; schema factory/specs/schema/finding-evidence.schema.json).
+ * `dimension: 'accessibility'` is the `a11y` taxonomy category; every other
+ * dimension (layout_spacing, consistency, states) is a `visual-design`
+ * departure from the spec, not an accessibility one.
+ */
+export function uiuxDeviationsToEvidence(deviations) {
+    return deviations.map((deviation) => ({
+        file_path: deviation.screenshot,
+        finding_category: deviation.dimension === 'accessibility' ? 'a11y' : 'visual-design',
+        severity: deviation.severity,
+        summary: `${deviation.dimension} deviation at ${deviation.viewport}/${deviation.theme}: ${deviation.expected}`,
+        failure_scenario: {
+            inputs: `viewport=${deviation.viewport} theme=${deviation.theme}`,
+            expected: deviation.expected,
+            actual: deviation.observed,
+        },
+    }));
+}
+let cachedTaxonomyForSchemas;
+let cachedSchemas;
+/**
+ * Schemas only — no taxonomy is read on this path, unlike the `{taxonomy,
+ * schemas}` pair `events.ts`/`findings.ts` each resolve for themselves.
+ * `compileSchemas` still takes a taxonomy argument (it needs one to compile
+ * at all), so one is loaded and cached to satisfy that, but nothing here ever
+ * reads it back out.
+ */
+function resolveSchemas(opts) {
+    if (opts.schemas)
+        return opts.schemas;
+    if (cachedSchemas === undefined) {
+        if (cachedTaxonomyForSchemas === undefined)
+            cachedTaxonomyForSchemas = loadTaxonomy();
+        cachedSchemas = compileSchemas(cachedTaxonomyForSchemas);
+    }
+    return cachedSchemas;
+}
+function describeShapeFailures(failures) {
+    return failures
+        .map((f) => `index ${f.index} (${f.errors.map((e) => e.message).join('; ')})`)
+        .join(', ');
+}
+/**
+ * Whether `role`'s array-shaped artifact, on this `taskId`, is finding-
+ * evidence and should be schema-checked. An allow-list, not a blanket check
+ * minus exceptions — each entry below was confirmed against the role's own
+ * output contract (`.claude/agents/*.md`) and, for `judge dispatch`/`judge
+ * report` specifically, `.claude/skills/bs/wave.md`'s list of the judges that
+ * bracket ("uiux visual pass, grader, reviewer, verifier, security-reviewer").
+ *
+ * - `reviewer` (bs-reviewer.md): its whole array is exactly the five
+ *   finding-evidence keys.
+ * - `security-reviewer` (bs-security-reviewer.md): its per-task array is the
+ *   same five keys as `reviewer`'s. Its OTHER artifact — the security axis of
+ *   `/bs audit` — carries a sixth key, `confidence`, and drops
+ *   `finding_category`, which `additionalProperties: false` rejects; that
+ *   shape is validated on its own terms by `smith audit record`, not this
+ *   schema. The two are told apart by `taskId`, not by role alone — an
+ *   ordinary per-task security review has no other way to distinguish
+ *   itself, and leaving the role exempt everywhere (as before) left real
+ *   per-task security findings unvalidated.
+ * - `GRADER_ROLE`: its declared artifact is a verdict OBJECT, handled by
+ *   `graderFindingCount` below and never reaching this check. But `gate run
+ *   --evidence <file> --found-by grader` (FD-1) can also close a grader turn
+ *   with an ordinary finding-evidence ARRAY, distinct from the `--grader
+ *   <file>` verdict-document path, so the role belongs here for that case.
+ *
+ * Every other role keeps the old count-only behaviour:
+ * - `verifier` (bs-verifier.md) reports `{finding_id, verdict, rationale,
+ *   failure_scenario}` — echoing a finding back rather than describing a
+ *   fresh one — a different, and never finding-evidence, shape by design.
+ * - `uiux` (bs-uiux.md): its artifact is always the OBJECT `{run_status,
+ *   structured_output, artifacts}`, never an array, so this check never
+ *   applies to it regardless of allow-listing.
+ * - `auditor`: the other three audit axes, the same AuditEvidenceItem shape
+ *   as security-reviewer's audit path — but auditor never reviews a single
+ *   task (bs-auditor.md: "never per-task, never for a diff"), so there is no
+ *   taskId to gate on; it stays exempt unconditionally.
+ * - `spec-reviewer` (bs-spec-reviewer.md): not on the list. Neither of its two
+ *   array artifacts — the pre-code/close spec review (finding-evidence
+ *   shaped) and the spec-vs-goal coverage check (`{clause, verdict,
+ *   taskIds?, reason?}`, not finding-evidence shaped) — currently reaches
+ *   this function at all: `smith epic spec-review`/`smith epic goal-check`
+ *   read them directly (cli.ts), never through `judge report`, and
+ *   wave.md's judge-dispatch/report roster does not name spec-reviewer.
+ *   Allow-listing the role here would be inert today and, because its two
+ *   artifacts disagree on shape with no taskId to tell them apart the way
+ *   security-reviewer's two are told apart, a latent wrong-rejection the day
+ *   something does route the goal-coverage array through this same role
+ *   string.
+ * - anything this taxonomy does not yet name.
+ */
+function validatesFindingEvidence(role, taskId) {
+    if (role === 'reviewer' || role === GRADER_ROLE)
+        return true;
+    if (role === 'security-reviewer')
+        return !isAuditAxisTaskId(taskId);
+    return false;
+}
 /**
  * Read a judge's artifact and answer how many findings it holds.
  *
@@ -277,8 +607,19 @@ function graderFindingCount(parsed) {
  * the grader result document is accepted beside the list, and the count is
  * its non-pass criteria. No other role gets that reading — a reviewer that
  * wrote a verdict wrote the wrong shape.
+ *
+ * A findings-evidence array is schema-validated element-wise before it is
+ * even counted (issue #233), but only for the roles `validatesFindingEvidence`
+ * names: a malformed array used to close the turn on a finding_count that
+ * `mintFindings` would later crash trying to mint from the same file, since
+ * `findings raise --evidence`/`gate run --evidence` read the identical
+ * artifact. Reusing `finding-evidence.schema.json` here keeps the two intake
+ * paths agreeing on what "malformed" means, for the roles that actually write
+ * that shape — a role whose real artifact is something else (verifier, an
+ * audit axis) is not "malformed" for failing to look like a finding. An empty
+ * array has nothing to validate, so `[]` still passes.
  */
-export function readJudgeArtifact(artifactPath, role) {
+export function readJudgeArtifact(artifactPath, role, taskId, kind = null, opts = {}) {
     let raw;
     try {
         raw = readFileSync(artifactPath, 'utf8');
@@ -293,19 +634,53 @@ export function readJudgeArtifact(artifactPath, role) {
     catch (err) {
         throw new JudgeError('judges.artifact-unparseable', `Judge artifact "${artifactPath}" is not JSON. Prose in the artifact slot is the wave-4 failure exactly: fluent text that reads like a verdict and is not one.`, { artifact_path: artifactPath, cause: err instanceof Error ? err.message : String(err) });
     }
-    if (Array.isArray(parsed))
+    if (Array.isArray(parsed)) {
+        // Only the roles `validatesFindingEvidence` names actually write a
+        // finding-evidence array; skipping the check for every other role does
+        // not weaken issue #233's guarantee — anything that reaches
+        // `mintFindings` is still validated in full before it is minted,
+        // regardless of role.
+        if (validatesFindingEvidence(role, taskId)) {
+            const failures = validateEachShape(resolveSchemas(opts), 'finding-evidence', parsed);
+            if (failures.length > 0) {
+                throw new JudgeError('judges.artifact-invalid-evidence', `Judge artifact "${artifactPath}" holds ${failures.length} item(s) that do not match finding-evidence.schema.json at ${describeShapeFailures(failures)}. Expected {file_path, finding_category, severity, summary, failure_scenario: {inputs, expected, actual}} (criterion_ref optional).`, { artifact_path: artifactPath, failures });
+            }
+        }
         return parsed.length;
+    }
     const graderCount = role === GRADER_ROLE ? graderFindingCount(parsed) : undefined;
     if (graderCount !== undefined)
         return graderCount;
+    if (role === UIUX_ROLE) {
+        const uiuxCount = uiuxFindingCount(parsed, kind);
+        if (uiuxCount !== undefined)
+            return uiuxCount;
+        if (kind === 'visual') {
+            throw new JudgeError('judges.artifact-invalid-evidence', `Judge artifact "${artifactPath}" is a uiux visual-pass result with no structured_output.deviations array. A visual pass reports its deviations, "[]" when it found none.`, { artifact_path: artifactPath });
+        }
+    }
     const accepted = role === GRADER_ROLE
         ? 'a findings-evidence array or the grader result document ({run_status, structured_output: {criteria: [...]}})'
-        : 'a findings-evidence array';
+        : role === UIUX_ROLE
+            ? 'the uiux result document ({run_status, structured_output: {...}})'
+            : 'a findings-evidence array';
     throw new JudgeError('judges.artifact-not-a-list', `Judge artifact "${artifactPath}" parsed to ${parsed === null ? 'null' : typeof parsed}, not ${accepted}. An empty review is "[]", written out.`, { artifact_path: artifactPath, agent_role: role ?? null });
 }
-function notDispatchedMessage(input, turn, forRole) {
-    if (forRole.length > 1) {
-        return `Task id "${input.taskId}" names a "${input.role}" turn in ${forRole.length} epics (${forRole.map((t) => t.taskId).join(', ')}). Report against the qualified id — closing one of them here would be a guess.`;
+function notDispatchedMessage(input, turn, forRole, kindAmbiguous) {
+    if (kindAmbiguous.length > 1) {
+        const kinds = kindAmbiguous.map((t) => t.kind ?? 'null').join(', ');
+        if (kindAmbiguous.every((t) => t.reported)) {
+            return `Task id "${input.taskId}" has ${kindAmbiguous.length} "${input.role}" turns (kinds: ${kinds}), all already reported. Report with "--kind" naming the one to re-report — picking one here would be a guess.`;
+        }
+        return `Task id "${input.taskId}" has ${kindAmbiguous.length} open "${input.role}" turns (kinds: ${kinds}). Report with "--kind" naming the one to close — closing one here would be a guess.`;
+    }
+    const distinctTaskIds = new Set(forRole.map((t) => t.taskId));
+    if (distinctTaskIds.size > 1) {
+        return `Task id "${input.taskId}" names a "${input.role}" turn in ${distinctTaskIds.size} epics (${forRole.map((t) => t.taskId).join(', ')}). Report against the qualified id — closing one of them here would be a guess.`;
+    }
+    if (turn === undefined && input.kind !== undefined && forRole.length > 0) {
+        const kinds = forRole.map((t) => t.kind ?? 'null').join(', ');
+        return `No "${input.kind}" ${input.role} dispatch on ${input.taskId} (dispatched kinds: ${kinds}). Dispatch it with "--kind ${input.kind}" first, or report against a kind that was dispatched.`;
     }
     if (turn === undefined) {
         return `No judge dispatch for role "${input.role}" on ${input.taskId}. Record the dispatch first — a report with no dispatch behind it proves nothing about coverage.`;
@@ -318,27 +693,49 @@ function notDispatchedMessage(input, turn, forRole) {
  * the two sets agree by growing both.
  */
 export async function recordJudgeReport(input, ctx, opts = {}) {
+    assertKindAllowed(input.role, input.kind);
+    const kind = input.kind ?? null;
     const turns = await readJudgeTurns(input.taskId, ctx, opts);
-    const forRole = turns.filter((t) => t.role === input.role);
-    // More than one is a bare id that two epics both claim a turn for. Closing
-    // either would be a guess, and `foldJudgeTurns` refuses the same ambiguity,
-    // so the report emitted here would close nothing on the next read anyway.
-    const turn = forRole.length === 1 ? forRole[0] : undefined;
+    const forRole = turns.filter((t) => t.role === input.role && taskIdsMatch(t.taskId, input.taskId));
+    // More than one distinct task id among same-role turns is a bare id that
+    // two epics both claim a turn for. More than one turn on the SAME task id
+    // (same role, same taskId) is the uiux spec/visual pair, disambiguated by
+    // `kind` instead — both cases are a guess to resolve on our own.
+    const distinctTaskIds = new Set(forRole.map((t) => t.taskId));
+    const epicAmbiguous = distinctTaskIds.size > 1;
+    // A kindless report picks among OPEN turns only, the same set
+    // `outstandingJudges` exposes — a closed turn is not a candidate to guess
+    // between, and the error must not count it as "open" either. With no turn
+    // open, every turn is a candidate again: one is a legacy re-report, two is
+    // the same guess, and must not silently re-report the first.
+    const openForRole = forRole.filter((t) => !t.reported);
+    const candidates = openForRole.length > 0 ? openForRole : forRole;
+    const kindAmbiguous = !epicAmbiguous && kind === null && candidates.length > 1;
+    const turn = epicAmbiguous || kindAmbiguous
+        ? undefined
+        : kind === null
+            ? candidates[0]
+            : forRole.find((t) => t.kind === kind);
     if (turn === undefined || (input.round !== undefined && input.round !== turn.round)) {
-        throw new JudgeError('judges.not-dispatched', notDispatchedMessage(input, turn, forRole), {
+        throw new JudgeError('judges.not-dispatched', notDispatchedMessage(input, turn, forRole, kindAmbiguous ? candidates : []), {
             task_id: input.taskId,
             agent_role: input.role,
             round: input.round ?? null,
         });
     }
     const artifactPath = input.noFindings ? null : (input.artifactPath ?? turn.declaredArtifact);
-    const findingCount = artifactPath === null ? 0 : readJudgeArtifact(artifactPath, input.role);
-    await emit(JUDGE_REPORT_EVENT_TYPE, {
+    if (artifactPath !== null)
+        assertArtifactFresh(artifactPath, turn);
+    const findingCount = artifactPath === null
+        ? 0
+        : readJudgeArtifact(artifactPath, input.role, input.taskId, turn.kind, opts);
+    const stored = await emit(JUDGE_REPORT_EVENT_TYPE, {
         agent_role: input.role,
         round: turn.round,
         artifact_path: artifactPath,
         finding_count: findingCount,
         ...(input.noFindings ? { attested_by: ATTESTED_BY } : {}),
+        ...(turn.kind ? { judge_kind: turn.kind } : {}),
     }, input.taskId, ctx, opts);
     return {
         taskId: input.taskId,
@@ -347,5 +744,6 @@ export async function recordJudgeReport(input, ctx, opts = {}) {
         artifactPath,
         findingCount,
         attested: input.noFindings === true,
+        event_id: stored.event_id,
     };
 }