@starci/skills 1.1.0

package/operators/frontend-source-apply/self-test.mjs

@@ -0,0 +1,214 @@
+// Proves validate.mjs on a synthetic session branch: one conforming application on the session branch
+// (one file modified, one application-owned leaf created, one path unchanged), one dry run that
+// commits nothing, one blocked on WRITE_REJECTED with nothing written, 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 { validateApplicationStep } from './validate.mjs';
+
+const PAGE = 'app/plans/page.tsx';
+const CANVAS = 'app/plans/canvas.tsx';
+const LEGEND = 'app/plans/legend.tsx';
+const BASE = '0f1e2d3c4b5a69788796a5b4c3d2e1f009182736';
+const COMMIT = '9a8b7c6d5e4f30211203344556677889900aabbc';
+const SESSION = 's-test';
+const fp = (c) => `sha256:${c.repeat(64)}`;
+
+const inventory = () => ({
+  treeFingerprint: fp('a'),
+  classNames: ['gap-6', 'gap-4'],
+  ruleIds: ['GAP-5', 'GAP-4'],
+  gaps: [],
+});
+
+const plan = ({ mode = 'apply', commit = COMMIT } = {}) => ({
+  mode,
+  base: BASE,
+  branch: `session/${SESSION}`,
+  commit,
+  files: [
+    { path: PAGE, change: 'modified', before: fp('b'), after: fp('c'), classes: ['gap-6'] },
+    { path: CANVAS, change: 'created', before: null, after: fp('d'), classes: [] },
+    { path: LEGEND, change: 'unchanged', before: fp('e'), after: fp('e'), classes: [] },
+  ],
+});
+
+const dryPlan = () => ({
+  mode: 'dry',
+  base: BASE,
+  branch: `session/${SESSION}`,
+  commit: null,
+  files: [
+    { path: PAGE, change: 'modified', before: fp('b'), after: null, classes: ['gap-6'] },
+    { path: CANVAS, change: 'created', before: null, after: null, classes: [] },
+  ],
+});
+
+const responseMd = ({ mode = 'apply', commit = COMMIT, files } = {}) => {
+  const rows = (files ?? plan().files).map(({ path: p, change, classes }) => `| \`${p}\` | ${change} | ${classes.length ? `\`${classes[0]}\`` : '—'} | ${classes.length ? '`GAP-5`' : '—'} | ${change === 'created' ? 'an application-owned leaf carrying its contract' : 'the resolved value for this node'} |`);
+  return `# frontend-source-application — plan-picker
+
+## Binding
+
+| Field | Value |
+| --- | --- |
+| Target | \`plan-picker\` |
+| Mode | \`${mode}\` |
+| Branch | \`session/${SESSION}\` |
+| Base | \`${BASE}\` |
+| Commit | ${commit ? `\`${commit}\`` : '—'} |
+
+## Projection
+
+| Path | Change | Classes | Claims | Why |
+| --- | --- | --- | --- | --- |
+${rows.join('\n')}
+
+## Rejections
+
+| Path | Value | Because |
+| --- | --- | --- |
+
+## Fallbacks taken
+
+| Code | Action |
+| --- | --- |
+`;
+};
+
+const changesMd = ({ files } = {}) => {
+  const rows = (files ?? plan().files).map(({ path: p, change, classes }) => `| \`${p}\` | ${change} | ${change === 'created' ? 'the application-owned leaf the direction marked' : 'the resolved value for this node'} | ${classes.length ? '`GAP-5`' : '—'} |`);
+  return `# changes — frontend.source.apply step-3/parallel-1
+
+The plans page and its application-owned canvas carry the resolved spacing on the session branch.
+
+## Binding
+
+| Field | Value |
+| --- | --- |
+| Operator | \`frontend.source.apply\` |
+| Step | \`step-3/parallel-1\` |
+| Checkout | \`@workspaces/fe\` at \`${BASE}\` → \`${COMMIT}\` on \`session/${SESSION}\` |
+| Predecessor | \`step-2/parallel-1/response/response.md\` |
+
+## Files
+
+| Path | Change | Why | Claims |
+| --- | --- | --- | --- |
+${rows.join('\n')}
+
+## What the next step must know
+
+- Gates to run: the lint and type gates the checkout pins for these paths.
+- Surfaces to observe: the /plans route at both branches.
+- Not changed on purpose: the legend, because the resolution decided nothing about it.
+`;
+};
+
+const requestJson = ({ extra = {} } = {}) => ({
+  schemaVersion: 9,
+  operatorId: 'frontend.source.apply',
+  step: 3,
+  parallel: 1,
+  sessionId: SESSION,
+  contexts: [{ alias: '@workspaces/fe', head: BASE }],
+  requirements: { mode: 'apply', resume: null, ...extra },
+  inputs: {
+    'frontend-presentation-resolution': 'step-2/parallel-1/response/response.md',
+    'frontend-direction-decision': 'step-1/parallel-1/response/response.md',
+  },
+  resume: null,
+});
+
+const responseJson = ({ status = 'done', stop, fields, commits = [COMMIT], next = ['frontend.surface.audit'] } = {}) => ({
+  schemaVersion: 9,
+  operatorId: 'frontend.source.apply',
+  step: 3,
+  parallel: 1,
+  status,
+  ...(stop ? { stop } : {}),
+  fallbacks: [],
+  fields: fields ?? { 'frontend-source-application': 'response/response.md', changes: 'response/changes.md', writes: 'response/data/writes.json' },
+  commits,
+  next,
+});
+
+function writeBranch(files, { inventoryDoc = inventory(), withInventory = true } = {}) {
+  const session = mkdtempSync(path.join(tmpdir(), 'fe-apply-session-'));
+  const branch = path.join(session, 'step-3', 'parallel-1');
+  for (const d of ['request', 'response/data']) mkdirSync(path.join(branch, d), { recursive: true });
+  const upstream = path.join(session, 'step-2', 'parallel-1', 'response', 'data');
+  mkdirSync(upstream, { recursive: true });
+  mkdirSync(path.join(session, 'step-1', 'parallel-1', 'response'), { recursive: true });
+  writeFileSync(path.join(session, 'step-1', 'parallel-1', 'response', 'response.md'), '# frontend-direction-decision — plan-picker\n');
+  writeFileSync(path.join(session, 'step-2', 'parallel-1', 'response', 'response.md'), '# frontend-presentation-resolution — plan-picker\n');
+  if (withInventory) writeFileSync(path.join(upstream, 'inventory.json'), JSON.stringify(inventoryDoc, null, 2));
+  writeFileSync(path.join(session, 'state.json'), JSON.stringify({ id: SESSION, chain: [['2/1'], ['3/1']], steps: { '2/1': 'frontend.presentation.resolve', '3/1': 'frontend.source.apply' }, current: '3/1', status: 'running' }));
+  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 = () => ({
+  'request/request.json': requestJson(),
+  'response/response.json': responseJson(),
+  'response/response.md': responseMd(),
+  'response/changes.md': changesMd(),
+  'response/data/writes.json': plan(),
+});
+
+const dryRun = () => ({
+  'request/request.json': requestJson({ extra: { mode: 'dry' } }),
+  'response/response.json': responseJson({ commits: [] }),
+  'response/response.md': responseMd({ mode: 'dry', commit: null, files: dryPlan().files }),
+  'response/changes.md': changesMd({ files: dryPlan().files }),
+  'response/data/writes.json': dryPlan(),
+});
+
+async function expectValid(files, label, options) {
+  const { branch, session } = writeBranch(files, options);
+  const { errors } = await validateApplicationStep(branch);
+  rmSync(session, { recursive: true, force: true });
+  assert.deepEqual(errors, [], `${label} should be valid`);
+}
+async function expectError(files, needle, label, options) {
+  const { branch, session } = writeBranch(files, options);
+  const { errors } = await validateApplicationStep(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)'}`);
+}
+const mutate = (change) => { const p = plan(); change(p); return { ...baseline(), 'response/data/writes.json': p }; };
+
+await expectValid(baseline(), 'one modified path, one application-owned leaf created, one unchanged');
+await expectValid(dryRun(), 'a dry run that commits nothing');
+await expectValid({ 'request/request.json': requestJson(), 'response/response.json': responseJson({ status: 'blocked', stop: 'WRITE_REJECTED', commits: [], next: [], fields: {} }) }, 'blocked on WRITE_REJECTED with nothing written');
+
+await expectError({ ...baseline(), 'request/request.json': requestJson({ extra: { mystery: 1 } }) }, 'requirements.mystery is not a field', 'undeclared requirement');
+await expectError({ ...baseline(), 'request/request.json': requestJson({ extra: { mode: 'dry' } }) }, "mode apply differs from the request's dry", 'mode re-decided in the plan');
+await expectError(mutate((p) => { p.files[0].classes = ['gap-8']; }), 'writes class gap-8, which the resolution never published', 'class the resolution never published');
+await expectError(mutate((p) => { p.branch = 'mtp'; }), 'only session/<sessionId> may be committed to', 'write on the person\'s branch');
+await expectError(mutate((p) => { p.branch = 'session/other'; }), 'is not the session branch of', 'write on another session branch');
+await expectError(mutate((p) => { p.commit = null; }), 'commits the declared write set exactly once', 'applied run without a commit');
+await expectError({ ...baseline(), 'response/response.json': responseJson({ commits: [COMMIT, BASE] }) }, 'records exactly one commit, found 2', 'two commits for one write set');
+await expectError({ ...baseline(), 'response/response.json': responseJson({ commits: [BASE] }) }, 'is not the commit', 'response and plan disagree on the commit');
+await expectError({ ...dryRun(), 'response/response.json': responseJson({ commits: [COMMIT] }) }, 'a dry run records no commit', 'dry run that committed');
+await expectError({ ...dryRun(), 'response/data/writes.json': { ...dryPlan(), commit: COMMIT } }, 'a dry run commits nothing, so commit must be null', 'dry plan carrying a commit');
+await expectError(mutate((p) => { p.files = p.files.map((f) => ({ ...f, change: 'unchanged', before: f.after ?? fp('e'), after: f.after ?? fp('e'), classes: [] })); }), 'moves at least one declared path', 'nothing moved');
+await expectError(mutate((p) => { p.files[0].after = p.files[0].before; }), 'reports a modification with an unchanged hash', 'modification that did not move');
+await expectError(mutate((p) => { p.files[1].before = fp('f'); }), 'was created but reports a prior hash', 'creation with a prior hash');
+await expectError(mutate((p) => { p.files[2].classes = ['gap-6']; }), 'is reported unchanged while carrying classes', 'unchanged file carrying classes');
+await expectError(mutate((p) => { p.files.push({ ...p.files[0] }); }), 'appears twice in the plan', 'one path planned twice');
+await expectError({ ...baseline(), 'response/response.md': responseMd({ commit: BASE }) }, 'Commit', 'receipt and plan disagree on the commit');
+await expectError({ ...baseline(), 'response/changes.md': changesMd().replace(`| \`${LEGEND}\` | unchanged | the resolved value for this node | — |\n`, '') }, 'Files lists 2 paths, the plan carries 3', 'changes.md hides a planned path');
+await expectError({ ...baseline(), 'response/changes.md': changesMd().replace('| modified |', '| deleted |') }, 'is deleted here and modified in the plan', 'changes.md contradicts the plan');
+await expectError({ ...baseline(), 'response/changes.md': changesMd().replace(` on \`session/${SESSION}\``, '') }, 'does not name the session branch', 'changes.md hides the session branch');
+await expectError(baseline(), 'the resolution inventory could not be read', 'inventory missing beside the receipt', { withInventory: false });
+await expectError({ ...baseline(), 'response/response.md': responseMd().replace('## Rejections', '## Rejected') }, 'missing section ^## Rejections$', 'receipt section renamed');
+await expectError({ ...baseline(), 'response/data/writes.json': null, 'response/response.json': responseJson({ fields: { 'frontend-source-application': 'response/response.md', changes: 'response/changes.md' } }) }, 'required output writes is not in fields', 'missing required output');
+await expectError({ ...baseline(), 'response/response.json': responseJson({ status: 'blocked', stop: 'MADE_UP_CODE', commits: [], next: [] }) }, 'not a registered code', 'unknown stop code');
+
+process.stdout.write('frontend.source.apply self-test: 3 valid branches, 22 rejected mutations\n');

package/operators/frontend-source-apply/validate.mjs

@@ -0,0 +1,133 @@
+// frontend.source.apply's own law over one branch, on top of the shared step check: every class in every
+// written file comes from the bound resolution's inventory, which is read back beside the resolution
+// receipt the request named; the write lands on the session branch and nowhere else; a dry run
+// commits nothing and an applied run commits exactly once; created, modified and unchanged agree with
+// the hashes; and the receipt and changes.md list exactly the files the plan carries.
+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';
+import { sessionRootOf } from '../../scripts/validate-request.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const empty = (v) => v === undefined || v === null || v === '' || v === '—';
+
+// The inventory the resolution froze sits beside its receipt: <branch>/response/data/inventory.json.
+export function inventoryPathFor(resolutionRef) {
+  return resolutionRef.replace(/response\/[a-z-]+\.md$/, 'response/data/inventory.json');
+}
+
+export async function validateApplicationStep(branchDir, root = ROOT) {
+  const base = await validateStep(root, branchDir);
+  const errors = [...base.errors];
+  const { request, response, requirements = {}, present = new Set() } = base;
+  if (!response || response.operatorId !== 'frontend.source.apply') return { errors };
+  const has = (f) => existsSync(path.join(branchDir, f));
+  const read = (f) => readFile(path.join(branchDir, f), 'utf8');
+  const mode = requirements.mode ?? 'apply';
+
+  let plan = null;
+  if (present.has('writes') && has('response/data/writes.json')) {
+    try { plan = JSON.parse(await read('response/data/writes.json')); } catch { plan = null; }
+  }
+  if (!plan) {
+    if (response.status === 'done') errors.push('response/data/writes.json: a done branch needs the write plan');
+    return { errors };
+  }
+  const at = 'response/data/writes.json';
+
+  if (plan.mode !== mode) errors.push(`${at}: mode ${plan.mode} differs from the request's ${mode}`);
+  if (!plan.branch.startsWith('session/')) errors.push(`${at}: the write lands on ${plan.branch}; only session/<sessionId> may be committed to`);
+  if (request?.sessionId && plan.branch !== `session/${request.sessionId}`) errors.push(`${at}: branch ${plan.branch} is not the session branch of ${request.sessionId}`);
+
+  const commits = response.commits ?? [];
+  if (mode === 'dry') {
+    if (plan.commit !== null) errors.push(`${at}: a dry run commits nothing, so commit must be null`);
+    if (commits.length) errors.push('response/response.json: a dry run records no commit');
+    for (const file of plan.files) if (file.change !== 'unchanged' && file.after !== null && file.before !== file.after) {
+      errors.push(`${at}: ${file.path} reports a change under a dry run, which writes nothing`);
+    }
+  } else if (response.status === 'done') {
+    if (plan.commit === null) errors.push(`${at}: an applied branch commits the declared write set exactly once`);
+    if (commits.length !== 1) errors.push(`response/response.json: an applied branch records exactly one commit, found ${commits.length}`);
+    else if (plan.commit !== null && commits[0] !== plan.commit) errors.push(`response/response.json: commits[0] ${commits[0]} is not the commit ${plan.commit} the plan recorded`);
+    if (!plan.files.some((f) => f.change !== 'unchanged')) errors.push(`${at}: an applied branch moves at least one declared path (NO_PROGRESS otherwise)`);
+  }
+
+  // Every value that entered source came from the resolution; there is no other source of one.
+  const sessionRoot = sessionRootOf(branchDir);
+  const resolutionRef = request?.inputs?.['frontend-presentation-resolution'];
+  let inventory = null;
+  if (sessionRoot && resolutionRef) {
+    const full = path.join(sessionRoot, inventoryPathFor(resolutionRef));
+    if (existsSync(full)) { try { inventory = JSON.parse(await readFile(full, 'utf8')); } catch { inventory = null; } }
+  }
+  if (inventory) {
+    const published = new Set(inventory.classNames);
+    for (const file of plan.files) {
+      for (const className of file.classes) {
+        if (!published.has(className)) errors.push(`${at}: ${file.path} writes class ${className}, which the resolution never published (WRITE_REJECTED)`);
+      }
+    }
+  } else if (response.status === 'done') errors.push(`${at}: the resolution inventory could not be read beside the receipt the request bound (RESOLUTION_STALE)`);
+
+  const seen = new Set();
+  for (const file of plan.files) {
+    if (seen.has(file.path)) errors.push(`${at}: path ${file.path} appears twice in the plan`);
+    seen.add(file.path);
+    if (file.change === 'created' && file.before !== null) errors.push(`${at}: ${file.path} was created but reports a prior hash`);
+    if (file.change === 'modified') {
+      if (file.before === null) errors.push(`${at}: ${file.path} was modified but reports no prior hash`);
+      else if (file.before === file.after) errors.push(`${at}: ${file.path} reports a modification with an unchanged hash`);
+    }
+    if (file.change === 'unchanged') {
+      if (file.before !== file.after) errors.push(`${at}: ${file.path} is reported unchanged with a different hash`);
+      if (file.classes.length) errors.push(`${at}: ${file.path} is reported unchanged while carrying classes`);
+    }
+    if (file.change === 'deleted' && file.after !== null) errors.push(`${at}: ${file.path} was deleted and still reports a later hash`);
+  }
+
+  if (present.has('frontend-source-application') && has('response/response.md')) {
+    const text = await read('response/response.md');
+    const rel = 'response/response.md';
+    const binding = Object.fromEntries((tableUnder(text, '## Binding') ?? []).map(([k, v]) => [k, v]));
+    if (binding.Mode !== mode) errors.push(`${rel}: Mode ${binding.Mode} differs from the request's ${mode}`);
+    if (binding.Branch !== plan.branch) errors.push(`${rel}: Branch differs from the write plan`);
+    if (binding.Base !== plan.base) errors.push(`${rel}: Base differs from the write plan`);
+    if (binding.Commit !== (plan.commit ?? '—')) errors.push(`${rel}: Commit ${binding.Commit} differs from the write plan's ${plan.commit ?? '—'}`);
+    const rows = tableUnder(text, '## Projection') ?? [];
+    if (rows.length !== plan.files.length) errors.push(`${rel}: Projection has ${rows.length} rows, the plan has ${plan.files.length}`);
+    for (const [p, change] of rows) {
+      const file = plan.files.find((f) => f.path === p);
+      if (!file) { errors.push(`${rel}: Projection names ${p}, which the plan does not carry`); continue; }
+      if (file.change !== change) errors.push(`${rel}: ${p} is ${change} here and ${file.change} in the plan`);
+    }
+  }
+
+  if (present.has('changes') && has('response/changes.md')) {
+    const text = await read('response/changes.md');
+    const rel = 'response/changes.md';
+    const rows = tableUnder(text, '## Files') ?? [];
+    const listed = rows.map(([p]) => p).sort();
+    const planned = plan.files.map((f) => f.path).sort();
+    if (listed.join('\n') !== planned.join('\n')) errors.push(`${rel}: Files lists ${listed.length} paths, the plan carries ${planned.length}`);
+    for (const [p, change] of rows) {
+      const file = plan.files.find((f) => f.path === p);
+      if (!file) { errors.push(`${rel}: Files names ${p}, which the plan does not carry`); continue; }
+      if (file.change !== change) errors.push(`${rel}: ${p} is ${change} here and ${file.change} in the plan`);
+    }
+    const binding = Object.fromEntries((tableUnder(text, '## Binding') ?? []).map(([k, v]) => [k, v]));
+    if (!empty(binding.Checkout) && !binding.Checkout.includes(plan.branch)) errors.push(`${rel}: the Checkout row does not name the session branch ${plan.branch}`);
+  }
+  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 validateApplicationStep(path.resolve(target));
+  if (errors.length) { process.stderr.write(`${errors.join('\n')}\n`); process.exitCode = 1; } else process.stdout.write('valid frontend.source.apply branch\n');
+}

package/operators/frontend-surface-audit/errors.json

@@ -0,0 +1,5 @@
+{
+  "schemaVersion": 9,
+  "note": "Stop codes frontend.surface.audit emits. INVALID_INPUT, SOURCE_DRIFT, EVIDENCE_MISSING and NO_PROGRESS come from operators/errors.json. RUNTIME_UNAVAILABLE is defined here and also emitted by uat.verify; UNKNOWN_RULE is emitted here too and is defined in operators/frontend-presentation-resolve/errors.json. Both belong in operators/errors.json with a scope list naming every operator that emits them.",
+  "codes": {}
+}

package/operators/frontend-surface-audit/operator.json

@@ -0,0 +1,22 @@
+{
+  "schemaVersion": 9,
+  "id": "frontend.surface.audit",
+  "domain": "frontend",
+  "job": "Observe one rendered surface across a declared viewport and state matrix, measure every presentation value it actually produces, compare each measurement against the contract claim on that node, and return findings drawn only from the bound rule inventory.",
+  "package": "operator.md",
+  "errors": "errors.json",
+  "validator": "validate.mjs",
+  "selfTest": "self-test.mjs",
+  "resources": {
+    "profile": "sol-reviewer",
+    "grammarBound": true,
+    "tools": {
+      "@tools/fileread": "context-aliases",
+      "@tools/git": "read",
+      "@tools/websearch": "bounded",
+      "@tools/visualize": "html",
+      "@tools/browsercontrol": "required",
+      "@tools/http": "probe"
+    }
+  }
+}

package/operators/frontend-surface-audit/operator.md

@@ -0,0 +1,121 @@
+# frontend.surface.audit
+
+## Job
+
+Observe the committed surface at the served route across the matrix the direction's coverage implies,
+measure every node that carries a claim, and judge each measurement against the published proof rules
+by the owner of the node it stands on.
+
+## Readiness, capture and judgement are one job
+
+Splitting them produced a familiar failure: a capture taken before the surface was ready, judged by a
+step that could no longer tell, against evidence it had not itself collected. One operator that
+waits, measures and judges under one receipt cannot lose that connection.
+
+## The surface must be the committed surface
+
+The applied receipt names the commit it wrote, the pinned head equals that commit, and the preview
+serves the session worktree at it. A head that differs is `SOURCE_DRIFT` with nothing captured,
+because a measurement of another tree proves nothing about this one.
+
+## Measurement beats claim, always
+
+Each node carries the identifiers it claims to satisfy, and the audit measures what the surface
+actually renders. A claim is never evidence of passing: a node claiming `GAP-4` while the computed
+gap measures `1.5rem` is a failure, and no amount of claiming changes the measurement. That is the
+whole mechanic, and it is why the claim exists.
+
+## The owner decides where a failure goes
+
+A failing claim on an application-owned node is a value the resolution has to publish again, so it
+routes back to `frontend.presentation.resolve`, which is the operator that caps the rounds. A failing claim
+on a Grammar component's own render is a Grammar gap: it goes to a person and into the family's own
+gap table, never into a resolve loop, because no application value can fix a component. The interior
+of an application-owned node carries no claim and is not audited at all; only that node's own measure
+rules are.
+
+## The audit changes nothing
+
+No verdict is a repair, a workaround or an instruction. A failure stays a failure in the receipt
+until a resolution publishes a new value and the applier writes it, and the same surface is audited
+again. That separation is why the receipt is worth anything: an operator that could fix what it found
+would always be able to report a clean surface.
+
+## Boundary
+
+Context is read-only, and the runtime is consumed, never owned. The operator writes only `response/`
+of its own branch: the audit receipt, its captures, its screenshots and its verdicts. It does not
+modify product source, the applied tree, knowledge or Grammar, repair, restyle or work around
+anything it observes, start, stop, deploy or reconfigure a runtime service, cite a rule identifier
+absent from the bound inventory, judge a node it did not measure, or accept a claim as evidence that
+a node passes.
+
+## Context
+
+| Alias | Bind | Required |
+| --- | --- | --- |
+| `@knowledge/ui/proof` | what only becomes true once rendered; the audit's whole rule inventory | yes |
+| `@workspaces/fe` | the routed checkout at the commit the application wrote; the owners and identifiers observed there | yes |
+| `@worktrees/sessions/central-runtime` | the shared runtime owner: the preview serving the session worktree at that commit | yes |
+| `@knowledge/grammars/starci` | how the Core family is meant to realize Common, and where its gaps are recorded | no |
+
+## Inputs
+
+| Kind | From | Required |
+| --- | --- | --- |
+| `frontend-source-application` | `frontend.source.apply`, the commit under observation and the claims it wrote | yes |
+| `frontend-presentation-resolution` | `frontend.presentation.resolve`, the owner of every node | yes |
+| `frontend-direction-decision` | `frontend.direction.decide`, the route and the coverage the matrix is derived from | yes |
+
+## Requirements
+
+| Field | Type | Default | Ask |
+| --- | --- | --- | --- |
+| `matrix` | list | every coverage entry | The matrix entries to capture; the person may only narrow what the coverage implies |
+| `readinessProbe` | choice | route-served | The floor for readiness; a state that needs data rises to `route-and-data-served` on its own |
+| `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 and resume, and confirm the head and the served route | `resume` | `request/request.json`, input `frontend-source-application` (its commit must equal the pinned head), @workspaces/fe at the frozen head, @worktrees/sessions/central-runtime (the preview serving the session worktree at that commit), @tools/git | — | `INVALID_INPUT`, `SOURCE_DRIFT`, `NO_PROGRESS` |
+| 2 | Bind the authority | — | @knowledge/ui/proof (every topic with its fingerprint and inventory), input `frontend-source-application` (the claims), input `frontend-presentation-resolution` (the owner of every node), @worktrees/sessions/central-runtime | — | — |
+| 3 | Select the matrix entries | `matrix` | input `frontend-direction-decision` (the coverage: state by viewport by colour scheme) | — | — |
+| 4 | Reach readiness for each entry | `readinessProbe` | @worktrees/sessions/central-runtime, @tools/http | — | `RUNTIME_UNAVAILABLE` |
+| 5 | Capture and measure each entry | — | @worktrees/sessions/central-runtime, @workspaces/fe (the observed owners and the identifiers each node carries), @tools/browsercontrol | `response/artifacts/<matrixId>.png`, `response/data/captures/<matrixId>.json` | `EVIDENCE_MISSING` |
+| 6 | Compare against the claims and the proof rules, judge by owner, and emit | — | @knowledge/ui/proof, @knowledge/grammars/starci, the captures, @tools/websearch | `response/data/verdicts.json`, `response/response.md`, `response/response.json`, @tools/visualize | `UNKNOWN_RULE` |
+
+The matrix is the direction's coverage, not a new decision: `matrix` may only narrow it, and the
+orchestrator may split the entries across up to three parallel branches of the same step. Every entry
+produces one screenshot and one capture, and an entry that produced neither is `EVIDENCE_MISSING`
+rather than a quiet omission. Every node carrying a claim is measured; a verdict is never recorded
+for a node that was not.
+
+## Outputs
+
+| Kind | File | Type | Required |
+| --- | --- | --- | --- |
+| `frontend-surface-audit` | `response/response.md` | md | yes |
+| `capture` | `response/data/captures/<matrixId>.json` | data | yes |
+| `screenshot` | `response/artifacts/<matrixId>.png` | artifact | yes |
+| `verdicts` | `response/data/verdicts.json` | data | yes |
+
+## Stops
+
+| Code | Disposition |
+| --- | --- |
+| `INVALID_INPUT` | terminate |
+| `SOURCE_DRIFT` | terminate |
+| `RUNTIME_UNAVAILABLE` | terminate |
+| `EVIDENCE_MISSING` | terminate |
+| `UNKNOWN_RULE` | terminate |
+| `NO_PROGRESS` | terminate |
+
+## Next
+
+| When | Operator |
+| --- | --- |
+| a claim fails on an application-owned node, so a value must be published again | `frontend.presentation.resolve` |
+| every claim holds and the checkout's own gates must run | `quality.verify` |
+| a claim fails on a Grammar component's own render, so a person records the family gap and publishes | `frontend.surface.audit` |

package/operators/frontend-surface-audit/operator.vi.md

@@ -0,0 +1,121 @@
+# frontend.surface.audit
+
+## Việc
+
+Quan sát bề mặt đã commit ở route đang được phục vụ, qua đúng ma trận mà coverage của hướng suy ra,
+đo mọi node có mang lời khai, và phán quyết từng phép đo theo luật proof đã publish, dựa trên chủ sở
+hữu của node mà nó đứng lên.
+
+## Sẵn sàng, chụp và phán quyết là một việc
+
+Tách chúng ra đã sinh ra một kiểu hỏng quen thuộc: một bức chụp lấy trước khi bề mặt sẵn sàng, bị
+phán quyết bởi một bước không còn cách nào biết điều đó, dựa trên bằng chứng mà chính nó không thu.
+Một operator vừa chờ, vừa đo, vừa phán quyết dưới một biên nhận thì không đánh mất mối nối ấy.
+
+## Bề mặt phải là bề mặt đã commit
+
+Biên nhận áp dụng gọi tên commit nó đã ghi, head được ghim bằng đúng commit đó, và preview phục vụ
+worktree phiên ở chính commit ấy. Head khác là `SOURCE_DRIFT` và không chụp gì cả, vì đo một cây khác
+thì không chứng minh được gì về cây này.
+
+## Phép đo thắng lời khai, luôn luôn
+
+Mỗi node mang những identifier nó khai là mình thoả, và lượt audit đo thứ bề mặt thực sự render ra.
+Lời khai không bao giờ là bằng chứng của việc pass: một node khai `GAP-4` trong khi gap tính được đo
+ra `1.5rem` là một lần hỏng, và khai bao nhiêu cũng không đổi được phép đo. Đó là toàn bộ cơ chế, và
+đó là lý do lời khai tồn tại.
+
+## Chủ sở hữu quyết định chỗ hỏng đi về đâu
+
+Một lời khai hỏng trên node do ứng dụng sở hữu là một giá trị mà resolution phải publish lại, nên nó
+quay về `frontend.presentation.resolve`, chính operator giữ số vòng. Một lời khai hỏng trên phần render của
+chính một component Grammar là một khoảng trống Grammar: nó đi tới một con người và vào bảng gap của
+họ, không bao giờ đi vào vòng lặp resolve, vì không giá trị ứng dụng nào sửa được một component. Phần
+ruột của node do ứng dụng sở hữu không mang lời khai nào và không bị audit; chỉ các luật đo của chính
+node ấy bị audit.
+
+## Audit không đổi gì cả
+
+Không phán quyết nào là một lần sửa, một cách chữa cháy hay một mệnh lệnh. Một chỗ hỏng vẫn là chỗ
+hỏng trong biên nhận cho tới khi một lượt resolution publish giá trị mới và người ghi viết nó xuống,
+rồi chính bề mặt ấy được audit lại. Sự tách bạch đó là lý do biên nhận này có giá trị: một operator
+có thể tự sửa thứ nó tìm ra thì lúc nào cũng báo được một bề mặt sạch.
+
+## Ranh giới
+
+Context chỉ đọc, và runtime là thứ được tiêu thụ chứ không được sở hữu. Operator chỉ ghi `response/`
+của nhánh mình: biên nhận audit, các bức chụp, các ảnh màn hình và các phán quyết. Nó không sửa source
+sản phẩm, cây đã áp dụng, knowledge hay Grammar, không sửa chữa, không tô lại, không chữa cháy bất cứ
+thứ gì nó thấy, không khởi động, dừng, deploy hay cấu hình lại dịch vụ runtime, không trích một
+identifier vắng mặt trong kho đã bind, không phán quyết một node nó chưa đo, và không nhận lời khai
+làm bằng chứng rằng node đã pass.
+
+## Context
+
+| Alias | Bind | Bắt buộc |
+| --- | --- | --- |
+| `@knowledge/ui/proof` | thứ chỉ thành thật khi đã render; toàn bộ kho luật của lượt audit | có |
+| `@workspaces/fe` | checkout được route ở commit mà lần áp dụng đã ghi; chủ sở hữu và identifier được quan sát ở đó | có |
+| `@worktrees/sessions/central-runtime` | chủ runtime dùng chung: preview đang phục vụ worktree phiên ở commit ấy | có |
+| `@knowledge/grammars/starci` | họ Core được kỳ vọng hiện thực hoá Common ra sao, và gap của họ được ghi ở đâu | không |
+
+## Đầu vào
+
+| Kind | Từ đâu | Bắt buộc |
+| --- | --- | --- |
+| `frontend-source-application` | `frontend.source.apply`, commit đang được quan sát và các lời khai nó đã ghi | có |
+| `frontend-presentation-resolution` | `frontend.presentation.resolve`, chủ sở hữu của từng node | có |
+| `frontend-direction-decision` | `frontend.direction.decide`, route và coverage mà ma trận suy ra từ đó | có |
+
+## Yêu cầu
+
+| Field | Kiểu | Mặc định | Hỏi |
+| --- | --- | --- | --- |
+| `matrix` | list | every coverage entry | Các mục ma trận cần chụp; người dùng chỉ được thu hẹp thứ coverage đã suy ra |
+| `readinessProbe` | choice | route-served | Mức sàn của sẵn sàng; một state cần dữ liệu tự nâng lên `route-and-data-served` |
+| `resume` | token | null | Token của nhánh bị chặn khi vào lại sau một mã dừng |
+
+## Các bước
+
+| # | Bước | Tham số | Đọc | Ghi | Dừng với |
+| --- | --- | --- | --- | --- | --- |
+| 1 | Kiểm gate, chạy lại, và xác nhận head cùng route đang phục vụ | `resume` | `request/request.json`, đầu vào `frontend-source-application` (commit của nó phải bằng head đã ghim), @workspaces/fe ở head đóng băng, @worktrees/sessions/central-runtime (preview phục vụ worktree phiên ở commit ấy), @tools/git | — | `INVALID_INPUT`, `SOURCE_DRIFT`, `NO_PROGRESS` |
+| 2 | Bind thẩm quyền | — | @knowledge/ui/proof (mọi topic kèm fingerprint và kho luật), đầu vào `frontend-source-application` (các lời khai), đầu vào `frontend-presentation-resolution` (chủ sở hữu của từng node), @worktrees/sessions/central-runtime | — | — |
+| 3 | Chọn các mục ma trận | `matrix` | đầu vào `frontend-direction-decision` (coverage: state nhân viewport nhân bảng màu) | — | — |
+| 4 | Chờ từng mục tới lúc sẵn sàng | `readinessProbe` | @worktrees/sessions/central-runtime, @tools/http | — | `RUNTIME_UNAVAILABLE` |
+| 5 | Chụp và đo từng mục | — | @worktrees/sessions/central-runtime, @workspaces/fe (các owner được quan sát và identifier từng node mang), @tools/browsercontrol | `response/artifacts/<matrixId>.png`, `response/data/captures/<matrixId>.json` | `EVIDENCE_MISSING` |
+| 6 | Đối chiếu với lời khai và luật proof, phán quyết theo chủ sở hữu, rồi phát | — | @knowledge/ui/proof, @knowledge/grammars/starci, các bức chụp, @tools/websearch | `response/data/verdicts.json`, `response/response.md`, `response/response.json`, @tools/visualize | `UNKNOWN_RULE` |
+
+Ma trận là coverage của hướng, không phải một quyết định mới: `matrix` chỉ được thu hẹp nó, và
+orchestrator có thể chia các mục ra tối đa ba nhánh song song của cùng một bậc. Mỗi mục cho đúng một
+ảnh màn hình và một bức chụp, và một mục không cho cái nào là `EVIDENCE_MISSING` chứ không phải một
+chỗ khuyết lặng lẽ. Mọi node mang lời khai đều được đo; không bao giờ có phán quyết cho một node chưa
+được đo.
+
+## Đầu ra
+
+| Kind | File | Kiểu | Bắt buộc |
+| --- | --- | --- | --- |
+| `frontend-surface-audit` | `response/response.md` | md | có |
+| `capture` | `response/data/captures/<matrixId>.json` | data | có |
+| `screenshot` | `response/artifacts/<matrixId>.png` | artifact | có |
+| `verdicts` | `response/data/verdicts.json` | data | có |
+
+## Dừng
+
+| Code | Xử lý |
+| --- | --- |
+| `INVALID_INPUT` | terminate |
+| `SOURCE_DRIFT` | terminate |
+| `RUNTIME_UNAVAILABLE` | terminate |
+| `EVIDENCE_MISSING` | terminate |
+| `UNKNOWN_RULE` | terminate |
+| `NO_PROGRESS` | terminate |
+
+## Kế tiếp
+
+| Khi | Operator |
+| --- | --- |
+| một lời khai hỏng trên node do ứng dụng sở hữu, nên phải publish lại một giá trị | `frontend.presentation.resolve` |
+| mọi lời khai đều đứng vững và các cổng của chính checkout phải chạy | `quality.verify` |
+| một lời khai hỏng trên phần render của chính component Grammar, nên một người ghi gap của họ rồi publish | `frontend.surface.audit` |