@awak-app/simy-cli 0.2.2 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awak-app/simy-cli",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Local SIMY Agentic Loop executor for Codex and Claude Code.",
   "type": "module",
   "bin": {
@@ -26,12 +26,13 @@
     "test:e2e:budgets": "node ./scripts/budget-enforcement-e2e.js",
     "test:e2e:desktop-executor": "node ./scripts/desktop-executor-e2e.js",
     "test:e2e:pre-guardrail": "node ./scripts/pre-guardrail-e2e.js",
+    "test:e2e:completion-contract": "node ./scripts/completion-contract-e2e.js",
     "test:e2e:console:real-provider": "node ./scripts/real-provider-console-e2e.js",
     "test:e2e:console:fullstack": "node ./scripts/fullstack-cli-smoke.js",
     "check": "npm run check:auto-update && node --check ./src/desktop-executor.js && node --check ./scripts/desktop-executor-e2e.js && node --check ./scripts/pre-guardrail-e2e.js && node --check ./scripts/fixtures/fake-desktop-provider.js && npm run check:syntax && npm run check:real-provider-syntax && npm test && npm run check:package",
     "check:auto-update": "node --check ./src/auto-update.js && node --check ./scripts/auto-update-e2e.js",
     "check:real-provider-syntax": "node --check ./scripts/real-codex-probe.js && node --check ./scripts/real-claude-probe.js && node --check ./scripts/real-provider-console-fixture.js && node --check ./scripts/real-provider-console-e2e.js",
-    "check:syntax": "node --check ./src/index.js && node --check ./src/agent.js && node --check ./src/browser.js && node --check ./src/web-api.js && node --check ./src/run-registry.js && node --check ./src/direct-executor.js && node --check ./src/execution-guardrail.js && node --check ./src/backend-executable.js && node --check ./src/provider-stream.js && node --check ./src/console/index.js && node --check ./src/console/app.js && node --check ./src/console/commands.js && node --check ./src/local-attachments.js && node --check ./src/repository-inventory.js && node --check ./src/session-store.js && node --check ./src/web-origin.js && node --check ./src/workspace-context.js && node --check ./src/orchestrator/index.js && node --check ./src/orchestrator/shared.js && node --check ./src/orchestrator/recovery.js && node --check ./src/orchestrator/risk.js && node --check ./src/orchestrator/contract.js && node --check ./src/orchestrator/instruction.js && node --check ./src/orchestrator/problem-solving.js && node --check ./src/orchestrator/budget.js && node --check ./src/orchestrator/execution-io.js && node --check ./src/orchestrator/presentation.js && node --check ./src/orchestrator/result.js && node --check ./src/orchestrator/retry.js && node --check ./src/orchestrator/evidence.js && node --check ./src/orchestrator/independent-audit.js && node --check ./src/orchestrator/audit.js && node --check ./src/orchestrator/loop.js && node --check ./src/runner.js && node --check ./scripts/fixtures/fake-coding-backend.js && node --check ./scripts/e2e-terminal-evidence.js && node --check ./scripts/audit-gate-e2e.js && node --check ./scripts/retry-circuit-e2e.js && node --check ./scripts/follow-up-charter-e2e.js && node --check ./scripts/task-routing-e2e.js && node --check ./scripts/executor-version-preflight-e2e.js && node --check ./scripts/blocked-recovery-e2e.js && node --check ./scripts/process-localization-e2e.js && node --check ./scripts/hypothesis-retries-e2e.js && node --check ./scripts/budget-enforcement-e2e.js && node --check ./scripts/console-e2e-fixture.js && node --check ./scripts/console-e2e.js && node --check ./scripts/real-provider-console-fixture.js && node --check ./scripts/real-provider-console-e2e.js && node --check ./scripts/fullstack-cli-smoke.js && node --check ./scripts/check-package-contents.js",
+    "check:syntax": "node --check ./src/index.js && node --check ./src/agent.js && node --check ./src/browser.js && node --check ./src/web-api.js && node --check ./src/run-registry.js && node --check ./src/direct-executor.js && node --check ./src/execution-guardrail.js && node --check ./src/backend-executable.js && node --check ./src/provider-stream.js && node --check ./src/console/index.js && node --check ./src/console/app.js && node --check ./src/console/commands.js && node --check ./src/local-attachments.js && node --check ./src/repository-inventory.js && node --check ./src/session-store.js && node --check ./src/web-origin.js && node --check ./src/workspace-context.js && node --check ./src/orchestrator/index.js && node --check ./src/orchestrator/shared.js && node --check ./src/orchestrator/recovery.js && node --check ./src/orchestrator/risk.js && node --check ./src/orchestrator/contract.js && node --check ./src/orchestrator/completion-contract.js && node --check ./src/orchestrator/instruction.js && node --check ./src/orchestrator/problem-solving.js && node --check ./src/orchestrator/budget.js && node --check ./src/orchestrator/execution-io.js && node --check ./src/orchestrator/presentation.js && node --check ./src/orchestrator/result.js && node --check ./src/orchestrator/retry.js && node --check ./src/orchestrator/evidence.js && node --check ./src/orchestrator/independent-audit.js && node --check ./src/orchestrator/audit.js && node --check ./src/orchestrator/loop.js && node --check ./src/runner.js && node --check ./scripts/fixtures/completion-contract-fixture.js && node --check ./scripts/fixtures/fake-coding-backend.js && node --check ./scripts/e2e-terminal-evidence.js && node --check ./scripts/audit-gate-e2e.js && node --check ./scripts/completion-contract-e2e.js && node --check ./scripts/retry-circuit-e2e.js && node --check ./scripts/follow-up-charter-e2e.js && node --check ./scripts/task-routing-e2e.js && node --check ./scripts/executor-version-preflight-e2e.js && node --check ./scripts/blocked-recovery-e2e.js && node --check ./scripts/process-localization-e2e.js && node --check ./scripts/hypothesis-retries-e2e.js && node --check ./scripts/budget-enforcement-e2e.js && node --check ./scripts/console-e2e-fixture.js && node --check ./scripts/console-e2e.js && node --check ./scripts/real-provider-console-fixture.js && node --check ./scripts/real-provider-console-e2e.js && node --check ./scripts/fullstack-cli-smoke.js && node --check ./scripts/check-package-contents.js",
     "check:package": "node ./scripts/check-package-contents.js"
   },
   "engines": {

package/src/cli-contract.js

@@ -1,5 +1,5 @@
-export const CLI_VERSION = "0.2.2";
-export const CLI_API_CONTRACT_VERSION = 2;
+export const CLI_VERSION = "0.2.3";
+export const CLI_API_CONTRACT_VERSION = 3;
 
 export function withCliContract(capabilities = {}, installMode = null) {
   return {

package/src/orchestrator/audit.js

@@ -8,11 +8,23 @@ import {
   stringArray,
 } from "./shared.js";
 import { evaluateRetryProblemSolving } from "./problem-solving.js";
+import {
+  completionEvidenceChecks,
+  normalizeVisualReview,
+} from "./completion-contract.js";
 
 export async function auditAttempt(charter, attempt, { previousAttempt = null } = {}) {
   const checks = [];
-  const addCheck = (id, label, passed, detail, severity = "blocker", repairability = "auto") => {
-    checks.push({ id, label, passed, severity, detail, repairability, evidence_refs: [] });
+  const addCheck = (
+    id,
+    label,
+    passed,
+    detail,
+    severity = "blocker",
+    repairability = "auto",
+    evidenceRefs = [],
+  ) => {
+    checks.push({ id, label, passed, severity, detail, repairability, evidence_refs: evidenceRefs });
   };
   const local = attempt.observed_evidence?.local || {};
 
@@ -119,6 +131,18 @@ export async function auditAttempt(charter, attempt, { previousAttempt = null }
   }
   attempt.retry_problem_solving = retryProblemSolving;
 
+  for (const check of completionEvidenceChecks(charter, attempt)) {
+    addCheck(
+      check.id,
+      check.label,
+      check.passed,
+      check.detail,
+      "blocker",
+      "auto",
+      check.evidence_refs,
+    );
+  }
+
   const evidenceRequired = charter.expected_evidence.includes("ui_evidence_path");
   const evidenceArtifact = await inspectEvidence(charter, attempt.ui_evidence_path);
   if (evidenceRequired || attempt.ui_evidence_path) {
@@ -142,6 +166,32 @@ export async function auditAttempt(charter, attempt, { previousAttempt = null }
         ? `${evidenceArtifact.visual_file_count} screenshot or video artifact(s) found.`
         : "UI and browser-extension work requires a real screenshot or video; a path, text file, or empty directory is not sufficient.",
     );
+    const visualReview = normalizeVisualReview(attempt.visual_review);
+    const visualArtifactReview = await inspectVisualReviewArtifacts(charter, visualReview);
+    addCheck(
+      "visual_content_inspected",
+      "Visual evidence content was inspected against acceptance criteria",
+      Boolean(
+        visualReview.inspected &&
+          visualReview.artifacts.length > 0 &&
+          visualReview.acceptance_observations.length > 0,
+      ),
+      visualReview.inspected && visualReview.acceptance_observations.length > 0
+        ? visualReview.acceptance_observations.join("; ")
+        : "UI evidence must be opened and inspected; record the artifact paths and concrete acceptance observations.",
+      "blocker",
+      "auto",
+      visualReview.artifacts,
+    );
+    addCheck(
+      "visual_review_artifacts_verified",
+      "Claimed visual-review artifacts are real local media",
+      visualArtifactReview.valid,
+      visualArtifactReview.summary,
+      "blocker",
+      "auto",
+      visualArtifactReview.verified,
+    );
   }
 
   const findings = checks
@@ -409,3 +459,41 @@ async function isVisualEvidenceFile(filePath) {
     header.subarray(0, 4).equals(Buffer.from([26, 69, 223, 163]))
   );
 }
+
+async function inspectVisualReviewArtifacts(charter, visualReview) {
+  const root = charter.ui_evidence_root ? path.resolve(charter.ui_evidence_root) : null;
+  const verified = [];
+  const invalid = [];
+  for (const artifact of visualReview.artifacts) {
+    const resolved = path.resolve(artifact);
+    const underRoot = Boolean(
+      root && (resolved === root || resolved.startsWith(`${root}${path.sep}`)),
+    );
+    let fileStat = null;
+    try {
+      fileStat = await stat(resolved);
+    } catch {
+      // The invalid reason below covers missing files.
+    }
+    if (
+      !underRoot ||
+      !fileStat?.isFile() ||
+      fileStat.size <= 0 ||
+      !(await isVisualEvidenceFile(resolved))
+    ) {
+      invalid.push(artifact);
+      continue;
+    }
+    verified.push(resolved);
+  }
+  return {
+    valid: visualReview.artifacts.length > 0 && invalid.length === 0,
+    verified,
+    summary:
+      visualReview.artifacts.length === 0
+        ? "No inspected visual artifact paths were recorded."
+        : invalid.length > 0
+          ? `Missing, non-visual, or out-of-root artifacts: ${invalid.join(", ")}`
+          : `${verified.length} inspected visual artifact(s) exist under the required local root with valid media signatures.`,
+  };
+}

package/src/orchestrator/completion-contract.js

@@ -0,0 +1,159 @@
+import { cleanString, stringArray } from "./shared.js";
+
+export const COMPLETION_CONTRACT_VERSION = 2;
+
+export function buildCompletionContract({
+  inherited,
+  requirement,
+  acceptanceCriteria,
+  nonGoals,
+  expectedEvidence,
+}) {
+  const source = record(inherited);
+  const minimumScope = stringArray(source.minimum_scope);
+  const proofRequired = stringArray(source.proof_required);
+  return {
+    version: COMPLETION_CONTRACT_VERSION,
+    user_outcome: cleanString(source.user_outcome) || cleanString(requirement),
+    minimum_scope:
+      minimumScope.length > 0 ? minimumScope : stringArray(acceptanceCriteria),
+    non_goals: stringArray(nonGoals),
+    proof_required: uniqueStrings([
+      "criterion_evidence",
+      ...proofRequired,
+      ...stringArray(expectedEvidence),
+    ]),
+    deadline: cleanString(source.deadline) || null,
+    milestones: stringArray(source.milestones),
+  };
+}
+
+export function acceptanceCriterionRows(charter) {
+  return stringArray(charter?.acceptance_criteria).map((statement, index) => ({
+    id: `AC-${index + 1}`,
+    statement,
+  }));
+}
+
+export function normalizeUncertaintyVerification(value) {
+  const source = record(value);
+  return {
+    top_uncertainty: cleanString(source.top_uncertainty) || null,
+    first_verification: cleanString(source.first_verification) || null,
+    evidence_checked: uniqueStrings(source.evidence_checked),
+    observed_result: cleanString(source.observed_result) || null,
+    resolved: source.resolved === true,
+    fallback: cleanString(source.fallback) || null,
+  };
+}
+
+export function normalizeCriterionEvidence(value) {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((item) => {
+      const source = record(item);
+      const criterionId = cleanString(source.criterion_id);
+      if (!criterionId) return null;
+      return {
+        criterion_id: criterionId,
+        passed: source.passed === true,
+        verification_method: cleanString(source.verification_method) || null,
+        evidence_refs: uniqueStrings(source.evidence_refs),
+        observed_result: cleanString(source.observed_result) || null,
+      };
+    })
+    .filter(Boolean);
+}
+
+export function normalizeVisualReview(value) {
+  const source = record(value);
+  return {
+    inspected: source.inspected === true,
+    artifacts: uniqueStrings(source.artifacts),
+    acceptance_observations: uniqueStrings(source.acceptance_observations),
+  };
+}
+
+export function completionEvidenceChecks(charter, attempt) {
+  const contract = record(charter?.completion_contract);
+  if (contract.version !== COMPLETION_CONTRACT_VERSION) return [];
+
+  const uncertainty = normalizeUncertaintyVerification(attempt?.uncertainty_verification);
+  const criterionEvidence = normalizeCriterionEvidence(attempt?.criterion_evidence);
+  const rows = acceptanceCriterionRows(charter);
+  const checks = [
+    check(
+      "top_uncertainty_recorded",
+      "Highest uncertainty is explicit",
+      Boolean(uncertainty.top_uncertainty),
+      uncertainty.top_uncertainty || "No highest uncertainty was recorded.",
+    ),
+    check(
+      "first_verification_recorded",
+      "First discriminating verification is explicit",
+      Boolean(uncertainty.first_verification),
+      uncertainty.first_verification || "No first verification was recorded.",
+    ),
+    check(
+      "uncertainty_evidence_recorded",
+      "Uncertainty verification records concrete evidence",
+      uncertainty.evidence_checked.length > 0 && Boolean(uncertainty.observed_result),
+      uncertainty.evidence_checked.length > 0 && uncertainty.observed_result
+        ? `${uncertainty.evidence_checked.length} evidence item(s): ${uncertainty.observed_result}`
+        : "The uncertainty check needs evidence_checked and an observed_result.",
+    ),
+    check(
+      "top_uncertainty_resolved",
+      "Highest uncertainty is resolved before completion",
+      uncertainty.resolved,
+      uncertainty.resolved
+        ? "The executor marked the highest uncertainty resolved with observed evidence."
+        : uncertainty.fallback || "The highest uncertainty remains unresolved.",
+    ),
+  ];
+
+  for (const row of rows) {
+    const matches = criterionEvidence.filter((item) => item.criterion_id === row.id);
+    const evidence = matches[0];
+    checks.push(
+      check(
+        `criterion_evidence_${row.id.toLowerCase()}`,
+        `${row.id} has passing completion evidence`,
+        Boolean(
+          matches.length === 1 &&
+            evidence?.passed &&
+            evidence.verification_method &&
+            evidence.evidence_refs.length > 0 &&
+            evidence.observed_result,
+        ),
+        matches.length > 1
+          ? `Expected exactly one evidence result for ${row.id}; recorded ${matches.length}.`
+          : evidence
+          ? `${evidence.verification_method || "method missing"}: ${
+              evidence.observed_result || "observed result missing"
+            }; evidence ${evidence.evidence_refs.join(", ") || "missing"}.`
+          : `No criterion evidence was recorded for ${row.id}: ${row.statement}`,
+        evidence?.evidence_refs || [],
+      ),
+    );
+  }
+  return checks;
+}
+
+function check(id, label, passed, detail, evidenceRefs = []) {
+  return {
+    id,
+    label,
+    passed: Boolean(passed),
+    detail,
+    evidence_refs: evidenceRefs,
+  };
+}
+
+function record(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function uniqueStrings(value) {
+  return [...new Set(stringArray(value))];
+}

package/src/orchestrator/contract.js

@@ -9,6 +9,7 @@ import {
 } from "./shared.js";
 import { budgetState, resolveRunBudgets } from "./budget.js";
 import { classifyRisk } from "./risk.js";
+import { buildCompletionContract } from "./completion-contract.js";
 import {
   DESKTOP_EXECUTION_TARGET,
   normalizeDesktopExecutionTarget,
@@ -63,6 +64,19 @@ export function createCodingLoopSnapshot({ runId, request, metadata = {} }) {
   const inheritedNonGoals = stringArray(charterContext.non_goals);
   const inheritedArtifacts = stringArray(charterContext.artifacts_required);
   const inheritedAssumptions = stringArray(charterContext.assumptions);
+  const inheritedCompletionContract = record(charterContext.completion_contract);
+  const finalAcceptanceCriteria =
+    acceptanceCriteria.length > 0
+      ? acceptanceCriteria
+      : [
+          "The requested change is implemented without unrelated scope.",
+          "Relevant tests pass and are recorded.",
+          `A pull request targets ${baseBranch}.`,
+        ];
+  const finalNonGoals =
+    inheritedNonGoals.length > 0
+      ? inheritedNonGoals
+      : ["Unrelated refactors", "Server-side execution of repository code"];
   const designReviewRequired =
     risk.requires_design_review || inheritedDesignReview.required === true;
   const designReviewApproved =
@@ -101,14 +115,7 @@ export function createCodingLoopSnapshot({ runId, request, metadata = {} }) {
       retry_budget: budgets.retry_budget,
       token_budget: budgets.token_budget,
       ui_evidence_root: cleanString(request.ui_evidence_root),
-      acceptance_criteria:
-        acceptanceCriteria.length > 0
-          ? acceptanceCriteria
-          : [
-              "The requested change is implemented without unrelated scope.",
-              "Relevant tests pass and are recorded.",
-              `A pull request targets ${baseBranch}.`,
-            ],
+      acceptance_criteria: finalAcceptanceCriteria,
       acceptance_criteria_source: acceptanceCriteriaSource,
       expected_tests: stringArray(request.expected_tests),
       expected_evidence: expectedEvidence,
@@ -149,14 +156,18 @@ export function createCodingLoopSnapshot({ runId, request, metadata = {} }) {
         accepted_artifact_kinds: browserEvidenceRequired ? ["image", "video"] : [],
         visual_review_required: browserEvidenceRequired,
       },
+      completion_contract: buildCompletionContract({
+        inherited: inheritedCompletionContract,
+        requirement: cleanString(charterContext.user_goal) || cleanString(request.requirement),
+        acceptanceCriteria: finalAcceptanceCriteria,
+        nonGoals: finalNonGoals,
+        expectedEvidence,
+      }),
       thread_state: {
         original_request:
           cleanString(charterContext.original_request) || cleanString(request.requirement),
         user_goal: cleanString(charterContext.user_goal) || cleanString(request.requirement),
-        non_goals:
-          inheritedNonGoals.length > 0
-            ? inheritedNonGoals
-            : ["Unrelated refactors", "Server-side execution of repository code"],
+        non_goals: finalNonGoals,
         expected_finish_line:
           cleanString(charterContext.expected_finish_line) ||
           `A verified pull request targeting ${baseBranch}.`,

package/src/orchestrator/independent-audit.js

@@ -1,4 +1,10 @@
 import { bullets, cleanString, section } from "./shared.js";
+import {
+  COMPLETION_CONTRACT_VERSION,
+  acceptanceCriterionRows,
+  normalizeCriterionEvidence,
+  normalizeVisualReview,
+} from "./completion-contract.js";
 
 export function buildIndependentAuditInstruction(charter, attempt) {
   const localEvidence = attempt.observed_evidence?.local || {};
@@ -21,6 +27,8 @@ export function buildIndependentAuditInstruction(charter, attempt) {
       [
         `Requirement: ${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)}`,
         `Risk level: ${charter.risk.level}`,
         `Risk tags: ${charter.risk.tags.join(", ") || "none"}`,
         `Base branch: ${charter.base_branch}`,
@@ -33,6 +41,9 @@ export function buildIndependentAuditInstruction(charter, attempt) {
         `Local UI evidence path: ${attempt.ui_evidence_path || "not reported"}`,
         `Local evidence verification: ${evidenceArtifact?.summary || "not available"}`,
         `Reported tests:\n${bullets(attempt.tests_run || [])}`,
+        `Executor uncertainty verification: ${JSON.stringify(attempt.uncertainty_verification || {})}`,
+        `Executor criterion evidence: ${JSON.stringify(attempt.criterion_evidence || [])}`,
+        `Executor visual review: ${JSON.stringify(attempt.visual_review || {})}`,
         `Observed local branch: ${localEvidence.branch_name || "unknown"}`,
         `Observed local HEAD: ${localEvidence.head_sha || "unknown"}`,
         `Observed changed files:\n${bullets(localEvidence.changed_files || [])}`,
@@ -48,6 +59,10 @@ 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.",
+        "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."
+          : "Do not require visual evidence when the Charter does not require browser evidence.",
         "Do not modify files, commit, push, or update the pull request.",
       ].join("\n"),
     ),
@@ -55,8 +70,10 @@ 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.",
+        "Required keys: passed, summary, findings, criterion_results, visual_review.",
         "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.",
         "Only passed=false entries are findings. Omit passing checks, and never report passed=true evidence as a finding.",
         "Use passed=false when a blocker or major finding remains, or when evidence is unavailable.",
       ].join("\n"),
@@ -64,13 +81,19 @@ export function buildIndependentAuditInstruction(charter, attempt) {
   ].join("\n\n");
 }
 
-export function buildIndependentAudit(execution) {
+export function buildIndependentAudit(execution, charter = null, attempt = null) {
   const result = execution?.result && typeof execution.result === "object" ? execution.result : {};
+  const completionContractV2 =
+    charter?.completion_contract?.version === COMPLETION_CONTRACT_VERSION;
   const valid =
     execution?.exitCode === 0 &&
     !execution?.error &&
     typeof result.passed === "boolean" &&
-    Array.isArray(result.findings);
+    Array.isArray(result.findings) &&
+    (!completionContractV2 ||
+      (Array.isArray(result.criterion_results) &&
+        result.visual_review &&
+        typeof result.visual_review === "object"));
   if (!valid) {
     return {
       passed: false,
@@ -85,6 +108,8 @@ export function buildIndependentAudit(execution) {
           repairability: "manual",
         },
       ],
+      criterion_results: [],
+      visual_review: normalizeVisualReview(null),
       requires_human: true,
     };
   }
@@ -101,6 +126,64 @@ export function buildIndependentAudit(execution) {
       auto_fix_hint: cleanString(item.auto_fix_hint) || null,
     }));
   const findings = evaluations.filter((item) => item.passed === false);
+  const criterionResults = normalizeCriterionEvidence(result.criterion_results);
+  if (completionContractV2) {
+    for (const criterion of acceptanceCriterionRows(charter)) {
+      const matches = criterionResults.filter(
+        (item) => item.criterion_id === criterion.id,
+      );
+      const criterionResult = matches[0];
+      if (
+        matches.length === 1 &&
+        criterionResult?.passed &&
+        criterionResult.verification_method &&
+        criterionResult.evidence_refs.length > 0 &&
+        criterionResult.observed_result
+      ) {
+        continue;
+      }
+      findings.push({
+        passed: false,
+        code: `INDEPENDENT_${criterion.id.replace("-", "_")}_UNPROVEN`,
+        severity: "blocker",
+        target: criterion.id,
+        explanation: matches.length > 1
+          ? `The independent result returned ${matches.length} entries for ${criterion.id}; exactly one is required.`
+          : criterionResult
+          ? `The independent result did not positively prove ${criterion.id}: ${criterion.statement}`
+          : `The independent result omitted ${criterion.id}: ${criterion.statement}`,
+        repairability: "auto",
+        auto_fix_hint: "Re-audit this acceptance criterion and cite directly inspected evidence.",
+      });
+    }
+  }
+  const visualReview = normalizeVisualReview(result.visual_review);
+  const executorVisualReview = normalizeVisualReview(attempt?.visual_review);
+  const visualArtifactsOverlap = visualReview.artifacts.some((artifact) =>
+    executorVisualReview.artifacts.includes(artifact),
+  );
+  if (
+    completionContractV2 &&
+    charter.evidence_policy?.browser_required &&
+    !(
+      visualReview.inspected &&
+      visualReview.artifacts.length > 0 &&
+      visualReview.acceptance_observations.length > 0 &&
+      (!attempt || visualArtifactsOverlap)
+    )
+  ) {
+    findings.push({
+      passed: false,
+      code: "INDEPENDENT_VISUAL_REVIEW_UNPROVEN",
+      severity: "blocker",
+      target: "visual_review",
+      explanation: attempt && !visualArtifactsOverlap
+        ? "The independent auditor did not inspect any artifact from the executor's verified visual-review set."
+        : "The independent auditor did not record inspection of the actual visual evidence content.",
+      repairability: "auto",
+      auto_fix_hint: "Open the local screenshots or videos and record acceptance observations.",
+    });
+  }
   if (result.passed === false && findings.length === 0) {
     findings.push({
       passed: false,
@@ -117,6 +200,8 @@ export function buildIndependentAudit(execution) {
     passed: result.passed === true && findings.length === 0,
     summary: cleanString(result.summary) || "Independent audit completed.",
     findings,
+    criterion_results: criterionResults,
+    visual_review: visualReview,
     requires_human: requiresHuman,
   };
 }

package/src/orchestrator/instruction.js

@@ -1,5 +1,6 @@
 import { bullets, looksLikeUiTask, section } from "./shared.js";
 import { problemSolvingResultContract } from "./problem-solving.js";
+import { acceptanceCriterionRows } from "./completion-contract.js";
 
 export function buildCodingInstruction(
   charter,
@@ -31,7 +32,24 @@ export function buildCodingInstruction(
         `Local evidence root: ${charter.ui_evidence_root || "not required"}`,
       ].join("\n"),
     ),
-    section("acceptance_criteria", bullets(charter.acceptance_criteria)),
+    section(
+      "completion_contract",
+      [
+        `User-visible outcome: ${charter.completion_contract?.user_outcome || charter.thread_state.user_goal}`,
+        `Minimum scope:\n${bullets(charter.completion_contract?.minimum_scope || charter.acceptance_criteria)}`,
+        `Non-goals:\n${bullets(charter.completion_contract?.non_goals || charter.thread_state.non_goals)}`,
+        `Proof required:\n${bullets(charter.completion_contract?.proof_required || [])}`,
+        `Deadline: ${charter.completion_contract?.deadline || "not specified"}`,
+      ].join("\n"),
+    ),
+    section(
+      "acceptance_criteria",
+      bullets(
+        acceptanceCriterionRows(charter).map(
+          (criterion) => `${criterion.id}: ${criterion.statement}`,
+        ),
+      ),
+    ),
     section("expected_tests", bullets(charter.expected_tests)),
     section("must_not", bullets(charter.must_not)),
   ];
@@ -91,16 +109,17 @@ export function buildCodingInstruction(
         "Treat implementation as hypothesis testing: state assumptions, list plausible causes or approaches, inspect discriminating evidence, then choose the smallest strategy supported by that evidence.",
         attemptNumber > 1
           ? "This is a retry. Before editing, generate at least eight distinct MECE hypotheses, select a different primary hypothesis or approach, and do not repeat the previous strategy."
-          : "For the first attempt, make uncertainty and the selected implementation hypothesis explicit before editing.",
+          : "For the first attempt, identify the single highest uncertainty and run the smallest discriminating verification before editing.",
         attemptNumber > 1
           ? "Explain exactly what changed from the previous attempt and why the new evidence supports this strategy."
-          : "Record the selected hypothesis, evidence checked, and strategy in the structured result.",
+          : "Record the uncertainty, first verification, concrete evidence checked, observed result, selected hypothesis, and strategy in the structured result.",
       ].join("\n"),
     ),
     section(
       "execution_contract",
       [
         "Read the repository instructions and current git state before editing.",
+        "Before editing, resolve the highest uncertainty with the first discriminating verification. If it cannot be resolved, stop and report a fallback instead of claiming completion.",
         "Preserve user changes and keep the diff scoped to the requirement.",
         "Run relevant tests, inspect the final diff, commit, push, and create or update a PR.",
         `The PR must target ${charter.base_branch}.`,
@@ -111,8 +130,11 @@ 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.",
+        "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.",
         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.",
+        "For UI or browser-extension work, visual_review must contain inspected=true, the local screenshot or video paths in artifacts, and concrete acceptance_observations from viewing the actual content. Capturing a file without viewing it does not count.",
         "Use null for unavailable scalar values and [] for unavailable arrays. Do not claim evidence that was not observed.",
       ].join("\n"),
     ),

package/src/orchestrator/loop.js

@@ -202,7 +202,11 @@ export async function runCodingLoop({
       }),
     );
     if (shouldStop()) return stopCodingLoop(snapshot, onUpdate);
-    attempt.independent_audit = buildIndependentAudit(auditExecution);
+    attempt.independent_audit = buildIndependentAudit(
+      auditExecution,
+      snapshot.charter,
+      attempt,
+    );
     attempt.token_usage = mergeTokenUsage(attempt.token_usage, auditExecution.tokenUsage);
     attempt.budget = refreshBudgetState(snapshot);
 

package/src/orchestrator/result.js

@@ -1,5 +1,10 @@
 import { cleanString, stringArray } from "./shared.js";
 import { normalizeProblemSolving } from "./problem-solving.js";
+import {
+  normalizeCriterionEvidence,
+  normalizeUncertaintyVerification,
+  normalizeVisualReview,
+} from "./completion-contract.js";
 
 export function buildAttempt({ attemptNumber, charter, instruction, promptInterventions, execution }) {
   const result = execution.result && typeof execution.result === "object" ? execution.result : {};
@@ -28,6 +33,11 @@ export function buildAttempt({ attemptNumber, charter, instruction, promptInterv
     ui_evidence_path: cleanString(result.ui_evidence_path) || null,
     summary,
     problem_solving: normalizeProblemSolving(result.problem_solving),
+    uncertainty_verification: normalizeUncertaintyVerification(
+      result.uncertainty_verification,
+    ),
+    criterion_evidence: normalizeCriterionEvidence(result.criterion_evidence),
+    visual_review: normalizeVisualReview(result.visual_review),
     prompt_interventions: promptInterventions,
     work_log_signals: [],
     work_log_interventions: [],

package/src/runner.js

@@ -158,6 +158,7 @@ export function restoreRun({ snapshot, session, apiOrigin, localPath = null }) {
         risk: charter.risk,
         design_review: charter.design_review,
         evidence_policy: charter.evidence_policy,
+        completion_contract: charter.completion_contract,
         prompt_policy_report: charter.prompt_policy_report,
         original_request: charter.thread_state?.original_request,
         user_goal: charter.thread_state?.user_goal,