@mytegroupinc/myte-core 0.0.46 → 0.0.49

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

@@ -4,9 +4,40 @@
 const fs = require("node:fs");
 const os = require("node:os");
 const path = require("node:path");
-const { spawnSync } = require("node:child_process");
+const { spawnSync } = require("node:child_process");
+const {
+  createCertificationManifest,
+  recordCertificationArtifact,
+  validateCertificationManifest,
+} = require("../lib/certification-manifest");
 
-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-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 +59,28 @@ 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 };
+  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"],
   });
@@ -68,7 +108,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,8 +127,99 @@ 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) {
   const manifestPath = path.join(workspace, "MyteCommandCenter", "data", "feedback.yml");
@@ -163,9 +294,44 @@ function assertFeedbackAbsent(workspace, feedbackIds) {
   }
 }
 
-function main() {
-  const args = parseArgs(process.argv.slice(2));
-  requireConfirm(args);
+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",
+      required_role_environment: [
+        "MYTE_OWNER_API_KEY",
+        "MYTE_DELEGATE_API_KEY",
+        "MYTE_COLLABORATOR_API_KEY",
+      ],
+      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();
+  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.",
+    );
+  }
 
   const workspace = path.resolve(
     args.workspace || fs.mkdtempSync(path.join(os.tmpdir(), "myte-feedback-full-harness-")),
@@ -177,40 +343,283 @@ 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,
+    delegate_review_used: 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;
+    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",
+      },
+    });
+
+    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 +630,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 +819,42 @@ 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 review = runCli([
+      "feedback",
+      "review",
+      "--request-ids",
+      pendingApprovalRequestIds.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 === 3, `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 +864,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 +1081,65 @@ 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_review_denied, "Collaborator approval denial was not certified.");
+      assert(roleMatrix.delegate_review_used, "Delegate approval was not used during strict role certification.");
+    }
+    manifest.checks = LIVE_SCENARIO_MATRIX.map((scenario) => ({
+      id: scenario.id,
+      status:
+        scenario.id === "owner-delegate-collaborator-matrix" && !roleMatrix.required
+          ? "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,
+      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 +1150,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));