@starci/skills 1.1.0

package/operators/git-publish/operator.vi.md

@@ -0,0 +1,178 @@
+# git.publish
+
+## Việc
+
+Publish một ranh giới Git đã được duyệt từ đúng commit mà quality đã kiểm định, theo ngữ nghĩa
+non-force và chỉ fast-forward, và dừng bằng một lỗi có kiểu thay vì với tay sang một đường tắt.
+
+## Nó không quyết gì về bản thân thay đổi
+
+Việc thay đổi có đúng hay không đã được quyết bởi các cổng sinh ra biên bản `quality-verification`,
+còn việc nó có được publish hay không đã được quyết bởi phê duyệt. Operator này chỉ thực hiện thao
+tác ghi, hoặc báo chính xác vì sao nó đã không ghi. Biên bản nó để lại chứng minh rằng đúng commit
+này đã tới đúng ref này dưới đúng những hook này; nó không mang phán quyết, không mang điểm, và
+không mang khẳng định nào rằng có thứ gì đã pass.
+
+## Route được đọc, không bao giờ được tự tìm lại
+
+Operator này không tự phân giải một project ra thành một checkout. `workspace.bind` làm việc đó, và
+biên bản của nó tới đây đã ràng sẵn. Một lần publish tự phân giải đường dẫn của mình có thể publish
+từ một checkout không ai kiểm, đúng cái hỏng mà sự tách bạch này sinh ra để chặn. Một biên bản route
+có trạng thái khác `bound`, hoặc gọi tên một project khác, là `ROUTE_UNVERIFIED`.
+
+## Phê duyệt luôn là một con người
+
+Publish đẩy công việc ra khỏi phiên và vào một nơi người khác pull về, nên `approval` không có mặc
+định: một hành động hướng ra ngoài luôn là thứ có người nói đồng ý. Bằng chứng hoàn thành ghi lại
+những cổng mà ranh giới đã qua; nó là bằng chứng công việc đã xong chứ không bao giờ là bằng chứng nó
+được phép publish. Đúng một phê duyệt phải gọi tên ranh giới này. Một phê duyệt cấp cho ranh giới khác
+là một phê duyệt thật của người khác, và đó chính là cách thay đổi chưa duyệt đi ké theo thay đổi đã
+duyệt; đó là `APPROVAL_MISSING`.
+
+## Commit được publish là commit đã kiểm định
+
+Đầu vào `quality-verification` đã đo đúng một commit. Chính commit đó, và không commit nào khác, là
+thứ lần publish này đẩy đi: một head nhỉnh hơn commit đã kiểm định một nhịp mang theo một thay đổi
+không cổng nào từng thấy. Biên bản ghi commit đã kiểm định cạnh head đã publish để sau này so được
+hai thứ mà không phải chạy lại gì.
+
+## Không force là chuyện cấu trúc, không phải lời khuyên
+
+Force push, viết lại lịch sử, `reset --hard`, `clean`, `stash`, xóa nhánh và bỏ qua hook không phải
+là những field có mặc định; chúng vắng mặt khỏi từ vựng của operator này, nên không request nào, ở
+bất kỳ tổ hợp và biện minh nào, xin được một cái. Lý do là mỗi thứ trong số đó cám dỗ nhất đúng vào
+lúc một lần publish vừa hỏng: một push bị từ chối, một hook đỏ và một file bẩn bất ngờ đều có một câu
+trả lời một lệnh rất hiển nhiên, và nó phá công việc hoặc bằng chứng của người khác. `reset --hard`
+phá công việc chưa commit mà không biên bản nào ghi, `clean` phá file chưa track chưa ai xem, còn
+`stash` giấu một ranh giới bẩn thay vì giải quyết nó. Làm cho lời xin không diễn đạt được là gỡ quyết
+định ra khỏi đúng khoảnh khắc nó sẽ bị quyết sai. Chế độ publish luôn là chỉ fast-forward, và mọi lần
+publish đều ghi rằng nó đã không bị force.
+
+## Nhánh phiên được merge, không bao giờ bị rebase
+
+Người sản xuất đã không viết trên nhánh mà người ta đang checkout. Nó viết trên nhánh phiên
+`session/<sessionId>` của checkout đã route, trong một git worktree dựng từ head đã đóng băng, và
+commit tập ghi của mình đúng một lần. Operator này merge nhánh phiên ấy vào nhánh đích trước khi
+push. Khi nhánh đích chưa dịch chuyển kể từ base của phiên, merge là fast-forward và không có gì mới
+sinh ra. Khi nhánh đích đã dịch chuyển, một merge commit chỉ được phép dưới hai điều kiện đồng thời:
+merge không sinh xung đột, và những cổng mà bản kiểm định đã nêu được chạy lại trên kết quả merge và
+đều pass. Xung đột là `NON_FAST_FORWARD`, nó terminate, và một con người giải quyết; operator không
+bao giờ rebase, không bao giờ force, và không bao giờ chạy với hook bị tắt.
+
+## Hook chặn là một kết quả
+
+Hook luôn được thi hành, và `pre-push` là cổng cuối trước remote. Một hook hỏng sinh ra `HOOK_BLOCKED`
+gọi tên hook đó, và phần delta gỡ được nó là một ranh giới đã sửa cùng một head mới. Nó không bao giờ
+là lý do để chạy lại push với hook bị tắt, để dời thay đổi sang một nhánh có hook nhẹ hơn, hay để
+commit chính cấu hình hook ra khỏi đường. Một lần publish mang theo kết quả hook hỏng, hoặc thiếu hẳn
+kết quả `pre-push`, đều bị từ chối.
+
+## Push bị từ chối là một kết quả
+
+Khi remote mang những commit mà ref cục bộ không có, push không phải fast-forward. Operator trả về
+`NON_FAST_FORWARD` gọi tên remote head nó quan sát được. Nó không rebase lên đó, không amend một
+commit cho push áp được, không squash phần phân kỳ đi, không force, không lease-force. Hòa giải lịch
+sử phân kỳ là đổi thứ người khác đã pull về, nên nó thuộc về người sở hữu nhánh, và người đó không
+phải operator này.
+
+## Ranh giới là chính xác
+
+Ranh giới là toàn bộ những gì lần publish này sở hữu, và Đầu vào `changes` nêu các path nằm trong đó.
+Bất cứ thứ gì bẩn ở ngoài nó là công việc ranh giới này không sở hữu, và một lần publish mang nó theo
+là publish thay đổi chưa duyệt của người khác; đó là `DIRTY_OUTSIDE_BOUNDARY`. Dưới chính sách cấm
+nhánh worktree, head được publish nằm trên nhánh mutation đã route, và một head trên nhánh khác là
+`BRANCH_POLICY_VIOLATION`. Một lần publish không đẩy được gì lên không phải là publish: head đã publish
+đi trước upstream của nó và ref thực sự đã dịch chuyển.
+
+## Tag là thứ được hỏi, hoặc không có
+
+`tag` mặc định null, nên một lần publish chỉ mang tag tiếp nối khi có người nêu tên nó, và tag ấy là
+annotated và trỏ vào một head mà chính lần publish này đã đẩy. Một tag trên head mà lần chạy này
+không đẩy là một cái nhãn mà commit của người khác đang phải mang.
+
+## Dọn dẹp là một phần của publish
+
+Sau khi push thành công, worktree phiên và nhánh phiên được xóa cùng thư mục phiên, vì bằng chứng
+chúng giữ vừa trở thành một commit đã publish. Một phiên bị chặn giữ lại cả hai: bằng chứng về việc
+đã thử làm gì nằm ở đó cho tới khi có người đọc.
+
+## Ranh giới ghi
+
+Context chỉ đọc, trừ merge và push. Operator chỉ ghi vào `response/` của nhánh mình, nhánh đích của
+checkout đã route, và cú push tới `@remote/git/<project>/<role>`: head đã duyệt trên ref đã route, và
+tối đa một tag tiếp nối annotated trỏ vào một head mà chính lần publish này đã đẩy. Nó không force
+push, không lease-force push, không viết lại lịch sử đã publish; không chạy reset, clean hay stash;
+không xóa nhánh nào ngoài nhánh phiên nó đang dọn; không bỏ qua, bỏ sót hay tắt một Git hook; không
+amend, rebase hay squash một commit để một push bị từ chối đi lọt; không publish một head ngoài ranh
+giới đã duyệt; và không publish khi chưa có route đã kiểm và một phê duyệt ràng vào đúng ranh giới này.
+
+## Context
+
+| Alias | Bind | Bắt buộc |
+| --- | --- | --- |
+| `@workspaces/local/routes/<project>/<role>` | checkout, nhánh phiên và nhánh đích của nó, đọc tại head đã đóng băng | có |
+| `@workspaces/<project>/<role>/husky` | `pre-commit` và `pre-push`, luôn chạy | có |
+| `@remote/git/<project>/<role>` | đích publish và remote head quan sát được lúc gọi | có |
+
+## Đầu vào
+
+| Kind | Từ đâu | Bắt buộc |
+| --- | --- | --- |
+| `workspace-route-binding` | `workspace.bind`; một lần publish không bao giờ tự phân giải checkout của mình | có |
+| `changes` | `backend.source.apply` hoặc `frontend.source.apply`, đúng tập file mà lần publish này mang | có |
+| `quality-verification` | `quality.verify`, biên bản có commit đã đo chính là commit lần publish này đẩy | có |
+
+## Yêu cầu
+
+| Field | Kiểu | Mặc định | Hỏi |
+| --- | --- | --- | --- |
+| `boundary` | id | — | Đúng một ranh giới được publish, đúng như phê duyệt gọi tên nó |
+| `approval` | id | — | Bản ghi phê duyệt phủ lên ranh giới này; hoàn thành không phải phê duyệt |
+| `tag` | `{name, message}` | null | Một tag tiếp nối annotated trên head mà lần publish này đẩy, hoặc không có |
+| `resume` | token | null | Token của nhánh bị chặn khi vào lại sau một mã dừng |
+
+## Các bước
+
+| # | Bước | Tham số | Đọc | Ghi | Dừng với |
+| --- | --- | --- | --- | --- | --- |
+| 1 | Kiểm cổng vào và resume | `resume` | `request/request.json`, @workspaces/local/routes/<project>/<role> tại head đã đóng băng, @remote/git/<project>/<role> như quan sát được | — | `INVALID_INPUT`, `SOURCE_DRIFT`, `NO_PROGRESS` |
+| 2 | Ràng route | — | Đầu vào `workspace-route-binding`: checkout đã kiểm, head và chính sách đã route của nó, cùng @workspaces/local/routes/<project>/<role> | — | `ROUTE_UNVERIFIED` |
+| 3 | Ràng phê duyệt vào đúng ranh giới này | `boundary`, `approval` | phần requirements của `request/request.json`, Đầu vào `changes` là tập file, Đầu vào `quality-verification` là commit đã đo | — | `APPROVAL_MISSING` |
+| 4 | Kiểm cây: bẩn ngoài ranh giới, chính sách nhánh | — | @workspaces/local/routes/<project>/<role>, các path bẩn, mọi nhánh, chính sách đã route | — | `DIRTY_OUTSIDE_BOUNDARY`, `BRANCH_POLICY_VIOLATION` |
+| 5 | Chạy hook | — | @workspaces/<project>/<role>/husky: các hook đã cài, trong đó có `pre-push` | @tools/shell | `HOOK_BLOCKED` |
+| 6 | Merge nhánh phiên vào nhánh đích | — | @workspaces/local/routes/<project>/<role> cho head đích, base phiên và head phiên | @workspaces/local/routes/<project>/<role>, nhánh đích của checkout đó, @tools/git | `NON_FAST_FORWARD` |
+| 7 | Push non-force, chỉ fast-forward | — | @workspaces/local/routes/<project>/<role> cho head đã duyệt, @remote/git/<project>/<role> tại remote head quan sát được, @tools/ci | @remote/git/<project>/<role>, @tools/git | `NON_FAST_FORWARD` |
+| 8 | Push tag tiếp nối | `tag` | @workspaces/local/routes/<project>/<role> cho head mà lần publish này đã đẩy | @remote/git/<project>/<role>, @tools/git | — |
+| 9 | Xóa worktree và nhánh phiên, viết biên bản và phát | — | mọi thứ ở trên | @workspaces/local/routes/<project>/<role>, `response/response.md`, `response/response.json`, @tools/git | — |
+
+Tạo một remote ref và fast-forward một remote ref là hai hành động khác nhau với hai người duyệt khác
+nhau, nên head đã publish ghi lại nó đã làm cái nào. Một lần resume bắt đầu lại từ cổng vào, chỉ dùng
+lại quan sát có fingerprint không đổi, và tiêu thụ đúng phần delta; một lần resume không thêm head,
+phê duyệt, hook hay thay đổi remote nào là `NO_PROGRESS`, và một remote đã quan sát lại phải tới dưới
+dạng một remote head mới vì cùng một quan sát không thể cho một kết quả khác.
+
+## Đầu ra
+
+| Kind | File | Kiểu | Bắt buộc |
+| --- | --- | --- | --- |
+| `git-publication` | `response/response.md` | md | có |
+
+## Dừng
+
+| Code | Xử lý |
+| --- | --- |
+| `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 |
+
+## Kế tiếp
+
+| Khi | Operator |
+| --- | --- |
+| ranh giới đã publish và head phải tới được một môi trường | `release.deploy` |

package/operators/git-publish/self-test.mjs

@@ -0,0 +1,177 @@
+// Proves validate.mjs on a synthetic session branch: one fast-forward publication, one merge-commit
+// publication, one that carries the continuation tag it was asked for, one blocked on a rejected
+// push, 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 { validateGitPublishStep } from './validate.mjs';
+
+const HEAD = '1'.repeat(40);
+const REMOTE = '2'.repeat(40);
+const OTHER = '3'.repeat(40);
+const BOUNDARY = 'api.core';
+const APPROVAL = '@worktrees/businesses/features/api-core/model.json#approval';
+const SESSION = 'session/s-test';
+const TAG = { name: 'v1.4.0', message: 'continuation' };
+
+function responseMd({
+  boundary = BOUNDARY, approval = APPROVAL, mode = 'fast-forward-only', forced = 'no', merge = 'fast-forward',
+  verified = HEAD, heads = [['`@workspaces/be`', '`mtp`', HEAD, REMOTE, '4']], hooks = [['`pre-push`', '`.husky/pre-push`', 'passed']],
+  tag = null, cleanup = 'worktree and session branch removed',
+  findings = [['HOOK_ENFORCED', '`pre-push`', 'the hook ran and was not bypassed'], ['REMOTE_FAST_FORWARDED', '`@workspaces/be`', 'the ref advanced from the remote head it carried']],
+} = {}) {
+  return `# git-publication — ${boundary}
+
+The boundary was published from the commit quality verified onto the routed ref, under enforced
+hooks, without force.
+
+## Binding
+
+| Field | Value |
+| --- | --- |
+| Operator | \`git.publish\` |
+| Step | \`step-1/parallel-1\` |
+| Project | \`starci-academy\` |
+| Boundary | ${boundary} |
+| Approval | ${approval} |
+| Route receipt | \`step-1/parallel-1/response/response.md\` |
+| Worktree branches | forbidden |
+| Mutation branch | \`mtp\` |
+| Frozen head | \`${HEAD}\` |
+
+## Publication
+
+| Field | Value |
+| --- | --- |
+| Remote | origin |
+| Ref | \`refs/heads/mtp\` |
+| Mode | ${mode} |
+| Forced | ${forced} |
+| Session branch | \`${SESSION}\` |
+| Target branch | \`mtp\` |
+| Merge | ${merge} |
+| Verified commit | \`${verified}\` |
+| Cleanup | ${cleanup} |
+
+## Published heads
+
+| Checkout | Branch | Head | Previous remote head | Commits |
+| --- | --- | --- | --- | --- |
+${heads.map((h) => `| ${h[0]} | ${h[1]} | \`${h[2]}\` | \`${h[3]}\` | ${h[4]} |`).join('\n')}
+
+## Hooks
+
+| Hook | Reference | Outcome |
+| --- | --- | --- |
+${hooks.map((h) => `| ${h[0]} | ${h[1]} | ${h[2]} |`).join('\n')}
+
+## Continuation tag
+
+| Field | Value |
+| --- | --- |
+| Tag | ${tag ? `\`${tag.name}\`` : '—'} |
+| Ref | ${tag ? `\`refs/tags/${tag.name}\`` : '—'} |
+| Head | ${tag ? `\`${tag.head}\`` : '—'} |
+
+## Findings
+
+| Code | Subject | Statement |
+| --- | --- | --- |
+${findings.map(([code, subject, statement]) => `| \`${code}\` | ${subject} | ${statement} |`).join('\n')}
+`;
+}
+
+const requestJson = ({ boundary = BOUNDARY, approval = APPROVAL, tag = null, inputs = {
+  'workspace-route-binding': 'step-1/parallel-1/response/response.md',
+  changes: 'step-1/parallel-1/response/changes.md',
+  'quality-verification': 'step-1/parallel-1/response/quality.md',
+}, extra = {} } = {}) => ({
+  schemaVersion: 9, operatorId: 'git.publish', step: 1, parallel: 1, sessionId: 's-test',
+  contexts: [{ alias: '@workspaces/local/routes/starci-academy/be', head: HEAD }],
+  requirements: { boundary, approval, tag, resume: null, ...extra },
+  inputs, resume: null,
+});
+
+const responseJson = ({ status = 'done', stop, commits = [HEAD], next = ['release.deploy'] } = {}) => ({
+  schemaVersion: 9, operatorId: 'git.publish', step: 1, parallel: 1, status, ...(stop ? { stop } : {}),
+  fallbacks: [], fields: status === 'blocked' ? {} : { 'git-publication': 'response/response.md' }, commits, next,
+});
+
+function writeBranch(files) {
+  const session = mkdtempSync(path.join(tmpdir(), 'publish-session-'));
+  const branch = path.join(session, 'step-1', 'parallel-1');
+  for (const d of ['request', 'response/data', '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': 'git.publish' }, current: '1/1', status: 'running' }));
+  for (const name of ['response.md', 'changes.md', 'quality.md']) writeFileSync(path.join(branch, 'response', name), '# placeholder\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(),
+  ...over,
+});
+
+async function expectValid(files, label) {
+  const { branch, session } = writeBranch(files);
+  const { errors } = await validateGitPublishStep(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 validateGitPublishStep(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 fast-forward publication of the verified commit');
+await expectValid(baseline({ 'response/response.md': responseMd({ merge: 'merge-commit' }) }), 'a merge commit onto a target that moved');
+await expectValid(baseline({
+  'request/request.json': requestJson({ tag: TAG }),
+  'response/response.md': responseMd({
+    tag: { ...TAG, head: HEAD },
+    findings: [['HOOK_ENFORCED', '`pre-push`', 'the hook ran'], ['CONTINUATION_TAG_PUBLISHED', '`v1.4.0`', 'the tag points at the head this run pushed']],
+  }),
+}), 'a continuation tag the person asked for');
+await expectValid({
+  'request/request.json': requestJson(),
+  'response/response.json': responseJson({ status: 'blocked', stop: 'NON_FAST_FORWARD', commits: [], next: [] }),
+  'response/response.md': null,
+}, 'blocked because the remote had moved');
+
+await expectError(baseline({ 'response/response.json': { ...responseJson(), stop: 'HOOK_BLOCKED' } }), 'only a blocked response carries a stop', 'done with a stop');
+await expectError(baseline({ 'response/response.json': responseJson({ status: 'blocked', stop: 'PUSH_REJECTED', commits: [], next: [] }) }), 'not a registered code', 'unknown stop code');
+await expectError(baseline({ 'request/request.json': requestJson({ extra: { force: true } }) }), 'requirements.force is not a field', 'force asked for in the request');
+await expectError(baseline({ 'request/request.json': requestJson({ extra: { writeRoots: ['src'] } }) }), 'requirements.writeRoots is not a field', 'a field the operator no longer declares');
+await expectError(baseline({ 'request/request.json': requestJson({ approval: null }) }), 'required field approval has no value', 'a publish with nobody approving it');
+await expectError(baseline({ 'response/response.md': responseMd({ boundary: 'other.boundary' }) }), 'but the request bound', 'a receipt for another boundary');
+await expectError(baseline({ 'response/response.md': responseMd({ approval: '`someone-elses-approval`' }) }), 'names an approval the request did not bind', 'an approval borrowed from another boundary');
+await expectError(baseline({ 'response/response.md': responseMd({ mode: 'force' }) }), 'the publication mode is always fast-forward only', 'a forced publication mode');
+await expectError(baseline({ 'response/response.md': responseMd({ forced: 'yes' }) }), 'a forced push rewrites', 'a push that was forced');
+await expectError(baseline({ 'response/response.md': responseMd({ merge: 'rebase' }) }), 'merged, never rebased', 'a session branch rebased onto the target');
+await expectError(baseline({ 'response/response.md': responseMd({ verified: OTHER }) }), 'but quality verified', 'a head past the commit the gates measured');
+await expectError(baseline({ 'response/response.md': responseMd({ verified: 'not-a-sha' }) }), 'Verified commit is not a commit sha', 'a receipt that never says what was verified');
+await expectError(baseline({ 'response/response.md': responseMd({ heads: [['`@workspaces/be`', '`mtp`', HEAD, HEAD, '4']] }) }), 'equals the remote head it claims to advance', 'a publication that advanced nothing');
+await expectError(baseline({ 'response/response.md': responseMd({ hooks: [['`pre-commit`', '`.husky/pre-commit`', 'passed']] }) }), 'lacks the pre-push result', 'a publish with no pre-push result');
+await expectError(baseline({ 'response/response.md': responseMd({ hooks: [['`pre-push`', '`.husky/pre-push`', 'failed']] }) }), 'is HOOK_BLOCKED, not a receipt', 'a receipt over a failed hook');
+await expectError(baseline({ 'response/response.md': responseMd({ findings: [['BOUNDARY_CLEAN', '`api.core`', 'nothing dirty lay outside the boundary']] }) }), 'records no HOOK_ENFORCED finding', 'hooks run but never recorded');
+await expectError(baseline({ 'request/request.json': requestJson({ tag: TAG }) }), 'asked for a continuation tag and the receipt records none', 'a tag asked for and never pushed');
+await expectError(baseline({ 'response/response.md': responseMd({ tag: { ...TAG, head: HEAD }, findings: [['HOOK_ENFORCED', '`pre-push`', 'ran'], ['CONTINUATION_TAG_PUBLISHED', '`v1.4.0`', 'pushed']] }) }), 'without the request asking for one', 'a tag nobody asked for');
+await expectError(baseline({
+  'request/request.json': requestJson({ tag: TAG }),
+  'response/response.md': responseMd({ tag: { ...TAG, head: OTHER }, findings: [['HOOK_ENFORCED', '`pre-push`', 'ran'], ['CONTINUATION_TAG_PUBLISHED', '`v1.4.0`', 'pushed']] }),
+}), 'which this publication did not push', 'a tag on somebody else\'s commit');
+await expectError(baseline({ 'response/response.md': responseMd({ cleanup: 'worktree kept for inspection' }) }), 'removes the worktree and the session branch', 'a published branch that never cleaned up');
+await expectError(baseline({ 'response/response.json': responseJson({ commits: [] }) }), 'commits does not register the published head', 'a receipt whose commit the response hides');
+await expectError(baseline({ 'response/response.json': responseJson({ commits: [HEAD, OTHER] }) }), 'which the receipt did not publish', 'a commit the receipt never published');
+await expectError(baseline({ 'request/request.json': requestJson({ inputs: { 'workspace-route-binding': 'step-1/parallel-1/response/response.md', changes: 'step-1/parallel-1/response/changes.md' } }) }), 'required input quality-verification is absent', 'a publish with nothing verified');
+await expectError(baseline({ 'response/response.md': responseMd().replace('## Hooks', '## Checks') }), 'missing section ^## Hooks$', 'receipt section renamed');
+
+process.stdout.write('git.publish self-test: 4 valid branches, 22 rejected mutations\n');

package/operators/git-publish/validate.mjs

@@ -0,0 +1,106 @@
+// git.publish's own law over one branch, on top of the shared step check: the receipt names the
+// boundary and the approval the request bound; the published head is the commit the
+// quality-verification input measured; the mode is fast-forward only and nothing was forced; the
+// session branch was merged, never rebased, and a merge commit exists only when the target moved;
+// every hook ran and passed, `pre-push` among them; the head actually advanced; a continuation tag
+// exists exactly when the request asked for one and points at the head this run pushed; and the
+// worktree and the session branch were cleaned up on a done branch.
+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 SHA = /^[0-9a-f]{40}$/;
+const empty = (v) => v === undefined || v === null || v === '' || v === '—';
+const rows = (text, heading) => tableUnder(text, heading) ?? [];
+const fields = (text, heading) => Object.fromEntries(rows(text, heading).map(([k, v]) => [k, v]));
+
+export async function validateGitPublishStep(branchDir, root = ROOT, { verifiedCommit = null } = {}) {
+  const base = await validateStep(root, branchDir);
+  const errors = [...base.errors];
+  const { response, request, requirements = {}, present = new Set() } = base;
+  if (!response || response.operatorId !== 'git.publish') return { errors };
+  const read = (f) => readFile(path.join(branchDir, f), 'utf8');
+
+  // Nothing destructive can be asked for, because no field can carry it.
+  for (const forbidden of ['force', 'forceWithLease', 'noVerify', 'rebase', 'amend', 'reset', 'clean', 'stash', 'deleteBranch']) {
+    if (requirements[forbidden] !== undefined) errors.push(`request.json: ${forbidden} is not a field git.publish declares; a destructive act must stay unrepresentable`);
+  }
+  if (empty(requirements.approval)) errors.push('request.json: approval has no default; publishing outward is always something a person said yes to');
+  const wantsTag = !empty(requirements.tag);
+
+  if (!(present.has('git-publication') && existsSync(path.join(branchDir, 'response/response.md')))) {
+    if (response.status === 'done') errors.push('response/response.md: a done branch needs the publication receipt');
+    return { errors };
+  }
+  const text = await read('response/response.md');
+  const binding = fields(text, '## Binding');
+  const publication = fields(text, '## Publication');
+  const heads = rows(text, '## Published heads');
+  const hooks = rows(text, '## Hooks');
+  const tag = fields(text, '## Continuation tag');
+  const findings = new Set(rows(text, '## Findings').map(([code]) => code));
+
+  if (!empty(requirements.boundary) && binding.Boundary !== requirements.boundary) errors.push(`response/response.md: Binding publishes ${binding.Boundary} but the request bound ${requirements.boundary}`);
+  if (!empty(requirements.approval) && binding.Approval !== requirements.approval) errors.push('response/response.md: Binding names an approval the request did not bind; an approval for another boundary is somebody else\'s');
+
+  if (publication.Mode !== 'fast-forward-only') errors.push(`response/response.md: Mode is ${publication.Mode}; the publication mode is always fast-forward only`);
+  if (publication.Forced !== 'no') errors.push('response/response.md: Forced is not no; a forced push rewrites what other people have already pulled');
+  if (!/^session\//.test(publication['Session branch'] ?? '')) errors.push('response/response.md: the producer wrote on a session branch, and the receipt must name it');
+  if (!['fast-forward', 'merge-commit'].includes(publication.Merge)) errors.push(`response/response.md: Merge is ${publication.Merge}; the session branch is merged, never rebased or squashed`);
+
+  // The published head is the commit quality measured, not one commit further on.
+  const verified = verifiedCommit ?? (publication['Verified commit'] ?? '');
+  if (!SHA.test(verified)) errors.push('response/response.md: Verified commit is not a commit sha; the receipt must say which commit the gates measured');
+  if (heads.length === 0) errors.push('response/response.md: Published heads is empty; a publication that advances nothing is not a publication');
+  for (const [checkout, branch, head, previous, commits] of heads) {
+    const at = `response/response.md: published head ${checkout}`;
+    if (SHA.test(verified) && head !== verified) errors.push(`${at} is ${head} but quality verified ${verified}; a head past the verified commit carries change no gate saw`);
+    if (head === previous) errors.push(`${at} equals the remote head it claims to advance`);
+    if (!/^[1-9][0-9]*$/.test(commits)) errors.push(`${at} publishes ${commits} commits`);
+    if (publication.Merge === 'fast-forward' && previous !== '—' && !SHA.test(previous)) errors.push(`${at} fast-forwarded from a previous head that is not a sha`);
+    if (branch === '—') errors.push(`${at} names no branch`);
+  }
+
+  // Hooks are enforced, always, and pre-push is the last gate before the remote.
+  const hookNames = hooks.map(([hook]) => hook);
+  if (!hookNames.includes('pre-push')) errors.push('response/response.md: Hooks lacks the pre-push result; the last gate before the remote cannot be missing');
+  for (const [hook, , outcome] of hooks) if (outcome !== 'passed') errors.push(`response/response.md: hook ${hook} is ${outcome}; a publication carrying a failed hook is HOOK_BLOCKED, not a receipt`);
+  if (hooks.length && !findings.has('HOOK_ENFORCED')) errors.push('response/response.md: the hooks ran but the receipt records no HOOK_ENFORCED finding');
+
+  // A tag exists exactly when the person asked for one, and it points at a head this run pushed.
+  const pushedHeads = new Set(heads.map(([, , head]) => head));
+  if (wantsTag) {
+    if (tag.Tag === '—') errors.push('response/response.md: the request asked for a continuation tag and the receipt records none');
+    else {
+      const name = (requirements.tag?.name ?? '').toString();
+      if (name && tag.Tag !== name) errors.push(`response/response.md: the tag is ${tag.Tag} but the request named ${name}`);
+      if (!/^refs\/tags\//.test(tag.Ref ?? '')) errors.push('response/response.md: a continuation tag is annotated and lives under refs/tags/');
+      if (!pushedHeads.has(tag.Head)) errors.push(`response/response.md: the tag points at ${tag.Head}, which this publication did not push`);
+      if (!findings.has('CONTINUATION_TAG_PUBLISHED')) errors.push('response/response.md: a published tag must record CONTINUATION_TAG_PUBLISHED');
+    }
+  } else if (tag.Tag !== '—') errors.push('response/response.md: a continuation tag was published without the request asking for one');
+
+  // Cleanup is part of the publish, and only on a done branch.
+  if (response.status === 'done' && !/removed/i.test(publication.Cleanup ?? '')) errors.push('response/response.md: a published branch removes the worktree and the session branch');
+
+  // The commit the response registers is the commit the receipt published.
+  const commits = new Set(response.commits ?? []);
+  for (const head of pushedHeads) if (!commits.has(head)) errors.push(`response/response.json: commits does not register the published head ${head}`);
+  for (const c of commits) if (!pushedHeads.has(c)) errors.push(`response/response.json: commits carries ${c}, which the receipt did not publish`);
+
+  // The verified commit comes from the quality receipt, so the input must be there to compare against.
+  if (response.status === 'done' && !(request?.inputs ?? {})['quality-verification']) errors.push('request.json: a publish needs the quality-verification input whose commit it pushes');
+  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 validateGitPublishStep(path.resolve(target));
+  if (errors.length) { process.stderr.write(`${errors.join('\n')}\n`); process.exitCode = 1; } else process.stdout.write('valid git.publish branch\n');
+}

package/operators/platform-operate/errors.json

@@ -0,0 +1,90 @@
+{
+  "schemaVersion": 9,
+  "note": "Stop codes only platform.operate emits. Same entry shape as operators/errors.json, scope implicit. Shared codes (INVALID_INPUT, SOURCE_DRIFT, NO_PROGRESS) come from operators/errors.json.",
+  "codes": {
+    "AUTHORITY_DRIFT": {
+      "domain": "caller",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "The approval, the plan hash, or the allowed effect set no longer matches the requested delta.",
+        "vi": "Phê duyệt, hash kế hoạch hay tập effect được phép không còn khớp phần delta được yêu cầu."
+      },
+      "resume": {
+        "en": "Bring a fresh approval for this exact plan.",
+        "vi": "Mang một phê duyệt mới cho đúng kế hoạch này."
+      }
+    },
+    "CAPABILITY_MISSING": {
+      "domain": "caller",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "The capability the service kind requires is absent or names no custody evidence.",
+        "vi": "Capability mà service kind đòi hỏi đang thiếu, hoặc không nêu bằng chứng custody nào."
+      },
+      "resume": {
+        "en": "Supply the missing capability handle with its custody.",
+        "vi": "Cấp handle capability còn thiếu cùng custody của nó."
+      }
+    },
+    "INVENTORY_DRIFT": {
+      "domain": "platform",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "A declared resource moved since the inventory was bound, so the plan describes a service that no longer exists.",
+        "vi": "Một tài nguyên đã khai đã đổi kể từ khi inventory được ràng, nên kế hoạch mô tả một dịch vụ không còn tồn tại."
+      },
+      "resume": {
+        "en": "Re-observe the inventory; it must arrive with a new fingerprint.",
+        "vi": "Quan sát lại inventory; nó phải tới với một fingerprint mới."
+      }
+    },
+    "PORT_CONFLICT": {
+      "domain": "product",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "A claimed port is already held by another declared process, and holding it is not permission to reclaim it.",
+        "vi": "Một cổng được claim đang bị một tiến trình đã khai khác giữ, và việc nó bị giữ không phải giấy phép giành lại."
+      },
+      "resume": {
+        "en": "Agree a port, or the holder's owner releases it.",
+        "vi": "Thoả thuận một cổng khác, hoặc chủ của kẻ đang giữ nhả nó ra."
+      }
+    },
+    "EFFECT_UNAUTHORIZED": {
+      "domain": "caller",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "A required effect lies outside the approved effect set or outside the branch.",
+        "vi": "Một effect cần thiết nằm ngoài tập effect đã duyệt hoặc ngoài nhánh."
+      },
+      "resume": {
+        "en": "Approve the effect, or bring a narrower plan.",
+        "vi": "Duyệt effect đó, hoặc mang một kế hoạch hẹp hơn."
+      }
+    },
+    "SERVICE_UNAVAILABLE": {
+      "domain": "provider",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "The shared service or its provider cannot be reached.",
+        "vi": "Dịch vụ dùng chung hoặc provider của nó không tới được."
+      },
+      "resume": {
+        "en": "Restore the provider.",
+        "vi": "Khôi phục provider."
+      }
+    },
+    "PROOF_FAILED": {
+      "domain": "platform",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "A required check is missing, unreadable, or failed after apply, and an unproved operation is not an operated one.",
+        "vi": "Một phép kiểm bắt buộc thiếu, không đọc được, hoặc hỏng sau khi áp, và một lần vận hành chưa chứng minh được thì chưa phải đã vận hành."
+      },
+      "resume": {
+        "en": "Repair the service, then invoke again.",
+        "vi": "Sửa dịch vụ, rồi gọi lại."
+      }
+    }
+  }
+}

package/operators/platform-operate/operator.json

@@ -0,0 +1,22 @@
+{
+  "schemaVersion": 9,
+  "id": "platform.operate",
+  "domain": "platform",
+  "job": "Operate one bounded shared observability, Sonar, or tunnel service from exact evidence: inventory it, converge only the approved delta, prove every check the bound knowledge requires, and stop at the smallest owning gap instead of taking product deployment ownership.",
+  "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/secrets": "resolve-by-name"
+    }
+  }
+}