@starci/skills 1.1.0

package/operators/frontend-surface-audit/self-test.mjs

@@ -0,0 +1,185 @@
+// Proves validate.mjs on a synthetic session branch: one conforming audit over two matrix entries
+// (one all-pass entry, one entry whose application-owned node fails and routes back to resolve), one
+// blocked on EVIDENCE_MISSING with nothing captured, 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 { validateAuditStep } from './validate.mjs';
+
+const WIDE = 'wide-light-loaded';
+const NARROW = 'narrow-light-loaded';
+const MAIN = 'body>main';
+const SECTION = 'body>main>section';
+const CAP = (id) => `response/data/captures/${id}.json`;
+const SHOT = (id) => `response/artifacts/${id}.png`;
+
+const capture = (id) => ({
+  matrixId: id,
+  viewport: id === WIDE ? [1440, 900] : [390, 844],
+  scheme: 'light',
+  state: 'loaded',
+  nodes: [
+    { path: MAIN, owner: 'app', claims: ['GAP-5'], measured: { gap: id === WIDE ? '1.5rem' : '1rem' } },
+    { path: SECTION, owner: 'grammar', claims: ['PADDING-4'], measured: { padding: '1rem' } },
+  ],
+});
+
+const verdicts = () => ({
+  entries: [
+    {
+      matrixId: WIDE,
+      results: [
+        { path: MAIN, owner: 'app', rule: 'GAP-5', measured: '1.5rem', verdict: 'pass', routeTo: 'none' },
+        { path: SECTION, owner: 'grammar', rule: 'PADDING-4', measured: '1rem', verdict: 'pass', routeTo: 'none' },
+      ],
+    },
+    {
+      matrixId: NARROW,
+      results: [
+        { path: MAIN, owner: 'app', rule: 'GAP-5', measured: '1rem', verdict: 'fail', routeTo: 'resolve' },
+        { path: SECTION, owner: 'grammar', rule: 'PADDING-4', measured: '1rem', verdict: 'pass', routeTo: 'none' },
+      ],
+    },
+  ],
+});
+
+const responseMd = () => `# frontend-surface-audit — plan-picker
+
+## Matrix
+
+| Matrix | Viewport | Scheme | State | Screenshot |
+| --- | --- | --- | --- | --- |
+| \`${WIDE}\` | 1440x900 | light | loaded | \`${SHOT(WIDE)}\` |
+| \`${NARROW}\` | 390x844 | light | loaded | \`${SHOT(NARROW)}\` |
+
+## Verdicts by owner
+
+| Matrix | Owner | Node | Rule | Measured | Verdict |
+| --- | --- | --- | --- | --- | --- |
+| \`${WIDE}\` | app | \`${MAIN}\` | \`GAP-5\` | 1.5rem | pass |
+| \`${WIDE}\` | grammar | \`${SECTION}\` | \`PADDING-4\` | 1rem | pass |
+| \`${NARROW}\` | app | \`${MAIN}\` | \`GAP-5\` | 1rem | fail |
+| \`${NARROW}\` | grammar | \`${SECTION}\` | \`PADDING-4\` | 1rem | pass |
+
+## Regressions
+
+| Matrix | Node | Rule | Measured | Routes to |
+| --- | --- | --- | --- | --- |
+| \`${NARROW}\` | \`${MAIN}\` | \`GAP-5\` | 1rem | resolve |
+
+## Grammar gaps
+
+| Component | Rule | What the family lacks |
+| --- | --- | --- |
+
+## Fallbacks taken
+
+| Code | Action |
+| --- | --- |
+`;
+
+const requestJson = ({ extra = {} } = {}) => ({
+  schemaVersion: 9,
+  operatorId: 'frontend.surface.audit',
+  step: 4,
+  parallel: 1,
+  sessionId: 's-test',
+  contexts: [{ alias: '@knowledge/ui/proof', head: null }, { alias: '@workspaces/fe', head: 'e'.repeat(40) }, { alias: '@worktrees/sessions/central-runtime', head: null }],
+  requirements: { matrix: [], readinessProbe: 'route-served', resume: null, ...extra },
+  inputs: {
+    'frontend-source-application': 'step-3/parallel-1/response/response.md',
+    '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, next = ['frontend.presentation.resolve'] } = {}) => ({
+  schemaVersion: 9,
+  operatorId: 'frontend.surface.audit',
+  step: 4,
+  parallel: 1,
+  status,
+  ...(stop ? { stop } : {}),
+  fallbacks: [],
+  fields: fields ?? {
+    'frontend-surface-audit': 'response/response.md',
+    verdicts: 'response/data/verdicts.json',
+    capture: [CAP(WIDE), CAP(NARROW)],
+    screenshot: [SHOT(WIDE), SHOT(NARROW)],
+  },
+  commits: [],
+  next,
+});
+
+function writeBranch(files) {
+  const session = mkdtempSync(path.join(tmpdir(), 'fe-audit-session-'));
+  const branch = path.join(session, 'step-4', 'parallel-1');
+  for (const d of ['request', 'response/data/captures', 'response/artifacts']) mkdirSync(path.join(branch, d), { recursive: true });
+  for (const [step, name] of [[1, 'frontend-direction-decision'], [2, 'frontend-presentation-resolution'], [3, 'frontend-source-application']]) {
+    const dir = path.join(session, `step-${step}`, 'parallel-1', 'response');
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path.join(dir, 'response.md'), `# ${name} — plan-picker\n`);
+  }
+  writeFileSync(path.join(session, 'state.json'), JSON.stringify({ id: 's-test', chain: [['3/1'], ['4/1']], steps: { '3/1': 'frontend.source.apply', '4/1': 'frontend.surface.audit' }, current: '4/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/data/verdicts.json': verdicts(),
+  [CAP(WIDE)]: capture(WIDE),
+  [CAP(NARROW)]: capture(NARROW),
+  [SHOT(WIDE)]: 'PNG',
+  [SHOT(NARROW)]: 'PNG',
+});
+
+async function expectValid(files, label) {
+  const { branch, session } = writeBranch(files);
+  const { errors } = await validateAuditStep(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 validateAuditStep(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 v = verdicts(); change(v); return { ...baseline(), 'response/data/verdicts.json': v }; };
+
+await expectValid(baseline(), 'two entries: one all-pass, one application-owned failure routed back to resolve');
+await expectValid({ 'request/request.json': requestJson(), 'response/response.json': responseJson({ status: 'blocked', stop: 'EVIDENCE_MISSING', next: [], fields: {} }) }, 'blocked on EVIDENCE_MISSING with nothing captured');
+
+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: { matrix: [{ matrixId: WIDE }] } }) }, 'the request narrowed the matrix without it', 'entry judged outside the narrowed matrix');
+await expectError(mutate((v) => { v.entries[1].results[0].routeTo = 'none'; }), 'fails and routes nowhere', 'failure that routes nowhere');
+await expectError(mutate((v) => { v.entries[1].results[0].routeTo = 'grammar-gap'; }), 'application-owned and its failure must route to resolve', 'application failure sent to the family');
+await expectError(mutate((v) => { v.entries[1].results[1].verdict = 'fail'; v.entries[1].results[1].routeTo = 'resolve'; }), "a failure there is a grammar-gap, never a resolve loop", 'Grammar failure sent into the resolve loop');
+await expectError(mutate((v) => { v.entries[0].results[0].routeTo = 'resolve'; }), 'passes and still routes to resolve', 'passing node that routes somewhere');
+await expectError(mutate((v) => { v.entries[1].results[0].rule = 'GAP-4'; }), 'which that node never claimed', 'judged on a rule nobody claimed');
+await expectError(mutate((v) => { v.entries[0].results[0].measured = '2rem'; }), 'which the capture did not measure', 'judged against a value nobody measured');
+await expectError(mutate((v) => { v.entries[0].results[0].owner = 'grammar'; }), 'in the capture', 'owner differs from the capture');
+await expectError(mutate((v) => { v.entries[0].results.push({ path: 'body>footer', owner: 'app', rule: 'GAP-1', measured: '0.25rem', verdict: 'pass', routeTo: 'none' }); }), 'was never measured there', 'verdict without a measurement');
+await expectError(mutate((v) => { v.entries[0].results = [v.entries[0].results[0]]; }), 'and no verdict judges it', 'claim left unjudged');
+await expectError(mutate((v) => { v.entries.push({ ...v.entries[0] }); }), 'is judged twice', 'one entry judged twice');
+await expectError({ ...baseline(), 'response/response.json': responseJson({ fields: { 'frontend-surface-audit': 'response/response.md', verdicts: 'response/data/verdicts.json', capture: [CAP(WIDE), CAP(NARROW)], screenshot: [SHOT(WIDE)] } }) }, 'has verdicts and no screenshot', 'entry without a screenshot');
+await expectError({ ...baseline(), 'response/response.json': responseJson({ next: ['quality.verify'] }) }, 'so next names frontend.presentation.resolve', 'failure that never reaches the resolver');
+await expectError({ ...baseline(), [CAP(NARROW)]: { ...capture(NARROW), viewport: [1440, 900] } }, 'in the capture', 'receipt and capture disagree on the viewport');
+await expectError({ ...baseline(), 'response/response.md': responseMd().replace('| 1rem | fail |', '| 1rem | pass |') }, 'is pass here and fail in the verdicts', 'receipt hides a failure');
+const dropRegression = (text) => text.split(String.fromCharCode(10)).filter((l) => !l.startsWith('| `narrow-light-loaded` | `body>main`')).join(String.fromCharCode(10));
+await expectError({ ...baseline(), 'response/response.md': dropRegression(responseMd()) }, 'Regressions has 0 rows, the verdicts carry 1 failures', 'regression dropped from the receipt');
+await expectError({ ...baseline(), 'response/response.md': responseMd().replace('## Grammar gaps', '## Gaps') }, 'missing section ^## Grammar gaps$', 'receipt section renamed');
+await expectError({ ...baseline(), 'response/data/verdicts.json': null, 'response/response.json': responseJson({ fields: { 'frontend-surface-audit': 'response/response.md', capture: [CAP(WIDE), CAP(NARROW)], screenshot: [SHOT(WIDE), SHOT(NARROW)] } }) }, 'required output verdicts is not in fields', 'missing required output');
+await expectError({ ...baseline(), [CAP(WIDE)]: { ...capture(WIDE), viewport: [10, 10] } }, 'viewport', 'capture schema');
+await expectError({ ...baseline(), 'response/response.json': responseJson({ status: 'blocked', stop: 'MADE_UP_CODE', next: [] }) }, 'not a registered code', 'unknown stop code');
+
+process.stdout.write('frontend.surface.audit self-test: 2 valid branches, 20 rejected mutations\n');

package/operators/frontend-surface-audit/validate.mjs

@@ -0,0 +1,127 @@
+// frontend.surface.audit's own law over one branch, on top of the shared step check: every matrix entry in
+// the verdicts has both a capture and a screenshot; every judged node was measured in that entry's
+// capture and judged on a rule it actually claimed; a Grammar-owned node never routes a failure into
+// the resolve loop and an application-owned failure always does; and the receipt reads what the
+// verdicts carry.
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { validateStep } from '../../scripts/validate-step.mjs';
+import { tableUnder } from '../../scripts/validate-response.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const empty = (v) => v === undefined || v === null || v === '' || v === '—';
+const list = (v) => (Array.isArray(v) ? v : empty(v) ? [] : [v]);
+
+export async function validateAuditStep(branchDir, root = ROOT) {
+  const base = await validateStep(root, branchDir);
+  const errors = [...base.errors];
+  const { response, requirements = {}, present = new Set() } = base;
+  if (!response || response.operatorId !== 'frontend.surface.audit') return { errors };
+  const has = (f) => existsSync(path.join(branchDir, f));
+  const read = (f) => readFile(path.join(branchDir, f), 'utf8');
+
+  let verdicts = null;
+  if (present.has('verdicts') && has('response/data/verdicts.json')) {
+    try { verdicts = JSON.parse(await read('response/data/verdicts.json')); } catch { verdicts = null; }
+  }
+  if (!verdicts) {
+    if (response.status === 'done') errors.push('response/data/verdicts.json: a done branch needs the verdicts');
+    return { errors };
+  }
+  const at = 'response/data/verdicts.json';
+
+  const captureRefs = new Set(list(response.fields?.capture));
+  const shotRefs = new Set(list(response.fields?.screenshot));
+  const narrowed = list(requirements.matrix);
+
+  const captures = new Map();
+  for (const ref of captureRefs) {
+    if (!has(ref)) continue;
+    let doc = null;
+    try { doc = JSON.parse(await read(ref)); } catch { doc = null; }
+    if (doc) captures.set(doc.matrixId, { doc, ref });
+  }
+
+  const ids = new Set();
+  for (const entry of verdicts.entries) {
+    if (ids.has(entry.matrixId)) errors.push(`${at}: matrix entry ${entry.matrixId} is judged twice`);
+    ids.add(entry.matrixId);
+    const capture = captures.get(entry.matrixId);
+    if (!capture) { errors.push(`${at}: matrix entry ${entry.matrixId} has verdicts and no capture (EVIDENCE_MISSING)`); continue; }
+    if (capture.ref !== `response/data/captures/${entry.matrixId}.json`) errors.push(`${capture.ref}: the capture of ${entry.matrixId} is not the file its id names`);
+    if (!shotRefs.has(`response/artifacts/${entry.matrixId}.png`)) errors.push(`${at}: matrix entry ${entry.matrixId} has verdicts and no screenshot (EVIDENCE_MISSING)`);
+    if (narrowed.length && !narrowed.some((m) => (typeof m === 'string' ? m : m.matrixId) === entry.matrixId)) {
+      errors.push(`${at}: matrix entry ${entry.matrixId} was judged but the request narrowed the matrix without it`);
+    }
+
+    const nodes = new Map(capture.doc.nodes.map((n) => [n.path, n]));
+    for (const result of entry.results) {
+      const node = nodes.get(result.path);
+      if (!node) { errors.push(`${at}: ${result.path} is judged under ${entry.matrixId} and was never measured there`); continue; }
+      if (node.owner !== result.owner) errors.push(`${at}: ${result.path} is ${result.owner} here and ${node.owner} in the capture`);
+      if (!node.claims.includes(result.rule)) errors.push(`${at}: ${result.path} is judged on ${result.rule}, which that node never claimed`);
+      const measured = Object.values(node.measured);
+      if (!measured.includes(result.measured)) errors.push(`${at}: ${result.path} is judged against ${result.measured}, which the capture did not measure`);
+      if (result.verdict === 'pass' && result.routeTo !== 'none') errors.push(`${at}: ${result.path} passes and still routes to ${result.routeTo}`);
+      if (result.verdict === 'fail') {
+        if (result.owner === 'grammar' && result.routeTo === 'resolve') errors.push(`${at}: ${result.path} is a Grammar component's own render; a failure there is a grammar-gap, never a resolve loop`);
+        if (result.owner === 'app' && result.routeTo !== 'resolve') errors.push(`${at}: ${result.path} is application-owned and its failure must route to resolve`);
+        if (result.routeTo === 'none') errors.push(`${at}: ${result.path} fails and routes nowhere`);
+      }
+    }
+    // Every claim a node carries is judged, or the claim is unaudited.
+    for (const node of capture.doc.nodes) {
+      for (const claim of node.claims) {
+        if (!entry.results.some((r) => r.path === node.path && r.rule === claim)) errors.push(`${at}: ${node.path} claims ${claim} under ${entry.matrixId} and no verdict judges it`);
+      }
+    }
+  }
+  for (const [matrixId] of captures) if (!ids.has(matrixId)) errors.push(`${at}: ${matrixId} was captured and never judged`);
+
+  const failing = verdicts.entries.flatMap((e) => e.results.filter((r) => r.verdict === 'fail'));
+  if (failing.some((r) => r.routeTo === 'resolve') && !(response.next ?? []).includes('frontend.presentation.resolve')) {
+    errors.push('response/response.json: a claim fails on an application-owned node, so next names frontend.presentation.resolve');
+  }
+
+  if (present.has('frontend-surface-audit') && has('response/response.md')) {
+    const text = await read('response/response.md');
+    const rel = 'response/response.md';
+    const matrixRows = tableUnder(text, '## Matrix') ?? [];
+    if (matrixRows.length !== verdicts.entries.length) errors.push(`${rel}: Matrix has ${matrixRows.length} rows, the verdicts carry ${verdicts.entries.length} entries`);
+    for (const [id, viewport, scheme, state] of matrixRows) {
+      const capture = captures.get(id);
+      if (!capture) { errors.push(`${rel}: Matrix names ${id}, which has no capture`); continue; }
+      if (`${capture.doc.viewport[0]}x${capture.doc.viewport[1]}` !== viewport) errors.push(`${rel}: ${id} is ${viewport} here and ${capture.doc.viewport.join('x')} in the capture`);
+      if (capture.doc.scheme !== scheme || capture.doc.state !== state) errors.push(`${rel}: ${id} scheme or state differs from the capture`);
+    }
+    const rows = tableUnder(text, '## Verdicts by owner') ?? [];
+    const all = verdicts.entries.flatMap((e) => e.results);
+    if (rows.length !== all.length) errors.push(`${rel}: Verdicts by owner has ${rows.length} rows, the verdicts carry ${all.length} results`);
+    for (const [matrixId, owner, node, rule, , verdict] of rows) {
+      const entry = verdicts.entries.find((e) => e.matrixId === matrixId);
+      const result = entry?.results.find((r) => r.path === node && r.rule === rule);
+      if (!result) { errors.push(`${rel}: Verdicts by owner names ${rule} on ${node} under ${matrixId}, which the verdicts do not carry`); continue; }
+      if (result.owner !== owner) errors.push(`${rel}: ${node} is ${owner} here and ${result.owner} in the verdicts`);
+      if (result.verdict !== verdict) errors.push(`${rel}: ${rule} on ${node} is ${verdict} here and ${result.verdict} in the verdicts`);
+    }
+    const regressions = tableUnder(text, '## Regressions') ?? [];
+    if (regressions.length !== failing.length) errors.push(`${rel}: Regressions has ${regressions.length} rows, the verdicts carry ${failing.length} failures`);
+    for (const [matrixId, node, rule, , routeTo] of regressions) {
+      const entry = verdicts.entries.find((e) => e.matrixId === matrixId);
+      const result = entry?.results.find((r) => r.path === node && r.rule === rule && r.verdict === 'fail');
+      if (!result) { errors.push(`${rel}: Regressions names ${rule} on ${node}, which no verdict fails`); continue; }
+      if (result.routeTo !== routeTo) errors.push(`${rel}: ${rule} on ${node} routes to ${routeTo} here and ${result.routeTo} in the verdicts`);
+    }
+  }
+  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 validateAuditStep(path.resolve(target));
+  if (errors.length) { process.stderr.write(`${errors.join('\n')}\n`); process.exitCode = 1; } else process.stdout.write('valid frontend.surface.audit branch\n');
+}

package/operators/git-publish/errors.json

@@ -0,0 +1,54 @@
+{
+  "schemaVersion": 9,
+  "note": "Stop codes only git.publish emits. Same entry shape as operators/errors.json, scope implicit. Shared codes (INVALID_INPUT, SOURCE_DRIFT, NO_PROGRESS) come from operators/errors.json; ROUTE_UNVERIFIED is defined by frontend.direction.decide and BRANCH_POLICY_VIOLATION is also emitted by workspace.bind; both belong in operators/errors.json with every emitting operator in scope.",
+  "codes": {
+    "APPROVAL_MISSING": {
+      "domain": "caller",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "No approval covers this exact boundary unit; completion proof is not approval.",
+        "vi": "Không phê duyệt nào phủ đúng đơn vị ranh giới này; bằng chứng hoàn thành không phải phê duyệt."
+      },
+      "resume": {
+        "en": "Supply an approval issued for this unit.",
+        "vi": "Cấp một phê duyệt cấp cho đúng đơn vị này."
+      }
+    },
+    "DIRTY_OUTSIDE_BOUNDARY": {
+      "domain": "source",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "Something dirty lies outside the declared write roots, so the publish would carry work this boundary does not own.",
+        "vi": "Có thứ bẩn nằm ngoài các write root đã khai, nên lần publish sẽ mang theo công việc ranh giới này không sở hữu."
+      },
+      "resume": {
+        "en": "Clean the tree, or correct the write roots.",
+        "vi": "Dọn sạch cây làm việc, hoặc sửa lại các write root."
+      }
+    },
+    "HOOK_BLOCKED": {
+      "domain": "source",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "A Git hook rejected the publication, and no bypass is representable.",
+        "vi": "Một Git hook từ chối lần publish, và không có đường vòng nào biểu diễn được."
+      },
+      "resume": {
+        "en": "Fix the boundary and bring a new head.",
+        "vi": "Sửa ranh giới và mang một head mới."
+      }
+    },
+    "NON_FAST_FORWARD": {
+      "domain": "remote",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "The remote carries commits the local ref does not, so the push is not fast-forward.",
+        "vi": "Remote mang những commit mà ref cục bộ không có, nên cú push không phải fast-forward."
+      },
+      "resume": {
+        "en": "The branch owner reconciles the divergence and a new head arrives.",
+        "vi": "Người sở hữu nhánh hoà giải phần phân kỳ và một head mới tới."
+      }
+    }
+  }
+}

package/operators/git-publish/operator.json

@@ -0,0 +1,20 @@
+{
+  "schemaVersion": 9,
+  "id": "git.publish",
+  "domain": "git",
+  "job": "Publish one approved Git boundary from the exact commit quality verified, with non-force, fast-forward-only semantics, and stop with a typed failure rather than reaching for a bypass.",
+  "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": "merge-and-push",
+      "@tools/shell": "declared-commands",
+      "@tools/ci": "read"
+    }
+  }
+}

package/operators/git-publish/operator.md

@@ -0,0 +1,180 @@
+# git.publish
+
+## Job
+
+Publish one approved Git boundary from the exact commit quality verified, with non-force,
+fast-forward-only semantics, and stop with a typed failure rather than reaching for a bypass.
+
+## It decides nothing about the change
+
+Whether the work is correct was settled by the gates that produced the `quality-verification` receipt,
+and whether it may be published was settled by the approval. This operator only performs the write, or
+reports precisely why it did not. The receipt it leaves proves that exactly this commit reached
+exactly this ref under exactly these hooks; it carries no verdict, no score, and no claim that
+anything passed.
+
+## The route is read, never rediscovered
+
+This operator does not resolve a project to a checkout. `workspace.bind` does that, and its receipt
+arrives here already bound. A publish that resolved its own path could publish from a checkout
+nobody verified, which is the failure this separation exists to prevent. A route receipt whose
+status is not `bound`, or which names another project, is `ROUTE_UNVERIFIED`.
+
+## Approval is a person, always
+
+Publishing pushes work out of the session and into a place other people pull from, so `approval` has
+no default: an outward-facing act is always something a person said yes to. Completion proof records
+the gates the boundary passed; it is evidence that the work is finished and never evidence that it
+may be published. Exactly one approval must name this boundary. An approval issued for a different
+boundary is a real approval for somebody else's work, which is exactly how unreviewed change rides
+along with reviewed change, and it is `APPROVAL_MISSING`.
+
+## The published commit is the verified commit
+
+The `quality-verification` input measured one commit. That commit, and no other, is what this
+publication pushes: a head one commit ahead of the verified one carries a change no gate ever saw.
+The receipt records the verified commit beside the published head so the two can be compared later
+without rerunning anything.
+
+## Non-force is structural, not advisory
+
+Force push, history rewrite, `reset --hard`, `clean`, `stash`, branch deletion and hook bypass are
+not fields with a default; they are absent from this operator's vocabulary, so no request, in any
+combination and under any justification, can ask for one. The reason is that each of them is most
+tempting exactly when a publish has just failed: a rejected push, a red hook and an unexpected dirty
+file each have an obvious one-command answer that destroys someone else's work or someone else's
+evidence. `reset --hard` destroys uncommitted work no receipt has recorded, `clean` destroys
+untracked files nobody has reviewed, and `stash` hides a dirty boundary instead of resolving it.
+Making the request unrepresentable removes the decision from the moment it would be made badly. The
+publication mode is always fast-forward only, and every publication records that it was not forced.
+
+## The session branch is merged, never rebased
+
+The producer did not write on the person's checked-out branch. It wrote on the session branch
+`session/<sessionId>` of the routed checkout, in a git worktree prepared from the frozen head, and
+committed its write set once. This operator merges that session branch into the target branch before
+it pushes. When the target has not moved since the session base, the merge is a fast-forward and
+nothing new is created. When the target has moved, a merge commit is allowed only under two
+conditions together: the merge produced no conflict, and the gates the verification named were re-run
+on the merge result and passed. A conflict is `NON_FAST_FORWARD`, it terminates, and a person
+resolves it; the operator never rebases, never forces, and never runs with hooks disabled.
+
+## A blocked hook is a result
+
+Hooks are enforced, always, and `pre-push` is the last gate before the remote. A failing hook
+produces `HOOK_BLOCKED` naming the hook, and the delta that clears it is a fixed boundary and a new
+head. It is never a reason to run the push again with the hook disabled, to move the change onto a
+branch whose hooks are lighter, or to commit the hook's own configuration out of the way. A
+publication that carries a failed hook result, or that lacks the `pre-push` result altogether, is
+refused.
+
+## A rejected push is a result
+
+When the remote carries commits the local ref does not, the push is not fast-forward. The operator
+returns `NON_FAST_FORWARD` naming the remote head it observed. It does not rebase onto it, amend a
+commit to make the push apply, squash the divergence away, force, or lease-force. Reconciling
+divergent history changes what other people have already pulled, so it belongs to whoever owns the
+branch, and that owner is not this operator.
+
+## The boundary is exact
+
+The boundary is the whole of what this publication owns, and the input `changes` names the paths
+inside it. Anything dirty outside it is work this boundary does not own, and a publish that carries
+it publishes somebody else's unreviewed change; that is `DIRTY_OUTSIDE_BOUNDARY`. Under a forbidden
+worktree policy every published head is on the routed mutation branch, and a head on any other
+branch is `BRANCH_POLICY_VIOLATION`. A publication that advances nothing is not a publication: the
+published head is ahead of its upstream and the ref actually moved.
+
+## The tag is asked for, or there is none
+
+`tag` defaults to null, so a publication carries a continuation tag only when a person named one,
+and that tag is annotated and points at a head this same publication pushed. A tag on a head this
+run did not push is a label somebody else's commit now wears.
+
+## Cleanup is part of the publish
+
+After the push succeeds, the session worktree and the session branch are removed together with the
+session folder, because the evidence they held has just become a published commit. A blocked session
+keeps both: the evidence of what was attempted lives there until a person has read it.
+
+## Boundary
+
+Context is read-only apart from the merge and the push. The operator writes only `response/` of its
+own branch, the target branch of the routed checkout, and the push to `@remote/git/<project>/<role>`:
+the approved head on the routed ref, and at most one annotated continuation tag pointing at a head
+this same publication pushed. It does not force push, lease-force push, or rewrite published history;
+does not run reset, clean, or stash; does not delete a branch other than the session branch it is
+cleaning up; does not bypass, skip, or disable a Git hook; does not amend, rebase, or squash a commit
+to make a rejected push succeed; does not publish a head outside the approved boundary; and does not
+publish without a verified route and an approval bound to this exact boundary.
+
+## Context
+
+| Alias | Bind | Required |
+| --- | --- | --- |
+| `@workspaces/local/routes/<project>/<role>` | the checkout, its session branch and its target branch, read at the frozen head | yes |
+| `@workspaces/<project>/<role>/husky` | `pre-commit` and `pre-push`, which always run | yes |
+| `@remote/git/<project>/<role>` | the publication target and the remote head observed at invocation time | yes |
+
+## Inputs
+
+| Kind | From | Required |
+| --- | --- | --- |
+| `workspace-route-binding` | `workspace.bind`; a publish never resolves its own checkout | yes |
+| `changes` | `backend.source.apply` or `frontend.source.apply`, the exact file set this publication carries | yes |
+| `quality-verification` | `quality.verify`, the receipt whose measured commit is the one this publication pushes | yes |
+
+## Requirements
+
+| Field | Type | Default | Ask |
+| --- | --- | --- | --- |
+| `boundary` | id | — | The one boundary being published, exactly as the approval names it |
+| `approval` | id | — | The approval record that covers this boundary; completion is not approval |
+| `tag` | `{name, message}` | null | One annotated continuation tag on the head this publication pushes, or none |
+| `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 | `resume` | `request/request.json`, @workspaces/local/routes/<project>/<role> at the frozen head, @remote/git/<project>/<role> as observed | — | `INVALID_INPUT`, `SOURCE_DRIFT`, `NO_PROGRESS` |
+| 2 | Bind the route | — | input `workspace-route-binding`: the verified checkout, its head and its routed policy, and @workspaces/local/routes/<project>/<role> | — | `ROUTE_UNVERIFIED` |
+| 3 | Bind the approval to this exact boundary | `boundary`, `approval` | `request/request.json` requirements, input `changes` as the file set, input `quality-verification` as the measured commit | — | `APPROVAL_MISSING` |
+| 4 | Verify the tree: dirty outside the boundary, branch policy | — | @workspaces/local/routes/<project>/<role>, the dirty paths, every branch, the routed policy | — | `DIRTY_OUTSIDE_BOUNDARY`, `BRANCH_POLICY_VIOLATION` |
+| 5 | Run the hooks | — | @workspaces/<project>/<role>/husky: the installed hooks, `pre-push` among them | @tools/shell | `HOOK_BLOCKED` |
+| 6 | Merge the session branch into the target branch | — | @workspaces/local/routes/<project>/<role> for the target head, the session base and the session head | @workspaces/local/routes/<project>/<role>, the target branch of that checkout, @tools/git | `NON_FAST_FORWARD` |
+| 7 | Push non-force, fast-forward only | — | @workspaces/local/routes/<project>/<role> for the approved head, @remote/git/<project>/<role> at the observed remote head, @tools/ci | @remote/git/<project>/<role>, @tools/git | `NON_FAST_FORWARD` |
+| 8 | Push the continuation tag | `tag` | @workspaces/local/routes/<project>/<role> for the head this publication pushed | @remote/git/<project>/<role>, @tools/git | — |
+| 9 | Remove the worktree and the session branch, write the receipt and emit | — | everything above | @workspaces/local/routes/<project>/<role>, `response/response.md`, `response/response.json`, @tools/git | — |
+
+Creating a remote ref and fast-forwarding one are different acts with different reviewers, so the
+published head records which of the two it performed. A resume begins again at validation, reuses
+only unchanged fingerprinted observations, and consumes the exact delta; a resume that adds no head,
+approval, hook or remote change is `NO_PROGRESS`, and a re-observed remote must arrive as a new
+remote head because the same observation cannot yield a different result.
+
+## Outputs
+
+| Kind | File | Type | Required |
+| --- | --- | --- | --- |
+| `git-publication` | `response/response.md` | md | yes |
+
+## Stops
+
+| Code | Disposition |
+| --- | --- |
+| `INVALID_INPUT` | terminate |
+| `SOURCE_DRIFT` | terminate |
+| `NO_PROGRESS` | terminate |
+| `ROUTE_UNVERIFIED` | terminate |
+| `APPROVAL_MISSING` | terminate |
+| `BRANCH_POLICY_VIOLATION` | terminate |
+| `DIRTY_OUTSIDE_BOUNDARY` | terminate |
+| `HOOK_BLOCKED` | terminate |
+| `NON_FAST_FORWARD` | terminate |
+
+## Next
+
+| When | Operator |
+| --- | --- |
+| the boundary is published and the head must reach an environment | `release.deploy` |