@starci/skills 1.1.0

package/operators/release-deploy/validate.mjs

@@ -0,0 +1,129 @@
+// release.deploy's own law over one branch, on top of the shared step check: the receipt names the
+// release, target, approval and rollback identity the request bound; no credential value appears
+// anywhere; the two fallbacks are taken in order and recorded, and a branch nobody entered is `none`;
+// monitoring stayed inside the deadline, a failing condition persisted across at least two
+// observations before recovery, and one transient probe never became a branch; a foreign release
+// terminates instead of being recovered; and steady state is proved by the digest, the targets and
+// every declared probe across the whole window, never by a single observation.
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { validateStep } from '../../scripts/validate-step.mjs';
+import { tableUnder } from '../../scripts/validate-response.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const DIGEST = /^sha256:[0-9a-f]{64}$/;
+const SECRET = /(?:ghp_[A-Za-z0-9]{16,}|glpat-[A-Za-z0-9_-]{16,}|xox[baprs]-[A-Za-z0-9-]{16,}|AKIA[0-9A-Z]{12,}|eyJ[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{10,})/;
+const empty = (v) => v === undefined || v === null || v === '' || v === '—';
+const rows = (text, heading) => tableUnder(text, heading) ?? [];
+const fields = (text, heading) => Object.fromEntries(rows(text, heading).map(([k, v]) => [k, v]));
+
+export async function validateReleaseStep(branchDir, root = ROOT) {
+  const base = await validateStep(root, branchDir);
+  const errors = [...base.errors];
+  const { response, request, requirements = {}, present = new Set() } = base;
+  if (!response || response.operatorId !== 'release.deploy') return { errors };
+  const read = (f) => readFile(path.join(branchDir, f), 'utf8');
+  const has = (f) => existsSync(path.join(branchDir, f));
+
+  if (empty(requirements.approval)) errors.push('request.json: approval has no default; changing what production serves is always something a person said yes to');
+  const deadline = Number(requirements.steadyDeadline ?? 600);
+  if (!Number.isFinite(deadline) || deadline <= 0) errors.push('request.json: steadyDeadline must be a positive number of seconds');
+  const declaredProbes = Array.isArray(requirements.probes) ? requirements.probes : [];
+  if (declaredProbes.length && !declaredProbes.some((p) => p.kind === 'public')) errors.push('request.json: at least one declared probe is public, because container health proves nothing a user could see');
+  const rollback = requirements.rollbackIdentity ?? null;
+  if (rollback && !DIGEST.test(rollback.digest ?? '')) errors.push('request.json: rollbackIdentity names no sha256 digest; a rollback by tag restores whatever the tag now points at');
+
+  // Credentials are names, never values, in the request as much as in the receipt.
+  for (const [key, value] of Object.entries(requirements)) {
+    if (typeof value !== 'string') continue;
+    if (SECRET.test(value) && !value.startsWith('secret-ref://')) errors.push(`request.json: requirements.${key} looks like a resolved credential value; handles are names, never values`);
+  }
+
+  // The two fallbacks are ordered: rollback is reachable only through an exhausted recovery.
+  const fallbacks = response.fallbacks ?? [];
+  if (fallbacks.includes('RECOVERY_EXHAUSTED') && !fallbacks.includes('ROLLOUT_FAILED')) errors.push('response/response.json: RECOVERY_EXHAUSTED was taken without ROLLOUT_FAILED; the rollback branch is reached only through an exhausted recovery');
+
+  let probes = null;
+  if (present.has('probes') && has('response/data/probes.json')) { try { probes = JSON.parse(await read('response/data/probes.json')); } catch { probes = null; } }
+  if (probes) {
+    if (probes.deadlineSeconds !== deadline) errors.push(`response/data/probes.json: monitored to ${probes.deadlineSeconds}s but the request pinned ${deadline}s`);
+    if (probes.elapsedSeconds > probes.deadlineSeconds) errors.push('response/data/probes.json: monitoring ran past its own bounded deadline');
+    if (probes.backoffSeconds > probes.deadlineSeconds) errors.push('response/data/probes.json: the backoff cannot exceed the deadline it sits inside');
+    const declaredIds = new Set(declaredProbes.map((p) => p.probeId));
+    for (const o of probes.observations) {
+      for (const r of o.probeResults) if (declaredIds.size && !declaredIds.has(r.probeId)) errors.push(`response/data/probes.json: probe ${r.probeId} was observed but the request never declared it`);
+      if (declaredIds.size) { const seen = new Set(o.probeResults.map((r) => r.probeId)); for (const id of declaredIds) if (!seen.has(id)) errors.push(`response/data/probes.json: the observation at ${o.observedAt} skipped declared probe ${id}`); }
+    }
+    // One transient probe never becomes recovery.
+    const failing = probes.observations.filter((o) => o.condition === 'failing').length;
+    if (fallbacks.includes('ROLLOUT_FAILED') && failing < 2) errors.push('response/data/probes.json: the recovery branch was taken after fewer than two failing observations; one transient probe is not a persistent failure');
+    if (probes.finalCondition === 'steady' && probes.observations.at(-1)?.condition !== 'steady') errors.push('response/data/probes.json: the final condition is steady but the last observation is not');
+    if (probes.finalCondition === 'deadline-exceeded' && response.status === 'done') errors.push('response/data/probes.json: the deadline was exceeded, which is STEADY_STATE_UNPROVEN, not a deployment');
+  } else if (response.status === 'done') errors.push('response/data/probes.json: a done branch needs the monitored probe series');
+
+  if (!(present.has('release-deployment') && has('response/response.md'))) {
+    if (response.status === 'done') errors.push('response/response.md: a done branch needs the deployment receipt');
+    return { errors };
+  }
+  const text = await read('response/response.md');
+  if (SECRET.test(text)) errors.push('response/response.md: the receipt carries something shaped like a resolved credential value');
+  const binding = fields(text, '## Binding');
+  const outcome = fields(text, '## Outcome');
+  const steps = rows(text, '## Steps');
+  const monitoring = fields(text, '## Monitoring');
+  const steady = fields(text, '## Steady state');
+
+  if (!empty(requirements.release) && binding.Release !== requirements.release) errors.push(`response/response.md: Binding deploys ${binding.Release} but the request bound ${requirements.release}`);
+  if (!empty(requirements.target) && binding.Target !== requirements.target) errors.push(`response/response.md: Binding names target ${binding.Target} but the request bound ${requirements.target}`);
+  if (!empty(requirements.approval) && binding.Approval !== requirements.approval) errors.push('response/response.md: Binding names an approval the request did not bind');
+  if (!DIGEST.test(binding.Digest ?? '')) errors.push('response/response.md: Binding names no sha256 digest; a release is identified by its digest, never by a tag');
+  if (rollback && binding['Rollback identity'] !== rollback.releaseId) errors.push('response/response.md: Binding names a rollback identity the request did not declare');
+  if (String(binding['Steady deadline']) !== String(deadline)) errors.push(`response/response.md: Binding says the deadline is ${binding['Steady deadline']} but the request pinned ${deadline}`);
+
+  // The branch the receipt records is the branch the fallbacks say was taken.
+  const expectedBranch = fallbacks.includes('RECOVERY_EXHAUSTED') ? 'rollback' : fallbacks.includes('ROLLOUT_FAILED') ? 'recover' : 'none';
+  if (outcome.Branch !== expectedBranch) errors.push(`response/response.md: Branch is ${outcome.Branch} but the fallbacks taken say ${expectedBranch}`);
+  if (expectedBranch === 'rollback' && outcome.Outcome !== 'rolled-back') errors.push('response/response.md: a rollback branch cannot report a deployed outcome; a restored release is its own terminal');
+  if (expectedBranch !== 'rollback' && outcome.Outcome === 'rolled-back') errors.push('response/response.md: the outcome is rolled-back but no rollback branch was taken');
+  if (outcome.Outcome === 'rolled-back' && !rollback) errors.push('response/response.md: a rollback happened with no declared rollback identity to restore');
+
+  // Every effect is a compare-and-set: an applied mutating step moved a revision, a reading step did not.
+  const MUTATING = new Set(['host-prepare', 'artifact-publish', 'migrate', 'domain-reconcile', 'rollout', 'recover', 'rollback']);
+  for (const [step, state, before, after] of steps) {
+    const at = `response/response.md: step ${step}`;
+    if (MUTATING.has(step)) {
+      if (state === 'applied' && (before === '—' || after === '—' || before === after)) errors.push(`${at} claims it applied without moving a revision`);
+      if (state === 'no-op' && before !== after) errors.push(`${at} is a no-op and moved a revision anyway`);
+    } else if (before !== '—' || after !== '—') errors.push(`${at} reports a revision for a boundary it never touched`);
+  }
+  const stepNames = new Set(steps.map(([s]) => s));
+  if (expectedBranch === 'recover' && !stepNames.has('recover')) errors.push('response/response.md: the recovery fallback was taken but no recover step is recorded');
+  if (expectedBranch === 'rollback' && !stepNames.has('rollback')) errors.push('response/response.md: the rollback fallback was taken but no rollback step is recorded');
+  if (expectedBranch === 'none' && (stepNames.has('recover') || stepNames.has('rollback'))) errors.push('response/response.md: a branch step is recorded while the run took neither fallback');
+
+  if (probes) {
+    if (String(monitoring.Deadline) !== String(probes.deadlineSeconds)) errors.push('response/response.md: Monitoring deadline differs from the measured series');
+    if (monitoring['Final condition'] !== probes.finalCondition) errors.push(`response/response.md: Monitoring says ${monitoring['Final condition']} but the series ended ${probes.finalCondition}`);
+  }
+
+  // Steady state is proved, not assumed.
+  if (outcome.Outcome === 'deployed') {
+    if (steady['Active digest'] !== binding.Digest) errors.push('response/response.md: the deployment is reported while another digest is active');
+    const [available, of] = (steady['Available targets'] ?? '').split(' of ');
+    if (available !== undefined && of !== undefined && Number(available) < Number(of)) errors.push(`response/response.md: ${available} of ${of} targets are available; a partly available target set is not steady state`);
+    if (Number(steady['Superseded active'] ?? 0) > 0) errors.push('response/response.md: a superseded target is still active, so the old release is still serving traffic');
+    if (probes && probes.finalCondition !== 'steady') errors.push('response/response.md: a deployment is reported while the observed series never reached steady');
+    if (probes && probes.observations.length < 2) errors.push('response/response.md: steady state is claimed from a single observation');
+  }
+  return { errors };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const target = process.argv[2];
+  if (!target) { process.stderr.write('usage: node validate.mjs <session>/step-N/parallel-M\n'); process.exit(2); }
+  const { errors } = await validateReleaseStep(path.resolve(target));
+  if (errors.length) { process.stderr.write(`${errors.join('\n')}\n`); process.exitCode = 1; } else process.stdout.write('valid release.deploy branch\n');
+}

package/operators/uat-verify/errors.json

@@ -0,0 +1,78 @@
+{
+  "schemaVersion": 9,
+  "note": "Stop codes only uat.verify emits. Same entry shape as operators/errors.json, scope implicit. Shared codes (INVALID_INPUT, SOURCE_DRIFT, NO_PROGRESS) come from operators/errors.json. RUNTIME_UNAVAILABLE is emitted here too but is defined in operators/frontend-surface-audit/errors.json; it belongs in operators/errors.json with both operators in scope, and until that move validate-operator reports it as out of scope here. No code asks a person for a credential: the shared UAT password is resolved by name at login, and unavailable provisioning blocks instead of prompting.",
+  "codes": {
+    "ADMISSION_MISSING": {
+      "domain": "quality",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "The surface audit or the quality verification that admits product UAT is absent, or one of them was taken at another commit than the pinned head.",
+        "vi": "Lượt soi bề mặt hoặc lượt kiểm chất lượng cho phép UAT sản phẩm đang thiếu, hoặc một trong hai được lấy ở commit khác commit đã ghim."
+      },
+      "resume": {
+        "en": "Re-run the missing admission at the pinned commit.",
+        "vi": "Chạy lại admission còn thiếu tại đúng commit đã ghim."
+      }
+    },
+    "PROVISIONING_UNAVAILABLE": {
+      "domain": "control-panel",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "The sealed UAT credential cannot be resolved by name, or the flow's dedicated account does not exist; asking a person to sign in is forbidden in every branch.",
+        "vi": "Không giải được thông tin đăng nhập UAT niêm phong theo tên, hoặc tài khoản riêng của luồng không tồn tại; nhờ người đăng nhập bị cấm ở mọi nhánh."
+      },
+      "resume": {
+        "en": "Restore the sealed credential or the account; never a person's sign-in.",
+        "vi": "Khôi phục thông tin đăng nhập niêm phong hoặc tài khoản; không bao giờ nhờ người đăng nhập."
+      }
+    },
+    "LEASE_INVALID": {
+      "domain": "control-panel",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "The exclusive lease on the flow directory is expired, foreign, or bound to another run, generation or origin.",
+        "vi": "Lease độc quyền trên thư mục luồng đã hết hạn, thuộc chỗ khác, hoặc gắn vào lượt chạy, generation hay origin khác."
+      },
+      "resume": {
+        "en": "The orchestrator grants the lease again for this run.",
+        "vi": "Orchestrator cấp lại lease cho đúng lượt chạy này."
+      }
+    },
+    "EVIDENCE_UNAVAILABLE": {
+      "domain": "runtime",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "A case produced no capture, no screenshot, or no screenshot whose login field could be masked, so a lane has nothing to be judged on.",
+        "vi": "Một case không sinh ra capture, không sinh ra ảnh chụp, hoặc không ảnh nào che được ô mật khẩu, nên một làn không có gì để xét."
+      },
+      "resume": {
+        "en": "Restore the dependency and run the frozen case again under a new runId.",
+        "vi": "Khôi phục phụ thuộc rồi chạy lại case đã đóng băng dưới một runId mới."
+      }
+    },
+    "FIXTURE_VIOLATION": {
+      "domain": "caller",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "The seed, the run namespace or the cleanup scope could not be satisfied: a seed would have created the outcome under test, or cleanup would have reached outside the namespace.",
+        "vi": "Seed, namespace lượt chạy hay phạm vi dọn dẹp không thoả được: seed sẽ tạo ra chính kết quả cần kiểm, hoặc dọn dẹp sẽ với ra ngoài namespace."
+      },
+      "resume": {
+        "en": "Correct the fixture boundary in seed/records.json.",
+        "vi": "Sửa ranh giới fixture trong seed/records.json."
+      }
+    },
+    "CANONICAL_WRITE_DENIED": {
+      "domain": "backend",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "The flow directory cannot be written and read back under the exclusive lease, or the write would have rewritten an existing run record.",
+        "vi": "Không ghi rồi đọc lại được thư mục luồng dưới lease độc quyền, hoặc lần ghi sẽ đè lên một hồ sơ lượt chạy đã có."
+      },
+      "resume": {
+        "en": "Restore write authority on the flow directory, or publish under a new runId.",
+        "vi": "Khôi phục quyền ghi trên thư mục luồng, hoặc phát hành dưới một runId mới."
+      }
+    }
+  }
+}

package/operators/uat-verify/operator.json

@@ -0,0 +1,25 @@
+{
+  "schemaVersion": 9,
+  "id": "uat.verify",
+  "domain": "test",
+  "job": "Verify one product flow end to end on the running product at the pinned commit, and publish one append-only run record with three independently judged lanes, or stop at the exact unavailability instead of manufacturing a verdict.",
+  "package": "operator.md",
+  "errors": "errors.json",
+  "validator": "validate.mjs",
+  "selfTest": "self-test.mjs",
+  "resources": {
+    "profile": "sol-fresh",
+    "grammarBound": false,
+    "tools": {
+      "@tools/fileread": "context-aliases",
+      "@tools/sourcewrite": "declared-write-set",
+      "@tools/git": "read",
+      "@tools/websearch": "bounded",
+      "@tools/visualize": "html",
+      "@tools/browsercontrol": "required",
+      "@tools/http": "probe",
+      "@tools/secrets": "resolve-by-name",
+      "@tools/database": "namespaced-write"
+    }
+  }
+}

package/operators/uat-verify/operator.md

@@ -0,0 +1,162 @@
+# uat.verify
+
+## Job
+
+Verify one product flow end to end on the running product at the pinned commit, and publish one
+append-only run record with three independently judged lanes, or stop at the exact unavailability
+instead of manufacturing a verdict.
+
+## UAT runs only when a person asked for it
+
+`requestedBy` names the person who asked; without it the operator has nothing to run for and stops at
+the gate. Nothing about this operator is routine: it signs in as a real user, writes real records into
+a shared runtime and leaves a permanent run record behind, so the trigger is a person and never a
+schedule, a chain default or another agent's convenience. `runId` and `lease` are not questions for a
+person either: the orchestrator generates the run identifier and grants the exclusive lease on the
+flow directory before the branch starts, and an invocation that arrives without them is
+`INVALID_INPUT` rather than a prompt.
+
+## The password is a name, never a value
+
+Every UAT account shares one password, sealed at `.stacks/<env>/secrets/uat.enc` with the shared
+master identity, and each flow owns its own dedicated username. The operator resolves the credential
+by name through `@workspaces/device-state` at the moment of login and at no other moment; it never
+copies the value into a variable it writes, a fixture, a command it records, or a sentence it
+publishes. The password is never plaintext anywhere this operator writes: not in `response/`, not in
+the run record under `runs/<runId>/`, not in a log. The login field is masked in every screenshot,
+including the ones taken before submission and the ones taken after a failed attempt, because a
+capture is published evidence and a password that reached a picture has already left custody. An
+account record therefore carries a username, a role, a credential name and the sealed file's path,
+and nothing that could hold a secret.
+
+## Freeze precedes execution
+
+The snapshot is written before any product action and never edited afterwards. It states the commit,
+the cases in their frozen order with their named assertions, the account record, the seed
+fingerprint and the fixture namespace. That ordering turns three invisible failures into detectable
+ones: a case that was never frozen cannot appear in a result, a run cannot be re-explained after the
+fact by editing what it claimed to test, and an admission cannot be back-dated onto a commit it
+never saw. Both admissions — the `frontend-surface-audit` receipt and the `quality-verification` receipt —
+must name the same commit as the pinned head; either one absent, or either one taken at another
+commit, is `ADMISSION_MISSING`, because a clean surface and a green gate at some other commit say
+nothing about the product this run drives.
+
+## Three lanes, judged apart
+
+Behaviour, UX and UI are judged on their own evidence and never borrow each other's conclusions.
+Exactly three lanes are published, each with its own pass or fail and its own evidence references; a
+lane with no evidence is not a fail but `EVIDENCE_UNAVAILABLE`, because charging unavailability as a
+failure blames a product nobody observed. A UI defect on an application-owned node routes to
+presentation, a behaviour defect routes to the backend, and a UX defect routes to a person: nobody
+resolves a question of intent by re-running the flow harder.
+
+## The namespace owns everything this run wrote
+
+Every record this run writes carries `is_uat=true` and the `runId` namespace, so what the run created
+is separable from what the product already had. Cleanup deletes exactly that namespace and nothing
+else: not another run's namespace, not a record that merely carries the UAT flag, and never a run
+record. Verification itself reads and does not write, and a seed may never create the outcome under
+test.
+
+## Runs are append-only
+
+`runs/<runId>/` is written once, at the end, under the exclusive lease, and `latest` is moved to point
+at it. A run folder that already exists is never rewritten, never trimmed and never corrected: a
+second attempt is a new `runId`, and the old record stays as the evidence of what was observed then.
+History that can be edited is not history.
+
+## Boundary
+
+Context is read-only apart from the flow directory. The operator writes the snapshot and the run
+record under `@worktrees/uat/<flow>/<case>` while it holds the exclusive lease, and writes only
+`response/` of its own branch: `data/snapshot.json`, `data/captures/<case>.json`,
+`data/verdicts.json`, the screenshots and the sheet under `response/artifacts/`, `response.md` and
+`response.json`. It does not read or write the password as a value, does not ask a person to sign in
+or paste a credential, does not repair the product to make a case pass, does not edit the frozen
+snapshot after execution begins, does not rewrite or delete a run record, and does not delete
+anything outside its own fixture namespace.
+
+## Context
+
+| Alias | Bind | Required |
+| --- | --- | --- |
+| `@worktrees/uat/<flow>/<case>` | the flow directory: `flow.md`, `account.json`, `seed/`, the append-only `runs/<runId>/` history and the `latest` pointer, bound by fingerprint per file and written only under the exclusive lease | yes |
+| `@worktrees/_templates` | the UAT flow template a new flow directory is created from; consumed, never modified | yes |
+| `@worktrees/sessions/central-runtime` | the ready runtime owner, its generation and its exact origins; readiness is proved, not assumed | yes |
+| `@workspaces/device-state` | the sealed credential roster; the shared UAT password is resolved by name here at login and read nowhere else | yes |
+| `@workspaces/be` | the routed backend checkout at the pinned commit, whose behaviour the flow verifies and whose store holds the namespaced records | yes |
+
+## Inputs
+
+| Kind | From | Required |
+| --- | --- | --- |
+| `frontend-surface-audit` | the surface audit that found the frontend clean, taken at the pinned commit | yes |
+| `quality-verification` | the quality gate that passed, taken at the same pinned commit | yes |
+
+## Requirements
+
+| Field | Type | Default | Ask |
+| --- | --- | --- | --- |
+| `requestedBy` | id | — | Who asked for this UAT run; UAT never starts without a person behind it |
+| `feature` | id | — | The feature key that addresses the flow directory |
+| `flow` | id | — | The one product flow this invocation verifies |
+| `cases` | list of `caseId` | every case of the flow | Which frozen cases to run; the default is every case `flow.md` declares, in its order |
+| `runId` | id | the orchestrator's run id | Not asked of a person: the orchestrator generates it and it namespaces every record this run writes |
+| `lease` | token | the orchestrator's lease | Not asked of a person: the orchestrator grants the exclusive lease on the flow directory before the branch starts |
+| `resume` | token | null | The blocked branch's token when re-entering after a stop |
+
+## Steps
+
+| # | Step | Params | Reads | Writes | Stops with |
+| --- | --- | --- | --- | --- | --- |
+| 1 | Validate the gate, the resume, the exclusive lease and the person who asked | `requestedBy`, `lease`, `resume` | `request/request.json`, @worktrees/uat/<flow>/<case> for `latest` and the prior run record, @workspaces/be at the pinned commit, @tools/git | — | `INVALID_INPUT`, `SOURCE_DRIFT`, `NO_PROGRESS` |
+| 2 | Confirm admission: the surface audit is clean and the quality gate is green at the same pinned commit | — | input `frontend-surface-audit`, input `quality-verification` | — | `ADMISSION_MISSING` |
+| 3 | Preflight the runtime: the sealed credential resolves by name, the account exists, the store answers | — | @workspaces/device-state for the credential named by `account.json`, @worktrees/sessions/central-runtime for the generation and origins, @tools/secrets, @tools/http | — | `PROVISIONING_UNAVAILABLE` |
+| 4 | Freeze the snapshot from `flow.md`, `account.json` and `seed/` | `feature`, `flow`, `cases` | @worktrees/uat/<flow>/<case>, @worktrees/_templates for the flow template | @worktrees/uat/<flow>/<case> (snapshot), `response/data/snapshot.json`, @tools/sourcewrite | `CANONICAL_WRITE_DENIED` |
+| 5 | Seed the frozen records into the run namespace | `runId` | `response/data/snapshot.json`, @workspaces/be | @tools/database | `FIXTURE_VIOLATION` |
+| 6 | Execute the frozen cases in order on the session worktree at the pinned commit | — | `response/data/snapshot.json`, @worktrees/sessions/central-runtime for the origin and generation, @workspaces/device-state for the credential at login only, @tools/browsercontrol, @tools/websearch | — | `LEASE_INVALID`, `RUNTIME_UNAVAILABLE` |
+| 7 | Capture at each named assertion with the login field masked, and stitch the sheet | — | `response/data/snapshot.json`, @worktrees/sessions/central-runtime for the most direct runtime evidence | `response/data/captures/<case>.json`, `response/artifacts/<case>.png`, `response/artifacts/sheet.png`, @tools/visualize | `EVIDENCE_UNAVAILABLE` |
+| 8 | Judge the three lanes apart | — | `response/data/captures/<case>.json` | `response/data/verdicts.json` | — |
+| 9 | Verify read-only, then delete the run namespace and nothing else | `runId` | @workspaces/be for the records carrying `is_uat=true` and this namespace, `response/data/verdicts.json` | @tools/database | — |
+| 10 | Append `runs/<runId>/`, move `latest`, and emit | `runId` | everything above | @worktrees/uat/<flow>/<case> (runs/<runId>/ and latest), `response/response.md`, `response/response.json`, @tools/sourcewrite | — |
+
+A blocked run publishes no run record at all, because a half-written record is the artifact a later
+reader would mistake for a decision. A resume begins again at validation, reuses only observations
+whose fingerprints are unchanged, and writes under the same lease; a resume that adds no admission,
+lease, evidence or case change is `NO_PROGRESS`. A second attempt after a published run is a new
+`runId`, never an edit of the old one.
+
+## Outputs
+
+| Kind | File | Type | Required |
+| --- | --- | --- | --- |
+| `uat-flow-verification` | `response/response.md` | md | yes |
+| `uat-snapshot` | `response/data/snapshot.json` | data | yes |
+| `uat-capture` | `response/data/captures/<case>.json` | data | yes |
+| `uat-verdicts` | `response/data/verdicts.json` | data | yes |
+| `screenshot` | `response/artifacts/<case>.png` | artifact | yes |
+| `sheet` | `response/artifacts/sheet.png` | artifact | yes |
+
+## Stops
+
+| Code | Disposition |
+| --- | --- |
+| `INVALID_INPUT` | terminate |
+| `SOURCE_DRIFT` | terminate |
+| `NO_PROGRESS` | terminate |
+| `ADMISSION_MISSING` | terminate |
+| `PROVISIONING_UNAVAILABLE` | terminate |
+| `LEASE_INVALID` | terminate |
+| `RUNTIME_UNAVAILABLE` | terminate |
+| `EVIDENCE_UNAVAILABLE` | terminate |
+| `FIXTURE_VIOLATION` | terminate |
+| `CANONICAL_WRITE_DENIED` | terminate |
+
+## Next
+
+| When | Operator |
+| --- | --- |
+| all three lanes pass | `git.publish` |
+| the UI lane fails on an application-owned node | `frontend.presentation.resolve` |
+| the behaviour lane fails | `backend.source.apply` |
+| the UX lane fails: a person decides what the experience should be, and the flow is verified again only after that decision | `user` |

package/operators/uat-verify/operator.vi.md

@@ -0,0 +1,161 @@
+# uat.verify
+
+## Việc
+
+Kiểm chứng một luồng sản phẩm từ đầu đến cuối trên sản phẩm đang chạy tại commit đã ghim, rồi phát
+một hồ sơ lượt chạy chỉ-thêm với ba làn được xét độc lập, hoặc dừng đúng chỗ không sẵn sàng thay vì
+chế ra một phán quyết.
+
+## UAT chỉ chạy khi có người yêu cầu
+
+`requestedBy` nêu tên người đã yêu cầu; thiếu nó thì operator không có ai để chạy cho và dừng ngay ở
+cổng. Không có gì ở operator này là thường lệ: nó đăng nhập như một người dùng thật, ghi bản ghi thật
+vào một runtime dùng chung và để lại một hồ sơ lượt chạy vĩnh viễn, nên thứ khởi động nó là một con
+người, không bao giờ là lịch hẹn, mặc định của chain hay sự tiện tay của một agent khác. `runId` và
+`lease` cũng không phải câu hỏi dành cho người: orchestrator sinh mã lượt chạy và cấp lease độc quyền
+trên thư mục luồng trước khi nhánh bắt đầu, và một lần gọi đến mà thiếu chúng là `INVALID_INPUT` chứ
+không phải một lời hỏi.
+
+## Mật khẩu là một cái tên, không bao giờ là một giá trị
+
+Mọi tài khoản UAT dùng chung một mật khẩu, niêm phong tại `.stacks/<env>/secrets/uat.enc` bằng master
+identity dùng chung, còn mỗi luồng giữ username riêng của nó. Operator giải mã thông tin đăng nhập
+theo tên qua `@workspaces/device-state` đúng lúc đăng nhập và không lúc nào khác; nó không bao giờ
+chép giá trị ấy vào một biến nó ghi ra, một fixture, một câu lệnh nó lưu lại hay một câu nó phát
+hành. Mật khẩu không bao giờ nằm ở dạng rõ tại bất kỳ nơi nào operator này ghi: không trong
+`response/`, không trong hồ sơ lượt chạy dưới `runs/<runId>/`, không trong log. Ô mật khẩu bị che
+trong mọi ảnh chụp, kể cả ảnh chụp trước khi gửi và ảnh chụp sau một lần đăng nhập hỏng, vì một ảnh
+chụp là bằng chứng đã phát hành và mật khẩu đã lọt vào ảnh thì đã rời khỏi vòng giữ. Vì thế hồ sơ tài
+khoản chỉ mang username, vai trò, tên thông tin đăng nhập và đường dẫn file niêm phong, không mang
+thứ gì có thể chứa một bí mật.
+
+## Đóng băng đi trước thực thi
+
+Snapshot được ghi trước mọi hành động lên sản phẩm và không bao giờ sửa lại sau đó. Nó nêu commit, các
+case theo thứ tự đã đóng băng cùng những khẳng định có tên, hồ sơ tài khoản, fingerprint của seed và
+namespace fixture. Thứ tự ấy biến ba thất bại vô hình thành ba thất bại thấy được: một case chưa từng
+được đóng băng không thể xuất hiện trong kết quả, một lượt chạy không thể được giải thích lại sau khi
+xong bằng cách sửa điều nó nói là mình kiểm, và một admission không thể bị gán ngược vào một commit nó
+chưa từng thấy. Cả hai admission — biên bản `frontend-surface-audit` và biên bản `quality-verification` —
+phải nêu đúng commit đã ghim; thiếu một trong hai, hoặc một trong hai lấy ở commit khác, là
+`ADMISSION_MISSING`, vì một bề mặt sạch và một cổng xanh ở commit khác chẳng nói gì về sản phẩm mà
+lượt chạy này đang lái.
+
+## Ba làn, xét riêng
+
+Hành vi, UX và UI được xét trên bằng chứng của riêng chúng và không bao giờ mượn kết luận của nhau.
+Đúng ba làn được phát hành, mỗi làn có pass hoặc fail riêng và tham chiếu bằng chứng riêng; một làn
+không có bằng chứng không phải là fail mà là `EVIDENCE_UNAVAILABLE`, vì tính sự không sẵn sàng thành
+lỗi là đổ tội cho một sản phẩm chưa ai quan sát. Lỗi UI trên một node do ứng dụng sở hữu đi về
+presentation, lỗi hành vi đi về backend, còn lỗi UX đi về người: không ai giải một câu hỏi về ý đồ
+bằng cách chạy lại luồng mạnh tay hơn.
+
+## Namespace sở hữu mọi thứ lượt chạy này ghi ra
+
+Mọi bản ghi lượt chạy này ghi đều mang `is_uat=true` và namespace `runId`, nên thứ lượt chạy tạo ra
+tách bạch với thứ sản phẩm vốn đã có. Dọn dẹp xoá đúng namespace ấy và không gì khác: không xoá
+namespace của lượt chạy khác, không xoá bản ghi chỉ vì nó mang cờ UAT, và không bao giờ xoá một hồ sơ
+lượt chạy. Bản thân khâu kiểm chứng chỉ đọc chứ không ghi, và seed không bao giờ được tạo ra chính kết
+quả cần kiểm.
+
+## Hồ sơ lượt chạy chỉ được thêm
+
+`runs/<runId>/` được ghi một lần, ở cuối, dưới lease độc quyền, rồi `latest` được dời sang trỏ vào nó.
+Một thư mục lượt chạy đã tồn tại thì không bao giờ bị ghi đè, bị cắt bớt hay bị "sửa cho đúng": lần
+thử thứ hai là một `runId` mới, còn hồ sơ cũ ở lại làm bằng chứng cho điều đã quan sát được lúc ấy.
+Lịch sử mà sửa được thì không còn là lịch sử.
+
+## Ranh giới ghi
+
+Context là chỉ-đọc, trừ thư mục luồng. Operator ghi snapshot và hồ sơ lượt chạy dưới
+`@worktrees/uat/<flow>/<case>` trong khi còn giữ lease độc quyền, và chỉ ghi trong `response/` của
+nhánh mình: `data/snapshot.json`, `data/captures/<case>.json`, `data/verdicts.json`, các ảnh chụp và
+tấm ghép dưới `response/artifacts/`, `response.md` và `response.json`. Nó không đọc cũng không ghi mật
+khẩu dưới dạng giá trị, không nhờ người đăng nhập hay đưa thông tin đăng nhập, không sửa sản phẩm cho
+một case đậu, không sửa snapshot đã đóng băng sau khi bắt đầu chạy, không ghi đè hay xoá một hồ sơ
+lượt chạy, và không xoá bất cứ thứ gì ngoài namespace fixture của chính nó.
+
+## Context
+
+| Alias | Bind | Bắt buộc |
+| --- | --- | --- |
+| `@worktrees/uat/<flow>/<case>` | thư mục luồng: `flow.md`, `account.json`, `seed/`, lịch sử chỉ-thêm `runs/<runId>/` và con trỏ `latest`, bind theo fingerprint từng file và chỉ ghi khi giữ lease độc quyền | có |
+| `@worktrees/_templates` | khuôn luồng UAT dùng để tạo thư mục luồng mới; tiêu thụ, không sửa | có |
+| `@worktrees/sessions/central-runtime` | chủ runtime đã sẵn sàng, generation và các origin chính xác của nó; sự sẵn sàng phải được chứng minh, không được giả định | có |
+| `@workspaces/device-state` | sổ thông tin đăng nhập niêm phong; mật khẩu UAT dùng chung được giải theo tên ở đây lúc đăng nhập và không đọc ở đâu khác | có |
+| `@workspaces/be` | checkout backend được route tại commit đã ghim, nơi luồng kiểm hành vi và nơi store giữ các bản ghi có namespace | có |
+
+## Đầu vào
+
+| Kind | Từ đâu | Bắt buộc |
+| --- | --- | --- |
+| `frontend-surface-audit` | lượt soi bề mặt kết luận frontend sạch, lấy tại commit đã ghim | có |
+| `quality-verification` | cổng chất lượng đã xanh, lấy tại đúng commit đã ghim ấy | có |
+
+## Yêu cầu
+
+| Field | Kiểu | Mặc định | Hỏi |
+| --- | --- | --- | --- |
+| `requestedBy` | id | — | Ai yêu cầu lượt UAT này; UAT không bao giờ khởi động khi không có người đứng sau |
+| `feature` | id | — | Khoá feature dùng để địa chỉ hoá thư mục luồng |
+| `flow` | id | — | Luồng sản phẩm duy nhất mà lần gọi này kiểm chứng |
+| `cases` | list `caseId` | every case of the flow | Chạy những case đã đóng băng nào; mặc định là mọi case `flow.md` khai, theo đúng thứ tự của nó |
+| `runId` | id | the orchestrator's run id | Không hỏi người: orchestrator sinh ra nó và nó namespace mọi bản ghi lượt chạy này ghi ra |
+| `lease` | token | the orchestrator's lease | Không hỏi người: orchestrator cấp lease độc quyền trên thư mục luồng trước khi nhánh bắt đầu |
+| `resume` | token | null | Token của nhánh bị chặn khi vào lại sau một mã dừng |
+
+## Các bước
+
+| # | Bước | Tham số | Đọc | Ghi | Dừng với |
+| --- | --- | --- | --- | --- | --- |
+| 1 | Kiểm gate, lần chạy lại, lease độc quyền và người đã yêu cầu | `requestedBy`, `lease`, `resume` | `request/request.json`, @worktrees/uat/<flow>/<case> để lấy `latest` và hồ sơ lượt chạy trước, @workspaces/be tại commit đã ghim, @tools/git | — | `INVALID_INPUT`, `SOURCE_DRIFT`, `NO_PROGRESS` |
+| 2 | Xác nhận admission: bề mặt sạch và cổng chất lượng xanh tại cùng một commit đã ghim | — | đầu vào `frontend-surface-audit`, đầu vào `quality-verification` | — | `ADMISSION_MISSING` |
+| 3 | Preflight runtime: thông tin đăng nhập niêm phong giải được theo tên, tài khoản tồn tại, store trả lời | — | @workspaces/device-state để lấy thông tin đăng nhập mà `account.json` nêu tên, @worktrees/sessions/central-runtime để lấy generation và các origin, @tools/secrets, @tools/http | — | `PROVISIONING_UNAVAILABLE` |
+| 4 | Đóng băng snapshot từ `flow.md`, `account.json` và `seed/` | `feature`, `flow`, `cases` | @worktrees/uat/<flow>/<case>, @worktrees/_templates để lấy khuôn luồng | @worktrees/uat/<flow>/<case> (snapshot), `response/data/snapshot.json`, @tools/sourcewrite | `CANONICAL_WRITE_DENIED` |
+| 5 | Gieo các bản ghi đã đóng băng vào namespace lượt chạy | `runId` | `response/data/snapshot.json`, @workspaces/be | @tools/database | `FIXTURE_VIOLATION` |
+| 6 | Chạy các case đã đóng băng theo thứ tự trên worktree phiên tại commit đã ghim | — | `response/data/snapshot.json`, @worktrees/sessions/central-runtime để lấy origin và generation, @workspaces/device-state để lấy thông tin đăng nhập chỉ lúc đăng nhập, @tools/browsercontrol, @tools/websearch | — | `LEASE_INVALID`, `RUNTIME_UNAVAILABLE` |
+| 7 | Capture tại từng khẳng định có tên với ô mật khẩu đã che, rồi ghép tấm sheet | — | `response/data/snapshot.json`, @worktrees/sessions/central-runtime để lấy bằng chứng runtime trực tiếp nhất | `response/data/captures/<case>.json`, `response/artifacts/<case>.png`, `response/artifacts/sheet.png`, @tools/visualize | `EVIDENCE_UNAVAILABLE` |
+| 8 | Xét ba làn tách rời nhau | — | `response/data/captures/<case>.json` | `response/data/verdicts.json` | — |
+| 9 | Kiểm chỉ-đọc, rồi xoá namespace lượt chạy và không gì khác | `runId` | @workspaces/be để lấy các bản ghi mang `is_uat=true` và namespace này, `response/data/verdicts.json` | @tools/database | — |
+| 10 | Thêm `runs/<runId>/`, dời `latest`, rồi phát | `runId` | mọi thứ ở trên | @worktrees/uat/<flow>/<case> (runs/<runId>/ và latest), `response/response.md`, `response/response.json`, @tools/sourcewrite | — |
+
+Một lượt bị chặn không phát hồ sơ lượt chạy nào cả, vì một hồ sơ viết nửa vời chính là thứ người đọc
+sau này sẽ nhầm thành một quyết định. Lần chạy lại bắt đầu lại từ khâu kiểm, chỉ tái dùng những quan
+sát có fingerprint không đổi, và ghi dưới cùng một lease; lần chạy lại không thêm admission, lease,
+bằng chứng hay case nào là `NO_PROGRESS`. Lần thử thứ hai sau một lượt đã phát hành là một `runId`
+mới, không bao giờ là một lần sửa lượt cũ.
+
+## Đầu ra
+
+| Kind | File | Kiểu | Bắt buộc |
+| --- | --- | --- | --- |
+| `uat-flow-verification` | `response/response.md` | md | có |
+| `uat-snapshot` | `response/data/snapshot.json` | data | có |
+| `uat-capture` | `response/data/captures/<case>.json` | data | có |
+| `uat-verdicts` | `response/data/verdicts.json` | data | có |
+| `screenshot` | `response/artifacts/<case>.png` | artifact | có |
+| `sheet` | `response/artifacts/sheet.png` | artifact | có |
+
+## Dừng
+
+| Code | Xử lý |
+| --- | --- |
+| `INVALID_INPUT` | terminate |
+| `SOURCE_DRIFT` | terminate |
+| `NO_PROGRESS` | terminate |
+| `ADMISSION_MISSING` | terminate |
+| `PROVISIONING_UNAVAILABLE` | terminate |
+| `LEASE_INVALID` | terminate |
+| `RUNTIME_UNAVAILABLE` | terminate |
+| `EVIDENCE_UNAVAILABLE` | terminate |
+| `FIXTURE_VIOLATION` | terminate |
+| `CANONICAL_WRITE_DENIED` | terminate |
+
+## Kế tiếp
+
+| Khi | Operator |
+| --- | --- |
+| cả ba làn đều pass | `git.publish` |
+| làn UI fail trên một node do ứng dụng sở hữu | `frontend.presentation.resolve` |
+| làn hành vi fail | `backend.source.apply` |
+| làn UX fail: người quyết định trải nghiệm phải thế nào, và luồng chỉ được kiểm lại sau quyết định ấy | `user` |