@chalksurf/cli 0.3.4 → 0.3.6

package/dist/bin/chalksurf.js

@@ -151,6 +151,15 @@ var createApiClient = ({
     agentGetExerciseUsage: async (id) => {
       return await query("agentGetExerciseUsage", { id });
     },
+    agentListQualityIssues: async (input) => {
+      return await query("agentListQualityIssues", input);
+    },
+    agentResolveQualityIssue: async (input) => {
+      return await mutation("agentResolveQualityIssue", input);
+    },
+    agentDismissQualityIssue: async (input) => {
+      return await mutation("agentDismissQualityIssue", input);
+    },
     agentListExerciseLabels: async () => {
       return await query("agentListExerciseLabels", {});
     },
@@ -211,6 +220,9 @@ var createApiClient = ({
     agentBulkUpdateSheets: async (input) => {
       return await mutation("agentBulkUpdateSheets", input);
     },
+    agentVerifyBulkSheetUpdates: async (input) => {
+      return await mutation("agentVerifyBulkSheetUpdates", input);
+    },
     agentListSheets: async (input) => {
       return await query("agentListSheets", input);
     },
@@ -887,7 +899,9 @@ var Constants = {
         "generate_sheet_translation_completed",
         "upload_exercise_figure",
         "attach_exercise_figures",
-        "bulk_update_sheets"
+        "bulk_update_sheets",
+        "resolve_quality_issue",
+        "dismiss_quality_issue"
       ],
       agent_audit_outcome: ["started", "success", "failed", "denied"],
       agent_audit_resource_type: ["exercise", "sheet", "folder", "job", "event", "figure_asset"],
@@ -928,7 +942,6 @@ var Constants = {
         "figure_update",
         "automatic_labeling"
       ],
-      figure_asset_source_kind: ["document_crop", "rendered_figure"],
       job_type: [
         "exercise_sheet_import",
         "exercise_import",
@@ -1408,6 +1421,18 @@ var agentWriteOperationRegistry = {
     resourceType: "exercise",
     sync: true
   },
+  resolve_quality_issue: {
+    agentToolName: "resolve_quality_issue",
+    receiptOperation: "resolve_quality_issue",
+    resourceType: "exercise",
+    sync: true
+  },
+  dismiss_quality_issue: {
+    agentToolName: "dismiss_quality_issue",
+    receiptOperation: "dismiss_quality_issue",
+    resourceType: "exercise",
+    sync: true
+  },
   update_sheet: {
     agentToolName: "update_sheet",
     receiptOperation: "update_sheet",
@@ -1735,6 +1760,7 @@ var folderPathSegmentSchema = strictObject({
   name: z3.string().trim().min(1)
 });
 var listSheetsAgentInputSchema = strictObject({
+  afterId: uuidSchema.optional(),
   folderId: uuidSchema.optional(),
   includeDescendants: z3.boolean().optional().default(false),
   limit: z3.number().int().min(1).max(100).optional().default(50),
@@ -1742,6 +1768,9 @@ var listSheetsAgentInputSchema = strictObject({
 }).refine(({ folderId, includeDescendants }) => folderId !== void 0 || !includeDescendants, {
   message: "folderId is required when includeDescendants is true",
   path: ["folderId"]
+}).refine(({ afterId, offset }) => afterId === void 0 || offset === 0, {
+  message: "offset must be zero when afterId is provided",
+  path: ["offset"]
 });
 var listSheetsAgentOutputSchema = strictObject({
   sheets: z3.array(
@@ -1756,6 +1785,7 @@ var listSheetsAgentOutputSchema = strictObject({
       seriesAssignments: sheetSeriesAssignmentsSchema
     })
   ),
+  inventoryToken: z3.string().trim().min(1),
   totalCount: z3.number().int().min(0)
 });
 var exerciseLabelSchema = strictObject({
@@ -2008,6 +2038,41 @@ var getExerciseUsageAgentInputSchema = strictObject({
 var getExerciseUsageAgentOutputSchema = strictObject({
   usage: exerciseUsageSchema
 });
+var qualityIssueSelectorShape = {
+  exerciseIds: z3.array(uuidSchema).min(1).max(100).optional(),
+  issueIds: z3.array(uuidSchema).min(1).max(100).optional(),
+  severities: z3.array(z3.enum(exerciseQualityIssueSeverities)).min(1).optional(),
+  limit: z3.number().int().min(1).max(100).optional().default(50),
+  cursor: z3.string().trim().min(1).optional()
+};
+var listQualityIssuesAgentInputSchema = strictObject(qualityIssueSelectorShape).refine(
+  ({ exerciseIds, issueIds }) => exerciseIds === void 0 || issueIds === void 0,
+  { message: "exerciseIds and issueIds are mutually exclusive" }
+);
+var qualityIssueListItemSchema = strictObject({
+  id: uuidSchema,
+  severity: z3.enum(exerciseQualityIssueSeverities),
+  comment: z3.string(),
+  sourceLanguage: z3.enum(translationLanguages),
+  sourceInputHash: z3.string(),
+  createdAt: dateStringSchema,
+  exercise: strictObject({
+    id: uuidSchema,
+    updatedAt: dateStringSchema,
+    subject: z3.enum(exerciseSubjects),
+    source: z3.string().nullable(),
+    organizationId: uuidSchema
+  })
+});
+var listQualityIssuesAgentOutputSchema = strictObject({
+  issues: z3.array(qualityIssueListItemSchema),
+  nextCursor: z3.string().nullable()
+});
+var resolveQualityIssueAgentInputSchema = strictObject({
+  issueId: uuidSchema,
+  expectedExerciseUpdatedAt: expectedUpdatedAtSchema
+});
+var dismissQualityIssueAgentInputSchema = resolveQualityIssueAgentInputSchema;
 var agentWriteReceiptSchema = strictObject({
   resource: strictObject({
     type: z3.enum(["exercise", "sheet", "folder"]),
@@ -2033,6 +2098,8 @@ var agentWriteReceiptSchema = strictObject({
 var agentWriteReceiptOutputSchema = strictObject({
   receipt: agentWriteReceiptSchema
 });
+var resolveQualityIssueAgentOutputSchema = agentWriteReceiptOutputSchema;
+var dismissQualityIssueAgentOutputSchema = agentWriteReceiptOutputSchema;
 var copyExerciseAgentInputSchema = strictObject({
   id: uuidSchema
 });
@@ -2218,6 +2285,34 @@ var bulkUpdateSheetsAgentOutputSchema = strictObject({
   results: z3.array(bulkUpdateSheetResultSchema),
   receipt: agentWriteReceiptSchema.nullable()
 });
+var verifyBulkSheetUpdateStatusSchema = z3.enum(["applied", "pending", "conflicting", "error"]);
+var verifyBulkSheetUpdateConflictSchema = strictObject({
+  field: z3.enum(["expectedUpdatedAt", "expectedSeriesAssignments"]),
+  code: z3.enum(["updated_at_changed", "series_assignments_changed"])
+});
+var verifyBulkSheetUpdateResultSchema = strictObject({
+  id: uuidSchema,
+  status: verifyBulkSheetUpdateStatusSchema,
+  matchedPaths: z3.array(z3.string()),
+  unmatchedPaths: z3.array(z3.string()),
+  conflicts: z3.array(verifyBulkSheetUpdateConflictSchema),
+  errorCode: z3.string().nullable(),
+  errorMessage: z3.string().nullable()
+});
+var verifyBulkSheetUpdatesAgentInputSchema = strictObject({
+  updates: z3.array(updateSheetAgentInputSchema).min(1).max(100)
+});
+var verifyBulkSheetUpdatesAgentOutputSchema = strictObject({
+  state: z3.enum(["applied", "pending", "conflicting", "mixed", "error"]),
+  counts: strictObject({
+    total: z3.number().int().min(0),
+    applied: z3.number().int().min(0),
+    pending: z3.number().int().min(0),
+    conflicting: z3.number().int().min(0),
+    error: z3.number().int().min(0)
+  }),
+  results: z3.array(verifyBulkSheetUpdateResultSchema)
+});
 var createSheetScoredExerciseSchema = strictObject({
   id: uuidSchema,
   scorePoints: z3.number().min(0).max(99999.9).refine((value) => Number.isInteger(value * 10), "Score can have at most 1 decimal place").nullable()
@@ -2611,6 +2706,18 @@ var getExerciseUsageInputSchema = getExerciseUsageAgentInputSchema.extend({
   organizationId: organizationIdSchema
 });
 var getExerciseUsageOutputSchema = getExerciseUsageAgentOutputSchema;
+var listQualityIssuesInputSchema = listQualityIssuesAgentInputSchema.safeExtend({
+  organizationId: organizationIdSchema
+});
+var listQualityIssuesOutputSchema = listQualityIssuesAgentOutputSchema;
+var resolveQualityIssueInputSchema = resolveQualityIssueAgentInputSchema.extend({
+  organizationId: organizationIdSchema
+});
+var resolveQualityIssueOutputSchema = resolveQualityIssueAgentOutputSchema;
+var dismissQualityIssueInputSchema = dismissQualityIssueAgentInputSchema.extend({
+  organizationId: organizationIdSchema
+});
+var dismissQualityIssueOutputSchema = dismissQualityIssueAgentOutputSchema;
 var listExerciseLabelsInputSchema = listExerciseLabelsAgentInputSchema;
 var listExerciseLabelsOutputSchema = listExerciseLabelsAgentOutputSchema;
 var copyExerciseInputSchema = copyExerciseAgentInputSchema.extend({
@@ -2687,7 +2794,7 @@ var searchSheetsOutputSchema = strictObject2({
 var listSheetsInputSchema = listSheetsAgentInputSchema.extend({
   organizationId: organizationIdSchema
 });
-var listSheetsOutputSchema = listSheetsAgentOutputSchema;
+var listSheetsOutputSchema = listSheetsAgentOutputSchema.omit({ inventoryToken: true });
 var getSheetInputSchema = getSheetAgentInputSchema.extend({
   organizationId: organizationIdSchema
 });
@@ -2726,6 +2833,10 @@ var bulkUpdateSheetsInputSchema = bulkUpdateSheetsAgentInputSchema.extend({
   organizationId: organizationIdSchema
 });
 var bulkUpdateSheetsOutputSchema = bulkUpdateSheetsAgentOutputSchema;
+var verifyBulkSheetUpdatesInputSchema = verifyBulkSheetUpdatesAgentInputSchema.extend({
+  organizationId: organizationIdSchema
+});
+var verifyBulkSheetUpdatesOutputSchema = verifyBulkSheetUpdatesAgentOutputSchema;
 var setSheetVisibilityInputSchema = setSheetVisibilityAgentInputSchema.extend({
   organizationId: organizationIdSchema
 });
@@ -3587,6 +3698,16 @@ var chalksurfMcpToolCapabilities = {
     requiredPermission: "read",
     security: { type: "oauth2", scopes: [chalksurfMcpScopes.read] }
   },
+  list_quality_issues: {
+    name: "list_quality_issues",
+    title: "List quality issues",
+    description: "List active quality issues for exercises owned by the selected ChalkSurf organization.",
+    inputSchema: listQualityIssuesInputSchema,
+    outputSchema: listQualityIssuesOutputSchema,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    requiredPermission: "read",
+    security: { type: "oauth2", scopes: [chalksurfMcpScopes.read] }
+  },
   list_exercise_labels: {
     name: "list_exercise_labels",
     title: "List exercise labels",
@@ -3637,6 +3758,26 @@ var chalksurfMcpToolCapabilities = {
     requiredPermission: "write",
     security: { type: "oauth2", scopes: [chalksurfMcpScopes.write] }
   },
+  resolve_quality_issue: {
+    name: "resolve_quality_issue",
+    title: "Resolve quality issue",
+    description: "Mark an active quality issue resolved after checking the exercise evidence timestamp.",
+    inputSchema: resolveQualityIssueInputSchema,
+    outputSchema: resolveQualityIssueOutputSchema,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    requiredPermission: "write",
+    security: { type: "oauth2", scopes: [chalksurfMcpScopes.write] }
+  },
+  dismiss_quality_issue: {
+    name: "dismiss_quality_issue",
+    title: "Dismiss quality issue",
+    description: "Dismiss an active quality issue after checking the exercise evidence timestamp.",
+    inputSchema: dismissQualityIssueInputSchema,
+    outputSchema: dismissQualityIssueOutputSchema,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    requiredPermission: "write",
+    security: { type: "oauth2", scopes: [chalksurfMcpScopes.write] }
+  },
   set_exercise_visibility: {
     name: "set_exercise_visibility",
     title: "Set exercise visibility",
@@ -3801,6 +3942,16 @@ var chalksurfMcpToolCapabilities = {
     requiredPermission: "write",
     security: { type: "oauth2", scopes: [chalksurfMcpScopes.write] }
   },
+  verify_bulk_sheet_updates: {
+    name: "verify_bulk_sheet_updates",
+    title: "Verify bulk sheet updates",
+    description: "Use this after an uncertain bulk apply response to classify each requested sheet target as applied, pending, conflicting, or error without writing.",
+    inputSchema: verifyBulkSheetUpdatesInputSchema,
+    outputSchema: verifyBulkSheetUpdatesOutputSchema,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    requiredPermission: "write",
+    security: { type: "oauth2", scopes: [chalksurfMcpScopes.write] }
+  },
   set_sheet_visibility: {
     name: "set_sheet_visibility",
     title: "Set sheet visibility",
@@ -8873,10 +9024,46 @@ var parseBulkUpdateSheetsAgentInput = (input) => {
   }
   return parsedInput.data;
 };
+var parseVerifyBulkSheetUpdatesAgentInput = (input) => {
+  if (typeof input === "object" && input !== null && "schemaVersion" in input) {
+    throw new CliCommandError(
+      "CLI result envelopes are not verifier manifests. Pass the original bulk update manifest or an object with updates.",
+      2
+    );
+  }
+  if (typeof input === "object" && input !== null && "mode" in input) {
+    const parsedBulkInput = bulkUpdateSheetsAgentInputSchema.safeParse(input);
+    if (!parsedBulkInput.success) {
+      throw new CliCommandError(
+        `Invalid bulk sheet verification input: ${formatZodIssues(parsedBulkInput.error.issues)}`,
+        2
+      );
+    }
+    return { updates: parsedBulkInput.data.updates };
+  }
+  const parsedInput = verifyBulkSheetUpdatesAgentInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    throw new CliCommandError(`Invalid bulk sheet verification input: ${formatZodIssues(parsedInput.error.issues)}`, 2);
+  }
+  return parsedInput.data;
+};
 
 // src/lib/agent-receipt.ts
+var getBulkSheetCount = (details) => {
+  if (typeof details !== "object" || details === null || !("sheetIds" in details) || !Array.isArray(details.sheetIds)) {
+    return null;
+  }
+  return details.sheetIds.filter((sheetId) => typeof sheetId === "string").length;
+};
 var formatAgentWriteReceiptOutput = ({ receipt }) => {
-  return `${receipt.operation} -> ${receipt.resource.type} ${receipt.resource.id}`;
+  if (receipt.resource) {
+    return `${receipt.operation} -> ${receipt.resource.type} ${receipt.resource.id}`;
+  }
+  const bulkSheetCount = receipt.operation === "bulk_update_sheets" ? getBulkSheetCount(receipt.details) : null;
+  if (bulkSheetCount !== null) {
+    return `${receipt.operation} -> ${bulkSheetCount} sheet${bulkSheetCount === 1 ? "" : "s"}`;
+  }
+  return `${receipt.operation} completed`;
 };
 
 // src/lib/command-options.ts
@@ -12034,135 +12221,1047 @@ var registerProfileCommands = (profileYargs, context) => {
   ).demandCommand(1).strict();
 };
 
-// src/commands/sheet.ts
+// src/commands/quality-issue/index.ts
+import { z as z15 } from "zod";
+
+// src/commands/quality-issue/artifact-integrity.ts
+import { createHash } from "node:crypto";
+import { readFile as readFile5 } from "node:fs/promises";
+import { join as join2 } from "node:path";
+
+// src/commands/quality-issue/artifact-schemas.ts
 import { z as z14 } from "zod";
-var readinessIssueTypeLabels = {
-  missing_translation: "missing translations",
-  missing_solution: "missing solutions",
-  invalid_latex: "invalid LaTeX",
-  missing_score: "missing scores",
-  exercise_quality_issue: "exercise quality issues"
+var schemaVersion = z14.literal("v1");
+var uuid = z14.uuid();
+var commonShape = {
+  schemaVersion,
+  runId: z14.string().trim().min(1),
+  organizationId: uuid
+};
+var qualityIssueScopeSchema = z14.object({
+  ...commonShape,
+  request: z14.string().trim().min(1),
+  environment: z14.string().trim().min(1),
+  profile: z14.string().trim().min(1),
+  mode: z14.enum(["dry_run", "apply"]),
+  discovery: z14.object({}).catchall(z14.unknown())
+}).strict();
+var qualityIssueInventoryRowSchema = z14.object({
+  ...commonShape,
+  issueId: uuid,
+  exerciseId: uuid,
+  exerciseUpdatedAt: z14.string().trim().min(1),
+  severity: z14.enum(["warning", "error", "critical"]),
+  subject: z14.enum(["math", "physics", "chemistry"]),
+  evidence: z14.object({}).catchall(z14.unknown())
+}).strict();
+var qualityIssueDiscoveryRowSchema = z14.object({
+  ...commonShape,
+  tool: z14.string().trim().min(1),
+  evidence: z14.object({}).catchall(z14.unknown())
+}).strict();
+var qualityIssueCandidateExerciseRowSchema = z14.object({
+  ...commonShape,
+  exerciseId: uuid,
+  evidence: z14.object({}).catchall(z14.unknown())
+}).strict();
+var patchSchema = z14.object({
+  path: z14.string().trim().min(1),
+  before: z14.unknown(),
+  after: z14.unknown()
+}).strict().refine((patch) => Object.hasOwn(patch, "before") && Object.hasOwn(patch, "after"), {
+  message: "Patch before and after values are required; use null for an intentionally empty value."
+});
+var classificationBaseShape = {
+  ...commonShape,
+  issueId: uuid,
+  reasonCode: z14.string().trim().min(1),
+  rationale: z14.string().trim().min(1)
+};
+var qualityIssueClassificationRowSchema = z14.discriminatedUnion("disposition", [
+  z14.object({
+    ...classificationBaseShape,
+    disposition: z14.literal("proposed_fix"),
+    patches: z14.array(patchSchema).min(1)
+  }).strict(),
+  z14.object({ ...classificationBaseShape, disposition: z14.literal("proposed_dismissal") }).strict(),
+  z14.object({ ...classificationBaseShape, disposition: z14.literal("needs_human") }).strict(),
+  z14.object({ ...classificationBaseShape, disposition: z14.literal("stale") }).strict(),
+  z14.object({ ...classificationBaseShape, disposition: z14.literal("failed") }).strict(),
+  z14.object({ ...classificationBaseShape, disposition: z14.literal("skipped") }).strict()
+]);
+var actionIdentityShape = {
+  actionId: z14.string().trim().min(1),
+  exerciseId: uuid
+};
+var updateActionSchema = z14.object({
+  ...actionIdentityShape,
+  type: z14.literal("update_exercise"),
+  expectedExerciseUpdatedAt: z14.string().trim().min(1),
+  issueIds: z14.array(uuid).min(1),
+  patches: z14.array(patchSchema).min(1)
+}).strict();
+var resolveActionSchema = z14.object({
+  ...actionIdentityShape,
+  type: z14.literal("resolve_quality_issue"),
+  issueId: uuid,
+  expectedExerciseUpdatedAtFromActionId: z14.string().trim().min(1)
+}).strict();
+var dismissActionSchema = z14.object({
+  ...actionIdentityShape,
+  type: z14.literal("dismiss_quality_issue"),
+  issueId: uuid,
+  expectedExerciseUpdatedAt: z14.string().trim().min(1)
+}).strict();
+var qualityIssueActionPlanSchema = z14.object({
+  ...commonShape,
+  inventory: z14.array(
+    z14.object({
+      issueId: uuid,
+      exerciseId: uuid,
+      exerciseUpdatedAt: z14.string().trim().min(1)
+    }).strict()
+  ),
+  actions: z14.array(z14.discriminatedUnion("type", [updateActionSchema, resolveActionSchema, dismissActionSchema])),
+  exclusions: z14.array(
+    z14.object({
+      issueId: uuid,
+      disposition: z14.enum(["needs_human", "stale", "failed", "skipped"]),
+      reasonCode: z14.string().trim().min(1)
+    }).strict()
+  )
+}).strict();
+var resultBaseShape = {
+  ...commonShape,
+  actionId: z14.string().trim().min(1)
+};
+var terminalErrorSchema = z14.object({
+  code: z14.string().trim().min(1),
+  message: z14.string().trim().min(1),
+  recovery: z14.string().trim().min(1)
+}).strict();
+var terminalResultSchema = (outcome) => z14.object({
+  ...resultBaseShape,
+  outcome: z14.literal(outcome),
+  error: terminalErrorSchema
+}).strict();
+var qualityIssueApplicationResultRowSchema = z14.discriminatedUnion("outcome", [
+  z14.object({
+    ...resultBaseShape,
+    outcome: z14.literal("success"),
+    receipt: agentWriteReceiptSchema,
+    resultingExerciseUpdatedAt: z14.iso.datetime({ offset: true }).optional()
+  }).strict(),
+  terminalResultSchema("failed"),
+  terminalResultSchema("stale"),
+  terminalResultSchema("skipped")
+]);
+
+// src/commands/quality-issue/artifact-integrity.ts
+var readJson = async (path, schema) => {
+  try {
+    return schema.parse(JSON.parse(await readFile5(path, "utf8")));
+  } catch (error) {
+    throw new CliCommandError(`Artifact validation failed for ${path}: ${String(error)}`, 2, true, {
+      code: "artifact_validation_failed",
+      retryable: false
+    });
+  }
 };
-var normalizeReadinessFilters = ({
-  issueTypes,
-  needsWork,
-  ready
-}) => {
-  if (needsWork && ready) {
-    throw new CliCommandError("--needs-work and --ready cannot be used together.", 2);
+var readJsonLines = async (path, schema, optional = false) => {
+  let contents;
+  try {
+    contents = await readFile5(path, "utf8");
+  } catch (error) {
+    if (optional && typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
+      return [];
+    }
+    throw new CliCommandError(`Artifact validation failed for ${path}: ${String(error)}`, 2, true, {
+      code: "artifact_validation_failed",
+      retryable: false
+    });
   }
-  return {
-    hasIssues: needsWork ? true : ready ? false : null,
-    issueTypes: normalizeChoiceValues({
-      allowedValues: sheetReadinessIssueTypes,
-      label: "--issue-type",
-      values: issueTypes
-    }) ?? []
-  };
+  return contents.split(/\r?\n/u).filter((line) => line.trim().length > 0).map((line, index) => {
+    try {
+      return schema.parse(JSON.parse(line));
+    } catch (error) {
+      throw new CliCommandError(`Artifact validation failed for ${path}:${index + 1}: ${String(error)}`, 2, true, {
+        code: "artifact_validation_failed",
+        retryable: false
+      });
+    }
+  });
 };
-var normalizeSheetSeriesPath = (value) => {
-  const normalizedValue = normalizeOptionalText(value);
-  if (normalizedValue === null) {
-    return null;
+var assertUnique = (values, label) => {
+  const seen = /* @__PURE__ */ new Set();
+  for (const value of values) {
+    if (seen.has(value)) {
+      throw new CliCommandError(`Artifact validation failed: duplicate ${label} ${value}`, 2, true, {
+        code: "artifact_validation_failed",
+        retryable: false
+      });
+    }
+    seen.add(value);
   }
-  const parsedValue = sheetSeriesPathSchema.safeParse(normalizedValue);
-  if (!parsedValue.success) {
-    throw new CliCommandError(
-      '--series-path is unknown. Run "chalksurf sheet series list --json" to inspect valid paths.',
-      2
+};
+var canonicalize = (value) => {
+  if (Array.isArray(value)) {
+    return value.map(canonicalize);
+  }
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, nestedValue]) => [key, canonicalize(nestedValue)])
     );
   }
-  return parsedValue.data;
+  return value;
 };
-var normalizeSheetSeriesYearFilter = ({ fromYear, toYear }) => {
-  if (fromYear === void 0 && toYear === void 0) {
-    return null;
+var canonicalJson = (value) => JSON.stringify(canonicalize(value));
+var assertPartitionIdentity = (scope, rows) => {
+  if (rows.some((row) => row.runId !== scope.runId || row.organizationId !== scope.organizationId)) {
+    throw new CliCommandError("Artifact validation failed: partition identity mismatch", 2, true, {
+      code: "artifact_validation_failed",
+      retryable: false
+    });
   }
-  if (fromYear !== void 0 && toYear !== void 0 && fromYear > toYear) {
-    throw new CliCommandError("--from-year must be less than or equal to --to-year.", 2);
+};
+var validateQualityIssueRun = async (runDirectory) => {
+  const scope = await readJson(join2(runDirectory, "scope.json"), qualityIssueScopeSchema);
+  const discovery = await readJsonLines(join2(runDirectory, "discovery.jsonl"), qualityIssueDiscoveryRowSchema);
+  const candidates = await readJsonLines(
+    join2(runDirectory, "candidate-exercises.jsonl"),
+    qualityIssueCandidateExerciseRowSchema
+  );
+  const inventory = await readJsonLines(join2(runDirectory, "inventory.jsonl"), qualityIssueInventoryRowSchema);
+  const classifications = await readJsonLines(
+    join2(runDirectory, "classifications.jsonl"),
+    qualityIssueClassificationRowSchema
+  );
+  const actionPlan = await readJson(join2(runDirectory, "action-plan.json"), qualityIssueActionPlanSchema);
+  const results = await readJsonLines(
+    join2(runDirectory, "application-results.jsonl"),
+    qualityIssueApplicationResultRowSchema,
+    true
+  );
+  assertPartitionIdentity(scope, [
+    ...discovery,
+    ...candidates,
+    ...inventory,
+    ...classifications,
+    actionPlan,
+    ...results
+  ]);
+  assertUnique(
+    candidates.map((row) => row.exerciseId),
+    "candidate exerciseId"
+  );
+  assertUnique(
+    inventory.map((row) => row.issueId),
+    "inventory issueId"
+  );
+  assertUnique(
+    classifications.map((row) => row.issueId),
+    "classification issueId"
+  );
+  assertUnique(
+    actionPlan.actions.map((action) => action.actionId),
+    "actionId"
+  );
+  const inventoryIds = new Set(inventory.map((row) => row.issueId));
+  const classificationIds = new Set(classifications.map((row) => row.issueId));
+  if (inventoryIds.size !== classificationIds.size || [...inventoryIds].some((issueId) => !classificationIds.has(issueId))) {
+    throw new CliCommandError(
+      "Artifact validation failed: every inventory issue needs exactly one classification",
+      2,
+      true,
+      {
+        code: "artifact_validation_failed",
+        retryable: false
+      }
+    );
   }
-  const parsedFilter = sheetSeriesYearFilterSchema.safeParse({ fromYear, toYear });
-  if (!parsedFilter.success) {
-    throw new CliCommandError("--from-year and --to-year must be four-digit years.", 2);
+  const planInventoryIds = new Set(actionPlan.inventory.map((row) => row.issueId));
+  assertUnique(
+    actionPlan.inventory.map((row) => row.issueId),
+    "action-plan inventory issueId"
+  );
+  if (inventoryIds.size !== planInventoryIds.size || [...inventoryIds].some((issueId) => !planInventoryIds.has(issueId))) {
+    throw new CliCommandError(
+      "Artifact validation failed: action-plan inventory does not match inventory.jsonl",
+      2,
+      true,
+      {
+        code: "artifact_validation_failed",
+        retryable: false
+      }
+    );
   }
-  return parsedFilter.data;
-};
-var hasUniqueItems2 = (values) => new Set(values).size === values.length;
-var sheetImportComponentIdPattern3 = /^[a-zA-Z0-9_-]{1,80}$/;
-var isValidTargetFolderPath2 = (value) => {
-  const normalizedSegments = value.replaceAll("\\", "/").split("/").filter((segment) => segment.length > 0);
-  return normalizedSegments.length > 0 && normalizedSegments.every((segment) => segment !== "." && segment !== "..");
-};
-var assertValidSheetImportPlan = (plan) => {
-  if (plan.sheets.length === 0) {
-    throw new CliCommandError("Invalid sheet import plan: sheets must include at least one sheet.", 2);
+  const candidateExerciseIds = new Set(candidates.map((row) => row.exerciseId));
+  if (inventory.some((row) => !candidateExerciseIds.has(row.exerciseId))) {
+    throw new CliCommandError("Artifact validation failed: inventory exercise is missing from candidates", 2, true, {
+      code: "artifact_validation_failed",
+      retryable: false
+    });
   }
-  plan.sheets.forEach((sheet) => {
-    if (sheet.sourceIndexes.length === 0) {
-      throw new CliCommandError("Invalid sheet import plan: sourceIndexes must include at least one source.", 2);
-    }
-    if (!sheet.sourceIndexes.every((sourceIndex) => Number.isInteger(sourceIndex) && sourceIndex >= 0)) {
-      throw new CliCommandError("Invalid sheet import plan: sourceIndexes must contain only non-negative integers.", 2);
-    }
-    if (!hasUniqueItems2(sheet.sourceIndexes)) {
-      throw new CliCommandError("Invalid sheet import plan: sourceIndexes must be unique within a sheet.", 2);
-    }
-    if (sheet.components) {
-      if (sheet.targetFolderPath !== void 0 || sheet.titleOverride !== void 0 || sheet.translateToLanguages) {
+  const inventoryByIssueId = new Map(inventory.map((row) => [row.issueId, row]));
+  const classificationByIssueId = new Map(classifications.map((row) => [row.issueId, row]));
+  const patchKeys = actionPlan.actions.flatMap(
+    (action) => action.type === "update_exercise" ? action.patches.map((patch) => `${action.exerciseId}\0${patch.path}`) : []
+  );
+  assertUnique(patchKeys, "exercise patch path");
+  assertUnique(
+    classifications.flatMap((classification) => {
+      if (classification.disposition !== "proposed_fix") return [];
+      const inventoryRow = inventoryByIssueId.get(classification.issueId);
+      return classification.patches.map((patch) => `${inventoryRow?.exerciseId ?? ""}\0${patch.path}`);
+    }),
+    "classified exercise patch path"
+  );
+  for (const plannedIssue of actionPlan.inventory) {
+    const source = inventoryByIssueId.get(plannedIssue.issueId);
+    if (!source || source.exerciseId !== plannedIssue.exerciseId || source.exerciseUpdatedAt !== plannedIssue.exerciseUpdatedAt) {
+      throw new CliCommandError("Artifact validation failed: action-plan evidence differs from inventory", 2, true, {
+        code: "artifact_validation_failed",
+        retryable: false
+      });
+    }
+  }
+  const updateActionsByExerciseId = /* @__PURE__ */ new Map();
+  const updateActionsByIssueId = /* @__PURE__ */ new Map();
+  const resolveActionsByIssueId = /* @__PURE__ */ new Map();
+  const dismissActionsByIssueId = /* @__PURE__ */ new Map();
+  const actionIndexById = new Map(actionPlan.actions.map((action, index) => [action.actionId, index]));
+  for (const action of actionPlan.actions) {
+    if (action.type === "update_exercise") {
+      assertUnique(action.issueIds, `update action ${action.actionId} issueId`);
+      if (updateActionsByExerciseId.has(action.exerciseId)) {
         throw new CliCommandError(
-          "Invalid sheet import plan: targetFolderPath, titleOverride, and translateToLanguages must be set on components when components are provided.",
-          2
+          `Artifact validation failed: exercise ${action.exerciseId} has more than one update action`,
+          2,
+          true,
+          { code: "artifact_validation_failed", retryable: false }
         );
       }
-      if (!hasUniqueItems2(sheet.components.map((component) => component.componentId))) {
-        throw new CliCommandError("Invalid sheet import plan: componentId values must be unique within a sheet.", 2);
-      }
-      sheet.components.forEach((component) => {
-        if (!sheetImportComponentIdPattern3.test(component.componentId)) {
+      updateActionsByExerciseId.set(action.exerciseId, action);
+      const expectedPatches = action.issueIds.flatMap((actionIssueId) => {
+        const source2 = inventoryByIssueId.get(actionIssueId);
+        const classification = classificationByIssueId.get(actionIssueId);
+        if (!source2 || source2.exerciseId !== action.exerciseId || source2.exerciseUpdatedAt !== action.expectedExerciseUpdatedAt || classification?.disposition !== "proposed_fix") {
           throw new CliCommandError(
-            "Invalid sheet import plan: componentId must be 1-80 letters, numbers, underscores, or hyphens.",
-            2
-          );
-        }
-        if (!component.description.trim()) {
-          throw new CliCommandError("Invalid sheet import plan: component descriptions must be non-empty.", 2);
-        }
-        if (component.targetFolderPath != null && !isValidTargetFolderPath2(component.targetFolderPath)) {
-          throw new CliCommandError(
-            'Invalid sheet import plan: component targetFolderPath must be a normalized folder path without "." or ".." segments.',
-            2
+            "Artifact validation failed: update action evidence differs from inventory",
+            2,
+            true,
+            {
+              code: "artifact_validation_failed",
+              retryable: false
+            }
           );
         }
-        if (component.translateToLanguages && !hasUniqueItems2(component.translateToLanguages)) {
-          throw new CliCommandError("Invalid sheet import plan: component translateToLanguages must be unique.", 2);
-        }
+        updateActionsByIssueId.set(actionIssueId, [...updateActionsByIssueId.get(actionIssueId) ?? [], action]);
+        return classification.patches;
       });
-      return;
+      const sortPatches = (patches) => [...patches].sort((left, right) => left.path.localeCompare(right.path));
+      if (canonicalJson(sortPatches(action.patches)) !== canonicalJson(sortPatches(expectedPatches))) {
+        throw new CliCommandError(
+          `Artifact validation failed: update action patches do not match classifications for ${action.exerciseId}`,
+          2,
+          true,
+          { code: "artifact_validation_failed", retryable: false }
+        );
+      }
+      continue;
     }
-    if (sheet.targetFolderPath === void 0) {
-      throw new CliCommandError("Invalid sheet import plan: targetFolderPath is required.", 2);
+    const source = inventoryByIssueId.get(action.issueId);
+    if (!source || source.exerciseId !== action.exerciseId) {
+      throw new CliCommandError("Artifact validation failed: triage action evidence differs from inventory", 2, true, {
+        code: "artifact_validation_failed",
+        retryable: false
+      });
     }
-    if (sheet.targetFolderPath !== null && !isValidTargetFolderPath2(sheet.targetFolderPath)) {
+    if (action.type === "resolve_quality_issue") {
+      resolveActionsByIssueId.set(action.issueId, [...resolveActionsByIssueId.get(action.issueId) ?? [], action]);
+    } else {
+      if (source.exerciseUpdatedAt !== action.expectedExerciseUpdatedAt) {
+        throw new CliCommandError("Artifact validation failed: dismissal evidence differs from inventory", 2, true, {
+          code: "artifact_validation_failed",
+          retryable: false
+        });
+      }
+      dismissActionsByIssueId.set(action.issueId, [...dismissActionsByIssueId.get(action.issueId) ?? [], action]);
+    }
+  }
+  const exclusionsByIssueId = new Map(actionPlan.exclusions.map((exclusion) => [exclusion.issueId, exclusion]));
+  assertUnique(
+    actionPlan.exclusions.map((exclusion) => exclusion.issueId),
+    "exclusion issueId"
+  );
+  for (const classification of classifications) {
+    const source = inventoryByIssueId.get(classification.issueId);
+    const updates = updateActionsByIssueId.get(classification.issueId) ?? [];
+    const resolves = resolveActionsByIssueId.get(classification.issueId) ?? [];
+    const dismissals = dismissActionsByIssueId.get(classification.issueId) ?? [];
+    const exclusion = exclusionsByIssueId.get(classification.issueId);
+    const exerciseUpdate = source ? updateActionsByExerciseId.get(source.exerciseId) : void 0;
+    if (classification.disposition === "proposed_dismissal" && dismissals.length === 1 && exerciseUpdate && (actionIndexById.get(dismissals[0].actionId) ?? Number.POSITIVE_INFINITY) > (actionIndexById.get(exerciseUpdate.actionId) ?? Number.NEGATIVE_INFINITY)) {
       throw new CliCommandError(
-        'Invalid sheet import plan: targetFolderPath must be a normalized folder path without "." or ".." segments.',
-        2
+        `Artifact validation failed: dismissal ${dismissals[0].actionId} must precede update ${exerciseUpdate.actionId}`,
+        2,
+        true,
+        { code: "artifact_validation_failed", retryable: false }
       );
     }
-    if (sheet.translateToLanguages && !hasUniqueItems2(sheet.translateToLanguages)) {
-      throw new CliCommandError("Invalid sheet import plan: translateToLanguages must be unique.", 2);
+    const valid = classification.disposition === "proposed_fix" && !exclusion && updates.length === 1 && resolves.length === 1 && dismissals.length === 0 && resolves[0]?.exerciseId === source?.exerciseId && resolves[0]?.expectedExerciseUpdatedAtFromActionId === updates[0]?.actionId && (actionIndexById.get(updates[0]?.actionId ?? "") ?? Number.POSITIVE_INFINITY) < (actionIndexById.get(resolves[0]?.actionId ?? "") ?? Number.NEGATIVE_INFINITY) || classification.disposition === "proposed_dismissal" && !exclusion && updates.length === 0 && resolves.length === 0 && dismissals.length === 1 || ["needs_human", "stale", "failed", "skipped"].includes(classification.disposition) && updates.length === 0 && resolves.length === 0 && dismissals.length === 0 && exclusion?.disposition === classification.disposition && exclusion.reasonCode === classification.reasonCode;
+    if (!valid) {
+      throw new CliCommandError(
+        `Artifact validation failed: action plan does not exactly implement ${classification.disposition} for ${classification.issueId}`,
+        2,
+        true,
+        { code: "artifact_validation_failed", retryable: false }
+      );
     }
-  });
-};
-var normalizeOptionalTitle = (value) => {
-  const normalizedValue = value?.trim();
-  if (!normalizedValue) {
-    return void 0;
   }
-  return normalizedValue;
-};
-var normalizeRequiredText = ({ label, value }) => {
-  const normalizedValue = value?.trim();
-  if (!normalizedValue) {
+  if ([...exclusionsByIssueId].some(([excludedIssueId]) => !classificationByIssueId.has(excludedIssueId))) {
+    throw new CliCommandError("Artifact validation failed: action plan contains an unexpected exclusion", 2, true, {
+      code: "artifact_validation_failed",
+      retryable: false
+    });
+  }
+  return { scope, discovery, candidates, inventory, classifications, actionPlan, results };
+};
+var digestQualityIssueRun = (run) => createHash("sha256").update(
+  JSON.stringify(
+    canonicalize({
+      scope: run.scope,
+      discovery: run.discovery,
+      candidates: run.candidates,
+      inventory: run.inventory,
+      classifications: run.classifications,
+      actionPlan: run.actionPlan
+    })
+  )
+).digest("hex");
+var reconcileQualityIssueRun = ({
+  actionPlan,
+  results
+}) => {
+  const planned = new Set(actionPlan.actions.map((action) => action.actionId));
+  const counts = /* @__PURE__ */ new Map();
+  for (const result of results) counts.set(result.actionId, (counts.get(result.actionId) ?? 0) + 1);
+  const missingActionIds = [...planned].filter((actionId) => !counts.has(actionId));
+  const duplicateActionIds = [...counts].filter(([, count]) => count > 1).map(([actionId]) => actionId);
+  const unexpectedActionIds = [...counts].filter(([actionId]) => !planned.has(actionId)).map(([actionId]) => actionId);
+  const resultByActionId = new Map(
+    results.filter((result) => counts.get(result.actionId) === 1).map((result) => [result.actionId, result])
+  );
+  const resultIndexByActionId = new Map(results.map((result, index) => [result.actionId, index]));
+  const sameStrings = (left, right) => canonicalJson([...left].sort()) === canonicalJson([...right].sort());
+  const semanticInvalidActionIds = actionPlan.actions.flatMap((action) => {
+    const result = resultByActionId.get(action.actionId);
+    if (!result || result.outcome !== "success") return [];
+    const receipt = result.receipt;
+    if (receipt.resource.type !== "exercise" || receipt.resource.id !== action.exerciseId || receipt.operation !== action.type || receipt.precondition.status !== "matched") {
+      return [action.actionId];
+    }
+    if (action.type === "update_exercise") {
+      const valid2 = result.resultingExerciseUpdatedAt !== void 0 && receipt.precondition.expectedUpdatedAt === action.expectedExerciseUpdatedAt && receipt.precondition.actualUpdatedAt === action.expectedExerciseUpdatedAt && sameStrings(
+        receipt.changedPaths,
+        action.patches.map((patch) => patch.path)
+      );
+      return valid2 ? [] : [action.actionId];
+    }
+    const expectedChangedPaths = [`qualityIssues.${action.issueId}.status`];
+    const details = receipt.details;
+    const expectedStatus = action.type === "resolve_quality_issue" ? "resolved" : "dismissed";
+    if (!sameStrings(receipt.changedPaths, expectedChangedPaths) || typeof details !== "object" || details === null || !("issueId" in details) || details.issueId !== action.issueId || !("status" in details) || details.status !== expectedStatus) {
+      return [action.actionId];
+    }
+    if (action.type === "dismiss_quality_issue") {
+      const valid2 = receipt.precondition.expectedUpdatedAt === action.expectedExerciseUpdatedAt && receipt.precondition.actualUpdatedAt === action.expectedExerciseUpdatedAt;
+      return valid2 ? [] : [action.actionId];
+    }
+    const dependencyResult = resultByActionId.get(action.expectedExerciseUpdatedAtFromActionId);
+    const dependencyIndex = resultIndexByActionId.get(action.expectedExerciseUpdatedAtFromActionId);
+    const resultIndex = resultIndexByActionId.get(action.actionId);
+    const expectedUpdatedAt = dependencyResult?.outcome === "success" ? dependencyResult.resultingExerciseUpdatedAt : void 0;
+    const valid = dependencyResult?.outcome === "success" && expectedUpdatedAt !== void 0 && dependencyIndex !== void 0 && resultIndex !== void 0 && dependencyIndex < resultIndex && receipt.precondition.expectedUpdatedAt === expectedUpdatedAt && receipt.precondition.actualUpdatedAt === expectedUpdatedAt;
+    return valid ? [] : [action.actionId];
+  });
+  const orderInvalidActionIds = missingActionIds.length === 0 && duplicateActionIds.length === 0 && unexpectedActionIds.length === 0 ? actionPlan.actions.flatMap(
+    (action, index) => results[index]?.actionId === action.actionId ? [] : [action.actionId]
+  ) : [];
+  const invalidActionIds = [.../* @__PURE__ */ new Set([...semanticInvalidActionIds, ...orderInvalidActionIds])];
+  return {
+    complete: missingActionIds.length === 0 && duplicateActionIds.length === 0 && unexpectedActionIds.length === 0 && invalidActionIds.length === 0,
+    missingActionIds,
+    duplicateActionIds,
+    unexpectedActionIds,
+    invalidActionIds
+  };
+};
+var verifyQualityIssueRun = (run, approvedDigest) => {
+  const actualDigest = digestQualityIssueRun(run);
+  if (actualDigest !== approvedDigest) {
+    throw new CliCommandError("Approved digest does not match the current action plan", 2, true, {
+      code: "approval_digest_mismatch",
+      retryable: false
+    });
+  }
+  return actualDigest;
+};
+
+// src/commands/quality-issue/index.ts
+var parseUuid = (value, label) => {
+  const result = z15.uuid().safeParse(value);
+  if (!result.success) throw new CliCommandError(`${label} must be a UUID.`, 2);
+  return result.data;
+};
+var parseUuidArray = (values, label) => {
+  if (values === void 0) return void 0;
+  const result = z15.array(z15.uuid()).min(1).max(100).safeParse(values);
+  if (!result.success) throw new CliCommandError(`${label} must contain 1 to 100 UUIDs.`, 2);
+  return result.data;
+};
+var registerQualityIssueCommands = (yargs2, context) => yargs2.command(
+  "list",
+  "List active quality issues for organization-owned exercises",
+  (listYargs) => listYargs.option("exercise-id", { type: "string", array: true, describe: "Restrict to exercise IDs" }).option("issue-id", { type: "string", array: true, describe: "Restrict to quality issue IDs" }).option("severity", {
+    type: "string",
+    array: true,
+    choices: ["warning", "error", "critical"]
+  }).option("limit", { type: "number", default: 50 }).option("cursor", { type: "string" }),
+  async (argv) => {
+    const common = argv;
+    if (argv.exerciseId && argv.issueId) {
+      throw new CliCommandError("--exercise-id and --issue-id are mutually exclusive.", 2);
+    }
+    const input = {
+      exerciseIds: parseUuidArray(argv.exerciseId, "exercise-id"),
+      issueIds: parseUuidArray(argv.issueId, "issue-id"),
+      severities: argv.severity,
+      limit: normalizeLimit(argv.limit),
+      cursor: argv.cursor
+    };
+    const { apiClient, organizationId } = await createResolvedApiClient({
+      context,
+      baseUrlFlagValue: common.baseUrl,
+      organizationFlagValue: common.organization,
+      profileName: common.profile
+    });
+    try {
+      const result = await apiClient.agentListQualityIssues(input);
+      context.output.print(
+        { request: { organizationId, ...input }, ...result },
+        `${result.issues.length} active quality issue(s)${result.nextCursor ? "; more available" : ""}`,
+        { command: "quality-issue list" }
+      );
+    } catch (error) {
+      throw mapApiErrorToCliError(error);
+    }
+  }
+).command(
+  "resolve <issueId>",
+  "Resolve one quality issue using the approved exercise timestamp",
+  (commandYargs) => commandYargs.positional("issueId", { type: "string", demandOption: true }).option("expected-exercise-updated-at", { type: "string", demandOption: true }),
+  async (argv) => {
+    const common = argv;
+    const input = {
+      issueId: parseUuid(argv.issueId, "issueId"),
+      expectedExerciseUpdatedAt: argv.expectedExerciseUpdatedAt
+    };
+    const { apiClient } = await createResolvedApiClient({
+      context,
+      baseUrlFlagValue: common.baseUrl,
+      organizationFlagValue: common.organization,
+      profileName: common.profile
+    });
+    try {
+      const result = await apiClient.agentResolveQualityIssue(input);
+      context.output.print(result, formatAgentWriteReceiptOutput, { command: "quality-issue resolve" });
+    } catch (error) {
+      throw mapApiErrorToCliError(error);
+    }
+  }
+).command(
+  "dismiss <issueId>",
+  "Dismiss one quality issue using the approved exercise timestamp",
+  (commandYargs) => commandYargs.positional("issueId", { type: "string", demandOption: true }).option("expected-exercise-updated-at", { type: "string", demandOption: true }),
+  async (argv) => {
+    const common = argv;
+    const input = {
+      issueId: parseUuid(argv.issueId, "issueId"),
+      expectedExerciseUpdatedAt: argv.expectedExerciseUpdatedAt
+    };
+    const { apiClient } = await createResolvedApiClient({
+      context,
+      baseUrlFlagValue: common.baseUrl,
+      organizationFlagValue: common.organization,
+      profileName: common.profile
+    });
+    try {
+      const result = await apiClient.agentDismissQualityIssue(input);
+      context.output.print(result, formatAgentWriteReceiptOutput, { command: "quality-issue dismiss" });
+    } catch (error) {
+      throw mapApiErrorToCliError(error);
+    }
+  }
+).command(
+  "artifact <subcommand>",
+  "Validate and reconcile local quality-issue run artifacts",
+  (artifactYargs) => artifactYargs.command(
+    "validate",
+    "Validate a quality-issue run partition",
+    (commandYargs) => commandYargs.option("run-dir", { type: "string", demandOption: true }),
+    async (argv) => {
+      const run = await validateQualityIssueRun(argv.runDir);
+      context.output.print(
+        {
+          runId: run.scope.runId,
+          organizationId: run.scope.organizationId,
+          inventoryCount: run.inventory.length,
+          classificationCount: run.classifications.length,
+          actionCount: run.actionPlan.actions.length,
+          resultCount: run.results.length
+        },
+        "Quality-issue run artifacts are valid.",
+        { command: "quality-issue artifact validate" }
+      );
+    }
+  ).command(
+    "digest",
+    "Compute the canonical action-plan digest",
+    (commandYargs) => commandYargs.option("run-dir", { type: "string", demandOption: true }),
+    async (argv) => {
+      const run = await validateQualityIssueRun(argv.runDir);
+      const digest = digestQualityIssueRun(run);
+      context.output.print({ digest }, digest, { command: "quality-issue artifact digest" });
+    }
+  ).command(
+    "verify",
+    "Verify an approved action-plan digest before writes",
+    (commandYargs) => commandYargs.option("run-dir", { type: "string", demandOption: true }).option("approved-digest", { type: "string", demandOption: true }),
+    async (argv) => {
+      const run = await validateQualityIssueRun(argv.runDir);
+      const digest = verifyQualityIssueRun(run, argv.approvedDigest);
+      context.output.print({ digest, verified: true }, "Approved digest verified.", {
+        command: "quality-issue artifact verify"
+      });
+    }
+  ).command(
+    "reconcile",
+    "Reconcile planned actions with terminal result rows",
+    (commandYargs) => commandYargs.option("run-dir", { type: "string", demandOption: true }),
+    async (argv) => {
+      const run = await validateQualityIssueRun(argv.runDir);
+      const reconciliation = reconcileQualityIssueRun(run);
+      context.output.print(
+        reconciliation,
+        reconciliation.complete ? "Reconciliation complete." : "Reconciliation incomplete.",
+        {
+          command: "quality-issue artifact reconcile",
+          ok: reconciliation.complete
+        }
+      );
+      if (!reconciliation.complete) throwSilentExitCode(2);
+    }
+  ).demandCommand(1),
+  () => {
+  }
+).demandCommand(1);
+
+// src/commands/sheet.ts
+import { z as z16 } from "zod";
+
+// src/lib/result-artifact.ts
+import { randomUUID } from "node:crypto";
+import { link, open as open2, unlink } from "node:fs/promises";
+import { basename as basename3, dirname as dirname2, join as join3, resolve as resolve7 } from "node:path";
+
+// src/lib/output.ts
+var cliJsonSchemaVersion = "v1";
+var ensureTrailingNewline = (value) => {
+  return value.endsWith("\n") ? value : `${value}
+`;
+};
+var writeLine = (writer, value) => {
+  writer.write(ensureTrailingNewline(value));
+};
+var serializeCliOutputEnvelope = (envelope) => JSON.stringify(envelope, null, 2);
+var createCliOutputEnvelope = ({
+  command,
+  error,
+  ok,
+  result,
+  warnings
+}) => ({
+  schemaVersion: cliJsonSchemaVersion,
+  command,
+  ok,
+  ...result === void 0 ? {} : { result },
+  ...error ? { error } : {},
+  warnings
+});
+var createOutput = ({
+  json,
+  stdout,
+  stderr
+}) => {
+  let warnings = [];
+  const consumeWarnings = () => {
+    const nextWarnings = warnings;
+    warnings = [];
+    return nextWarnings;
+  };
+  return {
+    json,
+    print: (value, humanFormatter, options) => {
+      if (json) {
+        writeLine(
+          stdout,
+          serializeCliOutputEnvelope(
+            createCliOutputEnvelope({
+              command: options.command,
+              error: options.error,
+              ok: options.ok ?? true,
+              result: value,
+              warnings: consumeWarnings()
+            })
+          )
+        );
+        return;
+      }
+      const message = typeof humanFormatter === "function" ? humanFormatter(value) : humanFormatter;
+      writeLine(stdout, message);
+    },
+    printWithResultArtifact: async (value, compactValue, humanFormatter, options) => {
+      const currentWarnings = [...warnings];
+      await options.publishArtifact(
+        createCliOutputEnvelope({
+          command: options.command,
+          error: options.error,
+          ok: options.ok ?? true,
+          result: value,
+          warnings: currentWarnings
+        })
+      );
+      warnings = warnings.slice(currentWarnings.length);
+      if (json) {
+        writeLine(
+          stdout,
+          serializeCliOutputEnvelope(
+            createCliOutputEnvelope({
+              command: options.command,
+              error: options.error,
+              ok: options.ok ?? true,
+              result: compactValue,
+              warnings: currentWarnings
+            })
+          )
+        );
+        return;
+      }
+      const message = typeof humanFormatter === "function" ? humanFormatter(compactValue) : humanFormatter;
+      writeLine(stdout, message);
+    },
+    printError: ({ command, error, result }) => {
+      if (json) {
+        writeLine(
+          stdout,
+          serializeCliOutputEnvelope(
+            createCliOutputEnvelope({
+              command,
+              ok: false,
+              result,
+              error,
+              warnings: consumeWarnings()
+            })
+          )
+        );
+        return;
+      }
+      writeLine(stderr, formatSerializableCliErrorForHuman(error));
+    },
+    info: (message) => {
+      if (json) {
+        warnings.push(message);
+        return;
+      }
+      writeLine(stderr, message);
+    },
+    error: (message) => {
+      writeLine(stderr, message);
+    }
+  };
+};
+
+// src/lib/result-artifact.ts
+var resolveCliResultFilePath = ({ cwd, inputPath }) => resolve7(cwd, inputPath);
+var getFilesystemErrorCode = (error) => error.code;
+var publishCliResultArtifact = async ({
+  destinationPath,
+  envelope
+}) => {
+  const temporaryPath = join3(dirname2(destinationPath), `.${basename3(destinationPath)}.${randomUUID()}.tmp`);
+  let temporaryFile;
+  try {
+    temporaryFile = await open2(temporaryPath, "wx", 384);
+    await temporaryFile.writeFile(`${serializeCliOutputEnvelope(envelope)}
+`, "utf8");
+    await temporaryFile.sync();
+    await temporaryFile.close();
+    temporaryFile = void 0;
+    await link(temporaryPath, destinationPath);
+  } catch (error) {
+    if (getFilesystemErrorCode(error) === "EEXIST") {
+      throw new CliCommandError(`Result file "${destinationPath}" already exists; choose another path.`, 2);
+    }
+    const message = error instanceof Error ? error.message : "Unknown filesystem error";
+    throw new CliCommandError(`Could not write result file "${destinationPath}": ${message}`, 1);
+  } finally {
+    await temporaryFile?.close().catch(() => {
+    });
+    await unlink(temporaryPath).catch(() => {
+    });
+  }
+};
+
+// src/lib/sheet-list-all.ts
+var pageSize = 100;
+var collectAllSheets = async ({
+  fetchPage
+}) => {
+  const sheets = [];
+  const seenSheetIds = /* @__PURE__ */ new Set();
+  const duplicateSheetIds = /* @__PURE__ */ new Set();
+  const seenPageSignatures = /* @__PURE__ */ new Set();
+  const observedTotalCounts = [];
+  const observedInventoryTokens = [];
+  const issues = [];
+  const warnings = [];
+  let afterId;
+  let pagesFetched = 0;
+  let rowsFetched = 0;
+  const addIssue = (issue, warning) => {
+    if (issues.includes(issue)) {
+      return;
+    }
+    issues.push(issue);
+    warnings.push(warning);
+  };
+  while (true) {
+    const page = await fetchPage({ limit: pageSize, ...afterId ? { afterId } : {} });
+    pagesFetched += 1;
+    rowsFetched += page.sheets.length;
+    observedTotalCounts.push(page.totalCount);
+    observedInventoryTokens.push(page.inventoryToken);
+    const firstObservedTotal = observedTotalCounts[0];
+    if (page.totalCount !== firstObservedTotal) {
+      addIssue(
+        "total_count_changed",
+        `Sheet inventory total changed during collection (${firstObservedTotal} -> ${page.totalCount}).`
+      );
+    }
+    const firstInventoryToken = observedInventoryTokens[0];
+    if (page.inventoryToken !== firstInventoryToken) {
+      addIssue(
+        "inventory_changed",
+        `Sheet inventory membership changed during collection (${firstInventoryToken} -> ${page.inventoryToken}).`
+      );
+    }
+    if (page.sheets.length === 0) {
+      if (sheets.length < page.totalCount) {
+        addIssue(
+          "early_empty_page",
+          `Sheet inventory returned an empty page${afterId ? ` after cursor ${afterId}` : ""} before the observed total of ${page.totalCount}.`
+        );
+      }
+      break;
+    }
+    const pageSignature = page.sheets.map(({ id }) => id).join("\n");
+    if (seenPageSignatures.has(pageSignature)) {
+      addIssue(
+        "repeated_page",
+        `Sheet inventory page${afterId ? ` after cursor ${afterId}` : ""} repeated an earlier page; collection stopped.`
+      );
+      break;
+    }
+    seenPageSignatures.add(pageSignature);
+    for (const sheet of page.sheets) {
+      if (seenSheetIds.has(sheet.id)) {
+        duplicateSheetIds.add(sheet.id);
+        continue;
+      }
+      seenSheetIds.add(sheet.id);
+      sheets.push(sheet);
+    }
+    if (duplicateSheetIds.size > 0) {
+      addIssue(
+        "duplicate_sheet_ids",
+        `Sheet inventory pages repeated ${duplicateSheetIds.size} sheet ID${duplicateSheetIds.size === 1 ? "" : "s"}; the snapshot may be incomplete.`
+      );
+    }
+    if (rowsFetched >= page.totalCount) {
+      break;
+    }
+    if (page.sheets.length < pageSize) {
+      addIssue(
+        "early_short_page",
+        `Sheet inventory returned only ${page.sheets.length} sheets${afterId ? ` after cursor ${afterId}` : ""} before the observed total of ${page.totalCount}.`
+      );
+      break;
+    }
+    afterId = page.sheets.at(-1).id;
+  }
+  const totalCount = observedTotalCounts.at(-1) ?? 0;
+  if (sheets.length !== totalCount) {
+    addIssue(
+      "sheet_count_mismatch",
+      `Collected ${sheets.length} unique sheets but the final observed total was ${totalCount}.`
+    );
+  }
+  return {
+    sheets,
+    totalCount,
+    snapshot: {
+      complete: issues.length === 0,
+      pageSize,
+      pagesFetched,
+      observedTotalCounts,
+      observedInventoryTokens,
+      uniqueSheetCount: sheets.length,
+      duplicateSheetIds: [...duplicateSheetIds],
+      issues
+    },
+    warnings
+  };
+};
+
+// src/commands/sheet.ts
+var readinessIssueTypeLabels = {
+  missing_translation: "missing translations",
+  missing_solution: "missing solutions",
+  invalid_latex: "invalid LaTeX",
+  missing_score: "missing scores",
+  exercise_quality_issue: "exercise quality issues"
+};
+var normalizeReadinessFilters = ({
+  issueTypes,
+  needsWork,
+  ready
+}) => {
+  if (needsWork && ready) {
+    throw new CliCommandError("--needs-work and --ready cannot be used together.", 2);
+  }
+  return {
+    hasIssues: needsWork ? true : ready ? false : null,
+    issueTypes: normalizeChoiceValues({
+      allowedValues: sheetReadinessIssueTypes,
+      label: "--issue-type",
+      values: issueTypes
+    }) ?? []
+  };
+};
+var normalizeSheetSeriesPath = (value) => {
+  const normalizedValue = normalizeOptionalText(value);
+  if (normalizedValue === null) {
+    return null;
+  }
+  const parsedValue = sheetSeriesPathSchema.safeParse(normalizedValue);
+  if (!parsedValue.success) {
+    throw new CliCommandError(
+      '--series-path is unknown. Run "chalksurf sheet series list --json" to inspect valid paths.',
+      2
+    );
+  }
+  return parsedValue.data;
+};
+var normalizeSheetSeriesYearFilter = ({ fromYear, toYear }) => {
+  if (fromYear === void 0 && toYear === void 0) {
+    return null;
+  }
+  if (fromYear !== void 0 && toYear !== void 0 && fromYear > toYear) {
+    throw new CliCommandError("--from-year must be less than or equal to --to-year.", 2);
+  }
+  const parsedFilter = sheetSeriesYearFilterSchema.safeParse({ fromYear, toYear });
+  if (!parsedFilter.success) {
+    throw new CliCommandError("--from-year and --to-year must be four-digit years.", 2);
+  }
+  return parsedFilter.data;
+};
+var hasUniqueItems2 = (values) => new Set(values).size === values.length;
+var sheetImportComponentIdPattern3 = /^[a-zA-Z0-9_-]{1,80}$/;
+var isValidTargetFolderPath2 = (value) => {
+  const normalizedSegments = value.replaceAll("\\", "/").split("/").filter((segment) => segment.length > 0);
+  return normalizedSegments.length > 0 && normalizedSegments.every((segment) => segment !== "." && segment !== "..");
+};
+var assertValidSheetImportPlan = (plan) => {
+  if (plan.sheets.length === 0) {
+    throw new CliCommandError("Invalid sheet import plan: sheets must include at least one sheet.", 2);
+  }
+  plan.sheets.forEach((sheet) => {
+    if (sheet.sourceIndexes.length === 0) {
+      throw new CliCommandError("Invalid sheet import plan: sourceIndexes must include at least one source.", 2);
+    }
+    if (!sheet.sourceIndexes.every((sourceIndex) => Number.isInteger(sourceIndex) && sourceIndex >= 0)) {
+      throw new CliCommandError("Invalid sheet import plan: sourceIndexes must contain only non-negative integers.", 2);
+    }
+    if (!hasUniqueItems2(sheet.sourceIndexes)) {
+      throw new CliCommandError("Invalid sheet import plan: sourceIndexes must be unique within a sheet.", 2);
+    }
+    if (sheet.components) {
+      if (sheet.targetFolderPath !== void 0 || sheet.titleOverride !== void 0 || sheet.translateToLanguages) {
+        throw new CliCommandError(
+          "Invalid sheet import plan: targetFolderPath, titleOverride, and translateToLanguages must be set on components when components are provided.",
+          2
+        );
+      }
+      if (!hasUniqueItems2(sheet.components.map((component) => component.componentId))) {
+        throw new CliCommandError("Invalid sheet import plan: componentId values must be unique within a sheet.", 2);
+      }
+      sheet.components.forEach((component) => {
+        if (!sheetImportComponentIdPattern3.test(component.componentId)) {
+          throw new CliCommandError(
+            "Invalid sheet import plan: componentId must be 1-80 letters, numbers, underscores, or hyphens.",
+            2
+          );
+        }
+        if (!component.description.trim()) {
+          throw new CliCommandError("Invalid sheet import plan: component descriptions must be non-empty.", 2);
+        }
+        if (component.targetFolderPath != null && !isValidTargetFolderPath2(component.targetFolderPath)) {
+          throw new CliCommandError(
+            'Invalid sheet import plan: component targetFolderPath must be a normalized folder path without "." or ".." segments.',
+            2
+          );
+        }
+        if (component.translateToLanguages && !hasUniqueItems2(component.translateToLanguages)) {
+          throw new CliCommandError("Invalid sheet import plan: component translateToLanguages must be unique.", 2);
+        }
+      });
+      return;
+    }
+    if (sheet.targetFolderPath === void 0) {
+      throw new CliCommandError("Invalid sheet import plan: targetFolderPath is required.", 2);
+    }
+    if (sheet.targetFolderPath !== null && !isValidTargetFolderPath2(sheet.targetFolderPath)) {
+      throw new CliCommandError(
+        'Invalid sheet import plan: targetFolderPath must be a normalized folder path without "." or ".." segments.',
+        2
+      );
+    }
+    if (sheet.translateToLanguages && !hasUniqueItems2(sheet.translateToLanguages)) {
+      throw new CliCommandError("Invalid sheet import plan: translateToLanguages must be unique.", 2);
+    }
+  });
+};
+var normalizeOptionalTitle = (value) => {
+  const normalizedValue = value?.trim();
+  if (!normalizedValue) {
+    return void 0;
+  }
+  return normalizedValue;
+};
+var normalizeRequiredText = ({ label, value }) => {
+  const normalizedValue = value?.trim();
+  if (!normalizedValue) {
     throw new CliCommandError(`${label} is required.`, 2);
   }
   return normalizedValue;
@@ -12187,7 +13286,7 @@ var resolveRequestedUuid2 = ({
     }
     return void 0;
   }
-  const parsedValue = z14.uuid().safeParse(resolvedValue);
+  const parsedValue = z16.uuid().safeParse(resolvedValue);
   if (!parsedValue.success) {
     throw new CliCommandError(`${label} must be a valid UUID.`, 2);
   }
@@ -12198,7 +13297,7 @@ var resolveRequestedUuidList = ({ label, values }) => {
     throw new CliCommandError(`${label} is required at least once.`, 2);
   }
   return values.map((value, index) => {
-    const parsedValue = z14.uuid().safeParse(value.trim());
+    const parsedValue = z16.uuid().safeParse(value.trim());
     if (!parsedValue.success) {
       throw new CliCommandError(`${label}[${index}] must be a valid UUID.`, 2);
     }
@@ -12607,22 +13706,26 @@ var formatDeleteSheetOutput = ({ receipt }) => {
 var formatUpdateSheetOutput = ({ receipt }) => {
   return formatAgentWriteReceiptOutput({ receipt });
 };
-var formatBulkUpdateSheetsOutput = ({
-  confirmationDigest,
-  mode,
-  receipt,
-  results
-}) => {
-  const summary = results.reduce(
+var getBulkUpdateSheetsCounts = ({ results }) => {
+  const statusCounts = results.reduce(
     (counts, result) => ({
       ...counts,
       [result.status]: counts[result.status] + 1
     }),
     { ready: 0, unchanged: 0, updated: 0, error: 0 }
   );
+  return { total: results.length, ...statusCounts };
+};
+var formatBulkUpdateSheetsOutput = ({
+  confirmationDigest,
+  mode,
+  receipt,
+  results
+}) => {
+  const counts = getBulkUpdateSheetsCounts({ confirmationDigest, mode, receipt, results });
   const lines = [
-    `${mode === "dry_run" ? "Validated" : "Applied"} ${results.length} sheet update${results.length === 1 ? "" : "s"}.`,
-    `ready: ${summary.ready}  updated: ${summary.updated}  unchanged: ${summary.unchanged}  errors: ${summary.error}`,
+    `${mode === "dry_run" ? "Validated" : "Applied"} ${counts.total} sheet update${counts.total === 1 ? "" : "s"}.`,
+    `ready: ${counts.ready}  updated: ${counts.updated}  unchanged: ${counts.unchanged}  errors: ${counts.error}`,
     `confirmation digest: ${confirmationDigest}`
   ];
   if (receipt) {
@@ -12630,6 +13733,161 @@ var formatBulkUpdateSheetsOutput = ({
   }
   return lines.join("\n");
 };
+var formatVerifyBulkSheetUpdatesOutput = ({ counts, state }) => [
+  `Verification state: ${state}.`,
+  `total: ${counts.total}  applied: ${counts.applied}  pending: ${counts.pending}  conflicting: ${counts.conflicting}  errors: ${counts.error}`
+].join("\n");
+var printWithOptionalResultArtifact = async ({
+  command,
+  compactHumanFormatter,
+  compactValue,
+  context,
+  fullHumanFormatter,
+  fullValue,
+  resultFileInput
+}) => {
+  if (resultFileInput === void 0) {
+    context.output.print(fullValue, fullHumanFormatter, { command });
+    return;
+  }
+  if (!resultFileInput.trim()) {
+    throw new CliCommandError("--result-file must be a non-empty path.", 2);
+  }
+  const resultFile = resolveCliResultFilePath({ cwd: context.cwd, inputPath: resultFileInput });
+  await context.output.printWithResultArtifact(fullValue, { ...compactValue, resultFile }, compactHumanFormatter, {
+    command,
+    publishArtifact: async (envelope) => await publishCliResultArtifact({
+      destinationPath: resultFile,
+      envelope
+    })
+  });
+};
+var configureBulkJsonInputOptions = (commandYargs, description) => commandYargs.option("input", {
+  type: "string",
+  nargs: 1,
+  describe: 'Read the JSON object from a UTF-8 file, or "-" for stdin'
+}).option("input-json", {
+  type: "string",
+  nargs: 1,
+  describe: description
+}).option("result-file", {
+  type: "string",
+  nargs: 1,
+  describe: "Publish the complete JSON result envelope to a new private file"
+});
+var runBulkUpdateCommand = async (argv, context) => {
+  const args = argv;
+  if (args.resultFile !== void 0 && !args.resultFile.trim()) {
+    throw new CliCommandError("--result-file must be a non-empty path.", 2);
+  }
+  const input = parseBulkUpdateSheetsAgentInput(
+    await loadJsonObjectInput({
+      cwd: context.cwd,
+      inputJson: args.inputJson,
+      inputPath: args.input,
+      stdin: context.stdin
+    })
+  );
+  const { apiClient, organizationId } = await createResolvedApiClient({
+    context,
+    baseUrlFlagValue: args.baseUrl,
+    organizationFlagValue: args.organization,
+    profileName: args.profile
+  });
+  let result;
+  try {
+    result = await apiClient.agentBulkUpdateSheets(input);
+  } catch (error) {
+    throw mapApiErrorToCliError(error);
+  }
+  const fullValue = {
+    request: {
+      ...input,
+      organizationId: organizationId ?? null
+    },
+    ...result
+  };
+  const counts = getBulkUpdateSheetsCounts(result);
+  try {
+    await printWithOptionalResultArtifact({
+      command: "sheet bulk-update",
+      compactHumanFormatter: ({ confirmationDigest, counts: counts2, mode, receiptPresent, resultFile }) => [
+        `${mode === "dry_run" ? "Validated" : "Applied"} ${counts2.total} sheet update${counts2.total === 1 ? "" : "s"}.`,
+        `ready: ${counts2.ready}  updated: ${counts2.updated}  unchanged: ${counts2.unchanged}  errors: ${counts2.error}`,
+        `confirmation digest: ${confirmationDigest}`,
+        `receipt: ${receiptPresent ? "present" : "none"}`,
+        `full result: ${resultFile}`
+      ].join("\n"),
+      compactValue: {
+        mode: result.mode,
+        counts,
+        confirmationDigest: result.confirmationDigest,
+        receiptPresent: result.receipt !== null
+      },
+      context,
+      fullHumanFormatter: (output) => formatBulkUpdateSheetsOutput(output),
+      fullValue,
+      resultFileInput: args.resultFile
+    });
+  } catch (error) {
+    if (input.mode !== "apply") {
+      throw error;
+    }
+    const message = error instanceof Error ? error.message : "Unknown result artifact error";
+    context.output.info(
+      `The server confirmed the bulk apply, but the result artifact could not be published: ${message} Do not retry the apply; preserve this stdout response and use "sheet bulk-update verify" with the original manifest if independent recovery is needed.`
+    );
+    context.output.print(fullValue, (output) => formatBulkUpdateSheetsOutput(output), {
+      command: "sheet bulk-update"
+    });
+  }
+};
+var runVerifyBulkSheetUpdatesCommand = async (argv, context) => {
+  const args = argv;
+  const input = parseVerifyBulkSheetUpdatesAgentInput(
+    await loadJsonObjectInput({
+      cwd: context.cwd,
+      inputJson: args.inputJson,
+      inputPath: args.input,
+      stdin: context.stdin
+    })
+  );
+  const { apiClient, organizationId } = await createResolvedApiClient({
+    context,
+    baseUrlFlagValue: args.baseUrl,
+    organizationFlagValue: args.organization,
+    profileName: args.profile
+  });
+  let result;
+  try {
+    result = await apiClient.agentVerifyBulkSheetUpdates(input);
+  } catch (error) {
+    throw mapApiErrorToCliError(error);
+  }
+  const fullValue = {
+    request: {
+      ...input,
+      organizationId: organizationId ?? null
+    },
+    ...result
+  };
+  await printWithOptionalResultArtifact({
+    command: "sheet bulk-update verify",
+    compactHumanFormatter: ({ counts, resultFile, state }) => [
+      `Verification state: ${state}.`,
+      `total: ${counts.total}  applied: ${counts.applied}  pending: ${counts.pending}  conflicting: ${counts.conflicting}  errors: ${counts.error}`,
+      `full result: ${resultFile}`
+    ].join("\n"),
+    compactValue: {
+      state: result.state,
+      counts: result.counts
+    },
+    context,
+    fullHumanFormatter: (output) => formatVerifyBulkSheetUpdatesOutput(output),
+    fullValue,
+    resultFileInput: args.resultFile
+  });
+};
 var formatSheetSeriesOutput = ({ series }) => series.map(({ depth, names, path }) => `${"  ".repeat(depth)}${names.english}  ${path}`).join("\n");
 var formatSetSheetVisibilityOutput = ({ receipt }) => {
   return formatAgentWriteReceiptOutput({ receipt });
@@ -12686,13 +13944,25 @@ var registerSheetCommands = (sheetYargs, context) => {
       describe: "Include sheets in descendant folders; requires --folder-id"
     }).option("limit", {
       type: "number",
-      default: 50,
       describe: "Maximum number of sheets to return"
     }).option("offset", {
       type: "number",
-      default: 0,
       describe: "Number of organization-owned sheets to skip"
+    }).option("after-id", {
+      type: "string",
+      describe: "Return sheets with IDs after this keyset cursor; cannot be combined with --offset"
+    }).option("all", {
+      type: "boolean",
+      default: false,
+      describe: "Collect every organization-owned sheet in sequential pages of 100"
+    }).option("result-file", {
+      type: "string",
+      nargs: 1,
+      describe: "Publish the complete JSON result envelope to a new private file"
     }).example("chalksurf --profile prod-codex sheet list --json", "List sheets owned by the selected organization").example(
+      "chalksurf --profile prod-codex sheet list --all --result-file inventory.json --json",
+      "Save a complete reviewed inventory"
+    ).example(
       "chalksurf --profile prod-codex sheet list --folder-id 00000000-0000-4000-8000-000000000001 --include-descendants --json",
       "List a folder subtree"
     ),
@@ -12705,8 +13975,21 @@ var registerSheetCommands = (sheetYargs, context) => {
       if (includeDescendants && !folderId) {
         throw new CliCommandError("--folder-id is required with --include-descendants.", 2);
       }
-      const limit = normalizeLimit(argv.limit);
-      const offset = normalizeOffset(argv.offset);
+      const collectAll = Boolean(argv.all);
+      const afterId = resolveRequestedUuid2({
+        flagValue: argv.afterId,
+        label: "--after-id"
+      });
+      const limitArgument = argv.limit;
+      const offsetArgument = argv.offset;
+      if (collectAll && (limitArgument !== void 0 || offsetArgument !== void 0 || afterId !== void 0)) {
+        throw new CliCommandError("--all cannot be combined with --limit, --offset, or --after-id.", 2);
+      }
+      if (afterId !== void 0 && offsetArgument !== void 0 && offsetArgument !== 0) {
+        throw new CliCommandError("--after-id cannot be combined with a non-zero --offset.", 2);
+      }
+      const limit = collectAll ? null : normalizeLimit(limitArgument ?? 50);
+      const offset = collectAll ? null : normalizeOffset(offsetArgument);
       const { apiClient, organizationId } = await createResolvedApiClient({
         context,
         baseUrlFlagValue: argv.baseUrl,
@@ -12715,31 +13998,61 @@ var registerSheetCommands = (sheetYargs, context) => {
       });
       let result;
       try {
-        result = await apiClient.agentListSheets({
-          folderId,
-          includeDescendants,
-          limit,
-          offset
-        });
+        if (collectAll) {
+          const collected = await collectAllSheets({
+            fetchPage: async ({ afterId: pageAfterId, limit: pageLimit }) => await apiClient.agentListSheets({
+              afterId: pageAfterId,
+              folderId,
+              includeDescendants,
+              limit: pageLimit,
+              offset: 0
+            })
+          });
+          for (const warning of collected.warnings) {
+            context.output.info(warning);
+          }
+          result = {
+            sheets: collected.sheets,
+            totalCount: collected.totalCount,
+            snapshot: collected.snapshot
+          };
+        } else {
+          result = await apiClient.agentListSheets({
+            afterId,
+            folderId,
+            includeDescendants,
+            limit,
+            offset
+          });
+        }
       } catch (error) {
         throw mapApiErrorToCliError(error);
       }
-      context.output.print(
-        {
-          request: {
-            folderId: folderId ?? null,
-            includeDescendants,
-            limit,
-            offset,
-            organizationId: organizationId ?? null
-          },
-          ...result
+      const fullValue = {
+        request: {
+          ...collectAll ? { all: true } : {},
+          ...afterId ? { afterId } : {},
+          folderId: folderId ?? null,
+          includeDescendants,
+          limit,
+          offset,
+          organizationId: organizationId ?? null
         },
-        (output) => formatSheetListOutput(output),
-        {
-          command: "sheet list"
-        }
-      );
+        ...result
+      };
+      await printWithOptionalResultArtifact({
+        command: "sheet list",
+        compactHumanFormatter: ({ resultFile, sheetCount, snapshotComplete }) => `Saved ${sheetCount} sheet${sheetCount === 1 ? "" : "s"} to ${resultFile}.${snapshotComplete === false ? " Snapshot is incomplete." : ""}`,
+        compactValue: {
+          sheetCount: result.sheets.length,
+          totalCount: result.totalCount,
+          snapshotComplete: "snapshot" in result ? result.snapshot.complete : null
+        },
+        context,
+        fullHumanFormatter: (output) => formatSheetListOutput(output),
+        fullValue,
+        resultFileInput: argv.resultFile
+      });
     }
   ).command(
     "search",
@@ -13731,58 +15044,35 @@ var registerSheetCommands = (sheetYargs, context) => {
       );
     }
   ).command(
-    "bulk-update",
-    "Dry-run or apply up to 100 sheet patches",
-    (bulkUpdateYargs) => bulkUpdateYargs.option("input", {
-      type: "string",
-      nargs: 1,
-      describe: 'Read the bulk update JSON object from a UTF-8 file, or "-" for stdin'
-    }).option("input-json", {
-      type: "string",
-      nargs: 1,
-      describe: "Inline JSON matching the bulk update contract: mode, updates, and confirmationDigest for apply mode"
-    }).example(
-      "chalksurf sheet bulk-update --input batch-001.json --json",
-      "Validate a reviewed bulk-update batch from a file"
-    ).example(
-      "cat batch-001.json | chalksurf sheet bulk-update --input - --json",
-      "Validate a reviewed bulk-update batch from stdin"
-    ).example(
-      `chalksurf sheet bulk-update --input-json '{"mode":"dry_run","updates":[{"id":"00000000-0000-4000-8000-000000000001","expectedUpdatedAt":"2026-01-01T00:00:00.000Z","patch":{"seriesAssignments":[{"seriesPath":"international.imo","editionYear":2025}]}}]}' --json`,
-      "Validate sheet-series assignments and obtain a confirmation digest"
+    "bulk-update [subcommand]",
+    "Bulk sheet update and recovery commands",
+    (bulkUpdateYargs) => bulkUpdateYargs.command(
+      "$0",
+      "Dry-run or apply up to 100 sheet patches",
+      (runYargs) => configureBulkJsonInputOptions(
+        runYargs,
+        "Inline JSON with mode, updates, and confirmationDigest for apply mode"
+      ).example(
+        "chalksurf sheet bulk-update --input batch-001.json --result-file dry-run.json --json",
+        "Validate a reviewed batch and save the complete result"
+      ).example(
+        "cat batch-001.json | chalksurf sheet bulk-update --input - --json",
+        "Validate a reviewed batch from stdin"
+      ).example('chalksurf sheet bulk-update --input-json "$BATCH_JSON" --json', "Validate an inline batch"),
+      async (argv) => await runBulkUpdateCommand(argv, context)
+    ).command(
+      "verify",
+      "Verify current targets after an uncertain bulk apply response",
+      (verifyYargs) => configureBulkJsonInputOptions(
+        verifyYargs,
+        "Inline JSON containing updates, or a prior dry-run/apply manifest"
+      ).example(
+        "chalksurf sheet bulk-update verify --input batch-001.json --result-file verification.json --json",
+        "Classify the current state of every target in a batch"
+      ),
+      async (argv) => await runVerifyBulkSheetUpdatesCommand(argv, context)
     ),
-    async (argv) => {
-      const input = parseBulkUpdateSheetsAgentInput(
-        await loadJsonObjectInput({
-          cwd: context.cwd,
-          inputJson: argv.inputJson,
-          inputPath: argv.input,
-          stdin: context.stdin
-        })
-      );
-      const { apiClient, organizationId } = await createResolvedApiClient({
-        context,
-        baseUrlFlagValue: argv.baseUrl,
-        organizationFlagValue: argv.organization,
-        profileName: argv.profile
-      });
-      let result;
-      try {
-        result = await apiClient.agentBulkUpdateSheets(input);
-      } catch (error) {
-        throw mapApiErrorToCliError(error);
-      }
-      context.output.print(
-        {
-          request: {
-            ...input,
-            organizationId: organizationId ?? null
-          },
-          ...result
-        },
-        (output) => formatBulkUpdateSheetsOutput(output),
-        { command: "sheet bulk-update" }
-      );
+    () => {
     }
   ).command(
     "import [sources..]",
@@ -14172,84 +15462,6 @@ var registerSheetCommands = (sheetYargs, context) => {
   ).demandCommand(1).strict();
 };
 
-// src/lib/output.ts
-var cliJsonSchemaVersion = "v1";
-var ensureTrailingNewline = (value) => {
-  return value.endsWith("\n") ? value : `${value}
-`;
-};
-var writeLine = (writer, value) => {
-  writer.write(ensureTrailingNewline(value));
-};
-var createOutput = ({
-  json,
-  stdout,
-  stderr
-}) => {
-  let warnings = [];
-  const consumeWarnings = () => {
-    const nextWarnings = warnings;
-    warnings = [];
-    return nextWarnings;
-  };
-  return {
-    json,
-    print: (value, humanFormatter, options) => {
-      if (json) {
-        writeLine(
-          stdout,
-          JSON.stringify(
-            {
-              schemaVersion: cliJsonSchemaVersion,
-              command: options.command,
-              ok: options.ok ?? true,
-              result: value,
-              ...options.error ? { error: options.error } : {},
-              warnings: consumeWarnings()
-            },
-            null,
-            2
-          )
-        );
-        return;
-      }
-      const message = typeof humanFormatter === "function" ? humanFormatter(value) : humanFormatter;
-      writeLine(stdout, message);
-    },
-    printError: ({ command, error, result }) => {
-      if (json) {
-        writeLine(
-          stdout,
-          JSON.stringify(
-            {
-              schemaVersion: cliJsonSchemaVersion,
-              command,
-              ok: false,
-              ...result === void 0 ? {} : { result },
-              error,
-              warnings: consumeWarnings()
-            },
-            null,
-            2
-          )
-        );
-        return;
-      }
-      writeLine(stderr, formatSerializableCliErrorForHuman(error));
-    },
-    info: (message) => {
-      if (json) {
-        warnings.push(message);
-        return;
-      }
-      writeLine(stderr, message);
-    },
-    error: (message) => {
-      writeLine(stderr, message);
-    }
-  };
-};
-
 // src/lib/prompt-secret.ts
 import { createInterface } from "node:readline/promises";
 import { Writable } from "node:stream";
@@ -14287,11 +15499,13 @@ var createPromptSecret = ({
 };
 
 // src/bin/chalksurf.ts
+var getHelpWidth = (stdout) => stdout.columns === void 0 ? null : Math.min(120, Math.max(80, stdout.columns));
 var packageJson = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
 var createCli = ({
   cwd,
   configPath,
   env,
+  helpWidth,
   now,
   output,
   sleep,
@@ -14308,7 +15522,7 @@ var createCli = ({
     sleep,
     stdin
   };
-  return yargs().scriptName("chalksurf").usage("$0 <command> [options]").version(false).option("json", {
+  return yargs().wrap(helpWidth).scriptName("chalksurf").usage("$0 <command> [options]").version(false).option("json", {
     type: "boolean",
     default: false,
     describe: "Write machine-readable JSON to stdout"
@@ -14352,6 +15566,12 @@ var createCli = ({
     (exerciseYargs) => registerExerciseCommands(exerciseYargs, commandContext),
     () => {
     }
+  ).command(
+    "quality-issue <subcommand>",
+    "Exercise quality issue review commands",
+    (qualityIssueYargs) => registerQualityIssueCommands(qualityIssueYargs, commandContext),
+    () => {
+    }
   ).command(
     "feedback <subcommand>",
     "Feedback commands",
@@ -14391,7 +15611,7 @@ var parseCliWithCapturedOutput = async ({
   argv,
   stdout
 }) => {
-  await new Promise((resolve7, reject) => {
+  await new Promise((resolve8, reject) => {
     cli.parse(argv, (error, _parsedArgv, output) => {
       if (output) {
         stdout.write(output);
@@ -14400,14 +15620,24 @@ var parseCliWithCapturedOutput = async ({
         reject(error);
         return;
       }
-      resolve7();
+      resolve8();
     });
   });
 };
 var hasFlag = (argv, flags) => {
   return argv.some((argument) => flags.includes(argument));
 };
-var topLevelCommands = /* @__PURE__ */ new Set(["auth", "org", "profile", "exercise", "feedback", "figure", "sheet", "job"]);
+var topLevelCommands = /* @__PURE__ */ new Set([
+  "auth",
+  "org",
+  "profile",
+  "exercise",
+  "quality-issue",
+  "feedback",
+  "figure",
+  "sheet",
+  "job"
+]);
 var hasTopLevelCommand = (argv) => {
   return argv.some((argument) => topLevelCommands.has(argument));
 };
@@ -14417,7 +15647,17 @@ var resolveCommandName = (argv) => {
     if (!topLevelCommands.has(argument)) {
       continue;
     }
-    const subcommand = argv.slice(index + 1).find((candidate) => candidate.length > 0 && !candidate.startsWith("-") && !candidate.startsWith("http"));
+    const commandArguments = argv.slice(index + 1);
+    const subcommandIndex = commandArguments.findIndex(
+      (candidate) => candidate.length > 0 && !candidate.startsWith("-") && !candidate.startsWith("http")
+    );
+    const subcommand = commandArguments[subcommandIndex];
+    if (argument === "sheet" && subcommand === "bulk-update") {
+      const nestedSubcommand = commandArguments.slice(subcommandIndex + 1).find((candidate) => candidate.length > 0 && !candidate.startsWith("-"));
+      if (nestedSubcommand === "verify") {
+        return "sheet bulk-update verify";
+      }
+    }
     return subcommand ? `${argument} ${subcommand}` : argument;
   }
   if (hasFlag(argv, ["--version", "-v"])) {
@@ -14431,7 +15671,7 @@ var runCli = async ({
   configPath,
   env = process.env,
   nowImpl = Date.now,
-  sleepImpl = (milliseconds) => new Promise((resolve7) => setTimeout(resolve7, milliseconds)),
+  sleepImpl = (milliseconds) => new Promise((resolve8) => setTimeout(resolve8, milliseconds)),
   stdin = process.stdin,
   stdout = process.stdout,
   stderr = process.stderr
@@ -14446,6 +15686,7 @@ var runCli = async ({
     cwd,
     configPath,
     env,
+    helpWidth: getHelpWidth(stdout),
     now: nowImpl,
     output,
     sleep: sleepImpl,