@mytegroupinc/myte-core 0.0.47 → 0.0.50

package/scripts/feedback-live-full-harness.js

@@ -2,11 +2,52 @@
 "use strict";
 
 const fs = require("node:fs");
-const os = require("node:os");
-const path = require("node:path");
-const { spawnSync } = require("node:child_process");
+const os = require("node:os");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+const {
+  createCertificationManifest,
+  recordCertificationArtifact,
+  validateCertificationManifest,
+} = require("../lib/certification-manifest");
+const { readYamlFile } = require("../cli");
 
-const CLI_PATH = path.resolve(__dirname, "..", "cli.js");
+const CLI_PATH = path.resolve(__dirname, "..", "cli.js");
+const LIVE_SCENARIO_MATRIX = [
+  { id: "doctor", kind: "transport", mutation: "none", required: true },
+  { id: "config", kind: "scope", mutation: "none", required: true },
+  { id: "create-independent-prds", kind: "write", mutation: "test_feedback", required: true },
+  { id: "create-three-document-prd", kind: "write", mutation: "test_feedback", required: true },
+  { id: "feedback-sync", kind: "read/local-sync", mutation: "local_temp_only", required: true },
+  { id: "feedback-get-history", kind: "read", mutation: "none", required: true },
+  { id: "feedback-comment", kind: "write", mutation: "test_comment", required: true },
+  { id: "feedback-comment-sync-roundtrip", kind: "read/local-sync", mutation: "local_temp_only", required: true },
+  {
+    id: "feedback-comment-attachment-sync",
+    kind: "web-write/read/local-sync",
+    mutation: "test_comment_attachment",
+    required: "when --require-comment-attachment-sync is set",
+  },
+  { id: "feedback-stale-edit-guard", kind: "conflict-safety", mutation: "test_feedback", required: true },
+  { id: "feedback-forced-stale-override", kind: "owner-conflict-override", mutation: "test_feedback", required: true },
+  { id: "feedback-move-undo", kind: "governed-write", mutation: "test_feedback", required: true },
+  { id: "feedback-validate-submit", kind: "review", mutation: "test_review", required: true },
+  { id: "feedback-review-list-detail", kind: "read", mutation: "none", required: true },
+  { id: "feedback-request-changes-revise", kind: "review", mutation: "test_review", required: true },
+  { id: "feedback-reject-cancel", kind: "review", mutation: "test_review", required: true },
+  { id: "feedback-batch-review", kind: "governed-write", mutation: "test_review", required: true },
+  { id: "feedback-document-refinement", kind: "review", mutation: "test_feedback", required: true },
+  { id: "feedback-prd-versions-diff", kind: "read", mutation: "none", required: true },
+  { id: "feedback-batch-move-archive", kind: "governed-write", mutation: "test_feedback", required: true },
+  { id: "project-key-unarchive-denial", kind: "negative-permission", mutation: "none", required: true },
+  {
+    id: "owner-delegate-collaborator-matrix",
+    kind: "role-permission",
+    mutation: "test_feedback",
+    required: "when --require-role-matrix is set",
+  },
+  { id: "exact-id-cleanup", kind: "cleanup", mutation: "archive_test_feedback", required: true },
+];
 
 function parseArgs(argv) {
   const args = { _: [] };
@@ -28,19 +69,32 @@ function parseArgs(argv) {
   return args;
 }
 
-function requireConfirm(args) {
-  if (!args["confirm-live"]) {
-    throw new Error("Refusing live feedback mutations. Re-run with --confirm-live after backend/web deploy.");
+function requireConfirm(args) {
+  if (!args["confirm-live"]) {
+    throw new Error("Refusing live feedback mutations. Re-run with --confirm-live after backend/web deploy.");
   }
-  if (!process.env.MYTE_API_KEY && !process.env.MYTE_PROJECT_API_KEY) {
-    throw new Error("Missing MYTE_API_KEY or MYTE_PROJECT_API_KEY.");
-  }
-}
-
-function runCli(cliArgs, cwd, { allowFailure = false } = {}) {
-  const result = spawnSync(process.execPath, [CLI_PATH, ...cliArgs], {
-    cwd,
-    env: process.env,
+  if (
+    !process.env.MYTE_OWNER_API_KEY
+    && !process.env.MYTE_API_KEY
+    && !process.env.MYTE_PROJECT_API_KEY
+  ) {
+    throw new Error("Missing MYTE_OWNER_API_KEY, MYTE_API_KEY, or MYTE_PROJECT_API_KEY.");
+  }
+}
+
+function runCli(cliArgs, cwd, { allowFailure = false, apiKey } = {}) {
+  const env = { ...process.env };
+  delete env.MYTE_OWNER_API_KEY;
+  delete env.MYTE_DELEGATE_API_KEY;
+  delete env.MYTE_COLLABORATOR_API_KEY;
+  delete env.MYTE_WEB_ACCESS_TOKEN;
+  if (apiKey) {
+    env.MYTE_API_KEY = apiKey;
+    env.MYTE_PROJECT_API_KEY = apiKey;
+  }
+  const result = spawnSync(process.execPath, [CLI_PATH, ...cliArgs], {
+    cwd,
+    env,
     encoding: "utf8",
     stdio: ["ignore", "pipe", "pipe"],
   });
@@ -59,8 +113,75 @@ function runCli(cliArgs, cwd, { allowFailure = false } = {}) {
       result.stderr || stdout || "(no output)",
     ].join("\n"));
   }
-  return { status: result.status, stdout: parsed, stderr: String(result.stderr || "").trim() };
-}
+  return { status: result.status, stdout: parsed, stderr: String(result.stderr || "").trim() };
+}
+
+function resolveHarnessApiBase(args) {
+  const raw = String(
+    args["base-url"]
+      || process.env.MYTE_API_BASE
+      || "https://api.myte.dev",
+  ).trim().replace(/\/+$/, "");
+  return raw.endsWith("/api") ? raw : `${raw}/api`;
+}
+
+async function createWebFeedbackCommentWithAttachment({
+  apiBase,
+  accessToken,
+  feedbackId,
+  projectId,
+  namespace,
+  timeoutMs,
+}) {
+  const attachmentName = `${namespace}-comment-context.md`;
+  const attachmentContent = [
+    `# ${namespace} Comment Attachment`,
+    "",
+    "This disposable document proves that a web-created Feedback comment attachment",
+    "remains associated with its comment and becomes readable after Project Assistant sync.",
+    "",
+  ].join("\n");
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  let response;
+  let body;
+  try {
+    response = await fetch(`${apiBase}/feedbacks/${feedbackId}/comments`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        project_id: projectId,
+        content: `${namespace} web attachment sync certification comment.`,
+        attachments: [
+          {
+            name: attachmentName,
+            data: `data:text/markdown;base64,${Buffer.from(attachmentContent, "utf8").toString("base64")}`,
+            size: Buffer.byteLength(attachmentContent, "utf8"),
+            type: "text/markdown",
+          },
+        ],
+      }),
+      signal: controller.signal,
+    });
+    body = await response.json();
+  } finally {
+    clearTimeout(timeout);
+  }
+  if (!response.ok || body?.status !== "success" || !body?.data?.comment_id) {
+    throw new Error(
+      `Web Feedback comment attachment fixture failed (${response.status}): ${body?.message || "unknown response"}`,
+    );
+  }
+  return {
+    commentId: String(body.data.comment_id),
+    commentContent: String(body.data.content || ""),
+    attachmentName,
+    attachmentContent,
+  };
+}
 
 function assert(condition, message) {
   if (!condition) {
@@ -68,7 +189,7 @@ function assert(condition, message) {
   }
 }
 
-function writePrd(workspace, title, index) {
+function writePrd(workspace, title, index) {
   const filePath = path.join(workspace, `feedback-live-harness-${index}.md`);
   fs.writeFileSync(
     filePath,
@@ -87,25 +208,117 @@ function writePrd(workspace, title, index) {
     ].join("\n"),
     "utf8",
   );
-  return filePath;
-}
+  return filePath;
+}
+
+function writeCreateApproval(workspace, runId, prdFiles) {
+  const approvalPath = path.join(workspace, `feedback-live-harness-${runId}-approval.md`);
+  fs.writeFileSync(
+    approvalPath,
+    [
+      "# Myte Feedback Certification Approval",
+      "",
+      `run_id: ${runId}`,
+      "command: myte create-prd",
+      `batch_count: ${prdFiles.length}`,
+      "targets:",
+      ...prdFiles.map((filePath) => `- ${path.basename(filePath)}`),
+      "proposed_change: Create disposable, namespaced TEST Feedback records for post-deploy certification.",
+      "reason: Verify the published CLI and deployed Feedback workflow before exact-ID archival.",
+      "",
+    ].join("\n"),
+    "utf8",
+  );
+  return approvalPath;
+}
+
+function writeCommentApproval(workspace, runId, feedbackId) {
+  const filePath = path.join(workspace, `feedback-live-harness-${runId}-comment.md`);
+  fs.writeFileSync(
+    filePath,
+    [
+      `# ${runId} Feedback certification comment`,
+      "",
+      `feedback_id: ${feedbackId}`,
+      `run_id: ${runId}`,
+      "proposed_change: Record a disposable, namespaced certification comment.",
+      "reason: Verify the project-scoped Feedback comment route and idempotency controls.",
+      "",
+    ].join("\n"),
+    "utf8",
+  );
+  return filePath;
+}
+
+function responseRequestId(payload) {
+  return String(
+    payload?.request?.request_id
+      || payload?.request?._id
+      || payload?.request_id
+      || payload?._id
+      || "",
+  ).trim();
+}
+
+function responseEventId(payload) {
+  return String(
+    payload?.event?.event_id
+      || payload?.event?._id
+      || payload?.event_id
+      || "",
+  ).trim();
+}
+
+function responseVersionId(version) {
+  return String(version?.version_id || version?._id || "").trim();
+}
+
+function assertDocumentSetMaterialized(workspace, feedbackId, expectedTitles) {
+  const root = path.join(
+    workspace,
+    "MyteCommandCenter",
+    "PRD",
+    "feedback-sync",
+    feedbackId,
+  );
+  assert(fs.existsSync(root), `Missing synchronized PRD document directory for ${feedbackId}.`);
+  const files = fs.readdirSync(root)
+    .filter((name) => name.toLowerCase().endsWith(".md"))
+    .sort();
+  assert(files.length === expectedTitles.length, `Expected ${expectedTitles.length} synchronized PRD files, got ${files.length}.`);
+  files.forEach((name, index) => {
+    const content = fs.readFileSync(path.join(root, name), "utf8");
+    assert(
+      content.includes(`# ${expectedTitles[index]}`),
+      `Synchronized document ${name} did not preserve its expected title.`,
+    );
+  });
+  return files;
+}
+
+function writeCertificationManifest(manifestPath, manifest) {
+  validateCertificationManifest(manifest);
+  fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+  fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+}
 
-function loadFeedbackManifest(workspace) {
+function loadFeedbackManifest(workspace) {
   const manifestPath = path.join(workspace, "MyteCommandCenter", "data", "feedback.yml");
   if (!fs.existsSync(manifestPath)) {
     return { items: [] };
-  }
-  const text = fs.readFileSync(manifestPath, "utf8");
-  try {
-    const parsed = JSON.parse(text);
-    const items = []
-      .concat(Array.isArray(parsed.items) ? parsed.items : [])
-      .concat(Array.isArray(parsed.queue) ? parsed.queue : []);
-    return { items };
-  } catch (_err) {
-    // Older local files may still be YAML-like. Keep a small fallback parser so
-    // the harness can validate either shape without adding runtime deps.
-  }
+  }
+  try {
+    const parsed = readYamlFile(manifestPath);
+    if (parsed && typeof parsed === "object") {
+      return {
+        ...parsed,
+        items: Array.isArray(parsed.items) ? parsed.items : [],
+      };
+    }
+  } catch (_err) {
+    // Keep a small fallback parser for a partially written legacy snapshot.
+  }
+  const text = fs.readFileSync(manifestPath, "utf8");
   const items = [];
   let current = null;
   for (const line of text.split(/\r?\n/)) {
@@ -127,8 +340,62 @@ function loadFeedbackManifest(workspace) {
     }
   }
   if (current) items.push(current);
-  return { items };
-}
+  return { items };
+}
+
+function findFeedbackItem(workspace, feedbackId) {
+  const manifest = loadFeedbackManifest(workspace);
+  return (manifest.items || []).find(
+    (item) => String(item?.feedback_id || item?.id || "") === String(feedbackId),
+  ) || null;
+}
+
+function assertSynchronizedComment({
+  workspace,
+  feedbackId,
+  commentId,
+  expectedContent,
+  expectedAttachment,
+}) {
+  const item = findFeedbackItem(workspace, feedbackId);
+  assert(item, `Feedback ${feedbackId} was missing while validating synchronized comments.`);
+  const turn = (item.conversation_turns || []).find(
+    (candidate) => String(candidate?.comment_id || "") === String(commentId),
+  );
+  assert(turn, `Comment ${commentId} was not linked to Feedback ${feedbackId} after sync.`);
+  assert(
+    String(turn.content || "").includes(expectedContent),
+    `Comment ${commentId} did not preserve its expected content after sync.`,
+  );
+
+  if (!expectedAttachment) return;
+  const attachment = (turn.attachments || []).find(
+    (candidate) => String(candidate?.name || "") === expectedAttachment.name,
+  );
+  assert(
+    attachment,
+    `Comment ${commentId} did not preserve attachment ${expectedAttachment.name}.`,
+  );
+  assert(
+    attachment.context_status === "readable",
+    `Comment attachment ${expectedAttachment.name} was not synchronized as readable context.`,
+  );
+  assert(
+    attachment.local_file,
+    `Comment attachment ${expectedAttachment.name} did not receive a local file reference.`,
+  );
+  const commandCenterRoot = path.resolve(workspace, "MyteCommandCenter");
+  const localPath = path.resolve(commandCenterRoot, String(attachment.local_file));
+  assert(
+    localPath.startsWith(`${commandCenterRoot}${path.sep}`),
+    `Comment attachment local path escaped MyteCommandCenter: ${attachment.local_file}`,
+  );
+  assert(fs.existsSync(localPath), `Synchronized comment attachment file is missing: ${localPath}`);
+  assert(
+    fs.readFileSync(localPath, "utf8").includes(expectedAttachment.contentMarker),
+    `Synchronized comment attachment ${expectedAttachment.name} lost its readable content.`,
+  );
+}
 
 function findFeedbackState(workspace, feedbackId) {
   const manifest = loadFeedbackManifest(workspace);
@@ -163,9 +430,52 @@ function assertFeedbackAbsent(workspace, feedbackIds) {
   }
 }
 
-function main() {
-  const args = parseArgs(process.argv.slice(2));
-  requireConfirm(args);
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args["confirm-live"]) {
+    console.log(JSON.stringify({
+      ok: true,
+      dry_run: true,
+      message: "No network, project mutation, or local certification artifact was created.",
+      required_live_flag: "--confirm-live",
+      optional_strict_role_flag: "--require-role-matrix",
+      optional_comment_attachment_flag: "--require-comment-attachment-sync",
+      required_role_environment: [
+        "MYTE_OWNER_API_KEY",
+        "MYTE_DELEGATE_API_KEY",
+        "MYTE_COLLABORATOR_API_KEY",
+      ],
+      comment_attachment_environment: "MYTE_WEB_ACCESS_TOKEN",
+      scenario_matrix: LIVE_SCENARIO_MATRIX,
+    }, null, 2));
+    return;
+  }
+  requireConfirm(args);
+
+  const ownerApiKey = String(
+    process.env.MYTE_OWNER_API_KEY
+      || process.env.MYTE_API_KEY
+      || process.env.MYTE_PROJECT_API_KEY
+      || "",
+  ).trim();
+  const delegateApiKey = String(process.env.MYTE_DELEGATE_API_KEY || "").trim();
+  const collaboratorApiKey = String(process.env.MYTE_COLLABORATOR_API_KEY || "").trim();
+  const webAccessToken = String(process.env.MYTE_WEB_ACCESS_TOKEN || "").trim();
+  process.env.MYTE_API_KEY = ownerApiKey;
+  process.env.MYTE_PROJECT_API_KEY = ownerApiKey;
+  if (
+    args["require-role-matrix"]
+    && (!ownerApiKey || !delegateApiKey || !collaboratorApiKey)
+  ) {
+    throw new Error(
+      "--require-role-matrix requires MYTE_OWNER_API_KEY, MYTE_DELEGATE_API_KEY, and MYTE_COLLABORATOR_API_KEY.",
+    );
+  }
+  if (args["require-comment-attachment-sync"] && !webAccessToken) {
+    throw new Error(
+      "--require-comment-attachment-sync requires an ephemeral MYTE_WEB_ACCESS_TOKEN for a user assigned to the target project.",
+    );
+  }
 
   const workspace = path.resolve(
     args.workspace || fs.mkdtempSync(path.join(os.tmpdir(), "myte-feedback-full-harness-")),
@@ -177,40 +487,487 @@ function main() {
     baseArgs.push("--base-url", String(args["base-url"]));
   }
 
-  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-  const reason = String(args.reason || "Disposable live Feedback harness verification");
-  const createdFeedbackIds = [];
-  const reviewRequestIds = [];
-
-  try {
-    const prdFiles = [];
-    for (let index = 1; index <= 5; index += 1) {
-      const title = `TEST Feedback Harness ${stamp} ${index}`;
-      prdFiles.push(writePrd(workspace, title, index));
-    }
-
-    const create = runCli([
-      "create-prd",
+  const runId = String(args["run-id"] || new Date().toISOString().replace(/[:.]/g, "-"));
+  const namespace = `MYTE_TEST_${runId.replace(/[^A-Za-z0-9_-]/g, "_")}`;
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const reason = String(args.reason || "Disposable live Feedback harness verification");
+  const createdFeedbackIds = [];
+  const reviewRequestIds = [];
+  const reviewArtifactByRequestId = new Map();
+  let documentSetFeedbackId = null;
+  let documentSetRequestId = null;
+  const roleMatrix = {
+    required: Boolean(args["require-role-matrix"]),
+    owner: true,
+    delegate: Boolean(delegateApiKey),
+    collaborator: Boolean(collaboratorApiKey),
+    same_project: true,
+    collaborator_review_denied: null,
+    collaborator_direct_apply_denied: null,
+    collaborator_archive_denied: null,
+    collaborator_writes_used: false,
+    owner_review_used: false,
+    delegate_review_used: false,
+  };
+  let commentAttachmentSyncVerified = false;
+  const manifestPath = path.resolve(
+    args.manifest
+      || path.join(workspace, "MyteCommandCenter", "certification", `${runId}.json`),
+  );
+  const manifest = createCertificationManifest({
+    runId,
+    namespace,
+    environment: String(args.environment || "dev"),
+  });
+  manifest.state = "running";
+  writeCertificationManifest(manifestPath, manifest);
+
+  try {
+    const doctor = runCli(
+      ["doctor", "--json", "--timeout-ms", String(args["timeout-ms"] || 60000), ...baseArgs],
+      workspace,
+      { apiKey: ownerApiKey },
+    ).stdout;
+    assert(doctor.ok === true, `Myte doctor failed at ${doctor.failure_layer || "unknown"} layer.`);
+
+    const config = runCli(
+      ["config", "--json", ...baseArgs],
+      workspace,
+      { apiKey: ownerApiKey },
+    ).stdout;
+    manifest.project_id = String(
+      config.project_id || config.project?.id || config.project?._id || "",
+    ) || null;
+    for (const [role, apiKey] of [
+      ["delegate", delegateApiKey],
+      ["collaborator", collaboratorApiKey],
+    ]) {
+      if (!apiKey) continue;
+      const roleConfig = runCli(
+        ["config", "--json", ...baseArgs],
+        workspace,
+        { apiKey },
+      ).stdout;
+      const roleProjectId = String(
+        roleConfig.project_id || roleConfig.project?.id || roleConfig.project?._id || "",
+      ).trim();
+      if (!manifest.project_id || roleProjectId !== manifest.project_id) {
+        roleMatrix.same_project = false;
+        throw new Error(`${role} certification key is not scoped to the owner key's project.`);
+      }
+    }
+    writeCertificationManifest(manifestPath, manifest);
+
+    const prdFiles = [];
+    for (let index = 1; index <= 5; index += 1) {
+      const title = `${namespace} Feedback ${stamp} ${index}`;
+      prdFiles.push(writePrd(workspace, title, index));
+    }
+    const createApprovalPath = writeCreateApproval(workspace, runId, prdFiles);
+
+    const create = runCli([
+      "create-prd",
       ...prdFiles,
-      "--description",
-      "Disposable TEST Feedback created by the live Feedback harness.",
-      "--json",
+      "--description",
+      `Disposable ${namespace} Feedback created by the live certification harness.`,
+      "--confirm-write",
+      "--approval-artifact",
+      createApprovalPath,
+      "--json",
       ...baseArgs,
     ], workspace).stdout;
 
     const createdItems = Array.isArray(create.items) ? create.items : [];
     for (const item of createdItems) {
-      if (item.status === "created" && item.feedback_id) {
-        createdFeedbackIds.push(String(item.feedback_id));
-      }
-    }
-    assert(createdFeedbackIds.length === 5, `Expected 5 created TEST feedback items, got ${createdFeedbackIds.length}: ${JSON.stringify(create, null, 2)}`);
-
-    runCli(["feedback-sync", "--json", ...baseArgs], workspace);
-    assertFeedbackPresent(workspace, createdFeedbackIds, "todo");
-
-    for (const feedbackId of createdFeedbackIds) {
-      const draft = runCli([
+      if (item.status === "created" && item.feedback_id) {
+        createdFeedbackIds.push(String(item.feedback_id));
+        recordCertificationArtifact(manifest, {
+          kind: "feedback",
+          id: String(item.feedback_id),
+          metadata: { source: "create-prd", cleanup: "archive" },
+        });
+      }
+    }
+    writeCertificationManifest(manifestPath, manifest);
+    assert(createdFeedbackIds.length === 5, `Expected 5 created TEST feedback items, got ${createdFeedbackIds.length}: ${JSON.stringify(create, null, 2)}`);
+
+    const documentSetTitles = [
+      `${namespace} Document Set Overview`,
+      `${namespace} Document Set Harness`,
+      `${namespace} Document Set Security`,
+    ];
+    const documentSetFiles = documentSetTitles.map((title, index) =>
+      writePrd(workspace, title, 101 + index),
+    );
+    const documentSetApprovalPath = writeCreateApproval(
+      workspace,
+      `${runId}-document-set`,
+      documentSetFiles,
+    );
+    const documentSetCreate = runCli([
+      "create-prd",
+      ...documentSetFiles,
+      "--document-set",
+      "--title",
+      `${namespace} Three Document PRD`,
+      "--description",
+      `Disposable ${namespace} three-document PRD certification record.`,
+      "--confirm-write",
+      "--approval-artifact",
+      documentSetApprovalPath,
+      "--json",
+      ...baseArgs,
+    ], workspace).stdout;
+    documentSetFeedbackId = String(documentSetCreate.feedback_id || "");
+    assert(documentSetFeedbackId, `Document-set creation did not return feedback_id: ${JSON.stringify(documentSetCreate, null, 2)}`);
+    assert(documentSetCreate.document_count === 3, `Expected three PRD documents: ${JSON.stringify(documentSetCreate, null, 2)}`);
+    assert(Array.isArray(documentSetCreate.documents) && documentSetCreate.documents.length === 3, "Document-set metadata did not contain three documents.");
+    recordCertificationArtifact(manifest, {
+      kind: "feedback",
+      id: documentSetFeedbackId,
+      metadata: {
+        source: "create-prd-document-set",
+        document_count: 3,
+        cleanup: "archive",
+      },
+    });
+    for (const document of documentSetCreate.documents) {
+      if (!document.document_id) continue;
+      recordCertificationArtifact(manifest, {
+        kind: "object",
+        id: String(document.document_id),
+        metadata: {
+          object_type: "prd_document",
+          feedback_id: documentSetFeedbackId,
+          cleanup: "retained_with_archived_parent",
+        },
+      });
+    }
+    writeCertificationManifest(manifestPath, manifest);
+
+    runCli(["feedback-sync", "--json", ...baseArgs], workspace);
+    assertFeedbackPresent(workspace, createdFeedbackIds, "todo");
+    assertFeedbackPresent(workspace, [documentSetFeedbackId], "todo");
+    assertDocumentSetMaterialized(
+      workspace,
+      documentSetFeedbackId,
+      documentSetTitles,
+    );
+
+    const collaboratorWriteKey = collaboratorApiKey || ownerApiKey;
+    const operationalReviewKey = delegateApiKey || ownerApiKey;
+    roleMatrix.collaborator_writes_used = Boolean(collaboratorApiKey);
+    const commentApprovalPath = writeCommentApproval(
+      workspace,
+      runId,
+      createdFeedbackIds[0],
+    );
+    const comment = runCli([
+      "feedback",
+      "comment",
+      "--feedback-id",
+      createdFeedbackIds[0],
+      "--body-file",
+      commentApprovalPath,
+      "--confirm-write",
+      "--approval-artifact",
+      commentApprovalPath,
+      "--no-sync",
+      "--json",
+      ...baseArgs,
+    ], workspace, { apiKey: collaboratorWriteKey }).stdout;
+    assert(comment.comment_id, `Feedback comment did not return comment_id: ${JSON.stringify(comment, null, 2)}`);
+    recordCertificationArtifact(manifest, {
+      kind: "comment",
+      id: String(comment.comment_id),
+      metadata: {
+        feedback_id: createdFeedbackIds[0],
+        cleanup: "retained_with_archived_parent",
+      },
+    });
+    let webAttachmentFixture = null;
+    if (webAccessToken) {
+      webAttachmentFixture = await createWebFeedbackCommentWithAttachment({
+        apiBase: resolveHarnessApiBase(args),
+        accessToken: webAccessToken,
+        feedbackId: createdFeedbackIds[0],
+        projectId: manifest.project_id,
+        namespace,
+        timeoutMs: Number(args["timeout-ms"] || 60000),
+      });
+      recordCertificationArtifact(manifest, {
+        kind: "comment",
+        id: webAttachmentFixture.commentId,
+        metadata: {
+          feedback_id: createdFeedbackIds[0],
+          attachment_name: webAttachmentFixture.attachmentName,
+          cleanup: "retained_with_archived_parent",
+        },
+      });
+    }
+
+    runCli(["feedback-sync", "--json", ...baseArgs], workspace);
+    assertSynchronizedComment({
+      workspace,
+      feedbackId: createdFeedbackIds[0],
+      commentId: String(comment.comment_id),
+      expectedContent: runId,
+    });
+    if (webAttachmentFixture) {
+      assertSynchronizedComment({
+        workspace,
+        feedbackId: createdFeedbackIds[0],
+        commentId: webAttachmentFixture.commentId,
+        expectedContent: namespace,
+        expectedAttachment: {
+          name: webAttachmentFixture.attachmentName,
+          contentMarker: `${namespace} Comment Attachment`,
+        },
+      });
+      commentAttachmentSyncVerified = true;
+    }
+
+    const staleGuardFeedbackId = createdFeedbackIds[4];
+    const staleDraft = runCli([
+      "feedback",
+      "edit",
+      "--feedback-id",
+      staleGuardFeedbackId,
+      "--title",
+      `${namespace} stale local proposal`,
+      "--reason",
+      "Harness creates this artifact before a remote revision.",
+      "--json",
+      ...baseArgs,
+    ], workspace).stdout;
+    assert(staleDraft.artifact_path, "Stale-edit guard did not create its initial local artifact.");
+
+    const staleRemoteMove = runCli([
+      "feedback",
+      "move",
+      "--feedback-id",
+      staleGuardFeedbackId,
+      "--from-state",
+      "todo",
+      "--to-state",
+      "in_progress",
+      "--reason",
+      "Harness advances the server revision after the local artifact was created.",
+      "--no-sync",
+      "--json",
+      ...baseArgs,
+    ], workspace, { apiKey: collaboratorWriteKey }).stdout;
+    const staleRemoteMoveEventId = responseEventId(staleRemoteMove);
+    assert(staleRemoteMoveEventId, "Stale-edit guard move did not return an event id.");
+
+    const staleValidation = runCli([
+      "feedback",
+      "validate",
+      "--file",
+      staleDraft.artifact_path,
+      "--json",
+      ...baseArgs,
+    ], workspace, { apiKey: collaboratorWriteKey }).stdout;
+    assert(staleValidation.ok === true && staleValidation.valid === false, "A stale local Feedback artifact unexpectedly validated.");
+    assert(
+      (staleValidation.errors || []).some((error) => error?.code === "snapshot_mismatch"),
+      `Stale artifact did not return snapshot_mismatch: ${JSON.stringify(staleValidation, null, 2)}`,
+    );
+
+    const staleGuardUndo = runCli([
+      "feedback",
+      "undo",
+      "--feedback-id",
+      staleGuardFeedbackId,
+      "--event-id",
+      staleRemoteMoveEventId,
+      "--reason",
+      "Harness restores the disposable card after stale-artifact certification.",
+      "--no-sync",
+      "--json",
+      ...baseArgs,
+    ], workspace, { apiKey: collaboratorWriteKey }).stdout;
+    assert(
+      String(staleGuardUndo.feedback_state || "") === "todo",
+      `Stale-edit guard cleanup did not restore todo: ${JSON.stringify(staleGuardUndo, null, 2)}`,
+    );
+
+    const forcedStaleApply = runCli([
+      "feedback",
+      "apply",
+      "--file",
+      staleDraft.artifact_path,
+      "--force",
+      "--no-sync",
+      "--json",
+      ...baseArgs,
+    ], workspace, { apiKey: ownerApiKey }).stdout;
+    assert(
+      String(forcedStaleApply.feedback?.title || "") === `${namespace} stale proposal`,
+      `Owner forced stale override did not apply the intended title: ${JSON.stringify(forcedStaleApply, null, 2)}`,
+    );
+    assert(
+      (forcedStaleApply.warnings || []).some(
+        (warning) => warning?.code === "snapshot_mismatch_forced",
+      ),
+      `Owner forced stale override did not report snapshot_mismatch_forced: ${JSON.stringify(forcedStaleApply, null, 2)}`,
+    );
+    assert(
+      forcedStaleApply.history?.force === true
+        && Boolean(String(forcedStaleApply.history?.reason || "").trim()),
+      `Owner forced stale override was not explicitly audited with a reason: ${JSON.stringify(forcedStaleApply, null, 2)}`,
+    );
+
+    runCli(["feedback-sync", "--json", ...baseArgs], workspace);
+    const freshDraft = runCli([
+      "feedback",
+      "edit",
+      "--feedback-id",
+      staleGuardFeedbackId,
+      "--title",
+      `${namespace} fresh proposal after resync`,
+      "--reason",
+      "Harness confirms a fresh artifact can replace the rejected stale proposal.",
+      "--json",
+      ...baseArgs,
+    ], workspace).stdout;
+    const freshValidation = runCli([
+      "feedback",
+      "validate",
+      "--file",
+      freshDraft.artifact_path,
+      "--json",
+      ...baseArgs,
+    ], workspace, { apiKey: collaboratorWriteKey }).stdout;
+    assert(
+      freshValidation.ok === true && freshValidation.valid !== false,
+      `Fresh artifact did not validate after resync: ${JSON.stringify(freshValidation, null, 2)}`,
+    );
+
+    if (collaboratorApiKey) {
+      const directApplyDenied = runCli([
+        "feedback",
+        "apply",
+        "--file",
+        freshDraft.artifact_path,
+        "--no-sync",
+        "--json",
+        ...baseArgs,
+      ], workspace, { allowFailure: true, apiKey: collaboratorApiKey }).stdout;
+      roleMatrix.collaborator_direct_apply_denied =
+        directApplyDenied.ok === false && directApplyDenied.status === 403;
+      assert(
+        roleMatrix.collaborator_direct_apply_denied,
+        `Regular collaborator direct apply was not denied: ${JSON.stringify(directApplyDenied, null, 2)}`,
+      );
+
+      const collaboratorArchiveDenied = runCli([
+        "feedback",
+        "move",
+        "--feedback-id",
+        staleGuardFeedbackId,
+        "--from-state",
+        "todo",
+        "--to-state",
+        "archived",
+        "--reason",
+        "Harness expects regular collaborator archive to be denied.",
+        "--no-sync",
+        "--json",
+        ...baseArgs,
+      ], workspace, { allowFailure: true, apiKey: collaboratorApiKey }).stdout;
+      roleMatrix.collaborator_archive_denied =
+        collaboratorArchiveDenied.ok === false && collaboratorArchiveDenied.status === 403;
+      assert(
+        roleMatrix.collaborator_archive_denied,
+        `Regular collaborator archive was not denied: ${JSON.stringify(collaboratorArchiveDenied, null, 2)}`,
+      );
+    }
+
+    const directMove = runCli([
+      "feedback",
+      "move",
+      "--feedback-id",
+      createdFeedbackIds[0],
+      "--from-state",
+      "todo",
+      "--to-state",
+      "in_progress",
+      "--reason",
+      "Harness verifies a collaborator-safe active-state move.",
+      "--no-sync",
+      "--json",
+      ...baseArgs,
+    ], workspace, { apiKey: collaboratorWriteKey }).stdout;
+    const directMoveEventId = responseEventId(directMove);
+    assert(directMoveEventId, `Feedback move did not return an event id: ${JSON.stringify(directMove, null, 2)}`);
+    recordCertificationArtifact(manifest, {
+      kind: "feedback_event",
+      id: directMoveEventId,
+      metadata: {
+        feedback_id: createdFeedbackIds[0],
+        action: "move",
+        cleanup: "retain_audit",
+      },
+    });
+
+    const undo = runCli([
+      "feedback",
+      "undo",
+      "--feedback-id",
+      createdFeedbackIds[0],
+      "--event-id",
+      directMoveEventId,
+      "--reason",
+      "Harness verifies exact event undo.",
+      "--json",
+      ...baseArgs,
+    ], workspace, { apiKey: collaboratorWriteKey }).stdout;
+    assert(
+      String(undo.feedback_state || "") === "todo",
+      `Feedback undo did not restore todo: ${JSON.stringify(undo, null, 2)}`,
+    );
+    const undoEventId = responseEventId(undo);
+    if (undoEventId) {
+      recordCertificationArtifact(manifest, {
+        kind: "feedback_event",
+        id: undoEventId,
+        metadata: {
+          feedback_id: createdFeedbackIds[0],
+          action: "undo",
+          cleanup: "retain_audit",
+        },
+      });
+    }
+
+    const getAfterUndo = runCli([
+      "feedback",
+      "get",
+      "--feedback-id",
+      createdFeedbackIds[0],
+      "--json",
+      ...baseArgs,
+    ], workspace, { apiKey: collaboratorWriteKey }).stdout;
+    assert(
+      String(getAfterUndo.feedback?.feedback_state || "") === "todo",
+      `Feedback get did not return the restored state: ${JSON.stringify(getAfterUndo, null, 2)}`,
+    );
+    const historyAfterUndo = runCli([
+      "feedback",
+      "history",
+      "--feedback-id",
+      createdFeedbackIds[0],
+      "--json",
+      ...baseArgs,
+    ], workspace, { apiKey: collaboratorWriteKey }).stdout;
+    assert(
+      Array.isArray(historyAfterUndo.events) && historyAfterUndo.events.length >= 2,
+      "Feedback history did not include move and undo evidence.",
+    );
+    writeCertificationManifest(manifestPath, manifest);
+
+    for (const feedbackId of createdFeedbackIds) {
+      const draft = runCli([
         "feedback",
         "status",
         "--feedback-id",
@@ -221,23 +978,177 @@ function main() {
         reason,
         "--json",
         ...baseArgs,
-      ], workspace).stdout;
-      assert(draft.artifact_path, `feedback status did not return artifact_path for ${feedbackId}`);
-
-      const submit = runCli([
+      ], workspace).stdout;
+      assert(draft.artifact_path, `feedback status did not return artifact_path for ${feedbackId}`);
+
+      const validation = runCli([
+        "feedback",
+        "validate",
+        "--file",
+        draft.artifact_path,
+        "--json",
+        ...baseArgs,
+      ], workspace, { apiKey: collaboratorWriteKey }).stdout;
+      assert(
+        validation.ok === true && validation.valid !== false,
+        `feedback validate failed for ${feedbackId}: ${JSON.stringify(validation, null, 2)}`,
+      );
+
+      const submit = runCli([
         "feedback",
         "submit",
-        "--file",
-        draft.artifact_path,
-        "--json",
-        ...baseArgs,
-      ], workspace).stdout;
-      const requestId = String(submit.request?.request_id || submit.request?._id || "");
+        "--file",
+        draft.artifact_path,
+        "--confirm-write",
+        "--approval-artifact",
+        draft.artifact_path,
+        "--json",
+        ...baseArgs,
+      ], workspace, { apiKey: collaboratorWriteKey }).stdout;
+      const requestId = responseRequestId(submit);
       assert(requestId, `feedback submit did not return request id for ${feedbackId}: ${JSON.stringify(submit, null, 2)}`);
-      reviewRequestIds.push(requestId);
-    }
-
-    const blocked = runCli([
+      reviewRequestIds.push(requestId);
+      reviewArtifactByRequestId.set(requestId, draft.artifact_path);
+      recordCertificationArtifact(manifest, {
+        kind: "review_request",
+        id: requestId,
+        metadata: { feedback_id: feedbackId },
+      });
+      writeCertificationManifest(manifestPath, manifest);
+    }
+
+    const openReviews = runCli([
+      "feedback",
+      "reviews",
+      "--status",
+      "open",
+      "--json",
+      ...baseArgs,
+    ], workspace, { apiKey: collaboratorWriteKey }).stdout;
+    const openRequestIds = new Set(
+      (openReviews.requests || []).map((request) => responseRequestId(request)).filter(Boolean),
+    );
+    assert(
+      reviewRequestIds.every((requestId) => openRequestIds.has(requestId)),
+      "Feedback review list did not include every submitted certification request.",
+    );
+    const reviewDetail = runCli([
+      "feedback",
+      "reviews",
+      "--request-id",
+      reviewRequestIds[0],
+      "--json",
+      ...baseArgs,
+    ], workspace, { apiKey: collaboratorWriteKey }).stdout;
+    assert(
+      responseRequestId(reviewDetail) === reviewRequestIds[0],
+      "Feedback review detail returned the wrong request.",
+    );
+
+    if (collaboratorApiKey) {
+      const deniedReview = runCli([
+        "feedback",
+        "review",
+        "--request-id",
+        reviewRequestIds[0],
+        "--action",
+        "approve",
+        "--reason",
+        "Harness expects regular collaborator approval to be denied.",
+        "--no-sync",
+        "--json",
+        ...baseArgs,
+      ], workspace, { allowFailure: true, apiKey: collaboratorApiKey }).stdout;
+      roleMatrix.collaborator_review_denied =
+        deniedReview.ok === false && deniedReview.status === 403;
+      assert(
+        roleMatrix.collaborator_review_denied,
+        `Regular collaborator review was not denied as expected: ${JSON.stringify(deniedReview, null, 2)}`,
+      );
+    }
+
+    const requestChanges = runCli([
+      "feedback",
+      "review",
+      "--request-id",
+      reviewRequestIds[0],
+      "--action",
+      "request_changes",
+      "--reason",
+      "Harness requests a submitter revision.",
+      "--verification-evidence",
+      "Initial validation completed; revision path remains to be certified.",
+      "--no-sync",
+      "--json",
+      ...baseArgs,
+    ], workspace, { apiKey: operationalReviewKey }).stdout;
+    assert(
+      String(requestChanges.request?.status || requestChanges.status || "") === "needs_changes",
+      `Request-changes did not enter needs_changes: ${JSON.stringify(requestChanges, null, 2)}`,
+    );
+
+    const revised = runCli([
+      "feedback",
+      "revise",
+      "--request-id",
+      reviewRequestIds[0],
+      "--file",
+      reviewArtifactByRequestId.get(reviewRequestIds[0]),
+      "--confirm-write",
+      "--approval-artifact",
+      reviewArtifactByRequestId.get(reviewRequestIds[0]),
+      "--json",
+      ...baseArgs,
+    ], workspace, { apiKey: collaboratorWriteKey }).stdout;
+    assert(
+      responseRequestId(revised) === reviewRequestIds[0],
+      `Feedback revise returned the wrong request: ${JSON.stringify(revised, null, 2)}`,
+    );
+
+    const rejected = runCli([
+      "feedback",
+      "review",
+      "--request-id",
+      reviewRequestIds[1],
+      "--action",
+      "reject",
+      "--reason",
+      "Harness verifies terminal rejection without applying changes.",
+      "--verification-evidence",
+      "Negative review path certified.",
+      "--no-sync",
+      "--json",
+      ...baseArgs,
+    ], workspace, { apiKey: operationalReviewKey }).stdout;
+    assert(
+      String(rejected.request?.status || rejected.status || "") === "rejected",
+      `Feedback rejection did not become terminal: ${JSON.stringify(rejected, null, 2)}`,
+    );
+
+    const cancelled = runCli([
+      "feedback",
+      "review",
+      "--request-id",
+      reviewRequestIds[2],
+      "--action",
+      "cancel",
+      "--reason",
+      "Harness submitter cancels a disposable review.",
+      "--no-sync",
+      "--json",
+      ...baseArgs,
+    ], workspace, { apiKey: collaboratorWriteKey }).stdout;
+    assert(
+      String(cancelled.request?.status || cancelled.status || "") === "cancelled",
+      `Feedback cancellation did not become terminal: ${JSON.stringify(cancelled, null, 2)}`,
+    );
+
+    const pendingApprovalRequestIds = [
+      reviewRequestIds[0],
+      reviewRequestIds[3],
+      reviewRequestIds[4],
+    ];
+    const blocked = runCli([
       "feedback",
       "move",
       "--feedback-ids",
@@ -256,28 +1167,69 @@ function main() {
     assert(blocked.status === 409, `Expected 409 pending review block, got ${blocked.status}.`);
     assert(blocked.data?.code === "pending_feedback_review", `Expected pending_feedback_review, got ${JSON.stringify(blocked, null, 2)}.`);
 
-    const review = runCli([
-      "feedback",
-      "review",
-      "--request-ids",
-      reviewRequestIds.join(","),
-      "--action",
-      "approve",
-      "--reason",
-      "Harness batch approval.",
-      "--json",
-      ...baseArgs,
-    ], workspace).stdout;
-    assert(review.ok !== false && review.updated_count === 5, `batch review failed: ${JSON.stringify(review, null, 2)}`);
-
-    runCli(["feedback-sync", "--json", ...baseArgs], workspace);
-    assertFeedbackPresent(workspace, createdFeedbackIds, "completed");
-
-    const reopen = runCli([
+    const ownerApproval = runCli([
+      "feedback",
+      "review",
+      "--request-id",
+      reviewRequestIds[0],
+      "--action",
+      "approve",
+      "--reason",
+      "Harness owner approval.",
+      "--verification-evidence",
+      "Stale-state, validation, role denial, request-changes, and revision checks passed.",
+      "--deployment-evidence",
+      "Dev post-deploy certification run; artifacts will be archived.",
+      "--no-sync",
+      "--json",
+      ...baseArgs,
+    ], workspace, { apiKey: ownerApiKey }).stdout;
+    roleMatrix.owner_review_used = true;
+    assert(
+      String(ownerApproval.request?.status || ownerApproval.status || "") === "applied",
+      `Owner approval did not apply: ${JSON.stringify(ownerApproval, null, 2)}`,
+    );
+
+    const batchApprovalRequestIds = [
+      reviewRequestIds[3],
+      reviewRequestIds[4],
+    ];
+    const review = runCli([
+      "feedback",
+      "review",
+      "--request-ids",
+      batchApprovalRequestIds.join(","),
+      "--action",
+      "approve",
+      "--reason",
+      "Harness batch approval.",
+      "--verification-evidence",
+      "Validation, role checks, request-changes, and direct board guards passed.",
+      "--deployment-evidence",
+      "Dev post-deploy certification run; artifacts will be archived.",
+      "--json",
+      ...baseArgs,
+    ], workspace, { apiKey: operationalReviewKey }).stdout;
+    roleMatrix.delegate_review_used = Boolean(delegateApiKey);
+    assert(review.ok !== false && review.updated_count === 2, `batch review failed: ${JSON.stringify(review, null, 2)}`);
+
+    runCli(["feedback-sync", "--json", ...baseArgs], workspace);
+    assertFeedbackPresent(
+      workspace,
+      [createdFeedbackIds[0], createdFeedbackIds[3], createdFeedbackIds[4]],
+      "completed",
+    );
+    assertFeedbackPresent(
+      workspace,
+      [createdFeedbackIds[1], createdFeedbackIds[2]],
+      "todo",
+    );
+
+    const reopen = runCli([
       "feedback",
       "move",
       "--feedback-ids",
-      createdFeedbackIds.join(","),
+      [createdFeedbackIds[0], createdFeedbackIds[3], createdFeedbackIds[4]].join(","),
       "--from-state",
       "completed",
       "--to-state",
@@ -287,29 +1239,206 @@ function main() {
       "--json",
       ...baseArgs,
     ], workspace).stdout;
-    assert(reopen.ok !== false && reopen.updated_count === 5, `batch active move failed: ${JSON.stringify(reopen, null, 2)}`);
-
-    runCli(["feedback-sync", "--json", ...baseArgs], workspace);
-    assertFeedbackPresent(workspace, createdFeedbackIds, "in_progress");
+    assert(reopen.ok !== false && reopen.updated_count === 3, `batch active move failed: ${JSON.stringify(reopen, null, 2)}`);
+
+    runCli(["feedback-sync", "--json", ...baseArgs], workspace);
+    assertFeedbackPresent(
+      workspace,
+      [createdFeedbackIds[0], createdFeedbackIds[3], createdFeedbackIds[4]],
+      "in_progress",
+    );
 
     const archive = runCli([
       "feedback",
-      "move",
-      "--feedback-ids",
-      createdFeedbackIds.join(","),
-      "--from-state",
-      "in_progress",
-      "--to-state",
-      "archived",
+      "move",
+      "--feedback-ids",
+      createdFeedbackIds.join(","),
+      "--to-state",
+      "archived",
       "--reason",
       "Harness cleanup archive.",
       "--json",
       ...baseArgs,
-    ], workspace).stdout;
-    assert(archive.ok !== false && archive.updated_count === 5, `batch archive failed: ${JSON.stringify(archive, null, 2)}`);
-
-    runCli(["feedback-sync", "--json", ...baseArgs], workspace);
-    assertFeedbackAbsent(workspace, createdFeedbackIds);
+    ], workspace).stdout;
+    assert(archive.ok !== false && archive.updated_count === 5, `batch archive failed: ${JSON.stringify(archive, null, 2)}`);
+
+    const selectedDocument = documentSetCreate.documents[1];
+    const selectedDocumentId = String(selectedDocument?.document_id || "").trim();
+    assert(selectedDocumentId, "Three-document PRD did not return a second document id.");
+    const revisedDocumentTitle = `${namespace} Document Set Harness Revised`;
+    const revisedDocumentPath = writePrd(
+      workspace,
+      revisedDocumentTitle,
+      202,
+    );
+    const documentDraft = runCli([
+      "feedback",
+      "edit",
+      "--feedback-id",
+      documentSetFeedbackId,
+      "--prd-file",
+      revisedDocumentPath,
+      "--document-id",
+      selectedDocumentId,
+      "--reason",
+      "Harness verifies document-scoped refinement.",
+      "--json",
+      ...baseArgs,
+    ], workspace).stdout;
+    assert(documentDraft.artifact_path, "Document-scoped edit did not create a review artifact.");
+    const documentValidation = runCli([
+      "feedback",
+      "validate",
+      "--file",
+      documentDraft.artifact_path,
+      "--json",
+      ...baseArgs,
+    ], workspace, { apiKey: collaboratorWriteKey }).stdout;
+    assert(
+      documentValidation.ok === true && documentValidation.valid !== false,
+      `Document-scoped refinement did not validate: ${JSON.stringify(documentValidation, null, 2)}`,
+    );
+    const documentSubmit = runCli([
+      "feedback",
+      "submit",
+      "--file",
+      documentDraft.artifact_path,
+      "--confirm-write",
+      "--approval-artifact",
+      documentDraft.artifact_path,
+      "--json",
+      ...baseArgs,
+    ], workspace, { apiKey: collaboratorWriteKey }).stdout;
+    documentSetRequestId = responseRequestId(documentSubmit);
+    assert(documentSetRequestId, "Document-scoped refinement did not return a review request id.");
+    recordCertificationArtifact(manifest, {
+      kind: "review_request",
+      id: documentSetRequestId,
+      metadata: {
+        feedback_id: documentSetFeedbackId,
+        document_id: selectedDocumentId,
+      },
+    });
+    const documentApproval = runCli([
+      "feedback",
+      "review",
+      "--request-id",
+      documentSetRequestId,
+      "--action",
+      "approve",
+      "--reason",
+      "Harness approves one document without replacing its siblings.",
+      "--verification-evidence",
+      "Document-set validation and sibling-preservation checks passed.",
+      "--deployment-evidence",
+      "Dev post-deploy certification only.",
+      "--no-sync",
+      "--json",
+      ...baseArgs,
+    ], workspace, { apiKey: operationalReviewKey }).stdout;
+    assert(
+      String(documentApproval.request?.status || documentApproval.status || "") === "applied",
+      `Document-scoped approval did not apply: ${JSON.stringify(documentApproval, null, 2)}`,
+    );
+
+    runCli(["feedback-sync", "--json", ...baseArgs], workspace);
+    const synchronizedDocumentRoot = path.join(
+      workspace,
+      "MyteCommandCenter",
+      "PRD",
+      "feedback-sync",
+      documentSetFeedbackId,
+    );
+    const synchronizedDocuments = fs.readdirSync(synchronizedDocumentRoot)
+      .filter((name) => name.toLowerCase().endsWith(".md"))
+      .sort();
+    assert(synchronizedDocuments.length === 3, "Document refinement changed the document count.");
+    assert(
+      fs.readFileSync(path.join(synchronizedDocumentRoot, synchronizedDocuments[0]), "utf8")
+        .includes(`# ${documentSetTitles[0]}`),
+      "Document refinement replaced the first sibling document.",
+    );
+    assert(
+      fs.readFileSync(path.join(synchronizedDocumentRoot, synchronizedDocuments[1]), "utf8")
+        .includes(`# ${revisedDocumentTitle}`),
+      "Document refinement did not update the selected second document.",
+    );
+    assert(
+      fs.readFileSync(path.join(synchronizedDocumentRoot, synchronizedDocuments[2]), "utf8")
+        .includes(`# ${documentSetTitles[2]}`),
+      "Document refinement replaced the third sibling document.",
+    );
+
+    const versions = runCli([
+      "feedback",
+      "prd-versions",
+      "--feedback-id",
+      documentSetFeedbackId,
+      "--json",
+      ...baseArgs,
+    ], workspace, { apiKey: collaboratorWriteKey }).stdout;
+    assert(
+      Array.isArray(versions.versions) && versions.versions.length >= 2,
+      `Document refinement did not retain PRD versions: ${JSON.stringify(versions, null, 2)}`,
+    );
+    const activeVersionId = String(versions.active_prd_version_id || "").trim();
+    const targetVersion =
+      versions.versions.find((version) => responseVersionId(version) !== activeVersionId)
+      || versions.versions[0];
+    const targetVersionId = responseVersionId(targetVersion);
+    assert(targetVersionId, "PRD version list did not return a target version id.");
+    const versionDiff = runCli([
+      "feedback",
+      "prd-diff",
+      "--feedback-id",
+      documentSetFeedbackId,
+      "--version-id",
+      targetVersionId,
+      "--document-id",
+      selectedDocumentId,
+      "--json",
+      ...baseArgs,
+    ], workspace, { apiKey: collaboratorWriteKey }).stdout;
+    assert(
+      String(versionDiff.document_id || "") === selectedDocumentId,
+      `PRD diff was not scoped to the selected document: ${JSON.stringify(versionDiff, null, 2)}`,
+    );
+    for (const version of versions.versions) {
+      const versionId = responseVersionId(version);
+      if (!versionId) continue;
+      recordCertificationArtifact(manifest, {
+        kind: "object",
+        id: versionId,
+        metadata: {
+          object_type: "prd_version",
+          feedback_id: documentSetFeedbackId,
+          cleanup: "retain_audit",
+        },
+      });
+    }
+    writeCertificationManifest(manifestPath, manifest);
+
+    const archiveDocumentSet = runCli([
+      "feedback",
+      "move",
+      "--feedback-id",
+      documentSetFeedbackId,
+      "--from-state",
+      "todo",
+      "--to-state",
+      "archived",
+      "--reason",
+      "Harness cleanup archive for three-document PRD.",
+      "--json",
+      ...baseArgs,
+    ], workspace).stdout;
+    assert(
+      archiveDocumentSet.ok !== false,
+      `document-set archive failed: ${JSON.stringify(archiveDocumentSet, null, 2)}`,
+    );
+
+    runCli(["feedback-sync", "--json", ...baseArgs], workspace);
+    assertFeedbackAbsent(workspace, [...createdFeedbackIds, documentSetFeedbackId]);
 
     const unarchive = runCli([
       "feedback",
@@ -327,29 +1456,90 @@ function main() {
       ...baseArgs,
     ], workspace, { allowFailure: true }).stdout;
     assert(unarchive.ok === false, "Project-key Feedback unarchive unexpectedly succeeded.");
-    assert(unarchive.status === 403, `Expected project-key unarchive to return 403, got ${unarchive.status}.`);
-    assert(unarchive.data?.code === "feedback_unarchive_not_supported_project_api", `Unexpected unarchive error: ${JSON.stringify(unarchive, null, 2)}`);
-
-    console.log(JSON.stringify({
-      ok: true,
-      workspace,
-      created_feedback_ids: createdFeedbackIds,
-      review_request_ids: reviewRequestIds,
-      pending_review_batch_block_verified: true,
-      batch_review_verified: true,
-      batch_active_move_verified: true,
-      batch_archive_verified: true,
-      archived_sync_exclusion_verified: true,
+    assert(unarchive.status === 403, `Expected project-key unarchive to return 403, got ${unarchive.status}.`);
+    assert(unarchive.data?.code === "feedback_unarchive_not_supported_project_api", `Unexpected unarchive error: ${JSON.stringify(unarchive, null, 2)}`);
+
+    if (roleMatrix.required) {
+      assert(roleMatrix.same_project, "Certification role keys were not scoped to one project.");
+      assert(roleMatrix.collaborator_writes_used, "Regular collaborator writes were not certified.");
+      assert(roleMatrix.collaborator_review_denied, "Collaborator approval denial was not certified.");
+      assert(roleMatrix.collaborator_direct_apply_denied, "Collaborator direct-apply denial was not certified.");
+      assert(roleMatrix.collaborator_archive_denied, "Collaborator archive denial was not certified.");
+      assert(roleMatrix.owner_review_used, "Owner approval was not used during strict role certification.");
+      assert(roleMatrix.delegate_review_used, "Delegate approval was not used during strict role certification.");
+    }
+    if (args["require-comment-attachment-sync"]) {
+      assert(
+        commentAttachmentSyncVerified,
+        "Web-created Feedback comment attachment did not survive Project Assistant sync.",
+      );
+    }
+    manifest.checks = LIVE_SCENARIO_MATRIX.map((scenario) => ({
+      id: scenario.id,
+      status: scenario.id === "owner-delegate-collaborator-matrix"
+        ? (
+            roleMatrix.required
+              ? "passed"
+              : delegateApiKey && collaboratorApiKey
+                ? "passed_optional"
+                : "optional_not_requested"
+          )
+        : scenario.id === "feedback-comment-attachment-sync"
+          ? (
+              commentAttachmentSyncVerified
+                ? "passed"
+                : "optional_not_requested"
+            )
+          : "passed",
+      checked_at: new Date().toISOString(),
+    }));
+    manifest.state = "cleaned";
+    manifest.completed_at = new Date().toISOString();
+    manifest.updated_at = manifest.completed_at;
+    writeCertificationManifest(manifestPath, manifest);
+
+    console.log(JSON.stringify({
+      ok: true,
+      run_id: runId,
+      namespace,
+      workspace,
+      manifest_path: manifestPath,
+      created_feedback_ids: createdFeedbackIds,
+      document_set_feedback_id: documentSetFeedbackId,
+      document_set_review_request_id: documentSetRequestId,
+      review_request_ids: reviewRequestIds,
+      role_matrix: roleMatrix,
+      comment_verified: true,
+      comment_sync_roundtrip_verified: true,
+      comment_attachment_sync_verified: commentAttachmentSyncVerified,
+      stale_edit_rejection_and_resync_verified: true,
+      forced_stale_override_verified: true,
+      move_undo_history_verified: true,
+      validation_verified: true,
+      request_changes_revision_verified: true,
+      rejection_and_cancellation_verified: true,
+      pending_review_batch_block_verified: true,
+      batch_review_verified: true,
+      batch_active_move_verified: true,
+      batch_archive_verified: true,
+      three_document_prd_verified: true,
+      document_scoped_refinement_verified: true,
+      prd_version_diff_verified: true,
+      archived_sync_exclusion_verified: true,
       project_key_unarchive_block_verified: true,
     }, null, 2));
-  } catch (err) {
-    if (createdFeedbackIds.length) {
-      try {
+  } catch (err) {
+    const cleanupFeedbackIds = [
+      ...createdFeedbackIds,
+      ...(documentSetFeedbackId ? [documentSetFeedbackId] : []),
+    ];
+    if (cleanupFeedbackIds.length) {
+      try {
         runCli([
           "feedback",
-          "move",
-          "--feedback-ids",
-          createdFeedbackIds.join(","),
+          "move",
+          "--feedback-ids",
+          cleanupFeedbackIds.join(","),
           "--to-state",
           "archived",
           "--reason",
@@ -360,12 +1550,29 @@ function main() {
       } catch (_cleanupErr) {
         // Keep the original error. Cleanup is best effort and must not hide failure evidence.
       }
-    }
-    const failure = {
-      ok: false,
-      workspace,
-      created_feedback_ids: createdFeedbackIds,
-      review_request_ids: reviewRequestIds,
+    }
+    manifest.state = "cleanup_required";
+    manifest.failure = {
+      message: String(err?.message || err).slice(0, 2000),
+      recorded_at: new Date().toISOString(),
+    };
+    manifest.updated_at = new Date().toISOString();
+    try {
+      writeCertificationManifest(manifestPath, manifest);
+    } catch (_manifestErr) {
+      // Preserve the primary harness failure.
+    }
+    const failure = {
+      ok: false,
+      run_id: runId,
+      namespace,
+      workspace,
+      manifest_path: manifestPath,
+      created_feedback_ids: createdFeedbackIds,
+      document_set_feedback_id: documentSetFeedbackId,
+      document_set_review_request_id: documentSetRequestId,
+      review_request_ids: reviewRequestIds,
+      role_matrix: roleMatrix,
       message: err?.message || String(err),
     };
     console.error(JSON.stringify(failure, null, 2));
@@ -373,4 +1580,10 @@ function main() {
   }
 }
 
-main();
+main().catch((err) => {
+  console.error(JSON.stringify({
+    ok: false,
+    message: err?.message || String(err),
+  }, null, 2));
+  process.exitCode = 1;
+});