@mytegroupinc/myte-core 0.0.19 → 0.0.21

package/cli.js

@@ -4,7 +4,7 @@
  *
  * - Auth: MYTE_API_KEY (project key) from `.env` or env
  * - Default API: https://api.myte.dev (override with MYTE_API_BASE or --base-url)
- * - Deterministic diffs: fetch /api/project-assistant/config to get repo folder names
+ * - Deterministic diffs: fetch project config, resolve local project repos, then collect scoped git context
  */
 
 const fs = require("fs");
@@ -98,6 +98,7 @@ function splitCommand(argv) {
     "update-owner",
     "update-client",
     "feedback-sync",
+    "feedback",
     "help",
     "--help",
     "-h",
@@ -141,6 +142,17 @@ function parseArgs(argv) {
         "target-contact-ids",
         "status",
         "source",
+        "feedback-id",
+        "reason",
+        "review-action",
+        "idempotency-key",
+        "user-id",
+        "assigned-user-id",
+        "due-date",
+        "priority",
+        "review-note",
+        "tags",
+        "tag",
         "mission-ids",
         "client-session-id",
       ],
@@ -194,7 +206,7 @@ function parseArgs(argv) {
 
 function printHelp() {
   const text = [
-    "myte - Myte Project Assistant CLI",
+    "myte - Myte CLI",
     "",
     "Usage:",
     "  myte query \"<text>\" [--with-diff] [--context \"...\"]",
@@ -212,6 +224,10 @@ function printHelp() {
     "  myte update-owner --subject \"<text>\" [--body-markdown \"...\"] [--body-file ./update.md] [--json]",
     "  myte update-client --subject \"<text>\" [--body-markdown \"...\"] [--body-file ./update.md] [--target-contact-ids <id1,id2>] [--json]",
     "  myte feedback-sync [--status <value>] [--source <value>] [--with-prd-text|--no-with-prd-text] [--output-dir ./MyteCommandCenter] [--json]",
+    "  myte feedback status --feedback-id <id> --status todo|in_progress|in_review|completed|deployed|rejected|archived --reason \"...\"",
+    "  myte feedback edit --feedback-id <id> [--title \"...\"] [--feedback-text \"...\"] [--priority High] [--reason \"...\"]",
+    "  myte feedback validate --file ./MyteCommandCenter/reviews/feedback/<id>-status.yml [--json]",
+    "  myte feedback apply --file ./MyteCommandCenter/reviews/feedback/<id>-status.yml [--json]",
     "  myte create-prd <file.md> [more.md ...] [--json] [--title \"...\"] [--description \"...\"]",
     "  cat file.md | myte create-prd --stdin [--title \"...\"] [--description \"...\"]",
     "  cat update.md | myte update-owner --stdin --subject \"Owner update\"",
@@ -232,13 +248,13 @@ function printHelp() {
     "  - Set MYTEAI_API_KEY in a workspace .env (or env var) for `myte ai`",
     "",
     "bootstrap contract:",
-    "  - Run from the wrapper root that contains the project's configured repo folders",
+    "  - Run from any workspace where you want local MyteCommandCenter data written",
     "  - Writes MyteCommandCenter/data/project.yml plus phases, epics, stories, and missions locally",
     "  - Uses the project-scoped bootstrap snapshot from the Myte API",
     "  - Mission cards include richer execution context like complexity, estimated_hours, due_date, subtasks, technical_requirements, resources_needed, labels, and normalized test_cases",
     "",
     "sync-qaqc contract:",
-    "  - Run from the wrapper root that contains the project's configured repo folders",
+    "  - Run from any workspace where you want local MyteCommandCenter data written",
     "  - Works even if bootstrap has not been run yet; it creates MyteCommandCenter/data/qaqc.yml",
     "  - Writes the active mission QAQC working set into one deterministic file: MyteCommandCenter/data/qaqc.yml",
     "",
@@ -285,13 +301,19 @@ function printHelp() {
     "  - If the project has no linked client contacts, the backend falls back to the project owner for internal projects",
     "",
     "feedback-sync contract:",
-    "  - Runs from the wrapper root that contains the project's configured repo folders",
+    "  - Runs from any workspace where you want local MyteCommandCenter data written",
     "  - Syncs pending feedback by default so local Command Center data stays focused on active work",
     "  - 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",
     "",
+    "feedback review contract:",
+    "  - Draft commands write review artifacts under MyteCommandCenter/reviews/feedback/*.yml for local IDE diff review",
+    "  - validate/apply send those artifacts to /api/project-assistant/feedback/<id>/refinement/*",
+    "  - The backend owns authorization, stale snapshot checks, allowed field/transition rules, and history",
+    "  - apply is idempotent and does not rewrite local feedback.yml; run feedback-sync after apply to refresh local state",
+    "",
     "Options:",
-    "  --with-diff           Include deterministic git diffs (project-scoped)",
+    "  --with-diff           Include deterministic git diffs (project-scoped; fails fast if no project repos are configured or resolved)",
     "  --diff-limit <chars>  Truncate diff context to N chars (default: 200000)",
     "  --timeout-ms <ms>     Request timeout (default: 300000)",
     "  --base-url <url>      API base (default: https://api.myte.dev)",
@@ -299,7 +321,7 @@ function printHelp() {
     "  --json-response       Ask the Myte AI gateway to return clean JSON only and send OpenAI-compatible response_format",
     "  --max-output-tokens   Output token cap for `myte ai` simple queries",
     "  --temperature <num>   Temperature for `myte ai` simple queries",
-    "  --output-dir <path>   Command Center output directory (default: <wrapper-root>/MyteCommandCenter)",
+    "  --output-dir <path>   Command Center output directory (default: <current-workspace>/MyteCommandCenter)",
     "  --file <path>         YAML/JSON payload file for suggestions create/revise/review",
     "  --stdin               Read supported command content from stdin instead of inline text or a file path",
     "  --title <text>        Override PRD title for raw markdown uploads",
@@ -310,8 +332,15 @@ function printHelp() {
     "  --body-file <path>    Read 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",
-    "  --status <value>      For mission status: required target status (todo|in_progress|done). For feedback-sync: optional filter (default: Pending).",
+    "  --feedback-id <id>    Feedback ObjectId for feedback review commands",
+    "  --reason <text>       Human review reason included in feedback refinement artifacts",
+    "  --status <value>      Mission status target, feedback-sync filter, or feedback review state depending on command",
     "  --source <value>      Feedback source filter for feedback-sync",
+    "  --priority <value>    Feedback review priority target: Low, Medium, or High",
+    "  --user-id <id>        Feedback assignee user id for `myte feedback assign`",
+    "  --assigned-user-id    Alias for --user-id in feedback assign",
+    "  --due-date <date>     Feedback due date target for edit artifacts",
+    "  --review-note <text>  Review note stored in feedback refinement history",
     "  --with-prd-text       Include extracted PRD text so local PRD files are materialized during feedback-sync (default: on)",
     "  --no-with-prd-text    Skip PRD text download and write only feedback metadata/comment turns",
     "  --mission-ids <ids>   Comma-separated mission business ids for run-qaqc or mission status (quote multi-id values on PowerShell)",
@@ -340,6 +369,9 @@ function printHelp() {
     "  myte update-owner --subject \"QAQC progress\" --body-file ./updates/owner.md",
     "  myte update-client --subject \"Weekly client update\" --body-file ./updates/week-12.md",
     "  myte feedback-sync --json",
+    "  myte feedback status --feedback-id 507f1f77bcf86cd799439011 --status in_review --reason \"Ready for owner review\"",
+    "  myte feedback 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",
     "  myte suggestions review",
@@ -589,18 +621,25 @@ function summarizeDiffDiagnosticsForContext(diagnostics) {
     project_id: diagnostics.project_id || null,
     mode: diagnostics.mode,
     requested_repos: diagnostics.requested_repo_names || [],
+    requested_repo_bindings: diagnostics.requested_repo_bindings || [],
     found_repos: diagnostics.found_repos || [],
     missing_repos: diagnostics.missing_repos || [],
     collected_any: Boolean(diagnostics.collected_any),
     truncation: diagnostics.truncated ? "truncated" : "full",
     repos: repos.map((repo) => ({
       name: repo.name,
+      role: repo.role || null,
       status: repo.status || "ok",
       head_branch: repo.head_branch || null,
       base_ref: repo.base_ref || null,
+      base_ref_label: repo.base_ref_label || repo.base_ref || null,
+      baseline_branch: repo.baseline_branch || null,
+      compare_mode: repo.compare_mode || "local_origin",
+      compare_remote_url: repo.compare_remote_url || null,
       has_changes: Boolean(repo.has_changes),
       changed_blocks: repo.changed_blocks || {},
       untracked_file_count: repo.untracked_file_count || 0,
+      matched_by: repo.matched_by || [],
       error_count: Array.isArray(repo.errors) ? repo.errors.length : 0,
     })),
     warnings: diagnostics.warnings || [],
@@ -642,8 +681,29 @@ const IGNORED_PATTERNS = [
   /^out\//,
 ];
 
+const DIFF_MARKDOWN_ALLOWLIST = new Set([
+  "README.md",
+  "AGENTS.md",
+  "CodexContext.MD",
+  "CLAUDE.md",
+  "GEMINI.md",
+]);
+
+function normalizeRepoPathForDiff(p) {
+  return String(p || "").replace(/\\/g, "/");
+}
+
+function shouldIgnoreMarkdownPath(p) {
+  const normalized = normalizeRepoPathForDiff(p);
+  if (!/\.md$/i.test(normalized)) return false;
+  const base = path.posix.basename(normalized);
+  return !DIFF_MARKDOWN_ALLOWLIST.has(base);
+}
+
 function shouldIgnore(p) {
-  return IGNORED_PATTERNS.some((re) => re.test(p));
+  const normalized = normalizeRepoPathForDiff(p);
+  if (shouldIgnoreMarkdownPath(normalized)) return true;
+  return IGNORED_PATTERNS.some((re) => re.test(normalized));
 }
 
 function hasGitDir(repoPath) {
@@ -833,12 +893,373 @@ function resolveConfiguredRepos(repoNames) {
   return { mode: "none", root: null, repos: [], missing: names };
 }
 
-function fetchBaseBranches(repoPath) {
+function findGitTopLevel(startPath) {
+  const result = runGitRaw(startPath, ["rev-parse", "--show-toplevel"]);
+  if (!result.ok) return null;
+  const value = String(result.stdout || "").trim();
+  return value || null;
+}
+
+function normalizeRemoteFingerprint(value) {
+  const raw = String(value || "").trim();
+  if (!raw) return "";
+
+  const cleaned = raw.replace(/\\/g, "/").replace(/\.git$/i, "");
+  const looksLikeLocalPath =
+    !cleaned.includes("://") &&
+    (/^[a-zA-Z]:\//.test(cleaned) || cleaned.startsWith("/") || cleaned.startsWith("./") || cleaned.startsWith("../"));
+  if (looksLikeLocalPath) {
+    return `local/${cleaned.toLowerCase()}`;
+  }
+  const sshMatch = cleaned.match(/^(?:.+@)?([^:/]+)[:/](.+)$/);
+  if (!cleaned.includes("://") && sshMatch) {
+    const host = String(sshMatch[1] || "").trim().toLowerCase();
+    const repoPath = String(sshMatch[2] || "")
+      .trim()
+      .replace(/^\/+/, "")
+      .replace(/\/+$/, "")
+      .toLowerCase();
+    return host && repoPath ? `${host}/${repoPath}` : "";
+  }
+
+  try {
+    const parsed = new URL(cleaned);
+    const host = String(parsed.hostname || "").trim().toLowerCase();
+    const repoPath = String(parsed.pathname || "")
+      .trim()
+      .replace(/^\/+/, "")
+      .replace(/\/+$/, "")
+      .toLowerCase();
+    return host && repoPath ? `${host}/${repoPath}` : "";
+  } catch {
+    return cleaned.toLowerCase();
+  }
+}
+
+function uniqueNormalizedStrings(values) {
+  const seen = new Set();
+  const ordered = [];
+  for (const value of Array.isArray(values) ? values : []) {
+    const text = String(value || "").trim();
+    if (!text) continue;
+    const key = text.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    ordered.push(text);
+  }
+  return ordered;
+}
+
+function normalizeRepoBindingEntry(binding, index = 0) {
+  if (!binding || typeof binding !== "object") return null;
+
+  const role = String(binding.role || "").trim().toLowerCase();
+  const canonicalRepoName = String(binding.canonical_repo_name || "").trim();
+  const canonicalRemoteUrl = String(binding.canonical_remote_url || "").trim();
+  const clientRepoName = String(binding.client_repo_name || "").trim();
+  const clientRemoteUrl = String(binding.client_remote_url || "").trim();
+  const localRepoAliases = uniqueNormalizedStrings(binding.local_repo_aliases || []);
+  const baselineBranch = String(binding.baseline_branch || "").trim();
+
+  const remoteFingerprints = uniqueNormalizedStrings([
+    ...(Array.isArray(binding.remote_fingerprints) ? binding.remote_fingerprints : []),
+    normalizeRemoteFingerprint(canonicalRemoteUrl),
+    normalizeRemoteFingerprint(clientRemoteUrl),
+  ]);
+
+  const matchingNames = uniqueNormalizedStrings([
+    ...(Array.isArray(binding.matching_names) ? binding.matching_names : []),
+    canonicalRepoName,
+    clientRepoName,
+    ...localRepoAliases,
+  ]);
+
+  if (!role && !matchingNames.length && !remoteFingerprints.length) return null;
+
+  return {
+    role: role || `repo_${index + 1}`,
+    canonical_repo_name: canonicalRepoName || null,
+    canonical_remote_url: canonicalRemoteUrl || null,
+    client_repo_name: clientRepoName || null,
+    client_remote_url: clientRemoteUrl || null,
+    local_repo_aliases: localRepoAliases,
+    baseline_branch: baselineBranch || null,
+    matching_names: matchingNames,
+    remote_fingerprints: remoteFingerprints,
+  };
+}
+
+function normalizeRepoBindings(bindings) {
+  const normalized = [];
+  const seenRoles = new Set();
+  for (const [index, binding] of (Array.isArray(bindings) ? bindings : []).entries()) {
+    const item = normalizeRepoBindingEntry(binding, index);
+    if (!item) continue;
+    const roleKey = String(item.role || "").trim().toLowerCase();
+    if (seenRoles.has(roleKey)) continue;
+    seenRoles.add(roleKey);
+    normalized.push(item);
+  }
+  return normalized;
+}
+
+function getRepoRemoteFingerprints(repoPath) {
+  const output = runGitTry(repoPath, ["remote", "-v"]);
+  if (!output) return [];
+  const fingerprints = [];
+  for (const line of String(output).split(/\r?\n/)) {
+    const parts = line.trim().split(/\s+/);
+    if (parts.length < 2) continue;
+    const normalized = normalizeRemoteFingerprint(parts[1]);
+    if (normalized) fingerprints.push(normalized);
+  }
+  return uniqueNormalizedStrings(fingerprints);
+}
+
+function listGitRepoCandidates(searchRoot, currentRepoRoot) {
+  const candidates = [];
+  const seen = new Set();
+
+  function pushCandidate(absPath, rootForDir) {
+    const abs = path.resolve(absPath);
+    if (!hasGitDir(abs) || seen.has(abs)) return;
+    seen.add(abs);
+    const rootBase = rootForDir ? path.resolve(rootForDir) : path.dirname(abs);
+    const rel = path.relative(rootBase, abs);
+    const dir = rel && rel !== "" ? rel : ".";
+    const repoName = path.basename(abs);
+    candidates.push({
+      abs,
+      dir,
+      name: repoName,
+      prefix: `${repoName.replace(/\\\\/g, "/")}/`,
+      remote_fingerprints: getRepoRemoteFingerprints(abs),
+      is_current_repo: currentRepoRoot ? path.resolve(currentRepoRoot) === abs : false,
+    });
+  }
+
+  if (currentRepoRoot) {
+    pushCandidate(currentRepoRoot, path.dirname(currentRepoRoot));
+  }
+
+  pushCandidate(searchRoot, path.dirname(searchRoot));
+
+  let entries = [];
+  try {
+    entries = fs.readdirSync(searchRoot, { withFileTypes: true });
+  } catch {
+    entries = [];
+  }
+  for (const entry of entries) {
+    if (!entry || !entry.isDirectory || !entry.isDirectory()) continue;
+    const abs = path.join(searchRoot, entry.name);
+    pushCandidate(abs, searchRoot);
+  }
+
+  return candidates;
+}
+
+function scoreBindingCandidate(binding, candidate) {
+  const candidateName = String(candidate?.name || "").trim().toLowerCase();
+  const bindingNames = new Set((binding?.matching_names || []).map((name) => String(name || "").trim().toLowerCase()).filter(Boolean));
+  const bindingRemotes = new Set((binding?.remote_fingerprints || []).map((value) => String(value || "").trim().toLowerCase()).filter(Boolean));
+  const candidateRemotes = new Set((candidate?.remote_fingerprints || []).map((value) => String(value || "").trim().toLowerCase()).filter(Boolean));
+  const canonicalRemoteFingerprint = normalizeRemoteFingerprint(binding?.canonical_remote_url).toLowerCase();
+  const clientRemoteFingerprint = normalizeRemoteFingerprint(binding?.client_remote_url).toLowerCase();
+
+  let score = 0;
+  const matchedBy = [];
+
+  if (binding.canonical_repo_name && candidateName === String(binding.canonical_repo_name).trim().toLowerCase()) {
+    score = Math.max(score, 240);
+    matchedBy.push("canonical_name");
+  }
+  if (binding.client_repo_name && candidateName === String(binding.client_repo_name).trim().toLowerCase()) {
+    score = Math.max(score, 260);
+    matchedBy.push("client_name");
+  }
+  if (bindingNames.has(candidateName)) {
+    score = Math.max(score, 200);
+    matchedBy.push("alias");
+  }
+  for (const remote of candidateRemotes) {
+    if (clientRemoteFingerprint && remote === clientRemoteFingerprint) {
+      score = Math.max(score, 340);
+      matchedBy.push("client_remote");
+      break;
+    }
+    if (canonicalRemoteFingerprint && remote === canonicalRemoteFingerprint) {
+      score = Math.max(score, 300);
+      matchedBy.push("canonical_remote");
+      break;
+    }
+    if (bindingRemotes.has(remote)) {
+      score = Math.max(score, 320);
+      matchedBy.push("remote");
+      break;
+    }
+  }
+
+  return { score, matchedBy: uniqueNormalizedStrings(matchedBy) };
+}
+
+function resolveConfiguredRepoBindings(bindings) {
+  const normalizedBindings = normalizeRepoBindings(bindings);
+  if (!normalizedBindings.length) {
+    return { mode: "none", root: null, repos: [], missing: [], bindings: [] };
+  }
+
+  const cwd = process.cwd();
+  const currentRepoRoot = findGitTopLevel(cwd);
+  const searchRoots = [];
+  const seenRoots = new Set();
+  const pushSearchRoot = (value) => {
+    if (!value) return;
+    const resolved = path.resolve(value);
+    if (seenRoots.has(resolved)) return;
+    seenRoots.add(resolved);
+    searchRoots.push(resolved);
+  };
+
+  // Prefer the invocation workspace first. A wrapper repo can contain the
+  // configured API/WEB repos as children, so jumping immediately to the parent
+  // can miss the project repos entirely.
+  pushSearchRoot(cwd);
+  if (currentRepoRoot) pushSearchRoot(currentRepoRoot);
+
+  const scanStart = currentRepoRoot ? path.dirname(currentRepoRoot) : path.dirname(cwd);
+  let cur = scanStart;
+  for (let i = 0; i < 8; i += 1) {
+    pushSearchRoot(cur);
+    const parent = path.dirname(cur);
+    if (parent === cur) break;
+    cur = parent;
+  }
+
+  let fallbackCandidates = [];
+  let fallbackRoot = null;
+
+  for (const candidateRoot of searchRoots) {
+    const candidates = listGitRepoCandidates(candidateRoot, currentRepoRoot);
+    if (!fallbackCandidates.length && candidates.length) {
+      fallbackCandidates = candidates;
+      fallbackRoot = candidateRoot;
+    }
+
+    const assigned = new Set();
+    const found = [];
+    for (const binding of normalizedBindings) {
+      let best = null;
+      for (const candidate of candidates) {
+        if (assigned.has(candidate.abs)) continue;
+        const match = scoreBindingCandidate(binding, candidate);
+        if (!match.score) continue;
+        if (!best || match.score > best.match.score) {
+          best = { candidate, match };
+        }
+      }
+      if (!best) continue;
+      assigned.add(best.candidate.abs);
+      found.push({
+        name: best.candidate.name,
+        dir: best.candidate.dir,
+        abs: best.candidate.abs,
+        prefix: best.candidate.prefix,
+        role: binding.role,
+        canonical_repo_name: binding.canonical_repo_name,
+        canonical_remote_url: binding.canonical_remote_url,
+        client_repo_name: binding.client_repo_name,
+        client_remote_url: binding.client_remote_url,
+        baseline_branch: binding.baseline_branch || null,
+        matched_by: best.match.matchedBy,
+        remote_fingerprints: best.candidate.remote_fingerprints,
+      });
+    }
+
+    if (found.length) {
+      const foundRoles = new Set(found.map((repo) => repo.role));
+      const missing = normalizedBindings
+        .filter((binding) => !foundRoles.has(binding.role))
+        .map((binding) => binding.client_repo_name || binding.canonical_repo_name || binding.role);
+      return {
+        mode: currentRepoRoot && found.length === 1 && found[0].abs === currentRepoRoot ? "repo" : "workspace",
+        root: candidateRoot,
+        repos: found,
+        missing,
+        bindings: normalizedBindings,
+      };
+    }
+  }
+
+  return {
+    mode: currentRepoRoot ? "repo" : "none",
+    root: fallbackRoot,
+    repos: [],
+    missing: normalizedBindings.map((binding) => binding.client_repo_name || binding.canonical_repo_name || binding.role),
+    bindings: normalizedBindings,
+  };
+}
+
+function fetchBaseBranches(repoPath, preferredBranch) {
+  const preferred = String(preferredBranch || "").trim();
+  if (preferred && runGitOk(repoPath, ["fetch", "origin", preferred, "--prune", "--quiet"])) return true;
   if (runGitOk(repoPath, ["fetch", "origin", "main", "master", "--prune", "--quiet"])) return true;
   return runGitOk(repoPath, ["fetch", "--all", "--prune", "--quiet"]);
 }
 
-function resolveBaseRef(repoPath) {
+function buildExternalBaseRefName(remoteUrl, branch) {
+  const branchSlug = String(branch || "main")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "main";
+  const digest = createHash("sha1")
+    .update(`${String(remoteUrl || "").trim()}::${branchSlug}`)
+    .digest("hex")
+    .slice(0, 12);
+  return `refs/myte/bases/${branchSlug}-${digest}`;
+}
+
+function fetchExternalBaseRef(repoPath, remoteUrl, preferredBranch) {
+  const remote = String(remoteUrl || "").trim();
+  if (!remote) return null;
+
+  const candidateBranches = uniqueNormalizedStrings([preferredBranch, "main", "master"]);
+  for (const branch of candidateBranches) {
+    const refName = buildExternalBaseRefName(remote, branch);
+    if (runGitOk(repoPath, ["fetch", "--quiet", "--no-tags", remote, `${branch}:${refName}`])) {
+      return { ref: refName, branch };
+    }
+  }
+  return null;
+}
+
+function resolveExternalCompareRemoteUrl(repo) {
+  const canonicalRemoteUrl = String(repo?.canonical_remote_url || "").trim();
+  const clientRemoteUrl = String(repo?.client_remote_url || "").trim();
+  if (!canonicalRemoteUrl || !clientRemoteUrl) return null;
+
+  const canonicalFingerprint = normalizeRemoteFingerprint(canonicalRemoteUrl);
+  const clientFingerprint = normalizeRemoteFingerprint(clientRemoteUrl);
+  if (!canonicalFingerprint || !clientFingerprint || canonicalFingerprint === clientFingerprint) return null;
+
+  const candidateFingerprints = new Set(
+    (Array.isArray(repo?.remote_fingerprints) ? repo.remote_fingerprints : [])
+      .map((value) => String(value || "").trim().toLowerCase())
+      .filter(Boolean)
+  );
+  if (!candidateFingerprints.has(clientFingerprint.toLowerCase())) return null;
+  if (candidateFingerprints.has(canonicalFingerprint.toLowerCase())) return null;
+
+  return canonicalRemoteUrl;
+}
+
+function resolveBaseRef(repoPath, preferredBranch) {
+  const preferred = String(preferredBranch || "").trim();
+  if (preferred) {
+    if (runGitOk(repoPath, ["rev-parse", "--verify", `refs/remotes/origin/${preferred}`])) return `origin/${preferred}`;
+    if (runGitOk(repoPath, ["rev-parse", "--verify", `refs/heads/${preferred}`])) return preferred;
+  }
   if (runGitOk(repoPath, ["rev-parse", "--verify", "refs/remotes/origin/main"])) return "origin/main";
   if (runGitOk(repoPath, ["rev-parse", "--verify", "refs/remotes/origin/master"])) return "origin/master";
   if (runGitOk(repoPath, ["rev-parse", "--verify", "refs/heads/main"])) return "main";
@@ -849,13 +1270,24 @@ function resolveBaseRef(repoPath) {
 function collectGitDiffWithDiagnostics({
   projectId,
   repoNames,
+  repoBindings,
   maxChars,
   fetchRemote = true,
 } = {}) {
   const configuredRepos = Array.isArray(repoNames) ? repoNames.map(String).map((s) => s.trim()).filter(Boolean) : [];
+  const configuredBindings = normalizeRepoBindings(repoBindings);
   const diagnostics = {
     project_id: projectId || null,
     requested_repo_names: configuredRepos,
+    requested_repo_bindings: configuredBindings.map((binding) => ({
+      role: binding.role,
+      canonical_repo_name: binding.canonical_repo_name,
+      canonical_remote_url: binding.canonical_remote_url,
+      client_repo_name: binding.client_repo_name,
+      client_remote_url: binding.client_remote_url,
+      local_repo_aliases: binding.local_repo_aliases,
+      baseline_branch: binding.baseline_branch,
+    })),
     fetch_remote: Boolean(fetchRemote),
     mode: "none",
     search_root: null,
@@ -870,7 +1302,9 @@ function collectGitDiffWithDiagnostics({
   };
 
   try {
-    const resolved = resolveConfiguredRepos(configuredRepos);
+    const resolved = configuredBindings.length
+      ? resolveConfiguredRepoBindings(configuredBindings)
+      : resolveConfiguredRepos(configuredRepos);
     diagnostics.mode = resolved.mode || "none";
     diagnostics.search_root = resolved.root || null;
     diagnostics.found_repos = (resolved.repos || []).map((r) => r.name);
@@ -888,7 +1322,15 @@ function collectGitDiffWithDiagnostics({
     const sections = [];
     if (projectId) sections.push(`# Project: ${projectId}`);
     sections.push(`# Mode: ${resolved.mode}`);
-    sections.push(`# Configured repos: ${configuredRepos.join(", ") || ""}`);
+    if (configuredBindings.length) {
+      sections.push(
+        `# Configured repo bindings: ${configuredBindings
+          .map((binding) => `${binding.role}=${binding.client_repo_name || binding.canonical_repo_name || binding.role}`)
+          .join(", ")}`
+      );
+    } else {
+      sections.push(`# Configured repos: ${configuredRepos.join(", ") || ""}`);
+    }
     if (resolved.missing && resolved.missing.length) {
       sections.push(`# Missing locally (skipped): ${resolved.missing.join(", ")}`);
     }
@@ -900,8 +1342,12 @@ function collectGitDiffWithDiagnostics({
         dir: repo.dir || ".",
         root: repo.abs,
         status: "ok",
+        role: repo.role || null,
         head_branch: null,
         base_ref: null,
+        base_ref_label: null,
+        compare_mode: "local_origin",
+        compare_remote_url: null,
         has_changes: false,
         changed_blocks: {
           base_vs_head: false,
@@ -914,22 +1360,55 @@ function collectGitDiffWithDiagnostics({
       };
 
       const { name, dir, abs, prefix } = repo;
-      const fetchDiag = { attempted: false, ok: false, message: "" };
+      const externalCompareRemoteUrl = resolveExternalCompareRemoteUrl(repo);
+      const fetchDiag = {
+        attempted: false,
+        ok: false,
+        message: "",
+        compare_mode: externalCompareRemoteUrl ? "external_remote" : "local_origin",
+        compare_remote_url: externalCompareRemoteUrl || null,
+      };
+      let baseRef = null;
+      let baseRefLabel = null;
       if (fetchRemote) {
         fetchDiag.attempted = true;
-        fetchDiag.ok = fetchBaseBranches(abs);
-        if (!fetchDiag.ok) {
-          fetchDiag.message = "failed to refresh origin main/master";
-          repoSummary.errors.push(fetchDiag.message);
-          diagnostics.warnings.push(`Repo "${name}": ${fetchDiag.message}`);
+        if (externalCompareRemoteUrl) {
+          const externalBase = fetchExternalBaseRef(abs, externalCompareRemoteUrl, repo.baseline_branch);
+          fetchDiag.ok = Boolean(externalBase?.ref);
+          if (externalBase?.ref) {
+            baseRef = externalBase.ref;
+            baseRefLabel = `${externalBase.branch}@canonical`;
+          } else {
+            fetchDiag.message = `failed to refresh canonical compare branch from ${externalCompareRemoteUrl}`;
+            repoSummary.errors.push(fetchDiag.message);
+            diagnostics.warnings.push(`Repo "${name}": ${fetchDiag.message}`);
+          }
+        } else {
+          fetchDiag.ok = fetchBaseBranches(abs, repo.baseline_branch);
+          if (!fetchDiag.ok) {
+            fetchDiag.message = "failed to refresh origin main/master";
+            repoSummary.errors.push(fetchDiag.message);
+            diagnostics.warnings.push(`Repo "${name}": ${fetchDiag.message}`);
+          }
         }
       }
 
       const headBranch = runGitTry(abs, ["rev-parse", "--abbrev-ref", "HEAD"]) || "HEAD";
-      const baseRef = resolveBaseRef(abs);
+      if (!baseRef && !externalCompareRemoteUrl) {
+        baseRef = resolveBaseRef(abs, repo.baseline_branch);
+      }
       repoSummary.head_branch = headBranch;
       repoSummary.base_ref = baseRef || "base-unresolved";
+      repoSummary.base_ref_label = baseRefLabel || repoSummary.base_ref;
       repoSummary.fetch = fetchDiag;
+      repoSummary.compare_mode = fetchDiag.compare_mode;
+      repoSummary.compare_remote_url = fetchDiag.compare_remote_url;
+      if (repo.matched_by) repoSummary.matched_by = repo.matched_by;
+      if (repo.baseline_branch) repoSummary.baseline_branch = repo.baseline_branch;
+      if (repo.canonical_repo_name) repoSummary.canonical_repo_name = repo.canonical_repo_name;
+      if (repo.canonical_remote_url) repoSummary.canonical_remote_url = repo.canonical_remote_url;
+      if (repo.client_repo_name) repoSummary.client_repo_name = repo.client_repo_name;
+      if (repo.client_remote_url) repoSummary.client_remote_url = repo.client_remote_url;
 
       let baseDiff = "";
       if (baseRef) {
@@ -999,8 +1478,16 @@ function collectGitDiffWithDiagnostics({
         repoSummary.status = "partial";
       }
 
-      let section = `### ${name} (${dir || "."})\n\n`;
-      section += `# ?? Base vs HEAD (${repoSummary.base_ref}...HEAD | head=${headBranch})\n`;
+      const headingParts = [`${name} (${dir || "."})`];
+      if (repo.role) headingParts.push(`role=${repo.role}`);
+      let section = `### ${headingParts.join(" | ")}\n\n`;
+      section += `# ?? Base vs HEAD (${repoSummary.base_ref_label}...HEAD | head=${headBranch})\n`;
+      if (repoSummary.matched_by?.length) {
+        section += `# ?? Matched by ${repoSummary.matched_by.join(", ")}\n`;
+      }
+      if (repoSummary.compare_remote_url) {
+        section += `# ?? Compare remote ${repoSummary.compare_remote_url}\n`;
+      }
       if (baseDiff) section += `${baseDiff}\n\n`;
       if (staged) section += `# ?? Staged changes\n${staged}\n\n`;
       if (unstaged) section += `# ?? Unstaged changes\n${unstaged}\n\n`;
@@ -1144,6 +1631,83 @@ async function fetchFeedbackSyncSnapshot({ apiBase, key, timeoutMs, filters = {}
   return body.data || {};
 }
 
+async function fetchFeedbackReview({ apiBase, key, timeoutMs, feedbackId }) {
+  const fetchFn = await getFetch();
+  const url = `${apiBase}/project-assistant/feedback/${encodeURIComponent(String(feedbackId || ""))}`;
+  const { resp, body } = await fetchJsonWithTimeout(
+    fetchFn,
+    url,
+    {
+      method: "GET",
+      headers: { Authorization: `Bearer ${key}` },
+    },
+    timeoutMs
+  );
+
+  if (!resp.ok || body.status !== "success") {
+    const msg = body?.message || `Feedback review request failed (${resp.status})`;
+    const err = new Error(msg);
+    err.status = resp.status;
+    throw err;
+  }
+  return body.data || {};
+}
+
+async function fetchFeedbackHistory({ apiBase, key, timeoutMs, feedbackId }) {
+  const fetchFn = await getFetch();
+  const url = `${apiBase}/project-assistant/feedback/${encodeURIComponent(String(feedbackId || ""))}/refinement/history`;
+  const { resp, body } = await fetchJsonWithTimeout(
+    fetchFn,
+    url,
+    {
+      method: "GET",
+      headers: { Authorization: `Bearer ${key}` },
+    },
+    timeoutMs
+  );
+
+  if (!resp.ok || body.status !== "success") {
+    const msg = body?.message || `Feedback history request failed (${resp.status})`;
+    const err = new Error(msg);
+    err.status = resp.status;
+    throw err;
+  }
+  return body.data || {};
+}
+
+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() } : {}),
+  };
+  if (idempotencyKey) {
+    headers["X-Idempotency-Key"] = String(idempotencyKey).trim();
+  }
+  const { resp, body } = await fetchJsonWithTimeout(
+    fetchFn,
+    url,
+    {
+      method: "POST",
+      headers,
+      body: JSON.stringify(payload || {}),
+    },
+    timeoutMs
+  );
+
+  if (!resp.ok || body.status !== "success") {
+    const msg = body?.message || `Feedback refinement ${action} failed (${resp.status})`;
+    const err = new Error(msg);
+    err.status = resp.status;
+    err.data = body?.data;
+    throw err;
+  }
+  return body.data || {};
+}
+
 async function fetchSuggestionsSyncSnapshot({ apiBase, key, timeoutMs, actorScope = "" }) {
   const fetchFn = await getFetch();
   const url = new URL(`${apiBase}/project-assistant/suggestions`);
@@ -1469,7 +2033,7 @@ async function runRunQaqc(args) {
 
       let resolved;
       try {
-        resolved = resolveBootstrapWorkspace(snapshot.repo_names || []);
+        resolved = resolvePortableWorkspace(snapshot.repo_names || []);
       } catch (err) {
         console.error(err?.message || err);
         process.exit(1);
@@ -2063,6 +2627,20 @@ function resolveBootstrapWorkspace(repoNames) {
   return resolved;
 }
 
+function resolvePortableWorkspace(repoNames) {
+  const configured = Array.isArray(repoNames) ? repoNames.map(String).map((s) => s.trim()).filter(Boolean) : [];
+  const resolved = resolveConfiguredRepos(configured);
+  if (resolved.root) {
+    return resolved;
+  }
+  return {
+    mode: "cwd",
+    root: process.cwd(),
+    repos: [],
+    missing: configured,
+  };
+}
+
 function resolveCommandCenterRoots(wrapperRoot, outputDir) {
   const targetRoot = outputDir
     ? path.resolve(process.cwd(), String(outputDir))
@@ -2301,6 +2879,150 @@ function writeFeedbackSnapshot({ snapshot, wrapperRoot, outputDir }) {
   };
 }
 
+function resolveFeedbackReviewPaths(args, { requireFeedback = false } = {}) {
+  const outputDir = args["output-dir"] || args.outputDir || args.output_dir;
+  const targetRoot = outputDir
+    ? path.resolve(process.cwd(), String(outputDir))
+    : findExistingCommandCenterRoot(process.cwd());
+  if (!targetRoot) {
+    if (requireFeedback) {
+      console.error("feedback.yml was not found. Run `myte feedback-sync` first or pass --output-dir.");
+      process.exit(1);
+    }
+    return null;
+  }
+  const dataRoot = path.join(targetRoot, "data");
+  const feedbackPath = path.join(dataRoot, "feedback.yml");
+  if (requireFeedback && !fs.existsSync(feedbackPath)) {
+    console.error("feedback.yml was not found. Run `myte feedback-sync` first or pass --output-dir.");
+    process.exit(1);
+  }
+  return {
+    targetRoot,
+    dataRoot,
+    feedbackPath,
+    reviewsRoot: path.join(targetRoot, "reviews", "feedback"),
+    wrapperRoot: path.dirname(targetRoot),
+  };
+}
+
+function readFeedbackManifest(args) {
+  const paths = resolveFeedbackReviewPaths(args, { requireFeedback: true });
+  const manifest = readYamlFile(paths.feedbackPath) || {};
+  if (!isPlainObject(manifest)) {
+    console.error(`Invalid feedback manifest: ${paths.feedbackPath}`);
+    process.exit(1);
+  }
+  return { paths, manifest };
+}
+
+function findFeedbackManifestItem(manifest, feedbackId) {
+  const wanted = String(feedbackId || "").trim();
+  if (!wanted) return null;
+  const items = Array.isArray(manifest?.items) ? manifest.items : [];
+  return items.find((item) => String(item?.feedback_id || item?.id || "").trim() === wanted) || null;
+}
+
+function readFeedbackRefinementArtifact(args) {
+  const filePath = firstNonEmptyString(args.file);
+  if (!filePath) {
+    console.error("Missing --file for feedback validate/apply.");
+    process.exit(1);
+  }
+  const absPath = resolveInputFile(filePath, "Feedback refinement");
+  const text = fs.readFileSync(absPath, "utf8");
+  let payload;
+  if (absPath.toLowerCase().endsWith(".json")) {
+    payload = JSON.parse(text);
+  } else {
+    payload = parseYaml(text);
+  }
+  if (!isPlainObject(payload)) {
+    console.error(`Feedback refinement file must contain an object: ${absPath}`);
+    process.exit(1);
+  }
+  return { absPath, payload };
+}
+
+function parseFeedbackTags(args) {
+  const values = parseCsvValues(args.tags, args.tag);
+  return values.length ? values : undefined;
+}
+
+function feedbackChange(from, to) {
+  return { from: from === undefined ? null : from, to: to === undefined ? null : to };
+}
+
+function buildFeedbackRefinementArtifact({ manifest, item, feedbackId, action, changes, reason, args }) {
+  const clientSessionId = firstNonEmptyString(args["client-session-id"], args.clientSessionId, args.client_session_id);
+  const artifact = {
+    schema_version: 1,
+    kind: "feedback_refinement",
+    project_id: firstNonEmptyString(manifest?.project?.id, item?.project_id),
+    feedback_id: feedbackId,
+    title_snapshot: firstNonEmptyString(item?.title),
+    base_snapshot_hash: firstNonEmptyString(item?.snapshot_hash),
+    base_updated_at: firstNonEmptyString(item?.updated_at),
+    review_action: action,
+    reason: reason || null,
+    changes,
+    force: Boolean(args.force) || undefined,
+    client_session_id: clientSessionId || undefined,
+    created_at: new Date().toISOString(),
+  };
+  return Object.fromEntries(Object.entries(artifact).filter(([, value]) => value !== undefined));
+}
+
+function writeFeedbackRefinementArtifact({ paths, artifact, action }) {
+  const feedbackId = sanitizeFileSegment(artifact.feedback_id, "feedback");
+  const actionSegment = sanitizeFileSegment(action || artifact.review_action || "refine", "refine");
+  const filePath = path.join(paths.reviewsRoot, `${feedbackId}-${actionSegment}.yml`);
+  writeYamlFile(filePath, artifact);
+  return filePath;
+}
+
+function printFeedbackRefinementDraft({ artifact, filePath, args }) {
+  const output = {
+    feedback_id: artifact.feedback_id,
+    review_action: artifact.review_action,
+    artifact_path: filePath || null,
+    base_snapshot_hash: artifact.base_snapshot_hash || null,
+    changes: artifact.changes || {},
+    reason: artifact.reason || null,
+  };
+  if (args.json) {
+    console.log(JSON.stringify(output, null, 2));
+    return;
+  }
+  console.log(`Feedback: ${output.feedback_id}`);
+  console.log(`Action: ${output.review_action}`);
+  if (filePath) console.log(`Artifact: ${filePath}`);
+  console.log(`Base Snapshot: ${output.base_snapshot_hash || "n/a"}`);
+  console.log("Changes:");
+  for (const [field, change] of Object.entries(output.changes || {})) {
+    const fromValue = change && typeof change === "object" && "from" in change ? change.from : null;
+    const toValue = change && typeof change === "object" && "to" in change ? change.to : change;
+    console.log(`- ${field}: ${JSON.stringify(fromValue)} -> ${JSON.stringify(toValue)}`);
+  }
+  if (output.reason) console.log(`Reason: ${output.reason}`);
+}
+
+function summarizeFeedbackRefinementResult(data) {
+  return {
+    valid: Boolean(data?.valid),
+    feedback_id: data?.feedback_id || data?.feedback?.feedback_id || null,
+    project_id: data?.project_id || null,
+    previous_snapshot_hash: data?.previous_snapshot_hash || data?.base_snapshot_hash || null,
+    current_snapshot_hash: data?.current_snapshot_hash || null,
+    new_snapshot_hash: data?.new_snapshot_hash || data?.feedback?.snapshot_hash || null,
+    diff_count: Array.isArray(data?.diffs) ? data.diffs.length : 0,
+    diffs: data?.diffs || [],
+    warnings: data?.warnings || [],
+    errors: data?.errors || [],
+    history_id: data?.history?.history_id || null,
+  };
+}
+
 function missionOpsThreads(payload) {
   if (Array.isArray(payload?.threads)) return payload.threads;
   if (Array.isArray(payload?.suggestions)) return payload.suggestions;
@@ -2545,7 +3267,7 @@ async function resolveSuggestionsOutputContext({ args, key, apiBase, timeoutMs,
   const repoNames = Array.isArray(snapshot?.repo_names) && snapshot.repo_names.length
     ? snapshot.repo_names
     : (await fetchProjectConfig({ apiBase, key, timeoutMs })).repo_names || [];
-  const resolved = resolveBootstrapWorkspace(repoNames);
+  const resolved = resolvePortableWorkspace(repoNames);
   return {
     wrapperRoot: resolved.root,
     targetRoot: path.join(resolved.root, "MyteCommandCenter"),
@@ -3155,11 +3877,15 @@ async function runConfig(args) {
   }
 
   const repoNames = Array.isArray(cfg.repo_names) ? cfg.repo_names : [];
-  const resolved = resolveConfiguredRepos(repoNames);
+  const repoBindings = Array.isArray(cfg.repo_bindings) ? cfg.repo_bindings : [];
+  const resolved = repoBindings.length
+    ? resolveConfiguredRepoBindings(repoBindings)
+    : resolveConfiguredRepos(repoNames);
   const payload = {
     api_base: apiBase,
     project_id: cfg.project_id,
     repo_names: repoNames,
+    repo_bindings: repoBindings,
     local: {
       mode: resolved.mode,
       root: resolved.root,
@@ -3174,6 +3900,13 @@ async function runConfig(args) {
     console.log(`Project: ${payload.project_id || "(unknown)"}`);
     console.log(`API base: ${payload.api_base}`);
     console.log(`Configured repos: ${repoNames.join(", ") || "(none)"}`);
+    if (repoBindings.length) {
+      console.log(
+        `Repo bindings: ${repoBindings
+          .map((binding) => `${binding.role}=${binding.client_repo_name || binding.canonical_repo_name || binding.role}`)
+          .join(", ")}`
+      );
+    }
     console.log(`Local mode: ${payload.local.mode}`);
     if (payload.local.found.length) console.log(`Found locally: ${payload.local.found.join(", ")}`);
     if (payload.local.missing.length) console.log(`Missing locally: ${payload.local.missing.join(", ")}`);
@@ -3209,7 +3942,7 @@ async function runBootstrap(args) {
 
   let resolved;
   try {
-    resolved = resolveBootstrapWorkspace(snapshot.repo_names || []);
+    resolved = resolvePortableWorkspace(snapshot.repo_names || []);
   } catch (err) {
     console.error(err?.message || err);
     process.exit(1);
@@ -3303,7 +4036,7 @@ async function runSyncQaqc(args) {
 
   let resolved;
   try {
-    resolved = resolveBootstrapWorkspace(snapshot.repo_names || []);
+    resolved = resolvePortableWorkspace(snapshot.repo_names || []);
   } catch (err) {
     console.error(err?.message || err);
     process.exit(1);
@@ -3397,7 +4130,7 @@ async function runFeedbackSync(args) {
 
   let resolved;
   try {
-    resolved = resolveBootstrapWorkspace(snapshot.repo_names || []);
+    resolved = resolvePortableWorkspace(snapshot.repo_names || []);
   } catch (err) {
     console.error(err?.message || err);
     process.exit(1);
@@ -3463,6 +4196,251 @@ async function runFeedbackSync(args) {
   console.log(`Snapshot: ${summary.snapshot_hash || "n/a"}`);
 }
 
+function resolveFeedbackIdArg(args) {
+  return firstNonEmptyString(args["feedback-id"], args.feedbackId, args.feedback_id, args._?.[1]);
+}
+
+function requireFeedbackDraftContext(args) {
+  const feedbackId = resolveFeedbackIdArg(args);
+  if (!feedbackId) {
+    console.error("Missing --feedback-id.");
+    process.exit(1);
+  }
+  const { paths, manifest } = readFeedbackManifest(args);
+  const item = findFeedbackManifestItem(manifest, feedbackId);
+  if (!item) {
+    console.error(`Feedback item not found in feedback.yml: ${feedbackId}. Run \`myte feedback-sync\` first.`);
+    process.exit(1);
+  }
+  return { paths, manifest, item, feedbackId };
+}
+
+async function buildFeedbackDraftForCommand(args, subcommand) {
+  const { paths, manifest, item, feedbackId } = requireFeedbackDraftContext(args);
+  const action = subcommand || "refine";
+  const reason = firstNonEmptyString(args.reason);
+  const changes = {};
+
+  if (action === "status") {
+    const targetStatus = firstNonEmptyString(args.status, args._?.[2]);
+    if (!targetStatus) {
+      console.error("Missing --status for feedback status.");
+      process.exit(1);
+    }
+    changes.feedback_state = feedbackChange(firstNonEmptyString(item.feedback_state, item.status), targetStatus);
+  } else if (action === "archive") {
+    changes.feedback_state = feedbackChange(firstNonEmptyString(item.feedback_state, item.status), "archived");
+  } else if (action === "assign") {
+    const assignee = firstNonEmptyString(args["assigned-user-id"], args.assignedUserId, args.assigned_user_id, args["user-id"], args.userId, args.user_id, args._?.[2]);
+    if (!assignee) {
+      console.error("Missing --user-id or --assigned-user-id for feedback assign.");
+      process.exit(1);
+    }
+    changes.assigned_user_id = feedbackChange(firstNonEmptyString(item.assigned_user_id), assignee);
+  } else if (action === "edit" || action === "refine") {
+    const title = firstNonEmptyString(args.title);
+    if (title) changes.title = feedbackChange(firstNonEmptyString(item.title), title);
+
+    let feedbackText = firstNonEmptyString(args["feedback-text"], args.feedbackText, args.feedback_text);
+    const bodyFile = firstNonEmptyString(args["body-file"], args.bodyFile, args.body_file);
+    if (!feedbackText && bodyFile) {
+      const bodyPath = resolveInputFile(bodyFile, "Feedback body");
+      feedbackText = fs.readFileSync(bodyPath, "utf8").trim();
+    }
+    if (feedbackText) changes.feedback_text = feedbackChange(firstNonEmptyString(item.feedback_text), feedbackText);
+
+    const priority = firstNonEmptyString(args.priority);
+    if (priority) changes.priority = feedbackChange(firstNonEmptyString(item.priority), priority);
+
+    const dueDate = firstNonEmptyString(args["due-date"], args.dueDate, args.due_date);
+    if (dueDate) changes.due_date = feedbackChange(firstNonEmptyString(item.due_date, item.due_date_text), dueDate);
+
+    const tags = parseFeedbackTags(args);
+    if (tags) changes.tags = feedbackChange(Array.isArray(item.tags) ? item.tags : [], tags);
+
+    const reviewNote = firstNonEmptyString(args["review-note"], args.reviewNote, args.review_note);
+    if (reviewNote) changes.review_note = feedbackChange(null, reviewNote);
+  } else {
+    console.error("Unknown feedback command. Use status, edit, assign, archive, get, history, validate, or apply.");
+    process.exit(1);
+  }
+
+  if (!Object.keys(changes).length) {
+    console.error("No feedback changes were provided.");
+    process.exit(1);
+  }
+
+  const artifact = buildFeedbackRefinementArtifact({
+    manifest,
+    item,
+    feedbackId,
+    action,
+    changes,
+    reason,
+    args,
+  });
+
+  if (args["print-context"] || args.printContext || args["dry-run"] || args.dryRun) {
+    if (args.json) {
+      console.log(JSON.stringify(artifact, null, 2));
+    } else {
+      console.log(stringifyYaml(artifact));
+    }
+    return;
+  }
+
+  const filePath = writeFeedbackRefinementArtifact({ paths, artifact, action });
+  printFeedbackRefinementDraft({ artifact, filePath, args });
+}
+
+async function runFeedbackValidateOrApply(args, mode) {
+  const key = getProjectApiKey();
+  if (!key) {
+    console.error("Missing MYTE_API_KEY (project key) in environment/.env");
+    process.exit(1);
+  }
+  const { absPath, payload } = readFeedbackRefinementArtifact(args);
+  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.");
+    process.exit(1);
+  }
+  if (args.force) payload.force = true;
+
+  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 = mode === "apply"
+    ? resolveProjectMutationIdempotencyKey({
+        args,
+        operation: `feedback_refinement_apply:${feedbackId}`,
+        payload,
+      })
+    : null;
+
+  let data;
+  try {
+    data = await postFeedbackRefinement({
+      apiBase,
+      key,
+      timeoutMs,
+      feedbackId,
+      mode,
+      payload,
+      idempotencyKey,
+      clientSessionId,
+    });
+  } catch (err) {
+    if (args.json) {
+      console.log(JSON.stringify({
+        ok: false,
+        status: err?.status || null,
+        message: err?.message || String(err),
+        data: err?.data || null,
+        artifact_path: absPath,
+      }, null, 2));
+    } else {
+      console.error(`Feedback ${mode} failed:`, err?.message || err);
+      if (err?.data) console.error(JSON.stringify(err.data, null, 2));
+    }
+    process.exit(1);
+  }
+
+  const summary = {
+    ok: true,
+    mode,
+    artifact_path: absPath,
+    ...summarizeFeedbackRefinementResult(data),
+  };
+  if (args.json) {
+    console.log(JSON.stringify(summary, null, 2));
+    return;
+  }
+  console.log(`Feedback ${mode}: ${summary.valid ? "valid" : "invalid"}`);
+  console.log(`Feedback: ${summary.feedback_id || feedbackId}`);
+  if (summary.history_id) console.log(`History: ${summary.history_id}`);
+  if (summary.new_snapshot_hash) console.log(`New Snapshot: ${summary.new_snapshot_hash}`);
+  if (summary.current_snapshot_hash) console.log(`Current Snapshot: ${summary.current_snapshot_hash}`);
+  console.log(`Diffs: ${summary.diff_count}`);
+  for (const diff of summary.diffs || []) {
+    console.log(`- ${diff.field}: ${JSON.stringify(diff.from)} -> ${JSON.stringify(diff.to)}`);
+  }
+  if (mode === "apply") {
+    console.log("Local feedback.yml is not modified by apply. Run `myte feedback-sync` to refresh it.");
+  }
+}
+
+async function runFeedbackGetOrHistory(args, mode) {
+  const key = getProjectApiKey();
+  if (!key) {
+    console.error("Missing MYTE_API_KEY (project key) in environment/.env");
+    process.exit(1);
+  }
+  const feedbackId = resolveFeedbackIdArg(args);
+  if (!feedbackId) {
+    console.error("Missing --feedback-id.");
+    process.exit(1);
+  }
+  const timeoutMs = resolveTimeoutMs(args);
+  const apiBase = resolveApiBase(args);
+
+  let data;
+  try {
+    data = mode === "history"
+      ? await fetchFeedbackHistory({ apiBase, key, timeoutMs, feedbackId })
+      : await fetchFeedbackReview({ apiBase, key, timeoutMs, feedbackId });
+  } catch (err) {
+    console.error(`Feedback ${mode} failed:`, err?.message || err);
+    process.exit(1);
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+  if (mode === "history") {
+    console.log(`Feedback: ${data.feedback_id || feedbackId}`);
+    console.log(`Events: ${data.count || 0}`);
+    for (const event of data.events || []) {
+      console.log(`- ${event.created_at || "unknown"} ${event.action || "refine"} ${event.history_id || ""}`);
+    }
+    return;
+  }
+  const feedback = data.feedback || {};
+  console.log(`Feedback: ${feedback.feedback_id || feedbackId}`);
+  console.log(`Title: ${feedback.title || "(untitled)"}`);
+  console.log(`Status: ${feedback.feedback_state || feedback.status || "unknown"} (${feedback.status || "legacy unknown"})`);
+  console.log(`Priority: ${feedback.priority || "n/a"}`);
+  console.log(`Snapshot: ${feedback.snapshot_hash || "n/a"}`);
+}
+
+async function runFeedback(args) {
+  const subcommand = firstNonEmptyString(args._?.[0]) || "help";
+  if (subcommand === "help") {
+    printHelp();
+    return;
+  }
+  if (["status", "edit", "assign", "archive", "refine"].includes(subcommand)) {
+    await buildFeedbackDraftForCommand(args, subcommand);
+    return;
+  }
+  if (subcommand === "validate" || subcommand === "apply") {
+    await runFeedbackValidateOrApply(args, subcommand);
+    return;
+  }
+  if (subcommand === "get" || subcommand === "history") {
+    await runFeedbackGetOrHistory(args, subcommand);
+    return;
+  }
+  console.error("Unknown feedback command. Use status, edit, assign, archive, get, history, validate, or apply.");
+  process.exit(1);
+}
+
 async function runSuggestionsSync(args) {
   const key = getProjectApiKey();
   if (!key) {
@@ -4037,30 +5015,41 @@ async function runQuery(args) {
     try {
       cfg = await fetchProjectConfig({ apiBase, key, timeoutMs });
     } catch (err) {
-      console.warn("Warning: project config unavailable for --with-diff. Continuing without diff context.");
-      console.warn(`Detail: ${err?.message || err}`);
-      cfg = null;
+      console.error("Failed to fetch project config for --with-diff:", err?.message || err);
+      process.exit(1);
     }
 
-    if (cfg) {
-      const repoNames = Array.isArray(cfg.repo_names) ? cfg.repo_names : [];
-      const diffResult = collectGitDiffWithDiagnostics({
-        projectId: cfg.project_id,
-        repoNames,
-        maxChars: diffLimit,
-        fetchRemote,
-      });
-      diffText = diffResult.text;
-      diffDiagnostics = diffResult.diagnostics;
-      if (diffDiagnostics?.errors?.length) {
-        for (const warning of diffDiagnostics.errors) console.warn(`Warning: ${warning}`);
-      }
-    } else {
-      diffText = "";
-      diffDiagnostics = null;
+    const repoNames = Array.isArray(cfg.repo_names) ? cfg.repo_names : [];
+    const repoBindings = Array.isArray(cfg.repo_bindings) ? cfg.repo_bindings : [];
+    if (!repoBindings.length && !repoNames.length) {
+      console.error("No project repositories are configured for --with-diff.");
+      console.error("Ask the project owner or builder to configure the project repos in Myte first.");
+      process.exit(1);
     }
-    if (!diffText) {
-      console.error("Warning: no diff context collected. Continuing without --with-diff context.");
+
+    const diffResult = collectGitDiffWithDiagnostics({
+      projectId: cfg.project_id,
+      repoNames,
+      repoBindings,
+      maxChars: diffLimit,
+      fetchRemote,
+    });
+    diffText = diffResult.text;
+    diffDiagnostics = diffResult.diagnostics;
+    if (diffDiagnostics?.errors?.length) {
+      for (const warning of diffDiagnostics.errors) console.warn(`Warning: ${warning}`);
+    }
+    if (!Array.isArray(diffDiagnostics?.found_repos) || !diffDiagnostics.found_repos.length) {
+      console.error("No configured project repos were found locally for --with-diff.");
+      const expectedBindings = Array.isArray(diffDiagnostics?.requested_repo_bindings)
+        ? diffDiagnostics.requested_repo_bindings
+            .map((binding) => binding.client_repo_name || binding.canonical_repo_name || binding.role)
+            .filter(Boolean)
+        : [];
+      const expected = expectedBindings.length ? expectedBindings : repoNames;
+      console.error(`Expected repo mapping or folder match for: ${expected.join(", ")}`);
+      console.error("Run `myte config --json` to inspect the configured repos and local resolution.");
+      process.exit(1);
     }
   }
 
@@ -4193,6 +5182,11 @@ async function main() {
     return;
   }
 
+  if (command === "feedback") {
+    await runFeedback(args);
+    return;
+  }
+
   if (command === "suggestions") {
     await runSuggestions(args);
     return;