@starci/skills 1.1.0

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

@@ -0,0 +1,210 @@
+// Proves validate.mjs on a synthetic session branch: one green verification, one red one that is a
+// verdict and not a stop, one blocked on an unavailable gate, and one mutation per law, each of which
+// must fail with a line that names the defect.
+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 { validateQualityStep } from './validate.mjs';
+
+const HEAD = '1'.repeat(40);
+const OTHER_HEAD = '2'.repeat(40);
+const BRANCH = 'session/s-test';
+const OBSERVED = '2026-01-10T00:00:00.000Z';
+const PLAN = [
+  { gate: 'format', commandRef: 'package.json#scripts.format', configRef: '.prettierrc', required: true },
+  { gate: 'lint', commandRef: 'package.json#scripts.lint', configRef: 'eslint.config.mjs', required: true },
+  { gate: 'unit-coverage', commandRef: 'package.json#scripts.test', configRef: 'jest.config.ts', required: true },
+];
+const THRESHOLDS = { statements: 80, lines: 80, functions: 80, branches: 80 };
+const DEBT = { debtId: 'lint-debt', gate: 'lint', approvalRef: '@worktrees/debts/be.md#lint', ownerRef: 'be-team', expiresAt: '2026-06-01T00:00:00.000Z' };
+
+const gateResult = (gate, over = {}) => ({
+  gate, required: true, sourceHead: HEAD, sessionBranch: BRANCH, predecessorCommit: HEAD, observedAt: OBSERVED,
+  commandRef: PLAN.find((g) => g.gate === gate)?.commandRef ?? 'package.json#scripts.x',
+  configRef: PLAN.find((g) => g.gate === gate)?.configRef ?? 'config.json',
+  status: 'pass', exitCode: 0, evidenceRef: `gates/${gate}.log`, classification: null, sonarScope: null, debt: null,
+  statement: `${gate} measured at the frozen head`, ...over,
+});
+const failing = (gate, over = {}) => gateResult(gate, { status: 'fail', exitCode: 1, classification: 'in-boundary', ...over });
+
+const coverage = (over = {}) => ({ statements: 90, lines: 90, functions: 90, branches: 81.4, thresholds: THRESHOLDS, evidenceRef: 'gates/unit-coverage.log', ...over });
+
+function responseMd({ results = PLAN.map((g) => [g.gate, 'pass']), verdict = 'pass', findings = [['PREDECESSOR_CONSUMED', '—', 'the producer receipt was consumed unchanged']], plan = PLAN, sonarScope = 'new-code', head = HEAD, cov = coverage() } = {}) {
+  return `# quality-verification — ${head}
+
+The delivery was verified at one frozen head against the routed gate plan, and the verdict rests on
+the measured gate files alone.
+
+## Binding
+
+| Field | Value |
+| --- | --- |
+| Operator | \`quality.verify\` |
+| Step | \`step-1/parallel-1\` |
+| Checkout | \`@workspaces/be\` |
+| Head | \`${head}\` |
+| Session branch | \`${BRANCH}\` |
+| Predecessors | \`step-1/parallel-1/response/changes.md\` |
+
+## Gate plan
+
+| Gate | Required | Command | Configuration |
+| --- | --- | --- | --- |
+${plan.map((g) => `| \`${g.gate}\` | ${g.required === false ? 'no' : 'yes'} | \`${g.commandRef}\` | \`${g.configRef}\` |`).join('\n')}
+
+## Results
+
+| Gate | Status | Exit code | Evidence | Classification | Statement |
+| --- | --- | --- | --- | --- | --- |
+${results.map(([gate, status]) => `| \`${gate}\` | ${status} | ${status === 'pass' ? 0 : status === 'skipped-not-requested' ? '—' : 1} | \`gates/${gate}.log\` | ${status === 'fail' ? 'in-boundary' : '—'} | ${gate} measured |`).join('\n')}
+
+## Coverage
+
+| Metric | Measured | Threshold | Verdict |
+| --- | --- | --- | --- |
+| branches | ${cov.branches} | ${cov.thresholds.branches} | ${cov.branches < cov.thresholds.branches ? 'below' : 'at-or-above'} |
+
+## Sonar
+
+| Field | Value |
+| --- | --- |
+| Scope | ${sonarScope} |
+| Finding | — |
+
+## Debts
+
+| Debt | Gate | Approval | Owner | Expires | Statement |
+| --- | --- | --- | --- | --- | --- |
+
+## Findings
+
+| Code | Gate | Statement |
+| --- | --- | --- |
+${findings.map(([code, gate, statement]) => `| \`${code}\` | ${gate} | ${statement} |`).join('\n')}
+
+## Verdict
+
+| Field | Value |
+| --- | --- |
+| Verdict | \`${verdict}\` |
+`;
+}
+
+const requestJson = ({ gates = PLAN, thresholds = THRESHOLDS, e2e = false, sonarScope = 'new-code', debts = [], head = HEAD, inputs = { changes: 'step-1/parallel-1/response/changes.md' }, extra = {} } = {}) => ({
+  schemaVersion: 9, operatorId: 'quality.verify', step: 1, parallel: 1, sessionId: 's-test',
+  contexts: [{ alias: '@workspaces/be', head }],
+  requirements: { gates, thresholds, explicitE2eRequest: e2e, sonarScope, declaredDebts: debts, resume: null, ...extra },
+  inputs, resume: null,
+});
+
+const responseJson = ({ status = 'done', stop, gates = PLAN.map((g) => `response/data/gates/${g.gate}.json`), coverageField = 'response/data/coverage.json', next = ['git.publish'] } = {}) => ({
+  schemaVersion: 9, operatorId: 'quality.verify', step: 1, parallel: 1, status, ...(stop ? { stop } : {}),
+  fallbacks: [],
+  fields: status === 'blocked' ? {} : { 'quality-verification': 'response/response.md', 'gate-result': gates, ...(coverageField ? { coverage: coverageField } : {}) },
+  commits: [], next,
+});
+
+function writeBranch(files) {
+  const session = mkdtempSync(path.join(tmpdir(), 'quality-session-'));
+  const branch = path.join(session, 'step-1', 'parallel-1');
+  for (const d of ['request', 'response/data/gates', 'response/artifacts']) mkdirSync(path.join(branch, d), { recursive: true });
+  writeFileSync(path.join(session, 'state.json'), JSON.stringify({ id: 's-test', chain: [['1/1']], steps: { '1/1': 'quality.verify' }, current: '1/1', status: 'running' }));
+  mkdirSync(path.join(session, 'step-1', 'parallel-1', 'response'), { recursive: true });
+  writeFileSync(path.join(session, 'step-1', 'parallel-1', 'response', 'changes.md'), '# changes\n');
+  for (const [name, content] of Object.entries(files)) {
+    if (content === null) continue;
+    writeFileSync(path.join(branch, name), typeof content === 'string' ? content : JSON.stringify(content, null, 2));
+  }
+  return { branch, session };
+}
+
+const baseline = (over = {}) => ({
+  'request/request.json': requestJson(),
+  'response/response.json': responseJson(),
+  'response/response.md': responseMd(),
+  'response/data/gates/format.json': gateResult('format'),
+  'response/data/gates/lint.json': gateResult('lint'),
+  'response/data/gates/unit-coverage.json': gateResult('unit-coverage'),
+  'response/data/coverage.json': coverage(),
+  ...over,
+});
+
+// A red gate is a verdict, not a stop: the branch is done and the receipt says fail.
+const red = () => baseline({
+  'response/data/gates/lint.json': failing('lint'),
+  'response/response.md': responseMd({ results: [['format', 'pass'], ['lint', 'fail'], ['unit-coverage', 'pass']], verdict: 'fail' }),
+  'response/response.json': responseJson({ next: ['backend.source.apply'] }),
+});
+
+async function expectValid(files, label) {
+  const { branch, session } = writeBranch(files);
+  const { errors } = await validateQualityStep(branch);
+  rmSync(session, { recursive: true, force: true });
+  assert.deepEqual(errors, [], `${label} should be valid`);
+}
+async function expectError(files, needle, label) {
+  const { branch, session } = writeBranch(files);
+  const { errors } = await validateQualityStep(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 green verification with one file per gate');
+await expectValid(red(), 'a red gate returned as a verdict, not a stop');
+await expectValid({
+  'request/request.json': requestJson(),
+  'response/response.json': responseJson({ status: 'blocked', stop: 'GATE_UNAVAILABLE', next: [] }),
+  'response/response.md': null, 'response/data/coverage.json': null,
+}, 'blocked because a required gate could not be executed');
+
+await expectError(baseline({ 'response/response.json': { ...responseJson(), stop: 'DEBT_UNAPPROVED' } }), 'only a blocked response carries a stop', 'done with a stop');
+await expectError(baseline({ 'response/response.json': responseJson({ status: 'blocked', stop: 'GATE_RED', next: [] }) }), 'not a registered code', 'unknown stop code');
+await expectError(baseline({ 'request/request.json': requestJson({ extra: { cachePolicy: 'fresh' } }) }), 'requirements.cachePolicy is not a field', 'a field the operator no longer declares');
+await expectError(baseline({ 'request/request.json': requestJson({ gates: [...PLAN, { gate: 'e2e', commandRef: 'p#e2e', configRef: 'e2e.config.ts', required: false }] }) }), 'cannot be planned without an explicit request', 'e2e planned with no person asking');
+await expectError(baseline({
+  'request/request.json': requestJson({ gates: [...PLAN, { gate: 'e2e', commandRef: 'p#e2e', configRef: 'e2e.config.ts', required: false }] }),
+  'response/data/gates/e2e.json': gateResult('e2e', { required: false, status: 'pass' }),
+  'response/response.json': responseJson({ gates: [...PLAN.map((g) => `response/data/gates/${g.gate}.json`), 'response/data/gates/e2e.json'] }),
+  'response/response.md': responseMd({ plan: [...PLAN, { gate: 'e2e', commandRef: 'p#e2e', configRef: 'e2e.config.ts', required: false }], results: [...PLAN.map((g) => [g.gate, 'pass']), ['e2e', 'pass']] }),
+}), 'ran without an explicit request', 'the e2e suite run unasked');
+await expectError(baseline({ 'request/request.json': requestJson({ gates: PLAN, e2e: true }), 'response/data/gates/e2e.json': gateResult('e2e', { status: 'skipped-not-requested', exitCode: null, evidenceRef: null }) }), 'never planned it', 'a gate result for a gate nobody planned');
+await expectError(baseline({ 'response/data/gates/lint.json': gateResult('lint', { exitCode: 1 }) }), 'passed with a non-zero exit code', 'a pass over a failing command');
+await expectError(baseline({ 'response/data/gates/lint.json': gateResult('lint', { evidenceRef: null }) }), 'passed with no evidence to open', 'a pass with nothing to open');
+await expectError(baseline({ 'response/data/gates/lint.json': failing('lint', { classification: null }), 'response/response.md': responseMd({ results: [['format', 'pass'], ['lint', 'fail'], ['unit-coverage', 'pass']], verdict: 'fail' }) }), 'without an in-boundary, boundary-drift, or flaky classification', 'a failure nobody classified');
+await expectError(baseline({ 'response/data/gates/format.json': gateResult('format', { status: 'skipped-not-requested', exitCode: null, evidenceRef: null }) }), 'cannot be skipped as not requested', 'a gate other than e2e quietly skipped');
+await expectError(baseline({ 'response/data/gates/lint.json': gateResult('lint', { sourceHead: OTHER_HEAD, predecessorCommit: OTHER_HEAD }) }), 'different heads', 'two gates standing on two heads');
+await expectError(baseline({ 'request/request.json': requestJson({ head: OTHER_HEAD }), 'response/response.md': responseMd({ head: OTHER_HEAD }) }), 'but the request pinned', 'gates measured off the pinned commit');
+await expectError(baseline({ 'response/data/gates/lint.json': gateResult('lint', { predecessorCommit: OTHER_HEAD }) }), 'which is not the head', 'a predecessor describing another commit');
+await expectError(baseline({ 'response/data/gates/lint.json': gateResult('lint', { sonarScope: 'new-code' }) }), 'belongs to the sonar gate alone', 'a sonar scope on a lint result');
+await expectError(baseline({ 'response/data/gates/unit-coverage.json': gateResult('unit-coverage', { gate: 'unit-coverage' }), 'response/data/coverage.json': coverage({ branches: 40 }), 'response/response.md': responseMd({ cov: coverage({ branches: 40 }) }) }), 'sit below their own threshold', 'a green unit gate over a red branch metric');
+await expectError(baseline({ 'response/data/coverage.json': coverage({ thresholds: { ...THRESHOLDS, branches: 50 } }) }), 'but the request pinned', 'a threshold lowered under the request');
+await expectError(baseline({ 'response/data/coverage.json': null, 'response/response.json': responseJson({ coverageField: null }) }), 'reports no coverage measurement', 'a passing unit gate with no coverage');
+await expectError(baseline({ 'response/response.md': responseMd({ verdict: 'fail' }) }), 'every required gate passed or is debt-covered', 'a red verdict over green gates');
+await expectError({ ...red(), 'response/response.md': responseMd({ results: [['format', 'pass'], ['lint', 'fail'], ['unit-coverage', 'pass']], verdict: 'pass' }) }, 'neither passed nor carry a debt', 'a green verdict over a red required gate');
+await expectError(baseline({
+  'request/request.json': requestJson({ debts: [DEBT] }),
+  'response/data/gates/lint.json': failing('lint', { debt: { debtId: 'lint-debt', approvalRef: DEBT.approvalRef, ownerRef: DEBT.ownerRef, expiresAt: '2025-01-01T00:00:00.000Z', statement: 'carried' } }),
+  'response/response.md': responseMd({ results: [['format', 'pass'], ['lint', 'fail'], ['unit-coverage', 'pass']], findings: [['DEBT_DECLARED', 'lint', 'the lint failure is owed']] }),
+}), 'expired before the gate was measured', 'a debt whose approval has run out');
+await expectError(baseline({
+  'request/request.json': requestJson({ debts: [{ ...DEBT, gate: 'format' }] }),
+  'response/data/gates/format.json': failing('format', { classification: 'boundary-drift', debt: { debtId: 'lint-debt', approvalRef: DEBT.approvalRef, ownerRef: DEBT.ownerRef, expiresAt: DEBT.expiresAt, statement: 'carried' } }),
+  'response/response.md': responseMd({ results: [['format', 'fail'], ['lint', 'pass'], ['unit-coverage', 'pass']], findings: [['DEBT_DECLARED', 'format', 'owed']] }),
+}), 'belongs to the boundary owner', 'a boundary-drift failure owed away');
+await expectError(baseline({ 'response/data/gates/lint.json': failing('lint', { debt: { debtId: 'ghost-debt', approvalRef: 'x', ownerRef: 'y', expiresAt: DEBT.expiresAt, statement: 'z' } }), 'response/response.md': responseMd({ results: [['format', 'pass'], ['lint', 'fail'], ['unit-coverage', 'pass']], findings: [['DEBT_DECLARED', 'lint', 'owed']] }) }), 'was never declared in the request', 'a debt nobody declared');
+await expectError({
+  ...baseline({
+    'request/request.json': requestJson({ gates: [...PLAN, { gate: 'sonar', commandRef: 'p#sonar', configRef: 'sonar-project.properties', required: false }] }),
+    'response/data/gates/sonar.json': gateResult('sonar', { required: false, sonarScope: 'new-code' }),
+    'response/response.json': responseJson({ gates: [...PLAN.map((g) => `response/data/gates/${g.gate}.json`), 'response/data/gates/sonar.json'] }),
+    'response/response.md': responseMd({ plan: [...PLAN, { gate: 'sonar', commandRef: 'p#sonar', configRef: 'sonar-project.properties', required: false }], results: [...PLAN.map((g) => [g.gate, 'pass']), ['sonar', 'pass']] }),
+  }),
+}, 'must record SONAR_NEW_CODE_ONLY', 'a green new-code Sonar gate read as project health');
+await expectError(baseline({ 'response/response.md': responseMd({ results: [['format', 'pass'], ['lint', 'pass']] }) }), 'Results has 2 rows', 'a receipt that drops a measured gate');
+await expectError(baseline({ 'response/response.md': responseMd().replace('## Verdict', '## Result') }), 'missing section ^## Verdict$', 'receipt section renamed');
+await expectError(baseline({ 'response/data/gates/lint.json': { ...gateResult('lint'), sourceHead: 'nope' } }), 'sourceHead', 'gate-result schema');
+await expectError(baseline({ 'response/response.json': responseJson({ gates: ['response/data/gates/format.json', 'response/data/gates/lint.json'] }) }), 'gate-result does not list', 'a gate file the response never lists');
+await expectError(baseline({ 'request/request.json': requestJson({ inputs: {} }) }), 'needs at least one of', 'a verification with no producer receipt');
+
+process.stdout.write('quality.verify self-test: 3 valid branches, 25 rejected mutations\n');

package/operators/quality-verify/validate.mjs

@@ -0,0 +1,197 @@
+// quality.verify's own law over one branch, on top of the shared step check: the gate plan the
+// person declared is the plan that ran, one file per gate; every gate file stands on the same head,
+// which is the head the request pinned and the commit the predecessor recorded; e2e runs only under
+// an explicit request and sonar carries the scope it was measured at; a result's exit code, evidence
+// and classification match its status; coverage exists exactly where the unit gate produced it and no
+// metric sits below its own threshold beside a green unit result; a debt is live, in-boundary and
+// recorded; and the receipt's verdict follows the required gates.
+import { existsSync } from 'node:fs';
+import { readFile, readdir } 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 METRICS = ['statements', 'lines', 'functions', 'branches'];
+const DEFAULT_GATES = [
+  { gate: 'format', required: true },
+  { gate: 'lint', required: true },
+  { gate: 'typecheck', required: true },
+  { gate: 'build', required: true },
+  { gate: 'unit-coverage', required: true },
+];
+const empty = (v) => v === undefined || v === null || v === '' || v === '—';
+const asList = (v) => (Array.isArray(v) ? v : []);
+const isTrue = (v) => v === true || v === 'true' || v === 'yes';
+
+// A gate result is measured, never narrated: each status implies an exact shape for the exit code,
+// the evidence and the classification, and a shape mismatch is how a claim with no command behind it
+// gets recorded as a pass.
+function checkResultShape(r, at, errors) {
+  if (r.status === 'pass') {
+    if (r.exitCode !== 0) errors.push(`${at} passed with a non-zero exit code`);
+    if (r.evidenceRef === null) errors.push(`${at} passed with no evidence to open`);
+    if (r.classification !== null) errors.push(`${at} passed but carries a failure classification`);
+  } else if (r.status === 'fail') {
+    if (r.exitCode === null || r.exitCode === 0) errors.push(`${at} failed with an exit code that reports success`);
+    if (r.evidenceRef === null) errors.push(`${at} failed with no evidence to open`);
+    if (r.classification === null || r.classification === 'external-blocker') errors.push(`${at} failed without an in-boundary, boundary-drift, or flaky classification`);
+  } else if (r.status === 'external-blocker') {
+    if (r.classification !== 'external-blocker') errors.push(`${at} was blocked externally but is classified otherwise`);
+    if (r.evidenceRef === null) errors.push(`${at} was blocked externally with no evidence to open`);
+  } else if (r.status === 'skipped-not-requested') {
+    // Available to e2e alone: a gate that quietly did not run reads exactly like a gate that passed.
+    if (r.gate !== 'e2e') errors.push(`${at} cannot be skipped as not requested`);
+    if (r.exitCode !== null) errors.push(`${at} was skipped but reports an exit code`);
+    if (r.evidenceRef !== null) errors.push(`${at} was skipped but names evidence`);
+    if (r.classification !== null) errors.push(`${at} was skipped but carries a classification`);
+  }
+}
+
+export async function validateQualityStep(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 !== 'quality.verify') return { errors };
+  const has = (f) => existsSync(path.join(branchDir, f));
+  const read = (f) => readFile(path.join(branchDir, f), 'utf8');
+
+  // The plan the person declared, before a command runs.
+  const plan = asList(requirements.gates).length ? requirements.gates : DEFAULT_GATES;
+  const plannedNames = plan.map((g) => g.gate);
+  const requiredNames = plan.filter((g) => g.required !== false).map((g) => g.gate);
+  if (new Set(plannedNames).size !== plannedNames.length) errors.push('request.json: gates plans the same gate more than once');
+  const e2eRequested = isTrue(requirements.explicitE2eRequest);
+  const sonarScope = empty(requirements.sonarScope) ? 'new-code' : String(requirements.sonarScope);
+  if (plannedNames.includes('e2e') && !e2eRequested) errors.push('request.json: the e2e gate cannot be planned without an explicit request');
+  if (!['new-code', 'overall'].includes(sonarScope)) errors.push(`request.json: sonarScope ${sonarScope} is neither new-code nor overall`);
+
+  const debts = asList(requirements.declaredDebts);
+  const debtIds = debts.map((d) => d.debtId);
+  if (new Set(debtIds).size !== debtIds.length) errors.push('request.json: declaredDebts repeats a debt identifier');
+  for (const d of debts) if (!plannedNames.includes(d.gate)) errors.push(`request.json: debt ${d.debtId} covers ${d.gate}, which is not a planned gate`);
+
+  // At least one producer receipt: a verification with no predecessor has no delivery to measure.
+  const inputs = Object.keys(request?.inputs ?? {});
+  if (response.status !== 'blocked' && !inputs.some((k) => ['backend-source-application', 'frontend-source-application', 'changes'].includes(k))) {
+    errors.push('request.json: quality.verify needs at least one of backend-source-application, frontend-source-application, changes');
+  }
+
+  // One file per gate, read from disk so a gate file nobody listed is still caught.
+  const gatesDir = path.join(branchDir, 'response', 'data', 'gates');
+  const files = existsSync(gatesDir) ? (await readdir(gatesDir)).filter((f) => f.endsWith('.json')).sort() : [];
+  const listed = new Set(asList(response.fields?.['gate-result']));
+  for (const f of files) if (!listed.has(`response/data/gates/${f}`)) errors.push(`response/response.json: gate-result does not list response/data/gates/${f}`);
+
+  const byGate = new Map();
+  for (const f of files) {
+    const rel = `response/data/gates/${f}`;
+    let r; try { r = JSON.parse(await read(rel)); } catch { errors.push(`${rel}: is not readable JSON`); continue; }
+    const at = `${rel}: gate ${r.gate}`;
+    if (`${r.gate}.json` !== f) errors.push(`${rel}: names gate ${r.gate}; one gate result lives in one file named after its gate`);
+    if (byGate.has(r.gate)) { errors.push(`${rel}: gate ${r.gate} reports more than one result`); continue; }
+    byGate.set(r.gate, r);
+    if (!plannedNames.includes(r.gate)) errors.push(`${rel}: gate ${r.gate} reports a result but the request never planned it`);
+    const planned = plan.find((g) => g.gate === r.gate);
+    if (planned && r.required !== (planned.required !== false)) errors.push(`${at} records required ${r.required} but the plan declares ${planned.required !== false}`);
+    checkResultShape(r, at, errors);
+  }
+  for (const g of plannedNames) if (!byGate.has(g) && response.status === 'done') errors.push(`response/data/gates/${g}.json: the plan names ${g} but no result was measured`);
+
+  // Every gate stands on one head, and that head is the one the request pinned and the predecessor recorded.
+  const pinned = (request?.contexts ?? []).find((c) => c.alias === '@workspaces/be' || c.alias === '@workspaces/fe')?.head ?? null;
+  const heads = new Set([...byGate.values()].map((r) => r.sourceHead));
+  if (heads.size > 1) errors.push(`response/data/gates: the gates measured ${heads.size} different heads (${[...heads].join(', ')}); two heads are two deliveries`);
+  for (const r of byGate.values()) {
+    const at = `response/data/gates/${r.gate}.json`;
+    if (pinned && r.sourceHead !== pinned) errors.push(`${at}: the gate measured ${r.sourceHead} but the request pinned ${pinned}`);
+    if (r.predecessorCommit !== r.sourceHead) errors.push(`${at}: the predecessor recorded commit ${r.predecessorCommit}, which is not the head ${r.sourceHead} the gate measured`);
+  }
+
+  const e2e = byGate.get('e2e');
+  if (e2e && e2e.status !== 'skipped-not-requested' && !e2eRequested) errors.push('response/data/gates/e2e.json: the e2e suite ran without an explicit request');
+
+  // Sonar carries the scope it was measured at, and only the sonar gate does.
+  for (const r of byGate.values()) {
+    const at = `response/data/gates/${r.gate}.json`;
+    if (r.gate === 'sonar') { if (r.sonarScope !== sonarScope) errors.push(`${at}: sonarScope ${r.sonarScope} differs from the request's ${sonarScope}`); }
+    else if (r.sonarScope !== null) errors.push(`${at}: a sonar scope belongs to the sonar gate alone`);
+  }
+
+  // Debt is live, in-boundary, and declared before it is carried.
+  const debtByGate = new Map();
+  for (const r of byGate.values()) {
+    if (r.debt === null) continue;
+    const at = `response/data/gates/${r.gate}.json`;
+    debtByGate.set(r.gate, r.debt);
+    if (!debtIds.includes(r.debt.debtId)) errors.push(`${at}: debt ${r.debt.debtId} was never declared in the request`);
+    if (Date.parse(r.debt.expiresAt) <= Date.parse(r.observedAt)) errors.push(`${at}: debt ${r.debt.debtId} carries an approval that expired before the gate was measured`);
+    if (r.status !== 'fail') errors.push(`${at}: debt ${r.debt.debtId} covers a gate that did not fail`);
+    else if (r.classification !== 'in-boundary') errors.push(`${at}: debt ${r.debt.debtId} owes away a ${r.classification} failure that belongs to the boundary owner`);
+  }
+  for (const d of debts) if (!debtByGate.has(d.gate) && response.status === 'done') errors.push(`response/data/gates/${d.gate}.json: debt ${d.debtId} was declared but the gate result carries no debt`);
+
+  let coverage = null;
+  if (present.has('coverage') && has('response/data/coverage.json')) { try { coverage = JSON.parse(await read('response/data/coverage.json')); } catch { coverage = null; } }
+  const unit = byGate.get('unit-coverage');
+  const unitMeasured = unit !== undefined && unit.status !== 'skipped-not-requested';
+  if (coverage === null && unit?.status === 'pass') errors.push('response/data/coverage.json: the unit-coverage gate passed but reports no coverage measurement');
+  if (coverage !== null && !unitMeasured) errors.push('response/data/coverage.json: coverage is reported without a measured unit-coverage gate');
+  let below = [];
+  if (coverage !== null) {
+    below = METRICS.filter((m) => coverage[m] < coverage.thresholds[m]);
+    if (below.length && unit?.status === 'pass') errors.push(`response/data/coverage.json: unit-coverage passed while ${below.join(', ')} sit below their own threshold`);
+    if (!empty(requirements.thresholds)) {
+      for (const m of METRICS) {
+        const want = requirements.thresholds?.[m];
+        if (want !== undefined && coverage.thresholds[m] !== want) errors.push(`response/data/coverage.json: threshold for ${m} is ${coverage.thresholds[m]} but the request pinned ${want}`);
+      }
+    }
+  }
+
+  // The verdict follows the required gates, and the receipt is the only place it is stated.
+  const unmet = requiredNames.filter((g) => {
+    const r = byGate.get(g);
+    if (r === undefined) return true;
+    if (r.status === 'pass') return false;
+    return !(r.status === 'fail' && debtByGate.has(g));
+  });
+  const expected = unmet.length ? 'fail' : 'pass';
+
+  if (present.has('quality-verification') && has('response/response.md')) {
+    const text = await read('response/response.md');
+    const findingKeys = new Set((tableUnder(text, '## Findings') ?? []).map(([code, gate]) => `${code}|${gate === '—' ? 'null' : gate}`));
+    const verdict = Object.fromEntries((tableUnder(text, '## Verdict') ?? []).map(([k, v]) => [k, v]));
+    if (verdict.Verdict !== expected) errors.push(`response/response.md: Verdict says ${verdict.Verdict} but ${unmet.length ? `required gates ${unmet.join(', ')} neither passed nor carry a debt` : 'every required gate passed or is debt-covered'}`);
+    const binding = Object.fromEntries((tableUnder(text, '## Binding') ?? []).map(([k, v]) => [k, v]));
+    if (pinned && binding.Head !== pinned) errors.push(`response/response.md: Binding names head ${binding.Head} but the request pinned ${pinned}`);
+    const sonar = Object.fromEntries((tableUnder(text, '## Sonar') ?? []).map(([k, v]) => [k, v]));
+    if (byGate.has('sonar') && sonar.Scope !== sonarScope) errors.push(`response/response.md: Sonar scope ${sonar.Scope} differs from the measured ${sonarScope}`);
+    if (byGate.get('sonar')?.status === 'pass' && sonarScope === 'new-code' && !findingKeys.has('SONAR_NEW_CODE_ONLY|sonar')) errors.push('response/response.md: a passing new-code Sonar gate must record SONAR_NEW_CODE_ONLY, because the project beneath it may be red');
+    if (e2e?.status === 'skipped-not-requested' && !findingKeys.has('E2E_NOT_REQUESTED|e2e')) errors.push('response/response.md: a skipped e2e gate must record E2E_NOT_REQUESTED so the absence is visible');
+    if (below.length && !findingKeys.has('COVERAGE_BELOW_THRESHOLD|unit-coverage')) errors.push('response/response.md: coverage below a threshold must record COVERAGE_BELOW_THRESHOLD');
+    for (const [gate, debt] of debtByGate) if (!findingKeys.has(`DEBT_DECLARED|${gate}`)) errors.push(`response/response.md: debt ${debt.debtId} is carried without recording DEBT_DECLARED`);
+    for (const key of findingKeys) { const gate = key.split('|')[1]; if (gate !== 'null' && !plannedNames.includes(gate)) errors.push(`response/response.md: a finding names unplanned gate ${gate}`); }
+    const mdResults = tableUnder(text, '## Results') ?? [];
+    if (mdResults.length !== byGate.size) errors.push(`response/response.md: Results has ${mdResults.length} rows, the gate files measure ${byGate.size}`);
+    for (const row of mdResults) {
+      const r = byGate.get(row[0]);
+      if (!r) { errors.push(`response/response.md: Results names gate ${row[0]}, which no gate file measures`); continue; }
+      if (row[1] !== r.status) errors.push(`response/response.md: gate ${row[0]} is ${row[1]} in the receipt and ${r.status} in its gate file`);
+    }
+    const mdPlan = tableUnder(text, '## Gate plan') ?? [];
+    if (mdPlan.length !== plannedNames.length) errors.push(`response/response.md: Gate plan has ${mdPlan.length} rows, the request plans ${plannedNames.length}`);
+  } else if (response.status === 'done') errors.push('response/response.md: a done branch needs the verification receipt');
+
+  if (response.status === 'done' && byGate.size === 0) errors.push('response/data/gates: a done branch needs at least one measured gate');
+  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 validateQualityStep(path.resolve(target));
+  if (errors.length) { process.stderr.write(`${errors.join('\n')}\n`); process.exitCode = 1; } else process.stdout.write('valid quality.verify branch\n');
+}

package/operators/release-deploy/errors.json

@@ -0,0 +1,158 @@
+{
+  "schemaVersion": 9,
+  "note": "Stop codes only release.deploy emits. Same entry shape as operators/errors.json, scope implicit. Shared codes (INVALID_INPUT, NO_PROGRESS) come from operators/errors.json; APPROVAL_REQUIRED is defined by business.decide and belongs in operators/errors.json with both operators in scope. ROLLOUT_FAILED and RECOVERY_EXHAUSTED are the two ordered fallbacks: a failed rollout takes the recovery branch, and exhausted recovery takes the rollback branch; everything after that terminates.",
+  "codes": {
+    "AUTHORIZATION_MISSING": {
+      "domain": "approval",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "No declared grant covers this project, environment, target, or the deploy action, or it had expired when the target was observed.",
+        "vi": "Không grant nào đã khai phủ project, môi trường, target hay hành động deploy này, hoặc nó đã hết hạn lúc target được quan sát."
+      },
+      "resume": {
+        "en": "Supply the declared authorization, still valid.",
+        "vi": "Cấp thẩm quyền đã khai và còn hiệu lực."
+      }
+    },
+    "MANIFEST_INVALID": {
+      "domain": "caller",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "The validated manifest is pinned to another release, and that substitution is how an unreviewed image reaches a reviewed target.",
+        "vi": "Manifest đã kiểm được ghim vào một release khác, và phép thay thế đó chính là cách một image chưa duyệt tới được target đã duyệt."
+      },
+      "resume": {
+        "en": "Bring a manifest validated against this release.",
+        "vi": "Mang một manifest đã kiểm đúng với release này."
+      }
+    },
+    "ARTIFACT_MISSING": {
+      "domain": "provider",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "The immutable digest cannot be resolved, and no replacement may be built and called the same release.",
+        "vi": "Digest bất biến không phân giải được, và không được build một cái thay thế rồi gọi nó là cùng release."
+      },
+      "resume": {
+        "en": "Publish the artifact at that digest.",
+        "vi": "Publish artifact ở đúng digest đó."
+      }
+    },
+    "CREDENTIAL_UNAVAILABLE": {
+      "domain": "platform",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "A declared handle cannot be resolved through existing custody.",
+        "vi": "Một handle đã khai không phân giải được qua custody đang có."
+      },
+      "resume": {
+        "en": "Restore the custody; never an inline value.",
+        "vi": "Khôi phục custody; không bao giờ nhập giá trị trực tiếp."
+      }
+    },
+    "HOST_UNAVAILABLE": {
+      "domain": "provider",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "The declared host cannot be prepared.",
+        "vi": "Host đã khai không chuẩn bị được."
+      },
+      "resume": {
+        "en": "Provide a reachable, prepared host.",
+        "vi": "Cấp một host tới được và đã chuẩn bị."
+      }
+    },
+    "MIGRATION_BLOCKED": {
+      "domain": "backend",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "The declared migration cannot be applied safely.",
+        "vi": "Migration đã khai không thể áp một cách an toàn."
+      },
+      "resume": {
+        "en": "Approve a migration boundary the backend owner can apply.",
+        "vi": "Duyệt một ranh giới migration mà chủ backend áp được."
+      }
+    },
+    "DOMAIN_UNRECONCILED": {
+      "domain": "provider",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "Domain or TLS state cannot be brought to the declaration.",
+        "vi": "Trạng thái domain hay TLS không đưa về đúng khai báo được."
+      },
+      "resume": {
+        "en": "Fix the provider state, or the provider authority.",
+        "vi": "Sửa trạng thái phía provider, hoặc thẩm quyền với provider."
+      }
+    },
+    "ROLLOUT_FAILED": {
+      "domain": "deployment",
+      "disposition": "fallback",
+      "meaning": {
+        "en": "The rollout could not place the release on the target.",
+        "vi": "Rollout không đặt được release lên target."
+      },
+      "resume": {
+        "en": "Correct the target or the plan and roll out again.",
+        "vi": "Sửa target hoặc plan rồi roll out lại."
+      },
+      "fallback": {
+        "en": "Take the recovery branch: apply only the approved reversible actions against the same release identity, one at a time, and record each attempt with its outcome under ## Fallbacks taken.",
+        "vi": "Đi nhánh phục hồi: chỉ áp những hành động đảo ngược được đã duyệt trên cùng release identity, từng cái một, và ghi mỗi lần thử cùng kết quả dưới ## Fallbacks taken."
+      }
+    },
+    "STEADY_STATE_UNPROVEN": {
+      "domain": "deployment",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "The steady window never closed before the bounded deadline, and an assumed rollout is not a deployment.",
+        "vi": "Cửa sổ ổn định không khép lại trước deadline có chặn trên, và một rollout được giả định không phải một lần deploy."
+      },
+      "resume": {
+        "en": "Observe a fresh series after the target recovers.",
+        "vi": "Quan sát một chuỗi mới sau khi target hồi phục."
+      }
+    },
+    "CONCURRENT_DRIFT": {
+      "domain": "deployment",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "A release that is neither this one nor its predecessor became active during execution.",
+        "vi": "Một release không phải release này và cũng không phải release trước nó đã trở nên active giữa lượt chạy."
+      },
+      "resume": {
+        "en": "Replan against the new observed state.",
+        "vi": "Lập kế hoạch lại theo trạng thái quan sát mới."
+      }
+    },
+    "RECOVERY_EXHAUSTED": {
+      "domain": "approval",
+      "disposition": "fallback",
+      "meaning": {
+        "en": "The approved reversible actions ran out.",
+        "vi": "Các hành động đảo ngược được đã duyệt đã cạn."
+      },
+      "resume": {
+        "en": "Grant rollback authority, or approve an unsafe action.",
+        "vi": "Cấp thẩm quyền rollback, hoặc duyệt một hành động không an toàn."
+      },
+      "fallback": {
+        "en": "Take the rollback branch: restore rollbackIdentity by its exact digest, never by tag, and record the restored release under ## Fallbacks taken.",
+        "vi": "Đi nhánh rollback: khôi phục rollbackIdentity theo đúng digest của nó, không bao giờ theo tag, và ghi release đã khôi phục dưới ## Fallbacks taken."
+      }
+    },
+    "ROLLBACK_IDENTITY_MISSING": {
+      "domain": "provider",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "Rollback is required and its exact safe release no longer exists.",
+        "vi": "Cần rollback nhưng đúng release an toàn của nó không còn tồn tại."
+      },
+      "resume": {
+        "en": "Restore the safe release at its exact digest.",
+        "vi": "Khôi phục release an toàn ở đúng digest của nó."
+      }
+    }
+  }
+}

package/operators/release-deploy/operator.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": 9,
+  "id": "release.deploy",
+  "domain": "deployment",
+  "job": "Deploy one immutable release to one declared target under its declared authorization and prove the steady state it reached, taking the recovery or rollback branch inside the same pass rather than assuming the rollout succeeded.",
+  "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/container": "operate",
+      "@tools/ci": "read",
+      "@tools/secrets": "resolve-by-name"
+    }
+  }
+}