@awak-app/simy-cli 0.5.15 → 0.5.17

package/src/orchestrator/instruction.js

@@ -1,7 +1,13 @@
-import { minimumCharter } from "../codex-plugins/simy/skills/agentic-delivery-loop/scripts/check-minimum-completion.mjs";
+import { minimumCharter } from "./delivery/scripts/check-minimum-completion.mjs";
 import { bullets, looksLikeUiTask, section } from "./shared.js";
 import { problemSolvingResultContract } from "./problem-solving.js";
 import { acceptanceCriterionRows } from "./completion-contract.js";
+import { fileURLToPath } from "node:url";
+import { buildPrClosureInstruction } from "./pr-closure.js";
+import { buildUxSpecificationInstruction } from "./ux-specification.js";
+import { buildDeliveryLevelInstruction } from "./delivery-level.js";
+import { buildChecklistContinuationInstruction } from "./checklist-continuation.js";
+import { PR_PREPARATION_CHECKS } from "./pr-preparation.js";
 
 export function buildCodingInstruction(
   charter,
@@ -15,6 +21,9 @@ export function buildCodingInstruction(
 ) {
   const sections = [
     section("role", "You are the local coding executor for a SIMY agentic loop."),
+    buildUxSpecificationInstruction(),
+    buildDeliveryLevelInstruction(),
+    buildChecklistContinuationInstruction(),
     section(
       "requirement_charter",
       [
@@ -63,7 +72,7 @@ export function buildCodingInstruction(
     section("minimum_completion_evidence", [
       "All delivery levels require this floor. Before implementation reconcile every original requirement and frozen experience with the stable criterion-ID 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.",
+      `Use the packaged Web/CLI verifier: ${fileURLToPath(new URL("./delivery/scripts/check-minimum-completion.mjs", import.meta.url))}. The contract is ${fileURLToPath(new URL("./delivery/references/minimum-completion.md", import.meta.url))}. No local Codex Delivery Loop skill is required.`,
       "For each stable criterion ID 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.",
@@ -72,7 +81,26 @@ export function buildCodingInstruction(
       `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("pr_preparation_contract", [
+      "Before reporting the PR ready, complete every preparation row below against the final committed HEAD. Do not reuse evidence after the head, fetched base, companion revision, manifest, policy, or relevant environment changes.",
+      ...PR_PREPARATION_CHECKS.map((row) => `- ${row.id}: ${row.label}`),
+      "Return one pr_preparation entry per ID. A required row needs passed=true, a concrete observation, evidence_refs that resolve to a checked repository file or an observed:* controller fact, and the current full commit SHA in bound_revisions.",
+      "Use applicability=not_applicable only when the changed boundary genuinely excludes the check; include reason, authoritative_source, verified evidence_refs, and the current full commit SHA. Missing tools, failed checks, time, or lack of evidence are pending/failed, not not-applicable.",
+      "exact_revision_integration requires companion_revisions entries with repository/full 40-character sha/evidence_ref and/or manifest_revisions entries with manifest/SHA-256/evidence_ref, or a verified N/A boundary when neither exists. e2e_outcome_and_cleanup requires cleanup_residual_count=0.",
+      "security_and_privacy requires security_privacy_checks. ui_and_i18n requires browser_artifacts, locales_checked, console_error_count=0, and network_failure_count=0, or a verified N/A boundary for non-UI work.",
+      "The final four rows are conditional safeguards. Mark them not_applicable only with current-head-bound verified boundary evidence, never merely because verification is inconvenient.",
+      "official_checklist_ownership applies when checklist/chat rendering changes: verify heading levels 1-6, leading spaces, trailing hashes, exactly one controller-owned official checklist, and an explicit unverified label for model-generated lookalikes.",
+      "deployment_target_mapping applies when release or live verification is in scope: report deployment_target, a verified deployment_target_source evidence ref, and revision_observation_method. Derive the environment from authoritative topology instead of assuming app-dev or production.",
+      "live_data_safety applies to shared/live verification: report live_write_policy as no_persistence, scoped_fixture, or authorized_production_write and cleanup_residual_count=0. Do not infer production-write authority from verification scope.",
+      "resume_compatibility applies when Delivery Loop state, derived views, or rendering changes: exercise normal and checkpoint resume; report paid_resume_support as supported or not_supported with a verified paid_resume_support_source evidence ref, exercise paid resume when supported, and prove derived_views_recomputed and artifact_content_preserved.",
+      "For current_base_and_head, fetch the remote base immediately before final verification, integrate it, and rerun invalidated checks after conflict resolution.",
+      "For current_ci_and_skips, verify the published current HEAD. Return every skipped GitHub check in skipped_checks with name, reason, and impact; a skipped full/live job must not be described as executed E2E.",
+      "For exact_revision_integration, pin every companion repository/manifest SHA and exercise the combined path. For e2e_outcome_and_cleanup, inspect expected scenario states and prove residual fixture count is zero; a green job with failed cleanup is not passing evidence.",
+      "For security_and_privacy, verify changed trust boundaries and that arbitrary messages, email addresses, URLs, identifiers, credentials, or user data are not retained in logs, breadcrumbs, or telemetry. For UI changes, exercise the actual locale/browser, layout overflow, console/network, and screenshot evidence.",
+      "Disclose remaining work, intentional skips, uncertainty, and post-merge migration/deploy/monitoring steps without calling them complete.",
+    ].join("\n")),
     section("must_not", bullets(charter.must_not)),
+    buildPrClosureInstruction(),
     section(
       "active_request_reconciliation",
       [
@@ -161,11 +189,12 @@ 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, delivery_evidence_path.",
+        "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, pr_preparation, skipped_checks.",
         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 stable criterion ID 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.",
+        "pr_preparation must contain the eight stable preparation IDs and four conditional safeguard IDs. skipped_checks must contain name, reason, and impact for every GitHub check that intentionally skipped.",
         "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

@@ -1,4 +1,4 @@
-import { minimumCharter } from "../codex-plugins/simy/skills/agentic-delivery-loop/scripts/check-minimum-completion.mjs";
+import { minimumCharter } from "./delivery/scripts/check-minimum-completion.mjs";
 import { auditAttempt, evaluatePrReadiness } from "./audit.js";
 import {
   buildIndependentAudit,
@@ -9,6 +9,7 @@ import { canStartProvider, refreshBudgetState } from "./budget.js";
 import { buildAttempt, mergeTokenUsage } from "./result.js";
 import { evaluateRetryCircuit } from "./retry.js";
 import { appendEvent, publish } from "./shared.js";
+import { independentAuditEvidenceIdentity } from "./pr-preparation.js";
 
 async function runCodingLoopOwned({
   snapshot,
@@ -212,6 +213,7 @@ async function runCodingLoopOwned({
     if (shouldStop()) return stopCodingLoop(snapshot, onUpdate);
     const auditInstruction = buildIndependentAuditInstruction(snapshot.charter, attempt);
     const reviewedMatrix = attempt.observed_evidence?.minimum_completion?.matrix_sha256;
+    const reviewedEvidenceIdentity = independentAuditEvidenceIdentity(attempt);
     const auditExecution = await safeExecution(() =>
       executeIndependentAudit({
         attemptNumber,
@@ -231,6 +233,7 @@ async function runCodingLoopOwned({
     attempt.budget = refreshBudgetState(snapshot);
 
     attempt.independent_audit.minimum_matrix_sha256 = reviewedMatrix;
+    attempt.independent_audit.evidence_identity_sha256 = reviewedEvidenceIdentity;
 
     // Re-collect after the read-only auditor to catch any mutated HEAD or working tree.
     attempt.observed_evidence = await safeEvidence(collectEvidence, attempt);

package/src/orchestrator/minimum-completion.js

@@ -5,11 +5,11 @@ import {
   minimumContext,
   checkMinimumCompletion,
   loadMinimumJson,
-} from "../codex-plugins/simy/skills/agentic-delivery-loop/scripts/check-minimum-completion.mjs";
+} from "./delivery/scripts/check-minimum-completion.mjs";
 import {
   contextDigest,
   sha256,
-} from "../codex-plugins/simy/skills/agentic-delivery-loop/scripts/check-acceptance.mjs";
+} from "./delivery/scripts/check-acceptance.mjs";
 
 export function minimumCharterDigest(charter) {
   return sha256(Buffer.from(JSON.stringify(minimumCharter(charter))));

package/src/orchestrator/pr-closure.js

@@ -0,0 +1,26 @@
+import { fileURLToPath } from "node:url";
+import { section } from "./shared.js";
+
+export const PR_CLOSURE_GUIDE_PATH = fileURLToPath(
+  new URL("./delivery/references/pr-closure.md", import.meta.url),
+);
+
+// Both real executor and independent-auditor instructions use this contract.
+// This is not a GitHub permission hook: external mutations still need authority.
+export function buildPrClosureInstruction({ auditor = false } = {}) {
+  return section("pr_closure_gate", [
+    "Applies only when proposing, performing or auditing PR closure/supersession/retirement. It does not request closing any PR.",
+    `Before a closure decision, read the packaged Web/CLI procedure: ${PR_CLOSURE_GUIDE_PATH}`,
+    "Freeze the original outcome criteria and exact old head/base, current target base, successor heads, integrated candidate and deployed identity. Preserve intended, observed and unknown behavior separately.",
+    "Persist a criterion-ID before/after table: old PR, current base alone, integrated successors and deployed target. Account for all changed files and unintended added behavior; file counts, ancestry and green CI are not UX equivalence.",
+    "For every unresolved yellow/red row, create a new remediation PR within explicit implementation/commit/push/PR authority, grouping only coherent changes. Reuse an exact existing open remediation PR rather than duplicating it. Map every criterion ID to a real PR URL, owner and acceptance tests; a broad successor link or uncreated PR plan is insufficient for transfer_ready. Missing authority, unresolved product decisions or budget blocks remain explicit blockers. PR creation alone never makes a row green.",
+    "Verify normal production reachability and the complete trigger-to-usable-result path, with independent technical postconditions and recovery. Code surviving only in fixtures is not inherited UX. Distinguish reuse, composition, conversational design, immediate ad-hoc work and background learning, including the no-workflow/no-match fallback.",
+    "Unknown, failed or stale applicable evidence blocks close_ready. Require independent review of original requirements and raw evidence before an authorized close. Preserve initial failures; tests changed to pass do not validate the unchanged original candidate.",
+    "Unfinished successors require transfer_ready with explicit informed administrative-close authorization, accepted owner, open tracking and remaining gates; never claim full inheritance. Intentional removal requires an explicit retirement decision and safe data/migration handling.",
+    "Re-read all bound revisions, successor state, checks and authority immediately before mutation; changed inputs invalidate affected verification/review. Close and comment-posting authority are separate. Audit-only requests authorize neither.",
+    "After an authorized action, read back remote state before claiming success or retrying. Persist pre/post state, review/evidence digests, draft/comment identity, pending obligations and recovery references before cleanup. Do not infer branch deletion, successor merge, deployment or delivery completion.",
+    auditor
+      ? "You remain read-only. Independently inspect the closure table and raw proof; report gaps as findings. Closure decisions never turn unmet delivery criteria green. Do not close, reopen, comment or repair the PR."
+      : "If any required decision, evidence, independent review or authority is missing, stop the dependent close action and report the blocker. This protocol is not authorization and does not introduce a new loop completion state.",
+  ].join("\n"));
+}

package/src/orchestrator/pr-preparation.js

@@ -0,0 +1,420 @@
+import { createHash } from "node:crypto";
+
+import { cleanString, stringArray } from "./shared.js";
+
+export const PR_PREPARATION_CONTRACT_VERSION = 2;
+const LEGACY_PR_PREPARATION_CONTRACT_VERSION = 1;
+
+const BASE_PR_PREPARATION_CHECKS = Object.freeze([
+  { id: "current_base_and_head", label: "Latest base is integrated into the reported head" },
+  { id: "current_ci_and_skips", label: "Current-head CI passed and every skip is disclosed" },
+  { id: "exact_revision_integration", label: "Companion revisions and combined-path evidence are exact and current" },
+  { id: "e2e_outcome_and_cleanup", label: "E2E outcomes passed and cleanup left no residual fixtures" },
+  { id: "security_and_privacy", label: "Security and privacy boundaries were checked at the changed surface" },
+  { id: "ui_and_i18n", label: "Applicable browser, layout, console, and localization checks passed" },
+  { id: "final_diff_and_scope", label: "The final diff is scoped and reviewed against the request" },
+  { id: "residual_status_disclosure", label: "Skipped gates, residual risk, and post-merge work are disclosed" },
+]);
+
+const CONDITIONAL_PR_PREPARATION_CHECKS = Object.freeze([
+  { id: "official_checklist_ownership", label: "Generated checklist-like output cannot duplicate or impersonate the controller checklist", conditional: true },
+  { id: "deployment_target_mapping", label: "The release target and deployed-revision observation method come from an authoritative topology source", conditional: true },
+  { id: "live_data_safety", label: "Live verification has an explicit write policy and leaves no residual test data", conditional: true },
+  { id: "resume_compatibility", label: "Applicable saved-run and checkpoint paths recompute derived views without losing artifacts", conditional: true },
+]);
+
+export const PR_PREPARATION_CHECKS = Object.freeze([
+  ...BASE_PR_PREPARATION_CHECKS,
+  ...CONDITIONAL_PR_PREPARATION_CHECKS,
+]);
+
+export function defaultPrPreparationContract() {
+  return {
+    version: PR_PREPARATION_CONTRACT_VERSION,
+    checks: PR_PREPARATION_CHECKS.map(({ id, label, conditional = false }) => ({
+      id,
+      label,
+      conditional,
+    })),
+  };
+}
+
+export function normalizePrPreparation(value) {
+  const rows = Array.isArray(value) ? value : [];
+  return rows.map((row) => {
+    const source = record(row);
+    return {
+      id: cleanString(source.id),
+      applicability:
+        source.applicability === "not_applicable" ? "not_applicable" : "required",
+      passed: source.passed === true,
+      observation: cleanString(source.observation) || null,
+      evidence_refs: stringArray(source.evidence_refs),
+      bound_revisions: stringArray(source.bound_revisions),
+      reason: cleanString(source.reason) || null,
+      authoritative_source: cleanString(source.authoritative_source) || null,
+      companion_revisions: normalizeCompanionRevisions(source.companion_revisions),
+      manifest_revisions: normalizeManifestRevisions(source.manifest_revisions),
+      cleanup_residual_count: Number.isInteger(source.cleanup_residual_count)
+        ? source.cleanup_residual_count
+        : null,
+      security_privacy_checks: normalizeSecurityPrivacyChecks(source.security_privacy_checks),
+      browser_artifacts: stringArray(source.browser_artifacts),
+      locales_checked: stringArray(source.locales_checked),
+      console_error_count: Number.isInteger(source.console_error_count)
+        ? source.console_error_count
+        : null,
+      network_failure_count: Number.isInteger(source.network_failure_count)
+        ? source.network_failure_count
+        : null,
+      heading_levels_checked: integerArray(source.heading_levels_checked),
+      leading_space_checked: source.leading_space_checked === true,
+      trailing_hash_checked: source.trailing_hash_checked === true,
+      single_official_checklist: source.single_official_checklist === true,
+      unverified_model_output_labeled: source.unverified_model_output_labeled === true,
+      deployment_target: cleanString(source.deployment_target) || null,
+      deployment_target_source: cleanString(source.deployment_target_source) || null,
+      revision_observation_method: cleanString(source.revision_observation_method) || null,
+      live_write_policy: normalizeLiveWritePolicy(source.live_write_policy),
+      resume_paths_checked: stringArray(source.resume_paths_checked),
+      paid_resume_support: normalizePaidResumeSupport(source.paid_resume_support),
+      paid_resume_support_source: cleanString(source.paid_resume_support_source) || null,
+      derived_views_recomputed: source.derived_views_recomputed === true,
+      artifact_content_preserved: source.artifact_content_preserved === true,
+    };
+  }).filter((row) => row.id);
+}
+
+export function normalizeSkippedChecks(value) {
+  const rows = Array.isArray(value) ? value : [];
+  return rows.map((row) => {
+    const source = record(row);
+    return {
+      name: cleanString(source.name),
+      reason: cleanString(source.reason) || null,
+      impact: cleanString(source.impact) || null,
+    };
+  }).filter((row) => row.name);
+}
+
+export function evaluatePrPreparation(charter, attempt) {
+  const contract = record(charter?.pr_preparation_contract);
+  if (!contract.version) {
+    return {
+      applicable: false,
+      passed: true,
+      checks: [],
+      detail: "Legacy charter has no structured PR preparation contract.",
+    };
+  }
+  const expectedChecks = contract.version === PR_PREPARATION_CONTRACT_VERSION
+    ? PR_PREPARATION_CHECKS
+    : contract.version === LEGACY_PR_PREPARATION_CONTRACT_VERSION
+      ? BASE_PR_PREPARATION_CHECKS
+      : null;
+  if (!expectedChecks) {
+    return {
+      applicable: true,
+      passed: false,
+      checks: [check(
+        "supported_pr_preparation_contract",
+        "PR preparation contract version is supported",
+        false,
+        `Unsupported PR preparation contract version: ${contract.version}.`,
+      )],
+      detail: "Unsupported PR preparation contract versions fail closed.",
+    };
+  }
+
+  const rows = normalizePrPreparation(attempt?.pr_preparation);
+  const byId = new Map(rows.map((row) => [row.id, row]));
+  const duplicateIds = rows
+    .map((row) => row.id)
+    .filter((id, index, all) => all.indexOf(id) !== index);
+  const unknownIds = rows
+    .map((row) => row.id)
+    .filter((id) => !expectedChecks.some((expected) => expected.id === id));
+  const headSha = cleanString(attempt?.commit_sha);
+  const verifiedRefs = new Set(
+    (attempt?.observed_evidence?.pr_preparation_refs || [])
+      .filter((item) => item?.verified === true)
+      .map((item) => cleanString(item.ref)),
+  );
+  const verifiedRefRecords = new Map(
+    (attempt?.observed_evidence?.pr_preparation_refs || [])
+      .filter((item) => item?.verified === true)
+      .map((item) => [cleanString(item.ref), item]),
+  );
+  const checks = expectedChecks.map((expected) => {
+    const row = byId.get(expected.id);
+    if (!row) {
+      return check(expected.id, expected.label, false, "Required preparation check is missing.");
+    }
+    if (row.applicability === "not_applicable") {
+      const currentRevisionBound = Boolean(headSha && row.bound_revisions.includes(headSha));
+      const evidenceVerified = row.evidence_refs.length > 0 &&
+        row.evidence_refs.every((ref) => verifiedRefs.has(ref));
+      const valid = Boolean(
+        row.reason && row.authoritative_source && currentRevisionBound && evidenceVerified
+      );
+      return check(
+        expected.id,
+        expected.label,
+        valid,
+        valid
+          ? "Not-applicable boundary is current-head-bound and supported by verified local/controller evidence."
+          : "Not-applicable claims require a reason, an authoritative source, verified evidence references, and the current head SHA binding.",
+      );
+    }
+    const currentRevisionBound = Boolean(headSha && row.bound_revisions.includes(headSha));
+    const evidenceVerified = row.evidence_refs.length > 0 &&
+      row.evidence_refs.every((ref) => verifiedRefs.has(ref));
+    const rowSpecific = rowSpecificValidation(row, verifiedRefRecords);
+    const valid = Boolean(
+      row.passed &&
+      row.observation &&
+      evidenceVerified &&
+      currentRevisionBound &&
+      rowSpecific.passed
+    );
+    return check(
+      expected.id,
+      expected.label,
+      valid,
+      valid
+        ? "Required preparation proof is current-head-bound, structurally complete, and backed by verified local/controller evidence."
+        : `Required checks need passed=true, a concrete observation, verified evidence references, the current head SHA in bound_revisions, and row-specific proof. ${rowSpecific.detail}`,
+    );
+  });
+  if (duplicateIds.length > 0) {
+    checks.push(check(
+      "unique_pr_preparation_ids",
+      "Preparation check IDs are unique",
+      false,
+      `Duplicate preparation check IDs were submitted (count: ${new Set(duplicateIds).size}).`,
+    ));
+  }
+  if (unknownIds.length > 0) {
+    checks.push(check(
+      "known_pr_preparation_ids",
+      "Preparation check IDs are recognized",
+      false,
+      `Unrecognized preparation check IDs were submitted (count: ${new Set(unknownIds).size}).`,
+    ));
+  }
+  return {
+    applicable: true,
+    passed: checks.every((item) => item.passed),
+    checks,
+    detail: checks.every((item) => item.passed)
+      ? "All applicable PR preparation checks have current revision-bound evidence."
+      : "PR preparation evidence is missing, stale, failed, or unjustifiably marked not applicable.",
+  };
+}
+
+export function independentAuditEvidenceIdentity(attempt) {
+  const local = record(attempt?.observed_evidence?.local);
+  const github = record(attempt?.observed_evidence?.github);
+  const payload = {
+    head_sha: cleanString(local.head_sha || attempt?.commit_sha),
+    fetched_base_sha: cleanString(local.base_sha),
+    github_base_sha: cleanString(github.base_sha),
+    github_head_sha: cleanString(github.head_sha),
+    github_checks: normalizeIdentityChecks(github.checks),
+    skipped_checks: normalizeSkippedChecks(attempt?.skipped_checks),
+    pr_preparation: normalizePrPreparation(attempt?.pr_preparation),
+    verified_pr_preparation_refs: (attempt?.observed_evidence?.pr_preparation_refs || [])
+      .map((item) => ({
+        ref: cleanString(item?.ref),
+        verified: item?.verified === true,
+        kind: cleanString(item?.kind),
+        sha256: cleanString(item?.sha256),
+      }))
+      .sort((a, b) => a.ref.localeCompare(b.ref)),
+    minimum_matrix_sha256: cleanString(
+      attempt?.observed_evidence?.minimum_completion?.matrix_sha256,
+    ),
+  };
+  return createHash("sha256").update(stableStringify(payload)).digest("hex");
+}
+
+export function skippedChecksDisclosure(githubChecks, reportedChecks) {
+  const observed = (Array.isArray(githubChecks) ? githubChecks : [])
+    .filter((item) => item?.state === "skipped")
+    .map((item) => cleanString(item.name))
+    .filter(Boolean);
+  const reported = normalizeSkippedChecks(reportedChecks);
+  const missing = observed.filter((name) => !reported.some((item) =>
+    item.name === name && item.reason && item.impact
+  ));
+  return {
+    passed: missing.length === 0,
+    observed_count: observed.length,
+    missing_count: missing.length,
+    detail: missing.length === 0
+      ? observed.length > 0
+        ? `All ${observed.length} skipped check(s) include reason and impact disclosure.`
+        : "No skipped PR checks were observed."
+      : `${missing.length} skipped check(s) need reason and impact disclosure.`,
+  };
+}
+
+function check(id, label, passed, detail) {
+  return { id, label, passed: Boolean(passed), detail };
+}
+
+function record(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function normalizeCompanionRevisions(value) {
+  return (Array.isArray(value) ? value : []).map((item) => {
+    const source = record(item);
+    return {
+      repository: cleanString(source.repository),
+      sha: cleanString(source.sha),
+      evidence_ref: cleanString(source.evidence_ref),
+    };
+  }).filter((item) => item.repository || item.sha || item.evidence_ref);
+}
+
+function normalizeManifestRevisions(value) {
+  return (Array.isArray(value) ? value : []).map((item) => {
+    const source = record(item);
+    return {
+      manifest: cleanString(source.manifest),
+      sha256: cleanString(source.sha256),
+      evidence_ref: cleanString(source.evidence_ref),
+    };
+  }).filter((item) => item.manifest || item.sha256 || item.evidence_ref);
+}
+
+function normalizeSecurityPrivacyChecks(value) {
+  return (Array.isArray(value) ? value : []).map((item) => {
+    const source = record(item);
+    return {
+      boundary: cleanString(source.boundary),
+      result: cleanString(source.result),
+      evidence_ref: cleanString(source.evidence_ref),
+    };
+  }).filter((item) => item.boundary || item.result || item.evidence_ref);
+}
+
+function rowSpecificValidation(row, verifiedRefs) {
+  if (row.id === "exact_revision_integration") {
+    const companionsValid = row.companion_revisions.every(
+      (item) => item.repository && /^[a-f0-9]{40}$/i.test(item.sha) &&
+        item.evidence_ref && row.evidence_refs.includes(item.evidence_ref),
+    );
+    const manifestsValid = row.manifest_revisions.every(
+      (item) => item.manifest && /^[a-f0-9]{64}$/i.test(item.sha256) &&
+        item.evidence_ref && row.evidence_refs.includes(item.evidence_ref) &&
+        verifiedRefs.get(item.evidence_ref)?.sha256 === item.sha256.toLowerCase(),
+    );
+    const valid = row.companion_revisions.length + row.manifest_revisions.length > 0 &&
+      companionsValid && manifestsValid;
+    return { passed: valid, detail: "Exact-revision integration needs a companion repository/full commit SHA or manifest/SHA-256 with a matching evidence reference; use not_applicable when neither exists." };
+  }
+  if (row.id === "e2e_outcome_and_cleanup") {
+    return {
+      passed: row.cleanup_residual_count === 0,
+      detail: "E2E cleanup must report cleanup_residual_count=0.",
+    };
+  }
+  if (row.id === "security_and_privacy") {
+    return {
+      passed: row.security_privacy_checks.length > 0 && row.security_privacy_checks.every(
+        (item) => item.boundary && item.result === "passed" &&
+          item.evidence_ref && row.evidence_refs.includes(item.evidence_ref),
+      ),
+      detail: "Security/privacy proof must name the checked boundaries; use not_applicable only with verified boundary evidence.",
+    };
+  }
+  if (row.id === "ui_and_i18n") {
+    return {
+      passed: row.browser_artifacts.length > 0 && row.browser_artifacts.every((ref) =>
+        row.evidence_refs.includes(ref) && verifiedRefs.has(ref)
+      ) && row.locales_checked.length > 0 &&
+        row.console_error_count === 0 && row.network_failure_count === 0,
+      detail: "UI/i18n proof needs browser artifacts, checked locales, and zero console/network failures; use not_applicable for non-UI changes.",
+    };
+  }
+  if (row.id === "official_checklist_ownership") {
+    const levels = [...new Set(row.heading_levels_checked)].sort((a, b) => a - b);
+    return {
+      passed: levels.join(",") === "1,2,3,4,5,6" && row.leading_space_checked &&
+        row.trailing_hash_checked && row.single_official_checklist &&
+        row.unverified_model_output_labeled,
+      detail: "Checklist ownership proof must cover heading levels 1-6, leading spaces, trailing hashes, one controller-owned official table, and explicit labeling of model-generated lookalikes.",
+    };
+  }
+  if (row.id === "deployment_target_mapping") {
+    return {
+      passed: Boolean(
+        row.deployment_target && row.deployment_target_source &&
+        row.revision_observation_method &&
+        row.evidence_refs.includes(row.deployment_target_source) &&
+        verifiedRefs.has(row.deployment_target_source)
+      ),
+      detail: "Deployment mapping proof needs a target, a verified authoritative-source reference, and an exact-revision observation method.",
+    };
+  }
+  if (row.id === "live_data_safety") {
+    return {
+      passed: Boolean(row.live_write_policy && row.cleanup_residual_count === 0),
+      detail: "Live verification needs an explicit no-persistence, scoped-fixture, or authorized-production-write policy and cleanup_residual_count=0.",
+    };
+  }
+  if (row.id === "resume_compatibility") {
+    const paidSupportVerified = Boolean(
+      row.paid_resume_support && row.paid_resume_support_source &&
+      row.evidence_refs.includes(row.paid_resume_support_source) &&
+      verifiedRefs.has(row.paid_resume_support_source)
+    );
+    const paidPathSatisfied = row.paid_resume_support === "not_supported" ||
+      row.resume_paths_checked.includes("paid");
+    return {
+      passed: row.resume_paths_checked.includes("normal") &&
+        row.resume_paths_checked.includes("checkpoint") &&
+        paidSupportVerified && paidPathSatisfied &&
+        row.derived_views_recomputed && row.artifact_content_preserved,
+      detail: "Resume compatibility needs normal and checkpoint paths, a verified paid-resume support classification (and the paid path when supported), derived-view recomputation, and artifact-content preservation.",
+    };
+  }
+  return { passed: true, detail: "" };
+}
+
+function integerArray(value) {
+  return (Array.isArray(value) ? value : []).filter(Number.isInteger);
+}
+
+function normalizeLiveWritePolicy(value) {
+  const policy = cleanString(value);
+  return ["no_persistence", "scoped_fixture", "authorized_production_write"].includes(policy)
+    ? policy
+    : null;
+}
+
+function normalizePaidResumeSupport(value) {
+  const support = cleanString(value);
+  return ["supported", "not_supported"].includes(support) ? support : null;
+}
+
+function normalizeIdentityChecks(value) {
+  return (Array.isArray(value) ? value : []).map((item) => ({
+    name: cleanString(item?.name),
+    state: cleanString(item?.state),
+    status: cleanString(item?.status),
+    conclusion: cleanString(item?.conclusion),
+  })).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort().map((key) =>
+      `${JSON.stringify(key)}:${stableStringify(value[key])}`
+    ).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}

package/src/orchestrator/presentation.js

@@ -88,9 +88,9 @@ export function summarizeCodingLoopEvent(snapshot, event) {
       };
     case "pr_ready_for_review":
       return {
-        summary: "Implementation is complete, but the PR still needs human review or external evidence.",
+        summary: "The run is unfinished: required PR checks, review or evidence still need verification.",
         result: pendingReasons.length ? `Pending: ${pendingReasons.join("; ")}` : cleanString(event?.message),
-        next: "Review or approve the PR, then refresh its evidence from Web or CLI.",
+        next: "Continue authorized verification, resolve the listed pending gates, then refresh evidence from Web or CLI. Obtain human approval only where required.",
       };
     case "merge_ready":
       return {

package/src/orchestrator/result.js

@@ -1,8 +1,12 @@
 import { minimumCharterDigest } from "./minimum-completion.js";
-import { minimumContext } from "../codex-plugins/simy/skills/agentic-delivery-loop/scripts/check-minimum-completion.mjs";
-import { contextDigest } from "../codex-plugins/simy/skills/agentic-delivery-loop/scripts/check-acceptance.mjs";
+import { minimumContext } from "./delivery/scripts/check-minimum-completion.mjs";
+import { contextDigest } from "./delivery/scripts/check-acceptance.mjs";
 import { cleanString, stringArray } from "./shared.js";
 import { normalizeProblemSolving } from "./problem-solving.js";
+import {
+  normalizePrPreparation,
+  normalizeSkippedChecks,
+} from "./pr-preparation.js";
 import {
   normalizeCriterionEvidence,
   normalizeUncertaintyVerification,
@@ -43,6 +47,8 @@ export function buildAttempt({ attemptNumber, charter, instruction, promptInterv
     ),
     criterion_evidence: normalizeCriterionEvidence(result.criterion_evidence),
     visual_review: normalizeVisualReview(result.visual_review),
+    pr_preparation: normalizePrPreparation(result.pr_preparation),
+    skipped_checks: normalizeSkippedChecks(result.skipped_checks),
     prompt_interventions: promptInterventions,
     work_log_signals: [],
     work_log_interventions: [],

package/src/orchestrator/ux-specification.js

@@ -0,0 +1,20 @@
+import { fileURLToPath } from "node:url";
+import { section } from "./shared.js";
+
+export const UX_SPECIFICATION_PATH = fileURLToPath(
+  new URL("./delivery/references/ux-specification.md", import.meta.url),
+);
+
+export function buildUxSpecificationInstruction({ auditor = false } = {}) {
+  return section("ux_specification_contract", [
+    `Apply the same behavioral-completeness standard throughout requirements, design, implementation mapping, verification, review, release, closure and handoff. Read: ${UX_SPECIFICATION_PATH}`,
+    "Describe observable interaction units, not feature inventories. Reuse stable acceptance IDs. For each unit specify actor/goal, context/preconditions, trigger/reachable entry, perceived information, available action/choice/control, system response/state transition, usable outcome/postconditions, next action/handoff, alternative/failure/recovery paths, and verification oracle/provenance. Treat these as semantic obligations in the existing specification, not new CLI JSON fields.",
+    "Decompose when actor, precondition, decision, observable state, postcondition or recovery differs materially, or when any clause could fail independently. Link predecessors/successors and preserve end-to-end criteria. Derive branches and applicable constraints from authoritative requirements and observed system boundaries; do not invent scenarios, defaults, thresholds or product policy to fill gaps.",
+    "Description is sufficient only when another implementer can derive the intended behavior and an independent verifier can determine pass/fail without guessing a material requirement. Review source coverage, causal continuity, branch closure, controllability, observability, traceability, consistency and epistemic separation. Word count, row count and verbosity are not quality thresholds.",
+    "Keep required/intended/observed/assumed/unknown distinct. Unknown facts stay explicit with affected IDs and resolution evidence; a missing requirement decision blocks dependent design, while missing runtime evidence blocks the affected verification claim. Genuine non-applicability needs a source and reason, not an empty cell.",
+    "Persist the complete contract in the canonical specification and link the same IDs from summaries, matrices, PRs and receipts. Summaries may shorten repetition but must not replace or drop behavioral obligations, unresolved gaps or evidence. A phase change revalidates affected descriptions and results; plans never become observed proof by wording alone.",
+    auditor
+      ? "Remain read-only. Independently derive coverage from original sources, identify any material behavior that still requires guessing, and report affected criterion IDs and required clarification/evidence as findings. Do not infer completeness from filled fields or copied executor claims."
+      : "Before dependent implementation, resolve material specification ambiguity within authority or report needs_decision; continue independent work. Before verification or completion, repair missing descriptions/evidence rather than relabeling incomplete UX as complete. This procedural contract does not add automatic schema or GitHub enforcement.",
+  ].join("\n"));
+}