@mytegroupinc/myte-core 0.0.22 → 0.0.24

package/README.md

@@ -19,6 +19,73 @@ 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.
+
+## Feedback Action Map
+
+| Command | What It Does | Governance |
+| --- | --- | --- |
+| `feedback-sync` | Pulls feedback metadata, comments, and PRD context into `MyteCommandCenter`. | Read-only project-key API call. |
+| `feedback get` | Reads one feedback item's current server snapshot and `snapshot_hash`. | Read-only; backend checks project access. |
+| `feedback status` | Creates a local YAML proposal to change canonical lifecycle state. | No live mutation until `submit` and owner/delegate review, except owner-direct `apply`. |
+| `feedback edit` / `feedback refine` | Creates a local YAML proposal for title, description/body, priority, due date, tags, or notes. | Content changes go through owner-review membrane. |
+| `feedback assign` | Creates a local YAML proposal to change assignee. | Goes through review unless applied through owner-direct path. |
+| `feedback archive` | Creates a local YAML proposal to archive. | Archive is governed by backend owner/delegate capability. |
+| `feedback submit` | Sends a local proposal artifact to the backend as a review request. | Does not mutate live feedback before approval. |
+| `feedback revise` | Resubmits the original submitter's request after `request_changes`. | Only valid for the original submitter and `needs_changes` requests. |
+| `feedback reviews` | Lists review requests or fetches one request by `--request-id`. | Read-only; response includes backend permissions. |
+| `feedback review` | Approves, rejects, requests changes, or cancels a review request. | Backend restricts approval/review decisions to Project Owner or elevated delegate for Feedback scope. |
+| `feedback move` | Moves a card across allowed board states directly with an audit event. | Safe states are direct; governed states such as archive/reject/deploy remain backend-authorized. |
+| `feedback undo` | Reverses an audited board event when there is no conflict. | Backend validates event ownership/project scope and conflict state. |
+| `feedback prd-versions` | Lists retained PRD baselines/revisions for a feedback item. | Read-only; old S3 objects are retained by reference. |
+| `feedback prd-diff` | Fetches backend-generated text diff for PRD versions. | Read-only; backend controls version access. |
+| `feedback history` | Lists audited feedback board/refinement events. | Read-only; backend checks project access. |
+| `feedback validate` | Sends an artifact to backend validation without mutation. | Useful before submit or owner-direct apply. |
+| `feedback apply` | Applies an artifact through the owner-direct/emergency path. | Not the normal collaborator flow; normal flow is `submit` -> `review`. |
+
+## Direct Project API Surface
+
+All routes use `Authorization: Bearer <MYTE_API_KEY>`. The CLI adds idempotency and client-session headers on mutation routes.
+
+Read/sync routes:
+
+- `GET /api/project-assistant/config`
+- `GET /api/project-assistant/bootstrap`
+- `GET /api/project-assistant/qaqc-sync`
+- `GET /api/project-assistant/feedback-sync`
+- `GET /api/project-assistant/feedback/<feedback_id>`
+- `GET /api/project-assistant/feedback/<feedback_id>/refinement/history`
+- `GET /api/project-assistant/feedback-review-requests`
+- `GET /api/project-assistant/feedback-review-requests/<request_id>`
+- `GET /api/project-assistant/feedback/<feedback_id>/events`
+- `GET /api/project-assistant/feedback/<feedback_id>/prd/versions`
+- `GET /api/project-assistant/feedback/<feedback_id>/prd/versions/<version_id>/diff`
+- `GET /api/project-assistant/suggestions`
+- `GET /api/project-assistant/run-qaqc/<batch_id>`
+
+Mutation routes:
+
+- `POST /api/project-assistant/query`
+- `POST /api/project-assistant/run-qaqc`
+- `POST /api/project-assistant/mission-status-update`
+- `POST /api/project-assistant/project-comment`
+- `POST /api/project-assistant/update-owner`
+- `POST /api/project-assistant/client-update-drafts`
+- `POST /api/project-assistant/create-prd`
+- `POST /api/project-assistant/create-prds`
+- `POST /api/project-assistant/feedback/<feedback_id>/refinement/validate`
+- `POST /api/project-assistant/feedback/<feedback_id>/refinement/requests`
+- `POST /api/project-assistant/feedback-review-requests/<request_id>/revise`
+- `POST /api/project-assistant/feedback/<feedback_id>/refinement/apply`
+- `POST /api/project-assistant/feedback-review-requests/<request_id>/review`
+- `POST /api/project-assistant/feedback-review-requests/<request_id>/request-changes`
+- `POST /api/project-assistant/feedback-review-requests/<request_id>/cancel`
+- `POST /api/project-assistant/feedback/<feedback_id>/board-move`
+- `POST /api/project-assistant/feedback/<feedback_id>/events/<event_id>/undo`
+- `POST /api/project-assistant/suggestions`
+- `POST /api/project-assistant/suggestions/revise`
+- `POST /api/project-assistant/suggestions/review`

package/cli.js

@@ -144,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",
@@ -152,6 +160,7 @@ function parseArgs(argv) {
         "due-date",
         "priority",
         "review-note",
+        "final-file",
         "tags",
         "tag",
         "mission-ids",
@@ -225,8 +234,20 @@ function printHelp() {
     "  myte update-owner --subject \"<text>\" [--body-markdown \"...\"] [--body-file ./update.md] [--json]",
     "  myte update-client --subject \"<text>\" [--body-markdown \"...\"] [--body-file ./update.md] [--target-contact-ids <id1,id2>] [--json]",
     "  myte feedback-sync [--status <value>] [--source <value>] [--with-prd-text|--no-with-prd-text] [--output-dir ./MyteCommandCenter] [--json]",
+    "  myte feedback get --feedback-id <id> [--json]",
+    "  myte feedback history --feedback-id <id> [--limit 50] [--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 assign --feedback-id <id> --user-id <id> [--reason \"...\"]",
+    "  myte feedback archive --feedback-id <id> --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 \"...\"]",
@@ -309,10 +330,32 @@ 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/*",
+    "  - status/edit/assign/archive/refine create local proposals only; they do not mutate live feedback by themselves",
+    "  - 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",
+    "  - get/history read current feedback snapshots and audited event history through the project-key API",
+    "  - 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",
     "",
+    "feedback action map:",
+    "  - feedback-sync: pull board/PRD context into MyteCommandCenter for IDE work",
+    "  - get: read one feedback item's current server snapshot and snapshot_hash",
+    "  - status/edit/assign/archive/refine: create reviewable local YAML artifacts; no live mutation",
+    "  - submit: submit a local artifact as a pending owner-review request",
+    "  - revise: resubmit the original submitter's request after request_changes",
+    "  - reviews: list open/terminal/all requests or inspect one request",
+    "  - review: approve, reject, request_changes, or cancel; backend restricts this to owner/delegate capability",
+    "  - move: direct audited board movement for allowed states; governed transitions remain backend-authorized",
+    "  - undo: reverse an audited board event when conflict checks allow it",
+    "  - prd-versions: list retained PRD baselines/revisions for a feedback item",
+    "  - prd-diff: fetch backend-generated text diff between PRD versions",
+    "  - history: list board/refinement events for audit review",
+    "  - validate: server-side validation of an artifact without mutation",
+    "  - apply: owner-direct/emergency apply path; normal collaborative flow is submit -> review",
+    "",
     "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: 500000)",
@@ -334,6 +377,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",
@@ -371,6 +421,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",
@@ -1711,6 +1765,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`);
@@ -4268,7 +4524,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);
   }
 
@@ -4382,69 +4638,581 @@ 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)) {
-    await buildFeedbackDraftForCommand(args, 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;
   }
   if (subcommand === "validate" || subcommand === "apply") {
     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);
 }
 

package/package.json

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