@starci/skills 1.1.0

package/operators/uat-verify/self-test.mjs

@@ -0,0 +1,270 @@
+// Proves validate.mjs on a synthetic session branch: a run a person asked for, admitted by both
+// receipts at the pinned commit, with a capture and a screenshot per frozen case, three independent
+// lanes, an appended run record and a moved latest pointer; a behaviour failure that routes to the
+// backend; a UX failure that routes to a person; a run blocked before it published anything; and one
+// mutation per law, each of which must fail with a line that names the defect. Two of the mutations
+// are the custody proof: the placeholder for the shared UAT password may appear in no file this
+// operator writes.
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { validateUatStep } from './validate.mjs';
+
+const FEATURE = 'enrollment';
+const FLOW = 'paid-enrollment';
+const RUN = 'run-2026-01-10-1';
+const NS = `uat-${RUN}`;
+const COMMIT = '1'.repeat(40);
+const OTHER_COMMIT = '2'.repeat(40);
+const FP = (c) => `sha256:${String(c).repeat(64)}`;
+const DIR = `.worktrees/uat/${FEATURE}/${FLOW}`;
+const SNAPSHOT_REF = `${DIR}/snapshot.json`;
+const T = (m) => new Date(Date.UTC(2026, 0, 10, 0, m, 0)).toISOString();
+const CASES = ['pay-and-enrol', 'abandon-checkout'];
+const ASSERTIONS = { 'pay-and-enrol': ['entry', 'commitment', 'terminal'], 'abandon-checkout': ['entry', 'recovery'] };
+const AUDIT_IN = 'step-1/parallel-1/response/response.md';
+const QUALITY_IN = 'step-2/parallel-1/response/response.md';
+// The placeholder this operator's law forbids anywhere it writes.
+const LEAK = 'UAT-SHARED-PASSWORD';
+
+const frozenCase = (caseId, i, over = {}) => ({ caseId, order: i + 1, assertions: [...ASSERTIONS[caseId]], ...over });
+
+function snapshot(over = {}) {
+  return {
+    runId: RUN, requestedBy: 'the product owner', feature: FEATURE, flow: FLOW, commit: COMMIT, frozenAt: T(10),
+    flowRoot: 'PATCHED-BY-WRITE-BRANCH', snapshotRef: SNAPSHOT_REF, snapshotFingerprint: FP(3),
+    lease: { leaseRef: `uat-lease://s-test/${FLOW}`, exclusive: true, expiresAt: T(180) },
+    admission: [
+      { kind: 'frontend-surface-audit', ref: AUDIT_IN, commit: COMMIT },
+      { kind: 'quality-verification', ref: QUALITY_IN, commit: COMMIT },
+    ],
+    account: {
+      username: `uat-${FLOW}`, role: 'learner', credentialName: 'uat-shared', credentialRef: '.stacks/local/secrets/uat.enc',
+      custody: 'sealed-shared-master-identity', isUat: true, plaintextRecorded: false,
+    },
+    fixtureNamespace: NS,
+    seed: { recordsRef: `${DIR}/seed/records.json`, expectedRef: `${DIR}/seed/expected.json`, fingerprint: FP(4), namespace: NS, isUat: true },
+    cases: CASES.map((c, i) => frozenCase(c, i)),
+    ...over,
+  };
+}
+
+const capture = (caseId, over = {}) => ({
+  caseId, runId: RUN, order: CASES.indexOf(caseId) + 1, executedAt: T(20 + CASES.indexOf(caseId)),
+  screenshotRef: `response/artifacts/${caseId}.png`, loginFieldMasked: true, outcome: 'pass',
+  assertions: ASSERTIONS[caseId].map((a) => ({ assertionId: a, lane: a === 'entry' ? 'ui' : 'behavior', observed: `the ${a} state was reached`, evidenceRef: `response/artifacts/${caseId}.png`, outcome: 'pass' })),
+  ...over,
+});
+
+const lane = (name, verdict = 'pass') => ({ lane: name, verdict, evidenceRefs: [`response/data/captures/${CASES[0]}.json`], statement: `the ${name} lane was judged on its own evidence` });
+const lanes = (over = {}) => ['behavior', 'ux', 'ui'].map((l) => lane(l, over[l] ?? 'pass'));
+
+function verdicts(over = {}) {
+  return {
+    runId: RUN, commit: COMMIT, resultRef: `${DIR}/runs/${RUN}/result.json`, latestRef: `${DIR}/latest`,
+    lanes: lanes(), cleanup: { performed: true, isUat: true, namespace: NS, runRecordsDeleted: false },
+    ...over,
+  };
+}
+
+function responseMd({ snap = snapshot(), verd = verdicts(), outcomes = { 'pay-and-enrol': 'pass', 'abandon-checkout': 'pass' }, note = 'The shared credential is named, never printed, and every login field is masked.' } = {}) {
+  return `# uat-flow-verification — ${snap.feature}/${snap.flow}
+
+The product owner asked for this run; it was admitted at one commit, executed case by case in the
+frozen order, and judged on three independent lanes. ${note}
+
+## Admission
+
+| Kind | Ref | Commit |
+| --- | --- | --- |
+${snap.admission.map((a) => `| \`${a.kind}\` | \`${a.ref}\` | \`${a.commit}\` |`).join('\n')}
+
+## Snapshot
+
+| Field | Value |
+| --- | --- |
+| Run | \`${snap.runId}\` |
+| Requested by | ${snap.requestedBy} |
+| Feature | \`${snap.feature}\` |
+| Flow | \`${snap.flow}\` |
+| Commit | \`${snap.commit}\` |
+| Snapshot | \`${snap.snapshotRef}\` |
+| Namespace | \`${snap.fixtureNamespace}\` |
+| Credential | \`${snap.account.credentialRef}\`, resolved by name at login only |
+| Run record | \`${verd.resultRef}\` |
+| Latest | \`${snap.runId}\` |
+
+## Cases
+
+| Case | Order | Assertions | Capture | Screenshot | Outcome |
+| --- | --- | --- | --- | --- | --- |
+${snap.cases.map((c) => `| \`${c.caseId}\` | ${c.order} | ${c.assertions.join(', ')} | \`response/data/captures/${c.caseId}.json\` | \`response/artifacts/${c.caseId}.png\` | ${outcomes[c.caseId] ?? 'pass'} |`).join('\n')}
+
+## Lanes
+
+| Lane | Verdict | Evidence |
+| --- | --- | --- |
+${verd.lanes.map((l) => `| \`${l.lane}\` | ${l.verdict} | \`${l.evidenceRefs[0]}\` |`).join('\n')}
+
+## Fallbacks taken
+
+| Code | Action |
+| --- | --- |
+`;
+}
+
+const requestJson = ({ extra = {}, inputs, cases = [...CASES] } = {}) => ({
+  schemaVersion: 9, operatorId: 'uat.verify', step: 3, parallel: 1, sessionId: 's-test',
+  contexts: [{ alias: '@workspaces/be', head: COMMIT }, { alias: '@worktrees/uat/enrollment/paid-enrollment', head: null }],
+  requirements: { requestedBy: 'the product owner', feature: FEATURE, flow: FLOW, cases, runId: RUN, lease: `uat-lease://s-test/${FLOW}`, resume: null, ...extra },
+  inputs: inputs ?? { 'frontend-surface-audit': AUDIT_IN, 'quality-verification': QUALITY_IN },
+  resume: null,
+});
+
+function responseJson({ status = 'done', stop, next = ['git.publish'], captures = CASES.map((c) => `response/data/captures/${c}.json`), shots = CASES.map((c) => `response/artifacts/${c}.png`), drop } = {}) {
+  const fields = {
+    'uat-flow-verification': 'response/response.md',
+    'uat-snapshot': 'response/data/snapshot.json',
+    'uat-capture': captures,
+    'uat-verdicts': 'response/data/verdicts.json',
+    screenshot: shots,
+    sheet: 'response/artifacts/sheet.png',
+  };
+  if (drop) delete fields[drop];
+  return { schemaVersion: 9, operatorId: 'uat.verify', step: 3, parallel: 1, status, ...(stop ? { stop } : {}), fallbacks: [], fields, commits: [], next };
+}
+
+// history: 'match' appends the record this run publishes; 'none' leaves no flow directory on disk;
+// 'missing-run' leaves the directory without the record; 'rewritten' leaves another result under the
+// same runId; 'stale-latest' points latest at another run.
+function writeBranch(files, history = 'match') {
+  const session = mkdtempSync(path.join(tmpdir(), 'uat-session-'));
+  const branch = path.join(session, 'step-3', 'parallel-1');
+  for (const d of ['request', 'response/data/captures', 'response/artifacts']) mkdirSync(path.join(branch, d), { recursive: true });
+  for (const input of [AUDIT_IN, QUALITY_IN]) {
+    mkdirSync(path.dirname(path.join(session, input)), { recursive: true });
+    writeFileSync(path.join(session, input), '# admitting receipt\n');
+  }
+  writeFileSync(path.join(session, 'state.json'), JSON.stringify({ id: 's-test', chain: [['3/1']], steps: { '3/1': 'uat.verify' }, current: '3/1', status: 'running' }));
+  for (const c of CASES) writeFileSync(path.join(branch, 'response', 'artifacts', `${c}.png`), 'png');
+  writeFileSync(path.join(branch, 'response', 'artifacts', 'sheet.png'), 'png');
+
+  const flowRoot = path.join(session, 'flow-root');
+  const prepared = { ...files };
+  const snap = prepared['response/data/snapshot.json'];
+  if (snap && typeof snap === 'object') prepared['response/data/snapshot.json'] = { ...snap, flowRoot };
+  for (const [name, content] of Object.entries(prepared)) {
+    if (content === null) continue;
+    writeFileSync(path.join(branch, name), typeof content === 'string' ? content : JSON.stringify(content, null, 2));
+  }
+
+  if (history !== 'none') {
+    mkdirSync(flowRoot, { recursive: true });
+    const verd = prepared['response/data/verdicts.json'];
+    if (history !== 'missing-run' && verd && typeof verd === 'object') {
+      const runDir = path.join(flowRoot, 'runs', verd.runId);
+      mkdirSync(runDir, { recursive: true });
+      const recorded = history === 'rewritten'
+        ? { runId: verd.runId, commit: OTHER_COMMIT, lanes: verd.lanes }
+        : { runId: verd.runId, commit: verd.commit, lanes: verd.lanes };
+      writeFileSync(path.join(runDir, 'result.json'), JSON.stringify(recorded, null, 2));
+    }
+    writeFileSync(path.join(flowRoot, 'latest'), history === 'stale-latest' ? 'run-2026-01-09-1' : RUN);
+  }
+  return { branch, session };
+}
+
+const baseline = () => ({
+  'request/request.json': requestJson(),
+  'response/response.json': responseJson(),
+  'response/response.md': responseMd(),
+  'response/data/snapshot.json': snapshot(),
+  'response/data/verdicts.json': verdicts(),
+  ...Object.fromEntries(CASES.map((c) => [`response/data/captures/${c}.json`, capture(c)])),
+});
+
+function withVerdicts(over, { next, outcomes } = {}) {
+  const verd = verdicts({ lanes: lanes(over) });
+  return {
+    ...baseline(),
+    'response/data/verdicts.json': verd,
+    'response/response.md': responseMd({ verd, outcomes }),
+    'response/response.json': responseJson({ next }),
+  };
+}
+
+const blocked = () => ({
+  'request/request.json': requestJson(),
+  'response/response.json': { schemaVersion: 9, operatorId: 'uat.verify', step: 3, parallel: 1, status: 'blocked', stop: 'ADMISSION_MISSING', fallbacks: [], fields: {}, commits: [], next: [] },
+});
+
+async function expectValid(files, label, history) {
+  const { branch, session } = writeBranch(files, history);
+  const { errors } = await validateUatStep(branch);
+  rmSync(session, { recursive: true, force: true });
+  assert.deepEqual(errors, [], `${label} should be valid`);
+}
+async function expectError(files, needle, label, history) {
+  const { branch, session } = writeBranch(files, history);
+  const { errors } = await validateUatStep(branch);
+  rmSync(session, { recursive: true, force: true });
+  assert.ok(errors.some((e) => e.includes(needle)), `${label}: expected an error containing "${needle}", got:\n${errors.join('\n') || '(none)'}`);
+}
+
+await expectValid(baseline(), 'a run a person asked for, admitted at the pinned commit, three lanes passing');
+await expectValid(withVerdicts({ behavior: 'fail' }, { next: ['backend.source.apply'], outcomes: { 'pay-and-enrol': 'fail', 'abandon-checkout': 'pass' } }), 'a behaviour failure routed to the backend');
+await expectValid(withVerdicts({ ux: 'fail' }, { next: ['user'], outcomes: { 'pay-and-enrol': 'fail', 'abandon-checkout': 'pass' } }), 'a UX failure routed to a person');
+await expectValid(blocked(), 'blocked on a missing admission, publishing nothing', 'none');
+
+// The gate and the person behind the run.
+await expectError({ ...baseline(), 'response/response.json': { ...responseJson(), stop: 'LEASE_INVALID' } }, 'only a blocked response carries a stop', 'a done branch carrying a stop');
+await expectValid({ ...blocked(), 'response/response.json': { schemaVersion: 9, operatorId: 'uat.verify', step: 3, parallel: 1, status: 'blocked', stop: 'RUNTIME_UNAVAILABLE', fallbacks: [], fields: {}, commits: [], next: [] } }, 'blocked on the shared RUNTIME_UNAVAILABLE code');
+await expectError({ ...baseline(), 'request/request.json': requestJson({ extra: { password: 'x' } }) }, 'requirements.password is not a field', 'a credential has nowhere to go in a request');
+await expectError({ ...baseline(), 'request/request.json': requestJson({ extra: { requestedBy: '' } }) }, 'required field requestedBy has no value', 'a run nobody asked for');
+await expectError({ ...baseline(), 'request/request.json': requestJson({ inputs: { 'frontend-surface-audit': AUDIT_IN } }) }, 'required input quality-verification is absent', 'a run admitted by one receipt only');
+
+// Admission at the pinned commit.
+await expectError({ ...baseline(), 'response/data/snapshot.json': snapshot({ admission: [{ kind: 'frontend-surface-audit', ref: AUDIT_IN, commit: COMMIT }, { kind: 'quality-verification', ref: QUALITY_IN, commit: OTHER_COMMIT }] }) }, 'ADMISSION_MISSING — quality-verification was taken at', 'an admission from another commit');
+await expectError({ ...baseline(), 'response/data/snapshot.json': snapshot({ admission: [{ kind: 'frontend-surface-audit', ref: AUDIT_IN, commit: COMMIT }, { kind: 'frontend-surface-audit', ref: AUDIT_IN, commit: COMMIT }] }) }, 'ADMISSION_MISSING — quality-verification is absent', 'a missing admission');
+await expectError({ ...baseline(), 'response/data/snapshot.json': snapshot({ admission: [{ kind: 'frontend-surface-audit', ref: 'step-9/parallel-1/response/response.md', commit: COMMIT }, { kind: 'quality-verification', ref: QUALITY_IN, commit: COMMIT }] }) }, 'but the request handed in', 'an admission the request never handed in');
+await expectError({ ...baseline(), 'response/data/snapshot.json': snapshot({ commit: OTHER_COMMIT }) }, 'but the request pinned @workspaces/be at', 'a snapshot frozen at another commit');
+await expectError({ ...baseline(), 'response/data/verdicts.json': verdicts({ commit: OTHER_COMMIT }) }, 'is not the pinned head', 'a result carrying another commit');
+
+// Three lanes, judged apart.
+await expectError({ ...baseline(), 'response/data/verdicts.json': verdicts({ lanes: [lane('behavior'), lane('ux')] }) }, 'the ui lane is missing', 'two lanes instead of three');
+await expectError({ ...baseline(), 'response/data/verdicts.json': verdicts({ lanes: [lane('behavior'), lane('behavior'), lane('ui')] }) }, 'a lane may report at most one verdict', 'one lane judged twice');
+await expectError({ ...baseline(), 'response/data/verdicts.json': verdicts({ lanes: [lane('behavior'), { ...lane('ux'), verdict: 'unavailable' }, lane('ui')] }) }, 'outside the allowed enum', 'a lane that is neither pass nor fail');
+await expectError({ ...baseline(), 'response/data/verdicts.json': verdicts({ lanes: [lane('behavior'), { ...lane('ux'), evidenceRefs: [] }, lane('ui')] }) }, 'array is too short', 'a lane with no evidence');
+await expectError({ ...withVerdicts({ behavior: 'fail' }, { next: ['git.publish'] }) }, 'a failing lane cannot hand to git.publish', 'a failing run handed to publication');
+await expectError({ ...baseline(), 'response/response.json': responseJson({ next: [] }) }, 'hands to git.publish', 'a passing run that routes nowhere');
+await expectError({ ...withVerdicts({ ux: 'fail' }, { next: ['backend.source.apply'] }) }, 'it hands to a person', 'a UX failure routed away from the person');
+
+// Evidence per case.
+await expectError({ ...baseline(), 'response/response.json': responseJson({ captures: [`response/data/captures/${CASES[0]}.json`] }), [`response/data/captures/${CASES[1]}.json`]: null }, `case ${CASES[1]} has no capture registered`, 'a frozen case with no capture');
+await expectError({ ...baseline(), 'response/response.json': responseJson({ shots: [`response/artifacts/${CASES[0]}.png`] }) }, `case ${CASES[1]} has no screenshot registered`, 'a frozen case with no screenshot');
+await expectError({ ...baseline(), [`response/data/captures/${CASES[0]}.json`]: capture(CASES[0], { loginFieldMasked: false }) }, 'expected true', 'a capture that cannot say the login field was masked');
+await expectError({ ...baseline(), [`response/data/captures/${CASES[0]}.json`]: capture(CASES[0], { executedAt: T(5) }) }, 'executed at or before the snapshot freeze', 'a case executed before the freeze');
+await expectError({ ...baseline(), [`response/data/captures/${CASES[0]}.json`]: capture(CASES[0], { assertions: capture(CASES[0]).assertions.slice(0, 2) }) }, 'was never observed', 'a frozen assertion nobody observed');
+await expectError({ ...baseline(), 'response/data/snapshot.json': snapshot({ cases: [frozenCase(CASES[0], 1), frozenCase(CASES[1], 2)] }) }, 'contiguous order starting at 1', 'a frozen order that starts at two');
+await expectError({ ...baseline(), 'request/request.json': requestJson({ cases: [CASES[0], 'ghost-case'] }) }, 'requested case ghost-case was never frozen', 'a case the snapshot never froze');
+
+// Custody: the password may appear in nothing this operator writes.
+await expectError({ ...baseline(), 'response/response.md': responseMd({ note: `The tester signed in with ${LEAK} and continued.` }) }, 'the shared UAT password appears in a file this operator writes', 'the password published in the receipt');
+await expectError({ ...baseline(), [`response/data/captures/${CASES[0]}.json`]: capture(CASES[0], { assertions: [{ assertionId: 'entry', lane: 'ui', observed: `the login form held ${LEAK}`, evidenceRef: 'x', outcome: 'pass' }, { assertionId: 'commitment', lane: 'behavior', observed: 'ok', evidenceRef: 'x', outcome: 'pass' }, { assertionId: 'terminal', lane: 'behavior', observed: 'ok', evidenceRef: 'x', outcome: 'pass' }] }) }, 'the shared UAT password appears in a file this operator writes', 'the password recorded in a capture');
+await expectError({ ...baseline(), 'response/data/snapshot.json': snapshot({ account: { ...snapshot().account, password: 'x' } }) }, 'unexpected property', 'an account record with a place to hold a secret');
+await expectError({ ...baseline(), 'response/data/snapshot.json': snapshot({ account: { ...snapshot().account, credentialRef: '.stacks/local/secrets/uat.txt' } }) }, 'string does not match', 'a credential outside the sealed file');
+
+// Namespace and append-only history.
+await expectError({ ...baseline(), 'response/data/verdicts.json': verdicts({ cleanup: { performed: true, isUat: true, namespace: 'uat-anything', runRecordsDeleted: false } }) }, 'cleanup must name the exact run fixture namespace', 'a cleanup wider than the run');
+await expectError({ ...baseline(), 'response/data/verdicts.json': verdicts({ cleanup: { performed: true, isUat: true, namespace: NS, runRecordsDeleted: true } }) }, 'expected false', 'a cleanup that deleted a run record');
+await expectError(baseline(), 'runs are append-only', 'a run record rewritten with another result', 'rewritten');
+await expectError(baseline(), 'appends its record under runs/', 'a decided run that appended nothing', 'missing-run');
+await expectError(baseline(), 'but this run published', 'a latest pointer left on another run', 'stale-latest');
+
+// The receipt agrees with the machine record.
+await expectError({ ...baseline(), 'response/response.md': responseMd().replace(`| Commit | \`${COMMIT}\` |`, `| Commit | \`${OTHER_COMMIT}\` |`) }, 'Snapshot names another commit', 'a receipt naming another commit');
+await expectError({ ...baseline(), 'response/response.md': responseMd().replace('## Cases', '## Case list') }, 'missing section ^## Cases$', 'a receipt section renamed');
+await expectError({ ...baseline(), 'response/response.json': responseJson({ drop: 'uat-verdicts' }) }, 'required output uat-verdicts is not in fields', 'a decided run that published no verdicts');
+
+process.stdout.write('uat.verify self-test: 4 valid branches, 36 rejected mutations\n');

package/operators/uat-verify/validate.mjs

@@ -0,0 +1,202 @@
+// uat.verify's own law over one branch, on top of the shared step check: a person asked for the run;
+// both admissions are present and taken at the pinned commit; the snapshot froze the requested cases
+// in a contiguous order; every frozen case has a capture and a screenshot; the verdicts carry exactly
+// the three independent lanes; the published result carries the pinned commit; cleanup deletes the run
+// namespace and never a run record; the run history is append-only; and no capture, snapshot, verdict
+// or published sentence contains the password. Masking is proved, not promised: the chosen placeholder
+// for the shared UAT password may appear nowhere this operator writes.
+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 LANES = ['behavior', 'ux', 'ui'];
+const ADMISSIONS = ['frontend-surface-audit', 'quality-verification'];
+// The password placeholder this operator's self-test injects, plus any inline assignment of one. The
+// shared UAT password is resolved by name at login; a run that wrote it anywhere failed its custody.
+export const PASSWORD_LEAK = /uat-shared-password|password\s*[:=]\s*\S/i;
+const empty = (v) => v === undefined || v === null || v === '' || v === '—';
+const asList = (v) => (Array.isArray(v) ? v : v === undefined || v === null ? [] : [v]);
+
+export async function validateUatStep(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 !== 'uat.verify') return { errors };
+  const has = (f) => existsSync(path.join(branchDir, f));
+  const read = (f) => readFile(path.join(branchDir, f), 'utf8');
+  const decided = response.status === 'done';
+
+  // UAT is never routine: a run exists because a person asked for it, and the run identifier and the
+  // exclusive lease arrive from the orchestrator rather than from a person.
+  if (empty(requirements.requestedBy)) errors.push('request.json: UAT runs only when a person asked; requestedBy has no value');
+  if (decided && empty(requirements.runId)) errors.push('request.json: the orchestrator supplies runId; a decided run cannot namespace its records without one');
+  if (decided && empty(requirements.lease)) errors.push('request.json: the orchestrator supplies the exclusive lease; a decided run cannot write the flow directory without one');
+
+  const pinned = (request?.contexts ?? []).find((c) => c.alias === '@workspaces/be')?.head ?? null;
+
+  let snapshot = null;
+  if (present.has('uat-snapshot') && has('response/data/snapshot.json')) {
+    try { snapshot = JSON.parse(await read('response/data/snapshot.json')); } catch { snapshot = null; }
+  } else if (decided) errors.push('response/data/snapshot.json: a done branch needs the frozen snapshot');
+  let verdicts = null;
+  if (present.has('uat-verdicts') && has('response/data/verdicts.json')) {
+    try { verdicts = JSON.parse(await read('response/data/verdicts.json')); } catch { verdicts = null; }
+  } else if (decided) errors.push('response/data/verdicts.json: a done branch needs the three lane verdicts');
+
+  if (snapshot) {
+    if (!empty(requirements.feature) && snapshot.feature !== requirements.feature) errors.push('response/data/snapshot.json: the snapshot names another feature');
+    if (!empty(requirements.flow) && snapshot.flow !== requirements.flow) errors.push('response/data/snapshot.json: the snapshot names another flow');
+    if (!empty(requirements.runId) && snapshot.runId !== requirements.runId) errors.push('response/data/snapshot.json: the snapshot names another runId');
+    if (!empty(requirements.requestedBy) && snapshot.requestedBy !== requirements.requestedBy) errors.push('response/data/snapshot.json: the snapshot names another requester than the person who asked');
+    if (snapshot.fixtureNamespace !== `uat-${snapshot.runId}`) errors.push(`response/data/snapshot.json: the fixture namespace must be uat-${snapshot.runId}, so cleanup can name exactly what this run wrote`);
+    if (snapshot.seed.namespace !== snapshot.fixtureNamespace) errors.push('response/data/snapshot.json: the seed namespace must equal the run fixture namespace');
+    if (pinned !== null && snapshot.commit !== pinned) errors.push(`response/data/snapshot.json: the snapshot froze commit ${snapshot.commit} but the request pinned @workspaces/be at ${pinned}`);
+    if (!snapshot.snapshotRef.startsWith(`.worktrees/uat/${snapshot.feature}/${snapshot.flow}/`)) errors.push('response/data/snapshot.json: the snapshot path must address this feature and flow');
+
+    // Admission: both receipts, both at the pinned head, both the files the request handed in.
+    const byKind = new Map(snapshot.admission.map((a) => [a.kind, a]));
+    for (const kind of ADMISSIONS) {
+      const entry = byKind.get(kind);
+      if (!entry) { errors.push(`response/data/snapshot.json: ADMISSION_MISSING — ${kind} is absent from the admission record`); continue; }
+      if (entry.commit !== snapshot.commit) errors.push(`response/data/snapshot.json: ADMISSION_MISSING — ${kind} was taken at ${entry.commit}, not at the pinned commit ${snapshot.commit}`);
+      const given = request?.inputs?.[kind];
+      if (given === undefined) errors.push(`request.json: ADMISSION_MISSING — input ${kind} is absent`);
+      else if (entry.ref !== given) errors.push(`response/data/snapshot.json: ${kind} admits ${entry.ref}, but the request handed in ${given}`);
+    }
+
+    // The frozen order is declared in advance, not discovered while running.
+    const ids = snapshot.cases.map((c) => c.caseId);
+    if (new Set(ids).size !== ids.length) errors.push('response/data/snapshot.json: the snapshot freezes the same case twice');
+    [...snapshot.cases].map((c) => c.order).sort((a, b) => a - b).forEach((order, i) => {
+      if (order !== i + 1) errors.push('response/data/snapshot.json: the frozen cases must carry a contiguous order starting at 1');
+    });
+    const asked = asList(requirements.cases).map(String);
+    if (asked.length) {
+      for (const c of asked) if (!ids.includes(c)) errors.push(`response/data/snapshot.json: requested case ${c} was never frozen`);
+      for (const c of ids) if (!asked.includes(c)) errors.push(`response/data/snapshot.json: case ${c} was frozen but the request did not ask for it`);
+    }
+
+    // Every frozen case leaves both kinds of evidence, and every registered artifact belongs to a case.
+    const captureFiles = new Set(asList(response.fields?.['uat-capture']));
+    const shots = new Set(asList(response.fields?.screenshot));
+    if (decided) {
+      for (const c of snapshot.cases) {
+        const capture = `response/data/captures/${c.caseId}.json`;
+        const shot = `response/artifacts/${c.caseId}.png`;
+        if (!captureFiles.has(capture)) errors.push(`response/response.json: case ${c.caseId} has no capture registered at ${capture}`);
+        if (!shots.has(shot)) errors.push(`response/response.json: case ${c.caseId} has no screenshot registered at ${shot}`);
+      }
+      for (const f of captureFiles) if (!ids.some((id) => f === `response/data/captures/${id}.json`)) errors.push(`response/response.json: the capture ${f} belongs to no frozen case`);
+      for (const f of shots) if (!ids.some((id) => f === `response/artifacts/${id}.png`)) errors.push(`response/response.json: the screenshot ${f} belongs to no frozen case`);
+    }
+
+    const frozenById = new Map(snapshot.cases.map((c) => [c.caseId, c]));
+    for (const f of captureFiles) {
+      if (!has(f)) continue;
+      let capture; try { capture = JSON.parse(await read(f)); } catch { continue; }
+      const frozen = frozenById.get(capture.caseId);
+      if (!frozen) { errors.push(`${f}: case ${capture.caseId} was captured without being frozen into the snapshot`); continue; }
+      if (capture.order !== frozen.order) errors.push(`${f}: case ${capture.caseId} was executed out of its frozen order`);
+      if (!empty(snapshot.runId) && capture.runId !== snapshot.runId) errors.push(`${f}: the capture belongs to run ${capture.runId}, not ${snapshot.runId}`);
+      if (capture.screenshotRef !== `response/artifacts/${capture.caseId}.png`) errors.push(`${f}: the capture must point at its own case screenshot`);
+      if (Date.parse(capture.executedAt) <= Date.parse(snapshot.frozenAt)) errors.push(`${f}: case ${capture.caseId} executed at or before the snapshot freeze`);
+      const seen = new Set(capture.assertions.map((a) => a.assertionId));
+      for (const a of frozen.assertions) if (!seen.has(a)) errors.push(`${f}: the frozen assertion ${a} was never observed`);
+      for (const a of capture.assertions) if (!frozen.assertions.includes(a.assertionId)) errors.push(`${f}: the assertion ${a.assertionId} was never frozen`);
+    }
+  }
+
+  if (verdicts) {
+    const names = verdicts.lanes.map((l) => l.lane);
+    for (const lane of LANES) if (!names.includes(lane)) errors.push(`response/data/verdicts.json: the ${lane} lane is missing; the three lanes are judged apart and all three are published`);
+    for (const name of names) if (!LANES.includes(name)) errors.push(`response/data/verdicts.json: ${name} is not one of the three lanes`);
+    if (new Set(names).size !== names.length) errors.push('response/data/verdicts.json: a lane may report at most one verdict');
+    if (snapshot) {
+      if (verdicts.runId !== snapshot.runId) errors.push('response/data/verdicts.json: the result belongs to another run than the snapshot');
+      if (verdicts.commit !== snapshot.commit) errors.push(`response/data/verdicts.json: the result carries commit ${verdicts.commit} but the run was pinned at ${snapshot.commit}`);
+      if (verdicts.resultRef !== `${snapshot.snapshotRef.replace(/snapshot\.json$/, '')}runs/${snapshot.runId}/result.json`) errors.push('response/data/verdicts.json: the result must be appended under runs/<runId>/ of this flow directory');
+      if (verdicts.latestRef !== `${snapshot.snapshotRef.replace(/snapshot\.json$/, '')}latest`) errors.push('response/data/verdicts.json: latest must be the pointer of this flow directory');
+      if (verdicts.cleanup.namespace !== snapshot.fixtureNamespace) errors.push('response/data/verdicts.json: cleanup must name the exact run fixture namespace and nothing wider');
+    }
+    if (pinned !== null && verdicts.commit !== pinned) errors.push(`response/data/verdicts.json: the result commit ${verdicts.commit} is not the pinned head ${pinned}`);
+    if (decided && !verdicts.cleanup.performed) errors.push('response/data/verdicts.json: a decided run cleans its own namespace before it publishes');
+
+    const failing = verdicts.lanes.filter((l) => l.verdict === 'fail').map((l) => l.lane);
+    const next = new Set(response.next ?? []);
+    if (decided && !failing.length && !next.has('git.publish')) errors.push('response/response.json: all three lanes pass, so the run hands to git.publish');
+    if (decided && failing.includes('behavior') && !next.has('backend.source.apply')) errors.push('response/response.json: the behaviour lane failed, so the run hands to backend.source.apply');
+    if (decided && failing.includes('ux') && !next.has('user')) errors.push('response/response.json: a UX failure is a question of intent; it hands to a person, and the flow is verified again only after that decision');
+    if (decided && failing.length && next.has('git.publish')) errors.push('response/response.json: a failing lane cannot hand to git.publish');
+  }
+
+  if (present.has('uat-flow-verification') && has('response/response.md')) {
+    const text = await read('response/response.md');
+    const snap = Object.fromEntries((tableUnder(text, '## Snapshot') ?? []).map(([k, v]) => [k, v]));
+    if (snapshot) {
+      if (snap.Run !== snapshot.runId) errors.push(`response/response.md: Snapshot names run ${snap.Run}, the frozen snapshot names ${snapshot.runId}`);
+      if (snap.Feature !== snapshot.feature) errors.push('response/response.md: Snapshot names another feature');
+      if (snap.Flow !== snapshot.flow) errors.push('response/response.md: Snapshot names another flow');
+      if (snap.Commit !== snapshot.commit) errors.push('response/response.md: Snapshot names another commit than the frozen one');
+      if (snap.Namespace !== snapshot.fixtureNamespace) errors.push('response/response.md: Snapshot names another fixture namespace');
+      if (snap['Requested by'] !== snapshot.requestedBy) errors.push('response/response.md: Snapshot names another requester');
+      const admission = tableUnder(text, '## Admission') ?? [];
+      for (const [kind, ref, commit] of admission) {
+        const entry = snapshot.admission.find((a) => a.kind === kind);
+        if (!entry) { errors.push(`response/response.md: Admission names ${kind}, which the snapshot did not record`); continue; }
+        if (entry.ref !== ref || entry.commit !== commit) errors.push(`response/response.md: the ${kind} admission differs from the frozen record`);
+      }
+      const cases = tableUnder(text, '## Cases') ?? [];
+      if (cases.length !== snapshot.cases.length) errors.push(`response/response.md: Cases has ${cases.length} rows, the snapshot froze ${snapshot.cases.length}`);
+    }
+    if (verdicts) {
+      const lanes = tableUnder(text, '## Lanes') ?? [];
+      for (const [lane, verdict] of lanes) {
+        const entry = verdicts.lanes.find((l) => l.lane === lane);
+        if (!entry) { errors.push(`response/response.md: Lanes names ${lane}, which the verdicts do not`); continue; }
+        if (entry.verdict !== verdict) errors.push(`response/response.md: the ${lane} lane reads ${verdict} but the verdicts say ${entry.verdict}`);
+      }
+    }
+  } else if (decided) errors.push('response/response.md: a done branch needs the verification receipt');
+
+  // Custody is proved on the written bytes, not asserted in prose.
+  const scanned = ['response/response.md', 'response/data/snapshot.json', 'response/data/verdicts.json', ...asList(response.fields?.['uat-capture'])];
+  for (const f of scanned) {
+    if (!has(f)) continue;
+    if (PASSWORD_LEAK.test(await read(f))) errors.push(`${f}: the shared UAT password appears in a file this operator writes; the credential is resolved by name at login and is never recorded`);
+  }
+
+  // The run history is append-only: a run folder that exists already is never rewritten.
+  if (snapshot && verdicts && existsSync(snapshot.flowRoot)) {
+    const runDir = path.join(snapshot.flowRoot, 'runs', snapshot.runId);
+    const resultFile = path.join(runDir, 'result.json');
+    if (existsSync(resultFile)) {
+      let recorded = null;
+      try { recorded = JSON.parse(await readFile(resultFile, 'utf8')); } catch { recorded = null; }
+      if (recorded === null) errors.push(`${snapshot.snapshotRef.replace(/snapshot\.json$/, '')}runs/${snapshot.runId}/result.json: the existing run record cannot be read, and a run record is never overwritten`);
+      else {
+        const same = recorded.runId === verdicts.runId && recorded.commit === verdicts.commit
+          && JSON.stringify(recorded.lanes) === JSON.stringify(verdicts.lanes);
+        if (!same) errors.push(`runs/${snapshot.runId}: a run record already exists with a different result; runs are append-only, so a second attempt is a new runId`);
+      }
+    } else if (decided) errors.push(`runs/${snapshot.runId}: a decided run appends its record under runs/<runId>/ before it emits`);
+    const latestFile = path.join(snapshot.flowRoot, 'latest');
+    if (decided && existsSync(latestFile)) {
+      const latest = (await readFile(latestFile, 'utf8')).trim();
+      if (latest !== snapshot.runId) errors.push(`latest: points at ${latest}, but this run published ${snapshot.runId}`);
+    }
+  }
+
+  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 validateUatStep(path.resolve(target));
+  if (errors.length) { process.stderr.write(`${errors.join('\n')}\n`); process.exitCode = 1; } else process.stdout.write('valid uat.verify branch\n');
+}

package/operators/workspace-bind/errors.json

@@ -0,0 +1,90 @@
+{
+  "schemaVersion": 9,
+  "note": "Stop codes only workspace.bind emits. Same entry shape as operators/errors.json, scope implicit. Shared codes (INVALID_INPUT, SOURCE_DRIFT, NO_PROGRESS) come from operators/errors.json, and BRANCH_POLICY_VIOLATION is not defined here because git.publish emits it too: a code two operators emit belongs in operators/errors.json with both ids in scope. Every domain below is the one the old package's OWNING_DOMAIN table published, and routing.json answers each of them for this operator: workspace resumes, source resumes, identity and runtime are external, caller is a person.",
+  "codes": {
+    "IDENTITY_UNVERIFIED": {
+      "domain": "identity",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "The machine identity or its encrypted credential roster is missing or stale.",
+        "vi": "Định danh máy hoặc roster credential đã mã hoá của nó thiếu hoặc cũ."
+      },
+      "resume": {
+        "en": "Verify the machine identity and seal its roster.",
+        "vi": "Xác minh định danh máy và niêm phong roster của nó."
+      }
+    },
+    "ROUTE_UNDECLARED": {
+      "domain": "workspace",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "No portable declaration names this project and role.",
+        "vi": "Không khai báo portable nào gọi tên project và role này."
+      },
+      "resume": {
+        "en": "Declare the route; this operator never repairs one.",
+        "vi": "Khai báo route; operator này không bao giờ tự sửa."
+      }
+    },
+    "ROUTE_UNHYDRATED": {
+      "domain": "workspace",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "The declaration exists but no local route projects it onto this machine.",
+        "vi": "Khai báo có tồn tại nhưng không route local nào chiếu nó xuống máy này."
+      },
+      "resume": {
+        "en": "Hydrate the route on this machine.",
+        "vi": "Hydrate route trên máy này."
+      }
+    },
+    "ROUTE_MISMATCH": {
+      "domain": "workspace",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "The hydrated route disagrees with the closed portable route, or belongs to another Source.",
+        "vi": "Route đã hydrate mâu thuẫn với route portable đóng, hoặc thuộc về một Source khác."
+      },
+      "resume": {
+        "en": "Correct the hydration.",
+        "vi": "Sửa lại phần hydrate."
+      }
+    },
+    "CHECKOUT_DIRTY": {
+      "domain": "source",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "Something is dirty outside the declared write roots.",
+        "vi": "Có thứ đang bẩn ngoài các write root đã khai báo."
+      },
+      "resume": {
+        "en": "Clean the boundary, or declare the write roots that cover it; this operator never stashes.",
+        "vi": "Dọn sạch ranh giới, hoặc khai báo write root bao được nó; operator này không bao giờ stash."
+      }
+    },
+    "ENDPOINT_AUTHORITY_STALE": {
+      "domain": "runtime",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "The endpoint binding is not the closed port projection, or its fingerprint is stale.",
+        "vi": "Ràng buộc endpoint không phải phép chiếu port đóng, hoặc fingerprint của nó đã cũ."
+      },
+      "resume": {
+        "en": "Recompute the authority fingerprint at its owner.",
+        "vi": "Tính lại fingerprint thẩm quyền ở phía chủ của nó."
+      }
+    },
+    "RUNTIME_NOT_READY": {
+      "domain": "runtime",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "The runtime owner registry is missing, stale, or not ready while the caller must consume it.",
+        "vi": "Registry chủ runtime thiếu, cũ hoặc chưa sẵn sàng trong khi người gọi phải tiêu thụ nó."
+      },
+      "resume": {
+        "en": "Raise one coordination request to the registered owner and wait for a ready generation.",
+        "vi": "Nêu một yêu cầu phối hợp tới chủ đã đăng ký và chờ một generation sẵn sàng."
+      }
+    }
+  }
+}

package/operators/workspace-bind/operator.json

@@ -0,0 +1,21 @@
+{
+  "schemaVersion": 9,
+  "id": "workspace.bind",
+  "domain": "workspace",
+  "job": "Resolve one project and role into a verified checkout identity, its exact source head, and the closed runtime binding it may consume, and return that as one typed route receipt.",
+  "package": "operator.md",
+  "errors": "errors.json",
+  "validator": "validate.mjs",
+  "selfTest": "self-test.mjs",
+  "resources": {
+    "profile": "luna",
+    "grammarBound": false,
+    "tools": {
+      "@tools/fileread": "context-aliases",
+      "@tools/git": "read",
+      "@tools/shell": "declared-commands",
+      "@tools/http": "probe",
+      "@tools/secrets": "resolve-by-name"
+    }
+  }
+}