@awak-app/simy-cli 0.5.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awak-app/simy-cli",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Local SIMY executor for non-coding Local Tasks and Agentic Loop runs.",
   "type": "module",
   "bin": {
@@ -15,6 +15,7 @@
     "test": "node --test",
     "test:e2e:console": "node ./scripts/console-e2e.js",
     "test:e2e:sqm-complete-loop": "node ./scripts/sqm-complete-loop-e2e.js",
+    "test:e2e:sqm-local-review": "node ./scripts/sqm-local-review-e2e.js",
     "test:e2e:console:narrow": "CLI_E2E_COLUMNS=78 CLI_E2E_ROWS=40 node ./scripts/console-e2e.js",
     "test:e2e:console:no-color": "CLI_E2E_NO_COLOR=1 node ./scripts/console-e2e.js",
     "test:e2e:console:recovery": "node ./scripts/console-recovery-e2e.js",
@@ -37,7 +38,7 @@
     "test:e2e:console:fullstack": "node ./scripts/fullstack-cli-smoke.js",
     "check": "npm run check:auto-update && node --check ./src/desktop-executor.js && node --check ./src/local-task.js && node --check ./scripts/desktop-executor-e2e.js && node --check ./scripts/pre-guardrail-e2e.js && node --check ./scripts/fixtures/fake-desktop-provider.js && npm run check:syntax && npm run check:real-provider-syntax && npm test && npm run check:package",
     "check:auto-update": "node --check ./src/auto-update.js && node --check ./scripts/auto-update-e2e.js && npm run check:sqm",
-    "check:sqm": "node --check ./src/sqm/canonical.js && node --check ./src/sqm/validation.js && node --check ./src/sqm/repository.js && node --check ./src/sqm/checkers.js && node --check ./src/sqm/bundle-store.js && node --check ./src/sqm/proof.js && node --check ./src/sqm/evidence-client.js && node --check ./src/sqm/session.js && node --check ./src/sqm/index.js && node --check ./src/sqm/command.js && node --check ./scripts/sqm-complete-loop-e2e.js",
+    "check:sqm": "node --check ./src/sqm/canonical.js && node --check ./src/sqm/validation.js && node --check ./src/sqm/repository.js && node --check ./src/sqm/checkers.js && node --check ./src/sqm/bundle-store.js && node --check ./src/sqm/proof.js && node --check ./src/sqm/evidence-client.js && node --check ./src/sqm/session.js && node --check ./src/sqm/index.js && node --check ./src/sqm/command.js && node --check ./src/sqm/agent-skill.js && node --check ./src/sqm/review-worker.js && node --check ./scripts/sqm-complete-loop-e2e.js && node --check ./scripts/sqm-local-review-e2e.js",
     "check:real-provider-syntax": "node --check ./scripts/real-codex-probe.js && node --check ./scripts/real-claude-probe.js && node --check ./scripts/real-provider-console-fixture.js && node --check ./scripts/real-provider-console-e2e.js",
     "check:syntax": "node --check ./src/index.js && node --check ./src/agent.js && node --check ./src/browser.js && node --check ./src/web-api.js && node --check ./src/durable-local-task-worker.js && node --check ./src/durable-local-task-steps-contract.js && node --check ./src/bounded-local-task-subtasks-contract.js && node --check ./src/bounded-local-task-subtask-pool.js && node --check ./src/local-task-artifact-contract.js && node --check ./src/execution-capability-contract.js && node --check ./src/shutdown.js && node --check ./src/run-registry.js && node --check ./src/direct-executor.js && node --check ./src/execution-guardrail.js && node --check ./src/backend-executable.js && node --check ./src/provider-stream.js && node --check ./src/console/index.js && node --check ./src/console/app.js && node --check ./src/console/commands.js && node --check ./src/local-attachments.js && node --check ./src/repository-inventory.js && node --check ./src/session-store.js && node --check ./src/web-origin.js && node --check ./src/workspace-context.js && node --check ./src/orchestrator/index.js && node --check ./src/orchestrator/shared.js && node --check ./src/orchestrator/recovery.js && node --check ./src/orchestrator/risk.js && node --check ./src/orchestrator/contract.js && node --check ./src/orchestrator/completion-contract.js && node --check ./src/orchestrator/instruction.js && node --check ./src/orchestrator/problem-solving.js && node --check ./src/orchestrator/budget.js && node --check ./src/orchestrator/execution-io.js && node --check ./src/orchestrator/presentation.js && node --check ./src/orchestrator/result.js && node --check ./src/orchestrator/retry.js && node --check ./src/orchestrator/evidence.js && node --check ./src/orchestrator/independent-audit.js && node --check ./src/orchestrator/audit.js && node --check ./src/orchestrator/loop.js && node --check ./src/runner.js && node --check ./scripts/fixtures/completion-contract-fixture.js && node --check ./scripts/fixtures/fake-coding-backend.js && node --check ./scripts/e2e-terminal-evidence.js && node --check ./scripts/audit-gate-e2e.js && node --check ./scripts/completion-contract-e2e.js && node --check ./scripts/retry-circuit-e2e.js && node --check ./scripts/follow-up-charter-e2e.js && node --check ./scripts/task-routing-e2e.js && node --check ./scripts/executor-version-preflight-e2e.js && node --check ./scripts/blocked-recovery-e2e.js && node --check ./scripts/process-localization-e2e.js && node --check ./scripts/hypothesis-retries-e2e.js && node --check ./scripts/budget-enforcement-e2e.js && node --check ./scripts/local-task-default-workspace-e2e.js && node --check ./scripts/local-task-idempotency-e2e.js && node --check ./scripts/console-e2e-fixture.js && node --check ./scripts/console-e2e.js && node --check ./scripts/console-recovery-e2e-fixture.js && node --check ./scripts/console-recovery-e2e.js && node --check ./scripts/real-provider-console-fixture.js && node --check ./scripts/real-provider-console-e2e.js && node --check ./scripts/fullstack-cli-smoke.js && node --check ./scripts/check-package-contents.js",
     "check:package": "node ./scripts/check-package-contents.js"

package/src/agent.js

@@ -115,6 +115,11 @@ import {
   normalizeLocalTaskScenarioPack,
   validateLocalTaskScenarioInputs,
 } from "./local-task-scenario-packs.js";
+import { inspectSqmAgentSkill, installSqmAgentSkill } from "./sqm/agent-skill.js";
+import {
+  createSqmLocalReviewApi,
+  createSqmLocalReviewWorker,
+} from "./sqm/review-worker.js";
 
 const DEVICE_HEARTBEAT_INTERVAL_MS = 20_000;
 
@@ -143,6 +148,10 @@ export async function startAgent({
     });
   await localTaskAttachmentStore.cleanupExpired?.();
   const authNonce = randomBytes(16).toString("base64url");
+  const sqmAgentIntegration = dependencies.sqmAgentIntegration || {
+    inspect: () => inspectSqmAgentSkill({ home: dependencies.home }),
+    install: (options) => installSqmAgentSkill({ home: dependencies.home, ...options }),
+  };
   let session = await readSession(apiOrigin, sessionRoot);
   if (session && sessionRequiresWebAuthorization(session, apiOrigin)) session = null;
   await cleanupExpiredRuns();
@@ -168,23 +177,39 @@ export async function startAgent({
   );
   const installMode = updateManager?.snapshot?.()?.install_mode ?? null;
   const inspectedCapabilities = await readCapabilities(dependencies);
+  const durableControlPlane =
+    inspectedCapabilities?.features?.local_task_control_plane === true;
+  const hasSqmLocalReview = Object.hasOwn(
+    inspectedCapabilities?.features || {},
+    "sqm_local_review",
+  );
   const contractSourceCapabilities =
-    inspectedCapabilities?.features?.local_task_control_plane === true
+    durableControlPlane || hasSqmLocalReview
       ? {
           ...inspectedCapabilities,
           features: {
-            ...inspectedCapabilities.features,
-            local_task_control_plane: daemon,
-            pipeline_local_task_artifacts:
-              daemon &&
-              inspectedCapabilities.features.pipeline_local_task_artifacts === true,
-            durable_local_task_attachments: daemon,
-            durable_local_task_steps:
-              daemon &&
-              inspectedCapabilities.features.durable_local_task_steps === true,
-            bounded_local_task_subtasks:
-              daemon &&
-              inspectedCapabilities.features.bounded_local_task_subtasks === true,
+            ...inspectedCapabilities?.features,
+            ...(durableControlPlane
+              ? {
+                  local_task_control_plane: daemon,
+                  pipeline_local_task_artifacts:
+                    daemon &&
+                    inspectedCapabilities.features.pipeline_local_task_artifacts === true,
+                  durable_local_task_attachments: daemon,
+                  durable_local_task_steps:
+                    daemon &&
+                    inspectedCapabilities.features.durable_local_task_steps === true,
+                  bounded_local_task_subtasks:
+                    daemon &&
+                    inspectedCapabilities.features.bounded_local_task_subtasks === true,
+                }
+              : {}),
+            ...(hasSqmLocalReview
+              ? {
+                  sqm_local_review:
+                    daemon && inspectedCapabilities?.features?.sqm_local_review === true,
+                }
+              : {}),
           },
         }
       : inspectedCapabilities;
@@ -211,6 +236,7 @@ export async function startAgent({
   let heartbeatTimer = null;
   let heartbeatInFlight = null;
   let durableLocalTaskWorker = null;
+  let sqmLocalReviewWorker = null;
 
   const restoreRemoteRuns = async () => {
     if (!isSessionValid(session, Date.now(), apiOrigin) || !session?.device_id) return;
@@ -254,7 +280,10 @@ export async function startAgent({
         }),
       )
       .then(async () => {
-        if (durableLocalTaskWorker) await durableLocalTaskWorker.poll();
+        const sqmResult = sqmLocalReviewWorker
+          ? await sqmLocalReviewWorker.poll()
+          : null;
+        if (!sqmResult && durableLocalTaskWorker) await durableLocalTaskWorker.poll();
         return true;
       })
       .finally(() => {
@@ -362,6 +391,27 @@ export async function startAgent({
     });
   }
 
+  if (daemon && availableCapabilities?.features?.sqm_local_review === true) {
+    const sqmApi =
+      dependencies.sqmLocalReviewApi ||
+      createSqmLocalReviewApi({
+        getConnection: () => ({
+          apiOrigin,
+          apiBaseUrl: session?.api_base_url,
+          token: session?.token,
+        }),
+        fetchImpl: dependencies.fetch || globalThis.fetch,
+      });
+    const createWorker =
+      dependencies.createSqmLocalReviewWorker || createSqmLocalReviewWorker;
+    sqmLocalReviewWorker = createWorker({
+      api: sqmApi,
+      beginWork: () => acquireUpdateWork(updateManager),
+      runReview: dependencies.runSqmLocalReview,
+      onError: (error) => reportSqmLocalReviewError(error, quiet),
+    });
+  }
+
   const selectRepository = async (run, repository) => {
     if (run) ensureAcceptingNewWork(updateManager);
     const selected = repository?.local_path
@@ -435,6 +485,34 @@ export async function startAgent({
         json(res, 200, refreshAvailableCapabilities());
         return;
       }
+      if (url.pathname === "/v1/integrations/sqm-agent") {
+        if (!isSessionValid(session, Date.now(), apiOrigin) || !session?.device_id) {
+          json(res, 401, { error: "Reconnect SIMY CLI before managing the SQM agent skill." });
+          return;
+        }
+        if (req.method === "GET") {
+          json(res, 200, await sqmAgentIntegration.inspect());
+          return;
+        }
+        if (req.method === "POST") {
+          const body = await readJson(req);
+          if (body.confirmed !== true) {
+            json(res, 400, {
+              error: "Explicit confirmation is required before installing the SIMY plugin, agent skills, and PR hooks.",
+            });
+            return;
+          }
+          try {
+            const installed = await sqmAgentIntegration.install({
+              platforms: Array.isArray(body.platforms) ? body.platforms : undefined,
+            });
+            json(res, 200, installed);
+          } catch (error) {
+            json(res, 400, { error: error instanceof Error ? error.message : String(error) });
+          }
+          return;
+        }
+      }
       if (
         req.method === "POST" &&
         url.pathname === "/v1/local-tasks/attachments/stage"
@@ -1482,8 +1560,9 @@ export async function startAgent({
     if (shutdownPromise) return shutdownPromise;
     shutdownPromise = (async () => {
       if (heartbeatTimer) clearInterval(heartbeatTimer);
-      await durableLocalTaskWorker?.close?.();
       updateManager?.stop?.();
+      await sqmLocalReviewWorker?.close?.();
+      await durableLocalTaskWorker?.close?.();
       registry.close();
       localTaskRegistry.close();
     })();
@@ -1499,6 +1578,7 @@ export async function startAgent({
     directRegistry,
     localTaskRegistry,
     durableLocalTaskWorker,
+    sqmLocalReviewWorker,
     shutdown,
     webOrigin: apiOrigin,
     get loginUrl() {
@@ -1716,6 +1796,13 @@ function reportDurableLocalTaskError(error, quiet) {
   );
 }
 
+function reportSqmLocalReviewError(error, quiet) {
+  if (quiet) return;
+  console.error(
+    `SIMY SQM Local Review worker: ${error instanceof Error ? error.message : String(error)}`,
+  );
+}
+
 function reportStartupConnectionError(error, quiet) {
   if (quiet) return;
   console.error(
@@ -1808,6 +1895,8 @@ async function capabilities() {
       durable_local_task_scenario_packs: true,
       durable_local_task_steps: true,
       bounded_local_task_subtasks: true,
+      sqm_agent_skill_management: true,
+      sqm_local_review: codex.compatible,
     },
     session_ttl_hours: 48,
   };

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.0";
+export const CLI_VERSION = "0.5.1";
 export const CLI_API_CONTRACT_VERSION = 10;
 
 export function withCliContract(

package/src/codex-plugins/simy/.codex-plugin/plugin.json

@@ -0,0 +1,26 @@
+{
+  "name": "simy",
+  "version": "0.1.0",
+  "description": "Run SIMY quality, delivery, and pull request review workflows from the current Codex thread.",
+  "author": {
+    "name": "Specialist Doctors Inc.",
+    "url": "https://github.com/SpecialistDoctors-Inc"
+  },
+  "repository": "https://github.com/SpecialistDoctors-Inc/simy-cli",
+  "license": "UNLICENSED",
+  "keywords": ["simy", "sqm", "delivery", "pull-request"],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "SIMY",
+    "shortDescription": "Quality, delivery, and PR workflows for SIMY.",
+    "longDescription": "SIMY turns the current Codex thread into a bounded quality check, a full evidence-driven delivery loop, or a read-only pull request review.",
+    "developerName": "Specialist Doctors Inc.",
+    "category": "Developer Tools",
+    "capabilities": ["Quality", "Delivery", "Review"],
+    "defaultPrompt": [
+      "Run the SIMY SQM Loop for the current thread.",
+      "Run the SIMY Delivery Loop for the current thread.",
+      "Review the current pull request with SIMY."
+    ]
+  }
+}

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

@@ -0,0 +1,154 @@
+---
+name: agentic-delivery-loop
+description: Drive complex repository changes from a frozen success charter and failing reproduction through bounded repair loops, local verification, production-like containers, Codex-controlled Chrome user journeys, PR and integration gates, authorized merge and deployment, exact-revision live verification, cleanup, and a completion receipt. Use when implementation must converge autonomously with real user-facing evidence. Do not use for read-only reviews or one-shot low-risk edits.
+---
+
+# Agentic Delivery Loop
+
+Use one Codex task as the controller for the complete delivery lifecycle. Shell,
+browser, API, log, database, and artifact operations may all run in the same
+task. Treat implementer, user actor, evidence collector, and verifier as logical
+roles; they do not require separate agents.
+
+## Freeze the delivery charter
+
+Before material action, record:
+
+- objective and user-visible success conditions;
+- repositories, latest base branches, dedicated worktrees, environments, and
+  the exact user journey;
+- required evidence and applicable change boundaries;
+- exclusions and authority boundaries, especially merge, deployment,
+  production writes, paid APIs, external messages, and fixture cleanup;
+- attempt, time, and cost budgets. Default to at most three evaluated repair
+  attempts when the user has not set a budget.
+
+Do not silently weaken explicit conditions. Add discoveries as a charter patch.
+A scope or success-condition change needs user direction when it materially
+changes the requested result.
+
+## Keep delivery states distinct
+
+Track and report the highest state actually proven:
+
+`chartered -> reproduction_verified -> implemented -> locally_verified -> pr_ci_green -> integration_verified -> user_like_local_verified -> merged -> deployed_exact_revision -> health_verified -> live_verified -> cleanup_verified -> done`
+
+Mark a non-applicable gate explicitly with a reason. Never infer a later state
+from an earlier one. In particular:
+
+- local or container evidence is not deployed evidence;
+- green PR CI is not integration verification;
+- merge is not deployment;
+- a healthy deployment is not a verified user journey;
+- a locally verified Chrome journey is `user_like_local_verified`, not
+  `live_verified`;
+- lack of merge authority ends at `ready_waiting_authority`, not `done`.
+
+## Run one controlled loop
+
+For each attempt:
+
+1. **Observe:** load the current snapshot and revision-bound evidence.
+2. **Evaluate:** identify progress, missing evidence, goal drift, or a repeated
+   failure fingerprint.
+3. **Decide:** apply deterministic policy for `continue`, `retry_current`,
+   `propose_replan`, `request_hil`, `abort`, or `complete`.
+4. **Act:** execute one complete, smallest coherent candidate or verification
+   action.
+5. **Verify:** inspect evidence independent of the action's success claim.
+6. **Reduce:** append a typed receipt and atomically advance the snapshot.
+
+An LLM may propose hypotheses, repairs, or verdicts, but it must not directly
+override state transitions, retry budgets, authorization, or evidence gates.
+Only the controller promotes a candidate or terminalizes the run.
+
+Read [state and receipts](references/state-and-receipts.md) when the task has
+multiple attempts, resumes a prior run, spans repositories, or performs merge,
+deployment, paid, external, or concurrent operations.
+
+## Execute the delivery phases
+
+### 1. Reproduce the real failure
+
+Prefer the real payload, logs, persisted state, browser sequence, environment,
+and user identity. Preserve a failure receipt that distinguishes the original
+boundary from a simplified unit fixture.
+
+### 2. Isolate and implement
+
+Start from the latest required base in a dedicated worktree. Preserve user
+changes. Build the smallest behaviorally correct patch and add a regression
+that fails against the pre-fix behavior at the escaped boundary.
+
+### 3. Verify locally by change boundary
+
+Run focused regression tests first, then formatting, lint, type checking, unit
+tests, and the actual affected runtime. Apply only the relevant lanes from
+[the change-boundary matrix](references/change-boundary-matrix.md).
+
+For medium/high-risk work, run an independent blocker/P1 review after local
+verification. Fix findings narrowly and re-review only the fixes and directly
+affected behavior.
+
+### 4. Coordinate through Draft PR and integration state
+
+Record reproduction, tests, evidence, companion revisions, skipped checks, and
+remaining gates in the Draft PR. Before Ready or merge, combine the latest base
+with required companion and parallel changes, rerun the affected path, and
+confirm current CI and mergeability. Without combined-state proof, report
+`pr_only_verified`, not `integration_verified`.
+
+### 5. Run the Codex-controlled Chrome user journey
+
+For user-facing or browser-mediated behavior, build and start the complete
+production-like local stack from exact candidate revisions, use real APIs when
+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.
+
+Read [Codex Chrome user verification](references/chrome-user-verification.md)
+before running this phase.
+
+### 6. Merge and deploy only with authority
+
+After authorization, use the repository's required merge method and verify the
+remote merge result. Wait until the target environment reports the exact merge
+revision or a verifiably derived image digest. Confirm health and runtime
+identity before live verification.
+
+### 7. Verify the deployed user journey
+
+Repeat the relevant Chrome journey against the deployed environment. Include
+refresh, session return, delayed responses, follow-up lineage, authorization,
+and artifact download/open checks when applicable. Capture screenshots and
+video when visible or timing-dependent behavior matters.
+
+If this fails, retain `merged` and `deployed_exact_revision`; do not reset
+history or claim `done`. Save the exact revision, environment, input, Run ID,
+timestamps, visible state, network evidence, and logs, then add a boundary
+regression before re-entering implementation.
+
+### 8. Clean up and issue the receipt
+
+Remove scoped fixtures and prove the residual count is zero. Deliver a compact
+completion receipt containing repository revisions, PR and CI, independent
+review, container/runtime results, local Chrome evidence, merge and deployment
+identity, deployed Chrome evidence, artifacts, cleanup, skipped gates, and
+residual risk.
+
+## Stop deliberately
+
+Use exactly one disposition:
+
+- `verified_complete`: every applicable gate passed with evidence;
+- `best_available`: the bounded loop produced a safe useful result but named
+  criteria remain unmet;
+- `blocked`: missing authority, input, dependency, or safety precondition
+  prevents progress;
+- `failed`: no safe useful candidate remains within budget;
+- `cancelled`: the user stopped or replaced the task.
+
+Stop after the attempt budget, two consecutive non-improving candidates, or an
+A-B-A failure pattern without a materially different safe repair. Deliver the
+best verified candidate, not merely the latest attempt.
+

package/src/codex-plugins/simy/skills/agentic-delivery-loop/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Agentic Delivery Loop"
+  short_description: "Converge code changes through real live proof"
+  default_prompt: "Use $agentic-delivery-loop to take this change from reproduction through verified delivery."
+

package/src/codex-plugins/simy/skills/agentic-delivery-loop/references/change-boundary-matrix.md

@@ -0,0 +1,67 @@
+# Change-Boundary Verification Matrix
+
+Apply only the lanes touched by the change, plus shared boundaries needed to
+prove the user outcome.
+
+## Common foundation
+
+- Preserve a failing reproduction or explain why it cannot be captured.
+- Run focused regressions, formatting, lint, type checks, unit tests, and the
+  real affected build/runtime in that order when available.
+- Inspect the final diff for scope, secrets, generated files, and unrelated
+  churn.
+- Use current source and dependency revisions in every evidence receipt.
+
+## UI and user-state changes
+
+- Render the actual UI in a browser.
+- Exercise refresh during and after completion, back/forward navigation,
+  another session and return, delayed stream/poll responses, and stale-cache or
+  replica responses where relevant.
+- Verify follow-up and parent/child lineage, optimistic state reconciliation,
+  authorization, and tenant separation.
+- Capture and inspect screenshots; capture video for streaming, recovery,
+  animation, or timing-dependent behavior.
+
+## Generated artifacts
+
+- Download through the user-facing path.
+- Verify non-empty bytes, expected type, stable hash, and ownership/tenant.
+- Open with the real consumer. Render every page/slide/sheet when layout
+  matters and inspect the rendered output.
+- Confirm final-result metadata and artifact storage agree.
+
+## Runtime and packaging
+
+- Build the exact production Dockerfile/image, not only a development image.
+- Start the real entrypoint and execute a representative app-server turn.
+- Check required binaries, fonts, renderers, runtime dependencies, health,
+  signals, and restart behavior inside the image.
+- Record the image digest and bind later evidence to it.
+
+## Backend, database, and asynchronous work
+
+- Apply migrations against an isolated representative database and verify
+  rollback/compatibility expectations where required.
+- Exercise the real API, authentication, authorization/RLS, persistence,
+  replay/idempotency, retries, concurrency, queue/worker delivery, and late
+  updates.
+- Confirm visible state against persisted rows and runtime logs using the same
+  Run ID.
+
+## Cross-repository changes
+
+- Pin every repository and contract revision.
+- Identify required merge/deploy order and backward-compatibility window.
+- Compose companion and parallel changes before Ready.
+- Run the user journey against the combined revisions and record all SHAs and
+  image digests.
+
+## External providers
+
+- Use real APIs only when the charter permits cost and side effects.
+- Prefer scoped sandbox accounts, dedicated users/tenants, unique Run IDs, and
+  explicit cleanup.
+- Require human authorization for production messages, destructive writes, or
+  other consequential effects not already authorized.
+

package/src/codex-plugins/simy/skills/agentic-delivery-loop/references/chrome-user-verification.md

@@ -0,0 +1,136 @@
+# Codex Chrome User Verification
+
+Read this before running a local production-like or deployed user journey with
+Codex controlling the user's Chrome through the browser extension.
+
+## Meaning of this gate
+
+This is goal-driven user simulation, not a direct API test and not merely a
+fixed selector script. Codex receives a user outcome, perceives the real page,
+and operates Chrome through normal visible interactions. Deterministic checks
+then judge the resulting evidence.
+
+Use distinct claims:
+
+- `user_like_local_verified`: the exact candidate revisions passed in a local
+  production-like stack through Chrome;
+- `live_verified`: the exact deployed revision passed in the target shared or
+  production environment through Chrome.
+
+## Prepare the local environment
+
+Prefer a Compose-style environment bundle over one monolithic container. Use
+the production Dockerfiles and exact candidate revisions for applicable
+services such as:
+
+```text
+web
+API / orchestration
+backend or edge functions
+agent runtime
+database and authentication
+queue and workers
+object storage
+supporting renderers or processors
+```
+
+Run Chrome on the host and route it to the environment through stable local
+URLs. Account for container networking: `127.0.0.1` inside a container is not
+the host. Use the platform's supported host gateway or service DNS and record
+the resolved endpoints.
+
+Start services, apply migrations and seeds, verify health, and record service
+SHAs plus image digests before opening the user journey.
+
+## Connect Codex to Chrome
+
+Use the Chrome/browser-control skill available in the current environment. The
+user's Chrome profile must have the ChatGPT browser extension installed and
+connected through the desktop app's Computer Use settings. Use the explicitly
+selected Chrome surface; do not silently substitute another browser.
+
+Use a dedicated verification profile and allowlist only the required local,
+dev, and external-provider domains. Do not inspect cookies, passwords, browser
+history, or profile storage. If authentication blocks the task, ask the user to
+sign in in the selected Chrome profile and resume from the same journey.
+
+## Define the user scenario
+
+Give the browser actor a natural-language goal and observable success criteria,
+not internal API steps. Example shape:
+
+```text
+Open the application, complete <real user objective>, wait for completion,
+refresh the page, leave and return through another session, follow up on the
+result, download the final artifact, and open it.
+```
+
+The actor should use visible UI interactions. Direct API, database, and log
+access are secondary evidence and diagnosis channels, not substitutes for the
+browser journey.
+
+## Use real APIs safely
+
+When permitted, use the actual model/provider and real integration APIs to
+exercise streaming, tool calls, latency, rate limits, and output variability.
+Require:
+
+- sandbox or dedicated verification accounts;
+- scoped credentials and tenant/user fixtures;
+- unique Run IDs and timestamps;
+- attempt, time, and spend caps;
+- dedicated Slack/Gmail/calendar or other external destinations;
+- reconciliation before retrying an ambiguous external effect;
+- recorded cleanup and residual count zero.
+
+Do not broaden existing authority. External messages, production writes,
+destructive operations, and new paid effects still require the applicable
+authorization.
+
+## Execute and collect evidence
+
+Codex may orchestrate the full sequence in one task:
+
+1. Build/start/restart services from the shell.
+2. Confirm health and runtime identity.
+3. Operate the application through Chrome.
+4. Capture screenshots and video when supported and relevant.
+5. Record visible messages, navigation, refresh/session behavior, download
+   paths, browser console/network failures, and timestamps.
+6. Correlate the visible result with backend logs, persisted state, Run IDs,
+   queue/worker activity, and artifact hashes.
+7. Evaluate the evidence against the frozen charter.
+8. On failure, classify the boundary, add a pre-fix regression, patch the
+   smallest surface, rebuild changed images, and repeat within budget.
+
+The same Codex task may perform actor and verifier phases, but the verifier must
+use recorded observable evidence rather than accepting the actor's completion
+claim.
+
+## Default acceptance predicate
+
+Tailor this to the charter:
+
+```text
+chrome_user_journey_passed =
+  visible_result_confirmed
+  && refresh_persistence_confirmed
+  && session_return_confirmed
+  && follow_up_lineage_confirmed_when_applicable
+  && backend_run_id_matched
+  && no_unexpected_console_or_network_failure
+  && artifact_download_open_hash_confirmed_when_applicable
+  && fixture_cleanup_confirmed
+```
+
+Save the browser profile label, target URL/environment, source revisions, image
+digests, user/tenant fixture, Run ID, start/end time, screenshots/video,
+download hashes, and skipped checks in the receipt.
+
+## After deployment
+
+First verify that the target environment serves the exact merge revision or
+derived image digest. Then repeat the smallest user journey that still crosses
+the changed boundary. A preview, local environment, or healthy endpoint cannot
+establish `live_verified` for another deployed environment.
+