@awak-app/simy-cli 0.5.8 → 0.5.11

package/src/install-update.js

@@ -0,0 +1,494 @@
+import { createHash, randomBytes } from "node:crypto";
+import {
+  lstat,
+  mkdir,
+  open,
+  readFile,
+  readdir,
+  readlink,
+  rename,
+  rm,
+  symlink,
+} from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { execFile } from "node:child_process";
+
+const execFileAsync = promisify(execFile);
+const APP_NAME = "SIMY CLI.app";
+const MAX_ARCHIVE_ENTRIES = 100_000;
+const MAX_ARCHIVE_BYTES = 512 * 1024 * 1024;
+const MAX_UNCOMPRESSED_BYTES = 2 * 1024 * 1024 * 1024;
+const MH_MAGIC_64 = 0xfeedfacf;
+const CPU_TYPE_ARM64 = 0x0100000c;
+
+export async function installMacosInstallerRelease({
+  version,
+  release,
+  marker,
+  stateRoot,
+  fetchImpl = fetch,
+  execFileCommand = execFileAsync,
+} = {}) {
+  if (!marker?.teamId) {
+    throw new Error("Automatic installer updates require a signed production installation.");
+  }
+  const updater = release?.artifact?.updater;
+  if (!updater) throw new Error("This release requires a manual installer download.");
+
+  const installerRoot = path.join(stateRoot, "installer");
+  const stagingRoot = path.join(installerRoot, "staging");
+  const releasesRoot = path.join(installerRoot, "releases");
+  const nonce = randomBytes(16).toString("hex");
+  const staging = path.join(stagingRoot, `${version}-${nonce}`);
+  const archivePath = path.join(staging, "update.zip");
+  const extractedRoot = path.join(staging, "extracted");
+  const candidateApp = path.join(extractedRoot, APP_NAME);
+  const releaseDirectory = path.join(releasesRoot, version);
+  const releaseApp = path.join(releaseDirectory, APP_NAME);
+  const currentLink = path.join(installerRoot, "current");
+
+  await mkdir(installerRoot, { recursive: true, mode: 0o700 });
+  await requirePlainDirectory(installerRoot);
+  await mkdir(stagingRoot, { recursive: true, mode: 0o700 });
+  await requirePlainDirectory(stagingRoot);
+  await mkdir(extractedRoot, { recursive: true, mode: 0o700 });
+  try {
+    await downloadVerifiedArchive(updater, archivePath, fetchImpl);
+    await inspectArchive(archivePath);
+    await execFileCommand("/usr/bin/tar", ["-xf", archivePath, "-C", extractedRoot, "--no-same-owner"], {
+      timeout: 5 * 60_000,
+      encoding: "utf8",
+    });
+    await rejectLinks(candidateApp);
+    await verifyCandidateApp(candidateApp, {
+      version,
+      marker,
+      execFileCommand,
+    });
+
+    await mkdir(releasesRoot, { recursive: true, mode: 0o700 });
+    await requirePlainDirectory(installerRoot);
+    await requirePlainDirectory(releasesRoot);
+    let releaseExists = false;
+    try {
+      const releaseDetails = await lstat(releaseDirectory);
+      if (!releaseDetails.isDirectory() || releaseDetails.isSymbolicLink()) {
+        throw new Error("Existing installer release path is not a plain directory.");
+      }
+      releaseExists = true;
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
+    if (releaseExists) {
+      await rejectLinks(releaseApp);
+      await verifyCandidateApp(releaseApp, { version, marker, execFileCommand });
+      await rm(staging, { recursive: true, force: true });
+    } else {
+      await rename(extractedRoot, releaseDirectory);
+      await rm(staging, { recursive: true, force: true });
+    }
+
+    const previousTarget = await readCurrentTarget(currentLink, installerRoot);
+    await switchCurrentLink({ installerRoot, currentLink, target: releaseApp, nonce });
+    return {
+      entryPath: path.join(releaseApp, "Contents", "Resources", "cli", "src", "index.js"),
+      executablePath: path.join(releaseApp, "Contents", "Resources", "runtime", "bin", "node"),
+      appPath: releaseApp,
+      rollback: async () => {
+        if (previousTarget) {
+          await switchCurrentLink({ installerRoot, currentLink, target: previousTarget, nonce: `${nonce}-rollback` });
+        } else {
+          await rm(currentLink, { force: true });
+        }
+      },
+    };
+  } catch (error) {
+    await rm(staging, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+export async function readCurrentInstallerVersion({ stateRoot } = {}) {
+  const packagePath = path.join(
+    stateRoot,
+    "installer",
+    "current",
+    "Contents",
+    "Resources",
+    "cli",
+    "package.json",
+  );
+  const payload = JSON.parse(await readFile(packagePath, "utf8"));
+  return String(payload.version || "").trim();
+}
+
+export async function downloadVerifiedArchive(updater, destination, fetchImpl = fetch) {
+  if (new URL(updater.url).protocol !== "https:") {
+    throw new Error("Installer update download must use HTTPS.");
+  }
+  if (updater.size > MAX_ARCHIVE_BYTES) {
+    throw new Error("Installer update archive exceeds the download safety limit.");
+  }
+  const response = await fetchImpl(updater.url, {
+    headers: { Accept: "application/zip, application/octet-stream" },
+    signal: AbortSignal.timeout(5 * 60_000),
+  });
+  if (!response.ok || !response.body) {
+    throw new Error(`Installer update download returned HTTP ${response.status}.`);
+  }
+  if (response.url && new URL(response.url).protocol !== "https:") {
+    throw new Error("Installer update download redirected to an insecure URL.");
+  }
+  const declaredLength = response.headers.get("content-length");
+  if (declaredLength && Number(declaredLength) !== updater.size) {
+    throw new Error("Installer update download size does not match the release manifest.");
+  }
+  const handle = await open(destination, "wx", 0o600);
+  const hash = createHash("sha256");
+  let size = 0;
+  try {
+    for await (const value of response.body) {
+      const chunk = Buffer.from(value);
+      size += chunk.length;
+      if (size > updater.size) throw new Error("Installer update download exceeds its declared size.");
+      hash.update(chunk);
+      await handle.write(chunk);
+    }
+  } finally {
+    await handle.close();
+  }
+  if (size !== updater.size || hash.digest("hex") !== updater.sha256) {
+    throw new Error("Installer update download failed size or SHA-256 verification.");
+  }
+}
+
+export async function inspectArchive(archivePath) {
+  const bytes = await readFile(archivePath);
+  const minimumEocd = Math.max(0, bytes.length - 65_557);
+  let eocd = -1;
+  for (let offset = bytes.length - 22; offset >= minimumEocd; offset -= 1) {
+    if (bytes.readUInt32LE(offset) === 0x06054b50) {
+      eocd = offset;
+      break;
+    }
+  }
+  if (eocd < 0 || eocd + 22 + bytes.readUInt16LE(eocd + 20) !== bytes.length) {
+    throw new Error("Installer update archive has an invalid central directory.");
+  }
+  const disk = bytes.readUInt16LE(eocd + 4);
+  const centralDisk = bytes.readUInt16LE(eocd + 6);
+  const diskEntries = bytes.readUInt16LE(eocd + 8);
+  const entryCount = bytes.readUInt16LE(eocd + 10);
+  const centralSize = bytes.readUInt32LE(eocd + 12);
+  const centralOffset = bytes.readUInt32LE(eocd + 16);
+  if (
+    disk !== 0 ||
+    centralDisk !== 0 ||
+    diskEntries !== entryCount ||
+    entryCount === 0 ||
+    entryCount > MAX_ARCHIVE_ENTRIES ||
+    centralSize === 0xffffffff ||
+    centralOffset === 0xffffffff ||
+    centralOffset + centralSize !== eocd
+  ) {
+    throw new Error("Installer update archive uses an unsupported ZIP structure.");
+  }
+  const entries = [];
+  const localRanges = [];
+  let totalBytes = 0;
+  let offset = centralOffset;
+  for (let index = 0; index < entryCount; index += 1) {
+    if (offset + 46 > eocd || bytes.readUInt32LE(offset) !== 0x02014b50) {
+      throw new Error("Installer update archive has a malformed central-directory entry.");
+    }
+    const versionMadeBy = bytes.readUInt16LE(offset + 4);
+    const flags = bytes.readUInt16LE(offset + 8);
+    const method = bytes.readUInt16LE(offset + 10);
+    const crc32 = bytes.readUInt32LE(offset + 16);
+    const compressedSize = bytes.readUInt32LE(offset + 20);
+    const uncompressedSize = bytes.readUInt32LE(offset + 24);
+    const nameLength = bytes.readUInt16LE(offset + 28);
+    const extraLength = bytes.readUInt16LE(offset + 30);
+    const commentLength = bytes.readUInt16LE(offset + 32);
+    const externalAttributes = bytes.readUInt32LE(offset + 38);
+    const localOffset = bytes.readUInt32LE(offset + 42);
+    const end = offset + 46 + nameLength + extraLength + commentLength;
+    if (
+      end > eocd ||
+      compressedSize === 0xffffffff ||
+      uncompressedSize === 0xffffffff ||
+      localOffset === 0xffffffff ||
+      (flags & 0x1) !== 0 ||
+      localOffset + 30 > centralOffset ||
+      bytes.readUInt32LE(localOffset) !== 0x04034b50
+    ) {
+      throw new Error("Installer update archive contains an unsupported entry.");
+    }
+    const nameBytes = bytes.subarray(offset + 46, offset + 46 + nameLength);
+    const centralExtra = bytes.subarray(
+      offset + 46 + nameLength,
+      offset + 46 + nameLength + extraLength,
+    );
+    rejectUnsafeExtraFields(centralExtra);
+    if ((flags & 0x800) === 0 && nameBytes.some((value) => value >= 0x80)) {
+      throw new Error("Installer update archive contains a non-UTF-8 path.");
+    }
+    let name;
+    try {
+      name = new TextDecoder("utf-8", { fatal: true }).decode(nameBytes);
+    } catch {
+      throw new Error("Installer update archive contains an invalid UTF-8 path.");
+    }
+    const localNameLength = bytes.readUInt16LE(localOffset + 26);
+    const localExtraLength = bytes.readUInt16LE(localOffset + 28);
+    const localFlags = bytes.readUInt16LE(localOffset + 6);
+    const localMethod = bytes.readUInt16LE(localOffset + 8);
+    const localName = bytes.subarray(localOffset + 30, localOffset + 30 + localNameLength);
+    const localExtra = bytes.subarray(
+      localOffset + 30 + localNameLength,
+      localOffset + 30 + localNameLength + localExtraLength,
+    );
+    rejectUnsafeExtraFields(localExtra);
+    const dataEnd = localOffset + 30 + localNameLength + localExtraLength + compressedSize;
+    if (
+      !nameBytes.equals(localName) ||
+      localFlags !== flags ||
+      localMethod !== method ||
+      dataEnd > centralOffset
+    ) {
+      throw new Error("Installer update archive entry names do not match.");
+    }
+    let entryEnd = dataEnd;
+    if ((flags & 0x08) !== 0) {
+      const hasSignature = dataEnd + 4 <= centralOffset && bytes.readUInt32LE(dataEnd) === 0x08074b50;
+      const descriptor = dataEnd + (hasSignature ? 4 : 0);
+      if (
+        descriptor + 12 > centralOffset ||
+        bytes.readUInt32LE(descriptor) !== crc32 ||
+        bytes.readUInt32LE(descriptor + 4) !== compressedSize ||
+        bytes.readUInt32LE(descriptor + 8) !== uncompressedSize
+      ) {
+        throw new Error("Installer update archive has an invalid data descriptor.");
+      }
+      entryEnd = descriptor + 12;
+    }
+    validateArchivePath(name);
+    const unixMode = (versionMadeBy >>> 8) === 3 ? externalAttributes >>> 16 : 0;
+    if ((unixMode & 0o170000) === 0o120000) {
+      throw new Error("Installer update archive contains a symbolic link.");
+    }
+    const fileType = unixMode & 0o170000;
+    if (fileType !== 0 && fileType !== 0o040000 && fileType !== 0o100000) {
+      throw new Error("Installer update archive contains an unsafe special file.");
+    }
+    if ((name.endsWith("/") && fileType === 0o100000) || (!name.endsWith("/") && fileType === 0o040000)) {
+      throw new Error("Installer update archive entry type does not match its path.");
+    }
+    totalBytes += uncompressedSize;
+    if (!Number.isSafeInteger(totalBytes) || totalBytes > MAX_UNCOMPRESSED_BYTES) {
+      throw new Error("Installer update archive expands beyond the safety limit.");
+    }
+    entries.push(name);
+    localRanges.push([localOffset, entryEnd]);
+    offset = end;
+  }
+  if (offset !== eocd) {
+    throw new Error("Installer update archive central-directory size does not match its entries.");
+  }
+  if (new Set(entries).size !== entries.length) {
+    throw new Error("Installer update archive contains duplicate paths.");
+  }
+  const normalizedEntries = entries.map((name) => name.normalize("NFD").toLowerCase());
+  if (new Set(normalizedEntries).size !== normalizedEntries.length) {
+    throw new Error("Installer update archive contains colliding paths.");
+  }
+  localRanges.sort((left, right) => left[0] - right[0]);
+  for (let index = 1; index < localRanges.length; index += 1) {
+    if (localRanges[index][0] < localRanges[index - 1][1]) {
+      throw new Error("Installer update archive contains overlapping entries.");
+    }
+  }
+  return entries;
+}
+
+function rejectUnsafeExtraFields(bytes) {
+  let offset = 0;
+  while (offset < bytes.length) {
+    if (offset + 4 > bytes.length) {
+      throw new Error("Installer update archive contains a malformed ZIP extra field.");
+    }
+    const id = bytes.readUInt16LE(offset);
+    const size = bytes.readUInt16LE(offset + 2);
+    if (offset + 4 + size > bytes.length) {
+      throw new Error("Installer update archive contains a malformed ZIP extra field.");
+    }
+    if (id === 0x0001 || id === 0x7075) {
+      throw new Error("Installer update archive contains an unsafe path override.");
+    }
+    offset += 4 + size;
+  }
+}
+
+export function validateArchivePath(name) {
+  if (
+    !name ||
+    name.includes("\\") ||
+    name.includes("\0") ||
+    /[\x00-\x1f\x7f]/.test(name) ||
+    path.posix.isAbsolute(name) ||
+    name.split("/").includes("..") ||
+    (name !== APP_NAME && !name.startsWith(`${APP_NAME}/`))
+  ) {
+    throw new Error("Installer update archive contains an unsafe path.");
+  }
+}
+
+export async function verifyCandidateApp(
+  appPath,
+  { version, marker, execFileCommand = execFileAsync } = {},
+) {
+  const resources = path.join(appPath, "Contents", "Resources");
+  const cliRoot = path.join(resources, "cli");
+  const runtimePath = path.join(resources, "runtime", "bin", "node");
+  const entryPath = path.join(cliRoot, "src", "index.js");
+  const appExecutable = path.join(appPath, "Contents", "MacOS", "simy");
+  for (const requiredPath of [runtimePath, entryPath, appExecutable]) await lstat(requiredPath);
+
+  const packageInfo = JSON.parse(await readFile(path.join(cliRoot, "package.json"), "utf8"));
+  const candidateMarker = JSON.parse(await readFile(path.join(cliRoot, "installation.json"), "utf8"));
+  if (packageInfo.version !== version || !sameMarker(candidateMarker, marker)) {
+    throw new Error("Installer update identity does not match the requested release.");
+  }
+
+  await execFileCommand("/usr/bin/codesign", ["--verify", "--deep", "--strict", appPath], {
+    timeout: 60_000,
+    encoding: "utf8",
+  });
+  await execFileCommand("/usr/bin/codesign", ["--verify", "--strict", runtimePath], {
+    timeout: 60_000,
+    encoding: "utf8",
+  });
+  const { stderr = "", stdout = "" } = await execFileCommand(
+    "/usr/bin/codesign",
+    ["-d", "--verbose=4", appPath],
+    { timeout: 60_000, encoding: "utf8" },
+  );
+  const signingDetails = `${stdout}\n${stderr}`;
+  if (
+    !signingDetails.split("\n").includes(`Identifier=${marker.bundleId}`) ||
+    !signingDetails.split("\n").includes(`TeamIdentifier=${marker.teamId}`)
+  ) {
+    throw new Error("Installer update signature identity does not match the installed SIMY release.");
+  }
+  const gatekeeper = await execFileCommand("/usr/sbin/spctl", [
+    "--assess",
+    "--type",
+    "execute",
+    "--verbose=4",
+    appPath,
+  ], {
+    timeout: 60_000,
+    encoding: "utf8",
+  });
+  if (!/source=Notarized Developer ID/i.test(`${gatekeeper.stdout || ""}\n${gatekeeper.stderr || ""}`)) {
+    throw new Error("Installer update did not pass the notarized Developer ID policy.");
+  }
+  await verifyArm64MachO(runtimePath);
+  await verifyArm64MachO(appExecutable);
+  const { stdout: bundleVersion } = await execFileCommand(
+    "/usr/bin/plutil",
+    ["-extract", "CFBundleShortVersionString", "raw", "-o", "-", path.join(appPath, "Contents", "Info.plist")],
+    { timeout: 30_000, encoding: "utf8" },
+  );
+  if (String(bundleVersion || "").trim() !== version) {
+    throw new Error("Installer update app version does not match the requested release.");
+  }
+  return { version, runtimePath, entryPath };
+}
+
+export async function verifyArm64MachO(executablePath) {
+  const handle = await open(executablePath, "r");
+  const header = Buffer.alloc(8);
+  try {
+    const { bytesRead } = await handle.read(header, 0, header.length, 0);
+    if (bytesRead !== header.length) {
+      throw new Error("Installer update contains a truncated executable.");
+    }
+  } finally {
+    await handle.close();
+  }
+  if (
+    header.readUInt32LE(0) !== MH_MAGIC_64 ||
+    header.readUInt32LE(4) !== CPU_TYPE_ARM64
+  ) {
+    throw new Error("Installer update contains a non-arm64 Mach-O executable.");
+  }
+  return true;
+}
+
+function sameMarker(left, right) {
+  return Boolean(
+    left &&
+      right &&
+      left.schemaVersion === 1 &&
+      left.channel === "macos-installer" &&
+      left.platform === "darwin" &&
+      left.arch === "arm64" &&
+      left.teamId === right.teamId &&
+      left.bundleId === right.bundleId &&
+      Object.keys(left).sort().join(",") ===
+        "arch,bundleId,channel,platform,schemaVersion,teamId"
+  );
+}
+
+async function rejectLinks(root) {
+  const details = await lstat(root);
+  if (details.isSymbolicLink()) throw new Error("Installer update contains an unsafe symbolic link.");
+  if (details.isFile()) return;
+  if (!details.isDirectory()) throw new Error("Installer update contains an unsafe special file.");
+  for (const child of await readdir(root)) await rejectLinks(path.join(root, child));
+}
+
+async function requirePlainDirectory(directory) {
+  const details = await lstat(directory);
+  if (!details.isDirectory() || details.isSymbolicLink()) {
+    throw new Error("Installer update storage is not a plain directory.");
+  }
+}
+
+async function readCurrentTarget(currentLink, installerRoot) {
+  try {
+    const details = await lstat(currentLink);
+    if (!details.isSymbolicLink()) {
+      throw new Error("The current installer release pointer is not a symbolic link.");
+    }
+    const target = await readlink(currentLink);
+    if (path.isAbsolute(target)) {
+      throw new Error("The current installer release pointer must be relative.");
+    }
+    const resolved = path.resolve(path.dirname(currentLink), target);
+    const relative = path.relative(installerRoot, resolved);
+    if (relative.startsWith("..") || !relative.startsWith(`releases${path.sep}`)) {
+      throw new Error("The current installer release pointer is outside the release directory.");
+    }
+    return resolved;
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+async function switchCurrentLink({ installerRoot, currentLink, target, nonce }) {
+  const temporaryLink = path.join(installerRoot, `.current-${nonce}`);
+  const relativeTarget = path.relative(installerRoot, target);
+  if (
+    path.isAbsolute(relativeTarget) ||
+    relativeTarget.startsWith("..") ||
+    !relativeTarget.startsWith(`releases${path.sep}`)
+  ) {
+    throw new Error("Refusing to select an installer release outside the release directory.");
+  }
+  await symlink(relativeTarget, temporaryLink);
+  await rename(temporaryLink, currentLink);
+}

package/src/orchestrator/audit.js

@@ -1,3 +1,4 @@
+import { minimumCompletionCheck } from "./minimum-completion.js";
 import { open, readdir, stat } from "node:fs/promises";
 import path from "node:path";
 
@@ -131,7 +132,7 @@ export async function auditAttempt(charter, attempt, { previousAttempt = null, s
   }
   attempt.retry_problem_solving = retryProblemSolving;
 
-  for (const check of completionEvidenceChecks(charter, attempt)) {
+  for (const check of [...completionEvidenceChecks(charter, attempt), minimumCompletionCheck(charter, attempt)]) {
     addCheck(
       check.id,
       check.label,
@@ -143,6 +144,13 @@ export async function auditAttempt(charter, attempt, { previousAttempt = null, s
     );
   }
 
+  if (attempt.independent_audit) {
+    addCheck("minimum_review_current", "Independent review covers the current evidence",
+      Boolean(attempt.independent_audit.minimum_matrix_sha256 &&
+        attempt.independent_audit.minimum_matrix_sha256 === attempt.observed_evidence?.minimum_completion?.matrix_sha256),
+      "Changed minimum evidence requires a fresh independent review.");
+  }
+
   const evidenceRequired = charter.expected_evidence.includes("ui_evidence_path");
   const evidenceArtifact = await inspectEvidence(charter, attempt.ui_evidence_path);
   if (evidenceRequired || attempt.ui_evidence_path) {
@@ -305,7 +313,12 @@ export function evaluatePrReadiness(charter, attempt) {
   const github = attempt.observed_evidence?.github || {};
   const local = attempt.observed_evidence?.local || {};
   const independentAudit = attempt.independent_audit;
+  const minimum = minimumCompletionCheck(charter, attempt);
   const checks = [
+    readinessCheck(minimum.id, minimum.passed, minimum.detail),
+    readinessCheck("minimum_independent_binding",
+      Boolean(independentAudit?.minimum_matrix_sha256 && independentAudit.minimum_matrix_sha256 === attempt.observed_evidence?.minimum_completion?.matrix_sha256),
+      "Independent review must cover the current minimum evidence matrix."),
     readinessCheck("implementation_gate", attempt.audit?.passed === true, "Implementation gate must pass."),
     readinessCheck(
       "independent_ai_audit",
@@ -372,7 +385,9 @@ export function evaluatePrReadiness(charter, attempt) {
     state: ready ? "merge_ready" : "pr_ready_for_review",
     summary: ready
       ? "PR has independently verified evidence, passing checks, and required approval."
-      : "Implementation is complete, but the PR is not merge-ready.",
+      : attempt.audit?.passed && minimum.passed
+        ? "Implementation is verified, but the PR is not merge-ready."
+        : "Implementation verification is incomplete; resolve the pending evidence before promotion.",
     checks,
     pending_reasons: checks.filter((check) => !check.passed).map((check) => check.detail),
   };

package/src/orchestrator/completion-contract.js

@@ -76,7 +76,7 @@ export function normalizeVisualReview(value) {
 
 export function completionEvidenceChecks(charter, attempt) {
   const contract = record(charter?.completion_contract);
-  if (contract.version !== COMPLETION_CONTRACT_VERSION) return [];
+  if (contract.version !== COMPLETION_CONTRACT_VERSION) return [check("completion_contract_version", "Supported completion contract required", false, "Missing or unsupported completion contract; re-charter and verify before promotion.")];
 
   const uncertainty = normalizeUncertaintyVerification(attempt?.uncertainty_verification);
   const rows = acceptanceCriterionRows(charter);

package/src/orchestrator/evidence.js

@@ -1,3 +1,4 @@
+import { collectMinimumCompletion } from "./minimum-completion.js";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 
@@ -25,9 +26,16 @@ export async function collectPrEvidence({
     runCommand,
   });
   const github = await collectGitHubEvidence({ charter, attempt, repositoryPath, runCommand });
+  const minimumCompletion = await collectMinimumCompletion({ charter, attempt, repositoryPath, local });
+  const latest = await collectLocalGitEvidence({ baseBranch: charter.base_branch, repositoryPath, runCommand });
+  if (!latest.available || latest.head_sha !== local.head_sha || !latest.working_tree_clean) {
+    minimumCompletion.status = "evidence_incomplete";
+    minimumCompletion.errors = ["Checkout changed while collecting minimum evidence; verify again."];
+  }
   return {
+    minimum_completion: minimumCompletion,
     collected_at: new Date().toISOString(),
-    local,
+    local: latest,
     github,
   };
 }

package/src/orchestrator/independent-audit.js

@@ -26,6 +26,7 @@ export function buildIndependentAuditInstruction(charter, attempt) {
       "audit_target",
       [
         `Requirement: ${charter.requirement}`,
+        `Original request: ${charter.thread_state?.original_request || charter.requirement}`,
         `Acceptance criteria:\n${bullets(charter.acceptance_criteria)}`,
         `User-visible outcome: ${charter.completion_contract?.user_outcome || charter.requirement}`,
         `Minimum scope:\n${bullets(charter.completion_contract?.minimum_scope || charter.acceptance_criteria)}`,
@@ -43,6 +44,8 @@ export function buildIndependentAuditInstruction(charter, attempt) {
         `Reported tests:\n${bullets(attempt.tests_run || [])}`,
         `Executor uncertainty verification: ${JSON.stringify(attempt.uncertainty_verification || {})}`,
         `Executor criterion evidence: ${JSON.stringify(attempt.criterion_evidence || [])}`,
+        `Minimum evidence matrix: ${attempt.observed_evidence?.minimum_completion?.evidence_path || "missing"}`,
+        `Minimum evidence digest: ${attempt.observed_evidence?.minimum_completion?.matrix_sha256 || "missing"}`,
         `Executor visual review: ${JSON.stringify(attempt.visual_review || {})}`,
         `Observed local branch: ${localEvidence.branch_name || "unknown"}`,
         `Observed local HEAD: ${localEvidence.head_sha || "unknown"}`,
@@ -59,6 +62,7 @@ export function buildIndependentAuditInstruction(charter, attempt) {
         "Inspect the final diff and related code directly from the repository.",
         "Look for unmet acceptance criteria, regressions, security issues, data and concurrency risks, missing tests, and unrelated changes.",
         "Treat executor claims as untrusted until supported by repository evidence.",
+        "Compare the original request to the complete AC-N list and implementation mapping. Report forgotten features, dead controls, unsaved results and broken integration. Open the raw minimum evidence, verify its oracle and actual runtime observations; matching expected/actual JSON and hashes alone do not prove truth. Check reload/session return and persisted values/ownership when saving is required.",
         "For every AC-N criterion, return a criterion_results entry only after directly checking its cited proof and observed outcome.",
         charter.evidence_policy?.browser_required
           ? "Open and inspect the actual local screenshots or videos. Return visual_review.inspected=true only after checking their visible content against the acceptance criteria."
@@ -70,7 +74,8 @@ export function buildIndependentAuditInstruction(charter, attempt) {
       "result_contract",
       [
         "Finish with exactly one line beginning SIMY_AUDIT_JSON: followed by one JSON object.",
-        "Required keys: passed, summary, findings, criterion_results, visual_review.",
+        "Required keys: passed, summary, findings, criterion_results, visual_review, coverage_review.",
+        "coverage_review must contain requirements_complete (boolean), unmapped_requirements (array), and observation explaining the comparison of the original request, AC-N list, implementation and raw user/system proof. Use false and list gaps when anything is missing or unverified.",
         "Each finding candidate must contain passed, code, severity, target, explanation, and repairability.",
         "criterion_results must contain one entry per AC-N with criterion_id, passed, verification_method, evidence_refs, and observed_result.",
         "visual_review must contain inspected, artifacts, and acceptance_observations.",
@@ -195,12 +200,19 @@ export function buildIndependentAudit(execution, charter = null, attempt = null)
       auto_fix_hint: null,
     });
   }
+  const coverage = result.coverage_review;
+  if (attempt && !(coverage?.requirements_complete === true &&
+      Array.isArray(coverage.unmapped_requirements) && coverage.unmapped_requirements.length === 0 && cleanString(coverage.observation))) {
+    findings.push({ passed: false, code: "MINIMUM_REQUIREMENT_COVERAGE_UNPROVEN", severity: "blocker",
+      target: "coverage_review", explanation: "Original request coverage and raw minimum evidence were not independently verified.", repairability: "auto" });
+  }
   const requiresHuman = findings.some((item) => item.repairability === "manual");
   return {
     passed: result.passed === true && findings.length === 0,
     summary: cleanString(result.summary) || "Independent audit completed.",
     findings,
     criterion_results: criterionResults,
+    coverage_review: coverage || null,
     visual_review: visualReview,
     requires_human: requiresHuman,
   };

package/src/orchestrator/instruction.js

@@ -1,3 +1,4 @@
+import { minimumCharter } from "../codex-plugins/simy/skills/agentic-delivery-loop/scripts/check-minimum-completion.mjs";
 import { bullets, looksLikeUiTask, section } from "./shared.js";
 import { problemSolvingResultContract } from "./problem-solving.js";
 import { acceptanceCriterionRows } from "./completion-contract.js";
@@ -50,6 +51,17 @@ export function buildCodingInstruction(
         ),
       ),
     ),
+    section("minimum_completion_evidence", [
+      "All delivery levels require this floor. Before implementation reconcile every original requirement with the AC-N list; report omissions instead of silently dropping them.",
+      "Save a matrix.json under the local evidence root (ui_evidence_root or repository .artifacts). Return delivery_evidence_path in SIMY_RESULT_JSON. A passed flag or tests_run string is not proof.",
+      "Use check-minimum-completion.mjs from the installed Delivery Loop skill. Its reference minimum-completion.md defines the matrix and structured observation format.",
+      "For each AC-N include real implementation_refs and required user/system evidence. Exercise the actual operation and result, then inspect postcondition and integration independently. For saving, reload/return in a new session and verify stored values and ownership. Document-only work uses the real command/consumer and artifact integrity, not imaginary API/DB checks.",
+      "First evidence artifact per layer must be JSON: {criterion_id, context_sha256, checks}. User checks: operation (expected=true, actual=observed boolean) and result; system checks: postcondition and integration. Each check includes subject, expected and actual. Derive expected values from the original requirement, not from the candidate output. Include screenshots/logs as additional evidence.",
+      "Freeze and bind observations to the current committed revision and charter before verification. Do not rehash old observations to make changed code pass. Use pending/failed for unavailable or mismatching evidence.",
+      `Controller input JSON: ${JSON.stringify({ id: charter.id, requirement: charter.requirement, repository: charter.repository, acceptance_criteria: charter.acceptance_criteria, completion_contract: charter.completion_contract, thread_state: { original_request: charter.thread_state.original_request } })}`,
+      `Controller-owned acceptance specification: ${JSON.stringify(minimumCharter(charter))}`,
+      `Context: run_id=${charter.id}, stage=locally_verified, environment=local, fixture_id=${charter.id}; input_sha256 is contextDigest(spec.source); source_revisions maps ${charter.repository} to current full HEAD.`,
+    ].join("\n")),
     section("expected_tests", bullets(charter.expected_tests)),
     section("must_not", bullets(charter.must_not)),
   ];
@@ -130,7 +142,7 @@ export function buildCodingInstruction(
       "result_contract",
       [
         "Finish with exactly one line beginning SIMY_RESULT_JSON: followed by one JSON object.",
-        "Required keys: outcome_kind, summary, branch_name, commit_sha, commit_message_headline, pr_url, pr_number, pr_title, pr_base_branch, tests_run, tests_passed, ui_evidence_path, unrelated_changes_detected, secret_scan_passed, changed_files, residual_risks, problem_solving, uncertainty_verification, criterion_evidence, visual_review.",
+        "Required keys: outcome_kind, summary, branch_name, commit_sha, commit_message_headline, pr_url, pr_number, pr_title, pr_base_branch, tests_run, tests_passed, ui_evidence_path, unrelated_changes_detected, secret_scan_passed, changed_files, residual_risks, problem_solving, uncertainty_verification, criterion_evidence, visual_review, delivery_evidence_path.",
         problemSolvingResultContract(),
         "uncertainty_verification must contain top_uncertainty, first_verification, evidence_checked, observed_result, resolved, and fallback. Only set resolved=true when concrete observed evidence resolves it.",
         "criterion_evidence must contain one entry for every AC-N with criterion_id, passed, verification_method, evidence_refs, and observed_result. Only set passed=true when the evidence directly proves that criterion.",