prpm-dbp 0.17.0 → 0.19.0

package/SKILL.md

@@ -9,6 +9,74 @@ Sumber kebenaran tunggal untuk ejaan BM dan Jawi ialah PRPM DBP, bukan ingatan m
 
 Model boleh hasilkan Jawi yang nampak betul tetapi salah, dan pembaca tidak dapat kesan. Skill ini tukar tekaan jadi semakan.
 
+## Sebelum menghantar apa-apa
+
+Jalankan `npx prpm-dbp gate <fail> --luar-talian` ke atas **keseluruhan teks**. Bukan sebahagian. Bukan perkataan yang anda rasa berisiko.
+
+Ejaan yang salah ialah tepat ejaan yang anda **tidak** syak. Kalau anda syak, anda sudah menyemaknya.
+
+Ini termasuk ejaan yang anda tulis dalam **kod, ujian dan dokumentasi**, bukan hanya dalam teks untuk pengguna. Semasa membina pakej ini sendiri, satu nilai Jawi ditulis ke dalam ujian daripada ingatan tanpa disemak. Nilainya kebetulan betul. Kebetulan bukan proses.
+
+**Apa yang berlaku apabila langkah ini dilangkau:**
+
+Satu agen menggunakan skill ini sepanjang sesi penuh untuk menukar Jawi ke Rumi, kemudian menghantar 549 kad RPH Pendidikan Islam ke pangkalan data produksi dengan **273 ejaan yang salah**.
+
+```
+pusingan 1   sunnah x206, hadith x16, fardhu x2        -> masuk produksi
+pusingan 2   tayammum, dhuha, qadha, redha, iddah x90  -> masuk produksi
+```
+
+Semuanya kata lazim dalam bahan Pendidikan Islam. Setiap satu ada jawapan tegas dalam PRPM: `sunnah` ialah rujukan silang ke `sunah`, `hadith` sepatutnya `hadis`, `fardhu` sepatutnya `fardu`, `tayammum` sepatutnya `tayamum`, `dhuha` sepatutnya `duha`, `qadha` sepatutnya `qada`.
+
+Alat untuk menangkap kesemuanya ada di tangan agen itu sepanjang masa. Ia tidak pernah dijalankan ke atas teks Rumi keluarannya sendiri. Kedua-dua pusingan ditemui kerana **pengguna bertanya**, bukan kerana proses menangkapnya.
+
+`gate` menyemak **kedua-dua tulisan dalam panggilan yang sama**. Versi terdahulu menyemak Rumi sahaja, jadi dokumen Jawi penuh melepasinya tanpa satu aduan pun — tepat jenis dokumen yang alat ini paling diperlukan.
+
+Empat perkara yang ditangkap dalam teks Jawi:
+
+| Keadaan | Contoh | Keputusan |
+|---|---|---|
+| ruang tersasar di dalam perkataan | `ݢول وڠن` | **ralat**, cadang `ݢولوڠن` |
+| ejaan tiada dalam DBP | `منجاوهكن` | **ralat**, cadang `منجاءوهکن` |
+| homograf tulen | `سنة` | tidak dapat disahkan, dua bacaan |
+| petikan Arab | `الشِّمال` | tidak dapat disahkan, §11.1 |
+
+Ruang tersasar itu kes paling berbahaya. Separuh perkataan boleh **berjaya secara palsu**: `ݢول` benar-benar memetakan kepada dua perkataan DBP tulen, `gol` dan `gul`. Penukar yang memilih calon paling kerap akan mengeluarkan "gol" dengan yakin, dan separuh perkataan hilang tanpa sesiapa perasan. Sebab itu percantuman dicuba apabila **salah satu** jiran belum selesai, bukan kedua-duanya.
+
+Nama khas Arab tanpa kata sandang `ال` (`أصحاب`, nama tokoh, nama tempat) tidak dapat disahkan kamus Melayu. Isytiharkannya melalui `npx prpm-dbp nama <rumi> <jawi> --jenis arab`; selepas itu ia berhenti menjadi ralat, tetapi tetap **bukan** lulus DBP.
+
+`gate` keluar dengan kod 1 apabila ada ralat, jadi ia boleh dipasang sebagai hook atau langkah CI. Peraturan yang bergantung pada agen ingat sendiri akan gagal, dan gagal secara senyap.
+
+## Kuatkuasa automatik
+
+```bash
+npx prpm-dbp install --hook
+```
+
+Memasang hook PostToolUse yang menjalankan `gate --luar-talian` ke atas setiap fail `.md`, `.txt` atau `.json` yang ditulis atau disunting. Ia **melaporkan** ralat kepada agen tanpa menyekat tulisan: menyekat atas kamus yang tidak lengkap akan menghalang kerja yang sah, manakala melaporkan sudah memadai kerana agen membaca output hook.
+
+Untuk menampal sendiri: `npx prpm-dbp hook-json`.
+
+Panaskan cache **sekali** semasa pemasangan, bukan semasa gate berjalan:
+
+```bash
+npx prpm-dbp warm kosa-kata-projek.txt
+```
+
+Gate atas cache panas mengambil 0.19 saat bagi 406 perkataan. Itu cukup pantas untuk setiap penyuntingan. Gate yang perlahan akan dimatikan orang.
+
+## Tiga keadaan gate, bukan dua
+
+| Medan | Maksud | Kesan |
+|---|---|---|
+| `lulusDbp` | ada dalam PRPM, ejaan padan | — |
+| `ralat` | ada dalam PRPM dengan ejaan lain, entri rujukan silang `®`, atau tiada dalam PRPM mahupun dataset | **exit 1** |
+| `tidakDapatDisahkan` | tiada dalam cache, nama khas, akronim, atau tiada entri PRPM tetapi wujud dalam dataset | dilapor; exit 1 jika melebihi `--ambang` |
+
+`tidakDapatDisahkan` **tidak pernah lulus senyap**. Gate yang lulus atas cache sejuk memberi jaminan palsu, dan itu lebih bahaya daripada tiada gate. Gunakan `--ambang 10` supaya cache sejuk menggagalkan gate.
+
+PRPM tiada entri untuk kata tugas paling asas: `dan`, `di`, `ke`, `yang`, `atau`. Menandakannya sebagai ralat menjadikan gate mustahil dipakai. Pembezanya bersumber, bukan senarai putih: kata tugas itu **semua** wujud dalam dataset, manakala `hadith`, `fardhu`, `tayammum`, `dhuha`, `qadha`, `redha` dan `iddah` **tiada satu pun**.
+
 ## Prosedur wajib
 
 Ikut ini setiap kali, jangan langkau langkah.
@@ -184,30 +252,6 @@ Ejaan yang disimpan begini ditandakan datang daripada pengguna, bukan daripada D
 
 Bagi nama berasal Arab, ejaan Jawinya memang ejaan Arab asal, jadi ia nampak seperti dikekalkan. Bagi nama bukan Arab ia ditransliterasi penuh: `Kuala Lumpur` menjadi `کوالا لومڤور`.
 
-## Prosedur wajib
-
-Ikut ini setiap kali, jangan langkau langkah.
-
-**Menulis Jawi daripada Rumi:**
-
-1. `npx prpm-dbp jawi <fail> --luar-talian --homograf --json`
-2. Baca `belumDisahkan` dan `namaKhas`. Jangan reka ejaan untuknya. Sahkan dengan `lookup`, atau tanya pengguna, atau tandakan dalam hasil akhir.
-3. Baca `mencurigakan`. Setiap satu bermakna PRPM sendiri mungkin tersilap. Semak di pautan yang diberi sebelum menggunakannya.
-4. Baca `homograf`. Beritahu pengguna perkataan mana yang akan taksa apabila dibaca.
-5. Laporkan `semuanyaDbp`. Jika `false`, nyatakan bahagian mana bukan daripada sumber rasmi.
-
-**Merumikan daripada Jawi:**
-
-1. `npx prpm-dbp rumi <fail> --pilih --konteks --json`
-2. Untuk **setiap** item dalam `kabur`: baca ayat yang mengandunginya, baca makna setiap calon, tentukan yang mana sesuai.
-3. Jika `dipilih` salah bagi ayat itu, **gantikan** dalam hasil akhir. Kekerapan kalah kepada konteks.
-4. Nyatakan kepada pengguna berapa banyak kekaburan wujud dan mana yang anda ubah.
-5. `tidakDikenali` bermakna perkataan itu tiada dalam cache. Jalankan `warm` di luar talian, bukan tinggalkan bertanda.
-
-**Berhenti dan tanya pengguna apabila:** ejaan `mencurigakan` mengubah makna, nama khas tiada rujukan bertulis, atau dua calon sama-sama munasabah dalam ayat itu.
-
-Semua perintah menyokong `--json`, jadi langkah di atas boleh dibuat secara berulang tanpa menghurai teks.
-
 ## Peraturan Pedoman DBP
 
 Satu fail sahaja dalam pakej ini **menjana** ejaan dan bukan mencarinya: `src/pedoman.js`. Ia dibenarkan kerana setiap peraturan di dalamnya datang daripada *Pedoman Umum Ejaan Jawi Bahasa Melayu* terbitan DBP, dan dirujuk pada seksyennya.
@@ -319,30 +363,6 @@ Dua puluh dua kes kabur yang tinggal itu sah: `قلقله` boleh dibaca `qalqala
 
 **Sifar perkataan hilang atau rosak.**
 
-## Prosedur wajib
-
-Ikut ini setiap kali, jangan langkau langkah.
-
-**Menulis Jawi daripada Rumi:**
-
-1. `npx prpm-dbp jawi <fail> --luar-talian --homograf --json`
-2. Baca `belumDisahkan` dan `namaKhas`. Jangan reka ejaan untuknya. Sahkan dengan `lookup`, atau tanya pengguna, atau tandakan dalam hasil akhir.
-3. Baca `mencurigakan`. Setiap satu bermakna PRPM sendiri mungkin tersilap. Semak di pautan yang diberi sebelum menggunakannya.
-4. Baca `homograf`. Beritahu pengguna perkataan mana yang akan taksa apabila dibaca.
-5. Laporkan `semuanyaDbp`. Jika `false`, nyatakan bahagian mana bukan daripada sumber rasmi.
-
-**Merumikan daripada Jawi:**
-
-1. `npx prpm-dbp rumi <fail> --pilih --konteks --json`
-2. Untuk **setiap** item dalam `kabur`: baca ayat yang mengandunginya, baca makna setiap calon, tentukan yang mana sesuai.
-3. Jika `dipilih` salah bagi ayat itu, **gantikan** dalam hasil akhir. Kekerapan kalah kepada konteks.
-4. Nyatakan kepada pengguna berapa banyak kekaburan wujud dan mana yang anda ubah.
-5. `tidakDikenali` bermakna perkataan itu tiada dalam cache. Jalankan `warm` di luar talian, bukan tinggalkan bertanda.
-
-**Berhenti dan tanya pengguna apabila:** ejaan `mencurigakan` mengubah makna, nama khas tiada rujukan bertulis, atau dua calon sama-sama munasabah dalam ayat itu.
-
-Semua perintah menyokong `--json`, jadi langkah di atas boleh dibuat secara berulang tanpa menghurai teks.
-
 ## Peraturan yang sengaja TIDAK dilaksanakan
 
 | Seksyen | Sebab |
@@ -457,6 +477,33 @@ Diukur pada 168 baris DSKP sebenar: token yang langsung tidak dikenali turun dar
 
 Kegunaannya bukan menjadikan alat lebih longgar. Ia membezakan **"ini surah, cuma dieja lain"** daripada **"saya tidak kenal benda ini"** — dua keadaan yang dahulu keluar sama sebagai `«...»`.
 
+## Kekaburan dalam teks domain
+
+`--pilih` menggunakan kekerapan korpus. Dalam teks am ia betul hampir sentiasa. Dalam **teks domain ia gagal tepat di tempat paling penting**: setiap istilah khusus kalah kepada kata lazim yang berkongsi rangka konsonan.
+
+Diukur pada DSKP KKQ/PQS: salah untuk 5 daripada 16 pasangan taksa, dan kelima-limanya ialah inti pelajaran.
+
+```
+اسم  -> asam    patut isim      "hamzah wasal pada kalimah asam dan faal"
+فعل  -> faal    patut fiil
+رسم  -> rasam   patut Rasm (Uthmani)
+سنة  -> sanat   patut sunah
+```
+
+Gunakan glosari domain. Ia **mengatasi segalanya**, termasuk lapisan 1:
+
+```bash
+npx prpm-dbp rumi dskp.txt --pilih --glosari istilah-kkq.json
+```
+
+```json
+{ "اسم": "isim", "فعل": "fiil", "رسم": "rasm", "سنة": "sunah" }
+```
+
+Setiap penggunaan direkod dalam medan `dariGlosari`, jadi ia boleh diaudit. Bina glosari itu sekali untuk domain anda; ia lebih murah daripada membetulkan output berulang kali, dan ia menjadi rekod: siapa membenarkan istilah apa.
+
+Kekerapan kekal sebagai pemecah seri sahaja, dan setiap keputusan tetap dilapor dalam `kabur` untuk semakan.
+
 ## Rantai kepercayaan
 
 Setiap ejaan Jawi yang dikeluarkan membawa asal-usulnya. Jangan runtuhkan lapisan ini.

package/bin/cli.js

@@ -2,11 +2,12 @@
 import { readFile } from 'node:fs/promises'
 import process from 'node:process'
 
-import { pasangSkill } from '../src/install.js'
+import { HOOK, pasangHook, pasangSkill } from '../src/install.js'
 import { banding, cariKamus } from '../src/kamus.js'
 import { keJawi, keRumi, semakJawi } from '../src/tukar.js'
 import { huraiTsv, muatDataset, simpanDataset } from '../src/dataset.js'
 import { NAMA_PATH, muatNama, tambahNama } from '../src/nama.js'
+import { gate, kodKeluar } from '../src/gate.js'
 import {
   CACHE_PATH,
   auditJawi,
@@ -29,9 +30,13 @@ const BANTUAN = `prpm-dbp — semak Bahasa Melayu dan Jawi terhadap PRPM DBP
   npx prpm-dbp import-tsv <fail.tsv>     import dataset rumi<TAB>jawi (dilabel bukan DBP)
   npx prpm-dbp nama <rumi> <jawi>        sahkan satu nama khas (tokoh, surah, tempat)
   npx prpm-dbp nama                      senaraikan nama khas yang disahkan
+  npx prpm-dbp gate <fail...>            semakan boleh GAGAL untuk hook dan CI
+                                        exit 0 bersih, exit 1 ada ralat
   npx prpm-dbp banding <kata...>         silang semak PRPM lawan KamusDBP
   npx prpm-dbp cache [--buang <kata>]    status cache
   npx prpm-dbp install [--link]          pasang sebagai Claude Code skill
+  npx prpm-dbp install --hook            pasang hook PostToolUse yang jalankan gate
+  npx prpm-dbp hook-json                 papar blok settings.json untuk ditampal sendiri
 
 Pilihan: --refresh  --had <n>  --delay <ms>  --json  --cepat
          --pedoman       jana imbuhan ikut peraturan DBP (88-98% tepat, hasil ditanda)
@@ -39,6 +44,9 @@ Pilihan: --refresh  --had <n>  --delay <ms>  --json  --cepat
          --homograf      tandakan perkataan yang ejaan Jawinya dikongsi perkataan lain
          --konteks       papar ayat dan makna setiap calon bagi kekaburan (rumi)
          --rangka        padan ejaan bukan piawai melalui rangka konsonan (berlabel)
+         --glosari <fail> rumi: glosari domain {jawi: rumi} yang mengatasi segalanya
+         --ambang <n>    gate: exit 1 jika tidakDapatDisahkan melebihi n peratus
+         --abai <fail>   gate: senarai nama khas/istilah yang sudah diisytihar
          --pilih         pilih calon paling lazim supaya teks boleh terus dibaca;
                          setiap pilihan disenaraikan untuk disemak ikut konteks
 
@@ -53,6 +61,7 @@ function huraiArgs(argv) {
     if (a === '--refresh') pilihan.refresh = true
     else if (a === '--json') pilihan.json = true
     else if (a === '--link') pilihan.link = true
+    else if (a === '--hook') pilihan.hook = true
     else if (a === '--cepat') pilihan.cepat = true
     else if (a === '--pedoman') pilihan.pedoman = true
     else if (a === '--luar-talian') pilihan.luarTalian = true
@@ -60,6 +69,9 @@ function huraiArgs(argv) {
     else if (a === '--konteks') pilihan.konteks = true
     else if (a === '--pilih') pilihan.pilih = true
     else if (a === '--rangka') pilihan.rangka = true
+    else if (a === '--ambang') pilihan.ambang = Number(argv[++i])
+    else if (a === '--abai') pilihan.abai = argv[++i]
+    else if (a === '--glosari') pilihan.glosari = argv[++i]
     else if (a === '--jenis') pilihan.jenis = argv[++i]
     else if (a === '--had') pilihan.had = Number(argv[++i])
     else if (a === '--delay') pilihan.delay = Number(argv[++i])
@@ -85,10 +97,20 @@ async function main() {
   }
 
   if (perintah === 'install') {
+    if (pilihan.hook) {
+      keluar(await pasangHook())
+      return
+    }
     keluar(await pasangSkill({ link: pilihan.link }))
     return
   }
 
+  if (perintah === 'hook-json') {
+    // Blok siap salin untuk pengguna yang mahu menampal sendiri.
+    keluar({ hooks: { PostToolUse: [HOOK] } })
+    return
+  }
+
   const cache = await loadCache()
   const opts = {
     refresh: pilihan.refresh,
@@ -229,6 +251,7 @@ async function main() {
         dataset: await muatDataset(),
         pilihLazim: pilihan.pilih,
         padanRangka: pilihan.rangka,
+        glosari: pilihan.glosari ? JSON.parse(await readFile(pilihan.glosari, 'utf8')) : null,
       })
       if (pilihan.json) { keluar(h); break }
       console.log(h.teks)
@@ -280,6 +303,64 @@ async function main() {
       break
     }
 
+    case 'gate': {
+      if (!baki.length) throw new Error('perlu sekurang-kurangnya satu fail')
+      const abai = new Set()
+      if (pilihan.abai) {
+        const senarai = await readFile(pilihan.abai, 'utf8')
+        for (const b of senarai.split('\n')) {
+          const k = b.trim().toLowerCase()
+          if (k && !k.startsWith('#')) abai.add(k)
+        }
+      }
+
+      const gabungan = { jumlahKataUnik: 0, lulusDbp: 0, ralat: [], tidakDapatDisahkan: [] }
+      for (const fail of baki) {
+        const laporan = await gate(await readFile(fail, 'utf8'), cache, {
+          ...opts,
+          // Dataset MESTI dimuatkan. Tanpanya peta songsang menyusut daripada
+          // 64k ejaan kepada saiz cache sahaja, dan kata tugas paling asas
+          // seperti دان dilaporkan sebagai ejaan Jawi yang salah.
+          dataset: await muatDataset(),
+          // Nama khas Arab (nama surah, tokoh, tempat) tidak boleh disahkan
+          // kamus Melayu. Yang sudah diisytihar melalui `nama` diambil kira
+          // supaya pengisytiharan itu benar-benar bermakna.
+          namaJawi: new Set(
+            Object.values(await muatNama())
+              .map((n) => n?.jawi)
+              .filter(Boolean),
+          ),
+          luarTalian: pilihan.luarTalian !== false,
+          abai,
+        })
+        gabungan.jumlahKataUnik += laporan.jumlahKataUnik
+        gabungan.lulusDbp += laporan.lulusDbp
+        gabungan.ralat.push(...laporan.ralat.map((r) => ({ ...r, fail })))
+        gabungan.tidakDapatDisahkan.push(...laporan.tidakDapatDisahkan.map((r) => ({ ...r, fail })))
+      }
+      gabungan.peratusTidakDapatDisahkan = gabungan.jumlahKataUnik
+        ? Math.round((gabungan.tidakDapatDisahkan.length / gabungan.jumlahKataUnik) * 100)
+        : 0
+
+      const kod = kodKeluar(gabungan, pilihan.ambang)
+      if (pilihan.json) keluar({ ...gabungan, kodKeluar: kod })
+      else {
+        console.error(
+          `gate: ${gabungan.lulusDbp}/${gabungan.jumlahKataUnik} disahkan DBP, ` +
+            `${gabungan.ralat.length} ralat, ` +
+            `${gabungan.tidakDapatDisahkan.length} tidak dapat disahkan (${gabungan.peratusTidakDapatDisahkan}%)`,
+        )
+        for (const r of gabungan.ralat.slice(0, 30)) {
+          console.error(
+            `  RALAT ${r.kata}: ${r.sebab}` + (r.sepatutnya ? ` -> guna "${r.sepatutnya}"` : ''),
+          )
+        }
+        if (gabungan.ralat.length > 30) console.error(`  ... ${gabungan.ralat.length - 30} lagi`)
+      }
+      process.exitCode = kod
+      break
+    }
+
     case 'nama': {
       if (baki.length >= 2) {
         const rec = await tambahNama(baki[0], baki[1], { jenis: pilihan.jenis ?? null })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prpm-dbp",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Semak ejaan Bahasa Melayu dan Jawi terhadap PRPM Dewan Bahasa dan Pustaka. CLI dan skill untuk AI agent.",
   "keywords": [
     "bahasa-melayu",

package/src/gate.js

@@ -0,0 +1,321 @@
+/**
+ * Gate: semakan yang boleh GAGAL, untuk hook dan CI.
+ *
+ * Dibina selepas satu agen menggunakan skill ini sepanjang sesi penuh dan
+ * tetap menghantar 273 ejaan salah ke pangkalan data produksi. Alat untuk
+ * menangkapnya ada di tangannya sepanjang masa; ia tidak pernah dijalankan.
+ * Kedua-dua pusingan ditemui kerana pengguna bertanya, bukan kerana proses
+ * menangkapnya.
+ *
+ * Kesimpulannya: skill yang bergantung pada agen ingat sendiri akan gagal,
+ * dan gagal secara senyap. Gate wujud supaya kepatuhan tidak bergantung
+ * pada ingatan.
+ *
+ * TIGA keadaan, bukan dua. `tidakDapatDisahkan` TIDAK PERNAH lulus senyap:
+ * gate yang lulus atas cache sejuk memberi jaminan palsu, dan itu lebih
+ * bahaya daripada tiada gate.
+ *
+ * Versi pertama menyemak Rumi SAHAJA. Regexnya `[A-Za-zÀ-ÿ]` bermakna
+ * dokumen Jawi penuh melepasi hook tanpa satu aduan pun — tepat jenis
+ * dokumen yang skill ini paling diperlukan. Sebaris teks pelajaran dengan
+ * `ݢول وڠن` (golongan dengan ruang tersasar di tengahnya) dan `منجاوهكن`
+ * (menjauhkan tanpa hamzah) lulus sepenuhnya. Gate kini menyemak
+ * kedua-dua tulisan.
+ */
+
+import { lookup } from './prpm.js'
+import { mungkinAkronim, mungkinNamaKhas } from './nama.js'
+import { cariDataset } from './dataset.js'
+import { normalisasiJawi } from './kamus.js'
+import { jarakHuruf, petaSongsang } from './tukar.js'
+import { pisahUlangJawi } from './pedoman.js'
+import { rangkaKonsonan } from './semak.js'
+
+const TOKEN_RUMI = /([A-Za-zÀ-ÿ][A-Za-zÀ-ÿ'-]*)/g
+const TOKEN_JAWI = /([؀-ۿݐ-ݿﭐ-﷿ﹰ-]+)/g
+
+// Baris tanda vokal Arab. Jawi Melayu tidak menggunakannya; petikan al-Quran
+// dan hadis dalam dokumen Melayu menggunakannya. Kehadirannya bermakna
+// potongan itu bahasa Arab, yang Pedoman §11.1 kata kekalkan seadanya.
+const HARAKAT = /[ً-ْٰٓ-ٕ]/
+
+/**
+ * Semak token Jawi terhadap peta songsang DBP.
+ *
+ * Yang paling penting di sini ialah pengesanan RUANG TERSASAR. Sebuah
+ * perkataan yang terbelah dua boleh gagal dengan LANTANG pada satu separuh
+ * dan BERJAYA SECARA PALSU pada separuh yang lain: `ݢولوڠن` (golongan)
+ * yang terbelah menjadi `ݢول` + `وڠن` meninggalkan `ݢول`, yang benar-benar
+ * memetakan kepada dua perkataan DBP tulen, gol dan gul. Penukar yang
+ * memilih calon paling kerap akan mengeluarkan "gol" dengan penuh yakin,
+ * dan separuh perkataan hilang tanpa sesiapa perasan.
+ *
+ * Sebab itu percantuman dicuba apabila SALAH SATU jiran tidak dapat
+ * diselesaikan. Menuntut kedua-duanya gagal akan terlepas kes ini justeru
+ * kerana separuh pertama "berjaya".
+ */
+export function gateJawi(teks, cache, opts = {}) {
+  const { dataset = null, abai = new Set(), namaJawi = new Set() } = opts
+  const peta = petaSongsang(cache, dataset)
+
+  // Indeks rangka konsonan, dibina sekali. Ejaan yang tersalah biasanya
+  // berbeza hanya pada vokal atau hamzah — منجاوهكن lawan منجاءوهکن — jadi
+  // rangkanya kekal sama dan ejaan DBP yang betul boleh dinamakan terus.
+  // Melaporkan "tiada dalam DBP" sahaja menyerahkan kerja mencari kepada
+  // pembaca; melaporkan ejaan sebenar menutup jurang itu.
+  const rangka = new Map()
+  for (const [kunci, slot] of peta) {
+    if (!slot.layak.length) continue
+    const r = rangkaKonsonan(kunci)
+    if (!r) continue
+    if (!rangka.has(r)) rangka.set(r, [])
+    rangka.get(r).push({ jawi: kunci, rumi: slot.layak[0] })
+  }
+  const cadang = (t) => {
+    const senarai = rangka.get(rangkaKonsonan(t)) ?? []
+    if (!senarai.length) return null
+    const terbaik = senarai
+      .map((c) => ({ ...c, jarak: jarakHuruf(normalisasiJawi(t), c.jawi) }))
+      .sort((a, b) => a.jarak - b.jarak)[0]
+    // Jarak besar bermakna ia perkataan lain sepenuhnya yang kebetulan
+    // berkongsi rangka, bukan salah eja. Cadangan begitu mengelirukan.
+    return terbaik.jarak <= 3 ? terbaik : null
+  }
+
+  const lulusDbp = []
+  const ralat = []
+  const tidakDapatDisahkan = []
+  const dilihat = new Set()
+
+  const bahagian = teks.split(TOKEN_JAWI)
+  const token = []
+  for (const [i, cebis] of bahagian.entries()) {
+    if (i % 2 === 1) token.push({ teks: cebis, i })
+  }
+
+  // Pemisah antara dua token mesti ruang tulen sebelum percantuman dicuba.
+  // Tanda baca, petikan atau baris baru antara mereka bermakna ia memang
+  // dua perkataan berasingan, bukan satu yang terbelah.
+  const ruangSahaja = (a, b) => /^[ \t ‌​]*$/.test(bahagian.slice(a + 1, b).join(''))
+
+  // §17.1: kata ulang penuh ialah kata dasar + angka dua Arab. `اوسها٢`
+  // ialah usaha-usaha, dan kata dasarnya yang ada dalam kamus, bukan bentuk
+  // berangka itu. Tanpa langkah ini setiap kata ulang dalam dokumen jadi
+  // ralat palsu.
+  const cari = (t) => {
+    const langsung = peta.get(normalisasiJawi(t))
+    if (langsung) return langsung
+    const dasar = pisahUlangJawi(t)
+    return dasar ? (peta.get(normalisasiJawi(dasar)) ?? null) : null
+  }
+  const selesai = (t) => {
+    const m = cari(t)
+    return m ? m.layak.length === 1 : false
+  }
+
+  for (const [n, tok] of token.entries()) {
+    const t = tok.teks
+    if (abai.has(t) || abai.has(normalisasiJawi(t))) continue
+
+    // Petikan Arab tidak selalu bertanda baris. Kata sandang `ال` ialah
+    // penanda paling boleh dipercayai yang tinggal: ia membuka hampir setiap
+    // frasa Arab yang dipetik (اليمين, المقربون, الشمال) dan pada dasarnya
+    // tidak pernah membuka kata Melayu Jawi. Nama khas Arab tanpa kata
+    // sandang (أصحاب) tetap perlu diisytihar melalui simpanan `nama`;
+    // kamus Melayu memang tidak boleh mengesahkannya, dan berpura-pura
+    // boleh adalah jaminan palsu.
+    if (HARAKAT.test(t) || (/^ال/.test(t) && !cari(t))) {
+      // Pedoman §11.1: petikan Arab kekalkan ejaan asal. Ia bukan lulus DBP
+      // kerana kamus Melayu tidak boleh mengesahkannya; ia keadaan ketiga.
+      if (!dilihat.has(t)) { dilihat.add(t); tidakDapatDisahkan.push({ kata: t, sebab: 'teks Arab, dikekalkan (Pedoman §11.1)' }) }
+      continue
+    }
+
+    const m = cari(t)
+
+    // Cuba cantum dengan jiran SEBELUM melaporkan apa-apa, kerana ruang
+    // tersasar mencemarkan kedua-dua separuh sekali gus.
+    const seterusnya = token[n + 1]
+    if (seterusnya && ruangSahaja(tok.i, seterusnya.i)) {
+      const belumSelesai = !selesai(t) || !selesai(seterusnya.teks)
+      if (belumSelesai) {
+        const gabung = cari(t + seterusnya.teks)
+        if (gabung?.layak.length) {
+          const kunci = t + ' ' + seterusnya.teks
+          if (!dilihat.has(kunci)) {
+            dilihat.add(kunci)
+            ralat.push({
+              kata: kunci,
+              sebab: 'ruang tersasar di dalam perkataan',
+              sepatutnya: t + seterusnya.teks,
+              bacaan: gabung.layak[0],
+            })
+          }
+          dilihat.add(t)
+          dilihat.add(seterusnya.teks)
+          continue
+        }
+      }
+    }
+
+    if (dilihat.has(t)) continue
+    dilihat.add(t)
+
+    if (!m) {
+      // Nama khas yang SUDAH diisytihar pengguna bukan ralat. Ia tetap bukan
+      // lulus DBP — kamus Melayu tidak mengesahkannya — jadi ia keadaan
+      // ketiga, dan pembaca nampak apa yang tidak disemak.
+      if (namaJawi.has(t) || namaJawi.has(normalisasiJawi(t))) {
+        tidakDapatDisahkan.push({ kata: t, sebab: 'nama khas diisytihar pengguna' })
+        continue
+      }
+      const c = cadang(t)
+      ralat.push({
+        kata: t,
+        sebab: 'ejaan Jawi tiada dalam DBP mahupun dataset',
+        ...(c ? { sepatutnya: c.jawi, bacaan: c.rumi } : {}),
+      })
+      continue
+    }
+    if (m.layak.length === 1) {
+      lulusDbp.push(t)
+      continue
+    }
+    if (m.layak.length > 1) {
+      // Homograf tulen. Ejaannya SAH; hanya bacaannya perlu konteks. Ini
+      // bukan ralat, dan menandakannya begitu akan menggagalkan setiap
+      // dokumen yang mengandungi سنة.
+      tidakDapatDisahkan.push({ kata: t, sebab: `homograf, ${m.layak.length} bacaan DBP`, calon: m.layak })
+      continue
+    }
+    if (m.entah.length) {
+      tidakDapatDisahkan.push({ kata: t, sebab: 'hanya dalam dataset, bukan DBP', calon: m.entah })
+      continue
+    }
+    ralat.push({ kata: t, sebab: 'hanya padan bentuk rujukan silang DBP', calon: m.tolak })
+  }
+
+  return { lulusDbp, ralat, tidakDapatDisahkan }
+}
+
+/**
+ * Semak teks Rumi. Setiap perkataan jatuh ke dalam SATU daripada tiga baldi.
+ */
+export async function gate(teks, cache, opts = {}) {
+  // Dataset boleh disuntik supaya ujian tidak bergantung pada fail yang
+  // diimport ke mesin tertentu. Ujian yang bergantung pada keadaan mesin
+  // lulus di sini dan gagal di CI, atau lebih teruk, sebaliknya.
+  const { luarTalian = true, abai = new Set(), cariDalamDataset = cariDataset } = opts
+
+  const lulusDbp = []
+  const ralat = []
+  const tidakDapatDisahkan = []
+  const dilihat = new Set()
+
+  const bahagian = teks.split(TOKEN_RUMI)
+  for (const [i, cebis] of bahagian.entries()) {
+    if (i % 2 === 0) continue
+    const kata = cebis.toLowerCase()
+    if (kata.length < 2 || dilihat.has(kata)) continue
+    dilihat.add(kata)
+
+    if (abai.has(kata)) continue
+
+    // Akronim dan nama khas tidak boleh disahkan oleh kamus. Ia BUKAN lulus;
+    // ia keadaan ketiga, supaya pengguna tahu apa yang tidak disemak.
+    if (mungkinAkronim(cebis) || mungkinNamaKhas(cebis, bahagian[i - 1])) {
+      tidakDapatDisahkan.push({ kata: cebis, sebab: 'nama khas atau akronim' })
+      continue
+    }
+
+    const rec = await lookup(kata, cache, { ...opts, luarTalian })
+
+    if (rec?.ralat) {
+      tidakDapatDisahkan.push({ kata, sebab: `gagal semak: ${rec.ralat}` })
+      continue
+    }
+
+    if (!rec?.dijumpai) {
+      // Dalam mod luar talian, "tiada dalam cache" berbeza daripada "tiada
+      // dalam PRPM". Yang pertama tidak dapat disahkan; yang kedua ralat.
+      if (luarTalian && /luar talian/.test(rec?.nota ?? '')) {
+        tidakDapatDisahkan.push({ kata, sebab: 'tiada dalam cache' })
+        continue
+      }
+
+      // PRPM menyatakan sendiri perkataan ini tiada dalam kamus TERKINI
+      // tetapi ada dalam tesaurus. Itu bukan ejaan salah; ia perkataan sah
+      // yang bahagian kamusnya tidak diliputi. Menandakannya ralat
+      // menghasilkan negatif palsu pada perkataan paling biasa.
+      if (rec?.adaTesaurus) {
+        tidakDapatDisahkan.push({
+          kata,
+          sebab: 'tiada dalam kamus terkini PRPM, tetapi ada dalam tesaurus',
+        })
+        continue
+      }
+
+      // PRPM tiada entri untuk kata tugas paling asas: dan, di, ke, yang,
+      // atau. Menandakannya sebagai ralat menjadikan gate mustahil dipakai.
+      // Pembezanya bersumber, bukan senarai putih dari ingatan: kata tugas
+      // itu SEMUA wujud dalam dataset, manakala hadith, fardhu, tayammum,
+      // dhuha, qadha, redha dan iddah TIADA satu pun.
+      const ds = await cariDalamDataset(kata)
+      if (ds?.jawi) {
+        tidakDapatDisahkan.push({
+          kata,
+          sebab: 'tiada entri PRPM, tetapi wujud dalam dataset',
+        })
+        continue
+      }
+
+      ralat.push({ kata, sebab: 'tiada entri dalam PRPM', url: rec?.url })
+      continue
+    }
+
+    // Entri rujukan silang bermakna DBP mengalihkan bentuk ini ke bentuk lain.
+    // sunnah -> ®sunah. Menggunakannya adalah ejaan yang salah.
+    const def = (rec.entri?.[0]?.definisi ?? '').trim()
+    const silang = /^®\s*(.+?)\.?$/.exec(def)
+    if (silang) {
+      ralat.push({
+        kata,
+        sebab: 'rujukan silang, DBP mengalihkan ke bentuk lain',
+        sepatutnya: silang[1].trim(),
+        url: rec.url,
+      })
+      continue
+    }
+
+    lulusDbp.push(kata)
+  }
+
+  // Jawi disemak dalam panggilan yang SAMA. Kalau ia perintah berasingan,
+  // ia jadi langkah yang boleh dilupakan, dan itu punca kegagalan asal.
+  const j = gateJawi(teks, cache, opts)
+  lulusDbp.push(...j.lulusDbp)
+  ralat.push(...j.ralat.map((r) => ({ ...r, tulisan: 'jawi' })))
+  tidakDapatDisahkan.push(...j.tidakDapatDisahkan.map((r) => ({ ...r, tulisan: 'jawi' })))
+
+  const jumlah = lulusDbp.length + ralat.length + tidakDapatDisahkan.length
+  const peratusTidakSah = jumlah ? Math.round((tidakDapatDisahkan.length / jumlah) * 100) : 0
+
+  return {
+    jumlahKataUnik: jumlah,
+    lulusDbp: lulusDbp.length,
+    ralat,
+    tidakDapatDisahkan,
+    peratusTidakDapatDisahkan: peratusTidakSah,
+  }
+}
+
+/**
+ * Tentukan kod keluar. Ralat sentiasa menggagalkan. `tidakDapatDisahkan`
+ * menggagalkan apabila melebihi ambang, kerana cache sejuk bermakna gate
+ * tidak menyemak apa-apa.
+ */
+export function kodKeluar(laporan, ambang = null) {
+  if (laporan.ralat.length) return 1
+  if (ambang != null && laporan.peratusTidakDapatDisahkan > ambang) return 1
+  return 0
+}

package/src/install.js

@@ -3,7 +3,7 @@
  * Mod salin (default) untuk pengguna npx, mod --link untuk pembangun.
  */
 
-import { cp, mkdir, rm, symlink } from 'node:fs/promises'
+import { cp, mkdir, readFile, rm, symlink, writeFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -26,3 +26,50 @@ export async function pasangSkill({ link = false } = {}) {
   }
   return { dipasang: SASARAN, mod: 'salin', sumber: AKAR }
 }
+
+/**
+ * Pasang hook PostToolUse Claude Code yang menjalankan gate ke atas fail
+ * yang baru ditulis atau disunting.
+ *
+ * Ini satu-satunya lapisan yang benar-benar memaksa. Peraturan dalam
+ * SKILL.md bergantung pada agen memilih untuk patuh, dan satu agen sudah
+ * membuktikan itu tidak mencukupi: 273 ejaan salah masuk produksi walaupun
+ * alat menangkapnya ada di tangan sepanjang masa.
+ *
+ * Hook gagal LEMBUT: ia melaporkan ralat kepada agen tanpa menyekat tulisan.
+ * Menyekat tulisan atas kamus yang tidak lengkap akan menghalang kerja yang
+ * sah; melaporkan sudah memadai kerana agen membaca output hook.
+ */
+export const HOOK = {
+  matcher: 'Write|Edit',
+  hooks: [
+    {
+      type: 'command',
+      command:
+        'f=$(echo "$CLAUDE_TOOL_INPUT" | grep -oE \'"file_path"[^,]*\' | cut -d\'"\' -f4); ' +
+        'case "$f" in *.md|*.txt|*.json) npx -y prpm-dbp gate "$f" --luar-talian 2>&1 | head -20 ;; esac; exit 0',
+    },
+  ],
+}
+
+export async function pasangHook({ fail = join(homedir(), '.claude', 'settings.json') } = {}) {
+  let tetapan = {}
+  try {
+    tetapan = JSON.parse(await readFile(fail, 'utf8'))
+  } catch {
+    tetapan = {}
+  }
+
+  tetapan.hooks ??= {}
+  tetapan.hooks.PostToolUse ??= []
+
+  const sedia = tetapan.hooks.PostToolUse.some((h) =>
+    JSON.stringify(h).includes('prpm-dbp gate'),
+  )
+  if (sedia) return { fail, status: 'sudah dipasang' }
+
+  tetapan.hooks.PostToolUse.push(HOOK)
+  await mkdir(dirname(fail), { recursive: true })
+  await writeFile(fail, JSON.stringify(tetapan, null, 2), 'utf8')
+  return { fail, status: 'dipasang', matcher: HOOK.matcher }
+}

package/src/prpm.js

@@ -34,6 +34,17 @@ const DEFINISI = /<b>Definisi\s*:\s*<\/b>([\s\S]*?)(?=<b>\(|$)/
 const SUMBER = /<b>\(([^)]+)\)<\/b>/
 const TIADA_TESAURUS = /Tiada maklumat tesaurus untuk kata/
 
+// PRPM mengisytiharkan keadaan ketiga dengan ayatnya sendiri. Perkataan
+// seperti orang, itu dan sumber memulangkan halaman 35-42KB tanpa satu pun
+// div.tab-pane, tetapi ia BUKAN "tiada entri": PRPM menyatakan perkataan itu
+// tiada dalam kamus TERKINI, dan memaparkan Tesaurus sebagai gantinya.
+//
+// Menyamakan dua keadaan ini menghasilkan negatif palsu pada perkataan yang
+// paling biasa, dan negatif palsu di situ merosakkan kepercayaan kepada
+// seluruh laporan.
+const BUKAN_KAMUS_TERKINI = /Carian kata tiada di dalam kamus terkini/
+const ADA_TESAURUS = /Bersinonim dengan/
+
 // Panel "Juga ditemukan dalam" menyenaraikan bilangan rujukan perkataan itu
 // dalam setiap korpus DBP. Jumlahnya ialah isyarat kekerapan yang BERSUMBER,
 // bukan tekaan: mengikut 2439 rujukan berbanding mengekot 6.
@@ -89,11 +100,16 @@ export function parse(kata, page) {
     jawiVarian: unik.slice(1),
     entri,
     url: `${BASE_URL}?keyword=${encodeURIComponent(kata)}`,
+    // Tiga keadaan berbeza, bukan dua.
+    dalamKamusTerkini: entri.length > 0 ? true : !BUKAN_KAMUS_TERKINI.test(page),
+    adaTesaurus: ADA_TESAURUS.test(page),
     nota: entri.length
       ? null
-      : TIADA_TESAURUS.test(page)
-        ? 'tiada entri dalam PRPM'
-        : 'halaman tidak dikenali, semak manual',
+      : BUKAN_KAMUS_TERKINI.test(page)
+        ? 'tiada dalam kamus terkini PRPM; ada dalam tesaurus'
+        : TIADA_TESAURUS.test(page)
+          ? 'tiada entri dalam PRPM'
+          : 'halaman tidak dikenali, semak manual',
   }
 }
 

package/src/tukar.js

@@ -162,6 +162,36 @@ export async function cariDasar(kata, cache, opts = {}) {
  * bilangan perkataan terpanjang supaya pembacaan songsang boleh memadan
  * jujukan, bukan token tunggal sahaja.
  */
+/**
+ * Jarak suntingan antara dua ejaan.
+ *
+ * MESTI menghormati susunan huruf. Ukuran berasaskan set huruf gagal dengan
+ * teruk: سروه (seruh) ialah anagram sempurna bagi سوره, jadi jaraknya sifar
+ * dan ia mengalahkan سورة (surah) yang sebenarnya betul. Susunan huruf itulah
+ * maklumat yang membezakannya.
+ */
+export function jarakHuruf(a, b) {
+  const m = a.length
+  const n = b.length
+  if (!m) return n
+  if (!n) return m
+  let baris = Array.from({ length: n + 1 }, (_, i) => i)
+  for (let i = 1; i <= m; i++) {
+    let sebelum = baris[0]
+    baris[0] = i
+    for (let j = 1; j <= n; j++) {
+      const simpan = baris[j]
+      baris[j] = Math.min(
+        baris[j] + 1,
+        baris[j - 1] + 1,
+        sebelum + (a[i - 1] === b[j - 1] ? 0 : 1),
+      )
+      sebelum = simpan
+    }
+  }
+  return baris[n]
+}
+
 /**
  * Indeks rangka konsonan, untuk memadan ejaan bukan piawai.
  *
@@ -455,7 +485,13 @@ export async function keJawi(teks, cache, opts = {}) {
 export function keRumi(
   teksJawi,
   cache,
-  { penanda = ['«', '»'], dataset = null, pilihLazim = false, padanRangka = false } = {},
+  {
+    penanda = ['«', '»'],
+    dataset = null,
+    pilihLazim = false,
+    padanRangka = false,
+    glosari = null,
+  } = {},
 ) {
   const peta = petaSongsang(cache, dataset)
   const tidakDikenali = []
@@ -463,6 +499,7 @@ export function keRumi(
   const arab = []
   const sendiDipisah = []
   const bukanPiawai = []
+  const dariGlosari = []
   const rangka = padanRangka ? petaRangka(cache, dataset) : null
   const bahagian = teksJawi.split(PECAH_JAWI)
   const keluar = []
@@ -470,6 +507,20 @@ export function keRumi(
   for (let i = 0; i < bahagian.length; i++) {
     if (i % 2 === 0) { keluar.push(bahagian[i]); continue }
 
+    // Glosari domain yang dibekalkan pemanggil MENGATASI segalanya.
+    // Kekerapan global gagal tepat di tempat paling penting: dalam teks
+    // domain, setiap istilah khusus kalah kepada kata lazim yang berkongsi
+    // rangka. اسم menjadi asam, فعل menjadi faal, رسم menjadi rasam.
+    // Hanya pengetahuan domain boleh membetulkannya, dan pemanggil ada.
+    if (glosari) {
+      const paksa = glosari[bahagian[i]] ?? glosari[normalisasiJawi(bahagian[i])]
+      if (paksa) {
+        dariGlosari.push({ jawi: bahagian[i], rumi: paksa })
+        keluar.push(paksa)
+        continue
+      }
+    }
+
     // Teks Arab bertanda baris dibiarkan seadanya. Cuba menukarnya akan
     // merosakkan petikan al-Quran dan hadis dalam dokumen Melayu.
     if (HARAKAT.test(bahagian[i])) {
@@ -525,12 +576,33 @@ export function keRumi(
       if (rangka) {
         const padananRangka = rangka.get(rangkaKonsonan(bahagian[i]))
         if (padananRangka?.size) {
-          const senarai = [...padananRangka.entries()].map(([rumi, jawiDbp]) => ({ rumi, jawiDbp }))
-          bukanPiawai.push({ jawi: bahagian[i], calon: senarai })
+          // Rangka pendek berlanggar teruk: رواية memberi 20+ calon. Isih
+          // ikut kedekatan huruf sebenar dahulu, kemudian kekerapan korpus,
+          // dan hadkan senarai supaya teks kekal boleh dibaca.
+          const asal = bahagian[i]
+          const senarai = [...padananRangka.entries()]
+            .map(([rumi, jawiDbp]) => ({
+              rumi,
+              jawiDbp,
+              jarak: jarakHuruf(asal, jawiDbp),
+              kerap: cache[rumi]?.rujukanKorpus ?? 0,
+            }))
+            .sort((a, b) => a.jarak - b.jarak || b.kerap - a.kerap)
+            .slice(0, 6)
+
+          bukanPiawai.push({ jawi: asal, calon: senarai })
+
           if (senarai.length === 1) {
             keluar.push(senarai[0].rumi)
             continue
           }
+          // --pilih mesti meleraikan ini juga, jika tidak seluruh senarai
+          // calon dibuang ke dalam teks dan ayat menjadi tidak boleh dibaca.
+          if (pilihLazim) {
+            bukanPiawai[bukanPiawai.length - 1].dipilih = senarai[0].rumi
+            keluar.push(senarai[0].rumi)
+            continue
+          }
           keluar.push(penanda[0] + senarai.map((x) => x.rumi).join('|') + penanda[1])
           continue
         }
@@ -567,6 +639,7 @@ export function keRumi(
     arab: [...new Set(arab)],
     sendiDipisah,
     ejaanBukanPiawai: bukanPiawai,
+    dariGlosari,
     saizPeta: peta.size,
     lengkap: tidakDikenali.length === 0,
   }