@starci/skills 1.1.0

package/operators/architecture-decide/operator.md

@@ -0,0 +1,133 @@
+# architecture.decide
+
+## Job
+
+Decide one architecture with its tech stack, system boundaries, and data ownership, and prove it
+against the observed current state, the rejected alternatives, verified compatibility, and an
+independent critique.
+
+## Observe before proposing
+
+Nothing is proposed before the current state has been observed at the frozen head of
+`@workspaces/be` and written to `response/data/current-state.json` with its own fingerprint. A
+proposal written before the observation describes a system simpler than the real one, and every
+later comparison inherits that simplification. An observation taken at another head is worse: it
+looks rigorous while describing code that no longer exists.
+
+## Incumbency is not authority
+
+The inventory says what the system runs today; that is the most useful and the most dangerous
+context this operator receives. An existing framework, datastore, broker, or deployment shape enters
+the decision in exactly two roles: as a measurable constraint the target must satisfy, or as observed
+evidence about behaviour already proved. It never enters as a reason by itself. A component
+justified because it is already there is rejected outright.
+
+## Prove, do not assume
+
+An alternative is counted only when it is materially different, different in ownership or
+mechanism, not in wording, and assessed on exactly the trade-off axes the person named. Every
+retained component carries a verified verdict with evidence across runtime version, deployable
+unit, communication failure, datastore ownership, and backup and restore; a verdict that skipped an
+axis is a partial check wearing a complete label. Every boundary answers the data question: it owns
+at least one store or states that it owns none; a store names one owning boundary that writes it,
+and a second writer exists only with an explicit shared-write justification.
+
+## The critique is a nested exchange
+
+After the selected alternative is deepened, the branch pauses: it emits `response/response.json`
+with status `waiting` and `awaiting { exchange: critique, kind: independent-critique }`. The
+orchestrator writes `critique/request/request.json` with only `response/data/stack-model.json` as
+input, never the author's rationale, and runs a fresh agent on this operator's own profile with no
+inherited turns. That agent writes only `critique/response/`. When its response is done the paused
+agent resumes at the confirmation step. Other branches of the same step keep running throughout.
+
+## Boundary
+
+Context is read-only. The operator writes only `response/` of its own branch: `response.md`,
+`data/current-state.json`, `data/stack-model.json`, the alternatives page when more than one
+alternative was asked for, and `response.json`; the critique agent writes only
+`critique/response/`. It does not mutate routed source, publish business authority, start or
+reconfigure runtime services, name implementation files in the handoff, or claim that an
+implementation, a quality gate, or a UAT run has passed.
+
+## Context
+
+| Alias | Bind | Required |
+| --- | --- | --- |
+| `@workspaces/be` | the routed backend checkout read at the frozen head; the inventory comes from its manifests and deployment files | yes |
+| `@worktrees/businesses/<featureId>` | the published business head, the promise the architecture must keep | yes |
+| `@knowledge/patterns` | reusable shapes the scope may bind; a shape, never a selection | no |
+
+## Inputs
+
+| Kind | From | Required |
+| --- | --- | --- |
+| `architecture-decision` | a prior run of `architecture.decide` on the same or an adjacent boundary; lineage that may be contradicted, never ignored | no |
+
+## Requirements
+
+| Field | Type | Default | Ask |
+| --- | --- | --- | --- |
+| `objective` | prompt | — | The objective the architecture must achieve, in the person's words |
+| `decisionId` | id | slug of `objective` | The name the artifacts carry |
+| `alternatives` | number 1–4 | 1 | How many materially different designs to generate; more than one only when a comparison was asked for |
+| `tradeoffAxes` | list | cost, complexity, reversibility | The axes every alternative is scored on and the critique attacks along |
+| `constraints` | list of `{id, kind, statement}` | — | kind is fixed-intent, measurable, preference, assumption or unknown; at least one fixed-intent |
+| `selectionPolicy` | choice | automatic | `automatic`: the operator selects and records why; `approval-required`: the person selects |
+| `approval` | id | null | The approved alternative id; required only under `approval-required`, supplied on resume after `CHOICE_REQUIRED` |
+| `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`, `approval` | `request/request.json`, input `architecture-decision` when present, @workspaces/be at the frozen head | — | `INVALID_INPUT`, `SOURCE_DRIFT`, `NO_PROGRESS` |
+| 2 | Observe the current state | — | @workspaces/be at the frozen head: manifests, configuration, deployment files, @tools/git | `response/data/current-state.json` | `CURRENT_STATE_UNOBSERVED` |
+| 3 | Bind the inventory to the business promise | — | `response/data/current-state.json`, @worktrees/businesses/<featureId> at its published head | — | `BUSINESS_AUTHORITY_REQUIRED`, `EVIDENCE_MISSING` |
+| 4 | Frame the decision | `objective`, `decisionId`, `constraints`, `tradeoffAxes` | `request/request.json` requirements | — | `CONSTRAINT_CONTRADICTION` |
+| 5 | Generate the alternatives | `alternatives` | `response/data/current-state.json`, @knowledge/patterns, @tools/websearch | `response/artifacts/<decisionId>-alternatives.html` only when more than one alternative was asked for, @tools/visualize | `NO_VIABLE_ALTERNATIVE` |
+| 6 | Select | `selectionPolicy`, `tradeoffAxes`, `approval` | `response/artifacts/<decisionId>-alternatives.html` when present | — | `CHOICE_REQUIRED` |
+| 7 | Deepen the selected alternative | `constraints` | `response/data/current-state.json` | `response/data/stack-model.json` | `DATA_OWNERSHIP_UNASSIGNED`, `COMPATIBILITY_UNVERIFIED` |
+| 8 | Await the critique: pause, a fresh agent attacks the selection, resume when it answers | — | `critique/response/critique.md` once the exchange is done | `response/response.json` (waiting, awaiting critique) | `CRITIQUE_UNRESOLVED` |
+| 9 | Confirm or return the selection | `selectionPolicy` | `critique/response/critique.md`, `response/data/stack-model.json` | — | `CHOICE_REQUIRED`, `NO_VIABLE_ALTERNATIVE` |
+| 10 | Write the handoff and emit | — | everything above | `response/response.md`, `response/response.json` | — |
+
+Under the defaults, step 5 produces one design and no comparison page, step 6 has nothing to
+choose, and the decision's quality rests on step 8. When the only alternative fails an attack, step 9
+stops with `NO_VIABLE_ALTERNATIVE`, not `CHOICE_REQUIRED`. The handoff names contracts, never
+implementation files, because choosing the files is the next domain's job.
+
+## Outputs
+
+| Kind | File | Type | Required |
+| --- | --- | --- | --- |
+| `architecture-decision` | `response/response.md` | md | yes |
+| `current-state` | `response/data/current-state.json` | data | yes |
+| `stack-model` | `response/data/stack-model.json` | data | yes |
+| `alternatives` | `response/artifacts/<decisionId>-alternatives.html` | artifact | no |
+| `independent-critique` | `critique/response/critique.md` | md | yes |
+
+## Stops
+
+| Code | Disposition |
+| --- | --- |
+| `INVALID_INPUT` | terminate |
+| `SOURCE_DRIFT` | terminate |
+| `NO_PROGRESS` | terminate |
+| `EVIDENCE_MISSING` | terminate |
+| `CURRENT_STATE_UNOBSERVED` | terminate |
+| `BUSINESS_AUTHORITY_REQUIRED` | terminate |
+| `CONSTRAINT_CONTRADICTION` | terminate |
+| `NO_VIABLE_ALTERNATIVE` | terminate |
+| `CHOICE_REQUIRED` | fallback |
+| `COMPATIBILITY_UNVERIFIED` | fallback |
+| `DATA_OWNERSHIP_UNASSIGNED` | terminate |
+| `CRITIQUE_UNRESOLVED` | terminate |
+
+## Next
+
+| When | Operator |
+| --- | --- |
+| the business promise must be modelled again against the decided boundaries | `business.decide` |
+| the decision is confirmed and a backend contract changes | `backend.source.apply` |
+| the decision is confirmed and a frontend surface changes | `frontend.direction.decide` |

package/operators/architecture-decide/operator.vi.md

@@ -0,0 +1,130 @@
+# architecture.decide
+
+## Việc
+
+Quyết một kiến trúc với stack, ranh giới hệ thống và quyền sở hữu dữ liệu, rồi chứng minh nó bằng
+hiện trạng quan sát được, các phương án bị loại, tương thích đã kiểm và một phản biện độc lập.
+
+## Quan sát trước khi đề xuất
+
+Không đề xuất gì trước khi hiện trạng được quan sát ở head đóng băng của `@workspaces/be` và ghi vào
+`response/data/current-state.json` với fingerprint riêng. Một đề xuất viết trước khi quan sát mô tả
+một hệ thống đơn giản hơn hệ thống thật, và mọi so sánh sau đó thừa hưởng sự đơn giản hoá ấy. Quan
+sát ở một head khác còn tệ hơn: trông chặt chẽ nhưng mô tả mã không còn tồn tại.
+
+## Đang chạy sẵn không phải là lý do
+
+Inventory nói hệ thống hôm nay chạy gì; đó là context hữu ích nhất và nguy hiểm nhất operator này
+nhận. Một framework, datastore, broker hay hình dạng deploy đang có chỉ đi vào quyết định theo đúng
+hai vai: ràng buộc đo được mà đích phải thoả, hoặc bằng chứng quan sát về hành vi đã được chứng minh.
+Nó không bao giờ là lý do tự thân. Component được biện minh vì đã có sẵn bị loại thẳng.
+
+## Chứng minh, không giả định
+
+Một phương án chỉ được tính khi khác nhau về bản chất, khác về quyền sở hữu hay cơ chế chứ không
+phải câu chữ, và được chấm trên đúng các trục đánh đổi người dùng nêu. Mọi component giữ lại mang
+một phán quyết đã kiểm có bằng chứng trên năm trục: phiên bản runtime, đơn vị deploy, lỗi giao
+tiếp, quyền sở hữu datastore, sao lưu và khôi phục; phán quyết bỏ qua một trục là kiểm một phần
+đội lốt kiểm đầy đủ. Mọi boundary trả lời câu hỏi dữ liệu: sở hữu ít nhất một store hoặc nói rõ
+không sở hữu; một store gọi tên đúng một boundary chủ và boundary đó ghi nó, người ghi thứ hai chỉ
+tồn tại khi có lý do chia sẻ ghi rõ ràng.
+
+## Phản biện là một cuộc trao đổi lồng
+
+Sau khi phương án đã chọn được đào sâu, nhánh tạm ngưng: nó phát `response/response.json` với status
+`waiting` và `awaiting { exchange: critique, kind: independent-critique }`. Orchestrator ghi
+`critique/request/request.json` chỉ với `response/data/stack-model.json` làm đầu vào, không bao giờ
+kèm lý lẽ của tác giả, rồi chạy một agent mới trên chính profile của operator này, không thừa hưởng
+lượt. Agent đó chỉ ghi `critique/response/`. Khi response của nó done, agent đang ngưng chạy tiếp ở
+bước xác nhận. Các nhánh khác cùng bậc vẫn chạy suốt thời gian đó.
+
+## Ranh giới
+
+Context chỉ đọc. Operator chỉ ghi `response/` của nhánh mình: `response.md`,
+`data/current-state.json`, `data/stack-model.json`, trang so sánh phương án khi được yêu cầu nhiều
+hơn một phương án, và `response.json`; agent phản biện chỉ ghi `critique/response/`. Nó không sửa
+source được route, không publish thẩm quyền nghiệp vụ, không khởi động hay cấu hình lại dịch vụ
+runtime, không nêu tên file implementation trong handoff, và không tuyên bố implementation, cổng
+chất lượng hay UAT đã qua.
+
+## Context
+
+| Alias | Bind | Bắt buộc |
+| --- | --- | --- |
+| `@workspaces/be` | checkout backend được route, đọc ở head đóng băng; inventory lấy từ manifest và file deploy | có |
+| `@worktrees/businesses/<featureId>` | head nghiệp vụ đã publish, lời hứa mà kiến trúc phải giữ | có |
+| `@knowledge/patterns` | hình dạng tái dùng mà scope có thể ràng; là hình dạng, không bao giờ là lựa chọn | không |
+
+## Đầu vào
+
+| Kind | Từ đâu | Bắt buộc |
+| --- | --- | --- |
+| `architecture-decision` | một lần chạy `architecture.decide` trước trên cùng hoặc kề ranh giới; dòng dõi có thể bị phản bác, không được bỏ qua | không |
+
+## Yêu cầu
+
+| Field | Kiểu | Mặc định | Hỏi |
+| --- | --- | --- | --- |
+| `objective` | prompt | — | Mục tiêu kiến trúc phải đạt, bằng lời của người dùng |
+| `decisionId` | id | slug of `objective` | Tên mà các artifact mang |
+| `alternatives` | number 1–4 | 1 | Sinh bao nhiêu thiết kế khác nhau về bản chất; nhiều hơn một chỉ khi được yêu cầu so sánh |
+| `tradeoffAxes` | list | cost, complexity, reversibility | Các trục mọi phương án được chấm và phản biện bám theo |
+| `constraints` | list `{id, kind, statement}` | — | kind là fixed-intent, measurable, preference, assumption hoặc unknown; ít nhất một fixed-intent |
+| `selectionPolicy` | choice | automatic | `automatic`: operator chọn và ghi lý do; `approval-required`: người chọn |
+| `approval` | id | null | Id phương án được duyệt; chỉ bắt buộc dưới `approval-required`, nhập khi chạy lại sau `CHOICE_REQUIRED` |
+| `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 và chạy lại | `resume`, `approval` | `request/request.json`, đầu vào `architecture-decision` nếu có, @workspaces/be ở head đóng băng | — | `INVALID_INPUT`, `SOURCE_DRIFT`, `NO_PROGRESS` |
+| 2 | Quan sát hiện trạng | — | @workspaces/be ở head đóng băng: manifest, cấu hình, file deploy, @tools/git | `response/data/current-state.json` | `CURRENT_STATE_UNOBSERVED` |
+| 3 | Ràng inventory với lời hứa nghiệp vụ | — | `response/data/current-state.json`, @worktrees/businesses/<featureId> ở head đã publish | — | `BUSINESS_AUTHORITY_REQUIRED`, `EVIDENCE_MISSING` |
+| 4 | Đóng khung quyết định | `objective`, `decisionId`, `constraints`, `tradeoffAxes` | phần requirements của `request/request.json` | — | `CONSTRAINT_CONTRADICTION` |
+| 5 | Sinh các phương án | `alternatives` | `response/data/current-state.json`, @knowledge/patterns, @tools/websearch | `response/artifacts/<decisionId>-alternatives.html` chỉ khi được yêu cầu nhiều hơn một phương án, @tools/visualize | `NO_VIABLE_ALTERNATIVE` |
+| 6 | Chọn | `selectionPolicy`, `tradeoffAxes`, `approval` | `response/artifacts/<decisionId>-alternatives.html` khi có | — | `CHOICE_REQUIRED` |
+| 7 | Đào sâu phương án đã chọn | `constraints` | `response/data/current-state.json` | `response/data/stack-model.json` | `DATA_OWNERSHIP_UNASSIGNED`, `COMPATIBILITY_UNVERIFIED` |
+| 8 | Chờ phản biện: tạm ngưng, một agent mới tấn công lựa chọn, chạy tiếp khi nó trả lời | — | `critique/response/critique.md` khi cuộc trao đổi done | `response/response.json` (waiting, awaiting critique) | `CRITIQUE_UNRESOLVED` |
+| 9 | Xác nhận hoặc trả lại lựa chọn | `selectionPolicy` | `critique/response/critique.md`, `response/data/stack-model.json` | — | `CHOICE_REQUIRED`, `NO_VIABLE_ALTERNATIVE` |
+| 10 | Viết handoff và phát | — | mọi thứ ở trên | `response/response.md`, `response/response.json` | — |
+
+Với mặc định, bước 5 sinh một thiết kế và không có trang so sánh, bước 6 không có gì để chọn, và
+chất lượng quyết định dựa vào bước 8. Khi phương án duy nhất chết dưới một đòn tấn công, bước 9 dừng
+với `NO_VIABLE_ALTERNATIVE`, không phải `CHOICE_REQUIRED`. Handoff nêu tên contract, không bao giờ
+nêu file implementation, vì chọn file là việc của domain kế tiếp.
+
+## Đầu ra
+
+| Kind | File | Kiểu | Bắt buộc |
+| --- | --- | --- | --- |
+| `architecture-decision` | `response/response.md` | md | có |
+| `current-state` | `response/data/current-state.json` | data | có |
+| `stack-model` | `response/data/stack-model.json` | data | có |
+| `alternatives` | `response/artifacts/<decisionId>-alternatives.html` | artifact | không |
+| `independent-critique` | `critique/response/critique.md` | md | có |
+
+## Dừng
+
+| Code | Xử lý |
+| --- | --- |
+| `INVALID_INPUT` | terminate |
+| `SOURCE_DRIFT` | terminate |
+| `NO_PROGRESS` | terminate |
+| `EVIDENCE_MISSING` | terminate |
+| `CURRENT_STATE_UNOBSERVED` | terminate |
+| `BUSINESS_AUTHORITY_REQUIRED` | terminate |
+| `CONSTRAINT_CONTRADICTION` | terminate |
+| `NO_VIABLE_ALTERNATIVE` | terminate |
+| `CHOICE_REQUIRED` | fallback |
+| `COMPATIBILITY_UNVERIFIED` | fallback |
+| `DATA_OWNERSHIP_UNASSIGNED` | terminate |
+| `CRITIQUE_UNRESOLVED` | terminate |
+
+## Kế tiếp
+
+| Khi | Operator |
+| --- | --- |
+| lời hứa nghiệp vụ phải được mô hình lại theo các boundary đã quyết | `business.decide` |
+| quyết định đã xác nhận và một contract backend thay đổi | `backend.source.apply` |
+| quyết định đã xác nhận và một bề mặt frontend thay đổi | `frontend.direction.decide` |

package/operators/architecture-decide/self-test.mjs

@@ -0,0 +1,221 @@
+// Proves validate.mjs on a synthetic session branch: one conforming branch under the defaults
+// (alternatives = 1, automatic) with its critique exchange, one with three alternatives under
+// approval-required, one blocked on a terminate code, 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 { validateArchitectureStep } from './validate.mjs';
+
+const head = 'b'.repeat(40);
+const fp = `sha256:${'a'.repeat(64)}`;
+const ev = (p) => `${p}@${head}`;
+
+function currentState() {
+  return {
+    observedHead: head, fingerprint: fp,
+    components: [
+      { componentId: 'nestjs', layer: 'framework', name: 'NestJS', version: '10.4.0', evidence: ev('package.json:12') },
+      { componentId: 'postgres', layer: 'persistence', name: 'PostgreSQL', version: '16.2', evidence: ev('compose.yaml:30-41') },
+    ],
+    boundaries: [{ boundaryId: 'entitlement', responsibility: 'answers who may read a course', stores: ['entitlement-store'], evidence: ev('src/entitlement/index.ts:1-40') }],
+  };
+}
+const verdicts = () => ['runtime-version', 'deployable-unit', 'communication-failure', 'datastore-ownership', 'backup-restore'].map((axis) => ({ axis, verified: true, evidence: ev('compose.yaml:30') }));
+function stackModel({ alternatives = 1 } = {}) {
+  const alts = [{ alternativeId: 'shared-boundary', status: 'selected', scores: { cost: 4, complexity: 3, reversibility: 4 }, rejectedBecause: null }];
+  if (alternatives > 1) alts.push({ alternativeId: 'per-feature-guards', status: 'rejected', scores: { cost: 2, complexity: 2, reversibility: 3 }, rejectedBecause: 'three boundaries derive one answer' });
+  if (alternatives > 2) alts.push({ alternativeId: 'edge-cache', status: 'rejected', scores: { cost: 3, complexity: 1, reversibility: 1 }, rejectedBecause: 'stale claims after revocation' });
+  return {
+    decisionId: 'entitlement-read-path', selectedAlternativeId: 'shared-boundary', alternatives: alts,
+    boundaries: [
+      { boundaryId: 'entitlement', responsibility: 'one entitlement answer', owner: 'platform-team', interfaces: ['EntitlementQuery'], ownsData: true },
+      { boundaryId: 'course-api', responsibility: 'serves course content', owner: 'learning-team', interfaces: ['CourseQuery'], ownsData: false },
+    ],
+    stores: [{ storeId: 'entitlement-store', owningBoundaryId: 'entitlement', writers: ['entitlement'], readers: ['course-api'], migrators: ['entitlement'], transactionScope: 'per request', backup: 'nightly snapshot', restore: 'tested weekly', sharedWriteJustification: null }],
+    components: [
+      { componentId: 'nestjs', status: 'existing', justification: 'observed-evidence', evidence: ev('package.json:12'), compatibility: verdicts() },
+      { componentId: 'postgres', status: 'existing', justification: 'measured-constraint', evidence: ev('compose.yaml:30'), compatibility: verdicts() },
+      { componentId: 'redis-cache', status: 'removed', justification: null, evidence: null, compatibility: [] },
+    ],
+  };
+}
+function responseMd({ alternatives = 1, policy = 'automatic', handoffDetail = 'EntitlementQuery contract returns one answer per viewer' } = {}) {
+  const altRows = ['| `shared-boundary` | selected | cost 4 · complexity 3 · reversibility 4 | — |'];
+  if (alternatives > 1) altRows.push('| `per-feature-guards` | rejected | cost 2 · complexity 2 · reversibility 3 | three boundaries derive one answer |');
+  if (alternatives > 2) altRows.push('| `edge-cache` | rejected | cost 3 · complexity 1 · reversibility 1 | stale claims after revocation |');
+  return `# architecture-decision — entitlement-read-path
+
+## Decision
+
+| Field | Value |
+| --- | --- |
+| Objective | one entitlement read path |
+| Decision id | \`entitlement-read-path\` |
+| Selected alternative | \`shared-boundary\` |
+| Selection policy | \`${policy}\` |
+
+## Current state
+
+| Boundary | Responsibility | Stores | Evidence |
+| --- | --- | --- | --- |
+| \`entitlement\` | answers who may read a course | \`entitlement-store\` | \`src/entitlement/index.ts:1-40@${head}\` |
+
+## Alternatives
+
+| Alternative | Status | Assessment | Rejected because |
+| --- | --- | --- | --- |
+${altRows.join('\n')}
+
+## Boundaries
+
+| Boundary | Responsibility | Owner | Interfaces | Owns data |
+| --- | --- | --- | --- | --- |
+| \`entitlement\` | one entitlement answer | platform-team | EntitlementQuery | yes |
+| \`course-api\` | serves course content | learning-team | CourseQuery | no |
+
+## Data ownership
+
+| Store | Owning boundary | Writers | Readers | Migrators | Transaction scope | Backup | Restore |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| \`entitlement-store\` | \`entitlement\` | \`entitlement\` | \`course-api\` | \`entitlement\` | per request | nightly snapshot | tested weekly |
+
+## Stack delta
+
+| Component | Status | Justification | Evidence | Compatibility |
+| --- | --- | --- | --- | --- |
+| \`nestjs\` | existing | observed-evidence | \`package.json:12@${head}\` | 5/5 verified |
+| \`postgres\` | existing | measured-constraint | \`compose.yaml:30@${head}\` | 5/5 verified |
+| \`redis-cache\` | removed | — | — | — |
+
+## Handoff
+
+| Item | Kind | Detail |
+| --- | --- | --- |
+| one answer per viewer | invariant | every entitlement read returns the same answer within one request |
+| entitlement query | contract | ${handoffDetail} |
+| cache removal | migration | drop the cache after the shared boundary serves all readers |
+| revert | rollback | restore the cache reader behind a flag |
+| proof | proof | integration test asserting one answer across three readers |
+
+## Fallbacks taken
+
+| Code | Action |
+| --- | --- |
+`;
+}
+function critiqueMd({ failing = false, selection = 'keep', inherited = 'none' } = {}) {
+  const paths = ['partial-failure', 'retry-idempotency', 'concurrency', 'stale-state', 'deletion', 'recovery', 'dependency-outage', 'rollback'];
+  return `# independent-critique — entitlement-read-path
+
+## Execution
+
+| Field | Value |
+| --- | --- |
+| Reviewer execution | exec://critique-7f3a |
+| Inherited turns | ${inherited} |
+| Given | response/data/stack-model.json |
+
+## Attacks
+
+| Adverse path | Attack | Resolution | Verdict |
+| --- | --- | --- | --- |
+${paths.map((p, i) => `| ${p} | what if ${p} hits the shared boundary | idempotent read, single writer | ${failing && i === 3 ? 'fails' : 'holds'} |`).join('\n')}
+
+## Verdict
+
+| Field | Value |
+| --- | --- |
+| Selection | ${selection} |
+`;
+}
+const requestJson = ({ alternatives = 1, policy = 'automatic', approval = null, extra = {} } = {}) => ({
+  schemaVersion: 9, operatorId: 'architecture.decide', step: 1, parallel: 1, sessionId: 's-test',
+  contexts: [{ alias: '@workspaces/be', head }, { alias: '@worktrees/businesses/pro-subscription', head: null }],
+  requirements: { objective: 'one entitlement read path', decisionId: 'entitlement-read-path', alternatives, tradeoffAxes: ['cost', 'complexity', 'reversibility'], constraints: [{ id: 'fi-1', kind: 'fixed-intent', statement: 'one answer per viewer' }, { id: 'm-1', kind: 'measurable', statement: 'p95 read under 50ms' }], selectionPolicy: policy, approval, resume: null, ...extra },
+  inputs: {}, resume: null,
+});
+const critiqueRequest = (inputs = { 'stack-model': 'step-1/parallel-1/response/data/stack-model.json' }) => ({ schemaVersion: 9, operatorId: 'architecture.decide', step: 1, parallel: 1, sessionId: 's-test', exchange: 'critique', contexts: [], requirements: {}, inputs, resume: null });
+const critiqueResponse = () => ({ schemaVersion: 9, operatorId: 'architecture.decide', step: 1, parallel: 1, exchange: 'critique', status: 'done', fallbacks: [], fields: { 'independent-critique': 'response/critique.md' }, commits: [], next: [] });
+function responseJson({ status = 'done', stop, fallbacks = [], withAlternatives = false, next = ['backend.source.apply'] } = {}) {
+  const fields = { 'architecture-decision': 'response/response.md', 'current-state': 'response/data/current-state.json', 'stack-model': 'response/data/stack-model.json' };
+  if (withAlternatives) fields.alternatives = 'response/artifacts/entitlement-read-path-alternatives.html';
+  return { schemaVersion: 9, operatorId: 'architecture.decide', step: 1, parallel: 1, status, ...(stop ? { stop } : {}), fallbacks, fields, commits: [], next };
+}
+
+function writeBranch(files) {
+  const session = mkdtempSync(path.join(tmpdir(), 'arch-session-'));
+  const branch = path.join(session, 'step-1', 'parallel-1');
+  for (const d of ['request', 'response/data', 'response/artifacts', 'critique/request', 'critique/response']) mkdirSync(path.join(branch, d), { recursive: true });
+  writeFileSync(path.join(session, 'state.json'), JSON.stringify({ id: 's-test', chain: [['1/1']], steps: { '1/1': 'architecture.decide' }, current: '1/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/current-state.json': currentState(),
+  'response/data/stack-model.json': stackModel(),
+  'critique/request/request.json': critiqueRequest(),
+  'critique/response/response.json': critiqueResponse(),
+  'critique/response/critique.md': critiqueMd(),
+});
+
+async function expectValid(files, label) {
+  const { branch, session } = writeBranch(files);
+  const { errors } = await validateArchitectureStep(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 validateArchitectureStep(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 threeAlts = (policy, approval, extraResponse = {}) => ({
+  ...baseline(),
+  'request/request.json': requestJson({ alternatives: 3, policy, approval }),
+  'response/response.md': responseMd({ alternatives: 3, policy }),
+  'response/data/stack-model.json': stackModel({ alternatives: 3 }),
+  'response/response.json': responseJson({ withAlternatives: true, ...extraResponse }),
+  'response/artifacts/entitlement-read-path-alternatives.html': '<!doctype html><title>alternatives</title>',
+});
+
+await expectValid(baseline(), 'defaults (one alternative, automatic, critique exchange done)');
+await expectValid(threeAlts('approval-required', 'shared-boundary'), 'three alternatives under approval-required');
+await expectValid({ ...baseline(), 'response/response.json': responseJson({ status: 'blocked', stop: 'DATA_OWNERSHIP_UNASSIGNED', next: [] }), 'critique/request/request.json': null, 'critique/response/response.json': null, 'critique/response/critique.md': null }, 'blocked before the critique on a terminate code');
+await expectValid({ ...baseline(), 'response/response.json': { ...responseJson({ next: [] }), status: 'waiting', awaiting: { exchange: 'critique', kind: 'independent-critique' }, fields: { 'current-state': 'response/data/current-state.json', 'stack-model': 'response/data/stack-model.json' } }, 'response/response.md': null, 'critique/request/request.json': null, 'critique/response/response.json': null, 'critique/response/critique.md': null }, 'waiting for the critique');
+await expectValid({ ...threeAlts('approval-required', null, { status: 'blocked', stop: 'CHOICE_REQUIRED', next: [] }), 'critique/request/request.json': null, 'critique/response/response.json': null, 'critique/response/critique.md': null }, 'CHOICE_REQUIRED terminates under approval-required');
+
+await expectError({ ...baseline(), 'response/response.json': { ...responseJson(), stop: 'CHOICE_REQUIRED' } }, 'only a blocked response carries a stop', 'done with stop');
+await expectError({ ...baseline(), 'response/response.json': responseJson({ status: 'blocked', stop: 'MADE_UP_CODE', next: [] }) }, 'not a registered code', 'unknown stop code');
+await expectError({ ...baseline(), 'response/response.json': responseJson({ status: 'blocked', stop: 'CHOICE_REQUIRED', next: [] }) }, 'has disposition fallback under these requirements', 'terminating on a fallback code under automatic');
+await expectError({ ...baseline(), 'response/response.json': responseJson({ fallbacks: ['DATA_OWNERSHIP_UNASSIGNED'] }) }, 'has disposition terminate under these requirements; it cannot be taken as a fallback', 'fallback on a terminate code');
+await expectError({ ...baseline(), 'response/response.json': responseJson({ fallbacks: ['COMPATIBILITY_UNVERIFIED'] }) }, 'not recorded under ## Fallbacks taken', 'fallback missing from response');
+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: { objective: '' } }) }, 'required field objective has no value', 'missing required objective');
+await expectError({ ...baseline(), 'request/request.json': requestJson({ approval: 'shared-boundary' }) }, 'approval is bound under automatic policy', 'approval under automatic');
+await expectError({ ...baseline(), 'critique/response/critique.md': critiqueMd().replace('| rollback |', '| rollbak |') }, 'lacks a row for rollback', 'critique missing an adverse path');
+await expectError({ ...baseline(), 'critique/response/critique.md': critiqueMd({ failing: true }) }, 'attacks stale-state fail', 'done with a failing attack');
+await expectError({ ...baseline(), 'critique/response/critique.md': critiqueMd({ inherited: 'author thread' }) }, 'no inherited turns', 'critique inherited turns');
+await expectError({ ...baseline(), 'critique/request/request.json': critiqueRequest({ 'stack-model': 'step-1/parallel-1/response/data/stack-model.json', 'architecture-decision': 'step-1/parallel-1/response/response.md' }) }, "may not be given the author's response.md", 'critique given the rationale');
+await expectError({ ...baseline(), 'critique/request/request.json': null, 'critique/response/response.json': null, 'critique/response/critique.md': null }, 'the branch is done, but it never ran', 'done without the critique exchange');
+await expectError({ ...baseline(), 'response/data/stack-model.json': { ...stackModel(), stores: [{ ...stackModel().stores[0], writers: ['course-api'] }] } }, 'is not among its writers', 'owner does not write its store');
+await expectError({ ...baseline(), 'response/data/stack-model.json': { ...stackModel(), stores: [{ ...stackModel().stores[0], writers: ['entitlement', 'course-api'] }] } }, 'no shared-write justification', 'unjustified second writer');
+await expectError({ ...baseline(), 'response/data/stack-model.json': { ...stackModel(), components: stackModel().components.map((c) => (c.componentId === 'nestjs' ? { ...c, compatibility: c.compatibility.slice(0, 4) } : c)) } }, 'compatibility unverified on backup-restore', 'retained component missing an axis');
+await expectError({ ...baseline(), 'response/data/stack-model.json': { ...stackModel(), alternatives: [{ ...stackModel().alternatives[0], status: 'rejected', rejectedBecause: 'x' }] } }, 'exactly one alternative must be selected', 'no selected alternative');
+await expectError({ ...baseline(), 'response/data/stack-model.json': stackModel({ alternatives: 2 }) }, 'but the request asked for 1', 'more alternatives than asked');
+await expectError({ ...baseline(), 'response/response.md': responseMd({ handoffDetail: 'src/entitlement/query.ts returns one answer' }) }, 'names an implementation file', 'handoff names a file');
+await expectError({ ...baseline(), 'response/response.md': responseMd().replace('| Selected alternative | `shared-boundary` |', '| Selected alternative | `edge-cache` |') }, 'Decision names edge-cache', 'response and model disagree on the selection');
+await expectError({ ...baseline(), 'response/response.md': responseMd().replace('## Handoff', '## Hand-off') }, 'missing section ^## Handoff$', 'response section renamed');
+await expectError({ ...baseline(), 'response/data/current-state.json': { ...currentState(), observedHead: 'nope' } }, 'observedHead', 'current-state schema');
+await expectError({ ...baseline(), 'response/response.json': (() => { const o = responseJson(); delete o.fields['stack-model']; return o; })() }, 'required output stack-model is not in fields', 'missing required output');
+await expectError({ ...baseline(), 'response/response.json': { ...responseJson(), status: 'waiting', awaiting: { exchange: 'review', kind: 'independent-critique' } } }, 'awaiting exchange review is declared by no Output', 'waiting on an undeclared exchange');
+
+process.stdout.write('architecture.decide self-test: 5 valid branches, 25 rejected mutations\n');

package/operators/architecture-decide/validate.mjs

@@ -0,0 +1,112 @@
+// architecture.decide's own law over one branch, on top of the shared step check: exactly one selected
+// alternative that the response names; the number of alternatives the person asked for; approval
+// binds the selection under approval-required and is absent under automatic; every store has an
+// owner among its writers and shared writes are justified; retained components are verified on all
+// five axes or carry the COMPATIBILITY_UNVERIFIED fallback; the critique came from the nested
+// exchange, attacks the selected alternative, and a failing attack cannot end in status done; the
+// handoff names contracts, never implementation files.
+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 AXES = ['runtime-version', 'deployable-unit', 'communication-failure', 'datastore-ownership', 'backup-restore'];
+const IMPLEMENTATION_FILE = /\b[\w./-]+\.(ts|tsx|js|jsx|mjs|cjs|py|go|java|rb|rs|php|sql)\b/i;
+const empty = (v) => v === undefined || v === null || v === '' || v === '—';
+
+export async function validateArchitectureStep(branchDir, root = ROOT) {
+  const base = await validateStep(root, branchDir);
+  const errors = [...base.errors];
+  const { response, requirements = {}, present = new Set() } = base;
+  if (!response || response.operatorId !== 'architecture.decide') return { errors };
+  const has = (f) => existsSync(path.join(branchDir, f));
+  const read = (f) => readFile(path.join(branchDir, f), 'utf8');
+  const wanted = Number(requirements.alternatives ?? 1);
+  const policy = requirements.selectionPolicy ?? 'automatic';
+  const approval = requirements.approval;
+  if (policy === 'automatic' && !empty(approval)) errors.push('request.json: approval is bound under automatic policy; supplying both hides which one decided');
+
+  let model = null;
+  if (present.has('stack-model') && has('response/data/stack-model.json')) { try { model = JSON.parse(await read('response/data/stack-model.json')); } catch { model = null; } }
+  if (model) {
+    const selected = model.alternatives.filter((a) => a.status === 'selected');
+    if (selected.length !== 1) errors.push(`response/data/stack-model.json: exactly one alternative must be selected, found ${selected.length}`);
+    else if (selected[0].alternativeId !== model.selectedAlternativeId) errors.push('response/data/stack-model.json: selectedAlternativeId names an alternative that is not the selected one');
+    if (model.alternatives.length !== wanted) errors.push(`response/data/stack-model.json: ${model.alternatives.length} alternatives, but the request asked for ${wanted}`);
+    const axes = Array.isArray(requirements.tradeoffAxes) ? requirements.tradeoffAxes : String(requirements.tradeoffAxes ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+    for (const a of model.alternatives) {
+      if (a.status === 'rejected' && !a.rejectedBecause) errors.push(`response/data/stack-model.json: ${a.alternativeId} is rejected without a reason`);
+      if (a.status === 'selected' && a.rejectedBecause) errors.push(`response/data/stack-model.json: ${a.alternativeId} is selected and carries a rejection reason`);
+      if (wanted > 1) for (const ax of axes) if (a.scores[ax] === undefined) errors.push(`response/data/stack-model.json: ${a.alternativeId} is not scored on ${ax}`);
+    }
+    if (wanted > 1 && !present.has('alternatives')) errors.push('response/response.json: more than one alternative was asked for but no alternatives page is in fields');
+    if (policy === 'approval-required' && response.status === 'done') {
+      if (empty(approval)) errors.push('response/response.json: approval-required with no approval cannot end done; CHOICE_REQUIRED terminates here');
+      else if (approval !== model.selectedAlternativeId) errors.push(`response/data/stack-model.json: selected ${model.selectedAlternativeId} but approval names ${approval}`);
+    }
+    const boundaries = new Map(model.boundaries.map((b) => [b.boundaryId, b]));
+    const owned = new Map();
+    for (const s of model.stores) {
+      if (!boundaries.has(s.owningBoundaryId)) errors.push(`response/data/stack-model.json: store ${s.storeId} is owned by unknown boundary ${s.owningBoundaryId}`);
+      if (!s.writers.includes(s.owningBoundaryId)) errors.push(`response/data/stack-model.json: store ${s.storeId} owner ${s.owningBoundaryId} is not among its writers`);
+      if (s.writers.length > 1 && !s.sharedWriteJustification) errors.push(`response/data/stack-model.json: store ${s.storeId} has ${s.writers.length} writers and no shared-write justification`);
+      if (s.writers.length === 1 && s.sharedWriteJustification) errors.push(`response/data/stack-model.json: store ${s.storeId} has one writer and a shared-write justification`);
+      owned.set(s.owningBoundaryId, (owned.get(s.owningBoundaryId) ?? 0) + 1);
+    }
+    for (const b of model.boundaries) {
+      const n = owned.get(b.boundaryId) ?? 0;
+      if (b.ownsData && n === 0) errors.push(`response/data/stack-model.json: boundary ${b.boundaryId} claims data and owns no store`);
+      if (!b.ownsData && n > 0) errors.push(`response/data/stack-model.json: boundary ${b.boundaryId} claims no data and owns ${n} store(s)`);
+    }
+    const fallbacks = new Set(response.fallbacks ?? []);
+    for (const c of model.components) {
+      if (c.status === 'removed') { if (c.compatibility.length) errors.push(`response/data/stack-model.json: removed component ${c.componentId} carries a compatibility verdict`); continue; }
+      if (!c.justification) errors.push(`response/data/stack-model.json: ${c.componentId} has no justification`);
+      const verified = new Set(c.compatibility.filter((v) => v.verified && v.evidence).map((v) => v.axis));
+      if (c.status === 'replaced-candidate') { if (!fallbacks.has('COMPATIBILITY_UNVERIFIED')) errors.push(`response/data/stack-model.json: ${c.componentId} is replaced-candidate but response.json lists no COMPATIBILITY_UNVERIFIED fallback`); continue; }
+      const missing = AXES.filter((ax) => !verified.has(ax));
+      if (missing.length) errors.push(`response/data/stack-model.json: ${c.componentId} is ${c.status} with compatibility unverified on ${missing.join(', ')}; mark it replaced-candidate under the COMPATIBILITY_UNVERIFIED fallback or terminate`);
+    }
+  }
+
+  if (present.has('architecture-decision') && has('response/response.md')) {
+    const text = await read('response/response.md');
+    const decision = Object.fromEntries((tableUnder(text, '## Decision') ?? []).map(([k, v]) => [k, v]));
+    if (model && decision['Selected alternative'] !== model.selectedAlternativeId) errors.push(`response/response.md: Decision names ${decision['Selected alternative']} but stack-model selected ${model.selectedAlternativeId}`);
+    if (decision['Selection policy'] !== policy) errors.push(`response/response.md: Selection policy ${decision['Selection policy']} differs from the request's ${policy}`);
+    if (!empty(requirements.decisionId) && decision['Decision id'] !== requirements.decisionId) errors.push('response/response.md: Decision id differs from the request');
+    const alts = tableUnder(text, '## Alternatives') ?? [];
+    if (model && alts.length !== model.alternatives.length) errors.push(`response/response.md: Alternatives has ${alts.length} rows, stack-model has ${model.alternatives.length}`);
+    for (const [item, kind, detail] of tableUnder(text, '## Handoff') ?? []) if (kind === 'contract' && IMPLEMENTATION_FILE.test(detail)) errors.push(`response/response.md: handoff contract "${item}" names an implementation file`);
+    for (const [component, status] of tableUnder(text, '## Stack delta') ?? []) if (status === 'replaced-candidate' && !(response.fallbacks ?? []).includes('COMPATIBILITY_UNVERIFIED')) errors.push(`response/response.md: ${component} is replaced-candidate without the COMPATIBILITY_UNVERIFIED fallback`);
+  }
+
+  if (present.has('independent-critique') && has('critique/response/critique.md')) {
+    const text = await read('critique/response/critique.md');
+    const attacks = tableUnder(text, '## Attacks') ?? [];
+    const failing = attacks.filter((r) => r[3] === 'fails').map((r) => r[0]);
+    const verdict = Object.fromEntries((tableUnder(text, '## Verdict') ?? []).map(([k, v]) => [k, v]));
+    if (response.status === 'done' && failing.length) errors.push(`critique/response/critique.md: attacks ${failing.join(', ')} fail; a done branch needs every attack to hold (CRITIQUE_UNRESOLVED or NO_VIABLE_ALTERNATIVE otherwise)`);
+    if (response.status === 'done' && verdict.Selection === 'return') errors.push('critique/response/critique.md: the critique returns the selection, so the branch cannot be done');
+    const exec = Object.fromEntries((tableUnder(text, '## Execution') ?? []).map(([k, v]) => [k, v]));
+    if (exec['Inherited turns'] !== 'none') errors.push('critique/response/critique.md: the critique must be a fresh execution with no inherited turns');
+    if (has('critique/request/request.json')) {
+      const creq = JSON.parse(await read('critique/request/request.json'));
+      const given = Object.values(creq.inputs ?? {});
+      if (!given.some((p) => p.endsWith('/response/data/stack-model.json'))) errors.push('critique/request/request.json: the critique must be given the stack model');
+      if (given.some((p) => p.endsWith('/response/response.md'))) errors.push('critique/request/request.json: the critique may not be given the author\'s response.md');
+    }
+  } else if (response.status === 'done') errors.push('critique/response/critique.md: a done branch needs the critique exchange');
+  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 validateArchitectureStep(path.resolve(target));
+  if (errors.length) { process.stderr.write(`${errors.join('\n')}\n`); process.exitCode = 1; } else process.stdout.write('valid architecture.decide branch\n');
+}