@mytegroupinc/myte-core 0.0.44 → 0.0.46

package/cli.js

@@ -208,10 +208,10 @@ function printHelp() {
     "  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 review --request-ids \"<id1,id2>\" --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 move --feedback-ids \"<id1,id2>\" --to-state in_progress --reason \"...\" [--json]",
-    "  myte feedback comment --feedback-id <id> --body \"...\" [--body-file ./comment.md] [--json]",
-    "  myte feedback undo --feedback-id <id> --event-id <id> --reason \"...\" [--json]",
+    "  myte feedback move --feedback-id <id> --to-state in_progress --from-state todo --reason \"...\" [--json]",
+    "  myte feedback move --feedback-ids \"<id1,id2>\" --to-state in_progress --reason \"...\" [--json]",
+    "  myte feedback comment --feedback-id <id> --body \"...\" [--body-file ./comment.md] [--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]",
@@ -231,16 +231,10 @@ function printHelp() {
     "  npx myte@latest query \"What changed in logging?\" --with-diff",
     "  npx myte@latest ai \"Return a JSON checklist\" --json-response",
     "",
-    "Auth:",
-    "  - Set MYTE_API_KEY in a workspace .env (or env var)",
-    "  - Set MYTEAI_API_KEY in a workspace .env (or env var) for `myte ai`",
-    "",
-    "Live write approval:",
-    "  - Live project-key mutations require --confirm-write --approval-artifact <path>",
-    "  - The artifact must be a local .md, .yml/.yaml, or .json file shown to and approved by the user before the command is rerun",
-    "  - Batch artifacts must enumerate every feedback id, mission id, suggestion id, request id, or PRD item",
-    "  - Read/sync/query/validate, --print-context, and --dry-run commands do not require write approval",
-    "",
+    "Auth:",
+    "  - Set MYTE_API_KEY in a workspace .env (or env var)",
+    "  - Set MYTEAI_API_KEY in a workspace .env (or env var) for `myte ai`",
+    "",
     "bootstrap contract:",
     "  - Run from any workspace where you want local MyteCommandCenter data written",
     "  - Writes MyteCommandCenter/data/project.yml plus phases, epics, stories, and missions locally",
@@ -319,7 +313,7 @@ function printHelp() {
     "  - Archived feedback is intentionally excluded from normal sync; returning it to active work is web UI only",
     "  - Writes project feedback metadata and conversation turns into MyteCommandCenter/data/feedback.yml",
     "  - Stores full PRD context in MyteCommandCenter/PRD/feedback-sync/*.md and points to those files from feedback.yml",
-    "  - Reads existing feedback comments and can create text-only feedback-specific comments through the project-key API",
+    "  - Reads existing feedback comments and can create text-only feedback-specific comments through the project-key API",
     "",
     "feedback review contract:",
     "  - Draft commands write review artifacts under MyteCommandCenter/reviews/feedback/*.yml for local IDE diff review",
@@ -328,9 +322,9 @@ function printHelp() {
     "  - reviews/review expose owner/delegate approval, rejection, request-changes, and cancel decisions",
     "  - review with --request-ids sends one batch review request; it does not loop single-review calls",
     "  - live lifecycle moves return pending_feedback_review while an active linked review request exists",
-    "  - move/undo operate safe board states directly; governed states remain backend-authorized",
-    "  - move with --feedback-ids sends one batch board move request; it supports active-state moves and authorized archive",
-    "  - comment creates text-only feedback-specific comments; attachments remain web UI only for this endpoint",
+    "  - move/undo operate safe board states directly; governed states remain backend-authorized",
+    "  - move with --feedback-ids sends one batch board move request; it supports active-state moves and authorized archive",
+    "  - comment creates text-only feedback-specific comments; attachments remain web UI only for this endpoint",
     "  - project-key API/CLI cannot unarchive archived Feedback; use the web archived Feedback view",
     "  - 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",
@@ -346,9 +340,9 @@ function printHelp() {
     "  - 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",
-    "  - comment: create a text-only comment on one Feedback item",
-    "  - undo: reverse an audited board event when conflict checks allow it",
+    "  - move: direct audited board movement for allowed states; governed transitions remain backend-authorized",
+    "  - comment: create a text-only comment on one Feedback item",
+    "  - 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",
@@ -369,11 +363,11 @@ function printHelp() {
     "  --stdin               Read supported command content from stdin instead of inline text or a file path",
     "  --title <text>        Override PRD title for raw markdown uploads",
     "  --description <text>  Set feedback description/card summary for raw markdown uploads",
-    "  --content <text>      Team update content for update-team",
-    "  --body <text>         Feedback comment body for feedback comment",
-    "  --subject <text>      Subject for update-owner or update-client",
+    "  --content <text>      Team update content for update-team",
+    "  --body <text>         Feedback comment body for feedback comment",
+    "  --subject <text>      Subject for update-owner or update-client",
     "  --body-markdown <md>  Markdown body for update-owner or update-client",
-    "  --body-file <path>    Read feedback comment, update-owner, or update-client markdown body from a file",
+    "  --body-file <path>    Read feedback comment, update-owner, or update-client markdown body from a file",
     "  --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",
@@ -401,10 +395,8 @@ function printHelp() {
     "  --actor-scope <id>    Actor workspace key inside mission-ops.yml (defaults to machine-cwd slug)",
     "  --wait                Poll batch status until terminal completion for run-qaqc",
     "  --sync                After run-qaqc completes, refresh local QAQC file",
-    "  --force               Allow run-qaqc to bypass stale-state protection when supported",
-    "  --confirm-write       Confirm the user explicitly approved a live Myte project-key mutation",
-    "  --approval-artifact   Local .md/.yml/.json approval artifact shown to and approved by the user",
-    "  --no-sync             Skip automatic post-mutation sync for suggestions, missions, and feedback mutations",
+    "  --force               Allow run-qaqc to bypass stale-state protection when supported",
+    "  --no-sync             Skip automatic post-mutation sync for suggestions, missions, and feedback mutations",
     "  --print-context       Print JSON payload and exit (no query call)",
     "  --no-fetch            Don't git fetch origin main/master before diff",
     "",
@@ -429,10 +421,10 @@ function printHelp() {
     "  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 comment --feedback-id 507f1f77bcf86cd799439011 --body \"Implementation notes are ready for review.\" --json",
-    "  myte feedback validate --file ./MyteCommandCenter/reviews/feedback/507f1f77bcf86cd799439011-status.yml --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 comment --feedback-id 507f1f77bcf86cd799439011 --body \"Implementation notes are ready for review.\" --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",
     "  myte suggestions revise",
@@ -678,10 +670,10 @@ function normalizeApiBase(baseRaw) {
   return base.endsWith("/api") ? base : `${base}/api`;
 }
 
-async function fetchJsonWithTimeout(fetchFn, url, options, timeoutMs) {
-  const controller = typeof AbortController !== "undefined" ? new AbortController() : undefined;
-  const timeoutId =
-    controller && timeoutMs > 0 ? setTimeout(() => controller.abort(), timeoutMs) : undefined;
+async function fetchJsonWithTimeout(fetchFn, url, options, timeoutMs) {
+  const controller = typeof AbortController !== "undefined" ? new AbortController() : undefined;
+  const timeoutId =
+    controller && timeoutMs > 0 ? setTimeout(() => controller.abort(), timeoutMs) : undefined;
   try {
     const resp = await fetchFn(url, { ...options, signal: controller?.signal });
     const text = await resp.text();
@@ -697,171 +689,13 @@ async function fetchJsonWithTimeout(fetchFn, url, options, timeoutMs) {
     }
     return { resp, body };
   } finally {
-    if (timeoutId) clearTimeout(timeoutId);
-  }
-}
-
-const WRITE_APPROVAL_TRANSPORT_KEYS = new Set(["write_approval", "client_session_id"]);
-
-function canonicalizeWritePayload(value) {
-  if (Array.isArray(value)) {
-    return value.map((item) => canonicalizeWritePayload(item));
-  }
-  if (value && typeof value === "object") {
-    return Object.fromEntries(
-      Object.keys(value)
-        .filter((key) => !WRITE_APPROVAL_TRANSPORT_KEYS.has(String(key)))
-        .sort()
-        .map((key) => [key, canonicalizeWritePayload(value[key])])
-    );
-  }
-  return value;
-}
-
-function projectApiWritePayloadHash(payload) {
-  return createHash("sha256")
-    .update(stableJsonStringify(canonicalizeWritePayload(payload || {})))
-    .digest("hex");
-}
-
-function isConfirmWrite(args) {
-  return Boolean(args["confirm-write"] || args.confirmWrite || args.confirm_write);
-}
-
-function resolveWriteApprovalArtifactPath(args) {
-  const explicit = firstNonEmptyString(args["approval-artifact"], args.approvalArtifact, args.approval_artifact);
-  if (!explicit) return "";
-  const resolved = path.resolve(process.cwd(), explicit);
-  if (!fs.existsSync(resolved) || !fs.statSync(resolved).isFile()) {
-    console.error(`Approval artifact not found: ${resolved}`);
-    process.exit(1);
-  }
-  return resolved;
-}
-
-function inferApprovalArtifactKind(filePath, fallbackKind) {
-  const ext = path.extname(String(filePath || "")).toLowerCase();
-  if (ext === ".md" || ext === ".markdown") return "markdown";
-  if (ext === ".yml" || ext === ".yaml") return "yaml";
-  if (ext === ".json") return "json";
-  return fallbackKind || "artifact";
-}
-
-function normalizeApprovalTargets(targets) {
-  return toStringArray(targets).map((item) => item.trim()).filter(Boolean);
-}
-
-function writePayloadItems(payload) {
-  if (Array.isArray(payload?.items)) return payload.items;
-  if (Array.isArray(payload)) return payload;
-  return payload && typeof payload === "object" ? [payload] : [];
-}
-
-function suggestionApprovalTargets(payload) {
-  return writePayloadItems(payload).map((item, index) => {
-    if (!item || typeof item !== "object") return `index:${index}`;
-    return firstNonEmptyString(
-      item.suggestion_id,
-      item.id,
-      item._id,
-      item.mission_id,
-      item.target_mission_id,
-      item.title ? `${item.change_type || "suggestion"}:${item.title}` : ""
-    ) || `index:${index}`;
-  });
-}
-
-function prdApprovalTargets(payload) {
-  return writePayloadItems(payload).map((item, index) => {
-    if (!item || typeof item !== "object") return `index:${index}`;
-    return firstNonEmptyString(item.client_ref, item.title) || `index:${index}`;
-  });
-}
-
-function requireWriteApproval(args, payload, { operation, artifactKind, targets = [], batchCount = null } = {}) {
-  const payloadSha256 = projectApiWritePayloadHash(payload || {});
-  const targetValues = normalizeApprovalTargets(targets);
-  const expectedBatchCount = batchCount !== null && batchCount !== undefined
-    ? Number(batchCount)
-    : targetValues.length > 1
-      ? targetValues.length
-      : null;
-
-  if (!isConfirmWrite(args)) {
-    console.error("Refusing live Myte write without explicit human approval.");
-    console.error(`Operation: ${operation || "unknown"}`);
-    console.error(`Payload SHA256: ${payloadSha256}`);
-    if (targetValues.length) console.error(`Targets: ${targetValues.join(", ")}`);
-    if (expectedBatchCount !== null) console.error(`Batch count: ${expectedBatchCount}`);
-    console.error("Create a local .md/.yml/.json approval artifact that lists the exact operation, payload summary, and every target.");
-    console.error("Show that artifact to the user and ask for explicit approval.");
-    console.error("Then rerun with --confirm-write --approval-artifact <path>.");
-    process.exit(1);
-  }
-
-  const artifactPath = resolveWriteApprovalArtifactPath(args);
-  if (!artifactPath) {
-    console.error("Missing --approval-artifact <path> for approved Myte write.");
-    console.error(`Payload SHA256: ${payloadSha256}`);
-    console.error("The artifact must be a local .md/.yml/.json file shown to and explicitly approved by the user.");
-    process.exit(1);
-  }
-
-  return {
-    approved: true,
-    source: "explicit_user_approval",
-    artifact_path: artifactPath,
-    artifact_kind: inferApprovalArtifactKind(artifactPath, artifactKind),
-    payload_sha256: payloadSha256,
-    targets: targetValues,
-    batch_count: expectedBatchCount,
-  };
-}
-
-function writeApprovalHeaders(writeApproval) {
-  if (!writeApproval) return {};
-  const headers = {
-    "X-Myte-Write-Approval": "explicit_user_approval",
-    "X-Myte-Approval-Artifact": String(writeApproval.artifact_path || ""),
-    "X-Myte-Approval-Artifact-Kind": String(writeApproval.artifact_kind || ""),
-    "X-Myte-Approval-Payload-SHA256": String(writeApproval.payload_sha256 || ""),
-  };
-  if (writeApproval.batch_count !== null && writeApproval.batch_count !== undefined) {
-    headers["X-Myte-Approval-Batch-Count"] = String(writeApproval.batch_count);
-  }
-  if (Array.isArray(writeApproval.targets) && writeApproval.targets.length) {
-    headers["X-Myte-Approval-Targets"] = writeApproval.targets.join(",");
-  }
-  return headers;
-}
-
-function formatProjectApiErrorMessage(body, fallback) {
-  const message = body?.message || fallback;
-  const data = body?.data || {};
-  const code = String(data?.code || "");
-  if (!code.startsWith("myte_write_approval")) {
-    return message;
-  }
-  const lines = [
-    message,
-    `Approval error: ${code}`,
-  ];
-  if (data.operation) lines.push(`Operation: ${data.operation}`);
-  if (data.payload_sha256) lines.push(`Payload SHA256: ${data.payload_sha256}`);
-  if (Array.isArray(data.targets) && data.targets.length) lines.push(`Targets: ${data.targets.join(", ")}`);
-  if (data.batch_count !== undefined && data.batch_count !== null) lines.push(`Batch count: ${data.batch_count}`);
-  if (Array.isArray(data.required_agent_steps) && data.required_agent_steps.length) {
-    lines.push("Required agent steps:");
-    for (const step of data.required_agent_steps) {
-      lines.push(`- ${step}`);
-    }
-  }
-  return lines.join("\n");
-}
-
-function summarizeDiffDiagnosticsForContext(diagnostics) {
-  if (!diagnostics) return null;
-  const repos = Array.isArray(diagnostics.repo_summaries)
+    if (timeoutId) clearTimeout(timeoutId);
+  }
+}
+
+function summarizeDiffDiagnosticsForContext(diagnostics) {
+  if (!diagnostics) return null;
+  const repos = Array.isArray(diagnostics.repo_summaries)
     ? diagnostics.repo_summaries
     : [];
   return {
@@ -1922,16 +1756,15 @@ async function fetchFeedbackHistory({ apiBase, key, timeoutMs, feedbackId }) {
   return body.data || {};
 }
 
-async function postFeedbackRefinement({ apiBase, key, timeoutMs, feedbackId, mode, payload, idempotencyKey, clientSessionId, writeApproval }) {
+async function postFeedbackRefinement({ apiBase, key, timeoutMs, feedbackId, mode, payload, idempotencyKey, clientSessionId }) {
   const fetchFn = await getFetch();
   const action = String(mode || "").trim();
   const url = `${apiBase}/project-assistant/feedback/${encodeURIComponent(String(feedbackId || ""))}/refinement/${action}`;
-  const headers = {
-    "Content-Type": "application/json",
-    Authorization: `Bearer ${key}`,
-    ...(String(clientSessionId || "").trim() ? { "X-Client-Session-Id": String(clientSessionId).trim() } : {}),
-    ...writeApprovalHeaders(writeApproval),
-  };
+  const headers = {
+    "Content-Type": "application/json",
+    Authorization: `Bearer ${key}`,
+    ...(String(clientSessionId || "").trim() ? { "X-Client-Session-Id": String(clientSessionId).trim() } : {}),
+  };
   if (idempotencyKey) {
     headers["X-Idempotency-Key"] = String(idempotencyKey).trim();
   }
@@ -1947,7 +1780,7 @@ async function postFeedbackRefinement({ apiBase, key, timeoutMs, feedbackId, mod
   );
 
   if (!resp.ok || body.status !== "success") {
-    const msg = formatProjectApiErrorMessage(body, `Feedback refinement ${action} failed (${resp.status})`);
+    const msg = body?.message || `Feedback refinement ${action} failed (${resp.status})`;
     const err = new Error(msg);
     err.status = resp.status;
     err.data = body?.data;
@@ -2026,7 +1859,7 @@ async function fetchFeedbackEvents({ apiBase, key, timeoutMs, feedbackId, limit
   return body.data || {};
 }
 
-async function postFeedbackReviewSubmission({ apiBase, key, timeoutMs, feedbackId, payload, idempotencyKey, clientSessionId, writeApproval }) {
+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(
@@ -2036,18 +1869,17 @@ async function postFeedbackReviewSubmission({ apiBase, key, timeoutMs, feedbackI
       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() } : {}),
-        ...writeApprovalHeaders(writeApproval),
-      },
+        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 = formatProjectApiErrorMessage(body, `Feedback review submission failed (${resp.status})`);
+    const msg = body?.message || `Feedback review submission failed (${resp.status})`;
     const err = new Error(msg);
     err.status = resp.status;
     err.data = body?.data;
@@ -2056,7 +1888,7 @@ async function postFeedbackReviewSubmission({ apiBase, key, timeoutMs, feedbackI
   return body.data || {};
 }
 
-async function postFeedbackReviewRequestMutation({ apiBase, key, timeoutMs, requestId, endpointAction, payload, idempotencyKey, clientSessionId, writeApproval }) {
+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(
@@ -2066,18 +1898,17 @@ async function postFeedbackReviewRequestMutation({ apiBase, key, timeoutMs, requ
       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() } : {}),
-        ...writeApprovalHeaders(writeApproval),
-      },
+        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 = formatProjectApiErrorMessage(body, `Feedback review ${endpointAction} failed (${resp.status})`);
+    const msg = body?.message || `Feedback review ${endpointAction} failed (${resp.status})`;
     const err = new Error(msg);
     err.status = resp.status;
     err.data = body?.data;
@@ -2086,7 +1917,7 @@ async function postFeedbackReviewRequestMutation({ apiBase, key, timeoutMs, requ
   return body.data || {};
 }
 
-async function postFeedbackBatchReviewMutation({ apiBase, key, timeoutMs, payload, idempotencyKey, clientSessionId, writeApproval }) {
+async function postFeedbackBatchReviewMutation({ apiBase, key, timeoutMs, payload, idempotencyKey, clientSessionId }) {
   const fetchFn = await getFetch();
   const url = `${apiBase}/project-assistant/feedback-review-requests/batch-review`;
   const { resp, body } = await fetchJsonWithTimeout(
@@ -2096,18 +1927,17 @@ async function postFeedbackBatchReviewMutation({ apiBase, key, timeoutMs, payloa
       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() } : {}),
-        ...writeApprovalHeaders(writeApproval),
-      },
+        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 = formatProjectApiErrorMessage(body, `Feedback batch review failed (${resp.status})`);
+    const msg = body?.message || `Feedback batch review failed (${resp.status})`;
     const err = new Error(msg);
     err.status = resp.status;
     err.data = body?.data;
@@ -2116,7 +1946,7 @@ async function postFeedbackBatchReviewMutation({ apiBase, key, timeoutMs, payloa
   return body.data || {};
 }
 
-async function postFeedbackBoardMutation({ apiBase, key, timeoutMs, feedbackId, endpoint, payload, idempotencyKey, clientSessionId, writeApproval }) {
+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(
@@ -2126,18 +1956,17 @@ async function postFeedbackBoardMutation({ apiBase, key, timeoutMs, feedbackId,
       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() } : {}),
-        ...writeApprovalHeaders(writeApproval),
-      },
+        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 = formatProjectApiErrorMessage(body, `Feedback board mutation failed (${resp.status})`);
+    const msg = body?.message || `Feedback board mutation failed (${resp.status})`;
     const err = new Error(msg);
     err.status = resp.status;
     err.data = body?.data;
@@ -2146,7 +1975,7 @@ async function postFeedbackBoardMutation({ apiBase, key, timeoutMs, feedbackId,
   return body.data || {};
 }
 
-async function postFeedbackBatchBoardMutation({ apiBase, key, timeoutMs, payload, idempotencyKey, clientSessionId, writeApproval }) {
+async function postFeedbackBatchBoardMutation({ apiBase, key, timeoutMs, payload, idempotencyKey, clientSessionId }) {
   const fetchFn = await getFetch();
   const url = `${apiBase}/project-assistant/feedback/batch-board-move`;
   const { resp, body } = await fetchJsonWithTimeout(
@@ -2156,57 +1985,55 @@ async function postFeedbackBatchBoardMutation({ apiBase, key, timeoutMs, payload
       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() } : {}),
-        ...writeApprovalHeaders(writeApproval),
-      },
+        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 = formatProjectApiErrorMessage(body, `Feedback batch board mutation failed (${resp.status})`);
+    const msg = body?.message || `Feedback batch 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 postFeedbackComment({ apiBase, key, timeoutMs, feedbackId, payload, idempotencyKey, clientSessionId, writeApproval }) {
-  const fetchFn = await getFetch();
-  const url = `${apiBase}/project-assistant/feedback/${encodeURIComponent(String(feedbackId || ""))}/comments`;
-  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() } : {}),
-        ...writeApprovalHeaders(writeApproval),
-      },
-      body: JSON.stringify(payload || {}),
-    },
-    timeoutMs
-  );
-
-  if (!resp.ok || body.status !== "success") {
-    const msg = formatProjectApiErrorMessage(body, `Feedback comment 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 }) {
+  return body.data || {};
+}
+
+async function postFeedbackComment({ apiBase, key, timeoutMs, feedbackId, payload, idempotencyKey, clientSessionId }) {
+  const fetchFn = await getFetch();
+  const url = `${apiBase}/project-assistant/feedback/${encodeURIComponent(String(feedbackId || ""))}/comments`;
+  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 comment 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(
@@ -2303,7 +2130,7 @@ function resolveProjectMutationIdempotencyKey({ args, operation, payload }) {
   return createHash("sha256").update(fingerprint).digest("hex");
 }
 
-async function postSuggestionsMutation({ apiBase, key, timeoutMs, endpoint, payload, idempotencyKey, clientSessionId, writeApproval }) {
+async function postSuggestionsMutation({ apiBase, key, timeoutMs, endpoint, payload, idempotencyKey, clientSessionId }) {
   const fetchFn = await getFetch();
   const url = `${apiBase}${endpoint}`;
   const { resp, body } = await fetchJsonWithTimeout(
@@ -2313,27 +2140,25 @@ async function postSuggestionsMutation({ apiBase, key, timeoutMs, endpoint, payl
       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() } : {}),
-        ...writeApprovalHeaders(writeApproval),
-      },
+        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 = formatProjectApiErrorMessage(body, `Mission suggestions request failed (${resp.status})`);
-    const err = new Error(msg);
-    err.status = resp.status;
-    err.data = body?.data;
+    const msg = body?.message || `Mission suggestions request failed (${resp.status})`;
+    const err = new Error(msg);
+    err.status = resp.status;
     throw err;
   }
   return body.data || {};
 }
 
-async function createRunQaqcBatch({ apiBase, key, timeoutMs, payload, idempotencyKey, clientSessionId, writeApproval }) {
+async function createRunQaqcBatch({ apiBase, key, timeoutMs, payload, idempotencyKey, clientSessionId }) {
   const fetchFn = await getFetch();
   const url = `${apiBase}/project-assistant/run-qaqc`;
   const { resp, body } = await fetchJsonWithTimeout(
@@ -2343,27 +2168,25 @@ async function createRunQaqcBatch({ apiBase, key, timeoutMs, payload, idempotenc
       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() } : {}),
-        ...writeApprovalHeaders(writeApproval),
-      },
+        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 = formatProjectApiErrorMessage(body, `Run QAQC request failed (${resp.status})`);
-    const err = new Error(msg);
-    err.status = resp.status;
-    err.data = body?.data;
-    throw err;
-  }
+    const msg = body?.message || `Run QAQC request failed (${resp.status})`;
+    const err = new Error(msg);
+    err.status = resp.status;
+    throw err;
+  }
   return body.data || {};
 }
 
-async function createMissionStatusUpdate({ apiBase, key, timeoutMs, payload, idempotencyKey, clientSessionId, writeApproval }) {
+async function createMissionStatusUpdate({ apiBase, key, timeoutMs, payload, idempotencyKey, clientSessionId }) {
   const fetchFn = await getFetch();
   const url = `${apiBase}/project-assistant/mission-status-update`;
   const { resp, body } = await fetchJsonWithTimeout(
@@ -2373,27 +2196,25 @@ async function createMissionStatusUpdate({ apiBase, key, timeoutMs, payload, ide
       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() } : {}),
-        ...writeApprovalHeaders(writeApproval),
-      },
+        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 = formatProjectApiErrorMessage(body, `Mission status update request failed (${resp.status})`);
-    const err = new Error(msg);
-    err.status = resp.status;
-    err.data = body?.data;
-    throw err;
-  }
+    const msg = body?.message || `Mission status update request failed (${resp.status})`;
+    const err = new Error(msg);
+    err.status = resp.status;
+    throw err;
+  }
   return body.data || {};
 }
 
-async function createMissionArchiveUpdate({ apiBase, key, timeoutMs, endpoint, payload, idempotencyKey, clientSessionId, writeApproval }) {
+async function createMissionArchiveUpdate({ apiBase, key, timeoutMs, endpoint, payload, idempotencyKey, clientSessionId }) {
   const fetchFn = await getFetch();
   const url = `${apiBase}${endpoint}`;
   const { resp, body } = await fetchJsonWithTimeout(
@@ -2403,21 +2224,19 @@ async function createMissionArchiveUpdate({ apiBase, key, timeoutMs, endpoint, p
       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() } : {}),
-        ...writeApprovalHeaders(writeApproval),
-      },
+        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 = formatProjectApiErrorMessage(body, `Mission archive request failed (${resp.status})`);
-    const err = new Error(msg);
-    err.status = resp.status;
-    err.data = body?.data;
+    const msg = body?.message || `Mission archive request failed (${resp.status})`;
+    const err = new Error(msg);
+    err.status = resp.status;
     throw err;
   }
   return body.data || {};
@@ -2530,15 +2349,20 @@ async function runRunQaqc(args) {
     process.exit(1);
   }
 
-  const payload = {
-    mission_ids: missionIds,
-    force: Boolean(args.force),
-  };
-  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
-  if (clientSessionId) payload.client_session_id = clientSessionId;
-  const idempotencyKey = resolveProjectMutationIdempotencyKey({
-    args,
-    operation: "run-qaqc",
+  let payload = {
+    mission_ids: missionIds,
+    force: Boolean(args.force),
+  };
+  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
+  if (clientSessionId) payload.client_session_id = clientSessionId;
+  payload = withWriteApproval(args, payload, {
+    artifactKind: "yaml",
+    targets: missionIds,
+    batchCount: missionIds.length > 1 ? missionIds.length : null,
+  });
+  const idempotencyKey = resolveProjectMutationIdempotencyKey({
+    args,
+    operation: "run-qaqc",
     payload,
   });
 
@@ -2547,28 +2371,21 @@ async function runRunQaqc(args) {
     return;
   }
 
-  const timeoutMs = resolveTimeoutMs(args);
-  const apiBase = resolveApiBase(args);
-  const shouldWait = Boolean(args.wait || args.sync);
-  const shouldSync = Boolean(args.sync);
-  const writeApproval = requireWriteApproval(args, payload, {
-    operation: "run-qaqc",
-    artifactKind: "yaml",
-    targets: missionIds,
-    batchCount: missionIds.length,
-  });
-
-  let data;
-  try {
-    data = await createRunQaqcBatch({
-      apiBase,
+  const timeoutMs = resolveTimeoutMs(args);
+  const apiBase = resolveApiBase(args);
+  const shouldWait = Boolean(args.wait || args.sync);
+  const shouldSync = Boolean(args.sync);
+
+  let data;
+  try {
+    data = await createRunQaqcBatch({
+      apiBase,
       key,
       timeoutMs,
-      payload,
-      idempotencyKey,
-      clientSessionId,
-      writeApproval,
-    });
+      payload,
+      idempotencyKey,
+      clientSessionId,
+    });
   } catch (err) {
     if (err?.name === "AbortError") {
       console.error(`Request timed out after ${timeoutMs}ms`);
@@ -2692,15 +2509,20 @@ async function runMissionStatus(args) {
     process.exit(1);
   }
 
-  const payload = {
-    mission_ids: missionIds,
-    new_status: newStatus,
-  };
-  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
-  if (clientSessionId) payload.client_session_id = clientSessionId;
-  const idempotencyKey = resolveProjectMutationIdempotencyKey({
-    args,
-    operation: "mission-status-update",
+  let payload = {
+    mission_ids: missionIds,
+    new_status: newStatus,
+  };
+  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
+  if (clientSessionId) payload.client_session_id = clientSessionId;
+  payload = withWriteApproval(args, payload, {
+    artifactKind: "yaml",
+    targets: missionIds,
+    batchCount: missionIds.length > 1 ? missionIds.length : null,
+  });
+  const idempotencyKey = resolveProjectMutationIdempotencyKey({
+    args,
+    operation: "mission-status-update",
     payload,
   });
 
@@ -2709,26 +2531,19 @@ async function runMissionStatus(args) {
     return;
   }
 
-  const timeoutMs = resolveTimeoutMs(args);
-  const apiBase = resolveApiBase(args);
-  const writeApproval = requireWriteApproval(args, payload, {
-    operation: "mission-status-update",
-    artifactKind: "yaml",
-    targets: missionIds,
-    batchCount: missionIds.length,
-  });
-
-  let data;
-  try {
-    data = await createMissionStatusUpdate({
-      apiBase,
+  const timeoutMs = resolveTimeoutMs(args);
+  const apiBase = resolveApiBase(args);
+
+  let data;
+  try {
+    data = await createMissionStatusUpdate({
+      apiBase,
       key,
       timeoutMs,
-      payload,
-      idempotencyKey,
-      clientSessionId,
-      writeApproval,
-    });
+      payload,
+      idempotencyKey,
+      clientSessionId,
+    });
   } catch (err) {
     if (err?.name === "AbortError") {
       console.error(`Request timed out after ${timeoutMs}ms`);
@@ -2802,13 +2617,18 @@ async function runMissionArchiveCommand(args) {
     process.exit(1);
   }
 
-  const payload = {
-    mission_ids: missionIds,
-  };
-  const reason = firstNonEmptyString(args.reason);
-  if (reason) payload.reason = reason;
-  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
-  if (clientSessionId) payload.client_session_id = clientSessionId;
+  let payload = {
+    mission_ids: missionIds,
+  };
+  const reason = firstNonEmptyString(args.reason);
+  if (reason) payload.reason = reason;
+  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
+  if (clientSessionId) payload.client_session_id = clientSessionId;
+  payload = withWriteApproval(args, payload, {
+    artifactKind: "yaml",
+    targets: missionIds,
+    batchCount: missionIds.length > 1 ? missionIds.length : null,
+  });
 
   const operation = "mission-archive";
   const idempotencyKey = resolveProjectMutationIdempotencyKey({
@@ -2822,28 +2642,21 @@ async function runMissionArchiveCommand(args) {
     return;
   }
 
-  const timeoutMs = resolveTimeoutMs(args);
-  const apiBase = resolveApiBase(args);
-  const endpoint = "/project-assistant/mission-archive";
-  const writeApproval = requireWriteApproval(args, payload, {
-    operation: "mission-archive",
-    artifactKind: "yaml",
-    targets: missionIds,
-    batchCount: missionIds.length,
-  });
-
-  let data;
-  try {
-    data = await createMissionArchiveUpdate({
-      apiBase,
+  const timeoutMs = resolveTimeoutMs(args);
+  const apiBase = resolveApiBase(args);
+  const endpoint = "/project-assistant/mission-archive";
+
+  let data;
+  try {
+    data = await createMissionArchiveUpdate({
+      apiBase,
       key,
       timeoutMs,
       endpoint,
-      payload,
-      idempotencyKey,
-      clientSessionId,
-      writeApproval,
-    });
+      payload,
+      idempotencyKey,
+      clientSessionId,
+    });
   } catch (err) {
     if (err?.name === "AbortError") {
       console.error(`Request timed out after ${timeoutMs}ms`);
@@ -2924,9 +2737,9 @@ async function runUpdateTeam(args) {
     process.exit(1);
   }
 
-  const payload = {
-    content: await resolveTeamUpdateContent(args),
-  };
+  let payload = {
+    content: await resolveTeamUpdateContent(args),
+  };
 
   if (args["print-context"] || args.printContext || args["dry-run"] || args.dryRun) {
     console.log(JSON.stringify(payload, null, 2));
@@ -2934,31 +2747,30 @@ async function runUpdateTeam(args) {
   }
 
   const timeoutMs = resolveTimeoutMs(args);
-  const apiBase = resolveApiBase(args);
-  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
-  if (clientSessionId) payload.client_session_id = clientSessionId;
-  const idempotencyKey = resolveProjectMutationIdempotencyKey({
-    args,
-    operation: "update_team",
-    payload,
-  });
-  const writeApproval = requireWriteApproval(args, payload, {
-    operation: "update_team",
+  const apiBase = resolveApiBase(args);
+  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
+  if (clientSessionId) payload.client_session_id = clientSessionId;
+  payload = withWriteApproval(args, payload, {
     artifactKind: "markdown",
+    targets: ["project"],
   });
-
-  let data;
-  try {
-    data = await postSuggestionsMutation({
+  const idempotencyKey = resolveProjectMutationIdempotencyKey({
+    args,
+    operation: "update_team",
+    payload,
+  });
+
+  let data;
+  try {
+    data = await postSuggestionsMutation({
       apiBase,
       key,
       payload,
       timeoutMs,
-      endpoint: "/project-assistant/project-comment",
-      idempotencyKey,
-      clientSessionId,
-      writeApproval,
-    });
+      endpoint: "/project-assistant/project-comment",
+      idempotencyKey,
+      clientSessionId,
+    });
   } catch (err) {
     if (err?.name === "AbortError") {
       console.error(`Request timed out after ${timeoutMs}ms`);
@@ -2997,10 +2809,10 @@ async function runUpdateOwner(args) {
     process.exit(1);
   }
 
-  const payload = {
-    subject,
-    body_markdown: await resolveOwnerUpdateBody(args),
-  };
+  let payload = {
+    subject,
+    body_markdown: await resolveOwnerUpdateBody(args),
+  };
 
   if (args["print-context"] || args.printContext || args["dry-run"] || args.dryRun) {
     console.log(JSON.stringify(payload, null, 2));
@@ -3008,31 +2820,30 @@ async function runUpdateOwner(args) {
   }
 
   const timeoutMs = resolveTimeoutMs(args);
-  const apiBase = resolveApiBase(args);
-  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
-  if (clientSessionId) payload.client_session_id = clientSessionId;
-  const idempotencyKey = resolveProjectMutationIdempotencyKey({
-    args,
-    operation: "update_owner",
-    payload,
-  });
-  const writeApproval = requireWriteApproval(args, payload, {
-    operation: "update_owner",
-    artifactKind: "markdown",
+  const apiBase = resolveApiBase(args);
+  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
+  if (clientSessionId) payload.client_session_id = clientSessionId;
+  payload = withWriteApproval(args, payload, {
+    artifactKind: "markdown",
+    targets: ["project"],
   });
-
-  let data;
-  try {
+  const idempotencyKey = resolveProjectMutationIdempotencyKey({
+    args,
+    operation: "update_owner",
+    payload,
+  });
+
+  let data;
+  try {
     data = await postSuggestionsMutation({
       apiBase,
       key,
       payload,
       timeoutMs,
-      endpoint: "/project-assistant/update-owner",
-      idempotencyKey,
-      clientSessionId,
-      writeApproval,
-    });
+      endpoint: "/project-assistant/update-owner",
+      idempotencyKey,
+      clientSessionId,
+    });
   } catch (err) {
     if (err?.name === "AbortError") {
       console.error(`Request timed out after ${timeoutMs}ms`);
@@ -3079,11 +2890,11 @@ async function runUpdateClient(args) {
     process.exit(1);
   }
 
-  const payload = {
-    subject,
-    body_markdown: await resolveClientUpdateBody(args),
-    target_contact_ids: resolveTargetContactIds(args),
-  };
+  let payload = {
+    subject,
+    body_markdown: await resolveClientUpdateBody(args),
+    target_contact_ids: resolveTargetContactIds(args),
+  };
 
   if (args["print-context"] || args.printContext || args["dry-run"] || args.dryRun) {
     console.log(JSON.stringify(payload, null, 2));
@@ -3091,31 +2902,30 @@ async function runUpdateClient(args) {
   }
 
   const timeoutMs = resolveTimeoutMs(args);
-  const apiBase = resolveApiBase(args);
-  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
-  if (clientSessionId) payload.client_session_id = clientSessionId;
-  const idempotencyKey = resolveProjectMutationIdempotencyKey({
-    args,
-    operation: "update_client",
-    payload,
-  });
-  const writeApproval = requireWriteApproval(args, payload, {
-    operation: "update_client",
+  const apiBase = resolveApiBase(args);
+  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
+  if (clientSessionId) payload.client_session_id = clientSessionId;
+  payload = withWriteApproval(args, payload, {
     artifactKind: "markdown",
+    targets: ["project"],
   });
-
-  let data;
-  try {
+  const idempotencyKey = resolveProjectMutationIdempotencyKey({
+    args,
+    operation: "update_client",
+    payload,
+  });
+
+  let data;
+  try {
     data = await postSuggestionsMutation({
       apiBase,
       key,
       payload,
       timeoutMs,
-      endpoint: "/project-assistant/client-update-drafts",
-      idempotencyKey,
-      clientSessionId,
-      writeApproval,
-    });
+      endpoint: "/project-assistant/client-update-drafts",
+      idempotencyKey,
+      clientSessionId,
+    });
   } catch (err) {
     if (err?.name === "AbortError") {
       console.error(`Request timed out after ${timeoutMs}ms`);
@@ -3207,23 +3017,138 @@ function stringifyYaml(value) {
   return `${JSON.stringify(value, null, 2)}\n`;
 }
 
-function stableJsonStringify(value) {
-  if (Array.isArray(value)) {
-    return `[${value.map((item) => stableJsonStringify(item)).join(",")}]`;
-  }
+function stableJsonStringify(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableJsonStringify(item)).join(",")}]`;
+  }
   if (value && typeof value === "object") {
     const entries = Object.keys(value)
       .sort()
       .map((key) => `${JSON.stringify(key)}:${stableJsonStringify(value[key])}`);
     return `{${entries.join(",")}}`;
-  }
-  return JSON.stringify(value);
-}
-
-function parseYaml(text) {
-  const raw = String(text || "").trim();
-  if (!raw) return null;
-  if (raw.startsWith("{") || raw.startsWith("[")) {
+  }
+  return JSON.stringify(value);
+}
+
+function pythonJsonStringify(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => pythonJsonStringify(item)).join(", ")}]`;
+  }
+  if (value && typeof value === "object") {
+    const entries = Object.keys(value)
+      .filter((key) => value[key] !== undefined)
+      .sort()
+      .map((key) => `${jsonStringEnsureAscii(key)}: ${pythonJsonStringify(value[key])}`);
+    return `{${entries.join(", ")}}`;
+  }
+  if (typeof value === "string") return jsonStringEnsureAscii(value);
+  if (value === undefined) return "null";
+  return JSON.stringify(value);
+}
+
+function jsonStringEnsureAscii(value) {
+  return JSON.stringify(String(value)).replace(/[^\x00-\x7F]/g, (char) => {
+    const code = char.charCodeAt(0);
+    return `\\u${code.toString(16).padStart(4, "0")}`;
+  });
+}
+
+function canonicalizeWritePayload(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => canonicalizeWritePayload(item));
+  }
+  if (value && typeof value === "object") {
+    const next = {};
+    for (const key of Object.keys(value)) {
+      if (key === "write_approval" || key === "client_session_id") continue;
+      if (value[key] === undefined) continue;
+      next[key] = canonicalizeWritePayload(value[key]);
+    }
+    return next;
+  }
+  return value;
+}
+
+function projectWritePayloadHash(payload) {
+  const canonical = canonicalizeWritePayload(payload || {});
+  return createHash("sha256").update(pythonJsonStringify(canonical)).digest("hex");
+}
+
+function approvalArtifactKind(artifactPath, fallback = "yaml") {
+  const ext = path.extname(String(artifactPath || "")).toLowerCase();
+  if (ext === ".md" || ext === ".markdown") return "markdown";
+  if (ext === ".json") return "json";
+  if (ext === ".yml" || ext === ".yaml") return "yaml";
+  return fallback || "yaml";
+}
+
+function resolveWriteApprovalArtifact(args) {
+  const artifactPath = firstNonEmptyString(
+    args["approval-artifact"],
+    args.approvalArtifact,
+    args.approval_artifact
+  );
+  if (!artifactPath) {
+    console.error("Missing --approval-artifact for confirmed live Myte write.");
+    process.exit(1);
+  }
+  const absPath = path.resolve(String(artifactPath));
+  if (!fs.existsSync(absPath) || !fs.statSync(absPath).isFile()) {
+    console.error(`Approval artifact not found: ${absPath}`);
+    process.exit(1);
+  }
+  const ext = path.extname(absPath).toLowerCase();
+  if (![".md", ".markdown", ".yml", ".yaml", ".json"].includes(ext)) {
+    console.error("Approval artifact must be a local .md, .yml, .yaml, or .json file.");
+    process.exit(1);
+  }
+  return { displayPath: String(artifactPath), absPath };
+}
+
+function approvalTargets(values) {
+  return uniqueNormalizedStrings(Array.isArray(values) ? values : [values]);
+}
+
+function withWriteApproval(args, payload, { artifactKind = "yaml", targets = [], batchCount = null } = {}) {
+  const confirmed = Boolean(args["confirm-write"] || args.confirmWrite || args.confirm_write);
+  if (!confirmed) return payload;
+  const { displayPath } = resolveWriteApprovalArtifact(args);
+  const nextPayload = { ...(payload || {}) };
+  const normalizedTargets = approvalTargets(targets);
+  const approval = {
+    approved: true,
+    source: "explicit_user_approval",
+    artifact_path: displayPath,
+    artifact_kind: approvalArtifactKind(displayPath, artifactKind),
+    payload_sha256: projectWritePayloadHash(nextPayload),
+  };
+  if (normalizedTargets.length) approval.targets = normalizedTargets;
+  if (batchCount !== undefined && batchCount !== null) approval.batch_count = Number(batchCount);
+  nextPayload.write_approval = approval;
+  return nextPayload;
+}
+
+function suggestionWriteTargets(items) {
+  return (Array.isArray(items) ? items : [])
+    .map((item, index) => {
+      if (!item || typeof item !== "object") return `index:${index}`;
+      const changeType = String(item.change_type || item.action || "suggestion").trim().toLowerCase() || "suggestion";
+      const changeSet = item.change_set && typeof item.change_set === "object" ? item.change_set : item;
+      return firstNonEmptyString(
+        item.suggestion_id,
+        item.mission_id,
+        item.client_ref,
+        changeSet.title ? `${changeType}:${String(changeSet.title).slice(0, 80)}` : "",
+        `index:${index}`
+      );
+    })
+    .filter(Boolean);
+}
+
+function parseYaml(text) {
+  const raw = String(text || "").trim();
+  if (!raw) return null;
+  if (raw.startsWith("{") || raw.startsWith("[")) {
     return JSON.parse(raw);
   }
   return parseSimpleYaml(raw);
@@ -4486,44 +4411,41 @@ async function fetchSuggestionsSyncSnapshot({ apiBase, key, timeoutMs, actorScop
   return body.data || {};
 }
 
-async function createProjectSuggestions({ apiBase, key, timeoutMs, payload, idempotencyKey, clientSessionId, writeApproval }) {
-  return postSuggestionsMutation({
-    apiBase,
-    key,
-    timeoutMs,
-    endpoint: "/project-assistant/suggestions",
-    payload,
-    idempotencyKey,
-    clientSessionId,
-    writeApproval,
-  });
-}
-
-async function reviseProjectSuggestions({ apiBase, key, timeoutMs, payload, idempotencyKey, clientSessionId, writeApproval }) {
-  return postSuggestionsMutation({
-    apiBase,
-    key,
-    timeoutMs,
-    endpoint: "/project-assistant/suggestions/revise",
-    payload,
-    idempotencyKey,
-    clientSessionId,
-    writeApproval,
-  });
-}
-
-async function reviewProjectSuggestions({ apiBase, key, timeoutMs, payload, idempotencyKey, clientSessionId, writeApproval }) {
-  return postSuggestionsMutation({
-    apiBase,
-    key,
-    timeoutMs,
-    endpoint: "/project-assistant/suggestions/review",
-    payload,
-    idempotencyKey,
-    clientSessionId,
-    writeApproval,
-  });
-}
+async function createProjectSuggestions({ apiBase, key, timeoutMs, payload, idempotencyKey, clientSessionId }) {
+  return postSuggestionsMutation({
+    apiBase,
+    key,
+    timeoutMs,
+    endpoint: "/project-assistant/suggestions",
+    payload,
+    idempotencyKey,
+    clientSessionId,
+  });
+}
+
+async function reviseProjectSuggestions({ apiBase, key, timeoutMs, payload, idempotencyKey, clientSessionId }) {
+  return postSuggestionsMutation({
+    apiBase,
+    key,
+    timeoutMs,
+    endpoint: "/project-assistant/suggestions/revise",
+    payload,
+    idempotencyKey,
+    clientSessionId,
+  });
+}
+
+async function reviewProjectSuggestions({ apiBase, key, timeoutMs, payload, idempotencyKey, clientSessionId }) {
+  return postSuggestionsMutation({
+    apiBase,
+    key,
+    timeoutMs,
+    endpoint: "/project-assistant/suggestions/review",
+    payload,
+    idempotencyKey,
+    clientSessionId,
+  });
+}
 
 async function runCreatePrd(args) {
   const key = (process.env.MYTE_API_KEY || process.env.MYTE_PROJECT_API_KEY || "").trim();
@@ -4630,31 +4552,29 @@ async function runCreatePrd(args) {
 
   const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
 
-  if (payloads.length === 1) {
-    let data;
-    const payload = payloads[0];
-    if (clientSessionId) payload.client_session_id = clientSessionId;
+  if (payloads.length === 1) {
+    let data;
+    let payload = payloads[0];
+    if (clientSessionId) payload.client_session_id = clientSessionId;
+    payload = withWriteApproval(args, payload, {
+      artifactKind: "markdown",
+      targets: [firstNonEmptyString(payload.client_ref, payload.title, "create-prd")],
+    });
     const idempotencyKey = resolveProjectMutationIdempotencyKey({
       args,
       operation: "create_prd",
-      payload,
-    });
-    const writeApproval = requireWriteApproval(args, payload, {
-      operation: "create_prd",
-      artifactKind: "markdown",
-      targets: prdApprovalTargets(payload),
-    });
-    try {
-      data = await postSuggestionsMutation({
-        apiBase,
-        key,
-        payload,
+      payload,
+    });
+    try {
+      data = await postSuggestionsMutation({
+        apiBase,
+        key,
+        payload,
         timeoutMs,
-        endpoint: "/project-assistant/create-prd",
-        idempotencyKey,
-        clientSessionId,
-        writeApproval,
-      });
+        endpoint: "/project-assistant/create-prd",
+        idempotencyKey,
+        clientSessionId,
+      });
     } catch (err) {
       if (err?.name === "AbortError") {
         console.error(`Request timed out after ${timeoutMs}ms`);
@@ -4695,32 +4615,29 @@ async function runCreatePrd(args) {
     failed_count: 0,
     items: [],
   };
-
-  try {
-    const payload = { items: payloads };
-    if (clientSessionId) payload.client_session_id = clientSessionId;
+
+  try {
+    let payload = { items: payloads };
+    if (clientSessionId) payload.client_session_id = clientSessionId;
+    payload = withWriteApproval(args, payload, {
+      artifactKind: "markdown",
+      targets: payloads.map((item, index) => firstNonEmptyString(item.client_ref, item.title, `index:${index}`)),
+      batchCount: payloads.length,
+    });
     const idempotencyKey = resolveProjectMutationIdempotencyKey({
       args,
       operation: "create_prds",
-      payload,
-    });
-    const prdTargets = prdApprovalTargets(payload);
-    const writeApproval = requireWriteApproval(args, payload, {
-      operation: "create_prds",
-      artifactKind: "markdown",
-      targets: prdTargets,
-      batchCount: prdTargets.length,
-    });
-    const data = await postSuggestionsMutation({
-      apiBase,
-      key,
-      payload,
-      timeoutMs,
-      endpoint: "/project-assistant/create-prds",
-      idempotencyKey,
-      clientSessionId,
-      writeApproval,
-    });
+      payload,
+    });
+    const data = await postSuggestionsMutation({
+      apiBase,
+      key,
+      payload,
+      timeoutMs,
+      endpoint: "/project-assistant/create-prds",
+      idempotencyKey,
+      clientSessionId,
+    });
     aggregated.project_id = data.project_id || null;
     aggregated.created_count = Number(data.created_count || 0);
     aggregated.failed_count = Number(data.failed_count || 0);
@@ -5276,7 +5193,8 @@ async function runFeedbackValidateOrApply(args, mode) {
     console.error("Missing MYTE_API_KEY (project key) in environment/.env");
     process.exit(1);
   }
-  const { absPath, payload } = readFeedbackRefinementArtifact(args);
+  const { absPath, payload: artifactPayload } = readFeedbackRefinementArtifact(args);
+  let payload = artifactPayload;
   const feedbackId = firstNonEmptyString(args["feedback-id"], args.feedbackId, args.feedback_id, payload.feedback_id);
   if (!feedbackId) {
     console.error("Feedback refinement artifact is missing feedback_id.");
@@ -5286,40 +5204,38 @@ async function runFeedbackValidateOrApply(args, mode) {
 
   const timeoutMs = resolveTimeoutMs(args);
   const apiBase = resolveApiBase(args);
-  const clientSessionId = firstNonEmptyString(
+  const clientSessionId = firstNonEmptyString(
     args["client-session-id"],
     args.clientSessionId,
     args.client_session_id,
     payload.client_session_id
-  );
+  );
+  if (mode === "apply") {
+    payload = withWriteApproval(args, payload, {
+      artifactKind: "yaml",
+      targets: [feedbackId],
+    });
+  }
   const idempotencyKey = mode === "apply"
-    ? resolveProjectMutationIdempotencyKey({
-        args,
-        operation: `feedback_refinement_apply:${feedbackId}`,
-        payload,
-      })
-    : null;
-  const writeApproval = mode === "apply"
-    ? requireWriteApproval(args, payload, {
-        operation: `feedback_refinement_apply:${feedbackId}`,
-        artifactKind: "yaml",
-        targets: [feedbackId],
-      })
-    : null;
-
-  let data;
-  try {
-    data = await postFeedbackRefinement({
-      apiBase,
+    ? resolveProjectMutationIdempotencyKey({
+        args,
+        operation: `feedback_refinement_apply:${feedbackId}`,
+        payload,
+      })
+    : null;
+
+  let data;
+  try {
+    data = await postFeedbackRefinement({
+      apiBase,
       key,
       timeoutMs,
       feedbackId,
       mode,
-      payload,
-      idempotencyKey,
-      clientSessionId,
-      writeApproval,
-    });
+      payload,
+      idempotencyKey,
+      clientSessionId,
+    });
   } catch (err) {
     if (args.json) {
       console.log(JSON.stringify({
@@ -5364,33 +5280,33 @@ 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 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]);
-}
-
-async function resolveFeedbackCommentContent(args, feedbackId) {
-  const explicit = firstNonEmptyString(args.body, args.content, args["body-markdown"], args.bodyMarkdown, args.body_markdown);
-  if (explicit) return explicit;
-
-  const bodyFile = firstNonEmptyString(args["body-file"], args.bodyFile, args.body_file);
-  if (bodyFile) {
-    const bodyPath = resolveInputFile(bodyFile, "Feedback comment body");
-    return fs.readFileSync(bodyPath, "utf8");
-  }
-
-  if (args.stdin) {
-    return readStdinText();
-  }
-
-  const positionals = Array.isArray(args._) ? args._.slice(1) : [];
-  const feedbackIdFromPositional = positionals[0] && String(positionals[0]) === String(feedbackId);
-  const textParts = feedbackIdFromPositional ? positionals.slice(1) : positionals;
-  return textParts.join(" ");
-}
+function resolveFeedbackVersionIdArg(args) {
+  return firstNonEmptyString(args["version-id"], args.versionId, args.version_id, args._?.[1]);
+}
+
+async function resolveFeedbackCommentContent(args, feedbackId) {
+  const explicit = firstNonEmptyString(args.body, args.content, args["body-markdown"], args.bodyMarkdown, args.body_markdown);
+  if (explicit) return explicit;
+
+  const bodyFile = firstNonEmptyString(args["body-file"], args.bodyFile, args.body_file);
+  if (bodyFile) {
+    const bodyPath = resolveInputFile(bodyFile, "Feedback comment body");
+    return fs.readFileSync(bodyPath, "utf8");
+  }
+
+  if (args.stdin) {
+    return readStdinText();
+  }
+
+  const positionals = Array.isArray(args._) ? args._.slice(1) : [];
+  const feedbackIdFromPositional = positionals[0] && String(positionals[0]) === String(feedbackId);
+  const textParts = feedbackIdFromPositional ? positionals.slice(1) : positionals;
+  return textParts.join(" ");
+}
 
 function summarizeFeedbackReviewRequestPayload(data) {
   const request = data?.request || data || {};
@@ -5430,7 +5346,8 @@ async function runFeedbackSubmit(args) {
     console.error("Missing MYTE_API_KEY (project key) in environment/.env");
     process.exit(1);
   }
-  const { absPath, payload } = readFeedbackRefinementArtifact(args);
+  const { absPath, payload: artifactPayload } = readFeedbackRefinementArtifact(args);
+  let payload = artifactPayload;
   const feedbackId = firstNonEmptyString(args["feedback-id"], args.feedbackId, args.feedback_id, payload.feedback_id);
   if (!feedbackId) {
     console.error("Feedback refinement artifact is missing feedback_id.");
@@ -5438,35 +5355,33 @@ async function runFeedbackSubmit(args) {
   }
   const timeoutMs = resolveTimeoutMs(args);
   const apiBase = resolveApiBase(args);
-  const clientSessionId = firstNonEmptyString(
+  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,
-  });
-  const writeApproval = requireWriteApproval(args, payload, {
-    operation: `feedback_refinement_request_submit:${feedbackId}`,
+  );
+  payload = withWriteApproval(args, payload, {
     artifactKind: "yaml",
     targets: [feedbackId],
   });
-
-  let data;
-  try {
-    data = await postFeedbackReviewSubmission({
+  const idempotencyKey = resolveProjectMutationIdempotencyKey({
+    args,
+    operation: `feedback_refinement_request_submit:${feedbackId}`,
+    payload,
+  });
+
+  let data;
+  try {
+    data = await postFeedbackReviewSubmission({
       apiBase,
       key,
       timeoutMs,
       feedbackId,
-      payload,
-      idempotencyKey,
-      clientSessionId,
-      writeApproval,
-    });
+      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));
@@ -5507,39 +5422,38 @@ async function runFeedbackRevise(args) {
     console.error("Missing --request-id.");
     process.exit(1);
   }
-  const { absPath, payload } = readFeedbackRefinementArtifact(args);
+  const { absPath, payload: artifactPayload } = readFeedbackRefinementArtifact(args);
+  let payload = artifactPayload;
   const timeoutMs = resolveTimeoutMs(args);
   const apiBase = resolveApiBase(args);
-  const clientSessionId = firstNonEmptyString(
+  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,
-  });
-  const writeApproval = requireWriteApproval(args, payload, {
-    operation: `feedback_refinement_request_revise:${requestId}`,
+  );
+  payload = withWriteApproval(args, payload, {
     artifactKind: "yaml",
     targets: [requestId],
   });
-
-  let data;
-  try {
-    data = await postFeedbackReviewRequestMutation({
+  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,
-      writeApproval,
-    });
+      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));
@@ -5656,41 +5570,36 @@ async function runFeedbackReviewDecision(args) {
       process.exit(1);
     }
     const reason = firstNonEmptyString(args.reason, args["review-note"], args.reviewNote, args.review_note);
-    const payload = {
-      ...(isPlainObject(filePayload) && !Array.isArray(filePayload) ? filePayload : {}),
-      items,
-      action,
-      reason: reason || undefined,
-    };
-    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_review_batch:${action}:${items.map((item) => item.request_id || item.id || "").join(",")}`,
-      payload,
-    });
-    const requestTargets = items
-      .map((item, index) => firstNonEmptyString(item.request_id, item.id, item._id) || `index:${index}`)
-      .filter(Boolean);
-    const writeApproval = requireWriteApproval(args, payload, {
-      operation: `feedback_review_batch:${action}`,
+    let payload = {
+      ...(isPlainObject(filePayload) && !Array.isArray(filePayload) ? filePayload : {}),
+      items,
+      action,
+      reason: reason || undefined,
+    };
+    payload = withWriteApproval(args, payload, {
       artifactKind: "yaml",
-      targets: requestTargets,
+      targets: items.map((item) => item.request_id || item.id).filter(Boolean),
       batchCount: items.length,
     });
-
-    let data;
-    try {
-      data = await postFeedbackBatchReviewMutation({
+    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_review_batch:${action}:${items.map((item) => item.request_id || item.id || "").join(",")}`,
+      payload,
+    });
+
+    let data;
+    try {
+      data = await postFeedbackBatchReviewMutation({
         apiBase,
         key,
         timeoutMs,
-        payload,
-        idempotencyKey,
-        clientSessionId,
-        writeApproval,
-      });
+        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));
@@ -5717,8 +5626,8 @@ async function runFeedbackReviewDecision(args) {
     process.exit(1);
   }
 
-  let payload;
-  try {
+  let payload;
+  try {
     payload = filePayload && !Array.isArray(filePayload?.items)
       ? buildFeedbackReviewDecisionPayload({ ...args, file: "" }, action)
       : buildFeedbackReviewDecisionPayload(args, action);
@@ -5729,35 +5638,33 @@ async function runFeedbackReviewDecision(args) {
     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,
-  });
-  const writeApproval = requireWriteApproval(args, payload, {
-    operation: `feedback_review_request_${operationAction}:${requestId}`,
+  const endpointAction = action === "request_changes" ? "request-changes" : action === "cancel" ? "cancel" : "review";
+  payload = withWriteApproval(args, payload, {
     artifactKind: "yaml",
     targets: [requestId],
   });
-
-  let data;
-  try {
-    data = await postFeedbackReviewRequestMutation({
+  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,
-      writeApproval,
-    });
+      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));
@@ -5777,7 +5684,7 @@ async function runFeedbackReviewDecision(args) {
   if (postSync?.error) console.error(`Feedback sync warning: ${postSync.error}`);
 }
 
-async function runFeedbackMove(args) {
+async function runFeedbackMove(args) {
   const key = getProjectApiKey();
   if (!key) {
     console.error("Missing MYTE_API_KEY (project key) in environment/.env");
@@ -5795,43 +5702,41 @@ async function runFeedbackMove(args) {
     process.exit(1);
   }
   const fromState = firstNonEmptyString(args["from-state"], args.fromState, args.from_state) || undefined;
-  const payload = {
-    to_state: toState,
-    reason: firstNonEmptyString(args.reason) || undefined,
-  };
+  let payload = {
+    to_state: toState,
+    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 isBatch = feedbackIds.length > 1 || Boolean(firstNonEmptyString(args["feedback-ids"], args.feedbackIds, args.feedback_ids));
-  if (isBatch) {
-    payload.feedback_ids = feedbackIds;
+  if (isBatch) {
+    payload.feedback_ids = feedbackIds;
     if (fromState) {
       payload.from_states = Object.fromEntries(feedbackIds.map((id) => [id, fromState]));
     }
     const batchId = firstNonEmptyString(args["batch-id"], args.batchId, args.batch_id);
-    if (batchId) payload.batch_id = batchId;
-    const idempotencyKey = resolveProjectMutationIdempotencyKey({
-      args,
-      operation: `feedback_board_batch_move:${toState}:${feedbackIds.join(",")}`,
-      payload,
-    });
-    const writeApproval = requireWriteApproval(args, payload, {
-      operation: `feedback_board_batch_move:${toState}`,
+    if (batchId) payload.batch_id = batchId;
+    payload = withWriteApproval(args, payload, {
       artifactKind: "yaml",
       targets: feedbackIds,
       batchCount: feedbackIds.length,
     });
-    let data;
-    try {
-      data = await postFeedbackBatchBoardMutation({
-        apiBase,
-        key,
+    const idempotencyKey = resolveProjectMutationIdempotencyKey({
+      args,
+      operation: `feedback_board_batch_move:${toState}:${feedbackIds.join(",")}`,
+      payload,
+    });
+    let data;
+    try {
+      data = await postFeedbackBatchBoardMutation({
+        apiBase,
+        key,
         timeoutMs,
-        payload,
-        idempotencyKey,
-        clientSessionId,
-        writeApproval,
-      });
+        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));
@@ -5851,32 +5756,30 @@ async function runFeedbackMove(args) {
     if (postSync?.error) console.error(`Feedback sync warning: ${postSync.error}`);
     return;
   }
-
-  payload.from_state = fromState;
-  const idempotencyKey = resolveProjectMutationIdempotencyKey({
-    args,
-    operation: `feedback_board_move:${feedbackId}`,
-    payload,
-  });
-  const writeApproval = requireWriteApproval(args, payload, {
-    operation: `feedback_board_move:${feedbackId}`,
+
+  payload.from_state = fromState;
+  payload = withWriteApproval(args, payload, {
     artifactKind: "yaml",
     targets: [feedbackId],
   });
-
-  let data;
-  try {
-    data = await postFeedbackBoardMutation({
+  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,
-      writeApproval,
-    });
+      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));
@@ -5896,92 +5799,89 @@ async function runFeedbackMove(args) {
   console.log(`State: ${data.feedback_state || toState}`);
   if (data.event?.event_id) console.log(`Event: ${data.event.event_id}`);
   if (postSync?.error) console.error(`Feedback sync warning: ${postSync.error}`);
-}
-
-async function runFeedbackComment(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 content = String(await resolveFeedbackCommentContent(args, feedbackId) || "").trim();
-  if (!content) {
-    console.error("Missing feedback comment body. Use --body, --body-file, --stdin, or positional text.");
-    process.exit(1);
-  }
-
-  const payload = { content };
+}
+
+async function runFeedbackComment(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 content = String(await resolveFeedbackCommentContent(args, feedbackId) || "").trim();
+  if (!content) {
+    console.error("Missing feedback comment body. Use --body, --body-file, --stdin, or positional text.");
+    process.exit(1);
+  }
+
+  let payload = { content };
   const timeoutMs = resolveTimeoutMs(args);
   const apiBase = resolveApiBase(args);
   const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
   if (clientSessionId) payload.client_session_id = clientSessionId;
-  const idempotencyKey = resolveProjectMutationIdempotencyKey({
-    args,
-    operation: `feedback_comment_create:${feedbackId}`,
-    payload,
-  });
-
-  if (args["print-context"] || args.printContext || args["dry-run"] || args.dryRun) {
-    console.log(JSON.stringify(payload, null, 2));
-    return;
-  }
-
-  const writeApproval = requireWriteApproval(args, payload, {
-    operation: `feedback_comment_create:${feedbackId}`,
+  payload = withWriteApproval(args, payload, {
     artifactKind: "markdown",
     targets: [feedbackId],
   });
-
-  let data;
-  try {
-    data = await postFeedbackComment({
-      apiBase,
-      key,
-      timeoutMs,
-      feedbackId,
-      payload,
-      idempotencyKey,
-      clientSessionId,
-      writeApproval,
-    });
-  } 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 comment failed:", err?.message || err);
-      if (err?.data) console.error(JSON.stringify(err.data, null, 2));
-    }
-    process.exit(1);
-  }
-
-  const postSync = await refreshFeedbackSnapshotAfterMutation(args, { apiBase, key, timeoutMs });
-  if (args.json) {
-    console.log(JSON.stringify({ ok: true, ...data, post_sync: postSync }, null, 2));
-    return;
-  }
-
-  if (data.comment_id) console.log(`Comment ID: ${data.comment_id}`);
-  console.log(`Feedback: ${data.feedback_id || feedbackId}`);
-  if (data.project_id) console.log(`Project ID: ${data.project_id}`);
-  if (data.user_name) console.log(`Author: ${data.user_name}`);
-  if (data.created_at) console.log(`Created At: ${data.created_at}`);
-  if (data.content) {
-    const body = String(data.content);
-    const truncated = body.length > 2000 ? `${body.slice(0, 2000)}\n...[truncated]` : body;
-    console.log("Content:");
-    console.log(truncated);
-  }
-  if (postSync?.data_root) console.log(`Synced feedback: ${postSync.data_root}`);
-  if (postSync?.error) console.error(`Feedback sync warning: ${postSync.error}`);
-}
-
-async function runFeedbackUndo(args) {
+  const idempotencyKey = resolveProjectMutationIdempotencyKey({
+    args,
+    operation: `feedback_comment_create:${feedbackId}`,
+    payload,
+  });
+
+  if (args["print-context"] || args.printContext || args["dry-run"] || args.dryRun) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  let data;
+  try {
+    data = await postFeedbackComment({
+      apiBase,
+      key,
+      timeoutMs,
+      feedbackId,
+      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 comment failed:", err?.message || err);
+      if (err?.data) console.error(JSON.stringify(err.data, null, 2));
+    }
+    process.exit(1);
+  }
+
+  const postSync = await refreshFeedbackSnapshotAfterMutation(args, { apiBase, key, timeoutMs });
+  if (args.json) {
+    console.log(JSON.stringify({ ok: true, ...data, post_sync: postSync }, null, 2));
+    return;
+  }
+
+  if (data.comment_id) console.log(`Comment ID: ${data.comment_id}`);
+  console.log(`Feedback: ${data.feedback_id || feedbackId}`);
+  if (data.project_id) console.log(`Project ID: ${data.project_id}`);
+  if (data.user_name) console.log(`Author: ${data.user_name}`);
+  if (data.created_at) console.log(`Created At: ${data.created_at}`);
+  if (data.content) {
+    const body = String(data.content);
+    const truncated = body.length > 2000 ? `${body.slice(0, 2000)}\n...[truncated]` : body;
+    console.log("Content:");
+    console.log(truncated);
+  }
+  if (postSync?.data_root) console.log(`Synced feedback: ${postSync.data_root}`);
+  if (postSync?.error) console.error(`Feedback sync warning: ${postSync.error}`);
+}
+
+async function runFeedbackUndo(args) {
   const key = getProjectApiKey();
   if (!key) {
     console.error("Missing MYTE_API_KEY (project key) in environment/.env");
@@ -5997,40 +5897,32 @@ async function runFeedbackUndo(args) {
     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,
-  });
-
-  if (args["print-context"] || args.printContext || args["dry-run"] || args.dryRun) {
-    console.log(JSON.stringify(payload, null, 2));
-    return;
-  }
-
-  const writeApproval = requireWriteApproval(args, payload, {
-    operation: `feedback_event_undo:${feedbackId}:${eventId}`,
+  let 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);
+  payload = withWriteApproval(args, payload, {
     artifactKind: "yaml",
     targets: [feedbackId, eventId],
   });
-
-  let data;
-  try {
+  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,
-      writeApproval,
-    });
+      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));
@@ -6188,15 +6080,15 @@ async function runFeedback(args) {
     await runFeedbackReviewDecision(args);
     return;
   }
-  if (subcommand === "move") {
-    await runFeedbackMove(args);
-    return;
-  }
-  if (subcommand === "comment" || subcommand === "comments") {
-    await runFeedbackComment(args);
-    return;
-  }
-  if (subcommand === "undo") {
+  if (subcommand === "move") {
+    await runFeedbackMove(args);
+    return;
+  }
+  if (subcommand === "comment" || subcommand === "comments") {
+    await runFeedbackComment(args);
+    return;
+  }
+  if (subcommand === "undo") {
     await runFeedbackUndo(args);
     return;
   }
@@ -6212,7 +6104,7 @@ async function runFeedback(args) {
     await runFeedbackGetOrHistory(args, subcommand);
     return;
   }
-  console.error("Unknown feedback command. Use status, edit, assign, archive, submit, revise, reviews, review, move, comment, undo, prd-versions, prd-diff, get, history, validate, or apply.");
+  console.error("Unknown feedback command. Use status, edit, assign, archive, submit, revise, reviews, review, move, comment, undo, prd-versions, prd-diff, get, history, validate, or apply.");
   process.exit(1);
 }
 
@@ -6315,14 +6207,20 @@ async function buildSuggestionsMutationContext(args, mode) {
   if (clientSessionId && !payload.client_session_id) {
     payload.client_session_id = clientSessionId;
   }
-  if (mode === "create") {
-    validateSuggestionsCreatePayload(payload);
-  } else if (mode === "revise") {
-    validateSuggestionsRevisePayload(payload);
-  }
-  const idempotencyKey = resolveSuggestionsIdempotencyKey({
-    args,
-    mode,
+  if (mode === "create") {
+    validateSuggestionsCreatePayload(payload);
+  } else if (mode === "revise") {
+    validateSuggestionsRevisePayload(payload);
+  }
+  const items = Array.isArray(payload?.items) ? payload.items : [];
+  payload = withWriteApproval(args, payload, {
+    artifactKind: "yaml",
+    targets: suggestionWriteTargets(items),
+    batchCount: items.length > 1 ? items.length : null,
+  });
+  const idempotencyKey = resolveSuggestionsIdempotencyKey({
+    args,
+    mode,
     actorScope,
     payload,
   });
@@ -6403,30 +6301,21 @@ async function runSuggestionsCreate(args) {
     process.exit(1);
   }
 
-  if (args["print-context"] || args.printContext || args["dry-run"] || args.dryRun) {
-    console.log(JSON.stringify(context.payload, null, 2));
-    return;
-  }
-
-  const createTargets = suggestionApprovalTargets(context.payload);
-  const writeApproval = requireWriteApproval(args, context.payload, {
-    operation: "suggestions.create",
-    artifactKind: "yaml",
-    targets: createTargets,
-    batchCount: createTargets.length > 1 ? createTargets.length : null,
-  });
-
-  let data;
-  try {
-    data = await createProjectSuggestions({
-      apiBase: context.apiBase,
-      key: context.key,
+  if (args["print-context"] || args.printContext || args["dry-run"] || args.dryRun) {
+    console.log(JSON.stringify(context.payload, null, 2));
+    return;
+  }
+
+  let data;
+  try {
+    data = await createProjectSuggestions({
+      apiBase: context.apiBase,
+      key: context.key,
       timeoutMs: context.timeoutMs,
-      payload: context.payload,
-      idempotencyKey: context.idempotencyKey,
-      clientSessionId: context.clientSessionId,
-      writeApproval,
-    });
+      payload: context.payload,
+      idempotencyKey: context.idempotencyKey,
+      clientSessionId: context.clientSessionId,
+    });
   } catch (err) {
     console.error("Suggestions create failed:", err?.message || err);
     process.exit(1);
@@ -6497,30 +6386,21 @@ async function runSuggestionsRevise(args) {
     process.exit(1);
   }
 
-  if (args["print-context"] || args.printContext || args["dry-run"] || args.dryRun) {
-    console.log(JSON.stringify(context.payload, null, 2));
-    return;
-  }
-
-  const reviseTargets = suggestionApprovalTargets(context.payload);
-  const writeApproval = requireWriteApproval(args, context.payload, {
-    operation: "suggestions.revise",
-    artifactKind: "yaml",
-    targets: reviseTargets,
-    batchCount: reviseTargets.length > 1 ? reviseTargets.length : null,
-  });
-
-  let data;
-  try {
-    data = await reviseProjectSuggestions({
-      apiBase: context.apiBase,
-      key: context.key,
+  if (args["print-context"] || args.printContext || args["dry-run"] || args.dryRun) {
+    console.log(JSON.stringify(context.payload, null, 2));
+    return;
+  }
+
+  let data;
+  try {
+    data = await reviseProjectSuggestions({
+      apiBase: context.apiBase,
+      key: context.key,
       timeoutMs: context.timeoutMs,
-      payload: context.payload,
-      idempotencyKey: context.idempotencyKey,
-      clientSessionId: context.clientSessionId,
-      writeApproval,
-    });
+      payload: context.payload,
+      idempotencyKey: context.idempotencyKey,
+      clientSessionId: context.clientSessionId,
+    });
   } catch (err) {
     console.error("Suggestions revise failed:", err?.message || err);
     process.exit(1);
@@ -6589,30 +6469,21 @@ async function runSuggestionsReview(args) {
     process.exit(1);
   }
 
-  if (args["print-context"] || args.printContext || args["dry-run"] || args.dryRun) {
-    console.log(JSON.stringify(context.payload, null, 2));
-    return;
-  }
-
-  const reviewTargets = suggestionApprovalTargets(context.payload);
-  const writeApproval = requireWriteApproval(args, context.payload, {
-    operation: "suggestions.review",
-    artifactKind: "yaml",
-    targets: reviewTargets,
-    batchCount: reviewTargets.length > 1 ? reviewTargets.length : null,
-  });
-
-  let data;
-  try {
-    data = await reviewProjectSuggestions({
-      apiBase: context.apiBase,
-      key: context.key,
+  if (args["print-context"] || args.printContext || args["dry-run"] || args.dryRun) {
+    console.log(JSON.stringify(context.payload, null, 2));
+    return;
+  }
+
+  let data;
+  try {
+    data = await reviewProjectSuggestions({
+      apiBase: context.apiBase,
+      key: context.key,
       timeoutMs: context.timeoutMs,
-      payload: context.payload,
-      idempotencyKey: context.idempotencyKey,
-      clientSessionId: context.clientSessionId,
-      writeApproval,
-    });
+      payload: context.payload,
+      idempotencyKey: context.idempotencyKey,
+      clientSessionId: context.clientSessionId,
+    });
   } catch (err) {
     console.error("Suggestions review failed:", err?.message || err);
     process.exit(1);