Tri thức

Tri thức là thẩm quyền quyết định, không phải quy trình. Một operator ràng buộc tập chủ đề nhỏ nhất mà quyết định của nó cần, và không được phát ra định danh nào ngoài kho luật đó. Ba chỉ mục dưới đây được chép nguyên từ cây.

UI knowledge

Cây này chứa universal UI law dùng chung cho mọi Grammar family đã publish, chia thành ba nhóm theo operator đọc từng law. Nó sở hữu 153 law X-n ổn định đang sống (36 ở composition, 68 ở presentation, 49 ở proof), cộng năm id composition đã nghỉ vào COVERAGE-1 và mười một id UI- đã nghỉ, nay tra về chính các rule topic proof đã sống sót thay chúng, không id nào được dùng lại, cùng với selection condition quan sát được, ownership decision, deterministic verdict và audit vector. Đây không phải implementation hay consumer cookbook. Nó không sở hữu business fact, copy riêng của page, route, permission, identity artwork, effect sản phẩm hay lựa chọn material của family.

Runtime policy

• Knowledge chuẩn cho agent/runtime chỉ là file .md tiếng Anh.
• File .vi.md cùng tên là bản mirror đầy đủ dành cho human review. Không bao giờ load, index hay cite chúng như runtime authority.
• Grammar operator resolve file canonical nhỏ nhất liên quan cùng rule ID. Từng file không mang routing metadata theo topic.
• Rule ID là địa chỉ ổn định, công khai. Chỉ được nối thêm PREFIX-n kế tiếp theo thứ tự; không bao giờ đánh số lại, tái sử dụng, hay lặng lẽ đổi nghĩa một ID đã tồn tại.
• Knowledge sở hữu invariant decision và audit vector, không sở hữu implementation status, migration plan, workflow, operator DAG hay task orchestration. Capability/debt hiện tại thuộc về plan và audit.

Grammar binding

@grammar/common là authority công khai cho props, semantics, renderer anatomy, state, accessibility, composition và universal implementation. Một application đã chọn family chỉ import đúng stylesheet của family đó; stylesheet đó import Common. Import trực tiếp @grammar/common/styles.css chỉ dành cho trường hợp dùng Common không family có chủ đích và cho test harness cô lập. Một application không được import cả hai đường cho cùng một cây đã render.

Một visual family là scoped overlay tương thích props, khai báo qua defineGrammarFamily. Nó có thể thay một Common renderer đã biết bằng props tương thích chính xác, hoặc thêm extension không xung đột; stylesheet của nó được scope bằng data-grammar-family. Nó phải giữ nguyên meaning, state behavior, accessibility, ownership và substitutability của Common.

Business/application code chọn đúng một family và cung cấp domain content, data, permission, handler và verified state. Application CSS được phép sở hữu page canvas, product layout/content/media và placement thông qua extension point công khai. Nó không được reach-through, dựng lại hay override anatomy, spacing, semantics, state, focus hay variant do Common sở hữu. Family document ghi lại lựa chọn overlay và conformance evidence; chúng không bao giờ lặp lại hay định nghĩa lại những universal law này. Một capability tái dùng còn thiếu là gap của Common, không phải giấy phép cho anatomy cục bộ theo sản phẩm hay một universal rule riêng của family.

Ba nhóm

Một topic sống cùng operator đọc nó. Topic nào không operator nào đọc thì không có lý do tồn tại.

Phép thử để xếp một topic là: đọc source có trả lời được không. Giá trị khoảng cách đọc được từ class nên thuộc presentation. Số hành động trội đã chốt trước khi có cây nên thuộc composition. Thứ tự bàn phím có khớp thứ tự nhìn thấy hay không thì phải chạy mới biết, nên thuộc proof.

Quy ước viết code sinh ra tất cả những thứ này nằm ở patterns/, còn phần hiện thực của từng họ nằm ở grammars/.

Rule binding architecture

Knowledge định nghĩa một rule nghĩa là gì; nó không hard-code instance DOM hiện tại nào pass rule đó. Một Common reusable expose stable anchor cho component, slot và relationship. Một binding registry co-located hoặc generated map các anchor đó sang rule, với tối thiểu:

• một binding ID và version ổn định;
• ruleId;
• target slot hoặc between-slot relationship chính xác;
• when variant, state hoặc composition selector;
• expected owner anchor.

Registry không bao giờ lặp lại metric hay behavior của rule. Application không tự tay viết mảng rule, và không markup nào tự gán nhãn pass cho chính nó. Auditor resolve binding từ stable DOM anchor, thu thập rendered evidence, và ghi rule ID cùng finding vào audit result. Rule ID không rõ, slot thiếu, anchor cũ và binding mồ côi đều fail validation. DOM nằm ngoài một reusable đã đăng ký có thể được chọn bằng semantic inspection, nhưng không thể nhận PASS nếu thiếu cùng owner và runtime evidence.

Contract claim là ngoại lệ duy nhất, và nó không phải self-assessment. Một rule-binding operator có thể emit data-contract trên node nó đã resolve, dưới dạng danh sách identifier cách nhau bằng space mà node đó tuyên bố thoả mãn. Claim nêu ra một ý định để auditor có thể phản bác: một node claim GAP-4 trong khi gap tính ra là 1.5rem là một finding, một node mang spacing mà không claim gì là một giá trị vô chủ, và một identifier được claim nhưng không có trong knowledge đã publish thì fail validation. Claim không bao giờ mang verdict, score hay PASS, và một claim viết tay là không hợp lệ vì chỉ receipt của operator mới verify được. Grammar emit cùng một claim trên những element hiện thực một relationship nó sở hữu, chính là các row trong bảng “Common already owns” của từng topic, nên một giá trị nội bộ của Grammar không bao giờ là giá trị vô chủ và resolver không claim lại những node đó. Receipt vẫn là bản ghi bền vững, nên attribute này có thể bị strip khỏi production build mà không làm yếu bất kỳ audit nào.

Canonical verdict model

Base verdict chỉ gồm đúng: PASS, COMMON_CAPABILITY_MISSING, COMMON_IMPLEMENTATION_GLITCH, FAMILY_OVERRIDE_GLITCH, APP_REIMPLEMENTATION, APP_OVERRIDE, APP_WORKAROUND, PROOF_MISSING.

Cause tag chỉ gồm đúng: VALUE_DRIFT, VENDOR_LEAK, WRONG_OWNER, OFF_SCALE_VALUE, DOUBLE_OWNER, PHYSICAL_SIDE_DRIFT, STATE_OR_VIEWPORT_DRIFT.

Đánh giá theo thứ tự capability, output cô lập của Common, delta của family, delta của app, rồi mới tới owner/state evidence. Một finding chứa đúng một base verdict và không hoặc nhiều cause tag. Nhiều layer fail cùng lúc tạo ra các finding liên kết; chúng không bị gộp thành một base verdict tổng hợp hay bị first-match logic che mất. PASS chỉ hợp lệ khi không tồn tại failure finding nào.

Nguồn: knowledge/ui/INDEX.vi.md.

StarCi Core Grammar — mục lục đọc

Nhánh này mô tả một visual family: StarCi Core, và cái gu chỉ đạo cách ghép nó. Luật UI universal vẫn canonical tại knowledge/ui; nhánh này map các luật X-n đó vào family Core đang chạy và ghi lại những idiom StarCi thực sự dựng bằng. Nó không kể lại giải phẫu renderer — DNA, sinh ra từ package, đã nói cái gì tồn tại và mỗi renderer sở hữu cái gì.

Chuỗi authority

knowledge/ui X-n → @starci/grammar/common props/anatomy/state → @starci/grammar/core DNA và scoped CSS → product adapter

• Common sở hữu public renderer, props, semantic DOM, accessibility, presentation state, universal spacing, COMMON_GRAMMAR_COMPONENTS và defineGrammarFamily.
• Core là sibling family có id core; CoreGrammarRoot cài data-grammar-family="core".
• Feature code sở hữu domain fact, route, copy, permission, persistence và effect.
• Tên product như Learn, Console, Dashboard, Navbar hay Course không bao giờ trở thành Grammar identity.

Thứ tự đọc

0. DNA — sinh ra từ package: cái gì đang tồn tại. Mồi cho agent định hướng bằng đúng file này.
1. Idiom — StarCi ghép những thứ đang tồn tại ra sao, mỗi idiom có ít nhất hai bằng chứng trong block đang chạy.
2. Playbook — hình dạng nghiệp vụ nào đòi chuỗi idiom nào, và tham chiếu được góp gì.
3. Family và DNA — danh tính riêng của visual family, token, hướng CSS, binding theme, và bảng gap duy nhất mà cả family công bố.

Đọc 0 tới 2 để quyết định dựng gì; đọc 3 khi một dòng đặt câu hỏi về chính family. Cách tiêu thụ gói trong code (import, một root family, cấm clone) là FE-IMPORTS-5 và FE-IMPORTS-7 trong knowledge/patterns/fe.

Gate review

Thay đổi hợp lệ không import renderer từ @starci/grammar/core, Common CSS không import Core CSS, Grammar không có feature-named component, không lặp luật X-n và không drift EN/VI. Claim riêng của Core phải resolve được tới source đang chạy hoặc ghi rõ là gap.

Nguồn: knowledge/grammars/starci/INDEX.vi.md.

Mẫu mã nguồn frontend

knowledge/ui/ quyết định giao diện phải là gì: đối tượng Grammar nào được vẽ, khoảng cách nào, sắc thái nào. knowledge/patterns/fe/ quyết định mã nguồn tạo ra giao diện ấy được viết ra sao: một đơn vị mã nằm ở đâu, các tệp của nó tên gì, hàm component có hình dạng nào, chuỗi class đặt ở đâu, thất bại được biểu diễn thế nào, và spec đi kèm nằm chỗ nào. Một luật mẫu không bao giờ chọn hình ảnh; một luật ui/ không bao giờ chọn tên tệp. Mọi luật dưới đây được rút ra từ ứng dụng tham chiếu (src/) và gói Grammar của nó (packages/grammar/src/) bằng cách mở tệp và đếm, và mỗi bảng đều dẫn nguồn tệp đã đọc. Nơi nào mã nguồn chia hai ngả, tệp ghi lại biến thể chiếm ưu thế cùng con số thay vì áp đặt.

Danh mục

Nguồn

Ứng dụng: src/ của ứng dụng tham chiếu (976 tệp TypeScript không phải spec, 497 spec). Gói Grammar: packages/grammar/src/ của nó. Bộ luật lint chỉ được tra để lấy tên luật: @starci/eslint-canon-fe như đã cài trong node_modules.

Nguồn: knowledge/patterns/fe/INDEX.vi.md.