@starci/skills 1.1.0

package/templates/README.md

@@ -0,0 +1,47 @@
+# Templates
+
+One template per document kind. A template is the skeleton a human copies and, inside it, one fenced
+`json template-contract` block that `scripts/validate-templates.mjs` enforces on every file the
+template applies to and on that file's `.vi.md` mirror. The contract is the authority; the skeleton
+is how a person reads it.
+
+| Template | Applies to | Enforces |
+| --- | --- | --- |
+| `ui-composition.template.md` | `knowledge/ui/composition/*.md` | title; only rule sections `PREFIX-n — …`, each with one `Case \| When \| Assert` table; closing section |
+| `ui-presentation.template.md` | `knowledge/ui/presentation/*.md` | title; Scale or Catalog, Owner with its table, free frame sections, of which `<Topic> Common already owns` is generated by `scripts/generate-presentation-owned.mjs` rather than written, rules with one `Case \| When \| Owner \| Render` table; closing section |
+| `ui-proof.template.md` | `knowledge/ui/proof/*.md` | title; only rule sections, each with one `Case \| When \| Observe` table; closing section |
+| `grammars.template.md` | `knowledge/grammars/*/*.md` | title; any sections; every rule section carries one `Case \| Rule \| Common owner \| Core realization` table |
+| `patterns.template.md` | `knowledge/patterns/*/*.md` | title; any sections; every rule section carries one `Case \| When \| Write` table |
+| `kinds/changes.contract.json` + `kinds/changes.skeleton.md` | `response/changes.md` inside a session branch; `templates/changes.example.md` is its enforced example | title; Binding table, Files table, What the next step must know |
+| `operator.template.md` | `operators/*/operator.md` | title `# <operator.id>`; Job, free law sections, Context, Inputs, Requirements, Steps, Outputs, Stops, Next, each with its table; `scripts/validate-operator.mjs` then checks the tables against each other, `errors/`, and `templates/kinds` |
+| `kinds/<kind>.contract.json` | markdown files inside a session branch (`response/response.md`, `critique/response/critique.md`) | pure JSON, checked against `kinds/contract.schema.json`: title regex, ordered sections, each table's header, row count, required rows, cell regexes; `kinds/<kind>.skeleton.md` is the copyable skeleton and must itself pass the contract; `scripts/validate-response.mjs` loads contracts by kind |
+| `kinds/<kind>.schema.json` | `response/data/<name>.json` inside a session branch | JSON Schema of one machine kind |
+| `step/request.schema.json`, `step/response.schema.json` | `request/request.json` and `response/response.json` of every branch and nested exchange | the two gates shared by every operator; `scripts/validate-request.mjs` runs before an agent, `scripts/validate-response.mjs` after |
+| `kinds/` artifact kinds | files an operator declares with type `artifact` (`alternatives`, `direction-image`, `resolved-tree`, `screenshot`, `sheet`, `article`, `image`, `image-prompt`, `track`) | no contract or schema on purpose: the validators check that the file exists and is pointed to; the operator's own `validate.mjs` may inspect it |
+
+## Contract vocabulary
+
+- `applies`: globs relative to `.claude`; `*` stays inside one path segment. `INDEX.md` files are never
+  claimed: they are reading indexes, not documents of a kind.
+- `title`: a regular expression the first line must match, one per language.
+- `sections`: the ordered `##` headings a document must carry. `{ "free": true }` marks a zone where a
+  document may add its own sections; outside a free zone an extra section is an error. A section may
+  carry `table`, the exact header row that must open it.
+- A section with a `table` may also carry `minRows` / `exactRows` (how many data rows), `rows` (first-column
+  values that must appear, backticks ignored), and `cell` (`{ "<Column>": "<regex>" }`, every data row's
+  cell under that column must match; a column absent from this language's header is skipped). A kind
+  contract under `kinds/` is single-language JSON: `title`, `heading` and `table` are plain strings.
+- `rules`: `heading` is the regular expression of a rule section, `table` the one header row each rule
+  must carry (exactly one table per rule), `closing` the section that must come last, `required`
+  whether the document must publish at least one rule. Rule and closing headings are excluded from
+  the `sections` walk.
+- Every `.md` a template claims must have a same-stem `.vi.md`, checked against the `vi` form of the
+  same contract. The mirror is a human reading copy, never runtime authority.
+
+## Changing a template
+
+Change the contract, run `node scripts/validate-templates.mjs`, and bring every document it names
+into conformance in the same commit. A template that the tree does not satisfy is not published.
+`scripts/validate-templates.spec.mjs` proves the validator itself on a synthetic tree: conforming
+documents pass, and a missing section, a wrong order, a wrong table header, an extra table under a
+rule, and a missing mirror each fail with the line that names them.

package/templates/README.vi.md

@@ -0,0 +1,45 @@
+# Khuôn
+
+Mỗi loại tài liệu một khuôn. Khuôn là bộ xương mà người viết chép lại, và bên trong nó có đúng một
+khối fenced `json template-contract` mà `scripts/validate-templates.mjs` ép lên mọi file khuôn đó áp
+vào, cùng bản `.vi.md` của file ấy. Hợp đồng là thẩm quyền; bộ xương là cách người đọc hiểu nó.
+
+| Khuôn | Áp vào | Ép gì |
+| --- | --- | --- |
+| `ui-composition.template.md` | `knowledge/ui/composition/*.md` | tiêu đề; chỉ các mục rule `PREFIX-n — …`, mỗi mục một bảng `Case \| Dùng khi \| Khẳng định`; mục đóng |
+| `ui-presentation.template.md` | `knowledge/ui/presentation/*.md` | tiêu đề; Thang giá trị hoặc Danh mục, Owner kèm bảng, mục khung tự do — trong đó `<Topic> Common already owns` do `scripts/generate-presentation-owned.mjs` sinh ra chứ không viết tay — rule với một bảng `Case \| Dùng khi \| Owner \| Render`; mục đóng |
+| `ui-proof.template.md` | `knowledge/ui/proof/*.md` | tiêu đề; chỉ các mục rule, mỗi mục một bảng `Case \| Dùng khi \| Quan sát`; mục đóng |
+| `grammars.template.md` | `knowledge/grammars/*/*.md` | tiêu đề; mục tuỳ ý; mọi mục rule mang một bảng `Case \| Luật \| Owner của Common \| Core hiện thực` |
+| `patterns.template.md` | `knowledge/patterns/*/*.md` | tiêu đề; mục tuỳ ý; mọi mục rule mang một bảng `Case \| Dùng khi \| Viết` |
+| `kinds/changes.contract.json` + `kinds/changes.skeleton.md` | `response/changes.md` trong một nhánh của phiên; `templates/changes.example.md` là ví dụ được ép | tiêu đề; bảng Binding, bảng Files, Bước kế tiếp cần biết gì |
+| `operator.template.md` | `operators/*/operator.md` | tiêu đề `# <operator.id>`; Việc, các mục luật tự do, Context, Đầu vào, Yêu cầu, Các bước, Đầu ra, Dừng, Kế tiếp, mỗi mục một bảng; `scripts/validate-operator.mjs` sau đó đối chiếu các bảng với nhau, với `errors/` và với `templates/kinds` |
+| `kinds/<kind>.contract.json` | file markdown trong một nhánh của phiên (`response/response.md`, `critique/response/critique.md`) | JSON thuần, kiểm bằng `kinds/contract.schema.json`: regex tiêu đề, mục theo thứ tự, header từng bảng, số dòng, dòng bắt buộc, regex ô; `kinds/<kind>.skeleton.md` là bộ xương để chép và tự nó phải qua hợp đồng; `scripts/validate-response.mjs` nạp hợp đồng theo kind |
+| `kinds/<kind>.schema.json` | `response/data/<name>.json` trong một nhánh của phiên | JSON Schema của một kind máy |
+| `step/request.schema.json`, `step/response.schema.json` | `request/request.json` và `response/response.json` của mọi nhánh và mọi cuộc trao đổi lồng | hai gate dùng chung cho mọi operator; `scripts/validate-request.mjs` chạy trước agent, `scripts/validate-response.mjs` chạy sau |
+| `kinds/` kind artifact | file mà operator khai kiểu `artifact` (`alternatives`, `direction-image`, `resolved-tree`, `screenshot`, `sheet`, `article`, `image`, `image-prompt`, `track`) | cố ý không có hợp đồng hay schema: validator chỉ kiểm file tồn tại và được trỏ tới; `validate.mjs` của operator có thể soi thêm |
+
+## Từ vựng của hợp đồng
+
+- `applies`: glob tính từ `.claude`; `*` không vượt qua dấu `/`. File `INDEX.md` không bao giờ bị
+  nhận: chúng là chỉ mục để đọc, không phải tài liệu của một loại.
+- `title`: biểu thức chính quy mà dòng đầu phải khớp, mỗi ngôn ngữ một cái.
+- `sections`: các heading `##` phải có, theo thứ tự. `{ "free": true }` đánh dấu vùng tài liệu được
+  thêm mục riêng; ngoài vùng tự do, một mục thừa là lỗi. Một mục có thể mang `table`, đúng dòng
+  header bảng phải mở đầu mục đó.
+- Mục có `table` còn có thể mang `minRows` / `exactRows` (số dòng dữ liệu), `rows` (giá trị cột đầu phải
+  xuất hiện, bỏ qua dấu backtick) và `cell` (`{ "<Cột>": "<regex>" }`, ô dưới cột đó ở mọi dòng phải khớp;
+  cột không có trong header của ngôn ngữ này thì bỏ qua). Hợp đồng kind dưới `kinds/` là JSON một ngôn ngữ:
+  `title`, `heading` và `table` là chuỗi trơn.
+- `rules`: `heading` là biểu thức của mục rule, `table` là dòng header duy nhất mỗi rule phải mang
+  (đúng một bảng cho mỗi rule), `closing` là mục phải đứng cuối, `required` là tài liệu có bắt buộc
+  publish ít nhất một rule không. Heading rule và heading đóng không tham gia bước duyệt `sections`.
+- Mọi `.md` mà khuôn nhận phải có `.vi.md` cùng gốc, được kiểm theo dạng `vi` của cùng hợp đồng. Bản
+  mirror là bản đọc cho người, không bao giờ là thẩm quyền lúc chạy.
+
+## Đổi khuôn
+
+Đổi hợp đồng, chạy `node scripts/validate-templates.mjs`, và đưa mọi tài liệu nó gọi tên về đúng
+khuôn trong cùng một commit. Khuôn mà cây không thoả thì chưa được publish.
+`scripts/validate-templates.spec.mjs` chứng minh chính validator trên một cây giả: tài liệu đúng khuôn
+thì qua; thiếu mục, sai thứ tự, sai header bảng, thừa bảng dưới một rule, thiếu bản mirror đều bị chặn
+kèm số dòng.

package/templates/changes.example.md

@@ -0,0 +1,27 @@
+# changes — frontend.source.apply step-5/parallel-1
+
+`frontend.source.apply` projected the resolved tree for the subscriptions route onto two declared paths of
+the frontend checkout, bound to the direction decided in `step-3/parallel-1` and the presentation
+resolved in `step-4/parallel-1`. Nothing outside the declared write set was touched.
+
+## Binding
+
+| Field | Value |
+| --- | --- |
+| Operator | `frontend.source.apply` |
+| Step | `step-5/parallel-1` |
+| Checkout | `@workspaces/fe` at `14e0c20…` → `uncommitted` |
+| Predecessor | `step-4/parallel-1/response/response.md` |
+
+## Files
+
+| Path | Change | Why | Claims |
+| --- | --- | --- | --- |
+| `src/blocks/commerce/ProSubscriptionBlock/index.tsx` | modified | resolved tree replaces the app-owned gap and padding classes with the rules the resolution selected | GAP-3, PADDING-4 |
+| `src/blocks/commerce/ProSubscriptionBlock/PlanCard.tsx` | created | new leaf the direction introduced for one plan | SURFACE-2, TONE-1 |
+
+## What the next step must know
+
+- Gates to run: `lint`, `typecheck`, `test:unit` for `src/blocks/commerce/**`.
+- Surfaces to observe: `/subscriptions` at mobile and desktop, light and dark.
+- Not changed on purpose: `src/blocks/commerce/ProSubscriptionBlock/index.stories.tsx` stays until the story audit runs after `frontend.surface.audit`.

package/templates/grammars.template.md

@@ -0,0 +1,34 @@
+# StarCi Core — <Topic>
+
+One or two paragraphs: which universal rules this file maps onto the live Core family, and that
+every owner named below is read from `packages/grammar/src`.
+
+## <Section, optional, repeatable>
+
+Prose sections are allowed: family DNA, consumption, the component matrix, states. A file that
+publishes rules follows the rule shape below for each of them.
+
+## PREFIX-1 — <what the rule governs>
+
+One line: the universal meaning of the rule.
+
+| Case | Rule | Common owner | Core realization |
+| --- | --- | --- | --- |
+| Case 1 | The situation. | The exact Common renderer, slot, or prop. | What Core does for it, or `gap` with one clause on what is missing. |
+
+Source: `packages/grammar/src/…`
+
+```json template-contract
+{
+  "kind": "grammars",
+  "applies": ["knowledge/grammars/*/*.md"],
+  "title": { "en": "^# .+$", "vi": "^# .+$" },
+  "sections": [{ "free": true }],
+  "rules": {
+    "heading": "^## [A-Z][A-Z0-9-]*-\\d+ — .+$",
+    "table": { "en": "| Case | Rule | Common owner | Core realization |", "vi": "| Case | Luật | Owner của Common | Core hiện thực |" },
+    "closing": null,
+    "required": false
+  }
+}
+```

package/templates/kinds/architecture-decision.contract.json

@@ -0,0 +1,14 @@
+{
+  "kind": "architecture-decision",
+  "title": "^# architecture-decision — [a-z0-9][a-z0-9-]*$",
+  "sections": [
+    { "heading": "^## Decision$", "table": "| Field | Value |", "rows": ["Objective", "Decision id", "Selected alternative", "Selection policy"], "cell": { "Value": "\\S" } },
+    { "heading": "^## Current state$", "table": "| Boundary | Responsibility | Stores | Evidence |", "minRows": 1, "cell": { "Evidence": "\\S" } },
+    { "heading": "^## Alternatives$", "table": "| Alternative | Status | Assessment | Rejected because |", "minRows": 1, "cell": { "Status": "^(selected|rejected)$" } },
+    { "heading": "^## Boundaries$", "table": "| Boundary | Responsibility | Owner | Interfaces | Owns data |", "minRows": 1, "cell": { "Owns data": "^(yes|no)$" } },
+    { "heading": "^## Data ownership$", "table": "| Store | Owning boundary | Writers | Readers | Migrators | Transaction scope | Backup | Restore |" },
+    { "heading": "^## Stack delta$", "table": "| Component | Status | Justification | Evidence | Compatibility |", "minRows": 1, "cell": { "Status": "^(existing|added|replaced|removed|replaced-candidate)$", "Justification": "^(measured-constraint|observed-evidence|requirement-fit|—)$" } },
+    { "heading": "^## Handoff$", "table": "| Item | Kind | Detail |", "minRows": 1, "cell": { "Kind": "^(invariant|risk|contract|migration|rollback|proof|unknown)$" } },
+    { "heading": "^## Fallbacks taken$", "table": "| Code | Action |", "cell": { "Code": "^`[A-Z][A-Z0-9_]+`$" } }
+  ]
+}

package/templates/kinds/architecture-decision.skeleton.md

@@ -0,0 +1,52 @@
+# architecture-decision — decision-id
+
+## Decision
+
+| Field | Value |
+| --- | --- |
+| Objective | the objective as the person stated it |
+| Decision id | `decision-id` |
+| Selected alternative | `alternative-id` |
+| Selection policy | `automatic` |
+
+## Current state
+
+| Boundary | Responsibility | Stores | Evidence |
+| --- | --- | --- | --- |
+| `boundary-id` | what it does today | `store-id` or — | `path:line@head` |
+
+## Alternatives
+
+| Alternative | Status | Assessment | Rejected because |
+| --- | --- | --- | --- |
+| `alternative-id` | selected | one cell per trade-off axis, in the order the person named them | — |
+
+## Boundaries
+
+| Boundary | Responsibility | Owner | Interfaces | Owns data |
+| --- | --- | --- | --- | --- |
+| `boundary-id` | what it will do | team or service | the contracts it exposes | yes |
+
+## Data ownership
+
+| Store | Owning boundary | Writers | Readers | Migrators | Transaction scope | Backup | Restore |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `store-id` | `boundary-id` | `boundary-id` | `other-boundary` | `boundary-id` | per request | nightly snapshot | tested restore path |
+
+## Stack delta
+
+| Component | Status | Justification | Evidence | Compatibility |
+| --- | --- | --- | --- | --- |
+| `component-id` | existing | measured-constraint | `path@head` | 5/5 verified, or the axes still unknown |
+
+## Handoff
+
+| Item | Kind | Detail |
+| --- | --- | --- |
+| one line each | invariant | what must stay true; contracts are named, implementation files never |
+
+## Fallbacks taken
+
+| Code | Action |
+| --- | --- |
+| `CODE` | what the fallback did; no rows when none was taken |

package/templates/kinds/backend-source-application.contract.json

@@ -0,0 +1,10 @@
+{
+  "kind": "backend-source-application",
+  "title": "^# backend-source-application — [a-z0-9][a-z0-9-]*$",
+  "sections": [
+    { "heading": "^## Binding$", "table": "| Field | Value |", "rows": ["Outcome", "Feature", "Contract fingerprint", "Base", "Branch", "Commit"], "cell": { "Value": "\\S" } },
+    { "heading": "^## Operations$", "table": "| Operation | Transport | Writer | Transaction | Idempotency | Decisions |", "minRows": 1, "cell": { "Transport": "^(graphql-mutation|graphql-query|rest|worker|cron|event-consumer)$", "Transaction": "^(single-transaction|per-item|read-only|none)$", "Idempotency": "^(none|natural-key|request-token|event-id)$", "Decisions": "^BA-[0-9]+(?:, BA-[0-9]+)*$" } },
+    { "heading": "^## Changes$", "table": "| Path | Change | Operation | Before | After |", "minRows": 1, "cell": { "Change": "^(added|modified|deleted)$", "Before": "^(sha256:[0-9a-f]{64}|—)$", "After": "^(sha256:[0-9a-f]{64}|—)$" } },
+    { "heading": "^## Findings$", "table": "| Code | Operation | File | Statement |", "cell": { "Code": "^`(PATTERN_BOUND|NEW_CONVENTION_REFUSED|SNAPSHOT_REVALIDATED|MIGRATION_INCLUDED|EXCEPTION_IDENTITY_REUSED|BUSINESS_QUESTION_RAISED)`$", "Statement": "\\S" } }
+  ]
+}

package/templates/kinds/backend-source-application.skeleton.md

@@ -0,0 +1,34 @@
+# backend-source-application — outcome-id
+
+One paragraph: which outcome was implemented, inside which frozen contract, and what measured that
+the contract was filled rather than widened. Written by `backend.source.apply` as `response/response.md`;
+the conformance and proof records that measure it live beside it in `response/data/`, one file each.
+
+## Binding
+
+| Field | Value |
+| --- | --- |
+| Outcome | the one thing implemented, as the person stated it |
+| Feature | `feature-id` |
+| Contract fingerprint | `sha256:0000000000000000000000000000000000000000000000000000000000000000` |
+| Base | `0000000000000000000000000000000000000000` |
+| Branch | `session/s-0000` |
+| Commit | `1111111111111111111111111111111111111111` |
+
+## Operations
+
+| Operation | Transport | Writer | Transaction | Idempotency | Decisions |
+| --- | --- | --- | --- | --- | --- |
+| `operation-id` | graphql-mutation | `src/features/api/core/graphql/mutations/handler.ts` | single-transaction | request-token | BA-1 |
+
+## Changes
+
+| Path | Change | Operation | Before | After |
+| --- | --- | --- | --- | --- |
+| `src/features/api/core/graphql/mutations/handler.ts` | added | `operation-id` | — | sha256:1111111111111111111111111111111111111111111111111111111111111111 |
+
+## Findings
+
+| Code | Operation | File | Statement |
+| --- | --- | --- | --- |
+| `PATTERN_BOUND` | `operation-id` | `src/features/api/core/graphql/mutations/handler.ts` | the sibling family this aspect mirrors |

package/templates/kinds/business-promise-authority.contract.json

@@ -0,0 +1,13 @@
+{
+  "kind": "business-promise-authority",
+  "title": "^# business-promise-authority — [a-z0-9][a-z0-9-]*$",
+  "sections": [
+    { "heading": "^## Binding$", "table": "| Field | Value |", "rows": ["Feature", "Mode", "Target state", "Head", "Claims fingerprint", "Coverage fingerprint"], "cell": { "Value": "\\S" } },
+    { "heading": "^## Promise$", "table": "| Field | Value |", "rows": ["Promise", "Actor", "Eligibility"], "cell": { "Value": "\\S" } },
+    { "heading": "^## Lineage$", "table": "| Field | Value |", "rows": ["Previous head", "Previous state", "Transition"], "cell": { "Value": "\\S" } },
+    { "heading": "^## Cited claims$", "table": "| Claim | Kind | Role | Source | Lines | Head |", "minRows": 1, "cell": { "Claim": "^`[a-z0-9][a-z0-9-]*`$", "Kind": "^(fact|intent|example|unknown|contradiction)$", "Lines": "^\\d+-\\d+$" } },
+    { "heading": "^## Coverage$", "table": "| Dimension | Disposition | Statement | Consumers |", "cell": { "Dimension": "^`[a-z0-9][a-z0-9-]*`$", "Disposition": "^(preserve|replace|retire|defer|not-applicable)$", "Statement": "\\S" } },
+    { "heading": "^## Reconciliation$", "table": "| Dimension | Delivered evidence | Discrepancy |" },
+    { "heading": "^## Findings$", "table": "| Code | Severity | Dimension | Statement |", "cell": { "Code": "^`[A-Z][A-Z0-9_]*`$", "Severity": "^(info|warning|error)$" } }
+  ]
+}

package/templates/kinds/business-promise-authority.skeleton.md

@@ -0,0 +1,67 @@
+# business-promise-authority — feature-id
+
+One paragraph: which promise was decided, for which feature, and against which evidence. Written by
+`business.decide` as `response/response.md`; read by `backend.source.apply`, `quality.verify` and
+`uat.verify`, which correlate against the same coverage fingerprint rather than a paraphrase of it.
+
+## Binding
+
+| Field | Value |
+| --- | --- |
+| Feature | `feature-id` |
+| Mode | model |
+| Target state | pending |
+| Head | `.worktrees/businesses/features/feature-id` |
+| Claims fingerprint | `sha256:0000000000000000000000000000000000000000000000000000000000000000` |
+| Coverage fingerprint | `sha256:0000000000000000000000000000000000000000000000000000000000000000` |
+
+## Promise
+
+| Field | Value |
+| --- | --- |
+| Promise | one sentence: what the product promises, from fact claims only |
+| Actor | one sentence: who the promise is made to |
+| Eligibility | one sentence: what makes that actor eligible |
+
+## Lineage
+
+| Field | Value |
+| --- | --- |
+| Previous head | — on a first publication, otherwise the head this one replaces |
+| Previous state | — on a first publication, otherwise pending, in-progress, implemented or rejected |
+| Transition | absent->pending |
+
+## Cited claims
+
+| Claim | Kind | Role | Source | Lines | Head |
+| --- | --- | --- | --- | --- | --- |
+| `claim-id` | fact | what the claim observes | `src/path.ts` | 10-24 | `0000000000000000000000000000000000000000` |
+
+## Coverage
+
+| Dimension | Disposition | Statement | Consumers |
+| --- | --- | --- | --- |
+| `actor-eligibility` | preserve | who may hold the promise and why | `consumer-id` |
+| `offer-entry` | preserve | where the promise is offered | — |
+| `read-entry` | preserve | where the promise is read | — |
+| `purchase-side-effect` | preserve | what the purchase changes | — |
+| `settlement` | preserve | how the purchase settles | — |
+| `idempotency` | preserve | what a repeated call does | — |
+| `entitlement-consumer` | preserve | which guards read the entitlement | — |
+| `denial` | preserve | how the promise is denied when it does not hold | — |
+| `renewal` | defer | postponed to a named owner | — |
+| `refund` | not-applicable | no refund path exists for this promise | — |
+| `legacy-create` | retire | the legacy creation path is closed | — |
+| `legacy-read` | preserve | already-purchased rights stay readable | — |
+| `legacy-settle` | preserve | pending legacy settlement still completes | — |
+
+## Reconciliation
+
+| Dimension | Delivered evidence | Discrepancy |
+| --- | --- | --- |
+
+## Findings
+
+| Code | Severity | Dimension | Statement |
+| --- | --- | --- | --- |
+| `LEGACY_COEXISTENCE` | info | `legacy-create` | what was observed but not enforced |

package/templates/kinds/capture.schema.json

@@ -0,0 +1,33 @@
+{
+  "$id": "kind:capture",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["matrixId", "viewport", "scheme", "state", "nodes"],
+  "properties": {
+    "matrixId": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+    "viewport": {
+      "type": "array",
+      "minItems": 2,
+      "maxItems": 2,
+      "items": { "type": "integer", "minimum": 240 }
+    },
+    "scheme": { "enum": ["light", "dark"] },
+    "state": { "type": "string", "minLength": 1 },
+    "nodes": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 512,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "owner", "claims", "measured"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "owner": { "enum": ["app", "grammar"] },
+          "claims": { "type": "array", "maxItems": 32, "items": { "type": "string", "pattern": "^[A-Z][A-Z0-9-]*-[0-9]+$" } },
+          "measured": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1 } }
+        }
+      }
+    }
+  }
+}

package/templates/kinds/changes.contract.json

@@ -0,0 +1,10 @@
+{
+  "kind": "changes",
+  "example": "templates/changes.example.md",
+  "title": "^# changes — [a-z]+(?:\\.[a-z]+)+ step-\\d+/parallel-\\d+$",
+  "sections": [
+    { "heading": "^## Binding$", "table": "| Field | Value |", "rows": ["Operator", "Step", "Checkout", "Predecessor"], "cell": { "Value": "\\S" } },
+    { "heading": "^## Files$", "table": "| Path | Change | Why | Claims |", "minRows": 1, "cell": { "Change": "^(created|modified|deleted|unchanged)$" } },
+    { "heading": "^## What the next step must know$" }
+  ]
+}

package/templates/kinds/changes.skeleton.md

@@ -0,0 +1,26 @@
+# changes — operator.id step-1/parallel-1
+
+One paragraph: what this step changed, in which checkout, at which head. Written by the step that
+wrote source (`backend.source.apply`, `frontend.source.apply`) as `response/changes.md`; read unchanged by the
+next steps (`quality.verify`, `frontend.surface.audit`, `git.publish`) through their `request.json` inputs.
+
+## Binding
+
+| Field | Value |
+| --- | --- |
+| Operator | `operator.id` |
+| Step | `step-1/parallel-1` |
+| Checkout | `@workspaces/role` at `head before` → `head after, or uncommitted` |
+| Predecessor | `step-1/parallel-1/response/response.md` of the step whose decision this change applies |
+
+## Files
+
+| Path | Change | Why | Claims |
+| --- | --- | --- | --- |
+| `checkout-relative/path.tsx` | created | the decision this file carries | rule ids written into it, or — |
+
+## What the next step must know
+
+- Gates to run: the gate names the checkout pins for these paths.
+- Surfaces to observe: the routes or blocks whose rendered output changed.
+- Not changed on purpose: paths a reader might expect, and why they stayed.

package/templates/kinds/checks.schema.json

@@ -0,0 +1,44 @@
+{
+  "$id": "kind:checks",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["serviceRef", "serviceKind", "requiredCheckNames", "checks", "findings"],
+  "properties": {
+    "serviceRef": { "type": "string", "minLength": 1 },
+    "serviceKind": { "enum": ["observability", "sonar", "tunnel"] },
+    "requiredCheckNames": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/$defs/checkName" } },
+    "checks": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "resourceRef", "status", "evidenceRef"],
+        "properties": {
+          "name": { "$ref": "#/$defs/checkName" },
+          "resourceRef": { "type": "string", "minLength": 1 },
+          "status": { "enum": ["passed", "failed"] },
+          "evidenceRef": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["code", "resourceRef", "port", "holderRef", "statement"],
+        "properties": {
+          "code": { "enum": ["SHARED_SERVICE_INVENTORIED", "PORT_COORDINATION_REQUIRED", "ALREADY_CONVERGED", "PARTIAL_MUTATION", "PRODUCT_DEPLOYMENT_DECLINED"] },
+          "resourceRef": { "type": "string", "minLength": 1 },
+          "port": { "oneOf": [{ "type": "integer", "minimum": 1, "maximum": 65535 }, { "type": "null" }] },
+          "holderRef": { "oneOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }] },
+          "statement": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "checkName": { "enum": ["service-health", "target-boundary", "label-boundary", "remote-write-delivery", "sample-ordering", "retry-backoff", "sensitive-data-filter", "service-available", "project-exists", "source-revision", "profile-assigned", "gate-assigned", "enforcement-active", "dns-target", "tunnel-route", "tls", "public-https"] }
+  }
+}

package/templates/kinds/claims.schema.json

@@ -0,0 +1,165 @@
+{
+  "$id": "kind:claims",
+  "title": "Every observation the decision rests on, separated by role and bound to the source that shows it.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "featureId",
+    "sourceHead",
+    "fingerprint",
+    "claims"
+  ],
+  "properties": {
+    "featureId": {
+      "$ref": "#/$defs/identifier"
+    },
+    "sourceHead": {
+      "$ref": "#/$defs/sourceHead"
+    },
+    "fingerprint": {
+      "$ref": "#/$defs/fingerprint"
+    },
+    "claims": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 256,
+      "items": {
+        "$ref": "#/$defs/claim"
+      }
+    }
+  },
+  "$defs": {
+    "identifier": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]*$"
+    },
+    "fingerprint": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "sourceHead": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{40,64}$"
+    },
+    "claim": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "claimId",
+        "kind",
+        "role"
+      ],
+      "properties": {
+        "claimId": {
+          "$ref": "#/$defs/identifier"
+        },
+        "kind": {
+          "enum": [
+            "fact",
+            "intent",
+            "example",
+            "unknown",
+            "contradiction"
+          ]
+        },
+        "role": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024
+        },
+        "lineStart": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "lineEnd": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "sourceHead": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/sourceHead"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "statement": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 4096,
+          "description": "The person's words, for an intent or unknown claim that no source line shows yet"
+        },
+        "source": {
+          "type": "string",
+          "pattern": "^request/request\\.json#requirements\\.[a-zA-Z]+$",
+          "description": "Where a statement came from: the request field that carried it"
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "kind": {
+                "enum": [
+                  "fact",
+                  "example",
+                  "contradiction"
+                ]
+              }
+            },
+            "required": [
+              "kind"
+            ]
+          },
+          "then": {
+            "required": [
+              "path",
+              "lineStart",
+              "lineEnd",
+              "sourceHead"
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "kind": {
+                "enum": [
+                  "intent",
+                  "unknown"
+                ]
+              }
+            },
+            "required": [
+              "kind"
+            ]
+          },
+          "then": {
+            "anyOf": [
+              {
+                "required": [
+                  "path",
+                  "lineStart",
+                  "lineEnd"
+                ]
+              },
+              {
+                "required": [
+                  "statement",
+                  "source"
+                ]
+              }
+            ]
+          }
+        }
+      ]
+    }
+  }
+}