@mytegroupinc/myte-core 0.0.21 → 0.0.23

package/README.md

@@ -19,6 +19,8 @@ This package exists so the public wrapper can stay small and versioned cleanly.
 ## Behavior Summary
 
 - Snapshot-style commands such as `bootstrap`, `sync-qaqc`, `feedback-sync`, and `suggestions sync` write local `MyteCommandCenter` data.
-- `feedback status|edit|assign|archive` writes reviewable local YAML artifacts, while `feedback validate|apply` sends those artifacts to the backend so business rules stay server-side.
+- `feedback status|edit|assign|archive` writes reviewable local YAML artifacts; `feedback submit|revise|reviews|review` routes them through the backend owner-review membrane.
+- `feedback move|undo|prd-versions|prd-diff|history` calls the project-key Feedback API while leaving lifecycle rules and permissions server-side.
+- `feedback validate|apply` remains available for validation and owner-direct apply paths; live authorization, stale checks, and history stay server-side.
 - `query --with-diff` requires project repos to be configured for diff collection and fails fast when no matching local project repo can be resolved.
 - Public package documentation is intentionally minimal. Internal rollout and design notes are not part of the npm package contract.

package/cli.js

@@ -22,6 +22,7 @@ const {
 } = require("./lib/ai-gateway");
 
 const DEFAULT_API_BASE = "https://api.myte.dev";
+const DEFAULT_DIFF_LIMIT_CHARS = 500_000;
 const REMOVED_COMMAND_MESSAGES = {
   ask: "The `ask` alias has been removed. Use `myte query \"...\"`.",
   chat: "The `chat` command has been removed. Use repeated `myte query` calls instead.",
@@ -143,6 +144,14 @@ function parseArgs(argv) {
         "status",
         "source",
         "feedback-id",
+        "request-id",
+        "event-id",
+        "version-id",
+        "compare-to",
+        "action",
+        "decision",
+        "to-state",
+        "from-state",
         "reason",
         "review-action",
         "idempotency-key",
@@ -151,6 +160,7 @@ function parseArgs(argv) {
         "due-date",
         "priority",
         "review-note",
+        "final-file",
         "tags",
         "tag",
         "mission-ids",
@@ -226,6 +236,14 @@ function printHelp() {
     "  myte feedback-sync [--status <value>] [--source <value>] [--with-prd-text|--no-with-prd-text] [--output-dir ./MyteCommandCenter] [--json]",
     "  myte feedback status --feedback-id <id> --status todo|in_progress|in_review|completed|deployed|rejected|archived --reason \"...\"",
     "  myte feedback edit --feedback-id <id> [--title \"...\"] [--feedback-text \"...\"] [--priority High] [--reason \"...\"]",
+    "  myte feedback submit --file ./MyteCommandCenter/reviews/feedback/<id>-edit.yml [--json]",
+    "  myte feedback revise --request-id <id> --file ./MyteCommandCenter/reviews/feedback/<id>-edit.yml [--json]",
+    "  myte feedback reviews [--status open|terminal|all] [--request-id <id>] [--json]",
+    "  myte feedback review --request-id <id> --action approve|reject|request_changes|cancel [--reason \"...\"] [--json]",
+    "  myte feedback move --feedback-id <id> --to-state in_progress --from-state todo --reason \"...\" [--json]",
+    "  myte feedback undo --feedback-id <id> --event-id <id> --reason \"...\" [--json]",
+    "  myte feedback prd-versions --feedback-id <id> [--json]",
+    "  myte feedback prd-diff --feedback-id <id> --version-id <id> [--compare-to <id>] [--json]",
     "  myte feedback validate --file ./MyteCommandCenter/reviews/feedback/<id>-status.yml [--json]",
     "  myte feedback apply --file ./MyteCommandCenter/reviews/feedback/<id>-status.yml [--json]",
     "  myte create-prd <file.md> [more.md ...] [--json] [--title \"...\"] [--description \"...\"]",
@@ -308,13 +326,17 @@ function printHelp() {
     "",
     "feedback review contract:",
     "  - Draft commands write review artifacts under MyteCommandCenter/reviews/feedback/*.yml for local IDE diff review",
-    "  - validate/apply send those artifacts to /api/project-assistant/feedback/<id>/refinement/*",
+    "  - submit/revise route artifacts through the owner-review membrane before live feedback mutation",
+    "  - reviews/review expose owner/delegate approval, rejection, request-changes, and cancel decisions",
+    "  - move/undo operate safe board states directly; governed states remain backend-authorized",
+    "  - prd-versions/prd-diff expose retained PRD versions and backend-generated text diffs",
+    "  - validate/apply send artifacts to /api/project-assistant/feedback/<id>/refinement/* for validation or owner-direct apply",
     "  - The backend owns authorization, stale snapshot checks, allowed field/transition rules, and history",
     "  - apply is idempotent and does not rewrite local feedback.yml; run feedback-sync after apply to refresh local state",
     "",
     "Options:",
     "  --with-diff           Include deterministic git diffs (project-scoped; fails fast if no project repos are configured or resolved)",
-    "  --diff-limit <chars>  Truncate diff context to N chars (default: 200000)",
+    "  --diff-limit <chars>  Truncate diff context to N chars (default: 500000)",
     "  --timeout-ms <ms>     Request timeout (default: 300000)",
     "  --base-url <url>      API base (default: https://api.myte.dev)",
     "  --payload-file <path> Raw OpenAI-style chat-completions payload for `myte ai`",
@@ -333,6 +355,13 @@ function printHelp() {
     "  --target-contact-id   Add one client contact ObjectId (repeatable)",
     "  --target-contact-ids  Comma-separated client contact ObjectIds",
     "  --feedback-id <id>    Feedback ObjectId for feedback review commands",
+    "  --request-id <id>     Feedback review request ObjectId for submit/revise/review flows",
+    "  --event-id <id>       Feedback board event ObjectId for undo",
+    "  --version-id <id>     Feedback PRD version ObjectId for prd-diff",
+    "  --compare-to <id>     Optional base PRD version ObjectId for prd-diff",
+    "  --action <value>      Feedback review action: approve, reject, request_changes, or cancel",
+    "  --to-state <value>    Target canonical feedback board state for feedback move",
+    "  --from-state <value>  Optional current-state guard for feedback move",
     "  --reason <text>       Human review reason included in feedback refinement artifacts",
     "  --status <value>      Mission status target, feedback-sync filter, or feedback review state depending on command",
     "  --source <value>      Feedback source filter for feedback-sync",
@@ -370,6 +399,10 @@ function printHelp() {
     "  myte update-client --subject \"Weekly client update\" --body-file ./updates/week-12.md",
     "  myte feedback-sync --json",
     "  myte feedback status --feedback-id 507f1f77bcf86cd799439011 --status in_review --reason \"Ready for owner review\"",
+    "  myte feedback submit --file ./MyteCommandCenter/reviews/feedback/507f1f77bcf86cd799439011-edit.yml --json",
+    "  myte feedback reviews --status open --json",
+    "  myte feedback review --request-id 507f1f77bcf86cd799439022 --action approve --reason \"Looks correct\" --json",
+    "  myte feedback move --feedback-id 507f1f77bcf86cd799439011 --to-state in_progress --reason \"Started\" --json",
     "  myte feedback validate --file ./MyteCommandCenter/reviews/feedback/507f1f77bcf86cd799439011-status.yml --json",
     "  myte feedback apply --file ./MyteCommandCenter/reviews/feedback/507f1f77bcf86cd799439011-status.yml --json",
     "  myte suggestions create --file ./suggestions/create.yml",
@@ -604,6 +637,8 @@ async function fetchJsonWithTimeout(fetchFn, url, options, timeoutMs) {
     } catch {
       const err = new Error(`Non-JSON response (${resp.status}): ${text.slice(0, 500)}`);
       err.status = resp.status;
+      const retryAfter = resp.headers?.get?.("retry-after");
+      if (retryAfter) err.retryAfter = retryAfter;
       throw err;
     }
     return { resp, body };
@@ -1708,6 +1743,208 @@ async function postFeedbackRefinement({ apiBase, key, timeoutMs, feedbackId, mod
   return body.data || {};
 }
 
+async function fetchFeedbackReviewRequests({ apiBase, key, timeoutMs, status, limit, offset }) {
+  const fetchFn = await getFetch();
+  const url = new URL(`${apiBase}/project-assistant/feedback-review-requests`);
+  if (status) url.searchParams.set("status", String(status));
+  if (limit !== undefined && limit !== null && String(limit).trim()) url.searchParams.set("limit", String(limit));
+  if (offset !== undefined && offset !== null && String(offset).trim()) url.searchParams.set("offset", String(offset));
+  const { resp, body } = await fetchJsonWithTimeout(
+    fetchFn,
+    url.toString(),
+    {
+      method: "GET",
+      headers: { Authorization: `Bearer ${key}` },
+    },
+    timeoutMs
+  );
+
+  if (!resp.ok || body.status !== "success") {
+    const msg = body?.message || `Feedback review requests failed (${resp.status})`;
+    const err = new Error(msg);
+    err.status = resp.status;
+    throw err;
+  }
+  return body.data || {};
+}
+
+async function fetchFeedbackReviewRequest({ apiBase, key, timeoutMs, requestId }) {
+  const fetchFn = await getFetch();
+  const url = `${apiBase}/project-assistant/feedback-review-requests/${encodeURIComponent(String(requestId || ""))}`;
+  const { resp, body } = await fetchJsonWithTimeout(
+    fetchFn,
+    url,
+    {
+      method: "GET",
+      headers: { Authorization: `Bearer ${key}` },
+    },
+    timeoutMs
+  );
+
+  if (!resp.ok || body.status !== "success") {
+    const msg = body?.message || `Feedback review request failed (${resp.status})`;
+    const err = new Error(msg);
+    err.status = resp.status;
+    throw err;
+  }
+  return body.data || {};
+}
+
+async function fetchFeedbackEvents({ apiBase, key, timeoutMs, feedbackId, limit }) {
+  const fetchFn = await getFetch();
+  const url = new URL(`${apiBase}/project-assistant/feedback/${encodeURIComponent(String(feedbackId || ""))}/events`);
+  if (limit !== undefined && limit !== null && String(limit).trim()) url.searchParams.set("limit", String(limit));
+  const { resp, body } = await fetchJsonWithTimeout(
+    fetchFn,
+    url.toString(),
+    {
+      method: "GET",
+      headers: { Authorization: `Bearer ${key}` },
+    },
+    timeoutMs
+  );
+
+  if (!resp.ok || body.status !== "success") {
+    const msg = body?.message || `Feedback events request failed (${resp.status})`;
+    const err = new Error(msg);
+    err.status = resp.status;
+    throw err;
+  }
+  return body.data || {};
+}
+
+async function postFeedbackReviewSubmission({ apiBase, key, timeoutMs, feedbackId, payload, idempotencyKey, clientSessionId }) {
+  const fetchFn = await getFetch();
+  const url = `${apiBase}/project-assistant/feedback/${encodeURIComponent(String(feedbackId || ""))}/refinement/requests`;
+  const { resp, body } = await fetchJsonWithTimeout(
+    fetchFn,
+    url,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${key}`,
+        "X-Idempotency-Key": String(idempotencyKey || "").trim(),
+        ...(String(clientSessionId || "").trim() ? { "X-Client-Session-Id": String(clientSessionId).trim() } : {}),
+      },
+      body: JSON.stringify(payload || {}),
+    },
+    timeoutMs
+  );
+
+  if (!resp.ok || body.status !== "success") {
+    const msg = body?.message || `Feedback review submission failed (${resp.status})`;
+    const err = new Error(msg);
+    err.status = resp.status;
+    err.data = body?.data;
+    throw err;
+  }
+  return body.data || {};
+}
+
+async function postFeedbackReviewRequestMutation({ apiBase, key, timeoutMs, requestId, endpointAction, payload, idempotencyKey, clientSessionId }) {
+  const fetchFn = await getFetch();
+  const url = `${apiBase}/project-assistant/feedback-review-requests/${encodeURIComponent(String(requestId || ""))}/${endpointAction}`;
+  const { resp, body } = await fetchJsonWithTimeout(
+    fetchFn,
+    url,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${key}`,
+        "X-Idempotency-Key": String(idempotencyKey || "").trim(),
+        ...(String(clientSessionId || "").trim() ? { "X-Client-Session-Id": String(clientSessionId).trim() } : {}),
+      },
+      body: JSON.stringify(payload || {}),
+    },
+    timeoutMs
+  );
+
+  if (!resp.ok || body.status !== "success") {
+    const msg = body?.message || `Feedback review ${endpointAction} failed (${resp.status})`;
+    const err = new Error(msg);
+    err.status = resp.status;
+    err.data = body?.data;
+    throw err;
+  }
+  return body.data || {};
+}
+
+async function postFeedbackBoardMutation({ apiBase, key, timeoutMs, feedbackId, endpoint, payload, idempotencyKey, clientSessionId }) {
+  const fetchFn = await getFetch();
+  const url = `${apiBase}/project-assistant/feedback/${encodeURIComponent(String(feedbackId || ""))}/${endpoint}`;
+  const { resp, body } = await fetchJsonWithTimeout(
+    fetchFn,
+    url,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${key}`,
+        "X-Idempotency-Key": String(idempotencyKey || "").trim(),
+        ...(String(clientSessionId || "").trim() ? { "X-Client-Session-Id": String(clientSessionId).trim() } : {}),
+      },
+      body: JSON.stringify(payload || {}),
+    },
+    timeoutMs
+  );
+
+  if (!resp.ok || body.status !== "success") {
+    const msg = body?.message || `Feedback board mutation failed (${resp.status})`;
+    const err = new Error(msg);
+    err.status = resp.status;
+    err.data = body?.data;
+    throw err;
+  }
+  return body.data || {};
+}
+
+async function fetchFeedbackPrdVersions({ apiBase, key, timeoutMs, feedbackId }) {
+  const fetchFn = await getFetch();
+  const url = `${apiBase}/project-assistant/feedback/${encodeURIComponent(String(feedbackId || ""))}/prd/versions`;
+  const { resp, body } = await fetchJsonWithTimeout(
+    fetchFn,
+    url,
+    {
+      method: "GET",
+      headers: { Authorization: `Bearer ${key}` },
+    },
+    timeoutMs
+  );
+
+  if (!resp.ok || body.status !== "success") {
+    const msg = body?.message || `Feedback PRD versions request failed (${resp.status})`;
+    const err = new Error(msg);
+    err.status = resp.status;
+    throw err;
+  }
+  return body.data || {};
+}
+
+async function fetchFeedbackPrdVersionDiff({ apiBase, key, timeoutMs, feedbackId, versionId, compareTo }) {
+  const fetchFn = await getFetch();
+  const url = new URL(`${apiBase}/project-assistant/feedback/${encodeURIComponent(String(feedbackId || ""))}/prd/versions/${encodeURIComponent(String(versionId || ""))}/diff`);
+  if (compareTo) url.searchParams.set("compare_to", String(compareTo));
+  const { resp, body } = await fetchJsonWithTimeout(
+    fetchFn,
+    url.toString(),
+    {
+      method: "GET",
+      headers: { Authorization: `Bearer ${key}` },
+    },
+    timeoutMs
+  );
+
+  if (!resp.ok || body.status !== "success") {
+    const msg = body?.message || `Feedback PRD version diff failed (${resp.status})`;
+    const err = new Error(msg);
+    err.status = resp.status;
+    throw err;
+  }
+  return body.data || {};
+}
+
 async function fetchSuggestionsSyncSnapshot({ apiBase, key, timeoutMs, actorScope = "" }) {
   const fetchFn = await getFetch();
   const url = new URL(`${apiBase}/project-assistant/suggestions`);
@@ -1881,6 +2118,10 @@ function resolveRetryAfterMs(err, fallbackMs = 5_000) {
   return fallbackMs;
 }
 
+function isTransientQueryStatusError(err) {
+  return [408, 429, 500, 502, 503, 504].includes(Number(err?.status));
+}
+
 async function createAssistantQueryJob({ apiBase, key, payload, timeoutMs, endpoint = "/project-assistant/query" }) {
   const fetchFn = await getFetch();
   const url = `${apiBase}${endpoint}`;
@@ -4261,7 +4502,7 @@ async function buildFeedbackDraftForCommand(args, subcommand) {
     const reviewNote = firstNonEmptyString(args["review-note"], args.reviewNote, args.review_note);
     if (reviewNote) changes.review_note = feedbackChange(null, reviewNote);
   } else {
-    console.error("Unknown feedback command. Use status, edit, assign, archive, get, history, validate, or apply.");
+    console.error("Unknown feedback draft command. Use status, edit, assign, archive, or refine.");
     process.exit(1);
   }
 
@@ -4375,57 +4616,537 @@ async function runFeedbackValidateOrApply(args, mode) {
   }
 }
 
-async function runFeedbackGetOrHistory(args, mode) {
+function resolveFeedbackRequestIdArg(args) {
+  return firstNonEmptyString(args["request-id"], args.requestId, args.request_id, args._?.[1]);
+}
+
+function resolveFeedbackEventIdArg(args) {
+  return firstNonEmptyString(args["event-id"], args.eventId, args.event_id, args._?.[1]);
+}
+
+function resolveFeedbackVersionIdArg(args) {
+  return firstNonEmptyString(args["version-id"], args.versionId, args.version_id, args._?.[1]);
+}
+
+function summarizeFeedbackReviewRequestPayload(data) {
+  const request = data?.request || data || {};
+  return {
+    request_id: request.request_id || request._id || null,
+    feedback_id: request.feedback_id || request.feedback?.feedback_id || null,
+    status: request.status || null,
+    title: request.title || request.feedback?.title || null,
+    can_review: request.can_review === true,
+    can_approve: request.can_approve === true,
+    is_terminal: request.is_terminal === true,
+    stale: request.stale === true,
+    conflicted: request.conflicted === true,
+    warnings: Array.isArray(request.warnings) ? request.warnings : [],
+  };
+}
+
+function printFeedbackReviewRequestSummary(data, args) {
+  const summary = summarizeFeedbackReviewRequestPayload(data);
+  if (args.json) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+  console.log(`Request: ${summary.request_id || "(unknown)"}`);
+  console.log(`Feedback: ${summary.feedback_id || "(unknown)"}`);
+  console.log(`Status: ${summary.status || "unknown"}`);
+  if (summary.title) console.log(`Title: ${summary.title}`);
+  console.log(`Can approve: ${summary.can_approve ? "yes" : "no"}`);
+  if (summary.stale || summary.conflicted) {
+    console.log(`Conflict: stale=${summary.stale ? "yes" : "no"}, conflicted=${summary.conflicted ? "yes" : "no"}`);
+  }
+}
+
+async function runFeedbackSubmit(args) {
   const key = getProjectApiKey();
   if (!key) {
     console.error("Missing MYTE_API_KEY (project key) in environment/.env");
     process.exit(1);
   }
-  const feedbackId = resolveFeedbackIdArg(args);
+  const { absPath, payload } = readFeedbackRefinementArtifact(args);
+  const feedbackId = firstNonEmptyString(args["feedback-id"], args.feedbackId, args.feedback_id, payload.feedback_id);
   if (!feedbackId) {
-    console.error("Missing --feedback-id.");
+    console.error("Feedback refinement artifact is missing feedback_id.");
     process.exit(1);
   }
   const timeoutMs = resolveTimeoutMs(args);
   const apiBase = resolveApiBase(args);
+  const clientSessionId = firstNonEmptyString(
+    args["client-session-id"],
+    args.clientSessionId,
+    args.client_session_id,
+    payload.client_session_id
+  );
+  const idempotencyKey = resolveProjectMutationIdempotencyKey({
+    args,
+    operation: `feedback_refinement_request_submit:${feedbackId}`,
+    payload,
+  });
 
   let data;
   try {
-    data = mode === "history"
-      ? await fetchFeedbackHistory({ apiBase, key, timeoutMs, feedbackId })
-      : await fetchFeedbackReview({ apiBase, key, timeoutMs, feedbackId });
+    data = await postFeedbackReviewSubmission({
+      apiBase,
+      key,
+      timeoutMs,
+      feedbackId,
+      payload,
+      idempotencyKey,
+      clientSessionId,
+    });
   } catch (err) {
-    console.error(`Feedback ${mode} failed:`, err?.message || err);
+    if (args.json) {
+      console.log(JSON.stringify({ ok: false, status: err?.status || null, message: err?.message || String(err), data: err?.data || null, artifact_path: absPath }, null, 2));
+    } else {
+      console.error("Feedback submit failed:", err?.message || err);
+      if (err?.data) console.error(JSON.stringify(err.data, null, 2));
+    }
     process.exit(1);
   }
 
+  const output = {
+    ok: true,
+    artifact_path: absPath,
+    feedback_id: data.feedback_id || feedbackId,
+    project_id: data.project_id || null,
+    pending_review_count: data.pending_review_count || null,
+    request: data.request || null,
+    permissions: data.permissions || null,
+  };
   if (args.json) {
-    console.log(JSON.stringify(data, null, 2));
-    return;
-  }
-  if (mode === "history") {
-    console.log(`Feedback: ${data.feedback_id || feedbackId}`);
-    console.log(`Events: ${data.count || 0}`);
-    for (const event of data.events || []) {
-      console.log(`- ${event.created_at || "unknown"} ${event.action || "refine"} ${event.history_id || ""}`);
-    }
+    console.log(JSON.stringify(output, null, 2));
     return;
   }
-  const feedback = data.feedback || {};
-  console.log(`Feedback: ${feedback.feedback_id || feedbackId}`);
-  console.log(`Title: ${feedback.title || "(untitled)"}`);
-  console.log(`Status: ${feedback.feedback_state || feedback.status || "unknown"} (${feedback.status || "legacy unknown"})`);
-  console.log(`Priority: ${feedback.priority || "n/a"}`);
-  console.log(`Snapshot: ${feedback.snapshot_hash || "n/a"}`);
+  console.log(`Feedback: ${output.feedback_id}`);
+  console.log(`Review request: ${output.request?.request_id || output.request?._id || "(unknown)"}`);
+  console.log(`Status: ${output.request?.status || "pending_review"}`);
+  console.log("Live feedback was not mutated. Owner/delegate approval is required.");
 }
 
-async function runFeedback(args) {
-  const subcommand = firstNonEmptyString(args._?.[0]) || "help";
-  if (subcommand === "help") {
-    printHelp();
-    return;
+async function runFeedbackRevise(args) {
+  const key = getProjectApiKey();
+  if (!key) {
+    console.error("Missing MYTE_API_KEY (project key) in environment/.env");
+    process.exit(1);
   }
-  if (["status", "edit", "assign", "archive", "refine"].includes(subcommand)) {
+  const requestId = resolveFeedbackRequestIdArg(args);
+  if (!requestId) {
+    console.error("Missing --request-id.");
+    process.exit(1);
+  }
+  const { absPath, payload } = readFeedbackRefinementArtifact(args);
+  const timeoutMs = resolveTimeoutMs(args);
+  const apiBase = resolveApiBase(args);
+  const clientSessionId = firstNonEmptyString(
+    args["client-session-id"],
+    args.clientSessionId,
+    args.client_session_id,
+    payload.client_session_id
+  );
+  const idempotencyKey = resolveProjectMutationIdempotencyKey({
+    args,
+    operation: `feedback_refinement_request_revise:${requestId}`,
+    payload,
+  });
+
+  let data;
+  try {
+    data = await postFeedbackReviewRequestMutation({
+      apiBase,
+      key,
+      timeoutMs,
+      requestId,
+      endpointAction: "revise",
+      payload,
+      idempotencyKey,
+      clientSessionId,
+    });
+  } catch (err) {
+    if (args.json) {
+      console.log(JSON.stringify({ ok: false, status: err?.status || null, message: err?.message || String(err), data: err?.data || null, artifact_path: absPath }, null, 2));
+    } else {
+      console.error("Feedback revise failed:", err?.message || err);
+      if (err?.data) console.error(JSON.stringify(err.data, null, 2));
+    }
+    process.exit(1);
+  }
+
+  const output = { ok: true, artifact_path: absPath, ...data };
+  if (args.json) {
+    console.log(JSON.stringify(output, null, 2));
+    return;
+  }
+  printFeedbackReviewRequestSummary(data, args);
+}
+
+async function runFeedbackReviews(args) {
+  const key = getProjectApiKey();
+  if (!key) {
+    console.error("Missing MYTE_API_KEY (project key) in environment/.env");
+    process.exit(1);
+  }
+  const timeoutMs = resolveTimeoutMs(args);
+  const apiBase = resolveApiBase(args);
+  const requestId = firstNonEmptyString(args["request-id"], args.requestId, args.request_id);
+
+  let data;
+  try {
+    data = requestId
+      ? await fetchFeedbackReviewRequest({ apiBase, key, timeoutMs, requestId })
+      : await fetchFeedbackReviewRequests({
+          apiBase,
+          key,
+          timeoutMs,
+          status: firstNonEmptyString(args.status) || "open",
+          limit: firstNonEmptyString(args.limit) || undefined,
+          offset: firstNonEmptyString(args.offset) || undefined,
+        });
+  } catch (err) {
+    console.error("Feedback reviews failed:", err?.message || err);
+    process.exit(1);
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+  if (requestId) {
+    printFeedbackReviewRequestSummary(data, args);
+    return;
+  }
+  const requests = Array.isArray(data.requests) ? data.requests : [];
+  console.log(`Review requests: ${requests.length}/${data.total ?? requests.length}`);
+  for (const requestItem of requests) {
+    const summary = summarizeFeedbackReviewRequestPayload(requestItem);
+    console.log(`- ${summary.request_id || "(unknown)"} ${summary.status || "unknown"} feedback=${summary.feedback_id || "(unknown)"} title=${summary.title || "(untitled)"}`);
+  }
+}
+
+function buildFeedbackReviewDecisionPayload(args, action) {
+  const filePath = firstNonEmptyString(args.file);
+  let payload = {};
+  if (filePath) {
+    const fromFile = readStructuredPayloadFile(filePath, "Feedback review");
+    payload = Array.isArray(fromFile?.items) ? fromFile.items[0] || {} : fromFile;
+  }
+  if (!isPlainObject(payload)) {
+    throw new Error("Feedback review payload must be an object.");
+  }
+  const nextPayload = { ...payload };
+  const reason = firstNonEmptyString(args.reason, args["review-note"], args.reviewNote, args.review_note);
+  if (reason && !nextPayload.reason && !nextPayload.review_reason) {
+    nextPayload.reason = reason;
+  }
+  const finalFile = firstNonEmptyString(args["final-file"], args.finalFile, args.final_file);
+  if (finalFile) {
+    nextPayload.final_change_set = readStructuredPayloadFile(finalFile, "Feedback final change set");
+  }
+  if (action === "approve" || action === "reject") {
+    nextPayload.decision = action;
+  }
+  return nextPayload;
+}
+
+async function runFeedbackReviewDecision(args) {
+  const key = getProjectApiKey();
+  if (!key) {
+    console.error("Missing MYTE_API_KEY (project key) in environment/.env");
+    process.exit(1);
+  }
+  const requestId = resolveFeedbackRequestIdArg(args);
+  if (!requestId) {
+    console.error("Missing --request-id.");
+    process.exit(1);
+  }
+  const action = String(firstNonEmptyString(args.action, args.decision, args["review-action"], args.reviewAction, args.review_action, args._?.[1]) || "").trim().toLowerCase().replace(/-/g, "_");
+  if (!["approve", "reject", "request_changes", "cancel"].includes(action)) {
+    console.error("Missing or invalid review action. Use approve, reject, request_changes, or cancel.");
+    process.exit(1);
+  }
+
+  let payload;
+  try {
+    payload = buildFeedbackReviewDecisionPayload(args, action);
+  } catch (err) {
+    console.error(err?.message || err);
+    process.exit(1);
+  }
+  const endpointAction = action === "request_changes" ? "request-changes" : action === "cancel" ? "cancel" : "review";
+  const timeoutMs = resolveTimeoutMs(args);
+  const apiBase = resolveApiBase(args);
+  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id, payload.client_session_id);
+  const operationAction = action === "request_changes" ? "request_changes" : action;
+  const idempotencyKey = resolveProjectMutationIdempotencyKey({
+    args,
+    operation: `feedback_review_request_${operationAction}:${requestId}`,
+    payload,
+  });
+
+  let data;
+  try {
+    data = await postFeedbackReviewRequestMutation({
+      apiBase,
+      key,
+      timeoutMs,
+      requestId,
+      endpointAction,
+      payload,
+      idempotencyKey,
+      clientSessionId,
+    });
+  } catch (err) {
+    if (args.json) {
+      console.log(JSON.stringify({ ok: false, status: err?.status || null, message: err?.message || String(err), data: err?.data || null }, null, 2));
+    } else {
+      console.error(`Feedback review ${action} failed:`, err?.message || err);
+      if (err?.data) console.error(JSON.stringify(err.data, null, 2));
+    }
+    process.exit(1);
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify({ ok: true, action, ...data }, null, 2));
+    return;
+  }
+  printFeedbackReviewRequestSummary(data, args);
+}
+
+async function runFeedbackMove(args) {
+  const key = getProjectApiKey();
+  if (!key) {
+    console.error("Missing MYTE_API_KEY (project key) in environment/.env");
+    process.exit(1);
+  }
+  const feedbackId = resolveFeedbackIdArg(args);
+  if (!feedbackId) {
+    console.error("Missing --feedback-id.");
+    process.exit(1);
+  }
+  const toState = firstNonEmptyString(args["to-state"], args.toState, args.to_state, args.status, args._?.[1]);
+  if (!toState) {
+    console.error("Missing --to-state for feedback move.");
+    process.exit(1);
+  }
+  const payload = {
+    to_state: toState,
+    from_state: firstNonEmptyString(args["from-state"], args.fromState, args.from_state) || undefined,
+    reason: firstNonEmptyString(args.reason) || undefined,
+  };
+  const timeoutMs = resolveTimeoutMs(args);
+  const apiBase = resolveApiBase(args);
+  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
+  const idempotencyKey = resolveProjectMutationIdempotencyKey({
+    args,
+    operation: `feedback_board_move:${feedbackId}`,
+    payload,
+  });
+
+  let data;
+  try {
+    data = await postFeedbackBoardMutation({
+      apiBase,
+      key,
+      timeoutMs,
+      feedbackId,
+      endpoint: "board-move",
+      payload,
+      idempotencyKey,
+      clientSessionId,
+    });
+  } catch (err) {
+    if (args.json) {
+      console.log(JSON.stringify({ ok: false, status: err?.status || null, message: err?.message || String(err), data: err?.data || null }, null, 2));
+    } else {
+      console.error("Feedback move failed:", err?.message || err);
+      if (err?.data) console.error(JSON.stringify(err.data, null, 2));
+    }
+    process.exit(1);
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify({ ok: true, ...data }, null, 2));
+    return;
+  }
+  console.log(`Feedback: ${data.feedback_id || feedbackId}`);
+  console.log(`State: ${data.feedback_state || toState}`);
+  if (data.event?.event_id) console.log(`Event: ${data.event.event_id}`);
+}
+
+async function runFeedbackUndo(args) {
+  const key = getProjectApiKey();
+  if (!key) {
+    console.error("Missing MYTE_API_KEY (project key) in environment/.env");
+    process.exit(1);
+  }
+  const feedbackId = resolveFeedbackIdArg(args);
+  const eventId = resolveFeedbackEventIdArg(args);
+  if (!feedbackId) {
+    console.error("Missing --feedback-id.");
+    process.exit(1);
+  }
+  if (!eventId) {
+    console.error("Missing --event-id.");
+    process.exit(1);
+  }
+  const payload = { reason: firstNonEmptyString(args.reason) || undefined };
+  const timeoutMs = resolveTimeoutMs(args);
+  const apiBase = resolveApiBase(args);
+  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
+  const idempotencyKey = resolveProjectMutationIdempotencyKey({
+    args,
+    operation: `feedback_event_undo:${feedbackId}:${eventId}`,
+    payload,
+  });
+
+  let data;
+  try {
+    data = await postFeedbackBoardMutation({
+      apiBase,
+      key,
+      timeoutMs,
+      feedbackId,
+      endpoint: `events/${encodeURIComponent(String(eventId))}/undo`,
+      payload,
+      idempotencyKey,
+      clientSessionId,
+    });
+  } catch (err) {
+    if (args.json) {
+      console.log(JSON.stringify({ ok: false, status: err?.status || null, message: err?.message || String(err), data: err?.data || null }, null, 2));
+    } else {
+      console.error("Feedback undo failed:", err?.message || err);
+      if (err?.data) console.error(JSON.stringify(err.data, null, 2));
+    }
+    process.exit(1);
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify({ ok: true, ...data }, null, 2));
+    return;
+  }
+  console.log(`Feedback: ${data.feedback_id || feedbackId}`);
+  console.log(`State: ${data.feedback_state || "unknown"}`);
+  if (data.reverted_event_id) console.log(`Reverted: ${data.reverted_event_id}`);
+}
+
+async function runFeedbackPrdVersions(args) {
+  const key = getProjectApiKey();
+  if (!key) {
+    console.error("Missing MYTE_API_KEY (project key) in environment/.env");
+    process.exit(1);
+  }
+  const feedbackId = resolveFeedbackIdArg(args);
+  if (!feedbackId) {
+    console.error("Missing --feedback-id.");
+    process.exit(1);
+  }
+  const timeoutMs = resolveTimeoutMs(args);
+  const apiBase = resolveApiBase(args);
+  let data;
+  try {
+    data = await fetchFeedbackPrdVersions({ apiBase, key, timeoutMs, feedbackId });
+  } catch (err) {
+    console.error("Feedback PRD versions failed:", err?.message || err);
+    process.exit(1);
+  }
+  if (args.json) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+  const versions = Array.isArray(data.versions) ? data.versions : [];
+  console.log(`PRD versions: ${versions.length}`);
+  for (const version of versions) {
+    console.log(`- ${version.version_id || version._id || "(unknown)"} v${version.version_number || "?"} active=${String(version._id || version.version_id) === String(data.active_prd_version_id) ? "yes" : "no"}`);
+  }
+}
+
+async function runFeedbackPrdDiff(args) {
+  const key = getProjectApiKey();
+  if (!key) {
+    console.error("Missing MYTE_API_KEY (project key) in environment/.env");
+    process.exit(1);
+  }
+  const feedbackId = resolveFeedbackIdArg(args);
+  const versionId = resolveFeedbackVersionIdArg(args);
+  if (!feedbackId) {
+    console.error("Missing --feedback-id.");
+    process.exit(1);
+  }
+  if (!versionId) {
+    console.error("Missing --version-id.");
+    process.exit(1);
+  }
+  const timeoutMs = resolveTimeoutMs(args);
+  const apiBase = resolveApiBase(args);
+  const compareTo = firstNonEmptyString(args["compare-to"], args.compareTo, args.compare_to);
+  let data;
+  try {
+    data = await fetchFeedbackPrdVersionDiff({ apiBase, key, timeoutMs, feedbackId, versionId, compareTo });
+  } catch (err) {
+    console.error("Feedback PRD diff failed:", err?.message || err);
+    process.exit(1);
+  }
+  if (args.json) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+  console.log(data.diff || "");
+}
+
+async function runFeedbackGetOrHistory(args, mode) {
+  const key = getProjectApiKey();
+  if (!key) {
+    console.error("Missing MYTE_API_KEY (project key) in environment/.env");
+    process.exit(1);
+  }
+  const feedbackId = resolveFeedbackIdArg(args);
+  if (!feedbackId) {
+    console.error("Missing --feedback-id.");
+    process.exit(1);
+  }
+  const timeoutMs = resolveTimeoutMs(args);
+  const apiBase = resolveApiBase(args);
+
+  let data;
+  try {
+    data = mode === "history"
+      ? await fetchFeedbackEvents({ apiBase, key, timeoutMs, feedbackId, limit: firstNonEmptyString(args.limit) || undefined })
+      : await fetchFeedbackReview({ apiBase, key, timeoutMs, feedbackId });
+  } catch (err) {
+    console.error(`Feedback ${mode} failed:`, err?.message || err);
+    process.exit(1);
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+  if (mode === "history") {
+    console.log(`Feedback: ${data.feedback_id || feedbackId}`);
+    console.log(`Events: ${data.count || 0}`);
+    for (const event of data.events || []) {
+      console.log(`- ${event.created_at || "unknown"} ${event.action || "refine"} ${event.history_id || ""}`);
+    }
+    return;
+  }
+  const feedback = data.feedback || {};
+  console.log(`Feedback: ${feedback.feedback_id || feedbackId}`);
+  console.log(`Title: ${feedback.title || "(untitled)"}`);
+  console.log(`Status: ${feedback.feedback_state || feedback.status || "unknown"} (${feedback.status || "legacy unknown"})`);
+  console.log(`Priority: ${feedback.priority || "n/a"}`);
+  console.log(`Snapshot: ${feedback.snapshot_hash || "n/a"}`);
+}
+
+async function runFeedback(args) {
+  const subcommand = firstNonEmptyString(args._?.[0]) || "help";
+  if (subcommand === "help") {
+    printHelp();
+    return;
+  }
+  if (["status", "edit", "assign", "archive", "refine"].includes(subcommand)) {
     await buildFeedbackDraftForCommand(args, subcommand);
     return;
   }
@@ -4433,11 +5154,43 @@ async function runFeedback(args) {
     await runFeedbackValidateOrApply(args, subcommand);
     return;
   }
+  if (subcommand === "submit") {
+    await runFeedbackSubmit(args);
+    return;
+  }
+  if (subcommand === "revise") {
+    await runFeedbackRevise(args);
+    return;
+  }
+  if (subcommand === "reviews" || subcommand === "requests") {
+    await runFeedbackReviews(args);
+    return;
+  }
+  if (subcommand === "review") {
+    await runFeedbackReviewDecision(args);
+    return;
+  }
+  if (subcommand === "move") {
+    await runFeedbackMove(args);
+    return;
+  }
+  if (subcommand === "undo") {
+    await runFeedbackUndo(args);
+    return;
+  }
+  if (subcommand === "prd-versions") {
+    await runFeedbackPrdVersions(args);
+    return;
+  }
+  if (subcommand === "prd-diff") {
+    await runFeedbackPrdDiff(args);
+    return;
+  }
   if (subcommand === "get" || subcommand === "history") {
     await runFeedbackGetOrHistory(args, subcommand);
     return;
   }
-  console.error("Unknown feedback command. Use status, edit, assign, archive, get, history, validate, or apply.");
+  console.error("Unknown feedback command. Use status, edit, assign, archive, submit, revise, reviews, review, move, undo, prd-versions, prd-diff, get, history, validate, or apply.");
   process.exit(1);
 }
 
@@ -5002,8 +5755,9 @@ async function runQuery(args) {
   const timeoutMs = Number.isFinite(timeoutParsed) ? timeoutParsed : 300_000;
 
   const charLimitRaw = args["diff-limit"] || args.diffLimit || args.diff_limit;
-  const charLimitParsed = charLimitRaw !== undefined && charLimitRaw !== null ? Number(charLimitRaw) : 200_000;
-  const diffLimit = Number.isFinite(charLimitParsed) ? charLimitParsed : 200_000;
+  const charLimitParsed =
+    charLimitRaw !== undefined && charLimitRaw !== null ? Number(charLimitRaw) : DEFAULT_DIFF_LIMIT_CHARS;
+  const diffLimit = Number.isFinite(charLimitParsed) ? charLimitParsed : DEFAULT_DIFF_LIMIT_CHARS;
 
   const baseRaw = args["base-url"] || args.baseUrl || args.base_url || process.env.MYTE_API_BASE || DEFAULT_API_BASE;
   const apiBase = normalizeApiBase(baseRaw);
@@ -5077,13 +5831,19 @@ async function runQuery(args) {
       const pollTimeoutMs = Math.max(timeoutMs, 900_000);
       const startedAt = Date.now();
       let finalStatus = null;
+      let pollDelayMs = 2_000;
       do {
-        await sleep(2_000);
+        await sleep(pollDelayMs);
         try {
           finalStatus = await fetchAssistantQueryJobStatus({ apiBase, key, timeoutMs, jobId });
+          pollDelayMs = Math.min(10_000, Math.ceil(pollDelayMs * 1.25));
         } catch (err) {
-          if (Number(err?.status) === 429) {
-            await sleep(resolveRetryAfterMs(err));
+          if (isTransientQueryStatusError(err)) {
+            const fallbackMs =
+              Number(err?.status) === 429 ? 5_000 : Math.min(30_000, Math.max(5_000, pollDelayMs * 2));
+            const waitMs = resolveRetryAfterMs(err, fallbackMs);
+            await sleep(waitMs);
+            pollDelayMs = Math.min(30_000, Math.max(pollDelayMs, waitMs));
             continue;
           }
           throw err;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mytegroupinc/myte-core",
-  "version": "0.0.21",
+  "version": "0.0.23",
   "description": "Myte CLI core implementation.",
   "type": "commonjs",
   "main": "cli.js",