@starci/skills 1.1.0

package/operators/business-decide/operator.md

@@ -0,0 +1,176 @@
+# business.decide
+
+## Job
+
+Decide and publish one evidence-backed business promise as durable backend-owned authority, frozen
+behind a complete promise-to-enforcement coverage matrix, or reconcile that published head against
+the source that was actually delivered.
+
+## Two modes, one head
+
+`mode` decides which half of this operator runs. Under `model` the promise is modelled and the
+coverage matrix is frozen: steps 4, 5 and 6 run and the branch writes
+`response/data/coverage-matrix.json`. Under `reconcile` nothing is modelled again; step 7 compares the
+head that was already published against the source a backend run delivered, and the Input
+`backend-source-application` is required in that mode, because a reconciliation with no delivered source
+is an opinion about code nobody read. The Inputs table marks it optional because the requirement is
+conditional, and `validate.mjs` refuses a `reconcile` branch whose request does not bind it. Both
+modes end at the same place: one head under `@worktrees/businesses/<featureId>` and one
+`response/data/model.json` that says exactly what that head now holds.
+
+## A first run starts from the person's promise
+
+A feature that no source implements yet has no fact claim by construction. On a first run under mode
+model, the promise the person stated in `promise` is recorded as the one intent claim, bound to
+`request/request.json#requirements.promise` instead of a source line, and the model is built from it;
+`EVIDENCE_MISSING` applies to a fact claim without a file behind it, never to the intent of a promise
+that is being decided for the first time. Every enforcing row of the coverage matrix still rests on a
+fact claim, so a greenfield head publishes with its enforcing rows open, which is what `pending` means.
+
+## Separate the claim before modelling it
+
+Modelling begins by separating every observation into fact, intent, example, unknown, or
+contradiction, and that separation is written to `response/data/claims.json` before anything is
+modelled from it. The separation exists to make one substitution impossible: an example, a
+screenshot, or an owner's intent illustrates a promise, and only an observed fact in routed source
+proves that the promise is enforced. A coverage row that asserts enforcement therefore cites at least
+one fact claim, and every fact claim binds the observed source head. A claim that cites a source
+nobody bound is invalid input rather than a warning, because an unbound citation cannot be told apart
+from an invented one. Two claims that disagree about the same behaviour are never averaged into a
+middle reading; the contradiction stops the invocation and returns to its owner.
+
+## No promise without coverage
+
+A promise is publishable only when every dimension the request declared carries exactly one
+disposition, and every consumer and lifecycle branch the operator discovered is disposed by name.
+`dimensions` defaults to the dimensions of the previous head, which is why it is required on a first
+run: the first publication is the one that decides what the promise is even accountable for. That
+rule exists because "full access" was modelled, implemented, and published while its course,
+community, blog, AI, mock-interview, legacy-sale, quota, settlement, renewal, cancellation, and
+recovery consumers had never all been proved. The promise was true in the offer and false at the
+guard. Four prohibitions carry the repair, and each is enforced rather than advised. A discovered
+consumer with no matrix row is `CONSUMER_UNPROVEN`. A mandatory dimension, meaning actor and
+eligibility, offer entry, read entry, purchase side effect, settlement, idempotency, entitlement
+consumer, and denial, can never be marked not applicable when it was declared. A dimension whose
+branch was observed in source can never be marked not applicable either, because it was found, so it
+applies. A preserve or replace disposition without a negative proof is rejected, since positive proof
+alone shows the promise is granted and never that it is denied when it should be.
+
+## The dispositions and what each one must carry
+
+`preserve` keeps the existing enforcement and carries owner, source, positive proof, negative proof,
+and one fact claim. `replace` changes the enforcement and carries the same substance for the new
+path. `retire` closes a path on purpose and carries owner, source, proof the path is closed, and one
+fact claim. `defer` postpones a branch to a named owner, carries a deferral reference, and carries no
+proof at all, because proof for work that has not happened is the most convincing kind of false pass.
+`not-applicable` states the branch cannot occur and carries nothing: no owner, no source, no proof, no
+consumer, no claim. `defer` is a disposition, so a deferred branch does not block publication; what
+blocks publication is silence.
+
+## One flat authority root
+
+One feature owns exactly one head directory, `<businesses root>/features/<featureId>`, whose
+`model.json` is the head, and step 8 takes an exclusive lease on that alias before it writes. Two
+branches of the same step may not publish the same feature. `features/` is the only segment between
+the root and a feature: a project segment inserted below the root starts a second authority tree that
+later readers never find, so any head that is not exactly `features/<featureId>` is refused. The head
+is classified absent, fresh, or stale against the frozen evidence and the frozen source head, and
+that classification decides which lifecycle transition is legal. Rejection preserves lineage by
+naming the previous head rather than erasing it, and `implemented` is never published on the strength
+of a plan: delivered source is compared against the frozen matrix first, under `reconcile`.
+
+## Boundary
+
+Context is read-only apart from the one feature head. The operator writes only `response/` of its own
+branch, `response.md`, `response/data/claims.json`, `response/data/coverage-matrix.json` under mode
+model, `response/data/model.json` and `response.json`, plus the one feature head under
+`@worktrees/businesses/<featureId>`. It never publishes a promise while a discovered consumer or
+lifecycle branch carries no disposition, promotes an example, a screenshot, or an intent claim into
+product truth, invents an actor, entitlement, quota, payment, settlement, or lifecycle behaviour the
+evidence does not state, advances a head through a transition the lifecycle does not allow, or writes
+a head below a project segment under the businesses root. It does not modify product source,
+architecture authority, frontend authority, or backend implementation, and it never claims that an
+implementation, a quality gate, or a UAT run has passed.
+
+## Context
+
+| Alias | Bind | Required |
+| --- | --- | --- |
+| `@worktrees/businesses/<featureId>` | the promise head and its lifecycle state, by content address from the registry; the one place this operator writes outside its branch | yes |
+| `@workspaces/be` | the routed backend checkout read at the frozen head; every fact claim cites it by path, line range, and head | yes |
+
+## Inputs
+
+| Kind | From | Required |
+| --- | --- | --- |
+| `architecture-decision` | `architecture.decide`; architecture evidence, never a source of business behaviour | no |
+| `backend-source-application` | `backend.source.apply`; the delivered source a reconciliation reads, required under mode `reconcile` and refused otherwise | no |
+
+## Requirements
+
+| Field | Type | Default | Ask |
+| --- | --- | --- | --- |
+| `featureId` | id | — | The one feature the promise belongs to |
+| `mode` | choice | model | `model` decides and publishes the promise; `reconcile` compares the published head against delivered source |
+| `promise` | prompt | the promise the previous head states | The promise in the person's words; required on a first run, when no head exists yet, and recorded as the intent claim bound to `request/request.json#requirements.promise` |
+| `targetState` | choice | — | `pending`, `in-progress`, `implemented` or `rejected` for the published head |
+| `dimensions` | list | the dimensions of the previous head | The coverage surface this promise is accountable for; required on a first run, because no previous head declares it |
+| `approval` | id | null | The owner approval the transition needs, supplied on resume after `APPROVAL_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`, `mode` | `request/request.json`, @workspaces/be at the frozen head | — | `INVALID_INPUT`, `SOURCE_DRIFT`, `NO_PROGRESS` |
+| 2 | Normalize the evidence into claims | — | @workspaces/be, every observation with its role, path, line range and head, input `architecture-decision` when present as evidence only, @tools/git | `response/data/claims.json` | `EVIDENCE_MISSING`, `CONTRADICTION_UNRESOLVED` |
+| 3 | Check the published head and the transition authority | `featureId`, `targetState`, `approval` | @worktrees/businesses/<featureId>: the current head, its state and its frozen evidence | — | `LIFECYCLE_TRANSITION_INVALID`, `AUTHORITY_CONFLICT`, `APPROVAL_REQUIRED` |
+| 4 | Model the promise, its actor and its eligibility, under mode model: fact claims carry every enforcing row, the intent claim carries the promise itself | `promise` | `response/data/claims.json`, @workspaces/be at the frozen head, @tools/websearch | — | `EVIDENCE_MISSING` |
+| 5 | Freeze the coverage matrix, under mode model | `dimensions` | `response/data/claims.json`, @workspaces/be and the surface it discovers | `response/data/coverage-matrix.json` | `COVERAGE_INCOMPLETE`, `CONSUMER_UNPROVEN` |
+| 6 | Dispose legacy coexistence, under mode model | — | `response/data/coverage-matrix.json`: the legacy create, read and settle rows and their proof | — | `CONTRADICTION_UNRESOLVED` |
+| 7 | Reconcile against delivered source, under mode reconcile | — | input `backend-source-application`, @workspaces/be at the frozen head, the coverage matrix frozen at the published head | — | `RECONCILIATION_DISCREPANCY` |
+| 8 | Publish one head under an exclusive lease | — | `response/data/claims.json`, @worktrees/businesses/<featureId> at the previous head | @worktrees/businesses/<featureId> as the new model.json head, `response/data/model.json`, @tools/sourcewrite | `SOURCE_DRIFT` |
+| 9 | Emit | — | everything above | `response/response.md`, `response/response.json` | — |
+
+Legacy create, read, and settle each take their own row when they are declared: a new sale path may
+retire legacy creation only while already-purchased rights stay readable and pending legacy
+settlement still completes, and the retirement carries proof that the creation path is closed. The
+matrix is content addressed and its fingerprint travels in the binding, so backend implementation,
+quality integration, and UAT can prove they consumed the same matrix rather than a paraphrase of it.
+A resume begins again at step 1, reuses only unchanged fingerprinted observations, and consumes the
+exact delta; republished evidence arrives as a new evidence fingerprint, because the same fingerprint
+cannot yield a different answer.
+
+## Outputs
+
+| Kind | File | Type | Required |
+| --- | --- | --- | --- |
+| `business-promise-authority` | `response/response.md` | md | yes |
+| `claims` | `response/data/claims.json` | data | yes |
+| `coverage-matrix` | `response/data/coverage-matrix.json` | data | no |
+| `model` | `response/data/model.json` | data | yes |
+
+## Stops
+
+| Code | Disposition |
+| --- | --- |
+| `INVALID_INPUT` | terminate |
+| `SOURCE_DRIFT` | terminate |
+| `NO_PROGRESS` | terminate |
+| `EVIDENCE_MISSING` | terminate |
+| `CONTRADICTION_UNRESOLVED` | terminate |
+| `LIFECYCLE_TRANSITION_INVALID` | terminate |
+| `AUTHORITY_CONFLICT` | terminate |
+| `APPROVAL_REQUIRED` | terminate |
+| `COVERAGE_INCOMPLETE` | terminate |
+| `CONSUMER_UNPROVEN` | terminate |
+| `RECONCILIATION_DISCREPANCY` | terminate |
+
+## Next
+
+| When | Operator |
+| --- | --- |
+| the promise is published and a frontend surface must carry it | `frontend.direction.decide` |
+| the promise is published and a backend contract must carry it | `backend.source.apply` |
+| the promise needs boundaries and data ownership decided before it can be enforced | `architecture.decide` |
+| the head is reconciled against the delivered source and the delivery may be published | `git.publish` |

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

@@ -0,0 +1,174 @@
+# business.decide
+
+## Việc
+
+Quyết và publish một lời hứa nghiệp vụ có bằng chứng thành thẩm quyền bền do backend sở hữu, đóng
+băng sau một ma trận phủ đầy đủ từ lời hứa tới điểm thực thi, hoặc đối chiếu chính head đã publish ấy
+với source thực sự đã được giao.
+
+## Hai chế độ, một head
+
+`mode` quyết định nửa nào của operator này chạy. Dưới `model`, lời hứa được mô hình hoá và ma trận
+phủ được đóng băng: bước 4, 5 và 6 chạy, và nhánh ghi `response/data/coverage-matrix.json`. Dưới
+`reconcile` không mô hình lại gì cả; bước 7 đối chiếu head đã publish với source mà một lượt backend
+đã giao, và Input `backend-source-application` là bắt buộc trong chế độ ấy, vì một cuộc đối chiếu không
+có source đã giao chỉ là ý kiến về đoạn code chưa ai đọc. Bảng Đầu vào ghi nó là tuỳ chọn vì tính bắt
+buộc phụ thuộc chế độ, và `validate.mjs` từ chối một nhánh `reconcile` mà request không ràng nó. Hai
+chế độ kết thúc ở cùng một chỗ: một head dưới `@worktrees/businesses/<featureId>` và một
+`response/data/model.json` nói đúng những gì head ấy đang giữ.
+
+## Lần chạy đầu bắt đầu từ lời hứa của người
+
+Một feature chưa có source hiện thực thì theo định nghĩa không có claim fact. Ở lần chạy đầu dưới chế
+độ model, lời hứa người dùng nêu trong `promise` được ghi thành claim intent duy nhất, ràng vào
+`request/request.json#requirements.promise` thay vì một dòng source, và mô hình dựng từ đó;
+`EVIDENCE_MISSING` áp cho claim fact không có file đứng sau, không bao giờ áp cho intent của một lời
+hứa đang được quyết lần đầu. Mọi hàng enforcing của coverage matrix vẫn phải tựa trên claim fact, nên
+head greenfield publish với các hàng enforcing còn mở, đó chính là nghĩa của `pending`.
+
+## Tách loại claim trước khi mô hình hoá
+
+Mô hình hoá bắt đầu bằng việc tách mọi quan sát thành fact, intent, example, unknown hay
+contradiction, và cách tách ấy được ghi vào `response/data/claims.json` trước khi có gì được mô hình
+từ nó. Nó tồn tại để một phép thay thế trở thành bất khả: một ví dụ, một ảnh chụp màn hình hay ý định
+của người chủ chỉ minh hoạ lời hứa, còn chỉ một fact quan sát được trong source được route mới chứng
+minh lời hứa đó có người thực thi. Vì vậy một hàng phủ khẳng định có thực thi phải dẫn ít nhất một
+claim fact, và mọi claim fact phải ràng head source đã quan sát. Một claim dẫn nguồn không ai ràng là
+input sai chứ không phải cảnh báo, vì một trích dẫn không ràng thì không phân biệt được với một trích
+dẫn bịa. Hai claim mâu thuẫn về cùng một hành vi không bao giờ được lấy trung bình thành một cách đọc
+ở giữa; mâu thuẫn dừng lượt chạy và trả về cho chủ của nó.
+
+## Không có phủ thì không có lời hứa
+
+Một lời hứa chỉ publish được khi mọi chiều mà request đã khai đều mang đúng một disposition, và mọi
+consumer cùng nhánh vòng đời mà operator phát hiện đều được xử lý đích danh. `dimensions` mặc định
+lấy theo các chiều của head trước, nên nó bắt buộc ở lần chạy đầu: lần publish đầu tiên chính là lần
+quyết định lời hứa phải chịu trách nhiệm về những gì. Luật này có vì "full access" từng được mô hình,
+cài đặt và publish trong khi các consumer khoá học, cộng đồng, blog, AI, phỏng vấn thử, bán legacy,
+quota, tất toán, gia hạn, huỷ và khôi phục chưa từng được chứng minh đủ. Lời hứa đúng ở chỗ chào bán
+và sai ở chỗ guard. Bốn điều cấm gánh phần sửa, và mỗi điều được cưỡng chế chứ không phải khuyên. Một
+consumer đã phát hiện mà không có hàng trong ma trận là `CONSUMER_UNPROVEN`. Một chiều bắt buộc, gồm
+actor và eligibility, offer entry, read entry, purchase side effect, settlement, idempotency,
+entitlement consumer và denial, không bao giờ được đánh không áp dụng khi nó đã được khai. Một chiều
+mà nhánh của nó đã được quan sát trong source cũng không bao giờ được đánh không áp dụng, vì đã tìm
+thấy tức là có áp dụng. Một disposition preserve hay replace mà thiếu negative proof bị từ chối, vì
+chứng minh dương chỉ cho thấy lời hứa được cấp, không bao giờ cho thấy nó bị từ chối đúng lúc phải từ
+chối.
+
+## Các disposition và phần thực chất mỗi loại phải mang
+
+`preserve` giữ nguyên phần thực thi đang có và mang owner, source, positive proof, negative proof và
+một claim fact. `replace` đổi phần thực thi và mang đúng ngần ấy thực chất cho đường mới. `retire`
+đóng một đường có chủ ý và mang owner, source, bằng chứng đường đã đóng, và một claim fact. `defer`
+hoãn một nhánh cho một chủ có tên, mang một tham chiếu hoãn, và không mang bằng chứng nào, vì bằng
+chứng cho việc chưa làm là kiểu pass giả thuyết phục nhất. `not-applicable` nói nhánh không thể xảy
+ra và không mang gì cả: không owner, không source, không proof, không consumer, không claim. `defer`
+là một disposition nên nhánh được hoãn không chặn publish; thứ chặn publish là sự im lặng.
+
+## Một gốc thẩm quyền phẳng
+
+Một feature sở hữu đúng một thư mục head, `<gốc businesses>/features/<featureId>`, mà `model.json`
+trong đó là head, và bước 8 giữ lease độc quyền trên alias ấy trước khi ghi. Hai nhánh của cùng một
+bước không được publish cùng một feature. `features/` là đoạn duy nhất giữa gốc và một feature: chèn
+một đoạn project dưới gốc là sinh ra cây thẩm quyền thứ hai mà người đọc sau không bao giờ tìm ra,
+nên mọi head không đúng `features/<featureId>` đều bị từ chối. Head được phân loại absent, fresh hay
+stale so với bằng chứng đã đóng băng và head source đã đóng băng, và phân loại đó quyết định chuyển
+trạng thái nào hợp lệ. Từ chối vẫn giữ dòng dõi bằng cách nêu tên head trước thay vì xoá nó, và
+`implemented` không bao giờ được publish dựa trên một kế hoạch: source đã giao phải được đối chiếu
+với ma trận đóng băng trước, dưới `reconcile`.
+
+## Ranh giới
+
+Context chỉ đọc, trừ đúng một head feature. Operator chỉ ghi `response/` của nhánh mình, gồm
+`response.md`, `response/data/claims.json`, `response/data/coverage-matrix.json` dưới chế độ model,
+`response/data/model.json` và `response.json`, cùng một head feature dưới
+`@worktrees/businesses/<featureId>`. Nó không bao giờ publish một lời hứa khi còn một consumer hay
+nhánh vòng đời đã phát hiện chưa có disposition, không nâng một ví dụ, một ảnh chụp hay một claim ý
+định thành sự thật sản phẩm, không bịa hành vi actor, entitlement, quota, thanh toán, tất toán hay
+vòng đời mà bằng chứng không nói, không đẩy head qua một chuyển trạng thái vòng đời không cho phép,
+và không ghi head dưới một đoạn project trong gốc businesses. Nó không sửa source sản phẩm, thẩm
+quyền kiến trúc, thẩm quyền frontend hay phần cài đặt backend, và không bao giờ tuyên bố rằng một bản
+cài đặt, một cổng chất lượng hay một lượt UAT đã qua.
+
+## Context
+
+| Alias | Bind | Bắt buộc |
+| --- | --- | --- |
+| `@worktrees/businesses/<featureId>` | head lời hứa và trạng thái vòng đời của nó, theo địa chỉ nội dung từ registry; nơi duy nhất operator này ghi ngoài nhánh của mình | có |
+| `@workspaces/be` | checkout backend được route, đọc ở head đã đóng băng; mọi claim fact dẫn nó theo path, khoảng dòng và head | có |
+
+## Đầu vào
+
+| Kind | Từ đâu | Bắt buộc |
+| --- | --- | --- |
+| `architecture-decision` | `architecture.decide`; bằng chứng kiến trúc, không bao giờ là nguồn của hành vi nghiệp vụ | không |
+| `backend-source-application` | `backend.source.apply`; source đã giao mà một cuộc đối chiếu phải đọc, bắt buộc dưới chế độ `reconcile` và bị từ chối ngoài chế độ ấy | không |
+
+## Yêu cầu
+
+| Field | Kiểu | Mặc định | Hỏi |
+| --- | --- | --- | --- |
+| `featureId` | id | — | Một feature duy nhất mà lời hứa thuộc về |
+| `mode` | choice | model | `model` quyết và publish lời hứa; `reconcile` đối chiếu head đã publish với source đã giao |
+| `promise` | prompt | the promise the previous head states | Lời hứa bằng lời của người dùng; bắt buộc ở lần chạy đầu khi chưa có head, và được ghi thành claim intent ràng vào `request/request.json#requirements.promise` |
+| `targetState` | choice | — | `pending`, `in-progress`, `implemented` hay `rejected` cho head được publish |
+| `dimensions` | list | the dimensions of the previous head | Bề mặt phủ mà lời hứa này chịu trách nhiệm; bắt buộc ở lần chạy đầu, vì chưa head nào khai nó |
+| `approval` | id | null | Phê duyệt của chủ mà chuyển trạng thái cần, nhập khi chạy lại sau `APPROVAL_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`, `mode` | `request/request.json`, @workspaces/be ở head đóng băng | — | `INVALID_INPUT`, `SOURCE_DRIFT`, `NO_PROGRESS` |
+| 2 | Chuẩn hoá bằng chứng thành claim | — | @workspaces/be, mọi quan sát kèm vai, path, khoảng dòng và head, đầu vào `architecture-decision` nếu có và chỉ như bằng chứng, @tools/git | `response/data/claims.json` | `EVIDENCE_MISSING`, `CONTRADICTION_UNRESOLVED` |
+| 3 | Kiểm head đã publish và thẩm quyền chuyển trạng thái | `featureId`, `targetState`, `approval` | @worktrees/businesses/<featureId>: head hiện tại, trạng thái và bằng chứng đóng băng của nó | — | `LIFECYCLE_TRANSITION_INVALID`, `AUTHORITY_CONFLICT`, `APPROVAL_REQUIRED` |
+| 4 | Mô hình lời hứa, actor và eligibility dưới chế độ model: claim fact gánh mọi hàng enforcing, claim intent gánh chính lời hứa | `promise` | `response/data/claims.json`, @workspaces/be ở head đóng băng, @tools/websearch | — | `EVIDENCE_MISSING` |
+| 5 | Đóng băng ma trận phủ, dưới chế độ model | `dimensions` | `response/data/claims.json`, @workspaces/be và bề mặt nó phát hiện | `response/data/coverage-matrix.json` | `COVERAGE_INCOMPLETE`, `CONSUMER_UNPROVEN` |
+| 6 | Xử lý phần chung sống với legacy, dưới chế độ model | — | `response/data/coverage-matrix.json`: các hàng legacy create, read, settle và bằng chứng của chúng | — | `CONTRADICTION_UNRESOLVED` |
+| 7 | Đối chiếu với source đã giao, dưới chế độ reconcile | — | đầu vào `backend-source-application`, @workspaces/be ở head đóng băng, ma trận phủ đã đóng băng ở head đã publish | — | `RECONCILIATION_DISCREPANCY` |
+| 8 | Publish một head dưới lease độc quyền | — | `response/data/claims.json`, @worktrees/businesses/<featureId> ở head trước | @worktrees/businesses/<featureId> thành model.json head mới, `response/data/model.json`, @tools/sourcewrite | `SOURCE_DRIFT` |
+| 9 | Phát | — | mọi thứ ở trên | `response/response.md`, `response/response.json` | — |
+
+Legacy create, read và settle mỗi thứ giữ một hàng riêng khi chúng được khai: một đường bán mới chỉ
+được retire phần tạo legacy khi quyền đã mua vẫn đọc được và phần tất toán legacy còn treo vẫn hoàn
+tất, và việc retire ấy mang bằng chứng rằng đường tạo đã đóng. Ma trận được địa chỉ theo nội dung và
+fingerprint của nó đi trong binding, nên phần cài đặt backend, phần tích hợp chất lượng và UAT chứng
+minh được rằng chúng tiêu thụ đúng ma trận ấy chứ không phải một bản diễn giải. Chạy lại thì bắt đầu
+lại từ bước 1, chỉ dùng lại quan sát có fingerprint không đổi, và tiêu thụ đúng phần delta; bằng
+chứng publish lại tới dưới dạng một fingerprint bằng chứng mới, vì cùng một fingerprint không thể cho
+một câu trả lời khác.
+
+## Đầu ra
+
+| Kind | File | Kiểu | Bắt buộc |
+| --- | --- | --- | --- |
+| `business-promise-authority` | `response/response.md` | md | có |
+| `claims` | `response/data/claims.json` | data | có |
+| `coverage-matrix` | `response/data/coverage-matrix.json` | data | không |
+| `model` | `response/data/model.json` | data | có |
+
+## Dừng
+
+| Code | Xử lý |
+| --- | --- |
+| `INVALID_INPUT` | terminate |
+| `SOURCE_DRIFT` | terminate |
+| `NO_PROGRESS` | terminate |
+| `EVIDENCE_MISSING` | terminate |
+| `CONTRADICTION_UNRESOLVED` | terminate |
+| `LIFECYCLE_TRANSITION_INVALID` | terminate |
+| `AUTHORITY_CONFLICT` | terminate |
+| `APPROVAL_REQUIRED` | terminate |
+| `COVERAGE_INCOMPLETE` | terminate |
+| `CONSUMER_UNPROVEN` | terminate |
+| `RECONCILIATION_DISCREPANCY` | terminate |
+
+## Kế tiếp
+
+| Khi | Operator |
+| --- | --- |
+| lời hứa đã publish và một bề mặt frontend phải mang nó | `frontend.direction.decide` |
+| lời hứa đã publish và một contract backend phải mang nó | `backend.source.apply` |
+| lời hứa cần quyết ranh giới và quyền sở hữu dữ liệu trước khi thực thi được | `architecture.decide` |
+| head đã được đối chiếu với source đã giao và bản giao có thể được publish | `git.publish` |

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

@@ -0,0 +1,225 @@
+// Proves validate.mjs on a synthetic session branch: one conforming publication of a first head under
+// mode model, one reconcile pass against delivered source, one branch 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 { validateBusinessStep } from './validate.mjs';
+
+const head = 'c'.repeat(40);
+const claimsFingerprint = `sha256:${'a'.repeat(64)}`;
+const coverageFingerprint = `sha256:${'b'.repeat(64)}`;
+const ROOT_REF = '.worktrees/businesses';
+const FEATURE = 'paid-access';
+const CONSUMER = { consumerId: 'course-guard', dimension: 'entitlement-consumer', sourceRef: 'src/course/guard.ts' };
+const DELIVERED = 'step-1/parallel-2/response/response.md';
+
+const DISPOSITIONS = [
+  ['actor-eligibility', 'preserve'], ['offer-entry', 'preserve'], ['read-entry', 'preserve'],
+  ['purchase-side-effect', 'preserve'], ['settlement', 'preserve'], ['idempotency', 'preserve'],
+  ['entitlement-consumer', 'preserve'], ['denial', 'preserve'], ['renewal', 'defer'],
+  ['refund', 'not-applicable'], ['legacy-create', 'retire'], ['legacy-read', 'preserve'],
+  ['legacy-settle', 'preserve'],
+];
+const DIMENSIONS = DISPOSITIONS.map(([d]) => d);
+
+const proof = (name) => `tests/${name}.spec.ts`;
+const row = (dimension, disposition, extra = {}) => {
+  const base = { dimension, disposition, statement: `how ${dimension} is answered`, enforcementOwner: null, sourceRef: null, positiveProofRef: null, negativeProofRef: null, deferralRef: null, consumerIds: [], claimIds: [] };
+  if (disposition === 'preserve' || disposition === 'replace') Object.assign(base, { enforcementOwner: 'entitlement', sourceRef: `src/${dimension}.ts`, positiveProofRef: proof(`${dimension}-granted`), negativeProofRef: proof(`${dimension}-denied`), claimIds: ['c-fact'] });
+  if (disposition === 'retire') Object.assign(base, { enforcementOwner: 'entitlement', sourceRef: `src/${dimension}.ts`, positiveProofRef: proof(`${dimension}-closed`), claimIds: ['c-fact'] });
+  if (disposition === 'defer') Object.assign(base, { deferralRef: `objective:${dimension}-later` });
+  return { ...base, ...extra };
+};
+function coverageMatrix(overrides = {}) {
+  return {
+    featureId: FEATURE,
+    fingerprint: coverageFingerprint,
+    dimensions: DIMENSIONS,
+    discoveredConsumers: [CONSUMER],
+    discoveredLifecycleBranches: ['renewal'],
+    rows: DISPOSITIONS.map(([dimension, disposition]) => row(dimension, disposition, dimension === 'entitlement-consumer' ? { consumerIds: [CONSUMER.consumerId] } : {})),
+    ...overrides,
+  };
+}
+function withRow(dimension, patch) {
+  const matrix = coverageMatrix();
+  matrix.rows = matrix.rows.map((r) => (r.dimension === dimension ? { ...r, ...patch } : r));
+  return matrix;
+}
+const CLAIMS = [
+  { claimId: 'c-fact', kind: 'fact', role: 'the guard that enforces the promise', path: 'src/entitlement/guard.ts', lineStart: 10, lineEnd: 24, sourceHead: head },
+  { claimId: 'c-intent', kind: 'intent', role: "the owner's stated intent", path: 'docs/paid-access.md', lineStart: 3, lineEnd: 9, sourceHead: null },
+];
+const claimsDoc = (overrides = {}) => ({ featureId: FEATURE, sourceHead: head, fingerprint: claimsFingerprint, claims: CLAIMS, ...overrides });
+
+function modelDoc({ mode = 'model', state = 'pending', transition = 'absent->pending', previousHeadRef = null, previousState = null, headRef = `${ROOT_REF}/features/${FEATURE}`, coverage = coverageFingerprint, reconciliation = null } = {}) {
+  return {
+    featureId: FEATURE, mode, headRef, headFingerprint: `sha256:${'d'.repeat(64)}`, state,
+    promise: { statement: 'a paying learner reads every course in the plan', actorStatement: 'a learner with a settled purchase', eligibilityStatement: 'the purchase settled and has not expired' },
+    lineage: { previousHeadRef, previousState, transition },
+    claimsFingerprint, coverageFingerprint: coverage, reconciliation,
+  };
+}
+
+function responseMd({ mode = 'model', state = 'pending', transition = 'absent->pending', previousHead = '—', previousState = '—', coverage = coverageFingerprint, claimsFp = claimsFingerprint, headRef = `${ROOT_REF}/features/${FEATURE}`, dispositions = DISPOSITIONS, reconciliation = [], findings = [], claims = [['c-fact', 'fact'], ['c-intent', 'intent']] } = {}) {
+  const coverageRows = dispositions.map(([dimension, disposition]) => `| \`${dimension}\` | ${disposition} | how ${dimension} is answered | ${dimension === 'entitlement-consumer' ? `\`${CONSUMER.consumerId}\`` : '—'} |`).join('\n');
+  const claimRows = claims.map(([id, kind]) => `| \`${id}\` | ${kind} | what ${id} observes | \`src/entitlement/guard.ts\` | 10-24 | ${kind === 'fact' ? `\`${head}\`` : '—'} |`).join('\n');
+  const reconciliationRows = reconciliation.map(([dimension, delivered, discrepancy]) => `| \`${dimension}\` | ${delivered} | ${discrepancy} |`).join('\n');
+  const findingRows = findings.map(([code, severity, dimension, statement]) => `| \`${code}\` | ${severity} | \`${dimension}\` | ${statement} |`).join('\n');
+  return `# business-promise-authority — ${FEATURE}
+
+The paid access promise, decided from the frozen evidence of the routed backend checkout.
+
+## Binding
+
+| Field | Value |
+| --- | --- |
+| Feature | \`${FEATURE}\` |
+| Mode | ${mode} |
+| Target state | ${state} |
+| Head | \`${headRef}\` |
+| Claims fingerprint | \`${claimsFp}\` |
+| Coverage fingerprint | \`${coverage}\` |
+
+## Promise
+
+| Field | Value |
+| --- | --- |
+| Promise | a paying learner reads every course in the plan |
+| Actor | a learner with a settled purchase |
+| Eligibility | the purchase settled and has not expired |
+
+## Lineage
+
+| Field | Value |
+| --- | --- |
+| Previous head | ${previousHead} |
+| Previous state | ${previousState} |
+| Transition | ${transition} |
+
+## Cited claims
+
+| Claim | Kind | Role | Source | Lines | Head |
+| --- | --- | --- | --- | --- | --- |
+${claimRows}
+
+## Coverage
+
+| Dimension | Disposition | Statement | Consumers |
+| --- | --- | --- | --- |
+${coverageRows}${coverageRows ? '\n' : ''}
+## Reconciliation
+
+| Dimension | Delivered evidence | Discrepancy |
+| --- | --- | --- |
+${reconciliationRows}${reconciliationRows ? '\n' : ''}
+## Findings
+
+| Code | Severity | Dimension | Statement |
+| --- | --- | --- | --- |
+${findingRows}${findingRows ? '\n' : ''}`;
+}
+
+const requestJson = ({ mode = 'model', targetState = 'pending', inputs = {}, extra = {} } = {}) => ({
+  schemaVersion: 9, operatorId: 'business.decide', step: 1, parallel: 1, sessionId: 's-test',
+  contexts: [{ alias: '@workspaces/be', head }, { alias: '@worktrees/businesses/paid-access', head: null }],
+  requirements: { featureId: FEATURE, mode, targetState, dimensions: DIMENSIONS, approval: null, resume: null, ...extra },
+  inputs, resume: null,
+});
+function responseJson({ status = 'done', stop, fallbacks = [], fields = null, next = ['backend.source.apply'] } = {}) {
+  return {
+    schemaVersion: 9, operatorId: 'business.decide', step: 1, parallel: 1, status, ...(stop ? { stop } : {}), fallbacks,
+    fields: fields ?? { 'business-promise-authority': 'response/response.md', claims: 'response/data/claims.json', 'coverage-matrix': 'response/data/coverage-matrix.json', model: 'response/data/model.json' },
+    commits: [], next,
+  };
+}
+
+function writeBranch(files) {
+  const session = mkdtempSync(path.join(tmpdir(), 'business-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 });
+  mkdirSync(path.join(session, 'step-1', 'parallel-2', 'response'), { recursive: true });
+  writeFileSync(path.join(session, DELIVERED), '# backend-source-application — delivered source\n');
+  writeFileSync(path.join(session, 'state.json'), JSON.stringify({ id: 's-test', chain: [['1/1']], steps: { '1/1': 'business.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/claims.json': claimsDoc(),
+  'response/data/coverage-matrix.json': coverageMatrix(),
+  'response/data/model.json': modelDoc(),
+});
+
+async function expectValid(files, label) {
+  const { branch, session } = writeBranch(files);
+  const { errors } = await validateBusinessStep(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 validateBusinessStep(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 RECONCILE_FIELDS = { 'business-promise-authority': 'response/response.md', claims: 'response/data/claims.json', model: 'response/data/model.json' };
+const reconciled = (overrides = {}) => ({
+  ...baseline(),
+  'request/request.json': requestJson({ mode: 'reconcile', targetState: 'implemented', inputs: { 'backend-source-application': DELIVERED } }),
+  'response/response.json': responseJson({ fields: RECONCILE_FIELDS }),
+  'response/response.md': responseMd({ mode: 'reconcile', state: 'implemented', transition: 'in-progress->implemented', previousHead: `\`${ROOT_REF}/features/${FEATURE}\``, previousState: 'in-progress', coverage: coverageFingerprint, dispositions: [], reconciliation: [['entitlement-consumer', '`src/course/guard.ts`', '—']] }),
+  'response/data/coverage-matrix.json': null,
+  'response/data/model.json': modelDoc({ mode: 'reconcile', state: 'implemented', transition: 'in-progress->implemented', previousHeadRef: `${ROOT_REF}/features/${FEATURE}`, previousState: 'in-progress', reconciliation: { deliveredEvidenceRefs: ['src/course/guard.ts'], discrepancies: [] } }),
+  ...overrides,
+});
+
+await expectValid(baseline(), 'a first publication of one feature head under mode model');
+await expectValid(reconciled(), 'a reconcile pass against delivered source');
+await expectValid({ ...baseline(), 'response/response.json': responseJson({ status: 'blocked', stop: 'CONSUMER_UNPROVEN', fields: {}, next: [] }), 'response/response.md': null, 'response/data/claims.json': null, 'response/data/coverage-matrix.json': null, 'response/data/model.json': null }, 'blocked on an undisposed consumer');
+
+await expectError({ ...baseline(), 'response/response.json': { ...responseJson(), stop: 'CONSUMER_UNPROVEN' } }, 'only a blocked response carries a stop', 'done with a stop');
+await expectError({ ...baseline(), 'response/response.json': responseJson({ status: 'blocked', stop: 'MADE_UP_CODE', fields: {}, next: [] }), 'response/response.md': null, 'response/data/claims.json': null, 'response/data/coverage-matrix.json': null, 'response/data/model.json': null }, 'not a registered code', 'unknown stop code');
+await expectError({ ...baseline(), 'response/response.json': responseJson({ fallbacks: ['COVERAGE_INCOMPLETE'] }) }, '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({ status: 'blocked', stop: 'CONSUMER_UNPROVEN', next: [] }) }, 'a blocked branch cannot freeze a coverage matrix', 'blocked while freezing the matrix');
+await expectError({ ...baseline(), 'request/request.json': requestJson({ mode: 'reconcile', targetState: 'implemented' }) }, 'input backend-source-application is required', 'reconcile with no delivered source');
+await expectError({ ...baseline(), 'request/request.json': requestJson({ inputs: { 'backend-source-application': DELIVERED } }) }, 'input backend-source-application is refused', 'model mode reading delivered source');
+await expectError(reconciled({ 'response/response.json': responseJson({ fields: { ...RECONCILE_FIELDS, 'coverage-matrix': 'response/data/coverage-matrix.json' } }), 'response/data/coverage-matrix.json': coverageMatrix() }), 'may not freeze a new coverage matrix', 'reconcile freezing a matrix');
+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: { featureId: '' } }) }, 'required field featureId has no value', 'missing required featureId');
+await expectError({ ...baseline(), 'response/data/model.json': modelDoc({ headRef: `${ROOT_REF}/features/starci/${FEATURE}` }) }, 'no project segment below the businesses root', 'a project segment below the businesses root');
+await expectError({ ...baseline(), 'response/data/model.json': modelDoc({ headRef: `.worktrees/authority/features/${FEATURE}` }) }, 'is not under a .worktrees/businesses root', 'head outside the businesses root');
+await expectError({ ...baseline(), 'response/data/model.json': modelDoc({ coverage: `sha256:${'e'.repeat(64)}` }) }, 'must equal the frozen matrix fingerprint', 'model and matrix disagree on the fingerprint');
+await expectError({ ...baseline(), 'response/response.md': responseMd({ coverage: `sha256:${'e'.repeat(64)}` }) }, 'must equal the coverage matrix fingerprint', 'response and matrix disagree on the fingerprint');
+await expectError({ ...baseline(), 'response/data/model.json': modelDoc({ transition: 'pending->in-progress' }) }, 'contradicts previous state null', 'transition contradicts the previous state');
+await expectError({ ...baseline(), 'response/data/model.json': modelDoc({ previousHeadRef: `${ROOT_REF}/features/${FEATURE}` }) }, 'a first publication cannot name a previous head', 'first publication with lineage');
+await expectError({ ...baseline(), 'request/request.json': requestJson({ targetState: 'implemented' }), 'response/data/model.json': modelDoc({ state: 'implemented', transition: 'in-progress->implemented', previousHeadRef: `${ROOT_REF}/features/${FEATURE}`, previousState: 'in-progress' }), 'response/response.md': responseMd({ state: 'implemented', transition: 'in-progress->implemented', previousHead: `\`${ROOT_REF}/features/${FEATURE}\``, previousState: 'in-progress' }) }, 'an implemented head requires reconciliation against delivered source', 'implemented without reconciliation');
+await expectError(reconciled({ 'response/data/model.json': modelDoc({ mode: 'reconcile', state: 'implemented', transition: 'in-progress->implemented', previousHeadRef: `${ROOT_REF}/features/${FEATURE}`, previousState: 'in-progress', reconciliation: { deliveredEvidenceRefs: ['src/settlement.ts'], discrepancies: [{ dimension: 'settlement', statement: 'the webhook still writes the legacy row' }] } }) }), 'reconciliation discrepancy or discrepancies remain', 'reconcile published with a discrepancy');
+await expectError({ ...baseline(), 'response/data/coverage-matrix.json': withRow('denial', { disposition: 'not-applicable', enforcementOwner: null, sourceRef: null, positiveProofRef: null, negativeProofRef: null, claimIds: [] }), 'response/response.md': responseMd({ dispositions: DISPOSITIONS.map(([d, p]) => (d === 'denial' ? [d, 'not-applicable'] : [d, p])) }) }, 'is mandatory for a published promise and cannot be marked not-applicable', 'mandatory dimension not applicable');
+await expectError({ ...baseline(), 'response/data/coverage-matrix.json': withRow('renewal', { disposition: 'not-applicable', deferralRef: null }), 'response/response.md': responseMd({ dispositions: DISPOSITIONS.map(([d, p]) => (d === 'renewal' ? [d, 'not-applicable'] : [d, p])) }) }, 'was discovered in the source and cannot be marked not-applicable', 'discovered lifecycle branch not applicable');
+await expectError({ ...baseline(), 'response/data/coverage-matrix.json': withRow('settlement', { negativeProofRef: null }) }, 'has no negative proof', 'preserve without a negative proof');
+await expectError({ ...baseline(), 'response/data/coverage-matrix.json': withRow('renewal', { positiveProofRef: proof('renewal-granted') }) }, 'cannot claim proof for work that has not happened', 'deferred row claiming proof');
+await expectError({ ...baseline(), 'response/data/coverage-matrix.json': withRow('settlement', { claimIds: ['c-intent'] }) }, 'without one fact claim', 'enforcement resting on an intent claim');
+await expectError({ ...baseline(), 'response/data/coverage-matrix.json': withRow('settlement', { claimIds: ['c-ghost'] }) }, 'which claims.json does not carry', 'row citing an unlisted claim');
+await expectError({ ...baseline(), 'response/data/coverage-matrix.json': withRow('entitlement-consumer', { consumerIds: [] }) }, 'has no disposition in the coverage matrix', 'discovered consumer never disposed');
+await expectError({ ...baseline(), 'response/data/coverage-matrix.json': withRow('denial', { consumerIds: [CONSUMER.consumerId] }) }, 'is disposed in more than one row', 'consumer disposed twice');
+await expectError({ ...baseline(), 'response/data/coverage-matrix.json': withRow('offer-entry', { consumerIds: ['ghost-guard'] }) }, 'was never discovered, so no evidence supports it', 'row disposing an undiscovered consumer');
+await expectError({ ...baseline(), 'response/data/coverage-matrix.json': coverageMatrix({ rows: coverageMatrix().rows.slice(0, 12) }), 'response/response.md': responseMd({ dispositions: DISPOSITIONS.slice(0, 12) }) }, 'has no disposition', 'a declared dimension missing from the matrix');
+await expectError({ ...baseline(), 'request/request.json': requestJson({ extra: { dimensions: DIMENSIONS.slice(0, 12) } }) }, 'was never declared by the request', 'a matrix dimension nobody declared');
+await expectError({ ...baseline(), 'response/response.md': responseMd({ dispositions: DISPOSITIONS.map(([d, p]) => (d === 'legacy-read' ? [d, 'defer'] : [d, p])) }) }, 'is defer here and preserve in the matrix', 'the response and the matrix disagree on a disposition');
+await expectError({ ...baseline(), 'response/response.md': responseMd().replace('## Coverage', '## Coverage matrix') }, 'missing section ^## Coverage$', 'response section renamed');
+await expectError({ ...baseline(), 'response/response.md': responseMd({ findings: [['LEGACY_COEXISTENCE', 'error', 'legacy-create', 'the legacy sale path still creates rights']] }) }, 'is still an open error, so the promise cannot be published', 'published with an open error finding');
+await expectError({ ...baseline(), 'response/data/claims.json': claimsDoc({ claims: [CLAIMS[0], { ...CLAIMS[0], kind: 'intent' }] }) }, 'is declared more than once', 'a duplicated claim');
+await expectError({ ...baseline(), 'response/data/claims.json': claimsDoc({ claims: [{ ...CLAIMS[0], sourceHead: null }, CLAIMS[1]] }) }, 'must bind the observed source head', 'a fact claim with no head');
+await expectError({ ...baseline(), 'response/response.md': responseMd({ claims: [['c-fact', 'fact']] }) }, 'which Cited claims omits', 'a claim the response never cites');
+await expectError({ ...baseline(), 'response/response.json': (() => { const o = responseJson(); delete o.fields.model; return o; })() }, 'required output model is not in fields', 'missing required output');
+
+process.stdout.write('business.decide self-test: 3 valid branches, 33 rejected mutations\n');