@awak-app/simy-cli 0.5.15 → 0.5.17

package/src/orchestrator/delivery/references/pr-closure.md

@@ -0,0 +1,203 @@
+# PR closure: SIMY Web / CLI procedure
+
+This procedure is loaded by the Web/CLI executor and independent auditor through
+`src/orchestrator/pr-closure.js`. It is not a local Codex skill or a GitHub hook.
+It adds a closure safety gate to the existing delivery workflow, not a new remote
+mutation tool, permission or terminal state. Closing a PR never proves delivery.
+
+Flow: scope/authority -> original requirements and exact revisions -> before/after
+table -> real outcome verification -> independent review -> decision -> freshness
+and authority recheck -> authorized close -> remote read-back and durable receipt.
+When blocked, stop the close, not independent authorized investigation. Reuse the
+run's attempt/time/cost limits; do not repeat unchanged failed checks indefinitely.
+
+## 1. Define the scope and reason
+
+Record repository/PR, purpose, beneficiary, source requirements and non-goals.
+Distinguish merged, duplicate/fully superseded, transfer to unfinished work, and
+intentional cancellation/retirement. An already merged PR needs its actual merge
+identity verified, not a manual unmerged close. Merge is not deployment.
+
+An audit/table request is read-only. Record close and comment-posting authority
+separately; a factual same-PR comment must be covered by explicit authorization
+or governing policy. Otherwise prepare an unposted draft. Do not infer authority
+to merge successors, deploy, delete branches or reopen an already closed PR.
+An existing clear authorization need not be requested twice; a newly discovered
+loss of functionality requires an informed decision on that consequence.
+
+## 2. Freeze requirements and comparison identities
+
+Use original requests, acceptance criteria and approved decisions as the oracle,
+not the closing comment or candidate's own tests alone. Reuse stable acceptance
+IDs from the delivery charter. Independently reconcile the original sources with
+the ID list so an omitted requirement cannot disappear before validation.
+
+Record full old PR head and merge-base SHAs, current target base, successor and
+companion heads, exact integrated candidate, PR/merge state, build/runtime identity,
+flags, permissions/tenant, environment and observation time. Track deployed state
+separately; never infer it from a branch. Preserve a recoverable reference to
+unmerged source before cleanup. An SHA without retrievable objects is not backup.
+
+Keep requested, intended-in-code, observed-in-runtime, absent and unknown distinct.
+An unavailable old environment does not prove a feature never existed. Old missing
+code does not waive an explicit requirement, and labels do not prove old guarantees.
+
+## 3. Persist the before/after table
+
+Use [UX behavioral completeness](ux-specification.md) for both sides of the
+comparison. A concise table cell must link to the complete interaction contract;
+do not reduce the comparison to feature labels or omit divergent branches.
+
+Use the existing [acceptance evidence](acceptance-evidence.md) and stable IDs.
+Keep separate bound results for each context and link the comparison to them;
+do not overwrite base-only results with combined or live results. Persist outside
+chat and retain failed/pending rows. Minimum comparison columns:
+
+| ID / requirement source | Persona, condition, required outcome | Old PR intended / observed | Current base alone | Base + successors | Deployed target | Decision, gap, owner, remediation PR | Evidence |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| Stable criterion | Trigger, real entry, action, result, next action | Exact revision, evidence level | Exact revision, evidence level | Exact integrated identity | Observed identity or unknown | Retained / approved change / transferred / missing / unknown | Source locations, raw results, artifact hashes, times |
+
+For each affected journey cover real navigation, discoverability, first use and
+empty data, flags/roles/ownership; transferred input/context, confirmation, state
+changes, actual execution, usable output and next action; persistence, reload and
+session return, history/sync, privacy and data migration; loading, no-match,
+permission denial, error, cancellation and retry/recovery. Include accessibility
+and device variants when affected. Extra clicks or lost controls may be regressions
+even if an API is unchanged.
+
+For workflow products, separately account for existing-workflow reuse, composition,
+conversational design of a saved workflow, immediate ad-hoc work without saving a
+workflow, and background discovery/learning. Explicitly test the no-workflow or
+no-match branch: can the user ask for help, preserve intent, clarify/design/execute
+as required and obtain a usable result? A catalog recommender or background
+learning is not proof of conversational/ad-hoc fallback. Classify each capability
+against authoritative requirements; do not invent an old capability or silently
+exclude one because old code lacked it.
+
+Inventory every changed file, including deletions/renames, contracts, flags, tests
+and affected consumers outside the diff. Map each to criteria or a justified
+non-behavioral classification. Trace all requirements forward to proof, removed
+behavior back to retained behavior or approved retirement, and added permissions,
+data collection, automation, costs, defaults or steps back to authorized scope.
+Identical blobs, ancestry and file counts prove accounting, not UX equivalence.
+
+### Yellow/red rows must become remediation PR work
+
+Display unresolved partial/changed/unverified outcomes as yellow (🟡), and verified
+missing/regressed outcomes as red (❌). Keep factual behavior, evidence sufficiency
+and approved scope separate; uncertainty alone is not proof of a product defect.
+For every yellow/red row, create a new remediation PR for the required repair or
+verification within the active task's implementation/commit/push/PR authority.
+Group rows only when they form one coherent behavior change; do not mechanically
+create one PR per row or combine unrelated fixes. Use a Draft PR while unfinished.
+Before creation, check existing remediation PRs: reuse an exact open match with
+explicit criterion coverage rather than creating duplicate competing work. A broad
+successor link does not count without that mapping.
+
+Record criterion IDs, original PR, observed gap/evidence, required outcome, owner,
+repository/base, tests/E2E and acceptance gates in each remediation PR. Add its real
+URL and state to every covered table row; include dependencies and re-evaluation
+triggers. Evidence-only yellow rows need the missing verification, not speculative
+product changes. An unresolved product choice remains `needs_decision`; do not
+choose a new specification just to open a PR. If implementation or publication is
+unauthorized, blocked or outside the current budget, record a concrete PR plan and
+the missing decision/authority, but do not claim a PR exists. A plan/issue alone
+does not satisfy the requested PR handoff or justify `transfer_ready`.
+
+Independent review must reconcile all yellow/red IDs with the actual remediation
+PRs and explicitly named blockers before the original PR can be closed by transfer.
+Creating a PR is not fixing the issue: keep the row non-green until its required
+revision-bound checks pass. Approved changes/retirements may resolve a row only
+with the product decision and applicable safety evidence; preserve its history.
+
+## 4. Verify the actual consumer and independent postconditions
+
+Trace normal production entry -> caller -> UI/service -> backend -> persisted
+result -> next user action. Verify actual imports, routes, permissions and flags.
+A surviving component/API used only in fixtures is not a production experience.
+Test the unchanged old candidate where feasible, base alone and exact integrated
+candidate. Inspect the combined behavior, not just mergeability or individual CI.
+Reuse valid bound evidence; do not inflate counts with unnecessary reruns.
+
+For browser behavior, use [normal-user verification](chrome-user-verification.md)
+on the complete production-like stack with authorized services and safe fixtures.
+Capture meaningful visible states, errors and correlated technical postconditions
+for the same input/run. Mocked/component E2E, direct API calls and static analysis
+are supporting evidence, not substitutes. Only an exact-runtime live journey proves
+live inheritance. Do not imply that local or merged verification is deployed proof.
+For docs/CLI/library/API work use the actual artifact, command or downstream
+consumer; record why browser checks are inapplicable. Unavailable checks are pending,
+not inapplicable. Never make production writes solely to satisfy this procedure.
+
+Preserve initial failures. Classify product, environment and oracle failures with
+independent evidence. Changed assertions/fixtures create a different tested
+candidate and require independent oracle review; do not credit their passes to
+the unchanged original PR. A stale label alone does not explain a missing route.
+
+## 5. Independent review and decision
+
+Before the close action, a separate reviewer receives original requirements,
+candidate revisions, complete file inventory, table and raw artifacts, without
+a prescribed verdict. Review omissions, reachability, fallback, integrated results,
+unapproved scope and unfinished dependencies. Record identity-bound findings in
+the existing independent-review receipt. A comment claiming a review occurred is
+not review evidence. Repair only within authority; re-review changed inputs.
+The normal post-execution CLI audit is not a substitute for review before closing.
+
+Store these labels in the closure record, not in the delivery-state enum:
+
+| Decision | Required evidence and permitted action |
+| --- | --- |
+| `close_ready` | All requirements accounted for, candidate evidence and independent review pass; no hidden loss or pending implementation. State separately whether base-only or live. Deployment may remain an explicit delivery obligation. |
+| `transfer_ready` | Every pending outcome/risk has an accepted owner or authorized assignment, actual open remediation PR with criterion coverage, acceptance gate and re-evaluation trigger; explicit informed administrative-close authorization. No unmapped yellow/red row or unresolved handoff blocker. Not full inheritance/completed delivery. |
+| `retirement_ready` | Explicit product decision retires named outcomes; necessary user-data/migration/safety obligations verified or safely assigned before close. Not equivalence. |
+| `needs_decision` | Lost/changed outcome or trade-off lacks an authoritative human selection; present consequences/options and keep open. |
+| `blocked` | Missing/stale evidence, review, authority, classification or handoff, or unsafe consequence prevents the proposed action/claim. |
+
+Unknown/failed applicable rows cannot support `close_ready`. A deliberately
+authorized transfer keeps them non-green and visible. Verify the successor exists,
+is open and carries the actual pending criteria; a link alone is insufficient.
+Do not invent an owner's acceptance. Transfer cannot waive mandatory security,
+privacy, data-integrity or external-contract constraints. Retain the actual highest
+proven delivery state, independently of the closure-task disposition.
+
+## 6. Freshness check, authorized action and read-back
+
+Immediately before mutation refresh old head, target base, all successor heads and
+states, integrated identity, checks/review inputs, flags/environment and authority.
+Any changed bound input invalidates affected verification/review under
+[state and receipts](state-and-receipts.md). Inspect and reverify before continuing;
+checking only the old head is insufficient. Use conditional updates if available;
+otherwise read immediately before/after, record residual races and stop on drift.
+
+Prepare a factual explanation: reason, exact identities, comparison/evidence/review
+links, approved changes, pending obligations/owners, deployment status and recovery
+reference. Do not say nothing remains if work is unknown or unmerged. Missing close
+authority blocks closing; missing posting authority retains a draft. If policy
+requires a posted explanation, missing posting authority also blocks closing.
+
+After an authorized close, read back state, close/merge timestamps and identities,
+any authorized posted explanation, and successor status (open or demonstrably
+resolved). Reconcile ambiguous responses before retrying to avoid duplicate
+actions/comments. On unexpected concurrent changes, preserve evidence and report;
+do not silently reopen or declare success. Audit previously closed PRs read-only,
+separating the historical decision's evidence from today's state.
+
+## 7. Durable receipt and handoff
+
+Add a `closure` section to the existing completion/handoff evidence record, reusing
+its run/input digest, idempotency key and append-only rules. Record target/reason,
+decision, comparison/context digests, criterion/file coverage, all non-green rows,
+review and artifact references/hashes, human decisions and separate authorities,
+pre/post state/timestamps, mutation identity, comment ID/URL or unposted draft,
+pending owners/gates/triggers, yellow/red-ID-to-remediation-PR mappings and blocked
+PR plans, and source recovery references. Record unperformed
+actions as unperformed; reconcile retries with the same logical action identity.
+This documented section is not a new automatically validated CLI schema.
+
+Preserve the table, relevant raw proof, review and recoverable unmerged source in
+an approved durable location before deleting temporary worktrees. Verify links
+remain accessible and remove secrets/unrelated personal data. Never remove the
+only evidence/source copy. Administrative closure can finish a scoped closure task,
+not unfinished feature delivery. Promise ongoing monitoring only if authorized and
+actually configured; otherwise hand off to the recorded owner/tracking item.

package/src/{codex-plugins/simy/skills/agentic-delivery-loop → orchestrator/delivery}/references/state-and-receipts.md

@@ -14,7 +14,10 @@ Persist one controller-owned snapshot with at least:
 - acceptance-source identities and digests, architecture boundaries, applicable
   rule decisions, human-decision receipt IDs, approved canonical sources and
   their precedence and fallback semantics, risk tier, requested/effective
-  delivery levels, the safety ceiling reason, and chat-confirmation receipt;
+  delivery levels, numbering version, safety floor and reason, complete five-level
+  comparison with per-level hour estimates and assumptions, recommendation and
+  rationale, and chat-confirmation receipt; preserve legacy numbering and record
+  verified conversions separately rather than rewriting historical choices;
 - repository, base SHA, head SHA, companion SHAs, merge SHA, image digests, and
   deployed revision;
 - target environments, user journey, user/tenant fixture identities, and

package/src/orchestrator/delivery/references/ux-specification.md

@@ -0,0 +1,98 @@
+# UX specification: behavioral completeness
+
+Apply this standard to every UX description across the SIMY Web/CLI delivery loop:
+requirements, As-Is/To-Be, design, implementation mapping, acceptance criteria,
+verification records, reviews, release, before/after comparisons, closure and handoff.
+The quality target is **behavioral completeness and verifiability**, not prose length.
+Expand until no material user-observable behavior must be guessed; stop expanding
+when additional text only repeats or introduces unsupported scope.
+
+## Unit of description and decomposition
+
+An **observable interaction unit** describes one coherent transition from a stated
+user context to an observable outcome, including the user's control and the system's
+response. A feature name or a list of implementation components is not such a unit.
+Reuse stable UX/acceptance IDs and link finer units to their parent criterion. Do not
+create a second competing source of requirements or silently replace frozen IDs.
+
+Split a unit when the actor, prerequisite, choice, observable state, postcondition
+or recovery obligation differs materially. Also split independently falsifiable
+claims so a partial failure cannot hide inside a broadly passing row. Retain an
+end-to-end criterion joining the units: local completeness does not prove a usable
+journey. Derive the necessary granularity from actual requirements and system
+boundaries, never from a fixed number of screens, steps, rows or words.
+
+## Semantic obligations for every unit
+
+Each obligation must have explicit content, a precise reference to shared content,
+or an authoritative non-applicability reason. These are semantic requirements for
+the canonical specification, not additional mandatory fields in the CLI JSON schema.
+
+| Obligation | Required description |
+| --- | --- |
+| Actor and intent | Who acts or receives value, what they seek, and how the outcome serves that intent. |
+| Context and preconditions | Relevant prior state, available information, authority and constraints that determine whether and how the experience is possible. |
+| Trigger and reachability | What initiates the unit, how the actor reaches it, and which prerequisite or preceding unit supplies the entry state. |
+| Perception and comprehension | Information and feedback available to the actor, its timing and meaning, and how it communicates current state, consequences and what can happen next. Do not assert a mental state as observed without evidence. |
+| Action, choice and control | Permitted actions, required input, alternatives, decision ownership, confirmation and reversibility where applicable, with their consequences. |
+| System response and transition | Response to each relevant action or event, observable intermediate and terminal states, and applicable timing, ordering and consistency constraints. |
+| Usable outcome and postconditions | What the actor can actually use after the transition, affected state or effects, and the conditions that distinguish complete, partial and unsuccessful outcomes. |
+| Continuation and handoff | Next permitted action or terminal boundary, destination/owner and context retained across the transition. A handoff must identify its receiving preconditions. |
+| Alternatives, failure and recovery | Conditions producing materially different behavior, what the actor perceives, available recovery/control and retained or lost state. A terminal state must be intentional, not an unexplained dead end. |
+| Acceptance oracle and provenance | Requirement source, observable pass/fail predicates, observation method and evidence identity for the same actor/context/revision. Distinguish planned verification from its observed result. |
+
+Apply relevant usability, accessibility, privacy, authority and continuity constraints
+to these obligations where they change the experience. Express qualitative requirements
+as observable discriminators; use quantitative thresholds only when grounded in an
+authoritative requirement or an explicitly approved decision. Unspecified values or
+policy remain unknown; never invent them to make the description appear complete.
+
+## Completeness review criteria
+
+Use these criteria together, not an average score. A complete description satisfies
+every applicable criterion for its declared scope. A completed form is not proof.
+
+| Criterion | Pass condition |
+| --- | --- |
+| Source coverage | Every in-scope user outcome and constraint from the independent acceptance sources maps to identified units; every specified behavior maps back to a source or recorded authorized decision. |
+| Causal continuity | Entry and exit conditions connect across units without an unstated user step, system dependency or context transfer. The complete path reaches a usable outcome or an explicitly justified terminal state. |
+| Branch closure | Each material alternative derived from requirements and actual boundaries has a condition, observable response, consequence and continuation or recovery. Conditions distinguish which response applies. |
+| Control clarity | The actor can determine what they may do, what is automatic, who decides, and the consequences and available reversal of relevant actions. |
+| Observability and falsifiability | An independent verifier can distinguish success, partial success and failure using the stated oracle and evidence method, without inventing expected behavior. |
+| Cross-view consistency | Descriptions of the same intent agree on actors, prerequisites, transitions, authority, outcomes and recovery across all affected surfaces and specification views, or cite an approved difference. |
+| Traceability and freshness | Stable IDs connect source, specification, implementation, checks, observations and unresolved obligations; referenced revisions and context match the claim. |
+| Epistemic separation | Requirements, intentions, observations, assumptions and unknowns are separately identified; lack of evidence is not presented as absence, success or non-applicability. |
+
+Perform an **independent reconstruction check**: a reader who did not author the
+implementation must be able to derive the intended interaction and its acceptance
+checks without supplying a material product decision. Review against original
+sources as well as the described units, so omitted behavior cannot pass unnoticed.
+Return gaps by criterion ID, missing obligation, consequence, authoritative question
+or evidence needed, and dependent phase. Do not claim exhaustive coverage beyond
+the declared scope and available sources; disclose unavailable sources and risks.
+
+## Application through the lifecycle
+
+| Phase | Required use of the same contract |
+| --- | --- |
+| Discovery and charter | Record known As-Is observations separately from requested outcomes and unknowns; derive coverage and freeze intended behavior before solution-dependent decisions. |
+| Design and implementation | Maintain the source-linked To-Be units and map their obligations to affected paths; inspect dependencies and consistency, without weakening the contract to fit candidate code. |
+| Verification and review | Observe the complete applicable paths and independent postconditions in the same bound context; compare expected and observed behavior unit by unit and end to end. |
+| Repair and scope change | Preserve failed results, record authorized requirement changes and invalidate only affected descriptions/evidence; re-review dependent units and their connected paths. |
+| Release and operation | Identify the target runtime and applicable outcome/guardrail observations; distinguish expected exposure, observed behavior and unresolved operational obligations. |
+| PR closure and handoff | Compare before/after using the same units, retain reachability and recovery detail, map unresolved obligations to authorized remediation work and preserve evidence and ownership. |
+
+Persist complete descriptions in the canonical specification and reference their IDs
+from matrices, PRs and receipts. Compact user-facing summaries may omit repetition,
+not material behavior, uncertainty or the link to the full contract. Do not impose
+long transcripts or duplicate the full specification in each progress update.
+
+Unknowns are visible work, not a reason to fabricate detail. A material unresolved
+requirement decision blocks dependent design/implementation; a missing runtime
+observation blocks the affected verification or equivalence claim. Discovery and
+independent authorized work may continue. Explicit assumptions retain their source,
+risk and resolution condition; assumption-based behavior cannot be presented as
+verified. Genuine non-applicability needs a reason/source before execution, not a
+post-failure waiver. This is a workflow and independent-review standard; existing
+validators check their documented evidence contracts, not these semantic criteria
+automatically. Do not claim machine enforcement merely because this guide is loaded.

package/src/{codex-plugins/simy/skills/agentic-delivery-loop → orchestrator/delivery}/scripts/production-contract.mjs

@@ -1,4 +1,4 @@
-// Shared by the CLI and the independently installed skill. Keep this module
+// Shared by the CLI and the packaged evidence checker. Keep this module
 // self-contained so validation never depends on the repository checkout.
 const cleanString = value => typeof value === "string" ? value.trim() : "";
 const record = value => value && typeof value === "object" && !Array.isArray(value) ? value : {};

package/src/orchestrator/delivery-level.js

@@ -0,0 +1,19 @@
+import { fileURLToPath } from "node:url";
+import { section } from "./shared.js";
+
+export const DELIVERY_LEVELS_PATH = fileURLToPath(
+  new URL("./delivery/references/delivery-levels.md", import.meta.url),
+);
+
+export function buildDeliveryLevelInstruction({ auditor = false } = {}) {
+  return section("delivery_level_contract", [
+    `Read the Web/CLI delivery-level contract: ${DELIVERY_LEVELS_PATH}`,
+    "Use assurance-ascending-v2: 5 is maximum assurance, 4 protected, 3 balanced, 2 fast, 1 lightest. Higher numbers mean more assurance, not greater task priority. Apply the highest applicable risk/policy floor; never lower mandatory verification or expand authority.",
+    "Whenever recommending, confirming or changing a level, present ALL five levels in descending order 5, 4, 3, 2, 1, as a table or clearly separated prose. For EACH show content, verification/review scope, trade-off, task applicability, and task-specific duration in hours. Mark the recommendation and explain its task/risk rationale, even when the user already selected a level; acknowledge a valid selection without asking again. Mark unsafe levels unavailable with reasons; do not hide them.",
+    "Estimate numeric lower-to-upper execution and elapsed-hour ranges for the same task scope and endpoint, using observed boundaries, implementation, checks, review, setup, repair and dependency critical path. Separate execution from CI/queue/approval/external waiting; account for parallelism. State assumptions, evidence, uncertainty and confidence. Do not hardcode per-level durations or product examples. Unknown external wait stays explicitly unbounded, with a conditional numeric execution range; never invent a finite total. If execution cannot yet be estimated, show the missing input and discovery step for each affected row and keep the selection packet incomplete pending a defensible range. Explain overlaps or inversions; estimates are not guarantees or permission to skip work.",
+    "Record the comparison, estimate basis, recommendation/reason, requested/effective level, numbering version, risk floor and user selection reference in existing charter/decision evidence, not invented CLI API fields. Refresh on material changes. Preserve historical receipts: map verified legacy levels 1→5, 2→4, 3→3, 4→2, 5→1 without changing assurance; clarify ambiguous unversioned selections rather than guessing.",
+    auditor
+      ? "Remain read-only. Check the actual user-facing comparison and selection evidence, not only this instruction. Report missing levels, scope, estimates, rationale, unsafe effective levels, or ambiguous legacy numbering as findings. This is procedural guidance, not a new deterministic selection validator."
+      : "Before material implementation ensure a valid selection and complete comparison are available. Read-only discovery may continue while unresolved; do not substitute a recommendation-only message. This is procedural guidance, not a new deterministic selection validator.",
+  ].join("\n"));
+}

package/src/orchestrator/evidence.js

@@ -1,11 +1,14 @@
 import { collectMinimumCompletion } from "./minimum-completion.js";
 import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { lstat, readFile, realpath } from "node:fs/promises";
+import path from "node:path";
 import { promisify } from "node:util";
 
 import { cleanString, stringArray } from "./shared.js";
 
 const execFileAsync = promisify(execFile);
-const SUCCESS_CONCLUSIONS = new Set(["SUCCESS", "NEUTRAL", "SKIPPED"]);
+const SUCCESS_CONCLUSIONS = new Set(["SUCCESS", "NEUTRAL"]);
 const FAILURE_CONCLUSIONS = new Set([
   "ACTION_REQUIRED",
   "CANCELLED",
@@ -20,14 +23,25 @@ export async function collectPrEvidence({
   repositoryPath,
   runCommand = execFileAsync,
 }) {
+  const baseRefresh = await command(
+    runCommand,
+    "git",
+    ["fetch", "--no-tags", "origin", charter.base_branch],
+    repositoryPath,
+  );
   const local = await collectLocalGitEvidence({
     baseBranch: charter.base_branch,
     repositoryPath,
     runCommand,
   });
+  local.base_ref_refreshed = baseRefresh.ok;
+  local.base_ref_error = baseRefresh.ok ? null : baseRefresh.error;
   const github = await collectGitHubEvidence({ charter, attempt, repositoryPath, runCommand });
   const minimumCompletion = await collectMinimumCompletion({ charter, attempt, repositoryPath, local });
+  const prPreparationRefs = await verifyPrPreparationRefs({ attempt, repositoryPath, local, github });
   const latest = await collectLocalGitEvidence({ baseBranch: charter.base_branch, repositoryPath, runCommand });
+  latest.base_ref_refreshed = baseRefresh.ok;
+  latest.base_ref_error = baseRefresh.ok ? null : baseRefresh.error;
   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."];
@@ -37,27 +51,69 @@ export async function collectPrEvidence({
     collected_at: new Date().toISOString(),
     local: latest,
     github,
+    pr_preparation_refs: prPreparationRefs,
+  };
+}
+
+async function verifyPrPreparationRefs({ attempt, repositoryPath, local, github }) {
+  const refs = [...new Set((attempt.pr_preparation || []).flatMap((row) => row.evidence_refs || []))];
+  return Promise.all(refs.map(async (ref) => {
+    const observed = observedEvidenceRef(ref, local, github);
+    if (observed !== null) return { ref, verified: observed, kind: "observed" };
+    try {
+      const root = await realpath(repositoryPath);
+      const target = await realpath(path.resolve(root, ref));
+      const relative = path.relative(root, target);
+      const details = await lstat(target);
+      const verified = !relative.startsWith("..") && !path.isAbsolute(relative) &&
+        details.isFile() && details.size <= 50 * 1024 * 1024;
+      const sha256 = verified
+        ? createHash("sha256").update(await readFile(target)).digest("hex")
+        : null;
+      return { ref, verified, kind: "local_file", sha256 };
+    } catch {
+      return { ref, verified: false, kind: "unverified" };
+    }
+  }));
+}
+
+function observedEvidenceRef(ref, local, github) {
+  const sources = {
+    "observed:local.head_sha": local.head_sha,
+    "observed:local.base_sha": local.base_sha,
+    "observed:local.base_is_ancestor": local.base_is_ancestor === true,
+    "observed:github.head_sha": github.head_sha,
+    "observed:github.base_sha": github.base_sha,
+    "observed:github.checks": Array.isArray(github.checks) && github.checks.length > 0,
   };
+  return Object.hasOwn(sources, ref) ? Boolean(sources[ref]) : null;
 }
 
 async function collectLocalGitEvidence({ baseBranch, repositoryPath, runCommand }) {
-  const [head, branch, headline, status, changed] = await Promise.all([
+  const baseRef = `origin/${baseBranch}`;
+  const [head, branch, headline, status, changed, base, mergeBase, baseAncestor] = await Promise.all([
     command(runCommand, "git", ["rev-parse", "HEAD"], repositoryPath),
     command(runCommand, "git", ["branch", "--show-current"], repositoryPath),
     command(runCommand, "git", ["log", "-1", "--pretty=%s"], repositoryPath),
     command(runCommand, "git", ["status", "--porcelain"], repositoryPath),
     changedFiles(runCommand, baseBranch, repositoryPath),
+    command(runCommand, "git", ["rev-parse", baseRef], repositoryPath),
+    command(runCommand, "git", ["merge-base", baseRef, "HEAD"], repositoryPath),
+    command(runCommand, "git", ["merge-base", "--is-ancestor", baseRef, "HEAD"], repositoryPath),
   ]);
   const statusLines = lines(status.stdout);
   return {
-    available: head.ok && branch.ok && headline.ok && status.ok && changed.ok,
+    available: head.ok && branch.ok && headline.ok && status.ok && changed.ok && base.ok && mergeBase.ok,
     head_sha: cleanString(head.stdout) || null,
     branch_name: cleanString(branch.stdout) || null,
     commit_headline: cleanString(headline.stdout) || null,
     working_tree_clean: status.ok && statusLines.length === 0,
     status_lines: statusLines,
     changed_files: lines(changed.stdout),
-    errors: [head, branch, headline, status, changed]
+    base_sha: cleanString(base.stdout) || null,
+    merge_base_sha: cleanString(mergeBase.stdout) || null,
+    base_is_ancestor: baseAncestor.ok,
+    errors: [head, branch, headline, status, changed, base, mergeBase]
       .filter((item) => !item.ok)
       .map((item) => item.error),
   };
@@ -93,6 +149,7 @@ async function collectGitHubEvidence({ charter, attempt, repositoryPath, runComm
     "headRepository",
     "headRepositoryOwner",
     "baseRefName",
+    "baseRefOid",
     "reviews",
     "statusCheckRollup",
   ].join(",");
@@ -137,10 +194,11 @@ async function collectGitHubEvidence({ charter, attempt, repositoryPath, runComm
         ? `${cleanString(payload.headRepositoryOwner.login)}/${cleanString(payload.headRepository.name)}`
         : null,
     base_branch: cleanString(payload.baseRefName) || null,
+    base_sha: cleanString(payload.baseRefOid) || null,
     checks,
     checks_present: checks.length > 0,
     checks_passing:
-      checks.length > 0 && checks.every((item) => item.state === "success"),
+      checks.length > 0 && checks.every((item) => ["success", "skipped"].includes(item.state)),
     required_checks_present: requiredChecks.every((name) => checkNames.has(name)),
     error: null,
   };
@@ -154,6 +212,7 @@ function normalizeChecks(value) {
     const conclusion = cleanString(item?.conclusion || item?.state).toUpperCase();
     let state = "pending";
     if (SUCCESS_CONCLUSIONS.has(conclusion)) state = "success";
+    if (conclusion === "SKIPPED") state = "skipped";
     if (FAILURE_CONCLUSIONS.has(conclusion)) state = "failure";
     if (status === "COMPLETED" && !conclusion) state = "failure";
     return { name, status: status || null, conclusion: conclusion || null, state };

package/src/orchestrator/independent-audit.js

@@ -1,10 +1,15 @@
 import { bullets, cleanString, section } from "./shared.js";
+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 {
   COMPLETION_CONTRACT_VERSION,
   acceptanceCriterionRows,
   normalizeCriterionEvidence,
   normalizeVisualReview,
 } from "./completion-contract.js";
+import { independentAuditEvidenceIdentity } from "./pr-preparation.js";
 
 export function buildIndependentAuditInstruction(charter, attempt) {
   const localEvidence = attempt.observed_evidence?.local || {};
@@ -18,6 +23,10 @@ export function buildIndependentAuditInstruction(charter, attempt) {
     : [];
 
   return [
+    buildUxSpecificationInstruction({ auditor: true }),
+    buildDeliveryLevelInstruction({ auditor: true }),
+    buildChecklistContinuationInstruction({ auditor: true }),
+    buildPrClosureInstruction({ auditor: true }),
     section(
       "role",
       "You are an independent PR auditor. You did not implement this change and must not edit files.",
@@ -47,9 +56,14 @@ export function buildIndependentAuditInstruction(charter, attempt) {
         `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"}`,
+        `Complete audit evidence identity: ${independentAuditEvidenceIdentity(attempt)}`,
         `Executor visual review: ${JSON.stringify(attempt.visual_review || {})}`,
+        `Executor PR preparation evidence: ${JSON.stringify(attempt.pr_preparation || [])}`,
+        `Executor skipped-check disclosures: ${JSON.stringify(attempt.skipped_checks || [])}`,
         `Observed local branch: ${localEvidence.branch_name || "unknown"}`,
         `Observed local HEAD: ${localEvidence.head_sha || "unknown"}`,
+        `Observed fetched base SHA: ${localEvidence.base_sha || "unknown"}`,
+        `Observed base ancestry: ${localEvidence.base_is_ancestor === true ? "integrated" : "not integrated or unknown"}`,
         `Observed changed files:\n${bullets(localEvidence.changed_files || [])}`,
         `Observed PR: ${githubEvidence.url || attempt.pr_url || "unknown"}`,
         `Observed passing GitHub checks:\n${bullets(passingChecks)}`,
@@ -63,6 +77,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.",
+        "Inspect every structured PR preparation row. Confirm required rows are bound to the current head and raw evidence; confirm not-applicable rows have a genuine boundary reason and authoritative source. Check exact companion/manifest revisions, scenario outcomes, cleanup residual count, telemetry redaction, locale/browser evidence, and residual-work disclosure where applicable.",
+        "For conditional safeguards, inspect the actual changed boundary: checklist rendering must resist H1-H6, leading-space, and trailing-hash lookalikes while keeping one official controller table; release work must derive its target from authoritative topology and define exact-revision observation; live verification must declare its write policy and prove residual test data zero; loop-state/rendering changes must preserve artifacts and recompute derived views across normal/checkpoint and supported paid resumes.",
+        "Confirm the remote base was freshly read, is an ancestor of the final head, and matches the PR base SHA. Treat DIRTY/BEHIND, stale companion SHAs, changed manifests, or conflict resolution without rerun evidence as blockers.",
+        "Inspect skipped GitHub checks independently. A documented skip may be legitimate, but it must not be represented as an executed full/live/E2E result.",
         "Compare the original request and frozen experience to the complete stable criterion-ID 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 stable criterion ID, return a criterion_results entry only after directly checking its cited proof and observed outcome.",
         "For production-relevant criteria, verify that each outcome and guardrail measure names its signal, independent source, observation window, threshold, decision, owner, and criterion ID.",

package/src/orchestrator/index.js

@@ -4,3 +4,10 @@ export { buildIndependentAuditInstruction } from "./independent-audit.js";
 export { recheckPrReadiness, runCodingLoop } from "./loop.js";
 export { mergeTokenUsage, parseStructuredMarker, parseStructuredResult } from "./result.js";
 export { buildRetryFingerprint, evaluateRetryCircuit } from "./retry.js";
+export {
+  PR_PREPARATION_CHECKS,
+  defaultPrPreparationContract,
+  evaluatePrPreparation,
+  independentAuditEvidenceIdentity,
+  skippedChecksDisclosure,
+} from "./pr-preparation.js";