@awak-app/simy-cli 0.5.11 → 0.5.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awak-app/simy-cli",
-  "version": "0.5.11",
+  "version": "0.5.12",
   "description": "Local SIMY executor for non-coding Local Tasks and Agentic Loop runs.",
   "type": "module",
   "bin": {

package/src/cli-contract.js

@@ -13,7 +13,7 @@ import {
 } from "./durable-local-task-steps-contract.js";
 import { buildExecutionCapabilityContract } from "./execution-capability-contract.js";
 
-export const CLI_VERSION = "0.5.11";
+export const CLI_VERSION = "0.5.12";
 export const CLI_API_CONTRACT_VERSION = 10;
 
 export function withCliContract(

package/src/codex-plugins/simy/skills/agentic-delivery-loop/SKILL.md

@@ -33,9 +33,20 @@ external-message authority and never weakens repository-required gates.
 
 ## Freeze the delivery charter
 
+Start with the beneficiary's experience, not the proposed solution. Read-only
+discovery may supply facts, but before solution design or coding freeze a compact
+experience contract: who is in what situation, what they are trying to achieve,
+the complete usable outcome, what they should understand and do next at each
+observable moment, recovery and forbidden experiences, and how each moment will
+be observed. Give each moment a stable UX/acceptance ID and carry those same IDs
+through the shared To-Be, implementation mapping, and results matrix. Do not use
+a list of components, endpoints, screens, or tasks as a substitute for the
+end-to-end experience.
+
 Before material action, record:
 
-- objective and user-visible success conditions;
+- objective, beneficiary, and the frozen experience contract with user-visible
+  success conditions;
 - authoritative acceptance sources that are independent of the candidate
   implementation, plus architecture boundaries and dependency direction;
 - repositories, latest base branches, dedicated worktrees, environments, and
@@ -58,8 +69,9 @@ changes the requested result.
 
 Before implementation, read [shared system specifications](references/shared-system-specifications.md).
 Find the team's canonical specification for this system; create it once if absent.
-Record purpose, beneficiary, current pain, intended user experience and observable
-success. Reference the current As-Is revision and update only affected To-Be views.
+Reconcile the frozen experience contract with the current As-Is, then update only
+the affected To-Be views. Preserve the purpose, beneficiary, current pain,
+intended user experience, observable success, and stable UX/acceptance IDs.
 Maintain the twelve-view inventory, stable IDs and cross-view impact links in the
 shared source, not twelve new task-local copies. Unaffected views retain their
 version; unknown As-Is facts remain unknown. Review changes through the team's
@@ -84,6 +96,10 @@ that historical failures cannot recur.
 Before implementation, read [acceptance evidence](references/acceptance-evidence.md)
 and persist a criterion-by-criterion checklist. Bind the criteria and both
 verification layers to independent acceptance sources in a frozen charter.
+Use the experience contract as the user-facing slice of these same criteria, not
+as a parallel checklist. Every observable moment from the real trigger through a
+usable outcome and applicable recovery path must map to at least one criterion;
+working components do not prove that the combined experience is complete.
 Use a separate current-results matrix for observations, status, evidence,
 unmet reasons, and next actions. Render a readable table alongside the JSON;
 checklists held only in chat or the model's memory are insufficient.
@@ -100,6 +116,15 @@ values, ownership, authorization, and duplication. HTTP 500/network failures are
 failure evidence; absence of a 500 or presence of a 200 does not prove persistence.
 Record justified non-applicability before execution, not after a failed test.
 
+After building the exact candidate in the production-like local environment,
+execute the complete experience and regenerate the readable table. It must let a
+reviewer compare, for every stable ID, the persona/context and expected visible
+outcome, the actual user observation, the independent technical postcondition or
+integration result, evidence, status, and the next repair. Inspect the table as a
+whole to catch gaps between individually working parts. Any missing, pending,
+failed, stale, or unverifiable applicable experience row blocks
+`user_like_local_verified` and returns the loop to the smallest affected repair.
+
 Run the packaged acceptance validator before promoting a relevant verification
 gate and before issuing the completion receipt. A missing, pending, failed, stale,
 or unverifiable applicable row prevents promotion. Matrix completeness is one
@@ -114,7 +139,7 @@ For persistence, require reload/session return and stored values/ownership. A
 working control, success message or HTTP 200 alone is insufficient.
 
 The bundled minimum checker extends the acceptance matrix with structured
-observations. Compare the original request to the AC-N list independently so
+observations. Compare the original request to the stable criterion-ID list independently so
 omitted requirements cannot disappear before validation. A missing, failed or
 stale floor check prevents verified completion at any level. The CLI now enforces
 this before implementation/PR promotion and on recheck; the standalone command
@@ -301,6 +326,12 @@ the charter permits, then have Codex operate the user's Chrome through the
 browser extension as a normal user. Do not replace this gate with direct API
 calls or a fixed selector-only test.
 
+Immediately after the journey, refresh and inspect the experience/acceptance table
+for the same candidate revision, environment, fixture, and input. Compare the
+entire trigger-to-usable-outcome path, including what the user understands and can
+do next, with the frozen experience contract. Do not promote the local journey
+because its individual controls, requests, or services worked in isolation.
+
 Read [Codex Chrome user verification](references/chrome-user-verification.md)
 before running this phase.
 

package/src/codex-plugins/simy/skills/agentic-delivery-loop/references/acceptance-evidence.md

@@ -2,6 +2,14 @@
 
 ## Before implementation
 
+Freeze the user experience before proposing the solution. Read-only discovery may
+inform it, but the first authored success record states the beneficiary and
+context, their goal, the complete usable outcome, what they should see,
+understand, and be able to do next at each observable moment, applicable recovery
+and forbidden experiences, and how those moments will be observed. Assign stable
+UX/acceptance IDs. A screen, component, endpoint, task, or stored row is an
+implementation detail unless it is tied to this experience.
+
 The controller externalizes every acceptance condition with a stable ID, observable
 outcome, source independent of the candidate, and required checks. For each
 verification gate, freeze its applicable criteria in `charter.json` and record the
@@ -9,6 +17,13 @@ SHA-256 of the exact file bytes in the controller-owned snapshot. Reconcile the
 gate charters against the overall delivery charter so no requirement disappears.
 Do not choose a convenient subset after observing failures.
 
+Use these criteria as the structured form of the experience contract rather than
+creating a second UX checklist. Cover the full path from its real trigger to its
+usable outcome and the applicable recovery path. When several parts must work
+together for the beneficiary to succeed, include an end-to-end criterion in
+addition to narrower diagnostic criteria. Independent coverage review compares
+the experience contract and original request to the frozen rows before coding.
+
 Each criterion has two layers:
 
 - `user`: a goal-driven user journey with visible interactions and evidence of the
@@ -49,6 +64,15 @@ After every evaluated action (test, repair, review or changed inputs):
 All rows, including pending/failed ones, stay visible. A green matrix cannot advance
 an unrelated gate or prove merge/deployment. Validate again for the final environment.
 
+After the exact candidate is built in a production-like local environment, run
+the complete experience and regenerate `checklist.md` for that same revision,
+environment, fixture, and input. Read the user and system rows together as a
+single experience table: expected outcome, actual user observation, independent
+postcondition/integration result, evidence, status, and next repair. Missing,
+pending, failed, stale, or unverifiable applicable rows prevent
+`user_like_local_verified`. Individually working components cannot override a
+failed or absent end-to-end row.
+
 ## File contract
 
 Charter example (illustrative values must be replaced with actual requirements):
@@ -59,7 +83,7 @@ Charter example (illustrative values must be replaced with actual requirements):
   "run_id": "save-run-42",
   "criteria": [{
     "id": "SAVE-1",
-    "outcome": "The owner can recover the saved note after returning",
+    "outcome": "An owner returning to the task sees the saved note, understands it was retained, and can continue editing",
     "acceptance_source": "Approved issue acceptance criteria, revision 3",
     "layers": {
       "user": {"applicability": "required", "method": "Save in Chrome, reload, sign in again and compare the note"},

package/src/codex-plugins/simy/skills/agentic-delivery-loop/references/minimum-completion.md

@@ -9,19 +9,25 @@ in an executor result or assurance-level selection disables the gate.
 ## Collect real observations
 
 Before implementation, reconcile the original request, acceptance criteria and
-planned operations. Preserve every requested outcome; a missing requirement must
+planned operations against the frozen experience contract. Preserve every
+observable moment from the real trigger to a usable result, including applicable
+recovery and forbidden experiences; a missing requirement must
 be added through the controller's charter process, not omitted from the matrix.
 The independent auditor compares original-request coverage and checks the oracle
 against raw evidence. Machine mapping checks cannot discover an omitted idea in
 natural language or authenticate what an evidence collector observed.
 
-For each AC-N record implementation_refs (repository-relative file paths), then:
+For each stable criterion ID record implementation_refs (repository-relative file
+paths). New UX-first charters preserve the IDs supplied by the experience
+contract; legacy charters without explicit IDs retain deterministic `AC-N` IDs.
+Then:
 
 - user/operation: operate the actual UI or CLI/consumer. Expected is true; actual
   is whether the intended operation really executed, not just whether a click
   command succeeded. Include screenshots/traces where relevant.
 - user/result: observe the requested visible outcome, including reload and session
-  return for a saving feature. Compare expected and actual values.
+  return for a saving feature. Compare expected and actual values, user
+  understanding, and the next action the experience makes available.
 - system/postcondition: independently inspect the final state; for persistence,
   include the saved values and ownership, not a toast or HTTP status.
 - system/integration: inspect the necessary combined path through APIs, storage,
@@ -33,6 +39,8 @@ For document-only work these mean opening the actual consumer and checking conte
 links and packaged bytes. No DB/API is required if none participates. Both generic
 layers remain required; there is no post-failure waiver. Tests, permissions or
 runtime unavailable means pending/blocked. Never fabricate expected/actual equality.
+Passing narrower rows for controls, APIs, services, or artifacts cannot substitute
+for the end-to-end row when the requested experience depends on their combination.
 
 ## Executable contract
 
@@ -59,7 +67,8 @@ identities in the evidence; the independent reviewer must validate their current
 identity. Do not claim that this single-checkout gate automatically re-reads a
 companion service's Git HEAD or production environment.
 
-Every matrix row adds `implementation_refs: ["src/example.js"]`. Each required
+Every matrix row uses the same stable criterion ID and adds
+`implementation_refs: ["src/example.js"]`. Each required
 user/system cell's **first** evidence file is JSON with this shape (user example):
 
 ```json
@@ -128,7 +137,7 @@ external provider calls are introduced.
 
 ## Shared specifications and independent review
 
-The floor's AC-N rows trace back to stable requirement IDs in the team's shared
+The floor's stable criterion rows trace back to requirement IDs in the team's shared
 As-Is/To-Be specification. Follow [shared system specifications](shared-system-specifications.md)
 for purpose, user experience, cross-view consistency, independent reviews and
 pre/post-PR SQM. These are controller workflow obligations, not fields magically

package/src/codex-plugins/simy/skills/agentic-delivery-loop/references/shared-system-specifications.md

@@ -15,23 +15,36 @@ An old design or green PR is not proof of current production behavior.
 
 At the start of each run:
 
-1. Read the existing index and current linked views. Reconcile relevant As-Is with
+1. Freeze the experience contract from the original request before proposing a
+   solution: beneficiary/context, goal, complete usable outcome, observable
+   moments with what the person sees, understands, and can do next, recovery and
+   forbidden experiences, and the observation method. Read-only discovery may
+   inform this record. Give every moment a stable UX/acceptance ID.
+2. Read the existing index and current linked views. Reconcile relevant As-Is with
    code and actual behavior; label unknowns, cite evidence, and correct documented
    drift without claiming that the drift was part of the requested feature.
-2. State why the change matters: beneficiary, current difficulty, what they can
-   do after the change, observable success, and non-goals. Preserve the user's
-   original request as an independent acceptance source.
-3. Prepare a proposed To-Be on a branch/change proposal linked from the shared
+3. Reconcile why the change matters against that contract: current difficulty,
+   observable success, and non-goals. Preserve the user's original request as an
+   independent acceptance source; do not replace their outcome with a component
+   or implementation inventory.
+4. Prepare a proposed To-Be on a branch/change proposal linked from the shared
    system index. Record its baseline revision, affected stable IDs, before/after
    behavior, dependencies and acceptance oracles. Reuse unchanged views by reference;
    do not copy the whole specification into every run or generate empty diagrams.
-4. Link the requirement to workflow, screen/control, state/sequence, API/event,
+5. Link each experience ID to workflow, screen/control, state/sequence, API/event,
    data/relationship, permission and runtime boundaries as applicable. Map these
-   stable system IDs to the run's AC-N rows and implementation/evidence locations.
-5. Obtain independent design review before implementation. Supply the original
+   stable system IDs to the run's criterion rows and implementation/evidence locations.
+6. Obtain independent design review before implementation. Supply the original
    request, shared baseline, To-Be and linked unchanged views. Missing evidence or
    contradictory views remains pending/failed, never silently accepted.
 
+After the exact local candidate is built, update the existing acceptance matrix
+and its readable table for those same experience IDs. Compare expected experience,
+actual user observation, independent system result, evidence, status, and next
+repair across the whole journey. This is a view of the canonical acceptance data,
+not another specification. A gap between working parts blocks local user-journey
+promotion even if every part passed a narrower test.
+
 The twelve-view index must account for every category: present (with a canonical
 link), unchanged (with a revision), not applicable (with a reason), or unknown
 (with an owner/next action). Only create/update a diagram where it describes a

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

@@ -9,6 +9,8 @@ Persist one controller-owned snapshot with at least:
 
 - `run_id`, `state`, monotonic `revision`, and terminal disposition;
 - immutable explicit conditions and their stable digest;
+- frozen experience-contract identities, their mapping to acceptance rows, and
+  the current readable local-experience table path and digest;
 - acceptance-source identities and digests, architecture boundaries, applicable
   rule decisions, risk tier, requested/effective delivery levels, the safety
   ceiling reason, and chat-confirmation receipt;
@@ -156,5 +158,8 @@ with current context and the required user/system layers. After each evaluated
 action, refresh the JSON matrix and its readable table; append a receipt for the
 update. Keep the frozen charter distinct from mutable results. A charter patch
 supersedes the old digest only after the controller verifies its authority.
+For `user_like_local_verified`, the current table must cover the frozen experience
+contract from real trigger to usable outcome for the exact local candidate. A
+collection of narrower passing rows does not waive a missing end-to-end row.
 
 The CLI records minimum evidence in observed_evidence.minimum_completion, independently of executor status. The independent audit is bound to its matrix digest. Legacy v2 histories remain readable, but missing minimum evidence cannot be reused as passing evidence on resume/recheck. Missing or unsupported charters require a refresh; they do not disable verification.

package/src/codex-plugins/simy/skills/agentic-delivery-loop/scripts/check-acceptance.mjs

@@ -25,7 +25,15 @@ function requireValue(condition, message) {
 }
 
 function validateCharter(charter) {
-  requireValue(object(charter) && charter.schema_version === 1 && text(charter.run_id), "Invalid charter header");
+  requireValue(object(charter) && [1, 2].includes(charter.schema_version) && text(charter.run_id), "Invalid charter header");
+  if (charter.schema_version === 2) {
+    requireValue(object(charter.experience), "Experience contract required");
+    for (const field of ["beneficiary", "situation", "goal", "usable_outcome", "recovery"])
+      requireValue(text(charter.experience[field]), `Experience contract needs ${field}`);
+    requireValue(Array.isArray(charter.experience.forbidden_experiences) &&
+      charter.experience.forbidden_experiences.length > 0 &&
+      charter.experience.forbidden_experiences.every(text), "Experience contract needs forbidden experiences");
+  }
   requireValue(Array.isArray(charter.criteria) && charter.criteria.length > 0, "Charter requires criteria");
   const ids = new Set();
   for (const criterion of charter.criteria) {
@@ -88,15 +96,24 @@ export async function readEvidenceArtifact(root, artifact) {
 const tableText = (value) => String(value ?? "").replaceAll("|", "\\|").replace(/[\r\n]+/g, " ");
 
 export function renderChecklist(report) {
+  const experienceContext = report.experience
+    ? `${report.experience.beneficiary} / ${report.experience.situation}`
+    : "Legacy charter: persona and situation not recorded";
   const header = [
-    "| Criterion / outcome | Layer / method | Status | Observation | Evidence | Unmet reason / next action |",
-    "| --- | --- | --- | --- | --- | --- |",
+    "| Experience criterion / expected outcome | Persona / situation | Layer / method | Status | Actual observation | Evidence | Unmet reason / next repair |",
+    "| --- | --- | --- | --- | --- | --- | --- |",
   ];
   const rows = report.checks.map((row) => "| " + [
-    `${row.id}: ${row.outcome}`, `${row.layer}: ${row.method}`, row.status,
+    `${row.id}: ${row.outcome}`, experienceContext,
+    `${row.layer}: ${row.method}`, row.status,
     row.observation, row.evidence.join(", "), [row.reason, row.next_action].filter(Boolean).join(" / "),
   ].map(tableText).join(" | ") + " |");
+  const context = report.context;
+  const candidate = context
+    ? `Candidate context: stage=${tableText(context.stage)}; environment=${tableText(context.environment)}; fixture=${tableText(context.fixture_id)}; input_sha256=${tableText(context.input_sha256)}; source_revisions=${tableText(JSON.stringify(context.source_revisions))}`
+    : "Candidate context: unavailable";
   return [...header, ...rows, "", `Validator: ${report.status}`,
+    candidate,
     ...report.errors.map((error) => `- ${tableText(error)}`)].join("\n") + "\n";
 }
 
@@ -111,7 +128,8 @@ export async function checkAcceptance({ charterBytes, matrix, expectedCharterSha
   requireValue(contextDigest(matrix.context) === expectedContextSha256, "Current context digest mismatch");
   requireValue(Array.isArray(matrix.results), "Matrix requires results");
   const root = await realpath(evidenceRoot);
-  const report = { status: "evidence_incomplete", checks: [], errors: [] };
+  const report = { status: "evidence_incomplete", experience: charter.experience ?? null,
+    context: matrix.context, checks: [], errors: [] };
   const results = new Map();
   const expectedIds = new Set(charter.criteria.map((criterion) => criterion.id));
   for (const row of matrix.results) {

package/src/codex-plugins/simy/skills/agentic-delivery-loop/scripts/check-minimum-completion.mjs

@@ -35,13 +35,22 @@ export function minimumCharter(charter) {
       charter.completion_contract.minimum_scope || charter.acceptance_criteria,
     non_goals: charter.completion_contract.non_goals || [],
   };
+  const ids = criterionIds(
+    charter.completion_contract.criterion_ids,
+    charter.acceptance_criteria.length,
+  );
+  const experience = minimumExperience(
+    charter.completion_contract.experience,
+    charter.completion_contract.user_outcome || charter.requirement,
+  );
   return {
-    schema_version: 1,
+    schema_version: 2,
     minimum_completion_version: MINIMUM_COMPLETION_VERSION,
     run_id: charter.id,
     source,
+    experience,
     criteria: charter.acceptance_criteria.map((outcome, index) => ({
-      id: `AC-${index + 1}`,
+      id: ids[index],
       outcome,
       acceptance_source: `request:${contextDigest(source)}`,
       layers: {
@@ -60,6 +69,49 @@ export function minimumCharter(charter) {
   };
 }
 
+function criterionIds(value, count) {
+  if (value === undefined || value === null)
+    return Array.from({ length: count }, (_, index) => `AC-${index + 1}`);
+  if (!Array.isArray(value)) throw new Error("Invalid acceptance criterion IDs");
+  const ids = value.map((id) => (text(id) ? id.trim() : ""));
+  if (
+    ids.length !== count ||
+    new Set(ids).size !== ids.length ||
+    ids.some(
+      (id) => !/^[A-Za-z][A-Za-z0-9]*(?:[-_.][A-Za-z0-9]+)*$/.test(id),
+    )
+  )
+    throw new Error("Invalid acceptance criterion IDs");
+  return ids;
+}
+
+function minimumExperience(value, userOutcome) {
+  const source = object(value) ? value : {};
+  return {
+    beneficiary: text(source.beneficiary)
+      ? source.beneficiary.trim()
+      : "The requester",
+    situation: text(source.situation)
+      ? source.situation.trim()
+      : "Using the requested changed behavior",
+    goal: text(source.goal) ? source.goal.trim() : userOutcome,
+    usable_outcome: text(source.usable_outcome)
+      ? source.usable_outcome.trim()
+      : userOutcome,
+    recovery: text(source.recovery)
+      ? source.recovery.trim()
+      : "Unmet acceptance rows remain visible with the next repair.",
+    forbidden_experiences:
+      Array.isArray(source.forbidden_experiences) &&
+      source.forbidden_experiences.length > 0 &&
+      source.forbidden_experiences.every(text)
+        ? source.forbidden_experiences.map((item) => item.trim())
+        : [
+            "Reporting completion from components or commands without the end-to-end outcome",
+          ],
+  };
+}
+
 export function minimumContext(charter, headSha) {
   const frozen = minimumCharter(charter);
   return {

package/src/orchestrator/completion-contract.js

@@ -1,6 +1,7 @@
 import { cleanString, stringArray } from "./shared.js";
 
 export const COMPLETION_CONTRACT_VERSION = 2;
+const criterionIdPattern = /^[A-Za-z][A-Za-z0-9]*(?:[-_.][A-Za-z0-9]+)*$/;
 
 export function buildCompletionContract({
   inherited,
@@ -12,11 +13,15 @@ export function buildCompletionContract({
   const source = record(inherited);
   const minimumScope = stringArray(source.minimum_scope);
   const proofRequired = stringArray(source.proof_required);
+  const criteria = stringArray(acceptanceCriteria);
+  const userOutcome = cleanString(source.user_outcome) || cleanString(requirement);
   return {
     version: COMPLETION_CONTRACT_VERSION,
-    user_outcome: cleanString(source.user_outcome) || cleanString(requirement),
+    user_outcome: userOutcome,
     minimum_scope:
-      minimumScope.length > 0 ? minimumScope : stringArray(acceptanceCriteria),
+      minimumScope.length > 0 ? minimumScope : criteria,
+    criterion_ids: criterionIds(source.criterion_ids, criteria.length),
+    experience: normalizeExperience(source.experience, userOutcome),
     non_goals: stringArray(nonGoals),
     proof_required: uniqueStrings([
       "criterion_evidence",
@@ -29,12 +34,53 @@ export function buildCompletionContract({
 }
 
 export function acceptanceCriterionRows(charter) {
-  return stringArray(charter?.acceptance_criteria).map((statement, index) => ({
-    id: `AC-${index + 1}`,
+  const statements = stringArray(charter?.acceptance_criteria);
+  const ids = criterionIds(
+    record(charter?.completion_contract).criterion_ids,
+    statements.length,
+  );
+  return statements.map((statement, index) => ({
+    id: ids[index],
     statement,
   }));
 }
 
+function criterionIds(value, count) {
+  if (value === undefined || value === null) {
+    return Array.from({ length: count }, (_, index) => `AC-${index + 1}`);
+  }
+  if (!Array.isArray(value)) throw new Error("Invalid acceptance criterion IDs");
+  const ids = value.map(cleanString);
+  if (
+    ids.length !== count ||
+    new Set(ids).size !== ids.length ||
+    ids.some((id) => !criterionIdPattern.test(id))
+  ) {
+    throw new Error("Invalid acceptance criterion IDs");
+  }
+  return ids;
+}
+
+function normalizeExperience(value, userOutcome) {
+  const source = record(value);
+  return {
+    beneficiary: cleanString(source.beneficiary) || "The requester",
+    situation:
+      cleanString(source.situation) || "Using the requested changed behavior",
+    goal: cleanString(source.goal) || userOutcome,
+    usable_outcome: cleanString(source.usable_outcome) || userOutcome,
+    recovery:
+      cleanString(source.recovery) ||
+      "Unmet acceptance rows remain visible with the next repair.",
+    forbidden_experiences:
+      stringArray(source.forbidden_experiences).length > 0
+        ? stringArray(source.forbidden_experiences)
+        : [
+            "Reporting completion from components or commands without the end-to-end outcome",
+          ],
+  };
+}
+
 export function normalizeUncertaintyVerification(value) {
   const source = record(value);
   return {

package/src/orchestrator/contract.js

@@ -65,6 +65,7 @@ export function createCodingLoopSnapshot({ runId, request, metadata = {} }) {
   const inheritedArtifacts = stringArray(charterContext.artifacts_required);
   const inheritedAssumptions = stringArray(charterContext.assumptions);
   const inheritedCompletionContract = record(charterContext.completion_contract);
+  const inheritedExperienceContract = record(charterContext.experience_contract);
   const finalAcceptanceCriteria =
     acceptanceCriteria.length > 0
       ? acceptanceCriteria
@@ -157,7 +158,17 @@ export function createCodingLoopSnapshot({ runId, request, metadata = {} }) {
         visual_review_required: browserEvidenceRequired,
       },
       completion_contract: buildCompletionContract({
-        inherited: inheritedCompletionContract,
+        inherited: {
+          ...inheritedCompletionContract,
+          ...(Object.keys(inheritedExperienceContract).length > 0
+            ? {
+                experience: inheritedExperienceContract,
+                criterion_ids:
+                  inheritedExperienceContract.criterion_ids ??
+                  inheritedCompletionContract.criterion_ids,
+              }
+            : {}),
+        },
         requirement: cleanString(charterContext.user_goal) || cleanString(request.requirement),
         acceptanceCriteria: finalAcceptanceCriteria,
         nonGoals: finalNonGoals,

package/src/orchestrator/independent-audit.js

@@ -27,7 +27,8 @@ export function buildIndependentAuditInstruction(charter, attempt) {
       [
         `Requirement: ${charter.requirement}`,
         `Original request: ${charter.thread_state?.original_request || charter.requirement}`,
-        `Acceptance criteria:\n${bullets(charter.acceptance_criteria)}`,
+        `Acceptance criteria:\n${bullets(acceptanceCriterionRows(charter).map(row => `${row.id}: ${row.statement}`))}`,
+        `Frozen experience (controller-owned): ${JSON.stringify(charter.completion_contract?.experience ?? null)}`,
         `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}`,
@@ -62,8 +63,8 @@ export function buildIndependentAuditInstruction(charter, attempt) {
         "Inspect the final diff and related code directly from the repository.",
         "Look for unmet acceptance criteria, regressions, security issues, data and concurrency risks, missing tests, and unrelated changes.",
         "Treat executor claims as untrusted until supported by repository evidence.",
-        "Compare the original request to the complete AC-N list and implementation mapping. Report forgotten features, dead controls, unsaved results and broken integration. Open the raw minimum evidence, verify its oracle and actual runtime observations; matching expected/actual JSON and hashes alone do not prove truth. Check reload/session return and persisted values/ownership when saving is required.",
-        "For every AC-N criterion, return a criterion_results entry only after directly checking its cited proof and observed outcome.",
+        "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.",
         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.",
@@ -75,9 +76,9 @@ export function buildIndependentAuditInstruction(charter, attempt) {
       [
         "Finish with exactly one line beginning SIMY_AUDIT_JSON: followed by one JSON object.",
         "Required keys: passed, summary, findings, criterion_results, visual_review, coverage_review.",
-        "coverage_review must contain requirements_complete (boolean), unmapped_requirements (array), and observation explaining the comparison of the original request, AC-N list, implementation and raw user/system proof. Use false and list gaps when anything is missing or unverified.",
+        "coverage_review must contain requirements_complete (boolean), unmapped_requirements (array), and observation explaining the comparison of the original request, frozen experience, stable criterion-ID list, implementation and raw user/system proof. Use false and list gaps when anything is missing or unverified.",
         "Each finding candidate must contain passed, code, severity, target, explanation, and repairability.",
-        "criterion_results must contain one entry per AC-N with criterion_id, passed, verification_method, evidence_refs, and observed_result.",
+        "criterion_results must contain one entry per stable criterion ID 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.",

package/src/orchestrator/instruction.js

@@ -37,6 +37,12 @@ export function buildCodingInstruction(
       "completion_contract",
       [
         `User-visible outcome: ${charter.completion_contract?.user_outcome || charter.thread_state.user_goal}`,
+        `Beneficiary: ${charter.completion_contract?.experience?.beneficiary || "not recorded"}`,
+        `Situation: ${charter.completion_contract?.experience?.situation || "not recorded"}`,
+        `Experience goal: ${charter.completion_contract?.experience?.goal || "not recorded"}`,
+        `Usable outcome: ${charter.completion_contract?.experience?.usable_outcome || "not recorded"}`,
+        `Recovery experience: ${charter.completion_contract?.experience?.recovery || "not recorded"}`,
+        `Forbidden experiences:\n${bullets(charter.completion_contract?.experience?.forbidden_experiences || [])}`,
         `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 || [])}`,
@@ -52,10 +58,10 @@ export function buildCodingInstruction(
       ),
     ),
     section("minimum_completion_evidence", [
-      "All delivery levels require this floor. Before implementation reconcile every original requirement with the AC-N list; report omissions instead of silently dropping them.",
+      "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.",
-      "For each AC-N include real implementation_refs and required user/system evidence. Exercise the actual operation and result, then inspect postcondition and integration independently. For saving, reload/return in a new session and verify stored values and ownership. Document-only work uses the real command/consumer and artifact integrity, not imaginary API/DB checks.",
+      "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.",
       `Controller input JSON: ${JSON.stringify({ id: charter.id, requirement: charter.requirement, repository: charter.repository, acceptance_criteria: charter.acceptance_criteria, completion_contract: charter.completion_contract, thread_state: { original_request: charter.thread_state.original_request } })}`,
@@ -145,7 +151,7 @@ export function buildCodingInstruction(
         "Required keys: outcome_kind, summary, branch_name, commit_sha, commit_message_headline, pr_url, pr_number, pr_title, pr_base_branch, tests_run, tests_passed, ui_evidence_path, unrelated_changes_detected, secret_scan_passed, changed_files, residual_risks, problem_solving, uncertainty_verification, criterion_evidence, visual_review, delivery_evidence_path.",
         problemSolvingResultContract(),
         "uncertainty_verification must contain top_uncertainty, first_verification, evidence_checked, observed_result, resolved, and fallback. Only set resolved=true when concrete observed evidence resolves it.",
-        "criterion_evidence must contain one entry for every AC-N with criterion_id, passed, verification_method, evidence_refs, and observed_result. Only set passed=true when the evidence directly proves that criterion.",
+        "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.",
         "Use null for unavailable scalar values and [] for unavailable arrays. Do not claim evidence that was not observed.",
       ].join("\n"),

package/src/orchestrator/minimum-completion.js

@@ -69,7 +69,7 @@ export async function collectMinimumCompletion({
     return {
       status: "evidence_incomplete",
       errors: [
-        "Minimum completion evidence missing, invalid or stale; verify the actual operation, result, postcondition and integration for every AC-N.",
+        "Minimum completion evidence missing, invalid or stale; verify the actual operation, result, postcondition and integration for every stable criterion ID.",
       ],
     };
   }