@starci/skills 1.1.0

package/operators/platform-operate/validate.mjs

@@ -0,0 +1,193 @@
+// platform.operate's own law over one branch, on top of the shared step check: the branch's closed
+// effect, proof and capability sets; the approved plan hash and the approval that covers it; every
+// desired resource inventoried under the same kind and inside the mutable ceiling; port claims owned
+// by this operation and never freed by mutating their holder; every mutation inventoried first and
+// inside the approved set; convergence agreeing with the mutation count; the complete proof set
+// passed before an operated outcome; and no capability handle or credential-shaped token anywhere.
+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)), '..', '..');
+
+// The three service kinds are branches of one job. Each publishes its own closed effect set, its own
+// required proof set, and the exact capabilities it needs; a cross-filed effect is how an unapproved
+// change acquires the appearance of authority.
+export const KIND_EFFECTS = {
+  observability: ['update-config', 'restart-service', 'upsert-dashboard', 'update-remote-write'],
+  sonar: ['create-project', 'assign-profile', 'assign-gate', 'enforce-setting'],
+  tunnel: ['create-tunnel', 'update-tunnel-route', 'upsert-proxied-dns'],
+};
+export const KIND_CHECKS = {
+  observability: ['service-health', 'target-boundary', 'label-boundary', 'remote-write-delivery', 'sample-ordering', 'retry-backoff', 'sensitive-data-filter'],
+  sonar: ['service-available', 'project-exists', 'source-revision', 'profile-assigned', 'gate-assigned', 'enforcement-active'],
+  tunnel: ['dns-target', 'tunnel-route', 'tls', 'public-https'],
+};
+export const KIND_CAPABILITIES = {
+  observability: ['metrics:remote-write'],
+  sonar: ['sonar:project-admin'],
+  tunnel: ['tunnel:write', 'dns:write'],
+};
+
+// A credential is resolved for use, never written down. Fingerprints and commit heads are legitimate
+// long hex, so they are scrubbed before the unbroken-run heuristic runs.
+export function credentialLeak(value) {
+  if (value.includes('capability://')) return true;
+  const scrubbed = value.replaceAll(/sha256:[0-9a-f]{64}/g, '').replaceAll(/\b[0-9a-f]{40}\b/g, '');
+  if (/(?:token|secret|password|api[_-]?key|bearer|authorization)\s*[:=]\s*\S/i.test(scrubbed)) return true;
+  return /[A-Za-z0-9+=]{32,}/.test(scrubbed);
+}
+function forEachString(value, visit, at = '$') {
+  if (typeof value === 'string') return visit(value, at);
+  if (Array.isArray(value)) { value.forEach((item, i) => forEachString(item, visit, `${at}[${i}]`)); return; }
+  if (value !== null && typeof value === 'object') for (const [k, child] of Object.entries(value)) forEachString(child, visit, `${at}.${k}`);
+}
+const empty = (v) => v === undefined || v === null || v === '' || v === '—';
+const asList = (v) => (Array.isArray(v) ? v : []);
+
+export async function validatePlatformStep(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 !== 'platform.operate') return { errors };
+  const has = (f) => existsSync(path.join(branchDir, f));
+  const read = (f) => readFile(path.join(branchDir, f), 'utf8');
+
+  const desired = requirements.desiredState ?? {};
+  const kind = String(desired.serviceKind ?? '');
+  const desiredEffects = asList(desired.effects);
+  const desiredResources = asList(desired.resourceRefs);
+  const mutable = new Set(asList(desired.mutableResourceRefs));
+  const observationOnly = new Set(asList(desired.observationOnlyResourceRefs));
+  const portClaims = asList(requirements.portClaims);
+  const service = requirements.service;
+
+  if (empty(requirements.approval)) errors.push('request.json: approval has no default; changing a shared runtime is never something an agent decides alone');
+  if (kind && !KIND_EFFECTS[kind]) errors.push(`request.json: ${kind} is not a service kind this operator operates`);
+  if (KIND_EFFECTS[kind]) {
+    if (new Set(desiredEffects).size !== desiredEffects.length) errors.push('request.json: desiredState.effects must not repeat an effect');
+    for (const e of desiredEffects) if (!KIND_EFFECTS[kind].includes(e)) errors.push(`request.json: requested effect ${e} does not belong to the ${kind} service kind`);
+  }
+  if (!empty(service) && mutable.size && !mutable.has(service)) errors.push('request.json: the operated service must be inside desiredState.mutableResourceRefs');
+  for (const r of mutable) if (observationOnly.has(r)) errors.push(`request.json: resource ${r} cannot be both mutable and observation-only`);
+  for (const r of desiredResources) if (mutable.size && !mutable.has(r)) errors.push(`request.json: desired resource ${r} lies outside the mutable ceiling`);
+  const claimedPorts = portClaims.map((c) => c.port);
+  if (new Set(claimedPorts).size !== claimedPorts.length) errors.push('request.json: portClaims must not claim the same port twice');
+  for (const c of portClaims) if (desiredResources.length && !desiredResources.includes(c.resourceRef)) errors.push(`request.json: port ${c.port} is claimed for ${c.resourceRef}, which this operation does not own`);
+  // The input contract refuses any string that carries credential material.
+  forEachString(request?.requirements ?? {}, (text, at) => { if (credentialLeak(text)) errors.push(`request.json: ${at} carries a credential value, which cannot enter the operator contract`); });
+
+  let delta = null;
+  if (present.has('delta') && has('response/data/delta.json')) { try { delta = JSON.parse(await read('response/data/delta.json')); } catch { delta = null; } }
+  let checks = null;
+  if (present.has('checks') && has('response/data/checks.json')) { try { checks = JSON.parse(await read('response/data/checks.json')); } catch { checks = null; } }
+
+  let inventoried = new Set();
+  if (delta) {
+    const refs = delta.inventoriedResources.map((r) => r.resourceRef);
+    inventoried = new Set(refs);
+    if (new Set(refs).size !== refs.length) errors.push('response/data/delta.json: inventoriedResources must not list a resource twice');
+    const ports = delta.observedPortHolders.map((h) => h.port);
+    if (new Set(ports).size !== ports.length) errors.push('response/data/delta.json: observedPortHolders must not list the same port twice');
+    if (!empty(service) && delta.serviceRef !== service) errors.push('response/data/delta.json: the delta operates a service the request did not name');
+    if (!empty(service) && !inventoried.has(service)) errors.push(`response/data/delta.json: service ${service} was not inventoried before the operation`);
+    if (kind && delta.serviceKind !== kind) errors.push(`response/data/delta.json: the delta names the ${delta.serviceKind} branch, not ${kind}`);
+    const byRef = new Map(delta.inventoriedResources.map((r) => [r.resourceRef, r]));
+    for (const r of desiredResources) {
+      const res = byRef.get(r);
+      if (!res) errors.push(`response/data/delta.json: desired resource ${r} is absent from the bound inventory`);
+      else if (res.kind !== kind) errors.push(`response/data/delta.json: resource ${r} belongs to the ${res.kind} branch and is outside this ${kind} operation`);
+    }
+    if (!empty(requirements.approval) && delta.approvalRef !== requirements.approval) errors.push('response/data/delta.json: the bound approval is not the one the request declared');
+    if (!empty(desired.planSha256) && delta.planSha256 !== desired.planSha256) errors.push('response/data/delta.json: planSha256 must equal the approved plan hash');
+    for (const e of delta.allowedEffects) if (KIND_EFFECTS[kind] && !KIND_EFFECTS[kind].includes(e)) errors.push(`response/data/delta.json: approved effect ${e} does not belong to the ${kind} service kind`);
+    for (const e of desiredEffects) if (!delta.allowedEffects.includes(e)) errors.push(`response/data/delta.json: requested effect ${e} is outside the approved effect set`);
+
+    const held = delta.capabilities.map((c) => c.capability);
+    if (new Set(held).size !== held.length) errors.push('response/data/delta.json: capabilities must not repeat a capability');
+    for (const c of held) if (KIND_CAPABILITIES[kind] && !KIND_CAPABILITIES[kind].includes(c)) errors.push(`response/data/delta.json: capability ${c} is not used by the ${kind} branch`);
+    for (const c of KIND_CAPABILITIES[kind] ?? []) if (!held.includes(c)) errors.push(`response/data/delta.json: the ${kind} branch requires the ${c} capability`);
+
+    const portHolderRefs = new Set(delta.observedPortHolders.map((h) => h.holderRef));
+    const applied = new Set(delta.appliedEffects);
+    const mutatedEffects = new Set();
+    for (const m of delta.mutations) {
+      if (KIND_EFFECTS[kind] && !KIND_EFFECTS[kind].includes(m.effect)) errors.push(`response/data/delta.json: effect ${m.effect} does not belong to the ${kind} service kind`);
+      if (!applied.has(m.effect)) errors.push(`response/data/delta.json: mutation effect ${m.effect} is absent from appliedEffects`);
+      mutatedEffects.add(m.effect);
+      if (!inventoried.has(m.resourceRef)) errors.push(`response/data/delta.json: resource ${m.resourceRef} was mutated without being inventoried first`);
+      // A port already in use is a coordination finding, never permission to reclaim it.
+      if (portHolderRefs.has(m.resourceRef)) errors.push(`response/data/delta.json: resource ${m.resourceRef} holds a claimed port and must never be mutated to free it`);
+      if (delta.mutableResourceRefs.length && !delta.mutableResourceRefs.includes(m.resourceRef)) errors.push(`response/data/delta.json: resource ${m.resourceRef} was mutated outside the mutable ceiling`);
+    }
+    for (const e of applied) if (!mutatedEffects.has(e)) errors.push(`response/data/delta.json: applied effect ${e} records no mutation`);
+    if (delta.convergence === 'already-converged' && delta.mutations.length > 0) errors.push('response/data/delta.json: an already-converged operation cannot report a mutation');
+    if (delta.convergence === 'converged' && delta.mutations.length === 0) errors.push('response/data/delta.json: a converged operation must report the mutation that converged it');
+    // The receipt is durable; a durable record of a capability is a leaked credential with a delay.
+    forEachString(delta, (text, at) => { if (credentialLeak(text)) errors.push(`response/data/delta.json: ${at} records a credential, which the receipt refuses`); });
+  } else if (response.status === 'done') errors.push('response/data/delta.json: a done branch needs the derived and applied delta');
+
+  let findingCount = 0;
+  if (checks) {
+    if (!empty(service) && checks.serviceRef !== service) errors.push('response/data/checks.json: the proof set names a service the request did not operate');
+    if (kind && checks.serviceKind !== kind) errors.push('response/data/checks.json: the proof set names another service kind');
+    // The required proof set is the whole set the branch publishes; the caller cannot ask for less.
+    const requested = new Set(checks.requiredCheckNames);
+    for (const n of KIND_CHECKS[kind] ?? []) if (!requested.has(n)) errors.push(`response/data/checks.json: the ${kind} branch must require the ${n} check`);
+    for (const n of requested) if (KIND_CHECKS[kind] && !KIND_CHECKS[kind].includes(n)) errors.push(`response/data/checks.json: check ${n} does not belong to the ${kind} service kind`);
+
+    const seen = new Set();
+    const proved = new Set();
+    for (const c of checks.checks) {
+      const key = `${c.name}|${c.resourceRef}`;
+      if (seen.has(key)) errors.push(`response/data/checks.json: check ${c.name} is recorded twice for ${c.resourceRef}`);
+      seen.add(key);
+      if (delta && !inventoried.has(c.resourceRef)) errors.push(`response/data/checks.json: check ${c.name} names uninventoried resource ${c.resourceRef}`);
+      if (c.status === 'passed') proved.add(c.name);
+      else if (response.status === 'done') errors.push(`response/data/checks.json: check ${c.name} failed, so the operation cannot be reported as operated`);
+    }
+    if (response.status === 'done') for (const n of KIND_CHECKS[kind] ?? []) if (!proved.has(n)) errors.push(`response/data/checks.json: the ${kind} branch cannot be proved without the ${n} check`);
+
+    findingCount = checks.findings.length;
+    for (const f of checks.findings) {
+      if (delta && !inventoried.has(f.resourceRef)) errors.push(`response/data/checks.json: finding on ${f.resourceRef} names an uninventoried resource`);
+      if (f.code !== 'PORT_COORDINATION_REQUIRED') continue;
+      if (f.port === null) errors.push('response/data/checks.json: a port coordination finding must name the port');
+      if (f.holderRef === null) errors.push('response/data/checks.json: a port coordination finding must name the process that already holds the port');
+      if (response.status === 'done') errors.push('response/data/checks.json: a port coordination finding cannot end in an operated outcome');
+      else if (response.stop !== 'PORT_CONFLICT') errors.push('response/response.json: a port coordination finding requires the PORT_CONFLICT failure');
+    }
+    forEachString(checks, (text, at) => { if (credentialLeak(text)) errors.push(`response/data/checks.json: ${at} records a credential, which the receipt refuses`); });
+  } else if (response.status === 'done') errors.push('response/data/checks.json: a done branch needs the proved check set');
+
+  if (present.has('platform-operation-receipt') && has('response/response.md')) {
+    const text = await read('response/response.md');
+    const binding = Object.fromEntries((tableUnder(text, '## Binding') ?? []).map(([k, v]) => [k, v]));
+    if (!empty(service) && binding.Service !== service) errors.push('response/response.md: Binding names a service the request did not operate');
+    if (kind && binding['Service kind'] !== kind) errors.push('response/response.md: Binding names another service kind');
+    if (!empty(desired.planSha256) && binding['Desired state'] !== desired.planSha256) errors.push('response/response.md: Binding carries a desired state the approval did not cover');
+    if (!empty(requirements.approval) && binding.Approval !== requirements.approval) errors.push('response/response.md: Binding names an approval the request did not declare');
+    const conv = Object.fromEntries((tableUnder(text, '## Convergence') ?? []).map(([k, v]) => [k, v]));
+    if (delta && conv.Convergence !== delta.convergence) errors.push(`response/response.md: Convergence says ${conv.Convergence} but the delta says ${delta.convergence}`);
+    const mdChecks = tableUnder(text, '## Checks') ?? [];
+    if (checks && mdChecks.length !== checks.checks.length) errors.push(`response/response.md: Checks has ${mdChecks.length} rows, the proof set has ${checks.checks.length}`);
+    const mdMutations = tableUnder(text, '## Mutations') ?? [];
+    if (delta && mdMutations.length !== delta.mutations.length) errors.push(`response/response.md: Mutations has ${mdMutations.length} rows, the delta has ${delta.mutations.length}`);
+    const mdFindings = tableUnder(text, '## Findings') ?? [];
+    if (checks && mdFindings.length !== findingCount) errors.push(`response/response.md: Findings has ${mdFindings.length} rows, the proof set has ${findingCount}`);
+    if (credentialLeak(text)) errors.push('response/response.md: a credential handle or secret-shaped token must never be recorded in the receipt');
+  } else if (response.status === 'done') errors.push('response/response.md: a done branch needs the operation receipt');
+
+  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 validatePlatformStep(path.resolve(target));
+  if (errors.length) { process.stderr.write(`${errors.join('\n')}\n`); process.exitCode = 1; } else process.stdout.write('valid platform.operate branch\n');
+}

package/operators/quality-verify/errors.json

@@ -0,0 +1,54 @@
+{
+  "schemaVersion": 9,
+  "note": "Stop codes only quality.verify emits. Same entry shape as operators/errors.json, scope implicit. Shared codes (INVALID_INPUT, SOURCE_DRIFT, NO_PROGRESS) come from operators/errors.json.",
+  "codes": {
+    "PREDECESSOR_MIXED": {
+      "domain": "caller",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "Two predecessor receipts describe different source heads, so their union is a delivery nobody built.",
+        "vi": "Hai biên bản tiền nhiệm mô tả hai source head khác nhau, nên hợp của chúng là một delivery chẳng ai xây."
+      },
+      "resume": {
+        "en": "Supply one coherent predecessor set on one head.",
+        "vi": "Cấp một bộ tiền nhiệm nhất quán trên cùng một head."
+      }
+    },
+    "PREDECESSOR_STALE": {
+      "domain": "caller",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "A predecessor fingerprint no longer matches the frozen source.",
+        "vi": "Fingerprint của một tiền nhiệm không còn khớp source đã đóng băng."
+      },
+      "resume": {
+        "en": "Bring a refreshed upstream receipt.",
+        "vi": "Mang biên bản thượng nguồn đã làm mới."
+      }
+    },
+    "GATE_UNAVAILABLE": {
+      "domain": "platform",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "A required gate cannot be executed at all in this environment, and an unmeasurable gate is not a passed one.",
+        "vi": "Một cổng bắt buộc hoàn toàn không chạy được ở môi trường này, và cổng không đo được không phải cổng đã qua."
+      },
+      "resume": {
+        "en": "Provide a working gate environment.",
+        "vi": "Cấp một môi trường chạy cổng hoạt động được."
+      }
+    },
+    "DEBT_UNAPPROVED": {
+      "domain": "caller",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "A declared debt has no live owner approval, or it covers a gate that passed or a boundary-drift failure.",
+        "vi": "Một khoản nợ đã khai không có phê duyệt còn sống của chủ, hoặc phủ lên một cổng đã pass hay một lỗi boundary-drift."
+      },
+      "resume": {
+        "en": "Supply the unexpired owner approval, or drop the debt.",
+        "vi": "Cấp phê duyệt của chủ còn hạn, hoặc bỏ khoản nợ."
+      }
+    }
+  }
+}

package/operators/quality-verify/operator.json

@@ -0,0 +1,20 @@
+{
+  "schemaVersion": 9,
+  "id": "quality.verify",
+  "domain": "quality",
+  "job": "Verify one bounded delivery by running its declared gates against an unchanged predecessor receipt at one frozen head, and return the exact measured verdict, repairing nothing.",
+  "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"
+    }
+  }
+}

package/operators/quality-verify/operator.md

@@ -0,0 +1,185 @@
+# quality.verify
+
+## Job
+
+Verify one bounded delivery by running its declared gates against an unchanged predecessor receipt
+at one frozen head, and return the exact measured verdict, repairing nothing.
+
+## One delivery, one head, at least one producer receipt
+
+The three Inputs are the three shapes a delivery arrives in: a backend implementation, a frontend
+source application, and the `changes` record that names which paths moved and which gates and
+surfaces they touch. Each is optional on its own and at least one must be present, because a
+verification with no producer receipt has no head to freeze and no delivery to measure. Every
+predecessor receipt must report the same source head, and that head must be the head
+`request/request.json` froze; two predecessors on different heads describe two different deliveries,
+and gating the union of them measures something nobody built. That is `PREDECESSOR_MIXED`, refused
+before a single command runs rather than discovered later as a confusing gate failure. A predecessor
+whose fingerprint no longer matches the frozen source is `PREDECESSOR_STALE`. What a predecessor
+decided is consumed unchanged: this operator never re-plans the delivery, re-opens its boundary, or
+forms an opinion about whether the change was a good one.
+
+## The head is confirmed inside the gate
+
+There is no separate head-verification step, because a head confirmed anywhere but at the gate is a
+head that could drift before the first command. The producer wrote its delivery on the session
+branch `session/<sessionId>` of the routed checkout, in a git worktree prepared from the frozen head,
+and committed it once. `request/request.json` therefore pins `@workspaces/be` or `@workspaces/fe` at
+that exact commit sha in `contexts[].head`, and step 1 confirms the observed head equals it before
+anything else happens; a difference is `SOURCE_DRIFT`. The predecessor receipt's own commit must
+equal that same head, because a receipt describing a commit the gates are not standing on is
+`PREDECESSOR_STALE`. Every gate runs inside that session branch worktree and never on the person's
+checked-out branch, so a gate result names one commit somebody can check out again.
+
+## A red gate is a verdict, not a stop
+
+Quality measures. It does not repair, redesign, reclassify, or negotiate. A failing gate produces a
+red verdict naming the failure and its classification, and that verdict goes back to the owner who
+can fix it; the branch is `done`, not `blocked`, because the operator did exactly what it was asked
+to do. Only an inability to reach any verdict at all is a stop. The operator does not touch product
+source, does not adjust a gate command or its configuration to change an outcome, and does not
+substitute an easier check for a hard one.
+
+## A gate result is measured, never narrated
+
+Every executed gate carries its command reference, its exit code, and its evidence, in its own file
+under `response/data/gates/`. One file per gate is what makes a gate result quotable on its own: a
+later reader opens `lint.json` and sees one command, one exit code, one classification, without
+reading around a bundle. A pass means exit code zero with evidence beside it; a failure means a
+non-zero exit code with evidence and a classification. The classification is read from the structured
+diagnostics after the command ran, never chosen before it: `in-boundary` when the delivery owner can
+fix it, `boundary-drift` when fixing it would change an approved boundary, `flaky` when identical
+source and environment produced contradictory outcomes, and `external-blocker` when the environment
+or a dependency prevented a verdict at all. A rerun exists to tell those four apart. It never exists
+to convert an unexplained failure into a pass. No gate is skipped, suppressed, substituted, or moved
+with `passWithNoTests`, and a zero-test run is not a pass. Every gate file records the same source
+head, because two gates standing on two heads measured two deliveries.
+
+## Two facts about this codebase
+
+Sonar measures new code only. The pinned gate is scoped to the change, so a green Sonar result is a
+statement about the diff and not about the project, and a project may sit red beneath it. Under the
+default `sonarScope` of `new-code`, a passing Sonar result is recorded together with a
+`SONAR_NEW_CODE_ONLY` finding; without it a later reader takes a green gate for project health, which
+is the exact misreading this operator exists to prevent.
+
+End-to-end is never run unless a person asked for it in this invocation, which is why
+`explicitE2eRequest` defaults to false. Otherwise the gate is recorded as `skipped-not-requested`
+with an `E2E_NOT_REQUESTED` finding: no command, no exit code, no evidence, and no implication that
+behaviour was proved. Planning the e2e gate without that request is invalid input.
+
+## Coverage carries four thresholds, not one
+
+Statements, lines, functions and branches are each compared against their own threshold, and
+branches carry an independent one because a branch threshold folded into the statement figure is how
+an untested error path passes. The thresholds default to the four percentages the routed gate
+configuration already pins, so a person who names none is measured against the project's own bar. A
+metric under its threshold makes the unit gate a failure and records `COVERAGE_BELOW_THRESHOLD`; it
+is never a note beside a green result.
+
+## Debt is explicit and owned
+
+A gate stays red only when an owner-approved debt record covers it, naming the debt, the gate, the
+approval, the owner and the expiry, and only when that approval is still live at the instant the
+gate was measured. An expired approval is not a debt and a debt against a gate that passed is a
+record of nothing; both are refused as `DEBT_UNAPPROVED`. A debt covers only an `in-boundary`
+failure, the kind the delivery owner can fix; a `boundary-drift` failure belongs to whoever owns the
+boundary and cannot be owed away here. `declaredDebts` defaults to the empty list, so carrying a red
+gate is always something a person did on purpose.
+
+## The verdict
+
+`pass` requires every required gate to have passed, or to have failed `in-boundary` under a declared
+debt. Every other shape is `fail`, including a required gate the environment blocked: an unmeasurable
+gate is not a passed one. A non-required gate that fails is recorded and does not by itself turn the
+verdict red, which is the whole reason `required` exists, and it is the gate plan's declaration and
+never this operator's judgement.
+
+## Boundary
+
+Context is read-only. The operator writes only `response/` of its own branch: one `gate-result` file
+per gate under `response/data/gates/`, `data/coverage.json`, `response.md` and `response.json`. It
+does not modify product source, configuration, or a gate command; it does not redesign, repair, or
+reclassify a measured failure into a pass; it does not run the end-to-end suite unasked; it does not
+add, weaken, skip, suppress, or substitute a declared gate; it does not read a project-level Sonar
+verdict out of a new-code quality gate; and it does not carry a debt no owner approved or whose
+approval expired.
+
+## Context
+
+| Alias | Bind | Required |
+| --- | --- | --- |
+| `@workspaces/<project>/<role>/gates` | the pinned gate commands, their configuration and the thresholds they carry; what "the same gate" means across runs | yes |
+| `@workspaces/be` | the routed backend checkout at the pinned commit, the subject every gate measures when the delivery is a backend | no |
+| `@workspaces/fe` | the routed frontend checkout at the pinned commit, the subject every gate measures when the delivery is a frontend | no |
+| `@worktrees/debts` | owner-approved debt records and their expiry; a red gate is carried only from here | no |
+
+## Inputs
+
+| Kind | From | Required |
+| --- | --- | --- |
+| `backend-source-application` | `backend.source.apply`, the backend delivery to verify | no |
+| `frontend-source-application` | `frontend.source.apply`, the frontend delivery to verify | no |
+| `changes` | `backend.source.apply` or `frontend.source.apply`, the paths that moved and the gates and surfaces they name | no |
+
+## Requirements
+
+| Field | Type | Default | Ask |
+| --- | --- | --- | --- |
+| `gates` | list of `{gate, commandRef, configRef, required}` | the routed gate plan | Which pinned gates to run, once each, from format, lint, typecheck, build, unit-coverage, integration, e2e and sonar |
+| `thresholds` | list of `{statements, lines, functions, branches}` | the four percentages the routed gate configuration pins | The percentage each coverage metric must meet, branches on its own |
+| `explicitE2eRequest` | choice | false | false unless a person asked for the end-to-end suite in this invocation; true only then |
+| `sonarScope` | choice | new-code | new-code or overall; it must agree with whether sonar is in the gate plan |
+| `declaredDebts` | list of `{debtId, gate, approvalRef, ownerRef, expiresAt}` | [] | Owner-approved debts that let a named gate stay red |
+| `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, confirm the frozen head and the resume | `resume` | `request/request.json`, @workspaces/be or @workspaces/fe at the commit the request pinned, @tools/git | — | `INVALID_INPUT`, `SOURCE_DRIFT`, `NO_PROGRESS` |
+| 2 | Consume the predecessors unchanged | — | inputs `backend-source-application`, `frontend-source-application` and `changes` at their fingerprints, and the commit each one recorded | — | `PREDECESSOR_MIXED`, `PREDECESSOR_STALE` |
+| 3 | Run the gates in declared order | `gates`, `explicitE2eRequest`, `sonarScope` | @workspaces/<project>/<role>/gates, @workspaces/be or @workspaces/fe as the subject each gate measures, @tools/http | `response/data/gates/<gate>.json`, @tools/shell | `GATE_UNAVAILABLE` |
+| 4 | Apply the coverage policy | `thresholds` | `response/data/gates/<gate>.json` of the unit gate | `response/data/coverage.json` | — |
+| 5 | Classify each failure from its diagnostics | — | `response/data/gates/<gate>.json` of every red gate | — | — |
+| 6 | Apply approved debt | `declaredDebts` | @worktrees/debts, `response/data/gates/<gate>.json` | — | `DEBT_UNAPPROVED` |
+| 7 | Compute the verdict, write the receipt and emit | — | everything above | `response/response.md`, `response/response.json` | — |
+
+A gate that could not be executed at all in this environment is `GATE_UNAVAILABLE` when it was
+required; a non-required gate the environment blocked is recorded as `external-blocker` and the
+verdict absorbs it. There is no repair code, because repair is not this operator's job: an
+`in-boundary` failure returns as a red verdict to the owner who can fix it, and the fixed delivery
+comes back as a new head with a new predecessor fingerprint. A resume reuses only unchanged
+fingerprinted observations and consumes the exact delta; a resume that adds no predecessor, gate,
+debt or source change is `NO_PROGRESS`, because the same fingerprint cannot yield a different answer.
+
+## Outputs
+
+| Kind | File | Type | Required |
+| --- | --- | --- | --- |
+| `quality-verification` | `response/response.md` | md | yes |
+| `gate-result` | `response/data/gates/<gate>.json` | data | yes |
+| `coverage` | `response/data/coverage.json` | data | no |
+
+## Stops
+
+| Code | Disposition |
+| --- | --- |
+| `INVALID_INPUT` | terminate |
+| `SOURCE_DRIFT` | terminate |
+| `NO_PROGRESS` | terminate |
+| `PREDECESSOR_MIXED` | terminate |
+| `PREDECESSOR_STALE` | terminate |
+| `GATE_UNAVAILABLE` | terminate |
+| `DEBT_UNAPPROVED` | terminate |
+
+## Next
+
+| When | Operator |
+| --- | --- |
+| a backend gate failed in boundary and the backend owner must fix it | `backend.source.apply` |
+| a frontend gate failed in boundary and the frontend owner must apply the fix | `frontend.source.apply` |
+| the verdict is green and the delivery is ready to publish | `git.publish` |
+| the verdict is green and the published head must reach an environment | `release.deploy` |
+| the gates are green and the promise must be reconciled against the delivered source | `business.decide` |
+| the gates are green and a person asked for the journey to be walked | `uat.verify` |

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

@@ -0,0 +1,177 @@
+# quality.verify
+
+## Việc
+
+Kiểm định một delivery có ranh giới bằng cách chạy các cổng đã khai trên một biên bản tiền nhiệm còn
+nguyên vẹn tại một head đã đóng băng, rồi trả về đúng phán quyết đo được, không sửa gì cả.
+
+## Một delivery, một head, ít nhất một biên bản của người sản xuất
+
+Ba Đầu vào là ba hình dạng mà một delivery có thể tới: một bản hiện thực backend, một bản áp source
+frontend, và bản ghi `changes` nêu những path nào đã dịch chuyển cùng những cổng và bề mặt chúng chạm
+tới. Từng cái đều không bắt buộc, nhưng phải có ít nhất một, vì một lần kiểm định không có biên bản
+của người sản xuất thì chẳng có head nào để đóng băng và chẳng có delivery nào để đo. Mọi biên bản
+tiền nhiệm phải báo cùng một source head, và head đó phải là head mà `request/request.json` đã đóng
+băng; hai tiền nhiệm trên hai head khác nhau mô tả hai delivery khác nhau, và gác hợp của chúng là đo
+một thứ không ai xây. Đó là `PREDECESSOR_MIXED`, bị từ chối trước khi có lệnh nào chạy thay vì lộ ra
+về sau dưới dạng một lỗi cổng khó hiểu. Một tiền nhiệm có fingerprint không còn khớp source đã đóng
+băng là `PREDECESSOR_STALE`. Điều tiền nhiệm đã quyết được tiêu thụ nguyên vẹn: operator này không
+bao giờ lập lại kế hoạch delivery, mở lại ranh giới của nó, hay có ý kiến về việc thay đổi ấy hay dở.
+
+## Head được xác nhận ngay trong cổng vào
+
+Không có bước xác nhận head riêng, vì một head được xác nhận ở chỗ nào khác cổng vào là một head còn
+kịp trôi trước lệnh đầu tiên. Người sản xuất đã viết delivery trên nhánh phiên `session/<sessionId>`
+của checkout đã route, trong một git worktree dựng từ head đã đóng băng, và commit đúng một lần. Vì
+thế `request/request.json` ghim `@workspaces/be` hoặc `@workspaces/fe` tại đúng commit sha đó trong
+`contexts[].head`, và bước 1 xác nhận head quan sát được bằng đúng nó trước khi bất kỳ điều gì khác
+xảy ra; khác nhau là `SOURCE_DRIFT`. Commit mà biên bản tiền nhiệm ghi phải bằng chính head đó, vì
+một biên bản mô tả một commit mà các cổng không đứng trên là `PREDECESSOR_STALE`. Mọi cổng chạy bên
+trong worktree của nhánh phiên ấy, không bao giờ trên nhánh người ta đang checkout, nên một kết quả
+cổng gọi tên đúng một commit mà ai đó có thể checkout lại.
+
+## Cổng đỏ là một phán quyết, không phải một mã dừng
+
+Quality đo. Nó không sửa, không thiết kế lại, không phân loại lại, không mặc cả. Một cổng hỏng sinh
+ra một phán quyết đỏ gọi tên cái hỏng và phân loại của nó, và phán quyết ấy quay về người chủ có thể
+sửa; nhánh là `done`, không phải `blocked`, vì operator đã làm đúng việc được giao. Chỉ khi hoàn toàn
+không đạt tới được phán quyết nào thì mới là một mã dừng. Operator không đụng vào source sản phẩm,
+không chỉnh lệnh cổng hay cấu hình của nó để đổi kết quả, và không thay một kiểm khó bằng một kiểm dễ.
+
+## Kết quả cổng là đo được, không phải kể lại
+
+Mọi cổng đã chạy mang theo tham chiếu lệnh, mã thoát và bằng chứng của nó, trong file riêng dưới
+`response/data/gates/`. Một file cho một cổng là thứ khiến kết quả cổng trích dẫn được một mình: người
+đọc sau mở `lint.json` và thấy một lệnh, một mã thoát, một phân loại, không phải đọc vòng quanh một
+bó. Pass nghĩa là mã thoát bằng không kèm bằng chứng bên cạnh; fail nghĩa là mã thoát khác không kèm
+bằng chứng và một phân loại. Phân loại được đọc từ chẩn đoán có cấu trúc sau khi lệnh đã chạy, không
+bao giờ chọn trước: `in-boundary` khi chủ delivery sửa được, `boundary-drift` khi sửa nó là đổi một
+ranh giới đã duyệt, `flaky` khi cùng source cùng môi trường cho hai kết quả mâu thuẫn, và
+`external-blocker` khi môi trường hay một phụ thuộc chặn hẳn phán quyết. Chạy lại tồn tại để phân
+biệt bốn thứ đó. Nó không bao giờ tồn tại để biến một lỗi chưa giải thích được thành pass. Không cổng
+nào bị bỏ, bịt, thay hay dời bằng `passWithNoTests`, và một lần chạy không có test nào không phải là
+pass. Mọi file cổng ghi cùng một source head, vì hai cổng đứng trên hai head là đã đo hai delivery.
+
+## Hai sự thật về codebase này
+
+Sonar chỉ đo new code. Cổng đã ghim được thu hẹp theo thay đổi, nên một kết quả Sonar xanh là phát
+biểu về cái diff chứ không phải về dự án, và dự án bên dưới vẫn có thể đỏ. Dưới mặc định `new-code`
+của `sonarScope`, một kết quả Sonar pass được ghi kèm phát hiện `SONAR_NEW_CODE_ONLY`; thiếu nó thì
+người đọc sau hiểu cổng xanh là sức khỏe dự án, đúng cái hiểu sai mà operator này sinh ra để chặn.
+
+End-to-end không bao giờ chạy trừ khi có người yêu cầu trong chính lần gọi này, nên
+`explicitE2eRequest` mặc định là false. Ngược lại cổng được ghi là `skipped-not-requested` kèm phát
+hiện `E2E_NOT_REQUESTED`: không lệnh, không mã thoát, không bằng chứng, và không hàm ý nào rằng hành
+vi đã được chứng minh. Lập kế hoạch cổng e2e mà không có yêu cầu ấy là đầu vào không hợp lệ.
+
+## Coverage mang bốn ngưỡng, không phải một
+
+Statement, line, function và branch mỗi thứ so với ngưỡng riêng của nó, và branch mang một ngưỡng độc
+lập vì gộp ngưỡng branch vào con số statement chính là cách một nhánh lỗi chưa test đi lọt. Ngưỡng
+mặc định lấy bốn phần trăm mà cấu hình cổng của route đã ghim, nên người không nêu ngưỡng nào vẫn được
+đo theo đúng thanh của dự án. Một chỉ số dưới ngưỡng của nó làm cổng unit thành fail và ghi
+`COVERAGE_BELOW_THRESHOLD`; nó không bao giờ là một ghi chú bên cạnh một kết quả xanh.
+
+## Nợ phải tường minh và có chủ
+
+Một cổng chỉ được ở lại màu đỏ khi có bản ghi nợ được chủ duyệt phủ lên nó, nêu khoản nợ, cổng, phê
+duyệt, chủ và hạn, và chỉ khi phê duyệt ấy còn sống tại đúng thời điểm cổng được đo. Phê duyệt hết hạn
+không phải là nợ, và một khoản nợ đặt lên cổng đã pass là bản ghi của hư không; cả hai bị từ chối bằng
+`DEBT_UNAPPROVED`. Nợ chỉ phủ được lỗi `in-boundary`, loại mà chủ delivery sửa được; lỗi
+`boundary-drift` thuộc về người sở hữu ranh giới và không thể khất ở đây. `declaredDebts` mặc định là
+danh sách rỗng, nên mang một cổng đỏ luôn là việc có người cố ý làm.
+
+## Phán quyết
+
+`pass` đòi mọi cổng bắt buộc đã pass, hoặc đã fail `in-boundary` dưới một khoản nợ đã khai. Mọi hình
+dạng khác là `fail`, kể cả một cổng bắt buộc bị môi trường chặn: cổng không đo được không phải cổng đã
+qua. Một cổng không bắt buộc mà fail thì được ghi lại và tự nó không làm phán quyết đỏ, đó chính là lý
+do `required` tồn tại, và nó là khai báo của kế hoạch cổng chứ không bao giờ là phán đoán của operator.
+
+## Ranh giới
+
+Context chỉ đọc. Operator chỉ ghi vào `response/` của nhánh mình: một file `gate-result` cho mỗi cổng
+dưới `response/data/gates/`, `data/coverage.json`, `response.md` và `response.json`. Nó không sửa
+source sản phẩm, cấu hình hay lệnh cổng; không thiết kế lại, sửa chữa hay phân loại một lỗi đã đo
+thành pass; không chạy bộ end-to-end khi không được hỏi; không thêm, làm yếu, bỏ, bịt hay thay một
+cổng đã khai; không đọc phán quyết mức dự án ra từ một quality gate chỉ đo new code; và không mang một
+khoản nợ không ai duyệt hoặc đã hết hạn.
+
+## Context
+
+| Alias | Bind | Bắt buộc |
+| --- | --- | --- |
+| `@workspaces/<project>/<role>/gates` | lệnh cổng đã ghim, cấu hình và ngưỡng chúng mang; là nghĩa của "cùng một cổng" qua các lần chạy | có |
+| `@workspaces/be` | checkout backend đã route tại commit đã ghim, chủ thể mọi cổng đo khi delivery là backend | không |
+| `@workspaces/fe` | checkout frontend đã route tại commit đã ghim, chủ thể mọi cổng đo khi delivery là frontend | không |
+| `@worktrees/debts` | bản ghi nợ được chủ duyệt và hạn của chúng; một cổng đỏ chỉ được mang từ đây | không |
+
+## Đầu vào
+
+| Kind | Từ đâu | Bắt buộc |
+| --- | --- | --- |
+| `backend-source-application` | `backend.source.apply`, delivery backend cần kiểm định | không |
+| `frontend-source-application` | `frontend.source.apply`, delivery frontend cần kiểm định | không |
+| `changes` | `backend.source.apply` hoặc `frontend.source.apply`, những path đã dịch chuyển cùng cổng và bề mặt chúng nêu | không |
+
+## Yêu cầu
+
+| Field | Kiểu | Mặc định | Hỏi |
+| --- | --- | --- | --- |
+| `gates` | list of `{gate, commandRef, configRef, required}` | the routed gate plan | Chạy những cổng đã ghim nào, mỗi cổng một lần, trong format, lint, typecheck, build, unit-coverage, integration, e2e và sonar |
+| `thresholds` | list of `{statements, lines, functions, branches}` | the four percentages the routed gate configuration pins | Mỗi chỉ số coverage phải đạt bao nhiêu phần trăm, branch đứng riêng |
+| `explicitE2eRequest` | choice | false | false trừ khi có người yêu cầu bộ end-to-end trong chính lần gọi này; chỉ khi đó mới true |
+| `sonarScope` | choice | new-code | new-code hoặc overall; phải khớp với việc sonar có nằm trong kế hoạch cổng hay không |
+| `declaredDebts` | list of `{debtId, gate, approvalRef, ownerRef, expiresAt}` | [] | Những khoản nợ được chủ duyệt cho phép một cổng có tên ở lại mà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 cổng vào, xác nhận head đã đóng băng và resume | `resume` | `request/request.json`, @workspaces/be hoặc @workspaces/fe tại commit mà request đã ghim, @tools/git | — | `INVALID_INPUT`, `SOURCE_DRIFT`, `NO_PROGRESS` |
+| 2 | Tiêu thụ tiền nhiệm nguyên vẹn | — | Đầu vào `backend-source-application`, `frontend-source-application` và `changes` tại fingerprint của chúng, cùng commit mà mỗi cái đã ghi | — | `PREDECESSOR_MIXED`, `PREDECESSOR_STALE` |
+| 3 | Chạy các cổng theo thứ tự đã khai | `gates`, `explicitE2eRequest`, `sonarScope` | @workspaces/<project>/<role>/gates, @workspaces/be hoặc @workspaces/fe là chủ thể mỗi cổng đo, @tools/http | `response/data/gates/<gate>.json`, @tools/shell | `GATE_UNAVAILABLE` |
+| 4 | Áp chính sách coverage | `thresholds` | `response/data/gates/<gate>.json` của cổng unit | `response/data/coverage.json` | — |
+| 5 | Phân loại từng lỗi từ chẩn đoán của nó | — | `response/data/gates/<gate>.json` của mọi cổng đỏ | — | — |
+| 6 | Áp nợ đã được duyệt | `declaredDebts` | @worktrees/debts, `response/data/gates/<gate>.json` | — | `DEBT_UNAPPROVED` |
+| 7 | Tính phán quyết, viết biên bản và phát | — | mọi thứ ở trên | `response/response.md`, `response/response.json` | — |
+
+Một cổng hoàn toàn không chạy được ở môi trường này là `GATE_UNAVAILABLE` khi nó bắt buộc; một cổng
+không bắt buộc bị môi trường chặn được ghi là `external-blocker` và phán quyết hấp thụ nó. Không có mã
+sửa chữa, vì sửa chữa không phải việc của operator này: một lỗi `in-boundary` quay về dưới dạng phán
+quyết đỏ tới người chủ sửa được nó, và delivery đã sửa quay lại thành một head mới với fingerprint
+tiền nhiệm mới. Một lần resume chỉ dùng lại quan sát có fingerprint không đổi và tiêu thụ đúng phần
+delta; một lần resume không thêm tiền nhiệm, cổng, nợ hay thay đổi source nào là `NO_PROGRESS`, vì
+cùng một fingerprint không thể cho một câu trả lời khác.
+
+## Đầu ra
+
+| Kind | File | Kiểu | Bắt buộc |
+| --- | --- | --- | --- |
+| `quality-verification` | `response/response.md` | md | có |
+| `gate-result` | `response/data/gates/<gate>.json` | data | có |
+| `coverage` | `response/data/coverage.json` | data | không |
+
+## Dừng
+
+| Code | Xử lý |
+| --- | --- |
+| `INVALID_INPUT` | terminate |
+| `SOURCE_DRIFT` | terminate |
+| `NO_PROGRESS` | terminate |
+| `PREDECESSOR_MIXED` | terminate |
+| `PREDECESSOR_STALE` | terminate |
+| `GATE_UNAVAILABLE` | terminate |
+| `DEBT_UNAPPROVED` | terminate |
+
+## Kế tiếp
+
+| Khi | Operator |
+| --- | --- |
+| một cổng backend hỏng trong ranh giới và chủ backend phải sửa | `backend.source.apply` |
+| một cổng frontend hỏng trong ranh giới và chủ frontend phải áp bản sửa | `frontend.source.apply` |
+| phán quyết xanh và delivery sẵn sàng để publish | `git.publish` |
+| phán quyết xanh và head đã publish phải tới được một môi trường | `release.deploy` |
+| các gate xanh và lời hứa phải được đối chiếu với source đã giao | `business.decide` |
+| các gate xanh và có người yêu cầu đi thử hành trình | `uat.verify` |