@starci/skills 1.1.0

package/operators/frontend-direction-decide/operator.md

@@ -0,0 +1,167 @@
+# frontend.direction.decide
+
+## Job
+
+Decide one evidence-backed, implementation-ready frontend direction for one authorized target, and
+prove it against the business promise, the published Grammar, the observed implementation and a
+falsification pass that no candidate survives by taste.
+
+## The change level decides what must be bound
+
+The change level is the request's own authority and current source never proves it: an audit that
+asks for a passing surface is `reconstruct`, not `refine`. `new` requires the business promise, and
+it closes the state set and the exits before anything is drawn. `reconstruct` requires the promise
+only when the state set changes, and it preserves the business facts, the behaviour authority and
+the API semantics it inherits. `refine` requires no input authority at all, because it changes
+nothing a promise could contradict. A backend implementation is required when a data contract
+changes, an architecture decision when a boundary changes; neither is required otherwise, and
+neither is ever invented. `create` occurs with `new` and only with it.
+
+## Evidence contradicts, it does not authorize
+
+The current implementation, a green test, a rendered DOM and a prior UAT pass are all evidence, and
+each observation is recorded as a path at the head it was read at. Evidence must be observed before
+any proposal is written: the target's direct artifacts without the producer's rationale, or, for a
+new target, proof that the target is absent and only the authorized host and product-family context.
+None of it authorizes a direction by incumbency. A page that exists is not a reason to build that
+page again.
+
+## Bounded research, and only where it is owed
+
+External references are resolved only when the person supplied none and the change level is `new` or
+`reconstruct`. A `refine` works from the family idioms alone. Every reference that survives is
+recorded with its URL and with the exact limitation it carries; nothing copies a page, a brand, a
+palette or a component anatomy. When bounded research cannot close the business or interaction
+question the decision rests on, the run stops with the owning gap.
+
+## The Grammar filter refuses invention, not ownership
+
+A candidate that invents a missing shared interface, bypasses the owner ceiling, imitates unpublished
+Grammar locally or contradicts a published composition is rejected. `GRAMMAR_REQUIRED` is only for a
+missing family component, and it goes to a person who publishes it; the operator never composes a
+substitute out of parts. A node the application legitimately owns, a canvas for instance, is not a
+Grammar gap and never raises one.
+
+## Candidates are falsified before they are chosen
+
+Falsification attacks business and backend conformance, hierarchy, content density, action feedback,
+recovery, responsive reflow, content stress, keyboard and focus behaviour, accessibility, family
+coherence, reversibility and owner leakage, and every attack lands in the receipt with its verdict.
+A direction is invalid while an applicable business contradiction, owner leak, Grammar invention,
+responsive failure, accessibility failure, unresolved adverse state or materially stronger reversible
+alternative remains. Under `refine` the candidates are element-level moves inside the approved
+structure, never a new structure. When the only candidate fails an attack the run stops with
+`NO_VIABLE_DIRECTION`, and when several survive, `DIRECTION_CHOICE_REQUIRED` selects the one that
+survived the most attacks unless the person kept the choice.
+
+## Boundary
+
+Context is read-only. The operator writes only `response/` of its own branch: the decision receipt,
+the coverage enumeration, the rendered candidate pages and `response.json`. It does not modify
+product or authority source, invent business, backend, architecture, authentication, persistence or
+data behaviour, publish shared UI Grammar, start or reconfigure runtime services, or claim that an
+implementation, a visual quality gate or a UAT run has passed.
+
+## Images are judged, not requested
+
+An image is a composition decision like any other: when a candidate leaves a region that reads empty
+(a hero without a subject, an empty state with only a sentence, a card row whose copy cannot carry the
+width), the operator adds an image made to one stated claim of the direction and records why, in the
+`## Images` table. It does not wait for a person to ask, and it does not decorate: a region that the
+copy and the Grammar objects already carry gets no image, and an image never encodes a claim the
+business promise did not make. The asset and its prompt land under `response/artifacts/images/`;
+`frontend.source.apply` writes them with the declared write set.
+
+## Context
+
+| Alias | Bind | Required |
+| --- | --- | --- |
+| `@grammar/core` | the published Grammar as the bound app resolves it; the compositions a direction may bind | yes |
+| `@knowledge/ui/composition` | the assertions the emitted receipt has to satisfy, `COVERAGE-1` being the assertion about the receipt as a whole | yes |
+| `@workspaces/fe` | the routed frontend checkout read at the frozen head; the current implementation as evidence, never as the requested direction | yes |
+| `@knowledge/grammars/starci` | how the Core family is meant to realize Common; law about the Grammar, never the Grammar itself | no |
+| `@worktrees/uat/<flow>/<case>` | prior behaviour, UX and UI observations with their captures; evidence and counterevidence, and a prior pass is not current authority | no |
+
+## Inputs
+
+| Kind | From | Required |
+| --- | --- | --- |
+| `business-promise-authority` | `business.decide`; required by `new`, and by `reconstruct` when the state set changes | no |
+| `backend-source-application` | `backend.source.apply`; required when a data contract changes | no |
+| `architecture-decision` | `architecture.decide`; required when a boundary changes | no |
+| `frontend-direction-decision` | a prior run of `frontend.direction.decide` on the same target, read when resuming | no |
+
+## Requirements
+
+| Field | Type | Default | Ask |
+| --- | --- | --- | --- |
+| `target` | id | — | The one route, page, layout, modal, drawer, flow, block or component this direction is for |
+| `intent` | choice | modify | create, modify, audit-repair or reconcile; `create` occurs with change level `new` and only with it |
+| `changeLevel` | choice | — | new, reconstruct or refine; an audit that must end in a passing surface is reconstruct |
+| `ownerCeiling` | choice | surface-and-nested-layouts | surface-only, surface-and-nested-layouts or ancestor-layouts-authorized |
+| `candidates` | number 1–3 | 1 | How many directions to form; more than one only when a comparison is wanted |
+| `preview` | choice | no | yes renders the single candidate as an inspectable page |
+| `references` | list | [] | External references the person supplies; bounded research runs only when this is empty |
+| `selectionPolicy` | choice | automatic | `automatic`: the operator selects and records why; `approval-required`: the person selects |
+| `approval` | id | null | The approved candidate id; required only under `approval-required`, supplied on resume after `DIRECTION_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 `frontend-direction-decision` when resuming, @workspaces/fe at the frozen head | — | `INVALID_INPUT`, `SOURCE_DRIFT`, `NO_PROGRESS` |
+| 2 | Check the request: route, scope, change level, owner ceiling | `target`, `intent`, `changeLevel`, `ownerCeiling` | @workspaces/fe at the frozen head, @tools/git | — | `ROUTE_UNVERIFIED`, `SCOPE_UNFROZEN`, `CHANGE_LEVEL_AMBIGUOUS`, `OWNER_CEILING_INVALID` |
+| 3 | Bind the inputs the change level requires | `changeLevel` | inputs `business-promise-authority`, `backend-source-application` and `architecture-decision` | — | `BUSINESS_REQUIRED`, `BACKEND_REQUIRED`, `ARCHITECTURE_REQUIRED` |
+| 4 | Observe the existing context | — | @workspaces/fe (the target's direct artifacts, or the authorized host and product family when the target is absent), @worktrees/uat/<flow>/<case> when present | — | `EVIDENCE_MISSING` |
+| 5 | Compile one UI contract and its coverage | — | @knowledge/ui/composition, input `business-promise-authority` when present, the observed context | `response/data/coverage.json` | `SCOPE_UNFROZEN` |
+| 6 | Resolve external references, bounded | `references`, `changeLevel` | @knowledge/ui/composition (the gap the research must close), @tools/websearch | — | `REFERENCE_EVIDENCE_EXHAUSTED` |
+| 7 | Form the candidates | `candidates` | the compiled UI contract | — | `NO_VIABLE_DIRECTION` |
+| 8 | Apply the Grammar filter | `ownerCeiling` | @grammar/core (what a component owns and which props exist), @knowledge/grammars/starci | — | `GRAMMAR_REQUIRED` |
+| 9 | Render the decision evidence and the judged images | `candidates`, `preview` | the surviving candidates, `@knowledge/grammars/starci` | `response/artifacts/<candidateId>.html`, `response/artifacts/images/<slot>.png`, @tools/visualize, @tools/imagegen | — |
+| 10 | Falsify | — | the candidates, inputs `business-promise-authority` and `backend-source-application`, `response/data/coverage.json` | — | `NO_VIABLE_DIRECTION` |
+| 11 | Decide | `selectionPolicy`, `approval` | the falsification table | — | `DIRECTION_CHOICE_REQUIRED` |
+| 12 | Emit | — | everything above | `response/response.md`, `response/response.json` | — |
+
+Step 9 renders only when more than one candidate was formed or `preview` is yes; a single candidate
+under the defaults produces no page and rests on step 10. Under `automatic`,
+`DIRECTION_CHOICE_REQUIRED` selects the candidate that survived the most attacks and records the
+table; under `approval-required` it stops and the person returns with `approval`. The receipt
+authorizes the next domain to resolve and implement inside the frozen owner ceiling and proves
+nothing about how the result renders.
+
+## Outputs
+
+| Kind | File | Type | Required |
+| --- | --- | --- | --- |
+| `frontend-direction-decision` | `response/response.md` | md | yes |
+| `ui-coverage` | `response/data/coverage.json` | data | yes |
+| `candidates` | `response/artifacts/<candidateId>.html` | artifact | no |
+| `direction-image` | `response/artifacts/images/<slot>.png` | artifact | no |
+
+## Stops
+
+| Code | Disposition |
+| --- | --- |
+| `INVALID_INPUT` | terminate |
+| `ROUTE_UNVERIFIED` | terminate |
+| `SOURCE_DRIFT` | terminate |
+| `SCOPE_UNFROZEN` | terminate |
+| `CHANGE_LEVEL_AMBIGUOUS` | terminate |
+| `OWNER_CEILING_INVALID` | terminate |
+| `BUSINESS_REQUIRED` | terminate |
+| `BACKEND_REQUIRED` | terminate |
+| `ARCHITECTURE_REQUIRED` | terminate |
+| `GRAMMAR_REQUIRED` | terminate |
+| `EVIDENCE_MISSING` | terminate |
+| `REFERENCE_EVIDENCE_EXHAUSTED` | terminate |
+| `NO_VIABLE_DIRECTION` | terminate |
+| `DIRECTION_CHOICE_REQUIRED` | fallback |
+| `NO_PROGRESS` | terminate |
+
+## Next
+
+| When | Operator |
+| --- | --- |
+| the direction is decided; every direction resolves its presentation values before any source is written | `frontend.presentation.resolve` |
+| a family component the direction needs is unpublished, so a person publishes it and the same direction runs again | `frontend.direction.decide` |

package/operators/frontend-direction-decide/operator.vi.md

@@ -0,0 +1,167 @@
+# frontend.direction.decide
+
+## Việc
+
+Quyết một hướng frontend có bằng chứng, đủ để triển khai, cho đúng một target được uỷ quyền, rồi
+chứng minh nó bằng lời hứa nghiệp vụ, Grammar đã publish, hiện trạng quan sát được và một lượt phản
+chứng mà không phương án nào qua được bằng khẩu vị.
+
+## Change level quyết định phải bind những gì
+
+Change level là thẩm quyền của chính lời yêu cầu, và source hiện tại không bao giờ chứng minh được
+nó: một lượt audit đòi bề mặt phải pass là `reconstruct`, không phải `refine`. `new` cần lời hứa
+nghiệp vụ, và nó đóng tập trạng thái cùng các lối ra trước khi vẽ bất cứ thứ gì. `reconstruct` chỉ
+cần lời hứa khi tập trạng thái đổi, và nó giữ nguyên các sự thật nghiệp vụ, thẩm quyền hành vi và
+ngữ nghĩa API mà nó thừa hưởng. `refine` không cần thẩm quyền đầu vào nào cả, vì nó không đổi thứ gì
+mà một lời hứa có thể phản bác. Backend implementation là bắt buộc khi một contract dữ liệu đổi,
+architecture decision khi một ranh giới đổi; ngoài ra không bắt buộc, và không bao giờ được bịa ra.
+`create` đi cùng `new` và chỉ đi cùng nó.
+
+## Bằng chứng phản bác, chứ không uỷ quyền
+
+Hiện trạng implementation, một test xanh, DOM đã render và một lần UAT pass trước đều là bằng chứng,
+và mỗi quan sát được ghi lại thành một path kèm head lúc đọc. Bằng chứng phải được quan sát trước khi
+viết bất kỳ đề xuất nào: lấy các artifact trực tiếp của target mà bỏ lý lẽ của người tạo ra chúng,
+hoặc, với target mới, chứng minh target chưa tồn tại rồi chỉ quan sát host được uỷ quyền và context
+cùng họ sản phẩm. Không mảnh nào trong số đó uỷ quyền cho một hướng chỉ vì nó đang chạy sẵn. Một
+trang đang tồn tại không phải lý do để dựng lại đúng trang ấy.
+
+## Nghiên cứu có giới hạn, và chỉ ở chỗ còn nợ
+
+Tham chiếu ngoài chỉ được đi tìm khi người dùng không cấp cái nào và change level là `new` hay
+`reconstruct`. Một lượt `refine` làm việc bằng idiom của họ là đủ. Mỗi tham chiếu còn lại được ghi
+kèm URL và đúng giới hạn nó mang theo; không gì chép lại một trang, một thương hiệu, một bảng màu hay
+giải phẫu của một component. Khi nghiên cứu có giới hạn không lấp được câu hỏi nghiệp vụ hay tương
+tác mà quyết định dựa vào, lần chạy dừng ở đúng khoảng trống có chủ.
+
+## Bộ lọc Grammar từ chối sự bịa đặt, không từ chối quyền sở hữu
+
+Một phương án bịa ra giao diện dùng chung còn thiếu, đi vòng qua trần owner, bắt chước Grammar chưa
+publish ngay tại chỗ hay chỏi một composition đã publish thì bị loại. `GRAMMAR_REQUIRED` chỉ dành cho
+một component của họ còn thiếu, và nó đi tới một con người để publish; operator không bao giờ ghép
+tạm một cái thay thế từ các mảnh. Một node mà ứng dụng sở hữu hợp lệ, chẳng hạn một canvas, không
+phải khoảng trống Grammar và không bao giờ làm phát mã ấy.
+
+## Phương án bị phản chứng trước khi được chọn
+
+Phản chứng tấn công vào tính phù hợp với nghiệp vụ và backend, thứ bậc, mật độ nội dung, phản hồi
+hành động, đường phục hồi, dòng chảy responsive, sức chịu nội dung, bàn phím và focus, khả năng tiếp
+cận, tính nhất quán của họ, khả năng đảo ngược và rò rỉ quyền sở hữu, và mỗi đòn tấn công đều rơi vào
+biên nhận kèm phán quyết của nó. Một hướng còn vô hiệu chừng nào còn một mâu thuẫn nghiệp vụ áp dụng
+được, một rò rỉ owner, một Grammar tự chế, một lỗi responsive, một lỗi tiếp cận, một trạng thái bất
+lợi chưa giải quyết hay một phương án đảo ngược mạnh hơn về bản chất. Dưới `refine`, các phương án là
+những nước đi ở cấp phần tử bên trong cấu trúc đã duyệt, không bao giờ là một cấu trúc mới. Khi
+phương án duy nhất chết dưới một đòn tấn công, lần chạy dừng với `NO_VIABLE_DIRECTION`; khi nhiều
+phương án cùng sống, `DIRECTION_CHOICE_REQUIRED` chọn cái sống sót qua nhiều đòn nhất, trừ khi người
+dùng giữ quyền chọn.
+
+## Ranh giới
+
+Context chỉ đọc. Operator chỉ ghi `response/` của nhánh mình: biên nhận quyết định, bản liệt kê
+coverage, các trang phương án đã render và `response.json`. Nó không sửa source sản phẩm hay source
+thẩm quyền, không bịa hành vi nghiệp vụ, backend, kiến trúc, xác thực, lưu trữ hay dữ liệu, không
+publish Grammar dùng chung, không khởi động hay cấu hình lại dịch vụ runtime, và không tuyên bố rằng
+implementation, cổng chất lượng thị giác hay một lượt UAT đã qua.
+
+## Hình là thứ operator tự xét, không chờ yêu cầu
+
+Một tấm hình là quyết định composition như mọi quyết định khác: khi một ứng viên để lại vùng đọc lên
+thấy trống (hero không có chủ thể, empty state chỉ có một câu, hàng card mà chữ không gánh nổi chiều
+rộng), operator thêm hình làm theo đúng một claim của hướng và ghi lý do vào bảng `## Images`. Nó
+không chờ người nói, và cũng không trang trí: vùng mà chữ và Grammar object đã gánh được thì không
+thêm hình, và hình không bao giờ mã hoá claim mà lời hứa nghiệp vụ không hề nêu. Asset và prompt nằm
+dưới `response/artifacts/images/`; `frontend.source.apply` ghi chúng cùng write set đã khai.
+
+## Context
+
+| Alias | Bind | Bắt buộc |
+| --- | --- | --- |
+| `@grammar/core` | Grammar đã publish như app đang bind resolve ra; các composition mà một hướng được phép ràng | có |
+| `@knowledge/ui/composition` | các khẳng định mà biên nhận phát ra phải thoả, `COVERAGE-1` là khẳng định về toàn bộ biên nhận | có |
+| `@workspaces/fe` | checkout frontend được route, đọc ở head đóng băng; hiện trạng là bằng chứng, không bao giờ là hướng được yêu cầu | có |
+| `@knowledge/grammars/starci` | họ Core được kỳ vọng hiện thực hoá Common ra sao; luật về Grammar, không phải chính Grammar | không |
+| `@worktrees/uat/<flow>/<case>` | quan sát hành vi, UX và UI của lần trước kèm ảnh chụp; bằng chứng và phản chứng, một lần pass cũ không phải thẩm quyền hiện tại | không |
+
+## Đầu vào
+
+| Kind | Từ đâu | Bắt buộc |
+| --- | --- | --- |
+| `business-promise-authority` | `business.decide`; bắt buộc với `new`, và với `reconstruct` khi tập trạng thái đổi | không |
+| `backend-source-application` | `backend.source.apply`; bắt buộc khi một contract dữ liệu đổi | không |
+| `architecture-decision` | `architecture.decide`; bắt buộc khi một ranh giới đổi | không |
+| `frontend-direction-decision` | một lần chạy `frontend.direction.decide` trước trên cùng target, đọc khi chạy lại | không |
+
+## Yêu cầu
+
+| Field | Kiểu | Mặc định | Hỏi |
+| --- | --- | --- | --- |
+| `target` | id | — | Đúng một route, page, layout, modal, drawer, flow, block hay component mà hướng này nhắm tới |
+| `intent` | choice | modify | create, modify, audit-repair hay reconcile; `create` đi cùng change level `new` và chỉ đi cùng nó |
+| `changeLevel` | choice | — | new, reconstruct hay refine; một lượt audit phải kết thúc bằng bề mặt pass là reconstruct |
+| `ownerCeiling` | choice | surface-and-nested-layouts | surface-only, surface-and-nested-layouts hay ancestor-layouts-authorized |
+| `candidates` | number 1–3 | 1 | Hình thành bao nhiêu hướng; nhiều hơn một chỉ khi muốn so sánh |
+| `preview` | choice | no | yes thì render phương án duy nhất thành một trang xem được |
+| `references` | list | [] | Tham chiếu ngoài do người dùng cấp; nghiên cứu có giới hạn chỉ chạy khi ô này rỗng |
+| `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 `DIRECTION_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 `frontend-direction-decision` khi chạy lại, @workspaces/fe ở head đóng băng | — | `INVALID_INPUT`, `SOURCE_DRIFT`, `NO_PROGRESS` |
+| 2 | Soát lời yêu cầu: route, scope, change level, trần owner | `target`, `intent`, `changeLevel`, `ownerCeiling` | @workspaces/fe ở head đóng băng, @tools/git | — | `ROUTE_UNVERIFIED`, `SCOPE_UNFROZEN`, `CHANGE_LEVEL_AMBIGUOUS`, `OWNER_CEILING_INVALID` |
+| 3 | Bind các đầu vào mà change level đòi | `changeLevel` | đầu vào `business-promise-authority`, `backend-source-application` và `architecture-decision` | — | `BUSINESS_REQUIRED`, `BACKEND_REQUIRED`, `ARCHITECTURE_REQUIRED` |
+| 4 | Quan sát context đang có | — | @workspaces/fe (artifact trực tiếp của target, hoặc host được uỷ quyền và họ sản phẩm khi target chưa tồn tại), @worktrees/uat/<flow>/<case> nếu có | — | `EVIDENCE_MISSING` |
+| 5 | Biên một UI contract và coverage của nó | — | @knowledge/ui/composition, đầu vào `business-promise-authority` nếu có, context đã quan sát | `response/data/coverage.json` | `SCOPE_UNFROZEN` |
+| 6 | Đi tìm tham chiếu ngoài, có giới hạn | `references`, `changeLevel` | @knowledge/ui/composition (khoảng trống mà nghiên cứu phải lấp), @tools/websearch | — | `REFERENCE_EVIDENCE_EXHAUSTED` |
+| 7 | Hình thành các phương án | `candidates` | UI contract vừa biên | — | `NO_VIABLE_DIRECTION` |
+| 8 | Áp bộ lọc Grammar | `ownerCeiling` | @grammar/core (component sở hữu gì và có prop nào), @knowledge/grammars/starci | — | `GRAMMAR_REQUIRED` |
+| 9 | Render bằng chứng quyết định và hình đã tự xét | `candidates`, `preview` | các phương án còn sống, @knowledge/grammars/starci | `response/artifacts/<candidateId>.html`, `response/artifacts/images/<slot>.png`, @tools/visualize, @tools/imagegen | — |
+| 10 | Phản chứng | — | các phương án, đầu vào `business-promise-authority` và `backend-source-application`, `response/data/coverage.json` | — | `NO_VIABLE_DIRECTION` |
+| 11 | Quyết | `selectionPolicy`, `approval` | bảng phản chứng | — | `DIRECTION_CHOICE_REQUIRED` |
+| 12 | Phát | — | mọi thứ ở trên | `response/response.md`, `response/response.json` | — |
+
+Bước 9 chỉ render khi có nhiều hơn một phương án được hình thành hoặc `preview` là yes; một phương án
+duy nhất dưới mặc định không sinh trang nào và dựa vào bước 10. Dưới `automatic`,
+`DIRECTION_CHOICE_REQUIRED` chọn phương án sống sót qua nhiều đòn tấn công nhất và ghi lại bảng; dưới
+`approval-required` nó dừng và người dùng quay lại với `approval`. Biên nhận uỷ quyền cho domain kế
+tiếp resolve và triển khai bên trong trần owner đã đóng băng, và không chứng minh gì về việc kết quả
+render ra sao.
+
+## Đầu ra
+
+| Kind | File | Kiểu | Bắt buộc |
+| --- | --- | --- | --- |
+| `frontend-direction-decision` | `response/response.md` | md | có |
+| `ui-coverage` | `response/data/coverage.json` | data | có |
+| `candidates` | `response/artifacts/<candidateId>.html` | artifact | không |
+| `direction-image` | `response/artifacts/images/<slot>.png` | artifact | không |
+
+## Dừng
+
+| Code | Xử lý |
+| --- | --- |
+| `INVALID_INPUT` | terminate |
+| `ROUTE_UNVERIFIED` | terminate |
+| `SOURCE_DRIFT` | terminate |
+| `SCOPE_UNFROZEN` | terminate |
+| `CHANGE_LEVEL_AMBIGUOUS` | terminate |
+| `OWNER_CEILING_INVALID` | terminate |
+| `BUSINESS_REQUIRED` | terminate |
+| `BACKEND_REQUIRED` | terminate |
+| `ARCHITECTURE_REQUIRED` | terminate |
+| `GRAMMAR_REQUIRED` | terminate |
+| `EVIDENCE_MISSING` | terminate |
+| `REFERENCE_EVIDENCE_EXHAUSTED` | terminate |
+| `NO_VIABLE_DIRECTION` | terminate |
+| `DIRECTION_CHOICE_REQUIRED` | fallback |
+| `NO_PROGRESS` | terminate |
+
+## Kế tiếp
+
+| Khi | Operator |
+| --- | --- |
+| hướng đã quyết; mọi hướng đều resolve giá trị trình bày trước khi ghi source | `frontend.presentation.resolve` |
+| một component của họ mà hướng cần chưa được publish, nên một người publish nó rồi chính hướng ấy chạy lại | `frontend.direction.decide` |

package/operators/frontend-direction-decide/self-test.mjs

@@ -0,0 +1,226 @@
+// Proves validate.mjs on a synthetic session branch: one conforming branch under the defaults
+// (modify, reconstruct, one candidate, automatic), one three-candidate branch that takes the
+// DIRECTION_CHOICE_REQUIRED fallback, one blocked on the same code under approval-required, 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 { validateDirectionStep } from './validate.mjs';
+
+const HEAD = '0f1e2d3c4b5a69788796a5b4c3d2e1f009182736';
+const NAMES = ['one-column', 'split-view', 'stepper'];
+
+const coverage = ({ regions = 2, actions = 1 } = {}) => ({
+  directionId: 'plan-picker',
+  actions: [{ action: 'choose a plan', pointerRoute: 'the plan card', keyboardRoute: 'tab to the card, enter', states: ['pending', 'confirmed'], pendingPaths: [{ path: 'server accepts', settlement: 'the confirmed plan replaces the picker' }] }].slice(0, actions),
+  regions: [
+    { region: 'offer', idiomRef: 'idioms#offer-block', compositionRef: '@grammar/core#SurfaceCard' },
+    { region: 'decision', idiomRef: 'idioms#decision-bar', compositionRef: '@grammar/core#SurfaceListCard' },
+  ].slice(0, regions),
+  states: [{ meaning: 'empty', carrier: 'the offer region' }, { meaning: 'pending', carrier: 'the decision button' }],
+  responsive: [{ branch: 'narrow', owner: 'the page shell' }],
+});
+
+function responseMd({
+  intent = 'modify', changeLevel = 'reconstruct', ownerCeiling = 'surface-and-nested-layouts',
+  classification = 'dominant', policy = 'automatic', selected = 'one-column', candidates = 1,
+  selectedFails = false, rejectAll = true, references = 0, fallbacks = [],
+} = {}) {
+  const formed = NAMES.slice(0, candidates);
+  const attacks = formed.map((id) => `| content stress | \`${id}\` | ${selectedFails && id === selected ? 'fails' : 'holds'} | the widest plan name still fits at 360px |`);
+  const others = rejectAll ? formed.filter((id) => id !== selected).map((id) => `| \`${id}\` | it loses the offer above the fold on the narrow branch |`) : [];
+  const refRows = references ? ['| a public plan picker | https://example.com/plans | it settles nothing about entitlement |'] : [];
+  return `# frontend-direction-decision — plan-picker
+
+## Decision
+
+| Field | Value |
+| --- | --- |
+| Direction id | \`plan-picker\` |
+| Target | \`/plans\` |
+| Intent | \`${intent}\` |
+| Change level | \`${changeLevel}\` |
+| Owner ceiling | \`${ownerCeiling}\` |
+| Classification | \`${classification}\` |
+| Selection policy | \`${policy}\` |
+| Selected candidate | \`${selected}\` |
+
+## Observed
+
+| Item | Evidence |
+| --- | --- |
+| what the plans route renders today | \`app/plans/page.tsx:1-64@${HEAD}\` |
+
+## UI contract
+
+| Element | Kind | Responsibility |
+| --- | --- | --- |
+| \`offer\` | region | names the offer and its price |
+| \`decision\` | region | carries the choice and its confirmation |
+| choose a plan | action | the actor picks one plan and the surface answers |
+| empty | state | no plan is offered yet |
+| pending | state | the choice is settling |
+| narrow | responsive | the two regions stack below the breakpoint |
+
+## Coverage
+
+| Concern | Enumerated |
+| --- | --- |
+| Actions | one action with its routes and one settled pending path |
+| Regions | two regions, each with one idiom and one composition |
+| States | two meanings on two carriers |
+| Responsive | one branch owned by the page shell |
+
+## References
+
+| Source | URL | Limitation |
+| --- | --- | --- |
+${refRows.join('\n')}
+
+## Images
+
+| Slot | Why | Claim | File |
+| --- | --- | --- | --- |
+
+## Falsification
+
+| Attack | Candidate | Verdict | Evidence |
+| --- | --- | --- | --- |
+${attacks.join('\n')}
+
+## Why not the others
+
+| Candidate | Rejected because |
+| --- | --- |
+${others.join('\n')}
+
+## Fallbacks taken
+
+| Code | Action |
+| --- | --- |
+${fallbacks.map((c) => `| \`${c}\` | the candidate that survived the most attacks was selected |`).join('\n')}
+`;
+}
+
+const requestJson = ({ extra = {} } = {}) => ({
+  schemaVersion: 9,
+  operatorId: 'frontend.direction.decide',
+  step: 2,
+  parallel: 1,
+  sessionId: 's-test',
+  contexts: [{ alias: '@workspaces/fe', head: HEAD }, { alias: '@grammar/core', head: null }, { alias: '@knowledge/ui/composition', head: null }],
+  requirements: {
+    target: '/plans',
+    intent: 'modify',
+    changeLevel: 'reconstruct',
+    ownerCeiling: 'surface-and-nested-layouts',
+    candidates: 1,
+    preview: 'no',
+    references: [],
+    selectionPolicy: 'automatic',
+    approval: null,
+    resume: null,
+    ...extra,
+  },
+  inputs: { 'business-promise-authority': 'step-1/parallel-1/response/response.md' },
+  resume: null,
+});
+
+const responseJson = ({ status = 'done', stop, fields, fallbacks = [], next = ['frontend.presentation.resolve'] } = {}) => ({
+  schemaVersion: 9,
+  operatorId: 'frontend.direction.decide',
+  step: 2,
+  parallel: 1,
+  status,
+  ...(stop ? { stop } : {}),
+  fallbacks,
+  fields: fields ?? { 'frontend-direction-decision': 'response/response.md', 'ui-coverage': 'response/data/coverage.json' },
+  commits: [],
+  next,
+});
+
+function writeBranch(files) {
+  const session = mkdtempSync(path.join(tmpdir(), 'fe-direction-session-'));
+  const branch = path.join(session, 'step-2', 'parallel-1');
+  for (const d of ['request', 'response/data', 'response/artifacts']) mkdirSync(path.join(branch, d), { recursive: true });
+  mkdirSync(path.join(session, 'step-1', 'parallel-1', 'response'), { recursive: true });
+  writeFileSync(path.join(session, 'step-1', 'parallel-1', 'response', 'response.md'), '# business-promise-authority — plans\n');
+  writeFileSync(path.join(session, 'state.json'), JSON.stringify({ id: 's-test', chain: [['1/1'], ['2/1']], steps: { '1/1': 'business.decide', '2/1': 'frontend.direction.decide' }, current: '2/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/coverage.json': coverage(),
+});
+
+const threeCandidates = ({ policy = 'automatic', approval = null, extraResponse = {}, md = {} } = {}) => ({
+  'request/request.json': requestJson({ extra: { candidates: 3, selectionPolicy: policy, approval } }),
+  'response/response.json': responseJson({
+    fallbacks: policy === 'automatic' ? ['DIRECTION_CHOICE_REQUIRED'] : [],
+    fields: { 'frontend-direction-decision': 'response/response.md', 'ui-coverage': 'response/data/coverage.json', candidates: NAMES.map((n) => `response/artifacts/${n}.html`) },
+    ...extraResponse,
+  }),
+  'response/response.md': responseMd({ policy, candidates: 3, fallbacks: policy === 'automatic' ? ['DIRECTION_CHOICE_REQUIRED'] : [], ...md }),
+  'response/data/coverage.json': coverage(),
+  ...Object.fromEntries(NAMES.map((n) => [`response/artifacts/${n}.html`, `<!doctype html><title>${n}</title>`])),
+});
+
+async function expectValid(files, label) {
+  const { branch, session } = writeBranch(files);
+  const { errors } = await validateDirectionStep(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 validateDirectionStep(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 withCoverage = (change) => { const c = coverage(); change(c); return { ...baseline(), 'response/data/coverage.json': c }; };
+
+await expectValid(baseline(), 'defaults (modify, reconstruct, one candidate, automatic)');
+await expectValid(threeCandidates(), 'three candidates, the choice taken as a fallback');
+await expectValid(threeCandidates({ policy: 'approval-required', approval: 'one-column' }), 'three candidates approved by the person');
+await expectValid({
+  'request/request.json': requestJson({ extra: { candidates: 3, selectionPolicy: 'approval-required' } }),
+  'response/response.json': responseJson({ status: 'blocked', stop: 'DIRECTION_CHOICE_REQUIRED', next: [], fields: { candidates: NAMES.map((n) => `response/artifacts/${n}.html`) } }),
+  ...Object.fromEntries(NAMES.map((n) => [`response/artifacts/${n}.html`, `<!doctype html><title>${n}</title>`])),
+}, 'DIRECTION_CHOICE_REQUIRED terminates under approval-required');
+
+await expectError({ ...baseline(), 'request/request.json': requestJson({ extra: { intent: 'create' } }) }, 'intent create requires changeLevel new', 'create without new');
+await expectError({ ...baseline(), 'request/request.json': requestJson({ extra: { candidates: 4 } }) }, 'candidates must be 1, 2 or 3', 'four candidates');
+await expectError({ ...baseline(), 'request/request.json': requestJson({ extra: { approval: 'one-column' } }) }, 'approval is bound under automatic policy', 'approval under automatic');
+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: { changeLevel: '' } }) }, 'required field changeLevel has no value', 'missing change level');
+await expectError({ ...baseline(), 'request/request.json': requestJson({ extra: { candidates: 2 } }) }, 'more than one candidate was formed but none was rendered', 'comparison without pages');
+await expectError({ ...baseline(), 'request/request.json': requestJson({ extra: { preview: 'yes' } }) }, 'preview was asked for but no candidate page was rendered', 'preview without a page');
+await expectError({ ...baseline(), 'response/response.json': responseJson({ fields: { 'frontend-direction-decision': 'response/response.md', 'ui-coverage': 'response/data/coverage.json', candidates: 'response/artifacts/one-column.html' } }), 'response/artifacts/one-column.html': '<!doctype html>' }, 'one candidate under no preview renders no page', 'unasked preview page');
+await expectError({ ...baseline(), 'response/response.md': responseMd({ changeLevel: 'refine' }) }, 'Change level refine differs from the request', 'receipt and request disagree on the change level');
+await expectError({ ...baseline(), 'request/request.json': requestJson({ extra: { changeLevel: 'refine' } }), 'response/response.md': responseMd({ changeLevel: 'refine' }) }, 'a refine is classified locked-refine', 'refine classified dominant');
+await expectError({ ...baseline(), 'request/request.json': requestJson({ extra: { changeLevel: 'refine' } }), 'response/response.md': responseMd({ changeLevel: 'refine', classification: 'locked-refine', references: 1 }) }, 'a refine works from the family idioms alone', 'refine that researched');
+await expectError({ ...baseline(), 'request/request.json': requestJson({ extra: { references: ['https://example.com/plans'] } }) }, 'the person supplied references and none of them is recorded', 'supplied reference dropped');
+await expectError({ ...baseline(), 'response/response.md': responseMd({ selectedFails: true }) }, 'fails an attack, so the direction is not decided', 'selected candidate fails an attack');
+await expectError({ ...threeCandidates(), 'response/response.md': responseMd({ candidates: 3, rejectAll: false, fallbacks: ['DIRECTION_CHOICE_REQUIRED'] }) }, 'is not rejected by name', 'unselected candidate not rejected');
+await expectError({ ...baseline(), 'response/response.md': responseMd({ candidates: 2 }).replace('| `split-view` | it loses', '| `absent` | it loses') }, 'Falsification covers 2 candidates, the request asked for 1', 'more candidates than asked');
+await expectError({ ...threeCandidates({ policy: 'approval-required', approval: 'split-view' }) }, 'but approval names split-view', 'approval names another candidate');
+await expectError({ ...threeCandidates({ policy: 'approval-required' }) }, 'approval-required with no approval cannot end done', 'approval-required decided without an approval');
+await expectError(withCoverage((c) => { c.regions = c.regions.slice(0, 1); }), 'COVERAGE-1: region is not covered: decision', 'region uncovered');
+await expectError(withCoverage((c) => { c.actions = []; }), 'COVERAGE-1: actions must enumerate every declared action', 'actions uncovered');
+await expectError(withCoverage((c) => { c.states[1].carrier = 'the offer region'; }), 'COVERAGE-1: two meanings share one carrier', 'two meanings on one carrier');
+await expectError(withCoverage((c) => { c.actions[0].pendingPaths[0].settlement = ''; }), 'pending path without a settlement', 'unsettled pending path');
+await expectError(withCoverage((c) => { c.directionId = 'other-picker'; }), 'differs from the receipt', 'coverage names another direction');
+await expectError({ ...baseline(), 'response/data/coverage.json': null, 'response/response.json': responseJson({ fields: { 'frontend-direction-decision': 'response/response.md' } }) }, 'required output ui-coverage is not in fields', 'missing required output');
+await expectError({ ...baseline(), 'response/response.md': responseMd().replace('## Observed', '## Observations') }, 'missing section ^## Observed$', 'receipt section renamed');
+await expectError({ ...baseline(), 'response/response.json': responseJson({ status: 'blocked', stop: 'DIRECTION_CHOICE_REQUIRED', next: [] }) }, 'has disposition fallback under these requirements', 'terminating on the choice under automatic');
+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.direction.decide self-test: 4 valid branches, 24 rejected mutations\n');