@pellux/goodvibes-agent 1.1.6 → 1.2.0

package/src/tools/agent-harness-delegation-posture.ts

@@ -21,6 +21,13 @@ interface DelegationRoute {
   readonly label: string;
   readonly detail: string;
   readonly effect: 'read-only' | 'main-conversation' | 'delegated-work' | 'blocked';
+  readonly lane?: DelegationLaneId;
+  readonly bestFor?: readonly string[];
+  readonly requiredFields?: readonly string[];
+  readonly optionalFields?: readonly string[];
+  readonly successEvidence?: readonly string[];
+  readonly statusRoutes?: readonly string[];
+  readonly recoveryRoutes?: readonly string[];
   readonly command?: string;
   readonly commandTemplate?: string;
   readonly workspaceActionId?: string;
@@ -28,6 +35,27 @@ interface DelegationRoute {
   readonly reviewPolicy?: 'explicit-only' | 'not-applicable';
 }
 
+type DelegationLaneId =
+  | 'local-first'
+  | 'tui-shared-session'
+  | 'delegated-review'
+  | 'remote-runner'
+  | 'hidden-fanout-blocked';
+
+interface DelegationDecisionCard {
+  readonly id: string;
+  readonly lane: DelegationLaneId;
+  readonly label: string;
+  readonly status: 'ready' | 'operator-needed' | 'blocked';
+  readonly userBenefit: string;
+  readonly chooseWhen: readonly string[];
+  readonly doNotUseWhen: readonly string[];
+  readonly routeIds: readonly string[];
+  readonly requiredFields: readonly string[];
+  readonly supervision: readonly string[];
+  readonly confirmationBoundary: string;
+}
+
 function readString(value: unknown): string {
   return typeof value === 'string' ? value.trim() : '';
 }
@@ -52,8 +80,20 @@ function routes(): readonly DelegationRoute[] {
     {
       id: 'delegate-build-task',
       label: 'Delegate build/fix/review task',
-      detail: 'Send one explicit build, fix, implementation, patch, or review task to GoodVibes TUI/shared-session routes with the full original ask.',
+      detail: 'Send one explicit build, fix, implementation, patch, or review task to GoodVibes TUI/shared-session routes when isolation, remote execution, parallelism, a separate coding UI, or user-requested handoff is useful.',
       effect: 'delegated-work',
+      lane: 'tui-shared-session',
+      bestFor: [
+        'Separate coding UI',
+        'Isolation or separate worktree ownership',
+        'Remote execution handled by the GoodVibes host or TUI',
+        'Parallel implementation or verification that should not block the main Agent conversation',
+      ],
+      requiredFields: ['full original user ask', 'delegation reason', 'success criteria or expected evidence'],
+      optionalFields: ['workspace/worktree hint', 'deadline/priority', 'review requested yes/no'],
+      successEvidence: ['delegation receipt/session id', 'status update', 'diff or artifact summary', 'verification result when available'],
+      statusRoutes: ['/delegate status', '/health remote', 'delegation action:"status"'],
+      recoveryRoutes: ['Open GoodVibes TUI shared session', 'Use local Agent read/edit/exec when the current workspace is sufficient'],
       commandTemplate: '/delegate <full original user ask>',
       workspaceActionId: 'delegate-task',
       confirmationRequired: true,
@@ -62,8 +102,19 @@ function routes(): readonly DelegationRoute[] {
     {
       id: 'delegate-build-task-with-review',
       label: 'Delegate with requested review',
-      detail: 'Request delegated review only when the user explicitly asks for review or explicitly requests review as part of a build/fix/review handoff.',
+      detail: 'Request delegated review only when the user explicitly asks for review or explicitly requests review as part of an isolated or remote build/fix/review handoff.',
       effect: 'delegated-work',
+      lane: 'delegated-review',
+      bestFor: [
+        'User explicitly asks for code review',
+        'Implementation handoff needs an independent review owner',
+        'Risky change needs WRFC-style evidence before merge/apply decisions',
+      ],
+      requiredFields: ['full original user ask', 'explicit review request', 'review focus', 'success criteria or expected evidence'],
+      optionalFields: ['files/components in scope', 'known risks', 'deadline/priority'],
+      successEvidence: ['review receipt/session id', 'findings or approval summary', 'artifact/diff references', 'follow-up questions when blocked'],
+      statusRoutes: ['/delegate status', '/health remote', 'delegation action:"route" delegationRouteId:"delegate-build-task-with-review"'],
+      recoveryRoutes: ['Use local Agent review when the current workspace is sufficient', 'Open GoodVibes TUI shared session for review follow-up'],
       commandTemplate: '/delegate --review <full original user ask>',
       workspaceActionId: 'delegate-task',
       confirmationRequired: true,
@@ -74,6 +125,13 @@ function routes(): readonly DelegationRoute[] {
       label: 'Delegation status',
       detail: 'Inspect build-delegation receipts and shared-session status without starting coding work.',
       effect: 'read-only',
+      lane: 'tui-shared-session',
+      bestFor: ['Checking whether a delegated build/fix/review task was submitted', 'Finding the shared-session receipt before follow-up'],
+      requiredFields: [],
+      optionalFields: ['session id or task text when available'],
+      successEvidence: ['receipt/session id', 'latest shared-session status'],
+      statusRoutes: ['/delegate status'],
+      recoveryRoutes: ['/health remote', 'Open GoodVibes TUI in the target workspace'],
       command: '/delegate status',
       workspaceActionId: 'delegation-status',
       reviewPolicy: 'not-applicable',
@@ -81,30 +139,178 @@ function routes(): readonly DelegationRoute[] {
     {
       id: 'ordinary-agent-work',
       label: 'Ordinary Agent work',
-      detail: 'Planning, research, operations, memory, configuration, approvals, automation observability, media generation, and ordinary assistant work stay in the main Agent conversation or first-class Agent tools.',
+      detail: 'Planning, research, operations, memory, configuration, approvals, automation observability, media generation, and ordinary local read/edit/exec work stay in the main Agent conversation or first-class Agent tools.',
+      effect: 'main-conversation',
+      lane: 'local-first',
+      bestFor: ['Normal chat', 'Planning and research', 'Current-workspace implementation or verification with available local tools'],
+      requiredFields: [],
+      optionalFields: ['work plan item', 'verification command', 'user-visible success criteria'],
+      successEvidence: ['direct answer', 'local diff', 'test result', 'artifact id when an Agent tool saves one'],
+      statusRoutes: ['main conversation', 'execution action:"status"', 'execution action:"history"'],
+      recoveryRoutes: ['execution action:"recovery"', 'execution action:"route" id:"local-edit-write"'],
+      reviewPolicy: 'not-applicable',
+    },
+    {
+      id: 'local-agent-execution',
+      label: 'Local Agent execution',
+      detail: 'Agent may use local read, edit, analyze, fetch, and bounded foreground shell tools when the current workspace and permissions are sufficient for the user request.',
       effect: 'main-conversation',
+      lane: 'local-first',
+      bestFor: ['Current workspace code changes', 'Targeted tests/builds', 'Foreground command verification', 'Direct file recovery through Agent snapshots'],
+      requiredFields: ['user request or task objective'],
+      optionalFields: ['files/components in scope', 'verification command', 'risk notes'],
+      successEvidence: ['changed files', 'command/test output', 'execution history record', 'file recovery snapshot when edits were made'],
+      statusRoutes: ['execution action:"history"', 'execution action:"route" id:"local-shell-command"'],
+      recoveryRoutes: ['execution action:"recovery"', 'agent_harness mode:"run_file_recovery"'],
       reviewPolicy: 'not-applicable',
     },
     {
-      id: 'local-coding-blocked',
-      label: 'Local coding execution blocked in Agent',
-      detail: 'Agent does not own file edits, git/worktree workflows, execution isolation UX, coding panels, or local delegated review chains.',
+      id: 'remote-runner-inspection',
+      label: 'Remote runner inspection',
+      detail: 'Inspect GoodVibes remote build-host pools, contracts, artifacts, and review summaries when the host exposes them; mutation-heavy remote pool assignment and artifact import are not Agent-owned actions.',
+      effect: 'read-only',
+      lane: 'remote-runner',
+      bestFor: ['Checking remote build-host health', 'Reviewing runner contracts', 'Reviewing remote artifacts that already exist'],
+      requiredFields: [],
+      optionalFields: ['runner id', 'artifact id', 'pool id'],
+      successEvidence: ['remote health summary', 'runner contract summary', 'remote artifact review summary'],
+      statusRoutes: ['/health remote', 'remote tool read-only modes: pools, contracts, artifacts, review'],
+      recoveryRoutes: ['Repair remote build-host state outside Agent', 'Use /delegate for build/fix/review execution changes'],
+      command: '/health remote',
+      reviewPolicy: 'not-applicable',
+    },
+    {
+      id: 'hidden-local-fanout-blocked',
+      label: 'Hidden local fanout blocked',
+      detail: 'Do not spawn invisible local coding workers, background exec batches, or untracked parallel subagents from Agent. Convert the request into local serial work, a visible work plan, a research run, an explicit schedule, or confirmed GoodVibes TUI/shared-session delegation.',
       effect: 'blocked',
+      lane: 'hidden-fanout-blocked',
+      bestFor: ['Policy explanation when a request implies hidden background implementation work'],
+      requiredFields: [],
+      optionalFields: ['visible work-plan item', 'delegation reason', 'success criteria'],
+      successEvidence: ['chosen visible route', 'confirmation receipt when delegated'],
+      statusRoutes: ['execution action:"status"', 'autonomy action:"intake"'],
+      recoveryRoutes: ['delegation action:"status"', 'Agent Workspace -> Work plan'],
       reviewPolicy: 'not-applicable',
     },
   ];
 }
 
+export function delegationDecisionCards(context: CommandContext): readonly DelegationDecisionCard[] {
+  const operatorAttached = Boolean(context.clients?.operator);
+  return [
+    {
+      id: 'delegate-decision-local-first',
+      lane: 'local-first',
+      label: 'Keep it in Agent',
+      status: 'ready',
+      userBenefit: 'Fastest path for current-workspace work: no handoff, no duplicate context, direct verification and recovery.',
+      chooseWhen: [
+        'The current Agent workspace is the target.',
+        'Local read/edit/exec tools can complete and verify the work.',
+        'The user did not ask for a separate runner, worktree, or delegated review.',
+      ],
+      doNotUseWhen: [
+        'The work needs a remote machine, separate worktree, independent review owner, or parallel execution lane.',
+      ],
+      routeIds: ['ordinary-agent-work', 'local-agent-execution'],
+      requiredFields: ['task objective'],
+      supervision: ['execution action:"status"', 'execution action:"history"', 'execution action:"recovery"'],
+      confirmationBoundary: 'Use normal Agent tool confirmations; no shared-session delegation is submitted.',
+    },
+    {
+      id: 'delegate-decision-tui-handoff',
+      lane: 'tui-shared-session',
+      label: 'Delegate to GoodVibes TUI',
+      status: operatorAttached ? 'ready' : 'operator-needed',
+      userBenefit: 'Best route when the user benefits from the coding TUI, shared sessions, isolation, worktree ownership, or remote host workflows.',
+      chooseWhen: [
+        'The task is explicit build/fix/implementation/review work.',
+        'Delegation improves the user outcome versus staying local.',
+        'The full original ask, reason, and success criteria can be preserved.',
+      ],
+      doNotUseWhen: [
+        'The task is ordinary local work that Agent can complete directly.',
+        'The user has not confirmed a mutating delegation submission.',
+      ],
+      routeIds: ['delegate-build-task', 'delegation-status'],
+      requiredFields: ['full original user ask', 'delegation reason', 'success criteria or expected evidence'],
+      supervision: ['/delegate status', '/health remote', 'GoodVibes TUI shared session'],
+      confirmationBoundary: 'Submitting delegated work requires a confirmed workspace form or slash command and an attached operator client.',
+    },
+    {
+      id: 'delegate-decision-review',
+      lane: 'delegated-review',
+      label: 'Request delegated review',
+      status: operatorAttached ? 'ready' : 'operator-needed',
+      userBenefit: 'Adds an independent review owner only when the user explicitly asks for it or the handoff needs review as part of the task.',
+      chooseWhen: [
+        'The user asks for review, WRFC, second pass, or independent verification.',
+        'The delegated task has review focus and expected evidence.',
+      ],
+      doNotUseWhen: [
+        'Review is only implied by the existence of a handoff.',
+        'A local code review in the current workspace is sufficient.',
+      ],
+      routeIds: ['delegate-build-task-with-review', 'delegation-status'],
+      requiredFields: ['full original user ask', 'explicit review request', 'review focus', 'success criteria or expected evidence'],
+      supervision: ['/delegate status', 'GoodVibes TUI shared session'],
+      confirmationBoundary: 'The --review lane is explicit-only; Agent must not add review by default.',
+    },
+    {
+      id: 'delegate-decision-remote-inspect',
+      lane: 'remote-runner',
+      label: 'Inspect remote runners',
+      status: 'ready',
+      userBenefit: 'Keeps remote-host state understandable without exposing mutation-heavy pool or artifact operations through Agent.',
+      chooseWhen: [
+        'The user asks about remote build-host health, runner contracts, or existing remote artifacts.',
+      ],
+      doNotUseWhen: [
+        'The user asks Agent to create pools, assign runners, import artifacts, or dispatch hidden remote work.',
+      ],
+      routeIds: ['remote-runner-inspection'],
+      requiredFields: [],
+      supervision: ['/health remote', 'remote read-only tool modes: pools/contracts/artifacts/review'],
+      confirmationBoundary: 'Remote build-host mutation belongs outside Agent or through explicit GoodVibes TUI delegation.',
+    },
+    {
+      id: 'delegate-decision-hidden-fanout',
+      lane: 'hidden-fanout-blocked',
+      label: 'Block hidden fanout',
+      status: 'blocked',
+      userBenefit: 'Protects the user from invisible work, unclear ownership, unreviewed side effects, and orphaned background jobs.',
+      chooseWhen: [
+        'A request implies invisible local subagents, background exec batches, untracked remote dispatch, or unmanaged parallel coding workers.',
+      ],
+      doNotUseWhen: [
+        'The work can be expressed as a visible work plan, research run, schedule, local serial tool use, or confirmed delegation.',
+      ],
+      routeIds: ['hidden-local-fanout-blocked'],
+      requiredFields: [],
+      supervision: ['execution action:"status"', 'autonomy action:"intake"', 'work plan'],
+      confirmationBoundary: 'Hidden fanout is never confirmed from Agent; convert to a visible owned route.',
+    },
+  ];
+}
+
 function routeSearchText(route: DelegationRoute): string {
   return [
     route.id,
     route.label,
     route.detail,
     route.effect,
+    route.lane ?? '',
     route.command ?? '',
     route.commandTemplate ?? '',
     route.workspaceActionId ?? '',
     route.reviewPolicy ?? '',
+    ...(route.bestFor ?? []),
+    ...(route.requiredFields ?? []),
+    ...(route.optionalFields ?? []),
+    ...(route.successEvidence ?? []),
+    ...(route.statusRoutes ?? []),
+    ...(route.recoveryRoutes ?? []),
   ].join('\n').toLowerCase();
 }
 
@@ -113,15 +319,14 @@ function describeCandidate(route: DelegationRoute): Record<string, unknown> {
     delegationRouteId: route.id,
     label: route.label,
     effect: route.effect,
+    lane: route.lane ?? 'local-first',
     confirmationRequired: route.confirmationRequired === true,
     modelRoute: delegationRouteModelRoute(route),
   };
 }
 
 function delegationRouteModelRoute(route: DelegationRoute): string {
-  if (route.workspaceActionId) return 'agent_harness mode:"run_workspace_action"';
-  if (route.command || route.commandTemplate) return 'agent_harness mode:"run_command"';
-  return route.effect === 'main-conversation' ? 'main conversation' : 'agent_harness mode:"delegation_route"';
+  return route.effect === 'main-conversation' ? 'main conversation' : `delegation action:"route" id:"${route.id}"`;
 }
 
 function describeRoute(
@@ -134,6 +339,7 @@ function describeRoute(
     label: route.label,
     ...(options.includeParameters ? { detail: route.detail } : { summary: previewHarnessText(route.detail) }),
     effect: route.effect,
+    lane: route.lane ?? 'local-first',
     confirmationRequired: route.confirmationRequired === true,
     reviewPolicy: route.reviewPolicy ?? 'not-applicable',
     modelRoute: delegationRouteModelRoute(route),
@@ -145,6 +351,12 @@ function describeRoute(
       ...(route.command ? { command: route.command } : {}),
       ...(route.commandTemplate ? { commandTemplate: route.commandTemplate } : {}),
       ...(route.workspaceActionId ? { workspaceActionId: route.workspaceActionId } : {}),
+      bestFor: route.bestFor ?? [],
+      requiredFields: route.requiredFields ?? [],
+      optionalFields: route.optionalFields ?? [],
+      successEvidence: route.successEvidence ?? [],
+      statusRoutes: route.statusRoutes ?? [],
+      recoveryRoutes: route.recoveryRoutes ?? [],
     } : {}),
     ...(options.lookup ? { lookup: options.lookup } : {}),
     ...(options.includeParameters ? {
@@ -154,12 +366,12 @@ function describeRoute(
         mutation: 'Delegated work submission stays a visible confirmed workspace or slash-command flow and must preserve the full original user ask.',
       },
       modelAccess: {
-        inspectDelegation: 'agent_harness mode:"delegation_posture"',
-        inspectRoute: 'agent_harness mode:"delegation_route"',
-        workspaceAction: route.workspaceActionId ? `agent_harness mode:"workspace_action" actionId:"${route.workspaceActionId}"` : null,
-        runWorkspaceAction: route.workspaceActionId ? `agent_harness mode:"run_workspace_action" actionId:"${route.workspaceActionId}" confirm:true explicitUserRequest:"..."` : null,
-        runCommand: route.command ? `agent_harness mode:"run_command" command:"${route.command}" confirm:true explicitUserRequest:"..."` : null,
-        runCommandTemplate: route.commandTemplate ? `agent_harness mode:"run_command" command:"${route.commandTemplate}" confirm:true explicitUserRequest:"..."` : null,
+        inspectDelegation: 'delegation action:"status"',
+        inspectRoute: 'delegation action:"route"',
+        workspaceAction: route.workspaceActionId ? `workspace action:"action" actionId:"${route.workspaceActionId}"` : null,
+        runWorkspaceAction: route.workspaceActionId ? `workspace action:"run" actionId:"${route.workspaceActionId}" confirm:true explicitUserRequest:"..."` : null,
+        runCommand: route.command ? `workspace action:"run_command" command:"${route.command}" confirm:true explicitUserRequest:"..."` : null,
+        runCommandTemplate: route.commandTemplate ? `workspace action:"run_command" command:"${route.commandTemplate}" confirm:true explicitUserRequest:"..."` : null,
       },
     } : {}),
   };
@@ -169,6 +381,7 @@ export function delegationPostureCatalogStatus(context: CommandContext): Record<
   return {
     modes: ['delegation_posture', 'delegation_route'],
     routes: routes().length,
+    decisionCards: delegationDecisionCards(context).length,
     operatorClientAttached: Boolean(context.clients?.operator),
     readOnly: true,
   };
@@ -184,12 +397,14 @@ export function delegationPostureSummary(context: CommandContext, args: AgentHar
     status: 'available',
     summary: {
       routes: routes().length,
+      decisionCards: delegationDecisionCards(context).length,
       operatorClientAttached: Boolean(context.clients?.operator),
       sessionId: context.session.runtime.sessionId,
       delegatedReviewPolicy: 'explicit-build-delegation-only',
-      normalChatPolicy: 'ordinary assistant work stays in the main Agent conversation',
-      codingOwnership: 'GoodVibes TUI owns file edits, git/worktree workflows, execution isolation UX, coding panels, and delegated review coordination',
+      normalChatPolicy: 'ordinary assistant work and suitable local execution stay in the main Agent conversation',
+      codingOwnership: 'Agent may use local read/edit/exec when the current workspace is sufficient; GoodVibes TUI/shared-session routes own isolation, remote execution, separate worktrees, coding panels, and delegated review coordination',
     },
+    decisionCards: delegationDecisionCards(context),
     routes: filtered.map((route) => describeRoute(context, route, { includeParameters })),
     returned: filtered.length,
     total: routes().length,
@@ -202,7 +417,7 @@ export function describeHarnessDelegationRoute(context: CommandContext, args: Ag
   if (!lookup) {
     return {
       status: 'missing_lookup',
-      usage: 'delegation_route requires delegationRouteId, target, or query. Use mode:"delegation_posture" to inspect delegation route ids.',
+      usage: 'delegation action:"route" requires delegationRouteId, target, or query. Use delegation action:"status" to inspect delegation route ids.',
     };
   }
   const all = routes();
@@ -222,6 +437,6 @@ export function describeHarnessDelegationRoute(context: CommandContext, args: Ag
   }
   return {
     status: 'missing_lookup',
-    usage: `Unknown delegation route ${lookup.input}. Use mode:"delegation_posture" to inspect delegation route ids.`,
+    usage: `Unknown delegation route ${lookup.input}. Use delegation action:"status" to inspect delegation route ids.`,
   };
 }

package/src/tools/agent-harness-document-ops-reviewer-readiness.ts

@@ -0,0 +1,234 @@
+import type { ArtifactDescriptor } from '@pellux/goodvibes-sdk/platform/artifacts';
+import type { CommandContext } from '../input/command-registry.ts';
+import { AgentDocumentRegistry, type AgentDocumentRecord } from '../agent/document-registry.ts';
+import type { ReviewerReadinessCheck, ReviewerReadinessChecklist, ReviewerReadinessStatus } from './agent-harness-document-ops-types.ts';
+
+function readMetadataString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function readMetadataStringList(value: unknown): readonly string[] {
+  if (typeof value === 'string') {
+    return value.split(/[,\n]/).map((entry) => entry.trim()).filter(Boolean);
+  }
+  if (!Array.isArray(value)) return [];
+  return value.filter((entry): entry is string => typeof entry === 'string').map((entry) => entry.trim()).filter(Boolean);
+}
+
+function artifactPurpose(artifact: ArtifactDescriptor): string {
+  return readMetadataString(artifact.metadata.purpose);
+}
+
+function isModelCompareArtifact(artifact: ArtifactDescriptor): boolean {
+  const purpose = artifactPurpose(artifact);
+  if (purpose === 'agent-model-compare') return true;
+  if (purpose) return false;
+  return readMetadataString(artifact.filename).startsWith('blind-model-comparison-cmp_');
+}
+
+function isModelCompareJudgmentArtifact(artifact: ArtifactDescriptor): boolean {
+  const purpose = artifactPurpose(artifact);
+  if (purpose === 'agent-model-compare-judgment') return true;
+  if (purpose) return false;
+  return readMetadataString(artifact.filename).startsWith('blind-model-comparison-judgment-');
+}
+
+function isModelCompareRouteDecisionArtifact(artifact: ArtifactDescriptor): boolean {
+  return artifactPurpose(artifact) === 'agent-model-compare-route-decision';
+}
+
+function isModelCompareHandoffArtifact(artifact: ArtifactDescriptor): boolean {
+  const purpose = artifactPurpose(artifact);
+  if (purpose === 'agent-model-compare-handoff') return true;
+  if (purpose) return false;
+  return readMetadataString(artifact.filename).startsWith('blind-model-comparison-handoff-');
+}
+
+function readDocuments(context: CommandContext): readonly AgentDocumentRecord[] {
+  const shellPaths = context.workspace?.shellPaths;
+  if (!shellPaths) return [];
+  try {
+    return AgentDocumentRegistry.fromShellPaths(shellPaths).list();
+  } catch {
+    return [];
+  }
+}
+
+function readArtifacts(context: CommandContext): readonly ArtifactDescriptor[] {
+  try {
+    return context.platform.artifactStore?.list?.(100) ?? [];
+  } catch {
+    return [];
+  }
+}
+
+function reviewerReadinessStatus(checks: readonly ReviewerReadinessCheck[]): ReviewerReadinessStatus {
+  if (checks.some((check) => check.status === 'needs-setup')) return 'needs-setup';
+  if (checks.some((check) => check.status === 'attention')) return 'attention';
+  return 'ready';
+}
+
+export function buildReviewerReadinessChecklist(
+  context: CommandContext,
+  options: {
+    readonly documentsReady: boolean;
+    readonly modelCompareReady: boolean;
+    readonly artifactBrowserReady: boolean;
+  },
+): ReviewerReadinessChecklist {
+  const documents = readDocuments(context);
+  const reviewDocuments = documents.filter((document) => document.status !== 'archived');
+  const openComments = reviewDocuments.reduce((total, document) => total + document.comments.filter((comment) => comment.status === 'open').length, 0);
+  const proposedSuggestions = reviewDocuments.reduce((total, document) => total + document.suggestions.filter((suggestion) => suggestion.status === 'proposed').length, 0);
+  const documentsMissingSourceArtifacts = reviewDocuments.filter((document) => document.attachments.length === 0 && !document.lastArtifactId).length;
+  const artifacts = readArtifacts(context);
+  const comparisons = artifacts.filter(isModelCompareArtifact);
+  const judgments = artifacts.filter(isModelCompareJudgmentArtifact);
+  const routeDecisions = artifacts.filter(isModelCompareRouteDecisionArtifact);
+  const handoffs = artifacts.filter(isModelCompareHandoffArtifact);
+  const revealedJudgments = judgments.filter((artifact) => (
+    artifact.metadata.revealIncludedInJudgment === true
+    && readMetadataString(artifact.metadata.winnerModel).length > 0
+  ));
+  const hiddenJudgments = judgments.filter((artifact) => (
+    artifact.metadata.revealIncludedInJudgment !== true
+    || readMetadataString(artifact.metadata.winnerModel).length === 0
+  ));
+  const routeDecisionComparisonIds = new Set(routeDecisions.map((artifact) => readMetadataString(artifact.metadata.comparisonId)).filter(Boolean));
+  const routeDecisionJudgmentArtifactIds = new Set(routeDecisions.map((artifact) => readMetadataString(artifact.metadata.judgmentArtifactId)).filter(Boolean));
+  const revealedJudgmentsWaitingOnRouteDecision = revealedJudgments.filter((artifact) => {
+    const comparisonId = readMetadataString(artifact.metadata.comparisonId);
+    return !routeDecisionJudgmentArtifactIds.has(artifact.id) && (!comparisonId || !routeDecisionComparisonIds.has(comparisonId));
+  });
+  const revealedComparisonIds = new Set(revealedJudgments.map((artifact) => readMetadataString(artifact.metadata.comparisonId)).filter(Boolean));
+  const unrevealedComparisons = comparisons.filter((artifact) => {
+    const comparisonId = readMetadataString(artifact.metadata.comparisonId);
+    return artifact.metadata.revealIncludedInTranscript !== true && (!comparisonId || !revealedComparisonIds.has(comparisonId));
+  });
+  const handoffsMissingRelatedArtifacts = handoffs.filter((artifact) => readMetadataStringList(artifact.metadata.relatedArtifactIds).length === 0).length;
+  const comparisonSourceMissing = comparisons.filter((artifact) => (
+    !readMetadataString(artifact.metadata.sourceArtifactId)
+    && !readMetadataString(artifact.metadata.documentId)
+  )).length;
+  const missingSourceArtifacts = documentsMissingSourceArtifacts + comparisonSourceMissing;
+  const firstOpenCommentDocument = reviewDocuments.find((document) => document.comments.some((comment) => comment.status === 'open'));
+  const firstProposedSuggestionDocument = reviewDocuments.find((document) => document.suggestions.some((suggestion) => suggestion.status === 'proposed'));
+  const firstUnrevealedComparison = unrevealedComparisons[0];
+  const firstHiddenJudgment = hiddenJudgments[0];
+  const firstRevealedJudgment = revealedJudgmentsWaitingOnRouteDecision[0];
+  const firstHandoffMissingRelated = handoffs.find((artifact) => readMetadataStringList(artifact.metadata.relatedArtifactIds).length === 0);
+
+  const checks: ReviewerReadinessCheck[] = [
+    {
+      id: 'review-tooling',
+      label: 'Review tooling',
+      status: options.documentsReady && options.modelCompareReady && options.artifactBrowserReady ? 'pass' : 'needs-setup',
+      count: Number(options.documentsReady) + Number(options.modelCompareReady) + Number(options.artifactBrowserReady),
+      detail: options.documentsReady && options.modelCompareReady && options.artifactBrowserReady
+        ? 'Document, artifact, and blind comparison routes are available.'
+        : 'Document, artifact, and blind comparison routes must be available before a reviewer-ready export can be trusted.',
+      inspectRoute: 'agent_harness mode:"document_ops"',
+      repairRoute: 'agent_harness mode:"workspace_actions" categoryId:"documents"',
+    },
+    {
+      id: 'document-review-state',
+      label: 'Document comments and suggestions',
+      status: openComments + proposedSuggestions > 0 ? 'attention' : 'pass',
+      count: openComments + proposedSuggestions,
+      detail: openComments + proposedSuggestions > 0
+        ? `${openComments} open comment(s) and ${proposedSuggestions} proposed suggestion(s) need a visible resolve, accept, or reject decision.`
+        : 'No open document comments or proposed AI suggestions are waiting on reviewer action.',
+      inspectRoute: firstOpenCommentDocument || firstProposedSuggestionDocument
+        ? `agent_documents show documentId:"${firstOpenCommentDocument?.id ?? firstProposedSuggestionDocument?.id}" includeVersions:true`
+        : 'agent_documents list',
+      repairRoute: firstOpenCommentDocument
+        ? `agent_documents resolveComment documentId:"${firstOpenCommentDocument.id}" commentId:"..." confirm:true explicitUserRequest:"..."`
+        : firstProposedSuggestionDocument
+          ? `agent_documents acceptSuggestion documentId:"${firstProposedSuggestionDocument.id}" suggestionId:"..." confirm:true explicitUserRequest:"..." or agent_documents rejectSuggestion documentId:"${firstProposedSuggestionDocument.id}" suggestionId:"..." confirm:true explicitUserRequest:"..."`
+          : undefined,
+    },
+    {
+      id: 'source-artifacts',
+      label: 'Source artifacts',
+      status: missingSourceArtifacts > 0 ? 'attention' : 'pass',
+      count: missingSourceArtifacts,
+      detail: missingSourceArtifacts > 0
+        ? `${documentsMissingSourceArtifacts} document draft(s) and ${comparisonSourceMissing} comparison artifact(s) have no attached source artifact or document source marker.`
+        : 'Document drafts and saved comparisons have source artifacts or explicit document/source markers where the current stores can verify them.',
+      inspectRoute: 'agent_harness mode:"document_ops_lane" laneId:"artifact_browser"',
+      repairRoute: missingSourceArtifacts > 0
+        ? 'agent_documents attachArtifact documentId:"..." artifactId:"..." confirm:true explicitUserRequest:"..." or agent_model_compare handoff artifactId:"..." relatedArtifactIds:"..." confirm:true explicitUserRequest:"..."'
+        : undefined,
+    },
+    {
+      id: 'comparison-reveal',
+      label: 'Blind comparison reveal',
+      status: unrevealedComparisons.length + hiddenJudgments.length > 0 ? 'attention' : 'pass',
+      count: unrevealedComparisons.length + hiddenJudgments.length,
+      detail: unrevealedComparisons.length + hiddenJudgments.length > 0
+        ? `${unrevealedComparisons.length} saved comparison(s) and ${hiddenJudgments.length} judgment(s) still hide winner identity before reviewer handoff.`
+        : 'Saved comparison judgments with route-change implications are revealed, or no hidden comparison artifacts are pending.',
+      inspectRoute: firstUnrevealedComparison
+        ? `agent_model_compare review artifactId:"${firstUnrevealedComparison.id}"`
+        : firstHiddenJudgment
+          ? `agent_model_compare review artifactId:"${firstHiddenJudgment.id}"`
+          : 'agent_model_compare review',
+      repairRoute: firstUnrevealedComparison
+        ? `agent_model_compare reveal artifactId:"${firstUnrevealedComparison.id}"`
+        : firstHiddenJudgment
+          ? `agent_model_compare judge artifactId:"${readMetadataString(firstHiddenJudgment.metadata.sourceArtifactId) || firstHiddenJudgment.id}" winnerBlindId:"${readMetadataString(firstHiddenJudgment.metadata.winnerBlindId) || '...'}" reveal:true confirm:true explicitUserRequest:"..."`
+          : undefined,
+    },
+    {
+      id: 'route-change-decision',
+      label: 'Route-change decision',
+      status: revealedJudgmentsWaitingOnRouteDecision.length > 0 ? 'attention' : 'pass',
+      count: revealedJudgmentsWaitingOnRouteDecision.length,
+      detail: revealedJudgmentsWaitingOnRouteDecision.length > 0
+        ? `${revealedJudgmentsWaitingOnRouteDecision.length} revealed judgment(s) can drive a confirmed model route update, or the user can explicitly leave routing unchanged before archiving.`
+        : 'No revealed model comparison judgment is waiting on an apply-or-leave-unchanged decision.',
+      inspectRoute: firstRevealedJudgment
+        ? `agent_model_compare review artifactId:"${firstRevealedJudgment.id}" reveal:true`
+        : 'models action:"status"',
+      repairRoute: firstRevealedJudgment
+        ? `agent_model_compare apply artifactId:"${firstRevealedJudgment.id}" confirm:true explicitUserRequest:"..." or agent_model_compare routeDecision artifactId:"${firstRevealedJudgment.id}" decision:"left-unchanged" confirm:true explicitUserRequest:"..."`
+        : undefined,
+    },
+    {
+      id: 'handoff-archive-evidence',
+      label: 'Reviewer handoff evidence',
+      status: handoffsMissingRelatedArtifacts > 0 ? 'attention' : 'pass',
+      count: handoffsMissingRelatedArtifacts,
+      detail: handoffsMissingRelatedArtifacts > 0
+        ? `${handoffsMissingRelatedArtifacts} reviewer handoff artifact(s) have no related evidence artifact ids before archive.`
+        : 'Reviewer handoff artifacts include related evidence ids, or no reviewer handoff archive is pending.',
+      inspectRoute: firstHandoffMissingRelated
+        ? `agent_model_compare review artifactId:"${firstHandoffMissingRelated.id}"`
+        : 'agent_model_compare review',
+      repairRoute: firstHandoffMissingRelated
+        ? `agent_model_compare handoff artifactId:"${readMetadataString(firstHandoffMissingRelated.metadata.sourceArtifactId) || firstHandoffMissingRelated.id}" relatedArtifactIds:"..." confirm:true explicitUserRequest:"..."`
+        : undefined,
+    },
+  ];
+  const status = reviewerReadinessStatus(checks);
+  const firstAction = checks.find((check) => check.status === 'attention' || check.status === 'needs-setup');
+  return {
+    status,
+    next: firstAction
+      ? `${firstAction.label}: ${firstAction.detail}`
+      : 'Export or archive reviewer packets through the returned confirmed document, artifact, or comparison routes.',
+    summary: {
+      documents: documents.length,
+      openComments,
+      proposedSuggestions,
+      documentsMissingSourceArtifacts,
+      savedComparisons: comparisons.length,
+      unrevealedComparisons: unrevealedComparisons.length,
+      hiddenJudgments: hiddenJudgments.length,
+      revealedJudgments: revealedJudgmentsWaitingOnRouteDecision.length,
+      handoffsMissingRelatedArtifacts,
+    },
+    checks,
+    policy: 'Reviewer readiness is read-only. It flags unresolved review work and returns exact existing routes; document exports, comparison handoffs, archives, and model route updates still require explicit confirmation.',
+  };
+}